ngx-keys 1.2.0 → 1.3.0

package/index.d.ts

@@ -1,9 +1,27 @@
-import * as _angular_core from '@angular/core';
-import { DestroyRef, OnDestroy } from '@angular/core';
+import * as i0 from '@angular/core';
+import { DestroyRef, OnDestroy, InjectionToken, Provider, OnInit } from '@angular/core';
 import { Observable } from 'rxjs';
 
 type KeyboardShortcutActiveUntil = Observable<unknown> | DestroyRef | 'destruct';
 type KeyStep = string[];
+/**
+ * Function signature for keyboard shortcut actions.
+ *
+ * @example
+ * ```typescript
+ * const saveAction: Action = () => {
+ *   console.log('Saving...');
+ * };
+ *
+ * this.keyboardService.register({
+ *   id: 'save',
+ *   keys: ['ctrl', 's'],
+ *   action: saveAction,
+ *   description: 'Save document'
+ * });
+ * ```
+ */
+type Action = () => void;
 interface KeyboardShortcut {
     id: string;
     /**
@@ -22,7 +40,7 @@ interface KeyboardShortcut {
     macKeys?: string[];
     steps?: KeyStep[];
     macSteps?: KeyStep[];
-    action: () => void;
+    action: Action;
     description: string;
     activeUntil?: KeyboardShortcutActiveUntil;
     /**
@@ -46,6 +64,38 @@ interface KeyboardShortcut {
      * ```
      */
     filter?: KeyboardShortcutFilter;
+    /**
+     * Optional timeout (in milliseconds) for multi-step sequences.
+     * After this duration of inactivity between steps, the sequence state will reset.
+     *
+     * @default undefined (no timeout - sequence remains active indefinitely)
+     *
+     * @remarks
+     * For accessibility, the default behavior (no timeout) is recommended.
+     * Multi-step sequences remain active until completed or the window/document loses focus.
+     * Only specify a timeout for specialized use cases like preventing stuck UI states.
+     *
+     * @example
+     * ```typescript
+     * // No timeout (default) - waits indefinitely between steps
+     * {
+     *   id: 'save-file',
+     *   steps: [['ctrl', 'k'], ['s']],
+     *   action: () => this.save(),
+     *   description: 'Save file'
+     * }
+     *
+     * // 5 second timeout - resets if user pauses too long between steps
+     * {
+     *   id: 'quick-action',
+     *   steps: [['ctrl', 'k'], ['q']],
+     *   action: () => this.quickAction(),
+     *   description: 'Quick action',
+     *   sequenceTimeout: 5000
+     * }
+     * ```
+     */
+    sequenceTimeout?: number;
 }
 interface KeyboardShortcutGroup {
     id: string;
@@ -114,9 +164,9 @@ interface KeyboardShortcutUI {
 }
 
 declare class KeyboardShortcuts implements OnDestroy {
-    private static readonly MODIFIER_KEYS;
     private readonly document;
     private readonly window;
+    private readonly config;
     private readonly shortcuts;
     private readonly groups;
     private readonly activeShortcuts;
@@ -129,7 +179,7 @@ declare class KeyboardShortcuts implements OnDestroy {
      */
     private readonly globalFilters;
     private readonly state;
-    readonly shortcuts$: _angular_core.Signal<{
+    readonly shortcuts$: i0.Signal<{
         active: KeyboardShortcut[];
         inactive: KeyboardShortcut[];
         all: KeyboardShortcut[];
@@ -138,7 +188,7 @@ declare class KeyboardShortcuts implements OnDestroy {
             inactive: string[];
         };
     }>;
-    readonly shortcutsUI$: _angular_core.Signal<{
+    readonly shortcutsUI$: i0.Signal<{
         active: KeyboardShortcutUI[];
         inactive: KeyboardShortcutUI[];
         all: KeyboardShortcutUI[];
@@ -148,8 +198,6 @@ declare class KeyboardShortcuts implements OnDestroy {
     private readonly blurListener;
     private readonly visibilityListener;
     private isListening;
-    /** Default timeout (ms) for completing a multi-step sequence */
-    protected sequenceTimeout: number;
     /** Runtime state for multi-step sequences */
     private pendingSequence;
     constructor();
@@ -307,6 +355,67 @@ declare class KeyboardShortcuts implements OnDestroy {
      * @returns `true` if filter exists, `false` otherwise
      */
     hasFilter(name: string): boolean;
+    /**
+     * Remove the filter from a specific group
+     * @param groupId - The group ID
+     * @throws KeyboardShortcutError if group doesn't exist
+     */
+    removeGroupFilter(groupId: string): void;
+    /**
+     * Remove the filter from a specific shortcut
+     * @param shortcutId - The shortcut ID
+     * @throws KeyboardShortcutError if shortcut doesn't exist
+     */
+    removeShortcutFilter(shortcutId: string): void;
+    /**
+     * Remove all filters from all groups
+     */
+    clearAllGroupFilters(): void;
+    /**
+     * Remove all filters from all shortcuts
+     */
+    clearAllShortcutFilters(): void;
+    /**
+     * Check if a group has a filter
+     * @param groupId - The group ID
+     * @returns True if the group has a filter
+     */
+    hasGroupFilter(groupId: string): boolean;
+    /**
+     * Check if a shortcut has a filter
+     * @param shortcutId - The shortcut ID
+     * @returns True if the shortcut has a filter
+     */
+    hasShortcutFilter(shortcutId: string): boolean;
+    /**
+     * Register multiple shortcuts in a single batch update
+     * @param shortcuts - Array of shortcuts to register
+     */
+    registerMany(shortcuts: KeyboardShortcut[]): void;
+    /**
+     * Unregister multiple shortcuts in a single batch update
+     * @param ids - Array of shortcut IDs to unregister
+     */
+    unregisterMany(ids: string[]): void;
+    /**
+     * Unregister multiple groups in a single batch update
+     * @param ids - Array of group IDs to unregister
+     */
+    unregisterGroups(ids: string[]): void;
+    /**
+     * Clear all shortcuts and groups (nuclear reset)
+     */
+    clearAll(): void;
+    /**
+     * Get all shortcuts belonging to a specific group
+     * @param groupId - The group ID
+     * @returns Array of shortcuts in the group
+     */
+    getGroupShortcuts(groupId: string): KeyboardShortcut[];
+    /**
+     * Normalize a key to lowercase for consistent comparison
+     */
+    private normalizeKey;
     /**
      * Find the group that contains a specific shortcut.
      *
@@ -359,8 +468,14 @@ declare class KeyboardShortcuts implements OnDestroy {
      * Accepts either a Set<string> (preferred) or an array for backwards compatibility.
      * Uses Set-based comparison: sizes must match and every element in target must exist in pressed.
      */
+    /**
+     * @deprecated Use KeyMatcher.keysMatch() instead
+     */
     protected keysMatch(pressedKeys: Set<string> | string[], targetKeys: string[]): boolean;
-    /** Compare two multi-step sequences for equality */
+    /**
+     * Compare two multi-step sequences for equality
+     * @deprecated Use KeyMatcher.stepsMatch() instead
+     */
     protected stepsMatch(a: string[][], b: string[][]): boolean;
     /** Safely clear any pending multi-step sequence */
     private clearPendingSequence;
@@ -370,8 +485,8 @@ declare class KeyboardShortcuts implements OnDestroy {
      * Evaluate group filters once per event and return the set of blocked group IDs.
      */
     protected precomputeBlockedGroups(event: KeyboardEvent): Set<string>;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<KeyboardShortcuts, never>;
-    static ɵprov: _angular_core.ɵɵInjectableDeclaration<KeyboardShortcuts>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KeyboardShortcuts, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<KeyboardShortcuts>;
 }
 
 /**
@@ -432,5 +547,170 @@ declare class KeyboardShortcutsErrorFactory {
     static cannotUnregisterGroup(id: string): KeyboardShortcutError;
 }
 
-export { KeyboardShortcutError, KeyboardShortcuts, KeyboardShortcutsErrorFactory, KeyboardShortcutsErrors };
-export type { KeyStep, KeyboardShortcut, KeyboardShortcutActiveUntil, KeyboardShortcutFilter, KeyboardShortcutGroup, KeyboardShortcutGroupOptions, KeyboardShortcutUI, KeyboardShortcutsErrorType };
+/**
+ * Configuration options for the KeyboardShortcuts service.
+ */
+interface KeyboardShortcutsConfig {
+}
+/**
+ * Injection token for providing KeyboardShortcuts configuration.
+ *
+ * @example
+ * ```typescript
+ * providers: [
+ *   provideKeyboardShortcutsConfig({ sequenceTimeoutMs: Infinity })
+ * ]
+ * ```
+ */
+declare const KEYBOARD_SHORTCUTS_CONFIG: InjectionToken<KeyboardShortcutsConfig>;
+/**
+ * Provides KeyboardShortcuts configuration using Angular's modern provider pattern.
+ *
+ * @param config - Configuration options for KeyboardShortcuts service
+ * @returns Provider array for use in Angular dependency injection
+ *
+ * @example
+ * ```typescript
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideKeyboardShortcutsConfig({ sequenceTimeoutMs: Infinity })
+ *   ]
+ * });
+ * ```
+ */
+declare function provideKeyboardShortcutsConfig(config: KeyboardShortcutsConfig): Provider[];
+
+/**
+ * Directive for registering keyboard shortcuts directly on elements in templates.
+ *
+ * This directive automatically:
+ * - Registers the shortcut when the directive initializes
+ * - Triggers the host element's click event (default) or executes a custom action
+ * - Unregisters the shortcut when the component is destroyed
+ *
+ * @example
+ * Basic usage with click trigger:
+ * ```html
+ * <button ngxKeys
+ *         keys="ctrl,s"
+ *         description="Save document"
+ *         (click)="save()">
+ *   Save
+ * </button>
+ * ```
+ *
+ * @example
+ * With custom action:
+ * ```html
+ * <button ngxKeys
+ *         keys="ctrl,s"
+ *         description="Save document"
+ *         [action]="customSaveAction">
+ *   Save
+ * </button>
+ * ```
+ *
+ * @example
+ * Multi-step shortcuts:
+ * ```html
+ * <button ngxKeys
+ *         [steps]="[['ctrl', 'k'], ['ctrl', 's']]"
+ *         description="Format document"
+ *         (click)="format()">
+ *   Format
+ * </button>
+ * ```
+ *
+ * @example
+ * Mac-specific keys:
+ * ```html
+ * <button ngxKeys
+ *         keys="ctrl,s"
+ *         macKeys="cmd,s"
+ *         description="Save document"
+ *         (click)="save()">
+ *   Save
+ * </button>
+ * ```
+ *
+ * @example
+ * On non-interactive elements:
+ * ```html
+ * <div ngxKeys
+ *      keys="?"
+ *      description="Show help"
+ *      [action]="showHelp">
+ *   Help content
+ * </div>
+ * ```
+ */
+declare class KeyboardShortcutDirective implements OnInit, OnDestroy {
+    private readonly keyboardShortcuts;
+    private readonly elementRef;
+    /**
+     * Comma-separated string of keys for the shortcut (e.g., "ctrl,s" or "alt,shift,k")
+     * Use either `keys` for single-step shortcuts or `steps` for multi-step shortcuts.
+     */
+    keys?: string;
+    /**
+     * Comma-separated string of keys for Mac users (e.g., "cmd,s")
+     * If not provided, `keys` will be used for all platforms.
+     */
+    macKeys?: string;
+    /**
+     * Multi-step shortcut as an array of key arrays.
+     * Each inner array represents one step in the sequence.
+     * Example: [['ctrl', 'k'], ['ctrl', 's']] for Ctrl+K followed by Ctrl+S
+     */
+    steps?: KeyStep[];
+    /**
+     * Multi-step shortcut for Mac users.
+     * Example: [['cmd', 'k'], ['cmd', 's']]
+     */
+    macSteps?: KeyStep[];
+    /**
+     * Description of what the shortcut does (displayed in help/documentation)
+     */
+    description: string;
+    /**
+     * Optional custom action to execute when the shortcut is triggered.
+     * If not provided, the directive will trigger a click event on the host element.
+     */
+    action?: Action;
+    /**
+     * Optional custom ID for the shortcut. If not provided, a unique ID will be generated.
+     * Useful for programmatically referencing the shortcut or for debugging.
+     */
+    shortcutId?: string;
+    /**
+     * Event emitted when the keyboard shortcut is triggered.
+     * This fires in addition to the action or click trigger.
+     */
+    readonly triggered: i0.OutputEmitterRef<void>;
+    /**
+     * Adds a data attribute to the host element for styling or testing purposes
+     */
+    get dataAttribute(): string;
+    private generatedId;
+    private isRegistered;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    /**
+     * Parse comma-separated key string into an array
+     * Example: "ctrl,s" -> ["ctrl", "s"]
+     */
+    private parseKeys;
+    /**
+     * Generate a unique ID for the shortcut based on the element and keys
+     */
+    private generateUniqueId;
+    /**
+     * Validate that required inputs are provided correctly
+     */
+    private validateInputs;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KeyboardShortcutDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KeyboardShortcutDirective, "[ngxKeys]", never, { "keys": { "alias": "keys"; "required": false; }; "macKeys": { "alias": "macKeys"; "required": false; }; "steps": { "alias": "steps"; "required": false; }; "macSteps": { "alias": "macSteps"; "required": false; }; "description": { "alias": "description"; "required": true; }; "action": { "alias": "action"; "required": false; }; "shortcutId": { "alias": "shortcutId"; "required": false; }; }, { "triggered": "triggered"; }, never, never, true, never>;
+}
+
+export { KEYBOARD_SHORTCUTS_CONFIG, KeyboardShortcutDirective, KeyboardShortcutError, KeyboardShortcuts, KeyboardShortcutsErrorFactory, KeyboardShortcutsErrors, provideKeyboardShortcutsConfig };
+export type { Action, KeyStep, KeyboardShortcut, KeyboardShortcutActiveUntil, KeyboardShortcutFilter, KeyboardShortcutGroup, KeyboardShortcutGroupOptions, KeyboardShortcutUI, KeyboardShortcutsConfig, KeyboardShortcutsErrorType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-keys",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A reactive Angular library for managing keyboard shortcuts with signals-based UI integration",
   "keywords": [
     "angular",