@teamofsilicons/silicon-ui 0.3.0 → 0.4.0

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;

package/lib/motion-tokens.js

@@ -1,6 +1,30 @@
-/** Motion presets are shared by the gallery and future registry consumers. */
+/**
+ * Motion tokens, shared by every component and by apps (`@teamofsilicons/silicon-ui/motion-tokens`).
+ *
+ * Interface motion runs on three spring tiers. Each tier is the ENTER transition (critically damped, except slow, which
+ * keeps a little bounce), and its `.exit` is the matching EXIT: a plain tween one tier quicker, so a dismissal reads as
+ * crisp and final instead of replaying the entrance in reverse. The bigger the thing that moves, the slower the tier.
+ * Never hand-write a duration: reach for a tier.
+ *
+ *   transition={motionTokens.spring.fast}                                    // enter
+ *   exit={{ opacity: 0, transition: motionTokens.spring.fast.exit }}         // leave
+ *
+ * The tier values and the exit rule are adapted from Fluid Functionalism by Micka Touillaud (MIT),
+ * https://github.com/mickadesign/fluid-functionalism.
+ */
+// Written as visualDuration (the form the components read) with values that arrive (95% of the way) at the same moment as
+// FF's settling durations of 0.08, 0.16 and 0.24s: 42, 83 and 109ms.
+const fast = { type: "spring", visualDuration: 0.05, bounce: 0, exit: { duration: 0.06 } };
+const moderate = { type: "spring", visualDuration: 0.09, bounce: 0, exit: { duration: 0.12 } };
+const slow = { type: "spring", visualDuration: 0.15, bounce: 0.12, exit: { duration: 0.16 } };
 export const motionTokens = {
-    duration: { instant: 0.12, fast: 0.16, exit: 0.18, standard: 0.24, considered: 0.48 },
+    /** Tween durations in seconds, for opacity, colour and blur, and for CSS (the same steps as `--duration-*`). */
+    duration: {
+        instant: 0.06, fast: 0.08, exit: 0.12, standard: 0.16, 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. */
+        expressive: 0.48,
+    },
     ease: {
         enter: [0.16, 1, 0.3, 1],
         exit: [0.7, 0, 0.84, 0],
@@ -9,17 +33,28 @@ export const motionTokens = {
         inOut: [0.65, 0, 0.35, 1],
     },
     spring: {
-        responsive: { type: "spring", stiffness: 520, damping: 38 },
-        gentle: { type: "spring", stiffness: 340, damping: 34 },
-        /** Presses, toggles, thumbs, and small indicators. Settles fast with a hint of life. */
-        snappy: { type: "spring", visualDuration: 0.26, bounce: 0.12 },
-        /** Panels, height changes, and layout shifts. Critically damped, never overshoots. */
-        smooth: { type: "spring", visualDuration: 0.4, bounce: 0 },
-        /** Shape morphs, shared layout highlights, and width changes that follow new content. */
-        morph: { type: "spring", visualDuration: 0.42, bounce: 0.16 },
+        /** Hover highlights, presses, toggles, thumbs and small indicators. */
+        fast,
+        /** Menus, popovers, tabs, drawers, height changes: short travel that must land exactly. */
+        moderate,
+        /** Dialogs, sheets, shape morphs and large shared-layout moves. A little bounce. */
+        slow,
+        /** Earlier names, kept so existing code keeps working. Prefer the tier names. */
+        snappy: fast,
+        smooth: moderate,
+        morph: slow,
+        responsive: moderate,
+        gentle: moderate,
+        /** The spring for expressive motion (see duration.expressive): a bar growing, a value settling into place. */
+        expressive: { type: "spring", visualDuration: 0.42, bounce: 0.16 },
     },
     /** Stagger steps in seconds. Keep total stagger under roughly 0.4s. */
     stagger: { char: 0.016, word: 0.04, line: 0.08, item: 0.035 },
     /** Blur radii in px for text and content crossfades. Keep blur small and brief. */
     blur: { subtle: 2, soft: 4, 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 const exitFallbackMs = (tier) => Math.round(tier.exit.duration * 1000) + 100;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamofsilicons/silicon-ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "React components with calm motion, on the Silicon design tokens. By Team of Silicons.",
   "license": "MIT",
   "author": "Team of Silicons",

package/styles.css

@@ -110,9 +110,12 @@
   --ease-standard: cubic-bezier(.22,1,.36,1);
   --ease-exit: cubic-bezier(.7,0,.84,0);
   --ease-in-out: cubic-bezier(.65,0,.35,1);
-  /* Spring with a gentle settle (bounce .15). Pair with --duration-spring for transform transitions. */
-  --ease-spring: linear(0, 0.0258, 0.09, 0.1763, 0.2732, 0.3724, 0.4683, 0.5573, 0.6376, 0.7082, 0.7689, 0.8202, 0.8628, 0.8976, 0.9256, 0.9476, 0.9648, 0.9778, 0.9875, 0.9945, 0.9994, 1.0026, 1.0047, 1.0058, 1.0062, 1.0062, 1.0059, 1.0055, 1.0049, 1.0043, 1.0036, 1.0031, 1.0025, 1.002, 1.0016, 1.0013, 1);
-  --duration-instant: 120ms; --duration-fast: 160ms; --duration-standard: 240ms; --duration-considered: 480ms; --duration-spring: 580ms;
+  /* The slow spring tier (bounce .12, settles in 240ms), sampled for CSS. Pair with --duration-spring for transforms. */
+  --ease-spring: linear(0, 0.0515, 0.1675, 0.3072, 0.4464, 0.5725, 0.6797, 0.7668, 0.8352, 0.887, 0.9253, 0.9527, 0.9717, 0.9846, 0.9928, 0.9979, 1.0008, 1.0023, 1.0029, 1.0029, 1.0027, 1.0023, 1.0019, 1.0015, 1);
+  /* The same steps as motionTokens.duration: fast is a hover or press, standard a menu or panel, considered a dialog. */
+  --duration-instant: 60ms; --duration-fast: 80ms; --duration-standard: 160ms; --duration-considered: 240ms; --duration-spring: 240ms;
+  /* Motion that tells a story (a chart drawing in, a slow image zoom), never a hover, press or panel. */
+  --duration-expressive: 480ms;
   /* Stagger steps (the same values as motionTokens.stagger). Keep total stagger under roughly 400ms. */
   --stagger-item: 35ms;
   /* Stacking order, by role. Menus and listboxes sit above popovers and dialogs because they open from inside them.