@djangocfg/ui-tools 2.1.381 → 2.1.383

package/src/tools/SpeechRecognition/widgets/DictationField.tsx

@@ -0,0 +1,105 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { DictationButton } from '../components/DictationButton';
+import { ErrorBanner } from '../components/ErrorBanner';
+import { MicMeter } from '../components/MicMeter';
+import { PushToTalkHint } from '../components/PushToTalkHint';
+import { useDictation } from '../hooks/useDictation';
+import { usePushToTalk } from '../hooks/usePushToTalk';
+import type { RecognitionEngine } from '../types';
+
+export interface DictationFieldProps {
+  value: string;
+  onChange: (next: string) => void;
+  /** Custom engine. Defaults to Web Speech via `useSpeechRecognition`. */
+  engine?: RecognitionEngine;
+  /** Override the language stored in `useSpeechPrefs`. */
+  language?: string;
+  /** Push-to-talk chord (e.g. `'alt'`, `'mod+alt'`). Disabled when omitted. */
+  pushToTalk?: { key: string; enabled?: boolean };
+  placeholder?: string;
+  rows?: number;
+  disabled?: boolean;
+  /** Show the interim transcript as a ghost overlay below the textarea. */
+  showInterim?: boolean;
+  /** Show a small RMS meter inside the toolbar. */
+  showMeter?: boolean;
+  className?: string;
+  textareaClassName?: string;
+}
+
+/**
+ * Opinionated textarea + dictation button assembly. Final segments are
+ * appended to the controlled `value` automatically. Press-and-hold
+ * shortcut is optional; the mic button itself works as a toggle.
+ */
+export function DictationField({
+  value,
+  onChange,
+  engine,
+  language,
+  pushToTalk,
+  placeholder = 'Type or press the mic to dictate…',
+  rows = 3,
+  disabled,
+  showInterim = true,
+  showMeter = true,
+  className,
+  textareaClassName,
+}: DictationFieldProps): React.ReactElement {
+  const rec = useDictation({
+    value,
+    onChange,
+    engine,
+    language,
+  });
+
+  usePushToTalk(rec, {
+    key: pushToTalk?.key ?? 'alt',
+    enabled: !!pushToTalk && pushToTalk.enabled !== false,
+  });
+
+  return (
+    <div className={cn('flex flex-col gap-2', className)}>
+      <div className="relative">
+        <textarea
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+          placeholder={placeholder}
+          rows={rows}
+          disabled={disabled}
+          className={cn(
+            'w-full resize-y rounded-md border border-input bg-background px-3 py-2 text-sm',
+            'placeholder:text-muted-foreground',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+            'disabled:cursor-not-allowed disabled:opacity-50',
+            textareaClassName,
+          )}
+        />
+        {showInterim && rec.transcript.interim && (
+          <div className="pointer-events-none mt-1 text-xs italic text-muted-foreground">
+            … {rec.transcript.interim}
+          </div>
+        )}
+      </div>
+
+      <div className="flex items-center gap-2">
+        <DictationButton
+          status={rec.status}
+          isSupported={rec.isSupported}
+          onClick={() => void rec.toggleDictation()}
+          size="sm"
+          disabled={disabled}
+        />
+        {showMeter && <MicMeter level={rec.level} bars={10} height={20} />}
+        {pushToTalk && <PushToTalkHint chord={pushToTalk.key} className="ml-auto" />}
+      </div>
+
+      <ErrorBanner error={rec.error} />
+    </div>
+  );
+}

package/src/tools/SpeechRecognition/widgets/VoiceComposerSlot.tsx

@@ -0,0 +1,305 @@
+'use client';
+
+import type * as React from 'react';
+import { useCallback, useEffect, useRef } from 'react';
+import { Loader2, Mic } from 'lucide-react';
+
+import { useCountdownFromSeconds, useNotificationSounds } from '@djangocfg/ui-core/hooks';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useChatContextOptional } from '../../Chat/context';
+import { useSpeechRecognition } from '../hooks/useSpeechRecognition';
+import { useVoiceSupport } from '../hooks/useVoiceSupport';
+import { normaliseFinal } from '../core/transcript';
+import { DEFAULT_VOICE_SOUNDS, type VoiceSoundEvent } from '../core/audio/defaults';
+import type { RecognitionEngine } from '../types';
+
+export interface VoiceComposerSlotProps {
+  /**
+   * Controlled composer value. Optional — when omitted, the slot
+   * reads/writes through the Chat context's registered `ComposerHandle`
+   * (built-in `<Composer>` and any host that calls
+   * `useRegisterComposer({ getValue, setValue })`). Pass explicitly
+   * only for standalone usage outside a `<ChatProvider>`.
+   */
+  value?: string;
+  /** Composer setter — see `value`. Optional when used inside a chat. */
+  onChange?: (next: string) => void;
+  /** Optional custom engine (Deepgram / HTTP / WS). Defaults to Web Speech. */
+  engine?: RecognitionEngine;
+  /** BCP-47 language override. Otherwise `useSpeechPrefs` decides. */
+  language?: string;
+  /** Hide the button if the host wants to disable voice on phones. */
+  hideOnMobile?: boolean;
+  /** Max session length in seconds before we auto-stop. Default 90. */
+  maxSeconds?: number;
+  /** Auto-stop after this many ms of silence. Default 2500. */
+  silenceMs?: number;
+  /** Button size. @default 'md' */
+  size?: 'sm' | 'md' | 'lg';
+  /** Override classes on the button. */
+  className?: string;
+  /** Fires when dictation finishes — useful for parent-side analytics. */
+  onFinish?: (transcript: string) => void;
+  /**
+   * Start/stop earcons. `true` (default) plays the bundled sounds,
+   * `false` disables them, or pass `{ start, stop }` data-URLs to
+   * override. Master mute lives in `useNotificationSounds` localStorage
+   * — users can silence everything via their own UI.
+   */
+  sounds?: boolean | { start?: string; stop?: string };
+}
+
+const SIZE_CLS: Record<NonNullable<VoiceComposerSlotProps['size']>, string> = {
+  sm: 'h-8 w-8 [&_svg]:h-4 [&_svg]:w-4',
+  md: 'h-9 w-9 [&_svg]:h-4 [&_svg]:w-4',
+  lg: 'h-12 w-12 [&_svg]:h-5 [&_svg]:w-5',
+};
+
+const STORAGE_KEY = 'djangocfg-stt:voice-sounds';
+
+/**
+ * Drop-in slot for the `<Composer toolbarEnd>` (or `toolbarStart`) prop.
+ *
+ * Renders a microphone button — but only when the browser + device
+ * combination can actually do speech recognition. Firefox, in-app
+ * WebViews, and missing `getUserMedia` all collapse the component to
+ * `null`, so the chat composer never shows a broken affordance.
+ *
+ * While listening, interim+final transcript is pushed live into the
+ * composer's `value` — like dictation on iOS / Android keyboards. The
+ * user's already-typed prefix is preserved (anchored on press). Cancel
+ * with the same button or by pressing Escape (handled upstream).
+ *
+ * Soft start/stop earcons play by default. Pass `sounds={false}` to
+ * mute, or `sounds={{ start, stop }}` to override the audio URLs.
+ */
+export function VoiceComposerSlot({
+  value,
+  onChange,
+  engine,
+  language,
+  hideOnMobile = false,
+  maxSeconds = 90,
+  silenceMs = 2500,
+  size = 'md',
+  className,
+  onFinish,
+  sounds = true,
+}: VoiceComposerSlotProps): React.ReactElement | null {
+  const support = useVoiceSupport(engine);
+
+  // Read the composer handle from chat context — works transparently
+  // for the built-in `<Composer>` (registers itself) and for TipTap
+  // hosts that call `useRegisterComposer({ getValue, setValue, focus,
+  // moveCursorToEnd })`. Falls back to a no-op when mounted outside of
+  // a chat.
+  const chatCtx = useChatContextOptional();
+  const composerHandleRef = useRef(chatCtx?.composer ?? null);
+  composerHandleRef.current = chatCtx?.composer ?? null;
+
+  // Resolve value/onChange: prop wins; otherwise pull from the
+  // registered composer handle. The slot can therefore be dropped into
+  // `composerToolbarEnd` of `ChatRoot` with zero props.
+  const resolvedGetValue = useCallback((): string => {
+    if (value !== undefined) return value;
+    return composerHandleRef.current?.getValue?.() ?? '';
+  }, [value]);
+  const resolvedSetValue = useCallback(
+    (next: string): void => {
+      if (onChange) {
+        onChange(next);
+        return;
+      }
+      composerHandleRef.current?.setValue?.(next);
+    },
+    [onChange],
+  );
+
+  // Anchor: what was already in the textarea when the user pressed the
+  // mic. Live transcript is appended to this baseline so manual typing
+  // before pressing the button is never overwritten.
+  const anchorRef = useRef<string>('');
+  const onFinishRef = useRef(onFinish);
+  onFinishRef.current = onFinish;
+
+  // Push caret to the end on the next frame — after React commits the
+  // new `value` into the DOM. Without the rAF the selection lands on
+  // the old text length, leaving the cursor mid-string while the live
+  // transcript visually keeps growing.
+  const pinCaretToEnd = useCallback(() => {
+    const handle = composerHandleRef.current;
+    if (!handle?.moveCursorToEnd) return;
+    requestAnimationFrame(() => {
+      composerHandleRef.current?.moveCursorToEnd?.();
+    });
+  }, []);
+
+  const [countdown, startCountdown] = useCountdownFromSeconds();
+
+  // Earcon bus. `sounds === false` → pass empty map so the bus stays
+  // silent. Object overrides merge with bundled defaults.
+  const soundMap =
+    sounds === false
+      ? undefined
+      : sounds === true
+        ? DEFAULT_VOICE_SOUNDS
+        : { ...DEFAULT_VOICE_SOUNDS, ...sounds };
+  const audio = useNotificationSounds<VoiceSoundEvent>({
+    storageKey: STORAGE_KEY,
+    sounds: soundMap,
+    muted: sounds === false,
+    // Both earcons stay deliberately quiet — they're self-initiated
+    // micro-confirmations, not notifications. Anything louder feels
+    // attention-grabbing when the user pressed the button themselves.
+    eventVolumes: { start: 0.35, stop: 0.5 },
+  });
+
+  const handlePartial = useCallback(
+    (text: string) => {
+      const next = anchorRef.current
+        ? `${anchorRef.current} ${text}`
+        : text;
+      resolvedSetValue(next);
+      pinCaretToEnd();
+    },
+    [pinCaretToEnd, resolvedSetValue],
+  );
+
+  const handleFinal = useCallback(
+    (text: string) => {
+      const clean = normaliseFinal(text);
+      if (!clean) return;
+      const merged = anchorRef.current ? `${anchorRef.current} ${clean}` : clean;
+      anchorRef.current = merged;
+      resolvedSetValue(merged);
+      pinCaretToEnd();
+    },
+    [pinCaretToEnd, resolvedSetValue],
+  );
+
+  const rec = useSpeechRecognition({
+    engine,
+    language,
+    interim: true,
+    autoStop: { silenceMs, maxMs: maxSeconds * 1000 },
+    onPartial: (text) => handlePartial(text),
+    onFinal: (text) => handleFinal(text),
+    onStart: () => {
+      void audio.play('start');
+      // Focus the composer + park caret at the end so the live
+      // transcript visibly grows where the user expects it to.
+      composerHandleRef.current?.focus();
+      pinCaretToEnd();
+    },
+    onStop: () => {
+      void audio.play('stop');
+      // Re-focus on stop too — auto-stop on silence happens without
+      // a user gesture, and we want the user to keep typing seamlessly.
+      composerHandleRef.current?.focus();
+      pinCaretToEnd();
+      onFinishRef.current?.(resolvedGetValue());
+    },
+  });
+
+  // Drive the countdown alongside the listening state.
+  useEffect(() => {
+    if (rec.status === 'listening') {
+      startCountdown(maxSeconds);
+    }
+  }, [rec.status, maxSeconds, startCountdown]);
+
+  // Hotkeys while listening:
+  //   Esc   — cancel dictation (and stop event propagation so the
+  //           outer chat doesn't *also* close — same convention as
+  //           ChatGPT / Slack voice mode).
+  //   Enter — finish dictation, KEEP what we already pushed into the
+  //           composer, do NOT submit the chat (avoids accidental
+  //           sends while the user is still talking). We block the
+  //           Enter that would otherwise reach the composer textarea
+  //           by listening in the capture phase.
+  const listening = rec.status === 'listening' || rec.status === 'starting';
+  useEffect(() => {
+    if (!listening) return undefined;
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        e.stopPropagation();
+        rec.abort();
+        return;
+      }
+      if (e.key === 'Enter' && !e.shiftKey) {
+        // Block the chat composer's "Enter to send" while we're
+        // dictating — finish recording instead.
+        e.preventDefault();
+        e.stopPropagation();
+        void rec.stop();
+      }
+    };
+    // `capture: true` so we run before the composer textarea's
+    // keydown handler (which would otherwise close the chat on Esc
+    // or submit the form on Enter).
+    window.addEventListener('keydown', onKey, true);
+    return () => {
+      window.removeEventListener('keydown', onKey, true);
+    };
+  }, [listening, rec]);
+
+  const toggle = useCallback(() => {
+    if (rec.status === 'listening' || rec.status === 'starting') {
+      void rec.stop();
+      return;
+    }
+    anchorRef.current = resolvedGetValue().trim();
+    void rec.start();
+  }, [rec, resolvedGetValue]);
+
+  if (!support.supported) return null;
+  if (hideOnMobile && support.isMobile) return null;
+
+  const stopping = rec.status === 'stopping';
+
+  // Tooltip: countdown + hotkey hint while listening, plain copy
+  // otherwise. Avoids the absolutely-positioned label that clipped
+  // against the composer bottom edge in the previous design.
+  const tooltip = listening
+    ? `Listening — ${countdown.label || `${maxSeconds}s left`} · Enter to finish · Esc to cancel`
+    : 'Dictate message';
+
+  return (
+    <span className="inline-flex items-center gap-1.5 !h-auto">
+      {listening && countdown.label ? (
+        <span
+          aria-hidden
+          className="rounded-full bg-destructive/10 px-1.5 py-0.5 font-mono text-[10px] leading-none text-destructive tabular-nums"
+        >
+          {countdown.label}
+        </span>
+      ) : null}
+      <button
+        type="button"
+        onClick={toggle}
+        aria-pressed={listening}
+        aria-label={listening ? 'Stop dictation' : 'Dictate message'}
+        title={tooltip}
+        className={cn(
+          'relative inline-flex items-center justify-center rounded-full transition-colors',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+          SIZE_CLS[size],
+          listening
+            ? 'bg-destructive text-destructive-foreground hover:bg-destructive/90'
+            : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+          className,
+        )}
+      >
+        {listening && (
+          <span
+            aria-hidden
+            className="absolute inset-0 rounded-full bg-destructive/30 animate-ping"
+          />
+        )}
+        {stopping ? <Loader2 className="animate-spin" /> : <Mic />}
+      </button>
+    </span>
+  );
+}

package/src/tools/SpeechRecognition/widgets/VoiceMessageRecorder.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+import type * as React from 'react';
+import { useEffect } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { DictationButton } from '../components/DictationButton';
+import { ErrorBanner } from '../components/ErrorBanner';
+import { MicMeter } from '../components/MicMeter';
+import { TranscriptView } from '../components/TranscriptView';
+import { useSpeechRecognition } from '../hooks/useSpeechRecognition';
+import type { RecognitionEngine, Segment } from '../types';
+
+export interface VoiceMessageRecorderProps {
+  /** Called once when the user stops, with the full final transcript. */
+  onSubmit: (text: string, segments: Segment[]) => void;
+  onCancel?: () => void;
+  engine?: RecognitionEngine;
+  language?: string;
+  /** Auto-stop after this many ms of silence. Default 1500. */
+  silenceMs?: number;
+  /** Hard cap on session length. Default 60000 ms. */
+  maxMs?: number;
+  className?: string;
+}
+
+/**
+ * Press-to-record assembly for "voice memo" UIs. Records until the user
+ * presses stop or silence-detection fires, then emits the full final
+ * transcript via `onSubmit`. Pair with a chat composer or any send-button
+ * flow.
+ */
+export function VoiceMessageRecorder({
+  onSubmit,
+  onCancel,
+  engine,
+  language,
+  silenceMs = 1500,
+  maxMs = 60000,
+  className,
+}: VoiceMessageRecorderProps): React.ReactElement {
+  const rec = useSpeechRecognition({
+    engine,
+    language,
+    autoStop: { silenceMs, maxMs },
+  });
+
+  // Auto-submit on transition out of listening — fires once the engine
+  // finalises and closes. Reducer resets after.
+  useEffect(() => {
+    if (rec.status !== 'idle') return;
+    if (!rec.transcript.final) return;
+    onSubmit(rec.transcript.final, rec.transcript.segments);
+    rec.reset();
+    // run only when status flips to idle
+  }, [rec.status, rec.transcript.final, rec.transcript.segments, onSubmit, rec.reset]);
+
+  return (
+    <div
+      className={cn(
+        'flex w-full flex-col gap-3 rounded-lg border border-border bg-card p-3',
+        className,
+      )}
+    >
+      <div className="flex items-center gap-3">
+        <DictationButton
+          status={rec.status}
+          isSupported={rec.isSupported}
+          onClick={() => void rec.toggle()}
+          size="lg"
+        />
+        <MicMeter level={rec.level} bars={14} height={28} className="flex-1" />
+        {onCancel && (
+          <button
+            type="button"
+            onClick={onCancel}
+            className="rounded-md border border-border px-2 py-1 text-xs text-muted-foreground hover:bg-muted"
+          >
+            Cancel
+          </button>
+        )}
+      </div>
+      <TranscriptView transcript={rec.transcript} />
+      <ErrorBanner error={rec.error} />
+    </div>
+  );
+}

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

@@ -0,0 +1,6 @@
+export { DictationField } from './DictationField';
+export type { DictationFieldProps } from './DictationField';
+export { VoiceMessageRecorder } from './VoiceMessageRecorder';
+export type { VoiceMessageRecorderProps } from './VoiceMessageRecorder';
+export { VoiceComposerSlot } from './VoiceComposerSlot';
+export type { VoiceComposerSlotProps } from './VoiceComposerSlot';

package/dist/ChatRoot-EJC5Y2YM.cjs

@@ -1,14 +0,0 @@
-'use strict';
-
-var chunkSI5RD2GD_cjs = require('./chunk-SI5RD2GD.cjs');
-require('./chunk-XACCHZH2.cjs');
-require('./chunk-OLISEQHS.cjs');
-
-
-
-Object.defineProperty(exports, "ChatRoot", {
-  enumerable: true,
-  get: function () { return chunkSI5RD2GD_cjs.ChatRoot; }
-});
-//# sourceMappingURL=ChatRoot-EJC5Y2YM.cjs.map
-//# sourceMappingURL=ChatRoot-EJC5Y2YM.cjs.map

package/dist/ChatRoot-QOSKJPM6.mjs

@@ -1,5 +0,0 @@
-export { ChatRoot } from './chunk-QLMKCSR6.mjs';
-import './chunk-NWUT327A.mjs';
-import './chunk-N2XQF2OL.mjs';
-//# sourceMappingURL=ChatRoot-QOSKJPM6.mjs.map
-//# sourceMappingURL=ChatRoot-QOSKJPM6.mjs.map