Skip to content

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.

ReferenceDeveloper

This page has not been translated yet and is shown in French.

Cette page rassemble les valeurs de référence de waka-ui. Le détail de chaque composant se consulte sur ui.wakastart.app.

Paquet

ÉlémentValeur
Nom@wakastellar/ui
Registreregistre npm public, sans authentification
Dernière version au 2 novembre 20266.1.4
Versions publiéesnpmjs.com/package/@wakastellar/ui
FormatsES 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épendanceVersion acceptéeObligatoire
next14 ou plus (testé sur 16)oui
react, react-dom18 ou plus (testé sur 19)oui
tailwindcss3.4 ou plus, ou 4oui
recharts2.xoui pour le point d'entrée principal et /charts
react-hook-form7.xoui pour le point d'entrée principal
Node.js22 ou plus—

Les dépendances des éditeurs et de l'export sont listées dans Composants et blocks.

Points d'entrée

ImportContenu
@wakastellar/uicomposants, 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-translationun hook seul
@wakastellar/ui/chartsgraphiques
@wakastellar/ui/rich-textéditeur de texte riche
@wakastellar/ui/exportexport et import des tableaux
@wakastellar/ui/docrendu de documentation
@wakastellar/ui/editoréditeur de blocs (Plate)
@wakastellar/ui/md-editoréditeur Markdown

Feuilles de style

ImportUsage
@wakastellar/ui/stylesTailwind CSS 4 : Tailwind, variables et thèmes intégrés
@wakastellar/ui/styles/v4identique à styles
@wakastellar/ui/styles/v3Tailwind CSS 3.4
@wakastellar/ui/styles/basevariables et thèmes seuls, sans Tailwind
@wakastellar/ui/tailwind-presetpreset 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 par les deux réglages suivants.

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

    JavaScript
    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

ChampTypeDéfautDescription
defaultLanguagechaîneobligatoirelangue au premier affichage, et langue de repli d'une clé absente
supportedLanguagestableau de chaînesobligatoirecodes des langues acceptées, par exemple ["fr", "en"]
languagestableau de { code, label, flagEmoji?, flag? }[]langues affichées par LanguageSelector et renvoyées par useWaka().languages
resourcesobjet—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
storageKeychaînewaka-ui-languageclé de mémorisation de la langue dans le navigateur

theme

ChampTypeDéfautDescription
defaultThemechaînedefaultidentifiant du thème au premier affichage
themestableau 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é
enableSystembooléenfalseactive 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

ChampTypeDescription
debugbooléenjournalise 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.

HookRenvoie
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%.

VariableRôle
--background, --foregroundfond et texte de la page
--card, --card-foregroundcartes
--popover, --popover-foregroundmenus, listes déroulantes, info-bulles
--primary, --primary-foregroundaction principale, liens
--secondary, --secondary-foregroundactions secondaires, surfaces atténuées
--muted, --muted-foregroundsurfaces neutres, textes d'aide
--accent, --accent-foregroundsurvol, sélection
--destructive, --destructive-foregrounderreurs, suppressions
--success, --warning, --info et leurs -foregroundétats
--border, --input, --ringbordures, champs, anneau de focus
--chart-1 à --chart-5séries des graphiques
--radiusarrondi 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-themeidentifiant du dernier thème appliqué
waka-dark-modedark ou light
waka-ui-language (ou la valeur de language.storageKey) et languagecode 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.

CommandeEffet
npx wakastellar-ui initcré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 cardcopie les composants et ceux dont ils dépendent ; --overwrite remplace les fichiers existants ; affiche les paquets npm à installer
npx wakastellar-ui listliste les composants ; --category <nom> filtre par catégorie
npx wakastellar-ui search datecherche un composant dans les noms, descriptions et catégories

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