@tanstack/preact-hotkeys 0.9.1 → 0.11.0

package/src/useHeldKeyCodes.ts

@@ -1,4 +1,4 @@
-import { useStore } from '@tanstack/preact-store'
+import { useSelector } from '@tanstack/preact-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/preact-store'
+import { useSelector } from '@tanstack/preact-store'
 import { getKeyStateTracker } from '@tanstack/hotkeys'
 
 /**
  * Preact hook that returns an array of currently held keyboard keys.
  *
- * This hook uses `useStore` from `@tanstack/preact-store` to subscribe
+ * This hook uses `useSelector` from `@tanstack/preact-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

@@ -169,7 +169,9 @@ export function useHotkey(
     // Update tracking refs
     prevTargetRef.current = resolvedTarget
     prevHotkeyRef.current = hotkeyString
+  })
 
+  useEffect(() => {
     // Cleanup on unmount
     return () => {
       if (registrationRef.current?.isActive) {
@@ -177,12 +179,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/preact-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 'preact/hooks'
-import { useStore } from '@tanstack/preact-store'
+import { useSelector } from '@tanstack/preact-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,5 @@
-import { useStore } from '@tanstack/preact-store'
+import { useMemo } from 'preact/hooks'
+import { useSelector } from '@tanstack/preact-store'
 import {
   getHotkeyManager,
   getSequenceManager,
@@ -33,12 +34,17 @@ export function useHotkeyRegistrations(): HotkeyRegistrationsResult {
   const hotkeyManager = getHotkeyManager()
   const sequenceManager = getSequenceManager()
 
-  const hotkeys = useStore(hotkeyManager.registrations, (state) =>
-    Array.from(state.values()).map(toHotkeyRegistrationView),
+  // Select stable store snapshots before deriving arrays; fresh selector arrays
+  // make Preact's external-store subscription render continuously.
+  const hotkeyState = useSelector(hotkeyManager.registrations)
+  const sequenceState = useSelector(sequenceManager.registrations)
+  const hotkeys = useMemo(
+    () => Array.from(hotkeyState.values()).map(toHotkeyRegistrationView),
+    [hotkeyState],
   )
-
-  const sequences = useStore(sequenceManager.registrations, (state) =>
-    Array.from(state.values()),
+  const sequences = useMemo(
+    () => Array.from(sequenceState.values()),
+    [sequenceState],
   )
 
   return { hotkeys, sequences }

package/src/useHotkeySequence.ts

@@ -167,7 +167,9 @@ export function useHotkeySequence(
     // Update tracking refs
     prevTargetRef.current = resolvedTarget
     prevSequenceRef.current = hotkeySequenceString
+  })
 
+  useEffect(() => {
     // Cleanup on unmount
     return () => {
       if (registrationRef.current?.isActive) {
@@ -175,14 +177,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 'preact/hooks'
-import { useStore } from '@tanstack/preact-store'
+import { useSelector } from '@tanstack/preact-store'
 import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
 import { useDefaultHotkeysOptions } from './HotkeysProvider'
 import type {
@@ -36,12 +36,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,22 +190,4 @@ export function useHotkeys(
       registrationsRef.current = new Map()
     }
   }, [])
-
-  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/preact-store'
+import { useSelector } from '@tanstack/preact-store'
 import { getKeyStateTracker } from '@tanstack/hotkeys'
 import type { IndividualKey } from '@tanstack/hotkeys'
 
 /**
  * Preact hook that returns whether a specific key is currently being held.
  *
- * This hook uses `useStore` from `@tanstack/preact-store` to subscribe
+ * This hook uses `useSelector` from `@tanstack/preact-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),
   )
 }