@joewinke/jatui 0.26.0 → 0.27.0

package/dist/utils/keyboardShortcutRegistry.d.ts

@@ -37,18 +37,64 @@
  *    browser (Chrome won't hand some of them to the page at all). The sidebar
  *    convention across JAT apps is `mod+\` — see `SIDEBAR_TOGGLE_KEY`.
  *
+ * Rebinding (jatui-voc3i.1): a definition with an `id` is rebindable. Its
+ * `key` is the DEFAULT; the effective binding is the user's override from a
+ * `BindingStore` (or `rebind()`), and registered entries re-resolve on every
+ * binding change, so components never re-register because a key moved.
+ * `declare()` makes ids known before their component mounts (a settings page
+ * can list a route's shortcuts without visiting the route). Combos are
+ * stored and compared in the canonical form `normalizeCombo()` produces.
+ * A stored entry that can't be parsed is never dropped silently: it is
+ * logged once (`console.warn`) and listed by `rejectedBindings()` with its
+ * raw value, so a settings page can show it.
+ *
+ * Conflicts (jatui-voc3i.2): `findConflicts(keys, { id | context })` and
+ * `allConflicts()` report collisions by how the stack resolves keys — same
+ * context is an error (one of them is dead), contexts that can be co-active
+ * (`contextGraph`; `global` is beneath everything) shadow with a warning, a
+ * modal upper context is info (they never compete), and `reserved`
+ * browser combos carry their own severity. `rebind()` rejects on any error.
+ *
+ * Beyond combos (jatui-voc3i.3): `onRelease` fires on the keyup of the
+ * same physical key (push-to-talk); `onModifierChange` reports held
+ * modifiers and is reset on blur; `registerHandler()` adds raw handlers
+ * (count prefixes, chords) that run inside the context walk after the
+ * context's combos, so modals still suppress them; `pushContext` takes a
+ * `layer` (frames sort by layer, then push order) and, for modal frames, a
+ * `passthrough` list of ids/combos that still reach the contexts beneath.
+ *
+ * Known divergences from the JAT IDE's legacy `shortcutParser` (an importer
+ * passed to `localStorageBindingStore({ migrate })` must account for them):
+ *  - `cmd`: the IDE maps `Cmd+K` to META on every platform; here `cmd` is
+ *    an alias of `mod` (Ctrl on Linux/Windows). Rewrite `cmd` → `meta`
+ *    when importing so a stored `Cmd+K` keeps meaning ⌘/Win.
+ *  - Physical-key fallback: the IDE falls back to `event.code` for LETTER
+ *    keys under any modifier (non-Latin layouts: Ctrl+K on a Cyrillic
+ *    layout). Here the `event.code` fallback applies only to alt combos and
+ *    to `` ` `` / Space; `ctrl+k` does not fire for `ctrl+л`.
+ *
  * Pure TypeScript, no Svelte runes and no DOM globals at import time, so it
  * is SSR-safe and unit-testable under plain node.
  */
 export type ShortcutModifier = 'mod' | 'meta' | 'ctrl' | 'shift' | 'alt' | 'cmd';
 export type ShortcutPlatform = 'mac' | 'other';
 export interface ShortcutDefinition {
+    /**
+     * Stable id. Required for rebinding and conflict reporting; optional
+     * otherwise. Registering one id twice in one context throws in
+     * dev and warns in prod (the later registration wins).
+     */
+    id?: string;
     /**
      * `KeyboardEvent.key` value (case-insensitive for letters), optionally
      * prefixed with modifiers: `'k'`, `'mod+k'`, `'shift+ArrowDown'`, `'?'`,
-     * `'mod+\\'`. Use `'+'` / `'mod++'` for the plus key itself.
+     * `'mod+\\'`. Use `'+'` / `'mod++'` for the plus key itself. An array
+     * binds several combos that all fire the action (`['j', 'ArrowDown']`).
+     * With an `id`, this is the default binding.
      */
-    key: string;
+    key: string | string[];
+    /** May the user rebind it? Default: true when `id` is set, false otherwise. */
+    rebindable?: boolean;
     /** Extra modifiers, merged with any parsed from `key`. `cmd` is an alias of `mod`. */
     modifiers?: ShortcutModifier | ShortcutModifier[];
     /** Shown in the overlay. */
@@ -70,12 +116,62 @@ export interface ShortcutDefinition {
     hidden?: boolean;
     /** Overrides the computed keycap label in the overlay (e.g. `'j / ↓'`). */
     label?: string;
+    /**
+     * Called on the `keyup` of the same PHYSICAL key (`event.code`) after this
+     * shortcut fired — whatever modifiers are still down, because on Linux an
+     * IME often swallows Ctrl before the keyup arrives. Push-to-talk is the
+     * use case. Needs `attach()` (or `handleKeyup`). A blur of the attached
+     * target clears the pending release WITHOUT calling it.
+     */
+    onRelease?: (event: KeyboardEvent) => void;
 }
 export interface PushContextOptions {
     /** Suppress every context beneath this one (including `global`) while pushed. */
     modal?: boolean;
     /** Overlay section title for this context. Default: the context name. */
     label?: string;
+    /**
+     * Modal only: shortcuts from the contexts beneath that still fire while
+     * this frame is pushed (a session overlay that keeps `mod+\\`). Each entry
+     * is a shortcut id or a combo; a combo matches physically against the
+     * lower entry's live binding. Raw handlers never pass through.
+     */
+    passthrough?: string[];
+    /**
+     * Stacking layer, default 0. Frames sort by layer, then push order, so an
+     * app-level surface pushed at `layer: 1` (a peek drawer, a command line)
+     * stays above any route context that mounts after it.
+     */
+    layer?: number;
+}
+/** Modifier keys currently held, as reported to `onModifierChange`. */
+export interface ModifierState {
+    alt: boolean;
+    ctrl: boolean;
+    shift: boolean;
+    meta: boolean;
+}
+/**
+ * Key handling that isn't a set of combos (count prefixes like `5j`, chords
+ * like `m<letter>`, `Alt+1..9` with an index). Runs INSIDE the context walk —
+ * after the context's combos — so a modal context still suppresses it. Never
+ * rebindable, never part of conflict detection.
+ */
+export interface RawShortcutHandler {
+    /** Context this handler belongs to. Default `'global'`. */
+    context?: string;
+    /** Return true when the event was handled: the walk stops and `preventDefault` is applied (unless opted out). */
+    handle: (event: KeyboardEvent) => boolean;
+    /** Called even while focus is in a text field. Default false. */
+    allowInInput?: boolean;
+    /** Call `preventDefault()` when `handle` returns true. Default true. */
+    preventDefault?: boolean;
+    /** Overlay rows this handler contributes (e.g. `{ key: 'm<letter>', description: 'Set mark' }`). */
+    describe?: () => {
+        key: string;
+        description: string;
+        group?: string;
+    }[];
 }
 /** Same shape as `KeyboardShortcutsOverlay`'s `ShortcutSection`. */
 export interface RegistrySection {
@@ -94,6 +190,12 @@ export interface ToSectionsOptions {
     scope?: 'active' | 'all';
     /** Drop shortcuts whose `enabled()` currently returns false. Default false. */
     onlyEnabled?: boolean;
+    /**
+     * Also list `declare()`d ids that no mounted component has registered yet
+     * (a route's shortcuts before the route is visited). With `scope: 'active'`
+     * only declarations in live contexts count. Default false.
+     */
+    includeDeclared?: boolean;
 }
 export interface ShortcutRegistryOptions {
     /** Force the platform (tests, SSR). Default: sniffed from `navigator`. */
@@ -102,11 +204,148 @@ export interface ShortcutRegistryOptions {
     contextLabels?: Record<string, string>;
     /** Called when an action throws or rejects. Default: `console.error`. */
     onError?: (error: unknown, shortcut: ShortcutDefinition) => void;
+    /** Where user overrides live. Without one, bindings are in-memory only. */
+    bindings?: BindingStore;
+    /**
+     * Throw on programming errors (duplicate id in one context) instead of
+     * warning. Default: `import.meta.env.DEV`, else `NODE_ENV !== 'production'`.
+     */
+    dev?: boolean;
+    /** Combos the browser or OS owns. Default: `BROWSER_RESERVED_COMBOS`. Pass `[]` to opt out. */
+    reserved?: ReservedCombo[];
+    /**
+     * Which contexts can be on the stack at the same time: `context → contexts
+     * it can sit ABOVE`. Transitive, and `global` is beneath everything. The IDE
+     * declares e.g. `{ 'route:tasks': ['global'], 'task-detail': ['route:tasks', 'route:inbox'] }`.
+     * Without it, every non-global context counts as co-active with `global` only.
+     */
+    contextGraph?: Record<string, string[]>;
+    /**
+     * Contexts that are always pushed `{ modal: true }`, for conflict reporting
+     * before they are ever pushed (a catalogue checked in a test). A context
+     * pushed modal at runtime is remembered as modal automatically.
+     */
+    modalContexts?: string[];
+    /**
+     * Replaces the "is this keystroke text entry?" test (default: the exported
+     * `isTypingTarget`). Compose with it to add editor hosts:
+     * `(t, e) => isTypingTarget(t) || !!(t as Element)?.closest?.('.monaco-editor')`.
+     */
+    isTypingTarget?: (target: EventTarget | null, event: KeyboardEvent) => boolean;
+    /**
+     * Called whenever the set of held modifiers changes (seen on keydown and
+     * keyup), and with everything released when the attached target blurs —
+     * so an Alt-held hint layer can't get stuck after Alt+Tab.
+     */
+    onModifierChange?: (state: ModifierState) => void;
 }
-/** Minimal event-target shape `attach()` needs (window, document, an element). */
+/** A combo the browser or OS owns. `block`: never delivered to the page; `warn`: delivered, but overriding it surprises users. */
+export interface ReservedCombo {
+    /** Combo in registry syntax (`'mod+t'`). Compared physically on the registry's platform. */
+    key: string;
+    reason: string;
+    severity: 'block' | 'warn';
+}
+/**
+ * Browser-owned combos. `mod+t/w/n` block: Chrome
+ * never hands them to the page. The editing/navigation combos (and Ctrl+B,
+ * the bookmarks bar) are delivered but warn.
+ */
+export declare const BROWSER_RESERVED_COMBOS: ReservedCombo[];
+/** Sparse user overrides: id → canonical combos. `[]` means "explicitly unbound". Missing id = default. */
+export type BindingOverrides = Record<string, string[]>;
+export interface BindingStore {
+    load(): BindingOverrides | Promise<BindingOverrides>;
+    save(overrides: BindingOverrides): void | Promise<void>;
+    /** Optional: another tab/device changed the bindings. Returns unsubscribe. */
+    subscribe?(listener: (overrides: BindingOverrides) => void): () => void;
+    /** Optional: stored entries the store could not use (surfaced by `registry.rejectedBindings()`). */
+    rejected?(): RejectedBinding[];
+}
+export interface BindingInfo {
+    id: string;
+    description: string;
+    context: string;
+    group?: string;
+    /** Canonical default combos. */
+    defaults: string[];
+    /** Canonical effective combos; `[]` when unbound. */
+    current: string[];
+    isCustom: boolean;
+    rebindable: boolean;
+}
+export type ShortcutConflictSeverity = 'error' | 'warning' | 'info';
+export interface ShortcutConflict {
+    /** Canonical combo, as passed in. */
+    combo: string;
+    /** The other definition's id (absent for fixed shortcuts and 'reserved'). */
+    id?: string;
+    /** The other definition's description, or the reserved combo's reason. */
+    description: string;
+    /** The other definition's context (`'browser'` for 'reserved'). */
+    context: string;
+    /**
+     * - `same-context`: both live in one context, so the older one is dead → error
+     * - `shadows`: the candidate's context sits above the other's; it wins while pushed → warning
+     * - `shadowed-by`: the other's context sits above the candidate's → warning
+     * - `modal-blocked`: the upper of the two contexts is modal, so they never compete → info
+     * - `reserved`: the browser/OS owns the combo → error (`block`) or warning (`warn`)
+     */
+    kind: 'same-context' | 'shadows' | 'shadowed-by' | 'modal-blocked' | 'reserved';
+    severity: ShortcutConflictSeverity;
+    /** `allConflicts()` only: the candidate side of the pair (`findConflicts` callers already know it). */
+    source?: {
+        id?: string;
+        description: string;
+        context: string;
+    };
+}
+export interface FindConflictsTarget {
+    /** The id being (re)bound — it never conflicts with itself. Its contexts are used when `context` is absent. */
+    id?: string;
+    /** Context of the candidate. Default: the id's registered/declared contexts, else `'global'`. */
+    context?: string;
+}
+export interface AllConflictsOptions {
+    /** Drop conflicts below this severity. Default `'info'` (everything). */
+    minSeverity?: ShortcutConflictSeverity;
+}
+export type RebindResult = {
+    ok: true;
+    binding: BindingInfo;
+    displaced: string[];
+    /** Non-blocking conflicts the new binding has (shadowing, modal, reserved warnings). */
+    conflicts: ShortcutConflict[];
+} | {
+    ok: false;
+    error: string;
+    conflicts: ShortcutConflict[];
+};
+export interface RebindOptions {
+    /**
+     * What to do when the new combo collides with an error-severity conflict.
+     * `'reject'` (default) fails with the conflicts; `'swap'` takes the combo
+     * away from the other id(s), leaving them with what remains; `'allow'`
+     * keeps both.
+     */
+    onConflict?: 'reject' | 'swap' | 'allow';
+}
+/** A stored binding that could not be used. `id` is `'*'` for a whole unreadable blob. */
+export interface RejectedBinding {
+    id: string;
+    /** The value exactly as stored (a combo string, a non-array value, or the raw blob). */
+    raw: unknown;
+    reason: string;
+}
+/** A declaration is a definition without an action — catalogue only. */
+export type ShortcutDeclaration = Omit<ShortcutDefinition, 'action'>;
+/**
+ * Minimal event-target shape `attach()` needs (window, document, an element).
+ * `attach()` listens for `keydown`, `keyup` and `blur`.
+ */
 export interface ShortcutEventTarget {
-    addEventListener(type: 'keydown', listener: (e: KeyboardEvent) => void): void;
-    removeEventListener(type: 'keydown', listener: (e: KeyboardEvent) => void): void;
+    addEventListener(type: 'keydown' | 'keyup' | 'blur', listener: (e: KeyboardEvent) => void): void;
+    removeEventListener(type: 'keydown' | 'keyup' | 'blur', listener: (e: KeyboardEvent) => void): void;
 }
 export interface ShortcutRegistry {
     /** Register one or many shortcuts. Returns an unregister function. */
@@ -115,19 +354,65 @@ export interface ShortcutRegistry {
     pushContext(name: string, options?: PushContextOptions): () => void;
     /** Context names that can currently fire, top of stack first. */
     activeContexts(): string[];
-    /** Listen for keydown on `target` (default `window`). Returns a detach function. */
+    /** Listen for keydown, keyup and blur on `target` (default `window`). Returns a detach function. */
     attach(target?: ShortcutEventTarget): () => void;
-    /** Dispatch an event by hand. Returns true when a shortcut fired. */
+    /** Dispatch an event by hand. Returns true when a shortcut (or raw handler) fired. */
     handleKeydown(event: KeyboardEvent): boolean;
+    /** Dispatch a keyup by hand. Returns true when a pending `onRelease` fired. */
+    handleKeyup(event: KeyboardEvent): boolean;
+    /** What `attach()` does on blur: drop pending releases, report all modifiers released. */
+    handleBlur(): void;
+    /**
+     * Register a raw handler (4.6). Consulted after its context's combos, in
+     * the same walk position; newest first. Returns unregister.
+     */
+    registerHandler(handler: RawShortcutHandler): () => void;
+    /** Keycap label for an id's live binding (`⌘K`, `Ctrl+K`); null when the id is unknown or unbound. */
+    formatBinding(id: string): string | null;
     /** Shortcuts grouped for `KeyboardShortcutsOverlay`'s `sections` prop. */
     toSections(options?: ToSectionsOptions): RegistrySection[];
     /** Every registration, in registration order. */
     list(): ShortcutDefinition[];
-    /** Keycap label for a shortcut on this registry's platform (`⌘K`, `Ctrl+K`). */
+    /** Keycap label for a shortcut on this registry's platform (`⌘K`, `Ctrl+K`). Uses the live binding for an id. */
     format(shortcut: ShortcutDefinition | string): string;
-    /** Notified after every register/unregister/push/pop. Returns unsubscribe. */
+    /** Notified after every register/unregister/push/pop, binding change and store load. Returns unsubscribe. */
     subscribe(listener: () => void): () => void;
     readonly platform: ShortcutPlatform;
+    /** Resolves once the binding store has loaded. Before then, defaults are in effect. */
+    readonly ready: Promise<void>;
+    /** Every known id (registered now, or catalogued via `declare`), first-seen order. */
+    bindings(): BindingInfo[];
+    binding(id: string): BindingInfo | undefined;
+    /**
+     * Change a binding (`null` or `[]` unbinds). Rejected, with the conflicts,
+     * when any conflict has severity `'error'` (another shortcut in the same
+     * context owns the combo, or the browser never delivers it) — unless
+     * `onConflict` says otherwise.
+     */
+    rebind(id: string, keys: string | string[] | null, options?: RebindOptions): RebindResult;
+    resetBinding(id: string): void;
+    resetAllBindings(): void;
+    /**
+     * Stored entries that could not be parsed (from the store and from the
+     * registry's own load), with the raw value and the reason. Each is also
+     * logged once with `console.warn`. Nothing is dropped silently.
+     */
+    rejectedBindings(): RejectedBinding[];
+    /** Make ids known before their component mounts. Returns an undeclare function. */
+    declare(defs: ShortcutDeclaration | ShortcutDeclaration[]): () => void;
+    /**
+     * Conflicts `keys` would have if bound to `target.id` (or to a new
+     * definition in `target.context`), against every registration and
+     * declaration plus the reserved list. Unparsable combos are skipped —
+     * check them with `validateCombo` first.
+     */
+    findConflicts(keys: string | string[], target?: FindConflictsTarget): ShortcutConflict[];
+    /**
+     * Every conflict among current registrations and declarations, each pair
+     * once (the newer definition is `source`). Run it with
+     * `{ minSeverity: 'error' }` in a test over an app's catalogue.
+     */
+    allConflicts(options?: AllConflictsOptions): ShortcutConflict[];
 }
 /** The sidebar-toggle convention. Ctrl+B is reserved by Chrome (bookmarks bar). */
 export declare const SIDEBAR_TOGGLE_KEY = "mod+\\";
@@ -142,10 +427,46 @@ interface ParsedCombo {
 export declare function detectPlatform(): ShortcutPlatform;
 /** Parse `'mod+shift+k'` (plus any extra modifiers) into a normalized combo. */
 export declare function parseCombo(key: string, extra?: ShortcutModifier | ShortcutModifier[]): ParsedCombo;
+/**
+ * Canonical, order-stable form used for storage and equality:
+ * `"alt+shift+s"`, `"mod+k"`, `"ctrl+\`"`, `"space"`, `"mod++"`. Modifier
+ * order is mod, meta, ctrl, alt, shift. `mod` is never introduced: a stored
+ * `Ctrl+K` stays `ctrl+k`. Throws on an unknown modifier (see `validateCombo`).
+ */
+export declare function normalizeCombo(key: string, extra?: ShortcutModifier | ShortcutModifier[]): string;
+/**
+ * Canonical combo for a live keydown (a settings "press the new shortcut"
+ * recorder). Null while only modifiers are down, or when the key can't be
+ * identified. Ctrl/Meta are reported literally (never `mod`). Uses the
+ * physical key when macOS Option (or a dead key / non-ASCII layout) hides it.
+ */
+export declare function comboFromEvent(event: KeyboardEvent, platform?: ShortcutPlatform): string | null;
+/**
+ * Structural validation for a user-entered binding. Null means valid,
+ * otherwise a human-readable reason. `requireModifier` demands Ctrl, Alt,
+ * Meta or mod (Shift alone doesn't count) — the IDE's rule for global ids.
+ */
+export declare function validateCombo(key: string, options?: {
+    requireModifier?: boolean;
+}): string | null;
 /** True when keystrokes on `target` are text entry (so bare-key shortcuts must not fire). */
 export declare function isTypingTarget(target: EventTarget | null | undefined): boolean;
-/** Keycap label: `⌘⇧K` on macOS, `Ctrl+Shift+K` elsewhere. */
-export declare function formatShortcut(shortcut: ShortcutDefinition | string, platform?: ShortcutPlatform): string;
+/** Keycap label: `⌘⇧K` on macOS, `Ctrl+Shift+K` elsewhere. Several keys join with `' / '`. */
+export declare function formatShortcut(shortcut: ShortcutDefinition | ShortcutDeclaration | string, platform?: ShortcutPlatform): string;
+/**
+ * Versioned localStorage `BindingStore`: `{ v: 1, bindings, rejected? }`.
+ * Tolerates corrupt JSON, a foreign shape and unavailable storage (private
+ * mode, SSR) — all read as "no overrides". `migrate` runs only when
+ * `storageKey` is absent, and its result (even an empty one) is written so
+ * it runs once. Entries it can't parse (from storage or from `migrate`) are
+ * warned once, exposed via `rejected()`, and kept in the stored `rejected`
+ * list so a later save doesn't lose them.
+ * `syncTabs` (default true) forwards other tabs' writes via `storage` events.
+ */
+export declare function localStorageBindingStore(storageKey: string, options?: {
+    migrate?: () => BindingOverrides | null;
+    syncTabs?: boolean;
+}): BindingStore;
 export declare function createShortcutRegistry(options?: ShortcutRegistryOptions): ShortcutRegistry;
 /** Lazily-created app-wide registry, for apps that want one without threading it through props. */
 export declare function getShortcutRegistry(): ShortcutRegistry;