## Overview [#overview]

Chat Elements are smaller composable pieces for AI chat interfaces. They are visual components only: consumers own messages, transport, persistence, tool state, and stream orchestration.

Use them when you want Cubitt styling and composition pieces without adopting a larger chat runtime contract.

<a href="/examples/chat">
  Open full chat example
</a>

## Usage [#usage]

```tsx
import {
  Conversation,
  Message,
  PromptInput,
} from "@tilt-legal/cubitt-components/chat-elements";
```

## Setup [#setup]

`MessageResponse` uses Streamdown for markdown rendering. Consumer apps need `streamdown` installed and should include Streamdown in Tailwind's source scan, with the path adjusted for their app:

```css
@source "../node_modules/streamdown/dist/*.js";
```

`PromptInput` owns its own transient composer state. No Chat Elements provider needs to be installed globally.

## Components [#components]

<Cards>
  <Card title="Conversation" href="./conversation">
    Scroll container, content layout, empty state, and scroll-to-bottom
    affordance.
  </Card>

  <Card title="Message" href="./message">
    User and assistant message shells, markdown responses, attachments, and
    actions.
  </Card>

  <Card title="Prompt Input" href="./prompt-input">
    Text editor form, submit state, action menu, attachment display, and speech
    composition.
  </Card>

  <Card title="Shimmer" href="./shimmer">
    Lightweight animated text for streaming or thinking states.
  </Card>

  <Card title="Task" href="./task">
    Collapsible task/progress rows for agent work.
  </Card>

  <Card title="Sources" href="./sources">
    Collapsible source lists for response-level references.
  </Card>

  <Card title="Inline Citation" href="./inline-citation">
    Inline cited text with preview-card and carousel source details.
  </Card>

  <Card title="Speech Input" href="./speech-input">
    Standalone voice capture button for dictation flows.
  </Card>
</Cards>

## Boundary [#boundary]

These components intentionally do not prescribe a message schema beyond small UI-facing prop types. Use your own chat hooks, AI SDK transport, backend routes, and persistence model, then pass the relevant values into the visual elements.

## API Reference [#api-reference]

### Shared Types [#shared-types]

These UI-facing types are exported from `@tilt-legal/cubitt-components/chat-elements` and are shared across the chat element pages.

#### UIMessage [#uimessage]

Minimal message shape used by message, conversation, and prompt examples.

| Field      | Type                                | Description                       |
| ---------- | ----------------------------------- | --------------------------------- |
| `id`       | `string`                            | Unique message id.                |
| `role`     | `"system" \| "user" \| "assistant"` | Message role.                     |
| `metadata` | `unknown`                           | Optional consumer-owned metadata. |
| `parts`    | `unknown[]`                         | Consumer-owned message parts.     |

#### FileUIPart [#fileuipart]

File part shape used when prompt attachments are submitted to consumers.

| Field              | Type                                               | Description                                        |
| ------------------ | -------------------------------------------------- | -------------------------------------------------- |
| `type`             | `"file"`                                           | File part discriminator.                           |
| `mediaType`        | `string`                                           | File MIME type.                                    |
| `filename`         | `string`                                           | Optional filename.                                 |
| `url`              | `string`                                           | File URL or data URL.                              |
| `providerMetadata` | `unknown`                                          | Optional provider-specific metadata.               |
| `name`             | `string`                                           | Optional display name inherited from file UI data. |
| `size`             | `number`                                           | Optional file size in bytes.                       |
| `sizeLabel`        | `string`                                           | Optional formatted size label.                     |
| `description`      | `string`                                           | Optional display description.                      |
| `badge`            | `React.ReactNode`                                  | Optional display badge.                            |
| `icon`             | `React.ReactNode`                                  | Optional display icon.                             |
| `thumbnailUrl`     | `string`                                           | Optional thumbnail URL.                            |
| `state`            | `"default" \| "loading" \| "uploading" \| "error"` | Optional display state.                            |
| `progress`         | `number`                                           | Optional upload/loading progress.                  |
| `disabled`         | `boolean`                                          | Optional disabled state.                           |
| `source`           | `unknown`                                          | Optional consumer source payload.                  |

`ChatFileUIPart` is an alias of `FileUIPart`.

#### ChatAttachmentFile [#chatattachmentfile]

Attachment file shape used by prompt and message attachment UI.

| Field       | Type                | Description                |
| ----------- | ------------------- | -------------------------- |
| `id`        | `string`            | Unique attachment id.      |
| file fields | `FileUIPart` fields | File display and URL data. |

`ChatAttachmentFileData` is the same shape with `id` optional, for attachment display cases where the consumer does not need a stable id.

#### SourceDocumentUIPart [#sourcedocumentuipart]

Source-document shape accepted by attachment and referenced-source APIs.

| Field              | Type                | Description                          |
| ------------------ | ------------------- | ------------------------------------ |
| `type`             | `"source-document"` | Source document discriminator.       |
| `mediaType`        | `string`            | Optional MIME type.                  |
| `title`            | `string`            | Optional source title.               |
| `filename`         | `string`            | Optional source filename.            |
| `url`              | `string`            | Optional source URL.                 |
| `providerMetadata` | `unknown`           | Optional provider-specific metadata. |

#### ChatStatus [#chatstatus]

Runtime status values accepted by prompt controls.

| Value          | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `"processing"` | The runtime has accepted the prompt and is preparing a response. |
| `"streaming"`  | The runtime is streaming a response.                             |