@zevra/ui 0.17.0 → 0.21.0

package/react/content.tsx

@@ -1,7 +1,7 @@
 // Contenu — surfaces, badges et blocs éditoriaux. Sans état, donc sans
 // « use client ».
 
-import type { HTMLAttributes, ReactNode } from 'react'
+import type { ElementType, HTMLAttributes, ReactNode } from 'react'
 import { cx } from './cx.js'
 
 type Div = Omit<HTMLAttributes<HTMLDivElement>, 'className'>
@@ -247,21 +247,61 @@ export function Faq({ className, ...reste }: Div & { className?: string }) {
   return <div className={cx('zv-faq', className)} {...reste} />
 }
 
-export interface FaqItemProps extends Div {
+export interface FaqItemProps
+  extends Omit<HTMLAttributes<HTMLDetailsElement>, 'className' | 'title'> {
   question: ReactNode
+  /** Dépliée au chargement. Une par page au plus : si toutes le sont, le
+   *  repli ne sert plus à rien et la page redevient un mur. */
+  ouvert?: boolean
   className?: string
   children?: ReactNode
 }
 
-/** Rendu ouvert, sans repli : la réponse est le contenu, la cacher derrière
- *  un clic n'ajoute rien à cinq questions. Pour un vrai accordéon, c'est un
- *  `<details>` — et il n'existe pas de style pour lui dans le paquet. */
-export function FaqItem({ question, className, children, ...reste }: FaqItemProps) {
+/** Une question qui se replie. `<details>`, donc AUCUN JavaScript : elle
+ *  s'ouvre au clic, à Entrée et à Espace, elle est annoncée comme repliable,
+ *  et la recherche du navigateur (⌘F) l'ouvre toute seule pour montrer ce
+ *  qu'elle a trouvé.
+ *
+ *  ⚠️ La réponse reste DANS LE DOM quand la question est fermée — `details`
+ *  la masque, il ne la retire pas. C'est ce qui permet à une page de porter
+ *  un balisage `FAQPage` honnête : ce que le moteur lit est bien ce que le
+ *  visiteur peut ouvrir. Un accordéon qui démonte son contenu annoncerait
+ *  des réponses absentes.
+ *
+ *  Le chevron fait partie du composant, comme celui de `Fold` et la flèche
+ *  de `LinkArrow` : recopié à la main, il finit par diverger.
+ *
+ *  `question` accepte un TITRE (`<h3>Ma question</h3>`) : une FAQ de vitrine
+ *  veut ses questions dans le plan du document — c'est ce que lisent les
+ *  moteurs, et ce que parcourt un lecteur d'écran qui saute de titre en
+ *  titre. Le CSS lui retire ce que le navigateur lui met : le niveau reste
+ *  au balisage, l'apparence au système. */
+export function FaqItem({
+  question,
+  ouvert,
+  className,
+  children,
+  ...reste
+}: FaqItemProps) {
   return (
-    <div className={className} {...reste}>
-      <p className="zv-faq__q">{question}</p>
+    <details className={cx('zv-faq__item', className)} open={ouvert} {...reste}>
+      <summary className="zv-faq__q">
+        {question}
+        <svg
+          className="zv-faq__chevron"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="square"
+          strokeLinejoin="miter"
+          aria-hidden="true"
+        >
+          <path d="M6.67 9.33 L12 14.67 L17.33 9.33" />
+        </svg>
+      </summary>
       <p className="zv-faq__a">{children}</p>
-    </div>
+    </details>
   )
 }
 
@@ -415,3 +455,274 @@ export function Callout({ titre, className, children, ...reste }: CalloutProps)
     </div>
   )
 }
+
+export interface MediaProps extends Div {
+  /** Rapport du cadre. Quatre, et pas davantage : un cinquième se demande. */
+  ratio?: '16-9' | '4-3' | '1-1' | '3-2'
+  /**
+   * L'image est CONTENUE au lieu de remplir — un logo, un schéma, une pièce
+   * qu'on ne peut pas rogner. Le papier passe alors derrière : il restera du
+   * vide, autant qu'il soit choisi.
+   */
+  contient?: boolean
+  className?: string
+  children?: ReactNode
+}
+
+/**
+ * Cadre à rapport constant pour une image ou une vidéo.
+ *
+ * ⚠️ Le rapport vit sur le CADRE, jamais sur l'image : posé sur un enfant de
+ * grille aligné au centre, il ne se résout pas et la colonne s'effondre à
+ * zéro. Le cadre est donc un bloc à lui, que l'image remplit en absolu.
+ *
+ * Il ne charge rien et ne décode rien : un produit qui veut masquer le temps
+ * de décodage compose `Spinner` par-dessus.
+ */
+export function Media({ ratio = '16-9', contient, className, children, ...reste }: MediaProps) {
+  return (
+    <div
+      className={cx('zv-media', `zv-media--${ratio}`, contient && 'zv-media--contient', className)}
+      {...reste}
+    >
+      {children}
+    </div>
+  )
+}
+
+export interface MediaImgProps
+  extends Omit<HTMLAttributes<HTMLImageElement>, 'className'> {
+  src: string
+  alt: string
+  className?: string
+}
+
+/**
+ * L'image d'un cadre. `alt` est OBLIGATOIRE — vide pour une image
+ * décorative, décrite sinon : c'est un choix, pas un oubli.
+ *
+ * Un produit qui optimise ses images (next/image) pose la classe
+ * `zv-media__img` sur son propre composant plutôt que d'employer celui-ci :
+ * le CSS est la source de vérité, la façade n'en est qu'une commodité.
+ */
+export function MediaImg({ className, alt, ...reste }: MediaImgProps) {
+  return <img alt={alt} className={cx('zv-media__img', className)} {...reste} />
+}
+
+export interface MediaCoinProps extends Span {
+  /** Coin gauche plutôt que droit. */
+  gauche?: boolean
+  /** Coin haut plutôt que bas. */
+  haut?: boolean
+  className?: string
+  children?: ReactNode
+}
+
+/** Mention posée dans un coin du cadre : durée d'une vidéo, nombre de pages,
+ *  réserve d'accès. Encre diluée, parce que le fond d'image est imprévisible. */
+export function MediaCoin({ gauche, haut, className, children, ...reste }: MediaCoinProps) {
+  return (
+    <span
+      className={cx(
+        'zv-media__coin',
+        gauche && 'zv-media__coin--gauche',
+        haut && 'zv-media__coin--haut',
+        className,
+      )}
+      {...reste}
+    >
+      {children}
+    </span>
+  )
+}
+
+/** Voile de lecture : un titre posé SUR une image n'est lisible qu'au-dessus
+ *  d'un dégradé. Il ne capte pas le pointeur — le cadre reste cliquable. */
+export function MediaVoile({ className, ...reste }: Span & { className?: string }) {
+  return <span aria-hidden="true" className={cx('zv-media__voile', className)} {...reste} />
+}
+
+/* ─── Page légale ──────────────────────────────────────────────────────
+ * La FORME d'un document contractuel. Le TEXTE vit dans @zevra/legal,
+ * versionné et archivé — ce composant n'en dépend pas : il décrit la forme
+ * qu'il sait rendre, et le typage structurel de TypeScript fait le reste.
+ * C'est délibéré : le design system ne doit pas dépendre du contenu, sinon
+ * une correction de clause deviendrait une livraison de charte. */
+
+export interface BlocLegal {
+  type: 'paragraphe' | 'sous-titre' | 'liste' | 'encart' | 'definitions' | 'grille' | 'tableau'
+  texte?: string
+  ordonnee?: boolean
+  items?: string[]
+  ton?: 'clair' | 'important'
+  label?: string
+  entrees?: { cle: string; valeur: string }[]
+  cartes?: { titre: string; texte: string }[]
+  entetes?: string[]
+  lignes?: string[][]
+}
+
+export interface SectionLegale {
+  id: string
+  titre: string
+  icone?: string
+  blocs: BlocLegal[]
+}
+
+export interface DocumentLegalRendu {
+  titre: string
+  /** L'identifiant juridique (« cgvu-2026-02-22 »). AFFICHÉ, et ce n'est pas
+   *  décoratif : c'est ce que l'utilisateur cite quand il conteste. */
+  version: string
+  applicableAu: string
+  essentiel?: { label: string; points: string[] }
+  preambule?: BlocLegal[]
+  sections: SectionLegale[]
+  contact?: string[]
+}
+
+/* ⚠️ POURQUOI dangerouslySetInnerHTML EST ACCEPTABLE ICI, ET SEULEMENT ICI.
+ * Le texte porte trois balises et trois seulement — <strong>, <em>,
+ * <a href> — qui ont un sens JURIDIQUE : une clause mise en avant par
+ * l'auteur, un renvoi vers un autre contrat. Les retirer appauvrirait le
+ * document ; les rendre en texte brut afficherait des chevrons.
+ * Ce contenu vient d'un dépôt versionné, JAMAIS d'une saisie utilisateur, et
+ * un test de @zevra/legal refuse toute autre balise. Ne pas reprendre ce
+ * motif pour du contenu dont on ne maîtrise pas l'origine. */
+function Riche({ html, as: Balise = 'span', className }: { html: string; as?: ElementType; className?: string }) {
+  return <Balise className={className} dangerouslySetInnerHTML={{ __html: html }} />
+}
+
+function BlocRendu({ bloc }: { bloc: BlocLegal }) {
+  switch (bloc.type) {
+    case 'paragraphe':
+      return <Riche as="p" className="zv-body" html={bloc.texte ?? ''} />
+    case 'sous-titre':
+      return <h3 className="zv-card-title">{bloc.texte}</h3>
+    case 'liste': {
+      const Liste = bloc.ordonnee ? 'ol' : 'ul'
+      return (
+        <Liste className="zv-legal__liste">
+          {(bloc.items ?? []).map((item, i) => (
+            <Riche key={i} as="li" html={item} />
+          ))}
+        </Liste>
+      )
+    }
+    case 'encart':
+      // L'encart « En clair » COMMENTE la clause, il ne la remplace pas :
+      // d'où une surface d'accompagnement, jamais l'aplat d'une alerte.
+      return (
+        <aside
+          className={cx('zv-legal__encart', bloc.ton === 'important' && 'zv-legal__encart--important')}
+        >
+          {bloc.label && <span className="zv-legal__encart-label">{bloc.label}</span>}
+          <Riche as="p" className="zv-body zv-body--dense" html={bloc.texte ?? ''} />
+        </aside>
+      )
+    case 'definitions':
+      return (
+        <Rows>
+          {(bloc.entrees ?? []).map((e) => (
+            <RowsItem key={e.cle} cle={e.cle}>
+              <Riche html={e.valeur} />
+            </RowsItem>
+          ))}
+        </Rows>
+      )
+    case 'grille':
+      return (
+        <IndexList cols>
+          {(bloc.cartes ?? []).map((c, i) => (
+            <IndexItem key={c.titre} num={String(i + 1).padStart(2, '0')}>
+              <h4 className="zv-card-title">{c.titre}</h4>
+              <Riche as="p" className="zv-body zv-body--dense" html={c.texte} />
+            </IndexItem>
+          ))}
+        </IndexList>
+      )
+    case 'tableau':
+      return (
+        <table className="zv-legal__table">
+          {(bloc.entetes ?? []).length > 0 && (
+            <thead>
+              <tr>
+                {(bloc.entetes ?? []).map((e) => (
+                  <th key={e}>{e}</th>
+                ))}
+              </tr>
+            </thead>
+          )}
+          <tbody>
+            {(bloc.lignes ?? []).map((ligne, i) => (
+              <tr key={i}>
+                {ligne.map((cellule, j) => (
+                  <Riche key={j} as="td" html={cellule} />
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )
+    default:
+      return null
+  }
+}
+
+/** Le rendu d'un document contractuel. Le sommaire ne fait PAS partie du
+ *  composant : il se pose à côté avec `Rail`, dont les ancres sont les `id`
+ *  de section — c'est ce qui permet de le placer en marge sur la vitrine et
+ *  de l'omettre dans un tunnel d'inscription.
+ *
+ *  ⚠️ Ne jamais tronquer un document contractuel derrière un « voir plus » :
+ *  un texte qu'on accepte doit être lisible en entier à l'endroit où on
+ *  l'accepte. */
+export function LegalPage({
+  document,
+  className,
+  ...reste
+}: Div & { document: DocumentLegalRendu; className?: string }) {
+  return (
+    <article className={cx('zv-legal', className)} {...reste}>
+      <header className="zv-legal__tete">
+        <h1 className="zv-h2 zv-h2--sm">{document.titre}</h1>
+        <span className="zv-mono zv-mono--micro">
+          EN VIGUEUR AU {document.applicableAu} · VERSION {document.version}
+        </span>
+      </header>
+
+      {document.essentiel && document.essentiel.points.length > 0 && (
+        // Résumé, donc sans valeur contractuelle : il est présenté comme un
+        // encart, jamais comme le corps du document.
+        <Callout titre={document.essentiel.label}>
+          <ul className="zv-legal__liste">
+            {document.essentiel.points.map((p, i) => (
+              <Riche key={i} as="li" html={p} />
+            ))}
+          </ul>
+        </Callout>
+      )}
+
+      {(document.preambule ?? []).map((bloc, i) => (
+        <BlocRendu key={i} bloc={bloc} />
+      ))}
+
+      {document.sections.map((section) => (
+        <section key={section.id} id={section.id} className="zv-legal__section">
+          <h2 className="zv-h3">{section.titre}</h2>
+          {section.blocs.map((bloc, i) => (
+            <BlocRendu key={i} bloc={bloc} />
+          ))}
+        </section>
+      ))}
+
+      {(document.contact ?? []).length > 0 && (
+        <footer className="zv-legal__tete">
+          {(document.contact ?? []).map((ligne, i) => (
+            <Riche key={i} as="p" className="zv-body zv-body--dense" html={ligne} />
+          ))}
+        </footer>
+      )}
+    </article>
+  )
+}