@tanstack/vue-hotkeys 0.0.1

package/dist/useHeldKeys.d.cts

@@ -0,0 +1,31 @@
+import { Ref } from "vue";
+
+//#region src/useHeldKeys.d.ts
+/**
+ * Vue composable that returns a reactive ref of currently held keyboard keys.
+ *
+ * This composable uses `useStore` from `@tanstack/vue-store` to subscribe
+ * to the global KeyStateTracker and updates whenever keys are pressed
+ * or released.
+ *
+ * @returns Reactive ref containing array of currently held key names
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useHeldKeys } from '@tanstack/vue-hotkeys'
+ *
+ * const heldKeys = useHeldKeys()
+ * </script>
+ *
+ * <template>
+ *   <div>
+ *     Currently pressed: {{ heldKeys.join(' + ') || 'None' }}
+ *   </div>
+ * </template>
+ * ```
+ */
+declare function useHeldKeys(): Ref<Array<string>>;
+//#endregion
+export { useHeldKeys };
+//# sourceMappingURL=useHeldKeys.d.cts.map

package/dist/useHeldKeys.d.ts

@@ -0,0 +1,31 @@
+import { Ref } from "vue";
+
+//#region src/useHeldKeys.d.ts
+/**
+ * Vue composable that returns a reactive ref of currently held keyboard keys.
+ *
+ * This composable uses `useStore` from `@tanstack/vue-store` to subscribe
+ * to the global KeyStateTracker and updates whenever keys are pressed
+ * or released.
+ *
+ * @returns Reactive ref containing array of currently held key names
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useHeldKeys } from '@tanstack/vue-hotkeys'
+ *
+ * const heldKeys = useHeldKeys()
+ * </script>
+ *
+ * <template>
+ *   <div>
+ *     Currently pressed: {{ heldKeys.join(' + ') || 'None' }}
+ *   </div>
+ * </template>
+ * ```
+ */
+declare function useHeldKeys(): Ref<Array<string>>;
+//#endregion
+export { useHeldKeys };
+//# sourceMappingURL=useHeldKeys.d.ts.map

package/dist/useHeldKeys.js

@@ -0,0 +1,35 @@
+import { getKeyStateTracker } from "@tanstack/hotkeys";
+import { useStore } from "@tanstack/vue-store";
+
+//#region src/useHeldKeys.ts
+/**
+* Vue composable that returns a reactive ref of currently held keyboard keys.
+*
+* This composable uses `useStore` from `@tanstack/vue-store` to subscribe
+* to the global KeyStateTracker and updates whenever keys are pressed
+* or released.
+*
+* @returns Reactive ref containing array of currently held key names
+*
+* @example
+* ```vue
+* <script setup>
+* import { useHeldKeys } from '@tanstack/vue-hotkeys'
+*
+* const heldKeys = useHeldKeys()
+* <\/script>
+*
+* <template>
+*   <div>
+*     Currently pressed: {{ heldKeys.join(' + ') || 'None' }}
+*   </div>
+* </template>
+* ```
+*/
+function useHeldKeys() {
+	return useStore(getKeyStateTracker().store, (state) => state.heldKeys);
+}
+
+//#endregion
+export { useHeldKeys };
+//# sourceMappingURL=useHeldKeys.js.map

package/dist/useHeldKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHeldKeys.js","names":[],"sources":["../src/useHeldKeys.ts"],"sourcesContent":["import { useStore } from '@tanstack/vue-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\nimport type { Ref } from 'vue'\n\n/**\n * Vue composable that returns a reactive ref of currently held keyboard keys.\n *\n * This composable uses `useStore` from `@tanstack/vue-store` to subscribe\n * to the global KeyStateTracker and updates whenever keys are pressed\n * or released.\n *\n * @returns Reactive ref containing array of currently held key names\n *\n * @example\n * ```vue\n * <script setup>\n * import { useHeldKeys } from '@tanstack/vue-hotkeys'\n *\n * const heldKeys = useHeldKeys()\n * </script>\n *\n * <template>\n *   <div>\n *     Currently pressed: {{ heldKeys.join(' + ') || 'None' }}\n *   </div>\n * </template>\n * ```\n */\nexport function useHeldKeys(): Ref<Array<string>> {\n  const tracker = getKeyStateTracker()\n  return useStore(tracker.store, (state) => state.heldKeys)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,cAAkC;AAEhD,QAAO,SADS,oBAAoB,CACZ,QAAQ,UAAU,MAAM,SAAS"}

package/dist/useHotkey.cjs

@@ -0,0 +1,124 @@
+const require_HotkeysProviderContext = require('./HotkeysProviderContext.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let vue = require("vue");
+
+//#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 = require_HotkeysProviderContext.useDefaultHotkeysOptions();
+	const manager = (0, _tanstack_hotkeys.getHotkeyManager)();
+	let registration = null;
+	const stopWatcher = (0, vue.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 ?? (0, _tanstack_hotkeys.detectPlatform)();
+		const hotkeyString = typeof resolvedHotkey === "string" ? resolvedHotkey : (0, _tanstack_hotkeys.formatHotkey)((0, _tanstack_hotkeys.rawHotkeyToParsedHotkey)(resolvedHotkey, platform));
+		const finalTarget = resolvedTarget ?? (typeof document !== "undefined" ? document : null);
+		if (!finalTarget) return;
+		if (registration?.isActive) {
+			registration.unregister();
+			registration = null;
+		}
+		const { target: _target, enabled: _enabled, ...restOptions } = mergedOptions;
+		const optionsWithoutTarget = {
+			...restOptions,
+			...resolvedEnabled === void 0 ? {} : { enabled: resolvedEnabled }
+		};
+		registration = manager.register(hotkeyString, callback, {
+			...optionsWithoutTarget,
+			target: finalTarget
+		});
+		if (registration.isActive) {
+			registration.callback = callback;
+			registration.setOptions(optionsWithoutTarget);
+		}
+	}, { immediate: true });
+	(0, vue.onUnmounted)(() => {
+		stopWatcher();
+		if (registration?.isActive) {
+			registration.unregister();
+			registration = null;
+		}
+	});
+}
+function resolveMaybeRefOrGetter(value) {
+	return typeof value === "function" ? value() : (0, vue.unref)(value);
+}
+
+//#endregion
+exports.useHotkey = useHotkey;
+//# sourceMappingURL=useHotkey.cjs.map

package/dist/useHotkey.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkey.cjs","names":["useDefaultHotkeysOptions"],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { onUnmounted, unref, watch } from 'vue'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProviderContext'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport type { MaybeRefOrGetter } from 'vue'\n\nexport interface UseHotkeyOptions extends Omit<\n  HotkeyOptions,\n  'enabled' | 'target'\n> {\n  /**\n   * Whether the hotkey is active.\n   * Can be a Ref, a getter function, or a boolean value.\n   * Defaults to true.\n   */\n  enabled?: MaybeRefOrGetter<boolean>\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Ref, a getter function, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?: MaybeRefOrGetter<HTMLElement | Document | Window | null>\n}\n\n/**\n * Vue composable for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This composable automatically tracks reactive dependencies and updates\n * the registration when options or the callback change.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior\n *\n * @example\n * ```vue\n * <script setup>\n * import { ref } from 'vue'\n * import { useHotkey } from '@tanstack/vue-hotkeys'\n *\n * const count = ref(0)\n *\n * // Callback always has access to latest count value\n * useHotkey('Mod+S', (event, { hotkey }) => {\n *   console.log(`Save triggered, count is ${count.value}`)\n *   handleSave()\n * })\n * </script>\n * ```\n *\n * @example\n * ```vue\n * <script setup>\n * import { ref } from 'vue'\n * import { useHotkey } from '@tanstack/vue-hotkeys'\n *\n * const isOpen = ref(false)\n *\n * // enabled option is reactive\n * useHotkey('Escape', () => {\n *   isOpen.value = false\n * }, { enabled: isOpen })\n * </script>\n * ```\n *\n * @example\n * ```vue\n * <script setup>\n * import { ref } from 'vue'\n * import { useHotkey } from '@tanstack/vue-hotkeys'\n *\n * const editorRef = ref<HTMLDivElement | null>(null)\n *\n * // Scoped to a specific element\n * useHotkey('Mod+S', () => {\n *   save()\n * }, { target: editorRef })\n * </script>\n *\n * <template>\n *   <div ref=\"editorRef\">...</div>\n * </template>\n * ```\n */\nexport function useHotkey(\n  hotkey: MaybeRefOrGetter<RegisterableHotkey>,\n  callback: HotkeyCallback,\n  options: MaybeRefOrGetter<UseHotkeyOptions> = {},\n): void {\n  const defaultOptions = useDefaultHotkeysOptions()\n  const manager = getHotkeyManager()\n\n  let registration: HotkeyRegistrationHandle | null = null\n\n  // Watch for changes to reactive dependencies\n  const stopWatcher = watch(\n    () => {\n      const resolvedHotkey = resolveMaybeRefOrGetter(hotkey)\n      const resolvedOptions = resolveMaybeRefOrGetter(options)\n      const mergedOptions = {\n        ...defaultOptions.hotkey,\n        ...resolvedOptions,\n      } as UseHotkeyOptions\n      const resolvedEnabled =\n        mergedOptions.enabled === undefined\n          ? undefined\n          : resolveMaybeRefOrGetter(mergedOptions.enabled)\n      const resolvedTarget =\n        mergedOptions.target === undefined\n          ? undefined\n          : resolveMaybeRefOrGetter(mergedOptions.target)\n\n      return {\n        resolvedHotkey,\n        mergedOptions,\n        resolvedEnabled,\n        resolvedTarget,\n      }\n    },\n    ({ resolvedHotkey, mergedOptions, resolvedEnabled, resolvedTarget }) => {\n      // Normalize to hotkey string\n      const platform = mergedOptions.platform ?? detectPlatform()\n      const hotkeyString: Hotkey =\n        typeof resolvedHotkey === 'string'\n          ? resolvedHotkey\n          : (formatHotkey(\n              rawHotkeyToParsedHotkey(resolvedHotkey as any, platform),\n            ) as Hotkey)\n\n      // Resolve target\n      const finalTarget =\n        resolvedTarget ?? (typeof document !== 'undefined' ? document : null)\n\n      if (!finalTarget) {\n        return\n      }\n\n      // Unregister previous registration if it exists\n      if (registration?.isActive) {\n        registration.unregister()\n        registration = null\n      }\n\n      // Extract options without target (target is handled separately)\n      const {\n        target: _target,\n        enabled: _enabled,\n        ...restOptions\n      } = mergedOptions\n      const optionsWithoutTarget = {\n        ...restOptions,\n        ...(resolvedEnabled === undefined ? {} : { enabled: resolvedEnabled }),\n      }\n\n      // Register the hotkey\n      registration = manager.register(hotkeyString, callback, {\n        ...optionsWithoutTarget,\n        target: finalTarget,\n      })\n\n      // Update callback and options\n      if (registration.isActive) {\n        registration.callback = callback\n        registration.setOptions(optionsWithoutTarget)\n      }\n    },\n    { immediate: true },\n  )\n\n  // Cleanup on unmount\n  onUnmounted(() => {\n    stopWatcher()\n    if (registration?.isActive) {\n      registration.unregister()\n      registration = null\n    }\n  })\n}\n\nfunction resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {\n  return typeof value === 'function' ? (value as () => T)() : unref(value)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmGA,SAAgB,UACd,QACA,UACA,UAA8C,EAAE,EAC1C;CACN,MAAM,iBAAiBA,yDAA0B;CACjD,MAAM,mDAA4B;CAElC,IAAI,eAAgD;CAGpD,MAAM,mCACE;EACJ,MAAM,iBAAiB,wBAAwB,OAAO;EACtD,MAAM,kBAAkB,wBAAwB,QAAQ;EACxD,MAAM,gBAAgB;GACpB,GAAG,eAAe;GAClB,GAAG;GACJ;AAUD,SAAO;GACL;GACA;GACA,iBAXA,cAAc,YAAY,SACtB,SACA,wBAAwB,cAAc,QAAQ;GAUlD,gBARA,cAAc,WAAW,SACrB,SACA,wBAAwB,cAAc,OAAO;GAOlD;KAEF,EAAE,gBAAgB,eAAe,iBAAiB,qBAAqB;EAEtE,MAAM,WAAW,cAAc,mDAA4B;EAC3D,MAAM,eACJ,OAAO,mBAAmB,WACtB,oGAE0B,gBAAuB,SAAS,CACzD;EAGP,MAAM,cACJ,mBAAmB,OAAO,aAAa,cAAc,WAAW;AAElE,MAAI,CAAC,YACH;AAIF,MAAI,cAAc,UAAU;AAC1B,gBAAa,YAAY;AACzB,kBAAe;;EAIjB,MAAM,EACJ,QAAQ,SACR,SAAS,UACT,GAAG,gBACD;EACJ,MAAM,uBAAuB;GAC3B,GAAG;GACH,GAAI,oBAAoB,SAAY,EAAE,GAAG,EAAE,SAAS,iBAAiB;GACtE;AAGD,iBAAe,QAAQ,SAAS,cAAc,UAAU;GACtD,GAAG;GACH,QAAQ;GACT,CAAC;AAGF,MAAI,aAAa,UAAU;AACzB,gBAAa,WAAW;AACxB,gBAAa,WAAW,qBAAqB;;IAGjD,EAAE,WAAW,MAAM,CACpB;AAGD,4BAAkB;AAChB,eAAa;AACb,MAAI,cAAc,UAAU;AAC1B,gBAAa,YAAY;AACzB,kBAAe;;GAEjB;;AAGJ,SAAS,wBAA2B,OAA+B;AACjE,QAAO,OAAO,UAAU,aAAc,OAAmB,kBAAS,MAAM"}

package/dist/useHotkey.d.cts

@@ -0,0 +1,86 @@
+import { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/useHotkey.d.ts
+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>
+ * ```
+ */
+declare function useHotkey(hotkey: MaybeRefOrGetter<RegisterableHotkey>, callback: HotkeyCallback, options?: MaybeRefOrGetter<UseHotkeyOptions>): void;
+//#endregion
+export { UseHotkeyOptions, useHotkey };
+//# sourceMappingURL=useHotkey.d.cts.map

package/dist/useHotkey.d.ts

@@ -0,0 +1,86 @@
+import { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/useHotkey.d.ts
+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>
+ * ```
+ */
+declare function useHotkey(hotkey: MaybeRefOrGetter<RegisterableHotkey>, callback: HotkeyCallback, options?: MaybeRefOrGetter<UseHotkeyOptions>): void;
+//#endregion
+export { UseHotkeyOptions, useHotkey };
+//# sourceMappingURL=useHotkey.d.ts.map

package/dist/useHotkey.js

@@ -0,0 +1,124 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProviderContext.js";
+import { detectPlatform, formatHotkey, getHotkeyManager, rawHotkeyToParsedHotkey } from "@tanstack/hotkeys";
+import { onUnmounted, unref, watch } from "vue";
+
+//#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 = useDefaultHotkeysOptions();
+	const manager = getHotkeyManager();
+	let registration = 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 = typeof resolvedHotkey === "string" ? resolvedHotkey : formatHotkey(rawHotkeyToParsedHotkey(resolvedHotkey, platform));
+		const finalTarget = resolvedTarget ?? (typeof document !== "undefined" ? document : null);
+		if (!finalTarget) return;
+		if (registration?.isActive) {
+			registration.unregister();
+			registration = null;
+		}
+		const { target: _target, enabled: _enabled, ...restOptions } = mergedOptions;
+		const optionsWithoutTarget = {
+			...restOptions,
+			...resolvedEnabled === void 0 ? {} : { enabled: resolvedEnabled }
+		};
+		registration = manager.register(hotkeyString, callback, {
+			...optionsWithoutTarget,
+			target: finalTarget
+		});
+		if (registration.isActive) {
+			registration.callback = callback;
+			registration.setOptions(optionsWithoutTarget);
+		}
+	}, { immediate: true });
+	onUnmounted(() => {
+		stopWatcher();
+		if (registration?.isActive) {
+			registration.unregister();
+			registration = null;
+		}
+	});
+}
+function resolveMaybeRefOrGetter(value) {
+	return typeof value === "function" ? value() : unref(value);
+}
+
+//#endregion
+export { useHotkey };
+//# sourceMappingURL=useHotkey.js.map

package/dist/useHotkey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkey.js","names":[],"sources":["../src/useHotkey.ts"],"sourcesContent":["import { onUnmounted, unref, watch } from 'vue'\nimport {\n  detectPlatform,\n  formatHotkey,\n  getHotkeyManager,\n  rawHotkeyToParsedHotkey,\n} from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProviderContext'\nimport type {\n  Hotkey,\n  HotkeyCallback,\n  HotkeyOptions,\n  HotkeyRegistrationHandle,\n  RegisterableHotkey,\n} from '@tanstack/hotkeys'\nimport type { MaybeRefOrGetter } from 'vue'\n\nexport interface UseHotkeyOptions extends Omit<\n  HotkeyOptions,\n  'enabled' | 'target'\n> {\n  /**\n   * Whether the hotkey is active.\n   * Can be a Ref, a getter function, or a boolean value.\n   * Defaults to true.\n   */\n  enabled?: MaybeRefOrGetter<boolean>\n  /**\n   * The DOM element to attach the event listener to.\n   * Can be a Ref, a getter function, direct DOM element, or null.\n   * Defaults to document.\n   */\n  target?: MaybeRefOrGetter<HTMLElement | Document | Window | null>\n}\n\n/**\n * Vue composable for registering a keyboard hotkey.\n *\n * Uses the singleton HotkeyManager for efficient event handling.\n * The callback receives both the keyboard event and a context object\n * containing the hotkey string and parsed hotkey.\n *\n * This composable automatically tracks reactive dependencies and updates\n * the registration when options or the callback change.\n *\n * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)\n * @param callback - The function to call when the hotkey is pressed\n * @param options - Options for the hotkey behavior\n *\n * @example\n * ```vue\n * <script setup>\n * import { ref } from 'vue'\n * import { useHotkey } from '@tanstack/vue-hotkeys'\n *\n * const count = ref(0)\n *\n * // Callback always has access to latest count value\n * useHotkey('Mod+S', (event, { hotkey }) => {\n *   console.log(`Save triggered, count is ${count.value}`)\n *   handleSave()\n * })\n * </script>\n * ```\n *\n * @example\n * ```vue\n * <script setup>\n * import { ref } from 'vue'\n * import { useHotkey } from '@tanstack/vue-hotkeys'\n *\n * const isOpen = ref(false)\n *\n * // enabled option is reactive\n * useHotkey('Escape', () => {\n *   isOpen.value = false\n * }, { enabled: isOpen })\n * </script>\n * ```\n *\n * @example\n * ```vue\n * <script setup>\n * import { ref } from 'vue'\n * import { useHotkey } from '@tanstack/vue-hotkeys'\n *\n * const editorRef = ref<HTMLDivElement | null>(null)\n *\n * // Scoped to a specific element\n * useHotkey('Mod+S', () => {\n *   save()\n * }, { target: editorRef })\n * </script>\n *\n * <template>\n *   <div ref=\"editorRef\">...</div>\n * </template>\n * ```\n */\nexport function useHotkey(\n  hotkey: MaybeRefOrGetter<RegisterableHotkey>,\n  callback: HotkeyCallback,\n  options: MaybeRefOrGetter<UseHotkeyOptions> = {},\n): void {\n  const defaultOptions = useDefaultHotkeysOptions()\n  const manager = getHotkeyManager()\n\n  let registration: HotkeyRegistrationHandle | null = null\n\n  // Watch for changes to reactive dependencies\n  const stopWatcher = watch(\n    () => {\n      const resolvedHotkey = resolveMaybeRefOrGetter(hotkey)\n      const resolvedOptions = resolveMaybeRefOrGetter(options)\n      const mergedOptions = {\n        ...defaultOptions.hotkey,\n        ...resolvedOptions,\n      } as UseHotkeyOptions\n      const resolvedEnabled =\n        mergedOptions.enabled === undefined\n          ? undefined\n          : resolveMaybeRefOrGetter(mergedOptions.enabled)\n      const resolvedTarget =\n        mergedOptions.target === undefined\n          ? undefined\n          : resolveMaybeRefOrGetter(mergedOptions.target)\n\n      return {\n        resolvedHotkey,\n        mergedOptions,\n        resolvedEnabled,\n        resolvedTarget,\n      }\n    },\n    ({ resolvedHotkey, mergedOptions, resolvedEnabled, resolvedTarget }) => {\n      // Normalize to hotkey string\n      const platform = mergedOptions.platform ?? detectPlatform()\n      const hotkeyString: Hotkey =\n        typeof resolvedHotkey === 'string'\n          ? resolvedHotkey\n          : (formatHotkey(\n              rawHotkeyToParsedHotkey(resolvedHotkey as any, platform),\n            ) as Hotkey)\n\n      // Resolve target\n      const finalTarget =\n        resolvedTarget ?? (typeof document !== 'undefined' ? document : null)\n\n      if (!finalTarget) {\n        return\n      }\n\n      // Unregister previous registration if it exists\n      if (registration?.isActive) {\n        registration.unregister()\n        registration = null\n      }\n\n      // Extract options without target (target is handled separately)\n      const {\n        target: _target,\n        enabled: _enabled,\n        ...restOptions\n      } = mergedOptions\n      const optionsWithoutTarget = {\n        ...restOptions,\n        ...(resolvedEnabled === undefined ? {} : { enabled: resolvedEnabled }),\n      }\n\n      // Register the hotkey\n      registration = manager.register(hotkeyString, callback, {\n        ...optionsWithoutTarget,\n        target: finalTarget,\n      })\n\n      // Update callback and options\n      if (registration.isActive) {\n        registration.callback = callback\n        registration.setOptions(optionsWithoutTarget)\n      }\n    },\n    { immediate: true },\n  )\n\n  // Cleanup on unmount\n  onUnmounted(() => {\n    stopWatcher()\n    if (registration?.isActive) {\n      registration.unregister()\n      registration = null\n    }\n  })\n}\n\nfunction resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {\n  return typeof value === 'function' ? (value as () => T)() : unref(value)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmGA,SAAgB,UACd,QACA,UACA,UAA8C,EAAE,EAC1C;CACN,MAAM,iBAAiB,0BAA0B;CACjD,MAAM,UAAU,kBAAkB;CAElC,IAAI,eAAgD;CAGpD,MAAM,cAAc,YACZ;EACJ,MAAM,iBAAiB,wBAAwB,OAAO;EACtD,MAAM,kBAAkB,wBAAwB,QAAQ;EACxD,MAAM,gBAAgB;GACpB,GAAG,eAAe;GAClB,GAAG;GACJ;AAUD,SAAO;GACL;GACA;GACA,iBAXA,cAAc,YAAY,SACtB,SACA,wBAAwB,cAAc,QAAQ;GAUlD,gBARA,cAAc,WAAW,SACrB,SACA,wBAAwB,cAAc,OAAO;GAOlD;KAEF,EAAE,gBAAgB,eAAe,iBAAiB,qBAAqB;EAEtE,MAAM,WAAW,cAAc,YAAY,gBAAgB;EAC3D,MAAM,eACJ,OAAO,mBAAmB,WACtB,iBACC,aACC,wBAAwB,gBAAuB,SAAS,CACzD;EAGP,MAAM,cACJ,mBAAmB,OAAO,aAAa,cAAc,WAAW;AAElE,MAAI,CAAC,YACH;AAIF,MAAI,cAAc,UAAU;AAC1B,gBAAa,YAAY;AACzB,kBAAe;;EAIjB,MAAM,EACJ,QAAQ,SACR,SAAS,UACT,GAAG,gBACD;EACJ,MAAM,uBAAuB;GAC3B,GAAG;GACH,GAAI,oBAAoB,SAAY,EAAE,GAAG,EAAE,SAAS,iBAAiB;GACtE;AAGD,iBAAe,QAAQ,SAAS,cAAc,UAAU;GACtD,GAAG;GACH,QAAQ;GACT,CAAC;AAGF,MAAI,aAAa,UAAU;AACzB,gBAAa,WAAW;AACxB,gBAAa,WAAW,qBAAqB;;IAGjD,EAAE,WAAW,MAAM,CACpB;AAGD,mBAAkB;AAChB,eAAa;AACb,MAAI,cAAc,UAAU;AAC1B,gBAAa,YAAY;AACzB,kBAAe;;GAEjB;;AAGJ,SAAS,wBAA2B,OAA+B;AACjE,QAAO,OAAO,UAAU,aAAc,OAAmB,GAAG,MAAM,MAAM"}

package/dist/useHotkeyRecorder.cjs

@@ -0,0 +1,80 @@
+const require_HotkeysProviderContext = require('./HotkeysProviderContext.cjs');
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let vue = require("vue");
+let _tanstack_vue_store = require("@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 = require_HotkeysProviderContext.useDefaultHotkeysOptions();
+	const recorder = new _tanstack_hotkeys.HotkeyRecorder(resolveRecorderOptions(options, defaultOptions));
+	const isRecording = (0, _tanstack_vue_store.useStore)(recorder.store, (state) => state.isRecording);
+	const recordedHotkey = (0, _tanstack_vue_store.useStore)(recorder.store, (state) => state.recordedHotkey);
+	const stopWatcher = (0, vue.watch)(() => resolveRecorderOptions(options, defaultOptions), (resolvedOptions) => {
+		recorder.setOptions(resolvedOptions);
+	}, { immediate: true });
+	(0, vue.onUnmounted)(() => {
+		stopWatcher();
+		recorder.destroy();
+	});
+	return {
+		isRecording,
+		recordedHotkey,
+		startRecording: () => recorder.start(),
+		stopRecording: () => recorder.stop(),
+		cancelRecording: () => recorder.cancel()
+	};
+}
+function resolveRecorderOptions(options, defaultOptions) {
+	return {
+		...defaultOptions.hotkeyRecorder,
+		...resolveMaybeRefOrGetter(options)
+	};
+}
+function resolveMaybeRefOrGetter(value) {
+	return typeof value === "function" ? value() : (0, vue.unref)(value);
+}
+
+//#endregion
+exports.useHotkeyRecorder = useHotkeyRecorder;
+//# sourceMappingURL=useHotkeyRecorder.cjs.map

package/dist/useHotkeyRecorder.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeyRecorder.cjs","names":["useDefaultHotkeysOptions","HotkeyRecorder"],"sources":["../src/useHotkeyRecorder.ts"],"sourcesContent":["import { onUnmounted, unref, watch } from 'vue'\nimport { useStore } from '@tanstack/vue-store'\nimport { HotkeyRecorder } from '@tanstack/hotkeys'\nimport { useDefaultHotkeysOptions } from './HotkeysProviderContext'\nimport type { MaybeRefOrGetter, Ref } from 'vue'\nimport type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys'\n\nexport interface VueHotkeyRecorder {\n  /** Whether recording is currently active */\n  isRecording: Ref<boolean>\n  /** The currently recorded hotkey (for live preview) */\n  recordedHotkey: Ref<Hotkey | null>\n  /** Start recording a new hotkey */\n  startRecording: () => void\n  /** Stop recording (same as cancel) */\n  stopRecording: () => void\n  /** Cancel recording without saving */\n  cancelRecording: () => void\n}\n\n/**\n * Vue composable for recording keyboard shortcuts.\n *\n * This composable provides a thin wrapper around the framework-agnostic `HotkeyRecorder`\n * class, managing all the complexity of capturing keyboard events, converting them\n * to hotkey strings, and handling edge cases like Escape to cancel or Backspace/Delete\n * to clear.\n *\n * @param options - Configuration options for the recorder\n * @returns An object with recording state and control functions\n *\n * @example\n * ```vue\n * <script setup>\n * import { ref } from 'vue'\n * import { useHotkeyRecorder } from '@tanstack/vue-hotkeys'\n *\n * const shortcut = ref<Hotkey>('Mod+S')\n *\n * const recorder = useHotkeyRecorder({\n *   onRecord: (hotkey) => {\n *     shortcut.value = hotkey\n *   },\n *   onCancel: () => {\n *     console.log('Recording cancelled')\n *   },\n * })\n * </script>\n *\n * <template>\n *   <div>\n *     <button @click=\"recorder.startRecording()\">\n *       {{ recorder.isRecording ? 'Recording...' : 'Edit Shortcut' }}\n *     </button>\n *     <div v-if=\"recorder.recordedHotkey\">\n *       Recording: {{ recorder.recordedHotkey }}\n *     </div>\n *   </div>\n * </template>\n * ```\n */\nexport function useHotkeyRecorder(\n  options: MaybeRefOrGetter<HotkeyRecorderOptions>,\n): VueHotkeyRecorder {\n  const defaultOptions = useDefaultHotkeysOptions()\n  const recorder = new HotkeyRecorder(\n    resolveRecorderOptions(options, defaultOptions),\n  )\n\n  // Subscribe to recorder state using useStore\n  const isRecording = useStore(recorder.store, (state) => state.isRecording)\n  const recordedHotkey = useStore(\n    recorder.store,\n    (state) => state.recordedHotkey,\n  )\n\n  const stopWatcher = watch(\n    () => resolveRecorderOptions(options, defaultOptions),\n    (resolvedOptions) => {\n      recorder.setOptions(resolvedOptions)\n    },\n    { immediate: true },\n  )\n\n  // Cleanup on unmount\n  onUnmounted(() => {\n    stopWatcher()\n    recorder.destroy()\n  })\n\n  return {\n    isRecording: isRecording as Ref<boolean>,\n    recordedHotkey: recordedHotkey as Ref<Hotkey | null>,\n    startRecording: () => recorder.start(),\n    stopRecording: () => recorder.stop(),\n    cancelRecording: () => recorder.cancel(),\n  }\n}\n\nfunction resolveRecorderOptions(\n  options: MaybeRefOrGetter<HotkeyRecorderOptions>,\n  defaultOptions: ReturnType<typeof useDefaultHotkeysOptions>,\n): HotkeyRecorderOptions {\n  return {\n    ...defaultOptions.hotkeyRecorder,\n    ...resolveMaybeRefOrGetter(options),\n  } as HotkeyRecorderOptions\n}\n\nfunction resolveMaybeRefOrGetter<T>(value: MaybeRefOrGetter<T>): T {\n  return typeof value === 'function' ? (value as () => T)() : unref(value)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,kBACd,SACmB;CACnB,MAAM,iBAAiBA,yDAA0B;CACjD,MAAM,WAAW,IAAIC,iCACnB,uBAAuB,SAAS,eAAe,CAChD;CAGD,MAAM,gDAAuB,SAAS,QAAQ,UAAU,MAAM,YAAY;CAC1E,MAAM,mDACJ,SAAS,QACR,UAAU,MAAM,eAClB;CAED,MAAM,mCACE,uBAAuB,SAAS,eAAe,GACpD,oBAAoB;AACnB,WAAS,WAAW,gBAAgB;IAEtC,EAAE,WAAW,MAAM,CACpB;AAGD,4BAAkB;AAChB,eAAa;AACb,WAAS,SAAS;GAClB;AAEF,QAAO;EACQ;EACG;EAChB,sBAAsB,SAAS,OAAO;EACtC,qBAAqB,SAAS,MAAM;EACpC,uBAAuB,SAAS,QAAQ;EACzC;;AAGH,SAAS,uBACP,SACA,gBACuB;AACvB,QAAO;EACL,GAAG,eAAe;EAClB,GAAG,wBAAwB,QAAQ;EACpC;;AAGH,SAAS,wBAA2B,OAA+B;AACjE,QAAO,OAAO,UAAU,aAAc,OAAmB,kBAAS,MAAM"}