@assistant-ui/react-generative-ui 0.0.24 → 0.1.0

package/src/renderGenerativeUI.tsx

@@ -1,165 +0,0 @@
-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";
-import type { GenerativeUILibrary, GenerativeUIRenderContext } from "./types";
-
-const DEFAULT_CONTEXT: GenerativeUIRenderContext = { status: "done" };
-
-const isElement = (node: NormalizedUINode): node is NormalizedUIElement =>
-  typeof node === "object" && node !== null && !Array.isArray(node);
-
-/**
- * Renders a generative-ui tree against a {@link GenerativeUILibrary}.
- *
- * The model emits each node as a flat object `{ $type, ...props }`. We first
- * normalize that wire form into the canonical {@link NormalizedUINode} (with
- * `children` lifted to a reserved top-level key), then render: each `type` is
- * looked up in the library and its `props` are passed to the component's
- * `render(props, context)`, with `children` rendered recursively so components
- * can nest.
- */
-export function renderGenerativeUI(
-  node: unknown,
-  library: GenerativeUILibrary,
-  context: GenerativeUIRenderContext = DEFAULT_CONTEXT,
-): ReactNode {
-  // Tool args are parsed incrementally, and the parse meta records which path
-  // is still mid-arrival, so normalization can hold back a node whose `$type`
-  // string has not finished streaming.
-  const meta = getPartialJsonObjectMeta(node as Record<symbol, unknown>);
-  const partialPath = meta?.state === "partial" ? meta.partialPath : undefined;
-  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,
-  context: GenerativeUIRenderContext,
-): ReactNode {
-  if (node == null || typeof node === "boolean") return null;
-  if (typeof node === "string" || typeof node === "number") return node;
-  if (Array.isArray(node)) {
-    // Use a model-provided stable key when present. Otherwise, keep the
-    // positional fallback: pairing the index with the node's kind means that
-    // when the kind at an index changes, React remounts instead of handing a
-    // streaming node's hook state to a different component.
-    return node.map((child, index) => (
-      <Fragment key={nodeKey(child, index)}>
-        {renderNode(child, library, context)}
-      </Fragment>
-    ));
-  }
-  return isElement(node) ? renderElement(node, library, context) : null;
-}
-
-function renderElement(
-  element: NormalizedUIElement,
-  library: GenerativeUILibrary,
-  context: GenerativeUIRenderContext,
-): ReactNode {
-  const entry = Object.hasOwn(library, element.type)
-    ? library[element.type]
-    : undefined;
-  if (!entry) {
-    reportUnknownComponent(element.type, Object.keys(library));
-    return null;
-  }
-
-  // Components that opt out of prop streaming wait until their props are
-  // complete rather than rendering from a partial parse.
-  if (!entry.streamProperties && context.status === "streaming") return null;
-
-  // `children` is a reserved top-level key on the normalized element, not a
-  // prop, so it is not in `props`. Inject the framework props last so the model
-  // can never override them. `$action` is likewise reserved and stripped from
-  // the prop bag during normalization, so it is re-injected here for components
-  // that carry behavior (e.g. `Button`).
-  const props: Record<string, unknown> = {
-    ...element.props,
-    $status: context.status,
-  };
-  if (context.dispatch !== undefined) {
-    props["$dispatch"] = context.dispatch;
-  }
-  if (element.action !== undefined) {
-    props["$action"] = element.action;
-  }
-  if (element.children !== undefined) {
-    props["children"] = renderNode(element.children, library, context);
-  }
-
-  return <GenerativeUIComponentRenderer render={entry.render} props={props} />;
-}
-
-/**
- * Mounts a single node's `render` on its own fiber so the function may use
- * hooks and hold state independently of its siblings and parent.
- */
-function GenerativeUIComponentRenderer({
-  render,
-  props,
-}: {
-  render: (props: any) => ReactNode;
-  props: Record<string, unknown>;
-}): ReactNode {
-  return render(props);
-}
-
-/** A coarse kind tag for a child, used in its list key so a node changing kind
- * at a given index forces a remount rather than a wrong-fiber reuse. */
-function nodeKind(node: NormalizedUINode): string {
-  if (node == null || typeof node === "boolean") return "";
-  if (typeof node === "string" || typeof node === "number") return "#text";
-  if (Array.isArray(node)) return "#array";
-  return isElement(node) ? node.type : "";
-}
-
-function nodeKey(node: NormalizedUINode, index: number): string {
-  return isElement(node) &&
-    (typeof node.key === "string" || typeof node.key === "number")
-    ? `model:${node.key}`
-    : `${index}:${nodeKind(node)}`;
-}
-
-function reportUnknownComponent(type: string, available: string[]): void {
-  if (process.env["NODE_ENV"] !== "production") {
-    // eslint-disable-next-line no-console
-    console.error(
-      `[@assistant-ui/react-generative-ui] Unknown component "${type}". ` +
-        `Available components: ${available.join(", ") || "(none)"}.`,
-    );
-  }
-}

package/src/scopeSchema.test.ts

@@ -1,72 +0,0 @@
-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

@@ -1,71 +0,0 @@
-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/slack/a2uiSlack.test.ts

@@ -1,198 +0,0 @@
-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

@@ -1,194 +0,0 @@
-import type {
-  SlackAlertBlock,
-  SlackButtonElement,
-  SlackCardBlock,
-  SlackCarouselBlock,
-  SlackContextBlock,
-  SlackDataTableBlock,
-  SlackDataTableCell,
-  SlackImageBlock,
-  SlackSectionBlock,
-  SlackTextObject,
-} from "./types";
-
-/** The block limit for a Slack message. */
-export const MESSAGE_BLOCK_CAP = 50;
-
-/** The block limit for a Slack modal. */
-export const MODAL_BLOCK_CAP = 100;
-
-/**
- * The maximum number of top-level blocks accepted when parsing Slack Block
- * Kit JSON back into generative UI, guarding against a hostile or malformed
- * payload.
- */
-export const INBOUND_BLOCK_CAP = 200;
-
-/** The character limit for header text. */
-export const HEADER_TEXT_CAP = 150;
-
-/** The character limit for section text. */
-export const SECTION_TEXT_CAP = 3000;
-
-/** The maximum number of fields in one section. */
-export const FACT_FIELD_CAP = 10;
-
-/** The character limit for one section field. */
-export const FACT_FIELD_TEXT_CAP = 2000;
-
-/** The character limit for button labels and option labels. */
-export const INTERACTIVE_TEXT_CAP = 75;
-
-/** The character limit for an action_id. */
-export const ACTION_ID_CAP = 255;
-
-/** The character limit for a button's serialized value payload. */
-export const BUTTON_VALUE_CAP = 2000;
-
-/** The maximum number of elements in one actions block. */
-export const ACTIONS_ELEMENT_CAP = 25;
-
-/** The maximum number of options in a static select. */
-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;
-
-/** The character limit for an input's label. */
-export const INPUT_LABEL_CAP = 2000;
-
-/** The maximum number of elements in one context block. */
-export const CONTEXT_ELEMENT_CAP = 10;
-
-/** The character limit for one context element's text. */
-export const CONTEXT_TEXT_CAP = 3000;
-
-/** The character limit for card titles and subtitles. */
-export const CARD_TITLE_CAP = 150;
-
-/** The character limit for a card's body text. */
-export const CARD_BODY_CAP = 200;
-
-/** The character limit for a card's subtext. */
-export const CARD_SUBTEXT_CAP = 200;
-
-/** The maximum number of buttons in a card's actions. */
-export const CARD_ACTIONS_CAP = 3;
-
-/** The minimum number of elements in a renderable carousel. */
-export const CAROUSEL_CARD_MIN = 1;
-
-/** The maximum number of elements in a carousel. */
-export const CAROUSEL_CARD_CAP = 10;
-
-/** The character limit for an alert's text. */
-export const ALERT_TEXT_CAP = 200;
-
-/**
- * The maximum number of data rows in a data-table block; the emitted `rows`
- * array additionally carries one header row.
- */
-export const DATA_TABLE_ROW_CAP = 200;
-
-/** The maximum number of columns in a data-table block. */
-export const DATA_TABLE_COLUMN_CAP = 20;
-
-/**
- * The cumulative character limit (summed across every cell's text) shared by
- * every data-table block in one payload.
- */
-export const DATA_TABLE_CHAR_BUDGET = 20000;
-
-/** The caption emitted on every native data-table block. */
-export const TABLE_CAPTION = "Table";
-
-/** The cumulative character limit for native markdown blocks. */
-export const MARKDOWN_TEXT_BUDGET = 12000;
-
-/** Builds the message-surface fallback for an alert. */
-export function buildAlertFallback(
-  title: string,
-  description: string,
-  tone: "info" | "success" | "warning" | "danger",
-): readonly [SlackContextBlock, SlackSectionBlock] {
-  const emoji = {
-    info: "ℹ️",
-    success: "✅",
-    warning: "⚠️",
-    danger: "🛑",
-  }[tone];
-  return [
-    {
-      type: "context",
-      elements: [
-        { type: "mrkdwn", text: title ? `${emoji} *${title}*` : emoji },
-      ],
-    },
-    { type: "section", text: { type: "mrkdwn", text: description } },
-  ];
-}
-
-/** Builds a 2026 Slack modal-only alert block, mapping `tone` to its `level`. */
-export function buildAlertBlock(
-  text: string,
-  tone: "info" | "success" | "warning" | "danger",
-): SlackAlertBlock {
-  const level = tone === "danger" ? "error" : tone;
-  return { type: "alert", text: { type: "mrkdwn", text }, level };
-}
-
-type CardBlockFields = {
-  readonly heroImage?: SlackImageBlock;
-  readonly title?: SlackTextObject;
-  readonly subtitle?: SlackTextObject;
-  readonly body?: SlackTextObject;
-  readonly subtext?: SlackTextObject;
-  readonly actions?: readonly SlackButtonElement[];
-};
-
-/** Builds a 2026 Slack card block from its already-clamped fields. */
-export function buildCardBlock(fields: CardBlockFields): SlackCardBlock {
-  const { heroImage, title, subtitle, body, subtext, actions } = fields;
-  return {
-    type: "card",
-    ...(heroImage !== undefined ? { hero_image: heroImage } : {}),
-    ...(title !== undefined ? { title } : {}),
-    ...(subtitle !== undefined ? { subtitle } : {}),
-    ...(body !== undefined ? { body } : {}),
-    ...(subtext !== undefined ? { subtext } : {}),
-    ...(actions !== undefined ? { actions } : {}),
-  };
-}
-
-/** Builds a 2026 Slack carousel block. */
-export function buildCarouselBlock(
-  elements: readonly SlackCardBlock[],
-): SlackCarouselBlock {
-  return { type: "carousel", elements };
-}
-
-/** Builds a 2026 Slack data-table block; `rows[0]` must be the header row. */
-export function buildDataTableBlock(
-  rows: readonly (readonly SlackDataTableCell[])[],
-): SlackDataTableBlock {
-  return { type: "data_table", caption: TABLE_CAPTION, rows };
-}
-
-/** Builds the final note used when a surface block budget is exceeded. */
-export function buildBlockBudgetNote(omitted: number): SlackContextBlock {
-  return {
-    type: "context",
-    elements: [
-      {
-        type: "mrkdwn",
-        text: `${omitted} ${omitted === 1 ? "block was" : "blocks were"} omitted.`,
-      },
-    ],
-  };
-}