@elabs-ai/components-ai 4.0.0

package/src/message-table.tsx

@@ -0,0 +1,366 @@
+"use client";
+
+/**
+ * MessageTable — a model-emittable data table rendered inside a chat message.
+ *
+ * The model emits a serializable, column-oriented `TableSpec` (see
+ * `message-table-spec.ts`); MessageTable renders a lightweight table (NOT the
+ * app-chrome `@elabs-ai/components-data` DataTable — this is message content).
+ *
+ * Design bar (mirrors AutoChart):
+ * - Spec-driven, zod-validated; the model never chooses the look.
+ * - Never throws. A malformed spec → `MessageTableFallback`; an unknown format
+ *   falls back to text; a missing cell renders an em-dash.
+ * - Streaming-tolerant. Half-arrived columns/rows are dropped or render
+ *   progressively; a spec with columns but no rows yet shows skeleton rows.
+ * - Tokens only; numeric columns are end-aligned + `tabular-nums`.
+ * - Optional client-side sort (controlled OR uncontrolled) and an optional
+ *   per-cell `renderCell` override for consumer composition.
+ *
+ * Composes the `@elabs-ai/components-ui` `Table` primitive.
+ */
+
+import { forwardRef, useId, useMemo, useState, type HTMLAttributes, type ReactNode } from "react";
+import { ChevronDown, ChevronUp, ChevronsUpDown } from "lucide-react";
+import {
+  Badge,
+  Skeleton,
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { useLocale } from "@elabs-ai/components-ui";
+
+import {
+  badgeToneForValue,
+  compareCellValues,
+  EMPTY_CELL,
+  formatCellValue,
+  isEmptyCell,
+  isNumericFormat,
+  normalizeTableSpec,
+  type ColumnSpec,
+  type TableRowData,
+  type TableSpec,
+} from "./message-table-spec";
+
+// ─── Sort ─────────────────────────────────────────────────────────────────────
+
+export interface TableSort {
+  /** The sorted column's key. */
+  key: string;
+  direction: "asc" | "desc";
+}
+
+/** Per-cell render override — return `undefined` to fall back to default rendering. */
+export type RenderCell = (args: {
+  value: unknown;
+  column: ColumnSpec;
+  row: TableRowData;
+  rowIndex: number;
+}) => ReactNode;
+
+// ─── Fallback ─────────────────────────────────────────────────────────────────
+
+export interface MessageTableFallbackProps extends HTMLAttributes<HTMLDivElement> {
+  /** Short human reason the table could not render. */
+  message?: string;
+}
+
+/** Shown when the spec is unusable. Mirrors `ChartFallback` semantics. */
+export const MessageTableFallback = forwardRef<HTMLDivElement, MessageTableFallbackProps>(
+  function MessageTableFallback(
+    { message = "This table could not be displayed.", className, ...props },
+    ref,
+  ) {
+    return (
+      <div
+        ref={ref}
+        role="status"
+        aria-live="polite"
+        className={cn(
+          // Sole structural cue is the border (no fill) — reads in every theme,
+          // incl. themes where surface-muted ≈ background. border-strong is
+          // contrast-guaranteed vs the background.
+          "flex items-center justify-center rounded-md border border-border-strong px-4 py-6 text-center text-body text-muted-foreground",
+          className,
+        )}
+        {...props}
+      >
+        {message}
+      </div>
+    );
+  },
+);
+
+// ─── MessageTable ─────────────────────────────────────────────────────────────
+
+export interface MessageTableProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  /** The serializable table specification produced by an LLM tool-call. */
+  spec: TableSpec | unknown;
+  /** Enable click-to-sort column headers. @default false */
+  sortable?: boolean;
+  /** Controlled sort. When provided, `onSortChange` is the only way to update it. */
+  sort?: TableSort | null;
+  /** Uncontrolled initial sort. */
+  defaultSort?: TableSort | null;
+  /** Called with the next sort (or `null`) when a header is clicked. */
+  onSortChange?: (sort: TableSort | null) => void;
+  /** Cap the number of rendered rows; shows a "Showing N of M rows" notice. */
+  maxRows?: number;
+  /** Per-cell render override for custom composition. */
+  renderCell?: RenderCell;
+  /** The spec is still streaming (columns-but-no-rows shows skeleton rows). */
+  streaming?: boolean;
+}
+
+/**
+ * MessageTable — renders a `TableSpec` as a lightweight message-body table.
+ *
+ * Intentionally bare: no toolbar, no expand chrome. Growing one here would be
+ * `ChartFrame` re-implemented inside this package.
+ *
+ * **To make it expandable, wrap it in `ExpandDialog`**
+ * (`@elabs-ai/components-ui`) — the shared two-pane expand surface,
+ * the same one a chart opens. Do NOT hand-roll a lightbox or a full-screen
+ * breakout; four of those already existed before the component was shared, and
+ * each one taught users a different meaning for the same button.
+ *
+ * The context pane for a table is its SHAPE, not statistics: row count,
+ * "showing N of M", column count, each column's declared `format`. A
+ * model-emitted table's numerics may already be formatted strings, so min/max/avg
+ * over them is wrong more often than right.
+ */
+export const MessageTable = forwardRef<HTMLDivElement, MessageTableProps>(function MessageTable(
+  {
+    spec,
+    sortable = false,
+    sort: sortProp,
+    defaultSort = null,
+    onSortChange,
+    maxRows,
+    renderCell,
+    streaming = false,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const { t } = useLocale();
+  const reactId = useId();
+  const isControlled = sortProp !== undefined;
+  const [internalSort, setInternalSort] = useState<TableSort | null>(defaultSort);
+  const resolvedSort = isControlled ? (sortProp as TableSort | null) : internalSort;
+
+  const result = normalizeTableSpec(spec);
+
+  const normalized = result.ok ? result.spec : null;
+
+  const sortedRows = useMemo<TableRowData[]>(() => {
+    if (!normalized || !resolvedSort) return normalized?.rows ?? [];
+    const column = normalized.columns.find((c) => c.key === resolvedSort.key);
+    if (!column) return normalized.rows;
+    const direction = resolvedSort.direction === "asc" ? 1 : -1;
+    return [...normalized.rows].sort(
+      (a, b) => direction * compareCellValues(a[column.key], b[column.key], column.format),
+    );
+  }, [normalized, resolvedSort]);
+
+  if (!result.ok) {
+    return (
+      <MessageTableFallback ref={ref} message={result.reason} className={className} {...props} />
+    );
+  }
+
+  const { columns, title, emptyText } = result.spec;
+
+  // No columns: skeleton while streaming, otherwise a fallback.
+  if (columns.length === 0) {
+    if (streaming) {
+      return (
+        <div ref={ref} className={cn("w-full", className)} {...props}>
+          <span className="sr-only" role="status" aria-live="polite">
+            Loading table…
+          </span>
+          <div
+            aria-hidden="true"
+            className="flex flex-col gap-2 rounded-md border border-border p-3"
+          >
+            <Skeleton className="h-5 w-40" />
+            <Skeleton className="h-4 w-full" />
+            <Skeleton className="h-4 w-full" />
+            <Skeleton className="h-4 w-3/4" />
+          </div>
+        </div>
+      );
+    }
+    return (
+      <MessageTableFallback
+        ref={ref}
+        message="This table has no columns to display."
+        className={className}
+        {...props}
+      />
+    );
+  }
+
+  const total = sortedRows.length;
+  const cappedRows =
+    maxRows !== undefined && maxRows >= 0 ? sortedRows.slice(0, maxRows) : sortedRows;
+  const truncatedCount = total - cappedRows.length;
+
+  const titleId = title ? `${reactId}-title` : undefined;
+
+  const setSort = (next: TableSort | null) => {
+    if (!isControlled) setInternalSort(next);
+    onSortChange?.(next);
+  };
+
+  const toggleSort = (column: ColumnSpec) => {
+    if (resolvedSort?.key === column.key) {
+      setSort({ key: column.key, direction: resolvedSort.direction === "asc" ? "desc" : "asc" });
+    } else {
+      setSort({ key: column.key, direction: "asc" });
+    }
+  };
+
+  const renderCellContent = (
+    column: ColumnSpec,
+    row: TableRowData,
+    rowIndex: number,
+  ): ReactNode => {
+    const value = row[column.key];
+    if (renderCell) {
+      const overridden = renderCell({ value, column, row, rowIndex });
+      if (overridden !== undefined) return overridden;
+    }
+    if (isEmptyCell(value)) {
+      return <span className="text-muted-foreground">{EMPTY_CELL}</span>;
+    }
+    if (column.format === "badge") {
+      return <Badge variant={badgeToneForValue(value)}>{String(value)}</Badge>;
+    }
+    return formatCellValue(value, column.format);
+  };
+
+  return (
+    <div ref={ref} className={cn("w-full", className)} {...props}>
+      {title && (
+        <p id={titleId} className="mb-1 text-body font-semibold text-foreground text-balance">
+          {title}
+        </p>
+      )}
+      <div className="overflow-hidden rounded-md border border-border">
+        {streaming && cappedRows.length === 0 && (
+          <span className="sr-only" role="status" aria-live="polite">
+            Loading table…
+          </span>
+        )}
+        <Table
+          aria-labelledby={titleId}
+          aria-label={title ? undefined : t("ai.messageTable.label")}
+          aria-busy={(streaming && cappedRows.length === 0) || undefined}
+        >
+          {truncatedCount > 0 && (
+            <TableCaption className="mb-2 mt-3 px-3 text-caption">
+              Showing {cappedRows.length} of {total} rows
+            </TableCaption>
+          )}
+          <TableHeader>
+            <TableRow>
+              {columns.map((column) => {
+                const numeric = isNumericFormat(column.format);
+                const active = resolvedSort?.key === column.key;
+                const ariaSort = active
+                  ? resolvedSort?.direction === "asc"
+                    ? "ascending"
+                    : "descending"
+                  : sortable
+                    ? "none"
+                    : undefined;
+                const label = column.label ?? column.key;
+                return (
+                  <TableHead
+                    key={column.key}
+                    scope="col"
+                    aria-sort={ariaSort}
+                    className={cn(numeric && "text-end")}
+                  >
+                    {sortable ? (
+                      <button
+                        type="button"
+                        onClick={() => toggleSort(column)}
+                        className={cn(
+                          "inline-flex items-center gap-1 rounded-sm font-medium",
+                          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+                          "hover:text-foreground transition-colors duration-fast ease-standard motion-reduce:transition-none",
+                          numeric && "flex-row-reverse",
+                        )}
+                      >
+                        <span>{label}</span>
+                        {active ? (
+                          resolvedSort?.direction === "asc" ? (
+                            <ChevronUp aria-hidden="true" className="size-3.5" />
+                          ) : (
+                            <ChevronDown aria-hidden="true" className="size-3.5" />
+                          )
+                        ) : (
+                          <ChevronsUpDown aria-hidden="true" className="size-3.5 opacity-50" />
+                        )}
+                      </button>
+                    ) : (
+                      label
+                    )}
+                  </TableHead>
+                );
+              })}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {cappedRows.length === 0 && streaming ? (
+              [0, 1, 2].map((i) => (
+                <TableRow key={`skeleton-${i}`} aria-hidden="true">
+                  {columns.map((column) => (
+                    <TableCell key={column.key}>
+                      <Skeleton className="h-4 w-full" />
+                    </TableCell>
+                  ))}
+                </TableRow>
+              ))
+            ) : cappedRows.length === 0 ? (
+              <TableRow>
+                <TableCell
+                  colSpan={columns.length}
+                  className="py-6 text-center text-muted-foreground"
+                >
+                  {emptyText ?? "No rows to display"}
+                </TableCell>
+              </TableRow>
+            ) : (
+              cappedRows.map((row, rowIndex) => (
+                <TableRow key={rowIndex}>
+                  {columns.map((column) => {
+                    const numeric = isNumericFormat(column.format);
+                    return (
+                      <TableCell
+                        key={column.key}
+                        className={cn(numeric && "text-end tabular-nums")}
+                      >
+                        {renderCellContent(column, row, rowIndex)}
+                      </TableCell>
+                    );
+                  })}
+                </TableRow>
+              ))
+            )}
+          </TableBody>
+        </Table>
+      </div>
+    </div>
+  );
+});

package/src/message.stories.tsx

@@ -0,0 +1,262 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent } from "storybook/test";
+import {
+  Copy as CopyIcon,
+  Pencil as PencilIcon,
+  Pin as PinIcon,
+  RotateCcw as RotateCcwIcon,
+} from "lucide-react";
+import {
+  AgentMessage,
+  Message,
+  MessageAction,
+  MessageActions,
+  MessageAvatar,
+  MessageBranch,
+  MessageBranchContent,
+  MessageBranchNext,
+  MessageBranchPage,
+  MessageBranchPrevious,
+  MessageBranchSelector,
+  MessageContent,
+  MessageHeader,
+  MessageResponse,
+  UserMessage,
+} from "./message";
+import { SourceList } from "./sources";
+const meta = {
+  title: "AI/Message",
+  component: Message,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Message>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Conversation_: Story = {
+  name: "User + Assistant",
+  render: () => (
+    <div className="space-y-4">
+      <Message from="user">
+        <MessageContent>Summarize last week's deploys.</MessageContent>
+      </Message>
+      <Message from="assistant">
+        <MessageContent>Three services shipped; billing is degraded.</MessageContent>
+      </Message>
+    </div>
+  ),
+};
+// The named preset wrappers (#191, research 11 §B.2): UserMessage / AgentMessage
+// with the MessageHeader identity slot.
+export const Presets: Story = {
+  name: "UserMessage + AgentMessage",
+  render: () => (
+    <div className="space-y-4">
+      <UserMessage>
+        <MessageContent>How did churn develop this quarter?</MessageContent>
+      </UserMessage>
+      <AgentMessage>
+        <MessageHeader>
+          <MessageAvatar name="Atlas" role="agent" />
+          <span>Atlas</span>
+        </MessageHeader>
+        <MessageContent>Pulling the retention cohorts now…</MessageContent>
+      </AgentMessage>
+    </div>
+  ),
+};
+// emphasis="answer" = the green left rail on the wrapper; prose + grounding
+// footer are COMPOSED children, not baked-in layout.
+export const FinalAnswer: Story = {
+  name: "AgentMessage emphasis=answer",
+  render: () => (
+    <AgentMessage emphasis="answer">
+      <MessageHeader>
+        <MessageAvatar name="Atlas" role="agent" />
+        <span>Atlas</span>
+      </MessageHeader>
+      <MessageContent>
+        <MessageResponse>{`## Churn improved this quarter
+
+Enterprise churn fell **0.4pp** to 1.8%, driven by the renewal-desk rollout:
+
+- 12 at-risk accounts recovered
+- \`auto-renew\` adoption up 9pp`}</MessageResponse>
+        <SourceList
+          sources={[
+            { href: "https://warehouse.acme.com/q3-retention", title: "Q3 retention cohort" },
+            { href: "https://crm.acme.com/renewals", title: "Renewal desk log" },
+          ]}
+        />
+      </MessageContent>
+    </AgentMessage>
+  ),
+};
+// LOADING — no tokens have arrived yet (loading-states.md `loading`).
+// `MessageResponse` renders skeleton lines at the body line-height instead of
+// `<Streamdown>`, so the bubble reserves its space before the first token.
+export const Loading: Story = {
+  name: "MessageResponse loading",
+  render: () => (
+    <AgentMessage>
+      <MessageHeader>
+        <MessageAvatar name="Atlas" role="agent" />
+        <span>Atlas</span>
+      </MessageHeader>
+      <MessageContent>
+        <MessageResponse loading />
+      </MessageContent>
+    </AgentMessage>
+  ),
+};
+// Controlled MessageBranch (#361) — an external control ("Jump to reply N")
+// drives the SAME `branch` state that the in-component Previous/Next controls
+// mutate via `onBranchChange`, proving the host can own branch selection
+// (e.g. restore it from a URL param) without remounting the subtree.
+export const BranchControlled: Story = {
+  name: "MessageBranch — controlled",
+  render: function Render() {
+    const [branch, setBranch] = useState(0);
+    return (
+      <div className="space-y-3">
+        <div className="flex gap-2">
+          <button
+            className="rounded-md border px-2 py-1 text-caption"
+            onClick={() => setBranch(0)}
+            type="button"
+          >
+            Jump to reply 1
+          </button>
+          <button
+            className="rounded-md border px-2 py-1 text-caption"
+            onClick={() => setBranch(2)}
+            type="button"
+          >
+            Jump to reply 3
+          </button>
+        </div>
+        <MessageBranch branch={branch} onBranchChange={setBranch}>
+          <MessageBranchContent>
+            <AgentMessage key="concise">
+              <MessageContent>Here's a concise answer.</MessageContent>
+            </AgentMessage>
+            <AgentMessage key="detailed">
+              <MessageContent>Here's a longer answer, with more context.</MessageContent>
+            </AgentMessage>
+            <AgentMessage key="alternate">
+              <MessageContent>Here's a third, differently-phrased answer.</MessageContent>
+            </AgentMessage>
+          </MessageBranchContent>
+          <MessageBranchSelector>
+            <MessageBranchPrevious />
+            <MessageBranchPage />
+            <MessageBranchNext />
+          </MessageBranchSelector>
+        </MessageBranch>
+      </div>
+    );
+  },
+  play: async ({ canvas }) => {
+    await expect(canvas.getByText("1 of 3")).toBeInTheDocument();
+
+    await userEvent.click(canvas.getByRole("button", { name: "Jump to reply 3" }));
+    await expect(canvas.getByText("3 of 3")).toBeInTheDocument();
+
+    // The component's own Previous control still drives the SAME external
+    // state — it doesn't fall back to internal tracking in controlled mode.
+    await userEvent.click(canvas.getByRole("button", { name: "Previous branch" }));
+    await expect(canvas.getByText("2 of 3")).toBeInTheDocument();
+  },
+};
+// ACTIONS, always visible (`appearance="plain" reveal="always"` — the defaults,
+// set explicitly here so both default values are exercised in a RENDERED
+// position, not only in the controls panel).
+export const ActionsPlain: Story = {
+  name: "MessageActions — inline",
+  render: () => (
+    <AgentMessage>
+      <MessageContent>Three services shipped; billing is degraded.</MessageContent>
+      <MessageActions appearance="plain" reveal="always">
+        <MessageAction onClick={() => {}} tooltip="Copy">
+          <CopyIcon aria-hidden="true" size={14} />
+        </MessageAction>
+        <MessageAction onClick={() => {}} tooltip="Pin">
+          <PinIcon aria-hidden="true" size={14} />
+        </MessageAction>
+      </MessageActions>
+    </AgentMessage>
+  ),
+};
+// ACTIONS, hover-revealed floating pill — the chat-client shape. The row is
+// `opacity-0` at rest on a FINE pointer only and fades in from the parent
+// `Message`'s hover; on a coarse (touch) pointer it never hides, since nothing
+// there could reveal it.
+//
+// The controls stay in the tab order the whole time — `focus-within` is what
+// brings the pill back for a keyboard user, which is why the row is NOT
+// `hidden`/`invisible`/unmounted at rest.
+export const ActionsHoverBar: Story = {
+  name: "MessageActions — hover pill",
+  render: function Render() {
+    const [pinned, setPinned] = useState(false);
+    return (
+      <div className="space-y-4">
+        <AgentMessage>
+          <MessageHeader>
+            <MessageAvatar name="Atlas" role="agent" />
+            <span>Atlas</span>
+          </MessageHeader>
+          <MessageContent>
+            Retention held at 94% — the dip you saw was a reporting lag, not churn.
+          </MessageContent>
+          <MessageActions appearance="bar" reveal="hover">
+            <MessageAction onClick={() => {}} tooltip="Copy">
+              <CopyIcon aria-hidden="true" size={14} />
+            </MessageAction>
+            {/* Pin is a TOGGLE the host owns — the component ships no pin state.
+                `aria-pressed` + the filled glyph are the two channels (a11y.md:
+                colour is never the only one). */}
+            <MessageAction
+              aria-pressed={pinned}
+              onClick={() => setPinned((v) => !v)}
+              tooltip={pinned ? "Unpin" : "Pin"}
+            >
+              <PinIcon
+                aria-hidden="true"
+                className={pinned ? "fill-current" : undefined}
+                size={14}
+              />
+            </MessageAction>
+            <MessageAction onClick={() => {}} tooltip="Retry">
+              <RotateCcwIcon aria-hidden="true" size={14} />
+            </MessageAction>
+          </MessageActions>
+        </AgentMessage>
+        <UserMessage>
+          <MessageContent>Can you break that down by region?</MessageContent>
+          <MessageActions appearance="bar" reveal="hover">
+            <MessageAction onClick={() => {}} tooltip="Copy">
+              <CopyIcon aria-hidden="true" size={14} />
+            </MessageAction>
+            <MessageAction onClick={() => {}} tooltip="Edit">
+              <PencilIcon aria-hidden="true" size={14} />
+            </MessageAction>
+          </MessageActions>
+        </UserMessage>
+      </div>
+    );
+  },
+  play: async ({ canvas }) => {
+    // Hover-revealed ≠ removed: the controls are real, named, reachable buttons
+    // at rest, which is the whole reason the row fades rather than unmounts.
+    const groups = canvas.getAllByRole("group", { name: "Message actions" });
+    await expect(groups).toHaveLength(2);
+
+    const pin = canvas.getByRole("button", { name: "Pin" });
+    await expect(pin).toHaveAttribute("aria-pressed", "false");
+    await userEvent.click(pin);
+    await expect(canvas.getByRole("button", { name: "Unpin" })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+  },
+};