dishui 0.0.84 → 0.0.89

package/dist/hooks/useControllableState.d.ts

@@ -1,20 +1,12 @@
 /**
- * A hook for managing controllable state that can be either controlled (by parent via props)
- * or uncontrolled (managed internally). Handles bidirectional sync between external props
- * and internal state without causing infinite loops.
- *
- * Key design decisions:
- * - Returns the raw useState setter → always stable reference, safe for useMemo deps
- * - Uses a version counter to distinguish internal vs external state changes
- * - onChange is called via useEffect (not inside state updater) for React safety
- * - onChangeRef avoids stale closures for the onChange callback
- *
- * @param externalValue - The value from props (controlled mode when onChange is provided)
- * @param onChange - Optional callback to notify parent of internal state changes
- * @param isEqual - Optional equality check (defaults to reference equality)
- * @returns [currentValue, setValue] - The current value and a stable setter
+ * A defined externalValue is strictly controlled, even without onChange (read-only).
+ * undefined opts into internal state; defaultValue is read only on mount.
+ * onChange reports distinct setter requests synchronously, never prop updates.
+ * Controlled functional updates use the last committed prop, not a pending request.
+ * Do not switch modes: switching back resumes the retained internal state.
  */
 export declare function useControllableState<T>(externalValue: T, onChange?: (value: T) => void, isEqual?: (a: T, b: T) => boolean): [T, React.Dispatch<React.SetStateAction<T>>];
+export declare function useControllableState<T>(externalValue: T | undefined, onChange: ((value: T) => void) | undefined, isEqual: ((a: T, b: T) => boolean) | undefined, defaultValue: T): [T, React.Dispatch<React.SetStateAction<T>>];
 /**
  * Structural deep equality for the plain values used by DataTable state
  * (arrays, plain objects, primitives). Avoids the overhead and edge cases of

package/dist/hooks/useControllableState.js

@@ -1,20 +1,26 @@
-import { useCallback as e, useEffect as t, useRef as n, useState as r } from "react";
+import { useCallback as e, useLayoutEffect as t, useRef as n, useState as r } from "react";
 //#region src/hooks/useControllableState.ts
-function i(i, a, o = (e, t) => e === t) {
-	let [s, c] = r(i), l = n(a);
-	l.current = a;
-	let u = n(i), d = n(0), f = n(0);
-	o(u.current, i) || (u.current = i, c(i));
-	let p = e((e) => {
-		d.current++, c(e);
-	}, []), m = n(!0);
+function i(i, a, o = Object.is, s) {
+	let [c, l] = r(() => i === void 0 ? s : i), u = i !== void 0, d = u ? i : c, f = n({
+		value: d,
+		controlled: u,
+		onChange: a,
+		isEqual: o
+	});
 	return t(() => {
-		if (m.current) {
-			m.current = !1;
-			return;
-		}
-		d.current !== f.current && (f.current = d.current, l.current?.(s));
-	}, [s]), [s, p];
+		f.current = {
+			value: d,
+			controlled: u,
+			onChange: a,
+			isEqual: o
+		};
+	}), [d, e((e) => {
+		let t = f.current, n = typeof e == "function" ? e(t.value) : e;
+		t.isEqual(t.value, n) || (t.controlled || (f.current = {
+			...t,
+			value: n
+		}, l(() => n)), t.onChange?.(n));
+	}, [])];
 }
 function a(e, t) {
 	if (Object.is(e, t)) return !0;

package/dist/hooks/useControllableState.js.map

@@ -1 +1 @@
-{"version":3,"file":"useControllableState.js","names":[],"sources":["../../src/hooks/useControllableState.ts"],"sourcesContent":["import { useState, useRef, useCallback, useEffect } from 'react';\n\n/**\n * A hook for managing controllable state that can be either controlled (by parent via props)\n * or uncontrolled (managed internally). Handles bidirectional sync between external props\n * and internal state without causing infinite loops.\n *\n * Key design decisions:\n * - Returns the raw useState setter → always stable reference, safe for useMemo deps\n * - Uses a version counter to distinguish internal vs external state changes\n * - onChange is called via useEffect (not inside state updater) for React safety\n * - onChangeRef avoids stale closures for the onChange callback\n *\n * @param externalValue - The value from props (controlled mode when onChange is provided)\n * @param onChange - Optional callback to notify parent of internal state changes\n * @param isEqual - Optional equality check (defaults to reference equality)\n * @returns [currentValue, setValue] - The current value and a stable setter\n */\nexport function useControllableState<T>(\n    externalValue: T,\n    onChange?: (value: T) => void,\n    isEqual: (a: T, b: T) => boolean = (a, b) => a === b\n): [T, React.Dispatch<React.SetStateAction<T>>] {\n    const [internalValue, setInternalValue] = useState<T>(externalValue);\n\n    // Always-current ref for onChange to avoid stale closures\n    const onChangeRef = useRef(onChange);\n    onChangeRef.current = onChange;\n\n    // Track external value to detect parent-driven changes\n    const prevExternalRef = useRef<T>(externalValue);\n\n    // Version counter: incremented only by internal (user-driven) changes\n    const internalVersionRef = useRef(0);\n    const notifiedVersionRef = useRef(0);\n\n    // Sync external → internal (during render, no extra render cycle)\n    if (!isEqual(prevExternalRef.current, externalValue)) {\n        prevExternalRef.current = externalValue;\n        setInternalValue(externalValue);\n    }\n\n    // Wrap setter to track internal changes via version counter\n    const setValue = useCallback(\n        (updater: React.SetStateAction<T>) => {\n            internalVersionRef.current++;\n            setInternalValue(updater);\n        },\n        []\n    );\n\n    // Notify parent only when value changed from an internal action (not external sync)\n    const isFirstRenderRef = useRef(true);\n    useEffect(() => {\n        if (isFirstRenderRef.current) {\n            isFirstRenderRef.current = false;\n            return;\n        }\n        if (internalVersionRef.current !== notifiedVersionRef.current) {\n            notifiedVersionRef.current = internalVersionRef.current;\n            onChangeRef.current?.(internalValue);\n        }\n    }, [internalValue]);\n\n    return [internalValue, setValue];\n}\n\n/**\n * Structural deep equality for the plain values used by DataTable state\n * (arrays, plain objects, primitives). Avoids the overhead and edge cases of\n * `JSON.stringify` (key ordering, `undefined`, functions) that the previous\n * implementation relied on.\n */\nexport function deepEqual<T>(a: T, b: T): boolean {\n    if (Object.is(a, b)) return true;\n    if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {\n        return false;\n    }\n\n    const aIsArray = Array.isArray(a);\n    const bIsArray = Array.isArray(b);\n    if (aIsArray !== bIsArray) return false;\n\n    if (aIsArray && bIsArray) {\n        if (a.length !== b.length) return false;\n        for (let i = 0; i < a.length; i++) {\n            if (!deepEqual(a[i], b[i])) return false;\n        }\n        return true;\n    }\n\n    const aKeys = Object.keys(a as Record<string, unknown>);\n    const bKeys = Object.keys(b as Record<string, unknown>);\n    if (aKeys.length !== bKeys.length) return false;\n    for (const key of aKeys) {\n        if (!Object.prototype.hasOwnProperty.call(b, key)) return false;\n        if (!deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) {\n            return false;\n        }\n    }\n    return true;\n}\n"],"mappings":";;AAkBA,SAAgB,EACZ,GACA,GACA,KAAoC,GAAG,MAAM,MAAM,GACP;CAC5C,IAAM,CAAC,GAAe,KAAoB,EAAY,CAAa,GAG7D,IAAc,EAAO,CAAQ;CACnC,EAAY,UAAU;CAGtB,IAAM,IAAkB,EAAU,CAAa,GAGzC,IAAqB,EAAO,CAAC,GAC7B,IAAqB,EAAO,CAAC;CAGnC,AAAK,EAAQ,EAAgB,SAAS,CAAa,MAC/C,EAAgB,UAAU,GAC1B,EAAiB,CAAa;CAIlC,IAAM,IAAW,GACZ,MAAqC;EAElC,AADA,EAAmB,WACnB,EAAiB,CAAO;CAC5B,GACA,CAAC,CACL,GAGM,IAAmB,EAAO,EAAI;CAYpC,OAXA,QAAgB;EACZ,IAAI,EAAiB,SAAS;GAC1B,EAAiB,UAAU;GAC3B;EACJ;EACA,AAAI,EAAmB,YAAY,EAAmB,YAClD,EAAmB,UAAU,EAAmB,SAChD,EAAY,UAAU,CAAa;CAE3C,GAAG,CAAC,CAAa,CAAC,GAEX,CAAC,GAAe,CAAQ;AACnC;AAQA,SAAgB,EAAa,GAAM,GAAe;CAC9C,IAAI,OAAO,GAAG,GAAG,CAAC,GAAG,OAAO;CAC5B,IAAI,OAAO,KAAM,aAAY,KAAc,OAAO,KAAM,aAAY,GAChE,OAAO;CAGX,IAAM,IAAW,MAAM,QAAQ,CAAC,GAC1B,IAAW,MAAM,QAAQ,CAAC;CAChC,IAAI,MAAa,GAAU,OAAO;CAElC,IAAI,KAAY,GAAU;EACtB,IAAI,EAAE,WAAW,EAAE,QAAQ,OAAO;EAClC,KAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,KAC1B,IAAI,CAAC,EAAU,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO;EAEvC,OAAO;CACX;CAEA,IAAM,IAAQ,OAAO,KAAK,CAA4B,GAChD,IAAQ,OAAO,KAAK,CAA4B;CACtD,IAAI,EAAM,WAAW,EAAM,QAAQ,OAAO;CAC1C,KAAK,IAAM,KAAO,GAEd,IADI,CAAC,OAAO,UAAU,eAAe,KAAK,GAAG,CAAG,KAC5C,CAAC,EAAW,EAA8B,IAAO,EAA8B,EAAI,GACnF,OAAO;CAGf,OAAO;AACX"}
+{"version":3,"file":"useControllableState.js","names":[],"sources":["../../src/hooks/useControllableState.ts"],"sourcesContent":["import { useState, useRef, useCallback, useLayoutEffect } from 'react';\n\n/**\n * A defined externalValue is strictly controlled, even without onChange (read-only).\n * undefined opts into internal state; defaultValue is read only on mount.\n * onChange reports distinct setter requests synchronously, never prop updates.\n * Controlled functional updates use the last committed prop, not a pending request.\n * Do not switch modes: switching back resumes the retained internal state.\n */\nexport function useControllableState<T>(\n    externalValue: T,\n    onChange?: (value: T) => void,\n    isEqual?: (a: T, b: T) => boolean,\n): [T, React.Dispatch<React.SetStateAction<T>>];\nexport function useControllableState<T>(\n    externalValue: T | undefined,\n    onChange: ((value: T) => void) | undefined,\n    isEqual: ((a: T, b: T) => boolean) | undefined,\n    defaultValue: T,\n): [T, React.Dispatch<React.SetStateAction<T>>];\nexport function useControllableState<T>(\n    externalValue: T | undefined,\n    onChange?: (value: T) => void,\n    isEqual: (a: T, b: T) => boolean = Object.is,\n    defaultValue?: T,\n): [T, React.Dispatch<React.SetStateAction<T>>] {\n    const [internalValue, setInternalValue] = useState<T>(() =>\n        externalValue !== undefined ? externalValue : defaultValue as T,\n    );\n    const controlled = externalValue !== undefined;\n    const value = controlled ? externalValue : internalValue;\n    const committed = useRef({ value, controlled, onChange, isEqual });\n\n    // Abandoned renders must not publish props/callbacks to the stable setter.\n    useLayoutEffect(() => {\n        committed.current = { value, controlled, onChange, isEqual };\n    });\n\n    const setValue = useCallback((updater: React.SetStateAction<T>) => {\n        const current = committed.current;\n        const next = typeof updater === 'function'\n            ? (updater as (previous: T) => T)(current.value)\n            : updater;\n        if (current.isEqual(current.value, next)) return;\n        if (!current.controlled) {\n            // Resolve outside React's updater so batched requests compose without\n            // replaying notifications in StrictMode.\n            committed.current = { ...current, value: next };\n            setInternalValue(() => next);\n        }\n        current.onChange?.(next);\n    }, []);\n\n    return [value, setValue];\n}\n\n/**\n * Structural deep equality for the plain values used by DataTable state\n * (arrays, plain objects, primitives). Avoids the overhead and edge cases of\n * `JSON.stringify` (key ordering, `undefined`, functions) that the previous\n * implementation relied on.\n */\nexport function deepEqual<T>(a: T, b: T): boolean {\n    if (Object.is(a, b)) return true;\n    if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {\n        return false;\n    }\n\n    const aIsArray = Array.isArray(a);\n    const bIsArray = Array.isArray(b);\n    if (aIsArray !== bIsArray) return false;\n\n    if (aIsArray && bIsArray) {\n        if (a.length !== b.length) return false;\n        for (let i = 0; i < a.length; i++) {\n            if (!deepEqual(a[i], b[i])) return false;\n        }\n        return true;\n    }\n\n    const aKeys = Object.keys(a as Record<string, unknown>);\n    const bKeys = Object.keys(b as Record<string, unknown>);\n    if (aKeys.length !== bKeys.length) return false;\n    for (const key of aKeys) {\n        if (!Object.prototype.hasOwnProperty.call(b, key)) return false;\n        if (!deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) {\n            return false;\n        }\n    }\n    return true;\n}\n"],"mappings":";;AAoBA,SAAgB,EACZ,GACA,GACA,IAAmC,OAAO,IAC1C,GAC4C;CAC5C,IAAM,CAAC,GAAe,KAAoB,QACtC,MAAkB,KAAA,IAA4B,IAAhB,CAClC,GACM,IAAa,MAAkB,KAAA,GAC/B,IAAQ,IAAa,IAAgB,GACrC,IAAY,EAAO;EAAE;EAAO;EAAY;EAAU;CAAQ,CAAC;CAsBjE,OAnBA,QAAsB;EAClB,EAAU,UAAU;GAAE;GAAO;GAAY;GAAU;EAAQ;CAC/D,CAAC,GAiBM,CAAC,GAfS,GAAa,MAAqC;EAC/D,IAAM,IAAU,EAAU,SACpB,IAAO,OAAO,KAAY,aACzB,EAA+B,EAAQ,KAAK,IAC7C;EACF,EAAQ,QAAQ,EAAQ,OAAO,CAAI,MAClC,EAAQ,eAGT,EAAU,UAAU;GAAE,GAAG;GAAS,OAAO;EAAK,GAC9C,QAAuB,CAAI,IAE/B,EAAQ,WAAW,CAAI;CAC3B,GAAG,CAAC,CAEW,CAAQ;AAC3B;AAQA,SAAgB,EAAa,GAAM,GAAe;CAC9C,IAAI,OAAO,GAAG,GAAG,CAAC,GAAG,OAAO;CAC5B,IAAI,OAAO,KAAM,aAAY,KAAc,OAAO,KAAM,aAAY,GAChE,OAAO;CAGX,IAAM,IAAW,MAAM,QAAQ,CAAC,GAC1B,IAAW,MAAM,QAAQ,CAAC;CAChC,IAAI,MAAa,GAAU,OAAO;CAElC,IAAI,KAAY,GAAU;EACtB,IAAI,EAAE,WAAW,EAAE,QAAQ,OAAO;EAClC,KAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,KAC1B,IAAI,CAAC,EAAU,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO;EAEvC,OAAO;CACX;CAEA,IAAM,IAAQ,OAAO,KAAK,CAA4B,GAChD,IAAQ,OAAO,KAAK,CAA4B;CACtD,IAAI,EAAM,WAAW,EAAM,QAAQ,OAAO;CAC1C,KAAK,IAAM,KAAO,GAEd,IADI,CAAC,OAAO,UAAU,eAAe,KAAK,GAAG,CAAG,KAC5C,CAAC,EAAW,EAA8B,IAAO,EAA8B,EAAI,GACnF,OAAO;CAGf,OAAO;AACX"}

package/dist/hooks/useTableColumns.d.ts

@@ -67,8 +67,8 @@ export interface ColumnConfig<T extends object = any> {
  * ]);
  * ```
  *
- * @param configs - 列配置数组
- * @param deps   - 额外依赖项（当 cell 渲染器依赖外部状态时使用）
+ * @param configs - 列配置数组；按引用跟踪更新。需要缓存时由调用方用 useMemo 稳定配置。
+ * @param deps   - 额外依赖项，不能代替 configs；每次渲染保持依赖项数量不变。
  */
-export declare function useTableColumns<T extends object>(configs: ColumnConfig<T>[], deps?: any[]): ColumnDef<T, any>[];
+export declare function useTableColumns<T extends object>(configs: ColumnConfig<T>[], deps?: readonly unknown[]): ColumnDef<T, any>[];
 export default useTableColumns;

package/dist/hooks/useTableColumns.js

@@ -1,4 +1,4 @@
-import { createActionColumn as e, createColumn as t, createComputedColumn as n, createSelectionColumn as r, dateSort as i, numericSort as a } from "../data-table.js";
+import { createActionColumn as e, createColumn as t, createComputedColumn as n, createSelectionColumn as r, dateSort as i, numericSort as a } from "../components/pro/DataTable/utils.js";
 import { useMemo as o } from "react";
 //#region src/hooks/useTableColumns.ts
 function s(o) {
@@ -35,7 +35,7 @@ function s(o) {
 	return l === "computed" ? n(s.startsWith("_") ? s.slice(1) : s, c, g, x) : t(s, c, x);
 }
 function c(e, t = []) {
-	return o(() => e.map(s), t);
+	return o(() => e.map(s), [e, ...t]);
 }
 //#endregion
 export { c as default, c as useTableColumns };

package/dist/hooks/useTableColumns.js.map

@@ -1 +1 @@
-{"version":3,"file":"useTableColumns.js","names":[],"sources":["../../src/hooks/useTableColumns.ts"],"sourcesContent":["import { useMemo, ReactNode } from 'react';\nimport { ColumnDef, Row, SortingFn } from '../components/pro/DataTable/tanstack-table';\nimport {\n    createColumn,\n    createComputedColumn,\n    createActionColumn,\n    createSelectionColumn,\n    numericSort,\n    dateSort,\n    stringSort,\n} from '../components/pro/DataTable';\n\n/**\n * 列筛选配置\n */\nexport interface ColumnFilterConfig {\n    /** 筛选类型 */\n    type: 'text' | 'select' | 'number' | 'dateRange';\n    /** 下拉选项（仅 select 类型使用） */\n    options?: { value: string; label: string }[];\n}\n\n/**\n * 列配置项（JSON 驱动）\n */\nexport interface ColumnConfig<T extends object = any> {\n    /** 字段名 / accessorKey。特殊值: '_selection' 自动创建选择列 */\n    key: string;\n    /** 列标题 */\n    header: string;\n    /**\n     * 列类型\n     * - 'text'      普通文本列（默认）\n     * - 'number'    数值列，自动使用 numericSort\n     * - 'date'      日期列，自动使用 dateSort\n     * - 'computed'  计算列，需提供 accessorFn\n     * - 'action'    操作列，禁用排序\n     * - 'selection' 选择列（含全选复选框）\n     */\n    type?: 'text' | 'number' | 'date' | 'computed' | 'action' | 'selection';\n    /** 是否可排序，默认 true（action/selection 默认 false） */\n    sortable?: boolean;\n    /** 自定义单元格渲染 */\n    cell?: ((info: any) => ReactNode) | ((props: { row: Row<T> }) => ReactNode);\n    /** 筛选配置 */\n    filter?: ColumnFilterConfig;\n    /** 列宽 */\n    width?: number;\n    /** 最小列宽 */\n    minWidth?: number;\n    /** 最大列宽 */\n    maxWidth?: number;\n    /** 计算列的 accessorFn（仅 type='computed' 时使用） */\n    accessorFn?: (row: T) => any;\n    /** 自定义排序函数 */\n    sortingFn?: SortingFn<any>;\n    /** 任意额外选项，会被合并到最终 ColumnDef 中 */\n    extra?: Partial<ColumnDef<T, any>>;\n}\n\n/**\n * 将单个 ColumnConfig 转换为 ColumnDef\n */\nfunction buildColumnDef<T extends object>(config: ColumnConfig<T>): ColumnDef<T, any> {\n    const { key, header, type = 'text', sortable, cell, filter, width, minWidth, maxWidth, accessorFn, sortingFn, extra } = config;\n\n    // 选择列\n    if (type === 'selection') {\n        return createSelectionColumn<T>(extra);\n    }\n\n    // 操作列\n    if (type === 'action') {\n        return createActionColumn<T>({\n            id: key.startsWith('_') ? 'actions' : key,\n            header,\n            cell: cell as any,\n            ...(width !== undefined ? { size: width } : {}),\n            ...(minWidth !== undefined ? { minSize: minWidth } : {}),\n            ...(maxWidth !== undefined ? { maxSize: maxWidth } : {}),\n            ...extra,\n        });\n    }\n\n    // 构建 meta（筛选信息）\n    const meta: Record<string, any> = {};\n    if (filter) {\n        meta.filterType = filter.type;\n        if (filter.options) {\n            meta.filterOptions = filter.options;\n        }\n    }\n\n    // 自动选择排序函数\n    let resolvedSortingFn: SortingFn<any> | undefined = sortingFn;\n    if (!resolvedSortingFn) {\n        switch (type) {\n            case 'number':\n                resolvedSortingFn = numericSort;\n                break;\n            case 'date':\n                resolvedSortingFn = dateSort;\n                break;\n            // 'text' 和 'computed' 使用默认排序\n        }\n    }\n\n    // 基础选项（v9：使用 sortFn）\n    const baseOptions: Partial<ColumnDef<T, any>> = {\n        ...(cell !== undefined ? { cell: cell as any } : {}),\n        ...(resolvedSortingFn ? { sortFn: resolvedSortingFn } : {}),\n        ...(sortable === false ? { enableSorting: false } : {}),\n        ...(Object.keys(meta).length > 0 ? { meta } : {}),\n        ...(width !== undefined ? { size: width } : {}),\n        ...(minWidth !== undefined ? { minSize: minWidth } : {}),\n        ...(maxWidth !== undefined ? { maxSize: maxWidth } : {}),\n        ...extra,\n    };\n\n    // 计算列\n    if (type === 'computed') {\n        return createComputedColumn<T>(\n            key.startsWith('_') ? key.slice(1) : key,\n            header,\n            accessorFn,\n            baseOptions\n        );\n    }\n\n    // 普通列 / number / date\n    return createColumn<T>(key, header, baseOptions);\n}\n\n/**\n * useTableColumns - 通过 JSON 配置数组快速创建 DataTable 列定义\n *\n * @example\n * ```tsx\n * const columns = useTableColumns<Order>([\n *   { key: '_selection', type: 'selection', header: '' },\n *   { key: 'orderNumber', header: '订单编号', filter: { type: 'text' } },\n *   { key: 'total', header: '总金额', type: 'number',\n *     cell: info => `¥${info.getValue<number>().toFixed(2)}`,\n *     filter: { type: 'number' } },\n *   { key: '_actions', type: 'action', header: '操作',\n *     cell: ({ row }) => <button>查看</button> }\n * ]);\n * ```\n *\n * @param configs - 列配置数组\n * @param deps   - 额外依赖项（当 cell 渲染器依赖外部状态时使用）\n */\nexport function useTableColumns<T extends object>(\n    configs: ColumnConfig<T>[],\n    deps: any[] = []\n): ColumnDef<T, any>[] {\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    return useMemo(() => configs.map(buildColumnDef), deps);\n}\n\nexport default useTableColumns;\n"],"mappings":";;;AA+DA,SAAS,EAAiC,GAA4C;CAClF,IAAM,EAAE,QAAK,WAAQ,UAAO,QAAQ,aAAU,SAAM,WAAQ,UAAO,aAAU,aAAU,eAAY,cAAW,aAAU;CAGxH,IAAI,MAAS,aACT,OAAO,EAAyB,CAAK;CAIzC,IAAI,MAAS,UACT,OAAO,EAAsB;EACzB,IAAI,EAAI,WAAW,GAAG,IAAI,YAAY;EACtC;EACM;EACN,GAAI,MAAU,KAAA,IAA8B,CAAC,IAAnB,EAAE,MAAM,EAAM;EACxC,GAAI,MAAa,KAAA,IAAoC,CAAC,IAAzB,EAAE,SAAS,EAAS;EACjD,GAAI,MAAa,KAAA,IAAoC,CAAC,IAAzB,EAAE,SAAS,EAAS;EACjD,GAAG;CACP,CAAC;CAIL,IAAM,IAA4B,CAAC;CACnC,AAAI,MACA,EAAK,aAAa,EAAO,MACrB,EAAO,YACP,EAAK,gBAAgB,EAAO;CAKpC,IAAI,IAAgD;CACpD,IAAI,CAAC,GACD,QAAQ,GAAR;EACI,KAAK;GACD,IAAoB;GACpB;EACJ,KAAK,QACD,IAAoB;CAG5B;CAIJ,IAAM,IAA0C;EAC5C,GAAI,MAAS,KAAA,IAAoC,CAAC,IAAzB,EAAQ,QAAY;EAC7C,GAAI,IAAoB,EAAE,QAAQ,EAAkB,IAAI,CAAC;EACzD,GAAI,MAAa,KAAQ,EAAE,eAAe,GAAM,IAAI,CAAC;EACrD,GAAI,OAAO,KAAK,CAAI,CAAC,CAAC,SAAS,IAAI,EAAE,QAAK,IAAI,CAAC;EAC/C,GAAI,MAAU,KAAA,IAA8B,CAAC,IAAnB,EAAE,MAAM,EAAM;EACxC,GAAI,MAAa,KAAA,IAAoC,CAAC,IAAzB,EAAE,SAAS,EAAS;EACjD,GAAI,MAAa,KAAA,IAAoC,CAAC,IAAzB,EAAE,SAAS,EAAS;EACjD,GAAG;CACP;CAaA,OAVI,MAAS,aACF,EACH,EAAI,WAAW,GAAG,IAAI,EAAI,MAAM,CAAC,IAAI,GACrC,GACA,GACA,CACJ,IAIG,EAAgB,GAAK,GAAQ,CAAW;AACnD;AAqBA,SAAgB,EACZ,GACA,IAAc,CAAC,GACI;CAEnB,OAAO,QAAc,EAAQ,IAAI,CAAc,GAAG,CAAI;AAC1D"}
+{"version":3,"file":"useTableColumns.js","names":[],"sources":["../../src/hooks/useTableColumns.ts"],"sourcesContent":["import { useMemo, ReactNode } from 'react';\nimport { ColumnDef, Row, SortingFn } from '../components/pro/DataTable/tanstack-table';\nimport {\n    createColumn,\n    createComputedColumn,\n    createActionColumn,\n    createSelectionColumn,\n    numericSort,\n    dateSort,\n} from '../components/pro/DataTable/utils';\n\n/**\n * 列筛选配置\n */\nexport interface ColumnFilterConfig {\n    /** 筛选类型 */\n    type: 'text' | 'select' | 'number' | 'dateRange';\n    /** 下拉选项（仅 select 类型使用） */\n    options?: { value: string; label: string }[];\n}\n\n/**\n * 列配置项（JSON 驱动）\n */\nexport interface ColumnConfig<T extends object = any> {\n    /** 字段名 / accessorKey。特殊值: '_selection' 自动创建选择列 */\n    key: string;\n    /** 列标题 */\n    header: string;\n    /**\n     * 列类型\n     * - 'text'      普通文本列（默认）\n     * - 'number'    数值列，自动使用 numericSort\n     * - 'date'      日期列，自动使用 dateSort\n     * - 'computed'  计算列，需提供 accessorFn\n     * - 'action'    操作列，禁用排序\n     * - 'selection' 选择列（含全选复选框）\n     */\n    type?: 'text' | 'number' | 'date' | 'computed' | 'action' | 'selection';\n    /** 是否可排序，默认 true（action/selection 默认 false） */\n    sortable?: boolean;\n    /** 自定义单元格渲染 */\n    cell?: ((info: any) => ReactNode) | ((props: { row: Row<T> }) => ReactNode);\n    /** 筛选配置 */\n    filter?: ColumnFilterConfig;\n    /** 列宽 */\n    width?: number;\n    /** 最小列宽 */\n    minWidth?: number;\n    /** 最大列宽 */\n    maxWidth?: number;\n    /** 计算列的 accessorFn（仅 type='computed' 时使用） */\n    accessorFn?: (row: T) => any;\n    /** 自定义排序函数 */\n    sortingFn?: SortingFn<any>;\n    /** 任意额外选项，会被合并到最终 ColumnDef 中 */\n    extra?: Partial<ColumnDef<T, any>>;\n}\n\n/**\n * 将单个 ColumnConfig 转换为 ColumnDef\n */\nfunction buildColumnDef<T extends object>(config: ColumnConfig<T>): ColumnDef<T, any> {\n    const { key, header, type = 'text', sortable, cell, filter, width, minWidth, maxWidth, accessorFn, sortingFn, extra } = config;\n\n    // 选择列\n    if (type === 'selection') {\n        return createSelectionColumn<T>(extra);\n    }\n\n    // 操作列\n    if (type === 'action') {\n        return createActionColumn<T>({\n            id: key.startsWith('_') ? 'actions' : key,\n            header,\n            cell: cell as any,\n            ...(width !== undefined ? { size: width } : {}),\n            ...(minWidth !== undefined ? { minSize: minWidth } : {}),\n            ...(maxWidth !== undefined ? { maxSize: maxWidth } : {}),\n            ...extra,\n        });\n    }\n\n    // 构建 meta（筛选信息）\n    const meta: Record<string, any> = {};\n    if (filter) {\n        meta.filterType = filter.type;\n        if (filter.options) {\n            meta.filterOptions = filter.options;\n        }\n    }\n\n    // 自动选择排序函数\n    let resolvedSortingFn: SortingFn<any> | undefined = sortingFn;\n    if (!resolvedSortingFn) {\n        switch (type) {\n            case 'number':\n                resolvedSortingFn = numericSort;\n                break;\n            case 'date':\n                resolvedSortingFn = dateSort;\n                break;\n            // 'text' 和 'computed' 使用默认排序\n        }\n    }\n\n    // 基础选项（v9：使用 sortFn）\n    const baseOptions: Partial<ColumnDef<T, any>> = {\n        ...(cell !== undefined ? { cell: cell as any } : {}),\n        ...(resolvedSortingFn ? { sortFn: resolvedSortingFn } : {}),\n        ...(sortable === false ? { enableSorting: false } : {}),\n        ...(Object.keys(meta).length > 0 ? { meta } : {}),\n        ...(width !== undefined ? { size: width } : {}),\n        ...(minWidth !== undefined ? { minSize: minWidth } : {}),\n        ...(maxWidth !== undefined ? { maxSize: maxWidth } : {}),\n        ...extra,\n    };\n\n    // 计算列\n    if (type === 'computed') {\n        return createComputedColumn<T>(\n            key.startsWith('_') ? key.slice(1) : key,\n            header,\n            accessorFn,\n            baseOptions\n        );\n    }\n\n    // 普通列 / number / date\n    return createColumn<T>(key, header, baseOptions);\n}\n\n/**\n * useTableColumns - 通过 JSON 配置数组快速创建 DataTable 列定义\n *\n * @example\n * ```tsx\n * const columns = useTableColumns<Order>([\n *   { key: '_selection', type: 'selection', header: '' },\n *   { key: 'orderNumber', header: '订单编号', filter: { type: 'text' } },\n *   { key: 'total', header: '总金额', type: 'number',\n *     cell: info => `¥${info.getValue<number>().toFixed(2)}`,\n *     filter: { type: 'number' } },\n *   { key: '_actions', type: 'action', header: '操作',\n *     cell: ({ row }) => <button>查看</button> }\n * ]);\n * ```\n *\n * @param configs - 列配置数组；按引用跟踪更新。需要缓存时由调用方用 useMemo 稳定配置。\n * @param deps   - 额外依赖项，不能代替 configs；每次渲染保持依赖项数量不变。\n */\nexport function useTableColumns<T extends object>(\n    configs: ColumnConfig<T>[],\n    deps: readonly unknown[] = []\n): ColumnDef<T, any>[] {\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    return useMemo(() => configs.map(buildColumnDef), [configs, ...deps]);\n}\n\nexport default useTableColumns;\n"],"mappings":";;;AA8DA,SAAS,EAAiC,GAA4C;CAClF,IAAM,EAAE,QAAK,WAAQ,UAAO,QAAQ,aAAU,SAAM,WAAQ,UAAO,aAAU,aAAU,eAAY,cAAW,aAAU;CAGxH,IAAI,MAAS,aACT,OAAO,EAAyB,CAAK;CAIzC,IAAI,MAAS,UACT,OAAO,EAAsB;EACzB,IAAI,EAAI,WAAW,GAAG,IAAI,YAAY;EACtC;EACM;EACN,GAAI,MAAU,KAAA,IAA8B,CAAC,IAAnB,EAAE,MAAM,EAAM;EACxC,GAAI,MAAa,KAAA,IAAoC,CAAC,IAAzB,EAAE,SAAS,EAAS;EACjD,GAAI,MAAa,KAAA,IAAoC,CAAC,IAAzB,EAAE,SAAS,EAAS;EACjD,GAAG;CACP,CAAC;CAIL,IAAM,IAA4B,CAAC;CACnC,AAAI,MACA,EAAK,aAAa,EAAO,MACrB,EAAO,YACP,EAAK,gBAAgB,EAAO;CAKpC,IAAI,IAAgD;CACpD,IAAI,CAAC,GACD,QAAQ,GAAR;EACI,KAAK;GACD,IAAoB;GACpB;EACJ,KAAK,QACD,IAAoB;CAG5B;CAIJ,IAAM,IAA0C;EAC5C,GAAI,MAAS,KAAA,IAAoC,CAAC,IAAzB,EAAQ,QAAY;EAC7C,GAAI,IAAoB,EAAE,QAAQ,EAAkB,IAAI,CAAC;EACzD,GAAI,MAAa,KAAQ,EAAE,eAAe,GAAM,IAAI,CAAC;EACrD,GAAI,OAAO,KAAK,CAAI,CAAC,CAAC,SAAS,IAAI,EAAE,QAAK,IAAI,CAAC;EAC/C,GAAI,MAAU,KAAA,IAA8B,CAAC,IAAnB,EAAE,MAAM,EAAM;EACxC,GAAI,MAAa,KAAA,IAAoC,CAAC,IAAzB,EAAE,SAAS,EAAS;EACjD,GAAI,MAAa,KAAA,IAAoC,CAAC,IAAzB,EAAE,SAAS,EAAS;EACjD,GAAG;CACP;CAaA,OAVI,MAAS,aACF,EACH,EAAI,WAAW,GAAG,IAAI,EAAI,MAAM,CAAC,IAAI,GACrC,GACA,GACA,CACJ,IAIG,EAAgB,GAAK,GAAQ,CAAW;AACnD;AAqBA,SAAgB,EACZ,GACA,IAA2B,CAAC,GACT;CAEnB,OAAO,QAAc,EAAQ,IAAI,CAAc,GAAG,CAAC,GAAS,GAAG,CAAI,CAAC;AACxE"}

package/dist/hooks/useTableData.d.ts

@@ -3,7 +3,7 @@ import { ColumnFiltersState, SortingState, RowSelectionState } from '../componen
  * useTableData 配置项
  */
 export interface UseTableDataOptions<T extends object> {
-    /** 原始数据数组 */
+    /** 原始数据数组。未提供 getRowId 时使用此数组的索引作为 ID；重排、插删或刷新数据时应提供稳定业务 ID。 */
     data: T[];
     /** 初始排序状态 */
     initialSort?: SortingState;
@@ -11,9 +11,9 @@ export interface UseTableDataOptions<T extends object> {
     initialFilters?: ColumnFiltersState;
     /** 初始每页行数，默认 10 */
     initialPageSize?: number;
-    /** 自定义筛选函数（客户端过滤）。若不提供则将原始数据直接传给 DataTable 做内置过滤 */
+    /** 自定义筛选函数（有筛选条件时执行）。提供后 tableProps.manualFiltering=true，避免 DataTable 二次过滤。 */
     filterFn?: (item: T, filters: ColumnFiltersState) => boolean;
-    /** 获取行 ID 的函数 */
+    /** 获取唯一行 ID；index 是筛选前原始 data 的索引，而不是 tableData 的索引。 */
     getRowId?: (row: T, index: number) => string;
 }
 /**
@@ -22,18 +22,24 @@ export interface UseTableDataOptions<T extends object> {
 export interface UseTableDataReturn<T extends object> {
     /** 经过筛选后的数据（如果提供了 filterFn） */
     tableData: T[];
+    /** 是否由此 Hook 负责筛选；同时包含在 tableProps 中。 */
+    manualFiltering: boolean;
     sorting: SortingState;
     onSortingChange: (sorting: SortingState) => void;
     columnFilters: ColumnFiltersState;
     onColumnFiltersChange: (filters: ColumnFiltersState | ((prev: ColumnFiltersState) => ColumnFiltersState)) => void;
     pageIndex: number;
     pageSize: number;
+    /** Math.ceil(tableData.length / pageSize)。提供 filterFn 时是自定义筛选后的页数；
+     * 未提供时仅是原始数据页数，不包含 DataTable 的内置筛选（此 Hook 没有 columns，无法精确计算）。
+     * 内置筛选后的实际页数以 DataTable 的 table.getPageCount() 为准，不要将此值当作服务端总页数传入。
+     */
     pageCount: number;
     onPageChange: (page: number) => void;
     onPageSizeChange: (size: number) => void;
     selectedRows: RowSelectionState;
     onRowSelectionChange: (selection: RowSelectionState) => void;
-    /** 当前选中的数据行（便捷字段） */
+    /** tableData 中选中的行，按输入顺序返回；自定义筛选隐藏的选中 ID 保留在 selectedRows，但不在此数组中。 */
     selectedData: T[];
     /**
      * 合并好的 props，可直接展开到 <DataTable>
@@ -54,6 +60,7 @@ export interface UseTableDataReturn<T extends object> {
         getRowId?: (row: T, index: number) => string;
         enableSorting: boolean;
         enableFiltering: boolean;
+        manualFiltering: boolean;
         enablePagination: boolean;
         enableSelection: boolean;
     };

package/dist/hooks/useTableData.js

@@ -2,65 +2,83 @@ import { useCallback as e, useMemo as t, useState as n } from "react";
 //#region src/hooks/useTableData.ts
 function r(r) {
 	let { data: i, initialSort: a = [], initialFilters: o = [], initialPageSize: s = 10, filterFn: c, getRowId: l } = r, [u, d] = n(a), [f, p] = n(o), [m, h] = n(0), [g, _] = n(s), [v, y] = n({}), b = e((e) => {
-		h(0), p(e);
+		h(0), d(e);
 	}, []), x = e((e) => {
-		h(e);
+		h(0), p(e);
 	}, []), S = e((e) => {
+		h(e);
+	}, []), C = e((e) => {
 		_(e), h(0);
-	}, []), C = t(() => !c || f.length === 0 ? i : i.filter((e) => c(e, f)), [
+	}, []), { tableData: w, sourceIndexes: T } = t(() => {
+		if (!c || f.length === 0) return {
+			tableData: i,
+			sourceIndexes: i.map((e, t) => t)
+		};
+		let e = [], t = [];
+		return i.forEach((n, r) => {
+			c(n, f) && (e.push(n), t.push(r));
+		}), {
+			tableData: e,
+			sourceIndexes: t
+		};
+	}, [
 		i,
 		f,
 		c
-	]);
+	]), E = !!c, D = e((e, t) => {
+		let n = T[t] ?? t;
+		return l ? l(e, n) : String(n);
+	}, [T, l]);
 	return {
-		tableData: C,
+		tableData: w,
+		manualFiltering: E,
 		sorting: u,
-		onSortingChange: d,
+		onSortingChange: b,
 		columnFilters: f,
-		onColumnFiltersChange: b,
+		onColumnFiltersChange: x,
 		pageIndex: m,
 		pageSize: g,
-		pageCount: t(() => Math.ceil(C.length / g), [C.length, g]),
-		onPageChange: x,
-		onPageSizeChange: S,
+		pageCount: t(() => Math.ceil(w.length / g), [w.length, g]),
+		onPageChange: S,
+		onPageSizeChange: C,
 		selectedRows: v,
 		onRowSelectionChange: y,
-		selectedData: t(() => l ? C.filter((e, t) => {
-			let n = l(e, t);
-			return v[n];
-		}) : Object.keys(v).filter((e) => v[e]).map((e) => C[Number(e)]).filter(Boolean), [
+		selectedData: t(() => w.filter((e, t) => v[D(e, t)]), [
 			v,
-			C,
-			l
+			w,
+			D
 		]),
 		tableProps: t(() => ({
-			data: C,
+			data: w,
 			sortingState: u,
-			onSortingChange: d,
+			onSortingChange: b,
 			columnFilters: f,
-			onColumnFiltersChange: b,
+			onColumnFiltersChange: x,
 			pageIndex: m,
 			pageSize: g,
-			onPageChange: x,
-			onPageSizeChange: S,
+			onPageChange: S,
+			onPageSizeChange: C,
 			selectedRows: v,
 			onRowSelectionChange: y,
-			...l ? { getRowId: l } : {},
+			getRowId: D,
 			enableSorting: !0,
 			enableFiltering: !0,
+			manualFiltering: E,
 			enablePagination: !0,
 			enableSelection: !0
 		}), [
-			C,
+			w,
 			u,
-			f,
 			b,
+			f,
+			x,
 			m,
 			g,
-			x,
 			S,
+			C,
 			v,
-			l
+			D,
+			E
 		])
 	};
 }

package/dist/hooks/useTableData.js.map

@@ -1 +1 @@
-{"version":3,"file":"useTableData.js","names":[],"sources":["../../src/hooks/useTableData.ts"],"sourcesContent":["import { useState, useMemo, useCallback } from 'react';\nimport {\n    ColumnFiltersState,\n    SortingState,\n    RowSelectionState,\n} from '../components/pro/DataTable/tanstack-table';\n\n/**\n * useTableData 配置项\n */\nexport interface UseTableDataOptions<T extends object> {\n    /** 原始数据数组 */\n    data: T[];\n    /** 初始排序状态 */\n    initialSort?: SortingState;\n    /** 初始筛选状态 */\n    initialFilters?: ColumnFiltersState;\n    /** 初始每页行数，默认 10 */\n    initialPageSize?: number;\n    /** 自定义筛选函数（客户端过滤）。若不提供则将原始数据直接传给 DataTable 做内置过滤 */\n    filterFn?: (item: T, filters: ColumnFiltersState) => boolean;\n    /** 获取行 ID 的函数 */\n    getRowId?: (row: T, index: number) => string;\n}\n\n/**\n * useTableData 返回值\n */\nexport interface UseTableDataReturn<T extends object> {\n    // 数据\n    /** 经过筛选后的数据（如果提供了 filterFn） */\n    tableData: T[];\n\n    // 排序\n    sorting: SortingState;\n    onSortingChange: (sorting: SortingState) => void;\n\n    // 筛选\n    columnFilters: ColumnFiltersState;\n    onColumnFiltersChange: (\n        filters: ColumnFiltersState | ((prev: ColumnFiltersState) => ColumnFiltersState)\n    ) => void;\n\n    // 分页\n    pageIndex: number;\n    pageSize: number;\n    pageCount: number;\n    onPageChange: (page: number) => void;\n    onPageSizeChange: (size: number) => void;\n\n    // 选择\n    selectedRows: RowSelectionState;\n    onRowSelectionChange: (selection: RowSelectionState) => void;\n    /** 当前选中的数据行（便捷字段） */\n    selectedData: T[];\n\n    /**\n     * 合并好的 props，可直接展开到 <DataTable>\n     * @example <DataTable columns={columns} {...tableProps} />\n     */\n    tableProps: {\n        data: T[];\n        sortingState: SortingState;\n        onSortingChange: (sorting: SortingState) => void;\n        columnFilters: ColumnFiltersState;\n        onColumnFiltersChange: (\n            filters: ColumnFiltersState | ((prev: ColumnFiltersState) => ColumnFiltersState)\n        ) => void;\n        pageIndex: number;\n        pageSize: number;\n        onPageChange: (page: number) => void;\n        onPageSizeChange: (size: number) => void;\n        selectedRows: RowSelectionState;\n        onRowSelectionChange: (selection: RowSelectionState) => void;\n        getRowId?: (row: T, index: number) => string;\n        enableSorting: boolean;\n        enableFiltering: boolean;\n        enablePagination: boolean;\n        enableSelection: boolean;\n    };\n}\n\n/**\n * useTableData - 封装 DataTable 的数据状态管理\n *\n * 将排序、筛选、分页、选择等状态统一管理，\n * 返回的 `tableProps` 可以直接展开到 `<DataTable>` 上。\n *\n * @example\n * ```tsx\n * const { tableProps, selectedData } = useTableData({\n *   data: orders,\n *   initialSort: [{ id: 'orderDate', desc: true }],\n *   initialPageSize: 5,\n * });\n *\n * <DataTable columns={columns} {...tableProps} />\n * ```\n */\nexport function useTableData<T extends object>(\n    options: UseTableDataOptions<T>\n): UseTableDataReturn<T> {\n    const {\n        data,\n        initialSort = [],\n        initialFilters = [],\n        initialPageSize = 10,\n        filterFn,\n        getRowId,\n    } = options;\n\n    // ─── 排序 ───\n    const [sorting, setSorting] = useState<SortingState>(initialSort);\n\n    // ─── 筛选 ───\n    const [columnFilters, setColumnFiltersRaw] = useState<ColumnFiltersState>(initialFilters);\n\n    // ─── 分页 ───\n    const [pageIndex, setPageIndex] = useState(0);\n    const [pageSize, setPageSize] = useState(initialPageSize);\n\n    // ─── 选择 ───\n    const [selectedRows, setSelectedRows] = useState<RowSelectionState>({});\n\n    // ─── 当筛选变化时重置到第一页 ───\n    const onColumnFiltersChange = useCallback(\n        (updater: ColumnFiltersState | ((prev: ColumnFiltersState) => ColumnFiltersState)) => {\n            setPageIndex(0);\n            setColumnFiltersRaw(updater);\n        },\n        []\n    );\n\n    // ─── 分页回调 ───\n    const onPageChange = useCallback((page: number) => {\n        setPageIndex(page);\n    }, []);\n\n    const onPageSizeChange = useCallback((size: number) => {\n        setPageSize(size);\n        setPageIndex(0);\n    }, []);\n\n    // ─── 客户端过滤（仅当提供了 filterFn 时） ───\n    const tableData = useMemo(() => {\n        if (!filterFn || columnFilters.length === 0) {\n            return data;\n        }\n        return data.filter((item) => filterFn(item, columnFilters));\n    }, [data, columnFilters, filterFn]);\n\n    // ─── 页数 ───\n    const pageCount = useMemo(\n        () => Math.ceil(tableData.length / pageSize),\n        [tableData.length, pageSize]\n    );\n\n    // ─── 选中数据便捷字段 ───\n    const selectedData = useMemo(() => {\n        if (!getRowId) {\n            // 用索引作为 key\n            return Object.keys(selectedRows)\n                .filter((k) => selectedRows[k])\n                .map((k) => tableData[Number(k)])\n                .filter(Boolean);\n        }\n        return tableData.filter((item, idx) => {\n            const id = getRowId(item, idx);\n            return selectedRows[id];\n        });\n    }, [selectedRows, tableData, getRowId]);\n\n    // ─── 合并 props ───\n    const tableProps = useMemo(\n        () => ({\n            data: tableData,\n            sortingState: sorting,\n            onSortingChange: setSorting,\n            columnFilters,\n            onColumnFiltersChange,\n            pageIndex,\n            pageSize,\n            onPageChange,\n            onPageSizeChange,\n            selectedRows,\n            onRowSelectionChange: setSelectedRows,\n            ...(getRowId ? { getRowId } : {}),\n            enableSorting: true,\n            enableFiltering: true,\n            enablePagination: true,\n            enableSelection: true,\n        }),\n        [\n            tableData,\n            sorting,\n            columnFilters,\n            onColumnFiltersChange,\n            pageIndex,\n            pageSize,\n            onPageChange,\n            onPageSizeChange,\n            selectedRows,\n            getRowId,\n        ]\n    );\n\n    return {\n        tableData,\n        sorting,\n        onSortingChange: setSorting,\n        columnFilters,\n        onColumnFiltersChange,\n        pageIndex,\n        pageSize,\n        pageCount,\n        onPageChange,\n        onPageSizeChange,\n        selectedRows,\n        onRowSelectionChange: setSelectedRows,\n        selectedData,\n        tableProps,\n    };\n}\n\nexport default useTableData;\n"],"mappings":";;AAmGA,SAAgB,EACZ,GACqB;CACrB,IAAM,EACF,SACA,iBAAc,CAAC,GACf,oBAAiB,CAAC,GAClB,qBAAkB,IAClB,aACA,gBACA,GAGE,CAAC,GAAS,KAAc,EAAuB,CAAW,GAG1D,CAAC,GAAe,KAAuB,EAA6B,CAAc,GAGlF,CAAC,GAAW,KAAgB,EAAS,CAAC,GACtC,CAAC,GAAU,KAAe,EAAS,CAAe,GAGlD,CAAC,GAAc,KAAmB,EAA4B,CAAC,CAAC,GAGhE,IAAwB,GACzB,MAAqF;EAElF,AADA,EAAa,CAAC,GACd,EAAoB,CAAO;CAC/B,GACA,CAAC,CACL,GAGM,IAAe,GAAa,MAAiB;EAC/C,EAAa,CAAI;CACrB,GAAG,CAAC,CAAC,GAEC,IAAmB,GAAa,MAAiB;EAEnD,AADA,EAAY,CAAI,GAChB,EAAa,CAAC;CAClB,GAAG,CAAC,CAAC,GAGC,IAAY,QACV,CAAC,KAAY,EAAc,WAAW,IAC/B,IAEJ,EAAK,QAAQ,MAAS,EAAS,GAAM,CAAa,CAAC,GAC3D;EAAC;EAAM;EAAe;CAAQ,CAAC;CAyDlC,OAAO;EACH;EACA;EACA,iBAAiB;EACjB;EACA;EACA;EACA;EACA,WA9Dc,QACR,KAAK,KAAK,EAAU,SAAS,CAAQ,GAC3C,CAAC,EAAU,QAAQ,CAAQ,CA4D3B;EACA;EACA;EACA;EACA,sBAAsB;EACtB,cA7DiB,QACZ,IAOE,EAAU,QAAQ,GAAM,MAAQ;GACnC,IAAM,IAAK,EAAS,GAAM,CAAG;GAC7B,OAAO,EAAa;EACxB,CAAC,IARU,OAAO,KAAK,CAAY,CAAC,CAC3B,QAAQ,MAAM,EAAa,EAAE,CAAC,CAC9B,KAAK,MAAM,EAAU,OAAO,CAAC,EAAE,CAAC,CAChC,OAAO,OAAO,GAMxB;GAAC;GAAc;GAAW;EAAQ,CAiDjC;EACA,YA/Ce,SACR;GACH,MAAM;GACN,cAAc;GACd,iBAAiB;GACjB;GACA;GACA;GACA;GACA;GACA;GACA;GACA,sBAAsB;GACtB,GAAI,IAAW,EAAE,YAAS,IAAI,CAAC;GAC/B,eAAe;GACf,iBAAiB;GACjB,kBAAkB;GAClB,iBAAiB;EACrB,IACA;GACI;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;EACJ,CAiBA;CACJ;AACJ"}
+{"version":3,"file":"useTableData.js","names":[],"sources":["../../src/hooks/useTableData.ts"],"sourcesContent":["import { useState, useMemo, useCallback } from 'react';\nimport {\n    ColumnFiltersState,\n    SortingState,\n    RowSelectionState,\n} from '../components/pro/DataTable/tanstack-table';\n\n/**\n * useTableData 配置项\n */\nexport interface UseTableDataOptions<T extends object> {\n    /** 原始数据数组。未提供 getRowId 时使用此数组的索引作为 ID；重排、插删或刷新数据时应提供稳定业务 ID。 */\n    data: T[];\n    /** 初始排序状态 */\n    initialSort?: SortingState;\n    /** 初始筛选状态 */\n    initialFilters?: ColumnFiltersState;\n    /** 初始每页行数，默认 10 */\n    initialPageSize?: number;\n    /** 自定义筛选函数（有筛选条件时执行）。提供后 tableProps.manualFiltering=true，避免 DataTable 二次过滤。 */\n    filterFn?: (item: T, filters: ColumnFiltersState) => boolean;\n    /** 获取唯一行 ID；index 是筛选前原始 data 的索引，而不是 tableData 的索引。 */\n    getRowId?: (row: T, index: number) => string;\n}\n\n/**\n * useTableData 返回值\n */\nexport interface UseTableDataReturn<T extends object> {\n    // 数据\n    /** 经过筛选后的数据（如果提供了 filterFn） */\n    tableData: T[];\n    /** 是否由此 Hook 负责筛选；同时包含在 tableProps 中。 */\n    manualFiltering: boolean;\n\n    // 排序\n    sorting: SortingState;\n    onSortingChange: (sorting: SortingState) => void;\n\n    // 筛选\n    columnFilters: ColumnFiltersState;\n    onColumnFiltersChange: (\n        filters: ColumnFiltersState | ((prev: ColumnFiltersState) => ColumnFiltersState)\n    ) => void;\n\n    // 分页\n    pageIndex: number;\n    pageSize: number;\n    /** Math.ceil(tableData.length / pageSize)。提供 filterFn 时是自定义筛选后的页数；\n     * 未提供时仅是原始数据页数，不包含 DataTable 的内置筛选（此 Hook 没有 columns，无法精确计算）。\n     * 内置筛选后的实际页数以 DataTable 的 table.getPageCount() 为准，不要将此值当作服务端总页数传入。\n     */\n    pageCount: number;\n    onPageChange: (page: number) => void;\n    onPageSizeChange: (size: number) => void;\n\n    // 选择\n    selectedRows: RowSelectionState;\n    onRowSelectionChange: (selection: RowSelectionState) => void;\n    /** tableData 中选中的行，按输入顺序返回；自定义筛选隐藏的选中 ID 保留在 selectedRows，但不在此数组中。 */\n    selectedData: T[];\n\n    /**\n     * 合并好的 props，可直接展开到 <DataTable>\n     * @example <DataTable columns={columns} {...tableProps} />\n     */\n    tableProps: {\n        data: T[];\n        sortingState: SortingState;\n        onSortingChange: (sorting: SortingState) => void;\n        columnFilters: ColumnFiltersState;\n        onColumnFiltersChange: (\n            filters: ColumnFiltersState | ((prev: ColumnFiltersState) => ColumnFiltersState)\n        ) => void;\n        pageIndex: number;\n        pageSize: number;\n        onPageChange: (page: number) => void;\n        onPageSizeChange: (size: number) => void;\n        selectedRows: RowSelectionState;\n        onRowSelectionChange: (selection: RowSelectionState) => void;\n        getRowId?: (row: T, index: number) => string;\n        enableSorting: boolean;\n        enableFiltering: boolean;\n        manualFiltering: boolean;\n        enablePagination: boolean;\n        enableSelection: boolean;\n    };\n}\n\n/**\n * useTableData - 封装 DataTable 的数据状态管理\n *\n * 将排序、筛选、分页、选择等状态统一管理，\n * 返回的 `tableProps` 可以直接展开到 `<DataTable>` 上。\n *\n * @example\n * ```tsx\n * const { tableProps, selectedData } = useTableData({\n *   data: orders,\n *   initialSort: [{ id: 'orderDate', desc: true }],\n *   initialPageSize: 5,\n * });\n *\n * <DataTable columns={columns} {...tableProps} />\n * ```\n */\nexport function useTableData<T extends object>(\n    options: UseTableDataOptions<T>\n): UseTableDataReturn<T> {\n    const {\n        data,\n        initialSort = [],\n        initialFilters = [],\n        initialPageSize = 10,\n        filterFn,\n        getRowId,\n    } = options;\n\n    // ─── 排序 ───\n    const [sorting, setSorting] = useState<SortingState>(initialSort);\n\n    // ─── 筛选 ───\n    const [columnFilters, setColumnFiltersRaw] = useState<ColumnFiltersState>(initialFilters);\n\n    // ─── 分页 ───\n    const [pageIndex, setPageIndex] = useState(0);\n    const [pageSize, setPageSize] = useState(initialPageSize);\n\n    // ─── 选择 ───\n    const [selectedRows, setSelectedRows] = useState<RowSelectionState>({});\n\n    const onSortingChange = useCallback((next: SortingState) => {\n        setPageIndex(0);\n        setSorting(next);\n    }, []);\n\n    // ─── 当筛选变化时重置到第一页 ───\n    const onColumnFiltersChange = useCallback(\n        (updater: ColumnFiltersState | ((prev: ColumnFiltersState) => ColumnFiltersState)) => {\n            setPageIndex(0);\n            setColumnFiltersRaw(updater);\n        },\n        []\n    );\n\n    // ─── 分页回调 ───\n    const onPageChange = useCallback((page: number) => {\n        setPageIndex(page);\n    }, []);\n\n    const onPageSizeChange = useCallback((size: number) => {\n        setPageSize(size);\n        setPageIndex(0);\n    }, []);\n\n    // Keep source indexes alongside rows, rather than mapping object identities:\n    // the same object can appear at multiple positions in the input array.\n    const { tableData, sourceIndexes } = useMemo(() => {\n        if (!filterFn || columnFilters.length === 0) {\n            return { tableData: data, sourceIndexes: data.map((_, index) => index) };\n        }\n        const tableData: T[] = [];\n        const sourceIndexes: number[] = [];\n        data.forEach((item, index) => {\n            if (filterFn(item, columnFilters)) {\n                tableData.push(item);\n                sourceIndexes.push(index);\n            }\n        });\n        return { tableData, sourceIndexes };\n    }, [data, columnFilters, filterFn]);\n    const manualFiltering = Boolean(filterFn);\n    const resolveRowId = useCallback((row: T, index: number) => {\n        const sourceIndex = sourceIndexes[index] ?? index;\n        return getRowId ? getRowId(row, sourceIndex) : String(sourceIndex);\n    }, [sourceIndexes, getRowId]);\n\n    // ─── 页数 ───\n    const pageCount = useMemo(\n        () => Math.ceil(tableData.length / pageSize),\n        [tableData.length, pageSize]\n    );\n\n    // ─── 选中数据便捷字段 ───\n    const selectedData = useMemo(() =>\n        tableData.filter((item, index) => selectedRows[resolveRowId(item, index)]),\n        [selectedRows, tableData, resolveRowId]\n    );\n\n    // ─── 合并 props ───\n    const tableProps = useMemo(\n        () => ({\n            data: tableData,\n            sortingState: sorting,\n            onSortingChange,\n            columnFilters,\n            onColumnFiltersChange,\n            pageIndex,\n            pageSize,\n            onPageChange,\n            onPageSizeChange,\n            selectedRows,\n            onRowSelectionChange: setSelectedRows,\n            getRowId: resolveRowId,\n            enableSorting: true,\n            enableFiltering: true,\n            manualFiltering,\n            enablePagination: true,\n            enableSelection: true,\n        }),\n        [\n            tableData,\n            sorting,\n            onSortingChange,\n            columnFilters,\n            onColumnFiltersChange,\n            pageIndex,\n            pageSize,\n            onPageChange,\n            onPageSizeChange,\n            selectedRows,\n            resolveRowId,\n            manualFiltering,\n        ]\n    );\n\n    return {\n        tableData,\n        manualFiltering,\n        sorting,\n        onSortingChange,\n        columnFilters,\n        onColumnFiltersChange,\n        pageIndex,\n        pageSize,\n        pageCount,\n        onPageChange,\n        onPageSizeChange,\n        selectedRows,\n        onRowSelectionChange: setSelectedRows,\n        selectedData,\n        tableProps,\n    };\n}\n\nexport default useTableData;\n"],"mappings":";;AA0GA,SAAgB,EACZ,GACqB;CACrB,IAAM,EACF,SACA,iBAAc,CAAC,GACf,oBAAiB,CAAC,GAClB,qBAAkB,IAClB,aACA,gBACA,GAGE,CAAC,GAAS,KAAc,EAAuB,CAAW,GAG1D,CAAC,GAAe,KAAuB,EAA6B,CAAc,GAGlF,CAAC,GAAW,KAAgB,EAAS,CAAC,GACtC,CAAC,GAAU,KAAe,EAAS,CAAe,GAGlD,CAAC,GAAc,KAAmB,EAA4B,CAAC,CAAC,GAEhE,IAAkB,GAAa,MAAuB;EAExD,AADA,EAAa,CAAC,GACd,EAAW,CAAI;CACnB,GAAG,CAAC,CAAC,GAGC,IAAwB,GACzB,MAAqF;EAElF,AADA,EAAa,CAAC,GACd,EAAoB,CAAO;CAC/B,GACA,CAAC,CACL,GAGM,IAAe,GAAa,MAAiB;EAC/C,EAAa,CAAI;CACrB,GAAG,CAAC,CAAC,GAEC,IAAmB,GAAa,MAAiB;EAEnD,AADA,EAAY,CAAI,GAChB,EAAa,CAAC;CAClB,GAAG,CAAC,CAAC,GAIC,EAAE,cAAW,qBAAkB,QAAc;EAC/C,IAAI,CAAC,KAAY,EAAc,WAAW,GACtC,OAAO;GAAE,WAAW;GAAM,eAAe,EAAK,KAAK,GAAG,MAAU,CAAK;EAAE;EAE3E,IAAM,IAAiB,CAAC,GAClB,IAA0B,CAAC;EAOjC,OANA,EAAK,SAAS,GAAM,MAAU;GAC1B,AAAI,EAAS,GAAM,CAAa,MAC5B,EAAU,KAAK,CAAI,GACnB,EAAc,KAAK,CAAK;EAEhC,CAAC,GACM;GAAE;GAAW;EAAc;CACtC,GAAG;EAAC;EAAM;EAAe;CAAQ,CAAC,GAC5B,IAAkB,EAAQ,GAC1B,IAAe,GAAa,GAAQ,MAAkB;EACxD,IAAM,IAAc,EAAc,MAAU;EAC5C,OAAO,IAAW,EAAS,GAAK,CAAW,IAAI,OAAO,CAAW;CACrE,GAAG,CAAC,GAAe,CAAQ,CAAC;CAmD5B,OAAO;EACH;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,WAzDc,QACR,KAAK,KAAK,EAAU,SAAS,CAAQ,GAC3C,CAAC,EAAU,QAAQ,CAAQ,CAuD3B;EACA;EACA;EACA;EACA,sBAAsB;EACtB,cAxDiB,QACjB,EAAU,QAAQ,GAAM,MAAU,EAAa,EAAa,GAAM,CAAK,EAAE,GACzE;GAAC;GAAc;GAAW;EAAY,CAsDtC;EACA,YAnDe,SACR;GACH,MAAM;GACN,cAAc;GACd;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA,sBAAsB;GACtB,UAAU;GACV,eAAe;GACf,iBAAiB;GACjB;GACA,kBAAkB;GAClB,iBAAiB;EACrB,IACA;GACI;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;EACJ,CAkBA;CACJ;AACJ"}

package/dist/index-nostyled.d.ts

@@ -1,7 +1,7 @@
 export { Resizable, ResizablePanel, ResizableHandle, useResize } from './components/Resizable';
 export type { ResizableProps, ResizablePanelProps, ResizableHandleProps, UseResizeOptions } from './components/Resizable';
-export { default as LayoutSuite, AdminSuite, WikiSuite, BlogSuite, BlankSuite, DashboardSuite } from './components/LayoutSuite';
-export type { AdminSuiteProps, WikiSuiteProps, BlogSuiteProps, BlankSuiteProps, DashboardSuiteProps, LayoutSuiteSidebarProps } from './components/LayoutSuite';
+export { default as LayoutSuite, AdminSuite, MailSuite, WikiSuite, BlogSuite, BlankSuite, DashboardSuite } from './components/LayoutSuite';
+export type { AdminSuiteProps, MailSuiteProps, WikiSuiteProps, BlogSuiteProps, BlankSuiteProps, DashboardSuiteProps, LayoutSuiteSidebarProps } from './components/LayoutSuite';
 export { default as ButtonMenu } from './components/ButtonMenu';
 export type { ButtonMenuProps, ButtonMenuItem } from './components/ButtonMenu';
 export { default as Button } from './components/Button';

package/dist/index.d.ts

@@ -40,8 +40,8 @@ export { default as PageHeader } from './components/PageHeader';
 export type { PageHeaderProps } from './components/PageHeader';
 export { default as Page, PageBody, PageLeft, PageRight, PageMain, PageFooter, PageFloat } from './components/Page';
 export type { PageProps, PageBodyProps, PageAsideProps, PageMainProps, PageFooterProps, PageFloatProps, PagePanelProps } from './components/Page';
-export { default as LayoutSuite, AdminSuite, WikiSuite, BlogSuite, BlankSuite, DashboardSuite } from './components/LayoutSuite';
-export type { AdminSuiteProps, WikiSuiteProps, BlogSuiteProps, BlankSuiteProps, DashboardSuiteProps, LayoutSuiteSidebarProps } from './components/LayoutSuite';
+export { default as LayoutSuite, AdminSuite, MailSuite, WikiSuite, BlogSuite, BlankSuite, DashboardSuite } from './components/LayoutSuite';
+export type { AdminSuiteProps, MailSuiteProps, WikiSuiteProps, BlogSuiteProps, BlankSuiteProps, DashboardSuiteProps, LayoutSuiteSidebarProps } from './components/LayoutSuite';
 export { default as EmptyState } from './components/EmptyState';
 export { default as Avatar } from './components/Avatar';
 export type { AvatarProps, AvatarShape, AvatarBorderStyle, AvatarNotificationPosition, } from './components/Avatar';