@djangocfg/ui-tools 2.1.381 → 2.1.382

package/src/tools/SpeechRecognition/hooks/useMicLevel.ts

@@ -0,0 +1,52 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * RMS level meter driven by an `AnalyserNode`. Attach a `MediaStream`
+ * (the one returned from `startMicCapture`) and read `level` (0..1) for
+ * VU meters / mic-pulse animations. Returns 0 when no stream is bound.
+ */
+export function useMicLevel(stream: MediaStream | null): number {
+  const [level, setLevel] = useState(0);
+  const raf = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (!stream) {
+      setLevel(0);
+      return undefined;
+    }
+    const AC =
+      (window as unknown as { AudioContext?: typeof AudioContext }).AudioContext ??
+      (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+    if (!AC) return undefined;
+    const ctx = new AC();
+    const source = ctx.createMediaStreamSource(stream);
+    const analyser = ctx.createAnalyser();
+    analyser.fftSize = 1024;
+    analyser.smoothingTimeConstant = 0.7;
+    source.connect(analyser);
+    const buf = new Float32Array(analyser.fftSize);
+
+    const tick = (): void => {
+      analyser.getFloatTimeDomainData(buf);
+      let sum = 0;
+      for (let i = 0; i < buf.length; i += 1) sum += buf[i] * buf[i];
+      const rms = Math.sqrt(sum / buf.length);
+      // soft compression so loud peaks don't dominate the meter
+      setLevel(Math.min(1, rms * 2.5));
+      raf.current = requestAnimationFrame(tick);
+    };
+    tick();
+
+    return () => {
+      if (raf.current != null) cancelAnimationFrame(raf.current);
+      raf.current = null;
+      source.disconnect();
+      analyser.disconnect();
+      void ctx.close();
+    };
+  }, [stream]);
+
+  return level;
+}

package/src/tools/SpeechRecognition/hooks/usePushToTalk.ts

@@ -0,0 +1,85 @@
+'use client';
+
+import { useEffect } from 'react';
+
+import type { UseSpeechRecognitionReturn } from '../types';
+
+export interface UsePushToTalkOptions {
+  /** Key to hold. Combine modifiers with `+`, e.g. `'alt'`, `'mod+alt'`. */
+  key: string;
+  /** Disable the binding without unmounting. */
+  enabled?: boolean;
+}
+
+const MOD_KEYS = new Set(['shift', 'ctrl', 'alt', 'meta', 'mod']);
+
+function parseChord(chord: string): { mods: Set<string>; main: string | null } {
+  const parts = chord
+    .toLowerCase()
+    .split('+')
+    .map((s) => s.trim());
+  const mods = new Set<string>();
+  let main: string | null = null;
+  for (const part of parts) {
+    if (MOD_KEYS.has(part)) {
+      mods.add(part === 'mod' ? 'meta' : part);
+    } else {
+      main = part;
+    }
+  }
+  return { mods, main };
+}
+
+function matches(e: KeyboardEvent, mods: Set<string>, main: string | null): boolean {
+  if (mods.has('shift') !== e.shiftKey) return false;
+  if (mods.has('ctrl') !== e.ctrlKey) return false;
+  if (mods.has('alt') !== e.altKey) return false;
+  // 'mod' → meta on mac / ctrl elsewhere; we already normalised to 'meta'.
+  if (mods.has('meta') !== (e.metaKey || (!e.metaKey && false))) return false;
+  if (main && e.key.toLowerCase() !== main) return false;
+  return true;
+}
+
+/**
+ * Hold-to-talk wiring. Press → `start()`, release → `stop()`. Ignores
+ * repeats and skips keydown inside `<input>` / `<textarea>` unless a
+ * modifier is in the chord.
+ */
+export function usePushToTalk(
+  recognition: Pick<UseSpeechRecognitionReturn, 'start' | 'stop' | 'status'>,
+  opts: UsePushToTalkOptions,
+): void {
+  const { key, enabled = true } = opts;
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return undefined;
+    const { mods, main } = parseChord(key);
+
+    const onDown = (e: KeyboardEvent): void => {
+      if (e.repeat) return;
+      if (!main && mods.size === 0) return;
+      const target = e.target as HTMLElement | null;
+      const inField =
+        target?.tagName === 'INPUT' ||
+        target?.tagName === 'TEXTAREA' ||
+        target?.isContentEditable;
+      if (inField && mods.size === 0) return;
+      if (!matches(e, mods, main)) return;
+      if (recognition.status === 'listening' || recognition.status === 'starting') return;
+      e.preventDefault();
+      void recognition.start();
+    };
+    const onUp = (e: KeyboardEvent): void => {
+      if (!matches(e, mods, main) && main && e.key.toLowerCase() !== main) return;
+      if (recognition.status !== 'listening' && recognition.status !== 'starting') return;
+      void recognition.stop();
+    };
+
+    window.addEventListener('keydown', onDown);
+    window.addEventListener('keyup', onUp);
+    return () => {
+      window.removeEventListener('keydown', onDown);
+      window.removeEventListener('keyup', onUp);
+    };
+  }, [enabled, key, recognition]);
+}

package/src/tools/SpeechRecognition/hooks/useResolvedLanguage.ts

@@ -0,0 +1,28 @@
+'use client';
+
+import { useLocaleOptional } from '@djangocfg/i18n';
+
+import { resolveSpeechLanguage } from '../core/language';
+import { useSpeechPrefs } from '../store/prefsStore';
+
+/**
+ * Resolves the BCP-47 language tag a speech session should use.
+ *
+ * Priority: explicit prop → user-picked `useSpeechPrefs.language` →
+ * app i18n locale (when an `<I18nProvider>` is mounted) →
+ * `navigator.language` → `en-US`.
+ *
+ * Uses `useLocaleOptional` (not `useLocale`) so that an unmounted
+ * provider doesn't silently inject `'en'`. Without that, the i18n
+ * default would shadow the user's real browser language — a Russian
+ * speaker would always get `en-US` recognition.
+ */
+export function useResolvedLanguage(explicit?: string): string {
+  const prefs = useSpeechPrefs();
+  const locale = useLocaleOptional();
+  return resolveSpeechLanguage({
+    explicit,
+    prefs: prefs.language,
+    i18n: locale,
+  });
+}

package/src/tools/SpeechRecognition/hooks/useSpeechLanguageInfo.ts

@@ -0,0 +1,108 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import {
+  countryFromTag,
+  findSpeechLanguage,
+} from '../core/languages-catalog';
+import { useSpeechPrefs } from '../store/prefsStore';
+import { useResolvedLanguage } from './useResolvedLanguage';
+
+export interface SpeechLanguageInfo {
+  /**
+   * BCP-47 tag that `useSpeechRecognition` will actually pass to the
+   * engine right now. Always non-null (falls through `prefs → i18n →
+   * navigator → 'en-US'`).
+   */
+  tag: string;
+  /**
+   * ISO-639 primary subtag of `tag` (`ru`, `en`, `cmn`). Useful as a
+   * map key when the host wires its own per-language behaviour
+   * (avatars, copy variants, etc.).
+   */
+  iso: string;
+  /**
+   * ISO-3166 alpha-2 country code extracted from `tag` (`RU`, `US`,
+   * `CN`). `null` when the tag has no region subtag — rare for our
+   * catalogue (every entry ships at least one regional dialect) but
+   * possible for custom-engine tags supplied by hosts.
+   */
+  country: string | null;
+  /**
+   * Native-script language name (`'Русский'`, `'中文'`). `null` for
+   * tags outside our catalogue.
+   */
+  name: string | null;
+  /**
+   * Lowercase English name (`'russian'`, `'chinese'`). `null` for
+   * tags outside our catalogue. Handy for analytics or English-only
+   * UI surfaces.
+   */
+  englishName: string | null;
+  /**
+   * Region label for the current dialect (`'Russia'`, `'United
+   * Kingdom'`, `'香港'`). `null` for unknown tags.
+   */
+  region: string | null;
+  /**
+   * `true` iff the user explicitly picked a language via
+   * `<ChatHeaderLanguageButton>` / `useSpeechPrefs.setLanguage(...)`.
+   * `false` means the resolved tag came from a lower-priority source
+   * (i18n locale, `navigator.language`, default).
+   *
+   * Use this when you want to distinguish "user told us to use ru-RU"
+   * from "we guessed ru-RU from browser headers". Analytics often
+   * cares about that distinction.
+   */
+  hasUserChoice: boolean;
+}
+
+/**
+ * One-shot read of "what speech language is active right now and why".
+ *
+ * Pulls together `useResolvedLanguage`, `useSpeechPrefs.language`, and
+ * the static catalogue (`findSpeechLanguage` / `countryFromTag`) into
+ * a single memoised object so consumers don't have to compose them by
+ * hand for every header badge / analytics call / persisted-state push.
+ *
+ * Reactive: re-renders when the user picks a different language in
+ * the chat header, when i18n locale changes, or when the underlying
+ * `navigator.language` reading flips (mount-time only).
+ *
+ * @example Render a status badge somewhere in the app shell
+ * ```tsx
+ * const { tag, name, country } = useSpeechLanguageInfo();
+ * return (
+ *   <Badge>
+ *     <Flag countryCode={country} />
+ *     {name ?? tag}
+ *   </Badge>
+ * );
+ * ```
+ *
+ * @example Sync the user's STT pick to a backend setting
+ * ```tsx
+ * const { tag, hasUserChoice } = useSpeechLanguageInfo();
+ * useEffect(() => {
+ *   if (!hasUserChoice) return;             // skip auto-resolved values
+ *   void api.user.update({ speechLanguage: tag });
+ * }, [tag, hasUserChoice]);
+ * ```
+ */
+export function useSpeechLanguageInfo(): SpeechLanguageInfo {
+  const prefs = useSpeechPrefs();
+  const tag = useResolvedLanguage();
+  return useMemo<SpeechLanguageInfo>(() => {
+    const found = findSpeechLanguage(tag);
+    return {
+      tag,
+      iso: found?.language.iso ?? tag.split('-')[0].toLowerCase(),
+      country: countryFromTag(tag),
+      name: found?.language.name ?? null,
+      englishName: found?.language.englishName ?? null,
+      region: found?.dialect.region ?? null,
+      hasUserChoice: prefs.language !== null,
+    };
+  }, [tag, prefs.language]);
+}

package/src/tools/SpeechRecognition/hooks/useSpeechRecognition.ts

@@ -0,0 +1,188 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';
+
+import {
+  EMPTY_TRANSCRIPT,
+  INITIAL_STATE,
+  buildTranscript,
+  reducer,
+  sttLogger,
+} from '../core';
+import { createWebSpeechEngine } from '../core/engine/webspeech';
+import { useSpeechPrefs } from '../store/prefsStore';
+import type {
+  RecognitionEngine,
+  Segment,
+  UseSpeechRecognitionConfig,
+  UseSpeechRecognitionReturn,
+} from '../types';
+import { useMicLevel } from './useMicLevel';
+import { useResolvedLanguage } from './useResolvedLanguage';
+
+/**
+ * Main entry point. With no config it uses the browser Web Speech API
+ * and the persisted language from `useSpeechPrefs`. Pass a custom
+ * `engine` to route through Deepgram / Whisper / custom WebSocket.
+ */
+export function useSpeechRecognition(
+  config: UseSpeechRecognitionConfig = {},
+): UseSpeechRecognitionReturn {
+  const prefs = useSpeechPrefs();
+  const language = useResolvedLanguage(config.language);
+  const engine = useMemo<RecognitionEngine>(
+    () => config.engine ?? createWebSpeechEngine(),
+    [config.engine],
+  );
+
+  const [state, dispatch] = useReducer(reducer, INITIAL_STATE);
+  const [stream, setStream] = useState<MediaStream | null>(null);
+  const level = useMicLevel(stream);
+
+  // Latest-callback refs so engine subscriptions never tear down on
+  // every render — same trick the Chat reducer uses.
+  const cbRef = useRef(config);
+  cbRef.current = config;
+
+  // Engine subscription lifecycle.
+  useEffect(() => {
+    const offs = [
+      engine.on('partial', (text, segmentId) => {
+        dispatch({ type: 'PARTIAL', text, segmentId });
+        const seg: Segment = {
+          id: segmentId,
+          text,
+          isFinal: false,
+          startedAt: Date.now(),
+        };
+        cbRef.current.onPartial?.(text, seg);
+      }),
+      engine.on('final', (text, segmentId, confidence) => {
+        dispatch({ type: 'FINAL', text, segmentId, confidence });
+        const seg: Segment = {
+          id: segmentId,
+          text,
+          isFinal: true,
+          confidence,
+          startedAt: Date.now(),
+          endedAt: Date.now(),
+        };
+        cbRef.current.onFinal?.(text, seg);
+      }),
+      engine.on('error', (err) => {
+        dispatch({ type: 'ERROR', error: err });
+        cbRef.current.onError?.(err);
+      }),
+      engine.on('state', (s) => {
+        if (s === 'listening') {
+          dispatch({ type: 'STARTED' });
+          cbRef.current.onStart?.();
+          setStream(engine.getStream?.() ?? null);
+        } else if (s === 'closed') {
+          dispatch({ type: 'STOPPED' });
+          cbRef.current.onStop?.();
+          setStream(null);
+        }
+      }),
+    ];
+    return () => {
+      offs.forEach((off) => off());
+    };
+  }, [engine]);
+
+  // AutoStop driven by silence + maxMs caps.
+  const silenceTimer = useRef<number | null>(null);
+  const maxTimer = useRef<number | null>(null);
+  useEffect(() => {
+    if (state.status !== 'listening') return undefined;
+    const { silenceMs, maxMs, silenceThreshold = 0.02 } = config.autoStop ?? {};
+    if (maxMs) {
+      maxTimer.current = window.setTimeout(() => {
+        sttLogger.debug('[autoStop] max duration hit');
+        void engine.stop();
+      }, maxMs);
+    }
+    if (silenceMs) {
+      const checkInterval = window.setInterval(() => {
+        if (level < silenceThreshold) {
+          if (silenceTimer.current == null) {
+            silenceTimer.current = window.setTimeout(() => {
+              sttLogger.debug('[autoStop] silence detected');
+              void engine.stop();
+            }, silenceMs);
+          }
+        } else if (silenceTimer.current != null) {
+          clearTimeout(silenceTimer.current);
+          silenceTimer.current = null;
+        }
+      }, 200);
+      return () => {
+        clearInterval(checkInterval);
+        if (silenceTimer.current != null) clearTimeout(silenceTimer.current);
+        silenceTimer.current = null;
+        if (maxTimer.current != null) clearTimeout(maxTimer.current);
+        maxTimer.current = null;
+      };
+    }
+    return () => {
+      if (maxTimer.current != null) clearTimeout(maxTimer.current);
+      maxTimer.current = null;
+    };
+  }, [state.status, config.autoStop, level, engine]);
+
+  const start = useCallback(async () => {
+    if (state.status === 'listening' || state.status === 'starting') return;
+    dispatch({ type: 'START' });
+    try {
+      await engine.start({
+        language,
+        interim: config.interim ?? true,
+        deviceId: config.deviceId ?? prefs.deviceId ?? undefined,
+      });
+    } catch (cause) {
+      // engine already emitted 'error'; reducer caught it via subscription
+      sttLogger.debug('[start] engine threw', cause);
+    }
+  }, [engine, language, config.interim, config.deviceId, prefs.deviceId, state.status]);
+
+  const stop = useCallback(async () => {
+    if (state.status === 'idle' || state.status === 'stopping') return;
+    dispatch({ type: 'STOP' });
+    await engine.stop();
+  }, [engine, state.status]);
+
+  const abort = useCallback(() => {
+    engine.abort();
+    dispatch({ type: 'ABORT' });
+  }, [engine]);
+
+  const toggle = useCallback(async () => {
+    if (state.status === 'listening' || state.status === 'starting') {
+      await stop();
+    } else {
+      await start();
+    }
+  }, [state.status, start, stop]);
+
+  const reset = useCallback(() => {
+    dispatch({ type: 'RESET' });
+  }, []);
+
+  const transcript = useMemo(
+    () => (state.segments.length === 0 ? EMPTY_TRANSCRIPT : buildTranscript(state.segments)),
+    [state.segments],
+  );
+
+  return {
+    status: state.status,
+    isSupported: engine.isSupported,
+    transcript,
+    error: state.error,
+    level,
+    start,
+    stop,
+    abort,
+    toggle,
+    reset,
+  };
+}

package/src/tools/SpeechRecognition/hooks/useVoiceSupport.ts

@@ -0,0 +1,78 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import { useBrowserDetect, useDeviceDetect } from '@djangocfg/ui-core/hooks';
+
+import type { RecognitionEngine } from '../types';
+import { createWebSpeechEngine } from '../core/engine/webspeech';
+
+export type VoiceUnsupportedReason =
+  | 'no-engine'
+  | 'no-mediadevices'
+  | 'in-app-browser'
+  | 'unknown';
+
+export interface VoiceSupport {
+  /** Should the host render the voice button at all? */
+  supported: boolean;
+  /** Why is it off? `null` when supported. */
+  reason: VoiceUnsupportedReason | null;
+  /** Engine id that would be used if rendered (for badges / telemetry). */
+  engineId: string | null;
+  /** True on a mobile UA — useful for hiding on phones if the host wants. */
+  isMobile: boolean;
+  /** True inside Facebook / Instagram / TikTok / etc. in-app browsers. */
+  isInApp: boolean;
+}
+
+/**
+ * Decides whether the `<VoiceComposerSlot>` should render the mic
+ * button. Three gates:
+ *
+ *  1. A `RecognitionEngine` reports `isSupported === true`. With no
+ *     custom engine passed we probe `createWebSpeechEngine()` —
+ *     Chrome / Edge / Safari pass, Firefox does not.
+ *  2. `navigator.mediaDevices.getUserMedia` exists. Required even when
+ *     using Web Speech (browser still asks the user for mic access).
+ *  3. The host browser is not a known in-app WebView (Instagram,
+ *     Facebook, TikTok, …) — mic permission flows are broken in most
+ *     of them. The host can override this gate by passing a custom
+ *     engine that already handles the case.
+ */
+export function useVoiceSupport(engine?: RecognitionEngine): VoiceSupport {
+  const browser = useBrowserDetect();
+  const device = useDeviceDetect();
+
+  return useMemo<VoiceSupport>(() => {
+    const isMobile = device.selectors.isMobile;
+    const isInApp = browser.isInAppBrowser;
+
+    const hasMediaDevices =
+      typeof navigator !== 'undefined' && !!navigator.mediaDevices?.getUserMedia;
+    if (!hasMediaDevices) {
+      return { supported: false, reason: 'no-mediadevices', engineId: null, isMobile, isInApp };
+    }
+
+    // If the host didn't pass a custom engine we can only fall back to
+    // the browser Web Speech API — bail when it's not available
+    // (Firefox / some WebViews).
+    const probe = engine ?? createWebSpeechEngine();
+    if (!probe.isSupported) {
+      // In-app browsers are the most common reason a probe fails on
+      // mobile; surface a friendlier code so the UI can hide silently.
+      if (isInApp) {
+        return { supported: false, reason: 'in-app-browser', engineId: null, isMobile, isInApp };
+      }
+      return { supported: false, reason: 'no-engine', engineId: null, isMobile, isInApp };
+    }
+
+    return {
+      supported: true,
+      reason: null,
+      engineId: probe.id,
+      isMobile,
+      isInApp,
+    };
+  }, [engine, browser.isInAppBrowser, device.selectors.isMobile]);
+}

package/src/tools/SpeechRecognition/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @djangocfg/ui-tools/speech-recognition
+ *
+ * Decomposed Speech-to-Text tool. Default backend is the browser Web
+ * Speech API; custom engines can be plugged in for cloud or self-hosted
+ * STT (Deepgram, Whisper, AssemblyAI, custom WebSocket).
+ */
+
+'use client';
+
+export type {
+  AutoStopOptions,
+  EngineEventMap,
+  EngineStartOptions,
+  EngineState,
+  RecognitionEngine,
+  RecognitionError,
+  RecognitionErrorCode,
+  RecognitionStatus,
+  Segment,
+  Transcript,
+  Unsub,
+  UseSpeechRecognitionConfig,
+  UseSpeechRecognitionReturn,
+} from './types';
+
+export {
+  EMPTY_TRANSCRIPT,
+  buildTranscript,
+  joinFinal,
+  newSegmentId,
+  normaliseFinal,
+} from './core';
+
+export { createEngineBus } from './core/engine';
+export { createWebSpeechEngine } from './core/engine/webspeech';
+export type { WebSpeechEngineOptions } from './core/engine/webspeech';
+export { createHttpEngine } from './core/engine/http';
+export type {
+  HttpEngineOptions,
+  HttpEngineParseResult,
+} from './core/engine/http';
+export { createWebSocketEngine } from './core/engine/websocket';
+export type {
+  WebSocketEngineOptions,
+  WsParsedEvent,
+} from './core/engine/websocket';
+export { createExternalEngine } from './core/engine/external';
+export type {
+  ExternalEngineHandle,
+  ExternalEngineOptions,
+} from './core/engine/external';
+export { pickMime, startMicCapture } from './core/engine/mediarecorder';
+export type {
+  MicCaptureHandle,
+  MicCaptureOptions,
+} from './core/engine/mediarecorder';
+
+export * from './hooks';
+export * from './components';
+export * from './widgets';
+export * from './context';
+export { LazyDictationField } from './lazy';
+export { useSpeechPrefs } from './store';
+export type { SpeechPrefs } from './store';
+export { DEFAULT_VOICE_SOUNDS } from './core/audio/defaults';
+export type { VoiceSoundEvent } from './core/audio/defaults';
+export {
+  DEFAULT_ISO_TO_BCP47,
+  resolveSpeechLanguage,
+  toBCP47,
+} from './core/language';
+export {
+  WEB_SPEECH_LANGUAGES,
+  WEB_SPEECH_TAGS,
+  findSpeechLanguage,
+  countryFromTag,
+} from './core/languages-catalog';
+export type {
+  SpeechLanguage,
+  SpeechLanguageDialect,
+} from './core/languages-catalog';

package/src/tools/SpeechRecognition/lazy.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import { createLazyComponent } from '../../components';
+import type { DictationFieldProps } from './widgets/DictationField';
+
+export const LazyDictationField = createLazyComponent<DictationFieldProps>(
+  () =>
+    import('./widgets/DictationField').then((mod) => ({
+      default: mod.DictationField,
+    })),
+  {
+    displayName: 'LazyDictationField',
+    fallback: (
+      <div className="rounded-lg border border-border/60 bg-card px-3 py-2 text-xs text-muted-foreground">
+        Loading dictation…
+      </div>
+    ),
+  },
+);

package/src/tools/SpeechRecognition/store/index.ts

@@ -0,0 +1,2 @@
+export { useSpeechPrefs } from './prefsStore';
+export type { SpeechPrefs } from './prefsStore';