@djangocfg/widget-chat 0.1.1

package/src/composer/controls/think.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+
+import { useChatCopy } from "../../i18n";
+import { useCapabilities } from "../../store";
+import { ComposerButton } from "./button";
+import { ComposerTooltip } from "./tooltip";
+
+export interface ComposerThinkProps {
+  readonly className?: string;
+  /**
+   * Icon or glyph, a FUNCTION of the on/off state like `ComposerVoice`'s. The
+   * accessible name comes from the label, never from this.
+   */
+  readonly children?: (enabled: boolean) => ReactNode;
+}
+
+/**
+ * Ask the model to think longer before answering, or nothing at all.
+ *
+ * **No capability ⇒ absent button**, never a disabled one. Only a third of the
+ * catalogue accepts the `reasoning_effort` request field, so a toggle rendered
+ * unconditionally would be pressable and inert on the rest — worse than absent,
+ * because it looks like it worked.
+ *
+ * The state is STICKY across turns (ChatGPT's behaviour): it lives on the
+ * capability, which the host owns, not in the draft. A draft-held value would
+ * switch itself off on every send, since `send` clears the draft.
+ */
+export function ComposerThink({ className, children }: ComposerThinkProps) {
+  const { think } = useCapabilities();
+  const copy = useChatCopy().composer;
+
+  if (!think) return null;
+
+  const label = think.enabled ? copy.thinkOff : copy.thinkOn;
+
+  return (
+    <ComposerTooltip label={label}>
+      <ComposerButton
+        className={className}
+        aria-label={label}
+        // A toggle, so the state is announced rather than inferred from the icon.
+        aria-pressed={think.enabled}
+        onClick={() => think.setEnabled(!think.enabled)}
+      >
+        {children?.(think.enabled)}
+      </ComposerButton>
+    </ComposerTooltip>
+  );
+}

package/src/composer/controls/tools.tsx

@@ -0,0 +1,130 @@
+import { useCallback, useMemo, useRef, useState, type ReactNode } from "react";
+
+import { useChatCopy } from "../../i18n";
+import { useDismiss } from "../../primitives";
+import { useCapabilities } from "../../store";
+import type { ToolCatalogEntry } from "../../core";
+import { useOptionalComposer } from "../context";
+import { focusComposerField } from "../focus-field";
+import { ToolMenu } from "../tools/menu";
+import { ComposerButton } from "./button";
+
+export interface ComposerToolsProps {
+  readonly className?: string;
+  /** The trigger's glyph. The accessible name comes from the label, never this. */
+  readonly children?: ReactNode;
+  /** Glyph for an entry's icon KEY. Absent, or unmapped, ⇒ a row with no glyph. */
+  readonly icon?: (key: string) => ReactNode;
+  /**
+   * The heading for a category key. Absent ⇒ the registry's raw key. The host's,
+   * because a mapping declared here goes stale silently on a new tool family.
+   */
+  readonly categoryLabel?: (category: string) => string;
+}
+
+/**
+ * The arsenal, or nothing at all.
+ *
+ * No capability ⇒ absent button, never a disabled one.
+ *
+ * A pick WRITES an intent into the draft and stops there — it neither runs the
+ * tool nor sends the turn, so the user can still add a file or edit the wording.
+ */
+export function ComposerTools({ className, children, icon, categoryLabel }: ComposerToolsProps) {
+  const { tools } = useCapabilities();
+  const copy = useChatCopy().composer;
+  const composer = useOptionalComposer();
+  const [open, setOpen] = useState(false);
+
+  const panelRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  const close = useCallback(() => setOpen(false), []);
+  // The trigger counts as inside, or its own press dismisses and reopens in one
+  // gesture and the sheet never closes by its button.
+  useDismiss({ open, onDismiss: close, refs: [panelRef, triggerRef] });
+
+  // The menu CLOSES on a pick: picking is the common act and unpicking the rare
+  // one, so the sheet should get out of the way rather than stay open for a
+  // correction most users never make. The staged chips are visible in the tray
+  // below, and each carries its own `×` — the way back does not need this sheet.
+  const onPick = useCallback(
+    (entry: ToolCatalogEntry) => {
+      // Staged on the draft, never written into the text: the marker belongs to
+      // the whole turn, and splicing one at the caret would change what the
+      // prose around it means. `buildOutbound` appends it at send.
+      // `needs` rides along so the composer can say what is still missing
+      // without holding the catalogue: the draft is what the placeholder reads.
+      composer?.toggleTool({
+        id: entry.id,
+        label: entry.name,
+        icon: entry.icon,
+        needs: entry.needs,
+      });
+      // The host's, after the fact — for a menu that must also record the pick.
+      // It cannot decide the text, or two writers would own the outbound turn.
+      tools?.onPick?.(entry);
+      close();
+      // A pick states an intent; the sentence naming its object comes next, so
+      // the caret must already be waiting. Without this the closing dialog
+      // leaves focus nowhere and the next keystroke is lost. Deferred: the menu
+      // is still mounted in this tick, and blur on unmount would undo it.
+      queueMicrotask(() => focusComposerField(triggerRef.current?.closest("form")));
+    },
+    [tools, composer, close],
+  );
+
+  const picked = useMemo(
+    () => new Set((composer?.draft.pickedTools ?? []).map((pick) => pick.id)),
+    [composer?.draft.pickedTools],
+  );
+
+  if (tools === undefined) return null;
+
+  // Three states, not two. `entries` empty while `loading` means the server has
+  // not answered yet, so the trigger holds its place disabled rather than
+  // disappearing and popping back when the reply lands.
+  const pending = tools.loading === true && tools.entries.length === 0;
+
+  return (
+    <span className="relative inline-flex items-center">
+      <ComposerButton
+        ref={triggerRef}
+        className={className}
+        aria-label={copy.toolsMenu}
+        aria-expanded={open}
+        aria-haspopup="dialog"
+        disabled={pending}
+        // The label already names the control; `busy` says the wait is this
+        // control's own, so a reader is not told the whole composer is loading.
+        aria-busy={pending || undefined}
+        onClick={() => setOpen((current) => !current)}
+      >
+        {children}
+      </ComposerButton>
+      {open && !pending ? (
+        <div
+          ref={panelRef}
+          role="dialog"
+          aria-label={copy.toolsMenu}
+          /* `left-0`, the mirror of the voice panel's `right-0`: this trigger
+             sits at the START of the row, so the panel has room only rightward. */
+          className="border-border bg-popover text-popover-foreground absolute bottom-full left-0 z-20 mb-2 w-72 overflow-hidden rounded-lg border shadow-lg"
+        >
+          <ToolMenu
+            entries={tools.entries}
+            onPick={onPick}
+            picked={picked}
+            label={copy.toolsMenu}
+            searchLabel={copy.toolsSearch}
+            emptyLabel={copy.toolsEmpty}
+            recentLabel={copy.toolsRecent}
+            forgetLabel={copy.toolsForget}
+            icon={icon}
+            categoryLabel={categoryLabel}
+          />
+        </div>
+      ) : null}
+    </span>
+  );
+}

package/src/composer/controls/tooltip.tsx

@@ -0,0 +1,10 @@
+export { ChatTooltip as ComposerTooltip } from "../../primitives/tooltip";
+export type { ChatTooltipProps as ComposerTooltipProps } from "../../primitives/tooltip";
+
+/**
+ * The composer's spelling of the shared `ChatTooltip`.
+ *
+ * An alias, not a second implementation: the message action row needs the same
+ * hover name, so the component moved to `primitives` and this keeps the three
+ * composer call sites reading in their own vocabulary.
+ */

package/src/composer/controls/voice.tsx

@@ -0,0 +1,266 @@
+import { ChevronDown, ChevronLeft, ChevronRight } from "lucide-react";
+import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+
+import { useChatCopy } from "../../i18n";
+import { useDismiss } from "../../primitives";
+import { useCapabilities, useVoice } from "../../store";
+import { ComposerButton } from "./button";
+import { ComposerTooltip } from "./tooltip";
+import { useComposer } from "../context";
+import { LanguageMenu, languageLabel } from "./language-menu";
+
+export interface ComposerVoiceProps {
+  readonly className?: string;
+  /**
+   * Icon or glyph. The accessible name comes from the labels, never from this.
+   *
+   * A FUNCTION of `recording`, matching `ComposerSend` and `ToolCallHeader`: the
+   * glyph must change with the role, and a static node cannot express that.
+   *
+   * Optional, but every assembly we ship passes one — an omitted `children` is
+   * how `ComposerSend` renders a blank blue pill. The default in
+   * `ui/chat.tsx` exists so a host never has to think about it.
+   */
+  readonly children?: (recording: boolean) => ReactNode;
+  /**
+   * The dictation language and how to change it.
+   *
+   * Absent ⇒ the mic alone, no options button. A host that has no opinion still
+   * gets working dictation, because `useSpeechLanguage` resolves a default;
+   * passing this is what makes the resolved value VISIBLE and overridable.
+   */
+  readonly language?: {
+    readonly value: string;
+    readonly onChange: (tag: string) => void;
+  };
+}
+
+/**
+ * Dictation, or nothing at all.
+ *
+ * **No engine ⇒ absent button**, never a disabled one — a greyed-out mic is a
+ * promise the product cannot keep. Note the threshold is the ENGINE, not the
+ * capability: an absent capability falls back to the package's Web Speech
+ * default, so only a browser without one yields no button. A host supplying its
+ * own capability overrides that default outright.
+ *
+ * The ANCHOR lives here, not in `VoiceSession`. The session knows only what was
+ * dictated; what the user had already typed before pressing the mic is composer
+ * state. Without anchoring, dictating into a half-written message replaces it.
+ */
+export function ComposerVoice({ className, children, language }: ComposerVoiceProps) {
+  const { voice: capability, voiceSounds } = useCapabilities();
+  const copy = useChatCopy().voice;
+  const { draft, setText, onSend } = useComposer();
+  const { available, recording, text, start, stop, cancel } = useVoice(
+    capability,
+    language?.value,
+    voiceSounds?.play,
+  );
+  const [pickerOpen, setPickerOpen] = useState(false);
+  // Which view the ONE panel is showing. A view switch rather than a second
+  // popover: nesting one floating surface inside another makes both fight over
+  // the same outside-press, and the inner search box loses keys to the outer.
+  const [view, setView] = useState<"main" | "language">("main");
+
+  const panelRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  const close = useCallback(() => {
+    setPickerOpen(false);
+    // Reset on the way out, so reopening always starts at the top rather than
+    // wherever the last visit ended.
+    setView("main");
+  }, []);
+
+  // The trigger is `inside` too — otherwise its own press dismisses and
+  // reopens in one gesture, and the panel can never be closed by its button.
+  useDismiss({ open: pickerOpen, onDismiss: close, refs: [panelRef, triggerRef] });
+
+  // Text present when dictation began. A ref, not state: it is read in a
+  // handler and an effect, never rendered.
+  const anchor = useRef("");
+  // Whether THIS session's transcript may write to the draft. Set on press,
+  // cleared on the commit, so a settled session cannot keep re-anchoring — see
+  // the effect below for the duplication that caused.
+  const armed = useRef(false);
+  // The draft, readable without depending on it. The click handler needs the
+  // CURRENT text, but this button has no reason to re-render on every keystroke.
+  const draftText = useRef(draft.text);
+  draftText.current = draft.text;
+
+  // A send ends dictation and discards what it heard.
+  //
+  // `cancel`, never `stop`: stop commits the in-flight interim into a draft the
+  // send just cleared, so the sent words reappear in the empty field.
+  //
+  // `armed` is disarmed here because it lives in this component, not the
+  // session: cancel emits one last empty snapshot that an armed effect would
+  // write into the new draft.
+  //
+  // Registered unconditionally — gating on `recording` would re-subscribe once
+  // per interim result, and cancel on an idle session is a no-op.
+  useEffect(() => {
+    return onSend(() => {
+      armed.current = false;
+      anchor.current = "";
+      cancel();
+    });
+  }, [onSend, cancel]);
+
+  const onClick = useCallback(() => {
+    if (recording) {
+      stop();
+      return;
+    }
+    // Captured on the way IN, before the session emits anything, so the anchor
+    // is the user's typed text and never a previous transcript.
+    anchor.current = draftText.current;
+    armed.current = true;
+    start();
+  }, [recording, start, stop]);
+
+  // Push the transcript into the draft as it arrives. Depends on `text`, so an
+  // interim REPLACING its predecessor replaces it in the field too — the
+  // duplicate-sentence bug `VoiceSession` exists to prevent, preserved across
+  // the React boundary rather than re-solved here.
+  //
+  // Gated on `armed`, NOT on `text !== ""`. The empty-text guard looks
+  // equivalent and is not: `start()` emits an empty snapshot, so a settled
+  // session's transcript could be re-applied by a later unrelated render, on top
+  // of whatever the user had typed since.
+  //
+  // What this does NOT do is stop a second dictation appending to the first —
+  // that is correct behaviour, not duplication. A user who presses the mic twice
+  // dictated twice, and the anchor is the draft as it stands, first transcript
+  // included.
+  useEffect(() => {
+    if (!armed.current) return;
+    setText(anchor.current === "" ? text : `${anchor.current} ${text}`);
+    // Disarm once the session has settled and delivered its final text. Leaving
+    // it armed would let a later unrelated render re-apply the same transcript
+    // on top of whatever the user has typed since.
+    if (!recording && text !== "") armed.current = false;
+  }, [recording, text, setText]);
+
+  if (!available) return null;
+
+  const micLabel = recording ? copy.stop : copy.start;
+  const mic = (
+    <ComposerTooltip label={micLabel}>
+      <ComposerButton
+        className={className}
+        aria-label={micLabel}
+        // A toggle, so the state is announced rather than inferred from the icon.
+        aria-pressed={recording}
+        // The state as DATA, so `styles/composer.css` owns the halo and its
+        // reduced-motion fallback. A Tailwind arbitrary variant would need the
+        // keyframes declared somewhere anyway, and then the rule and its
+        // animation would live in two files.
+        data-recording={recording || undefined}
+        onClick={onClick}
+      >
+        {children?.(recording)}
+      </ComposerButton>
+    </ComposerTooltip>
+  );
+
+  if (language === undefined) return mic;
+
+  const back = (
+    <div className="border-border flex items-center gap-1 border-b px-1 py-1">
+      <button
+        type="button"
+        aria-label={copy.languageBack}
+        onClick={() => setView("main")}
+        className="text-muted-foreground hover:bg-accent hover:text-foreground inline-flex h-6 w-6 items-center justify-center rounded-sm"
+      >
+        <ChevronLeft className="size-4" aria-hidden />
+      </button>
+      <span className="text-sm font-medium">{copy.languageMenu}</span>
+    </div>
+  );
+
+  const panel =
+    view === "language" ? (
+      <LanguageMenu
+        current={language.value}
+        onSelect={(tag) => {
+          language.onChange(tag);
+          close();
+        }}
+        label={copy.languageMenu}
+        searchLabel={copy.languageSearch}
+        emptyLabel={copy.languageEmpty}
+        header={back}
+      />
+    ) : (
+      <div className="flex flex-col gap-0.5 p-1">
+        {/*
+          The current value is on the ROW, not only behind it. A user whose
+          dictation returns nonsense has to be able to read what it is listening
+          for at the point where it fails — otherwise the state that broke the
+          feature is invisible from the feature.
+        */}
+        <button
+          type="button"
+          onClick={() => setView("language")}
+          className="hover:bg-accent hover:text-accent-foreground flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-left text-sm"
+        >
+          <span className="flex min-w-0 flex-1 flex-col">
+            <span>{copy.languageMenu}</span>
+            <span className="text-muted-foreground truncate text-xs">
+              {languageLabel(language.value)}
+            </span>
+          </span>
+          <ChevronRight className="text-muted-foreground size-4 shrink-0" aria-hidden />
+        </button>
+      </div>
+    );
+
+  // Trigger LEFT of the mic, mic last. The mic is the control the user aims for
+  // and the one that must stay adjacent to Send; an options button between them
+  // makes the action bar read as two competing primary buttons.
+  return (
+    <span className="relative inline-flex items-center gap-1">
+      {/* The shared control, like every other button in this row. Hand-rolled it
+          tinted with `--accent` — the theme's highlight, blue here — so this one
+          answered a hover with a coloured plate while its neighbours answered
+          with a grey one, and the row read as four unrelated controls. */}
+      {/* Tooltip OUTER, so its `asChild` and the button's ref compose onto one
+          node rather than each cloning separately. */}
+      <ComposerTooltip label={copy.language}>
+        <ComposerButton
+          ref={triggerRef}
+          aria-label={copy.language}
+          aria-expanded={pickerOpen}
+          aria-haspopup="dialog"
+          onClick={() => {
+            setPickerOpen((open) => !open);
+            setView("main");
+          }}
+        >
+          <ChevronDown className="size-4" aria-hidden />
+        </ComposerButton>
+      </ComposerTooltip>
+      {pickerOpen ? (
+        <div
+          ref={panelRef}
+          role="dialog"
+          aria-label={copy.language}
+          /*
+            Anchored to the trigger's RIGHT edge, not its left. The panel is
+            wider than the control that opens it, so `left-0` sends 256px of it
+            off past the composer's right edge — measured as a menu floating
+            detached in the middle of the transcript. `right-0` grows it back
+            over the composer, which is the only direction with room.
+          */
+          className="border-border bg-popover text-popover-foreground absolute bottom-full right-0 z-20 mb-2 w-64 overflow-hidden rounded-lg border shadow-lg"
+        >
+          {panel}
+        </div>
+      ) : null}
+      {mic}
+    </span>
+  );
+}

package/src/composer/field/field.tsx

@@ -0,0 +1,140 @@
+import { useRef, type KeyboardEvent } from "react";
+import { useChatEvents, useRecall } from "../../store";
+import { unmetNeed } from "../../core";
+import { useChatCopy } from "../../i18n";
+import { composerKeyDown } from "./keys";
+import { ComposerInput } from "./input";
+import { useComposer } from "../context";
+
+export interface ComposerFieldProps {
+  readonly className?: string;
+  /**
+   * Classes for the POSITIONED WRAPPER, not the textarea.
+   *
+   * They are different elements with different jobs, and only the wrapper is
+   * laid out by the composer's flex row — the textarea inside it is an ordinary
+   * block. Anything about width, growth or wrapping has to land here or it
+   * resolves against nothing.
+   */
+  readonly wrapperClassName?: string;
+  /** Sent prompts for ↑ recall, OLDEST first. Empty ⇒ the arrows never navigate. */
+  readonly history: readonly string[];
+}
+
+/**
+ * The composer field: the textarea and ↑/↓ recall over it.
+ *
+ * Both here because recall needs the field's ONE DOM node — it reads where the
+ * caret sits before it will claim an arrow. The MIC is the exception: it is a
+ * sibling control, and leaving it to the host is what keeps the row's order
+ * (field → mic → send) readable in one place.
+ *
+ * `ComposerInput` stays the lower seam and knows nothing about ladders, which is
+ * what keeps the editor swappable without retesting the racy half in
+ * `core/recall`.
+ */
+export function ComposerField({ className, wrapperClassName, history }: ComposerFieldProps) {
+  const composer = useComposer();
+  const events = useChatEvents();
+  const copy = useChatCopy().composer;
+  // A ref, not state: nothing renders from the node. It was state while an
+  // effect had to re-run once the node arrived — the vendor dictation bridge —
+  // and holding it as state now would re-render the field for nobody. `useRecall`
+  // wants the ref anyway: it reads the caret synchronously inside a keydown
+  // handler, where a state value is one render stale.
+  const nodeRef = useRef<HTMLTextAreaElement | null>(null);
+
+  const recall = useRecall({
+    entries: history,
+    input: nodeRef,
+    draft: composer.draft,
+    setText: composer.setText,
+  });
+
+  /*
+    A picked tool that still lacks its object REPLACES the standing advice.
+    "Ask anything" is exactly the line that stops being true once the user has
+    named an act, and a second line would turn one box into two.
+  */
+  const needed = unmetNeed(composer.draft);
+  const placeholder =
+    needed === "file" ? copy.needsFile : needed === "skill" ? copy.needsSkill : copy.placeholder;
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) =>
+    composerKeyDown(event, {
+      recall,
+      draftText: composer.draft.text,
+      // The whole draft, not its text: what went out is a draft, and narrowing
+      // it here would decide for every listener which of its fields matter.
+      onSending: () => events.emit("turn:sent", { draft: composer.draft }),
+    });
+
+  // `flex` rather than the default block. A block box puts its inline textarea
+  // on a TEXT BASELINE, which reserves descender space beneath it — measured
+  // 5px, making the wrapper 37px around a 32px field. The composer row aligns
+  // `items-end`, so it aligned that phantom gap and the text floated visibly
+  // above the buttons beside it.
+  return (
+    <div className={`relative flex min-w-0 flex-1 ${wrapperClassName ?? ""}`}>
+      <ComposerInput
+        ref={nodeRef}
+        label={copy.input}
+        /*
+          No placeholder while previewing. Both draw into the same empty field,
+          so they render ON TOP of each other — the preview and "type a
+          message…" overlapped into unreadable mush, which every DOM probe
+          reported as two correct elements and only a screenshot showed.
+
+          The preview wins because it is the live answer to what Tab does; the
+          placeholder is standing advice, and it returns the moment the walk ends.
+        */
+        placeholder={recall.preview === null ? placeholder : undefined}
+        className={className}
+        onKeyDown={onKeyDown}
+      />
+      {recall.preview === null ? null : (
+        /*
+          The recalled prompt, over the empty field rather than beside it.
+
+          Overlaid because recall only walks on an EMPTY buffer, so the line is
+          free — and because a preview in its own row would change the
+          composer's height on every press, which is the reflow this whole
+          design exists to remove.
+
+          `pointer-events-none` so the text underneath still takes the click:
+          the preview is something to read, not something to hit. The chip names
+          the key that commits; it is a LABEL, and the keyboard is the path.
+        */
+        <div
+          /*
+            Announced, not hidden. The preview is the ONLY signal of what Tab
+            will insert, so a screen reader user needs it more than a sighted
+            one, who can at least see the line. `polite` because it changes on
+            every arrow and must not interrupt.
+          */
+          role="status"
+          aria-live="polite"
+          className="pointer-events-none absolute inset-0 flex items-center gap-2 py-1"
+        >
+          {/*
+            `max-w-full` with no `flex-1`: the chip must sit BESIDE the text it
+            labels, not at the far edge of the field. A growing span pushed it
+            to the right margin, where it read as an unrelated control.
+          */}
+          <span className="text-muted-foreground min-w-0 max-w-full truncate leading-6">
+            {recall.preview}
+          </span>
+          {/*
+            The key's own name, not translated: `Tab` is what is printed on the
+            keycap in every locale this ships in, and translating it would name
+            a key the user cannot find. The surrounding `role="status"` carries
+            the meaning for a screen reader.
+          */}
+          <span className="rounded border border-border px-1 text-[10px] uppercase text-muted-foreground">
+            tab
+          </span>
+        </div>
+      )}
+    </div>
+  );
+}