@inklu/keys 1.4.1 → 2.0.1

package/README.md

@@ -2,6 +2,8 @@
 
 Keyboard shortcut management for the web. Built on TanStack Hotkeys, `@inklu/keys` provides a registry, scopes, conflict detection, and screen-reader-ready shortcuts.
 
+Docs: [inklu-keys.vercel.app](https://inklu-keys.vercel.app) · For agents: [llms.txt](https://inklu-keys.vercel.app/llms.txt) · Agent skill: `npx skills add nkurunziza-saddy/inklu --skill inklu-keys`
+
 ```bash
 pnpm add @inklu/keys
 ```
@@ -43,7 +45,7 @@ function App() {
 }
 
 function ShortcutButton() {
-	// Get live shortcut state
+	// Live state for the primary binding: `tokens` is one string per key
 	const shortcut = useShortcut(commands, "palette.open");
 
 	return (
@@ -52,7 +54,7 @@ function ShortcutButton() {
 			aria-keyshortcuts={shortcut.aria || undefined}
 		>
 			Open Palette
-			{shortcut.tokens[0]?.map((token, i) => (
+			{shortcut.tokens.map((token, i) => (
 				<kbd key={i}>{token}</kbd>
 			))}
 		</button>
@@ -97,6 +99,8 @@ commands.keymap.set("palette.open", null); // unbind
 commands.keymap.reset("palette.open"); // reset to default
 ```
 
+`set` replaces the command's keys outright; setting exactly the default forgets the override instead. `add` layers on top of the default rather than copying it, so if a later release of your app changes the default, the user gets the new one and keeps the keys they added.
+
 To rebind a command you did not define — one a package shipped — pass `bindings` when creating the registry. An unknown id is a compile error, and `reset` returns here rather than to the definition's `keys`:
 
 ```ts
@@ -118,18 +122,167 @@ const rebind = useRebind(commands, "palette.open");
 <button onClick={rebind.start}>{rebind.recording ? "Press keys…" : rebind.display}</button>;
 ```
 
+To build your own capture UI without React, use `createRebinder`:
+
+```ts
+import { createRebinder } from "@inklu/keys";
+
+const rebinder = createRebinder(commands, "palette.open", {
+	mode: "chord", // or "sequence": Enter or `commit()` finishes it
+	rejectConflicts: true, // don't apply a binding another command uses
+	onRecord: (binding, conflicts) => {},
+});
+rebinder.subscribe(() => render(rebinder.state)); // { recording, binding, steps, conflicts }
+rebinder.start(); // Escape cancels, Backspace unbinds
+```
+
+While recording, every other command is silenced — including `"*"` ones — so the keys being recorded never run anything.
+
+## 5. Conflicts
+
+`commands.conflicts(binding, { scope, ignore })` lists commands in overlapping scopes whose bindings collide with `binding`. Each result has a `kind`:
+
+- `"exact"` — the same keys. Only one command runs (see above).
+- `"prefix"` — one binding starts the other, like `G` against `seq("G", "I")`. These cannot be arbitrated: pressing `G` runs the chord, and continuing with `I` runs the sequence too.
+
+In development, both kinds are also reported with `console.warn` when commands are defined or added.
+
+## 6. Persistence and SSR
+
+```ts
+createCommands(definitions, {
+	persist: {
+		storage: () => (typeof window === "undefined" ? null : localStorage),
+		key: "my-app.keys",
+	},
+});
+```
+
+Only user overrides are stored — never defaults. `keymap.export()` / `keymap.import(json)` move them between devices. The stored data carries a `version`, and a release that doesn't recognise a version leaves it alone instead of misreading it. Data from releases before the version field still loads.
+
+While mounted, the registry follows edits other tabs make to the same storage key, so a shortcut rebound in one tab applies in every open tab, and a stale tab can't overwrite it on its next save.
+
+The registry is safe to create at module scope and render on the server:
+
+- Persisted overrides load on the first `mount()`, not at creation, so the server render and the client's first render match. Subscribers (and every hook) are notified when they arrive. Calling `keymap.set/add/reset` before mount loads them first, so an early edit never overwrites stored ones.
+- Before mount, shortcuts render in the non-Apple form (`Ctrl+K`); after mount they switch to the detected platform (`⌘K`). Pass `platform` to pin it.
+- Nothing listens for keys until `mount()` (or `useMountCommands`).
+
+## 7. Inputs and events
+
+`ignoreInputs` on a command decides whether it fires while focus is in a text input, textarea, select or contenteditable. When omitted, chords holding `Control` or `Meta` (so any `Mod+…`) and bare `Escape` still fire there; bare keys, `Shift`/`Alt` chords and sequences starting with one are ignored, so typing is never hijacked. Keydowns that are part of an IME composition never trigger commands.
+
+A command calls `preventDefault()` only when it actually runs; one that is disabled, out of scope, guarded or outranked leaves the event alone. Opt out per command with `preventDefault: false`. Propagation is never stopped. `run` may be async: nothing awaits it, but a rejection reaches `onError`.
+
+`commands.whyNotRun(id)` explains a shortcut that did not fire: `"disabled"`, `"out-of-scope"`, `"guarded"`, `"unknown"`, or `null` when it would run.
+
+## 8. Runtime commands
+
+```tsx
+// Registered while the component is mounted; the latest `run` and `when` are always used.
+useRegisterCommand(commands, "editor.format", {
+	title: "Format document",
+	keys: "Shift+Alt+F",
+	scope: "editor",
+	run: () => format(),
+});
+
+// Outside React: `add` returns a handle. Adding an existing id stacks over it until disposed.
+const handle = commands.add("editor.format", { title: "Format", run: format });
+handle.dispose();
+```
+
+## 9. Sequence progress
+
+```tsx
+const pending = usePendingSequences(commands); // [{ id, matched, total, remaining }]
+// e.g. show "G → …" while the user is halfway through `G then I`
+```
+
+`commands.pending()` / `commands.subscribePending()` are the non-React equivalents.
+
+## 10. Command palette
+
+Definitions can carry what a palette needs to list and find them, and `matchCommands` does the filtering:
+
+```ts
+createCommands({
+	"doc.find": {
+		title: "Find in document",
+		description: "Search the open document",
+		group: "Document", // heading to list it under
+		keywords: ["search", "lookup"], // extra search terms
+		keys: "Mod+F",
+		run: openFind,
+	},
+	"palette.close": { title: "Close palette", hidden: true, keys: "Escape", run: close },
+});
+```
+
+```tsx
+import { matchCommands } from "@inklu/keys";
+
+const results = matchCommands(useCommands(commands), query);
+```
+
+Every word of the query must match the title, description, group, keywords, id or displayed shortcut. Titles starting with the query come first, then titles containing it, then everything else, each in list order. `hidden` commands never match; they still run and still appear in `list()`.
+
+## 11. Without React: data attributes
+
+```ts
+import { observe } from "@inklu/keys/attributes";
+
+const stop = observe(commands); // or observe(commands, { root: element })
+```
+
+```html
+<button data-command="palette.open">Search <kbd data-command-keys="palette.open"></kbd></button>
+```
+
+Clicking an element with `data-command` runs that command (`source: "dom"`), unless the element or an ancestor has `aria-disabled="true"` or another handler already called `preventDefault()`. Elements with `data-command-keys` get the shortcut as text, and `data-command` elements get `aria-keyshortcuts`; both stay current across rebinds and DOM changes.
+
 ## API Summary
 
 - `createCommands(definitions, options)` - creates the registry
-  - `options`: `{ bindings, platform, target, persist, display, onRun, onError }`
-- `useMountCommands(commands)` - starts listening
-- `useShortcut(commands, id)` - gets display tokens and aria for rendering
-- `useScope(commands, name, active, { exclusive })` - isolates command execution
-- `useRebind(commands, id)` - records user shortcuts
+  - `options`: `{ bindings, platform, target, persist, display, singleKeyShortcuts, onRun, onError }`
+  - `commands.run(id)`, `canRun(id)`, `whyNotRun(id)`, `setEnabled(id, enabled)`, `add(id, definition)`, `remove(id)`
+  - `commands.pushScope(name, { exclusive, strict })`, `conflicts(binding, options)`, `display(id)`, `tokens(id)`
+  - `commands.keymap`: `get`, `set`, `add`, `reset`, `export`, `import`
+  - `commands.setSingleKeyShortcuts(enabled)`, `commands.singleKeyShortcuts`
+- `createRebinder(commands, id, options)` - framework-agnostic shortcut recording
+- `observe(commands, { root })` from `@inklu/keys/attributes` - declarative DOM wiring
+- `matchCommands(list, query)` - palette filtering over `title`, `description`, `group`, `keywords`
+- `formatBinding`, `bindingTokens`, `ariaKeyShortcuts`, `spokenBinding`, `validateBinding`, `isSingleKeyBinding`, `seq`
+- React (`@inklu/keys/react`):
+  - `useMountCommands(commands)` - starts listening
+  - `useCommands(commands)`, `useCommand(commands, id)` - live command snapshots
+  - `useShortcut(commands, id)` - `{ display, tokens, aria, spoken }` for the primary binding
+  - `useScope(commands, name, active, { exclusive, strict })` - isolates command execution
+  - `useRegisterCommand(commands, id, definition)` - component-scoped commands
+  - `useRebind(commands, id, options)` - records user shortcuts
+  - `usePendingSequences(commands)` - half-typed sequences
+  - `useHeldKeys()`, `useHeldKeyCodes()`, `useKeyHold(key)` - live key state
+
+Inside `run`, the context's `commands` is typed with the registry's own ids, so `commands.run("typo")` is a compile error.
 
 ## Accessibility
 
-Every command carries an `aria` string. Apply it to `aria-keyshortcuts` so screen readers announce the exact key sequence.
+Every command carries an `aria` string for the `aria-keyshortcuts` attribute. It lists chords only: the attribute separates alternatives with spaces, so it cannot express a sequence. Every command also carries `spoken` — `"Control+K"`, or `"G then I"` for a sequence — for visually hidden text or `aria-description`, which is how a sequence gets announced:
+
+```tsx
+const { aria, spoken } = useShortcut(commands, "nav.inbox");
+<button aria-keyshortcuts={aria || undefined} aria-description={spoken || undefined}>
+	Inbox
+</button>;
+```
+
+WCAG 2.1.4 (Character Key Shortcuts) requires that users can turn off shortcuts made of printable characters without a modifier — `?`, `G then I` — because speech input and stray keypresses trigger them. Expose a setting wired to:
+
+```ts
+commands.setSingleKeyShortcuts(false); // or createCommands(defs, { singleKeyShortcuts: false })
+```
+
+While off, those bindings neither fire nor appear in `display`, `tokens`, `aria` or `spoken`; chords with `Control`, `Alt` or `Meta` and keys like `Escape` or `F1` keep working. Users can also remap any shortcut with `useRebind`.
 
 ## License
 

package/dist/{attributes-O6bXNKT9.d.ts → attributes-DotLr2MW.d.mts}

@@ -41,10 +41,28 @@ interface CommandContext<Id extends string = string> {
    */
   readonly commands: Commands<Id>;
 }
-/** Definition of a command and its default configuration. */
-interface CommandDefinition {
+/**
+ * Definition of a command and its default configuration.
+ *
+ * `Id` is the registry's id union. `createCommands` fills it in, so
+ * `commands.run(...)` inside a handler is checked against the registry's own
+ * ids; a definition written on its own defaults to plain `string`.
+ */
+interface CommandDefinition<Id extends string = string> {
   /** Human-readable title. */
   title: string;
+  /** Longer explanation, such as a palette's secondary line or a tooltip. */
+  description?: string;
+  /** Heading to list the command under in a palette or shortcut sheet, e.g. `"Navigate"`. */
+  group?: string;
+  /** Extra search terms `matchCommands` checks besides the title, e.g. `["find", "search"]`. */
+  keywords?: ReadonlyArray<string>;
+  /**
+   * Leave the command out of `matchCommands` — for commands that only make
+   * sense from their key, like a palette's own Close. It still runs and
+   * still appears in `list()`. Defaults to `false`.
+   */
+  hidden?: boolean;
   /** Default key binding(s). */
   keys?: BindingInput;
   /** Scope required for this command to fire. Omit for global, or `"*"` to bypass exclusive scopes. */
@@ -53,21 +71,38 @@ interface CommandDefinition {
   when?: () => boolean;
   /** Whether the command is enabled. Defaults to `true`. */
   enabled?: boolean;
-  /** Prevent default event behavior when run. Defaults to `true`. */
+  /**
+   * Prevent default event behavior when run. Defaults to `true`. For a
+   * sequence this also covers each step as it matches, so a first step such
+   * as `Mod+K` does not trigger the browser's own shortcut on the way.
+   */
   preventDefault?: boolean;
-  /** Whether to ignore events in form inputs/textareas/contenteditable. */
+  /**
+   * Whether to ignore key events from text inputs, textareas and
+   * contenteditable elements. When omitted, TanStack Hotkeys decides per
+   * binding: chords holding Control or Meta (so `Mod+…`) and bare `Escape`
+   * still fire inside inputs, while everything else — bare keys, Shift/Alt
+   * chords, and sequences starting with one — is ignored there, so typing is
+   * never hijacked.
+   */
   ignoreInputs?: boolean;
   /** Require key release before firing again (prevents auto-repeat). Defaults to `false`. */
   requireReset?: boolean;
   /** Timeout in milliseconds between sequence steps. Defaults to `1000`. */
   sequenceTimeout?: number;
   /** Handler executed when the command runs. */
-  run: (context: CommandContext) => void | Promise<void>;
+  run: (context: CommandContext<Id>) => void | Promise<void>;
 }
 /** Resolved command snapshot including effective bindings, display tokens, and reachability. */
 interface Command<Id extends string = string> {
   readonly id: Id;
   readonly title: string;
+  readonly description?: string;
+  readonly group?: string;
+  /** Extra search terms; empty when the definition gave none. */
+  readonly keywords: ReadonlyArray<string>;
+  /** Whether `matchCommands` leaves the command out. */
+  readonly hidden: boolean;
   readonly scope?: string;
   /** Active bindings after user overrides. */
   readonly bindings: ReadonlyArray<Binding>;
@@ -75,8 +110,18 @@ interface Command<Id extends string = string> {
   readonly display: ReadonlyArray<string>;
   /** Formatted tokens per binding for rendering `<kbd>` elements. */
   readonly tokens: ReadonlyArray<ReadonlyArray<string>>;
-  /** Value for `aria-keyshortcuts` attribute. */
+  /**
+   * Value for the `aria-keyshortcuts` attribute. Only chords appear here: the
+   * attribute separates alternatives with spaces, so it cannot express a
+   * sequence. Use `spoken` to announce those.
+   */
   readonly aria: string;
+  /**
+   * Every binding phrased for a screen reader, alternatives joined by
+   * `" or "` — e.g. `"Control+K"` or `"G then I"`. Suited to visually hidden
+   * text or `aria-description`, and the only accessible form of a sequence.
+   */
+  readonly spoken: string;
   /** Whether the command is enabled. */
   readonly enabled: boolean;
   /** Whether the command is enabled and in an active scope. */
@@ -99,12 +144,20 @@ interface KeymapPersistence {
   /** Getter returning the storage implementation lazily. */
   storage: () => KeymapStorage | null;
 }
-/** Details of a conflict between commands with identical bindings in overlapping scopes. */
+/**
+ * How two bindings collide: `"exact"` when they are the same keys, `"prefix"`
+ * when one is the start of the other — chord `G` against `G then I` — so the
+ * shorter one fires on the way to the longer one.
+ */
+type ConflictKind = "exact" | "prefix";
+/** Details of a conflict between commands whose bindings collide in overlapping scopes. */
 interface Conflict<Id extends string = string> {
   /** ID of the conflicting command. */
   readonly id: Id;
-  /** Shared binding. */
+  /** The conflicting command's binding. */
   readonly binding: Binding;
+  /** Whether the bindings are identical or one is a prefix of the other. */
+  readonly kind: ConflictKind;
   /** Formatted display representation of the binding. */
   readonly display: string;
   /** Overlapping scope where conflict occurs, if any. */
@@ -114,34 +167,66 @@ interface Conflict<Id extends string = string> {
 interface ScopeOptions {
   /** Shadow commands in lower scopes, including global commands. */
   exclusive?: boolean;
+  /**
+   * Also shadow `"*"` commands, which otherwise survive every barrier.
+   * Implies `exclusive`. Meant for surfaces that must own the whole keyboard,
+   * such as recording a new shortcut.
+   */
+  strict?: boolean;
 }
 //#endregion
 //#region src/display.d.ts
 /** Display options for formatting hotkeys. */
-type DisplayOptions = FormatDisplayOptions;
+type DisplayOptions = Omit<FormatDisplayOptions, "parts">;
 /** Formats a binding for display on the target platform (e.g. `⌘K` or `Ctrl+K`). */
 declare function formatBinding(binding: Binding, options?: DisplayOptions): string;
 /** Splits a binding into display tokens for rendering `<kbd>` elements. */
 declare function bindingTokens(binding: Binding, options?: DisplayOptions): Array<string>;
+/**
+ * Phrases a binding for a screen reader: `"Control+K"` for a chord,
+ * `"G then I"` for a sequence. `aria-keyshortcuts` cannot express a sequence
+ * (a space there means "or"), so this is how a sequence gets announced — put it
+ * in visually hidden text or `aria-description`.
+ */
+declare function spokenBinding(binding: Binding, platform?: Platform): string;
 /** Generates an `aria-keyshortcuts` attribute string for a binding. */
 declare function ariaKeyShortcuts(binding: Binding, platform?: Platform): string;
 //#endregion
 //#region src/keymap.d.ts
-/** Persisted map of command IDs to serialized bindings. */
-type SerializedKeymap = Record<string, Array<SerializedBinding>>;
+/** One command's stored override: an array replaces the default, `{ add }` extends it. */
+type SerializedOverride = Array<SerializedBinding> | {
+  add: Array<SerializedBinding>;
+};
+/** Persisted user overrides, keyed by command id. */
+interface SerializedKeymap {
+  /** Format version, so a release can skip a format it does not know instead of misreading it. */
+  version: 1;
+  overrides: Record<string, SerializedOverride>;
+}
 /** Keymap interface for querying, modifying, and persisting keybindings. */
 interface CommandKeymap<Id extends string = string> {
-  /** Active bindings in effect (user overrides if present, otherwise defaults). */
+  /** Active bindings in effect: the default, with any user override applied. */
   get(id: Id | (string & {})): ReadonlyArray<Binding>;
-  /** Rebinds a command. Passing `null` unbinds it without restoring the default. */
+  /**
+   * Replaces a command's bindings. Passing `null` unbinds it without
+   * restoring the default; passing exactly the default forgets the override,
+   * so the command follows the default again if the app changes it.
+   */
   set(id: Id | (string & {}), input: BindingInput | null): void;
-  /** Appends an additional binding to a command. */
+  /**
+   * Appends an additional binding. On a command the user has not replaced,
+   * it is stored on top of the default rather than as a copy of it, so a
+   * default the app changes later still applies alongside the added keys.
+   */
   add(id: Id | (string & {}), input: BindingInput): void;
   /** Resets user overrides back to defaults for a specific command or all commands. */
   reset(id?: Id | (string & {})): void;
   /** Exports user overrides as JSON-serializable data. */
   export(): SerializedKeymap;
-  /** Imports user overrides, replacing current overrides and saving to storage. */
+  /**
+   * Imports user overrides, replacing current overrides and saving to
+   * storage. Accepts `export()` output from this and earlier releases.
+   */
   import(data: Json): void;
 }
 //#endregion
@@ -170,8 +255,21 @@ interface CommandsOptions<Id extends string = string> {
   platform?: Platform;
   /** Target element for key events. Defaults to `document`. */
   target?: HTMLElement | Document | Window | null;
-  /** Persistence configuration for user keymap overrides. */
+  /**
+   * Persistence configuration for user keymap overrides. Overrides are read
+   * on the first `mount()` rather than at creation, so the server render and
+   * the client's first render agree and hydration never mismatches; the
+   * registry notifies subscribers once they load.
+   */
   persist?: KeymapPersistence;
+  /**
+   * Whether single-key shortcuts — bindings where every step is a printable
+   * character with no Control, Alt or Meta, such as `?` or `G then I` — are
+   * active. Defaults to `true`. WCAG 2.1.4 requires a way to turn these off
+   * for speech-input and motor-impaired users; wire a setting to
+   * `commands.setSingleKeyShortcuts()`.
+   */
+  singleKeyShortcuts?: boolean;
   /** Display options for rendering shortcuts. */
   display?: DisplayOptions;
   /**
@@ -184,9 +282,12 @@ interface CommandsOptions<Id extends string = string> {
    * });
    * ```
    */
-  onRun?: (context: CommandContext) => void;
-  /** Error handler called when a command execution fails. Defaults to `console.error`. */
-  onError?: (error: Error, context: CommandContext) => void;
+  onRun?: (context: CommandContext<Id>) => void;
+  /**
+   * Error handler called when a command, its `when()` guard, or `onRun`
+   * throws. Defaults to `console.error`.
+   */
+  onError?: (error: Error, context: CommandContext<Id>) => void;
 }
 /** Options passed when manually running a command. */
 interface RunOptions {
@@ -232,6 +333,16 @@ interface Commands<Id extends string = string> {
   get(id: Id | (string & {})): Command<Id> | undefined;
   /** Returns all registered commands in definition order. */
   list(): ReadonlyArray<Command<Id>>;
+  /**
+   * The command list as the server renders it: the commands passed to
+   * `createCommands` with their default bindings (after `options.bindings`),
+   * formatted for the server platform — no runtime `add()`, scope, user
+   * override or `setEnabled` applied. Referentially stable. This is the
+   * `getServerSnapshot` the React hooks hand `useSyncExternalStore`, so a
+   * subtree that hydrates after the client state moved on still matches the
+   * server's HTML.
+   */
+  serverList(): ReadonlyArray<Command<Id>>;
   /** Runs a command by ID. Returns `true` if executed. */
   run(id: Id, options?: RunOptions): boolean;
   /** Checks whether a command can run currently. */
@@ -241,12 +352,16 @@ interface Commands<Id extends string = string> {
   /** Enables or disables a command. */
   setEnabled(id: Id | (string & {}), enabled: boolean): void;
   /** Registers a command at runtime. */
-  add(id: Id | (string & {}), definition: CommandDefinition): CommandHandle;
+  add(id: Id | (string & {}), definition: CommandDefinition<Id>): CommandHandle;
   /** Removes a command registration. */
   remove(id: Id | (string & {})): void;
   /** Activates a scope until the returned disposal function is called. */
   pushScope(name: string, options?: ScopeOptions): () => void;
-  /** Finds conflicting commands that share the given binding in overlapping scopes. */
+  /**
+   * Finds commands in overlapping scopes whose bindings collide with the given
+   * one — the same keys (`kind: "exact"`), or one a prefix of the other, like
+   * chord `G` against `G then I` (`kind: "prefix"`).
+   */
   conflicts(binding: BindingInput, options?: ConflictOptions<Id>): Array<Conflict<Id>>;
   /** Formats a command's primary binding for display. */
   display(id: Id | (string & {})): string;
@@ -260,6 +375,10 @@ interface Commands<Id extends string = string> {
   mount(): () => void;
   /** Subscribes to registry changes. Returns an unsubscribe function. */
   subscribe(listener: () => void): () => void;
+  /** Whether single-key shortcuts are active. See `CommandsOptions.singleKeyShortcuts`. */
+  readonly singleKeyShortcuts: boolean;
+  /** Turns single-key shortcuts on or off for every command (WCAG 2.1.4). */
+  setSingleKeyShortcuts(enabled: boolean): void;
   /** Tears down listeners and clears all command registrations. */
   destroy(): void;
 }
@@ -282,7 +401,7 @@ interface Commands<Id extends string = string> {
  * });
  * ```
  */
-declare function createCommands<const T extends { [K in keyof T]: CommandDefinition & Record<Exclude<keyof T[K], keyof CommandDefinition>, never>; }>(definitions: T, options?: CommandsOptions<Extract<keyof T, string>>): Commands<Extract<keyof T, string>>;
+declare function createCommands<Id extends string>(definitions: { [K in Id]: CommandDefinition<Id>; }, options?: CommandsOptions<NoInfer<Id>>): Commands<Id>;
 /**
  * Extracts command ID union from a Commands registry type.
  *
@@ -304,4 +423,4 @@ interface ObserveOptions {
  */
 declare function observe<Id extends string>(registry: Commands<Id>, options?: ObserveOptions): () => void;
 //#endregion
-export { Platform as A, CommandDefinition as C, HotkeySequence as D, Hotkey$1 as E, SequenceBinding as M, SerializedBinding as N, KeymapPersistence as O, CommandContext as S, Conflict as T, formatBinding as _, Commands as a, Chord as b, PendingSequence as c, createCommands as d, CommandKeymap as f, bindingTokens as g, ariaKeyShortcuts as h, CommandId as i, ScopeOptions as j, KeymapStorage as k, RunBlockReason as l, DisplayOptions as m, observe as n, CommandsOptions as o, SerializedKeymap as p, CommandHandle as r, ConflictOptions as s, ObserveOptions as t, RunOptions as u, Binding as v, CommandSource as w, Command as x, BindingInput as y };
+export { HotkeySequence as A, Command as C, Conflict as D, CommandSource as E, SequenceBinding as F, SerializedBinding as I, KeymapStorage as M, Platform as N, ConflictKind as O, ScopeOptions as P, Chord as S, CommandDefinition as T, bindingTokens as _, Commands as a, Binding as b, PendingSequence as c, createCommands as d, CommandKeymap as f, ariaKeyShortcuts as g, DisplayOptions as h, CommandId as i, KeymapPersistence as j, Hotkey$1 as k, RunBlockReason as l, SerializedOverride as m, observe as n, CommandsOptions as o, SerializedKeymap as p, CommandHandle as r, ConflictOptions as s, ObserveOptions as t, RunOptions as u, formatBinding as v, CommandContext as w, BindingInput as x, spokenBinding as y };

package/dist/{attributes.d.ts → attributes.d.mts}

@@ -1,2 +1,2 @@
-import { n as observe, t as ObserveOptions } from "./attributes-O6bXNKT9.js";
+import { n as observe, t as ObserveOptions } from "./attributes-DotLr2MW.mjs";
 export { ObserveOptions, observe };

package/dist/{attributes.js → attributes.mjs}

@@ -8,15 +8,19 @@ function observe(registry, options = {}) {
 	if (!("document" in globalThis)) return () => {};
 	const root = options.root ?? document;
 	const onClick = (event) => {
+		if (event.defaultPrevented) return;
 		const target = event.target;
 		if (!(target instanceof Element)) return;
-		const id = target.closest(`[${COMMAND_ATTRIBUTE}]`)?.getAttribute(COMMAND_ATTRIBUTE);
+		const element = target.closest(`[${COMMAND_ATTRIBUTE}]`);
+		const id = element?.getAttribute(COMMAND_ATTRIBUTE);
 		if (!id) return;
+		if (element?.closest("[aria-disabled=\"true\"]")) return;
 		registry.run(id, {
 			source: "dom",
 			event
 		});
 	};
+	const labelled = /* @__PURE__ */ new WeakSet();
 	const paintElement = (element) => {
 		const keysId = element.getAttribute(KEYS_ATTRIBUTE);
 		if (keysId) {
@@ -24,10 +28,13 @@ function observe(registry, options = {}) {
 			if (element.textContent !== display) element.textContent = display;
 		}
 		const commandId = element.getAttribute(COMMAND_ATTRIBUTE);
-		if (commandId) {
-			const aria = registry.get(commandId)?.aria ?? "";
-			if (aria) element.setAttribute("aria-keyshortcuts", aria);
-			else element.removeAttribute("aria-keyshortcuts");
+		const aria = commandId ? registry.get(commandId)?.aria ?? "" : "";
+		if (aria) {
+			if (element.getAttribute("aria-keyshortcuts") !== aria) element.setAttribute("aria-keyshortcuts", aria);
+			labelled.add(element);
+		} else if (commandId || labelled.has(element)) {
+			element.removeAttribute("aria-keyshortcuts");
+			labelled.delete(element);
 		}
 	};
 	const paintWithin = (scope) => {

package/dist/{index-B5iiRwCy.d.ts → index-BTgscYdI.d.mts}

@@ -1,4 +1,4 @@
-import { M as SequenceBinding, T as Conflict, a as Commands, b as Chord, v as Binding } from "./attributes-O6bXNKT9.js";
+import { C as Command, D as Conflict, F as SequenceBinding, N as Platform, S as Chord, a as Commands, b as Binding } from "./attributes-DotLr2MW.mjs";
 import { Hotkey } from "@tanstack/hotkeys";
 //#region src/bindings.d.ts
 /**
@@ -10,6 +10,13 @@ import { Hotkey } from "@tanstack/hotkeys";
  * ```
  */
 declare function seq(...steps: Array<Hotkey>): SequenceBinding;
+/**
+ * Whether every step of a binding is a single printable character with no
+ * Control, Alt or Meta — the "character key shortcuts" WCAG 2.1.4 lets users
+ * turn off, since speech input and stray keypresses trigger them by accident.
+ * Shift does not count as a modifier here: `Shift+A` still types a character.
+ */
+declare function isSingleKeyBinding(binding: Binding, platform?: Platform): boolean;
 /** Validation result for a hotkey binding. */
 interface BindingValidation {
   readonly valid: boolean;
@@ -90,4 +97,20 @@ declare function createRebinder<Id extends string>(registry: Commands<Id>, id: I
 /** Wildcard scope identifier for commands that remain active across exclusive scopes. */
 declare const ALWAYS_SCOPE = "*";
 //#endregion
-export { Rebinder as a, seq as c, RebindState as i, validateBinding as l, RebindMode as n, createRebinder as o, RebindOptions as r, BindingValidation as s, ALWAYS_SCOPE as t };
+//#region src/search.d.ts
+/**
+ * Filters commands for a search query, as a command palette does, leaving
+ * out `hidden` ones. Every word of the query must appear somewhere in the
+ * command — title, description, group, keywords, id or displayed shortcut —
+ * in any order. Title matches come first: titles starting with the query,
+ * then titles containing every word, then the rest; each tier keeps the
+ * list's own order. An empty query returns every visible command.
+ *
+ * @example
+ * ```ts
+ * const results = matchCommands(commands.list(), "go inbox");
+ * ```
+ */
+declare function matchCommands<Id extends string>(commands: ReadonlyArray<Command<Id>>, query: string): Array<Command<Id>>;
+//#endregion
+export { RebindState as a, BindingValidation as c, validateBinding as d, RebindOptions as i, isSingleKeyBinding as l, ALWAYS_SCOPE as n, Rebinder as o, RebindMode as r, createRebinder as s, matchCommands as t, seq as u };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { A as HotkeySequence, C as Command, D as Conflict, E as CommandSource, F as SequenceBinding, I as SerializedBinding, M as KeymapStorage, N as Platform, O as ConflictKind, P as ScopeOptions, S as Chord, T as CommandDefinition, _ as bindingTokens, a as Commands, b as Binding, c as PendingSequence, d as createCommands, f as CommandKeymap, g as ariaKeyShortcuts, h as DisplayOptions, i as CommandId, j as KeymapPersistence, k as Hotkey, l as RunBlockReason, m as SerializedOverride, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as formatBinding, w as CommandContext, x as BindingInput, y as spokenBinding } from "./attributes-DotLr2MW.mjs";
+import { a as RebindState, c as BindingValidation, d as validateBinding, i as RebindOptions, l as isSingleKeyBinding, n as ALWAYS_SCOPE, o as Rebinder, r as RebindMode, s as createRebinder, t as matchCommands, u as seq } from "./index-BTgscYdI.mjs";
+export { ALWAYS_SCOPE, type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandle, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictKind, type ConflictOptions, type DisplayOptions, type Hotkey, type HotkeySequence, type KeymapPersistence, type KeymapStorage, type ObserveOptions, type PendingSequence, type Platform, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, type SerializedOverride, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, observe, seq, spokenBinding, validateBinding };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { observe } from "./attributes.mjs";
+import { a as ariaKeyShortcuts, c as spokenBinding, d as seq, i as createRebinder, n as createCommands, o as bindingTokens, p as validateBinding, r as ALWAYS_SCOPE, s as formatBinding, t as matchCommands, u as isSingleKeyBinding } from "./src-DgYjA1oS.mjs";
+export { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, observe, seq, spokenBinding, validateBinding };