@extrachill/chat 0.2.0

package/src/Chat.tsx

@@ -0,0 +1,157 @@
+import { type ReactNode } from 'react';
+import type { ChatMessage as ChatMessageType, ContentFormat } from './types/index.ts';
+import type { FetchFn } from './api.ts';
+import { useChat, type UseChatOptions } from './hooks/useChat.ts';
+import { ErrorBoundary } from './components/ErrorBoundary.tsx';
+import { AvailabilityGate } from './components/AvailabilityGate.tsx';
+import { ChatMessages } from './components/ChatMessages.tsx';
+import { ChatInput } from './components/ChatInput.tsx';
+import { TypingIndicator } from './components/TypingIndicator.tsx';
+import { SessionSwitcher } from './components/SessionSwitcher.tsx';
+
+export interface ChatProps {
+	/**
+	 * Base path for the chat REST endpoints.
+	 * e.g. '/datamachine/v1/chat'
+	 */
+	basePath: string;
+	/**
+	 * Fetch function for API calls. Must accept { path, method?, data? }
+	 * and return parsed JSON. @wordpress/api-fetch works directly.
+	 */
+	fetchFn: FetchFn;
+	/**
+	 * Agent ID to scope the chat to.
+	 */
+	agentId?: number;
+	/** Content format for message rendering. Defaults to 'markdown'. */
+	contentFormat?: ContentFormat;
+	/** Custom content renderer for messages. */
+	renderContent?: (content: string, role: ChatMessageType['role']) => ReactNode;
+	/** Whether to display tool call/result messages. Defaults to true. */
+	showTools?: boolean;
+	/** Map of tool function names to friendly display labels. */
+	toolNames?: Record<string, string>;
+	/** Placeholder text for the input. */
+	placeholder?: string;
+	/** Content shown when conversation is empty. */
+	emptyState?: ReactNode;
+	/** Initial messages (hydrated from server). */
+	initialMessages?: ChatMessageType[];
+	/** Initial session ID. */
+	initialSessionId?: string;
+	/** Maximum continuation turns. */
+	maxContinueTurns?: number;
+	/** Called when an error occurs. */
+	onError?: UseChatOptions['onError'];
+	/** Called when a new message is added. */
+	onMessage?: UseChatOptions['onMessage'];
+	/** Additional CSS class name on the root element. */
+	className?: string;
+	/** Whether to show the session switcher. Defaults to true. */
+	showSessions?: boolean;
+	/** Label shown during multi-turn processing. */
+	processingLabel?: (turnCount: number) => string;
+}
+
+/**
+ * Ready-to-use chat component.
+ *
+ * Composes all the primitives (messages, input, typing, sessions, etc.)
+ * into a complete chat experience. For full control, use the individual
+ * components and `useChat` hook directly.
+ *
+ * @example
+ * ```tsx
+ * import { Chat } from '@extrachill/chat';
+ * import apiFetch from '@wordpress/api-fetch';
+ *
+ * function StudioChat() {
+ *   return (
+ *     <Chat
+ *       basePath="/datamachine/v1/chat"
+ *       fetchFn={apiFetch}
+ *       agentId={5}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function Chat({
+	basePath,
+	fetchFn,
+	agentId,
+	contentFormat = 'markdown',
+	renderContent,
+	showTools = true,
+	toolNames,
+	placeholder,
+	emptyState,
+	initialMessages,
+	initialSessionId,
+	maxContinueTurns,
+	onError,
+	onMessage,
+	className,
+	showSessions = true,
+	processingLabel,
+}: ChatProps) {
+	const chat = useChat({
+		basePath,
+		fetchFn,
+		agentId,
+		initialMessages,
+		initialSessionId,
+		maxContinueTurns,
+		onError,
+		onMessage,
+	});
+
+	const baseClass = 'ec-chat';
+	const classes = [baseClass, className].filter(Boolean).join(' ');
+
+	return (
+		<ErrorBoundary onError={onError ? (err) => onError(err) : undefined}>
+			<div className={classes}>
+				<AvailabilityGate availability={chat.availability}>
+					{showSessions && (
+						<SessionSwitcher
+							sessions={chat.sessions}
+							activeSessionId={chat.sessionId ?? undefined}
+							onSelect={chat.switchSession}
+							onNew={chat.newSession}
+							onDelete={chat.deleteSession}
+							loading={chat.sessionsLoading}
+						/>
+					)}
+
+					<ChatMessages
+						messages={chat.messages}
+						contentFormat={contentFormat}
+						renderContent={renderContent}
+						showTools={showTools}
+						toolNames={toolNames}
+						emptyState={emptyState}
+					/>
+
+					<TypingIndicator
+						visible={chat.isLoading}
+						label={
+							chat.turnCount > 0
+								? (processingLabel
+									? processingLabel(chat.turnCount)
+									: `Processing turn ${chat.turnCount}...`)
+								: undefined
+						}
+					/>
+
+					<ChatInput
+						onSend={chat.sendMessage}
+						disabled={chat.isLoading}
+						placeholder={placeholder}
+					/>
+				</AvailabilityGate>
+			</div>
+		</ErrorBoundary>
+	);
+}

package/src/api.ts

@@ -0,0 +1,173 @@
+/**
+ * REST API client for the chat package.
+ *
+ * Speaks the standard chat REST contract natively. Any backend that
+ * implements the same endpoint shapes works out of the box.
+ *
+ * The `fetchFn` parameter allows consumers to plug in their own
+ * fetch implementation (e.g. @wordpress/api-fetch for cookie auth).
+ */
+
+import type { ChatMessage } from './types/message.ts';
+import type { ChatSession } from './types/session.ts';
+import type {
+	SendResponse,
+	ContinueResponse,
+	ListSessionsResponse,
+	GetSessionResponse,
+	DeleteSessionResponse,
+} from './types/api.ts';
+import { normalizeConversation, normalizeMessage, normalizeSession } from './normalizer.ts';
+
+/**
+ * A fetch-like function. Accepts path + options, returns parsed JSON.
+ *
+ * This matches @wordpress/api-fetch signature:
+ *   apiFetch({ path: '/datamachine/v1/chat', method: 'POST', data: {...} })
+ *
+ * For non-WordPress contexts, consumers wrap native fetch:
+ *   (opts) => fetch(baseUrl + opts.path, { method: opts.method, body: JSON.stringify(opts.data) }).then(r => r.json())
+ */
+export interface FetchOptions {
+	path: string;
+	method?: string;
+	data?: Record<string, unknown>;
+}
+
+export type FetchFn = (options: FetchOptions) => Promise<unknown>;
+
+export interface ChatApiConfig {
+	/** Base path for the chat endpoints (e.g. '/datamachine/v1/chat'). */
+	basePath: string;
+	/** The fetch function to use for requests. */
+	fetchFn: FetchFn;
+	/** Agent ID to scope sessions to. */
+	agentId?: number;
+}
+
+export interface SendResult {
+	sessionId: string;
+	messages: ChatMessage[];
+	completed: boolean;
+	turnNumber: number;
+	maxTurnsReached: boolean;
+}
+
+export interface ContinueResult {
+	messages: ChatMessage[];
+	completed: boolean;
+	turnNumber: number;
+	maxTurnsReached: boolean;
+}
+
+/**
+ * Send a user message (create or continue a session).
+ */
+export async function sendMessage(
+	config: ChatApiConfig,
+	content: string,
+	sessionId?: string,
+): Promise<SendResult> {
+	const body: Record<string, unknown> = { message: content };
+	if (sessionId) body.session_id = sessionId;
+	if (config.agentId) body.agent_id = config.agentId;
+
+	const raw = await config.fetchFn({
+		path: config.basePath,
+		method: 'POST',
+		data: body,
+	}) as SendResponse;
+
+	if (!raw.success) {
+		throw new Error((raw as unknown as { message?: string }).message ?? 'Failed to send message');
+	}
+
+	return {
+		sessionId: raw.data.session_id,
+		messages: normalizeConversation(raw.data.conversation),
+		completed: raw.data.completed,
+		turnNumber: raw.data.turn_number,
+		maxTurnsReached: raw.data.max_turns_reached,
+	};
+}
+
+/**
+ * Continue a multi-turn response.
+ */
+export async function continueResponse(
+	config: ChatApiConfig,
+	sessionId: string,
+): Promise<ContinueResult> {
+	const raw = await config.fetchFn({
+		path: `${config.basePath}/continue`,
+		method: 'POST',
+		data: { session_id: sessionId },
+	}) as ContinueResponse;
+
+	if (!raw.success) {
+		throw new Error((raw as unknown as { message?: string }).message ?? 'Failed to continue');
+	}
+
+	return {
+		messages: raw.data.new_messages.map(normalizeMessage),
+		completed: raw.data.completed,
+		turnNumber: raw.data.turn_number,
+		maxTurnsReached: raw.data.max_turns_reached,
+	};
+}
+
+/**
+ * List sessions for the current user.
+ */
+export async function listSessions(
+	config: ChatApiConfig,
+	limit = 20,
+): Promise<ChatSession[]> {
+	const params = new URLSearchParams({ limit: String(limit) });
+	if (config.agentId) params.set('agent_id', String(config.agentId));
+
+	const raw = await config.fetchFn({
+		path: `${config.basePath}/sessions?${params.toString()}`,
+	}) as ListSessionsResponse;
+
+	if (!raw.success) {
+		throw new Error('Failed to list sessions');
+	}
+
+	return raw.data.sessions.map(normalizeSession);
+}
+
+/**
+ * Load a single session's conversation.
+ */
+export async function loadSession(
+	config: ChatApiConfig,
+	sessionId: string,
+): Promise<ChatMessage[]> {
+	const raw = await config.fetchFn({
+		path: `${config.basePath}/${sessionId}`,
+	}) as GetSessionResponse;
+
+	if (!raw.success) {
+		throw new Error('Failed to load session');
+	}
+
+	return normalizeConversation(raw.data.conversation);
+}
+
+/**
+ * Delete a session.
+ */
+export async function deleteSession(
+	config: ChatApiConfig,
+	sessionId: string,
+): Promise<void> {
+	const raw = await config.fetchFn({
+		path: `${config.basePath}/${sessionId}`,
+		method: 'DELETE',
+	}) as DeleteSessionResponse;
+
+	if (!raw.success) {
+		throw new Error('Failed to delete session');
+	}
+}

package/src/components/AvailabilityGate.tsx

@@ -0,0 +1,85 @@
+import type { ReactNode } from 'react';
+import type { ChatAvailability } from '../types/index.ts';
+
+export interface AvailabilityGateProps {
+	/** Current availability state. */
+	availability: ChatAvailability;
+	/** Custom renderer for non-ready states. */
+	renderState?: (availability: ChatAvailability) => ReactNode;
+	/** Children to render when ready. */
+	children: ReactNode;
+}
+
+/**
+ * Gates chat UI behind availability states.
+ *
+ * When the adapter reports a non-ready state, this component renders
+ * an appropriate message instead of the chat. Consumers can override
+ * the default rendering with `renderState`.
+ */
+export function AvailabilityGate({
+	availability,
+	renderState,
+	children,
+}: AvailabilityGateProps) {
+	if (availability.status === 'ready') {
+		return <>{children}</>;
+	}
+
+	if (renderState) {
+		return <>{renderState(availability)}</>;
+	}
+
+	return <DefaultAvailabilityMessage availability={availability} />;
+}
+
+function DefaultAvailabilityMessage({ availability }: { availability: ChatAvailability }) {
+	const baseClass = 'ec-chat-availability';
+
+	switch (availability.status) {
+		case 'login-required':
+			return (
+				<div className={`${baseClass} ${baseClass}--login`}>
+					<p>Please log in to use the chat.</p>
+					{availability.loginUrl && (
+						<a href={availability.loginUrl} className={`${baseClass}__action`}>
+							Log in
+						</a>
+					)}
+				</div>
+			);
+
+		case 'unavailable':
+			return (
+				<div className={`${baseClass} ${baseClass}--unavailable`}>
+					<p>{availability.reason ?? 'Chat is currently unavailable.'}</p>
+				</div>
+			);
+
+		case 'provisioning':
+			return (
+				<div className={`${baseClass} ${baseClass}--provisioning`}>
+					<p>{availability.message ?? 'Setting up your chat...'}</p>
+				</div>
+			);
+
+		case 'upgrade-required':
+			return (
+				<div className={`${baseClass} ${baseClass}--upgrade`}>
+					<p>{availability.message ?? 'Upgrade required to access chat.'}</p>
+					{availability.upgradeUrl && (
+						<a href={availability.upgradeUrl} className={`${baseClass}__action`}>
+							Upgrade
+						</a>
+					)}
+				</div>
+			);
+
+		case 'error':
+			return (
+				<div className={`${baseClass} ${baseClass}--error`}>
+					<p>{availability.message}</p>
+				</div>
+			);
+	}
+}

package/src/components/ChatInput.tsx

@@ -0,0 +1,114 @@
+import { useState, useRef, useCallback, type KeyboardEvent, type FormEvent } from 'react';
+
+export interface ChatInputProps {
+	/** Called when the user submits a message. */
+	onSend: (content: string) => void;
+	/** Whether input is disabled (e.g. while waiting for response). */
+	disabled?: boolean;
+	/** Placeholder text. Defaults to 'Type a message...'. */
+	placeholder?: string;
+	/** Maximum number of rows the textarea auto-grows to. Defaults to 6. */
+	maxRows?: number;
+	/** Additional CSS class name. */
+	className?: string;
+}
+
+/**
+ * Chat input with auto-growing textarea and keyboard shortcuts.
+ *
+ * - Enter sends the message
+ * - Shift+Enter adds a newline
+ * - Textarea auto-grows up to `maxRows`
+ */
+export function ChatInput({
+	onSend,
+	disabled = false,
+	placeholder = 'Type a message...',
+	maxRows = 6,
+	className,
+}: ChatInputProps) {
+	const [value, setValue] = useState('');
+	const textareaRef = useRef<HTMLTextAreaElement>(null);
+	const cooldownRef = useRef(false);
+
+	const resize = useCallback(() => {
+		const el = textareaRef.current;
+		if (!el) return;
+		el.style.height = 'auto';
+		const lineHeight = parseInt(getComputedStyle(el).lineHeight) || 20;
+		const maxHeight = lineHeight * maxRows;
+		el.style.height = `${Math.min(el.scrollHeight, maxHeight)}px`;
+	}, [maxRows]);
+
+	const handleSubmit = useCallback((e?: FormEvent) => {
+		e?.preventDefault();
+		const trimmed = value.trim();
+		if (!trimmed || disabled || cooldownRef.current) return;
+
+		// Debounce to prevent double-submit
+		cooldownRef.current = true;
+		setTimeout(() => { cooldownRef.current = false; }, 300);
+
+		onSend(trimmed);
+		setValue('');
+
+		// Reset textarea height after clearing
+		requestAnimationFrame(() => {
+			const el = textareaRef.current;
+			if (el) el.style.height = 'auto';
+		});
+	}, [value, disabled, onSend]);
+
+	const handleKeyDown = useCallback((e: KeyboardEvent<HTMLTextAreaElement>) => {
+		if (e.key === 'Enter' && !e.shiftKey) {
+			e.preventDefault();
+			handleSubmit();
+		}
+	}, [handleSubmit]);
+
+	const baseClass = 'ec-chat-input';
+	const classes = [baseClass, className].filter(Boolean).join(' ');
+
+	return (
+		<form className={classes} onSubmit={handleSubmit}>
+			<textarea
+				ref={textareaRef}
+				className={`${baseClass}__textarea`}
+				value={value}
+				onChange={(e) => { setValue(e.target.value); resize(); }}
+				onKeyDown={handleKeyDown}
+				placeholder={placeholder}
+				disabled={disabled}
+				rows={1}
+				aria-label={placeholder}
+			/>
+			<button
+				className={`${baseClass}__send`}
+				type="submit"
+				disabled={disabled || !value.trim()}
+				aria-label="Send message"
+			>
+				<SendIcon />
+			</button>
+		</form>
+	);
+}
+
+function SendIcon() {
+	return (
+		<svg
+			className="ec-chat-input__send-icon"
+			viewBox="0 0 24 24"
+			width="20"
+			height="20"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth="2"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+		>
+			<line x1="22" y1="2" x2="11" y2="13" />
+			<polygon points="22 2 15 22 11 13 2 9 22 2" />
+		</svg>
+	);
+}

package/src/components/ChatMessage.tsx

@@ -0,0 +1,85 @@
+import { type ReactNode } from 'react';
+import type { ChatMessage as ChatMessageType, ContentFormat } from '../types/index.ts';
+
+export interface ChatMessageProps {
+	/** The message to render. */
+	message: ChatMessageType;
+	/** How to render message content. Defaults to 'markdown'. */
+	contentFormat?: ContentFormat;
+	/**
+	 * Custom content renderer. When provided, overrides contentFormat.
+	 * Use this to plug in your own markdown renderer (react-markdown, etc.).
+	 */
+	renderContent?: (content: string, role: ChatMessageType['role']) => ReactNode;
+	/** Additional CSS class name on the outer wrapper. */
+	className?: string;
+}
+
+/**
+ * Renders a single chat message bubble.
+ *
+ * User messages align right, assistant messages align left.
+ * Content rendering is pluggable via `renderContent` or `contentFormat`.
+ */
+export function ChatMessage({
+	message,
+	contentFormat = 'markdown',
+	renderContent,
+	className,
+}: ChatMessageProps) {
+	const isUser = message.role === 'user';
+	const baseClass = 'ec-chat-message';
+	const roleClass = isUser ? `${baseClass}--user` : `${baseClass}--assistant`;
+	const classes = [baseClass, roleClass, className].filter(Boolean).join(' ');
+
+	return (
+		<div className={classes} data-message-id={message.id}>
+			<div className={`${baseClass}__bubble`}>
+				{renderContent
+					? renderContent(message.content, message.role)
+					: <DefaultContent content={message.content} format={contentFormat} />
+				}
+			</div>
+			{message.timestamp && (
+				<time
+					className={`${baseClass}__timestamp`}
+					dateTime={message.timestamp}
+					title={new Date(message.timestamp).toLocaleString()}
+				>
+					{formatTime(message.timestamp)}
+				</time>
+			)}
+		</div>
+	);
+}
+
+interface DefaultContentProps {
+	content: string;
+	format: ContentFormat;
+}
+
+function DefaultContent({ content, format }: DefaultContentProps) {
+	if (format === 'html') {
+		return <div dangerouslySetInnerHTML={{ __html: content }} />;
+	}
+
+	// For 'text' and 'markdown' (without a custom renderer), render as text
+	// with basic paragraph splitting. Consumers should provide renderContent
+	// for proper markdown support.
+	return (
+		<>
+			{content.split('\n\n').map((paragraph, i) => (
+				<p key={i}>{paragraph}</p>
+			))}
+		</>
+	);
+}
+
+function formatTime(iso: string): string {
+	try {
+		const date = new Date(iso);
+		return date.toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' });
+	} catch {
+		return '';
+	}
+}