@inklu/keys 2.1.0 → 3.0.0

package/dist/types-QEXldPnL.d.mts

@@ -1,398 +0,0 @@
-//#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 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>;
-/** 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 commands registry instance.
-   *
-   * @example
-   * ```ts
-   * run: ({ commands }) => {
-   *   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>;
-/**
- * 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
- * ids; a definition written on its own defaults to plain `string`.
- */
-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` — for commands that only make
-   * sense from their key, like a palette's own Close. It still runs and
-   * still appears in `list()`. Defaults to `false`.
-   */
-  hidden?: boolean;
-  /** Default key binding(s). */
-  keys?: BindingInput;
-  /** Scope required for this command to fire. Omit for global, or `"*"` to bypass exclusive scopes. */
-  scope?: string;
-  /**
-   * 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
-   * as `Mod+K` does not trigger the browser's own shortcut on the way.
-   */
-  preventDefault?: boolean;
-  /**
-   * 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;
-  /** Timeout in milliseconds between sequence steps. Defaults to `1000`. */
-  sequenceTimeout?: number;
-  /**
-   * 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> {
-  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. Only chords appear here: the
-   * attribute separates alternatives with spaces, so it cannot express a
-   * sequence. Use `spoken` to announce those.
-   */
-  readonly aria: string;
-  /**
-   * Every binding phrased for a screen reader, alternatives joined by
-   * `" or "` — e.g. `"Control+K"` or `"G then I"`. Suited to visually hidden
-   * text or `aria-description`, and 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;
-}
-/** Storage interface for persisting keymap overrides. */
-interface KeymapStorage {
-  getItem: (key: string) => string | null;
-  setItem: (key: string, value: string) => void;
-  removeItem: (key: string) => void;
-}
-/** Configuration for persisting keymap overrides. */
-interface KeymapPersistence {
-  /** Storage key name. Defaults to `"inklu.keys"`. */
-  key?: string;
-  /** Getter returning the storage implementation lazily. */
-  storage: () => KeymapStorage | null;
-}
-/** 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. `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): 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, 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, input: BindingInput): void;
-  /** Resets user overrides back to defaults for a specific command or all commands. */
-  reset(id?: Id): void;
-  /** Exports user overrides as JSON-serializable data. */
-  export(): SerializedKeymap;
-  /**
-   * Imports user overrides, replacing current overrides and saving to
-   * storage. Accepts `export()` output from this and earlier releases.
-   */
-  import(data: Json): void;
-}
-/**
- * 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> {
-  /**
-   * Replaces the default `keys` a command was defined with, keyed by command
-   * id. Lets an app rebind commands it did not define — a package ships the
-   * behaviour, the app decides which key reaches it — and an unknown id is a
-   * compile error rather than a silent no-op. `null` ships the command with
-   * no default binding at all.
-   *
-   * These are defaults, applied before persisted overrides load, so a user's
-   * own rebinding still wins.
-   *
-   * @example
-   * ```ts
-   * createCommands(commands, {
-   *   bindings: { "palette.open": "Mod+P", "doc.publish": null },
-   * });
-   * ```
-   */
-  bindings?: Partial<Record<Id, BindingInput | 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;
-  /**
-   * Persistence configuration for user keymap overrides. Overrides are read
-   * on the first `mount()` rather than at creation, so the server render and
-   * the client's first render agree and hydration never mismatches; the
-   * registry notifies subscribers once they load.
-   */
-  persist?: KeymapPersistence;
-  /**
-   * Whether single-key shortcuts — bindings where every step is 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 these off
-   * for speech-input and motor-impaired users; wire a setting to
-   * `commands.setSingleKeyShortcuts()`.
-   */
-  singleKeyShortcuts?: boolean;
-  /** Display options for rendering shortcuts. */
-  display?: DisplayOptions;
-  /**
-   * Callback fired whenever a command runs.
-   *
-   * @example
-   * ```ts
-   * createCommands(definitions, {
-   *   onRun: ({ id }) => logRun(id),
-   * });
-   * ```
-   */
-  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: 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. 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 `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>>;
-  /** 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, 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 };