@teamofsilicons/silicon-ui 0.0.0-stage → 0.2.0

package/components/shortcut-recorder/shortcut-recorder.js

@@ -0,0 +1,380 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { RotateCcw, Search, X } from "lucide-react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./shortcut-recorder.module.css";
+const MODIFIER_ORDER = ["mod", "ctrl", "alt", "shift", "meta"];
+const isModifier = (part) => MODIFIER_ORDER.includes(part);
+const CODE_KEYS = {
+    Comma: ",", Period: ".", Slash: "/", Semicolon: ";", Quote: "'", BracketLeft: "[", BracketRight: "]", Backslash: "\\", Minus: "-", Equal: "=", Backquote: "`",
+    Space: "space", Enter: "enter", NumpadEnter: "enter", Escape: "escape", Backspace: "backspace", Delete: "delete", Tab: "tab",
+    ArrowUp: "up", ArrowDown: "down", ArrowLeft: "left", ArrowRight: "right", Home: "home", End: "end", PageUp: "pageup", PageDown: "pagedown",
+};
+const MODIFIER_KEYS = { Meta: "meta", OS: "meta", Control: "ctrl", Alt: "alt", AltGraph: "alt", Shift: "shift" };
+/** 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 function keyId(event) {
+    const { code, key } = event;
+    if (MODIFIER_KEYS[key])
+        return MODIFIER_KEYS[key];
+    if (/^Key[A-Z]$/.test(code))
+        return code.slice(3).toLowerCase();
+    if (/^Digit\d$/.test(code))
+        return code.slice(5);
+    if (/^Numpad\d$/.test(code))
+        return code.slice(6);
+    if (CODE_KEYS[code])
+        return CODE_KEYS[code];
+    if (/^F\d{1,2}$/.test(key))
+        return key.toLowerCase();
+    if (key === "CapsLock" || key === "Fn" || key === "Dead" || key === "Unidentified" || key === "Process")
+        return null;
+    return key.length === 1 ? key.toLowerCase() : null;
+}
+function splitShortcut(shortcut) {
+    const parts = shortcut.toLowerCase().split("+").map(part => part.trim()).filter(Boolean);
+    const key = parts.filter(part => !isModifier(part)).pop() ?? "";
+    return { mods: new Set(parts.filter(isModifier)), key };
+}
+/** One spelling per combination: on a Mac, Command is `mod`; elsewhere, Ctrl is. Modifiers come in a fixed order. */
+export function normalizeShortcut(shortcut, platform) {
+    const { mods, key } = splitShortcut(shortcut);
+    if (platform === "mac" && mods.delete("meta"))
+        mods.add("mod");
+    if (platform === "other" && mods.delete("ctrl"))
+        mods.add("mod");
+    return [...MODIFIER_ORDER.filter(mod => mods.has(mod)), key].filter(Boolean).join("+");
+}
+/** Reads a keydown into a shortcut string, or `null` while only modifiers are down. */
+export function shortcutFromEvent(event, platform) {
+    const key = keyId(event);
+    if (!key || ["meta", "ctrl", "alt", "shift"].includes(key))
+        return null;
+    const mods = [];
+    if (platform === "mac" ? event.metaKey : event.ctrlKey)
+        mods.push("mod");
+    if (platform === "mac" ? event.ctrlKey : false)
+        mods.push("ctrl");
+    if (event.altKey)
+        mods.push("alt");
+    if (event.shiftKey)
+        mods.push("shift");
+    if (platform === "other" && event.metaKey)
+        mods.push("meta");
+    return normalizeShortcut([...mods, key].join("+"), platform);
+}
+/** True when a keydown is this shortcut. Use it to run the action a recorded shortcut is bound to. */
+export function matchesShortcut(event, shortcut, platform) {
+    const pressed = shortcutFromEvent(event, platform);
+    return !!pressed && pressed === normalizeShortcut(shortcut, platform);
+}
+const MAC_KEYS = { enter: ["↩", "Return"], backspace: ["⌫", "Delete"], delete: ["⌦", "Forward delete"], tab: ["⇥", "Tab"], escape: ["esc", "Escape"] };
+const SHARED_KEYS = {
+    space: ["Space", "Space"], enter: ["Enter", "Enter"], escape: ["Esc", "Escape"], backspace: ["Backspace", "Backspace"], delete: ["Del", "Delete"], tab: ["Tab", "Tab"],
+    up: ["↑", "Up arrow"], down: ["↓", "Down arrow"], left: ["←", "Left arrow"], right: ["→", "Right arrow"], home: ["Home", "Home"], end: ["End", "End"], pageup: ["PgUp", "Page up"], pagedown: ["PgDn", "Page down"],
+    ",": [",", "Comma"], ".": [".", "Period"], "/": ["/", "Slash"], ";": [";", "Semicolon"], "'": ["'", "Quote"], "[": ["[", "Left bracket"], "]": ["]", "Right bracket"], "\\": ["\\", "Backslash"], "-": ["-", "Minus"], "=": ["=", "Equals"], "`": ["`", "Backtick"],
+};
+/** Key caps for a shortcut in platform order: ⌃ ⌥ ⇧ ⌘ on a Mac, Ctrl Alt Shift Win elsewhere. */
+export function shortcutTokens(shortcut, platform) {
+    const { mods, key } = splitShortcut(normalizeShortcut(shortcut, platform));
+    const tokens = [];
+    if (platform === "mac") {
+        if (mods.has("ctrl"))
+            tokens.push({ label: "⌃", id: "ctrl", spoken: "Control" });
+        if (mods.has("alt"))
+            tokens.push({ label: "⌥", id: "alt", spoken: "Option" });
+        if (mods.has("shift"))
+            tokens.push({ label: "⇧", id: "shift", spoken: "Shift" });
+        if (mods.has("mod") || mods.has("meta"))
+            tokens.push({ label: "⌘", id: "meta", spoken: "Command" });
+    }
+    else {
+        if (mods.has("mod") || mods.has("ctrl"))
+            tokens.push({ label: "Ctrl", id: "ctrl", spoken: "Control" });
+        if (mods.has("alt"))
+            tokens.push({ label: "Alt", id: "alt", spoken: "Alt" });
+        if (mods.has("shift"))
+            tokens.push({ label: "Shift", id: "shift", spoken: "Shift" });
+        if (mods.has("meta"))
+            tokens.push({ label: "Win", id: "meta", spoken: "Windows" });
+    }
+    if (key) {
+        const named = (platform === "mac" ? MAC_KEYS[key] : undefined) ?? SHARED_KEYS[key];
+        tokens.push(named ? { label: named[0], id: key, spoken: named[1] } : { label: key.toUpperCase(), id: key, spoken: key.toUpperCase() });
+    }
+    return tokens;
+}
+/** "⌘⇧K" on a Mac, "Ctrl+Shift+K" elsewhere, plus a spoken form for assistive technology. */
+export function formatShortcut(shortcut, platform) {
+    const tokens = shortcutTokens(shortcut, platform);
+    return { text: tokens.map(token => token.label).join(platform === "mac" ? "" : "+"), spoken: tokens.map(token => token.spoken).join(" ") };
+}
+const subscribe = () => () => { };
+/** Reduced motion that only applies after hydration, so server and client render the same styles. */
+function useReducedFlag() {
+    const hydrated = useSyncExternalStore(subscribe, () => true, () => false);
+    return !!useReducedMotion() && hydrated;
+}
+const detectPlatform = () => {
+    if (typeof navigator === "undefined")
+        return "mac";
+    const hint = navigator.userAgentData?.platform ?? navigator.platform ?? navigator.userAgent;
+    return /mac|iphone|ipad|ipod/i.test(hint) ? "mac" : "other";
+};
+/** The viewer's platform. Server renders assume a Mac and settle on the first client render. */
+export function usePlatform(override) {
+    const detected = useSyncExternalStore(subscribe, detectPlatform, () => "mac");
+    return override ?? detected;
+}
+/** Keys held down right now, by physical id. Clears on window blur, and after Command lifts (macOS drops the other keyups). */
+export function usePressedKeys(enabled = true) {
+    const [held, setHeld] = useState(() => new Set());
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const update = (change) => setHeld(current => { const next = new Set(current); change(next); return next.size === current.size && [...next].every(key => current.has(key)) ? current : next; });
+        const down = (event) => { const id = keyId(event); if (id)
+            update(next => next.add(id)); };
+        const up = (event) => {
+            const id = keyId(event);
+            update(next => {
+                if (id)
+                    next.delete(id);
+                if (id === "meta")
+                    [...next].forEach(key => { if (!["ctrl", "alt", "shift"].includes(key))
+                        next.delete(key); });
+                if (!event.metaKey)
+                    next.delete("meta");
+                if (!event.ctrlKey)
+                    next.delete("ctrl");
+                if (!event.altKey)
+                    next.delete("alt");
+                if (!event.shiftKey)
+                    next.delete("shift");
+            });
+        };
+        const clear = () => setHeld(current => current.size ? new Set() : current);
+        // Capture phase, so keys still register while a focused recorder keeps the chord from bubbling.
+        window.addEventListener("keydown", down, true);
+        window.addEventListener("keyup", up, true);
+        window.addEventListener("blur", clear);
+        document.addEventListener("visibilitychange", clear);
+        return () => { window.removeEventListener("keydown", down, true); window.removeEventListener("keyup", up, true); window.removeEventListener("blur", clear); document.removeEventListener("visibilitychange", clear); };
+    }, [enabled]);
+    return enabled ? held : EMPTY;
+}
+const EMPTY = new Set();
+/** A key cap. Use it inline in copy, in menus, or through `ShortcutKeys` for a whole combination. */
+export const ShortcutKbd = forwardRef(function ShortcutKbd({ children, pressed = false, size = "md", className, ...props }, ref) {
+    return _jsx("kbd", { ref: ref, ...props, className: [styles.kbd, className].filter(Boolean).join(" "), "data-size": size, "data-pressed": pressed || undefined, children: children });
+});
+ShortcutKbd.displayName = "ShortcutKbd";
+/** @deprecated Renamed to `ShortcutKbd` so it never clashes with the `kbd` component's `Kbd` in a shared index.ts. */
+export const Kbd = ShortcutKbd;
+/** A shortcut as key caps, with a spoken label for assistive technology. */
+export function ShortcutKeys({ shortcut, platform: platformProp, pressed, size = "md", className }) {
+    const platform = usePlatform(platformProp);
+    const tokens = shortcutTokens(shortcut, platform);
+    return _jsx("span", { className: [styles.keys, className].filter(Boolean).join(" "), role: "img", "aria-label": tokens.map(token => token.spoken).join(" "), children: tokens.map((token, index) => _jsx(ShortcutKbd, { size: size, pressed: pressed?.has(token.id), "aria-hidden": "true", children: token.label }, `${index}-${token.id}`)) });
+}
+const RESERVED = [
+    { shortcut: "mod+w", label: "Close tab" }, { shortcut: "mod+t", label: "New tab" }, { shortcut: "mod+n", label: "New window" }, { shortcut: "mod+q", label: "Quit" },
+    { shortcut: "mod+l", label: "Address bar" }, { shortcut: "mod+r", label: "Reload" }, { shortcut: "mod+shift+t", label: "Reopen tab" },
+    { shortcut: "mod+c", label: "Copy" }, { shortcut: "mod+v", label: "Paste" }, { shortcut: "mod+x", label: "Cut" }, { shortcut: "mod+z", label: "Undo" }, { shortcut: "mod+a", label: "Select all" },
+];
+const chip = {
+    enter: { opacity: 0, scale: .72, y: 4, filter: `blur(${motionTokens.blur.subtle}px)` },
+    rest: (index) => ({ opacity: 1, scale: 1, y: 0, filter: "blur(0px)", transition: { ...motionTokens.spring.snappy, delay: index * motionTokens.stagger.item, opacity: { duration: .14, delay: index * motionTokens.stagger.item }, filter: { duration: .16, delay: index * motionTokens.stagger.item } } }),
+    exit: { opacity: 0, scale: .8, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: .1 } },
+};
+const chipFade = { enter: { opacity: 0 }, rest: { opacity: 1, scale: 1, y: 0, filter: "none", transition: { duration: .1 } }, exit: { opacity: 0, transition: { duration: .06 } } };
+/**
+ * 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 function ShortcutRecorder({ label, hideLabel = false, value, defaultValue = null, onValueChange, resetValue, bindings = [], warnReserved = true, requireModifier = true, platform: platformProp, placeholder = "Record shortcut", description, disabled = false, id, className, }) {
+    const reduced = useReducedFlag();
+    const platform = usePlatform(platformProp);
+    const uid = useId();
+    const buttonId = id ?? `${uid}-button`;
+    const labelId = `${uid}-label`, messageId = `${uid}-message`;
+    const [inner, setInner] = useState(defaultValue);
+    const current = value !== undefined ? value : inner;
+    const restoreTo = resetValue !== undefined ? resetValue : defaultValue;
+    const [recording, setRecording] = useState(false);
+    const [live, setLive] = useState([]);
+    const [pending, setPending] = useState(null);
+    const [nudge, setNudge] = useState(null);
+    const [settled, setSettled] = useState(0);
+    const [announcement, setAnnouncement] = useState("");
+    const buttonRef = useRef(null);
+    /* The message slot animates to the measured height of its content, so a swap to a message that wraps grows instead of snapping. */
+    const [messageHeight, setMessageHeight] = useState(null);
+    const measureMessage = useCallback((node) => {
+        if (!node)
+            return;
+        const observer = new ResizeObserver(() => setMessageHeight(node.getBoundingClientRect().height));
+        observer.observe(node);
+        return () => { observer.disconnect(); setMessageHeight(null); };
+    }, []);
+    const spoken = (shortcut) => shortcut ? formatShortcut(shortcut, platform).spoken : "none";
+    const commit = useCallback((next, replaced) => {
+        setPending(null);
+        setNudge(null);
+        if (value === undefined)
+            setInner(next);
+        onValueChange?.(next, { replaced });
+        setSettled(count => count + 1);
+        setAnnouncement(next ? `Shortcut set to ${formatShortcut(next, platform).spoken}` : "Shortcut cleared");
+    }, [onValueChange, platform, value]);
+    const start = () => {
+        if (disabled)
+            return;
+        setPending(null);
+        setNudge(null);
+        setLive([]);
+        setRecording(true);
+        setAnnouncement("Recording. Press the new shortcut, or Escape to cancel.");
+    };
+    const stop = () => { setRecording(false); setLive([]); };
+    const conflictFor = (shortcut) => {
+        const normal = normalizeShortcut(shortcut, platform);
+        if (current && normalizeShortcut(current, platform) === normal)
+            return null;
+        const taken = bindings.find(binding => normalizeShortcut(binding.shortcut, platform) === normal);
+        if (taken)
+            return { shortcut, conflict: taken, reserved: false };
+        const reserved = warnReserved ? RESERVED.find(binding => normalizeShortcut(binding.shortcut, platform) === normal) : undefined;
+        return reserved ? { shortcut, conflict: reserved, reserved: true } : null;
+    };
+    const liveMods = (event) => {
+        const mods = [];
+        if (event.ctrlKey && platform === "mac")
+            mods.push("ctrl");
+        if (event.altKey)
+            mods.push("alt");
+        if (event.shiftKey)
+            mods.push("shift");
+        if (platform === "mac" ? event.metaKey : event.ctrlKey)
+            mods.push("mod");
+        if (platform === "other" && event.metaKey)
+            mods.push("meta");
+        return mods;
+    };
+    function onKeyDown(event) {
+        if (!recording) {
+            if ((event.key === "Backspace" || event.key === "Delete") && current) {
+                event.preventDefault();
+                commit(null);
+            }
+            return;
+        }
+        if (event.key === "Tab" && !event.shiftKey && !event.metaKey && !event.ctrlKey && !event.altKey) {
+            stop();
+            return;
+        }
+        // The chord belongs to the recorder: keep it from the page's own shortcuts, such as a ⌘K command menu.
+        event.preventDefault();
+        event.stopPropagation();
+        const bare = !event.metaKey && !event.ctrlKey && !event.altKey && !event.shiftKey;
+        if (bare && event.key === "Escape") {
+            stop();
+            setAnnouncement("Recording canceled");
+            return;
+        }
+        if (bare && (event.key === "Backspace" || event.key === "Delete")) {
+            stop();
+            commit(null);
+            return;
+        }
+        const shortcut = shortcutFromEvent(event.nativeEvent, platform);
+        if (!shortcut) {
+            setLive(liveMods(event));
+            return;
+        }
+        const { mods, key } = splitShortcut(shortcut);
+        const strong = mods.has("mod") || mods.has("ctrl") || mods.has("alt") || mods.has("meta");
+        if (requireModifier && !strong && !/^f\d+$/.test(key)) {
+            const hint = platform === "mac" ? "Include ⌘, ⌃, or ⌥" : "Include Ctrl or Alt";
+            setNudge(hint);
+            setAnnouncement(hint);
+            setLive(liveMods(event));
+            return;
+        }
+        stop();
+        const conflict = conflictFor(shortcut);
+        if (conflict) {
+            setPending(conflict);
+            setAnnouncement(`${formatShortcut(shortcut, platform).spoken} is ${conflict.reserved ? "reserved for" : "used by"} ${conflict.conflict.label}. Use anyway, or record another.`);
+            return;
+        }
+        commit(shortcut);
+    }
+    function onKeyUp(event) { if (recording)
+        setLive(liveMods(event)); }
+    const shown = pending?.shortcut ?? current;
+    const tokens = recording ? shortcutTokens(live.join("+"), platform) : shown ? shortcutTokens(shown, platform) : [];
+    const state = recording ? "recording" : pending ? "conflict" : "idle";
+    const canReset = !recording && (pending !== null || (current ?? null) !== (restoreTo ?? null));
+    const canClear = !recording && !!current && !pending;
+    const message = pending
+        ? { tone: "warning", key: `c-${pending.shortcut}`, body: _jsxs(_Fragment, { children: [pending.reserved ? "Reserved for" : "Already used by", " ", _jsx("strong", { className: styles.strong, children: pending.conflict.label })] }) }
+        : nudge ? { tone: "hint", key: `n-${nudge}`, body: _jsx(_Fragment, { children: nudge }) }
+            : recording ? { tone: "hint", key: "rec", body: _jsx(_Fragment, { children: "Esc to cancel, Backspace to clear" }) }
+                : description ? { tone: "hint", key: "d", body: _jsx(_Fragment, { children: description }) } : null;
+    useEffect(() => {
+        if (!settled)
+            return;
+        const timer = window.setTimeout(() => setSettled(0), 700);
+        return () => window.clearTimeout(timer);
+    }, [settled]);
+    return _jsxs("div", { className: [styles.field, className].filter(Boolean).join(" "), "data-disabled": disabled || undefined, children: [_jsx("span", { id: labelId, className: hideLabel ? styles.srOnly : styles.label, children: label }), _jsxs("div", { className: styles.control, "data-state": state, children: [_jsxs("button", { ref: buttonRef, id: buttonId, type: "button", className: styles.recorder, disabled: disabled, "aria-labelledby": `${labelId} ${buttonId}`, "aria-describedby": message ? messageId : undefined, "aria-pressed": recording, onClick: event => { if (recording) {
+                            if (event.detail !== 0) {
+                                stop();
+                                setAnnouncement("Recording canceled");
+                            }
+                            return;
+                        } start(); }, onKeyDown: onKeyDown, onKeyUp: onKeyUp, onBlur: () => { if (recording) {
+                            stop();
+                            setNudge(null);
+                        } }, children: [_jsx("span", { className: styles.srOnly, children: recording ? "Recording" : shown ? spoken(shown) : placeholder }), _jsxs("span", { className: styles.row, "aria-hidden": "true", children: [recording && _jsx("span", { className: styles.dot, "data-reduced": reduced || undefined }), _jsxs(AnimatePresence, { initial: false, mode: "popLayout", children: [tokens.map((token, index) => _jsx(motion.span, { layout: reduced ? false : "position", custom: recording ? 0 : index, variants: reduced ? chipFade : chip, initial: "enter", animate: "rest", exit: "exit", transition: reduced ? { duration: 0 } : { layout: motionTokens.spring.snappy }, className: styles.chipSlot, children: _jsx(ShortcutKbd, { pressed: recording || (settled > 0 && !pending), "data-tone": pending ? "warning" : undefined, children: token.label }) }, `${token.id}`)), tokens.length === 0 && _jsx(motion.span, { className: styles.placeholder, "data-recording": recording || undefined, initial: reduced ? { opacity: 0 } : { opacity: 0, y: 4, filter: `blur(${motionTokens.blur.subtle}px)` }, animate: { opacity: 1, y: 0, filter: "blur(0px)" }, exit: { opacity: 0, transition: { duration: .08 } }, transition: reduced ? { duration: .1 } : { duration: motionTokens.duration.fast, ease: [...motionTokens.ease.enter] }, children: recording ? "Press keys" : placeholder }, recording ? "prompt" : "placeholder")] })] })] }), _jsx("span", { className: styles.actions, children: _jsxs(AnimatePresence, { initial: false, children: [canReset && _jsx(motion.button, { type: "button", className: styles.action, "aria-label": `Reset to ${restoreTo ? formatShortcut(restoreTo, platform).spoken : "none"}`, onClick: () => { commit(restoreTo ?? null); buttonRef.current?.focus(); }, initial: { opacity: 0, scale: .6 }, animate: { opacity: 1, scale: 1 }, exit: { opacity: 0, scale: .6, transition: { duration: .1 } }, transition: reduced ? { duration: 0 } : motionTokens.spring.snappy, children: _jsx(RotateCcw, { size: 16, strokeWidth: 1.75, "aria-hidden": "true" }) }, "reset"), canClear && _jsx(motion.button, { type: "button", className: styles.action, "aria-label": "Clear shortcut", onClick: () => { commit(null); buttonRef.current?.focus(); }, initial: { opacity: 0, scale: .6 }, animate: { opacity: 1, scale: 1 }, exit: { opacity: 0, scale: .6, transition: { duration: .1 } }, transition: reduced ? { duration: 0 } : motionTokens.spring.snappy, children: _jsx(X, { size: 16, strokeWidth: 1.75, "aria-hidden": "true" }) }, "clear")] }) })] }), _jsx(AnimatePresence, { initial: false, children: message && _jsx(motion.div, { className: styles.messageSlot, initial: reduced ? false : { height: 0, opacity: 0 }, animate: { height: messageHeight ?? "auto", opacity: 1 }, exit: { height: 0, opacity: 0, transition: reduced ? { duration: 0 } : { height: motionTokens.spring.smooth, opacity: { duration: .1 } } }, transition: reduced ? { duration: 0 } : { height: motionTokens.spring.smooth, opacity: { duration: motionTokens.duration.fast } }, children: _jsx("div", { ref: measureMessage, children: _jsx(AnimatePresence, { initial: false, mode: "popLayout", children: _jsxs(motion.div, { id: messageId, className: styles.message, "data-tone": message.tone, initial: reduced ? { opacity: 0 } : { opacity: 0, y: "0.35em", filter: `blur(${motionTokens.blur.soft}px)` }, animate: { opacity: 1, y: 0, filter: "blur(0px)" }, exit: { opacity: 0, transition: { duration: .08 } }, transition: { duration: reduced ? .1 : motionTokens.duration.standard, ease: [...motionTokens.ease.enter] }, children: [_jsx("span", { className: styles.messageText, children: message.body }), pending && _jsxs("span", { className: styles.messageActions, children: [_jsx("button", { type: "button", className: styles.link, onClick: () => { const taken = pending; commit(taken.shortcut, taken.reserved ? undefined : taken.conflict); buttonRef.current?.focus(); }, children: "Use anyway" }), _jsx("button", { type: "button", className: styles.link, "data-quiet": "", onClick: () => { setPending(null); setAnnouncement("Kept the previous shortcut"); buttonRef.current?.focus(); }, children: "Cancel" })] })] }, message.key) }) }) }, "slot") }), _jsx("span", { className: styles.srOnly, role: "status", "aria-live": "polite", children: announcement })] });
+}
+/**
+ * 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 function ShortcutList({ groups, label = "Keyboard shortcuts", searchable = true, searchPlaceholder = "Search shortcuts", highlightPressed = true, platform: platformProp, className }) {
+    const reduced = useReducedFlag();
+    const platform = usePlatform(platformProp);
+    const held = usePressedKeys(highlightPressed);
+    const [query, setQuery] = useState("");
+    const searchRef = useRef(null);
+    const heldMods = useMemo(() => [...held].filter(key => ["meta", "ctrl", "alt", "shift"].includes(key)), [held]);
+    const words = query.trim().toLowerCase().replace(/[⌘]/g, " cmd ").replace(/[⇧]/g, " shift ").replace(/[⌥]/g, " alt ").replace(/[⌃]/g, " ctrl ").split(/[\s+]+/).filter(Boolean);
+    const aliases = { cmd: "command", command: "command", ctrl: "control", control: "control", opt: "option", option: platform === "mac" ? "option" : "alt", alt: platform === "mac" ? "option" : "alt", win: "windows", esc: "escape", return: platform === "mac" ? "return" : "enter" };
+    const filtered = groups.map(group => ({
+        ...group,
+        items: group.items.filter(item => {
+            if (!words.length)
+                return true;
+            const tokens = shortcutTokens(item.shortcut, platform);
+            const haystack = `${item.label} ${group.label} ${item.keywords ?? ""} ${tokens.map(token => `${token.spoken} ${token.label}`).join(" ")}`.toLowerCase();
+            return words.every(word => haystack.includes(aliases[word] ?? word) || haystack.includes(word));
+        }),
+    })).filter(group => group.items.length);
+    const total = filtered.reduce((sum, group) => sum + group.items.length, 0);
+    const rowTransition = reduced ? { duration: 0 } : motionTokens.spring.smooth;
+    return _jsxs("section", { className: [styles.list, className].filter(Boolean).join(" "), "aria-label": label, children: [searchable && _jsxs("div", { className: styles.searchRow, children: [_jsx(Search, { className: styles.searchIcon, size: 16, strokeWidth: 1.75, "aria-hidden": "true" }), _jsx("input", { ref: searchRef, className: styles.search, type: "search", placeholder: searchPlaceholder, value: query, "aria-label": searchPlaceholder, onChange: event => setQuery(event.target.value), onKeyDown: event => { if (event.key === "Escape" && query) {
+                            event.preventDefault();
+                            setQuery("");
+                        } }, autoComplete: "off", spellCheck: false }), _jsx("span", { className: styles.count, "aria-live": "polite", children: query ? `${total} ${total === 1 ? "match" : "matches"}` : "" }), _jsx(AnimatePresence, { initial: false, children: query && _jsx(motion.button, { type: "button", className: styles.clear, "aria-label": "Clear search", onClick: () => { setQuery(""); searchRef.current?.focus(); }, initial: { opacity: 0, scale: .6 }, animate: { opacity: 1, scale: 1 }, exit: { opacity: 0, scale: .6, transition: { duration: .1 } }, transition: reduced ? { duration: 0 } : motionTokens.spring.snappy, children: _jsx(X, { size: 14, strokeWidth: 1.75, "aria-hidden": "true" }) }, "clear") })] }), _jsxs("div", { className: styles.groups, children: [_jsx(AnimatePresence, { initial: false, children: filtered.map(group => _jsxs(motion.section, { className: styles.group, "aria-label": group.label, initial: reduced ? { opacity: 0 } : { opacity: 0, height: 0 }, animate: { opacity: 1, height: "auto" }, exit: reduced ? { opacity: 0 } : { opacity: 0, height: 0 }, transition: rowTransition, children: [_jsx("h4", { className: styles.groupLabel, children: group.label }), _jsx("ul", { className: styles.rows, children: _jsx(AnimatePresence, { initial: false, children: group.items.map(item => {
+                                            const tokens = shortcutTokens(item.shortcut, platform);
+                                            const ids = tokens.map(token => token.id);
+                                            const match = held.size > 0 && ids.every(key => held.has(key));
+                                            const dim = heldMods.length > 0 && !match && !heldMods.every(mod => ids.includes(mod));
+                                            return _jsx(motion.li, { className: styles.item, "data-match": match || undefined, "data-dim": dim || undefined, initial: reduced ? { opacity: 0 } : { opacity: 0, height: 0 }, animate: { opacity: 1, height: "auto" }, exit: reduced ? { opacity: 0 } : { opacity: 0, height: 0 }, transition: rowTransition, children: _jsxs("span", { className: styles.itemInner, children: [_jsx("span", { className: styles.itemLabel, children: item.label }), _jsx(ShortcutKeys, { shortcut: item.shortcut, platform: platform, pressed: held, size: "sm" })] }) }, item.label);
+                                        }) }) })] }, group.label)) }), total === 0 && _jsxs("p", { className: styles.empty, children: ["No shortcuts match \u201C", query.trim(), "\u201D"] })] })] });
+}
+export default ShortcutRecorder;

package/components/shortcut-recorder/shortcut-recorder.module.css

@@ -0,0 +1,85 @@
+/* ---------------------------------------------- Kbd ---------------------------------------------- */
+
+/* A key cap: a one pixel edge with a slightly heavier bottom, so it reads as a key without a shadow. Held, it drops a pixel and takes the accent. */
+.kbd { display: inline-grid; min-width: 26px; height: 26px; box-sizing: border-box; place-items: center; padding: 0 7px 1px; border: 1px solid var(--border-strong); border-bottom-width: 2px; border-radius: var(--radius-detail); corner-shape: var(--corner-shape); background: var(--surface-raised); color: var(--foreground); font-family: var(--font-body); font-size: var(--text-xs); font-weight: 500; line-height: 1; letter-spacing: 0; font-variant-numeric: tabular-nums; white-space: nowrap; transition: transform var(--duration-spring) var(--ease-spring), border-color var(--duration-fast) var(--ease-standard), background-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard), border-bottom-width var(--duration-fast) var(--ease-standard); }
+.kbd[data-size="sm"] { min-width: 22px; height: 22px; padding: 0 5px 1px; border-radius: var(--radius-detail); corner-shape: var(--corner-shape); font-size: var(--text-xs); }
+.kbd[data-pressed] { transform: translateY(1px); border-color: color-mix(in oklab, var(--accent) 55%, var(--border-strong)); border-bottom-width: 1px; background: var(--accent-subtle); color: var(--accent-strong); transition-duration: 90ms; }
+.kbd[data-tone="warning"] { border-color: color-mix(in oklab, var(--warning) 55%, var(--border-strong)); background: color-mix(in oklab, var(--warning) 12%, var(--surface-raised)); color: var(--foreground); }
+.keys { display: inline-flex; flex: none; align-items: center; gap: 4px; }
+
+/* ---------------------------------------------- Recorder ---------------------------------------------- */
+
+.field { display: grid; min-width: 0; font-family: var(--font-body); letter-spacing: var(--tracking-body); }
+.label { justify-self: start; margin-bottom: var(--space-related); color: var(--foreground); font-size: var(--text-sm); font-weight: 500; line-height: var(--leading-body); }
+
+.control { position: relative; display: flex; min-width: 0; height: var(--control-height-md); box-sizing: border-box; align-items: center; border: 1px solid var(--border-strong); border-radius: var(--radius-control); corner-shape: var(--corner-shape); background: var(--surface); transition: border-color var(--duration-fast) var(--ease-standard), background-color var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .control[data-state="idle"]:hover { border-color: var(--foreground); } }
+.control:has(.recorder:focus-visible) { border-color: var(--foreground); }
+.control[data-state="recording"] { border-color: var(--accent); background: color-mix(in oklab, var(--accent) 4%, var(--surface)); }
+.control[data-state="conflict"] { border-color: var(--warning); }
+.field[data-disabled] .control { opacity: .5; background: var(--surface-muted); }
+
+.recorder { display: flex; min-width: 0; height: 100%; flex: 1; align-items: center; padding: 0 6px 0 9px; border: 0; border-radius: var(--radius-control); corner-shape: var(--corner-shape); background: transparent; color: var(--foreground); cursor: pointer; font: inherit; text-align: left; -webkit-tap-highlight-color: transparent; touch-action: manipulation; outline: none; }
+.recorder:disabled { cursor: not-allowed; }
+.row { position: relative; display: flex; min-width: 0; align-items: center; gap: 4px; }
+.chipSlot { display: inline-flex; }
+.placeholder { padding-left: 3px; color: var(--text-muted); font-size: var(--text-sm); white-space: nowrap; }
+.placeholder[data-recording] { color: var(--text-secondary); }
+/* A recording light: steady in reduced motion, a slow breath otherwise. */
+.dot { width: 7px; height: 7px; flex: none; margin: 0 6px 0 3px; border-radius: 50%; corner-shape: round; background: var(--accent); animation: breathe 1.4s var(--ease-in-out) infinite; }
+.dot[data-reduced] { animation: none; }
+@keyframes breathe { 50% { opacity: .35; } }
+
+.actions { display: flex; flex: none; align-items: center; gap: 2px; padding-right: 4px; }
+.action { display: grid; width: 32px; height: 32px; place-items: center; padding: 0; border: 0; border-radius: calc(var(--radius-control) - 5px); corner-shape: var(--corner-shape); background: transparent; color: var(--text-muted); cursor: pointer; -webkit-tap-highlight-color: transparent; transition: background-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .action:hover { background: var(--surface-muted); color: var(--foreground); } }
+.action:active, .action:focus-visible { background: var(--surface-muted); color: var(--foreground); outline: none; }
+
+.messageSlot { position: relative; overflow: hidden; }
+.message { display: flex; flex-wrap: wrap; align-items: baseline; justify-content: space-between; gap: 2px var(--space-group); padding-top: var(--space-related); font-size: var(--text-xs); line-height: var(--leading-body); }
+.message[data-tone="hint"] { color: var(--text-muted); }
+.message[data-tone="warning"] { color: var(--text-secondary); }
+.message[data-tone="warning"] .messageText::before { content: ""; display: inline-block; width: 6px; height: 6px; margin: 0 7px 1px 1px; border-radius: 50%; corner-shape: round; background: var(--warning); vertical-align: middle; }
+.strong { color: var(--foreground); font-weight: 500; }
+.messageActions { display: inline-flex; gap: var(--space-group); }
+.link { padding: 0; border: 0; background: none; color: var(--foreground); cursor: pointer; font: inherit; font-weight: 500; text-decoration: underline; text-decoration-color: var(--border-strong); text-underline-offset: 3px; transition: text-decoration-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard); }
+.link:focus-visible { text-decoration-color: currentColor; outline: none; }
+.link[data-quiet] { color: var(--text-muted); font-weight: 400; text-decoration: none; }
+@media (hover: hover) and (pointer: fine) { .link:hover { text-decoration-color: currentColor; } .link[data-quiet]:hover { color: var(--foreground); } }
+
+/* ---------------------------------------------- Cheatsheet ---------------------------------------------- */
+
+.list { container-type: inline-size; display: grid; min-width: 0; gap: var(--space-group); font-family: var(--font-body); letter-spacing: var(--tracking-body); }
+.searchRow { display: flex; height: var(--control-height-sm); box-sizing: border-box; align-items: center; gap: var(--space-related); padding: 0 6px 0 12px; border: 1px solid var(--border); border-radius: var(--radius-control); corner-shape: var(--corner-shape); background: var(--surface); transition: border-color var(--duration-fast) var(--ease-standard); }
+.searchRow:focus-within { border-color: var(--foreground); }
+.searchIcon { flex: none; color: var(--text-muted); }
+.search { min-width: 0; height: 100%; flex: 1; padding: 0; border: 0; background: transparent; color: var(--foreground); font: inherit; font-size: var(--text-sm); outline: none; -webkit-appearance: none; appearance: none; }
+.search::placeholder { color: var(--text-muted); }
+.search::-webkit-search-cancel-button { display: none; }
+.count { flex: none; color: var(--text-muted); font-size: var(--text-xs); font-variant-numeric: tabular-nums; }
+.clear { display: grid; width: 24px; height: 24px; flex: none; place-items: center; padding: 0; border: 0; border-radius: var(--radius-full); corner-shape: round; background: color-mix(in oklab, var(--foreground) 8%, transparent); color: var(--text-secondary); cursor: pointer; }
+.clear:focus-visible { background: color-mix(in oklab, var(--foreground) 14%, transparent); color: var(--foreground); outline: none; }
+
+.groups { display: grid; align-items: start; gap: 0 var(--space-section); }
+@container (min-width: 520px) { .groups { grid-template-columns: 1fr 1fr; } }
+.group { overflow: hidden; margin-inline: -8px; padding-inline: 8px; }
+.groupLabel { margin: 0; padding: var(--space-group) 0 var(--space-tight); color: var(--text-muted); font-size: var(--text-xs); font-weight: 400; }
+.rows { display: grid; margin: 0; padding: 0; list-style: none; }
+.item { overflow: hidden; margin-inline: -8px; }
+/* Rows fade when a held modifier is not in them, and light when their whole combination is down. */
+.itemInner { display: flex; min-height: 36px; align-items: center; justify-content: space-between; gap: var(--space-group); padding: 0 8px; border-radius: var(--radius-detail); corner-shape: var(--corner-shape); transition: opacity var(--duration-standard) var(--ease-standard), background-color var(--duration-fast) var(--ease-standard); }
+.item + .item .itemInner { box-shadow: inset 0 1px 0 var(--border-subtle); }
+.item[data-dim] .itemInner { opacity: .38; }
+.item[data-match] .itemInner { background: var(--accent-subtle); box-shadow: none; }
+.item[data-match] + .item .itemInner { box-shadow: none; }
+.itemLabel { min-width: 0; overflow: hidden; color: var(--text-secondary); font-size: var(--text-sm); text-overflow: ellipsis; white-space: nowrap; transition: color var(--duration-fast) var(--ease-standard); }
+.item[data-match] .itemLabel { color: var(--foreground); }
+.empty { margin: 0; padding: var(--space-inset) 0; color: var(--text-muted); font-size: var(--text-sm); }
+
+.srOnly { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; }
+
+@media (prefers-reduced-motion: reduce) {
+  .kbd, .control, .itemInner { transition-duration: 0ms; }
+  .kbd[data-pressed] { transform: none; }
+  .dot { animation: none; }
+}

package/components/signature-pad/signature-pad.d.ts

@@ -0,0 +1,72 @@
+/** A sampled point: position in pad units, pen pressure between 0 and 1 (or -1 when the device has none), and ms since the stroke began. */
+export interface InkPoint {
+    x: number;
+    y: number;
+    p: number;
+    t: number;
+}
+export type InkColor = "black" | "blue" | "violet";
+export type InkWidth = "fine" | "medium" | "bold";
+export interface InkStroke {
+    id: string;
+    points: InkPoint[];
+    color: InkColor;
+    width: InkWidth;
+    /** When the stroke began, in ms. Replay keeps the real rhythm between strokes. */
+    at: number;
+}
+export interface OutlineOptions {
+    /** Diameter of the stroke at half pressure, in pad units. */
+    size: number;
+    /** How much pressure changes the width, from 0 to 1. */
+    thinning?: number;
+    /** How far each point trails the pointer, from 0 to 1. Higher is smoother but lags more. */
+    streamline?: number;
+    /** Derive pressure from speed when the device reports none: fast is thin, slow is full. */
+    simulatePressure?: boolean;
+    /** Length over which the start and the end taper, in pad units. */
+    taperStart?: number;
+    taperEnd?: number;
+    /** False while the stroke is still being drawn, so the end does not taper yet. */
+    last?: boolean;
+}
+/** Pad coordinates. Strokes are stored in this space and scale with the pad. */
+export declare const PAD_WIDTH = 600, PAD_HEIGHT = 260;
+type Vec = [number, number];
+/**
+ * Turns sampled points into the outline of a variable width stroke, in the spirit of perfect-freehand. Points are streamlined
+ * toward the pointer, width follows pen pressure or, for a mouse or finger, speed, the ends taper, sharp turns get round joins,
+ * and both ends get round caps. Returns the outline polygon; pass it to `outlineToPath` for SVG.
+ */
+export declare function getStrokeOutline(input: InkPoint[], options: OutlineOptions): Vec[];
+/** Draws an outline as one smooth closed path, with quadratic curves through the midpoints of its edges. */
+export declare function outlineToPath(points: Vec[]): string;
+/** The SVG path of a stroke, or of its first `upTo` ms while it is replayed. */
+export declare function strokePath(stroke: Pick<InkStroke, "width" | "points">, upTo?: number): string;
+/** A standalone SVG of the signature, cropped to the ink, with print ink colors. */
+export declare function signatureToSvg(strokes: InkStroke[]): string;
+/** A transparent PNG of the signature, cropped to the ink, at `scale` times pad resolution. */
+export declare function signatureToPng(strokes: InkStroke[], scale?: number): Promise<Blob>;
+/**
+ * A signature field with real ink. Width follows pen pressure, or speed for a mouse or finger, and the ends taper like a nib
+ * lifting off. It keeps undo and redo, clears with a wipe across the pad, replays the signature in its original rhythm,
+ * and exports a cropped PNG or SVG. A "Sign here" hint rests on the baseline until the first stroke.
+ * Keyboard: Mod+Z undoes, Shift+Mod+Z or Mod+Y redoes, and Delete clears.
+ */
+export interface SignaturePadProps {
+    /** Printed under the baseline, such as the signer's name. */
+    signer?: string;
+    /** Resting hint on the baseline before the first stroke. */
+    hint?: string;
+    defaultColor?: InkColor;
+    defaultWidth?: InkWidth;
+    /** Receives the strokes after every change. */
+    onChange?: (strokes: InkStroke[]) => void;
+    /** File name for exports, without extension. */
+    fileName?: string;
+    /** Accessible name of the drawing surface. */
+    label?: string;
+    className?: string;
+}
+export declare function SignaturePad({ signer, hint, defaultColor, defaultWidth, onChange, fileName, label, className }: SignaturePadProps): import("react").JSX.Element;
+export default SignaturePad;