@sia-ui/cli 0.2.1 → 0.3.0

package/dist/registry/package/components/DataTable/types.ts

@@ -0,0 +1,194 @@
+import type { Key, ReactNode } from "react";
+import type { PermissionRule } from "@sia-ui/headless";
+import type { ComponentTone } from "@sia-ui/tokens";
+
+/** Liste dense, ou grille de cartes. */
+export type DataTableView = "table" | "cards";
+
+/**
+ * Le rôle d'une colonne dans la carte.
+ *
+ * `title` sert d'en-tête — la première colonne le prend si rien n'est
+ * déclaré. `meta` s'affiche en paire libellé / valeur. `hidden` reste au
+ * tableau seul : une carte qui recopie douze colonnes n'est plus une carte.
+ */
+export type ColumnCardRole = "title" | "meta" | "hidden";
+
+export interface DataTableColumn<T> {
+  key: string;
+  header: ReactNode;
+
+  /**
+   * Où lire la valeur : une clé de l'objet, ou une fonction pour les valeurs
+   * calculées. Sert au rendu par défaut, à la carte et à la recherche locale.
+   */
+  accessor?: keyof T | ((row: T) => unknown);
+
+  /** Rendu personnalisé. Prioritaire sur `accessor`. */
+  cell?: (row: T, index: number) => ReactNode;
+
+  align?: "start" | "center" | "end";
+
+  /**
+   * Largeur suggérée — `120px`, `20%`.
+   *
+   * En `layout="auto"` (défaut) le navigateur n'y voit qu'une indication.
+   * Pour qu'elle soit tenue, passer en `layout="fixed"`.
+   */
+  width?: string;
+  minWidth?: string;
+
+  /** Coupe au lieu d'élargir. Indispensable en `layout="fixed"`. */
+  truncate?: boolean;
+
+  /** Retire la colonne du tableau sans toucher à la carte. */
+  hidden?: boolean;
+
+  /** Rend l'en-tête cliquable. Le tri lui-même reste au serveur. */
+  sortable?: boolean;
+  /** Le champ envoyé au serveur, si différent de `key`. */
+  sortKey?: string;
+
+  /** Place de la colonne dans la carte. */
+  card?: ColumnCardRole;
+
+  headerClassName?: string;
+  cellClassName?: string;
+}
+
+export interface RowAction<T> {
+  key: string;
+  label: ReactNode;
+  icon?: ReactNode;
+  tone?: ComponentTone;
+
+  /** Masque l'action pour cette ligne — un solde nul, un envoi déjà annulé. */
+  hidden?: (row: T, index: number) => boolean;
+  disabled?: (row: T, index: number) => boolean;
+
+  /** Même grammaire de droits que la navigation. */
+  permission?: PermissionRule;
+
+  /** Demande confirmation. Obligatoire pour tout ce qui détruit. */
+  confirm?: {
+    title: ReactNode;
+    description?: ReactNode;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    destructive?: boolean;
+  };
+
+  onSelect: (row: T, index: number) => void | Promise<void>;
+}
+
+export interface DataTableProps<T> {
+  columns: Array<DataTableColumn<T>>;
+  data: T[];
+
+  /** La clé d'une ligne. Sans elle, l'index — à éviter si les lignes bougent. */
+  getRowKey?: (row: T, index: number) => Key;
+
+  /* ─────────────────────────────────────────────── en-tête et recherche */
+
+  title?: ReactNode;
+  description?: ReactNode;
+  /** Zone libre : filtres, sélecteur de période. */
+  toolbar?: ReactNode;
+  /** Actions globales, à droite. */
+  actions?: ReactNode;
+
+  /**
+   * Les clés sur lesquelles porte la recherche.
+   *
+   * Absente, aucun champ n'est affiché : un tableau sans champ déclaré n'a
+   * rien à chercher. Le filtrage est local, sur les lignes déjà chargées.
+   */
+  searchKeys?: string[];
+  searchPlaceholder?: string;
+  /** Recherche déléguée. Fournie, le tableau cesse de filtrer lui-même. */
+  onSearch?: (query: string) => void;
+
+  /* ─────────────────────────────────────────────────────── mise en page */
+
+  layout?: "auto" | "fixed";
+  /** Hauteur du corps. Sans elle, `stickyHeader` n'a rien où se coller. */
+  maxHeight?: string;
+  stickyHeader?: boolean;
+  density?: "compact" | "default" | "comfortable";
+  /** Un fond alterné, une ligne sur deux. */
+  striped?: boolean;
+  bordered?: boolean;
+
+  /* ────────────────────────────────────────────────── actions de ligne */
+
+  rowActions?: Array<RowAction<T>> | ((row: T, index: number) => Array<RowAction<T>>);
+  /** Au-delà, les actions passent dans un menu. */
+  inlineActionsLimit?: number;
+  actionsHeader?: ReactNode;
+  /** `icon` garde la colonne étroite sur un tableau déjà large. */
+  actionsDisplay?: "icon" | "label";
+
+  /** Évalue les règles de permission des actions. */
+  can?: (rule: PermissionRule) => boolean;
+
+  /* ────────────────────────────────────────────────── modes d'affichage */
+
+  view?: DataTableView;
+  defaultView?: DataTableView;
+  onViewChange?: (view: DataTableView) => void;
+  showViewToggle?: boolean;
+
+  /**
+   * Bascule en cartes sous le point de rupture. Actif par défaut : un
+   * tableau à sept colonnes est illisible sur un téléphone.
+   */
+  responsive?: boolean;
+  cardsBreakpoint?: number;
+
+  /** Rendu complet d'une carte. Sans lui, elle est déduite des colonnes. */
+  renderCard?: (row: T, index: number) => ReactNode;
+
+  /* ──────────────────────────────────────────────────────────── états */
+
+  loading?: boolean;
+  /** Lignes fantômes pendant le premier chargement. */
+  skeletonRows?: number;
+  error?: ReactNode;
+  onRetry?: () => void;
+  empty?: {
+    title?: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+  };
+
+  /* ───────────────────────────────────────────────────────── sélection */
+
+  /**
+   * Ajoute une colonne de cases à cocher.
+   *
+   * Sur une liste paginée côté serveur, la case d'en-tête ne porte que sur la
+   * page affichée : le composant ne connaît pas les lignes qu'il n'a pas
+   * reçues, et prétendre « tout sélectionner » serait un mensonge.
+   */
+  selectable?: boolean;
+  selectedKeys?: Key[];
+  defaultSelectedKeys?: Key[];
+  onSelectionChange?: (keys: Key[], rows: T[]) => void;
+  isRowSelectable?: (row: T, index: number) => boolean;
+  /** Barre affichée dès qu'une ligne est cochée. */
+  selectionActions?: (context: {
+    keys: Key[];
+    rows: T[];
+    clear: () => void;
+  }) => ReactNode;
+
+  /* ───────────────────────────────────────────────────────────── tri */
+
+  sort?: { field: string; direction: "asc" | "desc" } | null;
+  onSortChange?: (field: string) => void;
+
+  onRowClick?: (row: T, index: number) => void;
+  rowClassName?: (row: T, index: number) => string | undefined;
+  caption?: string;
+  className?: string;
+}

package/dist/registry/package/components/DataTable/values.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import type { DataTableColumn } from "./types";
+
+/**
+ * Lire une colonne.
+ *
+ * Tenu à part du tableau parce que trois endroits en ont besoin : le tableau
+ * lui-même, la carte, et la vue de détail de `CrudPage`. Recopié, ce petit
+ * morceau se serait mis à diverger — la vue de détail aurait ignoré les
+ * `accessor` calculés, et personne ne l'aurait remarqué avant de voir une
+ * ligne vide dans un modal.
+ */
+export function valeurDe<T>(row: T, column: DataTableColumn<T>): unknown {
+  if (typeof column.accessor === "function") return column.accessor(row);
+  if (column.accessor !== undefined) return row[column.accessor];
+  return (row as Record<string, unknown>)[column.key];
+}
+
+/** Ce qu'une cellule affiche : son rendu propre, ou sa valeur en texte. */
+export function renduCellule<T>(
+  row: T,
+  index: number,
+  column: DataTableColumn<T>,
+): ReactNode {
+  if (column.cell) return column.cell(row, index);
+  const valeur = valeurDe(row, column);
+  return valeur === null || valeur === undefined ? null : String(valeur);
+}

package/dist/registry/package/components/DatePicker/index.tsx

@@ -40,6 +40,13 @@ function defaultFormat(value: string, locale: string) {
   return Number.isNaN(date.getTime()) ? value : new Intl.DateTimeFormat(locale, { day: "2-digit", month: "short", year: "numeric" }).format(date);
 }
 
+/**
+ * Une date, choisie au calendrier ou saisie au clavier.
+ *
+ * La valeur est une chaîne `AAAA-MM-JJ` : un objet `Date` porte une heure
+ * et un fuseau dont une date d'échéance n'a que faire, et qui la décalent
+ * d'un jour selon l'endroit d'où on la lit.
+ */
 export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(function DatePicker({
   id,
   name,

package/dist/registry/package/components/DateRangeFilter/index.tsx

@@ -5,4 +5,11 @@ import "./styles.css";
 
 export interface DateRangePreset { label: ReactNode; value: DateRangeValue; }
 export interface DateRangeFilterProps { value: DateRangeValue; onValueChange: (value: DateRangeValue) => void; presets?: DateRangePreset[]; onClear?: () => void; className?: string; }
+/**
+ * Une période, avec ses raccourcis.
+ *
+ * Les périodes utiles se comptent sur une main — ce mois, le trimestre,
+ * l'exercice — et les proposer évite de saisir deux dates pour la question
+ * que tout le monde pose en premier.
+ */
 export function DateRangeFilter({ value, onValueChange, presets = [], onClear, className }: DateRangeFilterProps) { return <section className={cn("sia-date-range-filter", className)}><div className="sia-date-range-filter__presets">{presets.map((preset, index) => <button type="button" key={index} onClick={() => onValueChange(preset.value)}>{preset.label}</button>)}</div><DateRangePicker value={value} onValueChange={onValueChange} />{onClear && (value.start || value.end) && <button type="button" className="sia-date-range-filter__clear" onClick={onClear}>Effacer</button>}</section>; }

package/dist/registry/package/components/DateRangePicker/index.tsx

@@ -21,6 +21,13 @@ export interface DateRangePickerProps extends Pick<CalendarProps, "locale" | "fi
   disabled?: boolean;
   className?: string;
 }
+/**
+ * Un début et une fin, choisis ensemble.
+ *
+ * Deux champs séparés laissent poser une fin antérieure au début, et il
+ * faut alors décider lequel des deux avait tort. Ici les deux bornes sont
+ * une seule valeur, et le calendrier les tient dans l'ordre.
+ */
 export function DateRangePicker({ value, defaultValue = { start: "", end: "" }, onValueChange, min, max, startLabel = "Date de début", endLabel = "Date de fin", allowClear = true, placement = "bottom-start", tone = "primary", invalid, disabled, locale = "fr-FR", firstDayOfWeek = 1, disabledDate, cellRender, showWeek, className }: DateRangePickerProps) {
   const anchorRef = useRef<HTMLButtonElement>(null);
   const [internal, setInternal] = useState(defaultValue);

package/dist/registry/package/components/DateTimePicker/index.tsx

@@ -23,6 +23,13 @@ export interface DateTimePickerProps {
   timeProps?: Omit<TimePickerProps, "value" | "defaultValue" | "onValueChange" | "tone" | "invalid" | "disabled">;
   className?: string;
 }
+/**
+ * Une date et une heure, dans un seul champ.
+ *
+ * `needConfirm` existe parce que l'heure se choisit après la date : sans
+ * validation explicite, le panneau se referme sur la date et l'heure reste
+ * celle de la veille.
+ */
 export function DateTimePicker({ value, defaultValue = { date: "", time: "" }, onValueChange, minuteStep = 1, secondStep = 1, showSeconds = false, hourFormat = 24, needConfirm = false, minDate, maxDate, tone = "primary", invalid, disabled, dateProps, timeProps, className }: DateTimePickerProps) {
   const [internal, setInternal] = useState(defaultValue);
   const current = value ?? internal;

package/dist/registry/package/components/Descriptions/index.tsx

@@ -4,4 +4,11 @@ import "./styles.css";
 
 export interface DescriptionItem { key: string; label: ReactNode; value: ReactNode; span?: 1 | 2 | 3; }
 export interface DescriptionsProps { items: DescriptionItem[]; title?: ReactNode; columns?: 1 | 2 | 3; bordered?: boolean; className?: string; }
+/**
+ * Des paires libellé / valeur, en colonnes.
+ *
+ * C'est la forme d'une fiche en lecture — ce qu'un formulaire montre quand
+ * il n'y a rien à saisir. `span` laisse une valeur longue occuper toute la
+ * ligne plutôt que d'être coupée dans une colonne étroite.
+ */
 export function Descriptions({ items, title, columns = 2, bordered = false, className }: DescriptionsProps) { return <section className={cn("sia-descriptions", bordered && "sia-descriptions--bordered", className)}>{title && <h3>{title}</h3>}<dl className={`sia-descriptions__grid sia-descriptions__grid--${columns}`}>{items.map((item) => <div key={item.key} style={{ gridColumn: `span ${item.span ?? 1}` }}><dt>{item.label}</dt><dd>{item.value}</dd></div>)}</dl></section>; }

package/dist/registry/package/components/Divider/index.tsx

@@ -7,6 +7,13 @@ export interface DividerProps extends HTMLAttributes<HTMLDivElement> {
   decorative?: boolean;
 }
 
+/**
+ * Un trait entre deux choses.
+ *
+ * `decorative` décide s'il compte pour un lecteur d'écran. Un trait qui
+ * sépare deux groupes de sens est une information; un trait qui aère ne
+ * l'est pas, et l'annoncer ajoute du bruit à chaque parcours.
+ */
 export function Divider({ orientation = "horizontal", decorative = true, className, ...props }: DividerProps) {
   return <div className={cn("sia-divider", `sia-divider--${orientation}`, className)} role={decorative ? "presentation" : "separator"} aria-orientation={decorative ? undefined : orientation} {...props} />;
 }

package/dist/registry/package/components/Drawer/index.tsx

@@ -46,6 +46,14 @@ export type DrawerComponent = ForwardRefExoticComponent<
   Close: typeof DrawerClose;
 };
 
+/**
+ * Un panneau qui entre par un bord.
+ *
+ * Il sert là où une boîte modale serait trop : un filtre qu'on ajuste en
+ * regardant la liste derrière, un formulaire qu'on remplit sans perdre sa
+ * place. Le focus y est enfermé tant qu'il est ouvert, comme dans un
+ * modal — sans quoi la tabulation continue dans la page cachée.
+ */
 export const Drawer = forwardRef<DrawerRef, IDrawerProps>(
   (
     {

package/dist/registry/package/components/DurationDisplay/index.tsx

@@ -1,3 +1,9 @@
 import { cn } from "@sia-ui/utils";
 export interface DurationDisplayProps { milliseconds: number; locale?: string; style?: "short" | "long" | "clock"; className?: string; }
+/**
+ * Une durée, en mots ou en pendule.
+ *
+ * Trois styles pour trois usages : `clock` pour un chronomètre qu'on lit en
+ * continu, `short` pour une colonne de tableau, `long` pour une phrase.
+ */
 export function DurationDisplay({ milliseconds, locale = "fr-FR", style = "short", className }: DurationDisplayProps) { const totalSeconds = Math.max(0, Math.floor(milliseconds / 1000)); const hours = Math.floor(totalSeconds / 3600); const minutes = Math.floor((totalSeconds % 3600) / 60); const seconds = totalSeconds % 60; if (style === "clock") return <span className={cn("sia-duration-display", className)}>{[hours, minutes, seconds].map((value) => String(value).padStart(2, "0")).join(":")}</span>; const formatter = new Intl.NumberFormat(locale); const parts = [[hours, style === "long" ? "heure" : "h"], [minutes, style === "long" ? "minute" : "min"], [seconds, style === "long" ? "seconde" : "s"]] as const; return <span className={cn("sia-duration-display", className)}>{parts.filter(([value]) => value > 0).map(([value, unit]) => `${formatter.format(value)} ${unit}${style === "long" && value > 1 ? "s" : ""}`).join(" ") || `0 ${style === "long" ? "seconde" : "s"}`}</span>; }

package/dist/registry/package/components/EmptyState/index.tsx

@@ -11,6 +11,13 @@ export interface EmptyStateProps {
   className?: string;
 }
 
+/**
+ * Ce qu'on montre quand il n'y a rien.
+ *
+ * Une liste vide sans explication ressemble à un chargement bloqué. Elle
+ * porte donc une action : le vide initial est le meilleur moment pour
+ * proposer de créer le premier élément.
+ */
 export function EmptyState({ icon, title, description, action, compact, className }: EmptyStateProps) {
   return (
     <section className={cn("sia-empty-state", compact && "sia-empty-state--compact", className)}>

package/dist/registry/package/components/EntityMeta/index.tsx

@@ -32,6 +32,13 @@ function Detail({
   );
 }
 
+/**
+ * Les traces d'un objet : créé le, modifié par, identifiant.
+ *
+ * L'identifiant est normalisé pour être lu à voix haute au téléphone —
+ * c'est la première chose qu'on demande à un client, et une chaîne de
+ * trente-six caractères ne se dicte pas.
+ */
 export function EntityMeta({
   createdAt,
   updatedAt,

package/dist/registry/package/components/ErrorState/index.tsx

@@ -21,6 +21,14 @@ function getErrorMessage(error: unknown): string | undefined {
   return undefined;
 }
 
+/**
+ * Un échec, et de quoi en sortir.
+ *
+ * `error` accepte n'importe quoi : une `Error`, une réponse HTTP, une
+ * chaîne. Ce qui arrive d'un appel réseau n'a pas de forme garantie, et
+ * exiger un type ferait écrire un `try` autour de chaque affichage
+ * d'erreur.
+ */
 export function ErrorState({ title: titleProp, description, error, action, onRetry, retryLabel: retryLabelProp, compact, className }: ErrorStateProps) {
     const locale = useSiaLocale();
     const retryLabel = retryLabelProp ?? locale.retry;

package/dist/registry/package/components/EventCalendar/index.tsx

@@ -4,5 +4,12 @@ import "./styles.css";
 
 export interface CalendarEvent { id: string; date: string; title: string; tone?: ComponentTone; }
 export interface EventCalendarProps extends Omit<CalendarProps, "renderDay"> { events: CalendarEvent[]; maxEventsPerDay?: number; onEventClick?: (event: CalendarEvent) => void; }
+/**
+ * Un calendrier qui porte des événements.
+ *
+ * `maxEventsPerDay` plafonne l'affichage : une journée à douze rendez-vous
+ * déformerait toute la grille, et les douze ne se lisent de toute façon pas
+ * dans une case de calendrier.
+ */
 export function EventCalendar({ events, maxEventsPerDay = 2, onEventClick, ...props }: EventCalendarProps) { const renderDay = (day: CalendarDay) => { const matches = events.filter((event) => event.date === day.date).slice(0, maxEventsPerDay); return <span className="sia-event-calendar__events">{matches.map((event) => <button type="button" key={event.id} className={`sia-event-calendar__event sia-event-calendar__event--${event.tone ?? "primary"}`} onClick={() => onEventClick?.(event)}>{event.title}</button>)}</span>; }; return <Calendar {...props} className={cnEvent(props.className)} renderDay={renderDay} />; }
 function cnEvent(className?: string) { return ["sia-event-calendar", className].filter(Boolean).join(" "); }

package/dist/registry/package/components/Field/index.tsx

@@ -559,6 +559,18 @@ function pick<K extends string, V>(key: K, value: V | undefined) {
   return (value === undefined ? {} : { [key]: value }) as { [P in K]?: V };
 }
 
+/**
+ * Le champ, et tout ce qui l'entoure.
+ *
+ * Un libellé, un contrôle, un message d'erreur, et les attributs qui les
+ * relient — `id`, `aria-describedby`, `aria-invalid`. Ce câblage est
+ * toujours le même et toujours oublié quelque part : ici il est fait une
+ * fois.
+ *
+ * `type` choisit le contrôle parmi les vingt-sept que la bibliothèque
+ * fournit. Le champ ne les réimplémente pas : il les monte et leur passe le
+ * branchement.
+ */
 export function Field(rawProps: FieldProps) {
   const props = applyBinding(rawProps);
   const {

package/dist/registry/package/components/FileUpload/index.tsx

@@ -15,6 +15,13 @@ export interface FileUploadProps extends Omit<
   description?: string;
   onFilesChange?: (files: File[]) => void;
 }
+/**
+ * Un dépôt de fichiers, par clic ou par glisser.
+ *
+ * Le glisser-déposer seul exclut le clavier et le tactile; le bouton seul
+ * ignore le geste que tout le monde essaie d'abord. Les deux mènent au même
+ * champ natif.
+ */
 export function FileUpload({
   label = "Ajouter des fichiers",
   description = "Glissez les fichiers ici ou parcourez votre appareil.",

package/dist/registry/package/components/FiltersBar/index.tsx

@@ -13,6 +13,13 @@ export interface FiltersBarProps {
   className?: string;
 }
 
+/**
+ * La barre au-dessus d'une liste : recherche, filtres, actions.
+ *
+ * `activeCount` affiche combien de filtres sont en vigueur. Sans ce compte,
+ * une liste filtrée ressemble à une liste vide, et l'on cherche la panne
+ * avant de penser au filtre posé la veille.
+ */
 export function FiltersBar({ search, filters, actions, activeCount = 0, onReset, resetLabel: resetLabelProp, className }: FiltersBarProps) {
     const locale = useSiaLocale();
     const resetLabel = resetLabelProp ?? locale.reset;

package/dist/registry/package/components/HoverCard/index.tsx

@@ -1,14 +1,12 @@
 import {
   cloneElement,
   isValidElement,
-  useCallback,
-  useEffect,
   useRef,
-  useState,
   type ReactElement,
   type ReactNode,
 } from "react";
 import { cn } from "@sia-ui/utils";
+import { useHoverIntent } from "@sia-ui/headless";
 import { Overlay, type OverlayPlacement } from "../Overlay";
 import "./styles.css";
 
@@ -48,49 +46,29 @@ export function HoverCard({
   className,
 }: HoverCardProps) {
   const anchorRef = useRef<HTMLElement>(null);
-  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
-  const [internalOpen, setInternalOpen] = useState(false);
-  const open = openProp ?? internalOpen;
 
-  const setOpen = useCallback(
-    (next: boolean) => {
-      if (openProp === undefined) setInternalOpen(next);
-      onOpenChange?.(next);
-    },
-    [onOpenChange, openProp],
-  );
-
-  const schedule = useCallback(
-    (next: boolean, delay: number) => {
-      if (timer.current) clearTimeout(timer.current);
-      timer.current = setTimeout(() => setOpen(next), delay);
-    },
-    [setOpen],
-  );
-
-  useEffect(
-    () => () => {
-      if (timer.current) clearTimeout(timer.current);
-    },
-    [],
-  );
+  // Les deux délais vivent dans `@sia-ui/headless` : le volet de navigation
+  // du `Sidebar` pose exactement la même question, et deux réglages qui
+  // divergent donnent deux sensations différentes dans la même application.
+  const { open, triggerProps, panelProps, setOpen } = useHoverIntent({
+    openDelay,
+    closeDelay,
+    ...(openProp !== undefined ? { open: openProp } : {}),
+    ...(onOpenChange ? { onOpenChange } : {}),
+  });
 
   const trigger = isValidElement(children)
     ? cloneElement(children, {
         ref: anchorRef,
-        // Le focus ouvre aussi : au clavier il n'y a pas de survol, et une
-        // fiche qu'on ne peut atteindre qu'à la souris n'existe pas pour
-        // tout le monde.
+        ...triggerProps,
         onFocus: () => {
           children.props.onFocus?.();
-          schedule(true, 0);
+          triggerProps.onFocus();
         },
-        onBlur: () => schedule(false, closeDelay),
         onMouseEnter: () => {
           children.props.onMouseEnter?.();
-          schedule(true, openDelay);
+          triggerProps.onMouseEnter();
         },
-        onMouseLeave: () => schedule(false, closeDelay),
       } as never)
     : children;
 
@@ -110,8 +88,7 @@ export function HoverCard({
           className="sia-hover-card__body"
           // Survoler le panneau le maintient ouvert : sans cela il se ferme
           // dès que la souris quitte le déclencheur pour y aller.
-          onMouseEnter={() => schedule(true, 0)}
-          onMouseLeave={() => schedule(false, closeDelay)}
+          {...panelProps}
         >
           {content}
         </div>

package/dist/registry/package/components/IconButton/index.tsx

@@ -13,6 +13,14 @@ export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>
   tooltip?: Omit<TooltipProps, "children">;
 }
 
+/**
+ * Une action réduite à son icône.
+ *
+ * `label` est obligatoire : une icône seule n'a pas de nom, et un lecteur
+ * d'écran annoncerait « bouton » sans dire lequel. Le libellé sert aussi
+ * d'infobulle — ce que l'icône signifie doit rester atteignable à la
+ * souris comme au clavier.
+ */
 export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(
   ({ label, icon, variant: variantProp, size: sizeProp, radius: radiusProp, tooltip, className, type = "button", ...props }, ref) => {
     const defaults = useComponentDefaults<IconButtonProps>("iconButton");

package/dist/registry/package/components/Icons/index.tsx

@@ -1,3 +1,18 @@
+/**
+ * Le jeu d'icônes commun.
+ *
+ * Il n'a pas de composant principal : c'est une collection, et chaque icône y
+ * est une fonction. Toutes passent par le même socle — un trait de 1,8, des
+ * extrémités arrondies, une taille en `em` qui suit celle du texte, et un
+ * `aria-hidden` d'office. Une icône ne porte jamais de sens à elle seule;
+ * c'est le libellé à côté qui le porte.
+ *
+ * Ce jeu couvre ce dont la bibliothèque a besoin, et rien de plus. Un produit
+ * qui veut sa propre iconographie passe ses icônes en props plutôt que
+ * d'étendre celle-ci : embarquer trois cents dessins pour en servir douze
+ * pèserait sur tous les projets.
+ */
+
 import type { SVGProps } from "react";
 
 type IconProps = SVGProps<SVGSVGElement>;

package/dist/registry/package/components/ImageUpload/index.tsx

@@ -3,4 +3,11 @@ import { FileUpload, type FileUploadProps } from "../FileUpload";
 import { cn } from "@sia-ui/utils";
 import "./styles.css";
 export interface ImageUploadProps extends Omit<FileUploadProps, "accept" | "onFilesChange"> { accept?: string; value?: string; onValueChange?: (file: File | null, previewUrl?: string) => void; previewAlt?: string; }
+/**
+ * Un dépôt de fichier qui montre ce qu'on vient de choisir.
+ *
+ * L'aperçu est local, construit avant tout envoi : attendre le retour du
+ * serveur pour afficher l'image laisse un carré vide au moment précis où
+ * l'on veut vérifier qu'on n'a pas pris la mauvaise.
+ */
 export function ImageUpload({ accept = "image/*", value, onValueChange, previewAlt = "Aperçu de l'image", className, ...props }: ImageUploadProps) { const [preview, setPreview] = useState(value); useEffect(() => setPreview(value), [value]); useEffect(() => () => { if (preview?.startsWith("blob:")) URL.revokeObjectURL(preview); }, [preview]); const select = (files: File[]) => { const file = files[0]; if (!file) return; const next = URL.createObjectURL(file); setPreview(next); onValueChange?.(file, next); }; return <div className={cn("sia-image-upload", className)}>{preview && <div className="sia-image-upload__preview"><img src={preview} alt={previewAlt} /><button type="button" onClick={() => { setPreview(undefined); onValueChange?.(null); }}>Supprimer</button></div>}<FileUpload {...props} accept={accept} multiple={false} onFilesChange={select} /></div>; }

package/dist/registry/package/components/Input/index.tsx

@@ -23,6 +23,13 @@ export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
   radius?: "default" | "none" | "sm" | "lg" | "full";
 }
 
+/**
+ * La saisie d'une ligne de texte.
+ *
+ * `left` et `right` accueillent ce qui accompagne la valeur — une unité,
+ * une icône de recherche, un bouton de réinitialisation — à l'intérieur du
+ * cadre. Posés à côté, ils s'en désalignent dès que la taille change.
+ */
 export const Input = forwardRef<HTMLInputElement, InputProps>(
   (
     {

package/dist/registry/package/components/JsonEditor/index.tsx

@@ -3,4 +3,11 @@ import { Textarea } from "../Textarea";
 import { cn } from "@sia-ui/utils";
 import "./styles.css";
 export interface JsonEditorProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "defaultValue" | "onChange"> { value?: string; defaultValue?: string; onValueChange?: (value: string, parsed: unknown | undefined) => void; formatOnBlur?: boolean; }
+/**
+ * Une zone de saisie qui connaît la forme de ce qu'on y écrit.
+ *
+ * Elle signale une syntaxe invalide pendant la frappe et rend l'objet
+ * analysé à côté du texte : l'appelant reçoit donc les deux, et n'a pas à
+ * refaire un `JSON.parse` dans un `try`.
+ */
 export function JsonEditor({ value, defaultValue = "{}", onValueChange, formatOnBlur = true, className, ...props }: JsonEditorProps) { const [internal, setInternal] = useState(defaultValue); const current = value ?? internal; const result = useMemo(() => { try { return { valid: true, parsed: JSON.parse(current) as unknown }; } catch { return { valid: false, parsed: undefined }; } }, [current]); const update = (next: string) => { let parsed: unknown | undefined; try { parsed = JSON.parse(next) as unknown; } catch { parsed = undefined; } if (value === undefined) setInternal(next); onValueChange?.(next, parsed); }; return <div className={cn("sia-code-editor", className)}><Textarea {...props} value={current} invalid={!result.valid} resize="vertical" spellCheck={false} onChange={(event) => update(event.target.value)} onBlur={(event) => { if (formatOnBlur && result.valid) update(JSON.stringify(result.parsed, null, 2)); props.onBlur?.(event); }} /><small className={result.valid ? "is-valid" : "is-invalid"}>{result.valid ? "JSON valide" : "JSON invalide"}</small></div>; }

package/dist/registry/package/components/KpiGrid/index.tsx

@@ -6,6 +6,13 @@ export interface KpiGridProps extends HTMLAttributes<HTMLDivElement> {
   columns?: 1 | 2 | 3 | 4;
 }
 
+/**
+ * Une rangée d'indicateurs.
+ *
+ * Le nombre de colonnes est déclaré, pas déduit du nombre de cartes : trois
+ * indicateurs sur quatre colonnes laissent un trou, et ce trou dit qu'il
+ * manque une donnée.
+ */
 export function KpiGrid({ columns = 4, className, ...props }: KpiGridProps) {
   return <div className={cn("sia-kpi-grid", `sia-kpi-grid--${columns}`, className)} {...props} />;
 }

package/dist/registry/package/components/Label/index.tsx

@@ -16,6 +16,13 @@ export interface LabelProps
 /** Alias historique, attendu par les composants venus du registre. */
 export type ILabelProps = LabelProps;
 
+/**
+ * Le nom d'un champ.
+ *
+ * L'astérisque d'obligation est portée par une prop plutôt qu'écrite dans
+ * le texte : elle reçoit ainsi un `aria-hidden`, et le champ est annoncé
+ * « obligatoire » plutôt que « nom étoile ».
+ */
 export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
   ({ className, children, required, muted, tone, ...props }, ref) => {
     return (