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.
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
| Besoin | Fourni par | Où le lire |
|---|---|---|
| Connecter l'utilisateur, obtenir son jeton | votre application, avec Discovery et Keycloak | Authentification |
| Connaître son réseau, son client, ses droits | votre application, avec le jeton enrichi ou GET /api/me | Charger le contexte utilisateur |
| Récupérer le thème et les visuels de son organisation | votre application, avec GET /api/me | Afficher l'habillage |
| Récupérer les textes traduits de l'application | votre serveur, avec l'API publique | Charger les traductions |
| Appliquer un thème, basculer en mode sombre | waka-ui | Appliquer le thème |
| Traduire l'interface, changer de langue | waka-ui | Traduire l'interface |
| Dessiner les écrans | waka-ui | Composants et blocks |
Comment l'habillage et la langue arrivent aux composants
- Votre application lit les données sur Wakastart, avec le jeton de l'utilisateur ou une clé API côté serveur.
- Elle remet les traductions à
WakaProviderdans sa configuration, et lui indique la langue de l'utilisateur. - Elle transforme les variables du thème de l'utilisateur en feuille de style, puis active ce thème.
- Tous les composants placés sous
WakaProvidersuivent.
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-themeet la classedarksur 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.