@joewinke/jatui 0.22.0 → 0.24.0

package/dist/utils/keyboardShortcutRegistry.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Keyboard shortcut registry — the data source `KeyboardShortcutsOverlay`
+ * was always missing (jatui-m4uz3.6, harvested from chimaro's
+ * keyboardShortcutManager with its app-specific default registrations
+ * stripped).
+ *
+ * One registry per app (or use the lazy `getShortcutRegistry()` singleton).
+ * Components register shortcuts against a CONTEXT and get back an
+ * unregister function, which is exactly what a Svelte `$effect` wants to
+ * return:
+ *
+ *   $effect(() => registry.register([
+ *     { key: 'j', description: 'Next item', context: 'list', action: next },
+ *     { key: 'mod+k', description: 'Search', action: openPalette, allowInInput: true },
+ *   ]));
+ *
+ * Contexts form a STACK. `global` is always the bottom. `pushContext()`
+ * returns a pop function. When a key is pressed the stack is walked from
+ * the top down and the first matching, enabled shortcut wins — so a
+ * context higher up shadows the same combo lower down. A context pushed
+ * with `{ modal: true }` stops the walk: everything beneath it (including
+ * `global`) is suppressed while it is on the stack — that is how a dialog
+ * keeps page shortcuts from firing behind it.
+ *
+ * Sharp edges handled here so every app doesn't re-learn them:
+ *  - Input focus: shortcuts don't fire while typing in a text input,
+ *    textarea, select or contenteditable (checkboxes/buttons/ranges don't
+ *    count as typing). Opt back in per shortcut with `allowInInput`.
+ *  - IME composition and already-handled (`defaultPrevented`) events are
+ *    ignored.
+ *  - Modifiers: `mod` is ⌘ on macOS and Ctrl elsewhere. Matching is exact —
+ *    `mod+k` does not fire on `mod+shift+k`. Shift is implied by printable
+ *    symbols (`?` is Shift+/ on most layouts), so `key: '?'` matches without
+ *    listing `shift`. macOS Option rewrites `event.key` (Alt+K → "˚"), so
+ *    alt combos fall back to `event.code`.
+ *  - Browser-reserved combos: Ctrl+B / Ctrl+T / Ctrl+W / Ctrl+N belong to the
+ *    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`.
+ *
+ * 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 {
+    /**
+     * `KeyboardEvent.key` value (case-insensitive for letters), optionally
+     * prefixed with modifiers: `'k'`, `'mod+k'`, `'shift+ArrowDown'`, `'?'`,
+     * `'mod+\\'`. Use `'+'` / `'mod++'` for the plus key itself.
+     */
+    key: string;
+    /** Extra modifiers, merged with any parsed from `key`. `cmd` is an alias of `mod`. */
+    modifiers?: ShortcutModifier | ShortcutModifier[];
+    /** Shown in the overlay. */
+    description: string;
+    action: (event: KeyboardEvent) => void | Promise<void>;
+    /** Context this shortcut belongs to. Default `'global'`. */
+    context?: string;
+    /** Live predicate — a disabled shortcut is skipped and the walk continues. */
+    enabled?: () => boolean;
+    /** Fire even while focus is in a text field. Default false. */
+    allowInInput?: boolean;
+    /** Fire on auto-repeat keydowns (held key). Default true. */
+    allowRepeat?: boolean;
+    /** Call `preventDefault()` when this shortcut fires. Default true. */
+    preventDefault?: boolean;
+    /** Overlay section title. Defaults to the context's label. */
+    group?: string;
+    /** Register but leave out of the overlay. */
+    hidden?: boolean;
+    /** Overrides the computed keycap label in the overlay (e.g. `'j / ↓'`). */
+    label?: string;
+}
+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;
+}
+/** Same shape as `KeyboardShortcutsOverlay`'s `ShortcutSection`. */
+export interface RegistrySection {
+    title: string;
+    shortcuts: {
+        key: string;
+        description: string;
+    }[];
+}
+export interface ToSectionsOptions {
+    /**
+     * `'active'` (default) lists only contexts that can fire right now —
+     * the live part of the stack, top first. `'all'` lists every context
+     * with registrations.
+     */
+    scope?: 'active' | 'all';
+    /** Drop shortcuts whose `enabled()` currently returns false. Default false. */
+    onlyEnabled?: boolean;
+}
+export interface ShortcutRegistryOptions {
+    /** Force the platform (tests, SSR). Default: sniffed from `navigator`. */
+    platform?: ShortcutPlatform;
+    /** Overlay labels for contexts. `global` defaults to `'General'`. */
+    contextLabels?: Record<string, string>;
+    /** Called when an action throws or rejects. Default: `console.error`. */
+    onError?: (error: unknown, shortcut: ShortcutDefinition) => void;
+}
+/** Minimal event-target shape `attach()` needs (window, document, an element). */
+export interface ShortcutEventTarget {
+    addEventListener(type: 'keydown', listener: (e: KeyboardEvent) => void): void;
+    removeEventListener(type: 'keydown', listener: (e: KeyboardEvent) => void): void;
+}
+export interface ShortcutRegistry {
+    /** Register one or many shortcuts. Returns an unregister function. */
+    register(shortcuts: ShortcutDefinition | ShortcutDefinition[]): () => void;
+    /** Push a context onto the stack. Returns a pop function (idempotent). */
+    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. */
+    attach(target?: ShortcutEventTarget): () => void;
+    /** Dispatch an event by hand. Returns true when a shortcut fired. */
+    handleKeydown(event: KeyboardEvent): boolean;
+    /** 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`). */
+    format(shortcut: ShortcutDefinition | string): string;
+    /** Notified after every register/unregister/push/pop. Returns unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    readonly platform: ShortcutPlatform;
+}
+/** The sidebar-toggle convention. Ctrl+B is reserved by Chrome (bookmarks bar). */
+export declare const SIDEBAR_TOGGLE_KEY = "mod+\\";
+interface ParsedCombo {
+    key: string;
+    mod: boolean;
+    meta: boolean;
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+}
+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;
+/** 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;
+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;
+export {};

package/dist/utils/keyboardShortcutRegistry.js

@@ -0,0 +1,365 @@
+/**
+ * Keyboard shortcut registry — the data source `KeyboardShortcutsOverlay`
+ * was always missing (jatui-m4uz3.6, harvested from chimaro's
+ * keyboardShortcutManager with its app-specific default registrations
+ * stripped).
+ *
+ * One registry per app (or use the lazy `getShortcutRegistry()` singleton).
+ * Components register shortcuts against a CONTEXT and get back an
+ * unregister function, which is exactly what a Svelte `$effect` wants to
+ * return:
+ *
+ *   $effect(() => registry.register([
+ *     { key: 'j', description: 'Next item', context: 'list', action: next },
+ *     { key: 'mod+k', description: 'Search', action: openPalette, allowInInput: true },
+ *   ]));
+ *
+ * Contexts form a STACK. `global` is always the bottom. `pushContext()`
+ * returns a pop function. When a key is pressed the stack is walked from
+ * the top down and the first matching, enabled shortcut wins — so a
+ * context higher up shadows the same combo lower down. A context pushed
+ * with `{ modal: true }` stops the walk: everything beneath it (including
+ * `global`) is suppressed while it is on the stack — that is how a dialog
+ * keeps page shortcuts from firing behind it.
+ *
+ * Sharp edges handled here so every app doesn't re-learn them:
+ *  - Input focus: shortcuts don't fire while typing in a text input,
+ *    textarea, select or contenteditable (checkboxes/buttons/ranges don't
+ *    count as typing). Opt back in per shortcut with `allowInInput`.
+ *  - IME composition and already-handled (`defaultPrevented`) events are
+ *    ignored.
+ *  - Modifiers: `mod` is ⌘ on macOS and Ctrl elsewhere. Matching is exact —
+ *    `mod+k` does not fire on `mod+shift+k`. Shift is implied by printable
+ *    symbols (`?` is Shift+/ on most layouts), so `key: '?'` matches without
+ *    listing `shift`. macOS Option rewrites `event.key` (Alt+K → "˚"), so
+ *    alt combos fall back to `event.code`.
+ *  - Browser-reserved combos: Ctrl+B / Ctrl+T / Ctrl+W / Ctrl+N belong to the
+ *    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`.
+ *
+ * Pure TypeScript, no Svelte runes and no DOM globals at import time, so it
+ * is SSR-safe and unit-testable under plain node.
+ */
+/** The sidebar-toggle convention. Ctrl+B is reserved by Chrome (bookmarks bar). */
+export const SIDEBAR_TOGGLE_KEY = 'mod+\\';
+const GLOBAL = 'global';
+export function detectPlatform() {
+    if (typeof navigator === 'undefined')
+        return 'other';
+    const nav = navigator;
+    const p = nav.userAgentData?.platform || nav.platform || nav.userAgent || '';
+    return /mac|iphone|ipad|ipod/i.test(p) ? 'mac' : 'other';
+}
+/** Parse `'mod+shift+k'` (plus any extra modifiers) into a normalized combo. */
+export function parseCombo(key, extra) {
+    const combo = { key: '', mod: false, meta: false, ctrl: false, shift: false, alt: false };
+    const mods = extra === undefined ? [] : Array.isArray(extra) ? [...extra] : [extra];
+    let base = key;
+    if (key.length > 1) {
+        // `mod++` → modifiers 'mod', key '+'. A lone '+' never splits.
+        const parts = key.endsWith('++') ? [...key.slice(0, -2).split('+'), '+'] : key.split('+');
+        base = parts.pop() ?? '';
+        for (const p of parts) {
+            const m = p.trim().toLowerCase();
+            if (m === 'mod' || m === 'cmd' || m === 'meta' || m === 'ctrl' || m === 'shift' || m === 'alt') {
+                mods.push(m);
+            }
+            else if (m === 'control')
+                mods.push('ctrl');
+            else if (m === 'option')
+                mods.push('alt');
+            else if (m)
+                throw new Error(`keyboardShortcutRegistry: unknown modifier "${p}" in "${key}"`);
+        }
+    }
+    for (const m of mods) {
+        if (m === 'mod' || m === 'cmd')
+            combo.mod = true;
+        else
+            combo[m] = true;
+    }
+    combo.key = normalizeKey(base);
+    return combo;
+}
+function normalizeKey(key) {
+    if (key === 'Esc')
+        return 'escape';
+    if (key === 'Space' || key === 'Spacebar')
+        return ' ';
+    if (key === 'Del')
+        return 'delete';
+    return key.toLowerCase();
+}
+/** A single printable non-letter (`?`, `/`, `\`, `1`): its shift state is baked into the char. */
+function isSymbolKey(key) {
+    return key.length === 1 && key.toLowerCase() === key.toUpperCase() && key !== ' ';
+}
+function codeToKey(code) {
+    if (!code)
+        return null;
+    if (/^Key[A-Z]$/.test(code))
+        return code.slice(3).toLowerCase();
+    if (/^Digit\d$/.test(code))
+        return code.slice(5);
+    if (code === 'Backslash')
+        return '\\';
+    if (code === 'Slash')
+        return '/';
+    return null;
+}
+function matches(event, combo, platform) {
+    const evKey = normalizeKey(event.key ?? '');
+    let keyHit = evKey === combo.key;
+    // macOS Option (and some layouts) rewrite event.key for alt combos — fall
+    // back to the physical key when alt is part of the shortcut.
+    if (!keyHit && combo.alt)
+        keyHit = codeToKey(event.code) === combo.key;
+    if (!keyHit)
+        return false;
+    const wantMeta = combo.meta || (combo.mod && platform === 'mac');
+    const wantCtrl = combo.ctrl || (combo.mod && platform !== 'mac');
+    if (!!event.metaKey !== wantMeta)
+        return false;
+    if (!!event.ctrlKey !== wantCtrl)
+        return false;
+    if (!!event.altKey !== combo.alt)
+        return false;
+    // `?` arrives as Shift+/ — don't demand the shortcut spell that out.
+    if (!combo.shift && isSymbolKey(combo.key))
+        return true;
+    return !!event.shiftKey === combo.shift;
+}
+const NON_TEXT_INPUT_TYPES = new Set([
+    'button', 'checkbox', 'color', 'file', 'hidden', 'image', 'radio', 'range', 'reset', 'submit'
+]);
+/** True when keystrokes on `target` are text entry (so bare-key shortcuts must not fire). */
+export function isTypingTarget(target) {
+    const el = target;
+    if (!el || typeof el !== 'object')
+        return false;
+    if (el.isContentEditable)
+        return true;
+    const tag = typeof el.tagName === 'string' ? el.tagName.toUpperCase() : '';
+    if (tag === 'TEXTAREA' || tag === 'SELECT')
+        return true;
+    if (tag === 'INPUT')
+        return !NON_TEXT_INPUT_TYPES.has(String(el.type ?? 'text').toLowerCase());
+    return false;
+}
+const KEY_GLYPHS = {
+    escape: 'Esc',
+    ' ': 'Space',
+    delete: 'Del',
+    backspace: '⌫',
+    enter: 'Enter',
+    tab: 'Tab',
+    arrowup: '↑',
+    arrowdown: '↓',
+    arrowleft: '←',
+    arrowright: '→',
+    pageup: 'PgUp',
+    pagedown: 'PgDn',
+    home: 'Home',
+    end: 'End'
+};
+/** Keycap label: `⌘⇧K` on macOS, `Ctrl+Shift+K` elsewhere. */
+export function formatShortcut(shortcut, platform = detectPlatform()) {
+    const def = typeof shortcut === 'string' ? null : shortcut;
+    if (def?.label)
+        return def.label;
+    const combo = def ? parseCombo(def.key, def.modifiers) : parseCombo(shortcut);
+    const k = combo.key;
+    const keyLabel = KEY_GLYPHS[k] ?? (/^f\d{1,2}$/.test(k) ? k.toUpperCase() : k.length === 1 ? k.toUpperCase() : k);
+    if (platform === 'mac') {
+        let s = '';
+        if (combo.ctrl)
+            s += '⌃';
+        if (combo.alt)
+            s += '⌥';
+        if (combo.shift)
+            s += '⇧';
+        if (combo.mod || combo.meta)
+            s += '⌘';
+        return s + keyLabel;
+    }
+    const parts = [];
+    if (combo.ctrl || combo.mod)
+        parts.push('Ctrl');
+    if (combo.meta)
+        parts.push('Win');
+    if (combo.alt)
+        parts.push('Alt');
+    if (combo.shift)
+        parts.push('Shift');
+    parts.push(keyLabel);
+    return parts.join('+');
+}
+export function createShortcutRegistry(options = {}) {
+    const platform = options.platform ?? detectPlatform();
+    const labels = { [GLOBAL]: 'General', ...options.contextLabels };
+    const onError = options.onError ??
+        ((error) => console.error('keyboardShortcutRegistry: shortcut action failed', error));
+    const entries = [];
+    const stack = [];
+    const listeners = new Set();
+    let seq = 0;
+    function notify() {
+        for (const l of [...listeners])
+            l();
+    }
+    function activeContexts() {
+        const live = [];
+        for (let i = stack.length - 1; i >= 0; i--) {
+            const f = stack[i];
+            if (!live.includes(f.name))
+                live.push(f.name);
+            if (f.modal)
+                return live;
+        }
+        if (!live.includes(GLOBAL))
+            live.push(GLOBAL);
+        return live;
+    }
+    function register(shortcuts) {
+        const defs = Array.isArray(shortcuts) ? shortcuts : [shortcuts];
+        const added = defs.map((def) => {
+            const entry = {
+                def,
+                combo: parseCombo(def.key, def.modifiers),
+                context: def.context ?? GLOBAL,
+                seq: seq++
+            };
+            entries.push(entry);
+            return entry;
+        });
+        notify();
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            for (const e of added) {
+                const i = entries.indexOf(e);
+                if (i !== -1)
+                    entries.splice(i, 1);
+            }
+            notify();
+        };
+    }
+    function pushContext(name, opts = {}) {
+        const frame = { name, modal: !!opts.modal, token: {} };
+        if (opts.label)
+            labels[name] = opts.label;
+        stack.push(frame);
+        notify();
+        return () => {
+            // Pop THIS frame even if it is no longer on top (out-of-order
+            // teardown is normal when sibling components unmount together).
+            const i = stack.indexOf(frame);
+            if (i === -1)
+                return;
+            stack.splice(i, 1);
+            notify();
+        };
+    }
+    function handleKeydown(event) {
+        if (event.defaultPrevented || event.isComposing || event.key === 'Process')
+            return false;
+        const path = typeof event.composedPath === 'function' ? event.composedPath() : [];
+        const typing = isTypingTarget(path[0] ?? event.target);
+        for (const ctx of activeContexts()) {
+            // Later registrations shadow earlier ones within a context.
+            for (let i = entries.length - 1; i >= 0; i--) {
+                const e = entries[i];
+                if (e.context !== ctx)
+                    continue;
+                if (!matches(event, e.combo, platform))
+                    continue;
+                if (typing && !e.def.allowInInput)
+                    continue;
+                if (event.repeat && e.def.allowRepeat === false)
+                    continue;
+                if (e.def.enabled && !e.def.enabled())
+                    continue;
+                if (e.def.preventDefault !== false)
+                    event.preventDefault();
+                try {
+                    const result = e.def.action(event);
+                    if (result && typeof result.catch === 'function') {
+                        result.catch((err) => onError(err, e.def));
+                    }
+                }
+                catch (err) {
+                    onError(err, e.def);
+                }
+                return true;
+            }
+        }
+        return false;
+    }
+    function attach(target) {
+        const t = target ?? (typeof window !== 'undefined' ? window : null);
+        if (!t)
+            return () => { };
+        const listener = (e) => {
+            handleKeydown(e);
+        };
+        t.addEventListener('keydown', listener);
+        return () => t.removeEventListener('keydown', listener);
+    }
+    function toSections(opts = {}) {
+        const contexts = opts.scope === 'all'
+            ? [...new Set(entries.map((e) => e.context))].sort((a, b) => a === GLOBAL ? 1 : b === GLOBAL ? -1 : 0)
+            : activeContexts();
+        const sections = new Map();
+        const seen = new Set();
+        for (const ctx of contexts) {
+            // Walk newest-first so a shadowed combo (same context, or a lower
+            // context) is the one dropped, then restore registration order.
+            const kept = [];
+            for (let i = entries.length - 1; i >= 0; i--) {
+                const e = entries[i];
+                if (e.context !== ctx || e.def.hidden)
+                    continue;
+                if (opts.onlyEnabled && e.def.enabled && !e.def.enabled())
+                    continue;
+                const comboId = JSON.stringify(e.combo);
+                if (opts.scope !== 'all' && seen.has(comboId))
+                    continue;
+                seen.add(comboId);
+                kept.unshift(e);
+            }
+            for (const e of kept) {
+                const title = e.def.group ?? labels[ctx] ?? ctx;
+                let section = sections.get(title);
+                if (!section) {
+                    section = { title, shortcuts: [] };
+                    sections.set(title, section);
+                }
+                section.shortcuts.push({ key: formatShortcut(e.def, platform), description: e.def.description });
+            }
+        }
+        return [...sections.values()];
+    }
+    return {
+        register,
+        pushContext,
+        activeContexts,
+        attach,
+        handleKeydown,
+        toSections,
+        list: () => [...entries].sort((a, b) => a.seq - b.seq).map((e) => e.def),
+        format: (s) => formatShortcut(s, platform),
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        platform
+    };
+}
+let defaultRegistry = null;
+/** Lazily-created app-wide registry, for apps that want one without threading it through props. */
+export function getShortcutRegistry() {
+    defaultRegistry ??= createShortcutRegistry();
+    return defaultRegistry;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",