@tanstack/ember-hotkeys 0.9.0 → 0.10.0

package/dist/createHotkeysScope.d.ts

@@ -7,7 +7,8 @@ import { OnHotkey } from "./onHotkey.js";
 //#region src/createHotkeysScope.d.ts
 /**
  * Helpers and modifiers with shared defaults. Owners retain their own cleanup.
- * Pass the scope to `useHotkeyRecorder` to apply its recorder defaults.
+ * Pass the scope to `useHotkeyRecorder` to apply its recorder defaults, and to
+ * `useFormatForDisplay` to apply its `platform`.
  */
 export interface EmberHotkeysScope {
   onHotkey: typeof OnHotkey;

package/dist/createHotkeysScope.js

@@ -3,7 +3,7 @@ import { UseHotkeys } from "./useHotkeys.js";
 import { read, scopeDefaults } from "./utils.js";
 import { OnHotkey } from "./onHotkey.js";
 import { OnHotkeys } from "./onHotkeys.js";
-import { definedOptions } from "@tanstack/hotkeys/adapter";
+import { definedOptions, mergeHotkeysProviderDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/createHotkeysScope.ts
 /**
@@ -11,29 +11,30 @@ import { definedOptions } from "@tanstack/hotkeys/adapter";
 * Pass the scope to child components through arguments to share configuration.
 */
 function createHotkeysScope(defaultOptions = {}) {
+	const defaults = () => mergeHotkeysProviderDefaults(void 0, read(defaultOptions), void 0);
 	const scope = {
 		onHotkey: class extends OnHotkey {
 			modify(...[element, args, options]) {
-				super.modify(element, args, { ...definedOptions(read(defaultOptions).hotkey, options) });
+				super.modify(element, args, { ...definedOptions(defaults().hotkey, options) });
 			}
 		},
 		onHotkeys: class extends OnHotkeys {
 			modify(...[element, args, options]) {
-				super.modify(element, args, { ...definedOptions(read(defaultOptions).hotkey, options) });
+				super.modify(element, args, { ...definedOptions(defaults().hotkey, options) });
 			}
 		},
 		useHotkey: class extends UseHotkey {
 			compute(...[args, options]) {
-				super.compute(args, { ...definedOptions(read(defaultOptions).hotkey, options) });
+				super.compute(args, { ...definedOptions(defaults().hotkey, options) });
 			}
 		},
 		useHotkeys: class extends UseHotkeys {
 			compute(...[args, options]) {
-				super.compute(args, { ...definedOptions(read(defaultOptions).hotkey, options) });
+				super.compute(args, { ...definedOptions(defaults().hotkey, options) });
 			}
 		}
 	};
-	scopeDefaults.set(scope, defaultOptions);
+	scopeDefaults.set(scope, defaults);
 	return scope;
 }
 

package/dist/index.d.ts

@@ -13,5 +13,6 @@ import { OnHotkey } from "./onHotkey.js";
 import { EmberHotkeysScope, createHotkeysScope } from "./createHotkeysScope.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
+import { useFormatForDisplay } from "./useFormatForDisplay.js";
 export * from "@tanstack/hotkeys";
-export { DefaultHotkeysOptions, type ElementHotkeyOptions, EmberAppHotkeyList, EmberCustomHotkeys, EmberHotkeyCommonOptions, EmberHotkeyDefinition, EmberHotkeyRecorder, EmberHotkeyState, EmberHotkeyTarget, EmberHotkeysScope, HotkeyRegistrationsResult, type MaybeGetter, createHotkeysScope, OnHotkey as onHotkey, OnHotkeys as onHotkeys, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useHeldKeyCodes, useHeldKeys, UseHotkey as useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, UseHotkeys as useHotkeys, useKeyHold };
+export { DefaultHotkeysOptions, type ElementHotkeyOptions, EmberAppHotkeyList, EmberCustomHotkeys, EmberHotkeyCommonOptions, EmberHotkeyDefinition, EmberHotkeyRecorder, EmberHotkeyState, EmberHotkeyTarget, EmberHotkeysScope, HotkeyRegistrationsResult, type MaybeGetter, createHotkeysScope, OnHotkey as onHotkey, OnHotkeys as onHotkeys, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useFormatForDisplay, useHeldKeyCodes, useHeldKeys, UseHotkey as useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, UseHotkeys as useHotkeys, useKeyHold };

package/dist/index.js

@@ -8,10 +8,11 @@ import { useHotkeyRegistrations } from "./useHotkeyRegistrations.js";
 import { useHotkeyScopesState } from "./useHotkeyScopesState.js";
 import { useHotkeyRecorder } from "./useHotkeyRecorder.js";
 import { useAppHotkeyList, useAppHotkeys, useCustomHotkeys } from "./useAppHotkeys.js";
+import { useFormatForDisplay } from "./useFormatForDisplay.js";
 import { OnHotkey } from "./onHotkey.js";
 import { OnHotkeys } from "./onHotkeys.js";
 import { createHotkeysScope } from "./createHotkeysScope.js";
 
 export * from "@tanstack/hotkeys"
 
-export { createHotkeysScope, OnHotkey as onHotkey, OnHotkeys as onHotkeys, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useHeldKeyCodes, useHeldKeys, UseHotkey as useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, UseHotkeys as useHotkeys, useKeyHold };
+export { createHotkeysScope, OnHotkey as onHotkey, OnHotkeys as onHotkeys, useAppHotkeyList, useAppHotkeys, useCustomHotkeys, useFormatForDisplay, useHeldKeyCodes, useHeldKeys, UseHotkey as useHotkey, useHotkeyHint, useHotkeyRecorder, useHotkeyRegistrations, useHotkeyScopesState, UseHotkeys as useHotkeys, useKeyHold };

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { AppHotkey, AppHotkeyListItem, CustomHotkeys, Hotkey, HotkeyChordRecorderOptions, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorderOptions, RegisteredAppHotkeys, Target } from "@tanstack/hotkeys";
+import { AppHotkey, AppHotkeyListItem, CustomHotkeys, Hotkey, HotkeyChordRecorderOptions, HotkeyPlatform, HotkeyRegistrationView, HotkeySequence, HotkeySequenceRecorderOptions, RegisteredAppHotkeys, Target } from "@tanstack/hotkeys";
 import { AdapterCommonOptions, AdapterHotkeyDefinition } from "@tanstack/hotkeys/adapter";
 //#region src/types.d.ts
 /** A reactive value. Read `.value` where the framework tracks dependencies. */
@@ -53,6 +53,13 @@ export interface EmberCustomHotkeys {
 }
 /** Shared defaults; call-specific options take precedence. */
 export interface DefaultHotkeysOptions {
+  /**
+   * The user's platform, for labels from `useFormatForDisplay`, hotkeys, and
+   * recorders. `hotkey.platform` and `hotkeyRecorder.platform` win. Detected
+   * when unset. On a server, set it from the request with
+   * `detectPlatform(userAgent)`.
+   */
+  platform?: HotkeyPlatform;
   /** Defaults for every hotkey. `requireReset` applies to chords and `timeout` to sequences. */
   hotkey?: EmberHotkeyCommonOptions;
   /** Defaults for every recorder. */

package/dist/useFormatForDisplay.d.ts

@@ -0,0 +1,25 @@
+import { EmberHotkeysScope } from "./createHotkeysScope.js";
+import { formatForDisplay } from "@tanstack/hotkeys";
+//#region src/useFormatForDisplay.d.ts
+/**
+ * Returns `formatForDisplay` with the scope's `platform` as the default, so
+ * labels match the user's platform. The returned function works anywhere,
+ * including templates, and reads the scope's defaults when called, so
+ * templates update when they change. An explicit `platform` option wins.
+ *
+ * Server-rendered apps should set the scope's default `platform` from the
+ * request user agent, such as
+ * `detectPlatform(fastboot.request.headers.get('user-agent'))` with the
+ * FastBoot service.
+ *
+ * @example
+ * ```gts
+ * class SaveButton extends Component<{ Args: { hotkeys: EmberHotkeysScope } }> {
+ *   format = useFormatForDisplay(this.args.hotkeys)
+ *
+ *   <template><kbd>{{this.format "Mod+S"}}</kbd></template>
+ * }
+ * ```
+ */
+export declare function useFormatForDisplay(scope?: EmberHotkeysScope): typeof formatForDisplay;
+//#endregion

package/dist/useFormatForDisplay.js

@@ -0,0 +1,33 @@
+import { scopeDefaults } from "./utils.js";
+import { formatForDisplay } from "@tanstack/hotkeys";
+
+//#region src/useFormatForDisplay.ts
+/**
+* Returns `formatForDisplay` with the scope's `platform` as the default, so
+* labels match the user's platform. The returned function works anywhere,
+* including templates, and reads the scope's defaults when called, so
+* templates update when they change. An explicit `platform` option wins.
+*
+* Server-rendered apps should set the scope's default `platform` from the
+* request user agent, such as
+* `detectPlatform(fastboot.request.headers.get('user-agent'))` with the
+* FastBoot service.
+*
+* @example
+* ```gts
+* class SaveButton extends Component<{ Args: { hotkeys: EmberHotkeysScope } }> {
+*   format = useFormatForDisplay(this.args.hotkeys)
+*
+*   <template><kbd>{{this.format "Mod+S"}}</kbd></template>
+* }
+* ```
+*/
+function useFormatForDisplay(scope) {
+	return ((hotkey, options) => formatForDisplay(hotkey, {
+		...options,
+		platform: options?.platform ?? (scope && scopeDefaults.get(scope)().platform)
+	}));
+}
+
+//#endregion
+export { useFormatForDisplay };

package/dist/useHotkeyRecorder.js

@@ -5,7 +5,7 @@ import { withDefaults } from "@tanstack/hotkeys/adapter";
 
 //#region src/useHotkeyRecorder.ts
 function useHotkeyRecorder(owner, options, scope) {
-	const recorder = new HotkeyRecorder(() => withDefaults(scope && read(scopeDefaults.get(scope)).hotkeyRecorder, read(options)));
+	const recorder = new HotkeyRecorder(() => withDefaults(scope && scopeDefaults.get(scope)().hotkeyRecorder, read(options)));
 	const state = select(owner, recorder.store, (value) => value);
 	registerDestructor(owner, () => recorder.destroy());
 	return {

package/dist/utils.js

@@ -4,7 +4,7 @@ import { subscribePublishedAppHotkeys } from "@tanstack/hotkeys/adapter";
 import { trackedObject } from "@ember/reactive/collections";
 
 //#region src/utils.ts
-/** The defaults behind each `createHotkeysScope` result. */
+/** Reads the merged defaults behind each `createHotkeysScope` result. */
 const scopeDefaults = /* @__PURE__ */ new WeakMap();
 function read(value) {
 	return typeof value === "function" ? value() : value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ember-hotkeys",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Ember adapter for TanStack Hotkeys",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -40,7 +40,7 @@
   ],
   "dependencies": {
     "@embroider/addon-shim": "^1.10.3",
-    "@tanstack/hotkeys": "0.22.1",
+    "@tanstack/hotkeys": "0.23.0",
     "ember-modifier": "^4.2.2"
   },
   "devDependencies": {

package/skills/ember-hotkeys/SKILL.md

@@ -62,6 +62,7 @@ export default class Editor extends Component {
 | `{{onHotkey hotkey callback ...options}}`           | Attach a hotkey to the element the modifier is on, so it fires while focus is inside that element.                                                                                     |
 | `{{onHotkeys definitions}}`                         | Attach several hotkeys to one element.                                                                                                                                                 |
 | `createHotkeysScope(defaults?)`                     | Create `useHotkey`, `useHotkeys`, `onHotkey`, and `onHotkeys` that share default options.                                                                                              |
+| `useFormatForDisplay(scope?)`                       | Get `formatForDisplay` with the scope's `platform` filled in, for labels rendered by FastBoot.                                                                                         |
 | `provideAppHotkeys(appHotkeys, options?)`           | Declare app hotkeys and load the user's custom hotkeys before the app boots, since Ember has no provider.                                                                              |
 | `getHotkeyManager().activateScope(scope, options?)` | Turn on a scope, such as an exclusive one for a dialog; it returns the function that turns the scope off.                                                                              |
 | `useAppHotkeys(this)`                               | Get the declared app hotkeys with the user's custom hotkeys applied.                                                                                                                   |
@@ -86,6 +87,7 @@ The helpers are template helpers, not JavaScript functions. State readers take t
 - **`createHotkeysScope` isn't a hotkey scope.** It only sets defaults for its helpers. For a dialog, call `getHotkeyManager().activateScope(name, { exclusive: true })` in the constructor, pass the result to `registerDestructor(this, release)`, and put `scope=name` on the dialog's hotkeys. Give each open dialog its own name.
 - **Read app hotkeys through getters.** Template paths can't index ids that contain dots.
 - **Scopes have no `useHotkeyRecorder`** since v0.9.0. Call `useHotkeyRecorder(this, options, this.hotkeys)`, so apps that set defaults but don't record don't ship the recorder.
+- **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 `platform: detectPlatform(userAgent)` to `createHotkeysScope`, with the user agent from FastBoot's request, and format labels with `format = useFormatForDisplay(this.hotkeys)`, then `{{this.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 Ember](references/app-hotkeys.md).