@tanstack/react-hotkeys 0.9.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-hotkeys",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "React adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -39,18 +39,18 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/react-store": "^0.9.3",
-    "@tanstack/hotkeys": "0.7.1"
+    "@tanstack/react-store": "^0.11.0",
+    "@tanstack/hotkeys": "0.9.0"
   },
   "devDependencies": {
-    "@eslint-react/eslint-plugin": "^3.0.0",
+    "@eslint-react/eslint-plugin": "^4.2.3",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "@vitejs/plugin-react": "^6.0.1",
     "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"
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5"
   },
   "peerDependencies": {
     "react": ">=16.8",

package/src/index.ts

@@ -15,3 +15,4 @@ export * from './useHotkeySequences'
 export * from './useHotkeyRecorder'
 export * from './useHotkeyRegistrations'
 export * from './useHotkeySequenceRecorder'
+export * from './useHotkeyHint'

package/src/useHeldKeyCodes.ts

@@ -1,4 +1,4 @@
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 import { getKeyStateTracker } from '@tanstack/hotkeys'
 
 /**
@@ -29,5 +29,5 @@ import { getKeyStateTracker } from '@tanstack/hotkeys'
  */
 export function useHeldKeyCodes(): Record<string, string> {
   const tracker = getKeyStateTracker()
-  return useStore(tracker.store, (state) => state.heldCodes)
+  return useSelector(tracker.store, (state) => state.heldCodes)
 }

package/src/useHeldKeys.ts

@@ -1,10 +1,10 @@
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 import { getKeyStateTracker } from '@tanstack/hotkeys'
 
 /**
  * React hook that returns an array of currently held keyboard keys.
  *
- * This hook uses `useStore` from `@tanstack/react-store` to subscribe
+ * This hook uses `useSelector` from `@tanstack/react-store` to subscribe
  * to the global KeyStateTracker and updates whenever keys are pressed
  * or released.
  *
@@ -25,5 +25,5 @@ import { getKeyStateTracker } from '@tanstack/hotkeys'
  */
 export function useHeldKeys(): Array<string> {
   const tracker = getKeyStateTracker()
-  return useStore(tracker.store, (state) => state.heldKeys)
+  return useSelector(tracker.store, (state) => state.heldKeys)
 }

package/src/useHotkey.ts

@@ -168,7 +168,9 @@ export function useHotkey(
     // Update tracking refs
     prevTargetRef.current = resolvedTarget
     prevHotkeyRef.current = hotkeyString
+  })
 
+  useEffect(() => {
     // Cleanup on unmount
     return () => {
       if (registrationRef.current?.isActive) {
@@ -176,12 +178,13 @@ export function useHotkey(
         registrationRef.current = null
       }
     }
-  }, [hotkeyString])
-
-  // Sync callback and options on EVERY render (outside useEffect)
-  // This avoids stale closures - the callback always has access to latest state
-  if (registrationRef.current?.isActive) {
-    registrationRef.current.callback = callback
-    registrationRef.current.setOptions(optionsWithoutTarget)
-  }
+  }, [])
+
+  // Publish option changes after commit, never during render.
+  useEffect(() => {
+    if (registrationRef.current?.isActive) {
+      registrationRef.current.callback = callback
+      registrationRef.current.setOptions(optionsWithoutTarget)
+    }
+  })
 }

package/src/useHotkeyHint.ts

@@ -0,0 +1,19 @@
+import { useSelector } from '@tanstack/react-store'
+import { getKeyStateTracker, matchesHeldModifiers } from '@tanstack/hotkeys'
+import type { HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys'
+
+/**
+ * Returns a boolean indicating whether held modifiers reveal this shortcut.
+ * Only visibility changes from held-key updates cause a rerender.
+ * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
+ * every modifier. Combine with the action's enabled state before showing a badge.
+ * This helper does not register a shortcut or check whether its target is focused.
+ */
+export function useHotkeyHint(
+  hotkey: RegisterableHotkey,
+  options: HeldModifierOptions = {},
+): boolean {
+  return useSelector(getKeyStateTracker().store, (state) =>
+    matchesHeldModifiers(hotkey, state.heldKeys, options),
+  )
+}

package/src/useHotkeyRecorder.ts

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from 'react'
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 import { HotkeyRecorder } from '@tanstack/hotkeys'
 import { useDefaultHotkeysOptions } from './HotkeysProvider'
 import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'
@@ -74,12 +74,12 @@ export function useHotkeyRecorder(
   // This ensures callbacks always have access to latest values
   recorderRef.current.setOptions(mergedOptions)
 
-  // Subscribe to recorder state using useStore (same pattern as useHeldKeys)
-  const isRecording = useStore(
+  // Subscribe to recorder state using useSelector (same pattern as useHeldKeys)
+  const isRecording = useSelector(
     recorderRef.current.store,
     (state) => state.isRecording,
   )
-  const recordedHotkey = useStore(
+  const recordedHotkey = useSelector(
     recorderRef.current.store,
     (state) => state.recordedHotkey,
   )

package/src/useHotkeyRegistrations.ts

@@ -1,4 +1,4 @@
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 import {
   getHotkeyManager,
   getSequenceManager,
@@ -55,11 +55,11 @@ export function useHotkeyRegistrations(): HotkeyRegistrationsResult {
   const hotkeyManager = getHotkeyManager()
   const sequenceManager = getSequenceManager()
 
-  const hotkeys = useStore(hotkeyManager.registrations, (state) =>
+  const hotkeys = useSelector(hotkeyManager.registrations, (state) =>
     Array.from(state.values()).map(toHotkeyRegistrationView),
   )
 
-  const sequences = useStore(sequenceManager.registrations, (state) =>
+  const sequences = useSelector(sequenceManager.registrations, (state) =>
     Array.from(state.values()),
   )
 

package/src/useHotkeySequence.ts

@@ -166,7 +166,9 @@ export function useHotkeySequence(
     // Update tracking refs
     prevTargetRef.current = resolvedTarget
     prevSequenceRef.current = hotkeySequenceString
+  })
 
+  useEffect(() => {
     // Cleanup on unmount
     return () => {
       if (registrationRef.current?.isActive) {
@@ -174,14 +176,16 @@ export function useHotkeySequence(
         registrationRef.current = null
       }
     }
-  }, [hotkeySequenceString])
-
-  // 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)
-  }
+  }, [])
+
+  // Publish option changes after commit, never during render.
+  useEffect(() => {
+    if (registrationRef.current?.isActive) {
+      registrationRef.current.callback = (
+        event: KeyboardEvent,
+        context: HotkeyCallbackContext,
+      ) => callbackRef.current(event, context)
+      registrationRef.current.setOptions(optionsWithoutTarget)
+    }
+  })
 }

package/src/useHotkeySequenceRecorder.ts

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from 'react'
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
 import { useDefaultHotkeysOptions } from './HotkeysProvider'
 import type {
@@ -42,12 +42,12 @@ export function useHotkeySequenceRecorder(
 
   recorderRef.current.setOptions(mergedOptions)
 
-  const isRecording = useStore(
+  const isRecording = useSelector(
     recorderRef.current.store,
     (state) => state.isRecording,
   )
-  const steps = useStore(recorderRef.current.store, (state) => state.steps)
-  const recordedSequence = useStore(
+  const steps = useSelector(recorderRef.current.store, (state) => state.steps)
+  const recordedSequence = useSelector(
     recorderRef.current.store,
     (state) => state.recordedSequence,
   )

package/src/useHotkeySequences.ts

@@ -154,6 +154,10 @@ export function useHotkeySequences(
 
       const existing = prevRegistrations.get(registrationKey)
       if (existing?.handle.isActive && existing.target === resolvedTarget) {
+        // Publish callback/options only after commit, never during render.
+        existing.handle.callback = def.callback
+        const { target: _target, ...optionsWithoutTarget } = mergedOptions
+        existing.handle.setOptions(optionsWithoutTarget)
         nextRegistrations.set(registrationKey, existing)
         continue
       }
@@ -185,22 +189,4 @@ export function useHotkeySequences(
       registrationsRef.current = new Map()
     }
   }, [])
-
-  for (let i = 0; i < definitions.length; i++) {
-    const def = definitions[i]!
-    const seqStr = sequenceStrings[i]!
-    const registrationKey = `${i}:${seqStr}`
-    const handle = registrationsRef.current.get(registrationKey)?.handle
-
-    if (handle?.isActive && def.sequence.length > 0) {
-      handle.callback = def.callback
-      const mergedOptions = {
-        ...defaultOptions,
-        ...commonOptions,
-        ...def.options,
-      } as UseHotkeySequenceOptions
-      const { target: _target, ...optionsWithoutTarget } = mergedOptions
-      handle.setOptions(optionsWithoutTarget)
-    }
-  }
 }

package/src/useHotkeys.ts

@@ -155,6 +155,10 @@ export function useHotkeys(
 
       const existing = prevRegistrations.get(registrationKey)
       if (existing?.handle.isActive && existing.target === resolvedTarget) {
+        // Publish callback/options only after commit, never during render.
+        existing.handle.callback = def.callback
+        const { target: _target, ...optionsWithoutTarget } = mergedOptions
+        existing.handle.setOptions(optionsWithoutTarget)
         nextRegistrations.set(registrationKey, existing)
         continue
       }
@@ -186,23 +190,4 @@ export function useHotkeys(
       registrationsRef.current = new Map()
     }
   }, [])
-
-  // Sync callbacks and options on EVERY render (outside useEffect)
-  for (let i = 0; i < hotkeys.length; i++) {
-    const def = hotkeys[i]!
-    const hotkeyStr = hotkeyStrings[i]!
-    const registrationKey = `${i}:${hotkeyStr}`
-    const handle = registrationsRef.current.get(registrationKey)?.handle
-
-    if (handle?.isActive) {
-      handle.callback = def.callback
-      const mergedOptions = {
-        ...defaultOptions,
-        ...commonOptions,
-        ...def.options,
-      } as UseHotkeyOptions
-      const { target: _target, ...optionsWithoutTarget } = mergedOptions
-      handle.setOptions(optionsWithoutTarget)
-    }
-  }
 }

package/src/useKeyHold.ts

@@ -1,11 +1,11 @@
-import { useStore } from '@tanstack/react-store'
+import { useSelector } from '@tanstack/react-store'
 import { getKeyStateTracker } from '@tanstack/hotkeys'
 import type { IndividualKey } from '@tanstack/hotkeys'
 
 /**
  * React hook that returns whether a specific key is currently being held.
  *
- * This hook uses `useStore` from `@tanstack/react-store` to subscribe
+ * This hook uses `useSelector` from `@tanstack/react-store` to subscribe
  * to the global KeyStateTracker and uses a selector to determine if
  * the specified key is held.
  *
@@ -46,7 +46,7 @@ export function useKeyHold(key: IndividualKey): boolean {
   const tracker = getKeyStateTracker()
   const normalizedKey = key.toLowerCase()
 
-  return useStore(tracker.store, (state) =>
+  return useSelector(tracker.store, (state) =>
     state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey),
   )
 }