@tanstack/react-hotkeys 0.2.0 → 0.3.0

package/dist/useHotkeySequence.cjs

@@ -37,27 +37,59 @@ let react = require("react");
 * ```
 */
 function useHotkeySequence(sequence, callback, options = {}) {
-	const { enabled = true, ...sequenceOptions } = {
+	const mergedOptions = {
 		...require_HotkeysProvider.useDefaultHotkeysOptions().hotkeySequence,
 		...options
 	};
-	const { timeout, platform } = sequenceOptions;
+	const manager = (0, _tanstack_hotkeys.getSequenceManager)();
+	const registrationRef = (0, react.useRef)(null);
 	const callbackRef = (0, react.useRef)(callback);
+	const optionsRef = (0, react.useRef)(mergedOptions);
+	const managerRef = (0, react.useRef)(manager);
 	callbackRef.current = callback;
+	optionsRef.current = mergedOptions;
+	managerRef.current = manager;
+	const prevTargetRef = (0, react.useRef)(null);
+	const prevSequenceRef = (0, react.useRef)(null);
+	const hotkeySequenceString = (0, _tanstack_hotkeys.formatHotkeySequence)(sequence);
+	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
 	(0, react.useEffect)(() => {
-		if (!enabled || sequence.length === 0) return;
-		const manager = (0, _tanstack_hotkeys.getSequenceManager)();
-		const registerOptions = { enabled: true };
-		if (timeout !== void 0) registerOptions.timeout = timeout;
-		if (platform !== void 0) registerOptions.platform = platform;
-		return manager.register(sequence, (event, context) => callbackRef.current(event, context), registerOptions);
+		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;
+			}
+		};
 	}, [
-		enabled,
-		sequence,
-		sequence.join("|"),
-		timeout,
-		platform
+		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 React ref-like object.
+*/
+function isRef(value) {
+	return value !== null && typeof value === "object" && "current" in value;
 }
 
 //#endregion

package/dist/useHotkeySequence.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkeySequence.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type {\n  HotkeyCallback,\n  HotkeySequence,\n  SequenceOptions,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'enabled'\n> {\n  /** Whether the sequence is enabled. Defaults to true. */\n  enabled?: boolean\n}\n\n/**\n * React 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 { enabled = true, ...sequenceOptions } = mergedOptions\n\n  // Extract options for stable dependencies\n  const { timeout, platform } = sequenceOptions\n\n  // Use refs to keep callback stable\n  const callbackRef = useRef(callback)\n  callbackRef.current = callback\n\n  // Serialize sequence for dependency comparison\n  const sequenceKey = sequence.join('|')\n\n  useEffect(() => {\n    if (!enabled || sequence.length === 0) {\n      return\n    }\n\n    const manager = getSequenceManager()\n\n    // Build options object conditionally to avoid overwriting manager defaults with undefined\n    const registerOptions: SequenceOptions = { enabled: true }\n    if (timeout !== undefined) registerOptions.timeout = timeout\n    if (platform !== undefined) registerOptions.platform = platform\n\n    const unregister = manager.register(\n      sequence,\n      (event, context) => callbackRef.current(event, context),\n      registerOptions,\n    )\n\n    return unregister\n  }, [enabled, sequence, sequenceKey, timeout, platform])\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CAMN,MAAM,EAAE,UAAU,MAAM,GAAG,oBALL;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAKD,MAAM,EAAE,SAAS,aAAa;CAG9B,MAAM,gCAAqB,SAAS;AACpC,aAAY,UAAU;AAKtB,4BAAgB;AACd,MAAI,CAAC,WAAW,SAAS,WAAW,EAClC;EAGF,MAAM,qDAA8B;EAGpC,MAAM,kBAAmC,EAAE,SAAS,MAAM;AAC1D,MAAI,YAAY,OAAW,iBAAgB,UAAU;AACrD,MAAI,aAAa,OAAW,iBAAgB,WAAW;AAQvD,SANmB,QAAQ,SACzB,WACC,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD,gBACD;IAGA;EAAC;EAAS;EArBO,SAAS,KAAK,IAAI;EAqBF;EAAS;EAAS,CAAC"}
+{"version":3,"file":"useHotkeySequence.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\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 React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React 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 React ref-like object.\n */\nfunction isRef(value: unknown): value is React.RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,qDAA8B;CAGpC,MAAM,oCAA4D,KAAK;CAGvE,MAAM,gCAAqB,SAAS;CACpC,MAAM,+BAAoB,cAAc;CACxC,MAAM,+BAAoB,QAAQ;AAGlC,aAAY,UAAU;AACtB,YAAW,UAAU;AACrB,YAAW,UAAU;CAGrB,MAAM,kCAA+D,KAAK;CAC1E,MAAM,oCAAwC,KAAK;CAGnD,MAAM,mEAA4C,SAAS;CAG3D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,4BAAgB;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,OAA8D;AAC3E,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}

package/dist/useHotkeySequence.d.cts

@@ -1,9 +1,13 @@
 import { HotkeyCallback, HotkeySequence, SequenceOptions } from "@tanstack/hotkeys";
 
 //#region src/useHotkeySequence.d.ts
-interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'enabled'> {
-  /** Whether the sequence is enabled. Defaults to true. */
-  enabled?: boolean;
+interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a React ref, direct DOM element, or null.
+   * Defaults to document.
+   */
+  target?: React.RefObject<HTMLElement | null> | HTMLElement | Document | Window | null;
 }
 /**
  * React hook for registering a keyboard shortcut sequence (Vim-style).

package/dist/useHotkeySequence.d.ts

@@ -1,9 +1,13 @@
 import { HotkeyCallback, HotkeySequence, SequenceOptions } from "@tanstack/hotkeys";
 
 //#region src/useHotkeySequence.d.ts
-interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'enabled'> {
-  /** Whether the sequence is enabled. Defaults to true. */
-  enabled?: boolean;
+interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a React ref, direct DOM element, or null.
+   * Defaults to document.
+   */
+  target?: React.RefObject<HTMLElement | null> | HTMLElement | Document | Window | null;
 }
 /**
  * React hook for registering a keyboard shortcut sequence (Vim-style).

package/dist/useHotkeySequence.js

@@ -1,5 +1,5 @@
 import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
-import { getSequenceManager } from "@tanstack/hotkeys";
+import { formatHotkeySequence, getSequenceManager } from "@tanstack/hotkeys";
 import { useEffect, useRef } from "react";
 
 //#region src/useHotkeySequence.ts
@@ -36,27 +36,59 @@ import { useEffect, useRef } from "react";
 * ```
 */
 function useHotkeySequence(sequence, callback, options = {}) {
-	const { enabled = true, ...sequenceOptions } = {
+	const mergedOptions = {
 		...useDefaultHotkeysOptions().hotkeySequence,
 		...options
 	};
-	const { timeout, platform } = sequenceOptions;
+	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 (!enabled || sequence.length === 0) return;
-		const manager = getSequenceManager();
-		const registerOptions = { enabled: true };
-		if (timeout !== void 0) registerOptions.timeout = timeout;
-		if (platform !== void 0) registerOptions.platform = platform;
-		return manager.register(sequence, (event, context) => callbackRef.current(event, context), registerOptions);
+		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;
+			}
+		};
 	}, [
-		enabled,
-		sequence,
-		sequence.join("|"),
-		timeout,
-		platform
+		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 React ref-like object.
+*/
+function isRef(value) {
+	return value !== null && typeof value === "object" && "current" in value;
 }
 
 //#endregion

package/dist/useHotkeySequence.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkeySequence.js","names":[],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type {\n  HotkeyCallback,\n  HotkeySequence,\n  SequenceOptions,\n} from '@tanstack/hotkeys'\n\nexport interface UseHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'enabled'\n> {\n  /** Whether the sequence is enabled. Defaults to true. */\n  enabled?: boolean\n}\n\n/**\n * React 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 { enabled = true, ...sequenceOptions } = mergedOptions\n\n  // Extract options for stable dependencies\n  const { timeout, platform } = sequenceOptions\n\n  // Use refs to keep callback stable\n  const callbackRef = useRef(callback)\n  callbackRef.current = callback\n\n  // Serialize sequence for dependency comparison\n  const sequenceKey = sequence.join('|')\n\n  useEffect(() => {\n    if (!enabled || sequence.length === 0) {\n      return\n    }\n\n    const manager = getSequenceManager()\n\n    // Build options object conditionally to avoid overwriting manager defaults with undefined\n    const registerOptions: SequenceOptions = { enabled: true }\n    if (timeout !== undefined) registerOptions.timeout = timeout\n    if (platform !== undefined) registerOptions.platform = platform\n\n    const unregister = manager.register(\n      sequence,\n      (event, context) => callbackRef.current(event, context),\n      registerOptions,\n    )\n\n    return unregister\n  }, [enabled, sequence, sequenceKey, timeout, platform])\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,SAAgB,kBACd,UACA,UACA,UAAoC,EAAE,EAChC;CAMN,MAAM,EAAE,UAAU,MAAM,GAAG,oBALL;EACpB,GAAG,0BAA0B,CAAC;EAC9B,GAAG;EACJ;CAKD,MAAM,EAAE,SAAS,aAAa;CAG9B,MAAM,cAAc,OAAO,SAAS;AACpC,aAAY,UAAU;AAKtB,iBAAgB;AACd,MAAI,CAAC,WAAW,SAAS,WAAW,EAClC;EAGF,MAAM,UAAU,oBAAoB;EAGpC,MAAM,kBAAmC,EAAE,SAAS,MAAM;AAC1D,MAAI,YAAY,OAAW,iBAAgB,UAAU;AACrD,MAAI,aAAa,OAAW,iBAAgB,WAAW;AAQvD,SANmB,QAAQ,SACzB,WACC,OAAO,YAAY,YAAY,QAAQ,OAAO,QAAQ,EACvD,gBACD;IAGA;EAAC;EAAS;EArBO,SAAS,KAAK,IAAI;EAqBF;EAAS;EAAS,CAAC"}
+{"version":3,"file":"useHotkeySequence.js","names":[],"sources":["../src/useHotkeySequence.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\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 React ref, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?:\n    | React.RefObject<HTMLElement | null>\n    | HTMLElement\n    | Document\n    | Window\n    | null\n}\n\n/**\n * React 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 React ref-like object.\n */\nfunction isRef(value: unknown): value is React.RefObject<HTMLElement | null> {\n  return value !== null && typeof value === 'object' && 'current' in value\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,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,OAA8D;AAC3E,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-hotkeys",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -40,7 +40,7 @@
   ],
   "dependencies": {
     "@tanstack/react-store": "^0.9.1",
-    "@tanstack/hotkeys": "0.2.0"
+    "@tanstack/hotkeys": "0.3.0"
   },
   "devDependencies": {
     "@eslint-react/eslint-plugin": "^2.13.0",

package/src/useHotkeySequence.ts

@@ -1,18 +1,29 @@
 import { useEffect, useRef } from 'react'
-import { getSequenceManager } from '@tanstack/hotkeys'
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
 import { useDefaultHotkeysOptions } from './HotkeysProvider'
 import type {
   HotkeyCallback,
+  HotkeyCallbackContext,
   HotkeySequence,
   SequenceOptions,
+  SequenceRegistrationHandle,
 } from '@tanstack/hotkeys'
 
 export interface UseHotkeySequenceOptions extends Omit<
   SequenceOptions,
-  'enabled'
+  'target'
 > {
-  /** Whether the sequence is enabled. Defaults to true. */
-  enabled?: boolean
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a React ref, direct DOM element, or null.
+   * Defaults to document.
+   */
+  target?:
+    | React.RefObject<HTMLElement | null>
+    | HTMLElement
+    | Document
+    | Window
+    | null
 }
 
 /**
@@ -57,36 +68,101 @@ export function useHotkeySequence(
     ...options,
   } as UseHotkeySequenceOptions
 
-  const { enabled = true, ...sequenceOptions } = mergedOptions
+  const manager = getSequenceManager()
 
-  // Extract options for stable dependencies
-  const { timeout, platform } = sequenceOptions
+  // Stable ref for registration handle
+  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)
 
-  // Use refs to keep callback stable
+  // Refs to capture current values for use in effect without adding dependencies
   const callbackRef = useRef(callback)
+  const optionsRef = useRef(mergedOptions)
+  const managerRef = useRef(manager)
+
+  // Update refs on every render
   callbackRef.current = callback
+  optionsRef.current = mergedOptions
+  managerRef.current = manager
+
+  // Track previous target and sequence to detect changes requiring re-registration
+  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)
+  const prevSequenceRef = useRef<string | null>(null)
 
-  // Serialize sequence for dependency comparison
-  const sequenceKey = sequence.join('|')
+  // Normalize to hotkey sequence string (join with spaces)
+  const hotkeySequenceString = formatHotkeySequence(sequence)
+
+  // Extract options without target (target is handled separately)
+  const { target: _target, ...optionsWithoutTarget } = mergedOptions
 
   useEffect(() => {
-    if (!enabled || sequence.length === 0) {
+    if (sequence.length === 0) {
+      return
+    }
+
+    // Resolve target inside the effect so refs are already attached after mount
+    const resolvedTarget = isRef(optionsRef.current.target)
+      ? optionsRef.current.target.current
+      : (optionsRef.current.target ??
+        (typeof document !== 'undefined' ? document : null))
+
+    // Skip if no valid target (SSR or ref still null)
+    if (!resolvedTarget) {
       return
     }
 
-    const manager = getSequenceManager()
+    // Check if we need to re-register (target or sequence changed)
+    const targetChanged =
+      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget
+    const sequenceChanged =
+      prevSequenceRef.current !== null &&
+      prevSequenceRef.current !== hotkeySequenceString
+
+    // If we have an active registration and target/sequence changed, unregister first
+    if (
+      registrationRef.current?.isActive &&
+      (targetChanged || sequenceChanged)
+    ) {
+      registrationRef.current.unregister()
+      registrationRef.current = null
+    }
+
+    // Register if needed (no active registration)
+    if (!registrationRef.current || !registrationRef.current.isActive) {
+      registrationRef.current = managerRef.current.register(
+        sequence,
+        (event, context) => callbackRef.current(event, context),
+        {
+          ...optionsRef.current,
+          target: resolvedTarget,
+        },
+      )
+    }
+
+    // Update tracking refs
+    prevTargetRef.current = resolvedTarget
+    prevSequenceRef.current = hotkeySequenceString
 
-    // Build options object conditionally to avoid overwriting manager defaults with undefined
-    const registerOptions: SequenceOptions = { enabled: true }
-    if (timeout !== undefined) registerOptions.timeout = timeout
-    if (platform !== undefined) registerOptions.platform = platform
+    // Cleanup on unmount
+    return () => {
+      if (registrationRef.current?.isActive) {
+        registrationRef.current.unregister()
+        registrationRef.current = null
+      }
+    }
+  }, [hotkeySequenceString, mergedOptions.enabled, sequence])
 
-    const unregister = manager.register(
-      sequence,
-      (event, context) => callbackRef.current(event, context),
-      registerOptions,
-    )
+  // Sync callback and options on EVERY render (outside useEffect)
+  if (registrationRef.current?.isActive) {
+    registrationRef.current.callback = (
+      event: KeyboardEvent,
+      context: HotkeyCallbackContext,
+    ) => callbackRef.current(event, context)
+    registrationRef.current.setOptions(optionsWithoutTarget)
+  }
+}
 
-    return unregister
-  }, [enabled, sequence, sequenceKey, timeout, platform])
+/**
+ * Type guard to check if a value is a React ref-like object.
+ */
+function isRef(value: unknown): value is React.RefObject<HTMLElement | null> {
+  return value !== null && typeof value === 'object' && 'current' in value
 }