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

package/.docs/raw/docs/primitives/attachment.mdx

@@ -0,0 +1,216 @@
+---
+title: Attachment
+description: File and image attachment rendering for the composer and messages.
+---
+
+import { AttachmentSample } from "@/components/docs/samples/attachment";
+
+The Attachment primitive renders file and image attachments. It appears in two places: inside the composer for pending uploads (with a remove button), and inside messages for sent attachments (read-only). You provide the layout and styling.
+
+<Tabs items={["Preview", "Code"]}>
+  <Tab>
+    <AttachmentSample />
+  </Tab>
+  <Tab>
+```tsx
+import {
+  AttachmentPrimitive,
+  ComposerPrimitive,
+} from "@assistant-ui/react";
+import { XIcon } from "lucide-react";
+
+function ComposerAttachment() {
+  return (
+    <AttachmentPrimitive.Root className="flex items-center gap-2 rounded-lg border p-2">
+      <AttachmentPrimitive.unstable_Thumb className="flex size-10 items-center justify-center rounded bg-muted text-xs" />
+      <span className="text-sm">
+        <AttachmentPrimitive.Name />
+      </span>
+      <AttachmentPrimitive.Remove className="ml-auto rounded-full p-1 hover:bg-muted">
+        <XIcon className="size-3" />
+      </AttachmentPrimitive.Remove>
+    </AttachmentPrimitive.Root>
+  );
+}
+```
+  </Tab>
+</Tabs>
+
+## Quick Start
+
+An attachment inside a composer:
+
+```tsx
+import { AttachmentPrimitive, ComposerPrimitive } from "@assistant-ui/react";
+
+<ComposerPrimitive.Root>
+  <ComposerPrimitive.Attachments>
+    {() => <MyAttachment />}
+  </ComposerPrimitive.Attachments>
+  <ComposerPrimitive.Input placeholder="Ask anything..." />
+  <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
+</ComposerPrimitive.Root>
+```
+
+`Root` renders a `<div>`, `unstable_Thumb` renders a `<div>` showing the file extension with a leading dot (e.g., `.pdf`), `Name` renders plain text, and `Remove` renders a `<button>`.
+
+<Callout type="info">
+Runtime setup: primitives require runtime context. Wrap your UI in `AssistantRuntimeProvider` with a runtime (for example `useLocalRuntime(...)`). See [Pick a Runtime](/docs/runtimes/pick-a-runtime).
+</Callout>
+
+## Core Concepts
+
+### Two Contexts
+
+Attachments appear in two different contexts:
+
+- **Composer**: via `ComposerPrimitive.Attachments`. These are pending uploads that can be removed before sending.
+- **Messages**: via `MessagePrimitive.Attachments`. These are sent attachments, displayed read-only (the iterator renders attachments for user messages).
+
+The same `AttachmentPrimitive` parts work in both contexts. The difference is behavioral: `Remove` only works in the composer context.
+
+### Iterator Pattern
+
+You don't loop over attachments yourself. Instead, use the children render function:
+
+```tsx
+// Composer attachments
+<ComposerPrimitive.Attachments>
+  {({ attachment }) => {
+    if (attachment.type === "image") return <ImageAttachment />;
+    if (attachment.type === "document") return <DocumentAttachment />;
+    return <GenericAttachment />;
+  }}
+</ComposerPrimitive.Attachments>
+
+// Message attachments
+<MessagePrimitive.Attachments>
+  {({ attachment }) => {
+    if (attachment.type === "image") return <ImageAttachment />;
+    if (attachment.type === "document") return <DocumentAttachment />;
+    return <GenericAttachment />;
+  }}
+</MessagePrimitive.Attachments>
+```
+
+Each component receives its attachment context automatically, with no props to pass. `components` is deprecated — use the `children` render function instead.
+
+### Remove Button
+
+`Remove` calls the attachment runtime remove action. In composer attachments it removes the attachment from the pending message. In message attachments, this action is not supported and clicking `Remove` will throw `"Message attachments cannot be removed"`. Only render `Remove` in composer UIs.
+
+### Name as Text
+
+`Name` renders plain text with no wrapper element. Wrap it in a `<span>` or other element for styling:
+
+```tsx
+<span className="text-sm font-medium">
+  <AttachmentPrimitive.Name />
+</span>
+```
+
+## Parts
+
+### Root
+
+Container for a single attachment item. Renders a `<div>` element unless `asChild` is set.
+
+```tsx
+<AttachmentPrimitive.Root className="flex items-center gap-2 rounded-lg border p-2">
+  <AttachmentPrimitive.Name />
+</AttachmentPrimitive.Root>
+```
+
+### unstable_Thumb
+
+Thumbnail slot for attachment previews. Renders a `<div>` element unless `asChild` is set.
+
+```tsx
+<AttachmentPrimitive.unstable_Thumb className="flex size-10 items-center justify-center rounded bg-muted text-xs" />
+```
+
+### Name
+
+Renders the attachment filename text.
+
+```tsx
+<AttachmentPrimitive.Name />
+```
+
+### Remove
+
+Button that removes the current attachment when used in a removable attachment context. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<AttachmentPrimitive.Remove className="rounded-full p-1 hover:bg-muted">
+  <XIcon className="size-3" />
+</AttachmentPrimitive.Remove>
+```
+
+## Patterns
+
+### Composer Attachment with Remove
+
+```tsx
+function ComposerAttachmentItem() {
+  return (
+    <AttachmentPrimitive.Root className="flex items-center gap-2 rounded-lg border p-2">
+      <AttachmentPrimitive.unstable_Thumb className="flex size-10 items-center justify-center rounded bg-muted text-xs font-mono" />
+      <span className="min-w-0 flex-1 truncate text-sm">
+        <AttachmentPrimitive.Name />
+      </span>
+      <AttachmentPrimitive.Remove className="rounded-full p-1 hover:bg-muted">
+        <XIcon className="size-3" />
+      </AttachmentPrimitive.Remove>
+    </AttachmentPrimitive.Root>
+  );
+}
+
+<ComposerPrimitive.Root>
+  <ComposerPrimitive.Attachments
+    components={{ Attachment: ComposerAttachmentItem }}
+  />
+  <ComposerPrimitive.Input placeholder="Ask anything..." />
+  <ComposerPrimitive.Send>Send</ComposerPrimitive.Send>
+</ComposerPrimitive.Root>
+```
+
+### Message Attachment (Read-Only)
+
+```tsx
+function MessageAttachment() {
+  return (
+    <AttachmentPrimitive.Root className="flex items-center gap-2 rounded-lg border p-2">
+      <AttachmentPrimitive.unstable_Thumb className="flex size-10 items-center justify-center rounded bg-muted text-xs font-mono" />
+      <span className="text-sm">
+        <AttachmentPrimitive.Name />
+      </span>
+    </AttachmentPrimitive.Root>
+  );
+}
+```
+
+### Custom Layout with asChild
+
+```tsx
+<AttachmentPrimitive.Root asChild>
+  <li className="flex items-center gap-3 py-1">
+    <AttachmentPrimitive.unstable_Thumb className="size-8 rounded bg-muted text-xs" />
+    <span className="text-sm">
+      <AttachmentPrimitive.Name />
+    </span>
+  </li>
+</AttachmentPrimitive.Root>
+```
+
+## Relationship to Components
+
+The shadcn [Attachment](/docs/ui/attachment) component wraps these primitives with styled thumbnails, tooltip filenames, remove buttons, and image preview dialogs. Start there for a prebuilt attachment UI.
+
+## API Reference
+
+For full prop details on every part, see the [AttachmentPrimitive API Reference](/docs/api-reference/primitives/attachment).
+
+Related:
+- [ComposerPrimitive API Reference](/docs/api-reference/primitives/composer)
+- [MessagePrimitive API Reference](/docs/api-reference/primitives/message)

package/.docs/raw/docs/primitives/branch-picker.mdx

@@ -0,0 +1,221 @@
+---
+title: BranchPicker
+description: Navigate between message branches, which are alternative responses the user can flip through.
+---
+
+import { BranchPickerPrimitiveSample } from "@/components/docs/samples/branch-picker-primitive";
+import { BranchPickerPrimitive as BranchPickerPrimitiveDocs } from "@/generated/primitiveDocs";
+
+The BranchPicker primitive lets users navigate between message branches, which are alternative responses generated by editing a message or regenerating a reply. It's used alongside ActionBar inside message components.
+
+<Tabs items={["Preview", "Code"]}>
+  <Tab>
+    <BranchPickerPrimitiveSample />
+  </Tab>
+  <Tab>
+```tsx
+import {
+  BranchPickerPrimitive,
+  MessagePrimitive,
+} from "@assistant-ui/react";
+import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
+
+function AssistantMessage() {
+  return (
+    <MessagePrimitive.Root className="flex flex-col items-start gap-1">
+      <div className="rounded-2xl bg-muted px-4 py-2.5 text-sm">
+        <MessagePrimitive.Parts />
+      </div>
+      <BranchPickerPrimitive.Root className="inline-flex items-center gap-0.5 text-xs">
+        <BranchPickerPrimitive.Previous className="flex size-6 items-center justify-center rounded-md disabled:opacity-30">
+          <ChevronLeftIcon className="size-3.5" />
+        </BranchPickerPrimitive.Previous>
+        <span>
+          <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+        </span>
+        <BranchPickerPrimitive.Next className="flex size-6 items-center justify-center rounded-md disabled:opacity-30">
+          <ChevronRightIcon className="size-3.5" />
+        </BranchPickerPrimitive.Next>
+      </BranchPickerPrimitive.Root>
+    </MessagePrimitive.Root>
+  );
+}
+```
+  </Tab>
+</Tabs>
+
+## Quick Start
+
+Minimal example:
+
+```tsx
+import { BranchPickerPrimitive } from "@assistant-ui/react";
+
+<BranchPickerPrimitive.Root>
+  <BranchPickerPrimitive.Previous>←</BranchPickerPrimitive.Previous>
+  <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+  <BranchPickerPrimitive.Next>→</BranchPickerPrimitive.Next>
+</BranchPickerPrimitive.Root>
+```
+
+`Root` renders a `<div>`, `Previous` and `Next` render `<button>` elements that auto-disable at boundaries. `Number` and `Count` render plain text (the current branch index and total count).
+
+<Callout type="info">
+BranchPicker must be placed inside a `MessagePrimitive.Root` because it reads branch state from the nearest message context.
+</Callout>
+
+<Callout type="info">
+Runtime setup: primitives require runtime context. Wrap your UI in `AssistantRuntimeProvider` with a runtime (for example `useLocalRuntime(...)`). See [Pick a Runtime](/docs/runtimes/pick-a-runtime).
+</Callout>
+
+## Core Concepts
+
+### Branch Navigation
+
+`Previous` and `Next` buttons automatically disable at boundaries. `Previous` is disabled on the first branch, and `Next` is disabled on the last. Both also disable while the thread is running if the runtime doesn't support `switchBranchDuringRun`.
+
+### Number & Count
+
+`Number` and `Count` are text-only primitives that render raw numbers with no wrapping element. Use a `<span>` if you need to style them:
+
+```tsx
+<span className="tabular-nums">
+  <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+</span>
+```
+
+### hideWhenSingleBranch
+
+The `hideWhenSingleBranch` prop on `Root` hides the entire picker when there's only one branch. This is a common production pattern to reduce visual clutter:
+
+```tsx
+<BranchPickerPrimitive.Root hideWhenSingleBranch>
+  <BranchPickerPrimitive.Previous>←</BranchPickerPrimitive.Previous>
+  <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+  <BranchPickerPrimitive.Next>→</BranchPickerPrimitive.Next>
+</BranchPickerPrimitive.Root>
+```
+
+### Context Requirement
+
+BranchPicker reads branch state from the nearest message context. It must be placed inside a `MessagePrimitive.Root`, either directly or nested inside your message component.
+
+## Parts
+
+### Root
+
+Container with optional `hideWhenSingleBranch`. Renders a `<div>` element unless `asChild` is set.
+
+```tsx
+<BranchPickerPrimitive.Root hideWhenSingleBranch className="inline-flex items-center gap-1">
+  <BranchPickerPrimitive.Previous>←</BranchPickerPrimitive.Previous>
+  <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+  <BranchPickerPrimitive.Next>→</BranchPickerPrimitive.Next>
+</BranchPickerPrimitive.Root>
+```
+
+<PrimitivesTypeTable type="BranchPickerPrimitiveRootProps" parameters={BranchPickerPrimitiveDocs.Root.props.filter(p => p.name !== "asChild")} />
+
+### Previous
+
+Button that selects the previous branch. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<BranchPickerPrimitive.Previous>Previous</BranchPickerPrimitive.Previous>
+```
+
+### Next
+
+Button that selects the next branch. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<BranchPickerPrimitive.Next>Next</BranchPickerPrimitive.Next>
+```
+
+### Number
+
+Displays the current branch number.
+
+```tsx
+<BranchPickerPrimitive.Number />
+```
+
+### Count
+
+Displays the total number of branches for the current message.
+
+```tsx
+<BranchPickerPrimitive.Count />
+```
+
+## Patterns
+
+### Standard Picker with Icons
+
+```tsx
+import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
+
+<BranchPickerPrimitive.Root
+  hideWhenSingleBranch
+  className="inline-flex items-center gap-1 text-xs text-muted-foreground"
+>
+  <BranchPickerPrimitive.Previous className="size-6 rounded-md hover:bg-muted disabled:opacity-30">
+    <ChevronLeftIcon className="size-3.5" />
+  </BranchPickerPrimitive.Previous>
+  <span className="tabular-nums">
+    <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
+  </span>
+  <BranchPickerPrimitive.Next className="size-6 rounded-md hover:bg-muted disabled:opacity-30">
+    <ChevronRightIcon className="size-3.5" />
+  </BranchPickerPrimitive.Next>
+</BranchPickerPrimitive.Root>
+```
+
+### Custom Elements with asChild
+
+```tsx
+<BranchPickerPrimitive.Previous asChild>
+  <MyIconButton tooltip="Previous branch">
+    <ChevronLeftIcon />
+  </MyIconButton>
+</BranchPickerPrimitive.Previous>
+```
+
+The primitive's disabled state and click handler merge onto your element.
+
+### Inside a Message Footer
+
+The most common pattern places the BranchPicker alongside an ActionBar in a message footer:
+
+```tsx
+function AssistantMessage() {
+  return (
+    <MessagePrimitive.Root>
+      <div className="rounded-xl bg-muted p-3">
+        <MessagePrimitive.Parts />
+      </div>
+      <div className="flex items-center justify-between">
+        <BranchPickerPrimitive.Root hideWhenSingleBranch>
+          {/* prev / number / count / next */}
+        </BranchPickerPrimitive.Root>
+        <ActionBarPrimitive.Root>
+          <ActionBarPrimitive.Copy>Copy</ActionBarPrimitive.Copy>
+          <ActionBarPrimitive.Reload>Reload</ActionBarPrimitive.Reload>
+        </ActionBarPrimitive.Root>
+      </div>
+    </MessagePrimitive.Root>
+  );
+}
+```
+
+## Relationship to Components
+
+The shadcn [Thread](/docs/ui/thread) component includes a BranchPicker in both AssistantMessage and UserMessage footers, with `hideWhenSingleBranch` enabled. If the default layout works, use the component. Reach for `BranchPickerPrimitive` directly when you need a custom position, different styling, or a non-standard branch navigation experience.
+
+## API Reference
+
+For full prop details on every part, see the [BranchPickerPrimitive API Reference](/docs/api-reference/primitives/branch-picker).
+
+Related:
+- [ActionBarPrimitive API Reference](/docs/api-reference/primitives/action-bar)
+- [MessagePrimitive API Reference](/docs/api-reference/primitives/message)