@assistant-ui/react-generative-ui 0.0.13 → 0.0.14

package/src/teams/toAdaptiveCard.ts

@@ -108,14 +108,14 @@ function reservedSafeId(
   if (reserved) {
     warn(
       context,
-      "clamped",
+      "fallback",
       component,
       `the input id "${RESERVED_INPUT_ID}" collides with the submit envelope's reserved key and was renamed to "${candidate}".`,
     );
   } else if (candidate !== base) {
     warn(
       context,
-      "clamped",
+      "fallback",
       component,
       `the input id "${base}" was already used on this card and was renamed to "${candidate}".`,
     );
@@ -191,6 +191,15 @@ const choicesFrom = (
     const choice = toChoice(item);
     if (choice !== undefined) choices.push(choice);
   }
+  const dropped = items.length - choices.length;
+  if (dropped > 0) {
+    warn(
+      context,
+      "dropped",
+      component,
+      `${dropped} ${dropped === 1 ? "option was" : "options were"} dropped for want of a string value.`,
+    );
+  }
   return choices;
 };
 
@@ -211,7 +220,7 @@ function convertButtons(
   if (buttons.length > PRIMARY_ACTION_CAP) {
     warn(
       context,
-      "clamped",
+      "fallback",
       "Button",
       `actions beyond ${PRIMARY_ACTION_CAP} were set to secondary mode.`,
     );
@@ -302,6 +311,17 @@ function convertTable(
     );
   }
 
+  const unlabeled = rawColumns.filter(
+    (column) => !isRecord(column) || typeof column["label"] !== "string",
+  ).length;
+  if (unlabeled > 0) {
+    warn(
+      context,
+      "dropped",
+      "Table",
+      `${unlabeled} column ${unlabeled === 1 ? "header was" : "headers were"} left blank for want of a string label.`,
+    );
+  }
   const hasColumns = rawColumns.length > 0;
   const columns: TeamsTableColumnDefinition[] = rawColumns.map(() => ({
     width: 1 as const,
@@ -349,6 +369,29 @@ function convertListViewItem(
   };
 }
 
+/**
+ * Converts a child whose output is thrown away, and reports whether anything
+ * was lost with it. A scratch context keeps the ids it claims out of the card,
+ * where they would rename a control that survives; only its `dropped` warnings
+ * are forwarded, because those describe the tree the caller wrote, while a
+ * clamp or a rename would describe content never delivered.
+ */
+export const discardedChild = (
+  child: NormalizedUINode,
+  context: ConversionContext,
+  depth: number,
+): boolean => {
+  const scratch: ConversionContext = {
+    ...context,
+    warnings: [],
+    usedInputIds: new Set(context.usedInputIds),
+  };
+  const produced = convertSequence(child, scratch, depth).length > 0;
+  const lost = scratch.warnings.filter((warning) => warning.code === "dropped");
+  context.warnings.push(...lost);
+  return produced || lost.length > 0;
+};
+
 export function convertElement(
   element: NormalizedUIElement,
   context: ConversionContext,
@@ -539,7 +582,7 @@ export function convertElement(
     case "Row": {
       const children = normalizedList(element.children);
       if (children.length > 3) {
-        warn(context, "clamped", "Row", "Teams recommends at most 3 columns.");
+        warn(context, "advisory", "Row", "Teams recommends at most 3 columns.");
       }
       const columns: TeamsColumn[] = children.map((child) => ({
         type: "Column",
@@ -550,13 +593,21 @@ export function convertElement(
     }
     case "ListView": {
       const containers: TeamsContainer[] = [];
+      let discarded = 0;
       for (const child of normalizedList(element.children)) {
-        if (!isElement(child)) continue;
-        if (child.type === "ListViewItem") {
+        if (isElement(child) && child.type === "ListViewItem") {
           containers.push(convertListViewItem(child, context, depth + 1));
-        } else {
-          convertElement(child, context, depth + 1);
+          continue;
         }
+        if (discardedChild(child, context, depth + 1)) discarded += 1;
+      }
+      if (discarded > 0) {
+        warn(
+          context,
+          "dropped",
+          "ListView",
+          `${discarded} non-item ${discarded === 1 ? "child was" : "children were"} dropped.`,
+        );
       }
       return containers.map((container, index) =>
         index > 0 ? { ...container, separator: true } : container,
@@ -586,10 +637,23 @@ export function convertElement(
         "Carousel",
         "A carousel was rendered as sequential cards because it is not at the root.",
       );
-      const cards = normalizedList(element.children).filter(
-        (child): child is NormalizedUIElement =>
-          isElement(child) && child.type === "Card",
-      );
+      const cards: NormalizedUIElement[] = [];
+      let droppedCards = 0;
+      for (const child of normalizedList(element.children)) {
+        if (isElement(child) && child.type === "Card") {
+          cards.push(child);
+          continue;
+        }
+        if (discardedChild(child, context, depth + 1)) droppedCards += 1;
+      }
+      if (droppedCards > 0) {
+        warn(
+          context,
+          "dropped",
+          "Carousel",
+          `${droppedCards} non-card ${droppedCards === 1 ? "child was" : "children were"} dropped.`,
+        );
+      }
       return cards.flatMap((card) => convertElement(card, context, depth + 1));
     }
     case "Chart":
@@ -716,9 +780,9 @@ export function convertRootToCard(
   if (size > PAYLOAD_SOFT_CAP) {
     warn(
       context,
-      "clamped",
+      "advisory",
       "Root",
-      `the card is ${size} bytes, exceeding Teams' 100 KB bot message limit.`,
+      `the card is ${size} bytes, over the ${PAYLOAD_SOFT_CAP}-byte soft budget kept below Teams' 100 KB bot message limit.`,
     );
   }
   return card;
@@ -726,7 +790,7 @@ export function convertRootToCard(
 
 /**
  * Converts a generative-ui tree into a Microsoft Teams Adaptive Card and
- * non-fatal downgrade warnings. Sizes, weights, and colors map to Adaptive
+ * non-fatal conversion warnings. Sizes, weights, and colors map to Adaptive
  * Card's semantic enums rather than raw values. An Input/Select/RadioGroup/
  * Checkbox/DatePicker whose id would be the reserved {@link RESERVED_INPUT_ID}
  * is renamed with a warning (see `decodeSubmitData`). Never throws: an

package/src/teams/toTeamsAttachments.test.ts

@@ -19,11 +19,56 @@ describe("toTeamsAttachments payload budget", () => {
     }
     expect(
       warnings.some(
-        (warning) => warning.code === "clamped" && warning.component === "Root",
+        (warning) =>
+          warning.code === "advisory" && warning.component === "Root",
       ),
     ).toBe(false);
     expect(warnings).toContainEqual(
-      expect.objectContaining({ code: "clamped", component: "Carousel" }),
+      expect.objectContaining({
+        code: "advisory",
+        component: "Carousel",
+        detail: expect.stringContaining(
+          `over the ${PAYLOAD_SOFT_CAP}-byte soft budget`,
+        ),
+      }),
     );
   });
 });
+
+describe("toTeamsAttachments root carousel children", () => {
+  it("reports a renderable non-card child instead of dropping it silently", () => {
+    const { attachments, warnings } = toTeamsAttachments({
+      $type: "Carousel",
+      children: [
+        { $type: "Text", value: "lost" },
+        { $type: "Card", title: "kept" },
+      ],
+    });
+    expect(attachments).toHaveLength(1);
+    expect(warnings).toContainEqual({
+      code: "dropped",
+      component: "Carousel",
+      detail: "1 non-card child was dropped.",
+    });
+  });
+
+  it("forwards a discarded child's own dropped warning", () => {
+    const { warnings } = toTeamsAttachments({
+      $type: "Carousel",
+      children: [{ $type: "Mystery" }, { $type: "Card", title: "kept" }],
+    });
+    expect(warnings).toContainEqual({
+      code: "dropped",
+      component: "Mystery",
+      detail: "Unknown component type was dropped.",
+    });
+  });
+
+  it("stays silent for a child that renders nothing anyway", () => {
+    const { warnings } = toTeamsAttachments({
+      $type: "Carousel",
+      children: [{ $type: "Spacer" }, { $type: "Card", title: "kept" }],
+    });
+    expect(warnings).toEqual([]);
+  });
+});

package/src/teams/toTeamsAttachments.ts

@@ -12,8 +12,8 @@ import {
   utf8ByteLength,
 } from "./constants";
 import {
-  convertElement,
   convertRootToCard,
+  discardedChild,
   type ConversionContext,
 } from "./toAdaptiveCard";
 import type {
@@ -47,10 +47,9 @@ const clampArray = <T>(
 
 /**
  * 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
+ * children. A non-card child is routed through {@link discardedChild}, which
+ * reports it and forwards whatever it lost, rather than being filtered out
+ * silently. `undefined` means the root is not exclusively a
  * root-level carousel, so the caller falls back to converting the whole tree
  * as one card.
  */
@@ -61,13 +60,20 @@ function rootCarouselCards(
   const element = Array.isArray(root) && root.length === 1 ? root[0] : root;
   if (!isElement(element) || element.type !== "Carousel") return undefined;
   const cards: NormalizedUIElement[] = [];
+  let discarded = 0;
   for (const child of normalizedList(element.children)) {
-    if (!isElement(child)) continue;
-    if (child.type === "Card") {
+    if (isElement(child) && child.type === "Card") {
       cards.push(child);
-    } else {
-      convertElement(child, context, 1);
+      continue;
     }
+    if (discardedChild(child, context, 1)) discarded += 1;
+  }
+  if (discarded > 0) {
+    context.warnings.push({
+      code: "dropped",
+      component: "Carousel",
+      detail: `${discarded} non-card ${discarded === 1 ? "child was" : "children were"} dropped.`,
+    });
   }
   return cards;
 }
@@ -113,9 +119,9 @@ export function toTeamsAttachments(
       const size = utf8ByteLength(JSON.stringify(attachments));
       if (size > PAYLOAD_SOFT_CAP) {
         warnings.push({
-          code: "clamped",
+          code: "advisory",
           component: "Carousel",
-          detail: `the carousel attachments total ${size} bytes, exceeding Teams' 100 KB bot message limit.`,
+          detail: `the carousel attachments total ${size} bytes, over the ${PAYLOAD_SOFT_CAP}-byte soft budget kept below Teams' 100 KB bot message limit.`,
         });
       }
       return { attachments, attachmentLayout: "carousel", warnings };

package/src/teams/types.ts

@@ -213,9 +213,18 @@ export interface TeamsCardAttachment {
   readonly content: TeamsAdaptiveCard;
 }
 
-/** A non-fatal downgrade reported during Teams conversion. */
+/**
+ * A non-fatal note reported during Teams conversion.
+ *
+ * `clamped` removed content to fit a limit, `dropped` discarded a node or one
+ * of its props and may leave a placeholder note behind, and `fallback`
+ * emitted the node in a different form than requested. `advisory` changed
+ * nothing at all and notes content Teams may still render poorly or refuse,
+ * such as a payload over the byte budget or a `Row` past the recommended
+ * column count.
+ */
 export interface TeamsConversionWarning {
-  readonly code: "clamped" | "dropped" | "fallback";
+  readonly code: "clamped" | "dropped" | "fallback" | "advisory";
   readonly component: string;
   readonly detail: string;
 }

package/src/vocabulary/layout.test.tsx

@@ -38,7 +38,22 @@ describe("layoutVocabulary", () => {
         background: "var(--muted)",
       }),
     ).toBe(
-      '<section data-aui="card" data-aui-padding="2" data-aui-background="var(--muted)" style="background:var(--muted);color:white"><header data-aui="card-title">T</header></section>',
+      '<section data-aui="card" data-aui-padding="2" data-aui-background="var(--muted)" data-aui-surface="" style="background:var(--muted);color:white"><header data-aui="card-title">T</header></section>',
+    );
+  });
+
+  it("Card flags itself as a surface only when a background or a footer makes it one", () => {
+    expect(render({ $type: "Card", title: "Plain" })).not.toContain(
+      "data-aui-surface",
+    );
+    expect(render({ $type: "Card", background: "var(--muted)" })).toContain(
+      "data-aui-surface",
+    );
+    expect(render({ $type: "Card", confirm: { label: "Yes" } })).toContain(
+      "data-aui-surface",
+    );
+    expect(render({ $type: "Card", cancel: { label: "No" } })).toContain(
+      "data-aui-surface",
     );
   });
 

package/src/vocabulary/layout.tsx

@@ -24,7 +24,7 @@ const cardFooterButtonSchema = z.object({
 export const layoutVocabulary = {
   Card: {
     description:
-      "A bordered container grouping related content. Optionally titled. Set `asForm` to collect named child control values on submit, and `confirm`/`cancel` to add a footer with action buttons.",
+      "A titled section of related content, the default way to break a response into parts. It renders as plain content, so several in a row read as one answer rather than a stack of boxes; it takes on a framed surface only when `background` is set, when `confirm`/`cancel` add a footer, or when it is a slot in a `Carousel`. Set `asForm` to collect named child control values on submit.",
     properties: z.object({
       title: z.string().optional().describe("Optional card title."),
       padding: z
@@ -96,6 +96,9 @@ export const layoutVocabulary = {
           data-aui="card"
           data-aui-padding={padding}
           data-aui-background={background}
+          data-aui-surface={
+            background !== undefined || footer !== null ? "" : undefined
+          }
           style={
             background !== undefined
               ? { background, color: "white" }