@extrachill/chat 0.2.0

package/src/components/ChatMessages.tsx

@@ -0,0 +1,193 @@
+import { useEffect, useRef, type ReactNode } from 'react';
+import type { ChatMessage as ChatMessageType, ContentFormat } from '../types/index.ts';
+import { ChatMessage } from './ChatMessage.tsx';
+import { ToolMessage, type ToolGroup } from './ToolMessage.tsx';
+
+export interface ChatMessagesProps {
+	/** All messages in the conversation. */
+	messages: ChatMessageType[];
+	/** How to render message content. Defaults to 'markdown'. */
+	contentFormat?: ContentFormat;
+	/** Custom content renderer passed through to ChatMessage. */
+	renderContent?: (content: string, role: ChatMessageType['role']) => ReactNode;
+	/** Whether to show tool call/result messages. Defaults to false. */
+	showTools?: boolean;
+	/** Custom tool name display map. Maps tool function names to friendly labels. */
+	toolNames?: Record<string, string>;
+	/** Whether to auto-scroll to bottom on new messages. Defaults to true. */
+	autoScroll?: boolean;
+	/** Placeholder content shown when there are no messages. */
+	emptyState?: ReactNode;
+	/** Additional CSS class name. */
+	className?: string;
+}
+
+/**
+ * Scrollable message list with auto-scroll behavior.
+ *
+ * Filters system messages, groups tool_call/tool_result pairs,
+ * and renders user/assistant messages as ChatMessage components.
+ */
+export function ChatMessages({
+	messages,
+	contentFormat,
+	renderContent,
+	showTools = false,
+	toolNames,
+	autoScroll = true,
+	emptyState,
+	className,
+}: ChatMessagesProps) {
+	const bottomRef = useRef<HTMLDivElement>(null);
+	const containerRef = useRef<HTMLDivElement>(null);
+
+	useEffect(() => {
+		if (autoScroll && bottomRef.current) {
+			bottomRef.current.scrollIntoView({ behavior: 'smooth' });
+		}
+	}, [messages, autoScroll]);
+
+	const displayItems = buildDisplayItems(messages, showTools);
+	const baseClass = 'ec-chat-messages';
+	const classes = [baseClass, className].filter(Boolean).join(' ');
+
+	if (displayItems.length === 0 && emptyState) {
+		return (
+			<div className={classes} ref={containerRef}>
+				<div className={`${baseClass}__empty`}>
+					{emptyState}
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className={classes} ref={containerRef}>
+			{displayItems.map((item) => {
+				if (item.type === 'message') {
+					return (
+						<ChatMessage
+							key={item.message.id}
+							message={item.message}
+							contentFormat={contentFormat}
+							renderContent={renderContent}
+						/>
+					);
+				}
+
+				if (item.type === 'tool-group' && showTools) {
+					return (
+						<ToolMessage
+							key={item.group.callMessage.id}
+							group={item.group}
+							toolNames={toolNames}
+						/>
+					);
+				}
+
+				return null;
+			})}
+			<div ref={bottomRef} />
+		</div>
+	);
+}
+
+type DisplayItem =
+	| { type: 'message'; message: ChatMessageType }
+	| { type: 'tool-group'; group: ToolGroup };
+
+/**
+ * Build display items from raw messages.
+ *
+ * - Filters out system messages
+ * - Groups tool_call + tool_result pairs
+ * - Returns ordered display items
+ */
+function buildDisplayItems(messages: ChatMessageType[], showTools: boolean): DisplayItem[] {
+	const items: DisplayItem[] = [];
+	const toolResultMap = new Map<string, ChatMessageType>();
+
+	// Pre-index tool results by tool name for pairing
+	if (showTools) {
+		for (const msg of messages) {
+			if (msg.role === 'tool_result' && msg.toolResult?.toolName) {
+				toolResultMap.set(msg.toolResult.toolName, msg);
+			}
+		}
+	}
+
+	const processedToolResults = new Set<string>();
+
+	for (const msg of messages) {
+		// Skip system messages
+		if (msg.role === 'system') continue;
+
+		// Skip tool messages when tools are hidden
+		if (!showTools && (msg.role === 'tool_call' || msg.role === 'tool_result')) continue;
+
+		// Handle user/assistant messages (assistant messages with toolCalls get both treatments)
+		if (msg.role === 'user' || msg.role === 'assistant') {
+			// If assistant message has tool calls, render the text part as a message
+			// and the tool calls as tool groups
+			if (msg.role === 'assistant' && msg.toolCalls?.length && showTools) {
+				// Only render text bubble if there's actual text content
+				if (msg.content.trim()) {
+					items.push({ type: 'message', message: msg });
+				}
+
+				for (const call of msg.toolCalls) {
+					const resultMsg = toolResultMap.get(call.name);
+					if (resultMsg) {
+						processedToolResults.add(resultMsg.id);
+					}
+
+					items.push({
+						type: 'tool-group',
+						group: {
+							callMessage: {
+								...msg,
+								content: '',
+								toolCalls: [call],
+							},
+							resultMessage: resultMsg ?? null,
+							toolName: call.name,
+							parameters: call.parameters,
+							success: resultMsg?.toolResult?.success ?? null,
+						},
+					});
+				}
+			} else {
+				items.push({ type: 'message', message: msg });
+			}
+			continue;
+		}
+
+		// Handle standalone tool_call messages
+		if (msg.role === 'tool_call' && showTools) {
+			const toolName = msg.toolCalls?.[0]?.name ?? 'unknown';
+			const resultMsg = toolResultMap.get(toolName);
+			if (resultMsg) {
+				processedToolResults.add(resultMsg.id);
+			}
+
+			items.push({
+				type: 'tool-group',
+				group: {
+					callMessage: msg,
+					resultMessage: resultMsg ?? null,
+					toolName,
+					parameters: msg.toolCalls?.[0]?.parameters ?? {},
+					success: resultMsg?.toolResult?.success ?? null,
+				},
+			});
+			continue;
+		}
+
+		// Handle orphaned tool_result messages
+		if (msg.role === 'tool_result' && showTools && !processedToolResults.has(msg.id)) {
+			items.push({ type: 'message', message: msg });
+		}
+	}
+
+	return items;
+}

package/src/components/ErrorBoundary.tsx

@@ -0,0 +1,66 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+
+export interface ErrorBoundaryProps {
+	/** Content to render when an error occurs. */
+	fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+	/** Called when an error is caught. */
+	onError?: (error: Error, errorInfo: ErrorInfo) => void;
+	/** Children to render. */
+	children: ReactNode;
+}
+
+interface ErrorBoundaryState {
+	error: Error | null;
+}
+
+/**
+ * Error boundary for the chat UI.
+ *
+ * Catches React render errors and shows a fallback UI with retry.
+ * Resets automatically when children change via key prop.
+ */
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+	override state: ErrorBoundaryState = { error: null };
+
+	static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+		return { error };
+	}
+
+	override componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+		this.props.onError?.(error, errorInfo);
+	}
+
+	reset = () => {
+		this.setState({ error: null });
+	};
+
+	override render() {
+		const { error } = this.state;
+		const { fallback, children } = this.props;
+
+		if (error) {
+			if (typeof fallback === 'function') {
+				return fallback(error, this.reset);
+			}
+
+			if (fallback) {
+				return fallback;
+			}
+
+			return (
+				<div className="ec-chat-error">
+					<p className="ec-chat-error__message">Something went wrong in the chat.</p>
+					<button
+						className="ec-chat-error__retry"
+						onClick={this.reset}
+						type="button"
+					>
+						Try again
+					</button>
+				</div>
+			);
+		}
+
+		return children;
+	}
+}

package/src/components/SessionSwitcher.tsx

@@ -0,0 +1,129 @@
+import type { ChatSession } from '../types/index.ts';
+
+export interface SessionSwitcherProps {
+	/** List of available sessions. */
+	sessions: ChatSession[];
+	/** Currently active session ID. */
+	activeSessionId?: string;
+	/** Called when a session is selected. */
+	onSelect: (sessionId: string) => void;
+	/** Called when the user wants to create a new session. */
+	onNew?: () => void;
+	/** Called when the user wants to delete a session. */
+	onDelete?: (sessionId: string) => void;
+	/** Whether sessions are currently loading. */
+	loading?: boolean;
+	/** Additional CSS class name. */
+	className?: string;
+}
+
+/**
+ * Session switcher dropdown.
+ *
+ * Renders a list of sessions with the active one highlighted.
+ * Only rendered when the adapter declares `capabilities.sessions = true`.
+ */
+export function SessionSwitcher({
+	sessions,
+	activeSessionId,
+	onSelect,
+	onNew,
+	onDelete,
+	loading = false,
+	className,
+}: SessionSwitcherProps) {
+	const baseClass = 'ec-chat-sessions';
+	const classes = [baseClass, className].filter(Boolean).join(' ');
+
+	return (
+		<div className={classes}>
+			<div className={`${baseClass}__header`}>
+				<span className={`${baseClass}__title`}>Conversations</span>
+				{onNew && (
+					<button
+						className={`${baseClass}__new`}
+						onClick={onNew}
+						aria-label="New conversation"
+						type="button"
+					>
+						+
+					</button>
+				)}
+			</div>
+
+			{loading && (
+				<div className={`${baseClass}__loading`}>Loading...</div>
+			)}
+
+			<ul className={`${baseClass}__list`} role="listbox" aria-label="Chat sessions">
+				{sessions.map((session) => {
+					const isActive = session.id === activeSessionId;
+					const itemClass = [
+						`${baseClass}__item`,
+						isActive ? `${baseClass}__item--active` : '',
+					].filter(Boolean).join(' ');
+
+					return (
+						<li
+							key={session.id}
+							className={itemClass}
+							role="option"
+							aria-selected={isActive}
+						>
+							<button
+								className={`${baseClass}__item-button`}
+								onClick={() => onSelect(session.id)}
+								type="button"
+							>
+								<span className={`${baseClass}__item-title`}>
+									{session.title ?? `Session ${session.id.slice(0, 8)}`}
+								</span>
+								<time
+									className={`${baseClass}__item-date`}
+									dateTime={session.updatedAt}
+								>
+									{formatRelativeDate(session.updatedAt)}
+								</time>
+							</button>
+							{onDelete && (
+								<button
+									className={`${baseClass}__item-delete`}
+									onClick={(e) => {
+										e.stopPropagation();
+										onDelete(session.id);
+									}}
+									aria-label={`Delete session ${session.title ?? session.id}`}
+									type="button"
+								>
+									\u00D7
+								</button>
+							)}
+						</li>
+					);
+				})}
+			</ul>
+		</div>
+	);
+}
+
+function formatRelativeDate(iso: string): string {
+	try {
+		const date = new Date(iso);
+		const now = new Date();
+		const diffMs = now.getTime() - date.getTime();
+		const diffMins = Math.floor(diffMs / 60_000);
+
+		if (diffMins < 1) return 'just now';
+		if (diffMins < 60) return `${diffMins}m ago`;
+
+		const diffHours = Math.floor(diffMins / 60);
+		if (diffHours < 24) return `${diffHours}h ago`;
+
+		const diffDays = Math.floor(diffHours / 24);
+		if (diffDays < 7) return `${diffDays}d ago`;
+
+		return date.toLocaleDateString();
+	} catch {
+		return '';
+	}
+}

package/src/components/ToolMessage.tsx

@@ -0,0 +1,112 @@
+import { useState } from 'react';
+import type { ChatMessage } from '../types/index.ts';
+
+/**
+ * A paired tool call + result for display.
+ */
+export interface ToolGroup {
+	/** The message containing the tool call. */
+	callMessage: ChatMessage;
+	/** The result message (null if still pending). */
+	resultMessage: ChatMessage | null;
+	/** Tool function name. */
+	toolName: string;
+	/** Parameters passed to the tool. */
+	parameters: Record<string, unknown>;
+	/** Whether the tool succeeded (null if pending). */
+	success: boolean | null;
+}
+
+export interface ToolMessageProps {
+	/** The tool call/result group to display. */
+	group: ToolGroup;
+	/** Map of tool names to friendly display labels. */
+	toolNames?: Record<string, string>;
+	/** Whether the tool details are initially expanded. Defaults to false. */
+	defaultExpanded?: boolean;
+	/** Additional CSS class name. */
+	className?: string;
+}
+
+/**
+ * Renders a collapsible tool call/result pair.
+ *
+ * Shows a summary line with the tool name (or friendly label),
+ * success/error indicator, and expandable details section.
+ */
+export function ToolMessage({
+	group,
+	toolNames,
+	defaultExpanded = false,
+	className,
+}: ToolMessageProps) {
+	const [expanded, setExpanded] = useState(defaultExpanded);
+
+	const displayName = toolNames?.[group.toolName] ?? formatToolName(group.toolName);
+	const baseClass = 'ec-chat-tool';
+	const statusClass = group.success === true
+		? `${baseClass}--success`
+		: group.success === false
+			? `${baseClass}--error`
+			: `${baseClass}--pending`;
+	const classes = [baseClass, statusClass, className].filter(Boolean).join(' ');
+
+	return (
+		<div className={classes}>
+			<button
+				className={`${baseClass}__header`}
+				onClick={() => setExpanded(!expanded)}
+				aria-expanded={expanded}
+				type="button"
+			>
+				<span className={`${baseClass}__icon`}>
+					{group.success === true ? '\u2713' : group.success === false ? '\u2717' : '\u2026'}
+				</span>
+				<span className={`${baseClass}__name`}>{displayName}</span>
+				<span className={`${baseClass}__chevron`}>{expanded ? '\u25B2' : '\u25BC'}</span>
+			</button>
+
+			{expanded && (
+				<div className={`${baseClass}__details`}>
+					{Object.keys(group.parameters).length > 0 && (
+						<div className={`${baseClass}__section`}>
+							<div className={`${baseClass}__section-label`}>Parameters</div>
+							<pre className={`${baseClass}__json`}>
+								{JSON.stringify(group.parameters, null, 2)}
+							</pre>
+						</div>
+					)}
+
+					{group.resultMessage && (
+						<div className={`${baseClass}__section`}>
+							<div className={`${baseClass}__section-label`}>Result</div>
+							<pre className={`${baseClass}__json`}>
+								{formatResult(group.resultMessage.content)}
+							</pre>
+						</div>
+					)}
+				</div>
+			)}
+		</div>
+	);
+}
+
+/**
+ * Convert snake_case tool name to a readable label.
+ */
+function formatToolName(name: string): string {
+	return name
+		.replace(/_/g, ' ')
+		.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Try to pretty-print JSON content, fall back to raw string.
+ */
+function formatResult(content: string): string {
+	try {
+		return JSON.stringify(JSON.parse(content), null, 2);
+	} catch {
+		return content;
+	}
+}

package/src/components/TypingIndicator.tsx

@@ -0,0 +1,36 @@
+export interface TypingIndicatorProps {
+	/** Whether the indicator is visible. */
+	visible: boolean;
+	/** Optional label text. Defaults to none (dots only). */
+	label?: string;
+	/** Additional CSS class name. */
+	className?: string;
+}
+
+/**
+ * Animated typing indicator with three bouncing dots.
+ *
+ * Renders as an assistant-style message bubble.
+ * The animation is pure CSS — no JS timers.
+ */
+export function TypingIndicator({
+	visible,
+	label,
+	className,
+}: TypingIndicatorProps) {
+	if (!visible) return null;
+
+	const baseClass = 'ec-chat-typing';
+	const classes = [baseClass, className].filter(Boolean).join(' ');
+
+	return (
+		<div className={classes} role="status" aria-label="Assistant is typing">
+			<div className={`${baseClass}__dots`}>
+				<span className={`${baseClass}__dot`} />
+				<span className={`${baseClass}__dot`} />
+				<span className={`${baseClass}__dot`} />
+			</div>
+			{label && <span className={`${baseClass}__label`}>{label}</span>}
+		</div>
+	);
+}

package/src/components/index.ts

@@ -0,0 +1,8 @@
+export { ChatMessage, type ChatMessageProps } from './ChatMessage.tsx';
+export { ChatMessages, type ChatMessagesProps } from './ChatMessages.tsx';
+export { ChatInput, type ChatInputProps } from './ChatInput.tsx';
+export { ToolMessage, type ToolMessageProps, type ToolGroup } from './ToolMessage.tsx';
+export { TypingIndicator, type TypingIndicatorProps } from './TypingIndicator.tsx';
+export { SessionSwitcher, type SessionSwitcherProps } from './SessionSwitcher.tsx';
+export { ErrorBoundary, type ErrorBoundaryProps } from './ErrorBoundary.tsx';
+export { AvailabilityGate, type AvailabilityGateProps } from './AvailabilityGate.tsx';

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useChat, type UseChatOptions, type UseChatReturn } from './useChat.ts';