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

package/.docs/raw/docs/primitives/action-bar.mdx

@@ -0,0 +1,351 @@
+---
+title: ActionBar
+description: Build message action buttons with auto-hide, copy state, and intelligent disabling.
+---
+
+import { ActionBarPrimitiveSample } from "@/components/docs/samples/action-bar-primitive";
+import { ActionBarPrimitive as ActionBarPrimitiveDocs } from "@/generated/primitiveDocs";
+
+The ActionBar primitive provides message actions: copy, reload, edit, feedback, speech, and export. It handles intelligent visibility with auto-hide on hover, automatic disabling based on message state, and floating behavior. You compose the buttons; the primitive handles action state and availability.
+
+<Tabs items={["Preview", "Code"]}>
+  <Tab>
+    <ActionBarPrimitiveSample />
+  </Tab>
+  <Tab>
+```tsx
+import {
+  ActionBarPrimitive,
+  MessagePrimitive,
+} from "@assistant-ui/react";
+import { CheckIcon, CopyIcon, RefreshCwIcon } from "lucide-react";
+
+function AssistantMessage() {
+  return (
+    <MessagePrimitive.Root className="group flex flex-col items-start gap-1">
+      <div className="max-w-[80%] rounded-2xl bg-muted px-4 py-2.5 text-sm">
+        <MessagePrimitive.Parts />
+      </div>
+      <ActionBarPrimitive.Root
+        hideWhenRunning
+        autohide="not-last"
+        autohideFloat="always"
+        className="flex gap-0.5 data-[floating]:opacity-0 data-[floating]:group-hover:opacity-100 data-[floating]:transition-opacity"
+      >
+        <ActionBarPrimitive.Copy className="group/copy flex size-8 items-center justify-center rounded-lg text-muted-foreground hover:bg-muted hover:text-foreground">
+          <CopyIcon className="size-4 group-data-[copied]/copy:hidden" />
+          <CheckIcon className="hidden size-4 group-data-[copied]/copy:block" />
+        </ActionBarPrimitive.Copy>
+        <ActionBarPrimitive.Reload className="flex size-8 items-center justify-center rounded-lg text-muted-foreground hover:bg-muted hover:text-foreground">
+          <RefreshCwIcon className="size-4" />
+        </ActionBarPrimitive.Reload>
+      </ActionBarPrimitive.Root>
+    </MessagePrimitive.Root>
+  );
+}
+```
+  </Tab>
+</Tabs>
+
+## Quick Start
+
+A minimal action bar with copy and reload:
+
+```tsx
+import { ActionBarPrimitive } from "@assistant-ui/react";
+
+<ActionBarPrimitive.Root>
+  <ActionBarPrimitive.Copy>Copy</ActionBarPrimitive.Copy>
+  <ActionBarPrimitive.Reload>Reload</ActionBarPrimitive.Reload>
+</ActionBarPrimitive.Root>
+```
+
+`Root` renders a `<div>`, action buttons render `<button>` elements. Each button auto-disables when its action isn't available (e.g., Copy is disabled when there's no content, Reload is disabled while the model is running).
+
+<Callout type="info">
+ActionBar must be placed inside a `MessagePrimitive.Root` because it reads message 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
+
+### Auto-Hide & Floating
+
+The `autohide` prop controls when the action bar is visible:
+
+- **`"never"`** (default): always visible
+- **`"not-last"`**: hidden on all messages except the last, shown on hover
+- **`"always"`**: hidden on all messages, shown on hover
+
+When `autohideFloat` is set, hidden action bars get the `data-floating` attribute instead of being removed from the DOM. This lets you animate them with CSS:
+
+```tsx
+<ActionBarPrimitive.Root
+  autohide="not-last"
+  autohideFloat="always"
+  className="data-[floating]:opacity-0 data-[floating]:group-hover:opacity-100 data-[floating]:transition-opacity"
+>
+  {/* buttons */}
+</ActionBarPrimitive.Root>
+```
+
+The `"single-branch"` option for `autohideFloat` only floats when the message has a single branch (no alternatives).
+
+### Automatic Disabling
+
+Action buttons automatically disable based on state, with no manual wiring needed:
+
+- **Copy**: disabled when there's no copyable text content or an assistant message is still running
+- **Reload**: disabled when the thread is running or the message role isn't assistant
+- **Edit**: disabled when the message is already being edited
+- **Speak**: disabled when there's no speakable text or an assistant message is still running
+
+### Copy State
+
+After clicking Copy, the button gets a `data-copied` attribute for a configurable duration (default 3 seconds). Use this for visual feedback:
+
+```tsx
+<ActionBarPrimitive.Copy copiedDuration={2000} className="group">
+  <CopyIcon className="group-data-[copied]:hidden" />
+  <CheckIcon className="hidden group-data-[copied]:block" />
+</ActionBarPrimitive.Copy>
+```
+
+### Feedback Buttons
+
+Feedback buttons track submission state with `data-submitted`:
+
+```tsx
+<ActionBarPrimitive.FeedbackPositive className="data-[submitted]:text-green-500">
+  👍
+</ActionBarPrimitive.FeedbackPositive>
+<ActionBarPrimitive.FeedbackNegative className="data-[submitted]:text-red-500">
+  👎
+</ActionBarPrimitive.FeedbackNegative>
+```
+
+## Parts
+
+### Root
+
+Container with auto-hide and floating behavior. Renders a `<div>` element unless `asChild` is set.
+
+```tsx
+<ActionBarPrimitive.Root
+  hideWhenRunning
+  autohide="not-last"
+  autohideFloat="always"
+  className="flex gap-1"
+>
+  <ActionBarPrimitive.Copy>Copy</ActionBarPrimitive.Copy>
+  <ActionBarPrimitive.Reload>Reload</ActionBarPrimitive.Reload>
+</ActionBarPrimitive.Root>
+```
+
+<PrimitivesTypeTable type="ActionBarPrimitiveRootProps" parameters={ActionBarPrimitiveDocs.Root.props.filter(p => p.name !== "asChild")} />
+
+### Copy
+
+Copies message text to clipboard. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<ActionBarPrimitive.Copy copiedDuration={2000} className="group">
+  <CopyIcon className="group-data-[copied]:hidden" />
+  <CheckIcon className="hidden group-data-[copied]:block" />
+</ActionBarPrimitive.Copy>
+```
+
+<PrimitivesTypeTable type="ActionBarPrimitiveCopyProps" parameters={ActionBarPrimitiveDocs.Copy.props.filter(p => p.name !== "asChild")} />
+
+### Reload
+
+Reloads or regenerates the current assistant message. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<ActionBarPrimitive.Reload className="rounded-md px-2 py-1 text-sm hover:bg-muted">
+  Regenerate
+</ActionBarPrimitive.Reload>
+```
+
+### Edit
+
+Enters edit mode for the current message. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<ActionBarPrimitive.Edit className="rounded-md px-2 py-1 text-sm hover:bg-muted">
+  Edit
+</ActionBarPrimitive.Edit>
+```
+
+### Speak
+
+Starts speech playback for the current message. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<ActionBarPrimitive.Speak className="rounded-md px-2 py-1 text-sm hover:bg-muted">
+  Play
+</ActionBarPrimitive.Speak>
+```
+
+### StopSpeaking
+
+Stops speech playback for the current message. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<ActionBarPrimitive.StopSpeaking className="rounded-md px-2 py-1 text-sm hover:bg-muted">
+  Stop
+</ActionBarPrimitive.StopSpeaking>
+```
+
+### FeedbackPositive
+
+Submits positive feedback for the current message. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<ActionBarPrimitive.FeedbackPositive className="rounded-md px-2 py-1 text-sm hover:bg-muted">
+  Helpful
+</ActionBarPrimitive.FeedbackPositive>
+```
+
+### FeedbackNegative
+
+Submits negative feedback for the current message. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<ActionBarPrimitive.FeedbackNegative className="rounded-md px-2 py-1 text-sm hover:bg-muted">
+  Not helpful
+</ActionBarPrimitive.FeedbackNegative>
+```
+
+### ExportMarkdown
+
+Downloads message as Markdown or calls custom handler. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<ActionBarPrimitive.ExportMarkdown
+  onExport={async (content) => {
+    await navigator.clipboard.writeText(content);
+  }}
+>
+  Export
+</ActionBarPrimitive.ExportMarkdown>
+```
+
+<PrimitivesTypeTable type="ActionBarPrimitiveExportMarkdownProps" parameters={ActionBarPrimitiveDocs.ExportMarkdown.props.filter(p => p.name !== "asChild")} />
+
+## Patterns
+
+### Assistant Action Bar
+
+```tsx
+<ActionBarPrimitive.Root
+  hideWhenRunning
+  autohide="not-last"
+  autohideFloat="single-branch"
+>
+  <ActionBarPrimitive.Copy>Copy</ActionBarPrimitive.Copy>
+  <ActionBarPrimitive.Reload>Regenerate</ActionBarPrimitive.Reload>
+  <ActionBarPrimitive.ExportMarkdown>Export</ActionBarPrimitive.ExportMarkdown>
+</ActionBarPrimitive.Root>
+```
+
+### User Action Bar
+
+```tsx
+<ActionBarPrimitive.Root hideWhenRunning autohide="not-last">
+  <ActionBarPrimitive.Edit>Edit</ActionBarPrimitive.Edit>
+</ActionBarPrimitive.Root>
+```
+
+### Speech Toggle
+
+```tsx
+<AuiIf condition={(s) => !s.message.isSpeaking}>
+  <ActionBarPrimitive.Speak>Play</ActionBarPrimitive.Speak>
+</AuiIf>
+<AuiIf condition={(s) => s.message.isSpeaking}>
+  <ActionBarPrimitive.StopSpeaking>Stop</ActionBarPrimitive.StopSpeaking>
+</AuiIf>
+```
+
+<Callout type="info">
+Speech requires a `SpeechSynthesisAdapter` configured in your runtime. See [Speech & Dictation](/docs/guides/speech) for setup.
+</Callout>
+
+### Export with Custom Handler
+
+```tsx
+<ActionBarPrimitive.ExportMarkdown
+  onExport={async (content) => {
+    await navigator.clipboard.writeText(content);
+    toast("Copied as Markdown!");
+  }}
+>
+  Copy Markdown
+</ActionBarPrimitive.ExportMarkdown>
+```
+
+## Overflow Menu (ActionBarMorePrimitive)
+
+`ActionBarMorePrimitive` is a Radix DropdownMenu for overflow actions, using the same pattern as `ThreadListItemMorePrimitive`. Use it to group secondary actions behind a "more" button.
+
+`ActionBarMorePrimitive.Item` maps to Radix `DropdownMenu.Item`, so it preserves menu keyboard/focus semantics. Prefer `asChild` when composing an `ActionBarPrimitive` button into a menu item.
+
+`ActionBarMorePrimitive.Content` defaults to `sideOffset={4}` so the menu has a small gap from the trigger.
+
+| Part | Element | Purpose |
+|------|---------|---------|
+| `Root` | N/A | Radix DropdownMenu provider |
+| `Trigger` | `<button>` | Opens the dropdown |
+| `Content` | `<div>` (portal) | The dropdown panel |
+| `Item` | `<div>` | A menu item |
+| `Separator` | `<div>` | Visual separator between items |
+
+```tsx
+import {
+  ActionBarPrimitive,
+  ActionBarMorePrimitive,
+} from "@assistant-ui/react";
+import { MoreHorizontalIcon } from "lucide-react";
+
+<ActionBarPrimitive.Root>
+  <ActionBarPrimitive.Copy>Copy</ActionBarPrimitive.Copy>
+  <ActionBarPrimitive.Reload>Regenerate</ActionBarPrimitive.Reload>
+  <ActionBarMorePrimitive.Root>
+    <ActionBarMorePrimitive.Trigger className="flex size-8 items-center justify-center rounded-lg hover:bg-muted">
+      <MoreHorizontalIcon className="size-4" />
+    </ActionBarMorePrimitive.Trigger>
+    <ActionBarMorePrimitive.Content side="bottom" align="end">
+      <ActionBarMorePrimitive.Item asChild>
+        <ActionBarPrimitive.ExportMarkdown>
+          Export Markdown
+        </ActionBarPrimitive.ExportMarkdown>
+      </ActionBarMorePrimitive.Item>
+      <ActionBarMorePrimitive.Separator />
+      <ActionBarMorePrimitive.Item asChild>
+        <ActionBarPrimitive.FeedbackPositive>
+          Helpful
+        </ActionBarPrimitive.FeedbackPositive>
+      </ActionBarMorePrimitive.Item>
+    </ActionBarMorePrimitive.Content>
+  </ActionBarMorePrimitive.Root>
+</ActionBarPrimitive.Root>
+```
+
+See the [ActionBarMorePrimitive API Reference](/docs/api-reference/primitives/action-bar-more) for full prop details.
+
+## Relationship to Components
+
+The shadcn [Thread](/docs/ui/thread) component uses `ActionBarPrimitive` inside its `AssistantMessage` (with Copy, Reload, and an export dropdown) and `UserMessage` (with Edit). If those defaults work, use the component. Reach for `ActionBarPrimitive` directly when you need different actions, custom layout, or actions outside the standard thread UI.
+
+ActionBar is commonly paired with [BranchPicker](/docs/primitives/branch-picker) for navigating between alternative responses on assistant messages.
+
+## API Reference
+
+For full prop details on every part, see the [ActionBarPrimitive API Reference](/docs/api-reference/primitives/action-bar).
+
+Related:
+- [ActionBarMorePrimitive API Reference](/docs/api-reference/primitives/action-bar-more)

package/.docs/raw/docs/primitives/assistant-modal.mdx

@@ -0,0 +1,215 @@
+---
+title: AssistantModal
+description: A floating chat popover with a fixed-position trigger button that opens a chat panel.
+---
+
+import { AssistantModalSample } from "@/components/docs/samples/assistant-modal";
+import { AssistantModalPrimitive as AssistantModalPrimitiveDocs } from "@/generated/primitiveDocs";
+
+The AssistantModal primitive is a floating chat popover built on [Radix Popover](https://www.radix-ui.com/primitives/docs/components/popover). A trigger button opens a chat panel, which is a common floating assistant launcher pattern. You control the trigger, content, positioning, and animations.
+
+<Tabs items={["Preview", "Code"]}>
+  <Tab>
+    <AssistantModalSample />
+  </Tab>
+  <Tab>
+```tsx
+import { AssistantModalPrimitive } from "@assistant-ui/react";
+
+function MinimalAssistantModal() {
+  return (
+    <AssistantModalPrimitive.Root>
+      <AssistantModalPrimitive.Anchor>
+        <AssistantModalPrimitive.Trigger>
+          Open Chat
+        </AssistantModalPrimitive.Trigger>
+      </AssistantModalPrimitive.Anchor>
+      <AssistantModalPrimitive.Content>
+        {/* Your Thread goes here */}
+      </AssistantModalPrimitive.Content>
+    </AssistantModalPrimitive.Root>
+  );
+}
+```
+  </Tab>
+</Tabs>
+
+## Quick Start
+
+Minimal example:
+
+```tsx
+import { AssistantModalPrimitive } from "@assistant-ui/react";
+
+<AssistantModalPrimitive.Root>
+  <AssistantModalPrimitive.Anchor>
+    <AssistantModalPrimitive.Trigger>Open</AssistantModalPrimitive.Trigger>
+  </AssistantModalPrimitive.Anchor>
+  <AssistantModalPrimitive.Content>
+    <Thread />
+  </AssistantModalPrimitive.Content>
+</AssistantModalPrimitive.Root>
+```
+
+`Root` is a Radix Popover provider (no DOM), `Trigger` renders a `<button>`, `Anchor` renders a `<div>`, and `Content` renders a `<div>` inside a portal. Add your own classes, animations, and layout.
+
+<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
+
+### Popover Architecture
+
+AssistantModal is built directly on Radix Popover. `Root` manages open/close state, `Trigger` toggles it, `Anchor` positions the popover, and `Content` is the floating panel. All Radix Popover props are available on the corresponding parts.
+
+### Anchor vs Trigger
+
+`Content` positions itself relative to `Anchor`, not `Trigger`. The common pattern is wrapping `Trigger` inside `Anchor` so the popover aligns to a larger area (like a fixed-position button container) rather than the button itself:
+
+```tsx
+<AssistantModalPrimitive.Anchor className="fixed right-4 bottom-4 size-11">
+  <AssistantModalPrimitive.Trigger>
+    Open
+  </AssistantModalPrimitive.Trigger>
+</AssistantModalPrimitive.Anchor>
+```
+
+### Auto-Open on Run Start
+
+The `unstable_openOnRunStart` prop (default `true`) automatically opens the modal when the assistant starts responding. This means if a user triggers a run programmatically while the modal is closed, it pops open to show the response. Set to `false` to disable.
+
+### Dismiss Behavior
+
+`Content` uses `dissmissOnInteractOutside` *(intentional current API spelling, with the extra `s`)* and defaults it to `false`. Clicking outside the modal does **not** close it. This matches expected chat UX where users interact with the page while keeping the chat open. Set it to `true` for standard popover dismiss behavior.
+
+### Open/Close Animations
+
+`Content` exposes `data-[state=open]` and `data-[state=closed]` attributes for CSS animations:
+
+```tsx
+<AssistantModalPrimitive.Content
+  className="data-[state=open]:animate-in data-[state=open]:fade-in data-[state=closed]:animate-out data-[state=closed]:fade-out"
+>
+```
+
+## Parts
+
+### Root
+
+Radix Popover provider, manages open/close state. No DOM element rendered.
+
+```tsx
+<AssistantModalPrimitive.Root unstable_openOnRunStart={false}>
+  ...
+</AssistantModalPrimitive.Root>
+```
+
+<PrimitivesTypeTable type="AssistantModalPrimitiveRootProps" parameters={AssistantModalPrimitiveDocs.Root.props} />
+
+### Trigger
+
+Button that toggles the modal open and closed. Renders a `<button>` element unless `asChild` is set.
+
+```tsx
+<AssistantModalPrimitive.Trigger className="rounded-full bg-primary px-4 py-2 text-primary-foreground">
+  Open Chat
+</AssistantModalPrimitive.Trigger>
+```
+
+### Anchor
+
+Positions the trigger and content relative to a shared anchor. Renders a `<div>` element unless `asChild` is set.
+
+```tsx
+<AssistantModalPrimitive.Anchor className="fixed right-4 bottom-4">
+  <AssistantModalPrimitive.Trigger>Chat</AssistantModalPrimitive.Trigger>
+</AssistantModalPrimitive.Anchor>
+```
+
+### Content
+
+The floating chat panel. Renders a `<div>` element inside a portal.
+
+```tsx
+<AssistantModalPrimitive.Content
+  sideOffset={16}
+  className="h-[600px] w-[400px] rounded-xl border bg-background shadow-lg"
+>
+  <Thread />
+</AssistantModalPrimitive.Content>
+```
+
+<PrimitivesTypeTable type="AssistantModalPrimitiveContentProps" parameters={AssistantModalPrimitiveDocs.Content.props} />
+
+## Patterns
+
+### Floating Bottom-Right Widget
+
+```tsx
+<AssistantModalPrimitive.Root>
+  <AssistantModalPrimitive.Anchor className="fixed right-4 bottom-4 size-11">
+    <AssistantModalPrimitive.Trigger className="size-full rounded-full bg-primary text-primary-foreground shadow-lg">
+      <BotIcon className="size-6" />
+    </AssistantModalPrimitive.Trigger>
+  </AssistantModalPrimitive.Anchor>
+  <AssistantModalPrimitive.Content
+    sideOffset={16}
+    className="h-[600px] w-[400px] rounded-xl border bg-background shadow-lg"
+  >
+    <Thread />
+  </AssistantModalPrimitive.Content>
+</AssistantModalPrimitive.Root>
+```
+
+### Trigger Icon Swap
+
+The `Trigger` button receives a `data-state` attribute from Radix (`"open"` or `"closed"`). To pass that state down to child icons, use `asChild` with a wrapper component that destructures and forwards it:
+
+```tsx
+import { forwardRef } from "react";
+
+const ModalButton = forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<"button"> & { "data-state"?: string }
+>(({ "data-state": state, ...props }, ref) => (
+  <button ref={ref} {...props} className="relative size-11 rounded-full">
+    <BotIcon
+      data-state={state}
+      className="absolute size-6 transition-all data-[state=open]:rotate-90 data-[state=open]:scale-0"
+    />
+    <XIcon
+      data-state={state}
+      className="absolute size-6 transition-all data-[state=closed]:-rotate-90 data-[state=closed]:scale-0"
+    />
+  </button>
+));
+
+<AssistantModalPrimitive.Trigger asChild>
+  <ModalButton />
+</AssistantModalPrimitive.Trigger>
+```
+
+### Custom Portal Container
+
+Render the content inside a specific container instead of `document.body`:
+
+```tsx
+<AssistantModalPrimitive.Content
+  portalProps={{ container: myContainerRef.current }}
+>
+  <Thread />
+</AssistantModalPrimitive.Content>
+```
+
+## Relationship to Components
+
+The shadcn [AssistantModal](/docs/ui/assistant-modal) component wraps these primitives with slide/fade animations, icon transitions between open and closed states, and responsive sizing. Start there for a prebuilt floating chat widget.
+
+## API Reference
+
+For full prop details on every part, see the [AssistantModalPrimitive API Reference](/docs/api-reference/primitives/assistant-modal).
+
+Related:
+- [ThreadPrimitive](/docs/primitives/thread)
+- [ComposerPrimitive](/docs/primitives/composer)