@djangocfg/ui-tools 2.1.381 → 2.1.383

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';

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

@@ -0,0 +1,54 @@
+'use client';
+
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+
+export interface SpeechPrefs {
+  /**
+   * BCP-47 tag the user explicitly picked (via `<LanguagePicker>` or
+   * programmatically). `null` means "no override" — `useResolvedLanguage`
+   * then falls through to the app i18n locale / `navigator.language`.
+   * Storing the picker default as `null` is what lets a host's i18n
+   * locale take effect when the user never touched the picker.
+   */
+  language: string | null;
+  deviceId: string | null;
+  engineId: string | null;
+  earcons: boolean;
+}
+
+const DEFAULTS: SpeechPrefs = {
+  language: null,
+  deviceId: null,
+  engineId: null,
+  earcons: false,
+};
+
+interface PrefsStore extends SpeechPrefs {
+  setLanguage: (v: string | null) => void;
+  setDeviceId: (v: string | null) => void;
+  setEngineId: (v: string | null) => void;
+  setEarcons: (v: boolean) => void;
+  reset: () => void;
+}
+
+export const useSpeechPrefs = create<PrefsStore>()(
+  persist(
+    (set) => ({
+      ...DEFAULTS,
+      setLanguage: (language) => set({ language }),
+      setDeviceId: (deviceId) => set({ deviceId }),
+      setEngineId: (engineId) => set({ engineId }),
+      setEarcons: (earcons) => set({ earcons }),
+      reset: () => set({ ...DEFAULTS }),
+    }),
+    {
+      name: 'djangocfg-stt:prefs',
+      storage: createJSONStorage(() =>
+        typeof window === 'undefined'
+          ? (undefined as unknown as Storage)
+          : window.localStorage,
+      ),
+    },
+  ),
+);

package/src/tools/SpeechRecognition/types.ts

@@ -0,0 +1,133 @@
+/**
+ * Public types for the SpeechRecognition tool.
+ *
+ * Design: a small `RecognitionEngine` interface lets consumers plug in
+ * any STT backend (browser Web Speech, Deepgram, Whisper, custom WS).
+ * The hooks/UI never depend on a specific engine.
+ */
+
+export type RecognitionStatus =
+  | 'idle'
+  | 'starting'
+  | 'listening'
+  | 'stopping'
+  | 'error';
+
+export type EngineState =
+  | 'idle'
+  | 'connecting'
+  | 'listening'
+  | 'closing'
+  | 'closed'
+  | 'error';
+
+export type RecognitionErrorCode =
+  | 'unsupported'
+  | 'permission-denied'
+  | 'no-microphone'
+  | 'network'
+  | 'aborted'
+  | 'no-speech'
+  | 'language'
+  | 'engine'
+  | 'unknown';
+
+export interface RecognitionError {
+  code: RecognitionErrorCode;
+  message: string;
+  cause?: unknown;
+}
+
+export interface Segment {
+  id: string;
+  text: string;
+  isFinal: boolean;
+  /** Engine-provided confidence 0..1 if available. */
+  confidence?: number;
+  /** ms since session start. */
+  startedAt: number;
+  endedAt?: number;
+  /** Pass-through metadata from custom engines (diarization, lang, …). */
+  metadata?: Record<string, unknown>;
+}
+
+export interface Transcript {
+  /** Latest interim text (not yet final). Empty string when none. */
+  interim: string;
+  /** Concatenated final text (all segments joined with " "). */
+  final: string;
+  /** Full segment list including the trailing interim segment if any. */
+  segments: Segment[];
+}
+
+// ── engine contract ────────────────────────────────────────────────────────
+
+export interface EngineStartOptions {
+  language: string;
+  /** Whether the engine should emit partial/interim results. */
+  interim: boolean;
+  deviceId?: string;
+  signal?: AbortSignal;
+}
+
+export type EngineEventMap = {
+  partial: (text: string, segmentId: string) => void;
+  final: (text: string, segmentId: string, confidence?: number) => void;
+  error: (err: RecognitionError) => void;
+  state: (state: EngineState) => void;
+};
+
+export type Unsub = () => void;
+
+export interface RecognitionEngine {
+  readonly id: string;
+  readonly isSupported: boolean;
+  start(opts: EngineStartOptions): Promise<void>;
+  stop(): Promise<void>;
+  abort(): void;
+  on<K extends keyof EngineEventMap>(event: K, cb: EngineEventMap[K]): Unsub;
+  /**
+   * Optional — engines that capture mic audio themselves (HTTP / WS)
+   * may expose the active `MediaStream` so consumers can wire up a
+   * VU meter or waveform without owning a second `getUserMedia` call.
+   */
+  getStream?(): MediaStream | null;
+}
+
+// ── hook config ────────────────────────────────────────────────────────────
+
+export interface AutoStopOptions {
+  /** Stop after this many ms of silence (RMS below threshold). */
+  silenceMs?: number;
+  /** Hard cap on session length. */
+  maxMs?: number;
+  /** RMS threshold below which we count "silence". 0..1. Default 0.02. */
+  silenceThreshold?: number;
+}
+
+export interface UseSpeechRecognitionConfig {
+  engine?: RecognitionEngine;
+  language?: string;
+  interim?: boolean;
+  deviceId?: string;
+  autoStop?: AutoStopOptions;
+  onFinal?: (text: string, segment: Segment) => void;
+  onPartial?: (text: string, segment: Segment) => void;
+  onError?: (err: RecognitionError) => void;
+  onStart?: () => void;
+  onStop?: () => void;
+}
+
+export interface UseSpeechRecognitionReturn {
+  status: RecognitionStatus;
+  isSupported: boolean;
+  transcript: Transcript;
+  error: RecognitionError | null;
+  /** RMS level 0..1 for VU-meters. */
+  level: number;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  abort(): void;
+  toggle(): Promise<void>;
+  reset(): void;
+}