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

package/src/teams/toTeamsAttachments.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { toTeamsAttachments } from "./toTeamsAttachments";
+import { PAYLOAD_SOFT_CAP } from "./constants";
+
+describe("toTeamsAttachments payload budget", () => {
+  it("warns on the aggregate carousel size even when no single card exceeds the soft cap", () => {
+    const value = "x".repeat(45000);
+    const { attachments, warnings } = toTeamsAttachments({
+      $type: "Carousel",
+      children: [
+        { $type: "Card", title: "A", children: { $type: "Markdown", value } },
+        { $type: "Card", title: "B", children: { $type: "Markdown", value } },
+      ],
+    });
+    for (const attachment of attachments) {
+      expect(JSON.stringify(attachment.content).length).toBeLessThanOrEqual(
+        PAYLOAD_SOFT_CAP,
+      );
+    }
+    expect(
+      warnings.some(
+        (warning) => warning.code === "clamped" && warning.component === "Root",
+      ),
+    ).toBe(false);
+    expect(warnings).toContainEqual(
+      expect.objectContaining({ code: "clamped", component: "Carousel" }),
+    );
+  });
+});

package/src/teams/toTeamsAttachments.ts

@@ -0,0 +1,137 @@
+import {
+  normalizeSpec,
+  type NormalizedUIElement,
+  type NormalizedUINode,
+} from "../ir";
+import { boundSpec } from "./boundSpec";
+import {
+  CAROUSEL_ATTACHMENT_CAP,
+  PAYLOAD_SOFT_CAP,
+  buildAttachment,
+  clampReasonDetail,
+  utf8ByteLength,
+} from "./constants";
+import {
+  convertElement,
+  convertRootToCard,
+  type ConversionContext,
+} from "./toAdaptiveCard";
+import type {
+  TeamsAttachmentsResult,
+  TeamsCardAttachment,
+  TeamsConversionWarning,
+  ToAdaptiveCardOptions,
+} from "./types";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isElement = (node: NormalizedUINode): node is NormalizedUIElement =>
+  isRecord(node);
+
+const normalizedList = (
+  node: NormalizedUINode | undefined,
+): NormalizedUINode[] => {
+  if (node === undefined || node === null) return [];
+  if (!Array.isArray(node)) return [node];
+  return node.flatMap((child) => normalizedList(child));
+};
+
+const clampArray = <T>(
+  value: readonly T[],
+  cap: number,
+): { readonly items: T[]; readonly truncated: boolean } => ({
+  items: value.slice(0, cap),
+  truncated: value.length > cap,
+});
+
+/**
+ * Recognizes a root that is a single `Carousel` element, returning its `Card`
+ * children. Every child is routed through {@link convertElement} first (its
+ * result is discarded) so an unknown or unsupported child still produces its
+ * usual "dropped" warning instead of being filtered out silently; non-card
+ * children are then dropped. `undefined` means the root is not exclusively a
+ * root-level carousel, so the caller falls back to converting the whole tree
+ * as one card.
+ */
+function rootCarouselCards(
+  root: NormalizedUINode | readonly NormalizedUINode[],
+  context: ConversionContext,
+): NormalizedUIElement[] | undefined {
+  const element = Array.isArray(root) && root.length === 1 ? root[0] : root;
+  if (!isElement(element) || element.type !== "Carousel") return undefined;
+  const cards: NormalizedUIElement[] = [];
+  for (const child of normalizedList(element.children)) {
+    if (!isElement(child)) continue;
+    if (child.type === "Card") {
+      cards.push(child);
+    } else {
+      convertElement(child, context, 1);
+    }
+  }
+  return cards;
+}
+
+/**
+ * Converts a generative-ui tree into Teams bot-framework message attachments.
+ * A root-level `Carousel` becomes one attachment per `Card` child (clamped to
+ * {@link CAROUSEL_ATTACHMENT_CAP}) with `attachmentLayout: "carousel"`;
+ * anything else converts through {@link toAdaptiveCard}'s engine into a
+ * single attachment. Never throws.
+ */
+export function toTeamsAttachments(
+  node: unknown,
+  _options?: ToAdaptiveCardOptions,
+): TeamsAttachmentsResult {
+  const warnings: TeamsConversionWarning[] = [];
+  const context: ConversionContext = { warnings, usedInputIds: new Set() };
+  try {
+    const bounded = boundSpec(node, (reason) =>
+      warnings.push({
+        code: "clamped",
+        component: "Root",
+        detail: clampReasonDetail(reason),
+      }),
+    );
+    const { root } = normalizeSpec(bounded as never);
+    const carouselCards = rootCarouselCards(root, context);
+    if (carouselCards !== undefined) {
+      const { items, truncated } = clampArray(
+        carouselCards,
+        CAROUSEL_ATTACHMENT_CAP,
+      );
+      if (truncated) {
+        warnings.push({
+          code: "clamped",
+          component: "Carousel",
+          detail: `cards were clamped to ${CAROUSEL_ATTACHMENT_CAP} entries.`,
+        });
+      }
+      const attachments: TeamsCardAttachment[] = items.map((child) =>
+        buildAttachment(convertRootToCard(child, context)),
+      );
+      const size = utf8ByteLength(JSON.stringify(attachments));
+      if (size > PAYLOAD_SOFT_CAP) {
+        warnings.push({
+          code: "clamped",
+          component: "Carousel",
+          detail: `the carousel attachments total ${size} bytes, exceeding Teams' 100 KB bot message limit.`,
+        });
+      }
+      return { attachments, attachmentLayout: "carousel", warnings };
+    }
+    const attachment = buildAttachment(convertRootToCard(root, context));
+    return { attachments: [attachment], warnings };
+  } catch {
+    return {
+      attachments: [],
+      warnings: [
+        {
+          code: "dropped",
+          component: "Root",
+          detail: "Input could not be converted.",
+        },
+      ],
+    };
+  }
+}

package/src/teams/types.ts

@@ -0,0 +1,237 @@
+/** A TextBlock size, from Adaptive Card's closed size enum. */
+export type TeamsTextSize = "small" | "medium" | "large" | "extraLarge";
+
+/** A Container's style, driving its accent color in Teams' renderer. */
+export type TeamsContainerStyle =
+  | "default"
+  | "emphasis"
+  | "good"
+  | "attention"
+  | "warning"
+  | "accent";
+
+/** A run of wrapped text. Every TextBlock we emit sets `wrap: true`. */
+export interface TeamsTextBlock {
+  readonly type: "TextBlock";
+  readonly text: string;
+  readonly wrap: true;
+  readonly size?: TeamsTextSize;
+  readonly weight?: "bolder";
+  readonly style?: "heading";
+  readonly isSubtle?: true;
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** An image element. */
+export interface TeamsImage {
+  readonly type: "Image";
+  readonly url: string;
+  readonly altText?: string;
+  readonly size?: "small" | "medium" | "large";
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** One label/value entry inside a {@link TeamsFactSet}. */
+export interface TeamsFact {
+  readonly title: string;
+  readonly value: string;
+}
+
+/** A set of label/value facts, rendered as an aligned two-column list. */
+export interface TeamsFactSet {
+  readonly type: "FactSet";
+  readonly facts: readonly TeamsFact[];
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** The `aui` envelope nested inside every {@link TeamsSubmitAction}'s `data`. */
+export interface TeamsSubmitData {
+  readonly aui: {
+    readonly type: string;
+    readonly payload?: Record<string, unknown>;
+  };
+}
+
+/**
+ * A submit action. `data` carries the resume payload under an `aui` key so
+ * {@link decodeSubmitData} can invert it out of the merged `activity.value`
+ * a Teams bot receives, alongside whatever other named inputs shared the card.
+ */
+export interface TeamsSubmitAction {
+  readonly type: "Action.Submit";
+  readonly title: string;
+  readonly data: TeamsSubmitData;
+  readonly mode?: "secondary";
+}
+
+/** The action shape accepted at the card's top-level `actions` field. */
+export type TeamsCardAction = TeamsSubmitAction;
+
+/** A bar of submit actions, rendered inline in the body flow. */
+export interface TeamsActionSet {
+  readonly type: "ActionSet";
+  readonly actions: readonly TeamsSubmitAction[];
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** A bordered grouping container. */
+export interface TeamsContainer {
+  readonly type: "Container";
+  readonly style?: TeamsContainerStyle;
+  readonly items: readonly TeamsCardElement[];
+  readonly selectAction?: TeamsSubmitAction;
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** One column inside a {@link TeamsColumnSet}. */
+export interface TeamsColumn {
+  readonly type: "Column";
+  readonly width: "auto";
+  readonly items: readonly TeamsCardElement[];
+}
+
+/** A horizontal row of columns. */
+export interface TeamsColumnSet {
+  readonly type: "ColumnSet";
+  readonly columns: readonly TeamsColumn[];
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** One selectable choice inside a {@link TeamsInputChoiceSet}. */
+export interface TeamsInputChoice {
+  readonly title: string;
+  readonly value: string;
+}
+
+/** A dropdown (`compact`) or radio group (`expanded`) input. */
+export interface TeamsInputChoiceSet {
+  readonly type: "Input.ChoiceSet";
+  readonly id: string;
+  readonly style: "compact" | "expanded";
+  readonly choices: readonly TeamsInputChoice[];
+  readonly placeholder?: string;
+  readonly label?: string;
+  readonly value?: string;
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** A checkbox-shaped boolean input. */
+export interface TeamsInputToggle {
+  readonly type: "Input.Toggle";
+  readonly id: string;
+  readonly title: string;
+  readonly value: "true" | "false";
+  readonly valueOn: "true";
+  readonly valueOff: "false";
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** A single or multi-line text input. */
+export interface TeamsInputText {
+  readonly type: "Input.Text";
+  readonly id: string;
+  readonly label?: string;
+  readonly placeholder?: string;
+  readonly isMultiline?: true;
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** A date input, restricted to `YYYY-MM-DD` values. */
+export interface TeamsInputDate {
+  readonly type: "Input.Date";
+  readonly id: string;
+  readonly label?: string;
+  readonly value?: string;
+  readonly min?: string;
+  readonly max?: string;
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** One cell inside a {@link TeamsTableRow}. */
+export interface TeamsTableCell {
+  readonly type: "TableCell";
+  readonly items: readonly TeamsTextBlock[];
+}
+
+/** One row inside a {@link TeamsTable}. */
+export interface TeamsTableRow {
+  readonly type: "TableRow";
+  readonly cells: readonly TeamsTableCell[];
+}
+
+/** A column width definition inside a {@link TeamsTable}. */
+export interface TeamsTableColumnDefinition {
+  readonly width: 1;
+}
+
+/** A native table. `rows[0]` is the header row when `firstRowAsHeaders` is true. */
+export interface TeamsTable {
+  readonly type: "Table";
+  readonly firstRowAsHeaders: boolean;
+  readonly columns: readonly TeamsTableColumnDefinition[];
+  readonly rows: readonly TeamsTableRow[];
+  readonly separator?: true;
+  readonly spacing?: "large";
+}
+
+/** A body element emitted by {@link toAdaptiveCard}. */
+export type TeamsCardElement =
+  | TeamsTextBlock
+  | TeamsImage
+  | TeamsFactSet
+  | TeamsActionSet
+  | TeamsContainer
+  | TeamsColumnSet
+  | TeamsInputChoiceSet
+  | TeamsInputToggle
+  | TeamsInputText
+  | TeamsInputDate
+  | TeamsTable;
+
+/** A Microsoft Teams Adaptive Card, pinned to schema version 1.5 (the Teams desktop/web cap; mobile clients cap at 1.2). */
+export interface TeamsAdaptiveCard {
+  readonly $schema: "http://adaptivecards.io/schemas/adaptive-card.json";
+  readonly type: "AdaptiveCard";
+  readonly version: "1.5";
+  readonly body: readonly TeamsCardElement[];
+  readonly actions: readonly TeamsCardAction[];
+}
+
+/** An Adaptive Card wrapped as a bot-framework message attachment. */
+export interface TeamsCardAttachment {
+  readonly contentType: "application/vnd.microsoft.card.adaptive";
+  readonly content: TeamsAdaptiveCard;
+}
+
+/** A non-fatal downgrade reported during Teams conversion. */
+export interface TeamsConversionWarning {
+  readonly code: "clamped" | "dropped" | "fallback";
+  readonly component: string;
+  readonly detail: string;
+}
+
+/** Options accepted by {@link toAdaptiveCard} and {@link toTeamsAttachments}. Reserved for future extension; no options are currently defined. */
+export interface ToAdaptiveCardOptions {}
+
+/** The card and non-fatal warnings produced by {@link toAdaptiveCard}. */
+export interface AdaptiveCardResult {
+  readonly card: TeamsAdaptiveCard;
+  readonly warnings: TeamsConversionWarning[];
+}
+
+/** The attachments and non-fatal warnings produced by {@link toTeamsAttachments}. */
+export interface TeamsAttachmentsResult {
+  readonly attachments: TeamsCardAttachment[];
+  readonly attachmentLayout?: "carousel";
+  readonly warnings: TeamsConversionWarning[];
+}

package/src/teams.ts

@@ -0,0 +1,34 @@
+export { decodeSubmitData } from "./teams/decodeSubmitData";
+export { toAdaptiveCard } from "./teams/toAdaptiveCard";
+export { toTeamsAttachments } from "./teams/toTeamsAttachments";
+export type {
+  AdaptiveCardResult,
+  TeamsAdaptiveCard,
+  TeamsActionSet,
+  TeamsAttachmentsResult,
+  TeamsCardAction,
+  TeamsCardAttachment,
+  TeamsCardElement,
+  TeamsColumn,
+  TeamsColumnSet,
+  TeamsContainer,
+  TeamsContainerStyle,
+  TeamsConversionWarning,
+  TeamsFact,
+  TeamsFactSet,
+  TeamsImage,
+  TeamsInputChoice,
+  TeamsInputChoiceSet,
+  TeamsInputDate,
+  TeamsInputText,
+  TeamsInputToggle,
+  TeamsSubmitAction,
+  TeamsSubmitData,
+  TeamsTable,
+  TeamsTableCell,
+  TeamsTableColumnDefinition,
+  TeamsTableRow,
+  TeamsTextBlock,
+  TeamsTextSize,
+  ToAdaptiveCardOptions,
+} from "./teams/types";

package/src/types.ts

@@ -1,28 +1,78 @@
 import type { ReactNode } from "react";
 import type { ZodType } from "zod";
+import type { Action, NormalizedUIElement } from "./ir";
+
+/**
+ * The canonical generative-ui element, normalized from the flat `$type` shape
+ * or the legacy `component` shape (see {@link normalizeUINode}). `children` is
+ * a reserved top-level key, not a prop, so it lives here rather than inside
+ * `props`. Alias of {@link NormalizedUIElement}; kept under its old name so the
+ * package's public surface stays append-only.
+ */
+export type GenerativeUIElement = NormalizedUIElement;
+
+export type GenerativeUIProps = NormalizedUIElement["props"];
+
+/**
+ * Anything renderable as generative UI — mirrors React's `ReactNode`: an
+ * element, primitive text, a list of nodes, or nothing. Widened beyond the
+ * model payload (a {@link GenerativeUIElement}) with the renderer's
+ * null/boolean/undefined inputs.
+ */
+export type GenerativeUINode =
+  | GenerativeUIElement
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | GenerativeUINode[];
+
+export type GenerativeUIAction = Action;
 
 /** Whether a node's props are still streaming in or have fully arrived. */
 export type GenerativeUIStatus = "streaming" | "done";
 
+/** The dispatcher an interactive component calls to fire its `$action`. */
+export type GenerativeUIDispatch = (action: Action) => unknown;
+
 /** The render context threaded through {@link renderGenerativeUI}. */
 export type GenerativeUIRenderContext = {
   /** Whether the tool call's arguments are still streaming or are complete. */
   status: GenerativeUIStatus;
+  dispatch?: GenerativeUIDispatch;
 };
 
 /**
  * Props a component's `render` receives: its model props, rendered `children`,
- * and the injected `$status`. `$status` is the discriminant — when it is
- * `"done"`, `P` is complete; while `"streaming"`, `P` is partial. It is named
- * `$status` (not `status`) so it never collides with a real `status` prop, the
- * same reservation as `$type`.
+ * and the injected framework keys. `$status` is the discriminant — when it is
+ * `"done"`, `P` is complete; while `"streaming"`, `P` is partial. `$action` is
+ * the node's behavior payload, present only on interactive nodes. `$dispatch`
+ * fires that payload through the host's {@link ActionRegistry}; it is present
+ * only when a registry was wired. All three are `$`-prefixed so they never
+ * collide with a real `status`/`action`/`dispatch` prop.
  */
 type StreamingRenderProps<P> =
-  | (Partial<P> & { children?: ReactNode; $status: "streaming" })
-  | (P & { children?: ReactNode; $status: "done" });
+  | (Partial<P> & {
+      children?: ReactNode;
+      $status: "streaming";
+      $action?: Action;
+      $dispatch?: GenerativeUIDispatch;
+    })
+  | (P & {
+      children?: ReactNode;
+      $status: "done";
+      $action?: Action;
+      $dispatch?: GenerativeUIDispatch;
+    });
 
 /** Props for a component that only renders once complete — `$status` is always `"done"`. */
-type StaticRenderProps<P> = P & { children?: ReactNode; $status: "done" };
+type StaticRenderProps<P> = P & {
+  children?: ReactNode;
+  $status: "done";
+  $action?: Action;
+  $dispatch?: GenerativeUIDispatch;
+};
 
 /**
  * A component the model is allowed to render, with the schema for its props.
@@ -67,38 +117,3 @@ export type GenerativeUIComponent<P = any> =
  * This registry is the security boundary — any `type` not present is rejected.
  */
 export type GenerativeUILibrary = Record<string, GenerativeUIComponent>;
-
-/**
- * A component invocation — mirrors React's `ReactElement`.
- *
- * `type` selects a component from the {@link GenerativeUILibrary}; `props` are
- * passed to it. The `children` prop is special: it is itself a renderable
- * {@link GenerativeUINode}, drawn as generative UI rather than passed as data.
- *
- * On the wire the model emits the flattened form `{ $type, ...props }`, where
- * `$type` names the component so a real `type` prop never collides. This is the
- * normalized shape the renderer works with, the same way React normalizes
- * `createElement` arguments into an element.
- */
-export type GenerativeUIElement = {
-  type: string;
-  props: GenerativeUIProps;
-};
-
-/** Props passed to a component — mirrors a React component's props. */
-export type GenerativeUIProps = {
-  children?: GenerativeUINode;
-} & Record<string, unknown>;
-
-/**
- * Anything renderable as generative UI — mirrors React's `ReactNode`: an
- * element, primitive text, or a list of nodes.
- */
-export type GenerativeUINode =
-  | GenerativeUIElement
-  | string
-  | number
-  | boolean
-  | null
-  | undefined
-  | GenerativeUINode[];

package/src/vocabulary/alert.test.tsx

@@ -0,0 +1,136 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { renderGenerativeUI } from "../renderGenerativeUI";
+import { alertVocabulary } from "./alert";
+import { defaultGenerativeUILibrary } from "./index";
+
+const render = (node: unknown) =>
+  renderToStaticMarkup(<>{renderGenerativeUI(node, alertVocabulary)}</>);
+
+describe("alertVocabulary", () => {
+  it("Alert renders with title/description/tone, defaulting tone to info", () => {
+    expect(
+      render({
+        $type: "Alert",
+        title: "Heads up",
+        description: "Something happened",
+      }),
+    ).toBe(
+      '<div data-aui="alert" data-aui-tone="info" role="alert"><header data-aui="alert-title">Heads up</header><p data-aui="alert-desc">Something happened</p></div>',
+    );
+  });
+
+  it("Alert renders an explicit tone", () => {
+    expect(
+      render({ $type: "Alert", tone: "danger", title: "Error" }),
+    ).toContain('data-aui-tone="danger"');
+  });
+
+  it("Carousel wraps each child Card in a slide, capped at 10", () => {
+    const children = Array.from({ length: 12 }, (_, i) => ({
+      $type: "Card",
+      title: `c${i}`,
+    }));
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          { $type: "Carousel", children },
+          defaultGenerativeUILibrary,
+        )}
+      </>,
+    );
+    const slideCount = (html.match(/data-aui="carousel-slide"/g) ?? []).length;
+    expect(slideCount).toBe(10);
+  });
+
+  it("Carousel renders a single non-array child Card in one slide", () => {
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          {
+            $type: "Carousel",
+            children: { $type: "Card", title: "only" } as never,
+          },
+          defaultGenerativeUILibrary,
+        )}
+      </>,
+    );
+    expect((html.match(/data-aui="carousel-slide"/g) ?? []).length).toBe(1);
+  });
+
+  it("Carousel without a label renders role=group, no aria-label, and no double-name landmark", () => {
+    expect(render({ $type: "Carousel" })).toBe(
+      '<div data-aui="carousel" role="group" aria-roledescription="carousel" tabindex="0"></div>',
+    );
+  });
+
+  it("Carousel with a label renders role=region and the given aria-label", () => {
+    expect(render({ $type: "Carousel", label: "Featured" })).toBe(
+      '<div data-aui="carousel" role="region" aria-roledescription="carousel" aria-label="Featured" tabindex="0"></div>',
+    );
+  });
+
+  it("Carousel container carries region semantics and an optional label", () => {
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          {
+            $type: "Carousel",
+            label: "Featured items",
+            children: [
+              { $type: "Card", title: "a" },
+              { $type: "Card", title: "b" },
+            ],
+          },
+          defaultGenerativeUILibrary,
+        )}
+      </>,
+    );
+    expect(html).toContain('role="region"');
+    expect(html).toContain('aria-roledescription="carousel"');
+    expect(html).toContain('aria-label="Featured items"');
+    expect(html).toContain('tabindex="0"');
+  });
+
+  it("Carousel slides carry group semantics and a positional label", () => {
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          {
+            $type: "Carousel",
+            label: "Featured items",
+            children: [
+              { $type: "Card", title: "a" },
+              { $type: "Card", title: "b" },
+              { $type: "Card", title: "c" },
+            ],
+          },
+          defaultGenerativeUILibrary,
+        )}
+      </>,
+    );
+    expect((html.match(/role="group"/g) ?? []).length).toBe(3);
+    expect((html.match(/aria-roledescription="slide"/g) ?? []).length).toBe(3);
+    expect(html).toContain('aria-label="1 of 3"');
+    expect(html).toContain('aria-label="2 of 3"');
+    expect(html).toContain('aria-label="3 of 3"');
+  });
+
+  it("Carousel slide labels reflect the 10-slide cap, not the raw child count", () => {
+    const children = Array.from({ length: 12 }, (_, i) => ({
+      $type: "Card",
+      title: `c${i}`,
+    }));
+    const html = renderToStaticMarkup(
+      <>
+        {renderGenerativeUI(
+          { $type: "Carousel", children },
+          defaultGenerativeUILibrary,
+        )}
+      </>,
+    );
+    expect(html).toContain('aria-label="1 of 10"');
+    expect(html).toContain('aria-label="10 of 10"');
+    expect(html).not.toContain("11 of 10");
+  });
+});