@sia-ui/cli 0.2.2 → 0.3.1

package/dist/registry/package/components/AppShell/tab-bar.tsx

@@ -0,0 +1,134 @@
+import { memo, type ReactNode } from "react";
+import { cn } from "@sia-ui/utils";
+import { navLeaves, navSome } from "@sia-ui/headless";
+import type { SidebarItem, SidebarRenderLink } from "../Sidebar";
+
+export interface BottomTabsProps {
+  /** Attendu déjà filtré : la coquille a fait le tri une seule fois. */
+  items: SidebarItem[];
+  activeKey?: string;
+
+  /**
+   * Nombre d'onglets avant le bouton « Plus ».
+   *
+   * Quatre au maximum sur un téléphone : au-delà, les cibles tactiles
+   * descendent sous les quarante-quatre pixels recommandés, et on rate
+   * l'onglet voisin une fois sur trois.
+   */
+  max?: number;
+
+  renderLink?: SidebarRenderLink;
+  onNavigate?: (item: SidebarItem) => void;
+
+  /** Le bouton qui ouvre l'arborescence complète. */
+  more?: ReactNode;
+  onMore?: () => void;
+  moreLabel?: string;
+
+  className?: string;
+}
+
+/**
+ * La navigation d'un téléphone.
+ *
+ * Un rail d'icônes muettes n'est pas utilisable au comptoir : sur petit écran
+ * la navigation descend en bas, à portée du pouce, avec des libellés.
+ *
+ * Les onglets ne montrent que des **feuilles**. Un onglet qui ouvrirait un
+ * sous-menu depuis une barre basse serait un piège tactile — on vise une
+ * destination, on obtient un menu. Le reste de l'arborescence passe par
+ * « Plus ».
+ */
+export const BottomTabs = memo(function BottomTabs({
+  items,
+  activeKey,
+  max = 4,
+  renderLink,
+  onNavigate,
+  more,
+  onMore,
+  moreLabel = "Plus",
+  className,
+}: BottomTabsProps) {
+  const feuilles = navLeaves(items);
+  const onglets = feuilles.slice(0, max);
+  const reste = feuilles.length - onglets.length;
+  const afficherPlus = reste > 0 || Boolean(onMore);
+
+  return (
+    <nav className={cn("sia-bottom-tabs", className)} aria-label="Navigation principale">
+      {onglets.map((item) => {
+        const actif = item.key === activeKey;
+        const contenu = (
+          <>
+            <span className="sia-bottom-tabs__pastille" aria-hidden="true">
+              {item.icon}
+              {navSome(item, (e) => e.badge !== undefined && e.badge !== null) && (
+                <span className="sia-bottom-tabs__point" />
+              )}
+            </span>
+            <span className="sia-bottom-tabs__label">{item.label}</span>
+          </>
+        );
+
+        const classe = cn("sia-bottom-tabs__item", actif && "sia-bottom-tabs__item--active");
+        const naviguer = () => {
+          item.onClick?.();
+          onNavigate?.(item);
+        };
+
+        if (item.href && renderLink) {
+          return (
+            <span key={item.key} className="sia-bottom-tabs__cell">
+              {renderLink({
+                item,
+                children: contenu,
+                props: {
+                  className: classe,
+                  onClick: naviguer,
+                  ...(actif ? { "aria-current": "page" as const } : {}),
+                },
+              })}
+            </span>
+          );
+        }
+
+        return item.href ? (
+          <a
+            key={item.key}
+            href={item.href}
+            className={classe}
+            {...(actif ? { "aria-current": "page" as const } : {})}
+            onClick={naviguer}
+          >
+            {contenu}
+          </a>
+        ) : (
+          <button
+            key={item.key}
+            type="button"
+            className={classe}
+            {...(actif ? { "aria-current": "page" as const } : {})}
+            onClick={naviguer}
+          >
+            {contenu}
+          </button>
+        );
+      })}
+
+      {afficherPlus && (
+        <button
+          type="button"
+          className="sia-bottom-tabs__item"
+          onClick={onMore}
+          aria-label={`${moreLabel}${reste > 0 ? ` (${reste})` : ""}`}
+        >
+          <span className="sia-bottom-tabs__pastille" aria-hidden="true">
+            {more ?? "···"}
+          </span>
+          <span className="sia-bottom-tabs__label">{moreLabel}</span>
+        </button>
+      )}
+    </nav>
+  );
+});

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

@@ -14,6 +14,13 @@ export interface AsyncStateProps {
   children: ReactNode;
 }
 
+/**
+ * Les trois états d'un chargement, au même endroit.
+ *
+ * En attente, en erreur, ou vide : ce sont les mêmes trois cas à chaque
+ * écran, et les écrire à la main en oublie toujours un — le plus souvent le
+ * vide, qui ressemble à un chargement qui n'en finit pas.
+ */
 export function AsyncState({ loading, error, empty, emptyTitle = "No data", emptyDescription, onRetry, children }: AsyncStateProps) {
   if (loading) return <div className="sia-async-state" role="status"><span className="sia-spinner" /><span>Loading...</span></div>;
   if (error) return <Alert tone="danger" title="Unable to load data" action={onRetry && <Button variant="outline" onClick={onRetry}>Retry</Button>}>{error}</Alert>;

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

@@ -17,6 +17,14 @@ export interface AuditMetaProps {
   className?: string;
 }
 
+/**
+ * Qui a fait quoi, et quand.
+ *
+ * Une liste d'événements plutôt qu'un dernier état : savoir qu'une facture
+ * a été validée n'apprend rien si l'on ignore qu'elle avait été rejetée la
+ * veille. Les dates sont relatives — « il y a deux jours » se compare sans
+ * calcul mental.
+ */
 export function AuditMeta({ events, locale = "fr-FR", title = "Historique", emptyLabel = "Aucune activité", className }: AuditMetaProps) {
   return (
     <section className={cn("sia-audit-meta", className)}>

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

@@ -11,6 +11,13 @@ export interface AuthLayoutProps {
   footer?: ReactNode;
   className?: string;
 }
+/**
+ * La page qui précède l'application : connexion, inscription, mot de passe
+ * oublié.
+ *
+ * Elle n'a ni navigation ni coquille, et c'est délibéré : tout ce qui mène
+ * ailleurs est hors de portée de quelqu'un qui n'est pas encore entré.
+ */
 export function AuthLayout({
   title,
   description,

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

@@ -3,6 +3,13 @@ import { cn } from "@sia-ui/utils";
 import type { SelectOption } from "../Select";
 import { useSiaLocale } from "@sia-ui/headless";
 export interface AutocompleteProps { id?: string; options: SelectOption[]; value?: string; defaultValue?: string; onValueChange?: (value: string, option?: SelectOption) => void; placeholder?: string; allowCustomValue?: boolean; disabled?: boolean; className?: string; "aria-describedby"?: string; "aria-labelledby"?: string; "aria-invalid"?: boolean; "aria-required"?: boolean; }
+/**
+ * Un champ qui propose, sans imposer.
+ *
+ * `allowCustomValue` est vrai par défaut : la liste aide à trouver, elle ne
+ * dit pas ce qui existe. Un nom de client absent du référentiel reste
+ * saisissable, quitte à être créé ensuite.
+ */
 export function Autocomplete({ id, options, value, defaultValue = "", onValueChange, placeholder: placeholderProp, allowCustomValue = true, disabled, className, ...ariaProps }: AutocompleteProps) {
     const locale = useSiaLocale();
     const placeholder = placeholderProp ?? locale.searchPlaceholder; const initialLabel = options.find((option) => option.value === defaultValue)?.label; const [internal, setInternal] = useState(defaultValue); const [query, setQuery] = useState(initialLabel ? String(initialLabel) : defaultValue); const [open, setOpen] = useState(false); const current = value ?? internal; const filtered = useMemo(() => { const needle = query.toLowerCase(); return options.filter((option) => [String(option.label), ...(option.keywords ?? [])].join(" ").toLowerCase().includes(needle)); }, [options, query]); const select = (option: SelectOption) => { if (value === undefined) setInternal(option.value); setQuery(String(option.label)); setOpen(false); onValueChange?.(option.value, option); }; return <div id={id} className={cn("sia-autocomplete", className)} {...ariaProps}><input value={query} placeholder={placeholder} disabled={disabled} role="combobox" aria-expanded={open} aria-controls={`${id ?? "sia-autocomplete"}-list`} onFocus={() => setOpen(true)} onChange={(event) => { const next = event.target.value; setQuery(next); setOpen(true); if (allowCustomValue) { if (value === undefined) setInternal(next); onValueChange?.(next); } }} onBlur={() => window.setTimeout(() => setOpen(false), 120)} />{open && <div id={`${id ?? "sia-autocomplete"}-list`} role="listbox">{filtered.map((option) => <button type="button" role="option" aria-selected={current === option.value} key={option.value} disabled={option.disabled} onMouseDown={(event) => event.preventDefault()} onClick={() => select(option)}>{option.label}</button>)}</div>}</div>; }

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

@@ -1,23 +1,344 @@
-import { useState, type ImgHTMLAttributes } from "react";
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useState,
+  type HTMLAttributes,
+  type ImgHTMLAttributes,
+  type ReactNode,
+} from "react";
 import { cn } from "@sia-ui/utils";
 import "./styles.css";
 
-export interface AvatarProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "children"> {
-  name: string;
-  size?: "sm" | "md" | "lg";
-  fallback?: string;
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type AvatarShape = "circle" | "rounded" | "square";
+export type AvatarVariant = "soft" | "solid" | "outline";
+
+/**
+ * La présence d'une personne.
+ *
+ * Quatre états et pas davantage : au-delà, la pastille devient un code que
+ * personne ne retient, et il faut une légende pour la lire.
+ */
+export type AvatarStatus = "online" | "offline" | "busy" | "away";
+
+const LIBELLES_STATUT: Record<AvatarStatus, string> = {
+  online: "en ligne",
+  offline: "hors ligne",
+  busy: "occupé",
+  away: "absent",
+};
+
+/**
+ * Les teintes dérivées du nom.
+ *
+ * Deux personnes aux mêmes initiales doivent se distinguer : dans une liste
+ * de participants, six pastilles identiques ne valent pas mieux qu'aucune.
+ * La couleur est donc déterministe — la même personne garde la sienne d'un
+ * écran à l'autre, d'une session à l'autre.
+ */
+const TEINTES = [
+  "primary",
+  "info",
+  "success",
+  "warning",
+  "danger",
+  "secondary",
+] as const;
+
+export type AvatarTint = (typeof TEINTES)[number];
+
+/**
+ * Une empreinte stable, calculée sur le nom.
+ *
+ * Volontairement minuscule : cette fonction tourne pour chaque avatar d'une
+ * liste qui peut en compter des centaines. Un hachage cryptographique y
+ * coûterait mille fois plus pour un résultat visuellement identique.
+ */
+function empreinte(texte: string): number {
+  let h = 0;
+  for (let i = 0; i < texte.length; i += 1) {
+    h = (h * 31 + texte.charCodeAt(i)) | 0;
+  }
+  return Math.abs(h);
+}
+
+export function tintForName(name: string): AvatarTint {
+  return TEINTES[empreinte(name) % TEINTES.length]!;
+}
+
+/**
+ * Les initiales d'un nom.
+ *
+ * Première et dernière partie plutôt que les deux premières : « Jean-Baptiste
+ * Kouassi Mbella » se lit « JM », pas « JK ». Les particules sont écartées,
+ * sinon « Marie de la Tour » donnerait « MD ».
+ */
+const PARTICULES = new Set([
+  "de", "du", "des", "la", "le", "les", "van", "von", "da", "di", "el", "al",
+]);
+
+export function initialsOf(name: string, count = 2): string {
+  const parts = name
+    .trim()
+    .split(/[\s'-]+/)
+    .filter((p) => p.length > 0 && !PARTICULES.has(p.toLowerCase()));
+
+  if (parts.length === 0) return "";
+  if (parts.length === 1 || count === 1) {
+    return (parts[0]!.slice(0, count) || "").toUpperCase();
+  }
+
+  return (
+    (parts[0]![0] ?? "") + (parts[parts.length - 1]![0] ?? "")
+  ).toUpperCase();
 }
 
-function getInitials(name: string) {
-  return name.trim().split(/\s+/).slice(0, 2).map((part) => part[0]?.toUpperCase() ?? "").join("");
+interface AvatarGroupContextValue {
+  size: AvatarSize;
+  shape: AvatarShape;
+  variant: AvatarVariant;
 }
 
-export function Avatar({ name, size = "md", fallback, className, src, alt, onError, ...props }: AvatarProps) {
-  const [failed, setFailed] = useState(false);
+const AvatarGroupContext = createContext<AvatarGroupContextValue | null>(null);
+
+export interface AvatarProps
+  extends Omit<ImgHTMLAttributes<HTMLImageElement>, "children" | "width" | "height"> {
+  /** Le nom de la personne : il sert au repli, à la couleur et à l'annonce. */
+  name: string;
+
+  size?: AvatarSize;
+  shape?: AvatarShape;
+  variant?: AvatarVariant;
+
+  /** Force la teinte au lieu de la dériver du nom. */
+  tint?: AvatarTint;
+
+  /** Remplace les initiales — une icône, un emoji, deux lettres à soi. */
+  fallback?: ReactNode;
+
+  /** Nombre d'initiales quand le repli est automatique. */
+  initials?: 1 | 2;
+
+  status?: AvatarStatus;
+  /** Le libellé du statut, pour les lecteurs d'écran. */
+  statusLabel?: string;
+
+  /** Un liseré qui détache l'avatar de son fond. */
+  ring?: boolean;
+
+  /** Rend l'avatar actionnable — un menu de compte, par exemple. */
+  onPress?: () => void;
+}
+
+/**
+ * Le portrait d'une personne, ou ce qui le remplace.
+ *
+ * Une image met du temps à arriver, échoue parfois, et manque souvent. Les
+ * trois cas sont traités sans que la mise en page bouge : l'espace est réservé
+ * d'emblée, le repli est peint dessous, et l'image se fond par-dessus quand
+ * elle arrive.
+ */
+export function Avatar({
+  name,
+  size,
+  shape,
+  variant,
+  tint,
+  fallback,
+  initials = 2,
+  status,
+  statusLabel,
+  ring = false,
+  onPress,
+  className,
+  src,
+  alt,
+  onError,
+  onLoad,
+  style,
+  ...props
+}: AvatarProps) {
+  const groupe = useContext(AvatarGroupContext);
+  const [etatImage, setEtatImage] = useState<"attente" | "prete" | "echouee">(
+    src ? "attente" : "echouee",
+  );
+
+  const resolvedSize = size ?? groupe?.size ?? "md";
+  const resolvedShape = shape ?? groupe?.shape ?? "circle";
+  const resolvedVariant = variant ?? groupe?.variant ?? "soft";
+
+  // Le nom ne change pas à chaque rendu, le hachage non plus : dans une liste
+  // de cent participants, c'est cent calculs évités par frappe au clavier.
+  const teinte = useMemo(() => tint ?? tintForName(name), [name, tint]);
+  const lettres = useMemo(
+    () => (fallback === undefined ? initialsOf(name, initials) : null),
+    [fallback, initials, name],
+  );
+
+  const classe = cn(
+    "sia-avatar",
+    `sia-avatar--${resolvedSize}`,
+    `sia-avatar--${resolvedShape}`,
+    `sia-avatar--${resolvedVariant}`,
+    `sia-avatar--tint-${teinte}`,
+    ring && "sia-avatar--ring",
+    etatImage === "attente" && "sia-avatar--loading",
+    onPress && "sia-avatar--pressable",
+    className,
+  );
+
+  const contenu = (
+    <>
+      {/* Le repli est toujours peint, sous l'image. C'est lui qui tient la
+          place pendant le chargement, et qui reste si l'image échoue —
+          aucune bascule, donc aucun saut. */}
+      <span className="sia-avatar__fallback" aria-hidden="true">
+        {fallback ?? lettres}
+      </span>
+
+      {src && etatImage !== "echouee" && (
+        <img
+          {...props}
+          className="sia-avatar__image"
+          src={src}
+          alt={alt ?? ""}
+          loading="lazy"
+          decoding="async"
+          onLoad={(event) => {
+            setEtatImage("prete");
+            onLoad?.(event);
+          }}
+          onError={(event) => {
+            setEtatImage("echouee");
+            onError?.(event);
+          }}
+        />
+      )}
+
+      {status && (
+        <span
+          className={cn("sia-avatar__status", `sia-avatar__status--${status}`)}
+          aria-hidden="true"
+        />
+      )}
+
+      {/* Le nom n'est jamais dans l'image : un `alt` vide et un texte masqué
+          annoncent la personne une seule fois, statut compris. */}
+      <span className="sia-visually-hidden">
+        {name}
+        {status ? ` — ${statusLabel ?? LIBELLES_STATUT[status]}` : ""}
+      </span>
+    </>
+  );
+
+  if (onPress) {
+    return (
+      <button
+        type="button"
+        className={classe}
+        title={name}
+        onClick={onPress}
+        {...(style ? { style } : {})}
+      >
+        {contenu}
+      </button>
+    );
+  }
+
   return (
-    <span className={cn("sia-avatar", `sia-avatar--${size}`, className)} title={name}>
-      {src && !failed ? <img src={src} alt={alt ?? name} onError={(event) => { setFailed(true); onError?.(event); }} {...props} /> : <span aria-hidden="true">{fallback ?? getInitials(name)}</span>}
-      {!src || failed ? <span className="sia-visually-hidden">{name}</span> : null}
+    <span className={classe} title={name} {...(style ? { style } : {})}>
+      {contenu}
     </span>
   );
 }
+
+export interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+
+  /**
+   * Au-delà, les suivants sont résumés par un compteur.
+   *
+   * Sans limite, une réunion de quarante personnes déborde de sa ligne et
+   * n'apprend plus rien : au-delà de cinq visages, on ne lit plus des gens,
+   * on lit une foule.
+   */
+  max?: number;
+
+  size?: AvatarSize;
+  shape?: AvatarShape;
+  variant?: AvatarVariant;
+
+  /** Le chevauchement, de 0 (côte à côte) à 1 (fortement empilés). */
+  overlap?: number;
+
+  /** Écarte les avatars au survol, pour les distinguer. */
+  spreadOnHover?: boolean;
+
+  /** Ce qu'affiche le compteur. Par défaut `+N`. */
+  renderOverflow?: (count: number) => ReactNode;
+}
+
+/**
+ * Plusieurs personnes, sur une ligne.
+ *
+ * Les avatars se chevauchent — c'est ce qui dit « un groupe » plutôt qu'« une
+ * liste ». Chacun porte un liseré de la couleur du fond, sans quoi la pile
+ * devient une bouillie dès que deux teintes se ressemblent.
+ */
+export function AvatarGroup({
+  children,
+  max,
+  size = "md",
+  shape = "circle",
+  variant = "soft",
+  overlap = 0.25,
+  spreadOnHover = false,
+  renderOverflow,
+  className,
+  style,
+  ...props
+}: AvatarGroupProps) {
+  const tous = Array.isArray(children) ? children : [children];
+  const visibles = max === undefined ? tous : tous.slice(0, max);
+  const reste = tous.length - visibles.length;
+
+  const contexte = useMemo(
+    () => ({ size, shape, variant }),
+    [shape, size, variant],
+  );
+
+  return (
+    <AvatarGroupContext.Provider value={contexte}>
+      <div
+        className={cn(
+          "sia-avatar-group",
+          `sia-avatar-group--${size}`,
+          spreadOnHover && "sia-avatar-group--spread",
+          className,
+        )}
+        style={{
+          ...style,
+          "--sia-avatar-overlap": String(Math.min(Math.max(overlap, 0), 1)),
+        } as Record<string, string>}
+        {...props}
+      >
+        {visibles}
+        {reste > 0 && (
+          <span
+            className={cn(
+              "sia-avatar",
+              `sia-avatar--${size}`,
+              `sia-avatar--${shape}`,
+              "sia-avatar--overflow",
+            )}
+          >
+            <span className="sia-avatar__fallback">
+              {renderOverflow ? renderOverflow(reste) : `+${reste}`}
+            </span>
+          </span>
+        )}
+      </div>
+    </AvatarGroupContext.Provider>
+  );
+}