@zevra/ui 0.15.1 → 0.16.0

package/react/layout.tsx

@@ -354,6 +354,59 @@ export function LockupWord({
   return <img alt={alt} className={cx('zv-lockup__word', className)} {...reste} />
 }
 
+/* ─── Rail de lecture ──────────────────────────────────────────────── */
+
+/** La table des matières d'une page longue, posée sur le côté. Elle navigue
+ *  (chaque entrée est une ancre) et elle suit — poser `data-zv-rail` et
+ *  importer `@zevra/ui/rail.js` pour que l'entrée courante s'allume. Sans le
+ *  module, le rail navigue toujours : rien ne casse, le suivi manque.
+ *
+ *  ⚠️ Elle demande de la place à côté du texte, et disparaît sous le point
+ *  de rupture : un rail fixe sur un téléphone se pose sur la lecture. */
+export function Rail({
+  gauche,
+  className,
+  ...reste
+}: Omit<HTMLAttributes<HTMLElement>, 'className'> & {
+  gauche?: boolean
+  className?: string
+  'aria-label': string
+}) {
+  return (
+    <nav
+      data-zv-rail
+      className={cx('zv-rail zv-layer-chrome', gauche && 'zv-rail--gauche', className)}
+      {...reste}
+    />
+  )
+}
+
+/** ⚠️ `href` doit désigner une ancre de la page (`#section`) : c'est elle
+ *  que le module surveille, et c'est le balisage qui fait foi — il n'y a
+ *  pas de liste de sections à tenir à jour ailleurs. */
+export function RailItem({
+  courant,
+  className,
+  children,
+  ...reste
+}: Omit<HTMLAttributes<HTMLAnchorElement>, 'className'> & {
+  courant?: boolean
+  href: string
+  className?: string
+  children?: ReactNode
+}) {
+  return (
+    <a
+      aria-current={courant ? 'true' : undefined}
+      className={cx('zv-rail__item', courant && 'zv-rail__item--on', className)}
+      {...reste}
+    >
+      <span className="zv-mono zv-mono--micro">{children}</span>
+      <span className="zv-rail__dot" aria-hidden="true" />
+    </a>
+  )
+}
+
 /* ─── Frise d'étapes ───────────────────────────────────────────────── */
 
 export interface StepsProps extends Div {

package/src/layout.css

@@ -795,6 +795,107 @@
   }
 }
 
+/* ─── Rail de lecture ───────────────────────────────────────────────────
+ *
+ * La table des matières d'une page longue, posée sur le côté : un libellé,
+ * un point, et le point courant qui s'allume. Elle NAVIGUE (chaque entrée
+ * est une ancre) et elle SUIT (le module rail.js marque la section en
+ * cours) — les deux, sinon ce n'est qu'un décor qui occupe la marge.
+ *
+ * ⚠️ Elle demande de la place à côté du texte. Sous le point de rupture
+ * elle disparaît : un rail fixe sur un téléphone se pose sur la lecture.
+ * Au-dessus, c'est la mesure de la page qui décide — une page dont le
+ * contenu court d'un bord à l'autre jusqu'à 1100px gagnera à relever le
+ * seuil chez elle.
+ *
+ * L'empilement vient de .zv-layer-chrome, à poser avec : le rail est du
+ * chrome, il passe au-dessus des décors de scène. */
+
+.zv-rail {
+  position: fixed;
+  right: 40px;
+  top: 50%;
+  translate: 0 -50%;
+  display: none;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 16px;
+}
+
+@media (min-width: 768px) {
+  .zv-rail {
+    display: flex;
+  }
+}
+
+/* Sur la gauche, l'ordre s'inverse : le point précède le libellé, sinon il
+ * se retrouve au milieu de la colonne au lieu d'en tenir le bord. */
+.zv-rail--gauche {
+  right: auto;
+  left: 40px;
+  align-items: flex-start;
+}
+
+.zv-rail--gauche .zv-rail__item {
+  flex-direction: row-reverse;
+}
+
+.zv-rail__item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 3px 0;
+  color: var(--muted);
+  text-decoration: none;
+  /* Un rail flotte au-dessus de ce que la page met dans sa marge : un
+   * libellé gris pâle sur un décor pâle devient illisible par manque de
+   * contraste, sans qu'aucun empilement soit en cause. Le halo couleur
+   * papier le détache de tout ce qui passe dessous, sans lui donner de
+   * cadre. */
+  text-shadow:
+    0 0 6px var(--paper),
+    0 0 12px var(--paper);
+  transition: color 160ms var(--zv-easing, cubic-bezier(0.2, 0.7, 0.2, 1));
+}
+
+/* Le libellé est posé au registre mono par l'appelant : il doit suivre la
+ * couleur de son entrée, pas garder la sienne. */
+.zv-rail__item .zv-mono {
+  color: inherit;
+}
+
+.zv-rail__item:hover {
+  color: var(--accent-deep);
+}
+
+.zv-rail__dot {
+  width: 8px;
+  height: 8px;
+  flex: none;
+  border-radius: 50%;
+  background: var(--accent-line);
+  transition:
+    background 160ms var(--zv-easing, cubic-bezier(0.2, 0.7, 0.2, 1)),
+    scale 160ms var(--zv-easing, cubic-bezier(0.2, 0.7, 0.2, 1));
+}
+
+.zv-rail__item:hover .zv-rail__dot {
+  background: var(--accent);
+  scale: 1.35;
+}
+
+/* L'entrée courante, posée par rail.js. Le halo du point est le seul
+ * signal dont une navigation discrète a besoin — pas de fond, pas de
+ * filet. */
+.zv-rail__item--on {
+  color: var(--accent-deep);
+}
+
+.zv-rail__item--on .zv-rail__dot {
+  background: var(--iris);
+  box-shadow: 0 0 0 4px color-mix(in srgb, var(--iris) 18%, transparent);
+}
+
 /* ─── Le seuil d'une nav riche ──────────────────────────────────────────
  *
  * La bascule vers le tiroir est à 767px, réglée sur la nav de référence :

package/src/rail.js

@@ -0,0 +1,94 @@
+/* Zevra UI — rail.js : le rail de lecture suit la section en cours.
+ *
+ * Rôle exact, et rien d'autre : poser `.zv-rail__item--on` et
+ * `aria-current` sur l'entrée dont la section est à l'écran. La navigation
+ * elle-même est du HTML — chaque entrée est une ancre, et elle fonctionne
+ * sans ce module.
+ *
+ * Le contrat, en un attribut :
+ *   [data-zv-rail]   le rail (.zv-rail). Ses entrées sont ses <a href="#…">,
+ *                    et chaque href désigne la cible à surveiller.
+ *
+ * Rien à déclarer d'autre : l'ordre des entrées, leurs cibles et leur
+ * nombre se lisent dans le balisage. Un rail dont une ancre ne résout pas
+ * garde l'entrée cliquable et l'ignore au suivi, plutôt que de décaler
+ * tout le reste — c'est le décalage silencieux qui coûte cher.
+ *
+ * ─── Pourquoi pas un IntersectionObserver ───────────────────────────────
+ * Parce que les ancres d'un rail sont souvent des points MATÉRIELS de 1px
+ * posés en tête de section. Réduit à sa bande centrale, l'observateur ne
+ * les voit traverser que pendant quelques images — un défilement rapide
+ * saute la bande entière et l'entrée ne s'allume jamais. On lit donc la
+ * position : l'entrée courante est la DERNIÈRE dont l'ancre a passé la
+ * ligne de lecture. C'est déterministe, quelle que soit la vitesse.
+ *
+ * S'importe une fois par page : `import '@zevra/ui/rail.js'`. Sans lui, le
+ * rail navigue mais ne suit pas — dégradation douce, pas de page cassée.
+ */
+(() => {
+  if (typeof document === 'undefined') return
+  if (document.documentElement.dataset.zvRail === 'on') return
+  document.documentElement.dataset.zvRail = 'on'
+
+  /** Hauteur de la ligne de lecture, en fraction du viewport. 45 % : un peu
+   *  au-dessus du milieu, là où l'œil se pose vraiment. */
+  const LIGNE = 0.45
+
+  const rails = () => Array.from(document.querySelectorAll('[data-zv-rail]'))
+
+  const suivre = (rail) => {
+    const entrees = Array.from(rail.querySelectorAll('a[href^="#"]'))
+    if (!entrees.length) return
+
+    const cibles = entrees.map((a) => {
+      const id = decodeURIComponent(a.getAttribute('href').slice(1))
+      return id ? document.getElementById(id) : null
+    })
+    if (!cibles.some(Boolean)) return
+
+    let courant = -1
+    const marquer = (i) => {
+      if (i === courant) return
+      courant = i
+      entrees.forEach((a, k) => {
+        a.classList.toggle('zv-rail__item--on', k === i)
+        if (k === i) a.setAttribute('aria-current', 'true')
+        else a.removeAttribute('aria-current')
+      })
+    }
+
+    const relire = () => {
+      const ligne = window.innerHeight * LIGNE
+      let actif = 0
+      for (let i = 0; i < cibles.length; i++) {
+        const c = cibles[i]
+        if (c && c.getBoundingClientRect().top <= ligne) actif = i
+      }
+      marquer(actif)
+    }
+
+    // Une lecture par image au plus : le défilement émet bien plus souvent
+    // que l'écran ne se rafraîchit, et chaque lecture coûte un reflow.
+    let prevu = false
+    const planifier = () => {
+      if (prevu) return
+      prevu = true
+      requestAnimationFrame(() => {
+        prevu = false
+        relire()
+      })
+    }
+
+    addEventListener('scroll', planifier, { passive: true })
+    addEventListener('resize', planifier, { passive: true })
+    relire()
+  }
+
+  const demarrer = () => rails().forEach(suivre)
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', demarrer, { once: true })
+  } else {
+    demarrer()
+  }
+})()