@djangocfg/ui-tools 2.1.381 → 2.1.382

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/stories/01-basic.story.tsx

@@ -0,0 +1,32 @@
+import { useMemo } from 'react';
+
+import { defineStory } from '@djangocfg/playground';
+
+import { DictationButton } from '../components/DictationButton';
+import { ErrorBanner } from '../components/ErrorBanner';
+import { TranscriptView } from '../components/TranscriptView';
+import { useSpeechRecognition } from '../hooks/useSpeechRecognition';
+import { Frame, createMockEngine } from './shared';
+
+export default defineStory({
+  title: 'Tools/SpeechRecognition/Basic',
+  component: DictationButton,
+  description:
+    'Headless `useSpeechRecognition` with a mock engine — deterministic transcript, no mic prompt.',
+});
+
+export const MockTranscript = () => {
+  const engine = useMemo(() => createMockEngine(), []);
+  const rec = useSpeechRecognition({ engine });
+  return (
+    <Frame>
+      <div className="flex items-start gap-3">
+        <DictationButton status={rec.status} onClick={() => void rec.toggle()} />
+        <div className="flex-1">
+          <TranscriptView transcript={rec.transcript} />
+          <ErrorBanner error={rec.error} className="mt-2" />
+        </div>
+      </div>
+    </Frame>
+  );
+};

package/src/tools/SpeechRecognition/stories/02-dictation-field.story.tsx

@@ -0,0 +1,32 @@
+import { useMemo, useState } from 'react';
+
+import { defineStory } from '@djangocfg/playground';
+
+import { DictationField } from '../widgets/DictationField';
+import { Frame, createMockEngine } from './shared';
+
+export default defineStory({
+  title: 'Tools/SpeechRecognition/DictationField',
+  component: DictationField,
+  description:
+    'Opinionated textarea + mic button assembly. Final segments are appended to the controlled `value`. `BrowserNative` uses the real Web Speech API (mic prompt on first press); `MockedDemo` types a scripted phrase without touching the microphone.',
+});
+
+export const BrowserNative = () => {
+  const [value, setValue] = useState('');
+  return (
+    <Frame>
+      <DictationField value={value} onChange={setValue} />
+    </Frame>
+  );
+};
+
+export const MockedDemo = () => {
+  const engine = useMemo(() => createMockEngine(), []);
+  const [value, setValue] = useState('');
+  return (
+    <Frame>
+      <DictationField value={value} onChange={setValue} engine={engine} />
+    </Frame>
+  );
+};

package/src/tools/SpeechRecognition/stories/03-push-to-talk.story.tsx

@@ -0,0 +1,27 @@
+import { useMemo, useState } from 'react';
+
+import { defineStory } from '@djangocfg/playground';
+
+import { DictationField } from '../widgets/DictationField';
+import { Frame, createMockEngine } from './shared';
+
+export default defineStory({
+  title: 'Tools/SpeechRecognition/PushToTalk',
+  component: DictationField,
+  description: 'Hold ⌥ (alt) to dictate. Release to stop and commit.',
+});
+
+export const HoldAlt = () => {
+  const engine = useMemo(() => createMockEngine({ partialIntervalMs: 80 }), []);
+  const [value, setValue] = useState('');
+  return (
+    <Frame>
+      <DictationField
+        value={value}
+        onChange={setValue}
+        engine={engine}
+        pushToTalk={{ key: 'alt' }}
+      />
+    </Frame>
+  );
+};

package/src/tools/SpeechRecognition/stories/04-mic-meter.story.tsx

@@ -0,0 +1,35 @@
+import { useEffect, useState } from 'react';
+
+import { defineStory } from '@djangocfg/playground';
+
+import { MicMeter } from '../components/MicMeter';
+import { Frame } from './shared';
+
+export default defineStory({
+  title: 'Tools/SpeechRecognition/MicMeter',
+  component: MicMeter,
+  description:
+    'RMS level meter — animates from a synthetic sine here so you can see the bars without granting mic access.',
+});
+
+export const Animated = () => {
+  const [level, setLevel] = useState(0);
+  useEffect(() => {
+    let t = 0;
+    const id = window.setInterval(() => {
+      t += 0.1;
+      setLevel((Math.sin(t) + 1) / 2);
+    }, 80);
+    return () => window.clearInterval(id);
+  }, []);
+  return (
+    <Frame w={320}>
+      <div className="flex items-center gap-3">
+        <MicMeter level={level} bars={16} height={32} />
+        <span className="font-mono text-xs text-muted-foreground">
+          level: {level.toFixed(2)}
+        </span>
+      </div>
+    </Frame>
+  );
+};

package/src/tools/SpeechRecognition/stories/05-custom-engine-http.story.tsx

@@ -0,0 +1,40 @@
+import { defineStory } from '@djangocfg/playground';
+
+import { EngineBadge } from '../components/EngineBadge';
+import { Frame } from './shared';
+
+export default defineStory({
+  title: 'Tools/SpeechRecognition/CustomEngine: HTTP',
+  component: EngineBadge,
+  description:
+    'Plug `createHttpEngine` into `useSpeechRecognition` to forward audio to any REST endpoint (Whisper, custom Django, …). This story is documentation only — it would need a real backend to play sound.',
+});
+
+export const Snippet = () => (
+  <Frame>
+    <div className="space-y-2 text-xs">
+      <div className="flex items-center gap-2">
+        <EngineBadge engineId="http" />
+        <span className="text-muted-foreground">— consumer-owned backend</span>
+      </div>
+      <pre className="overflow-auto rounded-md border border-border bg-muted/40 p-3 font-mono text-[11px] leading-snug">
+        {`import {
+  createHttpEngine,
+  useSpeechRecognition,
+} from '@djangocfg/ui-tools/speech-recognition';
+
+const engine = createHttpEngine({
+  url: '/api/stt/transcribe',
+  headers: async () => ({ Authorization: \`Bearer \${token}\` }),
+  chunkMs: 750,
+  parse: async (resp) => {
+    const { text, final } = await resp.json();
+    return { text, isFinal: final };
+  },
+});
+
+const rec = useSpeechRecognition({ engine });`}
+      </pre>
+    </div>
+  </Frame>
+);

package/src/tools/SpeechRecognition/stories/06-custom-engine-ws.story.tsx

@@ -0,0 +1,48 @@
+import { defineStory } from '@djangocfg/playground';
+
+import { EngineBadge } from '../components/EngineBadge';
+import { Frame } from './shared';
+
+export default defineStory({
+  title: 'Tools/SpeechRecognition/CustomEngine: WebSocket',
+  component: EngineBadge,
+  description:
+    '`createWebSocketEngine` pushes audio frames over a persistent socket — Deepgram / AssemblyAI / custom realtime gateways. Documentation snippet, no live backend.',
+});
+
+export const Snippet = () => (
+  <Frame>
+    <div className="space-y-2 text-xs">
+      <div className="flex items-center gap-2">
+        <EngineBadge engineId="websocket" />
+        <span className="text-muted-foreground">— low-latency streaming</span>
+      </div>
+      <pre className="overflow-auto rounded-md border border-border bg-muted/40 p-3 font-mono text-[11px] leading-snug">
+        {`import {
+  createWebSocketEngine,
+  useSpeechRecognition,
+} from '@djangocfg/ui-tools/speech-recognition';
+
+const engine = createWebSocketEngine({
+  url: async () => {
+    const { token } = await fetch('/api/stt/ticket').then((r) => r.json());
+    return \`wss://stt.example.com/listen?token=\${token}\`;
+  },
+  chunkMs: 250,
+  parseMessage: (data) => {
+    if (typeof data !== 'string') return { kind: 'ignore' };
+    const msg = JSON.parse(data);
+    if (msg.type === 'Results') {
+      return msg.is_final
+        ? { kind: 'final', text: msg.channel.alternatives[0].transcript }
+        : { kind: 'partial', text: msg.channel.alternatives[0].transcript };
+    }
+    return { kind: 'ignore' };
+  },
+});
+
+const rec = useSpeechRecognition({ engine });`}
+      </pre>
+    </div>
+  </Frame>
+);

package/src/tools/SpeechRecognition/stories/07-language-device.story.tsx

@@ -0,0 +1,57 @@
+import { useMemo, useState } from 'react';
+
+import { defineStory } from '@djangocfg/playground';
+
+import { DevicePicker } from '../components/DevicePicker';
+import { EngineBadge } from '../components/EngineBadge';
+import { LanguagePicker } from '../components/LanguagePicker';
+import { TranscriptView } from '../components/TranscriptView';
+import { useMicDevices } from '../hooks/useMicDevices';
+import { useSpeechPrefs } from '../store/prefsStore';
+import { useSpeechRecognition } from '../hooks/useSpeechRecognition';
+import { Frame, createMockEngine } from './shared';
+
+export default defineStory({
+  title: 'Tools/SpeechRecognition/Language & Device',
+  component: LanguagePicker,
+  description:
+    'Persisted language / mic preferences via `useSpeechPrefs` + `useMicDevices`. Mock engine here so the toolbar renders without a real mic.',
+});
+
+export const LanguageAndDevice = () => {
+  const engine = useMemo(() => createMockEngine(), []);
+  const rec = useSpeechRecognition({ engine });
+  const prefs = useSpeechPrefs();
+  const { devices } = useMicDevices();
+  const [language, setLanguage] = useState(prefs.language ?? 'en-US');
+
+  return (
+    <Frame>
+      <div className="space-y-3">
+        <div className="flex items-center gap-2">
+          <LanguagePicker
+            value={language}
+            onChange={(v) => {
+              setLanguage(v);
+              prefs.setLanguage(v);
+            }}
+          />
+          <DevicePicker
+            devices={devices}
+            value={prefs.deviceId}
+            onChange={prefs.setDeviceId}
+          />
+          <EngineBadge engineId={engine.id} className="ml-auto" />
+        </div>
+        <button
+          type="button"
+          onClick={() => void rec.toggle()}
+          className="rounded-md border border-border px-2 py-1 text-xs hover:bg-muted"
+        >
+          {rec.status === 'listening' ? 'Stop' : 'Start'}
+        </button>
+        <TranscriptView transcript={rec.transcript} />
+      </div>
+    </Frame>
+  );
+};

package/src/tools/SpeechRecognition/stories/08-errors-permissions.story.tsx

@@ -0,0 +1,25 @@
+import { defineStory } from '@djangocfg/playground';
+
+import { ErrorBanner } from '../components/ErrorBanner';
+import { Frame } from './shared';
+
+export default defineStory({
+  title: 'Tools/SpeechRecognition/Errors',
+  component: ErrorBanner,
+  description:
+    'All error codes the engine can surface — render `<ErrorBanner>` to translate them into friendly copy.',
+});
+
+export const AllCodes = () => (
+  <Frame>
+    <div className="space-y-2">
+      <ErrorBanner error={{ code: 'unsupported', message: '' }} />
+      <ErrorBanner error={{ code: 'permission-denied', message: '' }} />
+      <ErrorBanner error={{ code: 'no-microphone', message: '' }} />
+      <ErrorBanner error={{ code: 'network', message: '' }} />
+      <ErrorBanner error={{ code: 'no-speech', message: '' }} />
+      <ErrorBanner error={{ code: 'language', message: '' }} />
+      <ErrorBanner error={{ code: 'engine', message: 'Engine X said no.' }} />
+    </div>
+  </Frame>
+);

package/src/tools/SpeechRecognition/stories/09-chat-voice.story.tsx

@@ -0,0 +1,90 @@
+import { useMemo } from 'react';
+
+import { defineStory } from '@djangocfg/playground';
+
+import { Composer } from '../../Chat/components/Composer';
+import { EmptyState } from '../../Chat/components/EmptyState';
+import { MessageList } from '../../Chat/components/MessageList';
+import { ChatProvider, useChatContext } from '../../Chat/context';
+import { useChatComposer } from '../../Chat/hooks/useChatComposer';
+import { ChatHeader } from '../../Chat/launcher/ChatHeader';
+import { ChatHeaderLanguageButton } from '../../Chat/launcher/ChatHeaderLanguageButton';
+import { SEED_BASIC, makeBasicTransport } from '../../Chat/stories/shared';
+import { Frame as ChatFrame } from '../../Chat/stories/shared/Frame';
+import { VoiceComposerSlot } from '../widgets/VoiceComposerSlot';
+import type { RecognitionEngine } from '../types';
+import { createMockEngine } from './shared';
+
+export default defineStory({
+  title: 'Tools/Chat/Voice composer',
+  component: VoiceComposerSlot,
+  description:
+    'Live dictation slot wired into the Chat composer. `InsideComposer` uses the real browser Web Speech API + a kebab settings menu in the header for picking the speech-recognition language (persists in `useSpeechPrefs`). `MockedDemo` uses a deterministic mock engine so screenshots / CI never prompt for microphone access. The slot auto-hides on Firefox / in-app browsers / missing getUserMedia.',
+});
+
+function VoiceChat({ engine }: { engine?: RecognitionEngine }) {
+  const chat = useChatContext();
+  const composer = useChatComposer({
+    onSubmit: (content, attachments) => chat.sendMessage(content, attachments),
+    disabled: chat.isStreaming,
+  });
+
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      <ChatHeader
+        title="Assistant"
+        actions={<ChatHeaderLanguageButton />}
+      />
+      <MessageList
+        renderEmpty={() => (
+          <EmptyState greeting="Open the settings menu (⋯) to pick the speech language, then press the mic." />
+        )}
+      />
+      <Composer
+        composer={composer}
+        placeholder="Type or press the mic…"
+        toolbarEnd={
+          <VoiceComposerSlot
+            value={composer.value}
+            onChange={composer.setValue}
+            engine={engine}
+          />
+        }
+      />
+    </div>
+  );
+}
+
+/**
+ * Real browser Web Speech API + kebab settings menu with the language
+ * picker. The choice persists in `useSpeechPrefs` (localStorage), so it
+ * survives reloads. Defaults are resolved in order: prop → prefs → i18n
+ * → `navigator.language` → `en-US`.
+ */
+export const InsideComposer = () => {
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+  return (
+    <ChatFrame>
+      <ChatProvider transport={transport}>
+        <VoiceChat />
+      </ChatProvider>
+    </ChatFrame>
+  );
+};
+
+/**
+ * Deterministic mock engine — types a scripted phrase into the composer
+ * without touching the microphone. Useful for screenshots, CI, and
+ * environments where granting mic permission is not desired.
+ */
+export const MockedDemo = () => {
+  const transport = useMemo(() => makeBasicTransport(SEED_BASIC), []);
+  const engine = useMemo(() => createMockEngine({ partialIntervalMs: 90 }), []);
+  return (
+    <ChatFrame>
+      <ChatProvider transport={transport}>
+        <VoiceChat engine={engine} />
+      </ChatProvider>
+    </ChatFrame>
+  );
+};

package/src/tools/SpeechRecognition/stories/shared.tsx

@@ -0,0 +1,123 @@
+/**
+ * Deterministic mock engine — emits scripted partials/finals on a timer
+ * so stories render the same thing every load and don't beg the browser
+ * for microphone permission.
+ */
+
+import { createEngineBus } from '../core/engine';
+import { newSegmentId } from '../core/ids';
+import type {
+  EngineStartOptions,
+  RecognitionEngine,
+  Unsub,
+} from '../types';
+
+export interface MockEngineOptions {
+  /** Final phrases the mock will emit, one after another. */
+  phrases?: string[];
+  /** ms between partial chunks. Default 120. */
+  partialIntervalMs?: number;
+  /** ms between final segments. Default 1500. */
+  finalIntervalMs?: number;
+  /** Override id (default `'mock'`). */
+  id?: string;
+}
+
+const DEFAULT_PHRASES = [
+  'Hello and welcome to the dictation demo.',
+  'This text is being typed by the mock engine.',
+  'Try the buttons on the right to control the session.',
+];
+
+export function createMockEngine(
+  opts: MockEngineOptions = {},
+): RecognitionEngine {
+  const bus = createEngineBus();
+  const phrases = opts.phrases ?? DEFAULT_PHRASES;
+  const partialMs = opts.partialIntervalMs ?? 120;
+  const finalMs = opts.finalIntervalMs ?? 1500;
+
+  let timers: ReturnType<typeof setTimeout>[] = [];
+  let running = false;
+
+  function clearTimers(): void {
+    timers.forEach(clearTimeout);
+    timers = [];
+  }
+
+  function run(): void {
+    let phraseIdx = 0;
+    let charIdx = 0;
+    let segmentId = newSegmentId();
+    let baseTime = 0;
+
+    const tick = (): void => {
+      if (!running) return;
+      const phrase = phrases[phraseIdx % phrases.length];
+      charIdx = Math.min(charIdx + 2, phrase.length);
+      bus.emit('partial', phrase.slice(0, charIdx), segmentId);
+      if (charIdx >= phrase.length) {
+        const tFinal = setTimeout(() => {
+          if (!running) return;
+          bus.emit('final', phrase, segmentId);
+          phraseIdx += 1;
+          charIdx = 0;
+          segmentId = newSegmentId();
+          baseTime += finalMs;
+          const tNext = setTimeout(tick, partialMs);
+          timers.push(tNext);
+        }, finalMs - partialMs);
+        timers.push(tFinal);
+        return;
+      }
+      const tNext = setTimeout(tick, partialMs);
+      timers.push(tNext);
+    };
+    tick();
+  }
+
+  return {
+    id: opts.id ?? 'mock',
+    isSupported: true,
+    on(event, cb): Unsub {
+      return bus.on(event, cb);
+    },
+    async start(_opts: EngineStartOptions): Promise<void> {
+      if (running) return;
+      running = true;
+      bus.emit('state', 'listening');
+      run();
+    },
+    async stop(): Promise<void> {
+      running = false;
+      clearTimers();
+      bus.emit('state', 'closed');
+    },
+    abort(): void {
+      running = false;
+      clearTimers();
+      bus.emit('state', 'closed');
+    },
+  };
+}
+
+import type { ReactNode } from 'react';
+
+export function Frame({
+  children,
+  w = 480,
+  h = 'auto' as number | string,
+}: {
+  children: ReactNode;
+  w?: number | string;
+  h?: number | string;
+}) {
+  return (
+    <div
+      className="rounded-lg border border-border bg-background p-4 shadow-sm"
+      style={{ width: w, height: h }}
+    >
+      {children}
+    </div>
+  );
+}