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

package/.docs/raw/docs/ui/thread.mdx

@@ -1,559 +0,0 @@
----
-title: Thread Component
-description: Stream-ready React chat container with message list, composer, auto-scroll, and accessibility built in. Drop into any AI chat UI built with assistant-ui.
-platforms: ["react"]
----
-
-import { ThreadSample } from "@/components/pages/docs/samples/thread";
-import { ThreadHistorySample } from "@/components/pages/docs/samples/thread/thread-history";
-import { ThreadActionsSample } from "@/components/pages/docs/samples/thread/message-actions";
-import { PreviewCode } from "@/components/pages/docs/preview-code.server";
-import { ThreadWelcomeSuggestionsSample } from "@/components/pages/docs/samples/thread/welcome-with-suggestions";
-import { ThreadBranchSample } from "@/components/pages/docs/samples/thread/branching-response";
-import { ThreadRunningSample } from "@/components/pages/docs/samples/thread/running-response";
-
-A complete chat interface that combines message rendering, auto-scrolling, composer input,
-attachments, and conditional UI states. Fully customizable and composable.
-
-
-<ThreadSample />
-
-## Anatomy
-
-The `Thread` component is built with the following primitives:
-
-```tsx
-import { ThreadPrimitive, AuiIf } from "@assistant-ui/react";
-
-<ThreadPrimitive.Root>
-  <ThreadPrimitive.Viewport>
-    <AuiIf condition={(s) => s.thread.isEmpty}>
-      <ThreadWelcome />
-      {/* ThreadWelcome includes ThreadPrimitive.Suggestions */}
-    </AuiIf>
-
-    <ThreadPrimitive.Messages>
-      {({ message }) => {
-        if (message.role === "user") return <UserMessage />;
-        return <AssistantMessage />;
-      }}
-    </ThreadPrimitive.Messages>
-
-    <ThreadPrimitive.ViewportFooter>
-      <ThreadPrimitive.ScrollToBottom />
-      <Composer />
-    </ThreadPrimitive.ViewportFooter>
-  </ThreadPrimitive.Viewport>
-</ThreadPrimitive.Root>
-```
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add the component
-
-<InstallCommand shadcn={["thread"]} />
-
-This adds a `/components/assistant-ui/thread.tsx` file to your project, which you can adjust as needed.
-
-  </Step>
-  <Step>
-
-### Use in your application
-
-```tsx title="/app/page.tsx" {1,6}
-import { Thread } from "@/components/assistant-ui/thread";
-
-export default function Chat() {
-  return (
-    <div className="h-full">
-      <Thread />
-    </div>
-  );
-}
-```
-
-  </Step>
-</Steps>
-
-## Examples
-
-### Welcome Screen
-
-```tsx
-<AuiIf condition={(s) => s.thread.isEmpty}>
-  <ThreadWelcome />
-</AuiIf>
-```
-
-### Viewport Spacer
-
-```tsx
-<AuiIf condition={(s) => !s.thread.isEmpty}>
-  <div className="min-h-8 grow" />
-</AuiIf>
-```
-
-### Thread with History
-
-The thread shows a completed multi-turn conversation. The composer stays below the
-messages, ready for the next input.
-
-<ThreadHistorySample />
-
-### Conditional Send/Cancel Button
-
-```tsx
-<AuiIf condition={(s) => !s.thread.isRunning}>
-  <ComposerPrimitive.Send>
-    Send
-  </ComposerPrimitive.Send>
-</AuiIf>
-
-<AuiIf condition={(s) => s.thread.isRunning}>
-  <ComposerPrimitive.Cancel>
-    Cancel
-  </ComposerPrimitive.Cancel>
-</AuiIf>
-```
-
-While the last assistant response runs, the composer shows the cancel action, not the send action, and the action bar of the response stays hidden. Click the stop button to cancel the run. The composer then shows the send action again.
-
-<ThreadRunningSample />
-
-### Suggestions
-
-Display suggested prompts using the Suggestions API. See the [Suggestions guide](/docs/guides/suggestions) for detailed configuration.
-
-An empty thread centers the welcome screen and shows the configured suggestion chips. When you select a chip, the thread sends its prompt.
-
-<PreviewCode
-  file="components/pages/docs/samples/thread/welcome-with-suggestions"
-  name="ChatWithSuggestions"
->
-  <ThreadWelcomeSuggestionsSample />
-</PreviewCode>
-
-```tsx
-import type { ReactNode } from "react";
-import {
-  AssistantRuntimeProvider,
-  AuiConfig,
-  SuggestionPrimitive,
-  Suggestions,
-  ThreadPrimitive,
-} from "@assistant-ui/react";
-import { useChatRuntime } from "@assistant-ui/ai-sdk";
-
-// Configure suggestions in your runtime provider
-const config = AuiConfig({
-  suggestions: Suggestions(["What's the weather?", "Tell me a joke"]),
-});
-
-const App = ({ children }: { children: ReactNode }) => {
-  const runtime = useChatRuntime();
-  return (
-    <AssistantRuntimeProvider runtime={runtime} config={config}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-};
-
-// Display suggestions in your thread component
-const ThreadSuggestions = () => (
-  <ThreadPrimitive.Suggestions>
-    {() => <SuggestionItem />}
-  </ThreadPrimitive.Suggestions>
-);
-
-// Custom suggestion item
-const SuggestionItem = () => (
-  <SuggestionPrimitive.Trigger send asChild>
-    <button>
-      <SuggestionPrimitive.Title />
-    </button>
-  </SuggestionPrimitive.Trigger>
-);
-```
-
-### Branching Response
-
-Select the refresh action below the assistant response to make an alternate branch. The built-in branch picker then shows `2 / 2` with arrows that switch between the two branches.
-
-<PreviewCode
-  file="components/pages/docs/samples/thread/branching-response"
-  name="Chat"
->
-  <ThreadBranchSample />
-</PreviewCode>
-
-### Message Actions
-
-Hover over the first assistant response to show its action bar. When the thread is idle, the last response always shows its actions. The copied `Thread` component sets `hideWhenRunning` and `autohide="not-last"` on `ActionBarPrimitive.Root`. Refer to the [ActionBar primitive](/docs/primitives/action-bar) to change this behavior.
-
-<ThreadActionsSample />
-
-## Composer Focus
-
-Set `autoFocus={false}` to keep the page focus. This setting stops composer focus when the thread mounts, starts a run, changes threads, or scrolls to the bottom. The default value is `true`.
-
-## Component Overrides
-
-`Thread` accepts an optional `components` prop that swaps parts of the rendering without editing the copied file. All slots are optional; omitted slots keep the built-in rendering.
-
-```tsx
-import { Thread, type ThreadComponents } from "@/components/assistant-ui/thread";
-
-const THREAD_COMPONENTS: ThreadComponents = {
-  ToolFallback: MyToolFallback,
-  ToolGroup: MyToolGroup,
-};
-
-export default function Chat() {
-  return <Thread components={THREAD_COMPONENTS} />;
-}
-```
-
-<ParametersTable
-  type="ThreadComponents"
-  parameters={[
-    {
-      name: "AssistantMessage",
-      type: "ComponentType",
-      description: "Replaces the entire assistant message, including the action bar and branch picker.",
-    },
-    {
-      name: "Welcome",
-      type: "ComponentType",
-      description: "Replaces the welcome screen shown for a new chat.",
-    },
-    {
-      name: "ToolFallback",
-      type: "ToolCallMessagePartComponent",
-      description: "Renders tool calls that have no tool UI registered by name. Registered tool UIs take precedence over this slot.",
-    },
-    {
-      name: "ToolGroup",
-      type: "ComponentType<PropsWithChildren<{ group: ThreadGroupPart }>>",
-      description: "Wraps runs of consecutive tool calls. Receives the group part (`indices`, `status`) and the rendered children.",
-    },
-    {
-      name: "ReasoningGroup",
-      type: "ComponentType<PropsWithChildren<{ group: ThreadGroupPart }>>",
-      description: "Wraps runs of consecutive reasoning parts. Receives the group part and the rendered children.",
-    },
-  ]}
-/>
-
-Define the `components` object once at module scope (or memoize it) so message subtrees do not re-render whenever the parent re-renders.
-
-For per-tool UI, prefer registering a renderer by tool name over overriding `ToolFallback`: put `render` on the matching toolkit entry (see [Tool UI](/docs/tools/tool-ui)). `data` message parts render through renderers registered with `useAssistantDataUI`; parts without a registered renderer are not displayed.
-
-## API Reference
-
-The following primitives are used within the Thread component and can be customized in your `/components/assistant-ui/thread.tsx` file.
-
-### Root
-
-Contains all parts of the thread.
-
-<ParametersTable
-  type="ThreadPrimitiveRootProps"
-  parameters={[
-    {
-      name: "asChild",
-      type: "boolean",
-      default: "false",
-      description: "Merge props with child element instead of rendering a wrapper div.",
-    },
-    {
-      name: "className",
-      type: "string",
-      description: "CSS class name.",
-    },
-  ]}
-/>
-
-This primitive renders a `<div>` element unless `asChild` is set.
-
-### Viewport
-
-The scrollable area containing all messages. Automatically scrolls to the bottom as new messages are added.
-
-<ParametersTable
-  type="ThreadPrimitiveViewportProps"
-  parameters={[
-    {
-      name: "asChild",
-      type: "boolean",
-      default: "false",
-      description: "Merge props with child element instead of rendering a wrapper div.",
-    },
-    {
-      name: "autoScroll",
-      type: "boolean",
-      default: 'true (false when turnAnchor is "top")',
-      description:
-        "Whether to automatically scroll to the bottom when new messages are added while the viewport was previously scrolled to the bottom.",
-    },
-    {
-      name: "turnAnchor",
-      type: '"top" | "bottom"',
-      default: '"bottom"',
-      description:
-        'Controls scroll anchoring behavior for new messages. "top" anchors new user messages at the top of the viewport.',
-    },
-    {
-      name: "topAnchorMessageClamp",
-      type: '{ tallerThan?: string; visibleHeight?: string }',
-      default: '{ tallerThan: "10em", visibleHeight: "6em" }',
-      description:
-        'Clamps tall user messages when turnAnchor is "top". Messages up to `tallerThan` stay fully visible; taller messages show only `visibleHeight` of their bottom edge above the assistant response.',
-      children: [
-        {
-          type: '{ tallerThan?: string; visibleHeight?: string }',
-          parameters: [
-            {
-              name: "tallerThan",
-              type: "string",
-              default: '"10em"',
-              description: "Clamp messages taller than this CSS length.",
-            },
-            {
-              name: "visibleHeight",
-              type: "string",
-              default: '"6em"',
-              description:
-                "Visible portion of a clamped message's bottom edge.",
-            },
-          ],
-        },
-      ],
-    },
-    {
-      name: "scrollToBottomOnRunStart",
-      type: "boolean",
-      default: "true",
-      description: "Whether to scroll to bottom when a new run starts.",
-    },
-    {
-      name: "scrollToBottomOnInitialize",
-      type: "boolean",
-      default: "true",
-      description:
-        "Whether to scroll to bottom when thread history is first loaded.",
-    },
-    {
-      name: "scrollToBottomOnThreadSwitch",
-      type: "boolean",
-      default: "true",
-      description:
-        "Whether to scroll to bottom when switching to a different thread.",
-    },
-    {
-      name: "className",
-      type: "string",
-      description: "CSS class name.",
-    },
-  ]}
-/>
-
-This primitive renders a `<div>` element unless `asChild` is set.
-
-### Messages
-
-Renders all messages in the thread. This primitive renders a separate component for each message.
-
-```tsx
-<ThreadPrimitive.Messages>
-  {({ message }) => {
-    if (message.role === "user") return <UserMessage />;
-    return <AssistantMessage />;
-  }}
-</ThreadPrimitive.Messages>
-```
-
-<ParametersTable
-  type="ThreadPrimitiveMessagesProps"
-  parameters={[
-    {
-      name: "components",
-      type: "MessageComponents",
-      required: true,
-      description: "Components to render for different message types.",
-      children: [
-        {
-          type: "MessageComponents",
-          parameters: [
-            {
-              name: "Message",
-              type: "ComponentType",
-              description: "Default component for all messages.",
-            },
-            {
-              name: "UserMessage",
-              type: "ComponentType",
-              description: "Component for user messages.",
-            },
-            {
-              name: "EditComposer",
-              type: "ComponentType",
-              description:
-                "Component for user messages being edited.",
-            },
-            {
-              name: "AssistantMessage",
-              type: "ComponentType",
-              description: "Component for assistant messages.",
-            },
-            {
-              name: "SystemMessage",
-              type: "ComponentType",
-              description: "Component for system messages.",
-            },
-          ],
-        },
-      ],
-    },
-  ]}
-/>
-
-
-### MessageByIndex
-
-Renders a single message at the specified index.
-
-```tsx
-<ThreadPrimitive.MessageByIndex
-  index={0}
-  components={{
-    UserMessage: UserMessage,
-    AssistantMessage: AssistantMessage
-  }}
-/>
-```
-
-<ParametersTable
-  type="ThreadPrimitiveMessageByIndexProps"
-  parameters={[
-    {
-      name: "index",
-      type: "number",
-      required: true,
-      description: "The index of the message to render.",
-    },
-    {
-      name: "components",
-      type: "MessageComponents",
-      description: "Components to render for different message types.",
-    },
-  ]}
-/>
-
-### Empty
-
-Renders children only when there are no messages in the thread.
-
-<ParametersTable
-  type="ThreadPrimitiveEmptyProps"
-  parameters={[
-    {
-      name: "children",
-      type: "ReactNode",
-      description: "Content to display when the thread is empty.",
-    },
-  ]}
-/>
-
-### ScrollToBottom
-
-A button to scroll the viewport to the bottom. Disabled when the viewport is already at the bottom.
-
-<ParametersTable
-  type="ThreadPrimitiveScrollToBottomProps"
-  parameters={[
-    {
-      name: "asChild",
-      type: "boolean",
-      default: "false",
-      description: "Merge props with child element instead of rendering a wrapper button.",
-    },
-    {
-      name: "className",
-      type: "string",
-      description: "CSS class name.",
-    },
-  ]}
-/>
-
-This primitive renders a `<button>` element unless `asChild` is set.
-
-### Suggestions
-
-Renders all configured suggestions. Configure suggestions using the `Suggestions()` API in your runtime provider.
-
-```tsx
-<ThreadPrimitive.Suggestions>
-  {() => <CustomSuggestionComponent />}
-</ThreadPrimitive.Suggestions>
-```
-
-<ParametersTable
-  type="ThreadPrimitiveSuggestionsProps"
-  parameters={[
-    {
-      name: "components",
-      type: "{ Suggestion: ComponentType }",
-      description: "Custom component to render each suggestion.",
-    },
-  ]}
-/>
-
-<Callout type="info">
-See the [Suggestions guide](/docs/guides/suggestions) for detailed information on configuring and customizing suggestions.
-</Callout>
-
-### AuiIf
-
-Conditionally renders children based on assistant state. This is a generic component that can access thread, message, composer, and other state.
-
-```tsx
-import { AuiIf } from "@assistant-ui/react";
-
-<AuiIf condition={(s) => s.thread.isEmpty}>
-  <WelcomeScreen />
-</AuiIf>
-
-<AuiIf condition={(s) => s.thread.isRunning}>
-  <LoadingIndicator />
-</AuiIf>
-
-<AuiIf condition={(s) => s.message.role === "assistant"}>
-  <AssistantAvatar />
-</AuiIf>
-```
-
-<ParametersTable
-  type="AuiIfProps"
-  parameters={[
-    {
-      name: "condition",
-      type: "(state: AssistantState) => boolean",
-      required: true,
-      description: "A function that receives the assistant state and returns whether to render children.",
-    },
-  ]}
-/>
-
-<Callout type="info">
-The condition function receives an `AssistantState` object with access to `thread`, `message`, `composer`, `part`, and `attachment` state depending on context.
-</Callout>
-
-
-## Related Components
-
-- [ThreadList](/docs/ui/thread-list) - List of threads, with or without sidebar
-- [Quoting guide](/docs/guides/quoting) - Quote selected text from messages
-- [SelectionToolbarPrimitive](/docs/api-reference/primitives/selection-toolbar) - Floating toolbar API reference

package/.docs/raw/docs/ui/tool-fallback.mdx

@@ -1,141 +0,0 @@
----
-title: ToolFallback
-description: Default UI component for tools without dedicated custom renderers.
-platforms: ["react"]
----
-
-import {
-  ToolFallbackSample,
-  ToolFallbackCompletedSample,
-  ToolFallbackCancelledSample,
-  ToolFallbackStreamingSample,
-} from "@/components/pages/docs/samples/tool-fallback";
-import { PreviewCode } from "@/components/pages/docs/preview-code.server";
-import { ToolFallbackApprovalSample } from "@/components/pages/docs/samples/tool-fallback/approval";
-import { ToolFallbackErrorSample } from "@/components/pages/docs/samples/tool-fallback/failed-with-error";
-
-<ToolFallbackSample />
-
-## Getting Started
-
-<Steps>
-  <Step>
-
-### Add `tool-fallback`
-
-<InstallCommand shadcn={["tool-fallback"]} />
-
-This adds a `/components/assistant-ui/tool-fallback.tsx` file to your project, which you can adjust as needed.
-
-  </Step>
-  <Step>
-
-### Use it in your application
-
-Pass the `ToolFallback` component to the `MessagePrimitive.Parts` component
-
-```tsx title="/components/assistant-ui/thread.tsx" {1,9}
-import { ToolFallback } from "@/components/assistant-ui/tool-fallback";
-
-const AssistantMessage = () => {
-  return (
-    <MessagePrimitive.Root>
-      <MessagePrimitive.Parts>
-        {({ part }) => {
-          if (part.type === "tool-call") return <ToolFallback {...part} />;
-          return null;
-        }}
-      </MessagePrimitive.Parts>
-    </MessagePrimitive.Root>
-  );
-};
-```
-
-  </Step>
-</Steps>
-
-## Examples
-
-### Streaming Demo
-
-Interactive demo showing the full tool call lifecycle: running → complete.
-
-<ToolFallbackStreamingSample />
-
-### Completed With Result
-
-Shows the arguments and the structured result for the completed call.
-
-<ToolFallbackCompletedSample />
-
-### Failed With Error State
-
-Shows a service error above its arguments.
-
-<ToolFallbackErrorSample />
-
-### Cancelled State
-
-The "Cancelled tool" label has a line through it. The arguments are muted after you open the call.
-
-<ToolFallbackCancelledSample />
-
-### Approval State
-
-Select Allow or Deny. The `resume` callback records the choice, removes the buttons, and shows the result. The block opens automatically for `requires-action`, so you can select a decision without an extra click. A tool call whose approval gate is decided shows no buttons. Edit your project's copy of `tool-fallback.tsx` to add trust escalation, edit-args, custom labels, or analytics hooks.
-
-<PreviewCode
-  file="components/pages/docs/samples/tool-fallback/approval"
-  name="ToolWithApproval"
->
-  <ToolFallbackApprovalSample />
-</PreviewCode>
-
-## Composable API
-
-All sub-components are exported for custom layouts:
-
-| Component | Description |
-| --------- | ----------- |
-| `ToolFallback.Root` | Collapsible container with scroll lock |
-| `ToolFallback.Trigger` | Header with tool name, status icon, and shimmer |
-| `ToolFallback.Content` | Animated collapsible content wrapper |
-| `ToolFallback.Args` | Displays tool arguments |
-| `ToolFallback.Result` | Displays tool execution result |
-| `ToolFallback.Error` | Displays error or cancellation messages |
-| `ToolFallback.Approval` | Renders Allow / Deny buttons for `requires-action` tools until a decision is recorded; wires `resume` / `addResult` / `respondToApproval` |
-
-```tsx
-import {
-  ToolFallback,
-  ToolFallbackRoot,
-  ToolFallbackTrigger,
-  ToolFallbackContent,
-  ToolFallbackArgs,
-  ToolFallbackResult,
-  ToolFallbackError,
-  ToolFallbackApproval,
-} from "@/components/assistant-ui/tool-fallback";
-
-// Compound component syntax
-<ToolFallback.Root>
-  <ToolFallback.Trigger toolName="get_weather" status={status} />
-  <ToolFallback.Content>
-    <ToolFallback.Error status={status} />
-    <ToolFallback.Args argsText={argsText} />
-    <ToolFallback.Approval
-      addResult={addResult}
-      resume={resume}
-      interrupt={interrupt}
-      approval={approval}
-      respondToApproval={respondToApproval}
-      status={status}
-    />
-    <ToolFallback.Result result={result} />
-  </ToolFallback.Content>
-</ToolFallback.Root>
-```
-
-## Related Components
-
-- [ToolGroup](/docs/ui/tool-group) - Group consecutive tool calls together