vanilla-agent 1.9.0 → 1.11.0

package/src/types.ts

@@ -156,6 +156,24 @@ export 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;
 };
 
 export type AgentWidgetLauncherConfig = {
@@ -170,6 +188,35 @@ export 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;
@@ -214,6 +261,7 @@ export type AgentWidgetSendButtonConfig = {
 
 export type AgentWidgetClearChatConfig = {
   enabled?: boolean;
+  placement?: "inline" | "top-right";
   iconName?: string;
   iconColor?: string;
   backgroundColor?: string;
@@ -339,10 +387,240 @@ export interface AgentWidgetStreamParser {
 }
 
 
+/**
+ * Component renderer function signature for custom components
+ */
+export type AgentWidgetComponentRenderer = (
+  props: Record<string, unknown>,
+  context: {
+    message: AgentWidgetMessage;
+    config: AgentWidgetConfig;
+    updateProps: (newProps: Record<string, unknown>) => void;
+  }
+) => HTMLElement;
+
+/**
+ * Result from custom SSE event parser
+ */
+export 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
+ */
+export type AgentWidgetSSEEventParser = (
+  eventData: unknown
+) => AgentWidgetSSEEventResult | Promise<AgentWidgetSSEEventResult>;
+
+/**
+ * Custom fetch function for full control over API requests
+ * Use this for custom authentication, request transformation, etc.
+ */
+export type AgentWidgetCustomFetch = (
+  url: string,
+  init: RequestInit,
+  payload: AgentWidgetRequestPayload
+) => Promise<Response>;
+
+/**
+ * Dynamic headers function - called before each request
+ */
+export type AgentWidgetHeadersFunction = () => Record<string, string> | Promise<Record<string, string>>;
+
+// ============================================================================
+// Layout Configuration Types
+// ============================================================================
+
+/**
+ * Context provided to header render functions
+ */
+export type HeaderRenderContext = {
+  config: AgentWidgetConfig;
+  onClose?: () => void;
+  onClearChat?: () => void;
+};
+
+/**
+ * Context provided to message render functions
+ */
+export type MessageRenderContext = {
+  message: AgentWidgetMessage;
+  config: AgentWidgetConfig;
+  streaming: boolean;
+};
+
+/**
+ * Context provided to slot render functions
+ */
+export type SlotRenderContext = {
+  config: AgentWidgetConfig;
+  defaultContent: () => HTMLElement | null;
+};
+
+/**
+ * Header layout configuration
+ * Allows customization of the header section appearance and behavior
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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;
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type AgentWidgetLayoutConfig = {
+  /** Header layout configuration */
+  header?: AgentWidgetHeaderLayoutConfig;
+  /** Message layout configuration */
+  messages?: AgentWidgetMessageLayoutConfig;
+  /** Slot renderers for custom content injection */
+  slots?: Partial<Record<WidgetLayoutSlot, SlotRenderer>>;
+};
+
 export 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;
@@ -374,6 +652,32 @@ export 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.
@@ -430,6 +734,83 @@ export 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;
 };
 
 export type AgentWidgetMessageRole = "user" | "assistant" | "system";