@assistant-ui/react-generative-ui 0.0.5 → 0.0.7

package/src/renderGenerativeUI.tsx

@@ -1,23 +1,26 @@
 import { getPartialJsonObjectMeta } from "assistant-stream/utils";
 import { Fragment, type ReactNode } from "react";
-import { TYPE_KEY } from "./constants";
-import type {
-  GenerativeUIElement,
-  GenerativeUILibrary,
-  GenerativeUINode,
-  GenerativeUIRenderContext,
-} from "./types";
+import {
+  normalizeUINode,
+  type NormalizedUIElement,
+  type NormalizedUINode,
+} from "./ir";
+import type { GenerativeUILibrary, GenerativeUIRenderContext } from "./types";
 
 const DEFAULT_CONTEXT: GenerativeUIRenderContext = { status: "done" };
 
+const isElement = (node: NormalizedUINode): node is NormalizedUIElement =>
+  typeof node === "object" && node !== null && !Array.isArray(node);
+
 /**
  * Renders a generative-ui tree against a {@link GenerativeUILibrary}.
  *
  * The model emits each node as a flat object `{ $type, ...props }`. We first
- * normalize that wire form into React-shaped elements (`{ type, props }`), then
- * render: each `type` is looked up in the library and its `props` are passed
- * to the component's `render(props, context)`, with `children` rendered
- * recursively so components can nest.
+ * normalize that wire form into the canonical {@link NormalizedUINode} (with
+ * `children` lifted to a reserved top-level key), then render: each `type` is
+ * looked up in the library and its `props` are passed to the component's
+ * `render(props, context)`, with `children` rendered recursively so components
+ * can nest.
  */
 export function renderGenerativeUI(
   node: unknown,
@@ -29,87 +32,32 @@ export function renderGenerativeUI(
   // string has not finished streaming.
   const meta = getPartialJsonObjectMeta(node as Record<symbol, unknown>);
   const partialPath = meta?.state === "partial" ? meta.partialPath : undefined;
-  return renderNode(normalizeNode(node, partialPath), library, context);
-}
-
-/**
- * The deepest tree we normalize. The input comes from the model, so a runaway
- * or adversarial response could nest arbitrarily deep and overflow the stack;
- * past this depth we stop (far beyond any real UI). Bounding normalization
- * bounds rendering too, since it only walks the normalized tree.
- */
-const MAX_DEPTH = 64;
-
-/**
- * Converts the flat wire form into a normalized {@link GenerativeUINode}.
- *
- * `partialPath` is the remaining segment of the parse meta's partial path
- * relative to `node` (`undefined` once the walk leaves the partial frontier,
- * i.e. everything below is complete).
- */
-function normalizeNode(
-  node: unknown,
-  partialPath: readonly string[] | undefined,
-  depth = 0,
-): GenerativeUINode {
-  if (depth > MAX_DEPTH) return null;
-  if (node == null || typeof node === "boolean") return null;
-  if (typeof node === "string" || typeof node === "number") return node;
-  if (Array.isArray(node))
-    return node.map((child, index) =>
-      normalizeNode(child, descend(partialPath, String(index)), depth + 1),
-    );
-  if (typeof node !== "object") return null;
-
-  const { [TYPE_KEY]: type, ...props } = node as Record<string, unknown>;
-  // Args stream in incrementally; a node whose `$type` has not arrived yet
-  // (or whose `$type` string is still mid-arrival) is not an error, it just
-  // isn't renderable.
-  if (typeof type !== "string") return null;
-  if (partialPath?.length === 1 && partialPath[0] === TYPE_KEY) return null;
-
-  if ("children" in props) {
-    props["children"] = normalizeNode(
-      props["children"],
-      descend(partialPath, "children"),
-      depth + 1,
-    );
-  }
-  return { type, props } as GenerativeUIElement;
-}
-
-/** Steps the partial path down into `key`; siblings of the path are complete. */
-function descend(
-  partialPath: readonly string[] | undefined,
-  key: string,
-): readonly string[] | undefined {
-  return partialPath?.[0] === key ? partialPath.slice(1) : undefined;
+  return renderNode(normalizeUINode(node, partialPath), library, context);
 }
 
 function renderNode(
-  node: GenerativeUINode,
+  node: NormalizedUINode,
   library: GenerativeUILibrary,
   context: GenerativeUIRenderContext,
 ): ReactNode {
   if (node == null || typeof node === "boolean") return null;
   if (typeof node === "string" || typeof node === "number") return node;
   if (Array.isArray(node)) {
-    // The wire format has no per-node id, so the key is positional. Pairing the
-    // index with the node's kind means that when the model splices or reorders
-    // `children` and the kind at an index changes, the key changes and React
-    // remounts instead of handing a streaming node's hook state to a different
-    // component.
+    // Use a model-provided stable key when present. Otherwise, keep the
+    // positional fallback: pairing the index with the node's kind means that
+    // when the kind at an index changes, React remounts instead of handing a
+    // streaming node's hook state to a different component.
     return node.map((child, index) => (
-      <Fragment key={`${index}:${nodeKind(child)}`}>
+      <Fragment key={nodeKey(child, index)}>
         {renderNode(child, library, context)}
       </Fragment>
     ));
   }
-  return renderElement(node, library, context);
+  return isElement(node) ? renderElement(node, library, context) : null;
 }
 
 function renderElement(
-  element: GenerativeUIElement,
+  element: NormalizedUIElement,
   library: GenerativeUILibrary,
   context: GenerativeUIRenderContext,
 ): ReactNode {
@@ -123,11 +71,23 @@ function renderElement(
   // complete rather than rendering from a partial parse.
   if (!entry.streamProperties && context.status === "streaming") return null;
 
-  // Inject the framework props last so the model can never override them.
-  const { children, ...rest } = element.props;
-  const props: Record<string, unknown> = { ...rest, $status: context.status };
-  if (children !== undefined) {
-    props["children"] = renderNode(children, library, context);
+  // `children` is a reserved top-level key on the normalized element, not a
+  // prop, so it is not in `props`. Inject the framework props last so the model
+  // can never override them. `$action` is likewise reserved and stripped from
+  // the prop bag during normalization, so it is re-injected here for components
+  // that carry behavior (e.g. `Button`).
+  const props: Record<string, unknown> = {
+    ...element.props,
+    $status: context.status,
+  };
+  if (context.dispatch !== undefined) {
+    props["$dispatch"] = context.dispatch;
+  }
+  if (element.action !== undefined) {
+    props["$action"] = element.action;
+  }
+  if (element.children !== undefined) {
+    props["children"] = renderNode(element.children, library, context);
   }
 
   return <GenerativeUIComponentRenderer render={entry.render} props={props} />;
@@ -149,11 +109,18 @@ function GenerativeUIComponentRenderer({
 
 /** A coarse kind tag for a child, used in its list key so a node changing kind
  * at a given index forces a remount rather than a wrong-fiber reuse. */
-function nodeKind(node: GenerativeUINode): string {
+function nodeKind(node: NormalizedUINode): string {
   if (node == null || typeof node === "boolean") return "";
   if (typeof node === "string" || typeof node === "number") return "#text";
   if (Array.isArray(node)) return "#array";
-  return node.type;
+  return isElement(node) ? node.type : "";
+}
+
+function nodeKey(node: NormalizedUINode, index: number): string {
+  return isElement(node) &&
+    (typeof node.key === "string" || typeof node.key === "number")
+    ? `model:${node.key}`
+    : `${index}:${nodeKind(node)}`;
 }
 
 function reportUnknownComponent(type: string, available: string[]): void {

package/src/types.ts

@@ -1,28 +1,78 @@
 import type { ReactNode } from "react";
 import type { ZodType } from "zod";
+import type { Action, NormalizedUIElement } from "./ir";
+
+/**
+ * The canonical generative-ui element, normalized from the flat `$type` shape
+ * or the legacy `component` shape (see {@link normalizeUINode}). `children` is
+ * a reserved top-level key, not a prop, so it lives here rather than inside
+ * `props`. Alias of {@link NormalizedUIElement}; kept under its old name so the
+ * package's public surface stays append-only.
+ */
+export type GenerativeUIElement = NormalizedUIElement;
+
+export type GenerativeUIProps = NormalizedUIElement["props"];
+
+/**
+ * Anything renderable as generative UI — mirrors React's `ReactNode`: an
+ * element, primitive text, a list of nodes, or nothing. Widened beyond the
+ * model payload (a {@link GenerativeUIElement}) with the renderer's
+ * null/boolean/undefined inputs.
+ */
+export type GenerativeUINode =
+  | GenerativeUIElement
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | GenerativeUINode[];
+
+export type GenerativeUIAction = Action;
 
 /** Whether a node's props are still streaming in or have fully arrived. */
 export type GenerativeUIStatus = "streaming" | "done";
 
+/** The dispatcher an interactive component calls to fire its `$action`. */
+export type GenerativeUIDispatch = (action: Action) => unknown;
+
 /** The render context threaded through {@link renderGenerativeUI}. */
 export type GenerativeUIRenderContext = {
   /** Whether the tool call's arguments are still streaming or are complete. */
   status: GenerativeUIStatus;
+  dispatch?: GenerativeUIDispatch;
 };
 
 /**
  * Props a component's `render` receives: its model props, rendered `children`,
- * and the injected `$status`. `$status` is the discriminant — when it is
- * `"done"`, `P` is complete; while `"streaming"`, `P` is partial. It is named
- * `$status` (not `status`) so it never collides with a real `status` prop, the
- * same reservation as `$type`.
+ * and the injected framework keys. `$status` is the discriminant — when it is
+ * `"done"`, `P` is complete; while `"streaming"`, `P` is partial. `$action` is
+ * the node's behavior payload, present only on interactive nodes. `$dispatch`
+ * fires that payload through the host's {@link ActionRegistry}; it is present
+ * only when a registry was wired. All three are `$`-prefixed so they never
+ * collide with a real `status`/`action`/`dispatch` prop.
  */
 type StreamingRenderProps<P> =
-  | (Partial<P> & { children?: ReactNode; $status: "streaming" })
-  | (P & { children?: ReactNode; $status: "done" });
+  | (Partial<P> & {
+      children?: ReactNode;
+      $status: "streaming";
+      $action?: Action;
+      $dispatch?: GenerativeUIDispatch;
+    })
+  | (P & {
+      children?: ReactNode;
+      $status: "done";
+      $action?: Action;
+      $dispatch?: GenerativeUIDispatch;
+    });
 
 /** Props for a component that only renders once complete — `$status` is always `"done"`. */
-type StaticRenderProps<P> = P & { children?: ReactNode; $status: "done" };
+type StaticRenderProps<P> = P & {
+  children?: ReactNode;
+  $status: "done";
+  $action?: Action;
+  $dispatch?: GenerativeUIDispatch;
+};
 
 /**
  * A component the model is allowed to render, with the schema for its props.
@@ -67,38 +117,3 @@ export type GenerativeUIComponent<P = any> =
  * This registry is the security boundary — any `type` not present is rejected.
  */
 export type GenerativeUILibrary = Record<string, GenerativeUIComponent>;
-
-/**
- * A component invocation — mirrors React's `ReactElement`.
- *
- * `type` selects a component from the {@link GenerativeUILibrary}; `props` are
- * passed to it. The `children` prop is special: it is itself a renderable
- * {@link GenerativeUINode}, drawn as generative UI rather than passed as data.
- *
- * On the wire the model emits the flattened form `{ $type, ...props }`, where
- * `$type` names the component so a real `type` prop never collides. This is the
- * normalized shape the renderer works with, the same way React normalizes
- * `createElement` arguments into an element.
- */
-export type GenerativeUIElement = {
-  type: string;
-  props: GenerativeUIProps;
-};
-
-/** Props passed to a component — mirrors a React component's props. */
-export type GenerativeUIProps = {
-  children?: GenerativeUINode;
-} & Record<string, unknown>;
-
-/**
- * Anything renderable as generative UI — mirrors React's `ReactNode`: an
- * element, primitive text, or a list of nodes.
- */
-export type GenerativeUINode =
-  | GenerativeUIElement
-  | string
-  | number
-  | boolean
-  | null
-  | undefined
-  | GenerativeUINode[];

package/src/vocabulary/alert.test.tsx

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { renderGenerativeUI } from "../renderGenerativeUI";
+import { alertVocabulary } from "./alert";
+import { defaultGenerativeUILibrary } from "./index";
+
+const render = (node: unknown) =>
+  renderToStaticMarkup(<>{renderGenerativeUI(node, alertVocabulary)}</>);
+
+describe("alertVocabulary", () => {
+  it("Alert renders with title/description/tone, defaulting tone to info", () => {
+    expect(
+      render({
+        $type: "Alert",
+        title: "Heads up",
+        description: "Something happened",
+      }),
+    ).toBe(
+      '<div data-aui="alert" data-aui-tone="info" role="alert"><header data-aui="alert-title">Heads up</header><p data-aui="alert-desc">Something happened</p></div>',
+    );
+  });
+
+  it("Alert renders an explicit tone", () => {
+    expect(
+      render({ $type: "Alert", tone: "danger", title: "Error" }),
+    ).toContain('data-aui-tone="danger"');
+  });
+
+  it("Carousel wraps each child Card in a slide, capped at 10", () => {
+    const children = Array.from({ length: 12 }, (_, i) => ({
+      $type: "Card",
+      title: `c${i}`,
+    }));
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          { $type: "Carousel", children },
+          defaultGenerativeUILibrary,
+        )}
+      </>,
+    );
+    const slideCount = (html.match(/data-aui="carousel-slide"/g) ?? []).length;
+    expect(slideCount).toBe(10);
+  });
+
+  it("Carousel renders a single non-array child Card in one slide", () => {
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          {
+            $type: "Carousel",
+            children: { $type: "Card", title: "only" } as never,
+          },
+          defaultGenerativeUILibrary,
+        )}
+      </>,
+    );
+    expect((html.match(/data-aui="carousel-slide"/g) ?? []).length).toBe(1);
+  });
+
+  it("Carousel with no children renders an empty container", () => {
+    expect(render({ $type: "Carousel" })).toBe(
+      '<div data-aui="carousel"></div>',
+    );
+  });
+});

package/src/vocabulary/alert.tsx

@@ -0,0 +1,47 @@
+import { Children } from "react";
+import { z } from "zod";
+import type { GenerativeUILibrary } from "../types";
+import { ALERT_TONES } from "../ir";
+
+const MAX_CARDS = 10;
+
+export const alertVocabulary = {
+  Alert: {
+    description:
+      "A highlighted message conveying urgency. `tone` drives the severity.",
+    properties: z.object({
+      title: z.string().optional().describe("Alert title."),
+      description: z
+        .string()
+        .optional()
+        .describe("Supporting description text."),
+      tone: z
+        .enum(ALERT_TONES)
+        .optional()
+        .describe("Severity tone; defaults to `info`."),
+    }),
+    render: ({ title, description, tone, children }) => (
+      <div data-aui="alert" data-aui-tone={tone ?? "info"} role="alert">
+        {title ? <header data-aui="alert-title">{title}</header> : null}
+        {description ? <p data-aui="alert-desc">{description}</p> : null}
+        {children}
+      </div>
+    ),
+  },
+  Carousel: {
+    description: "A horizontally scrollable group of `Card` children (max 10).",
+    properties: z.object({}),
+    render: ({ children }) => {
+      const cards = Children.toArray(children).slice(0, MAX_CARDS);
+      return (
+        <div data-aui="carousel">
+          {cards.map((card, i) => (
+            <div key={i} data-aui="carousel-slide">
+              {card}
+            </div>
+          ))}
+        </div>
+      );
+    },
+  },
+} satisfies GenerativeUILibrary;

package/src/vocabulary/data.test.tsx

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { renderGenerativeUI } from "../renderGenerativeUI";
+import { dataVocabulary } from "./data";
+
+const render = (node: unknown) =>
+  renderToStaticMarkup(<>{renderGenerativeUI(node, dataVocabulary)}</>);
+
+describe("dataVocabulary", () => {
+  it("Table renders columns and rows", () => {
+    const html = render({
+      $type: "Table",
+      columns: [{ label: "Name" }, { label: "Age" }],
+      rows: [
+        ["Ada", 36],
+        ["Bob", 24],
+      ],
+    });
+    expect(html).toContain('data-aui="table"');
+    expect(html).toContain('<th data-aui="table-col">Name</th>');
+    expect(html).toContain('<th data-aui="table-col">Age</th>');
+    expect(html).toContain("<td>Ada</td>");
+    expect(html).toContain("<td>36</td>");
+    expect(html).toContain("<td>Bob</td>");
+    expect(html).toContain("<td>24</td>");
+  });
+
+  it("Table renders with only rows (no header)", () => {
+    const html = render({ $type: "Table", rows: [["only"]] });
+    expect(html).toContain('data-aui="table"');
+    expect(html).not.toContain("<thead>");
+    expect(html).toContain("<td>only</td>");
+  });
+
+  it("Markdown renders the value in a div", () => {
+    expect(render({ $type: "Markdown", value: "# hi" })).toBe(
+      '<div data-aui="markdown"># hi</div>',
+    );
+  });
+
+  it("Markdown renders partial value while streaming", () => {
+    expect(
+      renderToStaticMarkup(
+        <>
+          {renderGenerativeUI(
+            { $type: "Markdown", value: "partial" },
+            dataVocabulary,
+            { status: "streaming" },
+          )}
+        </>,
+      ),
+    ).toBe('<div data-aui="markdown">partial</div>');
+  });
+
+  it("Chart renders a placeholder div with variant/color/data hooks", () => {
+    const html = render({
+      $type: "Chart",
+      variant: "bar",
+      data: [{ label: "a", value: 1 }],
+      color: "#f00",
+    });
+    expect(html).toContain('data-aui="chart"');
+    expect(html).toContain('data-aui-variant="bar"');
+    expect(html).toContain('data-aui-color="#f00"');
+    expect(html).toContain("&quot;value&quot;:1");
+  });
+});

package/src/vocabulary/data.tsx

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import type { GenerativeUILibrary } from "../types";
+
+const columnSchema = z.object({
+  label: z.string().describe("Column header label."),
+});
+
+const cellSchema = z
+  .union([z.string(), z.number(), z.boolean()])
+  .describe("A cell value.");
+
+export const dataVocabulary = {
+  Table: {
+    description:
+      "Tabular data. Provide `columns` and `rows`; each row is an array of cells matching the columns.",
+    properties: z.object({
+      columns: z.array(columnSchema).optional().describe("Column definitions."),
+      rows: z.array(z.array(cellSchema)).optional().describe("Rows of cells."),
+    }),
+    render: ({ columns, rows, children }) => (
+      <table data-aui="table">
+        {columns?.length ? (
+          <thead>
+            <tr>
+              {columns.map((c: { label: string }, i: number) => (
+                <th key={i} data-aui="table-col">
+                  {c.label}
+                </th>
+              ))}
+            </tr>
+          </thead>
+        ) : null}
+        {rows?.length ? (
+          <tbody>
+            {rows.map((row: (string | number | boolean)[], r: number) => (
+              <tr key={r}>
+                {row.map((cell: string | number | boolean, c: number) => (
+                  <td key={c}>{String(cell)}</td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        ) : null}
+        {children}
+      </table>
+    ),
+  },
+  Markdown: {
+    description:
+      "A markdown string. Rendered as-is by default; override this component for a full markdown renderer.",
+    properties: z.object({
+      value: z.string().describe("Markdown source."),
+    }),
+    streamProperties: true,
+    render: ({ value, children }) => (
+      <div data-aui="markdown">
+        {value}
+        {children}
+      </div>
+    ),
+  },
+  Chart: {
+    description:
+      "A chart placeholder. Carries variant and data for a client renderer to draw.",
+    properties: z.object({
+      variant: z.enum(["bar", "line", "sparkline"]).describe("Chart variant."),
+      data: z
+        .array(
+          z.object({
+            label: z.string().optional(),
+            value: z.number(),
+          }),
+        )
+        .describe("Data points."),
+      color: z.string().optional().describe("Series color."),
+    }),
+    render: ({ variant, data, color }) => (
+      <div
+        data-aui="chart"
+        data-aui-variant={variant}
+        data-aui-color={color}
+        data-aui-data={JSON.stringify(data)}
+      />
+    ),
+  },
+} satisfies GenerativeUILibrary;

package/src/vocabulary/fact.test.tsx

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { renderGenerativeUI } from "../renderGenerativeUI";
+import { factVocabulary } from "./fact";
+
+const render = (node: unknown) =>
+  renderToStaticMarkup(<>{renderGenerativeUI(node, factVocabulary)}</>);
+
+describe("factVocabulary", () => {
+  it("Fact renders a label/value pair inside a dl", () => {
+    expect(render({ $type: "Fact", label: "Status", value: "open" })).toBe(
+      '<dl data-aui="fact"><dt data-aui="fact-label">Status</dt><dd data-aui="fact-value">open</dd></dl>',
+    );
+  });
+});

package/src/vocabulary/fact.tsx

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import type { GenerativeUILibrary } from "../types";
+
+export const factVocabulary = {
+  Fact: {
+    description:
+      "A label/value pair, rendered as a key followed by its value. Use for compact metadata.",
+    properties: z.object({
+      label: z.string().describe("The fact label (key)."),
+      value: z.string().describe("The fact value."),
+    }),
+    render: ({ label, value, children }) => (
+      <dl data-aui="fact">
+        <dt data-aui="fact-label">{label}</dt>
+        <dd data-aui="fact-value">
+          {value}
+          {children}
+        </dd>
+      </dl>
+    ),
+  },
+} satisfies GenerativeUILibrary;

package/src/vocabulary/index.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import { buildPresentParameters } from "../buildPresentParameters";
+import { defaultGenerativeUILibrary } from "./index";
+
+const EXPECTED_KEYS = [
+  "Header",
+  "Text",
+  "Caption",
+  "Image",
+  "Divider",
+  "Fact",
+  "Button",
+  "Select",
+  "Input",
+  "DatePicker",
+  "Card",
+  "Col",
+  "Row",
+  "Spacer",
+  "Badge",
+  "Table",
+  "Markdown",
+  "Chart",
+  "Alert",
+  "Carousel",
+] as const;
+
+describe("defaultGenerativeUILibrary", () => {
+  it("exposes exactly the closed vocabulary set, no stray or missing entries", () => {
+    expect(Object.keys(defaultGenerativeUILibrary).sort()).toEqual(
+      [...EXPECTED_KEYS].sort(),
+    );
+  });
+
+  it("every entry has a description, a zod properties schema, and a render fn", () => {
+    for (const [name, entry] of Object.entries(defaultGenerativeUILibrary)) {
+      expect(typeof entry.description, `${name}.description`).toBe("string");
+      expect(typeof entry.render, `${name}.render`).toBe("function");
+      expect(
+        typeof (entry.properties as { safeParse?: unknown }).safeParse,
+        `${name}.properties is a zod schema`,
+      ).toBe("function");
+    }
+  });
+
+  it("buildPresentParameters produces a $type enum of the vocabulary names", () => {
+    const schema = buildPresentParameters(defaultGenerativeUILibrary) as Record<
+      string,
+      unknown
+    >;
+    const typeProp = (schema.properties as Record<string, unknown>)[
+      "$type"
+    ] as { enum?: unknown[] };
+    expect(typeProp.enum).toEqual([...EXPECTED_KEYS]);
+  });
+});