@runtypelabs/persona 4.6.1 → 4.8.0

package/src/components/artifact-card.test.ts

@@ -0,0 +1,333 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it } from "vitest";
+import { PersonaArtifactCard } from "./artifact-card";
+import { componentRegistry, type ComponentRenderer } from "./registry";
+import type { ComponentContext } from "./registry";
+import type {
+  AgentWidgetArtifactsFeature,
+  AgentWidgetConfig,
+  PersonaArtifactStatusLabelContext,
+} from "../types";
+
+const makeContext = (
+  artifacts?: AgentWidgetArtifactsFeature
+): ComponentContext =>
+  ({
+    message: {},
+    config: {
+      features: { artifacts: { enabled: true, ...(artifacts ?? {}) } },
+    } as AgentWidgetConfig,
+    updateProps: () => {},
+  }) as unknown as ComponentContext;
+
+const render = (
+  props: Record<string, unknown>,
+  artifacts?: AgentWidgetArtifactsFeature
+): HTMLElement => PersonaArtifactCard(props, makeContext(artifacts));
+
+const streamingProps = {
+  artifactId: "a1",
+  title: "index.html",
+  status: "streaming",
+  artifactType: "markdown",
+  file: { path: "index.html", mimeType: "text/html", language: "html" },
+};
+
+const NBSP = String.fromCharCode(0xa0);
+
+const findStatusText = (root: HTMLElement): HTMLElement | null =>
+  root.querySelector(
+    ".persona-tool-loading-shimmer, .persona-tool-loading-shimmer-color, .persona-tool-loading-rainbow, .persona-tool-loading-pulse"
+  ) as HTMLElement | null;
+
+describe("PersonaArtifactCard streaming status", () => {
+  it("renders shimmer animation by default with no pulsing dot", () => {
+    const root = render(streamingProps);
+
+    // No leftover pulsing dot element.
+    expect(root.querySelector(".persona-rounded-full")).toBeNull();
+    expect(root.innerHTML).not.toContain("persona-pulse ");
+
+    const statusText = findStatusText(root);
+    expect(statusText).not.toBeNull();
+    expect(statusText!.classList.contains("persona-tool-loading-shimmer")).toBe(
+      true
+    );
+    expect(statusText!.getAttribute("data-preserve-animation")).toBe("true");
+    expect(
+      statusText!.style.getPropertyValue("--persona-tool-anim-duration")
+    ).toBe("2000ms");
+
+    const chars = statusText!.querySelectorAll(".persona-tool-char");
+    expect(chars.length).toBeGreaterThan(0);
+    expect((chars[0] as HTMLElement).style.getPropertyValue("--char-index")).toBe(
+      "0"
+    );
+    // Reconstruct the animated text from the character spans.
+    const text = Array.from(chars)
+      .map((c) => (c.textContent === NBSP ? " " : c.textContent))
+      .join("");
+    expect(text).toBe("Generating html...");
+  });
+
+  it("renders plain text with no animation classes when loadingAnimation is none", () => {
+    const root = render(streamingProps, { loadingAnimation: "none" });
+
+    expect(findStatusText(root)).toBeNull();
+    expect(root.querySelector(".persona-tool-char")).toBeNull();
+    expect(root.textContent).toContain("Generating html...");
+  });
+
+  it("applies the pulse class to the status element without char spans", () => {
+    const root = render(streamingProps, { loadingAnimation: "pulse" });
+
+    const statusText = root.querySelector(
+      ".persona-tool-loading-pulse"
+    ) as HTMLElement | null;
+    expect(statusText).not.toBeNull();
+    expect(statusText!.getAttribute("data-preserve-animation")).toBe("true");
+    expect(statusText!.querySelector(".persona-tool-char")).toBeNull();
+    expect(statusText!.textContent).toBe("Generating html...");
+  });
+
+  it("sets color CSS vars for shimmer-color mode", () => {
+    const root = render(streamingProps, {
+      loadingAnimation: "shimmer-color",
+      loadingAnimationColor: "#111111",
+      loadingAnimationSecondaryColor: "#eeeeee",
+      loadingAnimationDuration: 3000,
+    });
+
+    const statusText = root.querySelector(
+      ".persona-tool-loading-shimmer-color"
+    ) as HTMLElement | null;
+    expect(statusText).not.toBeNull();
+    expect(
+      statusText!.style.getPropertyValue("--persona-tool-anim-color")
+    ).toBe("#111111");
+    expect(
+      statusText!.style.getPropertyValue("--persona-tool-anim-secondary-color")
+    ).toBe("#eeeeee");
+    expect(
+      statusText!.style.getPropertyValue("--persona-tool-anim-duration")
+    ).toBe("3000ms");
+  });
+
+  it("carries the artifact-card class so radius/border/background come from CSS", () => {
+    const root = render(streamingProps);
+
+    // Standalone card must not hardcode the rounded-xl utility class.
+    expect(root.classList.contains("persona-rounded-xl")).toBe(false);
+    // Radius/border/background now live in widget.css keyed off this class,
+    // following the --persona-artifact-card-radius → assistant-bubble chain.
+    expect(root.classList.contains("persona-artifact-card")).toBe(true);
+  });
+
+  it("keeps border/background off inline styles so they come from CSS", () => {
+    const root = render(streamingProps);
+
+    expect(root.classList.contains("persona-artifact-card")).toBe(true);
+    // Border/bg/radius/cursor moved to widget.css keyed off the card class.
+    expect(root.style.border).toBe("");
+    expect(root.style.background).toBe("");
+    expect(root.style.backgroundColor).toBe("");
+    expect(root.style.borderRadius).toBe("");
+  });
+
+  it("renders the Download button as a label button carrying the artifact id", () => {
+    const root = render({
+      artifactId: "a1",
+      title: "index.html",
+      status: "complete",
+      artifactType: "markdown",
+      file: { path: "index.html", mimeType: "text/html", language: "html" },
+    });
+
+    const dl = root.querySelector(
+      "[data-download-artifact]"
+    ) as HTMLButtonElement | null;
+    expect(dl).not.toBeNull();
+    expect(dl!.tagName).toBe("BUTTON");
+    expect(dl!.classList.contains("persona-label-btn")).toBe(true);
+    expect(dl!.textContent).toBe("Download");
+    expect(dl!.getAttribute("data-download-artifact")).toBe("a1");
+  });
+
+  it("renders the complete state with a Download button and no animation", () => {
+    const root = render({
+      artifactId: "a1",
+      title: "index.html",
+      status: "complete",
+      artifactType: "markdown",
+      file: { path: "index.html", mimeType: "text/html", language: "html" },
+    });
+
+    expect(findStatusText(root)).toBeNull();
+    expect(root.querySelector(".persona-tool-char")).toBeNull();
+
+    const dl = root.querySelector(
+      "[data-download-artifact]"
+    ) as HTMLButtonElement | null;
+    expect(dl).not.toBeNull();
+    expect(dl!.textContent).toBe("Download");
+    // Subtitle shows the file type label, not a "Generating" status.
+    expect(root.textContent).not.toContain("Generating");
+  });
+});
+
+describe("PersonaArtifactCard statusLabel", () => {
+  // Reconstruct the (possibly char-span animated) status label text.
+  const labelText = (root: HTMLElement): string => {
+    const label = root.querySelector(
+      ".persona-artifact-status-label"
+    ) as HTMLElement | null;
+    if (!label) return "";
+    const chars = label.querySelectorAll(".persona-tool-char");
+    if (chars.length === 0) return label.textContent ?? "";
+    return Array.from(chars)
+      .map((c) => (c.textContent === NBSP ? " " : c.textContent))
+      .join("");
+  };
+
+  it("replaces the default status text with a plain string", () => {
+    const root = render(streamingProps, { statusLabel: "Cooking up your file..." });
+    expect(labelText(root)).toBe("Cooking up your file...");
+    expect(root.textContent).not.toContain("Generating");
+  });
+
+  it("calls a statusLabel function with the card surface and ctx", () => {
+    const calls: PersonaArtifactStatusLabelContext[] = [];
+    const root = render(streamingProps, {
+      statusLabel: (ctx) => {
+        calls.push(ctx);
+        return "Custom label";
+      },
+    });
+    expect(calls.length).toBe(1);
+    expect(calls[0].surface).toBe("card");
+    expect(calls[0].artifactId).toBe("a1");
+    expect(calls[0].artifactType).toBe("markdown");
+    // file: index.html -> fileTypeLabel "HTML".
+    expect(calls[0].typeLabel).toBe("HTML");
+    expect(typeof calls[0].content).toBe("function");
+    expect(labelText(root)).toBe("Custom label");
+  });
+
+  it("renders a { label, detail } as an animated label + plain detail span", () => {
+    const root = render(streamingProps, {
+      statusLabel: () => ({ label: "Writing", detail: "just started" }),
+    });
+    expect(labelText(root)).toBe("Writing");
+    const detail = root.querySelector(
+      ".persona-artifact-status-detail"
+    ) as HTMLElement | null;
+    expect(detail).not.toBeNull();
+    expect(detail!.textContent).toBe("just started");
+    // The detail span is un-animated (no char spans / loading classes).
+    expect(detail!.querySelector(".persona-tool-char")).toBeNull();
+  });
+
+  it("falls back to the default label when statusLabel throws", () => {
+    const root = render(streamingProps, {
+      statusLabel: () => {
+        throw new Error("boom");
+      },
+    });
+    expect(labelText(root)).toBe("Generating html...");
+  });
+});
+
+describe("PersonaArtifactCard custom card actions", () => {
+  const completeProps = {
+    artifactId: "a1",
+    title: "index.html",
+    status: "complete",
+    artifactType: "markdown",
+    markdown: "# Hi",
+    file: { path: "index.html", mimeType: "text/html", language: "html" },
+  };
+
+  it("renders a card action button before Download on complete cards", () => {
+    const root = render(completeProps, {
+      cardActions: [
+        { id: "save", label: "Save to Drive", icon: "star", onClick: () => {} },
+      ],
+    });
+
+    const btn = root.querySelector(
+      '[data-artifact-custom-action="save"]'
+    ) as HTMLButtonElement | null;
+    expect(btn).not.toBeNull();
+    expect(btn!.tagName).toBe("BUTTON");
+    // Delegated in ui.ts: the card carries the id attribute, no direct listener.
+    expect(btn!.getAttribute("data-artifact-custom-action")).toBe("save");
+
+    const dl = root.querySelector(
+      "[data-download-artifact]"
+    ) as HTMLElement | null;
+    expect(dl).not.toBeNull();
+    // Custom actions render before Download.
+    expect(
+      btn!.compareDocumentPosition(dl!) & Node.DOCUMENT_POSITION_FOLLOWING
+    ).toBeTruthy();
+  });
+
+  it("does not render card actions while streaming", () => {
+    const root = render(streamingProps, {
+      cardActions: [
+        { id: "save", label: "Save to Drive", icon: "star", onClick: () => {} },
+      ],
+    });
+    expect(root.querySelector("[data-artifact-custom-action]")).toBeNull();
+  });
+
+  it("suppresses a card action whose visible() returns false", () => {
+    const root = render(completeProps, {
+      cardActions: [
+        {
+          id: "save",
+          label: "Save",
+          icon: "star",
+          visible: () => false,
+          onClick: () => {},
+        },
+      ],
+    });
+    expect(root.querySelector("[data-artifact-custom-action]")).toBeNull();
+  });
+});
+
+describe("componentRegistry registration options", () => {
+  const noop: ComponentRenderer = () => document.createElement("div");
+
+  afterEach(() => {
+    componentRegistry.unregister("OptTest");
+  });
+
+  it("registers the built-in artifact card with bubbleChrome:false", () => {
+    expect(componentRegistry.getOptions("PersonaArtifactCard")?.bubbleChrome).toBe(false);
+  });
+
+  it("returns the options passed to register", () => {
+    componentRegistry.register("OptTest", noop, { bubbleChrome: false });
+    expect(componentRegistry.getOptions("OptTest")).toEqual({ bubbleChrome: false });
+  });
+
+  it("returns undefined when a component is registered without options", () => {
+    componentRegistry.register("OptTest", noop);
+    expect(componentRegistry.getOptions("OptTest")).toBeUndefined();
+  });
+
+  it("clears prior options when re-registered without options", () => {
+    componentRegistry.register("OptTest", noop, { bubbleChrome: false });
+    componentRegistry.register("OptTest", noop);
+    expect(componentRegistry.getOptions("OptTest")).toBeUndefined();
+  });
+
+  it("drops options on unregister", () => {
+    componentRegistry.register("OptTest", noop, { bubbleChrome: false });
+    componentRegistry.unregister("OptTest");
+    expect(componentRegistry.getOptions("OptTest")).toBeUndefined();
+  });
+});

package/src/components/artifact-card.ts

@@ -1,4 +1,14 @@
 import type { ComponentContext, ComponentRenderer } from "./registry";
+import type { PersonaArtifactFileMeta, PersonaArtifactRecord } from "../types";
+import { fileTypeLabel, basenameOf } from "../utils/artifact-file";
+import {
+  applyArtifactStatus,
+  clearArtifactStatusTracking,
+  resolveArtifactStatusLabel
+} from "../utils/artifact-status-label";
+import { createLabelButton } from "../utils/buttons";
+import { buildArtifactActionButton } from "../utils/artifact-custom-actions";
+import type { PersonaArtifactActionContext } from "../types";
 
 /**
  * Default artifact card renderer.
@@ -6,26 +16,32 @@ import type { ComponentContext, ComponentRenderer } from "./registry";
  */
 function renderDefaultArtifactCard(
   props: Record<string, unknown>,
-  _context: ComponentContext
+  context: ComponentContext
 ): HTMLElement {
-  const title =
+  const file =
+    props.file && typeof props.file === "object" && !Array.isArray(props.file)
+      ? (props.file as PersonaArtifactFileMeta)
+      : undefined;
+  const rawTitle =
     typeof props.title === "string" && props.title
       ? props.title
       : "Untitled artifact";
+  // File artifacts show the basename (title stays the full path on the wire).
+  const title = file ? basenameOf(file.path) : rawTitle;
   const artifactId =
     typeof props.artifactId === "string" ? props.artifactId : "";
   const status = props.status === "streaming" ? "streaming" : "complete";
   const artifactType =
     typeof props.artifactType === "string" ? props.artifactType : "markdown";
-  const subtitle =
-    artifactType === "component" ? "Component" : "Document";
+  const subtitle = file
+    ? fileTypeLabel(file)
+    : artifactType === "component"
+      ? "Component"
+      : "Document";
 
   const root = document.createElement("div");
   root.className =
-    "persona-flex persona-w-full persona-max-w-full persona-items-center persona-gap-3 persona-rounded-xl persona-px-4 persona-py-3";
-  root.style.border = "1px solid var(--persona-border, #e5e7eb)";
-  root.style.backgroundColor = "var(--persona-surface, #ffffff)";
-  root.style.cursor = "pointer";
+    "persona-artifact-card persona-flex persona-w-full persona-max-w-full persona-items-center persona-gap-3 persona-px-4 persona-py-3";
   root.tabIndex = 0;
   root.setAttribute("role", "button");
   root.setAttribute("aria-label", `Open ${title} in artifact panel`);
@@ -56,35 +72,66 @@ function renderDefaultArtifactCard(
   subtitleEl.style.color = "var(--persona-muted, #9ca3af)";
 
   if (status === "streaming") {
-    // Pulsing dot for streaming status
-    const dot = document.createElement("span");
-    dot.className = "persona-inline-block persona-w-1.5 persona-h-1.5 persona-rounded-full";
-    dot.style.backgroundColor = "var(--persona-primary, #171717)";
-    dot.style.animation = "persona-pulse 1.5s ease-in-out infinite";
-    subtitleEl.appendChild(dot);
-
-    const statusText = document.createElement("span");
-    statusText.textContent = `Generating ${subtitle.toLowerCase()}...`;
-    subtitleEl.appendChild(statusText);
+    const artifactsCfg = context?.config?.features?.artifacts;
+    // The card re-renders only at streaming-start and completion (deltas flow to
+    // the pane / inline block, not here), so live counters don't tick on the
+    // card; the string / label form still applies. Build a minimal record from
+    // the card props so the shared resolver derives the same typeLabel + ctx.
+    const record: PersonaArtifactRecord = {
+      id: artifactId,
+      artifactType: artifactType === "component" ? "component" : "markdown",
+      title: rawTitle,
+      status: "streaming",
+      ...(typeof props.markdown === "string" ? { markdown: props.markdown } : {}),
+      ...(file ? { file } : {})
+    };
+    const resolved = resolveArtifactStatusLabel(record, artifactsCfg, "card");
+    applyArtifactStatus(subtitleEl, resolved, artifactsCfg);
   } else {
+    if (artifactId) clearArtifactStatusTracking(artifactId);
     subtitleEl.textContent = subtitle;
   }
 
   meta.append(titleEl, subtitleEl);
   root.append(iconBox, meta);
 
-  // Download button (visible when artifact is complete)
+  // Custom actions + Download button render only on complete artifacts, same
+  // as Download: content-dependent actions during streaming would act on
+  // partial content, so they wait until the artifact is fully materialized.
   if (status === "complete") {
-    const dl = document.createElement("button");
-    dl.type = "button";
-    dl.textContent = "Download";
+    // Custom card actions carry NO direct listeners (the card re-renders during
+    // streaming and is morphed by idiomorph). Clicks are handled by event
+    // delegation in ui.ts, keyed off data-artifact-custom-action, mirroring the
+    // Download button's data-download-artifact delegation.
+    const cardActions = context?.config?.features?.artifacts?.cardActions;
+    if (cardActions && cardActions.length > 0) {
+      const ctx: PersonaArtifactActionContext = {
+        artifactId: artifactId || null,
+        title,
+        artifactType,
+        markdown:
+          typeof props.markdown === "string" ? props.markdown : undefined,
+        file,
+      };
+      for (const action of cardActions) {
+        try {
+          if (action.visible === undefined || action.visible(ctx)) {
+            const btn = buildArtifactActionButton(action);
+            btn.setAttribute("data-artifact-custom-action", action.id);
+            btn.className = `${btn.className} persona-flex-shrink-0`;
+            root.append(btn);
+          }
+        } catch {
+          // A single bad action must not take down the whole card.
+        }
+      }
+    }
+
+    const dl = createLabelButton({
+      label: "Download",
+      className: "persona-flex-shrink-0",
+    });
     dl.title = `Download ${title}`;
-    dl.className =
-      "persona-flex-shrink-0 persona-rounded-md persona-px-3 persona-py-1.5 persona-text-xs persona-font-medium";
-    dl.style.border = "1px solid var(--persona-border, #e5e7eb)";
-    dl.style.color = "var(--persona-text, #1f2937)";
-    dl.style.backgroundColor = "transparent";
-    dl.style.cursor = "pointer";
     dl.setAttribute("data-download-artifact", artifactId);
     root.append(dl);
   }