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

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

@@ -0,0 +1,165 @@
+---
+title: SelectionToolbar
+description: A floating toolbar that appears when text is selected within a message.
+---
+
+import { SelectionToolbarPrimitiveSample } from "@/components/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 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

@@ -0,0 +1,242 @@
+---
+title: Suggestion
+description: Suggested prompts that users can click to quickly send or populate the composer.
+---
+
+import { SuggestionPrimitiveSample } from "@/components/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. When the thread is running, it falls back to populating the composer instead.
+- **`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
+
+### 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)