@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/chat/ChatMarkdownSource.tsx

@@ -0,0 +1,203 @@
+"use client";
+/**
+ * The parse half of <ChatMarkdown>: a markdown *string* → the `.chat-md`
+ * element grammar. <ChatMarkdown> stays a directive-free, server-safe frame
+ * around pre-built children; this file is where the renderer lives, split out
+ * purely for the RSC boundary — react-markdown imports React hooks, so it
+ * cannot be pulled into a server component.
+ *
+ * Pipeline (remark → rehype → React, no raw HTML anywhere — React escapes text
+ * nodes and no rehype-raw is in the chain):
+ *   remark-gfm    tables, task lists, strikethrough, autolinks
+ *   remark-math   `$inline$` and `$$block$$` → math nodes
+ *   rehype-katex  math nodes → KaTeX HTML + MathML, *at parse time*
+ *
+ * Math is deliberately NOT a client-side pass: rehype-katex runs inside the
+ * unified pipeline, so the server markup already contains laid-out KaTeX and
+ * math reads correctly with JS disabled. Only mermaid — which needs a live DOM
+ * to measure text — defers to the client, and <ChatMermaidBlock> ships the
+ * diagram source as its own fallback for that window.
+ *
+ * Emits bare tags wherever chat-core.css already has a combinator, and reaches
+ * for a component only where an affordance is needed: fenced code gets
+ * <ChatCodeBlock>'s copy caption, a ```mermaid fence gets <ChatMermaidBlock>.
+ */
+import { isValidElement, type ReactNode } from "react";
+import type { Components, Options } from "react-markdown";
+import ReactMarkdown from "react-markdown";
+import rehypeKatex from "rehype-katex";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
+
+import { ChatCodeBlock } from "./ChatCodeBlock";
+import { ChatMermaidBlock } from "./ChatMermaidBlock";
+
+/** Minimal shape of the mdast nodes remarkDisplayDollars touches. */
+type MathNode = {
+  type: string;
+  children?: MathNode[];
+  position?: { start?: { offset?: number } };
+  data?: { hProperties?: { className?: string[] } };
+};
+
+/**
+ * remark-math's *flow* (display) construct needs the `$$` fences on lines of
+ * their own; `$$x$$` written on a single line therefore comes out as an
+ * `inlineMath` node and renders squeezed inline. Models write display math on
+ * one line constantly, so promote the double-dollar case: rehype-katex keys
+ * displayMode off the `math-display` class alone, so swapping the class is the
+ * whole fix. Single-dollar `$x$` is untouched and stays inline.
+ */
+function remarkDisplayDollars() {
+  return (tree: unknown, file: { value?: unknown }) => {
+    const src = String(file.value ?? "");
+    const walk = (node: MathNode): void => {
+      if (node.type === "inlineMath" && node.data?.hProperties) {
+        const at = node.position?.start?.offset;
+        if (typeof at === "number" && src.startsWith("$$", at)) {
+          node.data.hProperties.className = ["language-math", "math-display"];
+        }
+      }
+      for (const child of node.children ?? []) walk(child);
+    };
+    walk(tree as MathNode);
+  };
+}
+
+/**
+ * `singleDollarTextMath: false` is load-bearing, not a preference. remark-math
+ * defaults it to true, which makes any paragraph containing two `$` signs parse
+ * as inline math: "the starter plan is $29 and the team plan is $99" re-sets the
+ * prose between them as italic math with the spaces collapsed, and eats the
+ * second `$`. Currency is far commoner than inline math in a docs answer — and
+ * this renders for a quant-finance stack — so `$…$` stays literal.
+ *
+ * The cost, stated plainly: there is then NO inline math syntax. remark-math
+ * understands only `$`/`$$`, not `\(…\)`, so turning single-dollar off leaves
+ * block math (`$$…$$`, plus fenced math promoted by remarkDisplayDollars below)
+ * as the only route. That is the right trade for a docs chat — a mangled price
+ * is a wrong answer, a formula that needs its own line is a formatting nit — but
+ * it is a trade, not a free win. Revisit if inline notation ever outweighs
+ * currency on these surfaces.
+ */
+const remarkPlugins: Options["remarkPlugins"] = [
+  remarkGfm,
+  [remarkMath, { singleDollarTextMath: false }],
+  remarkDisplayDollars,
+];
+
+/**
+ * KaTeX options. `strict: "ignore"` keeps half-typed model output from filling
+ * the console with parse complaints. rehype-katex forces `throwOnError` itself
+ * (first strict, then a lenient retry, then a `.katex-error` span), and that
+ * last-resort span is inline-styled from `errorColor` — so it is handed a
+ * var() and the failed expression reads on the token palette in both themes
+ * instead of KaTeX's hard-coded red.
+ */
+const rehypePlugins: Options["rehypePlugins"] = [
+  // maxSize bounds \rule and friends. KaTeX names maxExpand and maxSize as the two
+  // knobs for untrusted input; maxExpand defaults to 1000 and holds, but maxSize
+  // defaults to Infinity, so `$$\rule{99999em}{99999em}$$` in a model answer
+  // inserts a ~1.6-million-pixel box and blows out the page scroll — inline math
+  // has no overflow container at all.
+  [rehypeKatex, { strict: "ignore", errorColor: "var(--down)", maxSize: 10 }],
+];
+
+/** Only http(s) links survive; anything else (javascript:, data:) renders as text. */
+function safeHref(href: string | undefined): string | undefined {
+  return href && (href.startsWith("https://") || href.startsWith("http://")) ? href : undefined;
+}
+
+/** Per-fence-language block-code hook. Called with the fence's language tag
+ * (lowercased, no `language-` prefix — empty string for a bare fence) and its
+ * raw code. Return a node to render instead of the default fenced-code/mermaid
+ * handling below, or `undefined` to fall through to it. Not consulted for
+ * inline code (a single backtick span) — only ever for a block fence, since
+ * that is the only shape a caller has needed an override for so far. */
+export type CodeBlockOverride = (lang: string, code: string) => ReactNode | undefined;
+
+function buildComponents(renderCodeBlock?: CodeBlockOverride): Components {
+  return {
+    a: ({ href, children }) => {
+      const safe = safeHref(href);
+      if (!safe) return <span>{children}</span>;
+      return (
+        <a href={safe} target="_blank" rel="noopener noreferrer">
+          {children}
+        </a>
+      );
+    },
+    // Headings are downshifted two levels: a model that opens an answer with `#`
+    // must not take the page's <h1>. Neither digichat /embed nor digithings.ai/chat
+    // has an <h1> of its own on the transcript route, so an un-downshifted h1 from
+    // streamed text becomes the document's top-level heading — a real outline and
+    // screen-reader defect, not a cosmetic one. The renderer this replaced
+    // (digichat-ui's MiniMarkdown) mapped h1→h3, h2→h4, h3→h5, h4→h6; that
+    // behaviour is preserved here rather than dropped.
+    h1: ({ children }) => <h3>{children}</h3>,
+    h2: ({ children }) => <h4>{children}</h4>,
+    h3: ({ children }) => <h5>{children}</h5>,
+    h4: ({ children }) => <h6>{children}</h6>,
+    // Tables scroll inside their own box rather than widening the turn.
+    table: ({ children }) => (
+      <div className="chat-md-table">
+        <table>{children}</table>
+      </div>
+    ),
+    // <ChatCodeBlock>/<ChatMermaidBlock> are <figure>s that bring their own
+    // <pre>, so the fence's wrapper is dropped and `code` decides the shape.
+    // Block code is decided HERE, at the <pre>, because that node is the only one
+    // that actually says "this is a block". Guessing from the child string instead
+    // — react-markdown >=9 dropped the `inline` prop — misread the commonest shape
+    // of model output: a bare one-line fence holding a single shell command has no
+    // language and no newline, so it rendered as inline <code>, losing its block
+    // styling and its copy button. Indented blocks lost their leading whitespace
+    // for the same reason.
+    pre: ({ children }) => {
+      const child = Array.isArray(children) ? children[0] : children;
+      if (isValidElement<{ className?: string; children?: ReactNode }>(child)) {
+        const raw = String(child.props.children ?? "").replace(/\n$/, "");
+        const lang = child.props.className?.replace(/^language-/, "").toLowerCase() ?? "";
+        if (renderCodeBlock) {
+          const overridden = renderCodeBlock(lang, raw);
+          if (overridden !== undefined) return overridden;
+        }
+        if (lang === "mermaid") return <ChatMermaidBlock code={raw} />;
+        return <ChatCodeBlock code={raw} lang={lang || undefined} />;
+      }
+      return <>{children}</>;
+    },
+    // Reached for inline code only; the `pre` branch above consumes block code
+    // without rendering its child. renderCodeBlock is deliberately NOT consulted
+    // here — every caller that has needed it so far (a fenced ```json chart
+    // envelope) only ever appears as a block, and applying it to inline spans
+    // too would risk misfiring on a short inline snippet that happens to share a
+    // language tag.
+    code: ({ className, children }) => {
+      const raw = String(children).replace(/\n$/, "");
+      const lang = className?.replace(/^language-/, "").toLowerCase() ?? "";
+      if (lang === "mermaid") return <ChatMermaidBlock code={raw} />;
+      if (lang) return <ChatCodeBlock code={raw} lang={lang} />;
+      return <code>{raw}</code>;
+    },
+  };
+}
+
+export type ChatMarkdownSourceProps = {
+  /** Markdown source. */
+  source: string;
+  /** See {@link CodeBlockOverride}. */
+  renderCodeBlock?: CodeBlockOverride;
+};
+
+export function ChatMarkdownSource({ source, renderCodeBlock }: ChatMarkdownSourceProps) {
+  return (
+    <ReactMarkdown
+      remarkPlugins={remarkPlugins}
+      rehypePlugins={rehypePlugins}
+      components={buildComponents(renderCodeBlock)}
+    >
+      {source}
+    </ReactMarkdown>
+  );
+}

package/src/components/chat/ChatMermaidBlock.tsx

@@ -0,0 +1,202 @@
+"use client";
+/**
+ * Mermaid diagram block for <ChatMarkdown> — a ```mermaid fence in streamed
+ * model output, drawn as an SVG in the token palette. Promoted up from
+ * digichat-ui's MermaidBlock so both chat surfaces draw the same diagram;
+ * this is the canon copy.
+ *
+ * Four things it owes the canon:
+ *
+ *  1. TOKENS, NEVER MERMAID'S PALETTE. Every built-in mermaid theme hard-codes
+ *     its own hues, so we run `theme: "base"` — the one palette that lets every
+ *     themeVariable through — and fill it from the *computed* value of
+ *     --ink / --surface / --hair / --accent read off this figure. Reading off
+ *     the figure rather than :root means a livery scope (`.accent-digichat`)
+ *     or a nested [data-theme] resolves exactly the colours the surrounding
+ *     turn resolves.
+ *  2. BOTH THEMES, LIVE. A MutationObserver on <html data-theme> re-reads the
+ *     tokens and re-renders, so flipping the theme toggle repaints the diagram
+ *     instead of leaving a dark graph on a paper surface.
+ *  3. NO JS, NO PROBLEM. The source ships inside a <pre> in the server markup
+ *     and is only replaced once mermaid has actually drawn something. A reader
+ *     without JS (or before hydration) sees the diagram source, never an empty
+ *     box; a parse failure keeps that same <pre> and never throws into the
+ *     transcript.
+ *  4. LAZY. mermaid is ~2.9 MB raw (parser + d3 + dagre + cytoscape), so it is
+ *     imported *inside* the effect — `await import("mermaid")` — and lands in
+ *     its own async chunk that no page pays for until a diagram appears.
+ *
+ * Safety: the source is attacker-influenceable model text, so it runs under
+ * `securityLevel: "strict"` — mermaid disables HTML labels, drops click
+ * handlers/`script` directives, and passes its own output through the DOMPurify
+ * copy it bundles before returning it. `suppressErrorRendering` additionally
+ * stops a malformed graph injecting mermaid's error-bomb SVG into the
+ * transcript. `mermaid.render()` therefore hands back an already-sanitized SVG
+ * *string*, which is why this is the one justified innerHTML on the chat
+ * surfaces (`htmlLabels: false` is set again below so a config merge cannot
+ * quietly re-enable raw label HTML). Motion lives in styles/chat-core.css
+ * behind a prefers-reduced-motion guard.
+ */
+import { useEffect, useId, useRef, useState } from "react";
+
+import { tokenThemeVariables } from "../diagrams/mermaid-theme";
+import { ChatCopyButton } from "./ChatCodeBlock";
+
+/**
+ * Quotes unquoted `[...]` flowchart node labels that contain characters the
+ * classic flowchart grammar cannot parse unquoted — `(`, `)`, `{`, `}` — so a
+ * model-written label like `C[List locations (Exchange, OneDrive, Blob)]`
+ * (a real observed failure: `Parse error ... got 'PS'` on the `(`) renders
+ * instead of falling back to source. Mermaid's own fix for this is quoting
+ * the label (`C["List locations (Exchange, OneDrive, Blob)"]`); this applies
+ * that mechanically rather than relying on the model to always remember to.
+ *
+ * Deliberately narrow: only touches `ID[label]` shapes (the commonest node
+ * form in model output), only when the label is not already quoted, and only
+ * when it contains one of the four unparseable characters — anything else
+ * (round `(...)`, diamond `{...}`, decorated shapes) is left alone rather than
+ * guessed at. The `[^\]"]*` capture excludes any label already containing a
+ * literal `"` from the match entirely — such a label is already ambiguous
+ * (unquoted-but-quoted), so this leaves it for mermaid's own parser to reject
+ * rather than guessing at an escape.
+ *
+ * A label starting with `[`, `(`, `/`, or `\` right after the node's opening
+ * `[` is bailed out on rather than sanitized: that is the four OTHER `[...]`
+ * bracket shapes mermaid overloads the same opening character for — subroutine
+ * `id[[text]]`, cylinder `id[(text)]`, parallelogram `id[/text/]`, trapezoid
+ * `id[\text\]`. The regex only looks for the FIRST `]`, so on a subroutine it
+ * stops at the shape's own inner `]]` instead of the outer one, and on a
+ * cylinder/parallelogram/trapezoid it captures the whole shape delimiter as
+ * part of the "label" and silently downgrades the node to a plain rectangle
+ * when it quotes it. Left untouched, these still fail the same way they did
+ * before this function existed (a genuinely paren-bearing cylinder label was
+ * already unparseable) — worse than not fixing it would be corrupting a shape
+ * that was rendering fine.
+ *
+ * Applied only to the copy handed to `mermaid.parse`/`render` — the `code`
+ * prop keeps the model's exact text for the copy button and the source
+ * fallback, so a reader never sees text the model didn't write.
+ */
+export function sanitizeMermaidLabels(code: string): string {
+  return code.replace(/(\b[\w-]+)\[([^\]"]*)\]/g, (whole, id: string, label: string) => {
+    if (/^[[(/\\]/.test(label)) return whole;
+    if (!/[(){}]/.test(label)) return whole;
+    return `${id}["${label}"]`;
+  });
+}
+
+/**
+ * The palette table moved to `../diagrams/mermaid-theme` when the
+ * architecture diagram became a second mermaid surface — one table, both
+ * diagrams, so a token added for one is a token added for both.
+ */
+
+export type ChatMermaidBlockProps = {
+  /** Diagram source — rendered verbatim as the no-JS / parse-failure fallback. */
+  code: string;
+  /** Caption language label. */
+  label?: string;
+  className?: string;
+};
+
+export function ChatMermaidBlock({ code, label = "mermaid", className }: ChatMermaidBlockProps) {
+  const [svg, setSvg] = useState("");
+  const [failed, setFailed] = useState(false);
+  const [showSource, setShowSource] = useState(false);
+  // Bumped by the [data-theme] observer to re-run the render effect.
+  const [themeTick, setThemeTick] = useState(0);
+  const hostRef = useRef<HTMLElement>(null);
+  // React 19's useId is «r0»-shaped; mermaid uses this verbatim as an SVG id
+  // AND inside generated CSS selectors, so strip everything non-alphanumeric.
+  const id = `chat-mermaid-${useId().replace(/[^a-zA-Z0-9]/g, "")}`;
+
+  useEffect(() => {
+    const observer = new MutationObserver(() => setThemeTick((n) => n + 1));
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-theme"],
+    });
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+    let cancelled = false;
+
+    void (async () => {
+      try {
+        const mermaid = (await import("mermaid")).default;
+        mermaid.initialize({
+          startOnLoad: false,
+          securityLevel: "strict",
+          suppressErrorRendering: true,
+          theme: "base",
+          themeVariables: tokenThemeVariables(host),
+          flowchart: { htmlLabels: false, useMaxWidth: true },
+          sequence: { useMaxWidth: true },
+        });
+        // Validate first: parse throws on a malformed graph without touching
+        // the document, so the failure path never leaves stray nodes behind.
+        const sanitized = sanitizeMermaidLabels(code);
+        await mermaid.parse(sanitized);
+        const rendered = await mermaid.render(id, sanitized);
+        if (cancelled) return;
+        setSvg(rendered.svg);
+        setFailed(false);
+      } catch {
+        if (cancelled) return;
+        setSvg("");
+        setFailed(true);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [code, id, themeTick]);
+
+  const drawn = Boolean(svg) && !failed;
+  const cls = ["chat-md-mermaid", className ?? ""].filter(Boolean).join(" ");
+
+  return (
+    <figure
+      ref={hostRef}
+      className={cls}
+      data-state={failed ? "source" : drawn ? "diagram" : "pending"}
+    >
+      <figcaption>
+        <span>{failed ? `${label} · source` : label}</span>
+        <span className="chat-md-mermaid-actions">
+          {drawn ? (
+            <button
+              type="button"
+              className="chat-md-copy"
+              aria-expanded={showSource}
+              aria-controls={`${id}-source`}
+              onClick={() => setShowSource((v) => !v)}
+            >
+              {showSource ? "hide source" : "view source"}
+            </button>
+          ) : null}
+          <ChatCopyButton text={code} ariaLabel="Copy diagram source" />
+        </span>
+      </figcaption>
+      {drawn ? (
+        <div
+          className="chat-md-mermaid-fig"
+          role="img"
+          aria-label={`${label} diagram`}
+          // mermaid.render returns a sanitized SVG string under
+          // securityLevel: "strict" — see the module docblock.
+          dangerouslySetInnerHTML={{ __html: svg }}
+        />
+      ) : null}
+      {!drawn || showSource ? (
+        <pre id={`${id}-source`}>
+          <code>{code}</code>
+        </pre>
+      ) : null}
+    </figure>
+  );
+}

package/src/components/chat/ChatMessage.tsx

@@ -0,0 +1,77 @@
+/**
+ * Chat message — one turn of the digichat grammar (canon §16): a marker
+ * column and a body on a `1.25rem minmax(0,1fr)` grid — the digichat
+ * .dc-term-row geometry, and the convergence target for digichat-ui's
+ * .dc-msg (marker ⇢ .dc-who, body ⇢ .dc-body). `>` marks the user, `▸` the
+ * assistant, `·` system asides; markers carry the accent and stay out of
+ * the a11y tree. `tone` picks the body ink explicitly (user turns default
+ * to full ink, the rest to soft; an emphasized answer passes tone="ink") so
+ * consumers never fight utility order. `streaming` appends the blink caret.
+ * The row is position:relative (chat-core.css) so hover affordances — a
+ * per-turn <ChatCopyButton>, digichat-ui's .dc-msg-copy — can pin to it.
+ */
+import type { ReactNode } from "react";
+import { ChatStreamCursor } from "./ChatStreamCursor";
+
+export type ChatRole = "user" | "assistant" | "system";
+
+export type ChatTone = "ink" | "soft" | "mute";
+
+const MARKERS: Record<ChatRole, string> = { user: ">", assistant: "▸", system: "·" };
+
+const TONES: Record<ChatTone, string> = {
+  ink: "text-ink",
+  soft: "text-ink-soft",
+  mute: "text-ink-mute",
+};
+
+export type ChatMessageProps = {
+  role: ChatRole;
+  /** Marker glyph override (digichat-ui marks assistant turns `·`). */
+  marker?: ReactNode;
+  /** Body ink; defaults to `ink` for user turns, `soft` otherwise. */
+  tone?: ChatTone;
+  /** Append the blinking stream caret after the body. */
+  streaming?: boolean;
+  children?: ReactNode;
+  className?: string;
+  bodyClassName?: string;
+};
+
+export function ChatMessage({
+  role,
+  marker,
+  tone,
+  streaming,
+  children,
+  className,
+  bodyClassName,
+}: ChatMessageProps) {
+  const bodyTone = TONES[tone ?? (role === "user" ? "ink" : "soft")];
+  const cls = [
+    `chat-msg chat-msg--${role}`,
+    "grid grid-cols-[1.25rem_minmax(0,1fr)] items-baseline gap-[0.55rem]",
+    className ?? "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  const bodyCls = [
+    "chat-msg-body min-w-0",
+    bodyTone,
+    role === "user" ? "whitespace-pre-wrap" : "",
+    bodyClassName ?? "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return (
+    <div className={cls}>
+      <span className="chat-msg-marker aui-msg-marker text-ink" aria-hidden="true">
+        {marker ?? MARKERS[role]}
+      </span>
+      <div className={bodyCls}>
+        {children}
+        {streaming ? <ChatStreamCursor /> : null}
+      </div>
+    </div>
+  );
+}