@coral-ai/chat 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eunsoo Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @coral-ai/chat
+
+Chat surface for Coral UI: `<Chat>`, `<Chat.Canvas>`, `<Chat.Messages>`, `<Chat.Input>`, agent registration, and streaming helpers.
+
+## Install
+
+```sh
+npm install @coral-ai/chat @coral-ai/markdown @coral-ai/bundleicons @fluentui/react-components @fluentui/react-icons react react-dom
+```
+
+Peer dependencies do not install transitively. Install all of the above explicitly.
+
+## Usage
+
+```tsx
+import { Chat, createHandler } from "@coral-ai/chat";
+
+const myHandler = createHandler(async ({ message }) => {
+  return { content: `You said: ${message}` };
+});
+
+<Chat
+  agents={{ default: { handler: myHandler } }}
+  agent="default"
+/>
+```
+
+See [coral-ai](https://github.com/mochimilk/coral-ai) for the full project.

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+import React, { ReactNode } from 'react';
+import { ChatFontSize, ChatFontFamily } from '@coral-ai/markdown';
+
+/** Agent registration — keyed by agent name; `"default"` is the catch-all. */
+type AgentConfig = {
+    handler: AgentHandler;
+};
+interface ChatCanvasProps {
+    /** Name of the agent from the `agents` map. Falls back to `"default"`. */
+    agent?: string;
+    /** Named agent handlers keyed by agent name. Use `"default"` for the catch-all. */
+    agents?: Record<string, AgentConfig>;
+    /** Stable conversation identifier, passed back in onMessageComplete. */
+    conversationId?: string;
+    /** Pre-load conversation history. */
+    initialMessages?: ChatMessage[];
+    /** System prompt prepended to every request (not shown in UI). */
+    systemPrompt?: string;
+    /** Called when the user sends a message. Return a string, async iterable, or ChatResponse. */
+    onSendMessage?: (input: string, history: ChatMessage[], attachments: File[]) => ReturnType<AgentHandler>;
+    /** Called after every completed assistant response. Use to persist messages. */
+    onMessageComplete?: (messages: ChatMessage[], conversationId?: string) => void;
+    /** Called on every message-state update (user append, streaming chunk, final). Use for live persistence. */
+    onMessagesChange?: (messages: ChatMessage[], conversationId?: string) => void;
+    /** Called when an error occurs during send. */
+    onError?: (err: unknown) => void;
+    /** Automatically sends this message once on mount. */
+    autoSendMessage?: string;
+    /** Override the thinking indicator text during generation. */
+    thinkingStatus?: string;
+    /** Called when the user clicks Stop. Use to abort your fetch/API call. */
+    onStop?: () => void;
+    children?: ReactNode;
+}
+declare const ChatCanvas: React.FC<ChatCanvasProps>;
+
+type ChatMessage = {
+    /** Stable identifier — generated automatically by Chat.Canvas. Used as React key. */
+    id?: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    /** Identifies the message type for custom renderer lookup via the `components` prop. */
+    type?: string;
+    /** Arbitrary data passed to the custom renderer for this message. */
+    metadata?: Record<string, unknown>;
+};
+/** A single chunk yielded by a streaming onSendMessage. */
+type ChatChunk = string | {
+    type: "reasoning";
+    content: string;
+} | {
+    type: "agent";
+    name: string;
+};
+type ChatResponse = string | AsyncIterable<ChatChunk> | {
+    content: string;
+    type?: string;
+    metadata?: Record<string, unknown>;
+};
+/** The typed handler signature engineers implement. */
+type ChatAttachment = {
+    id: string;
+    file: File;
+    /** Data URL — populated for image/* files only. */
+    preview?: string;
+};
+type AgentHandler = (input: string, history: ChatMessage[], attachments: File[]) => ChatResponse | Promise<ChatResponse>;
+/** Props passed to a custom message renderer. */
+type ChatMessageRendererProps = {
+    message: ChatMessage;
+    /** Sends a message back into the chat as the user. */
+    onReply: (content: string) => void;
+};
+type ChatComponents = Record<string, React.FC<ChatMessageRendererProps>>;
+interface ChatProps {
+    agent?: string;
+    /** Named agent handlers keyed by agent name. Use `"default"` for the catch-all. */
+    agents?: Record<string, AgentConfig>;
+    conversationId?: string;
+    initialMessages?: ChatMessage[];
+    systemPrompt?: string;
+    onSendMessage?: AgentHandler;
+    onMessageComplete?: (messages: ChatMessage[], conversationId?: string) => void;
+    /** Fires on every message-state update (user append, streaming chunk, final). Use for live persistence. */
+    onMessagesChange?: (messages: ChatMessage[], conversationId?: string) => void;
+    onError?: (err: unknown) => void;
+    autoSendMessage?: string;
+    onFeedback?: (messageIndex: number, rating: "up" | "down") => void;
+    onCopy?: (content: string) => void;
+    onNavigate?: (path: string) => void;
+    components?: ChatComponents;
+    thinkingStatus?: string;
+    onStop?: () => void;
+    /** Placeholder text for the chat input. @default "Type a message..." */
+    placeholder?: string;
+    /** Disables the entire input. */
+    disabled?: boolean;
+    /** Slot rendered at the left of the input toolbar. */
+    actionsStart?: React.ReactNode;
+    /** Slot rendered at the right of the input toolbar, just before Send/Stop. */
+    actionsEnd?: React.ReactNode;
+    /** Shown 24px above the input while messages is empty. */
+    emptyState?: React.ReactNode;
+    /**
+     * Clickable suggestion chips rendered below the input while the chat is empty.
+     * Clicking a chip sends that string as the user's message. Chips fade out once
+     * any message has been sent.
+     */
+    promptStarters?: string[];
+    /**
+     * Pass `null` to disable the chat's built-in surface motion (input slide to
+     * bottom + prompt-starter fade). Omit / leave undefined for default motion.
+     */
+    surfaceMotion?: null;
+    /** Font size for assistant message markdown. */
+    fontSize?: ChatFontSize;
+    /** Font family for assistant message markdown. */
+    fontFamily?: ChatFontFamily;
+}
+declare const Chat$1: React.FC<ChatProps>;
+
+interface ChatMessagesProps {
+    /**
+     * Custom renderers keyed by message type.
+     * Falls back to default markdown rendering if no match.
+     */
+    components?: ChatComponents;
+    /** Called when the user clicks thumbs-up on an assistant message. */
+    onFeedback?: (messageIndex: number, rating: "up" | "down") => void;
+    /** Called when the user copies an assistant message. */
+    onCopy?: (content: string) => void;
+    /** Called when the user clicks an internal link (href starts with "/"). */
+    onNavigate?: (path: string) => void;
+    /** Font size for assistant message markdown. */
+    fontSize?: ChatFontSize;
+    /** Font family for assistant message markdown. */
+    fontFamily?: ChatFontFamily;
+}
+declare const ChatMessages: React.FC<ChatMessagesProps>;
+
+interface ChatInputProps {
+    /** Current input value. Optional inside Chat.Canvas — auto-wired from context. */
+    value?: string;
+    /** Change handler. Optional inside Chat.Canvas — auto-wired from context. */
+    onChange?: (val: string) => void;
+    /** Called on Enter. Optional inside Chat.Canvas — auto-wired to sendMessage. */
+    onEnter?: () => void;
+    placeholder?: string;
+    /** Disabled state. */
+    disabled?: boolean;
+    style?: React.CSSProperties;
+    /** Slot rendered at the left of the bottom toolbar. */
+    actionsStart?: React.ReactNode;
+    /** Slot rendered at the right of the bottom toolbar, just before Send/Stop. */
+    actionsEnd?: React.ReactNode;
+    /** Override attachments when used outside a Chat.Canvas. */
+    attachments?: ChatAttachment[];
+    /** Override remove handler when used outside a Chat.Canvas. */
+    removeAttachment?: (id: string) => void;
+}
+declare const ChatInput: React.ForwardRefExoticComponent<ChatInputProps & React.RefAttributes<HTMLTextAreaElement>>;
+
+type ErrorCategory = "auth_billing" | "rate_limit" | "overloaded" | "bad_input" | "not_found" | "server_error" | "unknown";
+interface NormalizedError {
+    category: ErrorCategory;
+    message: string;
+}
+/**
+ * Normalizes raw errors from Anthropic, OpenAI, and Google Gemini into a
+ * common category + user-friendly message. Safe to call with any unknown value.
+ */
+declare function normalizeChatError$1(err: unknown): NormalizedError;
+interface ChatErrorProps {
+    /** Raw error thrown by your onSendMessage handler — any provider shape works. */
+    error: unknown;
+    /** Optional retry callback shown as a button. */
+    onRetry?: () => void;
+}
+declare const ChatError: React.FC<ChatErrorProps>;
+
+interface ChatCalloutProps {
+    message: string;
+    onRetry?: () => void;
+    className?: string;
+}
+declare const ChatCallout: React.FC<ChatCalloutProps>;
+
+type CreateHandlerOptions = {
+    /** Your backend endpoint. Receives POST { input, history, context }. */
+    endpoint: string;
+    /** Additional headers (e.g. Authorization). */
+    headers?: HeadersInit;
+};
+/**
+ * Wraps a fetch endpoint into an AgentHandler.
+ * The endpoint should stream newline-delimited responses where each line is either:
+ *   - A plain text chunk (yielded as a string)
+ *   - A JSON-encoded ChatChunk object (e.g. `{"type":"reasoning","content":"..."}`)
+ *   - An SSE `data: ...` line (the `data: ` prefix is stripped automatically)
+ *   - `[DONE]` to signal end-of-stream
+ *
+ * @example
+ * // main.tsx
+ * <CoralProvider agents={{ default: { handler: createHandler({ endpoint: '/api/chat' }) } }}>
+ */
+declare function createHandler$1({ endpoint, headers }: CreateHandlerOptions): AgentHandler;
+
+interface ChatContextValue {
+    sendMessage: (overrideInput?: string) => Promise<void>;
+    scrollToBottom: () => void;
+    /** Pre-binds navigator.clipboard.writeText + the onCopy prop callback. */
+    handleCopy: (content: string) => void;
+    messages: ChatMessage[];
+    setMessages: React.Dispatch<React.SetStateAction<ChatMessage[]>>;
+    input: string;
+    setInput: React.Dispatch<React.SetStateAction<string>>;
+    isTyping: boolean;
+    isRetrying: boolean;
+    isInterrupted: boolean;
+    streamingReasoning: string;
+    streamingAgentName?: string;
+    /** Forwarded from Chat.Canvas thinkingStatus prop so Chat.Messages can read it. */
+    thinkingStatus?: string;
+    chatError: unknown | null;
+    showScrollButton: boolean;
+    /** Called by Chat.Input to report its measured height so Canvas positions the scroll button. */
+    setInputHeight: (height: number) => void;
+    messagesContainerRef: React.RefObject<HTMLDivElement | null>;
+    /** Called by Chat.Messages on mount/unmount so Canvas can attach scroll listener lazily. */
+    registerMessagesContainer: (el: HTMLDivElement | null) => void;
+    bottomRef: React.RefObject<HTMLDivElement | null>;
+    lastUserInputRef: React.MutableRefObject<string>;
+    hasEverSentRef: React.MutableRefObject<boolean>;
+    shouldStopRef: React.MutableRefObject<boolean>;
+    attachments: ChatAttachment[];
+    addAttachments: (files: File[]) => void;
+    removeAttachment: (id: string) => void;
+    onStop?: () => void;
+}
+declare function useChatContext(): ChatContextValue;
+
+declare const Chat: typeof Chat$1 & {
+    Canvas: typeof ChatCanvas;
+    Messages: typeof ChatMessages;
+    Input: typeof ChatInput;
+    Error: typeof ChatError;
+    Callout: typeof ChatCallout;
+};
+declare const normalizeChatError: typeof normalizeChatError$1;
+declare const createHandler: typeof createHandler$1;
+
+export { type AgentConfig, type AgentHandler, Chat, type ChatAttachment, type ChatCanvasProps, type ChatChunk, type ChatComponents, type ChatErrorProps, type ChatInputProps, type ChatMessage, type ChatMessageRendererProps, type ChatMessagesProps, type ChatResponse, createHandler, normalizeChatError, useChatContext };