@teamofsilicons/silicon-ui 0.2.0 → 0.4.0

package/eslint.js

@@ -7,6 +7,7 @@
  *
  * Options:
  *   files     globs the rules apply to (default: every .tsx and .jsx file)
+ *   allowExperimental   components whose experimental parts or prop values this app may use (a deliberate, reviewable opt-in)
  *   ignores   globs they skip (for example a vendored exception)
  *   elements  override the element → component table below
  *
@@ -14,6 +15,17 @@
  * if your own config also sets either rule, put this one last and move your entries into `extraSyntax` / `extraImports`.
  */
 
+import fs from "node:fs";
+
+/** This release's catalog (components.json next to this file): which components, parts or prop values are experimental. */
+function catalog() {
+  try {
+    return JSON.parse(fs.readFileSync(new URL("./components.json", import.meta.url), "utf8"));
+  } catch {
+    return [];
+  }
+}
+
 /** Raw elements Silicon UI already has a component for. */
 export const ELEMENTS = {
   button: "Use Button (actions) or ButtonLink (navigation) from @teamofsilicons/silicon-ui.",
@@ -34,7 +46,27 @@ const IMPORTS = [
   },
 ];
 
-export default function siliconUi({ files = ["**/*.{tsx,jsx}"], ignores = [], elements = ELEMENTS, extraSyntax = [], extraImports = [] } = {}) {
+export default function siliconUi({ files = ["**/*.{tsx,jsx}"], ignores = [], elements = ELEMENTS, extraSyntax = [], extraImports = [], allowExperimental = [] } = {}) {
+  const entries = catalog().filter(entry => !allowExperimental.includes(entry.name));
+  const optIn = name => `To try it, add "${name}" to siliconUi({ allowExperimental }) in your ESLint config.`;
+  // A whole experimental component: any import of it.
+  const gated = entries.filter(entry => entry.status === "experimental").map(entry => ({
+    regex: `^@teamofsilicons/silicon-ui/${entry.name}$`,
+    message: `${entry.name} is experimental: it may still change and is not for production. ${optIn(entry.name)}`,
+  }));
+  // Experimental parts of a stable component: only those named imports.
+  const gatedParts = entries.filter(entry => entry.status !== "experimental" && entry.experimentalExports?.length).map(entry => ({
+    name: `@teamofsilicons/silicon-ui/${entry.name}`,
+    importNames: entry.experimentalExports,
+    message: `These parts of ${entry.name} are experimental: they may still change and are not for production. ${optIn(entry.name)}`,
+  }));
+  // Experimental values of a stable component's prop, such as <Button size="xs">. The value "*" gates a new prop
+  // whatever its value, such as <Breadcrumb maxItems={3}>.
+  const gatedProps = entries.flatMap(entry => Object.entries(entry.experimentalProps ?? {}).flatMap(([component, props]) =>
+    Object.entries(props).flatMap(([prop, values]) => values.map(value => ({
+      selector: `JSXOpeningElement[name.name="${component}"] > JSXAttribute[name.name="${prop}"]${value === "*" ? "" : `[value.value="${value}"]`}`,
+      message: `${component} ${value === "*" ? prop : `${prop}="${value}"`} is experimental: it may still change and is not for production. ${optIn(entry.name)}`,
+    })))));
   const syntax = Object.entries(elements).map(([name, message]) => ({
     selector: `JSXOpeningElement[name.type="JSXIdentifier"][name.name="${name}"]`,
     message: `<${name}> is not allowed here. ${message}`,
@@ -45,8 +77,8 @@ export default function siliconUi({ files = ["**/*.{tsx,jsx}"], ignores = [], el
       files,
       ignores,
       rules: {
-        "no-restricted-syntax": ["error", ...syntax, ...extraSyntax],
-        "no-restricted-imports": ["error", { patterns: [...IMPORTS, ...extraImports] }],
+        "no-restricted-syntax": ["error", ...syntax, ...gatedProps, ...extraSyntax],
+        "no-restricted-imports": ["error", { paths: gatedParts, patterns: [...IMPORTS, ...gated, ...extraImports] }],
       },
     },
   ];

package/lib/fluid-hover.d.ts

@@ -0,0 +1,83 @@
+import type { FocusEvent, MouseEvent, PointerEvent, RefObject } from "react";
+/** An item's box in the container's own layout space (unaffected by transforms or scrolling). */
+export interface FluidRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export interface FluidHoverState {
+    /** Where the highlight sits, or null when nothing is lit. */
+    rect: FluidRect | null;
+    /** The lit item. */
+    item: HTMLElement | null;
+    /** False when the highlight should jump (keyboard, a resize) rather than travel. */
+    glide: boolean;
+    /** Steps on each new pointer entry, so the highlight fades in where it lands. */
+    session: number;
+}
+export interface FluidHoverOptions {
+    /** Selector for the items inside the container. */
+    items: string;
+    /** "y" for lists (default), "x" for a row of tabs, "xy" for grids. */
+    axis?: "x" | "y" | "xy";
+    /** Items the highlight skips (and a gap click never activates). Defaults to disabled or aria-disabled items. */
+    isItemDisabled?: (item: HTMLElement) => boolean;
+    /** "skip" (default) lights the nearest enabled item even over a disabled one; "clear" lights nothing over a disabled item (a calendar's unavailable days). */
+    disabled?: "skip" | "clear";
+    /** Route a click in a gap to the lit item. On by default; turn it off where empty space should stay inert. */
+    gapClick?: boolean;
+    /** Light the item that receives keyboard focus. On by default. */
+    followFocus?: boolean;
+}
+/** The item's box relative to the container, summing offsets through positioned ancestors in between. */
+export declare function rectOf(item: HTMLElement, container: HTMLElement): FluidRect;
+/**
+ * The item the pointer is inside, or else the one whose edge is nearest along the axis (both axes for a grid). Edges, not
+ * centres, so a gap next to a wide item still lights the item the pointer is closer to.
+ */
+export declare function pickNearest(items: HTMLElement[], x: number, y: number, axis: "x" | "y" | "xy"): HTMLElement | null;
+export declare function useFluidHover<T extends HTMLElement>(container: RefObject<T | null>, options: FluidHoverOptions): {
+    handlers: {
+        onMouseEnter: () => void;
+        onMouseMove: (event: MouseEvent<T>) => void;
+        onMouseLeave: () => void;
+        onKeyDownCapture: () => void;
+        onFocus: (event: FocusEvent<T>) => void;
+        onBlur: (event: FocusEvent<T>) => void;
+        onClick: (event: MouseEvent<T>) => void;
+    };
+    reset: () => void;
+    light: (item: HTMLElement | null, glide: boolean) => void;
+    /** Where the highlight sits, or null when nothing is lit. */
+    rect: FluidRect | null;
+    /** The lit item. */
+    item: HTMLElement | null;
+    /** False when the highlight should jump (keyboard, a resize) rather than travel. */
+    glide: boolean;
+    /** Steps on each new pointer entry, so the highlight fades in where it lands. */
+    session: number;
+};
+export interface NearestItemOptions extends Omit<FluidHoverOptions, "followFocus"> {
+    /** Called with the nearest enabled item as the mouse moves over the container. */
+    onPick: (item: HTMLElement) => void;
+}
+/**
+ * Fluid hover's picking without its highlight, for a list that already keeps its own active item and highlight (a listbox
+ * with aria-activedescendant, a roving list): the mouse picks the nearest enabled item, gaps and padding included, and a
+ * click in a gap goes to that item. Spread the result on the container.
+ */
+export declare function useNearestItem<T extends HTMLElement>({ items: selector, axis, isItemDisabled, gapClick, onPick }: NearestItemOptions): {
+    onPointerMove: (event: PointerEvent<T>) => void;
+    onClick: (event: MouseEvent<T>) => void;
+};
+export interface FluidHoverHighlightProps {
+    /** The state from useFluidHover (or any { rect, glide, session }). */
+    hover: Pick<FluidHoverState, "rect" | "glide" | "session">;
+    /** Radius, fill, z-index. The container must be position: relative; the highlight is placed at its top-left corner. */
+    className?: string;
+    /** Extra attributes for styling, such as data-tone. */
+    tone?: string;
+}
+/** The one highlight a fluid hover set renders: it springs between items on transforms, and fades in and out. */
+export declare function FluidHoverHighlight({ hover, className, tone }: FluidHoverHighlightProps): import("react").JSX.Element;

package/lib/fluid-hover.js

@@ -0,0 +1,184 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Fluid hover: in a set of items (a menu, a list, tabs, a grid), the item nearest the pointer is lit, even while the
+ * pointer is in a gap, the padding or past the last item, and one highlight springs between items. A click in a gap goes
+ * to the lit item, so what is lit is what a click hits. A new pointer entry fades the highlight in where it lands instead
+ * of sliding it over from the last item. The keyboard moves it without travel, and reduced motion keeps the fade but
+ * drops the travel.
+ *
+ *   const list = useRef<HTMLUListElement>(null);
+ *   const hover = useFluidHover(list, { items: "[data-item]" });
+ *   <ul ref={list} className={styles.list} {...hover.handlers}>      // .list { position: relative }
+ *     <FluidHoverHighlight hover={hover} className={styles.highlight} />
+ *     …items…
+ *   </ul>
+ *
+ * Adapted from Fluid Functionalism's use-fluid-hover and fluid-hover-highlight by Micka Touillaud (MIT),
+ * https://github.com/mickadesign/fluid-functionalism. Items are found by a selector instead of registering themselves,
+ * so a component adopts it without changing its items.
+ */
+import { useEffect, useEffectEvent, useRef, useState } from "react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { motionTokens } from "./motion-tokens.js";
+const defaultDisabled = (item) => item.matches(":disabled, [aria-disabled='true'], [data-disabled]");
+/** Controls that sit between items keep their own clicks. */
+const CONTROL = "input, textarea, select, button, a, summary, [contenteditable], [role='textbox'], [role='searchbox'], [role='button']";
+/** The item's box relative to the container, summing offsets through positioned ancestors in between. */
+export function rectOf(item, container) {
+    let top = item.offsetTop, left = item.offsetLeft;
+    let parent = item.offsetParent;
+    while (parent && parent !== container && container.contains(parent)) {
+        top += parent.offsetTop + parent.clientTop;
+        left += parent.offsetLeft + parent.clientLeft;
+        parent = parent.offsetParent;
+    }
+    return { top, left, width: item.offsetWidth, height: item.offsetHeight };
+}
+/**
+ * The item the pointer is inside, or else the one whose edge is nearest along the axis (both axes for a grid). Edges, not
+ * centres, so a gap next to a wide item still lights the item the pointer is closer to.
+ */
+export function pickNearest(items, x, y, axis) {
+    let nearest = null, best = Infinity;
+    for (const item of items) {
+        const r = item.getBoundingClientRect();
+        if (!r.width && !r.height)
+            continue;
+        if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom)
+            return item;
+        const dx = Math.max(r.left - x, 0, x - r.right), dy = Math.max(r.top - y, 0, y - r.bottom);
+        const distance = axis === "x" ? dx : axis === "y" ? dy : Math.hypot(dx, dy);
+        if (distance < best) {
+            best = distance;
+            nearest = item;
+        }
+    }
+    return nearest;
+}
+/** Hands a gap click to the item as a real mouse click (detail, modifiers and coordinates kept), so the item reads it as a pointer press, not a keyboard one. */
+function forwardClick(item, event) {
+    const { detail, clientX, clientY, screenX, screenY, ctrlKey, shiftKey, altKey, metaKey, button, buttons } = event;
+    item.dispatchEvent(new globalThis.MouseEvent("click", { bubbles: true, cancelable: true, composed: true, view: window, detail, clientX, clientY, screenX, screenY, ctrlKey, shiftKey, altKey, metaKey, button, buttons }));
+}
+/** Whether an event happened inside the element whose handler hears it, not in a portalled child (a submenu, a tooltip). */
+const isOwn = (event) => !(event.currentTarget instanceof Node) || !(event.target instanceof Node) || event.currentTarget.contains(event.target);
+export function useFluidHover(container, options) {
+    const { items: selector, axis = "y", isItemDisabled = defaultDisabled, disabled = "skip", gapClick = true, followFocus = true } = options;
+    const [state, setState] = useState({ rect: null, item: null, glide: false, session: 0 });
+    const current = useRef(state);
+    const pointer = useRef(false);
+    const entering = useRef(false);
+    const frame = useRef(0);
+    function commit(next) {
+        const prev = current.current;
+        if (prev.item === next.item && prev.session === next.session && sameRect(prev.rect, next.rect))
+            return;
+        current.current = next;
+        setState(next);
+    }
+    function light(item, glide) {
+        const root = container.current;
+        if (!root || !item)
+            return commit({ ...current.current, rect: null, item: null, glide });
+        let session = current.current.session;
+        if (entering.current) {
+            entering.current = false;
+            session += 1;
+        }
+        commit({ rect: rectOf(item, root), item, glide: glide && session === current.current.session, session });
+    }
+    const enabledItems = () => {
+        const root = container.current;
+        return root ? [...root.querySelectorAll(selector)].filter(item => !isItemDisabled(item)) : [];
+    };
+    // The lit item can move under a still highlight (a resize, content above it changing): follow it without travel.
+    const follow = useEffectEvent(() => { const { item } = current.current; if (item?.isConnected)
+        light(item, false); });
+    useEffect(() => {
+        const root = container.current;
+        if (!root || typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => follow());
+        observer.observe(root);
+        return () => observer.disconnect();
+    }, [container]);
+    useEffect(() => () => cancelAnimationFrame(frame.current), []);
+    const handlers = {
+        onMouseEnter: () => { entering.current = true; },
+        onMouseMove: (event) => {
+            if (!isOwn(event))
+                return;
+            pointer.current = true;
+            const { clientX, clientY } = event;
+            cancelAnimationFrame(frame.current);
+            frame.current = requestAnimationFrame(() => {
+                const over = disabled === "clear" ? document.elementFromPoint(clientX, clientY)?.closest(selector) : null;
+                light(over && isItemDisabled(over) ? null : pickNearest(enabledItems(), clientX, clientY, axis), true);
+            });
+        },
+        onMouseLeave: () => { cancelAnimationFrame(frame.current); entering.current = false; light(null, false); },
+        onKeyDownCapture: () => { pointer.current = false; },
+        onFocus: (event) => {
+            if (!followFocus || pointer.current || !isOwn(event))
+                return;
+            const item = event.target instanceof HTMLElement ? event.target.closest(selector) : null;
+            if (item && container.current?.contains(item) && !isItemDisabled(item))
+                light(item, false);
+        },
+        onBlur: (event) => {
+            if (!pointer.current && !event.currentTarget.contains(event.relatedTarget))
+                light(null, false);
+        },
+        onClick: (event) => {
+            if (!gapClick || !isOwn(event))
+                return;
+            const target = event.target;
+            if (!target.isConnected || target.closest(selector) || target.closest(CONTROL))
+                return;
+            const { item } = current.current;
+            if (item?.isConnected && !isItemDisabled(item))
+                forwardClick(item, event);
+        },
+    };
+    /** Clears the highlight at once, such as when a menu opens again. */
+    const reset = () => { cancelAnimationFrame(frame.current); entering.current = true; light(null, false); };
+    return { ...state, handlers, reset, light };
+}
+/**
+ * Fluid hover's picking without its highlight, for a list that already keeps its own active item and highlight (a listbox
+ * with aria-activedescendant, a roving list): the mouse picks the nearest enabled item, gaps and padding included, and a
+ * click in a gap goes to that item. Spread the result on the container.
+ */
+// A hook only so callbacks that touch refs can be passed during render; it keeps no state.
+export function useNearestItem({ items: selector, axis = "y", isItemDisabled = defaultDisabled, gapClick = true, onPick }) {
+    const nearest = (event) => {
+        if (!isOwn(event))
+            return null;
+        const items = [...event.currentTarget.querySelectorAll(selector)].filter(item => !isItemDisabled(item));
+        return pickNearest(items, event.clientX, event.clientY, axis);
+    };
+    return {
+        onPointerMove: (event) => { if (event.pointerType !== "mouse")
+            return; const item = nearest(event); if (item)
+            onPick(item); },
+        onClick: (event) => {
+            if (!gapClick)
+                return;
+            const target = event.target;
+            if (!target.isConnected || target.closest(selector) || target.closest(CONTROL))
+                return;
+            const item = nearest(event);
+            if (item)
+                forwardClick(item, event);
+        },
+    };
+}
+const sameRect = (a, b) => a === b || (!!a && !!b && a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height);
+/** The one highlight a fluid hover set renders: it springs between items on transforms, and fades in and out. */
+export function FluidHoverHighlight({ hover, className, tone }) {
+    const reduced = useReducedMotion() ?? false;
+    const { rect, glide, session } = hover;
+    const place = rect ? { x: rect.left, y: rect.top, width: rect.width, height: rect.height } : undefined;
+    return (_jsx(AnimatePresence, { initial: false, children: place ? (_jsx(motion.span, { className: className, "data-tone": tone, "aria-hidden": "true", style: { position: "absolute", top: 0, left: 0, pointerEvents: "none" }, initial: { opacity: 0, ...place }, animate: { opacity: 1, ...place }, exit: { opacity: 0, transition: motionTokens.spring.fast.exit }, transition: { default: glide && !reduced ? motionTokens.spring.fast : { duration: 0 }, opacity: { duration: motionTokens.duration.fast } } }, session)) : null }));
+}

package/lib/menu-highlight.d.ts

@@ -1,28 +1,41 @@
-import type { FocusEvent } from "react";
-type Highlight = {
+import type { FocusEvent, MouseEvent } from "react";
+import { type FluidRect } from "./fluid-hover.js";
+/** A fluid hover highlight in a menu: where it sits, whether it travels, its pointer session, and its tone. */
+type FluidHighlight = {
+    rect: FluidRect | null;
+    glide: boolean;
+    session: number;
+    danger: boolean;
+};
+/** A marker positioned by top and height only (a list's current-page marker). */
+type BarHighlight = {
     top: number;
     height: number;
     danger: boolean;
     glide: boolean;
 };
 /**
- * One highlight that glides between the items of a Radix menu or listbox for the pointer, and jumps instantly for the keyboard.
- * Radix focuses the highlighted item, so the highlight follows focus inside the content. Spread `contentProps` on the content,
- * call `reset` when it opens, and render `<MenuHighlight state={highlight} className={styles.highlight} />` as its first child.
- * Items mark a destructive tone with `data-tone="danger"`.
+ * Fluid hover for a Radix menu or listbox (lib/fluid-hover): the item nearest the pointer is lit, gaps and padding
+ * included, a click in a gap picks the lit item, and the keyboard moves the highlight with Radix's focus, without travel.
+ * Spread `contentProps` on the content, call `reset` when it opens, and render `<MenuHighlight state={highlight} … />`
+ * as its first child. Items mark a destructive tone with `data-tone="danger"`.
  */
 export declare function useMenuHighlight(itemSelector?: string): {
-    highlight: Highlight | null;
+    highlight: FluidHighlight;
     reset: () => void;
     contentProps: {
-        onFocus: (event: FocusEvent<HTMLElement>) => void;
-        onPointerMoveCapture: () => void;
+        onMouseEnter: (event: MouseEvent<HTMLElement>) => void;
+        onMouseMove: (event: MouseEvent<HTMLElement>) => void;
+        onMouseLeave: () => void;
         onKeyDownCapture: () => void;
+        onFocus: (event: FocusEvent<HTMLElement>) => void;
+        onBlur: (event: FocusEvent<HTMLElement, Element>) => void;
+        onClick: (event: MouseEvent<HTMLElement>) => void;
     };
 };
-/** The gliding highlight itself. Position it absolutely inside the content, under the items. */
+/** The highlight itself: the fluid hover highlight, or a marker that moves by top and height (a current-page marker). */
 export declare function MenuHighlight({ state, className }: {
-    state: Highlight | null;
+    state: FluidHighlight | BarHighlight | null;
     className?: string;
 }): import("react").JSX.Element;
 export {};

package/lib/menu-highlight.js

@@ -1,43 +1,44 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from "react";
+import { useRef } from "react";
 import { motion, useReducedMotion } from "motion/react";
+import { FluidHoverHighlight, useFluidHover } from "./fluid-hover.js";
 import { motionTokens } from "./motion-tokens.js";
+const ITEMS = '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"]';
 /**
- * One highlight that glides between the items of a Radix menu or listbox for the pointer, and jumps instantly for the keyboard.
- * Radix focuses the highlighted item, so the highlight follows focus inside the content. Spread `contentProps` on the content,
- * call `reset` when it opens, and render `<MenuHighlight state={highlight} className={styles.highlight} />` as its first child.
- * Items mark a destructive tone with `data-tone="danger"`.
+ * Fluid hover for a Radix menu or listbox (lib/fluid-hover): the item nearest the pointer is lit, gaps and padding
+ * included, a click in a gap picks the lit item, and the keyboard moves the highlight with Radix's focus, without travel.
+ * Spread `contentProps` on the content, call `reset` when it opens, and render `<MenuHighlight state={highlight} … />`
+ * as its first child. Items mark a destructive tone with `data-tone="danger"`.
  */
-export function useMenuHighlight(itemSelector = '[role="menuitem"], [role="option"]') {
-    const [highlight, setHighlight] = useState(null);
-    const pointer = useRef(false);
-    const clearTimer = useRef(0);
-    useEffect(() => () => window.clearTimeout(clearTimer.current), []);
-    function onFocus(event) {
-        const item = event.target instanceof HTMLElement ? event.target.closest(itemSelector) : null;
-        window.clearTimeout(clearTimer.current);
-        if (!item) {
-            // A short grace period keeps the highlight gliding across separators and item gaps.
-            clearTimer.current = window.setTimeout(() => setHighlight(null), pointer.current ? 70 : 0);
-            return;
-        }
-        const next = { top: item.offsetTop, height: item.offsetHeight, danger: item.dataset.tone === "danger" };
-        const glide = pointer.current;
-        setHighlight(current => ({ ...next, glide: glide && current !== null }));
-    }
+export function useMenuHighlight(itemSelector = ITEMS) {
+    // The content element is taken from its own events, so the hook never competes with the content's ref.
+    const content = useRef(null);
+    const hover = useFluidHover(content, { items: itemSelector });
+    const own = (event) => { content.current = event.currentTarget; };
+    const { handlers } = hover;
+    const highlight = { rect: hover.rect, glide: hover.glide, session: hover.session, danger: hover.item?.dataset.tone === "danger" };
     return {
         highlight,
-        reset: () => { window.clearTimeout(clearTimer.current); setHighlight(null); },
+        reset: hover.reset,
         contentProps: {
-            onFocus,
-            onPointerMoveCapture: () => { pointer.current = true; },
-            onKeyDownCapture: () => { pointer.current = false; },
+            onMouseEnter: (event) => { own(event); handlers.onMouseEnter(); },
+            onMouseMove: (event) => { own(event); handlers.onMouseMove(event); },
+            onMouseLeave: handlers.onMouseLeave,
+            onKeyDownCapture: handlers.onKeyDownCapture,
+            onFocus: (event) => { own(event); handlers.onFocus(event); },
+            onBlur: handlers.onBlur,
+            onClick: (event) => { own(event); handlers.onClick(event); },
         },
     };
 }
-/** The gliding highlight itself. Position it absolutely inside the content, under the items. */
+/** The highlight itself: the fluid hover highlight, or a marker that moves by top and height (a current-page marker). */
 export function MenuHighlight({ state, className }) {
+    if (state && "session" in state)
+        return _jsx(FluidHoverHighlight, { hover: state, className: className, tone: state.danger ? "danger" : undefined });
+    return _jsx(BarMarker, { state: state, className: className });
+}
+function BarMarker({ state, className }) {
     const reduced = useReducedMotion();
-    return _jsx(motion.span, { className: className, "data-tone": state?.danger ? "danger" : undefined, "aria-hidden": "true", initial: false, animate: state ? { y: state.top, height: state.height, opacity: 1 } : { opacity: 0 }, transition: { default: state?.glide && !reduced ? motionTokens.spring.snappy : { duration: 0 }, opacity: { duration: reduced ? 0 : .08 } } });
+    return _jsx(motion.span, { className: className, "data-tone": state?.danger ? "danger" : undefined, "aria-hidden": "true", initial: false, animate: state ? { y: state.top, height: state.height, opacity: 1 } : { opacity: 0 }, transition: { default: state?.glide && !reduced ? motionTokens.spring.fast : { duration: 0 }, opacity: { duration: reduced ? 0 : motionTokens.duration.fast } } });
 }

package/lib/motion-tokens.d.ts

@@ -1,11 +1,14 @@
-/** Motion presets are shared by the gallery and future registry consumers. */
 export declare const motionTokens: {
+    /** Tween durations in seconds, for opacity, colour and blur, and for CSS (the same steps as `--duration-*`). */
     readonly duration: {
-        readonly instant: 0.12;
-        readonly fast: 0.16;
-        readonly exit: 0.18;
-        readonly standard: 0.24;
-        readonly considered: 0.48;
+        readonly instant: 0.06;
+        readonly fast: 0.08;
+        readonly exit: 0.12;
+        readonly standard: 0.16;
+        readonly considered: 0.24;
+        /** Motion that tells a story over time rather than answering a click: a chart drawing in, a counter rolling, text
+         *  revealing, a success ring drawing, a slow image zoom. Never for a hover, press, menu or panel. */
+        readonly expressive: 0.48;
     };
     readonly ease: {
         readonly enter: readonly [0.16, 1, 0.3, 1];
@@ -15,30 +18,76 @@ export declare const motionTokens: {
         readonly inOut: readonly [0.65, 0, 0.35, 1];
     };
     readonly spring: {
-        readonly responsive: {
+        /** Hover highlights, presses, toggles, thumbs and small indicators. */
+        readonly fast: {
             readonly type: "spring";
-            readonly stiffness: 520;
-            readonly damping: 38;
+            readonly visualDuration: 0.05;
+            readonly bounce: 0;
+            readonly exit: {
+                readonly duration: 0.06;
+            };
         };
-        readonly gentle: {
+        /** Menus, popovers, tabs, drawers, height changes: short travel that must land exactly. */
+        readonly moderate: {
             readonly type: "spring";
-            readonly stiffness: 340;
-            readonly damping: 34;
+            readonly visualDuration: 0.09;
+            readonly bounce: 0;
+            readonly exit: {
+                readonly duration: 0.12;
+            };
         };
-        /** Presses, toggles, thumbs, and small indicators. Settles fast with a hint of life. */
-        readonly snappy: {
+        /** Dialogs, sheets, shape morphs and large shared-layout moves. A little bounce. */
+        readonly slow: {
             readonly type: "spring";
-            readonly visualDuration: 0.26;
+            readonly visualDuration: 0.15;
             readonly bounce: 0.12;
+            readonly exit: {
+                readonly duration: 0.16;
+            };
+        };
+        /** Earlier names, kept so existing code keeps working. Prefer the tier names. */
+        readonly snappy: {
+            readonly type: "spring";
+            readonly visualDuration: 0.05;
+            readonly bounce: 0;
+            readonly exit: {
+                readonly duration: 0.06;
+            };
         };
-        /** Panels, height changes, and layout shifts. Critically damped, never overshoots. */
         readonly smooth: {
             readonly type: "spring";
-            readonly visualDuration: 0.4;
+            readonly visualDuration: 0.09;
             readonly bounce: 0;
+            readonly exit: {
+                readonly duration: 0.12;
+            };
         };
-        /** Shape morphs, shared layout highlights, and width changes that follow new content. */
         readonly morph: {
+            readonly type: "spring";
+            readonly visualDuration: 0.15;
+            readonly bounce: 0.12;
+            readonly exit: {
+                readonly duration: 0.16;
+            };
+        };
+        readonly responsive: {
+            readonly type: "spring";
+            readonly visualDuration: 0.09;
+            readonly bounce: 0;
+            readonly exit: {
+                readonly duration: 0.12;
+            };
+        };
+        readonly gentle: {
+            readonly type: "spring";
+            readonly visualDuration: 0.09;
+            readonly bounce: 0;
+            readonly exit: {
+                readonly duration: 0.12;
+            };
+        };
+        /** The spring for expressive motion (see duration.expressive): a bar growing, a value settling into place. */
+        readonly expressive: {
             readonly type: "spring";
             readonly visualDuration: 0.42;
             readonly bounce: 0.16;
@@ -58,3 +107,12 @@ export declare const motionTokens: {
         readonly text: 8;
     };
 };
+/**
+ * How long (ms) a deferred-unmount timer waits for a tier's exit before forcing it: the exit plus a safety margin, for
+ * a throttled background tab that never finishes the animation.
+ */
+export declare const exitFallbackMs: (tier: {
+    exit: {
+        duration: number;
+    };
+}) => number;