rx-hotkeys 2.5.0 → 2.6.0

package/dist/tttt.js

@@ -0,0 +1,301 @@
+import { fromEvent, BehaviorSubject, EMPTY, filter, map, bufferCount, withLatestFrom, tap, catchError, scan, merge, } from "rxjs";
+// --- Enums, Interfaces and Types ---
+export var ShortcutTypes;
+(function (ShortcutTypes) {
+    ShortcutTypes["Combination"] = "combination";
+    ShortcutTypes["Sequence"] = "sequence";
+})(ShortcutTypes || (ShortcutTypes = {}));
+var EmitStates;
+(function (EmitStates) {
+    EmitStates[EmitStates["Emit"] = 0] = "Emit";
+    EmitStates[EmitStates["Ignore"] = 1] = "Ignore";
+    EmitStates[EmitStates["InProgress"] = 2] = "InProgress";
+})(EmitStates || (EmitStates = {}));
+function compareKey(eventKey, configuredKey) {
+    if (configuredKey.length === 1 && eventKey.length === 1) {
+        return eventKey.toLowerCase() === configuredKey.toLowerCase();
+    }
+    return eventKey === configuredKey;
+}
+export class Hotkeys {
+    static KEYDOWN_EVENT = "keydown";
+    static LOG_PREFIX = "Hotkeys:";
+    keydown$;
+    activeContext$;
+    activeShortcuts;
+    debugMode;
+    constructor(initialContext = null, debugMode = false) {
+        this.debugMode = debugMode;
+        if (typeof document === "undefined" || typeof performance === "undefined") {
+            throw new Error(`${Hotkeys.LOG_PREFIX} Hotkeys can only be used in a browser environment.`);
+        }
+        this.keydown$ = fromEvent(document, Hotkeys.KEYDOWN_EVENT);
+        this.activeContext$ = new BehaviorSubject(initialContext);
+        this.activeShortcuts = new Map();
+        if (this.debugMode) {
+            console.log(`${Hotkeys.LOG_PREFIX} Library initialized. Initial context: "${initialContext}".`);
+        }
+    }
+    setContext(contextName) {
+        const currentContext = this.activeContext$.getValue();
+        if (currentContext === contextName) {
+            return false;
+        }
+        if (this.debugMode) {
+            console.log(`${Hotkeys.LOG_PREFIX} Context changed from "${currentContext}" to "${contextName}".`);
+        }
+        this.activeContext$.next(contextName);
+        return true;
+    }
+    getContext() {
+        return this.activeContext$.getValue();
+    }
+    setDebugMode(enable) {
+        if (this.debugMode === enable)
+            return;
+        this.debugMode = enable;
+        console.log(`${Hotkeys.LOG_PREFIX} Debug mode ${enable ? "enabled" : "disabled"}.`);
+    }
+    hasShortcut(id) {
+        return this.activeShortcuts.has(id);
+    }
+    get onContextChange$() {
+        return this.activeContext$.asObservable();
+    }
+    _areSequencesIdentical(seq1, seq2) {
+        if (seq1.length !== seq2.length)
+            return false;
+        return seq1.every((key, index) => key === seq2[index]);
+    }
+    _shortcutMatchesEvent(shortcutConfig, event) {
+        const keyTriggers = Array.isArray(shortcutConfig.keys) ? shortcutConfig.keys : [shortcutConfig.keys];
+        for (const keyInput of keyTriggers) {
+            const parsed = this._parseKeyTrigger(keyInput, shortcutConfig.id);
+            if (!parsed)
+                continue;
+            const { configuredMainKey, ctrlKeyConfig, altKeyConfig, shiftKeyConfig, metaKeyConfig } = parsed;
+            const keyMatch = compareKey(event.key, configuredMainKey);
+            if (!keyMatch)
+                continue;
+            const ctrlMatch = (ctrlKeyConfig === undefined) ? true : (event.ctrlKey === ctrlKeyConfig);
+            const altMatch = (altKeyConfig === undefined) ? true : (event.altKey === altKeyConfig);
+            const shiftMatch = (shiftKeyConfig === undefined) ? true : (event.shiftKey === shiftKeyConfig);
+            const metaMatch = (metaKeyConfig === undefined) ? true : (event.metaKey === metaKeyConfig);
+            if (ctrlMatch && altMatch && shiftMatch && metaMatch) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Pre-filters a stream of keyboard events based on context and strictness rules.
+     */
+    filterByContext(source$, context, strict = false) {
+        return source$.pipe(withLatestFrom(this.activeContext$), filter(([, activeCtx]) => {
+            // Case 1: Strictly global shortcut. Only allow if no context is active.
+            if (context == null && strict) {
+                return activeCtx === null;
+            }
+            // Case 2: Shortcut with a specific context. Only allow if context matches.
+            if (context != null) {
+                return activeCtx === context;
+            }
+            // Case 3: Default global shortcut (context: null, strict: false).
+            // Always allow the event to pass through to the priority filter.
+            return true;
+        }), map(([event]) => event));
+    }
+    _registerShortcut(config, subscription, type, detailsForLog) {
+        const existingShortcut = this.activeShortcuts.get(config.id);
+        if (existingShortcut) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut with ID "${config.id}" already exists. It will be overwritten.`);
+            existingShortcut.subscription.unsubscribe();
+        }
+        this.activeShortcuts.set(config.id, { id: config.id, config, subscription });
+        if (this.debugMode) {
+            console.log(`${Hotkeys.LOG_PREFIX} ${type} shortcut "${config.id}" added. ${detailsForLog}, Context: ${config.context ?? "any"}`);
+        }
+        return config.id;
+    }
+    _parseKeyTrigger(keyInput, shortcutId) {
+        if (typeof keyInput === "string") {
+            if (!keyInput) {
+                console.warn(`${Hotkeys.LOG_PREFIX} Invalid key (shorthand) in shortcut "${shortcutId}".`);
+                return null;
+            }
+            return {
+                configuredMainKey: keyInput, ctrlKeyConfig: false, altKeyConfig: false,
+                shiftKeyConfig: false, metaKeyConfig: false,
+                logDetails: `key: "${keyInput}" (no mods)`,
+            };
+        }
+        else {
+            if (!keyInput.key) {
+                console.warn(`${Hotkeys.LOG_PREFIX} Invalid "key" property in shortcut "${shortcutId}".`);
+                return null;
+            }
+            const logDetails = `key: "${keyInput.key}"` +
+                (keyInput.ctrlKey !== undefined ? `, ctrl: ${keyInput.ctrlKey}` : "") +
+                (keyInput.altKey !== undefined ? `, alt: ${keyInput.altKey}` : "") +
+                (keyInput.shiftKey !== undefined ? `, shift: ${keyInput.shiftKey}` : "") +
+                (keyInput.metaKey !== undefined ? `, meta: ${keyInput.metaKey}` : "");
+            return {
+                configuredMainKey: keyInput.key, ctrlKeyConfig: keyInput.ctrlKey, altKeyConfig: keyInput.altKey,
+                shiftKeyConfig: keyInput.shiftKey, metaKeyConfig: keyInput.metaKey,
+                logDetails,
+            };
+        }
+    }
+    addCombination(config, strict = false) {
+        const { keys, callback, context, preventDefault = false, id } = config;
+        if (context && strict) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" has both a context and the 'strict' flag. The flag will be ignored.`);
+        }
+        const keyTriggers = Array.isArray(keys) ? keys : [keys];
+        if (keyTriggers.length === 0) {
+            console.warn(`${Hotkeys.LOG_PREFIX} "keys" array for shortcut "${id}" is empty.`);
+            return undefined;
+        }
+        // The base stream is now created with our centralized helper
+        const baseStream$ = this.filterByContext(this.keydown$, context, strict);
+        const observables = [];
+        const logParts = [];
+        for (const keyInput of keyTriggers) {
+            const parsedTrigger = this._parseKeyTrigger(keyInput, id);
+            if (!parsedTrigger)
+                return undefined;
+            const { configuredMainKey, ctrlKeyConfig, altKeyConfig, shiftKeyConfig, metaKeyConfig, logDetails } = parsedTrigger;
+            logParts.push(`{ ${logDetails} }`);
+            const stream = baseStream$.pipe(filter(event => {
+                const ctrlMatch = (ctrlKeyConfig === undefined) ? true : (event.ctrlKey === ctrlKeyConfig);
+                const altMatch = (altKeyConfig === undefined) ? true : (event.altKey === altKeyConfig);
+                const shiftMatch = (shiftKeyConfig === undefined) ? true : (event.shiftKey === shiftKeyConfig);
+                const metaMatch = (metaKeyConfig === undefined) ? true : (event.metaKey === metaKeyConfig);
+                return ctrlMatch && altMatch && shiftMatch && metaMatch && compareKey(event.key, configuredMainKey);
+            }), filter(event => {
+                if (context != null || strict)
+                    return true;
+                const currentSpecificContext = this.activeContext$.getValue();
+                if (currentSpecificContext == null)
+                    return true;
+                for (const [, otherAS] of this.activeShortcuts) {
+                    if (otherAS.config.id !== config.id &&
+                        'keys' in otherAS.config &&
+                        otherAS.config.context === currentSpecificContext &&
+                        this._shortcutMatchesEvent(otherAS.config, event)) {
+                        if (this.debugMode) {
+                            console.log(`${Hotkeys.LOG_PREFIX} Global shortcut "${config.id}" suppressed by "${otherAS.config.id}".`);
+                        }
+                        return false;
+                    }
+                }
+                return true;
+            }));
+            observables.push(stream);
+        }
+        if (observables.length === 0)
+            return undefined;
+        const finalShortcut$ = merge(...observables);
+        const overallLogDetails = `Triggers: [ ${logParts.join(", ")} ]`;
+        const subscription = finalShortcut$.pipe(tap(event => {
+            if (preventDefault)
+                event.preventDefault();
+        }), catchError(err => {
+            console.error(`${Hotkeys.LOG_PREFIX} Error in stream for shortcut "${id}":`, err);
+            return EMPTY;
+        })).subscribe(event => {
+            try {
+                callback(event);
+            }
+            catch (e) {
+                console.error(`${Hotkeys.LOG_PREFIX} Error in callback for shortcut "${id}":`, e);
+            }
+        });
+        return this._registerShortcut(config, subscription, ShortcutTypes.Combination, overallLogDetails);
+    }
+    addSequence(config, strict = false) {
+        const { sequence, callback, context, preventDefault = false, id, sequenceTimeoutMs } = config;
+        if (!Array.isArray(sequence) || sequence.length === 0) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Sequence for shortcut "${id}" is empty.`);
+            return undefined;
+        }
+        if (context && strict) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" has both a context and 'strict' flag. Flag ignored.`);
+        }
+        const baseKeydownStream$ = this.filterByContext(this.keydown$, context, strict);
+        let shortcut$;
+        if (sequenceTimeoutMs && sequenceTimeoutMs > 0) {
+            shortcut$ = baseKeydownStream$.pipe(scan((acc, event) => {
+                let { matchedEvents, lastEventTime } = acc;
+                const currentTime = performance.now();
+                if (acc.emitState === EmitStates.Emit)
+                    matchedEvents = [];
+                if (matchedEvents.length > 0 && (currentTime - lastEventTime > sequenceTimeoutMs))
+                    matchedEvents = [];
+                if (compareKey(event.key, sequence[matchedEvents.length])) {
+                    const newMatched = [...matchedEvents, event];
+                    if (newMatched.length === sequence.length)
+                        return { matchedEvents: newMatched, lastEventTime: currentTime, emitState: EmitStates.Emit };
+                    return { matchedEvents: newMatched, lastEventTime: currentTime, emitState: EmitStates.InProgress };
+                }
+                if (compareKey(event.key, sequence[0]))
+                    return { matchedEvents: [event], lastEventTime: currentTime, emitState: EmitStates.InProgress };
+                return { matchedEvents: [], lastEventTime: 0, emitState: EmitStates.Ignore };
+            }, { matchedEvents: [], lastEventTime: 0, emitState: EmitStates.Ignore }), filter(state => state.emitState === EmitStates.Emit), map(state => state.matchedEvents));
+        }
+        else {
+            shortcut$ = baseKeydownStream$.pipe(bufferCount(sequence.length, 1), filter((events) => events.every((event, index) => compareKey(event.key, sequence[index]))));
+        }
+        const finalShortcutWithPriority$ = shortcut$.pipe(filter(() => {
+            if (context != null || strict)
+                return true;
+            const currentSpecificContext = this.activeContext$.getValue();
+            if (currentSpecificContext == null)
+                return true;
+            for (const [, otherAS] of this.activeShortcuts) {
+                if (otherAS.config.id !== config.id &&
+                    "sequence" in otherAS.config &&
+                    otherAS.config.context === currentSpecificContext &&
+                    this._areSequencesIdentical(config.sequence, otherAS.config.sequence)) {
+                    return false;
+                }
+            }
+            return true;
+        }), tap(events => {
+            if (preventDefault && events.length > 0)
+                events[events.length - 1].preventDefault();
+        }));
+        const subscription = finalShortcutWithPriority$.subscribe((events) => {
+            try {
+                if (events.length > 0)
+                    callback(events[events.length - 1]);
+            }
+            catch (e) {
+                console.error(`${Hotkeys.LOG_PREFIX} Error in callback for sequence shortcut "${id}":`, e);
+            }
+        });
+        return this._registerShortcut(config, subscription, ShortcutTypes.Sequence, `Sequence: ${sequence.join(" -> ")}`);
+    }
+    remove(id) {
+        const shortcut = this.activeShortcuts.get(id);
+        if (shortcut) {
+            shortcut.subscription.unsubscribe();
+            this.activeShortcuts.delete(id);
+            return true;
+        }
+        return false;
+    }
+    getActiveShortcuts() {
+        return Array.from(this.activeShortcuts.values()).map(activeShortcut => ({
+            id: activeShortcut.id,
+            description: activeShortcut.config.description,
+            context: activeShortcut.config.context,
+            type: "sequence" in activeShortcut.config ? ShortcutTypes.Sequence : ShortcutTypes.Combination
+        }));
+    }
+    destroy() {
+        this.activeShortcuts.forEach(shortcut => shortcut.subscription.unsubscribe());
+        this.activeShortcuts.clear();
+        this.activeContext$.complete();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rx-hotkeys",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "type": "module",
   "scripts": {
     "build": "tsc",