@assistant-ui/mcp-docs-server 0.1.32 → 0.1.34

package/.docs/organized/code-examples/with-parent-id-grouping.md

@@ -1,596 +0,0 @@
-# Example: with-parent-id-grouping
-
-## app/globals.css
-
-```css
-@import "tailwindcss";
-@import "tw-animate-css";
-
-@source "../../../packages/ui/src";
-
-@custom-variant dark (&:is(.dark *));
-
-@theme inline {
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
-  --color-chart-1: var(--chart-1);
-  --color-chart-2: var(--chart-2);
-  --color-chart-3: var(--chart-3);
-  --color-chart-4: var(--chart-4);
-  --color-chart-5: var(--chart-5);
-  --color-sidebar: var(--sidebar);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-ring: var(--sidebar-ring);
-}
-
-:root {
-  --radius: 0.625rem;
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.141 0.005 285.823);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.141 0.005 285.823);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.141 0.005 285.823);
-  --primary: oklch(0.21 0.006 285.885);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.967 0.001 286.375);
-  --secondary-foreground: oklch(0.21 0.006 285.885);
-  --muted: oklch(0.967 0.001 286.375);
-  --muted-foreground: oklch(0.552 0.016 285.938);
-  --accent: oklch(0.967 0.001 286.375);
-  --accent-foreground: oklch(0.21 0.006 285.885);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.92 0.004 286.32);
-  --input: oklch(0.92 0.004 286.32);
-  --ring: oklch(0.705 0.015 286.067);
-  --chart-1: oklch(0.646 0.222 41.116);
-  --chart-2: oklch(0.6 0.118 184.704);
-  --chart-3: oklch(0.398 0.07 227.392);
-  --chart-4: oklch(0.828 0.189 84.429);
-  --chart-5: oklch(0.769 0.188 70.08);
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.141 0.005 285.823);
-  --sidebar-primary: oklch(0.21 0.006 285.885);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.967 0.001 286.375);
-  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
-  --sidebar-border: oklch(0.92 0.004 286.32);
-  --sidebar-ring: oklch(0.705 0.015 286.067);
-}
-
-.dark {
-  --background: oklch(0.141 0.005 285.823);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.21 0.006 285.885);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.21 0.006 285.885);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.92 0.004 286.32);
-  --primary-foreground: oklch(0.21 0.006 285.885);
-  --secondary: oklch(0.274 0.006 286.033);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.274 0.006 286.033);
-  --muted-foreground: oklch(0.705 0.015 286.067);
-  --accent: oklch(0.274 0.006 286.033);
-  --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.704 0.191 22.216);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.552 0.016 285.938);
-  --chart-1: oklch(0.488 0.243 264.376);
-  --chart-2: oklch(0.696 0.17 162.48);
-  --chart-3: oklch(0.769 0.188 70.08);
-  --chart-4: oklch(0.627 0.265 303.9);
-  --chart-5: oklch(0.645 0.246 16.439);
-  --sidebar: oklch(0.21 0.006 285.885);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.274 0.006 286.033);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(1 0 0 / 10%);
-  --sidebar-ring: oklch(0.552 0.016 285.938);
-}
-
-@layer base {
-  * {
-    @apply border-border outline-ring/50;
-  }
-  body {
-    @apply bg-background text-foreground;
-  }
-}
-
-```
-
-## app/layout.tsx
-
-```tsx
-import type { Metadata } from "next";
-import { MyRuntimeProvider } from "@/app/MyRuntimeProvider";
-
-import "./globals.css";
-
-export const metadata: Metadata = {
-  title: "Create Next App",
-  description: "Generated by create next app",
-};
-
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <MyRuntimeProvider>
-      <html lang="en" className="h-dvh">
-        <body className="h-dvh font-sans">{children}</body>
-      </html>
-    </MyRuntimeProvider>
-  );
-}
-
-```
-
-## app/MyRuntimeProvider.tsx
-
-```tsx
-"use client";
-
-import {
-  type ThreadMessageLike,
-  type AppendMessage,
-  AssistantRuntimeProvider,
-  useExternalStoreRuntime,
-} from "@assistant-ui/react";
-import { useState } from "react";
-
-const convertMessage = (message: ThreadMessageLike) => {
-  return message;
-};
-
-export function MyRuntimeProvider({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  const [messages, setMessages] = useState<readonly ThreadMessageLike[]>([
-    {
-      id: "msg-1",
-      createdAt: new Date("2024-01-01T10:00:00"),
-      role: "user",
-      content: [
-        {
-          type: "text",
-          text: "Tell me about climate change and its effects",
-        },
-      ],
-    },
-    {
-      id: "msg-2",
-      createdAt: new Date("2024-01-01T10:00:05"),
-      role: "assistant",
-      content: [
-        {
-          type: "text",
-          text: "Climate change refers to long-term shifts in global temperatures and weather patterns. Let me provide you with information about its causes and effects.",
-        },
-        {
-          type: "tool-call",
-          toolCallId: "call-1",
-          toolName: "search_research",
-          args: { query: "climate change causes" },
-          argsText: '{"query": "climate change causes"}',
-          result: {
-            sources: [
-              "https://climate.nasa.gov/causes/",
-              "https://www.ipcc.ch/report/ar6/wg1/",
-            ],
-          },
-          parentId: "research-climate-causes",
-        },
-        {
-          type: "source",
-          sourceType: "url",
-          id: "source-1",
-          url: "https://climate.nasa.gov/causes/",
-          title: "NASA: Climate Change Causes",
-          parentId: "research-climate-causes",
-        },
-        {
-          type: "source",
-          sourceType: "url",
-          id: "source-2",
-          url: "https://www.ipcc.ch/report/ar6/wg1/",
-          title: "IPCC Sixth Assessment Report",
-          parentId: "research-climate-causes",
-        },
-        {
-          type: "text",
-          text: "The main causes of climate change include:",
-          parentId: "research-climate-causes",
-        },
-        {
-          type: "text",
-          text: "1. **Greenhouse Gas Emissions**: The burning of fossil fuels releases CO2 and other greenhouse gases that trap heat in the atmosphere.",
-          parentId: "research-climate-causes",
-        },
-        {
-          type: "text",
-          text: "2. **Deforestation**: Removing forests reduces the Earth's capacity to absorb CO2.",
-          parentId: "research-climate-causes",
-        },
-        {
-          type: "text",
-          text: "Now, let me search for information about the effects of climate change:",
-        },
-        {
-          type: "tool-call",
-          toolCallId: "call-2",
-          toolName: "search_research",
-          args: { query: "climate change effects impacts" },
-          argsText: '{"query": "climate change effects impacts"}',
-          result: {
-            sources: [
-              "https://www.who.int/health-topics/climate-change",
-              "https://www.unep.org/facts-about-climate-emergency",
-            ],
-          },
-          parentId: "research-climate-effects",
-        },
-        {
-          type: "source",
-          sourceType: "url",
-          id: "source-3",
-          url: "https://www.who.int/health-topics/climate-change",
-          title: "WHO: Climate Change and Health",
-          parentId: "research-climate-effects",
-        },
-        {
-          type: "source",
-          sourceType: "url",
-          id: "source-4",
-          url: "https://www.unep.org/facts-about-climate-emergency",
-          title: "UNEP: Climate Emergency Facts",
-          parentId: "research-climate-effects",
-        },
-        {
-          type: "text",
-          text: "The major effects of climate change include:",
-          parentId: "research-climate-effects",
-        },
-        {
-          type: "text",
-          text: "• **Rising Sea Levels**: Melting ice caps and thermal expansion of oceans threaten coastal communities.",
-          parentId: "research-climate-effects",
-        },
-        {
-          type: "text",
-          text: "• **Extreme Weather Events**: More frequent and intense hurricanes, droughts, and heatwaves.",
-          parentId: "research-climate-effects",
-        },
-        {
-          type: "text",
-          text: "• **Ecosystem Disruption**: Changes in temperature and precipitation patterns affect biodiversity and agriculture.",
-          parentId: "research-climate-effects",
-        },
-        {
-          type: "text",
-          text: "In conclusion, climate change is one of the most pressing challenges facing humanity, requiring immediate action on both mitigation and adaptation strategies.",
-        },
-      ] as any, // Using any to bypass strict typing for demo purposes
-      status: { type: "complete", reason: "stop" },
-    },
-  ]);
-
-  const onNew = async (message: AppendMessage) => {
-    if (message.content.length !== 1 || message.content[0]?.type !== "text")
-      throw new Error("Only text content is supported");
-
-    const userMessage: ThreadMessageLike = {
-      id: `msg-user-${Date.now()}`,
-      createdAt: new Date(),
-      role: "user",
-      content: [{ type: "text", text: message.content[0].text }],
-    };
-    setMessages((currentMessages) => [...currentMessages, userMessage]);
-
-    // Simulate assistant response with parent IDs
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-
-    const assistantMessage: ThreadMessageLike = {
-      id: `msg-assistant-${Date.now()}`,
-      createdAt: new Date(),
-      role: "assistant",
-      content: [
-        {
-          type: "text",
-          text: "I understand you want to know more. Let me research that for you.",
-        },
-        {
-          type: "tool-call",
-          toolCallId: `call-${Date.now()}`,
-          toolName: "search",
-          args: { query: "recent developments" },
-          argsText: '{"query": "recent developments"}',
-          result: { data: "Latest information found" },
-          parentId: "new-research",
-        },
-        {
-          type: "text",
-          text: "Based on my research:",
-          parentId: "new-research",
-        },
-        {
-          type: "text",
-          text: "Here's what I found about your query...",
-          parentId: "new-research",
-        },
-        {
-          type: "text",
-          text: "I hope this information helps!",
-        },
-      ] as any, // Using any to bypass strict typing for demo purposes
-      status: { type: "complete", reason: "stop" },
-    };
-    setMessages((currentMessages) => [...currentMessages, assistantMessage]);
-  };
-
-  const runtime = useExternalStoreRuntime<ThreadMessageLike>({
-    messages,
-    setMessages,
-    onNew,
-    convertMessage,
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-
-```
-
-## app/page.tsx
-
-```tsx
-"use client";
-
-import { Thread } from "@/components/assistant-ui/thread";
-import { useAui, AuiProvider, Suggestions } from "@assistant-ui/react";
-
-function ThreadWithSuggestions() {
-  const aui = useAui({
-    suggestions: Suggestions([
-      {
-        title: "Tell me a story",
-        label: "with multiple parts",
-        prompt: "Tell me a short story with a beginning, middle, and end.",
-      },
-      {
-        title: "Explain quantum computing",
-        label: "in simple terms",
-        prompt: "Explain quantum computing like I'm five years old.",
-      },
-    ]),
-  });
-  return (
-    <AuiProvider value={aui}>
-      <Thread />
-    </AuiProvider>
-  );
-}
-
-export default function Home() {
-  return (
-    <main className="h-dvh">
-      <ThreadWithSuggestions />
-    </main>
-  );
-}
-
-```
-
-## components.json
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": true,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "app/globals.css",
-    "baseColor": "zinc",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "ui": "@/components/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  },
-  "iconLibrary": "lucide",
-  "registries": {
-    "@assistant-ui": "https://r.assistant-ui.com/{name}.json"
-  }
-}
-
-```
-
-## next.config.ts
-
-```typescript
-import type { NextConfig } from "next";
-
-const nextConfig: NextConfig = {
-  /* config options here */
-};
-
-export default nextConfig;
-
-```
-
-## package.json
-
-```json
-{
-  "name": "with-parent-id-grouping",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start"
-  },
-  "dependencies": {
-    "@ai-sdk/openai": "^3.0.64",
-    "@assistant-ui/react": "workspace:*",
-    "@assistant-ui/react-markdown": "workspace:*",
-    "@assistant-ui/ui": "workspace:*",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^1.16.0",
-    "next": "^16.2.6",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "tailwind-merge": "^3.6.0"
-  },
-  "devDependencies": {
-    "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4.3.0",
-    "@types/node": "^25.9.1",
-    "@types/react": "^19.2.15",
-    "@types/react-dom": "^19.2.3",
-    "postcss": "^8.5.15",
-    "tailwindcss": "^4.3.0",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^6.0.3"
-  }
-}
-
-```
-
-## README.md
-
-```markdown
-# Parent ID Grouping Example
-
-This example demonstrates how to use the parent ID feature in assistant-ui to group related message parts together.
-
-## Quick Start
-
-### Using CLI (Recommended)
-
-```bash
-npx assistant-ui@latest create my-app --example with-parent-id-grouping
-cd my-app
-```
-
-### Environment Variables
-
-Create `.env.local`:
-
-```
-OPENAI_API_KEY=sk-...
-```
-
-### Run
-
-```bash
-npm install
-npm run dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) to see the example.
-
-## Features
-
-- **Parent ID Support**: Message parts can have a `parentId` field that groups them together
-- **Visual Grouping**: Related parts are displayed in collapsible groups
-- **Custom Group Component**: Shows grouped parts in a bordered container with expand/collapse functionality
-
-## How it works
-
-1. **Message Structure**: The example uses the external store runtime with predefined messages that include parts with `parentId` fields:
-
-   ```typescript
-   {
-     type: "text",
-     text: "Some related text",
-     parentId: "research-climate-causes"
-   }
-   ```
-
-2. **Non-adjacent grouping component**: Uses the unstable `MessagePrimitive.Unstable_PartsGroupedByParentId` API to collect parts by `parentId`, even when related parts are not adjacent. For normal adjacent grouping, prefer `MessagePrimitive.GroupedParts`.
-
-3. **Custom Rendering**: The `ParentIdGroup` component provides collapsible sections for each group
-
-## Use Cases
-
-This pattern is useful for:
-
-- Grouping research sources with their related findings
-- Organizing multi-step tool executions
-- Creating hierarchical content structures
-- Showing related content in collapsible sections
-
-## Related Documentation
-
-- [assistant-ui Documentation](https://www.assistant-ui.com/docs)
-- [Message Structure Guide](https://www.assistant-ui.com/docs/concepts/messages)
-
-```
-
-## tsconfig.json
-
-```json
-{
-  "extends": "@assistant-ui/x-buildutils/ts/next",
-  "compilerOptions": {
-    "paths": {
-      "@/*": ["./*"],
-      "@/components/assistant-ui/*": [
-        "../../packages/ui/src/components/assistant-ui/*"
-      ],
-      "@/components/ui/*": ["../../packages/ui/src/components/ui/*"],
-      "@/lib/utils": ["../../packages/ui/src/lib/utils"],
-      "@assistant-ui/ui/*": ["../../packages/ui/src/*"]
-    }
-  },
-  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
-}
-
-```
-