@tanstack/angular-hotkeys 0.11.0 → 0.12.1

package/src/injectHotkeyRegistrations.ts

@@ -1,48 +0,0 @@
-import { injectSelector } from '@tanstack/angular-store'
-import {
-  getHotkeyManager,
-  getSequenceManager,
-  toHotkeyRegistrationView,
-} from '@tanstack/hotkeys'
-import type {
-  HotkeyRegistrationView,
-  SequenceRegistrationView,
-} from '@tanstack/hotkeys'
-import type { Signal } from '@angular/core'
-
-/**
- * Return type for injectHotkeyRegistrations.
- */
-export interface HotkeyRegistrationsResult {
-  /** Signal for all registered hotkeys (public view, no callbacks) */
-  hotkeys: Signal<Array<HotkeyRegistrationView>>
-  /** Signal for all registered sequences */
-  sequences: Signal<Array<SequenceRegistrationView>>
-}
-
-/**
- * Angular injectable that reactively reads all hotkey and sequence registrations
- * from the singleton managers.
- *
- * This is a standalone injectable that does NOT require the HotkeysProvider.
- * It subscribes to both HotkeyManager and SequenceManager stores and
- * triggers change detection when registrations change.
- *
- * Must be called in an injection context (constructor, factory, or `inject()`).
- *
- * @returns Object with `hotkeys` and `sequences` signals
- */
-export function injectHotkeyRegistrations(): HotkeyRegistrationsResult {
-  const hotkeyManager = getHotkeyManager()
-  const sequenceManager = getSequenceManager()
-
-  const hotkeys = injectSelector(hotkeyManager.registrations, (state) =>
-    Array.from(state.values()).map(toHotkeyRegistrationView),
-  )
-
-  const sequences = injectSelector(sequenceManager.registrations, (state) =>
-    Array.from(state.values()),
-  )
-
-  return { hotkeys, sequences }
-}

package/src/injectHotkeySequence.ts

@@ -1,140 +0,0 @@
-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' | '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
-}
-
-/**
- * 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.
- *
- * Each step may include modifiers. You can chain the same modifier across
- * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
- * Control, Alt, or Meta pressed alone) are ignored while matching—they do not
- * advance the sequence or reset progress.
- *
- * @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). `enabled: false` still registers
- *   the sequence (visible in devtools); only execution is suppressed.
- *
- * @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 })
- *     injectHotkeySequence(['Shift+R', 'Shift+T'], () => this.lastSequence.set('⇧R⇧T'))
- *   }
- * }
- * ```
- */
-export function injectHotkeySequence(
-  sequence: HotkeySequence | (() => HotkeySequence),
-  callback: HotkeyCallback,
-  options:
-    | InjectHotkeySequenceOptions
-    | (() => 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
-
-  destroyRef.onDestroy(() => {
-    if (handle?.isActive) {
-      handle.unregister()
-      handle = null
-    }
-    lastSequenceKey = null
-    lastTarget = null
-  })
-
-  effect(() => {
-    // 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
-
-    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 sequenceKey = formatHotkeySequence(resolvedSequence)
-
-    const registerPayload: SequenceOptions = {
-      ...sequenceOptions,
-      enabled,
-      target: resolvedTarget,
-    }
-    const { target: _t, ...optionsWithoutTarget } = registerPayload
-
-    if (
-      handle?.isActive &&
-      lastSequenceKey === sequenceKey &&
-      lastTarget === resolvedTarget
-    ) {
-      handle.callback = callback
-      handle.setOptions(optionsWithoutTarget)
-      return
-    }
-
-    if (handle?.isActive) {
-      handle.unregister()
-      handle = null
-    }
-
-    handle = manager.register(resolvedSequence, callback, registerPayload)
-    lastSequenceKey = sequenceKey
-    lastTarget = resolvedTarget
-  })
-}

package/src/injectHotkeySequenceRecorder.ts

@@ -1,103 +0,0 @@
-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

@@ -1,176 +0,0 @@
-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,
-      })
-    }
-  })
-}

package/src/injectHotkeys.ts

@@ -1,189 +0,0 @@
-import { DestroyRef, effect, inject } from '@angular/core'
-import {
-  detectPlatform,
-  getHotkeyManager,
-  normalizeRegisterableHotkey,
-} from '@tanstack/hotkeys'
-import { injectDefaultHotkeysOptions } from './hotkeys-provider'
-import type { InjectHotkeyOptions } from './injectHotkey'
-import type {
-  Hotkey,
-  HotkeyCallback,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-
-/**
- * A single hotkey definition for use with `injectHotkeys`.
- */
-export interface InjectHotkeyDefinition {
-  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
-  hotkey: RegisterableHotkey | (() => RegisterableHotkey)
-  /** The function to call when the hotkey is pressed */
-  callback: HotkeyCallback
-  /** Per-hotkey options (merged on top of commonOptions) */
-  options?: InjectHotkeyOptions | (() => InjectHotkeyOptions)
-}
-
-/**
- * Angular inject-based API for registering multiple keyboard hotkeys at once.
- *
- * Uses the singleton HotkeyManager for efficient event handling.
- * Accepts a dynamic array of hotkey definitions.
- *
- * Call in an injection context (e.g. constructor or field initializer).
- * Uses effect() to track reactive dependencies and update registrations
- * when options or the callback change.
- *
- * Options are merged in this order:
- * provideHotkeys defaults < commonOptions < per-definition options
- *
- * @param hotkeys - Array of hotkey definitions, or getter returning them
- * @param commonOptions - Shared options for all hotkeys, or getter
- *
- * @example
- * ```ts
- * @Component({ ... })
- * export class EditorComponent {
- *   constructor() {
- *     injectHotkeys([
- *       { hotkey: 'Mod+S', callback: () => this.save() },
- *       { hotkey: 'Mod+Z', callback: () => this.undo() },
- *       { hotkey: 'Escape', callback: () => this.close() },
- *     ])
- *   }
- * }
- * ```
- *
- * @example
- * ```ts
- * @Component({ ... })
- * export class DynamicShortcuts {
- *   shortcuts = signal([...])
- *
- *   constructor() {
- *     injectHotkeys(
- *       () => this.shortcuts().map((s) => ({
- *         hotkey: s.key,
- *         callback: s.action,
- *       })),
- *     )
- *   }
- * }
- * ```
- */
-export function injectHotkeys(
-  hotkeys:
-    | Array<InjectHotkeyDefinition>
-    | (() => Array<InjectHotkeyDefinition>),
-  commonOptions: InjectHotkeyOptions | (() => InjectHotkeyOptions) = {},
-): void {
-  type RegistrationRecord = {
-    handle: HotkeyRegistrationHandle
-    target: Document | HTMLElement | Window
-  }
-
-  const defaultOptions = injectDefaultHotkeysOptions()
-  const manager = getHotkeyManager()
-  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 resolvedHotkeys = typeof hotkeys === 'function' ? hotkeys() : hotkeys
-    const resolvedCommonOptions =
-      typeof commonOptions === 'function' ? commonOptions() : commonOptions
-
-    const nextKeys = new Set<string>()
-    const prepared: Array<{
-      registrationKey: string
-      def: InjectHotkeyDefinition
-      mergedOptions: InjectHotkeyOptions
-      hotkeyString: Hotkey
-      resolvedTarget: Document | HTMLElement | Window
-    }> = []
-
-    for (let i = 0; i < resolvedHotkeys.length; i++) {
-      const def = resolvedHotkeys[i]!
-      const resolvedHotkey =
-        typeof def.hotkey === 'function' ? def.hotkey() : def.hotkey
-      const resolvedDefOptions =
-        typeof def.options === 'function' ? def.options() : (def.options ?? {})
-
-      const mergedOptions = {
-        ...defaultOptions.hotkey,
-        ...resolvedCommonOptions,
-        ...resolvedDefOptions,
-      } as InjectHotkeyOptions
-
-      const platform = mergedOptions.platform ?? detectPlatform()
-      const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, platform)
-
-      const resolvedTarget =
-        'target' in mergedOptions
-          ? (mergedOptions.target ?? null)
-          : typeof document !== 'undefined'
-            ? document
-            : null
-
-      if (!resolvedTarget) {
-        continue
-      }
-
-      const registrationKey = `${i}:${hotkeyString}`
-      nextKeys.add(registrationKey)
-      prepared.push({
-        registrationKey,
-        def,
-        mergedOptions,
-        hotkeyString,
-        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.mergedOptions
-        existing.handle.setOptions(optionsWithoutTarget)
-        continue
-      }
-
-      if (existing) {
-        if (existing.handle.isActive) {
-          existing.handle.unregister()
-        }
-        registrations.delete(p.registrationKey)
-      }
-
-      const { target: _target, ...optionsWithoutTarget } = p.mergedOptions
-      const handle = manager.register(p.hotkeyString, p.def.callback, {
-        ...optionsWithoutTarget,
-        target: p.resolvedTarget,
-      })
-      registrations.set(p.registrationKey, {
-        handle,
-        target: p.resolvedTarget,
-      })
-    }
-  })
-}