@tanstack/hotkeys 0.10.0 → 0.11.0

package/README.md

@@ -67,6 +67,9 @@ Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objec
 > [!NOTE]
 > You may know **TanStack Hotkeys** by our adapter names, too!
 >
+> - [**Alpine Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/alpine/quick-start)
+> - [**Ember Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/ember/quick-start)
+> - [**Octane Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/octane/quick-start)
 > - [**React Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/react/react-hotkeys)
 > - [**Preact Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/preact/preact-hotkeys)
 > - [**Solid Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/solid/reference)

package/dist/adapter.d.ts

@@ -0,0 +1,27 @@
+import { HotkeyCallback, RegisterableHotkey } from "./hotkey.types.js";
+import { HotkeyOptions } from "./hotkey-manager.js";
+import { HotkeySequence, SequenceOptions } from "./sequence-manager.js";
+//#region src/adapter.d.ts
+/** A hotkey and its callback, with optional per-binding options. */
+export interface HotkeyDefinition {
+  hotkey: RegisterableHotkey;
+  callback: HotkeyCallback;
+  options?: HotkeyOptions;
+}
+/** A sequence and its callback, with optional per-binding options. */
+export interface HotkeySequenceDefinition {
+  sequence: HotkeySequence;
+  callback: HotkeyCallback;
+  options?: SequenceOptions;
+}
+/** Reconciles adapter registrations while retaining handles for option updates. */
+export declare function createHotkeyBindings(): {
+  update(definitions: Array<HotkeyDefinition>, commonOptions?: HotkeyOptions): void;
+  destroy: () => void;
+};
+/** Reconciles sequence bindings; empty sequences and explicit null targets are skipped. */
+export declare function createHotkeySequenceBindings(): {
+  update(definitions: Array<HotkeySequenceDefinition>, commonOptions?: SequenceOptions): void;
+  destroy: () => void;
+};
+//#endregion

package/dist/adapter.js

@@ -0,0 +1,109 @@
+import { detectPlatform } from "./platform.js";
+import { normalizeRegisterableHotkey, parseHotkey } from "./parse.js";
+import { defaultHotkeyOptions, getDefaultIgnoreInputs } from "./_registration.js";
+import { getHotkeyManager } from "./hotkey-manager.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, getSequenceManager } from "./sequence-manager.js";
+
+//#region src/adapter.ts
+function createBindings() {
+	const registrations = /* @__PURE__ */ new Map();
+	return {
+		update(bindings) {
+			const keys = new Set(bindings.map((binding) => binding.key));
+			for (const [key, registration] of registrations) if (!keys.has(key)) {
+				registration.handle.unregister();
+				registrations.delete(key);
+			}
+			for (const binding of bindings) {
+				const previous = registrations.get(binding.key);
+				const { target, platform } = binding.options;
+				if (previous?.handle.isActive && previous.target === target && previous.platform === platform) {
+					previous.handle.callback = binding.callback;
+					const reset = Object.fromEntries(Object.keys(previous.options).map((key) => [key, void 0]));
+					previous.handle.setOptions({
+						...reset,
+						...binding.options
+					});
+					previous.options = binding.options;
+				} else {
+					previous?.handle.unregister();
+					registrations.set(binding.key, {
+						handle: binding.register(),
+						target,
+						platform,
+						options: binding.options
+					});
+				}
+			}
+		},
+		destroy() {
+			for (const { handle } of registrations.values()) handle.unregister();
+			registrations.clear();
+		}
+	};
+}
+function resolveOptions(options) {
+	return {
+		...defaultHotkeyOptions,
+		requireReset: false,
+		...options,
+		ignoreInputs: options.ignoreInputs,
+		target: "target" in options ? options.target ?? null : typeof document === "undefined" ? null : document,
+		platform: options.platform ?? detectPlatform()
+	};
+}
+/** Reconciles adapter registrations while retaining handles for option updates. */
+function createHotkeyBindings() {
+	const bindings = createBindings();
+	return {
+		update(definitions, commonOptions = {}) {
+			const prepared = [];
+			definitions.forEach((definition, index) => {
+				const options = resolveOptions({
+					...commonOptions,
+					...definition.options
+				});
+				if (!options.target) return;
+				const hotkey = normalizeRegisterableHotkey(definition.hotkey, options.platform);
+				options.ignoreInputs ??= getDefaultIgnoreInputs(parseHotkey(hotkey, options.platform));
+				prepared.push({
+					key: `${index}:${hotkey}`,
+					callback: definition.callback,
+					options,
+					register: () => getHotkeyManager().register(hotkey, definition.callback, options)
+				});
+			});
+			bindings.update(prepared);
+		},
+		destroy: bindings.destroy
+	};
+}
+/** Reconciles sequence bindings; empty sequences and explicit null targets are skipped. */
+function createHotkeySequenceBindings() {
+	const bindings = createBindings();
+	return {
+		update(definitions, commonOptions = {}) {
+			const prepared = [];
+			definitions.forEach((definition, index) => {
+				const options = resolveOptions({
+					timeout: DEFAULT_SEQUENCE_TIMEOUT,
+					...commonOptions,
+					...definition.options
+				});
+				if (!options.target || definition.sequence.length === 0) return;
+				options.ignoreInputs ??= getDefaultIgnoreInputs(parseHotkey(definition.sequence[0], options.platform));
+				prepared.push({
+					key: `${index}:${JSON.stringify(definition.sequence)}`,
+					callback: definition.callback,
+					options,
+					register: () => getSequenceManager().register(definition.sequence, definition.callback, options)
+				});
+			});
+			bindings.update(prepared);
+		},
+		destroy: bindings.destroy
+	};
+}
+
+//#endregion
+export { createHotkeyBindings, createHotkeySequenceBindings };

package/dist/constants.d.ts

@@ -118,7 +118,7 @@ export declare const PUNCTUATION_CODE_MAP: Record<string, string>;
  * @see {@link EDITING_KEYS}
  * @see {@link PUNCTUATION_KEYS}
  */
-export declare const ALL_KEYS: Set<LetterKey | NumberKey | FunctionKey | NavigationKey | EditingKey | PunctuationKey | "CapsLock" | "ContextMenu" | "Convert" | "KanaMode" | "NonConvert" | "Help" | "Insert" | "NumLock" | "Fn" | "FnLock" | "PrintScreen" | "ScrollLock" | "Pause" | "BrowserBack" | "BrowserFavorites" | "BrowserForward" | "BrowserHome" | "BrowserRefresh" | "BrowserSearch" | "BrowserStop" | "Eject" | "LaunchMail" | "MediaPlayPause" | "MediaStop" | "MediaTrackNext" | "MediaTrackPrevious" | "Power" | "AudioVolumeDown" | "AudioVolumeMute" | "AudioVolumeUp" | "WakeUp" | "Hyper" | "Super" | "Again" | "Copy" | "Cut" | "Find" | "Open" | "Paste" | "Props" | "Select" | "Undo" | "Hiragana" | "Katakana" | "Clear" | "Cancel" | "Standby" | "LaunchApplication1" | "LaunchApplication2" | "LaunchMediaPlayer" | "HangulMode" | "HanjaMode" | "Zenkaku" | "Hankaku" | "ZenkakuHankaku">;
+export declare const ALL_KEYS: Set<"CapsLock" | "ContextMenu" | "Convert" | "KanaMode" | "NonConvert" | "Help" | "Insert" | "NumLock" | "Fn" | "FnLock" | "PrintScreen" | "ScrollLock" | "Pause" | "BrowserBack" | "BrowserFavorites" | "BrowserForward" | "BrowserHome" | "BrowserRefresh" | "BrowserSearch" | "BrowserStop" | "Eject" | "LaunchMail" | "MediaPlayPause" | "MediaStop" | "MediaTrackNext" | "MediaTrackPrevious" | "Power" | "AudioVolumeDown" | "AudioVolumeMute" | "AudioVolumeUp" | "WakeUp" | "Hyper" | "Super" | "Again" | "Copy" | "Cut" | "Find" | "Open" | "Paste" | "Props" | "Select" | "Undo" | "Hiragana" | "Katakana" | "Clear" | "Cancel" | "Standby" | "LaunchApplication1" | "LaunchApplication2" | "LaunchMediaPlayer" | "HangulMode" | "HanjaMode" | "Zenkaku" | "Hankaku" | "ZenkakuHankaku" | LetterKey | NumberKey | FunctionKey | NavigationKey | EditingKey | PunctuationKey>;
 /**
  * Normalizes a key name to its canonical form.
  *

package/dist/format.d.ts

@@ -31,7 +31,8 @@ export type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {});
 /**
  * Formats a hotkey for display in a user interface.
  *
- * On macOS, uses symbols (⌘⇧S) in the same modifier order as {@link normalizeHotkeyFromParsed}.
+ * On macOS, uses symbols (⇧⌘S) in Control, Option, Shift, Command order.
+ * Display ordering does not change the normalized hotkey used for registration.
  * On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
  * The separator can be customized with `separatorToken`.
  * Physical codes use conventional display labels: `[KeyS]` becomes `S` and
@@ -46,7 +47,7 @@ export type DisplayHotkey = RegisterableHotkey | ParsedHotkey | (string & {});
  * @example
  * ```ts
  * formatForDisplay('Mod+Shift+S', { platform: 'mac' })
- * // Returns: '⌘ ⇧ S' (symbols separated by spaces on macOS)
+ * // Returns: '⇧ ⌘ S' (symbols separated by spaces on macOS)
  *
  * formatForDisplay('Mod+Shift+S', { platform: 'windows' })
  * // Returns: 'Ctrl+Shift+S'

package/dist/format.js

@@ -47,7 +47,15 @@ function formatForDisplay(hotkey, options = {}) {
 	const keySymbols = typeof symbols === "boolean" ? symbols : symbols.keys ?? true;
 	const separator = options.separatorToken ?? (platform === "mac" && modifierSymbols ? " " : "+");
 	const normalized = typeof hotkey === "object" && "modifiers" in hotkey ? normalizeHotkeyFromParsed(hotkey, platform) : normalizeRegisterableHotkey(hotkey, platform);
-	const parts = splitHotkeyParts(normalized).map((segment) => {
+	const segments = splitHotkeyParts(normalized);
+	if (platform === "mac") {
+		const modifierIndex = (segment) => {
+			const index = MODIFIER_ORDER.indexOf(segment === "Mod" ? "Meta" : segment);
+			return index === -1 ? MODIFIER_ORDER.length : index;
+		};
+		segments.sort((a, b) => modifierIndex(a) - modifierIndex(b));
+	}
+	const parts = segments.map((segment) => {
 		if (isModifierKey(segment)) {
 			const modifier = MODIFIER_ALIASES[segment] ?? MODIFIER_ALIASES[segment.toLowerCase()];
 			return platform === "mac" ? modifierSymbols ? MAC_MODIFIER_SYMBOLS[modifier] : MAC_MODIFIER_LABELS[modifier] : platform === "windows" ? WINDOWS_MODIFIER_LABELS[modifier] : LINUX_MODIFIER_LABELS[modifier];

package/dist/hotkey-recorder.d.ts

@@ -78,7 +78,8 @@ export declare class HotkeyRecorder {
    * Use this to subscribe to state changes or access current state.
    */
   readonly store: Store<HotkeyRecorderState>;
-  constructor(options: HotkeyRecorderOptions);
+  /** Options may be a getter to read current configuration during an active session. */
+  constructor(options: HotkeyRecorderOptions | (() => HotkeyRecorderOptions));
   /**
    * Updates the recorder options, including callbacks.
    * This allows framework adapters to sync callback changes without recreating the recorder.

package/dist/hotkey-recorder.js

@@ -58,10 +58,18 @@ var HotkeyRecorder = class {
 		recordedHotkey: null
 	});
 	#keydownHandler = null;
-	#options;
+	#optionsSource;
+	#optionOverrides = {};
+	get #options() {
+		return {
+			...typeof this.#optionsSource === "function" ? this.#optionsSource() : this.#optionsSource,
+			...this.#optionOverrides
+		};
+	}
 	#platform;
+	/** Options may be a getter to read current configuration during an active session. */
 	constructor(options) {
-		this.#options = options;
+		this.#optionsSource = options;
 		this.#platform = detectPlatform();
 	}
 	/**
@@ -69,8 +77,8 @@ var HotkeyRecorder = class {
 	* This allows framework adapters to sync callback changes without recreating the recorder.
 	*/
 	setOptions(options) {
-		this.#options = {
-			...this.#options,
+		this.#optionOverrides = {
+			...this.#optionOverrides,
 			...options
 		};
 	}

package/dist/hotkey-sequence-recorder.d.ts

@@ -65,7 +65,8 @@ export interface HotkeySequenceRecorderOptions extends RecorderOptions {
 export declare class HotkeySequenceRecorder {
   #private;
   readonly store: Store<HotkeySequenceRecorderState>;
-  constructor(options: HotkeySequenceRecorderOptions);
+  /** Options may be a getter to read current configuration during an active session. */
+  constructor(options: HotkeySequenceRecorderOptions | (() => HotkeySequenceRecorderOptions));
   /** Merges current callbacks and options without discarding recorded steps. */
   setOptions(options: Partial<HotkeySequenceRecorderOptions>): void;
   /** Starts a fresh recording; repeated starts during an active session are ignored. */

package/dist/hotkey-sequence-recorder.js

@@ -32,22 +32,27 @@ var HotkeySequenceRecorder = class {
 		recordedSequence: null
 	});
 	#keydownHandler = null;
-	#options;
+	#optionsSource;
+	#optionOverrides = {};
+	get #options() {
+		return {
+			...defaultHotkeySequenceRecorderOptions,
+			...typeof this.#optionsSource === "function" ? this.#optionsSource() : this.#optionsSource,
+			...this.#optionOverrides
+		};
+	}
 	#platform;
 	#events = [];
 	#idleTimer = null;
+	/** Options may be a getter to read current configuration during an active session. */
 	constructor(options) {
-		this.#options = {
-			...defaultHotkeySequenceRecorderOptions,
-			...options
-		};
+		this.#optionsSource = options;
 		this.#platform = detectPlatform();
 	}
 	/** Merges current callbacks and options without discarding recorded steps. */
 	setOptions(options) {
-		this.#options = {
-			...defaultHotkeySequenceRecorderOptions,
-			...this.#options,
+		this.#optionOverrides = {
+			...this.#optionOverrides,
 			...options
 		};
 	}

package/dist/index.d.ts

@@ -1,15 +1,15 @@
 import { CanonicalModifier, EditingKey, FunctionKey, IndividualKey, Key, LetterKey, LogicalKey, Modifier, NamedKey, NavigationKey, NonPunctuationKey, NormalizedKeyboardEvent, NumberKey, PhysicalKey, PhysicalKeyCode, PunctuationKey } from "./key.types.js";
+import { ConflictBehavior, FourModifierHotkey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, ParsedHotkey, ParsedModifiers, RawHotkey, RawModifiers, RegisterableHotkey, SingleModifierHotkey, ThreeModifierHotkey, TwoModifierHotkey } from "./hotkey.types.js";
+import { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
+import { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistration, SequenceRegistrationHandle, SequenceRegistrationView, Target, createSequenceMatcher, getSequenceManager } from "./sequence-manager.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 { ConflictBehavior, FourModifierHotkey, Hotkey, HotkeyCallback, HotkeyCallbackContext, HotkeyMeta, ParsedHotkey, ParsedModifiers, RawHotkey, RawModifiers, RegisterableHotkey, SingleModifierHotkey, ThreeModifierHotkey, TwoModifierHotkey } from "./hotkey.types.js";
 import { DisplayHotkey, FormatDisplayOptions, formatForDisplay, formatHotkey, formatHotkeySequence, formatWithLabels } from "./format.js";
 import { hasNonModifierKey, isModifierKey, normalizeHotkey, normalizeHotkeyFromEvent, normalizeHotkeyFromParsed, normalizeRegisterableHotkey, parseHotkey, parseKeyboardEvent, parseRegisterableHotkey, rawHotkeyToParsedHotkey } from "./parse.js";
 import { ValidationResult, assertValidHotkey, checkHotkey, validateHotkey } from "./validate.js";
 import { CreateHotkeyHandlerOptions, KeyboardEventMatch, MultiHotkeyHandler, areHotkeysEqual, createHotkeyHandler, createMultiHotkeyHandler, matchesKeyboardEvent } from "./match.js";
 import { HeldModifierOptions, matchesHeldModifiers } from "./hint.js";
-import { HotkeyManager, HotkeyOptions, HotkeyRegistration, HotkeyRegistrationHandle, HotkeyRegistrationView, getHotkeyManager, toHotkeyRegistrationView } from "./hotkey-manager.js";
-import { DEFAULT_SEQUENCE_TIMEOUT, HotkeySequence, SequenceManager, SequenceOptions, SequenceRegistration, SequenceRegistrationHandle, SequenceRegistrationView, Target, createSequenceMatcher, getSequenceManager } from "./sequence-manager.js";
 import { HotkeyConflict, HotkeyConflictOptions, findHotkeyConflicts } from "./conflicts.js";
 import { KeyStateTracker, KeyStateTrackerState, getKeyStateTracker } from "./key-state-tracker.js";
 import { HotkeyRecorderValidationContext, HotkeySequenceRecorderValidationContext, RecorderKeyMode, RecorderOptions, RecorderRejection } from "./recorder-options.js";

package/dist/parse.d.ts

@@ -1,6 +1,6 @@
 import { Key } from "./key.types.js";
-import { MODIFIER_ALIASES } from "./constants.js";
 import { Hotkey, ParsedHotkey, RawHotkey, RegisterableHotkey } from "./hotkey.types.js";
+import { MODIFIER_ALIASES } from "./constants.js";
 //#region src/parse.d.ts
 /**
  * Parses a hotkey string into its component parts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/hotkeys",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Type-safe, framework-agnostic keyboard hotkey management for the browser",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -27,6 +27,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": "./dist/index.js",
+    "./adapter": "./dist/adapter.js",
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -37,7 +38,7 @@
     "dist"
   ],
   "dependencies": {
-    "@tanstack/store": "^0.11.1"
+    "@tanstack/store": "^0.11.2"
   },
   "scripts": {
     "clean": "premove ./build ./dist",