@runtypelabs/persona 4.14.0 → 4.16.0

package/src/components/messages.ts

@@ -9,7 +9,10 @@ import {
   isAskUserQuestionMessage,
   removeAskUserQuestionSheet,
 } from "./ask-user-question-bubble";
-import { isSuggestRepliesMessage } from "../suggest-replies-tool";
+import {
+  isSuggestRepliesMessage,
+  resolveFollowUpsFeature,
+} from "../suggest-replies-tool";
 
 export const renderMessages = (
   container: HTMLElement,
@@ -43,7 +46,7 @@ export const renderMessages = (
       return;
     } else if (
       isSuggestRepliesMessage(message) &&
-      config?.features?.suggestReplies?.enabled !== false
+      resolveFollowUpsFeature(config).enabled
     ) {
       // No transcript bubble: the chips above the composer are the only UI.
       // When the feature is disabled the message falls through to the generic

package/src/components/panel.ts

@@ -1,6 +1,7 @@
 import { createElement, createNode } from "../utils/dom";
 import { DEFAULT_FLOATING_LAUNCHER_WIDTH } from "../defaults";
-import { AgentWidgetConfig } from "../types";
+import { AgentWidgetConfig, AgentWidgetSuggestionSurface } from "../types";
+import { suggestionSurfaceAttr } from "./suggestions";
 import { positionMap } from "../utils/positioning";
 import { isComposerBarMountMode, isDockedMountMode } from "../utils/dock";
 import { DEFAULT_OVERLAY_Z_INDEX } from "../utils/constants";
@@ -9,6 +10,16 @@ import { buildHeaderWithLayout } from "./header-layouts";
 import { createCloseButton, createClearChatButton } from "./header-parts";
 import { buildComposer, ComposerElements } from "./composer-builder";
 import { buildPillComposer, buildPillPeekBanner } from "./pill-composer-builder";
+import {
+  applyWelcomeConfig,
+  applyWelcomeVisibility,
+  buildGreetingHost,
+  buildWelcomeHost,
+  renderWelcomeGreeting,
+  WelcomeHostElements,
+} from "./welcome";
+import { isWelcomeVisible, resolveWelcomeConfig } from "../welcome";
+import { resolveContentMaxWidth } from "../utils/content-width";
 
 export interface PanelWrapper {
   wrapper: HTMLElement;
@@ -132,6 +143,10 @@ export interface PanelElements {
   container: HTMLElement;
   body: HTMLElement;
   messagesWrapper: HTMLElement;
+  /** Starter prompts rendered inside the welcome card. */
+  starterSuggestions: HTMLElement;
+  /** Follow-up suggestions rendered after the transcript. */
+  transcriptSuggestions: HTMLElement;
   /**
    * Absolute-positioned slot above the composer footer. Interactive sheets
    * (e.g. the answer-pill sheet for the ask_user_question tool) mount here
@@ -146,6 +161,11 @@ export interface PanelElements {
   micButtonWrapper: HTMLElement | null;
   composerForm: HTMLFormElement;
   statusText: HTMLElement;
+  /** Permanent welcome host: variant and visibility change on it in place. */
+  welcomeHost: HTMLElement;
+  welcomeIconHolder: HTMLElement;
+  /** Display-only greeting bubble host, pinned above the transcript. */
+  greetingHost: HTMLElement;
   introTitle: HTMLElement;
   introSubtitle: HTMLElement;
   closeButton: HTMLButtonElement;
@@ -178,6 +198,41 @@ export interface PanelElements {
   peekTextNode?: HTMLElement;
 }
 
+const createSuggestionHost = (
+  surface: AgentWidgetSuggestionSurface
+): HTMLElement => {
+  const host = createNode("div", {
+    className: "persona-suggestions",
+    attrs: { "data-persona-suggestions": suggestionSurfaceAttr(surface) },
+  });
+  host.hidden = true;
+  return host;
+};
+
+/**
+ * Welcome surface for either panel builder: permanent host plus the greeting
+ * host that sits between it and the transcript.
+ */
+const buildWelcomeSurface = (
+  config: AgentWidgetConfig | undefined,
+  body: HTMLElement
+): { welcome: WelcomeHostElements; greetingHost: HTMLElement } => {
+  const starterSuggestions = createSuggestionHost("starter");
+  const welcome = buildWelcomeHost(config, starterSuggestions, {
+    flatShadow: isDockedMountMode(config),
+  });
+  const resolved = resolveWelcomeConfig(config);
+  applyWelcomeConfig(welcome, resolved);
+  applyWelcomeVisibility(
+    body,
+    welcome.host,
+    isWelcomeVisible(resolved, config?.initialMessages)
+  );
+  const greetingHost = buildGreetingHost();
+  renderWelcomeGreeting(greetingHost, resolved.message, config);
+  return { welcome, greetingHost };
+};
+
 /**
  * Composer-bar panel: minimal close-only header (× in the top-right of the
  * chat chrome). The pill (`footer`) and `peekBanner` are NOT children of
@@ -266,35 +321,17 @@ const buildComposerBarPanel = (
   // when streaming content first overflows and the scrollbar appears.
   body.style.setProperty("scrollbar-gutter", "stable");
 
-  const introTitle = createNode("h2", {
-    className: "persona-text-lg persona-font-semibold persona-text-persona-primary",
-    text: config?.copy?.welcomeTitle ?? "Hello 👋",
-  });
-  const introSubtitle = createNode("p", {
-    className: "persona-mt-2 persona-text-sm persona-text-persona-muted",
-    text:
-      config?.copy?.welcomeSubtitle ??
-      "Ask anything about your account or products.",
-  });
-  const introCard = createNode(
-    "div",
-    {
-      className: "persona-rounded-2xl persona-p-6",
-      attrs: { "data-persona-intro-card": "" },
-      style: {
-        background: "var(--persona-intro-card-bg, transparent)",
-        boxShadow: "var(--persona-intro-card-shadow, none)",
-      },
-    },
-    introTitle,
-    introSubtitle
-  );
+  const { welcome, greetingHost } = buildWelcomeSurface(config, body);
+  const { host: welcomeHost, title: introTitle, subtitle: introSubtitle } =
+    welcome;
+  const starterSuggestions = welcome.starterSuggestions;
 
   const messagesWrapper = createElement(
     "div",
-    "persona-flex persona-flex-col persona-gap-3"
+    "persona-widget-messages persona-flex persona-flex-col persona-gap-3"
   );
-  const contentMaxWidth = config?.layout?.contentMaxWidth;
+  const transcriptSuggestions = createSuggestionHost("followUp");
+  const contentMaxWidth = resolveContentMaxWidth(config, true);
   if (contentMaxWidth) {
     messagesWrapper.style.maxWidth = contentMaxWidth;
     messagesWrapper.style.marginLeft = "auto";
@@ -302,13 +339,12 @@ const buildComposerBarPanel = (
     messagesWrapper.style.width = "100%";
   }
 
-  const showWelcomeCard = config?.copy?.showWelcomeCard !== false;
-  if (!showWelcomeCard) {
-    introCard.style.display = "none";
-    body.classList.remove("persona-gap-6");
-    body.classList.add("persona-gap-3");
-  }
-  body.append(introCard, messagesWrapper);
+  body.append(
+    welcomeHost,
+    greetingHost,
+    messagesWrapper,
+    transcriptSuggestions
+  );
 
   // Composer overlay (interactive sheets like ask_user_question slide up here).
   // Anchored to the bottom of the container (which is `position: relative`),
@@ -338,6 +374,8 @@ const buildComposerBarPanel = (
     container,
     body,
     messagesWrapper,
+    starterSuggestions,
+    transcriptSuggestions,
     composerOverlay,
     suggestions: composerElements.suggestions,
     textarea: composerElements.textarea,
@@ -347,6 +385,9 @@ const buildComposerBarPanel = (
     micButtonWrapper: composerElements.micButtonWrapper,
     composerForm: composerElements.composerForm,
     statusText: composerElements.statusText,
+    welcomeHost,
+    welcomeIconHolder: welcome.iconHolder,
+    greetingHost,
     introTitle,
     introSubtitle,
     closeButton,
@@ -403,42 +444,18 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
   // when streaming content first overflows and the scrollbar appears.
   body.style.setProperty("scrollbar-gutter", "stable");
 
-  const introTitle = createNode("h2", {
-    className: "persona-text-lg persona-font-semibold persona-text-persona-primary",
-    text: config?.copy?.welcomeTitle ?? "Hello 👋",
-  });
-  const introSubtitle = createNode("p", {
-    className: "persona-mt-2 persona-text-sm persona-text-persona-muted",
-    text:
-      config?.copy?.welcomeSubtitle ??
-      "Ask anything about your account or products.",
-  });
-  // Background and box-shadow flow through the themable `components.introCard`
-  // tokens (--persona-intro-card-bg / --persona-intro-card-shadow); both
-  // default to flat (transparent / none). Docked mode always stays flat,
-  // even when a theme sets an introCard shadow.
-  const introCard = createNode(
-    "div",
-    {
-      className: "persona-rounded-2xl persona-p-6",
-      attrs: { "data-persona-intro-card": "" },
-      style: {
-        background: "var(--persona-intro-card-bg, transparent)",
-        boxShadow: isDockedMountMode(config)
-          ? "none"
-          : "var(--persona-intro-card-shadow, none)",
-      },
-    },
-    introTitle,
-    introSubtitle
-  );
+  const { welcome, greetingHost } = buildWelcomeSurface(config, body);
+  const { host: welcomeHost, title: introTitle, subtitle: introSubtitle } =
+    welcome;
+  const starterSuggestions = welcome.starterSuggestions;
 
   const messagesWrapper = createElement(
     "div",
-    "persona-flex persona-flex-col persona-gap-3"
+    "persona-widget-messages persona-flex persona-flex-col persona-gap-3"
   );
+  const transcriptSuggestions = createSuggestionHost("followUp");
 
-  const contentMaxWidth = config?.layout?.contentMaxWidth;
+  const contentMaxWidth = resolveContentMaxWidth(config, false);
   if (contentMaxWidth) {
     messagesWrapper.style.maxWidth = contentMaxWidth;
     messagesWrapper.style.marginLeft = "auto";
@@ -446,13 +463,12 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     messagesWrapper.style.width = "100%";
   }
 
-  const showWelcomeCard = config?.copy?.showWelcomeCard !== false;
-  if (!showWelcomeCard) {
-    introCard.style.display = "none";
-    body.classList.remove("persona-gap-6");
-    body.classList.add("persona-gap-3");
-  }
-  body.append(introCard, messagesWrapper);
+  body.append(
+    welcomeHost,
+    greetingHost,
+    messagesWrapper,
+    transcriptSuggestions
+  );
 
   // composer-bar mode early-returned above with its own pill builder; this
   // path always uses the standard column-stacked composer card.
@@ -500,6 +516,8 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     container,
     body,
     messagesWrapper,
+    starterSuggestions,
+    transcriptSuggestions,
     composerOverlay,
     suggestions: composerElements.suggestions,
     textarea: composerElements.textarea,
@@ -509,6 +527,9 @@ export const buildPanel = (config?: AgentWidgetConfig, showClose = true): PanelE
     micButtonWrapper: composerElements.micButtonWrapper,
     composerForm: composerElements.composerForm,
     statusText: composerElements.statusText,
+    welcomeHost,
+    welcomeIconHolder: welcome.iconHolder,
+    greetingHost,
     introTitle,
     introSubtitle,
     closeButton: headerElements.closeButton,

package/src/components/pill-composer-builder.test.ts

@@ -79,6 +79,24 @@ describe("buildPillComposer (single-row pill composer)", () => {
     expect(formChildren[2]).toBe(elements.rightActions);
   });
 
+  it("keeps its 100px max-height cap, even under a themed line height", () => {
+    const elements = buildPillComposer({ config: { apiUrl: "/api" } });
+    expect(elements.textarea.style.maxHeight).toBe("100px");
+
+    // A themed line height must not re-derive the cap: the pill's explicit
+    // post-construction override wins over the 3-line default.
+    elements.textarea.style.lineHeight = "24px";
+    document.body.appendChild(elements.textarea);
+    Object.defineProperty(elements.textarea, "scrollHeight", {
+      configurable: true,
+      value: 10000,
+    });
+    elements.textarea.dispatchEvent(new Event("input"));
+    expect(elements.textarea.style.maxHeight).toBe("100px");
+    expect(elements.textarea.style.height).toBe("100px");
+    document.body.removeChild(elements.textarea);
+  });
+
   it("returns null for optional controls when disabled (matching ComposerElements contract)", () => {
     const elements = buildPillComposer({ config: { apiUrl: "/api" } });
     expect(elements.attachmentButton).toBeNull();

package/src/components/suggestions.test.ts

@@ -0,0 +1,273 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createSuggestions } from "./suggestions";
+import type { AgentWidgetSession } from "../session";
+
+const makeSession = (): AgentWidgetSession =>
+  ({
+    isStreaming: () => false,
+    getMessages: () => [],
+    sendMessage: () => {},
+  }) as unknown as AgentWidgetSession;
+
+const setup = () => {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const textarea = document.createElement("textarea");
+  document.body.appendChild(textarea);
+  return {
+    container,
+    textarea,
+    manager: createSuggestions(container),
+    session: makeSession(),
+  };
+};
+
+const withAnimate = (): ReturnType<typeof vi.fn> => {
+  const animate = vi.fn(() => ({}));
+  Object.defineProperty(Element.prototype, "animate", {
+    value: animate,
+    configurable: true,
+    writable: true,
+  });
+  return animate;
+};
+
+afterEach(() => {
+  Reflect.deleteProperty(Element.prototype, "animate");
+  vi.unstubAllGlobals();
+  document.body.replaceChildren();
+});
+
+describe("suggestion entrance animation", () => {
+  it("animates each item once for a newly shown set", () => {
+    const animate = withAnimate();
+    const { manager, session, textarea } = setup();
+
+    manager.render(["One", "Two"], session, textarea, [], undefined, {
+      variant: "card",
+    });
+
+    expect(animate).toHaveBeenCalledTimes(2);
+    const [, secondOptions] = animate.mock.calls[1] as [
+      unknown,
+      { delay: number; duration: number; fill: string },
+    ];
+    expect(secondOptions.delay).toBe(60);
+    expect(secondOptions.duration).toBe(250);
+    expect(secondOptions.fill).toBe("backwards");
+  });
+
+  it("does not re-animate when render repeats the same items", () => {
+    const animate = withAnimate();
+    const { manager, session, textarea } = setup();
+    const items = ["One", "Two"];
+
+    manager.render(items, session, textarea, [], undefined, {
+      variant: "card",
+    });
+    manager.render(items, session, textarea, [], undefined, {
+      variant: "card",
+    });
+
+    expect(animate).toHaveBeenCalledTimes(2);
+  });
+
+  it("animates again once the item set changes", () => {
+    const animate = withAnimate();
+    const { manager, session, textarea } = setup();
+
+    manager.render(["One"], session, textarea, [], undefined, {
+      variant: "card",
+    });
+    manager.render(["Two"], session, textarea, [], undefined, {
+      variant: "card",
+    });
+
+    expect(animate).toHaveBeenCalledTimes(2);
+  });
+
+  it("skips the animation under prefers-reduced-motion", () => {
+    const animate = withAnimate();
+    vi.stubGlobal(
+      "matchMedia",
+      vi.fn(() => ({ matches: true }))
+    );
+    const { manager, session, textarea } = setup();
+
+    manager.render(["One", "Two"], session, textarea, [], undefined, {
+      variant: "card",
+    });
+
+    expect(animate).not.toHaveBeenCalled();
+  });
+
+  it("still renders when the platform has no Web Animations API", () => {
+    const { container, manager, session, textarea } = setup();
+
+    expect(typeof Element.prototype.animate).toBe("undefined");
+    expect(() =>
+      manager.render(["One", "Two"], session, textarea, [], undefined, {
+        variant: "card",
+      })
+    ).not.toThrow();
+    expect(container.querySelectorAll(".persona-suggestion")).toHaveLength(2);
+  });
+});
+
+describe("per-item icon color", () => {
+  const iconOf = (container: HTMLElement): SVGElement =>
+    container.querySelector(".persona-suggestion__icon") as SVGElement;
+
+  it("tints only the icon element", () => {
+    const { manager, session, textarea, container } = setup();
+
+    manager.render(
+      [{ label: "Compare plans", icon: "dollar-sign", iconColor: "#16a34a" }],
+      session,
+      textarea,
+      [],
+      undefined,
+      { variant: "card" }
+    );
+
+    const button = container.querySelector("button") as HTMLButtonElement;
+    expect(iconOf(container).style.color).toBe("rgb(22, 163, 74)");
+    expect(button.style.color).toBe("");
+    expect(button.style.borderColor).toBe("");
+    expect(button.style.background).toBe("");
+    expect(
+      (container.querySelector(".persona-suggestion__label") as HTMLElement)
+        .style.color
+    ).toBe("");
+  });
+
+  it("wins over the emphasis-primary icon tint without recoloring the button", () => {
+    const { manager, session, textarea, container } = setup();
+
+    manager.render(
+      [
+        {
+          label: "Compare plans",
+          icon: "dollar-sign",
+          iconColor: "#16a34a",
+          emphasis: "primary",
+        },
+      ],
+      session,
+      textarea,
+      [],
+      undefined,
+      { variant: "card" }
+    );
+
+    const button = container.querySelector("button") as HTMLButtonElement;
+    expect(button.dataset.emphasis).toBe("primary");
+    expect(iconOf(container).style.color).toBe("rgb(22, 163, 74)");
+  });
+
+  it("leaves the icon in currentColor when iconColor is absent", () => {
+    const { manager, session, textarea, container } = setup();
+
+    manager.render(
+      [{ label: "Compare plans", icon: "dollar-sign" }],
+      session,
+      textarea,
+      [],
+      undefined,
+      { variant: "card" }
+    );
+
+    const icon = iconOf(container);
+    expect(icon.style.color).toBe("");
+    expect(icon.getAttribute("stroke")).toBe("currentColor");
+  });
+
+  it("leaves string shorthand items unaffected", () => {
+    const { manager, session, textarea, container } = setup();
+
+    manager.render(["Compare plans"], session, textarea, [], undefined, {
+      variant: "card",
+    });
+
+    expect(container.querySelector(".persona-suggestion__icon")).toBeNull();
+    const button = container.querySelector("button") as HTMLButtonElement;
+    expect(button.style.color).toBe("");
+  });
+});
+
+describe("description rendering per variant", () => {
+  const items = [
+    {
+      label: "Track an order",
+      description: "Look up status by order number",
+    },
+  ];
+
+  it("keeps the chip variant to a single-line label", () => {
+    const { manager, session, textarea, container } = setup();
+
+    manager.render(items, session, textarea, [], undefined, {
+      variant: "chip",
+    });
+
+    expect(
+      container.querySelector(".persona-suggestion__description")
+    ).toBeNull();
+    expect(
+      (container.querySelector(".persona-suggestion__label") as HTMLElement)
+        .textContent
+    ).toBe("Track an order");
+  });
+
+  it("renders the description in the card and list variants", () => {
+    const { manager, session, textarea, container } = setup();
+
+    for (const variant of ["card", "list"] as const) {
+      manager.render(items, session, textarea, [], undefined, { variant });
+      expect(
+        (
+          container.querySelector(
+            ".persona-suggestion__description"
+          ) as HTMLElement
+        ).textContent
+      ).toBe("Look up status by order number");
+    }
+  });
+});
+
+describe("legacy suggestionChipsConfig scoping", () => {
+  const chipsConfig = {
+    fontFamily: "sans-serif" as const,
+    fontWeight: "500",
+    paddingX: "12px",
+    paddingY: "6px",
+  };
+
+  it("applies inline chip styles to the chip variant", () => {
+    const { manager, session, textarea, container } = setup();
+
+    manager.render(["One"], session, textarea, [], chipsConfig, {
+      variant: "chip",
+    });
+
+    const button = container.querySelector("button") as HTMLButtonElement;
+    expect(button.style.paddingLeft).toBe("12px");
+    expect(button.style.paddingTop).toBe("6px");
+    expect(button.style.fontWeight).toBe("500");
+  });
+
+  it("does not let chip config override card and list padding tokens", () => {
+    const { manager, session, textarea, container } = setup();
+
+    for (const variant of ["card", "list"] as const) {
+      manager.render(["One"], session, textarea, [], chipsConfig, { variant });
+      const button = container.querySelector("button") as HTMLButtonElement;
+      expect(button.style.paddingLeft).toBe("");
+      expect(button.style.paddingTop).toBe("");
+      expect(button.style.fontFamily).toBe("");
+    }
+  });
+});