@tanstack/svelte-hotkeys 0.19.1 → 0.20.0

package/dist/HotkeysCtx.d.ts

@@ -1,8 +1,14 @@
-import type { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from '@tanstack/hotkeys';
+import type { AppHotkeys, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeyPlatform, HotkeySequenceRecorderOptions } from '@tanstack/hotkeys';
 import type { HotkeysProviderScopeProps } from '@tanstack/hotkeys/adapter';
 import type { CreateHotkeyCommonOptions } from './createHotkey.svelte.js';
 import type { Snippet } from 'svelte';
 export interface HotkeysProviderOptions {
+    /**
+     * The user's platform, for labels from `getFormatForDisplay`, 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/getFormatForDisplay.d.ts

@@ -0,0 +1,20 @@
+import { formatForDisplay } from '@tanstack/hotkeys';
+/**
+ * Returns `formatForDisplay` with the provider's `platform` as the default,
+ * so labels match the user's platform. Call during component initialization,
+ * like `getContext`; the returned function works anywhere and reads the
+ * provider's current defaults. An explicit `platform` option wins.
+ *
+ * Server-rendered apps should set the provider's `defaultOptions.platform`
+ * from the request user agent with `detectPlatform(userAgent)`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   const format = getFormatForDisplay()
+ * </script>
+ *
+ * <kbd>{format('Mod+S')}</kbd>
+ * ```
+ */
+export declare function getFormatForDisplay(): typeof formatForDisplay;

package/dist/getFormatForDisplay.js

@@ -0,0 +1,27 @@
+import { formatForDisplay } from '@tanstack/hotkeys';
+import { getHotkeysContext } from './HotkeysCtx.js';
+/**
+ * Returns `formatForDisplay` with the provider's `platform` as the default,
+ * so labels match the user's platform. Call during component initialization,
+ * like `getContext`; the returned function works anywhere and reads the
+ * provider's current defaults. An explicit `platform` option wins.
+ *
+ * Server-rendered apps should set the provider's `defaultOptions.platform`
+ * from the request user agent with `detectPlatform(userAgent)`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   const format = getFormatForDisplay()
+ * </script>
+ *
+ * <kbd>{format('Mod+S')}</kbd>
+ * ```
+ */
+export function getFormatForDisplay() {
+    const context = getHotkeysContext();
+    return ((hotkey, options) => formatForDisplay(hotkey, {
+        ...options,
+        platform: options?.platform ?? context?.defaultOptions.platform,
+    }));
+}

package/dist/index.d.ts

@@ -12,3 +12,4 @@ export { default as HotkeysProvider } from './HotkeysProvider.svelte';
 export { DEFAULT_OPTIONS, getDefaultHotkeysOptions, getHotkeysContext, setHotkeysContext, } from './HotkeysCtx.js';
 export type { HotkeysContextOptions, HotkeysProviderOptions, HotkeysProviderProps, } from './HotkeysCtx.js';
 export * from './getHotkeyHint.svelte.js';
+export * from './getFormatForDisplay.js';

package/dist/index.js

@@ -12,3 +12,4 @@ export * from './getAppHotkeys.svelte.js';
 export { default as HotkeysProvider } from './HotkeysProvider.svelte';
 export { DEFAULT_OPTIONS, getDefaultHotkeysOptions, getHotkeysContext, setHotkeysContext, } from './HotkeysCtx.js';
 export * from './getHotkeyHint.svelte.js';
+export * from './getFormatForDisplay.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-hotkeys",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Svelte adapter for TanStack Hotkeys",
   "author": "Kunal Rao",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.22.0"
+    "@tanstack/hotkeys": "0.23.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^3.0.0",

package/skills/svelte-hotkeys/SKILL.md

@@ -65,6 +65,7 @@ Before starting, load the `@tanstack/hotkeys#hotkeys-core` skill (`npx @tanstack
 | `setHotkeysContext(options)`                           | Set the same options from a component's script instead of rendering `HotkeysProvider`; they apply to that component too.                                                                            |
 | `getHotkeysContext()`                                  | Read the nearest context's merged defaults and enabled state, or `null` outside one.                                                                                                                |
 | `getDefaultHotkeysOptions()`                           | Read the default options merged from every context above.                                                                                                                                           |
+| `getFormatForDisplay()`                                | Get `formatForDisplay` with the provider's `platform` filled in, for labels in server-rendered apps. Call it during component initialization.                                                       |
 | `getAppHotkeys()`                                      | Read `.current`, the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
 | `getAppHotkeyList()`                                   | Read `.current`, every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                            |
 | `getCustomHotkeys()`                                   | Read the user's custom hotkeys from `.current`, change or reset them, and check a new one for conflicts.                                                                                            |
@@ -88,6 +89,7 @@ No provider is required. Call these at the top level of a component's `<script>`
 - **Call `setHotkeysContext` before creating the component's hotkeys.** It applies to the component itself, so a hotkey created first lands in the outer scope, which an exclusive context then suspends. It reads its options once; for `enabled` or `exclusive` that change, wrap the component in `<HotkeysProvider>`. Give each open dialog its own scope name.
 - **The callback isn't tracked.** Read state and props inside it.
 - **Call the functions directly.** A `createShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, getter 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 = getFormatForDisplay()` during component initialization, 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 Svelte](references/app-hotkeys.md).