Aller au contenu

waka-ui et Wakastart

Ce que waka-ui prend en charge, ce qui reste à votre application, et comment l'habillage et les langues de Wakastart arrivent aux composants.

ConceptDéveloppeur
Voir en Markdown

waka-ui est une bibliothèque d'interface, pas un client de la plateforme. Elle dessine, applique un thème et traduit ; elle n'appelle jamais l'API de Wakastart, ne connaît ni le jeton de l'utilisateur ni son organisation. Votre application fait le lien entre les deux.

Qui fait quoi

BesoinFourni parOù le lire
Connecter l'utilisateur, obtenir son jetonvotre application, avec Discovery et KeycloakAuthentification
Connaître son réseau, son client, ses droitsvotre application, avec le jeton enrichi ou GET /api/meCharger le contexte utilisateur
Récupérer le thème et les visuels de son organisationvotre application, avec GET /api/meAfficher l'habillage
Récupérer les textes traduits de l'applicationvotre serveur, avec l'API publiqueCharger les traductions
Appliquer un thème, basculer en mode sombrewaka-uiAppliquer le thème
Traduire l'interface, changer de languewaka-uiTraduire l'interface
Dessiner les écranswaka-uiComposants et blocks

Comment l'habillage et la langue arrivent aux composants

Chargement du schéma…
  1. Votre application lit les données sur Wakastart, avec le jeton de l'utilisateur ou une clé API côté serveur.
  2. Elle remet les traductions à WakaProvider dans sa configuration, et lui indique la langue de l'utilisateur.
  3. Elle transforme les variables du thème de l'utilisateur en feuille de style, puis active ce thème.
  4. Tous les composants placés sous WakaProvider suivent.

Le fournisseur WakaProvider

WakaProvider réunit trois mécanismes, que vous pilotez par une seule configuration :

  • une instance i18next, qui contient vos traductions et le catalogue des textes de waka-ui ;
  • un gestionnaire de langue, qui mémorise la langue choisie dans le navigateur ;
  • un gestionnaire de thème, qui pose l'attribut data-theme et la classe dark sur l'élément <html> et mémorise ces choix dans le navigateur.

Vos composants y accèdent par les hooks useWaka, useTheme, useLanguage et useTranslation, tous exportés par @wakastellar/ui.

Un rendu dans le navigateur

WakaProvider initialise ses traductions dans le navigateur. Tant que cette initialisation n'est pas terminée, il affiche le texte « Loading WakaUI... » à la place de ses enfants. Conséquence : le contenu placé sous WakaProvider n'apparaît pas dans le HTML rendu par le serveur.

Pour un écran d'application derrière une connexion, ce délai est négligeable. Pour une page publique que les moteurs de recherche doivent indexer, placez WakaProvider dans le layout de la zone connectée plutôt qu'à la racine. Les composants simples, comme Button ou Card, fonctionnent sans fournisseur ; les hooks de thème et de langue l'exigent.

Les variables de couleur

Tous les composants lisent leurs couleurs dans des variables CSS au format de shadcn/ui : --background, --foreground, --primary, --primary-foreground, --border, --radius, etc.

waka-ui attend chaque couleur sous la forme de trois composantes HSL, sans fonction : --primary: 221.2 83.2% 53.3%. Il compose lui-même hsl(var(--primary)). C'est aussi le format des thèmes CSS de Wakastart que la console propose en exemple : un thème écrit dans ce format s'applique tel quel à waka-ui.

Pour aller plus loin