@tanstack/angular-hotkeys 0.3.3

package/dist/injectHotkeySequence.d.ts

@@ -0,0 +1,35 @@
+import { HotkeyCallback, HotkeySequence, SequenceOptions } from "@tanstack/hotkeys";
+
+//#region src/injectHotkeySequence.d.ts
+interface InjectHotkeySequenceOptions extends Omit<SequenceOptions, 'enabled'> {
+  /** Whether the sequence is enabled. Defaults to true. */
+  enabled?: boolean;
+}
+/**
+ * Angular inject-based API for registering a keyboard shortcut sequence (Vim-style).
+ *
+ * Allows you to register multi-key sequences like 'g g' or 'd d' that trigger
+ * when the full sequence is pressed within a timeout.
+ *
+ * @param sequence - Array of hotkey strings that form the sequence (or getter function)
+ * @param callback - Function to call when the sequence is completed
+ * @param options - Options for the sequence behavior (or getter function)
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class VimEditorComponent {
+ *   lastSequence = signal<string | null>(null)
+ *
+ *   constructor() {
+ *     injectHotkeySequence(['G', 'G'], () => this.lastSequence.set('gg → Go to top'))
+ *     injectHotkeySequence(['D', 'D'], () => this.lastSequence.set('dd → Delete line'))
+ *     injectHotkeySequence(['C', 'I', 'W'], () => this.lastSequence.set('ciw'), { timeout: 500 })
+ *   }
+ * }
+ * ```
+ */
+declare function injectHotkeySequence(sequence: HotkeySequence | (() => HotkeySequence), callback: HotkeyCallback, options?: InjectHotkeySequenceOptions | (() => InjectHotkeySequenceOptions)): void;
+//#endregion
+export { InjectHotkeySequenceOptions, injectHotkeySequence };
+//# sourceMappingURL=injectHotkeySequence.d.ts.map

package/dist/injectHotkeySequence.js

@@ -0,0 +1,55 @@
+import { injectDefaultHotkeysOptions } from "./hotkeys-provider.js";
+import { getSequenceManager } from "@tanstack/hotkeys";
+import { effect } from "@angular/core";
+
+//#region src/injectHotkeySequence.ts
+/**
+* Angular inject-based API for registering a keyboard shortcut sequence (Vim-style).
+*
+* Allows you to register multi-key sequences like 'g g' or 'd d' that trigger
+* when the full sequence is pressed within a timeout.
+*
+* @param sequence - Array of hotkey strings that form the sequence (or getter function)
+* @param callback - Function to call when the sequence is completed
+* @param options - Options for the sequence behavior (or getter function)
+*
+* @example
+* ```ts
+* @Component({ ... })
+* export class VimEditorComponent {
+*   lastSequence = signal<string | null>(null)
+*
+*   constructor() {
+*     injectHotkeySequence(['G', 'G'], () => this.lastSequence.set('gg → Go to top'))
+*     injectHotkeySequence(['D', 'D'], () => this.lastSequence.set('dd → Delete line'))
+*     injectHotkeySequence(['C', 'I', 'W'], () => this.lastSequence.set('ciw'), { timeout: 500 })
+*   }
+* }
+* ```
+*/
+function injectHotkeySequence(sequence, callback, options = {}) {
+	const defaultOptions = injectDefaultHotkeysOptions();
+	effect((onCleanup) => {
+		const resolvedSequence = typeof sequence === "function" ? sequence() : sequence;
+		const resolvedOptions = typeof options === "function" ? options() : options;
+		const { enabled = true, ...sequenceOptions } = {
+			...defaultOptions.hotkeySequence,
+			...resolvedOptions
+		};
+		if (!enabled || resolvedSequence.length === 0) return;
+		const manager = getSequenceManager();
+		const registerOptions = {
+			...sequenceOptions,
+			enabled: true,
+			target: sequenceOptions.target ?? (typeof document !== "undefined" ? document : void 0)
+		};
+		const handle = manager.register(resolvedSequence, callback, registerOptions);
+		onCleanup(() => {
+			if (handle.isActive) handle.unregister();
+		});
+	});
+}
+
+//#endregion
+export { injectHotkeySequence };
+//# sourceMappingURL=injectHotkeySequence.js.map

package/dist/injectHotkeySequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectHotkeySequence.js","names":[],"sources":["../src/injectHotkeySequence.ts"],"sourcesContent":["import { effect } from '@angular/core'\nimport { getSequenceManager } from '@tanstack/hotkeys'\nimport { injectDefaultHotkeysOptions } from './hotkeys-provider'\nimport type {\n  HotkeyCallback,\n  HotkeySequence,\n  SequenceOptions,\n} from '@tanstack/hotkeys'\n\nexport interface InjectHotkeySequenceOptions extends Omit<\n  SequenceOptions,\n  'enabled'\n> {\n  /** Whether the sequence is enabled. Defaults to true. */\n  enabled?: boolean\n}\n\n/**\n * Angular inject-based API for registering a keyboard shortcut sequence (Vim-style).\n *\n * Allows you to register multi-key sequences like 'g g' or 'd d' that trigger\n * when the full sequence is pressed within a timeout.\n *\n * @param sequence - Array of hotkey strings that form the sequence (or getter function)\n * @param callback - Function to call when the sequence is completed\n * @param options - Options for the sequence behavior (or getter function)\n *\n * @example\n * ```ts\n * @Component({ ... })\n * export class VimEditorComponent {\n *   lastSequence = signal<string | null>(null)\n *\n *   constructor() {\n *     injectHotkeySequence(['G', 'G'], () => this.lastSequence.set('gg → Go to top'))\n *     injectHotkeySequence(['D', 'D'], () => this.lastSequence.set('dd → Delete line'))\n *     injectHotkeySequence(['C', 'I', 'W'], () => this.lastSequence.set('ciw'), { timeout: 500 })\n *   }\n * }\n * ```\n */\nexport function injectHotkeySequence(\n  sequence: HotkeySequence | (() => HotkeySequence),\n  callback: HotkeyCallback,\n  options:\n    | InjectHotkeySequenceOptions\n    | (() => InjectHotkeySequenceOptions) = {},\n): void {\n  const defaultOptions = injectDefaultHotkeysOptions()\n\n  effect((onCleanup) => {\n    // Resolve reactive values\n    const resolvedSequence =\n      typeof sequence === 'function' ? sequence() : sequence\n    const resolvedOptions = typeof options === 'function' ? options() : options\n\n    const mergedOptions = {\n      ...defaultOptions.hotkeySequence,\n      ...resolvedOptions,\n    } as InjectHotkeySequenceOptions\n\n    const { enabled = true, ...sequenceOptions } = mergedOptions\n\n    if (!enabled || resolvedSequence.length === 0) {\n      return\n    }\n\n    const manager = getSequenceManager()\n\n    // Pass through options; default target to document when not provided\n    const registerOptions: SequenceOptions = {\n      ...sequenceOptions,\n      enabled: true,\n      target:\n        sequenceOptions.target ??\n        (typeof document !== 'undefined' ? document : undefined),\n    }\n\n    const handle = manager.register(resolvedSequence, callback, registerOptions)\n\n    onCleanup(() => {\n      if (handle.isActive) {\n        handle.unregister()\n      }\n    })\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,qBACd,UACA,UACA,UAE0C,EAAE,EACtC;CACN,MAAM,iBAAiB,6BAA6B;AAEpD,SAAQ,cAAc;EAEpB,MAAM,mBACJ,OAAO,aAAa,aAAa,UAAU,GAAG;EAChD,MAAM,kBAAkB,OAAO,YAAY,aAAa,SAAS,GAAG;EAOpE,MAAM,EAAE,UAAU,MAAM,GAAG,oBALL;GACpB,GAAG,eAAe;GAClB,GAAG;GACJ;AAID,MAAI,CAAC,WAAW,iBAAiB,WAAW,EAC1C;EAGF,MAAM,UAAU,oBAAoB;EAGpC,MAAM,kBAAmC;GACvC,GAAG;GACH,SAAS;GACT,QACE,gBAAgB,WACf,OAAO,aAAa,cAAc,WAAW;GACjD;EAED,MAAM,SAAS,QAAQ,SAAS,kBAAkB,UAAU,gBAAgB;AAE5E,kBAAgB;AACd,OAAI,OAAO,SACT,QAAO,YAAY;IAErB;GACF"}

package/dist/injectKeyHold.cjs

@@ -0,0 +1,49 @@
+let _tanstack_hotkeys = require("@tanstack/hotkeys");
+let _angular_core = require("@angular/core");
+let _tanstack_angular_store = require("@tanstack/angular-store");
+
+//#region src/injectKeyHold.ts
+/**
+* Angular inject-based API that returns a signal that is true when the given key is held.
+*
+* Subscribes to the global KeyStateTracker and uses a computed to determine
+* if the specified key is held.
+*
+* @param key - The key to check (e.g. 'Shift', 'Control', 'Space') - can be a getter function
+* @returns Signal that returns true if the key is currently held down
+*
+* @example
+* ```ts
+* @Component({
+*   template: `{{ isShiftHeld() ? 'Shift is pressed!' : 'Press Shift' }}`,
+* })
+* export class ShiftIndicatorComponent {
+*   isShiftHeld = injectKeyHold('Shift')
+* }
+* ```
+*
+* @example
+* ```ts
+* @Component({
+*   template: `
+*     <span [style.opacity]="ctrl() ? 1 : 0.3">Ctrl</span>
+*     <span [style.opacity]="shift() ? 1 : 0.3">Shift</span>
+*   `,
+* })
+* export class ModifierIndicatorsComponent {
+*   ctrl = injectKeyHold('Control')
+*   shift = injectKeyHold('Shift')
+* }
+* ```
+*/
+function injectKeyHold(key) {
+	const heldKeysSelector = (0, _tanstack_angular_store.injectStore)((0, _tanstack_hotkeys.getKeyStateTracker)().store, (state) => state.heldKeys);
+	return (0, _angular_core.computed)(() => {
+		const normalizedKey = (typeof key === "function" ? key() : key).toLowerCase();
+		return heldKeysSelector().some((heldKey) => heldKey.toLowerCase() === normalizedKey);
+	});
+}
+
+//#endregion
+exports.injectKeyHold = injectKeyHold;
+//# sourceMappingURL=injectKeyHold.cjs.map

package/dist/injectKeyHold.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectKeyHold.cjs","names":[],"sources":["../src/injectKeyHold.ts"],"sourcesContent":["import { computed } from '@angular/core'\nimport { injectStore } from '@tanstack/angular-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\nimport type { HeldKey } from '@tanstack/hotkeys'\nimport type { Signal } from '@angular/core'\n\n/**\n * Angular inject-based API that returns a signal that is true when the given key is held.\n *\n * Subscribes to the global KeyStateTracker and uses a computed to determine\n * if the specified key is held.\n *\n * @param key - The key to check (e.g. 'Shift', 'Control', 'Space') - can be a getter function\n * @returns Signal that returns true if the key is currently held down\n *\n * @example\n * ```ts\n * @Component({\n *   template: `{{ isShiftHeld() ? 'Shift is pressed!' : 'Press Shift' }}`,\n * })\n * export class ShiftIndicatorComponent {\n *   isShiftHeld = injectKeyHold('Shift')\n * }\n * ```\n *\n * @example\n * ```ts\n * @Component({\n *   template: `\n *     <span [style.opacity]=\"ctrl() ? 1 : 0.3\">Ctrl</span>\n *     <span [style.opacity]=\"shift() ? 1 : 0.3\">Shift</span>\n *   `,\n * })\n * export class ModifierIndicatorsComponent {\n *   ctrl = injectKeyHold('Control')\n *   shift = injectKeyHold('Shift')\n * }\n * ```\n */\nexport function injectKeyHold(key: HeldKey | (() => HeldKey)): Signal<boolean> {\n  const tracker = getKeyStateTracker()\n  const heldKeysSelector = injectStore(tracker.store, (state) => state.heldKeys)\n\n  return computed(() => {\n    const resolvedKey = typeof key === 'function' ? key() : key\n    const normalizedKey = resolvedKey.toLowerCase()\n\n    return heldKeysSelector().some(\n      (heldKey) => heldKey.toLowerCase() === normalizedKey,\n    )\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,cAAc,KAAiD;CAE7E,MAAM,uGAD8B,CACS,QAAQ,UAAU,MAAM,SAAS;AAE9E,0CAAsB;EAEpB,MAAM,iBADc,OAAO,QAAQ,aAAa,KAAK,GAAG,KACtB,aAAa;AAE/C,SAAO,kBAAkB,CAAC,MACvB,YAAY,QAAQ,aAAa,KAAK,cACxC;GACD"}

package/dist/injectKeyHold.d.cts

@@ -0,0 +1,41 @@
+import { HeldKey } from "@tanstack/hotkeys";
+import { Signal } from "@angular/core";
+
+//#region src/injectKeyHold.d.ts
+/**
+ * Angular inject-based API that returns a signal that is true when the given key is held.
+ *
+ * Subscribes to the global KeyStateTracker and uses a computed to determine
+ * if the specified key is held.
+ *
+ * @param key - The key to check (e.g. 'Shift', 'Control', 'Space') - can be a getter function
+ * @returns Signal that returns true if the key is currently held down
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `{{ isShiftHeld() ? 'Shift is pressed!' : 'Press Shift' }}`,
+ * })
+ * export class ShiftIndicatorComponent {
+ *   isShiftHeld = injectKeyHold('Shift')
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `
+ *     <span [style.opacity]="ctrl() ? 1 : 0.3">Ctrl</span>
+ *     <span [style.opacity]="shift() ? 1 : 0.3">Shift</span>
+ *   `,
+ * })
+ * export class ModifierIndicatorsComponent {
+ *   ctrl = injectKeyHold('Control')
+ *   shift = injectKeyHold('Shift')
+ * }
+ * ```
+ */
+declare function injectKeyHold(key: HeldKey | (() => HeldKey)): Signal<boolean>;
+//#endregion
+export { injectKeyHold };
+//# sourceMappingURL=injectKeyHold.d.cts.map

package/dist/injectKeyHold.d.ts

@@ -0,0 +1,41 @@
+import { HeldKey } from "@tanstack/hotkeys";
+import { Signal } from "@angular/core";
+
+//#region src/injectKeyHold.d.ts
+/**
+ * Angular inject-based API that returns a signal that is true when the given key is held.
+ *
+ * Subscribes to the global KeyStateTracker and uses a computed to determine
+ * if the specified key is held.
+ *
+ * @param key - The key to check (e.g. 'Shift', 'Control', 'Space') - can be a getter function
+ * @returns Signal that returns true if the key is currently held down
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `{{ isShiftHeld() ? 'Shift is pressed!' : 'Press Shift' }}`,
+ * })
+ * export class ShiftIndicatorComponent {
+ *   isShiftHeld = injectKeyHold('Shift')
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `
+ *     <span [style.opacity]="ctrl() ? 1 : 0.3">Ctrl</span>
+ *     <span [style.opacity]="shift() ? 1 : 0.3">Shift</span>
+ *   `,
+ * })
+ * export class ModifierIndicatorsComponent {
+ *   ctrl = injectKeyHold('Control')
+ *   shift = injectKeyHold('Shift')
+ * }
+ * ```
+ */
+declare function injectKeyHold(key: HeldKey | (() => HeldKey)): Signal<boolean>;
+//#endregion
+export { injectKeyHold };
+//# sourceMappingURL=injectKeyHold.d.ts.map

package/dist/injectKeyHold.js

@@ -0,0 +1,49 @@
+import { getKeyStateTracker } from "@tanstack/hotkeys";
+import { computed } from "@angular/core";
+import { injectStore } from "@tanstack/angular-store";
+
+//#region src/injectKeyHold.ts
+/**
+* Angular inject-based API that returns a signal that is true when the given key is held.
+*
+* Subscribes to the global KeyStateTracker and uses a computed to determine
+* if the specified key is held.
+*
+* @param key - The key to check (e.g. 'Shift', 'Control', 'Space') - can be a getter function
+* @returns Signal that returns true if the key is currently held down
+*
+* @example
+* ```ts
+* @Component({
+*   template: `{{ isShiftHeld() ? 'Shift is pressed!' : 'Press Shift' }}`,
+* })
+* export class ShiftIndicatorComponent {
+*   isShiftHeld = injectKeyHold('Shift')
+* }
+* ```
+*
+* @example
+* ```ts
+* @Component({
+*   template: `
+*     <span [style.opacity]="ctrl() ? 1 : 0.3">Ctrl</span>
+*     <span [style.opacity]="shift() ? 1 : 0.3">Shift</span>
+*   `,
+* })
+* export class ModifierIndicatorsComponent {
+*   ctrl = injectKeyHold('Control')
+*   shift = injectKeyHold('Shift')
+* }
+* ```
+*/
+function injectKeyHold(key) {
+	const heldKeysSelector = injectStore(getKeyStateTracker().store, (state) => state.heldKeys);
+	return computed(() => {
+		const normalizedKey = (typeof key === "function" ? key() : key).toLowerCase();
+		return heldKeysSelector().some((heldKey) => heldKey.toLowerCase() === normalizedKey);
+	});
+}
+
+//#endregion
+export { injectKeyHold };
+//# sourceMappingURL=injectKeyHold.js.map

package/dist/injectKeyHold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectKeyHold.js","names":[],"sources":["../src/injectKeyHold.ts"],"sourcesContent":["import { computed } from '@angular/core'\nimport { injectStore } from '@tanstack/angular-store'\nimport { getKeyStateTracker } from '@tanstack/hotkeys'\nimport type { HeldKey } from '@tanstack/hotkeys'\nimport type { Signal } from '@angular/core'\n\n/**\n * Angular inject-based API that returns a signal that is true when the given key is held.\n *\n * Subscribes to the global KeyStateTracker and uses a computed to determine\n * if the specified key is held.\n *\n * @param key - The key to check (e.g. 'Shift', 'Control', 'Space') - can be a getter function\n * @returns Signal that returns true if the key is currently held down\n *\n * @example\n * ```ts\n * @Component({\n *   template: `{{ isShiftHeld() ? 'Shift is pressed!' : 'Press Shift' }}`,\n * })\n * export class ShiftIndicatorComponent {\n *   isShiftHeld = injectKeyHold('Shift')\n * }\n * ```\n *\n * @example\n * ```ts\n * @Component({\n *   template: `\n *     <span [style.opacity]=\"ctrl() ? 1 : 0.3\">Ctrl</span>\n *     <span [style.opacity]=\"shift() ? 1 : 0.3\">Shift</span>\n *   `,\n * })\n * export class ModifierIndicatorsComponent {\n *   ctrl = injectKeyHold('Control')\n *   shift = injectKeyHold('Shift')\n * }\n * ```\n */\nexport function injectKeyHold(key: HeldKey | (() => HeldKey)): Signal<boolean> {\n  const tracker = getKeyStateTracker()\n  const heldKeysSelector = injectStore(tracker.store, (state) => state.heldKeys)\n\n  return computed(() => {\n    const resolvedKey = typeof key === 'function' ? key() : key\n    const normalizedKey = resolvedKey.toLowerCase()\n\n    return heldKeysSelector().some(\n      (heldKey) => heldKey.toLowerCase() === normalizedKey,\n    )\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAgB,cAAc,KAAiD;CAE7E,MAAM,mBAAmB,YADT,oBAAoB,CACS,QAAQ,UAAU,MAAM,SAAS;AAE9E,QAAO,eAAe;EAEpB,MAAM,iBADc,OAAO,QAAQ,aAAa,KAAK,GAAG,KACtB,aAAa;AAE/C,SAAO,kBAAkB,CAAC,MACvB,YAAY,QAAQ,aAAa,KAAK,cACxC;GACD"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tanstack/angular-hotkeys",
+  "version": "0.3.3",
+  "description": "Angular adapter for TanStack Hotkeys",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/hotkeys.git",
+    "directory": "packages/angular-hotkeys"
+  },
+  "homepage": "https://tanstack.com/hotkeys",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "angular",
+    "tanstack",
+    "hotkeys",
+    "keyboard",
+    "shortcuts"
+  ],
+  "scripts": {
+    "clean": "premove ./build ./dist",
+    "lint": "eslint ./src",
+    "lint:fix": "eslint ./src --fix",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc",
+    "build": "tsdown"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@tanstack/angular-store": "^0.9.2",
+    "@tanstack/hotkeys": "workspace:*"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=19.0.0",
+    "@angular/core": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@angular/common": "^21.2.1",
+    "@angular/core": "^21.2.1",
+    "@angular/platform-browser-dynamic": "^21.2.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/hotkeys-provider.ts

@@ -0,0 +1,40 @@
+import { InjectionToken, inject } from '@angular/core'
+import type { HotkeyRecorderOptions } from '@tanstack/hotkeys'
+import type { InjectHotkeyOptions } from './injectHotkey'
+import type { InjectHotkeySequenceOptions } from './injectHotkeySequence'
+import type { StaticProvider } from '@angular/core'
+
+export interface HotkeysProviderOptions {
+  hotkey?: Partial<InjectHotkeyOptions>
+  hotkeyRecorder?: Partial<HotkeyRecorderOptions>
+  hotkeySequence?: Partial<InjectHotkeySequenceOptions>
+}
+
+export interface HotkeysContextValue {
+  readonly defaultOptions: HotkeysProviderOptions
+}
+
+export const HOTKEYS_INJECTION_TOKEN = new InjectionToken<HotkeysContextValue>(
+  'HOTKEYS_INJECTION_TOKEN',
+  {
+    providedIn: 'root',
+    factory: () => ({ defaultOptions: {} }),
+  },
+)
+
+export function provideHotkeys(
+  defaultOptions: HotkeysProviderOptions,
+): StaticProvider {
+  return {
+    provide: HOTKEYS_INJECTION_TOKEN,
+    useValue: { defaultOptions },
+  }
+}
+
+export function injectHotkeysContext(): HotkeysContextValue {
+  return inject(HOTKEYS_INJECTION_TOKEN)
+}
+
+export function injectDefaultHotkeysOptions(): HotkeysProviderOptions {
+  return injectHotkeysContext().defaultOptions
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// Re-export everything from the core package
+export * from '@tanstack/hotkeys'
+
+// Provider
+export * from './hotkeys-provider'
+
+// Angular-specific primitives
+export * from './injectHotkey'
+export * from './injectHotkeySequence'
+export * from './injectHeldKeys'
+export * from './injectHeldKeyCodes'
+export * from './injectKeyHold'
+export * from './injectHotkeyRecorder'

package/src/injectHeldKeyCodes.ts

@@ -0,0 +1,31 @@
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+import { injectStore } from '@tanstack/angular-store'
+import type { Signal } from '@angular/core'
+
+/**
+ * Angular inject-based API that returns a signal of a map from held key names to their physical `event.code` values.
+ *
+ * Useful for debugging which physical key was pressed (e.g. distinguishing
+ * left vs right Shift via "ShiftLeft" / "ShiftRight").
+ *
+ * @returns Signal of record mapping normalized key names to their `event.code` values
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `
+ *     @for (key of heldKeys(); track key) {
+ *       <kbd>{{ key }} <small>{{ heldCodes()[key] }}</small></kbd>
+ *     }
+ *   `,
+ * })
+ * export class KeyDebugComponent {
+ *   heldKeys = injectHeldKeys()
+ *   heldCodes = injectHeldKeyCodes()
+ * }
+ * ```
+ */
+export function injectHeldKeyCodes(): Signal<Record<string, string>> {
+  const tracker = getKeyStateTracker()
+  return injectStore(tracker.store, (state) => state.heldCodes)
+}

package/src/injectHeldKeys.ts

@@ -0,0 +1,26 @@
+import { getKeyStateTracker } from '@tanstack/hotkeys'
+import { injectStore } from '@tanstack/angular-store'
+import type { Signal } from '@angular/core'
+
+/**
+ * Angular inject-based API that returns a signal of currently held keyboard keys.
+ *
+ * Subscribes to the global KeyStateTracker and updates whenever keys are
+ * pressed or released.
+ *
+ * @returns Signal of array of currently held key names
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `<div>Currently pressed: {{ heldKeys().join(' + ') || 'None' }}</div>`,
+ * })
+ * export class KeyDisplayComponent {
+ *   heldKeys = injectHeldKeys()
+ * }
+ * ```
+ */
+export function injectHeldKeys(): Signal<Array<string>> {
+  const tracker = getKeyStateTracker()
+  return injectStore(tracker.store, (state) => state.heldKeys)
+}

package/src/injectHotkey.ts

@@ -0,0 +1,145 @@
+import { effect } from '@angular/core'
+import {
+  detectPlatform,
+  formatHotkey,
+  getHotkeyManager,
+  rawHotkeyToParsedHotkey,
+} from '@tanstack/hotkeys'
+import { injectDefaultHotkeysOptions } from './hotkeys-provider'
+import type {
+  Hotkey,
+  HotkeyCallback,
+  HotkeyOptions,
+  RegisterableHotkey,
+} from '@tanstack/hotkeys'
+
+export interface InjectHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
+  /**
+   * The DOM element to attach the event listener to.
+   * Can be a direct DOM element, an accessor (for reactive targets that become
+   * available after mount), or null. Defaults to document.
+   * When using scoped targets, pass an accessor: () => ({ target: elementSignal() })
+   * so the hotkey waits for the element to be attached before registering.
+   */
+  target?: HTMLElement | Document | Window | null
+}
+
+/**
+ * Angular inject-based API for registering a keyboard hotkey.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * The callback receives both the keyboard event and a context object
+ * containing the hotkey string and parsed hotkey.
+ *
+ * Call in an injection context (e.g. constructor or field initializer).
+ * Uses effect() to track reactive dependencies and update registration
+ * when options or the callback change.
+ *
+ * @param hotkey - The hotkey string (e.g. 'Mod+S', 'Escape') or getter function
+ * @param callback - The function to call when the hotkey is pressed
+ * @param options - Options for the hotkey behavior, or getter for reactive options
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class SaveButtonComponent {
+ *   private readonly saveCount = signal(0)
+ *
+ *   constructor() {
+ *     injectHotkey('Mod+S', (event, { hotkey }) => {
+ *       event.preventDefault()
+ *       this.saveCount.update(c => c + 1)
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class ModalComponent {
+ *   isOpen = signal(true)
+ *
+ *   constructor() {
+ *     injectHotkey('Escape', () => this.close(), () => ({ enabled: this.isOpen() }))
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class EditorComponent {
+ *   private readonly editorRef = viewChild<ElementRef<HTMLDivElement>>('editorRef')
+ *
+ *   constructor() {
+ *     injectHotkey('Mod+B', () => this.toggleBold(), () => ({
+ *       target: this.editorRef()?.nativeElement ?? null,
+ *     }))
+ *   }
+ * }
+ * ```
+ */
+export function injectHotkey(
+  hotkey: RegisterableHotkey | (() => RegisterableHotkey),
+  callback: HotkeyCallback,
+  options: InjectHotkeyOptions | (() => InjectHotkeyOptions) = {},
+): void {
+  const defaultOptions = injectDefaultHotkeysOptions()
+  const manager = getHotkeyManager()
+
+  effect((onCleanup) => {
+    // Resolve reactive values
+    const resolvedHotkey = typeof hotkey === 'function' ? hotkey() : hotkey
+    const resolvedOptions = typeof options === 'function' ? options() : options
+
+    const mergedOptions = {
+      ...defaultOptions.hotkey,
+      ...resolvedOptions,
+    } as InjectHotkeyOptions
+
+    // Normalize to hotkey string
+    const platform = mergedOptions.platform ?? detectPlatform()
+    const hotkeyString: Hotkey =
+      typeof resolvedHotkey === 'string'
+        ? resolvedHotkey
+        : (formatHotkey(
+            rawHotkeyToParsedHotkey(resolvedHotkey, platform),
+          ) as Hotkey)
+
+    // Resolve target: when explicitly provided (even as null), use it and skip if null.
+    // When not provided, default to document. Matches React's ref handling.
+    const resolvedTarget =
+      'target' in mergedOptions
+        ? (mergedOptions.target ?? null)
+        : typeof document !== 'undefined'
+          ? document
+          : null
+
+    if (!resolvedTarget) {
+      return
+    }
+
+    // Extract options without target (target is handled separately)
+    const { target: _target, ...optionsWithoutTarget } = mergedOptions
+
+    // Register the hotkey
+    const registration = manager.register(hotkeyString, callback, {
+      ...optionsWithoutTarget,
+      target: resolvedTarget,
+    })
+
+    // Update callback and options on every effect run
+    if (registration.isActive) {
+      registration.callback = callback
+      registration.setOptions(optionsWithoutTarget)
+    }
+
+    // Cleanup on disposal
+    onCleanup(() => {
+      if (registration.isActive) {
+        registration.unregister()
+      }
+    })
+  })
+}