@runtypelabs/persona 2.3.1 → 3.1.0

package/README.md

@@ -77,7 +77,6 @@ const docked = initAgentWidget({
       dock: {
         side: 'right',
         width: '420px',
-        collapsedWidth: '72px'
       }
     }
   }
@@ -98,6 +97,12 @@ const docked = initAgentWidget({
 
 When `config.launcher.mountMode` is `'docked'`, `target` is treated as the page container that Persona should wrap. Use a concrete element such as `#workspace-main`; `body` and `html` are rejected.
 
+With **`dock.reveal: 'resize'`** (default), a **closed** dock uses a **`0px`** column. **`'emerge'`** uses the same **column width** animation (content reflows) but the chat panel stays **`dock.width`** wide and is **clipped** by the growing slot—like a normal-width widget emerging from the edge. **`'overlay'`** overlays with `transform`. **`'push'`** uses a sliding track (Shopify-style). The built-in launcher stays hidden in docked mode—open with **`controller.open()`** (or your own chrome).
+
+**Rounded / card layout:** `initAgentWidget` inserts a flex **shell** as the **direct child** of your target’s **parent**, with your `target` in the content column and the dock beside it. Put border-radius, border, and `overflow: hidden` on that **parent** (or an ancestor that wraps only the shell) so the dock column sits inside the same visual card as your content.
+
+**Inner push/overlay:** With `reveal: 'push'` or `'overlay'`, only the wrapped node moves. Use a **narrow `target`** (e.g. a main canvas div). For **`dock.side: 'left'`**, place a persistent rail **in flow** next to the stage (e.g. flex `[nav | stage]`) so the dock doesn’t open **under** the sidebar. For a **right** dock, you can instead use a **full-width** stage with an **absolute** left rail if you want the canvas to translate **behind** that rail.
+
 > **Security note:** When you return HTML from `postprocessMessage`, make sure you sanitise it before injecting into the page. The provided postprocessors (`markdownPostprocessor`, `directivePostprocessor`) do not perform sanitisation.
 
 
@@ -890,6 +895,218 @@ Indicators are resolved in this order:
 2. **Config function** (`loadingIndicator.render` / `loadingIndicator.renderIdle`)
 3. **Default** (3-dot bouncing animation for loading, `null` for idle)
 
+### Dropdown Menu
+
+A reusable dropdown menu utility for building custom menus in plugins, custom components, or host-page UI that matches the widget's theme.
+
+#### Basic usage
+
+```ts
+import { createDropdownMenu } from '@runtypelabs/persona';
+
+const button = document.querySelector('#my-button')!;
+const wrapper = document.createElement('div');
+wrapper.style.position = 'relative';
+button.parentElement!.insertBefore(wrapper, button);
+wrapper.appendChild(button);
+
+const dropdown = createDropdownMenu({
+  items: [
+    { id: 'edit', label: 'Edit', icon: 'pencil' },
+    { id: 'duplicate', label: 'Duplicate', icon: 'copy' },
+    { id: 'delete', label: 'Delete', icon: 'trash-2', destructive: true, dividerBefore: true },
+  ],
+  onSelect: (id) => console.log('Selected:', id),
+  anchor: wrapper,
+  position: 'bottom-left', // or 'bottom-right'
+});
+
+wrapper.appendChild(dropdown.element);
+button.addEventListener('click', () => dropdown.toggle());
+```
+
+#### Escaping overflow containers
+
+When the anchor is inside a container with `overflow: hidden`, use the `portal` option to render the menu at a higher DOM level while keeping CSS variable inheritance:
+
+```ts
+const dropdown = createDropdownMenu({
+  items: [...],
+  onSelect: (id) => { /* handle */ },
+  anchor: myButton,
+  position: 'bottom-right',
+  portal: document.querySelector('[data-persona-root]')!,
+});
+// No need to append — portal mode appends automatically
+```
+
+#### Header dropdown menus
+
+Trailing header actions support built-in dropdown menus via the `menuItems` property:
+
+```ts
+createAgentExperience(mount, {
+  layout: {
+    header: {
+      layout: 'minimal',
+      trailingActions: [
+        {
+          id: 'options',
+          icon: 'chevron-down',
+          ariaLabel: 'Options',
+          menuItems: [
+            { id: 'settings', label: 'Settings', icon: 'settings' },
+            { id: 'help', label: 'Help', icon: 'help-circle' },
+            { id: 'logout', label: 'Log out', icon: 'log-out', destructive: true, dividerBefore: true },
+          ]
+        }
+      ],
+      onAction: (actionId) => {
+        // Receives the menu item id when selected
+        console.log('Action:', actionId);
+      }
+    }
+  }
+});
+```
+
+#### Theming
+
+Dropdown menus are styled via CSS custom properties with semantic fallbacks:
+
+| Variable | Description | Fallback |
+|----------|-------------|----------|
+| `--persona-dropdown-bg` | Menu background | `--persona-surface` |
+| `--persona-dropdown-border` | Menu border | `--persona-border` |
+| `--persona-dropdown-radius` | Border radius | `0.625rem` |
+| `--persona-dropdown-shadow` | Box shadow | `0 4px 16px rgba(0,0,0,0.12)` |
+| `--persona-dropdown-item-color` | Item text color | `--persona-text` |
+| `--persona-dropdown-item-hover-bg` | Item hover background | `--persona-container` |
+| `--persona-dropdown-destructive-color` | Destructive item color | `#ef4444` |
+
+Artifact toolbar copy menu tokens (`copyMenuBackground`, `copyMenuBorder`, etc.) also set the dropdown variables as defaults, so dropdown theming works with the existing artifact token config.
+
+#### Type definitions
+
+```ts
+interface DropdownMenuItem {
+  id: string;
+  label: string;
+  icon?: string;        // Lucide icon name
+  destructive?: boolean;
+  dividerBefore?: boolean;
+}
+
+interface CreateDropdownOptions {
+  items: DropdownMenuItem[];
+  onSelect: (id: string) => void;
+  anchor: HTMLElement;
+  position?: 'bottom-left' | 'bottom-right';
+  portal?: HTMLElement;
+}
+
+interface DropdownMenuHandle {
+  element: HTMLElement;
+  show: () => void;
+  hide: () => void;
+  toggle: () => void;
+  destroy: () => void;
+}
+```
+
+### Button Utilities
+
+Composable button factories for building custom toolbars, actions, and toggle controls that match the widget's theme.
+
+#### Icon button
+
+```ts
+import { createIconButton } from '@runtypelabs/persona';
+
+const refreshBtn = createIconButton({
+  icon: 'refresh-cw',
+  label: 'Refresh',
+  onClick: () => handleRefresh(),
+});
+toolbar.appendChild(refreshBtn);
+```
+
+#### Label button
+
+```ts
+import { createLabelButton } from '@runtypelabs/persona';
+
+const copyBtn = createLabelButton({
+  icon: 'copy',
+  label: 'Copy',
+  variant: 'default',   // 'default' | 'primary' | 'destructive' | 'ghost'
+  onClick: () => copyToClipboard(),
+});
+```
+
+#### Toggle group
+
+```ts
+import { createToggleGroup } from '@runtypelabs/persona';
+
+const toggle = createToggleGroup({
+  items: [
+    { id: 'preview', icon: 'eye', label: 'Preview' },
+    { id: 'source', icon: 'code-2', label: 'Source' },
+  ],
+  selectedId: 'preview',
+  onSelect: (id) => setViewMode(id),
+});
+toolbar.appendChild(toggle.element);
+
+// Programmatic update (does not fire onSelect)
+toggle.setSelected('source');
+```
+
+#### Theming
+
+All button utilities are styled via CSS custom properties:
+
+| Variable | Component | Description | Fallback |
+|----------|-----------|-------------|----------|
+| `--persona-icon-btn-bg` | Icon button | Background | `--persona-surface` |
+| `--persona-icon-btn-border` | Icon button | Border | `--persona-border` |
+| `--persona-icon-btn-color` | Icon button | Icon color | `--persona-text` |
+| `--persona-icon-btn-hover-bg` | Icon button | Hover background | `--persona-container` |
+| `--persona-icon-btn-hover-color` | Icon button | Hover color | `inherit` |
+| `--persona-icon-btn-active-bg` | Icon button | Pressed/active bg | `--persona-container` |
+| `--persona-icon-btn-active-border` | Icon button | Pressed/active border | `--persona-border` |
+| `--persona-icon-btn-padding` | Icon button | Padding | `0.25rem` |
+| `--persona-icon-btn-radius` | Icon button | Border radius | `--persona-radius-md` |
+| `--persona-label-btn-bg` | Label button | Background | `--persona-surface` |
+| `--persona-label-btn-border` | Label button | Border | `--persona-border` |
+| `--persona-label-btn-color` | Label button | Text color | `--persona-text` |
+| `--persona-label-btn-hover-bg` | Label button | Hover background | `--persona-container` |
+| `--persona-label-btn-font-size` | Label button | Font size | `0.75rem` |
+| `--persona-toggle-group-gap` | Toggle group | Gap between items | `0` |
+| `--persona-toggle-group-radius` | Toggle group | First/last radius | `--persona-icon-btn-radius` |
+
+These can also be set via the widget config's theme token system:
+
+```ts
+createAgentExperience(mount, {
+  darkTheme: {
+    components: {
+      iconButton: {
+        background: 'transparent',
+        border: 'none',
+        hoverBackground: '#2B2B2B',
+        hoverColor: '#E5E5E5',
+      },
+      toggleGroup: {
+        gap: '0',
+        borderRadius: '8px',
+      },
+    }
+  }
+});
+```
+
 ### Runtype adapter
 
 This package ships with a Runtype adapter by default. The proxy handles all flow configuration, keeping the client lightweight and flexible.
@@ -1465,8 +1682,8 @@ config: {
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `theme` | `AgentWidgetTheme` | CSS variable overrides for colors, border radii, and visual styles. See [THEME-CONFIG.md](./THEME-CONFIG.md) for the full property list. |
-| `darkTheme` | `AgentWidgetTheme` | Theme overrides for dark mode. Falls back to `theme` when not provided. |
+| `theme` | `DeepPartial<PersonaTheme>` | Semantic tokens (`palette`, `semantic`, `components`). See [THEME-CONFIG.md](./THEME-CONFIG.md). Flat v1-style objects are still accepted at runtime (with a console warning) and migrated internally. |
+| `darkTheme` | `DeepPartial<PersonaTheme>` | Dark-mode token overrides, merged over `theme` when the active scheme is dark. |
 | `colorScheme` | `'light' \| 'dark' \| 'auto'` | Color scheme mode. `'auto'` detects from `<html class="dark">` or `prefers-color-scheme`. Default: `'light'`. |
 | `copy` | `{ welcomeTitle?, welcomeSubtitle?, inputPlaceholder?, sendButtonLabel? }` | Customize user-facing text strings. |
 | `autoFocusInput` | `boolean` | Focus the chat input after the panel opens. Skips when voice is active. Default: `false`. |
@@ -1491,7 +1708,7 @@ Controls the floating launcher button and panel.
 | `iconUrl` | `string?` | URL for the launcher icon image. |
 | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'?` | Screen corner position. |
 | `mountMode` | `'floating' \| 'docked'?` | Mount as the existing floating launcher or wrap the target with a docked side panel. Default: `'floating'`. |
-| `dock` | `{ side?: 'left' \| 'right'; width?: string; collapsedWidth?: string }?` | Docked panel sizing and side. Defaults: right / `420px` / `72px`. |
+| `dock` | `{ side?, width?, animate?, reveal? }?` | Dock layout. Defaults: right / `420px` / `animate: true` / `reveal: 'resize'`. `reveal: 'emerge'` = content column animates like resize but the panel stays fixed `dock.width` (clip-in). `reveal: 'overlay'` = transform overlay; `reveal: 'push'` = sliding track. `animate: false` snaps without transition. |
 | `width` | `string?` | Width of the launcher button. |
 | `fullHeight` | `boolean?` | Fill the full height of the container. Default: `false`. |
 | `sidebarMode` | `boolean?` | Flush sidebar layout with no border-radius or margins. Default: `false`. |
@@ -2105,6 +2322,6 @@ Add `RUNTYPE_API_KEY` to your environment. The proxy constructs the Runtype payl
 ### Development notes
 
 - The widget streams results using SSE and mirrors the backend `flow_complete`/`step_chunk` events.
-- Tailwind-esc classes are prefixed with `tvw-` and scoped to `#persona-root`, so they won't collide with the host page.
+- Tailwind-esc classes are prefixed with `tvw-` and scoped to `[data-persona-root]`, so they won't collide with the host page.
 - Run `pnpm dev` from the repository root to boot the example proxy (`examples/proxy`) and the vanilla demo (`examples/embedded-app`).
 - The proxy prefers port `43111` but automatically selects the next free port if needed.