@dbx-tools/ui-teams 0.6.63 → 0.6.64

package/README.md

@@ -25,7 +25,8 @@ contract from [`@dbx-tools/shared-teams`](../../shared/teams) and renders throug
 - `AdaptiveCardView` - a thin React wrapper over the imperative `adaptivecards`
   renderer: feed it a compiled Adaptive Card document and it mounts the rendered
   node, re-rendering on change and wiring `Action.OpenUrl` clicks (open in a new
-  tab by default, or intercept with `onOpenUrl`).
+  tab by default, or intercept with `onOpenUrl`). The renderer is loaded only
+  when the first card mounts.
 - `AdaptiveCardGallery` - a self-contained dev tool: edit a `CardSpec` (or pick a
   sample), compile it through the server's `POST /api/teams/card` route, and see
   the card render live. This is the drop-in "display them" surface for a dev
@@ -35,10 +36,10 @@ contract from [`@dbx-tools/shared-teams`](../../shared/teams) and renders throug
 - Markdown in a `TextBlock` actually renders. A `TextBlock` is markdown per the
   Adaptive Cards spec, but `adaptivecards` ships no parser - it leaves the
   implementation (and its sanitization) to the host, so `**bold**` renders
-  literally until one is installed. Importing this package registers `marked`
-  as the renderer's `onProcessMarkdown` processor, degrading to plain text if a
-  string fails to parse, and the stylesheet re-applies list markers / paragraph
-  spacing that Tailwind's preflight resets away.
+  literally until one is installed. Mounting the first card loads and registers
+  `marked` as the renderer's `onProcessMarkdown` processor, degrading to plain
+  text if a string fails to parse, and the stylesheet re-applies list markers /
+  paragraph spacing that Tailwind's preflight resets away.
 
 ## Simulate A Teams Chat
 

package/package.json

@@ -24,9 +24,9 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@dbx-tools/shared-core": "0.6.63",
-    "@dbx-tools/shared-teams": "0.6.63",
-    "@dbx-tools/ui-appkit": "0.6.63",
+    "@dbx-tools/shared-core": "0.6.64",
+    "@dbx-tools/shared-teams": "0.6.64",
+    "@dbx-tools/ui-appkit": "0.6.64",
     "adaptivecards": "^3.0.5",
     "marked": "^18.0.5",
     "react": "^19.2.4",
@@ -36,7 +36,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.63",
+  "version": "0.6.64",
   "type": "module",
   "exports": {
     "./react": "./src/react/index.ts",

package/src/react/_adaptive-card-renderer.tsx

@@ -0,0 +1,58 @@
+/**
+ * Imperative Adaptive Cards renderer loaded behind the public React wrapper.
+ *
+ * The `adaptivecards` package leaves TextBlock markdown processing to its host,
+ * so this module installs the shared `marked` processor when the renderer chunk
+ * is first requested.
+ */
+import * as AdaptiveCards from "adaptivecards";
+import { marked } from "marked";
+import { useEffect, useRef } from "react";
+import type { AdaptiveCardViewProps } from "./adaptive-card.tsx";
+
+/** Install the process-wide markdown callback required by Adaptive Cards. */
+function _installMarkdownProcessor(): void {
+  AdaptiveCards.AdaptiveCard.onProcessMarkdown = (text, result) => {
+    try {
+      result.outputHtml = marked.parse(text, { async: false, breaks: true }) as string;
+      result.didProcess = true;
+    } catch {
+      result.didProcess = false;
+    }
+  };
+}
+
+_installMarkdownProcessor();
+
+/** Parse and mount one Adaptive Card document into a host element. */
+const AdaptiveCardRenderer = ({ card, onOpenUrl, className }: AdaptiveCardViewProps) => {
+  const hostRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+    const rendered = new AdaptiveCards.AdaptiveCard();
+    rendered.onExecuteAction = (action) => {
+      if (action instanceof AdaptiveCards.OpenUrlAction && action.url) {
+        if (onOpenUrl) onOpenUrl(action.url);
+        else window.open(action.url, "_blank", "noopener,noreferrer");
+      }
+    };
+    try {
+      rendered.parse(card as unknown as Record<string, unknown>);
+      const element = rendered.render();
+      host.replaceChildren(...(element ? [element] : []));
+    } catch (error) {
+      host.replaceChildren(
+        Object.assign(document.createElement("pre"), {
+          textContent: `Failed to render card: ${(error as Error).message}`,
+        }),
+      );
+    }
+    return () => host.replaceChildren();
+  }, [card, onOpenUrl]);
+
+  return <div ref={hostRef} className={className} data-testid="adaptive-card" />;
+};
+
+export default AdaptiveCardRenderer;

package/src/react/adaptive-card.tsx

@@ -1,46 +1,7 @@
-// React wrapper over the Adaptive Cards JavaScript renderer (the
-// `adaptivecards` npm package). The renderer is imperative - you feed it card
-// JSON and it returns a rendered `HTMLElement` - so this component parses the
-// document and mounts the rendered node into a ref on every change, and wires
-// `Action.OpenUrl` clicks to an optional handler (defaulting to opening the URL
-// in a new tab). This is the same renderer many internal Teams preview tools
-// embed to show cards outside Teams.
-//
-// The renderer deliberately ships NO markdown parser: a `TextBlock` is markdown
-// per the Adaptive Cards spec, but `adaptivecards` leaves the implementation to
-// the host so each host can pick its own (and its own sanitization). Without a
-// host processor Teams' own `**bold**` renders literally, so this module
-// installs `marked` as the processor once at import - see
-// {@link installMarkdownProcessor}.
-
 import type { AdaptiveCard as AdaptiveCardDocument } from "@dbx-tools/shared-teams";
-import * as AdaptiveCards from "adaptivecards";
-import { marked } from "marked";
-import { useEffect, useRef } from "react";
-
-/**
- * Teach the renderer to process `TextBlock` markdown with `marked`.
- *
- * `onProcessMarkdown` is a STATIC hook on `AdaptiveCard`, so this runs once per
- * module load rather than per component. `didProcess` must be set to `true` or
- * the renderer discards the HTML and falls back to the raw text.
- *
- * `marked` is called in a try/catch and falls back to leaving the text alone:
- * card text can come from a model, and a markdown edge case should degrade to
- * plain text rather than blanking the card.
- */
-const installMarkdownProcessor = () => {
-  AdaptiveCards.AdaptiveCard.onProcessMarkdown = (text, result) => {
-    try {
-      result.outputHtml = marked.parse(text, { async: false, breaks: true }) as string;
-      result.didProcess = true;
-    } catch {
-      result.didProcess = false;
-    }
-  };
-};
+import { lazy, Suspense } from "react";
 
-installMarkdownProcessor();
+const AdaptiveCardRenderer = lazy(() => import("./_adaptive-card-renderer.tsx"));
 
 /** Props for {@link AdaptiveCardView}. */
 export interface AdaptiveCardViewProps {
@@ -56,35 +17,13 @@ export interface AdaptiveCardViewProps {
 }
 
 /**
- * Render a single Adaptive Card document with the `adaptivecards` renderer.
- * Re-renders whenever the card JSON changes.
+ * Render a single Adaptive Card document, loading the imperative renderer and
+ * markdown processor only when a card is actually mounted.
  */
-export const AdaptiveCardView = ({ card, onOpenUrl, className }: AdaptiveCardViewProps) => {
-  const hostRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    const host = hostRef.current;
-    if (!host) return;
-    const rendered = new AdaptiveCards.AdaptiveCard();
-    rendered.onExecuteAction = (action) => {
-      if (action instanceof AdaptiveCards.OpenUrlAction && action.url) {
-        if (onOpenUrl) onOpenUrl(action.url);
-        else window.open(action.url, "_blank", "noopener,noreferrer");
-      }
-    };
-    try {
-      rendered.parse(card as unknown as Record<string, unknown>);
-      const element = rendered.render();
-      host.replaceChildren(...(element ? [element] : []));
-    } catch (err) {
-      host.replaceChildren(
-        Object.assign(document.createElement("pre"), {
-          textContent: `Failed to render card: ${(err as Error).message}`,
-        }),
-      );
-    }
-    return () => host.replaceChildren();
-  }, [card, onOpenUrl]);
-
-  return <div ref={hostRef} className={className} data-testid="adaptive-card" />;
-};
+export const AdaptiveCardView = (props: AdaptiveCardViewProps) => (
+  <Suspense
+    fallback={<div className={props.className} data-testid="adaptive-card" aria-busy="true" />}
+  >
+    <AdaptiveCardRenderer {...props} />
+  </Suspense>
+);