@tanstack/angular-hotkeys 0.20.0 → 0.21.0

package/dist/hotkeys-provider.d.ts

@@ -1,9 +1,15 @@
 import { InjectHotkeyCommonOptions } from "./injectHotkey.js";
-import { AppHotkeys, AppHotkeysState, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
+import { AppHotkeys, AppHotkeysState, AppHotkeysStore, CustomHotkeys, HotkeyChordRecorderOptions, HotkeyPlatform, HotkeySequenceRecorderOptions } from "@tanstack/hotkeys";
 import { InjectionToken, Provider, Signal } from "@angular/core";
 import { HotkeysProviderScopeProps } from "@tanstack/hotkeys/adapter";
 //#region src/hotkeys-provider.d.ts
 export interface HotkeysProviderOptions {
+  /**
+   * The user's platform, for labels from `injectFormatForDisplay`, hotkeys,
+   * and recorders. Detected when unset. On a server, set it from the request
+   * with `detectPlatform(userAgent)`.
+   */
+  platform?: HotkeyPlatform;
   /**
    * Defaults for every hotkey registered by `injectHotkey` and `injectHotkeys`.
    * `requireReset` applies to chords and `timeout` applies to sequences.
@@ -14,8 +20,12 @@ export interface HotkeysProviderOptions {
 }
 /** Options for `provideHotkeys`. */
 export interface ProvideHotkeysOptions {
-  /** Merged with the parent provider's defaults. */
-  defaultOptions?: HotkeysProviderOptions;
+  /**
+   * Merged with the parent provider's defaults. A getter runs in the
+   * provider's injection context, so it can `inject(REQUEST)` to set
+   * `platform` from the request during server rendering.
+   */
+  defaultOptions?: MaybeGetter<HotkeysProviderOptions>;
   /**
    * See `HotkeysProviderScopeProps['scope']`. Getters, here and for
    * `exclusive` and `enabled`, run in the provider's injection context, so

package/dist/hotkeys-provider.js

@@ -43,7 +43,7 @@ function createHotkeysContext(options) {
 		appHotkeysState = state.asReadonly();
 	}
 	const enabled = computed(() => parent.enabled() && read(options.enabled) !== false);
-	const defaultOptions = computed(() => mergeHotkeysProviderDefaults(parent.defaultOptions, options.defaultOptions, read(options.scope)));
+	const defaultOptions = computed(() => mergeHotkeysProviderDefaults(parent.defaultOptions, read(options.defaultOptions), read(options.scope)));
 	const scopeKey = computed(() => getHotkeysProviderScopeKey({
 		scope: read(options.scope),
 		exclusive: read(options.exclusive),

package/dist/index.d.ts

@@ -9,5 +9,6 @@ import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
 import { injectHotkeyScopesState } from "./injectHotkeyScopesState.js";
 import { injectHotkeyHint } from "./injectHotkeyHint.js";
 import { InjectCustomHotkeysResult, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys } from "./injectAppHotkeys.js";
+import { injectFormatForDisplay } from "./injectFormatForDisplay.js";
 export * from "@tanstack/hotkeys";
-export { AngularHotkeyRecorder, HOTKEYS_INJECTION_TOKEN, HotkeysContextValue, HotkeysProviderOptions, InjectAppHotkeyOptions, InjectCustomHotkeysResult, InjectHotkeyChordOptions, InjectHotkeyCommonOptions, InjectHotkeyDefinition, InjectHotkeyOptions, InjectHotkeyOptionsFor, InjectHotkeySequenceOptions, InjectHotkeyTarget, MaybeGetter, ProvideHotkeysOptions, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeyScopesState, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };
+export { AngularHotkeyRecorder, HOTKEYS_INJECTION_TOKEN, HotkeysContextValue, HotkeysProviderOptions, InjectAppHotkeyOptions, InjectCustomHotkeysResult, InjectHotkeyChordOptions, InjectHotkeyCommonOptions, InjectHotkeyDefinition, InjectHotkeyOptions, InjectHotkeyOptionsFor, InjectHotkeySequenceOptions, InjectHotkeyTarget, MaybeGetter, ProvideHotkeysOptions, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectFormatForDisplay, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeyScopesState, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };

package/dist/index.js

@@ -9,7 +9,8 @@ import { injectHotkeyRegistrations } from "./injectHotkeyRegistrations.js";
 import { injectHotkeyScopesState } from "./injectHotkeyScopesState.js";
 import { injectHotkeyHint } from "./injectHotkeyHint.js";
 import { injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys } from "./injectAppHotkeys.js";
+import { injectFormatForDisplay } from "./injectFormatForDisplay.js";
 
 export * from "@tanstack/hotkeys"
 
-export { HOTKEYS_INJECTION_TOKEN, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeyScopesState, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };
+export { HOTKEYS_INJECTION_TOKEN, injectAppHotkeyList, injectAppHotkeys, injectCustomHotkeys, injectDefaultHotkeysOptions, injectFormatForDisplay, injectHeldKeyCodes, injectHeldKeys, injectHotkey, injectHotkeyHint, injectHotkeyRecorder, injectHotkeyRegistrations, injectHotkeyScopesState, injectHotkeys, injectHotkeysContext, injectKeyHold, provideHotkeys };

package/dist/injectFormatForDisplay.d.ts

@@ -0,0 +1,25 @@
+import { formatForDisplay } from "@tanstack/hotkeys";
+//#region src/injectFormatForDisplay.d.ts
+/**
+ * Returns `formatForDisplay` with the provider's `platform` as the default,
+ * so labels match the user's platform. Call it in an injection context, such
+ * as a field initializer; the returned function works anywhere, including
+ * templates. An explicit `platform` option wins.
+ *
+ * Server-rendered apps should set the provider's `defaultOptions.platform`
+ * from the request user agent, such as
+ * `detectPlatform(inject(REQUEST)?.headers.get('user-agent'))`.
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   selector: 'app-save-button',
+ *   template: `<kbd>{{ format('Mod+S') }}</kbd>`,
+ * })
+ * export class SaveButton {
+ *   format = injectFormatForDisplay()
+ * }
+ * ```
+ */
+export declare function injectFormatForDisplay(): typeof formatForDisplay;
+//#endregion

package/dist/injectFormatForDisplay.js

@@ -0,0 +1,35 @@
+import { injectHotkeysContext } from "./hotkeys-provider.js";
+import { formatForDisplay } from "@tanstack/hotkeys";
+
+//#region src/injectFormatForDisplay.ts
+/**
+* Returns `formatForDisplay` with the provider's `platform` as the default,
+* so labels match the user's platform. Call it in an injection context, such
+* as a field initializer; the returned function works anywhere, including
+* templates. An explicit `platform` option wins.
+*
+* Server-rendered apps should set the provider's `defaultOptions.platform`
+* from the request user agent, such as
+* `detectPlatform(inject(REQUEST)?.headers.get('user-agent'))`.
+*
+* @example
+* ```ts
+* @Component({
+*   selector: 'app-save-button',
+*   template: `<kbd>{{ format('Mod+S') }}</kbd>`,
+* })
+* export class SaveButton {
+*   format = injectFormatForDisplay()
+* }
+* ```
+*/
+function injectFormatForDisplay() {
+	const context = injectHotkeysContext();
+	return ((hotkey, options) => formatForDisplay(hotkey, {
+		...options,
+		platform: options?.platform ?? context.defaultOptions.platform
+	}));
+}
+
+//#endregion
+export { injectFormatForDisplay };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/angular-hotkeys",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Angular adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/hotkeys": "0.22.1"
+    "@tanstack/hotkeys": "0.23.0"
   },
   "peerDependencies": {
     "@angular/common": ">=19.0.0",

package/skills/angular-hotkeys/SKILL.md

@@ -66,6 +66,7 @@ export class PanelComponent {
 | `provideHotkeys(options)`                    | Set default options, a scope (`exclusive` for dialogs), `enabled`, and app hotkeys in the app config or a component's `providers`.                                                                 |
 | `injectHotkeysContext()`                     | Read the nearest provided defaults and enabled state. Activates that provider's scope.                                                                                                             |
 | `injectDefaultHotkeysOptions()`              | Read the default options merged from every provider above.                                                                                                                                         |
+| `injectFormatForDisplay()`                   | Get `formatForDisplay` with the provider's `platform` filled in, for labels in server-rendered apps. Call it in an injection context.                                                              |
 | `injectAppHotkeys()`                         | Get a signal of the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
 | `injectAppHotkeyList()`                      | Get a signal listing every app hotkey with its status, for a cheat sheet or settings screen.                                                                                                       |
 | `injectCustomHotkeys()`                      | Read, change, and reset the user's custom hotkeys, and check a new one for conflicts.                                                                                                              |
@@ -117,6 +118,7 @@ A component's `providers` apply to the component itself, so it can register its
 - **Replace `@HostListener('document:keydown')` and `(keydown.control.s)` bindings with `injectHotkey`.**
 - **Register runtime lists in the constructor.** `injectHotkey` throws outside an injection context, such as in `ngOnInit`. For hotkeys from data, use `injectHotkeys(() => this.items().map(...))`.
 - **Call the inject functions directly.** A shortcut service or `injectShortcut(keys: string)` wrapper has to cast strings to hotkeys, which turns off type checking and drops sequences, signal 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. Pass `provideHotkeys({ defaultOptions: () => ({ platform: detectPlatform(inject(REQUEST)?.headers.get('user-agent')) }) })`, and format labels with `format = injectFormatForDisplay()` as a field, then `format(hotkey)` in the template. 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 Angular](references/app-hotkeys.md).