@tanstack/react-hotkeys 0.0.1 → 0.0.3

package/dist/useHeldKeys.js

@@ -0,0 +1,33 @@
+import { getKeyStateTracker } from "@tanstack/hotkeys";
+import { useStore } from "@tanstack/react-store";
+
+//#region src/useHeldKeys.ts
+/**
+* React hook that returns an array of currently held keyboard keys.
+*
+* This hook uses `useStore` from `@tanstack/react-store` to subscribe
+* to the global KeyStateTracker and updates whenever keys are pressed
+* or released.
+*
+* @returns Array of currently held key names
+*
+* @example
+* ```tsx
+* function KeyDisplay() {
+*   const heldKeys = useHeldKeys()
+*
+*   return (
+*     <div>
+*       Currently pressed: {heldKeys.join(' + ') || 'None'}
+*     </div>
+*   )
+* }
+* ```
+*/
+function useHeldKeys() {
+	return useStore(getKeyStateTracker().store, (state) => state.heldKeys);
+}
+
+//#endregion
+export { useHeldKeys };
+//# sourceMappingURL=useHeldKeys.js.map

package/dist/useHeldKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHeldKeys.js","names":[],"sources":["../src/useHeldKeys.ts"],"sourcesContent":["import { useStore } from '@tanstack/react-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\n\n/**\n * React hook that returns an array of currently held keyboard keys.\n *\n * This hook uses `useStore` from `@tanstack/react-store` to subscribe\n * to the global KeyStateTracker and updates whenever keys are pressed\n * or released.\n *\n * @returns Array of currently held key names\n *\n * @example\n * ```tsx\n * function KeyDisplay() {\n *   const heldKeys = useHeldKeys()\n *\n *   return (\n *     <div>\n *       Currently pressed: {heldKeys.join(' + ') || 'None'}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useHeldKeys(): Array<string> {\n  const tracker = getKeyStateTracker()\n  return useStore(tracker.store, (state) => state.heldKeys)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,cAA6B;AAE3C,QAAO,SADS,oBAAoB,CACZ,QAAQ,UAAU,MAAM,SAAS"}

package/dist/useHotkey.cjs

@@ -0,0 +1,119 @@
+const require_runtime = require('./_virtual/_rolldown/runtime.cjs');
+const require_HotkeysProvider = require('./HotkeysProvider.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let react = require("react");
+
+//#region src/useHotkey.ts
+/**
+* React hook for registering a keyboard hotkey.
+*
+* Uses the singleton HotkeyManager for efficient event handling.
+* The callback receives both the keyboard event and a context object
+* containing the hotkey string and parsed hotkey.
+*
+* This hook syncs the callback and options on every render to avoid
+* stale closures. This means
+* callbacks that reference React state will always have access to
+* the latest values.
+*
+* @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
+* @param callback - The function to call when the hotkey is pressed
+* @param options - Options for the hotkey behavior
+*
+* @example
+* ```tsx
+* function SaveButton() {
+*   const [count, setCount] = useState(0)
+*
+*   // Callback always has access to latest count value
+*   useHotkey('Mod+S', (event, { hotkey }) => {
+*     console.log(`Save triggered, count is ${count}`)
+*     handleSave()
+*   })
+*
+*   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+* }
+* ```
+*
+* @example
+* ```tsx
+* function Modal({ isOpen, onClose }) {
+*   // enabled option is synced on every render
+*   useHotkey('Escape', () => {
+*     onClose()
+*   }, { enabled: isOpen })
+*
+*   if (!isOpen) return null
+*   return <div className="modal">...</div>
+* }
+* ```
+*
+* @example
+* ```tsx
+* function Editor() {
+*   const editorRef = useRef<HTMLDivElement>(null)
+*
+*   // Scoped to a specific element
+*   useHotkey('Mod+S', () => {
+*     save()
+*   }, { target: editorRef })
+*
+*   return <div ref={editorRef}>...</div>
+* }
+* ```
+*/
+function useHotkey(hotkey, callback, options = {}) {
+	const mergedOptions = {
+		...require_HotkeysProvider.useDefaultHotkeysOptions().hotkey,
+		...options
+	};
+	const manager = (0, _tanstack_hotkeys.getHotkeyManager)();
+	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 prevHotkeyRef = (0, react.useRef)(null);
+	const platform = mergedOptions.platform ?? (0, _tanstack_hotkeys.detectPlatform)();
+	const hotkeyString = typeof hotkey === "string" ? hotkey : (0, _tanstack_hotkeys.formatHotkey)((0, _tanstack_hotkeys.rawHotkeyToParsedHotkey)(hotkey, platform));
+	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+	(0, react.useEffect)(() => {
+		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 hotkeyChanged = prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString;
+		if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {
+			registrationRef.current.unregister();
+			registrationRef.current = null;
+		}
+		if (!registrationRef.current || !registrationRef.current.isActive) registrationRef.current = managerRef.current.register(hotkeyString, callbackRef.current, {
+			...optionsRef.current,
+			target: resolvedTarget
+		});
+		prevTargetRef.current = resolvedTarget;
+		prevHotkeyRef.current = hotkeyString;
+		return () => {
+			if (registrationRef.current?.isActive) {
+				registrationRef.current.unregister();
+				registrationRef.current = null;
+			}
+		};
+	}, [hotkeyString, options.enabled]);
+	if (registrationRef.current?.isActive) {
+		registrationRef.current.callback = callback;
+		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
+exports.useHotkey = useHotkey;
+//# sourceMappingURL=useHotkey.cjs.map

package/dist/useHotkey.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkey.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\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 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 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 React 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 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,SAAgB,UACd,QACA,UACA,UAA4B,EAAE,EACxB;CACN,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,mDAA4B;CAGlC,MAAM,oCAA0D,KAAK;CAGrE,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,kCAAsC,KAAK;CAGjD,MAAM,WAAW,cAAc,mDAA4B;CAC3D,MAAM,eACJ,OAAO,WAAW,WACd,4FACsC,QAAQ,SAAS,CAAC;CAG9D,MAAM,EAAE,QAAQ,SAAS,GAAG,yBAAyB;AAErD,4BAAgB;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,OAA8D;AAC3E,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}

package/dist/useHotkey.d.cts

@@ -0,0 +1,73 @@
+import { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+
+//#region src/useHotkey.d.ts
+interface UseHotkeyOptions extends Omit<HotkeyOptions, '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 hotkey.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * The callback receives both the keyboard event and a context object
+ * containing the hotkey string and parsed hotkey.
+ *
+ * This hook syncs the callback and options on every render to avoid
+ * stale closures. This means
+ * callbacks that reference React state will always have access to
+ * the latest values.
+ *
+ * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
+ * @param callback - The function to call when the hotkey is pressed
+ * @param options - Options for the hotkey behavior
+ *
+ * @example
+ * ```tsx
+ * function SaveButton() {
+ *   const [count, setCount] = useState(0)
+ *
+ *   // Callback always has access to latest count value
+ *   useHotkey('Mod+S', (event, { hotkey }) => {
+ *     console.log(`Save triggered, count is ${count}`)
+ *     handleSave()
+ *   })
+ *
+ *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function Modal({ isOpen, onClose }) {
+ *   // enabled option is synced on every render
+ *   useHotkey('Escape', () => {
+ *     onClose()
+ *   }, { enabled: isOpen })
+ *
+ *   if (!isOpen) return null
+ *   return <div className="modal">...</div>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const editorRef = useRef<HTMLDivElement>(null)
+ *
+ *   // Scoped to a specific element
+ *   useHotkey('Mod+S', () => {
+ *     save()
+ *   }, { target: editorRef })
+ *
+ *   return <div ref={editorRef}>...</div>
+ * }
+ * ```
+ */
+declare function useHotkey(hotkey: RegisterableHotkey, callback: HotkeyCallback, options?: UseHotkeyOptions): void;
+//#endregion
+export { UseHotkeyOptions, useHotkey };
+//# sourceMappingURL=useHotkey.d.cts.map

package/dist/useHotkey.d.ts

@@ -0,0 +1,73 @@
+import { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+
+//#region src/useHotkey.d.ts
+interface UseHotkeyOptions extends Omit<HotkeyOptions, '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 hotkey.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * The callback receives both the keyboard event and a context object
+ * containing the hotkey string and parsed hotkey.
+ *
+ * This hook syncs the callback and options on every render to avoid
+ * stale closures. This means
+ * callbacks that reference React state will always have access to
+ * the latest values.
+ *
+ * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
+ * @param callback - The function to call when the hotkey is pressed
+ * @param options - Options for the hotkey behavior
+ *
+ * @example
+ * ```tsx
+ * function SaveButton() {
+ *   const [count, setCount] = useState(0)
+ *
+ *   // Callback always has access to latest count value
+ *   useHotkey('Mod+S', (event, { hotkey }) => {
+ *     console.log(`Save triggered, count is ${count}`)
+ *     handleSave()
+ *   })
+ *
+ *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function Modal({ isOpen, onClose }) {
+ *   // enabled option is synced on every render
+ *   useHotkey('Escape', () => {
+ *     onClose()
+ *   }, { enabled: isOpen })
+ *
+ *   if (!isOpen) return null
+ *   return <div className="modal">...</div>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const editorRef = useRef<HTMLDivElement>(null)
+ *
+ *   // Scoped to a specific element
+ *   useHotkey('Mod+S', () => {
+ *     save()
+ *   }, { target: editorRef })
+ *
+ *   return <div ref={editorRef}>...</div>
+ * }
+ * ```
+ */
+declare function useHotkey(hotkey: RegisterableHotkey, callback: HotkeyCallback, options?: UseHotkeyOptions): void;
+//#endregion
+export { UseHotkeyOptions, useHotkey };
+//# sourceMappingURL=useHotkey.d.ts.map

package/dist/useHotkey.js

@@ -0,0 +1,118 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { detectPlatform, formatHotkey, getHotkeyManager, rawHotkeyToParsedHotkey } from "@tanstack/hotkeys";
+import { useEffect, useRef } from "react";
+
+//#region src/useHotkey.ts
+/**
+* React hook for registering a keyboard hotkey.
+*
+* Uses the singleton HotkeyManager for efficient event handling.
+* The callback receives both the keyboard event and a context object
+* containing the hotkey string and parsed hotkey.
+*
+* This hook syncs the callback and options on every render to avoid
+* stale closures. This means
+* callbacks that reference React state will always have access to
+* the latest values.
+*
+* @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
+* @param callback - The function to call when the hotkey is pressed
+* @param options - Options for the hotkey behavior
+*
+* @example
+* ```tsx
+* function SaveButton() {
+*   const [count, setCount] = useState(0)
+*
+*   // Callback always has access to latest count value
+*   useHotkey('Mod+S', (event, { hotkey }) => {
+*     console.log(`Save triggered, count is ${count}`)
+*     handleSave()
+*   })
+*
+*   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+* }
+* ```
+*
+* @example
+* ```tsx
+* function Modal({ isOpen, onClose }) {
+*   // enabled option is synced on every render
+*   useHotkey('Escape', () => {
+*     onClose()
+*   }, { enabled: isOpen })
+*
+*   if (!isOpen) return null
+*   return <div className="modal">...</div>
+* }
+* ```
+*
+* @example
+* ```tsx
+* function Editor() {
+*   const editorRef = useRef<HTMLDivElement>(null)
+*
+*   // Scoped to a specific element
+*   useHotkey('Mod+S', () => {
+*     save()
+*   }, { target: editorRef })
+*
+*   return <div ref={editorRef}>...</div>
+* }
+* ```
+*/
+function useHotkey(hotkey, callback, options = {}) {
+	const mergedOptions = {
+		...useDefaultHotkeysOptions().hotkey,
+		...options
+	};
+	const manager = getHotkeyManager();
+	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 prevHotkeyRef = useRef(null);
+	const platform = mergedOptions.platform ?? detectPlatform();
+	const hotkeyString = typeof hotkey === "string" ? hotkey : formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform));
+	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+	useEffect(() => {
+		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 hotkeyChanged = prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString;
+		if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {
+			registrationRef.current.unregister();
+			registrationRef.current = null;
+		}
+		if (!registrationRef.current || !registrationRef.current.isActive) registrationRef.current = managerRef.current.register(hotkeyString, callbackRef.current, {
+			...optionsRef.current,
+			target: resolvedTarget
+		});
+		prevTargetRef.current = resolvedTarget;
+		prevHotkeyRef.current = hotkeyString;
+		return () => {
+			if (registrationRef.current?.isActive) {
+				registrationRef.current.unregister();
+				registrationRef.current = null;
+			}
+		};
+	}, [hotkeyString, options.enabled]);
+	if (registrationRef.current?.isActive) {
+		registrationRef.current.callback = callback;
+		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
+export { useHotkey };
+//# sourceMappingURL=useHotkey.js.map

package/dist/useHotkey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkey.js","names":[],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\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 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 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 React 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 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,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,OAA8D;AAC3E,QAAO,UAAU,QAAQ,OAAO,UAAU,YAAY,aAAa"}

package/dist/useHotkeyRecorder.cjs

@@ -0,0 +1,72 @@
+const require_runtime = require('./_virtual/_rolldown/runtime.cjs');
+const require_HotkeysProvider = require('./HotkeysProvider.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let react = require("react");
+let _tanstack_react_store = require("@tanstack/react-store");
+
+//#region src/useHotkeyRecorder.ts
+/**
+* React 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 = {
+		...require_HotkeysProvider.useDefaultHotkeysOptions().hotkeyRecorder,
+		...options
+	};
+	const recorderRef = (0, react.useRef)(null);
+	if (!recorderRef.current) recorderRef.current = new _tanstack_hotkeys.HotkeyRecorder(mergedOptions);
+	recorderRef.current.setOptions(mergedOptions);
+	const isRecording = (0, _tanstack_react_store.useStore)(recorderRef.current.store, (state) => state.isRecording);
+	const recordedHotkey = (0, _tanstack_react_store.useStore)(recorderRef.current.store, (state) => state.recordedHotkey);
+	(0, react.useEffect)(() => {
+		return () => {
+			recorderRef.current?.destroy();
+		};
+	}, []);
+	return {
+		isRecording,
+		recordedHotkey,
+		startRecording: () => recorderRef.current?.start(),
+		stopRecording: () => recorderRef.current?.stop(),
+		cancelRecording: () => recorderRef.current?.cancel()
+	};
+}
+
+//#endregion
+exports.useHotkeyRecorder = useHotkeyRecorder;
+//# sourceMappingURL=useHotkeyRecorder.cjs.map

package/dist/useHotkeyRecorder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeyRecorder.cjs","names":["useDefaultHotkeysOptions","HotkeyRecorder"],"sources":["../src/useHotkeyRecorder.ts"],"sourcesContent":["import { useEffect, useRef } from 'react'\nimport { useStore } from '@tanstack/react-store'\nimport { HotkeyRecorder } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProvider'\nimport type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'\n\nexport interface ReactHotkeyRecorder {\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 * React 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): ReactHotkeyRecorder {\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,SACqB;CACrB,MAAM,gBAAgB;EACpB,GAAGA,kDAA0B,CAAC;EAC9B,GAAG;EACJ;CAED,MAAM,gCAA4C,KAAK;AAGvD,KAAI,CAAC,YAAY,QACf,aAAY,UAAU,IAAIC,iCAAe,cAAc;AAKzD,aAAY,QAAQ,WAAW,cAAc;CAG7C,MAAM,kDACJ,YAAY,QAAQ,QACnB,UAAU,MAAM,YAClB;CACD,MAAM,qDACJ,YAAY,QAAQ,QACnB,UAAU,MAAM,eAClB;AAGD,4BAAgB;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/useHotkeyRecorder.d.cts

@@ -0,0 +1,57 @@
+import { Hotkey, HotkeyRecorderOptions } from "@tanstack/hotkeys";
+
+//#region src/useHotkeyRecorder.d.ts
+interface ReactHotkeyRecorder {
+  /** Whether recording is currently active */
+  isRecording: boolean;
+  /** The currently recorded hotkey (for live preview) */
+  recordedHotkey: Hotkey | null;
+  /** Start recording a new hotkey */
+  startRecording: () => void;
+  /** Stop recording (same as cancel) */
+  stopRecording: () => void;
+  /** Cancel recording without saving */
+  cancelRecording: () => void;
+}
+/**
+ * React 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>
+ *   )
+ * }
+ * ```
+ */
+declare function useHotkeyRecorder(options: HotkeyRecorderOptions): ReactHotkeyRecorder;
+//#endregion
+export { ReactHotkeyRecorder, useHotkeyRecorder };
+//# sourceMappingURL=useHotkeyRecorder.d.cts.map

package/dist/useHotkeyRecorder.d.ts

@@ -0,0 +1,57 @@
+import { Hotkey, HotkeyRecorderOptions } from "@tanstack/hotkeys";
+
+//#region src/useHotkeyRecorder.d.ts
+interface ReactHotkeyRecorder {
+  /** Whether recording is currently active */
+  isRecording: boolean;
+  /** The currently recorded hotkey (for live preview) */
+  recordedHotkey: Hotkey | null;
+  /** Start recording a new hotkey */
+  startRecording: () => void;
+  /** Stop recording (same as cancel) */
+  stopRecording: () => void;
+  /** Cancel recording without saving */
+  cancelRecording: () => void;
+}
+/**
+ * React 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>
+ *   )
+ * }
+ * ```
+ */
+declare function useHotkeyRecorder(options: HotkeyRecorderOptions): ReactHotkeyRecorder;
+//#endregion
+export { ReactHotkeyRecorder, useHotkeyRecorder };
+//# sourceMappingURL=useHotkeyRecorder.d.ts.map