@ngrithms/hotkeys 0.1.0

package/fesm2022/ngrithms-hotkeys.mjs

@@ -0,0 +1,781 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, makeEnvironmentProviders, inject, PLATFORM_ID, signal, computed, DestroyRef, Injectable, input, Directive, EventEmitter, Output } from '@angular/core';
+import { DOCUMENT, isPlatformBrowser } from '@angular/common';
+import { Subject } from 'rxjs';
+
+/** Resolved hotkey configuration. Always returns a fully-defaulted object. */
+const HOTKEY_CONFIG = new InjectionToken('HOTKEY_CONFIG');
+const DEFAULT_HOTKEY_CONFIG = {
+    cheatsheetHotkey: '?',
+    allowInInputs: false,
+    sequenceTimeoutMs: 1000,
+    preventDefault: true,
+    allowDuplicateBindings: false,
+    allowReservedShortcuts: false,
+};
+
+/**
+ * Register `@ngrithms/hotkeys` for the application.
+ *
+ * ```ts
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [provideHotkeys({ sequenceTimeoutMs: 1000 })],
+ * };
+ * ```
+ */
+function provideHotkeys(config = {}) {
+    return makeEnvironmentProviders([
+        {
+            provide: HOTKEY_CONFIG,
+            useValue: { ...DEFAULT_HOTKEY_CONFIG, ...config },
+        },
+    ]);
+}
+
+/**
+ * Internal helpers for parsing combo strings and matching `KeyboardEvent`s.
+ *
+ * Combo grammar:
+ *   <step> ::= <modifier>+ ... + <key>
+ *   <key>  ::= a printable character or special name (escape, enter, arrowup, ...)
+ *   modifiers: mod | meta | ctrl | alt | shift
+ *   sequences: <step> ' ' <step> ' ' ...
+ *
+ *   'mod+s'         → single step, mod (= meta on Mac, ctrl elsewhere) + s
+ *   'shift+/'       → single step, shift + /
+ *   'g i'           → two-step sequence: press g then i within sequenceTimeoutMs
+ *   'mod+shift+k'   → mod + shift + k
+ *
+ * Key matching uses `KeyboardEvent.key` after lowercasing. This is the simplest
+ * approach and matches what users type on a US layout. Non-US layouts may need
+ * to bind by physical position — that's a future enhancement; for now use
+ * letter-based bindings (`mod+k`) which work consistently across layouts since
+ * `key` reports the produced letter.
+ */
+const SPECIAL_KEY_ALIASES = {
+    esc: 'escape',
+    return: 'enter',
+    del: 'delete',
+    ins: 'insert',
+    space: ' ',
+    spacebar: ' ',
+    up: 'arrowup',
+    down: 'arrowdown',
+    left: 'arrowleft',
+    right: 'arrowright',
+    plus: '+',
+};
+let _isMac = null;
+function isMacPlatform() {
+    if (_isMac !== null)
+        return _isMac;
+    if (typeof navigator === 'undefined')
+        return (_isMac = false);
+    // `navigator.platform` is deprecated but still the most reliable signal
+    // for cmd-vs-ctrl resolution; userAgentData.platform is the modern alt.
+    const platform = navigator.userAgentData?.platform ??
+        navigator.platform ??
+        '';
+    return (_isMac = /mac|iphone|ipad|ipod/i.test(platform));
+}
+/** Reset platform cache. Test-only. */
+function _resetPlatformCacheForTests() {
+    _isMac = null;
+}
+/** Parse a combo string into one or more sequence steps. */
+function parseHotkey(spec) {
+    const steps = spec
+        .trim()
+        .split(/\s+/)
+        .filter((s) => s.length > 0);
+    if (steps.length === 0) {
+        throw new Error(`[@ngrithms/hotkeys] empty combo string`);
+    }
+    return steps.map(parseStep);
+}
+/**
+ * Parse a single combo string or an array of combo strings into an array of
+ * step sequences (one entry per combo). The matcher tries each in order — a
+ * binding fires if any of its combos match.
+ */
+function parseHotkeyMulti(keys) {
+    const list = typeof keys === 'string' ? [keys] : [...keys];
+    if (list.length === 0) {
+        throw new Error(`[@ngrithms/hotkeys] keys array cannot be empty`);
+    }
+    return list.map(parseHotkey);
+}
+function parseStep(step) {
+    const lower = step.toLowerCase();
+    const result = {
+        key: '',
+        mod: false,
+        meta: false,
+        ctrl: false,
+        alt: false,
+        shift: false,
+    };
+    // Split into modifier-part and key-part. The key is always the segment after
+    // the LAST '+', except when the spec ends in '++' (literal '+' key) or is just '+'.
+    let keyPart;
+    let modifierPart;
+    if (lower === '+') {
+        keyPart = '+';
+        modifierPart = '';
+    }
+    else if (lower.endsWith('++')) {
+        keyPart = '+';
+        modifierPart = lower.slice(0, -2);
+    }
+    else {
+        const idx = lower.lastIndexOf('+');
+        if (idx === -1) {
+            keyPart = lower;
+            modifierPart = '';
+        }
+        else {
+            keyPart = lower.slice(idx + 1);
+            modifierPart = lower.slice(0, idx);
+        }
+    }
+    if (keyPart === '') {
+        throw new Error(`[@ngrithms/hotkeys] no key specified in "${step}"`);
+    }
+    if (modifierPart !== '') {
+        for (const p of modifierPart.split('+')) {
+            if (p === '')
+                continue;
+            switch (p) {
+                case 'mod':
+                    result.mod = true;
+                    break;
+                case 'meta':
+                case 'cmd':
+                case 'command':
+                case 'super':
+                case 'win':
+                    result.meta = true;
+                    break;
+                case 'ctrl':
+                case 'control':
+                    result.ctrl = true;
+                    break;
+                case 'alt':
+                case 'option':
+                case 'opt':
+                    result.alt = true;
+                    break;
+                case 'shift':
+                    result.shift = true;
+                    break;
+                default:
+                    throw new Error(`[@ngrithms/hotkeys] unknown modifier "${p}" in "${step}"`);
+            }
+        }
+    }
+    result.key = SPECIAL_KEY_ALIASES[keyPart] ?? keyPart;
+    return result;
+}
+/** Compare a parsed step against an actual KeyboardEvent. */
+function stepMatchesEvent(step, e, mac) {
+    const eventKey = e.key.toLowerCase();
+    if (eventKey !== step.key)
+        return false;
+    // `mod` resolves to meta on Mac, ctrl elsewhere.
+    const wantMeta = step.meta || (step.mod && mac);
+    const wantCtrl = step.ctrl || (step.mod && !mac);
+    if (wantMeta !== e.metaKey)
+        return false;
+    if (wantCtrl !== e.ctrlKey)
+        return false;
+    if (step.alt !== e.altKey)
+        return false;
+    if (step.shift !== e.shiftKey)
+        return false;
+    return true;
+}
+/** Render a combo step into a display string (used by the cheatsheet). */
+function comboToDisplay(combo, mac = isMacPlatform()) {
+    const steps = parseHotkey(combo);
+    return steps
+        .map((s) => {
+        const parts = [];
+        if (s.mod || s.meta)
+            parts.push(mac ? '⌘' : 'Ctrl');
+        if (s.ctrl && !s.mod)
+            parts.push('Ctrl');
+        if (s.alt)
+            parts.push(mac ? '⌥' : 'Alt');
+        if (s.shift)
+            parts.push(mac ? '⇧' : 'Shift');
+        parts.push(prettifyKey(s.key));
+        return parts.join(mac ? '' : '+');
+    })
+        .join(' then ');
+}
+function prettifyKey(key) {
+    switch (key) {
+        case ' ':
+            return 'Space';
+        case 'arrowup':
+            return '↑';
+        case 'arrowdown':
+            return '↓';
+        case 'arrowleft':
+            return '←';
+        case 'arrowright':
+            return '→';
+        case 'escape':
+            return 'Esc';
+        case 'enter':
+            return '⏎';
+        case 'backspace':
+            return '⌫';
+        case 'delete':
+            return 'Del';
+        case 'tab':
+            return 'Tab';
+        default:
+            return key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1);
+    }
+}
+/**
+ * Combos reserved by browsers / operating systems that never reach the page,
+ * regardless of `preventDefault()`. Used by the dev-mode warning so users learn
+ * about the limitation at registration time rather than discovering it in
+ * production. Source: empirical testing across Chrome / Safari / Firefox on
+ * macOS, Windows, and Linux as of 2026.
+ *
+ * Returns `null` when the combo is fine, or a short human description when it
+ * is reserved (used in the warning text).
+ */
+function reservedComboReason(combo) {
+    // Multi-step bindings have at most one reserved step at the end; check each.
+    // (Most reserved combos are single-key with a modifier.)
+    const k = combo.key;
+    const hasMod = combo.mod || combo.meta || combo.ctrl;
+    if (hasMod && !combo.shift && !combo.alt) {
+        // Single mod (Cmd or Ctrl) + key — the largest reserved set.
+        switch (k) {
+            case 'n':
+                return 'new window';
+            case 't':
+                return 'new tab';
+            case 'w':
+                return 'close tab';
+            case 'q':
+                return 'quit application';
+            case 'r':
+                return 'reload page';
+            case 'l':
+                return 'focus address bar';
+            case 'tab':
+                return 'switch tabs';
+        }
+    }
+    if (hasMod && combo.shift && !combo.alt) {
+        switch (k) {
+            case 'n':
+                return 'open incognito / private window';
+            case 't':
+                return 'reopen closed tab';
+            case 'w':
+                return 'close all tabs';
+            case 'tab':
+                return 'switch tabs (reverse)';
+        }
+    }
+    if (k === 'f11')
+        return 'toggle fullscreen';
+    if (k === 'f5')
+        return 'reload page';
+    // Cmd+M minimizes on macOS — only flag if explicit meta (not mod, since mod+m
+    // on Linux/Windows is fine).
+    if (combo.meta && !combo.ctrl && !combo.shift && !combo.alt && k === 'm') {
+        return 'minimize window (macOS)';
+    }
+    return null;
+}
+/** True if focus is in an editable element. */
+function isEditableTarget(target) {
+    if (!(target instanceof Element))
+        return false;
+    const tag = target.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT')
+        return true;
+    const el = target;
+    // `isContentEditable` is the canonical browser check, but jsdom does not
+    // populate it for detached / freshly-attached elements. Fall back to the
+    // attribute so tests and SSR-attached nodes behave the same as real browsers.
+    if (el.isContentEditable)
+        return true;
+    const attr = el.getAttribute('contenteditable');
+    return attr !== null && attr !== 'false';
+}
+
+/**
+ * Registry and dispatcher for keyboard shortcuts.
+ *
+ * Bindings are registered either programmatically via `register()` or
+ * declaratively via the `(ngrHotkey)` directive (recommended — the directive
+ * auto-unregisters on destroy).
+ *
+ * A single binding can listen for multiple combos by passing `keys` as an
+ * array (e.g. `['mod+s', 'mod+shift+s']`). The handler fires once when any of
+ * them matches; the `HotkeyTriggerEvent.combo` reports which one actually fired.
+ *
+ * Matching is global at the `document` level. When multiple bindings share a
+ * combo, scope precedence wins: bindings in the active (top-of-stack) scope
+ * fire first; if none match there, `'global'` bindings fire.
+ *
+ * Sequences (e.g. `'g i'`) require pressing each step within
+ * `config.sequenceTimeoutMs`. The buffer resets on any non-modifier key that
+ * doesn't extend a known sequence prefix.
+ *
+ * SSR-safe: on the server platform, `register()` is a no-op and signals stay
+ * empty. All DOM listeners are guarded by `isPlatformBrowser`.
+ */
+class HotkeysService {
+    config = inject(HOTKEY_CONFIG);
+    document = inject(DOCUMENT);
+    isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
+    mac = this.isBrowser ? isMacPlatform() : false;
+    _bindings = signal([], ...(ngDevMode ? [{ debugName: "_bindings" }] : /* istanbul ignore next */ []));
+    _scopeStack = signal(['global'], ...(ngDevMode ? [{ debugName: "_scopeStack" }] : /* istanbul ignore next */ []));
+    _lastTriggered = signal(null, ...(ngDevMode ? [{ debugName: "_lastTriggered" }] : /* istanbul ignore next */ []));
+    trigger$ = new Subject();
+    /** All currently-registered bindings (read-only view for cheatsheets). */
+    registered = computed(() => this._bindings().map((b) => publicShape(b)), ...(ngDevMode ? [{ debugName: "registered" }] : /* istanbul ignore next */ []));
+    /** Top-of-stack scope. Bindings in this scope (or `'global'`) are active. */
+    activeScope = computed(() => this._scopeStack().at(-1) ?? 'global', ...(ngDevMode ? [{ debugName: "activeScope" }] : /* istanbul ignore next */ []));
+    lastTriggered = this._lastTriggered.asReadonly();
+    onTrigger = this.trigger$.asObservable();
+    nextId = 1;
+    sequenceBuffer = [];
+    sequenceTimerId = null;
+    keydownListener = null;
+    listenerAttached = false;
+    constructor() {
+        if (!this.isBrowser)
+            return;
+        inject(DestroyRef).onDestroy(() => this.detachListener());
+    }
+    /**
+     * Register a binding. Returns an unsubscribe function that removes it.
+     * Idiomatic use is via the `(ngrHotkey)` directive, which calls this for you
+     * and wires the unsubscribe into the host's `DestroyRef`.
+     */
+    register(binding) {
+        if (!this.isBrowser)
+            return () => undefined;
+        const comboStrings = typeof binding.keys === 'string' ? [binding.keys] : [...binding.keys];
+        const combos = parseHotkeyMulti(binding.keys);
+        const scope = binding.scope ?? 'global';
+        const stored = {
+            id: this.nextId++,
+            keys: binding.keys,
+            comboStrings,
+            combos,
+            scope,
+            category: binding.category,
+            description: binding.description,
+            allowInInputs: binding.allowInInputs,
+            preventDefault: binding.preventDefault,
+            handler: binding.handler,
+        };
+        if (typeof ngDevMode === 'undefined' || ngDevMode) {
+            this.maybeWarnConflict(stored);
+            this.maybeWarnReserved(stored);
+        }
+        this._bindings.update((list) => [...list, stored]);
+        this.ensureListener();
+        return () => {
+            this._bindings.update((list) => list.filter((b) => b.id !== stored.id));
+        };
+    }
+    /**
+     * Push a scope onto the activation stack. Returns a function that pops it.
+     * Prefer the `[ngrHotkeyScope]` directive for component-bound scopes — it
+     * auto-pops on destroy.
+     */
+    pushScope(name) {
+        if (!this.isBrowser)
+            return () => undefined;
+        this._scopeStack.update((s) => [...s, name]);
+        return () => {
+            this._scopeStack.update((s) => {
+                // Remove the last occurrence of `name` so nested pushes of the same
+                // scope don't accidentally pop a sibling.
+                const idx = s.lastIndexOf(name);
+                if (idx === -1)
+                    return s;
+                return [...s.slice(0, idx), ...s.slice(idx + 1)];
+            });
+        };
+    }
+    ensureListener() {
+        if (this.listenerAttached || !this.isBrowser)
+            return;
+        this.keydownListener = (e) => this.handleKeyDown(e);
+        this.document.addEventListener('keydown', this.keydownListener);
+        this.listenerAttached = true;
+    }
+    detachListener() {
+        if (!this.listenerAttached || this.keydownListener === null)
+            return;
+        this.document.removeEventListener('keydown', this.keydownListener);
+        this.keydownListener = null;
+        this.listenerAttached = false;
+        this.clearSequenceTimer();
+    }
+    handleKeyDown(e) {
+        // Ignore pure modifier presses (Shift/Ctrl/Alt/Meta by themselves) — they're
+        // never the "key" of a combo and would otherwise spam the sequence buffer.
+        const key = e.key.toLowerCase();
+        if (key === 'shift' || key === 'control' || key === 'alt' || key === 'meta') {
+            return;
+        }
+        const editable = isEditableTarget(e.target);
+        const activeScope = this.activeScope();
+        const candidates = this._bindings();
+        // Extend the sequence buffer with this keystroke and try to match.
+        const newBuffer = [...this.sequenceBuffer, eventToComboStep(e)];
+        // First pass: exact match against the new buffer (full sequence completed).
+        const fullMatch = this.findBindingMatch(candidates, newBuffer, activeScope, editable);
+        if (fullMatch !== null) {
+            this.fire(fullMatch, e);
+            this.resetSequence();
+            return;
+        }
+        // Second pass: is any longer binding still in progress (newBuffer is a prefix)?
+        if (this.hasPrefixMatch(candidates, newBuffer, activeScope, editable)) {
+            this.sequenceBuffer = newBuffer;
+            this.scheduleSequenceTimeout();
+            return;
+        }
+        // Otherwise: maybe the *new* keystroke alone starts a fresh sequence.
+        this.resetSequence();
+        const freshBuffer = [eventToComboStep(e)];
+        const freshMatch = this.findBindingMatch(candidates, freshBuffer, activeScope, editable);
+        if (freshMatch !== null) {
+            this.fire(freshMatch, e);
+            return;
+        }
+        if (this.hasPrefixMatch(candidates, freshBuffer, activeScope, editable)) {
+            this.sequenceBuffer = freshBuffer;
+            this.scheduleSequenceTimeout();
+        }
+    }
+    findBindingMatch(bindings, buffer, activeScope, editable) {
+        // Prefer the active scope over global when both match the same combo.
+        const findIn = (scope) => {
+            for (const b of bindings) {
+                if (b.scope !== scope)
+                    continue;
+                if (!this.respectsInputFilter(b, editable))
+                    continue;
+                const idx = exactComboIndex(b, buffer);
+                if (idx !== -1)
+                    return { binding: b, comboIndex: idx };
+            }
+            return null;
+        };
+        const inActiveScope = findIn(activeScope);
+        if (inActiveScope !== null)
+            return inActiveScope;
+        if (activeScope !== 'global') {
+            const inGlobal = findIn('global');
+            if (inGlobal !== null)
+                return inGlobal;
+        }
+        return null;
+    }
+    hasPrefixMatch(bindings, buffer, activeScope, editable) {
+        return bindings.some((b) => (b.scope === 'global' || b.scope === activeScope) &&
+            this.respectsInputFilter(b, editable) &&
+            b.combos.some((c) => c.length > buffer.length && bufferIsPrefixOf(buffer, c)));
+    }
+    respectsInputFilter(b, editable) {
+        if (!editable)
+            return true;
+        const allow = b.allowInInputs ?? this.config.allowInInputs;
+        return allow;
+    }
+    fire(match, e) {
+        const { binding, comboIndex } = match;
+        const preventDefault = binding.preventDefault ?? this.config.preventDefault;
+        if (preventDefault)
+            e.preventDefault();
+        const event = {
+            combo: binding.comboStrings[comboIndex],
+            scope: binding.scope,
+            ts: Date.now(),
+        };
+        this._lastTriggered.set(event);
+        this.trigger$.next(event);
+        try {
+            binding.handler(e);
+        }
+        catch (err) {
+            // Don't let a handler error tear down the listener for everything else.
+            console.error('[@ngrithms/hotkeys] handler threw', err);
+        }
+    }
+    scheduleSequenceTimeout() {
+        this.clearSequenceTimer();
+        this.sequenceTimerId = setTimeout(() => {
+            this.resetSequence();
+        }, this.config.sequenceTimeoutMs);
+    }
+    clearSequenceTimer() {
+        if (this.sequenceTimerId !== null) {
+            clearTimeout(this.sequenceTimerId);
+            this.sequenceTimerId = null;
+        }
+    }
+    resetSequence() {
+        this.sequenceBuffer = [];
+        this.clearSequenceTimer();
+    }
+    maybeWarnConflict(stored) {
+        if (this.config.allowDuplicateBindings)
+            return;
+        for (const existing of this._bindings()) {
+            if (existing.scope !== stored.scope)
+                continue;
+            for (let i = 0; i < stored.combos.length; i++) {
+                const newCombo = stored.combos[i];
+                for (let j = 0; j < existing.combos.length; j++) {
+                    if (combosAreEqual(newCombo, existing.combos[j])) {
+                        const combo = stored.comboStrings[i];
+                        const existingLabel = existing.description ?? `(no description, id ${existing.id})`;
+                        const newLabel = stored.description ?? `(no description, id ${stored.id})`;
+                        console.warn(`[@ngrithms/hotkeys] Two bindings registered for "${combo}" in scope "${stored.scope}". ` +
+                            `The later registration will be shadowed.\n` +
+                            `  • ${existingLabel}\n` +
+                            `  • ${newLabel} ← new\n` +
+                            `Set provideHotkeys({ allowDuplicateBindings: true }) to silence.`);
+                    }
+                }
+            }
+        }
+    }
+    maybeWarnReserved(stored) {
+        if (this.config.allowReservedShortcuts)
+            return;
+        for (let i = 0; i < stored.combos.length; i++) {
+            const combo = stored.combos[i];
+            // Single-step combos with a modifier are the only realistic OS-reserved ones.
+            // Skip sequence shortcuts.
+            if (combo.length !== 1)
+                continue;
+            const reason = reservedComboReason(combo[0]);
+            if (reason !== null) {
+                console.warn(`[@ngrithms/hotkeys] "${stored.comboStrings[i]}" is reserved by the browser / OS (${reason}) ` +
+                    `and cannot be intercepted from JavaScript. The binding will not fire. ` +
+                    `See https://github.com/aboudbadra/ngrithms-hotkeys#reserved-shortcuts`);
+            }
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: HotkeysService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: HotkeysService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: HotkeysService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }], ctorParameters: () => [] });
+function publicShape(b) {
+    return {
+        keys: b.keys,
+        handler: b.handler,
+        scope: b.scope,
+        category: b.category,
+        description: b.description,
+        allowInInputs: b.allowInInputs,
+        preventDefault: b.preventDefault,
+    };
+}
+function eventToComboStep(e) {
+    return {
+        key: e.key.toLowerCase(),
+        mod: false,
+        meta: e.metaKey,
+        ctrl: e.ctrlKey,
+        alt: e.altKey,
+        shift: e.shiftKey,
+    };
+}
+function stepEquals(spec, actual) {
+    // `actual` always has `mod=false` (events carry explicit meta/ctrl). For a
+    // spec written with `mod`, accept either modifier based on platform.
+    if (spec.key !== actual.key)
+        return false;
+    const mac = isMacPlatform();
+    const wantMeta = spec.meta || (spec.mod && mac);
+    const wantCtrl = spec.ctrl || (spec.mod && !mac);
+    if (wantMeta !== actual.meta)
+        return false;
+    if (wantCtrl !== actual.ctrl)
+        return false;
+    if (spec.alt !== actual.alt)
+        return false;
+    if (spec.shift !== actual.shift)
+        return false;
+    return true;
+}
+function exactComboIndex(b, buffer) {
+    for (let i = 0; i < b.combos.length; i++) {
+        const combo = b.combos[i];
+        if (combo.length !== buffer.length)
+            continue;
+        if (combo.every((s, j) => stepEquals(s, buffer[j])))
+            return i;
+    }
+    return -1;
+}
+function bufferIsPrefixOf(buffer, combo) {
+    if (buffer.length > combo.length)
+        return false;
+    return buffer.every((s, i) => stepEquals(s, combo[i]));
+}
+function combosAreEqual(a, b) {
+    // Compare parsed combos directly (modifier-by-modifier, key, sequence length).
+    // We do NOT collapse `mod` into ctrl/meta here — `mod+s` and `meta+s` may or
+    // may not collide depending on platform, but they're written differently so
+    // we treat them as distinct registrations. The runtime matcher handles the
+    // platform resolution; the warning is about literal source-level collisions.
+    if (a.length !== b.length)
+        return false;
+    return a.every((sa, i) => {
+        const sb = b[i];
+        return (sa.key === sb.key &&
+            sa.mod === sb.mod &&
+            sa.meta === sb.meta &&
+            sa.ctrl === sb.ctrl &&
+            sa.alt === sb.alt &&
+            sa.shift === sb.shift);
+    });
+}
+
+/**
+ * Activates a hotkey scope while this directive's host element is mounted.
+ *
+ * Use this around a modal, dialog, drawer, or any region whose shortcuts should
+ * shadow global bindings while it is open. The scope is auto-popped on destroy
+ * — no manual lifecycle wiring needed.
+ *
+ * Child `(ngrHotkey)` bindings inherit this scope automatically via DI.
+ *
+ * ```html
+ * <dialog *ngIf="open()" ngrHotkeyScope="modal">
+ *   <button (ngrHotkey)="close()" hotkey="escape">Close</button>
+ * </dialog>
+ * ```
+ *
+ * While the dialog is mounted, `escape` fires `close()` instead of any global
+ * `escape` binding. When the dialog unmounts, global bindings take over again.
+ */
+class HotkeyScopeDirective {
+    hotkeys = inject(HotkeysService);
+    /** Scope name to push while this element is mounted. */
+    ngrHotkeyScope = input.required(...(ngDevMode ? [{ debugName: "ngrHotkeyScope" }] : /* istanbul ignore next */ []));
+    release = null;
+    ngOnInit() {
+        this.release = this.hotkeys.pushScope(this.ngrHotkeyScope());
+    }
+    ngOnDestroy() {
+        this.release?.();
+        this.release = null;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: HotkeyScopeDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.13", type: HotkeyScopeDirective, isStandalone: true, selector: "[ngrHotkeyScope]", inputs: { ngrHotkeyScope: { classPropertyName: "ngrHotkeyScope", publicName: "ngrHotkeyScope", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: HotkeyScopeDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[ngrHotkeyScope]',
+                    standalone: true,
+                }]
+        }], propDecorators: { ngrHotkeyScope: [{ type: i0.Input, args: [{ isSignal: true, alias: "ngrHotkeyScope", required: true }] }] } });
+
+/**
+ * Declarative shortcut binding. Registers on init, unregisters on destroy.
+ *
+ * ```html
+ * <button (ngrHotkey)="save()" hotkey="mod+s" hotkeyDescription="Save">Save</button>
+ * <div (ngrHotkey)="gotoInbox()" hotkey="g i" hotkeyDescription="Go to inbox"></div>
+ * <!-- multi-combo: one handler, two combos -->
+ * <button (ngrHotkey)="save()" [hotkey]="['mod+s', 'mod+shift+s']" hotkeyDescription="Save">Save</button>
+ * ```
+ *
+ * The host element does not need to be focused — matching is `document`-level.
+ * Use `[ngrHotkeyScope]` on an ancestor to scope the binding to a UI region.
+ */
+class HotkeyDirective {
+    hotkeys = inject(HotkeysService);
+    // Inherit scope from the nearest ancestor `[ngrHotkeyScope]`, if any. This walks
+    // the element-injector tree, so any ancestor element with the scope directive
+    // wins. Read at ngOnInit time so the parent input is guaranteed set.
+    parentScope = inject(HotkeyScopeDirective, { optional: true });
+    /**
+     * Combo string (`'mod+s'`, `'g i'`, `'escape'`, ...) or an array of strings
+     * mapping multiple combos to the same handler. Required.
+     */
+    hotkey = input.required(...(ngDevMode ? [{ debugName: "hotkey" }] : /* istanbul ignore next */ []));
+    /** Logical scope. Defaults to the surrounding `ngrHotkeyScope`, or `'global'`. */
+    hotkeyScope = input(undefined, ...(ngDevMode ? [{ debugName: "hotkeyScope" }] : /* istanbul ignore next */ []));
+    /**
+     * Optional sub-grouping label for the cheatsheet. Bindings sharing a category
+     * appear under a single subheader within their scope.
+     */
+    hotkeyCategory = input(undefined, ...(ngDevMode ? [{ debugName: "hotkeyCategory" }] : /* istanbul ignore next */ []));
+    /** Description shown in the cheatsheet. Bindings without a description are hidden. */
+    hotkeyDescription = input(undefined, ...(ngDevMode ? [{ debugName: "hotkeyDescription" }] : /* istanbul ignore next */ []));
+    /** Allow firing when focus is inside an input/textarea/contenteditable. */
+    hotkeyAllowInInputs = input(undefined, ...(ngDevMode ? [{ debugName: "hotkeyAllowInInputs" }] : /* istanbul ignore next */ []));
+    /** Override `preventDefault` for this binding. */
+    hotkeyPreventDefault = input(undefined, ...(ngDevMode ? [{ debugName: "hotkeyPreventDefault" }] : /* istanbul ignore next */ []));
+    /** Fired when the combo is matched. The DOM `KeyboardEvent` is the payload. */
+    ngrHotkey = new EventEmitter();
+    dispose = null;
+    ngOnInit() {
+        const scope = this.hotkeyScope() ?? this.parentScope?.ngrHotkeyScope() ?? 'global';
+        this.dispose = this.hotkeys.register({
+            keys: this.hotkey(),
+            scope,
+            category: this.hotkeyCategory(),
+            description: this.hotkeyDescription(),
+            allowInInputs: this.hotkeyAllowInInputs(),
+            preventDefault: this.hotkeyPreventDefault(),
+            handler: (e) => this.ngrHotkey.emit(e),
+        });
+    }
+    ngOnDestroy() {
+        this.dispose?.();
+        this.dispose = null;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: HotkeyDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.13", type: HotkeyDirective, isStandalone: true, selector: "[ngrHotkey]", inputs: { hotkey: { classPropertyName: "hotkey", publicName: "hotkey", isSignal: true, isRequired: true, transformFunction: null }, hotkeyScope: { classPropertyName: "hotkeyScope", publicName: "hotkeyScope", isSignal: true, isRequired: false, transformFunction: null }, hotkeyCategory: { classPropertyName: "hotkeyCategory", publicName: "hotkeyCategory", isSignal: true, isRequired: false, transformFunction: null }, hotkeyDescription: { classPropertyName: "hotkeyDescription", publicName: "hotkeyDescription", isSignal: true, isRequired: false, transformFunction: null }, hotkeyAllowInInputs: { classPropertyName: "hotkeyAllowInInputs", publicName: "hotkeyAllowInInputs", isSignal: true, isRequired: false, transformFunction: null }, hotkeyPreventDefault: { classPropertyName: "hotkeyPreventDefault", publicName: "hotkeyPreventDefault", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { ngrHotkey: "ngrHotkey" }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: HotkeyDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[ngrHotkey]',
+                    standalone: true,
+                }]
+        }], propDecorators: { hotkey: [{ type: i0.Input, args: [{ isSignal: true, alias: "hotkey", required: true }] }], hotkeyScope: [{ type: i0.Input, args: [{ isSignal: true, alias: "hotkeyScope", required: false }] }], hotkeyCategory: [{ type: i0.Input, args: [{ isSignal: true, alias: "hotkeyCategory", required: false }] }], hotkeyDescription: [{ type: i0.Input, args: [{ isSignal: true, alias: "hotkeyDescription", required: false }] }], hotkeyAllowInInputs: [{ type: i0.Input, args: [{ isSignal: true, alias: "hotkeyAllowInInputs", required: false }] }], hotkeyPreventDefault: [{ type: i0.Input, args: [{ isSignal: true, alias: "hotkeyPreventDefault", required: false }] }], ngrHotkey: [{
+                type: Output
+            }] } });
+
+/*
+ * Public API surface of @ngrithms/hotkeys
+ */
+// Setup
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { DEFAULT_HOTKEY_CONFIG, HOTKEY_CONFIG, HotkeyDirective, HotkeyScopeDirective, HotkeysService, comboToDisplay, isMacPlatform, provideHotkeys };
+//# sourceMappingURL=ngrithms-hotkeys.mjs.map