@dowel-ui/react 0.4.0 → 0.5.0

package/dist/components/session-expiry/session-expiry.js

@@ -0,0 +1,185 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import { Button } from "../button/button.js";
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "../dialog/dialog.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { memo, useEffect, useId, useRef, useState, useSyncExternalStore } from "react";
+//#region src/components/session-expiry/session-expiry.tsx
+/** Where a session stands, given the clock. Pure, for tests and for the server. */
+function sessionPhase(expiresAt, now, warnBefore) {
+	const remaining = expiresAt.getTime() - now.getTime();
+	if (remaining <= 0) return "expired";
+	if (remaining <= warnBefore) return "warning";
+	return "active";
+}
+/** Whole seconds left, never negative. */
+function secondsLeft(expiresAt, now) {
+	return Math.max(0, Math.ceil((expiresAt.getTime() - now.getTime()) / 1e3));
+}
+/** "1:59" for the screen. */
+function formatCountdown(seconds) {
+	const minutes = Math.floor(seconds / 60);
+	const rest = seconds % 60;
+	return `${String(minutes)}:${String(rest).padStart(2, "0")}`;
+}
+/** "1 minute 59 seconds" for the ear. */
+function describeCountdown(seconds) {
+	const minutes = Math.floor(seconds / 60);
+	const rest = seconds % 60;
+	const parts = [];
+	if (minutes > 0) parts.push(`${String(minutes)} ${minutes === 1 ? "minute" : "minutes"}`);
+	if (rest > 0 || minutes === 0) parts.push(`${String(rest)} ${rest === 1 ? "second" : "seconds"}`);
+	return parts.join(" ");
+}
+/** The seconds-left values at which the countdown is said aloud. */
+const ANNOUNCE_AT = [
+	60,
+	30,
+	10
+];
+function subscribeToClock(callback) {
+	const timer = setInterval(callback, 1e3);
+	return () => {
+		clearInterval(timer);
+	};
+}
+/** Whole seconds, so the snapshot is stable within a second and React does not re-render for nothing. */
+const readClockSeconds = () => Math.floor(Date.now() / 1e3);
+const readNoClock = () => null;
+function SessionExpiry({ expiresAt, warnBefore = 12e4, now: nowProp, onExtend, onExpire, onSignOut, heading = "Your session is about to end", children, expiredAction, className }) {
+	const id = useId();
+	const tickSeconds = useSyncExternalStore(subscribeToClock, readClockSeconds, readNoClock);
+	const tick = tickSeconds === null ? null : /* @__PURE__ */ new Date(tickSeconds * 1e3);
+	const now = nowProp ?? tick;
+	const phase = now ? sessionPhase(expiresAt, now, warnBefore) : "active";
+	const seconds = now ? secondsLeft(expiresAt, now) : 0;
+	const [announcement, setAnnouncement] = useState("");
+	const [spoken, setSpoken] = useState(null);
+	const [endedFor, setEndedFor] = useState(null);
+	if (phase === "warning") {
+		if (spoken === null) {
+			setSpoken(Number.POSITIVE_INFINITY);
+			setAnnouncement(`${heading}. ${describeCountdown(seconds)} left.`);
+		} else {
+			const due = ANNOUNCE_AT.find((at) => seconds <= at && at < spoken);
+			if (due !== void 0) {
+				setSpoken(due);
+				setAnnouncement(`${describeCountdown(seconds)} left.`);
+			}
+		}
+	} else if (spoken !== null && phase === "active") {
+		setSpoken(null);
+		setAnnouncement("");
+	} else if (phase === "expired" && endedFor !== expiresAt.getTime()) {
+		setEndedFor(expiresAt.getTime());
+		setAnnouncement("Your session has ended.");
+	}
+	const firedFor = useRef(null);
+	useEffect(() => {
+		if (phase !== "expired" || firedFor.current === expiresAt.getTime()) return;
+		firedFor.current = expiresAt.getTime();
+		onExpire?.();
+	}, [
+		phase,
+		expiresAt,
+		onExpire
+	]);
+	const open = phase !== "active";
+	const [shown, setShown] = useState(seconds);
+	if (open && shown !== seconds) setShown(seconds);
+	return /* @__PURE__ */ jsx(ExpiryDialog, {
+		id,
+		open,
+		phase,
+		seconds: shown,
+		heading,
+		announcement,
+		onExtend,
+		onSignOut,
+		expiredAction,
+		className,
+		children
+	});
+}
+const ExpiryDialog = memo(function ExpiryDialog({ id, open, phase, seconds, heading, announcement, onExtend, onSignOut, expiredAction, className, children }) {
+	const stayRef = useRef(null);
+	const [extending, setExtending] = useState(false);
+	const extend = () => {
+		const result = onExtend();
+		if (result instanceof Promise) {
+			setExtending(true);
+			result.finally(() => {
+				setExtending(false);
+			});
+		}
+	};
+	return /* @__PURE__ */ jsx(Dialog, {
+		open,
+		children: /* @__PURE__ */ jsxs(DialogContent, {
+			role: "alertdialog",
+			showCloseButton: false,
+			"aria-describedby": `${id}-description`,
+			"data-slot": "session-expiry",
+			"data-phase": phase,
+			className: cn("max-w-sm", className),
+			onEscapeKeyDown: (event) => {
+				event.preventDefault();
+			},
+			onPointerDownOutside: (event) => {
+				event.preventDefault();
+			},
+			onInteractOutside: (event) => {
+				event.preventDefault();
+			},
+			onOpenAutoFocus: (event) => {
+				event.preventDefault();
+				stayRef.current?.focus();
+			},
+			children: [
+				/* @__PURE__ */ jsxs(DialogHeader, { children: [/* @__PURE__ */ jsx(DialogTitle, { children: phase === "expired" ? "Your session has ended" : heading }), /* @__PURE__ */ jsx(DialogDescription, {
+					id: `${id}-description`,
+					children: phase === "expired" ? "You were signed out after a period of inactivity." : /* @__PURE__ */ jsxs(Fragment, { children: [
+						"You will be signed out in",
+						" ",
+						/* @__PURE__ */ jsxs("span", {
+							"data-slot": "session-expiry-countdown",
+							className: "font-medium tabular-nums",
+							children: [/* @__PURE__ */ jsx("span", {
+								"aria-hidden": "true",
+								children: formatCountdown(seconds)
+							}), /* @__PURE__ */ jsx("span", {
+								className: "sr-only",
+								children: describeCountdown(seconds)
+							})]
+						}),
+						"."
+					] })
+				})] }),
+				children ? /* @__PURE__ */ jsx("div", {
+					className: "text-sm text-muted-foreground",
+					children
+				}) : null,
+				/* @__PURE__ */ jsx("span", {
+					role: "status",
+					"aria-live": "polite",
+					className: "sr-only",
+					children: announcement
+				}),
+				/* @__PURE__ */ jsx(DialogFooter, { children: phase === "expired" ? expiredAction : /* @__PURE__ */ jsxs(Fragment, { children: [onSignOut ? /* @__PURE__ */ jsx(Button, {
+					variant: "outline",
+					onClick: onSignOut,
+					children: "Sign out now"
+				}) : null, /* @__PURE__ */ jsx(Button, {
+					ref: stayRef,
+					loading: extending,
+					onClick: extend,
+					children: "Stay signed in"
+				})] }) })
+			]
+		})
+	});
+});
+//#endregion
+export { SessionExpiry, describeCountdown, formatCountdown, secondsLeft, sessionPhase };
+
+//# sourceMappingURL=session-expiry.js.map

package/dist/components/session-expiry/session-expiry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-expiry.js","names":[],"sources":["../../../src/components/session-expiry/session-expiry.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  memo,\n  useEffect,\n  useId,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type ReactNode,\n} from \"react\";\n\nimport { Button } from \"@/components/button\";\nimport {\n  Dialog,\n  DialogContent,\n  DialogDescription,\n  DialogFooter,\n  DialogHeader,\n  DialogTitle,\n} from \"@/components/dialog\";\nimport { cn } from \"@/lib/utils\";\n\n/**\n * \"Your session ends in two minutes. Stay signed in?\"\n *\n * Every product with an idle timeout builds this, and WCAG 2.2.1 (Timing\n * Adjustable) says what it has to do: warn before the time runs out, and\n * give at least twenty seconds to extend it with a simple action. Most\n * implementations get the first half — a toast, a modal — and fail the\n * second in one of two ways: the warning can be dismissed without choosing,\n * so a reader who closed it to see the page underneath is signed out with\n * no further word; or the countdown is a live region, so a screen reader\n * user hears a number every second for two minutes and cannot hear the\n * choice they are being asked to make.\n *\n * So this is an alert dialog that cannot be waved away. Escape and the\n * backdrop do nothing, because dismissing a session warning without\n * choosing is choosing nothing, and the two buttons are the two things a\n * person can actually do. The countdown ticks on screen and is announced at\n * four moments — when the warning opens, at one minute, thirty seconds and\n * ten — which is enough to know how long is left and quiet enough to hear\n * the question.\n *\n * When time runs out, `onExpire` fires once and the dialog says so, with a\n * slot for whatever the application offers next. It does not sign anyone\n * out; the server did that, and this is the part that tells the person.\n */\n\nexport type SessionPhase = \"active\" | \"warning\" | \"expired\";\n\n/** Where a session stands, given the clock. Pure, for tests and for the server. */\nexport function sessionPhase(expiresAt: Date, now: Date, warnBefore: number): SessionPhase {\n  const remaining = expiresAt.getTime() - now.getTime();\n  if (remaining <= 0) return \"expired\";\n  if (remaining <= warnBefore) return \"warning\";\n  return \"active\";\n}\n\n/** Whole seconds left, never negative. */\nexport function secondsLeft(expiresAt: Date, now: Date): number {\n  return Math.max(0, Math.ceil((expiresAt.getTime() - now.getTime()) / 1000));\n}\n\n/** \"1:59\" for the screen. */\nexport function formatCountdown(seconds: number): string {\n  const minutes = Math.floor(seconds / 60);\n  const rest = seconds % 60;\n  return `${String(minutes)}:${String(rest).padStart(2, \"0\")}`;\n}\n\n/** \"1 minute 59 seconds\" for the ear. */\nexport function describeCountdown(seconds: number): string {\n  const minutes = Math.floor(seconds / 60);\n  const rest = seconds % 60;\n  const parts: string[] = [];\n  if (minutes > 0) parts.push(`${String(minutes)} ${minutes === 1 ? \"minute\" : \"minutes\"}`);\n  if (rest > 0 || minutes === 0)\n    parts.push(`${String(rest)} ${rest === 1 ? \"second\" : \"seconds\"}`);\n  return parts.join(\" \");\n}\n\n/** The seconds-left values at which the countdown is said aloud. */\nconst ANNOUNCE_AT = [60, 30, 10];\n\nfunction subscribeToClock(callback: () => void) {\n  const timer = setInterval(callback, 1000);\n  return () => {\n    clearInterval(timer);\n  };\n}\n/** Whole seconds, so the snapshot is stable within a second and React does not re-render for nothing. */\nconst readClockSeconds = () => Math.floor(Date.now() / 1000);\nconst readNoClock = () => null;\n\nexport interface SessionExpiryProps {\n  /** When the session ends. Move it forward after a successful extend. */\n  expiresAt: Date;\n  /** How long before the end to warn, in milliseconds. Two minutes by default. */\n  warnBefore?: number;\n  /**\n   * The clock. Supply it to drive the countdown yourself, or in tests; omit\n   * and the component ticks once a second while mounted.\n   */\n  now?: Date;\n  /** Keep the session going. May return a promise; the button waits for it. */\n  onExtend: () => void | Promise<void>;\n  /** Called once when the time runs out. */\n  onExpire?: () => void;\n  /** Offered as the other choice. Omit to offer only staying signed in. */\n  onSignOut?: () => void;\n  /** The warning's heading. */\n  heading?: string;\n  /** What is at stake, in the reader's language: \"Unsaved edits will be lost.\" */\n  children?: ReactNode;\n  /** What to offer once the session has ended: a sign-in link, usually. */\n  expiredAction?: ReactNode;\n  className?: string;\n}\n\nexport function SessionExpiry({\n  expiresAt,\n  warnBefore = 120_000,\n  now: nowProp,\n  onExtend,\n  onExpire,\n  onSignOut,\n  heading = \"Your session is about to end\",\n  children,\n  expiredAction,\n  className,\n}: SessionExpiryProps) {\n  const id = useId();\n\n  // The clock as an external store that ticks once a second. The server\n  // snapshot is null, so the server and the first client render agree on\n  // showing nothing; the real instant arrives in the re-render after.\n  const tickSeconds = useSyncExternalStore(subscribeToClock, readClockSeconds, readNoClock);\n  const tick = tickSeconds === null ? null : new Date(tickSeconds * 1000);\n\n  const now = nowProp ?? tick;\n  const phase = now ? sessionPhase(expiresAt, now, warnBefore) : \"active\";\n  const seconds = now ? secondsLeft(expiresAt, now) : 0;\n\n  const [announcement, setAnnouncement] = useState(\"\");\n\n  // Announced at the moments that matter, not every second. Tracked as the\n  // last threshold spoken so a tick that skips a value still says it once.\n  const [spoken, setSpoken] = useState<number | null>(null);\n  const [endedFor, setEndedFor] = useState<number | null>(null);\n\n  if (phase === \"warning\") {\n    if (spoken === null) {\n      setSpoken(Number.POSITIVE_INFINITY);\n      setAnnouncement(`${heading}. ${describeCountdown(seconds)} left.`);\n    } else {\n      const due = ANNOUNCE_AT.find((at) => seconds <= at && at < spoken);\n      if (due !== undefined) {\n        setSpoken(due);\n        setAnnouncement(`${describeCountdown(seconds)} left.`);\n      }\n    }\n  } else if (spoken !== null && phase === \"active\") {\n    // Extended. The next warning starts its announcements afresh.\n    setSpoken(null);\n    setAnnouncement(\"\");\n  } else if (phase === \"expired\" && endedFor !== expiresAt.getTime()) {\n    setEndedFor(expiresAt.getTime());\n    setAnnouncement(\"Your session has ended.\");\n  }\n\n  // The one side effect: telling the application, once per expiry. A ref\n  // rather than state, because nothing rendered depends on it.\n  const firedFor = useRef<number | null>(null);\n  useEffect(() => {\n    if (phase !== \"expired\" || firedFor.current === expiresAt.getTime()) return;\n    firedFor.current = expiresAt.getTime();\n    onExpire?.();\n  }, [phase, expiresAt, onExpire]);\n\n  const open = phase !== \"active\";\n\n  // Once told to close, the dialog is left alone: the countdown it shows is\n  // frozen and its props stop changing, so the clock's ticks no longer\n  // re-render a surface that is mid-exit. A dialog re-rendered every second\n  // while closing never finishes closing.\n  const [shown, setShown] = useState(seconds);\n  if (open && shown !== seconds) setShown(seconds);\n\n  return (\n    <ExpiryDialog\n      id={id}\n      open={open}\n      phase={phase}\n      seconds={shown}\n      heading={heading}\n      announcement={announcement}\n      onExtend={onExtend}\n      onSignOut={onSignOut}\n      expiredAction={expiredAction}\n      className={className}\n    >\n      {children}\n    </ExpiryDialog>\n  );\n}\n\ninterface ExpiryDialogProps {\n  id: string;\n  open: boolean;\n  phase: SessionPhase;\n  seconds: number;\n  heading: string;\n  announcement: string;\n  onExtend: () => void | Promise<void>;\n  onSignOut?: () => void;\n  expiredAction?: ReactNode;\n  className?: string;\n  children?: ReactNode;\n}\n\nconst ExpiryDialog = memo(function ExpiryDialog({\n  id,\n  open,\n  phase,\n  seconds,\n  heading,\n  announcement,\n  onExtend,\n  onSignOut,\n  expiredAction,\n  className,\n  children,\n}: ExpiryDialogProps) {\n  const stayRef = useRef<HTMLButtonElement>(null);\n  const [extending, setExtending] = useState(false);\n\n  const extend = () => {\n    const result = onExtend();\n    if (result instanceof Promise) {\n      setExtending(true);\n      void result.finally(() => {\n        setExtending(false);\n      });\n    }\n  };\n\n  return (\n    <Dialog open={open}>\n      <DialogContent\n        role=\"alertdialog\"\n        showCloseButton={false}\n        aria-describedby={`${id}-description`}\n        data-slot=\"session-expiry\"\n        data-phase={phase}\n        className={cn(\"max-w-sm\", className)}\n        // Dismissing a session warning without choosing is choosing nothing,\n        // so the gestures that dismiss a dialog do nothing here. The buttons\n        // are the way out, and there are two of them.\n        onEscapeKeyDown={(event) => {\n          event.preventDefault();\n        }}\n        onPointerDownOutside={(event) => {\n          event.preventDefault();\n        }}\n        onInteractOutside={(event) => {\n          event.preventDefault();\n        }}\n        // Focus lands on the safe choice. The first tabbable would be \"Sign\n        // out now\", and a reflexive Enter on that is the outcome the whole\n        // dialog exists to prevent.\n        onOpenAutoFocus={(event) => {\n          event.preventDefault();\n          stayRef.current?.focus();\n        }}\n      >\n        <DialogHeader>\n          <DialogTitle>{phase === \"expired\" ? \"Your session has ended\" : heading}</DialogTitle>\n          <DialogDescription id={`${id}-description`}>\n            {phase === \"expired\" ? (\n              \"You were signed out after a period of inactivity.\"\n            ) : (\n              <>\n                You will be signed out in{\" \"}\n                <span data-slot=\"session-expiry-countdown\" className=\"font-medium tabular-nums\">\n                  <span aria-hidden=\"true\">{formatCountdown(seconds)}</span>\n                  <span className=\"sr-only\">{describeCountdown(seconds)}</span>\n                </span>\n                .\n              </>\n            )}\n          </DialogDescription>\n        </DialogHeader>\n\n        {children ? <div className=\"text-sm text-muted-foreground\">{children}</div> : null}\n\n        {/* The countdown above is not live. This is, and it speaks four times. */}\n        <span role=\"status\" aria-live=\"polite\" className=\"sr-only\">\n          {announcement}\n        </span>\n\n        <DialogFooter>\n          {phase === \"expired\" ? (\n            expiredAction\n          ) : (\n            <>\n              {onSignOut ? (\n                <Button variant=\"outline\" onClick={onSignOut}>\n                  Sign out now\n                </Button>\n              ) : null}\n              <Button ref={stayRef} loading={extending} onClick={extend}>\n                Stay signed in\n              </Button>\n            </>\n          )}\n        </DialogFooter>\n      </DialogContent>\n    </Dialog>\n  );\n});\n"],"mappings":"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"}

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

@@ -0,0 +1,3 @@
+import { Platform, RESERVED_KEYS, Shortcut, describeShortcut, detectPlatform, formatShortcut, needsModifier, parseShortcut, serializeShortcut, shortcutFromKey, shortcutParts, shortcutsEqual } from "./shortcut-model.js";
+import { ShortcutRecorder, ShortcutRecorderProps, TakenShortcut } from "./shortcut-recorder.js";
+export { type Platform, RESERVED_KEYS, type Shortcut, ShortcutRecorder, type ShortcutRecorderProps, type TakenShortcut, describeShortcut, detectPlatform, formatShortcut, needsModifier, parseShortcut, serializeShortcut, shortcutFromKey, shortcutParts, shortcutsEqual };

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

@@ -0,0 +1,3 @@
+import { RESERVED_KEYS, describeShortcut, detectPlatform, formatShortcut, needsModifier, parseShortcut, serializeShortcut, shortcutFromKey, shortcutParts, shortcutsEqual } from "./shortcut-model.js";
+import { ShortcutRecorder } from "./shortcut-recorder.js";
+export { RESERVED_KEYS, ShortcutRecorder, describeShortcut, detectPlatform, formatShortcut, needsModifier, parseShortcut, serializeShortcut, shortcutFromKey, shortcutParts, shortcutsEqual };

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

@@ -0,0 +1,17 @@
+import { defineMeta } from "../../registry/schema.js";
+//#region src/components/shortcut-recorder/meta.ts
+const meta = defineMeta({
+	name: "shortcut-recorder",
+	title: "Shortcut Recorder",
+	description: "Press the keys you want: records a chord, platform-aware, and says when it clashes.",
+	category: "form",
+	status: "stable",
+	dependencies: [],
+	registryDependencies: [],
+	files: ["shortcut-model.ts", "shortcut-recorder.tsx"],
+	a11y: "The recorder is a button named by what the shortcut does and described by its value in words — Command Shift K — while the key caps on it are hidden from assistive technology, since ⌘⇧K read aloud is noise. While recording it is aria-pressed and its description says what to do; Tab always leaves and Escape always cancels, so it is never a keyboard trap. Every outcome is announced through a status region present from the start: recorded, refused with the reason, clashing with which command, cancelled, cleared. Symbols are shown on a Mac and words elsewhere, and the description uses the platform's own names for its keys."
+});
+//#endregion
+export { meta };
+
+//# sourceMappingURL=meta.js.map

package/dist/components/shortcut-recorder/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","names":[],"sources":["../../../src/components/shortcut-recorder/meta.ts"],"sourcesContent":["import { defineMeta } from \"@/registry/schema\";\n\nexport const meta = defineMeta({\n  name: \"shortcut-recorder\",\n  title: \"Shortcut Recorder\",\n  description:\n    \"Press the keys you want: records a chord, platform-aware, and says when it clashes.\",\n  category: \"form\",\n  status: \"stable\",\n  dependencies: [],\n  registryDependencies: [],\n  files: [\"shortcut-model.ts\", \"shortcut-recorder.tsx\"],\n  a11y:\n    \"The recorder is a button named by what the shortcut does and described by its value in \" +\n    \"words — Command Shift K — while the key caps on it are hidden from assistive technology, \" +\n    \"since ⌘⇧K read aloud is noise. While recording it is aria-pressed and its description \" +\n    \"says what to do; Tab always leaves and Escape always cancels, so it is never a keyboard \" +\n    \"trap. Every outcome is announced through a status region present from the start: recorded, \" +\n    \"refused with the reason, clashing with which command, cancelled, cleared. Symbols are shown \" +\n    \"on a Mac and words elsewhere, and the description uses the platform's own names for its \" +\n    \"keys.\",\n});\n"],"mappings":";;AAEA,MAAa,OAAO,WAAW;CAC7B,MAAM;CACN,OAAO;CACP,aACE;CACF,UAAU;CACV,QAAQ;CACR,cAAc,CAAC;CACf,sBAAsB,CAAC;CACvB,OAAO,CAAC,qBAAqB,uBAAuB;CACpD,MACE;AAQJ,CAAC"}

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

@@ -0,0 +1,67 @@
+//#region src/components/shortcut-recorder/shortcut-model.d.ts
+/**
+ * A keyboard shortcut as a value: parsed from the string an app stores,
+ * built from a keydown, and written back out for a Mac, for everyone else,
+ * and for the ear.
+ *
+ * Pure, so the modifier canon, the platform rendering and the conflict rule
+ * are tested without a keyboard, and so the same `parseShortcut` can run on
+ * the server that validates a saved binding.
+ *
+ * The stored form is platform-neutral: `Mod+Shift+K`, where `Mod` is Command
+ * on a Mac and Control elsewhere. That is the one decision every app makes
+ * and few make explicitly — a binding saved as `Ctrl+K` on Windows is wrong
+ * the moment the same account opens on a Mac.
+ */
+type Platform = "mac" | "other";
+interface Shortcut {
+  /** The non-modifier key, canonical: `K`, `1`, `ArrowUp`, `F5`, `Enter`, `Space`. */
+  key: string;
+  /** Command on a Mac, Control elsewhere. */
+  mod: boolean;
+  /** Control, held explicitly — on a Mac this is a different key from Mod. */
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+}
+/** Keys that cannot be a shortcut, because they already mean something. */
+declare const RESERVED_KEYS: Set<string>;
+/**
+ * `Mod+Shift+K` to a shortcut. Accepts the spellings people use — `Cmd`,
+ * `Command`, `Ctrl`, `Option` — and throws on an empty or modifier-only one.
+ */
+declare function parseShortcut(text: string): Shortcut;
+/** The stored, platform-neutral form. Modifiers in a fixed order, so equal shortcuts are equal strings. */
+declare function serializeShortcut(shortcut: Shortcut): string;
+declare function shortcutsEqual(a: Shortcut, b: Shortcut): boolean;
+interface KeyLike {
+  key: string;
+  code?: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  altKey: boolean;
+  shiftKey: boolean;
+}
+/**
+ * The shortcut a keydown amounts to, or null while only modifiers are held.
+ *
+ * Letters and digits come from `code`, not `key`: with Shift or Option held,
+ * `key` is `K`, `˚` or `∆` depending on the layout and the platform, and a
+ * shortcut recorded as Option-∆ is one nobody can read back. `Mod` is Meta
+ * on a Mac and Control elsewhere; the other one, when held, is kept as
+ * itself.
+ */
+declare function shortcutFromKey(event: KeyLike, platform: Platform): Shortcut | null;
+/** Printable keys need a modifier: a bare K as a shortcut fires while someone types a sentence. */
+declare function needsModifier(shortcut: Shortcut): boolean;
+/** The parts to draw, in order: symbols on a Mac, words elsewhere. */
+declare function shortcutParts(shortcut: Shortcut, platform: Platform): string[];
+/** "⌘⇧K" on a Mac, "Ctrl+Shift+K" elsewhere. */
+declare function formatShortcut(shortcut: Shortcut, platform: Platform): string;
+/** "Command Shift K" — words, for the ear, whatever the screen shows. */
+declare function describeShortcut(shortcut: Shortcut, platform: Platform): string;
+/** Whether the browser is on a Mac, by the only signal it gives. */
+declare function detectPlatform(): Platform;
+//#endregion
+export { Platform, RESERVED_KEYS, Shortcut, describeShortcut, detectPlatform, formatShortcut, needsModifier, parseShortcut, serializeShortcut, shortcutFromKey, shortcutParts, shortcutsEqual };
+//# sourceMappingURL=shortcut-model.d.ts.map

package/dist/components/shortcut-recorder/shortcut-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcut-model.d.ts","names":[],"sources":["../../../src/components/shortcut-recorder/shortcut-model.ts"],"mappings":";;;;;;;;;;;;;;;KAeY;UAEK;;EAEf;;EAEA;;EAEA;EACA;EACA;;;cAMW,eAAa;;;;;iBAgCV,cAAc,eAAe;;iBAsB7B,kBAAkB,UAAU;iBAU5B,eAAe,GAAG,UAAU,GAAG;UAIrC;EACR;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;iBAYc,gBAAgB,OAAO,SAAS,UAAU,WAAW;;iBAoBrD,cAAc,UAAU;;iBA2BxB,cAAc,UAAU,UAAU,UAAU;;iBAe5C,eAAe,UAAU,UAAU,UAAU;;iBAK7C,iBAAiB,UAAU,UAAU,UAAU;;iBAa/C,kBAAkB"}

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

@@ -0,0 +1,168 @@
+//#region src/components/shortcut-recorder/shortcut-model.ts
+const MODIFIER_KEYS = /* @__PURE__ */ new Set([
+	"Meta",
+	"Control",
+	"Alt",
+	"Shift",
+	"OS",
+	"AltGraph",
+	"Fn"
+]);
+/** Keys that cannot be a shortcut, because they already mean something. */
+const RESERVED_KEYS = /* @__PURE__ */ new Set(["Tab", "Escape"]);
+const KEY_ALIASES = {
+	" ": "Space",
+	spacebar: "Space",
+	esc: "Escape",
+	return: "Enter",
+	del: "Delete",
+	up: "ArrowUp",
+	down: "ArrowDown",
+	left: "ArrowLeft",
+	right: "ArrowRight",
+	cmd: "Mod",
+	command: "Mod",
+	meta: "Mod",
+	control: "Ctrl",
+	option: "Alt"
+};
+/** The canonical key name for a token someone typed or stored. */
+function canonicalKey(token) {
+	const alias = KEY_ALIASES[token.toLowerCase()];
+	if (alias) return alias;
+	if (token.length === 1) return token.toUpperCase();
+	return token.charAt(0).toUpperCase() + token.slice(1);
+}
+/**
+* `Mod+Shift+K` to a shortcut. Accepts the spellings people use — `Cmd`,
+* `Command`, `Ctrl`, `Option` — and throws on an empty or modifier-only one.
+*/
+function parseShortcut(text) {
+	const tokens = text.split("+").map((token) => token.trim()).filter(Boolean);
+	if (tokens.length === 0) throw new Error("Enter a shortcut.");
+	const shortcut = {
+		key: "",
+		mod: false,
+		ctrl: false,
+		alt: false,
+		shift: false
+	};
+	for (const token of tokens) {
+		const canonical = canonicalKey(token);
+		if (canonical === "Mod") shortcut.mod = true;
+		else if (canonical === "Ctrl") shortcut.ctrl = true;
+		else if (canonical === "Alt") shortcut.alt = true;
+		else if (canonical === "Shift") shortcut.shift = true;
+		else if (shortcut.key) throw new Error(`"${text}" has two keys; a shortcut has one.`);
+		else shortcut.key = canonical;
+	}
+	if (!shortcut.key) throw new Error(`"${text}" is only modifiers; it needs a key.`);
+	return shortcut;
+}
+/** The stored, platform-neutral form. Modifiers in a fixed order, so equal shortcuts are equal strings. */
+function serializeShortcut(shortcut) {
+	const parts = [];
+	if (shortcut.mod) parts.push("Mod");
+	if (shortcut.ctrl) parts.push("Ctrl");
+	if (shortcut.alt) parts.push("Alt");
+	if (shortcut.shift) parts.push("Shift");
+	parts.push(shortcut.key);
+	return parts.join("+");
+}
+function shortcutsEqual(a, b) {
+	return serializeShortcut(a) === serializeShortcut(b);
+}
+/**
+* The shortcut a keydown amounts to, or null while only modifiers are held.
+*
+* Letters and digits come from `code`, not `key`: with Shift or Option held,
+* `key` is `K`, `˚` or `∆` depending on the layout and the platform, and a
+* shortcut recorded as Option-∆ is one nobody can read back. `Mod` is Meta
+* on a Mac and Control elsewhere; the other one, when held, is kept as
+* itself.
+*/
+function shortcutFromKey(event, platform) {
+	if (MODIFIER_KEYS.has(event.key)) return null;
+	let key;
+	const code = event.code ?? "";
+	if (/^Key[A-Z]$/.test(code)) key = code.slice(3);
+	else if (/^Digit[0-9]$/.test(code)) key = code.slice(5);
+	else key = canonicalKey(event.key);
+	const mac = platform === "mac";
+	return {
+		key,
+		mod: mac ? event.metaKey : event.ctrlKey,
+		ctrl: mac ? event.ctrlKey : false,
+		alt: event.altKey,
+		shift: event.shiftKey
+	};
+}
+/** Printable keys need a modifier: a bare K as a shortcut fires while someone types a sentence. */
+function needsModifier(shortcut) {
+	return (shortcut.key.length === 1 || shortcut.key === "Space") && !shortcut.mod && !shortcut.ctrl && !shortcut.alt;
+}
+const MAC_SYMBOLS = {
+	Mod: "⌘",
+	Ctrl: "⌃",
+	Alt: "⌥",
+	Shift: "⇧",
+	Enter: "↩",
+	Backspace: "⌫",
+	Delete: "⌦",
+	ArrowUp: "↑",
+	ArrowDown: "↓",
+	ArrowLeft: "←",
+	ArrowRight: "→",
+	Escape: "⎋",
+	Space: "Space"
+};
+const SPOKEN = {
+	mac: {
+		Mod: "Command",
+		Ctrl: "Control",
+		Alt: "Option",
+		Shift: "Shift"
+	},
+	other: {
+		Mod: "Control",
+		Ctrl: "Control",
+		Alt: "Alt",
+		Shift: "Shift"
+	}
+};
+/** The parts to draw, in order: symbols on a Mac, words elsewhere. */
+function shortcutParts(shortcut, platform) {
+	const parts = [];
+	const name = (modifier) => platform === "mac" ? MAC_SYMBOLS[modifier] ?? modifier : SPOKEN.other[modifier] ?? modifier;
+	if (shortcut.mod) parts.push(name("Mod"));
+	if (shortcut.ctrl && !(platform === "other" && shortcut.mod)) parts.push(name("Ctrl"));
+	if (shortcut.alt) parts.push(name("Alt"));
+	if (shortcut.shift) parts.push(name("Shift"));
+	parts.push(platform === "mac" ? MAC_SYMBOLS[shortcut.key] ?? shortcut.key : shortcut.key);
+	return parts;
+}
+/** "⌘⇧K" on a Mac, "Ctrl+Shift+K" elsewhere. */
+function formatShortcut(shortcut, platform) {
+	return shortcutParts(shortcut, platform).join(platform === "mac" ? "" : "+");
+}
+/** "Command Shift K" — words, for the ear, whatever the screen shows. */
+function describeShortcut(shortcut, platform) {
+	const words = [];
+	const spoken = SPOKEN[platform];
+	if (shortcut.mod) words.push(spoken.Mod ?? "Mod");
+	if (shortcut.ctrl && !(platform === "other" && shortcut.mod)) words.push(spoken.Ctrl ?? "Ctrl");
+	if (shortcut.alt) words.push(spoken.Alt ?? "Alt");
+	if (shortcut.shift) words.push(spoken.Shift ?? "Shift");
+	words.push(shortcut.key.replace(/^Arrow/, "Arrow "));
+	return words.join(" ");
+}
+/** Whether the browser is on a Mac, by the only signal it gives. */
+function detectPlatform() {
+	if (typeof navigator === "undefined") return "other";
+	const hint = navigator.userAgentData?.platform ?? navigator.platform;
+	return /mac|iphone|ipad|ipod/i.test(hint) ? "mac" : "other";
+}
+//#endregion
+export { RESERVED_KEYS, describeShortcut, detectPlatform, formatShortcut, needsModifier, parseShortcut, serializeShortcut, shortcutFromKey, shortcutParts, shortcutsEqual };
+
+//# sourceMappingURL=shortcut-model.js.map

package/dist/components/shortcut-recorder/shortcut-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcut-model.js","names":[],"sources":["../../../src/components/shortcut-recorder/shortcut-model.ts"],"sourcesContent":["/**\n * A keyboard shortcut as a value: parsed from the string an app stores,\n * built from a keydown, and written back out for a Mac, for everyone else,\n * and for the ear.\n *\n * Pure, so the modifier canon, the platform rendering and the conflict rule\n * are tested without a keyboard, and so the same `parseShortcut` can run on\n * the server that validates a saved binding.\n *\n * The stored form is platform-neutral: `Mod+Shift+K`, where `Mod` is Command\n * on a Mac and Control elsewhere. That is the one decision every app makes\n * and few make explicitly — a binding saved as `Ctrl+K` on Windows is wrong\n * the moment the same account opens on a Mac.\n */\n\nexport type Platform = \"mac\" | \"other\";\n\nexport interface Shortcut {\n  /** The non-modifier key, canonical: `K`, `1`, `ArrowUp`, `F5`, `Enter`, `Space`. */\n  key: string;\n  /** Command on a Mac, Control elsewhere. */\n  mod: boolean;\n  /** Control, held explicitly — on a Mac this is a different key from Mod. */\n  ctrl: boolean;\n  alt: boolean;\n  shift: boolean;\n}\n\nconst MODIFIER_KEYS = new Set([\"Meta\", \"Control\", \"Alt\", \"Shift\", \"OS\", \"AltGraph\", \"Fn\"]);\n\n/** Keys that cannot be a shortcut, because they already mean something. */\nexport const RESERVED_KEYS = new Set([\"Tab\", \"Escape\"]);\n\nconst KEY_ALIASES: Record<string, string> = {\n  \" \": \"Space\",\n  spacebar: \"Space\",\n  esc: \"Escape\",\n  return: \"Enter\",\n  del: \"Delete\",\n  up: \"ArrowUp\",\n  down: \"ArrowDown\",\n  left: \"ArrowLeft\",\n  right: \"ArrowRight\",\n  cmd: \"Mod\",\n  command: \"Mod\",\n  meta: \"Mod\",\n  control: \"Ctrl\",\n  option: \"Alt\",\n};\n\n/** The canonical key name for a token someone typed or stored. */\nfunction canonicalKey(token: string): string {\n  const alias = KEY_ALIASES[token.toLowerCase()];\n  if (alias) return alias;\n  if (token.length === 1) return token.toUpperCase();\n  // ArrowUp, F5, Enter, Backspace, Delete, Home, End, PageUp…\n  return token.charAt(0).toUpperCase() + token.slice(1);\n}\n\n/**\n * `Mod+Shift+K` to a shortcut. Accepts the spellings people use — `Cmd`,\n * `Command`, `Ctrl`, `Option` — and throws on an empty or modifier-only one.\n */\nexport function parseShortcut(text: string): Shortcut {\n  const tokens = text\n    .split(\"+\")\n    .map((token) => token.trim())\n    .filter(Boolean);\n  if (tokens.length === 0) throw new Error(\"Enter a shortcut.\");\n\n  const shortcut: Shortcut = { key: \"\", mod: false, ctrl: false, alt: false, shift: false };\n  for (const token of tokens) {\n    const canonical = canonicalKey(token);\n    if (canonical === \"Mod\") shortcut.mod = true;\n    else if (canonical === \"Ctrl\") shortcut.ctrl = true;\n    else if (canonical === \"Alt\") shortcut.alt = true;\n    else if (canonical === \"Shift\") shortcut.shift = true;\n    else if (shortcut.key) throw new Error(`\"${text}\" has two keys; a shortcut has one.`);\n    else shortcut.key = canonical;\n  }\n  if (!shortcut.key) throw new Error(`\"${text}\" is only modifiers; it needs a key.`);\n  return shortcut;\n}\n\n/** The stored, platform-neutral form. Modifiers in a fixed order, so equal shortcuts are equal strings. */\nexport function serializeShortcut(shortcut: Shortcut): string {\n  const parts: string[] = [];\n  if (shortcut.mod) parts.push(\"Mod\");\n  if (shortcut.ctrl) parts.push(\"Ctrl\");\n  if (shortcut.alt) parts.push(\"Alt\");\n  if (shortcut.shift) parts.push(\"Shift\");\n  parts.push(shortcut.key);\n  return parts.join(\"+\");\n}\n\nexport function shortcutsEqual(a: Shortcut, b: Shortcut): boolean {\n  return serializeShortcut(a) === serializeShortcut(b);\n}\n\ninterface KeyLike {\n  key: string;\n  code?: string;\n  metaKey: boolean;\n  ctrlKey: boolean;\n  altKey: boolean;\n  shiftKey: boolean;\n}\n\n/**\n * The shortcut a keydown amounts to, or null while only modifiers are held.\n *\n * Letters and digits come from `code`, not `key`: with Shift or Option held,\n * `key` is `K`, `˚` or `∆` depending on the layout and the platform, and a\n * shortcut recorded as Option-∆ is one nobody can read back. `Mod` is Meta\n * on a Mac and Control elsewhere; the other one, when held, is kept as\n * itself.\n */\nexport function shortcutFromKey(event: KeyLike, platform: Platform): Shortcut | null {\n  if (MODIFIER_KEYS.has(event.key)) return null;\n\n  let key: string;\n  const code = event.code ?? \"\";\n  if (/^Key[A-Z]$/.test(code)) key = code.slice(3);\n  else if (/^Digit[0-9]$/.test(code)) key = code.slice(5);\n  else key = canonicalKey(event.key);\n\n  const mac = platform === \"mac\";\n  return {\n    key,\n    mod: mac ? event.metaKey : event.ctrlKey,\n    ctrl: mac ? event.ctrlKey : false,\n    alt: event.altKey,\n    shift: event.shiftKey,\n  };\n}\n\n/** Printable keys need a modifier: a bare K as a shortcut fires while someone types a sentence. */\nexport function needsModifier(shortcut: Shortcut): boolean {\n  const printable = shortcut.key.length === 1 || shortcut.key === \"Space\";\n  return printable && !shortcut.mod && !shortcut.ctrl && !shortcut.alt;\n}\n\nconst MAC_SYMBOLS: Record<string, string> = {\n  Mod: \"⌘\",\n  Ctrl: \"⌃\",\n  Alt: \"⌥\",\n  Shift: \"⇧\",\n  Enter: \"↩\",\n  Backspace: \"⌫\",\n  Delete: \"⌦\",\n  ArrowUp: \"↑\",\n  ArrowDown: \"↓\",\n  ArrowLeft: \"←\",\n  ArrowRight: \"→\",\n  Escape: \"⎋\",\n  Space: \"Space\",\n};\n\nconst SPOKEN: Record<Platform, Record<string, string>> = {\n  mac: { Mod: \"Command\", Ctrl: \"Control\", Alt: \"Option\", Shift: \"Shift\" },\n  other: { Mod: \"Control\", Ctrl: \"Control\", Alt: \"Alt\", Shift: \"Shift\" },\n};\n\n/** The parts to draw, in order: symbols on a Mac, words elsewhere. */\nexport function shortcutParts(shortcut: Shortcut, platform: Platform): string[] {\n  const parts: string[] = [];\n  const name = (modifier: string) =>\n    platform === \"mac\"\n      ? (MAC_SYMBOLS[modifier] ?? modifier)\n      : (SPOKEN.other[modifier] ?? modifier);\n  if (shortcut.mod) parts.push(name(\"Mod\"));\n  if (shortcut.ctrl && !(platform === \"other\" && shortcut.mod)) parts.push(name(\"Ctrl\"));\n  if (shortcut.alt) parts.push(name(\"Alt\"));\n  if (shortcut.shift) parts.push(name(\"Shift\"));\n  parts.push(platform === \"mac\" ? (MAC_SYMBOLS[shortcut.key] ?? shortcut.key) : shortcut.key);\n  return parts;\n}\n\n/** \"⌘⇧K\" on a Mac, \"Ctrl+Shift+K\" elsewhere. */\nexport function formatShortcut(shortcut: Shortcut, platform: Platform): string {\n  return shortcutParts(shortcut, platform).join(platform === \"mac\" ? \"\" : \"+\");\n}\n\n/** \"Command Shift K\" — words, for the ear, whatever the screen shows. */\nexport function describeShortcut(shortcut: Shortcut, platform: Platform): string {\n  const words: string[] = [];\n  const spoken = SPOKEN[platform];\n  if (shortcut.mod) words.push(spoken.Mod ?? \"Mod\");\n  if (shortcut.ctrl && !(platform === \"other\" && shortcut.mod))\n    words.push(spoken.Ctrl ?? \"Ctrl\");\n  if (shortcut.alt) words.push(spoken.Alt ?? \"Alt\");\n  if (shortcut.shift) words.push(spoken.Shift ?? \"Shift\");\n  words.push(shortcut.key.replace(/^Arrow/, \"Arrow \"));\n  return words.join(\" \");\n}\n\n/** Whether the browser is on a Mac, by the only signal it gives. */\nexport function detectPlatform(): Platform {\n  if (typeof navigator === \"undefined\") return \"other\";\n  const hint =\n    (navigator as { userAgentData?: { platform?: string } }).userAgentData?.platform ??\n    navigator.platform;\n  return /mac|iphone|ipad|ipod/i.test(hint) ? \"mac\" : \"other\";\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,47 @@
+import { Platform } from "./shortcut-model.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/components/shortcut-recorder/shortcut-recorder.d.ts
+/**
+ * Press the keys you want.
+ *
+ * Linear, Slack, VS Code, Figma and Superhuman each wrote one, and no
+ * component library ships the recorder — only the `<kbd>` that displays the
+ * result. The recorder is the hard part: a button that, when pressed, stops
+ * being a button and starts being a keyboard listener, and has to come back.
+ *
+ * Three things it does that a listener bolted onto an input does not. It
+ * reads letters from `code`, not `key`, so Option-K records as Option K and
+ * not as the ˚ the Mac produced. It stores `Mod`, not Command or Control,
+ * so a binding saved on one machine is right on the other. And it refuses a
+ * bare printable key by saying so, because a shortcut that fires while
+ * someone types a sentence is the bug every app that allowed it later fixed.
+ *
+ * Tab and Escape are never recorded: Tab leaves, Escape cancels, and a
+ * recorder that captures both is a keyboard trap with a nice label. A
+ * chord that another command already uses is said, with that command's
+ * name, and applied only if the person says to use it anyway.
+ */
+interface TakenShortcut {
+  /** Stored form: `Mod+K`. */
+  shortcut: string;
+  /** What it does: "Search". */
+  label: string;
+}
+interface ShortcutRecorderProps extends Omit<ComponentPropsWithRef<"div">, "onChange" | "defaultValue"> {
+  /** What the shortcut triggers: "Open search". Names the control. */
+  label: string;
+  /** Stored form, `Mod+Shift+K`, or null for none. Controlled. */
+  value?: string | null;
+  defaultValue?: string | null;
+  onChange?: (value: string | null) => void;
+  /** Shortcuts other commands already use. A clash is said, and applied only on request. */
+  taken?: TakenShortcut[];
+  /** Mac shows ⌘⇧K; everything else shows Ctrl+Shift+K. Detected if omitted. */
+  platform?: Platform;
+  /** Printable keys need a modifier. On by default, for the reason in the source. */
+  requireModifier?: boolean;
+}
+declare function ShortcutRecorder({ className, label, value: valueProp, defaultValue, onChange, taken, platform: platformProp, requireModifier, ...props }: ShortcutRecorderProps): import("react").JSX.Element;
+//#endregion
+export { ShortcutRecorder, ShortcutRecorderProps, TakenShortcut };
+//# sourceMappingURL=shortcut-recorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shortcut-recorder.d.ts","names":[],"sources":["../../../src/components/shortcut-recorder/shortcut-recorder.tsx"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;UA+CiB;;EAEf;;EAEA;;UAGe,8BAA8B,KAC7C;;EAIA;;EAEA;EACA;EACA,YAAY;;EAEZ,QAAQ;;EAER,WAAW;;EAEX;;iBAUc,mBACd,WACA,OACA,OAAO,WACP,cACA,UACA,OACA,UAAU,cACV,oBACG,SACF,wCAAqB,IAAA"}