@teamofsilicons/silicon-ui 0.0.0-stage → 0.2.0

package/components/usage-meter/usage-meter.js

@@ -0,0 +1,296 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { AnimatePresence, animate, cancelFrame, frame, motion, motionValue, useInView, useMotionValue, useReducedMotion, useTransform } from "motion/react";
+import { CircleAlert, TriangleAlert } from "lucide-react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./usage-meter.module.css";
+const { spring, duration, ease, blur } = motionTokens;
+/** Motion drops inherited velocity on time-defined springs, so values that retarget mid-flight run the same springs written as stiffness and damping. */
+const physical = ({ visualDuration, bounce }, restDelta = .001) => { const root = (2 * Math.PI) / (visualDuration * 1.2); return { type: "spring", stiffness: root * root, damping: 2 * (1 - bounce) * root, restDelta, restSpeed: restDelta * 2 }; };
+const settle = physical(spring.smooth);
+const reveal = physical({ visualDuration: duration.considered + .1, bounce: 0 });
+const turn = physical(spring.smooth);
+const fit = physical(spring.morph, .01);
+/** A segment stops two pixels short of the next, so neighbours read apart without an outline. */
+const GAP = 2;
+const subscribeNothing = () => () => { };
+/** Reduced motion is only known in the browser, so the first client render matches the server before it takes effect. */
+function useReducedMotionSafe() {
+    const hydrated = useSyncExternalStore(subscribeNothing, () => true, () => false);
+    return { reduced: !!useReducedMotion() && hydrated, hydrated };
+}
+/** Starts animations on the next frame, so the render that caused them never swallows a spring's first frames. Returns a cleanup. */
+function soon(start) {
+    let controls = null;
+    const run = () => { controls = start(); };
+    frame.update(run);
+    return () => { cancelFrame(run); controls?.stop(); };
+}
+/** Changed text rises from a soft blur and leaves a little faster than it arrives. Icons cross through a small scale instead. */
+const rise = {
+    hidden: (direction) => ({ opacity: 0, y: `${.3 * direction}em`, scale: 1, filter: `blur(${blur.soft}px)` }),
+    shown: { opacity: 1, y: 0, scale: 1, filter: "blur(0px)", transition: { duration: duration.standard, ease: [...ease.enter] } },
+    gone: (direction) => ({ opacity: 0, y: `${-.3 * direction}em`, scale: 1, filter: `blur(${blur.subtle}px)`, transition: { duration: duration.instant, ease: [...ease.standard] } }),
+};
+const pop = {
+    hidden: { opacity: 0, y: 0, scale: .6, filter: `blur(${blur.subtle + 1}px)` },
+    shown: { opacity: 1, y: 0, scale: 1, filter: "blur(0px)", transition: { ...spring.snappy, opacity: { duration: duration.fast, ease: [...ease.enter] }, filter: { duration: duration.fast, ease: [...ease.enter] } } },
+    gone: { opacity: 0, y: 0, scale: .6, filter: `blur(${blur.subtle + 1}px)`, transition: { duration: duration.instant, ease: [...ease.standard] } },
+};
+const fade = { hidden: { opacity: 0, y: 0, scale: 1, filter: "blur(0px)" }, shown: { opacity: 1, y: 0, scale: 1, filter: "blur(0px)", transition: { duration: duration.fast } }, gone: { opacity: 0, y: 0, scale: 1, filter: "blur(0px)", transition: { duration: duration.instant } } };
+function Swap({ text, reduced, direction = 1 }) {
+    return _jsx("span", { className: styles.swap, children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, custom: direction, children: _jsx(motion.span, { className: styles.swapText, custom: direction, variants: reduced ? fade : rise, initial: "hidden", animate: "shown", exit: "gone", children: text }, text) }) });
+}
+const formats = new Map();
+/** Split a number into columns keyed by place value, so 9.8 → 10.4 keeps the ones column the ones column and a new tens column slides in. */
+function partsFor(value, decimals) {
+    let format = formats.get(decimals);
+    if (!format) {
+        format = new Intl.NumberFormat("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals });
+        formats.set(decimals, format);
+    }
+    const parts = format.formatToParts(value);
+    let place = parts.reduce((count, part) => count + (part.type === "integer" ? part.value.length : 0), 0), fraction = 0;
+    return parts.flatMap((part, index) => {
+        if (part.type === "integer")
+            return [...part.value].map(char => ({ key: `i${--place}`, digit: Number(char) }));
+        if (part.type === "fraction")
+            return [...part.value].map(char => ({ key: `f${fraction++}`, digit: Number(char) }));
+        return [{ key: part.type === "group" ? `g${place}` : part.type === "decimal" ? "d" : `${part.type}${index}`, text: part.value }];
+    });
+}
+const DIGITS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+/** One digit on a wheel; its distance from the wheel position sets where it sits and how clearly it shows. */
+function Glyph({ position, digit }) {
+    const offset = useTransform(position, current => ((((digit - current) % 10) + 15) % 10) - 5);
+    const y = useTransform(offset, current => `${current}em`);
+    const opacity = useTransform(offset, current => Math.max(0, 1 - Math.abs(current)));
+    const filter = useTransform(offset, current => Math.abs(current) < .02 || Math.abs(current) >= 1 ? "none" : `blur(${(Math.abs(current) * blur.subtle).toFixed(2)}px)`);
+    return _jsx(motion.span, { className: styles.glyph, style: { y, opacity, filter }, children: digit });
+}
+const column = { initial: { width: 0, opacity: 0 }, animate: { width: "auto", opacity: 1 }, exit: { width: 0, opacity: 0 } };
+/** A digit wheel that always turns the way the whole number moved, wrapping 9 → 0 like an odometer. */
+function Column({ digit, direction, reduced }) {
+    const position = useMotionValue(digit);
+    const wheel = useRef({ digit, target: digit });
+    const running = useRef(null);
+    useEffect(() => () => running.current?.(), []);
+    useEffect(() => {
+        const state = wheel.current;
+        if (state.digit === digit)
+            return;
+        state.target += direction < 0 ? -((state.digit - digit + 10) % 10) : (digit - state.digit + 10) % 10;
+        state.digit = digit;
+        running.current?.();
+        if (reduced) {
+            position.jump(state.target);
+            running.current = null;
+            return;
+        }
+        const target = state.target;
+        running.current = soon(() => animate(position, target, turn));
+    }, [digit, direction, position, reduced]);
+    return _jsxs(motion.span, { className: styles.column, ...column, transition: reduced ? { duration: 0 } : fit, children: [_jsx("span", { className: styles.sizer, children: "0" }), DIGITS.map(item => _jsx(Glyph, { position: position, digit: item }, item))] });
+}
+/** A number that rolls to each new value. It is decoration over text that screen readers get elsewhere. */
+function Ticker({ value, decimals, reduced }) {
+    const [trend, setTrend] = useState({ value, direction: 1 });
+    if (trend.value !== value)
+        setTrend({ value, direction: value > trend.value ? 1 : -1 });
+    return _jsx("span", { className: styles.ticker, "aria-hidden": "true", children: _jsx(AnimatePresence, { initial: false, children: partsFor(value, decimals).map(part => "digit" in part
+                ? _jsx(Column, { digit: part.digit, direction: trend.direction, reduced: reduced }, part.key)
+                : _jsx(motion.span, { className: styles.symbol, ...column, transition: reduced ? { duration: 0 } : fit, children: part.text }, part.key)) }) });
+}
+/** The plan status as a compact mark. Its width springs to each new message and the warning icon grows in beside the words. */
+function StatusBadge({ status, text, reduced }) {
+    const inner = useRef(null);
+    const width = useMotionValue("auto");
+    useLayoutEffect(() => {
+        const node = inner.current;
+        if (!node || typeof ResizeObserver === "undefined")
+            return;
+        let measured = false;
+        const observer = new ResizeObserver(() => {
+            const next = node.offsetWidth;
+            if (measured && !reduced)
+                animate(width, next, fit);
+            else
+                width.jump(next);
+            measured = next > 0;
+        });
+        observer.observe(node);
+        return () => observer.disconnect();
+    }, [reduced, width]);
+    const Icon = status === "over" ? TriangleAlert : CircleAlert;
+    return _jsx(motion.span, { className: styles.badge, "data-status": status, style: { width }, children: _jsxs("span", { ref: inner, className: styles.badgeInner, children: [_jsx(AnimatePresence, { mode: "popLayout", initial: false, children: status !== "ok" && _jsx(motion.span, { className: styles.badgeIcon, variants: reduced ? fade : pop, initial: "hidden", animate: "shown", exit: "gone", children: _jsx(Icon, { size: 14, strokeWidth: 2, "aria-hidden": "true" }) }, status) }), _jsx(Swap, { text: text, reduced: reduced })] }) });
+}
+function Segment({ index, amounts, span, width, highlight }) {
+    // Each segment starts where the ones before it end, so growth in any of them pushes the rest along in the same frame.
+    const x = useTransform(() => { let start = 0; for (let at = 0; at < index; at++)
+        start += amounts[at].get(); return (start / span.get()) * width.get(); });
+    const scaleX = useTransform(() => {
+        const w = width.get();
+        if (!w)
+            return 0;
+        const size = (amounts[index].get() / span.get()) * w, rest = w - x.get() - size;
+        return Math.max(0, size - Math.min(GAP, size, Math.max(0, rest))) / w;
+    });
+    return _jsx(motion.span, { className: styles.segment, "data-index": index, "data-highlight": highlight, style: { x, scaleX, originX: 0 } });
+}
+export function UsageMeter({ label, segments, limit, unit = "", decimals = 1, freeLabel = "Free", overLabel = "Over limit", warnAt = .9 }) {
+    const { reduced, hydrated } = useReducedMotionSafe();
+    const root = useRef(null);
+    const trackRef = useRef(null);
+    const inView = useInView(root, { once: true, amount: .4 });
+    const titleId = useId();
+    const hatchId = `hatch${titleId.replace(/[^a-zA-Z0-9_-]/g, "")}`;
+    const ready = hydrated && (inView || reduced);
+    const round = (value) => Math.round(value * 10 ** decimals) / 10 ** decimals;
+    const total = round(segments.reduce((sum, segment) => sum + segment.value, 0));
+    const free = round(Math.max(0, limit - total)), over = round(Math.max(0, total - limit));
+    const status = total > limit ? "over" : total >= limit * warnAt ? "near" : "ok";
+    const format = (value) => `${value.toFixed(decimals)}${unit ? ` ${unit}` : ""}`;
+    const limitText = format(limit).replace(/\.0+(?= |$)/, "");
+    // One motion value per segment id, kept across renders so a changed value springs from where it is.
+    const [store] = useState(() => new Map());
+    const amounts = segments.map(segment => { let value = store.get(segment.id); if (!value) {
+        value = motionValue(0);
+        store.set(segment.id, value);
+    } return value; });
+    const shownLimit = useMotionValue(limit);
+    const width = useMotionValue(0);
+    const used = useTransform(() => amounts.reduce((sum, amount) => sum + amount.get(), 0));
+    // The bar spans the limit, or everything used once that is more; both follow their springs, so crossing the limit is continuous.
+    const span = useTransform(() => Math.max(shownLimit.get(), used.get(), 1e-6));
+    const limitX = useTransform(() => Math.round((shownLimit.get() / span.get()) * width.get()));
+    // The limit marker and the hatch fade on their own short tween whenever usage crosses the limit, so a limit that jumps past usage never blinks them out in one frame.
+    const markerOpacity = useMotionValue(0);
+    useEffect(() => {
+        let over = used.get() > shownLimit.get();
+        markerOpacity.jump(over ? 1 : 0);
+        let fading;
+        const check = () => {
+            const next = used.get() > shownLimit.get();
+            if (next === over)
+                return;
+            over = next;
+            fading?.stop();
+            if (reduced)
+                markerOpacity.jump(next ? 1 : 0);
+            else
+                fading = animate(markerOpacity, next ? 1 : 0, { duration: duration.fast, ease: [...ease.standard] });
+        };
+        const stops = [used.on("change", check), shownLimit.on("change", check)];
+        return () => { stops.forEach(stop => stop()); fading?.stop(); };
+    }, [markerOpacity, reduced, shownLimit, used]);
+    const overClip = useTransform(() => `inset(0 0 0 ${limitX.get() + GAP}px)`);
+    useLayoutEffect(() => {
+        const node = trackRef.current;
+        if (!node)
+            return;
+        width.set(node.clientWidth);
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => width.set(node.clientWidth));
+        observer.observe(node);
+        return () => observer.disconnect();
+    }, [width]);
+    // Segments grow into place once seen, left to right; later changes re-flow every segment on one spring each.
+    const values = segments.map(segment => `${segment.id}:${segment.value}`).join("|");
+    const revealed = useRef(false);
+    useEffect(() => {
+        if (!ready)
+            return;
+        const first = !revealed.current;
+        revealed.current = true;
+        const stops = segments.map((segment, index) => {
+            const amount = store.get(segment.id);
+            if (!amount || amount.get() === segment.value)
+                return null;
+            if (reduced) {
+                amount.jump(segment.value);
+                return null;
+            }
+            return soon(() => animate(amount, segment.value, first ? { ...reveal, delay: index * .07 } : settle));
+        });
+        return () => stops.forEach(stop => stop?.());
+        // `values` carries every segment id and value.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [values, ready, reduced, store]);
+    useEffect(() => {
+        if (shownLimit.get() === limit)
+            return;
+        if (reduced) {
+            shownLimit.jump(limit);
+            return;
+        }
+        return soon(() => animate(shownLimit, limit, settle));
+    }, [limit, reduced, shownLimit]);
+    // Hover previews a category, focus previews it too, and a press pins it until pressed again or Escape.
+    const [hovered, setHovered] = useState(null);
+    const [focused, setFocused] = useState(null);
+    const [pinned, setPinned] = useState(null);
+    const [roving, setRoving] = useState(0);
+    const items = [...segments.map(segment => ({ id: segment.id, label: segment.label, value: segment.value })), { id: "free", label: status === "over" ? overLabel : freeLabel, value: status === "over" ? over : free }];
+    const active = hovered ?? focused ?? pinned;
+    const activeItem = items.find(item => item.id === active) ?? null;
+    const legend = useRef(null);
+    const idAt = (clientX) => {
+        const rect = trackRef.current?.getBoundingClientRect();
+        if (!rect?.width)
+            return null;
+        const at = ((clientX - rect.left) / rect.width) * Math.max(limit, total);
+        // Past the limit the hatch stands for the overage, so pointing there highlights it rather than the category beneath.
+        if (at > limit)
+            return "free";
+        let end = 0;
+        for (const segment of segments) {
+            end += segment.value;
+            if (at <= end)
+                return segment.id;
+        }
+        return "free";
+    };
+    const onTrackMove = (event) => { if (event.pointerType === "mouse")
+        setHovered(idAt(event.clientX)); };
+    const onTrackTap = (event) => { if (event.pointerType !== "mouse") {
+        const id = idAt(event.clientX);
+        setPinned(current => current === id ? null : id);
+    } };
+    const onLegendKey = (event) => {
+        if (event.key === "Escape") {
+            if (pinned || focused) {
+                event.preventDefault();
+                setPinned(null);
+            }
+            return;
+        }
+        const next = { ArrowRight: roving + 1, ArrowDown: roving + 1, ArrowLeft: roving - 1, ArrowUp: roving - 1, Home: 0, End: items.length - 1 }[event.key];
+        if (next === undefined)
+            return;
+        event.preventDefault();
+        const index = (next + items.length) % items.length;
+        setRoving(index);
+        legend.current?.querySelectorAll("button")[index]?.focus();
+    };
+    const headline = ready ? (activeItem ? activeItem.value : total) : 0;
+    const share = activeItem ? Math.round((activeItem.value / limit) * 100) : 0;
+    const caption = !activeItem ? `${unit} of ${limitText} used` : activeItem.id === "free" ? `${unit} ${status === "over" ? "over the limit" : "free"}` : `${unit} in ${activeItem.label} · ${share}% of plan`;
+    const badge = status === "over" ? `${format(over)} over` : status === "near" ? "Almost full" : `${format(free)} free`;
+    const summary = `${label}: ${format(total)} of ${limitText} used. ${segments.map(segment => `${segment.label} ${format(segment.value)}`).join(", ")}. ${status === "over" ? `Over the limit by ${format(over)}.` : `${format(free)} free${status === "near" ? ", almost full" : ""}.`}`;
+    // Status changes are announced, and so is a growing overage; routine changes inside a status stay quiet.
+    const notice = status === "over" ? `over:${over}` : status;
+    const [announced, setAnnounced] = useState({ notice, message: "" });
+    if (announced.notice !== notice)
+        setAnnounced({ notice, message: status === "over" ? `Over the plan limit by ${format(over)}.` : status === "near" ? `Almost full. ${format(free)} free.` : `Under the limit. ${format(free)} free.` });
+    return _jsxs("div", { ref: root, className: styles.meter, role: "group", "aria-labelledby": titleId, "data-status": status, children: [_jsxs("div", { className: styles.top, children: [_jsx("span", { id: titleId, className: styles.title, children: label }), _jsx(StatusBadge, { status: status, text: badge, reduced: reduced })] }), _jsxs("p", { className: styles.total, children: [_jsxs("span", { className: styles.srOnly, children: [format(total), " of ", limitText, " used"] }), _jsx("span", { className: styles.amount, "aria-hidden": "true", children: _jsx(Ticker, { value: headline, decimals: decimals, reduced: reduced }) }), _jsx("span", { className: styles.caption, "aria-hidden": "true", children: _jsx(Swap, { text: caption, reduced: reduced }) })] }), _jsxs("div", { className: styles.bar, children: [_jsxs("div", { ref: trackRef, className: styles.track, role: "img", "aria-label": summary, "data-active": active ?? undefined, onPointerMove: onTrackMove, onPointerLeave: () => setHovered(null), onPointerUp: onTrackTap, children: [segments.map((segment, index) => _jsx(Segment, { index: index, amounts: amounts, span: span, width: width, highlight: active ? active === segment.id ? "on" : "off" : undefined }, segment.id)), _jsxs(motion.svg, { className: styles.overflow, "data-highlight": active ? active === "free" ? "on" : "off" : undefined, style: { clipPath: overClip, opacity: markerOpacity }, "aria-hidden": "true", focusable: "false", children: [_jsx("defs", { children: _jsx("pattern", { id: hatchId, width: 6, height: 6, patternUnits: "userSpaceOnUse", patternTransform: "rotate(45)", children: _jsx("rect", { width: 2.5, height: 6, className: styles.hatch }) }) }), _jsx("rect", { className: styles.overTint, width: "100%", height: "100%" }), _jsx("rect", { width: "100%", height: "100%", fill: `url(#${hatchId})` })] })] }), _jsx(motion.span, { className: styles.limit, style: { x: limitX, opacity: markerOpacity }, "aria-hidden": "true" })] }), _jsx("div", { ref: legend, className: styles.legend, role: "group", "aria-label": `${label} by category`, onKeyDown: onLegendKey, children: items.map((item, index) => {
+                    const warning = item.id === "free" && status === "over";
+                    return _jsxs("button", { type: "button", className: styles.item, "data-highlight": active ? active === item.id ? "on" : "off" : undefined, "aria-pressed": pinned === item.id, "aria-label": `${item.label}, ${format(item.value)}`, tabIndex: index === roving ? 0 : -1, onClick: () => { setRoving(index); setPinned(current => current === item.id ? null : item.id); }, onFocus: () => { setRoving(index); setFocused(item.id); }, onBlur: () => setFocused(null), onPointerEnter: event => { if (event.pointerType === "mouse")
+                            setHovered(item.id); }, onPointerLeave: event => { if (event.pointerType === "mouse")
+                            setHovered(null); }, children: [_jsxs("span", { className: styles.itemHead, children: [_jsx("span", { className: styles.key, "aria-hidden": "true", children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, children: warning
+                                                ? _jsx(motion.span, { className: styles.keyIcon, variants: reduced ? fade : pop, initial: "hidden", animate: "shown", exit: "gone", children: _jsx(TriangleAlert, { size: 12, strokeWidth: 2 }) }, "alert")
+                                                : _jsx(motion.span, { className: styles.swatch, "data-index": item.id === "free" ? "free" : index, variants: reduced ? fade : pop, initial: "hidden", animate: "shown", exit: "gone" }, "swatch") }) }), _jsx("span", { className: styles.itemLabel, children: _jsx(Swap, { text: item.label, reduced: reduced }) })] }), _jsxs("span", { className: styles.itemValue, children: [_jsx(Ticker, { value: item.value, decimals: decimals, reduced: reduced }), unit && _jsx("span", { className: styles.itemUnit, children: unit })] })] }, item.id);
+                }) }), _jsx("p", { className: styles.srOnly, "aria-live": "polite", "aria-atomic": "true", children: announced.message })] });
+}
+export default UsageMeter;

package/components/usage-meter/usage-meter.module.css

@@ -0,0 +1,61 @@
+/* Categories are steps of the accent, strongest first, so the meter reads as one allowance rather than a rainbow. Free space is the track itself. */
+.meter { --segment-0: var(--accent); --segment-1: color-mix(in oklab, var(--accent) 62%, var(--surface)); --segment-2: color-mix(in oklab, var(--accent) 36%, var(--surface)); --segment-3: color-mix(in oklab, var(--accent) 22%, var(--surface)); display: grid; min-width: 0; gap: var(--space-inset); color: var(--foreground); }
+.top { display: flex; min-width: 0; min-height: 28px; align-items: center; justify-content: space-between; gap: var(--space-group); }
+/* A long label wraps beside the status mark instead of hiding its end. */
+.title { min-width: 0; color: var(--foreground); font-size: var(--text-base); font-weight: 500; letter-spacing: var(--tracking-body); line-height: var(--leading-body); text-wrap: balance; }
+
+/* The status mark hugs its words: its width springs to each message and grows from the right edge, so the text never slides. */
+.badge { display: inline-flex; flex: none; height: 28px; justify-content: flex-end; overflow: hidden; border-radius: var(--radius-full); corner-shape: round; background: var(--surface-muted); color: var(--text-secondary); font-size: var(--text-xs); font-weight: 500; line-height: 1; transition: background-color var(--duration-standard) var(--ease-standard), color var(--duration-standard) var(--ease-standard); }
+.badgeInner { display: inline-flex; flex: none; align-items: center; gap: 6px; padding: 0 var(--space-group); white-space: nowrap; }
+.badgeIcon { display: grid; place-items: center; }
+.badge[data-status="near"] { background: color-mix(in oklab, var(--warning) 14%, var(--surface)); color: var(--foreground); }
+.badge[data-status="near"] .badgeIcon { color: var(--warning); }
+.badge[data-status="over"] { background: color-mix(in oklab, var(--danger) 12%, var(--surface)); color: var(--foreground); }
+.badge[data-status="over"] .badgeIcon { color: var(--danger); }
+
+.total { display: flex; min-width: 0; align-items: baseline; gap: var(--space-related); margin: 0; }
+.amount { flex: none; font-family: var(--font-display); font-size: var(--text-3xl); font-weight: 500; letter-spacing: var(--tracking-display); line-height: var(--leading-display); }
+.caption { min-width: 0; flex: 1; color: var(--text-secondary); font-size: var(--text-sm); }
+.swap { position: relative; display: block; min-width: 0; }
+.swapText { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+/* The bar leaves room above and below the track for the limit marker. */
+.bar { position: relative; padding-block: 5px; }
+.track { position: relative; height: 14px; overflow: hidden; border-radius: var(--radius-full); corner-shape: round; background: color-mix(in oklab, var(--foreground) 7%, var(--surface)); isolation: isolate; -webkit-tap-highlight-color: transparent; }
+.segment { position: absolute; inset: 0; transition: opacity var(--duration-fast) var(--ease-standard); }
+.segment[data-index="0"], .swatch[data-index="0"] { background: var(--segment-0); }
+.segment[data-index="1"], .swatch[data-index="1"] { background: var(--segment-1); }
+.segment[data-index="2"], .swatch[data-index="2"] { background: var(--segment-2); }
+.segment[data-index="3"], .swatch[data-index="3"] { background: var(--segment-3); }
+.segment[data-highlight="off"] { opacity: .28; }
+/* Past the limit the used colours stay, struck through by a hatch; highlighting the overage floods it with the danger colour. */
+.overflow { position: absolute; inset: 0; width: 100%; height: 100%; pointer-events: none; }
+.hatch { fill: var(--surface); }
+.overTint { fill: var(--danger); opacity: 0; transition: opacity var(--duration-fast) var(--ease-standard); }
+.overflow[data-highlight="on"] .overTint { opacity: 1; }
+.limit { position: absolute; top: 0; bottom: 0; left: -1px; width: 2px; border-radius: var(--radius-full); corner-shape: round; background: var(--foreground); pointer-events: none; }
+
+/* The legend doubles as the keyboard path: arrow keys move between categories, focus previews one, a press pins it. */
+.legend { display: grid; grid-template-columns: repeat(auto-fit, minmax(108px, 1fr)); gap: 2px; margin: 0 calc(var(--space-related) * -1); }
+.item { display: grid; min-width: 0; justify-items: start; gap: 2px; padding: var(--space-related); border: 0; border-radius: calc(var(--radius-control) - 6px); corner-shape: var(--corner-shape); background: transparent; color: inherit; font: inherit; text-align: left; cursor: pointer; -webkit-tap-highlight-color: transparent; transition: background-color var(--duration-fast) var(--ease-standard), opacity var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .item:hover { background: var(--surface-muted); } }
+.item[aria-pressed="true"] { background: var(--surface-muted); }
+.item[data-highlight="off"] { opacity: .45; }
+.itemHead { display: flex; min-width: 0; max-width: 100%; align-items: center; gap: var(--space-related); color: var(--text-secondary); font-size: var(--text-sm); line-height: var(--leading-body); }
+.itemLabel { min-width: 0; flex: 1; }
+.key { display: grid; width: 12px; height: 12px; flex: none; place-items: center; }
+.swatch { grid-area: 1 / 1; width: 10px; height: 10px; border-radius: var(--radius-detail); corner-shape: var(--corner-shape); }
+.swatch[data-index="free"] { background: color-mix(in oklab, var(--foreground) 7%, var(--surface)); box-shadow: inset 0 0 0 1px var(--border-strong); }
+.keyIcon { grid-area: 1 / 1; display: grid; place-items: center; color: var(--danger); }
+.itemValue { display: flex; align-items: baseline; gap: 4px; padding-left: 20px; color: var(--foreground); font-size: var(--text-base); font-weight: 500; line-height: var(--leading-body); }
+.itemUnit { color: var(--text-secondary); font-size: var(--text-sm); font-weight: 400; }
+
+/* A rolling number: each digit is a clipped wheel that feathers at its edges, and new columns open from zero width. */
+.ticker { position: relative; display: inline-flex; align-items: flex-start; white-space: nowrap; font-variant-numeric: tabular-nums; user-select: none; }
+.column { --feather: .16em; position: relative; display: inline-block; overflow: hidden; margin-block: calc(var(--feather) * -1); padding-block: var(--feather); mask-image: linear-gradient(to bottom, transparent, #000 calc(var(--feather) * 1.5), #000 calc(100% - var(--feather) * 1.5), transparent); }
+.sizer { visibility: hidden; }
+.glyph { position: absolute; inset: var(--feather) 0; text-align: center; }
+.symbol { display: inline-block; overflow-x: clip; }
+
+.srOnly { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+@media (prefers-reduced-motion: reduce) { .badge, .segment, .item, .overTint { transition: none; } }

package/components/user-menu/user-menu.d.ts

@@ -0,0 +1,62 @@
+import type { ReactNode, Ref } from "react";
+export type UserStatus = "available" | "busy" | "away";
+export type ThemePreference = "light" | "dark" | "system";
+/** Statuses in menu order. Each one has its own dot shape as well as color: solid, barred, or hollow. */
+export declare const userStatuses: {
+    value: UserStatus;
+    label: string;
+}[];
+export interface UserMenuUser {
+    name: string;
+    email: string;
+    plan?: string;
+    avatarSrc?: string;
+    avatarSrcSet?: string;
+}
+export interface UserMenuItem {
+    label: string;
+    icon?: ReactNode;
+    keys?: string[];
+    onSelect?: () => void;
+}
+/**
+ * The account menu behind a person's photo in an app's top bar. It holds a compact identity header, a short group of account
+ * destinations, an inline theme switch, and sign out. On screens narrower than 640px it opens as a bottom sheet instead.
+ * Theme and status choices keep the menu open; everything else closes it and returns focus to the trigger.
+ * When `onSignOut` returns a promise, the item shows its progress and the menu closes once it settles.
+ */
+export interface UserMenuProps {
+    user: UserMenuUser;
+    /** Presence status. Passing `status` or `onStatusChange` shows the presence dot and an inline status switch. */
+    status?: UserStatus;
+    defaultStatus?: UserStatus;
+    onStatusChange?: (status: UserStatus) => void;
+    theme?: ThemePreference;
+    defaultTheme?: ThemePreference;
+    /** Reports the choice. Applying it to the page is up to the app. */
+    onThemeChange?: (theme: ThemePreference) => void;
+    /** Shows the inline light, dark, and system switch. */
+    showTheme?: boolean;
+    /** Account destinations with optional shortcut hints, such as ["⌘", ","]. Keep it to three or four. */
+    items?: UserMenuItem[];
+    onSignOut?: () => void | Promise<unknown>;
+    signOutKeys?: string[];
+    align?: "start" | "center" | "end";
+    /** Shows the name and a chevron beside the avatar from 640px up. */
+    showName?: boolean;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Renders the desktop panel in a portal on the body. Pass false to keep it inside the trigger's wrapper. */
+    portal?: boolean;
+    /** The trigger button, for returning focus after the menu is swapped out. */
+    ref?: Ref<HTMLButtonElement>;
+    className?: string;
+}
+/** A presence mark that morphs between statuses: the color crossfades while a hole opens for away and a bar slides in for busy. */
+export declare function PresenceDot({ status, className }: {
+    status: UserStatus | "offline";
+    className?: string;
+}): import("react").JSX.Element;
+export declare function UserMenu({ user, status: statusProp, defaultStatus, onStatusChange, theme: themeProp, defaultTheme, onThemeChange, showTheme, items, onSignOut, signOutKeys, align, showName, open: openProp, defaultOpen, onOpenChange, portal, ref, className }: UserMenuProps): import("react").JSX.Element;
+export default UserMenu;