@tanstack/preact-hotkeys 0.17.1 → 0.19.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,7 +1,7 @@
-import { AppHotkeysStore, publishAppHotkeysStore } from "@tanstack/hotkeys";
+import { publishAppHotkeysStore } from "@tanstack/hotkeys";
 import { createContext } from "preact";
 import { useContext, useEffect, useMemo, useState } from "preact/hooks";
-import { activateHotkeysProviderScope, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
+import { activateHotkeysProviderScope, createAppHotkeysStore, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 import { jsx } from "preact/jsx-runtime";
 
 //#region src/HotkeysProvider.tsx
@@ -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,8 +1,9 @@
 import { useHotkeysContext } from "./HotkeysProvider.js";
-import { Store, useSelector } from "@tanstack/preact-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,54 @@
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "preact/hooks";
+
+//#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. Preact 10 has no
+* `useSyncExternalStore` outside `preact/compat`, so this follows its approach.
+*/
+function useSelector(store, selector) {
+	const select = useMemo(() => {
+		let memo;
+		return (state) => {
+			if (!memo || !Object.is(memo.state, state)) memo = {
+				state,
+				selected: selector(state)
+			};
+			return memo.selected;
+		};
+	}, [selector]);
+	const selected = useRef(void 0);
+	const getSelection = () => {
+		const next = select(store.get());
+		if (!Object.is(selected.current, next)) selected.current = next;
+		return selected.current;
+	};
+	const value = getSelection();
+	const [{ instance }, forceUpdate] = useState({ instance: {
+		value,
+		getSelection
+	} });
+	const changed = () => {
+		try {
+			return !Object.is(instance.value, instance.getSelection());
+		} catch {
+			return true;
+		}
+	};
+	useLayoutEffect(() => {
+		instance.value = value;
+		instance.getSelection = getSelection;
+		if (changed()) forceUpdate({ instance });
+	});
+	useEffect(() => {
+		if (changed()) forceUpdate({ instance });
+		return store.subscribe(() => {
+			if (changed()) forceUpdate({ instance });
+		}).unsubscribe;
+	}, [instance, store]);
+	return value;
+}
+
+//#endregion
+export { useSelector };

package/dist/useHeldKeyCodes.js

@@ -1,5 +1,5 @@
+import { useSelector } from "./_useSelector.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/preact-store";
 
 //#region src/useHeldKeyCodes.ts
 /**

package/dist/useHeldKeys.d.ts

@@ -2,8 +2,7 @@
 /**
  * Preact hook that returns an array of currently held keyboard keys.
  *
- * This hook uses `useSelector` from `@tanstack/preact-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,12 +1,11 @@
+import { useSelector } from "./_useSelector.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/preact-store";
 
 //#region src/useHeldKeys.ts
 /**
 * Preact hook that returns an array of currently held keyboard keys.
 *
-* This hook uses `useSelector` from `@tanstack/preact-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

@@ -38,7 +38,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
  *
@@ -61,6 +62,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,13 +1,14 @@
+import { useSelector } from "./_useSelector.js";
 import { useAppHotkeysStoreState } from "./_appHotkeysStore.js";
 import { getHotkeyManager, getKeyStateTracker, isAppHotkey, matchesHeldModifiers, resolveAppHotkey } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/preact-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,14 +1,12 @@
 import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { useSelector } from "./_useSelector.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
 import { useEffect, useRef } from "preact/hooks";
-import { useSelector } from "@tanstack/preact-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,5 +1,5 @@
+import { useSelector } from "./_useSelector.js";
 import { getHotkeyManager, toHotkeyRegistrationView } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/preact-store";
 
 //#region src/useHotkeyRegistrations.ts
 /**

package/dist/useHotkeyScopesState.js

@@ -1,5 +1,5 @@
+import { useSelector } from "./_useSelector.js";
 import { getHotkeyManager } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/preact-store";
 
 //#region src/useHotkeyScopesState.ts
 /**

package/dist/useKeyHold.d.ts

@@ -3,8 +3,7 @@ import { IndividualKey } from "@tanstack/hotkeys";
 /**
  * Preact hook that returns whether a specific key is currently being held.
  *
- * This hook uses `useSelector` from `@tanstack/preact-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,12 +1,11 @@
+import { useSelector } from "./_useSelector.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { useSelector } from "@tanstack/preact-store";
 
 //#region src/useKeyHold.ts
 /**
 * Preact hook that returns whether a specific key is currently being held.
 *
-* This hook uses `useSelector` from `@tanstack/preact-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/preact-hotkeys",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "Preact adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,8 +35,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.19.0",
-    "@tanstack/preact-store": "^0.13.5"
+    "@tanstack/hotkeys": "0.21.0"
   },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.6",

package/skills/preact-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.
 - **In tests,** set `<HotkeysProvider defaultOptions={{ hotkey: { platform: 'mac' } }}>`.