@teamix-evo/ui 0.1.1

package/src/components/command/command.tsx

@@ -0,0 +1,147 @@
+import * as React from 'react';
+import { Command as CommandPrimitive } from 'cmdk';
+import { Search } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Dialog, DialogContent } from '@/components/dialog/dialog';
+
+export interface CommandProps
+  extends React.ComponentPropsWithoutRef<typeof CommandPrimitive> {}
+
+const Command = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive>,
+  CommandProps
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive
+    ref={ref}
+    className={cn(
+      'flex h-full w-full flex-col overflow-hidden rounded-md bg-popover text-popover-foreground',
+      className,
+    )}
+    {...props}
+  />
+));
+Command.displayName = CommandPrimitive.displayName;
+
+interface CommandDialogProps
+  extends React.ComponentPropsWithoutRef<typeof Dialog> {}
+
+const CommandDialog = ({ children, ...props }: CommandDialogProps) => (
+  <Dialog {...props}>
+    <DialogContent className="overflow-hidden p-0">
+      <Command className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:size-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:size-5">
+        {children}
+      </Command>
+    </DialogContent>
+  </Dialog>
+);
+
+const CommandInput = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Input>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>
+>(({ className, ...props }, ref) => (
+  <div className="flex items-center border-b px-3" cmdk-input-wrapper="">
+    <Search className="mr-2 size-4 shrink-0 opacity-50" />
+    <CommandPrimitive.Input
+      ref={ref}
+      className={cn(
+        'flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50',
+        className,
+      )}
+      {...props}
+    />
+  </div>
+));
+CommandInput.displayName = CommandPrimitive.Input.displayName;
+
+const CommandList = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.List>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.List>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.List
+    ref={ref}
+    className={cn('max-h-[300px] overflow-y-auto overflow-x-hidden', className)}
+    {...props}
+  />
+));
+CommandList.displayName = CommandPrimitive.List.displayName;
+
+const CommandEmpty = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Empty>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Empty>
+>((props, ref) => (
+  <CommandPrimitive.Empty
+    ref={ref}
+    className="py-6 text-center text-sm text-muted-foreground"
+    {...props}
+  />
+));
+CommandEmpty.displayName = CommandPrimitive.Empty.displayName;
+
+const CommandGroup = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Group>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Group>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.Group
+    ref={ref}
+    className={cn(
+      'overflow-hidden p-1 text-foreground [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground',
+      className,
+    )}
+    {...props}
+  />
+));
+CommandGroup.displayName = CommandPrimitive.Group.displayName;
+
+const CommandSeparator = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.Separator
+    ref={ref}
+    className={cn('-mx-1 h-px bg-border', className)}
+    {...props}
+  />
+));
+CommandSeparator.displayName = CommandPrimitive.Separator.displayName;
+
+const CommandItem = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Item>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.Item
+    ref={ref}
+    className={cn(
+      "relative flex cursor-default gap-2 select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none data-[disabled=true]:pointer-events-none data-[selected='true']:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+      className,
+    )}
+    {...props}
+  />
+));
+CommandItem.displayName = CommandPrimitive.Item.displayName;
+
+const CommandShortcut = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLSpanElement>) => (
+  <span
+    className={cn(
+      'ml-auto text-xs tracking-widest text-muted-foreground',
+      className,
+    )}
+    {...props}
+  />
+);
+CommandShortcut.displayName = 'CommandShortcut';
+
+export {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+};

package/src/components/context-menu/context-menu.meta.md

@@ -0,0 +1,90 @@
+---
+id: context-menu
+name: ContextMenu
+type: component
+category: navigation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# ContextMenu
+
+右键菜单 — Radix ContextMenu 完整实现。**与 DropdownMenu 形态一致**(Item / CheckboxItem / RadioItem / Sub / Label / Separator / Shortcut),仅触发方式不同(右键 vs click)。
+shadcn 显式版,antd 用 Dropdown 模拟同样可达。
+
+## When to use
+
+- 文件 / 资源列表的右键操作(重命名 / 复制路径 / 删除)
+- 编辑器内的右键(剪切 / 复制 / 粘贴)
+- 富内容区的二级操作(替代行内按钮)
+
+## When NOT to use
+
+- 主操作 → 行内 Button
+- 移动端首要场景 → 触屏不易触发右键,改 `DropdownMenu` + 长按
+- 选择类下拉 → `Select`
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `ContextMenuContent` 的 props。
+
+<!-- auto:props:begin -->
+_(组件无 `<Name>Props` interface — props 详见 [`context-menu.tsx`](./context-menu.tsx))_
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add context-menu` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add @radix-ui/react-context-menu@^2.2.0 lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> 子组件与 DropdownMenu 完全一致(只差名称前缀):`ContextMenu / Trigger / Content / Item / CheckboxItem / RadioItem / Label / Separator / Shortcut / Sub / SubTrigger / SubContent / Group / RadioGroup / Portal`。
+
+## AI 生成纪律
+
+- **Trigger 必有可见区域**:不能是空区域,否则无右键目标 — 通常 wrap 一个文本块 / 图片 / 卡片
+- **桌面专属**:移动端默认无右键;移动端要等价能力时改用 `DropdownMenu` 触发
+- **危险动作配色**:`<ContextMenuItem className="text-destructive focus:text-destructive">删除</ContextMenuItem>`
+- **不嵌套 ContextMenu**:嵌套右键反模式
+
+## Examples
+
+```tsx
+import {
+  ContextMenu, ContextMenuTrigger, ContextMenuContent,
+  ContextMenuItem, ContextMenuSeparator, ContextMenuShortcut,
+} from '@/components/ui/context-menu';
+
+<ContextMenu>
+  <ContextMenuTrigger className="flex h-32 w-64 items-center justify-center rounded-md border border-dashed">
+    右键这里
+  </ContextMenuTrigger>
+  <ContextMenuContent className="w-56">
+    <ContextMenuItem>
+      复制 <ContextMenuShortcut>⌘C</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuItem>剪切</ContextMenuItem>
+    <ContextMenuItem>粘贴</ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuItem className="text-destructive focus:text-destructive">
+      删除 <ContextMenuShortcut>⌫</ContextMenuShortcut>
+    </ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```

package/src/components/context-menu/context-menu.stories.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  ContextMenu,
+  ContextMenuTrigger,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+} from './context-menu';
+
+const meta: Meta<typeof ContextMenuContent> = {
+  title: '导航 · Navigation/ContextMenu',
+  component: ContextMenuContent,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof ContextMenuContent>;
+
+export const Default: Story = {
+  render: () => (
+    <ContextMenu>
+      <ContextMenuTrigger className="flex h-32 w-72 items-center justify-center rounded-md border border-dashed text-sm text-muted-foreground">
+        在此处右键(或长按)打开菜单
+      </ContextMenuTrigger>
+      <ContextMenuContent className="w-56">
+        <ContextMenuItem>
+          复制 <ContextMenuShortcut>⌘C</ContextMenuShortcut>
+        </ContextMenuItem>
+        <ContextMenuItem>
+          剪切 <ContextMenuShortcut>⌘X</ContextMenuShortcut>
+        </ContextMenuItem>
+        <ContextMenuItem>
+          粘贴 <ContextMenuShortcut>⌘V</ContextMenuShortcut>
+        </ContextMenuItem>
+        <ContextMenuSeparator />
+        <ContextMenuItem>重命名</ContextMenuItem>
+        <ContextMenuItem>复制路径</ContextMenuItem>
+        <ContextMenuSeparator />
+        <ContextMenuItem className="text-destructive focus:text-destructive">
+          删除 <ContextMenuShortcut>⌫</ContextMenuShortcut>
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  ),
+};

package/src/components/context-menu/context-menu.tsx

@@ -0,0 +1,191 @@
+import * as React from 'react';
+import * as ContextMenuPrimitive from '@radix-ui/react-context-menu';
+import { Check, ChevronRight, Circle } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+const ContextMenu = ContextMenuPrimitive.Root;
+const ContextMenuTrigger = ContextMenuPrimitive.Trigger;
+const ContextMenuGroup = ContextMenuPrimitive.Group;
+const ContextMenuPortal = ContextMenuPrimitive.Portal;
+const ContextMenuSub = ContextMenuPrimitive.Sub;
+const ContextMenuRadioGroup = ContextMenuPrimitive.RadioGroup;
+
+const ContextMenuSubTrigger = React.forwardRef<
+  React.ElementRef<typeof ContextMenuPrimitive.SubTrigger>,
+  React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.SubTrigger> & {
+    inset?: boolean;
+  }
+>(({ className, inset, children, ...props }, ref) => (
+  <ContextMenuPrimitive.SubTrigger
+    ref={ref}
+    className={cn(
+      'flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+      inset && 'pl-8',
+      className,
+    )}
+    {...props}
+  >
+    {children}
+    <ChevronRight className="ml-auto" />
+  </ContextMenuPrimitive.SubTrigger>
+));
+ContextMenuSubTrigger.displayName = ContextMenuPrimitive.SubTrigger.displayName;
+
+const ContextMenuSubContent = React.forwardRef<
+  React.ElementRef<typeof ContextMenuPrimitive.SubContent>,
+  React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.SubContent>
+>(({ className, ...props }, ref) => (
+  <ContextMenuPrimitive.SubContent
+    ref={ref}
+    className={cn(
+      'z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+      className,
+    )}
+    {...props}
+  />
+));
+ContextMenuSubContent.displayName = ContextMenuPrimitive.SubContent.displayName;
+
+const ContextMenuContent = React.forwardRef<
+  React.ElementRef<typeof ContextMenuPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.Content>
+>(({ className, ...props }, ref) => (
+  <ContextMenuPrimitive.Portal>
+    <ContextMenuPrimitive.Content
+      ref={ref}
+      className={cn(
+        'z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md animate-in fade-in-80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+        className,
+      )}
+      {...props}
+    />
+  </ContextMenuPrimitive.Portal>
+));
+ContextMenuContent.displayName = ContextMenuPrimitive.Content.displayName;
+
+const ContextMenuItem = React.forwardRef<
+  React.ElementRef<typeof ContextMenuPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.Item> & {
+    inset?: boolean;
+  }
+>(({ className, inset, ...props }, ref) => (
+  <ContextMenuPrimitive.Item
+    ref={ref}
+    className={cn(
+      'relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+      inset && 'pl-8',
+      className,
+    )}
+    {...props}
+  />
+));
+ContextMenuItem.displayName = ContextMenuPrimitive.Item.displayName;
+
+const ContextMenuCheckboxItem = React.forwardRef<
+  React.ElementRef<typeof ContextMenuPrimitive.CheckboxItem>,
+  React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.CheckboxItem>
+>(({ className, children, checked, ...props }, ref) => (
+  <ContextMenuPrimitive.CheckboxItem
+    ref={ref}
+    className={cn(
+      'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className,
+    )}
+    checked={checked}
+    {...props}
+  >
+    <span className="absolute left-2 flex size-3.5 items-center justify-center">
+      <ContextMenuPrimitive.ItemIndicator>
+        <Check className="size-4" />
+      </ContextMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </ContextMenuPrimitive.CheckboxItem>
+));
+ContextMenuCheckboxItem.displayName =
+  ContextMenuPrimitive.CheckboxItem.displayName;
+
+const ContextMenuRadioItem = React.forwardRef<
+  React.ElementRef<typeof ContextMenuPrimitive.RadioItem>,
+  React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.RadioItem>
+>(({ className, children, ...props }, ref) => (
+  <ContextMenuPrimitive.RadioItem
+    ref={ref}
+    className={cn(
+      'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      className,
+    )}
+    {...props}
+  >
+    <span className="absolute left-2 flex size-3.5 items-center justify-center">
+      <ContextMenuPrimitive.ItemIndicator>
+        <Circle className="size-2 fill-current" />
+      </ContextMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </ContextMenuPrimitive.RadioItem>
+));
+ContextMenuRadioItem.displayName = ContextMenuPrimitive.RadioItem.displayName;
+
+const ContextMenuLabel = React.forwardRef<
+  React.ElementRef<typeof ContextMenuPrimitive.Label>,
+  React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.Label> & {
+    inset?: boolean;
+  }
+>(({ className, inset, ...props }, ref) => (
+  <ContextMenuPrimitive.Label
+    ref={ref}
+    className={cn(
+      'px-2 py-1.5 text-sm font-semibold text-foreground',
+      inset && 'pl-8',
+      className,
+    )}
+    {...props}
+  />
+));
+ContextMenuLabel.displayName = ContextMenuPrimitive.Label.displayName;
+
+const ContextMenuSeparator = React.forwardRef<
+  React.ElementRef<typeof ContextMenuPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <ContextMenuPrimitive.Separator
+    ref={ref}
+    className={cn('-mx-1 my-1 h-px bg-border', className)}
+    {...props}
+  />
+));
+ContextMenuSeparator.displayName = ContextMenuPrimitive.Separator.displayName;
+
+const ContextMenuShortcut = ({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLSpanElement>) => (
+  <span
+    className={cn(
+      'ml-auto text-xs tracking-widest text-muted-foreground',
+      className,
+    )}
+    {...props}
+  />
+);
+ContextMenuShortcut.displayName = 'ContextMenuShortcut';
+
+export {
+  ContextMenu,
+  ContextMenuTrigger,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuCheckboxItem,
+  ContextMenuRadioItem,
+  ContextMenuLabel,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuGroup,
+  ContextMenuPortal,
+  ContextMenuSub,
+  ContextMenuSubContent,
+  ContextMenuSubTrigger,
+  ContextMenuRadioGroup,
+};

package/src/components/data-table/data-table.meta.md

@@ -0,0 +1,149 @@
+---
+id: data-table
+name: DataTable
+type: component
+category: data-display
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# DataTable
+
+数据表 — 基于 [`@tanstack/react-table`](https://tanstack.com/table) + 基础 `Table` primitives + `SimplePagination`。
+**等价 antd `Table` 的核心交互合集**:`sorter` + `filter` + `pagination` + `rowSelection`,声明式 `columns + data` 即可。
+
+## When to use
+
+- 需要排序 / 筛选 / 分页 / 多选的列表(用户管理 / 订单 / 资源)
+- 大数据量(配 TanStack 的 virtualizer 可接百万行,本组件目前未集成)
+- 需要复杂列(多列分组、可拖拽列宽、嵌套行)— 用户可在 columns 里自由扩展
+
+## When NOT to use
+
+- 简单静态展示 → 基础 `Table`
+- 键值对详情 → `Descriptions`(v0.x)
+- 树结构 → `Tree`(v0.x)
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `columns` | `ColumnDef<TData, TValue>[]` | – | ✓ | 列定义(TanStack ColumnDef)。 |
+| `data` | `TData[]` | – | ✓ | 行数据。 |
+| `pagination` | `boolean \| { pageSize?: number; siblingCount?: number }` | `true` | – | 是否启用分页(antd `pagination` 并集)。 传 `true` 用默认配置;传对象自定义 pageSize / siblingCount。 |
+| `sorting` | `boolean` | `true` | – | 是否启用排序(列定义里的 `enableSorting` 也要打开;默认列已开)。 |
+| `filtering` | `boolean` | `true` | – | 是否启用列过滤(每列 `header` 配 input 单独使用;此 flag 控制 columnFilters 状态)。 |
+| `onRowSelectionChange` | `(selectedRows: TData[]) => void` | – | – | 行选择回调(antd `rowSelection.onChange` 并集)。传入即启用 selection。 Selected rows 的原始 data 通过 `getRowId(row)` 推断,默认是 row.index。 |
+| `emptyText` | `React.ReactNode` | – | – | 空数据时显示的内容。 |
+| `className` | `string` | – | – | 容器 className。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add data-table` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `table` | component | 基础表格 — 原生 HTML 元素薄包装(视觉骨架,无交互,交互见 DataTable) |
+| `pagination` | component | 分页 — shadcn primitives + 高阶 SimplePagination(antd 风格 total/pageSize/current/onChange,自动页码窗口 + 折叠) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add @tanstack/react-table@^8.0.0
+```
+<!-- auto:deps:end -->
+
+> 透传 TanStack Table 的核心能力。需要更精细控制(可控 state、virtualizer、column visibility / resizing 等),请直接用 `useReactTable` + 基础 `Table` primitives 自行拼装。
+
+## AI 生成纪律
+
+- **`columns` 用 `ColumnDef<TData>` 类型**:从本模块 re-export,业务侧 `import { type ColumnDef }`
+- **`accessorKey` 必稳定**:用对象的字段名,不要 index
+- **排序触发器**:`header: ({ column }) => <Button onClick={() => column.toggleSorting()}>...</Button>`
+- **筛选**:在 column header 里渲染 Input 调 `column.setFilterValue`
+- **rowSelection 用 `<Checkbox>`**:第一列加 `<Checkbox checked={row.getIsSelected()} onCheckedChange={(v) => row.toggleSelected(!!v)} />`
+- **不要在每个 cell 内独立请求数据**:在父组件聚合后传 `data`
+- **大数据量 → virtualizer**:本组件未集成,> 1000 行需自行加 `@tanstack/react-virtual`
+
+## Examples
+
+```tsx
+import { DataTable, type ColumnDef } from '@/components/ui/data-table';
+import { Button } from '@/components/ui/button';
+import { Checkbox } from '@/components/ui/checkbox';
+import { Badge } from '@/components/ui/badge';
+import { ArrowUpDown } from 'lucide-react';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  status: 'active' | 'invited';
+}
+
+const columns: ColumnDef<User>[] = [
+  {
+    id: 'select',
+    header: ({ table }) => (
+      <Checkbox
+        checked={
+          table.getIsAllPageRowsSelected()
+            ? true
+            : table.getIsSomePageRowsSelected()
+              ? 'indeterminate'
+              : false
+        }
+        onCheckedChange={(v) => table.toggleAllPageRowsSelected(!!v)}
+      />
+    ),
+    cell: ({ row }) => (
+      <Checkbox
+        checked={row.getIsSelected()}
+        onCheckedChange={(v) => row.toggleSelected(!!v)}
+      />
+    ),
+  },
+  { accessorKey: 'name', header: '姓名' },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => (
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={() => column.toggleSorting(column.getIsSorted() === 'asc')}
+      >
+        邮箱 <ArrowUpDown className="ml-1" />
+      </Button>
+    ),
+  },
+  {
+    accessorKey: 'status',
+    header: '状态',
+    cell: ({ row }) =>
+      row.original.status === 'active' ? (
+        <Badge variant="success">活跃</Badge>
+      ) : (
+        <Badge>已邀请</Badge>
+      ),
+  },
+];
+
+<DataTable
+  columns={columns}
+  data={users}
+  pagination={{ pageSize: 10 }}
+  onRowSelectionChange={(selected) => console.log(selected)}
+/>
+```