@djangocfg/widget-chat 0.1.1

package/src/core/voice/session.ts

@@ -0,0 +1,196 @@
+import type { VoiceCapability } from "../capabilities";
+import { safeEarcon, type PlayEarcon } from "./earcons";
+
+/**
+ * Dictation as a state machine — no React, no Web Speech API.
+ *
+ * The host owns recognition; this owns the two rules that are easy to get
+ * wrong and invisible when they are:
+ *
+ * 1. **An interim result REPLACES the previous interim, never appends.** The
+ *    engine re-emits its whole current guess as it refines — "hello wor",
+ *    "hello world" — so appending duplicates the sentence in front of the user.
+ * 2. **A final result COMMITS**, and the next interim starts from empty.
+ *
+ * The draft therefore always reads `committed + interim`, and only `committed`
+ * survives a stop.
+ */
+
+export interface VoiceSnapshot {
+  readonly recording: boolean;
+  /** Text the engine has committed. */
+  readonly committed: string;
+  /** The current guess. Replaced wholesale on each interim result. */
+  readonly interim: string;
+  /** What the composer should show: `committed + interim`. */
+  readonly text: string;
+  readonly error?: string;
+}
+
+export interface VoiceSessionOptions {
+  readonly capability: VoiceCapability;
+  readonly onChange: (snapshot: VoiceSnapshot) => void;
+  /**
+   * Play a start/stop tone. Absent ⇒ dictation is silent, which is a legitimate
+   * configuration: the package ships no audio and a host that supplies none
+   * gets working dictation without it.
+   */
+  readonly playEarcon?: PlayEarcon;
+}
+
+const IDLE: VoiceSnapshot = {
+  recording: false,
+  committed: "",
+  interim: "",
+  text: "",
+};
+
+export class VoiceSession {
+  private snapshot: VoiceSnapshot = IDLE;
+  private controller: AbortController | null = null;
+  /** Wrapped once here so neither call site needs a null check or a try. */
+  private readonly earcon: PlayEarcon;
+
+  constructor(private readonly options: VoiceSessionOptions) {
+    this.earcon = safeEarcon(options.playEarcon);
+  }
+
+  get state(): VoiceSnapshot {
+    return this.snapshot;
+  }
+
+  /** Begin, or do nothing if already recording. */
+  start(): void {
+    if (this.snapshot.recording) return;
+
+    const controller = new AbortController();
+    this.controller = controller;
+    this.emit({ recording: true, committed: "", interim: "", error: undefined });
+
+    // Before `capability.start`: after it the microphone is live and the tone
+    // is transcribed as a word.
+    this.earcon("start");
+
+    this.options.capability
+      .start((text, final) => {
+        // A result arriving after stop() belongs to a session the user ended.
+        // Accepting it would append words to a draft they already sent.
+        if (this.controller !== controller) return;
+        this.receive(text, final);
+      }, controller.signal)
+      .then(() => {
+        if (this.controller !== controller) return;
+        // The engine ended on its own (a pause, a time limit). Commit whatever
+        // interim was in flight rather than discarding the last words.
+        this.commitAndStop();
+      })
+      .catch((cause: unknown) => {
+        if (this.controller !== controller) return;
+        this.controller = null;
+        // Closes the pair. The start tone has already played — it must, before
+        // the microphone opens — so silence here leaves a session the user heard
+        // begin and never end.
+        this.earcon("stop");
+        // Failures settle on the snapshot; throwing here would surface as an
+        // unhandled rejection while the user is mid-sentence.
+        this.emit({
+          recording: false,
+          interim: "",
+          error: cause instanceof Error ? cause.message : String(cause),
+        });
+      });
+  }
+
+  /**
+   * Stop and commit the in-flight interim.
+   *
+   * Safe to call synchronously from a send: the capability's `stop` is invoked
+   * first, so no further words can arrive.
+   */
+  stop(): void {
+    if (!this.snapshot.recording) return;
+    this.options.capability.stop();
+    this.controller?.abort();
+    this.controller = null;
+    this.commitAndStop();
+  }
+
+  /**
+   * Stop and DISCARD everything — for a send.
+   *
+   * Distinct from `stop()` on purpose: after a send the draft is cleared, so
+   * committing dictated text back into it would resurrect the message the user
+   * just sent.
+   *
+   * SILENT: the caller is a send, which plays its own chime. A stop tone under
+   * it is two sounds for one action, and the user pressed send, not stop.
+   */
+  cancel(): void {
+    this.options.capability.stop();
+    this.controller?.abort();
+    this.controller = null;
+    // Through emit(), like every other transition. Assigning `this.snapshot`
+    // directly is the one way to leave `text` stale, since emit() is the sole
+    // place that recomputes it — a mutant doing exactly that survived a test
+    // asserting only `text`, because the stale value happened to be correct.
+    this.emit({ recording: false, committed: "", interim: "", error: undefined });
+  }
+
+  /** Take the dictated text and reset, for handing to the draft. */
+  take(): string {
+    const text = this.snapshot.text;
+    this.cancel();
+    return text;
+  }
+
+  dispose(): void {
+    this.options.capability.stop();
+    this.controller?.abort();
+    this.controller = null;
+  }
+
+  private receive(text: string, final: boolean): void {
+    if (final) {
+      // Committed text accumulates with a separating space; the engine emits
+      // phrases, not a continuous stream, so joining without one runs the
+      // sentences together.
+      const committed = this.snapshot.committed === ""
+        ? text
+        : `${this.snapshot.committed} ${text}`;
+      this.emit({ committed, interim: "" });
+      return;
+    }
+    // REPLACE, never append — the engine re-sends its whole current guess.
+    this.emit({ interim: text });
+  }
+
+  /**
+   * Both routes here — an explicit `stop()` and an engine ending on its own —
+   * are moments the user must hear, so the stop tone lives here. The microphone
+   * is already shut on both. `cancel()` does not pass through.
+   */
+  private commitAndStop(): void {
+    this.earcon("stop");
+    const { committed, interim } = this.snapshot;
+    const merged = interim === ""
+      ? committed
+      : committed === ""
+        ? interim
+        : `${committed} ${interim}`;
+    this.controller = null;
+    this.emit({ recording: false, committed: merged, interim: "" });
+  }
+
+  private emit(patch: Partial<Omit<VoiceSnapshot, "text">>): void {
+    const next = { ...this.snapshot, ...patch };
+    // `text` is DERIVED, never assigned: two writers for one value is how the
+    // draft and the snapshot drift apart.
+    const text = next.interim === ""
+      ? next.committed
+      : next.committed === ""
+        ? next.interim
+        : `${next.committed} ${next.interim}`;
+    this.snapshot = { ...next, text };
+    this.options.onChange(this.snapshot);
+  }
+}

package/src/core/voice/web-speech.ts

@@ -0,0 +1,170 @@
+import type { VoiceCapability } from "../capabilities";
+
+/**
+ * The browser's own dictation, as a `VoiceCapability`.
+ *
+ * This is the package's DEFAULT engine, and the reason the capability seam
+ * still exists: audio never leaves the device here, but a host with a server
+ * transcriber, Whisper, or a native bridge supplies its own capability and this
+ * steps aside. Neither available means no microphone button at all — a greyed
+ * out mic is a promise the product cannot keep.
+ *
+ * Everything racy — an interim replacing its predecessor, a result arriving
+ * after stop, an engine that ends on its own — is `VoiceSession`'s, not this
+ * file's. This is the adapter and nothing more.
+ */
+
+/**
+ * The two constructor spellings, without pulling in DOM lib types the package
+ * does not depend on.
+ *
+ * Typed structurally rather than via `SpeechRecognition` from `lib.dom`: that
+ * type is not in every consumer's TS configuration, and a package that fails to
+ * compile in a host missing one DOM lib is worse than one local interface.
+ */
+interface RecognitionLike {
+  continuous: boolean;
+  interimResults: boolean;
+  lang: string;
+  start: () => void;
+  stop: () => void;
+  abort: () => void;
+  onresult: ((event: RecognitionEventLike) => void) | null;
+  onerror: ((event: { readonly error?: string }) => void) | null;
+  onend: (() => void) | null;
+}
+
+interface RecognitionResultLike {
+  readonly isFinal: boolean;
+  readonly length: number;
+  readonly [index: number]: { readonly transcript: string } | undefined;
+}
+
+interface RecognitionEventLike {
+  readonly resultIndex: number;
+  readonly results: {
+    readonly length: number;
+    readonly [index: number]: RecognitionResultLike | undefined;
+  };
+}
+
+type RecognitionConstructor = new () => RecognitionLike;
+
+function constructorFor(): RecognitionConstructor | undefined {
+  if (typeof window === "undefined") return undefined;
+  const scope = window as unknown as {
+    SpeechRecognition?: RecognitionConstructor;
+    webkitSpeechRecognition?: RecognitionConstructor;
+  };
+  return scope.SpeechRecognition ?? scope.webkitSpeechRecognition;
+}
+
+/**
+ * Whether the browser can dictate at all.
+ *
+ * Exported so a host can decide before rendering. MediaRecorder is deliberately
+ * NOT treated as support: it only produces audio, and turning that into text
+ * needs a transcription endpoint — audio leaving the device, which is exactly
+ * the decision the capability seam leaves to the host.
+ */
+export function isWebSpeechAvailable(): boolean {
+  return constructorFor() !== undefined;
+}
+
+export interface WebSpeechOptions {
+  /** BCP-47 tag. Read at START, so a change applies to the next dictation. */
+  readonly language: () => string;
+}
+
+/**
+ * Build the default capability, or `undefined` when the browser has no engine.
+ *
+ * `language` is a FUNCTION, not a value: the capability object outlives any one
+ * dictation, and reading the tag at start is what lets a language change take
+ * effect without rebuilding the session mid-sentence.
+ */
+export function createWebSpeechCapability(
+  options: WebSpeechOptions,
+): VoiceCapability | undefined {
+  const Recognition = constructorFor();
+  if (Recognition === undefined) return undefined;
+
+  let active: RecognitionLike | null = null;
+
+  return {
+    start: (onText, signal) =>
+      new Promise<void>((resolve, reject) => {
+        if (signal.aborted) {
+          resolve();
+          return;
+        }
+        const recognition = new Recognition();
+        active = recognition;
+        // `continuous` so a pause between sentences does not end the session,
+        // and `interimResults` so words appear while they are being said. The
+        // interim half is what `VoiceSession`'s replace-never-append rule is
+        // for; without it dictation is silent until a phrase completes.
+        recognition.continuous = true;
+        recognition.interimResults = true;
+        recognition.lang = options.language();
+
+        const finish = (): void => {
+          if (active === recognition) active = null;
+          signal.removeEventListener("abort", onAbort);
+        };
+
+        const onAbort = (): void => {
+          recognition.abort();
+          finish();
+          resolve();
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+
+        recognition.onresult = (event) => {
+          // From `resultIndex`, not from zero: the engine re-sends the whole
+          // results list, and replaying it from the start re-delivers phrases
+          // already committed — the sentence duplicates itself.
+          for (let i = event.resultIndex; i < event.results.length; i += 1) {
+            const result = event.results[i];
+            const transcript = result?.[0]?.transcript;
+            if (result === undefined || transcript === undefined) continue;
+            onText(transcript, result.isFinal);
+          }
+        };
+
+        recognition.onerror = (event) => {
+          finish();
+          // `no-speech` and `aborted` are ordinary endings, not faults: the
+          // first is a silent room and the second is the user pressing stop.
+          // Surfacing either as an error puts a red message under a composer
+          // for doing nothing wrong.
+          if (event.error === "no-speech" || event.error === "aborted") {
+            resolve();
+            return;
+          }
+          reject(new Error(event.error ?? "speech recognition failed"));
+        };
+
+        recognition.onend = () => {
+          finish();
+          resolve();
+        };
+
+        try {
+          recognition.start();
+        } catch (cause) {
+          // `start()` throws synchronously when one is already running — a
+          // double-press. Treat it as a no-op rather than a failure.
+          finish();
+          resolve();
+          void cause;
+        }
+      }),
+    stop: () => {
+      // `stop()` rather than `abort()`: it lets the engine deliver the final
+      // result for what was already said, which is the difference between
+      // pressing stop mid-sentence and losing that sentence.
+      active?.stop();
+    },
+  };
+}

package/src/i18n/index.ts

@@ -0,0 +1,87 @@
+import { useMemo } from "react";
+import { useLocaleOptional } from "@djangocfg/i18n";
+
+import { ar } from "./locales/ar";
+import { da } from "./locales/da";
+import { de } from "./locales/de";
+import { en } from "./locales/en";
+import { es } from "./locales/es";
+import { fr } from "./locales/fr";
+import { it } from "./locales/it";
+import { ja } from "./locales/ja";
+import { ko } from "./locales/ko";
+import { nl } from "./locales/nl";
+import { no } from "./locales/no";
+import { pl } from "./locales/pl";
+import { ptBR } from "./locales/ptBR";
+import { ru } from "./locales/ru";
+import { sv } from "./locales/sv";
+import { tr } from "./locales/tr";
+import { zh } from "./locales/zh";
+import type { ChatCopy } from "./types";
+
+export type {
+  ChatCopy,
+  ComposerCopy,
+  MessageCopy,
+  PluralCopy,
+  QueueCopy,
+  ToolCopy,
+  TranscriptCopy,
+  VoiceCopy,
+} from "./types";
+export { fill, plural } from "./plural";
+
+/**
+ * Every bundled dictionary, keyed by the language code the host reports.
+ *
+ * Exported so the registry test asserts against THIS object rather than its own
+ * copy of the list: a second list is a second thing to forget, and what it
+ * hides is a locale that silently never loads.
+ */
+export const CHAT_DICTIONARIES: Readonly<Record<string, ChatCopy>> = {
+  en, ru, de, fr, es, it, nl, pl, sv, no, da, tr, ja, ko, zh, ar,
+  // The KEY is the language code the app reports (`pt-BR`), which is not a
+  // valid JS identifier — so the binding is `ptBR` and the key is quoted. Get
+  // this wrong and the lookup misses: every Brazilian user falls back to
+  // English with no error anywhere.
+  "pt-BR": ptBR,
+};
+
+/**
+ * The chat dictionary for the active language, English for anything not yet
+ * translated.
+ *
+ * The package owns its copy rather than taking it as props. Labels-in
+ * looked right — it kept this package free of i18next — but it made adding one
+ * string a four-file change and let a host assemble a translated string into a
+ * DOM selector, which broke the composer's caret in a single locale with types
+ * and tests green.
+ *
+ * The whole typed object, not a `t(key)` resolver: a dot-path string
+ * reintroduces exactly the runtime miss that typing the schema removes.
+ * `@djangocfg/i18n` types a CLOSED resources map, so a `chat` namespace does
+ * not typecheck there, and opening one would point the dependency arrow from
+ * `i18n` at this widget.
+ *
+ * `useLocaleOptional` returns null with no provider mounted, which is what lets
+ * every surface render in Storybook and in a test without one.
+ */
+export function useChatCopy(): ChatCopy {
+  const locale = useLocaleOptional();
+  return useMemo(() => (locale ? CHAT_DICTIONARIES[locale] ?? en : en), [locale]);
+}
+
+/**
+ * The active language tag, for `Intl.PluralRules`.
+ *
+ * Separate from the dictionary because the two can disagree: an untranslated
+ * language falls back to the English STRINGS while its own plural CATEGORIES
+ * still apply, and selecting `few` from a dictionary that has none is what the
+ * `other` fallback in `plural()` exists to absorb.
+ */
+export function useChatLanguage(): string {
+  // English rather than the empty string with no provider: `Intl.PluralRules`
+  // throws on an invalid tag, and a plural category is needed on every render.
+  return useLocaleOptional() ?? "en";
+}

package/src/i18n/locales/ar.ts

@@ -0,0 +1,97 @@
+import type { ChatCopy } from "../types";
+
+export const ar: ChatCopy = {
+  transcript: {
+    empty: "لا توجد رسائل بعد.",
+    suggestionsLabel: "اقتراحات للبدء",
+    log: "المحادثة",
+    announceStreaming: "المساعد يجيب",
+    announceComplete: "اكتمل الرد",
+    jumpToLatest: "الانتقال إلى الأحدث",
+    thinking: "يفكر",
+    thinkingElapsed: "{{seconds}} ث",
+    today: "اليوم",
+    yesterday: "أمس",
+  },
+  message: {
+    copy: "نسخ",
+    reply: "رد",
+    copyLink: "نسخ الرابط",
+    copiedLink: "تم نسخ الرابط",
+    jumpToQuoted: "الانتقال إلى الرسالة المقتبسة",
+    copied: "تم النسخ",
+    reasoning: "الاستدلال",
+    reasoningLive: "جارٍ التفكير…",
+    reasoningTokens: {
+      other: "فكّر خلال {{count}} رمزًا",
+    },
+    showMore: "عرض المزيد",
+    showLess: "عرض أقل",
+  },
+  tool: {
+    inputStreaming: "قيد التحضير",
+    inputAvailable: "قيد التشغيل",
+    outputAvailable: "تم",
+    outputError: "فشل",
+    collapse: "طيّ استدعاء الأداة",
+    expand: "توسيع استدعاء الأداة",
+  },
+  composer: {
+    replyClear: "إلغاء الرد",
+    input: "رسالة",
+    placeholder: "اسأل أي شيء",
+    send: "إرسال",
+    sendShortcut: "‏Enter للإرسال",
+    stop: "إيقاف",
+    toolsMenu: "الأدوات",
+    toolsSearch: "ابحث عن أداة…",
+    toolsEmpty: "لا توجد أداة بهذا الاسم",
+    toolsRecent: "الأخيرة",
+    toolsForget: "إزالة من الأخيرة",
+    toolRemove: "إزالة الأداة",
+    needsFile: "أرفق الملف",
+    needsSkill: "حدّد المهارة",
+    toolsPicked: "الأدوات المختارة",
+    thinkOn: "تفكير أطول (أبطأ، تكلفة أعلى)",
+    thinkOff: "إيقاف التفكير الأطول",
+  },
+  queue: {
+    prompts: {
+      zero: "{{count}} رسالة في قائمة الانتظار",
+      one: "{{count}} رسالة في قائمة الانتظار",
+      two: "{{count}} رسالتان في قائمة الانتظار",
+      few: "{{count}} رسائل في قائمة الانتظار",
+      many: "{{count}} رسالة في قائمة الانتظار",
+      other: "{{count}} رسالة في قائمة الانتظار",
+    },
+    more: {
+      zero: "{{count}} إضافية",
+      one: "{{count}} إضافية",
+      two: "{{count}} إضافيتان",
+      few: "{{count}} إضافية",
+      many: "{{count}} إضافية",
+      other: "{{count}} إضافية",
+    },
+    showLess: "عرض أقل",
+    remove: "إزالة من قائمة الانتظار",
+    show: "عرض قائمة الانتظار",
+    edit: "تحرير هذا الطلب",
+    send: "الإرسال الآن",
+    sendNow: "الإرسال الآن مع إيقاف الرد الحالي",
+    sendNowConfirmTitle: "إرسال هذه الرسالة الآن؟",
+    sendNowConfirmMessage:
+      "سيتوقف الرد الحالي وسيُفقد العمل غير المكتمل. تحتفظ بقية الرسائل بترتيبها في قائمة الانتظار.",
+    replaceDraftTitle: "استبدال ما كتبته؟",
+    replaceDraftMessage:
+      "مسودتك وهذه الرسالة مختلفتان. اختر ما تريد الاحتفاظ به.",
+  },
+  voice: {
+    start: "إملاء",
+    stop: "إيقاف الإملاء",
+    language: "لغة الإملاء",
+    languageMenu: "لغة الإملاء",
+    languageSearch: "البحث عن اللغات",
+    languageEmpty: "لم يتم العثور على لغة",
+    languageBack: "رجوع",
+  },
+};

package/src/i18n/locales/da.ts

@@ -0,0 +1,90 @@
+import type { ChatCopy } from "../types";
+
+export const da: ChatCopy = {
+  transcript: {
+    empty: "Ingen beskeder endnu.",
+    suggestionsLabel: "Foreslåede prompts",
+    log: "Samtale",
+    announceStreaming: "Assistenten svarer",
+    announceComplete: "Svaret er færdigt",
+    jumpToLatest: "Gå til nyeste",
+    thinking: "Tænker",
+    thinkingElapsed: "{{seconds}} s",
+    today: "I dag",
+    yesterday: "I går",
+  },
+  message: {
+    copy: "Kopiér",
+    reply: "Svar",
+    copyLink: "Kopiér link",
+    copiedLink: "Link kopieret",
+    jumpToQuoted: "Gå til citeret besked",
+    copied: "Kopieret",
+    reasoning: "Ræsonnement",
+    reasoningLive: "Ræsonnerer…",
+    reasoningTokens: {
+      one: "Tænkte i {{count}} token",
+      other: "Tænkte i {{count}} tokens",
+    },
+    showMore: "Vis mere",
+    showLess: "Vis mindre",
+  },
+  tool: {
+    inputStreaming: "Forbereder",
+    inputAvailable: "Kører",
+    outputAvailable: "Færdig",
+    outputError: "Mislykkedes",
+    collapse: "Skjul værktøjskaldet",
+    expand: "Vis værktøjskaldet",
+  },
+  composer: {
+    replyClear: "Annullér svar",
+    input: "Besked",
+    placeholder: "Spørg om hvad som helst",
+    send: "Send",
+    sendShortcut: "Enter for at sende",
+    stop: "Stop",
+    toolsMenu: "Værktøjer",
+    toolsSearch: "Find et værktøj…",
+    toolsEmpty: "Intet sådant værktøj",
+    toolsRecent: "Seneste",
+    toolsForget: "Fjern fra seneste",
+    toolRemove: "Fjern værktøj",
+    needsFile: "Vedhæft filen",
+    needsSkill: "Nævn din skill",
+    toolsPicked: "Valgte værktøjer",
+    thinkOn: "Tænk længere (langsommere, koster mere)",
+    thinkOff: "Stop længere tænkning",
+  },
+  queue: {
+    prompts: {
+      one: "{{count}} besked i kø",
+      other: "{{count}} beskeder i kø",
+    },
+    more: {
+      one: "{{count}} mere",
+      other: "{{count}} mere",
+    },
+    showLess: "Vis mindre",
+    remove: "Fjern fra køen",
+    show: "Vis køen",
+    edit: "Rediger anmodningen",
+    send: "Send nu",
+    sendNow: "Send nu, og afbryd det igangværende svar",
+    sendNowConfirmTitle: "Send denne besked nu?",
+    sendNowConfirmMessage:
+      "Det igangværende svar afbrydes, og dets ufærdige arbejde går tabt. De øvrige beskeder beholder deres rækkefølge i køen.",
+    replaceDraftTitle: "Erstat det, du har skrevet?",
+    replaceDraftMessage:
+      "Dit udkast og denne besked er forskellige. Vælg, hvad der bevares.",
+  },
+  voice: {
+    start: "Diktér",
+    stop: "Stop diktering",
+    language: "Dikteringssprog",
+    languageMenu: "Dikteringssprog",
+    languageSearch: "Søg sprog",
+    languageEmpty: "Intet sprog fundet",
+    languageBack: "Tilbage",
+  },
+};