@tanstack/vue-hotkeys 0.14.5 → 0.15.0

package/README.md

@@ -51,7 +51,7 @@
 # TanStack Hotkeys
 
 > [!NOTE]
-> TanStack Hotkeys is alpha. We are actively developing the library and are open to feedback and contributions.
+> TanStack Hotkeys is in beta. We are actively developing the library and are open to feedback and contributions.
 
 Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objects, a cross-platform `Mod` key, a singleton Hotkey Manager, and utilities for cheatsheet UIs—built to stay SSR-friendly.
 

package/dist/HotkeysProvider.d.ts

@@ -1,12 +1,17 @@
 import { HotkeysProviderOptions } from "./HotkeysProviderContext.js";
 import { AppHotkeys, CustomHotkeys } from "@tanstack/hotkeys";
 import { PropType } from "vue";
+import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/HotkeysProvider.d.ts
 /**
  * Vue component that provides default options, app hotkeys, and the user's
  * custom hotkeys. `customHotkeys` is read once; listen to
  * `custom-hotkeys-change` to save changes.
  *
+ * Nest providers to create hotkey scopes. A nested provider inherits app
+ * hotkeys and merges default options. With `scope`, its hotkeys fire only
+ * while it is mounted and enabled; with `exclusive`, only its hotkeys fire.
+ *
  * @example
  * ```vue
  * <template>
@@ -19,6 +24,13 @@ import { PropType } from "vue";
  *   </HotkeysProvider>
  * </template>
  * ```
+ *
+ * @example
+ * ```vue
+ * <HotkeysProvider scope="edit-dialog" :exclusive="{ allow: ['global'] }">
+ *   <DialogBody />
+ * </HotkeysProvider>
+ * ```
  */
 export declare const HotkeysProvider: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
   defaultOptions: {
@@ -33,6 +45,21 @@ export declare const HotkeysProvider: import("vue").DefineComponent<import("vue"
     type: PropType<CustomHotkeys | null>;
     default: undefined;
   };
+  /** See `HotkeysProviderScopeProps['scope']`. */
+  scope: {
+    type: StringConstructor;
+    default: undefined;
+  };
+  /** See `HotkeysProviderScopeProps['exclusive']`. */
+  exclusive: {
+    type: PropType<HotkeysProviderScopeProps["exclusive"]>;
+    default: boolean;
+  };
+  /** See `HotkeysProviderScopeProps['enabled']`. */
+  enabled: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
 }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
   [key: string]: any;
 }>[] | undefined, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
@@ -50,11 +77,31 @@ export declare const HotkeysProvider: import("vue").DefineComponent<import("vue"
     type: PropType<CustomHotkeys | null>;
     default: undefined;
   };
+  /** See `HotkeysProviderScopeProps['scope']`. */
+  scope: {
+    type: StringConstructor;
+    default: undefined;
+  };
+  /** See `HotkeysProviderScopeProps['exclusive']`. */
+  exclusive: {
+    type: PropType<HotkeysProviderScopeProps["exclusive"]>;
+    default: boolean;
+  };
+  /** See `HotkeysProviderScopeProps['enabled']`. */
+  enabled: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
 }>> & Readonly<{
   onCustomHotkeysChange?: ((_customHotkeys: CustomHotkeys<Readonly<Record<string, import("@tanstack/hotkeys").AppHotkey<string, import("@tanstack/hotkeys").HotkeyChord | import("@tanstack/hotkeys").HotkeySequence | null>>>>) => any) | undefined;
 }>, {
+  exclusive: boolean | {
+    allow: ReadonlyArray<string>;
+  } | undefined;
   defaultOptions: HotkeysProviderOptions;
   appHotkeys: Readonly<Record<string, import("@tanstack/hotkeys").AppHotkey<string, import("@tanstack/hotkeys").HotkeyChord | import("@tanstack/hotkeys").HotkeySequence | null>>>;
   customHotkeys: CustomHotkeys<Readonly<Record<string, import("@tanstack/hotkeys").AppHotkey<string, import("@tanstack/hotkeys").HotkeyChord | import("@tanstack/hotkeys").HotkeySequence | null>>>> | null;
+  scope: string;
+  enabled: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 //#endregion

package/dist/HotkeysProvider.js

@@ -7,6 +7,10 @@ import { defineComponent } from "vue";
 * custom hotkeys. `customHotkeys` is read once; listen to
 * `custom-hotkeys-change` to save changes.
 *
+* Nest providers to create hotkey scopes. A nested provider inherits app
+* hotkeys and merges default options. With `scope`, its hotkeys fire only
+* while it is mounted and enabled; with `exclusive`, only its hotkeys fire.
+*
 * @example
 * ```vue
 * <template>
@@ -19,6 +23,13 @@ import { defineComponent } from "vue";
 *   </HotkeysProvider>
 * </template>
 * ```
+*
+* @example
+* ```vue
+* <HotkeysProvider scope="edit-dialog" :exclusive="{ allow: ['global'] }">
+*   <DialogBody />
+* </HotkeysProvider>
+* ```
 */
 const HotkeysProvider = defineComponent({
 	name: "HotkeysProvider",
@@ -34,6 +45,21 @@ const HotkeysProvider = defineComponent({
 		customHotkeys: {
 			type: Object,
 			default: void 0
+		},
+		/** See `HotkeysProviderScopeProps['scope']`. */
+		scope: {
+			type: String,
+			default: void 0
+		},
+		/** See `HotkeysProviderScopeProps['exclusive']`. */
+		exclusive: {
+			type: [Boolean, Object],
+			default: false
+		},
+		/** See `HotkeysProviderScopeProps['enabled']`. */
+		enabled: {
+			type: Boolean,
+			default: true
 		}
 	},
 	emits: { customHotkeysChange: (_customHotkeys) => true },
@@ -42,6 +68,9 @@ const HotkeysProvider = defineComponent({
 			defaultOptions: () => props.defaultOptions,
 			appHotkeys: () => props.appHotkeys,
 			customHotkeys: props.customHotkeys,
+			scope: () => props.scope,
+			exclusive: () => props.exclusive,
+			enabled: () => props.enabled,
 			onCustomHotkeysChange: (custom) => emit("customHotkeysChange", custom)
 		});
 		return () => slots.default?.();

package/dist/HotkeysProviderContext.d.ts

@@ -1,6 +1,7 @@
 import { UseHotkeyCommonOptions } from "./useHotkey.js";
 import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import { MaybeRefOrGetter } from "vue";
+import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/HotkeysProviderContext.d.ts
 export interface HotkeysProviderOptions {
   /**
@@ -13,11 +14,21 @@ export interface HotkeysProviderOptions {
 }
 interface HotkeysContextValue {
   readonly appHotkeysStore: AppHotkeysStore | null;
+  /** Merged with every ancestor's defaults, including `hotkey.scope`. */
   readonly defaultOptions: HotkeysProviderOptions;
+  /** Whether this context and every ancestor are enabled. */
+  readonly enabled: boolean;
 }
 /** Options for `provideHotkeysContext`. */
 export interface ProvideHotkeysContextOptions {
+  /** Merged with the parent context's defaults. */
   defaultOptions?: MaybeRefOrGetter<HotkeysProviderOptions | undefined>;
+  /** See `HotkeysProviderScopeProps['scope']`. */
+  scope?: MaybeRefOrGetter<HotkeysProviderScopeProps['scope']>;
+  /** See `HotkeysProviderScopeProps['exclusive']`. */
+  exclusive?: MaybeRefOrGetter<HotkeysProviderScopeProps['exclusive']>;
+  /** See `HotkeysProviderScopeProps['enabled']`. */
+  enabled?: MaybeRefOrGetter<HotkeysProviderScopeProps['enabled']>;
   /**
    * Every app hotkey, from `defineAppHotkeys`. Read when the context is
    * provided; later changes update the declarations.
@@ -33,8 +44,13 @@ export interface ProvideHotkeysContextOptions {
 }
 /**
  * Provides default options, app hotkeys, and the user's custom hotkeys to
- * descendants. `HotkeysProvider` calls this; call it directly in a root
- * component's setup instead of rendering the provider.
+ * descendants. `HotkeysProvider` calls this; call it directly in a component's
+ * setup instead of rendering the provider.
+ *
+ * Nest contexts to create hotkey scopes. A nested context inherits app
+ * hotkeys and merges default options. With `scope`, its hotkeys fire only
+ * while the component is mounted and enabled; with `exclusive`, only its
+ * hotkeys fire.
  *
  * @example
  * ```ts

package/dist/HotkeysProviderContext.js

@@ -1,13 +1,19 @@
 import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
-import { inject, onScopeDispose, provide, toValue, watch } from "vue";
+import { computed, inject, onMounted, onScopeDispose, provide, toValue, watch } from "vue";
+import { activateHotkeysProviderScope, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/HotkeysProviderContext.ts
 const HotkeysContext = Symbol("HotkeysContext");
 const DEFAULT_OPTIONS = {};
 /**
 * Provides default options, app hotkeys, and the user's custom hotkeys to
-* descendants. `HotkeysProvider` calls this; call it directly in a root
-* component's setup instead of rendering the provider.
+* descendants. `HotkeysProvider` calls this; call it directly in a component's
+* setup instead of rendering the provider.
+*
+* Nest contexts to create hotkey scopes. A nested context inherits app
+* hotkeys and merges default options. With `scope`, its hotkeys fire only
+* while the component is mounted and enabled; with `exclusive`, only its
+* hotkeys fire.
 *
 * @example
 * ```ts
@@ -20,6 +26,7 @@ const DEFAULT_OPTIONS = {};
 * ```
 */
 function provideHotkeysContext(options = {}) {
+	const parent = inject(HotkeysContext, null);
 	const appHotkeys = toValue(options.appHotkeys);
 	const store = appHotkeys ? new AppHotkeysStore(appHotkeys, {
 		customHotkeys: options.customHotkeys,
@@ -31,12 +38,29 @@ function provideHotkeysContext(options = {}) {
 		});
 		if (typeof document !== "undefined") onScopeDispose(publishAppHotkeysStore(store));
 	}
-	provide(HotkeysContext, {
-		appHotkeysStore: store,
+	const active = computed(() => (parent?.enabled ?? true) && toValue(options.enabled) !== false);
+	const defaultOptions = computed(() => mergeHotkeysProviderDefaults(parent?.defaultOptions, toValue(options.defaultOptions), toValue(options.scope)));
+	const scopeKey = computed(() => getHotkeysProviderScopeKey({
+		scope: toValue(options.scope),
+		exclusive: toValue(options.exclusive),
+		active: active.value,
+		parent: parent?.defaultOptions.hotkey?.scope
+	}));
+	onMounted(() => {
+		watch(scopeKey, (key, _, onCleanup) => {
+			if (key) onCleanup(activateHotkeysProviderScope(key));
+		}, { immediate: true });
+	});
+	const contextValue = {
+		appHotkeysStore: store ?? parent?.appHotkeysStore ?? null,
 		get defaultOptions() {
-			return toValue(options.defaultOptions) ?? DEFAULT_OPTIONS;
+			return defaultOptions.value;
+		},
+		get enabled() {
+			return active.value;
 		}
-	});
+	};
+	provide(HotkeysContext, contextValue);
 }
 function useHotkeysContext() {
 	return inject(HotkeysContext, null);

package/dist/useAppHotkeys.d.ts

@@ -7,8 +7,8 @@ import { ComputedRef } from "vue";
  *
  * @example
  * ```ts
- * const hotkeys = useAppHotkeys()
- * useHotkey(() => hotkeys.value['doc.save'], () => save())
+ * const appHotkeys = useAppHotkeys()
+ * useHotkey(() => appHotkeys.value['doc.save'], () => save())
  * ```
  */
 export declare function useAppHotkeys(): ComputedRef<RegisteredAppHotkeys>;

package/dist/useAppHotkeys.js

@@ -17,8 +17,8 @@ function useRequiredStore(name) {
 *
 * @example
 * ```ts
-* const hotkeys = useAppHotkeys()
-* useHotkey(() => hotkeys.value['doc.save'], () => save())
+* const appHotkeys = useAppHotkeys()
+* useHotkey(() => appHotkeys.value['doc.save'], () => save())
 * ```
 */
 function useAppHotkeys() {

package/dist/useHotkey.d.ts

@@ -1,4 +1,4 @@
-import { AppHotkey, HotkeyCallback, RegisterableHotkey, Target } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, HotkeyCallbackContextFor, RegisterableHotkey, Target } from "@tanstack/hotkeys";
 import { MaybeRefOrGetter } from "vue";
 import { AdapterAppHotkeyOptions, AdapterChordOptions, AdapterCommonOptions, AdapterHotkeyOptions, AdapterOptionsFor, AdapterSequenceOptions } from "@tanstack/hotkeys/adapter";
 //#region src/useHotkey.d.ts
@@ -42,5 +42,5 @@ export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = WithReactiveE
  * ```
  */
 export declare function useHotkey<T extends AppHotkey>(hotkey: MaybeRefOrGetter<T>, callback: HotkeyCallback, options?: MaybeRefOrGetter<UseAppHotkeyOptions<T>>): void;
-export declare function useHotkey<T extends RegisterableHotkey>(hotkey: MaybeRefOrGetter<T>, callback: HotkeyCallback, options?: MaybeRefOrGetter<UseHotkeyOptionsFor<T>>): void;
+export declare function useHotkey<const T extends RegisterableHotkey>(hotkey: MaybeRefOrGetter<T>, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: MaybeRefOrGetter<UseHotkeyOptionsFor<T>>): void;
 //#endregion

package/dist/useHotkeyRecorder.d.ts

@@ -28,7 +28,7 @@ export interface VueHotkeyRecorder<THotkey extends Hotkey = Hotkey> {
  * @example
  * ```ts
  * const recorder = useHotkeyRecorder({ onRecord: (hotkey) => (shortcut.value = hotkey) })
- * const sequenceRecorder = useHotkeyRecorder({ maxSteps: 3, onRecord: save })
+ * const sequenceRecorder = useHotkeyRecorder({ maxSteps: Infinity, onRecord: save })
  * ```
  */
 export declare function useHotkeyRecorder(options: HotkeyChordRecorderOptions): VueHotkeyRecorder<HotkeyChord>;

package/dist/useHotkeys.d.ts

@@ -1,5 +1,5 @@
 import { UseAppHotkeyOptions, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyOptions, UseHotkeySequenceOptions } from "./useHotkey.js";
-import { AppHotkey, HotkeyCallback, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "@tanstack/hotkeys";
 import { MaybeRefOrGetter } from "vue";
 //#region src/useHotkeys.d.ts
 /**
@@ -8,15 +8,15 @@ import { MaybeRefOrGetter } from "vue";
  * kind accept only shared options.
  */
 export type UseHotkeyDefinition = {
-  /** A chord string such as `'Mod+S'`, or a RawHotkey object */
+  /** A chord string such as `'Mod+S'`, or a chord 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>;
+  /** A sequence such as `['G', 'G']`, with each step a string or an object */
+  hotkey: MaybeRefOrGetter<RegisterableHotkeySequence>;
   callback: HotkeyCallback;
   options?: MaybeRefOrGetter<UseHotkeySequenceOptions>;
 } | {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/vue-hotkeys",
-  "version": "0.14.5",
+  "version": "0.15.0",
   "description": "Vue adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -36,7 +36,7 @@
     "dist"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.15.1",
+    "@tanstack/hotkeys": "0.16.0",
     "@tanstack/vue-store": "^0.11.2"
   },
   "devDependencies": {