@assistant-ui/react-generative-ui 0.0.10 → 0.0.11

package/dist/a2ui/types.d.ts

@@ -0,0 +1,73 @@
+//#region src/a2ui/types.d.ts
+declare const A2UI_SURFACE_ID: unique symbol;
+type A2uiVersion = "v0.9" | "v1.0";
+interface A2uiTemplateChildren {
+  readonly template: {
+    readonly componentId: string;
+    readonly path: string;
+  };
+}
+interface ComponentNode extends Record<string, unknown> {
+  readonly id: string;
+  readonly component: string;
+  readonly children?: readonly string[] | A2uiTemplateChildren;
+}
+interface A2uiCreateSurfaceV09Payload {
+  readonly surfaceId: string;
+  readonly catalogId?: string;
+  readonly theme?: unknown;
+  readonly attachDataModel?: unknown;
+}
+interface A2uiCreateSurfaceV10Payload {
+  readonly surfaceId: string;
+  readonly surfaceProperties?: unknown;
+  readonly sendDataModel?: unknown;
+  readonly components?: readonly ComponentNode[];
+  readonly dataModel?: unknown;
+}
+interface A2uiUpdateComponentsPayload {
+  readonly surfaceId: string;
+  readonly components: readonly ComponentNode[];
+}
+interface A2uiUpdateDataModelPayload {
+  readonly surfaceId: string;
+  readonly path?: string;
+  readonly contents?: unknown;
+  readonly value?: unknown;
+  readonly data?: unknown;
+}
+interface A2uiDeleteSurfacePayload {
+  readonly surfaceId: string;
+}
+type A2uiCreateSurfaceOperation = {
+  readonly version: "v0.9";
+  readonly createSurface: A2uiCreateSurfaceV09Payload;
+} | {
+  readonly version: "v1.0";
+  readonly createSurface: A2uiCreateSurfaceV10Payload;
+};
+interface A2uiUpdateComponentsOperation {
+  readonly version: A2uiVersion;
+  readonly updateComponents: A2uiUpdateComponentsPayload;
+}
+interface A2uiUpdateDataModelOperation {
+  readonly version: A2uiVersion;
+  readonly updateDataModel: A2uiUpdateDataModelPayload;
+}
+interface A2uiDeleteSurfaceOperation {
+  readonly version: A2uiVersion;
+  readonly deleteSurface: A2uiDeleteSurfacePayload;
+}
+type A2uiOperation = A2uiCreateSurfaceOperation | A2uiUpdateComponentsOperation | A2uiUpdateDataModelOperation | A2uiDeleteSurfaceOperation;
+type A2uiSurfaceState = {
+  components: Map<string, Record<string, unknown>>;
+  dataModel: unknown;
+};
+type A2uiState = ReadonlyMap<string, A2uiSurfaceState>;
+interface A2uiOperationResult {
+  readonly state: A2uiState;
+  readonly warnings: string[];
+}
+//#endregion
+export { A2UI_SURFACE_ID, A2uiCreateSurfaceOperation, A2uiCreateSurfaceV09Payload, A2uiCreateSurfaceV10Payload, A2uiDeleteSurfaceOperation, A2uiDeleteSurfacePayload, A2uiOperation, A2uiOperationResult, A2uiState, A2uiSurfaceState, A2uiTemplateChildren, A2uiUpdateComponentsOperation, A2uiUpdateComponentsPayload, A2uiUpdateDataModelOperation, A2uiUpdateDataModelPayload, A2uiVersion, ComponentNode };
+//# sourceMappingURL=types.d.ts.map

package/dist/a2ui/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/a2ui/types.ts"],"mappings":";cAAa;KAED;UAEK;WACN;aACE;aACA;;;UAII,sBAAsB;WAC5B;WACA;WACA,+BAA+B;;UAGzB;WACN;WACA;WACA;WACA;;UAGM;WACN;WACA;WACA;WACA,sBAAsB;WACtB;;UAGM;WACN;WACA,qBAAqB;;UAGf;WACN;WACA;WACA;WACA;WACA;;UAGM;WACN;;KAGC;WAEG;WACA,eAAe;;WAGf;WACA,eAAe;;UAGb;WACN,SAAS;WACT,kBAAkB;;UAGZ;WACN,SAAS;WACT,iBAAiB;;UAGX;WACN,SAAS;WACT,eAAe;;KAGd,gBACR,6BACA,gCACA,+BACA;KAEQ;EACV,YAAY,YAAY;EACxB;;KAGU,YAAY,oBAAoB;UAE3B;WACN,OAAO;WACP"}

package/dist/a2ui/types.js

@@ -0,0 +1,6 @@
+//#region src/a2ui/types.ts
+const A2UI_SURFACE_ID = Symbol("a2uiSurfaceId");
+//#endregion
+export { A2UI_SURFACE_ID };
+
+//# sourceMappingURL=types.js.map

package/dist/a2ui/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../src/a2ui/types.ts"],"sourcesContent":["export const A2UI_SURFACE_ID = Symbol(\"a2uiSurfaceId\");\n\nexport type A2uiVersion = \"v0.9\" | \"v1.0\";\n\nexport interface A2uiTemplateChildren {\n  readonly template: {\n    readonly componentId: string;\n    readonly path: string;\n  };\n}\n\nexport interface ComponentNode extends Record<string, unknown> {\n  readonly id: string;\n  readonly component: string;\n  readonly children?: readonly string[] | A2uiTemplateChildren;\n}\n\nexport interface A2uiCreateSurfaceV09Payload {\n  readonly surfaceId: string;\n  readonly catalogId?: string;\n  readonly theme?: unknown;\n  readonly attachDataModel?: unknown;\n}\n\nexport interface A2uiCreateSurfaceV10Payload {\n  readonly surfaceId: string;\n  readonly surfaceProperties?: unknown;\n  readonly sendDataModel?: unknown;\n  readonly components?: readonly ComponentNode[];\n  readonly dataModel?: unknown;\n}\n\nexport interface A2uiUpdateComponentsPayload {\n  readonly surfaceId: string;\n  readonly components: readonly ComponentNode[];\n}\n\nexport interface A2uiUpdateDataModelPayload {\n  readonly surfaceId: string;\n  readonly path?: string;\n  readonly contents?: unknown;\n  readonly value?: unknown;\n  readonly data?: unknown;\n}\n\nexport interface A2uiDeleteSurfacePayload {\n  readonly surfaceId: string;\n}\n\nexport type A2uiCreateSurfaceOperation =\n  | {\n      readonly version: \"v0.9\";\n      readonly createSurface: A2uiCreateSurfaceV09Payload;\n    }\n  | {\n      readonly version: \"v1.0\";\n      readonly createSurface: A2uiCreateSurfaceV10Payload;\n    };\n\nexport interface A2uiUpdateComponentsOperation {\n  readonly version: A2uiVersion;\n  readonly updateComponents: A2uiUpdateComponentsPayload;\n}\n\nexport interface A2uiUpdateDataModelOperation {\n  readonly version: A2uiVersion;\n  readonly updateDataModel: A2uiUpdateDataModelPayload;\n}\n\nexport interface A2uiDeleteSurfaceOperation {\n  readonly version: A2uiVersion;\n  readonly deleteSurface: A2uiDeleteSurfacePayload;\n}\n\nexport type A2uiOperation =\n  | A2uiCreateSurfaceOperation\n  | A2uiUpdateComponentsOperation\n  | A2uiUpdateDataModelOperation\n  | A2uiDeleteSurfaceOperation;\n\nexport type A2uiSurfaceState = {\n  components: Map<string, Record<string, unknown>>;\n  dataModel: unknown;\n};\n\nexport type A2uiState = ReadonlyMap<string, A2uiSurfaceState>;\n\nexport interface A2uiOperationResult {\n  readonly state: A2uiState;\n  readonly warnings: string[];\n}\n"],"mappings":";AAAA,MAAa,kBAAkB,OAAO,eAAe"}

package/dist/a2ui.d.ts

@@ -0,0 +1,4 @@
+import { A2uiCreateSurfaceOperation, A2uiCreateSurfaceV09Payload, A2uiCreateSurfaceV10Payload, A2uiDeleteSurfaceOperation, A2uiDeleteSurfacePayload, A2uiOperation, A2uiOperationResult, A2uiState, A2uiSurfaceState, A2uiTemplateChildren, A2uiUpdateComponentsOperation, A2uiUpdateComponentsPayload, A2uiUpdateDataModelOperation, A2uiUpdateDataModelPayload, A2uiVersion, ComponentNode } from "./a2ui/types.js";
+import { applyA2uiOperations } from "./a2ui/reducer.js";
+import { convertSurfaceToUISpec } from "./a2ui/convert.js";
+export { type A2uiCreateSurfaceOperation, type A2uiCreateSurfaceV09Payload, type A2uiCreateSurfaceV10Payload, type A2uiDeleteSurfaceOperation, type A2uiDeleteSurfacePayload, type A2uiOperation, type A2uiOperationResult, type A2uiState, type A2uiSurfaceState, type A2uiTemplateChildren, type A2uiUpdateComponentsOperation, type A2uiUpdateComponentsPayload, type A2uiUpdateDataModelOperation, type A2uiUpdateDataModelPayload, type A2uiVersion, type ComponentNode, applyA2uiOperations, convertSurfaceToUISpec };

package/dist/a2ui.js

@@ -0,0 +1,3 @@
+import { applyA2uiOperations } from "./a2ui/reducer.js";
+import { convertSurfaceToUISpec } from "./a2ui/convert.js";
+export { applyA2uiOperations, convertSurfaceToUISpec };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/react-generative-ui",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Generative UI components for assistant-ui",
   "keywords": [
     "generative-ui",
@@ -28,6 +28,10 @@
       "types": "./dist/ir.d.ts",
       "default": "./dist/ir.js"
     },
+    "./a2ui": {
+      "types": "./dist/a2ui.d.ts",
+      "default": "./dist/a2ui.js"
+    },
     "./slack": {
       "types": "./dist/slack.d.ts",
       "default": "./dist/slack.js"
@@ -46,7 +50,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.29"
+    "assistant-stream": "^0.3.31"
   },
   "peerDependencies": {
     "@assistant-ui/react": "^0.15.0",
@@ -66,7 +70,7 @@
     "react-dom": "^19.2.8",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@assistant-ui/react": "0.15.0",
+    "@assistant-ui/react": "0.15.1",
     "@assistant-ui/x-buildutils": "0.0.20"
   },
   "publishConfig": {

package/src/a2ui/convert.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, it } from "vitest";
+import type { UIElement } from "../ir";
+import { convertSurfaceToUISpec } from "./convert";
+import { applyA2uiOperations } from "./reducer";
+import type { A2uiSurfaceState } from "./types";
+
+const surfaceFrom = (
+  components: readonly Record<string, unknown>[],
+  dataModel: unknown = {},
+): A2uiSurfaceState => ({
+  components: new Map(
+    components.map((component) => [
+      component["id"] as string,
+      { ...component },
+    ]),
+  ),
+  dataModel,
+});
+
+describe("convertSurfaceToUISpec", () => {
+  it("converts an operation-built A2UI surface to the exact canonical UISpec", () => {
+    const result = applyA2uiOperations(new Map(), [
+      {
+        version: "v0.9",
+        createSurface: { surfaceId: "main" },
+      },
+      {
+        version: "v0.9",
+        updateComponents: {
+          surfaceId: "main",
+          components: [
+            {
+              id: "root",
+              component: "Column",
+              gap: 2,
+              children: [
+                "heading",
+                "body",
+                "caption",
+                "image",
+                "row",
+                "card",
+                "divider",
+                "button",
+                "field",
+                "checkbox",
+              ],
+            },
+            {
+              id: "heading",
+              component: "Text",
+              variant: "h1",
+              text: { path: "/title" },
+            },
+            {
+              id: "body",
+              component: "Text",
+              text: { path: "/body" },
+            },
+            {
+              id: "caption",
+              component: "Text",
+              variant: "caption",
+              text: "Fine print",
+            },
+            {
+              id: "image",
+              component: "Image",
+              url: { path: "/imageUrl" },
+              altText: "Preview",
+            },
+            {
+              id: "row",
+              component: "Row",
+              gap: 1,
+              align: "center",
+              justify: "between",
+              children: ["rowText"],
+            },
+            {
+              id: "rowText",
+              component: "Text",
+              text: "Inside row",
+            },
+            {
+              id: "card",
+              component: "Card",
+              title: "Details",
+              padding: 3,
+            },
+            { id: "divider", component: "Divider", flush: true },
+            {
+              id: "button",
+              component: "Button",
+              label: "Open",
+              action: {
+                name: "open",
+                context: {
+                  ticketId: { path: "/ticketId" },
+                  literal: "kept",
+                  missing: { path: "/missing" },
+                },
+              },
+            },
+            {
+              id: "field",
+              component: "TextField",
+              label: "Email",
+              placeholder: "you@example.com",
+              text: { path: "/form/email" },
+            },
+            {
+              id: "checkbox",
+              component: "CheckBox",
+              label: "Accepted",
+              value: { path: "/form/accepted" },
+            },
+          ],
+        },
+      },
+      {
+        version: "v0.9",
+        updateDataModel: {
+          surfaceId: "main",
+          data: {
+            title: "Welcome",
+            body: "**Hello**",
+            imageUrl: "https://example.com/image.png",
+            ticketId: "ticket-1",
+            form: { email: "ada@example.com", accepted: true },
+          },
+        },
+      },
+    ]);
+    const surface = result.state.get("main");
+    expect(surface).toBeDefined();
+
+    const converted = convertSurfaceToUISpec(surface!);
+
+    expect(converted.warnings).toEqual([]);
+    expect(converted.spec).toEqual({
+      $type: "Col",
+      gap: 2,
+      children: [
+        { $type: "Header", text: "Welcome" },
+        { $type: "Markdown", value: "**Hello**" },
+        { $type: "Caption", value: "Fine print" },
+        {
+          $type: "Image",
+          src: "https://example.com/image.png",
+          alt: "Preview",
+        },
+        {
+          $type: "Row",
+          gap: 1,
+          align: "center",
+          justify: "between",
+          children: [{ $type: "Markdown", value: "Inside row" }],
+        },
+        { $type: "Card", title: "Details", padding: 3 },
+        { $type: "Divider", flush: true },
+        {
+          $type: "Button",
+          label: "Open",
+          $action: {
+            type: "a2ui:action",
+            name: "open",
+            surfaceId: "main",
+            sourceComponentId: "button",
+            context: { ticketId: "ticket-1", literal: "kept" },
+          },
+        },
+        {
+          $type: "Input",
+          label: "Email",
+          placeholder: "you@example.com",
+          name: "email",
+        },
+        {
+          $type: "Checkbox",
+          label: "Accepted",
+          name: "accepted",
+          defaultChecked: true,
+        },
+      ],
+    });
+  });
+
+  it("drops an unresolvable bound prop without throwing", () => {
+    const surface = surfaceFrom([
+      {
+        id: "root",
+        component: "Text",
+        text: { path: "/missing" },
+      },
+    ]);
+
+    expect(convertSurfaceToUISpec(surface)).toEqual({
+      spec: { $type: "Markdown" },
+      warnings: [],
+    });
+  });
+
+  it("expands template children relative to each bound item", () => {
+    const surface = surfaceFrom(
+      [
+        {
+          id: "root",
+          component: "Column",
+          children: {
+            template: { componentId: "item", path: "/items" },
+          },
+        },
+        {
+          id: "item",
+          component: "Text",
+          text: { path: "/name" },
+        },
+      ],
+      { items: [{ name: "one" }, { name: "two" }] },
+    );
+
+    expect(convertSurfaceToUISpec(surface)).toEqual({
+      spec: {
+        $type: "ListView",
+        children: [
+          {
+            $type: "ListViewItem",
+            children: { $type: "Markdown", value: "one" },
+          },
+          {
+            $type: "ListViewItem",
+            children: { $type: "Markdown", value: "two" },
+          },
+        ],
+      },
+      warnings: [],
+    });
+  });
+
+  it("caps template expansion at 100 items", () => {
+    const surface = surfaceFrom(
+      [
+        {
+          id: "root",
+          component: "Column",
+          children: {
+            template: { componentId: "item", path: "/items" },
+          },
+        },
+        {
+          id: "item",
+          component: "Text",
+          text: { path: "/" },
+        },
+      ],
+      { items: Array.from({ length: 101 }, (_, index) => `item-${index}`) },
+    );
+
+    const result = convertSurfaceToUISpec(surface);
+    expect((result.spec as UIElement).children).toHaveLength(100);
+    expect(result.warnings).toContain(
+      "A2UI template expansion was capped at 100 items.",
+    );
+  });
+
+  it("truncates a component cycle", () => {
+    const surface = surfaceFrom([
+      {
+        id: "root",
+        component: "Row",
+        children: ["root"],
+      },
+    ]);
+
+    expect(convertSurfaceToUISpec(surface)).toEqual({
+      spec: { $type: "Row" },
+      warnings: ['A2UI component cycle detected at "root".'],
+    });
+  });
+
+  it("truncates component resolution at depth 32", () => {
+    const components = Array.from({ length: 34 }, (_, index) => ({
+      id: index === 0 ? "root" : `node-${index}`,
+      component: "Row",
+      ...(index < 33
+        ? { children: [index === 0 ? "node-1" : `node-${index + 1}`] }
+        : {}),
+    }));
+    const result = convertSurfaceToUISpec(surfaceFrom(components));
+    let node = result.spec as UIElement;
+    let count = 1;
+    while (Array.isArray(node.children) && node.children.length > 0) {
+      node = node.children[0] as UIElement;
+      count++;
+    }
+
+    expect(count).toBe(32);
+    expect(result.warnings).toContain("A2UI depth cap of 32 was reached.");
+  });
+
+  it("enforces the total emitted node budget", () => {
+    const childCount = 5001;
+    const components = [
+      {
+        id: "root",
+        component: "Row",
+        children: Array.from(
+          { length: childCount },
+          (_, index) => `child-${index}`,
+        ),
+      },
+      ...Array.from({ length: childCount }, (_, index) => ({
+        id: `child-${index}`,
+        component: "Divider",
+      })),
+    ];
+    const result = convertSurfaceToUISpec(surfaceFrom(components));
+
+    expect((result.spec as UIElement).children).toHaveLength(4999);
+    expect(result.warnings).toContain("A2UI node budget of 5000 was reached.");
+  });
+
+  it("skips an unknown component with a warning naming it", () => {
+    const result = convertSurfaceToUISpec(
+      surfaceFrom([{ id: "root", component: "VideoPlayer" }]),
+    );
+
+    expect(result.spec).toBeNull();
+    expect(result.warnings).toEqual([
+      'Unknown A2UI component "VideoPlayer" was skipped.',
+    ]);
+  });
+
+  it("returns null with a warning when root is missing", () => {
+    expect(
+      convertSurfaceToUISpec(
+        surfaceFrom([{ id: "other", component: "Divider" }]),
+      ),
+    ).toEqual({
+      spec: null,
+      warnings: ['A2UI root component "root" was not found.'],
+    });
+  });
+});