@assistant-ui/react-generative-ui 0.0.18 → 0.0.20

package/src/a2ui/convert.ts

@@ -1,4 +1,4 @@
-import type { UIElement } from "../ir";
+import { ICON_NAMES, type UIElement } from "../ir";
 import {
   A2UI_SURFACE_ID,
   type A2uiSurfaceState,
@@ -12,15 +12,22 @@ const NODE_BUDGET = 5000;
 const SUPPORTED_COMPONENTS = new Set([
   "Text",
   "Image",
+  "Icon",
   "Row",
   "Column",
+  "List",
   "Card",
   "Divider",
   "Button",
   "TextField",
   "CheckBox",
+  "ChoicePicker",
+  "DateTimeInput",
 ]);
 
+const ICON_NAME_SET: ReadonlySet<string> = new Set(ICON_NAMES);
+const ICON_SIZE_SET: ReadonlySet<string> = new Set(["sm", "md", "lg"]);
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
 
@@ -145,6 +152,7 @@ type ConversionContext = {
   depthWarned: boolean;
   budgetWarned: boolean;
   templateCapWarned: boolean;
+  readonly keepUnknownComponents: boolean;
 };
 
 const reserveNode = (context: ConversionContext): boolean => {
@@ -214,6 +222,21 @@ const mappedAction = (
   };
 };
 
+const choiceOptions = (value: unknown): { label: string; value: string }[] => {
+  if (!Array.isArray(value)) return [];
+  const options: { label: string; value: string }[] = [];
+  for (const option of value) {
+    if (
+      isRecord(option) &&
+      typeof option["label"] === "string" &&
+      typeof option["value"] === "string"
+    ) {
+      options.push({ label: option["label"], value: option["value"] });
+    }
+  }
+  return options;
+};
+
 const mappedProps = (
   node: Record<string, unknown>,
   props: Record<string, unknown>,
@@ -245,7 +268,7 @@ const mappedProps = (
 
   if (component === "Image") {
     const src = stringProp(props, ["src", "url"]);
-    const alt = stringProp(props, ["alt", "altText"]);
+    const alt = stringProp(props, ["alt", "altText", "description"]);
     const size = props["size"];
     const round = props["round"];
     return {
@@ -257,6 +280,17 @@ const mappedProps = (
     };
   }
 
+  if (component === "Icon") {
+    const name = stringProp(props, ["name"]);
+    if (!name || !ICON_NAME_SET.has(name)) return undefined;
+    const size = props["size"];
+    return {
+      $type: "Icon",
+      name,
+      ...(typeof size === "string" && ICON_SIZE_SET.has(size) ? { size } : {}),
+    };
+  }
+
   if (component === "Row") {
     const gap = props["gap"];
     const align = firstDefined(props, ["align", "alignment"]);
@@ -279,6 +313,18 @@ const mappedProps = (
     };
   }
 
+  if (component === "List") {
+    const direction = props["direction"];
+    const align = props["align"];
+    if (direction === "horizontal") {
+      return {
+        $type: "Row",
+        ...(typeof align === "string" ? { align } : {}),
+      };
+    }
+    return { $type: "ListView" };
+  }
+
   if (component === "Card") {
     const title = props["title"];
     const padding = props["padding"];
@@ -345,6 +391,55 @@ const mappedProps = (
     };
   }
 
+  if (component === "ChoicePicker") {
+    const options = choiceOptions(props["options"]);
+    const value = props["value"];
+    const defaultValue =
+      typeof value === "string"
+        ? value
+        : Array.isArray(value) && typeof value[0] === "string"
+          ? value[0]
+          : undefined;
+    const radioStyle =
+      props["variant"] === "radio" ||
+      props["variant"] === "single" ||
+      props["variant"] === "singleSelection" ||
+      props["displayStyle"] === "radio" ||
+      (props["variant"] === "mutuallyExclusive" &&
+        props["displayStyle"] !== "chips");
+    if (radioStyle) {
+      return {
+        $type: "RadioGroup",
+        options,
+        ...(label !== undefined ? { label } : {}),
+        ...(name !== undefined ? { name } : {}),
+        ...(defaultValue !== undefined ? { defaultValue } : {}),
+      };
+    }
+    const placeholder = stringProp(props, ["placeholder"]);
+    return {
+      $type: "Select",
+      options,
+      ...(placeholder !== undefined ? { placeholder } : {}),
+      ...(label !== undefined ? { label } : {}),
+      ...(name !== undefined ? { name } : {}),
+    };
+  }
+
+  if (component === "DateTimeInput") {
+    const value = stringProp(props, ["value"]);
+    const min = stringProp(props, ["min"]);
+    const max = stringProp(props, ["max"]);
+    return {
+      $type: "DatePicker",
+      ...(value !== undefined ? { value } : {}),
+      ...(min !== undefined ? { min } : {}),
+      ...(max !== undefined ? { max } : {}),
+      ...(label !== undefined ? { label } : {}),
+      ...(name !== undefined ? { name } : {}),
+    };
+  }
+
   return undefined;
 };
 
@@ -355,14 +450,23 @@ const convertTemplate = (
   context: ConversionContext,
   depth: number,
   visited: Set<string>,
+  retained?: UIElement,
+  mappedContainer?: UIElement,
 ): UIElement | null => {
   if (!reserveNode(context)) return null;
+  const horizontalList =
+    node["component"] === "List" &&
+    materialize(node["direction"], dataSource) === "horizontal";
+  const container = mappedContainer ??
+    retained ?? {
+      $type: horizontalList ? "Row" : "ListView",
+    };
   const list = resolvePointer(dataSource, templateChildren.template.path);
   if (!Array.isArray(list)) {
     context.warnings.push(
       `Template on component "${String(node["id"] ?? "")}" did not resolve to a list.`,
     );
-    return { $type: "ListView", children: [] };
+    return { ...container, children: [] };
   }
   const itemCount = Math.min(list.length, TEMPLATE_ITEM_CAP);
   if (list.length > TEMPLATE_ITEM_CAP && !context.templateCapWarned) {
@@ -373,7 +477,7 @@ const convertTemplate = (
   }
   const children: UIElement[] = [];
   for (let index = 0; index < itemCount; index++) {
-    if (!reserveNode(context)) break;
+    if (!retained && !horizontalList && !reserveNode(context)) break;
     const child = convertComponent(
       templateChildren.template.componentId,
       list[index],
@@ -381,12 +485,16 @@ const convertTemplate = (
       depth + 1,
       visited,
     );
-    children.push({
-      $type: "ListViewItem",
-      ...(child ? { children: child } : {}),
-    });
+    if (retained || horizontalList) {
+      if (child) children.push(child);
+    } else {
+      children.push({
+        $type: "ListViewItem",
+        ...(child ? { children: child } : {}),
+      });
+    }
   }
-  return { $type: "ListView", children };
+  return { ...container, children };
 };
 
 function convertComponent(
@@ -416,24 +524,24 @@ function convertComponent(
 
   visited.add(componentId);
   try {
-    const templateChildren = node["children"];
-    if (isTemplateChildren(templateChildren)) {
-      return convertTemplate(
-        node,
-        templateChildren,
-        dataSource,
-        context,
-        depth,
-        visited,
+    if (typeof component !== "string") {
+      context.warnings.push(
+        `Unknown A2UI component "${String(component ?? "")}" was skipped.`,
       );
+      return null;
     }
-    if (typeof component !== "string" || !SUPPORTED_COMPONENTS.has(component)) {
+    const templateChildren = node["children"];
+    const hasTemplate = isTemplateChildren(templateChildren);
+    if (
+      !SUPPORTED_COMPONENTS.has(component) &&
+      !context.keepUnknownComponents &&
+      !hasTemplate
+    ) {
       context.warnings.push(
-        `Unknown A2UI component "${String(component ?? "")}" was skipped.`,
+        `Unknown A2UI component "${component}" was skipped.`,
       );
       return null;
     }
-    if (!reserveNode(context)) return null;
     const props: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(node)) {
       if (key === "id" || key === "component" || key === "children") continue;
@@ -441,18 +549,54 @@ function convertComponent(
       if (resolved !== undefined) setOwnProperty(props, key, resolved);
     }
     const mapped = mappedProps(node, props, dataSource, context);
-    if (!mapped) return null;
+    if (!mapped && SUPPORTED_COMPONENTS.has(component)) {
+      context.warnings.push(
+        `A2UI component "${component}" could not be mapped and was skipped.`,
+      );
+      return null;
+    }
+    const retained =
+      !mapped && context.keepUnknownComponents
+        ? {
+            $type: component,
+            ...Object.fromEntries(
+              Object.entries(props).filter(([key]) => !key.startsWith("$")),
+            ),
+          }
+        : undefined;
+    if (hasTemplate) {
+      return convertTemplate(
+        node,
+        templateChildren,
+        dataSource,
+        context,
+        depth,
+        visited,
+        retained,
+        component === "List" ? mapped : undefined,
+      );
+    }
+    if (!reserveNode(context)) return null;
+    const converted = mapped ?? retained;
+    if (!converted) return null;
     const children = childrenOf(node, dataSource, context, depth, visited);
+    const listChildren =
+      component === "List" && mapped?.$type === "ListView"
+        ? children.map((child) => ({ $type: "ListViewItem", children: child }))
+        : children;
     return {
-      ...mapped,
-      ...(children.length > 0 ? { children } : {}),
+      ...converted,
+      ...(listChildren.length > 0 ? { children: listChildren } : {}),
     };
   } finally {
     visited.delete(componentId);
   }
 }
 
-export function convertSurfaceToUISpec(surface: A2uiSurfaceState): {
+export function convertSurfaceToUISpec(
+  surface: A2uiSurfaceState,
+  options: { readonly keepUnknownComponents?: boolean } = {},
+): {
   spec: UIElement | null;
   warnings: string[];
 } {
@@ -471,6 +615,7 @@ export function convertSurfaceToUISpec(surface: A2uiSurfaceState): {
     depthWarned: false,
     budgetWarned: false,
     templateCapWarned: false,
+    keepUnknownComponents: options.keepUnknownComponents === true,
   };
   try {
     const spec = convertComponent(

package/src/a2ui/reducer.test.ts

@@ -35,6 +35,7 @@ describe("applyA2uiOperations", () => {
     expect(initial.size).toBe(0);
     expect(created.warnings).toEqual([]);
     expect(created.state.get("main")).toMatchObject({
+      catalogId: "default",
       dataModel: { profile: { name: "Ada" } },
     });
     expect(created.state.get("main")?.components.get("root")).toEqual({
@@ -61,6 +62,7 @@ describe("applyA2uiOperations", () => {
         version: "v1.0",
         createSurface: {
           surfaceId: "inline",
+          catalogId: "basic",
           surfaceProperties: { ignored: true },
           sendDataModel: true,
           components: [
@@ -73,6 +75,7 @@ describe("applyA2uiOperations", () => {
 
     expect(result.warnings).toEqual([]);
     expect(result.state.get("inline")).toMatchObject({
+      catalogId: "basic",
       dataModel: { message: "hello" },
     });
     expect(result.state.get("inline")?.components.get("root")).toEqual({
@@ -82,6 +85,21 @@ describe("applyA2uiOperations", () => {
     });
   });
 
+  it("keeps a v1.0 catalog id from surface properties", () => {
+    const result = applyA2uiOperations(new Map(), [
+      {
+        version: "v1.0",
+        createSurface: {
+          surfaceId: "properties",
+          surfaceProperties: { catalogId: "basic" },
+        },
+      },
+    ]);
+
+    expect(result.warnings).toEqual([]);
+    expect(result.state.get("properties")?.catalogId).toBe("basic");
+  });
+
   it.each(["10001", "4294967294"])(
     "rejects array pointer index %s beyond the auto-vivification limit",
     (index) => {

package/src/a2ui/reducer.ts

@@ -28,6 +28,17 @@ const surfaceIdOf = (payload: Record<string, unknown>): string | undefined => {
     : undefined;
 };
 
+const catalogIdOf = (payload: Record<string, unknown>): string | undefined => {
+  if (typeof payload["catalogId"] === "string") {
+    return payload["catalogId"];
+  }
+  const surfaceProperties = payload["surfaceProperties"];
+  return isRecord(surfaceProperties) &&
+    typeof surfaceProperties["catalogId"] === "string"
+    ? surfaceProperties["catalogId"]
+    : undefined;
+};
+
 const withSurfaceId = (
   surface: A2uiSurfaceState,
   surfaceId: string,
@@ -50,6 +61,9 @@ const cloneSurface = (
 ): A2uiSurfaceState =>
   withSurfaceId(
     {
+      ...(surface.catalogId !== undefined
+        ? { catalogId: surface.catalogId }
+        : {}),
       components: new Map(surface.components),
       dataModel: surface.dataModel,
     },
@@ -274,8 +288,10 @@ export function applyA2uiOperations(
       }
 
       if (operationKey === "createSurface") {
+        const catalogId = catalogIdOf(payload);
         const surface = withSurfaceId(
           {
+            ...(catalogId !== undefined ? { catalogId } : {}),
             components: new Map(),
             dataModel:
               version === "v1.0" && payload["dataModel"] !== undefined

package/src/a2ui/snapshot.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { surfaceToOperations } from "./snapshot";
+import { A2UI_SURFACE_ID, type A2uiSurfaceState } from "./types";
+
+const surface = (dataModel: unknown): A2uiSurfaceState => ({
+  components: new Map([["root", { id: "root", component: "Text" }]]),
+  dataModel,
+});
+
+describe("surfaceToOperations", () => {
+  it("uses an explicit surface id and omits an undefined data model", () => {
+    const value = Object.defineProperty(surface(undefined), A2UI_SURFACE_ID, {
+      value: "stored",
+    });
+
+    expect(surfaceToOperations(value, "provided")).toEqual([
+      {
+        version: "v0.9",
+        createSurface: { surfaceId: "provided" },
+      },
+      {
+        version: "v0.9",
+        updateComponents: {
+          surfaceId: "provided",
+          components: [{ id: "root", component: "Text" }],
+        },
+      },
+    ]);
+  });
+
+  it("uses the reducer surface id when no explicit id is supplied", () => {
+    const value = Object.defineProperty(surface(null), A2UI_SURFACE_ID, {
+      value: "stored",
+    });
+
+    expect(surfaceToOperations(value)).toMatchObject([
+      { createSurface: { surfaceId: "stored" } },
+      { updateComponents: { surfaceId: "stored" } },
+      { updateDataModel: { surfaceId: "stored", contents: null } },
+    ]);
+  });
+
+  it("requires either an explicit or reducer surface id", () => {
+    expect(() => surfaceToOperations(surface({}))).toThrow(
+      "A2UI surfaces must have a surface id to be replayed.",
+    );
+  });
+  it("rejects an empty surface id", () => {
+    const value = { components: new Map(), dataModel: undefined };
+    expect(() => surfaceToOperations(value, "")).toThrow();
+  });
+});

package/src/a2ui/snapshot.ts

@@ -0,0 +1,52 @@
+import {
+  A2UI_SURFACE_ID,
+  type A2uiSurfaceState,
+  type A2uiSurfaceSnapshotOperation,
+  type ComponentNode,
+} from "./types";
+
+const surfaceIdOf = (surface: A2uiSurfaceState): string | undefined =>
+  (surface as A2uiSurfaceState & { [A2UI_SURFACE_ID]?: string })[
+    A2UI_SURFACE_ID
+  ];
+
+export function surfaceToOperations(
+  surface: A2uiSurfaceState,
+  surfaceId?: string,
+): readonly A2uiSurfaceSnapshotOperation[] {
+  const resolvedSurfaceId = surfaceId ?? surfaceIdOf(surface);
+  if (!resolvedSurfaceId) {
+    throw new Error("A2UI surfaces must have a surface id to be replayed.");
+  }
+  const operations: A2uiSurfaceSnapshotOperation[] = [
+    {
+      version: "v0.9",
+      createSurface: {
+        surfaceId: resolvedSurfaceId,
+        ...(surface.catalogId !== undefined
+          ? { catalogId: surface.catalogId }
+          : {}),
+      },
+    },
+    {
+      version: "v0.9",
+      updateComponents: {
+        surfaceId: resolvedSurfaceId,
+        components: [...surface.components.values()].map((component) => ({
+          ...component,
+        })) as ComponentNode[],
+      },
+    },
+  ];
+  if (surface.dataModel !== undefined) {
+    operations.push({
+      version: "v0.9",
+      updateDataModel: {
+        surfaceId: resolvedSurfaceId,
+        path: "/",
+        contents: surface.dataModel,
+      },
+    });
+  }
+  return operations;
+}

package/src/a2ui/types.ts

@@ -24,6 +24,7 @@ export interface A2uiCreateSurfaceV09Payload {
 
 export interface A2uiCreateSurfaceV10Payload {
   readonly surfaceId: string;
+  readonly catalogId?: string;
   readonly surfaceProperties?: unknown;
   readonly sendDataModel?: unknown;
   readonly components?: readonly ComponentNode[];
@@ -78,7 +79,22 @@ export type A2uiOperation =
   | A2uiUpdateDataModelOperation
   | A2uiDeleteSurfaceOperation;
 
+export type A2uiSurfaceSnapshotOperation =
+  | {
+      readonly version: "v0.9";
+      readonly createSurface: A2uiCreateSurfaceV09Payload;
+    }
+  | {
+      readonly version: "v0.9";
+      readonly updateComponents: A2uiUpdateComponentsPayload;
+    }
+  | {
+      readonly version: "v0.9";
+      readonly updateDataModel: A2uiUpdateDataModelPayload;
+    };
+
 export type A2uiSurfaceState = {
+  catalogId?: string;
   components: Map<string, Record<string, unknown>>;
   dataModel: unknown;
 };

package/src/a2ui.ts

@@ -1,5 +1,6 @@
 export { applyA2uiOperations } from "./a2ui/reducer";
 export { convertSurfaceToUISpec } from "./a2ui/convert";
+export { surfaceToOperations } from "./a2ui/snapshot";
 export type {
   A2uiCreateSurfaceOperation,
   A2uiCreateSurfaceV09Payload,
@@ -9,6 +10,7 @@ export type {
   A2uiOperation,
   A2uiOperationResult,
   A2uiState,
+  A2uiSurfaceSnapshotOperation,
   A2uiSurfaceState,
   A2uiTemplateChildren,
   A2uiUpdateComponentsOperation,

package/src/actionRegistry.ts

@@ -10,17 +10,17 @@ export type ActionDispatchContext = {
 
 /**
  * Resolves a single `$action.type`. Fire-and-forget actions return `void` or a
- * promise that resolves to it; human-in-the-loop actions return a value the
- * runtime uses to resume the run (see IR doc Open question #2 — the resume
- * value is left as `unknown` and documented per-action). The return value is
- * handed back to `dispatch`'s caller as `unknown`.
+ * promise that resolves to it. For a `prompt_user` tool whose call has no
+ * result yet, a non-`undefined` return value becomes the tool result. Whether
+ * that resumes the run depends on the runtime, including how it treats human
+ * tools. The return value is handed back to `dispatch`'s caller as `unknown`.
  */
 export type ActionHandler = (
   ctx: ActionDispatchContext,
 ) => unknown | Promise<unknown>;
 
 /**
- * The host-provided map from `$action.type` to {@link ActionHandler}. This is the single dispatch target for rendered generative UI: every interactive component fires its `$action` here through the injected `$dispatch` (a submit Button defers to its ancestor form's dispatch instead). The payload's `$input` takes one of two shapes: a single value for a standalone control's dispatch (`Select`, `Input`, `DatePicker`, `Checkbox`, `RadioGroup`), or an object keyed by field `name` for a `Form` or a `Card` with `asForm` set. Construct it with {@link createActionRegistry} and pass it to `JSONGenerativeUI`.
+ * The host-provided map from `$action.type` to {@link ActionHandler}. This is the single dispatch target for rendered generative UI: every interactive component fires its `$action` here through the injected `$dispatch` (a submit Button defers to its ancestor form's dispatch instead). The payload's `$input` takes one of two shapes: a single value for a standalone control's dispatch (`Select`, `Input`, `DatePicker`, `Checkbox`, `RadioGroup`), or an object keyed by field `name` for a `Form` or a `Card` with `asForm` set. When a registry is used in a `JSONGenerativeUI` tool, each dispatched payload, including `$input`, is recorded on the tool call on a best-effort basis. Recording depends on the runtime and interaction log limits, and never delays or prevents dispatch. Construct it with {@link createActionRegistry} and pass it to `JSONGenerativeUI`.
  */
 export type ActionRegistry = {
   dispatch(action: Action): unknown;