@colletdev/docs 0.2.18 → 0.2.20

package/components.md

@@ -5,7 +5,7 @@
 
 ## Overview
 
-Collet ships 52 components as Custom Elements (`<cx-*>`) with
+Collet ships 54 components as Custom Elements (`<cx-*>`) with
 framework wrappers for React, Vue, Svelte, and Angular.
 
 **npm packages:**
@@ -95,7 +95,7 @@ Grouped activity feed with expandable entries and status indicators.
 | summary | `string` | — |  |
 | action | `string` | — |  |
 | expanded | `boolean` | `false` |  |
-| parts | `string` | — |  |
+| parts | `string[] \| string` | — |  |
 
 ---
 
@@ -497,11 +497,86 @@ Import from `@colletdev/core/types`:
 
 ---
 
+### Chat
+
+Chat component.
+
+**Tag:** `<cx-chat>`  |  **Form:** no  |  **Slots:** header, footer  |  **Ref methods:** addMessage, scrollToBottom, clear, focus, addFiles, clearAttachments
+
+#### Import
+
+| Framework | Import |
+|-----------|--------|
+| React | `import { Chat } from '@colletdev/react'` |
+| Vue | `import { Chat } from '@colletdev/vue'` |
+| Svelte | `import Chat from '@colletdev/svelte/chat.svelte'` |
+| Angular | `import { CxChat } from '@colletdev/angular'` |
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | — |  |
+| shape | `'sharp' \| 'rounded'` | — |  |
+| layout | `'standard' \| 'compact' \| 'fullscreen'` | — |  |
+| size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | — |  |
+| height | `string` | — |  |
+| scrollbarShape | `string` | — |  |
+| scrollbarTrack | `string` | — |  |
+| turns | `ChatTurn[] \| string` | — |  |
+| typing | `'' \| 'typing'` | — |  |
+| typingSender | `string` | — |  |
+| inputShape | `string` | — |  |
+| inputPlaceholder | `string` | — |  |
+| inputDisabled | `boolean` | `false` |  |
+| inputMaxLength | `number` | `0` |  |
+| showActionButton | `boolean` | `false` |  |
+| label | `string` | — |  |
+| inputLabel | `string` | — |  |
+| submitLabel | `string` | — |  |
+| emptyState | `string` | — |  |
+| acceptFiles | `boolean` | `false` |  |
+| accept | `string` | — |  |
+| maxFileSize | `number` | `0` |  |
+| multipleFiles | `boolean` | `false` |  |
+
+#### Events
+
+| Event | React | Vue | Detail |
+|-------|-------|-----|--------|
+| `cx-submit` | `onSubmit` | `@cx-submit` | `ChatSubmitDetail` |
+| `cx-file-add` | `onFileAdd` | `@cx-file-add` | `FileAddDetail` |
+| `cx-file-remove` | `onFileRemove` | `@cx-file-remove` | `FileRemoveDetail` |
+| `cx-file-reject` | `onFileReject` | `@cx-file-reject` | `FileRejectDetail` |
+
+#### Ref Methods
+
+| Method | Description |
+|--------|-------------|
+| `addMessage(html: string): void` | Adds a pre-rendered message turn to the chat. |
+| `scrollToBottom()` | Scrolls the message area to the bottom. |
+| `clear()` | Clears all messages from the chat. |
+| `focus()` | Focuses the chat input textarea. |
+| `addFiles(files: FileList): void` | Adds files programmatically to the chat input. |
+| `clearAttachments()` | Removes all file attachments from the chat input. |
+
+#### Structured Types
+
+Import from `@colletdev/core/types`:
+
+- `ChatSubmitDetail`
+- `ChatTurn`
+- `FileAddDetail`
+- `FileRejectDetail`
+- `FileRemoveDetail`
+
+---
+
 ### ChatInput
 
 Multi-line text area optimized for chat message composition.
 
-**Tag:** `<cx-chat-input>`  |  **Form:** yes  |  **Ref methods:** focus
+**Tag:** `<cx-chat-input>`  |  **Form:** yes  |  **Ref methods:** focus, addFiles, getAttachments, clearAttachments
 
 #### Import
 
@@ -529,6 +604,10 @@ Multi-line text area optimized for chat message composition.
 | label | `string` | — |  |
 | maxLength | `number` | `0` |  |
 | slotted | `boolean` | `false` |  |
+| acceptFiles | `boolean` | `false` |  |
+| accept | `string` | — |  |
+| maxFileSize | `number` | `0` |  |
+| multipleFiles | `boolean` | `false` |  |
 
 #### Events
 
@@ -540,18 +619,28 @@ Multi-line text area optimized for chat message composition.
 | `cx-keyup` | `onKeyup` | `@cx-keyup` | `KeyboardDetail` |
 | `cx-submit` | `onSubmit` | `@cx-submit` | `ChatSubmitDetail` |
 | `cx-input` | `onInput` | `@cx-input` | `InputDetail` |
+| `cx-file-add` | `onFileAdd` | `@cx-file-add` | `FileAddDetail` |
+| `cx-file-remove` | `onFileRemove` | `@cx-file-remove` | `FileRemoveDetail` |
+| `cx-file-reject` | `onFileReject` | `@cx-file-reject` | `FileRejectDetail` |
 
 #### Ref Methods
 
 | Method | Description |
 |--------|-------------|
 | `focus()` | Focuses the textarea. |
+| `addFiles(files: FileList): void` | Adds files programmatically to the attachment tray. |
+| `getAttachments(): FileInfo[]` | Returns current attachments as FileInfo[]. |
+| `clearAttachments()` | Removes all file attachments. |
 
 #### Structured Types
 
 Import from `@colletdev/core/types`:
 
 - `ChatSubmitDetail`
+- `FileAddDetail`
+- `FileInfo`
+- `FileRejectDetail`
+- `FileRemoveDetail`
 - `FocusDetail`
 - `InputDetail`
 - `KeyboardDetail`
@@ -1120,7 +1209,7 @@ Chat message container with sender alignment and avatar.
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | id | `string` | — |  |
-| role | `'user' \| 'assistant'` | — |  |
+| messageRole | `string` | — |  |
 | variant | `'filled' \| 'ghost'` | — |  |
 | shape | `'sharp' \| 'rounded'` | — |  |
 | alignment | `'auto' \| 'start' \| 'end'` | — |  |
@@ -1153,7 +1242,7 @@ Grouped sequence of message parts (text, code, tool calls, thinking).
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | id | `string` | — |  |
-| role | `'user' \| 'assistant'` | — |  |
+| messageRole | `string` | — |  |
 | alignment | `'auto' \| 'start' \| 'end'` | — |  |
 | size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | — |  |
 | senderName | `string` | — |  |
@@ -1205,11 +1294,17 @@ MessageTimeline component.
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | id | `string` | — |  |
-| role | `string` | — |  |
-| alignment | `string` | — |  |
+| messageRole | `string` | — |  |
+| alignment | `'auto' \| 'start' \| 'end'` | — |  |
 | size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | — |  |
 | senderName | `string` | — |  |
-| events | `string` | — |  |
+| events | `TimelineEvent[] \| string` | — |  |
+
+#### Structured Types
+
+Import from `@colletdev/core/types`:
+
+- `TimelineEvent`
 
 ---
 
@@ -1426,6 +1521,45 @@ Import from `@colletdev/core/types`:
 
 ---
 
+### ScrollArea
+
+ScrollArea component.
+
+**Tag:** `<cx-scroll-area>`  |  **Form:** no  |  **Slots:** default  |  **Ref methods:** scrollToBottom, scrollToTop
+
+#### Import
+
+| Framework | Import |
+|-----------|--------|
+| React | `import { ScrollArea } from '@colletdev/react'` |
+| Vue | `import { ScrollArea } from '@colletdev/vue'` |
+| Svelte | `import ScrollArea from '@colletdev/svelte/scroll-area.svelte'` |
+| Angular | `import { CxScrollArea } from '@colletdev/angular'` |
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | — |  |
+| shape | `'sharp' \| 'rounded' \| 'pill'` | — |  |
+| track | `'with-track' \| 'floating'` | — |  |
+| axis | `'vertical' \| 'horizontal' \| 'both'` | — |  |
+| size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | — |  |
+| height | `string` | — |  |
+| label | `string` | — |  |
+| autoScroll | `string` | — |  |
+| newContentLabel | `string` | — |  |
+| logRole | `boolean` | `false` |  |
+
+#### Ref Methods
+
+| Method | Description |
+|--------|-------------|
+| `scrollToBottom()` | Scrolls content to the bottom. |
+| `scrollToTop()` | Scrolls content to the top. |
+
+---
+
 ### Scrollbar
 
 Custom-styled scrollbar container for overflow content.

package/messages.md

@@ -32,25 +32,24 @@ The outer container. Controls sender alignment, avatar, name, and timestamp.
 ```tsx
 import { MessageBubble } from '@colletdev/react';
 
-<MessageBubble role="assistant" senderName="Collet" avatar="/collet.svg">
+<MessageBubble messageRole="assistant" senderName="Collet">
   {/* MessageGroup(s) go here */}
 </MessageBubble>
 
-<MessageBubble role="user" senderName="Dan">
+<MessageBubble messageRole="user" senderName="Dan">
   {/* User message content */}
 </MessageBubble>
 ```
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `role` | `'user' \| 'assistant'` | `'user'` | Determines alignment and color |
+| `messageRole` | `'user' \| 'assistant'` | `'user'` | Determines alignment and color |
 | `senderName` | `string` | — | Name displayed above the bubble |
-| `avatar` | `string` | — | Avatar image URL |
 | `timestamp` | `string` | — | Timestamp text |
 | `variant` | `'filled' \| 'ghost'` | `'filled'` | Visual style |
 | `shape` | `'sharp' \| 'rounded'` | `'rounded'` | Border radius |
 
-**Alignment:** `role="user"` right-aligns, `role="assistant"` left-aligns.
+**Alignment:** `messageRole="user"` right-aligns, `messageRole="assistant"` left-aligns.
 
 ### MessageGroup
 
@@ -60,18 +59,17 @@ a group share edges (no gaps between them).
 ```tsx
 import { MessageGroup } from '@colletdev/react';
 
-<MessageGroup role="assistant">
-  <MessagePart kind="text">Here is what I found:</MessagePart>
-  <MessagePart kind="code-block" language="rust" filename="main.rs">
-    fn main() { println!("Hello"); }
-  </MessagePart>
-</MessageGroup>
+<MessageGroup messageRole="assistant" parts={[
+  '<div>Here is what I found:</div>',
+  '<pre><code>fn main() { println!("Hello"); }</code></pre>',
+]} />
 ```
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `role` | `'user' \| 'assistant'` | `'user'` | Color scheme |
+| `messageRole` | `'user' \| 'assistant'` | `'user'` | Color scheme |
 | `variant` | `'filled' \| 'ghost'` | `'filled'` | Visual style |
+| `parts` | `string[]` | `[]` | Pre-rendered part HTML strings |
 
 ### MessagePart
 
@@ -108,18 +106,17 @@ import { MessagePart } from '@colletdev/react';
   kind="tool-call"
   toolName="search_docs"
   toolArguments='{"query": "auth"}'
-  status="pending"
+  toolStatus="pending"
 />
 
 {/* Tool result */}
 <MessagePart
   kind="tool-result"
   toolName="search_docs"
-  status="success"
+  toolStatus="success"
   collapsible
->
-  Found 3 results...
-</MessagePart>
+  content="Found 3 results..."
+/>
 
 {/* Thinking indicator */}
 <MessagePart kind="thinking" thinkingLabel="Analyzing code..." />
@@ -136,10 +133,10 @@ The status is computed from child tool states — you don't set it manually.
 ```tsx
 import { ActivityGroup } from '@colletdev/react';
 
-<ActivityGroup label="Code analysis" status="running">
-  <MessagePart kind="tool-call" toolName="read_file" status="success" />
-  <MessagePart kind="tool-call" toolName="search_code" status="pending" />
-</ActivityGroup>
+<ActivityGroup summary="Code analysis" parts={[
+  '<div>pre-rendered tool-call HTML</div>',
+  '<div>pre-rendered tool-call HTML</div>',
+]} />
 ```
 
 | Status | Meaning | Visual |
@@ -239,10 +236,10 @@ function StreamingMessage() {
 
 ---
 
-## MessageTimeline (Rust-side reducer)
+## MessageTimeline (Event Reducer)
 
 For production chat UIs with tool calls, streaming, and complex turn lifecycle,
-Collet provides a Rust-side chronological reducer. This is the recommended way
+Collet provides a chronological event reducer. This is the recommended way
 to build AI assistant interfaces.
 
 **What it handles:**
@@ -253,74 +250,91 @@ to build AI assistant interfaces.
 - Duplicate tool result deduplication
 - Terminal turn immutability (completed/aborted turns reject new events)
 
-**Note:** MessageTimeline is currently Rust-side only. It renders directly to HTML
-via the SSR gallery. WASM/npm export is planned — see the project roadmap.
+**Available via WASM** — pass an `events` array and the reducer renders
+the full turn to HTML:
+
+```tsx
+import { MessageTimeline } from '@colletdev/react';
+import type { TimelineEvent } from '@colletdev/react';
+
+const events: TimelineEvent[] = [
+  { type: 'text-delta', id: 'p1', delta: 'Hello ', markdown: true },
+  { type: 'text-delta', id: 'p1', delta: '**world**' },
+  { type: 'thinking-start', id: 't1', label: 'Analyzing...' },
+  { type: 'thinking-done', id: 't1', label: 'Analysis complete' },
+  { type: 'tool-call-start', group_id: 'g1', call_id: 'c1',
+    tool_name: 'read_file', description: 'Reading main.rs' },
+  { type: 'tool-call-done', group_id: 'g1', call_id: 'c1' },
+  { type: 'tool-result', group_id: 'g1', result_id: 'r1', call_id: 'c1',
+    tool_name: 'read_file', content: 'fn main() {}', status: 'success' },
+  { type: 'code-block', id: 'cb1', code: 'fn main() {}',
+    language: 'rust', filename: 'main.rs' },
+];
+
+<MessageTimeline
+  messageRole="assistant"
+  senderName="Collet"
+  events={events}
+/>
 
 ---
 
 ## Complete Example
 
-A full AI assistant conversation with tool calls:
+A full AI assistant conversation using MessageTimeline's event reducer:
 
 ```tsx
-import {
-  MessageBubble, MessageGroup, MessagePart, ActivityGroup
-} from '@colletdev/react';
+import { Chat, MessageTimeline } from '@colletdev/react';
+import type { TimelineEvent } from '@colletdev/react';
 
 function Conversation() {
+  const assistantEvents: TimelineEvent[] = [
+    { type: 'thinking-start', id: 't1', label: 'Searching documentation...' },
+    { type: 'thinking-done', id: 't1', label: 'Searched documentation' },
+    { type: 'tool-call-start', group_id: 'g1', call_id: 'c1',
+      tool_name: 'search_docs', description: 'Searched Next.js setup guide' },
+    { type: 'tool-call-done', group_id: 'g1', call_id: 'c1' },
+    { type: 'tool-result', group_id: 'g1', result_id: 'r1', call_id: 'c1',
+      tool_name: 'search_docs', content: '3 results found', status: 'success' },
+    { type: 'text-done', id: 'p1', content: "Here's how to set up Collet in Next.js:\n\n1. Install the packages\n2. Add the Vite plugin\n3. Call `init()` in your root layout", markdown: true },
+    { type: 'code-block', id: 'cb1',
+      code: "import { init } from '@colletdev/core';\n\ninit();\n\nexport default function RootLayout({ children }) {\n  return <html><body>{children}</body></html>;\n}",
+      language: 'tsx', filename: 'app/layout.tsx' },
+  ];
+
   return (
-    <div style={{ maxWidth: '48rem', margin: '0 auto' }}>
-      {/* User message */}
-      <MessageBubble role="user" senderName="Dan">
-        <MessageGroup role="user">
-          <MessagePart kind="text">
-            How do I set up Collet in my Next.js app?
-          </MessagePart>
-        </MessageGroup>
+    <Chat height="h-[600px]" label="Collet assistant">
+      {/* User turn — simple text via MessageBubble */}
+      <MessageBubble messageRole="user" senderName="Dan">
+        <MessageGroup messageRole="user" parts={[
+          '<div>How do I set up Collet in my Next.js app?</div>'
+        ]} />
       </MessageBubble>
 
-      {/* Assistant response with tool calls */}
-      <MessageBubble role="assistant" senderName="Collet" avatar="/collet.svg">
-        <MessageGroup role="assistant">
-          {/* Thinking */}
-          <MessagePart kind="thinking" completed thinkingLabel="Searched documentation" />
-
-          {/* Tool activity */}
-          <ActivityGroup label="Documentation search" status="done">
-            <MessagePart
-              kind="tool-call"
-              toolName="search_docs"
-              status="success"
-              description="Searched Next.js setup guide"
-            />
-          </ActivityGroup>
-
-          {/* Response text with markdown */}
-          <MessagePart kind="text" markdown>
-            Here's how to set up Collet in Next.js:
-
-            1. Install the packages
-            2. Add the Vite plugin (or configure manually for Next.js)
-            3. Call `init()` in your root layout
-          </MessagePart>
-
-          {/* Code example */}
-          <MessagePart kind="code-block" language="tsx" filename="app/layout.tsx">
-{`import { init } from '@colletdev/core';
-
-init();
-
-export default function RootLayout({ children }) {
-  return <html><body>{children}</body></html>;
-}`}
-          </MessagePart>
-        </MessageGroup>
-      </MessageBubble>
-    </div>
+      {/* Assistant turn — event-driven via MessageTimeline */}
+      <MessageTimeline
+        messageRole="assistant"
+        senderName="Collet"
+        events={assistantEvents}
+      />
+    </Chat>
   );
 }
 ```
 
+Or use individual components for full control:
+
+```tsx
+import { MessageBubble, MessageGroup, MessagePart } from '@colletdev/react';
+
+<MessageBubble messageRole="assistant" senderName="Collet">
+  <MessageGroup messageRole="assistant" parts={[
+    MessagePart.render({ kind: 'text', content: 'Hello!', markdown: true }),
+    MessagePart.render({ kind: 'code-block', code: 'npm install', language: 'bash' }),
+  ]} />
+</MessageBubble>
+```
+
 ---
 
 ## Standalone Code Blocks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colletdev/docs",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "description": "Collet component library documentation — API reference, framework guides, and AI agent setup",
   "type": "module",
   "bin": {