rift-ds 1.14.0 → 1.16.0

package/README.md

@@ -13,7 +13,7 @@ An open source React design system built for AI products and coding agents: comp
 
 ## Why Rift DS
 
-- **<!-- component-count -->159<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. Every one forwards a ref and your own attributes to its element, state you can own works controlled or uncontrolled (a modal opens when your app says so, by design), and every word a component writes has a prop you can localise. The build checks the first two on every component, and the words wherever they sit in markup. React and React DOM are the only required peer dependencies.
+- **<!-- component-count -->162<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. Every one forwards a ref and your own attributes to its element, state you can own works controlled or uncontrolled (a modal opens when your app says so, by design), and every word a component writes has a prop you can localise. The build checks the first two on every component, and the words wherever they sit in markup. React and React DOM are the only required peer dependencies.
 - **AI patterns, the whole chat and templates, ready to use.** Composer, streaming chat thread, tool calls, reasoning and thread panel are in the box, the complete AI chat ships assembled as one widget that one command scaffolds, and the docs site has complete template screens built from them.
 - **Fully themeable.** The shipped themes are complete looks to start from, each in light and dark. One `data-brand` attribute applies a theme, and a few CSS overrides make your own.
 - **Ready for coding agents.** One command installs the agent skills, and a public MCP endpoint serves every component's props, so your agent builds with the library as it actually is. No key, no account.
@@ -91,7 +91,7 @@ Every component's prop contract is also plain markdown (append `.md` to its docs
 
 ## Theming
 
-Theming is CSS custom properties; there is no configuration API and no provider (one exception: wrap your tree in `ToastProvider` if, and only if, you use the toast queue via `useToast`). Complete looks ship as generated stylesheets: import the aggregate once and one attribute rethemes everything, light and dark, typefaces included (each preset self-hosts its faces).
+Theming is CSS custom properties; there is no configuration API and no theme provider (one required exception: wrap your tree in `ToastProvider` if, and only if, you use the toast queue via `useToast`). Two providers are optional: `LinkProvider` hands every component your router's link, and `LocaleProvider` sets the locale numbers, dates and calendars are written in (`en-US` without it, never the browser's). Key bindings go through `useShortcut` from `rift-ds/behaviors/shortcuts`, the listener the components use, so a shortcut stays out of text fields and open overlays. For a right-to-left language, set `dir="rtl"` on `<html>`: every component lays itself out from it. Complete looks ship as generated stylesheets: import the aggregate once and one attribute rethemes everything, light and dark, typefaces included (each preset self-hosts its faces).
 
 ```tsx
 import 'rift-ds/tokens/presets/presets.css';
@@ -107,13 +107,13 @@ import 'rift-ds/tokens/presets/presets.css';
 
 ## Components
 
-<!-- component-count -->159<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
+<!-- component-count -->162<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
 
 <details>
 <summary>The full list</summary>
 
 <!-- component-list:start -->
-Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Artifact card · Artifact panel · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bento tile · Bento tile art · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Command palette trigger · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Question card · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Table toolbar · Tabs · Tag input · Textarea · Theme picker · Theme toggle · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
+Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Artifact card · Artifact panel · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bento tile · Bento tile art · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Command palette trigger · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mega menu · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Progressive blur · Prompt suggestions · Prose · Question card · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Site header · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Table toolbar · Tabs · Tag input · Textarea · Theme picker · Theme toggle · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
 <!-- component-list:end -->
 
 </details>

package/behaviors/LinkProvider.d.ts

@@ -27,6 +27,9 @@ export interface LinkProviderProps {
  * read a provider and take the prop alone (design.md's Components intro
  * names them, and scripts/validate-component-contract.mjs keeps them off
  * the provider).
+ *
+ * Published as the `./behaviors/LinkProvider` subpath because consumers
+ * mount it; with the scroll lock it is one of only two behaviors that are.
  */
 export declare function LinkProvider({ linkComponent, children }: LinkProviderProps): React.JSX.Element;
 /**

package/behaviors/LocaleProvider.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+export interface LocaleProviderProps {
+    /**
+     * The BCP 47 locale every rift-ds component under this provider formats
+     * numbers, dates and calendars in, such as `de-DE`. Named like the
+     * instance prop it stands in for.
+     */
+    locale: string;
+    /** The part of the app it applies to, usually the whole app. */
+    children?: React.ReactNode;
+}
+/**
+ * Sets the locale for every client-rendered rift-ds component below it that
+ * formats a number or a date, or lays out a calendar: grouping and decimal
+ * marks, month and weekday names, the first day of the week, and the
+ * 12- or 24-hour clock. A component's own `locale` prop wins over it. The
+ * components that can render on the server cannot read a provider and take
+ * the prop alone. Words stay props of their own: the locale formats, it
+ * never translates.
+ */
+export declare function LocaleProvider({ locale, children }: LocaleProviderProps): React.JSX.Element;
+/**
+ * The locale to format in: the component's own `locale` prop, else the
+ * nearest LocaleProvider's, else `en-US`. Never the runtime's default, so
+ * the server and the browser always agree.
+ */
+export declare function useLocale(override?: string): string;

package/behaviors/LocaleProvider.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+import { DEFAULT_LOCALE } from "./locale.js";
+const LocaleContext = createContext(null);
+function LocaleProvider({ locale, children }) {
+  return /* @__PURE__ */ jsx(LocaleContext.Provider, { value: locale, children });
+}
+function useLocale(override) {
+  const provided = useContext(LocaleContext);
+  return override ?? provided ?? DEFAULT_LOCALE;
+}
+export {
+  LocaleProvider,
+  useLocale
+};

package/behaviors/direction.css

@@ -0,0 +1,19 @@
+/* ============================================
+   READING DIRECTION SIGN
+   `--ds-inline-sign` is 1 in a left-to-right context and -1 in a
+   right-to-left one, read from the element's own direction (`:dir()`),
+   so a `dir` attribute anywhere up the tree sets it. A component that
+   moves along the inline axis (a slide-in, a thumb, a shimmer's sweep, an
+   optical nudge) multiplies its offset by it, always with the fallback
+   `var(--ds-inline-sign, 1)`, and imports this file. Logical properties
+   cover placement; this covers motion, which CSS has no logical form for.
+   design.md's "Layout follows the reading direction" owns the contract.
+   ============================================ */
+
+:dir(ltr) {
+  --ds-inline-sign: 1;
+}
+
+:dir(rtl) {
+  --ds-inline-sign: -1;
+}

package/behaviors/direction.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The reading direction, for the code that moves along the inline axis:
+ * arrow keys, drags and anything placed in pixels. Stylesheets read it
+ * through logical properties and `--ds-inline-sign` (direction.css); script
+ * reads it here, from the element itself at the moment it acts, so a `dir`
+ * attribute anywhere up the tree applies and a change to it needs no
+ * re-render. No React and no browser API at import time, so a server
+ * component can import it too. design.md's "Layout follows the reading
+ * direction" owns the contract.
+ */
+/** Whether `element` lays out right to left. False on the server and for a missing element. */
+export declare function isRtl(element: Element | null | undefined): boolean;
+/** 1 when `element` reads left to right, -1 when it reads right to left: the sign to multiply a horizontal pointer delta by. */
+export declare const inlineSign: (element: Element | null | undefined) => 1 | -1;
+/**
+ * An arrow key along the inline axis as a step through the reading order:
+ * `1` for the next item (ArrowRight in English, ArrowLeft in Arabic), `-1`
+ * for the previous one, and 0 for any other key.
+ */
+export declare function inlineStep(key: string, element: Element | null | undefined): -1 | 0 | 1;
+/**
+ * The Material Symbols ligatures that point along the reading direction and
+ * so mirror in a right-to-left context: a "next" chevron points left in
+ * Arabic. A component that draws one adds the `ds-mirror-rtl` class (the
+ * rule lives in src/fonts/material-symbols.css, which every icon imports);
+ * `mirrorClass` decides it for an icon a consumer passes by name.
+ */
+export declare const DIRECTIONAL_ICONS: Set<string>;
+/** Whether the icon named `name` points along the reading direction and should mirror in a right-to-left context. */
+export declare const mirrorsInRtl: (name: unknown) => boolean;
+/**
+ * A key as it would be pressed in a left-to-right layout: ArrowLeft and
+ * ArrowRight swap when `element` reads right to left, and every other key
+ * passes through. A component that steps along the inline axis switches on
+ * this instead of the raw key, so "the next tab" is ArrowRight in English
+ * and ArrowLeft in Arabic with no second branch.
+ */
+export declare function logicalArrowKey(key: string, element: Element | null | undefined): string;
+/** `ds-mirror-rtl` when the icon named `name` mirrors in a right-to-left context, else an empty string, for a className. */
+export declare const mirrorClass: (name: unknown) => string;

package/behaviors/direction.js

@@ -0,0 +1,56 @@
+function isRtl(element) {
+  if (!element || typeof getComputedStyle === "undefined") return false;
+  return getComputedStyle(element).direction === "rtl";
+}
+const inlineSign = (element) => isRtl(element) ? -1 : 1;
+const DIRECTIONAL_ICONS = /* @__PURE__ */ new Set([
+  "chevron_left",
+  "chevron_right",
+  "arrow_back",
+  "arrow_forward",
+  "arrow_back_ios",
+  "arrow_forward_ios",
+  "arrow_back_ios_new",
+  "first_page",
+  "last_page",
+  "keyboard_arrow_left",
+  "keyboard_arrow_right",
+  "keyboard_double_arrow_left",
+  "keyboard_double_arrow_right",
+  "navigate_before",
+  "navigate_next",
+  "east",
+  "west",
+  "trending_flat",
+  "subdirectory_arrow_right",
+  "subdirectory_arrow_left",
+  "reply",
+  "forward",
+  "undo",
+  "redo",
+  "logout",
+  "login",
+  "send",
+  "menu_open",
+  "format_indent_increase",
+  "format_indent_decrease",
+  "view_sidebar",
+  "left_panel_open",
+  "left_panel_close",
+  "right_panel_open",
+  "right_panel_close"
+]);
+const mirrorsInRtl = (name) => typeof name === "string" && DIRECTIONAL_ICONS.has(name);
+function logicalArrowKey(key, element) {
+  if (key !== "ArrowLeft" && key !== "ArrowRight" || !isRtl(element)) return key;
+  return key === "ArrowLeft" ? "ArrowRight" : "ArrowLeft";
+}
+const mirrorClass = (name) => mirrorsInRtl(name) ? "ds-mirror-rtl" : "";
+export {
+  DIRECTIONAL_ICONS,
+  inlineSign,
+  isRtl,
+  logicalArrowKey,
+  mirrorClass,
+  mirrorsInRtl
+};

package/behaviors/focusable.d.ts

@@ -2,7 +2,8 @@
  * Shared focusability queries for the overlay behavior layer.
  *
  * One home for the selector the modal components previously each carried a
- * copy of. Plain DOM utilities — no React, safe to import anywhere.
+ * copy of. Plain DOM utilities — no React, safe to import anywhere. It
+ * serves non-overlay keyboard work too: Toolbar's arrow-key model reads it.
  */
 /** Everything a focus trap must cycle through. */
 export declare const FOCUSABLE = "button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";

package/behaviors/locale.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Locale data every formatting component shares. Server-safe: no React and
+ * no browser API, so a component that renders from a Server Component can
+ * import it too. The client half (the provider and the hook) is
+ * LocaleProvider.tsx.
+ *
+ * The rule it carries: a component never formats in the runtime's default
+ * locale. The server and the browser can disagree on it, which prints
+ * `1,234` on one and `1.234` on the other and breaks hydration, and a
+ * consumer could not choose it. Every number, date and calendar convention
+ * a component prints is resolved from a locale the consumer can set, which
+ * falls back to DEFAULT_LOCALE. scripts/validate-locale-formatting.mjs
+ * enforces it.
+ */
+/** The locale a component formats in when neither its `locale` prop nor a LocaleProvider sets one. */
+export declare const DEFAULT_LOCALE = "en-US";
+/** A day of the week as `Date.getDay()` numbers it: 0 is Sunday, 6 is Saturday. */
+export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * The first day of the week in `locale`, as a `Date.getDay()` number:
+ * Sunday (0) in en-US, Monday (1) in de-DE, Saturday (6) in ar-EG. Read
+ * from the runtime's CLDR week data where it has it, else from the region.
+ */
+export declare function weekStartOf(locale: string): Weekday;
+/** A Sunday-first list of seven, reordered to start on `start`. */
+export declare function rotateWeek<T>(sundayFirst: readonly T[], start: Weekday): T[];
+/** How many days `day` sits after the week's first day: 0 for the first column, 6 for the last. */
+export declare const weekdayOffset: (day: number, start: Weekday) => number;
+/** The seven weekday names in `locale`, Sunday first, at the given width. */
+export declare function weekdayNamesIn(locale: string, width: 'long' | 'short' | 'narrow'): string[];
+/** Whether `locale` is written in English, the language every built-in label defaults to. */
+export declare function isEnglish(locale: string): boolean;
+/** Whether `locale` writes times on a 12-hour clock (en-US) rather than a 24-hour one (en-GB, de-DE). */
+export declare function uses12HourClock(locale: string): boolean;
+/**
+ * A number as `locale` writes it, grouped and with its own decimal mark:
+ * `1,234.5` in en-US, `1.234,5` in de-DE. Formats are cached per locale.
+ */
+export declare function formatNumber(value: number, locale: string): string;
+/**
+ * A number on a chart's value axis as `locale` writes it, grouped only from
+ * five digits up (`12,000` but `2024`), so a tick that happens to be a year
+ * never reads as a quantity.
+ */
+export declare function formatAxisNumber(value: number, locale: string): string;
+/** A whole percentage, given as 0 to 100, as `locale` writes it: `64%` in en-US, `٦٤٪` in ar-EG, `64 %` in de-DE. */
+export declare function formatPercent(percent: number, locale: string): string;

package/behaviors/locale.js

@@ -0,0 +1,87 @@
+const DEFAULT_LOCALE = "en-US";
+const SUNDAY_FIRST = new Set(
+  "AG AS BD BR BS BT BW BZ CA CN CO DM DO ET GT GU HK HN ID IL IN JM JP KE KH KR LA MH MM MO MT MX MZ NI NP PA PE PH PK PR PT PY SA SG SV TH TT TW UM US VE VI WS YE ZA ZW".split(" ")
+);
+const SATURDAY_FIRST = new Set("AE AF BH DJ DZ EG IQ IR JO KW LY OM QA SD SY".split(" "));
+const weekStartCache = /* @__PURE__ */ new Map();
+function weekStartOf(locale) {
+  const cached = weekStartCache.get(locale);
+  if (cached !== void 0) return cached;
+  let start = 1;
+  try {
+    const intlLocale = new Intl.Locale(locale);
+    const info = intlLocale.getWeekInfo?.() ?? intlLocale.weekInfo;
+    if (info) {
+      start = info.firstDay % 7;
+    } else {
+      const region = intlLocale.maximize().region ?? "";
+      start = SUNDAY_FIRST.has(region) ? 0 : SATURDAY_FIRST.has(region) ? 6 : 1;
+    }
+  } catch {
+    start = 1;
+  }
+  weekStartCache.set(locale, start);
+  return start;
+}
+function rotateWeek(sundayFirst, start) {
+  return [...sundayFirst.slice(start), ...sundayFirst.slice(0, start)];
+}
+const weekdayOffset = (day, start) => (day - start + 7) % 7;
+function weekdayNamesIn(locale, width) {
+  const format = new Intl.DateTimeFormat(locale, { weekday: width, timeZone: "UTC" });
+  return Array.from({ length: 7 }, (_, day) => format.format(Date.UTC(2023, 0, 1 + day)));
+}
+function isEnglish(locale) {
+  try {
+    return new Intl.Locale(locale).language === "en";
+  } catch {
+    return false;
+  }
+}
+function uses12HourClock(locale) {
+  const cycle = new Intl.DateTimeFormat(locale, { hour: "numeric" }).resolvedOptions().hourCycle;
+  return cycle === "h11" || cycle === "h12";
+}
+const numberFormats = /* @__PURE__ */ new Map();
+function formatNumber(value, locale) {
+  let format = numberFormats.get(locale);
+  if (!format) {
+    format = new Intl.NumberFormat(locale, { maximumFractionDigits: 3 });
+    numberFormats.set(locale, format);
+  }
+  return format.format(value);
+}
+const axisFormats = /* @__PURE__ */ new Map();
+function formatAxisNumber(value, locale) {
+  let format = axisFormats.get(locale);
+  if (!format) {
+    format = new Intl.NumberFormat(locale, {
+      maximumFractionDigits: 3,
+      // 'min2' is CLDR's grouping for short numbers; the type lags the spec.
+      useGrouping: "min2"
+    });
+    axisFormats.set(locale, format);
+  }
+  return format.format(value);
+}
+const percentFormats = /* @__PURE__ */ new Map();
+function formatPercent(percent, locale) {
+  let format = percentFormats.get(locale);
+  if (!format) {
+    format = new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 0 });
+    percentFormats.set(locale, format);
+  }
+  return format.format(percent / 100);
+}
+export {
+  DEFAULT_LOCALE,
+  formatAxisNumber,
+  formatNumber,
+  formatPercent,
+  isEnglish,
+  rotateWeek,
+  uses12HourClock,
+  weekStartOf,
+  weekdayNamesIn,
+  weekdayOffset
+};

package/behaviors/shortcut-keys.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The shortcut grammar and how a shortcut is drawn, with no React and no
+ * browser API, so a component that renders from a Server Component can
+ * draw or announce a shortcut too. The listener and the hooks are
+ * shortcuts.ts, which owns the grammar's description.
+ */
+/** A shortcut in the grammar above, such as `mod+k`, `shift+?` or `g i`. */
+export type Shortcut = string;
+/** The platform a shortcut is read and drawn for: `apple` maps `mod` to ⌘, `other` to Ctrl. */
+export type ShortcutPlatform = 'apple' | 'other';
+/** The legends a shortcut is drawn with, by modifier or key name. Merged over the platform's defaults. */
+export type ShortcutKeyLabels = Partial<Record<string, string>>;
+/** One step of a shortcut: its key and the modifiers held with it. */
+export type Step = {
+    key: string;
+    mod: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+};
+export declare const KEY_ALIASES: Record<string, string>;
+/** A shortcut's steps, parsed once. A step written `ctrl++` would be ambiguous, so `plus` names the key. */
+export declare const parseShortcut: (shortcut: Shortcut) => Step[];
+/** The platform this code runs on, read from the browser. `other` on the server. */
+export declare const detectPlatform: () => ShortcutPlatform;
+/**
+ * A shortcut as keycap legends, one array per step: `mod+shift+p` is
+ * `[['⇧', '⌘', 'P']]` on a Mac and `[['Ctrl', 'Shift', 'P']]` elsewhere.
+ * `labels` replaces any legend, such as `{ ctrl: 'Strg' }` for a German
+ * keyboard.
+ */
+export declare function shortcutKeys(shortcut: Shortcut, platform: ShortcutPlatform, labels?: ShortcutKeyLabels): string[][];
+/**
+ * A shortcut as one line of text, for a menu row: `⇧⌘P` on a Mac and
+ * `Ctrl+Shift+P` elsewhere, the steps of a sequence spaced apart.
+ */
+export declare function formatShortcut(shortcut: Shortcut, platform: ShortcutPlatform, labels?: ShortcutKeyLabels): string;
+/**
+ * A single-step shortcut as an `aria-keyshortcuts` value (`Meta+K` on a Mac,
+ * `Control+K` elsewhere). A sequence has no ARIA form, so it gives undefined.
+ */
+export declare function shortcutAria(shortcut: Shortcut, platform: ShortcutPlatform): string | undefined;
+/**
+ * A shortcut as an `aria-keyshortcuts` value for both platforms at once
+ * (`Meta+K Control+K` for `mod+k`), for markup that renders on the server or
+ * before the platform is known. Undefined for a sequence.
+ */
+export declare function shortcutAriaAnyPlatform(shortcut: Shortcut): string | undefined;

package/behaviors/shortcut-keys.js

@@ -0,0 +1,129 @@
+const KEY_ALIASES = {
+  esc: "escape",
+  return: "enter",
+  up: "arrowup",
+  down: "arrowdown",
+  left: "arrowleft",
+  right: "arrowright",
+  del: "delete",
+  plus: "+",
+  " ": "space",
+  cmd: "meta",
+  command: "meta",
+  option: "alt",
+  control: "ctrl"
+};
+const MODIFIERS = /* @__PURE__ */ new Set(["mod", "ctrl", "meta", "alt", "shift"]);
+const parseStep = (text) => {
+  const step = { key: "", mod: false, ctrl: false, meta: false, alt: false, shift: false };
+  for (const raw of text.toLowerCase().split("+")) {
+    const part = KEY_ALIASES[raw] ?? raw;
+    if (MODIFIERS.has(part)) step[part] = true;
+    else step.key = part;
+  }
+  return step;
+};
+const parseShortcut = (shortcut) => shortcut.trim().split(/\s+/).filter(Boolean).map(parseStep);
+const detectPlatform = () => {
+  if (typeof navigator === "undefined") return "other";
+  const nav = navigator;
+  const name = nav.userAgentData?.platform || nav.platform || nav.userAgent || "";
+  return /mac|iphone|ipad|ipod/i.test(name) ? "apple" : "other";
+};
+const APPLE_LABELS = {
+  mod: "⌘",
+  meta: "⌘",
+  ctrl: "⌃",
+  alt: "⌥",
+  shift: "⇧",
+  enter: "↩",
+  escape: "Esc",
+  backspace: "⌫",
+  delete: "⌦",
+  tab: "⇥",
+  space: "Space"
+};
+const OTHER_LABELS = {
+  mod: "Ctrl",
+  meta: "Meta",
+  ctrl: "Ctrl",
+  alt: "Alt",
+  shift: "Shift",
+  enter: "Enter",
+  escape: "Esc",
+  backspace: "Backspace",
+  delete: "Del",
+  tab: "Tab",
+  space: "Space"
+};
+const SHARED_LABELS = {
+  arrowup: "↑",
+  arrowdown: "↓",
+  arrowleft: "←",
+  arrowright: "→",
+  home: "Home",
+  end: "End",
+  pageup: "PgUp",
+  pagedown: "PgDn"
+};
+const APPLE_ORDER = ["ctrl", "alt", "shift", "mod", "meta"];
+const OTHER_ORDER = ["mod", "ctrl", "meta", "alt", "shift"];
+function shortcutKeys(shortcut, platform, labels = {}) {
+  const table = { ...SHARED_LABELS, ...platform === "apple" ? APPLE_LABELS : OTHER_LABELS };
+  const legend = (name) => labels[name] ?? table[name] ?? (/^f\d+$/.test(name) ? name.toUpperCase() : name.length === 1 ? name.toUpperCase() : name);
+  return parseShortcut(shortcut).map((step) => {
+    const order = platform === "apple" ? APPLE_ORDER : OTHER_ORDER;
+    const mods = order.filter((mod) => step[mod]);
+    const unique = mods.filter((mod, i) => !mods.slice(0, i).some((m) => legend(m) === legend(mod)));
+    return [...unique.map(legend), legend(step.key)];
+  });
+}
+function formatShortcut(shortcut, platform, labels = {}) {
+  return shortcutKeys(shortcut, platform, labels).map((keys) => keys.join(platform === "apple" ? "" : "+")).join(" ");
+}
+const ARIA_KEYS = {
+  ctrl: "Control",
+  meta: "Meta",
+  alt: "Alt",
+  shift: "Shift",
+  escape: "Escape",
+  enter: "Enter",
+  space: "Space",
+  tab: "Tab",
+  backspace: "Backspace",
+  delete: "Delete",
+  arrowup: "ArrowUp",
+  arrowdown: "ArrowDown",
+  arrowleft: "ArrowLeft",
+  arrowright: "ArrowRight",
+  home: "Home",
+  end: "End",
+  pageup: "PageUp",
+  pagedown: "PageDown"
+};
+function shortcutAria(shortcut, platform) {
+  const steps = parseShortcut(shortcut);
+  if (steps.length !== 1) return void 0;
+  const [step] = steps;
+  const names = [
+    step.ctrl || step.mod && platform === "other" ? "Control" : null,
+    step.meta || step.mod && platform === "apple" ? "Meta" : null,
+    step.alt ? "Alt" : null,
+    step.shift ? "Shift" : null,
+    ARIA_KEYS[step.key] ?? (step.key.length === 1 ? step.key.toUpperCase() : step.key)
+  ].filter(Boolean);
+  return names.join("+");
+}
+function shortcutAriaAnyPlatform(shortcut) {
+  const forms = [shortcutAria(shortcut, "apple"), shortcutAria(shortcut, "other")].filter(Boolean);
+  return forms.length > 0 ? [...new Set(forms)].join(" ") : void 0;
+}
+export {
+  KEY_ALIASES,
+  detectPlatform,
+  formatShortcut,
+  parseShortcut,
+  shortcutAria,
+  shortcutAriaAnyPlatform,
+  shortcutKeys
+};

package/behaviors/shortcuts.d.ts

@@ -0,0 +1,75 @@
+import { Shortcut, ShortcutPlatform } from './shortcut-keys';
+export { detectPlatform, formatShortcut, parseShortcut, shortcutAria, shortcutKeys, type Shortcut, type ShortcutKeyLabels, type ShortcutPlatform, } from './shortcut-keys';
+/**
+ * Keyboard shortcuts: the one document keydown listener every app-level key
+ * binding goes through, the grammar a shortcut is written in, and the way it
+ * is drawn on each platform.
+ *
+ * A shortcut is a string: steps separated by spaces, each step modifiers and
+ * a key joined by `+`. `mod+k` is ⌘K on Apple platforms and Ctrl+K
+ * elsewhere; `shift+?`, `alt+arrowup`, `escape`; `g i` is G then I. Keys are
+ * a character or a name (enter, escape, space, tab, backspace, delete, the
+ * arrows, home, end, pageup, pagedown, f1 to f12, plus).
+ *
+ * Who hears a key, in order:
+ * - Nothing does while an IME is composing, or once a component has handled
+ *   the key itself (`event.preventDefault()`), so a list's own arrow keys or
+ *   an input's own Escape never also fire a shortcut. Escape is the layer
+ *   stack's while any overlay is open (useLayer), so an `escape` shortcut
+ *   is for closing something that is not a library overlay.
+ * - Nothing does while focus is in a text field, unless the shortcut opts in
+ *   with `allowInInput` (a palette's Cmd+K should work from a search box).
+ * - A `global` shortcut always does.
+ * - A `scope`d shortcut does while focus is inside its element, or while
+ *   nothing has focus and the element sits on the surface in front (the open
+ *   modal, else the page). Lightbox's arrows are scoped to its panel.
+ * - Any other shortcut belongs to the page: it does only while no modal is
+ *   open and focus is not inside an open overlay (a menu, a popover), the
+ *   same topmost-only rule the layer stack applies to Escape.
+ * When several match, the longest sequence wins, then the shortcut
+ * registered last. A matched key's default is prevented.
+ *
+ * Exactly one document listener exists while any shortcut is registered, and
+ * none otherwise. scripts/validate-overlay-listeners.mjs holds every other
+ * document key listener in the library and the site to this module.
+ */
+export interface ShortcutOptions {
+    /** What the shortcut does, in a few words, for a help list built from `useRegisteredShortcuts`. */
+    description?: string;
+    /** The heading a help list files the shortcut under, such as "Navigation". */
+    group?: string;
+    /** Whether the shortcut is live. Default true. */
+    enabled?: boolean;
+    /** Fires only while focus is inside this element (see the module's rules). */
+    scope?: React.RefObject<HTMLElement | null>;
+    /** Fires whatever is open or focused, outside text fields. Default false. */
+    global?: boolean;
+    /** Fires while focus is in a text field too. Default false. */
+    allowInInput?: boolean;
+}
+/**
+ * The platform shortcuts are drawn for. The server and the first client
+ * render both say `other`, then the client settles on its own, so drawing a
+ * shortcut never breaks hydration.
+ */
+export declare function usePlatform(): ShortcutPlatform;
+/**
+ * Binds a shortcut (or several, as an array) to `handler` while the component
+ * is mounted and `enabled` is not false. The handler and options are read at
+ * key time, so passing new ones each render never re-registers the shortcut.
+ */
+export declare function useShortcut(shortcut: Shortcut | Shortcut[], handler: (event: KeyboardEvent) => void, options?: ShortcutOptions): void;
+/** A live shortcut as a help list reads it. */
+export interface RegisteredShortcut {
+    /** The shortcuts that run it, in the grammar. */
+    shortcuts: Shortcut[];
+    /** What it does, from the binding's `description`. */
+    description: string;
+    /** Its heading, from the binding's `group`. */
+    group?: string;
+}
+/**
+ * Every live shortcut that has a description, in registration order, for a
+ * "keyboard shortcuts" help dialog. Updates as shortcuts mount and unmount.
+ */
+export declare function useRegisteredShortcuts(): RegisteredShortcut[];