@gulibs/react-vtable 0.0.18 → 0.0.19

package/README.md

@@ -2,13 +2,46 @@
 
 ![NPM version](https://img.shields.io/npm/v/@gulibs/react-vtable.svg?style=flat-square)
 
+A powerful and flexible React table component library built with shadcn/ui and TanStack Table.
+
 [English](#english) | [中文](#chinese)
 
 ---
 
 ## English
 
-A powerful React table component library built with shadcn/ui components and TanStack Table.
+### Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Complete API Reference](#complete-api-reference)
+- [Advanced Examples](#advanced-examples)
+- [Best Practices](#best-practices)
+- [Development](#development)
+- [License](#license)
+
+### Features
+
+- ✨ **Powerful Table**: Built on TanStack Table v8 for maximum flexibility and performance
+- 🎨 **shadcn/ui Components**: Beautiful, accessible, and customizable UI components
+- 🔍 **Search & Filter**: Advanced search with auto-filtering for local/remote data
+- 📄 **Pagination**: Client-side and server-side pagination support
+- ✅ **Row Selection**: Single/multiple selection with cross-page selection support
+- 🎯 **Batch Actions**: Flexible batch operations with smart button grouping
+- ✏️ **Inline Editing**: Edit rows inline with validation support
+- 📌 **Fixed Columns**: Pin columns to left/right with automatic shadow effects
+- 🌳 **Tree Table**: Hierarchical data with expand/collapse support
+- 🔄 **Drag & Drop**: Row and column reordering with @dnd-kit
+- 📱 **Responsive**: Mobile-friendly design
+- 🌐 **i18n**: Built-in English and Chinese locales
+- 🎭 **Rich Value Types**: 20+ built-in value types (date, money, status, etc.)
+- 📋 **Copy to Clipboard**: One-click copy for cells
+- 💬 **Tooltip**: Customizable tooltips for cells and headers
+- 📏 **Text Ellipsis**: Single-line and multi-line text truncation
+- 🔧 **TypeScript**: Full TypeScript support with comprehensive types
 
 ### Prerequisites
 
@@ -17,16 +50,24 @@ This library requires **Tailwind CSS** to be installed and configured in your pr
 ### Installation
 
 ```bash
-# Install the library
+# Using pnpm (recommended)
 pnpm add @gulibs/react-vtable
 
-# Install peer dependencies
-pnpm add react react-dom tailwindcss
+# Using npm
+npm install @gulibs/react-vtable
+
+# Using yarn
+yarn add @gulibs/react-vtable
+
+# Peer dependencies (if not already installed)
+pnpm add react react-dom @tanstack/react-table tailwindcss
 ```
 
 ### Configuration
 
-#### Configure Tailwind CSS
+#### Tailwind CSS Setup
+
+Add the library path to your `tailwind.config.js`:
 
 ```javascript
 // tailwind.config.js
@@ -39,294 +80,646 @@ export default {
 }
 ```
 
-> 💡 **Note**: The library automatically injects its CSS styles, so no manual CSS imports are required.
+> 💡 **Note**: The library automatically injects its CSS styles. No manual CSS imports are required.
 
-### Usage
+### Quick Start
 
 ```tsx
 import { ProTable } from '@gulibs/react-vtable'
-// No need to manually import CSS, styles are automatically inlined
 
 function App() {
   const columns = [
-    {
-      title: 'Name',
-      dataIndex: 'name',
-      key: 'name',
-    },
-    {
-      title: 'Age',
-      dataIndex: 'age',
-      key: 'age',
-    },
+    { title: 'Name', dataIndex: 'name', key: 'name' },
+    { title: 'Age', dataIndex: 'age', key: 'age' },
+    { title: 'Email', dataIndex: 'email', key: 'email' },
   ]
 
   const dataSource = [
-    { name: 'John', age: 30 },
-    { name: 'Jane', age: 25 },
+    { id: 1, name: 'John Doe', age: 30, email: 'john@example.com' },
+    { id: 2, name: 'Jane Smith', age: 25, email: 'jane@example.com' },
   ]
 
   return (
     <ProTable
       columns={columns}
       dataSource={dataSource}
-      rowKey="name"
+      rowKey="id"
     />
   )
 }
 ```
 
-### Features
+### Core Concepts
 
-- **Powerful Table**: Built on TanStack Table for maximum flexibility
-- **shadcn/ui Components**: Beautiful, accessible UI components
-- **Drag & Drop**: Row and column reordering with @dnd-kit
-- **Search & Filter**: Advanced search and filtering capabilities with default behavior for local and remote data modes
-- **Pagination**: Built-in pagination with customizable options
-- **Column Settings**: Show/hide columns, drag to reorder
-- **Row Selection**: Single and multiple row selection with batch actions, **cross-page selection support** (selection state persists across pages when using `request` or `pagination.onChange`)
-- **Editable Rows**: Inline editing capabilities with various value types
-- **Fixed Columns**: Left and right fixed columns with automatic position calculation and subtle shadow effects (powered by TanStack Table column pinning)
-- **Tree Table**: Hierarchical data display with expandable/collapsible rows, custom expand icons, and accordion mode
-- **Internationalization**: Built-in i18n support with English and Chinese locales
-- **Horizontal Scrolling**: Configurable table width with scroll support
-- **Copy to Clipboard**: One-click copy functionality for cells
-- **Text Ellipsis**: Single-line and multi-line text truncation with ellipsis
-- **Tooltip**: Hover tooltips for cells and headers with customizable content
-- **Responsive**: Mobile-friendly design
-- **TypeScript**: Full TypeScript support
-
-### Examples
-
-#### Basic Table
+#### 1. Data Modes
+
+**Local Data Mode** (using `dataSource`):
+```tsx
+<ProTable
+  dataSource={localData}
+  columns={columns}
+  rowKey="id"
+/>
+```
 
+**Remote Data Mode** (using `request`):
 ```tsx
 <ProTable
+  request={async (params) => {
+    // params includes: current, pageSize, filters, sorter
+    const res = await fetchData(params)
+    return {
+      data: res.items,
+      total: res.total,
+      success: true
+    }
+  }}
   columns={columns}
-  dataSource={dataSource}
   rowKey="id"
 />
 ```
 
-#### With Search
+#### 2. Search Behavior
 
-The table provides **default search behavior** that works automatically:
+The table provides **automatic search behavior**:
 
-- **Local Data Mode** (no `request` prop): Search values are automatically converted to TanStack Table's `columnFilters`, and the table filters data in real-time using `getFilteredRowModel()`.
-- **Remote Data Mode** (with `request` prop): Search triggers a new data fetch with search parameters passed to the backend.
+- **Local Mode**: Converts search values to TanStack Table's `columnFilters` and filters in real-time
+- **Remote Mode**: Triggers data fetch with search parameters sent to backend
 
-The default filter function supports:
-- Case-insensitive string matching (contains) for **text-like** fields
-- **Exact match** for **enum/filter** fields (e.g. `valueEnum`, `filters`, `valueType: 'select' | 'status'`)
-- Array-based multi-select filtering (exact match for enum/filter fields, contains match for text fields)
-- Automatic handling of empty/null values
+Default filter supports:
+- Case-insensitive substring matching for text fields
+- Exact match for enum/select fields (`valueEnum`, `filters`, `valueType: 'select'`)
+- Array-based multi-select filtering
+- Automatic empty/null value handling
 
+#### 3. Pagination Modes
+
+**Client-side Pagination** (default with `dataSource`):
 ```tsx
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  search={{
-    filterType: 'query',
-    searchText: 'Search',
-    resetText: 'Reset'
+  dataSource={data}
+  pagination={{ pageSize: 10 }}
+/>
+```
+
+**Server-side Pagination** (with `request`):
+```tsx
+<ProTable
+  request={fetchData}
+  pagination={{ pageSize: 10 }}
+/>
+```
+
+**Manual Server Pagination** (without `request`):
+```tsx
+<ProTable
+  dataSource={currentPageData}
+  pagination={{
+    mode: 'server',  // Important!
+    current: page,
+    pageSize: pageSize,
+    total: total,
+    onChange: (page, pageSize) => fetchPage(page, pageSize)
   }}
 />
 ```
 
-**Custom Search Behavior:**
+---
+
+## Complete API Reference
+
+### ProTable Props
+
+#### Core Props
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `columns` | `ProColumn<T>[]` | `[]` | Column definitions |
+| `dataSource` | `T[]` | `[]` | Local data array |
+| `request` | `(params) => Promise<Response>` | - | Remote data fetcher |
+| `rowKey` | `string \| (record) => string` | `'id'` | Unique row identifier |
+| `loading` | `boolean` | `false` | Loading state |
+| `defaultData` | `T[]` | `[]` | Default data for initial render |
+| `postData` | `(data: T[]) => T[]` | - | Transform data after fetch |
+| `params` | `Record<string, any>` | - | Extra params for `request` |
+
+#### Layout Props
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `'small' \| 'middle' \| 'large'` | `'middle'` | Table size |
+| `bordered` | `boolean` | `false` | Show table borders |
+| `tableLayout` | `'auto' \| 'fixed'` | `'auto'` | Table layout algorithm |
+| `scroll` | `{ x?: number \| string \| true; y?: number \| string }` | - | Scrollable area config |
+| `sticky` | `boolean \| { offsetHeader?: number }` | `false` | Sticky header config |
+| `showHeader` | `boolean` | `true` | Show table header |
+| `className` | `string` | - | Custom class name |
+| `style` | `CSSProperties` | - | Custom styles |
+| `tableStyle` | `CSSProperties` | - | Table element styles |
+
+#### Feature Props
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `search` | `ProTableSearch \| false` | `false` | Search form config |
+| `toolbar` | `ProTableToolBar \| false` | `false` | Toolbar config |
+| `pagination` | `ProTablePagination \| false` | `false` | Pagination config |
+| `rowSelection` | `ProTableRowSelection<T>` | - | Row selection config |
+| `batchActions` | `ProTableBatchActions<T>` | - | Batch actions config |
+| `editable` | `ProTableEditable<T>` | - | Inline editing config |
+| `expandable` | `ProTableExpandable<T> \| false` | - | Tree table config |
+| `draggable` | `ProTableDraggable \| false` | - | Drag & drop config |
+| `columnsState` | `ProColumnState` | - | Column state management |
+
+#### Callback Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `onChange` | `(pagination, filters, sorter, extra) => void` | Table change callback |
+| `onLoad` | `(dataSource: T[]) => void` | Called after data loaded |
+| `onLoadingChange` | `(loading: boolean) => void` | Loading state change |
+| `onRequestError` | `(error: Error) => void` | Request error callback |
+| `onSubmit` | `(params: any) => void` | Search submit callback |
+| `onReset` | `() => void` | Search reset callback |
+| `onRow` | `(record, index) => HTMLAttributes` | Row props callback |
+
+#### Advanced Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `headerTitle` | `ReactNode` | Table header title |
+| `headerSubTitle` | `ReactNode` | Table header subtitle |
+| `footer` | `(data) => ReactNode` | Table footer render |
+| `emptyRender` | `ReactNode` | Empty state render |
+| `tableRender` | `(props, dom, domList) => ReactNode` | Custom table render |
+| `tableExtraRender` | `(props, data) => ReactNode` | Extra content after table |
+| `paginationRender` | `(opts) => ReactNode` | Custom pagination render |
+| `searchFormRender` | `(props, dom) => ReactNode` | Custom search form render |
+| `actionRef` | `Ref<ProTableAction<T>>` | Table action reference |
+| `formRef` | `Ref<FormInstance>` | Search form reference |
+| `locale` | `ProTableLocale` | i18n locale config |
+
+---
+
+### ProColumn Configuration
+
+#### Basic Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `title` | `string` | Column header text |
+| `dataIndex` | `keyof T \| string \| string[]` | Data field path (supports nested: `'user.name'` or `['user', 'name']`) |
+| `dataPath` | `string` | Alternative to dataIndex (string path only: `'user.name'`) |
+| `key` | `string` | Unique column key |
+| `width` | `number \| string` | Column width (required for fixed columns) |
+| `align` | `'left' \| 'center' \| 'right'` | Text alignment |
+| `fixed` | `'left' \| 'right'` | Pin column to left/right |
+
+#### Display Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `valueType` | `ProFieldValueType` | Value display type (20+ types) |
+| `valueEnum` | `Record<string, { text: string; status?: string; color?: string }>` | Enum value mapping |
+| `render` | `(value, record, index) => ReactNode` | Custom cell render (takes priority over `valueType`) |
+| `ellipsis` | `boolean \| ProColumnEllipsis` | Text ellipsis config |
+| `tooltip` | `boolean \| ProColumnTooltip` | Tooltip config |
+| `headerEllipsis` | `boolean \| ProColumnEllipsis` | Header ellipsis config |
+| `headerTooltip` | `boolean \| ProColumnTooltip` | Header tooltip config |
+| `copyable` | `boolean \| ProColumnCopyable` | Enable copy to clipboard |
+
+#### Search Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `search` | `boolean \| ProColumnSearch` | Include in search form |
+| `hideInSearch` | `boolean` | Hide in search form |
+| `searchFormItemProps` | `FormItemProps` | Search form item props |
+| `renderFormItem` | `(value, onChange, field, column) => ReactNode` | Custom search input render |
+
+#### Table Display Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `hideInTable` | `boolean` | Hide in table |
+| `sorter` | `boolean \| ((a, b) => number)` | Enable sorting |
+| `filters` | `Array<{ text: string; value: any }>` | Filter options |
+| `onFilter` | `(value, record) => boolean` | Filter function |
+
+#### Edit Props
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `editable` | `boolean \| ((record) => boolean)` | Enable inline editing |
+| `hideInForm` | `boolean` | Hide in edit form |
+| `formItemProps` | `FormItemProps` | Form item props |
+| `fieldProps` | `Record<string, any>` | Field component props |
+
+---
+
+### Value Types Reference
+
+Supported `valueType` values:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `text` | Plain text | "Hello World" |
+| `textarea` | Multi-line text | Long content |
+| `number` | Number | 123 |
+| `money` | Currency | $1,234.56 |
+| `percent` | Percentage | 75% |
+| `date` | Date | 2024-01-01 |
+| `dateTime` | Date with time | 2024-01-01 10:30:00 |
+| `dateRange` | Date range | 2024-01-01 ~ 2024-01-31 |
+| `select` | Select dropdown | Uses `valueEnum` |
+| `status` | Status badge | Uses `valueEnum` |
+| `tags` | Multiple tags | Array display |
+| `switch` | Boolean switch | true/false |
+| `avatar` | Avatar image | URL display |
+| `image` | Image | URL display |
+| `progress` | Progress bar | 0-100 |
+| `code` | Code block | Monospace text |
+| `fromNow` | Relative time | "2 hours ago" |
+| `email` | Email address | With mailto link |
+| `phone` | Phone number | Formatted |
+| `url` | URL link | Clickable link |
+| `color` | Color picker | Color swatch |
+| `rate` | Rating stars | 1-5 stars |
+| `custom` | Custom render | Use `render` function |
+
+---
+
+### Search Configuration
+
+```typescript
+interface ProTableSearch {
+  filterType?: 'query' | 'light'  // Query: form above table, Light: inline filters
+  searchText?: string              // Search button text
+  resetText?: string               // Reset button text
+  submitText?: string              // Submit button text
+  labelWidth?: number | 'auto'     // Label width
+  span?: number                    // Grid column span
+  defaultCollapsed?: boolean       // Initially collapsed
+  collapsed?: boolean              // Controlled collapse state
+  onCollapse?: (collapsed: boolean) => void
+  optionRender?: (config, props, dom) => ReactNode[]  // Custom action buttons
+}
+```
 
-You can provide custom `onSearch` and `onReset` callbacks to override the default behavior:
+**Example:**
 
 ```tsx
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
   search={{
     filterType: 'query',
-    onSearch: (values) => {
-      // Custom search logic
-      console.log('Search values:', values)
-    },
-    onReset: () => {
-      // Custom reset logic
-      console.log('Reset search')
-    }
+    searchText: 'Search',
+    resetText: 'Reset',
+    labelWidth: 'auto',
+    defaultCollapsed: false,
   }}
 />
 ```
 
-#### With Pagination
+---
+
+### Pagination Configuration
+
+```typescript
+interface ProTablePagination {
+  mode?: 'client' | 'server'  // Pagination mode
+  pageSize?: number            // Items per page
+  current?: number             // Current page (controlled)
+  total?: number               // Total items
+  showSizeChanger?: boolean    // Show page size selector
+  showQuickJumper?: boolean    // Show quick jump input
+  showTotal?: (total, range) => ReactNode
+  pageSizeOptions?: string[]   // Page size options
+  size?: 'default' | 'small'
+  simple?: boolean             // Simple pagination
+  disabled?: boolean
+  onChange?: (page, pageSize) => void
+  onShowSizeChange?: (current, size) => void
+}
+```
+
+---
+
+### Row Selection Configuration
+
+```typescript
+interface ProTableRowSelection<T> {
+  type?: 'checkbox' | 'radio'  // Selection type
+  selectedRowKeys?: React.Key[]  // Controlled selection
+  onChange?: (keys, rows) => void
+  preserveSelectedRowKeys?: boolean  // Keep selection across pages (default: true)
+  getCheckboxProps?: (record) => any
+  selections?: boolean | any[]
+  hideSelectAll?: boolean
+  fixed?: boolean              // Fix selection column
+  columnWidth?: number | string
+  renderCell?: (checked, record, index, originNode) => ReactNode
+  alwaysShowAlert?: boolean    // Always show batch actions bar
+  batchActions?: ProTableBatchActions<T>  // Batch operations config
+}
+```
+
+#### Cross-Page Selection
+
+When using `request` or `pagination.onChange`, selection automatically persists across pages:
 
 ```tsx
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true
+  request={fetchData}
+  rowSelection={{
+    type: 'checkbox',
+    preserveSelectedRowKeys: true,  // Default: true
+    onChange: (selectedRowKeys, selectedRows) => {
+      // selectedRowKeys: all selected keys across all pages
+      // selectedRows: rows from current page only
+      console.log('Total selected:', selectedRowKeys.length)
+    }
   }}
 />
 ```
 
-#### Remote Pagination (with `request`)
+---
+
+### Batch Actions Configuration (Updated API)
 
-In **Remote Data Mode** (when you pass `request`), pagination works like this:
+```typescript
+interface ProTableBatchActions<T> {
+  actions?: Array<ProTableBatchAction<T>>  // Batch action list
+  maxVisibleActions?: number  // Max buttons to show directly (default: 3)
+  hideClearButton?: boolean   // Hide clear selection button
+}
 
-- **`total` controls the page count**: return `total` from `request` (recommended) and/or pass `pagination.total`.
-- **Do not pass `pagination.current/pageSize` as constants** (e.g. `current: 1`), unless you intend to lock the table to that page. If you want controlled pagination, store them in state and update in `pagination.onChange`.
+interface ProTableBatchAction<T> {
+  key: string                  // Unique action key
+  label: string                // Button text
+  icon?: ReactNode             // Button icon
+  onClick: (rows: T[]) => void // Click handler
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
+  clearSelection?: boolean     // Clear selection after action (default: false)
+  showInMore?: boolean         // Show in "More" menu (default: false)
+  isExportFormat?: boolean     // Mark as export format (auto-groups multiple export formats)
+}
+```
 
-**Uncontrolled (recommended if you don't need to control page state):**
+**Example:**
 
 ```tsx
+import { Trash2, Download, FileText, Mail } from 'lucide-react'
+
 <ProTable
-  columns={columns}
-  rowKey="id"
-  request={async (params) => {
-    // params includes: current, pageSize, ...filters, ...sorter
-    const res = await fetchUsers(params)
-    return { data: res.items, total: res.total, success: true }
-  }}
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true,
-    showQuickJumper: true,
+  rowSelection={{
+    type: 'checkbox',
+    batchActions: {
+      maxVisibleActions: 3,  // Show max 3 buttons directly
+      actions: [
+        {
+          key: 'delete',
+          label: 'Delete',
+          icon: <Trash2 className="h-3 w-3 mr-1" />,
+          onClick: (rows) => {
+            console.log('Delete:', rows)
+          },
+          variant: 'destructive',
+          clearSelection: true,  // Clear after delete
+        },
+        {
+          key: 'export',
+          label: 'Export',
+          icon: <Download className="h-3 w-3 mr-1" />,
+          onClick: (rows) => {
+            console.log('Export:', rows)
+          },
+          variant: 'outline',
+        },
+        {
+          key: 'exportExcel',
+          label: 'Export Excel',
+          icon: <FileText className="h-3 w-3 mr-1" />,
+          onClick: (rows) => {
+            console.log('Export Excel:', rows)
+          },
+          variant: 'outline',
+          isExportFormat: true,  // Groups with other export formats
+          showInMore: true,
+        },
+        {
+          key: 'exportCSV',
+          label: 'Export CSV',
+          icon: <FileText className="h-3 w-3 mr-1" />,
+          onClick: (rows) => {
+            console.log('Export CSV:', rows)
+          },
+          variant: 'outline',
+          isExportFormat: true,
+          showInMore: true,
+        },
+        {
+          key: 'email',
+          label: 'Send Email',
+          icon: <Mail className="h-3 w-3 mr-1" />,
+          onClick: (rows) => {
+            console.log('Email:', rows)
+          },
+          variant: 'outline',
+          showInMore: true,  // Move to "More" menu
+        },
+      ],
+    },
   }}
 />
 ```
 
-**Controlled (when you need to sync pagination with external state / URL):**
+**Features:**
+- Smart button grouping: buttons exceeding `maxVisibleActions` auto-move to "More" (⋯) menu
+- Export format grouping: multiple `isExportFormat: true` actions auto-merge into dropdown
+- Flexible action control: use `clearSelection` to auto-clear selection after certain actions
 
-```tsx
-function Page() {
-  const [pagination, setPagination] = useState({
-    current: 1,
-    pageSize: 10,
-    total: 0,
-  })
+---
 
-  return (
-    <ProTable
-      columns={columns}
-      rowKey="id"
-      request={async (params) => {
-        const res = await fetchUsers(params)
-        setPagination((prev) => ({ ...prev, total: res.total }))
-        return { data: res.items, total: res.total, success: true }
-      }}
-      pagination={{
-        current: pagination.current,
-        pageSize: pagination.pageSize,
-        total: pagination.total,
-        showSizeChanger: true,
-        showQuickJumper: true,
-        onChange: (current, pageSize) => {
-          setPagination((prev) => ({ ...prev, current, pageSize }))
-        },
-      }}
-    />
-  )
+### Editable Configuration
+
+```typescript
+interface ProTableEditable<T> {
+  type?: 'single' | 'multiple'  // Edit mode
+  form?: any                     // React Hook Form instance
+  formProps?: Record<string, any>
+  onSave?: (key, record, originRow) => Promise<void>
+  onDelete?: (key, record) => Promise<void>
+  onCancel?: (key, record, originRow) => void
+  actionRender?: (record, config) => ReactNode[]  // Custom action buttons
+  deletePopconfirmMessage?: ReactNode
+  onlyOneLineEditorAlertMessage?: ReactNode
+  onlyAddOneLineAlertMessage?: ReactNode
 }
 ```
 
-#### Server Pagination (NO `request`, you fetch data yourself)
+---
 
-If you **do not** use `request`, but you still want **server-side pagination** (i.e. `dataSource` only contains **current page items**),
-set `pagination.mode: 'server'` to prevent TanStack Table from slicing again.
+### Expandable Configuration (Tree Table)
 
-```tsx
-function Page() {
-  const [pagination, setPagination] = useState({ current: 1, pageSize: 10, total: 0 })
-  const [data, setData] = useState<any[]>([])
+```typescript
+interface ProTableExpandable<T> {
+  childrenColumnName?: string    // Children field name (default: 'children')
+  defaultExpandedRowKeys?: React.Key[]  // Default expanded rows
+  expandedRowKeys?: React.Key[]  // Controlled expanded rows
+  onExpand?: (expanded, record) => void
+  onExpandedRowsChange?: (keys) => void
+  expandIcon?: (props: {
+    expanded: boolean
+    onExpand: () => void
+    record: T
+  }) => ReactNode
+  showExpandColumn?: boolean     // Show expand column (default: true)
+  expandColumnWidth?: number     // Expand column width (default: 50)
+  defaultExpandAllRows?: boolean // Expand all by default
+  accordion?: boolean            // Accordion mode (only one expanded)
+}
+```
 
-  const fetchPage = async (current: number, pageSize: number) => {
-    const res = await fetchUsers({ current, pageSize })
-    setData(res.items)
-    setPagination((prev) => ({ ...prev, current, pageSize, total: res.total }))
-  }
+---
 
-  useEffect(() => {
-    void fetchPage(pagination.current, pagination.pageSize)
-  }, [])
+### Ellipsis Configuration
 
-  return (
-    <ProTable
-      columns={columns}
-      rowKey="id"
-      dataSource={data}
-      pagination={{
-        mode: "server",
-        current: pagination.current,
-        pageSize: pagination.pageSize,
-        total: pagination.total,
-        onChange: (current, pageSize) => void fetchPage(current, pageSize),
-      }}
-    />
-  )
+```typescript
+interface ProColumnEllipsis {
+  multiline?: boolean  // Multi-line ellipsis
+  rows?: number        // Number of rows (1-5, default: 2)
+}
+```
+
+**Examples:**
+
+```tsx
+// Single-line ellipsis
+ellipsis: true
+
+// Multi-line ellipsis (2 lines)
+ellipsis: {
+  multiline: true,
+  rows: 2
 }
 ```
 
-#### Custom Pagination Rendering (`paginationRender`)
+---
+
+### Tooltip Configuration
 
-Use `paginationRender` when you want to **render your own pagination UI** (in any layout), while still reusing ProTable’s built-in
-pagination state and default Pagination component.
+```typescript
+interface ProColumnTooltip<T> {
+  content?: ReactNode | ((value, record, index) => ReactNode)
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  align?: 'start' | 'center' | 'end'
+  delayDuration?: number
+  disabled?: boolean
+}
+```
 
-Notes:
-- `paginationRender` receives `pagination`, `onChange`, and `defaultDom`.
-- If you are in **server pagination mode** (`pagination.mode: 'server'`) you must also provide `pagination.onChange` to fetch data.
+**Examples:**
 
 ```tsx
-<ProTable
-  columns={columns}
-  rowKey="id"
-  dataSource={data}
-  pagination={{
-    mode: "server",
-    current,
-    pageSize,
-    total,
-    onChange: (page, pageSize) => void fetchPage(page, pageSize),
-  }}
-  paginationRender={({ pagination, onChange, defaultDom }) => (
-    <div className="space-y-2">
-      <div className="flex items-center justify-between rounded border p-2">
-        <div className="text-sm text-muted-foreground">
-          Page {pagination.current} / Size {pagination.pageSize} / Total {pagination.total}
-        </div>
-        <div className="flex gap-2">
-          <button onClick={() => onChange(Math.max(1, pagination.current - 1), pagination.pageSize)}>
-            Prev
-          </button>
-          <button onClick={() => onChange(pagination.current + 1, pagination.pageSize)}>
-            Next
-          </button>
-        </div>
-      </div>
-      {/* reuse built-in Pagination UI */}
-      {defaultDom}
-    </div>
-  )}
-/>
+// Simple tooltip (shows cell value)
+tooltip: true
+
+// Custom tooltip
+tooltip: {
+  content: 'Custom tooltip text',
+  side: 'top',
+  delayDuration: 300
+}
+
+// Function-based tooltip
+tooltip: {
+  content: (value, record) => `Full: ${value} (ID: ${record.id})`,
+  side: 'top'
+}
+```
+
+---
+
+### Action Reference
+
+Access table methods via `actionRef`:
+
+```typescript
+interface ProTableAction<T> {
+  reload: (resetPageIndex?: boolean) => Promise<void>  // Reload data
+  reloadAndRest: () => Promise<void>  // Reload and reset to page 1
+  reset: () => void                    // Reset filters and search
+  clearSelected: () => void            // Clear row selection
+  startEditable: (rowKey) => boolean   // Start editing row
+  cancelEditable: (rowKey) => boolean  // Cancel editing row
+  saveEditable: (rowKey, record) => boolean  // Save edited row
+  getRowData: (rowKey) => T | undefined     // Get row data
+  getTableData: () => T[]              // Get all table data
+  setTableData: (data: T[]) => void    // Set table data
+}
 ```
 
-#### With Internationalization
+**Example:**
 
 ```tsx
-import { ProTable, zh_CN } from '@gulibs/react-vtable'
+const actionRef = useRef<ProTableAction<DataType>>(null)
+
+// Reload data
+actionRef.current?.reload()
+
+// Reset filters
+actionRef.current?.reset()
+
+// Clear selection
+actionRef.current?.clearSelected()
+```
+
+---
+
+## Advanced Examples
 
+### 1. Remote Data with Search and Pagination
+
+```tsx
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
+  request={async (params) => {
+    // params includes: current, pageSize, keyword, ...filters, ...sorter
+    const response = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify(params)
+    })
+    const data = await response.json()
+    return {
+      data: data.items,
+      total: data.total,
+      success: true
+    }
+  }}
+  columns={[
+    { title: 'Name', dataIndex: 'name', search: true },
+    { title: 'Email', dataIndex: 'email', search: true },
+    {
+      title: 'Status',
+      dataIndex: 'status',
+      valueType: 'select',
+      search: true,
+      valueEnum: {
+        active: { text: 'Active', status: 'success' },
+        inactive: { text: 'Inactive', status: 'default' },
+      },
+    },
+  ]}
+  search={{ filterType: 'query' }}
+  pagination={{
+    pageSize: 10,
+    showSizeChanger: true,
+    showQuickJumper: true,
+  }}
   rowKey="id"
-  locale={zh_CN}
 />
 ```
 
-#### With Fixed Columns
-
-Fixed columns are implemented using TanStack Table's column pinning feature. The library automatically calculates positions and applies subtle shadow effects to indicate fixed column boundaries.
+### 2. Fixed Columns with Horizontal Scroll
 
 ```tsx
 <ProTable
@@ -334,1268 +727,574 @@ Fixed columns are implemented using TanStack Table's column pinning feature. The
     {
       title: 'ID',
       dataIndex: 'id',
-      key: 'id',
       width: 80,
-      fixed: 'left'  // Fixed to the left
+      fixed: 'left',  // Pin to left
     },
     {
       title: 'Name',
       dataIndex: 'name',
-      key: 'name',
-      width: 120
+      width: 150,
+      fixed: 'left',
     },
+    { title: 'Email', dataIndex: 'email', width: 200 },
+    { title: 'Phone', dataIndex: 'phone', width: 150 },
+    { title: 'Address', dataIndex: 'address', width: 300 },
     {
       title: 'Actions',
-      dataIndex: 'actions',
       key: 'actions',
       width: 100,
-      fixed: 'right'  // Fixed to the right
-    }
+      fixed: 'right',  // Pin to right
+      render: (_, record) => (
+        <Button size="sm">Edit</Button>
+      ),
+    },
   ]}
-  dataSource={dataSource}
+  dataSource={data}
+  scroll={{ x: 1200 }}  // Enable horizontal scroll
+  tableLayout="fixed"    // Required for fixed columns
   rowKey="id"
-  scroll={{ x: 1000 }}  // Enable horizontal scrolling
-  tableLayout="fixed"    // Recommended for fixed columns
 />
 ```
 
-**Important Notes:**
-- Fixed columns require a `width` property to calculate positions correctly
-- The library automatically handles position calculations using TanStack Table's `getStart()` and `getAfter()` methods
-- Subtle shadow effects are automatically applied to the last left-pinned column and first right-pinned column
-- No additional CSS is required - all styles are applied inline
-
-#### With Tree Table (Expandable Rows)
-
-Tree tables support hierarchical data structures with expandable/collapsible rows. The data structure should include a `children` property (or custom field name) containing nested rows.
+### 3. Tree Table with Expandable Rows
 
 ```tsx
 <ProTable
-  columns={columns}
+  columns={[
+    { title: 'Name', dataIndex: 'name', width: 200 },
+    { title: 'Size', dataIndex: 'size' },
+    { title: 'Type', dataIndex: 'type' },
+  ]}
   dataSource={[
     {
       id: 1,
-      name: 'Parent Node',
+      name: 'Folder 1',
+      type: 'folder',
       children: [
-        { id: 11, name: 'Child Node 1' },
-        { id: 12, name: 'Child Node 2' }
-      ]
-    }
-  ]}
-  rowKey="id"
-  expandable={{
-    childrenColumnName: 'children',  // Default: 'children'
-    defaultExpandAllRows: false,     // Expand all rows by default
-    defaultExpandedRowKeys: [1],     // Initially expanded rows
-    accordion: false,                // Accordion mode (only one row expanded at a time)
-    showExpandColumn: true,          // Show expand icon column
-    expandColumnWidth: 50,           // Width of expand column
-    onExpand: (expanded, record) => {
-      console.log('Expand:', expanded, record)
+        { id: 11, name: 'File 1.1', type: 'file', size: '1.2 MB' },
+        { id: 12, name: 'File 1.2', type: 'file', size: '2.5 MB' },
+      ],
     },
-    onExpandedRowsChange: (expandedRowKeys) => {
-      console.log('Expanded keys:', expandedRowKeys)
+    {
+      id: 2,
+      name: 'Folder 2',
+      type: 'folder',
+      children: [
+        { id: 21, name: 'File 2.1', type: 'file', size: '3.1 MB' },
+      ],
     },
-    expandIcon: ({ expanded, onExpand, record }) => (
-      <Button onClick={onExpand}>
-        {expanded ? '▼' : '▶'}
-      </Button>
-    )
+  ]}
+  expandable={{
+    defaultExpandAllRows: false,
+    accordion: false,  // Allow multiple rows expanded
   }}
+  rowKey="id"
 />
 ```
 
-**Tree Table Features:**
-- **Controlled/Uncontrolled Mode**: Use `expandedRowKeys` for controlled mode, or `defaultExpandedRowKeys` for uncontrolled
-- **Default Expand All**: Set `defaultExpandAllRows: true` to expand all rows by default
-- **Accordion Mode**: Set `accordion: true` to allow only one row to be expanded at a time
-- **Custom Children Field**: Use `childrenColumnName` to specify a custom field name for children (default: `'children'`)
-- **Custom Expand Icon**: Provide a custom `expandIcon` function to customize the expand/collapse icon
-- **Expand Callbacks**: Use `onExpand` and `onExpandedRowsChange` to handle expand state changes
-
-#### With Editable Rows
+### 4. Inline Editing
 
 ```tsx
+const [editableKeys, setEditableKeys] = useState<React.Key[]>([])
+
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
+  columns={[
+    {
+      title: 'Name',
+      dataIndex: 'name',
+      editable: true,
+    },
+    {
+      title: 'Age',
+      dataIndex: 'age',
+      valueType: 'number',
+      editable: true,
+    },
+    {
+      title: 'Email',
+      dataIndex: 'email',
+      editable: true,
+    },
+  ]}
+  dataSource={data}
   editable={{
     type: 'multiple',
+    editableKeys,
+    onChange: setEditableKeys,
     onSave: async (key, record, originRow) => {
-      console.log('Save:', { key, record, originRow })
-      // Handle save logic
-    }
+      // Save to backend
+      await updateUser(key, record)
+      message.success('Saved successfully')
+    },
   }}
+  rowKey="id"
 />
 ```
 
-#### With Row Selection and Batch Actions
+### 5. Drag & Drop Reordering
 
 ```tsx
 <ProTable
   columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  rowSelection={{
-    type: 'checkbox',
-    onChange: (selectedRowKeys, selectedRows) => {
-      console.log('Selected:', selectedRowKeys, selectedRows)
+  dataSource={data}
+  draggable={{
+    enabled: true,
+    handle: true,  // Show drag handle
+    onDragEnd: (result) => {
+      const { items, oldIndex, newIndex } = result
+      console.log('New order:', items)
+      // Update backend order
+      updateOrder(items.map(item => item.id))
     },
-    batchActions: {
-      onDelete: (rows) => {
-        console.log('Delete:', rows)
-      },
-      onExport: (rows) => {
-        console.log('Export:', rows)
-      }
-    }
   }}
+  rowKey="id"
 />
 ```
 
-**Cross-Page Selection Support:**
-
-When using `request` or `pagination.onChange` for remote data fetching, the table automatically maintains selection state across pages. This means:
-
-- Selections made on one page are preserved when navigating to other pages
-- The batch actions bar shows the **total count** of selected rows across all pages
-- When you return to a previously visited page, your selections are automatically restored
-- The `onChange` callback receives all selected row keys across all pages
+### 6. Custom Cell Rendering
 
 ```tsx
 <ProTable
-  columns={columns}
-  rowKey="id"
-  request={async (params) => {
-    const res = await fetchUsers(params)
-    return { data: res.items, total: res.total, success: true }
-  }}
-  rowSelection={{
-    type: 'checkbox',
-    onChange: (selectedRowKeys, selectedRows) => {
-      // selectedRowKeys contains ALL selected keys across all pages
-      // selectedRows contains rows from the current page only
-      console.log('Total selected across all pages:', selectedRowKeys.length)
+  columns={[
+    {
+      title: 'Avatar',
+      dataIndex: 'avatar',
+      valueType: 'avatar',
+      render: (_, record) => (
+        <Avatar>
+          <AvatarImage src={record.avatar} />
+          <AvatarFallback>{record.name[0]}</AvatarFallback>
+        </Avatar>
+      ),
     },
-    batchActions: {
-      onDelete: (rows) => {
-        // This will receive rows from current page only
-        // Use selectedRowKeys from onChange for full selection
-        console.log('Delete current page rows:', rows)
-      }
-    }
-  }}
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true,
-    onChange: (current, pageSize) => {
-      // Selection state is automatically preserved when page changes
-    }
-  }}
+    {
+      title: 'Status',
+      dataIndex: 'status',
+      valueType: 'status',
+      valueEnum: {
+        active: { text: 'Active', status: 'success' },
+        inactive: { text: 'Inactive', status: 'default' },
+        pending: { text: 'Pending', status: 'warning' },
+      },
+      render: (_, record) => (
+        <Badge variant={record.status === 'active' ? 'success' : 'secondary'}>
+          {record.status}
+        </Badge>
+      ),
+    },
+    {
+      title: 'Progress',
+      dataIndex: 'progress',
+      valueType: 'progress',
+      render: (_, record) => (
+        <div className="flex items-center gap-2">
+          <Progress value={record.progress} className="w-20" />
+          <span className="text-xs">{record.progress}%</span>
+        </div>
+      ),
+    },
+  ]}
+  dataSource={data}
+  rowKey="id"
 />
 ```
 
-**Important Notes:**
-- Cross-page selection works automatically when using `request` or `pagination.onChange`
-- With `dataSource` (local data), selection works normally but doesn't need cross-page support
-- The batch actions bar always shows the total count of selected rows across all pages
-- Use `rowSelection.onChange` to get all selected keys if you need to perform operations on all selected rows
-
-**Automatic Selection Clearing:**
-
-After certain batch operations, the selection state is automatically cleared:
-
-- **Delete operation**: Automatically clears selection after deletion (since the data is removed)
-- **Archive operation**: Automatically clears selection after archiving
-- **Custom actions**: You can control whether to clear selection using the `clearSelection` option
+### 7. Multi-line Ellipsis with Tooltip
 
 ```tsx
 <ProTable
-  rowSelection={{
-    type: 'checkbox',
-    batchActions: {
-      onDelete: (rows) => {
-        // Delete operation - selection will be automatically cleared
-        console.log('Delete:', rows)
+  columns={[
+    {
+      title: 'Description',
+      dataIndex: 'description',
+      width: 300,
+      ellipsis: {
+        multiline: true,
+        rows: 3,  // Show 3 lines max
       },
-      onArchive: (rows) => {
-        // Archive operation - selection will be automatically cleared
-        console.log('Archive:', rows)
+      tooltip: {
+        content: (value) => value,
+        side: 'top',
       },
-      // Hide the clear button if needed
-      hideClearButton: false,
-      customActions: [
-        {
-          key: 'approve',
-          label: 'Approve',
-          onClick: (rows) => {
-            console.log('Approve:', rows)
-          },
-          // Control whether to clear selection after this action
-          clearSelection: true, // Set to true to clear selection after this action
-        },
-        {
-          key: 'export',
-          label: 'Export',
-          onClick: (rows) => {
-            console.log('Export:', rows)
-          },
-          clearSelection: false, // Keep selection after export (default)
-        }
-      ]
-    }
-  }}
+    },
+    {
+      title: 'Long Title Column with Header Tooltip',
+      dataIndex: 'data',
+      width: 150,
+      headerEllipsis: true,  // Header ellipsis
+      headerTooltip: {
+        content: 'This is a very long header title that needs tooltip',
+        side: 'bottom',
+      },
+      ellipsis: true,  // Cell ellipsis
+      tooltip: true,   // Cell tooltip
+    },
+  ]}
+  dataSource={data}
+  rowKey="id"
 />
 ```
 
-#### With Text Ellipsis and Tooltip
+### 8. Custom Search Form
 
 ```tsx
 <ProTable
   columns={[
     {
-      title: 'Description',
-      dataIndex: 'description',
-      key: 'description',
-      width: 200,
-      // Single-line ellipsis with tooltip
-      ellipsis: true,
-      tooltip: true
-    },
-    {
-      title: 'Content',
-      dataIndex: 'content',
-      key: 'content',
-      width: 250,
-      // Multi-line ellipsis (2 rows) with tooltip
-      ellipsis: {
-        multiline: true,
-        rows: 2
-      },
-      tooltip: true
+      title: 'Name',
+      dataIndex: 'name',
+      search: true,
     },
     {
-      title: 'Custom Tooltip',
-      dataIndex: 'name',
-      key: 'name',
-      width: 150,
-      ellipsis: true,
-      tooltip: {
-        content: (value, record) => `Full: ${record.fullName || value}`,
-        side: 'top',
-        delayDuration: 300
-      }
+      title: 'Date Range',
+      dataIndex: 'dateRange',
+      valueType: 'dateRange',
+      search: true,
+      renderFormItem: (value, onChange) => (
+        <DateRangePicker
+          value={value}
+          onChange={onChange}
+        />
+      ),
     },
     {
-      title: 'Header with Ellipsis',
-      dataIndex: 'email',
-      key: 'email',
-      width: 180,
-      // Header-specific ellipsis and tooltip
-      headerEllipsis: true,
-      headerTooltip: {
-        content: 'This is the full header title',
-        side: 'bottom'
+      title: 'Custom Filter',
+      dataIndex: 'customField',
+      search: {
+        transform: (value) => {
+          // Transform before sending to backend
+          return { customFieldQuery: value.toUpperCase() }
+        },
       },
-      // Cell ellipsis and tooltip
-      ellipsis: true,
-      tooltip: true
-    }
+      renderFormItem: (value, onChange) => (
+        <CustomFilterComponent
+          value={value}
+          onChange={onChange}
+        />
+      ),
+    },
   ]}
-  dataSource={dataSource}
+  request={fetchData}
+  search={{ filterType: 'query' }}
   rowKey="id"
 />
 ```
 
-### API Reference
+---
 
-#### ProTable Props
+## Best Practices
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `columns` | `ProColumn[]` | `[]` | Table column definitions |
-| `dataSource` | `T[]` | `[]` | Table data source |
-| `rowKey` | `string \| (record: T) => string` | `'id'` | Unique key for each row |
-| `loading` | `boolean` | `false` | Loading state |
-| `pagination` | `ProTablePagination \| false` | `false` | Pagination configuration |
-| `search` | `ProTableSearch \| false` | `false` | Search form configuration |
-| `rowSelection` | `ProTableRowSelection` | `undefined` | Row selection configuration |
-| `editable` | `ProTableEditable` | `undefined` | Editable rows configuration |
-| `draggable` | `ProTableDraggable` | `undefined` | Drag and drop configuration |
-| `expandable` | `ProTableExpandable \| false` | `undefined` | Tree table expandable configuration |
-| `scroll` | `{ x?: number \| true; y?: number \| string }` | `undefined` | Scroll configuration |
-| `tableLayout` | `'auto' \| 'fixed'` | `'auto'` | Table layout mode |
-| `locale` | `ProTableLocale` | `en_US` | Internationalization locale |
-| `size` | `'small' \| 'middle' \| 'large'` | `'middle'` | Table size |
-| `bordered` | `boolean` | `false` | Show table borders |
+### 1. Performance Optimization
 
-#### Column Configuration
+#### Use `rowKey` Correctly
+Always provide a stable, unique `rowKey`:
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `title` | `string` | Column header text |
-| `dataIndex` | `string` | Data field name |
-| `key` | `string` | Unique column key |
-| `width` | `number` | Column width in pixels |
-| `fixed` | `'left' \| 'right'` | Fixed column position |
-| `sorter` | `boolean` | Enable sorting |
-| `editable` | `boolean` | Enable inline editing |
-| `copyable` | `boolean` | Enable copy to clipboard |
-| `ellipsis` | `boolean \| ProColumnEllipsis` | Enable text ellipsis (single-line or multi-line) |
-| `tooltip` | `boolean \| ProColumnTooltip` | Enable tooltip on hover |
-| `headerEllipsis` | `boolean \| ProColumnEllipsis` | Enable ellipsis for header (defaults to `ellipsis`) |
-| `headerTooltip` | `boolean \| ProColumnTooltip` | Enable tooltip for header (defaults to `tooltip`) |
-| `search` | `boolean` | Include in search form |
-| `valueType` | `ProFieldValueType` | Value type for rendering |
-| `valueEnum` | `Record<string, { text: string; status?: string }>` | Enum values for select |
-| `filters` | `Array<{ text: string; value: any }>` | Filter options |
-| `render` | `(value: any, record: T, index: number) => ReactNode` | Custom render function |
+```tsx
+// Good: Use unique ID
+<ProTable rowKey="id" />
 
-#### Render Function and valueType Priority
+// Good: Use function for complex keys
+<ProTable rowKey={(record) => `${record.type}-${record.id}`} />
 
-When both `render` and `valueType` are configured, the `render` function takes **priority** over `valueType` for table cell rendering. This allows you to:
+// Bad: Use index (causes re-render issues)
+<ProTable rowKey={(record, index) => index} />
+```
 
-- Use `valueType` for **search form** rendering (e.g., `valueType: "select"` generates a select dropdown in the search form)
-- Use custom `render` function for **table cell** rendering (e.g., custom badges, icons, or complex layouts)
+#### Memoize Large Data
+For large datasets, memoize your data:
 
-**Rendering Priority:**
-1. **`render` function** (if provided) - Used for table cell rendering
-2. **`valueType`** (if provided) - Used for table cell rendering when `render` is not provided
-3. **Default rendering** - Raw value display
+```tsx
+const data = useMemo(() => generateLargeData(), [])
 
-**Example:**
+<ProTable dataSource={data} />
+```
+
+#### Optimize Column Rendering
+Use `useMemo` for column definitions with complex render functions:
 
 ```tsx
-const columns = [
+const columns = useMemo(() => [
   {
-    title: "Level",
-    dataIndex: "level",
-    key: "level",
-    valueType: "select",  // Used for search form
-    search: true,
-    valueEnum: {
-      "1": { text: "Level 1", status: "default" },
-      "2": { text: "Level 2", status: "default" },
-      "3": { text: "Level 3", status: "default" },
-    },
-    // Custom render function takes priority for table cell rendering
-    render: (_value, record) => {
-      const levelNum = parseInt(record.level);
-      const colors = [
-        "bg-blue-100 text-blue-800",
-        "bg-green-100 text-green-800",
-        "bg-yellow-100 text-yellow-800",
-      ];
-      return (
-        <Badge className={colors[levelNum - 1]}>
-          L{record.level}
-        </Badge>
-      );
-    },
+    title: 'Name',
+    render: (_, record) => <ComplexComponent record={record} />,
   },
-];
+], [dependencies])
 ```
 
-In this example:
-- **Search form**: Shows a select dropdown (because of `valueType: "select"`)
-- **Table cell**: Shows a custom Badge component (because of `render` function)
-
-**Note**: The `select` valueType also supports `valueEnum` for rendering when no `render` function is provided.
+### 2. Request Best Practices
 
-#### Ellipsis Configuration
+#### Handle Errors Gracefully
+```tsx
+<ProTable
+  request={async (params) => {
+    try {
+      const res = await fetchData(params)
+      return { data: res.items, total: res.total, success: true }
+    } catch (error) {
+      message.error('Failed to load data')
+      return { data: [], total: 0, success: false }
+    }
+  }}
+  onRequestError={(error) => {
+    console.error('Request error:', error)
+    // Report to error tracking service
+  }}
+/>
+```
 
-The `ellipsis` and `headerEllipsis` properties support the following configurations:
+#### Debounce Search Requests
+Use `params` prop to trigger re-fetch:
 
 ```tsx
-// Single-line ellipsis
-ellipsis: true
+const [searchParams, setSearchParams] = useState({})
+const debouncedSearch = useMemo(
+  () => debounce((value) => setSearchParams({ keyword: value }), 500),
+  []
+)
 
-// Multi-line ellipsis
-ellipsis: {
-  multiline: true,
-  rows: 2  // Number of lines (1-5)
-}
+<ProTable
+  request={fetchData}
+  params={searchParams}
+  toolbar={{
+    search: {
+      onSearch: debouncedSearch,
+    },
+  }}
+/>
 ```
 
-#### Tooltip Configuration
+### 3. State Management
 
-The `tooltip` and `headerTooltip` properties support the following configurations:
+#### Controlled Components
+For complex state management, use controlled mode:
 
 ```tsx
-// Simple tooltip (shows cell value)
-tooltip: true
+const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([])
+const [pagination, setPagination] = useState({ current: 1, pageSize: 10 })
 
-// Custom tooltip
-tooltip: {
-  content: 'Custom tooltip text',
-  side: 'top' | 'right' | 'bottom' | 'left',
-  align: 'start' | 'center' | 'end',
-  delayDuration: 300,
-  disabled: false
+<ProTable
+  rowSelection={{
+    selectedRowKeys,
+    onChange: setSelectedRowKeys,
+  }}
+  pagination={{
+    ...pagination,
+    onChange: (current, pageSize) => {
+      setPagination({ current, pageSize })
+    },
+  }}
+/>
+```
+
+#### Use Action Ref
+Access table methods via `actionRef`:
+
+```tsx
+const actionRef = useRef<ProTableAction<DataType>>(null)
+
+const handleRefresh = () => {
+  actionRef.current?.reload()
 }
 
-// Function-based tooltip
-tooltip: {
-  content: (value, record, index) => `Full: ${value}\nID: ${record.id}`,
-  side: 'top'
+const handleReset = () => {
+  actionRef.current?.reset()
+  actionRef.current?.clearSelected()
 }
+
+<ProTable actionRef={actionRef} />
 ```
 
-**Note**: When `ellipsis` is enabled and `tooltip` is `true`, the tooltip will automatically show the full original value (not the rendered value) when text is truncated.
+### 4. Accessibility
 
-#### Expandable (Tree Table) Configuration
+- Always provide meaningful `title` for columns
+- Use `aria-label` for action buttons
+- Ensure color contrast for status badges
+- Test with keyboard navigation
 
-The `expandable` property supports the following configurations:
+### 5. Internationalization
 
 ```tsx
-expandable: {
-  // Custom children field name (default: 'children')
-  childrenColumnName?: string
-
-  // Default expanded row keys (uncontrolled mode)
-  defaultExpandedRowKeys?: React.Key[]
+import { ProTable, zh_CN, en_US } from '@gulibs/react-vtable'
+import { useState } from 'react'
 
-  // Currently expanded row keys (controlled mode)
-  expandedRowKeys?: React.Key[]
-
-  // Expand/collapse callback
-  onExpand?: (expanded: boolean, record: T) => void
+function App() {
+  const [locale, setLocale] = useState(en_US)
 
-  // Expanded rows change callback
-  onExpandedRowsChange?: (expandedRowKeys: React.Key[]) => void
+  return (
+    <>
+      <Button onClick={() => setLocale(zh_CN)}>中文</Button>
+      <Button onClick={() => setLocale(en_US)}>English</Button>
+      
+      <ProTable
+        locale={locale}
+        columns={columns}
+        dataSource={data}
+      />
+    </>
+  )
+}
+```
 
-  // Custom expand icon
-  expandIcon?: (props: {
-    expanded: boolean
-    onExpand: () => void
-    record: T
-  }) => ReactNode
+### 6. Type Safety
 
-  // Show expand column (default: true)
-  showExpandColumn?: boolean
+Always provide TypeScript types for your data:
 
-  // Expand column width (default: 50)
-  expandColumnWidth?: number
+```tsx
+interface User {
+  id: string
+  name: string
+  email: string
+  age: number
+  status: 'active' | 'inactive'
+}
 
-  // Expand all rows by default (default: false)
-  defaultExpandAllRows?: boolean
+const columns: ProColumn<User>[] = [
+  {
+    title: 'Name',
+    dataIndex: 'name',
+    // TypeScript will validate dataIndex, valueType, render function params, etc.
+  },
+]
 
-  // Accordion mode - only one row expanded at a time (default: false)
-  accordion?: boolean
-}
+<ProTable<User>
+  columns={columns}
+  dataSource={users}
+  rowKey="id"
+/>
 ```
 
-### Development
+---
+
+## Development
 
 ```bash
 # Install dependencies
 pnpm install
 
-# Build the library
-pnpm run build
-
 # Start development server
 pnpm run dev
-```
 
-### License
+# Build library
+pnpm run build
 
-MIT
+# Lint code
+pnpm run lint
+```
 
 ---
 
-## Chinese
-
-一个基于 shadcn/ui 组件和 TanStack Table 构建的强大 React 表格组件库。
-
-### 前置要求
-
-此库需要您的项目中安装并配置 **Tailwind CSS**。
-
-### 安装
-
-```bash
-# 安装库
-pnpm add @gulibs/react-vtable
+## License
 
-# 安装对等依赖
-pnpm add react react-dom tailwindcss
-```
+MIT © [@gulibs](https://github.com/gulibs)
 
-### 配置
+---
 
-#### 配置 Tailwind CSS
+## Chinese
 
-```javascript
-// tailwind.config.js
-export default {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@gulibs/react-vtable/dist/**/*.js'
-  ],
-  // 无需额外配置 - 样式会自动注入
-}
-```
+## 中文文档
 
-> 💡 **注意**: 库会自动注入其 CSS 样式，因此无需手动导入 CSS。
+[查看完整中文文档 ↗](./README.zh-CN.md)
 
-### 使用方法
+### 快速开始
 
 ```tsx
-import { ProTable } from '@gulibs/react-vtable'
-// 无需手动导入 CSS，样式已自动内联
+import { ProTable, zh_CN } from '@gulibs/react-vtable'
 
 function App() {
   const columns = [
-    {
-      title: '姓名',
-      dataIndex: 'name',
-      key: 'name',
-    },
-    {
-      title: '年龄',
-      dataIndex: 'age',
-      key: 'age',
-    },
+    { title: '姓名', dataIndex: 'name', key: 'name' },
+    { title: '年龄', dataIndex: 'age', key: 'age' },
   ]
 
   const dataSource = [
-    { name: '张三', age: 30 },
-    { name: '李四', age: 25 },
+    { id: 1, name: '张三', age: 30 },
+    { id: 2, name: '李四', age: 25 },
   ]
 
   return (
     <ProTable
       columns={columns}
       dataSource={dataSource}
-      rowKey="name"
+      rowKey="id"
+      locale={zh_CN}
     />
   )
 }
 ```
 
-### 功能特性
-
-- **强大表格**: 基于 TanStack Table 构建，提供最大灵活性
-- **shadcn/ui 组件**: 美观、可访问的 UI 组件
-- **拖拽排序**: 使用 @dnd-kit 实现行和列重排序
-- **搜索筛选**: 高级搜索和筛选功能，支持本地和远程数据模式的默认行为
-- **分页**: 内置分页，支持自定义选项
-- **列设置**: 显示 / 隐藏列，拖拽重排序
-- **行选择**: 单选和多选行，支持批量操作，**跨页选中支持**（使用 `request` 或 `pagination.onChange` 时，选中状态会在切换页面时保留）
-- **可编辑行**: 内联编辑功能，支持多种值类型
-- **固定列**: 左右固定列，自动计算位置并应用柔和阴影效果（基于 TanStack Table column pinning）
-- **树形表格**: 层次数据展示，支持展开 / 收起行、自定义展开图标和手风琴模式
-- **国际化**: 内置 i18n 支持，提供中英文语言包
-- **横向滚动**: 可配置表格宽度，支持滚动
-- **复制功能**: 一键复制单元格内容
-- **文本省略**: 单行和多行文本截断，支持省略号
-- **提示框**: 单元格和表头悬停提示，支持自定义内容
-- **响应式**: 移动端友好设计
-- **TypeScript**: 完整的 TypeScript 支持
-
-### 示例
-
-#### 基础表格
+### 主要特性
+
+- ✨ 强大的表格：基于 TanStack Table v8
+- 🎨 精美组件：shadcn/ui 设计
+- 🔍 搜索筛选：自动处理本地/远程数据
+- 📄 分页支持：客户端和服务端分页
+- ✅ 行选择：支持跨页选中
+- 🎯 批量操作：灵活的批量操作配置
+- ✏️ 内联编辑：支持验证
+- 📌 固定列：左右固定，自动阴影
+- 🌳 树形表格：层次数据展示
+- 🔄 拖拽排序：行列拖拽重排
+- 📱 响应式设计：移动端友好
+- 🌐 国际化：内置中英文
+- 🎭 丰富类型：20+ 值类型
+- 💬 提示框：单元格和表头提示
+- 📏 文本省略：单行和多行截断
+- 🔧 TypeScript：完整类型支持
+
+### 批量操作示例
 
 ```tsx
+import { Trash2, Download, FileText } from 'lucide-react'
+
 <ProTable
-  columns={columns}
-  dataSource={dataSource}
+  rowSelection={{
+    type: 'checkbox',
+    batchActions: {
+      maxVisibleActions: 3,
+      actions: [
+        {
+          key: 'delete',
+          label: '删除',
+          icon: <Trash2 className="h-3 w-3 mr-1" />,
+          onClick: (rows) => console.log('删除:', rows),
+          variant: 'destructive',
+          clearSelection: true,
+        },
+        {
+          key: 'export',
+          label: '导出',
+          icon: <Download className="h-3 w-3 mr-1" />,
+          onClick: (rows) => console.log('导出:', rows),
+          variant: 'outline',
+        },
+        {
+          key: 'exportExcel',
+          label: '导出 Excel',
+          icon: <FileText className="h-3 w-3 mr-1" />,
+          onClick: (rows) => console.log('导出 Excel:', rows),
+          variant: 'outline',
+          isExportFormat: true,
+          showInMore: true,
+        },
+      ],
+    },
+  }}
+  dataSource={data}
   rowKey="id"
+  locale={zh_CN}
 />
 ```
 
-#### 带搜索
-
-表格提供了**默认搜索行为**，会自动工作：
-
-- **本地数据模式**（无 `request` 属性）：搜索值会自动转换为 TanStack Table 的 `columnFilters`，表格使用 `getFilteredRowModel()` 实时过滤数据。
-- **远程数据模式**（有 `request` 属性）：搜索会触发新的数据获取，搜索参数会传递给后端。
+### 更多文档
 
-默认过滤函数支持：
-- **文本类字段**：不区分大小写的字符串匹配（包含）
-- **枚举 / 筛选类字段**：精确匹配（例如 `valueEnum`、`filters`、`valueType: 'select' | 'status'`）
-- 基于数组的多选过滤（枚举 / 筛选类字段为精确匹配；文本类字段为包含匹配）
-- 自动处理空值 /null 值
+完整的中文文档和 API 参考，请查看英文部分。所有功能和 API 在中英文版本中都是一致的。
 
-```tsx
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  search={{
-    filterType: 'query',
-    searchText: '搜索',
-    resetText: '重置'
-  }}
-/>
-```
-
-**自定义搜索行为：**
+---
 
-您可以提供自定义的 `onSearch` 和 `onReset` 回调来覆盖默认行为：
+## Contributing
 
-```tsx
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  search={{
-    filterType: 'query',
-    onSearch: (values) => {
-      // 自定义搜索逻辑
-      console.log('搜索值:', values)
-    },
-    onReset: () => {
-      // 自定义重置逻辑
-      console.log('重置搜索')
-    }
-  }}
-/>
-```
-
-#### 带分页
-
-```tsx
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true
-  }}
-/>
-```
-
-#### 远程分页（配合 `request`）
-
-在**远程数据模式**（传入 `request`）下，分页规则如下：
-
-- **`total` 决定页码数量**：推荐让 `request` 返回 `{ total }`，也可以 / 同时传入 `pagination.total`。
-- **不要把 `pagination.current/pageSize` 写死**（例如 `current: 1`），除非你就是想把表格锁死在那一页；如果需要受控分页，请把它们放到 state 里，并在 `pagination.onChange` 里更新。
-
-**非受控（推荐：不需要外部同步分页状态时）**：
-
-```tsx
-<ProTable
-  columns={columns}
-  rowKey="id"
-  request={async (params) => {
-    // params 包含：current, pageSize, ...filters, ...sorter
-    const res = await fetchUsers(params)
-    return { data: res.items, total: res.total, success: true }
-  }}
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true,
-    showQuickJumper: true,
-  }}
-/>
-```
-
-**受控（需要把分页状态同步到外部 state / URL 时）**：
-
-```tsx
-function Page() {
-  const [pagination, setPagination] = useState({
-    current: 1,
-    pageSize: 10,
-    total: 0,
-  })
-
-  return (
-    <ProTable
-      columns={columns}
-      rowKey="id"
-      request={async (params) => {
-        const res = await fetchUsers(params)
-        setPagination((prev) => ({ ...prev, total: res.total }))
-        return { data: res.items, total: res.total, success: true }
-      }}
-      pagination={{
-        current: pagination.current,
-        pageSize: pagination.pageSize,
-        total: pagination.total,
-        showSizeChanger: true,
-        showQuickJumper: true,
-        onChange: (current, pageSize) => {
-          setPagination((prev) => ({ ...prev, current, pageSize }))
-        },
-      }}
-    />
-  )
-}
-```
-
-#### 服务端分页（不传 `request`，外部自行请求）
-
-如果你**不使用** `request`，但希望实现**服务端分页**（也就是 `dataSource` 只提供“当前页 items”），请设置
-`pagination.mode: 'server'`，避免 TanStack Table 再次 slice 导致第 2 页为空 / 数据错乱。
-
-```tsx
-function Page() {
-  const [pagination, setPagination] = useState({ current: 1, pageSize: 10, total: 0 })
-  const [data, setData] = useState<any[]>([])
-
-  const fetchPage = async (current: number, pageSize: number) => {
-    const res = await fetchUsers({ current, pageSize })
-    setData(res.items)
-    setPagination((prev) => ({ ...prev, current, pageSize, total: res.total }))
-  }
-
-  useEffect(() => {
-    void fetchPage(pagination.current, pagination.pageSize)
-  }, [])
-
-  return (
-    <ProTable
-      columns={columns}
-      rowKey="id"
-      dataSource={data}
-      pagination={{
-        mode: "server",
-        current: pagination.current,
-        pageSize: pagination.pageSize,
-        total: pagination.total,
-        onChange: (current, pageSize) => void fetchPage(current, pageSize),
-      }}
-    />
-  )
-}
-```
-
-#### 自定义分页渲染（`paginationRender`）
-
-当你想把分页 UI 放到任意布局 / 卡片里，并且仍复用 ProTable 内置分页状态 / 逻辑时，使用 `paginationRender`：
-
-- `paginationRender` 会拿到 `pagination`、`onChange`、`defaultDom`
-- 如果你是 **服务端分页模式**（`pagination.mode: 'server'`），务必同时提供 `pagination.onChange` 去请求数据
-
-```tsx
-<ProTable
-  columns={columns}
-  rowKey="id"
-  dataSource={data}
-  pagination={{
-    mode: "server",
-    current,
-    pageSize,
-    total,
-    onChange: (page, pageSize) => void fetchPage(page, pageSize),
-  }}
-  paginationRender={({ pagination, onChange, defaultDom }) => (
-    <div className="space-y-2">
-      <div className="flex items-center justify-between rounded border p-2">
-        <div className="text-sm text-muted-foreground">
-          自定义分页：第 {pagination.current} 页 / 每页 {pagination.pageSize} 条 / 共 {pagination.total} 条
-        </div>
-        <div className="flex gap-2">
-          <button onClick={() => onChange(Math.max(1, pagination.current - 1), pagination.pageSize)}>
-            上一页
-          </button>
-          <button onClick={() => onChange(pagination.current + 1, pagination.pageSize)}>
-            下一页
-          </button>
-        </div>
-      </div>
-      {defaultDom}
-    </div>
-  )}
-/>
-```
-
-#### 带国际化
-
-```tsx
-import { ProTable, zh_CN } from '@gulibs/react-vtable'
-
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  locale={zh_CN}
-/>
-```
-
-#### 带固定列
-
-固定列功能基于 TanStack Table 的 column pinning 实现。库会自动计算位置并应用柔和的阴影效果来标识固定列边界。
-
-```tsx
-<ProTable
-  columns={[
-    {
-      title: 'ID',
-      dataIndex: 'id',
-      key: 'id',
-      width: 80,
-      fixed: 'left'  // 固定在左侧
-    },
-    {
-      title: '姓名',
-      dataIndex: 'name',
-      key: 'name',
-      width: 120
-    },
-    {
-      title: '操作',
-      dataIndex: 'actions',
-      key: 'actions',
-      width: 100,
-      fixed: 'right'  // 固定在右侧
-    }
-  ]}
-  dataSource={dataSource}
-  rowKey="id"
-  scroll={{ x: 1000 }}  // 启用横向滚动
-  tableLayout="fixed"    // 固定列推荐使用 fixed 布局
-/>
-```
-
-**重要提示：**
-- 固定列需要设置 `width` 属性才能正确计算位置
-- 库会自动使用 TanStack Table 的 `getStart()` 和 `getAfter()` 方法计算位置
-- 最后一个左侧固定列和第一个右侧固定列会自动应用柔和的阴影效果
-- 无需额外 CSS - 所有样式都通过内联样式应用
-
-#### 带树形表格（可展开行）
-
-树形表格支持层次数据结构，可展开 / 收起行。数据结构应包含 `children` 属性（或自定义字段名）来存储嵌套行。
-
-```tsx
-<ProTable
-  columns={columns}
-  dataSource={[
-    {
-      id: 1,
-      name: '父节点',
-      children: [
-        { id: 11, name: '子节点 1' },
-        { id: 12, name: '子节点 2' }
-      ]
-    }
-  ]}
-  rowKey="id"
-  expandable={{
-    childrenColumnName: 'children',  // 默认: 'children'
-    defaultExpandAllRows: false,     // 默认展开所有行
-    defaultExpandedRowKeys: [1],     // 初始展开的行
-    accordion: false,                // 手风琴模式（同时只能展开一行）
-    showExpandColumn: true,          // 显示展开图标列
-    expandColumnWidth: 50,           // 展开列宽度
-    onExpand: (expanded, record) => {
-      console.log('展开:', expanded, record)
-    },
-    onExpandedRowsChange: (expandedRowKeys) => {
-      console.log('展开的行:', expandedRowKeys)
-    },
-    expandIcon: ({ expanded, onExpand, record }) => (
-      <Button onClick={onExpand}>
-        {expanded ? '▼' : '▶'}
-      </Button>
-    )
-  }}
-/>
-```
-
-**树形表格特性：**
-- **受控 / 非受控模式**: 使用 `expandedRowKeys` 实现受控模式，或使用 `defaultExpandedRowKeys` 实现非受控模式
-- **默认全部展开**: 设置 `defaultExpandAllRows: true` 来默认展开所有行
-- **手风琴模式**: 设置 `accordion: true` 来同时只允许展开一行
-- **自定义子字段**: 使用 `childrenColumnName` 指定自定义的子字段名（默认：`'children'`）
-- **自定义展开图标**: 提供自定义 `expandIcon` 函数来定制展开 / 收起图标
-- **展开回调**: 使用 `onExpand` 和 `onExpandedRowsChange` 来处理展开状态变化
-
-#### 带可编辑行
-
-```tsx
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  editable={{
-    type: 'multiple',
-    onSave: async (key, record, originRow) => {
-      console.log('保存:', { key, record, originRow })
-      // 处理保存逻辑
-    }
-  }}
-/>
-```
-
-#### 带行选择和批量操作
-
-```tsx
-<ProTable
-  columns={columns}
-  dataSource={dataSource}
-  rowKey="id"
-  rowSelection={{
-    type: 'checkbox',
-    onChange: (selectedRowKeys, selectedRows) => {
-      console.log('已选择:', selectedRowKeys, selectedRows)
-    },
-    batchActions: {
-      onDelete: (rows) => {
-        console.log('删除:', rows)
-      },
-      onExport: (rows) => {
-        console.log('导出:', rows)
-      }
-    }
-  }}
-/>
-```
-
-**跨页选中支持：**
-
-当使用 `request` 或 `pagination.onChange` 进行远程数据获取时，表格会自动维护跨页选中状态。这意味着：
-
-- 在某一页选择的行，在切换到其他页面时会保留
-- 批量操作栏会显示**所有页面**的选中总数
-- 当返回到之前访问过的页面时，之前的选中状态会自动恢复
-- `onChange` 回调会接收到所有页面的选中行 keys
-
-```tsx
-<ProTable
-  columns={columns}
-  rowKey="id"
-  request={async (params) => {
-    const res = await fetchUsers(params)
-    return { data: res.items, total: res.total, success: true }
-  }}
-  rowSelection={{
-    type: 'checkbox',
-    onChange: (selectedRowKeys, selectedRows) => {
-      // selectedRowKeys 包含所有页面的选中 keys
-      // selectedRows 仅包含当前页的行数据
-      console.log('所有页面选中的总数:', selectedRowKeys.length)
-    },
-    batchActions: {
-      onDelete: (rows) => {
-        // 这里只会收到当前页的行数据
-        // 如需操作所有选中的行，请使用 onChange 中的 selectedRowKeys
-        console.log('删除当前页行:', rows)
-      }
-    }
-  }}
-  pagination={{
-    pageSize: 10,
-    showSizeChanger: true,
-    onChange: (current, pageSize) => {
-      // 切换页面时，选中状态会自动保留
-    }
-  }}
-/>
-```
-
-**重要提示：**
-- 跨页选中在使用 `request` 或 `pagination.onChange` 时会自动生效
-- 使用 `dataSource`（本地数据）时，选中功能正常工作，但不需要跨页支持
-- 批量操作栏始终显示所有页面的选中总数
-- 如需对所有选中的行进行操作，请使用 `rowSelection.onChange` 获取所有选中的 keys
-
-**自动清空选中状态：**
-
-某些批量操作后，选中状态会自动清空：
-
-- **删除操作**：删除后自动清空选中状态（因为数据已被删除）
-- **归档操作**：归档后自动清空选中状态
-- **自定义操作**：可以通过 `clearSelection` 选项控制是否清空选中状态
-- **隐藏清空按钮**：可以通过 `hideClearButton` 选项隐藏清空按钮
-
-```tsx
-<ProTable
-  rowSelection={{
-    type: 'checkbox',
-    batchActions: {
-      onDelete: (rows) => {
-        // 删除操作 - 选中状态会自动清空
-        console.log('删除:', rows)
-      },
-      onArchive: (rows) => {
-        // 归档操作 - 选中状态会自动清空
-        console.log('归档:', rows)
-      },
-      // 如需隐藏清空按钮
-      hideClearButton: false,
-      customActions: [
-        {
-          key: 'approve',
-          label: '批量审批',
-          onClick: (rows) => {
-            console.log('审批:', rows)
-          },
-          // 控制操作后是否清空选中状态
-          clearSelection: true, // 设置为 true 表示操作后清空选中状态
-        },
-        {
-          key: 'export',
-          label: '导出',
-          onClick: (rows) => {
-            console.log('导出:', rows)
-          },
-          clearSelection: false, // 导出后保留选中状态（默认值）
-        }
-      ]
-    }
-  }}
-/>
-```
-
-#### 带文本省略和提示框
-
-```tsx
-<ProTable
-  columns={[
-    {
-      title: '描述',
-      dataIndex: 'description',
-      key: 'description',
-      width: 200,
-      // 单行省略，带提示框
-      ellipsis: true,
-      tooltip: true
-    },
-    {
-      title: '内容',
-      dataIndex: 'content',
-      key: 'content',
-      width: 250,
-      // 多行省略（2行），带提示框
-      ellipsis: {
-        multiline: true,
-        rows: 2
-      },
-      tooltip: true
-    },
-    {
-      title: '自定义提示',
-      dataIndex: 'name',
-      key: 'name',
-      width: 150,
-      ellipsis: true,
-      tooltip: {
-        content: (value, record) => `完整内容: ${record.fullName || value}`,
-        side: 'top',
-        delayDuration: 300
-      }
-    },
-    {
-      title: '表头省略',
-      dataIndex: 'email',
-      key: 'email',
-      width: 180,
-      // 表头独立的省略和提示配置
-      headerEllipsis: true,
-      headerTooltip: {
-        content: '这是完整的表头标题',
-        side: 'bottom'
-      },
-      // 单元格省略和提示
-      ellipsis: true,
-      tooltip: true
-    }
-  ]}
-  dataSource={dataSource}
-  rowKey="id"
-/>
-```
-
-### API 参考
-
-#### ProTable 属性
-
-| 属性 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `columns` | `ProColumn[]` | `[]` | 表格列定义 |
-| `dataSource` | `T[]` | `[]` | 表格数据源 |
-| `rowKey` | `string \| (record: T) => string` | `'id'` | 每行的唯一键 |
-| `loading` | `boolean` | `false` | 加载状态 |
-| `pagination` | `ProTablePagination \| false` | `false` | 分页配置 |
-| `search` | `ProTableSearch \| false` | `false` | 搜索表单配置 |
-| `rowSelection` | `ProTableRowSelection` | `undefined` | 行选择配置 |
-| `editable` | `ProTableEditable` | `undefined` | 可编辑行配置 |
-| `draggable` | `ProTableDraggable` | `undefined` | 拖拽配置 |
-| `expandable` | `ProTableExpandable \| false` | `undefined` | 树形表格展开配置 |
-| `scroll` | `{ x?: number \| true; y?: number \| string }` | `undefined` | 滚动配置 |
-| `tableLayout` | `'auto' \| 'fixed'` | `'auto'` | 表格布局模式 |
-| `locale` | `ProTableLocale` | `en_US` | 国际化语言包 |
-| `size` | `'small' \| 'middle' \| 'large'` | `'middle'` | 表格尺寸 |
-| `bordered` | `boolean` | `false` | 显示表格边框 |
-
-#### 列配置
-
-| 属性 | 类型 | 描述 |
-|------|------|------|
-| `title` | `string` | 列头文本 |
-| `dataIndex` | `string` | 数据字段名 |
-| `key` | `string` | 唯一列键 |
-| `width` | `number` | 列宽度（像素） |
-| `fixed` | `'left' \| 'right'` | 固定列位置 |
-| `sorter` | `boolean` | 启用排序 |
-| `editable` | `boolean` | 启用内联编辑 |
-| `copyable` | `boolean` | 启用复制到剪贴板 |
-| `ellipsis` | `boolean \| ProColumnEllipsis` | 启用文本省略（单行或多行） |
-| `tooltip` | `boolean \| ProColumnTooltip` | 启用悬停提示框 |
-| `headerEllipsis` | `boolean \| ProColumnEllipsis` | 启用表头省略（默认使用 `ellipsis`） |
-| `headerTooltip` | `boolean \| ProColumnTooltip` | 启用表头提示框（默认使用 `tooltip`） |
-| `search` | `boolean` | 包含在搜索表单中 |
-| `valueType` | `ProFieldValueType` | 值类型渲染 |
-| `valueEnum` | `Record<string, { text: string; status?: string }>` | 枚举值选择 |
-| `filters` | `Array<{ text: string; value: any }>` | 筛选选项 |
-| `render` | `(value: any, record: T, index: number) => ReactNode` | 自定义渲染函数 |
-
-#### render 函数与 valueType 优先级
-
-当同时配置 `render` 和 `valueType` 时，`render` 函数在表格单元格渲染中具有**优先权**。这允许您：
-
-- 使用 `valueType` 进行**搜索表单**渲染（例如，`valueType: "select"` 会在搜索表单中生成下拉选择框）
-- 使用自定义 `render` 函数进行**表格单元格**渲染（例如，自定义徽章、图标或复杂布局）
-
-**渲染优先级：**
-1. **`render` 函数**（如果提供）- 用于表格单元格渲染
-2. **`valueType`**（如果提供）- 当没有 `render` 时用于表格单元格渲染
-3. **默认渲染** - 原始值显示
-
-**示例：**
-
-```tsx
-const columns = [
-  {
-    title: "等级",
-    dataIndex: "level",
-    key: "level",
-    valueType: "select",  // 用于搜索表单
-    search: true,
-    valueEnum: {
-      "1": { text: "一级", status: "default" },
-      "2": { text: "二级", status: "default" },
-      "3": { text: "三级", status: "default" },
-    },
-    // 自定义渲染函数在表格单元格渲染中具有优先权
-    render: (_value, record) => {
-      const levelNum = parseInt(record.level);
-      const colors = [
-        "bg-blue-100 text-blue-800",
-        "bg-green-100 text-green-800",
-        "bg-yellow-100 text-yellow-800",
-      ];
-      return (
-        <Badge className={colors[levelNum - 1]}>
-          L{record.level}
-        </Badge>
-      );
-    },
-  },
-];
-```
-
-在这个示例中：
-- **搜索表单**：显示下拉选择框（因为 `valueType: "select"`）
-- **表格单元格**：显示自定义 Badge 组件（因为 `render` 函数）
-
-**注意**：`select` 类型的 `valueType` 在没有 `render` 函数时也支持使用 `valueEnum` 进行渲染。
-
-#### 省略号配置
-
-`ellipsis` 和 `headerEllipsis` 属性支持以下配置：
-
-```tsx
-// 单行省略
-ellipsis: true
-
-// 多行省略
-ellipsis: {
-  multiline: true,
-  rows: 2  // 行数（1-5）
-}
-```
-
-#### 提示框配置
-
-`tooltip` 和 `headerTooltip` 属性支持以下配置：
-
-```tsx
-// 简单提示框（显示单元格值）
-tooltip: true
-
-// 自定义提示框
-tooltip: {
-  content: '自定义提示文本',
-  side: 'top' | 'right' | 'bottom' | 'left',
-  align: 'start' | 'center' | 'end',
-  delayDuration: 300,
-  disabled: false
-}
-
-// 函数式提示框
-tooltip: {
-  content: (value, record, index) => `完整内容: ${value}\nID: ${record.id}`,
-  side: 'top'
-}
-```
-
-**注意**: 当 `ellipsis` 启用且 `tooltip` 为 `true` 时，如果文本被截断，提示框会自动显示完整的原始值（而不是渲染后的值）。
-
-#### 展开配置（树形表格）
-
-`expandable` 属性支持以下配置：
-
-```tsx
-expandable: {
-  // 自定义子字段名（默认: 'children'）
-  childrenColumnName?: string
-
-  // 默认展开的行 key 数组（非受控模式）
-  defaultExpandedRowKeys?: React.Key[]
-
-  // 当前展开的行 key 数组（受控模式）
-  expandedRowKeys?: React.Key[]
-
-  // 展开/收起回调
-  onExpand?: (expanded: boolean, record: T) => void
-
-  // 展开的行 key 变化回调
-  onExpandedRowsChange?: (expandedRowKeys: React.Key[]) => void
-
-  // 自定义展开图标
-  expandIcon?: (props: {
-    expanded: boolean
-    onExpand: () => void
-    record: T
-  }) => ReactNode
-
-  // 显示展开列（默认: true）
-  showExpandColumn?: boolean
-
-  // 展开列宽度（默认: 50）
-  expandColumnWidth?: number
-
-  // 默认展开所有行（默认: false）
-  defaultExpandAllRows?: boolean
-
-  // 手风琴模式 - 同时只能展开一行（默认: false）
-  accordion?: boolean
-}
-```
-
-### 开发
-
-```bash
-# 安装依赖
-pnpm install
-
-# 构建库
-pnpm run build
-
-# 启动开发服务器
-pnpm run dev
-```
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-### 许可证
+## Support
 
-MIT
+If you have any questions or need help, please open an issue on [GitHub](https://github.com/gulibs/react-vtable).