@remcostoeten/use-shortcut 2.1.0 → 2.3.0

package/dist/types-yQWKtHDh.d.ts

@@ -0,0 +1,320 @@
+/** Lowercase letter keys a-z */
+type AlphaKey = "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";
+/** Number keys 0-9 */
+type NumericKey = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+/** Function keys F1-F12 */
+type FunctionKey = "f1" | "f2" | "f3" | "f4" | "f5" | "f6" | "f7" | "f8" | "f9" | "f10" | "f11" | "f12";
+/** Arrow and navigation keys */
+type NavigationKey = "up" | "down" | "left" | "right" | "arrowup" | "arrowdown" | "arrowleft" | "arrowright" | "home" | "end" | "pageup" | "pagedown";
+/** Special action keys like Enter, Escape, Tab */
+type SpecialKey = "enter" | "return" | "escape" | "esc" | "space" | "tab" | "backspace" | "delete" | "del" | "insert";
+/** Symbol and punctuation keys */
+type SymbolKey = "minus" | "plus" | "equal" | "equals" | "bracketleft" | "bracketright" | "backslash" | "slash" | "/" | "comma" | "period" | "semicolon" | "quote" | "backtick";
+/**
+ * All valid action keys that can be used with `.key()`
+ * @example $.mod.key("s") // "s" is an ActionKey
+ */
+type ActionKey = AlphaKey | NumericKey | FunctionKey | NavigationKey | SpecialKey | SymbolKey;
+/** Modifier key names used in the chainable API */
+type ModifierName = "ctrl" | "shift" | "alt" | "cmd" | "mod";
+/** Internal modifier state flags */
+type ModifierFlags = {
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+    cmd: boolean;
+};
+/** Modifier key state from a keyboard event */
+type ModifierState = {
+    meta: boolean;
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+};
+/** Result of parsing a shortcut string */
+type ParsedShortcut = {
+    modifiers: ModifierState;
+    key: string;
+    original: string;
+};
+type EmptyModifiers = {};
+/**
+ * Handler function called when a shortcut is triggered
+ * @param event - The keyboard event that triggered the shortcut
+ */
+type ShortcutHandler = (event: KeyboardEvent) => void;
+/**
+ * Custom predicate for excluding shortcuts in certain conditions
+ * @param event - The keyboard event to evaluate
+ * @returns `true` to skip the shortcut, `false` to allow it
+ */
+type ExceptPredicate = (event: KeyboardEvent) => boolean;
+/**
+ * Built-in exception presets for common scenarios
+ * - "input" - Skip when focused on input, textarea, or select
+ * - "editable" - Skip when focused on contentEditable elements
+ * - "typing" - Skip in any text input context (combines input + editable)
+ * - "modal" - Skip when a modal/dialog is open (checks [data-modal] or [role="dialog"])
+ * - "disabled" - Skip when focused element is disabled
+ */
+type ExceptPreset = "input" | "editable" | "typing" | "modal" | "disabled";
+/** Scope selector used to enable/disable subsets of shortcuts at runtime. */
+type ShortcutScope = string | string[];
+/** Conflict metadata emitted when two registered shortcuts overlap. */
+type ShortcutConflict = {
+    combo: string;
+    existingCombo: string;
+    reason: "exact" | "sequence-prefix";
+};
+/** High-level match status for one shortcut attempt against the current keyboard input. */
+type ShortcutAttemptStatus = "matched" | "partial" | "wrong-order" | "mismatch";
+/** Token-level verdict for modifiers and keys inside debug attempt payloads. */
+type ShortcutDebugTokenStatus = "match" | "wrong-order" | "mismatch";
+/** Debug metadata for one expected token in a shortcut step. */
+type ShortcutDebugToken = {
+    token: string;
+    kind: "modifier" | "key";
+    status: ShortcutDebugTokenStatus;
+};
+/** Debug metadata for one step in a combo or multi-step shortcut sequence. */
+type ShortcutDebugStep = {
+    index: number;
+    expected: string;
+    actual?: string;
+    status: "match" | "partial" | "pending" | "wrong-order" | "mismatch";
+    tokens: ShortcutDebugToken[];
+};
+/** Normalized view of the keyboard input that triggered debug processing. */
+type ShortcutDebugInput = {
+    key: string;
+    code: string;
+    location: number;
+    repeat: boolean;
+    keyCode?: number;
+    which?: number;
+    combo: string;
+    modifiers: ModifierState;
+};
+/** Per-shortcut debug payload describing how one registered shortcut was evaluated. */
+type ShortcutAttemptDebugEvent = {
+    combo: string;
+    display: string;
+    description?: string;
+    status: ShortcutAttemptStatus;
+    matched: boolean;
+    progress: number;
+    expectedSteps: string[];
+    actualSteps: string[];
+    stepIndex: number;
+    input: ShortcutDebugInput;
+    steps: ShortcutDebugStep[];
+};
+/** Global debug payload emitted for every processed keyboard event. */
+type ShortcutDebugEvent = {
+    input: ShortcutDebugInput;
+    attempts: ShortcutAttemptDebugEvent[];
+};
+/** Runtime debug configuration for console/debug-stream metadata. */
+type ShortcutDebugOptions = {
+    /** Log shortcut attempts to the console (default: true) */
+    console?: boolean;
+    /** Include `KeyboardEvent.code` in console output */
+    includeCode?: boolean;
+    /** Include `KeyboardEvent.location` in console output */
+    includeLocation?: boolean;
+    /** Include deprecated numeric key metadata in console output when available */
+    includeKeyCode?: boolean;
+};
+/**
+ * Options for shortcut handler registration
+ */
+type HandlerOptions = {
+    /** Prevent the browser's default action (default: `true`) */
+    preventDefault?: boolean;
+    /** Stop event propagation */
+    stopPropagation?: boolean;
+    /** Delay handler execution in milliseconds */
+    delay?: number;
+    /** Description for documentation/debugging */
+    description?: string;
+    /** Disable this specific shortcut */
+    disabled?: boolean;
+    /** Conditions to skip the shortcut */
+    except?: ExceptPreset | ExceptPreset[] | ExceptPredicate;
+    /** Required named scopes that must be active */
+    scopes?: ShortcutScope;
+    /** Timeout in ms for multi-step sequences */
+    sequenceTimeout?: number;
+    /** Higher priority handlers run first (default: 0) */
+    priority?: number;
+    /** Stop evaluating other handlers for this combo when matched */
+    stopOnMatch?: boolean;
+};
+/**
+ * Result object returned when registering a shortcut
+ * Provides control over the shortcut and display information
+ */
+type ShortcutResult = {
+    /** Remove the keyboard listener */
+    unbind: () => void;
+    /** Platform-aware display string (e.g., "⌘S" on Mac, "Ctrl+S" on Windows) */
+    display: string;
+    /** Normalized combo string (e.g., "cmd+s" or "g d") */
+    combo: string;
+    /** Programmatically trigger the shortcut handler */
+    trigger: () => void;
+    /** Whether the shortcut is currently enabled */
+    isEnabled: boolean;
+    /** Enable the shortcut (after being disabled) */
+    enable: () => void;
+    /** Temporarily disable the shortcut */
+    disable: () => void;
+    /** Subscribe to shortcut attempt events (useful for visual feedback) */
+    onAttempt?: (callback: (matched: boolean, event: KeyboardEvent, details?: ShortcutAttemptDebugEvent) => void) => () => void;
+};
+/**
+ * Chainable modifier builder with type-safe exhaustion
+ * Each modifier can only be used once in a chain
+ */
+type ModifierChain<Used extends Partial<ModifierFlags>> = {
+    ctrl: Used["ctrl"] extends true ? never : ModifierChain<Used & {
+        ctrl: true;
+    }>;
+    shift: Used["shift"] extends true ? never : ModifierChain<Used & {
+        shift: true;
+    }>;
+    alt: Used["alt"] extends true ? never : ModifierChain<Used & {
+        alt: true;
+    }>;
+    cmd: Used["cmd"] extends true ? never : ModifierChain<Used & {
+        cmd: true;
+    }>;
+    mod: Used["cmd"] extends true ? never : ModifierChain<Used & {
+        cmd: true;
+    }>;
+    key: <K extends ActionKey>(key: K) => KeyChain<K>;
+    in: (scopes: ShortcutScope) => ModifierChain<Used>;
+};
+/**
+ * Chain state after calling `.key()` - ready to attach a handler
+ */
+type KeyChain<Key extends string> = {
+    /** Attach a handler to this shortcut */
+    on: (handler: ShortcutHandler, options?: HandlerOptions) => ShortcutResult;
+    /** Attach a handler with inline options */
+    handle: (options: HandlerOptions & {
+        handler: ShortcutHandler;
+    }) => ShortcutResult;
+    /** Bind a combo string mid-chain */
+    bind: (combo: string | string[]) => KeyChain<any>;
+    /** Add exception conditions before attaching handler */
+    except: (condition: ExceptPreset | ExceptPreset[] | ExceptPredicate) => KeyChainWithExcept<Key>;
+    /** Add required named scopes */
+    in: (scopes: ShortcutScope) => KeyChain<Key>;
+    /** Add the next step in a sequence */
+    then: <K extends ActionKey | string>(key: K) => KeyChain<`${Key} ${K}`>;
+};
+/**
+ * Chain state after calling `.except()` - ready to attach handler
+ */
+type KeyChainWithExcept<Key extends string> = {
+    on: (handler: ShortcutHandler, options?: Omit<HandlerOptions, "except">) => ShortcutResult;
+    /** Bind a combo string mid-chain */
+    bind: (combo: string | string[]) => KeyChainWithExcept<Key>;
+    in: (scopes: ShortcutScope) => KeyChainWithExcept<Key>;
+    then: <K extends ActionKey | string>(key: K) => KeyChainWithExcept<`${Key} ${K}`>;
+};
+/** Options for `ShortcutBuilder.record()` and low-level recording flows. */
+type ShortcutRecordingOptions = {
+    target?: HTMLElement | Window | null;
+    eventType?: "keydown" | "keyup";
+    timeoutMs?: number;
+};
+/**
+ * The main shortcut builder interface returned by `useShortcut()`
+ */
+type ShortcutBuilder = ModifierChain<EmptyModifiers> & {
+    ctrl: ModifierChain<{
+        ctrl: true;
+    }>;
+    shift: ModifierChain<{
+        shift: true;
+    }>;
+    alt: ModifierChain<{
+        alt: true;
+    }>;
+    cmd: ModifierChain<{
+        cmd: true;
+    }>;
+    mod: ModifierChain<{
+        cmd: true;
+    }>;
+    key: <K extends ActionKey>(key: K) => KeyChain<K>;
+    /** Bind a pre-defined combo string */
+    bind: (combo: string | string[]) => KeyChain<any>;
+    /** Set required scopes for upcoming chain calls */
+    in: (scopes: ShortcutScope) => ShortcutBuilder;
+    /** Update active scopes at runtime */
+    setScopes: (scopes: ShortcutScope) => void;
+    /** Enable one scope */
+    enableScope: (scope: string) => void;
+    /** Disable one scope */
+    disableScope: (scope: string) => void;
+    /** Return currently active scopes */
+    getScopes: () => string[];
+    /** Check if a scope is active */
+    isScopeActive: (scope: string) => boolean;
+    /** Subscribe to every keyboard input evaluated by this shortcut registry */
+    onDebug: (callback: (event: ShortcutDebugEvent) => void) => () => void;
+    /** Record the next key combo */
+    record: (options?: ShortcutRecordingOptions) => Promise<string>;
+};
+/**
+ * Options for the `useShortcut` hook
+ */
+type UseShortcutOptions = {
+    /** Enable debug logging to console or configure structured debug output */
+    debug?: boolean | ShortcutDebugOptions;
+    /** Global delay for all handlers in milliseconds */
+    delay?: number;
+    /** Skip shortcuts when focused on input elements (default: `true`) */
+    ignoreInputs?: boolean;
+    /** Target element for keyboard listeners (default: `window`) */
+    target?: HTMLElement | Window | null;
+    /** Keyboard event type to listen for (default: "keydown") */
+    eventType?: "keydown" | "keyup";
+    /** Globally disable all shortcuts from this hook */
+    disabled?: boolean;
+    /** Active named scopes. Shortcuts with scopes only run when at least one matches. */
+    activeScopes?: ShortcutScope;
+    /** Global timeout in ms for sequence completion */
+    sequenceTimeout?: number;
+    /** Warn when conflicting shortcuts are registered (default: true) */
+    conflictWarnings?: boolean;
+    /** Custom conflict callback */
+    onConflict?: (conflict: ShortcutConflict) => void;
+    /** Global event filter; return false to skip all shortcuts for the event */
+    eventFilter?: (event: KeyboardEvent) => boolean;
+};
+/** Single shortcut-map entry used by `registerShortcutMap` and `useShortcutMap`. */
+type ShortcutMapEntry = {
+    keys: string | string[];
+    handler: ShortcutHandler;
+    options?: HandlerOptions;
+};
+/** Bulk registration shape mapping action ids to key+handler definitions. */
+type ShortcutMap = Record<string, ShortcutMapEntry>;
+/** Return type for map registrations, keyed by the same ids as the source map. */
+type ShortcutMapResult<T extends ShortcutMap = ShortcutMap> = {
+    [K in keyof T]: ShortcutResult;
+};
+/** Imperative grouping controller for binding/unbinding many shortcut registrations together. */
+type ShortcutGroup = {
+    add: (...results: ShortcutResult[]) => void;
+    addMany: (results: ShortcutResult[] | Record<string, ShortcutResult>) => void;
+    unbindAll: () => void;
+    clear: () => void;
+    getResults: () => ShortcutResult[];
+};
+
+export type { ActionKey as A, ExceptPredicate as E, FunctionKey as F, HandlerOptions as H, KeyChain as K, ModifierChain as M, NavigationKey as N, ParsedShortcut as P, ShortcutAttemptDebugEvent as S, UseShortcutOptions as U, AlphaKey as a, ExceptPreset as b, ModifierFlags as c, ModifierName as d, ModifierState as e, NumericKey as f, ShortcutAttemptStatus as g, ShortcutBuilder as h, ShortcutConflict as i, ShortcutDebugEvent as j, ShortcutDebugInput as k, ShortcutDebugOptions as l, ShortcutDebugStep as m, ShortcutDebugToken as n, ShortcutDebugTokenStatus as o, ShortcutGroup as p, ShortcutHandler as q, ShortcutMap as r, ShortcutMapEntry as s, ShortcutMapResult as t, ShortcutRecordingOptions as u, ShortcutResult as v, ShortcutScope as w, SpecialKey as x, SymbolKey as y };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@remcostoeten/use-shortcut",
-    "version": "2.1.0",
-    "description": "Beautiful, intuitive, chainable syntax for executing keyboard shortcuts in React and Next.js with perfect TypeScript IntelliSense.",
+    "version": "2.3.0",
+    "description": "Tiny, chainable React keyboard shortcuts with sequences, scopes, and typed debug hooks.",
     "author": "Remco Stoeten",
     "license": "MIT",
     "homepage": "https://github.com/remcostoeten/use-shortcut#readme",
@@ -23,9 +23,6 @@
         "chainable"
     ],
     "sideEffects": false,
-    "bin": {
-        "use-shortcut": "dist/cli/index.mjs"
-    },
     "main": "./dist/index.js",
     "module": "./dist/index.mjs",
     "types": "./dist/index.d.ts",
@@ -39,6 +36,46 @@
                 "types": "./dist/index.d.ts",
                 "default": "./dist/index.js"
             }
+        },
+        "./react": {
+            "import": {
+                "types": "./dist/react.d.ts",
+                "default": "./dist/react.mjs"
+            },
+            "require": {
+                "types": "./dist/react.d.ts",
+                "default": "./dist/react.js"
+            }
+        },
+        "./parser": {
+            "import": {
+                "types": "./dist/parser.d.ts",
+                "default": "./dist/parser.mjs"
+            },
+            "require": {
+                "types": "./dist/parser.d.ts",
+                "default": "./dist/parser.js"
+            }
+        },
+        "./formatter": {
+            "import": {
+                "types": "./dist/formatter.d.ts",
+                "default": "./dist/formatter.mjs"
+            },
+            "require": {
+                "types": "./dist/formatter.d.ts",
+                "default": "./dist/formatter.js"
+            }
+        },
+        "./constants": {
+            "import": {
+                "types": "./dist/constants.d.ts",
+                "default": "./dist/constants.mjs"
+            },
+            "require": {
+                "types": "./dist/constants.d.ts",
+                "default": "./dist/constants.js"
+            }
         }
     },
     "files": [
@@ -56,9 +93,13 @@
         "build": "tsup && node scripts/prune-dist.mjs",
         "dev": "tsup --watch",
         "test": "vitest run --environment jsdom",
+        "test:watch": "vitest --environment jsdom",
+        "test:entrypoints": "vitest run --environment jsdom src/__tests__/entrypoints.test.ts",
+        "test:features": "vitest run --environment jsdom src/__tests__/features.test.ts",
         "typecheck": "tsc --noEmit",
         "docs:api": "node scripts/generate-api-reference.mjs",
         "docs:check": "bun run docs:api && node scripts/docs-check.mjs",
+        "verify": "bun run typecheck && bun run test && bun run build && bun run docs:check",
         "clean": "rm -rf dist",
         "prepublishOnly": "npm run build"
     },