@tanstack/hotkeys 0.13.0 → 0.15.0

package/dist/_registration.js

@@ -4,6 +4,7 @@
 * Omitted: platform, target (resolved at registration), requireReset (HotkeyManager only).
 */
 const defaultHotkeyOptions = {
+	capture: false,
 	preventDefault: true,
 	stopPropagation: true,
 	eventType: "keydown",
@@ -31,7 +32,7 @@ function getDefaultIgnoreInputs(parsedHotkey) {
 function handleConflict(conflictingId, keyDisplay, conflictBehavior, unregister) {
 	if (conflictBehavior === "allow") return;
 	if (conflictBehavior === "warn") {
-		console.warn(`'${keyDisplay}' is already registered. Multiple handlers will be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
+		console.warn(`'${keyDisplay}' is already registered. Multiple handlers may be triggered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to suppress this warning.`);
 		return;
 	}
 	if (conflictBehavior === "error") throw new Error(`'${keyDisplay}' is already registered. Use conflictBehavior: 'replace' to replace the existing handler, or conflictBehavior: 'allow' to allow multiple registrations.`);

package/dist/_target-listeners.js

@@ -0,0 +1,73 @@
+//#region src/_target-listeners.ts
+/** Shares keyboard listeners within each target and capture phase. */
+var TargetListeners = class {
+	dispatch;
+	#targets = /* @__PURE__ */ new Map();
+	#processed = /* @__PURE__ */ new WeakMap();
+	constructor(dispatch) {
+		this.dispatch = dispatch;
+	}
+	add(target, capture, id) {
+		if (typeof document === "undefined") return;
+		let phases = this.#targets.get(target);
+		if (!phases) {
+			phases = /* @__PURE__ */ new Map();
+			this.#targets.set(target, phases);
+		}
+		let group = phases.get(capture);
+		if (!group) {
+			const ids = /* @__PURE__ */ new Set();
+			const listener = (eventType) => (rawEvent) => {
+				const event = rawEvent;
+				let processed = this.#processed.get(event);
+				const first = !processed || processed.groups.has(ids);
+				if (!processed || first) {
+					processed = {
+						ids: /* @__PURE__ */ new Set(),
+						groups: /* @__PURE__ */ new Set()
+					};
+					this.#processed.set(event, processed);
+				}
+				processed.groups.add(ids);
+				const pending = /* @__PURE__ */ new Set();
+				for (const registrationId of ids) if (!processed.ids.has(registrationId)) {
+					processed.ids.add(registrationId);
+					pending.add(registrationId);
+				}
+				this.dispatch(event, target, eventType, capture, pending, first);
+			};
+			group = {
+				ids,
+				keydown: listener("keydown"),
+				keyup: listener("keyup")
+			};
+			phases.set(capture, group);
+			target.addEventListener("keydown", group.keydown, capture);
+			target.addEventListener("keyup", group.keyup, capture);
+		}
+		group.ids.add(id);
+	}
+	remove(target, capture, id) {
+		const phases = this.#targets.get(target);
+		const group = phases?.get(capture);
+		if (!group) return;
+		group.ids.delete(id);
+		if (group.ids.size === 0) {
+			target.removeEventListener("keydown", group.keydown, capture);
+			target.removeEventListener("keyup", group.keyup, capture);
+			phases.delete(capture);
+			if (phases.size === 0) this.#targets.delete(target);
+		}
+	}
+	destroy() {
+		for (const [target, phases] of this.#targets) for (const [capture, group] of phases) {
+			target.removeEventListener("keydown", group.keydown, capture);
+			target.removeEventListener("keyup", group.keyup, capture);
+		}
+		this.#targets.clear();
+		this.#processed = /* @__PURE__ */ new WeakMap();
+	}
+};
+
+//#endregion
+export { TargetListeners };

package/dist/app-hotkeys.d.ts

@@ -3,7 +3,7 @@ import { HotkeyChordOptions, HotkeyRegistrationView, HotkeySequenceOptions } fro
 import { Store } from "@tanstack/store";
 //#region src/app-hotkeys.d.ts
 type Platform = 'mac' | 'windows' | 'linux';
-type DeclaredOptionKeys = 'conflictBehavior' | 'eventType' | 'ignoreInputs' | 'preventDefault' | 'stopPropagation';
+type DeclaredOptionKeys = 'capture' | 'conflictBehavior' | 'eventType' | 'ignoreInputs' | 'preventDefault' | 'stopPropagation';
 /** Declared options for an app hotkey whose default is a chord. */
 export type AppHotkeyChordOptions = Pick<HotkeyChordOptions, DeclaredOptionKeys | 'requireReset'>;
 /** Declared options for an app hotkey whose default is a sequence. */

package/dist/hotkey-manager.d.ts

@@ -8,6 +8,14 @@ export type Target = HTMLElement | Document | Window;
  * Options shared by chords and sequences.
  */
 export interface HotkeyOptions {
+  /**
+   * Listen during capture, before descendant listeners. Defaults to `false` (bubble).
+   * With `stopPropagation: true`, a match on an ancestor prevents the event from
+   * reaching descendant widgets. Other listeners on the same target still run.
+   * Applies to both `keydown` and `keyup`, for chords and sequences.
+   * Changing this option preserves held-key reset state and sequence progress.
+   */
+  capture?: boolean;
   /** Behavior when this hotkey conflicts with an existing registration on the same target. Defaults to 'warn' */
   conflictBehavior?: ConflictBehavior;
   /**
@@ -156,6 +164,9 @@ export interface HotkeyRegistrationHandle<TOptions extends HotkeyOptions = Hotke
   /**
    * Update options (merged with existing options).
    * Useful for updating `enabled`, `preventDefault`, etc. without re-registering.
+   * Changing `capture` moves the listener phase without clearing `requireReset`
+   * state or sequence progress. A registration already processed for an event
+   * cannot process it again in another phase.
    */
   setOptions: (options: Partial<TOptions>) => void;
   /** Unregister this hotkey */
@@ -165,8 +176,8 @@ export interface HotkeyRegistrationHandle<TOptions extends HotkeyOptions = Hotke
  * Singleton manager for hotkey registrations, including sequences.
  *
  * This class provides a centralized way to register and manage keyboard
- * hotkeys. It attaches one keydown and one keyup listener per target,
- * regardless of how many hotkeys are registered.
+ * hotkeys. It shares one keydown and one keyup listener per target and
+ * capture phase across registrations.
  *
  * Sequences (Vim-style hotkeys such as `['G', 'G']`) match when every step is
  * pressed within the timeout. Modifier-only events (Shift, Control, Alt, or

package/dist/hotkey-manager.js

@@ -5,7 +5,8 @@ import { isHotkeySequence, isModifierKey, parseHotkey, rawHotkeyToParsedHotkey,
 import { formatHotkey } from "./format.js";
 import { matchKeyboardEvent } from "./_match.js";
 import { DEFAULT_SEQUENCE_TIMEOUT, areHotkeysEqual } from "./match.js";
-import { isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
+import { getTargetDocument, isEventForTarget, shouldIgnoreInputEvent } from "./_event-target.js";
+import { TargetListeners } from "./_target-listeners.js";
 import { isRecordingEvent } from "./_recording-guard.js";
 import { defaultHotkeyOptions, getDefaultIgnoreInputs, handleConflict, optionsEqual } from "./_registration.js";
 import { Store } from "@tanstack/store";
@@ -73,8 +74,8 @@ function formatForMessage(hotkey) {
 * Singleton manager for hotkey registrations, including sequences.
 *
 * This class provides a centralized way to register and manage keyboard
-* hotkeys. It attaches one keydown and one keyup listener per target,
-* regardless of how many hotkeys are registered.
+* hotkeys. It shares one keydown and one keyup listener per target and
+* capture phase across registrations.
 *
 * Sequences (Vim-style hotkeys such as `['G', 'G']`) match when every step is
 * pressed within the timeout. Modifier-only events (Shift, Control, Alt, or
@@ -123,8 +124,11 @@ var HotkeyManager = class HotkeyManager {
 	*/
 	appHotkeys = new Store(null);
 	#platform;
-	#targetListeners = /* @__PURE__ */ new Map();
-	#targetRegistrations = /* @__PURE__ */ new Map();
+	#listeners = new TargetListeners((...args) => this.#processTargetEvent(...args));
+	/** Events that continue a sequence in progress, decided before any listener runs. */
+	#sequenceOwned = /* @__PURE__ */ new WeakMap();
+	/** Physical keys whose keydown a sequence owned, so their repeats and keyup are owned too. */
+	#sequenceOwnedKeys = /* @__PURE__ */ new Set();
 	constructor() {
 		this.#platform = detectPlatform();
 	}
@@ -214,9 +218,7 @@ var HotkeyManager = class HotkeyManager {
 		const conflicting = this.#findConflictingRegistration(registration);
 		if (conflicting) handleConflict(conflicting.id, formatForMessage(registration.hotkey), options.conflictBehavior ?? "warn", (conflictId) => this.#unregister(conflictId));
 		this.registrations.setState((prev) => new Map(prev).set(id, registration));
-		if (!this.#targetRegistrations.has(target)) this.#targetRegistrations.set(target, /* @__PURE__ */ new Set());
-		this.#targetRegistrations.get(target).add(id);
-		this.#ensureListenersForTarget(target);
+		this.#listeners.add(target, !!registration.options.capture, id);
 		const manager = this;
 		return {
 			get id() {
@@ -241,6 +243,11 @@ var HotkeyManager = class HotkeyManager {
 						...optionsForKind(reg.kind, newOptions)
 					};
 					if (optionsEqual(reg.options, options)) return prev;
+					const capture = !!reg.options.capture;
+					if (capture !== !!options.capture) {
+						manager.#listeners.remove(reg.target, capture, id);
+						manager.#listeners.add(reg.target, !!options.capture, id);
+					}
 					return new Map(prev).set(id, {
 						...reg,
 						options
@@ -264,65 +271,40 @@ var HotkeyManager = class HotkeyManager {
 			next.delete(id);
 			return next;
 		});
-		const targetRegs = this.#targetRegistrations.get(target);
-		if (targetRegs) {
-			targetRegs.delete(id);
-			if (targetRegs.size === 0) this.#removeListenersForTarget(target);
-		}
-	}
-	/**
-	* Ensures event listeners are attached for a specific target.
-	*/
-	#ensureListenersForTarget(target) {
-		if (typeof document === "undefined") return;
-		if (this.#targetListeners.has(target)) return;
-		const keydown = (event) => this.#processTargetEvent(event, target, "keydown");
-		const keyup = (event) => this.#processTargetEvent(event, target, "keyup");
-		target.addEventListener("keydown", keydown);
-		target.addEventListener("keyup", keyup);
-		this.#targetListeners.set(target, {
-			keydown,
-			keyup
-		});
+		this.#listeners.remove(target, !!registration.options.capture, id);
 	}
-	/**
-	* Removes event listeners for a specific target.
-	*/
-	#removeListenersForTarget(target) {
-		if (typeof document === "undefined") return;
-		const listeners = this.#targetListeners.get(target);
-		if (!listeners) return;
-		target.removeEventListener("keydown", listeners.keydown);
-		target.removeEventListener("keyup", listeners.keyup);
-		this.#targetListeners.delete(target);
-		this.#targetRegistrations.delete(target);
-	}
-	/** Registrations of one kind on a target, in registration order. */
-	#registrationsOn(target, kind) {
+	/** Registrations of one kind in the listener phase, in registration order. */
+	#registrationsIn(ids, capture, kind) {
 		const result = [];
-		for (const id of this.#targetRegistrations.get(target) ?? []) {
+		for (const id of ids) {
 			const registration = this.registrations.state.get(id);
-			if (registration?.kind === kind) result.push(registration);
+			if (registration?.kind === kind && !!registration.options.capture === capture) result.push(registration);
 		}
 		return result;
 	}
+	/** The live registration, unless it was removed or moved to another phase. */
+	#currentIn(registration, capture) {
+		const current = this.registrations.state.get(registration.id);
+		return current && !!current.options.capture === capture ? current : void 0;
+	}
 	/**
 	* Processes keyboard events for a specific target and event type.
-	* Chords and sequences match independently; both may fire for one event.
+	* A key that continues a sequence in progress belongs to that sequence, so
+	* chords skip it. Chords and first steps of sequences may both fire.
 	*/
-	#processTargetEvent(event, target, eventType) {
-		this.#processChords(event, target, eventType);
-		this.#processSequences(event, target, eventType);
+	#processTargetEvent(event, target, eventType, capture, ids, first) {
+		if (first) this.#sequenceOwned.set(event, this.#isOwnedBySequence(event, eventType));
+		this.#processChords(event, target, eventType, capture, this.#registrationsIn(ids, capture, "chord"));
+		this.#processSequences(event, target, eventType, capture, this.#registrationsIn(ids, capture, "sequence"));
 	}
-	#processChords(event, target, eventType) {
-		const registrations = this.#registrationsOn(target, "chord");
+	#processChords(event, target, eventType, capture, registrations) {
 		if (eventType === "keyup") {
 			for (const registration of registrations) if (registration.hasFired && this.#shouldResetRegistration(registration, event)) {
 				registration.hasFired = false;
 				registration.activeMatch = void 0;
 			}
 		}
-		if (isRecordingEvent(event)) return;
+		if (isRecordingEvent(event) || this.#sequenceOwned.get(event)) return;
 		const matches = /* @__PURE__ */ new Map();
 		let bestScore = 0;
 		for (const registration of registrations) {
@@ -333,9 +315,11 @@ var HotkeyManager = class HotkeyManager {
 				bestScore = Math.max(bestScore, result.score);
 			}
 		}
-		for (const registration of registrations) {
-			const match = matches.get(registration.id);
+		for (const snapshot of registrations) {
+			const match = matches.get(snapshot.id);
 			if (!match?.matched || match.score !== bestScore) continue;
+			const registration = this.#currentIn(snapshot, capture);
+			if (!registration) continue;
 			if (eventType === "keyup") {
 				this.#executeCallback(registration, event);
 				continue;
@@ -343,16 +327,43 @@ var HotkeyManager = class HotkeyManager {
 			if (registration.options.preventDefault) event.preventDefault();
 			if (registration.options.stopPropagation) event.stopPropagation();
 			if (!registration.options.requireReset || !registration.hasFired) {
-				this.#executeCallback(registration, event);
 				if (registration.options.requireReset) {
 					registration.hasFired = true;
 					registration.activeMatch = match.identity;
 				}
+				this.#executeCallback(registration, event);
 			}
 		}
 	}
-	#processSequences(event, target, eventType) {
-		const registrations = this.#registrationsOn(target, "sequence");
+	/**
+	* Whether the event continues or completes a sequence in progress whose
+	* target the event reaches. The repeats and keyup of a keydown that a
+	* sequence owns belong to the sequence too.
+	*/
+	#isOwnedBySequence(event, eventType) {
+		const key = event.code || normalizeKeyName(event.key);
+		if (eventType === "keyup") {
+			const ownedKeydown = this.#sequenceOwnedKeys.delete(key);
+			return this.#continuesSequence(event, eventType) || ownedKeydown;
+		}
+		if (event.repeat) return this.#sequenceOwnedKeys.has(key);
+		const owned = this.#continuesSequence(event, eventType);
+		if (owned) this.#sequenceOwnedKeys.add(key);
+		else this.#sequenceOwnedKeys.delete(key);
+		return owned;
+	}
+	#continuesSequence(event, eventType) {
+		if (isRecordingEvent(event) || normalizeKeyboardEvent(event).isComposing || isModifierKey(normalizeKeyName(event.key))) return false;
+		const path = event.composedPath();
+		const now = Date.now();
+		for (const registration of this.registrations.state.values()) {
+			if (registration.kind !== "sequence" || registration.currentIndex === 0 || !registration.options.enabled || registration.options.eventType !== eventType || now - registration.lastKeyTime > (registration.options.timeout ?? 1e3)) continue;
+			const target = registration.target;
+			if (path.includes(target.nodeType === 1 ? target : getTargetDocument(target)) && !(ignoresInputs(registration) && shouldIgnoreInputEvent(event, target, target)) && matchKeyboardEvent(event, registration.parsedSequence[registration.currentIndex], registration.options.platform).matched) return true;
+		}
+		return false;
+	}
+	#processSequences(event, target, eventType, capture, registrations) {
 		if (registrations.length === 0) return;
 		if (isRecordingEvent(event)) {
 			let changed = false;
@@ -410,7 +421,10 @@ var HotkeyManager = class HotkeyManager {
 			}
 		}
 		if (changed && completed.length === 0) this.#notify();
-		for (const registration of completed) this.#executeCallback(registration, event);
+		for (const snapshot of completed) {
+			const registration = this.#currentIn(snapshot, capture);
+			if (registration) this.#executeCallback(registration, event);
+		}
 	}
 	/**
 	* Executes a hotkey callback with proper event handling.
@@ -517,11 +531,9 @@ var HotkeyManager = class HotkeyManager {
 	* Destroys the manager and removes all listeners.
 	*/
 	destroy() {
-		for (const target of this.#targetListeners.keys()) this.#removeListenersForTarget(target);
+		this.#listeners.destroy();
 		this.registrations.setState(() => /* @__PURE__ */ new Map());
 		this.appHotkeys.setState(() => null);
-		this.#targetListeners.clear();
-		this.#targetRegistrations.clear();
 	}
 };
 /**

package/dist/key-state-tracker.js

@@ -55,6 +55,7 @@ var KeyStateTracker = class KeyStateTracker {
 	#heldEntries = /* @__PURE__ */ new Map();
 	#keydownListener = null;
 	#keyupListener = null;
+	#mouseListener = null;
 	#blurListener = null;
 	constructor() {
 		this.#setupListeners();
@@ -81,6 +82,7 @@ var KeyStateTracker = class KeyStateTracker {
 	#setupListeners() {
 		if (typeof document === "undefined") return;
 		this.#keydownListener = (event) => {
+			let changed = this.#reconcileModifiers(event);
 			const key = normalizeKeyName(event.key);
 			const identity = event.code || `key:${key}`;
 			if (!this.#heldEntries.has(identity)) {
@@ -88,8 +90,9 @@ var KeyStateTracker = class KeyStateTracker {
 					key,
 					code: event.code
 				});
-				this.#syncState();
+				changed = true;
 			}
+			if (changed) this.#syncState();
 		};
 		this.#keyupListener = (event) => {
 			const key = normalizeKeyName(event.key);
@@ -98,22 +101,44 @@ var KeyStateTracker = class KeyStateTracker {
 			if (!event.code) {
 				for (const [entryIdentity, entry] of this.#heldEntries) if (entry.key === key) this.#heldEntries.delete(entryIdentity);
 			}
+			this.#reconcileModifiers(event);
 			if (MODIFIER_KEYS.has(key)) {
 				for (const [entryIdentity, entry] of this.#heldEntries) if (!MODIFIER_KEYS.has(entry.key)) this.#heldEntries.delete(entryIdentity);
 			}
 			this.#syncState();
 		};
+		this.#mouseListener = (event) => {
+			if (this.#reconcileModifiers(event)) this.#syncState();
+		};
 		this.#blurListener = () => {
 			if (this.#heldEntries.size > 0) {
 				this.#heldEntries.clear();
 				this.#syncState();
 			}
 		};
-		document.addEventListener("keydown", this.#keydownListener, true);
-		document.addEventListener("keyup", this.#keyupListener, true);
+		window.addEventListener("keydown", this.#keydownListener, true);
+		window.addEventListener("keyup", this.#keyupListener, true);
+		window.addEventListener("mousemove", this.#mouseListener, true);
+		window.addEventListener("mousedown", this.#mouseListener, true);
 		window.addEventListener("blur", this.#blurListener);
 	}
 	/**
+	* Removes modifiers whose release was missed without a window blur.
+	* Event modifier state is shared by left/right keys, so a true flag keeps
+	* both physical entries until their individual keyup events arrive.
+	* Only real user input counts: events dispatched by page code report no
+	* modifiers and would clear keys the user is still holding.
+	*/
+	#reconcileModifiers(event) {
+		if (!event.isTrusted) return false;
+		let changed = false;
+		for (const [identity, entry] of this.#heldEntries) if (entry.key === "Control" && !event.ctrlKey || entry.key === "Alt" && !event.altKey || entry.key === "Shift" && !event.shiftKey || entry.key === "Meta" && !event.metaKey) {
+			this.#heldEntries.delete(identity);
+			changed = true;
+		}
+		return changed;
+	}
+	/**
 	* Syncs the internal Set to the Store state.
 	*/
 	#syncState() {
@@ -130,13 +155,18 @@ var KeyStateTracker = class KeyStateTracker {
 	#removeListeners() {
 		if (typeof document === "undefined") return;
 		if (this.#keydownListener) {
-			document.removeEventListener("keydown", this.#keydownListener, true);
+			window.removeEventListener("keydown", this.#keydownListener, true);
 			this.#keydownListener = null;
 		}
 		if (this.#keyupListener) {
-			document.removeEventListener("keyup", this.#keyupListener, true);
+			window.removeEventListener("keyup", this.#keyupListener, true);
 			this.#keyupListener = null;
 		}
+		if (this.#mouseListener) {
+			window.removeEventListener("mousemove", this.#mouseListener, true);
+			window.removeEventListener("mousedown", this.#mouseListener, true);
+			this.#mouseListener = null;
+		}
 		if (this.#blurListener) {
 			window.removeEventListener("blur", this.#blurListener);
 			this.#blurListener = null;

package/package.json

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