@djangocfg/widget-chat 0.1.1

package/src/ui/renderers/tool.tsx

@@ -0,0 +1,176 @@
+import { ChevronDown } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+
+import { useChatCopy } from "../../i18n";
+import {
+  MessageContent,
+  SubagentThread,
+  ToolCall,
+  ToolCallHeader,
+  ToolCallInput,
+  ToolCallOutput,
+  type PartRenderProps,
+} from "../../primitives";
+import { ChatMessageFrame } from "../message";
+
+// Form adapted from vercel/ai-elements `packages/elements/src/tool.tsx`
+// (Apache-2.0, submodule @ 6a9d5b1). The header-as-trigger and the chevron are
+// theirs; the state dictionary, the disclosure rule and the reader's override
+// are ours — they collapse unconditionally, which renders a running call as a
+// stalled row.
+
+/**
+ * The four states of a tool call, as a person reads them.
+ *
+ * The protocol's own identifiers (`input-streaming`, `output-available`) are the
+ * reducer's vocabulary, not a label: a reader watching a turn sees
+ * "output-available" and has to translate it. This maps the four onto the
+ * dictionary's user-facing names.
+ */
+const TOOL_STATE_FIELD = {
+  "input-streaming": "inputStreaming",
+  "input-available": "inputAvailable",
+  "output-available": "outputAvailable",
+  "output-error": "outputError",
+} as const;
+
+/**
+ * Whether a call in this state deserves the reader's screen.
+ *
+ * Open while it RUNS: the part renders at `tool-input-start` so the reader sees
+ * which tool is working, and folded shut that is indistinguishable from stalled.
+ * Shut once it succeeded — one `tool_search` result buries the answer below it.
+ * An error stays open: short, and the reason the turn went as it did.
+ *
+ * The reference collapses unconditionally; that is the line not copied.
+ */
+export function opensItself(state: keyof typeof TOOL_STATE_FIELD): boolean {
+  return state !== "output-available";
+}
+
+/**
+ * Whether a reader's override still applies after the state moved.
+ *
+ * It survives everything except the transition that carries its own answer:
+ * arriving at a state auto-collapse governs. Without the exception a call opened
+ * mid-run would stay open forever; without the survival it would slam shut under
+ * the cursor the moment the result landed.
+ *
+ * A function rather than an effect body so the rule is testable without a DOM —
+ * this package ships no jsdom, and the rule is the fragile part, not the click.
+ */
+export function keepsOverride(
+  previous: keyof typeof TOOL_STATE_FIELD,
+  next: keyof typeof TOOL_STATE_FIELD,
+): boolean {
+  return previous === next;
+}
+
+export function ToolRenderer({ part }: PartRenderProps) {
+  const copy = useChatCopy().tool;
+  // Hooks run before the type guard: a renderer that returns early above a hook
+  // changes the hook order between parts and React unmounts the tree.
+  const [override, setOverride] = useState<boolean | null>(null);
+  const state = part.type === "tool" ? part.toolState.state : "output-available";
+  const auto = opensItself(state);
+
+  /*
+    A reader's click OUTLIVES the state change that follows it. Without this the
+    box opened mid-run slams shut when the result arrives. The ref tracks the
+    previous state so the override clears on that transition, not every render.
+  */
+  const previous = useRef(state);
+  useEffect(() => {
+    if (!keepsOverride(previous.current, state)) {
+      previous.current = state;
+      setOverride(null);
+    }
+  }, [state]);
+
+  if (part.type !== "tool") return null;
+
+  const open = override ?? auto;
+  const stateLabel = copy[TOOL_STATE_FIELD[state]];
+
+  return (
+    <ToolCall
+      part={part}
+      open={open}
+      className="chat-tool grid gap-1 rounded-md border border-border bg-muted/40 p-3 text-sm"
+    >
+      <ToolCallHeader>
+        {(p) => {
+          // A call is IN FLIGHT until its output or its error arrives.
+          const running =
+            p.toolState.state === "input-streaming" ||
+            p.toolState.state === "input-available";
+          const failed = p.toolState.state === "output-error";
+          // Sized and reserved in every state, so the label does not shift
+          // sideways when the call completes. A running call TUMBLES rather than
+          // pulses — the app's one vocabulary for "still going", shared with
+          // the turn mark and the recording glyph; a pulse says only "busy".
+          const dotTone = failed
+            ? "bg-destructive"
+            : running
+              ? "bg-primary"
+              : "bg-muted-foreground/40";
+          const dotClass = `chat-tool-dot shrink-0 ${dotTone}`;
+          const labelClass = `chat-tool-status text-xs ${failed ? "text-destructive" : "text-muted-foreground"}`;
+          return (
+            /*
+              A real button: keyboard-reachable, and `aria-expanded` carries the
+              state the decorative chevron only shows. `min-w-0` + `truncate` on
+              the name — it is data, and a long one pushes the chevron off the row.
+            */
+            <button
+              type="button"
+              className="chat-tool-header"
+              aria-expanded={open}
+              aria-label={open ? copy.collapse : copy.expand}
+              onClick={() => setOverride(!open)}
+            >
+              <span className="flex min-w-0 items-center gap-2">
+                <span aria-hidden className={dotClass} data-running={running || undefined} />
+                <strong className="truncate font-medium">{p.toolName}</strong>
+                <span className={labelClass}>{stateLabel}</span>
+              </span>
+              <ChevronDown className="chat-tool-chevron size-4 text-muted-foreground" aria-hidden />
+            </button>
+          );
+        }}
+      </ToolCallHeader>
+      {/* Absent, not hidden: a `hidden` subtree keeps the tall result in the
+          DOM, which is the weight this rule exists to remove. */}
+      {open ? (
+        <>
+          <ToolCallInput className="chat-tool-input text-muted-foreground font-mono text-xs" />
+          <ToolCallOutput className="chat-tool-output text-muted-foreground font-mono text-xs" />
+        </>
+      ) : null}
+      {/*
+        Renders null for an ordinary tool, so it costs a plain call nothing.
+        The nested thread inherits THESE renderers through the registry
+        context — a subagent's text and tools draw the same as an outer one
+        without registering anything.
+
+        The frame is supplied HERE rather than inside the thread because
+        `SubagentThread` is a primitive and the frame is `ui`: the layer rule
+        points the other way, and a primitive reaching up for it would invert
+        the arrow. Without this the nested turns render through a bare
+        `MessageContent` — no bubble, no role asymmetry, and none of the
+        selection containment every outer message has, so a drag inside a
+        delegation fuses two speakers.
+
+        Outside the disclosure: a delegation is the turn's substance, not the
+        call's arguments — folding it away hides a conversation behind a chevron.
+      */}
+      <SubagentThread className="mt-2 grid gap-2 border-l-2 border-border pl-3">
+        {(message) => (
+          <MessageContent message={message}>
+            {(msg, parts) => <ChatMessageFrame message={msg}>{parts}</ChatMessageFrame>}
+          </MessageContent>
+        )}
+      </SubagentThread>
+    </ToolCall>
+  );
+}

package/src/ui/turn-mark.tsx

@@ -0,0 +1,31 @@
+/**
+ * `waiting` — the turn is in flight and has produced nothing yet.
+ * `working` — text is arriving; the mark trails the last line.
+ *
+ * There is deliberately no "done". A resting mark under a finished reply is true
+ * of every reply ever sent, so it stacks up one per message and stops carrying
+ * information — the mark's whole job is telling the live turn from the settled
+ * ones.
+ */
+export type TurnMarkState = "waiting" | "working";
+
+export interface TurnMarkProps {
+  readonly state: TurnMarkState;
+  readonly className?: string;
+}
+
+/**
+ * One shape for the whole life of a turn: waiting, working, done.
+ *
+ * The states differ only in pace and weight — never in shape — so the end of an
+ * answer reads as the mark settling rather than as a new icon appearing. The
+ * motion and the sizing are in `styles/turn-mark.css`; this is only the element
+ * and its state attribute.
+ *
+ * `aria-hidden`, always. The transcript's own live region announces a turn's
+ * start and end; a mark that also spoke would double every announcement, and it
+ * carries no information the region does not already give.
+ */
+export function TurnMark({ state, className }: TurnMarkProps) {
+  return <span className={`turn-mark ${className ?? ""}`} data-state={state} aria-hidden />;
+}

package/src/utils/day-heading.ts

@@ -0,0 +1,46 @@
+import { startsNewDay } from "@djangocfg/widget-kit";
+
+/**
+ * Which day-label a transcript row opens, if it opens one at all.
+ *
+ * Only the CHOICE lives here. Calendar arithmetic and the absolute format are
+ * `lib-utils`, which owns display time for every surface — three surfaces had
+ * already spelled the clock three ways before that file existed, so a
+ * package-local date formatter is the one thing this must not become.
+ *
+ * "Today" and "yesterday" are product wording rather than a date format, which
+ * is why the choice is made here and the copy comes from this package. The
+ * `absolute` case carries no label: only the caller knows the reader's locale.
+ */
+export type DayHeading = "today" | "yesterday" | "absolute";
+
+/**
+ * The heading for `at`, or `undefined` when the row needs none.
+ *
+ * `previous` is the row immediately before; `undefined` means the first row.
+ *
+ * `now` is a parameter, not a clock read: it keeps the rule testable and lets
+ * one render pass label every row against a single instant, so a transcript
+ * cannot straddle midnight mid-list.
+ */
+export function dayHeadingFor(
+  at: number,
+  previous: number | undefined,
+  now: number,
+): DayHeading | undefined {
+  if (!startsNewDay(at, previous)) return undefined;
+  if (!startsNewDay(at, now)) {
+    // A "Today" opening the FIRST row separates nothing and names the day the
+    // reader is already in. Every other first-row label — "Yesterday", a date —
+    // carries information they do not have, so only this one is dropped.
+    return previous === undefined ? undefined : "today";
+  }
+  // Shifted from NOW, and by the DATE field rather than by 24h: "yesterday" is
+  // a statement about the reader's today, and a day is 23 or 25 hours long
+  // across a daylight-saving boundary, where subtracting a fixed span lands on
+  // the wrong date.
+  const yesterday = new Date(now);
+  yesterday.setDate(yesterday.getDate() - 1);
+  if (!startsNewDay(at, yesterday.getTime())) return "yesterday";
+  return "absolute";
+}

package/src/utils/error-message.ts

@@ -0,0 +1,10 @@
+/**
+ * The readable half of a thrown value.
+ *
+ * A `catch` binding is `unknown`, and a rejected fetch, a thrown string and a
+ * real `Error` all arrive through it. Rendering one directly prints
+ * `[object Object]` in the place a user reads to find out what went wrong.
+ */
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/utils/index.ts

@@ -0,0 +1,12 @@
+// Leaf mechanics: byte formatting, ids, clipboard, class merging, dates.
+//
+// May import: nothing local. This folder is a sink.
+//
+// Membership test, stated because this is where codebases dump everything: if
+// the helper's signature mentions a message, a part, a tool or a block, it is
+// NOT a util — it belongs in core.
+
+export { messageOf } from "./error-message";
+export { dayHeadingFor, type DayHeading } from "./day-heading";
+export { markdownToText, markdownToLine } from "./markdown-text";
+export type { MarkdownTextOptions, OpaqueBlock } from "./markdown-text";

package/src/utils/markdown-text.ts

@@ -0,0 +1,175 @@
+import { toString } from "mdast-util-to-string";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+
+/**
+ * Markdown → one line of plain text.
+ *
+ * For surfaces that show a message as a LABEL rather than rendering it: the
+ * roster preview, a notification body, a search hit, a chip title. The reader
+ * there wants to know WHAT arrived, not to read it, and raw `**bold**` or a
+ * table's pipes are this product's internal format leaking out.
+ *
+ * Built on the parser this package already renders with — `unified` +
+ * `remark-parse` + `remark-gfm`, the same stack `streamdown` runs. Not a regex
+ * pipeline: those do not merely miss constructs, they EDIT the text, and
+ * `file_name_here.txt` losing its underscores is worse than an asterisk
+ * surviving.
+ */
+
+/** A node's children are separate BLOCKS, so their text must not run together. */
+const BLOCK_CONTAINERS = new Set([
+  "root",
+  "blockquote",
+  "list",
+  "listItem",
+  "table",
+  "tableRow",
+  "footnoteDefinition",
+]);
+
+interface MdNode {
+  type: string;
+  children?: MdNode[];
+  checked?: boolean | null;
+  lang?: string | null;
+  alt?: string | null;
+  url?: string;
+}
+
+/**
+ * What a block becomes when its CONTENT is not worth reading in one line.
+ *
+ * A fenced block flattened to text reads as if the agent said it in prose:
+ * "const x = 1 const y = 2" is not something anyone wrote. A table is worse —
+ * headers and cells collapse into one stream and the structure that made it a
+ * table is gone. Both are frequent here, because this product is agents writing
+ * code.
+ *
+ * The glyph is a constant and never translated; the word beside it is supplied
+ * by the caller, which is what keeps this file free of an i18n dependency.
+ */
+export type OpaqueBlock = "code" | "table" | "image" | "formula";
+
+export interface MarkdownTextOptions {
+  /**
+   * Names for the blocks that collapse to a glyph. A key left out means that
+   * block flattens to its text as before — so a caller with no catalogue gets
+   * the old behaviour rather than a bare glyph with no word.
+   */
+  readonly blockLabels?: Partial<Record<OpaqueBlock, string>>;
+  /**
+   * Re-emit GFM task state as a glyph. A task item carries completion in
+   * `checked`, not in its text, so a preview that drops it says an unfinished
+   * item is done.
+   */
+  readonly taskMarks?: boolean;
+}
+
+const GLYPH: Record<OpaqueBlock, string> = {
+  code: "💻",
+  table: "📊",
+  image: "📷",
+  formula: "🔢",
+};
+
+/** `html` nodes are raw by design — mdast does not parse their inner markup.
+ *  These strings are message text, so a tag is something a human or an agent
+ *  typed: drop the tag, keep the words. NOT sanitisation — every consumer
+ *  renders the result as a text node. */
+const HTML_TAG = /<\/?[a-zA-Z][^>]*>/g;
+
+const collapse = (s: string): string =>
+  s.replace(HTML_TAG, "").replace(/\s+/g, " ").trim();
+
+const TO_STRING_OPTS = { includeImageAlt: true, includeHtml: true } as const;
+
+/** The opaque block this node is, or null when its text should be kept. */
+function opaqueKind(node: MdNode): OpaqueBlock | null {
+  if (node.type === "code") return "code";
+  if (node.type === "table") return "table";
+  if (node.type === "image") return "image";
+  if (node.type === "math" || node.type === "inlineMath") return "formula";
+  return null;
+}
+
+function flatten(node: MdNode, options: MarkdownTextOptions): string {
+  const labels = options.blockLabels ?? {};
+  const kind = opaqueKind(node);
+  if (kind !== null) {
+    const word = labels[kind];
+    // No label supplied: fall through to the text. A bare glyph with no word
+    // is less informative than the content it replaced.
+    if (word !== undefined) return `${GLYPH[kind]} ${word}`;
+  }
+
+  if (!BLOCK_CONTAINERS.has(node.type) || !node.children?.length) {
+    return toString(node as Parameters<typeof toString>[0], TO_STRING_OPTS);
+  }
+
+  const mark =
+    options.taskMarks && node.type === "listItem" && typeof node.checked === "boolean"
+      ? node.checked
+        ? "✓ "
+        : "◻ "
+      : "";
+
+  const parts: string[] = [];
+  for (const child of node.children) {
+    const text = flatten(child, options).trim();
+    if (text) parts.push(text);
+  }
+  // `toString` on a container concatenates blocks bare — two paragraphs come
+  // back as "donenext" — so the boundary is reintroduced here. One space is all
+  // a single line can express of it.
+  return mark + parts.join(" ");
+}
+
+const processor = unified().use(remarkParse).use(remarkGfm);
+
+function parse(markdown: string): MdNode | null {
+  try {
+    return processor.parse(markdown) as unknown as MdNode;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * All of the markdown's text on one collapsed line.
+ *
+ * A parser that throws must not blank the label: showing raw markdown is
+ * degraded, showing nothing loses the message entirely.
+ */
+export function markdownToText(
+  markdown: string,
+  options: MarkdownTextOptions = {},
+): string {
+  if (!markdown) return "";
+  const tree = parse(markdown);
+  if (tree === null) return collapse(markdown);
+  return collapse(flatten(tree, { taskMarks: true, ...options }));
+}
+
+/**
+ * The FIRST block that carries words — for a NAME (row title, chip, search hit).
+ *
+ * Returns '' when nothing is renderable (a lone fence with no label, a rule, a
+ * bare marker), so a caller can fall back to its own placeholder rather than
+ * printing punctuation as a name.
+ */
+export function markdownToLine(
+  markdown: string,
+  options: MarkdownTextOptions = {},
+): string {
+  if (!markdown) return "";
+  const tree = parse(markdown);
+  if (tree === null) return collapse(markdown.split("\n")[0] ?? "");
+  const opts = { taskMarks: false, ...options };
+  for (const block of tree.children ?? []) {
+    const line = collapse(flatten(block, opts));
+    if (line) return line;
+  }
+  return "";
+}

package/src/widgets/index.ts

@@ -0,0 +1,14 @@
+// Block renderers. A widget is a PURE FUNCTION of its `data`: no store, no
+// transcript, no streaming knowledge beyond an explicit prop. That is what
+// makes one testable without mounting a provider — and why a dependency with a
+// hidden context requirement (ui-core's Spinner needs i18n) cannot be used here.
+//
+// Each widget ships with a `read*` parser kept SEPARATE from the component, so
+// a malformed payload degrades to "render nothing" instead of throwing inside a
+// transcript row, and so the parsing is testable without a renderer.
+//
+// May import: core, utils, content.
+// May NOT import: store, primitives, composer, ui.
+
+export { MediaWidget } from "./media";
+export type { MediaRendererProps } from "./media";