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

package/.docs/raw/docs/ui/attachment.mdx

@@ -1,279 +0,0 @@
----
-title: Attachment
-description: UI components for attaching and viewing files in messages.
-platforms: ["react"]
----
-
-import { AttachmentSample } from "@/components/pages/docs/samples/attachment";
-import * as AttachmentRadixSamples from "@/components/pages/docs/samples/attachment.radix";
-import { Flavored, FlavorSwitcher } from "@/components/pages/docs/contexts/flavor.server";
-import { PreviewCode } from "@/components/pages/docs/preview-code.server";
-import { AttachmentComposerSample } from "@/components/pages/docs/samples/attachment/composer-attachments";
-import * as AttachmentComposerRadixSample from "@/components/pages/docs/samples/attachment/composer-attachments.radix";
-import { AttachmentMessageContextSample } from "@/components/pages/docs/samples/attachment/message-attachments";
-import * as AttachmentMessageRadixSample from "@/components/pages/docs/samples/attachment/message-attachments.radix";
-import { AttachmentTypesSample } from "@/components/pages/docs/samples/attachment/types";
-import * as AttachmentTypesRadixSample from "@/components/pages/docs/samples/attachment/types.radix";
-import { AttachmentPreviewSample } from "@/components/pages/docs/samples/attachment/image-preview";
-import * as AttachmentPreviewRadixSample from "@/components/pages/docs/samples/attachment/image-preview.radix";
-
-<FlavorSwitcher />
-
-<Flavored radix={<AttachmentRadixSamples.AttachmentSample />} base={<AttachmentSample />} />
-
-<Callout type="info">
-  **Note:** These components provide the UI for attachments, but you also need
-  to configure attachment adapters in your runtime to handle file uploads and
-  processing. See the [Attachments Guide](/docs/guides/attachments) for complete
-  setup instructions.
-</Callout>
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add `attachment`
-
-<InstallCommand shadcn={["attachment"]} />
-
-This adds a `/components/assistant-ui/attachment.tsx` file to your project, which you can adjust as needed.
-
-  </Step>
-  <Step>
-
-### Use in your application
-
-Add `ComposerAttachments` and `ComposerAddAttachment` to your composer:
-
-```tsx title="/components/assistant-ui/thread.tsx" {1-4,9-10}
-import {
-  ComposerAttachments,
-  ComposerAddAttachment,
-} from "@/components/assistant-ui/attachment";
-
-const Composer: FC = () => {
-  return (
-    <ComposerPrimitive.Root className="...">
-      <ComposerAttachments />
-      <ComposerAddAttachment />
-
-      <ComposerPrimitive.Input
-        autoFocus
-        placeholder="Write a message..."
-        rows={1}
-        className="..."
-      />
-      <ComposerAction />
-    </ComposerPrimitive.Root>
-  );
-};
-```
-
-Add `UserMessageAttachments` to your user message:
-
-```tsx title="/components/assistant-ui/thread.tsx" {1,8}
-import { UserMessageAttachments } from "@/components/assistant-ui/attachment";
-
-const UserMessage: FC = () => {
-  return (
-    <MessagePrimitive.Root className="...">
-      <UserActionBar />
-
-      <UserMessageAttachments />
-
-      <div className="...">
-        <MessagePrimitive.Parts />
-      </div>
-
-      <BranchPicker className="..." />
-    </MessagePrimitive.Root>
-  );
-};
-```
-
-  </Step>
-</Steps>
-
-## Examples
-
-### Composer
-
-In the composer, each attachment tile shows a remove button that deletes the attachment from the composer. Use the plus button to add your own files.
-
-<PreviewCode file="components/pages/docs/samples/attachment/composer-attachments" name="ComposerWithAttachments" base={<AttachmentComposerSample />}>
-  <AttachmentComposerRadixSample.AttachmentComposerSample />
-</PreviewCode>
-
-### User Message
-
-Message attachments are read-only. The same tile in a sent user message does not show a remove button.
-
-<PreviewCode file="components/pages/docs/samples/attachment/message-attachments" name="UserMessageWithAttachments" base={<AttachmentMessageContextSample />}>
-  <AttachmentMessageRadixSample.AttachmentMessageContextSample />
-</PreviewCode>
-
-### Custom Types
-
-This example shows the image tile and the generic fallback tile used for the built-in document type and the custom attachment type. The two fallback tiles use the same icon, but their accessible labels distinguish them.
-
-<PreviewCode file="components/pages/docs/samples/attachment/types" name="AttachmentTypesSample" base={<AttachmentTypesSample />}>
-  <AttachmentTypesRadixSample.AttachmentTypesSample />
-</PreviewCode>
-
-### Image Preview
-
-When you click an image tile or activate it with the keyboard, a full-size preview dialog opens.
-
-<PreviewCode file="components/pages/docs/samples/attachment/image-preview" name="AttachmentPreviewSample" base={<AttachmentPreviewSample />}>
-  <AttachmentPreviewRadixSample.AttachmentPreviewSample />
-</PreviewCode>
-
-## API Reference
-
-### Composer Attachments
-
-#### ComposerPrimitive.Attachments
-
-Renders all attachments in the composer.
-
-<ParametersTable
-  type="ComposerPrimitiveAttachmentsProps"
-  parameters={[
-    {
-      name: "components",
-      type: "AttachmentComponents",
-      description: "Components to render for different attachment types.",
-      children: [
-        {
-          type: "AttachmentComponents",
-          parameters: [
-            {
-              name: "Image",
-              type: "ComponentType",
-              description: "Component for image attachments.",
-            },
-            {
-              name: "Document",
-              type: "ComponentType",
-              description: "Component for document attachments (PDF, etc.).",
-            },
-            {
-              name: "File",
-              type: "ComponentType",
-              description: "Component for generic file attachments.",
-            },
-            {
-              name: "Attachment",
-              type: "ComponentType",
-              description: "Fallback component for all attachment types.",
-            },
-          ],
-        },
-      ],
-    },
-  ]}
-/>
-
-#### ComposerPrimitive.AddAttachment
-
-A button that opens the file picker to add attachments.
-
-<ParametersTable
-  type="ComposerPrimitiveAddAttachmentProps"
-  parameters={[
-    {
-      name: "multiple",
-      type: "boolean",
-      default: "true",
-      description: "Allow selecting multiple files at once.",
-    },
-    {
-      name: "asChild",
-      type: "boolean",
-      default: "false",
-      description: "Merge props with child element instead of rendering a wrapper button.",
-    },
-  ]}
-/>
-
-This primitive renders a `<button>` element unless `asChild` is set.
-
-### Message Attachments
-
-#### MessagePrimitive.Attachments
-
-Renders all attachments in a user message.
-
-<ParametersTable
-  type="MessagePrimitiveAttachmentsProps"
-  parameters={[
-    {
-      name: "components",
-      type: "AttachmentComponents",
-      description: "Components to render for different attachment types (same as ComposerPrimitive.Attachments).",
-    },
-  ]}
-/>
-
-### Attachment Primitives
-
-#### AttachmentPrimitive.Root
-
-Container for a single attachment.
-
-<ParametersTable
-  type="AttachmentPrimitiveRootProps"
-  parameters={[
-    {
-      name: "asChild",
-      type: "boolean",
-      default: "false",
-      description: "Merge props with child element instead of rendering a wrapper div.",
-    },
-  ]}
-/>
-
-#### AttachmentPrimitive.Name
-
-Renders the attachment's file name.
-
-#### AttachmentPrimitive.Remove
-
-A button to remove the attachment from the composer.
-
-<ParametersTable
-  type="AttachmentPrimitiveRemoveProps"
-  parameters={[
-    {
-      name: "asChild",
-      type: "boolean",
-      default: "false",
-      description: "Merge props with child element instead of rendering a wrapper button.",
-    },
-  ]}
-/>
-
-### Attachment Types
-
-Attachments have the following structure:
-
-```typescript
-type Attachment = {
-  id: string;
-  type: "image" | "document" | "file" | (string & {});
-  name: string;
-  contentType?: string;
-  file?: File;
-  status:
-    | { type: "running" | "requires-action" | "incomplete"; progress?: number }
-    | { type: "complete" };
-};
-```
-
-The `type` field accepts custom strings (e.g. `"data-workflow"`) beyond the built-in types. When an unknown type is encountered, the generic `Attachment` component is used as a fallback. The `contentType` field is optional — it can be omitted for non-file attachments where a MIME type is not meaningful.
-
-## Related Components
-
-- [Thread](/docs/ui/thread) - Main chat interface that displays attachments
-- [Attachments Guide](/docs/guides/attachments) - Complete setup instructions for attachment adapters

package/.docs/raw/docs/ui/composer-trigger-popover.mdx

@@ -1,247 +0,0 @@
----
-title: Composer Trigger Popover
-description: Reusable picker UI for @ mentions, / slash commands, and any other character-triggered popover.
-platforms: ["react"]
----
-
-import { ComposerTriggerPopoverSample } from "@/components/pages/docs/samples/composer-trigger-popover";
-
-<ComposerTriggerPopoverSample />
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add `composer-trigger-popover`
-
-<InstallCommand shadcn={["composer-trigger-popover"]} />
-
-This adds `/components/assistant-ui/composer-trigger-popover.tsx` — a generic picker UI (Categories + Items + Back) driven by an adapter and one of two behavior props: `directive` (insert a chip) or `action` (run a callback).
-
-  </Step>
-  <Step>
-
-### Wrap the composer
-
-Place `ComposerPrimitive.Unstable_TriggerPopoverRoot` around your composer. Any number of `ComposerTriggerPopover` declarations can live inside — each with its own trigger character, adapter, and behavior prop.
-
-```tsx title="components/assistant-ui/thread.tsx"
-import { ComposerPrimitive } from "@assistant-ui/react";
-import { ComposerTriggerPopover } from "@/components/assistant-ui/composer-trigger-popover";
-
-const Composer = () => (
-  <ComposerPrimitive.Unstable_TriggerPopoverRoot>
-    <ComposerPrimitive.Root>
-      <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
-      <ComposerPrimitive.Send />
-
-      {/* triggers declared here */}
-    </ComposerPrimitive.Root>
-  </ComposerPrimitive.Unstable_TriggerPopoverRoot>
-);
-```
-
-  </Step>
-</Steps>
-
-## @ Mention
-
-Pair the popover with `unstable_useMentionAdapter` — the hook returns a spreadable `{ adapter, directive }` bundle so selecting an item writes a `:tool[Label]{name=id}` directive into the composer text.
-
-```tsx
-import { unstable_useMentionAdapter } from "@assistant-ui/react";
-import { WrenchIcon } from "lucide-react";
-
-const mention = unstable_useMentionAdapter();
-
-<ComposerTriggerPopover
-  char="@"
-  {...mention}
-  fallbackIcon={WrenchIcon}
-/>;
-```
-
-Override formatter or add an `onInserted` callback via hook options: `unstable_useMentionAdapter({ formatter, onInserted })`.
-
-`unstable_useMentionAdapter` also accepts `items` (flat custom list), `categories` (multi-category drill-down), and `includeModelContextTools` for fine-grained control. See the [Mentions guide](/docs/guides/mentions#built-in-mention-adapter).
-
-Render selected mentions as chips in user messages with [`DirectiveText`](/docs/ui/directive-text). For inline chips **inside** the composer, use [`LexicalComposerInput`](/docs/guides/mentions#textarea-vs-lexical).
-
-## / Slash Command
-
-Use [`unstable_useSlashCommandAdapter`](/docs/guides/slash-commands) to bundle commands (data + `execute`) into `{ adapter, action }` — then plug both into `ComposerTriggerPopover`. By default a directive chip is left in the composer as an audit trail; pass `removeOnExecute` to strip the `/command` text entirely. `iconMap` maps `metadata.icon` strings on items and categories to Lucide icons.
-
-```tsx
-import {
-  unstable_useSlashCommandAdapter,
-  type Unstable_SlashCommand,
-} from "@assistant-ui/react";
-import { FileTextIcon, GlobeIcon, LanguagesIcon, SlashIcon } from "lucide-react";
-
-const SLASH_COMMANDS: readonly Unstable_SlashCommand[] = [
-  {
-    id: "summarize",
-    description: "Summarize the conversation",
-    icon: "FileText",
-    execute: () => {/* ... */},
-  },
-  {
-    id: "translate",
-    description: "Translate to another language",
-    icon: "Languages",
-    execute: () => {/* ... */},
-  },
-  {
-    id: "search",
-    description: "Search the web",
-    icon: "Globe",
-    execute: () => {/* ... */},
-  },
-];
-
-function SlashComposer() {
-  const slash = unstable_useSlashCommandAdapter({ commands: SLASH_COMMANDS });
-
-  return (
-    <ComposerTriggerPopover
-      char="/"
-      {...slash}
-      iconMap={{
-        FileText: FileTextIcon,
-        Languages: LanguagesIcon,
-        Globe: GlobeIcon,
-      }}
-      fallbackIcon={SlashIcon}
-    />
-  );
-}
-```
-
-## Custom Query Matching
-
-By default, whitespace closes a trigger query. Pass a stable `matcher` when a picker needs different syntax, such as multi-word business names. The same matcher controls the textarea popover and Lexical directive insertion.
-
-```tsx
-import type { Unstable_TriggerMatcher } from "@assistant-ui/react";
-
-const matchMultiWord: Unstable_TriggerMatcher = (
-  text,
-  triggerChar,
-  cursorPosition,
-) => {
-  const textUpToCursor = text.slice(0, cursorPosition);
-  const offset = textUpToCursor.lastIndexOf(triggerChar);
-  if (offset === -1) return null;
-
-  const preceding = textUpToCursor[offset - 1];
-  if (preceding && !/\s/u.test(preceding)) return null;
-
-  const query = textUpToCursor.slice(offset + triggerChar.length);
-  if (/[\n\t]/u.test(query) || query.endsWith("  ")) return null;
-
-  return { query, offset, endOffset: cursorPosition };
-};
-
-<ComposerTriggerPopover
-  char="@"
-  matcher={matchMultiWord}
-  {...mention}
-/>;
-```
-
-The matcher receives the serialized composer text for a textarea and the current text node for Lexical. `offset` is the trigger index in that string. `endOffset` is the exclusive end of the span both inputs replace. `query` is the search string and may differ from that span.
-
-## Combining Triggers
-
-Multiple popovers coexist under one `TriggerPopoverRoot`. Each reads state from its own declaration, so `@` and `/` never collide.
-
-```tsx
-const commandHandlers: Record<string, () => void> = {
-  summarize: () => {/* ... */},
-  translate: () => {/* ... */},
-};
-
-<ComposerPrimitive.Unstable_TriggerPopoverRoot>
-  <ComposerPrimitive.Root>
-    <ComposerPrimitive.Input placeholder="Type @ to mention, / for commands..." />
-
-    <ComposerTriggerPopover
-      char="@"
-      adapter={mentionAdapter}
-      directive={{ formatter: unstable_defaultDirectiveFormatter }}
-      fallbackIcon={WrenchIcon}
-    />
-    <ComposerTriggerPopover
-      char="/"
-      adapter={slashAdapter}
-      action={{
-        formatter: unstable_defaultDirectiveFormatter,
-        onExecute: (item) => commandHandlers[item.id]?.(),
-      }}
-      iconMap={slashIcons}
-      fallbackIcon={SlashIcon}
-    />
-  </ComposerPrimitive.Root>
-</ComposerPrimitive.Unstable_TriggerPopoverRoot>
-```
-
-## Keyboard Navigation
-
-| Key | Action |
-| --- | --- |
-| <Kbd>ArrowDown</Kbd> | Highlight next item |
-| <Kbd>ArrowUp</Kbd> | Highlight previous item |
-| <Kbd>Enter</Kbd> / <Kbd>Tab</Kbd> | Select highlighted item / drill into category |
-| <Kbd>Shift + Enter</Kbd> | Insert newline (popover stays open) |
-| <Kbd>Shift + Tab</Kbd> | Pass through (native focus traversal) |
-| <Kbd>Escape</Kbd> | Close popover |
-| <Kbd>Backspace</Kbd> | Go back to categories (when query is empty) |
-
-## Accessibility
-
-The popover implements the WAI-ARIA editable combobox pattern.
-
-- The listbox container has `role="listbox"` and each item has `role="option"` plus `aria-selected`.
-- When a popover is open, `ComposerPrimitive.Input` (the underlying `<textarea>`) automatically receives `aria-controls`, `aria-expanded="true"`, `aria-haspopup="listbox"`, and `aria-activedescendant` pointing at the highlighted option. Attributes are removed when the popover closes.
-- When `ComposerPrimitive.Input` is rendered outside a `TriggerPopoverRoot`, no ARIA attributes are added.
-
-## API Reference
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `char` | `string` | — | Trigger character, e.g. `"@"` or `"/"` (required; unique within the root) |
-| `matcher` | `Unstable_TriggerMatcher` | whitespace-terminated | Overrides trigger detection and the replace span for both textarea and Lexical inputs |
-| `adapter` | `Unstable_TriggerAdapter` | — | Provides categories, items, and search (required) |
-| `directive` | `{ formatter, onInserted?, chip? }` | — | Enables directive-insert behavior. Mutually exclusive with `action`. |
-| `action` | `{ formatter, onExecute, removeOnExecute?, chip? }` | — | Enables action behavior. Mutually exclusive with `directive`. |
-| `iconMap` | `Record<string, IconComponent>` | — | Maps `item.metadata.icon` / `category.metadata.icon` strings to icons |
-| `fallbackIcon` | `IconComponent` | `SparklesIcon` | Icon used when no `iconMap` entry matches |
-| `backLabel` | `string` | `"Back"` | Back button label |
-| `emptyCategoriesLabel` | `string` | `"No items available"` | Shown when no categories are available |
-| `emptyItemsLabel` | `string` | `"No matching items"` | Shown when no items match |
-| `isLoading` | `boolean` | `false` | Whether the adapter is resolving items (async sources). Pair with `unstable_useLiveCompletionAdapter`. |
-| `loadingLabel` | `string` | `"Loading…"` | Shown in place of `emptyItemsLabel` while `isLoading` and no items are present |
-
-All other props (`className`, etc.) forward to the underlying popover `div`.
-
-### `directive` object
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `formatter` | `Unstable_DirectiveFormatter` | Serializes the selected item into the directive text written to the composer |
-| `onInserted` | `(item) => void` | Optional callback fired after the directive has been inserted |
-
-### `action` object
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `formatter` | `Unstable_DirectiveFormatter` | Serializes the selected item into the chip left behind (unused when `removeOnExecute`) |
-| `onExecute` | `(item) => void` | Callback fired when an item is selected |
-| `removeOnExecute` | `boolean` | When `true`, strips the trigger text instead of leaving a chip. Default `false`. |
-
-## Related
-
-- [Directive Text](/docs/ui/directive-text) — renderer for mention chips in user messages
-- [Mentions guide](/docs/guides/mentions) — `@`-mention architecture and formatter details
-- [Slash Commands guide](/docs/guides/slash-commands) — `/`-command architecture

package/.docs/raw/docs/ui/context-display.mdx

@@ -1,148 +0,0 @@
----
-title: Context Display
-description: Visualize token usage relative to a model's context window — ring, bar, or text — with a detailed hover popover.
-platforms: ["react"]
----
-
-import { ContextDisplaySample } from "@/components/pages/docs/samples/context-display";
-
-<ContextDisplaySample />
-
-<Callout type="info">
-  This component requires server-side setup to [forward token usage metadata](#forward-token-usage-from-your-route-handler). Without it, ContextDisplay will show 0 usage and no breakdown data.
-</Callout>
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add `context-display`
-
-<InstallCommand shadcn={["context-display"]} />
-
-This adds a `/components/assistant-ui/context-display.tsx` file to your project.
-
-  </Step>
-  <Step>
-
-### Forward token usage from your route handler
-
-Use `messageMetadata` in your Next.js route to attach `usage` from `finish` and `modelId` from `finish-step`:
-
-```tsx title="app/api/chat/route.ts"
-import { streamText, convertToModelMessages } from "ai";
-
-export async function POST(req: Request) {
-  const { messages, config } = await req.json();
-  const result = streamText({
-    model: getModel(config?.modelName),
-    messages: await convertToModelMessages(messages),
-  });
-  return result.toUIMessageStreamResponse({
-    messageMetadata: ({ part }) => {
-      if (part.type === "finish") {
-        return {
-          usage: part.totalUsage,
-        };
-      }
-      if (part.type === "finish-step") {
-        return {
-          modelId: part.response.modelId,
-        };
-      }
-      return undefined;
-    },
-  });
-}
-```
-
-  </Step>
-  <Step>
-
-### Use in your application
-
-Pick a variant and place it in your thread footer, composer, or sidebar. Pass `modelContextWindow` with your model's token limit.
-
-```tsx title="/components/assistant-ui/thread.tsx" {1,8}
-import { ContextDisplay } from "@/components/assistant-ui/context-display";
-
-const ThreadFooter: FC = () => {
-  return (
-    <div className="flex items-center justify-end px-3 py-1.5">
-      <ContextDisplay.Bar modelContextWindow={128000} />
-    </div>
-  );
-};
-```
-
-  </Step>
-</Steps>
-
-## Variants
-
-Three preset variants are available, each wrapping the shared tooltip popover:
-
-```tsx
-// SVG donut ring (default, compact)
-<ContextDisplay.Ring modelContextWindow={128000} />
-
-// Horizontal progress bar with label
-<ContextDisplay.Bar modelContextWindow={128000} />
-
-// Minimal monospace text
-<ContextDisplay.Text modelContextWindow={128000} />
-```
-
-All presets accept `className` for styling overrides and `side` to control tooltip placement (`"top"`, `"bottom"`, `"left"`, `"right"`).
-
-## Composable API
-
-For custom visualizations, use the building blocks directly:
-
-```tsx
-import { ContextDisplay } from "@/components/assistant-ui/context-display";
-
-<ContextDisplay.Root modelContextWindow={128000}>
-  <ContextDisplay.Trigger aria-label="Context usage">
-    <MyCustomGauge />
-  </ContextDisplay.Trigger>
-  <ContextDisplay.Content side="top" />
-</ContextDisplay.Root>
-```
-
-| Component | Description |
-|-----------|-------------|
-| `Root` | Uses provided `usage` when supplied, otherwise fetches token usage internally; provides shared context and wraps children in a tooltip |
-| `Trigger` | Button that opens the tooltip on hover |
-| `Content` | Tooltip popover with the token breakdown (Usage %, Input, Cached, Output, Reasoning, Total) |
-
-## API Reference
-
-### Preset Props
-
-All preset variants (`Ring`, `Bar`, `Text`) share the same props:
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelContextWindow` | `number` | — | Maximum token limit of the current model (required) |
-| `className` | `string` | — | Additional class names on the trigger button |
-| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"top"` | Tooltip placement |
-| `usage` | `ThreadTokenUsage` | — | Optional externally-provided usage data (skips internal usage fetch when provided) |
-
-### Color Thresholds
-
-Ring and Bar share the same severity colors:
-
-| Level | Threshold | Ring | Bar |
-|-------|-----------|------|-----|
-| Low | `< 65%` | `stroke-emerald-500` | `bg-emerald-500` |
-| Warning | `65% – 85%` | `stroke-amber-500` | `bg-amber-500` |
-| Critical | `> 85%` | `stroke-red-500` | `bg-red-500` |
-
-Text displays numeric values only — no severity color.
-
-## Related
-
-- [Message Timing](/docs/ui/message-timing) — Streaming performance stats (TTFT, tok/s)
-- [Thread](/docs/ui/thread) — The thread component where ContextDisplay is typically placed