themelia-ui 1.0.0

package/.agents/skills/themelia-ui/references/components/features--ai-chat.md

@@ -0,0 +1,748 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+
+# `features/ai-chat`
+
+A conversational surface streams assistant messages, tool calls, artifacts and attachments.
+
+## Selection
+
+- **Use when:** A conversational surface streams assistant messages, tool calls, artifacts and attachments.
+- **Avoid when:** The thread is human discussion on a record, or the input is a single prompt field.
+- **Consider instead:** `features/comments`, `features/rich-text-editor`
+- **Stability:** stable.
+
+## Import
+
+```tsx fragment — import-only example
+import { AiAgent } from "themelia-ui/features/ai-chat"
+import "themelia-ui/features/ai-chat.css"
+```
+
+## Composition
+
+This family composes `base/badge`, `base/buttons`, `base/copyable`, `base/display`, `base/feedback`, `base/text-inputs`, `base/typography`, `base/upload`.
+
+Application policy—routing, fetching, persistence, permissions, and translation—stays
+outside the package and arrives through the public props, callbacks, slots, or accessors below.
+
+## Public declarations
+
+### `AiAgent`
+
+Kind: callable.
+
+```text
+({ name, icon, avatar, subtitle, tone, status, variant, trailing, className, strings, }: AiAgentProps) => import("react").JSX.Element
+```
+
+### `AiAgentStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `statusLabels` | yes | `Record<"idle" \| "thinking" \| "working" \| "done" \| "error" \| "offline", string>` |
+
+### `AiArtifact`
+
+Kind: callable.
+
+```text
+({ title, subtitle, icon, copyText, children, collapsed, onOpen, actions, onDownload, className, strings, }: AiArtifactProps) => import("react").JSX.Element
+```
+
+### `AiArtifactStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `openAria` | yes | `string` |
+| `copy` | yes | `string` |
+| `copied` | yes | `string` |
+| `copyAria` | yes | `string` |
+| `downloadAria` | yes | `string` |
+
+### `AiAttachment`
+
+Kind: callable.
+
+```text
+({ name, meta, kind, icon, thumbnailUrl, progress, errored, onOpen, onRemove, className, strings, }: AiAttachmentProps) => import("react").JSX.Element
+```
+
+### `AiAttachmentStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `removeAria` | yes | `string` |
+| `openAria` | yes | `string` |
+| `uploadProgressAria` | yes | `string` |
+
+### `AiChainOfThought`
+
+Kind: callable.
+
+```text
+({ steps, hideHeader, streaming, className, strings, }: AiChainOfThoughtProps) => import("react").JSX.Element
+```
+
+### `AiChainOfThoughtStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `streamingHint` | yes | `string` |
+
+### `AiChat`
+
+Kind: callable.
+
+```text
+({ messages, inputValue, onInputChange, onSubmit, onStop, streaming, disabled, attachments, onRemoveAttachment, onAttach, showAttach, agent, headerActions, queue, onCancelQueueItem, suggestions, onPickSuggestion, onMessageCopy, onMessageRegenerate, onAttachmentOpen, disableAutoScroll, slots, strings, className, }: AiChatProps<TSuggestionData>) => import("react").JSX.Element
+```
+
+### `AiChatAttachmentsStrip`
+
+Kind: callable.
+
+```text
+({ attachments, onRemove, onOpen, className, }: AiChatAttachmentsStripProps) => import("react").JSX.Element | null
+```
+
+### `AiChatAttachmentsStripProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `attachments` | yes | `readonly AiChatAttachment[]` |
+| `onRemove` | no | `(id: string) => void` |
+| `onOpen` | no | `(attachment: AiChatAttachment) => void` |
+| `className` | no | `string` |
+
+### `AiChatConversation`
+
+Kind: callable.
+
+```text
+({ messages, renderMessage, intro, footer, empty, disableAutoScroll, className, strings, }: AiChatConversationProps) => import("react").JSX.Element
+```
+
+### `AiChatConversationProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `messages` | yes | `readonly AiChatMessageData[]` |
+| `renderMessage` | yes | `(message: AiChatMessageData, context: AiChatRenderMessageContext) => ReactNode` |
+| `intro` | no | `ReactNode` |
+| `footer` | no | `ReactNode` |
+| `empty` | no | `ReactNode` |
+| `disableAutoScroll` | no | `boolean` |
+| `className` | no | `string` |
+| `strings` | no | `Partial<AiChatConversationStrings>` |
+
+### `AiChatConversationStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `transcriptAria` | yes | `string` |
+| `empty` | yes | `string` |
+| `scrollToBottom` | yes | `string` |
+| `scrollToBottomAria` | yes | `string` |
+
+### `AiChatEmptyState`
+
+Kind: callable.
+
+```text
+({ title, description, icon, below, className, }: AiChatEmptyStateProps) => import("react").JSX.Element
+```
+
+### `AiChatEmptyStateProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | no | `ReactNode` |
+| `description` | no | `ReactNode` |
+| `icon` | no | `ReactNode` |
+| `below` | no | `ReactNode` |
+| `className` | no | `string` |
+
+### `AiChatMessage`
+
+Kind: callable.
+
+```text
+({ message, onCopy, onRegenerate, onAttachmentOpen, className, strings, }: AiChatMessageProps) => import("react").JSX.Element
+```
+
+### `AiChatMessageProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `message` | yes | `AiChatMessageData` |
+| `onCopy` | no | `() => void` |
+| `onRegenerate` | no | `() => void` |
+| `onAttachmentOpen` | no | `(attachmentId: string) => void` |
+| `className` | no | `string` |
+| `strings` | no | `Partial<AiChatMessageStrings>` |
+
+### `AiChatMessageStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `pending` | yes | `string` |
+
+### `AiChatPromptInput`
+
+Kind: callable.
+
+```text
+({ value, onValueChange, onSubmit, onStop, streaming, disabled, attachments, onRemoveAttachment, onAttach, showAttach, leadingActions, trailingActions, hideHint, minRows, maxRows, autoFocus, submitKeyLabel, className, strings, }: AiChatPromptInputProps) => import("react").JSX.Element
+```
+
+### `AiChatPromptInputProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `value` | yes | `string` |
+| `onValueChange` | yes | `(value: string) => void` |
+| `onSubmit` | no | `(values: AiChatSubmitValues) => void` |
+| `onStop` | no | `() => void` |
+| `streaming` | no | `boolean` |
+| `disabled` | no | `boolean` |
+| `attachments` | no | `readonly AiChatAttachment[]` |
+| `onRemoveAttachment` | no | `(id: string) => void` |
+| `onAttach` | no | `() => void` |
+| `showAttach` | no | `boolean` |
+| `leadingActions` | no | `ReactNode` |
+| `trailingActions` | no | `ReactNode` |
+| `hideHint` | no | `boolean` |
+| `minRows` | no | `number` |
+| `maxRows` | no | `number` |
+| `autoFocus` | no | `boolean` |
+| `submitKeyLabel` | no | `string` |
+| `className` | no | `string` |
+| `strings` | no | `Partial<AiChatPromptInputStrings>` |
+
+### `AiChatPromptInputStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `placeholder` | yes | `string` |
+| `attachAria` | yes | `string` |
+| `submitAria` | yes | `string` |
+| `stopAria` | yes | `string` |
+| `hint` | yes | `string` |
+
+### `AiChatProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `messages` | yes | `readonly AiChatMessageData[]` |
+| `inputValue` | yes | `string` |
+| `onInputChange` | yes | `(value: string) => void` |
+| `onSubmit` | no | `(values: AiChatSubmitValues) => void` |
+| `onStop` | no | `() => void` |
+| `streaming` | no | `boolean` |
+| `disabled` | no | `boolean` |
+| `attachments` | no | `readonly AiChatAttachment[]` |
+| `onRemoveAttachment` | no | `(id: string) => void` |
+| `onAttach` | no | `() => void` |
+| `showAttach` | no | `boolean` |
+| `agent` | no | `AiChatAgent \| null` |
+| `headerActions` | no | `ReactNode` |
+| `queue` | no | `readonly AiChatQueueItem[]` |
+| `onCancelQueueItem` | no | `(id: string) => void` |
+| `suggestions` | no | `readonly AiChatSuggestion<TSuggestionData>[]` |
+| `onPickSuggestion` | no | `(suggestion: AiChatSuggestion<TSuggestionData>) => void` |
+| `onMessageCopy` | no | `(message: AiChatMessageData) => void` |
+| `onMessageRegenerate` | no | `(message: AiChatMessageData) => void` |
+| `onAttachmentOpen` | no | `(messageId: string, attachmentId: string) => void` |
+| `disableAutoScroll` | no | `boolean` |
+| `slots` | no | `AiChatSlots` |
+| `strings` | no | `Partial<AiChatStrings>` |
+| `className` | no | `string` |
+
+### `AiChatQueue`
+
+Kind: callable.
+
+```text
+({ items, hideHeader, onCancel, className, strings, }: AiChatQueueProps) => import("react").JSX.Element | null
+```
+
+### `AiChatQueueProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `items` | yes | `readonly AiChatQueueItem[]` |
+| `hideHeader` | no | `boolean` |
+| `onCancel` | no | `(id: string) => void` |
+| `className` | no | `string` |
+| `strings` | no | `Partial<AiChatQueueStrings>` |
+
+### `AiChatQueueStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `header` | yes | `string` |
+| `cancelAria` | yes | `string` |
+| `queuedLabel` | yes | `string` |
+| `runningLabel` | yes | `string` |
+
+### `AiChatStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `prompt` | yes | `AiChatPromptInputStrings` |
+| `conversation` | yes | `AiChatConversationStrings` |
+| `queue` | yes | `AiChatQueueStrings` |
+| `suggestions` | yes | `AiChatSuggestionsStrings` |
+| `message` | yes | `AiChatMessageStrings` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `AiChatSuggestionsRow`
+
+Kind: callable.
+
+```text
+({ suggestions, onPick, hideHeader, className, strings, }: AiChatSuggestionsRowProps<TData>) => import("react").JSX.Element | null
+```
+
+### `AiChatSuggestionsRowProps`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `suggestions` | yes | `readonly AiChatSuggestion<TData>[]` |
+| `onPick` | no | `(suggestion: AiChatSuggestion<TData>) => void` |
+| `hideHeader` | no | `boolean` |
+| `className` | no | `string` |
+| `strings` | no | `Partial<AiChatSuggestionsStrings>` |
+
+### `AiChatSuggestionsStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `header` | yes | `string` |
+
+### `AiCodeBlock`
+
+Kind: callable.
+
+```text
+({ code, language, filename, showLineNumbers, highlightLines, hideHeader, maxHeight, headerActions, onCopy, className, strings, }: AiCodeBlockProps) => import("react").JSX.Element
+```
+
+### `AiCodeBlockStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `copy` | yes | `string` |
+| `copied` | yes | `string` |
+| `copyAria` | yes | `string` |
+| `defaultLanguageLabel` | yes | `string` |
+
+### `AiConfirmation`
+
+Kind: callable.
+
+```text
+({ title, description, icon, tone, status, onApprove, onReject, approveLabel, rejectLabel, details, className, strings, }: AiConfirmationProps) => import("react").JSX.Element
+```
+
+### `AiConfirmationStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `approve` | yes | `string` |
+| `reject` | yes | `string` |
+| `pending` | yes | `string` |
+| `approved` | yes | `string` |
+| `rejected` | yes | `string` |
+| `detailsLabel` | yes | `string` |
+
+### `AiMessageBubble`
+
+Kind: callable.
+
+```text
+({ role, avatar, avatarLabel, authorName, timestamp, children, plainText, loading, onCopy, onRegenerate, className, strings, }: AiMessageBubbleProps) => import("react").JSX.Element
+```
+
+### `AiMessageBubbleStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `copyAria` | yes | `string` |
+| `copied` | yes | `string` |
+| `regenerateAria` | yes | `string` |
+
+### `AiReasoning`
+
+Kind: callable.
+
+```text
+({ children, streaming, durationSeconds, expandWhileStreaming, defaultExpanded, expanded: expandedProp, onExpandedChange, className, strings, }: AiReasoningProps) => import("react").JSX.Element
+```
+
+### `AiReasoningStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `thinking` | yes | `string` |
+| `thoughtFor` | yes | `string` |
+| `thoughtDone` | yes | `string` |
+| `expandAria` | yes | `string` |
+| `collapseAria` | yes | `string` |
+
+### `AiShimmer`
+
+Kind: callable.
+
+```text
+({ children, paused, duration, className, }: AiShimmerProps) => import("react").JSX.Element
+```
+
+### `AiSources`
+
+Kind: callable.
+
+```text
+({ sources, variant, maxAvatars, expanded: expandedProp, defaultExpanded, onExpandedChange, onSelect, className, strings, }: AiSourcesProps) => import("react").JSX.Element
+```
+
+### `AiSourcesStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `expand` | yes | `string` |
+| `collapse` | yes | `string` |
+| `visit` | yes | `string` |
+
+### `AiTask`
+
+Kind: callable.
+
+```text
+({ task, density, indent, className, strings, }: AiTaskProps) => import("react").JSX.Element
+```
+
+### `AiTaskStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `statusLabels` | yes | `Record<"queued" \| "running" \| "completed" \| "failed" \| "cancelled" \| "skipped", string>` |
+| `collapseSubtasks` | yes | `string` |
+| `expandSubtasks` | yes | `string` |
+
+### `AiToolCall`
+
+Kind: callable.
+
+```text
+({ name, status, icon, args, result, error, durationMs, expanded: expandedProp, defaultExpanded, onExpandedChange, className, strings, }: AiToolCallProps) => import("react").JSX.Element
+```
+
+### `AiToolCallStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `pending` | yes | `string` |
+| `running` | yes | `string` |
+| `success` | yes | `string` |
+| `error` | yes | `string` |
+| `expand` | yes | `string` |
+| `collapse` | yes | `string` |
+| `args` | yes | `string` |
+| `result` | yes | `string` |
+| `durationLabel` | yes | `string` |
+
+### `defaultAiAgentStrings`
+
+Kind: const.
+
+```text
+AiAgentStrings
+```
+
+### `defaultAiArtifactStrings`
+
+Kind: const.
+
+```text
+AiArtifactStrings
+```
+
+### `defaultAiAttachmentStrings`
+
+Kind: const.
+
+```text
+AiAttachmentStrings
+```
+
+### `defaultAiChainOfThoughtStrings`
+
+Kind: const.
+
+```text
+AiChainOfThoughtStrings
+```
+
+### `defaultAiChatConversationStrings`
+
+Kind: const.
+
+```text
+AiChatConversationStrings
+```
+
+### `defaultAiChatMessageStrings`
+
+Kind: const.
+
+```text
+AiChatMessageStrings
+```
+
+### `defaultAiChatPromptInputStrings`
+
+Kind: const.
+
+```text
+AiChatPromptInputStrings
+```
+
+### `defaultAiChatQueueStrings`
+
+Kind: const.
+
+```text
+AiChatQueueStrings
+```
+
+### `defaultAiChatStrings`
+
+Kind: const.
+
+```text
+AiChatStrings
+```
+
+### `defaultAiChatSuggestionsStrings`
+
+Kind: const.
+
+```text
+AiChatSuggestionsStrings
+```
+
+### `defaultAiCodeBlockStrings`
+
+Kind: const.
+
+```text
+AiCodeBlockStrings
+```
+
+### `defaultAiConfirmationStrings`
+
+Kind: const.
+
+```text
+AiConfirmationStrings
+```
+
+### `defaultAiMessageBubbleStrings`
+
+Kind: const.
+
+```text
+AiMessageBubbleStrings
+```
+
+### `defaultAiReasoningStrings`
+
+Kind: const.
+
+```text
+AiReasoningStrings
+```
+
+### `defaultAiSourcesStrings`
+
+Kind: const.
+
+```text
+AiSourcesStrings
+```
+
+### `defaultAiTaskStrings`
+
+Kind: const.
+
+```text
+AiTaskStrings
+```
+
+### `defaultAiToolCallStrings`
+
+Kind: const.
+
+```text
+AiToolCallStrings
+```
+
+### `useAiChatScroll`
+
+Kind: callable.
+
+```text
+({ threshold, dependency, disableAutoScroll, }?: UseAiChatScrollOptions) => UseAiChatScrollResult
+```
+
+### `UseAiChatScrollOptions`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `threshold` | no | `number` |
+| `dependency` | no | `unknown` |
+| `disableAutoScroll` | no | `boolean` |
+
+### `UseAiChatScrollResult`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `containerRef` | yes | `RefObject<HTMLDivElement \| null>` |
+| `endRef` | yes | `RefObject<HTMLDivElement \| null>` |
+| `isAtBottom` | yes | `boolean` |
+| `scrollToBottom` | yes | `(behavior?: ScrollBehavior) => void` |
+
+## Preview recipes
+
+Preview route: AI chat — `/ai-chat`
+
+### The chat
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<AiChat
+  messages={messages}
+  inputValue={input}
+  onInputChange={setInput}
+  onSubmit={({ text, attachments }) => send(text, attachments)}
+  onStop={() => abort()}
+  streaming={isStreaming}
+  agent={{ name: "Atlas", subtitle: "claude-opus-5", status: "thinking" }}
+  suggestions={suggestions}
+  onPickSuggestion={(s) => setInput(String(s.label))}
+/>
+```
+
+### A turn
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<AiMessageBubble role="assistant" authorName="Atlas" onRegenerate={retry}>
+  The totals are summed as floats.
+</AiMessageBubble>
+
+<AiShimmer>Thinking…</AiShimmer>
+```
+
+### Reasoning and plans
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<AiReasoning streaming={isThinking} durationSeconds={4}>
+  {trace}
+</AiReasoning>
+
+<AiChainOfThought steps={steps} streaming />
+<AiTask task={plan} />
+```
+
+### Tool calls
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<AiToolCall
+  name="search_codebase"
+  status="success"
+  durationMs={820}
+  args={JSON.stringify(args, null, 2)}
+  result={summary}
+/>
+```
+
+### What it produced
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<AiArtifact title="totals.ts" subtitle="TypeScript" copyText={code} onDownload={save}>
+  <AiCodeBlock code={code} language="TypeScript" showLineNumbers highlightLines={[2, 8]} />
+</AiArtifact>
+
+<AiSources sources={sources} defaultExpanded />
+<AiSources sources={sources} variant="avatars" />
+```
+
+### Asking first
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<AiConfirmation
+  title="Run the backfill on 4,102 invoices"
+  description="Rewrites every amount into cents. Not reversible."
+  tone="destructive"
+  status={status}
+  onApprove={approve}
+  onReject={reject}
+/>
+```