@tanstack/vue-hotkeys 0.18.0 → 0.19.0

package/dist/HotkeysProvider.d.ts

@@ -5,8 +5,9 @@ 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.
+ * custom hotkeys. A new `customHotkeys` value replaces the current custom
+ * hotkeys, `undefined` leaves them unchanged, and `null` clears them. 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

package/dist/HotkeysProvider.js

@@ -4,8 +4,9 @@ import { defineComponent } from "vue";
 //#region src/HotkeysProvider.tsx
 /**
 * 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.
+* custom hotkeys. A new `customHotkeys` value replaces the current custom
+* hotkeys, `undefined` leaves them unchanged, and `null` clears them. 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
@@ -67,7 +68,7 @@ const HotkeysProvider = defineComponent({
 		provideHotkeysContext({
 			defaultOptions: () => props.defaultOptions,
 			appHotkeys: () => props.appHotkeys,
-			customHotkeys: props.customHotkeys,
+			customHotkeys: () => props.customHotkeys,
 			scope: () => props.scope,
 			exclusive: () => props.exclusive,
 			enabled: () => props.enabled,

package/dist/HotkeysProviderContext.d.ts

@@ -35,10 +35,12 @@ export interface ProvideHotkeysContextOptions {
    */
   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.
+   * The user's saved custom hotkeys. When the value changes, such as after
+   * saved data loads or the user signs in, it replaces the current custom
+   * hotkeys. `undefined` leaves them unchanged; `null` clears them. Invalid
+   * entries are ignored with a warning.
    */
-  customHotkeys?: CustomHotkeys | null;
+  customHotkeys?: MaybeRefOrGetter<CustomHotkeys | null | undefined>;
   /** Called with the custom hotkeys after every change, ready to save. */
   onCustomHotkeysChange?: (customHotkeys: CustomHotkeys) => void;
 }

package/dist/HotkeysProviderContext.js

@@ -29,13 +29,14 @@ function provideHotkeysContext(options = {}) {
 	const parent = inject(HotkeysContext, null);
 	const appHotkeys = toValue(options.appHotkeys);
 	const store = appHotkeys ? createAppHotkeysStore(appHotkeys, {
-		customHotkeys: options.customHotkeys,
+		customHotkeys: toValue(options.customHotkeys),
 		onCustomHotkeysChange: (custom) => options.onCustomHotkeysChange?.(custom)
 	}) : null;
 	if (store) {
 		watch(() => toValue(options.appHotkeys), (next) => {
 			if (next) store.setAppHotkeys(next);
 		});
+		watch(() => toValue(options.customHotkeys), (customHotkeys) => store.setOptions({ customHotkeys }), { deep: true });
 		if (typeof document !== "undefined") onScopeDispose(publishAppHotkeysStore(store));
 	}
 	const active = computed(() => (parent?.enabled ?? true) && toValue(options.enabled) !== false);

package/dist/useHotkey.d.ts

@@ -33,6 +33,7 @@ export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = WithReactiveE
  * 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.
+ * `undefined`, `null`, or `''` registers nothing, for an optional shortcut.
  *
  * @example
  * ```ts
@@ -41,6 +42,6 @@ export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = WithReactiveE
  * useHotkey('Escape', () => close(), { enabled: isOpen })
  * ```
  */
-export declare function useHotkey<T extends AppHotkey>(hotkey: MaybeRefOrGetter<T>, callback: HotkeyCallback, options?: MaybeRefOrGetter<UseAppHotkeyOptions<T>>): void;
-export declare function useHotkey<const T extends RegisterableHotkey>(hotkey: MaybeRefOrGetter<T>, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: MaybeRefOrGetter<UseHotkeyOptionsFor<T>>): void;
+export declare function useHotkey<T extends AppHotkey>(hotkey: MaybeRefOrGetter<T | null | undefined>, callback: HotkeyCallback, options?: MaybeRefOrGetter<UseAppHotkeyOptions<T>>): void;
+export declare function useHotkey<const T extends RegisterableHotkey>(hotkey: MaybeRefOrGetter<T | null | undefined>, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: MaybeRefOrGetter<UseHotkeyOptionsFor<T>>): void;
 //#endregion

package/dist/useHotkeyHint.d.ts

@@ -7,7 +7,8 @@ import { ComputedRef, MaybeRefOrGetter } from "vue";
  * enabled and in an active scope. Pass refs or getters to track changing
  * hotkeys and options. A sequence reveals its hint from its first step, and
  * an app hotkey matches its registrations by id and uses its effective hotkey
- * (false while unbound). This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
+ * (false while unbound). No hotkey (`undefined`, `null`, or `''`) returns
+ * false. This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
  */
-export declare function useHotkeyHint(hotkey: MaybeRefOrGetter<RegisterableHotkey | AppHotkey>, options?: MaybeRefOrGetter<HeldModifierOptions>): ComputedRef<boolean>;
+export declare function useHotkeyHint(hotkey: MaybeRefOrGetter<RegisterableHotkey | AppHotkey | null | undefined>, options?: MaybeRefOrGetter<HeldModifierOptions>): ComputedRef<boolean>;
 //#endregion

package/dist/useHotkeyHint.js

@@ -10,7 +10,8 @@ import { computed, toValue } from "vue";
 * enabled and in an active scope. Pass refs or getters to track changing
 * hotkeys and options. A sequence reveals its hint from its first step, and
 * an app hotkey matches its registrations by id and uses its effective hotkey
-* (false while unbound). This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
+* (false while unbound). No hotkey (`undefined`, `null`, or `''`) returns
+* false. This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
 */
 function useHotkeyHint(hotkey, options = {}) {
 	const appHotkeys = useAppHotkeysStoreSource();

package/dist/useHotkeyRecorder.js

@@ -2,14 +2,12 @@ import { useStoreSelector } from "./useStoreSelector.js";
 import { useDefaultHotkeysOptionsSource } from "./defaultOptions.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
 import { onScopeDispose, toValue, watch } from "vue";
+import { withDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/useHotkeyRecorder.ts
 function useHotkeyRecorder(options) {
 	const defaultOptions = useDefaultHotkeysOptionsSource();
-	const resolve = () => ({
-		...defaultOptions().hotkeyRecorder,
-		...toValue(options)
-	});
+	const resolve = () => withDefaults(defaultOptions().hotkeyRecorder, toValue(options));
 	const recorder = new HotkeyRecorder(resolve());
 	const isRecording = useStoreSelector(recorder.store, (state) => state.isRecording);
 	const steps = useStoreSelector(recorder.store, (state) => state.steps);

package/dist/useHotkeys.d.ts

@@ -25,8 +25,11 @@ export type UseHotkeyDefinition = {
   callback: HotkeyCallback;
   options?: MaybeRefOrGetter<UseAppHotkeyOptions>;
 } | {
-  /** A hotkey whose kind is not known statically. Accepts only shared options. */
-  hotkey: MaybeRefOrGetter<RegisterableHotkey>;
+  /**
+   * A hotkey whose kind is not known statically. Accepts only shared
+   * options. `undefined`, `null`, or `''` registers nothing.
+   */
+  hotkey: MaybeRefOrGetter<RegisterableHotkey | null | undefined>;
   callback: HotkeyCallback;
   options?: MaybeRefOrGetter<UseHotkeyOptions>;
 };
@@ -36,7 +39,8 @@ export type UseHotkeyDefinition = {
  *
  * 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.
+ * that support it. Unbound app hotkeys, empty sequences, and `undefined`,
+ * `null`, or `''` hotkeys register nothing.
  * A target that resolves to `null` skips registration until it is set.
  *
  * @example

package/dist/useHotkeys.js

@@ -18,7 +18,8 @@ function resolveEnabled(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.
+* that support it. Unbound app hotkeys, empty sequences, and `undefined`,
+* `null`, or `''` hotkeys register nothing.
 * A target that resolves to `null` skips registration until it is set.
 *
 * @example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/vue-hotkeys",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Vue adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.20.0"
+    "@tanstack/hotkeys": "0.21.0"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.9",