@remcostoeten/use-shortcut 2.0.0 → 2.1.0

package/README.md

@@ -10,6 +10,7 @@ WIP keyboard shortcut library for React with a chainable API.
 ## Implemented Features
 
 - Chainable shortcut builder: `$.mod.key("k").on(handler)`
+- Bulk shortcut maps: `useShortcutMap()` and `registerShortcutMap()`
 - Modifier support: `ctrl`, `shift`, `alt`, `cmd`, `mod`
 - Sequence support: `$.key("g").then("d")`
 - Scope-aware shortcuts:
@@ -17,19 +18,83 @@ WIP keyboard shortcut library for React with a chainable API.
   - Runtime controls: `setScopes`, `enableScope`, `disableScope`, `getScopes`, `isScopeActive`
 - Exception predicates/presets with `.except(...)`
 - Recording mode: `$.record({ timeoutMs })`
+- Structured debug stream: `$.onDebug(...)` for every keypress
+- Per-shortcut attempt inspection: `result.onAttempt((matched, event, details) => ...)`
 - Conflict detection (`exact`, `sequence-prefix`)
 - Priority ordering and `stopOnMatch`
 - Global guard/filter support via `eventFilter`
 - React entry point:
   - `useShortcut`
+  - `useShortcutMap`
+  - `useShortcutGroup`
 
 ## API Intention (Consumer-Facing)
 
 - `useShortcut(options?)`
   - Main React hook. Use this for the chainable API (`$.mod.key("s").on(...)`).
+- `useShortcutMap(shortcutMap, options?)`
+  - React-safe bulk registration for render paths where a declarative object is cleaner than multiple `.on()` calls.
+- `registerShortcutMap(builder, shortcutMap)`
+  - Imperative bulk registration helper when you already have a `useShortcut()` builder.
 
 Internal helpers follow underscore naming (for example `_createShortcutBuilder`, `_canonicalizeParsed`) and are not re-exported from `src/index.ts`.
 
+## Shortcut Map Example
+
+```tsx
+import { useShortcutMap } from "@remcostoeten/use-shortcut"
+
+function App() {
+  useShortcutMap(
+    {
+      openPalette: {
+        keys: "mod+k",
+        handler: () => openPalette(),
+        options: { preventDefault: true },
+      },
+      closePalette: {
+        keys: "escape",
+        handler: () => closePalette(),
+      },
+      toggleSidebar: {
+        keys: "g then s",
+        handler: () => toggleSidebar(),
+      },
+    },
+    { ignoreInputs: false },
+  )
+
+  return <div>Shortcuts ready</div>
+}
+```
+
+If you already have a builder from `useShortcut()`, you can bulk register with `registerShortcutMap($, shortcutMap)` and unbind the returned handles on cleanup.
+
+## Debug Example
+
+```tsx
+const $ = useShortcut({
+  debug: {
+    console: true,
+    includeCode: true,
+    includeLocation: true,
+    includeKeyCode: true,
+  },
+})
+
+const unsubscribeDebug = $.onDebug((event) => {
+  console.log("key", event.input.combo, event.attempts)
+})
+
+const result = $.shift.key("e").then("e").on(runProbe, {
+  description: "sequence probe",
+})
+
+const unsubscribeAttempt = result.onAttempt?.((matched, _event, details) => {
+  console.log(matched ? "matched" : details?.status, details?.steps)
+})
+```
+
 ## Architecture Notes
 
 - Core runtime lives in `src/builder.ts`

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import{existsSync as h,mkdirSync as f,readFileSync as w,writeFileSync as x}from"fs";import{join as l,dirname as B}from"path";import{fileURLToPath as I}from"url";function m(t){return{"scopes.ts":`/** App-defined scope catalog used by the scaffolded provider. */
+import{existsSync as h,mkdirSync as f,readFileSync as A,writeFileSync as x}from"fs";import{join as l,dirname as B}from"path";import{fileURLToPath as I}from"url";function m(t){return{"scopes.ts":`/** App-defined scope catalog used by the scaffolded provider. */
 export const shortcutScopes = ["global", "navigation", "editor", "modal"] as const
 
 export type ShortcutScope = (typeof shortcutScopes)[number]
@@ -82,7 +82,7 @@ export type ShortcutContextValue = {
     actions: ShortcutActions
     meta: ShortcutMeta
 }
-`,"runtime.ts":`import type { ShortcutMap } from "@remcostoeten/use-shortcut"
+`,"runtime.ts":`import type { HandlerOptions, ShortcutMap } from "@remcostoeten/use-shortcut"
 import { shortcutRegistry, type ShortcutActionId, type ShortcutBindings } from "./registry"
 import type { ShortcutHandlers } from "./types"
 
@@ -120,11 +120,15 @@ export function buildShortcutMap(bindings: ShortcutBindings, handlers: ShortcutH
             continue
         }
 
+        const definitionOptions: Partial<HandlerOptions> = ("options" in definition && definition.options)
+            ? definition.options
+            : {}
+
         map[actionId] = {
             keys: bindings[actionId],
             handler,
             options: {
-                ...definition.options,
+                ...definitionOptions,
                 scopes: definition.scopes,
                 description: definition.description,
             },
@@ -431,6 +435,16 @@ It follows a scalable architecture with a strict split between:
 3. Optionally expose a user-configurable key in your settings UI through \`useShortcutManager().actions.setBinding\`.
 4. Activate scopes from feature boundaries (for example editor route enters \`editor\` scope).
 
+## Wiring A React App
+
+Scaffold the shortcut files into a React app shell:
+
+\`\`\`bash
+npx @remcostoeten/use-shortcut scaffold --framework react --target apps/shortcut-playground/src
+\`\`\`
+
+Then wire those generated files into your app root by wrapping your app in \`<ShortcutProvider handlers={...} />\`.
+
 ${t==="next"?"## Next.js Integration\n\n1. Create a client provider wrapper at `app/shortcut-provider.tsx` and render `<ShortcutProvider />` there.\n2. Render that provider inside `app/layout.tsx` around your app shell.\n3. Keep page/server components pure; shortcut handlers stay in client components.\n":"## React Integration\n\n1. Wrap your app root (for example in `main.tsx`) with `<ShortcutProvider />`.\n2. Keep handlers in a top-level client component and pass them to the provider via `handlers`.\n3. Use `useShortcutManager()` inside feature components to toggle scopes and bindings.\n"}
 ## Rules For Scale
 
@@ -438,16 +452,16 @@ ${t==="next"?"## Next.js Integration\n\n1. Create a client provider wrapper at `
 - Use scopes instead of conditionals in handlers.
 - Persist only key bindings, not executable handlers.
 - Treat \`registry.ts\` as your architectural contract.
-`}}var k=I(import.meta.url),_=B(k),e={reset:"\x1B[0m",green:"\x1B[32m",cyan:"\x1B[36m",yellow:"\x1B[33m",dim:"\x1B[2m",red:"\x1B[31m"};function r(t,o=e.reset){console.log(`${o}${t}${e.reset}`)}function O(){return l(_,"..","src")}function R(t){return l(process.cwd(),t,"use-shortcut")}function C(t,o){return l(process.cwd(),t,o)}function p(t,o,a){let s=t.indexOf(o);if(s===-1)return a;let n=t[s+1];return!n||n.startsWith("--")?a:n}function g(t,o){return t.includes(o)}var P=["index.ts","hook.ts","builder.ts","types.ts","parser.ts","constants.ts","formatter.ts","runtime/types.ts","runtime/binding.ts","runtime/conflicts.ts","runtime/debug.ts","runtime/guards.ts","runtime/keys.ts","runtime/listener.ts","runtime/recording.ts"];function E(t="hooks",o=!1){let a=O(),s=R(t);if(r(`
+`}}var k=I(import.meta.url),O=B(k),e={reset:"\x1B[0m",green:"\x1B[32m",cyan:"\x1B[36m",yellow:"\x1B[33m",dim:"\x1B[2m",red:"\x1B[31m"};function r(t,o=e.reset){console.log(`${o}${t}${e.reset}`)}function _(){return l(O,"..","src")}function R(t){return l(process.cwd(),t,"use-shortcut")}function C(t,o){return l(process.cwd(),t,o)}function p(t,o,a){let s=t.indexOf(o);if(s===-1)return a;let n=t[s+1];return!n||n.startsWith("--")?a:n}function g(t,o){return t.includes(o)}var P=["index.ts","hook.ts","builder.ts","types.ts","parser.ts","constants.ts","formatter.ts","runtime/types.ts","runtime/binding.ts","runtime/conflicts.ts","runtime/debug.ts","runtime/guards.ts","runtime/keys.ts","runtime/listener.ts","runtime/recording.ts"];function E(t="hooks",o=!1){let a=_(),s=R(t);if(r(`
 use-shortcut CLI
 `,e.cyan),h(s)&&!o){r(`Directory already exists: ${s}`,e.yellow),r(`Use --force to overwrite existing files
-`,e.dim);return}f(s,{recursive:!0});let n=0;for(let i of P){let c=l(a,i),d=l(s,i);if(f(B(d),{recursive:!0}),!h(c)){r(`Source file not found: ${i}`,e.yellow);continue}let u=w(c,"utf-8");x(d,u),n+=1,r(`  wrote ${i}`,e.green)}r(`
+`,e.dim);return}f(s,{recursive:!0});let n=0;for(let i of P){let c=l(a,i),d=l(s,i);if(f(B(d),{recursive:!0}),!h(c)){r(`Source file not found: ${i}`,e.yellow);continue}let u=A(c,"utf-8");x(d,u),n+=1,r(`  wrote ${i}`,e.green)}r(`
 Copied ${n} files to:`,e.green),r(`  ${s}
 `,e.dim),r("Usage:",e.cyan),r(`  import { useShortcut } from "@/${t}/use-shortcut"`,e.dim),r("  const $ = useShortcut()",e.dim),r(`  $.mod.key("k").on(() => console.log("Search"))
 `,e.dim)}function y(t,o="src",a="shortcuts",s=!1){let n=C(o,a),i=m(t);r(`
 use-shortcut CLI
 `,e.cyan),r(`Scaffolding ${t} architecture in ${n}
-`,e.dim),f(n,{recursive:!0});let c=0,d=0;for(let[u,A]of Object.entries(i)){let S=l(n,u);if(h(S)&&!s){d+=1,r(`  skipped ${u} (already exists)`,e.yellow);continue}x(S,A),c+=1,r(`  wrote ${u}`,e.green)}r("",e.reset),r(`Architecture scaffold complete: ${c} written, ${d} skipped.`,e.green),r(`Location: ${n}
+`,e.dim),f(n,{recursive:!0});let c=0,d=0;for(let[u,w]of Object.entries(i)){let S=l(n,u);if(h(S)&&!s){d+=1,r(`  skipped ${u} (already exists)`,e.yellow);continue}x(S,w),c+=1,r(`  wrote ${u}`,e.green)}r("",e.reset),r(`Architecture scaffold complete: ${c} written, ${d} skipped.`,e.green),r(`Location: ${n}
 `,e.dim),r("Next steps:",e.cyan),r(`  1. Open ${l(o,a,"registry.ts")} and define your action catalog`,e.dim),r("  2. Wire app handlers into <ShortcutProvider handlers={...} />",e.dim),r("  3. Toggle scopes from feature boundaries via useShortcutManager()",e.dim),r(`  4. Optionally expose setBinding/resetBinding in your settings UI
 `,e.dim)}function b(){r(`
 use-shortcut CLI

package/dist/index.d.ts

@@ -101,6 +101,57 @@ type ShortcutConflict = {
     existingCombo: string;
     reason: "exact" | "sequence-prefix";
 };
+type ShortcutAttemptStatus = "matched" | "partial" | "wrong-order" | "mismatch";
+type ShortcutDebugTokenStatus = "match" | "wrong-order" | "mismatch";
+type ShortcutDebugToken = {
+    token: string;
+    kind: "modifier" | "key";
+    status: ShortcutDebugTokenStatus;
+};
+type ShortcutDebugStep = {
+    index: number;
+    expected: string;
+    actual?: string;
+    status: "match" | "partial" | "pending" | "wrong-order" | "mismatch";
+    tokens: ShortcutDebugToken[];
+};
+type ShortcutDebugInput = {
+    key: string;
+    code: string;
+    location: number;
+    repeat: boolean;
+    keyCode?: number;
+    which?: number;
+    combo: string;
+    modifiers: ModifierState;
+};
+type ShortcutAttemptDebugEvent = {
+    combo: string;
+    display: string;
+    description?: string;
+    status: ShortcutAttemptStatus;
+    matched: boolean;
+    progress: number;
+    expectedSteps: string[];
+    actualSteps: string[];
+    stepIndex: number;
+    input: ShortcutDebugInput;
+    steps: ShortcutDebugStep[];
+};
+type ShortcutDebugEvent = {
+    input: ShortcutDebugInput;
+    attempts: ShortcutAttemptDebugEvent[];
+};
+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
  */
@@ -146,7 +197,7 @@ type ShortcutResult = {
     /** Temporarily disable the shortcut */
     disable: () => void;
     /** Subscribe to shortcut attempt events (useful for visual feedback) */
-    onAttempt?: (callback: (matched: boolean, event: KeyboardEvent) => void) => () => void;
+    onAttempt?: (callback: (matched: boolean, event: KeyboardEvent, details?: ShortcutAttemptDebugEvent) => void) => () => void;
 };
 /**
  * Chainable modifier builder with type-safe exhaustion
@@ -234,6 +285,8 @@ type ShortcutBuilder = ModifierChain<EmptyModifiers> & {
     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>;
 };
@@ -241,8 +294,8 @@ type ShortcutBuilder = ModifierChain<EmptyModifiers> & {
  * Options for the `useShortcut` hook
  */
 type UseShortcutOptions = {
-    /** Enable debug logging to console */
-    debug?: boolean;
+    /** 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`) */
@@ -264,6 +317,26 @@ type UseShortcutOptions = {
     /** 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[];
+};
 
 /**
  * Parse a shortcut string into its components
@@ -317,6 +390,23 @@ declare function matchesAnyShortcut(event: KeyboardEvent, parsedShortcuts: Parse
  */
 declare function formatShortcut(shortcut: string, platform?: PlatformType): string;
 
+/**
+ * Registers an object-based shortcut map in one call and returns per-action handles.
+ *
+ * @param builder - Builder returned by `useShortcut()`
+ * @param shortcutMap - Record of action ids to key bindings, handlers, and options
+ * @returns A result map with one `ShortcutResult` per shortcut id
+ *
+ * @example
+ * ```ts
+ * const $ = useShortcut()
+ * const results = registerShortcutMap($, {
+ *   save: { keys: "mod+s", handler: onSave },
+ *   nav: { keys: ["g", "d"], handler: onGoDashboard },
+ * })
+ * ```
+ */
+declare function registerShortcutMap<T extends ShortcutMap>(builder: ShortcutBuilder, shortcutMap: T): ShortcutMapResult<T>;
 /**
  * React hook for registering chainable keyboard shortcuts
  *
@@ -333,5 +423,46 @@ declare function formatShortcut(shortcut: string, platform?: PlatformType): stri
  * ```
  */
 declare function useShortcut(options?: UseShortcutOptions): ShortcutBuilder;
+/**
+ * React hook that registers a shortcut map and automatically unbinds on cleanup.
+ *
+ * @param shortcutMap - Record of action ids to key bindings, handlers, and options
+ * @param options - Same options as `useShortcut()`
+ * @returns A map of `ShortcutResult` keyed by your shortcut ids
+ *
+ * @example
+ * ```ts
+ * const mapResults = useShortcutMap({
+ *   save: { keys: "mod+s", handler: onSave },
+ *   close: { keys: "escape", handler: onClose },
+ * })
+ * ```
+ */
+declare function useShortcutMap<T extends ShortcutMap>(shortcutMap: T, options?: UseShortcutOptions): ShortcutMapResult<T>;
+/**
+ * Creates an imperative group controller for many shortcut registrations.
+ *
+ * @returns A `ShortcutGroup` that can add and unbind multiple shortcuts together
+ *
+ * @example
+ * ```ts
+ * const group = createShortcutGroup()
+ * group.add($.mod.key("s").on(onSave))
+ * group.add($.key("escape").on(onClose))
+ * group.unbindAll()
+ * ```
+ */
+declare function createShortcutGroup(): ShortcutGroup;
+/**
+ * React hook that returns a stable `ShortcutGroup` instance.
+ *
+ * @returns A memoized `ShortcutGroup` tied to the component lifecycle
+ *
+ * @example
+ * ```ts
+ * const group = useShortcutGroup()
+ * ```
+ */
+declare function useShortcutGroup(): ShortcutGroup;
 
-export { type ActionKey, type AlphaKey, type ExceptPredicate, type ExceptPreset, type FunctionKey, type HandlerOptions, type KeyChain, ModifierAliases, type ModifierChain, ModifierDisplayOrder, ModifierDisplaySymbols, type ModifierFlags, ModifierKey, type ModifierName, type ModifierState, type NavigationKey, type NumericKey, type ParsedShortcut, Platform, type ShortcutBuilder, type ShortcutConflict, type ShortcutHandler, type ShortcutRecordingOptions, type ShortcutResult, type ShortcutScope, type SpecialKey, SpecialKeyMap, type SymbolKey, type UseShortcutOptions, detectPlatform, formatShortcut, matchesAnyShortcut, matchesShortcut, parseShortcut, parseShortcuts, useShortcut };
+export { type ActionKey, type AlphaKey, type ExceptPredicate, type ExceptPreset, type FunctionKey, type HandlerOptions, type KeyChain, ModifierAliases, type ModifierChain, ModifierDisplayOrder, ModifierDisplaySymbols, type ModifierFlags, ModifierKey, type ModifierName, type ModifierState, type NavigationKey, type NumericKey, type ParsedShortcut, Platform, type ShortcutAttemptDebugEvent, type ShortcutAttemptStatus, type ShortcutBuilder, type ShortcutConflict, type ShortcutDebugEvent, type ShortcutDebugInput, type ShortcutDebugOptions, type ShortcutDebugStep, type ShortcutDebugToken, type ShortcutDebugTokenStatus, type ShortcutGroup, type ShortcutHandler, type ShortcutMap, type ShortcutMapEntry, type ShortcutMapResult, type ShortcutRecordingOptions, type ShortcutResult, type ShortcutScope, type SpecialKey, SpecialKeyMap, type SymbolKey, type UseShortcutOptions, createShortcutGroup, detectPlatform, formatShortcut, matchesAnyShortcut, matchesShortcut, parseShortcut, parseShortcuts, registerShortcutMap, useShortcut, useShortcutGroup, useShortcutMap };