@assistant-ui/react-generative-ui 0.0.21 → 0.0.22

package/src/fieldReferences.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { hasFieldReference, resolveFieldReferences } from "./fieldReferences";
+
+describe("field references", () => {
+  it("resolve from own fields only and drop what does not resolve", () => {
+    const fields = Object.assign(Object.create({ inherited: "no" }), {
+      note: "hi",
+      empty: undefined,
+    }) as Record<string, unknown>;
+
+    expect(
+      resolveFieldReferences(
+        {
+          note: { $field: "note" },
+          list: [
+            { $field: "note" },
+            { $field: "empty" },
+            { $field: "inherited" },
+          ],
+          literal: { $field: "note", other: 1 },
+        },
+        fields,
+      ),
+    ).toEqual({
+      note: "hi",
+      list: ["hi"],
+      literal: { $field: "note", other: 1 },
+    });
+  });
+
+  it("fall back to the reference's own fallback, and read only $field and fallback as a reference", () => {
+    expect(
+      resolveFieldReferences(
+        {
+          filled: { $field: "note", fallback: "old" },
+          missing: { $field: "gone", fallback: "kept" },
+          empty: { $field: "gone" },
+          list: [{ $field: "gone", fallback: 0 }],
+          data: { $field: "note", fallback: "old", extra: true },
+        },
+        { note: "new" },
+      ),
+    ).toEqual({
+      filled: "new",
+      missing: "kept",
+      list: [0],
+      data: { $field: "note", fallback: "old", extra: true },
+    });
+  });
+
+  it("terminate on a cyclic value and keep the cycle", () => {
+    const cyclic: Record<string, unknown> = { note: { $field: "note" } };
+    cyclic["self"] = cyclic;
+    const acyclic: Record<string, unknown> = { a: 1 };
+    acyclic["self"] = { back: [acyclic] };
+
+    expect(hasFieldReference(cyclic)).toBe(true);
+    expect(hasFieldReference(acyclic)).toBe(false);
+    const resolved = resolveFieldReferences(cyclic, { note: "hi" }) as Record<
+      string,
+      unknown
+    >;
+    expect(resolved["note"]).toBe("hi");
+    expect(resolved["self"]).toBe(cyclic);
+  });
+});

package/src/fieldReferences.ts

@@ -0,0 +1,83 @@
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const MAX_DEPTH = 64;
+
+const isFieldReference = (
+  value: unknown,
+): value is { readonly $field: string; readonly fallback?: unknown } =>
+  isRecord(value) &&
+  typeof value["$field"] === "string" &&
+  Object.keys(value).every((key) => key === "$field" || key === "fallback");
+
+/**
+ * Whether `value` contains a `{ "$field": name }` or `{ "$field": name, "fallback": value }` reference within 64 levels.
+ */
+export const hasFieldReference = (value: unknown): boolean => {
+  const seen = new Set<object>();
+  const visit = (entry: unknown, depth: number): boolean => {
+    if (
+      typeof entry !== "object" ||
+      entry === null ||
+      depth > MAX_DEPTH ||
+      seen.has(entry)
+    ) {
+      return false;
+    }
+    if (isFieldReference(entry)) return true;
+    seen.add(entry);
+    return Object.values(entry).some((item) => visit(item, depth + 1));
+  };
+  return visit(value, 0);
+};
+
+/**
+ * Replaces each `{ "$field": name }` reference inside `value` with the own property `name` of `fields`, or with the reference's own `fallback` when that is `undefined`. A reference that still resolves to `undefined` is dropped from its object or array, and a cyclic reference or anything nested deeper than 64 levels is kept as is.
+ */
+export const resolveFieldReferences = (
+  value: unknown,
+  fields: Readonly<Record<string, unknown>>,
+): unknown => {
+  const ancestors = new Set<object>();
+  const resolve = (entry: unknown, depth: number): unknown => {
+    if (isFieldReference(entry)) {
+      const current = Object.hasOwn(fields, entry.$field)
+        ? fields[entry.$field]
+        : undefined;
+      if (current !== undefined) return current;
+      return Object.hasOwn(entry, "fallback") ? entry.fallback : undefined;
+    }
+    if (
+      typeof entry !== "object" ||
+      entry === null ||
+      depth > MAX_DEPTH ||
+      ancestors.has(entry)
+    ) {
+      return entry;
+    }
+    ancestors.add(entry);
+    try {
+      if (Array.isArray(entry)) {
+        return entry
+          .map((item) => resolve(item, depth + 1))
+          .filter((item) => item !== undefined);
+      }
+      const result: Record<string, unknown> = {};
+      for (const [key, item] of Object.entries(entry)) {
+        const resolved = resolve(item, depth + 1);
+        if (resolved !== undefined) {
+          Object.defineProperty(result, key, {
+            value: resolved,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+          });
+        }
+      }
+      return result;
+    } finally {
+      ancestors.delete(entry);
+    }
+  };
+  return resolve(value, 0);
+};

package/src/generativeUIToJSX.test.ts

@@ -83,6 +83,24 @@ describe("generativeUIToJSX", () => {
 });
 
 describe("generativeUIToJSX with escape: true", () => {
+  it.each([false, true])(
+    "preserves literal entities in string props and keys with pretty=%s",
+    (pretty) => {
+      expect(
+        generativeUIToJSX(
+          { $type: "Text", $key: "A", value: "& A A" },
+          { escape: true, pretty },
+        ),
+      ).toBe('<Text key={"&#65;"} value={"&amp; &#65; &#x41;"} />');
+    },
+  );
+
+  it("keeps entity spelling in the default display form", () => {
+    expect(generativeUIToJSX({ $type: "Text", value: "&amp; &#65;" })).toBe(
+      '<Text value="&amp; &#65;" />',
+    );
+  });
+
   it("escapes a string child containing HTML-like tags", () => {
     expect(
       generativeUIToJSX(

package/src/generativeUIToJSX.ts

@@ -64,9 +64,9 @@ function toJSX(
   if (typeof type !== "string") return "";
 
   const attrs =
-    formatAttr("key", $key) +
+    formatAttr("key", $key, escape) +
     Object.entries(props)
-      .map(([key, value]) => formatAttr(key, value))
+      .map(([key, value]) => formatAttr(key, value, escape))
       .join("");
 
   if (!pretty) {
@@ -140,13 +140,11 @@ function formatChildText(value: string, escape: boolean): string {
 }
 
 /** Formats one prop as a JSX attribute (`id="x"`, `count={3}`, `open`, …). */
-function formatAttr(key: string, value: unknown): string {
+function formatAttr(key: string, value: unknown, escape: boolean): string {
   if (value === undefined) return "";
   if (value === true) return ` ${key}`;
   if (typeof value === "string") {
-    // Plain double-quoted form when safe; expression form when a quote or
-    // newline would break the attribute.
-    return /["\n]/.test(value)
+    return /["\n]/.test(value) || (escape && value.includes("&"))
       ? ` ${key}={${JSON.stringify(value)}}`
       : ` ${key}="${value}"`;
   }

package/src/index.server.test.ts

@@ -0,0 +1,106 @@
+/// <reference types="node" />
+import { describe, expect, it } from "vitest";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+const SRC_DIR = resolve(__dirname);
+
+// Next.js fails the build when a module reachable from a Server Component
+// names one of these React APIs in an import; the namespace import is allowed.
+const CLIENT_ONLY_REACT_APIS = new Set([
+  "Component",
+  "PureComponent",
+  "createContext",
+  "createFactory",
+  "useActionState",
+  "useEffect",
+  "useEffectEvent",
+  "useImperativeHandle",
+  "useInsertionEffect",
+  "useLayoutEffect",
+  "useOptimistic",
+  "useReducer",
+  "useRef",
+  "useState",
+  "useSyncExternalStore",
+  "useTransition",
+]);
+
+const RELATIVE_SPECIFIER_RE = /\b(?:from|import)\s*\(?\s*["'](\.[^"']*)["']/g;
+
+const NAMED_FROM_REACT_RE =
+  /(?:import|export)\s+(type\s+)?(?:\w+\s*,\s*)?\{([^}]*)\}\s+from\s+["']react["']/g;
+
+function resolveRelative(fromFile: string, spec: string): string | undefined {
+  const base = resolve(dirname(fromFile), spec);
+  return [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    join(base, "index.ts"),
+    join(base, "index.tsx"),
+  ].find((candidate) => existsSync(candidate) && statSync(candidate).isFile());
+}
+
+function collectGraph(entry: string): Set<string> {
+  const visited = new Set<string>();
+  const pending = [entry];
+  while (pending.length > 0) {
+    const file = pending.pop()!;
+    if (visited.has(file)) continue;
+    visited.add(file);
+    for (const [, spec] of readFileSync(file, "utf8").matchAll(
+      RELATIVE_SPECIFIER_RE,
+    )) {
+      const resolved = resolveRelative(file, spec!);
+      if (resolved) pending.push(resolved);
+    }
+  }
+  return visited;
+}
+
+function clientOnlyReactImports(file: string): string[] {
+  const names: string[] = [];
+  for (const [, typeOnly, specifiers] of readFileSync(file, "utf8").matchAll(
+    NAMED_FROM_REACT_RE,
+  )) {
+    if (typeOnly) continue;
+    for (const specifier of specifiers!.split(",")) {
+      const name = specifier.trim().split(/\s+as\s+/)[0]!;
+      if (CLIENT_ONLY_REACT_APIS.has(name)) names.push(name);
+    }
+  }
+  return names;
+}
+
+// Server code reaches every entry: the subpaths carry no react-server
+// condition, and the docs app resolves the root to its source through
+// tsconfig paths, which skip that condition.
+const ENTRIES = [
+  "index.server.ts",
+  "index.ts",
+  "ir.ts",
+  "a2ui.ts",
+  "slack.ts",
+  "teams.ts",
+];
+
+describe("published entries", () => {
+  const graph = new Set(
+    ENTRIES.flatMap((entry) => [...collectGraph(join(SRC_DIR, entry))]),
+  );
+
+  it("reach the vocabulary and the client renderer", () => {
+    expect(graph).toContain(join(SRC_DIR, "vocabulary", "interactive.tsx"));
+    expect(graph).toContain(join(SRC_DIR, "JSONGenerativeUI.client.tsx"));
+  });
+
+  it("never name a client-only React API in an import", () => {
+    const violations = [...graph].flatMap((file) =>
+      clientOnlyReactImports(file).map(
+        (name) => `${relative(SRC_DIR, file)}: ${name}`,
+      ),
+    );
+    expect(violations).toEqual([]);
+  });
+});

package/src/ir.ts

@@ -85,7 +85,7 @@ export const ICON_NAMES = [
 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 while converters may bind the type to a native action id on other platforms.
+ * 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. A `{ "$field": name }` value anywhere in the payload refers to the current value of the control with that `name`, resolved when the action fires, and `{ "$field": name, "fallback": value }` resolves to `fallback` when no control holds a value.
  */
 export interface Action {
   readonly type: string;

package/src/renderGenerativeUI.test.tsx

@@ -77,8 +77,10 @@ describe("renderGenerativeUI", () => {
       library,
     );
 
-    expect(Array.isArray(out)).toBe(true);
-    const elements = out as ReactElement[];
+    expect(isValidElement(out)).toBe(true);
+    const elements = (out as ReactElement<{ children: ReactElement[] }>).props
+      .children;
+    expect(Array.isArray(elements)).toBe(true);
     expect(elements.every(isValidElement)).toBe(true);
     expect(elements.map((element) => element.key)).toEqual([
       "model:1:Text",
@@ -108,12 +110,19 @@ describe("renderGenerativeUI", () => {
   });
 
   it("renders nothing for an unknown component", () => {
-    const html = renderToStaticMarkup(
-      <>{renderGenerativeUI({ $type: "Missing" }, library)}</>,
-    );
+    const rendered = renderGenerativeUI({ $type: "Missing" }, library);
+    expect(rendered).toBeNull();
+    const html = renderToStaticMarkup(<>{rendered}</>);
     expect(html).toBe("");
   });
 
+  it.each(["plain", 42, null])(
+    "preserves a primitive root result: %j",
+    (value) => {
+      expect(renderGenerativeUI(value, library)).toBe(value);
+    },
+  );
+
   it.each(["toString", "constructor"])(
     "treats inherited %s as an unknown component",
     (type) => {

package/src/renderGenerativeUI.tsx

@@ -1,7 +1,10 @@
+import { RadioGroupScope } from "./RadioGroupScope";
 import { getPartialJsonObjectMeta } from "assistant-stream/utils";
 import { Fragment, type ReactNode } from "react";
+import { hasFieldReference, resolveFieldReferences } from "./fieldReferences";
 import {
   normalizeUINode,
+  type Action,
   type NormalizedUIElement,
   type NormalizedUINode,
 } from "./ir";
@@ -32,9 +35,35 @@ export function renderGenerativeUI(
   // string has not finished streaming.
   const meta = getPartialJsonObjectMeta(node as Record<symbol, unknown>);
   const partialPath = meta?.state === "partial" ? meta.partialPath : undefined;
-  return renderNode(normalizeUINode(node, partialPath), library, context);
+  const rendered = renderNode(
+    normalizeUINode(node, partialPath),
+    library,
+    withFieldFallbacks(context),
+  );
+  return rendered !== null && typeof rendered === "object" ? (
+    <RadioGroupScope>{rendered}</RadioGroupScope>
+  ) : (
+    rendered
+  );
 }
 
+// A component that dispatches `$action` itself reads no control, so each `$field` reference left in it becomes its fallback.
+const withFieldFallbacks = (
+  context: GenerativeUIRenderContext,
+): GenerativeUIRenderContext => {
+  const { dispatch } = context;
+  if (dispatch === undefined) return context;
+  return {
+    ...context,
+    dispatch: (action) =>
+      dispatch(
+        hasFieldReference(action)
+          ? (resolveFieldReferences(action, {}) as Action)
+          : action,
+      ),
+  };
+};
+
 function renderNode(
   node: NormalizedUINode,
   library: GenerativeUILibrary,

package/src/slack/a2uiSlack.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it } from "vitest";
+import { convertSurfaceToUISpec } from "../a2ui/convert";
+import { decodeBlockAction } from "./decodeBlockAction";
+import { toSlackBlocks } from "./toSlackBlocks";
+
+const convertForm = () => {
+  const { spec, warnings: a2uiWarnings } = convertSurfaceToUISpec({
+    components: new Map([
+      ["root", { id: "root", component: "Column", children: ["name", "send"] }],
+      [
+        "name",
+        {
+          id: "name",
+          component: "TextField",
+          label: "Name",
+          value: { path: "/form/name" },
+        },
+      ],
+      [
+        "send",
+        {
+          id: "send",
+          component: "Button",
+          label: "Send",
+          action: {
+            event: {
+              name: "send",
+              context: { name: { path: "/form/name" } },
+            },
+          },
+        },
+      ],
+    ]),
+    dataModel: { form: { name: "Ada" } },
+  });
+
+  expect(a2uiWarnings).toEqual([]);
+  expect(spec).toMatchObject({
+    children: [
+      { $type: "Input", name: "/form/name", defaultValue: "Ada" },
+      {
+        $type: "Button",
+        $action: {
+          context: { name: { $field: "/form/name", fallback: "Ada" } },
+        },
+      },
+    ],
+  });
+  if (!spec) throw new Error("Expected an A2UI tree");
+
+  const { blocks, warnings: slackWarnings } = toSlackBlocks(spec);
+  expect(slackWarnings).toEqual([]);
+  const input = blocks.find((block) => block.type === "input");
+  const actions = blocks.find((block) => block.type === "actions");
+  if (!input || input.type !== "input" || !input.block_id)
+    throw new Error("Expected a named Slack input block");
+  if (!actions || actions.type !== "actions")
+    throw new Error("Expected a Slack actions block");
+  const button = actions.elements[0];
+  if (!button || button.type !== "button")
+    throw new Error("Expected a Slack button");
+
+  return { blockId: input.block_id, actionId: input.element.action_id, button };
+};
+
+describe("A2UI actions on Slack", () => {
+  it("resolves a bound CheckBox as a boolean when a button is pressed", () => {
+    const { spec, warnings } = convertSurfaceToUISpec({
+      components: new Map([
+        [
+          "root",
+          { id: "root", component: "Column", children: ["accepted", "send"] },
+        ],
+        [
+          "accepted",
+          {
+            id: "accepted",
+            component: "CheckBox",
+            label: "Accepted",
+            value: { path: "/form/accepted" },
+          },
+        ],
+        [
+          "send",
+          {
+            id: "send",
+            component: "Button",
+            label: "Send",
+            action: {
+              event: {
+                name: "send",
+                context: { accepted: { path: "/form/accepted" } },
+              },
+            },
+          },
+        ],
+      ]),
+      dataModel: { form: { accepted: true } },
+    });
+    expect(warnings).toEqual([]);
+    if (!spec) throw new Error("Expected an A2UI tree");
+    const { blocks, warnings: slackWarnings } = toSlackBlocks(spec);
+    expect(slackWarnings).toEqual([]);
+    const checkboxBlock = blocks.find(
+      (block) =>
+        block.type === "actions" &&
+        block.elements.some((element) => element.type === "checkboxes"),
+    );
+    const buttonBlock = blocks.find(
+      (block) =>
+        block.type === "actions" &&
+        block.elements.some((element) => element.type === "button"),
+    );
+    if (
+      !checkboxBlock ||
+      checkboxBlock.type !== "actions" ||
+      !checkboxBlock.block_id ||
+      !buttonBlock ||
+      buttonBlock.type !== "actions"
+    ) {
+      throw new Error("Expected named checkbox and button blocks");
+    }
+    const checkbox = checkboxBlock.elements.find(
+      (element) => element.type === "checkboxes",
+    );
+    const button = buttonBlock.elements.find(
+      (element) => element.type === "button",
+    );
+    if (!checkbox || checkbox.type !== "checkboxes" || !button) {
+      throw new Error("Expected a checkbox and button");
+    }
+
+    for (const [selectedOptions, accepted] of [
+      [[], false],
+      [checkbox.options[0] ? [checkbox.options[0]] : [], true],
+    ] as const) {
+      expect(
+        decodeBlockAction(button, {
+          [checkboxBlock.block_id]: {
+            [checkbox.action_id]: {
+              type: "checkboxes",
+              selected_options: selectedOptions,
+            },
+          },
+        }),
+      ).toMatchObject({ context: { accepted } });
+    }
+  });
+
+  it("decodes a named Checkbox action with a list in $input", () => {
+    const blockId = `aui:0:${JSON.stringify([["toggle", "agree", "Checkbox"]])}`;
+    for (const [selectedOptions, input] of [
+      [[], []],
+      [[{ value: "agree" }], ["agree"]],
+    ] as const) {
+      expect(
+        decodeBlockAction({
+          type: "checkboxes",
+          block_id: blockId,
+          action_id: "toggle",
+          selected_options: selectedOptions,
+        }),
+      ).toEqual({ type: "toggle", $input: input });
+    }
+  });
+
+  it("sends the user's edited TextField value", () => {
+    const { blockId, actionId, button } = convertForm();
+    const stateValues = {
+      [blockId]: {
+        [actionId]: {
+          type: "plain_text_input",
+          value: "Grace",
+        },
+      },
+    };
+
+    expect(decodeBlockAction(button, stateValues)).toEqual({
+      type: "a2ui:action",
+      name: "send",
+      surfaceId: "",
+      sourceComponentId: "send",
+      context: { name: "Grace" },
+    });
+  });
+
+  it("uses the agent's fallback when Slack provides no state", () => {
+    const { button } = convertForm();
+
+    expect(decodeBlockAction(button)).toEqual({
+      type: "a2ui:action",
+      name: "send",
+      surfaceId: "",
+      sourceComponentId: "send",
+      context: { name: "Ada" },
+    });
+  });
+});

package/src/slack/constants.ts

@@ -54,6 +54,9 @@ export const SELECT_OPTION_CAP = 100;
 /** The maximum number of options in a radio-button group. */
 export const RADIO_OPTION_CAP = 10;
 
+/** The maximum number of options in a checkbox group. */
+export const CHECKBOX_OPTION_CAP = 10;
+
 /** The character limit for a select or input placeholder. */
 export const PLACEHOLDER_TEXT_CAP = 150;