@tanstack/solid-hotkeys 0.19.2 → 0.20.0

package/dist/HotkeysProvider.d.ts

@@ -1,9 +1,15 @@
 import { CreateHotkeyCommonOptions } from "./createHotkey.js";
-import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeyPlatform, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import { JSX, ParentComponent } from "solid-js";
 import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/HotkeysProvider.d.ts
 export interface HotkeysProviderOptions {
+  /**
+   * The user's platform, for labels from `createFormatForDisplay`, hotkeys,
+   * and recorders. On a server, set it from the request with
+   * `detectPlatform(userAgent)`.
+   */
+  platform?: HotkeyPlatform;
   /**
    * Defaults for every hotkey registered by `createHotkey` and `createHotkeys`.
    * `requireReset` applies to chords and `timeout` applies to sequences.

package/dist/createFormatForDisplay.d.ts

@@ -0,0 +1,21 @@
+import { formatForDisplay } from "@tanstack/hotkeys";
+//#region src/createFormatForDisplay.d.ts
+/**
+ * Returns `formatForDisplay` with the provider's `platform` as the default,
+ * so labels match the user's platform. Call in a component; the returned
+ * function works anywhere, and JSX updates when the provider's platform
+ * changes. An explicit `platform` option wins.
+ *
+ * Server-rendered apps should set the provider's `defaultOptions.platform`
+ * from the request user agent with `detectPlatform(userAgent)`.
+ *
+ * @example
+ * ```tsx
+ * function SaveButton() {
+ *   const format = createFormatForDisplay()
+ *   return <kbd>{format('Mod+S')}</kbd>
+ * }
+ * ```
+ */
+export declare function createFormatForDisplay(): typeof formatForDisplay;
+//#endregion

package/dist/createFormatForDisplay.js

@@ -0,0 +1,31 @@
+import { useDefaultHotkeysOptionsSource } from "./defaultOptions.js";
+import { formatForDisplay } from "@tanstack/hotkeys";
+
+//#region src/createFormatForDisplay.ts
+/**
+* Returns `formatForDisplay` with the provider's `platform` as the default,
+* so labels match the user's platform. Call in a component; the returned
+* function works anywhere, and JSX updates when the provider's platform
+* changes. An explicit `platform` option wins.
+*
+* Server-rendered apps should set the provider's `defaultOptions.platform`
+* from the request user agent with `detectPlatform(userAgent)`.
+*
+* @example
+* ```tsx
+* function SaveButton() {
+*   const format = createFormatForDisplay()
+*   return <kbd>{format('Mod+S')}</kbd>
+* }
+* ```
+*/
+function createFormatForDisplay() {
+	const defaultOptions = useDefaultHotkeysOptionsSource();
+	return ((hotkey, options) => formatForDisplay(hotkey, {
+		...options,
+		platform: options?.platform ?? defaultOptions().platform
+	}));
+}
+
+//#endregion
+export { createFormatForDisplay };

package/dist/index.d.ts

@@ -5,9 +5,10 @@ import { SolidHotkeyRecorder, createHotkeyRecorder } from "./createHotkeyRecorde
 import { createHotkeyRegistrations } from "./createHotkeyRegistrations.js";
 import { createHotkeyScopesState } from "./createHotkeyScopesState.js";
 import { createHotkeyHint } from "./createHotkeyHint.js";
+import { createFormatForDisplay } from "./createFormatForDisplay.js";
 import { UseCustomHotkeysResult, createAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./appHotkeys.js";
 import { createHeldKeys } from "./createHeldKeys.js";
 import { createHeldKeyCodes } from "./createHeldKeyCodes.js";
 import { createKeyHold } from "./createKeyHold.js";
 export * from "@tanstack/hotkeys";
-export { CreateAppHotkeyOptions, CreateHotkeyChordOptions, CreateHotkeyCommonOptions, CreateHotkeyDefinition, CreateHotkeyOptions, CreateHotkeyOptionsFor, CreateHotkeySequenceOptions, CreateHotkeyTarget, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, SolidHotkeyRecorder, UseCustomHotkeysResult, createAppHotkeyList, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyHint, createHotkeyRecorder, createHotkeyRegistrations, createHotkeyScopesState, createHotkeys, createKeyHold, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHotkeysContext };
+export { CreateAppHotkeyOptions, CreateHotkeyChordOptions, CreateHotkeyCommonOptions, CreateHotkeyDefinition, CreateHotkeyOptions, CreateHotkeyOptionsFor, CreateHotkeySequenceOptions, CreateHotkeyTarget, HotkeysProvider, HotkeysProviderOptions, HotkeysProviderProps, SolidHotkeyRecorder, UseCustomHotkeysResult, createAppHotkeyList, createFormatForDisplay, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyHint, createHotkeyRecorder, createHotkeyRegistrations, createHotkeyScopesState, createHotkeys, createKeyHold, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHotkeysContext };

package/dist/index.js

@@ -5,6 +5,7 @@ import { createHotkeyRecorder } from "./createHotkeyRecorder.js";
 import { createHotkeyRegistrations } from "./createHotkeyRegistrations.js";
 import { createHotkeyScopesState } from "./createHotkeyScopesState.js";
 import { createHotkeyHint } from "./createHotkeyHint.js";
+import { createFormatForDisplay } from "./createFormatForDisplay.js";
 import { createAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./appHotkeys.js";
 import { createHeldKeys } from "./createHeldKeys.js";
 import { createHeldKeyCodes } from "./createHeldKeyCodes.js";
@@ -12,4 +13,4 @@ import { createKeyHold } from "./createKeyHold.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HotkeysProvider, createAppHotkeyList, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyHint, createHotkeyRecorder, createHotkeyRegistrations, createHotkeyScopesState, createHotkeys, createKeyHold, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHotkeysContext };
+export { HotkeysProvider, createAppHotkeyList, createFormatForDisplay, createHeldKeyCodes, createHeldKeys, createHotkey, createHotkeyHint, createHotkeyRecorder, createHotkeyRegistrations, createHotkeyScopesState, createHotkeys, createKeyHold, useAppHotkeys, useCustomHotkeys, useDefaultHotkeysOptions, useHotkeysContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/solid-hotkeys",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "SolidJS adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -38,7 +38,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.22.1"
+    "@tanstack/hotkeys": "0.23.0"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10",

package/skills/solid-hotkeys/SKILL.md

@@ -61,6 +61,7 @@ export function Editor() {
 | `<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.                                                                                                                                            |
+| `createFormatForDisplay()`                   | Get `formatForDisplay` with the provider's `platform` filled in, for labels in server-rendered apps.                                                                                                  |
 | `useAppHotkeys()`                            | Get an accessor of the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
 | `createAppHotkeyList()`                      | Get an accessor listing every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                       |
 | `useCustomHotkeys()`                         | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                                                                                 |
@@ -84,6 +85,7 @@ The state these return is accessors, including the recorder's fields. No provide
 - **The callback isn't tracked.** Read props inside it, as `() => props.onClose()`, rather than passing `props.onClose` itself.
 - **Register a dialog's hotkeys in a child of its provider.** A primitive uses the nearest `HotkeysProvider` above its component, so a dialog that renders `<HotkeysProvider scope={...} exclusive>` and creates `Escape` itself puts it in the suspended outer scope. Give each open dialog its own scope name, such as `` `dialog-${createUniqueId()}` ``.
 - **Call the primitives directly.** A `createShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, accessor 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 = createFormatForDisplay()` in 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 Solid](references/app-hotkeys.md).