zidane-ui 9.0.4 → 9.1.3

package/src/motion/springs.ts

@@ -1,413 +0,0 @@
-/**
- * The design system's motion vocabulary: ONE place every animation reads its
- * curve from, JS (`motion/react` components, `animate()`) and CSS alike.
- *
- * Which motion for what:
- *
- *   snap      indicators, pills, active chips, glyph swaps (a hint of overshoot)
- *   pop       dialogs and other surfaces that spring from their anchor
- *   menu      menus, popovers, dropdowns, hover cards, tooltips: one quick
- *             tween (opacity lands ahead of the scale, `menuTransition`),
- *             never a spring; `menu-exit` is its faster exit
- *   panel     full-window screens, sheets, side panels, the sidebar
- *   slide     horizontal content swaps (spaces list, lightbox steps), scroll glides
- *   settle    rows, collapses, crossfades, badges: no visible bounce
- *   exit      anything leaving, transform side: fast, straight, never a spring
- *   fade      opacity and colour entering: a soft ease-out tween, never a spring
- *   fade-out  opacity and colour leaving (the exit twin of `fade`)
- *
- * Movement (transform, size, position) springs: motion.dev's time-defined
- * spring (`visualDuration` + `bounce`) with a tween twin. Opacity and colour
- * never spring: a bouncy curve overshoots 1, clamps and ends abruptly. So an
- * element that springs its transform fades its opacity on its own curve:
- * `withFade('pop', prefs)` is the pop spring with `opacity` / colour /
- * filter keys on `fade` (exits pair with `fade-out`).
- *
- * Two switches on `<html>` pick what plays:
- *
- *   data-motion   off | reduced | full   (Appearance › Motion)
- *   data-springs  on  | off              (Appearance › Spring animations)
- *
- *   full + springs   movement springs, fades tween
- *   full, no springs movement on the tween twins, fades tween
- *   reduced          no movement (0ms; `MotionConfig reducedMotion` jumps
- *                    transforms in JS), fades a brief 140ms
- *   off              everything instant, exit timers included
- *
- * CSS consumes the same curves: `cssMotionVars` → `--zg-motion-<name>-duration`
- * / `-ease` (a spring becomes a CSS `linear()` easing sampled by motion's
- * `spring().toString()`, its duration the settle time), plus the shorthand
- * `--zg-motion-<name>` (duration + ease) from tokens.css. Split movement and
- * fade per property:
- *
- *   transition: transform var(--zg-motion-pop), opacity var(--zg-motion-fade);
- *   animation: zg-rise var(--zg-motion-pop) both, zg-fade-in var(--zg-motion-fade) both;
- *
- * Hover / press colour feedback is `--zg-motion-hover-*` (a short fixed tween
- * in every mode but `off`; Uno's `transition-colors` defaults to it).
- * `panelMotionVars` → `--zg-panel-ms` / `-ease` for the layout panels.
- * tokens.css ships the same values as static fallbacks (keyed on the two
- * attributes) for consumers without JS; `applyMotionVars` / `MotionProvider`
- * (motion/provider.tsx) write the live ones. JS exit timers read the vars
- * (`readExitMs` in presence.ts), never a hard-coded length.
- */
-import { spring, type TargetAndTransition, type Transition } from 'motion';
-import { useSyncExternalStore } from 'react';
-
-import { useMotionLevel, type MotionLevel } from './reduced';
-
-/**
- * Name of a motion in the design system's vocabulary. `snap`, `pop`, `panel`, `slide` and
- * `settle` are movement that springs; `exit` is a fast straight exit; `fade` and `fade-out` are
- * the opacity curves for entering and leaving; `menu` and `menu-exit` are the menu tweens.
- */
-export type MotionName =
-  'snap' | 'pop' | 'panel' | 'slide' | 'settle' | 'exit' | 'fade' | 'fade-out' | 'menu' | 'menu-exit';
-
-interface MotionSpec {
-  /** Spring: perceived duration in seconds and bounce (0 = critically damped). Absent: never springs. */
-  spring?: { visualDuration: number; bounce: number };
-  /** Tween (the twin, or the only curve): seconds + cubic-bezier. */
-  duration: number;
-  ease: readonly [number, number, number, number];
-  /** Opacity / colour: kept (briefly) under reduced motion; movement drops to 0. */
-  fade?: boolean;
-  /** Reduced motion keeps it as an opacity-only tween of this many seconds (the menus). */
-  reduced?: number;
-}
-
-/** `--zg-ease-out`: strong ease-out, the tween curve of `snap`, `pop`, `slide`, `settle` and `menu`. */
-const EASE_OUT = [0.23, 1, 0.32, 1] as const;
-/** `--zg-ease-drawer`: panels and sheets. */
-const EASE_DRAWER = [0.32, 0.72, 0, 1] as const;
-/** Exits accelerate away: shorter and never bouncy. */
-const EASE_IN = [0.4, 0, 1, 1] as const;
-/** Fades: a soft ease-out (cubic), so opacity lands gently instead of clamping. */
-const EASE_FADE = [0.33, 1, 0.68, 1] as const;
-
-/**
- * The curve of every {@link MotionName}: its spring (when it has one), tween duration in
- * seconds and easing.
- */
-export const MOTIONS: Readonly<Record<MotionName, MotionSpec>> = {
-  snap: { spring: { visualDuration: 0.28, bounce: 0.18 }, duration: 0.24, ease: EASE_OUT },
-  pop: { spring: { visualDuration: 0.22, bounce: 0.12 }, duration: 0.16, ease: EASE_OUT },
-  panel: { spring: { visualDuration: 0.32, bounce: 0.04 }, duration: 0.2, ease: EASE_DRAWER },
-  slide: { spring: { visualDuration: 0.34, bounce: 0.1 }, duration: 0.22, ease: EASE_OUT },
-  settle: { spring: { visualDuration: 0.26, bounce: 0.06 }, duration: 0.24, ease: EASE_OUT },
-  exit: { duration: 0.14, ease: EASE_IN },
-  fade: { duration: 0.2, ease: EASE_FADE, fade: true },
-  'fade-out': { duration: 0.14, ease: EASE_FADE, fade: true },
-  menu: { duration: 0.14, ease: EASE_OUT, reduced: 0.08 },
-  'menu-exit': { duration: 0.09, ease: EASE_IN, reduced: 0.08 },
-};
-
-/** A menu's enter opacity lands ahead of its scale: ~100ms of the 140ms `menu`. */
-export const MENU_FADE_RATIO = 0.7;
-
-/** Every {@link MotionName}, in the order of {@link MOTIONS}. */
-export const MOTION_NAMES = Object.keys(MOTIONS) as MotionName[];
-
-/** Hover / press colour feedback: one short tween, the same with springs on or off. */
-export const HOVER_MOTION = { duration: 0.15, ease: [0.4, 0, 0.2, 1] as const };
-
-/** The panel slider's default (ms): the `panel` spring's perceived duration. */
-export const DEFAULT_PANEL_MS = 200;
-
-/** The two switches that pick what plays: the motion level and whether movement springs. */
-export interface MotionPrefs {
-  /** Motion level. `off` is instant, `reduced` keeps brief fades, `full` plays all motion. */
-  level: MotionLevel;
-  /** Whether movement uses springs. When off, it uses the tween twins. */
-  springs: boolean;
-}
-
-/** Instant: what every motion resolves to with motion off. */
-export const INSTANT: Transition = { duration: 0 };
-
-/** Reduced motion: a short fade; transforms jump (MotionConfig `reducedMotion`). */
-export const REDUCED_FADE: Transition = { type: 'tween', duration: 0.14, ease: 'easeOut' };
-
-/** The values `withFade` puts on the fade curve: never sprung, whatever moves around them. */
-export const FADE_KEYS = [
-  'opacity',
-  'color',
-  'backgroundColor',
-  'borderColor',
-  'fill',
-  'stroke',
-  'filter',
-  'backdropFilter',
-] as const;
-
-const isExit = (name: MotionName) => name === 'exit' || name === 'fade-out' || name === 'menu-exit';
-
-/**
- * The motion transition for `name` under `prefs`. `visualDuration` overrides
- * the spec's duration (seconds; the panel slider), scaling the tween too.
- *
- * @param name - The motion to resolve.
- * @param prefs - The live motion level and spring switch.
- * @param visualDuration - Overrides the motion's duration, in seconds, for example from the panel
- * slider. A value of 0 or less is instant.
- * @returns A `motion` transition: instant when off, a short fade when reduced, otherwise a spring
- * or tween.
- */
-export function motionTransition(name: MotionName, prefs: MotionPrefs, visualDuration?: number): Transition {
-  if (prefs.level === 'off') return INSTANT;
-  const spec = MOTIONS[name];
-  if (prefs.level === 'reduced')
-    return spec.reduced === undefined ? REDUCED_FADE : { type: 'tween', duration: spec.reduced, ease: 'easeOut' };
-  if (visualDuration !== undefined && visualDuration <= 0) return INSTANT;
-  if (prefs.springs && spec.spring)
-    return { type: 'spring', visualDuration: visualDuration ?? spec.spring.visualDuration, bounce: spec.spring.bounce };
-  const scale = visualDuration !== undefined ? visualDuration / (spec.spring?.visualDuration ?? spec.duration) : 1;
-  return { type: 'tween', duration: spec.duration * scale, ease: [...spec.ease] };
-}
-
-/**
- * The fade curve for opacity / colour: `fade`, or `fade-out` for an exit.
- *
- * @param prefs - The live motion level and spring switch.
- * @param exit - Use the leaving curve, `fade-out`, instead of `fade`.
- * @returns The transition for opacity and colour.
- */
-export function fadeTransition(prefs: MotionPrefs, exit = false): Transition {
-  return motionTransition(exit ? 'fade-out' : 'fade', prefs);
-}
-
-/**
- * A menu's open (`menu`) or close (`menu-exit`) transition: one tween for
- * scale / position, with the enter's opacity on the same curve but shorter
- * (`MENU_FADE_RATIO`) so the surface is solid before it finishes growing.
- * Reduced: an opacity-only 80ms tween (pair it with no transform). Off: instant.
- *
- * @param prefs - The live motion level and spring switch.
- * @param exit - Use the close transition, `menu-exit`, instead of `menu`.
- * @returns The transition for a menu's scale and position, with a shorter opacity curve on enter.
- */
-export function menuTransition(prefs: MotionPrefs, exit = false): Transition {
-  const move = motionTransition(exit ? 'menu-exit' : 'menu', prefs);
-  const fade = !exit && prefs.level === 'full' ? { ...move, duration: MOTIONS.menu.duration * MENU_FADE_RATIO } : move;
-  return { ...move, opacity: fade } as Transition;
-}
-
-/**
- * `name`'s transition for movement, with every `FADE_KEYS` value on the
- * fade curve (`fade-out` when `name` is an exit): spring the transform,
- * fade the opacity. Pass it as a motion component's `transition`.
- *
- * @param name - The movement motion to use.
- * @param prefs - The live motion level and spring switch.
- * @param visualDuration - Overrides the motion's duration, in seconds, for example from the panel
- * slider. A value of 0 or less is instant.
- * @returns The movement transition with opacity and colour keys on the fade curve.
- */
-export function withFade(name: MotionName, prefs: MotionPrefs, visualDuration?: number): Transition {
-  const fade = fadeTransition(prefs, isExit(name));
-  const mixed: Record<string, unknown> = { ...motionTransition(name, prefs, visualDuration) };
-  for (const key of FADE_KEYS) mixed[key] = fade;
-  return mixed as Transition;
-}
-
-function splitCss(css: string): [string, string] {
-  // "550ms linear(0, 0.12, …, 1)": the spring sampled as a CSS easing, settle time first.
-  const space = css.indexOf(' ');
-  return [css.slice(0, space), css.slice(space + 1)];
-}
-
-const ms = (seconds: number) => `${Math.round(seconds * 1000)}ms`;
-const bezier = (ease: readonly number[]) => `cubic-bezier(${ease.join(', ')})`;
-
-/**
- * `--zg-motion-<name>-duration` / `-ease` for every motion and for `hover`,
- * for CSS that stays CSS. Below `full`, movement is 0ms; fades stay a brief
- * tween under `reduced`; `off` zeroes everything.
- *
- * @param prefs - The live motion level and spring switch.
- * @returns A map of custom property names to values.
- */
-export function cssMotionVars(prefs: MotionPrefs): Record<string, string> {
-  const vars: Record<string, string> = {};
-  const set = (name: string, duration: string, ease: string) => {
-    vars[`--zg-motion-${name}-duration`] = duration;
-    vars[`--zg-motion-${name}-ease`] = ease;
-  };
-  for (const name of MOTION_NAMES) {
-    const spec = MOTIONS[name];
-    if (prefs.level === 'off') set(name, '0ms', 'linear');
-    else if (prefs.level === 'reduced' && spec.reduced !== undefined) set(name, ms(spec.reduced), 'ease-out');
-    else if (prefs.level === 'reduced') set(name, spec.fade ? ms(0.14) : '0ms', spec.fade ? 'ease-out' : 'linear');
-    else if (prefs.springs && spec.spring)
-      set(name, ...splitCss(String(spring(spec.spring.visualDuration, spec.spring.bounce))));
-    else set(name, ms(spec.duration), bezier(spec.ease));
-  }
-  if (prefs.level === 'off') set('hover', '0ms', 'linear');
-  else set('hover', ms(HOVER_MOTION.duration), bezier(HOVER_MOTION.ease));
-  return vars;
-}
-
-/**
- * `--zg-panel-ms` / `--zg-panel-ease` for the layout panels (sidebar, side
- * panel, terminal drawer, tree column). They animate width / height in CSS
- * (a JS tween would re-lay out the chat column every frame), on the `panel`
- * spring sized by the user's slider: `panelMs` is the spring's perceived
- * duration; `--zg-panel-ms` becomes its settle time, which is also what
- * `usePresence` (`readPanelMs`) waits before unmounting a closed panel.
- *
- * @param panelMs - The panel spring's perceived duration, in ms. Zero or less makes panels instant.
- * @param prefs - The live motion level and spring switch.
- * @returns `--zg-panel-ms` and `--zg-panel-ease`.
- */
-export function panelMotionVars(panelMs: number, prefs: MotionPrefs): Record<string, string> {
-  if (prefs.level !== 'full' || panelMs <= 0) return { '--zg-panel-ms': '0ms', '--zg-panel-ease': 'linear' };
-  if (!prefs.springs) return { '--zg-panel-ms': `${panelMs}ms`, '--zg-panel-ease': bezier(MOTIONS.panel.ease) };
-  const [duration, ease] = splitCss(String(spring(panelMs / 1000, MOTIONS.panel.spring!.bounce)));
-  return { '--zg-panel-ms': duration, '--zg-panel-ease': ease };
-}
-
-/**
- * Every motion custom property for `prefs`: the named curves, hover and the panels.
- *
- * @param prefs - The live motion level and spring switch.
- * @param panelMs - The panel spring's perceived duration, in ms.
- * @returns A map of custom property names to values.
- */
-export function motionVars(prefs: MotionPrefs, panelMs: number = DEFAULT_PANEL_MS): Record<string, string> {
-  return { ...cssMotionVars(prefs), ...panelMotionVars(panelMs, prefs) };
-}
-
-/** Options of {@link applyMotionVars}. */
-export interface ApplyMotionOptions {
-  /** The panel slider (ms). Default `DEFAULT_PANEL_MS`. */
-  panelMs?: number;
-  /** Also write `data-motion` / `data-springs`. Default true; false when the attributes are the input. */
-  attributes?: boolean;
-}
-
-/**
- * Write the motion switches and every `--zg-motion-*` / `--zg-panel-*` var
- * on `root` (usually `<html>`): what an app calls when its motion settings
- * change, so it never copies the curves. Returns the vars written.
- *
- * @param root - The element to write to, usually `document.documentElement`.
- * @param prefs - The motion level and spring switch to apply.
- * @param options - See {@link ApplyMotionOptions}.
- */
-export function applyMotionVars(
-  root: HTMLElement,
-  prefs: MotionPrefs,
-  { panelMs = DEFAULT_PANEL_MS, attributes = true }: ApplyMotionOptions = {},
-): Record<string, string> {
-  const vars = motionVars(prefs, panelMs);
-  for (const [name, value] of Object.entries(vars)) root.style.setProperty(name, value);
-  if (attributes) {
-    root.dataset.motion = prefs.level;
-    root.dataset.springs = prefs.springs ? 'on' : 'off';
-    /*
-     * Present only below `full`, for rules that reach every element (`[data-motion-limited] *`).
-     * `[data-motion='off'] *` is tried by every element in every restyle and walks to the root
-     * for its ancestor, since `data-motion` is always set; a selector on an attribute that is
-     * absent is rejected at once by the browser's ancestor filter.
-     */
-    root.toggleAttribute('data-motion-off', prefs.level === 'off');
-    root.toggleAttribute('data-motion-limited', prefs.level !== 'full');
-  }
-  return vars;
-}
-
-function readSprings(): boolean {
-  return document.documentElement.dataset.springs !== 'off';
-}
-
-function subscribeSprings(onChange: () => void): () => void {
-  const observer = new MutationObserver(onChange);
-  observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-springs'] });
-  return () => observer.disconnect();
-}
-
-/** Spring animations on (`html[data-springs]` is not `off`). */
-export function useSprings(): boolean {
-  return useSyncExternalStore(subscribeSprings, readSprings, () => true);
-}
-
-/** Both switches, live. */
-export function useMotionPrefs(): MotionPrefs {
-  return { level: useMotionLevel(), springs: useSprings() };
-}
-
-/**
- * `motionTransition(name)` under the live preferences.
- *
- * @param name - The motion to resolve.
- * @param visualDuration - Overrides the motion's duration, in seconds, for example from the panel
- * slider. A value of 0 or less is instant.
- */
-export function useMotionTransition(name: MotionName, visualDuration?: number): Transition {
-  return motionTransition(name, useMotionPrefs(), visualDuration);
-}
-
-/**
- * `menuTransition` under the live preferences.
- *
- * @param exit - Use the close transition instead of the open one.
- */
-export function useMenuTransition(exit = false): Transition {
-  return menuTransition(useMotionPrefs(), exit);
-}
-
-/**
- * `withFade(name)` under the live preferences.
- *
- * @param name - The movement motion to use.
- * @param visualDuration - Overrides the motion's duration, in seconds, for example from the panel
- * slider. A value of 0 or less is instant.
- */
-export function useWithFade(name: MotionName, visualDuration?: number): Transition {
-  return withFade(name, useMotionPrefs(), visualDuration);
-}
-
-/**
- * A closing tab's `exit`, for every tab strip (tabs in an `AnimatePresence initial={false}`):
- * it folds to nothing on `settle` as it fades out, so the tabs after it flow left from where
- * they were. None with motion reduced or off: the tab goes at once and the rest close up.
- */
-export function useTabExit(): TargetAndTransition | undefined {
-  const prefs = useMotionPrefs();
-  if (prefs.level !== 'full') return undefined;
-  return {
-    width: 0,
-    opacity: 0,
-    overflow: 'hidden',
-    pointerEvents: 'none',
-    transition: { ...motionTransition('settle', prefs), opacity: fadeTransition(prefs, true) },
-  };
-}
-
-/** Both switches, read off `<html>` for imperative code. */
-export function currentMotionPrefs(): MotionPrefs {
-  const level = document.documentElement.dataset.motion;
-  return { level: level === 'off' || level === 'reduced' ? level : 'full', springs: readSprings() };
-}
-
-/**
- * Non-hook read for imperative animations (`animate()`, scroll glides).
- *
- * @param name - The motion to resolve.
- * @param visualDuration - Overrides the motion's duration, in seconds, for example from the panel
- * slider. A value of 0 or less is instant.
- */
-export function currentMotionTransition(name: MotionName, visualDuration?: number): Transition {
-  return motionTransition(name, currentMotionPrefs(), visualDuration);
-}
-
-/**
- * Non-hook `withFade`, for `animate()` calls that move and fade one element.
- *
- * @param name - The movement motion to use.
- * @param visualDuration - Overrides the motion's duration, in seconds, for example from the panel
- * slider. A value of 0 or less is instant.
- */
-export function currentWithFade(name: MotionName, visualDuration?: number): Transition {
-  return withFade(name, currentMotionPrefs(), visualDuration);
-}

package/src/motion/swap.tsx

@@ -1,216 +0,0 @@
-/**
- * State flips: an element that appears / disappears, or a slot whose
- * content is swapped by key (spinner → check → x).
- *
- *   Presence   keeps a leaving node mounted through a short exit and stamps
- *              `data-state="enter" | "exit"` for CSS (`.zg-presence`)
- *   Crossfade  stacks the outgoing and incoming nodes in one grid cell so one
- *              fades / scales out while the other fades / scales in
- *   useCadencedValue  holds a fast-changing value to a readable cadence
- *
- * Motion lives in styles/motion.css (`.zg-presence` / `.zg-crossfade`: the
- * transform on `snap` / `settle` and `exit`, opacity and blur on `fade` /
- * `fade-out`). How long a leaving node stays is read off the same vars
- * (`readExitMs`) when its exit starts: reduced motion keeps a brief fade,
- * off swaps at once. Layout-neutral: the container takes the size of its
- * largest child.
- */
-import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
-
-import { readExitMs, usePresence } from './presence';
-
-/** `settle` prop: how long after mounting a key change replaces the content instead of crossfading (a heuristic window, not a motion). */
-const SETTLE_MS = 200;
-
-/** Props for {@link Presence}. */
-export interface PresenceProps {
-  /** Whether the content is shown. When it turns false, the content stays mounted for its exit. */
-  show: boolean;
-  /** The content to show and animate out. */
-  children: ReactNode;
-  /** Extra classes on the wrapper (sizing, spacing). */
-  className?: string;
-  /** Inline styles on the root element, merged after the component's own. */
-  style?: CSSProperties;
-  /** Inline wrapper by default; `block` for full-width rows. */
-  display?: 'inline' | 'block';
-  /** `scale` (default) for glyphs; `text` blurs a line of words in and out, anchored left. */
-  variant?: 'scale' | 'text';
-}
-
-/**
- * Keeps `children` mounted for the exit (`readExitMs()`) after `show` flips
- * false so the exit animation plays. Renders nothing once the exit is done.
- *
- * @param props - Component props.
- */
-export function Presence({
-  show,
-  children,
-  className = '',
-  style,
-  display = 'inline',
-  variant = 'scale',
-}: PresenceProps) {
-  const { mounted } = usePresence(show, { exitMs: readExitMs });
-
-  if (!mounted) return null;
-
-  return (
-    <span
-      className={`zg-presence ${display === 'block' ? 'block' : 'inline-flex items-center'} ${className}`}
-      style={style}
-      data-state={show ? 'enter' : 'exit'}
-      data-variant={variant}
-    >
-      {children}
-    </span>
-  );
-}
-
-/** Props for {@link Crossfade}. */
-export interface CrossfadeProps {
-  /** Identity of the current content; a change triggers the swap. */
-  activeKey: string | number;
-  /** The current content. `null` is a valid empty slot. */
-  children: ReactNode;
-  /** Extra classes on the wrapping cell. */
-  className?: string;
-  /** Inline styles on the root element, merged after the component's own. */
-  style?: CSSProperties;
-  /**
-   * `scale` (default): the glyph swap, in/out through scale around the
-   * centre; right for spinners, checks and icons. `text`: for a line of
-   * words, anchored left; the old line blurs away, the new one sharpens
-   * into place, no scale.
-   */
-  variant?: 'scale' | 'text';
-  /**
-   * `text` only: which edge both lines hold to. `end` for text set against
-   * something on its right (a trailing slot): when the outgoing line leaves
-   * and the cell narrows, the line on show stays where it is.
-   */
-  align?: 'start' | 'end';
-  /**
-   * For content inside something that is itself still appearing (a line
-   * fading in): a key change in its first moments replaces the content
-   * without a crossfade, since two lines fading over each other inside a
-   * line that is fading in reads as a flicker.
-   */
-  settle?: boolean;
-}
-
-/**
- * Swaps content by key with a cross-fade: the previous node stays in the
- * same grid cell for the exit (`readExitMs()`) playing its exit while the new
- * one plays its enter; with motion off it is replaced at once. `children ===
- * null` is a valid state (empty slot).
- *
- * @param props - Component props.
- */
-export function Crossfade({
-  activeKey,
-  children,
-  className = '',
-  style,
-  variant = 'scale',
-  align = 'start',
-  settle = false,
-}: CrossfadeProps) {
-  const [previous, setPrevious] = useState<{ key: string | number; node: ReactNode } | null>(null);
-  const lastRef = useRef<{ key: string | number; node: ReactNode }>({ key: activeKey, node: children });
-  // The exit timer lives in a ref: this effect re-runs on every `children`
-  // change (each streaming tick), and a cleanup-owned timer would be
-  // cancelled by same-key re-renders, leaving the outgoing node mounted
-  // forever at opacity 0 and still sizing the grid cell.
-  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  // The first content was not swapped in, it was already there (a row
-  // mounting, a conversation opening): only later keys play the enter. With
-  // `settle`, a key change while the slot is still appearing replaces it.
-  const [mountedAt] = useState(() => performance.now());
-  const [firstKey, setFirstKey] = useState(activeKey);
-  const [swapped, setSwapped] = useState(false);
-  if (!swapped && activeKey !== firstKey) {
-    // eslint-disable-next-line react-hooks/purity -- the appearing window is a wall-clock check, decided while rendering
-    if (settle && performance.now() - mountedAt < SETTLE_MS) setFirstKey(activeKey);
-    else setSwapped(true);
-  }
-
-  useEffect(() => {
-    const last = lastRef.current;
-    lastRef.current = { key: activeKey, node: children };
-    if (last.key === activeKey || !swapped) return;
-    if (timer.current) clearTimeout(timer.current);
-    timer.current = null;
-    const exitMs = readExitMs();
-    if (exitMs <= 0) {
-      setPrevious(null);
-      return;
-    }
-    setPrevious(last);
-    timer.current = setTimeout(() => {
-      timer.current = null;
-      setPrevious(null);
-    }, exitMs);
-  }, [activeKey, children, swapped]);
-
-  useEffect(
-    () => () => {
-      if (timer.current) clearTimeout(timer.current);
-    },
-    [],
-  );
-
-  return (
-    <span className={`zg-crossfade ${className}`} style={style} data-variant={variant} data-align={align}>
-      {previous && previous.key !== activeKey && (
-        <span key={`out-${String(previous.key)}`} className="zg-crossfade-item" data-state="exit" aria-hidden>
-          {previous.node}
-        </span>
-      )}
-      <span key={`in-${String(activeKey)}`} className="zg-crossfade-item" data-state={swapped ? 'enter' : 'idle'}>
-        {children}
-      </span>
-    </span>
-  );
-}
-
-/**
- * Hold a fast-changing value to a readable cadence: at most one change every
- * `ms`, the newest value always wins, and the last one always lands (a
- * trailing update fires when the source goes quiet). The first value shows
- * at once.
- *
- * @param value - The source value, which may change faster than it should show.
- * @param ms - The minimum time between shown changes, in ms.
- * @returns The value to show.
- */
-export function useCadencedValue<T>(value: T, ms: number): T {
-  const [shown, setShown] = useState(value);
-  const last = useRef(Number.NEGATIVE_INFINITY);
-  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const latest = useRef(value);
-  useLayoutEffect(() => {
-    latest.current = value;
-  });
-
-  useEffect(() => {
-    if (Object.is(value, shown)) return;
-    const wait = Math.max(0, ms - (performance.now() - last.current));
-    if (timer.current) clearTimeout(timer.current);
-    timer.current = setTimeout(() => {
-      timer.current = null;
-      last.current = performance.now();
-      setShown(latest.current);
-    }, wait);
-    // No cleanup: a newer value reschedules above; unmount clears below.
-  }, [value, shown, ms]);
-
-  useEffect(
-    () => () => {
-      if (timer.current) clearTimeout(timer.current);
-    },
-    [],
-  );
-  return shown;
-}