npm - themelia-ui - Versions diffs - 2.0.1 → 3.0.0 - Mend

themelia-ui 2.0.1 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1675) hide show

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

@@ -1,1187 +0,0 @@
-<!-- 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
-```
-### `AiAgentProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `name` | yes | `string` |  |
-| `icon` | no | `LucideIcon` |  |
-| `avatar` | no | `ReactNode` | Replaces the icon medallion — an image, a gradient mark. |
-| `subtitle` | no | `ReactNode` |  |
-| `tone` | no | `AiAgentTone` |  |
-| `status` | no | `AiAgentStatus` |  |
-| `variant` | no | `"inline" \| "card"` | `inline` is a single-line chip; `card` is a tile. |
-| `trailing` | no | `ReactNode` |  |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiAgentStrings>` |  |
-### `AiAgentStatus`
-Kind: type.
-```text
-"idle" | "thinking" | "working" | "done" | "error" | "offline"
-```
-### `AiAgentStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `statusLabels` | yes | `Record<"idle" \| "thinking" \| "working" \| "done" \| "error" \| "offline", string>` |  |
-### `AiAgentTone`
-Kind: type.
-```text
-Exclude<SemanticTone, "secondary">
-```
-### `AiArtifact`
-Kind: callable.
-```text
-({ title, subtitle, icon, copyText, children, collapsed, onOpen, actions, onDownload, className, strings, }: AiArtifactProps) => import("react").JSX.Element
-```
-### `AiArtifactAction`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `label` | yes | `string` |  |
-| `icon` | no | `LucideIcon` |  |
-| `onSelect` | no | `() => void` |  |
-### `AiArtifactProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `title` | yes | `ReactNode` |  |
-| `subtitle` | no | `ReactNode` |  |
-| `icon` | no | `LucideIcon` |  |
-| `copyText` | no | `string` |  |
-| `children` | no | `ReactNode` |  |
-| `collapsed` | no | `boolean` | Header only — the artifact as a chip that opens somewhere else. |
-| `onOpen` | no | `() => void` |  |
-| `actions` | no | `readonly AiArtifactAction[]` |  |
-| `onDownload` | no | `() => void` |  |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiArtifactStrings>` |  |
-### `AiArtifactStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `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
-```
-### `AiAttachmentKind`
-Kind: type.
-```text
-"image" | "document" | "audio" | "video" | "code" | "archive" | "generic"
-```
-### `AiAttachmentProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `name` | yes | `string` |  |
-| `meta` | no | `string` |  |
-| `kind` | no | `AiAttachmentKind` |  |
-| `icon` | no | `LucideIcon` |  |
-| `thumbnailUrl` | no | `string` | Renders the chip as a thumbnail tile. |
-| `progress` | no | `number` | 0–1. |
-| `errored` | no | `boolean` | Overrides progress. |
-| `onOpen` | no | `() => void` |  |
-| `onRemove` | no | `() => void` |  |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiAttachmentStrings>` |  |
-### `AiAttachmentStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `removeAria` | yes | `string` |  |
-| `openAria` | yes | `string` |  |
-| `uploadProgressAria` | yes | `string` |  |
-### `AiChainOfThought`
-Kind: callable.
-```text
-({ steps, hideHeader, streaming, className, strings, }: AiChainOfThoughtProps) => import("react").JSX.Element
-```
-### `AiChainOfThoughtProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `steps` | yes | `readonly AiChainStep[]` | Order is significant. |
-| `hideHeader` | no | `boolean` |  |
-| `streaming` | no | `boolean` |  |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiChainOfThoughtStrings>` |  |
-### `AiChainOfThoughtStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `title` | yes | `string` |  |
-| `streamingHint` | yes | `string` |  |
-### `AiChainStep`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `title` | yes | `ReactNode` |  |
-| `description` | no | `ReactNode` |  |
-| `status` | no | `AiChainStepStatus` |  |
-| `icon` | no | `LucideIcon` |  |
-| `body` | no | `ReactNode` | Anything the step produced — a tool call, a code block, sub-steps. |
-### `AiChainStepStatus`
-Kind: type.
-```text
-"pending" | "active" | "completed" | "failed"
-```
-### `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
-```
-### `AiChatAgent`
-Kind: type.
-Who is answering. Drives the header strip.
-```text
-Pick<AiAgentProps, "name" | "icon" | "avatar" | "subtitle" | "tone" | "status">
-```
-### `AiChatAttachment`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `name` | yes | `string` |  |
-| `meta` | no | `string` |  |
-| `kind` | no | `AiAttachmentKind` |  |
-| `icon` | no | `LucideIcon` |  |
-| `thumbnailUrl` | no | `string` |  |
-| `url` | no | `string` |  |
-| `progress` | no | `number` | 0–1, while it is still uploading. |
-| `errored` | no | `boolean` |  |
-### `AiChatAttachmentsStrip`
-Kind: callable.
-```text
-({ attachments, onRemove, onOpen, className, }: AiChatAttachmentsStripProps) => import("react").JSX.Element | null
-```
-### `AiChatAttachmentsStripProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `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 | description / documented default |
-| --- | :-: | --- | --- |
-| `messages` | yes | `readonly AiChatMessageData[]` | Oldest first. |
-| `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 | description / documented default |
-| --- | :-: | --- | --- |
-| `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 | description / documented default |
-| --- | :-: | --- | --- |
-| `title` | no | `ReactNode` |  |
-| `description` | no | `ReactNode` |  |
-| `icon` | no | `ReactNode` |  |
-| `below` | no | `ReactNode` | Under the body — a grid of starter prompts, usually. |
-| `className` | no | `string` |  |
-### `AiChatMessage`
-Kind: callable.
-One turn. Only the first run of text parts goes in a bubble (other parts bring their own
-chrome); parts before and after it keep their declared order around the bubble.
-```text
-({ message, onCopy, onRegenerate, onAttachmentOpen, className, strings, }: AiChatMessageProps) => import("react").JSX.Element
-```
-### `AiChatMessageData`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `role` | yes | `AiMessageRole` |  |
-| `authorName` | no | `string` | Falls back to a role-derived label in the bubble. |
-| `avatar` | no | `ReactNode` |  |
-| `timestamp` | no | `ReactNode` |  |
-| `parts` | yes | `readonly AiChatMessagePart[]` |  |
-| `loading` | no | `boolean` |  |
-| `pending` | no | `boolean` | Renders the shimmer INSTEAD of the parts — the turn before the first token. |
-| `trailing` | no | `ReactNode` | Under the bubble: a feedback row, a retry, a footnote. |
-### `AiChatMessagePart`
-Kind: type.
-One part of a message; a message is an ordered list of these.
-```text
-{ type: "text"; content: ReactNode; plain?: string; } | { type: "reasoning"; content: ReactNode; streaming?: boolean; durationSeconds?: number; } | { type: "chain-of-thought"; steps: readonly AiChainStep[]; streaming?: boolean; } | { type: "tool"; name: string; status: AiToolCallStatus; icon?: LucideIcon; args?: ReactNode; result?: ReactNode; error?: ReactNode; durationMs?: number; defaultExpanded?: boolean; } | { type: "code"; code: string; language?: string; filename?: string; showLineNumbers?: boolean; highlightLines?: readonly number[]; } | { type: "attachments"; items: readonly AiChatAttachment[]; } | { type: "sources"; items: readonly AiSourceItem[]; variant?: AiSourcesVariant; defaultExpanded?: boolean; } | { type: "task"; task: AiTaskItem; } | { type: "artifact"; title: ReactNode; subtitle?: ReactNode; icon?: LucideIcon; copyText?: string; body?: ReactNode; actions?: readonly AiArtifactAction[]; onOpen?: () => void; onDownload?: () => void; } | { type: "confirmation"; title: ReactNode; description?: ReactNode; tone?: AiConfirmationTone; status?: AiConfirmationStatus; details?: ReactNode; onApprove?: () => void; onReject?: () => void; } | { type: "custom"; render: () => ReactNode; }
-```
-### `AiChatMessageProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `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 | description / documented default |
-| --- | :-: | --- | --- |
-| `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 | description / documented default |
-| --- | :-: | --- | --- |
-| `value` | yes | `string` |  |
-| `onValueChange` | yes | `(value: string) => void` |  |
-| `onSubmit` | no | `(values: AiChatSubmitValues) => void` |  |
-| `onStop` | no | `() => void` |  |
-| `streaming` | no | `boolean` | Flips submit to stop. |
-| `disabled` | no | `boolean` |  |
-| `attachments` | no | `readonly AiChatAttachment[]` |  |
-| `onRemoveAttachment` | no | `(id: string) => void` |  |
-| `onAttach` | no | `() => void` |  |
-| `showAttach` | no | `boolean` | Defaults to showing whenever `onAttach` is given. |
-| `leadingActions` | no | `ReactNode` | Before the attach button — a model picker, usually. |
-| `trailingActions` | no | `ReactNode` | Before submit. |
-| `hideHint` | no | `boolean` |  |
-| `minRows` | no | `number` |  |
-| `maxRows` | no | `number` |  |
-| `autoFocus` | no | `boolean` |  |
-| `submitKeyLabel` | no | `string` | What the hint calls the submit key. |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<AiChatPromptInputStrings>` |  |
-### `AiChatPromptInputStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `placeholder` | yes | `string` |  |
-| `attachAria` | yes | `string` |  |
-| `submitAria` | yes | `string` |  |
-| `stopAria` | yes | `string` | Replaces the submit label while a response is streaming. |
-| `hint` | yes | `string` | `{{submitKey}}` and `{{newlineKey}}` are replaced by the real shortcuts. |
-### `AiChatProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `messages` | yes | `readonly AiChatMessageData[]` | Oldest first. |
-| `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` | `null` hides the header strip. |
-| `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
-```
-### `AiChatQueueItem`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `label` | yes | `ReactNode` |  |
-| `status` | no | `"queued" \| "running"` |  |
-| `onCancel` | no | `() => void` |  |
-### `AiChatQueueProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `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 | description / documented default |
-| --- | :-: | --- | --- |
-| `header` | yes | `string` |  |
-| `cancelAria` | yes | `string` |  |
-| `queuedLabel` | yes | `string` |  |
-| `runningLabel` | yes | `string` |  |
-### `AiChatRenderMessageContext`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `isLast` | yes | `boolean` |  |
-| `index` | yes | `number` |  |
-### `AiChatSlots`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `header` | no | `ReactNode` |  |
-| `intro` | no | `ReactNode` | Before the transcript — a welcome card, an agent introduction. |
-| `belowMessages` | no | `ReactNode` | After the transcript, before the composer. |
-| `empty` | no | `ReactNode` |  |
-| `queue` | no | `ReactNode` |  |
-| `suggestions` | no | `ReactNode` |  |
-| `input` | no | `ReactNode` |  |
-| `renderMessage` | no | `(message: AiChatMessage, context: AiChatRenderMessageContext) => ReactNode` | `null` skips the message entirely. |
-### `AiChatStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `prompt` | yes | `AiChatPromptInputStrings` |  |
-| `conversation` | yes | `AiChatConversationStrings` |  |
-| `queue` | yes | `AiChatQueueStrings` |  |
-| `suggestions` | yes | `AiChatSuggestionsStrings` |  |
-| `message` | yes | `AiChatMessageStrings` |  |
-| `emptyTitle` | yes | `string` |  |
-| `emptyDescription` | yes | `string` |  |
-### `AiChatSubmitValues`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `text` | yes | `string` |  |
-| `attachments` | yes | `readonly AiChatAttachment[]` |  |
-### `AiChatSuggestion`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `label` | yes | `ReactNode` |  |
-| `icon` | no | `LucideIcon` |  |
-| `data` | no | `TData` | Echoed back to `onPickSuggestion` — an id, a template, a whole request body. |
-### `AiChatSuggestionsRow`
-Kind: callable.
-```text
-({ suggestions, onPick, hideHeader, className, strings, }: AiChatSuggestionsRowProps<TData>) => import("react").JSX.Element | null
-```
-### `AiChatSuggestionsRowProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `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 | description / documented default |
-| --- | :-: | --- | --- |
-| `header` | yes | `string` |  |
-### `AiCodeBlock`
-Kind: callable.
-```text
-({ code, language, filename, showLineNumbers, highlightLines, hideHeader, maxHeight, headerActions, onCopy, className, strings, }: AiCodeBlockProps) => import("react").JSX.Element
-```
-### `AiCodeBlockProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `code` | yes | `string` |  |
-| `language` | no | `string` |  |
-| `filename` | no | `string` |  |
-| `showLineNumbers` | no | `boolean` |  |
-| `highlightLines` | no | `readonly number[]` | 1-indexed. |
-| `hideHeader` | no | `boolean` |  |
-| `maxHeight` | no | `number \| string` |  |
-| `headerActions` | no | `ReactNode` |  |
-| `onCopy` | no | `() => void` |  |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiCodeBlockStrings>` |  |
-### `AiCodeBlockStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `copy` | yes | `string` |  |
-| `copied` | yes | `string` |  |
-| `copyAria` | yes | `string` |  |
-| `defaultLanguageLabel` | yes | `string` | Header label when no language was given. |
-### `AiConfirmation`
-Kind: callable.
-```text
-({ title, description, icon, tone, status, onApprove, onReject, approveLabel, rejectLabel, details, className, strings, }: AiConfirmationProps) => import("react").JSX.Element
-```
-### `AiConfirmationProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `title` | yes | `ReactNode` |  |
-| `description` | no | `ReactNode` |  |
-| `icon` | no | `LucideIcon` |  |
-| `tone` | no | `AiConfirmationTone` |  |
-| `status` | no | `AiConfirmationStatus` | Set, the action row is replaced by the outcome. |
-| `onApprove` | no | `() => void` |  |
-| `onReject` | no | `() => void` |  |
-| `approveLabel` | no | `ReactNode` |  |
-| `rejectLabel` | no | `ReactNode` |  |
-| `details` | no | `ReactNode` |  |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiConfirmationStrings>` |  |
-### `AiConfirmationStatus`
-Kind: type.
-```text
-"pending" | "approved" | "rejected"
-```
-### `AiConfirmationStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `approve` | yes | `string` |  |
-| `reject` | yes | `string` |  |
-| `pending` | yes | `string` |  |
-| `approved` | yes | `string` |  |
-| `rejected` | yes | `string` |  |
-| `detailsLabel` | yes | `string` |  |
-### `AiConfirmationTone`
-Kind: type.
-```text
-Exclude<SemanticTone, "secondary" | "success">
-```
-### `AiMessageBubble`
-Kind: callable.
-```text
-({ role, avatar, avatarLabel, authorName, timestamp, children, plainText, loading, onCopy, onRegenerate, className, strings, }: AiMessageBubbleProps) => import("react").JSX.Element
-```
-### `AiMessageBubbleProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `role` | no | `AiMessageRole` |  |
-| `avatar` | no | `ReactNode` |  |
-| `avatarLabel` | no | `string` |  |
-| `authorName` | no | `ReactNode` |  |
-| `timestamp` | no | `ReactNode` |  |
-| `children` | no | `ReactNode` |  |
-| `plainText` | no | `string` | What the copy action writes. Without it, only a string body can be copied. |
-| `loading` | no | `boolean` |  |
-| `onCopy` | no | `() => void` |  |
-| `onRegenerate` | no | `() => void` |  |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiMessageBubbleStrings>` |  |
-### `AiMessageBubbleStrings`
-Kind: interface.
-Copy for the chat and every surface it is built from: one object per surface, each
-overridable where it is used, and nested in the chat's own object.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `copyAria` | yes | `string` |  |
-| `copied` | yes | `string` |  |
-| `regenerateAria` | yes | `string` |  |
-### `AiMessageRole`
-Kind: type.
-```text
-"assistant" | "user" | "system"
-```
-### `AiReasoning`
-Kind: callable.
-```text
-({ children, streaming, durationSeconds, expandWhileStreaming, defaultExpanded, expanded: expandedProp, onExpandedChange, className, strings, }: AiReasoningProps) => import("react").JSX.Element
-```
-### `AiReasoningProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `children` | no | `ReactNode` | The trace. A string is rendered pre-wrapped; anything else is rendered as given. |
-| `streaming` | no | `boolean` |  |
-| `durationSeconds` | no | `number` |  |
-| `expandWhileStreaming` | no | `boolean` | Opens while streaming and closes when it stops. |
-| `defaultExpanded` | no | `boolean` |  |
-| `expanded` | no | `boolean` |  |
-| `onExpandedChange` | no | `(expanded: boolean) => void` |  |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiReasoningStrings>` |  |
-### `AiReasoningStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `thinking` | yes | `string` |  |
-| `thoughtFor` | yes | `string` | `{{duration}}` is replaced by the formatted elapsed time. |
-| `thoughtDone` | yes | `string` | When no duration was recorded. |
-| `expandAria` | yes | `string` |  |
-| `collapseAria` | yes | `string` |  |
-### `AiShimmer`
-Kind: callable.
-```text
-({ children, paused, duration, className, }: AiShimmerProps) => import("react").JSX.Element
-```
-### `AiShimmerProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `children` | no | `ReactNode` | Defaults to the "Thinking…" placeholder. |
-| `paused` | no | `boolean` | Renders the text still, in the muted foreground. |
-| `duration` | no | `number` | Sweep duration, in seconds. |
-| `className` | no | `string` |  |
-### `AiSourceItem`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `title` | yes | `ReactNode` |  |
-| `url` | no | `string` |  |
-| `publisher` | no | `string` |  |
-| `faviconUrl` | no | `string` |  |
-| `snippet` | no | `ReactNode` | Shown only in the expanded list. |
-### `AiSources`
-Kind: callable.
-```text
-({ sources, variant, maxAvatars, expanded: expandedProp, defaultExpanded, onExpandedChange, onSelect, className, strings, }: AiSourcesProps) => import("react").JSX.Element
-```
-### `AiSourcesProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `sources` | yes | `readonly AiSourceItem[]` | Order is significant — the index is the number the reader sees. |
-| `variant` | no | `AiSourcesVariant` |  |
-| `maxAvatars` | no | `number` | How many favicons the strip shows before the "+N". |
-| `expanded` | no | `boolean` |  |
-| `defaultExpanded` | no | `boolean` |  |
-| `onExpandedChange` | no | `(expanded: boolean) => void` |  |
-| `onSelect` | no | `(source: AiSourceItem, index: number) => void` | Preferred over `url`, so a source can route inside the app. |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiSourcesStrings>` |  |
-### `AiSourcesStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `title` | yes | `string` | `{{count}}` is replaced by the number of sources. |
-| `expand` | yes | `string` |  |
-| `collapse` | yes | `string` |  |
-| `visit` | yes | `string` |  |
-### `AiSourcesVariant`
-Kind: type.
-```text
-"list" | "avatars"
-```
-### `AiTask`
-Kind: callable.
-```text
-({ task, density, indent, className, strings, }: AiTaskProps) => import("react").JSX.Element
-```
-### `AiTaskItem`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `title` | yes | `ReactNode` |  |
-| `status` | no | `AiTaskStatus` |  |
-| `children` | no | `readonly AiTaskItem[]` |  |
-| `icon` | no | `LucideIcon` |  |
-| `rightSlot` | no | `ReactNode` | A duration, a byte count — whatever the row's trailing lane should carry. |
-| `body` | no | `ReactNode` |  |
-### `AiTaskProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `task` | yes | `AiTaskItem` |  |
-| `density` | no | `"compact" \| "expanded"` | `compact` collapses the sub-tasks behind a toggle; `expanded` always shows them. |
-| `indent` | no | `number` | Indent per nesting level, as a multiple of `--space-xl`. |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiTaskStrings>` |  |
-### `AiTaskStatus`
-Kind: type.
-```text
-"queued" | "running" | "completed" | "failed" | "cancelled" | "skipped"
-```
-### `AiTaskStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `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
-```
-### `AiToolCallProps`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `name` | yes | `string` |  |
-| `status` | yes | `AiToolCallStatus` |  |
-| `icon` | no | `LucideIcon` |  |
-| `args` | no | `ReactNode` |  |
-| `result` | no | `ReactNode` |  |
-| `error` | no | `ReactNode` |  |
-| `durationMs` | no | `number` |  |
-| `expanded` | no | `boolean` |  |
-| `defaultExpanded` | no | `boolean` |  |
-| `onExpandedChange` | no | `(expanded: boolean) => void` |  |
-| `className` | no | `string` |  |
-| `strings` | no | `Partial<Strings.AiToolCallStrings>` |  |
-### `AiToolCallStatus`
-Kind: type.
-```text
-"pending" | "running" | "success" | "error"
-```
-### `AiToolCallStrings`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `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 | description / documented default |
-| --- | :-: | --- | --- |
-| `threshold` | no | `number` | Distance from the bottom, in pixels, still counted as "at the bottom". |
-| `dependency` | no | `unknown` | Re-runs the auto-scroll when this changes — normally the message count. |
-| `disableAutoScroll` | no | `boolean` |  |
-### `UseAiChatScrollResult`
-Kind: interface.
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `containerRef` | yes | `RefObject<HTMLDivElement \| null>` | The scroll viewport. |
-| `endRef` | yes | `RefObject<HTMLDivElement \| null>` | A sentinel at the very end of the content. |
-| `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}
-/>
-```