vanilla-agent 1.9.0 → 1.11.0

package/dist/index.d.ts

@@ -194,6 +194,24 @@ type AgentWidgetTheme = {
     radiusLg?: string;
     launcherRadius?: string;
     buttonRadius?: string;
+    /**
+     * Border style for the chat panel container.
+     * @example "1px solid #e5e7eb" | "none"
+     * @default "1px solid var(--tvw-cw-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;
 };
 type AgentWidgetLauncherConfig = {
     enabled?: boolean;
@@ -207,6 +225,35 @@ type AgentWidgetLauncherConfig = {
     position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
     autoExpand?: boolean;
     width?: string;
+    /**
+     * When true, the widget panel will fill the full height of its container.
+     * Useful for sidebar layouts where the chat should take up the entire viewport height.
+     * The widget will use flex layout to ensure header stays at top, messages scroll in middle,
+     * and composer stays fixed at bottom.
+     *
+     * @default false
+     */
+    fullHeight?: boolean;
+    /**
+     * When true, the widget panel will be positioned as a sidebar flush with the viewport edges.
+     * The panel will have:
+     * - No border-radius (square corners)
+     * - No margins (flush with top, left/right, and bottom edges)
+     * - Full viewport height
+     * - Subtle shadow on the edge facing the content
+     * - No border between footer and messages
+     *
+     * Use with `position` to control which side ('bottom-left' for left sidebar, 'bottom-right' for right sidebar).
+     * Automatically enables fullHeight when true.
+     *
+     * @default false
+     */
+    sidebarMode?: boolean;
+    /**
+     * Width of the sidebar panel when sidebarMode is true.
+     * @default "420px"
+     */
+    sidebarWidth?: string;
     callToActionIconText?: string;
     callToActionIconName?: string;
     callToActionIconColor?: string;
@@ -249,6 +296,7 @@ type AgentWidgetSendButtonConfig = {
 };
 type AgentWidgetClearChatConfig = {
     enabled?: boolean;
+    placement?: "inline" | "top-right";
     iconName?: string;
     iconColor?: string;
     backgroundColor?: string;
@@ -363,10 +411,203 @@ interface AgentWidgetStreamParser {
      */
     close?(): Promise<void> | void;
 }
+/**
+ * Component renderer function signature for custom components
+ */
+type AgentWidgetComponentRenderer = (props: Record<string, unknown>, context: {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    updateProps: (newProps: Record<string, unknown>) => void;
+}) => HTMLElement;
+/**
+ * Result from custom SSE event parser
+ */
+type AgentWidgetSSEEventResult = {
+    /** Text content to display */
+    text?: string;
+    /** Whether the stream is complete */
+    done?: boolean;
+    /** Error message if an error occurred */
+    error?: string;
+} | null;
+/**
+ * Custom SSE event parser function
+ * Allows transforming non-standard SSE event formats to vanilla-agent's expected format
+ */
+type AgentWidgetSSEEventParser = (eventData: unknown) => AgentWidgetSSEEventResult | Promise<AgentWidgetSSEEventResult>;
+/**
+ * Custom fetch function for full control over API requests
+ * Use this for custom authentication, request transformation, etc.
+ */
+type AgentWidgetCustomFetch = (url: string, init: RequestInit, payload: AgentWidgetRequestPayload) => Promise<Response>;
+/**
+ * Dynamic headers function - called before each request
+ */
+type AgentWidgetHeadersFunction = () => Record<string, string> | Promise<Record<string, string>>;
+/**
+ * Context provided to header render functions
+ */
+type HeaderRenderContext = {
+    config: AgentWidgetConfig;
+    onClose?: () => void;
+    onClearChat?: () => void;
+};
+/**
+ * Context provided to message render functions
+ */
+type MessageRenderContext = {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    streaming: boolean;
+};
+/**
+ * Context provided to slot render functions
+ */
+type SlotRenderContext = {
+    config: AgentWidgetConfig;
+    defaultContent: () => HTMLElement | null;
+};
+/**
+ * Header layout configuration
+ * Allows customization of the header section appearance and behavior
+ */
+type AgentWidgetHeaderLayoutConfig = {
+    /**
+     * Layout preset: "default" | "minimal" | "expanded"
+     * - default: Standard layout with icon, title, subtitle, and buttons
+     * - minimal: Simplified layout with just title and close button
+     * - expanded: Full branding area with additional content space
+     */
+    layout?: "default" | "minimal" | "expanded";
+    /** Show/hide the header icon */
+    showIcon?: boolean;
+    /** Show/hide the title */
+    showTitle?: boolean;
+    /** Show/hide the subtitle */
+    showSubtitle?: boolean;
+    /** Show/hide the close button */
+    showCloseButton?: boolean;
+    /** Show/hide the clear chat button */
+    showClearChat?: boolean;
+    /**
+     * Custom renderer for complete header override
+     * When provided, replaces the entire header with custom content
+     */
+    render?: (context: HeaderRenderContext) => HTMLElement;
+};
+/**
+ * Avatar configuration for message bubbles
+ */
+type AgentWidgetAvatarConfig = {
+    /** Whether to show avatars */
+    show?: boolean;
+    /** Position of avatar relative to message bubble */
+    position?: "left" | "right";
+    /** URL or emoji for user avatar */
+    userAvatar?: string;
+    /** URL or emoji for assistant avatar */
+    assistantAvatar?: string;
+};
+/**
+ * Timestamp configuration for message bubbles
+ */
+type AgentWidgetTimestampConfig = {
+    /** Whether to show timestamps */
+    show?: boolean;
+    /** Position of timestamp relative to message */
+    position?: "inline" | "below";
+    /** Custom formatter for timestamp display */
+    format?: (date: Date) => string;
+};
+/**
+ * Message layout configuration
+ * Allows customization of how chat messages are displayed
+ */
+type AgentWidgetMessageLayoutConfig = {
+    /**
+     * Layout preset: "bubble" | "flat" | "minimal"
+     * - bubble: Standard chat bubble appearance (default)
+     * - flat: Flat messages without bubble styling
+     * - minimal: Minimal styling with reduced padding/borders
+     */
+    layout?: "bubble" | "flat" | "minimal";
+    /** Avatar configuration */
+    avatar?: AgentWidgetAvatarConfig;
+    /** Timestamp configuration */
+    timestamp?: AgentWidgetTimestampConfig;
+    /** Group consecutive messages from the same role */
+    groupConsecutive?: boolean;
+    /**
+     * Custom renderer for user messages
+     * When provided, replaces the default user message rendering
+     */
+    renderUserMessage?: (context: MessageRenderContext) => HTMLElement;
+    /**
+     * Custom renderer for assistant messages
+     * When provided, replaces the default assistant message rendering
+     */
+    renderAssistantMessage?: (context: MessageRenderContext) => HTMLElement;
+};
+/**
+ * Available layout slots for content injection
+ */
+type WidgetLayoutSlot = "header-left" | "header-center" | "header-right" | "body-top" | "messages" | "body-bottom" | "footer-top" | "composer" | "footer-bottom";
+/**
+ * Slot renderer function signature
+ * Returns HTMLElement to render in the slot, or null to use default content
+ */
+type SlotRenderer = (context: SlotRenderContext) => HTMLElement | null;
+/**
+ * Main layout configuration
+ * Provides comprehensive control over widget layout and appearance
+ *
+ * @example
+ * ```typescript
+ * config: {
+ *   layout: {
+ *     header: { layout: "minimal" },
+ *     messages: {
+ *       avatar: { show: true, assistantAvatar: "/bot.png" },
+ *       timestamp: { show: true, position: "below" }
+ *     },
+ *     slots: {
+ *       "footer-top": () => {
+ *         const el = document.createElement("div");
+ *         el.textContent = "Powered by AI";
+ *         return el;
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type AgentWidgetLayoutConfig = {
+    /** Header layout configuration */
+    header?: AgentWidgetHeaderLayoutConfig;
+    /** Message layout configuration */
+    messages?: AgentWidgetMessageLayoutConfig;
+    /** Slot renderers for custom content injection */
+    slots?: Partial<Record<WidgetLayoutSlot, SlotRenderer>>;
+};
 type AgentWidgetConfig = {
     apiUrl?: string;
     flowId?: string;
+    /**
+     * Static headers to include with each request.
+     * For dynamic headers (e.g., auth tokens), use `getHeaders` instead.
+     */
     headers?: Record<string, string>;
+    /**
+     * Dynamic headers function - called before each request.
+     * Useful for adding auth tokens that may change.
+     * @example
+     * ```typescript
+     * getHeaders: async () => ({
+     *   'Authorization': `Bearer ${await getAuthToken()}`
+     * })
+     * ```
+     */
+    getHeaders?: AgentWidgetHeadersFunction;
     copy?: {
         welcomeTitle?: string;
         welcomeSubtitle?: string;
@@ -398,6 +639,32 @@ type AgentWidgetConfig = {
     actionParsers?: AgentWidgetActionParser[];
     actionHandlers?: AgentWidgetActionHandler[];
     storageAdapter?: AgentWidgetStorageAdapter;
+    /**
+     * Registry of custom components that can be rendered from JSON directives.
+     * Components are registered by name and can be invoked via JSON responses
+     * with the format: `{"component": "ComponentName", "props": {...}}`
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   components: {
+     *     ProductCard: (props, context) => {
+     *       const card = document.createElement("div");
+     *       card.innerHTML = `<h3>${props.title}</h3><p>$${props.price}</p>`;
+     *       return card;
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    components?: Record<string, AgentWidgetComponentRenderer>;
+    /**
+     * Enable component streaming. When true, component props will be updated
+     * incrementally as they stream in from the JSON response.
+     *
+     * @default true
+     */
+    enableComponentStreaming?: boolean;
     /**
      * Custom stream parser for extracting text from streaming structured responses.
      * Handles incremental parsing of JSON, XML, or other formats.
@@ -454,6 +721,83 @@ type AgentWidgetConfig = {
      * ```
      */
     parserType?: "plain" | "json" | "regex-json" | "xml";
+    /**
+     * Custom fetch function for full control over API requests.
+     * Use this for custom authentication, request/response transformation, etc.
+     *
+     * When provided, this function is called instead of the default fetch.
+     * You receive the URL, RequestInit, and the payload that would be sent.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   customFetch: async (url, init, payload) => {
+     *     // Transform request for your API format
+     *     const myPayload = {
+     *       flow: { id: 'my-flow-id' },
+     *       messages: payload.messages,
+     *       options: { stream_response: true }
+     *     };
+     *
+     *     // Add auth header
+     *     const token = await getAuthToken();
+     *
+     *     return fetch('/my-api/dispatch', {
+     *       method: 'POST',
+     *       headers: {
+     *         'Content-Type': 'application/json',
+     *         'Authorization': `Bearer ${token}`
+     *       },
+     *       body: JSON.stringify(myPayload),
+     *       signal: init.signal
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    customFetch?: AgentWidgetCustomFetch;
+    /**
+     * Custom SSE event parser for non-standard streaming response formats.
+     *
+     * Use this when your API returns SSE events in a different format than expected.
+     * Return `{ text }` for text chunks, `{ done: true }` for completion,
+     * `{ error }` for errors, or `null` to ignore the event.
+     *
+     * @example
+     * ```typescript
+     * // For Travrse API format
+     * config: {
+     *   parseSSEEvent: (data) => {
+     *     if (data.type === 'step_chunk' && data.chunk) {
+     *       return { text: data.chunk };
+     *     }
+     *     if (data.type === 'flow_complete') {
+     *       return { done: true };
+     *     }
+     *     if (data.type === 'step_error') {
+     *       return { error: data.error };
+     *     }
+     *     return null; // Ignore other events
+     *   }
+     * }
+     * ```
+     */
+    parseSSEEvent?: AgentWidgetSSEEventParser;
+    /**
+     * Layout configuration for customizing widget appearance and structure.
+     * Provides control over header, messages, and content slots.
+     *
+     * @example
+     * ```typescript
+     * config: {
+     *   layout: {
+     *     header: { layout: "minimal" },
+     *     messages: { avatar: { show: true } }
+     *   }
+     * }
+     * ```
+     */
+    layout?: AgentWidgetLayoutConfig;
 };
 type AgentWidgetMessageRole = "user" | "assistant" | "system";
 type AgentWidgetReasoning = {
@@ -613,9 +957,17 @@ declare class AgentWidgetClient {
     private readonly createStreamParser;
     private readonly contextProviders;
     private readonly requestMiddleware?;
+    private readonly customFetch?;
+    private readonly parseSSEEvent?;
+    private readonly getHeaders?;
     constructor(config?: AgentWidgetConfig);
     dispatch(options: DispatchOptions, onEvent: SSEHandler): Promise<void>;
     private buildPayload;
+    /**
+     * Handle custom SSE event parsing via parseSSEEvent callback
+     * Returns true if event was handled, false otherwise
+     */
+    private handleCustomSSEEvent;
     private streamResponse;
 }
 
@@ -724,6 +1076,149 @@ declare class PluginRegistry {
 }
 declare const pluginRegistry: PluginRegistry;
 
+/**
+ * Context provided to component renderers
+ */
+interface ComponentContext {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    /**
+     * Update component props during streaming
+     */
+    updateProps: (newProps: Record<string, unknown>) => void;
+}
+/**
+ * Component renderer function signature
+ */
+type ComponentRenderer = (props: Record<string, unknown>, context: ComponentContext) => HTMLElement;
+/**
+ * Component registry for managing custom components
+ */
+declare class ComponentRegistry {
+    private components;
+    /**
+     * Register a custom component
+     */
+    register(name: string, renderer: ComponentRenderer): void;
+    /**
+     * Unregister a component
+     */
+    unregister(name: string): void;
+    /**
+     * Get a component renderer by name
+     */
+    get(name: string): ComponentRenderer | undefined;
+    /**
+     * Check if a component is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered component names
+     */
+    getAllNames(): string[];
+    /**
+     * Clear all registered components
+     */
+    clear(): void;
+    /**
+     * Register multiple components at once
+     */
+    registerAll(components: Record<string, ComponentRenderer>): void;
+}
+/**
+ * Global component registry instance
+ */
+declare const componentRegistry: ComponentRegistry;
+
+/**
+ * Represents a component directive extracted from JSON
+ */
+interface ComponentDirective {
+    component: string;
+    props: Record<string, unknown>;
+    raw: string;
+}
+/**
+ * Creates a parser that extracts component directives from JSON streams
+ * This parser looks for objects with a "component" field and extracts
+ * the component name and props incrementally as they stream in.
+ */
+declare function createComponentStreamParser(): {
+    /**
+     * Get the currently extracted component directive
+     */
+    getExtractedDirective: () => ComponentDirective | null;
+    /**
+     * Process a chunk of JSON and extract component directive if present
+     */
+    processChunk: (accumulatedContent: string) => ComponentDirective | null;
+    /**
+     * Reset the parser state
+     */
+    reset: () => void;
+};
+/**
+ * Type guard to check if an object is a component directive
+ */
+declare function isComponentDirectiveType(obj: unknown): obj is ComponentDirective;
+
+type MessageTransform = (context: {
+    text: string;
+    message: AgentWidgetMessage;
+    streaming: boolean;
+    raw?: string;
+}) => string;
+declare const createTypingIndicator: () => HTMLElement;
+/**
+ * Create standard message bubble
+ * Supports layout configuration for avatars, timestamps, and visual presets
+ */
+declare const createStandardBubble: (message: AgentWidgetMessage, transform: MessageTransform, layoutConfig?: AgentWidgetMessageLayoutConfig) => HTMLElement;
+/**
+ * Create bubble with custom renderer support
+ * Uses custom renderer if provided in layout config, otherwise falls back to standard bubble
+ */
+declare const createBubbleWithLayout: (message: AgentWidgetMessage, transform: MessageTransform, layoutConfig?: AgentWidgetMessageLayoutConfig) => HTMLElement;
+
+/**
+ * Options for component middleware
+ */
+interface ComponentMiddlewareOptions {
+    config: AgentWidgetConfig;
+    message: AgentWidgetMessage;
+    transform: MessageTransform;
+    onPropsUpdate?: (props: Record<string, unknown>) => void;
+}
+/**
+ * Renders a component directive into an HTMLElement
+ */
+declare function renderComponentDirective(directive: ComponentDirective, options: ComponentMiddlewareOptions): HTMLElement | null;
+/**
+ * Creates middleware that processes component directives from streamed JSON
+ */
+declare function createComponentMiddleware(): {
+    /**
+     * Process accumulated content and extract component directive
+     */
+    processChunk: (accumulatedContent: string) => ComponentDirective | null;
+    /**
+     * Get the currently extracted directive
+     */
+    getDirective: () => ComponentDirective | null;
+    /**
+     * Reset the parser state
+     */
+    reset: () => void;
+};
+/**
+ * Checks if a message contains a component directive in its raw content
+ */
+declare function hasComponentDirective(message: AgentWidgetMessage): boolean;
+/**
+ * Extracts component directive from a complete message
+ */
+declare function extractComponentDirectiveFromMessage(message: AgentWidgetMessage): ComponentDirective | null;
+
 /**
  * Default widget configuration
  * Single source of truth for all default values
@@ -735,4 +1230,89 @@ declare const DEFAULT_WIDGET_CONFIG: Partial<AgentWidgetConfig>;
  */
 declare function mergeWithDefaults(config?: Partial<AgentWidgetConfig>): Partial<AgentWidgetConfig>;
 
-export { AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, DEFAULT_WIDGET_CONFIG, createActionManager, createAgentExperience, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createPlainTextParser, createRegexJsonParser, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, initAgentWidget, markdownPostprocessor, mergeWithDefaults, pluginRegistry };
+interface HeaderElements {
+    header: HTMLElement;
+    iconHolder: HTMLElement;
+    headerTitle: HTMLElement;
+    headerSubtitle: HTMLElement;
+    closeButton: HTMLButtonElement;
+    closeButtonWrapper: HTMLElement;
+    clearChatButton: HTMLButtonElement | null;
+    clearChatButtonWrapper: HTMLElement | null;
+}
+interface HeaderBuildContext {
+    config?: AgentWidgetConfig;
+    showClose?: boolean;
+    onClose?: () => void;
+    onClearChat?: () => void;
+}
+/**
+ * Build the header section of the panel.
+ * Extracted for reuse and plugin override support.
+ */
+declare const buildHeader: (context: HeaderBuildContext) => HeaderElements;
+/**
+ * Attach header elements to the container, handling placement modes.
+ */
+declare const attachHeaderToContainer: (container: HTMLElement, headerElements: HeaderElements, config?: AgentWidgetConfig) => void;
+
+interface ComposerElements {
+    footer: HTMLElement;
+    suggestions: HTMLElement;
+    composerForm: HTMLFormElement;
+    textarea: HTMLTextAreaElement;
+    sendButton: HTMLButtonElement;
+    sendButtonWrapper: HTMLElement;
+    micButton: HTMLButtonElement | null;
+    micButtonWrapper: HTMLElement | null;
+    statusText: HTMLElement;
+}
+interface ComposerBuildContext {
+    config?: AgentWidgetConfig;
+    onSubmit?: (text: string) => void;
+    disabled?: boolean;
+}
+/**
+ * Build the composer/footer section of the panel.
+ * Extracted for reuse and plugin override support.
+ */
+declare const buildComposer: (context: ComposerBuildContext) => ComposerElements;
+
+interface HeaderLayoutContext {
+    config: AgentWidgetConfig;
+    showClose?: boolean;
+    onClose?: () => void;
+    onClearChat?: () => void;
+}
+type HeaderLayoutRenderer = (context: HeaderLayoutContext) => HeaderElements;
+/**
+ * Build default header layout
+ * Full header with icon, title, subtitle, clear chat, and close button
+ */
+declare const buildDefaultHeader: HeaderLayoutRenderer;
+/**
+ * Build minimal header layout
+ * Simplified layout with just title and close button
+ */
+declare const buildMinimalHeader: HeaderLayoutRenderer;
+/**
+ * Build expanded header layout
+ * Full branding area with additional space for custom content
+ */
+declare const buildExpandedHeader: HeaderLayoutRenderer;
+/**
+ * Header layout registry
+ * Maps layout names to their renderer functions
+ */
+declare const headerLayouts: Record<string, HeaderLayoutRenderer>;
+/**
+ * Get header layout renderer by name
+ */
+declare const getHeaderLayout: (layoutName: string) => HeaderLayoutRenderer;
+/**
+ * Build header based on layout configuration
+ * Applies layout config settings to determine which layout to use
+ */
+declare const buildHeaderWithLayout: (config: AgentWidgetConfig, layoutConfig?: AgentWidgetHeaderLayoutConfig, context?: Partial<HeaderLayoutContext>) => HeaderElements;
+
+export { type AgentWidgetAvatarConfig, AgentWidgetClient, type AgentWidgetConfig, type AgentWidgetController, type AgentWidgetCustomFetch, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeaderLayoutConfig, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetLayoutConfig, type AgentWidgetMessage, type AgentWidgetMessageLayoutConfig, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type AgentWidgetTimestampConfig, type ComponentContext, type ComponentDirective, type ComponentRenderer, type ComposerBuildContext, type ComposerElements, DEFAULT_WIDGET_CONFIG, type HeaderBuildContext, type HeaderElements, type HeaderLayoutContext, type HeaderLayoutRenderer, type HeaderRenderContext, type MessageRenderContext, type MessageTransform, type SlotRenderContext, type SlotRenderer, type WidgetLayoutSlot, attachHeaderToContainer, buildComposer, buildDefaultHeader, buildExpandedHeader, buildHeader, buildHeaderWithLayout, buildMinimalHeader, componentRegistry, createActionManager, createAgentExperience, createBubbleWithLayout, createComponentMiddleware, createComponentStreamParser, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createPlainTextParser, createRegexJsonParser, createStandardBubble, createTypingIndicator, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, getHeaderLayout, hasComponentDirective, headerLayouts, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, pluginRegistry, renderComponentDirective };