@tanstack/preact-hotkeys 0.3.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@tanstack/preact-hotkeys",
+  "version": "0.3.0",
+  "description": "Preact adapter for TanStack Hotkeys",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/hotkeys.git",
+    "directory": "packages/preact-hotkeys"
+  },
+  "homepage": "https://tanstack.com/hotkeys",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "preact",
+    "tanstack",
+    "keys"
+  ],
+  "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"
+  },
+  "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/hotkeys": "workspace:*",
+    "@tanstack/preact-store": "^0.11.0"
+  },
+  "devDependencies": {
+    "@preact/preset-vite": "^2.10.2",
+    "@testing-library/preact": "^3.2.4",
+    "preact": "^10.27.2"
+  },
+  "peerDependencies": {
+    "preact": ">=10.0.0"
+  }
+}

package/src/HotkeysProvider.tsx

@@ -0,0 +1,52 @@
+import { createContext } from 'preact'
+import { useContext, useMemo } from 'preact/hooks'
+import type { ComponentChildren } from 'preact'
+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: ComponentChildren
+  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 ?? {}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// Re-export everything from the core package
+export * from '@tanstack/hotkeys'
+
+// provider
+export * from './HotkeysProvider'
+
+// Preact-specific exports
+export * from './useHotkey'
+export * from './useHeldKeys'
+export * from './useHeldKeyCodes'
+export * from './useKeyHold'
+export * from './useHotkeySequence'
+export * from './useHotkeyRecorder'

package/src/useHeldKeyCodes.ts

@@ -0,0 +1,33 @@
+import { useStore } from '@tanstack/preact-store'
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+
+/**
+ * Preact hook that returns a map of currently held key names to their physical `event.code` values.
+ *
+ * This is useful for debugging which physical key was pressed (e.g. distinguishing
+ * left vs right Shift via "ShiftLeft" / "ShiftRight").
+ *
+ * @returns Record mapping normalized key names to their `event.code` values
+ *
+ * @example
+ * ```tsx
+ * function KeyDebugDisplay() {
+ *   const heldKeys = useHeldKeys()
+ *   const heldCodes = useHeldKeyCodes()
+ *
+ *   return (
+ *     <div>
+ *       {heldKeys.map((key) => (
+ *         <kbd key={key}>
+ *           {key} <small>{heldCodes[key]}</small>
+ *         </kbd>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useHeldKeyCodes(): Record<string, string> {
+  const tracker = getKeyStateTracker()
+  return useStore(tracker.store, (state) => state.heldCodes)
+}

package/src/useHeldKeys.ts

@@ -0,0 +1,29 @@
+import { useStore } 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
+ * 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>
+ *   )
+ * }
+ * ```
+ */
+export function useHeldKeys(): Array<string> {
+  const tracker = getKeyStateTracker()
+  return useStore(tracker.store, (state) => state.heldKeys)
+}

package/src/useHotkey.ts

@@ -0,0 +1,192 @@
+import { useEffect, useRef } from 'preact/hooks'
+import {
+  detectPlatform,
+  formatHotkey,
+  getHotkeyManager,
+  rawHotkeyToParsedHotkey,
+} from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type { RefObject } from 'preact'
+import type {
+  Hotkey,
+  HotkeyCallback,
+  HotkeyOptions,
+  HotkeyRegistrationHandle,
+  RegisterableHotkey,
+} from '@tanstack/hotkeys'
+
+export interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a Preact ref, direct DOM element, or null.
+   * Defaults to document.
+   */
+  target?:
+    | RefObject<HTMLElement | null>
+    | HTMLElement
+    | Document
+    | Window
+    | null
+}
+
+/**
+ * Preact 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 Preact 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>
+ * }
+ * ```
+ */
+export function useHotkey(
+  hotkey: RegisterableHotkey,
+  callback: HotkeyCallback,
+  options: UseHotkeyOptions = {},
+): void {
+  const mergedOptions = {
+    ...useDefaultHotkeysOptions().hotkey,
+    ...options,
+  } as UseHotkeyOptions
+
+  const manager = getHotkeyManager()
+
+  // Stable ref for registration handle
+  const registrationRef = useRef<HotkeyRegistrationHandle | null>(null)
+
+  // Refs to capture current values for use in effect without adding dependencies
+  const callbackRef = useRef(callback)
+  const optionsRef = useRef(mergedOptions)
+  const managerRef = useRef(manager)
+
+  // Update refs on every render
+  callbackRef.current = callback
+  optionsRef.current = mergedOptions
+  managerRef.current = manager
+
+  // Track previous target and hotkey to detect changes requiring re-registration
+  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)
+  const prevHotkeyRef = useRef<string | null>(null)
+
+  // Normalize to hotkey string
+  const platform = mergedOptions.platform ?? detectPlatform()
+  const hotkeyString: Hotkey =
+    typeof hotkey === 'string'
+      ? hotkey
+      : (formatHotkey(rawHotkeyToParsedHotkey(hotkey, platform)) as Hotkey)
+
+  // Extract options without target (target is handled separately)
+  const { target: _target, ...optionsWithoutTarget } = mergedOptions
+
+  useEffect(() => {
+    // Resolve target inside the effect so refs are already attached after mount
+    const resolvedTarget = isRef(optionsRef.current.target)
+      ? optionsRef.current.target.current
+      : (optionsRef.current.target ??
+        (typeof document !== 'undefined' ? document : null))
+
+    // Skip if no valid target (SSR or ref still null)
+    if (!resolvedTarget) {
+      return
+    }
+
+    // Check if we need to re-register (target or hotkey changed)
+    const targetChanged =
+      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget
+    const hotkeyChanged =
+      prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString
+
+    // If we have an active registration and target/hotkey changed, unregister first
+    if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {
+      registrationRef.current.unregister()
+      registrationRef.current = null
+    }
+
+    // Register if needed (no active registration)
+    // Use refs to access current values without adding them to dependencies
+    if (!registrationRef.current || !registrationRef.current.isActive) {
+      registrationRef.current = managerRef.current.register(
+        hotkeyString,
+        callbackRef.current,
+        {
+          ...optionsRef.current,
+          target: resolvedTarget,
+        },
+      )
+    }
+
+    // Update tracking refs
+    prevTargetRef.current = resolvedTarget
+    prevHotkeyRef.current = hotkeyString
+
+    // Cleanup on unmount
+    return () => {
+      if (registrationRef.current?.isActive) {
+        registrationRef.current.unregister()
+        registrationRef.current = null
+      }
+    }
+  }, [hotkeyString, options.enabled])
+
+  // 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)
+  }
+}
+
+/**
+ * Type guard to check if a value is a Preact ref-like object.
+ */
+function isRef(value: unknown): value is RefObject<HTMLElement | null> {
+  return value !== null && typeof value === 'object' && 'current' in value
+}

package/src/useHotkeyRecorder.ts

@@ -0,0 +1,101 @@
+import { useEffect, useRef } from 'preact/hooks'
+import { useStore } from '@tanstack/preact-store'
+import { HotkeyRecorder } from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'
+
+export interface PreactHotkeyRecorder {
+  /** 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
+}
+
+/**
+ * Preact 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>
+ *   )
+ * }
+ * ```
+ */
+export function useHotkeyRecorder(
+  options: HotkeyRecorderOptions,
+): PreactHotkeyRecorder {
+  const mergedOptions = {
+    ...useDefaultHotkeysOptions().hotkeyRecorder,
+    ...options,
+  } as HotkeyRecorderOptions
+
+  const recorderRef = useRef<HotkeyRecorder | null>(null)
+
+  // Create recorder instance once
+  if (!recorderRef.current) {
+    recorderRef.current = new HotkeyRecorder(mergedOptions)
+  }
+
+  // Sync options on every render (same pattern as useHotkey)
+  // 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(
+    recorderRef.current.store,
+    (state) => state.isRecording,
+  )
+  const recordedHotkey = useStore(
+    recorderRef.current.store,
+    (state) => state.recordedHotkey,
+  )
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      recorderRef.current?.destroy()
+    }
+  }, [])
+
+  return {
+    isRecording,
+    recordedHotkey,
+    startRecording: () => recorderRef.current?.start(),
+    stopRecording: () => recorderRef.current?.stop(),
+    cancelRecording: () => recorderRef.current?.cancel(),
+  }
+}

package/src/useHotkeySequence.ts

@@ -0,0 +1,169 @@
+import { useEffect, useRef } from 'preact/hooks'
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type { RefObject } from 'preact'
+import type {
+  HotkeyCallback,
+  HotkeyCallbackContext,
+  HotkeySequence,
+  SequenceOptions,
+  SequenceRegistrationHandle,
+} from '@tanstack/hotkeys'
+
+export interface UseHotkeySequenceOptions extends Omit<
+  SequenceOptions,
+  'target'
+> {
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a Preact ref, direct DOM element, or null.
+   * Defaults to document.
+   */
+  target?:
+    | RefObject<HTMLElement | null>
+    | HTMLElement
+    | Document
+    | Window
+    | null
+}
+
+/**
+ * Preact 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>
+ * }
+ * ```
+ */
+export function useHotkeySequence(
+  sequence: HotkeySequence,
+  callback: HotkeyCallback,
+  options: UseHotkeySequenceOptions = {},
+): void {
+  const mergedOptions = {
+    ...useDefaultHotkeysOptions().hotkeySequence,
+    ...options,
+  } as UseHotkeySequenceOptions
+
+  const manager = getSequenceManager()
+
+  // Stable ref for registration handle
+  const registrationRef = useRef<SequenceRegistrationHandle | null>(null)
+
+  // Refs to capture current values for use in effect without adding dependencies
+  const callbackRef = useRef(callback)
+  const optionsRef = useRef(mergedOptions)
+  const managerRef = useRef(manager)
+
+  // Update refs on every render
+  callbackRef.current = callback
+  optionsRef.current = mergedOptions
+  managerRef.current = manager
+
+  // Track previous target and sequence to detect changes requiring re-registration
+  const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null)
+  const prevSequenceRef = useRef<string | null>(null)
+
+  // Normalize to hotkey sequence string (join with spaces)
+  const hotkeySequenceString = formatHotkeySequence(sequence)
+
+  // Extract options without target (target is handled separately)
+  const { target: _target, ...optionsWithoutTarget } = mergedOptions
+
+  useEffect(() => {
+    if (sequence.length === 0) {
+      return
+    }
+
+    // Resolve target inside the effect so refs are already attached after mount
+    const resolvedTarget = isRef(optionsRef.current.target)
+      ? optionsRef.current.target.current
+      : (optionsRef.current.target ??
+        (typeof document !== 'undefined' ? document : null))
+
+    // Skip if no valid target (SSR or ref still null)
+    if (!resolvedTarget) {
+      return
+    }
+
+    // Check if we need to re-register (target or sequence changed)
+    const targetChanged =
+      prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget
+    const sequenceChanged =
+      prevSequenceRef.current !== null &&
+      prevSequenceRef.current !== hotkeySequenceString
+
+    // If we have an active registration and target/sequence changed, unregister first
+    if (
+      registrationRef.current?.isActive &&
+      (targetChanged || sequenceChanged)
+    ) {
+      registrationRef.current.unregister()
+      registrationRef.current = null
+    }
+
+    // Register if needed (no active registration)
+    if (!registrationRef.current || !registrationRef.current.isActive) {
+      registrationRef.current = managerRef.current.register(
+        sequence,
+        (event, context) => callbackRef.current(event, context),
+        {
+          ...optionsRef.current,
+          target: resolvedTarget,
+        },
+      )
+    }
+
+    // Update tracking refs
+    prevTargetRef.current = resolvedTarget
+    prevSequenceRef.current = hotkeySequenceString
+
+    // Cleanup on unmount
+    return () => {
+      if (registrationRef.current?.isActive) {
+        registrationRef.current.unregister()
+        registrationRef.current = null
+      }
+    }
+  }, [hotkeySequenceString, mergedOptions.enabled, sequence])
+
+  // 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)
+  }
+}
+
+/**
+ * Type guard to check if a value is a Preact ref-like object.
+ */
+function isRef(value: unknown): value is RefObject<HTMLElement | null> {
+  return value !== null && typeof value === 'object' && 'current' in value
+}