@assistant-ui/mcp-docs-server 0.2.3 → 0.3.0

package/.docs/raw/docs/primitives/selection-toolbar.mdx

@@ -1,191 +0,0 @@
----
-title: SelectionToolbar
-description: A floating toolbar that appears when text is selected within a message.
-platforms: ["react"]
----
-
-import { SelectionToolbarPrimitiveSample } from "@/components/pages/docs/samples/selection-toolbar-primitive";
-
-The SelectionToolbar primitive is a floating toolbar that appears when the user selects text within a message. It lets users quote selected text into the composer. Styling and action layout are fully customizable.
-
-<Tabs items={["Preview", "Code"]}>
-  <Tab>
-    <SelectionToolbarPrimitiveSample />
-  </Tab>
-  <Tab>
-```tsx
-import { SelectionToolbarPrimitive } from "@assistant-ui/react";
-import { QuoteIcon } from "lucide-react";
-
-function FloatingSelectionToolbar() {
-  return (
-    <SelectionToolbarPrimitive.Root className="flex items-center gap-1 rounded-lg border bg-popover px-1 py-1 shadow-md">
-      <SelectionToolbarPrimitive.Quote className="flex items-center gap-1.5 rounded-md px-2.5 py-1 text-popover-foreground text-sm hover:bg-accent">
-        <QuoteIcon className="size-3.5" />
-        Quote
-      </SelectionToolbarPrimitive.Quote>
-    </SelectionToolbarPrimitive.Root>
-  );
-}
-```
-  </Tab>
-</Tabs>
-
-## Quick Start
-
-A minimal selection toolbar:
-
-```tsx
-import { SelectionToolbarPrimitive } from "@assistant-ui/react";
-
-<SelectionToolbarPrimitive.Root>
-  <SelectionToolbarPrimitive.Quote>
-    Quote
-  </SelectionToolbarPrimitive.Quote>
-</SelectionToolbarPrimitive.Root>
-```
-
-`Root` renders a `<div>` inside a portal, positioned above the text selection. `Quote` renders a `<button>` that copies the selected text into the composer as a quote.
-
-<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
-
-### Automatic Positioning
-
-`Root` renders via a portal to `document.body`. In the current implementation, it positions itself with `position: fixed`, `top: rect.top - 8px`, `left: rect.left + rect.width / 2`, `transform: translate(-50%, -100%)` (placing it centered above the selection), and `z-index: 50`.
-
-### Single-Message Validation
-
-The toolbar only appears when the selection is entirely within a single message. Cross-message selections are ignored. Detection works by checking for `data-message-id` attributes on ancestor elements, which `MessagePrimitive.Root` sets automatically.
-
-`Root` returns `null` when there is no valid selection (collapsed selection, empty text, or no single-message match).
-
-### Quote Regions
-
-By default, any selected text inside a message can be quoted. For rich messages with tool cards, attachments, or custom controls, add `data-aui-quote-selectable` to the element that contains the message text. Once a message has a quote-selectable region, selections must stay inside the same marked region for the toolbar to appear.
-
-```tsx
-<MessagePrimitive.Root>
-  <div data-aui-quote-selectable="">
-    <MessagePrimitive.Parts />
-  </div>
-  <ToolCard />
-</MessagePrimitive.Root>
-```
-
-Set `data-aui-quote-selectable="false"` to exclude an element instead: on the message root it disables quoting for the entire message, and inside a quotable region it carves that subtree out. The nearest marker wins, and any value other than `"false"` (including empty) marks a quotable region.
-
-Apps know the message role at render time, so a role gate is a conditional attribute:
-
-```tsx
-const UserMessage = () => (
-  <MessagePrimitive.Root data-aui-quote-selectable="false">
-    <MessagePrimitive.Parts />
-  </MessagePrimitive.Root>
-);
-```
-
-### Quote Action
-
-The `Quote` button does two things on click:
-
-1. Calls `composer.setQuote({ text, messageId })` to populate the composer with the selected text as a quoted snippet
-2. Clears the browser selection via `window.getSelection()?.removeAllRanges()`
-
-The composer then shows the quoted text, and the user can type a follow-up message around it.
-
-### Dismissal
-
-The toolbar hides automatically when:
-
-- The user scrolls
-- The selection collapses (click away or arrow keys)
-- The selection is cleared programmatically (e.g., after quoting)
-
-Clicking the toolbar itself does not dismiss the selection. `Root` calls `preventDefault` on `mousedown` to preserve it.
-
-### Placement in Thread
-
-The SelectionToolbar must be placed inside `ThreadPrimitive.Root` but **outside** `ThreadPrimitive.Viewport`. It positions itself via a portal based on the browser selection, independent of the scroll container:
-
-```tsx
-<ThreadPrimitive.Root>
-  <ThreadPrimitive.Viewport>
-    <ThreadPrimitive.Messages ... />
-  </ThreadPrimitive.Viewport>
-  <SelectionToolbarPrimitive.Root>
-    <SelectionToolbarPrimitive.Quote>Quote</SelectionToolbarPrimitive.Quote>
-  </SelectionToolbarPrimitive.Root>
-  <ComposerPrimitive.Root>...</ComposerPrimitive.Root>
-</ThreadPrimitive.Root>
-```
-
-## Parts
-
-### Root
-
-Floating toolbar container that appears for a valid text selection. Renders a `<div>` element unless `asChild` is set.
-
-```tsx
-<SelectionToolbarPrimitive.Root className="flex items-center gap-1 rounded-lg border bg-popover px-1 py-1 shadow-md">
-  <SelectionToolbarPrimitive.Quote>Quote</SelectionToolbarPrimitive.Quote>
-</SelectionToolbarPrimitive.Root>
-```
-
-### Quote
-
-Quotes the currently selected text into the composer. Renders a `<button>` element unless `asChild` is set.
-
-```tsx
-<SelectionToolbarPrimitive.Quote className="rounded-md px-2.5 py-1 text-sm hover:bg-accent">
-  Quote
-</SelectionToolbarPrimitive.Quote>
-```
-
-## Patterns
-
-### Basic Toolbar with Quote
-
-```tsx
-<SelectionToolbarPrimitive.Root className="flex items-center gap-1 rounded-lg border bg-popover px-1 py-1 shadow-md">
-  <SelectionToolbarPrimitive.Quote className="flex items-center gap-1.5 rounded-md px-2.5 py-1 text-sm text-popover-foreground hover:bg-accent">
-    <QuoteIcon className="size-3.5" />
-    Quote
-  </SelectionToolbarPrimitive.Quote>
-</SelectionToolbarPrimitive.Root>
-```
-
-### Toolbar with Multiple Actions
-
-You can add custom buttons alongside `Quote` for additional actions:
-
-```tsx
-<SelectionToolbarPrimitive.Root className="flex items-center gap-1 rounded-lg border bg-popover px-1 py-1 shadow-md">
-  <SelectionToolbarPrimitive.Quote className="flex items-center gap-1.5 rounded-md px-2.5 py-1 text-sm hover:bg-accent">
-    <QuoteIcon className="size-3.5" />
-    Quote
-  </SelectionToolbarPrimitive.Quote>
-  <button
-    className="flex items-center gap-1.5 rounded-md px-2.5 py-1 text-sm hover:bg-accent"
-    onClick={() => navigator.clipboard.writeText(window.getSelection()?.toString() ?? "")}
-  >
-    <CopyIcon className="size-3.5" />
-    Copy
-  </button>
-</SelectionToolbarPrimitive.Root>
-```
-
-## Relationship to Components
-
-There is no pre-built shadcn component for SelectionToolbar. See the [Quoting guide](/docs/guides/quoting) for the full workflow including composer quote display and dismiss.
-
-## API Reference
-
-For full prop details on every part, see the [SelectionToolbarPrimitive API Reference](/docs/api-reference/primitives/selection-toolbar).
-
-Related:
-- [Quoting Guide](/docs/guides/quoting)
-- [ComposerPrimitive API Reference](/docs/api-reference/primitives/composer)

package/.docs/raw/docs/primitives/suggestion.mdx

@@ -1,254 +0,0 @@
----
-title: Suggestion
-description: Suggested prompts that users can click to quickly send or populate the composer.
-platforms: ["react"]
----
-
-import { SuggestionPrimitiveSample } from "@/components/pages/docs/samples/suggestion-primitive";
-import { SuggestionPrimitive as SuggestionPrimitiveDocs } from "@/generated/primitiveDocs";
-
-The Suggestion primitive renders suggested prompts as clickable pills that send a message or populate the composer. Use it for welcome screen suggestions, follow-up prompts, or quick actions. You provide the layout and styling.
-
-<Tabs items={["Preview", "Code"]}>
-  <Tab>
-    <SuggestionPrimitiveSample />
-  </Tab>
-  <Tab>
-```tsx
-import {
-  ThreadPrimitive,
-  SuggestionPrimitive,
-} from "@assistant-ui/react";
-
-function SuggestionList() {
-  return (
-    <div className="grid grid-cols-2 gap-2">
-      <ThreadPrimitive.Suggestions>
-        {() => <SuggestionItem />}
-      </ThreadPrimitive.Suggestions>
-    </div>
-  );
-}
-
-function SuggestionItem() {
-  return (
-    <SuggestionPrimitive.Trigger
-      send
-      className="flex flex-col items-start gap-1 rounded-2xl border px-4 py-3 text-left text-sm hover:bg-muted"
-    >
-      <span className="font-medium">
-        <SuggestionPrimitive.Title />
-      </span>
-      <span className="text-muted-foreground">
-        <SuggestionPrimitive.Description />
-      </span>
-    </SuggestionPrimitive.Trigger>
-  );
-}
-```
-  </Tab>
-</Tabs>
-
-## Quick Start
-
-A suggestion list using the iterator pattern:
-
-```tsx
-import { ThreadPrimitive, SuggestionPrimitive } from "@assistant-ui/react";
-
-<ThreadPrimitive.Suggestions>
-  {() => <MySuggestionItem />}
-</ThreadPrimitive.Suggestions>
-
-function MySuggestionItem() {
-  return (
-    <SuggestionPrimitive.Trigger className="rounded-lg border px-3 py-2 hover:bg-muted">
-      <SuggestionPrimitive.Title />
-    </SuggestionPrimitive.Trigger>
-  );
-}
-```
-
-`ThreadPrimitive.Suggestions` iterates over available suggestions and renders your component for each one. Inside the component, `SuggestionPrimitive` parts read from the suggestion context automatically.
-
-<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
-
-### Context-Based Rendering
-
-SuggestionPrimitive parts read from a suggestion context. Use `ThreadPrimitive.Suggestions` to provide this context. It iterates over the thread's suggestions and renders your component for each one:
-
-```tsx
-<ThreadPrimitive.Suggestions>
-  {() => <MySuggestion />}
-</ThreadPrimitive.Suggestions>
-```
-
-You can also use `ThreadPrimitive.SuggestionByIndex` to render a specific suggestion by index if you need more layout control.
-
-### Title and Description
-
-Suggestions support two text parts for structured display:
-
-- **`Title`**: the primary text (e.g., "Write a blog post")
-- **`Description`**: secondary text — renders the `label` field from the suggestion config (e.g., `{ prompt: "...", label: "About React Server Components" }`)
-
-Both render a `<span>` and accept `children` to override the value from state:
-
-```tsx
-<SuggestionPrimitive.Title>Custom title</SuggestionPrimitive.Title>
-```
-
-### Send vs Populate
-
-`Trigger`'s `send` prop controls what happens on click:
-
-- **`send={true}`**: immediately sends the suggestion as a new message. While a run is in progress, the suggestion is queued on runtimes that support queueing (leaving the composer draft untouched); otherwise the trigger is disabled.
-- **`send={false}`** (default): populates the composer text so the user can edit before sending
-
-```tsx
-// Send immediately
-<SuggestionPrimitive.Trigger send>
-  <SuggestionPrimitive.Title />
-</SuggestionPrimitive.Trigger>
-
-// Populate composer for editing
-<SuggestionPrimitive.Trigger>
-  <SuggestionPrimitive.Title />
-</SuggestionPrimitive.Trigger>
-```
-
-### clearComposer
-
-When `send={false}`, the `clearComposer` prop controls whether the suggestion replaces or appends to existing composer text:
-
-- **`clearComposer={true}`** (default): replaces the current composer text
-- **`clearComposer={false}`**: appends the suggestion to the existing text
-
-### Static configuration vs. runtime suggestions
-
-There are two data flows for suggestions:
-
-- **Static configuration** flows through the `suggestions` scope. Pass an array to `Suggestions(...)` in your runtime provider; render it with `ThreadPrimitive.Suggestions`. Best for welcome screen prompts.
-- **Runtime / dynamic suggestions** flow through `thread.suggestions`. Populate it via `SuggestionAdapter` (local runtime) or the `suggestions` field on `useExternalStoreRuntime`; render it with the shadcn `ThreadFollowupSuggestions` component or your own component reading `useAuiState((s) => s.thread.suggestions)`. Best for follow up prompts after a turn.
-
-When no static configuration is provided, the `suggestions` scope derives from `thread.suggestions`, so runtime suggestions also render through `ThreadPrimitive.Suggestions`. A static `Suggestions(...)` configuration takes precedence over the derived values.
-
-See [Suggested Prompts](/docs/guides/suggestions) for end to end examples.
-
-### ThreadPrimitive.Suggestion (Legacy)
-
-`ThreadPrimitive.Suggestion` is a self-contained button that takes a `prompt` prop directly. The newer pattern (`ThreadPrimitive.Suggestions` + `SuggestionPrimitive` parts) is preferred for structured suggestions with title and description:
-
-```tsx
-// Legacy: still works, but limited
-<ThreadPrimitive.Suggestion prompt="Write a blog post" />
-
-// Preferred: structured with title/description
-<ThreadPrimitive.Suggestions>
-  {() => <MySuggestionItem />}
-</ThreadPrimitive.Suggestions>
-```
-
-`ThreadPrimitive.Suggestion` also supports deprecated `autoSend` and `method` props for backwards compatibility. Prefer `send` and `clearComposer`.
-
-## Parts
-
-### Title
-
-Renders the suggestion title. Renders a `<span>` element unless `asChild` is set.
-
-```tsx
-<SuggestionPrimitive.Title />
-```
-
-### Description
-
-Renders the secondary suggestion description text. Renders a `<span>` element unless `asChild` is set.
-
-```tsx
-<SuggestionPrimitive.Description />
-```
-
-### Trigger
-
-Clickable button that sends or populates the suggestion. Renders a `<button>` element unless `asChild` is set.
-
-```tsx
-<SuggestionPrimitive.Trigger send className="rounded-lg border px-3 py-2 hover:bg-muted">
-  <SuggestionPrimitive.Title />
-</SuggestionPrimitive.Trigger>
-```
-
-<PrimitivesTypeTable type="SuggestionPrimitiveTriggerProps" parameters={SuggestionPrimitiveDocs.Trigger.props.filter(p => p.name !== "asChild")} />
-
-## Patterns
-
-### Welcome Screen Grid
-
-```tsx
-function WelcomeSuggestions() {
-  return (
-    <AuiIf condition={(s) => s.thread.isEmpty}>
-      <div className="text-center">
-        <h2 className="text-lg font-semibold">How can I help you?</h2>
-        <div className="mt-4 grid grid-cols-2 gap-2">
-          <ThreadPrimitive.Suggestions>
-            {() => <SuggestionCard />}
-          </ThreadPrimitive.Suggestions>
-        </div>
-      </div>
-    </AuiIf>
-  );
-}
-
-function SuggestionCard() {
-  return (
-    <SuggestionPrimitive.Trigger
-      send
-      className="flex flex-col gap-1 rounded-2xl border px-4 py-3 text-left hover:bg-muted"
-    >
-      <span className="font-medium">
-        <SuggestionPrimitive.Title />
-      </span>
-      <span className="text-sm text-muted-foreground">
-        <SuggestionPrimitive.Description />
-      </span>
-    </SuggestionPrimitive.Trigger>
-  );
-}
-```
-
-### Send-On-Click Suggestions
-
-```tsx
-<SuggestionPrimitive.Trigger send className="rounded-full border px-4 py-2 hover:bg-muted">
-  <SuggestionPrimitive.Title />
-</SuggestionPrimitive.Trigger>
-```
-
-### Populate-Only Suggestions
-
-```tsx
-<SuggestionPrimitive.Trigger
-  send={false}
-  clearComposer={false}
-  className="rounded-lg border px-3 py-1.5 text-sm hover:bg-muted"
->
-  <SuggestionPrimitive.Title />
-</SuggestionPrimitive.Trigger>
-```
-
-## Relationship to Components
-
-The shadcn [Thread](/docs/ui/thread) component includes suggestions in its welcome screen using `ThreadPrimitive.Suggestions` with `SuggestionPrimitive` parts in a responsive grid. Start there for a prebuilt welcome experience.
-
-## API Reference
-
-For full prop details on every part, see the [SuggestionPrimitive API Reference](/docs/api-reference/primitives/suggestion).
-
-Related:
-- [ThreadPrimitive API Reference](/docs/api-reference/primitives/thread)