@remcostoeten/use-shortcut 2.0.1 → 2.2.0

package/README.md

@@ -1,46 +1,78 @@
 # @remcostoeten/use-shortcut
 
-WIP keyboard shortcut library for React with a chainable API.
+Tiny, chainable keyboard shortcuts for React and Next.js.
 
-## Status
+The package keeps the fluent `useShortcut()` API, but it is now documented as explicit entrypoints so consumers can choose the narrowest surface that fits their use case.
 
-- Focus right now: runtime architecture and DX refinement
-- Documentation scope: feature/status overview only (full API docs will be expanded later)
+## Entrypoints
 
-## Implemented Features
+- `@remcostoeten/use-shortcut`
+  Full compatibility barrel.
+- `@remcostoeten/use-shortcut/react`
+  Recommended React entrypoint.
+- `@remcostoeten/use-shortcut/parser`
+  Parser and matcher utilities.
+- `@remcostoeten/use-shortcut/formatter`
+  Display formatting utilities such as `formatShortcut()` and `getModifierSymbols()`.
+- `@remcostoeten/use-shortcut/constants`
+  Platform and normalization constants.
 
-- 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:
-  - Register with `.in("editor")`
-  - Runtime controls: `setScopes`, `enableScope`, `disableScope`, `getScopes`, `isScopeActive`
-- Exception predicates/presets with `.except(...)`
-- Recording mode: `$.record({ timeoutMs })`
-- Conflict detection (`exact`, `sequence-prefix`)
-- Priority ordering and `stopOnMatch`
-- Global guard/filter support via `eventFilter`
-- React entry point:
-  - `useShortcut`
-  - `useShortcutMap`
-  - `useShortcutGroup`
+This package is for React and Next.js apps. If you are building on that stack, prefer `@remcostoeten/use-shortcut/react`.
+
+## Size
+
+Measured in this package on March 12, 2026:
 
-## API Intention (Consumer-Facing)
+- root published ESM build: about `16.5 kB` minified
+- app bundle for `useShortcut` only: about `13.8 kB` minified
+- gzip for the React hook path: about `5.3 kB`
+
+That means the runtime is already small in practice. The entrypoint split mainly prevents accidental convenience-barrel imports and makes the architecture explicit.
+
+## React API
+
+The public runtime API is React-only. Parser, formatter, and constants exports are supporting utilities inside the same React/Next.js package, not a separate framework-agnostic runtime.
+
+```tsx
+import { useShortcut } from "@remcostoeten/use-shortcut/react"
+
+function App() {
+  const $ = useShortcut()
+
+  $.mod.key("k").on(() => openPalette(), { preventDefault: true })
+  $.key("escape").on(() => closePalette())
+
+  return <div>Press Cmd/Ctrl+K</div>
+}
+```
+
+Main React exports:
 
 - `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.
+- `createShortcutGroup()`
+- `useShortcutGroup()`
+
+## Features
 
-Internal helpers follow underscore naming (for example `_createShortcutBuilder`, `_canonicalizeParsed`) and are not re-exported from `src/index.ts`.
+- 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 with `.in(...)`, `setScopes`, `enableScope`, `disableScope`
+- Exception predicates and presets with `.except(...)`
+- Recording mode with `$.record({ timeoutMs })`
+- Structured debug stream with `$.onDebug(...)`
+- Per-shortcut attempt inspection with `result.onAttempt(...)`
+- Conflict detection for exact and sequence-prefix overlaps
+- Priority ordering and `stopOnMatch`
+- Global guard/filter support via `eventFilter`
 
 ## Shortcut Map Example
 
 ```tsx
-import { useShortcutMap } from "@remcostoeten/use-shortcut"
+import { useShortcutMap } from "@remcostoeten/use-shortcut/react"
 
 function App() {
   useShortcutMap(
@@ -66,15 +98,49 @@ function App() {
 }
 ```
 
-If you already have a builder from `useShortcut()`, you can bulk register with `registerShortcutMap($, shortcutMap)` and unbind the returned handles on cleanup.
+## Debug Example
 
-## Architecture Notes
+```tsx
+import { useShortcut } from "@remcostoeten/use-shortcut/react"
+
+const $ = useShortcut({
+  debug: {
+    console: true,
+    includeCode: true,
+    includeLocation: true,
+    includeKeyCode: true,
+  },
+})
+
+const removeDebug = $.onDebug((event) => {
+  console.log("key", event.input.combo, event.attempts)
+})
+
+const result = $.shift.key("e").then("e").on(runProbe, {
+  description: "sequence probe",
+})
+
+const removeAttempt = result.onAttempt?.((matched, _event, details) => {
+  console.log(matched ? "matched" : details?.status, details?.steps)
+})
+```
 
-- Core runtime lives in `src/builder.ts`
-- Parsing/formatting are isolated in `src/parser.ts` and `src/formatter.ts`
-- React bindings and map helpers live in `src/hook.ts`
-- Type contracts live in `src/types.ts`
-- CLI scaffold/copy commands live under `cli/`
+## Architecture
+
+- `src/builder.ts`
+  Chainable builder runtime and registration plumbing.
+- `src/runtime/*`
+  Listener attachment, matching, conflicts, guards, recording, and debug internals.
+- `src/hook.ts`
+  React integration and bulk registration helpers.
+- `src/react.ts`
+  Narrow React entrypoint for hook consumers.
+- `src/parser.ts`, `src/formatter.ts`, `src/constants.ts`
+  Standalone utility entrypoints.
+- `src/index.ts`
+  Full compatibility barrel.
+
+The API design keeps the fluent React path front-and-center while still exposing low-level parser and formatter utilities when needed.
 
 ## Development
 

package/dist/constants.d.ts

@@ -0,0 +1,36 @@
+/** Supported runtime OS identifiers used by formatter and parser normalization. */
+declare const OS: {
+    readonly MAC: "mac";
+    readonly WINDOWS: "windows";
+    readonly LINUX: "linux";
+};
+type PlatformType = (typeof OS)[keyof typeof OS];
+/** Public platform constant alias (`Platform.MAC`, `Platform.WINDOWS`, `Platform.LINUX`). */
+declare const Platform: {
+    readonly MAC: "mac";
+    readonly WINDOWS: "windows";
+    readonly LINUX: "linux";
+};
+/**
+ * Detect the current OS platform for modifier normalization and display formatting.
+ * Result is memoized for the page lifecycle.
+ */
+declare function detectPlatform(): PlatformType;
+/** Canonical modifier token names used internally across parsing/formatting. */
+declare const ModifierKey: {
+    readonly META: "meta";
+    readonly CTRL: "ctrl";
+    readonly ALT: "alt";
+    readonly SHIFT: "shift";
+};
+type ModifierKeyType = (typeof ModifierKey)[keyof typeof ModifierKey];
+/** Alias map from user-facing modifier tokens to canonical modifier keys. */
+declare const ModifierAliases: Record<string, ModifierKeyType>;
+/** Alias map from human shortcut key tokens to `KeyboardEvent.key`-compatible values. */
+declare const SpecialKeyMap: Record<string, string>;
+/** Platform-specific display labels/symbols for modifier keys. */
+declare const ModifierDisplaySymbols: Record<PlatformType, Record<ModifierKeyType, string>>;
+/** Platform-specific canonical order for modifier rendering and combo normalization. */
+declare const ModifierDisplayOrder: Record<PlatformType, ModifierKeyType[]>;
+
+export { ModifierAliases, ModifierDisplayOrder, ModifierDisplaySymbols, ModifierKey, type ModifierKeyType, OS, Platform, type PlatformType, SpecialKeyMap, detectPlatform };

package/dist/constants.js

@@ -0,0 +1 @@
+'use strict';var o={MAC:"mac",WINDOWS:"windows",LINUX:"linux"},n=o,t=null;function i(){if(t)return t;if(typeof navigator>"u")return t=o.WINDOWS,t;let r=(navigator.userAgentData?.platform?.toLowerCase()??navigator.platform??navigator.userAgent??"").toLowerCase();return r.includes("mac")||r.includes("iphone")||r.includes("ipad")||r.includes("ipod")?(t=o.MAC,t):r.includes("linux")||r.includes("android")?(t=o.LINUX,t):(r.includes("win"),t=o.WINDOWS,t)}var e={META:"meta",CTRL:"ctrl",ALT:"alt",SHIFT:"shift"},s={command:e.META,cmd:e.META,"\u2318":e.META,meta:e.META,win:e.META,windows:e.META,super:e.META,mod:e.META,control:e.CTRL,ctrl:e.CTRL,"\u2303":e.CTRL,ctl:e.CTRL,alt:e.ALT,option:e.ALT,opt:e.ALT,"\u2325":e.ALT,shift:e.SHIFT,"\u21E7":e.SHIFT,shft:e.SHIFT},f={up:"ArrowUp",down:"ArrowDown",left:"ArrowLeft",right:"ArrowRight",home:"Home",end:"End",pageup:"PageUp",pagedown:"PageDown",enter:"Enter",return:"Enter",space:" ",spacebar:" ",tab:"Tab",backspace:"Backspace",delete:"Delete",del:"Delete",escape:"Escape",esc:"Escape",f1:"F1",f2:"F2",f3:"F3",f4:"F4",f5:"F5",f6:"F6",f7:"F7",f8:"F8",f9:"F9",f10:"F10",f11:"F11",f12:"F12",plus:"+",minus:"-",comma:",",period:".",slash:"/",backslash:"\\",bracket:"[",closebracket:"]"},T={[o.MAC]:{[e.META]:"\u2318",[e.CTRL]:"\u2303",[e.ALT]:"\u2325",[e.SHIFT]:"\u21E7"},[o.WINDOWS]:{[e.META]:"Ctrl",[e.CTRL]:"Ctrl",[e.ALT]:"Alt",[e.SHIFT]:"Shift"},[o.LINUX]:{[e.META]:"Super",[e.CTRL]:"Ctrl",[e.ALT]:"Alt",[e.SHIFT]:"Shift"}},p={[o.MAC]:[e.CTRL,e.ALT,e.SHIFT,e.META],[o.WINDOWS]:[e.META,e.ALT,e.SHIFT,e.CTRL],[o.LINUX]:[e.META,e.ALT,e.SHIFT,e.CTRL]};exports.ModifierAliases=s;exports.ModifierDisplayOrder=p;exports.ModifierDisplaySymbols=T;exports.ModifierKey=e;exports.OS=o;exports.Platform=n;exports.SpecialKeyMap=f;exports.detectPlatform=i;

package/dist/constants.mjs

@@ -0,0 +1 @@
+var o={MAC:"mac",WINDOWS:"windows",LINUX:"linux"},n=o,t=null;function i(){if(t)return t;if(typeof navigator>"u")return t=o.WINDOWS,t;let r=(navigator.userAgentData?.platform?.toLowerCase()??navigator.platform??navigator.userAgent??"").toLowerCase();return r.includes("mac")||r.includes("iphone")||r.includes("ipad")||r.includes("ipod")?(t=o.MAC,t):r.includes("linux")||r.includes("android")?(t=o.LINUX,t):(r.includes("win"),t=o.WINDOWS,t)}var e={META:"meta",CTRL:"ctrl",ALT:"alt",SHIFT:"shift"},s={command:e.META,cmd:e.META,"\u2318":e.META,meta:e.META,win:e.META,windows:e.META,super:e.META,mod:e.META,control:e.CTRL,ctrl:e.CTRL,"\u2303":e.CTRL,ctl:e.CTRL,alt:e.ALT,option:e.ALT,opt:e.ALT,"\u2325":e.ALT,shift:e.SHIFT,"\u21E7":e.SHIFT,shft:e.SHIFT},f={up:"ArrowUp",down:"ArrowDown",left:"ArrowLeft",right:"ArrowRight",home:"Home",end:"End",pageup:"PageUp",pagedown:"PageDown",enter:"Enter",return:"Enter",space:" ",spacebar:" ",tab:"Tab",backspace:"Backspace",delete:"Delete",del:"Delete",escape:"Escape",esc:"Escape",f1:"F1",f2:"F2",f3:"F3",f4:"F4",f5:"F5",f6:"F6",f7:"F7",f8:"F8",f9:"F9",f10:"F10",f11:"F11",f12:"F12",plus:"+",minus:"-",comma:",",period:".",slash:"/",backslash:"\\",bracket:"[",closebracket:"]"},T={[o.MAC]:{[e.META]:"\u2318",[e.CTRL]:"\u2303",[e.ALT]:"\u2325",[e.SHIFT]:"\u21E7"},[o.WINDOWS]:{[e.META]:"Ctrl",[e.CTRL]:"Ctrl",[e.ALT]:"Alt",[e.SHIFT]:"Shift"},[o.LINUX]:{[e.META]:"Super",[e.CTRL]:"Ctrl",[e.ALT]:"Alt",[e.SHIFT]:"Shift"}},p={[o.MAC]:[e.CTRL,e.ALT,e.SHIFT,e.META],[o.WINDOWS]:[e.META,e.ALT,e.SHIFT,e.CTRL],[o.LINUX]:[e.META,e.ALT,e.SHIFT,e.CTRL]};export{s as ModifierAliases,p as ModifierDisplayOrder,T as ModifierDisplaySymbols,e as ModifierKey,o as OS,n as Platform,f as SpecialKeyMap,i as detectPlatform};

package/dist/formatter.d.ts

@@ -0,0 +1,30 @@
+import { PlatformType, ModifierKeyType } from './constants.js';
+
+/**
+ * Format a shortcut string for display with platform-aware symbols
+ *
+ * @param shortcut - Shortcut string (e.g., "cmd+s")
+ * @param platform - Optional platform override (default: auto-detect)
+ * @returns Formatted display string (e.g., "⌘S" on Mac, "Ctrl+S" on Windows)
+ *
+ * @example
+ * ```ts
+ * formatShortcut("cmd+s") // "⌘S" on Mac, "Ctrl+S" on Windows
+ * formatShortcut("ctrl+shift+p", "mac") // "⌃⇧P"
+ * ```
+ */
+declare function formatShortcut(shortcut: string, platform?: PlatformType): string;
+/**
+ * Get the modifier key symbols for a platform
+ *
+ * @param platform - Optional platform override (default: auto-detect)
+ * @returns Object mapping modifier keys to display symbols
+ *
+ * @example
+ * ```ts
+ * getModifierSymbols("mac") // { meta: "⌘", ctrl: "⌃", alt: "⌥", shift: "⇧" }
+ * ```
+ */
+declare function getModifierSymbols(platform?: PlatformType): Record<ModifierKeyType, string>;
+
+export { formatShortcut, getModifierSymbols };

package/dist/formatter.js

@@ -0,0 +1 @@
+'use strict';var r={MAC:"mac",WINDOWS:"windows",LINUX:"linux"},T=r,o=null;function p(){if(o)return o;if(typeof navigator>"u")return o=r.WINDOWS,o;let t=(navigator.userAgentData?.platform?.toLowerCase()??navigator.platform??navigator.userAgent??"").toLowerCase();return t.includes("mac")||t.includes("iphone")||t.includes("ipad")||t.includes("ipod")?(o=r.MAC,o):t.includes("linux")||t.includes("android")?(o=r.LINUX,o):(t.includes("win"),o=r.WINDOWS,o)}var e={META:"meta",CTRL:"ctrl",ALT:"alt",SHIFT:"shift"},u={command:e.META,cmd:e.META,"\u2318":e.META,meta:e.META,win:e.META,windows:e.META,super:e.META,mod:e.META,control:e.CTRL,ctrl:e.CTRL,"\u2303":e.CTRL,ctl:e.CTRL,alt:e.ALT,option:e.ALT,opt:e.ALT,"\u2325":e.ALT,shift:e.SHIFT,"\u21E7":e.SHIFT,shft:e.SHIFT},A={up:"ArrowUp",down:"ArrowDown",left:"ArrowLeft",right:"ArrowRight",home:"Home",end:"End",pageup:"PageUp",pagedown:"PageDown",enter:"Enter",return:"Enter",space:" ",spacebar:" ",tab:"Tab",backspace:"Backspace",delete:"Delete",del:"Delete",escape:"Escape",esc:"Escape",f1:"F1",f2:"F2",f3:"F3",f4:"F4",f5:"F5",f6:"F6",f7:"F7",f8:"F8",f9:"F9",f10:"F10",f11:"F11",f12:"F12",plus:"+",minus:"-",comma:",",period:".",slash:"/",backslash:"\\",bracket:"[",closebracket:"]"},m={[r.MAC]:{[e.META]:"\u2318",[e.CTRL]:"\u2303",[e.ALT]:"\u2325",[e.SHIFT]:"\u21E7"},[r.WINDOWS]:{[e.META]:"Ctrl",[e.CTRL]:"Ctrl",[e.ALT]:"Alt",[e.SHIFT]:"Shift"},[r.LINUX]:{[e.META]:"Super",[e.CTRL]:"Ctrl",[e.ALT]:"Alt",[e.SHIFT]:"Shift"}},M={[r.MAC]:[e.CTRL,e.ALT,e.SHIFT,e.META],[r.WINDOWS]:[e.META,e.ALT,e.SHIFT,e.CTRL],[r.LINUX]:[e.META,e.ALT,e.SHIFT,e.CTRL]};function S(a){let t=p(),n=a.toLowerCase().trim().split(/[\s+-]+/).filter(Boolean);if(n.length===0)throw new Error(`Invalid shortcut: "${a}"`);let c={meta:false,ctrl:false,alt:false,shift:false},f=n.pop();for(let l of n){let d=u[l];d?l==="mod"?t===T.MAC?c.meta=true:c.ctrl=true:c[d]=true:f=l+f;}let s=A[f]||f;return {modifiers:c,key:s.length===1?s.toLowerCase():s,original:a}}var g={ArrowUp:"\u2191",ArrowDown:"\u2193",ArrowLeft:"\u2190",ArrowRight:"\u2192",Home:"Home",End:"End",PageUp:"PgUp",PageDown:"PgDn"},h={...g,Enter:"\u21A9",Tab:"\u21E5",Escape:"\u238B",Backspace:"\u232B",Delete:"\u2326"," ":"\u2423"},E={...g,Enter:"Enter",Tab:"Tab",Escape:"Esc",Backspace:"Backspace",Delete:"Del"," ":"Space"};function K(a,t){let i=t??p(),n=S(a),c=m[i],f=M[i],s=[];for(let y of f)n.modifiers[y]&&s.push(c[y]);let l=L(n.key,i);s.push(l);let d=i===r.MAC?"":"+";return s.join(d)}function L(a,t){return (t===r.MAC?h:E)[a]||a.toUpperCase()}function F(a){let t=a??p();return m[t]}exports.formatShortcut=K;exports.getModifierSymbols=F;

package/dist/formatter.mjs

@@ -0,0 +1 @@
+var r={MAC:"mac",WINDOWS:"windows",LINUX:"linux"},T=r,o=null;function p(){if(o)return o;if(typeof navigator>"u")return o=r.WINDOWS,o;let t=(navigator.userAgentData?.platform?.toLowerCase()??navigator.platform??navigator.userAgent??"").toLowerCase();return t.includes("mac")||t.includes("iphone")||t.includes("ipad")||t.includes("ipod")?(o=r.MAC,o):t.includes("linux")||t.includes("android")?(o=r.LINUX,o):(t.includes("win"),o=r.WINDOWS,o)}var e={META:"meta",CTRL:"ctrl",ALT:"alt",SHIFT:"shift"},u={command:e.META,cmd:e.META,"\u2318":e.META,meta:e.META,win:e.META,windows:e.META,super:e.META,mod:e.META,control:e.CTRL,ctrl:e.CTRL,"\u2303":e.CTRL,ctl:e.CTRL,alt:e.ALT,option:e.ALT,opt:e.ALT,"\u2325":e.ALT,shift:e.SHIFT,"\u21E7":e.SHIFT,shft:e.SHIFT},A={up:"ArrowUp",down:"ArrowDown",left:"ArrowLeft",right:"ArrowRight",home:"Home",end:"End",pageup:"PageUp",pagedown:"PageDown",enter:"Enter",return:"Enter",space:" ",spacebar:" ",tab:"Tab",backspace:"Backspace",delete:"Delete",del:"Delete",escape:"Escape",esc:"Escape",f1:"F1",f2:"F2",f3:"F3",f4:"F4",f5:"F5",f6:"F6",f7:"F7",f8:"F8",f9:"F9",f10:"F10",f11:"F11",f12:"F12",plus:"+",minus:"-",comma:",",period:".",slash:"/",backslash:"\\",bracket:"[",closebracket:"]"},m={[r.MAC]:{[e.META]:"\u2318",[e.CTRL]:"\u2303",[e.ALT]:"\u2325",[e.SHIFT]:"\u21E7"},[r.WINDOWS]:{[e.META]:"Ctrl",[e.CTRL]:"Ctrl",[e.ALT]:"Alt",[e.SHIFT]:"Shift"},[r.LINUX]:{[e.META]:"Super",[e.CTRL]:"Ctrl",[e.ALT]:"Alt",[e.SHIFT]:"Shift"}},M={[r.MAC]:[e.CTRL,e.ALT,e.SHIFT,e.META],[r.WINDOWS]:[e.META,e.ALT,e.SHIFT,e.CTRL],[r.LINUX]:[e.META,e.ALT,e.SHIFT,e.CTRL]};function S(a){let t=p(),n=a.toLowerCase().trim().split(/[\s+-]+/).filter(Boolean);if(n.length===0)throw new Error(`Invalid shortcut: "${a}"`);let c={meta:false,ctrl:false,alt:false,shift:false},f=n.pop();for(let l of n){let d=u[l];d?l==="mod"?t===T.MAC?c.meta=true:c.ctrl=true:c[d]=true:f=l+f;}let s=A[f]||f;return {modifiers:c,key:s.length===1?s.toLowerCase():s,original:a}}var g={ArrowUp:"\u2191",ArrowDown:"\u2193",ArrowLeft:"\u2190",ArrowRight:"\u2192",Home:"Home",End:"End",PageUp:"PgUp",PageDown:"PgDn"},h={...g,Enter:"\u21A9",Tab:"\u21E5",Escape:"\u238B",Backspace:"\u232B",Delete:"\u2326"," ":"\u2423"},E={...g,Enter:"Enter",Tab:"Tab",Escape:"Esc",Backspace:"Backspace",Delete:"Del"," ":"Space"};function K(a,t){let i=t??p(),n=S(a),c=m[i],f=M[i],s=[];for(let y of f)n.modifiers[y]&&s.push(c[y]);let l=L(n.key,i);s.push(l);let d=i===r.MAC?"":"+";return s.join(d)}function L(a,t){return (t===r.MAC?h:E)[a]||a.toUpperCase()}function F(a){let t=a??p();return m[t]}export{K as formatShortcut,F as getModifierSymbols};