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

package/src/buildPresentParameters.test.ts

@@ -0,0 +1,246 @@
+import type { JSONSchema7, JSONSchema7Definition } from "json-schema";
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { buildPresentParameters } from "./buildPresentParameters";
+
+const component = (properties: z.ZodType) => ({
+  description: "A component",
+  properties,
+  render: () => null,
+});
+
+function resolve(root: JSONSchema7, value: JSONSchema7Definition) {
+  let schema = value as JSONSchema7;
+  if (schema.$ref === "#") return root;
+  if (schema.$ref) {
+    expect(schema.$ref).toMatch(/^#\//);
+    let target: unknown = root;
+    for (const segment of schema.$ref.slice(2).split("/")) {
+      const key = decodeURIComponent(segment)
+        .replace(/~1/g, "/")
+        .replace(/~0/g, "~");
+      target = (target as Record<string, unknown> | undefined)?.[key];
+    }
+    expect(target).toBeDefined();
+    schema = target as JSONSchema7;
+  }
+  return schema;
+}
+
+describe("component schema references", () => {
+  it("retains recursive definitions used by a component prop", () => {
+    const Tree = z.object({
+      label: z.string(),
+      get descendants() {
+        return z.array(Tree);
+      },
+    });
+    const schema = buildPresentParameters({
+      Tree: component(z.object({ tree: Tree })),
+    });
+    const tree = resolve(schema, schema.properties!.tree!);
+    expect(tree.properties!.label).toEqual({ type: "string" });
+    const descendants = tree.properties!.descendants as JSONSchema7;
+    expect(resolve(schema, descendants.items as JSONSchema7Definition)).toBe(
+      tree,
+    );
+  });
+
+  it("keeps definitions with the same generated name isolated across components", () => {
+    const TextTree = z.object({
+      value: z.string(),
+      get descendants() {
+        return z.array(TextTree);
+      },
+    });
+    const NumberTree = z.object({
+      value: z.number(),
+      get descendants() {
+        return z.array(NumberTree);
+      },
+    });
+    const schema = buildPresentParameters({
+      node: component(z.object({ textTree: TextTree })),
+      children: component(z.object({ numberTree: NumberTree })),
+    });
+    const textTree = resolve(schema, schema.properties!.textTree!);
+    const numberTree = resolve(schema, schema.properties!.numberTree!);
+    expect(textTree.properties!.value).toEqual({ type: "string" });
+    expect(numberTree.properties!.value).toEqual({ type: "number" });
+    expect(
+      resolve(
+        schema,
+        (textTree.properties!.descendants as JSONSchema7)
+          .items as JSONSchema7Definition,
+      ),
+    ).toBe(textTree);
+    expect(
+      resolve(
+        schema,
+        (numberTree.properties!.descendants as JSONSchema7)
+          .items as JSONSchema7Definition,
+      ),
+    ).toBe(numberTree);
+    expect(resolve(schema, schema.properties!.children!).anyOf).toBeDefined();
+    expect((schema.$defs!.node as JSONSchema7).properties!.$type).toBeDefined();
+  });
+
+  it("rebases root references to component props instead of the generated UI node", () => {
+    const Props = z.object({
+      label: z.string(),
+      get nested() {
+        return z.array(Props);
+      },
+    });
+    const schema = buildPresentParameters({ Recursive: component(Props) });
+    const nested = schema.properties!.nested as JSONSchema7;
+    const props = resolve(schema, nested.items as JSONSchema7Definition);
+    expect(props.properties!.label).toEqual({ type: "string" });
+    expect(props.properties!.$type).toBeUndefined();
+    expect(props.required).toEqual(["label", "nested"]);
+  });
+
+  it("rebases recursive references inside unions and records", () => {
+    const Tree = z.object({
+      get branches() {
+        return z.record(z.string(), z.union([z.string(), Tree]));
+      },
+    });
+    const schema = buildPresentParameters({
+      Tree: component(z.object({ tree: Tree })),
+    });
+    const tree = resolve(schema, schema.properties!.tree!);
+    const branches = tree.properties!.branches as JSONSchema7;
+    const variants = (branches.additionalProperties as JSONSchema7).anyOf!;
+    expect(resolve(schema, variants[1]!)).toBe(tree);
+  });
+
+  it("retains recursive definitions referenced from tuple items", () => {
+    const Tree = z.object({
+      label: z.string(),
+      get descendants() {
+        return z.array(Tree);
+      },
+    });
+    const schema = buildPresentParameters({
+      Pair: component(z.object({ pair: z.tuple([Tree, z.string()]) })),
+    });
+    const pair = schema.properties!.pair as JSONSchema7 & {
+      prefixItems?: JSONSchema7Definition[];
+    };
+    const first = (pair.prefixItems ??
+      (pair.items as JSONSchema7Definition[]))[0]!;
+    const tree = resolve(schema, first);
+    expect(tree.properties!.label).toEqual({ type: "string" });
+    expect(
+      resolve(
+        schema,
+        (tree.properties!.descendants as JSONSchema7)
+          .items as JSONSchema7Definition,
+      ),
+    ).toBe(tree);
+  });
+
+  it("rebases prefixItems in draft 2020-12 converter output", () => {
+    const raw = {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+      $id: "https://example.com/pair",
+      type: "object",
+      properties: {
+        pair: {
+          type: "array",
+          prefixItems: [{ $ref: "#/$defs/item" }, { type: "string" }],
+        },
+      },
+      $defs: {
+        item: {
+          type: "object",
+          properties: {
+            descendants: { type: "array", items: { $ref: "#/$defs/item" } },
+          },
+        },
+      },
+    };
+    const schema = buildPresentParameters({
+      Pair: component(raw as unknown as z.ZodType),
+    });
+    const pair = schema.properties!.pair as JSONSchema7 & {
+      prefixItems: JSONSchema7Definition[];
+    };
+    const item = resolve(schema, pair.prefixItems[0]!);
+    expect(item.properties!.descendants).toBeDefined();
+    expect(
+      resolve(
+        schema,
+        (item.properties!.descendants as JSONSchema7)
+          .items as JSONSchema7Definition,
+      ),
+    ).toBe(item);
+    const embedded = schema.$defs!.component0 as JSONSchema7;
+    expect(Object.keys(embedded)).not.toContain("$schema");
+    expect(Object.keys(embedded)).not.toContain("$id");
+  });
+
+  it("strips root resource metadata from embedded component schemas", () => {
+    const Tree = z.object({
+      get descendants() {
+        return z.array(Tree);
+      },
+    });
+    const schema = buildPresentParameters({
+      Tree: component(z.object({ tree: Tree })),
+    });
+    const embedded = schema.$defs!.component0 as JSONSchema7;
+    expect(Object.keys(embedded)).not.toContain("$schema");
+    expect(embedded.type).toBe("object");
+  });
+
+  it("omits component definitions whose properties all lose the duplicate-name merge", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const StringTree = z.object({
+        get tree() {
+          return z.array(StringTree);
+        },
+      });
+      const NumberTree = z.object({
+        value: z.number(),
+        get tree() {
+          return z.array(NumberTree);
+        },
+      });
+      const schema = buildPresentParameters({
+        first: component(z.object({ tree: StringTree })),
+        second: component(z.object({ tree: NumberTree })),
+      });
+      expect(Object.keys(schema.$defs!)).toEqual([
+        "node",
+        "children",
+        "component0",
+      ]);
+      expect(warn).toHaveBeenCalledOnce();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("leaves literal reference-shaped data and non-recursive schemas unchanged", () => {
+    const literal = {
+      $ref: "#/literal",
+      properties: { nested: { $ref: "#" } },
+    };
+    const schema = buildPresentParameters({
+      Card: component(
+        z.object({
+          label: z.string().meta({ examples: [literal], default: literal }),
+        }),
+      ),
+    });
+    expect(schema.properties!.label).toEqual({
+      type: "string",
+      examples: [literal],
+      default: literal,
+    });
+    expect(Object.keys(schema.$defs!)).toEqual(["node", "children"]);
+  });
+});

package/src/buildPresentParameters.ts

@@ -2,6 +2,7 @@ import { toJSONSchema } from "assistant-stream";
 import type { JSONSchema7, JSONSchema7Definition } from "json-schema";
 import { TYPE_KEY } from "./constants";
 import type { GenerativeUILibrary } from "./types";
+import { scopeSchema } from "./scopeSchema";
 
 /**
  * Builds the JSON schema for the `present` tool from a {@link GenerativeUILibrary}.
@@ -31,14 +32,20 @@ export function buildPresentParameters(
   // advisory hint here, not a strict per-component contract.
   const props = new Map<string, JSONSchema7Definition>();
   const propOwners = new Map<string, string[]>();
-  for (const name of names) {
-    const propsSchema = toJSONSchema(library[name]!.properties);
+  const componentSchemas: Record<string, JSONSchema7> = {};
+  for (const [index, name] of names.entries()) {
+    const definition = `component${index}`;
+    const { schema: propsSchema, referenced } = scopeSchema(
+      toJSONSchema(library[name]!.properties),
+      `#/$defs/${definition}`,
+    );
     if (propsSchema.type !== "object") {
       throw new Error(
         `[@assistant-ui/react-generative-ui] Component "${name}": ` +
           "`properties` must be an object schema (e.g. `z.object({ ... })`).",
       );
     }
+    let merged = false;
     for (const [key, schema] of Object.entries(propsSchema.properties ?? {})) {
       if (key.startsWith("$") || key === "children") continue;
       // secure-json-parse rejects the whole tool-argument payload on this key,
@@ -46,9 +53,17 @@ export function buildPresentParameters(
       if (key === "__proto__") continue;
       if (!props.has(key)) {
         props.set(key, schema);
+        merged = true;
       }
       propOwners.set(key, [...(propOwners.get(key) ?? []), name]);
     }
+    if (referenced && merged) {
+      // `$schema` is only valid at a schema-resource root, and an embedded
+      // `$id` would both collide across components and re-base the pointers
+      // scopeSchema just rewrote to be document-root relative.
+      const { $schema: _, $id: _id, ...embedded } = propsSchema;
+      componentSchemas[definition] = embedded;
+    }
   }
 
   if (process.env["NODE_ENV"] !== "production") {
@@ -101,7 +116,7 @@ export function buildPresentParameters(
 
   return {
     ...node,
-    $defs: { node, children },
+    $defs: { node, children, ...componentSchemas },
   };
 }
 

package/src/scopeSchema.test.ts

@@ -0,0 +1,72 @@
+import type { JSONSchema7 } from "json-schema";
+import { describe, expect, it } from "vitest";
+import { scopeSchema } from "./scopeSchema";
+
+const ref = { $ref: "#/definitions/a~1b~0c" };
+const scopedRef = { $ref: "#/$defs/component0/definitions/a~1b~0c" };
+const scope = (schema: JSONSchema7) =>
+  scopeSchema(schema, "#/$defs/component0");
+
+describe("scopeSchema", () => {
+  it.each([
+    "properties",
+    "patternProperties",
+    "definitions",
+    "$defs",
+    "dependentSchemas",
+  ])("rebases schemas inside %s without changing the input", (keyword) => {
+    const original = {
+      [keyword]: { value: ref, allowed: true, forbidden: false },
+    };
+    const result = scope(original);
+    expect(result.schema).toEqual({
+      [keyword]: { value: scopedRef, allowed: true, forbidden: false },
+    });
+    expect(result.referenced).toBe(true);
+    expect(original).toEqual({
+      [keyword]: { value: ref, allowed: true, forbidden: false },
+    });
+  });
+  it.each(["allOf", "anyOf", "oneOf", "items", "prefixItems"])(
+    "rebases schemas in %s arrays",
+    (keyword) => {
+      expect(scope({ [keyword]: [ref, true, false] }).schema).toEqual({
+        [keyword]: [scopedRef, true, false],
+      });
+    },
+  );
+  it.each([
+    "items",
+    "additionalProperties",
+    "additionalItems",
+    "unevaluatedProperties",
+    "unevaluatedItems",
+    "contentSchema",
+    "contains",
+    "propertyNames",
+    "not",
+    "if",
+    "then",
+    "else",
+  ])("rebases the %s subschema", (keyword) => {
+    expect(scope({ [keyword]: ref }).schema).toEqual({ [keyword]: scopedRef });
+  });
+  it("preserves property dependencies while rebasing schema dependencies", () => {
+    expect(
+      scope({ dependencies: { first: ["second"], other: ref } }).schema,
+    ).toEqual({ dependencies: { first: ["second"], other: scopedRef } });
+  });
+  it("leaves literal data, external references, and named anchors unchanged", () => {
+    const schema: JSONSchema7 = {
+      default: ref,
+      examples: [ref],
+      enum: [ref],
+      const: ref,
+      properties: {
+        remote: { $ref: "https://example.com/schema.json#/definitions/value" },
+        anchor: { $ref: "#value" },
+      },
+    };
+    expect(scope(schema)).toEqual({ schema, referenced: false });
+  });
+});

package/src/scopeSchema.ts

@@ -0,0 +1,71 @@
+import type { JSONSchema7, JSONSchema7Definition } from "json-schema";
+
+// The converter does not pin a JSON Schema draft, so the 2020-12 applicators
+// missing from the JSONSchema7 typings must be traversed as well.
+type TraversableSchema = JSONSchema7 & {
+  prefixItems?: JSONSchema7Definition[];
+  dependentSchemas?: { [key: string]: JSONSchema7Definition };
+  unevaluatedItems?: JSONSchema7Definition;
+  unevaluatedProperties?: JSONSchema7Definition;
+  contentSchema?: JSONSchema7Definition;
+};
+
+export function scopeSchema(schema: JSONSchema7, path: string) {
+  let referenced = false;
+  const visit = (definition: JSONSchema7Definition): JSONSchema7Definition => {
+    if (typeof definition === "boolean") return definition;
+    const schema = definition as TraversableSchema;
+    const result = { ...schema };
+    if (schema.$ref === "#" || schema.$ref?.startsWith("#/")) {
+      referenced = true;
+      result.$ref = path + schema.$ref.slice(1);
+    }
+    // Only schema-bearing keywords are traversed; defaults and examples are data.
+    for (const key of [
+      "properties",
+      "patternProperties",
+      "definitions",
+      "$defs",
+      "dependentSchemas",
+    ] as const) {
+      const entries = schema[key];
+      if (entries)
+        result[key] = Object.fromEntries(
+          Object.entries(entries).map(([name, value]) => [name, visit(value)]),
+        );
+    }
+    for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"] as const) {
+      if (schema[key]) result[key] = schema[key].map(visit);
+    }
+    for (const key of [
+      "additionalProperties",
+      "additionalItems",
+      "unevaluatedProperties",
+      "unevaluatedItems",
+      "contentSchema",
+      "contains",
+      "propertyNames",
+      "not",
+      "if",
+      "then",
+      "else",
+    ] as const) {
+      const value = schema[key];
+      if (value !== undefined) result[key] = visit(value);
+    }
+    if (schema.items !== undefined)
+      result.items = Array.isArray(schema.items)
+        ? schema.items.map(visit)
+        : visit(schema.items);
+    if (schema.dependencies)
+      result.dependencies = Object.fromEntries(
+        Object.entries(schema.dependencies).map(([name, value]) => [
+          name,
+          Array.isArray(value) ? value : visit(value),
+        ]),
+      );
+    return result;
+  };
+  const scoped = visit(schema) as JSONSchema7;
+  return { schema: scoped, referenced };
+}

package/src/vocabulary/interactive.dispatch.test.tsx

@@ -1,5 +1,10 @@
 import { describe, it, expect, vi } from "vitest";
-import { isValidElement, type ReactElement, type ReactNode } from "react";
+import {
+  Children,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { interactiveVocabulary } from "./interactive";
 import { createActionRegistry } from "../actionRegistry";
@@ -27,6 +32,15 @@ function renderWithHooks(render: () => ReactNode): ReactElement {
   return captured!;
 }
 
+const getRadioOptions = (out: ReactElement) =>
+  Children.toArray((out.props as { children: ReactNode }).children)
+    .filter(isValidElement)
+    .filter(
+      (child) =>
+        (child.props as { "data-aui"?: string })["data-aui"] ===
+        "radiogroup-option",
+    ) as ReactElement[];
+
 describe("interactiveVocabulary $action dispatch", () => {
   it("Button render attaches an onClick that fires $dispatch with the $action payload", () => {
     const handler = vi.fn();
@@ -319,7 +333,7 @@ describe("interactiveVocabulary $action dispatch", () => {
         ],
       }),
     );
-    const options = (out.props as { children: ReactElement[] }).children;
+    const options = getRadioOptions(out);
     const secondRadio = (options[1]!.props as { children: ReactElement[] })
       .children[0] as ReactElement;
     const onChange = (secondRadio.props as { onChange: () => void }).onChange;
@@ -339,7 +353,7 @@ describe("interactiveVocabulary $action dispatch", () => {
         ],
       }),
     );
-    const options = (out.props as { children: ReactElement[] }).children;
+    const options = getRadioOptions(out);
     const firstRadio = (options[0]!.props as { children: ReactElement[] })
       .children[0] as ReactElement;
     const secondRadio = (options[1]!.props as { children: ReactElement[] })

package/src/vocabulary/interactive.test.tsx

@@ -3,6 +3,7 @@ import { renderToStaticMarkup } from "react-dom/server";
 import { GENERATED_NAME_ATTR } from "../constants";
 import { renderGenerativeUI } from "../renderGenerativeUI";
 import { interactiveVocabulary } from "./interactive";
+import { defaultGenerativeUILibrary } from "./index";
 
 const render = (node: unknown) =>
   renderToStaticMarkup(<>{renderGenerativeUI(node, interactiveVocabulary)}</>);
@@ -214,6 +215,24 @@ describe("interactiveVocabulary", () => {
     expect(html).toContain("Large");
   });
 
+  it("RadioGroup renders model-provided children after the options inside the fieldset", () => {
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          {
+            $type: "RadioGroup",
+            options: [{ label: "Small", value: "sm" }],
+            children: { $type: "Text", value: "Additional context" },
+          },
+          defaultGenerativeUILibrary,
+        )}
+      </>,
+    );
+    expect(html).toMatch(
+      /^<fieldset data-aui="radiogroup">.*data-aui="radiogroup-option".*Small<\/label>.*Additional context.*<\/fieldset>$/,
+    );
+  });
+
   it("RadioGroup renders an aria-label from the label prop", () => {
     const html = render({
       $type: "RadioGroup",

package/src/vocabulary/interactive.tsx

@@ -1,4 +1,4 @@
-import { useId } from "react";
+import { useId, type ReactNode } from "react";
 import { z } from "zod";
 import { GENERATED_NAME_ATTR } from "../constants";
 import type { Action } from "../ir";
@@ -31,6 +31,7 @@ type RadioGroupRenderProps = {
   name?: string;
   label?: string;
   defaultValue?: string;
+  children?: ReactNode;
   $status: GenerativeUIStatus;
   $action?: Action;
   $dispatch?: GenerativeUIDispatch;
@@ -41,6 +42,7 @@ function RadioGroupRender({
   name,
   label,
   defaultValue,
+  children,
   $action,
   $dispatch,
 }: RadioGroupRenderProps) {
@@ -68,6 +70,7 @@ function RadioGroupRender({
           </label>
         ) : null,
       )}
+      {children}
     </fieldset>
   );
 }