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

package/src/slack/types.ts

@@ -0,0 +1,230 @@
+import type { UIElement } from "../ir";
+
+/** A Slack plain-text composition object. */
+export interface SlackPlainText {
+  readonly type: "plain_text";
+  readonly text: string;
+}
+
+/** A Slack mrkdwn composition object. */
+export interface SlackMrkdwnText {
+  readonly type: "mrkdwn";
+  readonly text: string;
+}
+
+/** A text composition object accepted by card and alert text fields. */
+export type SlackTextObject = SlackPlainText | SlackMrkdwnText;
+
+/** A selectable Slack option. */
+export interface SlackOption {
+  readonly text: SlackPlainText;
+  readonly value: string;
+}
+
+/** A Slack button element. */
+export interface SlackButtonElement {
+  readonly type: "button";
+  readonly text: SlackPlainText;
+  readonly action_id: string;
+  readonly value?: string;
+  readonly style?: "primary" | "danger";
+}
+
+/** A Slack static-select element. */
+export interface SlackStaticSelectElement {
+  readonly type: "static_select";
+  readonly action_id: string;
+  readonly options: readonly SlackOption[];
+  readonly placeholder?: SlackPlainText;
+}
+
+/** A Slack date-picker element. */
+export interface SlackDatePickerElement {
+  readonly type: "datepicker";
+  readonly action_id: string;
+  readonly initial_date?: string;
+}
+
+/** A Slack checkbox-group element. */
+export interface SlackCheckboxesElement {
+  readonly type: "checkboxes";
+  readonly action_id: string;
+  readonly options: readonly SlackOption[];
+  readonly initial_options?: readonly SlackOption[];
+}
+
+/** A Slack radio-button element. */
+export interface SlackRadioButtonsElement {
+  readonly type: "radio_buttons";
+  readonly action_id: string;
+  readonly options: readonly SlackOption[];
+  readonly initial_option?: SlackOption;
+}
+
+/** A Slack plain-text input element. */
+export interface SlackPlainTextInputElement {
+  readonly type: "plain_text_input";
+  readonly action_id: string;
+  readonly multiline?: boolean;
+  readonly placeholder?: SlackPlainText;
+}
+
+/** An element accepted by a Slack actions block. */
+export type SlackActionElement =
+  | SlackButtonElement
+  | SlackStaticSelectElement
+  | SlackDatePickerElement
+  | SlackCheckboxesElement
+  | SlackRadioButtonsElement;
+
+/** A Slack header block. */
+export interface SlackHeaderBlock {
+  readonly type: "header";
+  readonly text: SlackPlainText;
+}
+
+/** A Slack section block. */
+export interface SlackSectionBlock {
+  readonly type: "section";
+  readonly text?: SlackMrkdwnText;
+  readonly fields?: readonly SlackMrkdwnText[];
+  readonly accessory?: SlackButtonElement;
+}
+
+/** A Slack context block. */
+export interface SlackContextBlock {
+  readonly type: "context";
+  readonly elements: readonly SlackMrkdwnText[];
+}
+
+/** A Slack image block. */
+export interface SlackImageBlock {
+  readonly type: "image";
+  readonly image_url: string;
+  readonly alt_text: string;
+}
+
+/** A Slack divider block. */
+export interface SlackDividerBlock {
+  readonly type: "divider";
+}
+
+/** A Slack actions block. */
+export interface SlackActionsBlock {
+  readonly type: "actions";
+  readonly elements: readonly SlackActionElement[];
+}
+
+/** A Slack input block. */
+export interface SlackInputBlock {
+  readonly type: "input";
+  readonly label: SlackPlainText;
+  readonly element: SlackPlainTextInputElement;
+}
+
+/** A text cell in a Slack data-table block. */
+export interface SlackDataTableRawTextCell {
+  readonly type: "raw_text";
+  readonly text: string;
+}
+
+/** A numeric cell in a Slack data-table block. */
+export interface SlackDataTableRawNumberCell {
+  readonly type: "raw_number";
+  readonly text: string;
+}
+
+/** A cell value in a Slack data-table block. */
+export type SlackDataTableCell =
+  | SlackDataTableRawTextCell
+  | SlackDataTableRawNumberCell;
+
+/**
+ * A Slack card block. A card does not nest arbitrary blocks: content is
+ * limited to a hero image, title, subtitle, body, subtext, and up to three
+ * action buttons. At least one of `hero_image`, `title`, `actions`, or `body`
+ * is required.
+ */
+export interface SlackCardBlock {
+  readonly type: "card";
+  readonly hero_image?: SlackImageBlock;
+  readonly title?: SlackTextObject;
+  readonly subtitle?: SlackTextObject;
+  readonly body?: SlackTextObject;
+  readonly subtext?: SlackTextObject;
+  readonly actions?: readonly SlackButtonElement[];
+}
+
+/** A Slack carousel block: a horizontally scrollable group of card blocks. */
+export interface SlackCarouselBlock {
+  readonly type: "carousel";
+  readonly elements: readonly SlackCardBlock[];
+}
+
+/** A Slack data-table block. The first entry in `rows` is the header row. */
+export interface SlackDataTableBlock {
+  readonly type: "data_table";
+  readonly caption: string;
+  readonly rows: readonly (readonly SlackDataTableCell[])[];
+  readonly page_size?: number;
+}
+
+/** A Slack markdown block. */
+export interface SlackMarkdownBlock {
+  readonly type: "markdown";
+  readonly text: string;
+}
+
+/** The severity level accepted by a Slack alert block. */
+export type SlackAlertLevel =
+  | "default"
+  | "info"
+  | "warning"
+  | "error"
+  | "success";
+
+/** A Slack alert block. Alert blocks are only supported in modals. */
+export interface SlackAlertBlock {
+  readonly type: "alert";
+  readonly text: SlackTextObject;
+  readonly level?: SlackAlertLevel;
+}
+
+/** A block emitted by the Slack converter. */
+export type SlackBlock =
+  | SlackHeaderBlock
+  | SlackSectionBlock
+  | SlackContextBlock
+  | SlackImageBlock
+  | SlackDividerBlock
+  | SlackActionsBlock
+  | SlackInputBlock
+  | SlackCardBlock
+  | SlackCarouselBlock
+  | SlackDataTableBlock
+  | SlackMarkdownBlock
+  | SlackAlertBlock;
+
+/** Options that select the target Slack surface. */
+export interface ToSlackBlocksOptions {
+  readonly surface?: "message" | "modal";
+}
+
+/** A non-fatal downgrade reported during Slack conversion. */
+export interface SlackConversionWarning {
+  readonly code: "clamped" | "dropped" | "fallback";
+  readonly component: string;
+  readonly detail: string;
+}
+
+/** The blocks and non-fatal warnings produced by Slack conversion. */
+export interface SlackBlocksResult {
+  readonly blocks: SlackBlock[];
+  readonly warnings: SlackConversionWarning[];
+}
+
+/** The IR nodes and non-fatal warnings produced by converting Slack Block Kit JSON back into generative UI. */
+export interface FromSlackBlocksResult {
+  readonly nodes: UIElement[];
+  readonly warnings: SlackConversionWarning[];
+}

package/src/slack.ts

@@ -0,0 +1,37 @@
+export { decodeBlockAction } from "./slack/decodeBlockAction";
+export { fromSlackBlocks } from "./slack/fromSlackBlocks";
+export { toSlackBlocks } from "./slack/toSlackBlocks";
+export type {
+  FromSlackBlocksResult,
+  SlackActionElement,
+  SlackActionsBlock,
+  SlackAlertBlock,
+  SlackAlertLevel,
+  SlackBlock,
+  SlackBlocksResult,
+  SlackButtonElement,
+  SlackCardBlock,
+  SlackCarouselBlock,
+  SlackCheckboxesElement,
+  SlackContextBlock,
+  SlackConversionWarning,
+  SlackDataTableBlock,
+  SlackDataTableCell,
+  SlackDataTableRawNumberCell,
+  SlackDataTableRawTextCell,
+  SlackDatePickerElement,
+  SlackDividerBlock,
+  SlackHeaderBlock,
+  SlackImageBlock,
+  SlackInputBlock,
+  SlackMarkdownBlock,
+  SlackMrkdwnText,
+  SlackOption,
+  SlackPlainText,
+  SlackPlainTextInputElement,
+  SlackRadioButtonsElement,
+  SlackSectionBlock,
+  SlackStaticSelectElement,
+  SlackTextObject,
+  ToSlackBlocksOptions,
+} from "./slack/types";

package/src/teams/boundSpec.ts

@@ -0,0 +1,102 @@
+import {
+  CHILDREN_CAP,
+  MAX_TRAVERSAL_DEPTH,
+  NODE_BUDGET,
+  type ClampReason,
+} from "./constants";
+
+interface BoundState {
+  remaining: number;
+  exhausted: boolean;
+}
+
+function boundNode(
+  value: unknown,
+  depth: number,
+  onClamp: (reason: ClampReason) => void,
+  state: BoundState,
+  ancestors: WeakSet<object>,
+): unknown {
+  if (state.remaining <= 0) {
+    if (!state.exhausted) {
+      state.exhausted = true;
+      onClamp("budget");
+    }
+    return null;
+  }
+  state.remaining -= 1;
+  if (depth > MAX_TRAVERSAL_DEPTH) {
+    onClamp("depth");
+    return null;
+  }
+  if (Array.isArray(value)) {
+    if (ancestors.has(value)) {
+      onClamp("cycle");
+      return null;
+    }
+    ancestors.add(value);
+    const bounded = Array.prototype.slice.call(
+      value,
+      0,
+      CHILDREN_CAP,
+    ) as unknown[];
+    if (value.length > CHILDREN_CAP) onClamp("children");
+    const result = bounded.map((item) =>
+      boundNode(item, depth + 1, onClamp, state, ancestors),
+    );
+    ancestors.delete(value);
+    return result;
+  }
+  if (
+    value !== null &&
+    typeof value === "object" &&
+    "children" in (value as Record<string, unknown>)
+  ) {
+    if (ancestors.has(value)) {
+      onClamp("cycle");
+      return null;
+    }
+    ancestors.add(value);
+    const record = value as Record<string, unknown>;
+    const result = {
+      ...record,
+      children: boundNode(
+        record["children"],
+        depth + 1,
+        onClamp,
+        state,
+        ancestors,
+      ),
+    };
+    ancestors.delete(value);
+    return result;
+  }
+  return value;
+}
+
+/**
+ * Produces a bounded plain copy of a raw generative-ui spec before it
+ * reaches `normalizeSpec`, whose own traversal of the root array or any
+ * `children` array walks the full reported length of a hostile proxied
+ * array before any per-field cap downstream ever applies. Every array
+ * (root, or `children` at any depth) is capped to {@link CHILDREN_CAP}
+ * entries via `Array.prototype.slice`, which bounds even a proxy with a
+ * fabricated `length`; recursion itself is capped at
+ * {@link MAX_TRAVERSAL_DEPTH}. `onClamp` fires once per level that was
+ * truncated, receiving the reason for that truncation: `"children"`,
+ * `"depth"`, `"budget"`, or `"cycle"`. The walk also spends a total budget of
+ * {@link NODE_BUDGET} nodes, so shared references cannot multiply work
+ * exponentially, and a node that is its own ancestor is cut to `null`.
+ */
+export function boundSpec(
+  spec: unknown,
+  onClamp: (reason: ClampReason) => void,
+): unknown {
+  return boundNode(
+    spec,
+    0,
+    onClamp,
+    { remaining: NODE_BUDGET, exhausted: false },
+    new WeakSet(),
+  );
+}

package/src/teams/constants.ts

@@ -0,0 +1,127 @@
+import type {
+  TeamsAdaptiveCard,
+  TeamsCardAttachment,
+  TeamsCardElement,
+  TeamsSubmitAction,
+  TeamsSubmitData,
+} from "./types";
+
+/** The Adaptive Card schema version emitted by {@link toAdaptiveCard}: the Teams desktop/web cap (mobile clients cap at 1.2). */
+export const AC_VERSION = "1.5";
+
+/** The `$schema` URL stamped on every emitted card. */
+export const ADAPTIVE_CARD_SCHEMA =
+  "http://adaptivecards.io/schemas/adaptive-card.json";
+
+/** The `contentType` stamped on every emitted attachment. */
+export const ATTACHMENT_CONTENT_TYPE =
+  "application/vnd.microsoft.card.adaptive";
+
+/** The maximum normalized traversal depth. */
+export const MAX_TRAVERSAL_DEPTH = 64;
+
+/**
+ * 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
+ * `normalizeSpec`. Bounds a hostile array's reported `length` so the pre-pass
+ * can never be made to walk further than this regardless of what the array
+ * claims about itself.
+ */
+export const CHILDREN_CAP = 200;
+
+/**
+ * The total number of nodes {@link boundSpec} will visit across one walk,
+ * regardless of how many times a shared reference recurs. Bounds the
+ * combinatorial work a DAG of shared or self-referential nodes would
+ * otherwise force even though each individual array stays within
+ * {@link CHILDREN_CAP}.
+ */
+export const NODE_BUDGET = 5000;
+
+export type ClampReason = "children" | "budget" | "cycle" | "depth";
+
+export function clampReasonDetail(reason: ClampReason): string {
+  if (reason === "budget") {
+    return `the tree was truncated after ${NODE_BUDGET} nodes.`;
+  }
+  if (reason === "cycle") return "a self-referencing node was dropped.";
+  if (reason === "depth") {
+    return `nodes deeper than ${MAX_TRAVERSAL_DEPTH} levels were dropped.`;
+  }
+  return `children were clamped to ${CHILDREN_CAP} entries.`;
+}
+
+/** The maximum number of attachments produced from a root-level Carousel. */
+export const CAROUSEL_ATTACHMENT_CAP = 10;
+
+/** The maximum number of primary-mode actions in one ActionSet; extras are set to secondary mode instead of being dropped. */
+export const PRIMARY_ACTION_CAP = 6;
+
+/** The maximum number of data rows in a Table. */
+export const TABLE_ROW_CAP = 100;
+
+/** The maximum number of columns in a Table. */
+export const TABLE_COLUMN_CAP = 20;
+
+/** The maximum number of choices in a Select or RadioGroup. */
+export const CHOICE_OPTION_CAP = 100;
+
+/** The soft byte-count budget for a serialized card, past which a warning notes Teams' 100 KB bot message limit (the card is never truncated to fit it). */
+export const PAYLOAD_SOFT_CAP = 80000;
+
+const textEncoder = new TextEncoder();
+
+/** Measures the wire size of `value` in UTF-8 bytes rather than UTF-16 code units. */
+export function utf8ByteLength(value: string): number {
+  return textEncoder.encode(value).byteLength;
+}
+
+/** Builds the fixed-shape Adaptive Card envelope around a converted body. */
+export function buildCard(body: TeamsCardElement[]): TeamsAdaptiveCard {
+  return {
+    $schema: ADAPTIVE_CARD_SCHEMA,
+    type: "AdaptiveCard",
+    version: AC_VERSION,
+    body,
+    actions: [],
+  };
+}
+
+/** Wraps a card as a bot-framework message attachment. */
+export function buildAttachment(card: TeamsAdaptiveCard): TeamsCardAttachment {
+  return { contentType: ATTACHMENT_CONTENT_TYPE, content: card };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * Nests an IR action under an `aui` key so `decodeSubmitData` can invert it
+ * back out of the merged `activity.value` object a Teams bot receives,
+ * alongside whatever other named inputs shared the card.
+ */
+export function buildSubmitData(action: unknown): TeamsSubmitData {
+  if (!isRecord(action)) return { aui: { type: "action" } };
+  const { type: rawType, ...payload } = action;
+  const type = typeof rawType === "string" ? rawType : "action";
+  return {
+    aui: {
+      type,
+      ...(Object.keys(payload).length > 0 ? { payload } : {}),
+    },
+  };
+}
+
+/** Builds an Action.Submit carrying `action` in the `aui` envelope. */
+export function buildSubmitAction(
+  title: string,
+  action: unknown,
+  mode?: "secondary",
+): TeamsSubmitAction {
+  return {
+    type: "Action.Submit",
+    title,
+    data: buildSubmitData(action),
+    ...(mode !== undefined ? { mode } : {}),
+  };
+}

package/src/teams/decodeSubmitData.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import { decodeSubmitData } from "./decodeSubmitData";
+
+describe("decodeSubmitData", () => {
+  it("decodes the aui envelope, spreading its payload into the result", () => {
+    const value = { aui: { type: "approve", payload: { requestId: "r1" } } };
+    expect(decodeSubmitData(value)).toEqual({
+      type: "approve",
+      requestId: "r1",
+    });
+  });
+
+  it("collects every other top-level key into $input", () => {
+    const value = {
+      aui: { type: "approve", payload: { requestId: "r1" } },
+      email: "a@b.com",
+      subscribe: "true",
+    };
+    expect(decodeSubmitData(value)).toEqual({
+      type: "approve",
+      requestId: "r1",
+      $input: { email: "a@b.com", subscribe: "true" },
+    });
+  });
+
+  it("omits $input when there are no other top-level keys", () => {
+    expect(decodeSubmitData({ aui: { type: "approve" } })).toEqual({
+      type: "approve",
+    });
+  });
+
+  it("omits payload when the envelope carries none", () => {
+    const value = { aui: { type: "approve" }, note: "hi" };
+    expect(decodeSubmitData(value)).toEqual({
+      type: "approve",
+      $input: { note: "hi" },
+    });
+  });
+
+  it("drops a $input key inside the envelope payload, keeping the slot for collected inputs", () => {
+    const value = {
+      aui: { type: "approve", payload: { requestId: "r1", $input: "spoofed" } },
+      email: "a@b.com",
+    };
+    expect(decodeSubmitData(value)).toEqual({
+      type: "approve",
+      requestId: "r1",
+      $input: { email: "a@b.com" },
+    });
+  });
+
+  it("drops a payload $input even when no input values were collected", () => {
+    const value = {
+      aui: { type: "approve", payload: { $input: "spoofed" } },
+    };
+    const decoded = decodeSubmitData(value);
+    expect(decoded).toEqual({ type: "approve" });
+    expect(decoded !== undefined && "$input" in decoded).toBe(false);
+  });
+
+  it("keeps the envelope type over a payload key of the same name", () => {
+    const value = {
+      aui: { type: "approve", payload: { type: "spoofed" } },
+    };
+    expect(decodeSubmitData(value)).toEqual({ type: "approve" });
+  });
+
+  it("returns undefined when aui is missing", () => {
+    expect(decodeSubmitData({ email: "a@b.com" })).toBeUndefined();
+  });
+
+  it("returns undefined for malformed or null input, never throwing", () => {
+    const malformed: unknown[] = [
+      null,
+      undefined,
+      42,
+      "just a string",
+      true,
+      [],
+      {},
+      { aui: "nope" },
+      { aui: {} },
+      { aui: { type: 123 } },
+    ];
+    for (const input of malformed) {
+      expect(() => decodeSubmitData(input)).not.toThrow();
+      expect(decodeSubmitData(input)).toBeUndefined();
+    }
+  });
+
+  it("never throws even when reading the input itself throws", () => {
+    const hostile = new Proxy(
+      {},
+      {
+        get() {
+          throw new Error("boom");
+        },
+      },
+    );
+    expect(() => decodeSubmitData(hostile)).not.toThrow();
+    expect(decodeSubmitData(hostile)).toBeUndefined();
+  });
+
+  it("returns undefined for a non-empty array activity.value", () => {
+    expect(decodeSubmitData([1, 2, 3])).toBeUndefined();
+  });
+
+  it("returns undefined when aui is inherited rather than owned", () => {
+    const value = Object.create({ aui: { type: "x" } });
+    expect(decodeSubmitData(value)).toBeUndefined();
+  });
+
+  it("returns undefined when the envelope's type is inherited rather than owned", () => {
+    const value = { aui: Object.create({ type: "x" }) };
+    expect(decodeSubmitData(value)).toBeUndefined();
+  });
+
+  it("keeps __proto__ and constructor keys from the payload as own data properties without polluting Object.prototype", () => {
+    const payload = JSON.parse(
+      '{"__proto__": {"evil": true}, "constructor": {"evil": true}}',
+    );
+    const value = { aui: { type: "approve", payload } };
+    const result = decodeSubmitData(value) as Record<string, unknown>;
+    expect(Object.prototype.hasOwnProperty.call(result, "__proto__")).toBe(
+      true,
+    );
+    expect(result["__proto__"]).toEqual({ evil: true });
+    expect(result["constructor"]).toEqual({ evil: true });
+    expect(({} as Record<string, unknown>)["evil"]).toBeUndefined();
+    expect(Object.getPrototypeOf({})).toBe(Object.prototype);
+  });
+
+  it("keeps __proto__ and constructor keys from $input as own data properties without polluting Object.prototype", () => {
+    const value = JSON.parse(
+      '{"aui": {"type": "approve"}, "__proto__": "hostile", "constructor": "hostile"}',
+    );
+    const result = decodeSubmitData(value);
+    const input = result?.["$input"] as Record<string, unknown>;
+    expect(Object.prototype.hasOwnProperty.call(input, "__proto__")).toBe(true);
+    expect(Object.prototype.hasOwnProperty.call(input, "constructor")).toBe(
+      true,
+    );
+    expect(input["__proto__"]).toBe("hostile");
+    expect(input["constructor"]).toBe("hostile");
+    expect(typeof ({} as object).constructor).toBe("function");
+    expect(Object.getPrototypeOf({})).toBe(Object.prototype);
+  });
+});

package/src/teams/decodeSubmitData.ts

@@ -0,0 +1,57 @@
+import type { Action } from "../ir";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * Decodes the merged `activity.value` object a Teams bot receives on
+ * Action.Submit, inverting the `aui` envelope {@link buildSubmitAction} nests
+ * the resume action under. Adaptive Cards fold every other same-card input's
+ * value into the same submit object keyed by its `id`, so every top-level key
+ * besides `aui` is collected into `$input` (omitted when there are none).
+ * `aui` is reserved for the envelope: `toAdaptiveCard` renames any input
+ * whose id would collide to an unused id derived from it before encoding, so
+ * a same-card input value can never land on this key. `$input` and `type`
+ * are reserved on the way out: a `$input` key inside the envelope payload is
+ * dropped so the slot only ever reflects same-card input values, and the
+ * envelope's own `type` wins over a payload key of the same name. Every
+ * collected key (in `payload` or `$input`) is kept as an own data property of
+ * the returned object, even a `__proto__` or `constructor` key, since the
+ * object is always built by spreading and `Object.fromEntries` rather than by
+ * keyed assignment. Envelope keys are read as own properties only, so
+ * prototype-inherited `aui`, `type`, or `payload` values never dispatch.
+ * Returns `undefined` for a missing or malformed `aui` envelope; never throws.
+ */
+export function decodeSubmitData(value: unknown): Action | undefined {
+  try {
+    if (!isRecord(value) || !Object.hasOwn(value, "aui")) return undefined;
+    const aui = value["aui"];
+    if (
+      !isRecord(aui) ||
+      !Object.hasOwn(aui, "type") ||
+      typeof aui["type"] !== "string"
+    ) {
+      return undefined;
+    }
+    const type = aui["type"];
+
+    const payload =
+      Object.hasOwn(aui, "payload") && isRecord(aui["payload"])
+        ? aui["payload"]
+        : {};
+    const payloadEntries = Object.entries(payload).filter(
+      ([key]) => key !== "$input",
+    );
+    const inputEntries = Object.entries(value).filter(([key]) => key !== "aui");
+    const input =
+      inputEntries.length > 0 ? Object.fromEntries(inputEntries) : undefined;
+
+    return {
+      ...Object.fromEntries(payloadEntries),
+      type,
+      ...(input !== undefined ? { $input: input } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}