@tanstack/angular-hotkeys 0.5.1 → 0.7.0

package/src/injectHotkey.ts

@@ -1,4 +1,4 @@
-import { effect } from '@angular/core'
+import { DestroyRef, effect, inject } from '@angular/core'
 import {
   detectPlatform,
   formatHotkey,
@@ -10,6 +10,7 @@ import type {
   Hotkey,
   HotkeyCallback,
   HotkeyOptions,
+  HotkeyRegistrationHandle,
   RegisterableHotkey,
 } from '@tanstack/hotkeys'
 
@@ -34,6 +35,8 @@ export interface InjectHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
  * Call in an injection context (e.g. constructor or field initializer).
  * Uses effect() to track reactive dependencies and update registration
  * when options or the callback change.
+ * `enabled: false` keeps the registration (visible in devtools) and only suppresses firing; the same
+ * handle is updated instead of unregistering and re-registering when identity is unchanged.
  *
  * @param hotkey - The hotkey string (e.g. 'Mod+S', 'Escape') or getter function
  * @param callback - The function to call when the hotkey is pressed
@@ -87,8 +90,22 @@ export function injectHotkey(
 ): void {
   const defaultOptions = injectDefaultHotkeysOptions()
   const manager = getHotkeyManager()
+  const destroyRef = inject(DestroyRef)
 
-  effect((onCleanup) => {
+  let registration: HotkeyRegistrationHandle | null = null
+  let lastHotkeyString: Hotkey | null = null
+  let lastTarget: HTMLElement | Document | Window | null = null
+
+  destroyRef.onDestroy(() => {
+    if (registration?.isActive) {
+      registration.unregister()
+      registration = null
+    }
+    lastHotkeyString = null
+    lastTarget = null
+  })
+
+  effect(() => {
     // Resolve reactive values
     const resolvedHotkey = typeof hotkey === 'function' ? hotkey() : hotkey
     const resolvedOptions = typeof options === 'function' ? options() : options
@@ -117,29 +134,44 @@ export function injectHotkey(
           : null
 
     if (!resolvedTarget) {
+      if (registration?.isActive) {
+        registration.unregister()
+        registration = null
+      }
+      lastHotkeyString = null
+      lastTarget = null
       return
     }
 
     // Extract options without target (target is handled separately)
     const { target: _target, ...optionsWithoutTarget } = mergedOptions
 
-    // Register the hotkey
-    const registration = manager.register(hotkeyString, callback, {
+    if (
+      registration?.isActive &&
+      lastHotkeyString === hotkeyString &&
+      lastTarget === resolvedTarget
+    ) {
+      registration.callback = callback
+      registration.setOptions(optionsWithoutTarget)
+      return
+    }
+
+    if (registration?.isActive) {
+      registration.unregister()
+      registration = null
+    }
+
+    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()
-      }
-    })
+    lastHotkeyString = hotkeyString
+    lastTarget = resolvedTarget
   })
 }

package/src/injectHotkeySequence.ts

@@ -1,18 +1,27 @@
-import { effect } from '@angular/core'
-import { getSequenceManager } from '@tanstack/hotkeys'
+import { DestroyRef, effect, inject } from '@angular/core'
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
 import { injectDefaultHotkeysOptions } from './hotkeys-provider'
 import type {
   HotkeyCallback,
   HotkeySequence,
   SequenceOptions,
+  SequenceRegistrationHandle,
 } from '@tanstack/hotkeys'
 
+type SequenceTarget = Document | HTMLElement | Window
+
 export interface InjectHotkeySequenceOptions extends Omit<
   SequenceOptions,
-  'enabled'
+  'enabled' | 'target'
 > {
   /** Whether the sequence is enabled. Defaults to true. */
   enabled?: boolean
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a direct DOM element, an accessor target, or null.
+   * Defaults to document when omitted.
+   */
+  target?: HTMLElement | Document | Window | null
 }
 
 /**
@@ -28,7 +37,8 @@ export interface InjectHotkeySequenceOptions extends Omit<
  *
  * @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)
+ * @param options - Options for the sequence behavior (or getter function). `enabled: false` still registers
+ *   the sequence (visible in devtools); only execution is suppressed.
  *
  * @example
  * ```ts
@@ -53,8 +63,23 @@ export function injectHotkeySequence(
     | (() => InjectHotkeySequenceOptions) = {},
 ): void {
   const defaultOptions = injectDefaultHotkeysOptions()
+  const manager = getSequenceManager()
+  const destroyRef = inject(DestroyRef)
+
+  let handle: SequenceRegistrationHandle | null = null
+  let lastSequenceKey: string | null = null
+  let lastTarget: SequenceTarget | null = null
 
-  effect((onCleanup) => {
+  destroyRef.onDestroy(() => {
+    if (handle?.isActive) {
+      handle.unregister()
+      handle = null
+    }
+    lastSequenceKey = null
+    lastTarget = null
+  })
+
+  effect(() => {
     // Resolve reactive values
     const resolvedSequence =
       typeof sequence === 'function' ? sequence() : sequence
@@ -67,27 +92,49 @@ export function injectHotkeySequence(
 
     const { enabled = true, ...sequenceOptions } = mergedOptions
 
-    if (!enabled || resolvedSequence.length === 0) {
+    const resolvedTarget =
+      'target' in sequenceOptions
+        ? (sequenceOptions.target ?? null)
+        : typeof document !== 'undefined'
+          ? document
+          : null
+
+    if (resolvedSequence.length === 0 || !resolvedTarget) {
+      if (handle?.isActive) {
+        handle.unregister()
+        handle = null
+      }
+      lastSequenceKey = null
+      lastTarget = null
       return
     }
 
-    const manager = getSequenceManager()
+    const sequenceKey = formatHotkeySequence(resolvedSequence)
 
-    // Pass through options; default target to document when not provided
-    const registerOptions: SequenceOptions = {
+    const registerPayload: SequenceOptions = {
       ...sequenceOptions,
-      enabled: true,
-      target:
-        sequenceOptions.target ??
-        (typeof document !== 'undefined' ? document : undefined),
+      enabled,
+      target: resolvedTarget,
     }
+    const { target: _t, ...optionsWithoutTarget } = registerPayload
 
-    const handle = manager.register(resolvedSequence, callback, registerOptions)
+    if (
+      handle?.isActive &&
+      lastSequenceKey === sequenceKey &&
+      lastTarget === resolvedTarget
+    ) {
+      handle.callback = callback
+      handle.setOptions(optionsWithoutTarget)
+      return
+    }
 
-    onCleanup(() => {
-      if (handle.isActive) {
-        handle.unregister()
-      }
-    })
+    if (handle?.isActive) {
+      handle.unregister()
+      handle = null
+    }
+
+    handle = manager.register(resolvedSequence, callback, registerPayload)
+    lastSequenceKey = sequenceKey
+    lastTarget = resolvedTarget
   })
 }

package/src/injectHotkeySequenceRecorder.ts

@@ -0,0 +1,103 @@
+import {
+  DestroyRef,
+  computed,
+  effect,
+  inject,
+  linkedSignal,
+  untracked,
+} from '@angular/core'
+import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
+import { injectDefaultHotkeysOptions } from './hotkeys-provider'
+import type { Atom, ReadonlyAtom } from '@tanstack/angular-store'
+import type { Signal } from '@angular/core'
+import type {
+  HotkeySequence,
+  HotkeySequenceRecorderOptions,
+} from '@tanstack/hotkeys'
+
+export interface AngularHotkeySequenceRecorder {
+  readonly isRecording: () => boolean
+  readonly steps: () => HotkeySequence
+  readonly recordedSequence: () => HotkeySequence | null
+  readonly startRecording: () => void
+  readonly stopRecording: () => void
+  readonly cancelRecording: () => void
+  readonly commitRecording: () => void
+}
+
+/**
+ * Angular inject-based API for recording multi-chord sequences.
+ */
+export function injectHotkeySequenceRecorder(
+  options:
+    | HotkeySequenceRecorderOptions
+    | (() => HotkeySequenceRecorderOptions),
+): AngularHotkeySequenceRecorder {
+  const defaultOptions = injectDefaultHotkeysOptions()
+  const destroyRef = inject(DestroyRef)
+
+  const recorderSignal = computed(() =>
+    untracked(() => {
+      const resolvedOptions =
+        typeof options === 'function' ? options() : options
+
+      const mergedOptions = {
+        ...defaultOptions.hotkeySequenceRecorder,
+        ...resolvedOptions,
+      } as HotkeySequenceRecorderOptions
+
+      return new HotkeySequenceRecorder(mergedOptions)
+    }),
+  )
+
+  const recorderStore = computed(() => untracked(() => recorderSignal().store))
+  const isRecording = injectLazyStore(
+    recorderStore,
+    (state) => state.isRecording,
+  )
+  const steps = injectLazyStore(recorderStore, (state) => state.steps)
+  const recordedSequence = injectLazyStore(
+    recorderStore,
+    (state) => state.recordedSequence,
+  )
+
+  effect(() => {
+    const resolved = typeof options === 'function' ? options() : options
+    recorderSignal().setOptions({
+      ...defaultOptions.hotkeySequenceRecorder,
+      ...resolved,
+    } as HotkeySequenceRecorderOptions)
+  })
+
+  destroyRef.onDestroy(() => {
+    recorderSignal().destroy()
+  })
+
+  return {
+    isRecording,
+    steps,
+    recordedSequence,
+    startRecording: () => recorderSignal().start(),
+    stopRecording: () => recorderSignal().stop(),
+    cancelRecording: () => recorderSignal().cancel(),
+    commitRecording: () => recorderSignal().commit(),
+  }
+}
+
+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/injectHotkeySequences.ts

@@ -0,0 +1,176 @@
+import { DestroyRef, effect, inject } from '@angular/core'
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
+import { injectDefaultHotkeysOptions } from './hotkeys-provider'
+import type { InjectHotkeySequenceOptions } from './injectHotkeySequence'
+import type {
+  HotkeyCallback,
+  HotkeySequence,
+  SequenceRegistrationHandle,
+} from '@tanstack/hotkeys'
+
+/**
+ * A single sequence definition for use with `injectHotkeySequences`.
+ */
+export interface InjectHotkeySequenceDefinition {
+  /** Array of hotkey strings that form the sequence */
+  sequence: HotkeySequence | (() => HotkeySequence)
+  /** The function to call when the sequence is completed */
+  callback: HotkeyCallback
+  /** Per-sequence options (merged on top of commonOptions) */
+  options?: InjectHotkeySequenceOptions | (() => InjectHotkeySequenceOptions)
+}
+
+/**
+ * Angular inject-based API for registering multiple keyboard shortcut sequences at once (Vim-style).
+ *
+ * Uses the singleton SequenceManager. Call in an injection context (e.g. constructor).
+ * Uses `effect()` to track reactive dependencies when definitions or options are getters.
+ *
+ * Options are merged in this order:
+ * provideHotkeys defaults < commonOptions < per-definition options
+ *
+ * Definitions with an empty `sequence` are skipped. Disabled sequences (`enabled: false`)
+ * remain registered so they stay visible in devtools; the core manager suppresses execution.
+ *
+ * @param sequences - Array of sequence definitions, or getter returning them
+ * @param commonOptions - Shared options for all sequences, or getter
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class VimComponent {
+ *   constructor() {
+ *     injectHotkeySequences([
+ *       { sequence: ['G', 'G'], callback: () => this.goTop() },
+ *       { sequence: ['D', 'D'], callback: () => this.deleteLine() },
+ *     ])
+ *   }
+ * }
+ * ```
+ */
+export function injectHotkeySequences(
+  sequences:
+    | Array<InjectHotkeySequenceDefinition>
+    | (() => Array<InjectHotkeySequenceDefinition>),
+  commonOptions:
+    | InjectHotkeySequenceOptions
+    | (() => InjectHotkeySequenceOptions) = {},
+): void {
+  type RegistrationRecord = {
+    handle: SequenceRegistrationHandle
+    target: Document | HTMLElement | Window
+  }
+
+  const defaultOptions = injectDefaultHotkeysOptions()
+  const manager = getSequenceManager()
+  const destroyRef = inject(DestroyRef)
+
+  const registrations = new Map<string, RegistrationRecord>()
+
+  destroyRef.onDestroy(() => {
+    for (const { handle } of registrations.values()) {
+      if (handle.isActive) {
+        handle.unregister()
+      }
+    }
+    registrations.clear()
+  })
+
+  effect(() => {
+    const resolvedSequences =
+      typeof sequences === 'function' ? sequences() : sequences
+    const resolvedCommonOptions =
+      typeof commonOptions === 'function' ? commonOptions() : commonOptions
+
+    const nextKeys = new Set<string>()
+    const prepared: Array<{
+      registrationKey: string
+      def: InjectHotkeySequenceDefinition
+      resolvedSequence: HotkeySequence
+      enabled: boolean
+      sequenceOpts: Omit<InjectHotkeySequenceOptions, 'enabled'>
+      resolvedTarget: Document | HTMLElement | Window
+    }> = []
+
+    for (let i = 0; i < resolvedSequences.length; i++) {
+      const def = resolvedSequences[i]!
+      const resolvedSequence =
+        typeof def.sequence === 'function' ? def.sequence() : def.sequence
+      const resolvedDefOptions =
+        typeof def.options === 'function' ? def.options() : (def.options ?? {})
+
+      const mergedOptions = {
+        ...defaultOptions.hotkeySequence,
+        ...resolvedCommonOptions,
+        ...resolvedDefOptions,
+      } as InjectHotkeySequenceOptions
+
+      const { enabled = true, ...sequenceOpts } = mergedOptions
+
+      if (resolvedSequence.length === 0) {
+        continue
+      }
+
+      const resolvedTarget =
+        'target' in sequenceOpts
+          ? (sequenceOpts.target ?? null)
+          : typeof document !== 'undefined'
+            ? document
+            : null
+
+      if (!resolvedTarget) {
+        continue
+      }
+
+      const registrationKey = `${i}:${formatHotkeySequence(resolvedSequence)}`
+      nextKeys.add(registrationKey)
+      prepared.push({
+        registrationKey,
+        def,
+        resolvedSequence,
+        enabled,
+        sequenceOpts,
+        resolvedTarget,
+      })
+    }
+
+    for (const [key, record] of [...registrations.entries()]) {
+      if (!nextKeys.has(key)) {
+        if (record.handle.isActive) {
+          record.handle.unregister()
+        }
+        registrations.delete(key)
+      }
+    }
+
+    for (const p of prepared) {
+      const existing = registrations.get(p.registrationKey)
+      if (existing?.handle.isActive && existing.target === p.resolvedTarget) {
+        existing.handle.callback = p.def.callback
+        const { target: _target, ...optionsWithoutTarget } = p.sequenceOpts
+        existing.handle.setOptions({
+          ...optionsWithoutTarget,
+          enabled: p.enabled,
+        })
+        continue
+      }
+
+      if (existing) {
+        if (existing.handle.isActive) {
+          existing.handle.unregister()
+        }
+        registrations.delete(p.registrationKey)
+      }
+
+      const handle = manager.register(p.resolvedSequence, p.def.callback, {
+        ...p.sequenceOpts,
+        enabled: p.enabled,
+        target: p.resolvedTarget,
+      })
+      registrations.set(p.registrationKey, {
+        handle,
+        target: p.resolvedTarget,
+      })
+    }
+  })
+}