@tanstack/octane-hotkeys 0.9.2 → 0.10.0

package/dist/HotkeysProvider.d.ts

@@ -1,8 +1,14 @@
 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 { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/HotkeysProvider.d.ts
 export interface DefaultHotkeysOptions {
+  /**
+   * 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/index.d.ts

@@ -5,10 +5,11 @@ import { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
+import { useFormatForDisplay } from "./useFormatForDisplay.js";
 import { HotkeyRegistrationsResult, OctaneHotkeyRecorder, UseCustomHotkeysResult } from "./types.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyScopesState } from "./useHotkeyScopesState.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
 export * from "@tanstack/hotkeys";
-export { type DefaultHotkeysOptions, HotkeyRegistrationsResult, HotkeysProvider, type HotkeysProviderOptions, type HotkeysProviderProps, OctaneHotkeyRecorder, UseAppHotkeyOptions, UseCustomHotkeysResult, UseHotkeyChordOptions, UseHotkeyCommonOptions, UseHotkeyDefinition, UseHotkeyOptions, UseHotkeyOptionsFor, UseHotkeySequenceOptions, UseHotkeyTarget, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHeldKeyCodes, useHeldKeys, useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, useHotkeys, useHotkeysContext, useKeyHold };
+export { type DefaultHotkeysOptions, HotkeyRegistrationsResult, HotkeysProvider, type HotkeysProviderOptions, type HotkeysProviderProps, OctaneHotkeyRecorder, 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 { useHeldKeys } from "./useHeldKeys.js";
 import { useHeldKeyCodes } from "./useHeldKeyCodes.js";
 import { useKeyHold } from "./useKeyHold.js";
 import { useHotkeyHint } from "./useHotkeyHint.js";
+import { useFormatForDisplay } from "./useFormatForDisplay.js";
 import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyScopesState } from "./useHotkeyScopesState.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
@@ -12,4 +13,4 @@ import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotke
 
 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,26 @@
+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. Without a provider platform, server rendering and hydration use
+ * 'linux', then the client re-renders with the detected platform.
+ *
+ * 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()
+ *
+ *   <button>
+ *     Save <kbd>{format('Mod+S')}</kbd>
+ *   </button>
+ * }
+ * ```
+ */
+export declare function useFormatForDisplay(): typeof formatForDisplay;
+//#endregion

package/dist/useFormatForDisplay.js

@@ -0,0 +1,19 @@
+import { subSlot } from "./internal.js";
+import { useDefaultHotkeysOptions } from "./HotkeysProvider.js";
+import { detectPlatform, formatForDisplay } from "@tanstack/hotkeys";
+import { useCallback, useSyncExternalStore } from "octane";
+import { getServerPlatformSnapshot } from "@tanstack/hotkeys/adapter";
+
+//#region src/useFormatForDisplay.ts
+const subscribe = () => () => {};
+function useFormatForDisplay(slot) {
+	const provided = useDefaultHotkeysOptions().platform;
+	const platform = useSyncExternalStore(subscribe, () => provided ?? detectPlatform(), () => provided ?? getServerPlatformSnapshot(), subSlot(slot, "platform"));
+	return useCallback((hotkey, options) => formatForDisplay(hotkey, {
+		...options,
+		platform: options?.platform ?? platform
+	}), [platform], subSlot(slot, "format"));
+}
+
+//#endregion
+export { useFormatForDisplay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/octane-hotkeys",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Octane adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.22.1"
+    "@tanstack/hotkeys": "0.23.0"
   },
   "devDependencies": {
     "@tsrx/oxc": "0.20.0",

package/skills/octane-hotkeys/SKILL.md

@@ -55,6 +55,7 @@ export function Panel({ 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.                                                                                                                                                |
@@ -77,6 +78,7 @@ No provider is required. Use Octane 0.12 or newer, with hooks in compiler-enable
 - **Hooks are tracked by call site.** Use `useHotkeys(items.map(...))` for lists, not `useHotkey` in a loop.
 - **Custom hooks in plain `.ts` and `.js` files need the compiler.** Calls from a `.ts` or `.js` file that the compiler skips share one slot per hook in each component, even across different custom hooks, so only the last `useHotkey` call works. The compiler handles a file that imports a value from `octane` or starts with `/** @jsxImportSource octane */`. A type-only import doesn't count. `.tsrx` and `.tsx` files are fine.
 - **Call the hooks directly.** A `useShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, options, and app hotkeys.
+- **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 Octane](references/app-hotkeys.md).