vanilla-agent 1.10.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;
@@ -396,6 +444,151 @@ type AgentWidgetCustomFetch = (url: string, init: RequestInit, payload: AgentWid
  * 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;
@@ -590,6 +783,21 @@ type AgentWidgetConfig = {
      * ```
      */
     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 = {
@@ -960,6 +1168,17 @@ type MessageTransform = (context: {
     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
@@ -1011,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 AgentWidgetCustomFetch, type AgentWidgetEvent, type AgentWidgetFeatureFlags, type AgentWidgetHeadersFunction, type AgentWidgetInitHandle, type AgentWidgetInitOptions, type AgentWidgetLauncherConfig, type AgentWidgetMessage, type AgentWidgetPlugin, type AgentWidgetRequestPayload, type AgentWidgetSSEEventParser, type AgentWidgetSSEEventResult, AgentWidgetSession, type AgentWidgetSessionStatus, type AgentWidgetStreamParser, type AgentWidgetStreamParserResult, type AgentWidgetTheme, type ComponentContext, type ComponentDirective, type ComponentRenderer, DEFAULT_WIDGET_CONFIG, componentRegistry, createActionManager, createAgentExperience, createComponentMiddleware, createComponentStreamParser, createFlexibleJsonStreamParser, createJsonStreamParser, createLocalStorageAdapter, createPlainTextParser, createRegexJsonParser, createXmlParser, initAgentWidget as default, defaultActionHandlers, defaultJsonActionParser, directivePostprocessor, escapeHtml, extractComponentDirectiveFromMessage, hasComponentDirective, initAgentWidget, isComponentDirectiveType, markdownPostprocessor, mergeWithDefaults, pluginRegistry, renderComponentDirective };
+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 };