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

package/.docs/raw/docs/primitives/thread-list.mdx

@@ -1,467 +0,0 @@
----
-title: ThreadList
-description: Multi-thread management for listing, creating, switching, archiving, and deleting conversations.
-platforms: ["react"]
----
-
-import { ThreadListPrimitiveSample } from "@/components/pages/docs/samples/thread-list-primitive";
-import { ThreadListPrimitive as ThreadListPrimitiveDocs, ThreadListItemPrimitive as ThreadListItemPrimitiveDocs, ThreadListItemMorePrimitive as ThreadListItemMorePrimitiveDocs } from "@/generated/primitiveDocs";
-
-The ThreadList primitive manages multiple conversations by listing threads, creating new ones, switching between them, and archiving or deleting old ones. It's composed from three primitive namespaces: `ThreadListPrimitive`, `ThreadListItemPrimitive`, and `ThreadListItemMorePrimitive`.
-
-<Tabs items={["Preview", "Code"]}>
-  <Tab>
-    <ThreadListPrimitiveSample />
-  </Tab>
-  <Tab>
-```tsx
-import {
-  ThreadListPrimitive,
-  ThreadListItemPrimitive,
-  ThreadListItemMorePrimitive,
-} from "@assistant-ui/react";
-import { ArchiveIcon, MoreHorizontalIcon, PlusIcon, TrashIcon } from "lucide-react";
-
-function MyThreadList() {
-  return (
-    <ThreadListPrimitive.Root className="flex flex-col gap-1">
-      <ThreadListPrimitive.New className="flex h-9 items-center gap-2 rounded-lg border px-3 text-sm hover:bg-muted">
-        <PlusIcon className="size-4" />
-        New Thread
-      </ThreadListPrimitive.New>
-      <ThreadListPrimitive.Items>
-        {() => <ThreadListItem />}
-      </ThreadListPrimitive.Items>
-    </ThreadListPrimitive.Root>
-  );
-}
-
-function ThreadListItem() {
-  return (
-    <ThreadListItemPrimitive.Root className="group relative flex h-9 items-center rounded-lg hover:bg-muted data-active:bg-muted has-focus-visible:bg-muted">
-      <ThreadListItemPrimitive.Trigger className="min-w-0 flex-1 truncate px-3 text-sm outline-none">
-        <ThreadListItemPrimitive.Title fallback="New Chat" />
-      </ThreadListItemPrimitive.Trigger>
-      <ThreadListItemMorePrimitive.Root sharedFocusGroup>
-        <ThreadListItemMorePrimitive.Trigger className="absolute end-1.5 top-1/2 size-7 -translate-y-1/2 rounded-md opacity-0 group-hover:opacity-100 group-has-focus-visible:opacity-100 data-[state=open]:opacity-100">
-          <MoreHorizontalIcon className="size-4" />
-        </ThreadListItemMorePrimitive.Trigger>
-        <ThreadListItemMorePrimitive.Content className="rounded-md border bg-popover p-1 shadow-md">
-          <ThreadListItemPrimitive.Archive asChild>
-            <ThreadListItemMorePrimitive.Item className="flex items-center gap-2 rounded-sm px-2 py-1.5 text-sm hover:bg-accent">
-              <ArchiveIcon className="size-4" /> Archive
-            </ThreadListItemMorePrimitive.Item>
-          </ThreadListItemPrimitive.Archive>
-          <ThreadListItemPrimitive.Delete asChild>
-            <ThreadListItemMorePrimitive.Item className="flex items-center gap-2 rounded-sm px-2 py-1.5 text-sm text-destructive hover:bg-destructive/10">
-              <TrashIcon className="size-4" /> Delete
-            </ThreadListItemMorePrimitive.Item>
-          </ThreadListItemPrimitive.Delete>
-        </ThreadListItemMorePrimitive.Content>
-      </ThreadListItemMorePrimitive.Root>
-    </ThreadListItemPrimitive.Root>
-  );
-}
-```
-  </Tab>
-</Tabs>
-
-## Quick Start
-
-Minimal example:
-
-```tsx
-import {
-  ThreadListPrimitive,
-  ThreadListItemPrimitive,
-} from "@assistant-ui/react";
-
-<ThreadListPrimitive.Root>
-  <ThreadListPrimitive.New>New Thread</ThreadListPrimitive.New>
-  <ThreadListPrimitive.Items>
-    {() => (
-      <ThreadListItemPrimitive.Root>
-        <ThreadListItemPrimitive.Trigger>
-          <ThreadListItemPrimitive.Title fallback="New Chat" />
-        </ThreadListItemPrimitive.Trigger>
-      </ThreadListItemPrimitive.Root>
-    )}
-  </ThreadListPrimitive.Items>
-</ThreadListPrimitive.Root>
-```
-
-`Root` renders a `<div>`, `New` renders a `<button>` that creates a new thread, and `Items` iterates over the thread list. Each item is composed from `ThreadListItemPrimitive` parts.
-
-<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
-
-### Three Namespaces
-
-ThreadList is split across three namespaces to keep each level of abstraction composable:
-
-- **`ThreadListPrimitive`**: The outer container. `Root` wraps the list, `New` creates threads, and `Items` iterates over them.
-- **`ThreadListItemPrimitive`**: An individual thread row. `Root` provides context, `Trigger` switches to the thread, `Title` shows the thread name, and action buttons (Archive, Unarchive, Delete) manage the thread lifecycle.
-- **`ThreadListItemMorePrimitive`**: An overflow dropdown menu (built on Radix DropdownMenu) for thread actions. Compose action buttons with menu items using `asChild`.
-
-### Active State
-
-Both `ThreadListPrimitive.New` and `ThreadListItemPrimitive.Root` get a `data-active` attribute when they represent the current thread. Use this for styling:
-
-```tsx
-<ThreadListItemPrimitive.Root className="hover:bg-muted data-active:bg-muted">
-  {/* ... */}
-</ThreadListItemPrimitive.Root>
-```
-
-The `New` button gets `data-active` when the user is on a fresh, unsaved thread.
-
-### Keyboard Navigation
-
-Every item stays a native Tab stop, and arrow keys are layered on top. Up/Down move between items and Right focuses an item's `More` button (Left/Right are mirrored in RTL). This is built into the primitives — no prop is required.
-
-To fold the `More` menu into the same navigation, opt it in with `sharedFocusGroup`:
-
-```tsx
-<ThreadListItemMorePrimitive.Root sharedFocusGroup>
-  {/* Right opens the menu from the trigger; Left/Escape close it and
-      return focus to the trigger, keeping the highlight continuous. */}
-</ThreadListItemMorePrimitive.Root>
-```
-
-`sharedFocusGroup` joins the menu to the list's focus group, so its trigger and the open menu act as one keyboard-navigable unit: Right opens it and Left/Escape close it, synchronously restoring focus to the trigger so a `group-has-focus-visible` highlight never flickers. Enabling it forces the menu non-modal, because a focus trap and a shared focus group are mutually exclusive — the trap keeps focus inside the menu, the shared group lets it move out across the boundary. Without `sharedFocusGroup` the menu keeps its standard Radix `DropdownMenu` keyboard behavior (modal by default), so menus you already render are unchanged. Our assistant-ui [thread-list](/docs/ui/thread-list) registry component sets `sharedFocusGroup` for you.
-
-### Items Iterator
-
-`ThreadListPrimitive.Items` now prefers a children render function, similar to `ThreadPrimitive.Messages`:
-
-```tsx
-<ThreadListPrimitive.Items>
-  {({ threadListItem }) => (
-    <MyThreadItem threadId={threadListItem.id} />
-  )}
-</ThreadListPrimitive.Items>
-```
-
-`components` is deprecated. Use the `children` render function instead.
-
-### Archived Threads
-
-Pass `archived` to `Items` to render archived threads separately:
-
-```tsx
-<ThreadListPrimitive.Root>
-  <ThreadListPrimitive.New>New Thread</ThreadListPrimitive.New>
-  <ThreadListPrimitive.Items>
-    {() => <ThreadListItem />}
-  </ThreadListPrimitive.Items>
-
-  <h3>Archived</h3>
-  <ThreadListPrimitive.Items archived>
-    {() => <ArchivedThreadItem />}
-  </ThreadListPrimitive.Items>
-</ThreadListPrimitive.Root>
-```
-
-### Thread Actions
-
-`Archive`, `Unarchive`, and `Delete` buttons disable automatically when the runtime capability is unavailable.
-
-### Composing Actions with Menu Items
-
-The canonical pattern composes `ThreadListItemPrimitive.Archive asChild` with `ThreadListItemMorePrimitive.Item` to get both the action behavior AND the menu item styling:
-
-```tsx
-<ThreadListItemPrimitive.Archive asChild>
-  <ThreadListItemMorePrimitive.Item>
-    <ArchiveIcon className="size-4" /> Archive
-  </ThreadListItemMorePrimitive.Item>
-</ThreadListItemPrimitive.Archive>
-```
-
-`Archive` provides the click handler and disabled logic. `Item` provides the menu item behavior and styling. `asChild` merges them into a single element.
-
-## Accessibility
-
-The thread list leans on native button semantics and Radix's `DropdownMenu`; the arrow-key navigation is layered on top as a convenience, not a requirement.
-
-- Each `ThreadListItemPrimitive.Trigger` is a native `<button>` and its own Tab stop, so the whole list is reachable with <Kbd>Tab</Kbd> alone. The arrow keys (see [Keyboard Navigation](#keyboard-navigation)) speed traversal up, but nothing depends on them.
-- The item representing the current thread sets `aria-current="true"` (alongside `data-active`) on `ThreadListItemPrimitive.Root`, so assistive tech announces which conversation is open.
-- The `More` trigger exposes `aria-haspopup="menu"`, and its panel is a Radix `role="menu"` with `role="menuitem"` children, so screen readers announce it as a menu and the arrow keys cycle its items.
-- With `sharedFocusGroup`, the `More` menu is non-modal and joins the list's focus group: opening and closing it move focus synchronously between the trigger and the menu, so keyboard focus is never dropped and the `group-has-focus-visible` highlight never flickers. Without it, the menu keeps Radix's default modal focus trap.
-
-## Parts
-
-### ThreadListPrimitive
-
-#### Root
-
-Container for the full thread list. Renders a `<div>` element unless `asChild` is set.
-
-```tsx
-<ThreadListPrimitive.Root className="flex flex-col gap-1">
-  <ThreadListPrimitive.Items>
-    {() => <MyThreadItem />}
-  </ThreadListPrimitive.Items>
-</ThreadListPrimitive.Root>
-```
-
-#### New
-
-Button that creates a new thread. Renders a `<button>` element unless `asChild` is set.
-
-```tsx
-<ThreadListPrimitive.New className="rounded-lg border px-3 py-2 text-sm">
-  New Thread
-</ThreadListPrimitive.New>
-```
-
-#### Items
-
-Renders a component per thread.
-
-```tsx
-<ThreadListPrimitive.Items>
-  {() => <MyThreadItem />}
-</ThreadListPrimitive.Items>
-```
-
-<PrimitivesTypeTable type="ThreadListPrimitiveItemsProps" parameters={ThreadListPrimitiveDocs.Items.props} />
-
-#### ItemByIndex
-
-Renders a single thread at a specific index.
-
-```tsx
-<ThreadListPrimitive.ItemByIndex
-  index={0}
-  components={{ ThreadListItem: MyThreadItem }}
-/>
-```
-
-<PrimitivesTypeTable type="ThreadListPrimitiveItemByIndexProps" parameters={ThreadListPrimitiveDocs.ItemByIndex.props} />
-
-#### LoadMore
-
-Button that appends the next page of threads. Renders a `<button>` element unless `asChild` is set, and is automatically disabled when the runtime is loading or when the adapter's last `list()` did not return a `nextCursor`. See [Threads concepts](/docs/runtimes/concepts/threads#paginating-the-thread-list) for the adapter contract.
-
-```tsx
-<ThreadListPrimitive.LoadMore className="rounded-lg border px-3 py-2 text-sm">
-  Load more
-</ThreadListPrimitive.LoadMore>
-```
-
-For scroll-driven loading, wrap `aui.threads.loadMore()` in your own `IntersectionObserver` at the application layer; assistant-ui ships the explicit button to keep the primitive surface predictable.
-
-```tsx
-import { useAui, useAuiState } from "@assistant-ui/react";
-import { useEffect, useRef } from "react";
-
-function LoadMoreSentinel() {
-  const aui = useAui();
-  const disabled = useAuiState(
-    (s) =>
-      !s.threads.hasMore || s.threads.isLoading || s.threads.isLoadingMore,
-  );
-  const ref = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    const el = ref.current;
-    if (!el || disabled) return;
-    const observer = new IntersectionObserver(([entry]) => {
-      if (entry?.isIntersecting) aui.threads.loadMore();
-    });
-    observer.observe(el);
-    return () => observer.disconnect();
-  }, [aui, disabled]);
-
-  return disabled ? null : <div ref={ref} className="h-9" />;
-}
-```
-
-### ThreadListItemPrimitive
-
-#### Root
-
-Container for one thread list item. Renders a `<div>` element unless `asChild` is set.
-
-```tsx
-<ThreadListItemPrimitive.Root className="flex items-center gap-2 rounded-lg px-2 py-1.5">
-  <ThreadListItemPrimitive.Trigger className="flex-1 text-left">
-    <ThreadListItemPrimitive.Title fallback="New Chat" />
-  </ThreadListItemPrimitive.Trigger>
-</ThreadListItemPrimitive.Root>
-```
-
-#### Trigger
-
-Interactive button that selects the thread. Renders a `<button>` element unless `asChild` is set.
-
-```tsx
-<ThreadListItemPrimitive.Trigger className="flex-1 text-left">
-  <ThreadListItemPrimitive.Title fallback="New Chat" />
-</ThreadListItemPrimitive.Trigger>
-```
-
-#### Title
-
-Displays the thread title with a `fallback` prop. Renders a React fragment (no wrapper element). Use a `<span>` wrapper if you need to style it.
-
-```tsx
-<ThreadListItemPrimitive.Title fallback="New Chat" />
-```
-
-<PrimitivesTypeTable type="ThreadListItemPrimitiveTitleProps" parameters={ThreadListItemPrimitiveDocs.Title.props} />
-
-#### Archive
-
-Button that archives the current thread item. Renders a `<button>` element unless `asChild` is set.
-
-```tsx
-<ThreadListItemPrimitive.Archive>Archive</ThreadListItemPrimitive.Archive>
-```
-
-#### Unarchive
-
-Button that restores the current thread item from the archive. Renders a `<button>` element unless `asChild` is set.
-
-```tsx
-<ThreadListItemPrimitive.Unarchive>Unarchive</ThreadListItemPrimitive.Unarchive>
-```
-
-#### Delete
-
-Button that deletes the current thread item. Renders a `<button>` element unless `asChild` is set.
-
-```tsx
-<ThreadListItemPrimitive.Delete>Delete</ThreadListItemPrimitive.Delete>
-```
-
-### ThreadListItemMorePrimitive
-
-#### Root
-
-Root container for the overflow menu primitives. Pass `sharedFocusGroup` to fold the menu into the list's arrow-key navigation (see [Keyboard Navigation](#keyboard-navigation)); doing so forces it non-modal. Without it the menu honors the `modal` prop, defaulting to modal like Radix's `DropdownMenu`.
-
-```tsx
-<ThreadListItemMorePrimitive.Root sharedFocusGroup>
-  <ThreadListItemMorePrimitive.Trigger>More</ThreadListItemMorePrimitive.Trigger>
-</ThreadListItemMorePrimitive.Root>
-```
-
-#### Trigger
-
-Button that opens the overflow menu. Renders a `<button>` element unless `asChild` is set.
-
-```tsx
-<ThreadListItemMorePrimitive.Trigger className="rounded-md p-1 hover:bg-muted">
-  More
-</ThreadListItemMorePrimitive.Trigger>
-```
-
-#### Content
-
-The dropdown panel. Renders a `<div>` via a portal (positioned relative to the trigger).
-
-```tsx
-<ThreadListItemMorePrimitive.Content className="rounded-md border bg-popover p-1 shadow-md">
-  <ThreadListItemPrimitive.Archive asChild>
-    <ThreadListItemMorePrimitive.Item>Archive</ThreadListItemMorePrimitive.Item>
-  </ThreadListItemPrimitive.Archive>
-</ThreadListItemMorePrimitive.Content>
-```
-
-<PrimitivesTypeTable type="ThreadListItemMorePrimitiveContentProps" parameters={ThreadListItemMorePrimitiveDocs.Content.props} />
-
-#### Item
-
-Menu item slot inside the overflow menu. Renders a `<div>` element unless `asChild` is set.
-
-```tsx
-<ThreadListItemMorePrimitive.Item>Archive</ThreadListItemMorePrimitive.Item>
-```
-
-#### Separator
-
-Visual separator between groups of menu items. Renders a `<div>` element unless `asChild` is set.
-
-```tsx
-<ThreadListItemMorePrimitive.Separator className="my-1 h-px bg-border" />
-```
-
-## Patterns
-
-### Basic Thread List with New Button
-
-```tsx
-<ThreadListPrimitive.Root className="flex flex-col gap-1">
-  <ThreadListPrimitive.New className="flex items-center gap-2 rounded-lg border px-3 py-2 text-sm">
-    <PlusIcon className="size-4" /> New Thread
-  </ThreadListPrimitive.New>
-  <ThreadListPrimitive.Items>
-    {() => <ThreadListItem />}
-  </ThreadListPrimitive.Items>
-</ThreadListPrimitive.Root>
-```
-
-### Thread Item with More Menu
-
-```tsx
-function ThreadListItem() {
-  return (
-    <ThreadListItemPrimitive.Root className="group flex items-center rounded-lg hover:bg-muted data-active:bg-muted">
-      <ThreadListItemPrimitive.Trigger className="flex-1 truncate px-3 py-2 text-sm">
-        <ThreadListItemPrimitive.Title fallback="New Chat" />
-      </ThreadListItemPrimitive.Trigger>
-      <ThreadListItemMorePrimitive.Root>
-        <ThreadListItemMorePrimitive.Trigger className="opacity-0 group-hover:opacity-100">
-          <MoreHorizontalIcon className="size-4" />
-        </ThreadListItemMorePrimitive.Trigger>
-        <ThreadListItemMorePrimitive.Content>
-          <ThreadListItemPrimitive.Archive asChild>
-            <ThreadListItemMorePrimitive.Item>Archive</ThreadListItemMorePrimitive.Item>
-          </ThreadListItemPrimitive.Archive>
-          <ThreadListItemMorePrimitive.Separator />
-          <ThreadListItemPrimitive.Delete asChild>
-            <ThreadListItemMorePrimitive.Item>Delete</ThreadListItemMorePrimitive.Item>
-          </ThreadListItemPrimitive.Delete>
-        </ThreadListItemMorePrimitive.Content>
-      </ThreadListItemMorePrimitive.Root>
-    </ThreadListItemPrimitive.Root>
-  );
-}
-```
-
-### Archived Threads Section
-
-```tsx
-<ThreadListPrimitive.Root>
-  <ThreadListPrimitive.New>New Thread</ThreadListPrimitive.New>
-
-  <h3 className="px-3 pt-4 text-xs font-medium text-muted-foreground">Recent</h3>
-  <ThreadListPrimitive.Items>
-    {() => <ThreadListItem />}
-  </ThreadListPrimitive.Items>
-
-  <h3 className="px-3 pt-4 text-xs font-medium text-muted-foreground">Archived</h3>
-  <ThreadListPrimitive.Items archived>
-    {() => <ArchivedItem />}
-  </ThreadListPrimitive.Items>
-</ThreadListPrimitive.Root>
-```
-
-In the `ArchivedItem` component, use `ThreadListItemPrimitive.Unarchive` instead of `Archive` to let users restore threads.
-
-## Relationship to Components
-
-The shadcn [ThreadList](/docs/ui/thread-list) component wraps these primitives with Tailwind styling in a sidebar layout, including a skeleton loading state and a prebuilt more menu with archive and delete actions. Start there for a default thread list implementation. Reach for the primitives directly when you need a custom layout, different actions, or integration with your own sidebar or navigation system.
-
-## API Reference
-
-For full prop details on every part, see the API reference for each namespace:
-
-- [ThreadListPrimitive](/docs/api-reference/primitives/thread-list)
-- [ThreadListItemPrimitive](/docs/api-reference/primitives/thread-list-item)
-- [ThreadListItemMorePrimitive](/docs/api-reference/primitives/thread-list-item-more)