@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/data-table/index.tsx

@@ -0,0 +1,1537 @@
+/**
+ * 数据表格 DataTable
+ *
+ * 高阶数据表 — 基于 [@tanstack/react-table](https://tanstack.com/table) 的配置式表格，组合
+ * Table primitives + Pagination 实现 排序 / 过滤 / 分页 / 行选择 / 行展开 / 自定义渲染 等核心交互。
+ * 主题与视觉对齐本仓 tokens；API 命名采用业界主流（columns / data / accessorKey / header / cell / enableSorting…），
+ * 同时保留对 antd / cloud-design 旧字段的向后兼容（dataSource / dataIndex / title / sortable / render / fixed / width）。
+ *
+ * @when
+ * - 需要排序、筛选等交互的数据列表
+ * - 批量操作场景（多选行 + 操作按钮）
+ * - 大量数据的分页展示
+ * - 表格行需要可展开补充信息时
+ *
+ * 组合结构：DataTable（columns + data）— 内部组合 Table + TableHeader/Body/Row/Cell + Pagination + Popover Filter
+ */
+import * as React from 'react';
+import {
+  flexRender,
+  getCoreRowModel,
+  getExpandedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+  type CellContext,
+  type ColumnDef,
+  type ColumnFiltersState,
+  type ExpandedState,
+  type HeaderContext,
+  type RowSelectionState,
+  type SortingState,
+  type VisibilityState,
+  type Row as RTRow,
+  type Table as RTTable,
+} from '@tanstack/react-table';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import {
+  DndContext,
+  PointerSensor,
+  closestCenter,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+} from '@dnd-kit/core';
+import {
+  SortableContext,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable';
+import { CSS } from '@dnd-kit/utilities';
+import {
+  ArrowDown,
+  ArrowUp,
+  ArrowUpDown,
+  ChevronRight,
+  Filter as FilterIcon,
+  GripVertical,
+} from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/button';
+import { Checkbox } from '@/components/checkbox';
+import { Pagination } from '@/components/pagination';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/popover';
+import { RadioGroup, RadioGroupItem } from '@/components/radio-group';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/table';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+/** 列过滤候选项。 */
+export interface DataTableFilterOption {
+  /** 选项展示文案。 */
+  label: React.ReactNode;
+  /** 选项值（用于匹配 record 字段）。 */
+  value: string | number | boolean;
+}
+
+/** 列定义；优先使用业界主流字段（accessorKey/header/cell/enableSorting…），保留 cd 旧字段做兼容。 */
+export interface DataTableColumn<T> {
+  // ── 主流字段 ────────────────────────────
+  /** 列唯一键；若省略则自动用 accessorKey / dataIndex。 */
+  key?: string;
+  /** 字段访问器（顶级 key）。与 dataIndex 等价。 */
+  accessorKey?: keyof T & string;
+  /** 表头节点或渲染函数。 */
+  header?:
+    | React.ReactNode
+    | ((ctx: HeaderContext<T, unknown>) => React.ReactNode);
+  /** 单元格渲染函数（TanStack 风格）。 */
+  cell?: (ctx: CellContext<T, unknown>) => React.ReactNode;
+  /** 是否启用排序。 @default false */
+  enableSorting?: boolean;
+  /** 是否启用列过滤；启用后自动以 includes 匹配 filters 列表。 @default 由 filters 隐式开启 */
+  enableColumnFilter?: boolean;
+  /** 过滤候选项（启用 filter 时必填）。 */
+  filters?: DataTableFilterOption[];
+  /** 过滤模式：单选 / 多选。 @default 'multiple' */
+  filterMode?: 'single' | 'multiple';
+  /** 列宽（数字视为 px）。 */
+  size?: number;
+  /** 列对齐方式。 @default 'left' */
+  align?: 'left' | 'center' | 'right';
+  /** 是否可拖拽调整列宽。 @default false */
+  resizable?: boolean;
+  /** 子列（用于多级表头 / ColumnGroup）；传入后本列作为 header group。 */
+  children?: DataTableColumn<T>[];
+
+  // ── 兼容字段（cd / antd） ────────────────
+  /** 表头标题（旧字段，等价 `header`）。 */
+  title?: React.ReactNode;
+  /** 字段名（旧字段，等价 `accessorKey`）。 */
+  dataIndex?: keyof T & string;
+  /** 是否可排序（旧字段，等价 `enableSorting`）。 */
+  sortable?: boolean;
+  /** 单元格渲染（旧字段，签名为 `(value, record, index)`）。 */
+  render?: (value: unknown, record: T, index: number) => React.ReactNode;
+  /** 锁列方向（旧字段，留作 P1 启用）。 */
+  fixed?: 'left' | 'right';
+  /** 列宽（旧字段，等价 `size`，字符串视作 CSS 宽度）。 */
+  width?: number | string;
+}
+
+/** 行选择配置（兼容 cd 风格）。 */
+export interface DataTableRowSelection<T> {
+  /** 模式：multiple（多选，默认） / single（单选）。 */
+  mode?: 'single' | 'multiple';
+  /** 受控选中行 key 列表。 */
+  selectedRowKeys?: string[];
+  /** 默认选中行 key 列表（非受控）。 */
+  defaultSelectedRowKeys?: string[];
+  /** 选中变化回调。 */
+  onChange?: (selectedRowKeys: string[], selectedRows: T[]) => void;
+  /** 自定义每行 checkbox / radio 属性。 */
+  getProps?: (record: T, index: number) => Record<string, unknown>;
+}
+
+/** 行展开配置。 */
+export interface DataTableExpandable<T> {
+  /** 展开内容渲染函数。 */
+  expandedRowRender: (record: T, index: number) => React.ReactNode;
+  /** 行是否可展开；返回 false 则该行不出现展开按钮。 */
+  rowExpandable?: (record: T, index: number) => boolean;
+  /** 受控展开行 key 列表。 */
+  expandedRowKeys?: string[];
+  /** 默认展开行 key 列表（非受控）。 */
+  defaultExpandedRowKeys?: string[];
+  /** 展开 / 收起回调。 */
+  onChange?: (expandedRowKeys: string[]) => void;
+}
+
+/** 分页配置（false 关闭分页）。 */
+export type DataTablePagination =
+  | false
+  | {
+      /** 当前页（1-based 受控）。 */
+      current?: number;
+      /** 默认当前页（非受控）。 @default 1 */
+      defaultCurrent?: number;
+      /** 每页条数（受控）。 */
+      pageSize?: number;
+      /** 默认每页条数（非受控）。 @default 10 */
+      defaultPageSize?: number;
+      /** 总条数（默认取 data.length）。 */
+      total?: number;
+      /** 每页条数候选项。 */
+      pageSizeOptions?: number[];
+      /** 是否显示 pageSize 选择器。 @default false */
+      showSizeChanger?: boolean;
+      /** 是否显示总数文本。 @default true */
+      showTotal?: boolean;
+      /** 翻页回调。 */
+      onChange?: (page: number, pageSize: number) => void;
+    };
+
+/** DataTable 完整 props。 */
+export interface DataTableProps<T>
+  extends Omit<React.ComponentProps<'div'>, 'onChange' | 'onDragEnd'> {
+  /** 列定义。 */
+  columns: DataTableColumn<T>[];
+  /** 数据源（主名）。 */
+  data?: T[];
+  /** 数据源（cd / antd 兼容名，等价 `data`）。 */
+  dataSource?: T[];
+  /** 行唯一键字段或函数。 @default 'id' */
+  rowKey?: keyof T | ((record: T) => string);
+  /** 表格尺寸。 @default 'sm' */
+  size?: 'sm' | 'md';
+  /** 是否显示外边框与单元格分隔线。 @default true */
+  bordered?: boolean;
+  /** 是否启用斑马纹。 @default false */
+  striped?: boolean;
+  /** 是否启用行 hover 高亮。 @default true */
+  hoverable?: boolean;
+  /** 是否启用十字辅助轴。 @default false */
+  crossline?: boolean;
+  /** 是否吸顶表头。 @default false */
+  stickyHeader?: boolean;
+  /** 表格容器最大高度（配合 stickyHeader 使用）。 */
+  maxBodyHeight?: number | string;
+  /** 是否启用列宽拖拽（开关，列级用 column.resizable 覆盖）。 @default false */
+  enableColumnResizing?: boolean;
+  /** 受控列宽状态。 */
+  columnSizing?: Record<string, number>;
+  /** 列宽变更回调（拖拽完成时触发）。 */
+  onColumnSizingChange?: (sizing: Record<string, number>) => void;
+  /** 是否启用树形结构（按 `childrenColumnName` 字段递归渲染子行）。 @default false */
+  isTree?: boolean;
+  /** 子节点字段名（树形模式下）。 @default 'children' */
+  childrenColumnName?: string;
+  /** 每层缩进像素（树形模式下）。 @default 16 */
+  indentSize?: number;
+  /** 是否启用虚拟滚动（大数据量场景）。需同时设置 `maxBodyHeight`。 @default false */
+  virtual?: boolean;
+  /** 虚拟滚动预估行高（像素）。 @default 40 */
+  estimateRowHeight?: number;
+  /** 虚拟滚动 overscan 个数。 @default 8 */
+  virtualOverscan?: number;
+  /** 合并单元格：返回 `{ rowSpan, colSpan }`；返回 0 则跳过该 td。 */
+  cellProps?: (
+    rowIndex: number,
+    colIndex: number,
+    record: T,
+  ) => { rowSpan?: number; colSpan?: number } | undefined;
+  /** 是否启用行拖拽排序。 @default false */
+  draggable?: boolean;
+  /** 行拖拽结束回调（仅拖拽启用时）。 */
+  onDragEnd?: (info: { from: number; to: number; data: T[] }) => void;
+  /** 是否加载中。 @default false */
+  loading?: boolean;
+  /** 自定义加载节点。 */
+  loadingNode?: React.ReactNode;
+  /** 空数据节点。 @default 居中 Inbox 图标 + “暂无数据” */
+  empty?: React.ReactNode;
+
+  // ── 受控 / 非受控状态 ─────────────────
+  /** 受控排序状态（TanStack SortingState）。 */
+  sorting?: SortingState;
+  /** 排序变化回调。 */
+  onSortingChange?: (sorting: SortingState) => void;
+  /** 受控列过滤状态（TanStack ColumnFiltersState）。 */
+  columnFilters?: ColumnFiltersState;
+  /** 列过滤变化回调。 */
+  onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
+  /** 受控列显隐状态（key 为列 id，value 为 boolean）。 */
+  columnVisibility?: VisibilityState;
+  /** 列显隐变化回调。 */
+  onColumnVisibilityChange?: (visibility: VisibilityState) => void;
+  /** 行选择配置；传入开启选择列。 */
+  rowSelection?: DataTableRowSelection<T>;
+  /** 分页配置；传 false 关闭分页。 */
+  pagination?: DataTablePagination;
+  /** 行展开配置；传入开启展开列。 */
+  expandable?: DataTableExpandable<T>;
+  /** 行级 props（cd 兼容）。 */
+  onRow?: (
+    record: T,
+    index: number,
+  ) => React.HTMLAttributes<HTMLTableRowElement>;
+  /** 整行点击。 */
+  onRowClick?: (record: T, index: number, e: React.MouseEvent) => void;
+
+  /** 类容器 className（透传给最外层 div）。 */
+  className?: string;
+  /** Table 的 className（内层 table 元素）。 */
+  tableClassName?: string;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function getRowKey<T>(
+  record: T,
+  rowKey: keyof T | ((record: T) => string),
+): string {
+  if (typeof rowKey === 'function') return rowKey(record);
+  return String((record as Record<string, unknown>)[rowKey as string]);
+}
+
+function alignClass(align?: DataTableColumn<unknown>['align']) {
+  if (align === 'center') return 'text-center';
+  if (align === 'right') return 'text-right';
+  return undefined;
+}
+
+function widthStyle(col: DataTableColumn<unknown>): React.CSSProperties {
+  const w = col.size ?? col.width;
+  if (w === undefined) return {};
+  return { width: typeof w === 'number' ? `${w}px` : w };
+}
+
+/** 把 DataTableColumn 适配为 TanStack ColumnDef；同时按 fixed 重排（左→中→右）以满足锁列 sticky 计算。 */
+function adaptColumns<T>(
+  columns: DataTableColumn<T>[],
+): ColumnDef<T, unknown>[] {
+  const adaptOne = (col: DataTableColumn<T>): ColumnDef<T, unknown> => {
+    // 多级表头：header group
+    if (col.children && col.children.length > 0) {
+      const groupId =
+        col.key ??
+        (typeof col.header === 'string'
+          ? col.header
+          : typeof col.title === 'string'
+          ? col.title
+          : Math.random().toString());
+      return {
+        id: groupId,
+        header: (col.header ?? col.title) as ColumnDef<T, unknown>['header'],
+        meta: {
+          align: col.align,
+          fixed: col.fixed,
+        },
+        columns: col.children.map(adaptOne),
+      };
+    }
+    const accessorKey = col.accessorKey ?? col.dataIndex;
+    const id =
+      col.key ??
+      (accessorKey as string | undefined) ??
+      Math.random().toString();
+    const enableSorting = col.enableSorting ?? col.sortable ?? false;
+    const enableColumnFilter =
+      col.enableColumnFilter ?? (col.filters ? true : false);
+    const filterMode = col.filterMode ?? 'multiple';
+
+    const header =
+      col.header ?? col.title ?? (accessorKey as React.ReactNode | undefined);
+
+    const cell =
+      col.cell ??
+      ((ctx: CellContext<T, unknown>): React.ReactNode => {
+        if (col.render) {
+          return col.render(ctx.getValue(), ctx.row.original, ctx.row.index);
+        }
+        return ctx.getValue() as React.ReactNode;
+      });
+
+    const def: ColumnDef<T, unknown> = {
+      id,
+      header: header as ColumnDef<T, unknown>['header'],
+      cell,
+      enableSorting,
+      enableColumnFilter,
+      enableResizing: col.resizable ?? false,
+      meta: {
+        align: col.align,
+        filters: col.filters,
+        filterMode,
+        size: col.size ?? col.width,
+        fixed: col.fixed,
+        resizable: col.resizable ?? false,
+      },
+    };
+
+    if (accessorKey) {
+      (def as { accessorKey?: string }).accessorKey = accessorKey;
+    }
+
+    if (col.size != null) {
+      def.size = col.size;
+    }
+
+    if (enableColumnFilter) {
+      def.filterFn = (row, _columnId, filterValue: unknown) => {
+        if (filterValue == null) return true;
+        const v = row.getValue<unknown>(_columnId);
+        if (Array.isArray(filterValue)) {
+          if (filterValue.length === 0) return true;
+          return filterValue.includes(v as string | number | boolean);
+        }
+        return v === filterValue;
+      };
+    }
+
+    return def;
+  };
+
+  const adapted = columns.map(adaptOne);
+
+  // 按 fixed 重排：left → middle → right
+  const fixedOf = (d: ColumnDef<T, unknown>) =>
+    (d.meta as { fixed?: 'left' | 'right' } | undefined)?.fixed;
+  const left = adapted.filter((d) => fixedOf(d) === 'left');
+  const right = adapted.filter((d) => fixedOf(d) === 'right');
+  const mid = adapted.filter((d) => {
+    const f = fixedOf(d);
+    return f !== 'left' && f !== 'right';
+  });
+  return [...left, ...mid, ...right];
+}
+
+// ─── Filter Popover ─────────────────────────────────────────────────────────
+
+interface ColumnFilterPopoverProps {
+  options: DataTableFilterOption[];
+  mode: 'single' | 'multiple';
+  value: unknown;
+  onChange: (value: unknown) => void;
+}
+
+function ColumnFilterPopover({
+  options,
+  mode,
+  value,
+  onChange,
+}: ColumnFilterPopoverProps) {
+  const [open, setOpen] = React.useState(false);
+  const [draft, setDraft] = React.useState<unknown>(value);
+
+  React.useEffect(() => {
+    if (open) setDraft(value);
+  }, [open, value]);
+
+  const active =
+    mode === 'multiple'
+      ? Array.isArray(value) && value.length > 0
+      : value != null && value !== '';
+
+  const handleConfirm = () => {
+    onChange(draft);
+    setOpen(false);
+  };
+  const handleReset = () => {
+    setDraft(mode === 'multiple' ? [] : undefined);
+    onChange(undefined);
+    setOpen(false);
+  };
+
+  const draftArr = Array.isArray(draft) ? (draft as unknown[]) : [];
+  const toggleMulti = (v: unknown, checked: boolean) => {
+    setDraft(
+      checked ? [...draftArr, v] : draftArr.filter((item) => item !== v),
+    );
+  };
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          aria-label="过滤"
+          className={cn(
+            'inline-flex size-5 cursor-pointer items-center justify-center rounded-sm text-muted-foreground transition-colors hover:bg-accent hover:text-foreground',
+            active && 'text-primary',
+          )}
+          onClick={(e) => e.stopPropagation()}
+        >
+          <FilterIcon className="size-3.5" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent align="start" className="w-44 gap-2 p-2">
+        {mode === 'multiple' ? (
+          <div className="flex flex-col gap-1.5 py-1">
+            {options.map((opt) => {
+              const checked = draftArr.includes(opt.value);
+              return (
+                <label
+                  key={String(opt.value)}
+                  className="flex cursor-pointer items-center gap-2 text-xs"
+                >
+                  <Checkbox
+                    checked={checked}
+                    onCheckedChange={(c) => toggleMulti(opt.value, c === true)}
+                  />
+                  <span>{opt.label}</span>
+                </label>
+              );
+            })}
+          </div>
+        ) : (
+          <RadioGroup
+            value={draft != null ? String(draft) : ''}
+            onValueChange={(v) => {
+              const matched = options.find((o) => String(o.value) === v);
+              setDraft(matched?.value);
+            }}
+            className="gap-1.5 py-1"
+          >
+            {options.map((opt) => {
+              const id = `filter-${String(opt.value)}`;
+              return (
+                <label
+                  key={String(opt.value)}
+                  htmlFor={id}
+                  className="flex cursor-pointer items-center gap-2 text-xs"
+                >
+                  <RadioGroupItem id={id} value={String(opt.value)} />
+                  <span>{opt.label}</span>
+                </label>
+              );
+            })}
+          </RadioGroup>
+        )}
+        <div className="mt-1 flex justify-end gap-2 border-t border-border pt-2">
+          <Button variant="ghost" size="sm" onClick={handleReset}>
+            重置
+          </Button>
+          <Button size="sm" onClick={handleConfirm}>
+            确定
+          </Button>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+// ─── Drag helpers ───────────────────────────────────────────────────────────
+
+interface DragHandleContextValue {
+  attributes?: Record<string, unknown>;
+  listeners?: Record<string, unknown>;
+}
+
+const DragHandleContext = React.createContext<DragHandleContextValue>({});
+
+/** 拖拽手柄 cell（在 `__drag__` 列内自动渲染；从 SortableRow 继承 listeners）。 */
+function DragHandleCell() {
+  const { attributes, listeners } = React.useContext(DragHandleContext);
+  return (
+    <button
+      type="button"
+      aria-label="拖拽排序"
+      className="inline-flex size-5 cursor-grab items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground active:cursor-grabbing"
+      onClick={(e) => e.stopPropagation()}
+      {...(attributes as React.HTMLAttributes<HTMLButtonElement> | undefined)}
+      {...(listeners as React.HTMLAttributes<HTMLButtonElement> | undefined)}
+    >
+      <GripVertical className="size-3.5" />
+    </button>
+  );
+}
+
+interface SortableRowProps extends React.ComponentProps<'tr'> {
+  rowId: string;
+}
+
+function SortableRow({ rowId, children, style, ...rest }: SortableRowProps) {
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id: rowId });
+  const finalStyle: React.CSSProperties = {
+    ...style,
+    transform: CSS.Transform.toString(transform),
+    transition,
+    opacity: isDragging ? 0.6 : 1,
+    position: 'relative',
+    zIndex: isDragging ? 2 : undefined,
+  };
+  return (
+    <DragHandleContext.Provider
+      value={{
+        attributes: attributes as unknown as Record<string, unknown>,
+        listeners: listeners as unknown as Record<string, unknown> | undefined,
+      }}
+    >
+      <TableRow
+        ref={(node: HTMLTableRowElement | null) => setNodeRef(node)}
+        style={finalStyle}
+        {...rest}
+      >
+        {children}
+      </TableRow>
+    </DragHandleContext.Provider>
+  );
+}
+
+// ─── EditableCell ───────────────────────────────────────────────────────────
+
+export interface EditableCellProps {
+  /** 当前值。 */
+  value: string | number;
+  /** blur / Enter 时若值变化则提交。 */
+  onCommit: (next: string | number) => void;
+  /** 输入类型。 @default 'text' */
+  type?: 'text' | 'number';
+  /** placeholder。 */
+  placeholder?: string;
+  /** 自定义 className。 */
+  className?: string;
+}
+
+/** 双击切入编辑态的单元格 — 用于 column.cell 中包裹文本字段以快速实现行内编辑。 */
+function EditableCell({
+  value,
+  onCommit,
+  type = 'text',
+  placeholder,
+  className,
+}: EditableCellProps) {
+  const [editing, setEditing] = React.useState(false);
+  const [draft, setDraft] = React.useState<string | number>(value);
+  React.useEffect(() => {
+    setDraft(value);
+  }, [value]);
+
+  if (!editing) {
+    return (
+      <span
+        className={cn(
+          'inline-flex min-h-6 cursor-text items-center rounded-sm px-1 hover:bg-accent/50',
+          className,
+        )}
+        onDoubleClick={(e) => {
+          e.stopPropagation();
+          setEditing(true);
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        {String(value ?? '')}
+      </span>
+    );
+  }
+
+  return (
+    <input
+      autoFocus
+      type={type}
+      value={draft as string | number}
+      placeholder={placeholder}
+      className={cn(
+        'h-7 w-full rounded-sm border border-border bg-background px-2 text-xs outline-none focus:border-primary',
+        className,
+      )}
+      onChange={(e) =>
+        setDraft(type === 'number' ? Number(e.target.value) : e.target.value)
+      }
+      onBlur={() => {
+        setEditing(false);
+        if (draft !== value) onCommit(draft);
+      }}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') (e.target as HTMLInputElement).blur();
+        if (e.key === 'Escape') {
+          setDraft(value);
+          setEditing(false);
+        }
+      }}
+      onClick={(e) => e.stopPropagation()}
+    />
+  );
+}
+
+// ─── DataTable ──────────────────────────────────────────────────────────────
+
+function DataTable<T = Record<string, unknown>>(props: DataTableProps<T>) {
+  const {
+    columns,
+    data,
+    dataSource,
+    rowKey = 'id' as keyof T,
+    size = 'sm',
+    bordered = false,
+    striped = false,
+    hoverable = true,
+    crossline = false,
+    stickyHeader = false,
+    maxBodyHeight,
+    enableColumnResizing = false,
+    columnSizing: columnSizingProp,
+    onColumnSizingChange,
+    isTree = false,
+    childrenColumnName = 'children',
+    indentSize = 16,
+    virtual = false,
+    estimateRowHeight = 40,
+    virtualOverscan = 8,
+    cellProps,
+    draggable = false,
+    onDragEnd,
+    loading = false,
+    loadingNode,
+    empty,
+    sorting: sortingProp,
+    onSortingChange,
+    columnFilters: columnFiltersProp,
+    onColumnFiltersChange,
+    columnVisibility: columnVisibilityProp,
+    onColumnVisibilityChange,
+    rowSelection: rowSelectionConfig,
+    pagination,
+    expandable,
+    onRow,
+    onRowClick,
+    className,
+    tableClassName,
+    ...rest
+  } = props;
+
+  const finalData = (data ?? dataSource ?? []) as T[];
+
+  // ── Sorting state（受控/非受控）
+  const [innerSorting, setInnerSorting] = React.useState<SortingState>([]);
+  const sorting = sortingProp ?? innerSorting;
+  const handleSortingChange = (updater: React.SetStateAction<SortingState>) => {
+    const next = typeof updater === 'function' ? updater(sorting) : updater;
+    if (sortingProp === undefined) setInnerSorting(next);
+    onSortingChange?.(next);
+  };
+
+  // ── ColumnFilters state（受控/非受控）
+  const [innerFilters, setInnerFilters] = React.useState<ColumnFiltersState>(
+    [],
+  );
+  const columnFilters = columnFiltersProp ?? innerFilters;
+  const handleFiltersChange = (
+    updater: React.SetStateAction<ColumnFiltersState>,
+  ) => {
+    const next =
+      typeof updater === 'function' ? updater(columnFilters) : updater;
+    if (columnFiltersProp === undefined) setInnerFilters(next);
+    onColumnFiltersChange?.(next);
+  };
+
+  // ── ColumnVisibility state（受控/非受控）
+  const [innerVisibility, setInnerVisibility] = React.useState<VisibilityState>(
+    {},
+  );
+  const columnVisibility = columnVisibilityProp ?? innerVisibility;
+  const handleVisibilityChange = (
+    updater: React.SetStateAction<VisibilityState>,
+  ) => {
+    const next =
+      typeof updater === 'function' ? updater(columnVisibility) : updater;
+    if (columnVisibilityProp === undefined) setInnerVisibility(next);
+    onColumnVisibilityChange?.(next);
+  };
+
+  // ── ColumnSizing state（受控/非受控）
+  const [innerSizing, setInnerSizing] = React.useState<Record<string, number>>(
+    {},
+  );
+  const columnSizing = columnSizingProp ?? innerSizing;
+  const handleSizingChange = (
+    updater: React.SetStateAction<Record<string, number>>,
+  ) => {
+    const next =
+      typeof updater === 'function' ? updater(columnSizing) : updater;
+    if (columnSizingProp === undefined) setInnerSizing(next);
+    onColumnSizingChange?.(next);
+  };
+
+  // ── 列 hover 状态（crossline 十字辅助轴）
+  const [hoveredColId, setHoveredColId] = React.useState<string | null>(null);
+
+  // ── RowSelection state
+  const selectionMode = rowSelectionConfig?.mode ?? 'multiple';
+  const [innerSelection, setInnerSelection] = React.useState<RowSelectionState>(
+    () => {
+      const init = rowSelectionConfig?.defaultSelectedRowKeys ?? [];
+      return Object.fromEntries(
+        init.map((k) => [k, true]),
+      ) as RowSelectionState;
+    },
+  );
+  const controlledKeys = rowSelectionConfig?.selectedRowKeys;
+  const rowSelectionState: RowSelectionState = controlledKeys
+    ? (Object.fromEntries(
+        controlledKeys.map((k) => [k, true]),
+      ) as RowSelectionState)
+    : innerSelection;
+
+  const handleRowSelectionChange = (
+    updater: React.SetStateAction<RowSelectionState>,
+  ) => {
+    let next =
+      typeof updater === 'function' ? updater(rowSelectionState) : updater;
+    // 单选模式：保留最后一个被勾选的 row id
+    if (selectionMode === 'single') {
+      const trueKeys = Object.entries(next)
+        .filter(([, v]) => v)
+        .map(([k]) => k);
+      const prevKeys = Object.entries(rowSelectionState)
+        .filter(([, v]) => v)
+        .map(([k]) => k);
+      const newlyAdded = trueKeys.filter((k) => !prevKeys.includes(k));
+      const lastKey = newlyAdded[newlyAdded.length - 1] ?? trueKeys[0];
+      next = lastKey ? { [lastKey]: true } : {};
+    }
+    if (controlledKeys === undefined) setInnerSelection(next);
+    const keys = Object.entries(next)
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+    const records = finalData.filter((r) =>
+      keys.includes(getRowKey(r, rowKey)),
+    );
+    rowSelectionConfig?.onChange?.(keys, records);
+  };
+
+  // ── Expanded state
+  const expandedKeys =
+    expandable?.expandedRowKeys ?? expandable?.defaultExpandedRowKeys;
+  const [innerExpanded, setInnerExpanded] = React.useState<ExpandedState>(
+    () => {
+      const init = expandable?.defaultExpandedRowKeys ?? [];
+      return Object.fromEntries(init.map((k) => [k, true])) as ExpandedState;
+    },
+  );
+  const expandedState: ExpandedState = expandable?.expandedRowKeys
+    ? (Object.fromEntries(
+        expandable.expandedRowKeys.map((k) => [k, true]),
+      ) as ExpandedState)
+    : innerExpanded;
+  void expandedKeys; // keep ref for future use
+  const handleExpandedChange = (
+    updater: React.SetStateAction<ExpandedState>,
+  ) => {
+    const next =
+      typeof updater === 'function' ? updater(expandedState) : updater;
+    if (expandable?.expandedRowKeys === undefined) setInnerExpanded(next);
+    const keys =
+      typeof next === 'object' && next !== null
+        ? Object.entries(next)
+            .filter(([, v]) => v)
+            .map(([k]) => k)
+        : [];
+    expandable?.onChange?.(keys);
+  };
+
+  // ── Pagination state（仅当未受控时使用 TanStack 内部分页）
+  const paginationEnabled = pagination !== false;
+  const isPagObject =
+    paginationEnabled && pagination && typeof pagination === 'object';
+  const pagObj = isPagObject
+    ? (pagination as Exclude<DataTablePagination, false>)
+    : undefined;
+  const [innerPageIndex, setInnerPageIndex] = React.useState(
+    (pagObj?.defaultCurrent ?? 1) - 1,
+  );
+  const [innerPageSize, setInnerPageSize] = React.useState(
+    pagObj?.defaultPageSize ?? 10,
+  );
+  const currentPage =
+    pagObj?.current != null ? pagObj.current : innerPageIndex + 1;
+  const pageSize = pagObj?.pageSize ?? innerPageSize;
+  const totalRecords = pagObj?.total ?? finalData.length;
+
+  // ── Build columns
+  const adaptedColumns = React.useMemo(
+    () => adaptColumns<T>(columns),
+    [columns],
+  );
+
+  const hasLeftFixed = React.useMemo(
+    () =>
+      adaptedColumns.some(
+        (c) =>
+          (c.meta as { fixed?: 'left' | 'right' } | undefined)?.fixed ===
+          'left',
+      ),
+    [adaptedColumns],
+  );
+
+  const tableColumns = React.useMemo<ColumnDef<T, unknown>[]>(() => {
+    const list: ColumnDef<T, unknown>[] = [];
+
+    // selection column
+    if (rowSelectionConfig) {
+      list.push({
+        id: '__selection__',
+        size: 40,
+        enableSorting: false,
+        enableColumnFilter: false,
+        enableResizing: false,
+        meta: hasLeftFixed ? { fixed: 'left' } : {},
+        header: ({ table }) =>
+          selectionMode === 'multiple' ? (
+            <Checkbox
+              aria-label="全选"
+              checked={
+                table.getIsAllPageRowsSelected()
+                  ? true
+                  : table.getIsSomePageRowsSelected()
+                  ? 'indeterminate'
+                  : false
+              }
+              onCheckedChange={(v) =>
+                table.toggleAllPageRowsSelected(v === true)
+              }
+            />
+          ) : null,
+        cell: ({ row }) => {
+          const extra =
+            rowSelectionConfig.getProps?.(row.original, row.index) ?? {};
+          if (selectionMode === 'single') {
+            return (
+              <input
+                type="radio"
+                aria-label="选择行"
+                checked={row.getIsSelected()}
+                onChange={() => row.toggleSelected(true)}
+                onClick={(e) => e.stopPropagation()}
+                className="size-3.5 cursor-pointer accent-primary"
+                {...(extra as React.InputHTMLAttributes<HTMLInputElement>)}
+              />
+            );
+          }
+          return (
+            <Checkbox
+              aria-label="选择行"
+              checked={row.getIsSelected()}
+              onCheckedChange={(v) => row.toggleSelected(v === true)}
+              onClick={(e) => e.stopPropagation()}
+              {...(extra as Partial<React.ComponentProps<typeof Checkbox>>)}
+            />
+          );
+        },
+      });
+    }
+
+    // drag handle column（行拖拽排序时插在最前；锁列存在时跟随 left）
+    if (draggable) {
+      list.push({
+        id: '__drag__',
+        size: 32,
+        enableSorting: false,
+        enableColumnFilter: false,
+        enableResizing: false,
+        meta: hasLeftFixed ? { fixed: 'left' } : {},
+        header: () => null,
+        cell: () => <DragHandleCell />,
+      });
+    }
+
+    // expand column（树形模式下不另起列，在首列 cell 内联展开按钮）
+    if (expandable && !isTree) {
+      list.push({
+        id: '__expand__',
+        size: 40,
+        enableSorting: false,
+        enableColumnFilter: false,
+        enableResizing: false,
+        meta: hasLeftFixed ? { fixed: 'left' } : {},
+        header: () => null,
+        cell: ({ row }) => {
+          const can =
+            expandable.rowExpandable?.(row.original, row.index) ?? true;
+          if (!can) return null;
+          const expanded =
+            typeof expandedState === 'object' && !!expandedState[row.id];
+          return (
+            <button
+              type="button"
+              aria-label={expanded ? '收起' : '展开'}
+              className="inline-flex size-5 cursor-pointer items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+              onClick={(e) => {
+                e.stopPropagation();
+                handleExpandedChange((prev) => {
+                  const o =
+                    typeof prev === 'object' && prev !== null
+                      ? (prev as Record<string, boolean>)
+                      : {};
+                  return { ...o, [row.id]: !o[row.id] } as ExpandedState;
+                });
+              }}
+            >
+              <ChevronRight
+                className={cn(
+                  'size-3.5 transition-transform',
+                  expanded && 'rotate-90',
+                )}
+              />
+            </button>
+          );
+        },
+      });
+    }
+
+    return [...list, ...adaptedColumns];
+  }, [
+    adaptedColumns,
+    rowSelectionConfig,
+    selectionMode,
+    expandable,
+    expandedState,
+    isTree,
+    hasLeftFixed,
+    draggable,
+  ]);
+
+  // ── Build table
+  const table: RTTable<T> = useReactTable({
+    data: finalData,
+    columns: tableColumns,
+    state: {
+      sorting,
+      columnFilters,
+      columnVisibility,
+      rowSelection: rowSelectionState,
+      expanded: expandedState,
+      columnSizing,
+      ...(paginationEnabled
+        ? {
+            pagination: {
+              pageIndex: currentPage - 1,
+              pageSize,
+            },
+          }
+        : {}),
+    },
+    onSortingChange: handleSortingChange,
+    onColumnFiltersChange: handleFiltersChange,
+    onColumnVisibilityChange: handleVisibilityChange,
+    onRowSelectionChange: handleRowSelectionChange,
+    onExpandedChange: handleExpandedChange,
+    onColumnSizingChange: handleSizingChange,
+    enableRowSelection: !!rowSelectionConfig,
+    enableMultiRowSelection: selectionMode === 'multiple',
+    enableExpanding: !!expandable || isTree,
+    enableColumnResizing,
+    columnResizeMode: 'onChange',
+    getRowId: (row) => getRowKey(row, rowKey),
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getExpandedRowModel:
+      expandable || isTree ? getExpandedRowModel() : undefined,
+    ...(isTree
+      ? {
+          getSubRows: (row: T) =>
+            (row as Record<string, unknown>)[childrenColumnName] as
+              | T[]
+              | undefined,
+        }
+      : {}),
+    ...(paginationEnabled
+      ? {
+          getPaginationRowModel: getPaginationRowModel(),
+          manualPagination: pagObj?.total != null,
+          pageCount:
+            pagObj?.total != null
+              ? Math.ceil(pagObj.total / pageSize)
+              : undefined,
+        }
+      : {}),
+  });
+
+  const rows = table.getRowModel().rows;
+  const showEmpty = !loading && rows.length === 0;
+  const colCount = tableColumns.length;
+
+  // ── Sticky 偏移计算（锁列）
+  const leafColumns = table.getVisibleLeafColumns();
+  const stickyOffsets = React.useMemo(() => {
+    const left = new Map<string, number>();
+    const right = new Map<string, number>();
+    let leftAcc = 0;
+    for (const col of leafColumns) {
+      const fixed = (col.columnDef.meta as { fixed?: 'left' | 'right' })?.fixed;
+      if (fixed === 'left') {
+        left.set(col.id, leftAcc);
+        leftAcc += col.getSize();
+      }
+    }
+    let rightAcc = 0;
+    for (const col of [...leafColumns].reverse()) {
+      const fixed = (col.columnDef.meta as { fixed?: 'left' | 'right' })?.fixed;
+      if (fixed === 'right') {
+        right.set(col.id, rightAcc);
+        rightAcc += col.getSize();
+      }
+    }
+    return { left, right };
+  }, [leafColumns, columnSizing]);
+
+  // ── 锁列边界：最后一个 left-fixed / 第一个 right-fixed 加 shadow 区分
+  const lastLeftFixedId = React.useMemo(() => {
+    let id: string | undefined;
+    for (const col of leafColumns) {
+      if (
+        (col.columnDef.meta as { fixed?: 'left' | 'right' })?.fixed === 'left'
+      ) {
+        id = col.id;
+      }
+    }
+    return id;
+  }, [leafColumns]);
+  const firstRightFixedId = React.useMemo(() => {
+    for (const col of leafColumns) {
+      if (
+        (col.columnDef.meta as { fixed?: 'left' | 'right' })?.fixed === 'right'
+      ) {
+        return col.id;
+      }
+    }
+    return undefined;
+  }, [leafColumns]);
+
+  // ── 树形/首数据列 id（跳过锁定的选择 / 展开 / 拖拽列，取首个业务列）
+  const firstDataColId = React.useMemo(() => {
+    return leafColumns.find(
+      (c) =>
+        c.id !== '__selection__' &&
+        c.id !== '__expand__' &&
+        c.id !== '__drag__',
+    )?.id;
+  }, [leafColumns]);
+
+  // ── 滚动容器 ref（虚拟滚动需要）
+  const scrollWrapperRef = React.useRef<HTMLDivElement>(null);
+  const getScrollElement = React.useCallback(() => {
+    return (
+      scrollWrapperRef.current?.querySelector<HTMLElement>(
+        '[data-slot="table-container"]',
+      ) ?? null
+    );
+  }, []);
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement,
+    estimateSize: () => estimateRowHeight,
+    overscan: virtualOverscan,
+    enabled: virtual,
+  });
+  const virtualItems = virtual ? virtualizer.getVirtualItems() : [];
+  const totalSize = virtual ? virtualizer.getTotalSize() : 0;
+  const paddingTop =
+    virtual && virtualItems.length > 0 ? virtualItems[0]!.start : 0;
+  const paddingBottom =
+    virtual && virtualItems.length > 0
+      ? totalSize - virtualItems[virtualItems.length - 1]!.end
+      : 0;
+
+  // ── 拖拽排序 sensors / handler
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 4 } }),
+  );
+  const rowIds = React.useMemo(() => rows.map((r) => r.id), [rows]);
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event;
+    if (!over || active.id === over.id) return;
+    const from = rowIds.indexOf(String(active.id));
+    const to = rowIds.indexOf(String(over.id));
+    if (from < 0 || to < 0) return;
+    const next = [...finalData];
+    const [moved] = next.splice(from, 1);
+    if (moved !== undefined) next.splice(to, 0, moved);
+    onDragEnd?.({ from, to, data: next });
+  };
+
+  // ── 单行渲染 helper（抽出以复用于虚拟滚动 / 拖拽两条路径）
+  const renderCells = (row: RTRow<T>) => {
+    const visibleCells = row.getVisibleCells();
+    const cells: React.ReactNode[] = [];
+    for (let colIdx = 0; colIdx < visibleCells.length; colIdx += 1) {
+      const cell = visibleCells[colIdx]!;
+      const cellMeta = cell.column.columnDef.meta as
+        | {
+            align?: 'left' | 'center' | 'right';
+            fixed?: 'left' | 'right';
+          }
+        | undefined;
+      const colId = cell.column.id;
+
+      // cellProps 合并（快推内部列）
+      let rowSpan: number | undefined;
+      let colSpan: number | undefined;
+      if (
+        cellProps &&
+        colId !== '__selection__' &&
+        colId !== '__expand__' &&
+        colId !== '__drag__'
+      ) {
+        const cp = cellProps(row.index, colIdx, row.original);
+        if (cp) {
+          rowSpan = cp.rowSpan;
+          colSpan = cp.colSpan;
+          if (rowSpan === 0 || colSpan === 0) continue;
+        }
+      }
+
+      const isFixedLeft = cellMeta?.fixed === 'left';
+      const isFixedRight = cellMeta?.fixed === 'right';
+      const isFixed = isFixedLeft || isFixedRight;
+      const cellStyle: React.CSSProperties = {};
+      if (isFixedLeft) {
+        cellStyle.position = 'sticky';
+        cellStyle.left = `${stickyOffsets.left.get(colId) ?? 0}px`;
+        cellStyle.zIndex = 1;
+      }
+      if (isFixedRight) {
+        cellStyle.position = 'sticky';
+        cellStyle.right = `${stickyOffsets.right.get(colId) ?? 0}px`;
+        cellStyle.zIndex = 1;
+      }
+      if (isFixedLeft && colId === lastLeftFixedId) {
+        cellStyle.boxShadow = 'inset -6px 0 6px -6px var(--color-border)';
+      }
+      if (isFixedRight && colId === firstRightFixedId) {
+        cellStyle.boxShadow = 'inset 6px 0 6px -6px var(--color-border)';
+      }
+      const isFirstDataCol = colId === firstDataColId;
+      const treeIndent = isTree && isFirstDataCol ? row.depth * indentSize : 0;
+      if (treeIndent > 0) {
+        cellStyle.paddingLeft = `${12 + treeIndent}px`;
+      }
+      const isColHover = crossline && hoveredColId === colId;
+      const canTreeExpand = isTree && row.subRows && row.subRows.length > 0;
+
+      cells.push(
+        <TableCell
+          key={cell.id}
+          style={cellStyle}
+          rowSpan={rowSpan}
+          colSpan={colSpan}
+          data-fixed={cellMeta?.fixed}
+          data-col-hover={isColHover ? '' : undefined}
+          className={cn(
+            alignClass(cellMeta?.align),
+            isFixed && 'bg-background',
+            isColHover && 'bg-muted/30',
+          )}
+          onMouseEnter={crossline ? () => setHoveredColId(colId) : undefined}
+          onMouseLeave={crossline ? () => setHoveredColId(null) : undefined}
+        >
+          {isTree && isFirstDataCol ? (
+            <span className="inline-flex items-center gap-1.5">
+              {canTreeExpand ? (
+                <button
+                  type="button"
+                  aria-label={row.getIsExpanded() ? '收起' : '展开'}
+                  className="inline-flex size-5 cursor-pointer items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground"
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    row.toggleExpanded();
+                  }}
+                >
+                  <ChevronRight
+                    className={cn(
+                      'size-3.5 transition-transform',
+                      row.getIsExpanded() && 'rotate-90',
+                    )}
+                  />
+                </button>
+              ) : (
+                <span className="inline-block size-5" />
+              )}
+              <span>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </span>
+            </span>
+          ) : (
+            flexRender(cell.column.columnDef.cell, cell.getContext())
+          )}
+        </TableCell>,
+      );
+    }
+    return cells;
+  };
+
+  const renderRow = (row: RTRow<T>) => {
+    const rowMeta = onRow?.(row.original, row.index) ?? {};
+    const isExpanded =
+      !!expandable &&
+      typeof expandedState === 'object' &&
+      !!expandedState[row.id];
+    const handleClick = (e: React.MouseEvent<HTMLTableRowElement>) => {
+      rowMeta.onClick?.(e);
+      onRowClick?.(row.original, row.index, e);
+    };
+    const dataState = row.getIsSelected() ? 'selected' : undefined;
+    return (
+      <React.Fragment key={row.id}>
+        {draggable ? (
+          <SortableRow
+            rowId={row.id}
+            data-state={dataState}
+            {...rowMeta}
+            onClick={handleClick}
+          >
+            {renderCells(row)}
+          </SortableRow>
+        ) : (
+          <TableRow data-state={dataState} {...rowMeta} onClick={handleClick}>
+            {renderCells(row)}
+          </TableRow>
+        )}
+        {isExpanded ? (
+          <TableRow
+            data-slot="data-table-expanded-row"
+            className="bg-muted/20 hover:bg-muted/20"
+          >
+            <TableCell colSpan={colCount} className="whitespace-normal py-3">
+              {expandable!.expandedRowRender(row.original, row.index)}
+            </TableCell>
+          </TableRow>
+        ) : null}
+      </React.Fragment>
+    );
+  };
+
+  // ── 虚拟模式下仅渲染可见行 + 上下 spacer
+  const visibleRows = virtual
+    ? virtualItems
+        .map((vi) => rows[vi.index])
+        .filter((r): r is RTRow<T> => r !== undefined)
+    : rows;
+
+  // 计算所有列的总宽度，作为 table 的 min-width 防止列被拉伸
+  const totalColumnWidth = React.useMemo(() => {
+    let total = 0;
+    let hasWidth = false;
+    for (const col of columns) {
+      const w = col.size ?? col.width;
+      if (typeof w === 'number') {
+        total += w;
+        hasWidth = true;
+      }
+    }
+    return hasWidth ? total : undefined;
+  }, [columns]);
+
+  const tableEl = (
+    <Table
+      size={size}
+      bordered={bordered}
+      striped={striped}
+      hoverable={hoverable}
+      crossline={crossline}
+      stickyHeader={stickyHeader}
+      maxBodyHeight={maxBodyHeight}
+      loading={loading}
+      loadingNode={loadingNode}
+      empty={showEmpty ? empty ?? undefined : undefined}
+      className={tableClassName}
+      style={
+        totalColumnWidth ? { minWidth: `${totalColumnWidth}px` } : undefined
+      }
+    >
+      <TableHeader>
+        {table.getHeaderGroups().map((headerGroup) => (
+          <TableRow key={headerGroup.id}>
+            {headerGroup.headers.map((header) => {
+              const meta = header.column.columnDef.meta as
+                | {
+                    align?: 'left' | 'center' | 'right';
+                    filters?: DataTableFilterOption[];
+                    filterMode?: 'single' | 'multiple';
+                    size?: number | string;
+                    fixed?: 'left' | 'right';
+                    resizable?: boolean;
+                  }
+                | undefined;
+              const canSort = header.column.getCanSort();
+              const sortDir = header.column.getIsSorted();
+              const canFilter =
+                header.column.getCanFilter() && meta?.filters?.length;
+              const canResize =
+                enableColumnResizing &&
+                header.column.getCanResize() &&
+                meta?.resizable !== false;
+              const isFixedLeft = meta?.fixed === 'left';
+              const isFixedRight = meta?.fixed === 'right';
+              const isFixed = isFixedLeft || isFixedRight;
+              const colId = header.column.id;
+              const widthVal =
+                columnSizing[colId] != null
+                  ? header.getSize()
+                  : meta?.size != null
+                  ? typeof meta.size === 'number'
+                    ? meta.size
+                    : meta.size
+                  : isFixed
+                  ? header.getSize()
+                  : undefined;
+              const finalStyle: React.CSSProperties = {};
+              if (widthVal != null) {
+                finalStyle.width =
+                  typeof widthVal === 'number' ? `${widthVal}px` : widthVal;
+              }
+              if (header.colSpan > 1) {
+                // 多级表头：父 group 跨列
+              }
+              if (isFixedLeft) {
+                finalStyle.position = 'sticky';
+                finalStyle.left = `${stickyOffsets.left.get(colId) ?? 0}px`;
+                finalStyle.zIndex = 11;
+                if (colId === lastLeftFixedId) {
+                  finalStyle.boxShadow =
+                    'inset -6px 0 6px -6px var(--color-border)';
+                }
+              }
+              if (isFixedRight) {
+                finalStyle.position = 'sticky';
+                finalStyle.right = `${stickyOffsets.right.get(colId) ?? 0}px`;
+                finalStyle.zIndex = 11;
+                if (colId === firstRightFixedId) {
+                  finalStyle.boxShadow =
+                    'inset 6px 0 6px -6px var(--color-border)';
+                }
+              }
+              const isColHover = crossline && hoveredColId === colId;
+              return (
+                <TableHead
+                  key={header.id}
+                  style={finalStyle}
+                  colSpan={header.colSpan > 1 ? header.colSpan : undefined}
+                  data-fixed={meta?.fixed}
+                  data-col-hover={isColHover ? '' : undefined}
+                  className={cn(
+                    alignClass(meta?.align),
+                    canSort && 'cursor-pointer select-none',
+                    canResize && 'relative',
+                    isFixed && 'bg-panel',
+                    isColHover && 'bg-muted/30',
+                    header.colSpan > 1 && 'text-center',
+                  )}
+                  onClick={
+                    canSort
+                      ? header.column.getToggleSortingHandler()
+                      : undefined
+                  }
+                  onMouseEnter={
+                    crossline ? () => setHoveredColId(colId) : undefined
+                  }
+                  onMouseLeave={
+                    crossline ? () => setHoveredColId(null) : undefined
+                  }
+                >
+                  <span className="inline-flex items-center gap-1.5">
+                    {header.isPlaceholder
+                      ? null
+                      : flexRender(
+                          header.column.columnDef.header,
+                          header.getContext(),
+                        )}
+                    {canSort ? (
+                      <span className="inline-flex size-4 items-center justify-center text-muted-foreground">
+                        {sortDir === 'asc' ? (
+                          <ArrowUp className="size-3 text-foreground" />
+                        ) : sortDir === 'desc' ? (
+                          <ArrowDown className="size-3 text-foreground" />
+                        ) : (
+                          <ArrowUpDown className="size-3 opacity-60" />
+                        )}
+                      </span>
+                    ) : null}
+                    {canFilter ? (
+                      <ColumnFilterPopover
+                        options={meta!.filters!}
+                        mode={meta?.filterMode ?? 'multiple'}
+                        value={header.column.getFilterValue()}
+                        onChange={(v) => header.column.setFilterValue(v)}
+                      />
+                    ) : null}
+                  </span>
+                  {canResize ? (
+                    <span
+                      role="separator"
+                      aria-orientation="vertical"
+                      aria-label="拖拽调整列宽"
+                      onMouseDown={header.getResizeHandler()}
+                      onTouchStart={header.getResizeHandler()}
+                      onClick={(e) => e.stopPropagation()}
+                      className={cn(
+                        'absolute right-0 top-0 z-10 h-full w-1 cursor-col-resize touch-none select-none bg-transparent transition-colors hover:bg-primary/40',
+                        header.column.getIsResizing() && 'bg-primary',
+                      )}
+                    />
+                  ) : null}
+                </TableHead>
+              );
+            })}
+          </TableRow>
+        ))}
+      </TableHeader>
+      <TableBody>
+        {virtual && paddingTop > 0 ? (
+          <tr aria-hidden style={{ height: `${paddingTop}px` }}>
+            <td colSpan={colCount} />
+          </tr>
+        ) : null}
+        {visibleRows.map((row) => renderRow(row))}
+        {virtual && paddingBottom > 0 ? (
+          <tr aria-hidden style={{ height: `${paddingBottom}px` }}>
+            <td colSpan={colCount} />
+          </tr>
+        ) : null}
+      </TableBody>
+    </Table>
+  );
+
+  const tableContent = draggable ? (
+    <DndContext
+      sensors={sensors}
+      collisionDetection={closestCenter}
+      onDragEnd={handleDragEnd}
+    >
+      <SortableContext items={rowIds} strategy={verticalListSortingStrategy}>
+        {tableEl}
+      </SortableContext>
+    </DndContext>
+  ) : (
+    tableEl
+  );
+
+  return (
+    <div
+      ref={scrollWrapperRef}
+      data-slot="data-table"
+      className={cn('flex w-full flex-col gap-3', className)}
+      {...rest}
+    >
+      {tableContent}
+
+      {paginationEnabled && totalRecords > 0 ? (
+        <div className="flex items-center justify-end">
+          <Pagination
+            current={currentPage}
+            total={totalRecords}
+            pageSize={pageSize}
+            pageSizeOptions={pagObj?.pageSizeOptions}
+            showSizeChanger={pagObj?.showSizeChanger}
+            showTotal={pagObj?.showTotal ?? true}
+            onChange={(page, ps) => {
+              if (pagObj?.current === undefined) setInnerPageIndex(page - 1);
+              if (pagObj?.pageSize === undefined) setInnerPageSize(ps);
+              pagObj?.onChange?.(page, ps);
+            }}
+          />
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export { DataTable, EditableCell };