@tanstack/preact-hotkeys 0.4.1 → 0.5.0

package/README.md

@@ -58,7 +58,7 @@ Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objec
 > - [**Solid Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/solid/reference)
 > - [**Angular Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/angular/reference)
 > - [**Vue Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/vue/reference)
-> - Svelte Hotkeys – needs a contributor!
+> - [**Svelte Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/svelte/reference)
 
 ## Get Involved
 

package/dist/index.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_HotkeysProvider = require('./HotkeysProvider.cjs');
 const require_useHotkey = require('./useHotkey.cjs');
+const require_useHotkeys = require('./useHotkeys.cjs');
 const require_useHeldKeys = require('./useHeldKeys.cjs');
 const require_useHeldKeyCodes = require('./useHeldKeyCodes.cjs');
 const require_useKeyHold = require('./useKeyHold.cjs');
@@ -14,6 +15,7 @@ exports.useHeldKeys = require_useHeldKeys.useHeldKeys;
 exports.useHotkey = require_useHotkey.useHotkey;
 exports.useHotkeyRecorder = require_useHotkeyRecorder.useHotkeyRecorder;
 exports.useHotkeySequence = require_useHotkeySequence.useHotkeySequence;
+exports.useHotkeys = require_useHotkeys.useHotkeys;
 exports.useHotkeysContext = require_HotkeysProvider.useHotkeysContext;
 exports.useKeyHold = require_useKeyHold.useKeyHold;
 var _tanstack_hotkeys = require("@tanstack/hotkeys");

package/dist/index.d.cts

@@ -1,9 +1,10 @@
 import { UseHotkeyOptions, useHotkey } from "./useHotkey.cjs";
 import { UseHotkeySequenceOptions, useHotkeySequence } from "./useHotkeySequence.cjs";
 import { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProvider.cjs";
+import { UseHotkeyDefinition, useHotkeys } from "./useHotkeys.cjs";
 import { useHeldKeys } from "./useHeldKeys.cjs";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.cjs";
 import { useKeyHold } from "./useKeyHold.cjs";
 import { PreactHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.cjs";
 export * from "@tanstack/hotkeys";
-export { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, PreactHotkeyRecorder, UseHotkeyOptions, UseHotkeySequenceOptions, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, PreactHotkeyRecorder, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceOptions, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { UseHotkeyOptions, useHotkey } from "./useHotkey.js";
 import { UseHotkeySequenceOptions, useHotkeySequence } from "./useHotkeySequence.js";
 import { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProvider.js";
+import { UseHotkeyDefinition, useHotkeys } from "./useHotkeys.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 import { PreactHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.js";
 export * from "@tanstack/hotkeys";
-export { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, PreactHotkeyRecorder, UseHotkeyOptions, UseHotkeySequenceOptions, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, PreactHotkeyRecorder, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceOptions, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { HotkeysProvider, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProvider.js";
 import { useHotkey } from "./useHotkey.js";
+import { useHotkeys } from "./useHotkeys.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
@@ -8,4 +9,4 @@ import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyRecorder, useHotkeySequence, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/useHotkey.cjs

@@ -1,4 +1,5 @@
 const require_HotkeysProvider = require('./HotkeysProvider.cjs');
+const require_utils = require('./utils.cjs');
 let _tanstack_hotkeys = require("@tanstack/hotkeys");
 let preact_hooks = require("preact/hooks");
 
@@ -80,7 +81,7 @@ function useHotkey(hotkey, callback, options = {}) {
 	const hotkeyString = typeof hotkey === "string" ? hotkey : (0, _tanstack_hotkeys.formatHotkey)((0, _tanstack_hotkeys.rawHotkeyToParsedHotkey)(hotkey, platform));
 	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
 	(0, preact_hooks.useEffect)(() => {
-		const resolvedTarget = isRef(optionsRef.current.target) ? optionsRef.current.target.current : optionsRef.current.target ?? (typeof document !== "undefined" ? document : null);
+		const resolvedTarget = require_utils.isRef(optionsRef.current.target) ? optionsRef.current.target.current : optionsRef.current.target ?? (typeof document !== "undefined" ? document : null);
 		if (!resolvedTarget) return;
 		const targetChanged = prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget;
 		const hotkeyChanged = prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString;
@@ -106,12 +107,6 @@ function useHotkey(hotkey, callback, options = {}) {
 		registrationRef.current.setOptions(optionsWithoutTarget);
 	}
 }
-/**
-* Type guard to check if a value is a Preact ref-like object.
-*/
-function isRef(value) {
-	return value !== null && typeof value === "object" && "current" in value;
-}
 
 //#endregion
 exports.useHotkey = useHotkey;

package/dist/useHotkey.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkey.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type { RefObject } from 'preact'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Preact ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * Preact hook for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This hook syncs the callback and options on every render to avoid\n * stale closures. This means\n * callbacks that reference Preact state will always have access to\n * the latest values.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior\n *\n * @example\n * ```tsx\n * function SaveButton() {\n *   const [count, setCount] = useState(0)\n *\n *   // Callback always has access to latest count value\n *   useHotkey('Mod+S', (event, { hotkey }) => {\n *     console.log(`Save triggered, count is ${count}`)\n *     handleSave()\n *   })\n *\n *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal({ isOpen, onClose }) {\n *   // enabled option is synced on every render\n *   useHotkey('Escape', () => {\n *     onClose()\n *   }, { enabled: isOpen })\n *\n *   if (!isOpen) return null\n *   return <div className=\"modal\">...</div>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n *   const editorRef = useRef<HTMLDivElement>(null)\n *\n *   // Scoped to a specific element\n *   useHotkey('Mod+S', () => {\n *     save()\n *   }, { target: editorRef })\n *\n *   return <div ref={editorRef}>...</div>\n * }\n * ```\n */\nexport function useHotkey(\n  hotkey: RegisterableHotkey,\n  callback: HotkeyCallback,\n  options: UseHotkeyOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkey,\n    ...options,\n  } as UseHotkeyOptions\n\n  const manager = getHotkeyManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and hotkey to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevHotkeyRef = useRef<string | null>(null)\n\n  // Normalize to hotkey string\n  const platform = mergedOptions.platform ?? detectPlatform()\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string'\n      ? hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      return\n    }\n\n    // Check if we need to re-register (target or hotkey changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const hotkeyChanged =\n      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString\n\n    // If we have an active registration and target/hotkey changed, unregister first\n    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    // Use refs to access current values without adding them to dependencies\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        hotkeyString,\n        callbackRef.current,\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevHotkeyRef.current = hotkeyString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeyString, options.enabled])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  // This avoids stale closures - the callback always has access to latest state\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = callback\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n\n/**\n * Type guard to check if a value is a Preact ref-like object.\n */\nfunction isRef(value: unknown): value is RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyFA,SAAgB,UACd,QACA,UACA,UAA4B,EAAE,EACxB;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,mDAA4B;CAGlC,MAAM,2CAA0D,KAAK;CAGrE,MAAM,uCAAqB,SAAS;CACpC,MAAM,sCAAoB,cAAc;CACxC,MAAM,sCAAoB,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,yCAA+D,KAAK;CAC1E,MAAM,yCAAsC,KAAK;CAGjD,MAAM,WAAW,cAAc,mDAA4B;CAC3D,MAAM,eACJ,OAAO,WAAW,WACd,4FACsC,QAAQ,SAAS,CAAC;CAG9D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,mCAAgB;EAEd,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;AAG9D,MAAI,gBAAgB,SAAS,aAAa,iBAAiB,gBAAgB;AACzE,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAK5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,cACA,YAAY,SACZ;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,gBAAc,UAAU;AAGxB,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,CAAC,cAAc,QAAQ,QAAQ,CAAC;AAInC,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,WAAW;AACnC,kBAAgB,QAAQ,WAAW,qBAAqB;;;;;;AAO5D,SAAS,MAAM,OAAwD;AACrE,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}
+{"version":3,"file":"useHotkey.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { RefObject } from 'preact'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Preact ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * Preact hook for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This hook syncs the callback and options on every render to avoid\n * stale closures. This means\n * callbacks that reference Preact state will always have access to\n * the latest values.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior\n *\n * @example\n * ```tsx\n * function SaveButton() {\n *   const [count, setCount] = useState(0)\n *\n *   // Callback always has access to latest count value\n *   useHotkey('Mod+S', (event, { hotkey }) => {\n *     console.log(`Save triggered, count is ${count}`)\n *     handleSave()\n *   })\n *\n *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal({ isOpen, onClose }) {\n *   // enabled option is synced on every render\n *   useHotkey('Escape', () => {\n *     onClose()\n *   }, { enabled: isOpen })\n *\n *   if (!isOpen) return null\n *   return <div className=\"modal\">...</div>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n *   const editorRef = useRef<HTMLDivElement>(null)\n *\n *   // Scoped to a specific element\n *   useHotkey('Mod+S', () => {\n *     save()\n *   }, { target: editorRef })\n *\n *   return <div ref={editorRef}>...</div>\n * }\n * ```\n */\nexport function useHotkey(\n  hotkey: RegisterableHotkey,\n  callback: HotkeyCallback,\n  options: UseHotkeyOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkey,\n    ...options,\n  } as UseHotkeyOptions\n\n  const manager = getHotkeyManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and hotkey to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevHotkeyRef = useRef<string | null>(null)\n\n  // Normalize to hotkey string\n  const platform = mergedOptions.platform ?? detectPlatform()\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string'\n      ? hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      return\n    }\n\n    // Check if we need to re-register (target or hotkey changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const hotkeyChanged =\n      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString\n\n    // If we have an active registration and target/hotkey changed, unregister first\n    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    // Use refs to access current values without adding them to dependencies\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        hotkeyString,\n        callbackRef.current,\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevHotkeyRef.current = hotkeyString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeyString, options.enabled])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  // This avoids stale closures - the callback always has access to latest state\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = callback\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0FA,SAAgB,UACd,QACA,UACA,UAA4B,EAAE,EACxB;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,mDAA4B;CAGlC,MAAM,2CAA0D,KAAK;CAGrE,MAAM,uCAAqB,SAAS;CACpC,MAAM,sCAAoB,cAAc;CACxC,MAAM,sCAAoB,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,yCAA+D,KAAK;CAC1E,MAAM,yCAAsC,KAAK;CAGjD,MAAM,WAAW,cAAc,mDAA4B;CAC3D,MAAM,eACJ,OAAO,WAAW,WACd,4FACsC,QAAQ,SAAS,CAAC;CAG9D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,mCAAgB;EAEd,MAAM,iBAAiBC,oBAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;AAG9D,MAAI,gBAAgB,SAAS,aAAa,iBAAiB,gBAAgB;AACzE,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAK5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,cACA,YAAY,SACZ;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,gBAAc,UAAU;AAGxB,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,CAAC,cAAc,QAAQ,QAAQ,CAAC;AAInC,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,WAAW;AACnC,kBAAgB,QAAQ,WAAW,qBAAqB"}

package/dist/useHotkey.js

@@ -1,4 +1,5 @@
 import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { isRef } from "./utils.js";
 import { detectPlatform, formatHotkey, getHotkeyManager, rawHotkeyToParsedHotkey } from "@tanstack/hotkeys";
 import { useEffect, useRef } from "preact/hooks";
 
@@ -106,12 +107,6 @@ function useHotkey(hotkey, callback, options = {}) {
 		registrationRef.current.setOptions(optionsWithoutTarget);
 	}
 }
-/**
-* Type guard to check if a value is a Preact ref-like object.
-*/
-function isRef(value) {
-	return value !== null && typeof value === "object" && "current" in value;
-}
 
 //#endregion
 export { useHotkey };

package/dist/useHotkey.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkey.js","names":[],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type { RefObject } from 'preact'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Preact ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * Preact hook for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This hook syncs the callback and options on every render to avoid\n * stale closures. This means\n * callbacks that reference Preact state will always have access to\n * the latest values.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior\n *\n * @example\n * ```tsx\n * function SaveButton() {\n *   const [count, setCount] = useState(0)\n *\n *   // Callback always has access to latest count value\n *   useHotkey('Mod+S', (event, { hotkey }) => {\n *     console.log(`Save triggered, count is ${count}`)\n *     handleSave()\n *   })\n *\n *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal({ isOpen, onClose }) {\n *   // enabled option is synced on every render\n *   useHotkey('Escape', () => {\n *     onClose()\n *   }, { enabled: isOpen })\n *\n *   if (!isOpen) return null\n *   return <div className=\"modal\">...</div>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n *   const editorRef = useRef<HTMLDivElement>(null)\n *\n *   // Scoped to a specific element\n *   useHotkey('Mod+S', () => {\n *     save()\n *   }, { target: editorRef })\n *\n *   return <div ref={editorRef}>...</div>\n * }\n * ```\n */\nexport function useHotkey(\n  hotkey: RegisterableHotkey,\n  callback: HotkeyCallback,\n  options: UseHotkeyOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkey,\n    ...options,\n  } as UseHotkeyOptions\n\n  const manager = getHotkeyManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and hotkey to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevHotkeyRef = useRef<string | null>(null)\n\n  // Normalize to hotkey string\n  const platform = mergedOptions.platform ?? detectPlatform()\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string'\n      ? hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      return\n    }\n\n    // Check if we need to re-register (target or hotkey changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const hotkeyChanged =\n      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString\n\n    // If we have an active registration and target/hotkey changed, unregister first\n    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    // Use refs to access current values without adding them to dependencies\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        hotkeyString,\n        callbackRef.current,\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevHotkeyRef.current = hotkeyString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeyString, options.enabled])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  // This avoids stale closures - the callback always has access to latest state\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = callback\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n\n/**\n * Type guard to check if a value is a Preact ref-like object.\n */\nfunction isRef(value: unknown): value is RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyFA,SAAgB,UACd,QACA,UACA,UAA4B,EAAE,EACxB;CACN,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,UAAU,kBAAkB;CAGlC,MAAM,kBAAkB,OAAwC,KAAK;CAGrE,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,aAAa,OAAO,cAAc;CACxC,MAAM,aAAa,OAAO,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,gBAAgB,OAA+C,KAAK;CAC1E,MAAM,gBAAgB,OAAsB,KAAK;CAGjD,MAAM,WAAW,cAAc,YAAY,gBAAgB;CAC3D,MAAM,eACJ,OAAO,WAAW,WACd,SACC,aAAa,wBAAwB,QAAQ,SAAS,CAAC;CAG9D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,iBAAgB;EAEd,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;AAG9D,MAAI,gBAAgB,SAAS,aAAa,iBAAiB,gBAAgB;AACzE,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAK5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,cACA,YAAY,SACZ;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,gBAAc,UAAU;AAGxB,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,CAAC,cAAc,QAAQ,QAAQ,CAAC;AAInC,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,WAAW;AACnC,kBAAgB,QAAQ,WAAW,qBAAqB;;;;;;AAO5D,SAAS,MAAM,OAAwD;AACrE,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}
+{"version":3,"file":"useHotkey.js","names":[],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { RefObject } from 'preact'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Preact ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * Preact hook for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This hook syncs the callback and options on every render to avoid\n * stale closures. This means\n * callbacks that reference Preact state will always have access to\n * the latest values.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior\n *\n * @example\n * ```tsx\n * function SaveButton() {\n *   const [count, setCount] = useState(0)\n *\n *   // Callback always has access to latest count value\n *   useHotkey('Mod+S', (event, { hotkey }) => {\n *     console.log(`Save triggered, count is ${count}`)\n *     handleSave()\n *   })\n *\n *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Modal({ isOpen, onClose }) {\n *   // enabled option is synced on every render\n *   useHotkey('Escape', () => {\n *     onClose()\n *   }, { enabled: isOpen })\n *\n *   if (!isOpen) return null\n *   return <div className=\"modal\">...</div>\n * }\n * ```\n *\n * @example\n * ```tsx\n * function Editor() {\n *   const editorRef = useRef<HTMLDivElement>(null)\n *\n *   // Scoped to a specific element\n *   useHotkey('Mod+S', () => {\n *     save()\n *   }, { target: editorRef })\n *\n *   return <div ref={editorRef}>...</div>\n * }\n * ```\n */\nexport function useHotkey(\n  hotkey: RegisterableHotkey,\n  callback: HotkeyCallback,\n  options: UseHotkeyOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkey,\n    ...options,\n  } as UseHotkeyOptions\n\n  const manager = getHotkeyManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and hotkey to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevHotkeyRef = useRef<string | null>(null)\n\n  // Normalize to hotkey string\n  const platform = mergedOptions.platform ?? detectPlatform()\n  const hotkeyString: Hotkey =\n    typeof hotkey === 'string'\n      ? hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      return\n    }\n\n    // Check if we need to re-register (target or hotkey changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const hotkeyChanged =\n      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString\n\n    // If we have an active registration and target/hotkey changed, unregister first\n    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    // Use refs to access current values without adding them to dependencies\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        hotkeyString,\n        callbackRef.current,\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevHotkeyRef.current = hotkeyString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeyString, options.enabled])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  // This avoids stale closures - the callback always has access to latest state\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = callback\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0FA,SAAgB,UACd,QACA,UACA,UAA4B,EAAE,EACxB;CACN,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,UAAU,kBAAkB;CAGlC,MAAM,kBAAkB,OAAwC,KAAK;CAGrE,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,aAAa,OAAO,cAAc;CACxC,MAAM,aAAa,OAAO,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,gBAAgB,OAA+C,KAAK;CAC1E,MAAM,gBAAgB,OAAsB,KAAK;CAGjD,MAAM,WAAW,cAAc,YAAY,gBAAgB;CAC3D,MAAM,eACJ,OAAO,WAAW,WACd,SACC,aAAa,wBAAwB,QAAQ,SAAS,CAAC;CAG9D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,iBAAgB;EAEd,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;AAG9D,MAAI,gBAAgB,SAAS,aAAa,iBAAiB,gBAAgB;AACzE,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAK5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,cACA,YAAY,SACZ;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,gBAAc,UAAU;AAGxB,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B,CAAC,cAAc,QAAQ,QAAQ,CAAC;AAInC,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,WAAW;AACnC,kBAAgB,QAAQ,WAAW,qBAAqB"}

package/dist/useHotkeySequence.cjs

@@ -1,4 +1,5 @@
 const require_HotkeysProvider = require('./HotkeysProvider.cjs');
+const require_utils = require('./utils.cjs');
 let _tanstack_hotkeys = require("@tanstack/hotkeys");
 let preact_hooks = require("preact/hooks");
 
@@ -54,7 +55,7 @@ function useHotkeySequence(sequence, callback, options = {}) {
 	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
 	(0, preact_hooks.useEffect)(() => {
 		if (sequence.length === 0) return;
-		const resolvedTarget = isRef(optionsRef.current.target) ? optionsRef.current.target.current : optionsRef.current.target ?? (typeof document !== "undefined" ? document : null);
+		const resolvedTarget = require_utils.isRef(optionsRef.current.target) ? optionsRef.current.target.current : optionsRef.current.target ?? (typeof document !== "undefined" ? document : null);
 		if (!resolvedTarget) return;
 		const targetChanged = prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget;
 		const sequenceChanged = prevSequenceRef.current !== null && prevSequenceRef.current !== hotkeySequenceString;
@@ -84,12 +85,6 @@ function useHotkeySequence(sequence, callback, options = {}) {
 		registrationRef.current.setOptions(optionsWithoutTarget);
 	}
 }
-/**
-* Type guard to check if a value is a Preact ref-like object.
-*/
-function isRef(value) {
-	return value !== null && typeof value === "object" && "current" in value;
-}
 
 //#endregion
 exports.useHotkeySequence = useHotkeySequence;

package/dist/useHotkeySequence.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkeySequence.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type { RefObject } from 'preact'\nimport type {\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeySequence,\n  SequenceOptions,\n  SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'target'\n> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Preact ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * Preact hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior\n *\n * @example\n * ```tsx\n * function VimEditor() {\n *   // 'g g' to go to top\n *   useHotkeySequence(['G', 'G'], () => {\n *     scrollToTop()\n *   })\n *\n *   // 'd d' to delete line\n *   useHotkeySequence(['D', 'D'], () => {\n *     deleteLine()\n *   })\n *\n *   // 'd i w' to delete inner word\n *   useHotkeySequence(['D', 'I', 'W'], () => {\n *     deleteInnerWord()\n *   }, { timeout: 500 })\n *\n *   return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n  sequence: HotkeySequence,\n  callback: HotkeyCallback,\n  options: UseHotkeySequenceOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequence,\n    ...options,\n  } as UseHotkeySequenceOptions\n\n  const manager = getSequenceManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and sequence to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevSequenceRef = useRef<string | null>(null)\n\n  // Normalize to hotkey sequence string (join with spaces)\n  const hotkeySequenceString = formatHotkeySequence(sequence)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    if (sequence.length === 0) {\n      return\n    }\n\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      return\n    }\n\n    // Check if we need to re-register (target or sequence changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const sequenceChanged =\n      prevSequenceRef.current !== null &&\n      prevSequenceRef.current !== hotkeySequenceString\n\n    // If we have an active registration and target/sequence changed, unregister first\n    if (\n      registrationRef.current?.isActive &&\n      (targetChanged || sequenceChanged)\n    ) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        sequence,\n        (event, context) => callbackRef.current(event, context),\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevSequenceRef.current = hotkeySequenceString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeySequenceString, mergedOptions.enabled, sequence])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = (\n      event: KeyboardEvent,\n      context: HotkeyCallbackContext,\n    ) => callbackRef.current(event, context)\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n\n/**\n * Type guard to check if a value is a Preact ref-like object.\n */\nfunction isRef(value: unknown): value is RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,qDAA8B;CAGpC,MAAM,2CAA4D,KAAK;CAGvE,MAAM,uCAAqB,SAAS;CACpC,MAAM,sCAAoB,cAAc;CACxC,MAAM,sCAAoB,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,yCAA+D,KAAK;CAC1E,MAAM,2CAAwC,KAAK;CAGnD,MAAM,mEAA4C,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,mCAAgB;AACd,MAAI,SAAS,WAAW,EACtB;EAIF,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,WACC,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAG1B,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B;EAAC;EAAsB,cAAc;EAAS;EAAS,CAAC;AAG3D,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB;;;;;;AAO5D,SAAS,MAAM,OAAwD;AACrE,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}
+{"version":3,"file":"useHotkeySequence.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { RefObject } from 'preact'\nimport type {\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeySequence,\n  SequenceOptions,\n  SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'target'\n> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Preact ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * Preact hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior\n *\n * @example\n * ```tsx\n * function VimEditor() {\n *   // 'g g' to go to top\n *   useHotkeySequence(['G', 'G'], () => {\n *     scrollToTop()\n *   })\n *\n *   // 'd d' to delete line\n *   useHotkeySequence(['D', 'D'], () => {\n *     deleteLine()\n *   })\n *\n *   // 'd i w' to delete inner word\n *   useHotkeySequence(['D', 'I', 'W'], () => {\n *     deleteInnerWord()\n *   }, { timeout: 500 })\n *\n *   return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n  sequence: HotkeySequence,\n  callback: HotkeyCallback,\n  options: UseHotkeySequenceOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequence,\n    ...options,\n  } as UseHotkeySequenceOptions\n\n  const manager = getSequenceManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and sequence to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevSequenceRef = useRef<string | null>(null)\n\n  // Normalize to hotkey sequence string (join with spaces)\n  const hotkeySequenceString = formatHotkeySequence(sequence)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    if (sequence.length === 0) {\n      return\n    }\n\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      return\n    }\n\n    // Check if we need to re-register (target or sequence changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const sequenceChanged =\n      prevSequenceRef.current !== null &&\n      prevSequenceRef.current !== hotkeySequenceString\n\n    // If we have an active registration and target/sequence changed, unregister first\n    if (\n      registrationRef.current?.isActive &&\n      (targetChanged || sequenceChanged)\n    ) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        sequence,\n        (event, context) => callbackRef.current(event, context),\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevSequenceRef.current = hotkeySequenceString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeySequenceString, mergedOptions.enabled, sequence])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = (\n      event: KeyboardEvent,\n      context: HotkeyCallbackContext,\n    ) => callbackRef.current(event, context)\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,qDAA8B;CAGpC,MAAM,2CAA4D,KAAK;CAGvE,MAAM,uCAAqB,SAAS;CACpC,MAAM,sCAAoB,cAAc;CACxC,MAAM,sCAAoB,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,yCAA+D,KAAK;CAC1E,MAAM,2CAAwC,KAAK;CAGnD,MAAM,mEAA4C,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,mCAAgB;AACd,MAAI,SAAS,WAAW,EACtB;EAIF,MAAM,iBAAiBC,oBAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,WACC,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAG1B,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B;EAAC;EAAsB,cAAc;EAAS;EAAS,CAAC;AAG3D,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB"}

package/dist/useHotkeySequence.js

@@ -1,4 +1,5 @@
 import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { isRef } from "./utils.js";
 import { formatHotkeySequence, getSequenceManager } from "@tanstack/hotkeys";
 import { useEffect, useRef } from "preact/hooks";
 
@@ -84,12 +85,6 @@ function useHotkeySequence(sequence, callback, options = {}) {
 		registrationRef.current.setOptions(optionsWithoutTarget);
 	}
 }
-/**
-* Type guard to check if a value is a Preact ref-like object.
-*/
-function isRef(value) {
-	return value !== null && typeof value === "object" && "current" in value;
-}
 
 //#endregion
 export { useHotkeySequence };

package/dist/useHotkeySequence.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkeySequence.js","names":[],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type { RefObject } from 'preact'\nimport type {\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeySequence,\n  SequenceOptions,\n  SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'target'\n> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Preact ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * Preact hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior\n *\n * @example\n * ```tsx\n * function VimEditor() {\n *   // 'g g' to go to top\n *   useHotkeySequence(['G', 'G'], () => {\n *     scrollToTop()\n *   })\n *\n *   // 'd d' to delete line\n *   useHotkeySequence(['D', 'D'], () => {\n *     deleteLine()\n *   })\n *\n *   // 'd i w' to delete inner word\n *   useHotkeySequence(['D', 'I', 'W'], () => {\n *     deleteInnerWord()\n *   }, { timeout: 500 })\n *\n *   return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n  sequence: HotkeySequence,\n  callback: HotkeyCallback,\n  options: UseHotkeySequenceOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequence,\n    ...options,\n  } as UseHotkeySequenceOptions\n\n  const manager = getSequenceManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and sequence to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevSequenceRef = useRef<string | null>(null)\n\n  // Normalize to hotkey sequence string (join with spaces)\n  const hotkeySequenceString = formatHotkeySequence(sequence)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    if (sequence.length === 0) {\n      return\n    }\n\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      return\n    }\n\n    // Check if we need to re-register (target or sequence changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const sequenceChanged =\n      prevSequenceRef.current !== null &&\n      prevSequenceRef.current !== hotkeySequenceString\n\n    // If we have an active registration and target/sequence changed, unregister first\n    if (\n      registrationRef.current?.isActive &&\n      (targetChanged || sequenceChanged)\n    ) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        sequence,\n        (event, context) => callbackRef.current(event, context),\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevSequenceRef.current = hotkeySequenceString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeySequenceString, mergedOptions.enabled, sequence])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = (\n      event: KeyboardEvent,\n      context: HotkeyCallbackContext,\n    ) => callbackRef.current(event, context)\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n\n/**\n * Type guard to check if a value is a Preact ref-like object.\n */\nfunction isRef(value: unknown): value is RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,UAAU,oBAAoB;CAGpC,MAAM,kBAAkB,OAA0C,KAAK;CAGvE,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,aAAa,OAAO,cAAc;CACxC,MAAM,aAAa,OAAO,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,gBAAgB,OAA+C,KAAK;CAC1E,MAAM,kBAAkB,OAAsB,KAAK;CAGnD,MAAM,uBAAuB,qBAAqB,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,iBAAgB;AACd,MAAI,SAAS,WAAW,EACtB;EAIF,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,WACC,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAG1B,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B;EAAC;EAAsB,cAAc;EAAS;EAAS,CAAC;AAG3D,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB;;;;;;AAO5D,SAAS,MAAM,OAAwD;AACrE,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}
+{"version":3,"file":"useHotkeySequence.js","names":[],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { RefObject } from 'preact'\nimport type {\n  HotkeyCallback,\n  HotkeyCallbackContext,\n  HotkeySequence,\n  SequenceOptions,\n  SequenceRegistrationHandle,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'target'\n> {\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Preact ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * Preact hook for registering a keyboard shortcut sequence (Vim-style).\n *\n * This hook allows you to register multi-key sequences like 'g g' or 'd d'\n * that trigger when the full sequence is pressed within a timeout.\n *\n * @param sequence - Array of hotkey strings that form the sequence\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior\n *\n * @example\n * ```tsx\n * function VimEditor() {\n *   // 'g g' to go to top\n *   useHotkeySequence(['G', 'G'], () => {\n *     scrollToTop()\n *   })\n *\n *   // 'd d' to delete line\n *   useHotkeySequence(['D', 'D'], () => {\n *     deleteLine()\n *   })\n *\n *   // 'd i w' to delete inner word\n *   useHotkeySequence(['D', 'I', 'W'], () => {\n *     deleteInnerWord()\n *   }, { timeout: 500 })\n *\n *   return <div>...</div>\n * }\n * ```\n */\nexport function useHotkeySequence(\n  sequence: HotkeySequence,\n  callback: HotkeyCallback,\n  options: UseHotkeySequenceOptions = {},\n): void {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeySequence,\n    ...options,\n  } as UseHotkeySequenceOptions\n\n  const manager = getSequenceManager()\n\n  // Stable ref for registration handle\n  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)\n\n  // Refs to capture current values for use in effect without adding dependencies\n  const callbackRef = useRef(callback)\n  const optionsRef = useRef(mergedOptions)\n  const managerRef = useRef(manager)\n\n  // Update refs on every render\n  callbackRef.current = callback\n  optionsRef.current = mergedOptions\n  managerRef.current = manager\n\n  // Track previous target and sequence to detect changes requiring re-registration\n  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)\n  const prevSequenceRef = useRef<string | null>(null)\n\n  // Normalize to hotkey sequence string (join with spaces)\n  const hotkeySequenceString = formatHotkeySequence(sequence)\n\n  // Extract options without target (target is handled separately)\n  const { target: _target, ...optionsWithoutTarget } = mergedOptions\n\n  useEffect(() => {\n    if (sequence.length === 0) {\n      return\n    }\n\n    // Resolve target inside the effect so refs are already attached after mount\n    const resolvedTarget = isRef(optionsRef.current.target)\n      ? optionsRef.current.target.current\n      : (optionsRef.current.target ??\n        (typeof document !== 'undefined' ? document : null))\n\n    // Skip if no valid target (SSR or ref still null)\n    if (!resolvedTarget) {\n      return\n    }\n\n    // Check if we need to re-register (target or sequence changed)\n    const targetChanged =\n      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget\n    const sequenceChanged =\n      prevSequenceRef.current !== null &&\n      prevSequenceRef.current !== hotkeySequenceString\n\n    // If we have an active registration and target/sequence changed, unregister first\n    if (\n      registrationRef.current?.isActive &&\n      (targetChanged || sequenceChanged)\n    ) {\n      registrationRef.current.unregister()\n      registrationRef.current = null\n    }\n\n    // Register if needed (no active registration)\n    if (!registrationRef.current || !registrationRef.current.isActive) {\n      registrationRef.current = managerRef.current.register(\n        sequence,\n        (event, context) => callbackRef.current(event, context),\n        {\n          ...optionsRef.current,\n          target: resolvedTarget,\n        },\n      )\n    }\n\n    // Update tracking refs\n    prevTargetRef.current = resolvedTarget\n    prevSequenceRef.current = hotkeySequenceString\n\n    // Cleanup on unmount\n    return () => {\n      if (registrationRef.current?.isActive) {\n        registrationRef.current.unregister()\n        registrationRef.current = null\n      }\n    }\n  }, [hotkeySequenceString, mergedOptions.enabled, sequence])\n\n  // Sync callback and options on EVERY render (outside useEffect)\n  if (registrationRef.current?.isActive) {\n    registrationRef.current.callback = (\n      event: KeyboardEvent,\n      context: HotkeyCallbackContext,\n    ) => callbackRef.current(event, context)\n    registrationRef.current.setOptions(optionsWithoutTarget)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,UAAU,oBAAoB;CAGpC,MAAM,kBAAkB,OAA0C,KAAK;CAGvE,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,aAAa,OAAO,cAAc;CACxC,MAAM,aAAa,OAAO,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,gBAAgB,OAA+C,KAAK;CAC1E,MAAM,kBAAkB,OAAsB,KAAK;CAGnD,MAAM,uBAAuB,qBAAqB,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,iBAAgB;AACd,MAAI,SAAS,WAAW,EACtB;EAIF,MAAM,iBAAiB,MAAM,WAAW,QAAQ,OAAO,GACnD,WAAW,QAAQ,OAAO,UACzB,WAAW,QAAQ,WACnB,OAAO,aAAa,cAAc,WAAW;AAGlD,MAAI,CAAC,eACH;EAIF,MAAM,gBACJ,cAAc,YAAY,QAAQ,cAAc,YAAY;EAC9D,MAAM,kBACJ,gBAAgB,YAAY,QAC5B,gBAAgB,YAAY;AAG9B,MACE,gBAAgB,SAAS,aACxB,iBAAiB,kBAClB;AACA,mBAAgB,QAAQ,YAAY;AACpC,mBAAgB,UAAU;;AAI5B,MAAI,CAAC,gBAAgB,WAAW,CAAC,gBAAgB,QAAQ,SACvD,iBAAgB,UAAU,WAAW,QAAQ,SAC3C,WACC,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD;GACE,GAAG,WAAW;GACd,QAAQ;GACT,CACF;AAIH,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAG1B,eAAa;AACX,OAAI,gBAAgB,SAAS,UAAU;AACrC,oBAAgB,QAAQ,YAAY;AACpC,oBAAgB,UAAU;;;IAG7B;EAAC;EAAsB,cAAc;EAAS;EAAS,CAAC;AAG3D,KAAI,gBAAgB,SAAS,UAAU;AACrC,kBAAgB,QAAQ,YACtB,OACA,YACG,YAAY,QAAQ,OAAO,QAAQ;AACxC,kBAAgB,QAAQ,WAAW,qBAAqB"}

package/dist/useHotkeys.cjs

@@ -0,0 +1,137 @@
+const require_HotkeysProvider = require('./HotkeysProvider.cjs');
+const require_utils = require('./utils.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let preact_hooks = require("preact/hooks");
+
+//#region src/useHotkeys.ts
+/**
+* Preact hook for registering multiple keyboard hotkeys at once.
+*
+* Uses the singleton HotkeyManager for efficient event handling.
+* Accepts a dynamic array of hotkey definitions, making it safe to use
+* with variable-length lists without violating the rules of hooks.
+*
+* Options are merged in this order:
+* HotkeysProvider defaults < commonOptions < per-definition options
+*
+* Callbacks and options are synced on every render to avoid stale closures.
+*
+* @param hotkeys - Array of hotkey definitions to register
+* @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+*
+* @example
+* ```tsx
+* function Editor() {
+*   useHotkeys([
+*     { hotkey: 'Mod+S', callback: () => save() },
+*     { hotkey: 'Mod+Z', callback: () => undo() },
+*     { hotkey: 'Escape', callback: () => close() },
+*   ])
+* }
+* ```
+*
+* @example
+* ```tsx
+* function MenuShortcuts({ items }) {
+*   // Dynamic hotkeys from data -- safe because it's a single hook call
+*   useHotkeys(
+*     items.map((item) => ({
+*       hotkey: item.shortcut,
+*       callback: item.action,
+*       options: { enabled: item.enabled },
+*     })),
+*     { preventDefault: true },
+*   )
+* }
+* ```
+*/
+function useHotkeys(hotkeys, commonOptions = {}) {
+	const defaultOptions = require_HotkeysProvider.useDefaultHotkeysOptions().hotkey;
+	const manager = (0, _tanstack_hotkeys.getHotkeyManager)();
+	const platform = commonOptions.platform ?? defaultOptions?.platform ?? (0, _tanstack_hotkeys.detectPlatform)();
+	const registrationsRef = (0, preact_hooks.useRef)(/* @__PURE__ */ new Map());
+	const hotkeysRef = (0, preact_hooks.useRef)(hotkeys);
+	const hotkeyStringsRef = (0, preact_hooks.useRef)([]);
+	const commonOptionsRef = (0, preact_hooks.useRef)(commonOptions);
+	const defaultOptionsRef = (0, preact_hooks.useRef)(defaultOptions);
+	const managerRef = (0, preact_hooks.useRef)(manager);
+	const hotkeyStrings = hotkeys.map((def) => typeof def.hotkey === "string" ? def.hotkey : (0, _tanstack_hotkeys.formatHotkey)((0, _tanstack_hotkeys.rawHotkeyToParsedHotkey)(def.hotkey, platform)));
+	hotkeysRef.current = hotkeys;
+	hotkeyStringsRef.current = hotkeyStrings;
+	commonOptionsRef.current = commonOptions;
+	defaultOptionsRef.current = defaultOptions;
+	managerRef.current = manager;
+	(0, preact_hooks.useEffect)(() => {
+		const prevRegistrations = registrationsRef.current;
+		const nextRegistrations = /* @__PURE__ */ new Map();
+		const rows = [];
+		for (let i = 0; i < hotkeysRef.current.length; i++) {
+			const def = hotkeysRef.current[i];
+			const hotkeyStr = hotkeyStringsRef.current[i];
+			const mergedOptions = {
+				...defaultOptionsRef.current,
+				...commonOptionsRef.current,
+				...def.options
+			};
+			const resolvedTarget = require_utils.isRef(mergedOptions.target) ? mergedOptions.target.current : mergedOptions.target ?? (typeof document !== "undefined" ? document : null);
+			if (!resolvedTarget) continue;
+			const registrationKey = `${i}:${hotkeyStr}`;
+			rows.push({
+				registrationKey,
+				def,
+				hotkeyStr,
+				mergedOptions,
+				resolvedTarget
+			});
+		}
+		const nextKeys = new Set(rows.map((r) => r.registrationKey));
+		for (const [key, record] of prevRegistrations) if (!nextKeys.has(key) && record.handle.isActive) record.handle.unregister();
+		for (const row of rows) {
+			const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } = row;
+			const existing = prevRegistrations.get(registrationKey);
+			if (existing?.handle.isActive && existing.target === resolvedTarget) {
+				nextRegistrations.set(registrationKey, existing);
+				continue;
+			}
+			if (existing?.handle.isActive) existing.handle.unregister();
+			const handle = managerRef.current.register(hotkeyStr, def.callback, {
+				...mergedOptions,
+				target: resolvedTarget
+			});
+			nextRegistrations.set(registrationKey, {
+				handle,
+				target: resolvedTarget
+			});
+		}
+		registrationsRef.current = nextRegistrations;
+		return () => {
+			for (const { handle } of registrationsRef.current.values()) if (handle.isActive) handle.unregister();
+			registrationsRef.current = /* @__PURE__ */ new Map();
+		};
+	}, [hotkeyStrings.join("\0"), hotkeys.map((def) => {
+		return {
+			...defaultOptions,
+			...commonOptions,
+			...def.options
+		}.enabled ?? true;
+	}).join("\0")]);
+	for (let i = 0; i < hotkeys.length; i++) {
+		const def = hotkeys[i];
+		const hotkeyStr = hotkeyStrings[i];
+		const registrationKey = `${i}:${hotkeyStr}`;
+		const handle = registrationsRef.current.get(registrationKey)?.handle;
+		if (handle?.isActive) {
+			handle.callback = def.callback;
+			const { target: _target, ...optionsWithoutTarget } = {
+				...defaultOptions,
+				...commonOptions,
+				...def.options
+			};
+			handle.setOptions(optionsWithoutTarget);
+		}
+	}
+}
+
+//#endregion
+exports.useHotkeys = useHotkeys;
+//# sourceMappingURL=useHotkeys.cjs.map

package/dist/useHotkeys.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeys.cjs","names":["useDefaultHotkeysOptions","isRef"],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `useHotkeys`.\n */\nexport interface UseHotkeyDefinition {\n  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */\n  hotkey: RegisterableHotkey\n  /** The function to call when the hotkey is pressed */\n  callback: HotkeyCallback\n  /** Per-hotkey options (merged on top of commonOptions) */\n  options?: UseHotkeyOptions\n}\n\n/**\n * Preact hook for registering multiple keyboard hotkeys at once.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * Accepts a dynamic array of hotkey definitions, making it safe to use\n * with variable-length lists without violating the rules of hooks.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * Callbacks and options are synced on every render to avoid stale closures.\n *\n * @param hotkeys - Array of hotkey definitions to register\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)\n *\n * @example\n * ```tsx\n * function Editor() {\n *   useHotkeys([\n *     { hotkey: 'Mod+S', callback: () => save() },\n *     { hotkey: 'Mod+Z', callback: () => undo() },\n *     { hotkey: 'Escape', callback: () => close() },\n *   ])\n * }\n * ```\n *\n * @example\n * ```tsx\n * function MenuShortcuts({ items }) {\n *   // Dynamic hotkeys from data -- safe because it's a single hook call\n *   useHotkeys(\n *     items.map((item) => ({\n *       hotkey: item.shortcut,\n *       callback: item.action,\n *       options: { enabled: item.enabled },\n *     })),\n *     { preventDefault: true },\n *   )\n * }\n * ```\n */\nexport function useHotkeys(\n  hotkeys: Array<UseHotkeyDefinition>,\n  commonOptions: UseHotkeyOptions = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions().hotkey\n  const manager = getHotkeyManager()\n  const platform =\n    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()\n\n  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())\n  const hotkeysRef = useRef(hotkeys)\n  const hotkeyStringsRef = useRef<Array<Hotkey>>([])\n  const commonOptionsRef = useRef(commonOptions)\n  const defaultOptionsRef = useRef(defaultOptions)\n  const managerRef = useRef(manager)\n\n  const hotkeyStrings = hotkeys.map((def) =>\n    typeof def.hotkey === 'string'\n      ? def.hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform)) as Hotkey),\n  )\n\n  hotkeysRef.current = hotkeys\n  hotkeyStringsRef.current = hotkeyStrings\n  commonOptionsRef.current = commonOptions\n  defaultOptionsRef.current = defaultOptions\n  managerRef.current = manager\n\n  const hotkeyKey = hotkeyStrings.join('\\0')\n  const enabledKey = hotkeys\n    .map((def) => {\n      const merged = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      }\n      return merged.enabled ?? true\n    })\n    .join('\\0')\n\n  useEffect(() => {\n    const prevRegistrations = registrationsRef.current\n    const nextRegistrations = new Map<string, RegistrationRecord>()\n\n    const rows: Array<{\n      registrationKey: string\n      def: (typeof hotkeysRef.current)[number]\n      hotkeyStr: Hotkey\n      mergedOptions: UseHotkeyOptions\n      resolvedTarget: Document | HTMLElement | Window\n    }> = []\n\n    for (let i = 0; i < hotkeysRef.current.length; i++) {\n      const def = hotkeysRef.current[i]!\n      const hotkeyStr = hotkeyStringsRef.current[i]!\n      const mergedOptions = {\n        ...defaultOptionsRef.current,\n        ...commonOptionsRef.current,\n        ...def.options,\n      } as UseHotkeyOptions\n\n      const resolvedTarget = isRef(mergedOptions.target)\n        ? mergedOptions.target.current\n        : (mergedOptions.target ??\n          (typeof document !== 'undefined' ? document : null))\n\n      if (!resolvedTarget) {\n        continue\n      }\n\n      const registrationKey = `${i}:${hotkeyStr}`\n      rows.push({\n        registrationKey,\n        def,\n        hotkeyStr,\n        mergedOptions,\n        resolvedTarget,\n      })\n    }\n\n    const nextKeys = new Set(rows.map((r) => r.registrationKey))\n\n    for (const [key, record] of prevRegistrations) {\n      if (!nextKeys.has(key) && record.handle.isActive) {\n        record.handle.unregister()\n      }\n    }\n\n    for (const row of rows) {\n      const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } =\n        row\n\n      const existing = prevRegistrations.get(registrationKey)\n      if (existing?.handle.isActive && existing.target === resolvedTarget) {\n        nextRegistrations.set(registrationKey, existing)\n        continue\n      }\n\n      if (existing?.handle.isActive) {\n        existing.handle.unregister()\n      }\n\n      const handle = managerRef.current.register(hotkeyStr, def.callback, {\n        ...mergedOptions,\n        target: resolvedTarget,\n      })\n      nextRegistrations.set(registrationKey, {\n        handle,\n        target: resolvedTarget,\n      })\n    }\n\n    registrationsRef.current = nextRegistrations\n\n    return () => {\n      for (const { handle } of registrationsRef.current.values()) {\n        if (handle.isActive) {\n          handle.unregister()\n        }\n      }\n      registrationsRef.current = new Map()\n    }\n  }, [hotkeyKey, enabledKey])\n\n  for (let i = 0; i < hotkeys.length; i++) {\n    const def = hotkeys[i]!\n    const hotkeyStr = hotkeyStrings[i]!\n    const registrationKey = `${i}:${hotkeyStr}`\n    const handle = registrationsRef.current.get(registrationKey)?.handle\n\n    if (handle?.isActive) {\n      handle.callback = def.callback\n      const mergedOptions = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      } as UseHotkeyOptions\n      const { target: _target, ...optionsWithoutTarget } = mergedOptions\n      handle.setOptions(optionsWithoutTarget)\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsEA,SAAgB,WACd,SACA,gBAAkC,EAAE,EAC9B;CAMN,MAAM,iBAAiBA,kDAA0B,CAAC;CAClD,MAAM,mDAA4B;CAClC,MAAM,WACJ,cAAc,YAAY,gBAAgB,mDAA4B;CAExE,MAAM,4DAA2D,IAAI,KAAK,CAAC;CAC3E,MAAM,sCAAoB,QAAQ;CAClC,MAAM,4CAAyC,EAAE,CAAC;CAClD,MAAM,4CAA0B,cAAc;CAC9C,MAAM,6CAA2B,eAAe;CAChD,MAAM,sCAAoB,QAAQ;CAElC,MAAM,gBAAgB,QAAQ,KAAK,QACjC,OAAO,IAAI,WAAW,WAClB,IAAI,4FACkC,IAAI,QAAQ,SAAS,CAAC,CACjE;AAED,YAAW,UAAU;AACrB,kBAAiB,UAAU;AAC3B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAcrB,mCAAgB;EACd,MAAM,oBAAoB,iBAAiB;EAC3C,MAAM,oCAAoB,IAAI,KAAiC;EAE/D,MAAM,OAMD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,QAAQ,KAAK;GAClD,MAAM,MAAM,WAAW,QAAQ;GAC/B,MAAM,YAAY,iBAAiB,QAAQ;GAC3C,MAAM,gBAAgB;IACpB,GAAG,kBAAkB;IACrB,GAAG,iBAAiB;IACpB,GAAG,IAAI;IACR;GAED,MAAM,iBAAiBC,oBAAM,cAAc,OAAO,GAC9C,cAAc,OAAO,UACpB,cAAc,WACd,OAAO,aAAa,cAAc,WAAW;AAElD,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,QAAK,KAAK;IACR;IACA;IACA;IACA;IACA;IACD,CAAC;;EAGJ,MAAM,WAAW,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,gBAAgB,CAAC;AAE5D,OAAK,MAAM,CAAC,KAAK,WAAW,kBAC1B,KAAI,CAAC,SAAS,IAAI,IAAI,IAAI,OAAO,OAAO,SACtC,QAAO,OAAO,YAAY;AAI9B,OAAK,MAAM,OAAO,MAAM;GACtB,MAAM,EAAE,iBAAiB,KAAK,WAAW,eAAe,mBACtD;GAEF,MAAM,WAAW,kBAAkB,IAAI,gBAAgB;AACvD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,gBAAgB;AACnE,sBAAkB,IAAI,iBAAiB,SAAS;AAChD;;AAGF,OAAI,UAAU,OAAO,SACnB,UAAS,OAAO,YAAY;GAG9B,MAAM,SAAS,WAAW,QAAQ,SAAS,WAAW,IAAI,UAAU;IAClE,GAAG;IACH,QAAQ;IACT,CAAC;AACF,qBAAkB,IAAI,iBAAiB;IACrC;IACA,QAAQ;IACT,CAAC;;AAGJ,mBAAiB,UAAU;AAE3B,eAAa;AACX,QAAK,MAAM,EAAE,YAAY,iBAAiB,QAAQ,QAAQ,CACxD,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,oBAAiB,0BAAU,IAAI,KAAK;;IAErC,CA9Fe,cAAc,KAAK,KAAK,EACvB,QAChB,KAAK,QAAQ;AAMZ,SALe;GACb,GAAG;GACH,GAAG;GACH,GAAG,IAAI;GACR,CACa,WAAW;GACzB,CACD,KAAK,KAAK,CAoFa,CAAC;AAE3B,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;EACvC,MAAM,MAAM,QAAQ;EACpB,MAAM,YAAY,cAAc;EAChC,MAAM,kBAAkB,GAAG,EAAE,GAAG;EAChC,MAAM,SAAS,iBAAiB,QAAQ,IAAI,gBAAgB,EAAE;AAE9D,MAAI,QAAQ,UAAU;AACpB,UAAO,WAAW,IAAI;GAMtB,MAAM,EAAE,QAAQ,SAAS,GAAG,yBALN;IACpB,GAAG;IACH,GAAG;IACH,GAAG,IAAI;IACR;AAED,UAAO,WAAW,qBAAqB"}

package/dist/useHotkeys.d.cts

@@ -0,0 +1,60 @@
+import { UseHotkeyOptions } from "./useHotkey.cjs";
+import { HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+
+//#region src/useHotkeys.d.ts
+/**
+ * A single hotkey definition for use with `useHotkeys`.
+ */
+interface UseHotkeyDefinition {
+  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
+  hotkey: RegisterableHotkey;
+  /** The function to call when the hotkey is pressed */
+  callback: HotkeyCallback;
+  /** Per-hotkey options (merged on top of commonOptions) */
+  options?: UseHotkeyOptions;
+}
+/**
+ * Preact hook for registering multiple keyboard hotkeys at once.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * Accepts a dynamic array of hotkey definitions, making it safe to use
+ * with variable-length lists without violating the rules of hooks.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * Callbacks and options are synced on every render to avoid stale closures.
+ *
+ * @param hotkeys - Array of hotkey definitions to register
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   useHotkeys([
+ *     { hotkey: 'Mod+S', callback: () => save() },
+ *     { hotkey: 'Mod+Z', callback: () => undo() },
+ *     { hotkey: 'Escape', callback: () => close() },
+ *   ])
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function MenuShortcuts({ items }) {
+ *   // Dynamic hotkeys from data -- safe because it's a single hook call
+ *   useHotkeys(
+ *     items.map((item) => ({
+ *       hotkey: item.shortcut,
+ *       callback: item.action,
+ *       options: { enabled: item.enabled },
+ *     })),
+ *     { preventDefault: true },
+ *   )
+ * }
+ * ```
+ */
+declare function useHotkeys(hotkeys: Array<UseHotkeyDefinition>, commonOptions?: UseHotkeyOptions): void;
+//#endregion
+export { UseHotkeyDefinition, useHotkeys };
+//# sourceMappingURL=useHotkeys.d.cts.map

package/dist/useHotkeys.d.ts

@@ -0,0 +1,60 @@
+import { UseHotkeyOptions } from "./useHotkey.js";
+import { HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+
+//#region src/useHotkeys.d.ts
+/**
+ * A single hotkey definition for use with `useHotkeys`.
+ */
+interface UseHotkeyDefinition {
+  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
+  hotkey: RegisterableHotkey;
+  /** The function to call when the hotkey is pressed */
+  callback: HotkeyCallback;
+  /** Per-hotkey options (merged on top of commonOptions) */
+  options?: UseHotkeyOptions;
+}
+/**
+ * Preact hook for registering multiple keyboard hotkeys at once.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * Accepts a dynamic array of hotkey definitions, making it safe to use
+ * with variable-length lists without violating the rules of hooks.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * Callbacks and options are synced on every render to avoid stale closures.
+ *
+ * @param hotkeys - Array of hotkey definitions to register
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   useHotkeys([
+ *     { hotkey: 'Mod+S', callback: () => save() },
+ *     { hotkey: 'Mod+Z', callback: () => undo() },
+ *     { hotkey: 'Escape', callback: () => close() },
+ *   ])
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function MenuShortcuts({ items }) {
+ *   // Dynamic hotkeys from data -- safe because it's a single hook call
+ *   useHotkeys(
+ *     items.map((item) => ({
+ *       hotkey: item.shortcut,
+ *       callback: item.action,
+ *       options: { enabled: item.enabled },
+ *     })),
+ *     { preventDefault: true },
+ *   )
+ * }
+ * ```
+ */
+declare function useHotkeys(hotkeys: Array<UseHotkeyDefinition>, commonOptions?: UseHotkeyOptions): void;
+//#endregion
+export { UseHotkeyDefinition, useHotkeys };
+//# sourceMappingURL=useHotkeys.d.ts.map

package/dist/useHotkeys.js

@@ -0,0 +1,137 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { isRef } from "./utils.js";
+import { detectPlatform, formatHotkey, getHotkeyManager, rawHotkeyToParsedHotkey } from "@tanstack/hotkeys";
+import { useEffect, useRef } from "preact/hooks";
+
+//#region src/useHotkeys.ts
+/**
+* Preact hook for registering multiple keyboard hotkeys at once.
+*
+* Uses the singleton HotkeyManager for efficient event handling.
+* Accepts a dynamic array of hotkey definitions, making it safe to use
+* with variable-length lists without violating the rules of hooks.
+*
+* Options are merged in this order:
+* HotkeysProvider defaults < commonOptions < per-definition options
+*
+* Callbacks and options are synced on every render to avoid stale closures.
+*
+* @param hotkeys - Array of hotkey definitions to register
+* @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+*
+* @example
+* ```tsx
+* function Editor() {
+*   useHotkeys([
+*     { hotkey: 'Mod+S', callback: () => save() },
+*     { hotkey: 'Mod+Z', callback: () => undo() },
+*     { hotkey: 'Escape', callback: () => close() },
+*   ])
+* }
+* ```
+*
+* @example
+* ```tsx
+* function MenuShortcuts({ items }) {
+*   // Dynamic hotkeys from data -- safe because it's a single hook call
+*   useHotkeys(
+*     items.map((item) => ({
+*       hotkey: item.shortcut,
+*       callback: item.action,
+*       options: { enabled: item.enabled },
+*     })),
+*     { preventDefault: true },
+*   )
+* }
+* ```
+*/
+function useHotkeys(hotkeys, commonOptions = {}) {
+	const defaultOptions = useDefaultHotkeysOptions().hotkey;
+	const manager = getHotkeyManager();
+	const platform = commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform();
+	const registrationsRef = useRef(/* @__PURE__ */ new Map());
+	const hotkeysRef = useRef(hotkeys);
+	const hotkeyStringsRef = useRef([]);
+	const commonOptionsRef = useRef(commonOptions);
+	const defaultOptionsRef = useRef(defaultOptions);
+	const managerRef = useRef(manager);
+	const hotkeyStrings = hotkeys.map((def) => typeof def.hotkey === "string" ? def.hotkey : formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform)));
+	hotkeysRef.current = hotkeys;
+	hotkeyStringsRef.current = hotkeyStrings;
+	commonOptionsRef.current = commonOptions;
+	defaultOptionsRef.current = defaultOptions;
+	managerRef.current = manager;
+	useEffect(() => {
+		const prevRegistrations = registrationsRef.current;
+		const nextRegistrations = /* @__PURE__ */ new Map();
+		const rows = [];
+		for (let i = 0; i < hotkeysRef.current.length; i++) {
+			const def = hotkeysRef.current[i];
+			const hotkeyStr = hotkeyStringsRef.current[i];
+			const mergedOptions = {
+				...defaultOptionsRef.current,
+				...commonOptionsRef.current,
+				...def.options
+			};
+			const resolvedTarget = isRef(mergedOptions.target) ? mergedOptions.target.current : mergedOptions.target ?? (typeof document !== "undefined" ? document : null);
+			if (!resolvedTarget) continue;
+			const registrationKey = `${i}:${hotkeyStr}`;
+			rows.push({
+				registrationKey,
+				def,
+				hotkeyStr,
+				mergedOptions,
+				resolvedTarget
+			});
+		}
+		const nextKeys = new Set(rows.map((r) => r.registrationKey));
+		for (const [key, record] of prevRegistrations) if (!nextKeys.has(key) && record.handle.isActive) record.handle.unregister();
+		for (const row of rows) {
+			const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } = row;
+			const existing = prevRegistrations.get(registrationKey);
+			if (existing?.handle.isActive && existing.target === resolvedTarget) {
+				nextRegistrations.set(registrationKey, existing);
+				continue;
+			}
+			if (existing?.handle.isActive) existing.handle.unregister();
+			const handle = managerRef.current.register(hotkeyStr, def.callback, {
+				...mergedOptions,
+				target: resolvedTarget
+			});
+			nextRegistrations.set(registrationKey, {
+				handle,
+				target: resolvedTarget
+			});
+		}
+		registrationsRef.current = nextRegistrations;
+		return () => {
+			for (const { handle } of registrationsRef.current.values()) if (handle.isActive) handle.unregister();
+			registrationsRef.current = /* @__PURE__ */ new Map();
+		};
+	}, [hotkeyStrings.join("\0"), hotkeys.map((def) => {
+		return {
+			...defaultOptions,
+			...commonOptions,
+			...def.options
+		}.enabled ?? true;
+	}).join("\0")]);
+	for (let i = 0; i < hotkeys.length; i++) {
+		const def = hotkeys[i];
+		const hotkeyStr = hotkeyStrings[i];
+		const registrationKey = `${i}:${hotkeyStr}`;
+		const handle = registrationsRef.current.get(registrationKey)?.handle;
+		if (handle?.isActive) {
+			handle.callback = def.callback;
+			const { target: _target, ...optionsWithoutTarget } = {
+				...defaultOptions,
+				...commonOptions,
+				...def.options
+			};
+			handle.setOptions(optionsWithoutTarget);
+		}
+	}
+}
+
+//#endregion
+export { useHotkeys };
+//# sourceMappingURL=useHotkeys.js.map

package/dist/useHotkeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeys.js","names":[],"sources":["../src/useHotkeys.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport { isRef } from './utils'\nimport type { UseHotkeyOptions } from './useHotkey'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\n\n/**\n * A single hotkey definition for use with `useHotkeys`.\n */\nexport interface UseHotkeyDefinition {\n  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */\n  hotkey: RegisterableHotkey\n  /** The function to call when the hotkey is pressed */\n  callback: HotkeyCallback\n  /** Per-hotkey options (merged on top of commonOptions) */\n  options?: UseHotkeyOptions\n}\n\n/**\n * Preact hook for registering multiple keyboard hotkeys at once.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * Accepts a dynamic array of hotkey definitions, making it safe to use\n * with variable-length lists without violating the rules of hooks.\n *\n * Options are merged in this order:\n * HotkeysProvider defaults < commonOptions < per-definition options\n *\n * Callbacks and options are synced on every render to avoid stale closures.\n *\n * @param hotkeys - Array of hotkey definitions to register\n * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)\n *\n * @example\n * ```tsx\n * function Editor() {\n *   useHotkeys([\n *     { hotkey: 'Mod+S', callback: () => save() },\n *     { hotkey: 'Mod+Z', callback: () => undo() },\n *     { hotkey: 'Escape', callback: () => close() },\n *   ])\n * }\n * ```\n *\n * @example\n * ```tsx\n * function MenuShortcuts({ items }) {\n *   // Dynamic hotkeys from data -- safe because it's a single hook call\n *   useHotkeys(\n *     items.map((item) => ({\n *       hotkey: item.shortcut,\n *       callback: item.action,\n *       options: { enabled: item.enabled },\n *     })),\n *     { preventDefault: true },\n *   )\n * }\n * ```\n */\nexport function useHotkeys(\n  hotkeys: Array<UseHotkeyDefinition>,\n  commonOptions: UseHotkeyOptions = {},\n): void {\n  type RegistrationRecord = {\n    handle: HotkeyRegistrationHandle\n    target: Document | HTMLElement | Window\n  }\n\n  const defaultOptions = useDefaultHotkeysOptions().hotkey\n  const manager = getHotkeyManager()\n  const platform =\n    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()\n\n  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())\n  const hotkeysRef = useRef(hotkeys)\n  const hotkeyStringsRef = useRef<Array<Hotkey>>([])\n  const commonOptionsRef = useRef(commonOptions)\n  const defaultOptionsRef = useRef(defaultOptions)\n  const managerRef = useRef(manager)\n\n  const hotkeyStrings = hotkeys.map((def) =>\n    typeof def.hotkey === 'string'\n      ? def.hotkey\n      : (formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform)) as Hotkey),\n  )\n\n  hotkeysRef.current = hotkeys\n  hotkeyStringsRef.current = hotkeyStrings\n  commonOptionsRef.current = commonOptions\n  defaultOptionsRef.current = defaultOptions\n  managerRef.current = manager\n\n  const hotkeyKey = hotkeyStrings.join('\\0')\n  const enabledKey = hotkeys\n    .map((def) => {\n      const merged = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      }\n      return merged.enabled ?? true\n    })\n    .join('\\0')\n\n  useEffect(() => {\n    const prevRegistrations = registrationsRef.current\n    const nextRegistrations = new Map<string, RegistrationRecord>()\n\n    const rows: Array<{\n      registrationKey: string\n      def: (typeof hotkeysRef.current)[number]\n      hotkeyStr: Hotkey\n      mergedOptions: UseHotkeyOptions\n      resolvedTarget: Document | HTMLElement | Window\n    }> = []\n\n    for (let i = 0; i < hotkeysRef.current.length; i++) {\n      const def = hotkeysRef.current[i]!\n      const hotkeyStr = hotkeyStringsRef.current[i]!\n      const mergedOptions = {\n        ...defaultOptionsRef.current,\n        ...commonOptionsRef.current,\n        ...def.options,\n      } as UseHotkeyOptions\n\n      const resolvedTarget = isRef(mergedOptions.target)\n        ? mergedOptions.target.current\n        : (mergedOptions.target ??\n          (typeof document !== 'undefined' ? document : null))\n\n      if (!resolvedTarget) {\n        continue\n      }\n\n      const registrationKey = `${i}:${hotkeyStr}`\n      rows.push({\n        registrationKey,\n        def,\n        hotkeyStr,\n        mergedOptions,\n        resolvedTarget,\n      })\n    }\n\n    const nextKeys = new Set(rows.map((r) => r.registrationKey))\n\n    for (const [key, record] of prevRegistrations) {\n      if (!nextKeys.has(key) && record.handle.isActive) {\n        record.handle.unregister()\n      }\n    }\n\n    for (const row of rows) {\n      const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } =\n        row\n\n      const existing = prevRegistrations.get(registrationKey)\n      if (existing?.handle.isActive && existing.target === resolvedTarget) {\n        nextRegistrations.set(registrationKey, existing)\n        continue\n      }\n\n      if (existing?.handle.isActive) {\n        existing.handle.unregister()\n      }\n\n      const handle = managerRef.current.register(hotkeyStr, def.callback, {\n        ...mergedOptions,\n        target: resolvedTarget,\n      })\n      nextRegistrations.set(registrationKey, {\n        handle,\n        target: resolvedTarget,\n      })\n    }\n\n    registrationsRef.current = nextRegistrations\n\n    return () => {\n      for (const { handle } of registrationsRef.current.values()) {\n        if (handle.isActive) {\n          handle.unregister()\n        }\n      }\n      registrationsRef.current = new Map()\n    }\n  }, [hotkeyKey, enabledKey])\n\n  for (let i = 0; i < hotkeys.length; i++) {\n    const def = hotkeys[i]!\n    const hotkeyStr = hotkeyStrings[i]!\n    const registrationKey = `${i}:${hotkeyStr}`\n    const handle = registrationsRef.current.get(registrationKey)?.handle\n\n    if (handle?.isActive) {\n      handle.callback = def.callback\n      const mergedOptions = {\n        ...defaultOptions,\n        ...commonOptions,\n        ...def.options,\n      } as UseHotkeyOptions\n      const { target: _target, ...optionsWithoutTarget } = mergedOptions\n      handle.setOptions(optionsWithoutTarget)\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsEA,SAAgB,WACd,SACA,gBAAkC,EAAE,EAC9B;CAMN,MAAM,iBAAiB,0BAA0B,CAAC;CAClD,MAAM,UAAU,kBAAkB;CAClC,MAAM,WACJ,cAAc,YAAY,gBAAgB,YAAY,gBAAgB;CAExE,MAAM,mBAAmB,uBAAwC,IAAI,KAAK,CAAC;CAC3E,MAAM,aAAa,OAAO,QAAQ;CAClC,MAAM,mBAAmB,OAAsB,EAAE,CAAC;CAClD,MAAM,mBAAmB,OAAO,cAAc;CAC9C,MAAM,oBAAoB,OAAO,eAAe;CAChD,MAAM,aAAa,OAAO,QAAQ;CAElC,MAAM,gBAAgB,QAAQ,KAAK,QACjC,OAAO,IAAI,WAAW,WAClB,IAAI,SACH,aAAa,wBAAwB,IAAI,QAAQ,SAAS,CAAC,CACjE;AAED,YAAW,UAAU;AACrB,kBAAiB,UAAU;AAC3B,kBAAiB,UAAU;AAC3B,mBAAkB,UAAU;AAC5B,YAAW,UAAU;AAcrB,iBAAgB;EACd,MAAM,oBAAoB,iBAAiB;EAC3C,MAAM,oCAAoB,IAAI,KAAiC;EAE/D,MAAM,OAMD,EAAE;AAEP,OAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,QAAQ,KAAK;GAClD,MAAM,MAAM,WAAW,QAAQ;GAC/B,MAAM,YAAY,iBAAiB,QAAQ;GAC3C,MAAM,gBAAgB;IACpB,GAAG,kBAAkB;IACrB,GAAG,iBAAiB;IACpB,GAAG,IAAI;IACR;GAED,MAAM,iBAAiB,MAAM,cAAc,OAAO,GAC9C,cAAc,OAAO,UACpB,cAAc,WACd,OAAO,aAAa,cAAc,WAAW;AAElD,OAAI,CAAC,eACH;GAGF,MAAM,kBAAkB,GAAG,EAAE,GAAG;AAChC,QAAK,KAAK;IACR;IACA;IACA;IACA;IACA;IACD,CAAC;;EAGJ,MAAM,WAAW,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,gBAAgB,CAAC;AAE5D,OAAK,MAAM,CAAC,KAAK,WAAW,kBAC1B,KAAI,CAAC,SAAS,IAAI,IAAI,IAAI,OAAO,OAAO,SACtC,QAAO,OAAO,YAAY;AAI9B,OAAK,MAAM,OAAO,MAAM;GACtB,MAAM,EAAE,iBAAiB,KAAK,WAAW,eAAe,mBACtD;GAEF,MAAM,WAAW,kBAAkB,IAAI,gBAAgB;AACvD,OAAI,UAAU,OAAO,YAAY,SAAS,WAAW,gBAAgB;AACnE,sBAAkB,IAAI,iBAAiB,SAAS;AAChD;;AAGF,OAAI,UAAU,OAAO,SACnB,UAAS,OAAO,YAAY;GAG9B,MAAM,SAAS,WAAW,QAAQ,SAAS,WAAW,IAAI,UAAU;IAClE,GAAG;IACH,QAAQ;IACT,CAAC;AACF,qBAAkB,IAAI,iBAAiB;IACrC;IACA,QAAQ;IACT,CAAC;;AAGJ,mBAAiB,UAAU;AAE3B,eAAa;AACX,QAAK,MAAM,EAAE,YAAY,iBAAiB,QAAQ,QAAQ,CACxD,KAAI,OAAO,SACT,QAAO,YAAY;AAGvB,oBAAiB,0BAAU,IAAI,KAAK;;IAErC,CA9Fe,cAAc,KAAK,KAAK,EACvB,QAChB,KAAK,QAAQ;AAMZ,SALe;GACb,GAAG;GACH,GAAG;GACH,GAAG,IAAI;GACR,CACa,WAAW;GACzB,CACD,KAAK,KAAK,CAoFa,CAAC;AAE3B,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;EACvC,MAAM,MAAM,QAAQ;EACpB,MAAM,YAAY,cAAc;EAChC,MAAM,kBAAkB,GAAG,EAAE,GAAG;EAChC,MAAM,SAAS,iBAAiB,QAAQ,IAAI,gBAAgB,EAAE;AAE9D,MAAI,QAAQ,UAAU;AACpB,UAAO,WAAW,IAAI;GAMtB,MAAM,EAAE,QAAQ,SAAS,GAAG,yBALN;IACpB,GAAG;IACH,GAAG;IACH,GAAG,IAAI;IACR;AAED,UAAO,WAAW,qBAAqB"}

package/dist/utils.cjs

@@ -0,0 +1,12 @@
+
+//#region src/utils.ts
+/**
+* Type guard to check if a value is a Preact ref-like object.
+*/
+function isRef(value) {
+	return value !== null && typeof value === "object" && "current" in value;
+}
+
+//#endregion
+exports.isRef = isRef;
+//# sourceMappingURL=utils.cjs.map

package/dist/utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.cjs","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import type { RefObject } from 'preact'\n\n/**\n * Type guard to check if a value is a Preact ref-like object.\n */\nexport function isRef(value: unknown): value is RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;;AAKA,SAAgB,MAAM,OAAwD;AAC5E,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}

package/dist/utils.js

@@ -0,0 +1,11 @@
+//#region src/utils.ts
+/**
+* Type guard to check if a value is a Preact ref-like object.
+*/
+function isRef(value) {
+	return value !== null && typeof value === "object" && "current" in value;
+}
+
+//#endregion
+export { isRef };
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import type { RefObject } from 'preact'\n\n/**\n * Type guard to check if a value is a Preact ref-like object.\n */\nexport function isRef(value: unknown): value is RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;AAKA,SAAgB,MAAM,OAAwD;AAC5E,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/preact-hotkeys",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Preact adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -40,12 +40,12 @@
   ],
   "dependencies": {
     "@tanstack/preact-store": "^0.11.2",
-    "@tanstack/hotkeys": "0.4.1"
+    "@tanstack/hotkeys": "0.4.2"
   },
   "devDependencies": {
-    "@preact/preset-vite": "^2.10.3",
+    "@preact/preset-vite": "^2.10.5",
     "@testing-library/preact": "^3.2.4",
-    "preact": "^10.28.4"
+    "preact": "^10.29.0"
   },
   "peerDependencies": {
     "preact": ">=10.0.0"

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './HotkeysProvider'
 
 // Preact-specific exports
 export * from './useHotkey'
+export * from './useHotkeys'
 export * from './useHeldKeys'
 export * from './useHeldKeyCodes'
 export * from './useKeyHold'

package/src/useHotkey.ts

@@ -6,6 +6,7 @@ import {
   rawHotkeyToParsedHotkey,
 } from '@tanstack/hotkeys'
 import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import { isRef } from './utils'
 import type { RefObject } from 'preact'
 import type {
   Hotkey,
@@ -183,10 +184,3 @@ export function useHotkey(
     registrationRef.current.setOptions(optionsWithoutTarget)
   }
 }
-
-/**
- * Type guard to check if a value is a Preact ref-like object.
- */
-function isRef(value: unknown): value is RefObject<HTMLElement | null> {
-  return value !== null && typeof value === 'object' && 'current' in value
-}

package/src/useHotkeySequence.ts

@@ -1,6 +1,7 @@
 import { useEffect, useRef } from 'preact/hooks'
 import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
 import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import { isRef } from './utils'
 import type { RefObject } from 'preact'
 import type {
   HotkeyCallback,
@@ -160,10 +161,3 @@ export function useHotkeySequence(
     registrationRef.current.setOptions(optionsWithoutTarget)
   }
 }
-
-/**
- * Type guard to check if a value is a Preact ref-like object.
- */
-function isRef(value: unknown): value is RefObject<HTMLElement | null> {
-  return value !== null && typeof value === 'object' && 'current' in value
-}

package/src/useHotkeys.ts

@@ -0,0 +1,217 @@
+import { useEffect, useRef } from 'preact/hooks'
+import {
+  detectPlatform,
+  formatHotkey,
+  getHotkeyManager,
+  rawHotkeyToParsedHotkey,
+} from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import { isRef } from './utils'
+import type { UseHotkeyOptions } from './useHotkey'
+import type {
+  Hotkey,
+  HotkeyCallback,
+  HotkeyRegistrationHandle,
+  RegisterableHotkey,
+} from '@tanstack/hotkeys'
+
+/**
+ * A single hotkey definition for use with `useHotkeys`.
+ */
+export interface UseHotkeyDefinition {
+  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
+  hotkey: RegisterableHotkey
+  /** The function to call when the hotkey is pressed */
+  callback: HotkeyCallback
+  /** Per-hotkey options (merged on top of commonOptions) */
+  options?: UseHotkeyOptions
+}
+
+/**
+ * Preact hook for registering multiple keyboard hotkeys at once.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * Accepts a dynamic array of hotkey definitions, making it safe to use
+ * with variable-length lists without violating the rules of hooks.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * Callbacks and options are synced on every render to avoid stale closures.
+ *
+ * @param hotkeys - Array of hotkey definitions to register
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   useHotkeys([
+ *     { hotkey: 'Mod+S', callback: () => save() },
+ *     { hotkey: 'Mod+Z', callback: () => undo() },
+ *     { hotkey: 'Escape', callback: () => close() },
+ *   ])
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function MenuShortcuts({ items }) {
+ *   // Dynamic hotkeys from data -- safe because it's a single hook call
+ *   useHotkeys(
+ *     items.map((item) => ({
+ *       hotkey: item.shortcut,
+ *       callback: item.action,
+ *       options: { enabled: item.enabled },
+ *     })),
+ *     { preventDefault: true },
+ *   )
+ * }
+ * ```
+ */
+export function useHotkeys(
+  hotkeys: Array<UseHotkeyDefinition>,
+  commonOptions: UseHotkeyOptions = {},
+): void {
+  type RegistrationRecord = {
+    handle: HotkeyRegistrationHandle
+    target: Document | HTMLElement | Window
+  }
+
+  const defaultOptions = useDefaultHotkeysOptions().hotkey
+  const manager = getHotkeyManager()
+  const platform =
+    commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform()
+
+  const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map())
+  const hotkeysRef = useRef(hotkeys)
+  const hotkeyStringsRef = useRef<Array<Hotkey>>([])
+  const commonOptionsRef = useRef(commonOptions)
+  const defaultOptionsRef = useRef(defaultOptions)
+  const managerRef = useRef(manager)
+
+  const hotkeyStrings = hotkeys.map((def) =>
+    typeof def.hotkey === 'string'
+      ? def.hotkey
+      : (formatHotkey(rawHotkeyToParsedHotkey(def.hotkey, platform)) as Hotkey),
+  )
+
+  hotkeysRef.current = hotkeys
+  hotkeyStringsRef.current = hotkeyStrings
+  commonOptionsRef.current = commonOptions
+  defaultOptionsRef.current = defaultOptions
+  managerRef.current = manager
+
+  const hotkeyKey = hotkeyStrings.join('\0')
+  const enabledKey = hotkeys
+    .map((def) => {
+      const merged = {
+        ...defaultOptions,
+        ...commonOptions,
+        ...def.options,
+      }
+      return merged.enabled ?? true
+    })
+    .join('\0')
+
+  useEffect(() => {
+    const prevRegistrations = registrationsRef.current
+    const nextRegistrations = new Map<string, RegistrationRecord>()
+
+    const rows: Array<{
+      registrationKey: string
+      def: (typeof hotkeysRef.current)[number]
+      hotkeyStr: Hotkey
+      mergedOptions: UseHotkeyOptions
+      resolvedTarget: Document | HTMLElement | Window
+    }> = []
+
+    for (let i = 0; i < hotkeysRef.current.length; i++) {
+      const def = hotkeysRef.current[i]!
+      const hotkeyStr = hotkeyStringsRef.current[i]!
+      const mergedOptions = {
+        ...defaultOptionsRef.current,
+        ...commonOptionsRef.current,
+        ...def.options,
+      } as UseHotkeyOptions
+
+      const resolvedTarget = isRef(mergedOptions.target)
+        ? mergedOptions.target.current
+        : (mergedOptions.target ??
+          (typeof document !== 'undefined' ? document : null))
+
+      if (!resolvedTarget) {
+        continue
+      }
+
+      const registrationKey = `${i}:${hotkeyStr}`
+      rows.push({
+        registrationKey,
+        def,
+        hotkeyStr,
+        mergedOptions,
+        resolvedTarget,
+      })
+    }
+
+    const nextKeys = new Set(rows.map((r) => r.registrationKey))
+
+    for (const [key, record] of prevRegistrations) {
+      if (!nextKeys.has(key) && record.handle.isActive) {
+        record.handle.unregister()
+      }
+    }
+
+    for (const row of rows) {
+      const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } =
+        row
+
+      const existing = prevRegistrations.get(registrationKey)
+      if (existing?.handle.isActive && existing.target === resolvedTarget) {
+        nextRegistrations.set(registrationKey, existing)
+        continue
+      }
+
+      if (existing?.handle.isActive) {
+        existing.handle.unregister()
+      }
+
+      const handle = managerRef.current.register(hotkeyStr, def.callback, {
+        ...mergedOptions,
+        target: resolvedTarget,
+      })
+      nextRegistrations.set(registrationKey, {
+        handle,
+        target: resolvedTarget,
+      })
+    }
+
+    registrationsRef.current = nextRegistrations
+
+    return () => {
+      for (const { handle } of registrationsRef.current.values()) {
+        if (handle.isActive) {
+          handle.unregister()
+        }
+      }
+      registrationsRef.current = new Map()
+    }
+  }, [hotkeyKey, enabledKey])
+
+  for (let i = 0; i < hotkeys.length; i++) {
+    const def = hotkeys[i]!
+    const hotkeyStr = hotkeyStrings[i]!
+    const registrationKey = `${i}:${hotkeyStr}`
+    const handle = registrationsRef.current.get(registrationKey)?.handle
+
+    if (handle?.isActive) {
+      handle.callback = def.callback
+      const mergedOptions = {
+        ...defaultOptions,
+        ...commonOptions,
+        ...def.options,
+      } as UseHotkeyOptions
+      const { target: _target, ...optionsWithoutTarget } = mergedOptions
+      handle.setOptions(optionsWithoutTarget)
+    }
+  }
+}

package/src/utils.ts

@@ -0,0 +1,8 @@
+import type { RefObject } from 'preact'
+
+/**
+ * Type guard to check if a value is a Preact ref-like object.
+ */
+export function isRef(value: unknown): value is RefObject<HTMLElement | null> {
+  return value !== null && typeof value === 'object' && 'current' in value
+}