@gulibs/react-vtable 0.0.11 → 0.0.13

package/README.md

@@ -116,8 +116,9 @@ The table provides **default search behavior** that works automatically:
 - **Remote Data Mode** (with `request` prop): Search triggers a new data fetch with search parameters passed to the backend.
 
 The default filter function supports:
-- Case-insensitive string matching (contains)
-- Array-based multi-select filtering
+- 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
 
 ```tsx
@@ -164,14 +165,152 @@ You can provide custom `onSearch` and `onReset` callbacks to override the defaul
   dataSource={dataSource}
   rowKey="id"
   pagination={{
-    current: 1,
     pageSize: 10,
-    total: 100,
     showSizeChanger: true
   }}
 />
 ```
 
+#### Remote Pagination (with `request`)
+
+In **Remote Data Mode** (when you pass `request`), pagination works like this:
+
+- **`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`.
+
+**Uncontrolled (recommended if you don't need to control page state):**
+
+```tsx
+<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,
+  }}
+/>
+```
+
+**Controlled (when you need to sync pagination with external 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 }))
+        },
+      }}
+    />
+  )
+}
+```
+
+#### 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.
+
+```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),
+      }}
+    />
+  )
+}
+```
+
+#### Custom Pagination Rendering (`paginationRender`)
+
+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.
+
+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.
+
+```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>
+  )}
+/>
+```
+
 #### With Internationalization
 
 ```tsx
@@ -629,8 +768,9 @@ function App() {
 - **远程数据模式**（有 `request` 属性）：搜索会触发新的数据获取，搜索参数会传递给后端。
 
 默认过滤函数支持：
-- 不区分大小写的字符串匹配（包含）
-- 基于数组的多选过滤
+- **文本类字段**：不区分大小写的字符串匹配（包含）
+- **枚举 / 筛选类字段**：精确匹配（例如 `valueEnum`、`filters`、`valueType: 'select' | 'status'`）
+- 基于数组的多选过滤（枚举 / 筛选类字段为精确匹配；文本类字段为包含匹配）
 - 自动处理空值 /null 值
 
 ```tsx
@@ -677,14 +817,149 @@ function App() {
   dataSource={dataSource}
   rowKey="id"
   pagination={{
-    current: 1,
     pageSize: 10,
-    total: 100,
     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

package/dist/components/loading-state.d.ts

@@ -5,7 +5,7 @@ interface LoadingStateProps {
     draggable?: boolean;
     /** 是否显示选择列 */
     rowSelection?: boolean;
-    /** 加载行数，默认 5 */
+    /** 加载行数，默认 10（更贴近常用 pageSize，减少翻页加载时的高度跳动） */
     rowCount?: number;
 }
 export declare function LoadingState({ columnCount, draggable, rowSelection, rowCount, }: LoadingStateProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/loading-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loading-state.d.ts","sourceRoot":"","sources":["../../lib/components/loading-state.tsx"],"names":[],"mappings":"AAGA,UAAU,iBAAiB;IACzB,SAAS;IACT,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,EAC3B,WAAW,EACX,SAAiB,EACjB,YAAoB,EACpB,QAAY,GACb,EAAE,iBAAiB,2CAwBnB"}
+{"version":3,"file":"loading-state.d.ts","sourceRoot":"","sources":["../../lib/components/loading-state.tsx"],"names":[],"mappings":"AAGA,UAAU,iBAAiB;IACzB,SAAS;IACT,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,EAC3B,WAAW,EACX,SAAiB,EACjB,YAAoB,EACpB,QAAa,GACd,EAAE,iBAAiB,2CAwBnB"}

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

@@ -22,6 +22,9 @@ type ProTableActionType<T> = {
         data: T[];
         total?: number;
     };
+} | {
+    type: 'SET_TOTAL';
+    payload: number;
 } | {
     type: 'SET_PAGINATION';
     payload: {

package/dist/hooks/use-pro-table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-pro-table.d.ts","sourceRoot":"","sources":["../../lib/hooks/use-pro-table.ts"],"names":[],"mappings":"AAaA,OAAO,EAAiE,KAAK,GAAG,EAAE,MAAM,OAAO,CAAA;AAC/F,OAAO,KAAK,EACR,cAAc,EACd,aAAa,EAEhB,MAAM,SAAS,CAAA;AAGhB,UAAU,aAAa,CAAC,CAAC;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,eAAe,EAAE,GAAG,EAAE,CAAA;IACtB,YAAY,EAAE,CAAC,EAAE,CAAA;IACjB,UAAU,EAAE,GAAG,GAAG,IAAI,CAAA;IACtB,aAAa,EAAE,CAAC,GAAG,IAAI,CAAA;CAC1B;AAED,KAAK,kBAAkB,CAAC,CAAC,IACnB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE;QAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE;QAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAAC,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE;QAAE,GAAG,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAA;AAoEvB,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrD,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC;;;;;;0CAyS8B,MAAM,YAAY,MAAM;+BAUnC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;EAyHhE"}
+{"version":3,"file":"use-pro-table.d.ts","sourceRoot":"","sources":["../../lib/hooks/use-pro-table.ts"],"names":[],"mappings":"AAaA,OAAO,EAAiE,KAAK,GAAG,EAAE,MAAM,OAAO,CAAA;AAC/F,OAAO,KAAK,EACR,cAAc,EACd,aAAa,EAEhB,MAAM,SAAS,CAAA;AAGhB,UAAU,aAAa,CAAC,CAAC;IACrB,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC3B,eAAe,EAAE,GAAG,EAAE,CAAA;IACtB,YAAY,EAAE,CAAC,EAAE,CAAA;IACjB,UAAU,EAAE,GAAG,GAAG,IAAI,CAAA;IACtB,aAAa,EAAE,CAAC,GAAG,IAAI,CAAA;CAC1B;AAED,KAAK,kBAAkB,CAAC,CAAC,IACnB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE;QAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE;QAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAAC,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE;QAAE,GAAG,EAAE,GAAG,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAA;AAyEvB,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACrD,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC;;;;;;0CA6W8B,MAAM,YAAY,MAAM;+BAUnC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;EA2HhE"}