Initial commit

2025-11-30 08:41:51 +08:00
commit 43ed648a28
43 changed files with 8444 additions and 0 deletions
--- a/docs/components/branch.md
+++ b/docs/components/branch.md
@@ -0,0 +1,146 @@
+# Branch
+
+URL: /components/branch
+
+---
+
+title: Branch
+description: Manages multiple versions of AI messages, allowing users to navigate between different response branches.
+path: elements/components/branch
+
+---
+
+The `Branch` component manages multiple versions of AI messages, allowing users to navigate between different response branches. It provides a clean, modern interface with customizable themes and keyboard-accessible navigation buttons.
+
+<Preview path="branch" />
+
+## Installation
+
+<ElementsInstaller path="branch" />
+
+## Usage
+
+```tsx
+import { Branch, BranchMessages, BranchNext, BranchPage, BranchPrevious, BranchSelector } from "@/components/ai-elements/branch";
+```
+
+```tsx
+<Branch defaultBranch={0}>
+    <BranchMessages>
+        <Message from="user">
+            <MessageContent>Hello</MessageContent>
+        </Message>
+        <Message from="user">
+            <MessageContent>Hi!</MessageContent>
+        </Message>
+    </BranchMessages>
+    <BranchSelector from="user">
+        <BranchPrevious />
+        <BranchPage />
+        <BranchNext />
+    </BranchSelector>
+</Branch>
+```
+
+## Usage with AI SDK
+
+<Callout>
+  Branching is an advanced use case that you can implement yourself to suit your
+  application's needs. While the AI SDK does not provide built-in support for
+  branching, you have full flexibility to design and manage multiple response
+  paths as required.
+</Callout>
+
+## Features
+
+-   Context-based state management for multiple message branches
+-   Navigation controls for moving between branches (previous/next)
+-   Uses CSS to prevent re-rendering of branches when switching
+-   Branch counter showing current position (e.g., "1 of 3")
+-   Automatic branch tracking and synchronization
+-   Callbacks for branch change and navigation using `onBranchChange`
+-   Support for custom branch change callbacks
+-   Responsive design with mobile-friendly controls
+-   Clean, modern styling with customizable themes
+-   Keyboard-accessible navigation buttons
+
+## Props
+
+### `<Branch />`
+
+<TypeTable
+type={{
+  defaultBranch: {
+    description: 'The index of the branch to show by default.',
+    type: 'number',
+    default: '0',
+  },
+  onBranchChange: {
+    description: 'Callback fired when the branch changes.',
+    type: '(branchIndex: number) => void',
+  },
+  '...props': {
+    description: 'Any other props are spread to the root div.',
+    type: 'React.HTMLAttributes<HTMLDivElement>',
+  },
+}}
+/>
+
+### `<BranchMessages />`
+
+<TypeTable
+type={{
+  '...props': {
+    description: 'Any other props are spread to the root div.',
+    type: 'React.HTMLAttributes<HTMLDivElement>',
+  },
+}}
+/>
+
+### `<BranchSelector />`
+
+<TypeTable
+type={{
+  from: {
+    description: 'Aligns the selector for user, assistant or system messages.',
+    type: 'UIMessage["role"]',
+  },
+  '...props': {
+    description: 'Any other props are spread to the selector container.',
+    type: 'React.HTMLAttributes<HTMLDivElement>',
+  },
+}}
+/>
+
+### `<BranchPrevious />`
+
+<TypeTable
+type={{
+  '...props': {
+    description: 'Any other props are spread to the underlying shadcn/ui Button component.',
+    type: 'React.ComponentProps<typeof Button>',
+  },
+}}
+/>
+
+### `<BranchNext />`
+
+<TypeTable
+type={{
+  '...props': {
+    description: 'Any other props are spread to the underlying shadcn/ui Button component.',
+    type: 'React.ComponentProps<typeof Button>',
+  },
+}}
+/>
+
+### `<BranchPage />`
+
+<TypeTable
+type={{
+  '...props': {
+    description: 'Any other props are spread to the underlying span element.',
+    type: 'React.HTMLAttributes<HTMLSpanElement>',
+  },
+}}
+/>