@runtypelabs/persona 2.3.1 → 3.1.0

package/src/types/theme.ts

@@ -199,6 +199,20 @@ export interface HeaderTokens extends ComponentTokenSet {
   background: TokenReference<'color'>;
   border: TokenReference<'color'>;
   borderRadius: TokenReference<'radius'>;
+  /** Background of the rounded avatar tile next to the title (Lucide / emoji / image). */
+  iconBackground: TokenReference<'color'>;
+  /** Foreground (glyph stroke or emoji text) on the header avatar tile. */
+  iconForeground: TokenReference<'color'>;
+  /** Header title line (next to the icon, or minimal layout title). */
+  titleForeground: TokenReference<'color'>;
+  /** Header subtitle line under the title. */
+  subtitleForeground: TokenReference<'color'>;
+  /** Default color for clear / close icon buttons when launcher overrides are unset. */
+  actionIconForeground: TokenReference<'color'>;
+  /** Box-shadow on the header (e.g., a fade shadow to replace the default border). */
+  shadow?: string;
+  /** Override the header bottom border (e.g., `none`). */
+  borderBottom?: string;
 }
 
 export interface MessageTokens {
@@ -317,6 +331,10 @@ export interface ArtifactToolbarTokens {
   copyMenuShadow?: string;
   copyMenuBorderRadius?: string;
   copyMenuItemHoverBackground?: string;
+  /** Base background of icon buttons (defaults to --persona-surface). */
+  iconBackground?: string;
+  /** Border on the toolbar (e.g., `none` to remove the bottom border). */
+  toolbarBorder?: string;
 }
 
 /** Artifact tab strip chrome. */
@@ -326,13 +344,62 @@ export interface ArtifactTabTokens {
   activeBorder?: string;
   borderRadius?: string;
   textColor?: string;
+  /** Hover background for inactive tabs. */
+  hoverBackground?: string;
+  /** Tab list container background. */
+  listBackground?: string;
+  /** Tab list container border color. */
+  listBorderColor?: string;
+  /** Tab list container padding (CSS shorthand). */
+  listPadding?: string;
 }
 
 /** Artifact pane chrome. */
 export interface ArtifactPaneTokens {
+  /**
+   * Background for the artifact column (toolbar + content), resolved from the theme.
+   * Defaults to `semantic.colors.container` so the pane matches assistant message surfaces.
+   * `features.artifacts.layout.paneBackground` still wins when set (layout escape hatch).
+   */
+  background?: string;
   toolbarBackground?: string;
 }
 
+/** Icon button chrome (used by createIconButton). */
+export interface IconButtonTokens {
+  background?: string;
+  border?: string;
+  color?: string;
+  padding?: string;
+  borderRadius?: string;
+  hoverBackground?: string;
+  hoverColor?: string;
+  /** Background when aria-pressed="true". */
+  activeBackground?: string;
+  /** Border color when aria-pressed="true". */
+  activeBorder?: string;
+}
+
+/** Label button chrome (used by createLabelButton). */
+export interface LabelButtonTokens {
+  background?: string;
+  border?: string;
+  color?: string;
+  padding?: string;
+  borderRadius?: string;
+  hoverBackground?: string;
+  fontSize?: string;
+  gap?: string;
+}
+
+/** Toggle group chrome (used by createToggleGroup). */
+export interface ToggleGroupTokens {
+  /** Gap between toggle buttons. Default: 0 (connected). */
+  gap?: string;
+  /** Border radius for first/last buttons. */
+  borderRadius?: string;
+}
+
 export interface ComponentTokens {
   button: ButtonTokens;
   input: InputTokens;
@@ -348,6 +415,12 @@ export interface ComponentTokens {
   toolBubble: ToolBubbleTokens;
   reasoningBubble: ReasoningBubbleTokens;
   composer: ComposerChromeTokens;
+  /** Icon button styling tokens. */
+  iconButton?: IconButtonTokens;
+  /** Label button styling tokens. */
+  labelButton?: LabelButtonTokens;
+  /** Toggle group styling tokens. */
+  toggleGroup?: ToggleGroupTokens;
   /** Artifact toolbar, tab strip, and pane chrome. */
   artifact?: {
     toolbar?: ArtifactToolbarTokens;
@@ -384,6 +457,9 @@ export type PersonaTheme = PersonaThemeBase &
   PersonaThemeSemantic & 
   PersonaThemeComponents;
 
+/** Recursive partial for `config.theme` / `config.darkTheme` overrides. */
+export type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
+
 export interface ResolvedToken {
   path: string;
   value: string;

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { AgentWidgetPlugin } from "./plugins/types";
+import type { DeepPartial, PersonaTheme } from "./types/theme";
 
 // ============================================================================
 // Multi-Modal Content Types
@@ -469,7 +470,9 @@ export type AgentWidgetArtifactsLayoutConfig = {
    */
   unifiedSplitOuterRadius?: string;
   /**
-   * Background color for the artifact column (CSS color). Sets `--persona-artifact-pane-bg` on the widget root.
+   * Strongest override: solid background for the artifact column (CSS color). Sets `--persona-artifact-pane-bg`
+   * on the widget root. Leave unset to use theme `components.artifact.pane.background` (defaults to semantic
+   * container) so light/dark stays consistent.
    */
   paneBackground?: string;
   /**
@@ -533,6 +536,20 @@ export type AgentWidgetArtifactsFeature = {
     type: 'open' | 'download';
     artifactId: string;
   }) => boolean | void;
+  /**
+   * Custom renderer for artifact reference cards shown in the message thread.
+   * Return an HTMLElement to replace the default card, or `null` to use the default.
+   */
+  renderCard?: (context: {
+    artifact: {
+      artifactId: string;
+      title: string;
+      artifactType: string;
+      status: string;
+    };
+    config: AgentWidgetConfig;
+    defaultRenderer: () => HTMLElement;
+  }) => HTMLElement | null;
 };
 
 export type AgentWidgetFeatureFlags = {
@@ -667,85 +684,6 @@ export type EventStreamPayloadRenderContext = {
   parsedPayload: unknown;
 };
 
-export type AgentWidgetTheme = {
-  primary?: string;
-  secondary?: string;
-  surface?: string;
-  muted?: string;
-  accent?: string;
-  container?: string;
-  border?: string;
-  divider?: string;
-  messageBorder?: string;
-  inputBackground?: string;
-  callToAction?: string;
-  callToActionBackground?: string;
-  sendButtonBackgroundColor?: string;
-  sendButtonTextColor?: string;
-  sendButtonBorderColor?: string;
-  closeButtonColor?: string;
-  closeButtonBackgroundColor?: string;
-  closeButtonBorderColor?: string;
-  clearChatIconColor?: string;
-  clearChatBackgroundColor?: string;
-  clearChatBorderColor?: string;
-  tooltipBackground?: string;
-  tooltipForeground?: string;
-  micIconColor?: string;
-  micBackgroundColor?: string;
-  micBorderColor?: string;
-  recordingIconColor?: string;
-  recordingBackgroundColor?: string;
-  recordingBorderColor?: string;
-  inputFontFamily?: "sans-serif" | "serif" | "mono";
-  inputFontWeight?: string;
-  radiusSm?: string;
-  radiusMd?: string;
-  radiusLg?: string;
-  launcherRadius?: string;
-  buttonRadius?: string;
-  /**
-   * Border style for the chat panel container.
-   * @example "1px solid #e5e7eb" | "none"
-   * @default "1px solid var(--persona-border)"
-   */
-  panelBorder?: string;
-  /**
-   * Box shadow for the chat panel container.
-   * @example "0 25px 50px -12px rgba(0,0,0,0.25)" | "none"
-   * @default "0 25px 50px -12px rgba(0,0,0,0.25)"
-   */
-  panelShadow?: string;
-  /**
-   * Border radius for the chat panel container.
-   * @example "16px" | "0"
-   * @default "16px"
-   */
-  panelBorderRadius?: string;
-  /**
-   * Box-shadow for user message bubbles (bubble message layout).
-   * @example "none" | "0 1px 2px rgba(0,0,0,0.05)"
-   */
-  messageUserShadow?: string;
-  /**
-   * Box-shadow for assistant message bubbles (bubble message layout).
-   * Overrides the default subtle assistant shadow when set.
-   */
-  messageAssistantShadow?: string;
-  /**
-   * Box-shadow for tool-call / function-call rows.
-   */
-  toolBubbleShadow?: string;
-  /**
-   * Box-shadow for reasoning (“thinking”) rows.
-   */
-  reasoningBubbleShadow?: string;
-  /**
-   * Box-shadow on the composer (input) container.
-   */
-  composerShadow?: string;
-};
-
 export type AgentWidgetDockConfig = {
   /**
    * Side of the wrapped container where the docked panel should render.
@@ -758,10 +696,22 @@ export type AgentWidgetDockConfig = {
    */
   width?: string;
   /**
-   * Width of the collapsed launcher rail when the docked panel is closed.
-   * @default "72px"
+   * When false, the dock column snaps between `0` and `width` with no CSS transition so main
+   * content does not reflow during the open/close animation.
+   * @default true
+   */
+  animate?: boolean;
+  /**
+   * How the dock panel is shown.
+   * - `"resize"` (default): a flex column grows/shrinks between `0` and `width` (main content reflows).
+   * - `"overlay"`: panel is absolutely positioned and translates in/out **over** full-width content.
+   * - `"push"`: a wide inner track `[content at shell width][panel]` translates horizontally so the panel
+   *   appears to push the workspace aside **without** animating the content column width (Shopify-style).
+   * - `"emerge"`: like `"resize"`, the flex column animates so **page content reflows**; the chat
+   *   panel keeps a **fixed** `dock.width` (not squeezed while the column grows), clipped by the slot so
+   *   it appears to emerge at full width like a floating widget.
    */
-  collapsedWidth?: string;
+  reveal?: "resize" | "overlay" | "push" | "emerge";
 };
 
 export type AgentWidgetLauncherConfig = {
@@ -1396,6 +1346,17 @@ export type AgentWidgetHeaderTrailingAction = {
   icon?: string;
   label?: string;
   ariaLabel?: string;
+  /**
+   * When set, clicking this action opens a dropdown menu.
+   * Menu item selections fire `onAction(menuItemId)`.
+   */
+  menuItems?: Array<{
+    id: string;
+    label: string;
+    icon?: string;
+    destructive?: boolean;
+    dividerBefore?: boolean;
+  }>;
 };
 
 /**
@@ -1466,6 +1427,41 @@ export type AgentWidgetHeaderLayoutConfig = {
    * When set, the title row becomes visually interactive (cursor: pointer).
    */
   onTitleClick?: () => void;
+  /** Style config for the title row hover effect (minimal layout). */
+  titleRowHover?: {
+    /** Hover background color. */
+    background?: string;
+    /** Hover border color. */
+    border?: string;
+    /** Border radius for the pill shape. */
+    borderRadius?: string;
+    /** Padding inside the pill. */
+    padding?: string;
+  };
+  /**
+   * Replaces the title with a combo button (label + chevron + dropdown menu).
+   * When set, `trailingActions`, `onTitleClick`, and `titleRowHover` are ignored
+   * since the combo button handles all of these internally.
+   */
+  titleMenu?: {
+    /** Dropdown menu items. */
+    menuItems: Array<{
+      id: string;
+      label: string;
+      icon?: string;
+      destructive?: boolean;
+      dividerBefore?: boolean;
+    }>;
+    /** Called when a menu item is selected. */
+    onSelect: (id: string) => void;
+    /** Hover pill style. */
+    hover?: {
+      background?: string;
+      border?: string;
+      borderRadius?: string;
+      padding?: string;
+    };
+  };
 };
 
 /**
@@ -2256,22 +2252,15 @@ export type AgentWidgetConfig = {
      */
     showWelcomeCard?: boolean;
   };
-  theme?: AgentWidgetTheme;
   /**
-   * Theme colors for dark mode. Applied when dark mode is detected
-   * (when colorScheme is 'dark' or 'auto' with dark mode active).
-   * If not provided, falls back to `theme` colors.
-   * 
-   * @example
-   * ```typescript
-   * config: {
-   *   theme: { primary: '#111827', surface: '#ffffff' },
-   *   darkTheme: { primary: '#f9fafb', surface: '#1f2937' },
-   *   colorScheme: 'auto'
-   * }
-   * ```
+   * Semantic design tokens (`palette`, `semantic`, `components`).
+   * Omit for library defaults.
+   */
+  theme?: DeepPartial<PersonaTheme>;
+  /**
+   * Dark-mode token overrides. Merged over `theme` when the active scheme is dark.
    */
-  darkTheme?: AgentWidgetTheme;
+  darkTheme?: DeepPartial<PersonaTheme>;
   /**
    * Color scheme mode for the widget.
    * - 'light': Always use light theme (default)

package/src/ui.docked.test.ts

@@ -10,7 +10,7 @@ describe("createAgentExperience docked mode", () => {
     document.body.innerHTML = "";
   });
 
-  it("collapses the docked panel wrapper and keeps the rail trigger visible when closed", () => {
+  it("toggles docked panel open/closed; built-in launcher stays hidden (open via controller.open)", () => {
     const mount = document.createElement("div");
     document.body.appendChild(mount);
 
@@ -22,7 +22,6 @@ describe("createAgentExperience docked mode", () => {
         dock: {
           side: "right",
           width: "420px",
-          collapsedWidth: "72px",
         },
       },
     });
@@ -40,7 +39,7 @@ describe("createAgentExperience docked mode", () => {
     controller.close();
 
     expect(wrapper?.style.display).toBe("none");
-    expect(launcherButton?.style.display).toBe("");
+    expect(launcherButton?.style.display).toBe("none");
 
     controller.open();
 
@@ -50,7 +49,141 @@ describe("createAgentExperience docked mode", () => {
     controller.destroy();
   });
 
-  it("collapses the dock width when the header close button is clicked", () => {
+  it("keeps docked panel hidden when closed under mobile fullscreen breakpoint", () => {
+    const prevWidth = window.innerWidth;
+    try {
+      Object.defineProperty(window, "innerWidth", {
+        configurable: true,
+        value: 480,
+      });
+
+      const mount = document.createElement("div");
+      document.body.appendChild(mount);
+
+      const controller = createAgentExperience(mount, {
+        apiUrl: "https://api.example.com/chat",
+        launcher: {
+          mountMode: "docked",
+          autoExpand: false,
+          dock: {
+            side: "right",
+            width: "420px",
+          },
+        },
+      });
+
+      const wrapper = mount.firstElementChild as HTMLElement | null;
+      expect(wrapper?.style.display).toBe("none");
+      expect(getComputedStyle(wrapper!).display).toBe("none");
+
+      controller.open();
+      expect(wrapper?.style.display).toBe("flex");
+
+      controller.destroy();
+    } finally {
+      Object.defineProperty(window, "innerWidth", {
+        configurable: true,
+        writable: true,
+        value: prevWidth,
+      });
+    }
+  });
+
+  it("keeps docked panel hidden after resize into mobile when closed", () => {
+    const prevWidth = window.innerWidth;
+    try {
+      Object.defineProperty(window, "innerWidth", {
+        configurable: true,
+        value: 900,
+      });
+
+      const mount = document.createElement("div");
+      document.body.appendChild(mount);
+
+      const controller = createAgentExperience(mount, {
+        apiUrl: "https://api.example.com/chat",
+        launcher: {
+          mountMode: "docked",
+          autoExpand: false,
+          dock: {
+            side: "right",
+            width: "420px",
+          },
+        },
+      });
+
+      const wrapper = mount.firstElementChild as HTMLElement | null;
+      expect(wrapper?.style.display).toBe("none");
+
+      Object.defineProperty(window, "innerWidth", {
+        configurable: true,
+        value: 480,
+      });
+      window.dispatchEvent(new Event("resize"));
+
+      expect(wrapper?.style.display).toBe("none");
+
+      controller.destroy();
+    } finally {
+      Object.defineProperty(window, "innerWidth", {
+        configurable: true,
+        writable: true,
+        value: prevWidth,
+      });
+    }
+  });
+
+  it("collapses the dock width to 0 when the header close button is clicked", () => {
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+
+    const hostLayout = createWidgetHostLayout(target, {
+      launcher: {
+        mountMode: "docked",
+        autoExpand: true,
+        dock: {
+          side: "right",
+          width: "420px",
+        },
+      },
+    });
+    const mount = document.createElement("div");
+    hostLayout.host.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: {
+        mountMode: "docked",
+        autoExpand: true,
+        dock: {
+          side: "right",
+          width: "420px",
+        },
+      },
+    });
+
+    const syncDockState = () => hostLayout.syncWidgetState(controller.getState());
+    const openUnsub = controller.on("widget:opened", syncDockState);
+    const closeUnsub = controller.on("widget:closed", syncDockState);
+    syncDockState();
+
+    const dockSlot = hostLayout.shell?.querySelector<HTMLElement>('[data-persona-dock-role="panel"]');
+    const closeButton = mount.querySelector<HTMLButtonElement>('[aria-label="Close chat"]');
+
+    expect(dockSlot?.style.width).toBe("420px");
+    expect(closeButton).not.toBeNull();
+
+    closeButton!.click();
+
+    expect(dockSlot?.style.width).toBe("0px");
+
+    openUnsub();
+    closeUnsub();
+    controller.destroy();
+    hostLayout.destroy();
+  });
+
+  it("overlay reveal keeps width when closed; host-layout uses transform", () => {
     const target = document.createElement("div");
     document.body.appendChild(target);
 
@@ -61,7 +194,7 @@ describe("createAgentExperience docked mode", () => {
         dock: {
           side: "right",
           width: "420px",
-          collapsedWidth: "72px",
+          reveal: "overlay",
         },
       },
     });
@@ -76,7 +209,7 @@ describe("createAgentExperience docked mode", () => {
         dock: {
           side: "right",
           width: "420px",
-          collapsedWidth: "72px",
+          reveal: "overlay",
         },
       },
     });
@@ -94,7 +227,70 @@ describe("createAgentExperience docked mode", () => {
 
     closeButton!.click();
 
-    expect(dockSlot?.style.width).toBe("72px");
+    expect(dockSlot?.style.width).toBe("420px");
+    expect(dockSlot?.style.transform).toBe("translateX(100%)");
+
+    openUnsub();
+    closeUnsub();
+    controller.destroy();
+    hostLayout.destroy();
+  });
+
+  it("push reveal translates the push-track when the header close button is clicked", () => {
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+
+    const hostLayout = createWidgetHostLayout(target, {
+      launcher: {
+        mountMode: "docked",
+        autoExpand: true,
+        dock: {
+          side: "right",
+          width: "420px",
+          reveal: "push",
+        },
+      },
+    });
+    const shell = hostLayout.shell!;
+    Object.defineProperty(shell, "clientWidth", { get: () => 1000, configurable: true });
+    hostLayout.updateConfig({
+      launcher: {
+        mountMode: "docked",
+        autoExpand: true,
+        dock: { side: "right", width: "420px", reveal: "push" },
+      },
+    });
+
+    const mount = document.createElement("div");
+    hostLayout.host.appendChild(mount);
+
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      launcher: {
+        mountMode: "docked",
+        autoExpand: true,
+        dock: {
+          side: "right",
+          width: "420px",
+          reveal: "push",
+        },
+      },
+    });
+
+    const syncDockState = () => hostLayout.syncWidgetState(controller.getState());
+    const openUnsub = controller.on("widget:opened", syncDockState);
+    const closeUnsub = controller.on("widget:closed", syncDockState);
+    syncDockState();
+
+    const pushTrack = shell.querySelector<HTMLElement>('[data-persona-dock-role="push-track"]');
+    const closeButton = mount.querySelector<HTMLButtonElement>('[aria-label="Close chat"]');
+
+    expect(pushTrack).not.toBeNull();
+    expect(pushTrack?.style.transform).toBe("translateX(-420px)");
+
+    closeButton!.click();
+
+    expect(pushTrack?.style.transform).toBe("translateX(0)");
 
     openUnsub();
     closeUnsub();