@elabs-ai/components-ai 4.2.0 → 5.0.0

package/src/a2ui/ui-catalog.tsx

@@ -0,0 +1,225 @@
+"use client";
+
+/**
+ * ui-catalog.tsx — the shipped A2UI catalog: every non-builtin type in
+ * `catalog.source.json` bound to its `@elabs-ai/components-ui` component. The
+ * schema half (`A2UI_CATALOG_SCHEMA`, generated) says what an agent MAY emit; this
+ * half says what it renders AS. A test asserts the two key sets are identical, so
+ * a type cannot be validatable-but-unrenderable or the reverse.
+ *
+ * Apps extend it (`createA2uiCatalog`) with their own types — a chart from
+ * `@elabs-ai/components-charts`, a domain card — because `ai` may not import its
+ * sibling packages (one-way dependency graph) and an app composes freely.
+ */
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+  Alert,
+  AlertDescription,
+  AlertTitle,
+  Avatar,
+  AvatarFallback,
+  Badge,
+  BentoGrid,
+  BentoGridItem,
+  Button,
+  ButtonGroup,
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  Checkbox,
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+  Descriptions,
+  DescriptionsItem,
+  EmptyState,
+  Heading,
+  Input,
+  Kbd,
+  Label,
+  MetricCard,
+  Progress,
+  RadioGroup,
+  RadioGroupItem,
+  SectionHeader,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Separator,
+  Slider,
+  StatePanel,
+  StatusBadge,
+  Switch,
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableFooter,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+  Text,
+  Textarea,
+  Timeline,
+} from "@elabs-ai/components-ui";
+import type { AlertTitleProps } from "@elabs-ai/components-ui";
+import type { ComponentType } from "react";
+
+import { A2UI_CATALOG_SCHEMA } from "./core/catalog.generated";
+import type { A2uiCatalogSchema, A2uiCatalogTypeSchema } from "./core/spec";
+
+/** One renderable catalog type: its schema plus the component that draws it. */
+export interface A2uiCatalogEntry {
+  schema: A2uiCatalogTypeSchema;
+  /** Absent for builtins (`Stack`, `Grid`), which the surface draws itself. */
+  component?: ComponentType<Record<string, unknown>>;
+}
+
+export type A2uiCatalog = Record<string, A2uiCatalogEntry>;
+
+// `ComponentType<Record<string, unknown>>` is the erased shape the renderer calls
+// with validated, catalog-shaped props; each binding is a real ui component.
+type AnyComponent = ComponentType<any>; // eslint-disable-line @typescript-eslint/no-explicit-any -- erased at the catalog boundary; props are validated against the schema
+
+/**
+ * `AlertTitle` inside a surface, as a `<div>` rather than its default `<h5>`.
+ *
+ * A surface is rendered into a host page whose heading outline the agent cannot see, so a
+ * fixed `h5` fails axe's `heading-order` under any host with no `h4` above it — which is
+ * most of them. The alert's `role="alert"` announces the title either way, so the heading
+ * adds nothing here; `CardTitle` defaults to `div` for the same reason. A host writing real
+ * code composes `<AlertTitle as="h3">`, where the level is knowable.
+ */
+const SurfaceAlertTitle = (props: AlertTitleProps) => <AlertTitle {...props} as="div" />;
+
+/** The `@elabs-ai/components-ui` bindings, one per non-builtin catalog type. */
+export const UI_CATALOG_BINDINGS: Record<string, AnyComponent> = {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+  Alert,
+  AlertDescription,
+  AlertTitle: SurfaceAlertTitle,
+  Avatar,
+  AvatarFallback,
+  Badge,
+  BentoGrid,
+  BentoGridItem,
+  Button,
+  ButtonGroup,
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  Checkbox,
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+  Descriptions,
+  DescriptionsItem,
+  EmptyState,
+  Heading,
+  Input,
+  Kbd,
+  Label,
+  MetricCard,
+  Progress,
+  RadioGroup,
+  RadioGroupItem,
+  SectionHeader,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Separator,
+  Slider,
+  StatePanel,
+  StatusBadge,
+  Switch,
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableFooter,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+  Text,
+  Textarea,
+  Timeline,
+};
+
+/**
+ * Build a catalog from component bindings + a schema. Every schema type that is
+ * not a builtin must have a binding; a binding without a schema is ignored (it
+ * would be unvalidatable). Extend the shipped one:
+ *
+ * ```ts
+ * const catalog = createA2uiCatalog(
+ *   { ...UI_CATALOG_BINDINGS, RevenueChart },
+ *   { ...A2UI_CATALOG_SCHEMA, RevenueChart: defineA2uiType({ props: { series: { type: "array", required: true } } }) },
+ * );
+ * ```
+ */
+export function createA2uiCatalog(
+  bindings: Record<string, AnyComponent>,
+  schema: A2uiCatalogSchema = A2UI_CATALOG_SCHEMA,
+): A2uiCatalog {
+  const catalog: A2uiCatalog = {};
+  for (const [type, typeSchema] of Object.entries(schema)) {
+    if (typeSchema.builtin) {
+      catalog[type] = { schema: typeSchema };
+      continue;
+    }
+    const component = bindings[type];
+    if (!component) {
+      throw new Error(`createA2uiCatalog: catalog type "${type}" has no component binding`);
+    }
+    catalog[type] = { schema: typeSchema, component };
+  }
+  return catalog;
+}
+
+/** Author a schema entry for an app-provided type with sensible defaults. */
+export function defineA2uiType(
+  partial: Partial<A2uiCatalogTypeSchema> & { source?: string },
+): A2uiCatalogTypeSchema {
+  return {
+    children: partial.children ?? false,
+    props: partial.props ?? {},
+    events: partial.events ?? {},
+    source: partial.source ?? "app",
+    ...(partial.summary ? { summary: partial.summary } : {}),
+    ...(partial.builtin ? { builtin: true } : {}),
+  };
+}
+
+/** The schema half of a catalog (what `validateA2uiSurface` takes). */
+export function catalogSchema(catalog: A2uiCatalog): A2uiCatalogSchema {
+  return Object.fromEntries(Object.entries(catalog).map(([t, e]) => [t, e.schema]));
+}
+
+/** The shipped catalog: builtins + every `@elabs-ai/components-ui` type above. */
+export const uiCatalog: A2uiCatalog = createA2uiCatalog(UI_CATALOG_BINDINGS);

package/src/a2ui/wave1-chart-spec.test.ts

@@ -0,0 +1,87 @@
+import { CHARTS_A2UI_CATALOG_SCHEMA } from "@elabs-ai/components-charts";
+import { describe, expect, it } from "vitest";
+
+import { A2UI_CATALOG_SCHEMA, type A2uiCatalogSchema, validateA2uiSurface } from "./core";
+
+/**
+ * Proves the A2UI catalog's `AutoChart.spec` prop (an opaque `type: "object"`,
+ * `packages/ai/src/a2ui/catalog.source.json`) validates `ChartSpec` objects that use the
+ * wave-1 fields (`labels`, `annotations`, `nulls`, dumbbell `variant`, …) — an agent that
+ * reads the catalog's description can rely on emitting them (`.claude/scratch/datawrapper-parity`).
+ * `charts` is a devDependency of `ai` for exactly this kind of cross-catalog test (see
+ * `agentic-workspace.stories.tsx`); `ai` never imports `charts` at runtime (D6).
+ *
+ * `ChartsA2uiCatalogSchema` (charts) and `A2uiCatalogSchema` (ai) are structurally close
+ * but not identical (`default?: unknown` vs `default?: A2uiJson`) — the same gap the
+ * `createA2uiCatalog` docblock's merge example papers over as a comment, never
+ * type-checked. The runtime shapes agree; the cast documents the known type gap rather
+ * than widening either schema's `default` field.
+ */
+const CATALOG = {
+  ...A2UI_CATALOG_SCHEMA,
+  ...CHARTS_A2UI_CATALOG_SCHEMA,
+} as unknown as A2uiCatalogSchema;
+
+describe("A2UI catalog accepts wave-1 ChartSpec fields", () => {
+  it("validates line, pie and dumbbell specs using labels.series, annotations, nulls, labels.slices and variant: arrow", () => {
+    const r = validateA2uiSurface(
+      {
+        a2ui: "1",
+        root: {
+          type: "Stack",
+          children: [
+            {
+              type: "AutoChart",
+              props: {
+                spec: {
+                  type: "line",
+                  data: [
+                    { month: "Jan", revenue: 100 },
+                    { month: "Feb", revenue: null },
+                    { month: "Mar", revenue: 140 },
+                  ],
+                  x: "month",
+                  series: ["revenue"],
+                  labels: { series: "end" },
+                  annotations: [{ kind: "line", y: 120, label: "Target" }],
+                  nulls: "connect",
+                },
+              },
+            },
+            {
+              type: "AutoChart",
+              props: {
+                spec: {
+                  type: "pie",
+                  data: [
+                    { channel: "Direct", share: 62 },
+                    { channel: "Referral", share: 38 },
+                  ],
+                  x: "channel",
+                  series: ["share"],
+                  labels: { slices: { show: ["label", "percent"] } },
+                },
+              },
+            },
+            {
+              type: "AutoChart",
+              props: {
+                spec: {
+                  type: "dumbbell",
+                  data: [{ region: "West", fy24: 10, fy25: 15 }],
+                  x: "region",
+                  series: ["fy24"],
+                  y2: "fy25",
+                  variant: "arrow",
+                },
+              },
+            },
+          ],
+        },
+      },
+      CATALOG,
+    );
+    expect(r.errors).toEqual([]);
+    expect(r.ok).toBe(true);
+  });
+});

package/src/a2ui/wave2-chart-spec.test.ts

@@ -0,0 +1,108 @@
+import { CHARTS_A2UI_CATALOG_SCHEMA } from "@elabs-ai/components-charts";
+import { describe, expect, it } from "vitest";
+
+import { A2UI_CATALOG_SCHEMA, type A2uiCatalogSchema, validateA2uiSurface } from "./core";
+
+/**
+ * Proves the A2UI catalog's `AutoChart.spec` prop (an opaque `type: "object"`,
+ * `packages/ai/src/a2ui/catalog.source.json`) validates `ChartSpec` objects that use the
+ * wave-2 fields — frame chrome (`notes`/`source`), `tooltip`, `facet`, `type: "dual-axis"`
+ * with `series[].axis`, and waterfall `groupBy`/`dataFormat` — the same precedent as
+ * `wave1-chart-spec.test.ts` (`.claude/scratch/datawrapper-parity`). See that file's docblock
+ * for why `charts` is a devDependency of `ai` here and why the cast is needed.
+ */
+const CATALOG = {
+  ...A2UI_CATALOG_SCHEMA,
+  ...CHARTS_A2UI_CATALOG_SCHEMA,
+} as unknown as A2uiCatalogSchema;
+
+describe("A2UI catalog accepts wave-2 ChartSpec fields", () => {
+  it("validates frame chrome (notes/source), tooltip and facet.by on a line spec", () => {
+    const r = validateA2uiSurface(
+      {
+        a2ui: "1",
+        root: {
+          type: "AutoChart",
+          props: {
+            spec: {
+              type: "line",
+              data: [
+                { region: "West", month: "Jan", revenue: 100 },
+                { region: "West", month: "Feb", revenue: 120 },
+                { region: "East", month: "Jan", revenue: 80 },
+                { region: "East", month: "Feb", revenue: 90 },
+              ],
+              x: "month",
+              series: ["revenue"],
+              notes: "Preliminary figures, subject to close.",
+              source: { name: "Finance", href: "https://example.com/finance" },
+              tooltip: { variant: "rows", focus: true },
+              facet: { by: "region", scales: { y: "shared" } },
+            },
+          },
+        },
+      },
+      CATALOG,
+    );
+    expect(r.errors).toEqual([]);
+    expect(r.ok).toBe(true);
+  });
+
+  it("validates a type: dual-axis spec using series[].axis and series[].mark", () => {
+    const r = validateA2uiSurface(
+      {
+        a2ui: "1",
+        root: {
+          type: "AutoChart",
+          props: {
+            spec: {
+              type: "dual-axis",
+              data: [
+                { month: "Jan", revenue: 100, margin: 0.2 },
+                { month: "Feb", revenue: 120, margin: 0.25 },
+              ],
+              x: "month",
+              series: [
+                { key: "revenue", axis: "left", mark: "column" },
+                { key: "margin", axis: "right", mark: "line" },
+              ],
+              axes: { y2: { align: "ticks", zero: "auto" } },
+            },
+          },
+        },
+      },
+      CATALOG,
+    );
+    expect(r.errors).toEqual([]);
+    expect(r.ok).toBe(true);
+  });
+
+  it("validates a waterfall spec using groupBy (subtotals) and dataFormat", () => {
+    const r = validateA2uiSurface(
+      {
+        a2ui: "1",
+        root: {
+          type: "AutoChart",
+          props: {
+            spec: {
+              type: "waterfall",
+              data: [
+                { step: "Starting cash", value: 1000, group: "Q1" },
+                { step: "Sales", value: 400, group: "Q1" },
+                { step: "Costs", value: -150, group: "Q1" },
+              ],
+              x: "step",
+              series: ["value"],
+              groupBy: "group",
+              dataFormat: "differences",
+              zoomToDifferences: false,
+            },
+          },
+        },
+      },
+      CATALOG,
+    );
+    expect(r.errors).toEqual([]);
+    expect(r.ok).toBe(true);
+  });
+});

package/src/agentic-workspace.stories.tsx

@@ -1,22 +1,15 @@
 import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import {
-  Avatar,
-  AvatarFallback,
   Badge,
   Button,
   Collapsible,
   CollapsibleContent,
   CollapsibleTrigger,
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuLabel,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger,
   Separator,
   Sidebar,
   SidebarContent,
+  NavUser,
   SidebarFooter,
   SidebarGroup,
   SidebarGroupAction,
@@ -52,18 +45,15 @@ import {
   Boxes,
   Calculator,
   ChevronRight,
-  ChevronsUpDown,
   Copy,
   Database,
   FolderKanban,
   Globe,
   History,
-  LogOut,
   MessageSquarePlus,
   PencilLine,
   RefreshCw,
   Search,
-  Settings,
   Share2,
   Sparkles,
   ThumbsDown,
@@ -345,7 +335,7 @@ function WorkspaceSidebar({
                 <SidebarMenuButton
                   tooltip="New chat"
                   onClick={onNewChat}
-                  className="bg-primary text-primary-foreground hover:bg-primary/90 hover:text-primary-foreground"
+                  className="bg-primary text-primary-foreground hover:bg-primary-hover hover:text-primary-foreground active:bg-primary-active active:text-primary-foreground"
                 >
                   <MessageSquarePlus />
                   <span>New chat</span>
@@ -479,38 +469,7 @@ function WorkspaceSidebar({
       </SidebarContent>
 
       <SidebarFooter>
-        <SidebarMenu>
-          <SidebarMenuItem>
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <SidebarMenuButton size="lg" tooltip="Account" className="group">
-                  <Avatar className="size-7 rounded-md">
-                    <AvatarFallback className="rounded-md text-meta">AR</AvatarFallback>
-                  </Avatar>
-                  <span className="grid flex-1 text-start leading-tight">
-                    <span className="truncate text-body font-medium">Avery Rao</span>
-                    <span className="truncate text-meta text-sidebar-muted-foreground group-hover:text-sidebar-accent-foreground">
-                      avery@acme.co
-                    </span>
-                  </span>
-                  <ChevronsUpDown className="ms-auto size-4" />
-                </SidebarMenuButton>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent side="right" align="end" className="w-48">
-                <DropdownMenuLabel>Account</DropdownMenuLabel>
-                <DropdownMenuItem>
-                  <Settings className="me-2 size-4" />
-                  Settings
-                </DropdownMenuItem>
-                <DropdownMenuSeparator />
-                <DropdownMenuItem>
-                  <LogOut className="me-2 size-4" />
-                  Sign out
-                </DropdownMenuItem>
-              </DropdownMenuContent>
-            </DropdownMenu>
-          </SidebarMenuItem>
-        </SidebarMenu>
+        <NavUser user={{ name: "Avery Rao", email: "avery@acme.co" }} />
       </SidebarFooter>
 
       <SidebarRail />
@@ -974,7 +933,7 @@ function AgenticWorkspace({ defaultSidebarOpen = true }: { defaultSidebarOpen?:
           <SidebarInset className="flex min-w-0 flex-col">
             {/* Header bar — h-12 to align with the right ContextPanelHeader and
                 the library header convention (ChatShell/ContextPanel). */}
-            <header className="flex h-12 shrink-0 items-center gap-2 border-b bg-background px-3">
+            <header className="flex h-header shrink-0 items-center gap-2 border-b bg-background px-3">
               <SidebarTrigger className="-ms-1" />
               <Separator orientation="vertical" className="me-1 h-5" />
               <div className="flex min-w-0 items-center gap-1.5 text-body">
@@ -1083,9 +1042,11 @@ function AgenticWorkspace({ defaultSidebarOpen = true }: { defaultSidebarOpen?:
 const meta = {
   title: "Patterns/Scenarios/Agentic AI Workspace",
   component: AgenticWorkspace,
+  tags: ["autodocs"],
   parameters: {
     layout: "fullscreen",
     docs: {
+      subtitle: "For copilots and agentic products",
       description: {
         component:
           "A full-page demo scenario composed from the @elabs-ai/components-* grammar: a double-sided application shell (collapsible left nav + the real ContextPanel right rail with animated collapse and asset drill-in) wrapping a complete agentic AI interaction — reasoning, a plan, the AgentTimeline execution rail, tools with JSON behind disclosure, a ToolResultCard chart headline, an ApprovalCard decision, a task summary, a checkpoint, and a grounded AgentMessage answer with an EvidenceChip and a SourceList.",

package/src/chat-shell.test.tsx

@@ -58,8 +58,8 @@ describe("ChatShell — slots", () => {
 
   it("omits the header row entirely when no header is supplied", () => {
     const { container } = render(<ChatShell>t</ChatShell>);
-    // An empty header would still occupy its fixed h-12 row.
-    expect(container.querySelector(".h-12")).toBeNull();
+    // An empty header would still occupy its fixed h-header row.
+    expect(container.querySelector(".h-header")).toBeNull();
   });
 
   it("omits the aside rail entirely when no aside is supplied", () => {
@@ -91,16 +91,46 @@ describe("ChatShell — variants", () => {
     expect(container.querySelector(".border-t")).toBeNull();
   });
 
-  it("makes the bare variant's edge scrims inert (aria-hidden AND pointer-events-none)", () => {
-    const { container } = render(<ChatShell variant="bare">t</ChatShell>);
-    const scrims = container.querySelectorAll("[aria-hidden='true']");
-    expect(scrims).toHaveLength(2);
-    for (const scrim of scrims) expect(scrim).toHaveClass("pointer-events-none");
+  it("makes the edge scrims inert (aria-hidden AND pointer-events-none) in both variants", () => {
+    for (const variant of ["card", "bare"] as const) {
+      const { container, unmount } = render(<ChatShell variant={variant}>t</ChatShell>);
+      const scrims = container.querySelectorAll("[aria-hidden='true']");
+      expect(scrims).toHaveLength(2);
+      for (const scrim of scrims) expect(scrim).toHaveClass("pointer-events-none");
+      unmount();
+    }
   });
+});
 
-  it("renders no scrims in the card variant (there is a real divider instead)", () => {
-    const { container } = render(<ChatShell>t</ChatShell>);
-    expect(container.querySelectorAll("[aria-hidden='true']")).toHaveLength(0);
+describe("ChatShell — floating composer", () => {
+  it("floats the composer over the transcript instead of stacking a footer bar", () => {
+    const { container } = render(
+      <ChatShell composer={<textarea aria-label="Message" />}>
+        <p>transcript</p>
+      </ChatShell>,
+    );
+    const layer = container.querySelector("[data-slot='chat-shell-composer']");
+    expect(layer).toHaveClass("absolute", "bottom-0", "pb-4");
+    // The layer passes pointer events through to the transcript; only the
+    // composer column takes input.
+    expect(layer).toHaveClass("pointer-events-none");
+    expect(screen.getByRole("textbox", { name: "Message" }).parentElement).toHaveClass(
+      "pointer-events-auto",
+      "max-w-(--chat-composer-column)",
+    );
+    expect(container.querySelector(".border-t")).toBeNull();
+  });
+
+  it("publishes the composer height so the transcript can scroll clear of it", () => {
+    const { container, rerender } = render(
+      <ChatShell composer={<textarea aria-label="Message" />}>t</ChatShell>,
+    );
+    const root = container.firstChild as HTMLElement;
+    // jsdom has no layout, so the measured height is 0 — the contract is that
+    // the variable is written at all.
+    expect(root.style.getPropertyValue("--chat-composer-inset")).toBe("0px");
+    rerender(<ChatShell>t</ChatShell>);
+    expect(root.style.getPropertyValue("--chat-composer-inset")).toBe("");
   });
 });