@tanstack/angular-hotkeys 0.3.3

package/src/injectHotkeyRecorder.ts

@@ -0,0 +1,128 @@
+import {
+  DestroyRef,
+  computed,
+  effect,
+  inject,
+  linkedSignal,
+  untracked,
+} from '@angular/core'
+import { HotkeyRecorder } from '@tanstack/hotkeys'
+import { injectDefaultHotkeysOptions } from './hotkeys-provider'
+import type { Atom, ReadonlyAtom } from '@tanstack/angular-store'
+import type { Signal } from '@angular/core'
+import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'
+
+export interface AngularHotkeyRecorder {
+  /** Whether recording is currently active */
+  readonly isRecording: () => boolean
+  /** The currently recorded hotkey (for live preview) */
+  readonly recordedHotkey: () => Hotkey | null
+  /** Start recording a new hotkey */
+  readonly startRecording: () => void
+  /** Stop recording (same as cancel) */
+  readonly stopRecording: () => void
+  /** Cancel recording without saving */
+  readonly cancelRecording: () => void
+}
+
+/**
+ * Angular inject-based API for recording keyboard shortcuts.
+ *
+ * Thin wrapper around the framework-agnostic HotkeyRecorder class: captures
+ * keyboard events, converts them to hotkey strings, and handles Escape to
+ * cancel or Backspace/Delete to clear.
+ *
+ * @param options - Configuration options for the recorder (or getter)
+ * @returns Object with recording state signals and control functions
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class ShortcutSettingsComponent {
+ *   shortcut = signal<Hotkey>('Mod+S')
+ *   recorder = injectHotkeyRecorder({
+ *     onRecord: (hotkey) => this.shortcut.set(hotkey),
+ *     onCancel: () => console.log('Recording cancelled'),
+ *   })
+ *
+ *   constructor() {
+ *     injectHotkey(
+ *       () => this.shortcut(),
+ *       () => this.handleSave(),
+ *       () => ({ enabled: !this.recorder.isRecording() }),
+ *     )
+ *   }
+ * }
+ * ```
+ */
+export function injectHotkeyRecorder(
+  options: HotkeyRecorderOptions | (() => HotkeyRecorderOptions),
+): AngularHotkeyRecorder {
+  const defaultOptions = injectDefaultHotkeysOptions()
+  const destroyRef = inject(DestroyRef)
+
+  // Stable signal to lazy initialize the recorder
+  const recorderSignal = computed(() =>
+    untracked(() => {
+      const resolvedOptions =
+        typeof options === 'function' ? options() : options
+
+      const mergedOptions = {
+        ...defaultOptions.hotkeyRecorder,
+        ...resolvedOptions,
+      } as HotkeyRecorderOptions
+
+      return new HotkeyRecorder(mergedOptions)
+    }),
+  )
+
+  // Subscribe to recorder state
+  const recorderStore = computed(() => untracked(() => recorderSignal().store))
+  const isRecording = injectLazyStore(
+    recorderStore,
+    (state) => state.isRecording,
+  )
+  const recordedHotkey = injectLazyStore(
+    recorderStore,
+    (state) => state.recordedHotkey,
+  )
+
+  // Sync options on every effect run (matches React's sync on render)
+  effect(() => {
+    const resolved = typeof options === 'function' ? options() : options
+    recorderSignal().setOptions({
+      ...defaultOptions.hotkeyRecorder,
+      ...resolved,
+    } as HotkeyRecorderOptions)
+  })
+
+  destroyRef.onDestroy(() => {
+    recorderSignal().destroy()
+  })
+
+  return {
+    isRecording,
+    recordedHotkey,
+    startRecording: () => recorderSignal().start(),
+    stopRecording: () => recorderSignal().stop(),
+    cancelRecording: () => recorderSignal().cancel(),
+  }
+}
+
+function injectLazyStore<TState, TSelected = NoInfer<TState>>(
+  storeSignal: Signal<Atom<TState> | ReadonlyAtom<TState>>,
+  selector: (state: NoInfer<TState>) => TSelected,
+): Signal<TSelected> {
+  const slice = linkedSignal(() => selector(storeSignal().get()))
+
+  effect((onCleanup) => {
+    const currentStore = storeSignal()
+    slice.set(selector(currentStore.get()))
+    const { unsubscribe } = currentStore.subscribe((s) => {
+      slice.set(selector(s))
+    })
+    onCleanup(() => unsubscribe())
+  })
+
+  return slice.asReadonly()
+}

package/src/injectHotkeySequence.ts

@@ -0,0 +1,87 @@
+import { effect } from '@angular/core'
+import { getSequenceManager } from '@tanstack/hotkeys'
+import { injectDefaultHotkeysOptions } from './hotkeys-provider'
+import type {
+  HotkeyCallback,
+  HotkeySequence,
+  SequenceOptions,
+} from '@tanstack/hotkeys'
+
+export interface InjectHotkeySequenceOptions extends Omit<
+  SequenceOptions,
+  'enabled'
+> {
+  /** Whether the sequence is enabled. Defaults to true. */
+  enabled?: boolean
+}
+
+/**
+ * Angular inject-based API for registering a keyboard shortcut sequence (Vim-style).
+ *
+ * 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 getter function)
+ * @param callback - Function to call when the sequence is completed
+ * @param options - Options for the sequence behavior (or getter function)
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class VimEditorComponent {
+ *   lastSequence = signal<string | null>(null)
+ *
+ *   constructor() {
+ *     injectHotkeySequence(['G', 'G'], () => this.lastSequence.set('gg → Go to top'))
+ *     injectHotkeySequence(['D', 'D'], () => this.lastSequence.set('dd → Delete line'))
+ *     injectHotkeySequence(['C', 'I', 'W'], () => this.lastSequence.set('ciw'), { timeout: 500 })
+ *   }
+ * }
+ * ```
+ */
+export function injectHotkeySequence(
+  sequence: HotkeySequence | (() => HotkeySequence),
+  callback: HotkeyCallback,
+  options:
+    | InjectHotkeySequenceOptions
+    | (() => InjectHotkeySequenceOptions) = {},
+): void {
+  const defaultOptions = injectDefaultHotkeysOptions()
+
+  effect((onCleanup) => {
+    // Resolve reactive values
+    const resolvedSequence =
+      typeof sequence === 'function' ? sequence() : sequence
+    const resolvedOptions = typeof options === 'function' ? options() : options
+
+    const mergedOptions = {
+      ...defaultOptions.hotkeySequence,
+      ...resolvedOptions,
+    } as InjectHotkeySequenceOptions
+
+    const { enabled = true, ...sequenceOptions } = mergedOptions
+
+    if (!enabled || resolvedSequence.length === 0) {
+      return
+    }
+
+    const manager = getSequenceManager()
+
+    // Pass through options; default target to document when not provided
+    const registerOptions: SequenceOptions = {
+      ...sequenceOptions,
+      enabled: true,
+      target:
+        sequenceOptions.target ??
+        (typeof document !== 'undefined' ? document : undefined),
+    }
+
+    const handle = manager.register(resolvedSequence, callback, registerOptions)
+
+    onCleanup(() => {
+      if (handle.isActive) {
+        handle.unregister()
+      }
+    })
+  })
+}

package/src/injectKeyHold.ts

@@ -0,0 +1,52 @@
+import { computed } from '@angular/core'
+import { injectStore } from '@tanstack/angular-store'
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+import type { HeldKey } from '@tanstack/hotkeys'
+import type { Signal } from '@angular/core'
+
+/**
+ * Angular inject-based API that returns a signal that is true when the given key is held.
+ *
+ * Subscribes to the global KeyStateTracker and uses a computed to determine
+ * if the specified key is held.
+ *
+ * @param key - The key to check (e.g. 'Shift', 'Control', 'Space') - can be a getter function
+ * @returns Signal that returns true if the key is currently held down
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `{{ isShiftHeld() ? 'Shift is pressed!' : 'Press Shift' }}`,
+ * })
+ * export class ShiftIndicatorComponent {
+ *   isShiftHeld = injectKeyHold('Shift')
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `
+ *     <span [style.opacity]="ctrl() ? 1 : 0.3">Ctrl</span>
+ *     <span [style.opacity]="shift() ? 1 : 0.3">Shift</span>
+ *   `,
+ * })
+ * export class ModifierIndicatorsComponent {
+ *   ctrl = injectKeyHold('Control')
+ *   shift = injectKeyHold('Shift')
+ * }
+ * ```
+ */
+export function injectKeyHold(key: HeldKey | (() => HeldKey)): Signal<boolean> {
+  const tracker = getKeyStateTracker()
+  const heldKeysSelector = injectStore(tracker.store, (state) => state.heldKeys)
+
+  return computed(() => {
+    const resolvedKey = typeof key === 'function' ? key() : key
+    const normalizedKey = resolvedKey.toLowerCase()
+
+    return heldKeysSelector().some(
+      (heldKey) => heldKey.toLowerCase() === normalizedKey,
+    )
+  })
+}