@datalayer/agent-runtimes 0.0.2

package/lib/components/chat/components/base/ChatBase.d.ts

@@ -0,0 +1,285 @@
+import React, { type ReactNode } from 'react';
+import { type PoweredByTagProps } from '../elements/PoweredByTag';
+import type { ChatMessage } from '../../types/message';
+import type { TransportType } from '../../types/protocol';
+import type { FrontendToolDefinition } from '../../types/tool';
+/**
+ * Tool call status for tool rendering
+ */
+export type ToolCallStatus = 'inProgress' | 'executing' | 'complete' | 'error';
+/**
+ * Response callback type for human-in-the-loop interactions
+ */
+export type RespondCallback = (result: unknown) => void;
+/**
+ * Suggestion item for quick actions
+ */
+export interface Suggestion {
+    /** Display title for the suggestion */
+    title: string;
+    /** Message to send when clicked */
+    message: string;
+}
+/**
+ * Tool call render context passed to renderToolResult
+ */
+export interface ToolCallRenderContext {
+    /** Tool call ID */
+    toolCallId: string;
+    /** Tool name (e.g., "get_weather") */
+    toolName: string;
+    /** Alias for toolName */
+    name: string;
+    /** Tool arguments (may be incomplete during 'inProgress' status) */
+    args: Record<string, unknown>;
+    /** Tool result (only available when status is 'complete') */
+    result?: unknown;
+    /** Tool call status */
+    status: ToolCallStatus;
+    /** Error message if status is 'error' */
+    error?: string;
+    /**
+     * Callback to send response back to the agent (human-in-the-loop).
+     * Only available when status is 'executing'.
+     * Calling this resolves the tool call with the provided result.
+     */
+    respond?: RespondCallback;
+}
+/**
+ * Render function for tool results
+ */
+export type RenderToolResult = (context: ToolCallRenderContext) => ReactNode;
+/**
+ * Avatar configuration
+ */
+export interface AvatarConfig {
+    /** User avatar icon or image */
+    userAvatar?: ReactNode;
+    /** Assistant avatar icon or image */
+    assistantAvatar?: ReactNode;
+    /** System avatar icon or image */
+    systemAvatar?: ReactNode;
+    /** Avatar size in pixels */
+    avatarSize?: number;
+    /** User avatar background color */
+    userAvatarBg?: string;
+    /** Assistant avatar background color */
+    assistantAvatarBg?: string;
+    /** Show avatars */
+    showAvatars?: boolean;
+}
+/**
+ * Header button configuration
+ */
+export interface HeaderButtonsConfig {
+    /** Show new chat button */
+    showNewChat?: boolean;
+    /** Show clear button */
+    showClear?: boolean;
+    /** Show settings button */
+    showSettings?: boolean;
+    /** Callback when new chat clicked */
+    onNewChat?: () => void;
+    /** Callback when clear clicked */
+    onClear?: () => void;
+    /** Callback when settings clicked */
+    onSettings?: () => void;
+}
+/**
+ * Empty state configuration
+ */
+export interface EmptyStateConfig {
+    /** Custom empty state icon */
+    icon?: ReactNode;
+    /** Empty state title */
+    title?: string;
+    /** Empty state subtitle */
+    subtitle?: string;
+    /** Custom empty state renderer */
+    render?: () => ReactNode;
+}
+/**
+ * Streaming options for custom message handler.
+ * Enables streaming response support with chunk callbacks.
+ */
+export interface StreamingMessageOptions {
+    /** Callback for each chunk of streamed content */
+    onChunk?: (chunk: string) => void;
+    /** Callback when streaming is complete */
+    onComplete?: (fullResponse: string) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Custom message handler type for props-based mode.
+ * Supports both simple and streaming response patterns.
+ */
+export type MessageHandler = (message: string, messages: ChatMessage[], options?: StreamingMessageOptions) => Promise<string | void>;
+/**
+ * Model configuration
+ */
+export interface ModelConfig {
+    id: string;
+    name: string;
+    builtinTools?: string[];
+}
+/**
+ * Builtin tool configuration
+ */
+export interface BuiltinTool {
+    name: string;
+    id: string;
+}
+/**
+ * Remote configuration from server
+ */
+export interface RemoteConfig {
+    models: ModelConfig[];
+    builtinTools: BuiltinTool[];
+}
+/**
+ * Protocol configuration for ChatBase
+ */
+export interface ProtocolConfig {
+    /** Protocol/transport type */
+    type: TransportType;
+    /** Endpoint URL */
+    endpoint: string;
+    /** Authentication token */
+    authToken?: string;
+    /** Agent ID */
+    agentId?: string;
+    /** Enable config query for models and tools */
+    enableConfigQuery?: boolean;
+    /** Config endpoint URL for non-Jupyter protocols (if not set, uses Jupyter requestAPI) */
+    configEndpoint?: string;
+    /** Additional protocol options */
+    options?: Record<string, unknown>;
+}
+/**
+ * ChatBase props
+ */
+export interface ChatBaseProps {
+    /** Chat title */
+    title?: string;
+    /** Show header */
+    showHeader?: boolean;
+    /** Show loading indicator */
+    showLoadingIndicator?: boolean;
+    /** Show error messages */
+    showErrors?: boolean;
+    /** Show input area */
+    showInput?: boolean;
+    /** Show model selector (for protocols that support it) */
+    showModelSelector?: boolean;
+    /** Show tools menu (for protocols that support it) */
+    showToolsMenu?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Custom loading state */
+    loadingState?: React.ReactNode;
+    /** Header actions */
+    headerActions?: React.ReactNode;
+    /**
+     * Use Zustand store for state management.
+     * When true, uses the shared store. When false with protocol, uses protocol mode.
+     * @default true
+     */
+    useStore?: boolean;
+    /**
+     * Protocol configuration for connecting to backend.
+     * When provided and useStore is false, enables protocol mode.
+     */
+    protocol?: ProtocolConfig;
+    /**
+     * Custom message handler (for props-based mode).
+     * When provided, uses custom handler instead of store or protocol.
+     * Supports streaming via options callbacks.
+     */
+    onSendMessage?: MessageHandler;
+    /**
+     * Enable streaming mode for custom message handler.
+     * When true, will provide streaming callbacks to onSendMessage.
+     * @default false
+     */
+    enableStreaming?: boolean;
+    /** Custom brand icon for header */
+    brandIcon?: ReactNode;
+    /** Avatar configuration */
+    avatarConfig?: AvatarConfig;
+    /** Header buttons configuration */
+    headerButtons?: HeaderButtonsConfig;
+    /** Show powered by tag */
+    showPoweredBy?: boolean;
+    /** Powered by tag props */
+    poweredByProps?: Partial<PoweredByTagProps>;
+    /** Empty state configuration */
+    emptyState?: EmptyStateConfig;
+    /** Tool result renderer for tool calls */
+    renderToolResult?: RenderToolResult;
+    /** Custom footer content (rendered above input) */
+    footerContent?: ReactNode;
+    /** Custom header content (rendered below title row) */
+    headerContent?: ReactNode;
+    /** Children to render in the messages area (for custom content) */
+    children?: ReactNode;
+    /** Border radius for the panel container */
+    borderRadius?: string | number;
+    /** Panel background color */
+    backgroundColor?: string;
+    /** Border style */
+    border?: string;
+    /** Box shadow */
+    boxShadow?: string;
+    /** Compact mode (reduced padding) */
+    compact?: boolean;
+    /** Input placeholder override */
+    placeholder?: string;
+    /** Description shown in empty state (protocol mode) */
+    description?: string;
+    /** Callback for state updates (for shared state) */
+    onStateUpdate?: (state: unknown) => void;
+    /** Callback when new chat is triggered */
+    onNewChat?: () => void;
+    /** Callback when messages are cleared */
+    onClear?: () => void;
+    /** Callback when messages change (for tracking message count) */
+    onMessagesChange?: (messages: ChatMessage[]) => void;
+    /** Auto-focus the input on mount */
+    autoFocus?: boolean;
+    /**
+     * Suggestions to show in empty state.
+     * When clicked, the suggestion message is sent to the chat.
+     */
+    suggestions?: Suggestion[];
+    /**
+     * Whether to automatically submit the message when a suggestion is clicked.
+     * @default true
+     */
+    submitOnSuggestionClick?: boolean;
+    /**
+     * Whether to hide assistant messages that follow a rendered tool call UI.
+     * When true, assistant messages after tool UI are hidden to avoid duplicate information.
+     * @default false
+     */
+    hideMessagesAfterToolUI?: boolean;
+    /**
+     * Trigger to refocus the input field.
+     * When this value changes, the input will be focused.
+     * Useful for refocusing after view mode changes.
+     */
+    focusTrigger?: number;
+    /**
+     * Frontend tools to register with the agent.
+     * These tools execute in the browser and their results are sent back to the agent.
+     */
+    frontendTools?: FrontendToolDefinition[];
+}
+/**
+ * ChatBase component - Universal chat panel supporting store, protocol, and custom modes
+ */
+export declare function ChatBase({ title, showHeader, showLoadingIndicator, showErrors, showInput, showModelSelector, showToolsMenu, className, loadingState, headerActions, useStore: useStoreMode, protocol, onSendMessage, enableStreaming, brandIcon, avatarConfig, headerButtons, showPoweredBy, poweredByProps, emptyState, renderToolResult, footerContent, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact, placeholder, description, onStateUpdate, onNewChat, onClear, onMessagesChange, autoFocus, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, focusTrigger, frontendTools, }: ChatBaseProps): import("react/jsx-runtime").JSX.Element;
+export type { PoweredByTagProps };
+export default ChatBase;