@zevra/ui 0.3.2 → 0.5.0

package/react/layout.tsx

@@ -0,0 +1,347 @@
+// Mise en page vitrine — page, gouttières, grille 12, sections, hero, frise
+// d'étapes, statistiques, pieds de page, couches d'empilement.
+//
+// Couche VITRINE : une application n'a aucune raison de charger ce fichier.
+// Tout y est sans état.
+
+import type { ElementType, HTMLAttributes, ReactNode } from 'react'
+import { cx } from './cx.js'
+
+type Div = Omit<HTMLAttributes<HTMLDivElement>, 'className'>
+
+/* ─── Page et gouttières ───────────────────────────────────────────── */
+
+export function Page({
+  as,
+  className,
+  ...reste
+}: Div & { as?: ElementType; className?: string }) {
+  const Balise = as ?? 'div'
+  return <Balise className={cx('zv-page', className)} {...reste} />
+}
+
+export interface GutterProps extends Div {
+  /** `wide` pour une bande pleine largeur, `chrome` pour la barre de
+   *  navigation — qui ne s'aligne pas sur la colonne de texte. */
+  variante?: 'wide' | 'chrome'
+  as?: ElementType
+  className?: string
+}
+
+/** La largeur de colonne du système. Toute la vitrine s'aligne dessus : un
+ *  bloc qui pose sa propre largeur maximale se décale de tous les autres. */
+export function Gutter({ variante, as, className, ...reste }: GutterProps) {
+  const Balise = as ?? 'div'
+  return (
+    <Balise
+      className={cx('zv-gutter', variante && `zv-gutter--${variante}`, className)}
+      {...reste}
+    />
+  )
+}
+
+/** Débord latéral : ressort de la gouttière pour aller au bord de l'écran
+ *  (une bande de couleur, une image pleine largeur). */
+export function InsetX({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-inset-x', className)} {...reste} />
+}
+
+/* ─── Grilles ──────────────────────────────────────────────────────── */
+
+export function Grid12({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-grid-12', className)} {...reste} />
+}
+
+export type Span12 = 3 | 4 | 6 | 8 | 9
+
+/** ⚠️ Seules 3, 4, 6, 8 et 9 existent : ce sont les découpes employées par la
+ *  vitrine. En ajouter une revient à ajouter une mise en page, pas une
+ *  utilité — c'est une décision de DA. */
+export function Col({
+  span,
+  className,
+  ...reste
+}: Div & { span: Span12; className?: string }) {
+  return <div className={cx(`zv-col-${span}`, className)} {...reste} />
+}
+
+/** Grilles régulières, empilées sous le point de rupture. */
+export function Grid({
+  colonnes,
+  className,
+  ...reste
+}: Div & { colonnes: 3 | 4; className?: string }) {
+  return <div className={cx(`zv-grid-${colonnes}`, className)} {...reste} />
+}
+
+/* ─── Sections ─────────────────────────────────────────────────────── */
+
+export interface SectionHeadProps extends Div {
+  /** Bloc de droite : un lien, un chiffre, une précision. Il tombe SOUS le
+   *  titre en dessous du point de rupture. */
+  aside?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function SectionHead({ aside, className, children, ...reste }: SectionHeadProps) {
+  return (
+    <div className={cx('zv-section-head', className)} {...reste}>
+      <div className="zv-section-head__main">{children}</div>
+      {aside && <div className="zv-section-head__aside">{aside}</div>}
+    </div>
+  )
+}
+
+export function SectionRule({
+  discret,
+  className,
+  ...reste
+}: Div & { discret?: boolean; className?: string }) {
+  return (
+    <div
+      className={cx('zv-section-rule', discret && 'zv-section-rule--quiet', className)}
+      {...reste}
+    />
+  )
+}
+
+export interface SheetSectionProps extends Div {
+  titre?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+/** Section d'un document long : un intitulé mono, un filet, du corps. */
+export function SheetSection({ titre, className, children, ...reste }: SheetSectionProps) {
+  return (
+    <section className={cx('zv-sheet-section', className)} {...reste}>
+      {titre && <h2 className="zv-sheet-section__title">{titre}</h2>}
+      <div className="zv-sheet-section__body">{children}</div>
+    </section>
+  )
+}
+
+/* ─── Blocs centrés ────────────────────────────────────────────────── */
+
+export function Hero({ className, ...reste }: Div & { className?: string }) {
+  return <section className={cx('zv-hero', className)} {...reste} />
+}
+
+export function CTA({ className, ...reste }: Div & { className?: string }) {
+  return <section className={cx('zv-cta', className)} {...reste} />
+}
+
+/** En-tête fixe de la vitrine. */
+export function Header({ className, ...reste }: Div & { className?: string }) {
+  return <header className={cx('zv-header', className)} {...reste} />
+}
+
+/* ─── Navigation vitrine ───────────────────────────────────────────── */
+
+export function Nav({ className, ...reste }: Div & { className?: string }) {
+  return <nav className={cx('zv-nav', className)} {...reste} />
+}
+
+export function NavLogo({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-nav__logo', className)} {...reste} />
+}
+
+/** ⚠️ Cette rangée disparaît sous le point de rupture, remplacée par le
+ *  burger. Le CSS s'en occupe : ne jamais la conditionner en JavaScript. */
+export function NavLinks({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-nav__links', className)} {...reste} />
+}
+
+export interface NavLinkProps
+  extends Omit<HTMLAttributes<HTMLAnchorElement>, 'className'> {
+  /** Lien secondaire : connexion, mentions. */
+  discret?: boolean
+  href?: string
+  className?: string
+}
+
+/** ⚠️ `.zv-navlink` est la navigation de VITRINE. L'entrée applicative
+ *  s'appelle `SideLink` — les deux ne doivent jamais se recouvrir. */
+export function NavLink({ discret, className, ...reste }: NavLinkProps) {
+  return (
+    <a className={cx('zv-navlink', discret && 'zv-navlink--quiet', className)} {...reste} />
+  )
+}
+
+/** Le burger de la vitrine. Il n'apparaît que sous le point de rupture. */
+export function NavBurger({
+  className,
+  type = 'button',
+  ...reste
+}: Omit<HTMLAttributes<HTMLButtonElement>, 'className'> & {
+  className?: string
+  type?: 'button'
+  'aria-label': string
+}) {
+  return <button type={type} className={cx('zv-nav__burger', className)} {...reste} />
+}
+
+/** Le contenu du tiroir de navigation vitrine — à poser dans `Drawer`. */
+export function NavDrawer({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-nav-drawer', className)} {...reste} />
+}
+
+export function NavDrawerLink({
+  courant,
+  className,
+  ...reste
+}: Omit<HTMLAttributes<HTMLAnchorElement>, 'className'> & {
+  courant?: boolean
+  href?: string
+  className?: string
+}) {
+  return (
+    <a
+      aria-current={courant ? 'page' : undefined}
+      className={cx('zv-nav-drawer__link', courant && 'zv-nav-drawer__link--on', className)}
+      {...reste}
+    />
+  )
+}
+
+/* ─── Frise d'étapes ───────────────────────────────────────────────── */
+
+export interface StepsProps extends Div {
+  /** Avancement du rail, entre 0 et 1 — piloté au défilement. */
+  avancement?: number
+  className?: string
+  children?: ReactNode
+}
+
+export function Steps({ avancement, className, children, ...reste }: StepsProps) {
+  const part = Math.min(1, Math.max(0, avancement ?? 0))
+  return (
+    <div className={cx('zv-steps', className)} {...reste}>
+      <div className="zv-steps__rail" aria-hidden="true">
+        <div className="zv-steps__progress" style={{ width: `${part * 100}%` }} />
+      </div>
+      {children}
+    </div>
+  )
+}
+
+export interface StepProps extends Div {
+  /** Troisième et dernier emploi autorisé du spectre : le point de méthode.
+   *  Jamais en fond, jamais en texte. */
+  teinte?: 'violet' | 'cyan'
+  className?: string
+  children?: ReactNode
+}
+
+export function Step({ teinte, className, children, ...reste }: StepProps) {
+  return (
+    <div className={cx('zv-step', className)} {...reste}>
+      <span
+        className={cx('zv-step__dot', teinte && `zv-step__dot--${teinte}`)}
+        aria-hidden="true"
+      />
+      {children}
+    </div>
+  )
+}
+
+/* ─── Statistiques ─────────────────────────────────────────────────── */
+
+export function Stats({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-stats', className)} {...reste} />
+}
+
+export interface StatProps extends Div {
+  valeur: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function Stat({ valeur, className, children, ...reste }: StatProps) {
+  return (
+    <div className={cx('zv-stat', className)} {...reste}>
+      <span className="zv-stat__value">{valeur}</span>
+      {children}
+    </div>
+  )
+}
+
+/* ─── Pieds de page ────────────────────────────────────────────────── */
+
+export interface FooterProps extends Div {
+  /** Colonne de gauche : logo, signature, mention légale. */
+  marque?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function Footer({ marque, className, children, ...reste }: FooterProps) {
+  return (
+    <footer className={cx('zv-footer', className)} {...reste}>
+      {marque && <div className="zv-footer__brand">{marque}</div>}
+      <div className="zv-footer__cols">{children}</div>
+    </footer>
+  )
+}
+
+/** Pied réduit : une ligne, un logo, des mentions. Pour une page isolée
+ *  (connexion, document partagé) qui n'a pas de pied complet à porter. */
+export function FooterMini({
+  logo,
+  className,
+  children,
+  ...reste
+}: Div & { logo?: ReactNode; className?: string; children?: ReactNode }) {
+  return (
+    <footer className={cx('zv-footer-mini', className)} {...reste}>
+      {logo && <div className="zv-footer-mini__logo">{logo}</div>}
+      {children}
+    </footer>
+  )
+}
+
+export interface ProofBarProps extends Div {
+  /** Les noms cités. ⚠️ RÈGLE DE CHARTE : jamais de client inventé. */
+  noms?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function ProofBar({ noms, className, children, ...reste }: ProofBarProps) {
+  return (
+    <div className={cx('zv-proof-bar', className)} {...reste}>
+      {children}
+      {noms && <div className="zv-proof-bar__names">{noms}</div>}
+    </div>
+  )
+}
+
+/* ─── Empilement ───────────────────────────────────────────────────── */
+
+/** Les cinq étages du système, nommés une fois pour toutes : un `z-index`
+ *  écrit à la main quelque part finit toujours par passer devant ou derrière
+ *  ce qu'il ne fallait pas. Les enrobages (voile 60 → notification 100) sont
+ *  au-dessus, dans overlays.css. */
+export type Etage = 'scene' | 'content' | 'progress' | 'chrome' | 'top'
+
+export function Layer({
+  etage,
+  className,
+  ...reste
+}: Div & { etage: Etage; className?: string }) {
+  return <div className={cx(`zv-layer-${etage}`, className)} {...reste} />
+}
+
+/* ─── Visibilité ───────────────────────────────────────────────────── */
+
+/** ⚠️ Rendu par le CSS, PAS par JavaScript : le serveur ne connaît pas la
+ *  largeur de l'écran, et conditionner le rendu produit un décalage
+ *  d'hydratation. Les deux nœuds sont posés, le CSS en masque un. */
+export function OnlyDesktop({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-only-desktop', className)} {...reste} />
+}
+
+export function OnlyMobile({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-only-mobile', className)} {...reste} />
+}

package/react/navigation.tsx

@@ -0,0 +1,329 @@
+// Navigation applicative — colonne latérale, barre supérieure, fil d'Ariane,
+// menu, pagination, feuille de source, zones défilantes.
+//
+// Rien ici n'a d'état propre : l'entrée courante, la page courante, l'item
+// sélectionné viennent de l'appelant. Aucun « use client », donc — c'est ce
+// qui permet à une colonne de navigation Next de rester rendue au serveur.
+//
+// ⚠️ Les OVERLAYS (tiroir, modale, notification) sont dans overlays.tsx : eux
+// ont besoin du navigateur.
+
+import type {
+  AnchorHTMLAttributes,
+  ButtonHTMLAttributes,
+  HTMLAttributes,
+  ReactNode,
+} from 'react'
+import { cx } from './cx.js'
+import { Seg, SegGroup } from './forms.js'
+
+type Div = Omit<HTMLAttributes<HTMLDivElement>, 'className'>
+type Span = Omit<HTMLAttributes<HTMLSpanElement>, 'className'>
+type A = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'className'>
+type Btn = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className'>
+
+/* ─── Colonne latérale ─────────────────────────────────────────────── */
+
+/** Une colonne, un filet, rien d'autre : ni ombre, ni rayon. Une ombre ferait
+ *  flotter une pièce qui ne bouge jamais. Elle défile pour son propre compte —
+ *  une nav longue n'entraîne jamais le contenu. */
+export function Sidebar({ className, ...reste }: Div & { className?: string }) {
+  return <aside className={cx('zv-sidebar', className)} {...reste} />
+}
+
+export function SidebarHead({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-sidebar__head', className)} {...reste} />
+}
+
+/** Collé en bas quand la nav est courte, il suit le contenu quand elle est
+ *  longue. */
+export function SidebarFoot({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-sidebar__foot', className)} {...reste} />
+}
+
+export interface SideGroupProps extends Div {
+  titre?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function SideGroup({ titre, className, children, ...reste }: SideGroupProps) {
+  return (
+    <div className={cx('zv-sidegroup', className)} {...reste}>
+      {titre && <div className="zv-sidegroup__title">{titre}</div>}
+      {children}
+    </div>
+  )
+}
+
+export interface SideLinkProps extends A {
+  /** Pose `aria-current="page"` en plus de la classe : sans lui, l'entrée
+   *  courante est marquée pour l'œil et muette au lecteur d'écran. */
+  courant?: boolean
+  /** Rang mono ou glyphe, sur une colonne de largeur fixe — sinon les
+   *  libellés se décalent d'un groupe à l'autre. */
+  num?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function SideLink({ courant, num, className, children, ...reste }: SideLinkProps) {
+  return (
+    <a
+      aria-current={courant ? 'page' : undefined}
+      className={cx('zv-sidelink', courant && 'zv-sidelink--on', className)}
+      {...reste}
+    >
+      {num != null && <span className="zv-sidelink__num">{num}</span>}
+      {children}
+    </a>
+  )
+}
+
+/* ─── Barre supérieure ─────────────────────────────────────────────── */
+
+/** Elle REMPLACE la colonne sous le point de rupture : masquée au-dessus,
+ *  elle n'apparaît que dans le bloc mobile du CSS. Ne pas la conditionner en
+ *  JavaScript — le rendu serveur ne connaît pas la largeur de l'écran. */
+export function Topbar({ className, ...reste }: Div & { className?: string }) {
+  return <header className={cx('zv-topbar', className)} {...reste} />
+}
+
+/** Le logo cède AVANT le nom : un logo client très large ne doit jamais
+ *  pousser la barre hors de l'écran. */
+export function TopbarLogo({ className, ...reste }: Div & { className?: string }) {
+  return <div className={cx('zv-topbar__logo', className)} {...reste} />
+}
+
+export function TopbarTitle({ className, ...reste }: Span & { className?: string }) {
+  return <span className={cx('zv-topbar__title', className)} {...reste} />
+}
+
+export function TopbarBurger({ className, type = 'button', ...reste }: Btn & { className?: string }) {
+  return <button type={type} className={cx('zv-topbar__burger', className)} {...reste} />
+}
+
+/** Croix bordée du chrome — fermeture d'un tiroir, d'une feuille de source.
+ *  Angles vifs : le rayon signale l'action, le chrome n'en est pas une. */
+export function ChromeButton({
+  className,
+  type = 'button',
+  ...reste
+}: Btn & { className?: string; 'aria-label': string }) {
+  return <button type={type} className={cx('zv-chrome-btn', className)} {...reste} />
+}
+
+/* ─── Fil d'Ariane ─────────────────────────────────────────────────── */
+
+export interface CrumbsProps extends Omit<A, 'children'> {
+  /** Les segments, du plus général au plus précis. Le DERNIER est plus sombre :
+   *  c'est celui qu'on lit, le reste n'est qu'un chemin. */
+  segments: ReactNode[]
+  /** Séparateur. Le `/` par défaut est celui du relevé. */
+  separateur?: ReactNode
+  className?: string
+}
+
+/** ⚠️ Le fil ENTIER est cliquable — c'est un seul nœud, pas une liste de
+ *  liens. Sans `href`, il se rend en `<span>` : un `<a>` sans cible reste
+ *  annoncé comme un lien et déçoit. */
+export function Crumbs({
+  segments,
+  separateur = '/',
+  href,
+  className,
+  ...reste
+}: CrumbsProps) {
+  const contenu = segments.map((seg, i) => (
+    <span key={i}>
+      {i > 0 && (
+        <span className="zv-crumbs__sep" aria-hidden="true">
+          {separateur}
+        </span>
+      )}
+      <span className={i === segments.length - 1 ? 'zv-crumbs__seg' : undefined}>{seg}</span>
+    </span>
+  ))
+  const classe = cx('zv-crumbs', className)
+  if (!href) {
+    return <span className={classe}>{contenu}</span>
+  }
+  return (
+    <a href={href} className={classe} {...reste}>
+      {contenu}
+    </a>
+  )
+}
+
+/* ─── Menu déroulant ───────────────────────────────────────────────── */
+
+/** À poser dans un `SelectAnchor` (forms) : c'est l'enveloppe qui ancre le
+ *  menu, pas le déclencheur — l'ancrer sur le déclencheur casse sa largeur
+ *  maximale calculée sur la fenêtre. */
+export function Menu({ className, ...reste }: Div & { className?: string; role?: string }) {
+  return <div role="listbox" className={cx('zv-menu', className)} {...reste} />
+}
+
+export interface MenuItemProps extends Btn {
+  /** Pose `aria-selected` en plus de la classe. */
+  actif?: boolean
+  className?: string
+}
+
+export function MenuItem({ actif, className, type = 'button', ...reste }: MenuItemProps) {
+  return (
+    <button
+      type={type}
+      role="option"
+      aria-selected={actif ?? false}
+      className={cx('zv-menu__item', actif && 'zv-menu__item--on', className)}
+      {...reste}
+    />
+  )
+}
+
+/* ─── Onglets ──────────────────────────────────────────────────────── */
+
+export interface TabsProps<T extends string> {
+  onglets: readonly { id: T; label: ReactNode; compte?: ReactNode }[]
+  actif: T
+  onChange: (id: T) => void
+  /** Rangée qui défile au lieu de passer à la ligne. */
+  rail?: boolean
+  /** Identifiant du panneau piloté, pour `aria-controls`. */
+  panneau?: string
+  className?: string
+}
+
+/** ⚠️ Il n'existe AUCUNE classe d'onglet dans le CSS, et c'est délibéré : une
+ *  rangée d'onglets est une rangée de puces, avec la grammaire d'état de
+ *  `Seg`. Un onglet SOULIGNÉ reste à faire — il suppose d'arbitrer couleur et
+ *  épaisseur du trait actif, ce qu'aucune source ne donne. Ce composant
+ *  n'ajoute donc que l'ARIA, pas un style de plus. */
+export function Tabs<T extends string>({
+  onglets,
+  actif,
+  onChange,
+  rail,
+  panneau,
+  className,
+}: TabsProps<T>) {
+  return (
+    <SegGroup role="tablist" rail={rail} className={className}>
+      {onglets.map((o) => (
+        <Seg
+          key={o.id}
+          role="tab"
+          aria-selected={o.id === actif}
+          aria-controls={panneau}
+          on={o.id === actif}
+          compte={o.compte}
+          onClick={() => onChange(o.id)}
+        >
+          {o.label}
+        </Seg>
+      ))}
+    </SegGroup>
+  )
+}
+
+/* ─── Pagination ───────────────────────────────────────────────────── */
+
+export interface PagerProps extends Div {
+  /** Pied de tableau : compte à gauche, sens à droite. C'est un MODIFICATEUR,
+   *  il se pose avec `Pager`, jamais seul. */
+  pied?: boolean
+  className?: string
+}
+
+export function Pager({ pied, className, ...reste }: PagerProps) {
+  return (
+    <nav
+      className={cx('zv-pager', pied && 'zv-pager--foot', className)}
+      {...reste}
+    />
+  )
+}
+
+/** ⚠️ Une flèche désactivée reste ATTEIGNABLE au clavier (`aria-disabled` et
+ *  non `disabled`) : sinon elle disparaît du parcours sans être annoncée. */
+export function PagerArrow({
+  desactive,
+  className,
+  type = 'button',
+  ...reste
+}: Btn & { desactive?: boolean; className?: string; 'aria-label': string }) {
+  return (
+    <button
+      type={type}
+      aria-disabled={desactive || undefined}
+      className={cx('zv-pager__arrow', className)}
+      {...reste}
+    />
+  )
+}
+
+/** Le rang courant (« p. 12 / 31 »). Cliquable dans le relevé : il ouvre la
+ *  saisie directe d'un numéro. */
+export function PagerRank({ className, type = 'button', ...reste }: Btn & { className?: string }) {
+  return <button type={type} className={cx('zv-pager__rank', className)} {...reste} />
+}
+
+/** « ‹ Précédent · Suivant › » du pied de tableau. */
+export function PagerStep({ className, type = 'button', ...reste }: Btn & { className?: string }) {
+  return <button type={type} className={cx('zv-pager__step', className)} {...reste} />
+}
+
+/* ─── Feuille de source citée ──────────────────────────────────────── */
+
+export interface CitePanelProps extends Div {
+  titre?: ReactNode
+  /** Croix de fermeture et actions de tête. */
+  actions?: ReactNode
+  pied?: ReactNode
+  className?: string
+  children?: ReactNode
+}
+
+export function CitePanel({
+  titre,
+  actions,
+  pied,
+  className,
+  children,
+  ...reste
+}: CitePanelProps) {
+  return (
+    <div className={cx('zv-cite-panel', className)} {...reste}>
+      <div className="zv-cite-panel__head">
+        {titre && <span className="zv-cite-panel__title">{titre}</span>}
+        {actions}
+      </div>
+      <div className="zv-cite-panel__body">{children}</div>
+      {pied && <div className="zv-cite-panel__foot">{pied}</div>}
+    </div>
+  )
+}
+
+/* ─── Défilement ───────────────────────────────────────────────────── */
+
+export interface ScrollProps extends Div {
+  /** Barre fine, aux couleurs du système. OPT-IN : par défaut la barre native
+   *  est conservée — sur macOS et iOS, l'habiller la rend permanente et elle
+   *  mange une colonne. */
+  habillee?: boolean
+  className?: string
+}
+
+/** ⚠️ Porte `min-height: 0` ET `min-width: 0`. Sans les deux, un enfant flex
+ *  refuse de rétrécir sous son contenu : la zone déborde et c'est la PAGE qui
+ *  part en défilement horizontal. C'est la faute la plus fréquente de ce
+ *  gabarit. */
+export function Scroll({ habillee, className, ...reste }: ScrollProps) {
+  return (
+    <div
+      className={cx('zv-scroll-y', habillee && 'zv-scrollbar', className)}
+      {...reste}
+    />
+  )
+}