@elabs-ai/components-ai 4.0.0

package/src/message-table-spec.ts

@@ -0,0 +1,281 @@
+/**
+ * message-table-spec.ts — Serializable TableSpec for MessageTable.
+ *
+ * Pure data types + zod schemas (no React). The shape is what an LLM tool-call
+ * emits when it wants to show tabular data inside a chat message. It is
+ * column-oriented: `columns` declare the shape + per-column `format`, and each
+ * `rows` entry is an object keyed by column `key`.
+ *
+ * The exported zod schemas are the source of truth downstream catalogs compile
+ * prompts + validators from. Specs carry NO style-bearing props — the model
+ * chooses the data and its semantic format, never the look.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Columns
+// ---------------------------------------------------------------------------
+
+/**
+ * How a cell's value is rendered + aligned.
+ * - `text` (default) — as-is, start-aligned.
+ * - `number` / `currency` / `percent` — `Intl`-formatted, end-aligned, tabular.
+ * - `date` — localized date.
+ * - `badge` — a tonal badge whose tone is inferred from the value's semantics.
+ */
+export const cellFormatSchema = z.enum(["text", "number", "currency", "percent", "date", "badge"]);
+export type CellFormat = z.infer<typeof cellFormatSchema>;
+
+/** One column definition. */
+export const columnSpecSchema = z.object({
+  /** The row-object key this column reads. */
+  key: z.string(),
+  /** Header label. Falls back to the `key` when omitted. */
+  label: z.string().optional(),
+  /** How cells in this column are formatted + aligned. @default "text" */
+  format: cellFormatSchema.optional(),
+});
+export type ColumnSpec = z.infer<typeof columnSpecSchema>;
+
+// ---------------------------------------------------------------------------
+// TableSpec
+// ---------------------------------------------------------------------------
+
+/** A single row: an object keyed by column `key`. */
+export type TableRowData = Record<string, unknown>;
+
+/**
+ * The serializable table specification produced by an LLM tool-call.
+ * MessageTable reads this and renders a lightweight, message-body table.
+ */
+export const tableSpecSchema = z.object({
+  /** Optional heading + accessible label for the table. */
+  title: z.string().optional(),
+  /** Ordered column definitions. */
+  columns: z.array(columnSpecSchema),
+  /** Row objects keyed by column `key`. */
+  rows: z.array(z.record(z.string(), z.unknown())),
+  /** Message shown when there are zero rows. @default "No rows to display" */
+  emptyText: z.string().optional(),
+});
+export type TableSpec = z.infer<typeof tableSpecSchema>;
+
+// ---------------------------------------------------------------------------
+// Normalization (lenient — streaming-tolerant, never throws)
+// ---------------------------------------------------------------------------
+
+/** A validated, render-ready TableSpec. */
+export interface NormalizedTableSpec {
+  title?: string;
+  columns: ColumnSpec[];
+  rows: TableRowData[];
+  emptyText?: string;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function strOrUndefined(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Lenient parse for the render path. NEVER throws. Individually invalid columns
+ * are dropped and non-object rows are filtered out, so a partial (streaming)
+ * spec still renders progressively. Returns `{ ok: false }` only when the whole
+ * spec is unusable (not an object).
+ */
+export function normalizeTableSpec(
+  spec: unknown,
+): { ok: true; spec: NormalizedTableSpec } | { ok: false; reason: string } {
+  if (!isPlainObject(spec)) {
+    return { ok: false, reason: "Table specification is missing or malformed." };
+  }
+
+  const columns: ColumnSpec[] = [];
+  const seen = new Set<string>();
+  if (Array.isArray(spec.columns)) {
+    for (const candidate of spec.columns) {
+      const parsed = columnSpecSchema.safeParse(candidate);
+      if (!parsed.success) continue; // drop invalid / still-streaming column
+      if (seen.has(parsed.data.key)) continue; // de-dupe by key
+      seen.add(parsed.data.key);
+      columns.push(parsed.data);
+    }
+  }
+
+  const rows: TableRowData[] = Array.isArray(spec.rows) ? spec.rows.filter(isPlainObject) : [];
+
+  return {
+    ok: true,
+    spec: {
+      title: strOrUndefined(spec.title),
+      columns,
+      rows,
+      emptyText: strOrUndefined(spec.emptyText),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+/** The em-dash shown for a missing / empty cell. */
+export const EMPTY_CELL = "—";
+
+/** Whether a format is numeric (drives end-alignment + `tabular-nums`). */
+export function isNumericFormat(format: CellFormat | undefined): boolean {
+  return format === "number" || format === "currency" || format === "percent";
+}
+
+/** Whether a value is considered empty (renders the em-dash). */
+export function isEmptyCell(value: unknown): boolean {
+  return value === null || value === undefined || value === "";
+}
+
+function toNumber(value: unknown): number {
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && value.trim() !== "") return Number(value);
+  return Number.NaN;
+}
+
+const numberFormatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 });
+const currencyFormatter = new Intl.NumberFormat(undefined, {
+  style: "currency",
+  currency: "USD",
+  maximumFractionDigits: 0,
+});
+const percentFormatter = new Intl.NumberFormat(undefined, {
+  style: "percent",
+  maximumFractionDigits: 1,
+});
+
+/**
+ * Format a present value to a display string per its column format.
+ * Unknown formats fall through to `String(value)` (never throws). Empty values
+ * are the caller's concern (render `EMPTY_CELL`). `percent` follows `Intl`
+ * semantics — pass fractions (0.42 → "42%").
+ */
+export function formatCellValue(value: unknown, format: CellFormat | undefined): string {
+  switch (format) {
+    case "number": {
+      const n = toNumber(value);
+      return Number.isNaN(n) ? String(value) : numberFormatter.format(n);
+    }
+    case "currency": {
+      const n = toNumber(value);
+      return Number.isNaN(n) ? String(value) : currencyFormatter.format(n);
+    }
+    case "percent": {
+      const n = toNumber(value);
+      return Number.isNaN(n) ? String(value) : percentFormatter.format(n);
+    }
+    case "date": {
+      const d = value instanceof Date ? value : new Date(String(value));
+      return Number.isNaN(d.getTime())
+        ? String(value)
+        : d.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+    }
+    default:
+      return String(value);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Badge tone inference (semantic, not style — the spec never picks a tone)
+// ---------------------------------------------------------------------------
+
+export type BadgeTone = "secondary" | "success" | "warning" | "destructive" | "info";
+
+const SUCCESS_WORDS = new Set([
+  "active",
+  "success",
+  "successful",
+  "complete",
+  "completed",
+  "done",
+  "passed",
+  "pass",
+  "approved",
+  "ok",
+  "online",
+  "enabled",
+  "healthy",
+  "live",
+  "paid",
+  "yes",
+  "true",
+]);
+const WARNING_WORDS = new Set([
+  "pending",
+  "warning",
+  "in progress",
+  "in-progress",
+  "review",
+  "in review",
+  "waiting",
+  "partial",
+  "degraded",
+  "low",
+  "hold",
+  "on hold",
+]);
+const DESTRUCTIVE_WORDS = new Set([
+  "failed",
+  "fail",
+  "error",
+  "rejected",
+  "inactive",
+  "offline",
+  "disabled",
+  "blocked",
+  "cancelled",
+  "canceled",
+  "overdue",
+  "no",
+  "false",
+  "critical",
+  "high",
+  "expired",
+]);
+const INFO_WORDS = new Set(["info", "new", "draft", "queued", "scheduled", "beta", "todo", "open"]);
+
+/** Infer a badge tone from a value's semantics (status vocabulary). */
+export function badgeToneForValue(value: unknown): BadgeTone {
+  const key = String(value).trim().toLowerCase();
+  if (SUCCESS_WORDS.has(key)) return "success";
+  if (WARNING_WORDS.has(key)) return "warning";
+  if (DESTRUCTIVE_WORDS.has(key)) return "destructive";
+  if (INFO_WORDS.has(key)) return "info";
+  return "secondary";
+}
+
+// ---------------------------------------------------------------------------
+// Sorting
+// ---------------------------------------------------------------------------
+
+/** Compare two cell values for sorting, honoring numeric/date formats. */
+export function compareCellValues(a: unknown, b: unknown, format: CellFormat | undefined): number {
+  const aEmpty = isEmptyCell(a);
+  const bEmpty = isEmptyCell(b);
+  if (aEmpty && bEmpty) return 0;
+  if (aEmpty) return 1; // empties sort last
+  if (bEmpty) return -1;
+
+  if (isNumericFormat(format)) {
+    return toNumber(a) - toNumber(b);
+  }
+  if (format === "date") {
+    const da = new Date(String(a)).getTime();
+    const db = new Date(String(b)).getTime();
+    return (Number.isNaN(da) ? 0 : da) - (Number.isNaN(db) ? 0 : db);
+  }
+  // Mixed/auto: numeric when both parse as numbers, else locale string compare.
+  const na = toNumber(a);
+  const nb = toNumber(b);
+  if (!Number.isNaN(na) && !Number.isNaN(nb)) return na - nb;
+  return String(a).localeCompare(String(b));
+}

package/src/message-table.stories.tsx

@@ -0,0 +1,176 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { MessageTable, type TableSort } from "./message-table";
+import type { TableSpec } from "./message-table-spec";
+
+const meta = {
+  title: "AI/MessageTable",
+  component: MessageTable,
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof MessageTable>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// A representative spec an LLM tool-call might emit inside a chat message.
+const invoicesSpec: TableSpec = {
+  title: "Recent invoices",
+  columns: [
+    { key: "id", label: "Invoice" },
+    { key: "customer", label: "Customer" },
+    { key: "amount", label: "Amount", format: "currency" },
+    { key: "margin", label: "Margin", format: "percent" },
+    { key: "due", label: "Due", format: "date" },
+    { key: "status", label: "Status", format: "badge" },
+  ],
+  rows: [
+    {
+      id: "INV-1042",
+      customer: "Acme",
+      amount: 12400,
+      margin: 0.32,
+      due: "2026-08-01",
+      status: "Paid",
+    },
+    {
+      id: "INV-1043",
+      customer: "Globex",
+      amount: 8800,
+      margin: 0.21,
+      due: "2026-08-05",
+      status: "Pending",
+    },
+    {
+      id: "INV-1044",
+      customer: "Initech",
+      amount: 21500,
+      margin: 0.44,
+      due: "2026-07-20",
+      status: "Overdue",
+    },
+    {
+      id: "INV-1045",
+      customer: "Umbrella",
+      amount: 3600,
+      margin: 0.12,
+      due: "2026-08-12",
+      status: "Draft",
+    },
+  ],
+};
+
+/** The default: formatted columns (currency/percent right-aligned, tonal badge). */
+export const Default: Story = {
+  args: { spec: invoicesSpec },
+};
+
+/** Sortable — click a header to sort; numeric columns sort numerically. */
+export const Sortable: Story = {
+  args: { spec: invoicesSpec, sortable: true },
+};
+
+/** Controlled sort — the parent owns the sort state. */
+export const ControlledSort: Story = {
+  render: function ControlledSort() {
+    const [sort, setSort] = useState<TableSort | null>({ key: "amount", direction: "desc" });
+    return (
+      <div className="flex flex-col gap-3">
+        <p className="text-caption text-muted-foreground">
+          Sort: {sort ? `${sort.key} ${sort.direction}` : "none"}
+        </p>
+        <MessageTable spec={invoicesSpec} sortable sort={sort} onSortChange={setSort} />
+      </div>
+    );
+  },
+};
+
+/** Truncated — `maxRows` caps the display and shows a "Showing N of M" notice. */
+export const Truncated: Story = {
+  args: {
+    spec: {
+      title: "Top accounts",
+      columns: [
+        { key: "name", label: "Account" },
+        { key: "arr", label: "ARR", format: "currency" },
+      ],
+      rows: Array.from({ length: 40 }, (_, i) => ({
+        name: `Account ${i + 1}`,
+        arr: (40 - i) * 1000,
+      })),
+    },
+    maxRows: 5,
+  },
+};
+
+/** Streaming / partial — columns known, rows still arriving → skeleton rows. */
+export const StreamingRows: Story = {
+  args: {
+    streaming: true,
+    spec: { title: "Loading results", columns: invoicesSpec.columns, rows: [] },
+  },
+};
+
+/** Missing cells render an em-dash — a half-arrived row never crashes. */
+export const PartialRows: Story = {
+  args: {
+    streaming: true,
+    spec: {
+      title: "Streaming rows",
+      columns: invoicesSpec.columns,
+      rows: [
+        {
+          id: "INV-1042",
+          customer: "Acme",
+          amount: 12400,
+          margin: 0.32,
+          due: "2026-08-01",
+          status: "Paid",
+        },
+        { id: "INV-1043", customer: "Globex" }, // rest not arrived yet
+      ],
+    },
+  },
+};
+
+/** Empty (not streaming) — a real empty state row, never broken UI. */
+export const Empty: Story = {
+  args: {
+    spec: {
+      title: "No results",
+      columns: [
+        { key: "name", label: "Name" },
+        { key: "role", label: "Role" },
+      ],
+      rows: [],
+      emptyText: "No teammates match this filter.",
+    },
+  },
+};
+
+/** Fallback — a non-object spec renders a typed fallback (no throw). */
+export const Fallback: Story = {
+  args: { spec: 42 as unknown },
+};
+
+/** Per-cell override — compose custom cell content (like ChangeReview.renderHunk). */
+export const CustomCell: Story = {
+  args: {
+    spec: invoicesSpec,
+    renderCell: ({ value, column }) =>
+      column.key === "customer" ? (
+        <span className="font-medium text-foreground">{String(value)}</span>
+      ) : undefined,
+  },
+};
+
+/** Dark theme — verifies token-driven surfaces + dividers in dark. */
+export const DarkTheme: Story = {
+  args: { spec: invoicesSpec, sortable: true },
+  decorators: [
+    (Story) => (
+      <div data-theme="dark" className="rounded-lg bg-background p-6 text-foreground">
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/message-table.test.tsx

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MessageTable } from "./message-table";
+import {
+  badgeToneForValue,
+  compareCellValues,
+  formatCellValue,
+  normalizeTableSpec,
+  type TableSpec,
+} from "./message-table-spec";
+
+const spec: TableSpec = {
+  title: "Invoices",
+  columns: [
+    { key: "id", label: "Invoice" },
+    { key: "amount", label: "Amount", format: "currency" },
+    { key: "status", label: "Status", format: "badge" },
+  ],
+  rows: [
+    { id: "INV-2", amount: 300, status: "Pending" },
+    { id: "INV-1", amount: 100, status: "Paid" },
+  ],
+};
+
+describe("MessageTable — rendering", () => {
+  it("renders the title, headers and rows", () => {
+    render(<MessageTable spec={spec} />);
+    expect(screen.getByText("Invoices")).toBeInTheDocument();
+    expect(screen.getByRole("columnheader", { name: "Invoice" })).toBeInTheDocument();
+    expect(screen.getByText("INV-1")).toBeInTheDocument();
+    expect(screen.getByText("INV-2")).toBeInTheDocument();
+  });
+
+  it("labels the table via its title", () => {
+    render(<MessageTable spec={spec} />);
+    expect(screen.getByRole("table", { name: "Invoices" })).toBeInTheDocument();
+  });
+
+  it("renders an em-dash for a missing cell (never crashes)", () => {
+    render(<MessageTable spec={{ columns: spec.columns, rows: [{ id: "INV-9" }] }} />);
+    expect(screen.getAllByText("—").length).toBeGreaterThan(0);
+  });
+
+  it("renders a real empty state (not streaming)", () => {
+    render(<MessageTable spec={{ columns: spec.columns, rows: [], emptyText: "Nothing here." }} />);
+    expect(screen.getByText("Nothing here.")).toBeInTheDocument();
+  });
+
+  it("shows a truncation notice when maxRows caps the rows", () => {
+    render(<MessageTable spec={spec} maxRows={1} />);
+    expect(screen.getByText("Showing 1 of 2 rows")).toBeInTheDocument();
+  });
+});
+
+describe("MessageTable — never throws / fallback", () => {
+  it("renders a fallback for a non-object spec", () => {
+    render(<MessageTable spec={42 as unknown} />);
+    expect(screen.getByText(/missing or malformed|could not/i)).toBeInTheDocument();
+  });
+
+  it("renders a fallback when there are no columns (not streaming)", () => {
+    render(<MessageTable spec={{ columns: [], rows: [] }} />);
+    expect(screen.getByText(/no columns/i)).toBeInTheDocument();
+  });
+
+  it("renders skeleton rows while streaming with no rows yet", () => {
+    const { container } = render(
+      <MessageTable spec={{ columns: spec.columns, rows: [] }} streaming />,
+    );
+    expect(container.querySelector('[aria-hidden="true"] .animate-pulse')).not.toBeNull();
+  });
+});
+
+describe("MessageTable — sorting", () => {
+  it("sorts numerically when a header is clicked (uncontrolled)", async () => {
+    const user = userEvent.setup();
+    render(<MessageTable spec={spec} sortable />);
+    await user.click(screen.getByRole("button", { name: /Amount/ }));
+    const rows = screen.getAllByRole("row");
+    // rows[0] is the header row; first body row should be the smaller amount asc.
+    const firstBody = within(rows[1] as HTMLElement).getByText("INV-1");
+    expect(firstBody).toBeInTheDocument();
+    // aria-sort is set on the sorted header.
+    expect(screen.getByRole("columnheader", { name: /Amount/ })).toHaveAttribute(
+      "aria-sort",
+      "ascending",
+    );
+  });
+
+  it("supports controlled sort via onSortChange", async () => {
+    const user = userEvent.setup();
+    const onSortChange = vi.fn();
+    render(<MessageTable spec={spec} sortable sort={null} onSortChange={onSortChange} />);
+    await user.click(screen.getByRole("button", { name: /Invoice/ }));
+    expect(onSortChange).toHaveBeenCalledWith({ key: "id", direction: "asc" });
+  });
+});
+
+describe("MessageTable — per-cell override", () => {
+  it("uses renderCell when it returns a node, else falls back", () => {
+    render(
+      <MessageTable
+        spec={spec}
+        renderCell={({ value, column }) =>
+          column.key === "id" ? <a href="#x">{String(value)}</a> : undefined
+        }
+      />,
+    );
+    expect(screen.getByRole("link", { name: "INV-1" })).toBeInTheDocument();
+    // Non-overridden column still formats currency.
+    expect(screen.getByText("$100")).toBeInTheDocument();
+  });
+});
+
+describe("message-table-spec", () => {
+  it("normalizeTableSpec drops invalid columns + non-object rows", () => {
+    const result = normalizeTableSpec({
+      columns: [{ key: "a" }, { label: "no key" }],
+      rows: [{ a: 1 }, "not a row", 5],
+    });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.spec.columns).toHaveLength(1);
+      expect(result.spec.rows).toHaveLength(1);
+    }
+  });
+
+  it("formatCellValue handles number/currency/percent/date + unknown", () => {
+    expect(formatCellValue(0.42, "percent")).toContain("42");
+    expect(formatCellValue("abc", "number")).toBe("abc"); // non-numeric → string, never throws
+  });
+
+  it("badgeToneForValue maps status vocabulary to tones", () => {
+    expect(badgeToneForValue("Paid")).toBe("success");
+    expect(badgeToneForValue("Overdue")).toBe("destructive");
+    expect(badgeToneForValue("Whatever")).toBe("secondary");
+  });
+
+  it("compareCellValues sorts empties last", () => {
+    expect(compareCellValues(undefined, 5, "number")).toBeGreaterThan(0);
+    expect(compareCellValues(5, undefined, "number")).toBeLessThan(0);
+  });
+});