@djangocfg/widget-chat 0.1.1

package/src/ui/collapsible-row.tsx

@@ -0,0 +1,81 @@
+import type React from "react";
+
+import type { ChatMessage } from "../core/parts";
+import { useMessageIds } from "../store";
+import { CollapseTrigger, CollapsibleBody, useCollapse } from "./collapsible-body";
+import { ChatMessageFrame } from "./message";
+
+/**
+ * The row that owns its own collapse.
+ *
+ * Its own component because `useCollapse` is a hook and `ChatMessageView`'s
+ * render callback is not a component — and because the body and the toolbar are siblings
+ * inside the frame, so their shared state must live above both.
+ *
+ * Composed here rather than inside the frame, which subagent threads and the
+ * channel rows also use: a turn is bounded because it is long, and that is a
+ * fact about a TRANSCRIPT row.
+ */
+export function CollapsibleRow({
+  message,
+  parts,
+  className,
+  footer,
+}: {
+  readonly message: ChatMessage;
+  readonly parts: React.ReactNode;
+  readonly className?: string;
+  readonly footer?: React.ReactNode;
+}) {
+  // `parts` is the revision — it changes as a reply streams, which is what
+  // re-measures the height.
+  const collapse = useCollapse(
+    message.status.state === "streaming",
+    parts,
+    useMayCollapse(message.id),
+  );
+  return (
+    <ChatMessageFrame
+      message={message}
+      className={className}
+      // Both controls act on THIS turn, so they belong at the same end, next to
+      // each other. `footerEnd` is the opposite corner — filling it makes the
+      // frame justify the row apart, which threw the trigger 700px across the
+      // transcript to the far edge and left it looking absent beside the reply
+      // it opens.
+      footer={
+        // undefined when there is nothing to show: the frame keys the toolbar's
+        // very existence on this prop, and a fragment is never undefined — so
+        // building one unconditionally would reserve a 28px row under EVERY
+        // turn, including the short ones that have no controls at all.
+        footer === undefined && !collapse.showTrigger ? undefined : (
+          <>
+            {footer}
+            <CollapseTrigger collapse={collapse} />
+          </>
+        )
+      }
+    >
+      <CollapsibleBody collapse={collapse}>{parts}</CollapsibleBody>
+    </ChatMessageFrame>
+  );
+}
+
+/**
+ * Whether a turn is eligible to be collapsed at all.
+ *
+ * The newest turn is not: there is nothing below it to scroll past, so the
+ * height it saves buys the reader nothing, and folding the answer they are
+ * reading right now is the opposite of the point.
+ *
+ * Read at MOUNT only — `useCollapse` freezes it — so a turn that was last when
+ * it arrived stays open after the next message pushes it up. That is what keeps
+ * a positional rule from retroactively folding something mid-read.
+ *
+ * `ids` is reference-stable unless a message is added, so this subscription is
+ * as cheap as the transcript's own.
+ */
+function useMayCollapse(id: string): boolean {
+  const ids = useMessageIds();
+  return ids[ids.length - 1] !== id;
+}

package/src/ui/day-divider.tsx

@@ -0,0 +1,49 @@
+export interface DayDividerProps {
+  /** The day this heading opens, already resolved to the reader's wording. */
+  readonly label: string;
+  /** Machine-readable date (`YYYY-MM-DD`) for the `<time>` element. */
+  readonly dateTime: string;
+}
+
+/**
+ * The day heading between two turns.
+ *
+ * A `<time>` inside a separator, not a bare line of text: the label may read
+ * "Today", which names no date to anyone arriving at the transcript later —
+ * `dateTime` keeps the fact machine-readable however the copy is worded.
+ *
+ * `role="separator"` rather than `<hr>`: the element carries a visible label,
+ * and an `<hr>` with text inside is not a thing. The role announces the break
+ * and `aria-label` gives it the same words a sighted reader sees.
+ *
+ * Sticky, so the day a reader is inside stays named while they scroll through
+ * it. `top-0` against the scroller, which is the transcript's own element.
+ */
+export function DayDivider({ label, dateTime }: DayDividerProps) {
+  return (
+    <div
+      role="separator"
+      aria-label={label}
+      // Asymmetric on purpose: the heading belongs to the day BELOW it, so it
+      // sits closer to the turn it opens than to the one it ends. The generous
+      // top margin is what separates it from the previous message's action row,
+      // which reveals on hover — matching `py-3` there put a hidden control and
+      // a heading on the same line the moment a pointer arrived.
+      className="sticky top-0 z-10 mt-8 flex items-center gap-3 pt-2 pb-4"
+    >
+      <span className="bg-border h-px flex-1" aria-hidden />
+      {/*
+        The pill sits ON the line, so it needs its own ground or the rule runs
+        through the text. `bg-background` is the scroller's, which is what the
+        transcript paints.
+      */}
+      <time
+        dateTime={dateTime}
+        className="bg-background text-muted-foreground rounded-full px-2 text-xs"
+      >
+        {label}
+      </time>
+      <span className="bg-border h-px flex-1" aria-hidden />
+    </div>
+  );
+}

package/src/ui/index.ts

@@ -0,0 +1,54 @@
+// The styled layer — what a host actually mounts.
+//
+// This is the ONLY folder that knows ui-core and semantic tokens. Keeping it
+// separate is what makes the copy-in strategy possible at all: components
+// arrive from @sources as FORM, get re-tokened here, and never reach the
+// layers below.
+//
+// May import: everything below it.
+// May NOT be imported by: anything in this package.
+//
+// shadcn components are substituted with ui-core equivalents; four of those
+// substitutions are not mechanical.
+
+export { Chat } from "./chat";
+export type { ChatProps, ChatBody, ChatConversation, ChatSlots } from "./chat";
+export { ChatComposer } from "./chat-composer";
+export type { ChatComposerProps } from "./chat-composer";
+export { ChatTranscript } from "./chat-transcript";
+export type { ChatTranscriptProps } from "./chat-transcript";
+export { ChatSuggestions } from "./chat-suggestions";
+export type { ChatSuggestionsProps } from "./chat-suggestions";
+export { ChatMessageView, ChatMessageFrame, MessageProse } from "./message";
+export { CollapsibleBody } from "./collapsible-body";
+export { JumpToLatest } from "./jump-to-latest";
+export type { JumpToLatestProps } from "./jump-to-latest";
+export { MessageActions, messageCopyText, useCopyAction } from "./message-actions";
+export type {
+  MessageAction,
+  MessageActionsProps,
+  UseCopyActionOptions,
+} from "./message-actions";
+// Part renderers a host registers by name. Not a default registry: a host still
+// names them, because which part types it draws — and what it substitutes for
+// one — is its decision. There is no text renderer here on purpose; drawing
+// text needs a markdown component, and `./content` is a separate subpath so a
+// read-only host pays nothing for shiki and katex.
+//
+// `*Renderer`, never `*Part`: `core` already exports `DataPart`, `ToolPart` and
+// `ReasoningPart` as the part TYPES, and the root barrel re-exports both layers,
+// so matching names would make every one of them ambiguous.
+export { DataRenderer } from "./renderers/data";
+export { ReasoningRenderer } from "./renderers/reasoning";
+export { ToolRenderer } from "./renderers/tool";
+export { PendingIndicator } from "./pending";
+export type { PendingIndicatorProps } from "./pending";
+export { DayDivider } from "./day-divider";
+export type { DayDividerProps } from "./day-divider";
+export { TurnMark } from "./turn-mark";
+export type { TurnMarkProps, TurnMarkState } from "./turn-mark";
+export type { ChatMessageViewProps, ChatMessageFrameProps } from "./message";
+export { CollapseTrigger, useCollapse } from "./collapsible-body";
+export type { Collapse, CollapseState } from "./collapsible-body";
+export { LinkChip } from "./link-chip";
+export type { LinkChipProps } from "./link-chip";

package/src/ui/jump-to-latest.tsx

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+
+import { cn } from "@djangocfg/ui-core/lib";
+
+export interface JumpToLatestProps {
+  readonly onClick: () => void;
+  /** Accessible name. The button is icon-only, so nothing else names it. */
+  readonly label: string;
+  /**
+   * Replies that arrived since the reader left, or null when there is nothing
+   * honest to show. Null renders no badge — an empty one claims a count.
+   */
+  readonly missed?: number | null;
+  readonly icon: ReactNode;
+  readonly className?: string;
+}
+
+/**
+ * The return-to-bottom control.
+ *
+ * An overlay, unlike the message toolbar: it belongs to the viewport rather
+ * than to any message, so it must not sit in the transcript's flow and scroll
+ * away with the content it is offering to leave.
+ *
+ * Rendering is gated by `Transcript`, which shows this only while unpinned —
+ * this component must not decide its own visibility, or two owners would
+ * disagree about where the viewport is.
+ */
+export function JumpToLatest({ onClick, label, missed, icon, className }: JumpToLatestProps) {
+  const hasBadge = missed !== null && missed !== undefined && missed > 0;
+  // A pill when it carries a count, a disc when it does not — the shape says
+  // whether there is something to come back TO before the number is read.
+  const shape = hasBadge ? "h-8 ps-2 pe-3" : "size-8 justify-center";
+  const count = hasBadge ? (
+    <span className="text-xs font-medium tabular-nums">{missed}</span>
+  ) : null;
+  const classes = cn(
+    // Anchored to the zero-height strip Transcript places at the scroller's
+    // lower edge, so it floats just above the last message and clear of the
+    // composer below.
+    "absolute bottom-2 left-1/2 z-20 -translate-x-1/2",
+    "inline-flex items-center gap-1.5 rounded-full",
+    // Blurred backdrop rather than an opaque fill: the control sits over live
+    // text, and a solid disc reads as a hole punched in the reply.
+    "bg-background/70 shadow-md backdrop-blur-md",
+    "border border-border",
+    shape,
+    "text-muted-foreground transition-colors",
+    "hover:bg-secondary hover:text-foreground",
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+    className,
+  );
+
+  return (
+    <button type="button" onClick={onClick} aria-label={label} title={label} className={classes}>
+      {icon}
+      {count}
+    </button>
+  );
+}

package/src/ui/link-chip.tsx

@@ -0,0 +1,73 @@
+import type { ComponentProps } from "react";
+import { Globe } from "lucide-react";
+
+import { linkChipLabel } from "../core/links";
+
+/**
+ * The anchor's own props are accepted and forwarded so a wrapper that CLONES
+ * this element — a hover card trigger, a tooltip — can attach its handlers.
+ */
+export interface LinkChipProps extends ComponentProps<"a"> {
+  /** The href, already hardened by the renderer. */
+  href: string;
+}
+
+/**
+ * Inline chip rendered in place of a BARE url in a chat bubble.
+ *
+ * ## Why only a bare url
+ *
+ * `[the docs](https://…)` already has the label its author chose; boxing it
+ * adds weight and removes nothing. A bare url has no label at all, so the
+ * reader is left parsing the raw string — often longer than the sentence
+ * around it, and wrapping mid-url across two lines. That is what a chip fixes.
+ * The decision itself lives in `core/links/prose.ts`, so it is testable
+ * without a DOM.
+ *
+ * ## An anchor, not a button
+ *
+ * A link is a LINK: the browser already knows how to open one in a new tab,
+ * copy its address, or show it on hover, and every one of those is lost the
+ * moment a button stands in for it.
+ *
+ * ## The label is the short form, the href is the tooltip
+ *
+ * Same trade the file chip makes with a path. `linkChipLabel` keeps the domain
+ * whole and collapses the path's middle; the whole url stays one hover away.
+ *
+ * ## It does not take which side of the bubble it is on
+ *
+ * It used to, and nothing could supply the answer: the anchor is rendered from
+ * the host's memoized `components` object, which is built once per screen and
+ * cannot carry a per-message value without re-parsing every message. The
+ * stylesheet reads `data-role` off the message wrapper instead.
+ */
+export function LinkChip({ href, ...rest }: LinkChipProps) {
+  const label = linkChipLabel(href);
+
+  return (
+    <a
+      // FIRST, so the hardened `target`/`rel` below cannot be overwritten by a
+      // caller — but present at all so a cloning wrapper's handlers survive.
+      {...rest}
+      href={href}
+      // Size, colour, ground and the width ceiling come from `.chat-chip` and
+      // `.chat-link-chip` in markdown.css. This list carries STRUCTURE only.
+      //
+      // No `items-center`: the rule sets `align-items: baseline` so the LABEL
+      // donates the chip's baseline, and a utility would win over it.
+      className="chat-chip chat-link-chip inline-flex h-auto min-w-0 gap-1 align-baseline whitespace-nowrap"
+      // The label collapses the url's middle, so the whole address is visible
+      // NOWHERE else — this is both the tooltip and the accessible name. A
+      // wrapper showing it more richly passes `title=""` to suppress it.
+      title={rest.title ?? href}
+      target="_blank"
+      // `noreferrer` implies `noopener`; both are stated because the pair is
+      // what keeps the opened page from reaching back through `window.opener`.
+      rel="noreferrer noopener"
+    >
+      <Globe aria-hidden />
+      <span className="truncate">{label}</span>
+    </a>
+  );
+}

package/src/ui/message-actions.tsx

@@ -0,0 +1,163 @@
+import { useCallback, useState, type ReactNode } from "react";
+
+import { cn } from "@djangocfg/ui-core/lib";
+
+import { isTextPart, type ChatMessage } from "../core/parts";
+import { ChatTooltip } from "../primitives/tooltip";
+
+/**
+ * The per-message action row: the package owns placement, reveal and a11y; the
+ * host owns which actions exist. Hence a list of descriptors, not `showRetry` /
+ * `showCopy` flags — a flag per feature cannot express an action this package
+ * has never heard of, and a host with no retry lane gets a correct one-button
+ * row instead of a broken three-button one.
+ */
+
+export interface MessageAction {
+  /** Stable key. Also the `data-action` value, which is what a story asserts on. */
+  readonly id: string;
+  /** Accessible name. Required — the row is icon-only, so nothing else names it. */
+  readonly label: string;
+  readonly icon: ReactNode;
+  readonly onSelect: () => void;
+  readonly disabled?: boolean;
+}
+
+export interface MessageActionsProps {
+  readonly message: ChatMessage;
+  readonly actions: readonly MessageAction[];
+  readonly className?: string;
+}
+
+/**
+ * In flow and always present, faint until the message is hovered or focused.
+ *
+ * Not an overlay: a row that floats over the transcript does not read as
+ * belonging to the message it acts on. It holds its place instead, and the
+ * height it takes is given back by pulling the NEXT message up (`ChatMessage-
+ * Frame` sets a negative top margin on the following row), so the transcript
+ * keeps the spacing it had before actions existed.
+ *
+ * Faint rather than invisible: at zero the control cannot be discovered without
+ * hovering every message, and a first-time reader never learns it is there.
+ * `focus-within` is the keyboard half — hover alone leaves it unreachable.
+ */
+export function MessageActions({ message, actions, className }: MessageActionsProps) {
+  const isUser = message.role === "user";
+  if (actions.length === 0) return null;
+
+  return (
+    <div
+      role="group"
+      aria-label={message.role}
+      className={cn(
+        "flex h-7 items-center gap-0.5",
+        // Aligned with what it acts on: under the reply on the left, under the
+        // bubble on the right.
+        isUser ? "justify-end" : "justify-start",
+        "opacity-10 transition-opacity",
+        "group-hover:opacity-100 group-focus-within:opacity-100",
+        className,
+      )}
+    >
+      {actions.map((action) => (
+        // The design system's tooltip, not the native `title`: the OS bubble
+        // ignores the theme, waits ~1s, and would be the one control in the
+        // host still using it. `label` doubles as the `aria-label`, which
+        // Radix links with `aria-describedby` rather than repeating.
+        //
+        // A DISABLED button fires no pointer events, so its tooltip never
+        // opens — the same known limit the composer's Send carries. The name
+        // stays reachable through `aria-label`.
+        <ChatTooltip key={action.id} label={action.label}>
+          <button
+            type="button"
+            data-action={action.id}
+            aria-label={action.label}
+            disabled={action.disabled}
+            onClick={action.onSelect}
+            className={cn(
+              "inline-flex h-7 w-7 items-center justify-center rounded-md",
+              "text-muted-foreground transition-colors",
+              "hover:bg-secondary hover:text-foreground",
+              "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              "disabled:pointer-events-none disabled:opacity-50",
+            )}
+          >
+            {action.icon}
+          </button>
+        </ChatTooltip>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Text parts only. Reasoning collapses by default and is not the answer a
+ * reader means by "copy this"; a tool call's rendered form is not its data, so
+ * copying a diff card as JSON is worse than offering nothing.
+ */
+export function messageCopyText(message: ChatMessage): string {
+  return message.parts
+    .filter(isTextPart)
+    .map((part) => part.text)
+    .join("\n\n")
+    .trim();
+}
+
+export interface UseCopyActionOptions {
+  readonly label: string;
+  readonly copiedLabel: string;
+  readonly icon: ReactNode;
+  readonly copiedIcon: ReactNode;
+  /**
+   * Injected so this package acquires no clipboard implementation. Must return
+   * false rather than throw when the write did not land — the confirmed state
+   * reads it.
+   */
+  readonly write: (text: string) => Promise<boolean>;
+  /** How long the confirmed state holds, in ms. */
+  readonly confirmMs?: number;
+}
+
+/**
+ * `undefined` when the turn has no text, so a tool-only turn offers no control
+ * rather than one that writes an empty string. The icon flips only on a real
+ * success — a check after a failed write is a lie the user acts on.
+ *
+ * Also `undefined` while the turn is still STREAMING. Text length alone was the
+ * whole condition, and a streaming turn has text from its first token, so the
+ * control appeared over a half-written answer and copied whatever had arrived
+ * by the instant of the click. Worse, it appeared over a turn showing only
+ * "Thinking" — a reasoning part carries no text, so the row was offering to
+ * copy nothing at all.
+ *
+ * `interrupted` and `failed` DO get the control: both are final, their text is
+ * whatever the turn managed to produce, and that is exactly what a reader wants
+ * to keep. Only `streaming` is a moving target.
+ */
+export function useCopyAction(
+  message: ChatMessage,
+  options: UseCopyActionOptions,
+): MessageAction | undefined {
+  const { label, copiedLabel, icon, copiedIcon, write, confirmMs = 1500 } = options;
+  const [copied, setCopied] = useState(false);
+  const text = messageCopyText(message);
+
+  const onSelect = useCallback(() => {
+    void write(text).then((ok) => {
+      if (!ok) return;
+      setCopied(true);
+      setTimeout(() => setCopied(false), confirmMs);
+    });
+  }, [write, text, confirmMs]);
+
+  if (text.length === 0) return undefined;
+  if (message.status.state === "streaming") return undefined;
+  return {
+    id: "copy",
+    label: copied ? copiedLabel : label,
+    icon: copied ? copiedIcon : icon,
+    onSelect,
+  };
+}

package/src/ui/message-quote.tsx

@@ -0,0 +1,47 @@
+import type { ChatMessage } from "../core/parts";
+import { messageCopyText } from "./message-actions";
+import { useChatCopy } from "../i18n";
+import { useChatSurfaces, useMessage } from "../store";
+
+/**
+ * The message a turn answers, above its own text.
+ *
+ * Renders nothing when this turn answers nothing, or when the answered message
+ * is not in the loaded transcript — a quote naming a row the reader cannot
+ * scroll to would describe something that is not there. History is paged, so
+ * that is an ordinary state rather than an error.
+ *
+ * Resolved from the store, like the composer's chip: one index, so the quote a
+ * sender saw and the quote a reader sees cannot disagree.
+ */
+export function MessageQuote({ message }: { readonly message: ChatMessage }) {
+  const target = useMessage(message.replyTo ?? "");
+  const surfaces = useChatSurfaces();
+  const copy = useChatCopy().message;
+  if (message.replyTo === undefined || target === undefined) return null;
+
+  const quoted = message.replyTo;
+  return (
+    <button
+      type="button"
+      onClick={() => surfaces?.revealMessage(quoted)}
+      aria-label={copy.jumpToQuoted}
+      // `w-fit` with a cap, not `w-full`: the quote belongs to ONE bubble, and a
+      // full-column bar above a short right-aligned turn reads as a divider for
+      // the whole transcript. The cap matches the user bubble's own measure so a
+      // long quote wraps where the bubble would.
+      //
+      // `ms-auto` on a user turn puts it over the bubble it belongs to. The row
+      // below is aligned by the frame's own `items-end`, which this element sits
+      // outside of, so it places itself.
+      className={`chat-quote hover:bg-muted/50 mb-1 flex w-fit max-w-[52ch] items-center gap-2 rounded px-1 py-0.5 text-left text-xs${
+        message.role === "user" ? " ms-auto" : ""
+      }`}
+    >
+      <span className="bg-primary/60 h-4 w-0.5 shrink-0 rounded-full" aria-hidden />
+      <span className="text-muted-foreground min-w-0 truncate">
+        {messageCopyText(target)}
+      </span>
+    </button>
+  );
+}