@assistant-ui/react-generative-ui 0.0.7 → 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/vocabulary/alert.test.tsx

@@ -58,9 +58,79 @@ describe("alertVocabulary", () => {
     expect((html.match(/data-aui="carousel-slide"/g) ?? []).length).toBe(1);
   });
 
-  it("Carousel with no children renders an empty container", () => {
+  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"></div>',
+      '<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");
+  });
 });

package/src/vocabulary/alert.tsx

@@ -29,14 +29,33 @@ export const alertVocabulary = {
     ),
   },
   Carousel: {
-    description: "A horizontally scrollable group of `Card` children (max 10).",
-    properties: z.object({}),
-    render: ({ children }) => {
+    description:
+      "A horizontally scrollable group of `Card` children (max 10). Set `label` for an accessible name.",
+    properties: z.object({
+      label: z
+        .string()
+        .optional()
+        .describe("Accessible label for the carousel."),
+    }),
+    render: ({ label, children }) => {
       const cards = Children.toArray(children).slice(0, MAX_CARDS);
+      const n = cards.length;
       return (
-        <div data-aui="carousel">
+        <div
+          data-aui="carousel"
+          role={label ? "region" : "group"}
+          aria-roledescription="carousel"
+          aria-label={label}
+          tabIndex={0}
+        >
           {cards.map((card, i) => (
-            <div key={i} data-aui="carousel-slide">
+            <div
+              key={i}
+              data-aui="carousel-slide"
+              role="group"
+              aria-roledescription="slide"
+              aria-label={`${i + 1} of ${n}`}
+            >
               {card}
             </div>
           ))}

package/src/vocabulary/collectFormValues.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from "vitest";
+import {
+  collectFormValues,
+  type FormControlElementLike,
+} from "./collectFormValues";
+
+const el = (
+  partial: Partial<FormControlElementLike>,
+): FormControlElementLike => ({
+  name: "",
+  type: "text",
+  value: "",
+  disabled: false,
+  ...partial,
+});
+
+describe("collectFormValues", () => {
+  it("resolves a checkbox to its checked boolean", () => {
+    expect(
+      collectFormValues([
+        el({ name: "agree", type: "checkbox", checked: true }),
+      ]),
+    ).toEqual({ agree: true });
+    expect(
+      collectFormValues([
+        el({ name: "agree", type: "checkbox", checked: false }),
+      ]),
+    ).toEqual({ agree: false });
+  });
+
+  it("resolves a radio set to the checked option's value", () => {
+    expect(
+      collectFormValues([
+        el({ name: "size", type: "radio", value: "sm", checked: false }),
+        el({ name: "size", type: "radio", value: "md", checked: true }),
+        el({ name: "size", type: "radio", value: "lg", checked: false }),
+      ]),
+    ).toEqual({ size: "md" });
+  });
+
+  it("resolves a radio set with no checked option to undefined", () => {
+    const values = collectFormValues([
+      el({ name: "size", type: "radio", value: "sm", checked: false }),
+      el({ name: "size", type: "radio", value: "md", checked: false }),
+    ]);
+    expect("size" in values).toBe(true);
+    expect(values.size).toBeUndefined();
+  });
+
+  it("resolves select/input/textarea/date controls to their string value", () => {
+    expect(
+      collectFormValues([
+        el({ name: "role", type: "select-one", value: "admin" }),
+        el({ name: "email", type: "email", value: "a@example.com" }),
+        el({ name: "bio", type: "textarea", value: "hi" }),
+        el({ name: "dob", type: "date", value: "2026-01-01" }),
+      ]),
+    ).toEqual({
+      role: "admin",
+      email: "a@example.com",
+      bio: "hi",
+      dob: "2026-01-01",
+    });
+  });
+
+  it("collects repeated non-radio names into an array in document order", () => {
+    expect(
+      collectFormValues([
+        el({ name: "tag", type: "text", value: "a" }),
+        el({ name: "tag", type: "text", value: "b" }),
+        el({ name: "tag", type: "text", value: "c" }),
+      ]),
+    ).toEqual({ tag: ["a", "b", "c"] });
+  });
+
+  it("skips controls without a name", () => {
+    expect(
+      collectFormValues([
+        el({ name: "", type: "text", value: "unnamed" }),
+        el({ name: "kept", type: "text", value: "yes" }),
+      ]),
+    ).toEqual({ kept: "yes" });
+  });
+
+  it("skips disabled controls", () => {
+    expect(
+      collectFormValues([
+        el({ name: "off", type: "text", value: "nope", disabled: true }),
+        el({ name: "on", type: "text", value: "yep" }),
+      ]),
+    ).toEqual({ on: "yep" });
+  });
+
+  it("skips a disabled control inside an otherwise-checked radio set", () => {
+    expect(
+      collectFormValues([
+        el({
+          name: "size",
+          type: "radio",
+          value: "sm",
+          checked: true,
+          disabled: true,
+        }),
+        el({ name: "size", type: "radio", value: "md", checked: false }),
+      ]),
+    ).toEqual({ size: undefined });
+  });
+
+  it("returns an empty object for no elements", () => {
+    expect(collectFormValues([])).toEqual({});
+  });
+
+  it("a field named __proto__ round-trips as an own data key", () => {
+    const values = collectFormValues([
+      el({ name: "__proto__", type: "text", value: "x" }),
+    ]);
+    expect(Object.hasOwn(values, "__proto__")).toBe(true);
+    expect(values["__proto__"]).toBe("x");
+  });
+
+  it("a field named constructor collects as its submitted string, not an array seeded with the inherited function", () => {
+    const values = collectFormValues([
+      el({ name: "constructor", type: "text", value: "hi" }),
+    ]);
+    expect(values["constructor"]).toBe("hi");
+  });
+});