rx-hotkeys 2.6.1 → 3.1.1

package/README.md

@@ -1,19 +1,20 @@
-# rx-hotkeys: Advanced Keyboard Shortcut Management using rxjs
+# rx-hotkeys: Advanced Keyboard Shortcut Management with RxJS
 
-rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard shortcuts in web applications. It leverages RxJS to handle keyboard events, allowing for the registration of simple key combinations (e.g., `Ctrl+S`) and complex key sequences (e.g., `g` -> `i` for "go to inbox"). It supports contexts for enabling/disabling shortcuts based on application state, and provides a type-safe way to define keys using standard `KeyboardEvent.key` values.
+rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard shortcuts in web applications. It leverages the full power of RxJS to handle keyboard events, allowing for the registration of simple key combinations (e.g., `Ctrl+S`), complex key sequences (e.g., `g` -> `i` for "go to inbox"), and much more. It supports contexts for enabling/disabling shortcuts based on application state, element-scoped listeners, and provides a type-safe API for defining shortcuts.
 
-## Features
+## ✨ Features
 
-* **Key Combinations:** Define shortcuts that trigger when a specific key and modifier keys (Ctrl, Alt, Shift, Meta) are pressed simultaneously.
-* **Key Sequences:** Define shortcuts that trigger when a series of keys are pressed in a specific order.
-* **Sequence Timeouts:** Optional timeout between key presses in a sequence to prevent accidental triggers or indefinite waiting.
-* **Context Management:** Activate or deactivate groups of shortcuts based on the application's current state (e.g., "editor", "modal", "global").
-* **Strict Global Shortcuts:** Option to register global shortcuts that *only* fire when no other context is active, preventing them from triggering unintentionally.
-* **Type-Safe Key Definitions:** Uses an exported `Keys` object based on standard `KeyboardEvent.key` values for improved developer experience and fewer errors.
-* **RxJS Powered:** Built on RxJS for robust and efficient event handling.
-* **Prevent Default:** Option to prevent the default browser action for a triggered shortcut.
-* **Debug Mode:** Optional logging for easier development and troubleshooting.
-* **Clean API:** Simple and intuitive methods for adding, removing, and managing shortcuts.
+* **Official React Hooks**: Provides an official wrapper (`HotkeysProvider`, `useHotkeys`) for seamless, idiomatic integration with React.
+* **Fully Observable API**: Returns an RxJS `Observable` for each shortcut, allowing for powerful stream manipulation like chaining, filtering, debouncing, and merging with other streams.
+* **Flexible Shortcut Definitions**: Define shortcuts using simple, intuitive strings (e.g., `"ctrl+s"` or `"g -> i"`) in addition to the classic object-based configuration.
+* **Element-Scoped Listeners**: Attach shortcuts to specific DOM elements, so they are only active within a certain component or area, not just on the global `document`.
+* **`keyup` Event Support**: Trigger actions on key release (`keyup`) in addition to the default key press (`keydown`).
+* **Key Combinations & Sequences**: Supports both simultaneous key presses (`Ctrl+S`) and ordered key sequences (`g` -> `c`).
+* **Context Management**: Activate or deactivate groups of shortcuts based on the application's current state (e.g., "editor", "modal", "global").
+* **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.
+* **Debug Mode**: Optional, detailed console logging for easier development and troubleshooting.
 
 ## Installation
 
@@ -21,13 +22,47 @@ rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard s
 npm install rxjs rx-hotkeys
 ```
 
+## ⚠️ Breaking Changes (v3.0+)
+
+Starting with v3.0, the API has been significantly updated for a more powerful and idiomatic RxJS experience. This is a major breaking change.
+
+* `addCombination` and `addSequence` no longer accept a `callback` property in their configuration.
+* They now return an **`Observable<KeyboardEvent>`**.
+* You **must** now call `.subscribe()` on the returned Observable to execute your action.
+
+**Migration Example:**
+
+**Old (v2.x):**
+```typescript
+// The old way
+keyManager.addCombination({
+  id: "save",
+  keys: { key: Keys.S, ctrlKey: true },
+  callback: () => console.log("File saved!"),
+});
+```
+
+**New (v3.0+):**
+```typescript
+// The new, observable-based way
+const save$ = keyManager.addCombination({
+  id: "save",
+  keys: { key: Keys.S, ctrlKey: true }
+});
+
+const subscription = save$.subscribe(() => console.log("File saved!"));
+
+// Don't forget to unsubscribe when your component is destroyed!
+// The stream will also complete automatically if the shortcut is removed or keyManager.destroy() is called.
+// subscription.unsubscribe();
+```
 
 ## Basic Usage
 
-First, ensure you have the `rx-hotkeys` library and its helper Keys imported:
+First, ensure you have the `Hotkeys` class and its helper `Keys` object imported:
 
 ```typescript
-import { Hotkeys, Keys, KeyCombinationConfig, KeySequenceConfig } from 'rx-hotkeys';
+import { Hotkeys, Keys } from "rx-hotkeys";
 ```
 
 ### 1. Initialize Hotkeys
@@ -37,54 +72,78 @@ Create an instance of the `Hotkeys` class. You can optionally provide an initial
 ```typescript
 const keyManager = new Hotkeys(); // No initial context, debug mode off
 
-// With an initial context and debug mode enabled:
-// const keyManager = new Hotkeys('editor', true);
+// Or with an initial context and debug mode enabled:
+// const keyManager = new Hotkeys("editor", true);
 ```
 
 ### 2. Add a Key Combination
 
-Register a shortcut for a key combination, like Ctrl+S.
+Register a shortcut for a key combination, like `Ctrl+S`, by subscribing to the returned Observable.
 
 ```typescript
-const saveConfig: KeyCombinationConfig = {
+const save$ = keyManager.addCombination({
   id: "saveFile", // Unique ID for this shortcut
-  keys: { key: Keys.S, ctrlKey: true }, // Use Keys.S for 's' key
-  callback: () => {
-    console.log("Ctrl+S pressed: Save file action triggered!");
-  },
+  keys: { key: Keys.S, ctrlKey: true }, // Use Keys.S for "s" key
   preventDefault: true, // Prevent browser's default save action
   description: "Save the current file."
-};
+});
+
+const saveSubscription = save$.subscribe((event) => {
+  console.log("Ctrl+S pressed: Save file action triggered!", event);
+});
+```
+
+### 3. Define Shortcuts with Strings (New)
 
-keyManager.addCombination(saveConfig);
+You can also use more concise strings to define shortcuts.
+
+```typescript
+// Combination
+const open$ = keyManager.addCombination({ id: "openFile", keys: "ctrl+o" });
+open$.subscribe(() => console.log("Opening file..."));
+
+// Sequence
+const command$ = keyManager.addSequence({ id: "showCommandPalette", sequence: "cmd+k" }); // Note: "cmd+k" is a combination, not a sequence. Let's fix this example.
+const command$ = keyManager.addSequence({ id: "goToInbox", sequence: "g -> i" });
+command$.subscribe(() => console.log("Navigating to Inbox..."));
 ```
 
-### 3. Add a Key Sequence
+### 4. Add a Key Sequence
 
 Register a shortcut for a sequence of keys, like the Konami code.
 
 ```typescript
-const konamiConfig: KeySequenceConfig = {
+const konami$ = keyManager.addSequence({
   id: "konamiCode",
-  sequence: [
-    Keys.ArrowUp, Keys.ArrowUp,
-    Keys.ArrowDown, Keys.ArrowDown,
-    Keys.ArrowLeft, Keys.ArrowRight,
-    Keys.ArrowLeft, Keys.ArrowRight,
-    Keys.B, Keys.A // 'B' and 'A' from Keys
-  ],
-  callback: (event) => { // The last KeyboardEvent of the sequence is passed
-    console.log("Konami code entered!");
-    // event.preventDefault(); // Can also be done here if not set in config
-  },
+  sequence: "up -> up -> down -> down -> left -> right -> left -> right -> b -> a",
   sequenceTimeoutMs: 3000, // User has 3 seconds between each key press
   description: "Unlock special features."
-};
+});
 
-keyManager.addSequence(konamiConfig);
+konami$.subscribe((event) => { // The last KeyboardEvent of the sequence is emitted
+  console.log("Konami code entered!");
+});
 ```
 
-### 4. Manage Contexts
+### 5. Advanced Usage: Scopes and `keyup`
+
+You can scope a shortcut to a specific element and trigger it on `keyup`.
+
+```typescript
+const myInputField = document.getElementById("my-input");
+
+const submit$ = keyManager.addCombination({
+    id: "submitOnEnter",
+    keys: Keys.Enter,
+    target: myInputField, // Only active on this element
+    event: "keyup", // Trigger on key release
+    preventDefault: true
+});
+
+submit$.subscribe(() => console.log("Form submitted on Enter keyup!"));
+```
+
+### 6. Manage Contexts
 
 Control which shortcuts are active by setting the context.
 
@@ -96,80 +155,151 @@ keyManager.setContext("editor"); // Activates "editor" shortcuts and global shor
 keyManager.setContext(null);
 ```
 
-#### Global vs. Strict Global Shortcuts
+### 7. Clean Up
+
+When the Hotkeys instance is no longer needed (e.g., component unmount), call `destroy()` to clean up all internal streams and listeners, preventing memory leaks. This will also `complete` all active shortcut Observables.
 
-Global shortcuts (those without a `context` property) have two behaviors:
+```typescript
+// In a component lifecycle cleanup method or similar:
+keyManager.destroy();
+```
 
-* **Default Global**: By default, a global shortcut will fire in *any* context, unless a more specific shortcut for the same key combination exists for that context.
+---
 
-    ```typescript
-    // This shortcut for Ctrl+P will fire in the "editor" context, "modal" context, or any other,
-    // unless a specific "editor" shortcut for Ctrl+P exists.
-    keyManager.addCombination({ id: 'globalPrint', keys: { key: Keys.P, ctrlKey: true }, callback: myCallback });
-    ```
-* **Strict Global**: By passing `true` as the second argument to `addCombination` or `addSequence`, you can register a "strict" global shortcut. This shortcut will **only** fire when no context is active (`keyManager.getContext()` returns `null`).
+## Usage with React
 
-    ```typescript
-    // This help shortcut for "?" will ONLY fire when no other context is active.
-    keyManager.addCombination({ id: 'strictHelp', keys: Keys.QuestionMark, callback: openHelpModal, strict: true });
-    ```
+The library provides a dedicated React wrapper for the best developer experience.
 
-### 5. Clean Up
+### Step 1: Wrap Your App with `HotkeysProvider`
 
-When the Hotkeys instance is no longer needed (e.g., component unmount), call `destroy()` to clean up subscriptions and prevent memory leaks.
+First, import `HotkeysProvider` and wrap your root application component with it. This creates a single, shared instance of the hotkeys manager for your entire app.
 
-```typescript
-// In a component lifecycle cleanup method or similar:
-keyManager.destroy();
+```jsx
+// In your main App.js or index.js
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { HotkeysProvider } from 'rx-hotkeys/react';
+import App from './App';
+
+const root = ReactDOM.createRoot(document.getElementById('root'));
+root.render(
+  <React.StrictMode>
+    <HotkeysProvider debugMode={true}>
+      <App />
+    </HotkeysProvider>
+  </React.StrictMode>
+);
 ```
 
+### Step 2: Use the `useHotkeys` Hook in Your Components
+
+Now, you can use the `useHotkeys` and `useSequence` hooks anywhere in your component tree. The hook automatically handles registration, cleanup, and stale closures. You no longer need to provide a dependency array for your callback.
+
+```jsx
+// src/components/Counter.jsx
+import React, { useState } from 'react';
+import { useHotkeys, useSequence } from 'rx-hotkeys/react';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+
+  // The callback can safely use the latest component state (like `count`)
+  // without you needing to worry about stale closures or dependency arrays.
+  const handleIncrement = () => {
+    console.log(`Incrementing from ${count}...`);
+    setCount(count + 1);
+  };
+
+  // Register '+' key to increment.
+  useHotkeys('+', handleIncrement);
+
+  // Register 'c' key to increment, with options.
+  useHotkeys('c', handleIncrement, { preventDefault: true });
+
+  // Register a sequence to reset the counter.
+  useSequence('r -> e -> s -> e -> t', () => {
+    console.log('Resetting counter!');
+    setCount(0);
+  });
+
+  return (
+    <div>
+      <h2>Count: {count}</h2>
+      <p>Press '+' or 'c' to increment. Type 'reset' to reset.</p>
+    </div>
+  );
+}
+```
+
+### Step 3: Manage Context with `useScopedHotkeysContext`
+
+This hook allows a component (like a modal) to activate a specific context only while it is mounted.
+
+```jsx
+// src/components/MyModal.jsx
+import { useHotkeys, useScopedHotkeysContext } from 'rx-hotkeys/react';
+
+export function MyModal({ onClose }) {
+  // This activates the 'modal' context for all children of this component.
+  // When MyModal unmounts, this context is automatically removed from the stack.
+  useScopedHotkeysContext('modal');
+
+  // This hotkey will only be active when the 'modal' context is active.
+  useHotkeys('escape', onClose, { context: 'modal' });
+
+  return (
+    <div className="modal">
+      <p>This is a modal. Press ESC to close.</p>
+      {/* ... other modal content ... */}
+    </div>
+  );
+}
+```
+
+---
 
 ## API Reference
 
 ### `Keys` Object & `StandardKey` Type
 
-* `Keys`: An exported constant object containing standard KeyboardEvent.key string values (e.g., Keys.Enter, Keys.ArrowUp, Keys.A). It's highly recommended to use these when defining key in `KeyCombinationConfig` or keys in the sequence array of `KeySequenceConfig`.
-* `StandardKey`: A TypeScript type representing any valid key string from the Keys object.
+* `Keys`: An exported constant object containing standard `KeyboardEvent.key` string values (e.g., `Keys.Enter`, `Keys.ArrowUp`, `Keys.A`). It's highly recommended to use these for type safety and to avoid typos.
+* `StandardKey`: A TypeScript type representing any valid key string from the `Keys` object.
 
-### `Hotkeys` Class
+### `Hotkeys` Class (Core)
 
 `constructor(initialContext?: string | null, debugMode?: boolean)`
 
 Creates a new Hotkeys instance.
 
-`addCombination(config: KeyCombinationConfig): string | undefined`
+`addCombination(config: KeyCombinationConfig): Observable<KeyboardEvent>`
 
 Registers a key combination shortcut.
+* `config`: The `KeyCombinationConfig` object.
+* Returns an `Observable<KeyboardEvent>` that emits when the shortcut is triggered.
 
-* `config`: The KeyCombinationConfig object.
-* Returns the shortcut ID if successful, undefined otherwise.
-
-`addSequence(config: KeySequenceConfig): string | undefined`
+`addSequence(config: KeySequenceConfig): Observable<KeyboardEvent>`
 
 Registers a key sequence shortcut.
-
-* `config`: The KeySequenceConfig object.
-* Returns the shortcut ID if successful, undefined otherwise.
+* `config`: The `KeySequenceConfig` object.
+* Returns an `Observable<KeyboardEvent>` that emits the final `KeyboardEvent` when the sequence is completed.
 
 `setContext(contextName: string | null): boolean`
 
-Sets the active context. Only shortcuts matching this context or global shortcuts (no context) will trigger.
+Sets the active context. Only shortcuts matching this context or global shortcuts will trigger.
 
 `getContext(): string | null`
 
-Returns the current active context name, or null.
+Returns the current active context name, or `null`.
 
 `remove(id: string): boolean`
 
-Removes a registered shortcut by its ID.
-
-* Returns true if found and removed, false otherwise.
+Removes a registered shortcut by its ID. This will cause the corresponding Observable to complete.
+* Returns `true` if found and removed, `false` otherwise.
 
 `hasShortcut(id: string): boolean`
 
 Checks if a shortcut with the given ID is registered.
-
-* Returns true if it exists, false otherwise.
+* Returns `true` if it exists, `false` otherwise.
 
 `getActiveShortcuts(): { id: string; description?: string; context?: string | null; type: "combination" | "sequence" }[]`
 
@@ -183,34 +313,64 @@ Enables or disables console logging for debug purposes.
 
 Cleans up all subscriptions and resources. Essential to call to prevent memory leaks.
 
+### React Hooks (`rx-hotkeys/react`)
+
+`HotkeysProvider({ children, initialContext?, debugMode? })`
+
+A React component that provides the Hotkeys instance to its children.
+
+`useHotkeys(keys, callback, options?)`
+
+A React hook to register a key combination.
+* `keys: string | string[]`: The shortcut definition (e.g., `'ctrl+s'`).
+* `callback: (event: KeyboardEvent) => void`: The function to execute.
+* `options?: HotkeyHookOptions`: Optional config for `preventDefault`, `context`, `target`, etc.
+
+`useSequence(sequence, callback, options?)`
+
+A React hook to register a key sequence.
+* `sequence: string | string[]`: The sequence definition (e.g., `'g -> i'`).
+* `callback: (event: KeyboardEvent) => void`: The function to execute.
+* `options?: SequenceHookOptions`: Optional config for `preventDefault`, `context`, etc.
+
+`useScopedHotkeysContext(context)`
+
+A React hook to apply a specific context for the lifetime of the component.
+
 ### Configuration Interfaces
 
-`KeyCombinationConfig`
+#### `KeyCombinationConfig`
 
 * `id: string` (required): Unique identifier for the shortcut.
-* `keys: { key: StandardKey; ctrlKey?: boolean; altKey?: boolean; shiftKey?: boolean; metaKey?: boolean; } | StandardKey | Array<{ key: StandardKey; ctrlKey?: boolean; altKey?: boolean; shiftKey?: boolean; metaKey?: boolean; } | StandardKey>` (required): Defines the main key (from Keys) and optional modifier keys.
-* `callback: (event: KeyboardEvent) => void` (required): Function to execute when the shortcut is triggered. The triggering `KeyboardEvent` is passed as an argument.
+* `keys: string | KeyCombinationTrigger | KeyCombinationTrigger[]` (required): Defines the key(s). Can be a string (`"ctrl+s"`), a shorthand `StandardKey` (`Keys.Escape`), an object (`{ key: Keys.S, ctrlKey: true }`), or an array of these.
 * `context?: string | null`: Specifies the context in which this shortcut is active. If `null` or `undefined`, it's a global shortcut.
-* `preventDefault?: boolean`: If true, `event.preventDefault()` will be called when the shortcut triggers. Defaults to `false`.
+* `preventDefault?: boolean`: If `true`, `event.preventDefault()` will be called when the shortcut triggers. Defaults to `false`.
 * `description?: string`: An optional description for the shortcut (e.g., for help menus).
 * `strict?: boolean` (optional): If `true` and the shortcut has no `context`, it will only fire when no other context is active. Defaults to `false`.
+* `target?: HTMLElement` (optional): The DOM element to attach the listener to. Defaults to `document`.
+* `event?: "keydown" | "keyup"` (optional): The keyboard event to listen for. Defaults to `"keydown"`.
+* `callback?: (event: KeyboardEvent) => void` (**@deprecated**): This property is deprecated. Subscribe to the `Observable` returned by `addCombination` instead.
 
-`KeySequenceConfig`
+#### `KeySequenceConfig`
 
 * `id: string` (required): Unique identifier.
-* `sequence: StandardKey[]` (required): An array of `StandardKey` values (from `Keys`) representing the key sequence.
-* `callback: (event: KeyboardEvent) => void` (required): Function to execute. The last `KeyboardEvent` of the sequence is passed.
+* `sequence: string | StandardKey[]` (required): An array of `StandardKey` values or a string representation (e.g., `"g -> i"`).
 * `context?: string | null`: Context for activation.
-* `preventDefault?: boolean`: If true, `event.preventDefault()` is called for the last event in the sequence. Defaults to `false`.
+* `preventDefault?: boolean`: If `true`, `event.preventDefault()` is called for the last event in the sequence. Defaults to `false`.
 * `description?: string`: Optional description.
-* `sequenceTimeoutMs?: number`: Optional. Maximum time (in milliseconds) allowed between consecutive key presses in the sequence. If exceeded, the sequence resets. If `0` or `undefined`, no inter-key timeout is applied (uses simpler buffer-based matching).
-* `strict?: boolean` (optional): If `true` and the shortcut has no `context`, it will only fire when no other context is active. Defaults to `false`.
+* `sequenceTimeoutMs?: number`: Optional. Maximum time (in milliseconds) allowed between consecutive key presses in the sequence.
+* `strict?: boolean` (optional): If `true` and the shortcut has no `context`, it will only fire when no other context is active.
+* `target?: HTMLElement` (optional): The DOM element to attach the listener to. Defaults to `document`.
+* `event?: "keydown" | "keyup"` (optional): The keyboard event to listen for. Defaults to `"keydown"`.
+* `callback?: (event: KeyboardEvent) => void` (**@deprecated**): This property is deprecated. Subscribe to the `Observable` returned by `addSequence` instead.
 
+## Key Matching & Normalization
 
-## Key Matching Logic
+* **Case Insensitivity**: The library automatically handles case for you. `keys: "a"` will match both "a" and "A" presses. `keys: "escape"` will match an event where `event.key` is `"Escape"`.
+* **Aliases**: Common aliases are supported in string definitions, such as `cmd` for `Meta`, `option` for `Alt`, and `esc` for `Escape`.
+* **Special Keys**: For full type-safety, it is recommended to use the exported `Keys` object (e.g., `Keys.Enter`, `Keys.ArrowUp`).
 
-* **Single Character Keys** (e.g., `Keys.A`, `Keys.Digit7`): When you configure a shortcut with a single character key from `Keys`, the library matches it case-insensitively against the `event.key` from the browser. For example, if you configure `Keys.A`, it will trigger for both "a" and "A" key presses (assuming Shift isn't a required modifier).
-* **Special Keys** (e.g., `Keys.Enter`, `Keys.ArrowUp`, `Keys.Escape`): These are multi-character `event.key` values. The library matches these case-sensitively against the `event.key`. Using the `Keys` object ensures you provide the correct, standard case-sensitive string.
+---
 
 ## Contributing
 
@@ -218,12 +378,10 @@ Contributions are welcome! Please feel free to submit issues, fork the repositor
 
 ## Development Setup
 
-1. Clone the repository.
-2. Install dependencies: `npm install`.
-3. Run tests: `npm test`.
+1.  Clone the repository.
+2.  Install dependencies: `npm install`.
+3.  Run tests: `npm test`.
 
-# License
+## License
 
 This project is licensed under the MIT License.
-
-Powered by AI