@voquill/desktop-utils 0.3.3

package/dist/activation.d.ts

@@ -0,0 +1,28 @@
+export declare class ActivationController {
+    private _isActive;
+    private _isLocked;
+    private ignoreNextActivation;
+    private deactivateTimer;
+    private pressTimestamp;
+    private lastReleaseTimestamp;
+    private toggleInProgress;
+    private onActivateRef;
+    private onDeactivateRef;
+    constructor(onActivate: () => void, onDeactivate: () => void);
+    setCallbacks(onActivate: () => void, onDeactivate: () => void): void;
+    get isActive(): boolean;
+    get isLocked(): boolean;
+    get shouldIgnoreActivation(): boolean;
+    get hasHadRelease(): boolean;
+    private clearPendingDeactivation;
+    private doActivate;
+    private doDeactivate;
+    handlePress(): void;
+    handleRelease(): void;
+    toggle(): void;
+    reset(): void;
+    forceReset(): void;
+    clearIgnore(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=activation.d.ts.map

package/dist/activation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation.d.ts","sourceRoot":"","sources":["../src/activation.ts"],"names":[],"mappings":"AAEA,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,eAAe,CAA8C;IACrE,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,oBAAoB,CAAuB;IACnD,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,eAAe,CAA6B;gBAExC,UAAU,EAAE,MAAM,IAAI,EAAE,YAAY,EAAE,MAAM,IAAI;IAK5D,YAAY,CAAC,UAAU,EAAE,MAAM,IAAI,EAAE,YAAY,EAAE,MAAM,IAAI,GAAG,IAAI;IAKpE,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,sBAAsB,IAAI,OAAO,CAEpC;IAED,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,OAAO,CAAC,wBAAwB;IAOhC,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,YAAY;IAcpB,WAAW,IAAI,IAAI;IAenB,aAAa,IAAI,IAAI;IAuBrB,MAAM,IAAI,IAAI;IAkBd,KAAK,IAAI,IAAI;IAOb,UAAU,IAAI,IAAI;IAQlB,WAAW,IAAI,IAAI;IAInB,OAAO,IAAI,IAAI;CAGhB"}

package/dist/activation.js

@@ -0,0 +1,128 @@
+const TAP_THRESHOLD_MS = 500;
+export class ActivationController {
+    constructor(onActivate, onDeactivate) {
+        this._isActive = false;
+        this._isLocked = false;
+        this.ignoreNextActivation = false;
+        this.deactivateTimer = null;
+        this.pressTimestamp = null;
+        this.lastReleaseTimestamp = null;
+        this.toggleInProgress = false;
+        this.onActivateRef = null;
+        this.onDeactivateRef = null;
+        this.onActivateRef = onActivate;
+        this.onDeactivateRef = onDeactivate;
+    }
+    setCallbacks(onActivate, onDeactivate) {
+        this.onActivateRef = onActivate;
+        this.onDeactivateRef = onDeactivate;
+    }
+    get isActive() {
+        return this._isActive;
+    }
+    get isLocked() {
+        return this._isLocked;
+    }
+    get shouldIgnoreActivation() {
+        return this.ignoreNextActivation;
+    }
+    get hasHadRelease() {
+        return this.lastReleaseTimestamp !== null;
+    }
+    clearPendingDeactivation() {
+        if (this.deactivateTimer) {
+            clearTimeout(this.deactivateTimer);
+            this.deactivateTimer = null;
+        }
+    }
+    doActivate(timestamp) {
+        if (this._isActive)
+            return;
+        this.clearPendingDeactivation();
+        this._isActive = true;
+        this.pressTimestamp = timestamp;
+        this.onActivateRef?.();
+    }
+    doDeactivate() {
+        const wasActive = this._isActive;
+        this.clearPendingDeactivation();
+        this._isActive = false;
+        this._isLocked = false;
+        this.ignoreNextActivation = false;
+        this.pressTimestamp = null;
+        if (wasActive) {
+            this.onDeactivateRef?.();
+        }
+    }
+    handlePress() {
+        if (this.ignoreNextActivation) {
+            return;
+        }
+        const now = Date.now();
+        this.clearPendingDeactivation();
+        this.pressTimestamp = now;
+        if (!this._isActive) {
+            this.doActivate(now);
+        }
+    }
+    handleRelease() {
+        this.ignoreNextActivation = false;
+        this.lastReleaseTimestamp = Date.now();
+        if (!this._isActive)
+            return;
+        const now = Date.now();
+        const pressedAt = this.pressTimestamp ?? now;
+        const elapsed = now - pressedAt;
+        if (elapsed < TAP_THRESHOLD_MS) {
+            if (this._isLocked) {
+                this.doDeactivate();
+            }
+            else {
+                this._isLocked = true;
+            }
+        }
+        else {
+            if (!this._isLocked) {
+                this.doDeactivate();
+            }
+        }
+    }
+    toggle() {
+        if (this.toggleInProgress) {
+            return;
+        }
+        this.toggleInProgress = true;
+        try {
+            if (this._isActive) {
+                this.doDeactivate();
+            }
+            else {
+                this._isLocked = true;
+                this.lastReleaseTimestamp = Date.now();
+                this.doActivate(Date.now());
+            }
+        }
+        finally {
+            this.toggleInProgress = false;
+        }
+    }
+    reset() {
+        this.ignoreNextActivation = false;
+        this.lastReleaseTimestamp = null;
+        this.clearPendingDeactivation();
+        this.doDeactivate();
+    }
+    forceReset() {
+        this._isActive = false;
+        this._isLocked = false;
+        this.ignoreNextActivation = false;
+        this.pressTimestamp = null;
+        this.clearPendingDeactivation();
+    }
+    clearIgnore() {
+        this.ignoreNextActivation = false;
+    }
+    dispose() {
+        this.clearPendingDeactivation();
+    }
+}

package/dist/hotkey.d.ts

@@ -0,0 +1,45 @@
+import type { ActivationController } from "./activation";
+type HoldAction = {
+    controller: ActivationController;
+    combos: string[][];
+    triggerCount: number;
+};
+export type UseHotkeyHoldManyArgs = {
+    actions: HoldAction[];
+    keysHeld: string[];
+    isDisabled?: boolean;
+};
+export type UseHotkeyHoldArgs = {
+    controller: ActivationController;
+    combos: string[][];
+    triggerCount: number;
+    keysHeld: string[];
+    isDisabled?: boolean;
+};
+export type UseHotkeyFireArgs = {
+    combos: string[][];
+    triggerCount: number;
+    keysHeld: string[];
+    isDisabled?: boolean;
+    onFire?: () => void;
+};
+/**
+ * Drives one or more {@link ActivationController}s from a press/release model
+ * over the supplied keys. The consumer owns all state (held keys, combos per
+ * action, trigger counts) and feeds it in; this hook is pure behavior.
+ *
+ * Controller lifetimes are the consumer's responsibility — this hook does not
+ * call `.dispose()`.
+ */
+export declare const useHotkeyHoldMany: (args: UseHotkeyHoldManyArgs) => void;
+/**
+ * Single-controller variant of {@link useHotkeyHoldMany}.
+ */
+export declare const useHotkeyHold: (args: UseHotkeyHoldArgs) => void;
+/**
+ * Fires `onFire` on a press-then-release (tap) that matches one of the combos,
+ * and also when `triggerCount` increments. The consumer owns all state.
+ */
+export declare const useHotkeyFire: (args: UseHotkeyFireArgs) => void;
+export {};
+//# sourceMappingURL=hotkey.d.ts.map

package/dist/hotkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotkey.d.ts","sourceRoot":"","sources":["../src/hotkey.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD,KAAK,UAAU,GAAG;IAChB,UAAU,EAAE,oBAAoB,CAAC;IACjC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,oBAAoB,CAAC;IACjC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,qBAAqB,KAAG,IAgG/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,iBAAiB,KAAG,IAgBvD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,iBAAiB,KAAG,IAiHvD,CAAC"}

package/dist/hotkey.js

@@ -0,0 +1,179 @@
+import { useEffect, useMemo, useRef } from "react";
+/**
+ * Drives one or more {@link ActivationController}s from a press/release model
+ * over the supplied keys. The consumer owns all state (held keys, combos per
+ * action, trigger counts) and feeds it in; this hook is pure behavior.
+ *
+ * Controller lifetimes are the consumer's responsibility — this hook does not
+ * call `.dispose()`.
+ */
+export const useHotkeyHoldMany = (args) => {
+    const isDisabled = Boolean(args.isDisabled);
+    const { actions, keysHeld } = args;
+    const combosSignature = useMemo(() => actions.map((a) => JSON.stringify(a.combos)).join("|"), [actions]);
+    const wasPressedRef = useRef(new Map());
+    useEffect(() => {
+        const normalize = (key) => key.toLowerCase();
+        const matchesCombo = (held, combo) => {
+            if (combo.length === 0) {
+                return false;
+            }
+            const uniqueHeld = Array.from(new Set(held.map((key) => normalize(key))));
+            const required = Array.from(new Set(combo.map((key) => normalize(key))));
+            if (uniqueHeld.length !== required.length) {
+                return false;
+            }
+            const heldSet = new Set(uniqueHeld);
+            return required.every((key) => heldSet.has(key));
+        };
+        for (const action of actions) {
+            const availableCombos = action.combos;
+            const wasPressed = wasPressedRef.current.get(action.controller) ?? false;
+            const isPressed = availableCombos.some((combo) => matchesCombo(keysHeld, combo));
+            if (isDisabled) {
+                wasPressedRef.current.set(action.controller, isPressed);
+                action.controller.reset();
+                continue;
+            }
+            if (action.controller.isActive &&
+                !wasPressed &&
+                !action.controller.hasHadRelease) {
+                action.controller.forceReset();
+            }
+            if (availableCombos.length === 0) {
+                wasPressedRef.current.set(action.controller, false);
+                action.controller.reset();
+                continue;
+            }
+            if (isPressed && !wasPressed) {
+                if (action.controller.shouldIgnoreActivation) {
+                    wasPressedRef.current.set(action.controller, isPressed);
+                    continue;
+                }
+                action.controller.handlePress();
+            }
+            else if (!isPressed && wasPressed) {
+                action.controller.clearIgnore();
+                action.controller.handleRelease();
+            }
+            wasPressedRef.current.set(action.controller, isPressed);
+        }
+    }, [keysHeld, combosSignature, actions, isDisabled]);
+    const triggerSignature = useMemo(() => actions.map((a) => a.triggerCount).join(","), [actions]);
+    const prevTriggerCountsRef = useRef(new Map());
+    useEffect(() => {
+        if (!isDisabled) {
+            for (const action of actions) {
+                const prev = prevTriggerCountsRef.current.get(action.controller) ?? 0;
+                const curr = action.triggerCount;
+                if (curr > prev) {
+                    action.controller.toggle();
+                }
+            }
+        }
+        for (const action of actions) {
+            prevTriggerCountsRef.current.set(action.controller, action.triggerCount);
+        }
+    }, [triggerSignature, isDisabled, actions]);
+};
+/**
+ * Single-controller variant of {@link useHotkeyHoldMany}.
+ */
+export const useHotkeyHold = (args) => {
+    const actions = useMemo(() => [
+        {
+            controller: args.controller,
+            combos: args.combos,
+            triggerCount: args.triggerCount,
+        },
+    ], [args.controller, args.combos, args.triggerCount]);
+    useHotkeyHoldMany({
+        actions,
+        keysHeld: args.keysHeld,
+        isDisabled: args.isDisabled,
+    });
+};
+/**
+ * Fires `onFire` on a press-then-release (tap) that matches one of the combos,
+ * and also when `triggerCount` increments. The consumer owns all state.
+ */
+export const useHotkeyFire = (args) => {
+    const isDisabled = Boolean(args.isDisabled);
+    const { combos, triggerCount, keysHeld, onFire } = args;
+    const previousKeysHeldRef = useRef([]);
+    const comboStateRef = useRef(new Map());
+    const wasDisabledRef = useRef(false);
+    useEffect(() => {
+        if (isDisabled) {
+            previousKeysHeldRef.current = keysHeld;
+            comboStateRef.current.clear();
+            wasDisabledRef.current = true;
+            return;
+        }
+        const wasDisabled = wasDisabledRef.current;
+        wasDisabledRef.current = false;
+        const normalize = (key) => key.toLowerCase();
+        const toNormalizedSet = (keys) => new Set(keys.map((key) => normalize(key)));
+        const getComboId = (requiredKeys) => Array.from(requiredKeys).sort().join("+");
+        const previousSet = toNormalizedSet(previousKeysHeldRef.current);
+        const currentSet = toNormalizedSet(keysHeld);
+        const activeComboIds = new Set();
+        let shouldFire = false;
+        for (const combo of combos) {
+            if (combo.length === 0) {
+                continue;
+            }
+            const requiredSet = toNormalizedSet(combo);
+            if (requiredSet.size === 0) {
+                continue;
+            }
+            const comboId = getComboId(requiredSet);
+            activeComboIds.add(comboId);
+            const comboState = comboStateRef.current.get(comboId) ?? {
+                contaminated: false,
+            };
+            const previousIncludesAll = Array.from(requiredSet).every((key) => previousSet.has(key));
+            const currentIncludesAll = Array.from(requiredSet).every((key) => currentSet.has(key));
+            const previousExact = previousIncludesAll && previousSet.size === requiredSet.size;
+            const currentExact = currentIncludesAll && currentSet.size === requiredSet.size;
+            if (wasDisabled && currentIncludesAll) {
+                comboState.contaminated = true;
+            }
+            if (!previousIncludesAll && currentIncludesAll) {
+                comboState.contaminated = false;
+            }
+            if (currentIncludesAll && !currentExact) {
+                comboState.contaminated = true;
+            }
+            if (previousExact &&
+                !currentExact &&
+                !currentIncludesAll &&
+                !comboState.contaminated) {
+                shouldFire = true;
+            }
+            if (!currentIncludesAll) {
+                comboState.contaminated = false;
+            }
+            comboStateRef.current.set(comboId, comboState);
+            if (shouldFire) {
+                break;
+            }
+        }
+        for (const comboId of comboStateRef.current.keys()) {
+            if (!activeComboIds.has(comboId)) {
+                comboStateRef.current.delete(comboId);
+            }
+        }
+        if (shouldFire) {
+            onFire?.();
+        }
+        previousKeysHeldRef.current = keysHeld;
+    }, [keysHeld, combos, isDisabled, onFire]);
+    const prevTriggerCountRef = useRef(triggerCount);
+    useEffect(() => {
+        if (!isDisabled && triggerCount > prevTriggerCountRef.current) {
+            onFire?.();
+        }
+        prevTriggerCountRef.current = triggerCount;
+    }, [triggerCount, isDisabled, onFire]);
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./activation";
+export * from "./hotkey";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./activation";
+export * from "./hotkey";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@voquill/desktop-utils",
+  "version": "0.3.3",
+  "description": "Shared React hooks and logic for Voquill desktop-style clients.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voquill/voquill.git",
+    "directory": "packages/desktop-utils"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@voquill/typescript-config": "workspace:*",
+    "react": "^19.2.4",
+    "typescript": "5.9.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}