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

package/src/slack/toSlackBlocks.ts

@@ -26,6 +26,7 @@ import {
   INPUT_LABEL_CAP,
   INTERACTIVE_TEXT_CAP,
   MARKDOWN_TEXT_BUDGET,
+  MAX_ELEMENT_DEPTH,
   MAX_TRAVERSAL_DEPTH,
   MESSAGE_BLOCK_CAP,
   MODAL_BLOCK_CAP,
@@ -73,6 +74,14 @@ const INTERACTIVE_TYPES = new Set([
   "RadioGroup",
 ]);
 
+/**
+ * Types whose control disappears when a card is reshaped to text. `Input` and
+ * `Form` are not in {@link INTERACTIVE_TYPES} because they emit their own
+ * block rather than an actions element, but a reshape loses them the same way,
+ * and a `Form` gets a Submit button whether or not it carries an action.
+ */
+const CONTROL_TYPES = new Set([...INTERACTIVE_TYPES, "Input", "Form"]);
+
 const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -201,6 +210,22 @@ const optionFrom = (
   };
 };
 
+const warnDroppedOptions = (
+  kept: number,
+  taken: number,
+  component: string,
+  context: ConversionContext,
+) => {
+  const dropped = taken - kept;
+  if (dropped === 0) return;
+  warn(
+    context,
+    "dropped",
+    component,
+    `${dropped} ${dropped === 1 ? "option was" : "options were"} dropped for want of a string label and value.`,
+  );
+};
+
 const toActionElement = (
   element: NormalizedUIElement,
   context: ConversionContext,
@@ -227,10 +252,16 @@ const toActionElement = (
           `options were clamped to ${SELECT_OPTION_CAP} entries.`,
         );
       }
-      const options = rawOptions
-        .slice(0, SELECT_OPTION_CAP)
+      const takenOptions = rawOptions.slice(0, SELECT_OPTION_CAP);
+      const options = takenOptions
         .map((option) => optionFrom(option, "Select", context))
         .filter((option): option is SlackOption => option !== undefined);
+      warnDroppedOptions(
+        options.length,
+        takenOptions.length,
+        "Select",
+        context,
+      );
       const placeholder = clampText(
         asString(props["placeholder"]),
         PLACEHOLDER_TEXT_CAP,
@@ -296,10 +327,16 @@ const toActionElement = (
           `options were clamped to ${RADIO_OPTION_CAP} entries.`,
         );
       }
-      const options = rawOptions
-        .slice(0, RADIO_OPTION_CAP)
+      const takenOptions = rawOptions.slice(0, RADIO_OPTION_CAP);
+      const options = takenOptions
         .map((option) => optionFrom(option, "RadioGroup", context))
         .filter((option): option is SlackOption => option !== undefined);
+      warnDroppedOptions(
+        options.length,
+        takenOptions.length,
+        "RadioGroup",
+        context,
+      );
       const selectedValue =
         typeof props["value"] === "string"
           ? props["value"]
@@ -582,10 +619,54 @@ const convertCard = (
   return [card];
 };
 
+/** The content kinds a reshaped carousel card cannot carry, in report order. */
+const LOST_CONTENT_KINDS = ["images", "tables", "charts", "controls"] as const;
+
+const listPhrase = (items: readonly string[]): string =>
+  items.length <= 1
+    ? (items[0] ?? "")
+    : `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+
+/**
+ * Collects the kinds of content a reshape drops, walking the same tree
+ * {@link collectText} does so a node nested below the top level counts too.
+ * These are exactly the pieces text cannot represent: an image has no text, a
+ * table and a chart carry theirs in array props, and a control is behavior,
+ * whether or not it carries an action of its own. An `$action` counts only on
+ * a node that renders a control from it, since a `Box` or a `Row` carrying one
+ * renders no control on the clean path either.
+ */
+const scanLostContent = (
+  node: NormalizedUINode | undefined,
+  into: Set<string>,
+  depth: number,
+): void => {
+  if (depth > MAX_TRAVERSAL_DEPTH) return;
+  if (Array.isArray(node)) {
+    for (const child of node) scanLostContent(child, into, depth + 1);
+    return;
+  }
+  if (node === undefined || !isElement(node)) return;
+  if (
+    CONTROL_TYPES.has(node.type) ||
+    (node.type === "ListViewItem" && isRecord(node.action)) ||
+    (node.type === "Card" &&
+      (isRecord(node.props["confirm"]) || isRecord(node.props["cancel"])))
+  ) {
+    into.add("controls");
+  }
+  if (node.type === "Image") into.add("images");
+  if (node.type === "Table") into.add("tables");
+  if (node.type === "Chart") into.add("charts");
+  scanLostContent(node.children, into, depth + 1);
+};
+
 /**
  * Degrades a card that cannot map cleanly into a title-and-body card block.
- * A carousel cannot fall back to a block sequence like a standalone card
- * can, so its content is clamped down to fit the card shape instead.
+ * A carousel cannot fall back to a block sequence like a standalone card can,
+ * so the card is reshaped to the two text fields the block has. Text reachable
+ * by {@link collectText} survives at any depth; an image, a table, a chart,
+ * and a control do not, and are reported separately from the reshape itself.
  */
 const degradeCard = (
   element: NormalizedUIElement,
@@ -596,14 +677,40 @@ const degradeCard = (
   const textChunks = collectText(element.children, depth + 1);
   const titleSource = rawTitle || textChunks[0] || "";
   const bodyChunks = rawTitle ? textChunks : textChunks.slice(1);
-  const titleText = titleSource.slice(0, CARD_TITLE_CAP);
-  const bodyText = bodyChunks.join("\n").slice(0, CARD_BODY_CAP);
+  const titleText = clampText(
+    titleSource,
+    CARD_TITLE_CAP,
+    "Card",
+    "title",
+    context,
+  );
+  const bodyText = clampText(
+    bodyChunks.join("\n"),
+    CARD_BODY_CAP,
+    "Card",
+    "body",
+    context,
+  );
   warn(
     context,
-    "clamped",
+    "fallback",
     "Card",
-    "A card inside a carousel was degraded to title and body.",
+    "A card inside a carousel was reshaped to title and body.",
   );
+  const lostKinds = new Set<string>();
+  if (isRecord(element.props["confirm"]) || isRecord(element.props["cancel"])) {
+    lostKinds.add("controls");
+  }
+  scanLostContent(element.children, lostKinds, depth + 1);
+  const lost = LOST_CONTENT_KINDS.filter((kind) => lostKinds.has(kind));
+  if (lost.length > 0) {
+    warn(
+      context,
+      "dropped",
+      "Card",
+      `A reshaped carousel card's ${listPhrase(lost)} were dropped.`,
+    );
+  }
   return buildCardBlock({
     ...(titleText ? { title: { type: "mrkdwn", text: titleText } } : {}),
     ...(bodyText ? { body: { type: "mrkdwn", text: bodyText } } : {}),
@@ -698,15 +805,47 @@ const convertListItem = (
   };
 };
 
+/**
+ * Converts a child whose output is thrown away, and reports whether anything
+ * was lost with it. A scratch context keeps the throwaway out of the shared
+ * markdown and data-table budgets that surviving blocks still need; only its
+ * `dropped` warnings are forwarded, because those describe the tree the caller
+ * wrote, while a clamp or a fallback would describe content never delivered.
+ */
+const discardedChild = (
+  child: NormalizedUINode,
+  context: ConversionContext,
+  depth: number,
+): boolean => {
+  const scratch: ConversionContext = { ...context, warnings: [] };
+  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;
+};
+
 const convertListView = (
   element: NormalizedUIElement,
   context: ConversionContext,
   depth: number,
 ): SlackBlock[] => {
-  const items = normalizedList(element.children).filter(
-    (child): child is NormalizedUIElement =>
-      isElement(child) && child.type === "ListViewItem",
-  );
+  const items: NormalizedUIElement[] = [];
+  let discarded = 0;
+  for (const child of normalizedList(element.children)) {
+    if (isElement(child) && child.type === "ListViewItem") {
+      items.push(child);
+      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 items.flatMap((item, index) => [
     ...(index > 0 ? [{ type: "divider" as const }] : []),
     convertListItem(item, context, depth + 1),
@@ -719,12 +858,21 @@ const convertCarousel = (
   depth: number,
 ): SlackBlock[] => {
   const cardChildren: NormalizedUIElement[] = [];
+  let droppedCards = 0;
   for (const child of normalizedList(element.children)) {
     if (isElement(child) && child.type === "Card") {
       cardChildren.push(child);
-    } else {
-      warn(context, "dropped", "Carousel", "A non-card child was dropped.");
+      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.`,
+    );
   }
   if (cardChildren.length > CAROUSEL_CARD_CAP) {
     warn(
@@ -790,13 +938,22 @@ const convertTable = (
     );
   }
 
-  const columnHeaderRow: SlackDataTableCell[] = rawColumns
-    .slice(0, DATA_TABLE_COLUMN_CAP)
-    .filter(isRecord)
-    .map((column) => ({
-      type: "raw_text" as const,
-      text: asString(column["label"]),
-    }));
+  const takenColumns = rawColumns.slice(0, DATA_TABLE_COLUMN_CAP);
+  const unlabeled = takenColumns.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 columnHeaderRow: SlackDataTableCell[] = takenColumns.map((column) => ({
+    type: "raw_text" as const,
+    text: isRecord(column) ? asString(column["label"]) : "",
+  }));
   const dataRows: SlackDataTableCell[][] = rawRows
     .slice(0, DATA_TABLE_ROW_CAP)
     .map((row) =>
@@ -1283,7 +1440,7 @@ export function toSlackBlocks(
           : reason === "cycle"
             ? "a self-referencing node was dropped."
             : reason === "depth"
-              ? `nodes deeper than ${MAX_TRAVERSAL_DEPTH} levels were dropped.`
+              ? `nodes deeper than ${MAX_ELEMENT_DEPTH} levels were dropped.`
               : `children were clamped to ${CHILDREN_CAP} entries.`;
       warn(context, "clamped", "Root", detail);
     });

package/src/slack/types.ts

@@ -210,7 +210,13 @@ export interface ToSlackBlocksOptions {
   readonly surface?: "message" | "modal";
 }
 
-/** A non-fatal downgrade reported during Slack conversion. */
+/**
+ * A non-fatal note reported during Slack 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.
+ */
 export interface SlackConversionWarning {
   readonly code: "clamped" | "dropped" | "fallback";
   readonly component: string;

package/src/teams/constants.ts

@@ -17,9 +17,17 @@ export const ADAPTIVE_CARD_SCHEMA =
 export const ATTACHMENT_CONTENT_TYPE =
   "application/vnd.microsoft.card.adaptive";
 
-/** The maximum normalized traversal depth. */
+/** The maximum traversal depth, counted in visited values, not tree levels. */
 export const MAX_TRAVERSAL_DEPTH = 64;
 
+/**
+ * The element-nesting ceiling a caller observes. `boundNode` visits an element
+ * and its `children` array separately, so one level of nesting spends two of
+ * {@link MAX_TRAVERSAL_DEPTH}; it runs before the conversion walk and is never
+ * the looser of the two. A root array costs one more level than a root object.
+ */
+export const MAX_ELEMENT_DEPTH = MAX_TRAVERSAL_DEPTH / 2;
+
 /**
  * The maximum number of entries kept at any single level (root, or a
  * `children` array at any depth) of the raw spec, before it ever reaches
@@ -46,7 +54,7 @@ export function clampReasonDetail(reason: ClampReason): string {
   }
   if (reason === "cycle") return "a self-referencing node was dropped.";
   if (reason === "depth") {
-    return `nodes deeper than ${MAX_TRAVERSAL_DEPTH} levels were dropped.`;
+    return `nodes deeper than ${MAX_ELEMENT_DEPTH} levels were dropped.`;
   }
   return `children were clamped to ${CHILDREN_CAP} entries.`;
 }

package/src/teams/toAdaptiveCard.test.ts

@@ -368,7 +368,7 @@ describe("toAdaptiveCard", () => {
         expect(action.mode).toBe("secondary");
       }
       expect(warnings).toContainEqual(
-        expect.objectContaining({ code: "clamped", component: "Button" }),
+        expect.objectContaining({ code: "fallback", component: "Button" }),
       );
     });
   });
@@ -418,7 +418,7 @@ describe("toAdaptiveCard", () => {
         expect(action.mode).toBe("secondary");
       }
       expect(warnings).toContainEqual(
-        expect.objectContaining({ code: "clamped", component: "Button" }),
+        expect.objectContaining({ code: "fallback", component: "Button" }),
       );
     });
   });
@@ -623,7 +623,7 @@ describe("toAdaptiveCard", () => {
         const element = card.body[0] as { id: string };
         expect(element.id).toBe("aui_");
         expect(warnings).toContainEqual(
-          expect.objectContaining({ code: "clamped", component: type }),
+          expect.objectContaining({ code: "fallback", component: type }),
         );
       },
     );
@@ -647,7 +647,7 @@ describe("toAdaptiveCard", () => {
       const ids = (card.body as TeamsInputText[]).map((element) => element.id);
       expect(ids).toEqual(["input", "input_2"]);
       expect(warnings).toContainEqual(
-        expect.objectContaining({ code: "clamped", component: "Input" }),
+        expect.objectContaining({ code: "fallback", component: "Input" }),
       );
     });
 
@@ -659,7 +659,9 @@ describe("toAdaptiveCard", () => {
       ]);
       const ids = (card.body as TeamsInputText[]).map((element) => element.id);
       expect(new Set(ids).size).toBe(3);
-      expect(warnings.some((warning) => warning.code === "clamped")).toBe(true);
+      expect(warnings.some((warning) => warning.code === "fallback")).toBe(
+        true,
+      );
     });
 
     it("names the actually-emitted id in the reserved-key warning, and fires only that one warning, when the rename target also collides", () => {
@@ -671,7 +673,7 @@ describe("toAdaptiveCard", () => {
       expect(ids).toEqual(["aui_", "aui__2"]);
       expect(warnings).toEqual([
         {
-          code: "clamped",
+          code: "fallback",
           component: "Input",
           detail:
             'the input id "aui" collides with the submit envelope\'s reserved key and was renamed to "aui__2".',
@@ -801,7 +803,7 @@ describe("toAdaptiveCard", () => {
       const columnSet = card.body[0] as TeamsColumnSet;
       expect(columnSet.columns).toHaveLength(4);
       expect(warnings).toContainEqual(
-        expect.objectContaining({ code: "clamped", component: "Row" }),
+        expect.objectContaining({ code: "advisory", component: "Row" }),
       );
     });
   });
@@ -863,9 +865,177 @@ describe("toAdaptiveCard", () => {
         detail: "Unknown component type was dropped.",
       });
     });
+
+    it("keeps a discarded child's clamp warning out of the result", () => {
+      const { warnings } = toAdaptiveCard({
+        $type: "ListView",
+        children: [
+          {
+            $type: "Table",
+            rows: Array.from({ length: TABLE_ROW_CAP + 5 }, () => ["x"]),
+          },
+          { $type: "ListViewItem", title: "row" },
+        ],
+      });
+      expect(warnings.some((warning) => warning.code === "clamped")).toBe(
+        false,
+      );
+      expect(warnings).toContainEqual({
+        code: "dropped",
+        component: "ListView",
+        detail: "1 non-item child was dropped.",
+      });
+    });
+
+    it("reports a renderable non-item child whose output it discards", () => {
+      const { card, warnings } = toAdaptiveCard({
+        $type: "ListView",
+        children: [
+          { $type: "Text", value: "stray" },
+          { $type: "ListViewItem", children: { $type: "Text", value: "Kept" } },
+        ],
+      });
+      expect(card.body).toEqual([
+        {
+          type: "Container",
+          items: [{ type: "TextBlock", text: "Kept", wrap: true }],
+        },
+      ]);
+      expect(warnings).toContainEqual({
+        code: "dropped",
+        component: "ListView",
+        detail: "1 non-item child was dropped.",
+      });
+    });
+
+    it.each([
+      ["before", 0],
+      ["after", 1],
+    ] as const)(
+      "does not let a discarded non-item child claim or report an input id, surviving control %s",
+      (_position, listViewIndex) => {
+        const listView = {
+          $type: "ListView",
+          children: [
+            { $type: "Input", name: "email" },
+            { $type: "ListViewItem", title: "row" },
+          ],
+        };
+        const survivor = { $type: "Input", name: "email", label: "Real" };
+        const { card, warnings } = toAdaptiveCard(
+          listViewIndex === 0 ? [listView, survivor] : [survivor, listView],
+        );
+        const ids = card.body.map((element) => (element as { id?: string }).id);
+        expect(ids).toContain("email");
+        expect(
+          warnings.some((warning) => warning.detail.includes("email_2")),
+        ).toBe(false);
+      },
+    );
+  });
+
+  describe("Carousel", () => {
+    it("reports the non-card children a nested carousel filters out", () => {
+      const { warnings } = toAdaptiveCard({
+        $type: "Col",
+        children: {
+          $type: "Carousel",
+          children: [
+            { $type: "Text", value: "lost" },
+            { $type: "Card", title: "kept" },
+          ],
+        },
+      });
+      expect(warnings).toContainEqual({
+        code: "dropped",
+        component: "Carousel",
+        detail: "1 non-card child was dropped.",
+      });
+    });
+
+    it("stays silent for a nested-carousel child that renders nothing anyway", () => {
+      const { warnings } = toAdaptiveCard({
+        $type: "Col",
+        children: {
+          $type: "Carousel",
+          children: [{ $type: "Spacer" }, { $type: "Card", title: "kept" }],
+        },
+      });
+      expect(warnings.some((warning) => warning.code === "dropped")).toBe(
+        false,
+      );
+    });
+
+    it("forwards a nested-carousel child's own dropped warning", () => {
+      const { warnings } = toAdaptiveCard({
+        $type: "Col",
+        children: {
+          $type: "Carousel",
+          children: [{ $type: "Mystery" }, { $type: "Card", title: "kept" }],
+        },
+      });
+      expect(warnings).toContainEqual({
+        code: "dropped",
+        component: "Mystery",
+        detail: "Unknown component type was dropped.",
+      });
+    });
+  });
+
+  describe("choices", () => {
+    it("reports options dropped for want of a string value", () => {
+      const { card, warnings } = toAdaptiveCard({
+        $type: "Select",
+        name: "s",
+        options: [{ label: "ok", value: "a" }, { label: "bad" }, "nope"],
+      });
+      expect((card.body[0] as { choices: unknown[] }).choices).toEqual([
+        { title: "ok", value: "a" },
+      ]);
+      expect(warnings).toContainEqual({
+        code: "dropped",
+        component: "Select",
+        detail: "2 options were dropped for want of a string value.",
+      });
+    });
+
+    it("names RadioGroup when the same loss happens there", () => {
+      const { warnings } = toAdaptiveCard({
+        $type: "RadioGroup",
+        name: "r",
+        options: [{ label: "ok", value: "a" }, { label: "bad" }],
+      });
+      expect(warnings).toContainEqual({
+        code: "dropped",
+        component: "RadioGroup",
+        detail: "1 option was dropped for want of a string value.",
+      });
+    });
   });
 
   describe("Table", () => {
+    it.each([["A"], [{}], [{ label: 42 }]])(
+      "keeps an unlabeled column's position in the header and reports it: %j",
+      (column) => {
+        const { card, warnings } = toAdaptiveCard({
+          $type: "Table",
+          columns: [column, { label: "B" }],
+          rows: [["1", "2"]],
+        });
+        const table = card.body[0] as TeamsTable;
+        expect(
+          table.rows[0]?.cells.map(
+            (cell) => (cell.items[0] as TeamsTextBlock).text,
+          ),
+        ).toEqual(["", "B"]);
+        expect(warnings).toContainEqual({
+          code: "dropped",
+          component: "Table",
+          detail: "1 column header was left blank for want of a string label.",
+        });
+      },
+    );
+
     it("renders firstRowAsHeaders true and a header row when columns are present", () => {
       const { card } = toAdaptiveCard({
         $type: "Table",
@@ -1158,7 +1328,13 @@ describe("toAdaptiveCard", () => {
       const value = "x".repeat(PAYLOAD_SOFT_CAP + 1000);
       const { warnings } = toAdaptiveCard({ $type: "Text", value });
       expect(warnings).toContainEqual(
-        expect.objectContaining({ code: "clamped", component: "Root" }),
+        expect.objectContaining({
+          code: "advisory",
+          component: "Root",
+          detail: expect.stringContaining(
+            `over the ${PAYLOAD_SOFT_CAP}-byte soft budget`,
+          ),
+        }),
       );
     });
 
@@ -1166,7 +1342,7 @@ describe("toAdaptiveCard", () => {
       const value = "汉".repeat(30000);
       const { warnings } = toAdaptiveCard({ $type: "Markdown", value });
       expect(warnings).toContainEqual(
-        expect.objectContaining({ code: "clamped", component: "Root" }),
+        expect.objectContaining({ code: "advisory", component: "Root" }),
       );
     });
 
@@ -1295,9 +1471,27 @@ describe("toAdaptiveCard", () => {
       expect(warnings).toContainEqual({
         code: "clamped",
         component: "Root",
-        detail: "nodes deeper than 64 levels were dropped.",
+        detail: "nodes deeper than 32 levels were dropped.",
       });
     });
+
+    it("reports the depth detail at the level it actually starts dropping", () => {
+      const chain = (levels: number) => {
+        let node: unknown = { $type: "Caption", value: "x" };
+        for (let i = 0; i < levels; i++) {
+          node = { $type: "Card", children: [node] };
+        }
+        return node;
+      };
+      const dropped = (node: unknown) =>
+        toAdaptiveCard(node).warnings.some((warning) =>
+          warning.detail.includes("deeper than"),
+        );
+      expect(dropped(chain(32))).toBe(false);
+      expect(dropped(chain(33))).toBe(true);
+      expect(dropped([chain(31)])).toBe(false);
+      expect(dropped([chain(32)])).toBe(true);
+    });
   });
 });