@tanstack/preact-hotkeys 0.19.1 → 0.20.0

package/dist/HotkeysProvider.d.ts

@@ -1,9 +1,15 @@
 import { UseHotkeyCommonOptions } from "./useHotkey.js";
-import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeyPlatform, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import { ComponentChildren } from "preact";
 import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/HotkeysProvider.d.ts
 export interface HotkeysProviderOptions {
+  /**
+   * The user's platform, for labels from `useFormatForDisplay`, hotkeys, and
+   * recorders. Defaults to detection. When server rendering, set it from the
+   * request with `detectPlatform(userAgent)`.
+   */
+  platform?: HotkeyPlatform;
   /**
    * Defaults for every hotkey registered by `useHotkey` and `useHotkeys`.
    * `requireReset` applies to chords and `timeout` applies to sequences.

package/dist/HotkeysProvider.js

@@ -1,6 +1,6 @@
 import { publishAppHotkeysStore } from "@tanstack/hotkeys";
 import { createContext } from "preact";
-import { useContext, useEffect, useMemo, useState } from "preact/hooks";
+import { useContext, useLayoutEffect, useMemo, useState } from "preact/hooks";
 import { activateHotkeysProviderScope, createAppHotkeysStore, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 import { jsx } from "preact/jsx-runtime";
 
@@ -56,10 +56,10 @@ function HotkeysProvider({ children, appHotkeys, customHotkeys, onCustomHotkeysC
 		active,
 		parent: parent.defaultOptions.hotkey?.scope
 	});
-	useEffect(() => {
+	useLayoutEffect(() => {
 		return scopeKey ? activateHotkeysProviderScope(scopeKey) : void 0;
 	}, [scopeKey]);
-	useEffect(() => {
+	useLayoutEffect(() => {
 		store?.setOptions({
 			customHotkeys,
 			onCustomHotkeysChange
@@ -69,10 +69,10 @@ function HotkeysProvider({ children, appHotkeys, customHotkeys, onCustomHotkeysC
 		customHotkeys,
 		onCustomHotkeysChange
 	]);
-	useEffect(() => {
+	useLayoutEffect(() => {
 		if (appHotkeys) store?.setAppHotkeys(appHotkeys);
 	}, [store, appHotkeys]);
-	useEffect(() => {
+	useLayoutEffect(() => {
 		if (!store) return;
 		return publishAppHotkeysStore(store);
 	}, [store]);

package/dist/index.d.ts

@@ -5,9 +5,10 @@ import { PreactHotkeyRecorder, useHotkeyRecorder } from "./useHotkeyRecorder.js"
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyScopesState } from "./useHotkeyScopesState.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
+import { useFormatForDisplay } from "./useFormatForDisplay.js";
 import { UseCustomHotkeysResult, useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 export * from "@tanstack/hotkeys";
-export { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, PreactHotkeyRecorder, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, PreactHotkeyRecorder, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useFormatForDisplay, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/index.js

@@ -5,6 +5,7 @@ import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyScopesState } from "./useHotkeyScopesState.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
+import { useFormatForDisplay } from "./useFormatForDisplay.js";
 import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
@@ -12,4 +13,4 @@ import { useKeyHold } from "./useKeyHold.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };
+export { HotkeysProvider, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useFormatForDisplay, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };

package/dist/useFormatForDisplay.d.ts

@@ -0,0 +1,27 @@
+import { formatForDisplay } from "@tanstack/hotkeys";
+//#region src/useFormatForDisplay.d.ts
+/**
+ * Returns `formatForDisplay` with the platform from `HotkeysProvider`, or the
+ * detected platform without one. A `platform` passed to the returned function
+ * wins.
+ *
+ * Call the hook once at the top of the component; the returned function can
+ * be called anywhere, such as in a loop or a condition. Server-rendered apps
+ * should set the provider's `defaultOptions.platform` from the request with
+ * `detectPlatform(userAgent)`, so the server HTML matches the user's platform.
+ *
+ * @example
+ * ```tsx
+ * function SaveButton() {
+ *   const format = useFormatForDisplay()
+ *
+ *   return (
+ *     <button>
+ *       Save <kbd>{format('Mod+S')}</kbd>
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export declare function useFormatForDisplay(): typeof formatForDisplay;
+//#endregion

package/dist/useFormatForDisplay.js

@@ -0,0 +1,38 @@
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { formatForDisplay } from "@tanstack/hotkeys";
+import { useCallback } from "preact/hooks";
+
+//#region src/useFormatForDisplay.ts
+/**
+* Returns `formatForDisplay` with the platform from `HotkeysProvider`, or the
+* detected platform without one. A `platform` passed to the returned function
+* wins.
+*
+* Call the hook once at the top of the component; the returned function can
+* be called anywhere, such as in a loop or a condition. Server-rendered apps
+* should set the provider's `defaultOptions.platform` from the request with
+* `detectPlatform(userAgent)`, so the server HTML matches the user's platform.
+*
+* @example
+* ```tsx
+* function SaveButton() {
+*   const format = useFormatForDisplay()
+*
+*   return (
+*     <button>
+*       Save <kbd>{format('Mod+S')}</kbd>
+*     </button>
+*   )
+* }
+* ```
+*/
+function useFormatForDisplay() {
+	const platform = useDefaultHotkeysOptions().platform;
+	return useCallback((hotkey, options) => formatForDisplay(hotkey, {
+		...options,
+		platform: options?.platform ?? platform
+	}), [platform]);
+}
+
+//#endregion
+export { useFormatForDisplay };

package/dist/useHotkeyRecorder.js

@@ -1,7 +1,7 @@
 import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
 import { useSelector } from "./_useSelector.js";
 import { HotkeyRecorder } from "@tanstack/hotkeys";
-import { useEffect, useRef } from "preact/hooks";
+import { useLayoutEffect, useRef, useState } from "preact/hooks";
 import { withDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/useHotkeyRecorder.ts
@@ -14,19 +14,22 @@ function useHotkeyRecorder(options) {
 	const isRecording = useSelector(recorder.store, (state) => state.isRecording);
 	const steps = useSelector(recorder.store, (state) => state.steps);
 	const recordedHotkey = useSelector(recorder.store, (state) => state.recordedHotkey);
-	useEffect(() => {
+	useLayoutEffect(() => {
 		return () => {
 			recorderRef.current?.destroy();
 		};
 	}, []);
-	return {
-		isRecording,
-		steps,
-		recordedHotkey,
+	const [actions] = useState(() => ({
 		startRecording: () => recorderRef.current?.start(),
 		stopRecording: () => recorderRef.current?.stop(),
 		cancelRecording: () => recorderRef.current?.cancel(),
 		commitRecording: () => recorderRef.current?.commit()
+	}));
+	return {
+		isRecording,
+		steps,
+		recordedHotkey,
+		...actions
 	};
 }
 

package/dist/useHotkeys.js

@@ -1,7 +1,7 @@
 import { useHotkeysContext } from "./HotkeysProvider.js";
 import { useAppHotkeysStoreState } from "./_appHotkeysStore.js";
 import { resolveTarget } from "./utils.js";
-import { useEffect, useRef } from "preact/hooks";
+import { useLayoutEffect, useRef } from "preact/hooks";
 import { createHotkeyBindings, prepareHotkeyDefinitions } from "@tanstack/hotkeys/adapter";
 
 //#region src/useHotkeys.ts
@@ -62,7 +62,7 @@ function useHotkeys(hotkeys, commonOptions = {}) {
 		appHotkeysStore
 	};
 	const bindingsRef = useRef(null);
-	useEffect(() => {
+	useLayoutEffect(() => {
 		bindingsRef.current ??= createHotkeyBindings();
 		const { hotkeys, ...context } = latestRef.current;
 		bindingsRef.current.update(prepareHotkeyDefinitions(hotkeys, {
@@ -70,7 +70,7 @@ function useHotkeys(hotkeys, commonOptions = {}) {
 			resolveTarget
 		}));
 	});
-	useEffect(() => {
+	useLayoutEffect(() => {
 		return () => {
 			bindingsRef.current?.destroy();
 			bindingsRef.current = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/preact-hotkeys",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Preact adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.22.0"
+    "@tanstack/hotkeys": "0.23.0"
   },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.6",

package/skills/preact-hotkeys/SKILL.md

@@ -52,6 +52,7 @@ export function SaveButton({ onSave }: { onSave: () => void }) {
 | `<HotkeysProvider>`                       | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys for the components inside it.                                                                                                                     |
 | `useHotkeysContext()`                     | Read the nearest provider's merged defaults and enabled state, or `null` outside a provider.                                                                                                                                         |
 | `useDefaultHotkeysOptions()`              | Read the default options merged from every provider above.                                                                                                                                                                           |
+| `useFormatForDisplay()`                   | Get `formatForDisplay` with the provider's `platform` filled in. Use it for labels in server-rendered apps; call it at the top of the component.                                                                                     |
 | `useAppHotkeys()`                         | Get the declared app hotkeys with the user's custom hotkeys applied, to pass to the register API.                                                                                                                                    |
 | `useAppHotkeyList()`                      | List every app hotkey with its status, including ones whose components aren't mounted, for a cheat sheet or settings screen.                                                                                                         |
 | `useCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                                                                                                                |
@@ -101,10 +102,12 @@ 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 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.
+- **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` for an element the component always renders.
+- **Keep elements that mount later in state.** The hook reads a ref only after its component renders, so it misses an element that mounts later, such as one a child shows from its own state. Use `const [el, setEl] = useState<HTMLElement | null>(null)`, `target: el`, and `ref={setEl}`; the hotkey registers when the element mounts and unregisters when it unmounts.
 - **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' } }}>`.
+- **Server-rendered labels need the user's platform.** On the server, `formatForDisplay` can't see the user's OS, so it renders Linux labels that differ after hydration for Mac and Windows users. Set the provider's `defaultOptions.platform` to `detectPlatform(userAgent)` from the request's `User-Agent` header, and format labels with `const format = useFormatForDisplay()` at the top of the component, then `format(hotkey)`. Keep plain `formatForDisplay` for labels that render only in the browser.
 
 When declaring app hotkeys, building a cheat sheet, or letting users rebind shortcuts, load `@tanstack/hotkeys#app-hotkeys` and read [app hotkeys in Preact](references/app-hotkeys.md).