@teamofsilicons/silicon-ui 0.0.0-stage → 0.2.0

package/components/donut-chart/donut-chart.js

@@ -0,0 +1,382 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useImperativeHandle, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { AnimatePresence, animate, frame, cancelFrame, motion, motionValue, useInView, useReducedMotion } from "motion/react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./donut-chart.module.css";
+const OTHER = "__other";
+const TAU = Math.PI * 2;
+const { spring, ease, stagger, duration } = 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 = .0005) => { const root = (2 * Math.PI) / (visualDuration * 1.2); return { type: "spring", stiffness: root * root, damping: 2 * (1 - bounce) * root, restDelta, restSpeed: restDelta * 2 }; };
+const reveal = physical({ visualDuration: .72, bounce: 0 });
+const settle = physical({ visualDuration: .5, bounce: 0 });
+const pop = physical(spring.snappy, .002);
+/** Neutral steps after the four series colors, and the quietest step for Other. */
+const NEUTRAL = [56, 42, 32];
+const seriesColor = (index) => index < 4 ? `var(--series-${index + 1})` : `color-mix(in oklab, var(--foreground) ${NEUTRAL[(index - 4) % NEUTRAL.length]}%, var(--surface))`;
+const OTHER_COLOR = "color-mix(in oklab, var(--foreground) 26%, var(--surface))";
+/** Room left outside the ring for the lift; the gap between segments and their corner radius, in pixels. */
+const LIFT = 4, GROW = 2, MARGIN = 7, GAP = 3, CORNER = 4;
+const grouped = new Intl.NumberFormat("en-US", { maximumFractionDigits: 1 });
+const percent = new Intl.NumberFormat("en-US", { style: "percent", maximumFractionDigits: 0 });
+const shareText = (share) => share > 0 && share < .01 ? "<1%" : percent.format(share);
+/** Small parts join one "Other" segment, but only when at least two would; grouping a single part hides it for nothing. */
+function sliceData(data, groupBelow, maxSegments, otherLabel) {
+    const parts = data.filter(item => item.value > 0);
+    const total = parts.reduce((sum, item) => sum + item.value, 0);
+    if (!total)
+        return [];
+    const ranked = [...parts].sort((a, b) => b.value - a.value);
+    const keep = new Set(ranked.filter((item, rank) => item.value / total >= groupBelow && rank < maxSegments - 1).map(item => item.key));
+    const rest = parts.filter(item => !keep.has(item.key));
+    if (rest.length < 2)
+        return parts.map(item => ({ ...item }));
+    return [...parts.filter(item => keep.has(item.key)).map(item => ({ ...item })), { key: OTHER, label: otherLabel, value: rest.reduce((sum, item) => sum + item.value, 0), members: rest }];
+}
+/** Turns of the ring for each slice in data order; a hidden slice closes to a point where it sits. */
+function layout(slices, hidden) {
+    const total = slices.reduce((sum, item) => sum + (hidden.has(item.key) ? 0 : item.value), 0) || 1;
+    let at = 0;
+    return new Map(slices.map(item => { const arc = { start: at, end: at + (hidden.has(item.key) ? 0 : item.value / total) }; at = arc.end; return [item.key, arc]; }));
+}
+/** Half the width, in pixels, of a sector's outer edge once the gap is cut; below a couple of pixels a segment fades rather than drawing a hairline. */
+function breadth(R, t0, t1, gap) {
+    const turns = t1 - t0;
+    if (turns >= 1 - 1e-6)
+        return Infinity;
+    return Math.sin(Math.min(turns * Math.PI, Math.PI / 2)) * R - Math.min(gap / 2, ((1 - turns) * TAU * R) / 2);
+}
+const n2 = (value) => (Math.round(value * 100) / 100).toString();
+/**
+ * An annular sector between two turns of the ring, measured clockwise from the top, with rounded corners.
+ * Its sides run parallel to the radius at a fixed distance, so the gap between neighbours is the same number of pixels from the inner edge to the outer one.
+ * A thin sector narrows to a wedge and then to nothing, so a closing segment never pops.
+ */
+function sector(c, R, r, t0, t1, gap, corner) {
+    const turns = t1 - t0;
+    if (turns <= 1e-6)
+        return "";
+    const at = (radius, angle) => `${n2(c + radius * Math.cos(angle))} ${n2(c + radius * Math.sin(angle))}`;
+    if (turns >= 1 - 1e-6)
+        return `M${at(R, -Math.PI / 2)}A${n2(R)} ${n2(R)} 0 1 1 ${at(R, Math.PI / 2)}A${n2(R)} ${n2(R)} 0 1 1 ${at(R, -Math.PI / 2)}ZM${at(r, -Math.PI / 2)}A${n2(r)} ${n2(r)} 0 1 0 ${at(r, Math.PI / 2)}A${n2(r)} ${n2(r)} 0 1 0 ${at(r, -Math.PI / 2)}Z`;
+    // Half the gap on each side; a lone segment closes its gap as the rest of the ring empties, so it becomes a whole ring without a jump.
+    const p = Math.min(gap / 2, ((1 - turns) * TAU * R) / 2);
+    const a0 = t0 * TAU - Math.PI / 2, a1 = t1 * TAU - Math.PI / 2, half = (a1 - a0) / 2, s = Math.sin(Math.min(half, Math.PI / 2));
+    if (s * R <= p + 1e-6)
+        return "";
+    const side = (t, angle, sign) => `${n2(c + t * Math.cos(angle) - sign * p * Math.sin(angle))} ${n2(c + t * Math.sin(angle) + sign * p * Math.cos(angle))}`;
+    const band = (R - r) / 2;
+    const ro = Math.max(0, Math.min(corner, band, s >= .9999 ? Infinity : (s * R - p) / (1 + s)));
+    const dO = Math.asin(Math.min(1, (p + ro) / (R - ro))), tO = Math.sqrt(Math.max(0, (R - ro) ** 2 - (p + ro) ** 2));
+    const bigO = a1 - a0 - 2 * dO > Math.PI ? 1 : 0;
+    let d = `M${side(tO, a0, 1)}`;
+    if (ro > .01)
+        d += `A${n2(ro)} ${n2(ro)} 0 0 1 ${at(R, a0 + dO)}`;
+    d += `A${n2(R)} ${n2(R)} 0 ${bigO} 1 ${at(R, a1 - dO)}`;
+    if (ro > .01)
+        d += `A${n2(ro)} ${n2(ro)} 0 0 1 ${side(tO, a1, -1)}`;
+    if (s * r > p + 1e-6 || s >= .9999) {
+        const ri = Math.max(0, Math.min(corner, band, s >= .9999 ? Infinity : (s * r - p) / (1 - s)));
+        const dI = Math.asin(Math.min(1, (p + ri) / (r + ri))), tI = Math.sqrt(Math.max(0, (r + ri) ** 2 - (p + ri) ** 2));
+        const bigI = a1 - a0 - 2 * dI > Math.PI ? 1 : 0;
+        d += `L${side(tI, a1, -1)}`;
+        if (ri > .01)
+            d += `A${n2(ri)} ${n2(ri)} 0 0 1 ${at(r, a1 - dI)}`;
+        d += `A${n2(r)} ${n2(r)} 0 ${bigI} 0 ${at(r, a0 + dI)}`;
+        if (ri > .01)
+            d += `A${n2(ri)} ${n2(ri)} 0 0 1 ${side(tI, a0, 1)}`;
+    }
+    else
+        d += `L${at(p / s, (a0 + a1) / 2)}`;
+    return `${d}Z`;
+}
+/** A number that counts to each new value, written straight to the DOM so no frame re-renders React. Whole targets count in whole steps. */
+function Count({ value, format, reduced }) {
+    const node = useRef(null);
+    const [initial] = useState(() => format(value));
+    const live = useRef(null);
+    useLayoutEffect(() => {
+        const el = node.current;
+        if (!el)
+            return;
+        if (!live.current) {
+            const state = { mv: motionValue(value), format, target: value };
+            state.mv.on("change", now => { el.textContent = state.format(Number.isInteger(state.target) ? Math.round(now) : now); });
+            live.current = state;
+        }
+        const state = live.current;
+        state.format = format;
+        if (state.target === value && !reduced) {
+            if (!state.mv.isAnimating())
+                el.textContent = format(value);
+            return;
+        }
+        state.target = value;
+        if (reduced) {
+            state.mv.jump(value);
+            el.textContent = format(value);
+            return;
+        }
+        animate(state.mv, value, physical({ visualDuration: .4, bounce: 0 }, Math.max(Math.abs(value - state.mv.get()) * .001, 1e-6)));
+    }, [value, format, reduced]);
+    useEffect(() => () => { live.current?.mv.destroy(); live.current = null; }, []);
+    return _jsx("span", { ref: node, children: initial });
+}
+/** Center readouts stay mounted in one grid cell and roll like a drum: the ones before the active segment wait above, the ones after it below. */
+const drum = (place, reduced) => ({
+    animate: { opacity: place === 0 ? 1 : 0, y: `${.45 * Math.sign(place)}em` },
+    transition: reduced ? { duration: 0 } : place === 0 ? { duration: duration.standard, ease: [...ease.enter] } : { duration: duration.fast, ease: [...ease.standard] },
+});
+const subscribeNothing = () => () => { };
+function useReducedMotionSafe() {
+    const hydrated = useSyncExternalStore(subscribeNothing, () => true, () => false);
+    return !!useReducedMotion() && hydrated;
+}
+export function DonutChart({ data, label, unit = "", formatValue = value => grouped.format(value), totalLabel = "Total", size = 208, thickness = 24, groupBelow = .04, maxSegments = 6, otherLabel = "Other", activeKey, defaultActiveKey = null, onActiveChange, hiddenKeys, defaultHiddenKeys, onHiddenKeysChange, legendAction = "toggle", legend = true, emptyLabel = "No data yet", ref, className }) {
+    const reduced = useReducedMotionSafe();
+    const figure = useRef(null);
+    useImperativeHandle(ref, () => figure.current);
+    const inView = useInView(figure, { once: true, amount: .35 });
+    const legendId = useId();
+    const slices = sliceData(data, groupBelow, maxSegments, otherLabel);
+    // Hidden segments are controlled or not, like selection.
+    const [ownHidden, setOwnHidden] = useState(defaultHiddenKeys ?? []);
+    const hiddenList = hiddenKeys ?? ownHidden;
+    const hidden = new Set(hiddenList.filter(key => slices.some(item => item.key === key)));
+    const visible = slices.filter(item => !hidden.has(item.key));
+    const total = visible.reduce((sum, item) => sum + item.value, 0);
+    const signature = `${slices.map(item => `${item.key}:${item.value}${hidden.has(item.key) ? "h" : ""}`).join("|")}`;
+    const suffix = unit ? ` ${unit}` : "";
+    // Colors follow a key from the first time it is seen, so a segment keeps its color through every dataset.
+    const [palette, setPalette] = useState(() => new Map(data.map((item, index) => [item.key, index])));
+    if (data.some(item => !palette.has(item.key))) {
+        const next = new Map(palette);
+        for (const item of data)
+            if (!next.has(item.key))
+                next.set(item.key, next.size);
+        setPalette(next);
+    }
+    const colorFor = (item) => item.color ?? (item.key === OTHER ? OTHER_COLOR : seriesColor(palette.get(item.key) ?? 0));
+    // Leaving segments stay drawn in their old place while they close, then drop out once they have.
+    const [drawn, setDrawn] = useState(slices);
+    const [seenSignature, setSeenSignature] = useState(signature);
+    if (seenSignature !== signature) {
+        setSeenSignature(signature);
+        const next = [...slices];
+        drawn.forEach((item, index) => {
+            if (next.some(slice => slice.key === item.key))
+                return;
+            const before = drawn.slice(0, index).reverse().find(prior => next.some(slice => slice.key === prior.key));
+            next.splice(before ? next.findIndex(slice => slice.key === before.key) + 1 : 0, 0, { ...item, value: 0 });
+        });
+        setDrawn(next);
+    }
+    // Selection is controlled or not; hover and focus preview on top of it.
+    const [ownActive, setOwnActive] = useState(defaultActiveKey);
+    const selected = activeKey !== undefined ? activeKey : ownActive;
+    const [preview, setPreview] = useState(null);
+    const select = (key) => { if (activeKey === undefined)
+        setOwnActive(key); onActiveChange?.(key); };
+    const current = [preview, selected].find(key => key && visible.some(item => item.key === key)) ?? null;
+    const activeSlice = visible.find(item => item.key === current) ?? null;
+    const [announcement, setAnnouncement] = useState("");
+    const setHidden = (key) => {
+        const isHidden = hidden.has(key);
+        if (!isHidden && visible.length <= 1)
+            return;
+        const next = isHidden ? hiddenList.filter(item => item !== key) : [...hiddenList, key];
+        if (hiddenKeys === undefined)
+            setOwnHidden(next);
+        onHiddenKeysChange?.(next);
+        const item = slices.find(slice => slice.key === key);
+        const nextTotal = slices.reduce((sum, slice) => sum + (next.includes(slice.key) ? 0 : slice.value), 0);
+        if (item)
+            setAnnouncement(`${item.label} ${isHidden ? "shown" : "hidden"}. ${totalLabel} ${formatValue(nextTotal)}${suffix}.`);
+    };
+    // Geometry in the chart's own units; the SVG scales with its container.
+    const c = size / 2, outer = c - MARGIN, inner = Math.max(8, outer - thickness);
+    const corner = Math.min(CORNER, thickness / 4);
+    const geometry = useRef({ c, outer, inner, corner });
+    const segments = useRef(new Map());
+    const paths = useRef(new Map());
+    const registerPath = useCallback((node) => {
+        const key = node?.dataset.key;
+        if (!node || !key)
+            return;
+        paths.current.set(key, node);
+        return () => { if (paths.current.get(key) === node)
+            paths.current.delete(key); };
+    }, []);
+    // One paint per frame, whatever moved: every path's shape and lift are written straight to the DOM.
+    const paint = useCallback(() => {
+        const { c, outer, inner, corner } = geometry.current;
+        for (const [key, node] of paths.current) {
+            const segment = segments.current.get(key);
+            if (!segment) {
+                node.setAttribute("d", "");
+                continue;
+            }
+            const start = segment.start.get(), end = segment.end.get(), lift = Math.max(0, segment.lift.get());
+            const R = outer + lift * GROW;
+            node.setAttribute("d", sector(c, R, inner - lift * GROW * .5, start, end, GAP, corner));
+            node.setAttribute("fill-opacity", n2(Math.min(1, Math.max(0, (breadth(R, start, end, GAP) - 1) / 3))));
+            const middle = ((start + end) / 2) * TAU - Math.PI / 2, distance = lift * LIFT;
+            node.setAttribute("transform", `translate(${n2(Math.cos(middle) * distance)} ${n2(Math.sin(middle) * distance)})`);
+        }
+    }, []);
+    const schedule = useCallback(() => { frame.render(paint); }, [paint]);
+    useLayoutEffect(() => { geometry.current = { c, outer, inner, corner }; paint(); });
+    useEffect(() => () => { cancelFrame(paint); for (const segment of segments.current.values())
+        segment.off(); segments.current.clear(); }, [paint]);
+    const targets = useRef(new Map());
+    const latest = useRef({ drawn, slices });
+    useLayoutEffect(() => { latest.current = { drawn, slices }; });
+    // New data, or a segment shown or hidden, moves every arc from wherever it is on screen, keeping its velocity if it was already moving.
+    const shown = inView || reduced;
+    useEffect(() => {
+        if (!shown)
+            return;
+        const { drawn: order, slices: now } = latest.current;
+        const goal = layout(now, hidden);
+        targets.current = goal;
+        const first = segments.current.size === 0;
+        const place = (index) => { const before = order.slice(0, index).reverse().find(item => goal.has(item.key)); return before ? goal.get(before.key).end : 0; };
+        const drop = (key) => {
+            if (latest.current.slices.some(item => item.key === key))
+                return;
+            segments.current.get(key)?.off();
+            segments.current.delete(key);
+            setDrawn(list => list.filter(item => item.key !== key));
+        };
+        order.forEach((item, index) => {
+            const leaving = !goal.has(item.key);
+            const to = goal.get(item.key) ?? { start: place(index), end: place(index) };
+            let segment = segments.current.get(item.key);
+            if (!segment) {
+                // A new segment opens from the edge of the one before it, as it is right now.
+                const prior = order.slice(0, index).reverse().map(entry => segments.current.get(entry.key)).find(Boolean);
+                const from = first ? 0 : prior ? prior.end.get() : 0;
+                const start = motionValue(from), end = motionValue(from), lift = motionValue(0);
+                const offs = [start.on("change", schedule), end.on("change", schedule), lift.on("change", schedule)];
+                segment = { start, end, lift, off: () => { offs.forEach(off => off()); start.destroy(); end.destroy(); lift.destroy(); } };
+                segments.current.set(item.key, segment);
+            }
+            if (reduced) {
+                segment.start.jump(to.start);
+                segment.end.jump(to.end);
+                if (leaving)
+                    drop(item.key);
+                return;
+            }
+            if (first) {
+                // One sweep: every segment leaves the top together, and each trailing edge follows a beat behind the one before.
+                animate(segment.start, to.start, reveal);
+                animate(segment.end, to.end, { ...reveal, delay: .04 + index * stagger.item });
+                return;
+            }
+            animate(segment.start, to.start, settle);
+            animate(segment.end, to.end, { ...settle, onComplete: leaving ? () => drop(item.key) : undefined });
+        });
+        schedule();
+    }, [shown, signature, reduced, schedule]); // eslint-disable-line react-hooks/exhaustive-deps
+    // The active segment slides out along its middle and thickens a little; the one it replaces settles back at the same time.
+    useEffect(() => {
+        for (const [key, segment] of segments.current) {
+            const to = key === current ? 1 : 0;
+            if (reduced)
+                segment.lift.jump(to);
+            else if (segment.lift.get() !== to || segment.lift.isAnimating())
+                animate(segment.lift, to, pop);
+        }
+    }, [current, reduced, drawn, shown]);
+    // One pointer handler for the whole ring: the angle picks the segment, so crossing a gap never drops the hover.
+    const svg = useRef(null);
+    const hit = (event) => {
+        const box = svg.current?.getBoundingClientRect();
+        if (!box || !box.width)
+            return undefined;
+        const scale = size / box.width, x = (event.clientX - box.left) * scale - c, y = (event.clientY - box.top) * scale - c;
+        const radius = Math.hypot(x, y);
+        if (radius < inner - 6 || radius > c)
+            return null;
+        let turn = (Math.atan2(y, x) + Math.PI / 2) / TAU;
+        if (turn < 0)
+            turn += 1;
+        for (const [key, arc] of targets.current)
+            if (arc.end > arc.start && turn >= arc.start && turn < arc.end && visible.some(item => item.key === key))
+                return key;
+        return undefined;
+    };
+    const onRingMove = (event) => {
+        if (event.pointerType !== "mouse")
+            return;
+        const key = hit(event);
+        if (key !== undefined && key !== preview)
+            setPreview(key);
+    };
+    const onRingClick = (event) => {
+        const key = hit(event);
+        if (key)
+            select(selected === key ? null : key);
+    };
+    const format = (value) => `${formatValue(value)}${suffix}`;
+    const describe = (item) => `${item.label}, ${format(item.value)}, ${shareText(item.value / (total || 1))}${item.members ? `. Includes ${item.members.map(member => member.label).join(", ")}` : ""}`;
+    // Arrow keys walk the segments, in the legend or on the ring itself when there is no legend.
+    const rows = useRef([]);
+    const step = (key, index, count) => ({ ArrowDown: index + 1, ArrowRight: index + 1, ArrowUp: index - 1, ArrowLeft: index - 1, Home: 0, End: count - 1 }[key]);
+    const onLegendKey = (event, index) => {
+        if (event.key === "Escape" && selected) {
+            event.preventDefault();
+            select(null);
+            return;
+        }
+        const next = step(event.key, index, slices.length);
+        if (next === undefined)
+            return;
+        event.preventDefault();
+        rows.current[(next + slices.length) % slices.length]?.focus();
+    };
+    const onRingKey = (event) => {
+        if (!visible.length)
+            return;
+        if (event.key === "Escape") {
+            event.preventDefault();
+            setPreview(null);
+            if (selected)
+                select(null);
+            return;
+        }
+        if ((event.key === "Enter" || event.key === " ") && current) {
+            event.preventDefault();
+            select(selected === current ? null : current);
+            return;
+        }
+        const index = visible.findIndex(item => item.key === current);
+        const next = step(event.key, index < 0 ? (event.key.endsWith("Up") || event.key.endsWith("Left") ? 0 : -1) : index, visible.length);
+        if (next === undefined)
+            return;
+        event.preventDefault();
+        const item = visible[(next + visible.length) % visible.length];
+        setPreview(item.key);
+        setAnnouncement(describe(item));
+    };
+    const onLegendBlur = (event) => { if (!(event.relatedTarget instanceof Node && event.currentTarget.closest("ul")?.contains(event.relatedTarget)))
+        setPreview(null); };
+    // One readout per segment plus the total; the active one rolls in from the side it sits on, so moving clockwise rolls the drum forward.
+    const identity = activeSlice ? activeSlice.key : total ? "__total" : "__empty";
+    const readouts = [{ key: "__total", label: total ? totalLabel : emptyLabel, value: total, meta: null }, ...slices.map(item => ({ key: item.key, label: item.label, value: item.value, meta: item }))];
+    const activeIndex = Math.max(0, readouts.findIndex(item => item.key === (identity === "__empty" ? "__total" : identity)));
+    const summary = total ? `${label}. ${totalLabel} ${format(total)}. ${visible.map(describe).join(". ")}.` : `${label}. ${emptyLabel}.`;
+    const members = (item) => item.members ? item.members.length > 2 ? `${item.members.slice(0, 2).map(member => member.label).join(", ")} and ${item.members.length - 2} more` : item.members.map(member => member.label).join(" and ") : null;
+    const ringLabel = `${label}. Use the arrow keys to read each segment.`;
+    return _jsxs("figure", { ref: figure, className: [styles.figure, className].filter(Boolean).join(" "), "aria-label": label, "data-legend": legend || undefined, children: [_jsxs("div", { className: styles.ring, style: { width: size, "--inner": `${(inner * 2) / size * 100}%` }, tabIndex: legend ? undefined : 0, role: legend ? undefined : "group", "aria-label": legend ? undefined : ringLabel, onKeyDown: legend ? undefined : onRingKey, onBlur: legend ? undefined : () => setPreview(null), children: [_jsxs("svg", { ref: svg, className: styles.svg, viewBox: `0 0 ${size} ${size}`, "aria-hidden": "true", focusable: "false", onPointerMove: onRingMove, onPointerLeave: () => setPreview(null), onClick: onRingClick, "data-hovering": current !== null || undefined, children: [_jsx("circle", { className: styles.track, cx: c, cy: c, r: (outer + inner) / 2, strokeWidth: outer - inner, "data-idle": (!shown || !total) || undefined }), drawn.map(item => _jsx("path", { ref: registerPath, "data-key": item.key, className: styles.segment, "data-active": item.key === current || undefined, "data-dim": (current !== null && item.key !== current) || undefined, style: { "--slice": colorFor(item) } }, item.key))] }), _jsx("div", { className: styles.center, "aria-hidden": "true", children: readouts.map((item, index) => _jsxs(motion.span, { className: styles.readout, initial: false, ...drum(index - activeIndex, reduced), children: [_jsx("span", { className: styles.centerLabel, children: item.label }), _jsx("span", { className: styles.centerValue, children: item.value || item.meta ? _jsx(Count, { value: item.value, format: formatValue, reduced: reduced }) : " " }), _jsx("span", { className: styles.centerMeta, children: item.meta ? _jsxs(_Fragment, { children: [_jsx(Count, { value: total && !hidden.has(item.key) ? item.value / total : 0, format: shareText, reduced: reduced }), " of ", totalLabel.toLowerCase()] }) : unit || " " })] }, item.key)) })] }), legend && slices.length > 0 && _jsx("ul", { className: styles.legend, "aria-label": `${label}, segments${legendAction === "toggle" ? ". Press a segment to show or hide it" : ""}`, id: legendId, onPointerLeave: () => setPreview(null), children: _jsx(AnimatePresence, { initial: false, children: slices.map((item, index) => {
+                        const off = hidden.has(item.key);
+                        // A row that joins or leaves (a part folding into Other, say) opens or closes its height, so the rows below and the card around them glide instead of jumping.
+                        return _jsx(motion.li, { className: styles.item, initial: { height: 0, opacity: 0 }, animate: { height: "auto", opacity: 1 }, exit: { height: 0, opacity: 0 }, transition: reduced ? { duration: 0 } : spring.smooth, children: _jsxs("button", { ref: node => { if (node)
+                                    rows.current[index] = node; }, type: "button", className: styles.row, "aria-pressed": legendAction === "toggle" ? !off : selected === item.key, "aria-label": off ? `${item.label}, hidden` : describe(item), "data-active": item.key === current || undefined, "data-pinned": selected === item.key || undefined, "data-hidden": off || undefined, style: { "--slice": colorFor(item) }, onClick: () => legendAction === "toggle" ? setHidden(item.key) : select(selected === item.key ? null : item.key), onPointerEnter: event => { if (event.pointerType === "mouse")
+                                    setPreview(off ? null : item.key); }, onFocus: event => { if (event.currentTarget.matches(":focus-visible"))
+                                    setPreview(off ? null : item.key); }, onBlur: onLegendBlur, onKeyDown: event => onLegendKey(event, index), children: [_jsx("span", { className: styles.dot, "aria-hidden": "true" }), _jsxs("span", { className: styles.rowText, children: [_jsx("span", { className: styles.rowLabel, children: item.label }), item.members && _jsx("span", { className: styles.rowMembers, children: members(item) })] }), _jsx("span", { className: styles.rowValue, "aria-hidden": "true", children: _jsx(Count, { value: item.value, format: formatValue, reduced: reduced }) }), _jsx("span", { className: styles.rowShare, "aria-hidden": "true", children: _jsx(Count, { value: off || !total ? 0 : item.value / total, format: shareText, reduced: reduced }) })] }) }, item.key);
+                    }) }) }), _jsx("p", { className: styles.srOnly, children: summary }), _jsx("p", { className: styles.srOnly, "aria-live": "polite", children: announcement }), total > 0 && _jsxs("table", { className: styles.srOnly, children: [_jsx("caption", { children: label }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Segment" }), _jsx("th", { scope: "col", children: "Value" }), _jsx("th", { scope: "col", children: "Share" })] }) }), _jsx("tbody", { children: visible.flatMap(item => item.members ? item.members.map(member => ({ key: member.key, label: `${member.label} (${otherLabel})`, value: member.value })) : [item]).map(item => _jsxs("tr", { children: [_jsx("th", { scope: "row", children: item.label }), _jsx("td", { children: format(item.value) }), _jsx("td", { children: shareText(item.value / total) })] }, item.key)) })] })] });
+}
+export default DonutChart;

package/components/donut-chart/donut-chart.module.css

@@ -0,0 +1,48 @@
+/* The ring sits beside its legend when there is room, and above it on a phone. */
+.figure { container-type: inline-size; display: grid; min-width: 0; margin: 0; color: var(--foreground); font-family: var(--font-body); letter-spacing: var(--tracking-body); }
+.figure > * { min-width: 0; }
+.figure[data-legend] { gap: var(--space-section); }
+@container (min-width: 460px) {
+  .figure[data-legend] { grid-template-columns: auto minmax(0, 1fr); align-items: center; gap: var(--space-block); }
+}
+
+.ring { position: relative; max-width: 100%; aspect-ratio: 1; justify-self: center; -webkit-tap-highlight-color: transparent; }
+.svg { display: block; width: 100%; height: 100%; overflow: visible; cursor: default; }
+.svg[data-hovering] { cursor: pointer; }
+/* The track shows only before the first sweep and when there is nothing to draw, so the gaps between segments stay the page colour. */
+.track { fill: none; stroke: var(--surface-muted); transition: opacity var(--duration-considered, .48s) var(--ease-standard); opacity: 0; }
+.track[data-idle] { opacity: 1; }
+/* Shapes are written every frame from script; only colour and dimming ease here, on the compositor. */
+.segment { fill: var(--slice); shape-rendering: geometricPrecision; transition: fill var(--duration-standard) var(--ease-standard), opacity var(--duration-standard) var(--ease-standard); }
+.segment[data-dim] { opacity: .45; }
+
+/* The centre reads the active segment, or the total at rest. Old and new readouts share one grid cell, so a swap never moves or resizes anything. */
+.center { position: absolute; top: 50%; left: 50%; display: grid; width: calc(var(--inner) - 16px); transform: translate(-50%, -50%); pointer-events: none; }
+.readout { grid-area: 1 / 1; display: grid; min-width: 0; justify-items: center; gap: 2px; text-align: center; }
+.centerLabel, .centerMeta { display: block; width: 100%; min-height: calc(1em * var(--leading-body)); overflow: hidden; font-size: var(--text-xs); line-height: var(--leading-body); text-overflow: ellipsis; white-space: nowrap; }
+.centerLabel { color: var(--text-secondary); }
+.centerMeta { color: var(--text-muted); font-variant-numeric: tabular-nums; }
+.centerValue { display: block; max-width: 100%; min-height: calc(1em * var(--leading-display)); overflow: hidden; font-family: var(--font-display); font-size: var(--text-2xl); font-weight: 500; letter-spacing: var(--tracking-display); line-height: var(--leading-display); font-variant-numeric: tabular-nums; text-overflow: ellipsis; white-space: nowrap; }
+
+/* Legend rows mirror the segments: hovering either lights both. */
+/* Rows carry their own 2px spacing so a row closing its height takes its gap with it; the list's negative margin drops the last one. */
+.legend { display: grid; margin: 0 0 -2px; padding: 0; list-style: none; }
+.item { overflow: hidden; }
+.item > .row { margin-bottom: 2px; }
+.row { display: grid; width: 100%; min-height: 40px; grid-template-columns: 10px minmax(0, 1fr) auto 3.25em; align-items: center; column-gap: 10px; padding: 6px 10px; border: 0; border-radius: var(--radius-control); corner-shape: var(--corner-shape); background: transparent; color: var(--foreground); cursor: pointer; font: inherit; font-size: var(--text-sm); line-height: var(--leading-body); text-align: left; -webkit-tap-highlight-color: transparent; transition: background-color var(--duration-fast) var(--ease-standard), transform var(--duration-instant) var(--ease-standard); }
+.row:active { transform: scale(.985); }
+.row[data-active], .row[data-pinned] { background: color-mix(in oklab, var(--foreground) 5%, transparent); }
+.dot { width: 10px; height: 10px; border-radius: 50%; corner-shape: round; background: var(--slice); box-shadow: inset 0 0 0 1.5px var(--slice); transition: background-color var(--duration-standard) var(--ease-standard), box-shadow var(--duration-standard) var(--ease-standard); }
+/* A hidden segment keeps its row: the dot empties to a ring and the text quiets, so it can be shown again. */
+.row[data-hidden] .dot { background: transparent; }
+.row[data-hidden] .rowLabel, .row[data-hidden] .rowValue, .row[data-hidden] .rowShare { color: var(--text-muted); }
+.rowLabel, .rowValue, .rowShare { transition: color var(--duration-standard) var(--ease-standard); }
+.rowText { display: grid; min-width: 0; }
+.rowLabel, .rowMembers { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.rowMembers { color: var(--text-muted); font-size: var(--text-xs); }
+.rowValue { justify-self: end; color: var(--text-secondary); font-variant-numeric: tabular-nums; }
+.rowShare { justify-self: end; color: var(--foreground); font-weight: 500; font-variant-numeric: tabular-nums; }
+@media (hover: hover) and (pointer: fine) { .row:hover { background: color-mix(in oklab, var(--foreground) 5%, transparent); } }
+
+.srOnly { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+@media (prefers-reduced-motion: reduce) { .segment, .track, .row, .dot, .rowLabel, .rowValue, .rowShare { transition: none; } }

package/components/drawer/drawer.d.ts

@@ -0,0 +1,20 @@
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+/**
+ * The last item a drawer showed. Pass the selected item (or null when nothing is open) and render the drawer's content
+ * from the result, so the content stays on screen while the panel slides out instead of vanishing the moment it closes.
+ */
+export declare function useDrawerItem<T>(item: T | null | undefined): T | null | undefined;
+export declare function Drawer({ open: openProp, defaultOpen, onOpenChange, ...props }: ComponentPropsWithoutRef<typeof DialogPrimitive.Root>): import("react").JSX.Element;
+export declare const DrawerTrigger: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & import("react").RefAttributes<HTMLButtonElement>>;
+export declare const DrawerClose: import("react").ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & import("react").RefAttributes<HTMLButtonElement>>;
+export interface DrawerContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content> {
+    title: string;
+    description?: string;
+    children: ReactNode;
+    side?: "left" | "right" | "top" | "bottom";
+    /** Renders the drawer inside this element instead of the page body, anchored to its edges. The element needs position: relative and overflow: hidden. */
+    container?: HTMLElement | null;
+}
+export declare function DrawerContent({ title, description, children, side, container, className, onInteractOutside, onEscapeKeyDown, onOpenAutoFocus, onCloseAutoFocus, ...props }: DrawerContentProps): import("react").JSX.Element;
+export default Drawer;

package/components/drawer/drawer.js

@@ -0,0 +1,111 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { createContext, useCallback, useContext, useMemo, useRef, useState } from "react";
+import { AnimatePresence, animate, motion, useMotionValue, useReducedMotion } from "motion/react";
+import { X } from "lucide-react";
+import { ESCAPE_LAYER_ATTRIBUTE, layerEscape } from "../../lib/escape.js";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import { useReturnFocus } from "../../lib/return-focus.js";
+import styles from "./drawer.module.css";
+/**
+ * The last item a drawer showed. Pass the selected item (or null when nothing is open) and render the drawer's content
+ * from the result, so the content stays on screen while the panel slides out instead of vanishing the moment it closes.
+ */
+export function useDrawerItem(item) {
+    const [last, setLast] = useState(item);
+    if (item != null && item !== last)
+        setLast(item);
+    return item ?? last;
+}
+/** Mirrors the open state so the panel can stay mounted while it slides out, retarget mid-flight, and close itself after a drag. */
+const DrawerContext = createContext(null);
+export function Drawer({ open: openProp, defaultOpen = false, onOpenChange, ...props }) {
+    const [uncontrolled, setUncontrolled] = useState(defaultOpen);
+    // A drag that dismisses the panel hands its velocity to the exit spring; every other close uses the shorter tween.
+    const [flung, setFlung] = useState(false);
+    // When the drawer last opened, so a click that reopens it mid-close is not also read as a click outside the leaving panel.
+    const openedAt = useRef(0);
+    const open = openProp ?? uncontrolled;
+    const setOpen = useCallback((next) => {
+        setFlung(false);
+        if (next)
+            openedAt.current = performance.now();
+        if (openProp === undefined)
+            setUncontrolled(next);
+        onOpenChange?.(next);
+    }, [openProp, onOpenChange]);
+    const fling = useCallback(() => { setOpen(false); setFlung(true); }, [setOpen]);
+    const value = useMemo(() => ({ open, flung, setOpen, fling, openedAt }), [open, flung, setOpen, fling]);
+    return _jsx(DrawerContext.Provider, { value: value, children: _jsx(DialogPrimitive.Root, { ...props, open: open, onOpenChange: setOpen }) });
+}
+export const DrawerTrigger = DialogPrimitive.Trigger;
+export const DrawerClose = DialogPrimitive.Close;
+const fade = { duration: motionTokens.duration.instant };
+/* A click or Escape returns the panel quickly; a flick keeps its velocity in a spring of the same length. The shadow fades over the last stretch so it leaves with the panel instead of popping away at unmount. */
+const shadowOut = { duration: motionTokens.duration.standard, times: [0, .65, 1], ease: "linear" };
+const leave = { default: { duration: motionTokens.duration.standard, ease: [...motionTokens.ease.standard] }, opacity: shadowOut };
+const flingOut = { default: { ...motionTokens.spring.smooth, visualDuration: motionTokens.duration.standard }, opacity: shadowOut };
+/** When the title or description changes while open, the new copy rises in and the old copy leaves upward. */
+function SwapText({ text }) {
+    const reduced = useReducedMotion();
+    return (_jsx(AnimatePresence, { mode: "popLayout", initial: false, children: _jsx(motion.span, { className: styles.swap, initial: reduced ? false : { opacity: 0, y: "0.3em", filter: `blur(${motionTokens.blur.soft}px)` }, animate: { opacity: 1, y: 0, filter: "blur(0px)" }, exit: reduced ? { opacity: 0, transition: { duration: 0 } } : { opacity: 0, y: "-0.3em", filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.standard] } }, transition: { duration: motionTokens.duration.standard, ease: [...motionTokens.ease.enter] }, children: text }, text) }));
+}
+export function DrawerContent({ title, description, children, side = "right", container, className, onInteractOutside, onEscapeKeyDown, onOpenAutoFocus, onCloseAutoFocus, ...props }) {
+    const drawer = useContext(DrawerContext);
+    const reduced = useReducedMotion();
+    // Closing puts focus back on what opened the drawer, Trigger or not (lib/return-focus.ts).
+    const returnFocus = useReturnFocus(drawer?.open, onOpenAutoFocus, onCloseAutoFocus);
+    // Escape inside belongs to an open list, calendar or question first (lib/escape.ts); the next one closes the drawer.
+    const escape = { [ESCAPE_LAYER_ATTRIBUTE]: "", onEscapeKeyDown: layerEscape(onEscapeKeyDown), ...returnFocus };
+    const panelRef = useRef(null);
+    const offset = useMotionValue(0);
+    const pan = useRef(null);
+    const axis = side === "left" || side === "right" ? "x" : "y";
+    const sign = side === "right" || side === "bottom" ? 1 : -1;
+    const offscreen = { [axis]: `${sign * 100}%` };
+    const classes = [styles.content, className].filter(Boolean).join(" ");
+    const draggable = drawer !== null && !reduced;
+    const panelSize = () => (axis === "x" ? panelRef.current?.offsetWidth : panelRef.current?.offsetHeight) ?? 480;
+    // The header is the grab handle. It follows the pointer toward the edge and rubber-bands the other way.
+    function panStart(event) {
+        const target = event.target instanceof Element ? event.target : null;
+        if (!draggable || target?.closest("button, a, input, select, textarea, [role='button']"))
+            return;
+        // The entrance animates in percent of the panel, so a grab mid-flight converts it to pixels.
+        const value = offset.get();
+        pan.current = typeof value === "number" ? value : parseFloat(value) / 100 * panelSize();
+        offset.stop();
+    }
+    function panMove(_, info) {
+        if (pan.current === null)
+            return;
+        const toward = (pan.current + info.offset[axis]) * sign;
+        offset.set(sign * (toward >= 0 ? toward : -Math.sqrt(-toward)));
+    }
+    // Past a third of the panel, or on a quick flick toward the edge, the drawer closes and keeps its velocity; otherwise it springs back.
+    function panEnd(_, info) {
+        if (pan.current === null)
+            return;
+        pan.current = null;
+        const toward = Number(offset.get()) * sign;
+        if (toward > panelSize() / 3 || (toward > 0 && info.velocity[axis] * sign > 500))
+            drawer?.fling();
+        else
+            animate(offset, 0, motionTokens.spring.snappy);
+    }
+    const inner = _jsxs(_Fragment, { children: [_jsxs(motion.div, { className: [styles.header, draggable ? styles.handle : ""].filter(Boolean).join(" "), onPanStart: panStart, onPan: panMove, onPanEnd: panEnd, children: [_jsxs("div", { children: [_jsx(DialogPrimitive.Title, { className: styles.title, children: _jsx(SwapText, { text: title }) }), description ? (_jsx(DialogPrimitive.Description, { className: styles.description, children: _jsx(SwapText, { text: description }) })) : null] }), _jsx(DialogPrimitive.Close, { className: styles.close, "aria-label": "Close drawer", children: _jsx(X, { size: 16, strokeWidth: 1.75, "aria-hidden": "true" }) })] }), _jsx("div", { className: styles.body, children: children })] });
+    // Under a bare Radix root the open state is unknown here, so CSS keyframes keyed off data-state animate the layers instead.
+    if (drawer === null) {
+        return (_jsxs(DialogPrimitive.Portal, { container: container, children: [_jsx(DialogPrimitive.Overlay, { className: `${styles.overlay} ${styles.keyframes}`, "data-contained": container ? "" : undefined }), _jsx(DialogPrimitive.Content, { ...props, ...escape, onInteractOutside: onInteractOutside, "data-side": side, "data-contained": container ? "" : undefined, className: `${classes} ${styles.keyframes}`, children: inner })] }));
+    }
+    // The panel springs fully opaque from its own edge and returns to it faster than it arrived, from wherever it is.
+    return (_jsx(AnimatePresence, { custom: drawer.flung, children: drawer.open && (_jsxs(DialogPrimitive.Portal, { forceMount: true, container: container, children: [_jsx(DialogPrimitive.Overlay, { asChild: true, forceMount: true, children: _jsx(motion.div, { className: styles.overlay, "data-contained": container ? "" : undefined, initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0, transition: reduced ? fade : { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.standard] } }, transition: reduced ? fade : { duration: motionTokens.duration.standard, ease: [...motionTokens.ease.enter] } }) }), _jsx(DialogPrimitive.Content, { ...props, ...escape, asChild: true, forceMount: true, 
+                    // Radix reads a click outside on click, so the press that reopens a closing drawer would dismiss it again.
+                    onInteractOutside: event => {
+                        onInteractOutside?.(event);
+                        if (event.detail.originalEvent.timeStamp < drawer.openedAt.current)
+                            event.preventDefault();
+                    }, children: _jsx(motion.div, { ref: panelRef, className: classes, "data-side": side, "data-contained": container ? "" : undefined, style: { [axis]: offset }, variants: { exit: (flung) => reduced ? { opacity: 0, transition: fade } : { ...offscreen, opacity: [1, 1, 0], transition: flung ? flingOut : leave } }, initial: reduced ? { opacity: 0 } : { ...offscreen, opacity: 1 }, animate: reduced ? { opacity: 1 } : { [axis]: 0, opacity: 1 }, exit: "exit", transition: reduced ? fade : motionTokens.spring.smooth, children: inner }) })] }, "drawer")) }));
+}
+export default Drawer;