@inklu/keys 2.0.2 → 2.2.0

package/dist/attributes-DotLr2MW.d.mts

@@ -1,426 +0,0 @@
-import { FormatDisplayOptions, Hotkey as Hotkey$1, HotkeySequence } from "@tanstack/hotkeys";
-//#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;
-}
-/** 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;
-};
-/** Trigger source for a command. */
-type CommandSource = "keyboard" | "api" | "dom";
-/** Context passed to a command's `run` 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.setEnabled("doc.publish", false);
-   *   commands.run("doc.save");
-   * }
-   * ```
-   */
-  readonly commands: Commands<Id>;
-}
-/**
- * Definition of a command and its default configuration.
- *
- * `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;
-  /** 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
-   * 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 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.
-   */
-  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>;
-}
-/** 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 the command is enabled. */
-  readonly enabled: boolean;
-  /** Whether the command is enabled and in an active scope. */
-  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;
-  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;
-}
-/**
- * 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. */
-  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>;
-  /**
-   * 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;
-  /**
-   * 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;
-  /** Resets user overrides back to defaults for a specific command or all commands. */
-  reset(id?: Id | (string & {})): 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;
-}
-//#endregion
-//#region src/registry.d.ts
-/** 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 command, its `when()` guard, 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. */
-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. */
-  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.
-   */
-  serverList(): ReadonlyArray<Command<Id>>;
-  /** Runs a command by ID. Returns `true` if executed. */
-  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;
-  /** Activates a scope until the returned disposal function is called. */
-  pushScope(name: string, options?: ScopeOptions): () => 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. */
-  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 command registrations. */
-  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 };

package/dist/index-BTgscYdI.d.mts

@@ -1,116 +0,0 @@
-import { C as Command, D as Conflict, F as SequenceBinding, N as Platform, S as Chord, a as Commands, b as Binding } from "./attributes-DotLr2MW.mjs";
-import { Hotkey } from "@tanstack/hotkeys";
-//#region src/bindings.d.ts
-/**
- * Creates a sequence binding from ordered hotkey steps.
- *
- * @example
- * ```ts
- * keys: seq("G", "I")
- * ```
- */
-declare function seq(...steps: Array<Hotkey>): 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.
- * Shift does not count as a modifier here: `Shift+A` still types a character.
- */
-declare function isSingleKeyBinding(binding: Binding, platform?: Platform): 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/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.
- *
- * @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/scopes.d.ts
-/** Wildcard scope identifier for commands that remain active across exclusive scopes. */
-declare const ALWAYS_SCOPE = "*";
-//#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 { RebindState as a, BindingValidation as c, validateBinding as d, RebindOptions as i, isSingleKeyBinding as l, ALWAYS_SCOPE as n, Rebinder as o, RebindMode as r, createRebinder as s, matchCommands as t, seq as u };