@ngrithms/hotkeys 0.1.0

package/README.md

@@ -0,0 +1,390 @@
+# @ngrithms/hotkeys
+
+[![npm](https://img.shields.io/npm/v/@ngrithms/hotkeys.svg)](https://www.npmjs.com/package/@ngrithms/hotkeys)
+[![CI](https://github.com/aboudbadra/ngrithms-hotkeys/actions/workflows/ci.yml/badge.svg)](https://github.com/aboudbadra/ngrithms-hotkeys/actions/workflows/ci.yml)
+[![Angular compat](https://github.com/aboudbadra/ngrithms-hotkeys/actions/workflows/compat-matrix.yml/badge.svg)](https://github.com/aboudbadra/ngrithms-hotkeys/actions/workflows/compat-matrix.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Modern keyboard-shortcut library for Angular 17+. Standalone, signals-first, SSR-safe, zero runtime dependencies. Register shortcuts with a directive that auto-cleans on destroy, scope them to modals or palettes, and define multi-step sequences like `g i` (Gmail / GitHub / Linear-style).
+
+```html
+<button (ngrHotkey)="save()" hotkey="mod+s" hotkeyDescription="Save">Save</button>
+```
+
+## Install
+
+```bash
+npm install @ngrithms/hotkeys
+```
+
+Peer-compatible with Angular `>=17.2.0 <22.0.0`. No runtime dependencies.
+
+## Quick start
+
+```ts
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideHotkeys } from '@ngrithms/hotkeys';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideHotkeys()],
+};
+```
+
+```ts
+// any component
+import { Component } from '@angular/core';
+import { HotkeyDirective } from '@ngrithms/hotkeys';
+
+@Component({
+  standalone: true,
+  imports: [HotkeyDirective],
+  template: `
+    <button (ngrHotkey)="save()" hotkey="mod+s" hotkeyDescription="Save">Save</button>
+    <button (ngrHotkey)="open()" hotkey="mod+k" hotkeyDescription="Command palette">Open palette</button>
+  `,
+})
+export class Toolbar {
+  save() { /* ... */ }
+  open() { /* ... */ }
+}
+```
+
+That's it. The directive registers on init and unregisters on destroy. No `ngOnDestroy`, no manual cleanup.
+
+## The directive (the recommended way)
+
+`(ngrHotkey)="..."` is an Angular `Output` — it fires when the combo matches.
+
+| Input | Type | What it does |
+|---|---|---|
+| `hotkey` | `string \| string[]` *(required)* | The combo, or an array of combos that all map to this handler. Examples: `'mod+s'`, `'g i'`, `['mod+s', 'mod+shift+s']`. |
+| `hotkeyDescription` | `string` | Human-readable label for the cheatsheet. Without it, the binding is hidden from the cheatsheet. |
+| `hotkeyScope` | `string` | Logical group. Defaults to the nearest `[ngrHotkeyScope]`, or `'global'`. |
+| `hotkeyCategory` | `string` | Optional sub-grouping label for the cheatsheet (e.g. `"Navigation"`, `"Editing"`). Bindings with the same category appear under a shared subheader within their scope. |
+| `hotkeyAllowInInputs` | `boolean` | Let this binding fire when focus is in an input/textarea/contenteditable. |
+| `hotkeyPreventDefault` | `boolean` | Override the global `preventDefault` for this one binding. |
+
+## The combo grammar in plain English
+
+A combo is a chain of optional modifiers and exactly one key, joined with `+`.
+
+```
+mod+s            ⌘+S on Mac, Ctrl+S elsewhere
+mod+shift+k      ⌘+Shift+K / Ctrl+Shift+K
+escape           the Escape key on its own
+/                slash (Shift+/ on most layouts — works because matching is on the produced key)
+```
+
+A **sequence** is two or more combos separated by a space. The user must press each combo within `sequenceTimeoutMs` of the last.
+
+```
+g i              press G, then I within 1 second
+g d              press G, then D within 1 second
+```
+
+### The `mod` keyword
+
+Every modern keyboard-driven app uses one logical "primary modifier" that maps to Cmd on Mac and Ctrl elsewhere — VS Code, Linear, Notion, GitHub, Slack all do this. `mod` is that modifier. Use `meta` or `ctrl` explicitly if you really mean one platform only.
+
+### Multi-combo per binding
+
+Sometimes you want two combos to do the same thing — `mod+s` *and* `mod+shift+s` both save, `mod+/` *and* `?` both open help. Pass an array and skip the duplicate registration:
+
+```html
+<button (ngrHotkey)="save()" [hotkey]="['mod+s', 'mod+shift+s']" hotkeyDescription="Save">Save</button>
+```
+
+The handler fires when **any** of the combos matches. In the cheatsheet, the first combo renders prominently and the rest appear as muted "or" badges next to it. The `HotkeyTriggerEvent.combo` field reports which specific combo actually fired — useful if you want to analytics on it.
+
+### A note on non-US keyboard layouts
+
+Matching uses `KeyboardEvent.key` — the character the keyboard *produces*, not the physical button. That has two practical implications:
+
+- **Letter bindings (`mod+k`, `mod+s`) work everywhere.** Every Latin layout produces the same lowercase letter for the same physical key, so `KeyboardEvent.key` agrees across QWERTY, QWERTZ, AZERTY, Dvorak, Colemak.
+- **Symbol bindings (`mod+/`, `shift+/`) may not fire on non-US layouts.** On AZERTY, for example, `/` is produced by `Shift+:`, so an event with `key === '/'` only happens after the user presses `Shift+:` — not the bare key you might assume. If you must support symbol shortcuts globally, prefer to ship one binding per common layout (`mod+/` and `mod+shift+7`), or wait for the layout-independent matching mode planned for a future release.
+
+There's a related quirk on macOS: `Option+letter` produces a special character (`Option+E` → `´`), so `alt+e` doesn't currently fire on Mac. Use `mod+e` instead, or a letter that doesn't have a dead-key overlay on the layouts you care about.
+
+### Reserved browser / OS shortcuts (can't be intercepted)
+
+Some shortcuts are reserved by the browser or operating system and never reach the page — no JavaScript library, this one included, can override them. The most common ones to avoid:
+
+- `Cmd/Ctrl + N` — new window
+- `Cmd/Ctrl + T` — new tab
+- `Cmd/Ctrl + W` — close tab
+- `Cmd/Ctrl + Q` — quit
+- `Cmd/Ctrl + Shift + N` — incognito window
+- `Cmd/Ctrl + Shift + T` — reopen closed tab
+- `Cmd/Ctrl + L` — focus address bar
+- `Cmd/Ctrl + R` — reload
+- `Cmd + M` (Mac) — minimize
+- `F11` — fullscreen
+
+`Cmd/Ctrl + S`, `Cmd/Ctrl + P`, `Cmd/Ctrl + F` show a browser dialog by default but **can** be intercepted via `preventDefault()` (the library does this for you). If you need a "New item" shortcut, use a single letter like `c` (Gmail/Linear convention) or a non-reserved combo like `mod+shift+a`.
+
+## Configuration — what each option actually does
+
+Every option below is optional. Defaults are listed; the explanation is what you'd want to know before changing them.
+
+```ts
+provideHotkeys({
+  cheatsheetHotkey: '?',
+  allowInInputs: false,
+  sequenceTimeoutMs: 1000,
+  preventDefault: true,
+  allowDuplicateBindings: false,
+  allowReservedShortcuts: false,
+});
+```
+
+### `cheatsheetHotkey` — default `'?'`
+
+The single-key combo that opens the built-in cheatsheet (when `<ngr-hotkey-cheatsheet>` is rendered). Setting `null` disables the toggle entirely — useful when you render your own cheatsheet UI.
+
+> **Real-world example:** Linear uses `?` for "Show keyboard shortcuts," so does GitHub. If your app already binds `?` to something else, set this to another key (e.g. `'F1'`) or `null` and trigger the cheatsheet yourself.
+
+### `allowInInputs` — default `false`
+
+Should single-key shortcuts fire while the user is typing in a form field?
+
+By default: **no**. If a user is typing in a text field, pressing `n` should insert "n" — not trigger your "New item" shortcut. This matches Gmail, GitHub, Linear, Notion, Slack — every keyboard-heavy app.
+
+You can override per-binding via `[hotkeyAllowInInputs]="true"`. Common opt-ins: `Escape` to blur, `Cmd+S` to save while editing, `Cmd+Enter` to submit.
+
+> **Real-world example:** In a comment composer, set `[hotkeyAllowInInputs]="true"` on `mod+enter` so users can submit without taking their hands off the keyboard.
+
+### `sequenceTimeoutMs` — default `1000`
+
+Maximum gap (in milliseconds) between the keys of a sequence before the buffer resets.
+
+```
+g  …(800 ms)…  i   →  fires the 'g i' binding
+g  …(1500 ms)… i   →  buffer reset; nothing fires; 'i' tried as a standalone combo
+```
+
+> **Real-world example:** Gmail uses ~1 second; some users prefer more time. Bump to `1500` for a slower audience, drop to `750` to feel snappier.
+
+### `preventDefault` — default `true`
+
+When a binding matches, should we call `event.preventDefault()` so the browser doesn't also do its built-in thing (e.g. open Save dialog on `Cmd+S`)?
+
+Most of the time, yes — you defined the shortcut, you want your handler to win. Override per-binding if you want the browser default *too* (rare).
+
+### `allowDuplicateBindings` — default `false`
+
+In development builds, registering two bindings with the same combo in the same scope emits a `console.warn`. This catches the bug where two components both bind `mod+k` and one silently shadows the other — a problem that's nearly impossible to debug without the warning.
+
+The warning only fires for **same-scope** collisions. Cross-scope shadowing (e.g. a modal binding `escape` while a global `escape` exists) is intentional and never warns. Production builds never emit the warning regardless of this setting.
+
+Set `true` if you deliberately layer multiple handlers on the same combo and don't want the noise.
+
+### `allowReservedShortcuts` — default `false`
+
+In development builds, registering a combo the browser/OS reserves (`mod+n`, `mod+t`, `mod+w`, `mod+shift+n`, etc.) emits a `console.warn` with the reason it won't fire. Catches the exact "why isn't this triggering?" frustration these combos cause — you find out at registration time instead of in production. Production builds never emit the warning regardless.
+
+Set `true` to silence — useful when you know your app is wrapped in something (Electron, an iframe with `sandbox` permissions, a kiosk shell) that lets you intercept these.
+
+## Use case 1 — global app shortcuts
+
+The "save," "new," "search" shortcuts every productivity app has.
+
+```html
+<button (ngrHotkey)="save()" hotkey="mod+s" hotkeyDescription="Save">Save</button>
+<button (ngrHotkey)="newItem()" hotkey="c" hotkeyDescription="Create new">New</button>
+<button (ngrHotkey)="search()" hotkey="/" hotkeyDescription="Focus search">/</button>
+```
+
+The directive places these on actual buttons, but they fire even when those buttons aren't focused — matching happens at the `document` level. Putting the binding on the button keeps the shortcut documented next to the action it triggers.
+
+## Use case 2 — navigation sequences
+
+Press `G`, then a letter, to jump somewhere. Used by Gmail, GitHub, Linear.
+
+```html
+<a (ngrHotkey)="go('/inbox')"  hotkey="g i" hotkeyDescription="Go to inbox"></a>
+<a (ngrHotkey)="go('/drafts')" hotkey="g d" hotkeyDescription="Go to drafts"></a>
+<a (ngrHotkey)="go('/sent')"   hotkey="g s" hotkeyDescription="Go to sent"></a>
+```
+
+Why two keys instead of one? You run out of single letters fast. `g` + 26 letters gives you a clean, conflict-free navigation namespace.
+
+## Use case 3 — modal / dialog shortcuts (scopes)
+
+When a modal is open, `Esc` should close *the modal*, not trigger your global Esc handler.
+
+```html
+<button (click)="open.set(true)">Edit</button>
+
+@if (open()) {
+  <div ngrHotkeyScope="modal" class="modal">
+    <button (ngrHotkey)="open.set(false)" hotkey="escape" hotkeyDescription="Close">
+      Close
+    </button>
+  </div>
+}
+```
+
+`[ngrHotkeyScope]` pushes the `'modal'` scope when it mounts and pops it when it unmounts. Bindings *inside* the scope take precedence over `'global'` bindings with the same combo while the modal is open. No manual lifecycle wiring.
+
+> **Why this matters:** without scopes, every Esc handler has to manually check "is a modal open right now?" Scopes solve it once at the library level.
+
+## Use case 4 — let some shortcuts fire while typing
+
+A composer where `Cmd+Enter` submits even while the textarea has focus.
+
+```html
+<textarea
+  (ngrHotkey)="submit()"
+  hotkey="mod+enter"
+  hotkeyDescription="Send"
+  [hotkeyAllowInInputs]="true"
+></textarea>
+```
+
+The textarea still receives all normal typing. Only `Cmd+Enter` is intercepted.
+
+## Use case 5 — command palette (`Cmd+K`)
+
+```html
+<button (ngrHotkey)="palette.open()" hotkey="mod+k" hotkeyDescription="Command palette">
+  ⌘K
+</button>
+
+@if (palette.isOpen()) {
+  <div ngrHotkeyScope="palette" class="palette">
+    <input ... />
+    <button (ngrHotkey)="palette.close()" hotkey="escape" [hotkeyAllowInInputs]="true">Close</button>
+  </div>
+}
+```
+
+Pattern is identical to the modal scope above — that's the point. One mechanism, many UIs.
+
+## The cheatsheet
+
+Drop it anywhere — usually next to `<router-outlet>` in your shell:
+
+```ts
+import { HotkeyCheatsheetComponent } from '@ngrithms/hotkeys/cheatsheet';
+
+@Component({
+  standalone: true,
+  imports: [HotkeyCheatsheetComponent],
+  template: `
+    <router-outlet />
+    <ngr-hotkey-cheatsheet />
+  `,
+})
+export class App {}
+```
+
+Press `?` (configurable) to toggle. Only bindings with a `hotkeyDescription` show up; bindings are grouped by `scope`.
+
+### Searchable
+
+For apps with many shortcuts, opt into a filter input above the list:
+
+```html
+<ngr-hotkey-cheatsheet [searchable]="true" />
+```
+
+The filter matches against the description, the combo string, and the rendered display (so `'⌘S'` matches `mod+s`). Off by default — overkill for apps with five shortcuts.
+
+### Categories
+
+Group bindings within a scope under sub-headers by setting `hotkeyCategory` on the directive (or `category` on a service registration):
+
+```html
+<button (ngrHotkey)="save()"     hotkey="mod+s"  hotkeyCategory="Editing"    hotkeyDescription="Save">Save</button>
+<button (ngrHotkey)="undo()"     hotkey="mod+z"  hotkeyCategory="Editing"    hotkeyDescription="Undo">Undo</button>
+<button (ngrHotkey)="palette()"  hotkey="mod+k"  hotkeyCategory="Navigation" hotkeyDescription="Command palette">⌘K</button>
+```
+
+The cheatsheet shows a single "global" scope header, then sub-headers for "Editing" and "Navigation" with the bindings under each. Uncategorized bindings render first.
+
+### Theming
+
+Override CSS custom properties on the component:
+
+```css
+ngr-hotkey-cheatsheet {
+  --ngr-hotkey-bg: #0b1220;
+  --ngr-hotkey-fg: #e2e8f0;
+  --ngr-hotkey-kbd-bg: #1e293b;
+  --ngr-hotkey-kbd-fg: #f8fafc;
+}
+```
+
+The cheatsheet ships as a **secondary entry point** so the core stays small. If you don't import it, none of its code lands in your bundle.
+
+## Programmatic API — `HotkeysService`
+
+For shortcuts that aren't tied to a single component (e.g. an app-wide help dialog or a feature behind a service):
+
+```ts
+const hotkeys = inject(HotkeysService);
+
+const dispose = hotkeys.register({
+  keys: 'mod+/',
+  description: 'Open help',
+  handler: () => this.help.toggle(),
+});
+
+// dispose() to remove later. The directive does this automatically; service-level
+// registrations are yours to clean up.
+```
+
+Signals you can read:
+
+| Member | Type | Description |
+|---|---|---|
+| `registered` | `Signal<readonly HotkeyBinding[]>` | All current bindings — read this from your own cheatsheet UI. |
+| `activeScope` | `Signal<string>` | Top of the scope stack. |
+| `lastTriggered` | `Signal<HotkeyTriggerEvent \| null>` | The most recent fire — useful for analytics or debug UIs. |
+| `onTrigger` | `Observable<HotkeyTriggerEvent>` | Stream of every fire. |
+
+Scope control:
+
+```ts
+const release = hotkeys.pushScope('modal');
+// ... later ...
+release();
+```
+
+You almost never need this — `[ngrHotkeyScope]` handles it via the component's own lifecycle. Use it only when your scope boundary doesn't match an element (e.g. a router-level "in editor route" scope).
+
+## SSR
+
+All DOM listeners are guarded by `isPlatformBrowser`. On the server platform:
+
+- `register()` returns a no-op disposer.
+- `registered()` is `[]`.
+- The cheatsheet renders nothing.
+
+You can import and use the library anywhere in your code, including SSR-rendered pages — it won't break your build.
+
+## Comparison to `angular2-hotkeys`
+
+|  | `angular2-hotkeys` | `@ngrithms/hotkeys` |
+|---|---|---|
+| Maintenance | Last release 2 years ago | Active |
+| Setup | `HotkeyModule.forRoot()` | `provideHotkeys({...})` functional config |
+| Registration | Manual `service.add(new Hotkey(...))` + `remove()` in `ngOnDestroy` | `(ngrHotkey)` directive auto-cleans on destroy |
+| State surface | None | Signals (`registered`, `activeScope`, `lastTriggered`) |
+| Cross-platform `mod` | Manual `meta` vs `ctrl` branching | Auto-resolved via `mod` keyword |
+| Scopes | None | Stack-based via `[ngrHotkeyScope]` |
+| Sequences (`g i`) | No | Yes |
+| Multi-combo per binding | Yes (one of the few areas it had) | Yes (parity) |
+| Dev-mode conflict warning | No | Yes — catches silent shadowing |
+| Reserved-combo warning | No | Yes — flags `mod+n`, `mod+t`, etc. at registration |
+| Input filtering | One global boolean | Per-binding, distinguishes `contenteditable` |
+| Cheatsheet | Built-in, hard to theme | Optional secondary entry, themable, searchable, category groups |
+| Standalone / signals | ✗ | ✓ |
+| SSR-safe | ✗ | ✓ |
+| Runtime deps | `hotkeys.js` | None |
+| Bundle (gz) | ~10 KB (lib) + `hotkeys.js` | ~9 KB core, ~13 KB with cheatsheet |
+
+## License
+
+MIT © Aboud Badra

package/cheatsheet/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../fesm2022/ngrithms-hotkeys-cheatsheet.mjs",
+  "typings": "../types/ngrithms-hotkeys-cheatsheet.d.ts"
+}