@tanstack/vue-hotkeys 0.13.0 → 0.14.1

package/dist/useHotkey.js

@@ -1,139 +1,12 @@
-import { useDefaultHotkeysOptionsSource } from "./defaultOptions.js";
-import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey } from "@tanstack/hotkeys";
-import { onUnmounted, unref, watch } from "vue";
+import { useHotkeys } from "./useHotkeys.js";
 
 //#region src/useHotkey.ts
-/**
-* 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>
-* ```
-*/
 function useHotkey(hotkey, callback, options = {}) {
-	const defaultOptions = useDefaultHotkeysOptionsSource();
-	const manager = getHotkeyManager();
-	let registration = null;
-	let lastHotkeyString = null;
-	let lastTarget = null;
-	const stopWatcher = watch(() => {
-		const resolvedHotkey = resolveMaybeRefOrGetter(hotkey);
-		const resolvedOptions = resolveMaybeRefOrGetter(options);
-		const mergedOptions = {
-			...defaultOptions().hotkey,
-			...resolvedOptions
-		};
-		return {
-			resolvedHotkey,
-			mergedOptions,
-			resolvedEnabled: mergedOptions.enabled === void 0 ? void 0 : resolveMaybeRefOrGetter(mergedOptions.enabled),
-			resolvedTarget: mergedOptions.target === void 0 ? void 0 : resolveMaybeRefOrGetter(mergedOptions.target)
-		};
-	}, ({ resolvedHotkey, mergedOptions, resolvedEnabled, resolvedTarget }) => {
-		const platform = mergedOptions.platform ?? detectPlatform();
-		const hotkeyString = normalizeRegisterableHotkey(resolvedHotkey, platform);
-		const finalTarget = resolvedTarget === void 0 ? typeof document !== "undefined" ? document : null : resolvedTarget;
-		if (!finalTarget) {
-			if (registration?.isActive) {
-				registration.unregister();
-				registration = null;
-			}
-			lastHotkeyString = null;
-			lastTarget = null;
-			return;
-		}
-		const { target: _target, enabled: _enabled, ...restOptions } = mergedOptions;
-		const optionsWithoutTarget = {
-			...restOptions,
-			...resolvedEnabled === void 0 ? {} : { 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 });
-	onUnmounted(() => {
-		stopWatcher();
-		if (registration?.isActive) {
-			registration.unregister();
-			registration = null;
-		}
-	});
-}
-function resolveMaybeRefOrGetter(value) {
-	return typeof value === "function" ? value() : unref(value);
+	useHotkeys([{
+		hotkey,
+		callback,
+		options
+	}]);
 }
 
 //#endregion

package/dist/useHotkeyHint.d.ts

@@ -1,12 +1,12 @@
-import { HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HeldModifierOptions, RegisterableHotkey } from "@tanstack/hotkeys";
 import { ComputedRef, MaybeRefOrGetter } from "vue";
 //#region src/useHotkeyHint.d.ts
 /**
  * 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.
+ * Pass refs or getters to track changing hotkeys and options. A sequence
+ * reveals its hint from its first step, and an app hotkey uses its effective
+ * hotkey (false while unbound). This helper does not register a shortcut or
+ * check whether its target is focused.
  */
-export declare function useHotkeyHint(hotkey: MaybeRefOrGetter<RegisterableHotkey>, options?: MaybeRefOrGetter<HeldModifierOptions>): ComputedRef<boolean>;
+export declare function useHotkeyHint(hotkey: MaybeRefOrGetter<RegisterableHotkey | AppHotkey>, options?: MaybeRefOrGetter<HeldModifierOptions>): ComputedRef<boolean>;
 //#endregion

package/dist/useHotkeyHint.js

@@ -1,18 +1,25 @@
-import { getKeyStateTracker, matchesHeldModifiers } from "@tanstack/hotkeys";
+import { useAppHotkeysStoreSource } from "./defaultOptions.js";
+import { getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
 import { computed, toValue } from "vue";
 import { useSelector } from "@tanstack/vue-store";
 
 //#region src/useHotkeyHint.ts
 /**
 * 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.
+* Pass refs or getters to track changing hotkeys and options. A sequence
+* reveals its hint from its first step, and an app hotkey uses its effective
+* hotkey (false while unbound). This helper does not register a shortcut or
+* check whether its target is focused.
 */
 function useHotkeyHint(hotkey, options = {}) {
+	const appHotkeys = useAppHotkeysStoreSource();
 	const held = useSelector(getKeyStateTracker().store, (state) => state.heldKeys);
-	return computed(() => matchesHeldModifiers(toValue(hotkey), held.value, toValue(options)));
+	return computed(() => {
+		appHotkeys.state.value;
+		const value = toValue(hotkey);
+		const resolved = isAppHotkey(value) ? resolveAppHotkey(value, appHotkeys.store).hotkey : value;
+		return resolved !== null && matchesHeldModifiers(resolved, held.value, toValue(options));
+	});
 }
 
 //#endregion

package/dist/useHotkeyRecorder.d.ts

@@ -1,58 +1,39 @@
-import { Hotkey, HotkeyRecorderOptions } from "@tanstack/hotkeys";
-import { MaybeRefOrGetter, Ref } from "vue";
+import { Hotkey, HotkeyChord, HotkeyChordRecorderOptions, HotkeyRecorderOptions, HotkeySequence, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { Ref } from "vue";
 //#region src/useHotkeyRecorder.d.ts
-export interface VueHotkeyRecorder {
+export interface VueHotkeyRecorder<THotkey extends Hotkey = Hotkey> {
   /** Whether recording is currently active */
-  isRecording: Ref<boolean>;
-  /** The currently recorded hotkey (for live preview) */
-  recordedHotkey: Ref<Hotkey | null>;
+  isRecording: Readonly<Ref<boolean>>;
+  /** Chords recorded so far in a multi-step recording (for live preview) */
+  steps: Readonly<Ref<HotkeySequence>>;
+  /** The last committed hotkey */
+  recordedHotkey: Readonly<Ref<THotkey | null>>;
   /** Start recording a new hotkey */
   startRecording: () => void;
-  /** Stop recording (same as cancel) */
+  /** Stop recording without calling onCancel */
   stopRecording: () => void;
-  /** Cancel recording without saving */
+  /** Cancel recording and call onCancel */
   cancelRecording: () => void;
+  /** Commit the recorded steps now (multi-step recordings) */
+  commitRecording: () => void;
 }
 /**
- * Vue composable for recording keyboard shortcuts.
+ * Vue composable for recording keyboard shortcuts. Options may be a ref or getter.
  *
- * 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
+ * With the default `maxSteps: 1`, the first valid chord is recorded. With a
+ * larger `maxSteps`, each chord adds a step; the recording commits on Enter
+ * (unless `commitKeys: 'none'`), after `idleTimeoutMs`, or at `maxSteps`, and
+ * `onRecord` receives a chord (one step) or a sequence.
  *
  * @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>
+ * ```ts
+ * const recorder = useHotkeyRecorder({ onRecord: (hotkey) => (shortcut.value = hotkey) })
+ * const sequenceRecorder = useHotkeyRecorder({ maxSteps: 3, onRecord: save })
  * ```
  */
-export declare function useHotkeyRecorder(options: MaybeRefOrGetter<HotkeyRecorderOptions>): VueHotkeyRecorder;
+export declare function useHotkeyRecorder(options: HotkeyChordRecorderOptions): VueHotkeyRecorder<HotkeyChord>;
+export declare function useHotkeyRecorder(options: HotkeySequenceRecorderOptions): VueHotkeyRecorder;
+export declare function useHotkeyRecorder(options: () => HotkeySequenceRecorderOptions): VueHotkeyRecorder;
+export declare function useHotkeyRecorder(options: () => HotkeyChordRecorderOptions): VueHotkeyRecorder<HotkeyChord>;
+export declare function useHotkeyRecorder(options: Ref<HotkeyRecorderOptions>): VueHotkeyRecorder;
 //#endregion

package/dist/useHotkeyRecorder.js

@@ -1,79 +1,34 @@
 import { useDefaultHotkeysOptionsSource } from "./defaultOptions.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
-import { onUnmounted, unref, watch } from "vue";
+import { onScopeDispose, toValue, watch } from "vue";
 import { useSelector } from "@tanstack/vue-store";
 
 //#region src/useHotkeyRecorder.ts
-/**
-* 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>
-* ```
-*/
 function useHotkeyRecorder(options) {
 	const defaultOptions = useDefaultHotkeysOptionsSource();
-	const recorder = new HotkeyRecorder(resolveRecorderOptions(options, defaultOptions));
+	const resolve = () => ({
+		...defaultOptions().hotkeyRecorder,
+		...toValue(options)
+	});
+	const recorder = new HotkeyRecorder(resolve());
 	const isRecording = useSelector(recorder.store, (state) => state.isRecording);
+	const steps = useSelector(recorder.store, (state) => state.steps);
 	const recordedHotkey = useSelector(recorder.store, (state) => state.recordedHotkey);
-	const stopWatcher = watch(() => resolveRecorderOptions(options, defaultOptions), (resolvedOptions) => {
-		recorder.setOptions(resolvedOptions);
-	}, { immediate: true });
-	onUnmounted(() => {
+	const stopWatcher = watch(resolve, (resolved) => recorder.setOptions(resolved));
+	onScopeDispose(() => {
 		stopWatcher();
 		recorder.destroy();
 	});
 	return {
 		isRecording,
+		steps,
 		recordedHotkey,
 		startRecording: () => recorder.start(),
 		stopRecording: () => recorder.stop(),
-		cancelRecording: () => recorder.cancel()
+		cancelRecording: () => recorder.cancel(),
+		commitRecording: () => recorder.commit()
 	};
 }
-function resolveRecorderOptions(options, defaultOptions) {
-	return {
-		...defaultOptions().hotkeyRecorder,
-		...resolveMaybeRefOrGetter(options)
-	};
-}
-function resolveMaybeRefOrGetter(value) {
-	return typeof value === "function" ? value() : unref(value);
-}
 
 //#endregion
 export { useHotkeyRecorder };

package/dist/useHotkeyRegistrations.d.ts

@@ -1,24 +1,25 @@
-import { HotkeyRegistrationView, SequenceRegistrationView } from "@tanstack/hotkeys";
+import { HotkeyRegistrationView } from "@tanstack/hotkeys";
 import { Ref } from "vue";
 //#region src/useHotkeyRegistrations.d.ts
 /**
- * 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.
+ * Vue composable that reactively reads every hotkey registration, chords and
+ * sequences, from the singleton HotkeyManager. Narrow each view with `kind`.
+ *
+ * This composable does NOT require the HotkeysProvider.
  *
- * 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 A ref of all registrations, without callbacks
  *
- * @returns Object with `hotkeys` and `sequences` refs
+ * @example
+ * ```vue
+ * <script setup>
+ * const registrations = useHotkeyRegistrations()
+ * </script>
+ * <template>
+ *   <li v-for="reg in registrations" :key="reg.id">
+ *     {{ reg.options.meta?.name }}: {{ formatForDisplay(reg.hotkey) }}
+ *   </li>
+ * </template>
+ * ```
  */
-export declare function useHotkeyRegistrations(): HotkeyRegistrationsResult;
+export declare function useHotkeyRegistrations(): Readonly<Ref<Array<HotkeyRegistrationView>>>;
 //#endregion

package/dist/useHotkeyRegistrations.js

@@ -1,24 +1,29 @@
-import { getHotkeyManager, getSequenceManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
+import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
 import { useSelector } from "@tanstack/vue-store";
 
 //#region src/useHotkeyRegistrations.ts
 /**
-* Vue composable that reactively reads all hotkey and sequence registrations
-* from the singleton managers.
+* Vue composable that reactively reads every hotkey registration, chords and
+* sequences, from the singleton HotkeyManager. Narrow each view with `kind`.
 *
-* 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.
+* This composable does NOT require the HotkeysProvider.
 *
-* @returns Object with `hotkeys` and `sequences` refs
+* @returns A ref of all registrations, without callbacks
+*
+* @example
+* ```vue
+* <script setup>
+* const registrations = useHotkeyRegistrations()
+* <\/script>
+* <template>
+*   <li v-for="reg in registrations" :key="reg.id">
+*     {{ reg.options.meta?.name }}: {{ formatForDisplay(reg.hotkey) }}
+*   </li>
+* </template>
+* ```
 */
 function useHotkeyRegistrations() {
-	const hotkeyManager = getHotkeyManager();
-	const sequenceManager = getSequenceManager();
-	return {
-		hotkeys: useSelector(hotkeyManager.registrations, (state) => Array.from(state.values()).map(toHotkeyRegistrationView)),
-		sequences: useSelector(sequenceManager.registrations, (state) => Array.from(state.values()))
-	};
+	return useSelector(getHotkeyManager().registrations, (state) => Array.from(state.values()).map(toHotkeyRegistrationView));
 }
 
 //#endregion

package/dist/useHotkeys.d.ts

@@ -1,62 +1,51 @@
-import { UseHotkeyOptions } from "./useHotkey.js";
-import { HotkeyCallback, RegisterableHotkey } from "@tanstack/hotkeys";
+import { UseAppHotkeyOptions, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyOptions, UseHotkeySequenceOptions } from "./useHotkey.js";
+import { AppHotkey, HotkeyCallback, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord } from "@tanstack/hotkeys";
 import { MaybeRefOrGetter } from "vue";
 //#region src/useHotkeys.d.ts
 /**
- * A single hotkey definition for use with `useHotkeys`.
+ * One hotkey for `useHotkeys`. The hotkey and options may be refs or getters.
+ * Chords accept `requireReset`; sequences accept `timeout`; hotkeys of unknown
+ * kind accept only shared options.
  */
-export interface UseHotkeyDefinition {
-  /** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
-  hotkey: MaybeRefOrGetter<RegisterableHotkey>;
+export type UseHotkeyDefinition = {
+  /** A chord string such as `'Mod+S'`, or a RawHotkey object */
+  hotkey: MaybeRefOrGetter<RegisterableHotkeyChord>;
   /** The function to call when the hotkey is pressed */
   callback: HotkeyCallback;
   /** Per-hotkey options (merged on top of commonOptions) */
+  options?: MaybeRefOrGetter<UseHotkeyChordOptions>;
+} | {
+  /** A sequence such as `['G', 'G']` */
+  hotkey: MaybeRefOrGetter<HotkeySequence>;
+  callback: HotkeyCallback;
+  options?: MaybeRefOrGetter<UseHotkeySequenceOptions>;
+} | {
+  /** An app hotkey from `defineAppHotkeys` */
+  hotkey: MaybeRefOrGetter<AppHotkey>;
+  callback: HotkeyCallback;
+  options?: MaybeRefOrGetter<UseAppHotkeyOptions>;
+} | {
+  /** A hotkey whose kind is not known statically. Accepts only shared options. */
+  hotkey: MaybeRefOrGetter<RegisterableHotkey>;
+  callback: HotkeyCallback;
   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.
+ * Vue composable for registering several hotkeys at once: chords, sequences,
+ * and app hotkeys. The list, each hotkey, and options may be refs or getters.
  *
- * 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)
+ * Options merge in this order: provider defaults, app hotkey declaration,
+ * commonOptions, per-hotkey options. Each option applies only to the kinds
+ * that support it. Unbound app hotkeys and empty sequences register nothing.
+ * A target that resolves to `null` skips registration until it is set.
  *
  * @example
- * ```vue
- * <script setup>
- * import { useHotkeys } from '@tanstack/vue-hotkeys'
- *
+ * ```ts
  * useHotkeys([
  *   { hotkey: 'Mod+S', callback: () => save() },
- *   { hotkey: 'Mod+Z', callback: () => undo() },
- *   { hotkey: 'Escape', callback: () => close() },
+ *   { hotkey: ['G', 'G'], callback: () => scrollToTop(), options: { timeout: 500 } },
  * ])
- * </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 declare function useHotkeys(hotkeys: MaybeRefOrGetter<Array<UseHotkeyDefinition>>, commonOptions?: MaybeRefOrGetter<UseHotkeyOptions>): void;
+export declare function useHotkeys(hotkeys: MaybeRefOrGetter<ReadonlyArray<UseHotkeyDefinition>>, commonOptions?: MaybeRefOrGetter<UseHotkeyCommonOptions>): void;
 //#endregion