react-hook-toolkit 3.0.2 → 3.0.3

package/dist/chunk1516/chunk3312.js

@@ -0,0 +1,462 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function getSpeechRecognitionCtor() {
+    if (typeof window === 'undefined')
+        return null;
+    const w = window;
+    return (w.SpeechRecognition ||
+        w.webkitSpeechRecognition ||
+        w.mozSpeechRecognition ||
+        w.msSpeechRecognition ||
+        null);
+}
+/**
+ * Word-boundary match — avoids "home" firing on "homework".
+ * Splits both transcript and keyword on whitespace and checks for an
+ * exact word (or multi-word phrase) match.
+ */
+export function matchVoiceCommand(transcript, commands) {
+    const words = transcript.toLowerCase().trim().split(/\s+/);
+    if (!words.length)
+        return null;
+    for (const cmd of commands) {
+        for (const kw of cmd.keywords) {
+            const kwWords = kw.toLowerCase().trim().split(/\s+/);
+            // Sliding-window check for multi-word keywords
+            for (let i = 0; i <= words.length - kwWords.length; i++) {
+                if (kwWords.every((w, j) => words[i + j] === w))
+                    return cmd;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Returns the command whose keywords share the most words with the transcript.
+ * Used for "did you mean?" hints on no-match.
+ */
+export function closestVoiceCommand(transcript, commands) {
+    if (!commands.length)
+        return null;
+    const words = new Set(transcript.toLowerCase().trim().split(/\s+/));
+    let best = null;
+    let bestScore = 0;
+    for (const cmd of commands) {
+        for (const kw of cmd.keywords) {
+            const overlap = kw
+                .toLowerCase()
+                .split(/\s+/)
+                .filter((w) => words.has(w)).length;
+            if (overlap > bestScore) {
+                bestScore = overlap;
+                best = cmd;
+            }
+        }
+    }
+    return bestScore > 0 ? best : null;
+}
+/** Detects iOS Safari where continuous mode silently breaks. */
+function detectContinuousSupport() {
+    if (typeof window === 'undefined')
+        return false;
+    const ua = navigator.userAgent;
+    const isIOS = /iPad|iPhone|iPod/.test(ua) && !window.MSStream;
+    const isSafari = /^((?!chrome|android).)*safari/i.test(ua);
+    return !(isIOS && isSafari);
+}
+// ─── Hook ─────────────────────────────────────────────────────────────────────
+export function useVoice(options = {}) {
+    const { commands = [], language = 'en-US', continuous = false, interimResults = true, autoNavigate = true, historySize = 10, minConfidence = 0.4, idleTimeoutMs = 0, wakeWord, shortcut, navigate: navigateProp, onMatch, onNoMatch, onError, onStart, onEnd, onToast, } = options;
+    // ── Refs ────────────────────────────────────────────────────────────────────
+    const recognitionRef = useRef(null);
+    const audioContextRef = useRef(null);
+    const analyserRef = useRef(null);
+    const streamRef = useRef(null);
+    const animFrameRef = useRef(0);
+    const idleTimerRef = useRef(null);
+    const mountedRef = useRef(true);
+    const startingRef = useRef(false); // guard for concurrent start() calls
+    // Stable refs for values that must not be in effect deps
+    const commandsRef = useRef(commands);
+    const navigateRef = useRef(navigateProp);
+    const executeRef = useRef(null);
+    const callbacksRef = useRef({ onMatch, onNoMatch, onError, onStart, onEnd, onToast });
+    // Keep refs in sync every render (no extra re-renders, no stale closures)
+    useEffect(() => { commandsRef.current = commands; });
+    useEffect(() => { navigateRef.current = navigateProp; });
+    useEffect(() => {
+        callbacksRef.current = { onMatch, onNoMatch, onError, onStart, onEnd, onToast };
+    });
+    // ── State ───────────────────────────────────────────────────────────────────
+    const [status, setStatus] = useState('idle');
+    const [transcript, setTranscript] = useState('');
+    const [audioLevel, setAudioLevel] = useState(0);
+    const [history, setHistory] = useState([]);
+    const [lastMatch, setLastMatch] = useState(null);
+    const [pendingConfirm, setPendingConfirm] = useState(null);
+    const isSupported = useMemo(() => !!getSpeechRecognitionCtor(), []);
+    const isContinuousSupported = useMemo(() => detectContinuousSupport(), []);
+    // ── Idle timer ──────────────────────────────────────────────────────────────
+    const clearIdleTimer = useCallback(() => {
+        if (idleTimerRef.current !== null) {
+            clearTimeout(idleTimerRef.current);
+            idleTimerRef.current = null;
+        }
+    }, []);
+    const resetIdleTimer = useCallback(() => {
+        clearIdleTimer();
+        if (idleTimeoutMs > 0) {
+            idleTimerRef.current = setTimeout(() => {
+                var _a;
+                if (!mountedRef.current)
+                    return;
+                try {
+                    (_a = recognitionRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+                }
+                catch ( /* ignore */_b) { /* ignore */ }
+            }, idleTimeoutMs);
+        }
+    }, [idleTimeoutMs, clearIdleTimer]);
+    // ── Audio analysis ──────────────────────────────────────────────────────────
+    const stopAudioAnalysis = useCallback(() => {
+        var _a;
+        clearIdleTimer();
+        cancelAnimationFrame(animFrameRef.current);
+        if (mountedRef.current)
+            setAudioLevel(0);
+        (_a = streamRef.current) === null || _a === void 0 ? void 0 : _a.getTracks().forEach((t) => t.stop());
+        streamRef.current = null;
+        // Keep a local ref before nulling so the async close doesn't re-read a
+        // new context that was created after cleanup.
+        const ctx = audioContextRef.current;
+        audioContextRef.current = null;
+        analyserRef.current = null;
+        ctx === null || ctx === void 0 ? void 0 : ctx.close().catch(() => { });
+    }, [clearIdleTimer]);
+    const startAudioAnalysis = useCallback(async () => {
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            if (!mountedRef.current) {
+                stream.getTracks().forEach((t) => t.stop());
+                return false;
+            }
+            streamRef.current = stream;
+            const ctx = new AudioContext();
+            audioContextRef.current = ctx;
+            const analyser = ctx.createAnalyser();
+            analyser.fftSize = 256;
+            analyserRef.current = analyser;
+            ctx.createMediaStreamSource(stream).connect(analyser);
+            const data = new Uint8Array(analyser.frequencyBinCount);
+            const tick = () => {
+                if (!analyserRef.current || !mountedRef.current)
+                    return;
+                analyserRef.current.getByteFrequencyData(data);
+                let sum = 0;
+                for (let i = 0; i < data.length; i++)
+                    sum += data[i];
+                setAudioLevel(Math.min(100, (sum / data.length) * 2));
+                animFrameRef.current = requestAnimationFrame(tick);
+            };
+            tick();
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    }, []);
+    // ── Execute command ─────────────────────────────────────────────────────────
+    const executeCommand = useCallback((text) => {
+        var _a, _b, _c, _d;
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        const cb = callbacksRef.current;
+        // Wake-word gate
+        if (wakeWord) {
+            const ww = wakeWord.toLowerCase();
+            if (!trimmed.toLowerCase().includes(ww))
+                return;
+        }
+        const matched = matchVoiceCommand(trimmed, commandsRef.current);
+        const time = new Date().toLocaleTimeString();
+        setHistory((prev) => [
+            { text: trimmed, matched: !!matched, label: matched === null || matched === void 0 ? void 0 : matched.label, time },
+            ...prev.slice(0, Math.max(0, historySize - 1)),
+        ]);
+        if (matched) {
+            setLastMatch(matched);
+            (_a = cb.onToast) === null || _a === void 0 ? void 0 : _a.call(cb, 'success', `Matched: ${matched.label}`);
+            (_b = cb.onMatch) === null || _b === void 0 ? void 0 : _b.call(cb, matched, trimmed);
+            if (matched.requiresConfirmation) {
+                setPendingConfirm(matched);
+                setStatus('confirming');
+                return; // wait for a follow-up "yes" / "confirm"
+            }
+            // Fire the command
+            if (matched.action) {
+                matched.action();
+            }
+            else if (autoNavigate && matched.path && navigateRef.current) {
+                navigateRef.current(matched.path);
+            }
+        }
+        else {
+            const closest = closestVoiceCommand(trimmed, commandsRef.current);
+            (_c = cb.onToast) === null || _c === void 0 ? void 0 : _c.call(cb, 'warn', closest ? `Did you mean: ${closest.label}?` : 'Command not recognized');
+            (_d = cb.onNoMatch) === null || _d === void 0 ? void 0 : _d.call(cb, trimmed, closest);
+        }
+        if (mountedRef.current)
+            setStatus('idle');
+    }, [autoNavigate, historySize, wakeWord]);
+    // Keep a stable ref so the recognition effect can call it without being
+    // in its own dep array (fixes the stale-closure / rebuild-on-every-render bug).
+    useEffect(() => { executeRef.current = executeCommand; }, [executeCommand]);
+    // ── Confirmation handler ────────────────────────────────────────────────────
+    const resolveConfirm = useCallback((text) => {
+        var _a, _b, _c, _d;
+        if (!pendingConfirm)
+            return;
+        const yes = /\b(yes|confirm|ok|okay|sure|do it)\b/i.test(text);
+        if (yes) {
+            if (pendingConfirm.action) {
+                pendingConfirm.action();
+            }
+            else if (autoNavigate && pendingConfirm.path && navigateRef.current) {
+                navigateRef.current(pendingConfirm.path);
+            }
+            (_b = (_a = callbacksRef.current).onToast) === null || _b === void 0 ? void 0 : _b.call(_a, 'success', `Confirmed: ${pendingConfirm.label}`);
+        }
+        else {
+            (_d = (_c = callbacksRef.current).onToast) === null || _d === void 0 ? void 0 : _d.call(_c, 'warn', 'Cancelled');
+        }
+        setPendingConfirm(null);
+        setStatus('idle');
+    }, [pendingConfirm, autoNavigate]);
+    // ── SpeechRecognition setup ─────────────────────────────────────────────────
+    // executeCommand is intentionally NOT in this dep array.
+    // We call it via executeRef.current to avoid rebuilding recognition on every render.
+    useEffect(() => {
+        const Ctor = getSpeechRecognitionCtor();
+        if (!Ctor) {
+            setStatus('unsupported');
+            return;
+        }
+        const recognition = new Ctor();
+        recognition.continuous = continuous && isContinuousSupported;
+        recognition.interimResults = interimResults;
+        recognition.lang = language;
+        recognition.onstart = () => {
+            var _a, _b;
+            if (!mountedRef.current)
+                return;
+            setStatus('listening');
+            (_b = (_a = callbacksRef.current).onStart) === null || _b === void 0 ? void 0 : _b.call(_a);
+            resetIdleTimer();
+        };
+        recognition.onresult = (event) => {
+            var _a;
+            if (!mountedRef.current)
+                return;
+            let interim = '';
+            let finalText = '';
+            let highestConfidence = 0;
+            for (let i = event.resultIndex; i < event.results.length; i++) {
+                const result = event.results[i];
+                const txt = result[0].transcript;
+                // Chrome often returns confidence=0 even for correct final results;
+                // treat 0 (and missing) as "unknown" so we don't drop every redirect.
+                const conf = result[0].confidence || 1;
+                if (result.isFinal) {
+                    if (conf >= minConfidence)
+                        finalText += txt;
+                    highestConfidence = Math.max(highestConfidence, conf);
+                }
+                else {
+                    interim += txt;
+                }
+            }
+            setTranscript(finalText || interim);
+            if (finalText) {
+                setStatus('processing');
+                stopAudioAnalysis();
+                clearIdleTimer();
+                // Resolve a pending confirmation or run normal command matching
+                if (pendingConfirm) {
+                    resolveConfirm(finalText);
+                }
+                else {
+                    (_a = executeRef.current) === null || _a === void 0 ? void 0 : _a.call(executeRef, finalText);
+                }
+            }
+            else {
+                // Interim speech resets the idle timer
+                resetIdleTimer();
+            }
+        };
+        recognition.onerror = (event) => {
+            var _a, _b, _c, _d;
+            if (!mountedRef.current)
+                return;
+            // These are non-fatal — ignore silently
+            if (event.error === 'aborted' || event.error === 'no-speech')
+                return;
+            setStatus('error');
+            const msg = event.error === 'not-allowed'
+                ? 'Microphone permission denied'
+                : `Speech error: ${event.error}`;
+            (_b = (_a = callbacksRef.current).onToast) === null || _b === void 0 ? void 0 : _b.call(_a, 'error', msg);
+            (_d = (_c = callbacksRef.current).onError) === null || _d === void 0 ? void 0 : _d.call(_c, event.error);
+            stopAudioAnalysis();
+            // Auto-recover to idle after 2s so UI isn't stuck on error
+            setTimeout(() => {
+                if (mountedRef.current)
+                    setStatus('idle');
+            }, 2000);
+        };
+        recognition.onend = () => {
+            var _a, _b;
+            if (!mountedRef.current)
+                return;
+            // Only reset to idle if we weren't already in processing/error/confirming
+            setStatus((prev) => prev === 'listening' || prev === 'processing' ? 'idle' : prev);
+            stopAudioAnalysis();
+            (_b = (_a = callbacksRef.current).onEnd) === null || _b === void 0 ? void 0 : _b.call(_a);
+        };
+        recognitionRef.current = recognition;
+        return () => {
+            var _a;
+            try {
+                (_a = recognitionRef.current) === null || _a === void 0 ? void 0 : _a.abort();
+            }
+            catch ( /* ignore */_b) { /* ignore */ }
+            recognitionRef.current = null;
+            stopAudioAnalysis();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [continuous, interimResults, isContinuousSupported]);
+    // ↑ language intentionally omitted from deps — updated via separate effect below
+    // ↑ executeCommand intentionally omitted — called via executeRef to avoid rebuilds
+    // Update lang on the existing recognition instance without rebuilding it
+    useEffect(() => {
+        if (recognitionRef.current) {
+            recognitionRef.current.lang = language;
+        }
+    }, [language]);
+    // Keep pendingConfirm and resolveConfirm accessible inside the recognition
+    // onresult handler without adding them to the effect deps.
+    const pendingConfirmRef = useRef(pendingConfirm);
+    const resolveConfirmRef = useRef(resolveConfirm);
+    useEffect(() => { pendingConfirmRef.current = pendingConfirm; }, [pendingConfirm]);
+    useEffect(() => { resolveConfirmRef.current = resolveConfirm; }, [resolveConfirm]);
+    // ── Keyboard shortcut ───────────────────────────────────────────────────────
+    useEffect(() => {
+        if (!shortcut)
+            return;
+        const handler = (e) => {
+            var _a, _b;
+            // e.g. shortcut = "alt+v"
+            const parts = shortcut.toLowerCase().split('+');
+            const key = parts[parts.length - 1];
+            const needsAlt = parts.includes('alt');
+            const needsCtrl = parts.includes('ctrl');
+            const needsShift = parts.includes('shift');
+            const needsMeta = parts.includes('meta');
+            if (e.key.toLowerCase() === key &&
+                e.altKey === needsAlt &&
+                e.ctrlKey === needsCtrl &&
+                e.shiftKey === needsShift &&
+                e.metaKey === needsMeta) {
+                e.preventDefault();
+                // Call toggle via refs to avoid stale closure
+                if (status === 'listening') {
+                    try {
+                        (_a = recognitionRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+                    }
+                    catch ( /* ignore */_c) { /* ignore */ }
+                    stopAudioAnalysis();
+                    setStatus('idle');
+                }
+                else {
+                    (_b = startRef.current) === null || _b === void 0 ? void 0 : _b.call(startRef);
+                }
+            }
+        };
+        window.addEventListener('keydown', handler);
+        return () => window.removeEventListener('keydown', handler);
+    }, [shortcut, status, stopAudioAnalysis]);
+    // ── Public actions ──────────────────────────────────────────────────────────
+    const start = useCallback(async () => {
+        var _a, _b, _c, _d;
+        if (!recognitionRef.current)
+            return;
+        if (status === 'listening' || startingRef.current)
+            return;
+        startingRef.current = true;
+        setTranscript('');
+        const micOk = await startAudioAnalysis();
+        startingRef.current = false;
+        if (!mountedRef.current)
+            return;
+        if (!micOk) {
+            (_b = (_a = callbacksRef.current).onToast) === null || _b === void 0 ? void 0 : _b.call(_a, 'error', 'Microphone access denied');
+            (_d = (_c = callbacksRef.current).onError) === null || _d === void 0 ? void 0 : _d.call(_c, 'not-allowed');
+            return;
+        }
+        try {
+            recognitionRef.current.start();
+        }
+        catch ( /* already started */_e) { /* already started */ }
+    }, [status, startAudioAnalysis]);
+    // Keep a ref so the shortcut handler can call start() without being stale
+    const startRef = useRef(start);
+    useEffect(() => { startRef.current = start; }, [start]);
+    const stop = useCallback(() => {
+        var _a;
+        try {
+            (_a = recognitionRef.current) === null || _a === void 0 ? void 0 : _a.stop();
+        }
+        catch ( /* ignore */_b) { /* ignore */ }
+        stopAudioAnalysis();
+        if (mountedRef.current)
+            setStatus('idle');
+    }, [stopAudioAnalysis]);
+    const toggle = useCallback(async () => {
+        if (status === 'listening')
+            stop();
+        else
+            await start();
+    }, [status, start, stop]);
+    const reset = useCallback(() => {
+        setTranscript('');
+        setHistory([]);
+        setLastMatch(null);
+        setPendingConfirm(null);
+    }, []);
+    // ── Mount / unmount guard ───────────────────────────────────────────────────
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            clearIdleTimer();
+        };
+    }, [clearIdleTimer]);
+    // ── Result ──────────────────────────────────────────────────────────────────
+    return {
+        status,
+        transcript,
+        audioLevel,
+        history,
+        lastMatch,
+        pendingConfirm,
+        isSupported,
+        isContinuousSupported,
+        isListening: status === 'listening',
+        isProcessing: status === 'processing',
+        start,
+        stop,
+        toggle,
+        reset,
+        executeCommand,
+    };
+}