@inklu/keys 2.0.1 → 2.1.0

package/dist/{attributes-DotLr2MW.d.mts → types-QEXldPnL.d.mts}

@@ -1,10 +1,38 @@
-import { FormatDisplayOptions, Hotkey as Hotkey$1, HotkeySequence } from "@tanstack/hotkeys";
+//#region src/chord.d.ts
+/**
+ * One chord: its spelling, reading it from a string or a keypress, comparing
+ * the two, and writing it back. Everything else in the package handles chords
+ * through here, so there is one grammar and one idea of which key was pressed.
+ */
+/** Supported platforms for hotkey resolution and display formatting. */
+type Platform = "mac" | "windows" | "linux";
+/**
+ * Named keys with a place in the `Key` type, as `KeyboardEvent.key` spells
+ * them. Any other name still works as a key; `validateChord` only remarks on it.
+ */
+declare const NAMED_KEYS: readonly ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown", "Enter", "Escape", "Space", "Tab", "Backspace", "Delete", "Insert", "CapsLock", "ContextMenu", "PrintScreen", "ScrollLock", "Pause", "NumLock", "Help", "Clear", "MediaPlayPause", "MediaStop", "MediaTrackNext", "MediaTrackPrevious", "AudioVolumeUp", "AudioVolumeDown", "AudioVolumeMute", "BrowserBack", "BrowserForward", "BrowserRefresh", "BrowserSearch", "BrowserHome"];
+type Letter = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z";
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type FunctionKey = `F${Exclude<Digit, "0">}` | `F1${Digit}` | `F2${"0" | "1" | "2" | "3" | "4"}`;
+type Punctuation = "/" | "[" | "]" | "\\" | "=" | "-" | "," | "." | ";" | "`" | "'" | "+" | "?" | "!" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")" | "_" | "{" | "}" | "|" | ":" | '"' | "<" | ">" | "~";
+/**
+ * The key of a chord: the character or named key it produces (`"K"`,
+ * `"Escape"`), or a physical key by its `KeyboardEvent.code` in brackets
+ * (`"[KeyK]"`), which stays put whatever the keyboard layout.
+ */
+type Key = Letter | Digit | FunctionKey | Punctuation | (typeof NAMED_KEYS)[number] | `[${string}]`;
+type Held<Modifier extends string> = "" | `${Modifier}+`;
+type Modifiers = `${Held<"Control">}${Held<"Alt">}${Held<"Shift">}${Held<"Meta">}` | `Mod+${Held<"Alt">}${Held<"Shift">}`;
+/**
+ * A single hotkey chord, e.g. `"Mod+K"`: modifiers in the order Control, Alt,
+ * Shift, Meta, then one key. `Mod` is Command on macOS and Control elsewhere.
+ */
+type Chord = `${Modifiers}${Key}`;
+//#endregion
 //#region src/types.d.ts
-/** A single hotkey chord, e.g. `"Mod+K"`. */
-type Chord = Hotkey$1;
 /** A sequence of chords pressed in order, e.g. `G` then `I`. */
 interface SequenceBinding {
-  readonly sequence: HotkeySequence;
+  readonly sequence: ReadonlyArray<Chord>;
 }
 /** A hotkey chord or sequence that triggers a command. */
 type Binding = Chord | SequenceBinding;
@@ -16,9 +44,16 @@ type SerializedBinding = string | Array<string>;
 type Json = string | number | boolean | null | ReadonlyArray<Json> | {
   readonly [key: string]: Json;
 };
+/** Display options for formatting hotkeys. */
+interface DisplayOptions {
+  /** Platform to write for. Defaults to the one detected. */
+  platform?: Platform;
+  /** Symbols such as `⌘` and `↵` rather than names such as `Cmd`. Defaults to `true`. */
+  useSymbols?: boolean;
+}
 /** Trigger source for a command. */
 type CommandSource = "keyboard" | "api" | "dom";
-/** Context passed to a command's `run` handler. */
+/** Context passed to a command's handler. */
 interface CommandContext<Id extends string = string> {
   /** ID of the command being run. */
   readonly id: Id;
@@ -34,15 +69,16 @@ interface CommandContext<Id extends string = string> {
    * @example
    * ```ts
    * run: ({ commands }) => {
-   *   commands.setEnabled("doc.publish", false);
    *   commands.run("doc.save");
    * }
    * ```
    */
   readonly commands: Commands<Id>;
 }
+/** What a command does when it runs. */
+type CommandHandler<Id extends string = string> = (context: CommandContext<Id>) => void | Promise<void>;
 /**
- * Definition of a command and its default configuration.
+ * A command: what it is called, which keys reach it, and where it is live.
  *
  * `Id` is the registry's id union. `createCommands` fills it in, so
  * `commands.run(...)` inside a handler is checked against the registry's own
@@ -67,10 +103,6 @@ interface CommandDefinition<Id extends string = string> {
   keys?: BindingInput;
   /** Scope required for this command to fire. Omit for global, or `"*"` to bypass exclusive scopes. */
   scope?: string;
-  /** Guard function evaluated before running. */
-  when?: () => boolean;
-  /** Whether the command is enabled. Defaults to `true`. */
-  enabled?: boolean;
   /**
    * 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
@@ -78,20 +110,23 @@ interface CommandDefinition<Id extends string = string> {
    */
   preventDefault?: boolean;
   /**
-   * 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.
+   * Whether to ignore key events from text inputs, textareas, selects and
+   * contenteditable elements. When omitted it is decided 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<Id>) => void | Promise<void>;
+  /**
+   * What the command does, when that needs nothing a component owns. Leave
+   * it out and attach the behaviour where the state lives, with
+   * `commands.handle()` or `useCommandHandler`: a command with no handler
+   * cannot run and leaves its key alone.
+   */
+  run?: CommandHandler<Id>;
 }
 /** Resolved command snapshot including effective bindings, display tokens, and reachability. */
 interface Command<Id extends string = string> {
@@ -122,15 +157,11 @@ interface Command<Id extends string = string> {
    * 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. */
+  /** Whether its keys work right now: it has a handler and its scope is active. */
   readonly reachable: boolean;
   /** Whether the command has a user keymap override. */
   readonly overridden: boolean;
 }
-/** Supported platforms for hotkey resolution and display formatting. */
-type Platform = "mac" | "windows" | "linux";
 /** Storage interface for persisting keymap overrides. */
 interface KeymapStorage {
   getItem: (key: string) => string | null;
@@ -144,83 +175,36 @@ interface KeymapPersistence {
   /** Getter returning the storage implementation lazily. */
   storage: () => KeymapStorage | null;
 }
-/**
- * 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;
-  /** 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. */
-  readonly scope?: string;
-}
-/** Options for activating a scope. */
-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 = 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
 /** 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. */
+/**
+ * Persisted user overrides, keyed by command id. `version` lets a release
+ * skip a format it does not know instead of misreading it.
+ */
+type SerializedKeymap = {
   version: 1;
   overrides: Record<string, SerializedOverride>;
-}
+};
 /** Keymap interface for querying, modifying, and persisting keybindings. */
 interface CommandKeymap<Id extends string = string> {
   /** Active bindings in effect: the default, with any user override applied. */
-  get(id: Id | (string & {})): ReadonlyArray<Binding>;
+  get(id: Id): ReadonlyArray<Binding>;
   /**
    * 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;
+  set(id: Id, input: BindingInput | null): void;
   /**
    * 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;
+  add(id: Id, input: BindingInput): void;
   /** Resets user overrides back to defaults for a specific command or all commands. */
-  reset(id?: Id | (string & {})): void;
+  reset(id?: Id): void;
   /** Exports user overrides as JSON-serializable data. */
   export(): SerializedKeymap;
   /**
@@ -229,8 +213,68 @@ interface CommandKeymap<Id extends string = string> {
    */
   import(data: Json): void;
 }
-//#endregion
-//#region src/registry.d.ts
+/**
+ * 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;
+  /** 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. */
+  readonly scope?: string;
+}
+/** Options for conflict detection. */
+interface ConflictOptions<Id extends string = string> {
+  /** Command ID to ignore during conflict checking. */
+  ignore?: Id;
+  /** Scope to evaluate conflicts in. Defaults to global. */
+  scope?: string;
+}
+/** Options for activating a scope. */
+interface ScopeOptions {
+  /** Silence the keys of commands in lower scopes, including global commands. */
+  exclusive?: boolean;
+}
+/**
+ * Receives each keypress while the keyboard is captured: the event, and the
+ * chord it expresses (`null` for a modifier on its own). It decides what the
+ * key means, including whether to `preventDefault()` it.
+ */
+type KeyCapture = (event: KeyboardEvent, chord: Chord | null) => void;
+/** Options passed when manually running a command. */
+interface RunOptions {
+  /** Trigger source. Defaults to `"api"`. */
+  source?: CommandSource;
+  /** Originating DOM event. */
+  event?: Event;
+}
+/**
+ * Why a command cannot run: its id is not registered, nothing has attached a
+ * handler to it, or its scope is not open.
+ */
+type RunBlockReason = "unknown" | "unhandled" | "out-of-scope";
+/** Represents a partially completed key sequence. */
+interface PendingSequence<Id extends string = string> {
+  /** Command ID. */
+  readonly id: Id;
+  /** Sequence binding being typed. */
+  readonly binding: SequenceBinding;
+  /** Number of steps matched so far. */
+  readonly matched: number;
+  /** Total steps in the sequence. */
+  readonly total: number;
+  /** Formatted remaining steps. */
+  readonly remaining: ReadonlyArray<string>;
+}
 /** Configuration options for a commands registry. */
 interface CommandsOptions<Id extends string = string> {
   /**
@@ -284,90 +328,58 @@ interface CommandsOptions<Id extends string = string> {
    */
   onRun?: (context: CommandContext<Id>) => void;
   /**
-   * Error handler called when a command, its `when()` guard, or `onRun`
-   * throws. Defaults to `console.error`.
+   * Error handler called when a handler or `onRun` throws. Defaults to
+   * `console.error`.
    */
   onError?: (error: Error, context: CommandContext<Id>) => void;
 }
-/** Options passed when manually running a command. */
-interface RunOptions {
-  /** Trigger source. Defaults to `"api"`. */
-  source?: CommandSource;
-  /** Originating DOM event. */
-  event?: Event;
-}
-/** Options for conflict detection. */
-interface ConflictOptions<Id extends string = string> {
-  /** Command ID to ignore during conflict checking. */
-  ignore?: Id;
-  /** Scope to evaluate conflicts in. Defaults to global. */
-  scope?: string;
-}
-/** Reason why a command cannot run. */
-type RunBlockReason = "unknown" | "disabled" | "out-of-scope" | "guarded";
-/** Represents a partially completed key sequence. */
-interface PendingSequence<Id extends string = string> {
-  /** Command ID. */
-  readonly id: Id;
-  /** Sequence binding being typed. */
-  readonly binding: SequenceBinding;
-  /** Number of steps matched so far. */
-  readonly matched: number;
-  /** Total steps in the sequence. */
-  readonly total: number;
-  /** Formatted remaining steps. */
-  readonly remaining: ReadonlyArray<string>;
-}
-/** Handle for a dynamically registered runtime command. */
-interface CommandHandle {
-  /** Runs the command. Returns `true` if executed. */
-  run: (options?: RunOptions) => boolean;
-  /** Disposes and unregisters the command. */
-  dispose: () => void;
-}
-/** Public interface for the commands registry. */
+/** The commands registry. */
 interface Commands<Id extends string = string> {
   /** Keymap holding default and user bindings. */
   readonly keymap: CommandKeymap<Id>;
   /** Retrieves a command's snapshot, or `undefined` if unregistered. */
-  get(id: Id | (string & {})): Command<Id> | undefined;
-  /** Returns all registered commands in definition order. */
+  get(id: Id): Command<Id> | undefined;
+  /** Returns all 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.
+   * The list as the server rendered it: default bindings in the
+   * platform-neutral form, no scope, user override or attached handler
+   * applied. Referentially stable. Hand it to a framework as the server
+   * snapshot (`useSyncExternalStore`'s third argument), 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. */
+  /**
+   * Runs a command by ID. Returns `true` if executed. A direct call is not
+   * a keypress, so it passes `exclusive` barriers: a palette can run what it
+   * lists while its own scope silences the keyboard.
+   */
   run(id: Id, options?: RunOptions): boolean;
-  /** Checks whether a command can run currently. */
-  canRun(id: Id | (string & {})): boolean;
-  /** Returns why a command cannot run, or `null` if executable. */
-  whyNotRun(id: Id | (string & {})): RunBlockReason | null;
-  /** Enables or disables a command. */
-  setEnabled(id: Id | (string & {}), enabled: boolean): void;
-  /** Registers a command at runtime. */
-  add(id: Id | (string & {}), definition: CommandDefinition<Id>): CommandHandle;
-  /** Removes a command registration. */
-  remove(id: Id | (string & {})): void;
+  /** Checks whether `run` would execute the command right now. */
+  canRun(id: Id): boolean;
+  /** Returns why `run` would refuse the command, or `null` if it would run. */
+  whyNotRun(id: Id): RunBlockReason | null;
+  /**
+   * Attaches what a command does until the returned function is called.
+   * The most recently attached handler runs; disposing it hands the command
+   * back to the one before, or to the definition's own `run`.
+   */
+  handle(id: Id, run: CommandHandler<Id>): () => void;
   /** Activates a scope until the returned disposal function is called. */
   pushScope(name: string, options?: ScopeOptions): () => void;
+  /**
+   * Takes the whole keyboard until the returned function is called: every
+   * keypress goes to `onKey` first and no command's keys are live, `"*"`
+   * ones included. This is what recording a new shortcut is built on.
+   */
+  capture(onKey: KeyCapture): () => void;
   /**
    * 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;
-  /** Splits a command's primary binding into `<kbd>` tokens. */
-  tokens(id: Id | (string & {})): Array<string>;
-  /** Returns currently active partially-typed sequences. */
+  /** Returns the partially-typed sequences. Tracked only while something is subscribed. */
   pending(): ReadonlyArray<PendingSequence<Id>>;
   /** Subscribes to sequence progress changes. */
   subscribePending(listener: () => void): () => void;
@@ -379,48 +391,8 @@ interface Commands<Id extends string = string> {
   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. */
+  /** Tears down listeners and clears all commands. */
   destroy(): void;
 }
-/**
- * Creates a command registry.
- *
- * @example
- * ```ts
- * export const commands = createCommands({
- *   "palette.open": {
- *     title: "Open command palette",
- *     keys: "Mod+K",
- *     run: () => setPaletteOpen(true),
- *   },
- *   "nav.inbox": {
- *     title: "Go to inbox",
- *     keys: seq("G", "I"),
- *     run: () => 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/attributes.d.ts
-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.
- */
-declare function observe<Id extends string>(registry: Commands<Id>, options?: ObserveOptions): () => void;
 //#endregion
-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 };
+export { SequenceBinding as C, Chord as D, SerializedOverride as E, Key as O, ScopeOptions as S, SerializedKeymap as T, KeymapPersistence as _, CommandDefinition as a, RunBlockReason as b, CommandSource as c, Conflict as d, ConflictKind as f, KeyCapture as g, Json as h, CommandContext as i, Platform as k, Commands as l, DisplayOptions as m, BindingInput as n, CommandHandler as o, ConflictOptions as p, Command as r, CommandKeymap as s, Binding as t, CommandsOptions as u, KeymapStorage as v, SerializedBinding as w, RunOptions as x, PendingSequence as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklu/keys",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A command system for the web — typed commands, portable keybindings, scopes, sequences, conflict detection, rebinding, and platform-aware display.",
   "keywords": [
     "accessibility",
@@ -41,12 +41,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@tanstack/hotkeys": "^0.10.0"
-  },
   "devDependencies": {
     "@inklu/tsconfig": "1.0.0",
+    "@playwright/test": "^1.63.0",
     "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.6.2",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "jsdom": "^30.1.1",
@@ -67,6 +66,7 @@
   "scripts": {
     "build": "vp pack",
     "dev": "vp pack --watch",
-    "test": "vp test"
+    "test": "vp test",
+    "test:e2e": "playwright test"
   }
 }