@inklu/keys 1.0.0 → 1.1.0

package/README.md

@@ -1,18 +1,17 @@
 # @inklu/keys
 
-Keyboard shortcut management for the web. Define commands once, bind keys to them separately, and let users remap anything.
-
-Built on [TanStack Hotkeys](https://tanstack.com/hotkeys) for key matching, which means typed hotkey strings, portable `Mod` bindings, layout-aware parsing and a single document listener no matter how many commands you register. `@inklu/keys` adds what an application needs on top: a registry, scopes, conflict detection, persistence, rebinding, and shortcuts a screen reader can read.
+Keyboard shortcut management for the web. Built on TanStack Hotkeys, `@inklu/keys` provides a registry, scopes, conflict detection, and screen-reader-ready shortcuts.
 
 ```bash
 pnpm add @inklu/keys
 ```
 
-## The idea
+## 1. Define Commands
 
-A **command** is an addressable thing your app can do — it has an id, a title and a handler. A **binding** is a key that triggers it. Keeping them apart is what makes the rest possible: the same command runs from the keyboard, a palette, a menu item or code, and a user can rebind it without you touching its definition.
+A command is an addressable action. It has an id, title, and a handler.
 
 ```ts
+// commands.ts
 import { createCommands, seq } from "@inklu/keys";
 
 export const commands = createCommands({
@@ -21,237 +20,91 @@ export const commands = createCommands({
     keys: "Mod+K",
     run: () => setPaletteOpen(true),
   },
-  "doc.save": {
-    title: "Save document",
-    keys: "Mod+S",
-    when: () => isDirty(),
-    run: () => save(),
-  },
   "nav.inbox": {
     title: "Go to inbox",
     keys: seq("G", "I"), // press G, then I
     run: () => navigate("/inbox"),
   },
 });
-
-commands.mount(); // start listening; returns a function to stop
 ```
 
-Ids are inferred from the object, so `commands.run("doc.save")` autocompletes and a typo is a type error. So is a typo in a definition — `key:` instead of `keys:` would otherwise bind nothing at all, silently.
-
-`Mod` resolves to <kbd>⌘</kbd> on macOS and <kbd>Ctrl</kbd> everywhere else, so you write a shortcut once.
-
-### What this is not
-
-This is not a command-palette toolkit. There is no palette component, no fuzzy matcher, no ranking, and no `group` or `description` on a command — a command is an id, a title, a handler and its keys, and that is the whole of it. Filtering commands is your app's business and every app wants it slightly differently. This package gives you the list, current shortcuts and current state; sorting it is three lines you own:
-
-```ts
-const results = commands.filter((command) =>
-  command.title.toLowerCase().includes(query.toLowerCase()),
-);
-```
+## 2. React Setup
 
-## React
+Pass the registry explicitly to all hooks. There is no Context provider.
 
 ```tsx
-import { useCommands, useMountCommands } from "@inklu/keys/react";
+import { useCommands, useMountCommands, useShortcut } from "@inklu/keys/react";
 import { commands } from "./commands";
 
 function App() {
+  // Starts listening in an effect
   useMountCommands(commands);
-  return <Shortcuts />;
+  return <ShortcutButton />;
 }
 
-function Shortcuts() {
-  const list = useCommands(commands);
-
-  return list.map((command) => (
-    <button
-      key={command.id}
-      onClick={() => commands.run(command.id)}
-      aria-keyshortcuts={command.aria || undefined}
+function ShortcutButton() {
+  // Get live shortcut state
+  const shortcut = useShortcut(commands, "palette.open");
+  
+  return (
+    <button 
+      onClick={() => commands.run("palette.open")}
+      aria-keyshortcuts={shortcut.aria || undefined}
     >
-      {command.title}
-      {command.tokens[0]?.map((token, i) => <kbd key={i}>{token}</kbd>)}
+      Open Palette
+      {shortcut.tokens[0]?.map((token, i) => <kbd key={i}>{token}</kbd>)}
     </button>
-  ));
+  );
 }
 ```
 
-`useMountCommands` starts listening in an effect, so nothing touches the DOM during render and the registry is safe to create at module scope in a server-rendered app.
-
-**Every hook takes the registry as its first argument.** There is no provider and no context: you already have the registry by importing it, and passing it explicitly is what keeps the ids typed — through context they widen to `string` and `useShortcut("typo")` stops being an error.
-
-| Hook | What it gives you |
-| :--- | :--- |
-| `useMountCommands(commands)` | Starts listening for as long as the component lives |
-| `useCommands(commands)` | Every command, with live shortcuts and state |
-| `useCommand(commands, id)` | One command's live state |
-| `useShortcut(commands, id)` | `{ display, tokens, aria }`, ready to render |
-| `useScope(commands, name, active, { exclusive })` | Activates a scope while a component is mounted |
-| `useRegisterCommand(commands, id, definition)` | A command that exists only while a feature is on screen |
-| `useRebind(commands, id)` | The "press the keys you want" flow, with conflicts |
-| `useHeldKeys()` | The keys physically down right now |
-
-## Server rendering
-
-There is no `navigator` on the server, so a shortcut has to be written for *some* platform before the browser can be asked. The registry writes `Ctrl+K` on the server and in the first client render, then settles on the real platform at `mount()` and re-renders. A Mac user sees `⌘K` a frame later instead of a hydration mismatch.
-
-Pin `platform` if you know better, and nothing ever changes:
-
-```ts
-createCommands(definitions, { platform: "mac" });
-```
-
-## Accessibility
+## 3. Scopes
 
-Every command carries an `aria` string — the value for [`aria-keyshortcuts`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts), which is what a screen reader announces. It is deliberately not the display string: the attribute wants resolved key *names*, so `Mod+K` becomes `Meta+K` on macOS and `Control+K` elsewhere, never `⌘K`.
+Use scopes to isolate commands when modals or dialogs are open.
 
 ```tsx
-<button aria-keyshortcuts={command.aria || undefined}>Save</button>
-```
-
-Sequences produce `""`. The attribute separates *alternatives* with spaces, so emitting `seq("G","I")` as `"G I"` would announce "press G or I" — the opposite of what it means. There is no way to express a sequence, so the package says nothing rather than something false.
-
-If you render shortcuts as `<kbd>⌘</kbd>`, give the control an accessible name too — a screen reader reads that glyph by its Unicode name, not as "Command".
+import { useScope } from "@inklu/keys/react";
 
-## Scopes
+function Dialog({ isOpen }) {
+  // When exclusive is true, commands outside this scope are silenced
+  useScope(commands, "dialog", isOpen, { exclusive: true });
 
-A scope decides whether a command is reachable. Push one while a dialog is open and it shadows the rest of the app, so you do not end up writing `if (!modalOpen)` in twenty different handlers.
-
-```ts
-const release = commands.pushScope("dialog", { exclusive: true });
-// …everything below this barrier stops responding
-release();
+  return isOpen ? <div className="dialog">...</div> : null;
+}
 ```
 
-In React that is `useScope("dialog", isOpen, { exclusive: true })`.
-
-`exclusive` is a **barrier, not a filter**: everything at or above the topmost barrier stays reachable, everything below it goes quiet. That is what lets a menu opened inside a dialog keep working while the page behind the dialog does not. Commands scoped `"*"` always fire.
+## 4. Rebinding
 
-Scoping is resolved when a scope is pushed or released, never per keystroke — an open dialog costs one pass over the registrations rather than a check on every key the user presses.
-
-## Rebinding
-
-Bindings live in a keymap, layered as defaults plus user overrides, so "reset to default" is exact rather than approximate.
+Overrides are layered over defaults.
 
 ```ts
 commands.keymap.set("palette.open", "Mod+P");     // remap
 commands.keymap.add("palette.open", "Control+P"); // an additional key
-commands.keymap.set("palette.open", null);        // unbind, but keep the command
-commands.keymap.reset("palette.open");            // forget the override, back to the default
-commands.keymap.reset();                          // …for every command
-```
-
-`set(id, null)` and `reset(id)` are different on purpose: the first records an explicit "no keys" that survives, the second forgets that the user chose anything at all.
-
-Persist them by handing the registry a storage getter:
-
-```ts
-createCommands(definitions, {
-  persist: { storage: () => localStorage },
-});
-```
-
-A getter is the only accepted form, so nothing touches `localStorage` at module scope and the package stays safe to import on the server. Overrides that no longer parse — a hand-edited value, a key that was renamed — are skipped rather than thrown on, so one bad row cannot lock a user out of their own shortcuts.
-
-**Overrides are user data.** They are keyed by command id and outlive the command: unregistering a feature drops its defaults but keeps the key someone chose, so a panel that comes and goes does not quietly reset it. Only `keymap.reset(id)` forgets one.
-
-### Conflicts
-
-```ts
-commands.conflicts("Mod+K", { ignore: "palette.open" });
-// → [{ id: "search.open", display: "⌘K", scope: undefined }]
+commands.keymap.set("palette.open", null);        // unbind
+commands.keymap.reset("palette.open");            // reset to default
 ```
 
-Two commands only conflict when their scopes can be active at the same time, so the same key may safely mean different things in different places. A global command conflicts with every scope, because it stays reachable inside them.
-
-In development the registry reports collisions itself: once at startup for the initial map, and again whenever a command is added at runtime, which in a React app is where most of them come from. It also warns about bindings the key parser cannot read — a mistyped modifier is otherwise silent, because the parser drops the part it does not recognize and `"Mdo+K"` quietly becomes a bare `K`.
-
-### Recording
+In React, use the `useRebind` hook for a capture flow:
 
 ```tsx
-const rebind = useRebind("palette.open");
+const rebind = useRebind(commands, "palette.open");
 
 <button onClick={rebind.start}>
   {rebind.recording ? "Press keys…" : rebind.display}
 </button>;
-{rebind.overridden && <button onClick={rebind.reset}>Reset</button>}
-{rebind.conflicts.length > 0 && <p>Also used by {rebind.conflicts[0].id}</p>}
-```
-
-`display`, `tokens` and `overridden` come from the command itself rather than from the last capture, so a rebind made anywhere else in the app still shows up here.
-
-Commands are suppressed while recording, so capturing `Mod+K` does not also fire whatever `Mod+K` is currently bound to.
-
-## Markup
-
-For pages that are not React, `@inklu/keys/attributes` wires the DOM to a registry with one delegated listener:
-
-```html
-<button data-command="palette.open">
-  Search <kbd data-command-keys="palette.open"></kbd>
-</button>
-```
-
-```ts
-import { observe } from "@inklu/keys/attributes";
-const dispose = observe(commands);
-```
-
-Elements with `data-command-keys` are filled with the current shortcut and stay in sync when it is rebound. Elements with `data-command` also get `aria-keyshortcuts` set for free.
-
-## Behaviour worth knowing
-
-**Typing in inputs.** Bare keys and Shift/Alt combos are ignored while the user is in an `input`, `textarea` or contenteditable; Ctrl/Meta shortcuts and `Escape` still fire. So `Mod+K` works from inside your search box, and `/` does not. Override per command with `ignoreInputs`.
-
-**Consuming the event.** A command calls `preventDefault()` only when it actually runs. A command that is disabled, out of scope, or blocked by `when` leaves the key alone for the browser and for other handlers. Opt out with `preventDefault: false`. Propagation is never stopped — the matcher already prevents other hotkeys from firing, and halting the DOM event too would silently break delegation in your app.
-
-**`when` is a guard, not state.** It is checked immediately before running and is not observed, so it will not re-render anything. Use `setEnabled` or scopes for state that should be visible in the UI — `command.reachable` reflects both.
-
-**Why didn't my shortcut fire?** `commands.whyNotRun(id)` returns `"disabled"`, `"out-of-scope"`, `"guarded"`, `"unknown"`, or `null` when it would have run.
-
-**Knowing what ran.** `onRun` is called for every command, whatever triggered it — that is the hook for recent-command ordering, analytics or an activity log, so a command's own `run` does not have to report on itself.
-
-```ts
-createCommands(definitions, {
-  onRun: ({ id, source }) => recents.push(id),
-});
 ```
 
-**Async commands.** `run` may be async. Nothing awaits it — a keystroke is fire-and-forget — but a rejection still reaches `onError` rather than the unhandled-rejection channel. If you need to await, do it inside your own handler.
+## API Summary
 
-**One way to write a binding.** A chord is a string, `"Mod+K"`. A sequence is `seq("G", "I")`. An array means alternatives — `keys: ["Mod+K", "/"]` binds two different keys to one command. There is no object form of a chord and no inline `"G I"` string, so nothing has to normalize a binding before it can compare, format or store one.
+- `createCommands(definitions, options)` - creates the registry
+- `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
 
-## API
-
-```ts
-createCommands(definitions, options)  // → Commands
-commands.list()                       // → readonly Command[], stable identity
-commands.get(id)
-commands.run(id, options?)            // → boolean
-commands.canRun(id) / commands.whyNotRun(id)
-commands.setEnabled(id, enabled)
-commands.add(id, definition)          // → { run, dispose }
-commands.remove(id)                   // keeps the user's override
-commands.pushScope(name, { exclusive })  // → release()
-commands.conflicts(binding, { ignore, scope })
-commands.display(id) / commands.tokens(id)   // "" / [] when unbound
-commands.mount()                      // → stop()
-commands.subscribe(listener)          // → unsubscribe()
-commands.destroy()
-commands.keymap                       // get / set / add / reset / export / import
-```
-
-`list()` returns the same array until something actually changes, so it can go straight into `useSyncExternalStore`. Each `Command` carries `title`, `scope`, `bindings`, `display`, `tokens`, `aria`, `enabled`, `reachable` and `overridden`.
-
-`display(id)` and `tokens(id)` take a command id. To format a binding you are holding directly — one out of `conflicts()`, say — `formatBinding` and `bindingTokens` are exported for that, and every `Conflict` already carries its own `display`.
-
-`CommandId<typeof commands>` is the id union, for typing values that travel alongside the registry:
+## Accessibility
 
-```ts
-export type AppCommandId = CommandId<typeof commands>;
-```
+Every command carries an `aria` string. Apply it to `aria-keyshortcuts` so screen readers announce the exact key sequence.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklu/keys",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A command system for the web — typed commands, portable keybindings, scopes, sequences, conflict detection, rebinding, and platform-aware display.",
   "keywords": [
     "keyboard",