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

package/src/buildPresentParameters.ts

@@ -6,10 +6,11 @@ import type { GenerativeUILibrary } from "./types";
 /**
  * Builds the JSON schema for the `present` tool from a {@link GenerativeUILibrary}.
  *
- * The model produces a node `{ $type, ...props }` where `$type` selects a
- * component and the rest are its props. The schema is a flat object: `$type` is
- * an enum of the component names, every component's props are merged into one
- * optional bag, and `children` recurses via `$defs` so the tree can nest.
+ * The model produces a node `{ $type, $key?, ...props }` where `$type` selects
+ * a component, the optional `$key` pins a stable identity for list items that
+ * may reorder, and the rest are its props. The schema is a flat object: `$type`
+ * is an enum of the component names, every component's props are merged into
+ * one optional bag, and `children` recurses via `$defs` so the tree can nest.
  *
  * It is intentionally flat rather than a per-`$type` discriminated union. Tool /
  * function-call schemas (OpenAI and others) require the top-level parameters to
@@ -24,10 +25,10 @@ export function buildPresentParameters(
 ): JSONSchema7 {
   const names = Object.keys(library);
 
-  // Merge every component's props into one optional bag. `$type`/`children` are
-  // framework-reserved, so drop any author-declared copies. On a name clash the
-  // first component's schema wins — props are an advisory hint here, not a
-  // strict per-component contract.
+  // Merge every component's props into one optional bag. `$`-prefixed keys and
+  // `children` are framework-reserved (see ir.ts), so drop any author-declared
+  // copies. On a name clash the first component's schema wins — props are an
+  // advisory hint here, not a strict per-component contract.
   const props: Record<string, JSONSchema7Definition> = {};
   const propOwners = new Map<string, string[]>();
   for (const name of names) {
@@ -39,7 +40,7 @@ export function buildPresentParameters(
       );
     }
     for (const [key, schema] of Object.entries(propsSchema.properties ?? {})) {
-      if (key === TYPE_KEY || key === "children") continue;
+      if (key.startsWith("$") || key === "children") continue;
       if (!(key in props)) {
         props[key] = schema;
       }
@@ -72,6 +73,11 @@ export function buildPresentParameters(
     type: "object",
     properties: {
       [TYPE_KEY]: { type: "string", enum: names, description: typeDescription },
+      $key: {
+        description:
+          "Stable identity for this UI node. Use it for list items that may reorder.",
+        anyOf: [{ type: "string" }, { type: "number" }],
+      },
       ...props,
       children: { $ref: "#/$defs/children" },
     },

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.shared.ts

@@ -1,5 +1,6 @@
 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";
@@ -13,6 +14,7 @@ export {
   JUSTIFIES,
   BUTTON_STYLES,
   ALERT_TONES,
+  ICON_NAMES,
 } from "./ir";
 export { defaultGenerativeUILibrary } from "./vocabulary";
 export { createActionRegistry, emptyActionRegistry } from "./actionRegistry";
@@ -55,4 +57,5 @@ export type {
   Justify,
   ButtonStyle,
   AlertTone,
+  IconName,
 } from "./ir";

package/src/ir.ts

@@ -52,14 +52,40 @@ export const BUTTON_STYLES = [
 export type ButtonStyle = (typeof BUTTON_STYLES)[number];
 
 export const ALERT_TONES = ["info", "success", "warning", "danger"] as const;
-/** Maps to ChatKit `alert` severity levels. */
+/** A severity level, from informational to destructive. */
 export type AlertTone = (typeof ALERT_TONES)[number];
 
+export const ICON_NAMES = [
+  "sun",
+  "moon",
+  "cloud",
+  "rain",
+  "snow",
+  "wind",
+  "play",
+  "pause",
+  "check",
+  "x",
+  "star",
+  "heart",
+  "arrow-right",
+  "arrow-up-right",
+  "chevron-right",
+  "calendar",
+  "clock",
+  "map-pin",
+  "plane",
+  "truck",
+  "credit-card",
+  "user",
+  "search",
+  "bell",
+] as const;
+/** A name from the built-in icon set; the closed enum lets the model see exactly which icons exist. */
+export type IconName = (typeof ICON_NAMES)[number];
+
 /**
- * Behavior payload carried by an interactive node. `type` is resolved by the
- * host's action registry, not the renderer; keeping behavior as data keeps the
- * tree serializable so the same node renders on web and converts to a native
- * action id on Slack.
+ * Behavior payload carried by an interactive node. `type` is resolved by the host's action registry, not the renderer; keeping behavior as data keeps the tree serializable, so the same node renders on web while converters may bind the type to a native action id on other platforms.
  */
 export interface Action {
   readonly type: string;

package/src/renderGenerativeUI.test.tsx

@@ -212,6 +212,11 @@ describe("buildPresentParameters", () => {
     ]);
     // each component's description rides along on the $type enum.
     expect(schema.properties.$type.description).toContain("Card");
+    expect(schema.properties.$key).toEqual({
+      description:
+        "Stable identity for this UI node. Use it for list items that may reorder.",
+      anyOf: [{ type: "string" }, { type: "number" }],
+    });
     expect(schema.properties.children.$ref).toBe("#/$defs/children");
 
     // every component's props are merged into the one flat property bag.
@@ -228,12 +233,14 @@ describe("buildPresentParameters", () => {
     expect(schema.$defs.node.oneOf).toBeUndefined();
   });
 
-  it("drops author-declared `$type`/`children` and keeps the discriminator", () => {
+  it("drops author-declared `$`-prefixed and `children` props, keeping framework fields", () => {
     const schema = buildPresentParameters({
       Reserved: {
         description: "Declares reserved keys that must not leak through.",
         properties: z.object({
           $type: z.number(),
+          $key: z.boolean(),
+          $action: z.string(),
           children: z.number(),
           label: z.string(),
         }),
@@ -242,8 +249,15 @@ describe("buildPresentParameters", () => {
     }) as any;
 
     // The discriminator is the framework enum, not the author's `$type`; the
-    // author's `children` is dropped (the root `children` $ref owns that slot).
+    // author's `$`-prefixed props and `children` are dropped in favor of the
+    // framework fields.
     expect(schema.properties.$type.enum).toEqual(["Reserved"]);
+    expect(schema.properties.$key).toEqual({
+      description:
+        "Stable identity for this UI node. Use it for list items that may reorder.",
+      anyOf: [{ type: "string" }, { type: "number" }],
+    });
+    expect(schema.properties.$action).toBeUndefined();
     expect(schema.properties.children.$ref).toBe("#/$defs/children");
     expect(schema.properties.label).toBeDefined();
     expect(schema.required).toEqual(["$type"]);