@assistant-ui/react-generative-ui 0.0.6 → 0.0.8

package/src/generativeUIToJSX.test.ts

@@ -1,6 +1,16 @@
 import { describe, it, expect } from "vitest";
 import { generativeUIToJSX } from "./generativeUIToJSX";
 
+describe("generativeUIToJSX pretty depth bound", () => {
+  it("tolerates children nested in arrays beyond the depth bound", () => {
+    let node: unknown = { $type: "Text", value: "leaf" };
+    for (let i = 0; i < 100; i++) node = [node];
+    expect(() =>
+      generativeUIToJSX({ $type: "Card", children: node }, { pretty: true }),
+    ).not.toThrow();
+  });
+});
+
 describe("generativeUIToJSX", () => {
   it("renders a leaf element as a self-closing tag", () => {
     expect(generativeUIToJSX({ $type: "Weather", id: "5d99d2e9" })).toBe(
@@ -31,6 +41,15 @@ describe("generativeUIToJSX", () => {
     );
   });
 
+  it("emits a model-provided $key as the JSX key attribute", () => {
+    expect(
+      generativeUIToJSX({ $type: "Text", $key: "1:Text", children: "hello" }),
+    ).toBe('<Text key="1:Text">hello</Text>');
+    expect(generativeUIToJSX({ $type: "Item", $key: 2 })).toBe(
+      "<Item key={2} />",
+    );
+  });
+
   it("renders string children between tags", () => {
     expect(
       generativeUIToJSX({ $type: "Text", tone: "muted", children: "hello" }),
@@ -62,3 +81,170 @@ describe("generativeUIToJSX", () => {
     expect(generativeUIToJSX({})).toBe(""); // no $type yet (still streaming)
   });
 });
+
+describe("generativeUIToJSX with escape: true", () => {
+  it("escapes a string child containing HTML-like tags", () => {
+    expect(
+      generativeUIToJSX(
+        { $type: "Text", children: "<script>alert(1)</script>" },
+        { escape: true },
+      ),
+    ).toBe('<Text>{"<script>alert(1)</script>"}</Text>');
+  });
+
+  it("escapes a string child containing braces", () => {
+    expect(
+      generativeUIToJSX(
+        { $type: "Text", children: "a {b} c" },
+        { escape: true },
+      ),
+    ).toBe('<Text>{"a {b} c"}</Text>');
+  });
+
+  it("escapes a string child containing an ampersand", () => {
+    expect(
+      generativeUIToJSX({ $type: "Text", children: "Q&A" }, { escape: true }),
+    ).toBe('<Text>{"Q&A"}</Text>');
+  });
+
+  it("leaves a plain text child verbatim", () => {
+    expect(
+      generativeUIToJSX(
+        { $type: "Text", children: "hello world" },
+        { escape: true },
+      ),
+    ).toBe("<Text>hello world</Text>");
+  });
+
+  it("leaves numbers, arrays, and nested objects unaffected", () => {
+    expect(
+      generativeUIToJSX(
+        {
+          $type: "Card",
+          children: [
+            { $type: "Text", children: 42 },
+            { $type: "Text", data: { a: 1 }, children: "plain" },
+          ],
+        },
+        { escape: true },
+      ),
+    ).toBe('<Card><Text>42</Text><Text data={{"a":1}}>plain</Text></Card>');
+  });
+});
+
+describe("generativeUIToJSX with pretty: true", () => {
+  const nestedCard = {
+    $type: "Card",
+    title: "Hi",
+    children: [
+      { $type: "Text", children: "a" },
+      {
+        $type: "Box",
+        children: { $type: "Text", tone: "muted", children: "b" },
+      },
+    ],
+  };
+
+  it("keeps default output single-line and byte-identical without pretty", () => {
+    expect(generativeUIToJSX(nestedCard)).toBe(
+      '<Card title="Hi"><Text>a</Text><Box><Text tone="muted">b</Text></Box></Card>',
+    );
+  });
+
+  it("block-nests elements with two-space grandchild indentation", () => {
+    expect(generativeUIToJSX(nestedCard, { pretty: true })).toBe(
+      [
+        '<Card title="Hi">',
+        "  <Text>a</Text>",
+        "  <Box>",
+        '    <Text tone="muted">b</Text>',
+        "  </Box>",
+        "</Card>",
+      ].join("\n"),
+    );
+  });
+
+  it("keeps elements with only string or number children on one line", () => {
+    expect(
+      generativeUIToJSX(
+        { $type: "Text", tone: "muted", children: "hello" },
+        { pretty: true },
+      ),
+    ).toBe('<Text tone="muted">hello</Text>');
+    expect(
+      generativeUIToJSX({ $type: "Text", children: 42 }, { pretty: true }),
+    ).toBe("<Text>42</Text>");
+    expect(generativeUIToJSX({ $type: "Divider" }, { pretty: true })).toBe(
+      "<Divider />",
+    );
+  });
+
+  it("renders a root-level array with each item on its own line", () => {
+    expect(
+      generativeUIToJSX(
+        [
+          { $type: "Text", children: "a" },
+          { $type: "Text", children: "b" },
+        ],
+        { pretty: true },
+      ),
+    ).toBe("<Text>a</Text>\n<Text>b</Text>");
+  });
+
+  it("puts mixed text and element children each on their own line", () => {
+    expect(
+      generativeUIToJSX(
+        {
+          $type: "Card",
+          children: ["hello", { $type: "Text", children: "world" }, 7],
+        },
+        { pretty: true },
+      ),
+    ).toBe(
+      ["<Card>", "  hello", "  <Text>world</Text>", "  7", "</Card>"].join(
+        "\n",
+      ),
+    );
+  });
+
+  it("skips non-renderable children without blank lines", () => {
+    expect(
+      generativeUIToJSX(
+        {
+          $type: "Card",
+          children: [
+            null,
+            { $type: "Text", children: "a" },
+            false,
+            { $type: "Text", children: "b" },
+            true,
+          ],
+        },
+        { pretty: true },
+      ),
+    ).toBe(
+      ["<Card>", "  <Text>a</Text>", "  <Text>b</Text>", "</Card>"].join("\n"),
+    );
+  });
+
+  it("composes escape with pretty", () => {
+    expect(
+      generativeUIToJSX(
+        {
+          $type: "Card",
+          children: {
+            $type: "Text",
+            children: "<script>alert(1)</script>",
+          },
+        },
+        { escape: true, pretty: true },
+      ),
+    ).toBe(
+      [
+        "<Card>",
+        '  <Text>{"<script>alert(1)</script>"}</Text>',
+        "</Card>",
+      ].join("\n"),
+    );
+  });
+});

package/src/generativeUIToJSX.ts

@@ -1,18 +1,27 @@
 import { TYPE_KEY } from "./constants";
 
+/** Options for {@link generativeUIToJSX}. */
+export interface GenerativeUIToJSXOptions {
+  /** Escape string children so the output is safe to paste back into a JSX file. Defaults to `false`. */
+  escape?: boolean;
+  /** Pretty-print nested element trees with two-space indentation. Defaults to `false`. */
+  pretty?: boolean;
+}
+
 /**
- * Serializes a generative-UI node to a JSX-like string for display — the
- * "view source" of a model-produced tree. The wire form
- * `{ $type: "Weather", id: "x" }` becomes `<Weather id="x" />`, and nested
- * `children` render between tags: `<Card title="Hi"><Text>hello</Text></Card>`.
+ * Serializes a generative-UI node to a JSX-like string for display: the "view source" of a model-produced tree. The wire form `{ $type: "Weather", id: "x" }` becomes `<Weather id="x" />`, and nested `children` render between tags: `<Card title="Hi"><Text>hello</Text></Card>`. A model-provided `$key` becomes the JSX `key` attribute.
+ *
+ * By default this is a faithful textual rendering, not a parser: text children are emitted verbatim (not HTML/JSX-escaped), so the result is meant to be shown, not re-parsed. Returns `""` for nodes that aren't renderable (no `$type` yet, `null`, booleans).
  *
- * It is a faithful textual rendering, not a parser: text children are emitted
- * verbatim (not HTML/JSX-escaped), so the result is meant to be shown, not
- * re-parsed. Returns `""` for nodes that aren't renderable (no `$type` yet,
- * `null`, booleans).
+ * Pass `{ escape: true }` to make the output safe to paste back into JSX: any string child containing `<`, `>`, `&`, `{`, or `}` is emitted as a JSON-stringified expression (`{JSON.stringify(child)}`) instead of verbatim, while a string child with none of those characters still renders verbatim.
+ *
+ * Pass `{ pretty: true }` to pretty-print nested element trees with two-space indentation, while pure text children stay on one line.
  */
-export function generativeUIToJSX(node: unknown): string {
-  return toJSX(node, 0);
+export function generativeUIToJSX(
+  node: unknown,
+  options?: GenerativeUIToJSXOptions,
+): string {
+  return toJSX(node, 0, options?.escape ?? false, options?.pretty ?? false, 0);
 }
 
 /**
@@ -22,30 +31,112 @@ export function generativeUIToJSX(node: unknown): string {
  */
 const MAX_DEPTH = 64;
 
-function toJSX(node: unknown, depth: number): string {
+/** Characters that would break JSX if emitted verbatim inside a text child. */
+const UNSAFE_CHILD_CHARS = /[<>&{}]/;
+
+function toJSX(
+  node: unknown,
+  depth: number,
+  escape: boolean,
+  pretty: boolean,
+  indent: number,
+): string {
   if (depth > MAX_DEPTH) return "";
   if (node == null || typeof node === "boolean") return "";
-  if (typeof node === "string") return node;
+  if (typeof node === "string") return formatChildText(node, escape);
   if (typeof node === "number") return String(node);
-  if (Array.isArray(node))
-    return node.map((child) => toJSX(child, depth + 1)).join("");
+  if (Array.isArray(node)) {
+    if (pretty) {
+      return collectBlockLines(node, depth, escape, indent).join("\n");
+    }
+    return node
+      .map((child) => toJSX(child, depth + 1, escape, false, 0))
+      .join("");
+  }
   if (typeof node !== "object") return "";
 
   const {
     [TYPE_KEY]: type,
+    $key,
     children,
     ...props
   } = node as Record<string, unknown>;
   if (typeof type !== "string") return "";
 
-  const attrs = Object.entries(props)
-    .map(([key, value]) => formatAttr(key, value))
-    .join("");
-  const inner = children === undefined ? "" : toJSX(children, depth + 1);
+  const attrs =
+    formatAttr("key", $key) +
+    Object.entries(props)
+      .map(([key, value]) => formatAttr(key, value))
+      .join("");
+
+  if (!pretty) {
+    const inner =
+      children === undefined
+        ? ""
+        : toJSX(children, depth + 1, escape, false, 0);
+
+    return inner === ""
+      ? `<${type}${attrs} />`
+      : `<${type}${attrs}>${inner}</${type}>`;
+  }
+
+  const pad = "  ".repeat(indent);
+
+  if (children === undefined || !hasElementChild(children)) {
+    const inner =
+      children === undefined
+        ? ""
+        : toJSX(children, depth + 1, escape, false, 0);
+    return inner === ""
+      ? `${pad}<${type}${attrs} />`
+      : `${pad}<${type}${attrs}>${inner}</${type}>`;
+  }
+
+  const lines = collectBlockLines(children, depth + 1, escape, indent + 1);
+  if (lines.length === 0) {
+    return `${pad}<${type}${attrs} />`;
+  }
+  return `${pad}<${type}${attrs}>\n${lines.join("\n")}\n${pad}</${type}>`;
+}
+
+function hasElementChild(node: unknown, depth = 0): boolean {
+  if (depth > MAX_DEPTH) return false;
+  if (Array.isArray(node))
+    return node.some((child) => hasElementChild(child, depth + 1));
+  return (
+    node != null &&
+    typeof node === "object" &&
+    typeof (node as Record<string, unknown>)[TYPE_KEY] === "string"
+  );
+}
+
+function collectBlockLines(
+  node: unknown,
+  depth: number,
+  escape: boolean,
+  indent: number,
+): string[] {
+  if (depth > MAX_DEPTH) return [];
+  if (node == null || typeof node === "boolean") return [];
+  if (Array.isArray(node)) {
+    return node.flatMap((child) =>
+      collectBlockLines(child, depth + 1, escape, indent),
+    );
+  }
+  if (typeof node === "string") {
+    return [`${"  ".repeat(indent)}${formatChildText(node, escape)}`];
+  }
+  if (typeof node === "number") {
+    return [`${"  ".repeat(indent)}${String(node)}`];
+  }
+  const rendered = toJSX(node, depth, escape, true, indent);
+  return rendered === "" ? [] : [rendered];
+}
 
-  return inner === ""
-    ? `<${type}${attrs} />`
-    : `<${type}${attrs}>${inner}</${type}>`;
+function formatChildText(value: string, escape: boolean): string {
+  return escape && UNSAFE_CHILD_CHARS.test(value)
+    ? `{${JSON.stringify(value)}}`
+    : value;
 }
 
 /** Formats one prop as a JSX attribute (`id="x"`, `count={3}`, `open`, …). */

package/src/index.server.ts

@@ -0,0 +1,2 @@
+export { JSONGenerativeUI } from "./JSONGenerativeUI.server";
+export * from "./index.shared";

package/src/index.shared.ts

@@ -0,0 +1,61 @@
+export { renderGenerativeUI } from "./renderGenerativeUI";
+export { generativeUIToJSX } from "./generativeUIToJSX";
+export type { GenerativeUIToJSXOptions } from "./generativeUIToJSX";
+export { buildPresentParameters } from "./buildPresentParameters";
+export { defineGenerativeComponents } from "./defineGenerativeComponents";
+export { TYPE_KEY } from "./constants";
+export { normalizeUINode, normalizeSpec } from "./ir";
+export {
+  TEXT_SIZES,
+  IMAGE_SIZE_TOKENS,
+  WEIGHTS,
+  COLORS,
+  ALIGNS,
+  JUSTIFIES,
+  BUTTON_STYLES,
+  ALERT_TONES,
+  ICON_NAMES,
+} from "./ir";
+export { defaultGenerativeUILibrary } from "./vocabulary";
+export { createActionRegistry, emptyActionRegistry } from "./actionRegistry";
+export type {
+  ActionHandler,
+  ActionRegistry,
+  ActionDispatchContext,
+} from "./actionRegistry";
+export type {
+  JSONGenerativeUIOptions,
+  PresentTool,
+  PresentToolOptions,
+  PromptUserTool,
+} from "./JSONGenerativeUI.shared";
+export type {
+  GenerativeUILibrary,
+  GenerativeUIComponent,
+  GenerativeUIElement,
+  GenerativeUIProps,
+  GenerativeUINode,
+  GenerativeUIStatus,
+  GenerativeUIRenderContext,
+  GenerativeUIAction,
+  GenerativeUIDispatch,
+} from "./types";
+export type {
+  UINode,
+  UIElement,
+  UIChildren,
+  LegacyComponentNode,
+  Action,
+  UISpec,
+  NormalizedUINode,
+  NormalizedUIElement,
+  TextSize,
+  ImageSize,
+  Weight,
+  Color,
+  Align,
+  Justify,
+  ButtonStyle,
+  AlertTone,
+  IconName,
+} from "./ir";

package/src/index.ts

@@ -1,26 +1,2 @@
-// `JSONGenerativeUI` is the one export that differs per build: it comes from the
-// `./internal-json` subpath, which resolves to the server variant (schema only)
-// under the `react-server` condition and the client variant (adds render/execute)
-// otherwise. Everything else here is isomorphic, so this single entry serves
-// both conditions — no per-build index barrel needed.
-export { JSONGenerativeUI } from "@assistant-ui/react-generative-ui/internal-json";
-export { renderGenerativeUI } from "./renderGenerativeUI";
-export { generativeUIToJSX } from "./generativeUIToJSX";
-export { buildPresentParameters } from "./buildPresentParameters";
-export { defineGenerativeComponents } from "./defineGenerativeComponents";
-export { TYPE_KEY } from "./constants";
-export type {
-  JSONGenerativeUIOptions,
-  PresentTool,
-  PresentToolOptions,
-  PromptUserTool,
-} from "./JSONGenerativeUI.shared";
-export type {
-  GenerativeUILibrary,
-  GenerativeUIComponent,
-  GenerativeUIElement,
-  GenerativeUIProps,
-  GenerativeUINode,
-  GenerativeUIStatus,
-  GenerativeUIRenderContext,
-} from "./types";
+export { JSONGenerativeUI } from "./JSONGenerativeUI.client";
+export * from "./index.shared";

package/src/ir.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeSpec,
+  normalizeUINode,
+  type NormalizedUIElement,
+  type NormalizedUINode,
+} from "./ir";
+
+/** Narrows a normalized node to its element form for property assertions. */
+const asElement = (node: NormalizedUINode): NormalizedUIElement => {
+  if (node === null || typeof node === "string" || typeof node === "number") {
+    throw new Error(`expected an element, got ${node as unknown as string}`);
+  }
+  if (Array.isArray(node)) {
+    throw new Error("expected an element, got an array");
+  }
+  return node as NormalizedUIElement;
+};
+
+describe("normalizeUINode", () => {
+  describe("text leaf", () => {
+    it("passes a string through", () => {
+      expect(normalizeUINode("hello")).toBe("hello");
+    });
+  });
+
+  describe("legacy component shape", () => {
+    it("maps component + nested props to the canonical element", () => {
+      const node = asElement(
+        normalizeUINode({
+          component: "Card",
+          props: { padding: 4 },
+          children: ["inside"],
+          key: "c1",
+        }),
+      );
+
+      expect(node).toEqual({
+        type: "Card",
+        props: { padding: 4 },
+        children: ["inside"],
+        key: "c1",
+        action: undefined,
+      });
+    });
+
+    it("defaults missing props to an empty bag and carries no action", () => {
+      const node = asElement(normalizeUINode({ component: "Divider" }));
+      expect(node.props).toEqual({});
+      expect(node.children).toBeUndefined();
+      expect(node.action).toBeUndefined();
+    });
+  });
+
+  describe("flat $type shape", () => {
+    it("keeps inline props and strips reserved keys", () => {
+      const node = asElement(
+        normalizeUINode({
+          $type: "Text",
+          value: "hi",
+          size: "md",
+          weight: "semibold",
+        }),
+      );
+
+      expect(node.type).toBe("Text");
+      expect(node.props).toEqual({
+        value: "hi",
+        size: "md",
+        weight: "semibold",
+      });
+      expect(node.children).toBeUndefined();
+    });
+
+    it("lets a component use `type` as an ordinary prop (no collision)", () => {
+      const node = asElement(
+        normalizeUINode({
+          $type: "Button",
+          type: "submit",
+          label: "Go",
+        }),
+      );
+
+      expect(node.type).toBe("Button");
+      expect(node.props).toEqual({ type: "submit", label: "Go" });
+    });
+
+    it("routes a flat `$type` node with a `component` prop to the flat branch, not the legacy one", () => {
+      const node = asElement(
+        normalizeUINode({
+          $type: "Schema",
+          component: "display-name",
+          label: "Go",
+        }),
+      );
+
+      expect(node.type).toBe("Schema");
+      expect(node.props).toEqual({ component: "display-name", label: "Go" });
+    });
+
+    it("threads $action and $key through as action/key", () => {
+      const node = asElement(
+        normalizeUINode({
+          $type: "Button",
+          $key: "buy",
+          label: "Purchase",
+          $action: { type: "purchase", itemId: "sku-1" },
+        }),
+      );
+
+      expect(node.key).toBe("buy");
+      expect(node.action).toEqual({ type: "purchase", itemId: "sku-1" });
+      expect(node.props).toEqual({ label: "Purchase" });
+    });
+
+    it("strips the whole $-prefixed namespace from props (not just the named keys)", () => {
+      const node = asElement(
+        normalizeUINode({
+          $type: "Card",
+          $status: "done",
+          $custom: 1,
+          title: "hi",
+        }),
+      );
+
+      expect(node.props).toEqual({ title: "hi" });
+      expect("$status" in node.props).toBe(false);
+      expect("$custom" in node.props).toBe(false);
+    });
+  });
+
+  describe("nesting", () => {
+    it("recurses through children of both shapes", () => {
+      const node = asElement(
+        normalizeUINode({
+          $type: "Col",
+          children: [
+            { component: "Text", props: { value: "a" } },
+            { $type: "Text", value: "b" },
+            "leaf",
+          ],
+        }),
+      );
+
+      expect(node.children).toEqual([
+        {
+          type: "Text",
+          props: { value: "a" },
+          children: undefined,
+          key: undefined,
+          action: undefined,
+        },
+        {
+          type: "Text",
+          props: { value: "b" },
+          children: undefined,
+          key: undefined,
+          action: undefined,
+        },
+        "leaf",
+      ]);
+    });
+  });
+
+  describe("malformed input", () => {
+    it("resolves a node without $type or component to null", () => {
+      expect(normalizeUINode({ foo: "bar" } as unknown as never)).toBeNull();
+    });
+
+    it("resolves non-record input: null and boolean to null, number to a text leaf", () => {
+      expect(normalizeUINode(null as unknown as never)).toBeNull();
+      expect(normalizeUINode(true as unknown as never)).toBeNull();
+      expect(normalizeUINode(42 as unknown as never)).toBe(42);
+    });
+  });
+});
+
+describe("normalizeSpec", () => {
+  it("normalizes a single root", () => {
+    expect(normalizeSpec({ $type: "Text", value: "x" }).root).toEqual({
+      type: "Text",
+      props: { value: "x" },
+      children: undefined,
+      key: undefined,
+      action: undefined,
+    });
+  });
+
+  it("normalizes a list root", () => {
+    const { root } = normalizeSpec([{ $type: "Text", value: "a" }, "b"]);
+    expect(Array.isArray(root)).toBe(true);
+    expect(root).toEqual([
+      {
+        type: "Text",
+        props: { value: "a" },
+        children: undefined,
+        key: undefined,
+        action: undefined,
+      },
+      "b",
+    ]);
+  });
+});