@elabs-ai/components-ai 4.0.0 → 4.2.0

package/src/tool.test.tsx

@@ -61,3 +61,68 @@ describe("ToolOutput isStreaming (#269, loading-states.md)", () => {
     expect(container).toBeEmptyDOMElement();
   });
 });
+
+// A tool that returns a count of 0, a boolean check of false, or an empty
+// string is a REAL, defined result — only `undefined` means "no output yet".
+// The old `!(output || errorText || isStreaming)` guard treated all three as
+// "nothing to show" and rendered null outright.
+describe("ToolOutput — defined-but-falsy output renders (review #1)", () => {
+  it("renders a numeric 0 result instead of returning null", () => {
+    render(<ToolOutput output={0} errorText={undefined} />);
+    expect(screen.getByText("Result")).toBeInTheDocument();
+    expect(screen.getByText("0")).toBeInTheDocument();
+  });
+
+  it("renders a boolean false result instead of returning null", () => {
+    const { container } = render(<ToolOutput output={false} errorText={undefined} />);
+    expect(screen.getByText("Result")).toBeInTheDocument();
+    expect(container.querySelector('[data-language="json"]')).not.toBeNull();
+  });
+
+  it("renders an empty-string result (not the pending skeleton, not null)", () => {
+    const { container } = render(<ToolOutput output="" errorText={undefined} />);
+    expect(screen.getByText("Result")).toBeInTheDocument();
+    expect(container.querySelector('[role="status"]')).toBeNull();
+  });
+});
+
+describe("ToolOutput — string output renders as plain text, not forced JSON (review #1)", () => {
+  it("renders a plain-text (non-JSON) string result without the JSON highlighter", () => {
+    const { container } = render(
+      <ToolOutput output="just a plain sentence, not json" errorText={undefined} />,
+    );
+    expect(screen.getByText("just a plain sentence, not json")).toBeInTheDocument();
+    expect(container.querySelector('[data-language="text"]')).not.toBeNull();
+    expect(container.querySelector('[data-language="json"]')).toBeNull();
+  });
+
+  it("still renders an object result through the JSON highlighter", () => {
+    const { container } = render(<ToolOutput output={{ ok: true }} errorText={undefined} />);
+    expect(container.querySelector('[data-language="json"]')).not.toBeNull();
+  });
+});
+
+describe("ToolOutput/ToolInput — JSON.stringify never crashes the render (review #1)", () => {
+  it("falls back gracefully for a circular output object instead of throwing", () => {
+    const circular: Record<string, unknown> = { name: "circular" };
+    circular.self = circular;
+
+    expect(() => render(<ToolOutput output={circular} errorText={undefined} />)).not.toThrow();
+    expect(screen.getByText("Result")).toBeInTheDocument();
+  });
+
+  it("renders a BigInt field in the output instead of throwing", () => {
+    expect(() =>
+      render(<ToolOutput output={{ total: 10n }} errorText={undefined} />),
+    ).not.toThrow();
+    expect(screen.getByText("Result")).toBeInTheDocument();
+    expect(screen.getByText(/10n/)).toBeInTheDocument();
+  });
+
+  it("falls back gracefully for circular tool input instead of throwing", () => {
+    const circular: Record<string, unknown> = { query: "x" };
+    circular.self = circular;
+
+    expect(() => render(<ToolInput input={circular} />)).not.toThrow();
+  });
+});

package/src/tool.tsx

@@ -7,6 +7,7 @@ import type { DynamicToolUIPart, ToolUIPart } from "ai";
 import { ChevronDownIcon, WrenchIcon } from "lucide-react";
 import type { ComponentProps, ReactNode } from "react";
 import { isValidElement } from "react";
+import type { BundledLanguage } from "shiki";
 
 import { CodeBlock } from "./code-block";
 
@@ -21,6 +22,19 @@ export const Tool = ({ className, ...props }: ToolProps) => (
 
 export type ToolPart = ToolUIPart | DynamicToolUIPart;
 
+/**
+ * `JSON.stringify` throws on a circular reference or a `BigInt` — both
+ * realistic shapes for tool input/output payloads a model produced. Falls
+ * back to a readable placeholder instead of crashing the message render.
+ */
+function safeJsonStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, (_key, v) => (typeof v === "bigint" ? `${v.toString()}n` : v), 2);
+  } catch {
+    return String(value);
+  }
+}
+
 export type ToolHeaderProps = {
   title?: string;
   /**
@@ -123,36 +137,44 @@ export type ToolDetailsProps = ComponentProps<typeof Collapsible> & {
  */
 export const ToolDetails = ({
   className,
-  label = "Show technical details",
+  label,
   defaultOpen = false,
   children,
   ...props
-}: ToolDetailsProps) => (
-  <Collapsible
-    className={cn("group/tool-details not-prose", className)}
-    defaultOpen={defaultOpen}
-    {...props}
-  >
-    <CollapsibleTrigger className="flex items-center gap-1 rounded-sm text-meta text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
-      <ChevronDownIcon className="size-3.5 transition-transform group-data-[state=open]/tool-details:rotate-180" />
-      {label}
-    </CollapsibleTrigger>
-    <CollapsibleContent className="mt-3 space-y-4">{children}</CollapsibleContent>
-  </Collapsible>
-);
+}: ToolDetailsProps) => {
+  const { t } = useLocale();
+  return (
+    <Collapsible
+      className={cn("group/tool-details not-prose", className)}
+      defaultOpen={defaultOpen}
+      {...props}
+    >
+      <CollapsibleTrigger className="flex items-center gap-1 rounded-sm text-meta text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+        <ChevronDownIcon className="size-3.5 transition-transform group-data-[state=open]/tool-details:rotate-180" />
+        {label ?? t("ai.tool.showTechnicalDetails")}
+      </CollapsibleTrigger>
+      <CollapsibleContent className="mt-3 space-y-4">{children}</CollapsibleContent>
+    </Collapsible>
+  );
+};
 
 export type ToolInputProps = ComponentProps<"div"> & {
   input: ToolPart["input"];
 };
 
-export const ToolInput = ({ className, input, ...props }: ToolInputProps) => (
-  <div className={cn("space-y-2 overflow-hidden", className)} {...props}>
-    <h4 className="text-meta uppercase text-muted-foreground">Parameters</h4>
-    <div className="rounded-md bg-muted/50">
-      <CodeBlock code={JSON.stringify(input, null, 2)} language="json" />
+export const ToolInput = ({ className, input, ...props }: ToolInputProps) => {
+  const { t } = useLocale();
+  return (
+    <div className={cn("space-y-2 overflow-hidden", className)} {...props}>
+      <h4 className="text-meta uppercase text-muted-foreground">
+        {t("ai.schemaDisplay.parameters")}
+      </h4>
+      <div className="rounded-md bg-muted/50">
+        <CodeBlock code={safeJsonStringify(input)} language="json" />
+      </div>
     </div>
-  </div>
-);
+  );
+};
 
 export type ToolOutputProps = ComponentProps<"div"> & {
   /**
@@ -192,25 +214,44 @@ export const ToolOutput = ({
 }: ToolOutputProps) => {
   const { t } = useLocale();
 
-  if (!(output || errorText || isStreaming)) {
+  // `output` is a defined-but-falsy result (`0`, `false`, `""`) for plenty of
+  // real tools (a count, a boolean check, an empty-string field) — only
+  // `undefined` means "no output (yet)".
+  const hasOutput = output !== undefined;
+
+  if (!(hasOutput || errorText || isStreaming)) {
     return null;
   }
 
   const showError = !isStreaming && Boolean(errorText);
-  const pending = isStreaming && !output && !errorText;
+  const pending = isStreaming && !hasOutput && !errorText;
 
-  let Output = <div>{output as ReactNode}</div>;
+  let Output: ReactNode = null;
 
-  if (typeof output === "object" && !isValidElement(output)) {
-    Output = <CodeBlock code={JSON.stringify(output, null, 2)} language="json" />;
-  } else if (typeof output === "string") {
-    Output = <CodeBlock code={output} language="json" />;
+  if (hasOutput) {
+    if (isValidElement(output)) {
+      Output = output;
+    } else if (typeof output === "string") {
+      // A tool result is arbitrary text, not guaranteed JSON — forcing the
+      // JSON highlighter on it mis-colours ordinary strings. Shiki's own
+      // `BundledLanguage` union (grammar-backed languages) omits its
+      // hard-coded plain-text pseudo-languages (`isPlainLang`:
+      // "plaintext" | "txt" | "text" | "plain") — `createHighlighter`/
+      // `codeToTokens` accept and special-case them with no grammar load
+      // (verified: `getLoadedLanguages()` stays empty, no throw), so this
+      // is a type-only gap, not a runtime one.
+      Output = <CodeBlock code={output} language={"text" as BundledLanguage} />;
+    } else {
+      // Objects, arrays, numbers, booleans, null, bigint — all safe to
+      // stringify for display.
+      Output = <CodeBlock code={safeJsonStringify(output)} language="json" />;
+    }
   }
 
   return (
     <div className={cn("space-y-2", className)} {...props}>
       <h4 className="text-meta uppercase text-muted-foreground">
-        {showError ? "Error" : "Result"}
+        {showError ? t("ai.tool.error") : t("ai.tool.result")}
       </h4>
       {pending ? (
         <div className="space-y-2 rounded-md bg-muted/50 p-3" role="status" aria-live="polite">
@@ -223,7 +264,9 @@ export const ToolOutput = ({
         <div
           className={cn(
             "overflow-x-auto rounded-md text-caption [&_table]:w-full",
-            showError ? "bg-destructive/10 text-destructive" : "bg-muted/50 text-foreground",
+            // #124: this colours the ambient text of the error/result body —
+            // running text, so the error branch takes the ink rung.
+            showError ? "bg-destructive/10 text-destructive-text" : "bg-muted/50 text-foreground",
           )}
         >
           {showError && <div>{errorText}</div>}

package/src/transcription.tsx

@@ -54,7 +54,7 @@ export const Transcription = ({
   return (
     <TranscriptionContext.Provider value={contextValue}>
       <div
-        className={cn("flex flex-wrap gap-1 text-sm leading-relaxed", className)}
+        className={cn("flex flex-wrap gap-1 text-body leading-relaxed", className)}
         data-slot="transcription"
         {...props}
       >

package/src/turn-status.stories.tsx

@@ -0,0 +1,124 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useEffect, useState } from "react";
+import { TurnStatus } from "./turn-status";
+
+const meta = {
+  title: "AI/TurnStatus",
+  component: TurnStatus,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT in-turn footer; the console skin is `Terminal/TerminalWorking` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
+          "The in-turn footer: label, elapsed time, token counts, turn progress and a stop affordance in one place (#105). Exactly one role=status live region announces the label and the settled state — the ticking elapsed/tokens/turn stats are plain visible text so they never flood assistive tech.",
+      },
+    },
+  },
+  args: {
+    elapsedMs: 8000,
+    label: "Working…",
+    status: "working",
+    tokens: { input: 1200, output: 340 },
+    turn: 2,
+    turnTotal: 5,
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof TurnStatus>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A running turn: label, elapsed, tokens, turn progress and a stop button. */
+export const Default: Story = {
+  args: {
+    onStop: () => undefined,
+  },
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** No stop control — just the label and live stats. */
+export const WithoutStop: Story = {
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** A minimal working state — only a label, no stats yet. */
+export const LabelOnly: Story = {
+  args: {
+    elapsedMs: undefined,
+    tokens: undefined,
+    turn: undefined,
+    turnTotal: undefined,
+  },
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** The completed-turn line — stats and the stop control disappear; the live region stops announcing further ticks. */
+export const Settled: Story = {
+  args: {
+    status: "settled",
+  },
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** Adds a "scroll to bottom" affordance beside the stop control. */
+export const WithScrollToBottom: Story = {
+  args: {
+    onScrollToBottom: () => undefined,
+    onStop: () => undefined,
+    showScrollToBottom: true,
+  },
+  render: (args) => (
+    <div className="max-w-lg rounded-md border bg-card p-2">
+      <TurnStatus {...args} />
+    </div>
+  ),
+};
+
+/** A live-ticking demo — elapsed time advances every second until Stop settles the turn. */
+export const Live: Story = {
+  render: () => {
+    const LiveDemo = () => {
+      const [elapsedMs, setElapsedMs] = useState(0);
+      const [status, setStatus] = useState<"working" | "settled">("working");
+
+      useEffect(() => {
+        if (status !== "working") return;
+        const id = setInterval(() => setElapsedMs((ms) => ms + 1000), 1000);
+        return () => clearInterval(id);
+      }, [status]);
+
+      return (
+        <div className="max-w-lg rounded-md border bg-card p-2">
+          <TurnStatus
+            elapsedMs={elapsedMs}
+            label="Editing files…"
+            onStop={() => setStatus("settled")}
+            status={status}
+            tokens={{ input: 800 + elapsedMs, output: 120 + elapsedMs / 2 }}
+            turn={1}
+            turnTotal={3}
+          />
+        </div>
+      );
+    };
+    return <LiveDemo />;
+  },
+};

package/src/turn-status.test.tsx

@@ -0,0 +1,74 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { formatElapsed } from "@elabs-ai/components-ui";
+import { TurnStatus } from "./turn-status";
+
+// `formatElapsed` now lives in `@elabs-ai/components-ui` (docs/decisions/
+// 2026-09-01-brainless-adoption-architecture.md § 6.1) — `TurnStatus` imports
+// it rather than declaring it. These tests stay here because `TurnStatus` is
+// the surface whose behaviour they were written to lock.
+describe("formatElapsed", () => {
+  it.each([
+    // [elapsedMs, expected]
+    [0, "0ms"],
+    [420, "420ms"],
+    [999, "999ms"],
+    [1000, "1.0s"],
+    [8000, "8.0s"],
+    [9949, "9.9s"],
+    [10000, "10s"],
+    [42000, "42s"],
+    [59000, "59s"],
+    [60000, "1m00s"],
+    [77000, "1m17s"],
+    [605000, "10m05s"],
+  ] as const)("formats %dms as %s", (elapsedMs, expected) => {
+    expect(formatElapsed(elapsedMs)).toBe(expected);
+  });
+});
+
+describe("TurnStatus", () => {
+  it("renders exactly one live region when label, elapsed, tokens and turn are all supplied", () => {
+    render(
+      <TurnStatus
+        elapsedMs={8000}
+        label="Working…"
+        tokens={{ input: 120, output: 340 }}
+        turn={2}
+        turnTotal={5}
+      />,
+    );
+
+    const liveRegions = screen.getAllByRole("status");
+    expect(liveRegions).toHaveLength(1);
+    expect(liveRegions[0]).toHaveTextContent("Working…");
+  });
+
+  it("renders the elapsed time and does not put it inside the live region", () => {
+    render(<TurnStatus elapsedMs={8000} label="Working…" />);
+
+    expect(screen.getByText("8.0s")).toBeInTheDocument();
+    const [liveRegion] = screen.getAllByRole("status");
+    expect(liveRegion).not.toHaveTextContent("8.0s");
+  });
+
+  it("renders a focusable stop button while working, reachable via onStop", () => {
+    const onStop = () => undefined;
+    render(<TurnStatus label="Working…" onStop={onStop} status="working" />);
+
+    const stop = screen.getByRole("button", { name: "Stop" });
+    expect(stop).toBeInTheDocument();
+    expect(stop.tagName).toBe("BUTTON");
+    stop.focus();
+    expect(stop).toHaveFocus();
+  });
+
+  it("renders the completed-turn line and stops announcing when settled", () => {
+    render(<TurnStatus elapsedMs={8000} status="settled" />);
+
+    expect(screen.queryByRole("button", { name: "Stop" })).not.toBeInTheDocument();
+    const liveRegions = screen.getAllByRole("status");
+    expect(liveRegions).toHaveLength(1);
+    expect(liveRegions[0]).toHaveTextContent(/8\.0s/);
+  });
+});

package/src/turn-status.tsx

@@ -0,0 +1,174 @@
+"use client";
+
+import { Button, cn, formatElapsed, useLocale } from "@elabs-ai/components-ui";
+import { ArrowDownIcon, SquareIcon } from "lucide-react";
+import type { ComponentProps } from "react";
+import { forwardRef } from "react";
+
+export interface TurnStatusTokens {
+  input?: number;
+  output?: number;
+}
+
+export interface TurnStatusProps extends Omit<ComponentProps<"div">, "children"> {
+  /**
+   * What the turn is doing right now, e.g. `"Working…"`, `"Editing files…"`.
+   * Caller-supplied and rendered verbatim — `TurnStatus` never invents this
+   * text, so it carries no default and needs no translation key of its own.
+   */
+  label?: string;
+  /** Elapsed time in the current turn, in milliseconds. Rendered via `formatElapsed`. */
+  elapsedMs?: number;
+  /** Token counts for the turn so far. */
+  tokens?: TurnStatusTokens;
+  /** 1-based index of the current turn. */
+  turn?: number;
+  /** Total number of turns, when known. */
+  turnTotal?: number;
+  /**
+   * `"working"` (default) renders the live stats + stop control and keeps
+   * announcing `label` changes. `"settled"` renders the completed-turn line
+   * instead and stops announcing (the elapsed/tokens/turn stats and the stop
+   * control are hidden — the turn is over).
+   */
+  status?: "working" | "settled";
+  /** Renders a focusable stop button, reachable by keyboard, while `status="working"`. */
+  onStop?: () => void;
+  /** Renders a "scroll to bottom" affordance. */
+  showScrollToBottom?: boolean;
+  onScrollToBottom?: () => void;
+}
+
+/**
+ * TurnStatus — the in-turn footer: a working/settled label, elapsed time,
+ * token counts, turn progress, and a stop affordance, all in one place (#105).
+ *
+ * Exactly ONE `role="status" aria-live="polite"` region is rendered — a
+ * visually-hidden node that announces `label` while working and the
+ * completed-turn line once `status="settled"`. The ticking elapsed time and
+ * token/turn counts are plain (non-live) visible text: they update every
+ * render without re-announcing on every tick, which would flood assistive
+ * tech (see `.claude/rules/loading-states.md`). This mirrors `Persona`'s
+ * visible-content/`sr-only`-announcement split.
+ */
+export const TurnStatus = forwardRef<HTMLDivElement, TurnStatusProps>(function TurnStatus(
+  {
+    label,
+    elapsedMs,
+    tokens,
+    turn,
+    turnTotal,
+    status = "working",
+    onStop,
+    showScrollToBottom,
+    onScrollToBottom,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const { t, formatNumber } = useLocale();
+  const isSettled = status === "settled";
+  const formattedElapsed = elapsedMs === undefined ? undefined : formatElapsed(elapsedMs);
+
+  const settledText = isSettled
+    ? (label ??
+      (formattedElapsed
+        ? t("ai.turnStatus.completedIn", { elapsed: formattedElapsed })
+        : t("ai.turnStatus.completed")))
+    : undefined;
+
+  /** The one thing this component ever announces: `label`, or the settled line. */
+  const announced = isSettled ? (settledText ?? "") : (label ?? "");
+
+  const hasTokens = tokens?.input !== undefined || tokens?.output !== undefined;
+  const hasTurn = turn !== undefined;
+  const visibleLabel = isSettled ? settledText : label;
+  const hasMeta = !isSettled && (formattedElapsed !== undefined || hasTokens || hasTurn);
+  const showStop = !isSettled && Boolean(onStop);
+  const hasTrailing = hasMeta || showScrollToBottom || showStop;
+
+  return (
+    <div
+      ref={ref}
+      className={cn("flex w-full items-center gap-3 text-body text-foreground", className)}
+      data-slot="turn-status"
+      {...props}
+    >
+      <span
+        aria-hidden="true"
+        className={cn(
+          "size-2 shrink-0 rounded-full",
+          isSettled ? "bg-success" : "animate-pulse bg-primary motion-reduce:animate-none",
+        )}
+        data-slot="turn-status-indicator"
+      />
+
+      {visibleLabel ? (
+        <span className="truncate" data-slot="turn-status-label">
+          {visibleLabel}
+        </span>
+      ) : null}
+
+      {/* The single live region — see the component doc comment above. */}
+      <span aria-live="polite" className="sr-only" data-slot="turn-status-live" role="status">
+        {announced}
+      </span>
+
+      {hasTrailing ? (
+        <div className="ms-auto flex shrink-0 items-center gap-3" data-slot="turn-status-trailing">
+          {hasMeta ? (
+            <div
+              className="flex items-center gap-3 text-meta text-muted-foreground tabular-nums"
+              data-slot="turn-status-meta"
+            >
+              {formattedElapsed ? (
+                <span data-slot="turn-status-elapsed">{formattedElapsed}</span>
+              ) : null}
+              {hasTokens ? (
+                <span data-slot="turn-status-tokens">
+                  {formatNumber(tokens?.input ?? 0, { notation: "compact" })}
+                  {"↑ "}
+                  {formatNumber(tokens?.output ?? 0, { notation: "compact" })}
+                  {"↓"}
+                </span>
+              ) : null}
+              {hasTurn ? (
+                <span data-slot="turn-status-turn">
+                  {turn}
+                  {turnTotal === undefined ? "" : `/${turnTotal}`}
+                </span>
+              ) : null}
+            </div>
+          ) : null}
+
+          {showScrollToBottom ? (
+            <Button
+              aria-label={t("ai.turnStatus.scrollToBottom")}
+              data-slot="turn-status-scroll-to-bottom"
+              onClick={onScrollToBottom}
+              size="icon-sm"
+              type="button"
+              variant="ghost"
+            >
+              <ArrowDownIcon className="size-4" />
+            </Button>
+          ) : null}
+
+          {showStop ? (
+            <Button
+              aria-label={t("ai.promptInput.stop")}
+              data-slot="turn-status-stop"
+              onClick={onStop}
+              size="icon-sm"
+              type="button"
+              variant="outline"
+            >
+              <SquareIcon className="size-4" />
+            </Button>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+});