@tanstack/vue-hotkeys 0.12.1 → 0.14.0

package/README.md

@@ -67,6 +67,9 @@ Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objec
 > [!NOTE]
 > You may know **TanStack Hotkeys** by our adapter names, too!
 >
+> - [**Alpine Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/alpine/quick-start)
+> - [**Ember Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/ember/quick-start)
+> - [**Octane Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/octane/quick-start)
 > - [**React Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/react/react-hotkeys)
 > - [**Preact Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/preact/preact-hotkeys)
 > - [**Solid Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/solid/reference)

package/dist/HotkeysProvider.d.ts

@@ -1,12 +1,20 @@
 import { HotkeysProviderOptions } from "./HotkeysProviderContext.js";
+import { AppHotkeys, CustomHotkeys } from "@tanstack/hotkeys";
+import { PropType } from "vue";
 //#region src/HotkeysProvider.d.ts
 /**
- * Vue component that provides default options for hotkeys context.
+ * 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.
  *
  * @example
  * ```vue
  * <template>
- *   <HotkeysProvider :defaultOptions="{ hotkey: { enabled: true } }">
+ *   <HotkeysProvider
+ *     :app-hotkeys="appHotkeys"
+ *     :custom-hotkeys="saved"
+ *     @custom-hotkeys-change="save"
+ *   >
  *     <App />
  *   </HotkeysProvider>
  * </template>
@@ -14,17 +22,39 @@ import { HotkeysProviderOptions } from "./HotkeysProviderContext.js";
  */
 export declare const HotkeysProvider: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
   defaultOptions: {
-    type: () => HotkeysProviderOptions;
+    type: PropType<HotkeysProviderOptions>;
+    default: undefined;
+  };
+  appHotkeys: {
+    type: PropType<AppHotkeys>;
+    default: undefined;
+  };
+  customHotkeys: {
+    type: PropType<CustomHotkeys | null>;
     default: undefined;
   };
 }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+  customHotkeysChange: (_customHotkeys: CustomHotkeys) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
   defaultOptions: {
-    type: () => HotkeysProviderOptions;
+    type: PropType<HotkeysProviderOptions>;
+    default: undefined;
+  };
+  appHotkeys: {
+    type: PropType<AppHotkeys>;
+    default: undefined;
+  };
+  customHotkeys: {
+    type: PropType<CustomHotkeys | null>;
     default: undefined;
   };
-}>> & Readonly<{}>, {
+}>> & Readonly<{
+  onCustomHotkeysChange?: ((_customHotkeys: CustomHotkeys<Readonly<Record<string, import("@tanstack/hotkeys").AppHotkey<string, import("@tanstack/hotkeys").HotkeyChord | import("@tanstack/hotkeys").HotkeySequence | null>>>>) => any) | 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;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 //#endregion

package/dist/HotkeysProvider.js

@@ -3,12 +3,18 @@ import { defineComponent } from "vue";
 
 //#region src/HotkeysProvider.tsx
 /**
-* Vue component that provides default options for hotkeys context.
+* 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.
 *
 * @example
 * ```vue
 * <template>
-*   <HotkeysProvider :defaultOptions="{ hotkey: { enabled: true } }">
+*   <HotkeysProvider
+*     :app-hotkeys="appHotkeys"
+*     :custom-hotkeys="saved"
+*     @custom-hotkeys-change="save"
+*   >
 *     <App />
 *   </HotkeysProvider>
 * </template>
@@ -16,12 +22,28 @@ import { defineComponent } from "vue";
 */
 const HotkeysProvider = defineComponent({
 	name: "HotkeysProvider",
-	props: { defaultOptions: {
-		type: Object,
-		default: void 0
-	} },
-	setup(props, { slots }) {
-		provideHotkeysContext(props.defaultOptions);
+	props: {
+		defaultOptions: {
+			type: Object,
+			default: void 0
+		},
+		appHotkeys: {
+			type: Object,
+			default: void 0
+		},
+		customHotkeys: {
+			type: Object,
+			default: void 0
+		}
+	},
+	emits: { customHotkeysChange: (_customHotkeys) => true },
+	setup(props, { slots, emit }) {
+		provideHotkeysContext({
+			defaultOptions: () => props.defaultOptions,
+			appHotkeys: () => props.appHotkeys,
+			customHotkeys: props.customHotkeys,
+			onCustomHotkeysChange: (custom) => emit("customHotkeysChange", custom)
+		});
 		return () => slots.default?.();
 	}
 });

package/dist/HotkeysProviderContext.d.ts

@@ -1,17 +1,52 @@
-import { UseHotkeyOptions } from "./useHotkey.js";
-import { UseHotkeySequenceOptions } from "./useHotkeySequence.js";
-import { HotkeyRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { UseHotkeyCommonOptions } from "./useHotkey.js";
+import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { MaybeRefOrGetter } from "vue";
 //#region src/HotkeysProviderContext.d.ts
 export interface HotkeysProviderOptions {
-  hotkey?: Partial<UseHotkeyOptions>;
-  hotkeyRecorder?: Partial<HotkeyRecorderOptions>;
-  hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>;
-  hotkeySequence?: Partial<UseHotkeySequenceOptions>;
+  /**
+   * Defaults for every hotkey registered by `useHotkey` and `useHotkeys`.
+   * `requireReset` applies to chords and `timeout` applies to sequences.
+   */
+  hotkey?: UseHotkeyCommonOptions;
+  /** Defaults for every `useHotkeyRecorder`. */
+  hotkeyRecorder?: Partial<Omit<HotkeyChordRecorderOptions & HotkeySequenceRecorderOptions, 'maxSteps' | 'onRecord' | 'validate'>>;
 }
 interface HotkeysContextValue {
-  defaultOptions: HotkeysProviderOptions;
+  readonly appHotkeysStore: AppHotkeysStore | null;
+  readonly defaultOptions: HotkeysProviderOptions;
 }
-export declare function provideHotkeysContext(defaultOptions?: HotkeysProviderOptions): void;
+/** Options for `provideHotkeysContext`. */
+export interface ProvideHotkeysContextOptions {
+  defaultOptions?: MaybeRefOrGetter<HotkeysProviderOptions | undefined>;
+  /**
+   * Every app hotkey, from `defineAppHotkeys`. Read when the context is
+   * provided; later changes update the declarations.
+   */
+  appHotkeys?: MaybeRefOrGetter<AppHotkeys | undefined>;
+  /**
+   * Starting custom hotkeys, such as saved data. Read once; the context owns
+   * the state afterwards. Invalid entries are ignored with a warning.
+   */
+  customHotkeys?: CustomHotkeys | null;
+  /** Called with the custom hotkeys after every change, ready to save. */
+  onCustomHotkeysChange?: (customHotkeys: CustomHotkeys) => void;
+}
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * provideHotkeysContext({
+ *   appHotkeys,
+ *   customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+ *   onCustomHotkeysChange: (custom) =>
+ *     localStorage.setItem('hotkeys', JSON.stringify(custom)),
+ * })
+ * ```
+ */
+export declare function provideHotkeysContext(options?: ProvideHotkeysContextOptions): void;
 export declare function useHotkeysContext(): HotkeysContextValue | null;
 export declare function useDefaultHotkeysOptions(): HotkeysProviderOptions;
 //#endregion

package/dist/HotkeysProviderContext.js

@@ -1,16 +1,48 @@
-import { inject, provide } from "vue";
+import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
+import { inject, onScopeDispose, provide, toValue, watch } from "vue";
 
 //#region src/HotkeysProviderContext.ts
 const HotkeysContext = Symbol("HotkeysContext");
 const DEFAULT_OPTIONS = {};
-function provideHotkeysContext(defaultOptions) {
-	provide(HotkeysContext, { defaultOptions: defaultOptions ?? 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.
+*
+* @example
+* ```ts
+* provideHotkeysContext({
+*   appHotkeys,
+*   customHotkeys: JSON.parse(localStorage.getItem('hotkeys') ?? '{}'),
+*   onCustomHotkeysChange: (custom) =>
+*     localStorage.setItem('hotkeys', JSON.stringify(custom)),
+* })
+* ```
+*/
+function provideHotkeysContext(options = {}) {
+	const appHotkeys = toValue(options.appHotkeys);
+	const store = appHotkeys ? new AppHotkeysStore(appHotkeys, {
+		customHotkeys: options.customHotkeys,
+		onCustomHotkeysChange: (custom) => options.onCustomHotkeysChange?.(custom)
+	}) : null;
+	if (store) {
+		watch(() => toValue(options.appHotkeys), (next) => {
+			if (next) store.setAppHotkeys(next);
+		});
+		if (typeof document !== "undefined") onScopeDispose(publishAppHotkeysStore(store));
+	}
+	provide(HotkeysContext, {
+		appHotkeysStore: store,
+		get defaultOptions() {
+			return toValue(options.defaultOptions) ?? DEFAULT_OPTIONS;
+		}
+	});
 }
 function useHotkeysContext() {
 	return inject(HotkeysContext, null);
 }
 function useDefaultHotkeysOptions() {
-	return inject(HotkeysContext, null)?.defaultOptions ?? {};
+	return inject(HotkeysContext, null)?.defaultOptions ?? DEFAULT_OPTIONS;
 }
 
 //#endregion

package/dist/defaultOptions.js

@@ -0,0 +1,24 @@
+import { useHotkeysContext } from "./HotkeysProviderContext.js";
+import { Store, useSelector } from "@tanstack/vue-store";
+
+//#region src/defaultOptions.ts
+/** Captures the context once and reads current defaults inside reactive computations. */
+function useDefaultHotkeysOptionsSource() {
+	const context = useHotkeysContext();
+	return () => context?.defaultOptions ?? {};
+}
+const NO_APP_HOTKEYS = new Store(null);
+/**
+* The provider's app hotkeys store and a ref that tracks its state, so
+* watchers re-run when app hotkeys or custom hotkeys change.
+*/
+function useAppHotkeysStoreSource() {
+	const store = useHotkeysContext()?.appHotkeysStore ?? null;
+	return {
+		store,
+		state: useSelector(store?.store ?? NO_APP_HOTKEYS, (value) => value)
+	};
+}
+
+//#endregion
+export { useAppHotkeysStoreSource, useDefaultHotkeysOptionsSource };

package/dist/index.d.ts

@@ -1,15 +1,13 @@
-import { UseHotkeyOptions, useHotkey } from "./useHotkey.js";
-import { UseHotkeySequenceOptions, useHotkeySequence } from "./useHotkeySequence.js";
-import { HotkeysProviderOptions, provideHotkeysContext, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProviderContext.js";
+import { UseAppHotkeyOptions, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, useHotkey } from "./useHotkey.js";
+import { HotkeysProviderOptions, ProvideHotkeysContextOptions, provideHotkeysContext, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProviderContext.js";
 import { HotkeysProvider } from "./HotkeysProvider.js";
 import { UseHotkeyDefinition, useHotkeys } from "./useHotkeys.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
-import { UseHotkeySequenceDefinition, useHotkeySequences } from "./useHotkeySequences.js";
 import { VueHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.js";
-import { HotkeyRegistrationsResult, useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
-import { VueHotkeySequenceRecorder, useHotkeySequenceRecorder } from "./useHotkeySequenceRecorder.js";
+import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
+import { UseCustomHotkeysResult, useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 export * from "@tanstack/hotkeys";
-export { HotkeyRegistrationsResult, HotkeysProvider, HotkeysProviderOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeySequenceDefinition, UseHotkeySequenceOptions, VueHotkeyRecorder, VueHotkeySequenceRecorder, provideHotkeysContext, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, ProvideHotkeysContextOptions, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, VueHotkeyRecorder, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.js

@@ -1,17 +1,15 @@
 import { provideHotkeysContext, useDefaultHotkeysOptions, useHotkeysContext } from "./HotkeysProviderContext.js";
 import { HotkeysProvider } from "./HotkeysProvider.js";
-import { useHotkey } from "./useHotkey.js";
 import { useHotkeys } from "./useHotkeys.js";
+import { useHotkey } from "./useHotkey.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
-import { useHotkeySequence } from "./useHotkeySequence.js";
-import { useHotkeySequences } from "./useHotkeySequences.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
-import { useHotkeySequenceRecorder } from "./useHotkeySequenceRecorder.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
+import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, provideHotkeysContext, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeySequence, useHotkeySequenceRecorder, useHotkeySequences, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, provideHotkeysContext, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/useAppHotkeys.d.ts

@@ -0,0 +1,43 @@
+import { AppHotkey, AppHotkeyListItem, CustomHotkeys, Hotkey, RegisteredAppHotkeys } from "@tanstack/hotkeys";
+import { ComputedRef } from "vue";
+//#region src/useAppHotkeys.d.ts
+/**
+ * Returns a computed ref of the effective app hotkeys from `HotkeysProvider`,
+ * typed by `Register`: each declaration with the user's custom hotkey applied.
+ *
+ * @example
+ * ```ts
+ * const hotkeys = useAppHotkeys()
+ * useHotkey(() => hotkeys.value['doc.save'], () => save())
+ * ```
+ */
+export declare function useAppHotkeys(): ComputedRef<RegisteredAppHotkeys>;
+/**
+ * Lists every app hotkey with its live status, in declaration order, for
+ * cheat sheets and settings screens. App hotkeys whose components have not
+ * mounted are `'inactive'`; those without a hotkey are `'unbound'`.
+ */
+export declare function useAppHotkeyList(): ComputedRef<Array<AppHotkeyListItem<RegisteredAppHotkeys[keyof RegisteredAppHotkeys]>>>;
+/** Custom hotkey state and actions returned by `useCustomHotkeys`. */
+export interface UseCustomHotkeysResult {
+  /** The user's hotkeys that differ from the defaults. */
+  customHotkeys: ComputedRef<CustomHotkeys>;
+  /**
+   * Sets the user's hotkey for an app hotkey. `null` unbinds it.
+   * Returns conflicting app hotkeys; when any exist, nothing changes.
+   */
+  setCustomHotkey: (id: keyof RegisteredAppHotkeys & string, hotkey: Hotkey | null) => Array<AppHotkey>;
+  /** Restores the default hotkey for an app hotkey. */
+  resetCustomHotkey: (id: keyof RegisteredAppHotkeys & string) => void;
+  /** Restores every default hotkey. */
+  resetCustomHotkeys: () => void;
+  /** Other app hotkeys that would collide if `id` used `hotkey`. */
+  findConflicts: (id: keyof RegisteredAppHotkeys & string, hotkey: Hotkey) => Array<AppHotkey>;
+}
+/**
+ * Reads and changes the user's custom hotkeys. Changes apply to every
+ * registered app hotkey immediately and are emitted by the provider as
+ * `custom-hotkeys-change`, ready to save.
+ */
+export declare function useCustomHotkeys(): UseCustomHotkeysResult;
+//#endregion

package/dist/useAppHotkeys.js

@@ -0,0 +1,64 @@
+import { useAppHotkeysStoreSource } from "./defaultOptions.js";
+import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
+import { computed } from "vue";
+
+//#region src/useAppHotkeys.ts
+function useRequiredStore(name) {
+	const source = useAppHotkeysStoreSource();
+	if (!source.store) throw new Error(`${name} requires a HotkeysProvider with app hotkeys`);
+	return {
+		store: source.store,
+		state: source.state
+	};
+}
+/**
+* Returns a computed ref of the effective app hotkeys from `HotkeysProvider`,
+* typed by `Register`: each declaration with the user's custom hotkey applied.
+*
+* @example
+* ```ts
+* const hotkeys = useAppHotkeys()
+* useHotkey(() => hotkeys.value['doc.save'], () => save())
+* ```
+*/
+function useAppHotkeys() {
+	const { store, state } = useRequiredStore("useAppHotkeys");
+	return computed(() => {
+		state.value;
+		return store.appHotkeys;
+	});
+}
+/**
+* Lists every app hotkey with its live status, in declaration order, for
+* cheat sheets and settings screens. App hotkeys whose components have not
+* mounted are `'inactive'`; those without a hotkey are `'unbound'`.
+*/
+function useAppHotkeyList() {
+	const { store, state } = useRequiredStore("useAppHotkeyList");
+	const registrations = useHotkeyRegistrations();
+	return computed(() => {
+		state.value;
+		return store.getList(registrations.value);
+	});
+}
+/**
+* Reads and changes the user's custom hotkeys. Changes apply to every
+* registered app hotkey immediately and are emitted by the provider as
+* `custom-hotkeys-change`, ready to save.
+*/
+function useCustomHotkeys() {
+	const { store, state } = useRequiredStore("useCustomHotkeys");
+	return {
+		customHotkeys: computed(() => {
+			state.value;
+			return store.customHotkeys;
+		}),
+		setCustomHotkey: (id, hotkey) => store.setCustomHotkey(id, hotkey),
+		resetCustomHotkey: (id) => store.resetCustomHotkey(id),
+		resetCustomHotkeys: () => store.resetCustomHotkeys(),
+		findConflicts: (id, hotkey) => store.findConflicts(id, hotkey)
+	};
+}
+
+//#endregion
+export { useAppHotkeyList, useAppHotkeys, useCustomHotkeys };

package/dist/useHotkey.d.ts

@@ -1,83 +1,46 @@
-import { HotkeyCallback, HotkeyOptions, RegisterableHotkey } from "@tanstack/hotkeys";
+import { AppHotkey, HotkeyCallback, 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
-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.
-   */
+/**
+ * The element to listen on: a ref, getter, element, or null. A target that
+ * resolves to `null` skips registration until it is set. Defaults to document.
+ */
+export type UseHotkeyTarget = MaybeRefOrGetter<Target | null>;
+/** Lets `enabled` be a ref or getter. */
+type WithReactiveEnabled<TOptions> = Omit<TOptions, 'enabled'> & {
+  /** Whether the hotkey is active. Can be a ref, getter, or boolean. 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>;
-}
+};
+/** Options shared by chords and sequences. */
+export type UseHotkeyOptions = WithReactiveEnabled<AdapterHotkeyOptions<UseHotkeyTarget>>;
+/** Options for a chord such as `'Mod+S'`. */
+export type UseHotkeyChordOptions = WithReactiveEnabled<AdapterChordOptions<UseHotkeyTarget>>;
+/** Options for a sequence such as `['G', 'G']`. */
+export type UseHotkeySequenceOptions = WithReactiveEnabled<AdapterSequenceOptions<UseHotkeyTarget>>;
+/** Options applied to every hotkey, such as provider defaults. Each applies to the kinds that support it. */
+export type UseHotkeyCommonOptions = WithReactiveEnabled<AdapterCommonOptions<UseHotkeyTarget>>;
+/** The options type for a hotkey: chord options for chords, sequence options for sequences. */
+export type UseHotkeyOptionsFor<T extends RegisterableHotkey> = WithReactiveEnabled<AdapterOptionsFor<T, UseHotkeyTarget>>;
+/** Call-site options for an app hotkey, typed by its declared default kind. */
+export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = WithReactiveEnabled<AdapterAppHotkeyOptions<T, UseHotkeyTarget>>;
 /**
- * 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
+ * Vue composable for registering a hotkey: a chord such as `'Mod+S'`, a
+ * sequence such as `['G', 'G']`, or an app hotkey from `defineAppHotkeys`.
+ * The hotkey and options may be refs or getters.
  *
- * @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>
- * ```
+ * Chords accept `requireReset`; sequences accept `timeout`. A one-step
+ * sequence registers as its chord. An app hotkey uses its effective hotkey
+ * from `HotkeysProvider` (including the user's custom hotkey) and its
+ * declared meta and options, and registers nothing while unbound.
  *
  * @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>
+ * ```ts
+ * useHotkey('Mod+S', () => save())
+ * useHotkey(['G', 'G'], () => scrollToTop(), { timeout: 500 })
+ * useHotkey('Escape', () => close(), { enabled: isOpen })
  * ```
  */
-export declare function useHotkey(hotkey: MaybeRefOrGetter<RegisterableHotkey>, callback: HotkeyCallback, options?: MaybeRefOrGetter<UseHotkeyOptions>): void;
+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;
 //#endregion