@wakastellar/ui 0.1.8 → 0.1.10

package/dist/context/language-context.d.ts

@@ -1,57 +1,195 @@
+import { WakaError } from '../utils/error-handling';
+/**
+ * @fileoverview Contexte de gestion des langues pour WakaStart UI
+ *
+ * Ce module fournit un système complet de gestion de l'internationalisation:
+ * - Chargement dynamique des traductions depuis S3 ou localement
+ * - Cache des traductions déjà chargées
+ * - Intégration transparente avec i18next
+ * - Persistance de la langue dans localStorage
+ *
+ * @module context/language-context
+ *
+ * @example
+ * ```tsx
+ * // Configuration avec S3
+ * <LanguageProvider
+ *   languages={[
+ *     { code: "fr", label: "Français", flagEmoji: "🇫🇷" },
+ *     { code: "en", label: "English", flagEmoji: "🇬🇧" }
+ *   ]}
+ *   defaultLanguage="fr"
+ *   s3Config={{ baseUrl: "https://cdn.example.com/translations" }}
+ * >
+ *   <App />
+ * </LanguageProvider>
+ * ```
+ */
 import * as React from "react";
+/**
+ * Configuration pour le chargement des traductions depuis S3
+ */
 export interface S3Config {
-    /** URL de base du bucket S3 */
+    /** URL de base du bucket S3 (ex: "https://bucket.s3.region.amazonaws.com") */
     baseUrl: string;
-    /** Préfixe des fichiers (ex: "translations/") */
+    /** Préfixe des fichiers de traduction (ex: "translations/") */
     prefix?: string;
     /** Extension des fichiers (défaut: "json") */
     extension?: string;
-    /** Headers personnalisés pour les requêtes */
+    /** Headers HTTP personnalisés pour les requêtes */
     headers?: Record<string, string>;
 }
+/**
+ * Type pour les traductions JSON inline
+ * Structure clé-valeur avec support des namespaces imbriqués
+ */
+export type TranslationsJSON = Record<string, string | Record<string, unknown>>;
+/**
+ * Configuration d'une langue disponible
+ *
+ * @example
+ * ```ts
+ * // Avec traductions inline (recommandé pour éviter les dépendances externes)
+ * const french: LanguageConfig = {
+ *   code: "fr",
+ *   label: "Français",
+ *   flagEmoji: "🇫🇷",
+ *   translations: {
+ *     common: {
+ *       save: "Enregistrer",
+ *       cancel: "Annuler"
+ *     }
+ *   }
+ * }
+ *
+ * // Sans traductions inline (utilise S3)
+ * const english: LanguageConfig = {
+ *   code: "en",
+ *   label: "English",
+ *   flagEmoji: "🇬🇧"
+ * }
+ * ```
+ */
 export interface LanguageConfig {
+    /** Code ISO de la langue (ex: "fr", "en", "es") */
     code: string;
+    /** Libellé d'affichage */
     label: string;
+    /** Emoji du drapeau (optionnel) */
     flagEmoji?: string;
+    /** URL de l'image du drapeau (optionnel) */
     flag?: string;
+    /**
+     * Traductions inline au format JSON
+     * Si fourni, les traductions sont utilisées directement sans charger depuis S3
+     */
+    translations?: TranslationsJSON;
 }
+/**
+ * Valeur exposée par le contexte de langue
+ */
 export interface LanguageContextValue {
-    /** Langue courante */
+    /** Code de la langue actuellement active */
     currentLanguage: string;
-    /** Liste des langues disponibles */
+    /** Liste des langues disponibles configurées */
     languages: LanguageConfig[];
-    /** Changer de langue */
+    /** Change la langue active et charge les traductions si nécessaire */
     changeLanguage: (code: string) => Promise<void>;
-    /** État de chargement */
+    /** Indique si un chargement de traductions est en cours */
     isLoading: boolean;
-    /** Traductions chargées */
+    /** Set des codes de langues dont les traductions sont chargées */
     loadedLanguages: Set<string>;
 }
+/**
+ * Props du provider de langue
+ */
 export interface LanguageProviderProps {
+    /** Composants enfants */
     children: React.ReactNode;
-    /** Langues disponibles */
+    /** Liste des langues disponibles dans l'application */
     languages: LanguageConfig[];
-    /** Langue par défaut */
+    /** Code de la langue par défaut (défaut: "fr") */
     defaultLanguage?: string;
-    /** Configuration S3 (optionnel - si non fourni, utilise les traductions locales) */
+    /** Configuration S3 pour le chargement distant des traductions */
     s3Config?: S3Config;
-    /** Callback après changement de langue */
+    /** Callback appelé après chaque changement de langue réussi */
     onLanguageChange?: (code: string) => void;
+    /** Callback en cas d'erreur (chargement traductions, parsing, etc.) */
+    onError?: (error: WakaError) => void;
 }
 /**
- * LanguageProvider
+ * Provider pour la gestion de l'internationalisation
  *
- * Provider pour gérer les langues et charger les traductions depuis S3.
+ * Gère automatiquement:
+ * - Le chargement des traductions depuis inline JSON ou S3
+ * - Le cache des traductions déjà chargées
+ * - La persistance de la langue dans localStorage
+ * - L'intégration avec i18next
  *
- * Features:
- * - Chargement dynamique des traductions depuis S3
- * - Cache des traductions déjà chargées
- * - Intégration avec i18next
- * - Persistance dans localStorage
- * - Support des traductions locales si pas de S3
+ * @example
+ * ```tsx
+ * // Configuration avec traductions inline (sans dépendance externe)
+ * <LanguageProvider
+ *   languages={[
+ *     {
+ *       code: "fr",
+ *       label: "Français",
+ *       translations: {
+ *         common: { save: "Enregistrer", cancel: "Annuler" }
+ *       }
+ *     },
+ *     {
+ *       code: "en",
+ *       label: "English",
+ *       translations: {
+ *         common: { save: "Save", cancel: "Cancel" }
+ *       }
+ *     }
+ *   ]}
+ * >
+ *   <App />
+ * </LanguageProvider>
+ *
+ * // Avec S3 pour chargement distant
+ * <LanguageProvider
+ *   languages={languages}
+ *   s3Config={{ baseUrl: "https://cdn.example.com/i18n" }}
+ *   onLanguageChange={(lang) => analytics.track("language_changed", { lang })}
+ * >
+ *   <App />
+ * </LanguageProvider>
+ * ```
  */
-export declare function LanguageProvider({ children, languages, defaultLanguage, s3Config, onLanguageChange, }: LanguageProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function LanguageProvider({ children, languages, defaultLanguage, s3Config, onLanguageChange, onError, }: LanguageProviderProps): import("react/jsx-runtime").JSX.Element;
 /**
- * Hook pour utiliser le contexte de langue
+ * Hook pour accéder au contexte de langue
+ *
+ * Fournit la langue courante, les langues disponibles et la fonction
+ * de changement de langue.
+ *
+ * @throws {Error} Si utilisé en dehors d'un LanguageProvider
+ *
+ * @returns Valeur du contexte de langue
+ *
+ * @example
+ * ```tsx
+ * function LanguageSwitcher() {
+ *   const { currentLanguage, languages, changeLanguage, isLoading } = useLanguage()
+ *
+ *   return (
+ *     <select
+ *       value={currentLanguage}
+ *       onChange={(e) => changeLanguage(e.target.value)}
+ *       disabled={isLoading}
+ *     >
+ *       {languages.map((lang) => (
+ *         <option key={lang.code} value={lang.code}>
+ *           {lang.flagEmoji} {lang.label}
+ *         </option>
+ *       ))}
+ *     </select>
+ *   )
+ * }
+ * ```
  */
 export declare function useLanguage(): LanguageContextValue;

package/dist/context/theme-provider.d.ts

@@ -1,3 +1,4 @@
+import { WakaError } from '../utils/error-handling';
 import * as React from "react";
 export interface ThemeS3Config {
     /** URL de base du bucket S3 */
@@ -11,6 +12,22 @@ export interface ThemeS3Config {
     /** Timeout en millisecondes */
     timeout?: number;
 }
+/**
+ * Variables CSS pour un thème
+ * Peut contenir des variables CSS standard ou des objets de couleur
+ */
+export type ThemeCSSVariables = Record<string, string | number | {
+    r?: number;
+    g?: number;
+    b?: number;
+    a?: number;
+    h?: number;
+    s?: number;
+    l?: number;
+}>;
+/**
+ * Configuration d'un thème avec variables CSS inline
+ */
 export interface ThemeConfig {
     /** Identifiant du thème (utilisé dans data-theme) */
     id: string;
@@ -20,6 +37,25 @@ export interface ThemeConfig {
     description?: string;
     /** Couleur représentative du thème (pour preview) */
     previewColor?: string;
+    /**
+     * Variables CSS du thème au format JSON
+     * Permet de définir le thème directement sans charger depuis S3
+     *
+     * @example
+     * ```ts
+     * cssVars: {
+     *   "--background": "0 0% 100%",
+     *   "--foreground": "222.2 84% 4.9%",
+     *   "--primary": "222.2 47.4% 11.2%"
+     * }
+     * ```
+     */
+    cssVars?: ThemeCSSVariables;
+    /**
+     * Variables CSS pour le mode sombre
+     * Utilisées quand .dark est appliqué
+     */
+    darkCssVars?: ThemeCSSVariables;
 }
 export interface ThemeContextValue {
     /** Thème courant */
@@ -51,6 +87,8 @@ export interface ThemeProviderProps {
     s3Config?: ThemeS3Config;
     /** Callback après changement de thème */
     onThemeChange?: (id: string) => void;
+    /** Callback en cas d'erreur (chargement thème, parsing, etc.) */
+    onError?: (error: WakaError) => void;
     /** Activer le mode sombre (optionnel) */
     enableDarkMode?: boolean;
 }
@@ -67,7 +105,7 @@ export interface ThemeProviderProps {
  * - Préchargement de thèmes
  * - Support des thèmes locaux si pas de S3
  */
-export declare function ThemeProvider({ children, themes, defaultTheme, s3Config, onThemeChange, enableDarkMode, }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ThemeProvider({ children, themes, defaultTheme, s3Config, onThemeChange, onError, enableDarkMode, }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Hook pour utiliser le ThemeProvider
  */

package/dist/context/waka-provider.d.ts

@@ -2,23 +2,66 @@ import { WakaProviderConfig, WakaProviderProps } from '../types/provider';
 /**
  * WakaProvider - Provider principal pour WakaStart UI
  *
- * Centralise la configuration du thème, de la langue et des traductions S3
+ * Centralise la configuration du thème et de la langue.
+ * Fonctionne avec des thèmes/traductions inline (sans dépendance S3)
+ * ou avec S3 pour un chargement distant.
  *
  * @example
  * ```tsx
+ * // Configuration avec thèmes et traductions inline (sans S3)
  * <WakaProvider config={{
  *   theme: {
  *     defaultTheme: "light",
- *     themes: ["light", "dark", "forest"],
- *     enableSystem: true
+ *     themes: [
+ *       {
+ *         id: "light",
+ *         label: "Clair",
+ *         cssVars: {
+ *           "--background": "0 0% 100%",
+ *           "--foreground": "222.2 84% 4.9%"
+ *         }
+ *       },
+ *       {
+ *         id: "dark",
+ *         label: "Sombre",
+ *         cssVars: {
+ *           "--background": "222.2 84% 4.9%",
+ *           "--foreground": "210 40% 98%"
+ *         }
+ *       }
+ *     ]
  *   },
  *   language: {
  *     defaultLanguage: "fr",
  *     supportedLanguages: ["fr", "en"],
- *     s3Config: {
- *       bucketUrl: "https://my-bucket.s3.amazonaws.com",
- *       translationsPath: "translations"
- *     }
+ *     languages: [
+ *       {
+ *         code: "fr",
+ *         label: "Français",
+ *         translations: { common: { save: "Enregistrer" } }
+ *       },
+ *       {
+ *         code: "en",
+ *         label: "English",
+ *         translations: { common: { save: "Save" } }
+ *       }
+ *     ]
+ *   }
+ * }}>
+ *   <App />
+ * </WakaProvider>
+ *
+ * // Configuration avec S3 (chargement distant)
+ * <WakaProvider config={{
+ *   theme: {
+ *     defaultTheme: "light",
+ *     themes: [{ id: "light", label: "Clair" }],
+ *     s3Config: { baseUrl: "https://cdn.example.com/themes" }
+ *   },
+ *   language: {
+ *     defaultLanguage: "fr",
+ *     supportedLanguages: ["fr", "en"],
+ *     s3Config: { bucketUrl: "https://cdn.example.com", translationsPath: "i18n" }
  *   }
  * }}>
  *   <App />

package/dist/hooks/use-toast.d.ts

@@ -1,11 +1,34 @@
 import { ToastActionElement, ToastProps } from '../components/toast';
+/**
+ * @fileoverview Hook de gestion des notifications toast
+ *
+ * Ce module fournit un système de notifications toast avec:
+ * - Gestion d'état globale via un reducer
+ * - Limite configurable du nombre de toasts
+ * - Suppression automatique après un délai
+ * - API simple pour créer, mettre à jour et fermer les toasts
+ *
+ * @module hooks/use-toast
+ */
 import * as React from "react";
+/**
+ * Type représentant un toast dans le système
+ * Étend ToastProps avec des propriétés additionnelles pour la gestion
+ */
 type ToasterToast = ToastProps & {
+    /** Identifiant unique du toast */
     id: string;
+    /** Titre du toast */
     title?: React.ReactNode;
+    /** Description/contenu du toast */
     description?: React.ReactNode;
+    /** Élément d'action optionnel (bouton, lien, etc.) */
     action?: ToastActionElement;
 };
+/**
+ * Types d'actions disponibles pour le reducer de toasts
+ * @internal
+ */
 declare const actionTypes: {
     readonly ADD_TOAST: "ADD_TOAST";
     readonly UPDATE_TOAST: "UPDATE_TOAST";
@@ -13,6 +36,10 @@ declare const actionTypes: {
     readonly REMOVE_TOAST: "REMOVE_TOAST";
 };
 type ActionType = typeof actionTypes;
+/**
+ * Union type des actions possibles pour le reducer de toasts
+ * @internal
+ */
 type Action = {
     type: ActionType["ADD_TOAST"];
     toast: ToasterToast;
@@ -26,19 +53,108 @@ type Action = {
     type: ActionType["REMOVE_TOAST"];
     toastId?: ToasterToast["id"];
 };
+/**
+ * État du gestionnaire de toasts
+ */
 interface State {
+    /** Liste des toasts actuellement affichés */
     toasts: ToasterToast[];
 }
+/**
+ * Reducer pour gérer l'état des toasts
+ *
+ * @param state - État actuel
+ * @param action - Action à exécuter
+ * @returns Nouvel état
+ *
+ * @example
+ * ```ts
+ * // Ajouter un toast
+ * reducer(state, { type: "ADD_TOAST", toast: { id: "1", title: "Hello" } })
+ *
+ * // Fermer un toast
+ * reducer(state, { type: "DISMISS_TOAST", toastId: "1" })
+ * ```
+ */
 export declare const reducer: (state: State, action: Action) => State;
+/**
+ * Type pour les props d'un nouveau toast (sans l'ID qui est généré automatiquement)
+ */
 type Toast = Omit<ToasterToast, "id">;
+/**
+ * Crée et affiche un nouveau toast
+ *
+ * @param props - Propriétés du toast (title, description, variant, action, etc.)
+ * @returns Objet avec l'ID du toast et les méthodes dismiss/update
+ *
+ * @example
+ * ```tsx
+ * // Toast simple
+ * toast({ title: "Succès", description: "Opération réussie" })
+ *
+ * // Toast avec action
+ * toast({
+ *   title: "Nouveau message",
+ *   description: "Vous avez reçu un message",
+ *   action: <ToastAction altText="Voir">Voir</ToastAction>
+ * })
+ *
+ * // Toast destructif
+ * toast({
+ *   variant: "destructive",
+ *   title: "Erreur",
+ *   description: "Une erreur est survenue"
+ * })
+ *
+ * // Contrôler le toast
+ * const { id, dismiss, update } = toast({ title: "Chargement..." })
+ * // Plus tard...
+ * update({ title: "Terminé!" })
+ * // Ou...
+ * dismiss()
+ * ```
+ */
 declare function toast({ ...props }: Toast): {
+    /** Identifiant unique du toast créé */
     id: string;
+    /** Ferme le toast */
     dismiss: () => void;
+    /** Met à jour le toast avec de nouvelles propriétés */
     update: (props: ToasterToast) => void;
 };
+/**
+ * Hook pour accéder au système de toasts
+ *
+ * Fournit l'état actuel des toasts et les méthodes pour les gérer.
+ *
+ * @returns Objet contenant les toasts, la fonction toast() et dismiss()
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { toast, toasts, dismiss } = useToast()
+ *
+ *   const handleClick = () => {
+ *     toast({
+ *       title: "Hello!",
+ *       description: "Ceci est une notification"
+ *     })
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleClick}>
+ *       Afficher toast
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 declare function useToast(): {
+    /** Fonction pour créer un nouveau toast */
     toast: typeof toast;
+    /** Fonction pour fermer un toast spécifique ou tous les toasts */
     dismiss: (toastId?: string) => void;
+    /** Liste des toasts actuellement affichés */
     toasts: ToasterToast[];
 };
 export { useToast, toast };

package/dist/hooks/use-translation.d.ts

@@ -1,3 +1,22 @@
+import { default as i18n } from '../lib/i18n';
+/**
+ * Type pour les options de traduction
+ */
+type TranslationOptions = Record<string, string | number | boolean> & {
+    defaultValue?: string;
+};
+/**
+ * Type pour la fonction de traduction
+ */
+type TranslationFunction = (key: string, options?: TranslationOptions) => string;
+/**
+ * Type de retour du hook useTranslation
+ */
+interface TranslationResult {
+    t: TranslationFunction;
+    i18n: typeof i18n;
+    ready: boolean;
+}
 /**
  * Hook pour utiliser les traductions dans les composants
  *
@@ -6,10 +25,14 @@
  *
  * Si i18next n'est pas encore prêt, retourne la clé de traduction telle quelle.
  *
+ * @param namespace - Namespace i18n optionnel
+ * @returns Objet contenant la fonction t, l'instance i18n et l'état ready
+ *
  * @example
  * ```tsx
  * const { t } = useTranslation()
  * return <div>{t('hello')}</div>
  * ```
  */
-export declare function useTranslation(): any;
+export declare function useTranslation(namespace?: string): TranslationResult;
+export {};

package/dist/hooks/useToast.d.ts

@@ -1,11 +1,34 @@
 import { ToastActionElement, ToastProps } from '../components/toast';
+/**
+ * @fileoverview Système de notifications toast pour WakaStart UI
+ *
+ * Ce module implémente un système de gestion des notifications toast
+ * avec support pour:
+ * - Création, mise à jour et suppression de toasts
+ * - Limite configurable du nombre de toasts affichés
+ * - Suppression automatique après délai
+ * - Pattern publish/subscribe pour la réactivité React
+ *
+ * @module hooks/useToast
+ */
 import * as React from "react";
+/**
+ * Représente un toast complet avec toutes ses propriétés
+ * Étend ToastProps avec les propriétés spécifiques au système
+ */
 type ToasterToast = ToastProps & {
+    /** Identifiant unique du toast */
     id: string;
+    /** Titre du toast */
     title?: React.ReactNode;
+    /** Description/contenu du toast */
     description?: React.ReactNode;
+    /** Action personnalisée (bouton, lien, etc.) */
     action?: ToastActionElement;
 };
+/**
+ * Types d'actions disponibles pour le reducer
+ */
 declare const actionTypes: {
     readonly ADD_TOAST: "ADD_TOAST";
     readonly UPDATE_TOAST: "UPDATE_TOAST";
@@ -13,6 +36,9 @@ declare const actionTypes: {
     readonly REMOVE_TOAST: "REMOVE_TOAST";
 };
 type ActionType = typeof actionTypes;
+/**
+ * Actions disponibles pour manipuler l'état des toasts
+ */
 type Action = {
     type: ActionType["ADD_TOAST"];
     toast: ToasterToast;
@@ -26,19 +52,75 @@ type Action = {
     type: ActionType["REMOVE_TOAST"];
     toastId?: ToasterToast["id"];
 };
+/**
+ * État global du système de toasts
+ */
 interface State {
+    /** Liste des toasts actuellement actifs */
     toasts: ToasterToast[];
 }
+/**
+ * Reducer pour la gestion de l'état des toasts
+ *
+ * @param state - État actuel
+ * @param action - Action à appliquer
+ * @returns Nouvel état
+ */
 export declare const reducer: (state: State, action: Action) => State;
+/** Type pour les props de création d'un toast (sans l'ID) */
 type Toast = Omit<ToasterToast, "id">;
+/**
+ * Crée et affiche un nouveau toast
+ *
+ * @param props - Propriétés du toast (title, description, variant, action, etc.)
+ * @returns Objet avec l'ID du toast et les méthodes dismiss/update
+ *
+ * @example
+ * ```tsx
+ * // Toast simple
+ * toast({ title: "Succès", description: "Opération réussie" })
+ *
+ * // Toast avec action
+ * toast({
+ *   title: "Fichier supprimé",
+ *   action: <ToastAction onClick={undo}>Annuler</ToastAction>
+ * })
+ *
+ * // Contrôler le toast
+ * const { id, dismiss, update } = toast({ title: "Chargement..." })
+ * update({ title: "Terminé !" })
+ * ```
+ */
 declare function toast({ ...props }: Toast): {
     id: string;
     dismiss: () => void;
     update: (props: ToasterToast) => void;
 };
+/**
+ * Hook pour accéder au système de toasts
+ *
+ * Fournit l'état actuel des toasts et les méthodes pour les manipuler.
+ * S'abonne automatiquement aux mises à jour de l'état.
+ *
+ * @returns État des toasts et méthodes de manipulation
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { toasts, toast, dismiss } = useToast()
+ *
+ *   return (
+ *     <button onClick={() => toast({ title: "Hello!" })}>
+ *       Afficher toast
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 declare function useToast(): {
     toast: typeof toast;
     dismiss: (toastId?: string) => void;
+    /** Liste des toasts actuellement actifs */
     toasts: ToasterToast[];
 };
 export { useToast, toast };