@tanstack/react-hotkeys 0.18.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

@@ -1,8 +1,8 @@
 'use client';
 
-import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
+import { publishAppHotkeysStore } from "@tanstack/hotkeys";
 import React, { createContext, useContext, useEffect, useMemo, useState } from "react";
-import { activateHotkeysProviderScope, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
+import { activateHotkeysProviderScope, createAppHotkeysStore, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/HotkeysProvider.tsx
 const HotkeysContext = createContext(null);
@@ -45,7 +45,7 @@ const NO_PARENT = {
 */
 function HotkeysProvider({ children, appHotkeys, customHotkeys, onCustomHotkeysChange, defaultOptions = DEFAULT_OPTIONS, scope, exclusive = false, enabled = true }) {
 	const parent = useContext(HotkeysContext) ?? NO_PARENT;
-	const [store] = useState(() => appHotkeys ? new AppHotkeysStore(appHotkeys, {
+	const [store] = useState(() => appHotkeys ? createAppHotkeysStore(appHotkeys, {
 		customHotkeys,
 		onCustomHotkeysChange
 	}) : null);
@@ -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/_appHotkeysStore.js

@@ -1,10 +1,11 @@
 'use client';
 
 import { useHotkeysContext } from "./HotkeysProvider.js";
-import { Store, useSelector } from "@tanstack/react-store";
+import { useSelector } from "./_useSelector.js";
+import { createStore } from "@tanstack/hotkeys/adapter";
 
 //#region src/_appHotkeysStore.ts
-const NO_APP_HOTKEYS = new Store(null);
+const NO_APP_HOTKEYS = createStore(null);
 /**
 * The provider's app hotkeys store, re-rendering when app hotkeys or custom
 * hotkeys change. Null outside a provider with `appHotkeys`.

package/dist/_useSelector.js

@@ -0,0 +1,29 @@
+'use client';
+
+import { useCallback, useRef, useSyncExternalStore } from "react";
+
+//#region src/_useSelector.ts
+/**
+* Subscribes to a store and returns the selected value, re-rendering when it
+* changes (by `Object.is`). The selector runs again only when the store's
+* state or the selector itself changes.
+*/
+function useSelector(store, selector) {
+	const subscribe = useCallback((onChange) => store.subscribe(onChange).unsubscribe, [store]);
+	const memo = useRef(null);
+	const getSelection = () => {
+		const state = store.get();
+		const last = memo.current;
+		if (last && last.selector === selector && Object.is(last.state, state)) return last.selected;
+		memo.current = {
+			state,
+			selector,
+			selected: selector(state)
+		};
+		return memo.current.selected;
+	};
+	return useSyncExternalStore(subscribe, getSelection, getSelection);
+}
+
+//#endregion
+export { useSelector };

package/dist/useHeldKeyCodes.js

@@ -1,7 +1,7 @@
 'use client';
 
+import { useSelector } from "./_useSelector.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/react-store";
 
 //#region src/useHeldKeyCodes.ts
 /**

package/dist/useHeldKeys.d.ts

@@ -2,8 +2,7 @@
 /**
  * React hook that returns an array of currently held keyboard keys.
  *
- * This hook uses `useSelector` from `@tanstack/react-store` to subscribe
- * to the global KeyStateTracker and updates whenever keys are pressed
+ * This hook subscribes to the global KeyStateTracker and updates whenever keys are pressed
  * or released.
  *
  * @returns Array of currently held key names

package/dist/useHeldKeys.js

@@ -1,14 +1,13 @@
 'use client';
 
+import { useSelector } from "./_useSelector.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/react-store";
 
 //#region src/useHeldKeys.ts
 /**
 * React hook that returns an array of currently held keyboard keys.
 *
-* This hook uses `useSelector` from `@tanstack/react-store` to subscribe
-* to the global KeyStateTracker and updates whenever keys are pressed
+* This hook subscribes to the global KeyStateTracker and updates whenever keys are pressed
 * or released.
 *
 * @returns Array of currently held key names

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

@@ -1,15 +1,16 @@
 'use client';
 
+import { useSelector } from "./_useSelector.js";
 import { useAppHotkeysStoreState } from "./_appHotkeysStore.js";
 import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/react-store";
 
 //#region src/useHotkeyHint.ts
 /**
 * 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

@@ -1,16 +1,14 @@
 'use client';
 
 import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { useSelector } from "./_useSelector.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
 import { useEffect, useRef } from "react";
-import { useSelector } from "@tanstack/react-store";
+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/useHotkeyRegistrations.js

@@ -1,7 +1,7 @@
 'use client';
 
+import { useSelector } from "./_useSelector.js";
 import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/react-store";
 
 //#region src/useHotkeyRegistrations.ts
 /**

package/dist/useHotkeyScopesState.js

@@ -1,7 +1,7 @@
 'use client';
 
+import { useSelector } from "./_useSelector.js";
 import { getHotkeyManager } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/react-store";
 
 //#region src/useHotkeyScopesState.ts
 /**

package/dist/useKeyHold.d.ts

@@ -3,8 +3,7 @@ import { IndividualKey } from "@tanstack/hotkeys";
 /**
  * React hook that returns whether a specific key is currently being held.
  *
- * This hook uses `useSelector` from `@tanstack/react-store` to subscribe
- * to the global KeyStateTracker and uses a selector to determine if
+ * This hook subscribes to the global KeyStateTracker and uses a selector to determine if
  * the specified key is held.
  *
  * @param key - The key to check (e.g., 'Shift', 'Control', 'A')

package/dist/useKeyHold.js

@@ -1,14 +1,13 @@
 'use client';
 
+import { useSelector } from "./_useSelector.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/react-store";
 
 //#region src/useKeyHold.ts
 /**
 * React hook that returns whether a specific key is currently being held.
 *
-* This hook uses `useSelector` from `@tanstack/react-store` to subscribe
-* to the global KeyStateTracker and uses a selector to determine if
+* This hook subscribes to the global KeyStateTracker and uses a selector to determine if
 * the specified key is held.
 *
 * @param key - The key to check (e.g., 'Shift', 'Control', 'A')

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.18.0",
+  "version": "0.20.0",
   "description": "React adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,11 +35,11 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.19.0",
-    "@tanstack/react-store": "^0.11.2"
+    "@tanstack/hotkeys": "0.21.0"
   },
   "devDependencies": {
     "@eslint-react/eslint-plugin": "^4.2.3",
+    "@tanstack/react-store": "^0.11.2",
     "@testing-library/react": "^16.3.3",
     "@types/react": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",

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`.