@assistant-ui/mcp-docs-server 0.1.22 → 0.1.24

package/.docs/raw/docs/react-native/primitives.mdx

@@ -0,0 +1,653 @@
+---
+title: Primitives
+description: Composable React Native components for building chat UIs.
+---
+
+Primitives are thin wrappers around React Native components (`View`, `TextInput`, `FlatList`, `Pressable`) that integrate with the assistant-ui runtime. They accept all standard React Native props and add runtime-aware behavior.
+
+Many primitives share their core logic with `@assistant-ui/react` via `@assistant-ui/core/react` — only the UI layer (View/Pressable/Text vs DOM elements) differs.
+
+## Thread
+
+### ThreadRoot
+
+Container `View` for the thread area.
+
+```tsx
+import { ThreadRoot } from "@assistant-ui/react-native";
+
+<ThreadRoot style={{ flex: 1 }}>
+  {children}
+</ThreadRoot>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `...rest` | `ViewProps` | Standard React Native View props |
+
+### ThreadMessages
+
+`FlatList`-based message list with automatic runtime integration. Each message is wrapped in a scoped context so that `useAuiState((s) => s.message)` works inside `renderMessage`.
+
+```tsx
+import { ThreadMessages } from "@assistant-ui/react-native";
+
+<ThreadMessages
+  renderMessage={({ message }) => <MessageBubble message={message} />}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderMessage` | `(info: { message: ThreadMessage; index: number }) => ReactElement` | Message renderer |
+| `...rest` | `FlatListProps` | Standard FlatList props (except `data`, `renderItem`) |
+
+### ThreadEmpty
+
+Renders children only when the thread has no messages.
+
+```tsx
+import { ThreadEmpty } from "@assistant-ui/react-native";
+
+<ThreadEmpty>
+  <Text>Send a message to get started</Text>
+</ThreadEmpty>
+```
+
+### ThreadIf
+
+Conditional rendering based on thread state.
+
+```tsx
+import { ThreadIf } from "@assistant-ui/react-native";
+
+<ThreadIf empty>
+  <Text>No messages yet</Text>
+</ThreadIf>
+
+<ThreadIf running>
+  <ActivityIndicator />
+</ThreadIf>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `empty` | `boolean` | Render when thread is empty |
+| `running` | `boolean` | Render when thread is running |
+
+## Composer
+
+### ComposerRoot
+
+Container `View` for the composer area.
+
+```tsx
+import { ComposerRoot } from "@assistant-ui/react-native";
+
+<ComposerRoot style={styles.composerContainer}>
+  {children}
+</ComposerRoot>
+```
+
+### ComposerInput
+
+`TextInput` wired to the composer runtime. Value and `onChangeText` are managed automatically.
+
+```tsx
+import { ComposerInput } from "@assistant-ui/react-native";
+
+<ComposerInput
+  placeholder="Message..."
+  multiline
+  style={styles.input}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `...rest` | `TextInputProps` | Standard TextInput props (except `value`, `onChangeText`) |
+
+### ComposerSend
+
+`Pressable` that sends the current message. Automatically disabled when the composer is empty.
+
+```tsx
+import { ComposerSend } from "@assistant-ui/react-native";
+
+<ComposerSend style={styles.sendButton}>
+  <Text>Send</Text>
+</ComposerSend>
+```
+
+### ComposerCancel
+
+`Pressable` that cancels the current run. Automatically disabled when no run is active.
+
+```tsx
+import { ComposerCancel } from "@assistant-ui/react-native";
+
+<ComposerCancel style={styles.cancelButton}>
+  <Text>Stop</Text>
+</ComposerCancel>
+```
+
+### ComposerAttachments
+
+Renders composer attachments using the provided component configuration.
+
+```tsx
+import { ComposerAttachments } from "@assistant-ui/react-native";
+
+<ComposerAttachments
+  components={{
+    Image: MyImageAttachment,
+    Document: MyDocumentAttachment,
+    Attachment: MyFallbackAttachment, // fallback for all types
+  }}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `components` | `{ Image?, Document?, File?, Attachment? }` | Component renderers by attachment type |
+
+## Message
+
+### MessageRoot
+
+Container `View` for a single message.
+
+```tsx
+import { MessageRoot } from "@assistant-ui/react-native";
+
+<MessageRoot style={styles.messageBubble}>
+  {children}
+</MessageRoot>
+```
+
+### MessageContent
+
+Renders message content parts. Tool call and data parts automatically render registered tool UIs (via `useAssistantTool` / `useAssistantDataUI`), falling back to render props if provided.
+
+```tsx
+import { MessageContent } from "@assistant-ui/react-native";
+
+<MessageContent
+  renderText={({ part }) => <Text>{part.text}</Text>}
+  renderImage={({ part }) => <Image source={{ uri: part.image }} />}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderText` | `(props: { part; index }) => ReactElement` | Text part renderer |
+| `renderToolCall` | `(props: { part; index }) => ReactElement` | Tool call fallback (used when no tool UI is registered) |
+| `renderImage` | `(props: { part; index }) => ReactElement` | Image part renderer |
+| `renderReasoning` | `(props: { part; index }) => ReactElement` | Reasoning part renderer |
+| `renderSource` | `(props: { part; index }) => ReactElement` | Source part renderer |
+| `renderFile` | `(props: { part; index }) => ReactElement` | File part renderer |
+| `renderData` | `(props: { part; index }) => ReactElement` | Data part fallback (used when no data UI is registered) |
+
+### MessageIf
+
+Conditional rendering based on message properties.
+
+```tsx
+import { MessageIf } from "@assistant-ui/react-native";
+
+<MessageIf user>
+  <Text>You said:</Text>
+</MessageIf>
+
+<MessageIf assistant last>
+  <ActivityIndicator />
+</MessageIf>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `user` | `boolean` | Render for user messages |
+| `assistant` | `boolean` | Render for assistant messages |
+| `running` | `boolean` | Render when message is being generated |
+| `last` | `boolean` | Render for the last message |
+
+### MessageAttachments
+
+Renders user message attachments using the provided component configuration.
+
+```tsx
+import { MessageAttachments } from "@assistant-ui/react-native";
+
+<MessageAttachments
+  components={{
+    Image: MyImageAttachment,
+    Attachment: MyFallbackAttachment,
+  }}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `components` | `{ Image?, Document?, File?, Attachment? }` | Component renderers by attachment type |
+
+## Attachment
+
+Primitives for rendering individual attachments (inside `ComposerAttachments` or `MessageAttachments`).
+
+### AttachmentRoot
+
+Container `View` for an attachment.
+
+```tsx
+import { AttachmentRoot } from "@assistant-ui/react-native";
+
+<AttachmentRoot style={styles.attachment}>
+  {children}
+</AttachmentRoot>
+```
+
+### AttachmentName
+
+`Text` component displaying the attachment filename.
+
+```tsx
+import { AttachmentName } from "@assistant-ui/react-native";
+
+<AttachmentName style={styles.filename} />
+```
+
+### AttachmentThumb
+
+`Text` component displaying the file extension (e.g. `.pdf`).
+
+```tsx
+import { AttachmentThumb } from "@assistant-ui/react-native";
+
+<AttachmentThumb style={styles.extension} />
+```
+
+### AttachmentRemove
+
+`Pressable` that removes the attachment from the composer.
+
+```tsx
+import { AttachmentRemove } from "@assistant-ui/react-native";
+
+<AttachmentRemove>
+  <Text>Remove</Text>
+</AttachmentRemove>
+```
+
+## ActionBar
+
+### ActionBarCopy
+
+`Pressable` that copies the message content. Supports function-as-children for copy state feedback.
+
+```tsx
+import { ActionBarCopy } from "@assistant-ui/react-native";
+
+<ActionBarCopy copiedDuration={3000}>
+  {({ isCopied }) => <Text>{isCopied ? "Copied!" : "Copy"}</Text>}
+</ActionBarCopy>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `copiedDuration` | `number` | Duration in ms to show "copied" state (default: 3000) |
+| `copyToClipboard` | `(text: string) => void` | Custom clipboard function |
+
+### ActionBarEdit
+
+`Pressable` that enters edit mode for a message.
+
+```tsx
+import { ActionBarEdit } from "@assistant-ui/react-native";
+
+<ActionBarEdit>
+  <Text>Edit</Text>
+</ActionBarEdit>
+```
+
+### ActionBarReload
+
+`Pressable` that regenerates an assistant message.
+
+```tsx
+import { ActionBarReload } from "@assistant-ui/react-native";
+
+<ActionBarReload>
+  <Text>Retry</Text>
+</ActionBarReload>
+```
+
+### ActionBarFeedbackPositive / ActionBarFeedbackNegative
+
+`Pressable` buttons for submitting message feedback.
+
+```tsx
+import {
+  ActionBarFeedbackPositive,
+  ActionBarFeedbackNegative,
+} from "@assistant-ui/react-native";
+
+<ActionBarFeedbackPositive>
+  {({ isSubmitted }) => <Text>{isSubmitted ? "👍" : "👍🏻"}</Text>}
+</ActionBarFeedbackPositive>
+
+<ActionBarFeedbackNegative>
+  {({ isSubmitted }) => <Text>{isSubmitted ? "👎" : "👎🏻"}</Text>}
+</ActionBarFeedbackNegative>
+```
+
+## BranchPicker
+
+### BranchPickerPrevious / BranchPickerNext
+
+`Pressable` buttons to navigate between message branches.
+
+```tsx
+import {
+  BranchPickerPrevious,
+  BranchPickerNext,
+  BranchPickerNumber,
+  BranchPickerCount,
+} from "@assistant-ui/react-native";
+
+<View style={{ flexDirection: "row", alignItems: "center" }}>
+  <BranchPickerPrevious>
+    <Text>←</Text>
+  </BranchPickerPrevious>
+  <BranchPickerNumber />
+  <Text>/</Text>
+  <BranchPickerCount />
+  <BranchPickerNext>
+    <Text>→</Text>
+  </BranchPickerNext>
+</View>
+```
+
+### BranchPickerNumber / BranchPickerCount
+
+`Text` components displaying the current branch number and total count.
+
+## ThreadList
+
+### ThreadListRoot
+
+Container `View` for the thread list.
+
+```tsx
+import { ThreadListRoot } from "@assistant-ui/react-native";
+
+<ThreadListRoot style={styles.threadList}>
+  {children}
+</ThreadListRoot>
+```
+
+### ThreadListItems
+
+`FlatList` of thread IDs with runtime integration.
+
+```tsx
+import { ThreadListItems } from "@assistant-ui/react-native";
+
+<ThreadListItems
+  renderItem={({ threadId }) => (
+    <ThreadListEntry threadId={threadId} />
+  )}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `renderItem` | `(props: { threadId: string; index: number }) => ReactElement` | Thread item renderer |
+| `...rest` | `FlatListProps` | Standard FlatList props (except `data`, `renderItem`) |
+
+### ThreadListNew
+
+`Pressable` that creates a new thread.
+
+```tsx
+import { ThreadListNew } from "@assistant-ui/react-native";
+
+<ThreadListNew style={styles.newThreadButton}>
+  <Text>New Chat</Text>
+</ThreadListNew>
+```
+
+## ThreadListItem
+
+Primitives for rendering individual thread list items. Use inside a `ThreadListItemByIndexProvider` or within `ThreadListPrimitiveItems` components.
+
+### ThreadListItemRoot
+
+Container `View` for a thread list item.
+
+```tsx
+import { ThreadListItemRoot } from "@assistant-ui/react-native";
+
+<ThreadListItemRoot style={styles.threadItem}>
+  {children}
+</ThreadListItemRoot>
+```
+
+### ThreadListItemTitle
+
+Renders the thread title text. Falls back to the provided fallback when title is empty. This component is shared from `@assistant-ui/core/react`.
+
+```tsx
+import { ThreadListItemTitle } from "@assistant-ui/react-native";
+
+<ThreadListItemTitle fallback="New Chat" />
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `fallback` | `ReactNode` | Content to show when title is empty |
+
+### ThreadListItemTrigger
+
+`Pressable` that switches to the thread.
+
+```tsx
+import { ThreadListItemTrigger } from "@assistant-ui/react-native";
+
+<ThreadListItemTrigger>
+  <ThreadListItemTitle fallback="New Chat" />
+</ThreadListItemTrigger>
+```
+
+### ThreadListItemDelete
+
+`Pressable` that deletes the thread.
+
+```tsx
+import { ThreadListItemDelete } from "@assistant-ui/react-native";
+
+<ThreadListItemDelete>
+  <Text>Delete</Text>
+</ThreadListItemDelete>
+```
+
+### ThreadListItemArchive / ThreadListItemUnarchive
+
+`Pressable` buttons that archive or unarchive the thread.
+
+```tsx
+import {
+  ThreadListItemArchive,
+  ThreadListItemUnarchive,
+} from "@assistant-ui/react-native";
+
+<ThreadListItemArchive>
+  <Text>Archive</Text>
+</ThreadListItemArchive>
+
+<ThreadListItemUnarchive>
+  <Text>Unarchive</Text>
+</ThreadListItemUnarchive>
+```
+
+## Suggestion
+
+Primitives for rendering suggestions. Use inside a `SuggestionByIndexProvider` (from `@assistant-ui/core/react`).
+
+### SuggestionTitle
+
+`Text` component displaying the suggestion title.
+
+```tsx
+import { SuggestionTitle } from "@assistant-ui/react-native";
+
+<SuggestionTitle style={styles.suggestionTitle} />
+```
+
+### SuggestionDescription
+
+`Text` component displaying the suggestion description/label.
+
+```tsx
+import { SuggestionDescription } from "@assistant-ui/react-native";
+
+<SuggestionDescription style={styles.suggestionDescription} />
+```
+
+### SuggestionTrigger
+
+`Pressable` that triggers the suggestion action (send or insert into composer).
+
+```tsx
+import { SuggestionTrigger } from "@assistant-ui/react-native";
+
+<SuggestionTrigger send>
+  <SuggestionTitle />
+</SuggestionTrigger>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `send` | `boolean` | When true, sends immediately; when false, inserts into composer |
+| `clearComposer` | `boolean` | Whether to clear/replace composer text (default: true) |
+
+### ThreadSuggestion
+
+Inline `Pressable` that triggers a suggestion with a specified prompt. Use this when you want to hardcode suggestion text.
+
+```tsx
+import { ThreadSuggestion } from "@assistant-ui/react-native";
+
+<ThreadSuggestion prompt="Tell me a joke" send>
+  <Text>Tell me a joke</Text>
+</ThreadSuggestion>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `prompt` | `string` | The suggestion text |
+| `send` | `boolean` | When true, sends immediately |
+| `clearComposer` | `boolean` | Whether to clear/replace composer text (default: true) |
+
+### ThreadPrimitiveSuggestions
+
+Renders all suggestions from the store. Shared from `@assistant-ui/core/react`.
+
+```tsx
+import { ThreadPrimitiveSuggestions } from "@assistant-ui/react-native";
+
+<ThreadPrimitiveSuggestions
+  components={{ Suggestion: MySuggestionComponent }}
+/>
+```
+
+## ChainOfThought
+
+Primitives for rendering chain of thought content (grouped reasoning and tool-call parts).
+
+### ChainOfThoughtRoot
+
+Container `View` for chain of thought content.
+
+```tsx
+import { ChainOfThoughtRoot } from "@assistant-ui/react-native";
+
+<ChainOfThoughtRoot style={styles.chainOfThought}>
+  {children}
+</ChainOfThoughtRoot>
+```
+
+### ChainOfThoughtAccordionTrigger
+
+`Pressable` that toggles the collapsed state of the chain of thought.
+
+```tsx
+import { ChainOfThoughtAccordionTrigger } from "@assistant-ui/react-native";
+
+<ChainOfThoughtAccordionTrigger>
+  <Text>Toggle reasoning</Text>
+</ChainOfThoughtAccordionTrigger>
+```
+
+### ChainOfThoughtPrimitiveParts
+
+Renders the parts within a chain of thought. Shared from `@assistant-ui/core/react`.
+
+```tsx
+import { ChainOfThoughtPrimitiveParts } from "@assistant-ui/react-native";
+
+<ChainOfThoughtPrimitiveParts
+  components={{
+    Reasoning: ({ text }) => <Text>{text}</Text>,
+    tools: { Fallback: MyToolComponent },
+  }}
+/>
+```
+
+## Additional Composer Primitives
+
+### ComposerAddAttachment
+
+`Pressable` for triggering attachment addition. The actual file picker must be implemented by the consumer (e.g. using `expo-document-picker` or `expo-image-picker`).
+
+```tsx
+import { ComposerAddAttachment } from "@assistant-ui/react-native";
+
+<ComposerAddAttachment onPress={handlePickFile}>
+  <Text>📎</Text>
+</ComposerAddAttachment>
+```
+
+### ComposerIf
+
+Conditional rendering based on composer state. Shared from `@assistant-ui/core/react`.
+
+```tsx
+import { ComposerIf } from "@assistant-ui/react-native";
+
+<ComposerIf editing>
+  <Text>Currently editing</Text>
+</ComposerIf>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `editing` | `boolean` | Render when composer is in editing mode |
+| `dictation` | `boolean` | Render when dictation is active |
+
+## Shared Primitives from core/react
+
+The following primitives are shared with `@assistant-ui/react` via `@assistant-ui/core/react` and work identically on both platforms:
+
+- **`ThreadPrimitiveMessages`** / **`ThreadPrimitiveMessageByIndex`** — Component-composition pattern for rendering messages (alternative to the FlatList-based `ThreadMessages`)
+- **`MessagePrimitiveParts`** / **`MessagePrimitivePartByIndex`** — Renders message parts with grouping, ChainOfThought, and Empty support (alternative to the render-props-based `MessageContent`). Uses `<Text>` as default text renderer on RN.
+- **`ThreadPrimitiveSuggestions`** / **`ThreadPrimitiveSuggestionByIndex`** — Renders suggestions from the store
+- **`ThreadListPrimitiveItems`** / **`ThreadListPrimitiveItemByIndex`** — Component-composition pattern for thread list items (alternative to the FlatList-based `ThreadListItems`)
+- **`ChainOfThoughtPrimitiveParts`** — Renders chain of thought parts
+
+```tsx
+import {
+  ThreadPrimitiveMessages,
+  MessagePrimitiveParts,
+  ThreadPrimitiveSuggestions,
+} from "@assistant-ui/react-native";
+```