@inklu/keys 2.1.0 → 2.2.0

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

@@ -1,15 +1,11 @@
 //#region src/chord.d.ts
+/** Chords: reading one from text or a keypress, matching the two, and writing one back. */
 /**
- * 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.
+ * 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";
@@ -38,6 +34,19 @@ interface SequenceBinding {
 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. */
@@ -48,7 +57,7 @@ type Json = string | number | boolean | null | ReadonlyArray<Json> | {
 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`. */
+  /** Symbols such as `⌘` and `↩` rather than names such as `Cmd`. Defaults to `true`. */
   useSymbols?: boolean;
 }
 /** Trigger source for a command. */
@@ -63,26 +72,14 @@ interface CommandContext<Id extends string = string> {
   readonly event?: Event;
   /** Specific binding that triggered the command. */
   readonly binding?: Binding;
-  /**
-   * The commands registry instance.
-   *
-   * @example
-   * ```ts
-   * run: ({ commands }) => {
-   *   commands.run("doc.save");
-   * }
-   * ```
-   */
+  /** 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. `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`.
+ * `Id` is the registry's id union, which `createCommands` fills in.
  */
 interface CommandDefinition<Id extends string = string> {
   /** Human-readable title. */
@@ -94,37 +91,42 @@ interface CommandDefinition<Id extends string = 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`.
+   * Leave the command out of `matchCommands`. It still runs and still appears
+   * in `list()`. Defaults to `false`.
    */
   hidden?: boolean;
-  /** Default key binding(s). */
-  keys?: BindingInput;
+  /**
+   * 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. 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.
+   * 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, 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.
+   * 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;
   /**
-   * 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.
+   * 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>;
 }
@@ -145,16 +147,11 @@ interface Command<Id extends string = string> {
   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.
-   */
+  /** Value for the `aria-keyshortcuts` attribute. Chords only: it cannot express a sequence. */
   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.
+   * 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. */
@@ -162,76 +159,63 @@ interface Command<Id extends string = string> {
   /** 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;
+/** 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>;
 }
-/** 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;
+/** 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>;
 };
-/**
- * Persisted user overrides, keyed by command id. `version` lets a release
- * skip a format it does not know instead of misreading it.
- */
+/** User overrides as JSON-safe data, keyed by command id. What `exportKeymap()` returns. */
 type SerializedKeymap = {
   version: 1;
   overrides: Record<string, SerializedOverride>;
 };
-/** Keymap interface for querying, modifying, and persisting keybindings. */
+/** 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. 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.
-   */
+  /** Replaces a command's bindings. `null` unbinds it; exactly the default forgets the override. */
   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.
-   */
+  /** 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;
-  /** 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.
+ * 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 ConflictKind = "exact" | "prefix";
-/** Details of a conflict between commands whose bindings collide in overlapping scopes. */
-interface Conflict<Id extends string = string> {
+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;
-  /** Whether the bindings are identical or one is a prefix of the other. */
-  readonly kind: ConflictKind;
-  /** Formatted display representation of the binding. */
+  /** Formatted display representation of that binding. */
   readonly display: string;
-  /** Overlapping scope where conflict occurs, if any. */
+  /** 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. */
@@ -246,8 +230,7 @@ interface ScopeOptions {
 }
 /**
  * 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.
+ * 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. */
@@ -278,14 +261,9 @@ interface PendingSequence<Id extends string = 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.
+   * 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
@@ -294,38 +272,26 @@ interface CommandsOptions<Id extends string = string> {
    * });
    * ```
    */
-  bindings?: Partial<Record<Id, BindingInput | 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;
   /**
-   * 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.
+   * 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?: KeymapPersistence;
+  persist?: KeymapStore;
   /**
-   * 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()`.
+   * 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;
-  /**
-   * Callback fired whenever a command runs.
-   *
-   * @example
-   * ```ts
-   * createCommands(definitions, {
-   *   onRun: ({ id }) => logRun(id),
-   * });
-   * ```
-   */
+  /** Called whenever a command runs. */
   onRun?: (context: CommandContext<Id>) => void;
   /**
    * Error handler called when a handler or `onRun` throws. Defaults to
@@ -342,17 +308,13 @@ interface Commands<Id extends string = string> {
   /** 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.
+   * 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. 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.
+   * 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. */
@@ -360,23 +322,20 @@ interface Commands<Id extends string = string> {
   /** 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`.
+   * 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` first and no command's keys are live, `"*"`
-   * ones included. This is what recording a new shortcut is built on.
+   * keypress goes to `onKey` and no command runs.
    */
   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"`).
+   * 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. */
@@ -395,4 +354,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, 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 };
+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.1.0",
+  "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",