@runtypelabs/persona 4.13.0 → 4.15.0

package/src/components/suggestions.ts

@@ -1,11 +1,37 @@
-import { createElement } from "../utils/dom";
+import { createElement, createNode } from "../utils/dom";
+import { renderLucideIcon } from "../utils/icons";
 import { AgentWidgetSession } from "../session";
-import { AgentWidgetMessage, AgentWidgetSuggestionChipsConfig } from "../types";
+import {
+  AgentWidgetConfig,
+  AgentWidgetMessage,
+  AgentWidgetResolvedSuggestion,
+  AgentWidgetSuggestion,
+  AgentWidgetSuggestionChipsConfig,
+  AgentWidgetSuggestionBehavior,
+  AgentWidgetSuggestionSource,
+  AgentWidgetSuggestionSurface,
+  AgentWidgetSuggestionVariant,
+} from "../types";
+import type { AgentWidgetPlugin } from "../plugins/types";
+
+export type NormalizedSuggestion = Omit<
+  AgentWidgetResolvedSuggestion,
+  "behavior"
+> & {
+  behavior?: AgentWidgetSuggestionBehavior;
+};
+
+/** DOM attribute values stay kebab-case; TS surface values stay camelCase. */
+export const suggestionSurfaceAttr = (
+  surface: AgentWidgetSuggestionSurface
+): string => (surface === "followUp" ? "follow-up" : surface);
 
 export interface SuggestionButtons {
   buttons: HTMLButtonElement[];
+  elements: HTMLElement[];
+  destroy: () => void;
   render: (
-    chips: string[] | undefined,
+    items: AgentWidgetSuggestion[] | undefined,
     session: AgentWidgetSession,
     textarea: HTMLTextAreaElement,
     messages?: AgentWidgetMessage[],
@@ -15,113 +41,463 @@ export interface SuggestionButtons {
 }
 
 export interface SuggestionRenderOptions {
+  /** Whether these are welcome starters or agent-produced follow-ups. */
+  surface?: AgentWidgetSuggestionSurface;
+  /** Presentation density. */
+  variant?: AgentWidgetSuggestionVariant;
+  /** Default click behavior, overridable per item. */
+  behavior?: AgentWidgetSuggestionBehavior;
+  /** Chip overflow behavior. */
+  overflow?: "scroll" | "wrap";
+  /** Renderer cap. */
+  maxItems?: number;
   /**
-   * Chips pushed by the agent's `suggest_replies` tool rather than the
-   * static `suggestionChips` config. Skips the before-first-user-message
-   * gate (the caller already applied the latest-turn visibility rule) and
-   * dispatches `persona:suggestReplies:*` DOM events.
+   * Who produced these items. Defaults to `config`; `agent` and `host` mark
+   * the follow-up surface, which keeps the legacy `persona:suggestReplies:*`
+   * events and skips the starters' before-first-user-message gate.
    */
-  agentPushed?: boolean;
+  source?: AgentWidgetSuggestionSource;
+  /** Live widget config exposed to plugin hooks. */
+  config?: AgentWidgetConfig;
+  /** Priority-sorted plugins active for this widget instance. */
+  plugins?: readonly AgentWidgetPlugin[];
 }
 
+export const normalizeSuggestion = (
+  item: AgentWidgetSuggestion,
+  index = 0
+): NormalizedSuggestion | null => {
+  if (typeof item === "string") {
+    const value = item.trim();
+    if (!value) return null;
+    return {
+      id: value,
+      label: value,
+      prompt: value,
+      emphasis: "default",
+    };
+  }
+
+  const label = item.label.trim();
+  if (!label) return null;
+  const prompt = item.prompt?.trim() || label;
+  return {
+    id: item.id?.trim() || prompt || `suggestion-${index}`,
+    label,
+    prompt,
+    description: item.description?.trim() || undefined,
+    icon: item.icon,
+    iconColor: item.iconColor?.trim() || undefined,
+    behavior: item.behavior,
+    emphasis: item.emphasis ?? "default",
+  };
+};
+
+const fontFamilyValue = (
+  family: "sans-serif" | "serif" | "mono"
+): string => {
+  switch (family) {
+    case "serif":
+      return 'Georgia, "Times New Roman", Times, serif';
+    case "mono":
+      return '"Courier New", Courier, "Lucida Console", Monaco, monospace';
+    default:
+      return '-apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif';
+  }
+};
+
+// Module-level, keyed on the widget config: one widget owns several suggestion
+// managers, so a per-instance flag hints once per surface instead of once.
+const hintedOverflowVariant = new WeakSet<AgentWidgetConfig>();
+
+const prefersReducedMotion = (): boolean =>
+  typeof window !== "undefined" &&
+  typeof window.matchMedia === "function" &&
+  window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+/**
+ * Staggered fade-up for a newly shown set. WAAPI, not CSS transitions: morph
+ * re-renders strip post-render CSS state, and a running animation survives.
+ */
+const animateEntrance = (elements: readonly HTMLElement[]): void => {
+  if (prefersReducedMotion()) return;
+  elements.forEach((element, index) => {
+    if (typeof element.animate !== "function") return;
+    element.animate(
+      [
+        { opacity: "0", transform: "translateY(4px)" },
+        { opacity: "1", transform: "none" },
+      ],
+      {
+        duration: 250,
+        delay: index * 60,
+        easing: "ease-out",
+        fill: "backwards",
+      }
+    );
+  });
+};
+
 export const createSuggestions = (container: HTMLElement): SuggestionButtons => {
   const suggestionButtons: HTMLButtonElement[] = [];
-  // render() runs on every message change; only announce agent-pushed chips
-  // when the visible set actually changes, not on each re-render pass.
-  let lastAgentShownKey: string | null = null;
+  const suggestionElements: HTMLElement[] = [];
+  let lastShownKey: string | null = null;
+  let overflowFrame: number | null = null;
+
+  const clearOverflowAffordance = () => {
+    container.removeAttribute("data-scroll-left");
+    container.removeAttribute("data-scroll-right");
+  };
+
+  const syncOverflowAffordance = () => {
+    overflowFrame = null;
+    if (
+      container.hidden ||
+      container.dataset.variant !== "chip" ||
+      container.dataset.overflow !== "scroll"
+    ) {
+      clearOverflowAffordance();
+      return;
+    }
+
+    const maxScroll = Math.max(0, container.scrollWidth - container.clientWidth);
+    if (maxScroll <= 1) {
+      clearOverflowAffordance();
+      return;
+    }
+
+    const isRtl = getComputedStyle(container).direction === "rtl";
+    const position = Math.min(
+      maxScroll,
+      Math.max(0, Math.abs(container.scrollLeft))
+    );
+    // Scroll snap and the scroller's 2px visual padding can settle a browser
+    // just off either boundary. Treat that subpixel-sized drift as the edge so
+    // a misleading opposite fade does not appear before the user scrolls.
+    const edgeTolerance = 4;
+    const atStart = position <= edgeTolerance;
+    const atEnd = position >= maxScroll - edgeTolerance;
+    const hasLeftOverflow = isRtl ? !atEnd : !atStart;
+    const hasRightOverflow = isRtl ? !atStart : !atEnd;
+
+    container.toggleAttribute("data-scroll-left", hasLeftOverflow);
+    container.toggleAttribute("data-scroll-right", hasRightOverflow);
+  };
+
+  const scheduleOverflowAffordance = () => {
+    if (overflowFrame !== null || typeof requestAnimationFrame !== "function") {
+      if (typeof requestAnimationFrame !== "function") {
+        syncOverflowAffordance();
+      }
+      return;
+    }
+    overflowFrame = requestAnimationFrame(syncOverflowAffordance);
+  };
+
+  container.addEventListener("scroll", scheduleOverflowAffordance, {
+    passive: true,
+  });
+  const resizeObserver =
+    typeof ResizeObserver === "function"
+      ? new ResizeObserver(scheduleOverflowAffordance)
+      : null;
+  resizeObserver?.observe(container);
 
   const render = (
-    chips: string[] | undefined,
+    items: AgentWidgetSuggestion[] | undefined,
     session: AgentWidgetSession,
     textarea: HTMLTextAreaElement,
     messages?: AgentWidgetMessage[],
     chipsConfig?: AgentWidgetSuggestionChipsConfig,
     opts?: SuggestionRenderOptions
   ) => {
-    container.innerHTML = "";
+    container.replaceChildren();
     suggestionButtons.length = 0;
-    const agentPushed = opts?.agentPushed === true;
-    if (!agentPushed) lastAgentShownKey = null;
-    if (!chips || !chips.length) return;
-
-    // Hide config suggestions after the first user message is sent.
-    // Agent-pushed chips skip this gate: their visibility is the caller's
-    // latest-turn rule (last suggest_replies call with no user message after).
-    // Use provided messages or get from session
-    if (!agentPushed) {
-      const messagesToCheck = messages ?? (session ? session.getMessages() : []);
-      const hasUserMessage = messagesToCheck.some((msg) => msg.role === "user");
-      if (hasUserMessage) return;
+    suggestionElements.length = 0;
+
+    const source: AgentWidgetSuggestionSource = opts?.source ?? "config";
+    const surface =
+      opts?.surface ?? (source === "config" ? "starter" : "followUp");
+    // Follow-ups render mid-conversation and keep the legacy event names.
+    const isFollowUp = surface === "followUp";
+    const variant = opts?.variant ?? "chip";
+    const behavior = opts?.behavior ?? "send";
+    const overflow = opts?.overflow ?? "wrap";
+    const widgetConfig = opts?.config ?? ({} as AgentWidgetConfig);
+    const plugins = opts?.plugins ?? [];
+    const maxItems =
+      typeof opts?.maxItems === "number"
+        ? Math.max(0, Math.floor(opts.maxItems))
+        : undefined;
+
+    // `data-overflow` is styled under the chip variant only; hint once so the
+    // no-op is discoverable without reading the CSS.
+    const surfaceKey = isFollowUp ? "followUps" : "starters";
+    if (
+      !hintedOverflowVariant.has(widgetConfig) &&
+      widgetConfig.debug === true &&
+      variant !== "chip" &&
+      widgetConfig.suggestions?.[surfaceKey]?.overflow !== undefined
+    ) {
+      hintedOverflowVariant.add(widgetConfig);
+      console.info(
+        `[persona] suggestions.${surfaceKey}.overflow applies to the "chip" variant only; the "${variant}" variant manages its own stacking.`
+      );
     }
 
-    const fragment = document.createDocumentFragment();
-    const streaming = session ? session.isStreaming() : false;
-
-    // Get font family mapping function
-    const getFontFamilyValue = (family: "sans-serif" | "serif" | "mono"): string => {
-      switch (family) {
-        case "serif":
-          return 'Georgia, "Times New Roman", Times, serif';
-        case "mono":
-          return '"Courier New", Courier, "Lucida Console", Monaco, monospace';
-        case "sans-serif":
-        default:
-          return '-apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif';
-      }
-    };
+    // Normalize before transform: hooks see resolved items and may return the
+    // loose shape, so re-resolution only fills a missing per-item behavior.
+    const resolveAll = (
+      list: AgentWidgetSuggestion[]
+    ): AgentWidgetResolvedSuggestion[] =>
+      list
+        .map(normalizeSuggestion)
+        .filter((item): item is NormalizedSuggestion => item !== null)
+        .map((item) => ({ ...item, behavior: item.behavior ?? behavior }));
 
-    chips.forEach((chip) => {
-      const btn = createElement(
-        "button",
-        "persona-rounded-button persona-bg-persona-surface persona-px-3 persona-py-1.5 persona-text-xs persona-font-medium persona-text-persona-primary hover:persona-opacity-80 persona-cursor-pointer persona-border persona-border-persona-border"
-      ) as HTMLButtonElement;
-      btn.type = "button";
-      btn.textContent = chip;
-      btn.disabled = streaming;
-
-      // Apply typography settings
-      if (chipsConfig?.fontFamily) {
-        btn.style.fontFamily = getFontFamilyValue(chipsConfig.fontFamily);
-      }
-      if (chipsConfig?.fontWeight) {
-        btn.style.fontWeight = chipsConfig.fontWeight;
-      }
+    let resolved = resolveAll(items ?? []);
+    plugins.forEach((plugin) => {
+      if (!plugin.transformSuggestions) return;
+      resolved = resolveAll(
+        plugin.transformSuggestions({
+          suggestions: resolved.map((item) => ({ ...item })),
+          surface,
+          source,
+          config: widgetConfig,
+        })
+      );
+    });
 
-      // Apply padding settings
-      if (chipsConfig?.paddingX) {
-        btn.style.paddingLeft = chipsConfig.paddingX;
-        btn.style.paddingRight = chipsConfig.paddingX;
-      }
-      if (chipsConfig?.paddingY) {
-        btn.style.paddingTop = chipsConfig.paddingY;
-        btn.style.paddingBottom = chipsConfig.paddingY;
+    // The cap applies once, after the full transform chain.
+    const normalized =
+      maxItems === undefined ? resolved : resolved.slice(0, maxItems);
+
+    if (!normalized.length) {
+      container.hidden = true;
+      lastShownKey = null;
+      clearOverflowAffordance();
+      return;
+    }
+
+    if (!isFollowUp) {
+      const messagesToCheck = messages ?? session.getMessages();
+      if (messagesToCheck.some((message) => message.role === "user")) {
+        container.hidden = true;
+        lastShownKey = null;
+        return;
       }
+    }
 
-      btn.addEventListener("click", () => {
-        if (!session || session.isStreaming()) return;
-        textarea.value = "";
-        if (agentPushed) {
+    container.hidden = false;
+    container.classList.add("persona-suggestions");
+    container.dataset.personaSuggestionSurface = suggestionSurfaceAttr(surface);
+    container.dataset.variant = variant;
+    container.dataset.overflow = overflow;
+
+    const fragment = document.createDocumentFragment();
+    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: chip },
+              detail: { suggestion: item.prompt },
               bubbles: true,
               composed: true,
             })
           );
         }
-        session.sendMessage(chip);
+        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");
+      }
+
+      fragment.appendChild(element);
+      suggestionElements.push(element);
+      const buttons = [
+        ...(element instanceof HTMLButtonElement ? [element] : []),
+        ...Array.from(element.querySelectorAll<HTMLButtonElement>("button")),
+      ];
+      buttons.forEach((button) => {
+        if (!suggestionButtons.includes(button)) {
+          button.disabled = streaming;
+          suggestionButtons.push(button);
+        }
       });
-      fragment.appendChild(btn);
-      suggestionButtons.push(btn);
     });
     container.appendChild(fragment);
-    if (agentPushed) {
-      const shownKey = JSON.stringify(chips);
-      if (shownKey !== lastAgentShownKey) {
-        lastAgentShownKey = shownKey;
+    syncOverflowAffordance();
+    scheduleOverflowAffordance();
+
+    const shownKey = JSON.stringify({
+      normalized,
+      surface,
+      variant,
+      source,
+    });
+    if (shownKey !== lastShownKey) {
+      lastShownKey = shownKey;
+      // Guarded by the same key as the shown event: render() re-runs on every
+      // UI update with identical items and must not re-animate.
+      animateEntrance(suggestionElements);
+      container.dispatchEvent(
+        new CustomEvent("persona:suggestion:shown", {
+          detail: {
+            suggestions: normalized.map((item) => ({ ...item })),
+            surface,
+            source,
+            variant,
+          },
+          bubbles: true,
+          composed: true,
+        })
+      );
+      if (isFollowUp) {
         container.dispatchEvent(
           new CustomEvent("persona:suggestReplies:shown", {
-            detail: { suggestions: [...chips] },
+            detail: {
+              suggestions: normalized.map((item) => item.prompt),
+            },
             bubbles: true,
             composed: true,
           })
@@ -132,9 +508,15 @@ export const createSuggestions = (container: HTMLElement): SuggestionButtons =>
 
   return {
     buttons: suggestionButtons,
-    render
+    elements: suggestionElements,
+    destroy: () => {
+      container.removeEventListener("scroll", scheduleOverflowAffordance);
+      resizeObserver?.disconnect();
+      if (overflowFrame !== null && typeof cancelAnimationFrame === "function") {
+        cancelAnimationFrame(overflowFrame);
+      }
+      overflowFrame = null;
+    },
+    render,
   };
 };
-
-
-

package/src/components/widget-view.ts

@@ -30,6 +30,8 @@ export interface WidgetTranscriptRefs {
   container: HTMLElement;
   body: HTMLElement;
   messagesWrapper: HTMLElement;
+  starterSuggestions: HTMLElement;
+  transcriptSuggestions: HTMLElement;
   /** Absolute slot above the composer where interactive sheets mount. */
   composerOverlay: HTMLElement;
   introTitle: HTMLElement;
@@ -119,6 +121,8 @@ export const createWidgetView = ({
     container: panelElements.container,
     body: panelElements.body,
     messagesWrapper: panelElements.messagesWrapper,
+    starterSuggestions: panelElements.starterSuggestions,
+    transcriptSuggestions: panelElements.transcriptSuggestions,
     composerOverlay: panelElements.composerOverlay,
     introTitle: panelElements.introTitle,
     introSubtitle: panelElements.introSubtitle,

package/src/defaults.ts

@@ -169,10 +169,12 @@ export const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig> = {
       submitLabel: "Send",
     },
   },
+  // Placeholder copy that models the right shape: verb-first, user-voice,
+  // one line. Integrators should swap in domain prompts.
   suggestionChips: [
-    "What can you help me with?",
-    "Tell me about your features",
-    "How does this work?",
+    "Show me what you can help with",
+    "Walk me through getting started",
+    "Answer a question about this page",
   ],
   suggestionChipsConfig: {
     fontFamily: "sans-serif",

package/src/generated/runtype-openapi-contract.ts

@@ -260,7 +260,24 @@ export type RuntypeExecutionStreamEvent = ({
   type: "source";
   url?: string;
   [key: string]: unknown;
+} | {
+  executionId: string;
+  iteration?: number;
+  seq: number;
+  state: Record<string, unknown>;
+  type: "state_snapshot";
 } | ({
+  executionId: string;
+  iteration?: number;
+  patch: Array<{
+  from?: string;
+  op: "add" | "remove" | "replace" | "move" | "copy" | "test";
+  path: string;
+  value?: unknown;
+}>;
+  seq: number;
+  type: "state_delta";
+}) | ({
   executionId: string;
   hiddenParameterNames?: Array<string>;
   iteration?: number;