@tanstack/react-hotkeys 0.19.0 → 0.20.0

package/dist/HotkeysProvider.d.ts

@@ -27,8 +27,10 @@ export interface HotkeysProviderProps<T extends AppHotkeys = AppHotkeys> extends
    */
   appHotkeys?: T;
   /**
-   * Starting custom hotkeys, such as saved data. Read once; the provider 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<T> | null;
   /** Called with the custom hotkeys after every change, ready to save. */

package/dist/HotkeysProvider.js

@@ -60,8 +60,15 @@ function HotkeysProvider({ children, appHotkeys, customHotkeys, onCustomHotkeysC
 		return scopeKey ? activateHotkeysProviderScope(scopeKey) : void 0;
 	}, [scopeKey]);
 	useEffect(() => {
-		store?.setOptions({ onCustomHotkeysChange });
-	}, [store, onCustomHotkeysChange]);
+		store?.setOptions({
+			customHotkeys,
+			onCustomHotkeysChange
+		});
+	}, [
+		store,
+		customHotkeys,
+		onCustomHotkeysChange
+	]);
 	useEffect(() => {
 		if (appHotkeys) store?.setAppHotkeys(appHotkeys);
 	}, [store, appHotkeys]);

package/dist/useHotkey.d.ts

@@ -37,7 +37,8 @@ export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHot
  * Options merge in this order: provider defaults, app hotkey declaration,
  * call-site options.
  *
- * @param hotkey - A chord string, RawHotkeyChord object, sequence, or app hotkey
+ * @param hotkey - A chord string, RawHotkeyChord object, sequence, or app hotkey.
+ *   `undefined`, `null`, or `''` registers nothing, for an optional shortcut.
  * @param callback - The function to call when the hotkey is pressed
  * @param options - Options for the hotkey behavior
  *
@@ -60,6 +61,6 @@ export type UseAppHotkeyOptions<T extends AppHotkey = AppHotkey> = AdapterAppHot
  * }
  * ```
  */
-export declare function useHotkey<T extends AppHotkey>(hotkey: T, callback: HotkeyCallback, options?: UseAppHotkeyOptions<T>): void;
-export declare function useHotkey<const T extends RegisterableHotkey>(hotkey: T, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: UseHotkeyOptionsFor<T>): void;
+export declare function useHotkey<T extends AppHotkey>(hotkey: T | null | undefined, callback: HotkeyCallback, options?: UseAppHotkeyOptions<T>): void;
+export declare function useHotkey<const T extends RegisterableHotkey>(hotkey: T | null | undefined, callback: HotkeyCallback<HotkeyCallbackContextFor<T>>, options?: UseHotkeyOptionsFor<T>): void;
 //#endregion

package/dist/useHotkeyHint.d.ts

@@ -4,10 +4,11 @@ import { AppHotkey, HeldModifierOptions, RegisterableHotkey } from "@tanstack/ho
  * Returns a boolean indicating whether held modifiers reveal this shortcut.
  * The hint shows only while the hotkey can fire: some registration of it is
  * enabled and in an active scope. An app hotkey matches its registrations by
- * id and uses its effective hotkey (false while unbound).
+ * id and uses its effective hotkey (false while unbound). No hotkey
+ * (`undefined`, `null`, or `''`) returns false.
  * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact`
  * requires every modifier. A sequence reveals its hint from its first step.
  * Only visibility changes cause a rerender. This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.
  */
-export declare function useHotkeyHint(hotkey: RegisterableHotkey | AppHotkey, options?: HeldModifierOptions): boolean;
+export declare function useHotkeyHint(hotkey: RegisterableHotkey | AppHotkey | null | undefined, options?: HeldModifierOptions): boolean;
 //#endregion

package/dist/useHotkeyHint.js

@@ -9,7 +9,8 @@ import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers
 * Returns a boolean indicating whether held modifiers reveal this shortcut.
 * The hint shows only while the hotkey can fire: some registration of it is
 * enabled and in an active scope. An app hotkey matches its registrations by
-* id and uses its effective hotkey (false while unbound).
+* id and uses its effective hotkey (false while unbound). No hotkey
+* (`undefined`, `null`, or `''`) returns false.
 * Uses the nonempty-subset/AltGr rules of `matchesHeldModifiers`; `exact`
 * requires every modifier. A sequence reveals its hint from its first step.
 * Only visibility changes cause a rerender. This helper does not register a shortcut. A hotkey on an element counts only while focus is inside it.

package/dist/useHotkeyRecorder.js

@@ -4,13 +4,11 @@ import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
 import { useSelector } from "./_useSelector.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
 import { useEffect, useRef } from "react";
+import { withDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/useHotkeyRecorder.ts
 function useHotkeyRecorder(options) {
-	const mergedOptions = {
-		...useDefaultHotkeysOptions().hotkeyRecorder,
-		...options
-	};
+	const mergedOptions = withDefaults(useDefaultHotkeysOptions().hotkeyRecorder, options);
 	const recorderRef = useRef(null);
 	if (!recorderRef.current) recorderRef.current = new HotkeyRecorder(mergedOptions);
 	recorderRef.current.setOptions(mergedOptions);

package/dist/utils.js

@@ -6,11 +6,11 @@ function isRef(value) {
 	return value !== null && typeof value === "object" && "current" in value;
 }
 /**
-* Resolves a hook target. A ref that is still null skips registration;
-* a null target means document.
+* Resolves a hook target. A null target, or a ref that is still null, skips
+* registration. Omit the target to listen on the document.
 */
 function resolveTarget(target) {
-	return isRef(target) ? target.current : target ?? void 0;
+	return isRef(target) ? target.current : target;
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-hotkeys",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "React adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.20.0"
+    "@tanstack/hotkeys": "0.21.0"
   },
   "devDependencies": {
     "@eslint-react/eslint-plugin": "^4.2.3",

package/skills/react-hotkeys/SKILL.md

@@ -101,7 +101,7 @@ A hook uses the nearest `HotkeysProvider` above its component. Registering `Esca
 
 ## Pitfalls
 
-- **Pass the ref, not `ref.current`.** `target: listRef.current` is `null` on the first render, and a `null` target means `document`, so the hotkey works page-wide. Pass `target: listRef`; a ref that is still empty waits for its element.
+- **Pass the ref, not `ref.current`.** `target: listRef.current` is `null` on the first render, and a `null` target registers nothing, so the hotkey doesn't work until the component renders again. Pass `target: listRef`; a ref that is still empty waits for its element.
 - **No dependency arrays or `useCallback`.** The hooks read the hotkey, callback, and options on every render, so inline callbacks always see current state.
 - **Call the hooks directly.** A `useShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, options, app hotkeys, and the typed callback context.
 - **`matchesKeyboardEvent` takes the DOM event.** In a widget's `onKeyDown`, pass `event.nativeEvent`.