@tanstack/preact-hotkeys 0.3.0

package/dist/useHotkeyRecorder.js

@@ -0,0 +1,71 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { HotkeyRecorder } from "@tanstack/hotkeys";
+import { useEffect, useRef } from "preact/hooks";
+import { useStore } from "@tanstack/preact-store";
+
+//#region src/useHotkeyRecorder.ts
+/**
+* Preact hook for recording keyboard shortcuts.
+*
+* This hook provides a thin wrapper around the framework-agnostic `HotkeyRecorder`
+* class, managing all the complexity of capturing keyboard events, converting them
+* to hotkey strings, and handling edge cases like Escape to cancel or Backspace/Delete
+* to clear.
+*
+* @param options - Configuration options for the recorder
+* @returns An object with recording state and control functions
+*
+* @example
+* ```tsx
+* function ShortcutSettings() {
+*   const [shortcut, setShortcut] = useState<Hotkey>('Mod+S')
+*
+*   const recorder = useHotkeyRecorder({
+*     onRecord: (hotkey) => {
+*       setShortcut(hotkey)
+*     },
+*     onCancel: () => {
+*       console.log('Recording cancelled')
+*     },
+*   })
+*
+*   return (
+*     <div>
+*       <button onClick={recorder.startRecording}>
+*         {recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}
+*       </button>
+*       {recorder.recordedHotkey && (
+*         <div>Recording: {recorder.recordedHotkey}</div>
+*       )}
+*     </div>
+*   )
+* }
+* ```
+*/
+function useHotkeyRecorder(options) {
+	const mergedOptions = {
+		...useDefaultHotkeysOptions().hotkeyRecorder,
+		...options
+	};
+	const recorderRef = useRef(null);
+	if (!recorderRef.current) recorderRef.current = new HotkeyRecorder(mergedOptions);
+	recorderRef.current.setOptions(mergedOptions);
+	const isRecording = useStore(recorderRef.current.store, (state) => state.isRecording);
+	const recordedHotkey = useStore(recorderRef.current.store, (state) => state.recordedHotkey);
+	useEffect(() => {
+		return () => {
+			recorderRef.current?.destroy();
+		};
+	}, []);
+	return {
+		isRecording,
+		recordedHotkey,
+		startRecording: () => recorderRef.current?.start(),
+		stopRecording: () => recorderRef.current?.stop(),
+		cancelRecording: () => recorderRef.current?.cancel()
+	};
+}
+
+//#endregion
+export { useHotkeyRecorder };
+//# sourceMappingURL=useHotkeyRecorder.js.map

package/dist/useHotkeyRecorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeyRecorder.js","names":[],"sources":["../src/useHotkeyRecorder.ts"],"sourcesContent":["import { useEffect, useRef } from 'preact/hooks'\nimport { useStore } from '@tanstack/preact-store'\nimport { HotkeyRecorder } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'\n\nexport interface PreactHotkeyRecorder {\n  /** Whether recording is currently active */\n  isRecording: boolean\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Hotkey | null\n  /** Start recording a new hotkey */\n  startRecording: () => void\n  /** Stop recording (same as cancel) */\n  stopRecording: () => void\n  /** Cancel recording without saving */\n  cancelRecording: () => void\n}\n\n/**\n * Preact hook for recording keyboard shortcuts.\n *\n * This hook provides a thin wrapper around the framework-agnostic `HotkeyRecorder`\n * class, managing all the complexity of capturing keyboard events, converting them\n * to hotkey strings, and handling edge cases like Escape to cancel or Backspace/Delete\n * to clear.\n *\n * @param options - Configuration options for the recorder\n * @returns An object with recording state and control functions\n *\n * @example\n * ```tsx\n * function ShortcutSettings() {\n *   const [shortcut, setShortcut] = useState<Hotkey>('Mod+S')\n *\n *   const recorder = useHotkeyRecorder({\n *     onRecord: (hotkey) => {\n *       setShortcut(hotkey)\n *     },\n *     onCancel: () => {\n *       console.log('Recording cancelled')\n *     },\n *   })\n *\n *   return (\n *     <div>\n *       <button onClick={recorder.startRecording}>\n *         {recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}\n *       </button>\n *       {recorder.recordedHotkey && (\n *         <div>Recording: {recorder.recordedHotkey}</div>\n *       )}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useHotkeyRecorder(\n  options: HotkeyRecorderOptions,\n): PreactHotkeyRecorder {\n  const mergedOptions = {\n    ...useDefaultHotkeysOptions().hotkeyRecorder,\n    ...options,\n  } as HotkeyRecorderOptions\n\n  const recorderRef = useRef<HotkeyRecorder | null>(null)\n\n  // Create recorder instance once\n  if (!recorderRef.current) {\n    recorderRef.current = new HotkeyRecorder(mergedOptions)\n  }\n\n  // Sync options on every render (same pattern as useHotkey)\n  // This ensures callbacks always have access to latest values\n  recorderRef.current.setOptions(mergedOptions)\n\n  // Subscribe to recorder state using useStore (same pattern as useHeldKeys)\n  const isRecording = useStore(\n    recorderRef.current.store,\n    (state) => state.isRecording,\n  )\n  const recordedHotkey = useStore(\n    recorderRef.current.store,\n    (state) => state.recordedHotkey,\n  )\n\n  // Cleanup on unmount\n  useEffect(() => {\n    return () => {\n      recorderRef.current?.destroy()\n    }\n  }, [])\n\n  return {\n    isRecording,\n    recordedHotkey,\n    startRecording: () => recorderRef.current?.start(),\n    stopRecording: () => recorderRef.current?.stop(),\n    cancelRecording: () => recorderRef.current?.cancel(),\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,kBACd,SACsB;CACtB,MAAM,gBAAgB;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,cAAc,OAA8B,KAAK;AAGvD,KAAI,CAAC,YAAY,QACf,aAAY,UAAU,IAAI,eAAe,cAAc;AAKzD,aAAY,QAAQ,WAAW,cAAc;CAG7C,MAAM,cAAc,SAClB,YAAY,QAAQ,QACnB,UAAU,MAAM,YAClB;CACD,MAAM,iBAAiB,SACrB,YAAY,QAAQ,QACnB,UAAU,MAAM,eAClB;AAGD,iBAAgB;AACd,eAAa;AACX,eAAY,SAAS,SAAS;;IAE/B,EAAE,CAAC;AAEN,QAAO;EACL;EACA;EACA,sBAAsB,YAAY,SAAS,OAAO;EAClD,qBAAqB,YAAY,SAAS,MAAM;EAChD,uBAAuB,YAAY,SAAS,QAAQ;EACrD"}

package/dist/useHotkeySequence.cjs

@@ -0,0 +1,96 @@
+const require_HotkeysProvider = require('./HotkeysProvider.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let preact_hooks = require("preact/hooks");
+
+//#region src/useHotkeySequence.ts
+/**
+* Preact hook for registering a keyboard shortcut sequence (Vim-style).
+*
+* This hook allows you to register multi-key sequences like 'g g' or 'd d'
+* that trigger when the full sequence is pressed within a timeout.
+*
+* @param sequence - Array of hotkey strings that form the sequence
+* @param callback - Function to call when the sequence is completed
+* @param options - Options for the sequence behavior
+*
+* @example
+* ```tsx
+* function VimEditor() {
+*   // 'g g' to go to top
+*   useHotkeySequence(['G', 'G'], () => {
+*     scrollToTop()
+*   })
+*
+*   // 'd d' to delete line
+*   useHotkeySequence(['D', 'D'], () => {
+*     deleteLine()
+*   })
+*
+*   // 'd i w' to delete inner word
+*   useHotkeySequence(['D', 'I', 'W'], () => {
+*     deleteInnerWord()
+*   }, { timeout: 500 })
+*
+*   return <div>...</div>
+* }
+* ```
+*/
+function useHotkeySequence(sequence, callback, options = {}) {
+	const mergedOptions = {
+		...require_HotkeysProvider.useDefaultHotkeysOptions().hotkeySequence,
+		...options
+	};
+	const manager = (0, _tanstack_hotkeys.getSequenceManager)();
+	const registrationRef = (0, preact_hooks.useRef)(null);
+	const callbackRef = (0, preact_hooks.useRef)(callback);
+	const optionsRef = (0, preact_hooks.useRef)(mergedOptions);
+	const managerRef = (0, preact_hooks.useRef)(manager);
+	callbackRef.current = callback;
+	optionsRef.current = mergedOptions;
+	managerRef.current = manager;
+	const prevTargetRef = (0, preact_hooks.useRef)(null);
+	const prevSequenceRef = (0, preact_hooks.useRef)(null);
+	const hotkeySequenceString = (0, _tanstack_hotkeys.formatHotkeySequence)(sequence);
+	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);
+		if (!resolvedTarget) return;
+		const targetChanged = prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget;
+		const sequenceChanged = prevSequenceRef.current !== null && prevSequenceRef.current !== hotkeySequenceString;
+		if (registrationRef.current?.isActive && (targetChanged || sequenceChanged)) {
+			registrationRef.current.unregister();
+			registrationRef.current = null;
+		}
+		if (!registrationRef.current || !registrationRef.current.isActive) registrationRef.current = managerRef.current.register(sequence, (event, context) => callbackRef.current(event, context), {
+			...optionsRef.current,
+			target: resolvedTarget
+		});
+		prevTargetRef.current = resolvedTarget;
+		prevSequenceRef.current = hotkeySequenceString;
+		return () => {
+			if (registrationRef.current?.isActive) {
+				registrationRef.current.unregister();
+				registrationRef.current = null;
+			}
+		};
+	}, [
+		hotkeySequenceString,
+		mergedOptions.enabled,
+		sequence
+	]);
+	if (registrationRef.current?.isActive) {
+		registrationRef.current.callback = (event, context) => callbackRef.current(event, context);
+		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;
+//# sourceMappingURL=useHotkeySequence.cjs.map

package/dist/useHotkeySequence.cjs.map

@@ -0,0 +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"}

package/dist/useHotkeySequence.d.cts

@@ -0,0 +1,48 @@
+import { HotkeyCallback, HotkeySequence, SequenceOptions } from "@tanstack/hotkeys";
+import { RefObject } from "preact";
+
+//#region src/useHotkeySequence.d.ts
+interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a Preact ref, direct DOM element, or null.
+   * Defaults to document.
+   */
+  target?: RefObject<HTMLElement | null> | HTMLElement | Document | Window | null;
+}
+/**
+ * Preact hook for registering a keyboard shortcut sequence (Vim-style).
+ *
+ * This hook allows you to register multi-key sequences like 'g g' or 'd d'
+ * that trigger when the full sequence is pressed within a timeout.
+ *
+ * @param sequence - Array of hotkey strings that form the sequence
+ * @param callback - Function to call when the sequence is completed
+ * @param options - Options for the sequence behavior
+ *
+ * @example
+ * ```tsx
+ * function VimEditor() {
+ *   // 'g g' to go to top
+ *   useHotkeySequence(['G', 'G'], () => {
+ *     scrollToTop()
+ *   })
+ *
+ *   // 'd d' to delete line
+ *   useHotkeySequence(['D', 'D'], () => {
+ *     deleteLine()
+ *   })
+ *
+ *   // 'd i w' to delete inner word
+ *   useHotkeySequence(['D', 'I', 'W'], () => {
+ *     deleteInnerWord()
+ *   }, { timeout: 500 })
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+declare function useHotkeySequence(sequence: HotkeySequence, callback: HotkeyCallback, options?: UseHotkeySequenceOptions): void;
+//#endregion
+export { UseHotkeySequenceOptions, useHotkeySequence };
+//# sourceMappingURL=useHotkeySequence.d.cts.map

package/dist/useHotkeySequence.d.ts

@@ -0,0 +1,48 @@
+import { HotkeyCallback, HotkeySequence, SequenceOptions } from "@tanstack/hotkeys";
+import { RefObject } from "preact";
+
+//#region src/useHotkeySequence.d.ts
+interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a Preact ref, direct DOM element, or null.
+   * Defaults to document.
+   */
+  target?: RefObject<HTMLElement | null> | HTMLElement | Document | Window | null;
+}
+/**
+ * Preact hook for registering a keyboard shortcut sequence (Vim-style).
+ *
+ * This hook allows you to register multi-key sequences like 'g g' or 'd d'
+ * that trigger when the full sequence is pressed within a timeout.
+ *
+ * @param sequence - Array of hotkey strings that form the sequence
+ * @param callback - Function to call when the sequence is completed
+ * @param options - Options for the sequence behavior
+ *
+ * @example
+ * ```tsx
+ * function VimEditor() {
+ *   // 'g g' to go to top
+ *   useHotkeySequence(['G', 'G'], () => {
+ *     scrollToTop()
+ *   })
+ *
+ *   // 'd d' to delete line
+ *   useHotkeySequence(['D', 'D'], () => {
+ *     deleteLine()
+ *   })
+ *
+ *   // 'd i w' to delete inner word
+ *   useHotkeySequence(['D', 'I', 'W'], () => {
+ *     deleteInnerWord()
+ *   }, { timeout: 500 })
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+declare function useHotkeySequence(sequence: HotkeySequence, callback: HotkeyCallback, options?: UseHotkeySequenceOptions): void;
+//#endregion
+export { UseHotkeySequenceOptions, useHotkeySequence };
+//# sourceMappingURL=useHotkeySequence.d.ts.map

package/dist/useHotkeySequence.js

@@ -0,0 +1,96 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { formatHotkeySequence, getSequenceManager } from "@tanstack/hotkeys";
+import { useEffect, useRef } from "preact/hooks";
+
+//#region src/useHotkeySequence.ts
+/**
+* Preact hook for registering a keyboard shortcut sequence (Vim-style).
+*
+* This hook allows you to register multi-key sequences like 'g g' or 'd d'
+* that trigger when the full sequence is pressed within a timeout.
+*
+* @param sequence - Array of hotkey strings that form the sequence
+* @param callback - Function to call when the sequence is completed
+* @param options - Options for the sequence behavior
+*
+* @example
+* ```tsx
+* function VimEditor() {
+*   // 'g g' to go to top
+*   useHotkeySequence(['G', 'G'], () => {
+*     scrollToTop()
+*   })
+*
+*   // 'd d' to delete line
+*   useHotkeySequence(['D', 'D'], () => {
+*     deleteLine()
+*   })
+*
+*   // 'd i w' to delete inner word
+*   useHotkeySequence(['D', 'I', 'W'], () => {
+*     deleteInnerWord()
+*   }, { timeout: 500 })
+*
+*   return <div>...</div>
+* }
+* ```
+*/
+function useHotkeySequence(sequence, callback, options = {}) {
+	const mergedOptions = {
+		...useDefaultHotkeysOptions().hotkeySequence,
+		...options
+	};
+	const manager = getSequenceManager();
+	const registrationRef = useRef(null);
+	const callbackRef = useRef(callback);
+	const optionsRef = useRef(mergedOptions);
+	const managerRef = useRef(manager);
+	callbackRef.current = callback;
+	optionsRef.current = mergedOptions;
+	managerRef.current = manager;
+	const prevTargetRef = useRef(null);
+	const prevSequenceRef = useRef(null);
+	const hotkeySequenceString = formatHotkeySequence(sequence);
+	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+	useEffect(() => {
+		if (sequence.length === 0) return;
+		const resolvedTarget = 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;
+		if (registrationRef.current?.isActive && (targetChanged || sequenceChanged)) {
+			registrationRef.current.unregister();
+			registrationRef.current = null;
+		}
+		if (!registrationRef.current || !registrationRef.current.isActive) registrationRef.current = managerRef.current.register(sequence, (event, context) => callbackRef.current(event, context), {
+			...optionsRef.current,
+			target: resolvedTarget
+		});
+		prevTargetRef.current = resolvedTarget;
+		prevSequenceRef.current = hotkeySequenceString;
+		return () => {
+			if (registrationRef.current?.isActive) {
+				registrationRef.current.unregister();
+				registrationRef.current = null;
+			}
+		};
+	}, [
+		hotkeySequenceString,
+		mergedOptions.enabled,
+		sequence
+	]);
+	if (registrationRef.current?.isActive) {
+		registrationRef.current.callback = (event, context) => callbackRef.current(event, context);
+		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 };
+//# sourceMappingURL=useHotkeySequence.js.map

package/dist/useHotkeySequence.js.map

@@ -0,0 +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"}

package/dist/useKeyHold.cjs

@@ -0,0 +1,53 @@
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let _tanstack_preact_store = require("@tanstack/preact-store");
+
+//#region src/useKeyHold.ts
+/**
+* Preact hook that returns whether a specific key is currently being held.
+*
+* This hook uses `useStore` from `@tanstack/preact-store` to subscribe
+* to the global KeyStateTracker and uses a selector to determine if
+* the specified key is held.
+*
+* @param key - The key to check (e.g., 'Shift', 'Control', 'A')
+* @returns True if the key is currently held down
+*
+* @example
+* ```tsx
+* function ShiftIndicator() {
+*   const isShiftHeld = useKeyHold('Shift')
+*
+*   return (
+*     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
+*       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
+*     </div>
+*   )
+* }
+* ```
+*
+* @example
+* ```tsx
+* function ModifierIndicators() {
+*   const ctrl = useKeyHold('Control')
+*   const shift = useKeyHold('Shift')
+*   const alt = useKeyHold('Alt')
+*
+*   return (
+*     <div>
+*       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>
+*       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>
+*       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>
+*     </div>
+*   )
+* }
+* ```
+*/
+function useKeyHold(key) {
+	const tracker = (0, _tanstack_hotkeys.getKeyStateTracker)();
+	const normalizedKey = key.toLowerCase();
+	return (0, _tanstack_preact_store.useStore)(tracker.store, (state) => state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey));
+}
+
+//#endregion
+exports.useKeyHold = useKeyHold;
+//# sourceMappingURL=useKeyHold.cjs.map

package/dist/useKeyHold.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyHold.cjs","names":[],"sources":["../src/useKeyHold.ts"],"sourcesContent":["import { useStore } from '@tanstack/preact-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\nimport type { HeldKey } from '@tanstack/hotkeys'\n\n/**\n * Preact hook that returns whether a specific key is currently being held.\n *\n * This hook uses `useStore` from `@tanstack/preact-store` to subscribe\n * to the global KeyStateTracker and uses a selector to determine if\n * the specified key is held.\n *\n * @param key - The key to check (e.g., 'Shift', 'Control', 'A')\n * @returns True if the key is currently held down\n *\n * @example\n * ```tsx\n * function ShiftIndicator() {\n *   const isShiftHeld = useKeyHold('Shift')\n *\n *   return (\n *     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>\n *       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}\n *     </div>\n *   )\n * }\n * ```\n *\n * @example\n * ```tsx\n * function ModifierIndicators() {\n *   const ctrl = useKeyHold('Control')\n *   const shift = useKeyHold('Shift')\n *   const alt = useKeyHold('Alt')\n *\n *   return (\n *     <div>\n *       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>\n *       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>\n *       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useKeyHold(key: HeldKey): boolean {\n  const tracker = getKeyStateTracker()\n  const normalizedKey = key.toLowerCase()\n\n  return useStore(tracker.store, (state) =>\n    state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey),\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,WAAW,KAAuB;CAChD,MAAM,qDAA8B;CACpC,MAAM,gBAAgB,IAAI,aAAa;AAEvC,6CAAgB,QAAQ,QAAQ,UAC9B,MAAM,SAAS,MAAM,YAAY,QAAQ,aAAa,KAAK,cAAc,CAC1E"}

package/dist/useKeyHold.d.cts

@@ -0,0 +1,47 @@
+import { HeldKey } from "@tanstack/hotkeys";
+
+//#region src/useKeyHold.d.ts
+/**
+ * Preact hook that returns whether a specific key is currently being held.
+ *
+ * This hook uses `useStore` from `@tanstack/preact-store` to subscribe
+ * to the global KeyStateTracker and uses a selector to determine if
+ * the specified key is held.
+ *
+ * @param key - The key to check (e.g., 'Shift', 'Control', 'A')
+ * @returns True if the key is currently held down
+ *
+ * @example
+ * ```tsx
+ * function ShiftIndicator() {
+ *   const isShiftHeld = useKeyHold('Shift')
+ *
+ *   return (
+ *     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
+ *       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ModifierIndicators() {
+ *   const ctrl = useKeyHold('Control')
+ *   const shift = useKeyHold('Shift')
+ *   const alt = useKeyHold('Alt')
+ *
+ *   return (
+ *     <div>
+ *       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>
+ *       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>
+ *       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useKeyHold(key: HeldKey): boolean;
+//#endregion
+export { useKeyHold };
+//# sourceMappingURL=useKeyHold.d.cts.map

package/dist/useKeyHold.d.ts

@@ -0,0 +1,47 @@
+import { HeldKey } from "@tanstack/hotkeys";
+
+//#region src/useKeyHold.d.ts
+/**
+ * Preact hook that returns whether a specific key is currently being held.
+ *
+ * This hook uses `useStore` from `@tanstack/preact-store` to subscribe
+ * to the global KeyStateTracker and uses a selector to determine if
+ * the specified key is held.
+ *
+ * @param key - The key to check (e.g., 'Shift', 'Control', 'A')
+ * @returns True if the key is currently held down
+ *
+ * @example
+ * ```tsx
+ * function ShiftIndicator() {
+ *   const isShiftHeld = useKeyHold('Shift')
+ *
+ *   return (
+ *     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
+ *       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ModifierIndicators() {
+ *   const ctrl = useKeyHold('Control')
+ *   const shift = useKeyHold('Shift')
+ *   const alt = useKeyHold('Alt')
+ *
+ *   return (
+ *     <div>
+ *       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>
+ *       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>
+ *       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useKeyHold(key: HeldKey): boolean;
+//#endregion
+export { useKeyHold };
+//# sourceMappingURL=useKeyHold.d.ts.map

package/dist/useKeyHold.js

@@ -0,0 +1,53 @@
+import { getKeyStateTracker } from "@tanstack/hotkeys";
+import { useStore } from "@tanstack/preact-store";
+
+//#region src/useKeyHold.ts
+/**
+* Preact hook that returns whether a specific key is currently being held.
+*
+* This hook uses `useStore` from `@tanstack/preact-store` to subscribe
+* to the global KeyStateTracker and uses a selector to determine if
+* the specified key is held.
+*
+* @param key - The key to check (e.g., 'Shift', 'Control', 'A')
+* @returns True if the key is currently held down
+*
+* @example
+* ```tsx
+* function ShiftIndicator() {
+*   const isShiftHeld = useKeyHold('Shift')
+*
+*   return (
+*     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
+*       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
+*     </div>
+*   )
+* }
+* ```
+*
+* @example
+* ```tsx
+* function ModifierIndicators() {
+*   const ctrl = useKeyHold('Control')
+*   const shift = useKeyHold('Shift')
+*   const alt = useKeyHold('Alt')
+*
+*   return (
+*     <div>
+*       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>
+*       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>
+*       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>
+*     </div>
+*   )
+* }
+* ```
+*/
+function useKeyHold(key) {
+	const tracker = getKeyStateTracker();
+	const normalizedKey = key.toLowerCase();
+	return useStore(tracker.store, (state) => state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey));
+}
+
+//#endregion
+export { useKeyHold };
+//# sourceMappingURL=useKeyHold.js.map

package/dist/useKeyHold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyHold.js","names":[],"sources":["../src/useKeyHold.ts"],"sourcesContent":["import { useStore } from '@tanstack/preact-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\nimport type { HeldKey } from '@tanstack/hotkeys'\n\n/**\n * Preact hook that returns whether a specific key is currently being held.\n *\n * This hook uses `useStore` from `@tanstack/preact-store` to subscribe\n * to the global KeyStateTracker and uses a selector to determine if\n * the specified key is held.\n *\n * @param key - The key to check (e.g., 'Shift', 'Control', 'A')\n * @returns True if the key is currently held down\n *\n * @example\n * ```tsx\n * function ShiftIndicator() {\n *   const isShiftHeld = useKeyHold('Shift')\n *\n *   return (\n *     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>\n *       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}\n *     </div>\n *   )\n * }\n * ```\n *\n * @example\n * ```tsx\n * function ModifierIndicators() {\n *   const ctrl = useKeyHold('Control')\n *   const shift = useKeyHold('Shift')\n *   const alt = useKeyHold('Alt')\n *\n *   return (\n *     <div>\n *       <span style={{ opacity: ctrl ? 1 : 0.3 }}>Ctrl</span>\n *       <span style={{ opacity: shift ? 1 : 0.3 }}>Shift</span>\n *       <span style={{ opacity: alt ? 1 : 0.3 }}>Alt</span>\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useKeyHold(key: HeldKey): boolean {\n  const tracker = getKeyStateTracker()\n  const normalizedKey = key.toLowerCase()\n\n  return useStore(tracker.store, (state) =>\n    state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey),\n  )\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,WAAW,KAAuB;CAChD,MAAM,UAAU,oBAAoB;CACpC,MAAM,gBAAgB,IAAI,aAAa;AAEvC,QAAO,SAAS,QAAQ,QAAQ,UAC9B,MAAM,SAAS,MAAM,YAAY,QAAQ,aAAa,KAAK,cAAc,CAC1E"}