@tanstack/vue-hotkeys 0.11.0 → 0.12.1

package/src/useHotkey.ts

@@ -1,213 +0,0 @@
-import { onUnmounted, unref, watch } from 'vue'
-import {
-  detectPlatform,
-  getHotkeyManager,
-  normalizeRegisterableHotkey,
-} from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProviderContext'
-import type {
-  Hotkey,
-  HotkeyCallback,
-  HotkeyOptions,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-import type { MaybeRefOrGetter } from 'vue'
-
-export interface UseHotkeyOptions extends Omit<
-  HotkeyOptions,
-  'enabled' | 'target'
-> {
-  /**
-   * Whether the hotkey is active.
-   * Can be a Ref, a getter function, or a boolean value.
-   * Defaults to true.
-   */
-  enabled?: MaybeRefOrGetter<boolean>
-  /**
-   * The DOM element to attach the event listener to.
-   * Can be a Ref, a getter function, direct DOM element, or null.
-   * Defaults to document.
-   */
-  target?: MaybeRefOrGetter<HTMLElement | Document | Window | null>
-}
-
-/**
- * Vue composable 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 composable 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
- * ```vue
- * <script setup>
- * import { ref } from 'vue'
- * import { useHotkey } from '@tanstack/vue-hotkeys'
- *
- * const count = ref(0)
- *
- * // Callback always has access to latest count value
- * useHotkey('Mod+S', (event, { hotkey }) => {
- *   console.log(`Save triggered, count is ${count.value}`)
- *   handleSave()
- * })
- * </script>
- * ```
- *
- * @example
- * ```vue
- * <script setup>
- * import { ref } from 'vue'
- * import { useHotkey } from '@tanstack/vue-hotkeys'
- *
- * const isOpen = ref(false)
- *
- * // enabled option is reactive
- * useHotkey('Escape', () => {
- *   isOpen.value = false
- * }, { enabled: isOpen })
- * </script>
- * ```
- *
- * @example
- * ```vue
- * <script setup>
- * import { ref } from 'vue'
- * import { useHotkey } from '@tanstack/vue-hotkeys'
- *
- * const editorRef = ref<HTMLDivElement | null>(null)
- *
- * // Scoped to a specific element
- * useHotkey('Mod+S', () => {
- *   save()
- * }, { target: editorRef })
- * </script>
- *
- * <template>
- *   <div ref="editorRef">...</div>
- * </template>
- * ```
- */
-export function useHotkey(
-  hotkey: MaybeRefOrGetter<RegisterableHotkey>,
-  callback: HotkeyCallback,
-  options: MaybeRefOrGetter<UseHotkeyOptions> = {},
-): void {
-  const defaultOptions = useDefaultHotkeysOptions()
-  const manager = getHotkeyManager()
-
-  let registration: HotkeyRegistrationHandle | null = null
-  let lastHotkeyString: Hotkey | null = null
-  let lastTarget: HTMLElement | Document | Window | null = null
-
-  // Watch for changes to reactive dependencies
-  const stopWatcher = watch(
-    () => {
-      const resolvedHotkey = resolveMaybeRefOrGetter(hotkey)
-      const resolvedOptions = resolveMaybeRefOrGetter(options)
-      const mergedOptions = {
-        ...defaultOptions.hotkey,
-        ...resolvedOptions,
-      } as UseHotkeyOptions
-      const resolvedEnabled =
-        mergedOptions.enabled === undefined
-          ? undefined
-          : resolveMaybeRefOrGetter(mergedOptions.enabled)
-      const resolvedTarget =
-        mergedOptions.target === undefined
-          ? undefined
-          : resolveMaybeRefOrGetter(mergedOptions.target)
-
-      return {
-        resolvedHotkey,
-        mergedOptions,
-        resolvedEnabled,
-        resolvedTarget,
-      }
-    },
-    ({ resolvedHotkey, mergedOptions, resolvedEnabled, resolvedTarget }) => {
-      // Normalize to hotkey string
-      const platform = mergedOptions.platform ?? detectPlatform()
-      const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, platform)
-
-      // Resolve target
-      const finalTarget =
-        resolvedTarget === undefined
-          ? typeof document !== 'undefined'
-            ? document
-            : null
-          : resolvedTarget
-
-      if (!finalTarget) {
-        if (registration?.isActive) {
-          registration.unregister()
-          registration = null
-        }
-        lastHotkeyString = null
-        lastTarget = null
-        return
-      }
-
-      // Extract options without target (target is handled separately)
-      const {
-        target: _target,
-        enabled: _enabled,
-        ...restOptions
-      } = mergedOptions
-      const optionsWithoutTarget = {
-        ...restOptions,
-        ...(resolvedEnabled === undefined ? {} : { enabled: resolvedEnabled }),
-      }
-
-      if (
-        registration?.isActive &&
-        lastHotkeyString === hotkeyString &&
-        lastTarget === finalTarget
-      ) {
-        registration.callback = callback
-        registration.setOptions(optionsWithoutTarget)
-        return
-      }
-
-      if (registration?.isActive) {
-        registration.unregister()
-        registration = null
-      }
-
-      registration = manager.register(hotkeyString, callback, {
-        ...optionsWithoutTarget,
-        target: finalTarget,
-      })
-
-      if (registration.isActive) {
-        registration.callback = callback
-        registration.setOptions(optionsWithoutTarget)
-      }
-
-      lastHotkeyString = hotkeyString
-      lastTarget = finalTarget
-    },
-    { immediate: true },
-  )
-
-  // Cleanup on unmount
-  onUnmounted(() => {
-    stopWatcher()
-    if (registration?.isActive) {
-      registration.unregister()
-      registration = null
-    }
-  })
-}
-
-function resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {
-  return typeof value === 'function' ? (value as () => T)() : unref(value)
-}

package/src/useHotkeyHint.ts

@@ -1,25 +0,0 @@
-import { computed, toValue } from 'vue'
-import { useSelector } from '@tanstack/vue-store'
-import { getKeyStateTracker, matchesHeldModifiers } from '@tanstack/hotkeys'
-import type { ComputedRef, MaybeRefOrGetter } from 'vue'
-import type { HeldModifierOptions, RegisterableHotkey } from '@tanstack/hotkeys'
-
-/**
- * Returns a computed ref indicating whether held modifiers reveal this shortcut.
- * Pass refs or getters to track changing bindings and options.
- * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact` requires
- * every modifier. Combine with the action's enabled state before showing a badge.
- * This helper does not register a shortcut or check whether its target is focused.
- */
-export function useHotkeyHint(
-  hotkey: MaybeRefOrGetter<RegisterableHotkey>,
-  options: MaybeRefOrGetter<HeldModifierOptions> = {},
-): ComputedRef<boolean> {
-  const held = useSelector(
-    getKeyStateTracker().store,
-    (state) => state.heldKeys,
-  )
-  return computed(() =>
-    matchesHeldModifiers(toValue(hotkey), held.value, toValue(options)),
-  )
-}

package/src/useHotkeyRecorder.ts

@@ -1,112 +0,0 @@
-import { onUnmounted, unref, watch } from 'vue'
-import { useSelector } from '@tanstack/vue-store'
-import { HotkeyRecorder } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProviderContext'
-import type { MaybeRefOrGetter, Ref } from 'vue'
-import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'
-
-export interface VueHotkeyRecorder {
-  /** Whether recording is currently active */
-  isRecording: Ref<boolean>
-  /** The currently recorded hotkey (for live preview) */
-  recordedHotkey: Ref<Hotkey | null>
-  /** Start recording a new hotkey */
-  startRecording: () => void
-  /** Stop recording (same as cancel) */
-  stopRecording: () => void
-  /** Cancel recording without saving */
-  cancelRecording: () => void
-}
-
-/**
- * Vue composable for recording keyboard shortcuts.
- *
- * This composable 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
- * ```vue
- * <script setup>
- * import { ref } from 'vue'
- * import { useHotkeyRecorder } from '@tanstack/vue-hotkeys'
- *
- * const shortcut = ref<Hotkey>('Mod+S')
- *
- * const recorder = useHotkeyRecorder({
- *   onRecord: (hotkey) => {
- *     shortcut.value = hotkey
- *   },
- *   onCancel: () => {
- *     console.log('Recording cancelled')
- *   },
- * })
- * </script>
- *
- * <template>
- *   <div>
- *     <button @click="recorder.startRecording()">
- *       {{ recorder.isRecording ? 'Recording...' : 'Edit Shortcut' }}
- *     </button>
- *     <div v-if="recorder.recordedHotkey">
- *       Recording: {{ recorder.recordedHotkey }}
- *     </div>
- *   </div>
- * </template>
- * ```
- */
-export function useHotkeyRecorder(
-  options: MaybeRefOrGetter<HotkeyRecorderOptions>,
-): VueHotkeyRecorder {
-  const defaultOptions = useDefaultHotkeysOptions()
-  const recorder = new HotkeyRecorder(
-    resolveRecorderOptions(options, defaultOptions),
-  )
-
-  // Subscribe to recorder state using useSelector
-  const isRecording = useSelector(recorder.store, (state) => state.isRecording)
-  const recordedHotkey = useSelector(
-    recorder.store,
-    (state) => state.recordedHotkey,
-  )
-
-  const stopWatcher = watch(
-    () => resolveRecorderOptions(options, defaultOptions),
-    (resolvedOptions) => {
-      recorder.setOptions(resolvedOptions)
-    },
-    { immediate: true },
-  )
-
-  // Cleanup on unmount
-  onUnmounted(() => {
-    stopWatcher()
-    recorder.destroy()
-  })
-
-  return {
-    isRecording: isRecording as Ref<boolean>,
-    recordedHotkey: recordedHotkey as Ref<Hotkey | null>,
-    startRecording: () => recorder.start(),
-    stopRecording: () => recorder.stop(),
-    cancelRecording: () => recorder.cancel(),
-  }
-}
-
-function resolveRecorderOptions(
-  options: MaybeRefOrGetter<HotkeyRecorderOptions>,
-  defaultOptions: ReturnType<typeof useDefaultHotkeysOptions>,
-): HotkeyRecorderOptions {
-  return {
-    ...defaultOptions.hotkeyRecorder,
-    ...resolveMaybeRefOrGetter(options),
-  } as HotkeyRecorderOptions
-}
-
-function resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {
-  return typeof value === 'function' ? (value as () => T)() : unref(value)
-}

package/src/useHotkeyRegistrations.ts

@@ -1,46 +0,0 @@
-import { useSelector } from '@tanstack/vue-store'
-import {
-  getHotkeyManager,
-  getSequenceManager,
-  toHotkeyRegistrationView,
-} from '@tanstack/hotkeys'
-import type {
-  HotkeyRegistrationView,
-  SequenceRegistrationView,
-} from '@tanstack/hotkeys'
-import type { Ref } from 'vue'
-
-/**
- * Return type for useHotkeyRegistrations.
- */
-export interface HotkeyRegistrationsResult {
-  /** All registered hotkeys (public view, no callbacks) */
-  hotkeys: Ref<Array<HotkeyRegistrationView>>
-  /** All registered sequences */
-  sequences: Ref<Array<SequenceRegistrationView>>
-}
-
-/**
- * Vue composable that reactively reads all hotkey and sequence registrations
- * from the singleton managers.
- *
- * This is a standalone composable that does NOT require the HotkeysProvider.
- * It subscribes to both HotkeyManager and SequenceManager stores and
- * triggers reactivity when registrations change.
- *
- * @returns Object with `hotkeys` and `sequences` refs
- */
-export function useHotkeyRegistrations(): HotkeyRegistrationsResult {
-  const hotkeyManager = getHotkeyManager()
-  const sequenceManager = getSequenceManager()
-
-  const hotkeys = useSelector(hotkeyManager.registrations, (state) =>
-    Array.from(state.values()).map(toHotkeyRegistrationView),
-  )
-
-  const sequences = useSelector(sequenceManager.registrations, (state) =>
-    Array.from(state.values()),
-  )
-
-  return { hotkeys, sequences }
-}

package/src/useHotkeySequence.ts

@@ -1,187 +0,0 @@
-import { onUnmounted, unref, watch } from 'vue'
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProviderContext'
-import type { MaybeRefOrGetter } from 'vue'
-import type {
-  HotkeyCallback,
-  HotkeySequence,
-  SequenceOptions,
-  SequenceRegistrationHandle,
-} from '@tanstack/hotkeys'
-
-export interface UseHotkeySequenceOptions extends Omit<
-  SequenceOptions,
-  'enabled' | 'target'
-> {
-  /**
-   * Whether the sequence is active.
-   * Can be a Ref, a getter function, or a boolean value.
-   * Defaults to true.
-   */
-  enabled?: MaybeRefOrGetter<boolean>
-  /**
-   * The DOM element to attach the event listener to.
-   * Can be a Ref, a getter function, direct DOM element, or null.
-   * Defaults to document.
-   */
-  target?: MaybeRefOrGetter<HTMLElement | Document | Window | null>
-}
-
-/**
- * Vue composable for registering a keyboard shortcut sequence (Vim-style).
- *
- * This composable 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
- * @param callback - Function to call when the sequence is completed
- * @param options - Options for the sequence behavior
- *
- * @example
- * ```vue
- * <script setup>
- * import { useHotkeySequence } from '@tanstack/vue-hotkeys'
- *
- * // '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 })
- *
- * // Same modifier on consecutive steps (bare Shift between chords is ignored)
- * useHotkeySequence(['Shift+R', 'Shift+T'], () => {
- *   nextAction()
- * })
- * </script>
- *
- * <template>
- *   <div>...</div>
- * </template>
- * ```
- */
-export function useHotkeySequence(
-  sequence: MaybeRefOrGetter<HotkeySequence>,
-  callback: HotkeyCallback,
-  options: MaybeRefOrGetter<UseHotkeySequenceOptions> = {},
-): void {
-  const defaultOptions = useDefaultHotkeysOptions()
-  const manager = getSequenceManager()
-
-  let registration: SequenceRegistrationHandle | null = null
-  let lastSequenceKey: string | null = null
-  let lastTarget: HTMLElement | Document | Window | null = null
-
-  // Watch for changes to reactive dependencies
-  const stopWatcher = watch(
-    () => {
-      const resolvedSequence = resolveMaybeRefOrGetter(sequence)
-      const resolvedOptions = resolveMaybeRefOrGetter(options)
-      const mergedOptions = {
-        ...defaultOptions.hotkeySequence,
-        ...resolvedOptions,
-      } as UseHotkeySequenceOptions
-      const resolvedEnabled =
-        mergedOptions.enabled === undefined
-          ? undefined
-          : resolveMaybeRefOrGetter(mergedOptions.enabled)
-      const resolvedTarget =
-        mergedOptions.target === undefined
-          ? undefined
-          : resolveMaybeRefOrGetter(mergedOptions.target)
-
-      return {
-        resolvedSequence,
-        mergedOptions,
-        resolvedEnabled,
-        resolvedTarget,
-      }
-    },
-    ({ resolvedSequence, mergedOptions, resolvedEnabled, resolvedTarget }) => {
-      const finalTarget =
-        resolvedTarget === undefined
-          ? typeof document !== 'undefined'
-            ? document
-            : null
-          : resolvedTarget
-
-      if (resolvedSequence.length === 0 || !finalTarget) {
-        if (registration?.isActive) {
-          registration.unregister()
-          registration = null
-        }
-        lastSequenceKey = null
-        lastTarget = null
-        return
-      }
-
-      const sequenceKey = formatHotkeySequence(resolvedSequence)
-
-      // Extract options without target (target is handled separately)
-      const {
-        target: _target,
-        enabled: _enabled,
-        ...restOptions
-      } = mergedOptions
-      const optionsWithoutTarget = {
-        ...restOptions,
-        ...(resolvedEnabled === undefined ? {} : { enabled: resolvedEnabled }),
-      }
-
-      if (
-        registration?.isActive &&
-        lastSequenceKey === sequenceKey &&
-        lastTarget === finalTarget
-      ) {
-        registration.callback = callback
-        registration.setOptions(optionsWithoutTarget)
-        return
-      }
-
-      if (registration?.isActive) {
-        registration.unregister()
-        registration = null
-      }
-
-      registration = manager.register(resolvedSequence, callback, {
-        ...optionsWithoutTarget,
-        target: finalTarget,
-      })
-
-      if (registration.isActive) {
-        registration.callback = callback
-        registration.setOptions(optionsWithoutTarget)
-      }
-
-      lastSequenceKey = sequenceKey
-      lastTarget = finalTarget
-    },
-    { immediate: true },
-  )
-
-  // Cleanup on unmount
-  onUnmounted(() => {
-    stopWatcher()
-    if (registration?.isActive) {
-      registration.unregister()
-      registration = null
-    }
-  })
-}
-
-function resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {
-  return typeof value === 'function' ? (value as () => T)() : unref(value)
-}

package/src/useHotkeySequenceRecorder.ts

@@ -1,75 +0,0 @@
-import { onUnmounted, unref, watch } from 'vue'
-import { useSelector } from '@tanstack/vue-store'
-import { HotkeySequenceRecorder } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProviderContext'
-import type { MaybeRefOrGetter, Ref } from 'vue'
-import type {
-  HotkeySequence,
-  HotkeySequenceRecorderOptions,
-} from '@tanstack/hotkeys'
-
-export interface VueHotkeySequenceRecorder {
-  isRecording: Ref<boolean>
-  steps: Ref<HotkeySequence>
-  recordedSequence: Ref<HotkeySequence | null>
-  startRecording: () => void
-  stopRecording: () => void
-  cancelRecording: () => void
-  commitRecording: () => void
-}
-
-/**
- * Vue composable for recording multi-chord sequences (Vim-style shortcuts).
- */
-export function useHotkeySequenceRecorder(
-  options: MaybeRefOrGetter<HotkeySequenceRecorderOptions>,
-): VueHotkeySequenceRecorder {
-  const defaultOptions = useDefaultHotkeysOptions()
-  const recorder = new HotkeySequenceRecorder(
-    resolveHotkeySequenceRecorderOptions(options, defaultOptions),
-  )
-
-  const isRecording = useSelector(recorder.store, (state) => state.isRecording)
-  const steps = useSelector(recorder.store, (state) => state.steps)
-  const recordedSequence = useSelector(
-    recorder.store,
-    (state) => state.recordedSequence,
-  )
-
-  const stopWatcher = watch(
-    () => resolveHotkeySequenceRecorderOptions(options, defaultOptions),
-    (resolvedOptions) => {
-      recorder.setOptions(resolvedOptions)
-    },
-    { immediate: true },
-  )
-
-  onUnmounted(() => {
-    stopWatcher()
-    recorder.destroy()
-  })
-
-  return {
-    isRecording: isRecording as Ref<boolean>,
-    steps: steps as Ref<HotkeySequence>,
-    recordedSequence: recordedSequence as Ref<HotkeySequence | null>,
-    startRecording: () => recorder.start(),
-    stopRecording: () => recorder.stop(),
-    cancelRecording: () => recorder.cancel(),
-    commitRecording: () => recorder.commit(),
-  }
-}
-
-function resolveHotkeySequenceRecorderOptions(
-  options: MaybeRefOrGetter<HotkeySequenceRecorderOptions>,
-  defaultOptions: ReturnType<typeof useDefaultHotkeysOptions>,
-): HotkeySequenceRecorderOptions {
-  return {
-    ...defaultOptions.hotkeySequenceRecorder,
-    ...resolveMaybeRefOrGetter(options),
-  } as HotkeySequenceRecorderOptions
-}
-
-function resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {
-  return typeof value === 'function' ? (value as () => T)() : unref(value)
-}