@djangocfg/ui-tools 2.1.381 → 2.1.383

package/src/tools/SpeechRecognition/components/DictationButton.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import type * as React from 'react';
+
+import { Loader2, Mic, MicOff } from 'lucide-react';
+import type { CSSProperties, ReactNode } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { RecognitionStatus } from '../types';
+
+export interface DictationButtonProps {
+  status: RecognitionStatus;
+  onClick: () => void;
+  isSupported?: boolean;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+  style?: CSSProperties;
+  ariaLabel?: string;
+  /** Override icon for the idle state. */
+  idleIcon?: ReactNode;
+  /** Override icon for the listening state. */
+  listeningIcon?: ReactNode;
+  /** Disable without unmounting. */
+  disabled?: boolean;
+}
+
+const SIZE_CLS: Record<NonNullable<DictationButtonProps['size']>, string> = {
+  sm: 'h-8 w-8 [&_svg]:h-4 [&_svg]:w-4',
+  md: 'h-10 w-10 [&_svg]:h-5 [&_svg]:w-5',
+  lg: 'h-12 w-12 [&_svg]:h-6 [&_svg]:w-6',
+};
+
+/**
+ * Round microphone button. Cycles icon by status; shows a soft pulse
+ * ring when listening. ARIA-correct so screen readers announce
+ * "recording" vs "start dictation".
+ */
+export function DictationButton({
+  status,
+  onClick,
+  isSupported = true,
+  size = 'md',
+  className,
+  style,
+  ariaLabel,
+  idleIcon,
+  listeningIcon,
+  disabled,
+}: DictationButtonProps): React.ReactElement {
+  const listening = status === 'listening' || status === 'starting';
+  const stopping = status === 'stopping';
+  const off = !isSupported;
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled || off}
+      aria-pressed={listening}
+      aria-label={
+        ariaLabel ?? (listening ? 'Stop dictation' : off ? 'Dictation not supported' : 'Start dictation')
+      }
+      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',
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        SIZE_CLS[size],
+        listening
+          ? 'bg-destructive text-destructive-foreground hover:bg-destructive/90'
+          : 'bg-primary text-primary-foreground hover:bg-primary/90',
+        className,
+      )}
+      style={style}
+    >
+      {listening && (
+        <span
+          aria-hidden
+          className="absolute inset-0 rounded-full bg-destructive/40 animate-ping"
+        />
+      )}
+      {stopping ? (
+        <Loader2 className="animate-spin" />
+      ) : off ? (
+        listeningIcon ?? <MicOff />
+      ) : listening ? (
+        listeningIcon ?? <Mic />
+      ) : (
+        idleIcon ?? <Mic />
+      )}
+    </button>
+  );
+}

package/src/tools/SpeechRecognition/components/EngineBadge.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface EngineBadgeProps {
+  engineId: string;
+  className?: string;
+}
+
+const LABELS: Record<string, string> = {
+  webspeech: 'Web Speech',
+  http: 'Custom HTTP',
+  websocket: 'WebSocket',
+};
+
+export function EngineBadge({ engineId, className }: EngineBadgeProps): React.ReactElement {
+  const label = LABELS[engineId] ?? engineId;
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center rounded-full border border-border bg-muted/60 px-2 py-0.5 text-[10px] uppercase tracking-wide text-muted-foreground',
+        className,
+      )}
+    >
+      {label}
+    </span>
+  );
+}

package/src/tools/SpeechRecognition/components/ErrorBanner.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+import type * as React from 'react';
+
+import { AlertTriangle } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { RecognitionError } from '../types';
+
+const FRIENDLY: Record<RecognitionError['code'], string> = {
+  unsupported: 'Speech recognition isn\'t available in this browser.',
+  'permission-denied': 'Microphone access was denied. Allow it in your browser settings to dictate.',
+  'no-microphone': 'No microphone found.',
+  network: 'Network error talking to the speech service.',
+  aborted: 'Recognition was interrupted.',
+  'no-speech': 'No speech was detected. Try again.',
+  language: 'The requested language isn\'t supported by the engine.',
+  engine: 'The speech engine reported an error.',
+  unknown: 'Something went wrong with the microphone.',
+};
+
+export interface ErrorBannerProps {
+  error: RecognitionError | null;
+  className?: string;
+  onDismiss?: () => void;
+}
+
+export function ErrorBanner({ error, className, onDismiss }: ErrorBannerProps): React.ReactElement | null {
+  if (!error) return null;
+  return (
+    <div
+      role="alert"
+      className={cn(
+        'flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive',
+        className,
+      )}
+    >
+      <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+      <div className="flex-1">{FRIENDLY[error.code] ?? error.message}</div>
+      {onDismiss && (
+        <button
+          type="button"
+          onClick={onDismiss}
+          className="text-destructive hover:underline"
+        >
+          Dismiss
+        </button>
+      )}
+    </div>
+  );
+}

package/src/tools/SpeechRecognition/components/LanguagePicker.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface LanguageOption {
+  value: string;
+  label: string;
+}
+
+const DEFAULT_LANGUAGES: LanguageOption[] = [
+  { value: 'en-US', label: 'English (US)' },
+  { value: 'en-GB', label: 'English (UK)' },
+  { value: 'ru-RU', label: 'Русский' },
+  { value: 'ko-KR', label: '한국어' },
+  { value: 'ja-JP', label: '日本語' },
+  { value: 'zh-CN', label: '中文 (简体)' },
+  { value: 'es-ES', label: 'Español' },
+  { value: 'fr-FR', label: 'Français' },
+  { value: 'de-DE', label: 'Deutsch' },
+];
+
+export interface LanguagePickerProps {
+  value: string;
+  onChange: (value: string) => void;
+  options?: LanguageOption[];
+  className?: string;
+  disabled?: boolean;
+  ariaLabel?: string;
+}
+
+export function LanguagePicker({
+  value,
+  onChange,
+  options = DEFAULT_LANGUAGES,
+  className,
+  disabled,
+  ariaLabel = 'Recognition language',
+}: LanguagePickerProps): React.ReactElement {
+  return (
+    <select
+      value={value}
+      onChange={(e) => onChange(e.target.value)}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      className={cn(
+        'h-8 rounded-md border border-input bg-background px-2 text-xs text-foreground',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        className,
+      )}
+    >
+      {options.map((o) => (
+        <option key={o.value} value={o.value}>
+          {o.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+export { DEFAULT_LANGUAGES };

package/src/tools/SpeechRecognition/components/MicMeter.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface MicMeterProps {
+  /** RMS level 0..1 (use the value returned by `useMicLevel`). */
+  level: number;
+  /** Number of bars rendered. @default 12 */
+  bars?: number;
+  /** Bar gap in px. @default 2 */
+  gap?: number;
+  /** Bar width in px. @default 3 */
+  barWidth?: number;
+  /** Container height in px. @default 24 */
+  height?: number;
+  className?: string;
+}
+
+/**
+ * Discrete-bar VU meter — small, dependency-free, no canvas. Each bar
+ * lights up when the current `level` exceeds its threshold. Centre bars
+ * are tallest so the meter reads like a classic mic level indicator.
+ */
+export function MicMeter({
+  level,
+  bars = 12,
+  gap = 2,
+  barWidth = 3,
+  height = 24,
+  className,
+}: MicMeterProps): React.ReactElement {
+  const clamped = Math.min(1, Math.max(0, level));
+  return (
+    <div
+      role="meter"
+      aria-valuemin={0}
+      aria-valuemax={1}
+      aria-valuenow={clamped}
+      className={cn('inline-flex items-center', className)}
+      style={{ gap, height }}
+    >
+      {Array.from({ length: bars }).map((_, i) => {
+        const ratio = (i + 1) / bars;
+        const active = clamped >= ratio - 0.5 / bars;
+        // taller in the middle, shorter at edges
+        const heightRatio = 1 - Math.abs(i - (bars - 1) / 2) / ((bars - 1) / 2 || 1);
+        const barH = Math.max(2, height * (0.35 + heightRatio * 0.65));
+        return (
+          <span
+            key={i}
+            className={cn(
+              'rounded-sm transition-colors',
+              active ? 'bg-primary' : 'bg-border',
+            )}
+            style={{ width: barWidth, height: barH }}
+          />
+        );
+      })}
+    </div>
+  );
+}

package/src/tools/SpeechRecognition/components/PushToTalkHint.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface PushToTalkHintProps {
+  /** Same chord string passed to `usePushToTalk`. */
+  chord: string;
+  className?: string;
+}
+
+/**
+ * Renders "Hold ⌥ to talk" with the chord pretty-printed. Tiny helper
+ * meant to live next to a `DictationButton`.
+ */
+export function PushToTalkHint({ chord, className }: PushToTalkHintProps): React.ReactElement {
+  const formatted = chord
+    .split('+')
+    .map((p) => p.trim().toLowerCase())
+    .map((p) => {
+      switch (p) {
+        case 'mod':
+        case 'meta':
+          return '⌘';
+        case 'alt':
+          return '⌥';
+        case 'shift':
+          return '⇧';
+        case 'ctrl':
+          return '⌃';
+        default:
+          return p.length === 1 ? p.toUpperCase() : p;
+      }
+    })
+    .join('');
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center gap-1 text-[11px] text-muted-foreground',
+        className,
+      )}
+    >
+      Hold
+      <kbd className="rounded border border-border bg-muted px-1 py-0.5 font-mono text-[10px] text-foreground">
+        {formatted}
+      </kbd>
+      to talk
+    </span>
+  );
+}

package/src/tools/SpeechRecognition/components/TranscriptView.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { Transcript } from '../types';
+
+export interface TranscriptViewProps {
+  transcript: Transcript;
+  /** Render the empty state when there is nothing yet. */
+  emptyState?: React.ReactNode;
+  /** Tone the interim text down so users can tell it's still "wet". */
+  dimInterim?: boolean;
+  className?: string;
+}
+
+/**
+ * Two-tone transcript: final segments in foreground, the trailing
+ * interim chunk dimmed so users see the model "thinking". Pure
+ * presentational — pair with `useSpeechRecognition().transcript`.
+ */
+export function TranscriptView({
+  transcript,
+  emptyState,
+  dimInterim = true,
+  className,
+}: TranscriptViewProps): React.ReactElement {
+  const { final, interim } = transcript;
+  if (!final && !interim) {
+    return (
+      <div className={cn('text-sm text-muted-foreground', className)}>
+        {emptyState ?? 'Press the mic to start dictating…'}
+      </div>
+    );
+  }
+  return (
+    <div className={cn('text-sm leading-relaxed', className)}>
+      <span className="text-foreground whitespace-pre-wrap">{final}</span>
+      {interim && (
+        <>
+          {' '}
+          <span
+            className={cn(
+              'whitespace-pre-wrap',
+              dimInterim ? 'text-muted-foreground' : 'text-foreground',
+            )}
+          >
+            {interim}
+          </span>
+        </>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,16 @@
+export { DictationButton } from './DictationButton';
+export type { DictationButtonProps } from './DictationButton';
+export { MicMeter } from './MicMeter';
+export type { MicMeterProps } from './MicMeter';
+export { TranscriptView } from './TranscriptView';
+export type { TranscriptViewProps } from './TranscriptView';
+export { LanguagePicker, DEFAULT_LANGUAGES } from './LanguagePicker';
+export type { LanguagePickerProps, LanguageOption } from './LanguagePicker';
+export { DevicePicker } from './DevicePicker';
+export type { DevicePickerProps } from './DevicePicker';
+export { EngineBadge } from './EngineBadge';
+export type { EngineBadgeProps } from './EngineBadge';
+export { ErrorBanner } from './ErrorBanner';
+export type { ErrorBannerProps } from './ErrorBanner';
+export { PushToTalkHint } from './PushToTalkHint';
+export type { PushToTalkHintProps } from './PushToTalkHint';

package/src/tools/SpeechRecognition/context/SpeechRecognitionProvider.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import type * as React from 'react';
+import { createContext, useContext, useMemo } from 'react';
+
+import type { UseSpeechRecognitionConfig, UseSpeechRecognitionReturn } from '../types';
+import { useSpeechRecognition } from '../hooks/useSpeechRecognition';
+
+const Ctx = createContext<UseSpeechRecognitionReturn | null>(null);
+
+export interface SpeechRecognitionProviderProps extends UseSpeechRecognitionConfig {
+  children?: React.ReactNode;
+}
+
+/**
+ * Lifts a single `useSpeechRecognition` instance into a context so any
+ * descendant — composer slot, header badge, transcript overlay — can
+ * read the same status / transcript / level without each component
+ * spinning up its own engine. Mount it once per Chat (or per
+ * dictation-aware screen).
+ */
+export function SpeechRecognitionProvider({
+  children,
+  ...config
+}: SpeechRecognitionProviderProps): React.ReactElement {
+  const rec = useSpeechRecognition(config);
+  // Memo prevents context-value churn from leaking through to every
+  // useContext consumer when only one of {status, level, transcript}
+  // changes — React already triggers them via the inner state, the
+  // outer object identity should stay stable across renders.
+  const value = useMemo(() => rec, [rec]);
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useSpeechRecognitionContext(): UseSpeechRecognitionReturn {
+  const ctx = useContext(Ctx);
+  if (!ctx) {
+    throw new Error(
+      'useSpeechRecognitionContext must be used inside a <SpeechRecognitionProvider>.',
+    );
+  }
+  return ctx;
+}
+
+export function useSpeechRecognitionContextOptional(): UseSpeechRecognitionReturn | null {
+  return useContext(Ctx);
+}

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

@@ -0,0 +1,6 @@
+export {
+  SpeechRecognitionProvider,
+  useSpeechRecognitionContext,
+  useSpeechRecognitionContextOptional,
+} from './SpeechRecognitionProvider';
+export type { SpeechRecognitionProviderProps } from './SpeechRecognitionProvider';

package/src/tools/SpeechRecognition/core/audio/defaults.ts

@@ -0,0 +1,24 @@
+/**
+ * Default earcons for speech sessions. We reuse two of the bundled
+ * Chat notification sounds rather than ship new MP3s — same lazy chunk
+ * already pays for them, and the tonal palette stays consistent across
+ * the chat + dictation UI.
+ *
+ *  - `start` → the chat "stream start" chime (calm low-key tone).
+ *  - `stop`  → the chat "sent" tick (2KB, very short — feels like
+ *              "captured" rather than a notification ping).
+ *    Previously used `notification.mp3` (30KB, long, loud) which was
+ *    too attention-grabbing for a self-initiated action.
+ *
+ * Loaded as `dataurl` by tsup (see `tsup.config.ts`), so consumers get
+ * working audio with zero asset setup.
+ */
+import start from '../../../Chat/core/audio/sounds/start.mp3';
+import sent from '../../../Chat/core/audio/sounds/sent.mp3';
+
+export type VoiceSoundEvent = 'start' | 'stop';
+
+export const DEFAULT_VOICE_SOUNDS: Record<VoiceSoundEvent, string> = {
+  start,
+  stop: sent,
+};