@tanstack/hotkeys 0.22.0 → 0.23.0

package/dist/_server.js

@@ -0,0 +1,21 @@
+//#region src/_server.ts
+const SERVER_AGENT = /^(?:Node\.js\/|Deno\/|Bun\/|Cloudflare-Workers)/;
+/** Whether this runs on a server: no `navigator`, or a server runtime's. */
+function isServerRuntime() {
+	return typeof navigator === "undefined" || SERVER_AGENT.test(String(navigator.userAgent));
+}
+let warned = false;
+/**
+* Warns once, in development, when a label's platform is detected during
+* server rendering. The server then renders 'linux' labels, which differ for
+* users on macOS and Windows after hydration.
+*/
+function warnServerPlatform() {
+	if (process.env.NODE_ENV !== "production" && !warned && isServerRuntime()) {
+		warned = true;
+		console.warn("[TanStack Hotkeys] A hotkey label was formatted during server rendering without a platform, so it uses 'linux'. Mac and Windows users get a different label after hydration. Read the platform from the request with `detectPlatform(userAgent)`, set it as the `platform` of your hotkeys provider or scope, and format labels with your adapter's formatter, such as `useFormatForDisplay`. Or render the labels only in the browser. See the server rendering section of the Displaying Hotkeys guide.");
+	}
+}
+
+//#endregion
+export { isServerRuntime, warnServerPlatform };

package/dist/adapter.d.ts

@@ -2,8 +2,9 @@ import { Store, createStore } from "./_store.js";
 import { HotkeyCallback, HotkeyChord, HotkeySequence, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence } from "./hotkey.types.js";
 import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyOptions, HotkeySequenceOptions, Target } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeysStore } from "./app-hotkeys.js";
-import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
+import { HotkeyPlatform } from "./platform.js";
 import { definedOptions, withDefaults } from "./_registration.js";
+import { createAppHotkeysStore } from "@tanstack/hotkeys";
 //#region src/adapter.d.ts
 /**
  * A hotkey and its callback, with optional per-binding options. Chords accept
@@ -147,11 +148,20 @@ export interface HotkeysProviderScopeProps {
 /**
  * Merges a provider's default options over its parent's. A provider with a
  * `scope` sets `hotkey.scope`, so hotkeys registered inside it use that scope.
+ * A provider's `platform` is inherited, and is the default platform for its
+ * hotkeys and recorders; `hotkey.platform` and `hotkeyRecorder.platform` win.
  */
 export declare function mergeHotkeysProviderDefaults<T extends {
+  platform?: HotkeyPlatform;
   hotkey?: object;
   hotkeyRecorder?: object;
 }>(parent: T | undefined, own: T | undefined, scope: string | undefined): T;
+/**
+ * The platform to render with during server rendering and hydration when no
+ * provider sets one, for a `useSyncExternalStore` server snapshot. Warns once
+ * in development on the server.
+ */
+export declare function getServerPlatformSnapshot(): HotkeyPlatform;
 /**
  * A key for a provider's scope activation, or `null` when the scope should not
  * be active. Equal keys mean the same activation, so adapters reactivate only

package/dist/adapter.js

@@ -1,10 +1,7 @@
-import { detectPlatform } from "./platform.js";
-import { isHotkeySequence, normalizeHotkey, parseHotkey } from "./parse.js";
+import { warnServerPlatform } from "./_server.js";
 import { chordHasKey, defaultHotkeyOptions, definedOptions, withDefaults } from "./_registration.js";
 import { createStore } from "./_store.js";
-import { getHotkeyManager } from "./hotkey-manager.js";
-import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
-import { getAppHotkeyRegistrationOptions, isAppHotkey, resolveAppHotkey } from "./app-hotkeys.js";
+import { createAppHotkeysStore, detectPlatform, getAppHotkeyRegistrationOptions, getHotkeyManager, isAppHotkey, isHotkeySequence, normalizeHotkey, parseHotkey, resolveAppHotkey } from "@tanstack/hotkeys";
 
 //#region src/adapter.ts
 /** Reconciles adapter registrations while retaining handles for option updates. */
@@ -126,17 +123,31 @@ function subscribePublishedAppHotkeys(onChange) {
 /**
 * Merges a provider's default options over its parent's. A provider with a
 * `scope` sets `hotkey.scope`, so hotkeys registered inside it use that scope.
+* A provider's `platform` is inherited, and is the default platform for its
+* hotkeys and recorders; `hotkey.platform` and `hotkeyRecorder.platform` win.
 */
 function mergeHotkeysProviderDefaults(parent, own, scope) {
+	const parentPlatform = { platform: parent?.platform };
+	const ownPlatform = { platform: own?.platform };
 	return {
+		...definedOptions(parentPlatform, ownPlatform),
 		hotkey: {
-			...definedOptions(parent?.hotkey, own?.hotkey),
+			...definedOptions(parentPlatform, parent?.hotkey, ownPlatform, own?.hotkey),
 			...scope && { scope }
 		},
-		hotkeyRecorder: definedOptions(parent?.hotkeyRecorder, own?.hotkeyRecorder)
+		hotkeyRecorder: definedOptions(parentPlatform, parent?.hotkeyRecorder, ownPlatform, own?.hotkeyRecorder)
 	};
 }
 /**
+* The platform to render with during server rendering and hydration when no
+* provider sets one, for a `useSyncExternalStore` server snapshot. Warns once
+* in development on the server.
+*/
+function getServerPlatformSnapshot() {
+	warnServerPlatform();
+	return "linux";
+}
+/**
 * A key for a provider's scope activation, or `null` when the scope should not
 * be active. Equal keys mean the same activation, so adapters reactivate only
 * when the key changes, not when an inline `exclusive` object is recreated.
@@ -163,4 +174,4 @@ function activateHotkeysProviderScope(key) {
 }
 
 //#endregion
-export { activateHotkeysProviderScope, createAppHotkeysStore, createHotkeyBindings, createStore, definedOptions, getHotkeysProviderScopeKey, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys, withDefaults };
+export { activateHotkeysProviderScope, createAppHotkeysStore, createHotkeyBindings, createStore, definedOptions, getHotkeysProviderScopeKey, getServerPlatformSnapshot, mergeHotkeysProviderDefaults, prepareHotkeyDefinitions, subscribePublishedAppHotkeys, withDefaults };

package/dist/format.js

@@ -1,5 +1,6 @@
 import { MODIFIER_ORDER, normalizeKeyName } from "./constants.js";
 import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
+import { warnServerPlatform } from "./_server.js";
 import { detectPlatform } from "./platform.js";
 import { assertLogicalKey, codeToLogicalKey, modifierAlias, physicalCodeOf, splitChordParts } from "./_keyboard-event.js";
 import { normalizeHotkey } from "./parse.js";
@@ -23,16 +24,21 @@ function formatForDisplay(hotkey, options = {}) {
 	const parts = formatChordParts(hotkey, options);
 	return options.parts ? parts : parts.join(chordSeparator(options));
 }
+/** Detects the platform for a label, warning in development on a server. */
+function detectDisplayPlatform() {
+	warnServerPlatform();
+	return detectPlatform();
+}
 function modifierSymbolsEnabled(options) {
 	const symbols = options.useSymbols ?? true;
 	return typeof symbols === "boolean" ? symbols : symbols.modifiers ?? true;
 }
 function chordSeparator(options) {
-	const platform = options.platform ?? detectPlatform();
+	const platform = options.platform ?? detectDisplayPlatform();
 	return options.separatorToken ?? (platform === "mac" && modifierSymbolsEnabled(options) ? " " : "+");
 }
 function formatChordParts(hotkey, options) {
-	const platform = options.platform ?? detectPlatform();
+	const platform = options.platform ?? detectDisplayPlatform();
 	const symbols = options.useSymbols ?? true;
 	const modifierSymbols = modifierSymbolsEnabled(options);
 	const keySymbols = typeof symbols === "boolean" ? symbols : symbols.keys ?? true;

package/dist/index.d.ts

@@ -2,9 +2,9 @@ import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterK
 import { ConflictBehavior, FourModifierHotkeyChord, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyMeta, HotkeySequence, HotkeySequenceCallbackContext, ParsedHotkeyChord, ParsedModifiers, RawHotkeyChord, RawModifiers, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, SingleModifierHotkeyChord, ThreeModifierHotkeyChord, TwoModifierHotkeyChord } from "./hotkey.types.js";
 import { ActivateHotkeyScopeOptions, HotkeyChordOptions, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyManager, HotkeyOptions, HotkeyOptionsFor, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequenceOptions, HotkeySequenceRegistration, HotkeySequenceRegistrationView, Target, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CustomHotkeys, DefinedAppHotkeys, Register, RegisteredAppHotkeys, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
+import { HotkeyPlatform, detectPlatform, resolveModifier } from "./platform.js";
 import { ALL_KEYS, EDITING_KEYS, FUNCTION_KEYS, LETTER_KEYS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, isSingleLetterKey, normalizeKeyName } from "./constants.js";
 import { KEY_DISPLAY_SYMBOLS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS } from "./display-labels.js";
-import { detectPlatform, resolveModifier } from "./platform.js";
 import { DisplayHotkey, DisplayHotkeyChord, FormatDisplayOptions, formatForDisplay, formatHotkey } from "./format.js";
 import { hasNonModifierKey, isHotkeySequence, isModifierKey, normalizeHotkey, parseHotkey, parseKeyboardEvent, simplifyHotkey } from "./parse.js";
 import { ValidatableHotkey, ValidationResult, assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
@@ -13,4 +13,5 @@ import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
 import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./hotkey-recorder.js";
-export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };
+import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
+export { ALL_KEYS, ActivateHotkeyScopeOptions, AppHotkey, AppHotkeyChordOptions, AppHotkeyDefaultKind, AppHotkeyId, AppHotkeyInput, AppHotkeyListItem, AppHotkeyOptions, AppHotkeySequenceOptions, AppHotkeyStatus, AppHotkeys, AppHotkeysState, AppHotkeysStore, AppHotkeysStoreOptions, CanonicalModifier, ConflictBehavior, CreateHotkeyChordHandlerOptions, CustomHotkeys, DEFAULT_SEQUENCE_TIMEOUT, DefinedAppHotkeys, DisplayHotkey, DisplayHotkeyChord, EDITING_KEYS, EditingKey, FUNCTION_KEYS, FormatDisplayOptions, FourModifierHotkeyChord, FunctionKey, HeldModifierOptions, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyCallbackContextFor, HotkeyChord, HotkeyChordCallbackContext, HotkeyChordOptions, HotkeyChordRecorderOptions, HotkeyChordRecorderValidationContext, HotkeyChordRegistration, HotkeyChordRegistrationView, HotkeyConflict, HotkeyConflictOptions, HotkeyManager, HotkeyMeta, HotkeyOptions, HotkeyOptionsFor, HotkeyPlatform, HotkeyRecorder, HotkeyRecorderCommitKeys, HotkeyRecorderOptions, HotkeyRecorderState, HotkeyRecorderValidationContext, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationStatus, HotkeyRegistrationView, HotkeyScopesState, HotkeySequence, HotkeySequenceCallbackContext, HotkeySequenceOptions, HotkeySequenceRecorderOptions, HotkeySequenceRecorderValidationContext, HotkeySequenceRegistration, HotkeySequenceRegistrationView, IndividualKey, KEY_DISPLAY_SYMBOLS, Key, KeyStateTracker, KeyStateTrackerState, KeyboardEventMatch, LETTER_KEYS, LINUX_MODIFIER_LABELS, LetterKey, LogicalKey, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, Modifier, MultiHotkeyChordHandler, NAVIGATION_KEYS, NUMBER_KEYS, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, ParsedHotkeyChord, ParsedModifiers, PhysicalKey, PhysicalKeyCode, PunctuationKey, RawHotkeyChord, RawModifiers, RecorderKeyMode, RecorderOptions, RecorderRejection, Register, RegisterableHotkey, RegisterableHotkeyChord, RegisterableHotkeySequence, RegisteredAppHotkeys, SingleModifierHotkeyChord, Target, ThreeModifierHotkeyChord, TwoModifierHotkeyChord, ValidatableHotkey, ValidationResult, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createAppHotkeysStore, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/dist/index.js

@@ -8,8 +8,9 @@ import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual, createHotkeyChordHandler, cr
 import { matchesHeldModifiers } from "./hint.js";
 import { HotkeyManager, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
 import { findHotkeyConflicts } from "./conflicts.js";
+import { createAppHotkeysStore } from "./_app-hotkeys-factory.js";
 import { AppHotkeysStore, defineAppHotkeys, getAppHotkeyRegistrationOptions, isAppHotkey, isCustomHotkey, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey } from "./app-hotkeys.js";
 import { KeyStateTracker, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyRecorder } from "./hotkey-recorder.js";
 
-export { ALL_KEYS, AppHotkeysStore, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };
+export { ALL_KEYS, AppHotkeysStore, DEFAULT_SEQUENCE_TIMEOUT, EDITING_KEYS, FUNCTION_KEYS, HotkeyManager, HotkeyRecorder, KEY_DISPLAY_SYMBOLS, KeyStateTracker, LETTER_KEYS, LINUX_MODIFIER_LABELS, MAC_MODIFIER_LABELS, MAC_MODIFIER_SYMBOLS, MODIFIER_ALIASES, MODIFIER_KEYS, MODIFIER_ORDER, NAVIGATION_KEYS, NUMBER_KEYS, PUNCTUATION_CODE_MAP, PUNCTUATION_KEYS, PUNCTUATION_KEY_DISPLAY_LABELS, WINDOWS_MODIFIER_LABELS, areHotkeysEqual, assertValidHotkey, checkHotkey, createAppHotkeysStore, createHotkeyChordHandler, createMultiHotkeyChordHandler, createSequenceMatcher, defineAppHotkeys, detectPlatform, findHotkeyConflicts, formatForDisplay, formatHotkey, getAppHotkeyRegistrationOptions, getHotkeyManager, getKeyStateTracker, hasNonModifierKey, isAppHotkey, isCustomHotkey, isHotkeySequence, isModifierKey, isSingleLetterKey, matchesHeldModifiers, matchesKeyboardEvent, normalizeHotkey, normalizeKeyName, parseHotkey, parseKeyboardEvent, provideAppHotkeys, publishAppHotkeysStore, resolveAppHotkey, resolveModifier, simplifyHotkey, toHotkeyRegistrationView, validateHotkey };

package/dist/match.d.ts

@@ -1,4 +1,5 @@
 import { HotkeyCallback, HotkeyChord, HotkeyChordCallbackContext, ParsedHotkeyChord, RegisterableHotkey, RegisterableHotkeySequence } from "./hotkey.types.js";
+import { HotkeyPlatform } from "./platform.js";
 //#region src/match.d.ts
 export interface KeyboardEventMatch {
   matched: boolean;
@@ -96,7 +97,7 @@ export declare function createMultiHotkeyChordHandler(handlers: MultiHotkeyChord
  * Aliases resolve on the supplied platform. A physical code and a logical key
  * remain distinct even when one keyboard event could match both.
  */
-export declare function areHotkeysEqual(left: RegisterableHotkey, right: RegisterableHotkey, platform?: "mac" | "windows" | "linux"): boolean;
+export declare function areHotkeysEqual(left: RegisterableHotkey, right: RegisterableHotkey, platform?: HotkeyPlatform): boolean;
 /** Default timeout between sequence steps (in milliseconds). */
 export declare const DEFAULT_SEQUENCE_TIMEOUT = 1000;
 /**

package/dist/platform.d.ts

@@ -1,21 +1,33 @@
 import { CanonicalModifier } from "./key.types.js";
 //#region src/platform.d.ts
+/** A platform for resolving `Mod` and formatting labels. */
+export type HotkeyPlatform = 'mac' | 'windows' | 'linux';
 /**
- * Detects the current platform based on browser navigator properties.
+ * Detects a platform from a user agent string, or from the browser's
+ * `navigator` when called without one.
  *
  * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
- * Control elsewhere) and for platform-specific hotkey formatting.
+ * Control elsewhere) and for platform-specific hotkey formatting. During server
+ * rendering, pass the request's `User-Agent` header to detect the user's
+ * platform instead of the server's.
  *
+ * @param userAgent - A user agent string, such as a request's `User-Agent` header.
+ * When omitted or `null` (a missing header), reads `navigator`.
  * @returns The detected platform: 'mac', 'windows', or 'linux'
- * @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+ * @remarks Without a user agent, returns 'linux' on a server runtime (no
+ * `navigator`, or Node, Deno, Bun, or Cloudflare Workers), where `navigator`
+ * describes the server.
  *
  * @example
  * ```ts
  * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
  * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+ *
+ * // On the server
+ * detectPlatform(request.headers.get('user-agent'))
  * ```
  */
-export declare function detectPlatform(): 'mac' | 'windows' | 'linux';
+export declare function detectPlatform(userAgent?: string | null): HotkeyPlatform;
 /**
  * Resolves the platform-adaptive 'Mod' modifier to the appropriate canonical modifier.
  *

package/dist/platform.js

@@ -1,25 +1,42 @@
+import { isServerRuntime } from "./_server.js";
+
 //#region src/platform.ts
 /**
-* Detects the current platform based on browser navigator properties.
+* Detects a platform from a user agent string, or from the browser's
+* `navigator` when called without one.
 *
 * Used internally to resolve platform-adaptive modifiers like 'Mod' (Command on Mac,
-* Control elsewhere) and for platform-specific hotkey formatting.
+* Control elsewhere) and for platform-specific hotkey formatting. During server
+* rendering, pass the request's `User-Agent` header to detect the user's
+* platform instead of the server's.
 *
+* @param userAgent - A user agent string, such as a request's `User-Agent` header.
+* When omitted or `null` (a missing header), reads `navigator`.
 * @returns The detected platform: 'mac', 'windows', or 'linux'
-* @remarks Defaults to 'linux' in SSR environments where navigator is undefined
+* @remarks Without a user agent, returns 'linux' on a server runtime (no
+* `navigator`, or Node, Deno, Bun, or Cloudflare Workers), where `navigator`
+* describes the server.
 *
 * @example
 * ```ts
 * const platform = detectPlatform() // 'mac' | 'windows' | 'linux'
 * const modifier = resolveModifier('Mod', platform) // 'Meta' on Mac, 'Control' elsewhere
+*
+* // On the server
+* detectPlatform(request.headers.get('user-agent'))
 * ```
 */
-function detectPlatform() {
-	if (typeof navigator === "undefined") return "linux";
-	const platform = navigator.platform?.toLowerCase() ?? "";
-	const userAgent = navigator.userAgent?.toLowerCase() ?? "";
-	if (platform.includes("mac") || userAgent.includes("mac")) return "mac";
-	if (platform.includes("win") || userAgent.includes("win")) return "windows";
+function detectPlatform(userAgent) {
+	let platform = "";
+	let agent = userAgent;
+	if (agent == null) {
+		if (isServerRuntime()) return "linux";
+		platform = navigator.platform?.toLowerCase() ?? "";
+		agent = navigator.userAgent ?? "";
+	}
+	agent = agent.toLowerCase();
+	if (platform.includes("mac") || agent.includes("mac")) return "mac";
+	if (platform.includes("win") || agent.includes("win")) return "windows";
 	return "linux";
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",

package/skills/hotkeys-core/SKILL.md

@@ -50,7 +50,7 @@ Use the first mechanism that fits:
 1. **Lifetime.** A hotkey registered in a component exists while that component is mounted. A dialog's `Escape` belongs in the dialog.
 2. **`enabled`.** A condition inside a mounted component.
 3. **Scope.** A group that turns on and off together, such as a dialog, pane, or tab. An `exclusive` scope suspends every other scope, including global hotkeys, while it is active.
-4. **`target`.** Only while focus is inside one element, which must be focusable (`tabindex="0"`).
+4. **`target`.** Only while focus is on one element or inside it. If nothing there can take focus, give the element `tabindex="0"`.
 
 When nesting scopes, stacking dialogs, or keeping some hotkeys working during an exclusive scope, read [scopes](references/scopes.md).
 
@@ -66,6 +66,7 @@ When nesting scopes, stacking dialogs, or keeping some hotkeys working during an
 - **Single-character shortcuts need an off switch.** For WCAG 2.1.4, `K`, `?`, and `['G', 'H']` need a user setting passed as `enabled`, or an app hotkey users can remap.
 - **react-hotkeys-hook names don't carry over.** `useHotkeys` and `HotkeysProvider` share names, not signatures: there's no dependency array, `preventDefault` is on by default, and sequences are arrays. Remove the old library, so two libraries don't handle the same keys.
 - **Install only the adapter.** A separately installed `@tanstack/hotkeys` at another version is a second copy, and scopes don't apply across copies.
+- **Server-rendered labels need the user's platform.** On a server, `formatForDisplay` renders Linux labels, because the server can't see the user's OS. Read the request's `User-Agent` header, pass `detectPlatform(userAgent)` as the platform of the adapter's provider or scope, and format labels with the adapter's formatter, such as `useFormatForDisplay`. Those pages then depend on the user agent, so keep them out of shared caches or add the platform to the cache key.
 
 When writing tests for hotkeys, read [testing](references/testing.md).