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

package/dist/vocabulary/text.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+//#region src/vocabulary/text.d.ts
+declare const textVocabulary: {
+  Header: {
+    description: string;
+    properties: z.ZodObject<{
+      text: z.ZodString;
+      size: z.ZodOptional<z.ZodEnum<{
+        sm: "sm";
+        md: "md";
+        lg: "lg";
+        xl: "xl";
+        "2xl": "2xl";
+        "3xl": "3xl";
+      }>>;
+    }, z.core.$strip>;
+    render: ({ text, size, children }: any) => import("react").JSX.Element;
+  };
+  Text: {
+    description: string;
+    properties: z.ZodObject<{
+      value: z.ZodString;
+      size: z.ZodOptional<z.ZodEnum<{
+        sm: "sm";
+        md: "md";
+        lg: "lg";
+        xl: "xl";
+        "2xl": "2xl";
+        "3xl": "3xl";
+      }>>;
+      weight: z.ZodOptional<z.ZodEnum<{
+        bold: "bold";
+        normal: "normal";
+        medium: "medium";
+        semibold: "semibold";
+      }>>;
+      color: z.ZodOptional<z.ZodEnum<{
+        emphasis: "emphasis";
+        secondary: "secondary";
+        "alpha-70": "alpha-70";
+        white: "white";
+        "white-70": "white-70";
+        "white-50": "white-50";
+      }>>;
+    }, z.core.$strip>;
+    streamProperties: true;
+    render: ({ value, size, weight, color, children }: any) => import("react").JSX.Element;
+  };
+  Caption: {
+    description: string;
+    properties: z.ZodObject<{
+      value: z.ZodString;
+    }, z.core.$strip>;
+    streamProperties: true;
+    render: ({ value, children }: any) => import("react").JSX.Element;
+  };
+};
+//#endregion
+export { textVocabulary };
+//# sourceMappingURL=text.d.ts.map

package/dist/vocabulary/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","names":[],"sources":["../../src/vocabulary/text.tsx"],"mappings":";;cAIa"}

package/dist/vocabulary/text.js

@@ -0,0 +1,48 @@
+import { COLORS, TEXT_SIZES, WEIGHTS } from "../ir.js";
+import { jsxs } from "react/jsx-runtime";
+import { z } from "zod";
+//#region src/vocabulary/text.tsx
+const textVocabulary = {
+	Header: {
+		description: "A section heading. Renders as a bold title.",
+		properties: z.object({
+			text: z.string().describe("The heading text."),
+			size: z.enum(TEXT_SIZES).optional().describe("Heading size; defaults to `lg`.")
+		}),
+		render: ({ text, size, children }) => /* @__PURE__ */ jsxs("h2", {
+			"data-aui": "header",
+			"data-aui-size": size ?? "lg",
+			children: [text, children]
+		})
+	},
+	Text: {
+		description: "A run of text. Use for paragraphs, labels, or inline copy.",
+		properties: z.object({
+			value: z.string().describe("The text content."),
+			size: z.enum(TEXT_SIZES).optional().describe("Text size; defaults to `md`."),
+			weight: z.enum(WEIGHTS).optional().describe("Font weight."),
+			color: z.enum(COLORS).optional().describe("Foreground color token.")
+		}),
+		streamProperties: true,
+		render: ({ value, size, weight, color, children }) => /* @__PURE__ */ jsxs("span", {
+			"data-aui": "text",
+			"data-aui-size": size ?? "md",
+			"data-aui-weight": weight,
+			"data-aui-color": color,
+			children: [value, children]
+		})
+	},
+	Caption: {
+		description: "Secondary, de-emphasized text under a primary element.",
+		properties: z.object({ value: z.string().describe("The caption text.") }),
+		streamProperties: true,
+		render: ({ value, children }) => /* @__PURE__ */ jsxs("p", {
+			"data-aui": "caption",
+			children: [value, children]
+		})
+	}
+};
+//#endregion
+export { textVocabulary };
+
+//# sourceMappingURL=text.js.map

package/dist/vocabulary/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","names":[],"sources":["../../src/vocabulary/text.tsx"],"sourcesContent":["import { z } from \"zod\";\nimport type { GenerativeUILibrary } from \"../types\";\nimport { COLORS, TEXT_SIZES, WEIGHTS } from \"../ir\";\n\nexport const textVocabulary = {\n  Header: {\n    description: \"A section heading. Renders as a bold title.\",\n    properties: z.object({\n      text: z.string().describe(\"The heading text.\"),\n      size: z\n        .enum(TEXT_SIZES)\n        .optional()\n        .describe(\"Heading size; defaults to `lg`.\"),\n    }),\n    render: ({ text, size, children }) => (\n      <h2 data-aui=\"header\" data-aui-size={size ?? \"lg\"}>\n        {text}\n        {children}\n      </h2>\n    ),\n  },\n  Text: {\n    description: \"A run of text. Use for paragraphs, labels, or inline copy.\",\n    properties: z.object({\n      value: z.string().describe(\"The text content.\"),\n      size: z\n        .enum(TEXT_SIZES)\n        .optional()\n        .describe(\"Text size; defaults to `md`.\"),\n      weight: z.enum(WEIGHTS).optional().describe(\"Font weight.\"),\n      color: z.enum(COLORS).optional().describe(\"Foreground color token.\"),\n    }),\n    streamProperties: true,\n    render: ({ value, size, weight, color, children }) => (\n      <span\n        data-aui=\"text\"\n        data-aui-size={size ?? \"md\"}\n        data-aui-weight={weight}\n        data-aui-color={color}\n      >\n        {value}\n        {children}\n      </span>\n    ),\n  },\n  Caption: {\n    description: \"Secondary, de-emphasized text under a primary element.\",\n    properties: z.object({\n      value: z.string().describe(\"The caption text.\"),\n    }),\n    streamProperties: true,\n    render: ({ value, children }) => (\n      <p data-aui=\"caption\">\n        {value}\n        {children}\n      </p>\n    ),\n  },\n} satisfies GenerativeUILibrary;\n"],"mappings":";;;;AAIA,MAAa,iBAAiB;CAC5B,QAAQ;EACN,aAAa;EACb,YAAY,EAAE,OAAO;GACnB,MAAM,EAAE,OAAO,CAAC,CAAC,SAAS,mBAAmB;GAC7C,MAAM,EACH,KAAK,UAAU,CAAC,CAChB,SAAS,CAAC,CACV,SAAS,iCAAiC;EAC/C,CAAC;EACD,SAAS,EAAE,MAAM,MAAM,eACrB,qBAAC,MAAD;GAAI,YAAS;GAAS,iBAAe,QAAQ;aAA7C,CACG,MACA,QACC;;CAER;CACA,MAAM;EACJ,aAAa;EACb,YAAY,EAAE,OAAO;GACnB,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS,mBAAmB;GAC9C,MAAM,EACH,KAAK,UAAU,CAAC,CAChB,SAAS,CAAC,CACV,SAAS,8BAA8B;GAC1C,QAAQ,EAAE,KAAK,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,cAAc;GAC1D,OAAO,EAAE,KAAK,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,yBAAyB;EACrE,CAAC;EACD,kBAAkB;EAClB,SAAS,EAAE,OAAO,MAAM,QAAQ,OAAO,eACrC,qBAAC,QAAD;GACE,YAAS;GACT,iBAAe,QAAQ;GACvB,mBAAiB;GACjB,kBAAgB;aAJlB,CAMG,OACA,QACG;;CAEV;CACA,SAAS;EACP,aAAa;EACb,YAAY,EAAE,OAAO,EACnB,OAAO,EAAE,OAAO,CAAC,CAAC,SAAS,mBAAmB,EAChD,CAAC;EACD,kBAAkB;EAClB,SAAS,EAAE,OAAO,eAChB,qBAAC,KAAD;GAAG,YAAS;aAAZ,CACG,OACA,QACA;;CAEP;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/react-generative-ui",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Generative UI components for assistant-ui",
   "keywords": [
     "generative-ui",
@@ -15,18 +15,26 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./internal-json": {
       "react-server": {
-        "types": "./dist/JSONGenerativeUI.server.d.ts",
-        "default": "./dist/JSONGenerativeUI.server.js"
+        "types": "./dist/index.server.d.ts",
+        "default": "./dist/index.server.js"
       },
       "default": {
-        "types": "./dist/JSONGenerativeUI.client.d.ts",
-        "default": "./dist/JSONGenerativeUI.client.js"
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
       }
+    },
+    "./ir": {
+      "types": "./dist/ir.d.ts",
+      "default": "./dist/ir.js"
+    },
+    "./slack": {
+      "types": "./dist/slack.d.ts",
+      "default": "./dist/slack.js"
+    },
+    "./teams": {
+      "types": "./dist/teams.d.ts",
+      "default": "./dist/teams.js"
     }
   },
   "main": "./dist/index.js",
@@ -38,7 +46,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "assistant-stream": "^0.3.24"
+    "assistant-stream": "^0.3.26"
   },
   "peerDependencies": {
     "@assistant-ui/react": "^0.14.14",
@@ -56,10 +64,10 @@
     "@types/react": "^19.2.17",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "vitest": "^4.1.9",
+    "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@assistant-ui/react": "0.14.24",
-    "@assistant-ui/x-buildutils": "0.0.16"
+    "@assistant-ui/react": "0.14.27",
+    "@assistant-ui/x-buildutils": "0.0.18"
   },
   "publishConfig": {
     "access": "public",

package/src/JSONGenerativeUI.client.tsx

@@ -9,6 +9,7 @@ import {
   type PresentToolOptions,
   type PromptUserTool,
 } from "./JSONGenerativeUI.shared";
+import { type ActionRegistry } from "./actionRegistry";
 import { renderGenerativeUI } from "./renderGenerativeUI";
 import type { GenerativeUILibrary, GenerativeUIStatus } from "./types";
 
@@ -27,15 +28,19 @@ function uiStatus(status: { type: string }): GenerativeUIStatus {
  * `present` is a frontend tool that renders the model's `{ $type, ...props }`
  * tree against the library and resolves immediately. `prompt_user` is a
  * human-in-the-loop tool: the model pauses and the rendered UI supplies the
- * result. Both draw the tree the same way, so they share one `render`.
+ * result. Both draw the tree the same way, so they share one `render`. The
+ * `actions` registry (if provided) is threaded into the render context so
+ * interactive components can fire `$action` through `$dispatch`.
  */
 export class JSONGenerativeUI {
   private readonly library: GenerativeUILibrary;
   private readonly parameters: PresentParameters;
+  private readonly actions: ActionRegistry | undefined;
 
   constructor(options: JSONGenerativeUIOptions) {
     this.library = options.library;
     this.parameters = buildPresentParameters(options.library);
+    this.actions = options.actions;
   }
 
   private readonly render = ({
@@ -45,7 +50,10 @@ export class JSONGenerativeUI {
     args: unknown;
     status: { type: string };
   }): ReactNode =>
-    renderGenerativeUI(args, this.library, { status: uiStatus(status) });
+    renderGenerativeUI(args, this.library, {
+      status: uiStatus(status),
+      ...(this.actions ? { dispatch: this.actions.dispatch } : {}),
+    });
 
   present(options?: PresentToolOptions): PresentTool {
     return {

package/src/JSONGenerativeUI.shared.ts

@@ -1,5 +1,6 @@
 import type { ToolDefinition } from "@assistant-ui/react";
 import type { JSONSchema7 } from "json-schema";
+import type { ActionRegistry } from "./actionRegistry";
 import type { GenerativeUILibrary } from "./types";
 
 /** Options for {@link JSONGenerativeUI}. */
@@ -10,6 +11,13 @@ export type JSONGenerativeUIOptions = {
    * `"use generative"` build can split each `render` from its `properties`.
    */
   library: GenerativeUILibrary;
+  /**
+   * Host-provided map from `$action.type` to its handler. Interactive
+   * components (`Button`/`Select`/`Input`/`DatePicker`) call `$dispatch($action)`
+   * on their event, which resolves through this registry. Omit it for a
+   * read-only render where model-emitted actions degrade to a no-op.
+   */
+  actions?: ActionRegistry;
 };
 
 /** Options for {@link JSONGenerativeUI.present}. */

package/src/actionRegistry.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, vi } from "vitest";
+import { createActionRegistry, emptyActionRegistry } from "./actionRegistry";
+
+describe("createActionRegistry", () => {
+  it("dispatch resolves a registered action type and calls its handler with the payload", () => {
+    const handler = vi.fn(() => "ok");
+    const registry = createActionRegistry({ purchase: handler });
+
+    const result = registry.dispatch({
+      type: "purchase",
+      itemId: "sku-1",
+    });
+
+    expect(handler).toHaveBeenCalledWith({
+      payload: { type: "purchase", itemId: "sku-1" },
+    });
+    expect(result).toBe("ok");
+  });
+
+  it("dispatch returns the handler's resolved promise value for async handlers", async () => {
+    const registry = createActionRegistry({
+      fetch: async () => 42,
+    });
+
+    const result = await registry.dispatch({ type: "fetch" });
+    expect(result).toBe(42);
+  });
+
+  it("dispatch is a no-op (returns undefined) for an unknown action type", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const registry = createActionRegistry({
+        purchase: () => undefined,
+        refund: () => undefined,
+      });
+      expect(registry.dispatch({ type: "unknown" })).toBeUndefined();
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn).toHaveBeenCalledWith(
+        '[@assistant-ui/react-generative-ui] Action "unknown" has no registered handler. Registered actions: "purchase", "refund". Register it with createActionRegistry(...) or update the emitted `$action.type`.',
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("dispatch is a no-op for malformed non-string action types", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const handler = vi.fn();
+      const registry = createActionRegistry({ purchase: handler });
+
+      expect(registry.dispatch({ type: 123 } as never)).toBeUndefined();
+
+      expect(handler).not.toHaveBeenCalled();
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn).toHaveBeenCalledWith(
+        "[@assistant-ui/react-generative-ui] Skipping malformed action; `$action.type` must be a string. Received number. Update the emitted `$action` payload.",
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("has reports whether a handler is registered", () => {
+    const registry = createActionRegistry({ a: () => undefined });
+    expect(registry.has("a")).toBe(true);
+    expect(registry.has("b")).toBe(false);
+  });
+});
+
+describe("emptyActionRegistry", () => {
+  it("dispatch is a no-op for any type and emits the dev warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(
+        emptyActionRegistry.dispatch({ type: "anything" }),
+      ).toBeUndefined();
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn).toHaveBeenCalledWith(
+        '[@assistant-ui/react-generative-ui] Action "anything" has no registered handler. No actions are registered. Register it with createActionRegistry(...) or update the emitted `$action.type`.',
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("has is false for any type", () => {
+    expect(emptyActionRegistry.has("anything")).toBe(false);
+  });
+});

package/src/actionRegistry.ts

@@ -0,0 +1,88 @@
+import type { Action } from "./ir";
+
+/** Context handed to an {@link ActionHandler} when an `$action` fires. */
+export type ActionDispatchContext = {
+  /**
+   * The action payload. For fire-and-forget actions this is the `$action` as the model emitted it. For an interactive component the user's runtime input is merged in under the reserved `$input` key: a single value for a standalone control's dispatch, or an object keyed by each field's `name` for a `Form` or a `Card` with `asForm` set. A model-supplied `value` field is never clobbered.
+   */
+  readonly payload: Action;
+};
+
+/**
+ * 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`.
+ */
+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`.
+ */
+export type ActionRegistry = {
+  dispatch(action: Action): unknown;
+  has(type: string): boolean;
+};
+
+export function createActionRegistry(
+  handlers: Readonly<Record<string, ActionHandler>>,
+): ActionRegistry {
+  const map = new Map(Object.entries(handlers));
+  return {
+    dispatch(action) {
+      if (typeof action?.type !== "string") {
+        if (process.env["NODE_ENV"] !== "production") {
+          // eslint-disable-next-line no-console
+          console.warn(
+            "[@assistant-ui/react-generative-ui] Skipping malformed action; " +
+              "`$action.type` must be a string. " +
+              `Received ${formatReceivedType(action?.type)}. Update the emitted ` +
+              "`$action` payload.",
+          );
+        }
+        return undefined;
+      }
+
+      const handler = map.get(action.type);
+      if (!handler) {
+        if (process.env["NODE_ENV"] !== "production") {
+          const actionTypes = [...map.keys()];
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[@assistant-ui/react-generative-ui] Action "${action.type}" has ` +
+              `no registered handler. ${formatRegisteredActions(actionTypes)} ` +
+              "Register it with createActionRegistry(...) or update the emitted " +
+              "`$action.type`.",
+          );
+        }
+        return undefined;
+      }
+      return handler({ payload: action });
+    },
+    has(type) {
+      return map.has(type);
+    },
+  };
+}
+
+/** A no-op registry used when no handlers are provided. Dispatch resolves to
+ * `undefined` and logs a warning in dev for unknown types, so a model-emitted
+ * action with no handler degrades to "does nothing" rather than throwing. */
+export const emptyActionRegistry: ActionRegistry = createActionRegistry({});
+
+function formatRegisteredActions(actionTypes: string[]) {
+  if (actionTypes.length === 0) return "No actions are registered.";
+
+  return `Registered actions: ${actionTypes
+    .map((type) => `"${type}"`)
+    .join(", ")}.`;
+}
+
+function formatReceivedType(value: unknown) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}

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,11 +25,12 @@ 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) {
     const propsSchema = toJSONSchema(library[name]!.properties);
     if (propsSchema.type !== "object") {
@@ -38,17 +40,23 @@ 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;
-      } else if (process.env["NODE_ENV"] !== "production") {
-        // eslint-disable-next-line no-console
-        console.warn(
-          `[@assistant-ui/react-generative-ui] Prop "${key}" is declared by more ` +
-            "than one component; the first component's schema is kept and the rest " +
-            "are ignored. Rename or align the type to avoid an ambiguous schema.",
-        );
       }
+      propOwners.set(key, [...(propOwners.get(key) ?? []), name]);
+    }
+  }
+
+  if (process.env["NODE_ENV"] !== "production") {
+    for (const [key, owners] of propOwners) {
+      if (owners.length < 2) continue;
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[@assistant-ui/react-generative-ui] Prop "${key}" is declared by ` +
+          `${formatComponentList(owners)}; keeping "${owners[0]}"'s schema. ` +
+          "Rename or align the prop type to avoid an ambiguous schema.",
+      );
     }
   }
 
@@ -65,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" },
     },
@@ -88,3 +101,12 @@ export function buildPresentParameters(
     $defs: { node, children },
   };
 }
+
+function formatComponentList(names: string[]) {
+  if (names.length <= 2) return names.map((name) => `"${name}"`).join(" and ");
+
+  return `${names
+    .slice(0, -1)
+    .map((name) => `"${name}"`)
+    .join(", ")}, and "${names[names.length - 1]}"`;
+}