@tanstack/react-hotkeys 0.0.1 → 0.0.3

package/dist/useHotkeyRecorder.js

@@ -0,0 +1,71 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { HotkeyRecorder } from "@tanstack/hotkeys";
+import { useEffect, useRef } from "react";
+import { useStore } from "@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 = {
+		...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 '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,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,65 @@
+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/useHotkeySequence.ts
+/**
+* React 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 { enabled = true, ...sequenceOptions } = {
+		...require_HotkeysProvider.useDefaultHotkeysOptions().hotkeySequence,
+		...options
+	};
+	const { timeout, platform } = sequenceOptions;
+	const callbackRef = (0, react.useRef)(callback);
+	callbackRef.current = callback;
+	(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);
+	}, [
+		enabled,
+		sequence,
+		sequence.join("|"),
+		timeout,
+		platform
+	]);
+}
+
+//#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 '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"}

package/dist/useHotkeySequence.d.cts

@@ -0,0 +1,43 @@
+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;
+}
+/**
+ * React 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,43 @@
+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;
+}
+/**
+ * React 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,64 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { getSequenceManager } from "@tanstack/hotkeys";
+import { useEffect, useRef } from "react";
+
+//#region src/useHotkeySequence.ts
+/**
+* React 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 { enabled = true, ...sequenceOptions } = {
+		...useDefaultHotkeysOptions().hotkeySequence,
+		...options
+	};
+	const { timeout, platform } = sequenceOptions;
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	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);
+	}, [
+		enabled,
+		sequence,
+		sequence.join("|"),
+		timeout,
+		platform
+	]);
+}
+
+//#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 '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"}

package/dist/useKeyHold.cjs

@@ -0,0 +1,54 @@
+const require_runtime = require('./_virtual/_rolldown/runtime.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let _tanstack_react_store = require("@tanstack/react-store");
+
+//#region src/useKeyHold.ts
+/**
+* React hook that returns whether a specific key is currently being held.
+*
+* This hook uses `useStore` from `@tanstack/react-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_react_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/react-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\nimport type { HeldKey } from '@tanstack/hotkeys'\n\n/**\n * React hook that returns whether a specific key is currently being held.\n *\n * This hook uses `useStore` from `@tanstack/react-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,4CAAgB,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
+/**
+ * React hook that returns whether a specific key is currently being held.
+ *
+ * This hook uses `useStore` from `@tanstack/react-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
+/**
+ * React hook that returns whether a specific key is currently being held.
+ *
+ * This hook uses `useStore` from `@tanstack/react-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/react-store";
+
+//#region src/useKeyHold.ts
+/**
+* React hook that returns whether a specific key is currently being held.
+*
+* This hook uses `useStore` from `@tanstack/react-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/react-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\nimport type { HeldKey } from '@tanstack/hotkeys'\n\n/**\n * React hook that returns whether a specific key is currently being held.\n *\n * This hook uses `useStore` from `@tanstack/react-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"}

package/package.json

@@ -1,10 +1,69 @@
 {
   "name": "@tanstack/react-hotkeys",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @tanstack/react-hotkeys",
+  "version": "0.0.3",
+  "description": "React adapter for TanStack Hotkeys",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/hotkeys.git",
+    "directory": "packages/react-hotkeys"
+  },
+  "homepage": "https://tanstack.com/hotkeys",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "react",
+    "tanstack",
+    "keys"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@tanstack/react-store": "^0.8.0",
+    "@tanstack/hotkeys": "0.0.2"
+  },
+  "devDependencies": {
+    "@eslint-react/eslint-plugin": "^2.12.2",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.13",
+    "@vitejs/plugin-react": "^5.1.4",
+    "eslint-plugin-react-compiler": "19.1.0-rc.2",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "peerDependencies": {
+    "react": ">=16.8",
+    "react-dom": ">=16.8"
+  },
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint": "eslint ./src",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "build": "tsdown"
+  }
+}

package/src/HotkeysProvider.tsx

@@ -0,0 +1,51 @@
+import React, { createContext, useContext, useMemo } from 'react'
+import type { ReactNode } from 'react'
+import type { HotkeyRecorderOptions } from '@tanstack/hotkeys'
+import type { UseHotkeyOptions } from './useHotkey'
+import type { UseHotkeySequenceOptions } from './useHotkeySequence'
+
+export interface HotkeysProviderOptions {
+  hotkey?: Partial<UseHotkeyOptions>
+  hotkeyRecorder?: Partial<HotkeyRecorderOptions>
+  hotkeySequence?: Partial<UseHotkeySequenceOptions>
+}
+
+interface HotkeysContextValue {
+  defaultOptions: HotkeysProviderOptions
+}
+
+const HotkeysContext = createContext<HotkeysContextValue | null>(null)
+
+export interface HotkeysProviderProps {
+  children: ReactNode
+  defaultOptions?: HotkeysProviderOptions
+}
+
+const DEFAULT_OPTIONS: HotkeysProviderOptions = {}
+
+export function HotkeysProvider({
+  children,
+  defaultOptions = DEFAULT_OPTIONS,
+}: HotkeysProviderProps) {
+  const contextValue: HotkeysContextValue = useMemo(
+    () => ({
+      defaultOptions,
+    }),
+    [defaultOptions],
+  )
+
+  return (
+    <HotkeysContext.Provider value={contextValue}>
+      {children}
+    </HotkeysContext.Provider>
+  )
+}
+
+export function useHotkeysContext() {
+  return useContext(HotkeysContext)
+}
+
+export function useDefaultHotkeysOptions() {
+  const context = useContext(HotkeysContext)
+  return context?.defaultOptions ?? {}
+}