@inklu/keys 2.2.0 → 3.0.0

package/dist/{types-D-hUKGoN.d.mts → types-BxMI3b4a.d.mts}

@@ -11,12 +11,8 @@ type Letter = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" |
 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}]`;
+/** 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">}`;
 /**
@@ -53,13 +49,6 @@ 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 handler. */
@@ -84,17 +73,6 @@ type CommandHandler<Id extends string = string> = (context: CommandContext<Id>)
 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.
@@ -103,26 +81,11 @@ interface CommandDefinition<Id extends string = string> {
   /** 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.
+   * 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;
-  /** 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
@@ -134,12 +97,6 @@ interface CommandDefinition<Id extends string = string> {
 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>;
@@ -149,37 +106,21 @@ interface Command<Id extends string = string> {
   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;
+  /** 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;
 }
-/** 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>;
+  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> {
@@ -187,19 +128,14 @@ interface CommandKeymap<Id extends string = string> {
   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`).
+ * 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"`).
  */
-type Conflict<Id extends string = string> = {
-  /** Whether the bindings are identical or one is a prefix of the other. */
+interface Conflict<Id extends string = string> {
   readonly kind: "exact" | "prefix";
   /** ID of the conflicting command. */
   readonly id: Id;
@@ -209,13 +145,7 @@ type Conflict<Id extends string = string> = {
   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. */
@@ -245,19 +175,6 @@ interface RunOptions {
  * 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> {
   /**
@@ -275,8 +192,6 @@ interface CommandsOptions<Id extends string = string> {
   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
@@ -289,15 +204,8 @@ interface CommandsOptions<Id extends string = string> {
    * `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. */
+  /** Called before any command runs, for logging or analytics. */
   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> {
@@ -317,8 +225,6 @@ interface Commands<Id extends string = string> {
    * 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;
   /**
@@ -333,15 +239,8 @@ interface Commands<Id extends string = string> {
    * 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.
-   */
+  /** Finds the commands in overlapping scopes whose keys collide with a binding. */
   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. */
@@ -354,4 +253,4 @@ interface Commands<Id extends string = string> {
   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 };
+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.2.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",