@tanstack/vue-hotkeys 0.11.0 → 0.12.1

package/src/useHotkeySequences.ts

@@ -1,221 +0,0 @@
-import { onUnmounted, unref, watch } from 'vue'
-import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProviderContext'
-import type { UseHotkeySequenceOptions } from './useHotkeySequence'
-import type {
-  HotkeyCallback,
-  HotkeySequence,
-  SequenceRegistrationHandle,
-} from '@tanstack/hotkeys'
-import type { MaybeRefOrGetter } from 'vue'
-
-/**
- * A single sequence definition for use with `useHotkeySequences`.
- */
-export interface UseHotkeySequenceDefinition {
-  /** Array of hotkey strings that form the sequence */
-  sequence: MaybeRefOrGetter<HotkeySequence>
-  /** The function to call when the sequence is completed */
-  callback: HotkeyCallback
-  /** Per-sequence options (merged on top of commonOptions) */
-  options?: MaybeRefOrGetter<UseHotkeySequenceOptions>
-}
-
-/**
- * Vue composable for registering multiple keyboard shortcut sequences at once (Vim-style).
- *
- * Uses the singleton SequenceManager. Accepts a dynamic array of definitions, or a getter/ref
- * that returns one, so you can register variable-length lists safely.
- *
- * Options are merged in this order:
- * HotkeysProvider defaults < commonOptions < per-definition options
- *
- * Definitions with an empty `sequence` are skipped (no registration).
- *
- * @param definitions - Array of sequence definitions, or a getter/ref
- * @param commonOptions - Shared options applied to all sequences (overridden by per-definition options)
- *
- * @example
- * ```vue
- * <script setup>
- * import { useHotkeySequences } from '@tanstack/vue-hotkeys'
- *
- * useHotkeySequences([
- *   { sequence: ['G', 'G'], callback: () => scrollToTop() },
- *   { sequence: ['D', 'D'], callback: () => deleteLine() },
- * ])
- * </script>
- * ```
- *
- * @example
- * ```vue
- * <script setup>
- * import { computed } from 'vue'
- * import { useHotkeySequences } from '@tanstack/vue-hotkeys'
- *
- * const items = computed(() => [...])
- * useHotkeySequences(
- *   () => items.value.map((item) => ({
- *     sequence: item.chords,
- *     callback: item.action,
- *     options: { enabled: item.enabled },
- *   })),
- *   { preventDefault: true },
- * )
- * </script>
- * ```
- */
-export function useHotkeySequences(
-  definitions: MaybeRefOrGetter<Array<UseHotkeySequenceDefinition>>,
-  commonOptions: MaybeRefOrGetter<UseHotkeySequenceOptions> = {},
-): void {
-  type RegistrationRecord = {
-    handle: SequenceRegistrationHandle
-    target: Document | HTMLElement | Window
-  }
-
-  const defaultOptions = useDefaultHotkeysOptions()
-  const manager = getSequenceManager()
-
-  const registrations = new Map<string, RegistrationRecord>()
-
-  const stopWatcher = watch(
-    () => {
-      const resolvedDefinitions = resolveMaybeRefOrGetter(definitions)
-      const resolvedCommonOptions = resolveMaybeRefOrGetter(commonOptions)
-
-      return resolvedDefinitions.map((def, i) => {
-        const resolvedSequence = resolveMaybeRefOrGetter(def.sequence)
-        const resolvedDefOptions = def.options
-          ? resolveMaybeRefOrGetter(def.options)
-          : {}
-
-        const mergedOptions = {
-          ...defaultOptions.hotkeySequence,
-          ...resolvedCommonOptions,
-          ...resolvedDefOptions,
-        } as UseHotkeySequenceOptions
-
-        const sequenceString = formatHotkeySequence(resolvedSequence)
-
-        const resolvedEnabled =
-          mergedOptions.enabled === undefined
-            ? undefined
-            : resolveMaybeRefOrGetter(mergedOptions.enabled)
-        const resolvedTarget =
-          mergedOptions.target === undefined
-            ? undefined
-            : resolveMaybeRefOrGetter(mergedOptions.target as any)
-
-        return {
-          index: i,
-          resolvedSequence,
-          sequenceString,
-          callback: def.callback,
-          mergedOptions,
-          resolvedEnabled,
-          resolvedTarget,
-        }
-      })
-    },
-    (resolved) => {
-      const nextKeys = new Set<string>()
-      const prepared: Array<{
-        registrationKey: string
-        entry: (typeof resolved)[number]
-        finalTarget: Document | HTMLElement | Window
-      }> = []
-
-      for (const entry of resolved) {
-        if (entry.resolvedSequence.length === 0) {
-          continue
-        }
-
-        const finalTarget =
-          entry.resolvedTarget ??
-          (typeof document !== 'undefined' ? document : null)
-
-        if (!finalTarget) {
-          continue
-        }
-
-        const registrationKey = `${entry.index}:${entry.sequenceString}`
-        nextKeys.add(registrationKey)
-        prepared.push({ registrationKey, entry, finalTarget })
-      }
-
-      for (const [key, record] of [...registrations.entries()]) {
-        if (!nextKeys.has(key)) {
-          if (record.handle.isActive) {
-            record.handle.unregister()
-          }
-          registrations.delete(key)
-        }
-      }
-
-      for (const { registrationKey, entry, finalTarget } of prepared) {
-        const existing = registrations.get(registrationKey)
-        if (existing?.handle.isActive && existing.target === finalTarget) {
-          existing.handle.callback = entry.callback
-          const {
-            target: _target,
-            enabled: _enabled,
-            ...restOptions
-          } = entry.mergedOptions
-          const optionsWithoutTarget = {
-            ...restOptions,
-            ...(entry.resolvedEnabled === undefined
-              ? {}
-              : { enabled: entry.resolvedEnabled }),
-          }
-          existing.handle.setOptions(optionsWithoutTarget)
-          continue
-        }
-
-        if (existing) {
-          if (existing.handle.isActive) {
-            existing.handle.unregister()
-          }
-          registrations.delete(registrationKey)
-        }
-
-        const {
-          target: _target,
-          enabled: _enabled,
-          ...restOptions
-        } = entry.mergedOptions
-        const optionsWithoutTarget = {
-          ...restOptions,
-          ...(entry.resolvedEnabled === undefined
-            ? {}
-            : { enabled: entry.resolvedEnabled }),
-        }
-
-        const handle = manager.register(
-          entry.resolvedSequence,
-          entry.callback,
-          {
-            ...optionsWithoutTarget,
-            target: finalTarget,
-          },
-        )
-        registrations.set(registrationKey, { handle, target: finalTarget })
-      }
-    },
-    { immediate: true },
-  )
-
-  onUnmounted(() => {
-    stopWatcher()
-    for (const { handle } of registrations.values()) {
-      if (handle.isActive) {
-        handle.unregister()
-      }
-    }
-    registrations.clear()
-  })
-}
-
-function resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {
-  return typeof value === 'function' ? (value as () => T)() : unref(value)
-}

package/src/useHotkeys.ts

@@ -1,221 +0,0 @@
-import { onUnmounted, unref, watch } from 'vue'
-import {
-  detectPlatform,
-  getHotkeyManager,
-  normalizeRegisterableHotkey,
-} from '@tanstack/hotkeys'
-import { useDefaultHotkeysOptions } from './HotkeysProviderContext'
-import type { UseHotkeyOptions } from './useHotkey'
-import type {
-  HotkeyCallback,
-  HotkeyRegistrationHandle,
-  RegisterableHotkey,
-} from '@tanstack/hotkeys'
-import type { MaybeRefOrGetter } from 'vue'
-
-/**
- * A single hotkey definition for use with `useHotkeys`.
- */
-export interface UseHotkeyDefinition {
-  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
-  hotkey: MaybeRefOrGetter<RegisterableHotkey>
-  /** The function to call when the hotkey is pressed */
-  callback: HotkeyCallback
-  /** Per-hotkey options (merged on top of commonOptions) */
-  options?: MaybeRefOrGetter<UseHotkeyOptions>
-}
-
-/**
- * Vue composable for registering multiple keyboard hotkeys at once.
- *
- * Uses the singleton HotkeyManager for efficient event handling.
- * Accepts a dynamic array of hotkey definitions, making it safe to use
- * with variable-length lists.
- *
- * Options are merged in this order:
- * HotkeysProvider defaults < commonOptions < per-definition options
- *
- * @param hotkeys - Array of hotkey definitions to register, or a getter/ref
- * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options)
- *
- * @example
- * ```vue
- * <script setup>
- * import { useHotkeys } from '@tanstack/vue-hotkeys'
- *
- * useHotkeys([
- *   { hotkey: 'Mod+S', callback: () => save() },
- *   { hotkey: 'Mod+Z', callback: () => undo() },
- *   { hotkey: 'Escape', callback: () => close() },
- * ])
- * </script>
- * ```
- *
- * @example
- * ```vue
- * <script setup>
- * import { computed } from 'vue'
- * import { useHotkeys } from '@tanstack/vue-hotkeys'
- *
- * const items = computed(() => [...])
- * // Dynamic hotkeys from reactive data
- * useHotkeys(
- *   () => items.value.map((item) => ({
- *     hotkey: item.shortcut,
- *     callback: item.action,
- *     options: { enabled: item.enabled },
- *   })),
- *   { preventDefault: true },
- * )
- * </script>
- * ```
- */
-export function useHotkeys(
-  hotkeys: MaybeRefOrGetter<Array<UseHotkeyDefinition>>,
-  commonOptions: MaybeRefOrGetter<UseHotkeyOptions> = {},
-): void {
-  type RegistrationRecord = {
-    handle: HotkeyRegistrationHandle
-    target: Document | HTMLElement | Window
-  }
-
-  const defaultOptions = useDefaultHotkeysOptions()
-  const manager = getHotkeyManager()
-
-  const registrations = new Map<string, RegistrationRecord>()
-
-  const stopWatcher = watch(
-    () => {
-      const resolvedHotkeys = resolveMaybeRefOrGetter(hotkeys)
-      const resolvedCommonOptions = resolveMaybeRefOrGetter(commonOptions)
-
-      return resolvedHotkeys.map((def, i) => {
-        const resolvedHotkey = resolveMaybeRefOrGetter(def.hotkey)
-        const resolvedDefOptions = def.options
-          ? resolveMaybeRefOrGetter(def.options)
-          : {}
-
-        const mergedOptions = {
-          ...defaultOptions.hotkey,
-          ...resolvedCommonOptions,
-          ...resolvedDefOptions,
-        } as UseHotkeyOptions
-
-        const platform = mergedOptions.platform ?? detectPlatform()
-        const hotkeyString = normalizeRegisterableHotkey(
-          resolvedHotkey,
-          platform,
-        )
-
-        const resolvedEnabled =
-          mergedOptions.enabled === undefined
-            ? undefined
-            : resolveMaybeRefOrGetter(mergedOptions.enabled)
-        const resolvedTarget =
-          mergedOptions.target === undefined
-            ? undefined
-            : resolveMaybeRefOrGetter(mergedOptions.target as any)
-
-        return {
-          index: i,
-          hotkeyString,
-          callback: def.callback,
-          mergedOptions,
-          resolvedEnabled,
-          resolvedTarget,
-        }
-      })
-    },
-    (resolved) => {
-      const nextKeys = new Set<string>()
-      const prepared: Array<{
-        registrationKey: string
-        entry: (typeof resolved)[number]
-        finalTarget: Document | HTMLElement | Window
-      }> = []
-
-      for (const entry of resolved) {
-        const finalTarget =
-          entry.resolvedTarget ??
-          (typeof document !== 'undefined' ? document : null)
-
-        if (!finalTarget) {
-          continue
-        }
-
-        const registrationKey = `${entry.index}:${entry.hotkeyString}`
-        nextKeys.add(registrationKey)
-        prepared.push({ registrationKey, entry, finalTarget })
-      }
-
-      for (const [key, record] of [...registrations.entries()]) {
-        if (!nextKeys.has(key)) {
-          if (record.handle.isActive) {
-            record.handle.unregister()
-          }
-          registrations.delete(key)
-        }
-      }
-
-      for (const { registrationKey, entry, finalTarget } of prepared) {
-        const existing = registrations.get(registrationKey)
-        if (existing?.handle.isActive && existing.target === finalTarget) {
-          existing.handle.callback = entry.callback
-          const {
-            target: _target,
-            enabled: _enabled,
-            ...restOptions
-          } = entry.mergedOptions
-          const optionsWithoutTarget = {
-            ...restOptions,
-            ...(entry.resolvedEnabled === undefined
-              ? {}
-              : { enabled: entry.resolvedEnabled }),
-          }
-          existing.handle.setOptions(optionsWithoutTarget)
-          continue
-        }
-
-        if (existing) {
-          if (existing.handle.isActive) {
-            existing.handle.unregister()
-          }
-          registrations.delete(registrationKey)
-        }
-
-        const {
-          target: _target,
-          enabled: _enabled,
-          ...restOptions
-        } = entry.mergedOptions
-        const optionsWithoutTarget = {
-          ...restOptions,
-          ...(entry.resolvedEnabled === undefined
-            ? {}
-            : { enabled: entry.resolvedEnabled }),
-        }
-
-        const handle = manager.register(entry.hotkeyString, entry.callback, {
-          ...optionsWithoutTarget,
-          target: finalTarget,
-        })
-        registrations.set(registrationKey, { handle, target: finalTarget })
-      }
-    },
-    { immediate: true },
-  )
-
-  onUnmounted(() => {
-    stopWatcher()
-    for (const { handle } of registrations.values()) {
-      if (handle.isActive) {
-        handle.unregister()
-      }
-    }
-    registrations.clear()
-  })
-}
-
-function resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {
-  return typeof value === 'function' ? (value as () => T)() : unref(value)
-}

package/src/useKeyHold.ts

@@ -1,65 +0,0 @@
-import { useSelector } from '@tanstack/vue-store'
-import { getKeyStateTracker } from '@tanstack/hotkeys'
-import { unref } from 'vue'
-import type { MaybeRefOrGetter, Ref } from 'vue'
-import type { IndividualKey } from '@tanstack/hotkeys'
-
-/**
- * Vue composable that returns a reactive ref indicating whether a specific key is currently being held.
- *
- * This composable uses `useSelector` from `@tanstack/vue-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')
- * @returns Reactive ref that is true if the key is currently held down
- *
- * @example
- * ```vue
- * <script setup>
- * import { useKeyHold } from '@tanstack/vue-hotkeys'
- *
- * const isShiftHeld = useKeyHold('Shift')
- * </script>
- *
- * <template>
- *   <div :style="{ opacity: isShiftHeld ? 1 : 0.5 }">
- *     {{ isShiftHeld ? 'Shift is pressed!' : 'Press Shift' }}
- *   </div>
- * </template>
- * ```
- *
- * @example
- * ```vue
- * <script setup>
- * import { useKeyHold } from '@tanstack/vue-hotkeys'
- *
- * const ctrl = useKeyHold('Control')
- * const shift = useKeyHold('Shift')
- * const alt = useKeyHold('Alt')
- * </script>
- *
- * <template>
- *   <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>
- * </template>
- * ```
- */
-export function useKeyHold(key: MaybeRefOrGetter<IndividualKey>): Ref<boolean> {
-  const tracker = getKeyStateTracker()
-
-  const isHeld = useSelector(tracker.store, (state) => {
-    const keyValue = unref(key)
-    const normalizedKey = (
-      typeof keyValue === 'string' ? keyValue : String(keyValue)
-    ).toLowerCase()
-    return state.heldKeys.some(
-      (heldKey) => heldKey.toLowerCase() === normalizedKey,
-    )
-  })
-
-  return isHeld as Ref<boolean>
-}

package/src/vue.d.ts

@@ -1,6 +0,0 @@
-declare module '*.vue' {
-  import type { DefineComponent } from 'vue'
-
-  const component: DefineComponent<{}, {}, any>
-  export default component
-}