@teamofsilicons/silicon-ui 0.0.0-stage → 0.2.0

package/components/floating-button-group/floating-button-group.js

@@ -0,0 +1,215 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import { AnimatePresence, animate, motion, useIsPresent, useMotionValue, useReducedMotion } from "motion/react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import { Tooltip } from "../tooltip/tooltip.js";
+import styles from "./floating-button-group.module.css";
+const isAction = (item) => item.type !== "separator";
+const standard = [...motionTokens.ease.standard];
+const enter = [...motionTokens.ease.enter];
+const rest = { opacity: 1, y: 0, filter: "blur(0px)" };
+const textIn = { opacity: 0, y: 4, filter: `blur(${motionTokens.blur.soft}px)` };
+const textOut = { opacity: 0, y: -3, filter: `blur(${motionTokens.blur.soft}px)`, transition: { duration: motionTokens.duration.fast, ease: standard } };
+const fadeIn = { opacity: 0 };
+const fadeOut = { opacity: 0, transition: { duration: motionTokens.duration.instant } };
+function Phase({ children, reduced }) {
+    const present = useIsPresent();
+    return _jsx(motion.span, { className: styles.phase, "aria-hidden": present ? undefined : true, initial: reduced ? fadeIn : textIn, animate: rest, exit: reduced ? fadeOut : textOut, transition: { duration: reduced ? motionTokens.duration.instant : motionTokens.duration.standard, ease: enter }, children: children });
+}
+/**
+ * Icon and label. Every label the item can show is laid out invisibly in the same grid cell, so the button always has the width
+ * of the widest one: a label change crossfades in place and never resizes the button, its neighbours or the tray.
+ */
+function ItemBody({ label, icon, iconOnly, reserve, reduced }) {
+    const ghosts = iconOnly ? [] : Array.from(new Set([label, ...reserve]));
+    return _jsxs("span", { className: styles.slot, children: [ghosts.map(text => _jsxs("span", { className: styles.ghost, "aria-hidden": "true", children: [icon ? _jsx("span", { className: styles.iconSpace }) : null, _jsx("span", { className: styles.text, children: text })] }, text)), _jsx(AnimatePresence, { initial: false, children: _jsxs(Phase, { reduced: reduced, children: [icon ? _jsx("span", { className: styles.icon, "aria-hidden": "true", children: icon }) : null, iconOnly ? null : _jsx("span", { className: styles.text, children: label })] }, label) })] });
+}
+function TipContent({ label, shortcut }) {
+    return _jsxs("span", { className: styles.tip, children: [label, shortcut ? _jsx("kbd", { className: styles.kbd, children: shortcut }) : null] });
+}
+/** Side tooltips for a column. The library Tooltip opens above or below, which would cover the neighbouring button. */
+function SideTip({ side, content, children }) {
+    return _jsxs(TooltipPrimitive.Root, { children: [_jsx(TooltipPrimitive.Trigger, { asChild: true, children: children }), _jsx(TooltipPrimitive.Portal, { children: _jsx(TooltipPrimitive.Content, { className: styles.sideTip, side: side, sideOffset: 10, collisionPadding: 12, children: content }) })] });
+}
+/**
+ * Separate soft buttons in a quiet tray. One shared highlight morphs, in position and size, to whichever button the pointer
+ * or keyboard focus is on, fades when the pointer leaves the tray, and settles darker in place while a button is pressed.
+ * It is the toolbar's only hover and focus indicator. Arrow keys move focus, Home and End jump to the ends, Enter and Space act.
+ */
+export function FloatingButtonGroup({ items, label, variant = "muted", size = "md", orientation = "horizontal", iconOnly: groupIconOnly = false, tooltipSide, onAction, className, style }) {
+    const reduced = useReducedMotion() ?? false;
+    const tray = useRef(null);
+    const nodes = useRef(new Map());
+    const [hoverId, setHoverId] = useState(null);
+    const [focusId, setFocusId] = useState(null);
+    const [pressing, setPressing] = useState(false);
+    const [tabStop, setTabStop] = useState(null);
+    const actions = items.filter(isAction);
+    const byId = new Map(actions.map(action => [action.id, action]));
+    const enabled = (id) => !!id && !!byId.get(id) && !byId.get(id)?.disabled;
+    // Pointer wins over keyboard focus while it is in the tray; a disabled item under the pointer hands back to focus.
+    const activeId = enabled(hoverId) ? hoverId : focusId && byId.has(focusId) ? focusId : null;
+    const stop = enabled(tabStop) ? tabStop : actions.find(action => !action.disabled)?.id ?? null;
+    const vertical = orientation === "vertical";
+    const side = tooltipSide ?? (vertical ? "right" : "top");
+    const idsKey = actions.map(action => action.id).join("\u0000");
+    // The highlight lives in motion values so moving it never re-renders the buttons.
+    const x = useMotionValue(0), y = useMotionValue(0), width = useMotionValue(0), height = useMotionValue(0);
+    const opacity = useMotionValue(0), scale = useMotionValue(1);
+    const traveling = useRef(false);
+    const activeRef = useRef(activeId);
+    const pressingRef = useRef(pressing);
+    /** The button's box in tray coordinates, exact to the device pixel (offsetLeft rounds to whole pixels) and free of ancestor transforms. */
+    const measure = useCallback((node) => {
+        const root = tray.current;
+        if (!root)
+            return null;
+        const outer = root.getBoundingClientRect(), box = node.getBoundingClientRect();
+        const unscale = outer.width ? root.offsetWidth / outer.width : 1;
+        const dpr = window.devicePixelRatio || 1;
+        const snap = (value) => Math.round(value * unscale * dpr) / dpr;
+        return { x: snap(box.left - outer.left) - root.clientLeft, y: snap(box.top - outer.top) - root.clientTop, width: snap(box.width), height: snap(box.height) };
+    }, []);
+    const place = useCallback((id, mode) => {
+        const node = id ? nodes.current.get(id) : undefined;
+        if (!node) {
+            animate(opacity, 0, { duration: reduced ? motionTokens.duration.instant : motionTokens.duration.standard, ease: standard });
+            return;
+        }
+        const rect = measure(node);
+        if (!rect)
+            return;
+        const visible = opacity.get() > .15;
+        // Travel between buttons on the morph spring. Appearing from nothing, and every move with reduced motion, lands in place.
+        const travel = !reduced && visible && (mode === "move" || traveling.current);
+        if (travel) {
+            traveling.current = true;
+            animate(x, rect.x, motionTokens.spring.morph);
+            animate(y, rect.y, motionTokens.spring.morph);
+            animate(width, rect.width, motionTokens.spring.morph);
+            animate(height, rect.height, { ...motionTokens.spring.morph, onComplete: () => { traveling.current = false; } });
+        }
+        else {
+            traveling.current = false;
+            x.jump(rect.x);
+            y.jump(rect.y);
+            width.jump(rect.width);
+            height.jump(rect.height);
+            if (!visible && !reduced) {
+                scale.jump(.94);
+                animate(scale, pressingRef.current ? .965 : 1, motionTokens.spring.snappy);
+            }
+        }
+        if (opacity.get() !== 1)
+            animate(opacity, 1, { duration: reduced ? motionTokens.duration.instant : motionTokens.duration.fast, ease: standard });
+    }, [height, measure, opacity, reduced, scale, width, x, y]);
+    useLayoutEffect(() => {
+        activeRef.current = activeId;
+        place(activeId, "move");
+    }, [activeId, place]);
+    useEffect(() => {
+        pressingRef.current = pressing;
+        animate(scale, pressing && activeId ? .965 : 1, reduced ? { duration: 0 } : motionTokens.spring.snappy);
+    }, [activeId, pressing, reduced, scale]);
+    // A font that loads or a container that reflows moves the buttons; the highlight follows without travel.
+    useEffect(() => {
+        const root = tray.current;
+        if (!root || typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => { if (activeRef.current)
+            place(activeRef.current, "follow"); });
+        observer.observe(root);
+        nodes.current.forEach(node => observer.observe(node));
+        return () => observer.disconnect();
+    }, [idsKey, place]);
+    // A native listener, because React bubbles pointer events through portals: moving from a button onto its tooltip
+    // would not count as leaving the tray, and the highlight would stay behind.
+    useEffect(() => {
+        const root = tray.current;
+        if (!root)
+            return;
+        const leave = () => { setHoverId(null); setPressing(false); };
+        root.addEventListener("pointerleave", leave);
+        return () => root.removeEventListener("pointerleave", leave);
+    }, []);
+    const buttons = () => Array.from(tray.current?.querySelectorAll("[data-fbg-item]") ?? []);
+    const onKeyDown = (event) => {
+        const all = buttons();
+        const index = all.findIndex(node => node === document.activeElement);
+        if (index < 0)
+            return;
+        const next = vertical ? "ArrowDown" : "ArrowRight";
+        const previous = vertical ? "ArrowUp" : "ArrowLeft";
+        const usable = (node) => node.getAttribute("aria-disabled") !== "true";
+        let target;
+        if (event.key === "Home")
+            target = all.find(usable);
+        else if (event.key === "End")
+            target = [...all].reverse().find(usable);
+        else if (event.key === next || event.key === previous) {
+            const step = event.key === next ? 1 : -1;
+            for (let offset = 1; offset <= all.length; offset += 1) {
+                const candidate = all[(index + step * offset + all.length * offset) % all.length];
+                if (usable(candidate)) {
+                    target = candidate;
+                    break;
+                }
+            }
+        }
+        else
+            return;
+        event.preventDefault();
+        if (!target)
+            return;
+        // The keyboard takes the highlight back until the pointer moves again.
+        setHoverId(null);
+        target.focus();
+    };
+    const onBlur = (event) => {
+        if (tray.current?.contains(event.relatedTarget))
+            return;
+        setFocusId(null);
+        setPressing(false);
+    };
+    const classes = [styles.group, styles[variant], styles[size], vertical ? styles.vertical : "", className].filter(Boolean).join(" ");
+    const group = _jsxs("div", { ref: tray, className: classes, style: style, role: "toolbar", "aria-label": label, "aria-orientation": orientation, "data-variant": variant, onKeyDown: onKeyDown, onBlur: onBlur, children: [_jsx(motion.span, { className: styles.highlight, "data-pressing": pressing && activeId ? "" : undefined, style: { x, y, width, height, opacity, scale }, "aria-hidden": "true" }), items.map((item, position) => {
+                if (!isAction(item))
+                    return _jsx("span", { className: styles.separator, role: "separator", "aria-orientation": vertical ? "horizontal" : "vertical" }, item.id ?? `separator-${position}`);
+                const { id, label: itemLabel, icon, onSelect, disabled = false, pressed, shortcut, reserveLabels = [] } = item;
+                const iconOnly = !!icon && (item.iconOnly ?? groupIconOnly);
+                const button = _jsx("button", { ref: node => { if (node)
+                        nodes.current.set(id, node);
+                    else
+                        nodes.current.delete(id); }, type: "button", className: styles.item, "data-fbg-item": "", "data-active": activeId === id ? "" : undefined, "data-icon": icon ? "" : undefined, "data-icon-only": iconOnly ? "" : undefined, "aria-label": itemLabel, "aria-pressed": pressed === undefined ? undefined : pressed, "aria-disabled": disabled || undefined, tabIndex: stop === id ? 0 : -1, onPointerMove: event => { if (event.pointerType === "mouse" || event.pointerType === "pen")
+                        setHoverId(id); }, onPointerDown: event => { if (disabled || event.button !== 0)
+                        return; setHoverId(id); setPressing(true); }, onPointerUp: () => setPressing(false), onPointerCancel: () => setPressing(false), onPointerLeave: () => setPressing(false), onKeyDown: event => { if ((event.key === "Enter" || event.key === " ") && !event.repeat && !disabled)
+                        setPressing(true); }, onKeyUp: event => { if (event.key === "Enter" || event.key === " ")
+                        setPressing(false); }, onFocus: event => {
+                        setTabStop(id);
+                        let keyboard = false;
+                        try {
+                            keyboard = event.currentTarget.matches(":focus-visible");
+                        }
+                        catch {
+                            keyboard = false;
+                        }
+                        setFocusId(keyboard ? id : null);
+                    }, onClick: () => {
+                        if (disabled)
+                            return;
+                        onSelect?.();
+                        onAction?.(id);
+                    }, children: _jsx(ItemBody, { label: itemLabel, icon: icon, iconOnly: iconOnly, reserve: reserveLabels, reduced: reduced }) });
+                // Tooltips render no wrapper element, so every button stays a direct child of the tray and measures against it.
+                if (!iconOnly && !shortcut)
+                    return _jsx(Fragment, { children: button }, id);
+                const tip = _jsx(TipContent, { label: itemLabel, shortcut: shortcut });
+                return side === "top" || side === "bottom"
+                    ? _jsx(Tooltip, { side: side, content: tip, children: button }, id)
+                    : _jsx(SideTip, { side: side, content: tip, children: button }, id);
+            })] });
+    return side === "left" || side === "right" ? _jsx(TooltipPrimitive.Provider, { delayDuration: 250, skipDelayDuration: 300, disableHoverableContent: true, children: group }) : group;
+}
+export default FloatingButtonGroup;

package/components/floating-button-group/floating-button-group.module.css

@@ -0,0 +1,74 @@
+/* Separate soft buttons in a quiet tray, with real gaps between them. The tray always keeps its natural size and never wraps or clips its buttons. The buttons stay transparent: one shared highlight
+   moves underneath their content, so there is only ever one moving surface. Corners are concentric with the tray. */
+.group {
+  --fbg-h: 36px; --fbg-pad: 4px; --fbg-gap: 4px; --fbg-pad-x: 12px;
+  --fbg-outer: var(--radius-control);
+  --fbg-radius: calc(var(--fbg-outer) - var(--fbg-pad) - 1px);
+  --fbg-highlight: color-mix(in oklab, var(--foreground) 7%, transparent);
+  --fbg-highlight-press: color-mix(in oklab, var(--foreground) 12%, transparent);
+  --fbg-on: color-mix(in oklab, var(--control-on) 12%, transparent);
+  --fbg-rule: color-mix(in oklab, var(--foreground) 12%, transparent);
+  /* The muted tray is a translucent tint, not --surface-muted, so it still reads when it sits on a muted surface. */
+  --fbg-tray: color-mix(in oklab, var(--foreground) 4.5%, transparent);
+  --fbg-tray-edge: color-mix(in oklab, var(--foreground) 3%, transparent);
+  position: relative; isolation: isolate; display: inline-flex; flex: none; flex-wrap: nowrap; align-items: center; gap: var(--fbg-gap); padding: var(--fbg-pad); border: 1px solid var(--fbg-tray-edge); border-radius: var(--fbg-outer); background: var(--fbg-tray); color: var(--text-secondary); font-family: var(--font-body); letter-spacing: var(--tracking-body); -webkit-tap-highlight-color: transparent;
+}
+.sm { --fbg-h: 30px; --fbg-pad: 3px; --fbg-gap: 3px; --fbg-pad-x: 10px; --fbg-outer: calc(var(--radius-control) - 3px); }
+.md { --fbg-h: 36px; }
+/* Raised for overlays such as a selection toolbar: the floating layer shadow and a hairline edge. */
+.floating { border-color: var(--border); background: var(--surface-raised); box-shadow: var(--shadow-floating); }
+.vertical { flex-direction: column; align-items: stretch; }
+:global(:root[data-theme="dark"]) .group {
+  --fbg-highlight: color-mix(in oklab, var(--foreground) 9%, transparent);
+  --fbg-highlight-press: color-mix(in oklab, var(--foreground) 15%, transparent);
+  --fbg-on: color-mix(in oklab, var(--control-on) 16%, transparent);
+  --fbg-tray: color-mix(in oklab, var(--foreground) 6%, transparent);
+  --fbg-tray-edge: color-mix(in oklab, var(--foreground) 5%, transparent);
+}
+
+/* The highlight paints above the buttons' own backgrounds (a pressed tint) and below their content. */
+.highlight { position: absolute; z-index: 1; top: 0; left: 0; border-radius: var(--fbg-radius); background: var(--fbg-highlight); pointer-events: none; transition: background-color var(--duration-fast) var(--ease-standard); }
+.highlight[data-pressing] { background: var(--fbg-highlight-press); transition-duration: var(--duration-instant); }
+
+/* Buttons are not positioned, so the highlight measures them against the tray and stacks above their background. */
+.item { display: inline-flex; min-width: var(--fbg-h); height: var(--fbg-h); flex: none; align-items: center; justify-content: center; margin: 0; padding: 0 var(--fbg-pad-x); border: 0; border-radius: var(--fbg-radius); background: transparent; color: inherit; font: inherit; font-size: var(--text-sm); font-weight: 500; line-height: 1; white-space: nowrap; cursor: pointer; user-select: none; -webkit-tap-highlight-color: transparent; touch-action: manipulation; transition: color var(--duration-fast) var(--ease-standard), background-color var(--duration-fast) var(--ease-standard), opacity var(--duration-fast) var(--ease-standard); }
+.sm .item { font-size: var(--text-xs); }
+.item[data-icon]:not([data-icon-only]) { padding-left: calc(var(--fbg-pad-x) - 2px); }
+.item[data-icon-only] { width: var(--fbg-h); padding: 0; }
+.item[data-active], .item[aria-pressed="true"] { color: var(--foreground); }
+.item[aria-pressed="true"] { background: var(--fbg-on); }
+.item[aria-disabled="true"] { color: var(--text-muted); cursor: not-allowed; opacity: .5; }
+.vertical .item:not([data-icon-only]) { justify-content: flex-start; }
+.vertical .item[data-icon-only] { align-self: center; }
+
+/* Ghosts of every label share one grid cell with the visible one, so the slot always has the widest label's width. */
+.slot { position: relative; z-index: 2; display: inline-grid; align-items: center; justify-items: center; }
+.slot > * { grid-area: 1 / 1; }
+.vertical .slot { justify-items: start; }
+.ghost { display: inline-flex; align-items: center; gap: 6px; white-space: nowrap; visibility: hidden; pointer-events: none; }
+.iconSpace { display: block; width: 16px; height: 16px; flex: none; }
+.phase { display: inline-flex; align-items: center; gap: 6px; white-space: nowrap; }
+.icon { display: inline-flex; flex: none; }
+.icon svg { width: 16px; height: 16px; stroke-width: 1.75; }
+.text { display: block; }
+
+.separator { flex: none; align-self: center; width: 1px; height: calc(var(--fbg-h) * .5); margin-inline: 2px; border-radius: var(--radius-full); corner-shape: round; background: var(--fbg-rule); }
+.vertical .separator { width: calc(var(--fbg-h) * .5); height: 1px; margin: 2px 0; }
+
+.tip { display: inline-flex; align-items: baseline; gap: var(--space-group); white-space: nowrap; }
+.kbd { font: inherit; color: color-mix(in oklab, var(--background) 58%, var(--foreground)); font-variant-numeric: tabular-nums; }
+
+/* Side tooltips for a column match the library tooltip, rising a few pixels away from the rail instead of up. */
+.sideTip { --tip-x: -3px; z-index: 90; max-width: 15rem; padding: var(--space-group) var(--space-inset); border: 1px solid color-mix(in oklab, var(--background) 14%, var(--foreground)); border-radius: var(--radius-control); corner-shape: var(--corner-shape); background: var(--foreground); color: var(--background); box-shadow: var(--shadow-raised); font-family: var(--font-body); font-size: var(--text-sm); font-weight: 400; letter-spacing: var(--tracking-body); line-height: var(--leading-body); transform-origin: var(--radix-tooltip-content-transform-origin); transition: opacity var(--duration-fast) var(--ease-enter), transform var(--duration-fast) var(--ease-enter); }
+.sideTip[data-side="left"] { --tip-x: 3px; }
+@starting-style {
+  .sideTip[data-state$="-open"] { opacity: 0; transform: translateX(var(--tip-x)) scale(.97); }
+}
+/* Radix unmounts when the exit animation ends, so a no-op keyframe times the exit while the transition does the visual work. */
+.sideTip[data-state="closed"] { opacity: 0; transform: scale(.98); transition: opacity 110ms var(--ease-standard), transform 110ms var(--ease-standard); animation: side-tip-exit 110ms linear both; }
+@keyframes side-tip-exit { to { --side-tip-exit: 1; } }
+
+@media (prefers-reduced-motion: reduce) {
+  .item, .highlight { transition: color var(--duration-instant) linear, background-color var(--duration-instant) linear, opacity var(--duration-instant) linear; }
+  .sideTip, .sideTip[data-state="closed"] { transform: none; transition: opacity 90ms linear; }
+}

package/components/gauge/gauge.d.ts

@@ -0,0 +1,18 @@
+type GaugeTone = "accent" | "success" | "warning" | "danger";
+/** A band that starts at `from`: the highest band the value reaches sets the tone and names the state, so it never rests on color alone. */
+export interface GaugeThreshold {
+    from: number;
+    tone: GaugeTone;
+    label: string;
+}
+export interface GaugeProps {
+    value: number;
+    min?: number;
+    max?: number;
+    label: string;
+    detail?: string;
+    tone?: GaugeTone;
+    thresholds?: GaugeThreshold[];
+}
+export declare function Gauge({ value, min, max, label, detail, tone, thresholds }: GaugeProps): import("react").JSX.Element;
+export default Gauge;

package/components/gauge/gauge.js

@@ -0,0 +1,101 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { AnimatePresence, animate, motion, useInView, useMotionValue, useMotionValueEvent, useReducedMotion, useTransform } from "motion/react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./gauge.module.css";
+/** Copy enters from the side the value moved toward: a rise comes up from below, a fall drops from above. */
+const rise = { hidden: (direction) => ({ opacity: 0, y: `${.3 * direction}em`, filter: `blur(${motionTokens.blur.soft}px)` }), shown: { opacity: 1, y: 0, filter: "blur(0px)", transition: { duration: motionTokens.duration.standard, ease: [...motionTokens.ease.enter] } }, gone: (direction) => ({ opacity: 0, y: `${-.3 * direction}em`, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.standard] } }) };
+// Same keys as `rise` so the settled style is identical whichever branch renders on the server.
+const fade = { hidden: { opacity: 0, y: 0, filter: "blur(0px)" }, shown: { opacity: 1, y: 0, filter: "blur(0px)", transition: { duration: motionTokens.duration.instant } }, gone: { opacity: 0, y: 0, filter: "blur(0px)", transition: { duration: motionTokens.duration.instant } } };
+/** The first fill is slower and never overshoots, like a ring closing when the view opens. */
+const reveal = { ...motionTokens.spring.smooth, visualDuration: motionTokens.duration.considered * 1.6 };
+/** New copy rises in while the old copy leaves, popped out of flow so the line never holds both. */
+function Swap({ text, direction = 1 }) {
+    const reduceMotion = !!useReducedMotion();
+    return _jsx("span", { className: styles.swap, children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, custom: direction, children: _jsx(motion.span, { className: styles.text, custom: direction, variants: reduceMotion ? fade : rise, initial: "hidden", animate: "shown", exit: "gone", children: text }, text) }) });
+}
+/** A 270 degree ring open at the bottom, drawn clockwise from its lower left end. Redrawn from the sweep every frame so the round cap stays exact. */
+const radius = 42, start = -135, span = 270;
+function arcFor(sweep) {
+    const end = start + span * Math.min(1, Math.max(0, sweep));
+    const at = (angle) => `${(50 + radius * Math.sin((angle * Math.PI) / 180)).toFixed(3)} ${(50 - radius * Math.cos((angle * Math.PI) / 180)).toFixed(3)}`;
+    return `M ${at(start)} A ${radius} ${radius} 0 ${end - start > 180 ? 1 : 0} 1 ${at(end)}`;
+}
+const track = arcFor(1);
+export function Gauge({ value, min = 0, max = 100, label, detail, tone = "accent", thresholds }) {
+    const safeMax = max > min ? max : min + 1;
+    const percentage = Math.min(1, Math.max(0, (value - min) / (safeMax - min)));
+    const displayValue = Math.round(percentage * 100);
+    const bands = [...thresholds ?? []].sort((a, b) => a.from - b.from);
+    const bandAt = (at) => bands.filter(threshold => at >= threshold.from - 1e-6).pop();
+    const band = bandAt(value);
+    const ref = useRef(null);
+    const sizer = useRef(null);
+    const inView = useInView(ref, { once: true, amount: .5 });
+    const reduceMotion = !!useReducedMotion();
+    const sweep = useMotionValue(0);
+    const count = useMotionValue(0);
+    const digitsWidth = useMotionValue("auto");
+    const [filled, setFilled] = useState(false);
+    const [live, setLive] = useState(band);
+    const path = useTransform(sweep, arcFor);
+    // The cap fades in over the first sliver instead of popping in as a dot.
+    const arcOpacity = useTransform(sweep, current => Math.min(1, Math.max(0, current / .02)));
+    const digits = useTransform(count, current => String(Math.round(Math.min(100, Math.max(0, current)))));
+    const [moved, setMoved] = useState({ value: displayValue, direction: 1 });
+    if (moved.value !== displayValue)
+        setMoved({ value: displayValue, direction: displayValue < moved.value ? -1 : 1 });
+    // The ring fills once it is seen, then springs to each new value with a little life; the count follows without overshooting.
+    useEffect(() => {
+        // Reduced motion lands on the value at once; the state appears a frame later, after hydration has matched the server.
+        if (reduceMotion) {
+            sweep.jump(percentage);
+            count.jump(percentage * 100);
+            const frame = requestAnimationFrame(() => setFilled(true));
+            return () => cancelAnimationFrame(frame);
+        }
+        if (!inView)
+            return;
+        const arc = animate(sweep, percentage, filled ? motionTokens.spring.morph : reveal);
+        const number = animate(count, percentage * 100, { ...(filled ? motionTokens.spring.smooth : reveal), onComplete: () => setFilled(true) });
+        return () => { arc.stop(); number.stop(); };
+    }, [count, filled, inView, percentage, reduceMotion, sweep]);
+    // The state arrives as the first fill lands. After that it follows the number on screen, so the color and label change exactly as the count crosses a threshold.
+    useMotionValueEvent(count, "change", current => {
+        const next = bandAt(min + (current / 100) * (safeMax - min));
+        const changed = next?.from !== live?.from || next?.label !== live?.label;
+        if (filled) {
+            if (changed)
+                setLive(next);
+        }
+        else if (inView && Math.abs(current - percentage * 100) < 1) {
+            if (changed)
+                setLive(next);
+            setFilled(true);
+        }
+    });
+    const shown = reduceMotion || !filled ? band : live;
+    const activeTone = shown?.tone ?? tone;
+    // Digits are right aligned in a box sized to the target number, so the ones column never jumps while counting and the group recentres on a spring.
+    useEffect(() => {
+        const node = sizer.current;
+        if (!node || typeof ResizeObserver === "undefined")
+            return;
+        let measured = null;
+        const observer = new ResizeObserver(([entry]) => {
+            if (!entry)
+                return;
+            const next = entry.borderBoxSize?.[0]?.inlineSize ?? node.offsetWidth;
+            if (measured !== null && measured !== node.textContent && !reduceMotion)
+                animate(digitsWidth, next, motionTokens.spring.smooth);
+            else
+                digitsWidth.jump(next);
+            measured = node.textContent;
+        });
+        observer.observe(node);
+        return () => observer.disconnect();
+    }, [digitsWidth, reduceMotion]);
+    return _jsxs("figure", { ref: ref, className: [styles.figure, styles[activeTone]].join(" "), "aria-label": `${label}: ${value} of ${safeMax}${band ? `, ${band.label}` : ""}`, children: [_jsxs("div", { className: styles.visual, role: "meter", "aria-label": label, "aria-valuemin": min, "aria-valuemax": safeMax, "aria-valuenow": Math.min(safeMax, Math.max(min, value)), "aria-valuetext": `${displayValue}%${band ? `, ${band.label}` : ""}`, children: [_jsxs("svg", { viewBox: "0 0 100 90", "aria-hidden": "true", focusable: "false", children: [_jsx("path", { className: styles.track, d: track }), _jsx(motion.path, { className: styles.arc, d: path, style: { opacity: arcOpacity } })] }), _jsxs("div", { className: styles.readout, "aria-hidden": "true", children: [_jsxs("span", { className: styles.number, children: [_jsx(motion.span, { className: styles.digits, style: { width: digitsWidth }, children: digits }), _jsx("span", { className: styles.unit, children: "%" }), _jsx("span", { ref: sizer, className: styles.sizer, children: displayValue })] }), thresholds && _jsx("span", { className: styles.status, children: _jsx(Swap, { text: filled ? shown?.label ?? "" : "", direction: moved.direction }) })] })] }), _jsxs("figcaption", { children: [_jsx("strong", { children: _jsx(Swap, { text: label }) }), detail && _jsx("span", { className: styles.detail, children: _jsx(Swap, { text: detail, direction: moved.direction }) })] })] });
+}
+export default Gauge;

package/components/gauge/gauge.module.css

@@ -0,0 +1,22 @@
+.figure { display: grid; justify-items: center; min-width: 0; gap: 10px; margin: 0; text-align: center; }.figure figcaption { display: grid; gap: 3px; min-width: 0; }.figure strong { font-size: var(--text-sm); font-weight: 500; }.detail { color: var(--text-muted); font-size: var(--text-xs); font-variant-numeric: tabular-nums; }
+.accent { --gauge-color: var(--accent); --gauge-text: var(--accent-strong); }.success { --gauge-color: var(--success); --gauge-text: var(--success); }.warning { --gauge-color: var(--warning); --gauge-text: var(--warning); }.danger { --gauge-color: var(--danger); --gauge-text: var(--danger); }
+
+/* An activity style ring: a thick stroke with round caps over a faint tint of its own color. The stroke scales with the ring. */
+.visual { position: relative; width: min(100%, 176px); aspect-ratio: 100 / 90; }
+.visual svg { display: block; width: 100%; height: 100%; overflow: visible; }
+.track, .arc { fill: none; stroke-width: 9; stroke-linecap: round; transition: stroke var(--duration-standard) var(--ease-standard); }
+.track { stroke: color-mix(in oklab, var(--gauge-color) 13%, transparent); }
+.arc { stroke: var(--gauge-color); }
+
+/* The readout sits on the ring's true centre, which is the middle of a square as wide as the ring. */
+.readout { position: absolute; top: 0; left: 0; display: grid; width: 100%; aspect-ratio: 1; place-content: center; justify-items: center; gap: 4px; pointer-events: none; }
+.number { position: relative; display: inline-flex; align-items: baseline; color: var(--foreground); font-family: var(--font-display); font-size: var(--text-3xl); font-weight: 500; letter-spacing: var(--tracking-display); line-height: 1; font-variant-numeric: tabular-nums; }
+.digits { display: inline-flex; justify-content: flex-end; white-space: nowrap; }
+.unit { margin-left: 1px; color: var(--text-secondary); font-family: var(--font-body); font-size: .5em; letter-spacing: 0; }
+.sizer { position: absolute; top: 0; left: 0; visibility: hidden; white-space: nowrap; pointer-events: none; }
+.status { min-width: 100px; min-height: 1.4em; color: var(--gauge-text); font-size: var(--text-xs); font-weight: 500; line-height: 1.4; transition: color var(--duration-standard) var(--ease-standard); }
+
+/* Label, status and detail copy swap in place: the outgoing line is popped out of flow while the new one rises in. */
+.swap { position: relative; display: block; }
+.swap > .text { display: inline-block; }
+@media (prefers-reduced-motion: reduce) { .track, .arc, .status { transition: none; } }

package/components/hold-to-confirm/hold-to-confirm.d.ts

@@ -0,0 +1,25 @@
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+/**
+ * A button that commits only after it is held, for destructive or hard to undo actions where a stray tap must not count. A fill tracks the hold on a
+ * linear timeline; letting go early rewinds it on a spring, and finishing morphs the label and icon into a done state. Space and Enter can be held too.
+ * Prefer a regular confirmation dialog when people need to read consequences first; use this when the consequence is already on screen.
+ */
+export interface HoldToConfirmProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onClick" | "onDrag" | "onDragEnd" | "onDragStart" | "onAnimationStart" | "onAnimationEnd"> {
+    /** The instruction and the action, for example “Hold to delete project”. */
+    label: string;
+    /** Shown once the hold completes, for example “Deleted”. */
+    confirmedLabel?: string;
+    /** Called once when the hold completes. */
+    onConfirm: () => void;
+    /** Hold length in milliseconds. */
+    duration?: number;
+    icon?: ReactNode;
+    /** `accent` (default) fills with the selected accent; `danger` is for an irreversible action; `neutral` fills with the foreground. */
+    tone?: "accent" | "danger" | "neutral";
+    /** Controls the done state. Set it back to false to reset the button; leave it undefined to let the button keep its own state. */
+    confirmed?: boolean;
+    /** Reports when a hold starts and ends, for surrounding hints such as “Keep holding”. */
+    onHoldChange?: (holding: boolean) => void;
+}
+export declare function HoldToConfirm({ label, confirmedLabel, onConfirm, duration, icon, tone, confirmed, onHoldChange, className, disabled, ...props }: HoldToConfirmProps): import("react").JSX.Element;
+export default HoldToConfirm;

package/components/hold-to-confirm/hold-to-confirm.js

@@ -0,0 +1,165 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useEffectEvent, useId, useRef, useState } from "react";
+import { AnimatePresence, animate, motion, useMotionValue, useReducedMotion, useTransform } from "motion/react";
+import { Trash2 } from "lucide-react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./hold-to-confirm.module.css";
+const enter = [...motionTokens.ease.enter];
+const standard = [...motionTokens.ease.standard];
+const rest = { opacity: 1, y: 0, scale: 1, filter: "blur(0px)" };
+const textIn = { opacity: 0, y: "0.3em", filter: `blur(${motionTokens.blur.soft}px)` };
+const textOut = { opacity: 0, y: "-0.3em", filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.fast, ease: standard } };
+const iconIn = { opacity: 0, scale: .6, filter: `blur(${motionTokens.blur.subtle}px)` };
+const iconOut = { ...iconIn, transition: { duration: motionTokens.duration.fast, ease: standard } };
+const fadeIn = { opacity: 0 };
+const fadeOut = { opacity: 0, transition: { duration: motionTokens.duration.instant } };
+/** Scale rides the spring; opacity and blur tween so the blur never overshoots below zero. */
+const iconEnter = { ...motionTokens.spring.snappy, opacity: { duration: motionTokens.duration.fast, ease: enter }, filter: { duration: motionTokens.duration.fast, ease: enter } };
+/** The tick draws itself from its short stroke, the way a hand would write it. */
+function DrawnCheck({ reduced }) {
+    return _jsx("svg", { width: 18, height: 18, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: _jsx(motion.path, { d: "M4 12.5l5 5L20 6.5", initial: reduced ? false : { pathLength: 0, opacity: 0 }, animate: { pathLength: 1, opacity: 1 }, transition: { pathLength: { duration: .32, ease: enter, delay: .08 }, opacity: { duration: .05, delay: .08 } } }) });
+}
+/** Icon and label. The button renders it twice: once on the surface and once inside the fill, so the text changes colour exactly at the fill edge. */
+function Face({ icon, text, done, width, reduced, measure }) {
+    return _jsxs("span", { className: styles.face, children: [_jsx("span", { className: styles.iconSlot, children: _jsx(AnimatePresence, { initial: false, children: _jsx(motion.span, { className: styles.iconPhase, initial: reduced ? fadeIn : iconIn, animate: rest, exit: reduced ? fadeOut : iconOut, transition: reduced ? { duration: motionTokens.duration.fast } : iconEnter, children: done ? _jsx(DrawnCheck, { reduced: reduced }) : icon }, done ? "done" : "idle") }) }), _jsxs(motion.span, { className: styles.labelFrame, style: { width }, children: [measure && _jsx("span", { ref: measure, className: styles.measure, children: text }), _jsx(AnimatePresence, { mode: "popLayout", initial: false, children: _jsx(motion.span, { className: styles.label, initial: reduced ? fadeIn : textIn, animate: rest, exit: reduced ? fadeOut : textOut, transition: { duration: reduced ? motionTokens.duration.fast : motionTokens.duration.standard, ease: enter }, children: text }, text) })] })] });
+}
+/** Springs the label frame to the width of new text, so the button morphs instead of snapping. A late web font or a reflow follows instantly. */
+function useLabelWidth(reduced) {
+    const width = useMotionValue("auto");
+    const [node, setNode] = useState(null);
+    useEffect(() => {
+        if (!node || typeof ResizeObserver === "undefined")
+            return;
+        let lastText = null;
+        let sizing = null;
+        const observer = new ResizeObserver(([entry]) => {
+            // Layout width, not the painted box: the done label is measured while the pressed button is still scaled down.
+            const next = entry?.borderBoxSize?.[0]?.inlineSize ?? node.offsetWidth;
+            const text = node.textContent;
+            const morph = lastText !== null && lastText !== text && !reduced && typeof width.get() === "number";
+            lastText = text;
+            sizing?.stop();
+            if (morph)
+                sizing = animate(width, next, motionTokens.spring.morph);
+            else
+                width.jump(next);
+        });
+        observer.observe(node);
+        return () => { observer.disconnect(); sizing?.stop(); };
+    }, [node, reduced, width]);
+    return [width, setNode];
+}
+export function HoldToConfirm({ label, confirmedLabel = "Done", onConfirm, duration = 1200, icon = _jsx(Trash2, { strokeWidth: 1.75 }), tone = "accent", confirmed, onHoldChange, className, disabled, ...props }) {
+    const reduced = useReducedMotion() ?? false;
+    const hintId = useId();
+    const [ownDone, setOwnDone] = useState(false);
+    const [completions, setCompletions] = useState(0);
+    const done = confirmed ?? ownDone;
+    const [holding, setHolding] = useState(false);
+    const progress = useMotionValue(0);
+    const scale = useMotionValue(1);
+    const clipPath = useTransform(progress, value => `inset(0 ${((1 - Math.min(1, Math.max(0, value))) * 100).toFixed(3)}% 0 0)`);
+    const [width, measure] = useLabelWidth(reduced);
+    const source = useRef(null);
+    const pointerType = useRef("mouse");
+    const fill = useRef(null);
+    const press = useRef(null);
+    const button = useRef(null);
+    const text = done ? confirmedLabel : label;
+    const seconds = (duration / 1000).toLocaleString("en-US", { maximumFractionDigits: 1 });
+    function pressTo(pressed) {
+        press.current?.stop();
+        if (reduced) {
+            scale.jump(1);
+            return;
+        }
+        const depth = (button.current?.offsetWidth ?? 0) > 220 ? .985 : .97;
+        press.current = animate(scale, pressed ? depth : 1, motionTokens.spring.snappy);
+    }
+    function rewind() {
+        fill.current?.stop();
+        if (reduced)
+            progress.jump(0);
+        else
+            fill.current = animate(progress, 0, { ...motionTokens.spring.smooth, velocity: 0 });
+    }
+    function stopHolding() {
+        source.current = null;
+        setHolding(false);
+        onHoldChange?.(false);
+        pressTo(false);
+    }
+    function complete() {
+        if (!source.current)
+            return;
+        stopHolding();
+        if (pointerType.current === "touch")
+            navigator.vibrate?.(12);
+        setOwnDone(true);
+        setCompletions(count => count + 1);
+        onConfirm();
+    }
+    /** Starts or resumes the fill from wherever it is, so a quick re-press after letting go carries on instead of starting over. */
+    function begin(from) {
+        if (done || disabled || source.current)
+            return;
+        source.current = from;
+        setHolding(true);
+        onHoldChange?.(true);
+        pressTo(true);
+        fill.current?.stop();
+        fill.current = animate(progress, 1, { duration: (1 - progress.get()) * duration / 1000, ease: "linear", onComplete: complete });
+    }
+    function release() {
+        if (!source.current)
+            return;
+        stopHolding();
+        rewind();
+    }
+    // A reset rewinds the fill as the label morphs back; a confirmation the parent declined rewinds too.
+    const syncFill = useEffectEvent(() => {
+        if (done && progress.get() < 1 && !source.current) {
+            fill.current?.stop();
+            if (reduced)
+                progress.jump(1);
+            else
+                fill.current = animate(progress, 1, motionTokens.spring.smooth);
+        }
+        if (!done && progress.get() > 0 && !source.current)
+            rewind();
+    });
+    useEffect(() => { syncFill(); }, [done, completions]);
+    useEffect(() => () => { fill.current?.stop(); press.current?.stop(); }, []);
+    function onPointerDown(event) {
+        if (!event.isPrimary || event.button !== 0)
+            return;
+        pointerType.current = event.pointerType;
+        event.currentTarget.setPointerCapture(event.pointerId);
+        begin("pointer");
+    }
+    function onPointerMove(event) {
+        if (source.current !== "pointer")
+            return;
+        // Sliding well off the button cancels, the way a native press does.
+        const box = event.currentTarget.getBoundingClientRect(), slack = 24;
+        if (event.clientX < box.left - slack || event.clientX > box.right + slack || event.clientY < box.top - slack || event.clientY > box.bottom + slack)
+            release();
+    }
+    function onKeyDown(event) {
+        if (event.key !== " " && event.key !== "Enter")
+            return;
+        event.preventDefault();
+        if (!event.repeat)
+            begin("key");
+    }
+    function onKeyUp(event) {
+        if (event.key !== " " && event.key !== "Enter")
+            return;
+        event.preventDefault();
+        if (source.current === "key")
+            release();
+    }
+    return _jsxs(_Fragment, { children: [_jsxs(motion.button, { ...props, ref: button, type: "button", className: [styles.button, className].filter(Boolean).join(" "), "data-tone": tone, "data-state": done ? "done" : holding ? "holding" : "idle", disabled: disabled, "aria-disabled": done || undefined, "aria-label": text, "aria-describedby": done ? undefined : hintId, style: { scale }, onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: release, onPointerCancel: release, onLostPointerCapture: release, onKeyDown: onKeyDown, onKeyUp: onKeyUp, onBlur: release, onContextMenu: event => event.preventDefault(), children: [_jsx(Face, { icon: icon, text: text, done: done, width: width, reduced: reduced, measure: measure }), _jsx(motion.span, { className: styles.fill, style: { clipPath }, "aria-hidden": "true", children: _jsx(Face, { icon: icon, text: text, done: done, width: width, reduced: reduced }) })] }), _jsx("span", { id: hintId, className: styles.srOnly, children: `Press and hold for ${seconds} seconds to confirm. With a keyboard, hold Space or Enter.` }), _jsx("span", { className: styles.srOnly, role: "status", children: done ? confirmedLabel : "" })] });
+}
+export default HoldToConfirm;