@inklu/keys 2.0.2 → 2.2.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. What an app does not use, it does not ship: persistence, recording a shortcut and palette search are imports of their own, and the registry does not pull them in.
+
+Docs: [inklu.saddy.me/keys](https://inklu.saddy.me/keys) · For agents: [llms.txt](https://inklu.saddy.me/keys/llms.txt) · Agent skills: `npx skills add nkurunziza-saddy/inklu --skill inklu-keys` for the API, and `--skill inklu-keys-practices` for choosing and showing shortcuts well
 
 ```bash
 pnpm add @inklu/keys
@@ -10,32 +18,69 @@ 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"),
 	},
 });
 ```
 
+### Keys that differ by platform
+
+`Mod` covers most shortcuts, since it is Command on a Mac and Control everywhere else. Where the platforms' own conventions differ, give each its keys: `mac` is for Apple keyboards (macOS, iPadOS, iOS), `other` for the rest. A side left out is unbound there.
+
+```ts
+createCommands({
+	"edit.redo": { title: "Redo", keys: { mac: "Mod+Shift+Z", other: ["Mod+Y", "Mod+Shift+Z"] } },
+	"nav.back": { title: "Back", keys: { mac: "Mod+[", other: "Alt+ArrowLeft" } },
+	"doc.new": { title: "New document", keys: { mac: "Mod+Alt+N", other: "Alt+N" } },
+});
+```
+
+Some keys are not an app's to bind, and the registry warns about them in development:
+
+- **Reserved by the browser or the operating system.** `Mod+N`, `Mod+T`, `Mod+W` and their `Shift` forms, `Control+Tab`, `Mod+Q` on a Mac, `Alt+F4` and anything holding `Meta` (the Windows or Super key) elsewhere. The page never receives most of these, so `preventDefault()` cannot help. That is why `doc.new` above is not `Mod+N`.
+- **`Control+Alt` with a character key, on Windows and Linux.** Many keyboard layouts report AltGr as `Control+Alt`, and there the keys type a character (`@`, `€`, `{`) instead. `Mod+Alt+N` is fine on a Mac and not elsewhere, which is the other reason for `{ mac, other }`.
+- **`Control+Alt` on a Mac.** It is the VoiceOver modifier.
+
+Browser features a page _can_ take over (`Mod+F`, `Mod+P`, `Mod+L`, `Mod+R`) are left to your judgement: do it only where your version does the same job better.
+
+### Commands generated from data
+
+Ids come from the object's keys, so generated commands are typed when their keys are. `Object.fromEntries` returns plain string keys; give the result its key type where you build it:
+
+```ts
+const pages = Object.fromEntries(
+	docs.map((doc) => [`go.${doc.slug}`, { title: doc.title, run: () => router.navigate(doc.path) }]),
+) as Record<`go.${Slug}`, CommandDefinition>;
+
+export const commands = createCommands({
+	"palette.open": { title: "Open command palette", keys: "Mod+K" },
+	...pages,
+});
+```
+
+Spread from a `Record<string, CommandDefinition>` instead, the commands still exist at runtime but the types only know the literal keys. To have the compiler check that every id is present, name the ids yourself: `createCommands<AppCommandId>({ … })`.
+
 ## 2. React Setup
 
 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 +89,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 +114,22 @@ 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.
+- A handler is attached when its component mounts. Keep it with its state in code that is already loaded, and lazy-load only what it shows: a handler inside a lazily loaded component leaves the key to the browser until its chunk arrives.
+
+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 +138,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. 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.
 
-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.
+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 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.
+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
 
@@ -130,78 +203,75 @@ 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
+	// A binding the browser or OS reserves is never applied, whatever this says.
 	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.
+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
 
-`commands.conflicts(binding, { scope, ignore })` lists commands in overlapping scopes whose bindings collide with `binding`. Each result has a `kind`:
+`commands.conflicts(binding, { scope, ignore })` lists what stands in the way of `binding`. Each result has a `kind`:
 
-- `"exact"` — the same keys. Only one command runs (see above).
+- `"reserved"` — the browser or operating system keeps these keys on this platform (see [Keys that differ by platform](#keys-that-differ-by-platform)). Listed first. A rebinder reports it and never applies the binding.
+- `"exact"` — a command in an overlapping scope has 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.
+Only a conflict with a command has an `id`, so narrow on `kind` before reading it:
+
+```tsx
+rebind.conflicts.map((conflict) =>
+	conflict.kind === "reserved"
+		? `${conflict.display} belongs to the browser`
+		: `Also used by ${commands.get(conflict.id)?.title}`,
+);
+```
+
+In development, all three are also reported with `console.warn` when the registry is created, for the defaults on both kinds of platform. The check is dropped from production builds.
 
 ## 6. Persistence and SSR
 
 ```ts
-createCommands(definitions, {
-	persist: {
-		storage: () => (typeof window === "undefined" ? null : localStorage),
-		key: "my-app.keys",
-	},
-});
+import { createCommands, webStorage } from "@inklu/keys";
+
+createCommands(definitions, { persist: webStorage("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.
+`webStorage(key, storage?)` keeps the user's overrides in `localStorage`. It is an import, so a registry created without it carries no storage code. Pass a second argument to keep them elsewhere: a function returning the storage, as in `webStorage("my-app.keys", () => sessionStorage)`. Any object with `getItem`, `setItem` and `removeItem` will do, and the function is only called in the browser.
+
+Only user overrides are stored — never defaults. To move them between devices yourself, `exportKeymap(commands)` returns them as JSON-safe data and `importKeymap(commands, data)` puts them back and saves them. The data carries a `version`, and data in a version this release does not know is ignored instead of misread.
 
-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.
+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. Each mount reads what is stored, so a registry that was unmounted for a while has caught up by the time it listens again.
+
+For a store that is not Web Storage, `persist` takes any object shaped like `KeymapStore`: `read()`, `write(overrides)` and `watch(onChange)`, all synchronous, with `Override` the type of one command's entry. For something asynchronous, such as a user's account, use `exportKeymap` and `importKeymap` instead.
 
 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`), and `{ mac, other }` keys to its side. 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`.
+`ignoreInputs` on a command decides whether it fires while focus is in a text input, textarea, select or contenteditable, or in a custom widget with a text-entry role (`textbox`, `searchbox`, `combobox`, `spinbutton`, `slider`). 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. Editing is not hijacked either. Select all, copy, cut, paste, undo and redo (`Mod+A`, `C`, `X`, `V`, `Z`, `Shift+Z`, `Shift+V`, and `Mod+Y` off the Mac) are ignored in a field too, and so is `Mod` with `Backspace`, `Delete`, an arrow, `Home` or `End`, which move and delete by word or line. An app's own undo, select-all or delete-item leaves the field's alone. Set `ignoreInputs: false` on a command that should take one of them anyway. Keydowns that are part of an IME composition never trigger commands.
 
-`commands.whyNotRun(id)` explains a shortcut that did not fire: `"disabled"`, `"out-of-scope"`, `"guarded"`, `"unknown"`, or `null` when it would run.
+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, which suits stepping and undo; give a toggle, or anything that should happen once per press, `repeat: false`. It still claims its key for as long as the key is held.
 
-## 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();
-```
+`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 +283,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";
@@ -241,33 +312,101 @@ const stop = observe(commands); // or observe(commands, { root: element })
 
 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.
 
+## 11. Recipes
+
+Patterns the pieces above already cover, so none of them needs an API of its own.
+
+### Act on the selection, else on the highlighted item
+
+Which item a shortcut applies to is your state. Compute the target once, and let it switch the handler on and off:
+
+```tsx
+const targets = selection.size > 0 ? [...selection] : highlighted ? [highlighted] : [];
+
+useCommandHandler(commands, "issue.setStatus", () => openStatusPicker(targets), targets.length > 0);
+useCommandHandler(commands, "issue.selectAll", () => setSelection(new Set(visibleIds)));
+```
+
+With nothing targeted the command has no handler, so its key falls through, `reachable` is false for its button, and a palette that lists what `canRun` leaves it out: the palette follows the selection without being told. `issue.selectAll` can be `Mod+A`: inside a text field that stays the field's own select-all.
+
+### Hold a key to peek
+
+`repeat: false` runs a command once per press. Letting go is a `keyup` away:
+
+```tsx
+// "issue.peek": { title: "Peek", keys: "Space", repeat: false }
+const [peeking, setPeeking] = useState(false);
+useCommandHandler(commands, "issue.peek", () => setPeeking(true), highlighted !== null);
+
+useEffect(() => {
+	if (!peeking) return;
+	const stop = () => setPeeking(false);
+	window.addEventListener("keyup", stop);
+	window.addEventListener("blur", stop);
+	return () => {
+		window.removeEventListener("keyup", stop);
+		window.removeEventListener("blur", stop);
+	};
+}, [peeking]);
+```
+
+Bind a hold to a bare key. While Command is down, macOS sends no `keyup` for the other keys, so a held `Mod+…` chord cannot tell when it was let go.
+
+### A shortcut sheet on `?` and `Mod+/`
+
+```ts
+"help.shortcuts": { title: "Keyboard shortcuts", keys: ["?", "Mod+/"], scope: "*" },
+```
+
+Build the sheet from `useCommands(commands)`, grouped by `group`, and search it with `matchCommands`, which also matches the displayed shortcut. When a user turns single-key shortcuts off, `?` goes and `Mod+/` stays, so the sheet that explains the setting is still reachable.
+
+### A way out of a text field
+
+Bare keys are ignored while the user types, so give them a key that leaves the field. `Escape` is the one bare key that fires inside an input:
+
+```tsx
+// "field.leave": { title: "Leave field", keys: "Escape", hidden: true }
+const [editing, setEditing] = useState(false);
+useCommandHandler(commands, "field.leave", () => rowRef.current?.focus(), editing);
+
+<input onFocus={() => setEditing(true)} onBlur={() => setEditing(false)} />;
+```
+
+Move focus to the item the field belongs to, not to nothing, so the next key has a target.
+
 ## API Summary
 
 - `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.keymap`: `get`, `set`, `add`, `reset`, `export`, `import`
+  - `options`: `{ bindings, platform, target, persist, display, singleKeyShortcuts, onRun, onError }`; `platform` is `"mac"` or `"other"`
+  - `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`
   - `commands.setSingleKeyShortcuts(enabled)`, `commands.singleKeyShortcuts`
+- `webStorage(key, storage?)` - the `persist` option: Web Storage, followed across tabs
+- `exportKeymap(commands)`, `importKeymap(commands, data)` - user overrides as JSON-safe data
 - `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`
+- `matchCommands(list, query)` - palette filtering over `title`, `description`, `group`, `keywords`, id and displayed shortcut
+- `formatBinding`, `bindingTokens`, `ariaKeyShortcuts`, `spokenBinding`, `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
+  - `useHeldKeys()` - the keys held down right now, by name
 
-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
 
-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:
+Shortcuts are written the way each platform writes them: `⇧⌘S` on a Mac, symbols run together in Apple's order, and `Ctrl+Shift+S` elsewhere. `tokens` holds the same keys one at a time, for a `<kbd>` each.
+
+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` — `"Command K"` on a Mac and `"Control K"` elsewhere, 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");
@@ -284,6 +423,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-D-hUKGoN.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);
 		}
@@ -51,28 +52,25 @@ function observe(registry, options = {}) {
 		lastPainted = next;
 		paintWithin(root);
 	});
-	let observer;
-	if ("MutationObserver" in globalThis) {
-		observer = new MutationObserver((mutations) => {
-			for (const mutation of mutations) {
-				if (mutation.type === "attributes" && mutation.target instanceof Element) {
-					paintElement(mutation.target);
-					continue;
-				}
-				for (const node of mutation.addedNodes) if (node instanceof Element) paintWithin(node);
+	const observer = new MutationObserver((mutations) => {
+		for (const mutation of mutations) {
+			if (mutation.type === "attributes" && mutation.target instanceof Element) {
+				paintElement(mutation.target);
+				continue;
 			}
-		});
-		observer.observe(root instanceof Document ? root.documentElement : root, {
-			childList: true,
-			subtree: true,
-			attributes: true,
-			attributeFilter: [COMMAND_ATTRIBUTE, KEYS_ATTRIBUTE]
-		});
-	}
+			for (const node of mutation.addedNodes) if (node instanceof Element) paintWithin(node);
+		}
+	});
+	observer.observe(root instanceof Document ? root.documentElement : root, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeFilter: [COMMAND_ATTRIBUTE, KEYS_ATTRIBUTE]
+	});
 	return () => {
 		root.removeEventListener("click", onClick);
 		unsubscribe();
-		observer?.disconnect();
+		observer.disconnect();
 	};
 }
 //#endregion