@inklu/keys 2.0.2 → 2.2.0

package/dist/types-D-hUKGoN.d.mts

@@ -0,0 +1,357 @@
+//#region src/chord.d.ts
+/** Chords: reading one from text or a keypress, matching the two, and writing one back. */
+/**
+ * The two kinds of keyboard: `"mac"` for Apple's (macOS, iPadOS, iOS), whose
+ * primary modifier is Command, and `"other"` for the rest, where it is Control.
+ */
+type Platform = "mac" | "other";
+/** Named keys in the `Key` type, as `KeyboardEvent.key` spells them. Other names still work. */
+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 sequence of chords pressed in order, e.g. `G` then `I`. */
+interface SequenceBinding {
+  readonly sequence: ReadonlyArray<Chord>;
+}
+/** A hotkey chord or sequence that triggers a command. */
+type Binding = Chord | SequenceBinding;
+/** One binding or an array of alternative bindings. */
+type BindingInput = Binding | ReadonlyArray<Binding>;
+/**
+ * Keys that differ by platform: `mac` on Apple keyboards (macOS, iPadOS and
+ * iOS), `other` everywhere else. A side left out is unbound there.
+ *
+ * @example
+ * ```ts
+ * keys: { mac: "Mod+Shift+Z", other: ["Mod+Y", "Mod+Shift+Z"] }
+ * ```
+ */
+interface PlatformBindings {
+  readonly mac?: BindingInput;
+  readonly other?: BindingInput;
+}
+/** JSON-serializable form of a binding. */
+type SerializedBinding = string | Array<string>;
+/** An arbitrary JSON-compatible value, e.g. from `JSON.parse` or persisted storage. */
+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 handler. */
+interface CommandContext<Id extends string = string> {
+  /** ID of the command being run. */
+  readonly id: Id;
+  /** How the command was triggered. */
+  readonly source: CommandSource;
+  /** Originating DOM event, if triggered by user interaction. */
+  readonly event?: Event;
+  /** Specific binding that triggered the command. */
+  readonly binding?: Binding;
+  /** The registry, typed with its own ids. */
+  readonly commands: Commands<Id>;
+}
+/** What a command does when it runs. */
+type CommandHandler<Id extends string = string> = (context: CommandContext<Id>) => void | Promise<void>;
+/**
+ * A command: what it is called, which keys reach it, and where it is live.
+ * `Id` is the registry's id union, which `createCommands` fills in.
+ */
+interface CommandDefinition<Id extends string = string> {
+  /** Human-readable title. */
+  title: string;
+  /** Longer explanation, such as a palette's secondary line or a tooltip. */
+  description?: string;
+  /** Heading to list the command under in a palette or shortcut sheet, e.g. `"Navigate"`. */
+  group?: string;
+  /** Extra search terms `matchCommands` checks besides the title, e.g. `["find", "search"]`. */
+  keywords?: ReadonlyArray<string>;
+  /**
+   * Leave the command out of `matchCommands`. It still runs and still appears
+   * in `list()`. Defaults to `false`.
+   */
+  hidden?: boolean;
+  /**
+   * Default key binding(s). Write `{ mac, other }` where the platforms'
+   * conventions differ, as they do for redo and for back and forward.
+   */
+  keys?: BindingInput | PlatformBindings;
+  /** Scope required for this command to fire. Omit for global, or `"*"` to bypass exclusive scopes. */
+  scope?: string;
+  /**
+   * Prevent default event behavior when run, and for each step of a sequence as
+   * it matches. Defaults to `true`.
+   */
+  preventDefault?: boolean;
+  /**
+   * Whether to ignore key events from text inputs, selects, contenteditable
+   * elements and widgets with a text-entry ARIA role. When omitted, chords
+   * holding Control or Meta and bare `Escape` still fire there, except the
+   * field's own: select all, copy, cut, paste, undo, redo, and moving or
+   * deleting by word or line.
+   */
+  ignoreInputs?: boolean;
+  /** Timeout in milliseconds between sequence steps. Defaults to `1000`. */
+  sequenceTimeout?: number;
+  /**
+   * Whether holding the keys down runs the command again on each auto-repeat.
+   * Defaults to `true`. With `false` it runs once per press and still claims
+   * its key while held.
+   */
+  repeat?: boolean;
+  /**
+   * What the command does, when that needs nothing a component owns. Otherwise
+   * attach it 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> {
+  readonly id: Id;
+  readonly title: string;
+  readonly description?: string;
+  readonly group?: string;
+  /** Extra search terms; empty when the definition gave none. */
+  readonly keywords: ReadonlyArray<string>;
+  /** Whether `matchCommands` leaves the command out. */
+  readonly hidden: boolean;
+  readonly scope?: string;
+  /** Active bindings after user overrides. */
+  readonly bindings: ReadonlyArray<Binding>;
+  /** Formatted display strings for active bindings. */
+  readonly display: ReadonlyArray<string>;
+  /** Formatted tokens per binding for rendering `<kbd>` elements. */
+  readonly tokens: ReadonlyArray<ReadonlyArray<string>>;
+  /** Value for the `aria-keyshortcuts` attribute. Chords only: it cannot express a sequence. */
+  readonly aria: string;
+  /**
+   * Every binding phrased for a screen reader, joined by `" or "`: `"Command K"`,
+   * `"G then I"`. The only accessible form of a sequence.
+   */
+  readonly spoken: string;
+  /** 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;
+}
+/** A user's change to one command: `"replace"` the default (`[]` unbinds), or `"add"` to it. */
+interface Override {
+  readonly kind: "replace" | "add";
+  readonly bindings: ReadonlyArray<Binding>;
+}
+/** Where user overrides are kept between visits. `webStorage()` makes one. */
+interface KeymapStore {
+  /** The stored overrides: empty when there are none, `null` when they cannot be read. */
+  read(): Map<string, Override> | null;
+  write(overrides: ReadonlyMap<string, Override>): void;
+  /** Calls `onChange` when another tab writes. Returns a function that stops. */
+  watch(onChange: () => void): () => void;
+}
+/** One command's stored override: an array replaces the default, `{ add }` extends it. */
+type SerializedOverride = Array<SerializedBinding> | {
+  add: Array<SerializedBinding>;
+};
+/** User overrides as JSON-safe data, keyed by command id. What `exportKeymap()` returns. */
+type SerializedKeymap = {
+  version: 1;
+  overrides: Record<string, SerializedOverride>;
+};
+/** A registry's keymap: the keys in effect, and the user's changes to them. */
+interface CommandKeymap<Id extends string = string> {
+  /** Active bindings in effect: the default, with any user override applied. */
+  get(id: Id): ReadonlyArray<Binding>;
+  /** Replaces a command's bindings. `null` unbinds it; exactly the default forgets the override. */
+  set(id: Id, input: BindingInput | null): void;
+  /** Appends a binding, stored on top of the default so a default that changes still applies. */
+  add(id: Id, input: BindingInput): void;
+  /** Resets user overrides back to defaults for a specific command or all commands. */
+  reset(id?: Id): void;
+}
+/**
+ * One thing in a binding's way: a command in an overlapping scope with the
+ * same keys (`"exact"`) or with one binding starting the other (`"prefix"`),
+ * or the browser or operating system keeping the keys (`"reserved"`, which
+ * has no `id`).
+ */
+type Conflict<Id extends string = string> = {
+  /** Whether the bindings are identical or one is a prefix of the other. */
+  readonly kind: "exact" | "prefix";
+  /** ID of the conflicting command. */
+  readonly id: Id;
+  /** The conflicting command's binding. */
+  readonly binding: Binding;
+  /** Formatted display representation of that binding. */
+  readonly display: string;
+  /** The conflicting command's scope, if it has one. */
+  readonly scope?: string;
+} | {
+  readonly kind: "reserved";
+  /** The binding that was asked about. */
+  readonly binding: Binding;
+  /** Formatted display representation of that binding. */
+  readonly display: 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).
+ */
+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> {
+  /**
+   * Replaces the default `keys` of commands, by id, for rebinding commands the
+   * app did not define. `null` ships a command unbound. A user's own rebinding
+   * still wins.
+   *
+   * @example
+   * ```ts
+   * createCommands(commands, {
+   *   bindings: { "palette.open": "Mod+P", "doc.publish": null },
+   * });
+   * ```
+   */
+  bindings?: Partial<Record<Id, BindingInput | PlatformBindings | null>>;
+  /** Platform for modifier resolution and display formatting. Defaults to auto-detection. */
+  platform?: Platform;
+  /** Target element for key events. Defaults to `document`. */
+  target?: HTMLElement | Document | Window | null;
+  /**
+   * Where to keep user keymap overrides between visits, such as
+   * `webStorage("my-app.keys")`. They load on the first `mount()`, so the
+   * server render and the client's first render agree.
+   */
+  persist?: KeymapStore;
+  /**
+   * Whether single-key shortcuts (every step a printable character with no
+   * Control, Alt or Meta, such as `?` or `G then I`) are active. Defaults to
+   * `true`. WCAG 2.1.4 requires a way to turn them off.
+   */
+  singleKeyShortcuts?: boolean;
+  /** Display options for rendering shortcuts. */
+  display?: DisplayOptions;
+  /** Called whenever a command runs. */
+  onRun?: (context: CommandContext<Id>) => void;
+  /**
+   * Error handler called when a handler or `onRun` throws. Defaults to
+   * `console.error`.
+   */
+  onError?: (error: Error, context: CommandContext<Id>) => void;
+}
+/** 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): Command<Id> | undefined;
+  /** Returns all commands in definition order. */
+  list(): ReadonlyArray<Command<Id>>;
+  /**
+   * The list as the server rendered it: defaults only, and referentially
+   * stable. For a framework's server snapshot.
+   */
+  serverList(): ReadonlyArray<Command<Id>>;
+  /**
+   * Runs a command by ID. Returns `true` if executed. Passes `exclusive`
+   * barriers, which silence keys, not commands.
+   */
+  run(id: Id, options?: RunOptions): boolean;
+  /** 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.
+   */
+  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` and no command runs.
+   */
+  capture(onKey: KeyCapture): () => void;
+  /**
+   * Finds what stands in a binding's way: the platform reserving it (listed
+   * first), then commands in overlapping scopes with colliding keys.
+   */
+  conflicts(binding: BindingInput, options?: ConflictOptions<Id>): Array<Conflict<Id>>;
+  /** Returns the partially-typed sequences. Tracked only while something is subscribed. */
+  pending(): ReadonlyArray<PendingSequence<Id>>;
+  /** Subscribes to sequence progress changes. */
+  subscribePending(listener: () => void): () => void;
+  /** Starts listening for key events. Returns an unmount function. */
+  mount(): () => void;
+  /** Subscribes to registry changes. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+  /** Whether single-key shortcuts are active. See `CommandsOptions.singleKeyShortcuts`. */
+  readonly singleKeyShortcuts: boolean;
+  /** Turns single-key shortcuts on or off for every command (WCAG 2.1.4). */
+  setSingleKeyShortcuts(enabled: boolean): void;
+  /** Tears down listeners and clears all commands. */
+  destroy(): void;
+}
+//#endregion
+export { SequenceBinding as C, Chord as D, SerializedOverride as E, Key as O, ScopeOptions as S, SerializedKeymap as T, Override as _, CommandDefinition as a, RunBlockReason as b, CommandSource as c, Conflict as d, ConflictOptions as f, KeymapStore as g, KeyCapture as h, CommandContext as i, Platform as k, Commands as l, Json as m, BindingInput as n, CommandHandler as o, DisplayOptions as p, Command as r, CommandKeymap as s, Binding as t, CommandsOptions as u, PendingSequence as v, SerializedBinding as w, RunOptions as x, PlatformBindings as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklu/keys",
-  "version": "2.0.2",
+  "version": "2.2.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"
   }
 }