@teamofsilicons/silicon-ui 0.0.0-stage → 0.2.0

package/components/scroll-area/scroll-area.d.ts

@@ -0,0 +1,40 @@
+import type { CSSProperties, HTMLAttributes, ReactNode, Ref, UIEvent } from "react";
+/** Which edges still have content beyond them. */
+export interface ScrollAreaEdges {
+    top: boolean;
+    bottom: boolean;
+    left: boolean;
+    right: boolean;
+}
+/**
+ * A native scroll container with thin overlay scrollbars that appear while scrolling or on hover and fade away at rest.
+ * Each edge fades out only when there is more content beyond it, in proportion to how much. Scrolling stays native, so
+ * keyboard, touch momentum, and scroll snap all behave as the platform expects.
+ */
+export interface ScrollAreaProps extends Omit<HTMLAttributes<HTMLDivElement>, "onScroll"> {
+    children?: ReactNode;
+    /** Axes that scroll. Defaults to vertical. */
+    orientation?: "vertical" | "horizontal" | "both";
+    /** Length of the edge fade in px. 0 turns the fades off. */
+    fade?: number;
+    /** "auto" shows scrollbars while scrolling or hovering; "always" keeps them visible when content overflows. */
+    scrollbars?: "auto" | "always";
+    /** How long scrollbars linger after scrolling stops, in ms. */
+    hideDelay?: number;
+    /** Maximum height of the viewport, for vertical areas that should grow with their content. */
+    maxHeight?: CSSProperties["maxHeight"];
+    /** Passed to the viewport's `scroll-snap-type`, for example "x mandatory". Children set their own `scroll-snap-align`. */
+    snap?: CSSProperties["scrollSnapType"];
+    /** Accessible name. The viewport becomes a labelled, focusable region that arrow and page keys scroll. */
+    label?: string;
+    /** Turns vertical wheel movement into horizontal scrolling for horizontal areas. Defaults to true. */
+    wheelToHorizontal?: boolean;
+    viewportClassName?: string;
+    viewportStyle?: CSSProperties;
+    viewportRef?: Ref<HTMLDivElement>;
+    onScroll?: (event: UIEvent<HTMLDivElement>) => void;
+    /** Called when content starts or stops extending past an edge. */
+    onEdgeChange?: (edges: ScrollAreaEdges) => void;
+}
+export declare const ScrollArea: import("react").ForwardRefExoticComponent<ScrollAreaProps & import("react").RefAttributes<HTMLDivElement>>;
+export default ScrollArea;

package/components/scroll-area/scroll-area.js

@@ -0,0 +1,153 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useRef } from "react";
+import styles from "./scroll-area.module.css";
+const MIN_THUMB = 28;
+export const ScrollArea = forwardRef(function ScrollArea({ children, orientation = "vertical", fade = 28, scrollbars = "auto", hideDelay = 900, maxHeight, snap, label, wheelToHorizontal = true, viewportClassName, viewportStyle, viewportRef, onScroll, onEdgeChange, className, ...rest }, forwardedRef) {
+    const rootRef = useRef(null);
+    const viewport = useRef(null);
+    const tracks = useRef({ x: null, y: null });
+    const thumbs = useRef({ x: null, y: null });
+    const hideTimer = useRef(undefined);
+    const lastEdges = useRef("");
+    const onEdgeRef = useRef(onEdgeChange);
+    useImperativeHandle(forwardedRef, () => rootRef.current);
+    useImperativeHandle(viewportRef, () => viewport.current);
+    useEffect(() => { onEdgeRef.current = onEdgeChange; }, [onEdgeChange]);
+    const vertical = orientation !== "horizontal", horizontal = orientation !== "vertical";
+    /* Everything visual is written straight to the DOM on each scroll frame, so scrolling never re-renders React. */
+    const sync = useCallback(() => {
+        const node = viewport.current, root = rootRef.current;
+        if (!node || !root)
+            return;
+        const { scrollTop, scrollLeft, scrollHeight, scrollWidth, clientHeight, clientWidth } = node;
+        const maxY = Math.max(0, scrollHeight - clientHeight), maxX = Math.max(0, scrollWidth - clientWidth);
+        // RTL layouts report negative scrollLeft; distance from the start edge is its magnitude.
+        const left = Math.abs(scrollLeft);
+        const edges = { top: vertical && scrollTop > .5, bottom: vertical && maxY - scrollTop > .5, left: horizontal && left > .5, right: horizontal && maxX - left > .5 };
+        if (fade > 0) {
+            node.style.setProperty("--fade-top", `${vertical ? Math.min(fade, scrollTop) : 0}px`);
+            node.style.setProperty("--fade-bottom", `${vertical ? Math.min(fade, maxY - scrollTop) : 0}px`);
+            node.style.setProperty("--fade-left", `${horizontal ? Math.min(fade, left) : 0}px`);
+            node.style.setProperty("--fade-right", `${horizontal ? Math.min(fade, maxX - left) : 0}px`);
+        }
+        const place = (axis, scroll, max, client, total) => {
+            const track = tracks.current[axis], thumb = thumbs.current[axis];
+            if (!track || !thumb)
+                return;
+            const overflowing = max > .5;
+            track.toggleAttribute("data-hidden", !overflowing);
+            if (!overflowing)
+                return;
+            const length = axis === "y" ? track.clientHeight : track.clientWidth;
+            const size = Math.max(MIN_THUMB, length * client / total);
+            const offset = (length - size) * (scroll / max);
+            thumb.style[axis === "y" ? "height" : "width"] = `${size}px`;
+            thumb.style.transform = axis === "y" ? `translate3d(0, ${offset}px, 0)` : `translate3d(${offset}px, 0, 0)`;
+        };
+        if (vertical)
+            place("y", scrollTop, maxY, clientHeight, scrollHeight);
+        if (horizontal)
+            place("x", left, maxX, clientWidth, scrollWidth);
+        root.toggleAttribute("data-overflow", maxY > .5 || maxX > .5);
+        const key = `${edges.top}${edges.bottom}${edges.left}${edges.right}`;
+        if (key !== lastEdges.current) {
+            lastEdges.current = key;
+            onEdgeRef.current?.(edges);
+        }
+    }, [fade, horizontal, vertical]);
+    useLayoutEffect(() => {
+        const node = viewport.current;
+        if (!node)
+            return;
+        sync();
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => sync());
+        observer.observe(node);
+        Array.from(node.children).forEach(child => observer.observe(child));
+        const mutations = new MutationObserver(() => { observer.disconnect(); observer.observe(node); Array.from(node.children).forEach(child => observer.observe(child)); sync(); });
+        mutations.observe(node, { childList: true });
+        return () => { observer.disconnect(); mutations.disconnect(); };
+    }, [sync]);
+    useEffect(() => () => window.clearTimeout(hideTimer.current), []);
+    const wake = () => {
+        const root = rootRef.current;
+        if (!root)
+            return;
+        root.setAttribute("data-scrolling", "");
+        window.clearTimeout(hideTimer.current);
+        hideTimer.current = window.setTimeout(() => root.removeAttribute("data-scrolling"), hideDelay);
+    };
+    const handleScroll = (event) => {
+        sync();
+        wake();
+        onScroll?.(event);
+    };
+    // A mouse wheel over a horizontal strip moves it sideways, but only while there is room, so the page still scrolls at the ends.
+    useEffect(() => {
+        const node = viewport.current;
+        if (!node || orientation !== "horizontal" || !wheelToHorizontal)
+            return;
+        const wheel = (event) => {
+            if (event.ctrlKey || Math.abs(event.deltaX) >= Math.abs(event.deltaY))
+                return;
+            const max = node.scrollWidth - node.clientWidth, at = Math.abs(node.scrollLeft);
+            if (max <= 0 || (event.deltaY < 0 && at <= 0) || (event.deltaY > 0 && at >= max - .5))
+                return;
+            event.preventDefault();
+            node.scrollLeft += event.deltaY * (getComputedStyle(node).direction === "rtl" ? -1 : 1);
+        };
+        node.addEventListener("wheel", wheel, { passive: false });
+        return () => node.removeEventListener("wheel", wheel);
+    }, [orientation, wheelToHorizontal]);
+    /* Dragging a thumb maps pointer travel to scroll distance; pressing the track pages toward the pointer. */
+    const drag = useRef(null);
+    const onThumbDown = (event, axis) => {
+        const node = viewport.current, track = tracks.current[axis], thumb = thumbs.current[axis];
+        if (!node || !track || !thumb || event.button !== 0)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        const length = axis === "y" ? track.clientHeight : track.clientWidth, size = axis === "y" ? thumb.offsetHeight : thumb.offsetWidth;
+        const max = axis === "y" ? node.scrollHeight - node.clientHeight : node.scrollWidth - node.clientWidth;
+        drag.current = { axis, start: axis === "y" ? event.clientY : event.clientX, scroll: axis === "y" ? node.scrollTop : node.scrollLeft, ratio: max / Math.max(1, length - size) };
+        rootRef.current?.setAttribute("data-dragging", axis);
+        node.style.scrollSnapType = "none";
+    };
+    const onThumbMove = (event) => {
+        const state = drag.current, node = viewport.current;
+        if (!state || !node)
+            return;
+        const delta = ((state.axis === "y" ? event.clientY : event.clientX) - state.start) * state.ratio;
+        if (state.axis === "y")
+            node.scrollTop = state.scroll + delta;
+        else
+            node.scrollLeft = state.scroll + delta;
+    };
+    const onThumbUp = (event) => {
+        if (!drag.current)
+            return;
+        drag.current = null;
+        if (event.currentTarget.hasPointerCapture(event.pointerId))
+            event.currentTarget.releasePointerCapture(event.pointerId);
+        rootRef.current?.removeAttribute("data-dragging");
+        if (viewport.current)
+            viewport.current.style.scrollSnapType = "";
+        wake();
+    };
+    const onTrackDown = (event, axis) => {
+        const node = viewport.current, thumb = thumbs.current[axis];
+        if (!node || !thumb || event.button !== 0 || event.target !== event.currentTarget)
+            return;
+        const rect = thumb.getBoundingClientRect();
+        const before = axis === "y" ? event.clientY < rect.top : event.clientX < rect.left;
+        const page = (axis === "y" ? node.clientHeight : node.clientWidth) * .9 * (before ? -1 : 1);
+        const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+        node.scrollBy({ [axis === "y" ? "top" : "left"]: page, behavior: reduce ? "auto" : "smooth" });
+    };
+    const bar = (axis) => _jsx("div", { ref: node => { tracks.current[axis] = node; }, className: styles.track, "data-axis": axis, "data-hidden": "", "aria-hidden": "true", onPointerDown: event => onTrackDown(event, axis), children: _jsx("div", { ref: node => { thumbs.current[axis] = node; }, className: styles.thumb, onPointerDown: event => onThumbDown(event, axis), onPointerMove: onThumbMove, onPointerUp: onThumbUp, onPointerCancel: onThumbUp }) });
+    return _jsxs("div", { ref: rootRef, className: [styles.root, className].filter(Boolean).join(" "), "data-orientation": orientation, "data-scrollbars": scrollbars, ...rest, children: [_jsx("div", { ref: viewport, className: [styles.viewport, viewportClassName].filter(Boolean).join(" "), "data-fade": fade > 0 ? orientation : undefined, style: { maxHeight, scrollSnapType: snap, ...viewportStyle }, tabIndex: 0, role: label ? "region" : undefined, "aria-label": label, onScroll: handleScroll, children: children }), vertical && bar("y"), horizontal && bar("x")] });
+});
+export default ScrollArea;

package/components/scroll-area/scroll-area.module.css

@@ -0,0 +1,79 @@
+.root { position: relative; display: flex; min-width: 0; min-height: 0; flex-direction: column; overflow: hidden; }
+
+/* Native scrolling with the platform scrollbars hidden; the overlay bars below replace them. */
+.viewport {
+  --fade-top: 0px; --fade-bottom: 0px; --fade-left: 0px; --fade-right: 0px;
+  min-width: 0;
+  min-height: 0;
+  flex: 1 1 auto;
+  overscroll-behavior-x: contain;
+  scrollbar-width: none;
+  -webkit-overflow-scrolling: touch;
+}
+.viewport::-webkit-scrollbar { display: none; }
+.root[data-orientation="vertical"] > .viewport { overflow-x: hidden; overflow-y: auto; }
+.root[data-orientation="horizontal"] > .viewport { overflow-x: auto; overflow-y: hidden; }
+.root[data-orientation="both"] > .viewport { overflow: auto; }
+
+/* Each fade is exactly as long as the content hidden past that edge, up to the fade size, so it grows in with the first pixels of scroll. */
+.viewport[data-fade="vertical"] {
+  -webkit-mask-image: linear-gradient(to bottom, transparent, #000 var(--fade-top), #000 calc(100% - var(--fade-bottom)), transparent);
+  mask-image: linear-gradient(to bottom, transparent, #000 var(--fade-top), #000 calc(100% - var(--fade-bottom)), transparent);
+}
+.viewport[data-fade="horizontal"] {
+  -webkit-mask-image: linear-gradient(to right, transparent, #000 var(--fade-left), #000 calc(100% - var(--fade-right)), transparent);
+  mask-image: linear-gradient(to right, transparent, #000 var(--fade-left), #000 calc(100% - var(--fade-right)), transparent);
+}
+.viewport[data-fade="both"] {
+  -webkit-mask-image: linear-gradient(to bottom, transparent, #000 var(--fade-top), #000 calc(100% - var(--fade-bottom)), transparent), linear-gradient(to right, transparent, #000 var(--fade-left), #000 calc(100% - var(--fade-right)), transparent);
+  -webkit-mask-composite: source-in;
+  mask-image: linear-gradient(to bottom, transparent, #000 var(--fade-top), #000 calc(100% - var(--fade-bottom)), transparent), linear-gradient(to right, transparent, #000 var(--fade-left), #000 calc(100% - var(--fade-right)), transparent);
+  mask-composite: intersect;
+}
+
+/* Overlay scrollbars: a generous hit area around a thin pill that thickens under the pointer. */
+.track {
+  position: absolute;
+  z-index: 1;
+  opacity: 0;
+  pointer-events: none;
+  touch-action: none;
+  transition: opacity var(--duration-considered) var(--ease-standard);
+}
+.track[data-axis="y"] { top: 3px; right: 1px; bottom: 3px; width: 11px; }
+.track[data-axis="x"] { right: 3px; bottom: 1px; left: 3px; height: 11px; }
+.root[data-orientation="both"] > .track[data-axis="y"] { bottom: 13px; }
+.root[data-orientation="both"] > .track[data-axis="x"] { right: 13px; }
+.track[data-hidden] { display: none; }
+
+.thumb { position: absolute; top: 0; left: 0; will-change: transform; }
+.track[data-axis="y"] .thumb { width: 100%; }
+.track[data-axis="x"] .thumb { height: 100%; }
+.thumb::after {
+  content: "";
+  position: absolute;
+  border-radius: var(--radius-full); corner-shape: round;
+  background: color-mix(in oklab, var(--foreground) 30%, transparent);
+  transition: width var(--duration-fast) var(--ease-standard), height var(--duration-fast) var(--ease-standard), background-color var(--duration-fast) var(--ease-standard);
+}
+.track[data-axis="y"] .thumb::after { top: 0; right: 3px; bottom: 0; width: 5px; }
+.track[data-axis="x"] .thumb::after { right: 0; bottom: 3px; left: 0; height: 5px; }
+
+/* Visible while scrolling, while the pointer is over the area, and always when asked. Appearing is quick; leaving lingers. */
+.root[data-scrolling] > .track,
+.root[data-dragging] > .track,
+.root[data-scrollbars="always"] > .track { opacity: 1; pointer-events: auto; transition-duration: var(--duration-fast); }
+
+@media (hover: hover) and (pointer: fine) {
+  .root:hover > .track { opacity: 1; pointer-events: auto; transition-duration: var(--duration-fast); }
+  .track:hover .thumb::after,
+  .root[data-dragging] .thumb::after { background: color-mix(in oklab, var(--foreground) 46%, transparent); }
+  .track[data-axis="y"]:hover .thumb::after,
+  .root[data-dragging="y"] .track[data-axis="y"] .thumb::after { width: 7px; right: 2px; }
+  .track[data-axis="x"]:hover .thumb::after,
+  .root[data-dragging="x"] .track[data-axis="x"] .thumb::after { height: 7px; bottom: 2px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .track, .thumb::after { transition: none; }
+}

package/components/search-field/search-field.d.ts

@@ -0,0 +1,7 @@
+import type { InputHTMLAttributes } from "react";
+export interface SearchFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type"> {
+    label: string;
+    value: string;
+    onValueChange: (value: string) => void;
+}
+export declare const SearchField: import("react").ForwardRefExoticComponent<SearchFieldProps & import("react").RefAttributes<HTMLInputElement>>;

package/components/search-field/search-field.js

@@ -0,0 +1,20 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId, useRef } from "react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { Search, X as Xmark } from "lucide-react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./search-field.module.css";
+export const SearchField = forwardRef(function SearchField({ label, value, onValueChange, id, className, ...props }, ref) {
+    const generated = useId();
+    const controlId = id ?? generated;
+    const reduced = useReducedMotion();
+    const inputRef = useRef(null);
+    const setRefs = (node) => { inputRef.current = node; if (typeof ref === "function")
+        ref(node);
+    else if (ref)
+        ref.current = node; };
+    // Clearing returns focus to the field, since the clear button unmounts under the pointer.
+    function clear() { onValueChange(""); inputRef.current?.focus(); }
+    return _jsxs("div", { className: styles.field, children: [_jsx("label", { htmlFor: controlId, children: label }), _jsxs("div", { className: styles.shell, "data-filled": value ? "true" : undefined, children: [_jsx(Search, { width: 18, height: 18, "aria-hidden": "true" }), _jsx("input", { ...props, ref: setRefs, id: controlId, type: "search", value: value, onChange: event => onValueChange(event.target.value), className: [styles.input, className].filter(Boolean).join(" ") }), _jsx("span", { className: styles.clearSlot, children: _jsx(AnimatePresence, { initial: false, children: value ? _jsx(motion.button, { type: "button", tabIndex: 0, onClick: clear, "aria-label": "Clear search", initial: reduced ? { opacity: 0 } : { opacity: 0, scale: .8, filter: `blur(${motionTokens.blur.subtle}px)` }, animate: { opacity: 1, scale: 1, filter: "blur(0px)" }, exit: reduced ? { opacity: 0, transition: { duration: 0 } } : { opacity: 0, scale: .8, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.instant, ease: [...motionTokens.ease.standard] } }, whileTap: reduced ? undefined : { scale: .96, transition: { duration: motionTokens.duration.instant, ease: [...motionTokens.ease.standard] } }, transition: reduced ? { duration: motionTokens.duration.instant } : { ...motionTokens.spring.snappy, opacity: { duration: motionTokens.duration.fast }, filter: { duration: motionTokens.duration.fast } }, children: _jsx(Xmark, { width: 16, height: 16, "aria-hidden": "true" }) }, "clear") : null }) })] })] });
+});

package/components/search-field/search-field.module.css

@@ -0,0 +1,17 @@
+.field { display: grid; gap: var(--space-related); min-width: 0; }
+.field label { font-size: var(--text-sm); font-weight: 500; line-height: var(--leading-body); letter-spacing: var(--tracking-body); }
+/* Focus darkens the border; the shell never changes size. */
+.shell { display: flex; min-height: var(--control-height-md); align-items: center; gap: var(--space-related); border: 1px solid var(--border-strong); border-radius: var(--radius-control); padding: 0 var(--space-group); background: var(--surface); transition: border-color var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .shell:hover:not(:focus-within) { border-color: var(--foreground); } }
+.shell:focus-within { border-color: var(--foreground); }
+/* The glass wakes up with the field: muted at rest, full contrast while searching. */
+.shell > svg { flex: 0 0 auto; color: var(--text-muted); transition: color var(--duration-fast) var(--ease-standard); }
+.shell:focus-within > svg, .shell[data-filled="true"] > svg { color: var(--foreground); }
+.input { width: 100%; min-width: 0; border: 0; background: transparent; color: var(--foreground); font: inherit; font-size: var(--text-sm); letter-spacing: var(--tracking-body); outline: 0; }
+.input:focus-visible { outline: 0; }
+.input::placeholder { color: var(--text-muted); }
+.input::-webkit-search-cancel-button { display: none; }
+.clearSlot { display: grid; width: 24px; height: 24px; flex: 0 0 auto; place-items: center; }
+.shell button { display: grid; width: 24px; height: 24px; flex: 0 0 auto; place-items: center; border: 0; border-radius: var(--radius-control); background: transparent; color: var(--text-muted); transition: background-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .shell button:hover { background: var(--surface-muted); color: var(--foreground); } }
+@media (prefers-reduced-motion: reduce) { .shell, .shell > svg, .shell button { transition: none; } }

package/components/segmented-control/segmented-control.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+export interface Segment {
+    value: string;
+    label: string; /** Optional content after the label, such as a badge. */
+    accessory?: ReactNode;
+}
+export interface SegmentedControlProps {
+    options: Segment[];
+    value: string;
+    onValueChange: (value: string) => void;
+    label?: string;
+    /** Called when the pointer or focus reaches an option, before it is chosen. Use it to start loading what that option shows. */
+    onOptionIntent?: (value: string) => void;
+    className?: string;
+}
+export default function SegmentedControl({ options, value, onValueChange, label, onOptionIntent, className }: SegmentedControlProps): import("react").JSX.Element;

package/components/segmented-control/segmented-control.js

@@ -0,0 +1,56 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useLayoutEffect, useRef } from "react";
+import { LayoutGroup, motion, useReducedMotion } from "motion/react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./segmented-control.module.css";
+export default function SegmentedControl({ options, value, onValueChange, label, onOptionIntent, className }) {
+    const id = useId();
+    const reduced = useReducedMotion();
+    const track = useRef(null);
+    // When the options are wider than the container, the track scrolls inside itself. Edges fade only on the side with more to see.
+    useLayoutEffect(() => {
+        const node = track.current;
+        if (!node)
+            return;
+        const edges = () => {
+            const rest = node.scrollWidth - node.clientWidth - node.scrollLeft;
+            node.toggleAttribute("data-fade-start", node.scrollLeft > 1);
+            node.toggleAttribute("data-fade-end", rest > 1);
+        };
+        edges();
+        node.addEventListener("scroll", edges, { passive: true });
+        const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(edges);
+        observer?.observe(node);
+        return () => { node.removeEventListener("scroll", edges); observer?.disconnect(); };
+    }, [options.length]);
+    // The selected option is always scrolled fully into view, with a little room so it clears the fade.
+    const first = useRef(true);
+    useEffect(() => {
+        const node = track.current;
+        const button = node?.querySelector('[aria-pressed="true"]');
+        if (!node || !button || node.scrollWidth <= node.clientWidth) {
+            first.current = false;
+            return;
+        }
+        const room = 20, start = button.offsetLeft - room, end = button.offsetLeft + button.offsetWidth + room - node.clientWidth;
+        const left = node.scrollLeft > start ? start : node.scrollLeft < end ? end : node.scrollLeft;
+        if (left !== node.scrollLeft)
+            node.scrollTo({ left: Math.max(0, left), behavior: first.current || reduced ? "auto" : "smooth" });
+        first.current = false;
+    }, [value, reduced]);
+    // Arrow keys, Home and End move the selection like a tab list; only the selected option is a tab stop.
+    const selectedIndex = Math.max(0, options.findIndex(option => option.value === value));
+    const onKeyDown = (event) => {
+        const last = options.length - 1;
+        const target = event.key === "ArrowRight" || event.key === "ArrowDown" ? (selectedIndex === last ? 0 : selectedIndex + 1)
+            : event.key === "ArrowLeft" || event.key === "ArrowUp" ? (selectedIndex === 0 ? last : selectedIndex - 1)
+                : event.key === "Home" ? 0 : event.key === "End" ? last : -1;
+        if (target < 0 || !options[target])
+            return;
+        event.preventDefault();
+        onValueChange(options[target].value);
+        track.current?.querySelector(`[data-value="${CSS.escape(options[target].value)}"]`)?.focus({ preventScroll: true });
+    };
+    return _jsx("div", { className: `${styles.root} ${className ?? ""}`, role: "group", "aria-label": label, children: _jsx(LayoutGroup, { id: id, children: _jsx(motion.div, { ref: track, layoutScroll: true, className: styles.track, children: options.map((option, index) => _jsxs("button", { id: `${id}-${option.value}`, className: styles.button, type: "button", "data-value": option.value, "aria-pressed": value === option.value, tabIndex: index === selectedIndex ? 0 : -1, onClick: () => onValueChange(option.value), onKeyDown: onKeyDown, onPointerEnter: onOptionIntent ? () => onOptionIntent(option.value) : undefined, onFocus: onOptionIntent ? () => onOptionIntent(option.value) : undefined, children: [value === option.value && _jsx(motion.span, { className: styles.selection, layoutId: "selection", layoutDependency: value, transition: reduced ? { duration: 0 } : motionTokens.spring.morph, "aria-hidden": "true" }), _jsxs("span", { className: styles.label, children: [option.label, option.accessory] })] }, option.value)) }) }) });
+}

package/components/segmented-control/segmented-control.module.css

@@ -0,0 +1,15 @@
+/* The frame can shrink below its content inside flex and grid parents; the track then scrolls inside it. */
+.root { display: inline-flex; min-width: 0; max-width: 100%; flex-shrink: 1; border: 1px solid var(--border); border-radius: var(--radius-control); background: var(--surface-muted); }
+/* The track owns the stacking context so the gliding highlight passes under every label, not over earlier ones. */
+.track { --fade-start: 0px; --fade-end: 0px; isolation: isolate; display: flex; min-width: 0; gap: 2px; overflow-x: auto; overscroll-behavior-x: contain; padding: 3px; border-radius: inherit; corner-shape: inherit; scrollbar-width: none; -webkit-mask-image: linear-gradient(to right, transparent, #000 var(--fade-start), #000 calc(100% - var(--fade-end)), transparent); mask-image: linear-gradient(to right, transparent, #000 var(--fade-start), #000 calc(100% - var(--fade-end)), transparent); }
+.track::-webkit-scrollbar { display: none; }
+.track[data-fade-start] { --fade-start: 20px; }
+.track[data-fade-end] { --fade-end: 20px; }
+/* Items never scale or change weight; only the highlight travels and the label color follows it. */
+.button { position: relative; flex: 0 0 auto; min-height: var(--control-height-sm); border: 0; border-radius: calc(var(--radius-control) - 4px); padding: 0 12px; background: transparent; color: var(--text-muted); font: inherit; font-size: var(--text-sm); font-weight: 500; white-space: nowrap; cursor: pointer; -webkit-tap-highlight-color: transparent; transition: color var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .button:hover { color: var(--foreground); } }
+.button:active, .button[aria-pressed="true"] { color: var(--foreground); }
+.selection { position: absolute; z-index: -1; inset: 0; border: 1px solid var(--border); border-radius: inherit; corner-shape: inherit; background: var(--surface); box-shadow: var(--shadow-resting); }
+.label { position: relative; z-index: 1; display: inline-flex; align-items: center; gap: 6px; }
+@media (max-width: 380px) { .button { padding: 0 10px; } }
+@media (prefers-reduced-motion: reduce) { .button { transition: none; } }

package/components/select/select.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentPropsWithoutRef } from "react";
+import * as SelectPrimitive from "@radix-ui/react-select";
+export interface SelectProps extends Omit<ComponentPropsWithoutRef<typeof SelectPrimitive.Root>, "children"> {
+    label: string;
+    description?: string;
+    placeholder?: string;
+    id?: string;
+    className?: string;
+    options: {
+        value: string;
+        label: string;
+        disabled?: boolean;
+    }[];
+}
+export declare const Select: import("react").ForwardRefExoticComponent<SelectProps & import("react").RefAttributes<HTMLButtonElement>>;

package/components/select/select.js

@@ -0,0 +1,36 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId, useState } from "react";
+import * as SelectPrimitive from "@radix-ui/react-select";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { Check, ChevronDown, ChevronUp } from "lucide-react";
+import { MenuHighlight, useMenuHighlight } from "../../lib/menu-highlight.js";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./select.module.css";
+/** The shown value rolls in the direction of the list: a later option rises from below, an earlier one drops from above. */
+const valueRoll = {
+    enter: (direction) => ({ opacity: 0, y: `${direction * 0.35}em`, filter: `blur(${motionTokens.blur.soft}px)` }),
+    center: { opacity: 1, y: 0, filter: "blur(0px)", transition: { duration: motionTokens.duration.standard, ease: [...motionTokens.ease.enter] } },
+    exit: (direction) => ({ opacity: 0, y: `${direction * -0.3}em`, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.standard] } }),
+};
+/** Reduced motion keeps a short crossfade; the resting state matches valueRoll so server and client markup agree. */
+const valueFade = { enter: { opacity: 0 }, center: { opacity: 1, y: 0, filter: "blur(0px)", transition: { duration: motionTokens.duration.instant } }, exit: { opacity: 0, transition: { duration: motionTokens.duration.instant } } };
+export const Select = forwardRef(function Select({ label, description, placeholder = "Select an option", options, id, className, disabled, onValueChange, ...rootProps }, ref) {
+    const generatedId = useId();
+    const controlId = id ?? generatedId;
+    const hintId = description ? `${controlId}-description` : undefined;
+    const reduceMotion = useReducedMotion();
+    const { highlight, reset, contentProps } = useMenuHighlight();
+    const [uncontrolledValue, setUncontrolledValue] = useState(rootProps.defaultValue ?? "");
+    const currentValue = rootProps.value ?? uncontrolledValue;
+    const index = options.findIndex((option) => option.value === currentValue);
+    const shown = currentValue ? options[index]?.label ?? "" : placeholder;
+    const [previousIndex, setPreviousIndex] = useState(index);
+    const [direction, setDirection] = useState(1);
+    if (previousIndex !== index) {
+        setPreviousIndex(index);
+        setDirection(index > previousIndex ? 1 : -1);
+    }
+    return (_jsxs("div", { className: styles.field, children: [_jsx("label", { htmlFor: controlId, children: label }), _jsxs(SelectPrimitive.Root, { ...rootProps, disabled: disabled, onOpenChange: (open) => { if (open)
+                    reset(); rootProps.onOpenChange?.(open); }, onValueChange: (next) => { setUncontrolledValue(next); onValueChange?.(next); }, children: [_jsxs(SelectPrimitive.Trigger, { ref: ref, id: controlId, "aria-describedby": hintId, className: [styles.trigger, className].filter(Boolean).join(" "), children: [_jsx("span", { className: styles.srOnly, children: _jsx(SelectPrimitive.Value, { placeholder: placeholder }) }), _jsx("span", { className: styles.valueText, "aria-hidden": "true", children: _jsx(AnimatePresence, { initial: false, custom: direction, children: _jsx(motion.span, { "data-placeholder": currentValue ? undefined : "", custom: direction, variants: reduceMotion ? valueFade : valueRoll, initial: "enter", animate: "center", exit: "exit", children: shown }, currentValue ? `value-${currentValue}` : "placeholder") }) }), _jsx(SelectPrimitive.Icon, { className: styles.chevron, children: _jsx(ChevronDown, { size: 16, strokeWidth: 1.75, "aria-hidden": "true" }) })] }), _jsx(SelectPrimitive.Portal, { children: _jsxs(SelectPrimitive.Content, { className: styles.content, position: "popper", sideOffset: 4, collisionPadding: 12, ...contentProps, children: [_jsx(SelectPrimitive.ScrollUpButton, { className: styles.scrollButton, children: _jsx(ChevronUp, { size: 16, strokeWidth: 1.75, "aria-hidden": "true" }) }), _jsxs(SelectPrimitive.Viewport, { className: styles.viewport, children: [_jsx(MenuHighlight, { state: highlight, className: styles.highlight }), options.map((option) => (_jsxs(SelectPrimitive.Item, { value: option.value, disabled: option.disabled, className: styles.item, children: [_jsx(SelectPrimitive.ItemText, { children: option.label }), _jsx(SelectPrimitive.ItemIndicator, { className: styles.indicator, children: _jsx(Check, { size: 16, strokeWidth: 1.75, "aria-hidden": "true" }) })] }, option.value)))] }), _jsx(SelectPrimitive.ScrollDownButton, { className: styles.scrollButton, children: _jsx(ChevronDown, { size: 16, strokeWidth: 1.75, "aria-hidden": "true" }) })] }) })] }), description && _jsx("span", { id: hintId, className: styles.hint, children: description })] }));
+});

package/components/select/select.module.css

@@ -0,0 +1,35 @@
+.field { display: grid; gap: var(--space-related); min-width: 0; }
+.field label { font-size: var(--text-sm); font-weight: 500; }
+/* The trigger anchors the floating menu. Radix opens on pointerdown and measures this box, so it never scales: press feedback is color only. */
+.trigger { position: relative; box-sizing: border-box; display: flex; align-items: center; justify-content: space-between; gap: var(--space-group); width: 100%; min-height: var(--control-height-md); border: 1px solid var(--border); border-radius: var(--radius-control); padding: 0 var(--space-group); background: var(--surface); color: var(--foreground); font: inherit; font-size: var(--text-sm); text-align: left; cursor: pointer; transition: border-color var(--duration-fast) var(--ease-standard), background-color var(--duration-fast) var(--ease-standard), box-shadow var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .trigger:hover:not([data-disabled]) { border-color: var(--border-strong); background: var(--surface-muted); } }
+.trigger:active:not([data-disabled]), .trigger[data-state="open"] { border-color: var(--border-strong); background: var(--surface-muted); }
+.trigger:focus-visible { border-color: var(--border-strong); }
+.trigger[data-disabled] { opacity: .5; cursor: not-allowed; }
+.valueText { display: grid; flex: 1; min-width: 0; grid-template-columns: minmax(0, 1fr); }
+.valueText > span { grid-area: 1 / 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.valueText > [data-placeholder] { color: var(--text-muted); }
+.srOnly { position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
+.chevron { display: inline-flex; flex: 0 0 auto; color: var(--text-muted); transition: transform var(--duration-spring) var(--ease-spring), color var(--duration-fast) var(--ease-standard); }
+.trigger[data-state="open"] .chevron { transform: rotate(180deg); }
+.hint { color: var(--text-muted); font-size: var(--text-xs); }
+/* Radix holds the animation until the menu is positioned, so it always grows from the trigger edge. */
+.content { --menu-x: 0px; --menu-y: -6px; box-sizing: border-box; z-index: 1000; width: var(--radix-select-trigger-width); min-width: var(--radix-select-trigger-width); max-width: min(24rem, calc(100vw - 20px)); max-height: min(320px, var(--radix-select-content-available-height)); overflow: hidden; border: 1px solid var(--border); border-radius: calc(var(--radius-control) + 2px); padding: 6px; background: var(--surface-raised); color: var(--foreground); box-shadow: var(--shadow-floating); transform-origin: var(--radix-select-content-transform-origin); animation: select-in var(--duration-standard) var(--ease-enter) both; }
+.content[data-side="top"] { --menu-y: 6px; }
+.content[data-side="left"] { --menu-x: 6px; --menu-y: 0px; }
+.content[data-side="right"] { --menu-x: -6px; --menu-y: 0px; }
+.content[data-state="closed"] { animation: select-out var(--duration-instant) var(--ease-standard) both; }
+.viewport { position: relative; padding: 2px 0; }
+/* One highlight glides between options for the pointer and jumps instantly for the keyboard (lib/menu-highlight). */
+.highlight { position: absolute; top: 0; right: 0; left: 0; border-radius: calc(var(--radius-control) - 4px); background: var(--surface-muted); opacity: 0; pointer-events: none; }
+.item { position: relative; display: flex; align-items: center; min-height: 36px; border-radius: calc(var(--radius-control) - 4px); padding: 0 34px 0 11px; color: var(--foreground); font-size: var(--text-sm); cursor: default; outline: none; user-select: none; transition: background-color var(--duration-instant) var(--ease-standard), color var(--duration-instant) var(--ease-standard); }
+.item[data-disabled] { opacity: .45; }
+.indicator { position: absolute; right: 10px; display: inline-flex; align-items: center; color: var(--foreground); animation: indicator-in var(--duration-standard) var(--ease-enter) 40ms both; }
+.scrollButton { display: grid; height: 28px; place-items: center; color: var(--text-muted); }
+@keyframes select-in { from { opacity: 0; transform: translate(var(--menu-x), var(--menu-y)) scale(.97); } }
+@keyframes select-out { to { opacity: 0; transform: translate(calc(var(--menu-x) / 2), calc(var(--menu-y) / 2)) scale(.98); } }
+@keyframes indicator-in { from { opacity: 0; transform: scale(.6); filter: blur(2px); } }
+@media (prefers-reduced-transparency: reduce) { .content { background: var(--surface-raised); backdrop-filter: none; -webkit-backdrop-filter: none; } }
+@media (prefers-reduced-motion: reduce) { .trigger, .chevron, .item { transition: none; } .content { animation: select-fade var(--duration-instant) var(--ease-standard) both; } .content[data-state="closed"] { animation: select-fade-out var(--duration-instant) var(--ease-standard) both; } .indicator { animation: none; } }
+@keyframes select-fade { from { opacity: 0; } }
+@keyframes select-fade-out { to { opacity: 0; } }

package/components/shortcut-recorder/shortcut-recorder.d.ts

@@ -0,0 +1,108 @@
+import type { HTMLAttributes, ReactNode } from "react";
+export type Platform = "mac" | "other";
+export interface ShortcutToken {
+    label: string; /** Physical key id, matched against held keys. */
+    id: string;
+    spoken: string;
+}
+/** The physical key id for an event: "k", "1", "enter", "meta", "shift"… `null` for keys that never make a shortcut, such as Caps Lock. */
+export declare function keyId(event: Pick<KeyboardEvent, "key" | "code">): string | null;
+/** One spelling per combination: on a Mac, Command is `mod`; elsewhere, Ctrl is. Modifiers come in a fixed order. */
+export declare function normalizeShortcut(shortcut: string, platform: Platform): string;
+/** Reads a keydown into a shortcut string, or `null` while only modifiers are down. */
+export declare function shortcutFromEvent(event: Pick<KeyboardEvent, "key" | "code" | "metaKey" | "ctrlKey" | "altKey" | "shiftKey">, platform: Platform): string | null;
+/** True when a keydown is this shortcut. Use it to run the action a recorded shortcut is bound to. */
+export declare function matchesShortcut(event: Pick<KeyboardEvent, "key" | "code" | "metaKey" | "ctrlKey" | "altKey" | "shiftKey">, shortcut: string, platform: Platform): boolean;
+/** Key caps for a shortcut in platform order: ⌃ ⌥ ⇧ ⌘ on a Mac, Ctrl Alt Shift Win elsewhere. */
+export declare function shortcutTokens(shortcut: string, platform: Platform): ShortcutToken[];
+/** "⌘⇧K" on a Mac, "Ctrl+Shift+K" elsewhere, plus a spoken form for assistive technology. */
+export declare function formatShortcut(shortcut: string, platform: Platform): {
+    text: string;
+    spoken: string;
+};
+/** The viewer's platform. Server renders assume a Mac and settle on the first client render. */
+export declare function usePlatform(override?: Platform): Platform;
+/** Keys held down right now, by physical id. Clears on window blur, and after Command lifts (macOS drops the other keyups). */
+export declare function usePressedKeys(enabled?: boolean): ReadonlySet<string>;
+export interface ShortcutKbdProps extends HTMLAttributes<HTMLElement> {
+    children: ReactNode;
+    /** Draws the key pushed down and lit, such as while it is held. */
+    pressed?: boolean;
+    size?: "sm" | "md";
+}
+/** A key cap. Use it inline in copy, in menus, or through `ShortcutKeys` for a whole combination. */
+export declare const ShortcutKbd: import("react").ForwardRefExoticComponent<ShortcutKbdProps & import("react").RefAttributes<HTMLElement>>;
+/** @deprecated Renamed to `ShortcutKbd` so it never clashes with the `kbd` component's `Kbd` in a shared index.ts. */
+export declare const Kbd: import("react").ForwardRefExoticComponent<ShortcutKbdProps & import("react").RefAttributes<HTMLElement>>;
+/** @deprecated Renamed to `ShortcutKbdProps`. */
+export type KbdProps = ShortcutKbdProps;
+export interface ShortcutKeysProps {
+    shortcut: string;
+    platform?: Platform;
+    /** Held key ids from `usePressedKeys`; matching caps light up. */
+    pressed?: ReadonlySet<string>;
+    size?: "sm" | "md";
+    className?: string;
+}
+/** A shortcut as key caps, with a spoken label for assistive technology. */
+export declare function ShortcutKeys({ shortcut, platform: platformProp, pressed, size, className }: ShortcutKeysProps): import("react").JSX.Element;
+export interface ShortcutBinding {
+    shortcut: string;
+    label: string;
+}
+export interface ShortcutRecorderProps {
+    label: string;
+    hideLabel?: boolean;
+    value?: string | null;
+    defaultValue?: string | null;
+    /** `replaced` is the binding the new shortcut was taken from after "Use anyway", so the caller can unbind it. */
+    onValueChange?: (value: string | null, details: {
+        replaced?: ShortcutBinding;
+    }) => void;
+    /** What the reset button restores. Defaults to `defaultValue`. */
+    resetValue?: string | null;
+    /** Shortcuts already in use. Recording one of them asks before taking it. */
+    bindings?: ShortcutBinding[];
+    /** Also warn about combinations the browser or system keeps, such as ⌘W and ⌘C. On by default. */
+    warnReserved?: boolean;
+    /** Require ⌘, Ctrl, or ⌥ (function keys are always allowed). On by default. */
+    requireModifier?: boolean;
+    platform?: Platform;
+    placeholder?: string;
+    description?: string;
+    disabled?: boolean;
+    id?: string;
+    className?: string;
+}
+/**
+ * A field that records a keyboard shortcut. Press it, then press the combination: held modifiers light up as caps while you
+ * build the chord, the finished shortcut settles into place, and a combination that is already taken asks before it is used.
+ * Escape cancels, Backspace clears, and the reset button restores the default. Caps follow the platform: ⌘ on a Mac, Ctrl elsewhere.
+ */
+export declare function ShortcutRecorder({ label, hideLabel, value, defaultValue, onValueChange, resetValue, bindings, warnReserved, requireModifier, platform: platformProp, placeholder, description, disabled, id, className, }: ShortcutRecorderProps): import("react").JSX.Element;
+export interface ShortcutListItem {
+    label: string;
+    shortcut: string; /** Extra words that match when searching. */
+    keywords?: string;
+}
+export interface ShortcutListGroup {
+    label: string;
+    items: ShortcutListItem[];
+}
+export interface ShortcutListProps {
+    groups: ShortcutListGroup[];
+    /** Accessible name of the list. */
+    label?: string;
+    searchable?: boolean;
+    searchPlaceholder?: string;
+    /** Light up caps as keys are held, and fade rows that do not use the held modifiers. On by default. */
+    highlightPressed?: boolean;
+    platform?: Platform;
+    className?: string;
+}
+/**
+ * A searchable, grouped cheatsheet. Holding a modifier lights that cap in every row and fades rows that do not use it, so people
+ * can explore by holding keys; a row whose whole combination is down lights up. Search matches names, groups, and key names such as "cmd k".
+ */
+export declare function ShortcutList({ groups, label, searchable, searchPlaceholder, highlightPressed, platform: platformProp, className }: ShortcutListProps): import("react").JSX.Element;
+export default ShortcutRecorder;