@zevra/ui 0.3.2 → 0.5.0

package/react/data.tsx

@@ -0,0 +1,300 @@
+// Données — tableau en grille, listes, métadonnées, clé-valeur, vignettes.
+//
+// Le tableau du système n'est PAS un <table> : c'est une grille CSS, parce
+// qu'une même rangée doit se rendre en colonnes au-dessus du point de rupture
+// et en carte empilée en dessous, sans dupliquer le balisage. `Unwrap` est la
+// primitive qui rend cela possible.
+
+import type { AnchorHTMLAttributes, CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import { cx } from './cx.js'
+
+type Div = Omit<HTMLAttributes<HTMLDivElement>, 'className'>
+type Span = Omit<HTMLAttributes<HTMLSpanElement>, 'className'>
+
+/** `--zv-cols` est un PARAMÈTRE de grille, pas un token de marque : il se
+ *  pose en style inline sur le cadre, et l'en-tête comme les lignes en
+ *  héritent. Une seule déclaration pour les deux — recopié aux deux
+ *  endroits, on l'oublie à l'un et les intitulés se décalent des valeurs
+ *  sans que rien ne casse visiblement. */
+function cols(gabarit: string | undefined, style: CSSProperties | undefined) {
+  return gabarit ? ({ ...style, ['--zv-cols']: gabarit } as CSSProperties) : style
+}
+
+/* ─── Tableau ──────────────────────────────────────────────────────── */
+
+export interface TableProps extends Div {
+  /** Gabarit de colonnes, en syntaxe `grid-template-columns`
+   *  (ex. `'minmax(0,2fr) 120px 90px'`). Hérité par l'en-tête et les lignes. */
+  gabarit?: string
+  className?: string
+}
+
+/** Le tableau défile DANS son cadre : sans ce confinement, une colonne trop
+ *  large fait défiler la page entière et le rail de navigation part avec. */
+export function Table({ gabarit, className, style, ...reste }: TableProps) {
+  return (
+    <div className={cx('zv-table', className)} style={cols(gabarit, style)} {...reste} />
+  )
+}
+
+export interface TableHeadProps extends Div {
+  /** En-tête en retrait, pour un tableau posé dans une carte. */
+  inset?: boolean
+  className?: string
+}
+
+export function TableHead({ inset, className, ...reste }: TableHeadProps) {
+  return (
+    <div
+      className={cx('zv-table__head', inset && 'zv-table__head--inset', className)}
+      {...reste}
+    />
+  )
+}
+
+export interface RowProps extends Div {
+  /** Rend la rangée comme un lien : la cible entière devient cliquable, ce
+   *  qu'un `onClick` sur un `<div>` ne donne jamais (ni clavier, ni ouverture
+   *  dans un nouvel onglet). */
+  href?: string
+  className?: string
+}
+
+export function Row({ href, className, ...reste }: RowProps) {
+  if (href) {
+    return (
+      <a
+        href={href}
+        className={cx('zv-row', className)}
+        {...(reste as AnchorHTMLAttributes<HTMLAnchorElement>)}
+      />
+    )
+  }
+  return <div className={cx('zv-row', className)} {...reste} />
+}
+
+export interface CellProps extends Div {
+  /** `nom` : la colonne d'identité, la seule en encre pleine.
+   *  `num` : chiffres alignés à droite, en chasse tabulaire. */
+  registre?: 'nom' | 'num'
+  /** Intitulé qui REMPLACE l'en-tête quand celui-ci disparaît (mobile). */
+  label?: ReactNode
+  /** Unité accolée au nombre, en plus petit. */
+  unite?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function Cell({ registre, label, unite, className, children, ...reste }: CellProps) {
+  return (
+    <div
+      className={cx(
+        'zv-cell',
+        registre === 'nom' && 'zv-cell--name',
+        registre === 'num' && 'zv-cell--num',
+        className,
+      )}
+      {...reste}
+    >
+      {label && <span className="zv-cell__label">{label}</span>}
+      {children}
+      {unite && <span className="zv-cell__unit">{unite}</span>}
+    </div>
+  )
+}
+
+/** Groupe deux ou trois cellules pour l'empilement mobile, puis s'efface
+ *  (`display: contents`) et rend ses enfants DIRECTEMENT à la grille.
+ *  ⚠️ N'exprime QUE ce sens-là : le mouvement inverse (pile au-dessus du
+ *  seuil, colonnes en dessous) n'est pas cette classe. */
+export function Unwrap({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-unwrap', className)} {...reste} />
+}
+
+/* ─── Liste sans colonnes ──────────────────────────────────────────── */
+
+export function List({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-list', className)} {...reste} />
+}
+
+export interface ListRowProps extends Div {
+  /** Rangée de dépôt en cours : gabarit propre à l'écran d'import. */
+  upload?: boolean
+  className?: string
+}
+
+export function ListRow({ upload, className, ...reste }: ListRowProps) {
+  return (
+    <div
+      className={cx('zv-list__row', upload && 'zv-list__row--upload', className)}
+      {...reste}
+    />
+  )
+}
+
+export function ListMain({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-list__main', className)} {...reste} />
+}
+
+export function ListName({ className, ...reste }: Span & { className?: string }) {
+  return <span className={cx('zv-list__name', className)} {...reste} />
+}
+
+/* ─── Métadonnée mono ──────────────────────────────────────────────── */
+
+export interface MetaProps extends Span {
+  taille?: 'sm' | 'normal' | 'md'
+  /** Encore plus effacée : contexte de second plan. */
+  discret?: boolean
+  className?: string
+}
+
+/** Second registre mono du système, en BAS DE CASSE : taille de fichier,
+ *  date, horodatage, latence. Ni capitales ni interlettrage — c'est ce qui le
+ *  distingue de `Tag` et `Mono`, et une date en capitales espacées devient
+ *  illisible. */
+export function Meta({ taille = 'normal', discret, className, ...reste }: MetaProps) {
+  return (
+    <span
+      className={cx(
+        'zv-meta',
+        taille === 'sm' && 'zv-meta--sm',
+        taille === 'md' && 'zv-meta--md',
+        discret && 'zv-meta--quiet',
+        className,
+      )}
+      {...reste}
+    />
+  )
+}
+
+export function MetaRow({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-meta-row', className)} {...reste} />
+}
+
+/* ─── Clé-valeur ───────────────────────────────────────────────────── */
+
+export interface KVProps extends Div {
+  /** `grid` : deux colonnes alignées. `foot` : bloc de pied de fiche. */
+  variante?: 'grid' | 'foot'
+  className?: string
+}
+
+export function KV({ variante, className, ...reste }: KVProps) {
+  return (
+    <div className={cx('zv-kv', variante && `zv-kv--${variante}`, className)} {...reste} />
+  )
+}
+
+export interface KVRowProps extends Div {
+  /** ⚠️ La CLÉ est en mono, en accent, et se coupe ; la VALEUR est en texte
+   *  courant, en gris, et ne se coupe jamais. Inverser les deux change ce que
+   *  l'œil balaie en premier dans une colonne de métadonnées. */
+  cle: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function KVRow({ cle, className, children, ...reste }: KVRowProps) {
+  return (
+    <div className={cx('zv-kv__row', className)} {...reste}>
+      <span className="zv-kv__key">{cle}</span>
+      <span className="zv-kv__val">{children}</span>
+    </div>
+  )
+}
+
+/* ─── Pastille d'initiales ─────────────────────────────────────────── */
+
+export interface AvatarProps extends Span {
+  /** ⚠️ La teinte dit la NATURE de l'entité, elle n'est pas décorative :
+   *  la changer, c'est changer le sens. */
+  ton?: 'accent' | 'ink' | 'soft'
+  petit?: boolean
+  className?: string
+}
+
+/** CARRÉE, jamais ronde : le rond est un usage de réseau social, l'encre et
+ *  le papier posent des blocs. */
+export function Avatar({ ton, petit, className, ...reste }: AvatarProps) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cx(
+        'zv-avatar',
+        ton && `zv-avatar--${ton}`,
+        petit && 'zv-avatar--sm',
+        className,
+      )}
+      {...reste}
+    />
+  )
+}
+
+/* ─── Troncature ───────────────────────────────────────────────────── */
+
+/** Coupe sur une ligne avec des points de suspension. Jamais interchangeable
+ *  avec `Break`, qui revient à la ligne. */
+export function Trunc({ className, ...reste }: Span & { className?: string }) {
+  return <span className={cx('zv-trunc', className)} {...reste} />
+}
+
+/** Revient à la ligne au milieu d'un mot : jetons, URLs, chemins. */
+export function Break({ className, ...reste }: Span & { className?: string }) {
+  return <span className={cx('zv-break', className)} {...reste} />
+}
+
+/* ─── Étiquette de catégorie ───────────────────────────────────────── */
+
+export interface ChipProps extends Span {
+  /** `mono` : identifiant, code. `outline` : filet au lieu du fond. */
+  variante?: 'mono' | 'outline'
+  className?: string
+}
+
+/** Étiquette NON porteuse d'alerte : nature d'entité, matière, mot-clé.
+ *  À ne pas confondre avec `Badge` (couleur sémantique) ni `Tag` (kicker
+ *  éditorial). Une catégorie n'a pas à crier. */
+export function Chip({ variante, className, ...reste }: ChipProps) {
+  return (
+    <span
+      className={cx('zv-chip', variante && `zv-chip--${variante}`, className)}
+      {...reste}
+    />
+  )
+}
+
+export function ChipRow({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-chip-row', className)} {...reste} />
+}
+
+/* ─── Citation ─────────────────────────────────────────────────────── */
+
+export function Cite({
+  className,
+  ...reste
+}: Omit<HTMLAttributes<HTMLButtonElement>, 'className'> & { className?: string }) {
+  return <button type="button" className={cx('zv-cite', className)} {...reste} />
+}
+
+export function CiteRow({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-cite-row', className)} {...reste} />
+}
+
+/* ─── Vignette de format ───────────────────────────────────────────── */
+
+export interface FileTypeProps extends Span {
+  /** Règle de choix relevée : DOCX si le type MIME contient « word »,
+   *  PDF sinon. Les couleurs ne viennent PAS de la charte — ce sont celles
+   *  que le monde associe à ces formats. */
+  format: 'pdf' | 'docx'
+  className?: string
+}
+
+export function FileType({ format, className, ...reste }: FileTypeProps) {
+  return (
+    <span className={cx('zv-filetype', `zv-filetype--${format}`, className)} {...reste}>
+      {format.toUpperCase()}
+    </span>
+  )
+}

package/react/feedback.tsx

@@ -0,0 +1,229 @@
+// Retours — bandeaux d'état, étiquettes, pastilles, absence, travail en cours.
+//
+// Rien ici n'est interactif : pas de fermeture, pas de survol. Aucun de ces
+// composants n'a besoin de tourner côté navigateur.
+//
+// ⚠️ Ce fichier ne livre NI roue de chargement, NI squelette, NI infobulle :
+// le CSS n'en a pas, parce que le relevé de production n'en contenait aucun.
+// Le travail en cours se dit par `Loading`, qui nomme ce qu'on attend — une
+// roue dit « attendez », cette phrase dit sur quoi.
+
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cx } from './cx.js'
+
+type Div = Omit<HTMLAttributes<HTMLDivElement>, 'className'>
+type Span = Omit<HTMLAttributes<HTMLSpanElement>, 'className'>
+
+/* ─── Bandeaux d'état ──────────────────────────────────────────────── */
+
+export type AlertTon = 'info' | 'ok' | 'warn' | 'err' | 'dash'
+
+export interface AlertProps extends Div {
+  /** OBLIGATOIRE : sans ton, le bandeau hérite d'un filet en `currentColor`,
+   *  soit un trait d'encre autour d'un fond blanc. */
+  ton: AlertTon
+  /** `sm` resserre, `lg` amplifie — ce dernier pour le message qui REMPLACE
+   *  un contenu attendu (incident, réponse impossible). */
+  taille?: 'sm' | 'normal' | 'lg'
+  className?: string
+}
+
+export function Alert({ ton, taille = 'normal', className, ...reste }: AlertProps) {
+  return (
+    <div
+      role="alert"
+      className={cx(
+        'zv-alert',
+        `zv-alert--${ton}`,
+        taille === 'sm' && 'zv-alert--sm',
+        taille === 'lg' && 'zv-alert--lg',
+        className,
+      )}
+      {...reste}
+    />
+  )
+}
+
+/* ─── Étiquettes d'état ────────────────────────────────────────────── */
+
+export type BadgeTon = 'neutre' | 'accent' | 'ok' | 'warn' | 'err'
+
+export interface BadgeProps extends Span {
+  ton?: BadgeTon
+  /** `micro` : niveau de log en tête de ligne, badge de coque.
+   *  `state` : état de service (OK / CHARGE). */
+  gabarit?: 'micro' | 'state'
+  /** Pastille en tête, de la couleur du texte. */
+  pastille?: boolean
+  className?: string
+  children?: ReactNode
+}
+
+/** Le libellé s'écrit EN CAPITALES dans le contenu, pas en CSS : transformé
+ *  par le navigateur, « INDEXÉ » se casse selon la locale. */
+export function Badge({
+  ton = 'neutre',
+  gabarit,
+  pastille,
+  className,
+  children,
+  ...reste
+}: BadgeProps) {
+  return (
+    <span
+      className={cx(
+        'zv-badge',
+        `zv-badge--${ton}`,
+        gabarit === 'micro' && 'zv-badge--micro',
+        gabarit === 'state' && 'zv-badge--state',
+        pastille && 'zv-badge--dot',
+        className,
+      )}
+      {...reste}
+    >
+      {pastille && <span className="zv-dot" aria-hidden="true" />}
+      {children}
+    </span>
+  )
+}
+
+/* ─── Pastilles ────────────────────────────────────────────────────── */
+
+export type DotEtat = 'recu' | 'ocr' | 'indexation' | 'indexe' | 'ok' | 'erreur'
+
+export interface DotProps extends Span {
+  /** Sans état, la pastille reste GRISE : un statut inconnu — ajouté côté
+   *  serveur, pas encore côté interface — ne doit pas passer pour un succès. */
+  etat?: DotEtat
+  taille?: 'sm' | 'normal' | 'lg'
+  /** CARRÉE : marque une SOURCE, pas un état. Ne pas uniformiser. */
+  carree?: boolean
+  className?: string
+}
+
+export function Dot({ etat, taille = 'normal', carree, className, ...reste }: DotProps) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cx(
+        'zv-dot',
+        etat && `zv-dot--${etat}`,
+        taille === 'sm' && 'zv-dot--sm',
+        taille === 'lg' && 'zv-dot--lg',
+        carree && 'zv-dot--square',
+        className,
+      )}
+      {...reste}
+    />
+  )
+}
+
+/* ─── Statut en clair ──────────────────────────────────────────────── */
+
+export interface StatusProps extends Div {
+  etat?: DotEtat
+  /** Le message d'erreur REMPLACE le libellé quand il y en a un :
+   *  l'utilisateur veut lire la cause, pas le mot « Erreur ». */
+  children?: ReactNode
+  className?: string
+}
+
+export function Status({ etat, className, children, ...reste }: StatusProps) {
+  return (
+    <div className={cx('zv-status', className)} {...reste}>
+      <Dot etat={etat} />
+      <span className="zv-status__label">{children}</span>
+    </div>
+  )
+}
+
+/* ─── Absence ──────────────────────────────────────────────────────── */
+
+export interface EmptyProps extends Div {
+  /** ⚠️ DEUX OBJETS DISTINCTS. Sans `titre` c'est la LIGNE d'absence : un
+   *  filtre trop étroit, la collection existe, l'en-tête du tableau reste
+   *  visible. Avec `titre` et `page`, c'est l'ÉCRAN d'absence : la collection
+   *  est vide et il faut lui offrir une porte de sortie. Les confondre
+   *  affiche un écran de bienvenue à chaque filtre trop strict. */
+  titre?: ReactNode
+  page?: boolean
+  /** L'action qui remplira la collection. Réservée à l'écran d'absence. */
+  action?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function Empty({ titre, page, action, className, children, ...reste }: EmptyProps) {
+  return (
+    <div className={cx('zv-empty', page && 'zv-empty--page', className)} {...reste}>
+      {titre && <p className="zv-empty__title">{titre}</p>}
+      {children && <p className="zv-empty__text">{children}</p>}
+      {action && <div className="zv-empty__action">{action}</div>}
+    </div>
+  )
+}
+
+/* ─── Travail en cours ─────────────────────────────────────────────── */
+
+export interface LoadingProps extends Div {
+  className?: string
+  children?: ReactNode
+}
+
+/** Pastille + phrase qui dit le travail réel (« Recherche dans 4 812
+ *  documents anonymisés… »). STATIQUE : la pastille ne bat pas, et lui
+ *  ajouter un pouls est l'invention la plus tentante du système. */
+export function Loading({ className, children, ...reste }: LoadingProps) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className={cx('zv-loading', className)}
+      {...reste}
+    >
+      <span className="zv-dot" aria-hidden="true" />
+      {children}
+    </div>
+  )
+}
+
+/** Bloc collé à la fin d'un texte en cours de diffusion, sur le DERNIER
+ *  message seulement : sans lui, une réponse coupée à mi-phrase se lit comme
+ *  une réponse complète et fausse. */
+export function Caret({ className, ...reste }: Span & { className?: string }) {
+  return (
+    <span className={cx('zv-caret', className)} aria-hidden="true" {...reste}>
+      ▍
+    </span>
+  )
+}
+
+/* ─── Barre de progression ─────────────────────────────────────────── */
+
+export interface ProgressProps extends Div {
+  /** Entre 0 et 1. Hors bornes, la valeur est ramenée dedans : une barre à
+   *  140 % déborde de son cadre. */
+  valeur: number
+  /** Ce que la barre mesure — annoncé, jamais dessiné. */
+  label?: string
+  className?: string
+}
+
+/** Deuxième des trois emplois autorisés du spectre (avec le filet de section
+ *  et les points de méthode). Jamais en fond, jamais en texte. */
+export function Progress({ valeur, label, className, ...reste }: ProgressProps) {
+  const part = Math.min(1, Math.max(0, valeur))
+  return (
+    <div
+      role="progressbar"
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuenow={Math.round(part * 100)}
+      aria-label={label}
+      className={cx('zv-progress', className)}
+      {...reste}
+    >
+      <div className="zv-progress__fill" style={{ width: `${part * 100}%` }} />
+    </div>
+  )
+}