@runtypelabs/persona 4.15.0 → 4.16.0

package/src/components/launcher.ts

@@ -1,5 +1,5 @@
-import { createElement } from "../utils/dom";
-import { AgentWidgetConfig } from "../types";
+import { createElement, createNode, cx } from "../utils/dom";
+import { AgentWidgetConfig, AgentWidgetLauncherTeaserConfig } from "../types";
 import { positionMap } from "../utils/positioning";
 import { isDockedMountMode } from "../utils/dock";
 import { renderLucideIcon } from "../utils/icons";
@@ -240,3 +240,298 @@ export const createLauncherButton = (
     destroy
   };
 };
+
+/** Teaser bubble handle. `dismiss(true)` also writes the persisted flag. */
+export interface LauncherTeaser {
+  element: HTMLElement;
+  show: () => void;
+  dismiss: (persist: boolean) => void;
+}
+
+/** "auto" covers restored/hook-driven opens: they never persist the teaser flag. */
+export type LauncherOpenOrigin = "user" | "auto";
+
+export interface LauncherSurface {
+  /** Positioned wrapper. Sibling teaser + launcher live inside it. */
+  element: HTMLElement;
+  launcher: LauncherButton;
+  /** Null when no teaser is configured for the current config. */
+  teaser: LauncherTeaser | null;
+  /** Opening the panel consumes the teaser; closing never resurrects it. */
+  setPanelOpen: (open: boolean, origin?: LauncherOpenOrigin) => void;
+  update: (config: AgentWidgetConfig) => void;
+  destroy: () => void;
+}
+
+const TEASER_KEY_SUFFIX = "teaser-dismissed";
+
+/** Consumed teaser keys for this page load; also the blocked-storage fallback. */
+const teaserMemoryDismissed = new Set<string>();
+
+const teaserStorageKey = (config?: AgentWidgetConfig): string => {
+  const persist = config?.persistState;
+  const prefix =
+    (typeof persist === "object" ? persist?.keyPrefix : undefined) ?? "persona-";
+  return `${prefix}${TEASER_KEY_SUFFIX}`;
+};
+
+// localStorage access throws (not just fails) in Safari private mode and
+// partitioned iframes, so every access falls back to the in-memory set.
+const readTeaserDismissed = (key: string, useStorage: boolean): boolean => {
+  if (teaserMemoryDismissed.has(key)) return true;
+  if (!useStorage) return false;
+  try {
+    return window.localStorage.getItem(key) === "1";
+  } catch {
+    return false;
+  }
+};
+
+const writeTeaserDismissed = (key: string, useStorage: boolean): void => {
+  teaserMemoryDismissed.add(key);
+  if (!useStorage) return;
+  try {
+    window.localStorage.setItem(key, "1");
+  } catch {
+    /* blocked storage: the in-memory flag above is the fallback */
+  }
+};
+
+const prefersReducedMotion = (): boolean =>
+  typeof window !== "undefined" &&
+  typeof window.matchMedia === "function" &&
+  window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+const resolveTeaserConfig = (
+  config: AgentWidgetConfig | undefined
+): AgentWidgetLauncherTeaserConfig | null => {
+  const teaser = config?.launcher?.teaser;
+  if (!teaser || !teaser.text) return null;
+  if (config?.launcher?.enabled === false) return null;
+  if (isDockedMountMode(config ?? {})) return null;
+  return teaser;
+};
+
+/**
+ * Launcher wrapper owning the collapsed button and its optional teaser bubble.
+ * Both the critical `launcher.global.js` bundle and the full widget build the
+ * launcher through this, so teaser behavior and cleanup are identical on the
+ * eager and deferred paths.
+ */
+export const createLauncherSurface = (
+  config: AgentWidgetConfig | undefined,
+  onToggle: () => void
+): LauncherSurface => {
+  const wrapper = createElement("div", "persona-launcher-surface");
+  wrapper.setAttribute("data-persona-launcher-surface", "true");
+
+  let currentConfig: AgentWidgetConfig = config ?? {};
+  let teaserConfig: AgentWidgetLauncherTeaserConfig | null = null;
+  let teaserElement: HTMLElement | null = null;
+  let dismissButton: HTMLButtonElement | null = null;
+  let teaserTextButton: HTMLButtonElement | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let visible = false;
+  let shown = false;
+  let consumed = false;
+  let panelOpen = false;
+
+  const usesStorage = (): boolean =>
+    (teaserConfig?.frequency ?? "once") === "once" &&
+    currentConfig.persistState !== false;
+
+  const clearTimer = () => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+
+  const hideBubble = () => {
+    if (!teaserElement || !visible) return;
+    visible = false;
+    teaserElement.hidden = true;
+  };
+
+  const dismiss = (persist: boolean) => {
+    clearTimer();
+    consumed = true;
+    hideBubble();
+    writeTeaserDismissed(teaserStorageKey(currentConfig), persist && usesStorage());
+  };
+
+  /**
+   * Click-through and launcher clicks consume; only a seen teaser persists.
+   * An automatic open is never user intent, so it consumes in memory only.
+   */
+  const consumeForOpen = (origin: LauncherOpenOrigin) => {
+    if (!teaserConfig || consumed) return;
+    dismiss(origin === "user" && visible);
+  };
+
+  const show = () => {
+    timer = null;
+    if (!teaserElement || consumed || panelOpen) return;
+    shown = true;
+    visible = true;
+    teaserElement.hidden = false;
+    if (prefersReducedMotion() || typeof teaserElement.animate !== "function") return;
+    teaserElement.animate(
+      [
+        { opacity: "0", transform: "translateY(6px)" },
+        { opacity: "1", transform: "none" },
+      ],
+      { duration: 220, easing: "ease-out", fill: "backwards" }
+    );
+  };
+
+  const schedule = () => {
+    if (!teaserConfig || !teaserElement) return;
+    if (consumed || shown || panelOpen) return;
+    if (readTeaserDismissed(teaserStorageKey(currentConfig), usesStorage())) return;
+    clearTimer();
+    timer = setTimeout(show, Math.max(0, teaserConfig.delayMs ?? 0));
+  };
+
+  const handleTeaserClick = () => {
+    dismiss(usesStorage());
+    onToggle();
+  };
+
+  const handleDismissClick = (event: MouseEvent) => {
+    event.stopPropagation();
+    dismiss(usesStorage());
+  };
+
+  const handleLauncherToggle = () => {
+    consumeForOpen("user");
+    onToggle();
+  };
+
+  const launcher = createLauncherButton(config, handleLauncherToggle);
+
+  const removeTeaserElement = () => {
+    clearTimer();
+    teaserTextButton?.removeEventListener("click", handleTeaserClick);
+    dismissButton?.removeEventListener("click", handleDismissClick);
+    teaserElement?.remove();
+    teaserElement = null;
+    teaserTextButton = null;
+    dismissButton = null;
+    visible = false;
+  };
+
+  const buildTeaserElement = () => {
+    teaserTextButton = createNode("button", {
+      className: "persona-launcher-teaser-text",
+      attrs: { type: "button" },
+    });
+    teaserTextButton.addEventListener("click", handleTeaserClick);
+
+    dismissButton = createNode("button", {
+      className: "persona-launcher-teaser-dismiss",
+      attrs: { type: "button" },
+      text: "\u00d7",
+    });
+    dismissButton.addEventListener("click", handleDismissClick);
+
+    teaserElement = createNode(
+      "div",
+      {
+        className: "persona-launcher-teaser",
+        attrs: {
+          "data-persona-launcher-teaser": "true",
+          role: "status",
+          "aria-live": "polite",
+          hidden: "",
+        },
+      },
+      teaserTextButton,
+      dismissButton
+    );
+    wrapper.insertBefore(teaserElement, launcher.element);
+  };
+
+  /**
+   * The wrapper is `display: contents` until a teaser exists, so the launcher
+   * keeps its own fixed placement; with a teaser the wrapper takes over the
+   * corner and the button becomes static inside it.
+   */
+  const applyPlacement = () => {
+    const position = currentConfig.launcher?.position ?? "bottom-right";
+    const positionClass = positionMap[position] ?? positionMap["bottom-right"];
+
+    if (!teaserElement) {
+      wrapper.className = "persona-launcher-surface";
+      wrapper.removeAttribute("data-teaser");
+      wrapper.style.zIndex = "";
+      launcher.element.style.position = "";
+      return;
+    }
+
+    wrapper.className = cx("persona-launcher-surface", positionClass);
+    wrapper.setAttribute("data-teaser", position);
+    wrapper.style.zIndex = String(
+      currentConfig.launcher?.zIndex ?? DEFAULT_OVERLAY_Z_INDEX
+    );
+    launcher.element.style.position = "static";
+  };
+
+  const syncTeaser = (nextConfig: AgentWidgetConfig) => {
+    const next = resolveTeaserConfig(nextConfig);
+    teaserConfig = next;
+
+    if (!next) {
+      removeTeaserElement();
+      return;
+    }
+
+    // `shown` is deliberately not reset here: at most one appearance per load.
+    if (!teaserElement) buildTeaserElement();
+
+    teaserTextButton!.textContent = next.text;
+    dismissButton!.hidden = next.dismissible === false;
+    dismissButton!.setAttribute(
+      "aria-label",
+      next.dismissLabel ?? "Dismiss message"
+    );
+    schedule();
+  };
+
+  const update = (nextConfig: AgentWidgetConfig) => {
+    currentConfig = nextConfig;
+    launcher.update(nextConfig);
+    syncTeaser(nextConfig);
+    applyPlacement();
+  };
+
+  const setPanelOpen = (open: boolean, origin: LauncherOpenOrigin = "user") => {
+    panelOpen = open;
+    if (!open) return;
+    consumeForOpen(origin);
+  };
+
+  const destroy = () => {
+    removeTeaserElement();
+    launcher.destroy();
+    wrapper.remove();
+  };
+
+  wrapper.appendChild(launcher.element);
+  if (config) {
+    syncTeaser(config);
+    applyPlacement();
+  }
+
+  return {
+    element: wrapper,
+    launcher,
+    get teaser(): LauncherTeaser | null {
+      if (!teaserElement) return null;
+      return { element: teaserElement, show, dismiss };
+    },
+    setPanelOpen,
+    update,
+    destroy,
+  };
+};

package/src/components/panel.ts

@@ -10,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;
@@ -151,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;
@@ -194,6 +209,30 @@ const createSuggestionHost = (
   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
@@ -282,38 +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 starterSuggestions = createSuggestionHost("starter");
-  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,
-    starterSuggestions
-  );
+  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, true);
   if (contentMaxWidth) {
     messagesWrapper.style.maxWidth = contentMaxWidth;
     messagesWrapper.style.marginLeft = "auto";
@@ -321,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, transcriptSuggestions);
+  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`),
@@ -368,6 +385,9 @@ const buildComposerBarPanel = (
     micButtonWrapper: composerElements.micButtonWrapper,
     composerForm: composerElements.composerForm,
     statusText: composerElements.statusText,
+    welcomeHost,
+    welcomeIconHolder: welcome.iconHolder,
+    greetingHost,
     introTitle,
     introSubtitle,
     closeButton,
@@ -424,45 +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.",
-  });
-  const starterSuggestions = createSuggestionHost("starter");
-  // 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,
-    starterSuggestions
-  );
+  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";
@@ -470,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, transcriptSuggestions);
+  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.
@@ -535,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/suggestions.test.ts

@@ -198,6 +198,46 @@ describe("per-item icon color", () => {
   });
 });
 
+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,