@runtypelabs/persona 4.15.0 → 4.16.0

package/src/components/suggestions.ts

@@ -138,6 +138,205 @@ const animateEntrance = (elements: readonly HTMLElement[]): void => {
   });
 };
 
+export interface SuggestionElementContext {
+  /** Fully normalized item, including the effective send/fill behavior. */
+  item: AgentWidgetResolvedSuggestion;
+  index: number;
+  surface: AgentWidgetSuggestionSurface;
+  source: AgentWidgetSuggestionSource;
+  variant: AgentWidgetSuggestionVariant;
+  streaming: boolean;
+  config: AgentWidgetConfig;
+  plugins: readonly AgentWidgetPlugin[];
+  chipsConfig?: AgentWidgetSuggestionChipsConfig;
+  session: AgentWidgetSession;
+  /** Read live: inline mentions and composer rebuilds swap the input element. */
+  getTextarea: () => HTMLTextAreaElement;
+  /** Node the cancelable `persona:suggestion:*` events dispatch from. */
+  eventTarget: HTMLElement;
+}
+
+/**
+ * Build one suggestion element with the full select pipeline attached:
+ * cancelable DOM events, `onSuggestionSelect` hooks, then send or fill. The
+ * suggestion rows and the `renderWelcome` ctx's `renderStarter` share this, so
+ * a plugin-rendered starter behaves identically to a built-in one.
+ */
+export const createSuggestionElement = (
+  context: SuggestionElementContext
+): HTMLElement => {
+  const {
+    item,
+    index,
+    surface,
+    source,
+    variant,
+    streaming,
+    config,
+    plugins,
+    chipsConfig,
+    session,
+    getTextarea,
+    eventTarget,
+  } = context;
+  const isFollowUp = surface === "followUp";
+  const itemBehavior = item.behavior;
+
+  const select = () => {
+    if (session.isStreaming()) return;
+    const detail = {
+      suggestion: { ...item },
+      surface,
+      source,
+      behavior: itemBehavior,
+    };
+    const shouldContinue = eventTarget.dispatchEvent(
+      new CustomEvent("persona:suggestion:selected", {
+        detail,
+        bubbles: true,
+        composed: true,
+        cancelable: true,
+      })
+    );
+    if (isFollowUp) {
+      eventTarget.dispatchEvent(
+        new CustomEvent("persona:suggestReplies:selected", {
+          detail: { suggestion: item.prompt },
+          bubbles: true,
+          composed: true,
+        })
+      );
+    }
+    if (!shouldContinue) return;
+
+    for (const plugin of plugins) {
+      if (
+        plugin.onSuggestionSelect?.({
+          suggestion: { ...item },
+          surface,
+          source,
+          variant,
+          config,
+        }) === false
+      ) {
+        return;
+      }
+    }
+
+    const textarea = getTextarea();
+    if (itemBehavior === "fill") {
+      textarea.value = item.prompt;
+      textarea.dispatchEvent(new Event("input", { bubbles: true, composed: true }));
+      textarea.focus();
+      return;
+    }
+
+    textarea.value = "";
+    session.sendMessage(item.prompt);
+  };
+
+  const defaultRenderer = (): HTMLElement => {
+    const button = createElement(
+      "button",
+      `persona-suggestion persona-suggestion--${variant}`
+    ) as HTMLButtonElement;
+    button.type = "button";
+    button.disabled = streaming;
+    button.dataset.suggestionId = item.id;
+    button.dataset.emphasis = item.emphasis;
+    button.dataset.behavior = itemBehavior;
+
+    // Legacy `suggestionChipsConfig` compat is chip-only: its inline
+    // styles would otherwise override the card/list padding tokens.
+    if (variant === "chip") {
+      if (chipsConfig?.fontFamily) {
+        button.style.fontFamily = fontFamilyValue(chipsConfig.fontFamily);
+      }
+      if (chipsConfig?.fontWeight) {
+        button.style.fontWeight = chipsConfig.fontWeight;
+      }
+      if (chipsConfig?.paddingX) {
+        button.style.paddingLeft = chipsConfig.paddingX;
+        button.style.paddingRight = chipsConfig.paddingX;
+      }
+      if (chipsConfig?.paddingY) {
+        button.style.paddingTop = chipsConfig.paddingY;
+        button.style.paddingBottom = chipsConfig.paddingY;
+      }
+    }
+
+    if (item.icon) {
+      const icon = renderLucideIcon(
+        item.icon,
+        "var(--persona-suggestion-icon-size)",
+        "currentColor",
+        1.8
+      );
+      if (icon) {
+        icon.classList.add("persona-suggestion__icon");
+        // The glyph strokes in currentColor, so this tints it alone; inline
+        // also beats the emphasis-primary icon rule.
+        if (item.iconColor) icon.style.color = item.iconColor;
+        button.appendChild(icon);
+      }
+    }
+
+    const copy = createElement("span", "persona-suggestion__copy");
+    copy.appendChild(
+      createNode("span", {
+        className: "persona-suggestion__label",
+        text: item.label,
+      })
+    );
+    // Chips are single-line labels; descriptions belong to card and list.
+    if (item.description && variant !== "chip") {
+      copy.appendChild(
+        createNode("span", {
+          className: "persona-suggestion__description",
+          text: item.description,
+        })
+      );
+    }
+    button.appendChild(copy);
+
+    if (variant !== "chip") {
+      const arrow = renderLucideIcon("arrow-right", 16, "currentColor", 1.8);
+      if (arrow) {
+        arrow.classList.add("persona-suggestion__arrow");
+        button.appendChild(arrow);
+      }
+    }
+
+    button.addEventListener("click", select);
+    return button;
+  };
+
+  let element: HTMLElement | null = null;
+  for (const plugin of plugins) {
+    if (!plugin.renderSuggestion) continue;
+    element = plugin.renderSuggestion({
+      suggestion: { ...item },
+      index,
+      surface,
+      source,
+      variant,
+      streaming,
+      config,
+      defaultRenderer,
+      select,
+    });
+    if (element) break;
+  }
+  element ??= defaultRenderer();
+  element.dataset.suggestionId ||= item.id;
+  element.dataset.behavior ||= itemBehavior;
+  element.dataset.emphasis ||= item.emphasis;
+  if (!(element instanceof HTMLButtonElement)) {
+    element.setAttribute("aria-disabled", streaming ? "true" : "false");
+  }
+  return element;
+};
+
 export const createSuggestions = (container: HTMLElement): SuggestionButtons => {
   const suggestionButtons: HTMLButtonElement[] = [];
   const suggestionElements: HTMLElement[] = [];
@@ -298,159 +497,20 @@ export const createSuggestions = (container: HTMLElement): SuggestionButtons =>
     const streaming = session.isStreaming();
 
     normalized.forEach((item, index) => {
-      const itemBehavior = item.behavior;
-      const select = () => {
-        if (session.isStreaming()) return;
-        const detail = {
-          suggestion: { ...item },
-          surface,
-          source,
-          behavior: itemBehavior,
-        };
-        const shouldContinue = container.dispatchEvent(
-          new CustomEvent("persona:suggestion:selected", {
-            detail,
-            bubbles: true,
-            composed: true,
-            cancelable: true,
-          })
-        );
-        if (isFollowUp) {
-          container.dispatchEvent(
-            new CustomEvent("persona:suggestReplies:selected", {
-              detail: { suggestion: item.prompt },
-              bubbles: true,
-              composed: true,
-            })
-          );
-        }
-        if (!shouldContinue) return;
-
-        for (const plugin of plugins) {
-          if (
-            plugin.onSuggestionSelect?.({
-              suggestion: { ...item },
-              surface,
-              source,
-              variant,
-              config: widgetConfig,
-            }) === false
-          ) {
-            return;
-          }
-        }
-
-        if (itemBehavior === "fill") {
-          textarea.value = item.prompt;
-          textarea.dispatchEvent(
-            new Event("input", { bubbles: true, composed: true })
-          );
-          textarea.focus();
-          return;
-        }
-
-        textarea.value = "";
-        session.sendMessage(item.prompt);
-      };
-
-      const defaultRenderer = (): HTMLElement => {
-        const button = createElement(
-          "button",
-          `persona-suggestion persona-suggestion--${variant}`
-        ) as HTMLButtonElement;
-        button.type = "button";
-        button.disabled = streaming;
-        button.dataset.suggestionId = item.id;
-        button.dataset.emphasis = item.emphasis;
-        button.dataset.behavior = itemBehavior;
-
-        // Legacy `suggestionChipsConfig` compat is chip-only: its inline
-        // styles would otherwise override the card/list padding tokens.
-        if (variant === "chip") {
-          if (chipsConfig?.fontFamily) {
-            button.style.fontFamily = fontFamilyValue(chipsConfig.fontFamily);
-          }
-          if (chipsConfig?.fontWeight) {
-            button.style.fontWeight = chipsConfig.fontWeight;
-          }
-          if (chipsConfig?.paddingX) {
-            button.style.paddingLeft = chipsConfig.paddingX;
-            button.style.paddingRight = chipsConfig.paddingX;
-          }
-          if (chipsConfig?.paddingY) {
-            button.style.paddingTop = chipsConfig.paddingY;
-            button.style.paddingBottom = chipsConfig.paddingY;
-          }
-        }
-
-        if (item.icon) {
-          const icon = renderLucideIcon(
-            item.icon,
-            "var(--persona-suggestion-icon-size)",
-            "currentColor",
-            1.8
-          );
-          if (icon) {
-            icon.classList.add("persona-suggestion__icon");
-            // The glyph strokes in currentColor, so this tints it alone; inline
-            // also beats the emphasis-primary icon rule.
-            if (item.iconColor) icon.style.color = item.iconColor;
-            button.appendChild(icon);
-          }
-        }
-
-        const copy = createElement("span", "persona-suggestion__copy");
-        copy.appendChild(
-          createNode("span", {
-            className: "persona-suggestion__label",
-            text: item.label,
-          })
-        );
-        if (item.description) {
-          copy.appendChild(
-            createNode("span", {
-              className: "persona-suggestion__description",
-              text: item.description,
-            })
-          );
-        }
-        button.appendChild(copy);
-
-        if (variant !== "chip") {
-          const arrow = renderLucideIcon("arrow-right", 16, "currentColor", 1.8);
-          if (arrow) {
-            arrow.classList.add("persona-suggestion__arrow");
-            button.appendChild(arrow);
-          }
-        }
-
-        button.addEventListener("click", select);
-        return button;
-      };
-
-      let element: HTMLElement | null = null;
-      for (const plugin of plugins) {
-        if (!plugin.renderSuggestion) continue;
-        element = plugin.renderSuggestion({
-          suggestion: { ...item },
-          index,
-          surface,
-          source,
-          variant,
-          streaming,
-          config: widgetConfig,
-          defaultRenderer,
-          select,
-        });
-        if (element) break;
-      }
-      element ??= defaultRenderer();
-      element.dataset.suggestionId ||= item.id;
-      element.dataset.behavior ||= itemBehavior;
-      element.dataset.emphasis ||= item.emphasis;
-      if (!(element instanceof HTMLButtonElement)) {
-        element.setAttribute("aria-disabled", streaming ? "true" : "false");
-      }
+      const element = createSuggestionElement({
+        item,
+        index,
+        surface,
+        source,
+        variant,
+        streaming,
+        config: widgetConfig,
+        plugins,
+        chipsConfig,
+        session,
+        getTextarea: () => textarea,
+        eventTarget: container,
+      });
 
       fragment.appendChild(element);
       suggestionElements.push(element);

package/src/components/welcome.test.ts

@@ -0,0 +1,121 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  animateWelcomeOut,
+  applyWelcomeConfig,
+  applyWelcomeVisibility,
+  buildGreetingHost,
+  buildWelcomeHost,
+  renderWelcomeGreeting,
+} from "./welcome";
+import { resolveWelcomeConfig } from "../welcome";
+import type { AgentWidgetConfig } from "../types";
+
+const makeHost = () => {
+  const starters = document.createElement("div");
+  return buildWelcomeHost(undefined, starters);
+};
+
+describe("welcome host", () => {
+  it("carries the permanent host attributes", () => {
+    const { host } = makeHost();
+    expect(host.hasAttribute("data-persona-welcome")).toBe(true);
+    expect(host.hasAttribute("data-persona-intro-card")).toBe(true);
+  });
+
+  it("gives the title and subtitle their tokenized typography classes", () => {
+    const { title, subtitle } = makeHost();
+    expect(title.tagName).toBe("H2");
+    expect(title.className).toBe("persona-welcome-title");
+    expect(subtitle.tagName).toBe("P");
+    expect(subtitle.className).toBe("persona-welcome-subtitle");
+  });
+
+  it("applies resolved config in place", () => {
+    const elements = makeHost();
+    applyWelcomeConfig(
+      elements,
+      resolveWelcomeConfig({
+        welcome: { title: "Hi", subtitle: "Scope", variant: "hero" },
+      } as AgentWidgetConfig)
+    );
+    expect(elements.title.textContent).toBe("Hi");
+    expect(elements.subtitle.textContent).toBe("Scope");
+    expect(elements.host.getAttribute("data-persona-welcome-variant")).toBe(
+      "hero"
+    );
+    expect(elements.host.getAttribute("data-persona-welcome-dismiss")).toBe(
+      "on-first-message"
+    );
+  });
+
+  it("tightens the body gap when the surface is hidden", () => {
+    const { host } = makeHost();
+    const body = document.createElement("div");
+    body.className = "persona-gap-6";
+    applyWelcomeVisibility(body, host, false);
+    expect(body.classList.contains("persona-gap-3")).toBe(true);
+    expect(body.classList.contains("persona-gap-6")).toBe(false);
+    applyWelcomeVisibility(body, host, true);
+    expect(body.classList.contains("persona-gap-6")).toBe(true);
+    expect(host.hidden).toBe(false);
+  });
+});
+
+describe("greeting bubble", () => {
+  it("renders the greeting as plain text, never markup", () => {
+    const host = buildGreetingHost();
+    renderWelcomeGreeting(host, "<b>bold</b> & fine", undefined);
+    expect(host.querySelector("b")).toBeNull();
+    expect(host.textContent).toBe("<b>bold</b> & fine");
+  });
+
+  it("clears and hides when the greeting is removed", () => {
+    const host = buildGreetingHost();
+    renderWelcomeGreeting(host, "Hi", undefined);
+    expect(host.hidden).toBe(false);
+    renderWelcomeGreeting(host, undefined, undefined);
+    expect(host.hidden).toBe(true);
+    expect(host.childElementCount).toBe(0);
+  });
+});
+
+describe("hero dismiss animation", () => {
+  it("runs on the Web Animations API and settles after it finishes", async () => {
+    const { host } = makeHost();
+    document.body.appendChild(host);
+    let resolveFinished: () => void = () => {};
+    const finished = new Promise<void>((resolve) => {
+      resolveFinished = resolve;
+    });
+    const animate = vi.fn(
+      (_keyframes: unknown, _options?: { fill?: string }) =>
+        ({ finished }) as unknown as Animation
+    );
+    (host as unknown as { animate: typeof animate }).animate = animate;
+
+    const onFinished = vi.fn();
+    const animation = animateWelcomeOut(host, onFinished);
+    expect(animate).toHaveBeenCalledTimes(1);
+    // `forwards`: `backwards` only fills the delay phase, so the element would
+    // flash back to opacity 1 after the keyframes end.
+    expect(animate.mock.calls[0]![1]?.fill).toBe("forwards");
+    expect(animation).toBeTruthy();
+    expect(onFinished).not.toHaveBeenCalled();
+
+    resolveFinished();
+    await finished;
+    await Promise.resolve();
+    expect(onFinished).toHaveBeenCalledWith(animation);
+    host.remove();
+  });
+
+  it("settles immediately without Web Animations support", () => {
+    const { host } = makeHost();
+    const onFinished = vi.fn();
+    expect(animateWelcomeOut(host, onFinished)).toBeNull();
+    expect(onFinished).toHaveBeenCalledWith(null);
+  });
+});