@remcostoeten/use-shortcut 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -5,7 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [2.0.1] - 2026-03-11
+
+### Fixed
+
+- Re-exported `useShortcutMap`, `registerShortcutMap`, `createShortcutGroup`, and `useShortcutGroup` from the public package entrypoint.
+- Re-exported shortcut map and shortcut group types from the public package entrypoint.
+
+### Changed
+
+- Updated the README to document the public shortcut map API.
 
 ## [2.0.0] - 2026-03-04
 

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:
@@ -22,14 +23,51 @@ WIP keyboard shortcut library for React with a chainable API.
 - 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.
+
 ## Architecture Notes
 
 - Core runtime lives in `src/builder.ts`

package/dist/index.d.mts

@@ -264,6 +264,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 +337,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 +370,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 ShortcutBuilder, type ShortcutConflict, 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 };

package/dist/index.d.ts

@@ -264,6 +264,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 +337,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 +370,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 ShortcutBuilder, type ShortcutConflict, 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 };

package/dist/index.js

@@ -750,6 +750,95 @@ function _createShortcutBuilder(options = {}) {
 }
 
 // src/hook.ts
+function _areShortcutMapKeysEqual(a, b) {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i += 1) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  }
+  if (!Array.isArray(a) && !Array.isArray(b)) {
+    return a === b;
+  }
+  return false;
+}
+function _areShortcutMapsEquivalent(a, b) {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    const aEntry = a[key];
+    const bEntry = b[key];
+    if (!bEntry) return false;
+    if (!_areShortcutMapKeysEqual(aEntry.keys, bEntry.keys)) return false;
+    if (aEntry.handler !== bEntry.handler) return false;
+    if (aEntry.options !== bEntry.options) return false;
+  }
+  return true;
+}
+function _normalizeShortcutMapKeys(keys) {
+  if (Array.isArray(keys)) {
+    return keys.map((key) => key.trim()).filter(Boolean);
+  }
+  const trimmed = keys.trim();
+  if (!trimmed) return [];
+  if (trimmed.includes(" then ")) {
+    return trimmed.split(/\s+then\s+/i).map((key) => key.trim()).filter(Boolean);
+  }
+  if (trimmed.includes(" ") && !trimmed.includes("+")) {
+    return trimmed.split(/\s+/).map((key) => key.trim()).filter(Boolean);
+  }
+  return [trimmed];
+}
+function _applyStep(builder, step) {
+  const tokens = step.toLowerCase().split("+").map((token) => token.trim()).filter(Boolean);
+  if (tokens.length === 0) {
+    throw new Error("[useShortcutMap] Invalid step: empty shortcut step");
+  }
+  const key = tokens.pop();
+  let chain = builder;
+  for (const token of tokens) {
+    if (token === "ctrl" || token === "control") {
+      chain = chain.ctrl;
+      continue;
+    }
+    if (token === "shift") {
+      chain = chain.shift;
+      continue;
+    }
+    if (token === "alt" || token === "option") {
+      chain = chain.alt;
+      continue;
+    }
+    if (token === "cmd" || token === "command" || token === "meta") {
+      chain = chain.cmd;
+      continue;
+    }
+    if (token === "mod") {
+      chain = chain.mod;
+      continue;
+    }
+    throw new Error(`[useShortcutMap] Unsupported modifier token "${token}" in step "${step}"`);
+  }
+  return chain.key(key);
+}
+function registerShortcutMap(builder, shortcutMap) {
+  const results = {};
+  for (const id of Object.keys(shortcutMap)) {
+    const entry = shortcutMap[id];
+    const steps = _normalizeShortcutMapKeys(entry.keys);
+    if (steps.length === 0) {
+      throw new Error(`[useShortcutMap] Shortcut "${String(id)}" has no key steps`);
+    }
+    let chain = _applyStep(builder, steps[0]);
+    for (const step of steps.slice(1)) {
+      chain = chain.then(step);
+    }
+    results[id] = chain.on(entry.handler, entry.options);
+  }
+  return results;
+}
 function useShortcut(options = {}) {
   const optionsRef = react.useRef(options);
   optionsRef.current = options;
@@ -777,6 +866,64 @@ function useShortcut(options = {}) {
   }, [registry]);
   return builder;
 }
+function useShortcutMap(shortcutMap, options = {}) {
+  const $ = useShortcut(options);
+  const stableShortcutMapRef = react.useRef(shortcutMap);
+  if (!_areShortcutMapsEquivalent(stableShortcutMapRef.current, shortcutMap)) {
+    stableShortcutMapRef.current = shortcutMap;
+  }
+  const stableShortcutMap = stableShortcutMapRef.current;
+  const resultsRef = react.useRef({});
+  react.useEffect(() => {
+    const registrations = registerShortcutMap($, stableShortcutMap);
+    const results = resultsRef.current;
+    for (const key of Object.keys(results)) {
+      delete results[key];
+    }
+    Object.assign(results, registrations);
+    return () => {
+      for (const result of Object.values(registrations)) {
+        result.unbind();
+      }
+      for (const key of Object.keys(results)) {
+        delete results[key];
+      }
+    };
+  }, [$, stableShortcutMap]);
+  return resultsRef.current;
+}
+function createShortcutGroup() {
+  const results = [];
+  return {
+    add: (...entries) => {
+      results.push(...entries);
+    },
+    addMany: (entries) => {
+      if (Array.isArray(entries)) {
+        results.push(...entries);
+        return;
+      }
+      results.push(...Object.values(entries));
+    },
+    unbindAll: () => {
+      for (const entry of results) {
+        entry.unbind();
+      }
+      results.length = 0;
+    },
+    clear: () => {
+      results.length = 0;
+    },
+    getResults: () => [...results]
+  };
+}
+function useShortcutGroup() {
+  const groupRef = react.useRef(null);
+  if (!groupRef.current) {
+    groupRef.current = createShortcutGroup();
+  }
+  return groupRef.current;
+}
 
 exports.ModifierAliases = ModifierAliases;
 exports.ModifierDisplayOrder = ModifierDisplayOrder;
@@ -784,12 +931,16 @@ exports.ModifierDisplaySymbols = ModifierDisplaySymbols;
 exports.ModifierKey = ModifierKey;
 exports.Platform = Platform;
 exports.SpecialKeyMap = SpecialKeyMap;
+exports.createShortcutGroup = createShortcutGroup;
 exports.detectPlatform = detectPlatform;
 exports.formatShortcut = formatShortcut;
 exports.matchesAnyShortcut = matchesAnyShortcut;
 exports.matchesShortcut = matchesShortcut;
 exports.parseShortcut = parseShortcut;
 exports.parseShortcuts = parseShortcuts;
+exports.registerShortcutMap = registerShortcutMap;
 exports.useShortcut = useShortcut;
+exports.useShortcutGroup = useShortcutGroup;
+exports.useShortcutMap = useShortcutMap;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map