@inklu/keys 2.0.1 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 [Your Name]
+Copyright (c) 2026 nkurunziza-saddy
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,16 @@
 # @inklu/keys
 
-Keyboard shortcut management for the web. Built on TanStack Hotkeys, `@inklu/keys` provides a registry, scopes, conflict detection, and screen-reader-ready shortcuts.
+`@inklu/keys` organises an app's keys and respects its boundaries. Every shortcut is a named command declared in one place, and exactly one command runs per keypress: the right one for where the user is.
 
-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`
+Three ideas, learned as you need them:
+
+- **Command**: something the app can do, with a title, default keys and the scope it is live in.
+- **Handler**: what the command does, attached from the component that owns the state.
+- **Keymap**: the keys, kept apart from the definition so users can rebind them.
+
+It has no dependencies, and listens with one `keydown` listener however many commands exist.
+
+Docs: [inklu.saddy.me/keys](https://inklu.saddy.me/keys) · For agents: [llms.txt](https://inklu.saddy.me/keys/llms.txt) · Agent skill: `npx skills add nkurunziza-saddy/inklu --skill inklu-keys`
 
 ```bash
 pnpm add @inklu/keys
@@ -10,22 +18,22 @@ pnpm add @inklu/keys
 
 ## 1. Define Commands
 
-A command is an addressable action. It has an id, title, and a handler.
+Declare every command in one module. Ids come from the object keys, so `commands.run("doc.save")` autocompletes and a typo is a type error.
+
+A chord is written modifiers first, then one key: `"Mod+Shift+S"`. The modifiers are `Mod`, `Control`, `Alt`, `Shift` and `Meta`, in that order, and `Mod` is Command on macOS and Control elsewhere. The key is the character or the name `KeyboardEvent.key` gives it (`"K"`, `"?"`, `"Escape"`, `"ArrowUp"`), or a physical key in brackets (`"[KeyK]"`) that stays put whatever the layout. Chords are typed, so a misspelling is a compile error. An array of chords means alternatives; a sequence is `seq("G", "I")`.
 
 ```ts
 // commands.ts
 import { createCommands, seq } from "@inklu/keys";
 
 export const commands = createCommands({
-	"palette.open": {
-		title: "Open command palette",
-		keys: "Mod+K",
-		run: () => setPaletteOpen(true),
-	},
+	"palette.open": { title: "Open command palette", keys: "Mod+K" },
+	"doc.save": { title: "Save document", keys: "Mod+S" },
 	"nav.inbox": {
 		title: "Go to inbox",
 		keys: seq("G", "I"), // press G, then I
-		run: () => navigate("/inbox"),
+		// Needs nothing a component owns, so it can live here.
+		run: () => router.navigate("/inbox"),
 	},
 });
 ```
@@ -35,7 +43,7 @@ export const commands = createCommands({
 Pass the registry explicitly to all hooks. There is no Context provider.
 
 ```tsx
-import { useCommands, useMountCommands, useShortcut } from "@inklu/keys/react";
+import { useCommandHandler, useMountCommands, useShortcut } from "@inklu/keys/react";
 import { commands } from "./commands";
 
 function App() {
@@ -44,6 +52,13 @@ function App() {
 	return <ShortcutButton />;
 }
 
+function Palette() {
+	const [open, setOpen] = useState(false);
+	// What the command does, attached where the state lives.
+	useCommandHandler(commands, "palette.open", () => setOpen(true));
+	return open ? <dialog open>…</dialog> : null;
+}
+
 function ShortcutButton() {
 	// Live state for the primary binding: `tokens` is one string per key
 	const shortcut = useShortcut(commands, "palette.open");
@@ -62,6 +77,21 @@ function ShortcutButton() {
 }
 ```
 
+### Handlers
+
+A command runs when its scope is open and it has a handler. A definition's own `run` is one; `useCommandHandler` attaches another for as long as a component is mounted, and the latest closure is always the one called.
+
+```tsx
+// The last argument switches the handler off: with nothing to save, Mod+S is not ours.
+useCommandHandler(commands, "doc.save", save, dirty);
+```
+
+- A command with no handler cannot run and leaves its key alone, so unmounting a feature switches its shortcuts off with it.
+- The most recently mounted handler wins. Unmounting hands the command back to the one before it, or to the definition's `run`. "Most recently" is the order React runs effects in, so of a parent and a child mounting in the same render, the parent's comes last and wins.
+- Outside React, `commands.handle(id, run)` does the same and returns a function that detaches.
+
+Switch a command off by its handler (`enabled`, or detaching) rather than with an early `return` inside it: only then does the key fall through to another command or the browser.
+
 ## 3. Scopes
 
 Use scopes to isolate commands when modals or dialogs are open.
@@ -70,23 +100,28 @@ Use scopes to isolate commands when modals or dialogs are open.
 import { useScope } from "@inklu/keys/react";
 
 function Dialog({ isOpen }) {
-	// When exclusive is true, commands outside this scope are silenced
+	// When exclusive is true, the keys of commands outside this scope are silenced
 	useScope(commands, "dialog", isOpen, { exclusive: true });
 
 	return isOpen ? <div className="dialog">...</div> : null;
 }
 ```
 
-`exclusive` is a barrier: it silences the whole app beneath it. To claim only a few keys, drop it and give those commands a `scope` instead — see below.
+`exclusive` is a barrier: it silences every key beneath it. To claim only a few keys, drop it and give those commands a `scope` instead — see below.
+
+A barrier claims the keyboard, not the command: `commands.run(id)` still works beneath one, so a palette can run what it lists while its own scope is open. A direct run only needs the command's own scope to be open. To make a button obey the same gate as its key, read `reachable` from `useCommand(commands, id)`.
 
 ### When two commands share a key
 
-Exactly one command runs per keypress. The winner is:
+Exactly one command runs per keypress. Among the commands that could take it, the winner is:
 
-1. The command in a named scope, over a global one. `"*"` counts as global here — it means "survives barriers", not "belongs to a region of the UI".
-2. Failing that, the one registered later. Registration order tracks mount order, so the most recently opened surface claims the key.
+1. A sequence being finished, over a chord on the same key.
+2. The command whose scope was opened most recently. Scopes track the surfaces on screen, so the dialog on top claims `Escape` before the panel beneath it, and any scoped command beats a global one. `"*"` counts as global here — it means "survives barriers", not "belongs to a region of the UI".
+3. Failing that, the one defined later.
 
-A winner whose `when()` currently returns `false` steps aside rather than swallowing the keypress. This is how `Escape` closes the dialog when one is open and the panel otherwise, without making the dialog `exclusive`. Two commands sharing a chord _in the same scope_ can never separate, so that case warns in development.
+Scopes rank in the order they were pushed. With `useScope` that is the order React runs effects in: a surface opened later ranks higher, but of a parent and a child that open in the same render, the child is pushed first. Open the inner surface after the outer one when their order matters.
+
+A command with no handler is never a candidate, so it steps aside rather than swallowing the keypress. This is how `Escape` closes the dialog when one is open and the panel otherwise, without making the dialog `exclusive`. Two commands sharing a chord _in the same scope_ can only be told apart by which has a handler, so that case warns in development.
 
 ## 4. Rebinding
 
@@ -136,7 +171,7 @@ rebinder.subscribe(() => render(rebinder.state)); // { recording, binding, steps
 rebinder.start(); // Escape cancels, Backspace unbinds
 ```
 
-While recording, every other command is silenced — including `"*"` ones — so the keys being recorded never run anything.
+While recording, every command is silenced — including `"*"` ones — so the keys being recorded never run anything. The rebinder is built on `commands.capture(onKey)`, which hands every keypress to `onKey(event, chord)` until the function it returns is called; use it directly for a recorder of your own.
 
 ## 5. Conflicts
 
@@ -145,7 +180,7 @@ While recording, every other command is silenced — including `"*"` ones — so
 - `"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.
+In development, both kinds are also reported with `console.warn` when the registry is created. The check is dropped from production builds.
 
 ## 6. Persistence and SSR
 
@@ -158,50 +193,34 @@ createCommands(definitions, {
 });
 ```
 
-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.
+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 ignores it instead of misreading it; the user's next change then replaces 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.
+- 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
+A command calls `preventDefault()` only when it actually runs, or when the key is a step on the way through one of its sequences; one that is unhandled, out of scope or outranked leaves the event alone. Opt out per command with `preventDefault: false`. Propagation is never stopped. A handler may be async: nothing awaits it, but a rejection reaches `onError`. Holding a chord down runs its command again on each auto-repeat.
 
-```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();
-```
+`commands.whyNotRun(id)` explains a command that would not run: `"unhandled"` (nothing has attached a handler), `"out-of-scope"` (its scope is not open), `"unknown"`, or `null` when it would run.
 
-## 9. Sequence progress
+## 8. 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.
+`commands.subscribePending()` / `commands.pending()` are the non-React equivalents. Progress is tracked only while something is subscribed, so `pending()` is empty otherwise.
 
-## 10. Command palette
+## 9. Command palette
 
 Definitions can carry what a palette needs to list and find them, and `matchCommands` does the filtering:
 
@@ -213,21 +232,22 @@ createCommands({
 		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 },
+	"palette.close": { title: "Close palette", hidden: true, scope: "palette", keys: "Escape" },
 });
 ```
 
 ```tsx
 import { matchCommands } from "@inklu/keys";
 
-const results = matchCommands(useCommands(commands), query);
+// List what can run right now: it has a handler and its scope is open.
+const runnable = useCommands(commands).filter((command) => commands.canRun(command.id));
+const results = matchCommands(runnable, 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
+## 10. Without React: data attributes
 
 ```ts
 import { observe } from "@inklu/keys/attributes";
@@ -245,25 +265,27 @@ Clicking an element with `data-command` runs that command (`source: "dom"`), unl
 
 - `createCommands(definitions, options)` - creates the registry
   - `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.run(id)`, `canRun(id)`, `whyNotRun(id)`, `handle(id, run)`
+  - `commands.get(id)`, `list()`, `subscribe(listener)`: snapshots with `display`, `tokens`, `aria`, `spoken`, `reachable`, `overridden`
+  - `commands.pushScope(name, { exclusive })`, `capture(onKey)`, `conflicts(binding, options)`, `mount()`, `destroy()`
+  - `commands.serverList()`: the list as the server rendered it, for a framework's hydration snapshot
   - `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`
+- `matchCommands(list, query)` - palette filtering over `title`, `description`, `group`, `keywords`, id and displayed shortcut
 - `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
+  - `useScope(commands, name, active, { exclusive })` - opens a scope while a component needs it
+  - `useCommandHandler(commands, id, run, enabled)` - what a command does while a component is mounted
   - `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.
+Inside a handler, the context's `commands` is typed with the registry's own ids, so `commands.run("typo")` is a compile error.
 
 ## Accessibility
 
@@ -284,6 +306,10 @@ commands.setSingleKeyShortcuts(false); // or createCommands(defs, { singleKeySho
 
 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`.
 
+## Acknowledgements
+
+The rules for matching a keypress across keyboard layouts follow the matcher in [TanStack Hotkeys](https://tanstack.com/hotkeys) (MIT), which earlier releases depended on.
+
 ## License
 
 MIT © nkurunziza-saddy

package/dist/attributes.d.mts

@@ -1,2 +1,11 @@
-import { n as observe, t as ObserveOptions } from "./attributes-DotLr2MW.mjs";
-export { ObserveOptions, observe };
+import { l as Commands } from "./types-QEXldPnL.mjs";
+//#region src/attributes.d.ts
+export interface ObserveOptions {
+  /** Root document or element to delegate from. Defaults to `document`. */
+  root?: Document | Element;
+}
+/**
+ * Wires a commands registry to DOM data attributes. Returns a cleanup function.
+ */
+export declare function observe<Id extends string>(registry: Commands<Id>, options?: ObserveOptions): () => void;
+//#endregion

package/dist/attributes.mjs

@@ -7,15 +7,16 @@ const KEYS_ATTRIBUTE = "data-command-keys";
 function observe(registry, options = {}) {
 	if (!("document" in globalThis)) return () => {};
 	const root = options.root ?? document;
+	const find = (id) => id ? registry.list().find((command) => command.id === id) : void 0;
 	const onClick = (event) => {
 		if (event.defaultPrevented) return;
 		const target = event.target;
 		if (!(target instanceof Element)) return;
 		const element = target.closest(`[${COMMAND_ATTRIBUTE}]`);
-		const id = element?.getAttribute(COMMAND_ATTRIBUTE);
-		if (!id) return;
+		const command = find(element?.getAttribute(COMMAND_ATTRIBUTE) ?? null);
+		if (!command) return;
 		if (element?.closest("[aria-disabled=\"true\"]")) return;
-		registry.run(id, {
+		registry.run(command.id, {
 			source: "dom",
 			event
 		});
@@ -24,15 +25,15 @@ function observe(registry, options = {}) {
 	const paintElement = (element) => {
 		const keysId = element.getAttribute(KEYS_ATTRIBUTE);
 		if (keysId) {
-			const display = registry.display(keysId);
+			const display = find(keysId)?.display[0] ?? "";
 			if (element.textContent !== display) element.textContent = display;
 		}
 		const commandId = element.getAttribute(COMMAND_ATTRIBUTE);
-		const aria = commandId ? registry.get(commandId)?.aria ?? "" : "";
+		const aria = find(commandId)?.aria ?? "";
 		if (aria) {
 			if (element.getAttribute("aria-keyshortcuts") !== aria) element.setAttribute("aria-keyshortcuts", aria);
 			labelled.add(element);
-		} else if (commandId || labelled.has(element)) {
+		} else if (labelled.has(element)) {
 			element.removeAttribute("aria-keyshortcuts");
 			labelled.delete(element);
 		}

package/dist/{index-BTgscYdI.d.mts → index-3d9f54ln.d.mts}

@@ -1,22 +1,20 @@
-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";
+import { C as SequenceBinding, D as Chord, a as CommandDefinition, d as Conflict, k as Platform, l as Commands, m as DisplayOptions, r as Command, t as Binding, u as CommandsOptions } from "./types-QEXldPnL.mjs";
 //#region src/bindings.d.ts
 /**
- * Creates a sequence binding from ordered hotkey steps.
+ * Creates a sequence binding from ordered chords.
  *
  * @example
  * ```ts
  * keys: seq("G", "I")
  * ```
  */
-declare function seq(...steps: Array<Hotkey>): SequenceBinding;
+declare function seq(...steps: Array<Chord>): 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;
+declare function isSingleKeyBinding(binding: Binding): boolean;
 /** Validation result for a hotkey binding. */
 interface BindingValidation {
   readonly valid: boolean;
@@ -26,6 +24,21 @@ interface BindingValidation {
 /** Validates a binding's syntax without logging warnings or errors. */
 declare function validateBinding(binding: Binding): BindingValidation;
 //#endregion
+//#region src/display.d.ts
+/** 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/rebind.d.ts
 /** Hotkey capture mode: single `"chord"` or multi-step `"sequence"`. */
 type RebindMode = "chord" | "sequence";
@@ -80,6 +93,9 @@ interface Rebinder<Id extends string = string> {
 }
 /**
  * Creates a rebinder instance for capturing and remapping a command's keys.
+ * While it records it holds the whole keyboard, so no command runs on the
+ * keys being pressed. Escape cancels, Backspace removes the shortcut (or the
+ * last step of a sequence), and Enter finishes a sequence.
  *
  * @example
  * ```ts
@@ -93,9 +109,33 @@ interface Rebinder<Id extends string = string> {
  */
 declare function createRebinder<Id extends string>(registry: Commands<Id>, id: Id, options?: RebindOptions<Id>): Rebinder<Id>;
 //#endregion
-//#region src/scopes.d.ts
-/** Wildcard scope identifier for commands that remain active across exclusive scopes. */
-declare const ALWAYS_SCOPE = "*";
+//#region src/registry.d.ts
+/**
+ * Creates a command registry.
+ *
+ * @example
+ * ```ts
+ * export const commands = createCommands({
+ *   "palette.open": { title: "Open command palette", keys: "Mod+K" },
+ *   "nav.inbox": {
+ *     title: "Go to inbox",
+ *     keys: seq("G", "I"),
+ *     run: () => router.navigate("/inbox"),
+ *   },
+ * });
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * export const commands = createCommands({ … });
+ * export type AppCommandId = CommandId<typeof commands>;
+ * ```
+ */
+type CommandId<C> = C extends Commands<infer Id> ? Id : never;
 //#endregion
 //#region src/search.d.ts
 /**
@@ -113,4 +153,4 @@ declare const ALWAYS_SCOPE = "*";
  */
 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 };
+export { RebindOptions as a, createRebinder as c, formatBinding as d, spokenBinding as f, validateBinding as g, seq as h, RebindMode as i, ariaKeyShortcuts as l, isSingleKeyBinding as m, CommandId as n, RebindState as o, BindingValidation as p, createCommands as r, Rebinder as s, matchCommands as t, bindingTokens as u };

package/dist/index.d.mts

@@ -1,3 +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 };
+import { C as SequenceBinding, D as Chord, E as SerializedOverride, O as Key, S as ScopeOptions, T as SerializedKeymap, _ as KeymapPersistence, a as CommandDefinition, b as RunBlockReason, c as CommandSource, d as Conflict, f as ConflictKind, g as KeyCapture, h as Json, i as CommandContext, k as Platform, l as Commands, m as DisplayOptions, n as BindingInput, o as CommandHandler, p as ConflictOptions, r as Command, s as CommandKeymap, t as Binding, u as CommandsOptions, v as KeymapStorage, w as SerializedBinding, x as RunOptions, y as PendingSequence } from "./types-QEXldPnL.mjs";
+import { a as RebindOptions, c as createRebinder, d as formatBinding, f as spokenBinding, g as validateBinding, h as seq, i as RebindMode, l as ariaKeyShortcuts, m as isSingleKeyBinding, n as CommandId, o as RebindState, p as BindingValidation, r as createCommands, s as Rebinder, t as matchCommands, u as bindingTokens } from "./index-3d9f54ln.mjs";
+export { type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandler, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictKind, type ConflictOptions, type DisplayOptions, type Json, type Key, type KeyCapture, type KeymapPersistence, type KeymapStorage, 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, seq, spokenBinding, validateBinding };

package/dist/index.mjs

@@ -1,3 +1,2 @@
-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 };
+import { a as bindingTokens, c as isSingleKeyBinding, i as ariaKeyShortcuts, l as seq, n as createCommands, o as formatBinding, r as createRebinder, s as spokenBinding, t as matchCommands, u as validateBinding } from "./src-B76YvObL.mjs";
+export { ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, seq, spokenBinding, validateBinding };

package/dist/react.d.mts

@@ -1,5 +1,5 @@
-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";
+import { C as SequenceBinding, D as Chord, E as SerializedOverride, O as Key, S as ScopeOptions, T as SerializedKeymap, _ as KeymapPersistence, a as CommandDefinition, b as RunBlockReason, c as CommandSource, d as Conflict, f as ConflictKind, g as KeyCapture, h as Json, i as CommandContext, k as Platform, l as Commands, m as DisplayOptions, n as BindingInput, o as CommandHandler, p as ConflictOptions, r as Command, s as CommandKeymap, t as Binding, u as CommandsOptions, v as KeymapStorage, w as SerializedBinding, x as RunOptions, y as PendingSequence } from "./types-QEXldPnL.mjs";
+import { a as RebindOptions, c as createRebinder, d as formatBinding, f as spokenBinding, g as validateBinding, h as seq, i as RebindMode, l as ariaKeyShortcuts, m as isSingleKeyBinding, n as CommandId, o as RebindState, p as BindingValidation, r as createCommands, s as Rebinder, t as matchCommands, u as bindingTokens } from "./index-3d9f54ln.mjs";
 //#region src/react/hooks.d.ts
 /**
  * Mounts a commands registry for the lifecycle of the component.
@@ -29,7 +29,10 @@ export declare function useShortcut<Id extends string>(registry: Commands<Id>, i
   spoken: string;
 };
 /**
- * Activates a scope for the lifecycle of the component.
+ * Activates a scope for the lifecycle of the component. Scopes rank in the
+ * order they are pushed, which here is the order React runs effects in: a
+ * surface opened later ranks higher, but of a parent and a child opening in
+ * the same render the child is pushed first.
  *
  * @example
  * ```tsx
@@ -37,8 +40,21 @@ export declare function useShortcut<Id extends string>(registry: Commands<Id>, i
  * ```
  */
 export declare function useScope<Id extends string>(registry: Commands<Id>, name: string, active?: boolean, options?: ScopeOptions): void;
-/** Registers a dynamic command for the lifecycle of the component. */
-export declare function useRegisterCommand<Id extends string>(registry: Commands<Id>, id: NoInfer<Id> | (string & {}), definition: CommandDefinition<NoInfer<Id>>): void;
+/**
+ * Attaches what a command does for the lifecycle of the component, so the
+ * behaviour lives where its state does. The latest `run` is always the one
+ * called. While `enabled` is `false` the component steps back: the command
+ * falls to the handler attached before it, or cannot run if there is none.
+ * The handler attached last wins, and React attaches a parent's after its
+ * children's when they mount together.
+ *
+ * @example
+ * ```tsx
+ * useCommandHandler(commands, "palette.open", () => setOpen(true));
+ * useCommandHandler(commands, "doc.save", save, dirty);
+ * ```
+ */
+export declare function useCommandHandler<Id extends string>(registry: Commands<Id>, id: NoInfer<Id>, run: CommandHandler<NoInfer<Id>>, enabled?: boolean): void;
 /** State and actions for rebinding a command. */
 interface UseRebindResult<Id extends string = string> extends RebindState<Id> {
   /** Active display string for the shortcut. */
@@ -79,4 +95,4 @@ export declare function useHeldKeyCodes(): Readonly<Record<string, string>>;
  */
 export declare function usePendingSequences<Id extends string>(registry: Commands<Id>): ReadonlyArray<PendingSequence<Id>>;
 //#endregion
-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, type UseRebindResult, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, observe, seq, spokenBinding, validateBinding };
+export { type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandler, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictKind, type ConflictOptions, type DisplayOptions, type Json, type Key, type KeyCapture, type KeymapPersistence, type KeymapStorage, 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, type UseRebindResult, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, seq, spokenBinding, validateBinding };