@inklu/keys 2.1.0 → 3.0.0

package/dist/types-BxMI3b4a.d.mts

@@ -0,0 +1,256 @@
+//#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"`). */
+type Key = Letter | Digit | FunctionKey | Punctuation | (typeof NAMED_KEYS)[number];
+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;
+};
+/** 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;
+  /**
+   * 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;
+  /**
+   * Whether a text field keeps the keys: inputs, selects, contenteditable
+   * elements and widgets with a text-entry ARIA role. Defaults to `true`,
+   * except for `Escape`. Set `false` on a command that should fire there too.
+   */
+  ignoreInputs?: 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 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;
+  /** 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;
+}
+/** Where user overrides are kept between visits. `webStorage()` makes one. */
+interface KeymapStore {
+  /** The stored overrides by command id: empty when there are none, `null` when they cannot be read. */
+  read(): Map<string, ReadonlyArray<Binding>> | null;
+  write(overrides: ReadonlyMap<string, ReadonlyArray<Binding>>): void;
+}
+/** User overrides as JSON-safe data, keyed by command id. What `exportKeymap()` returns. */
+type SerializedKeymap = {
+  version: 1;
+  overrides: Record<string, Array<SerializedBinding>>;
+};
+/** 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;
+  /** Resets user overrides back to defaults for a specific command or all commands. */
+  reset(id?: Id): void;
+}
+/**
+ * A command in an overlapping scope whose keys stand in a binding's way: the
+ * same keys (`"exact"`), or one binding starting the other (`"prefix"`).
+ */
+interface Conflict<Id extends string = string> {
+  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;
+}
+/** 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";
+/** 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;
+  /**
+   * 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;
+  /** Called before any command runs, for logging or analytics. */
+  onRun?: (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;
+  /** 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 the commands in overlapping scopes whose keys collide with a binding. */
+  conflicts(binding: BindingInput, options?: ConflictOptions<Id>): Array<Conflict<Id>>;
+  /** 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 { Chord as C, SerializedKeymap as S, Platform as T, RunBlockReason as _, CommandDefinition as a, SequenceBinding as b, CommandSource as c, Conflict as d, ConflictOptions as f, PlatformBindings as g, KeymapStore as h, CommandContext as i, Commands as l, KeyCapture as m, BindingInput as n, CommandHandler as o, Json as p, Command as r, CommandKeymap as s, Binding as t, CommandsOptions as u, RunOptions as v, Key as w, SerializedBinding as x, ScopeOptions as y };

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@inklu/keys",
-  "version": "2.1.0",
-  "description": "A command system for the web — typed commands, portable keybindings, scopes, sequences, conflict detection, rebinding, and platform-aware display.",
+  "version": "3.0.0",
+  "description": "A command system for the web: typed commands, portable keybindings, scopes, sequences, conflict detection, rebinding and platform-aware display.",
   "keywords": [
     "accessibility",
-    "command-palette",
     "commands",
     "hotkeys",
     "keybindings",

package/dist/index-3d9f54ln.d.mts

@@ -1,156 +0,0 @@
-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 chords.
- *
- * @example
- * ```ts
- * keys: seq("G", "I")
- * ```
- */
-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.
- */
-declare function isSingleKeyBinding(binding: Binding): boolean;
-/** Validation result for a hotkey binding. */
-interface BindingValidation {
-  readonly valid: boolean;
-  readonly errors: ReadonlyArray<string>;
-  readonly warnings: ReadonlyArray<string>;
-}
-/** 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";
-/** Current state of a rebinding session. */
-interface RebindState<Id extends string = string> {
-  /** Whether keys are actively being recorded. */
-  readonly recording: boolean;
-  /** Most recently captured binding. */
-  readonly binding: Binding | null;
-  /** Captured steps in the current sequence session. */
-  readonly steps: ReadonlyArray<Chord>;
-  /** Conflicting commands for the captured binding. */
-  readonly conflicts: ReadonlyArray<Conflict<Id>>;
-}
-/** Options for creating a rebinder. */
-interface RebindOptions<Id extends string = string> {
-  /** Capture mode. Defaults to `"chord"`. */
-  mode?: RebindMode;
-  /** Whether to write the recorded (or cleared) binding into the keymap. Defaults to `true`. */
-  apply?: boolean;
-  /** Whether to append rather than replace existing bindings. Defaults to `false`. */
-  add?: boolean;
-  /** Prevent applying bindings that conflict with other commands. Defaults to `false`. */
-  rejectConflicts?: boolean;
-  /** Ignore key events from inputs while recording. Defaults to `true`. */
-  ignoreInputs?: boolean;
-  /** Inactivity timeout in milliseconds before a sequence commits. */
-  idleTimeout?: number;
-  /** Callback fired when a binding is recorded. */
-  onRecord?: (binding: Binding, conflicts: ReadonlyArray<Conflict<Id>>) => void;
-  /** Callback fired when recording is cancelled. */
-  onCancel?: () => void;
-  /** Callback fired when Backspace or Delete clears the binding while recording. */
-  onClear?: () => void;
-}
-/** Controller instance for managing a rebinding session. */
-interface Rebinder<Id extends string = string> {
-  /** Begins capturing keys. */
-  start: () => void;
-  /** Stops capturing keys without recording. */
-  stop: () => void;
-  /** Stops capturing keys and reports cancellation. */
-  cancel: () => void;
-  /** Commits the currently captured sequence steps. */
-  commit: () => void;
-  /** Current rebinder state. */
-  readonly state: RebindState<Id>;
-  /** Subscribes to rebinder state changes. Returns an unsubscribe function. */
-  subscribe: (listener: () => void) => () => void;
-  /** Destroys the rebinder and cleans up listeners. */
-  destroy: () => void;
-}
-/**
- * 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
- * const rebinder = createRebinder(commands, "palette.open", {
- *   onRecord: (binding, conflicts) => {
- *     if (conflicts.length) console.warn("Conflict with", conflicts[0].id);
- *   },
- * });
- * rebinder.start();
- * ```
- */
-declare function createRebinder<Id extends string>(registry: Commands<Id>, id: Id, options?: RebindOptions<Id>): Rebinder<Id>;
-//#endregion
-//#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
-/**
- * Filters commands for a search query, as a command palette does, leaving
- * out `hidden` ones. Every word of the query must appear somewhere in the
- * command — title, description, group, keywords, id or displayed shortcut —
- * in any order. Title matches come first: titles starting with the query,
- * then titles containing every word, then the rest; each tier keeps the
- * list's own order. An empty query returns every visible command.
- *
- * @example
- * ```ts
- * const results = matchCommands(commands.list(), "go inbox");
- * ```
- */
-declare function matchCommands<Id extends string>(commands: ReadonlyArray<Command<Id>>, query: string): Array<Command<Id>>;
-//#endregion
-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 };