@tanstack/solid-hotkeys 0.0.1

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tanstack/solid-hotkeys",
+  "version": "0.0.1",
+  "description": "SolidJS adapter for TanStack Hotkeys",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/hotkeys.git",
+    "directory": "packages/solid-hotkeys"
+  },
+  "homepage": "https://tanstack.com/hotkeys",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "solid",
+    "solidjs",
+    "tanstack",
+    "hotkeys",
+    "keyboard",
+    "shortcuts"
+  ],
+  "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/solid-store": "^0.8.0"
+  },
+  "devDependencies": {
+    "@solidjs/testing-library": "^0.8.10",
+    "@testing-library/jest-dom": "^6.9.1",
+    "solid-js": "^1.9.11",
+    "vite-plugin-solid": "^2.11.10"
+  },
+  "peerDependencies": {
+    "solid-js": ">=1.7.0"
+  }
+}

package/src/HotkeysProvider.tsx

@@ -0,0 +1,47 @@
+import { createContext, useContext } from 'solid-js'
+import type { JSX, ParentComponent } from 'solid-js'
+import type { HotkeyRecorderOptions } from '@tanstack/hotkeys'
+import type { CreateHotkeyOptions } from './createHotkey'
+import type { CreateHotkeySequenceOptions } from './createHotkeySequence'
+
+export interface HotkeysProviderOptions {
+  hotkey?: Partial<CreateHotkeyOptions>
+  hotkeyRecorder?: Partial<HotkeyRecorderOptions>
+  hotkeySequence?: Partial<CreateHotkeySequenceOptions>
+}
+
+interface HotkeysContextValue {
+  defaultOptions: HotkeysProviderOptions
+}
+
+const HotkeysContext = createContext<HotkeysContextValue | null>(null)
+
+export interface HotkeysProviderProps {
+  children: JSX.Element
+  defaultOptions?: HotkeysProviderOptions
+}
+
+const DEFAULT_OPTIONS: HotkeysProviderOptions = {}
+
+export const HotkeysProvider: ParentComponent<HotkeysProviderProps> = (
+  props,
+) => {
+  const contextValue: HotkeysContextValue = {
+    defaultOptions: props.defaultOptions ?? DEFAULT_OPTIONS,
+  }
+
+  return (
+    <HotkeysContext.Provider value={contextValue}>
+      {props.children}
+    </HotkeysContext.Provider>
+  )
+}
+
+export function useHotkeysContext() {
+  return useContext(HotkeysContext)
+}
+
+export function useDefaultHotkeysOptions() {
+  const context = useContext(HotkeysContext)
+  return context?.defaultOptions ?? {}
+}

package/src/createHeldKeyCodes.ts

@@ -0,0 +1,38 @@
+import { useStore } from '@tanstack/solid-store'
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+
+/**
+ * SolidJS primitive that returns a signal of a map from 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").
+ *
+ * This primitive uses `useStore` from `@tanstack/solid-store` to subscribe
+ * to the global KeyStateTracker.
+ *
+ * @returns Signal accessor for record mapping normalized key names to their `event.code` values
+ *
+ * @example
+ * ```tsx
+ * function KeyDebugDisplay() {
+ *   const heldKeys = createHeldKeys()
+ *   const heldCodes = createHeldKeyCodes()
+ *
+ *   return (
+ *     <div>
+ *       <For each={heldKeys()}>
+ *         {(key) => (
+ *           <kbd>
+ *             {key} <small>{heldCodes()[key]}</small>
+ *           </kbd>
+ *         )}
+ *       </For>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function createHeldKeyCodes(): () => Record<string, string> {
+  const tracker = getKeyStateTracker()
+  return useStore(tracker.store, (state) => state.heldCodes)
+}

package/src/createHeldKeys.ts

@@ -0,0 +1,29 @@
+import { useStore } from '@tanstack/solid-store'
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+
+/**
+ * SolidJS primitive that returns a signal of currently held keyboard keys.
+ *
+ * This primitive uses `useStore` from `@tanstack/solid-store` to subscribe
+ * to the global KeyStateTracker and updates whenever keys are pressed
+ * or released.
+ *
+ * @returns Signal accessor for array of currently held key names
+ *
+ * @example
+ * ```tsx
+ * function KeyDisplay() {
+ *   const heldKeys = createHeldKeys()
+ *
+ *   return (
+ *     <div>
+ *       Currently pressed: {heldKeys().join(' + ') || 'None'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function createHeldKeys(): () => Array<string> {
+  const tracker = getKeyStateTracker()
+  return useStore(tracker.store, (state) => state.heldKeys)
+}

package/src/createHotkey.ts

@@ -0,0 +1,154 @@
+import { createEffect, onCleanup } from 'solid-js'
+import {
+  detectPlatform,
+  formatHotkey,
+  getHotkeyManager,
+  rawHotkeyToParsedHotkey,
+} from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type {
+  Hotkey,
+  HotkeyCallback,
+  HotkeyOptions,
+  HotkeyRegistrationHandle,
+  RegisterableHotkey,
+} from '@tanstack/hotkeys'
+
+export interface CreateHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a direct DOM element, an accessor (for reactive targets that become
+   * available after mount), or null. Defaults to document.
+   * When using scoped targets, pass an accessor: () => ({ target: elementSignal() })
+   * so the hotkey waits for the element to be attached before registering.
+   */
+  target?: HTMLElement | Document | Window | null
+}
+
+/**
+ * SolidJS primitive 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 primitive automatically tracks reactive dependencies and updates
+ * the registration when options or the callback change.
+ *
+ * @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] = createSignal(0)
+ *
+ *   // Callback always has access to latest count value
+ *   createHotkey('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(props) {
+ *   // enabled option is reactive
+ *   createHotkey('Escape', () => {
+ *     props.onClose()
+ *   }, () => ({ enabled: props.isOpen }))
+ *
+ *   return <Show when={props.isOpen}>
+ *     <div class="modal">...</div>
+ *   </Show>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const [editorRef, setEditorRef] = createSignal<HTMLDivElement | null>(null)
+ *
+ *   // Scoped to a specific element - use accessor so hotkey waits for ref
+ *   createHotkey('Mod+S', save, () => ({ target: editorRef() }))
+ *
+ *   return <div ref={setEditorRef}>...</div>
+ * }
+ * ```
+ */
+export function createHotkey(
+  hotkey: RegisterableHotkey | (() => RegisterableHotkey),
+  callback: HotkeyCallback,
+  options: CreateHotkeyOptions | (() => CreateHotkeyOptions) = {},
+): void {
+  const defaultOptions = useDefaultHotkeysOptions()
+  const manager = getHotkeyManager()
+
+  let registration: HotkeyRegistrationHandle | null = null
+
+  createEffect(() => {
+    // Resolve reactive values
+    const resolvedHotkey = typeof hotkey === 'function' ? hotkey() : hotkey
+    const resolvedOptions = typeof options === 'function' ? options() : options
+
+    const mergedOptions = {
+      ...defaultOptions.hotkey,
+      ...resolvedOptions,
+    } as CreateHotkeyOptions
+
+    // Normalize to hotkey string
+    const platform = mergedOptions.platform ?? detectPlatform()
+    const hotkeyString: Hotkey =
+      typeof resolvedHotkey === 'string'
+        ? resolvedHotkey
+        : (formatHotkey(
+            rawHotkeyToParsedHotkey(resolvedHotkey, platform),
+          ) as Hotkey)
+
+    // Resolve target: when explicitly provided (even as null), use it and skip if null.
+    // When not provided, default to document. Matches React's ref handling.
+    const resolvedTarget =
+      'target' in mergedOptions
+        ? (mergedOptions.target ?? null)
+        : typeof document !== 'undefined'
+          ? document
+          : null
+
+    if (!resolvedTarget) {
+      return
+    }
+
+    // Unregister previous registration if it exists
+    if (registration?.isActive) {
+      registration.unregister()
+      registration = null
+    }
+
+    // Extract options without target (target is handled separately)
+    const { target: _target, ...optionsWithoutTarget } = mergedOptions
+
+    // Register the hotkey
+    registration = manager.register(hotkeyString, callback, {
+      ...optionsWithoutTarget,
+      target: resolvedTarget,
+    })
+
+    // Update callback and options on every effect run
+    if (registration.isActive) {
+      registration.callback = callback
+      registration.setOptions(optionsWithoutTarget)
+    }
+
+    // Cleanup on disposal
+    onCleanup(() => {
+      if (registration?.isActive) {
+        registration.unregister()
+        registration = null
+      }
+    })
+  })
+}

package/src/createHotkeyRecorder.ts

@@ -0,0 +1,103 @@
+import { createEffect, onCleanup } from 'solid-js'
+import { useStore } from '@tanstack/solid-store'
+import { HotkeyRecorder } from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'
+
+export interface SolidHotkeyRecorder {
+  /** 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
+}
+
+/**
+ * SolidJS primitive for recording keyboard shortcuts.
+ *
+ * This primitive 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.
+ *
+ * This primitive uses `useStore` from `@tanstack/solid-store` to subscribe
+ * to the recorder's store state (same pattern as useHotkeyRecorder in React).
+ *
+ * @param options - Configuration options for the recorder (or accessor function)
+ * @returns An object with recording state signals and control functions
+ *
+ * @example
+ * ```tsx
+ * function ShortcutSettings() {
+ *   const [shortcut, setShortcut] = createSignal<Hotkey>('Mod+S')
+ *
+ *   const recorder = createHotkeyRecorder({
+ *     onRecord: (hotkey) => {
+ *       setShortcut(hotkey)
+ *     },
+ *     onCancel: () => {
+ *       console.log('Recording cancelled')
+ *     },
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={recorder.startRecording}>
+ *         {recorder.isRecording() ? 'Recording...' : 'Edit Shortcut'}
+ *       </button>
+ *       <Show when={recorder.recordedHotkey()}>
+ *         <div>Recording: {recorder.recordedHotkey()}</div>
+ *       </Show>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function createHotkeyRecorder(
+  options: HotkeyRecorderOptions | (() => HotkeyRecorderOptions),
+): SolidHotkeyRecorder {
+  const defaultOptions = useDefaultHotkeysOptions()
+
+  const resolvedOptions = typeof options === 'function' ? options() : options
+  const mergedOptions = {
+    ...defaultOptions.hotkeyRecorder,
+    ...resolvedOptions,
+  } as HotkeyRecorderOptions
+
+  // Create recorder once synchronously (matches React's useRef pattern)
+  const recorder = new HotkeyRecorder(mergedOptions)
+
+  // Subscribe to recorder state using useStore (same pattern as useHotkeyRecorder)
+  const isRecording = useStore(recorder.store, (state) => state.isRecording)
+  const recordedHotkey = useStore(
+    recorder.store,
+    (state) => state.recordedHotkey,
+  )
+
+  // Sync options on every effect run (matches React's sync on render)
+  createEffect(() => {
+    const resolved = typeof options === 'function' ? options() : options
+    recorder.setOptions({
+      ...defaultOptions.hotkeyRecorder,
+      ...resolved,
+    } as HotkeyRecorderOptions)
+  })
+
+  // Cleanup on unmount
+  onCleanup(() => {
+    recorder.destroy()
+  })
+
+  return {
+    isRecording,
+    recordedHotkey,
+    startRecording: () => recorder.start(),
+    stopRecording: () => recorder.stop(),
+    cancelRecording: () => recorder.cancel(),
+  }
+}

package/src/createHotkeySequence.ts

@@ -0,0 +1,93 @@
+import { createEffect, onCleanup } from 'solid-js'
+import { getSequenceManager } from '@tanstack/hotkeys'
+import { useDefaultHotkeysOptions } from './HotkeysProvider'
+import type {
+  HotkeyCallback,
+  HotkeySequence,
+  SequenceOptions,
+} from '@tanstack/hotkeys'
+
+export interface CreateHotkeySequenceOptions extends Omit<
+  SequenceOptions,
+  'enabled'
+> {
+  /** Whether the sequence is enabled. Defaults to true. */
+  enabled?: boolean
+}
+
+/**
+ * SolidJS primitive for registering a keyboard shortcut sequence (Vim-style).
+ *
+ * This primitive 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 (or accessor function)
+ * @param callback - Function to call when the sequence is completed
+ * @param options - Options for the sequence behavior (or accessor function)
+ *
+ * @example
+ * ```tsx
+ * function VimEditor() {
+ *   // 'g g' to go to top
+ *   createHotkeySequence(['G', 'G'], () => {
+ *     scrollToTop()
+ *   })
+ *
+ *   // 'd d' to delete line
+ *   createHotkeySequence(['D', 'D'], () => {
+ *     deleteLine()
+ *   })
+ *
+ *   // 'd i w' to delete inner word
+ *   createHotkeySequence(['D', 'I', 'W'], () => {
+ *     deleteInnerWord()
+ *   }, { timeout: 500 })
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+export function createHotkeySequence(
+  sequence: HotkeySequence | (() => HotkeySequence),
+  callback: HotkeyCallback,
+  options:
+    | CreateHotkeySequenceOptions
+    | (() => CreateHotkeySequenceOptions) = {},
+): void {
+  const defaultOptions = useDefaultHotkeysOptions()
+
+  createEffect(() => {
+    // Resolve reactive values
+    const resolvedSequence =
+      typeof sequence === 'function' ? sequence() : sequence
+    const resolvedOptions = typeof options === 'function' ? options() : options
+
+    const mergedOptions = {
+      ...defaultOptions.hotkeySequence,
+      ...resolvedOptions,
+    } as CreateHotkeySequenceOptions
+
+    const { enabled = true, ...sequenceOptions } = mergedOptions
+
+    if (!enabled || resolvedSequence.length === 0) {
+      return
+    }
+
+    const manager = getSequenceManager()
+
+    // Build options object conditionally to avoid overwriting manager defaults with undefined
+    const registerOptions: SequenceOptions = { enabled: true }
+    if (sequenceOptions.timeout !== undefined)
+      registerOptions.timeout = sequenceOptions.timeout
+    if (sequenceOptions.platform !== undefined)
+      registerOptions.platform = sequenceOptions.platform
+
+    const unregister = manager.register(
+      resolvedSequence,
+      callback,
+      registerOptions,
+    )
+
+    onCleanup(unregister)
+  })
+}

package/src/createKeyHold.ts

@@ -0,0 +1,57 @@
+import { createMemo } from 'solid-js'
+import { useStore } from '@tanstack/solid-store'
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+import type { HeldKey } from '@tanstack/hotkeys'
+
+/**
+ * SolidJS primitive that returns whether a specific key is currently being held.
+ *
+ * This primitive uses `useStore` from `@tanstack/solid-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') - can be an accessor function
+ * @returns Signal accessor that returns true if the key is currently held down
+ *
+ * @example
+ * ```tsx
+ * function ShiftIndicator() {
+ *   const isShiftHeld = createKeyHold('Shift')
+ *
+ *   return (
+ *     <div style={{ opacity: isShiftHeld() ? 1 : 0.5 }}>
+ *       {isShiftHeld() ? 'Shift is pressed!' : 'Press Shift'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ModifierIndicators() {
+ *   const ctrl = createKeyHold('Control')
+ *   const shift = createKeyHold('Shift')
+ *   const alt = createKeyHold('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>
+ *   )
+ * }
+ * ```
+ */
+export function createKeyHold(key: HeldKey | (() => HeldKey)): () => boolean {
+  const tracker = getKeyStateTracker()
+  const heldKeysSelector = useStore(tracker.store, (state) => state.heldKeys)
+
+  return createMemo(() => {
+    const resolvedKey = typeof key === 'function' ? key() : key
+    const normalizedKey = resolvedKey.toLowerCase()
+    return heldKeysSelector().some(
+      (heldKey) => heldKey.toLowerCase() === normalizedKey,
+    )
+  })
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// Re-export everything from the core package
+export * from '@tanstack/hotkeys'
+
+// Provider
+export * from './HotkeysProvider'
+
+// SolidJS-specific primitives
+export * from './createHotkey'
+export * from './createHeldKeys'
+export * from './createHeldKeyCodes'
+export * from './createKeyHold'
+export * from './createHotkeySequence'
+export * from './createHotkeyRecorder'