# Modra 接入指南（面向 AI 编码助手）

本文件是给 AI 助手读取的权威接入规则。生成 Modra 相关代码前请先通读；组件 API 以 `/ai/components/<slug>.md` 为准，不要凭记忆猜测 props。

## 0. AI 接入流程（只知道站点地址时从这里开始）

站点地址：`https://modra.feinian.net`。按顺序执行，每步完成后再进入下一步：

1. **识别项目类型**：读 `package.json`。有 `react` → React / Next.js 路线；没有 React（Django、Rails、Blade、纯静态页）→ HTML 路线（`@modra/website`），**不要**引入 React。
2. **检查 registry 认证**（见第 2 节）：运行 `npm view @modra/react@dev --registry https://npm.feinian.net/`。失败（401/403/ENOTFOUND）→ **停止并告知用户**需要 `NPM_TOKEN`，不要自行尝试获取或把 token 写入仓库。
3. **安装包与 peer**（第 2 节）。
4. **配置样式入口**（第 3 节）：Tailwind v4 + `@modra/tailwind-preset` + `@source`。
5. **写入 AI 约定文件**：把 `https://modra.feinian.net/AGENTS.md` 的内容写入项目根的 `AGENTS.md`（Claude Code 用 `CLAUDE.md`，Cursor 用 `.cursor/rules/modra.mdc`），已存在则追加，不覆盖。
6. **写代码前查 API**：读 `https://modra.feinian.net/ai/components/<slug>.md`，不要凭记忆写 props。
7. **验证**：运行项目的类型检查与构建；渲染一个 `Button` 确认样式生效（见第 7 节常见错误）。

可选：连接 MCP 服务器，让 AI 直接按需查询文档，免于逐个抓取文件。见第 9 节。

## 1. 选包

| 场景                                        | 使用                                                                                                            |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| React / Next.js 应用                        | `@modra/react` + `@modra/tailwind-preset` + `@modra/tokens`                                                     |
| 纯 HTML / 后端模板（Django、Rails、Blade…） | `@modra/tokens` CSS 变量，或 Tailwind 语义类，或 `@modra/website` 配方（`modra-` 前缀类名）。**不要**引入 React |
| 图标（可选）                                | `@feinian/fontawesome-pro-react`（需授权）或 `@feinian/fontawesome-free-react`，两者 API 一致                   |

## 2. 安装

```bash
pnpm add @modra/tokens@dev @modra/tailwind-preset@dev @modra/react@dev --registry https://npm.feinian.net/
```

- 包来自内网 registry `https://npm.feinian.net/`，发布在 `dev` 通道（所以带 `@dev`）。
- **认证**：token 通过环境变量 `NPM_TOKEN` 提供，在**用户级** `~/.npmrc`（不是项目内文件）写入：

  ```ini
  //npm.feinian.net/:_authToken=${NPM_TOKEN}
  ```

  - `NPM_TOKEN` 由团队的 registry 管理员发放；AI 无法也不应自行获取。
  - 安装前检查：`echo "${NPM_TOKEN:+set}"` 输出 `set` 才算已配置。**未配置时停止并请用户设置**，不要把 token 写入项目的 `.npmrc`、`package.json`、CI 配置或任何会提交的文件。
  - 在 CI / Docker 构建中通过构建密钥或环境变量注入，不要 `COPY` 含 token 的 `.npmrc` 进镜像。
  - 验证：`npm view @modra/react@dev version --registry https://npm.feinian.net/` 能输出版本号。
  - 只使用 `--registry` 参数或用户级 `.npmrc` 指向该 registry；不要修改全局默认 registry。

- 只在确实用到对应组件时才安装可选 peer（与组件同一个应用内安装）：

| 组件                               | peer 依赖                     |
| ---------------------------------- | ----------------------------- |
| `DataTable`                        | `@tanstack/react-table`       |
| `Calendar` / 日期类选择器          | `react-day-picker` `date-fns` |
| `Command`                          | `cmdk`                        |
| `Form`                             | `react-hook-form`             |
| `InputOTP`                         | `input-otp`                   |
| `Resizable`                        | `react-resizable-panels`      |
| 虚拟化 `Tree` / `VirtualDataTable` | `@tanstack/react-virtual`     |

`Button` 等核心控件不需要任何额外 peer。

## 3. 样式入口（必须）

```css
/* app.css */
@import "tailwindcss";
@import "@modra/tailwind-preset";
/* 让 Tailwind 扫描组件库用到的工具类 */
@source "../node_modules/@modra/react/dist/**/*.{js,mjs}";
```

要求 Tailwind v4。缺少 `@source` 会导致组件样式丢失。

## 4. 使用组件

```tsx
import { Button } from "@modra/react";

export default function Page() {
  return <Button variant="primary">开始使用</Button>;
}
```

- 所有组件从包根 `@modra/react` 导入，不要深层导入内部路径。
- 复合组件按子组件组合（如 `Dialog` / `DialogContent` / `DialogHeader` / `DialogTitle`），导出清单见各组件的 md。
- 全局应用外层使用 `ConfigProvider`（默认 `zhCN`）；需要同步 `<html lang>` 时传 `syncDocumentLang`。
- 通知使用 `Toaster` + `toast()`，确认框使用 `confirm()` + `ConfirmDialogHost`。

## 5. 样式与主题规则

- 使用**语义类**：`bg-primary`、`text-primary-foreground`、`text-muted-foreground`、`bg-background`、`rounded-md` 等。**不要**硬编码颜色、也不要用 `dark:` 去手写颜色分支——暗色由语义变量自动切换。
- 优先使用逻辑属性类（`ps-*`/`pe-*`/`ms-*`/`me-*`/`start-*`/`end-*`），以便 RTL；不要用 `pl-*`/`pr-*`/`left-*`/`right-*` 表达方向性间距。
- 暗色模式：给 `<html>` 切换 `.dark`。品牌：`<html data-brand="ocean|forest|ids">`（`ids` 仅浅色）。密度：`data-density="compact"`。
- 运行时自定义主题使用 `ThemeProvider theme={{ color: { primary: "..." } }}`，不要手写覆盖 CSS 变量。
- 修改视觉应通过令牌（`@modra/tokens`）而不是改组件内部类名。

## 6. 选型速查（同类组件怎么选）

| 需求   | 选择                                                                                                                |
| ------ | ------------------------------------------------------------------------------------------------------------------- |
| 选择器 | `select`（少量）→ `combobox`（可搜索）→ `command`（命令面板）→ `tree-select` / `cascader` / `transfer`（层级/穿梭） |
| 覆盖层 | `dialog`（通用）、`alert-dialog` / `popconfirm`（确认）、`sheet`（侧滑）                                            |
| 表格   | `table`（静态）、`data-table`（排序/筛选/分页）、`virtual-data-table`（海量数据）                                   |
| 反馈   | `alert`（页内）、`toast`（瞬时）、`empty`（空态）、`result`（结果页）                                               |

完整的决策指引见 `/llms-full.txt`。

## 7. 常见错误

1. 忘记 `@import "@modra/tailwind-preset"` 或 `@source` → 无样式。
2. 使用了 `DataTable`/`Form` 等但未安装对应 peer → 运行时找不到模块。
3. 编造不存在的 prop 或组件名 → 以 `/ai/components/<slug>.md` 的 props 与导出为准。
4. 在非 React 页面使用 `@modra/react` → 应改用 `@modra/website` 或令牌 CSS。
5. 浏览器最低要求：Chrome/Edge 111、Firefox 128、Safari 16.4。

## 8. 延伸

- 组件站：`/components`、`/usage`、`/tokens`、`/website`
- 非 SPA 接入：`/website`
- 仓库文档：`docs/components.md`、`docs/website.md`、`docs/tokens.md`

## 9. MCP 服务器（可选，推荐）

远程 MCP（Streamable HTTP，无状态、只读、无需认证）：`https://modra.feinian.net/mcp`。

```bash
# Claude Code
claude mcp add --transport http modra https://modra.feinian.net/mcp
```

```jsonc
// Cursor：.cursor/mcp.json   |   VS Code：.vscode/mcp.json（顶层键为 "servers"）
{ "mcpServers": { "modra": { "url": "https://modra.feinian.net/mcp" } } }
```

工具：

| 工具                    | 用途                                                   |
| ----------------------- | ------------------------------------------------------ |
| `get_integration_guide` | 返回本指南；可传 `scenario`：`react` / `next` / `html` |
| `get_agents_md`         | 返回已填好站点地址的 AGENTS.md，写入使用方项目         |
| `list_components`       | 列出全部组件（可按分组过滤）                           |
| `get_component`         | 返回单个组件的导出与 props（参数 `slug`）              |
| `search_components`     | 按关键词搜索组件                                       |
| `get_design_tokens`     | 返回语义令牌清单与主题/品牌/密度切换方式               |

服务器描述文件：`/.well-known/mcp/server-card.json`。MCP 不可用时，退回读取 `/llms.txt` 与 `/ai/components/<slug>.md`，内容相同。


---

# 选型指引

- 选择器怎么选：select / combobox / command / tree-select / cascader / transfer
- 覆盖层怎么选：dialog / alert-dialog / popconfirm / sheet
- 表格怎么选：table / data-table / virtual-data-table
- 日期时间怎么选：calendar / date-picker / date-range-picker / date-time-picker / time-picker / date-time-display
- 反馈状态怎么选：alert / toast / empty / result
- Badge 和 Tag 怎么选：badge / tag

---

# alert

- 分组：核心组件（Core）
- 页面：/components/alert
- 源码：packages/react/src/components/alert.tsx

## 导出

```ts
import { Alert, AlertDescription, AlertTitle, alertVariants } from "@modra/react";
```

## Props

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `variant` | 否 | `"default" \| "destructive" \| "success" \| "warning" \| "info"` |  |

---

# avatar

- 分组：核心组件（Core）
- 页面：/components/avatar
- 源码：packages/react/src/components/avatar.tsx

## 导出

```ts
import { Avatar, AvatarFallback, AvatarImage } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# badge

- 分组：核心组件（Core）
- 页面：/components/badge
- 源码：packages/react/src/components/badge.tsx

## 导出

```ts
import { Badge, badgeVariants } from "@modra/react";
```

## Props（BadgeProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `variant` | 否 | `"default" \| "secondary" \| "destructive" \| "success" \| "warning" \| "info" \| "outline"` |  |

---

# breadcrumb

- 分组：核心组件（Core）
- 页面：/components/breadcrumb
- 源码：packages/react/src/components/breadcrumb.tsx

## 导出

```ts
import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# button

- 分组：核心组件（Core）
- 页面：/components/button
- 源码：packages/react/src/components/button.tsx

## 导出

```ts
import { Button, buttonVariants } from "@modra/react";
```

## Props（ButtonProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `asChild` | 否 | `boolean` | 以子元素作为渲染根（用于包裹链接等）。 |
| `loading` | 否 | `boolean` | 加载态：强制禁用并显示旋转图标，避免重复提交。 |
| `variant` | 否 | `"default" \| "secondary" \| "destructive" \| "outline" \| "ghost" \| "link"` |  |
| `size` | 否 | `"sm" \| "md" \| "lg" \| "icon"` |  |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |
| `disabled` | 否 | `boolean` |  |

---

# card

- 分组：核心组件（Core）
- 页面：/components/card
- 源码：packages/react/src/components/card.tsx

## 导出

```ts
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cardVariants } from "@modra/react";
```

## Props（CardProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `variant` | 否 | `"default" \| "elevated"` |  |

---

# checkbox

- 分组：核心组件（Core）
- 页面：/components/checkbox
- 源码：packages/react/src/components/checkbox.tsx

## 导出

```ts
import { Checkbox } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# dialog

- 分组：核心组件（Core）
- 页面：/components/dialog
- 源码：packages/react/src/components/dialog.tsx

## 导出

```ts
import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# dropdown-menu

- 分组：核心组件（Core）
- 页面：/components/dropdown-menu
- 源码：packages/react/src/components/dropdown-menu.tsx

## 导出

```ts
import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger } from "@modra/react";
```

## Props（DropdownMenuItemProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `inset` | 否 | `boolean` | Indents the label to line up with checkbox and radio items. |
| `variant` | 否 | `MenuItemVariant` | `destructive` colours the item (and its icon) with the destructive tokens. |

---

# empty

- 分组：核心组件（Core）
- 页面：/components/empty
- 源码：packages/react/src/components/empty.tsx

## 导出

```ts
import { Empty } from "@modra/react";
```

## Props（EmptyProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `image` | 否 | `React.ReactNode` |  |
| `description` | 否 | `React.ReactNode` |  |

---

# form

- 分组：核心组件（Core）
- 页面：/components/form
- 源码：packages/react/src/components/form.tsx

## 导出

```ts
import { Form, FormControl, FormDescription, FormError, FormField, FormItem, FormLabel, FormList, FormMessage, useFormField } from "@modra/react";
```

## Props（FormProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `children` | 否 | `React.ReactNode` |  |
| `layout` | 否 | `FormLayout` |  |
| `labelWidth` | 否 | `string \| number` |  |
| `labelAlign` | 否 | `FormLabelAlign` |  |
| `disabled` | 否 | `boolean` |  |
| `scrollToFirstError` | 否 | `boolean \| FormScrollToFirstErrorOptions` |  |
| `validateMessages` | 否 | `FormValidateMessages` | Templates apply only when RHF/resolver errors have no explicit message. |

---

# input

- 分组：核心组件（Core）
- 页面：/components/input
- 源码：packages/react/src/components/input.tsx

## 导出

```ts
import { Input } from "@modra/react";
```

## Props（InputProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `size` | 否 | `ControlSize` | Control height; defaults to `md`. |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |
| `disabled` | 否 | `boolean` |  |

---

# label

- 分组：核心组件（Core）
- 页面：/components/label
- 源码：packages/react/src/components/label.tsx

## 导出

```ts
import { Label } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# pagination

- 分组：核心组件（Core）
- 页面：/components/pagination
- 源码：packages/react/src/components/pagination.tsx

## 导出

```ts
import { Pagination } from "@modra/react";
```

## Props（PaginationProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `page` | 否 | `number` |  |
| `defaultPage` | 否 | `number` |  |
| `onPageChange` | 否 | `(page: number) => void` |  |
| `pageSize` | 否 | `number` |  |
| `defaultPageSize` | 否 | `number` |  |
| `onPageSizeChange` | 否 | `(pageSize: number) => void` |  |
| `total` | 是 | `number` |  |
| `pageSizeOptions` | 否 | `number[]` |  |
| `disabled` | 否 | `boolean` |  |
| `showSizeChanger` | 否 | `boolean` |  |
| `showQuickJumper` | 否 | `boolean` |  |
| `showTotal` | 否 | `boolean` |  |
| `hideOnSinglePage` | 否 | `boolean` |  |

---

# popover

- 分组：核心组件（Core）
- 页面：/components/popover
- 源码：packages/react/src/components/popover.tsx

## 导出

```ts
import { Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# progress

- 分组：核心组件（Core）
- 页面：/components/progress
- 源码：packages/react/src/components/progress.tsx

## 导出

```ts
import { Progress } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# radio-group

- 分组：核心组件（Core）
- 页面：/components/radio-group
- 源码：packages/react/src/components/radio-group.tsx

## 导出

```ts
import { RadioGroup, RadioGroupItem } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# select

- 分组：核心组件（Core）
- 页面：/components/select
- 源码：packages/react/src/components/select.tsx

## 导出

```ts
import { Select, SelectClearButton, SelectContent, SelectEmpty, SelectGroup, SelectItem, SelectLabel, SelectLoading, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue } from "@modra/react";
```

## Props（SelectClearButtonProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `onClear` | 是 | `() => void` |  |
| `disabled` | 否 | `boolean` |  |

---

# separator

- 分组：核心组件（Core）
- 页面：/components/separator
- 源码：packages/react/src/components/separator.tsx

## 导出

```ts
import { Separator } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# sheet

- 分组：核心组件（Core）
- 页面：/components/sheet
- 源码：packages/react/src/components/sheet.tsx

## 导出

```ts
import { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# skeleton

- 分组：核心组件（Core）
- 页面：/components/skeleton
- 源码：packages/react/src/components/skeleton.tsx

## 导出

```ts
import { Skeleton } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# switch

- 分组：核心组件（Core）
- 页面：/components/switch
- 源码：packages/react/src/components/switch.tsx

## 导出

```ts
import { Switch } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# table

- 分组：核心组件（Core）
- 页面：/components/table
- 源码：packages/react/src/components/table.tsx

## 导出

```ts
import { Table, TableBody, TableCaption, TableCell, TableCellStack, TableFooter, TableHead, TableHeader, TableRow } from "@modra/react";
```

## Props（TableProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `scrollHint` | 否 | `boolean` | Shows an edge shadow on the side(s) that have more content to scroll to, and hides it once the edge is reached. On by default; the shadow follows the writing direction. |
| `containerClassName` | 否 | `string` | Internal wrapper class for consumers that provide their own scrollport. |
| `wrapperClassName` | 否 | `string` | Class for the outer positioning wrapper around the scrollport and its scroll hints. |
| `containerStyle` | 否 | `React.CSSProperties` |  |
| `scrollRegionLabel` | 否 | `string` | Accessible name for the keyboard-scrollable table region. |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |

---

# tabbar

- 分组：核心组件（Core）
- 页面：/components/tabbar
- 源码：packages/react/src/components/tabbar.tsx

## 导出

```ts
import { Tabbar } from "@modra/react";
```

## Props（TabbarProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `items` | 是 | `TabbarItem[]` |  |
| `value` | 是 | `string` |  |
| `onChange` | 否 | `(key: string) => void` |  |
| `renderItem` | 否 | `(item: TabbarItem, state: { active: boolean }) => React.ReactNode` | Render an item with a custom link component (e.g. a router Link). |
| `aria-label` | 否 | `string` |  |

---

# tabs

- 分组：核心组件（Core）
- 页面：/components/tabs
- 源码：packages/react/src/components/tabs.tsx

## 导出

```ts
import { Tabs, TabsCloseButton, TabsContent, TabsList, TabsTrigger } from "@modra/react";
```

## Props（TabsProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `variant` | 否 | `TabsVariant` | `pill` (default) is the segmented control look. `line` is the admin look: a 1px bottom border on the list and a 2px primary underline on the active tab. |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |
| `disabled` | 否 | `boolean` |  |

---

# textarea

- 分组：核心组件（Core）
- 页面：/components/textarea
- 源码：packages/react/src/components/textarea.tsx

## 导出

```ts
import { Textarea } from "@modra/react";
```

## Props（TextareaProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |

---

# tooltip

- 分组：核心组件（Core）
- 页面：/components/tooltip
- 源码：packages/react/src/components/tooltip.tsx

## 导出

```ts
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# layout

- 分组：核心组件（Core）
- 页面：/components/layout
- 源码：packages/react/src/components/layout.tsx

## 导出

```ts
import { AuthLayout, Col, Flex, LAYOUT_BREAKPOINTS, Layout, LayoutContent, LayoutFooter, LayoutHeader, LayoutSider, Row, SiderThemeProvider, Space, useBreakpoint, useSiderCollapsed, useSiderTheme } from "@modra/react";
```

## Props（LayoutSiderProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `breakpoint` | 否 | `Breakpoint` |  |
| `collapsed` | 否 | `boolean` |  |
| `collapsedWidth` | 否 | `number \| string` | Width when collapsed. Defaults to the `--component-layout-sider-collapsed-width` token (80px; 56px in the admin density). |
| `collapsible` | 否 | `boolean` |  |
| `defaultCollapsed` | 否 | `boolean` |  |
| `onBreakpoint` | 否 | `(broken: boolean) => void` |  |
| `onCollapse` | 否 | `(collapsed: boolean, type: SiderCollapseType) => void` |  |
| `reverseArrow` | 否 | `boolean` |  |
| `trigger` | 否 | `React.ReactNode` |  |
| `width` | 否 | `number \| string` | Expanded width. Defaults to the `--component-layout-sider-width` token (256px; 224px in the admin density). |
| `zeroWidthTriggerStyle` | 否 | `React.CSSProperties` |  |
| `theme` | 否 | `"light" \| "dark"` |  |

---

# accordion

- 分组：组合组件（Composite）
- 页面：/components/accordion
- 源码：packages/react/src/components/accordion.tsx

## 导出

```ts
import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# calendar

- 分组：组合组件（Composite）
- 页面：/components/calendar
- 源码：packages/react/src/components/calendar.tsx

## 导出

```ts
import { Calendar } from "@modra/react";
```

## Props（CalendarProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `mode` | 否 | `"single" \| "range"` |  |
| `selected` | 否 | `Date \| DateRange` |  |
| `onSelect` | 否 | `(value: Date \| DateRange \| undefined) => void` |  |
| `disabled` | 否 | `Matcher \| Matcher[]` |  |
| `className` | 否 | `string` |  |

---

# cascader

- 分组：组合组件（Composite）
- 页面：/components/cascader
- 源码：packages/react/src/components/cascader.tsx

## 导出

```ts
import { Cascader } from "@modra/react";
```

## Props（CascaderProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `options` | 是 | `TreeNode[]` |  |
| `value` | 否 | `string[]` |  |
| `defaultValue` | 否 | `string[]` |  |
| `onValueChange` | 否 | `(value: string[]) => void` |  |
| `loadData` | 否 | `(path: TreeNode[]) => Promise<TreeNode[] \| void> \| TreeNode[] \| void` | Load children for a non-leaf node before entering its child level. |
| `changeOnSelect` | 否 | `boolean` | Emit the selected path even when the selected node has children. |
| `placeholder` | 否 | `string` |  |
| `disabled` | 否 | `boolean` |  |
| `className` | 否 | `string` |  |
| `data-form-control` | 否 | `boolean \| string` | Internal marker applied by FormControl for status styling. |

---

# collapsible

- 分组：组合组件（Composite）
- 页面：/components/collapsible
- 源码：packages/react/src/components/collapsible.tsx

## 导出

```ts
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# combobox

- 分组：组合组件（Composite）
- 页面：/components/combobox
- 源码：packages/react/src/components/combobox.tsx

## 导出

```ts
import { Combobox, useAsyncOptions } from "@modra/react";
```

## Props（ComboboxProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `options` | 是 | `ComboboxOption[]` |  |
| `value` | 否 | `string` |  |
| `defaultValue` | 否 | `string` |  |
| `onValueChange` | 否 | `(value: string) => void` |  |
| `open` | 否 | `boolean` |  |
| `defaultOpen` | 否 | `boolean` |  |
| `onOpenChange` | 否 | `(open: boolean) => void` |  |
| `onSearchChange` | 否 | `(search: string) => void` | Called with the search text. The input itself updates immediately; this callback is debounced by `searchDebounce` and is not fired while an IME composition is in progress. |
| `searchDebounce` | 否 | `number` | Milliseconds to wait before `onSearchChange`. Defaults to 300 when `filter` is `false`, else 0. |
| `filter` | 否 | `boolean \| ComboboxFilter` | `true` (default) filters locally, `false` shows `options` as-is (remote search), or pass a custom filter function. |
| `loading` | 否 | `boolean` | Keeps the previous options on screen and shows an inline indicator while true. |
| `selectedOption` | 否 | `ComboboxOption` | Option shown on the trigger when the selected value is not in the current `options`. |
| `disabled` | 否 | `boolean` |  |
| `placeholder` | 否 | `string` |  |
| `searchPlaceholder` | 否 | `string` |  |
| `emptyText` | 否 | `string` |  |
| `className` | 否 | `string` |  |
| `contentClassName` | 否 | `string` |  |
| `id` | 否 | `string` | Id of the trigger button, so an external `<label htmlFor>` can name it. |
| `invalid` | 否 | `boolean` | Marks the trigger invalid (`aria-invalid`) and applies the destructive border. |
| `onClear` | 否 | `() => void` | When provided, a clear button is shown while a value is selected. It calls this instead of `onValueChange`, so the parent decides what "no selection" means. |
| `error` | 否 | `React.ReactNode` | A load failure to show in the list. Pair with `onRetry`. |
| `onRetry` | 否 | `() => void` | Shows a retry button next to `error`. |

---

# command

- 分组：组合组件（Composite）
- 页面：/components/command
- 源码：packages/react/src/components/command.tsx

## 导出

```ts
import { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# context-menu

- 分组：组合组件（Composite）
- 页面：/components/context-menu
- 源码：packages/react/src/components/context-menu.tsx

## 导出

```ts
import { ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger } from "@modra/react";
```

## Props（ContextMenuItemProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `inset` | 否 | `boolean` | Indents the label to line up with checkbox and radio items. |
| `variant` | 否 | `MenuItemVariant` | `destructive` colours the item (and its icon) with the destructive tokens. |

---

# data-table

- 分组：组合组件（Composite）
- 页面：/components/data-table
- 源码：packages/react/src/components/data-table.tsx

## 导出

```ts
import { DataTable } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# date-picker

- 分组：组合组件（Composite）
- 页面：/components/date-picker
- 源码：packages/react/src/components/date-picker.tsx

## 导出

```ts
import { DatePicker } from "@modra/react";
```

## Props（DatePickerProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `Date` |  |
| `defaultValue` | 否 | `Date` |  |
| `onValueChange` | 否 | `(value: Date \| undefined) => void` |  |
| `disabled` | 否 | `boolean \| Matcher \| Matcher[]` |  |
| `placeholder` | 否 | `string` |  |
| `locale` | 否 | `Locale` |  |
| `format` | 否 | `string` |  |
| `className` | 否 | `string` |  |
| `calendarClassName` | 否 | `string` |  |

---

# date-range-picker

- 分组：组合组件（Composite）
- 页面：/components/date-range-picker
- 源码：packages/react/src/components/date-range-picker.tsx

## 导出

```ts
import { DateRangePicker } from "@modra/react";
```

## Props（DateRangePickerProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `DateRange` |  |
| `defaultValue` | 否 | `DateRange` |  |
| `onValueChange` | 否 | `(value: DateRange \| undefined) => void` |  |
| `disabled` | 否 | `boolean \| Matcher \| Matcher[]` |  |
| `placeholder` | 否 | `string` |  |
| `locale` | 否 | `Locale` |  |
| `format` | 否 | `string` |  |
| `presets` | 否 | `DateRangePickerPreset[]` |  |
| `onPresetSelect` | 否 | `(preset: DateRangePickerPreset, value: DateRange) => void` |  |
| `className` | 否 | `string` |  |
| `calendarClassName` | 否 | `string` |  |

---

# date-time-display

- 分组：组合组件（Composite）
- 页面：/components/date-time-display
- 源码：packages/react/src/components/date-time-display.tsx

## 导出

```ts
import { DateTimeDisplay } from "@modra/react";
```

## Props（DateTimeDisplayProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `DateTimeDisplayValue \| null` | An absolute Date, a value accepted by Date, or a millisecond timestamp. |
| `locale` | 否 | `string \| string[]` | Locale passed to Intl.DateTimeFormat. Defaults to the browser locale. |
| `timeZone` | 否 | `string` | IANA time zone used for rendering the value. |
| `format` | 否 | `Intl.DateTimeFormatOptions` | Intl formatting options. Defaults to a medium date and short time. |
| `fallback` | 否 | `React.ReactNode` | Content rendered when value is empty or cannot be parsed. |
| `as` | 否 | `"time" \| "span"` | Element used for the semantic output. |

---

# date-time-picker

- 分组：组合组件（Composite）
- 页面：/components/date-time-picker
- 源码：packages/react/src/components/date-time-picker.tsx

## 导出

```ts
import { DateTimePicker } from "@modra/react";
```

## Props（DateTimePickerProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `Date` |  |
| `defaultValue` | 否 | `Date` |  |
| `onValueChange` | 否 | `(value: Date \| undefined) => void` |  |
| `timeZone` | 否 | `string` | IANA timezone used for the calendar and clock wall time (for example, `America/New_York`). |
| `dateFormat` | 否 | `string` |  |
| `timeFormat` | 否 | `string` |  |
| `use12Hours` | 否 | `boolean` |  |
| `hourStep` | 否 | `number` | Step options of the time columns (for example `minuteStep={15}`). |
| `minuteStep` | 否 | `number` |  |
| `secondStep` | 否 | `number` |  |
| `showSecond` | 否 | `boolean` | Shows the seconds column; defaults to whether `timeFormat` has a seconds token. |
| `disabled` | 否 | `boolean` |  |
| `dateDisabled` | 否 | `boolean \| Matcher \| Matcher[]` |  |
| `placeholder` | 否 | `string` |  |
| `className` | 否 | `string` |  |
| `data-form-control` | 否 | `boolean \| string` | Internal marker applied by FormControl for status styling. |
| `children` | 否 | `React.ReactNode` |  |

---

# date-time-range-picker

- 分组：组合组件（Composite）
- 页面：/components/date-time-range-picker
- 源码：packages/react/src/components/date-time-range-picker.tsx

## 导出

```ts
import { DateTimeRangePicker } from "@modra/react";
```

## Props（DateTimeRangePickerProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `DateTimeRange` |  |
| `defaultValue` | 否 | `DateTimeRange` |  |
| `onValueChange` | 否 | `(value: DateTimeRange \| undefined) => void` |  |
| `disabled` | 否 | `boolean \| Matcher \| Matcher[]` |  |
| `placeholder` | 否 | `string` |  |
| `locale` | 否 | `Locale` |  |
| `dateFormat` | 否 | `string` | Date part of the displayed value. |
| `timeFormat` | 否 | `string` | Time part of the displayed value. |
| `clearable` | 否 | `boolean` | Shows a clear control when a value is set. Defaults to true. |
| `presets` | 否 | `DateTimeRangePickerPreset[]` |  |
| `onPresetSelect` | 否 | `(preset: DateTimeRangePickerPreset, value: DateTimeRange) => void` |  |
| `id` | 否 | `string` |  |
| `className` | 否 | `string` |  |
| `calendarClassName` | 否 | `string` |  |
| `aria-label` | 否 | `string` |  |
| `data-form-control` | 否 | `boolean \| string` | Internal marker applied by FormControl for status styling. |

---

# descriptions

- 分组：组合组件（Composite）
- 页面：/components/descriptions
- 源码：packages/react/src/components/descriptions.tsx

## 导出

```ts
import { Descriptions } from "@modra/react";
```

## Props（DescriptionsProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `title` | 否 | `React.ReactNode` |  |
| `items` | 否 | `DescriptionItem[]` |  |
| `bordered` | 否 | `boolean` |  |
| `column` | 否 | `number` |  |

---

# hover-card

- 分组：组合组件（Composite）
- 页面：/components/hover-card
- 源码：packages/react/src/components/hover-card.tsx

## 导出

```ts
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# list

- 分组：组合组件（Composite）
- 页面：/components/list
- 源码：packages/react/src/components/list.tsx

## 导出

```ts
import { List } from "@modra/react";
```

## Props（ListProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `dataSource` | 否 | `ListItem[]` |  |
| `header` | 否 | `React.ReactNode` |  |
| `footer` | 否 | `React.ReactNode` |  |
| `loading` | 否 | `boolean` |  |
| `bordered` | 否 | `boolean` |  |

---

# menu

- 分组：组合组件（Composite）
- 页面：/components/menu
- 源码：packages/react/src/components/menu.tsx

## 导出

```ts
import { Menu } from "@modra/react";
```

## Props（MenuProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `items` | 否 | `MenuItemType[]` |  |
| `mode` | 否 | `MenuMode` |  |
| `selectedKeys` | 否 | `string[]` |  |
| `defaultSelectedKeys` | 否 | `string[]` |  |
| `openKeys` | 否 | `string[]` |  |
| `defaultOpenKeys` | 否 | `string[]` |  |
| `multiple` | 否 | `boolean` |  |
| `inlineCollapsed` | 否 | `boolean` | Icon-only inline menu. When omitted, a Menu inside a `Layout.Sider` follows the sidebar's collapsed state; an explicit value always wins. |
| `inlineIndent` | 否 | `number` | Indent per level in px for inline menus. Defaults to the `--component-menu-inline-indent` token. |
| `overflow` | 否 | `MenuOverflow` |  |
| `theme` | 否 | `MenuTheme` | `dark` renders on the sidebar surface (sidebar tokens). Defaults to the theme of the enclosing Layout.Sider, or light outside of one. |
| `overflowedIndicator` | 否 | `React.ReactNode` |  |
| `triggerSubMenuAction` | 否 | `"click" \| "hover"` |  |
| `onClick` | 否 | `(info: MenuInfo) => void` |  |
| `onSelect` | 否 | `(info: MenuInfo) => void` |  |
| `onOpenChange` | 否 | `(openKeys: string[]) => void` |  |
| `highlightActiveAncestors` | 否 | `boolean` | Marks submenu triggers that contain a selected item with `data-active-ancestor` and a subtle accent background, so the selected item's section stays visible when it is closed or the menu is collapsed. Defaults to true. |
| `onCollapsedGroupClick` | 否 | `(info: MenuInfo) => void` | Called when a submenu trigger is activated while the inline menu is collapsed. When set (or when the menu sits in an AppShell sidebar that expands itself), the submenu is added to the open keys instead of opening a flyout, so the caller can expand the sidebar and show it inline. |
| `disabled` | 否 | `boolean` |  |

---

# menubar

- 分组：组合组件（Composite）
- 页面：/components/menubar
- 源码：packages/react/src/components/menubar.tsx

## 导出

```ts
import { Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# navigation-menu

- 分组：组合组件（Composite）
- 页面：/components/navigation-menu
- 源码：packages/react/src/components/navigation-menu.tsx

## 导出

```ts
import { NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuSub, NavigationMenuTrigger, NavigationMenuViewport, navigationMenuTriggerStyle } from "@modra/react";
```

## Props（NavigationMenuProps）

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# popconfirm

- 分组：组合组件（Composite）
- 页面：/components/popconfirm
- 源码：packages/react/src/components/popconfirm.tsx

## 导出

```ts
import { Popconfirm } from "@modra/react";
```

## Props（PopconfirmProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `title` | 是 | `React.ReactNode` |  |
| `description` | 否 | `React.ReactNode` |  |
| `onConfirm` | 否 | `() => void \| Promise<void>` |  |
| `onCancel` | 否 | `() => void` |  |
| `okText` | 否 | `React.ReactNode` |  |
| `cancelText` | 否 | `React.ReactNode` |  |
| `children` | 是 | `React.ReactElement` |  |
| `open` | 否 | `boolean` |  |
| `onOpenChange` | 否 | `(open: boolean) => void` |  |

---

# result

- 分组：组合组件（Composite）
- 页面：/components/result
- 源码：packages/react/src/components/result.tsx

## 导出

```ts
import { Result } from "@modra/react";
```

## Props（ResultProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `status` | 否 | `keyof typeof statusClass` |  |
| `title` | 是 | `React.ReactNode` |  |
| `subTitle` | 否 | `React.ReactNode` |  |
| `icon` | 否 | `React.ReactNode` |  |
| `extra` | 否 | `React.ReactNode` |  |

---

# spin

- 分组：组合组件（Composite）
- 页面：/components/spin
- 源码：packages/react/src/components/spin.tsx

## 导出

```ts
import { Spin } from "@modra/react";
```

## Props（SpinProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `spinning` | 否 | `boolean` |  |
| `tip` | 否 | `React.ReactNode` |  |
| `size` | 否 | `ControlSize` |  |
| `fullscreen` | 否 | `boolean` |  |
| `delay` | 否 | `number` | Delay in milliseconds before the indicator becomes visible, to avoid flicker on fast loads. |

---

# statistic

- 分组：组合组件（Composite）
- 页面：/components/statistic
- 源码：packages/react/src/components/statistic.tsx

## 导出

```ts
import { Statistic } from "@modra/react";
```

## Props（StatisticProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `title` | 否 | `React.ReactNode` |  |
| `value` | 否 | `React.ReactNode` |  |
| `prefix` | 否 | `React.ReactNode` |  |
| `suffix` | 否 | `React.ReactNode` |  |
| `valueStyle` | 否 | `React.CSSProperties` |  |
| `loading` | 否 | `boolean` |  |
| `align` | 否 | `"left" \| "center" \| "right"` | Horizontal alignment of the title and value. |

---

# steps

- 分组：组合组件（Composite）
- 页面：/components/steps
- 源码：packages/react/src/components/steps.tsx

## 导出

```ts
import { Steps, StepsItem } from "@modra/react";
```

## Props（StepsItemProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `status` | 否 | `StepStatus` |  |
| `title` | 是 | `React.ReactNode` |  |
| `description` | 否 | `React.ReactNode` |  |
| `icon` | 否 | `React.ReactNode` |  |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |

---

# tag

- 分组：组合组件（Composite）
- 页面：/components/tag
- 源码：packages/react/src/components/tag.tsx

## 导出

```ts
import { Tag, tagVariants } from "@modra/react";
```

## Props（TagProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `closable` | 否 | `boolean` |  |
| `onClose` | 否 | `(event: React.MouseEvent<HTMLButtonElement>) => void` |  |
| `variant` | 否 | `"default" \| "secondary" \| "success" \| "warning" \| "error" \| "outline"` |  |
| `disabled` | 否 | `boolean` |  |

---

# timeline

- 分组：组合组件（Composite）
- 页面：/components/timeline
- 源码：packages/react/src/components/timeline.tsx

## 导出

```ts
import { Timeline } from "@modra/react";
```

## Props（TimelineProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `items` | 否 | `TimelineItem[]` |  |
| `mode` | 否 | `"left" \| "alternate"` |  |

---

# toggle

- 分组：组合组件（Composite）
- 页面：/components/toggle
- 源码：packages/react/src/components/toggle.tsx

## 导出

```ts
import { Toggle, toggleVariants } from "@modra/react";
```

## Props

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `variant` | 否 | `"default" \| "outline"` |  |
| `size` | 否 | `"sm" \| "md" \| "default" \| "lg"` |  |

---

# toggle-group

- 分组：组合组件（Composite）
- 页面：/components/toggle-group
- 源码：packages/react/src/components/toggle-group.tsx

## 导出

```ts
import { ToggleGroup, ToggleGroupItem, toggleGroupItemVariants } from "@modra/react";
```

## Props

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `variant` | 否 | `"default"` |  |
| `size` | 否 | `"sm" \| "md" \| "default" \| "lg"` |  |

---

# tree

- 分组：组合组件（Composite）
- 页面：/components/tree
- 源码：packages/react/src/components/tree.tsx

## 导出

```ts
import { Tree, findNode } from "@modra/react";
```

## Props（TreeProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `treeData` | 是 | `TreeNode[]` |  |
| `expandedKeys` | 否 | `TreeKey[]` |  |
| `defaultExpandedKeys` | 否 | `TreeKey[]` |  |
| `onExpandedKeysChange` | 否 | `(keys: TreeKey[]) => void` |  |
| `selectedKeys` | 否 | `TreeKey[]` |  |
| `defaultSelectedKeys` | 否 | `TreeKey[]` |  |
| `onSelectedKeysChange` | 否 | `(keys: TreeKey[]) => void` |  |
| `checkedKeys` | 否 | `TreeKey[]` |  |
| `defaultCheckedKeys` | 否 | `TreeKey[]` |  |
| `onCheckedKeysChange` | 否 | `(keys: TreeKey[]) => void` |  |
| `checkStrictly` | 否 | `boolean` | Disables parent/child check propagation when true. |
| `halfCheckedKeys` | 否 | `TreeKey[]` | Explicit half checked keys for controlled trees. Derived automatically otherwise. |
| `checkable` | 否 | `boolean` |  |
| `multiple` | 否 | `boolean` |  |
| `loadChildren` | 否 | `(node: TreeNode) => Promise<TreeNode[]>` |  |
| `loading` | 否 | `boolean` | Marks the tree as busy while its root data is loading. |
| `loadingKeys` | 否 | `TreeKey[]` |  |
| `onLoadError` | 否 | `(event: TreeLoadError) => void` |  |
| `activeKey` | 否 | `TreeKey` |  |
| `defaultActiveKey` | 否 | `TreeKey` |  |
| `onActiveKeyChange` | 否 | `(key: TreeKey \| undefined) => void` |  |
| `virtual` | 否 | `boolean` | Render only visible rows in a fixed-height viewport. |
| `height` | 否 | `number` |  |
| `itemHeight` | 否 | `number` |  |
| `overscan` | 否 | `number` |  |
| `draggable` | 否 | `TreeDraggable` | Enable native drag and drop for nodes, optionally filtered per node. |
| `allowDrop` | 否 | `(info: TreeDropInfo) => boolean` | Reject a proposed drop before `onDrop` is called. |
| `onDrop` | 否 | `(info: TreeDropInfo) => void` | Receive a valid mouse or keyboard node move. The caller owns treeData updates. |
| `searchValue` | 否 | `string` | Filters nodes by title, highlights matches, and expands matching ancestor paths. |
| `emptyText` | 否 | `React.ReactNode` | Localized empty content rendered when a search has no matches. |

---

# tree-select

- 分组：组合组件（Composite）
- 页面：/components/tree-select
- 源码：packages/react/src/components/tree-select.tsx

## 导出

```ts
import { TreeSelect } from "@modra/react";
```

## Props（TreeSelectProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `treeData` | 是 | `TreeNode[]` |  |
| `value` | 否 | `TreeKey \| TreeKey[]` |  |
| `defaultValue` | 否 | `TreeKey \| TreeKey[]` |  |
| `onValueChange` | 否 | `(value: TreeKey \| TreeKey[] \| undefined) => void` |  |
| `multiple` | 否 | `boolean` |  |
| `checkable` | 否 | `boolean` |  |
| `placeholder` | 否 | `string` |  |
| `disabled` | 否 | `boolean` |  |
| `className` | 否 | `string` |  |
| `virtual` | 否 | `boolean` | Render the dropdown tree in a fixed-height virtual viewport. |
| `height` | 否 | `number` | Height of the virtual tree viewport in pixels. |
| `itemHeight` | 否 | `number` | Estimated row height used by virtual rendering. |
| `overscan` | 否 | `number` | Number of rows kept mounted around the viewport. |
| `searchValue` | 否 | `string` | Controlled search value for the dropdown tree. |
| `onSearchChange` | 否 | `(value: string) => void` | Called whenever the dropdown search value changes. |

---

# typography

- 分组：组合组件（Composite）
- 页面：/components/typography
- 源码：packages/react/src/components/typography.tsx

## 导出

```ts
import { Paragraph, Text, Title, Typography } from "@modra/react";
```

## Props（TypographyTextProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `code` | 否 | `boolean` |  |
| `mark` | 否 | `boolean` |  |
| `delete` | 否 | `boolean` |  |
| `strong` | 否 | `boolean` |  |
| `type` | 否 | `"secondary" \| "success" \| "warning" \| "danger"` |  |

---

# alert-dialog

- 分组：组合组件（Composite）
- 页面：/components/alert-dialog
- 源码：packages/react/src/components/alert-dialog.tsx

## 导出

```ts
import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, ConfirmDialog, ConfirmDialogHost, confirm } from "@modra/react";
```

## Props（ConfirmDialogProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `open` | 是 | `boolean` |  |
| `onOpenChange` | 是 | `(open: boolean) => void` |  |
| `onCancel` | 否 | `() => void` | Called when the user dismisses the dialog with the cancel action or Escape. |

---

# app-shell

- 分组：组合组件（Composite）
- 页面：/components/app-shell
- 源码：packages/react/src/components/app-shell.tsx

## 导出

```ts
import { AppShell, SiderCollapseButton, SiderToggle, useSiderToggle } from "@modra/react";
```

## Props（AppShellProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `breakpoint` | 否 | `Breakpoint` | Below this breakpoint the shell renders the mobile layout (top bar + content + tabbar). |
| `sidebar` | 否 | `React.ReactNode` | Desktop navigation, rendered inside a collapsible Sider. Below the breakpoint it moves into a drawer. |
| `header` | 否 | `React.ReactNode` | Shown above the content on both desktop and mobile. On mobile it sits in the top bar after the hamburger. |
| `brand` | 否 | `React.ReactNode` | Logo / product name shown in the mobile top bar next to the hamburger button. |
| `tabbar` | 否 | `React.ReactNode` | Mobile bottom navigation, typically a <Tabbar>. Ignored on desktop. |
| `siderWidth` | 否 | `number \| string` | Expanded sidebar width. Defaults to the `--component-layout-sider-width` token. |
| `siderCollapsed` | 否 | `boolean` |  |
| `defaultSiderCollapsed` | 否 | `boolean` |  |
| `onSiderCollapse` | 否 | `(collapsed: boolean) => void` |  |
| `siderCollapsedStorageKey` | 否 | `string` | Persist the uncontrolled sidebar collapsed state in `localStorage` under this key. The stored value is read after mount (SSR-safe) and wins over `defaultSiderCollapsed`; storage errors are ignored. Has no effect when `siderCollapsed` is controlled. |
| `siderTrigger` | 否 | `React.ReactNode` | Replaces the built-in collapse strip at the bottom of the sidebar. `null` hides it; pair that with a `SiderCollapseButton` (or `useSiderToggle`) inside `sidebar`. Defaults to the built-in strip. |
| `expandSiderOnGroupClick` | 否 | `boolean` | When the desktop sidebar is collapsed, activating a submenu trigger of a Menu inside it expands the sidebar (through `onSiderCollapse(false)`) and opens that submenu inline instead of a flyout. Defaults to true. |
| `siderTheme` | 否 | `"light" \| "dark"` | Surface of the sidebar and of the mobile drawer. `dark` uses the `sidebar*` tokens. |
| `mobileNav` | 否 | `AppShellMobileNav` | How the sidebar is reached below the breakpoint. `drawer` (default) renders a hamburger button in the top bar that opens the sidebar in a sheet; `none` keeps the previous behavior of hiding it. |
| `drawerOpen` | 否 | `boolean` |  |
| `defaultDrawerOpen` | 否 | `boolean` |  |
| `onDrawerOpenChange` | 否 | `(open: boolean) => void` |  |
| `drawerWidth` | 否 | `number \| string` | Drawer width; defaults to 18rem capped at 85vw. |
| `closeDrawerOnNavigate` | 否 | `boolean` | Close the drawer when a link or a leaf menu item inside it is activated. Defaults to true. |
| `contentClassName` | 否 | `string` |  |
| `fullscreen` | 否 | `boolean` | Fill the dynamic viewport (`h-dvh`) instead of the parent's height (`h-full`). Enable it when the shell is the page root so no wrapper needs an explicit height. |

---

# async-state

- 分组：组合组件（Composite）
- 页面：/components/async-state
- 源码：packages/react/src/components/async-state.tsx

## 导出

```ts
import { AsyncState } from "@modra/react";
```

## Props（AsyncStateProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `status` | 是 | `AsyncStateStatus` |  |
| `children` | 否 | `React.ReactNode` | Rendered when status is "ready". |
| `empty` | 否 | `EmptyProps \| React.ReactNode` | Props forwarded to the Empty primitive, or a full custom node. |
| `error` | 否 | `Omit<ResultProps, "status"> \| React.ReactNode` | Props forwarded to the Result primitive (status defaults to "error"), or a full custom node. |
| `minHeight` | 否 | `number \| string` | Minimum block height while loading/empty/error, so surrounding layout does not jump. |

---

# bulk-action-bar

- 分组：组合组件（Composite）
- 页面：/components/bulk-action-bar
- 源码：packages/react/src/components/bulk-action-bar.tsx

## 导出

```ts
import { BulkActionBar } from "@modra/react";
```

## Props（BulkActionBarProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `selectedCount` | 是 | `number` | Number of selected items. Selection-dependent actions are disabled at 0. |
| `actions` | 否 | `BulkAction[]` | Ungrouped actions; rendered as the first group. |
| `groups` | 否 | `BulkActionGroup[]` | Grouped actions; groups are visually separated. |
| `onClearSelection` | 否 | `() => void` | Renders a "clear" link next to the count while something is selected. |
| `help` | 否 | `React.ReactNode` | Guidance shown in a popover from a help button at the end of the bar. |
| `helpLabel` | 否 | `React.ReactNode` | Label of the help button. Defaults to the locale copy. |
| `trailing` | 否 | `React.ReactNode` | Always-available controls (export, import, …) aligned to the end of the bar. |
| `selectionLabel` | 否 | `(count: number) => React.ReactNode` | Replaces the default "N selected" copy. |
| `disabled` | 否 | `boolean` |  |

---

# copyable-text

- 分组：组合组件（Composite）
- 页面：/components/copyable-text
- 源码：packages/react/src/components/copyable-text.tsx

## 导出

```ts
import { CopyableText } from "@modra/react";
```

## Props（CopyableTextProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `string` | Text written to the clipboard. Defaults to the rendered children string. |
| `copyLabel` | 否 | `string` | Accessible label for the copy control. Defaults to the locale's `CopyableText.copy`. |
| `copiedLabel` | 否 | `string` | Accessible label shown after a successful copy. Defaults to `CopyableText.copied`. |
| `unsupportedLabel` | 否 | `string` | Accessible label shown when the clipboard API is unavailable. Defaults to `CopyableText.unsupported`. |
| `resetDelay` | 否 | `number` | Duration of the copied state in milliseconds. |
| `onCopy` | 否 | `(value: string) => void` | Called after the clipboard write succeeds. |
| `truncate` | 否 | `boolean` | Single-line truncation through `TruncatedText`: the text ellipsizes, and the full value is shown in a tooltip (with a keyboard focus stop) only when it is actually clipped. The copy button never shrinks, so it stays visible however narrow the control gets. |
| `monospace` | 否 | `boolean` | Renders the text in the monospace code font, for identifiers, keys and hashes. |
| `maxWidth` | 否 | `number \| string` | Caps the width of the whole control (text + copy button). Numbers are pixels. |

---

# empty-value

- 分组：组合组件（Composite）
- 页面：/components/empty-value
- 源码：packages/react/src/components/empty-value.tsx

## 导出

```ts
import { EmptyValue, isEmptyValue } from "@modra/react";
```

## Props（EmptyValueProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `unknown` | The value to display. When it is empty (see `isEmptyValue`) the placeholder is rendered, otherwise `children` (or the value itself when it is a string, number or element). Omit it to always render the placeholder. |
| `children` | 否 | `React.ReactNode` | Rendered instead of the raw value when the value is present. |
| `placeholder` | 否 | `React.ReactNode` | The placeholder glyph. Defaults to an em dash. |

---

# filter-bar

- 分组：组合组件（Composite）
- 页面：/components/filter-bar
- 源码：packages/react/src/components/filter-bar.tsx

## 导出

```ts
import { FilterBar, FilterField } from "@modra/react";
```

## Props（FilterBarProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `columns` | 否 | `FilterBarColumns` | Columns from the `lg` breakpoint up. Below it the grid is two columns from `sm` and a single column on phones. When omitted the column tracks come from the density tokens: 2 / 4 columns by default and an auto-fitting grid (about 4 / 6 / 8 columns as the container grows) in the `admin` density. |
| `onApply` | 否 | `() => void` | Called when the form is submitted (Enter in a field or the apply button). |
| `onReset` | 否 | `() => void` | Called by the reset button. Omit to hide the reset button. |
| `loading` | 否 | `boolean` | Disables and shows a busy state on the apply button. |
| `applyLabel` | 否 | `React.ReactNode` | Overrides the "查询" label. |
| `resetLabel` | 否 | `React.ReactNode` | Overrides the "重置" label. |
| `actions` | 否 | `React.ReactNode` | Extra buttons rendered after reset / apply. |
| `hideActions` | 否 | `boolean` | Hides the built-in apply / reset buttons (use when the page filters instantly). |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |

---

# form-layout

- 分组：组合组件（Composite）
- 页面：/components/form-layout
- 源码：packages/react/src/components/form-layout.tsx

## 导出

```ts
import { FormActions, FormGrid, FormListAddButton, FormListEditor, FormListItem, FormReadonlyField, FormSection } from "@modra/react";
```

## Props（FormListEditorProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `fields` | 是 | `readonly TField[]` | Current items, e.g. `fields` from `FormList` / `useFieldArray`. |
| `renderItem` | 是 | `(field: TField, index: number) => React.ReactNode` | Renders the fields of one item (without the remove button, which the editor adds). |
| `onAdd` | 否 | `() => void` | Shows the add button. |
| `onRemove` | 否 | `(index: number) => void` | Shows a remove button on each item. |
| `min` | 否 | `number` | Remove buttons are disabled while there are this many items or fewer. Defaults to 0. |
| `max` | 否 | `number` | The add button is disabled once there are this many items. |
| `variant` | 否 | `FormListItemVariant` |  |
| `itemTitle` | 否 | `(field: TField, index: number) => React.ReactNode` | Card header for each item (card variant). |
| `removeLabel` | 否 | `(field: TField, index: number) => string` | Remove button name for each item. Defaults to the locale text. |
| `addLabel` | 否 | `React.ReactNode` | Add button content. Defaults to the locale "Add" text. |
| `getKey` | 否 | `(field: TField, index: number) => React.Key` | Stable key per item. Defaults to `field.id`, then `field.key`, then the index. |
| `labelOffset` | 否 | `boolean` | Forwarded to each inline item; see `FormListItem`. |
| `disabled` | 否 | `boolean` | Disables the add and remove buttons. |
| `empty` | 否 | `React.ReactNode` | Shown when there are no items. |

---

# page-container

- 分组：组合组件（Composite）
- 页面：/components/page-container
- 源码：packages/react/src/components/page-container.tsx

## 导出

```ts
import { PageContainer } from "@modra/react";
```

## Props（PageContainerProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `width` | 否 | `PageContainerWidth` | Maximum content width, centred in the content area. `full` removes the cap. Defaults to `full` so existing layouts keep their width. |
| `flush` | 否 | `boolean` | Removes the page padding (16px on phones, 24px from `md`). |

---

# page-header

- 分组：组合组件（Composite）
- 页面：/components/page-header
- 源码：packages/react/src/components/page-header.tsx

## 导出

```ts
import { PageHeader } from "@modra/react";
```

## Props（PageHeaderProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `breadcrumb` | 否 | `PageHeaderBreadcrumbItem[]` | Breadcrumb trail shown above the title. The last entry is rendered as the current page. |
| `icon` | 否 | `React.ReactNode` | A decorative icon shown before the title. |
| `onBack` | 否 | `() => void` | Renders a back button before the title and calls this handler when it is activated. |
| `backLabel` | 否 | `string` | Accessible name of the back button. Defaults to the locale string. |
| `title` | 是 | `React.ReactNode` |  |
| `description` | 否 | `React.ReactNode` | Secondary line under the title (body-sm size, muted). |
| `actions` | 否 | `React.ReactNode` | Actions row. Stays at the end of the title row on wide screens and wraps below the title on narrow ones. |
| `extra` | 否 | `React.ReactNode` | Extra content rendered below the title row (tabs, filters, …). |

---

# row-actions

- 分组：组合组件（Composite）
- 页面：/components/row-actions
- 源码：packages/react/src/components/row-actions.tsx

## 导出

```ts
import { RowActions } from "@modra/react";
```

## Props（RowActionsProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `primary` | 否 | `RowAction \| RowAction[]` | Text actions shown inline (usually one, at most two). |
| `more` | 否 | `RowAction[]` | Secondary actions, tucked into the icon-only "more" menu. Button size follows `--component-row-actions-button-size` (sm control height; md / 28px under admin density). |
| `moreLabel` | 否 | `string` | Accessible name of the more button. Include the row, e.g. `更多操作：张三`. |

---

# settings-row

- 分组：组合组件（Composite）
- 页面：/components/settings-row
- 源码：packages/react/src/components/settings-row.tsx

## 导出

```ts
import { SettingsRow } from "@modra/react";
```

## Props（SettingsRowProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `title` | 是 | `React.ReactNode` |  |
| `description` | 否 | `React.ReactNode` |  |
| `icon` | 否 | `React.ReactNode` |  |
| `control` | 是 | `React.ReactNode` | The row's control, e.g. a <Switch>, <Button> or <Select>. |
| `disabled` | 否 | `boolean` |  |
| `htmlFor` | 否 | `string` | Associates the control with the title for screen readers (pass the control's id). |

---

# stat-card

- 分组：组合组件（Composite）
- 页面：/components/stat-card
- 源码：packages/react/src/components/stat-card.tsx

## 导出

```ts
import { StatCard } from "@modra/react";
```

## Props（StatCardProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `title` | 是 | `React.ReactNode` |  |
| `value` | 是 | `React.ReactNode` |  |
| `prefix` | 否 | `React.ReactNode` |  |
| `suffix` | 否 | `React.ReactNode` |  |
| `icon` | 否 | `React.ReactNode` |  |
| `status` | 否 | `StatusBadgeTone` | Small status dot before the title. Status colour is limited to the dot (or a badge), never the card. |
| `statusLabel` | 否 | `string` | Accessible text for the status dot, announced to screen readers. |
| `badge` | 否 | `React.ReactNode` | Trailing badge (for example a StatusBadge) shown at the end of the title row. |
| `trend` | 否 | `StatCardTrend` |  |
| `loading` | 否 | `boolean` |  |

---

# status-badge

- 分组：组合组件（Composite）
- 页面：/components/status-badge
- 源码：packages/react/src/components/status-badge.tsx

## 导出

```ts
import { BadgeGroup, StatusBadge, statusBadgeVariants } from "@modra/react";
```

## Props（BadgeGroupProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `items` | 否 | `React.ReactNode[]` | Badges to show. Alternatively pass them as children. |
| `max` | 否 | `number` | How many badges stay visible before the rest fold into a "+N" popover. Defaults to 2. |
| `wrap` | 否 | `boolean` | Shows every badge and wraps them onto further lines (same gap, no "+N" control; `max` is ignored). Use it in detail views where nothing may be hidden. Defaults to false. |
| `renderOverflow` | 否 | `(count: number) => React.ReactNode` | Replaces the "+N" label. |
| `empty` | 否 | `React.ReactNode` | Rendered when there are no badges (`items` / children empty, or only `null`, `false` and `""` entries). Defaults to the shared `EmptyValue` placeholder (a muted em dash with an accessible label) so empty table cells stay consistent; pass `null` to render nothing. |

---

# toolbar

- 分组：组合组件（Composite）
- 页面：/components/toolbar
- 源码：packages/react/src/components/toolbar.tsx

## 导出

```ts
import { Toolbar } from "@modra/react";
```

## Props（ToolbarProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `start` | 否 | `React.ReactNode` | Content placed before the main toolbar children. |
| `end` | 否 | `React.ReactNode` | Content placed after the main toolbar children. |
| `align` | 否 | `ToolbarAlign` | Alignment used when the toolbar has no explicit start/end slot. |
| `wrap` | 否 | `boolean` | Whether toolbar content may wrap on narrow viewports. |
| `density` | 否 | `ToolbarDensity` | Spacing preset for dense data-management surfaces. |

---

# truncated-text

- 分组：组合组件（Composite）
- 页面：/components/truncated-text
- 源码：packages/react/src/components/truncated-text.tsx

## 导出

```ts
import { TruncatedText } from "@modra/react";
```

## Props（TruncatedTextProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `lines` | 否 | `number` | Visible lines before truncation. 1 (default) uses a single-line ellipsis. |
| `tooltip` | 否 | `React.ReactNode` | Content of the tooltip. Defaults to the text itself. |
| `alwaysShowTooltip` | 否 | `boolean` | Always show the tooltip, even when the text is not clipped. |

---

# user-menu

- 分组：组合组件（Composite）
- 页面：/components/user-menu
- 源码：packages/react/src/components/user-menu.tsx

## 导出

```ts
import { UserMenu } from "@modra/react";
```

## Props（UserMenuProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `name` | 是 | `string` | Display name: first line of the trigger and the menu header. Also the collapsed trigger's accessible name. |
| `description` | 否 | `React.ReactNode` | Secondary line under the name (account, tenant, role...). |
| `avatarSrc` | 否 | `string` | Avatar image URL. When missing or failing to load, `avatarFallback` is shown. |
| `avatarFallback` | 否 | `React.ReactNode` | Fallback content of the avatar. Defaults to the first character of `name`. |
| `status` | 否 | `UserMenuStatus` | Presence dot on the avatar and a status line in the menu header. |
| `items` | 否 | `UserMenuItem[]` | Menu rows, in order. |
| `header` | 否 | `React.ReactNode \| false` | Replaces the account header at the top of the menu. `false` hides it. By default it shows the avatar, `name`, `description` and `status`. |
| `footer` | 否 | `React.ReactNode` | Rendered below the items, after a separator (e.g. a version line or a plan upsell). |
| `collapsed` | 否 | `boolean` | Collapses the trigger to the avatar. Defaults to the collapsed state of the enclosing `Layout.Sider`. |
| `side` | 否 | `"top" \| "right" \| "bottom" \| "left"` | Where the menu opens. Defaults to `top` (expanded) or `right` (collapsed). |
| `align` | 否 | `"start" \| "center" \| "end"` | Alignment against the trigger. Defaults to `start` (expanded) or `end` (collapsed). |
| `menuClassName` | 否 | `string` | Class name of the menu content. |
| `open` | 否 | `boolean` | Controlled open state. |
| `defaultOpen` | 否 | `boolean` |  |
| `onOpenChange` | 否 | `(open: boolean) => void` |  |
| `modal` | 否 | `boolean` | Set `false` to keep the page interactive while the menu is open. Defaults to `true`. |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |
| `disabled` | 否 | `boolean` |  |

---

# value-preview

- 分组：组合组件（Composite）
- 页面：/components/value-preview
- 源码：packages/react/src/components/value-preview.tsx

## 导出

```ts
import { JsonBlock, JsonPreview, ValuePopover } from "@modra/react";
```

## Props（JsonPreviewProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 是 | `unknown` | Any JSON-serialisable value. Primitives render inline; objects and arrays are summarised. |
| `mode` | 否 | `"popover" \| "inline"` | `popover` (default) shows a short "N 项" / "N 个字段" trigger. `inline` renders the formatted JSON block directly, which suits detail pages. |
| `label` | 否 | `React.ReactNode` | Override the trigger label. |
| `title` | 否 | `React.ReactNode` | Heading for the popover. |
| `space` | 否 | `number` | Indentation passed to JSON.stringify. Defaults to 2. |
| `copyable` | 否 | `boolean` | Shows a copy button next to the formatted JSON. Defaults to true. |
| `disabled` | 否 | `boolean` |  |

---

# aspect-ratio

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/aspect-ratio
- 源码：packages/react/src/components/aspect-ratio.tsx

## 导出

```ts
import { AspectRatio } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# color-picker

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/color-picker
- 源码：packages/react/src/components/color-picker.tsx

## 导出

```ts
import { ColorPicker } from "@modra/react";
```

## Props（ColorPickerProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `string` |  |
| `defaultValue` | 否 | `string` |  |
| `onValueChange` | 否 | `(value: string \| undefined) => void` |  |
| `format` | 否 | `ColorFormat` |  |
| `presets` | 否 | `ColorPreset[]` |  |
| `recentColors` | 否 | `string[]` | Previously selected colors, ordered from newest to oldest. |
| `defaultRecentColors` | 否 | `string[]` |  |
| `onRecentColorsChange` | 否 | `(colors: string[]) => void` |  |
| `maxRecentColors` | 否 | `number` |  |
| `allowEyeDropper` | 否 | `boolean` | Show the native screen color sampler when the browser exposes EyeDropper. |
| `allowClear` | 否 | `boolean` |  |
| `showText` | 否 | `boolean` |  |
| `open` | 否 | `boolean` |  |
| `onOpenChange` | 否 | `(open: boolean) => void` |  |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |
| `disabled` | 否 | `boolean` |  |

---

# echart

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/echart
- 源码：packages/react/src/components/echart.tsx

## 导出

```ts
import { EChart } from "@modra/react";
```

## Props（EChartProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `option` | 是 | `EChartsOption` |  |
| `theme` | 否 | `string \| Record<string, unknown>` | ECharts theme name or registered theme object. Changing it recreates the instance. |
| `renderer` | 否 | `"canvas" \| "svg"` |  |
| `loading` | 否 | `boolean` | Shows the built-in ECharts loading mask over the current option. |
| `onReady` | 否 | `(instance: ECharts) => void` | Called once per instance, right after `echarts.init`, for advanced imperative access. |

---

# image-viewer

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/image-viewer
- 源码：packages/react/src/components/image-viewer.tsx

## 导出

```ts
import { ImageViewer } from "@modra/react";
```

## Props（ImageViewerProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `items` | 是 | `readonly ImageViewerItem[]` | Images to browse. An empty list renders nothing. |
| `open` | 否 | `boolean` |  |
| `defaultOpen` | 否 | `boolean` |  |
| `onOpenChange` | 否 | `(open: boolean) => void` |  |
| `index` | 否 | `number` | Index of the displayed image (controlled). |
| `defaultIndex` | 否 | `number` |  |
| `onIndexChange` | 否 | `(index: number) => void` |  |
| `loop` | 否 | `boolean` | Wrap around at the first/last image. |
| `minScale` | 否 | `number` |  |
| `maxScale` | 否 | `number` |  |
| `actions` | 否 | `React.ReactNode \| ((context: ImageViewerActionsContext) => React.ReactNode)` | Extra toolbar content, e.g. a download button. Receives the current item. |
| `className` | 否 | `string` |  |

---

# input-number

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/input-number
- 源码：packages/react/src/components/input-number.tsx

## 导出

```ts
import { InputNumber } from "@modra/react";
```

## Props（InputNumberProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `number \| null` |  |
| `defaultValue` | 否 | `number` |  |
| `onValueChange` | 否 | `(value: number \| null) => void` |  |
| `min` | 否 | `number` |  |
| `max` | 否 | `number` |  |
| `step` | 否 | `number` |  |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |
| `disabled` | 否 | `boolean` |  |

---

# input-otp

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/input-otp
- 源码：packages/react/src/components/input-otp.tsx

## 导出

```ts
import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from "@modra/react";
```

## Props

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `className` | 否 | `string` |  |
| `children` | 否 | `React.ReactNode` |  |
| `disabled` | 否 | `boolean` |  |

---

# media-grid

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/media-grid
- 源码：packages/react/src/components/media-grid.tsx

## 导出

```ts
import { MediaGrid } from "@modra/react";
```

## Props（MediaGridProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `items` | 是 | `readonly MediaGridItem[]` |  |
| `minItemWidth` | 否 | `string` | Minimum tile width as a CSS length; tiles stretch to fill the row. |
| `aspectRatio` | 否 | `number \| string` | Thumbnail aspect ratio as width / height, or a CSS `aspect-ratio` value. Defaults to 1. |
| `fit` | 否 | `"cover" \| "contain"` |  |
| `selectionMode` | 否 | `"none" \| "multiple"` |  |
| `selectedIds` | 否 | `readonly string[]` |  |
| `defaultSelectedIds` | 否 | `readonly string[]` |  |
| `onSelectedIdsChange` | 否 | `(ids: string[]) => void` |  |
| `onItemClick` | 否 | `(item: MediaGridItem, index: number) => void` | Called when a tile is activated with click or Enter. |
| `itemActions` | 否 | `(item: MediaGridItem, index: number) => React.ReactNode` | Hover/focus toolbar in the bottom-end corner of each tile. Always visible on touch devices. |
| `loading` | 否 | `boolean` | Show placeholder tiles instead of items. |
| `skeletonCount` | 否 | `number` |  |
| `empty` | 否 | `React.ReactNode` | Rendered when there are no items and `loading` is false. |

---

# rate

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/rate
- 源码：packages/react/src/components/rate.tsx

## 导出

```ts
import { Rate } from "@modra/react";
```

## Props（RateProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `count` | 否 | `number` |  |
| `value` | 否 | `number` |  |
| `defaultValue` | 否 | `number` |  |
| `onChange` | 否 | `(value: number) => void` |  |
| `allowHalf` | 否 | `boolean` |  |
| `allowClear` | 否 | `boolean` |  |
| `disabled` | 否 | `boolean` |  |

---

# resizable

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/resizable
- 源码：packages/react/src/components/resizable.tsx

## 导出

```ts
import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# scroll-area

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/scroll-area
- 源码：packages/react/src/components/scroll-area.tsx

## 导出

```ts
import { ScrollArea, ScrollBar } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# slider

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/slider
- 源码：packages/react/src/components/slider.tsx

## 导出

```ts
import { Slider } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。

---

# time-picker

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/time-picker
- 源码：packages/react/src/components/time-picker.tsx

## 导出

```ts
import { TimePicker, TimeRangePicker } from "@modra/react";
```

## Props（TimePickerProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `value` | 否 | `string` |  |
| `defaultValue` | 否 | `string` |  |
| `onValueChange` | 否 | `(value: string \| undefined) => void` |  |
| `format` | 否 | `string` |  |
| `use12Hours` | 否 | `boolean` |  |
| `step` | 否 | `number` |  |
| `hourStep` | 否 | `number` |  |
| `minuteStep` | 否 | `number` |  |
| `secondStep` | 否 | `number` |  |
| `showSecond` | 否 | `boolean` | Shows the seconds column. Defaults to whether `format` contains a seconds token, so `format="HH:mm"` gives an hour/minute-only panel. |
| `disabledHours` | 否 | `TimeDisabled` |  |
| `disabledMinutes` | 否 | `(hour: number) => boolean \| number[]` |  |
| `disabledSeconds` | 否 | `(hour: number, minute: number) => boolean \| number[]` |  |
| `open` | 否 | `boolean` |  |
| `onOpenChange` | 否 | `(open: boolean) => void` |  |

---

# transfer

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/transfer
- 源码：packages/react/src/components/transfer.tsx

## 导出

```ts
import { Transfer } from "@modra/react";
```

## Props（TransferProps）

| 名称 | 必填 | 类型 | 说明 |
| --- | --- | --- | --- |
| `dataSource` | 是 | `TransferItem[]` |  |
| `targetKeys` | 否 | `string[]` |  |
| `defaultTargetKeys` | 否 | `string[]` |  |
| `onTargetKeysChange` | 否 | `(keys: string[]) => void` |  |
| `titles` | 否 | `[React.ReactNode, React.ReactNode]` |  |
| `showSearch` | 否 | `boolean` |  |
| `oneWay` | 否 | `boolean` |  |
| `disabled` | 否 | `boolean` |  |
| `data-form-control` | 否 | `boolean \| string` | Internal marker applied by FormControl for status styling. |

---

# upload

- 分组：高级 / 可选能力（Advanced / Optional）
- 页面：/components/upload
- 源码：packages/react/src/components/upload.tsx

## 导出

```ts
import { Upload, UploadDragger } from "@modra/react";
```

## Props

无独立的 props 接口（组合式组件，参考组件页示例，或沿用原生元素属性）。