@sia-ui/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Mbella
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @sia-ui/react
+
+Les primitives de runtime dont un composant DOM a besoin.
+
+```bash
+pnpm add @sia-ui/react
+```
+
+```tsx
+import { SiaProvider, Portal, usePortal, useOutsideClick } from "@sia-ui/react";
+```
+
+- `SiaProvider` — thème clair/sombre, variables CSS;
+- `Portal` et `usePortal` — rendre hors du flux, sans casser le rendu serveur;
+- `useOutsideClick` — écoute `pointerdown`, pas `click` : une sélection de
+  texte qui déborde ne ferme pas l'overlay;
+- `useControllableState`, `useDisclosure`, `mergeRefs`.
+
+`react` et `react-dom` sont des `peerDependencies`.
+
+## Place dans SIA UI
+
+```
+@sia-ui/tokens      valeurs : couleurs, espacements, mouvement, vocabulaire
+@sia-ui/utils       fonctions sans dépendance
+@sia-ui/api         client HTTP — indépendant de l'interface
+@sia-ui/headless    comportement, avec React, sans plateforme
+@sia-ui/react       primitives de runtime DOM
+@sia-ui/react-web   composants DOM
+@sia-ui/react-native  composants natifs, à venir
+```
+
+Une chose s'écrit au niveau le plus bas où elle a du sens, et une seule fois.
+Voir [la documentation](https://github.com/BeatJo/sia-ui/tree/main/docs).
+
+## Licence
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,319 @@
+'use strict';
+
+var react = require('react');
+var tokens = require('@sia-ui/tokens');
+var jsxRuntime = require('react/jsx-runtime');
+var reactDom = require('react-dom');
+var clipboard = require('@sia-ui/utils/clipboard');
+
+// src/theme-provider.tsx
+function read(key, fallback, area, deserialize) {
+  if (!area) return fallback;
+  try {
+    const raw = area.getItem(key);
+    return raw === null ? fallback : deserialize(raw);
+  } catch {
+    return fallback;
+  }
+}
+function areaFor(kind) {
+  if (typeof window === "undefined") return null;
+  try {
+    return kind === "session" ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function useLocalStorage(key, initialValue, options = {}) {
+  const {
+    storage = "local",
+    serialize = JSON.stringify,
+    deserialize = JSON.parse,
+    syncTabs = false
+  } = options;
+  const area = areaFor(storage);
+  const [value, setValue] = react.useState(initialValue);
+  const hydrated = react.useRef(false);
+  react.useEffect(() => {
+    if (hydrated.current) return;
+    hydrated.current = true;
+    const stored = read(key, initialValue, area, deserialize);
+    if (stored !== initialValue) setValue(stored);
+  }, []);
+  const write = react.useCallback(
+    (next) => {
+      setValue((current) => {
+        const resolved = typeof next === "function" ? next(current) : next;
+        try {
+          area?.setItem(key, serialize(resolved));
+        } catch {
+        }
+        return resolved;
+      });
+    },
+    [area, key, serialize]
+  );
+  const remove = react.useCallback(() => {
+    try {
+      area?.removeItem(key);
+    } catch {
+    }
+    setValue(initialValue);
+  }, [area, key]);
+  react.useEffect(() => {
+    if (!syncTabs || typeof window === "undefined") return void 0;
+    const onStorage = (event) => {
+      if (event.key !== key || event.storageArea !== area) return;
+      setValue(
+        event.newValue === null ? initialValue : deserialize(event.newValue)
+      );
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, [area, key, syncTabs]);
+  return [value, write, remove];
+}
+function useMediaQuery(query, serverValue = false) {
+  const subscribe = react.useCallback(
+    (onChange) => {
+      if (typeof window === "undefined" || !window.matchMedia) return () => {
+      };
+      const list = window.matchMedia(query);
+      list.addEventListener("change", onChange);
+      return () => list.removeEventListener("change", onChange);
+    },
+    [query]
+  );
+  const getSnapshot = react.useCallback(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return serverValue;
+    return window.matchMedia(query).matches;
+  }, [query, serverValue]);
+  const getServerSnapshot = react.useCallback(() => serverValue, [serverValue]);
+  return react.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+var breakpoints = {
+  sm: 480,
+  md: 640,
+  lg: 768,
+  xl: 1024,
+  "2xl": 1280
+};
+function useBreakpoint(name) {
+  return useMediaQuery(`(min-width: ${breakpoints[name]}px)`);
+}
+function useIsMobile() {
+  return !useMediaQuery(`(min-width: ${breakpoints.lg}px)`);
+}
+function usePrefersDark() {
+  return useMediaQuery("(prefers-color-scheme: dark)");
+}
+function usePrefersReducedMotion() {
+  return useMediaQuery("(prefers-reduced-motion: reduce)");
+}
+var COLOR_MODE_KEY = "sia-ui.color-mode";
+var ThemeContext = react.createContext({
+  colorMode: "light",
+  resolvedColorMode: "light",
+  setColorMode: () => {
+  },
+  toggleColorMode: () => {
+  }
+});
+function SiaProvider({
+  children,
+  colorMode: controlled,
+  defaultColorMode = "system",
+  onColorModeChange,
+  storageKey = COLOR_MODE_KEY,
+  theme,
+  className
+}) {
+  const [stored, setStored] = useLocalStorage(
+    storageKey === false ? COLOR_MODE_KEY : storageKey,
+    defaultColorMode
+  );
+  const mode = controlled ?? (storageKey === false ? defaultColorMode : stored);
+  const prefersDark = usePrefersDark();
+  const resolved = mode === "system" ? prefersDark ? "dark" : "light" : mode;
+  const setColorMode = react.useCallback(
+    (next) => {
+      if (storageKey !== false && controlled === void 0) setStored(next);
+      onColorModeChange?.(next);
+    },
+    [controlled, onColorModeChange, setStored, storageKey]
+  );
+  const variables = react.useMemo(() => {
+    const semanticTheme = resolved === "dark" ? tokens.darkTheme : tokens.lightTheme;
+    return {
+      ...tokens.toCssVariables(tokens.primitives),
+      ...tokens.toCssVariables(semanticTheme),
+      ...tokens.toCssVariables(theme ?? {})
+    };
+  }, [resolved, theme]);
+  react.useEffect(() => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    root.dataset.siaColorMode = resolved;
+    root.style.colorScheme = resolved;
+  }, [resolved]);
+  const value = react.useMemo(
+    () => ({
+      colorMode: mode,
+      resolvedColorMode: resolved,
+      setColorMode,
+      // Bascule depuis ce qui est affiché, pas depuis ce qui est demandé :
+      // en mode `system` la personne voit du sombre et attend du clair.
+      toggleColorMode: () => setColorMode(resolved === "dark" ? "light" : "dark")
+    }),
+    [mode, resolved, setColorMode]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(ThemeContext.Provider, { value, children: /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      className,
+      "data-sia-root": "",
+      "data-sia-color-mode": resolved,
+      style: variables,
+      children
+    }
+  ) });
+}
+function useSiaTheme() {
+  return react.useContext(ThemeContext);
+}
+function useColorMode() {
+  const { colorMode, resolvedColorMode, setColorMode, toggleColorMode } = react.useContext(ThemeContext);
+  return { colorMode, resolvedColorMode, setColorMode, toggleColorMode };
+}
+function colorModeScript(storageKey = COLOR_MODE_KEY, defaultMode = "system") {
+  return `(function(){try{var m=localStorage.getItem(${JSON.stringify(storageKey)});m=m?JSON.parse(m):${JSON.stringify(defaultMode)};if(m==="system"){m=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";}document.documentElement.dataset.siaColorMode=m;document.documentElement.style.colorScheme=m;}catch(e){}})();`;
+}
+function useControllableState({
+  value,
+  defaultValue,
+  onChange
+}) {
+  const [internalValue, setInternalValue] = react.useState(defaultValue);
+  const controlled = value !== void 0;
+  const currentValue = controlled ? value : internalValue;
+  const setValue = react.useCallback(
+    (nextValue) => {
+      if (!controlled) setInternalValue(nextValue);
+      onChange?.(nextValue);
+    },
+    [controlled, onChange]
+  );
+  return [currentValue, setValue];
+}
+function useDisclosure(options = {}) {
+  const [open, setOpen] = useControllableState({
+    value: options.open,
+    defaultValue: options.defaultOpen ?? false,
+    onChange: options.onOpenChange
+  });
+  return {
+    open,
+    setOpen,
+    onOpen: react.useCallback(() => setOpen(true), [setOpen]),
+    onClose: react.useCallback(() => setOpen(false), [setOpen]),
+    onToggle: react.useCallback(() => setOpen(!open), [open, setOpen])
+  };
+}
+
+// src/merge-refs.ts
+function mergeRefs(...refs) {
+  return (value) => {
+    for (const ref of refs) {
+      if (typeof ref === "function") ref(value);
+      else if (ref) ref.current = value;
+    }
+  };
+}
+function usePortal(options = {}) {
+  const { container, id } = options;
+  const [node, setNode] = react.useState(null);
+  react.useEffect(() => {
+    if (typeof document === "undefined") return void 0;
+    if (container) {
+      setNode(container);
+      return void 0;
+    }
+    const element = document.createElement("div");
+    if (id) element.id = id;
+    element.setAttribute("data-sia-portal", "");
+    document.body.appendChild(element);
+    setNode(element);
+    return () => {
+      element.remove();
+      setNode(null);
+    };
+  }, [container, id]);
+  return node;
+}
+
+// src/portal.tsx
+function Portal({ children, container }) {
+  const node = usePortal(container ? { container } : {});
+  return node ? reactDom.createPortal(children, node) : null;
+}
+function useOutsideClick(targets, onOutside, options = {}) {
+  const { enabled = true } = options;
+  const handler = react.useRef(onOutside);
+  handler.current = onOutside;
+  const refs = react.useRef(targets);
+  refs.current = targets;
+  react.useEffect(() => {
+    if (!enabled || typeof document === "undefined") return void 0;
+    const listener = (event) => {
+      const target = event.target;
+      if (!target || !target.isConnected) return;
+      const zones = Array.isArray(refs.current) ? refs.current : [refs.current];
+      if (zones.some((zone) => zone.current?.contains(target))) return;
+      handler.current(event);
+    };
+    document.addEventListener("pointerdown", listener, true);
+    return () => document.removeEventListener("pointerdown", listener, true);
+  }, [enabled]);
+}
+function useCopyToClipboard(options = {}) {
+  const { resetAfter = 2e3 } = options;
+  const [copied, setCopied] = react.useState(false);
+  const [failed, setFailed] = react.useState(false);
+  const timer = react.useRef(void 0);
+  react.useEffect(() => () => clearTimeout(timer.current), []);
+  const copy = react.useCallback(
+    async (text) => {
+      const ok = await clipboard.copyText(text);
+      setCopied(ok);
+      setFailed(!ok);
+      clearTimeout(timer.current);
+      timer.current = setTimeout(() => {
+        setCopied(false);
+        setFailed(false);
+      }, resetAfter);
+      return ok;
+    },
+    [resetAfter]
+  );
+  return { copy, copied, failed };
+}
+
+exports.COLOR_MODE_KEY = COLOR_MODE_KEY;
+exports.Portal = Portal;
+exports.SiaProvider = SiaProvider;
+exports.breakpoints = breakpoints;
+exports.colorModeScript = colorModeScript;
+exports.mergeRefs = mergeRefs;
+exports.useBreakpoint = useBreakpoint;
+exports.useColorMode = useColorMode;
+exports.useControllableState = useControllableState;
+exports.useCopyToClipboard = useCopyToClipboard;
+exports.useDisclosure = useDisclosure;
+exports.useIsMobile = useIsMobile;
+exports.useLocalStorage = useLocalStorage;
+exports.useMediaQuery = useMediaQuery;
+exports.useOutsideClick = useOutsideClick;
+exports.usePortal = usePortal;
+exports.usePrefersDark = usePrefersDark;
+exports.usePrefersReducedMotion = usePrefersReducedMotion;
+exports.useSiaTheme = useSiaTheme;

package/dist/index.d.cts

@@ -0,0 +1,208 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { PropsWithChildren, Ref, RefCallback, RefObject } from 'react';
+import { SiaTheme } from '@sia-ui/tokens';
+
+/** Ce que l'application demande. */
+type ColorMode = "light" | "dark" | "system";
+/** Ce qui est réellement appliqué — `system` a été résolu. */
+type ResolvedColorMode = "light" | "dark";
+declare const COLOR_MODE_KEY = "sia-ui.color-mode";
+interface SiaProviderProps extends PropsWithChildren {
+    /** Le mode imposé. Sans lui, le mode est piloté par le fournisseur. */
+    colorMode?: ColorMode;
+    /** Le mode de départ quand rien n'est encore enregistré. */
+    defaultColorMode?: ColorMode;
+    onColorModeChange?: (mode: ColorMode) => void;
+    /** Clé de persistance, ou `false` pour ne rien enregistrer. */
+    storageKey?: string | false;
+    theme?: SiaTheme;
+    className?: string;
+}
+interface ThemeValue {
+    /** Ce qui est demandé : `light`, `dark` ou `system`. */
+    colorMode: ColorMode;
+    /** Ce qui est appliqué, `system` résolu. */
+    resolvedColorMode: ResolvedColorMode;
+    setColorMode: (mode: ColorMode) => void;
+    /** Bascule entre clair et sombre, en partant de ce qui est affiché. */
+    toggleColorMode: () => void;
+}
+/**
+ * Le thème de l'application.
+ *
+ * `next-themes` apparaît dans cinq des projets du disque D, pour cette seule
+ * fonction. Il tient ici en un fournisseur, sans dépendance et sans être lié
+ * à un cadre : `system` suit la préférence du poste, le choix est enregistré,
+ * et `colorMode` reste disponible pour piloter le mode depuis l'extérieur.
+ */
+declare function SiaProvider({ children, colorMode: controlled, defaultColorMode, onColorModeChange, storageKey, theme, className, }: SiaProviderProps): react_jsx_runtime.JSX.Element;
+/** Le thème en vigueur, et de quoi en changer. */
+declare function useSiaTheme(): ThemeValue;
+/**
+ * Le mode et son sélecteur, sans le reste.
+ *
+ * ```tsx
+ * const { resolvedColorMode, toggleColorMode } = useColorMode();
+ * <Toggle pressed={resolvedColorMode === "dark"} onPressedChange={toggleColorMode} />
+ * ```
+ */
+declare function useColorMode(): {
+    colorMode: ColorMode;
+    resolvedColorMode: ResolvedColorMode;
+    setColorMode: (mode: ColorMode) => void;
+    toggleColorMode: () => void;
+};
+/**
+ * Le script à poser avant le premier rendu, pour éviter le flash.
+ *
+ * Entre le chargement du document et le premier rendu de React, la page
+ * s'affiche dans le mode par défaut — un éclair blanc sur un thème sombre.
+ * Ce script lit le choix enregistré et pose l'attribut avant la peinture.
+ *
+ * ```tsx
+ * <head>
+ *   <script dangerouslySetInnerHTML={{ __html: colorModeScript() }} />
+ * </head>
+ * ```
+ */
+declare function colorModeScript(storageKey?: string, defaultMode?: ColorMode): string;
+
+interface ControllableStateOptions<T> {
+    value?: T | undefined;
+    defaultValue: T;
+    onChange?: ((value: T) => void) | undefined;
+}
+declare function useControllableState<T>({ value, defaultValue, onChange }: ControllableStateOptions<T>): readonly [T, (nextValue: T) => void];
+
+declare function useDisclosure(options?: {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}): {
+    open: boolean;
+    setOpen: (nextValue: boolean) => void;
+    onOpen: () => void;
+    onClose: () => void;
+    onToggle: () => void;
+};
+
+declare function mergeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T>;
+
+interface PortalProps extends PropsWithChildren {
+    /** Conteneur existant à réutiliser. Par défaut, un nœud créé sous `document.body`. */
+    container?: HTMLElement | null | undefined;
+}
+/**
+ * Rend ses enfants hors du flux, dans un nœud attaché au document.
+ *
+ * Le rendu est différé jusqu'à ce que `usePortal` ait un nœud : sans cela le
+ * rendu serveur tenterait d'atteindre `document`, et la première passe cliente
+ * rendrait dans le vide.
+ */
+declare function Portal({ children, container }: PortalProps): react.ReactPortal | null;
+
+interface UsePortalOptions {
+    /** Conteneur existant à réutiliser. Par défaut, un nœud créé sous `document.body`. */
+    container?: HTMLElement | null | undefined;
+    /** Identifiant du nœud créé, utile pour le retrouver dans le DOM. */
+    id?: string | undefined;
+}
+/**
+ * Renvoie le nœud dans lequel une couche flottante doit être rendue, ou `null`
+ * tant que le document n'est pas disponible — le rendu serveur passe par ce cas.
+ *
+ * Le nœud créé par le hook est retiré au démontage; un conteneur fourni par
+ * l'appelant ne l'est jamais, puisqu'il ne nous appartient pas.
+ */
+declare function usePortal(options?: UsePortalOptions): HTMLElement | null;
+
+type OutsideClickTarget = RefObject<HTMLElement | null>;
+interface UseOutsideClickOptions {
+    /** Désactive l'écoute sans démonter le composant. */
+    enabled?: boolean;
+}
+/**
+ * Appelle `onOutside` lorsqu'un pointeur est pressé hors de toutes les zones
+ * passées — un panneau et son déclencheur, par exemple.
+ *
+ * L'écoute se fait sur `pointerdown` et non sur `click` : un clic dont la
+ * pression a commencé à l'intérieur et s'est terminée à l'extérieur — une
+ * sélection de texte qui déborde — ne doit pas fermer l'overlay.
+ */
+declare function useOutsideClick(targets: OutsideClickTarget | readonly OutsideClickTarget[], onOutside: (event: PointerEvent) => void, options?: UseOutsideClickOptions): void;
+
+/**
+ * Une requête média, suivie en direct.
+ *
+ * `useSyncExternalStore` plutôt qu'un `useState` + `useEffect` : le rendu
+ * serveur rend `false`, la première passe cliente lit la vraie valeur, et
+ * React sait que la source est extérieure. Un `useEffect` produirait un
+ * clignotement au premier affichage — la mise en page saute une fois montée.
+ */
+declare function useMediaQuery(query: string, serverValue?: boolean): boolean;
+/** Les points de rupture du système, alignés sur les feuilles de style. */
+declare const breakpoints: {
+    readonly sm: 480;
+    readonly md: 640;
+    readonly lg: 768;
+    readonly xl: 1024;
+    readonly "2xl": 1280;
+};
+type Breakpoint = keyof typeof breakpoints;
+/** Vrai au-dessus du point de rupture demandé. */
+declare function useBreakpoint(name: Breakpoint): boolean;
+/** Vrai sous 768 px — le seuil où les mises en page du dépôt basculent. */
+declare function useIsMobile(): boolean;
+/** La préférence système de thème sombre. */
+declare function usePrefersDark(): boolean;
+/**
+ * La préférence système de mouvement réduit.
+ *
+ * Les feuilles de style la respectent déjà. Ce hook sert pour ce que le CSS
+ * ne peut pas couper : une animation pilotée en JavaScript, un défilement
+ * automatique, un carrousel.
+ */
+declare function usePrefersReducedMotion(): boolean;
+
+interface UseLocalStorageOptions<T> {
+    /** `sessionStorage` pour ce qui ne doit pas survivre à l'onglet. */
+    storage?: "local" | "session";
+    serialize?: (value: T) => string;
+    deserialize?: (raw: string) => T;
+    /**
+     * Suit les changements venus d'un autre onglet. Utile pour une déconnexion
+     * ou un thème; inutile — et coûteux — pour un brouillon local.
+     */
+    syncTabs?: boolean;
+}
+/**
+ * Une valeur qui survit au rechargement.
+ *
+ * La lecture initiale est paresseuse : elle se fait au premier rendu client,
+ * jamais pendant le rendu serveur, ce qui évite l'erreur d'hydratation quand
+ * la valeur stockée diffère du repli.
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T, options?: UseLocalStorageOptions<T>): readonly [T, (next: T | ((current: T) => T)) => void, () => void];
+
+interface UseCopyToClipboardOptions {
+    /** Durée pendant laquelle `copied` reste vrai. */
+    resetAfter?: number;
+}
+interface CopyToClipboard {
+    copy: (text: string) => Promise<boolean>;
+    /** Vrai juste après une copie réussie — pour changer l'icône du bouton. */
+    copied: boolean;
+    /** Vrai si la dernière tentative a échoué. */
+    failed: boolean;
+}
+/**
+ * Copier, et le montrer.
+ *
+ * La copie elle-même est dans `@sia-ui/utils/clipboard`, avec son repli pour
+ * les contextes non sécurisés. Ce qui est ici est le seul ajout de React :
+ * l'état éphémère qui permet au bouton de dire « copié » deux secondes.
+ */
+declare function useCopyToClipboard(options?: UseCopyToClipboardOptions): CopyToClipboard;
+
+export { type Breakpoint, COLOR_MODE_KEY, type ColorMode, type ControllableStateOptions, type CopyToClipboard, type OutsideClickTarget, Portal, type PortalProps, type ResolvedColorMode, SiaProvider, type SiaProviderProps, type UseCopyToClipboardOptions, type UseLocalStorageOptions, type UseOutsideClickOptions, type UsePortalOptions, breakpoints, colorModeScript, mergeRefs, useBreakpoint, useColorMode, useControllableState, useCopyToClipboard, useDisclosure, useIsMobile, useLocalStorage, useMediaQuery, useOutsideClick, usePortal, usePrefersDark, usePrefersReducedMotion, useSiaTheme };

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { PropsWithChildren, Ref, RefCallback, RefObject } from 'react';
+import { SiaTheme } from '@sia-ui/tokens';
+
+/** Ce que l'application demande. */
+type ColorMode = "light" | "dark" | "system";
+/** Ce qui est réellement appliqué — `system` a été résolu. */
+type ResolvedColorMode = "light" | "dark";
+declare const COLOR_MODE_KEY = "sia-ui.color-mode";
+interface SiaProviderProps extends PropsWithChildren {
+    /** Le mode imposé. Sans lui, le mode est piloté par le fournisseur. */
+    colorMode?: ColorMode;
+    /** Le mode de départ quand rien n'est encore enregistré. */
+    defaultColorMode?: ColorMode;
+    onColorModeChange?: (mode: ColorMode) => void;
+    /** Clé de persistance, ou `false` pour ne rien enregistrer. */
+    storageKey?: string | false;
+    theme?: SiaTheme;
+    className?: string;
+}
+interface ThemeValue {
+    /** Ce qui est demandé : `light`, `dark` ou `system`. */
+    colorMode: ColorMode;
+    /** Ce qui est appliqué, `system` résolu. */
+    resolvedColorMode: ResolvedColorMode;
+    setColorMode: (mode: ColorMode) => void;
+    /** Bascule entre clair et sombre, en partant de ce qui est affiché. */
+    toggleColorMode: () => void;
+}
+/**
+ * Le thème de l'application.
+ *
+ * `next-themes` apparaît dans cinq des projets du disque D, pour cette seule
+ * fonction. Il tient ici en un fournisseur, sans dépendance et sans être lié
+ * à un cadre : `system` suit la préférence du poste, le choix est enregistré,
+ * et `colorMode` reste disponible pour piloter le mode depuis l'extérieur.
+ */
+declare function SiaProvider({ children, colorMode: controlled, defaultColorMode, onColorModeChange, storageKey, theme, className, }: SiaProviderProps): react_jsx_runtime.JSX.Element;
+/** Le thème en vigueur, et de quoi en changer. */
+declare function useSiaTheme(): ThemeValue;
+/**
+ * Le mode et son sélecteur, sans le reste.
+ *
+ * ```tsx
+ * const { resolvedColorMode, toggleColorMode } = useColorMode();
+ * <Toggle pressed={resolvedColorMode === "dark"} onPressedChange={toggleColorMode} />
+ * ```
+ */
+declare function useColorMode(): {
+    colorMode: ColorMode;
+    resolvedColorMode: ResolvedColorMode;
+    setColorMode: (mode: ColorMode) => void;
+    toggleColorMode: () => void;
+};
+/**
+ * Le script à poser avant le premier rendu, pour éviter le flash.
+ *
+ * Entre le chargement du document et le premier rendu de React, la page
+ * s'affiche dans le mode par défaut — un éclair blanc sur un thème sombre.
+ * Ce script lit le choix enregistré et pose l'attribut avant la peinture.
+ *
+ * ```tsx
+ * <head>
+ *   <script dangerouslySetInnerHTML={{ __html: colorModeScript() }} />
+ * </head>
+ * ```
+ */
+declare function colorModeScript(storageKey?: string, defaultMode?: ColorMode): string;
+
+interface ControllableStateOptions<T> {
+    value?: T | undefined;
+    defaultValue: T;
+    onChange?: ((value: T) => void) | undefined;
+}
+declare function useControllableState<T>({ value, defaultValue, onChange }: ControllableStateOptions<T>): readonly [T, (nextValue: T) => void];
+
+declare function useDisclosure(options?: {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}): {
+    open: boolean;
+    setOpen: (nextValue: boolean) => void;
+    onOpen: () => void;
+    onClose: () => void;
+    onToggle: () => void;
+};
+
+declare function mergeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T>;
+
+interface PortalProps extends PropsWithChildren {
+    /** Conteneur existant à réutiliser. Par défaut, un nœud créé sous `document.body`. */
+    container?: HTMLElement | null | undefined;
+}
+/**
+ * Rend ses enfants hors du flux, dans un nœud attaché au document.
+ *
+ * Le rendu est différé jusqu'à ce que `usePortal` ait un nœud : sans cela le
+ * rendu serveur tenterait d'atteindre `document`, et la première passe cliente
+ * rendrait dans le vide.
+ */
+declare function Portal({ children, container }: PortalProps): react.ReactPortal | null;
+
+interface UsePortalOptions {
+    /** Conteneur existant à réutiliser. Par défaut, un nœud créé sous `document.body`. */
+    container?: HTMLElement | null | undefined;
+    /** Identifiant du nœud créé, utile pour le retrouver dans le DOM. */
+    id?: string | undefined;
+}
+/**
+ * Renvoie le nœud dans lequel une couche flottante doit être rendue, ou `null`
+ * tant que le document n'est pas disponible — le rendu serveur passe par ce cas.
+ *
+ * Le nœud créé par le hook est retiré au démontage; un conteneur fourni par
+ * l'appelant ne l'est jamais, puisqu'il ne nous appartient pas.
+ */
+declare function usePortal(options?: UsePortalOptions): HTMLElement | null;
+
+type OutsideClickTarget = RefObject<HTMLElement | null>;
+interface UseOutsideClickOptions {
+    /** Désactive l'écoute sans démonter le composant. */
+    enabled?: boolean;
+}
+/**
+ * Appelle `onOutside` lorsqu'un pointeur est pressé hors de toutes les zones
+ * passées — un panneau et son déclencheur, par exemple.
+ *
+ * L'écoute se fait sur `pointerdown` et non sur `click` : un clic dont la
+ * pression a commencé à l'intérieur et s'est terminée à l'extérieur — une
+ * sélection de texte qui déborde — ne doit pas fermer l'overlay.
+ */
+declare function useOutsideClick(targets: OutsideClickTarget | readonly OutsideClickTarget[], onOutside: (event: PointerEvent) => void, options?: UseOutsideClickOptions): void;
+
+/**
+ * Une requête média, suivie en direct.
+ *
+ * `useSyncExternalStore` plutôt qu'un `useState` + `useEffect` : le rendu
+ * serveur rend `false`, la première passe cliente lit la vraie valeur, et
+ * React sait que la source est extérieure. Un `useEffect` produirait un
+ * clignotement au premier affichage — la mise en page saute une fois montée.
+ */
+declare function useMediaQuery(query: string, serverValue?: boolean): boolean;
+/** Les points de rupture du système, alignés sur les feuilles de style. */
+declare const breakpoints: {
+    readonly sm: 480;
+    readonly md: 640;
+    readonly lg: 768;
+    readonly xl: 1024;
+    readonly "2xl": 1280;
+};
+type Breakpoint = keyof typeof breakpoints;
+/** Vrai au-dessus du point de rupture demandé. */
+declare function useBreakpoint(name: Breakpoint): boolean;
+/** Vrai sous 768 px — le seuil où les mises en page du dépôt basculent. */
+declare function useIsMobile(): boolean;
+/** La préférence système de thème sombre. */
+declare function usePrefersDark(): boolean;
+/**
+ * La préférence système de mouvement réduit.
+ *
+ * Les feuilles de style la respectent déjà. Ce hook sert pour ce que le CSS
+ * ne peut pas couper : une animation pilotée en JavaScript, un défilement
+ * automatique, un carrousel.
+ */
+declare function usePrefersReducedMotion(): boolean;
+
+interface UseLocalStorageOptions<T> {
+    /** `sessionStorage` pour ce qui ne doit pas survivre à l'onglet. */
+    storage?: "local" | "session";
+    serialize?: (value: T) => string;
+    deserialize?: (raw: string) => T;
+    /**
+     * Suit les changements venus d'un autre onglet. Utile pour une déconnexion
+     * ou un thème; inutile — et coûteux — pour un brouillon local.
+     */
+    syncTabs?: boolean;
+}
+/**
+ * Une valeur qui survit au rechargement.
+ *
+ * La lecture initiale est paresseuse : elle se fait au premier rendu client,
+ * jamais pendant le rendu serveur, ce qui évite l'erreur d'hydratation quand
+ * la valeur stockée diffère du repli.
+ */
+declare function useLocalStorage<T>(key: string, initialValue: T, options?: UseLocalStorageOptions<T>): readonly [T, (next: T | ((current: T) => T)) => void, () => void];
+
+interface UseCopyToClipboardOptions {
+    /** Durée pendant laquelle `copied` reste vrai. */
+    resetAfter?: number;
+}
+interface CopyToClipboard {
+    copy: (text: string) => Promise<boolean>;
+    /** Vrai juste après une copie réussie — pour changer l'icône du bouton. */
+    copied: boolean;
+    /** Vrai si la dernière tentative a échoué. */
+    failed: boolean;
+}
+/**
+ * Copier, et le montrer.
+ *
+ * La copie elle-même est dans `@sia-ui/utils/clipboard`, avec son repli pour
+ * les contextes non sécurisés. Ce qui est ici est le seul ajout de React :
+ * l'état éphémère qui permet au bouton de dire « copié » deux secondes.
+ */
+declare function useCopyToClipboard(options?: UseCopyToClipboardOptions): CopyToClipboard;
+
+export { type Breakpoint, COLOR_MODE_KEY, type ColorMode, type ControllableStateOptions, type CopyToClipboard, type OutsideClickTarget, Portal, type PortalProps, type ResolvedColorMode, SiaProvider, type SiaProviderProps, type UseCopyToClipboardOptions, type UseLocalStorageOptions, type UseOutsideClickOptions, type UsePortalOptions, breakpoints, colorModeScript, mergeRefs, useBreakpoint, useColorMode, useControllableState, useCopyToClipboard, useDisclosure, useIsMobile, useLocalStorage, useMediaQuery, useOutsideClick, usePortal, usePrefersDark, usePrefersReducedMotion, useSiaTheme };

package/dist/index.js

@@ -0,0 +1,299 @@
+import { createContext, useState, useRef, useEffect, useCallback, useSyncExternalStore, useMemo, useContext } from 'react';
+import { toCssVariables, darkTheme, lightTheme, primitives } from '@sia-ui/tokens';
+import { jsx } from 'react/jsx-runtime';
+import { createPortal } from 'react-dom';
+import { copyText } from '@sia-ui/utils/clipboard';
+
+// src/theme-provider.tsx
+function read(key, fallback, area, deserialize) {
+  if (!area) return fallback;
+  try {
+    const raw = area.getItem(key);
+    return raw === null ? fallback : deserialize(raw);
+  } catch {
+    return fallback;
+  }
+}
+function areaFor(kind) {
+  if (typeof window === "undefined") return null;
+  try {
+    return kind === "session" ? window.sessionStorage : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function useLocalStorage(key, initialValue, options = {}) {
+  const {
+    storage = "local",
+    serialize = JSON.stringify,
+    deserialize = JSON.parse,
+    syncTabs = false
+  } = options;
+  const area = areaFor(storage);
+  const [value, setValue] = useState(initialValue);
+  const hydrated = useRef(false);
+  useEffect(() => {
+    if (hydrated.current) return;
+    hydrated.current = true;
+    const stored = read(key, initialValue, area, deserialize);
+    if (stored !== initialValue) setValue(stored);
+  }, []);
+  const write = useCallback(
+    (next) => {
+      setValue((current) => {
+        const resolved = typeof next === "function" ? next(current) : next;
+        try {
+          area?.setItem(key, serialize(resolved));
+        } catch {
+        }
+        return resolved;
+      });
+    },
+    [area, key, serialize]
+  );
+  const remove = useCallback(() => {
+    try {
+      area?.removeItem(key);
+    } catch {
+    }
+    setValue(initialValue);
+  }, [area, key]);
+  useEffect(() => {
+    if (!syncTabs || typeof window === "undefined") return void 0;
+    const onStorage = (event) => {
+      if (event.key !== key || event.storageArea !== area) return;
+      setValue(
+        event.newValue === null ? initialValue : deserialize(event.newValue)
+      );
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, [area, key, syncTabs]);
+  return [value, write, remove];
+}
+function useMediaQuery(query, serverValue = false) {
+  const subscribe = useCallback(
+    (onChange) => {
+      if (typeof window === "undefined" || !window.matchMedia) return () => {
+      };
+      const list = window.matchMedia(query);
+      list.addEventListener("change", onChange);
+      return () => list.removeEventListener("change", onChange);
+    },
+    [query]
+  );
+  const getSnapshot = useCallback(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return serverValue;
+    return window.matchMedia(query).matches;
+  }, [query, serverValue]);
+  const getServerSnapshot = useCallback(() => serverValue, [serverValue]);
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+var breakpoints = {
+  sm: 480,
+  md: 640,
+  lg: 768,
+  xl: 1024,
+  "2xl": 1280
+};
+function useBreakpoint(name) {
+  return useMediaQuery(`(min-width: ${breakpoints[name]}px)`);
+}
+function useIsMobile() {
+  return !useMediaQuery(`(min-width: ${breakpoints.lg}px)`);
+}
+function usePrefersDark() {
+  return useMediaQuery("(prefers-color-scheme: dark)");
+}
+function usePrefersReducedMotion() {
+  return useMediaQuery("(prefers-reduced-motion: reduce)");
+}
+var COLOR_MODE_KEY = "sia-ui.color-mode";
+var ThemeContext = createContext({
+  colorMode: "light",
+  resolvedColorMode: "light",
+  setColorMode: () => {
+  },
+  toggleColorMode: () => {
+  }
+});
+function SiaProvider({
+  children,
+  colorMode: controlled,
+  defaultColorMode = "system",
+  onColorModeChange,
+  storageKey = COLOR_MODE_KEY,
+  theme,
+  className
+}) {
+  const [stored, setStored] = useLocalStorage(
+    storageKey === false ? COLOR_MODE_KEY : storageKey,
+    defaultColorMode
+  );
+  const mode = controlled ?? (storageKey === false ? defaultColorMode : stored);
+  const prefersDark = usePrefersDark();
+  const resolved = mode === "system" ? prefersDark ? "dark" : "light" : mode;
+  const setColorMode = useCallback(
+    (next) => {
+      if (storageKey !== false && controlled === void 0) setStored(next);
+      onColorModeChange?.(next);
+    },
+    [controlled, onColorModeChange, setStored, storageKey]
+  );
+  const variables = useMemo(() => {
+    const semanticTheme = resolved === "dark" ? darkTheme : lightTheme;
+    return {
+      ...toCssVariables(primitives),
+      ...toCssVariables(semanticTheme),
+      ...toCssVariables(theme ?? {})
+    };
+  }, [resolved, theme]);
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    root.dataset.siaColorMode = resolved;
+    root.style.colorScheme = resolved;
+  }, [resolved]);
+  const value = useMemo(
+    () => ({
+      colorMode: mode,
+      resolvedColorMode: resolved,
+      setColorMode,
+      // Bascule depuis ce qui est affiché, pas depuis ce qui est demandé :
+      // en mode `system` la personne voit du sombre et attend du clair.
+      toggleColorMode: () => setColorMode(resolved === "dark" ? "light" : "dark")
+    }),
+    [mode, resolved, setColorMode]
+  );
+  return /* @__PURE__ */ jsx(ThemeContext.Provider, { value, children: /* @__PURE__ */ jsx(
+    "div",
+    {
+      className,
+      "data-sia-root": "",
+      "data-sia-color-mode": resolved,
+      style: variables,
+      children
+    }
+  ) });
+}
+function useSiaTheme() {
+  return useContext(ThemeContext);
+}
+function useColorMode() {
+  const { colorMode, resolvedColorMode, setColorMode, toggleColorMode } = useContext(ThemeContext);
+  return { colorMode, resolvedColorMode, setColorMode, toggleColorMode };
+}
+function colorModeScript(storageKey = COLOR_MODE_KEY, defaultMode = "system") {
+  return `(function(){try{var m=localStorage.getItem(${JSON.stringify(storageKey)});m=m?JSON.parse(m):${JSON.stringify(defaultMode)};if(m==="system"){m=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";}document.documentElement.dataset.siaColorMode=m;document.documentElement.style.colorScheme=m;}catch(e){}})();`;
+}
+function useControllableState({
+  value,
+  defaultValue,
+  onChange
+}) {
+  const [internalValue, setInternalValue] = useState(defaultValue);
+  const controlled = value !== void 0;
+  const currentValue = controlled ? value : internalValue;
+  const setValue = useCallback(
+    (nextValue) => {
+      if (!controlled) setInternalValue(nextValue);
+      onChange?.(nextValue);
+    },
+    [controlled, onChange]
+  );
+  return [currentValue, setValue];
+}
+function useDisclosure(options = {}) {
+  const [open, setOpen] = useControllableState({
+    value: options.open,
+    defaultValue: options.defaultOpen ?? false,
+    onChange: options.onOpenChange
+  });
+  return {
+    open,
+    setOpen,
+    onOpen: useCallback(() => setOpen(true), [setOpen]),
+    onClose: useCallback(() => setOpen(false), [setOpen]),
+    onToggle: useCallback(() => setOpen(!open), [open, setOpen])
+  };
+}
+
+// src/merge-refs.ts
+function mergeRefs(...refs) {
+  return (value) => {
+    for (const ref of refs) {
+      if (typeof ref === "function") ref(value);
+      else if (ref) ref.current = value;
+    }
+  };
+}
+function usePortal(options = {}) {
+  const { container, id } = options;
+  const [node, setNode] = useState(null);
+  useEffect(() => {
+    if (typeof document === "undefined") return void 0;
+    if (container) {
+      setNode(container);
+      return void 0;
+    }
+    const element = document.createElement("div");
+    if (id) element.id = id;
+    element.setAttribute("data-sia-portal", "");
+    document.body.appendChild(element);
+    setNode(element);
+    return () => {
+      element.remove();
+      setNode(null);
+    };
+  }, [container, id]);
+  return node;
+}
+
+// src/portal.tsx
+function Portal({ children, container }) {
+  const node = usePortal(container ? { container } : {});
+  return node ? createPortal(children, node) : null;
+}
+function useOutsideClick(targets, onOutside, options = {}) {
+  const { enabled = true } = options;
+  const handler = useRef(onOutside);
+  handler.current = onOutside;
+  const refs = useRef(targets);
+  refs.current = targets;
+  useEffect(() => {
+    if (!enabled || typeof document === "undefined") return void 0;
+    const listener = (event) => {
+      const target = event.target;
+      if (!target || !target.isConnected) return;
+      const zones = Array.isArray(refs.current) ? refs.current : [refs.current];
+      if (zones.some((zone) => zone.current?.contains(target))) return;
+      handler.current(event);
+    };
+    document.addEventListener("pointerdown", listener, true);
+    return () => document.removeEventListener("pointerdown", listener, true);
+  }, [enabled]);
+}
+function useCopyToClipboard(options = {}) {
+  const { resetAfter = 2e3 } = options;
+  const [copied, setCopied] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const timer = useRef(void 0);
+  useEffect(() => () => clearTimeout(timer.current), []);
+  const copy = useCallback(
+    async (text) => {
+      const ok = await copyText(text);
+      setCopied(ok);
+      setFailed(!ok);
+      clearTimeout(timer.current);
+      timer.current = setTimeout(() => {
+        setCopied(false);
+        setFailed(false);
+      }, resetAfter);
+      return ok;
+    },
+    [resetAfter]
+  );
+  return { copy, copied, failed };
+}
+
+export { COLOR_MODE_KEY, Portal, SiaProvider, breakpoints, colorModeScript, mergeRefs, useBreakpoint, useColorMode, useControllableState, useCopyToClipboard, useDisclosure, useIsMobile, useLocalStorage, useMediaQuery, useOutsideClick, usePortal, usePrefersDark, usePrefersReducedMotion, useSiaTheme };

package/dist/styles.css

@@ -0,0 +1,12 @@
+/* src/styles.css */
+[data-sia-root] {
+  box-sizing: border-box;
+  color: var(--sia-foreground);
+  background: var(--sia-background);
+  font-family: var(--sia-font-sans);
+}
+[data-sia-root] *,
+[data-sia-root] *::before,
+[data-sia-root] *::after {
+  box-sizing: inherit;
+}

package/dist/styles.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/styles.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@sia-ui/react",
+  "version": "0.1.0",
+  "description": "React runtime foundations for SIA UI.",
+  "keywords": [
+    "sia-ui",
+    "react",
+    "provider",
+    "hooks",
+    "portal"
+  ],
+  "license": "MIT",
+  "author": "Ivan Mbella",
+  "homepage": "https://github.com/BeatJo/sia-ui#readme",
+  "bugs": {
+    "url": "https://github.com/BeatJo/sia-ui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BeatJo/sia-ui.git",
+    "directory": "packages/react"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sia-ui/utils": "0.1.0",
+    "@sia-ui/tokens": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0",
+    "react-dom": ">=18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  }
+}