# Référence de waka-ui

> Paquet, versions, prérequis, points d'entrée, configuration de WakaProvider, hooks, variables de couleur et ligne de commande de waka-ui.

Cette page rassemble les valeurs de référence de waka-ui. Le détail de chaque composant se consulte sur [ui.wakastart.app](https://ui.wakastart.app).

## Paquet

| Élément | Valeur |
|---|---|
| Nom | `@wakastellar/ui` |
| Registre | registre npm public, sans authentification |
| Dernière version au 2 novembre 2026 | 6.1.4 |
| Versions publiées | [npmjs.com/package/@wakastellar/ui](https://www.npmjs.com/package/@wakastellar/ui) |
| Formats | ES modules et CommonJS, types TypeScript inclus |

Les numéros de version suivent le versionnage sémantique : une version majeure signale un changement incompatible, par exemple une dépendance dont la plage acceptée se resserre. Épinglez une version exacte dans votre `package.json` et montez de version volontairement, après avoir vérifié vos écrans.

## Prérequis

| Dépendance | Version acceptée | Obligatoire |
|---|---|---|
| `next` | 14 ou plus (testé sur 16) | oui |
| `react`, `react-dom` | 18 ou plus (testé sur 19) | oui |
| `tailwindcss` | 3.4 ou plus, ou 4 | oui |
| `recharts` | 2.x | oui pour le point d'entrée principal et `/charts` |
| `react-hook-form` | 7.x | oui pour le point d'entrée principal |
| Node.js | 22 ou plus | — |

Les dépendances des éditeurs et de l'export sont listées dans [Composants et blocks](/v1.0/interface-waka-ui/composants-et-blocks#points-dentrée-dédiés).

## Points d'entrée

| Import | Contenu |
|---|---|
| `@wakastellar/ui` | composants, blocks, fournisseurs, hooks, types |
| `@wakastellar/ui/components/<dossier>` | un composant seul, par exemple `components/button` |
| `@wakastellar/ui/blocks/<dossier>` | un block seul, par exemple `blocks/error-pages` |
| `@wakastellar/ui/hooks/use-toast`, `@wakastellar/ui/hooks/use-translation` | un hook seul |
| `@wakastellar/ui/charts` | graphiques |
| `@wakastellar/ui/rich-text` | éditeur de texte riche |
| `@wakastellar/ui/export` | export et import des tableaux |
| `@wakastellar/ui/doc` | rendu de documentation |
| `@wakastellar/ui/editor` | éditeur de blocs (Plate) |
| `@wakastellar/ui/md-editor` | éditeur Markdown |

### Feuilles de style

| Import | Usage |
|---|---|
| `@wakastellar/ui/styles` | Tailwind CSS 4 : Tailwind, variables et thèmes intégrés |
| `@wakastellar/ui/styles/v4` | identique à `styles` |
| `@wakastellar/ui/styles/v3` | Tailwind CSS 3.4 |
| `@wakastellar/ui/styles/base` | variables et thèmes seuls, sans Tailwind |
| `@wakastellar/ui/tailwind-preset` | preset de configuration pour Tailwind CSS 3.4 |

### Tailwind CSS 3

Pour un projet en Tailwind CSS 3.4, remplacez l'étape « Importer les styles » de l'[installation](/v1.0/interface-waka-ui/installer-waka-ui) par les deux réglages suivants.

1. Dans `tailwind.config.js`, ajoutez le preset et les composants compilés de waka-ui :

   ```js
   module.exports = {
     presets: [require("@wakastellar/ui/tailwind-preset")],
     content: [
       "./app/**/*.{js,ts,jsx,tsx}",
       "./components/**/*.{js,ts,jsx,tsx}",
       "./node_modules/@wakastellar/ui/dist/**/*.js",
     ],
   };
   ```

   Le preset déclare les couleurs du thème et le mode sombre par classe.

2. Dans `app/layout.tsx`, importez la feuille de style :

   ```tsx
   import "@wakastellar/ui/styles/v3";
   ```

## Configuration de WakaProvider

`WakaProvider` reçoit une propriété `config` de type `WakaProviderConfig`. Gardez-la stable d'un rendu à l'autre : une nouvelle configuration réinitialise les traductions.

### `language`

| Champ | Type | Défaut | Description |
|---|---|---|---|
| `defaultLanguage` | chaîne | obligatoire | langue au premier affichage, et langue de repli d'une clé absente |
| `supportedLanguages` | tableau de chaînes | obligatoire | codes des langues acceptées, par exemple `["fr", "en"]` |
| `languages` | tableau de `{ code, label, flagEmoji?, flag? }` | `[]` | langues affichées par `LanguageSelector` et renvoyées par `useWaka().languages` |
| `resources` | objet | — | traductions de l'application, sous la forme `{ fr: { translation: { … } } }` |
| `s3Config` | `{ bucketUrl, translationsPath? }` | — | chargement des traductions par URL : `<bucketUrl>/<translationsPath>/<langue>.json`, sans en-tête d'authentification. `translationsPath` vaut `translations` par défaut |
| `storageKey` | chaîne | `waka-ui-language` | clé de mémorisation de la langue dans le navigateur |

### `theme`

| Champ | Type | Défaut | Description |
|---|---|---|---|
| `defaultTheme` | chaîne | `default` | identifiant du thème au premier affichage |
| `themes` | tableau de `{ id, label, description?, previewColor? }` | `[{ id: "default", label: "Default" }]` | thèmes proposés par `ThemeSelector` ; un thème mémorisé qui n'y figure pas est ignoré |
| `enableSystem` | booléen | `false` | active le mode sombre : mode du système à la première visite, puis choix mémorisé |
| `s3Config` | `{ baseUrl, prefix?, extension?, headers?, timeout? }` | — | chargement des thèmes par URL : `<baseUrl>/<prefix>/<id>.<extension>`. `extension` vaut `css` (feuille de style) ou `json` (variables) ; `timeout` vaut 10 000 ms |

### Autres champs

| Champ | Type | Description |
|---|---|---|
| `debug` | booléen | journalise l'initialisation et les changements de langue dans la console du navigateur |

## Hooks

Tous les hooks s'utilisent dans un composant client placé sous `WakaProvider`, sauf `useToast` qui demande seulement un `<Toaster />` rendu dans la page.

| Hook | Renvoie |
|---|---|
| `useWaka()` | `currentLanguage`, `changeLanguage(code)`, `languages`, `isLanguageLoading`, `currentTheme`, `changeTheme(id)`, `themes`, `isThemeLoading`, `preloadTheme(id)`, `isThemeLoaded(id)`, `t` |
| `useTheme()` | `currentTheme`, `themes`, `changeTheme(id)`, `isLoading`, `isDarkMode`, `toggleDarkMode()`, `preloadTheme(id)`, `isThemeLoaded(id)` |
| `useLanguage()` | `currentLanguage`, `languages`, `changeLanguage(code)`, `isLoading` |
| `useTranslation()` | `t`, `i18n` (i18next) |
| `useToast()` | `toast({ title, description, variant })`, `dismiss(id?)`, `toasts` |

`toast` affiche une notification à la fois ; `variant` vaut `default` ou `destructive`.

## Variables de couleur

Chaque couleur s'écrit en trois composantes HSL sans fonction, par exemple `--primary: 221.2 83.2% 53.3%`.

| Variable | Rôle |
|---|---|
| `--background`, `--foreground` | fond et texte de la page |
| `--card`, `--card-foreground` | cartes |
| `--popover`, `--popover-foreground` | menus, listes déroulantes, info-bulles |
| `--primary`, `--primary-foreground` | action principale, liens |
| `--secondary`, `--secondary-foreground` | actions secondaires, surfaces atténuées |
| `--muted`, `--muted-foreground` | surfaces neutres, textes d'aide |
| `--accent`, `--accent-foreground` | survol, sélection |
| `--destructive`, `--destructive-foreground` | erreurs, suppressions |
| `--success`, `--warning`, `--info` et leurs `-foreground` | états |
| `--border`, `--input`, `--ring` | bordures, champs, anneau de focus |
| `--chart-1` à `--chart-5` | séries des graphiques |
| `--radius` | arrondi de base, par exemple `0.5rem` |

Les thèmes intégrés sont `default`, `forest`, `twilight`, `sunset`, `monochrome` et `perpetuity`. Un thème se définit sur `[data-theme="<id>"]` pour le mode clair et `[data-theme="<id>"].dark` pour le mode sombre.

## Mémorisation dans le navigateur

waka-ui conserve les choix de l'utilisateur dans le `localStorage` :

| Clé | Contenu |
|---|---|
| `waka-theme` | identifiant du dernier thème appliqué |
| `waka-dark-mode` | `dark` ou `light` |
| `waka-ui-language` (ou la valeur de `language.storageKey`) et `language` | code de la dernière langue choisie |

Effacez ces clés pour revenir aux valeurs de la configuration.

## Ligne de commande

Le paquet installe la commande `wakastellar-ui`. Elle copie le code source d'un composant dans votre projet, pour le modifier librement ; vous en assurez ensuite vous-même la maintenance. Pour utiliser les composants tels que publiés, l'import depuis le paquet suffit.

| Commande | Effet |
|---|---|
| `npx wakastellar-ui init` | crée `components.json` et les dossiers `components/ui`, `components/waka`, `components/blocks`, `lib`, `hooks`. `--yes` garde les choix par défaut |
| `npx wakastellar-ui add button card` | copie les composants et ceux dont ils dépendent ; `--overwrite` remplace les fichiers existants ; affiche les paquets npm à installer |
| `npx wakastellar-ui list` | liste les composants ; `--category <nom>` filtre par catégorie |
| `npx wakastellar-ui search date` | cherche un composant dans les noms, descriptions et catégories |

Lancez ces commandes dans un projet où `@wakastellar/ui` est déjà installé.
