@djangocfg/widget-chat 0.1.1

package/src/primitives/stories-harness.tsx

@@ -0,0 +1,118 @@
+import { useEffect } from "react";
+
+import type { StreamChunk } from "../core/chunks";
+import type { ChatMessage } from "../core/parts";
+import type { PartRenderProps } from "./part-registry";
+import { ChatProvider, useChatStore } from "../store";
+import { mockAdapter } from "../testing/mock-adapter";
+import { Message } from "./message";
+import { PartRegistryProvider, type PartRegistry } from "./part-registry";
+import { Transcript } from "./transcript";
+// From `ui/`, which primitives may not import — allowed here because the
+// workbench never ships (`layers.test.ts` exempts it by name). Both are styled,
+// and the tool renderer is the SHIPPED one, so a story cannot pass against a
+// card the product does not draw.
+import { PendingIndicator } from "../ui/pending";
+import { ToolRenderer } from "../ui/renderers/tool";
+
+/**
+ * The workbench the transcript stories share.
+ *
+ * One set of renderers, not one per story file: a second copy would let a
+ * story pass against renderers nothing ships, which is the failure mode a
+ * workbench exists to prevent.
+ *
+ * Light and dark come from the preview's `withThemeByClassName` decorator and
+ * its toolbar (`.storybook/preview.tsx`). Do NOT add a switcher or duplicate a
+ * story per theme; semantic token classes make one story set correct in both.
+ */
+
+const bare = "grid gap-3 p-4 text-foreground";
+
+function TextPart({ part }: PartRenderProps) {
+  if (part.type !== "text") return null;
+  return <p className="m-0 whitespace-pre-wrap">{part.text}</p>;
+}
+
+function ReasoningPart({ part }: PartRenderProps) {
+  if (part.type !== "reasoning") return null;
+  return (
+    <details>
+      <summary className="text-muted-foreground">Thinking</summary>
+      <p className="m-0 text-muted-foreground">{part.text}</p>
+    </details>
+  );
+}
+
+/**
+ * Tool calls render through the SHIPPED renderer, not a copy.
+ *
+ * This workbench used to keep its own: a pulsing dot, no disclosure, no running
+ * border. Every story passed while showing a screen the product no longer had —
+ * the exact failure a workbench exists to prevent. `ui/` is reachable here
+ * because `layers.test.ts` exempts this file by name, the same allowance
+ * `PendingIndicator` already uses.
+ *
+ * The subagent thread comes with it: `PartRegistryProvider` is a context, so a
+ * nested tool resolves through this same registry with nothing re-registered.
+ */
+const renderers: PartRegistry = {
+  text: TextPart,
+  reasoning: ReasoningPart,
+  tool: ToolRenderer,
+};
+
+export interface HarnessProps {
+  readonly script: readonly StreamChunk[];
+  readonly delayMs?: number;
+  readonly prompt?: string;
+  /**
+   * Seed the transcript instead of streaming it. `ToolPart.messages` has no
+   * chunk in the wire vocabulary — an adapter that ran a subagent populates it
+   * directly — so `store.load()` is the only honest way to reach that state.
+   */
+  readonly history?: readonly ChatMessage[];
+}
+
+/** Drives one turn on mount so a story shows a conversation, not an empty box. */
+export function Harness({ script, delayMs = 40, prompt = "Show me the log", history }: HarnessProps) {
+  return (
+    <ChatProvider adapter={mockAdapter({ script, delayMs })}>
+      <PartRegistryProvider renderers={renderers}>
+        {history === undefined ? <AutoSend prompt={prompt} /> : <LoadHistory messages={history} />}
+        <Transcript
+          empty={<p className="text-muted-foreground">No messages yet.</p>}
+          className="chat-transcript bg-background"
+          pending={() => (
+            <PendingIndicator
+              className="text-muted-foreground flex items-center gap-2 py-3 text-sm"
+              label="Thinking"
+            />
+          )}
+        >
+          {(id) => (
+            <div className={bare}>
+              <Message id={id} />
+            </div>
+          )}
+        </Transcript>
+      </PartRegistryProvider>
+    </ChatProvider>
+  );
+}
+
+function AutoSend({ prompt }: { readonly prompt: string }) {
+  const store = useChatStore();
+  useEffect(() => {
+    void store.send({ text: prompt });
+  }, [store, prompt]);
+  return null;
+}
+
+function LoadHistory({ messages }: { readonly messages: readonly ChatMessage[] }) {
+  const store = useChatStore();
+  useEffect(() => {
+    store.load(messages);
+  }, [store, messages]);
+  return null;
+}

package/src/primitives/suggestions.tsx

@@ -0,0 +1,112 @@
+import type { ReactNode } from "react";
+
+import type { ChatSuggestion } from "../core/capabilities";
+import { emptyDraft } from "../core/outbound";
+import { useCapabilities, useChatStore, useHistoryLoaded, useMessageIds } from "../store";
+import { useTurnActivity } from "./use-turn-activity";
+
+export interface SuggestionsProps {
+  /**
+   * Render one row. Called with the suggestion and the handler that sends it.
+   *
+   * A render prop rather than a built-in button, for the reason `jumpToLatest`
+   * is one: the chrome and the icon are the host's, and this package ships no
+   * icon library. A primitive that decides its own chrome is how a primitive
+   * turns back into 83 props.
+   */
+  readonly children: (props: SuggestionRenderProps) => ReactNode;
+  /**
+   * Wrapped around the rows. Absent ⇒ they render as siblings, which is what a
+   * host supplying its own container wants.
+   */
+  readonly className?: string;
+  /**
+   * The list's accessible name. Copy is the host's — no locales here.
+   *
+   * Without it the group is an unnamed landmark and a screen reader announces
+   * only "list", with nothing to say what these rows start.
+   */
+  readonly label?: string;
+}
+
+export interface SuggestionRenderProps {
+  readonly suggestion: ChatSuggestion;
+  /** Send this suggestion's prompt. Already bound; the row only calls it. */
+  readonly onSelect: () => void;
+}
+
+/**
+ * The starter rows for an empty room.
+ *
+ * Renders NOTHING when the capability is absent, the list is empty, or the room
+ * is not empty — never an empty container, which would still spend the parent's
+ * `gap` and push the composer down.
+ *
+ * It owns the emptiness test itself, so every mount point agrees on it.
+ */
+/**
+ * Whether starter rows will render right now.
+ *
+ * Exported because the transcript's "no messages yet" line is a FALLBACK for
+ * exactly this: when rows are offered they already say the room is empty and
+ * name what to do, so the line becomes a caption for the obvious. One predicate,
+ * two readers, so the two can never both appear or both vanish.
+ */
+export function useHasSuggestions(): boolean {
+  const { suggestions } = useCapabilities();
+  const ids = useMessageIds();
+  const historyLoaded = useHistoryLoaded();
+  const activity = useTurnActivity();
+
+  // The two suppressions `<Transcript>` applies to its own empty state, both
+  // bought with incidents: a first turn sent into a fresh room is not an empty
+  // room, and an unanswered fetch is not either — a 90-message room would
+  // otherwise open on starter prompts while history loads.
+  const roomIsEmpty = ids.length === 0 && historyLoaded && activity === null;
+
+  return roomIsEmpty && (suggestions?.items.length ?? 0) > 0;
+}
+
+export function Suggestions({ children, className, label }: SuggestionsProps) {
+  const { suggestions } = useCapabilities();
+  const store = useChatStore();
+  const show = useHasSuggestions();
+  const items = suggestions?.items ?? [];
+
+  if (!show || suggestions === undefined) return null;
+
+  const { onPick, replyLanguage } = suggestions;
+  // `store.send`, not the adapter: it queues behind a running turn and mints the
+  // optimistic row, so a picked row and a typed message are one event
+  // downstream. `prompt`, never `title` — the title is an abbreviation.
+  //
+  // The language sentence is appended, not hidden: whatever is sent is what the
+  // transcript stores forever, and a hidden marker would need every surface
+  // (web, messengers, search, export) to strip it and keep stripping it.
+  const pick = (suggestion: ChatSuggestion) => {
+    const text = replyLanguage
+      ? `${suggestion.prompt} Reply in ${replyLanguage}.`
+      : suggestion.prompt;
+    void store.send({ ...emptyDraft, text });
+    onPick?.(suggestion);
+  };
+
+  // Built here so the JSX below only lays out values that exist: an inline
+  // `() => pick(s)` is a new function per row per render.
+  const rows = items.map((suggestion) => ({
+    id: suggestion.id,
+    node: children({ suggestion, onSelect: () => pick(suggestion) }),
+  }));
+
+  // `listitem` on a wrapper, not on the host's row: a button carrying both roles
+  // loses one of them depending on the reader.
+  return (
+    <div className={className} role="list" aria-label={label}>
+      {rows.map((row) => (
+        <div key={row.id} role="listitem" className="contents">
+          {row.node}
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/primitives/tool-call.tsx

@@ -0,0 +1,145 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+import { subagentMessages, type ChatMessage, type ToolPart } from "../core/parts";
+import { MessageContent } from "./message";
+
+/**
+ * A tool call, as composed parts.
+ *
+ * The root takes `part` and `children` and nothing else. Everything that would
+ * have been `showInput` / `showOutput` / `inputLabel` is a component the host
+ * either renders or does not — AI Elements' shape, and the concrete cure for
+ * "a boolean prop is a component someone declined to write".
+ */
+
+const ToolPartContext = createContext<ToolPart | null>(null);
+
+function useToolPart(): ToolPart {
+  const part = useContext(ToolPartContext);
+  if (part === null) throw new Error("tool-call parts must render inside <ToolCall>");
+  return part;
+}
+
+export interface ToolCallProps {
+  readonly part: ToolPart;
+  readonly children: ReactNode;
+  readonly className?: string;
+  /**
+   * Disclosure state, as DATA on the root. The host owns the rule; this only
+   * publishes the answer, so a stylesheet can turn the chevron without the
+   * primitive knowing a chevron exists.
+   */
+  readonly open?: boolean;
+}
+
+export function ToolCall({ part, children, className, open }: ToolCallProps) {
+  return (
+    <ToolPartContext.Provider value={part}>
+      <div
+        className={className}
+        data-tool={part.toolName}
+        data-state={part.toolState.state}
+        // Absent rather than `false`: CSS selects on presence, and
+        // `data-open="false"` matches `[data-open]` just as well as "true".
+        data-open={open === true ? "" : undefined}
+      >
+        {children}
+      </div>
+    </ToolPartContext.Provider>
+  );
+}
+
+export interface ToolCallHeaderProps {
+  readonly className?: string;
+  /** Receives the live state so a host can label it without reading context. */
+  readonly children?: (part: ToolPart) => ReactNode;
+}
+
+export function ToolCallHeader({ className, children }: ToolCallHeaderProps) {
+  const part = useToolPart();
+  return (
+    <div className={className}>{children === undefined ? part.toolName : children(part)}</div>
+  );
+}
+
+export interface ToolCallInputProps {
+  readonly className?: string;
+  readonly children?: (input: unknown, streaming: boolean) => ReactNode;
+}
+
+/**
+ * Arguments, including while they stream in.
+ *
+ * During `input-streaming` the payload is a PARTIAL JSON string, not an object.
+ * Handing a host `JSON.parse`d garbage — or throwing — is how a tool card
+ * breaks the whole transcript mid-turn, so the raw text is passed through with
+ * `streaming` true and the host decides what to show.
+ */
+export function ToolCallInput({ className, children }: ToolCallInputProps) {
+  const { toolState } = useToolPart();
+  const streaming = toolState.state === "input-streaming";
+  const input = streaming ? toolState.inputText : toolState.input;
+  if (children !== undefined) return <div className={className}>{children(input, streaming)}</div>;
+  return <div className={className}>{typeof input === "string" ? input : JSON.stringify(input)}</div>;
+}
+
+export interface ToolCallOutputProps {
+  readonly className?: string;
+  readonly children?: (output: unknown) => ReactNode;
+  /** Rendered instead when the call failed. Absent ⇒ the error text is shown. */
+  readonly error?: (message: string) => ReactNode;
+}
+
+export function ToolCallOutput({ className, children, error }: ToolCallOutputProps) {
+  const { toolState } = useToolPart();
+
+  if (toolState.state === "output-error") {
+    return (
+      <div className={className} data-error="">
+        {error === undefined ? toolState.error : error(toolState.error)}
+      </div>
+    );
+  }
+  // Nothing to show yet is NOT an empty output: rendering an empty box while a
+  // tool runs reads as "it returned nothing".
+  if (toolState.state !== "output-available") return null;
+
+  const { output } = toolState;
+  if (children !== undefined) return <div className={className}>{children(output)}</div>;
+  return (
+    <div className={className}>{typeof output === "string" ? output : JSON.stringify(output)}</div>
+  );
+}
+
+export interface SubagentThreadProps {
+  readonly className?: string;
+  readonly children?: (message: ChatMessage) => ReactNode;
+}
+
+/**
+ * The subagent's own conversation, nested and read-only.
+ *
+ * Read-only is a property of the data, not a flag: these messages live inside a
+ * completed tool call, so there is no composer and nothing to send. Renders
+ * nothing when the tool ran no subagent, which is the ordinary case.
+ *
+ * Part renderers are inherited from the enclosing registry — see
+ * `part-registry.tsx`. A nested thread that had to re-register them would
+ * silently lose whichever the host forgot.
+ */
+export function SubagentThread({ className, children }: SubagentThreadProps) {
+  const messages = subagentMessages(useToolPart());
+  if (messages === undefined) return null;
+
+  return (
+    <div className={className} data-subagent="">
+      {messages.map((message) =>
+        children === undefined ? (
+          <MessageContent key={message.id} message={message} />
+        ) : (
+          <div key={message.id}>{children(message)}</div>
+        ),
+      )}
+    </div>
+  );
+}

package/src/primitives/tooltip.tsx

@@ -0,0 +1,48 @@
+import type { ReactElement, ReactNode } from "react";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@djangocfg/ui-core";
+
+export interface ChatTooltipProps {
+  /** The hover copy. Falsy → the child renders BARE, keeping `asChild` chains intact. */
+  readonly label?: ReactNode;
+  readonly children: ReactNode;
+  readonly side?: "top" | "bottom" | "left" | "right";
+  readonly align?: "start" | "center" | "end";
+}
+
+/**
+ * Hover name for one icon-only control in this package.
+ *
+ * The ordinary design-system Tooltip, not the status bar's: that wrapper is
+ * shaped for a live multi-line readout, and importing it here would couple a
+ * chat control to another surface's presentation.
+ *
+ * In `primitives` rather than beside the composer because two surfaces use it —
+ * the composer row and the per-message action row. A control that names itself
+ * on hover is not a composer idea, and leaving it under `composer/` would make
+ * the message row import a component whose name says it belongs elsewhere.
+ *
+ * The provider is mounted app-wide, so this adds none — a second one would give
+ * a row its own delay and skip behaviour.
+ *
+ * Content MIRRORS each control's `aria-label`. Radix links it with
+ * `aria-describedby`, so the name is not doubled; a different sentence here
+ * would be the only version a pointer user ever reads.
+ */
+export function ChatTooltip({
+  label,
+  children,
+  side = "top",
+  align = "center",
+}: ChatTooltipProps): ReactElement {
+  // Bare, never a Fragment: an outer `PopoverTrigger asChild` clones a single
+  // element's ref and a Fragment breaks that clone.
+  if (!label) return children as ReactElement;
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{children}</TooltipTrigger>
+      <TooltipContent side={side} align={align} className="max-w-64">
+        {label}
+      </TooltipContent>
+    </Tooltip>
+  );
+}