rx-hotkeys 4.2.0 → 5.0.0

package/README.md

@@ -16,6 +16,7 @@ rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard s
 * **Strict Global Shortcuts**: Option to register global shortcuts that *only* fire when no other context is active.
 * **Type-Safe Key Definitions**: Uses an exported `Keys` object based on standard `KeyboardEvent.key` values for a superior developer experience and fewer errors.
 * **Sequence Timeouts**: Optional timeout between key presses in a sequence to prevent accidental triggers.
+* **Form, Editor & IME Guards**: Automatically suppresses accidental shortcut triggers while typing in `<input>`, `<textarea>`, `<select>`, rich-text editors (`contentEditable`), or during IME composition (`isComposing`). Easily opt-in or customize per shortcut.
 * **Debug Mode**: Optional, detailed console logging for easier development and troubleshooting.
 
 ## Installation
@@ -382,6 +383,10 @@ A hook to get direct access to the `Hotkeys` manager instance.
 * `target?: HTMLElement`: The DOM element to attach the listener to. Defaults to `document`.
 * `event?: "keydown" | "keyup"`: The keyboard event to listen for. Defaults to `"keydown"`.
 * `options?: AddEventListenerOptions`: Optional. Advanced options to pass directly to the underlying `addEventListener` call. Use this to control behaviors like `capture`, `passive`, or `once`.
+* `enableOnFormTags?: boolean | Array<"input" | "textarea" | "select" | string>`: Whether the shortcut triggers inside form elements (`<input>`, `<textarea>`, `<select>`). Defaults to `false` (suppressed to prevent accidental triggers). Set to `true` or an array of tags (e.g. `['input']`) to allow.
+* `enableOnContentEditable?: boolean`: Whether the shortcut triggers inside rich-text editors (`contentEditable`). Defaults to `false`. Set to `true` to allow.
+* `ignoreComposing?: boolean`: Whether shortcuts are suppressed during IME composition (Chinese/Japanese/Korean input methods). Defaults to `true`.
+* `filter?: (event: KeyboardEvent) => boolean`: Optional custom predicate function to determine if the event should be processed. Return `false` to suppress without calling `preventDefault()`.
 
 
 #### `KeyCombinationConfig`

package/dist/core/hotkeys.d.ts

@@ -1,10 +1,11 @@
 import { Observable, Subject } from "rxjs";
-import { type StandardKey } from "./keys.js";
-export declare enum ShortcutTypes {
-    Combination = "combination",
-    Sequence = "sequence"
-}
-interface ShortcutConfigBase {
+import { type StandardKey } from "./keys.ts";
+export declare const ShortcutTypes: Readonly<{
+    readonly Combination: "combination";
+    readonly Sequence: "sequence";
+}>;
+export type ShortcutTypes = typeof ShortcutTypes[keyof typeof ShortcutTypes];
+export interface ShortcutConfigBase {
     id: string;
     context?: string | null;
     preventDefault?: boolean;
@@ -39,6 +40,35 @@ interface ShortcutConfigBase {
      * @default undefined
      */
     options?: AddEventListenerOptions;
+    /**
+     * Controls whether the shortcut is enabled inside form elements (`<input>`, `<textarea>`, `<select>`).
+     * - `false` (default): Suppresses shortcuts while typing in form elements to prevent accidental triggers.
+     * - `true`: Enables the shortcut in all form elements.
+     * - `string[]`: Enables the shortcut only on specific tag names (e.g. `['input']` or `['textarea']`).
+     * @default false
+     */
+    enableOnFormTags?: boolean | Array<"input" | "textarea" | "select" | string>;
+    /**
+     * Controls whether the shortcut is enabled inside rich-text editors (`contentEditable` elements).
+     * - `false` (default): Suppresses shortcuts while editing rich-text content.
+     * - `true`: Enables the shortcut in `contentEditable` elements.
+     * @default false
+     */
+    enableOnContentEditable?: boolean;
+    /**
+     * Controls whether shortcuts are ignored during IME (Input Method Editor) composition,
+     * such as Chinese, Japanese, or Korean text input.
+     * - `true` (default): Suppresses shortcuts while IME composition is active (`event.isComposing` or `keyCode === 229`).
+     * - `false`: Allows shortcuts even during IME composition.
+     * @default true
+     */
+    ignoreComposing?: boolean;
+    /**
+     * Optional custom predicate function to decide whether a `KeyboardEvent` should be handled.
+     * Returning `false` will suppress the shortcut without triggering `preventDefault()`.
+     * @default undefined
+     */
+    filter?: (event: KeyboardEvent) => boolean;
 }
 /**
  * Defines a single key trigger, which can be a StandardKey (for simple presses like "Escape")
@@ -123,21 +153,7 @@ export interface ActiveShortcut {
  * Supports contexts to enable/disable shortcuts based on application state.
  */
 export declare class Hotkeys {
-    private static readonly KEYDOWN_EVENT;
-    private static readonly KEYUP_EVENT;
-    private static readonly LOG_PREFIX;
-    private static readonly NO_OVERRIDE;
-    private eventStreams;
-    private activeShortcuts;
-    private debugMode;
-    private contextStack$;
-    private overrideContext$;
-    /**
-     * An Observable that emits the new active context name (or null) whenever it changes.
-     * The active context is the override context if one is set, otherwise it's the context
-     * from the top of the stack.
-     */
-    private readonly activeContext$;
+    #private;
     /**
      * Creates an instance of Hotkeys.
      * @param initialContext - Optional initial context name. This forms the base of the context stack.
@@ -145,24 +161,6 @@ export declare class Hotkeys {
      * @throws Error if not in a browser environment (i.e., `document` or `performance` is undefined).
      */
     constructor(initialContext?: string | null, debugMode?: boolean);
-    /**
-     * Helper method to determine the active context based on override and stack.
-     */
-    private _resolveActiveContext;
-    private _normalizeAndParseTriggers;
-    private _normalizeSequence;
-    /**
-     * [PRIVATE] Generates a unique key for the stream cache based on event type and options.
-     */
-    private _getStreamCacheKey;
-    /**
-     * Gets or creates a shared event stream for a given event type, target, and options.
-     * @param eventType The type of event ("keydown" or "keyup").
-     * @param target The DOM element to attach the listener to.
-     * @param options The AddEventListenerOptions.
-     * @returns A shared Observable for the specified event.
-     */
-    private _getEventStream;
     /**
      * Sets a temporary, high-priority override context that takes precedence over the context stack.
      * @param contextName The override context to activate (can be a string or `null`).
@@ -217,33 +215,6 @@ export declare class Hotkeys {
      * ```
      */
     get onContextChange$(): Observable<string | null>;
-    /**
-     * Compares two sequences of StandardKey arrays to see if they are identical.
-     * @param seq1 - The first sequence array.
-     * @param seq2 - The second sequence array.
-     * @returns True if the sequences are identical, false otherwise.
-     */
-    private _areSequencesIdentical;
-    /**
-     * Checks if a given KeyCombinationConfig matches a given KeyboardEvent.
-     * This is used internally for priority checking.
-     * @param shortcutConfig The KeyCombinationConfig to check.
-     * @param event The KeyboardEvent to match against.
-     * @returns True if the shortcutConfig matches the event, false otherwise.
-     */
-    private _shortcutMatchesEvent;
-    private filterByContext;
-    private _registerShortcut;
-    /**
-     * Parses a single key trigger definition (either shorthand StandardKey or an object with modifiers)
-     * into its constituent parts: main key and modifier states.
-     * @param keyInput - The KeyCombinationTrigger to parse.
-     * @param shortcutId - The ID of the shortcut this key trigger belongs to (for logging).
-     * @returns An object containing configuredMainKey and modifier states, or null if parsing fails.
-     */
-    private _parseKeyTrigger;
-    private _parseCombinationString;
-    private _parseSequenceString;
     /**
      * Registers a key combination shortcut (e.g., Ctrl+S, Shift+Enter, or a single key like Escape)
      * and returns an Observable that emits the `KeyboardEvent` when the combination is triggered.

package/dist/core/hotkeys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../../src/core/hotkeys.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../../src/core/hotkeys.ts"],"names":[],"mappings":"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"}