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

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",
+    ]);
+  });
+});

package/src/ir.ts

@@ -0,0 +1,253 @@
+/**
+ * The generative-ui intermediate representation: a model-emitted, cross-platform
+ * UI tree. React-free, so converters and non-web runtimes consume it without
+ * pulling React. The flat `$type` shape is the canonical form; the legacy
+ * `component` shape is accepted as a backward-compatible alias.
+ *
+ * Reserved keys are partitioned off from component props so the component prop
+ * namespace stays fully free:
+ *
+ * - `$`-prefixed keys are framework-reserved (`$type`, `$key`, `$action`,
+ *   `$status`). Components never declare `$`-prefixed props, so a component
+ *   can use `type`, `status`, `variant`, etc. as ordinary props without
+ *   colliding with the framework.
+ * - `children` is additionally reserved (the JSX convention).
+ * - every other key is an inline prop passed straight to the component.
+ */
+
+import { TYPE_KEY } from "./constants";
+
+export const TEXT_SIZES = ["sm", "md", "lg", "xl", "2xl", "3xl"] as const;
+export type TextSize = (typeof TEXT_SIZES)[number];
+
+export const IMAGE_SIZE_TOKENS = ["sm", "md", "lg"] as const;
+export type ImageSize = (typeof IMAGE_SIZE_TOKENS)[number] | number;
+
+export const WEIGHTS = ["normal", "medium", "semibold", "bold"] as const;
+export type Weight = (typeof WEIGHTS)[number];
+
+export const COLORS = [
+  "emphasis",
+  "secondary",
+  "alpha-70",
+  "white",
+  "white-70",
+  "white-50",
+] as const;
+export type Color = (typeof COLORS)[number];
+
+export const ALIGNS = ["start", "center", "end"] as const;
+export type Align = (typeof ALIGNS)[number];
+
+export const JUSTIFIES = ["start", "center", "end", "between"] as const;
+export type Justify = (typeof JUSTIFIES)[number];
+
+export const BUTTON_STYLES = [
+  "primary",
+  "secondary",
+  "outline",
+  "ghost",
+  "danger",
+] as const;
+export type ButtonStyle = (typeof BUTTON_STYLES)[number];
+
+export const ALERT_TONES = ["info", "success", "warning", "danger"] as const;
+/** Maps to ChatKit `alert` severity levels. */
+export type AlertTone = (typeof ALERT_TONES)[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.
+ */
+export interface Action {
+  readonly type: string;
+  readonly [payload: string]: unknown;
+}
+
+/**
+ * Anything renderable as generative UI, as the model emits it. The renderer
+ * also accepts `number`, `boolean`, `null`, `undefined`, and arrays at the
+ * input boundary (numbers render as text, falsy/boolean as nothing, arrays as
+ * lists); {@link normalizeUINode} accepts that full range.
+ */
+export type UINode = string | number | UIElement | LegacyComponentNode;
+
+export type UIChildren = UINode | readonly UINode[];
+
+/** The flat node shape: inline props keep the tree compact and natural for a
+ * model to emit, instead of a nested `{ type, props }` bag. Reserved keys are
+ * stripped before props reach the component (see the module header). */
+export interface UIElement {
+  readonly $type: string;
+  readonly $key?: string | number;
+  readonly children?: UIChildren;
+  readonly $action?: Action;
+  readonly [prop: string]: unknown;
+}
+
+/**
+ * The legacy node shape: a `component` name plus a nested `props` bag. Kept
+ * for backward compatibility. New code authors the flat {@link UIElement}
+ * shape instead.
+ */
+export interface LegacyComponentNode {
+  readonly component: string;
+  readonly props?: Record<string, unknown>;
+  readonly children?: UIChildren;
+  readonly key?: string;
+}
+
+export type UISpec = UINode | readonly UINode[];
+
+/**
+ * A node normalized to a single canonical shape: a `type` string, an inline
+ * `props` bag, recursive `children`, an optional `key`, and an optional
+ * `action`. Renderers and platform converters consume this form, so they never
+ * branch on whether the model emitted the flat `$type` shape or the legacy
+ * `component` shape, and they never see the reserved `$`-prefixed keys leak
+ * into component props.
+ */
+export interface NormalizedUIElement {
+  readonly type: string;
+  readonly props: Readonly<Record<string, unknown>>;
+  readonly children?: NormalizedUINode | undefined;
+  readonly key?: string | number | undefined;
+  readonly action?: Action | undefined;
+}
+
+export type NormalizedUINode =
+  | string
+  | number
+  | readonly NormalizedUINode[]
+  | NormalizedUIElement
+  | null;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+type LegacyNodeRecord = { component: string } & Record<string, unknown>;
+
+const isLegacyNode = (
+  node: Record<string, unknown>,
+): node is LegacyNodeRecord => typeof node["component"] === "string";
+
+const isTypeNode = (node: Record<string, unknown>): node is UIElement =>
+  typeof node[TYPE_KEY] === "string";
+
+/** Bounds recursion so a runaway or adversarial model response cannot overflow
+ * the stack; past this depth (far beyond any real UI) we stop. */
+const MAX_DEPTH = 64;
+
+/**
+ * Steps a streaming partial path down into `key`. `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 descend(
+  partialPath: readonly string[] | undefined,
+  key: string,
+): readonly string[] | undefined {
+  return partialPath?.[0] === key ? partialPath.slice(1) : undefined;
+}
+
+/**
+ * Normalizes a generative-ui input to {@link NormalizedUINode}. The flat
+ * `$type` shape and the legacy `component` shape both map to the same canonical
+ * element, with reserved keys (`$type`, `$key`, `$action`, `children`) stripped
+ * from the prop bag. A node that carries neither a `$type` nor a `component`
+ * string is not renderable and resolves to `null` rather than throwing, so a
+ * partially-streamed or malformed node degrades to "render nothing".
+ *
+ * `partialPath` carries streaming state from the tool-args parse meta: a node
+ * whose `$type` is still mid-arrival is held back (resolves to `null`) until it
+ * completes, and the path is threaded into `children` so a nested streaming
+ * node is held back while completed siblings render. Omit it for a
+ * non-streaming (converter) normalize.
+ */
+export function normalizeUINode(
+  node: unknown,
+  partialPath?: readonly string[] | undefined,
+  depth = 0,
+): NormalizedUINode {
+  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) =>
+      normalizeUINode(child, descend(partialPath, String(index)), depth + 1),
+    );
+  if (!isRecord(node)) return null;
+
+  // The flat `$type` shape is the canonical form; detect it first so a flat
+  // node that happens to use `component` as an ordinary prop is not swallowed
+  // by the legacy `component`-shape branch.
+  if (isTypeNode(node)) {
+    if (partialPath?.length === 1 && partialPath[0] === TYPE_KEY) return null;
+    const { [TYPE_KEY]: type, $key, $action, children, ...rest } = node;
+    // The `$`-prefixed namespace is framework-reserved (see the module header),
+    // so any model-supplied `$`-prefixed key is stripped from the prop bag the
+    // component sees. `$type`/`$key`/`$action` are pulled above; sweep the rest
+    // (e.g. a stray `$status`) so it never leaks to converters or components.
+    const props = stripReservedProps(rest);
+    return {
+      type,
+      props,
+      children: normalizeChildren(children, partialPath, depth),
+      key: $key,
+      action: $action,
+    };
+  }
+
+  if (isLegacyNode(node)) {
+    const props = stripReservedProps(
+      (node.props ?? {}) as Record<string, unknown>,
+    );
+    return {
+      type: node.component,
+      props,
+      children: normalizeChildren(node.children, partialPath, depth),
+      key: node.key as string | undefined,
+    };
+  }
+
+  return null;
+}
+
+function stripReservedProps(
+  props: Record<string, unknown>,
+): Record<string, unknown> {
+  let out: Record<string, unknown> | undefined;
+  for (const key of Object.keys(props)) {
+    if (key.startsWith("$")) {
+      out ??= { ...props };
+      delete out[key];
+    }
+  }
+  return out ?? props;
+}
+
+function normalizeChildren(
+  children: unknown,
+  partialPath: readonly string[] | undefined,
+  depth: number,
+): NormalizedUINode | undefined {
+  if (children === undefined) return undefined;
+  return normalizeUINode(children, descend(partialPath, "children"), depth + 1);
+}
+
+/**
+ * Normalizes the root of a {@link UISpec}, preserving whether the root was a
+ * single node or a list.
+ */
+export function normalizeSpec(spec: UISpec): {
+  readonly root: NormalizedUINode | readonly NormalizedUINode[];
+} {
+  if (Array.isArray(spec)) {
+    return {
+      root: (spec as readonly UINode[]).map((node) => normalizeUINode(node)),
+    };
+  }
+  return { root: normalizeUINode(spec) };
+}

package/src/renderGenerativeUI.test.tsx

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi } from "vitest";
 import { renderToStaticMarkup } from "react-dom/server";
+import { isValidElement, type ReactElement } from "react";
 import { parsePartialJsonObject } from "assistant-stream/utils";
 import { z } from "zod";
 import { renderGenerativeUI } from "./renderGenerativeUI";
@@ -65,6 +66,28 @@ describe("renderGenerativeUI", () => {
     );
   });
 
+  it("uses stable $key for array items and keeps the positional fallback", () => {
+    const out = renderGenerativeUI(
+      [
+        { $type: "Text", $key: "1:Text", children: "first" },
+        { $type: "Text", children: "second" },
+        "plain",
+        { $type: "Text", $key: { id: "bad" }, children: "bad key" },
+      ],
+      library,
+    );
+
+    expect(Array.isArray(out)).toBe(true);
+    const elements = out as ReactElement[];
+    expect(elements.every(isValidElement)).toBe(true);
+    expect(elements.map((element) => element.key)).toEqual([
+      "model:1:Text",
+      "1:Text",
+      "2:#text",
+      "3:Text",
+    ]);
+  });
+
   it("passes a component's own `type` prop through without collision", () => {
     const html = renderToStaticMarkup(
       <>
@@ -226,6 +249,36 @@ describe("buildPresentParameters", () => {
     expect(schema.required).toEqual(["$type"]);
   });
 
+  it("names every component that declares the same prop in the dev warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      buildPresentParameters({
+        Select: {
+          description: "Selects an option.",
+          properties: z.object({ value: z.string() }),
+          render: () => null,
+        },
+        DatePicker: {
+          description: "Picks a date.",
+          properties: z.object({ value: z.string() }),
+          render: () => null,
+        },
+        Combobox: {
+          description: "Chooses from filtered options.",
+          properties: z.object({ value: z.string() }),
+          render: () => null,
+        },
+      });
+
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn).toHaveBeenCalledWith(
+        '[@assistant-ui/react-generative-ui] Prop "value" is declared by "Select", "DatePicker", and "Combobox"; keeping "Select"\'s schema. Rename or align the prop type to avoid an ambiguous schema.',
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   it("throws when a component's properties is not an object schema", () => {
     expect(() =>
       buildPresentParameters({