feat: Add Angular Adapter

.changeset/odd-ties-clap.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/angular-hotkeys': patch
+---
+
+add angular adapter

README.md

@@ -55,8 +55,8 @@ Type-safe keyboard shortcuts for the web. Template-string bindings, parsed objec
 >
 > - [**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/solid-hotkeys)
-> - Angular Hotkeys – needs a contributor!
+> - [**Solid Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/solid/reference)
+> - [**Angular Hotkeys**](https://tanstack.com/hotkeys/latest/docs/framework/angular/reference)
 > - Svelte Hotkeys – needs a contributor!
 > - Vue Hotkeys – needs a contributor!
 

docs/config.json

@@ -168,6 +168,15 @@
               "to": "framework/solid/reference/index"
             }
           ]
+        },
+        {
+          "label": "angular",
+          "children": [
+            {
+              "label": "Angular Inject APIs",
+              "to": "framework/angular/reference/index"
+            }
+          ]
         }
       ]
     },
@@ -248,6 +257,27 @@
               "to": "framework/solid/reference/interfaces/CreateHotkeyOptions"
             }
           ]
+        },
+        {
+          "label": "angular",
+          "children": [
+            {
+              "label": "injectHotkey",
+              "to": "framework/angular/reference/functions/injectHotkey"
+            },
+            {
+              "label": "InjectHotkeyOptions",
+              "to": "framework/angular/reference/interfaces/InjectHotkeyOptions"
+            },
+            {
+              "label": "provideHotkeys",
+              "to": "framework/angular/reference/functions/provideHotkeys"
+            },
+            {
+              "label": "HotkeysProviderOptions",
+              "to": "framework/angular/reference/interfaces/HotkeysProviderOptions"
+            }
+          ]
         }
       ]
     },
@@ -316,6 +346,19 @@
               "to": "framework/solid/reference/interfaces/CreateHotkeySequenceOptions"
             }
           ]
+        },
+        {
+          "label": "angular",
+          "children": [
+            {
+              "label": "injectHotkeySequence",
+              "to": "framework/angular/reference/functions/injectHotkeySequence"
+            },
+            {
+              "label": "InjectHotkeySequenceOptions",
+              "to": "framework/angular/reference/interfaces/InjectHotkeySequenceOptions"
+            }
+          ]
         }
       ]
     },
@@ -368,6 +411,15 @@
               "to": "framework/solid/reference/functions/createKeyHold"
             }
           ]
+        },
+        {
+          "label": "angular",
+          "children": [
+            {
+              "label": "injectKeyHold",
+              "to": "framework/angular/reference/functions/injectKeyHold"
+            }
+          ]
         }
       ]
     },
@@ -432,6 +484,19 @@
               "to": "framework/solid/reference/functions/createHeldKeyCodes"
             }
           ]
+        },
+        {
+          "label": "angular",
+          "children": [
+            {
+              "label": "injectHeldKeys",
+              "to": "framework/angular/reference/functions/injectHeldKeys"
+            },
+            {
+              "label": "injectHeldKeyCodes",
+              "to": "framework/angular/reference/functions/injectHeldKeyCodes"
+            }
+          ]
         }
       ]
     },
@@ -492,6 +557,19 @@
               "to": "framework/solid/reference/interfaces/SolidHotkeyRecorder"
             }
           ]
+        },
+        {
+          "label": "angular",
+          "children": [
+            {
+              "label": "injectHotkeyRecorder",
+              "to": "framework/angular/reference/functions/injectHotkeyRecorder"
+            },
+            {
+              "label": "AngularHotkeyRecorder",
+              "to": "framework/angular/reference/interfaces/AngularHotkeyRecorder"
+            }
+          ]
         }
       ]
     },
@@ -636,4 +714,4 @@
       ]
     }
   ]
-}
+}

docs/framework/angular/reference/functions/injectDefaultHotkeysOptions.md

@@ -0,0 +1,16 @@
+---
+id: injectDefaultHotkeysOptions
+title: injectDefaultHotkeysOptions
+---
+
+# Function: injectDefaultHotkeysOptions()
+
+```ts
+function injectDefaultHotkeysOptions(): HotkeysProviderOptions;
+```
+
+Defined in: [hotkeys-provider.ts:38](https://github.com/TanStack/hotkeys/blob/main/packages/angular-hotkeys/src/hotkeys-provider.ts#L38)
+
+## Returns
+
+[`HotkeysProviderOptions`](../interfaces/HotkeysProviderOptions.md)

docs/framework/angular/reference/functions/injectHeldKeyCodes.md

@@ -0,0 +1,39 @@
+---
+id: injectHeldKeyCodes
+title: injectHeldKeyCodes
+---
+
+# Function: injectHeldKeyCodes()
+
+```ts
+function injectHeldKeyCodes(): Signal<Record<string, string>>;
+```
+
+Defined in: [injectHeldKeyCodes.ts:28](https://github.com/TanStack/hotkeys/blob/main/packages/angular-hotkeys/src/injectHeldKeyCodes.ts#L28)
+
+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`\<`Record`\<`string`, `string`\>\>
+
+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()
+}
+```

docs/framework/angular/reference/functions/injectHeldKeys.md

@@ -0,0 +1,34 @@
+---
+id: injectHeldKeys
+title: injectHeldKeys
+---
+
+# Function: injectHeldKeys()
+
+```ts
+function injectHeldKeys(): Signal<string[]>;
+```
+
+Defined in: [injectHeldKeys.ts:23](https://github.com/TanStack/hotkeys/blob/main/packages/angular-hotkeys/src/injectHeldKeys.ts#L23)
+
+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`\<`string`[]\>
+
+Signal of array of currently held key names
+
+## Example
+
+```ts
+@Component({
+  template: `<div>Currently pressed: {{ heldKeys().join(' + ') || 'None' }}</div>`,
+})
+export class KeyDisplayComponent {
+  heldKeys = injectHeldKeys()
+}
+```

docs/framework/angular/reference/functions/injectHotkey.md

@@ -0,0 +1,89 @@
+---
+id: injectHotkey
+title: injectHotkey
+---
+
+# Function: injectHotkey()
+
+```ts
+function injectHotkey(
+   hotkey, 
+   callback, 
+   options): void;
+```
+
+Defined in: [injectHotkey.ts:83](https://github.com/TanStack/hotkeys/blob/main/packages/angular-hotkeys/src/injectHotkey.ts#L83)
+
+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.
+
+## Parameters
+
+### hotkey
+
+The hotkey string (e.g. 'Mod+S', 'Escape') or getter function
+
+`RegisterableHotkey` | () => `RegisterableHotkey`
+
+### callback
+
+`HotkeyCallback`
+
+The function to call when the hotkey is pressed
+
+### options
+
+Options for the hotkey behavior, or getter for reactive options
+
+[`InjectHotkeyOptions`](../interfaces/InjectHotkeyOptions.md) | () => [`InjectHotkeyOptions`](../interfaces/InjectHotkeyOptions.md)
+
+## Returns
+
+`void`
+
+## Examples
+
+```ts
+@Component({ ... })
+export class SaveButtonComponent {
+  private readonly saveCount = signal(0)
+
+  constructor() {
+    injectHotkey('Mod+S', (event, { hotkey }) => {
+      event.preventDefault()
+      this.saveCount.update(c => c + 1)
+    })
+  }
+}
+```
+
+```ts
+@Component({ ... })
+export class ModalComponent {
+  isOpen = signal(true)
+
+  constructor() {
+    injectHotkey('Escape', () => this.close(), () => ({ enabled: this.isOpen() }))
+  }
+}
+```
+
+```ts
+@Component({ ... })
+export class EditorComponent {
+  private readonly editorRef = viewChild<ElementRef<HTMLDivElement>>('editorRef')
+
+  constructor() {
+    injectHotkey('Mod+B', () => this.toggleBold(), () => ({
+      target: this.editorRef()?.nativeElement ?? null,
+    }))
+  }
+}
+```

docs/framework/angular/reference/functions/injectHotkeyRecorder.md

@@ -0,0 +1,53 @@
+---
+id: injectHotkeyRecorder
+title: injectHotkeyRecorder
+---
+
+# Function: injectHotkeyRecorder()
+
+```ts
+function injectHotkeyRecorder(options): AngularHotkeyRecorder;
+```
+
+Defined in: [injectHotkeyRecorder.ts:58](https://github.com/TanStack/hotkeys/blob/main/packages/angular-hotkeys/src/injectHotkeyRecorder.ts#L58)
+
+Angular inject-based API for recording keyboard shortcuts.
+
+Thin wrapper around the framework-agnostic HotkeyRecorder class: captures
+keyboard events, converts them to hotkey strings, and handles Escape to
+cancel or Backspace/Delete to clear.
+
+## Parameters
+
+### options
+
+Configuration options for the recorder (or getter)
+
+`HotkeyRecorderOptions` | () => `HotkeyRecorderOptions`
+
+## Returns
+
+[`AngularHotkeyRecorder`](../interfaces/AngularHotkeyRecorder.md)
+
+Object with recording state signals and control functions
+
+## Example
+
+```ts
+@Component({ ... })
+export class ShortcutSettingsComponent {
+  shortcut = signal<Hotkey>('Mod+S')
+  recorder = injectHotkeyRecorder({
+    onRecord: (hotkey) => this.shortcut.set(hotkey),
+    onCancel: () => console.log('Recording cancelled'),
+  })
+
+  constructor() {
+    injectHotkey(
+      () => this.shortcut(),
+      () => this.handleSave(),
+      () => ({ enabled: !this.recorder.isRecording() }),
+    )
+  }
+}
+```