lynote-ui 0.0.8 → 0.0.10

package/dist/switch/index.js

@@ -1,7 +1,7 @@
 "use client";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-require("../chunk-CoQrYLCe.js");
-const require_utils = require("../utils-BGuEr0aP.js");
+require("../chunk-8l464Juk.js");
+const require_utils = require("../utils-DrngEK1K.js");
 let react_jsx_runtime = require("react/jsx-runtime");
 let _base_ui_react_switch = require("@base-ui/react/switch");
 //#region src/switch/index.tsx

package/dist/switch/index.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { t as cn } from "../utils-TtTqRIUX.mjs";
+import { t as cn } from "../utils-Bg4z4cXr.mjs";
 import { jsx } from "react/jsx-runtime";
 import { Switch as Switch$1 } from "@base-ui/react/switch";
 //#region src/switch/index.tsx

package/dist/table/components/base-table.d.ts

@@ -0,0 +1,10 @@
+import * as React from "react";
+declare function Table({ className, ...props }: React.ComponentProps<"table">): import("react/jsx-runtime").JSX.Element;
+declare function TableHeader({ className, ...props }: React.ComponentProps<"thead">): import("react/jsx-runtime").JSX.Element;
+declare function TableBody({ className, ...props }: React.ComponentProps<"tbody">): import("react/jsx-runtime").JSX.Element;
+declare function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">): import("react/jsx-runtime").JSX.Element;
+declare function TableRow({ className, ...props }: React.ComponentProps<"tr">): import("react/jsx-runtime").JSX.Element;
+declare function TableHead({ className, ...props }: React.ComponentProps<"th">): import("react/jsx-runtime").JSX.Element;
+declare function TableCell({ className, ...props }: React.ComponentProps<"td">): import("react/jsx-runtime").JSX.Element;
+declare function TableCaption({ className, ...props }: React.ComponentProps<"caption">): import("react/jsx-runtime").JSX.Element;
+export { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, };

package/dist/table/components/data-table-column-header.d.ts

@@ -0,0 +1,12 @@
+import { Header } from '@tanstack/react-table';
+import { ScrollShadowState } from '../type';
+type DataTableColumnHeaderProps<TData> = {
+    header: Header<TData, unknown>;
+    resizable?: boolean;
+    scrollShadow: ScrollShadowState;
+};
+/**
+ * 表头单元格,封装排序、列宽拖拽、固定列阴影
+ */
+export declare function DataTableColumnHeader<TData>({ header, resizable, scrollShadow, }: DataTableColumnHeaderProps<TData>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/table/components/data-table-pagination.d.ts

@@ -0,0 +1,12 @@
+import { Table as TanstackTable } from '@tanstack/react-table';
+type DataTablePaginationProps<TData> = {
+    table: TanstackTable<TData>;
+    pageSizeOptions?: number[];
+    /** 是否显示已选择行数,默认 true */
+    showSelectionCount?: boolean;
+};
+/**
+ * 表格分页栏:总行数 / 每页数量 / 页码跳转
+ */
+export declare function DataTablePagination<TData>({ table, pageSizeOptions, showSelectionCount, }: DataTablePaginationProps<TData>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/table/components/data-table-toolbar.d.ts

@@ -0,0 +1,23 @@
+import { Table as TanstackTable } from '@tanstack/react-table';
+import { ReactNode } from 'react';
+type DataTableToolbarProps<TData> = {
+    table: TanstackTable<TData>;
+    /** 绑定搜索输入框的列 id;留空则使用全局过滤 */
+    searchColumnId?: string;
+    /** 输入框 placeholder */
+    searchPlaceholder?: string;
+    /** 是否展示视图配置(列显隐),默认 true */
+    showViewOptions?: boolean;
+    /** 是否启用列拖拽 */
+    enableColumnOrdering?: boolean;
+    /** 是否启用列固定 */
+    enableColumnPinning?: boolean;
+    /** 工具栏右侧追加内容 */
+    extra?: ReactNode;
+    className?: string;
+};
+/**
+ * 表格工具栏:搜索 + 视图配置 + 自定义扩展
+ */
+export declare function DataTableToolbar<TData>({ table, searchColumnId, searchPlaceholder, showViewOptions, enableColumnOrdering, enableColumnPinning, extra, className, }: DataTableToolbarProps<TData>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/table/components/data-table-view-options.d.ts

@@ -0,0 +1,18 @@
+import { Table as TanstackTable } from '@tanstack/react-table';
+import { ReactElement } from 'react';
+type DataTableViewOptionsProps<TData> = {
+    table: TanstackTable<TData>;
+    /** 是否允许列拖拽排序,默认 false */
+    enableOrdering?: boolean;
+    /** 是否允许列固定操作,默认 false */
+    enablePinning?: boolean;
+    /** 触发按钮自定义,默认 "视图" */
+    trigger?: ReactElement;
+};
+/**
+ * 列显隐 / 排序 / 固定 设置面板
+ *
+ * 通过 DropdownMenu 弹出列表,内置 DnD-Kit 排序与固定按钮
+ */
+export declare function DataTableViewOptions<TData>({ table, enableOrdering, enablePinning, trigger, }: DataTableViewOptionsProps<TData>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/table/components/data-table-virtual-body.d.ts

@@ -0,0 +1,19 @@
+import { Table as TanstackTable } from '@tanstack/react-table';
+import { ReactNode } from 'react';
+import { DataTableVirtualOptions } from '../type';
+type DataTableVirtualBodyProps<TData> = {
+    table: TanstackTable<TData>;
+    loading?: boolean;
+    empty?: ReactNode;
+    options?: DataTableVirtualOptions;
+    /** 是否显示纵向边框 */
+    bordered?: boolean;
+    className?: string;
+};
+/**
+ * 行虚拟滚动表格:使用 grid 布局 + `useVirtualizer` 仅渲染可视区域
+ *
+ * 因表格采用 grid 布局,固定列 / 多级表头暂不支持
+ */
+export declare function DataTableVirtualBody<TData>({ table, loading, empty, options, bordered, className, }: DataTableVirtualBodyProps<TData>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/table/components/data-table.d.ts

@@ -0,0 +1,15 @@
+import { Table as TanstackTable } from '@tanstack/react-table';
+import { ReactElement, RefAttributes } from 'react';
+import { DataTablePropsType } from '../type';
+/**
+ * DataTable 暴露给 ref 的命令式 handle —— 就是底层 TanStack table 实例
+ *
+ * 通过 `ref` 即可拿到完整的 TanStack `table` API:`setPageIndex`、`getSelectedRowModel`、
+ * `resetSorting`、`getState` 等。配合受控状态使用更顺手
+ */
+export type DataTableHandle<TData> = TanstackTable<TData>;
+/**
+ * forwardRef 包装,泛型用 cast 保留 —— 否则会被 forwardRef 的签名擦除成 unknown
+ */
+declare const DataTable: <TData, TValue = unknown>(props: DataTablePropsType<TData, TValue> & RefAttributes<DataTableHandle<TData>>) => ReactElement | null;
+export { DataTable };

package/dist/table/components/row-drag-handle.d.ts

@@ -0,0 +1,16 @@
+import { DraggableAttributes, DraggableSyntheticListeners } from '@dnd-kit/core';
+import { ComponentProps, Ref, Context } from 'react';
+/**
+ * SortableRow 通过此 context 向其内部 cell 暴露 dnd-kit 的激活器/监听器
+ *
+ * 用 context 而非 prop 钻透,因为 cell 是用户自定义渲染函数,触不到 SortableRow 的局部变量
+ */
+export type RowDragHandleContextValue = {
+    attributes: DraggableAttributes;
+    listeners: DraggableSyntheticListeners | undefined;
+    setActivatorNodeRef: Ref<HTMLElement>;
+    isDragging: boolean;
+} | null;
+export declare const RowDragHandleContext: Context<RowDragHandleContextValue>;
+/** 在 cell 内任意位置放此组件即可成为行拖拽手柄 */
+export declare function RowDragHandle({ className, ...props }: Omit<ComponentProps<"button">, "ref" | "onMouseDown" | "onKeyDown" | "onTouchStart">): import("react/jsx-runtime").JSX.Element | null;

package/dist/table/components/row-expand-toggle.d.ts

@@ -0,0 +1,21 @@
+import { Row } from '@tanstack/react-table';
+import { ComponentProps } from 'react';
+type RowExpandTogglePropsType<TData> = Omit<ComponentProps<"button">, "onClick" | "children"> & {
+    /** 当前行实例 */
+    row: Row<TData>;
+    /**
+     * 嵌套树场景下,每层缩进的像素数;设为 0 关闭自动缩进
+     *
+     * 默认 16,即每深一层缩进 16px
+     */
+    indent?: number;
+    /** 当行无可展开子项时是否仍占位渲染(保持对齐),默认 true */
+    placeholder?: boolean;
+};
+/**
+ * 行展开切换按钮:基于 `row.getToggleExpandedHandler` + `row.depth` 自动缩进
+ *
+ * 配合 `features.expanding` 与 `tableOptions.getSubRows`(嵌套树),或 `expandedRowRender`(展开面板)使用
+ */
+export declare function RowExpandToggle<TData>({ row, indent, placeholder, className, ...props }: RowExpandTogglePropsType<TData>): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/table/hooks/use-data-table.d.ts

@@ -0,0 +1,44 @@
+import { TableOptions, Table } from '@tanstack/react-table';
+import { DataTableColumn, DataTableFeatures, DataTableState, DataTableStateHandlers, ScrollShadowState } from '../type';
+type UseDataTableOptions<TData, TValue> = {
+    data: TData[];
+    columns: DataTableColumn<TData, TValue>[];
+    features?: DataTableFeatures;
+    state?: DataTableState;
+    initialState?: DataTableState;
+    onStateChange?: DataTableStateHandlers;
+    /**
+     * 透传至底层 useReactTable 的额外配置,会与内部配置浅合并
+     *
+     * 常用于服务端模式:`manualPagination` / `pageCount` / `rowCount` /
+     * `manualSorting` / `manualFiltering`,以及 `meta` 等
+     */
+    tableOptions?: Partial<TableOptions<TData>>;
+};
+/**
+ * 构造 TanStack 表格实例,并按需开启各项功能
+ */
+export declare function useDataTable<TData, TValue = unknown>({ data, columns, features, state, initialState, onStateChange, tableOptions, }: UseDataTableOptions<TData, TValue>): {
+    table: Table<TData>;
+    features: {
+        sorting: boolean;
+        multiSort: boolean;
+        filtering: boolean;
+        globalFilter: boolean;
+        pagination: boolean;
+        rowSelection: boolean;
+        columnVisibility: boolean;
+        columnOrdering: boolean;
+        columnPinning: boolean;
+        columnResizing: boolean;
+        rowDnd: boolean;
+        expanding: boolean;
+    };
+};
+/**
+ * 监听容器横向滚动,返回左右阴影显示状态
+ *
+ * 用于固定列阴影提示
+ */
+export declare function useScrollShadow(wrapperRef: React.RefObject<HTMLElement | null>, containerSelector?: string): ScrollShadowState;
+export {};

package/dist/table/index.d.ts

@@ -1,10 +1,13 @@
-import * as React from "react";
-declare function Table({ className, ...props }: React.ComponentProps<"table">): import("react/jsx-runtime").JSX.Element;
-declare function TableHeader({ className, ...props }: React.ComponentProps<"thead">): import("react/jsx-runtime").JSX.Element;
-declare function TableBody({ className, ...props }: React.ComponentProps<"tbody">): import("react/jsx-runtime").JSX.Element;
-declare function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">): import("react/jsx-runtime").JSX.Element;
-declare function TableRow({ className, ...props }: React.ComponentProps<"tr">): import("react/jsx-runtime").JSX.Element;
-declare function TableHead({ className, ...props }: React.ComponentProps<"th">): import("react/jsx-runtime").JSX.Element;
-declare function TableCell({ className, ...props }: React.ComponentProps<"td">): import("react/jsx-runtime").JSX.Element;
-declare function TableCaption({ className, ...props }: React.ComponentProps<"caption">): import("react/jsx-runtime").JSX.Element;
-export { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, };
+export * from './components/base-table';
+export { DataTable, type DataTableHandle } from './components/data-table';
+export { DataTableColumnHeader } from './components/data-table-column-header';
+export { DataTablePagination } from './components/data-table-pagination';
+export { DataTableToolbar } from './components/data-table-toolbar';
+export { DataTableViewOptions } from './components/data-table-view-options';
+export { DataTableVirtualBody } from './components/data-table-virtual-body';
+export { RowDragHandle, RowDragHandleContext, type RowDragHandleContextValue, } from './components/row-drag-handle';
+export { RowExpandToggle } from './components/row-expand-toggle';
+export { useDataTable, useScrollShadow } from './hooks/use-data-table';
+export type { AnyColumn, CellMergeMeta, ColSpanContext, DataTableColumn, DataTableFeatures, DataTablePropsType, DataTableState, DataTableStateHandlers, DataTableVirtualOptions, RowOrderChangeInfo, RowSpanContext, ScrollShadowState, } from './type';
+export { computeCellSpans, getColumnPinningClassName, getCommonPinningStyles, panelIdFor, } from './utils';
+export type { CellSpan, CellSpanMap } from './utils';

package/dist/table/index.js

@@ -1,79 +1,25 @@
-"use client";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_chunk = require("../chunk-CoQrYLCe.js");
-const require_utils = require("../utils-BGuEr0aP.js");
-let react_jsx_runtime = require("react/jsx-runtime");
-let react = require("react");
-react = require_chunk.__toESM(react);
-//#region src/table/index.tsx
-function Table({ className, ...props }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-		"data-slot": "table-container",
-		className: "relative w-full overflow-x-auto",
-		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("table", {
-			"data-slot": "table",
-			className: require_utils.cn("w-full caption-bottom text-sm", className),
-			...props
-		})
-	});
-}
-function TableHeader({ className, ...props }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("thead", {
-		"data-slot": "table-header",
-		className: require_utils.cn("[&_tr]:border-b", className),
-		...props
-	});
-}
-function TableBody({ className, ...props }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("tbody", {
-		"data-slot": "table-body",
-		className: require_utils.cn("[&_tr:last-child]:border-0", className),
-		...props
-	});
-}
-function TableFooter({ className, ...props }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("tfoot", {
-		"data-slot": "table-footer",
-		className: require_utils.cn("bg-muted/50 border-t font-medium [&>tr]:last:border-b-0", className),
-		...props
-	});
-}
-function TableRow({ className, ...props }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("tr", {
-		"data-slot": "table-row",
-		className: require_utils.cn("hover:bg-muted/50 data-[state=selected]:bg-muted border-b transition-colors", className),
-		...props
-	});
-}
-function TableHead({ className, ...props }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("th", {
-		"data-slot": "table-head",
-		className: require_utils.cn("text-foreground h-10 whitespace-nowrap px-2 text-left align-middle font-medium [&:has([role=checkbox])]:pr-0", className),
-		...props
-	});
-}
-function TableCell({ className, ...props }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("td", {
-		"data-slot": "table-cell",
-		className: require_utils.cn("whitespace-nowrap p-2 align-middle [&:has([role=checkbox])]:pr-0", className),
-		...props
-	});
-}
-function TableCaption({ className, ...props }) {
-	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("caption", {
-		"data-slot": "table-caption",
-		className: require_utils.cn("text-muted-foreground mt-4 text-sm", className),
-		...props
-	});
-}
-//#endregion
-exports.Table = Table;
-exports.TableBody = TableBody;
-exports.TableCaption = TableCaption;
-exports.TableCell = TableCell;
-exports.TableFooter = TableFooter;
-exports.TableHead = TableHead;
-exports.TableHeader = TableHeader;
-exports.TableRow = TableRow;
-
-//# sourceMappingURL=index.js.map
+const require_table = require("../table-FocfdaF7.js");
+exports.DataTable = require_table.DataTable;
+exports.DataTableColumnHeader = require_table.DataTableColumnHeader;
+exports.DataTablePagination = require_table.DataTablePagination;
+exports.DataTableToolbar = require_table.DataTableToolbar;
+exports.DataTableViewOptions = require_table.DataTableViewOptions;
+exports.DataTableVirtualBody = require_table.DataTableVirtualBody;
+exports.RowDragHandle = require_table.RowDragHandle;
+exports.RowDragHandleContext = require_table.RowDragHandleContext;
+exports.RowExpandToggle = require_table.RowExpandToggle;
+exports.Table = require_table.Table;
+exports.TableBody = require_table.TableBody;
+exports.TableCaption = require_table.TableCaption;
+exports.TableCell = require_table.TableCell;
+exports.TableFooter = require_table.TableFooter;
+exports.TableHead = require_table.TableHead;
+exports.TableHeader = require_table.TableHeader;
+exports.TableRow = require_table.TableRow;
+exports.computeCellSpans = require_table.computeCellSpans;
+exports.getColumnPinningClassName = require_table.getColumnPinningClassName;
+exports.getCommonPinningStyles = require_table.getCommonPinningStyles;
+exports.panelIdFor = require_table.panelIdFor;
+exports.useDataTable = require_table.useDataTable;
+exports.useScrollShadow = require_table.useScrollShadow;

package/dist/table/index.mjs

@@ -1,69 +1,2 @@
-"use client";
-import { t as cn } from "../utils-TtTqRIUX.mjs";
-import { jsx } from "react/jsx-runtime";
-import "react";
-//#region src/table/index.tsx
-function Table({ className, ...props }) {
-	return /* @__PURE__ */ jsx("div", {
-		"data-slot": "table-container",
-		className: "relative w-full overflow-x-auto",
-		children: /* @__PURE__ */ jsx("table", {
-			"data-slot": "table",
-			className: cn("w-full caption-bottom text-sm", className),
-			...props
-		})
-	});
-}
-function TableHeader({ className, ...props }) {
-	return /* @__PURE__ */ jsx("thead", {
-		"data-slot": "table-header",
-		className: cn("[&_tr]:border-b", className),
-		...props
-	});
-}
-function TableBody({ className, ...props }) {
-	return /* @__PURE__ */ jsx("tbody", {
-		"data-slot": "table-body",
-		className: cn("[&_tr:last-child]:border-0", className),
-		...props
-	});
-}
-function TableFooter({ className, ...props }) {
-	return /* @__PURE__ */ jsx("tfoot", {
-		"data-slot": "table-footer",
-		className: cn("bg-muted/50 border-t font-medium [&>tr]:last:border-b-0", className),
-		...props
-	});
-}
-function TableRow({ className, ...props }) {
-	return /* @__PURE__ */ jsx("tr", {
-		"data-slot": "table-row",
-		className: cn("hover:bg-muted/50 data-[state=selected]:bg-muted border-b transition-colors", className),
-		...props
-	});
-}
-function TableHead({ className, ...props }) {
-	return /* @__PURE__ */ jsx("th", {
-		"data-slot": "table-head",
-		className: cn("text-foreground h-10 whitespace-nowrap px-2 text-left align-middle font-medium [&:has([role=checkbox])]:pr-0", className),
-		...props
-	});
-}
-function TableCell({ className, ...props }) {
-	return /* @__PURE__ */ jsx("td", {
-		"data-slot": "table-cell",
-		className: cn("whitespace-nowrap p-2 align-middle [&:has([role=checkbox])]:pr-0", className),
-		...props
-	});
-}
-function TableCaption({ className, ...props }) {
-	return /* @__PURE__ */ jsx("caption", {
-		"data-slot": "table-caption",
-		className: cn("text-muted-foreground mt-4 text-sm", className),
-		...props
-	});
-}
-//#endregion
-export { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow };
-
-//# sourceMappingURL=index.mjs.map
+import { C as TableRow, S as TableHeader, _ as TableBody, a as RowDragHandle, b as TableFooter, c as DataTablePagination, d as getColumnPinningClassName, f as getCommonPinningStyles, g as Table, h as useScrollShadow, i as DataTable, l as DataTableColumnHeader, m as useDataTable, n as DataTableToolbar, o as RowDragHandleContext, p as panelIdFor, r as DataTableViewOptions, s as DataTableVirtualBody, t as RowExpandToggle, u as computeCellSpans, v as TableCaption, x as TableHead, y as TableCell } from "../table-BA2BijtZ.mjs";
+export { DataTable, DataTableColumnHeader, DataTablePagination, DataTableToolbar, DataTableViewOptions, DataTableVirtualBody, RowDragHandle, RowDragHandleContext, RowExpandToggle, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, computeCellSpans, getColumnPinningClassName, getCommonPinningStyles, panelIdFor, useDataTable, useScrollShadow };

package/dist/table/type.d.ts

@@ -0,0 +1,198 @@
+import { Column, ColumnDef, ColumnFiltersState, ColumnOrderState, ColumnPinningState, ExpandedState, PaginationState, Row, RowData, RowSelectionState, SortingState, TableOptions, Table as TanstackTable, VisibilityState } from '@tanstack/react-table';
+import { ReactNode } from 'react';
+/** 行合并回调上下文 */
+export type RowSpanContext<TData> = {
+    row: Row<TData>;
+    rows: Row<TData>[];
+    rowIndex: number;
+    value: unknown;
+};
+/** 列合并回调上下文 */
+export type ColSpanContext<TData> = {
+    row: Row<TData>;
+    rows: Row<TData>[];
+    rowIndex: number;
+    column: Column<TData, unknown>;
+};
+/**
+ * 通过 `column.meta` 在 DataTable 中描述单元格合并行为
+ *
+ * - `rowSpan: true`(等同 `"auto"`):自动合并连续相同值
+ * - `rowSpan: (ctx) => number`:返回 rowSpan,`0` 表示该格不渲染
+ * - `rowSpanParent`:仅当父字段同时相同才允许合并(如 city 在同 region 下才合并)
+ * - `colSpan: (ctx) => number`:返回 colSpan,`0` 表示该格不渲染
+ */
+export type CellMergeMeta<TData = RowData> = {
+    rowSpan?: true | "auto" | ((ctx: RowSpanContext<TData>) => number);
+    rowSpanParent?: string;
+    colSpan?: (ctx: ColSpanContext<TData>) => number;
+};
+declare module "@tanstack/react-table" {
+    interface ColumnMeta<TData extends RowData, TValue> extends CellMergeMeta<TData> {
+    }
+}
+/**
+ * 表格容器横向滚动阴影状态
+ */
+export type ScrollShadowState = {
+    left: boolean;
+    right: boolean;
+};
+/**
+ * 列配置,扩展 TanStack ColumnDef
+ */
+export type DataTableColumn<TData, TValue = unknown> = ColumnDef<TData, TValue>;
+/**
+ * 受控状态,所有字段均可选
+ */
+export type DataTableState = {
+    sorting?: SortingState;
+    columnFilters?: ColumnFiltersState;
+    columnVisibility?: VisibilityState;
+    columnOrder?: ColumnOrderState;
+    columnPinning?: ColumnPinningState;
+    rowSelection?: RowSelectionState;
+    pagination?: PaginationState;
+    globalFilter?: string;
+    expanded?: ExpandedState;
+};
+/**
+ * 状态变更回调集合
+ */
+export type DataTableStateHandlers = {
+    onSortingChange?: (state: SortingState) => void;
+    onColumnFiltersChange?: (state: ColumnFiltersState) => void;
+    onColumnVisibilityChange?: (state: VisibilityState) => void;
+    onColumnOrderChange?: (state: ColumnOrderState) => void;
+    onColumnPinningChange?: (state: ColumnPinningState) => void;
+    onRowSelectionChange?: (state: RowSelectionState) => void;
+    onPaginationChange?: (state: PaginationState) => void;
+    onGlobalFilterChange?: (state: string) => void;
+    onExpandedChange?: (state: ExpandedState) => void;
+};
+/**
+ * 各能力开关 + 初始值
+ */
+export type DataTableFeatures = {
+    /** 是否启用排序,默认 true */
+    sorting?: boolean;
+    /** 是否启用多列同时排序,默认 false */
+    multiSort?: boolean;
+    /** 是否启用列筛选,默认 true */
+    filtering?: boolean;
+    /** 是否启用全局搜索,默认 false */
+    globalFilter?: boolean;
+    /** 是否启用分页,默认 true */
+    pagination?: boolean;
+    /** 是否启用行选择(多选),默认 false */
+    rowSelection?: boolean;
+    /** 是否启用列显隐控制,默认 true */
+    columnVisibility?: boolean;
+    /** 是否启用列拖拽排序,默认 false */
+    columnOrdering?: boolean;
+    /** 是否启用列固定(冻结),默认 false */
+    columnPinning?: boolean;
+    /** 是否启用列宽调整,默认 false */
+    columnResizing?: boolean;
+    /**
+     * 是否启用行拖拽排序,默认 false
+     *
+     * 开启后会在最左侧自动插入一列拖拽手柄;也可手动在自己的 cell 里放 `<RowDragHandle />`。
+     * 需要传 `tableOptions.getRowId` 提供稳定的行标识,并在 `onRowOrderChange` 中接住新顺序。
+     * 与 `virtual` 不兼容
+     */
+    rowDnd?: boolean;
+    /**
+     * 是否启用行展开,默认 false
+     *
+     * 嵌套树:在 `tableOptions.getSubRows` 中返回子行,即可在 cell 里用 `<RowExpandToggle row={row} />` 展开。
+     * 展开面板:传 `expandedRowRender` 在每行下方渲染自定义面板。
+     * 开启 `virtual` 时会被自动忽略
+     */
+    expanding?: boolean;
+};
+/** 行拖拽完成后的回调 */
+export type RowOrderChangeInfo = {
+    oldIndex: number;
+    newIndex: number;
+    activeId: string;
+    overId: string;
+};
+/**
+ * 行虚拟滚动配置
+ */
+export type DataTableVirtualOptions = {
+    /** 估计的行高(px),默认 36 */
+    estimateRowHeight?: number;
+    /** 滚动容器高度,默认 480 */
+    maxHeight?: number | string;
+    /** 视口外预渲染行数,默认 10 */
+    overscan?: number;
+};
+/**
+ * DataTable 顶层属性
+ */
+export type DataTablePropsType<TData, TValue = unknown> = {
+    /** 列定义 */
+    columns: DataTableColumn<TData, TValue>[];
+    /** 数据源 */
+    data: TData[];
+    /** 加载状态,显示占位条 */
+    loading?: boolean;
+    /** 受控状态 */
+    state?: DataTableState;
+    /** 初始状态(非受控) */
+    initialState?: DataTableState;
+    /** 状态变更回调 */
+    onStateChange?: DataTableStateHandlers;
+    /** 功能开关 */
+    features?: DataTableFeatures;
+    /**
+     * 工具栏渲染函数,接收 table 实例;不传则不渲染工具栏
+     *
+     * 搜索 / 视图设置等控件请在此函数中用 `DataTableToolbar` / `DataTableViewOptions` 自由组合
+     */
+    renderToolbar?: (table: TanstackTable<TData>) => ReactNode;
+    /** 自定义分页区域 */
+    renderPagination?: (table: TanstackTable<TData>) => ReactNode;
+    /** 空状态文本或节点 */
+    empty?: ReactNode;
+    /** 每页可选数量,默认 [10, 20, 30, 50, 100] */
+    pageSizeOptions?: number[];
+    /** 外层 className */
+    className?: string;
+    /** 表格容器 className */
+    tableClassName?: string;
+    /** 是否显示纵向边框(单元格分隔线),默认 `false` */
+    bordered?: boolean;
+    /** 行点击回调 */
+    onRowClick?: (row: TData) => void;
+    /** 行拖拽完成后回调,接收重排后的完整数据 */
+    onRowOrderChange?: (nextData: TData[], info: RowOrderChangeInfo) => void;
+    /**
+     * 自定义展开面板渲染;返回任意节点会在该行下方渲染一行,跨满所有列
+     *
+     * - 需要将 `features.expanding` 设为 true 才会生效
+     * - 未自定义 `tableOptions.getRowCanExpand` 时会自动注入 `() => true`,所有行均可展开
+     * - 开启 `virtual` 时会被自动忽略
+     */
+    expandedRowRender?: (row: Row<TData>) => ReactNode;
+    /**
+     * 行 DnD 拖拽手柄安放方式,默认 `"auto"` 自动在最左侧追加一列
+     *
+     * 设为 `"manual"` 则不追加,需要用户在自己的列里放 `<RowDragHandle />`
+     */
+    rowDndHandle?: "auto" | "manual";
+    /** 透传至底层 useReactTable 的额外配置(服务端模式 / meta 等) */
+    tableOptions?: Partial<TableOptions<TData>>;
+    /**
+     * 行虚拟滚动:`true` 启用默认配置;传对象自定义
+     *
+     * 开启后会自动关闭分页;列固定与多级表头暂不兼容
+     */
+    virtual?: boolean | DataTableVirtualOptions;
+};
+/**
+ * 列固定 / 拖拽辅助类型
+ */
+export type AnyColumn<TData> = Column<TData, unknown>;

package/dist/table/utils.d.ts

@@ -0,0 +1,31 @@
+import { Row } from '@tanstack/react-table';
+import { CSSProperties } from 'react';
+import { AnyColumn, ScrollShadowState } from './type';
+/**
+ * 展开面板 row 的 DOM id 协议
+ *
+ * `DataTable` 渲染面板 row 时把这个 id 设到 `<tr id>` 上,
+ * `RowExpandToggle` 把它写进按钮的 `aria-controls`,二者必须保持一致
+ */
+export declare const panelIdFor: (rowId: string) => string;
+/**
+ * 计算固定列(sticky)需要的样式
+ */
+export declare function getCommonPinningStyles<TData>(column: AnyColumn<TData>): CSSProperties;
+/**
+ * 计算固定列阴影 className
+ */
+export declare function getColumnPinningClassName<TData>(column: AnyColumn<TData>, scrollShadow: ScrollShadowState): string;
+/** 单元格合并跨度 */
+export type CellSpan = {
+    rowSpan: number;
+    colSpan: number;
+};
+/** 内部存储:每行每列对应的跨度 */
+export type CellSpanMap = Map<number, Map<string, CellSpan>>;
+/**
+ * 根据每列 `meta.rowSpan` / `meta.colSpan` 计算每行每列的合并跨度
+ *
+ * `0` 表示该单元格不应渲染(被合并掉了)
+ */
+export declare function computeCellSpans<TData>(rows: Row<TData>[], columns: AnyColumn<TData>[]): CellSpanMap;