@ackplus/react-tanstack-data-table 1.1.19 → 1.1.21

package/src/lib/hooks/use-data-table-engine.ts

@@ -1,1516 +0,0 @@
-import {
-    getCoreRowModel,
-    getPaginationRowModel,
-    getSortedRowModel,
-    PaginationState,
-    useReactTable,
-    type ColumnOrderState,
-    type ColumnPinningState,
-    type SortingState,
-    type Updater,
-} from "@tanstack/react-table";
-import { useVirtualizer } from "@tanstack/react-virtual";
-import { useTheme } from "@mui/material/styles";
-import { useMemo, useReducer, useState, useRef, useCallback, useEffect, RefObject, CSSProperties } from "react";
-
-// your types
-import type {
-    ColumnFilterState,
-    DataFetchMeta,
-    DataRefreshOptions,
-    DataTableProps,
-    ExportPhase,
-    ExportProgressPayload,
-    ExportStateChange,
-    TableFiltersForFetch,
-    TableState,
-} from "../types";
-import type { DataTableApi, DataTableExportApiOptions } from "../types/data-table-api";
-
-// your features / utils
-import { ColumnFilterFeature, getCombinedFilteredRowModel } from "../features/column-filter.feature";
-import { SelectionFeature, SelectionState } from "../features";
-import { createExpandingColumn, createSelectionColumn } from "../utils/special-columns.utils";
-import {
-    exportClientData,
-    exportServerData,
-    generateRowId,
-    withIdsDeep,
-    type DataTableSize,
-} from "../utils";
-import { useDebouncedFetch } from "../utils/debounced-fetch.utils";
-
-const DEFAULT_INITIAL_STATE = {
-    sorting: [] as SortingState,
-    pagination: { pageIndex: 0, pageSize: 10 },
-    selectionState: { ids: [], type: "include" } as SelectionState,
-    globalFilter: "",
-    expanded: {} as Record<string, boolean>,
-    columnOrder: [] as ColumnOrderState,
-    columnPinning: { left: [], right: [] } as ColumnPinningState,
-    columnVisibility: {} as Record<string, boolean>,
-    columnSizing: {} as Record<string, number>,
-    columnFilter: {
-        filters: [],
-        logic: "AND",
-        pendingFilters: [],
-        pendingLogic: "AND",
-    } as ColumnFilterState,
-};
-
-type EngineUIState = {
-    sorting: SortingState;
-    pagination: { pageIndex: number; pageSize: number };
-    globalFilter: string;
-    selectionState: SelectionState;
-    columnFilter: ColumnFilterState;
-    expanded: Record<string, boolean>;
-    tableSize: DataTableSize;
-    columnOrder: ColumnOrderState;
-    columnPinning: ColumnPinningState;
-    columnVisibility: Record<string, boolean>;
-    columnSizing: Record<string, number>;
-};
-type EngineAction =
-    | { type: "SET_SORTING_RESET_PAGE"; payload: SortingState }
-    | { type: "SET_PAGINATION"; payload: { pageIndex: number; pageSize: number } }
-    | { type: "SET_GLOBAL_FILTER_RESET_PAGE"; payload: string }
-    | { type: "SET_SELECTION"; payload: SelectionState }
-    | { type: "SET_COLUMN_FILTER"; payload: ColumnFilterState }
-    | { type: "SET_COLUMN_FILTER_RESET_PAGE"; payload: ColumnFilterState }
-    | { type: "SET_EXPANDED"; payload: Record<string, boolean> }
-    | { type: "SET_TABLE_SIZE"; payload: DataTableSize }
-    | { type: "SET_COLUMN_ORDER"; payload: ColumnOrderState }
-    | { type: "SET_COLUMN_PINNING"; payload: ColumnPinningState }
-    | { type: "SET_COLUMN_VISIBILITY"; payload: Record<string, boolean> }
-    | { type: "SET_COLUMN_SIZING"; payload: Record<string, number> }
-    | { type: "RESET_ALL"; payload: Partial<EngineUIState> } // payload = computed reset state
-    | { type: "RESTORE_LAYOUT"; payload: Partial<EngineUIState> };
-
-
-function uiReducer(state: EngineUIState, action: EngineAction): EngineUIState {
-    switch (action.type) {
-        case "SET_SORTING_RESET_PAGE":
-            return { ...state, sorting: action.payload, pagination: { pageIndex: 0, pageSize: state.pagination.pageSize } };
-        case "SET_PAGINATION":
-            return { ...state, pagination: action.payload };
-        case "SET_GLOBAL_FILTER_RESET_PAGE":
-            return { ...state, globalFilter: action.payload, pagination: { pageIndex: 0, pageSize: state.pagination.pageSize } };
-        case "SET_SELECTION":
-            return { ...state, selectionState: action.payload };
-        case "SET_COLUMN_FILTER":
-            return { ...state, columnFilter: action.payload };
-        case "SET_COLUMN_FILTER_RESET_PAGE":
-            return { ...state, columnFilter: action.payload, pagination: { pageIndex: 0, pageSize: state.pagination.pageSize } };
-        case "SET_EXPANDED":
-            return { ...state, expanded: action.payload };
-        case "SET_TABLE_SIZE":
-            return { ...state, tableSize: action.payload };
-        case "SET_COLUMN_ORDER":
-            return { ...state, columnOrder: action.payload };
-        case "SET_COLUMN_PINNING":
-            return { ...state, columnPinning: action.payload };
-        case "SET_COLUMN_VISIBILITY":
-            return { ...state, columnVisibility: action.payload };
-        case "SET_COLUMN_SIZING":
-            return { ...state, columnSizing: action.payload };
-        case "RESTORE_LAYOUT":
-            return { ...state, ...action.payload };
-        case "RESET_ALL":
-            return { ...state, ...action.payload };
-        default:
-            return state;
-    }
-}
-
-function useLatestRef<T>(value: T) {
-    const ref = useRef(value);
-    useEffect(() => {
-        ref.current = value;
-    }, [value]);
-    return ref;
-}
-
-function useEvent<T extends (...args: any[]) => any>(fn: T): T {
-    const fnRef = useLatestRef(fn);
-    return useCallback(((...args: any[]) => fnRef.current(...args)) as T, [fnRef]) as T;
-}
-
-
-export interface EngineResult<T = any> {
-    table: ReturnType<typeof useReactTable<T>>;
-    refs: {
-        tableContainerRef: RefObject<HTMLDivElement>;
-        apiRef: RefObject<DataTableApi<T> | null>;
-        exportControllerRef: RefObject<AbortController | null>;
-    };
-    derived: {
-        isServerMode: boolean;
-        isServerPagination: boolean;
-        isServerFiltering: boolean;
-        isServerSorting: boolean;
-        tableData: T[];
-        tableTotalRow: number;
-        tableLoading: boolean;
-        rows: ReturnType<ReturnType<typeof useReactTable<T>>["getRowModel"]>["rows"];
-        visibleLeafColumns: ReturnType<typeof useReactTable<T>>["getVisibleLeafColumns"];
-        useFixedLayout: boolean;
-        tableStyle: CSSProperties;
-        isExporting: boolean;
-        exportPhase: ExportPhase | null;
-        exportProgress: ExportProgressPayload;
-        isSomeRowsSelected: boolean;
-        selectedRowCount: number;
-    };
-    state: EngineUIState;
-    actions: {
-        fetchData: (overrides?: Partial<TableState>, options?: { delay?: number; meta?: DataFetchMeta }) => Promise<any>;
-        handleSortingChange: (updaterOrValue: any) => void;
-        handlePaginationChange: (updater: any) => void;
-        handleGlobalFilterChange: (updaterOrValue: any) => void;
-        handleColumnFilterChangeHandler: (updater: any, isApply?: boolean) => void;
-        handleColumnOrderChange: (updatedColumnOrder: Updater<ColumnOrderState>) => void;
-        handleColumnPinningChange: (updater: Updater<ColumnPinningState>) => void;
-        handleColumnVisibilityChange: (updater: any) => void;
-        handleColumnSizingChange: (updater: any) => void;
-        handleColumnReorder: (draggedColumnId: string, targetColumnId: string) => void;
-        resetAllAndReload: () => void;
-        triggerRefresh: (options?: boolean | DataRefreshOptions, fallbackReason?: string) => Promise<void>;
-        setTableSize: (size: DataTableSize) => void;
-        handleCancelExport: () => void;
-        renderRowModel: { rowVirtualizer: ReturnType<typeof useVirtualizer> };
-    };
-    api: DataTableApi<T>;
-    providerProps: {
-        table: ReturnType<typeof useReactTable<T>>;
-        apiRef: RefObject<DataTableApi<T> | null>;
-        dataMode: "client" | "server";
-        tableSize: DataTableSize;
-        onTableSizeChange: (size: DataTableSize) => void;
-        columnFilter: ColumnFilterState;
-        onChangeColumnFilter: (filter: ColumnFilterState) => void;
-        slots: Record<string, any>;
-        slotProps: Record<string, any>;
-        isExporting: boolean;
-        exportController: AbortController | null;
-        exportPhase: ExportPhase | null;
-        exportProgress: ExportProgressPayload;
-        onCancelExport: () => void;
-        exportFilename: string;
-        onExportProgress?: (progress: ExportProgressPayload) => void;
-        onExportComplete?: (result: { success: boolean; filename: string; totalRows: number }) => void;
-        onExportError?: (error: { message: string; code: string }) => void;
-        onServerExport?: (filters?: Partial<any>, selection?: SelectionState, signal?: AbortSignal) => Promise<any>;
-    };
-}
-
-export function useDataTableEngine<T extends Record<string, any>>(
-    props: DataTableProps<T>
-): EngineResult<T> {
-    const {
-        initialState,
-        columns,
-        data = [],
-        totalRow = 0,
-        idKey = "id" as keyof T,
-
-        dataMode = "client",
-        initialLoadData = true,
-        onFetchData,
-        onFetchStateChange,
-        onDataStateChange,
-
-        enableRowSelection = false,
-        enableMultiRowSelection = true,
-        selectMode = "page",
-        isRowSelectable,
-        onSelectionChange,
-        enableBulkActions = false,
-
-        enableColumnResizing = false,
-        columnResizeMode = "onChange",
-        onColumnSizingChange,
-
-        enableColumnDragging = false,
-        onColumnDragEnd,
-
-        enableColumnPinning = false,
-        onColumnPinningChange,
-
-        onColumnVisibilityChange,
-        enableColumnVisibility = true,
-
-        enableExpanding = false,
-        getRowCanExpand,
-
-        enablePagination = false,
-        paginationMode = "client",
-
-        enableGlobalFilter = true,
-
-        enableColumnFilter = false,
-        filterMode = "client",
-
-        enableSorting = true,
-        sortingMode = "client",
-        onSortingChange,
-
-        exportFilename = "export",
-        exportConcurrency = "cancelAndRestart",
-        exportChunkSize = 1000,
-        exportStrictTotalCheck = false,
-        exportSanitizeCSV = true,
-        onExportProgress,
-        onExportComplete,
-        onExportError,
-        onServerExport,
-        onExportCancel,
-        onExportStateChange,
-
-        fitToScreen = true,
-        tableSize: initialTableSize = "medium",
-        enableVirtualization = false,
-        estimateRowHeight = 52,
-
-        loading = false,
-
-        onColumnFiltersChange,
-        onPaginationChange,
-        onGlobalFilterChange,
-
-        slots = {},
-        slotProps = {},
-    } = props;
-
-    const theme = useTheme();
-
-    const isServerMode = dataMode === "server";
-    const isServerPagination = paginationMode === "server" || isServerMode;
-    const isServerFiltering = filterMode === "server" || isServerMode;
-    const isServerSorting = sortingMode === "server" || isServerMode;
-
-    // --- initial config (memo)
-    const initialStateConfig = useMemo(() => {
-        const config = { ...DEFAULT_INITIAL_STATE, ...initialState };
-        return config;
-    }, [initialState]);
-
-    const initialUIState: EngineUIState = useMemo(
-        () => ({
-            sorting: initialStateConfig.sorting ?? DEFAULT_INITIAL_STATE.sorting,
-            pagination: initialStateConfig.pagination ?? DEFAULT_INITIAL_STATE.pagination,
-            globalFilter: initialStateConfig.globalFilter ?? DEFAULT_INITIAL_STATE.globalFilter,
-            selectionState: initialStateConfig.selectionState ?? DEFAULT_INITIAL_STATE.selectionState,
-            columnFilter: initialStateConfig.columnFilter ?? DEFAULT_INITIAL_STATE.columnFilter,
-            expanded: initialStateConfig.expanded ?? {},
-            tableSize: (initialTableSize || "medium") as DataTableSize,
-            columnOrder: initialStateConfig.columnOrder ?? DEFAULT_INITIAL_STATE.columnOrder,
-            columnPinning: initialStateConfig.columnPinning ?? DEFAULT_INITIAL_STATE.columnPinning,
-            columnVisibility: initialStateConfig.columnVisibility ?? DEFAULT_INITIAL_STATE.columnVisibility,
-            columnSizing: initialStateConfig.columnSizing ?? DEFAULT_INITIAL_STATE.columnSizing,
-        }),
-        [initialStateConfig, initialTableSize]
-    );
-
-    // --- UI state (reducer)
-    const [ui, dispatch] = useReducer(uiReducer, initialUIState);
-
-    // --- server data state (UI-affecting)
-    const [serverData, setServerData] = useState<T[] | null>(null);
-    const [serverTotal, setServerTotal] = useState<number>(0);
-
-    // --- export UI state
-    const [exportPhase, setExportPhase] = useState<ExportPhase | null>(null);
-    const [exportProgress, setExportProgress] = useState<ExportProgressPayload>({});
-    const [exportController, setExportController] = useState<AbortController | null>(null);
-    const [queuedExportCount, setQueuedExportCount] = useState(0);
-
-    // --- refs (no-render control)
-    const tableContainerRef = useRef<HTMLDivElement>(null);
-    const apiRef = useRef<DataTableApi<T> | null>(null);
-    const exportControllerRef = useRef<AbortController | null>(null);
-    const exportQueueRef = useRef<Promise<void>>(Promise.resolve());
-    const lastSentRef = useRef<string>("");
-
-    // --- latest refs (prevent stale closures in stable API)
-    const uiRef = useLatestRef(ui);
-    const dataRef = useLatestRef(data);;
-    const serverDataRef = useLatestRef(serverData);
-    const nextFetchDelayRef = useRef<number>(0);
-
-    // callbacks refs (super important)
-    const onFetchDataRef = useLatestRef(onFetchData);
-    const onFetchStateChangeRef = useLatestRef(onFetchStateChange);
-    const onDataStateChangeRef = useLatestRef(onDataStateChange);
-
-    const onSortingChangeRef = useLatestRef(onSortingChange);
-    const onPaginationChangeRef = useLatestRef(onPaginationChange);
-    const onGlobalFilterChangeRef = useLatestRef(onGlobalFilterChange);
-    const onColumnFiltersChangeRef = useLatestRef(onColumnFiltersChange);
-
-    const onColumnDragEndRef = useLatestRef(onColumnDragEnd);
-    const onColumnPinningChangeRef = useLatestRef(onColumnPinningChange);
-    const onColumnVisibilityChangeRef = useLatestRef(onColumnVisibilityChange);
-    const onColumnSizingChangeRef = useLatestRef(onColumnSizingChange);
-    const onSelectionChangeRef = useLatestRef(onSelectionChange);
-
-    const onExportProgressRef = useLatestRef(onExportProgress);
-    const onExportCompleteRef = useLatestRef(onExportComplete);
-    const onExportErrorRef = useLatestRef(onExportError);
-    const onExportCancelRef = useLatestRef(onExportCancel);
-    const onExportStateChangeRef = useLatestRef(onExportStateChange);
-    const onServerExportRef = useLatestRef(onServerExport);
-
-
-    // --- debounced fetch helper (can stay as-is)
-    const fetchHandler = useEvent((filters: any, opts: any) => onFetchDataRef.current?.(filters, opts));
-    const { debouncedFetch, isLoading: fetchLoading } = useDebouncedFetch(fetchHandler);
-
-    const tableData = useMemo(() => {
-        return serverData !== null ? serverData : data;
-    }, [serverData, data]);
-
-    const tableTotalRow = useMemo(() => {
-        return serverData !== null ? serverTotal : totalRow || data.length;
-    }, [serverData, serverTotal, totalRow, data]);
-
-    const tableLoading = useMemo(() => {
-        return onFetchData ? loading || fetchLoading : loading;
-    }, [onFetchData, loading, fetchLoading]);
-
-
-    // --- columns enhancement
-    const enhancedColumns = useMemo(() => {
-        let cols = [...columns];
-        if (enableExpanding) {
-            cols = [
-                createExpandingColumn<T>({
-                    ...(slotProps?.expandColumn && typeof slotProps.expandColumn === "object"
-                        ? slotProps.expandColumn
-                        : {}),
-                }),
-                ...cols,
-            ];
-        }
-        if (enableRowSelection) {
-            cols = [
-                createSelectionColumn<T>({
-                    ...(slotProps?.selectionColumn && typeof slotProps.selectionColumn === "object"
-                        ? slotProps.selectionColumn
-                        : {}),
-                    multiSelect: enableMultiRowSelection,
-                }),
-                ...cols,
-            ];
-        }
-        return withIdsDeep(cols);
-    }, [
-        columns,
-        enableExpanding,
-        enableRowSelection,
-        enableMultiRowSelection,
-        slotProps?.expandColumn,
-        slotProps?.selectionColumn,
-    ]);
-
-    // --- fetchData: useEvent so it's stable but reads latest state refs
-    const fetchData = useEvent(async (overrides: Partial<TableState> = {}, options?: { delay?: number; meta?: DataFetchMeta }) => {
-        const s = uiRef.current;
-
-        const filters: Partial<TableFiltersForFetch> = {
-            globalFilter: s.globalFilter,
-            pagination: s.pagination,
-            columnFilter: s.columnFilter,
-            sorting: s.sorting,
-            ...overrides,
-        };
-
-        onFetchStateChangeRef.current?.(filters, options?.meta);
-
-        const handler = onFetchDataRef.current;
-        if (!handler) return;
-
-        const delay = options?.delay ?? 0;
-        const result = await debouncedFetch(filters, { debounceDelay: delay, meta: options?.meta });
-
-        if (result && Array.isArray(result.data) && result.total !== undefined) {
-            setServerData(result.data);
-            setServerTotal(result.total);
-        }
-
-        return result;
-    });
-
-    // --- derived selection counts
-    const isSomeRowsSelected = useMemo(() => {
-        if (!enableBulkActions || !enableRowSelection) return false;
-        if (ui.selectionState.type === "exclude") return ui.selectionState.ids.length < tableTotalRow;
-        return ui.selectionState.ids.length > 0;
-    }, [enableBulkActions, enableRowSelection, ui.selectionState, tableTotalRow]);
-
-    const selectedRowCount = useMemo(() => {
-        if (!enableBulkActions || !enableRowSelection) return 0;
-        if (ui.selectionState.type === "exclude") return tableTotalRow - ui.selectionState.ids.length;
-        return ui.selectionState.ids.length;
-    }, [enableBulkActions, enableRowSelection, ui.selectionState, tableTotalRow]);
-
-
-
-    // --- TanStack Table
-    const table = useReactTable({
-        _features: [ColumnFilterFeature, SelectionFeature],
-        data: tableData,
-        columns: enhancedColumns,
-        initialState: initialStateConfig,
-        state: {
-            ...(enableSorting ? { sorting: ui.sorting } : {}),
-            ...(enablePagination ? { pagination: ui.pagination } : {}),
-            ...(enableGlobalFilter ? { globalFilter: ui.globalFilter } : {}),
-            ...(enableExpanding ? { expanded: ui.expanded } : {}),
-            ...(enableColumnDragging ? { columnOrder: ui.columnOrder } : {}),
-            ...(enableColumnPinning ? { columnPinning: ui.columnPinning } : {}),
-            ...(enableColumnVisibility ? { columnVisibility: ui.columnVisibility } : {}),
-            ...(enableColumnResizing ? { columnSizing: ui.columnSizing } : {}),
-            ...(enableColumnFilter ? { columnFilter: ui.columnFilter } : {}),
-            ...(enableRowSelection ? { selectionState: ui.selectionState } : {}),
-        },
-
-        selectMode,
-        enableAdvanceSelection: !!enableRowSelection,
-        isRowSelectable: isRowSelectable as any,
-
-        ...(enableRowSelection
-            ? {
-                onSelectionStateChange: (updaterOrValue: any) => {
-                    dispatch({
-                        type: "SET_SELECTION",
-                        payload:
-                            typeof updaterOrValue === "function"
-                                ? updaterOrValue(uiRef.current.selectionState)
-                                : updaterOrValue,
-                    });
-                },
-            }
-            : {}),
-
-        enableAdvanceColumnFilter: enableColumnFilter,
-        onColumnFilterChange: (updater: any) => {
-            const next = typeof updater === "function" ? updater(uiRef.current.columnFilter) : updater;
-            dispatch({ type: "SET_COLUMN_FILTER", payload: next });
-        },
-        onColumnFilterApply: (state: ColumnFilterState) => {
-            dispatch({ type: "SET_COLUMN_FILTER_RESET_PAGE", payload: state });
-        },
-
-        ...(enableSorting
-            ? {
-                onSortingChange: (updaterOrValue: any) => {
-                    const prev = uiRef.current.sorting;
-                    const next = typeof updaterOrValue === "function" ? updaterOrValue(prev) : updaterOrValue;
-                    const cleaned = (next || []).filter((s: any) => s?.id);
-                    onSortingChangeRef.current?.(cleaned);
-                    dispatch({ type: "SET_SORTING_RESET_PAGE", payload: cleaned });
-                },
-            }
-            : {}),
-
-        ...(enablePagination
-            ? {
-                onPaginationChange: (updater: any) => {
-                    const prev = uiRef.current.pagination;
-                    const next = typeof updater === "function" ? updater(prev) : updater;
-                    onPaginationChangeRef.current?.(next);
-                    dispatch({ type: "SET_PAGINATION", payload: next });
-                },
-            }
-            : {}),
-
-        ...(enableGlobalFilter
-            ? {
-                onGlobalFilterChange: (updaterOrValue: any) => {
-                    const prev = uiRef.current.globalFilter;
-                    const next = typeof updaterOrValue === "function" ? updaterOrValue(prev) : updaterOrValue;
-                    onGlobalFilterChangeRef.current?.(next);
-                    nextFetchDelayRef.current = 400;
-                    dispatch({ type: "SET_GLOBAL_FILTER_RESET_PAGE", payload: next });
-                },
-            }
-            : {}),
-
-        ...(enableExpanding ? { onExpandedChange: (u: any) => dispatch({ type: "SET_EXPANDED", payload: typeof u === "function" ? u(uiRef.current.expanded) : u }) } : {}),
-        ...(enableColumnDragging ? { onColumnOrderChange: (u: any) => dispatch({ type: "SET_COLUMN_ORDER", payload: typeof u === "function" ? u(uiRef.current.columnOrder) : u }) } : {}),
-        ...(enableColumnPinning ? { onColumnPinningChange: (u: any) => dispatch({ type: "SET_COLUMN_PINNING", payload: typeof u === "function" ? u(uiRef.current.columnPinning) : u }) } : {}),
-        ...(enableColumnVisibility ? { onColumnVisibilityChange: (u: any) => dispatch({ type: "SET_COLUMN_VISIBILITY", payload: typeof u === "function" ? u(uiRef.current.columnVisibility) : u }) } : {}),
-        ...(enableColumnResizing ? { onColumnSizingChange: (u: any) => dispatch({ type: "SET_COLUMN_SIZING", payload: typeof u === "function" ? u(uiRef.current.columnSizing) : u }) } : {}),
-
-        getCoreRowModel: getCoreRowModel(),
-        ...(enableSorting ? { getSortedRowModel: getSortedRowModel() } : {}),
-        ...(enableColumnFilter || enableGlobalFilter ? { getFilteredRowModel: getCombinedFilteredRowModel<T>() } : {}),
-        ...(enablePagination && !isServerPagination ? { getPaginationRowModel: getPaginationRowModel() } : {}),
-
-        enableSorting,
-        manualSorting: isServerSorting,
-        manualFiltering: isServerFiltering,
-
-        enableColumnResizing,
-        columnResizeMode,
-        columnResizeDirection: theme.direction,
-
-        enableColumnPinning,
-        ...(enableExpanding ? { getRowCanExpand: getRowCanExpand as any } : {}),
-
-        manualPagination: isServerPagination,
-        autoResetPageIndex: false,
-
-        rowCount: enablePagination ? (tableTotalRow ?? tableData.length) : tableData.length,
-        getRowId: (row: any, index: number) => generateRowId(row, index, idKey),
-    });
-
-    // --- layout sizing
-    const allLeafColumns = table.getAllLeafColumns();
-    const hasExplicitSizing = allLeafColumns.some((col) => {
-        const { size, minSize, maxSize } = col.columnDef;
-        return size !== undefined || minSize !== undefined || maxSize !== undefined;
-    });
-    const useFixedLayout = fitToScreen || enableColumnResizing || hasExplicitSizing;
-    const tableTotalSize = table.getTotalSize();
-    const tableWidth = fitToScreen ? "100%" : useFixedLayout ? tableTotalSize : "100%";
-
-    const tableStyle: CSSProperties = {
-        width: tableWidth,
-        minWidth: fitToScreen ? tableTotalSize : undefined,
-        tableLayout: useFixedLayout ? "fixed" : "auto",
-    };
-
-    // --- virtualization
-    const rows = table.getRowModel().rows;
-    const rowVirtualizer = useVirtualizer({
-        count: rows.length,
-        getScrollElement: () => tableContainerRef.current,
-        estimateSize: () => estimateRowHeight,
-        overscan: 10,
-        enabled: enableVirtualization && !enablePagination && rows.length > 0,
-    });
-
-
-    const serverKey = useMemo(() => {
-        if (!(isServerMode || isServerPagination || isServerFiltering || isServerSorting)) return null;
-
-        return JSON.stringify({
-            sorting: ui.sorting,
-            pagination: ui.pagination,
-            globalFilter: ui.globalFilter,
-            columnFilter: { filters: ui.columnFilter.filters, logic: ui.columnFilter.logic }, // only applied
-        });
-    }, [isServerMode, isServerPagination, isServerFiltering, isServerSorting, ui.sorting, ui.pagination, ui.globalFilter, ui.columnFilter]);
-    const serverKeyRef = useLatestRef(serverKey);
-    const lastServerKeyRef = useRef<string | null>(null);
-
-    // --- initial fetch
-    useEffect(() => {
-        if (!initialLoadData) return;
-        // If we're in server mode, mark current serverKey as already handled
-        // so the serverKey effect doesn't immediately fetch again.
-        if (serverKeyRef.current) {
-            lastServerKeyRef.current = serverKeyRef.current;
-        }
-        if (onFetchData || onFetchStateChange) {
-            void fetchData({}, { delay: 0, meta: { reason: "initial" } });
-        }
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
-
-    useEffect(() => {
-        if (!serverKey) return;
-        if (serverKey === lastServerKeyRef.current) return;
-        lastServerKeyRef.current = serverKey;
-
-        const delay = nextFetchDelayRef.current ?? 0;
-        nextFetchDelayRef.current = 0; // reset after using
-
-        const timeoutId = setTimeout(() => {
-            void fetchData({}, { delay, meta: { reason: "stateChange" } });
-        }, 0);
-        return () => clearTimeout(timeoutId);
-    }, [serverKey, fetchData]);
-
-    // columnFilter apply handler stays explicit (button), but you can also auto-fetch on change if needed
-    const handleColumnFilterChangeHandler = useCallback(
-        (updater: any, isApply = false) => {
-            const prev = uiRef.current.columnFilter;
-            const next = typeof updater === "function" ? updater(prev) : updater;
-            if (isApply) {
-                nextFetchDelayRef.current = 0;
-                dispatch({ type: "SET_COLUMN_FILTER_RESET_PAGE", payload: next });
-            } else {
-                dispatch({ type: "SET_COLUMN_FILTER", payload: next });
-            }
-            onColumnFiltersChangeRef.current?.(next, isApply);
-        },
-        [onColumnFiltersChangeRef, uiRef]
-    );
-
-    // --- emit table state (dedupe)
-    useEffect(() => {
-        const cb = onDataStateChangeRef.current;
-        if (!cb) return;
-
-        const live = table.getState();
-        const payload = {
-            sorting: live.sorting,
-            pagination: live.pagination,
-            globalFilter: live.globalFilter,
-            columnFilter: live.columnFilter,
-            columnVisibility: live.columnVisibility,
-            columnSizing: live.columnSizing,
-            columnOrder: live.columnOrder,
-            columnPinning: live.columnPinning,
-        };
-        const key = JSON.stringify(payload);
-        if (key === lastSentRef.current) return;
-        lastSentRef.current = key;
-        cb(payload);
-    }, [table, ui.sorting, ui.pagination, ui.globalFilter, ui.columnFilter, ui.columnVisibility, ui.columnSizing, ui.columnOrder, ui.columnPinning, onDataStateChangeRef]);
-
-    // --- helpers
-    const resetPageToFirst = useCallback(() => {
-        return { pageIndex: 0, pageSize: uiRef.current.pagination.pageSize };
-    }, [uiRef]);
-
-    const normalizeRefreshOptions = useCallback(
-        (options?: boolean | DataRefreshOptions, fallbackReason: string = "refresh") => {
-            if (typeof options === "boolean") return { resetPagination: options, force: false, reason: fallbackReason };
-            return {
-                resetPagination: options?.resetPagination ?? false,
-                force: options?.force ?? false,
-                reason: options?.reason ?? fallbackReason,
-            };
-        },
-        []
-    );
-
-    const triggerRefresh = useCallback(
-        async (options?: boolean | DataRefreshOptions, fallbackReason: string = "refresh") => {
-            const n = normalizeRefreshOptions(options, fallbackReason);
-            const current = uiRef.current.pagination;
-            const nextPagination = enablePagination
-                ? { pageIndex: n.resetPagination ? 0 : current.pageIndex, pageSize: current.pageSize }
-                : undefined;
-
-            if (nextPagination) {
-                nextFetchDelayRef.current = 0;
-                dispatch({ type: "SET_PAGINATION", payload: nextPagination });
-                onPaginationChangeRef.current?.(nextPagination);
-            }
-            const paginationChanged = !!nextPagination &&
-                (nextPagination.pageIndex !== current.pageIndex || nextPagination.pageSize !== current.pageSize);
-
-            if (!paginationChanged) {
-                await fetchData({}, { delay: 0, meta: { reason: n.reason, force: n.force } });
-            }
-        },
-        [enablePagination, fetchData, normalizeRefreshOptions, onPaginationChangeRef, uiRef]
-    );
-
-    const getResetPayload = useCallback((): Partial<EngineUIState> => {
-        const resetSorting = initialStateConfig.sorting || [];
-        const resetGlobalFilter = initialStateConfig.globalFilter ?? "";
-        const resetColumnFilter = (initialStateConfig.columnFilter ?? DEFAULT_INITIAL_STATE.columnFilter) as ColumnFilterState;
-
-        const resetPagination = enablePagination
-            ? (initialStateConfig.pagination || { pageIndex: 0, pageSize: 10 })
-            : uiRef.current.pagination;
-
-        return {
-            sorting: resetSorting,
-            globalFilter: resetGlobalFilter,
-            columnFilter: resetColumnFilter,
-            ...(enablePagination ? { pagination: resetPagination } : {}),
-            selectionState: initialStateConfig.selectionState ?? DEFAULT_INITIAL_STATE.selectionState,
-            expanded: {},
-            columnVisibility: initialStateConfig.columnVisibility || {},
-            columnSizing: initialStateConfig.columnSizing || {},
-            columnOrder: initialStateConfig.columnOrder || [],
-            columnPinning: initialStateConfig.columnPinning || { left: [], right: [] },
-        };
-    }, [enablePagination, initialStateConfig]);
-
-    const resetAllAndReload = useCallback(() => {
-        const payload = getResetPayload();
-        dispatch({ type: "RESET_ALL", payload });
-        void fetchData(
-            {
-                sorting: payload.sorting as any,
-                globalFilter: payload.globalFilter as any,
-                columnFilter: payload.columnFilter as any,
-                ...(enablePagination ? { pagination: payload.pagination as any } : {}),
-            },
-            { delay: 0, meta: { reason: "reset", force: true } }
-        );
-    }, [enablePagination, fetchData, getResetPayload]);
-
-    // --- export (refs + small UI state)
-    const setExportControllerSafely = useCallback(
-        (value: AbortController | null | ((current: AbortController | null) => AbortController | null)) => {
-            setExportController((current) => {
-                const next = typeof value === "function" ? (value as any)(current) : value;
-                exportControllerRef.current = next;
-                return next;
-            });
-        },
-        []
-    );
-
-    const handleExportProgressInternal = useCallback((p: ExportProgressPayload) => {
-        setExportProgress(p || {});
-        onExportProgressRef.current?.(p);
-    }, []);
-
-    const handleExportStateChangeInternal = useCallback((s: ExportStateChange) => {
-        setExportPhase(s.phase);
-        if (s.processedRows !== undefined || s.totalRows !== undefined || s.percentage !== undefined) {
-            setExportProgress({
-                processedRows: s.processedRows,
-                totalRows: s.totalRows,
-                percentage: s.percentage,
-            });
-        }
-        onExportStateChangeRef.current?.(s);
-    }, []);
-
-    const runExportWithPolicy = useCallback(
-        async (options: { format: "csv" | "excel"; filename: string; mode: "client" | "server"; execute: (controller: AbortController) => Promise<void> }) => {
-            const { format, filename, mode, execute } = options;
-
-            const startExecution = async () => {
-                const controller = new AbortController();
-                setExportProgress({});
-                setExportControllerSafely(controller);
-                try {
-                    await execute(controller);
-                } finally {
-                    setExportControllerSafely((cur) => (cur === controller ? null : cur));
-                }
-            };
-
-            if (exportConcurrency === "queue") {
-                setQueuedExportCount((p) => p + 1);
-                const runQueued = async () => {
-                    setQueuedExportCount((p) => Math.max(0, p - 1));
-                    await startExecution();
-                };
-                const queuedPromise = exportQueueRef.current.catch(() => undefined).then(runQueued);
-                exportQueueRef.current = queuedPromise;
-                return queuedPromise;
-            }
-
-            const active = exportControllerRef.current;
-            if (active) {
-                if (exportConcurrency === "ignoreIfRunning") {
-                    handleExportStateChangeInternal({
-                        phase: "error",
-                        mode,
-                        format,
-                        filename,
-                        message: "An export is already running",
-                        code: "EXPORT_IN_PROGRESS",
-                        endedAt: Date.now(),
-                    } as any);
-                    onExportErrorRef.current?.({ message: "An export is already running", code: "EXPORT_IN_PROGRESS" });
-                    return;
-                }
-                if (exportConcurrency === "cancelAndRestart") active.abort();
-            }
-
-            await startExecution();
-        },
-        [exportConcurrency, handleExportStateChangeInternal, onExportErrorRef, setExportControllerSafely]
-    );
-
-    const handleCancelExport = useCallback(() => {
-        const active = exportControllerRef.current;
-        if (!active) return;
-        active.abort();
-        setExportControllerSafely((cur) => (cur === active ? null : cur));
-        onExportCancelRef.current?.();
-    }, [onExportCancelRef, setExportControllerSafely]);
-
-    const isExporting = exportController !== null;
-
-    // --- stable API (created once)
-    if (!apiRef.current) {
-        apiRef.current = {} as DataTableApi<T>;
-
-        // IMPORTANT: do NOT capture `table/ui/data` here. Always read from refs inside methods.
-        (apiRef.current as any).table = { getTable: () => table }; // will be updated below via tableRef
-        // We'll overwrite getTable below with a ref-backed function.
-    }
-
-    // table ref so API always returns latest table instance
-    const tableRef = useLatestRef(table);
-
-
-    useEffect(() => {
-        const api = apiRef.current!;
-        api.table = { getTable: () => tableRef.current } as any;
-
-        // --- state getters
-        api.state = {
-            getTableState: () => tableRef.current.getState(),
-            getCurrentFilters: () => tableRef.current.getState().columnFilter,
-            getCurrentSorting: () => tableRef.current.getState().sorting,
-            getCurrentPagination: () => tableRef.current.getState().pagination,
-            getCurrentSelection: () => uiRef.current.selectionState,
-            getGlobalFilter: () => tableRef.current.getState().globalFilter,
-        };
-
-        // --- data
-        const getBaseData = () => {
-            const sData = serverDataRef.current;
-            return sData !== null ? sData : dataRef.current;
-        };
-        const getRowIndexById = (arr: T[], rowId: string) =>
-            arr.findIndex((row, i) => generateRowId(row, i, idKey) === rowId);
-        api.data = {
-            refresh: (options?: boolean | DataRefreshOptions) => void triggerRefresh(options, "refresh"),
-            reload: (options: DataRefreshOptions = {}) => void triggerRefresh({ ...options, reason: options.reason ?? "reload" }, "reload"),
-            resetAll: () => resetAllAndReload(),
-            getAllData: () => [...getBaseData()],
-            getRowData: (rowId: string) => {
-                const rows = tableRef.current.getRowModel().rows;
-                const row = rows.find((r: any) => r.id === rowId);
-                return row?.original as T | undefined;
-            },
-            getRowByIndex: (index: number) => tableRef.current.getRowModel().rows[index]?.original as T | undefined,
-            getDataCount: () => getBaseData().length,
-            getFilteredDataCount: () => tableRef.current.getFilteredRowModel().rows.length,
-            updateRow: (rowId: string, updates: Partial<T>) => {
-                const base = getBaseData();
-                const idx = getRowIndexById(base, rowId);
-                if (idx === -1) return;
-                const next = [...base];
-                next[idx] = { ...next[idx], ...updates } as T;
-                setServerData(next);
-                setServerTotal(next.length);
-            },
-            updateRowByIndex: (index: number, updates: Partial<T>) => {
-                const base = getBaseData();
-                if (index < 0 || index >= base.length) return;
-                const next = [...base];
-                next[index] = { ...next[index], ...updates } as T;
-                setServerData(next);
-                setServerTotal(next.length);
-            },
-            insertRow: (newRow: T, index?: number) => {
-                const base = getBaseData();
-                const next = index == null ? [...base, newRow] : [...base.slice(0, index), newRow, ...base.slice(index)];
-                setServerData(next);
-                setServerTotal(next.length);
-            },
-            deleteRow: (rowId: string) => {
-                const base = getBaseData();
-                const idx = getRowIndexById(base, rowId);
-                if (idx === -1) return;
-                const next = base.filter((_, i) => i !== idx);
-                setServerData(next);
-                setServerTotal(next.length);
-            },
-            deleteRowByIndex: (index: number) => {
-                const base = getBaseData();
-                if (index < 0 || index >= base.length) return;
-                const next = base.filter((_, i) => i !== index);
-                setServerData(next);
-                setServerTotal(next.length);
-            },
-            deleteSelectedRows: () => {
-                const state = tableRef.current.getSelectionState?.();
-                if (!state || state.type !== "include" || !state.ids.length) return;
-                const base = getBaseData();
-                const ids = new Set(state.ids);
-                const next = base.filter((row, i) => !ids.has(generateRowId(row, i, idKey)));
-                setServerData(next);
-                setServerTotal(next.length);
-                tableRef.current.deselectAll?.();
-            },
-            replaceAllData: (newData: T[]) => {
-                setServerData(newData);
-                setServerTotal(newData.length);
-            },
-            updateMultipleRows: (updates: Array<{ rowId: string; data: Partial<T> }>) => {
-                const base = getBaseData();
-                const next = [...base];
-                for (const { rowId, data: u } of updates) {
-                    const idx = getRowIndexById(next, rowId);
-                    if (idx !== -1) next[idx] = { ...next[idx], ...u } as T;
-                }
-                setServerData(next);
-                setServerTotal(next.length);
-            },
-            insertMultipleRows: (newRows: T[], startIndex?: number) => {
-                const base = getBaseData();
-                const idx = startIndex ?? base.length;
-                const next = [...base.slice(0, idx), ...newRows, ...base.slice(idx)];
-                setServerData(next);
-                setServerTotal(next.length);
-            },
-            deleteMultipleRows: (rowIds: string[]) => {
-                const ids = new Set(rowIds);
-                const base = getBaseData();
-                const next = base.filter((row, i) => !ids.has(generateRowId(row, i, idKey)));
-                setServerData(next);
-                setServerTotal(next.length);
-            },
-            updateField: (rowId: string, fieldName: keyof T, value: any) => {
-                api.data.updateRow(rowId, { [fieldName]: value } as Partial<T>);
-            },
-            updateFieldByIndex: (index: number, fieldName: keyof T, value: any) => {
-                api.data.updateRowByIndex(index, { [fieldName]: value } as Partial<T>);
-            },
-            findRows: (predicate: (row: T) => boolean) => getBaseData().filter(predicate),
-            findRowIndex: (predicate: (row: T) => boolean) => getBaseData().findIndex(predicate),
-        } as any;
-
-        // --- layout (save/restore column visibility, order, sizing, pinning)
-        api.layout = {
-            saveLayout: () => {
-                const s = tableRef.current.getState();
-                return {
-                    columnVisibility: s.columnVisibility ?? {},
-                    columnOrder: s.columnOrder ?? [],
-                    columnSizing: s.columnSizing ?? {},
-                    columnPinning: s.columnPinning ?? { left: [], right: [] },
-                    pagination: s.pagination ?? { pageIndex: 0, pageSize: 10 },
-                    globalFilter: s.globalFilter ?? "",
-                    columnFilter: s.columnFilter ?? [],
-                };
-            },
-            restoreLayout: (layout: any) => {
-
-                if (layout.columnVisibility) dispatch({ type: "SET_COLUMN_VISIBILITY", payload: layout.columnVisibility });
-                if (layout.columnOrder) { dispatch({ type: "SET_COLUMN_ORDER", payload: layout.columnOrder }); onColumnDragEndRef.current?.(layout.columnOrder); }
-                if (layout.columnSizing) { dispatch({ type: "SET_COLUMN_SIZING", payload: layout.columnSizing }); onColumnSizingChangeRef.current?.(layout.columnSizing); }
-                if (layout.columnPinning) { dispatch({ type: "SET_COLUMN_PINNING", payload: layout.columnPinning }); onColumnPinningChangeRef.current?.(layout.columnPinning); }
-                if (layout.pagination && enablePagination) dispatch({ type: "SET_PAGINATION", payload: layout.pagination as any });
-                if (layout.globalFilter !== undefined) dispatch({ type: "SET_GLOBAL_FILTER_RESET_PAGE", payload: layout.globalFilter });
-                if (layout.columnFilter) dispatch({ type: "SET_COLUMN_FILTER", payload: layout.columnFilter as any });
-            },
-            resetLayout: () => {
-                const vis = initialStateConfig.columnVisibility || {};
-                const order = initialStateConfig.columnOrder || [];
-                const sizing = initialStateConfig.columnSizing || {};
-                const pinning = initialStateConfig.columnPinning || { left: [] as string[], right: [] as string[] };
-                dispatch({ type: "SET_COLUMN_VISIBILITY", payload: vis });
-                dispatch({ type: "SET_COLUMN_ORDER", payload: order });
-                dispatch({ type: "SET_COLUMN_SIZING", payload: sizing });
-                dispatch({ type: "SET_COLUMN_PINNING", payload: pinning });
-                dispatch({ type: "SET_PAGINATION", payload: { pageIndex: 0, pageSize: 10 } });
-                dispatch({ type: "SET_GLOBAL_FILTER_RESET_PAGE", payload: "" });
-                dispatch({ type: "SET_COLUMN_FILTER", payload: [] });
-                onColumnDragEndRef.current?.(order);
-                onColumnSizingChangeRef.current?.(sizing);
-                onColumnPinningChangeRef.current?.(pinning);
-            },
-            resetAll: () => {
-                api.layout.resetLayout();
-                resetAllAndReload();
-            },
-        } as any;
-
-        // --- sorting/pagination/filtering - dispatch + callbacks + server fetch policies
-        api.sorting = {
-            setSorting: (next: SortingState) => {
-                const cleaned = (next || []).filter((s: any) => s?.id);
-                onSortingChangeRef.current?.(cleaned);
-                nextFetchDelayRef.current = 0;
-                dispatch({ type: "SET_SORTING_RESET_PAGE", payload: cleaned });
-            },
-            sortColumn: (columnId: string, direction: 'asc' | 'desc' | false) => {
-                const next: SortingState = direction === false ? [] : [{ id: columnId, desc: direction === 'desc' }];
-                onSortingChangeRef.current?.(next);
-                nextFetchDelayRef.current = 0;
-                dispatch({ type: "SET_SORTING_RESET_PAGE", payload: next });
-            },
-            clearSorting: () => {
-                onSortingChangeRef.current?.([]);
-                nextFetchDelayRef.current = 0;
-                dispatch({ type: "SET_SORTING_RESET_PAGE", payload: [] });
-            },
-            resetSorting: () => {
-                const next = (initialStateConfig.sorting || []) as SortingState;
-                onSortingChangeRef.current?.(next);
-                nextFetchDelayRef.current = 0;
-                dispatch({ type: "SET_SORTING_RESET_PAGE", payload: next });
-            },
-        } as any;
-
-        api.pagination = {
-            goToPage: (pageIndex: number) => {
-                const prev = uiRef.current.pagination;
-                const next = { ...prev, pageIndex };
-                onPaginationChangeRef.current?.(next);
-                nextFetchDelayRef.current = 0;
-                dispatch({ type: "SET_PAGINATION", payload: next });
-            },
-            nextPage: () => {
-                const prev = uiRef.current.pagination;
-                api.pagination.goToPage(Math.min(prev.pageIndex + 1, Math.max(0, Math.ceil((tableTotalRow ?? 0) / prev.pageSize) - 1)));
-            },
-            previousPage: () => {
-                const prev = uiRef.current.pagination;
-                api.pagination.goToPage(Math.max(0, prev.pageIndex - 1));
-            },
-            setPageSize: (pageSize: number) => {
-                const next = { pageIndex: 0, pageSize };
-                onPaginationChangeRef.current?.(next);
-                nextFetchDelayRef.current = 0;
-                dispatch({ type: "SET_PAGINATION", payload: next });
-            },
-            goToFirstPage: () => api.pagination.goToPage(0),
-            goToLastPage: () => {
-                const prev = uiRef.current.pagination;
-                api.pagination.goToPage(Math.max(0, Math.ceil((tableTotalRow ?? 0) / prev.pageSize) - 1));
-            },
-            resetPagination: () => {
-                const next = (initialStateConfig.pagination || { pageIndex: 0, pageSize: 10 }) as any;
-                onPaginationChangeRef.current?.(next);
-                nextFetchDelayRef.current = 0;
-                dispatch({ type: "SET_PAGINATION", payload: next });
-            },
-        } as any;
-
-        api.filtering = {
-            setGlobalFilter: (filter: string) => {
-                onGlobalFilterChangeRef.current?.(filter);
-                nextFetchDelayRef.current = 400;
-                dispatch({ type: "SET_GLOBAL_FILTER_RESET_PAGE", payload: filter });
-            },
-            clearGlobalFilter: () => {
-                onGlobalFilterChangeRef.current?.("");
-                nextFetchDelayRef.current = 400;
-                dispatch({ type: "SET_GLOBAL_FILTER_RESET_PAGE", payload: "" });
-            },
-            setColumnFilters: (filters: ColumnFilterState, isApply = false) => handleColumnFilterChangeHandler(filters, isApply),
-            addColumnFilter: (columnId: string, operator: string, value: any) => tableRef.current.addColumnFilter?.(columnId, operator, value),
-            removeColumnFilter: (filterId: string) => tableRef.current.removeColumnFilter?.(filterId),
-            clearAllFilters: () => tableRef.current.resetColumnFilter?.(),
-            resetFilters: () => {
-                const reset = (initialStateConfig.columnFilter ?? DEFAULT_INITIAL_STATE.columnFilter) as ColumnFilterState;
-                handleColumnFilterChangeHandler(reset, true);
-            },
-        } as any;
-
-        api.columnVisibility = {
-            showColumn: (id: string) => dispatch({ type: "SET_COLUMN_VISIBILITY", payload: { ...uiRef.current.columnVisibility, [id]: true } }),
-            hideColumn: (id: string) => dispatch({ type: "SET_COLUMN_VISIBILITY", payload: { ...uiRef.current.columnVisibility, [id]: false } }),
-            toggleColumn: (id: string) => dispatch({ type: "SET_COLUMN_VISIBILITY", payload: { ...uiRef.current.columnVisibility, [id]: !uiRef.current.columnVisibility[id] } }),
-            showAllColumns: () => dispatch({ type: "SET_COLUMN_VISIBILITY", payload: {} }),
-            hideAllColumns: () => {
-                const all = tableRef.current.getAllLeafColumns().reduce((acc, col) => ({ ...acc, [col.id]: false }), {} as Record<string, boolean>);
-                dispatch({ type: "SET_COLUMN_VISIBILITY", payload: all });
-            },
-            resetColumnVisibility: () => dispatch({ type: "SET_COLUMN_VISIBILITY", payload: initialStateConfig.columnVisibility || {} }),
-        } as any;
-
-        api.columnOrdering = {
-            setColumnOrder: (next: ColumnOrderState) => {
-                dispatch({ type: "SET_COLUMN_ORDER", payload: next });
-                onColumnDragEndRef.current?.(next);
-            },
-            moveColumn: (columnId: string, toIndex: number) => {
-                const order = uiRef.current.columnOrder.length ? uiRef.current.columnOrder : tableRef.current.getAllLeafColumns().map((c: any) => c.id);
-                const from = order.indexOf(columnId);
-                if (from === -1 || toIndex < 0 || toIndex >= order.length) return;
-                const next = [...order];
-                next.splice(from, 1);
-                next.splice(toIndex, 0, columnId);
-                dispatch({ type: "SET_COLUMN_ORDER", payload: next });
-                onColumnDragEndRef.current?.(next);
-            },
-            resetColumnOrder: () => dispatch({ type: "SET_COLUMN_ORDER", payload: initialStateConfig.columnOrder || [] }),
-        } as any;
-
-        api.columnPinning = {
-            pinColumnLeft: (columnId: string) => {
-                const cur = uiRef.current.columnPinning;
-                const left = cur.left.includes(columnId) ? cur.left : [...cur.left.filter((id: string) => id !== columnId), columnId];
-                const right = cur.right.filter((id: string) => id !== columnId);
-                dispatch({ type: "SET_COLUMN_PINNING", payload: { left, right } });
-                onColumnPinningChangeRef.current?.({ left, right });
-            },
-            pinColumnRight: (columnId: string) => {
-                const cur = uiRef.current.columnPinning;
-                const left = cur.left.filter((id: string) => id !== columnId);
-                const right = cur.right.includes(columnId) ? cur.right : [...cur.right.filter((id: string) => id !== columnId), columnId];
-                dispatch({ type: "SET_COLUMN_PINNING", payload: { left, right } });
-                onColumnPinningChangeRef.current?.({ left, right });
-            },
-            unpinColumn: (columnId: string) => {
-                const cur = uiRef.current.columnPinning;
-                const left = cur.left.filter((id: string) => id !== columnId);
-                const right = cur.right.filter((id: string) => id !== columnId);
-                dispatch({ type: "SET_COLUMN_PINNING", payload: { left, right } });
-                onColumnPinningChangeRef.current?.({ left, right });
-            },
-            setPinning: (next: ColumnPinningState) => {
-                dispatch({ type: "SET_COLUMN_PINNING", payload: next });
-                onColumnPinningChangeRef.current?.(next);
-            },
-            resetColumnPinning: () => dispatch({ type: "SET_COLUMN_PINNING", payload: initialStateConfig.columnPinning || { left: [], right: [] } }),
-        } as any;
-
-        api.columnResizing = {
-            resizeColumn: (columnId: string, width: number) => {
-                const cur = uiRef.current.columnSizing;
-                dispatch({ type: "SET_COLUMN_SIZING", payload: { ...cur, [columnId]: width } });
-                onColumnSizingChangeRef.current?.({ ...cur, [columnId]: width });
-            },
-            autoSizeColumn: (columnId: string) => { void columnId; /* no-op: would require measure; use reset for default */ },
-            autoSizeAllColumns: () => { /* no-op */ },
-            resetColumnSizing: () => dispatch({ type: "SET_COLUMN_SIZING", payload: initialStateConfig.columnSizing || {} }),
-        } as any;
-
-        api.selection = {
-            selectRow: (rowId: string) => tableRef.current.selectRow?.(rowId),
-            deselectRow: (rowId: string) => tableRef.current.deselectRow?.(rowId),
-            toggleRowSelection: (rowId: string) => tableRef.current.toggleRowSelected?.(rowId),
-            selectAll: () => tableRef.current.selectAll?.(),
-            deselectAll: () => tableRef.current.deselectAll?.(),
-            toggleSelectAll: () => tableRef.current.toggleAllRowsSelected?.(),
-            getSelectionState: () => tableRef.current.getSelectionState?.() || ({ ids: [], type: "include" } as const),
-            getSelectedRows: () => tableRef.current.getSelectedRows(),
-            getSelectedCount: () => tableRef.current.getSelectedCount(),
-            isRowSelected: (rowId: string) => tableRef.current.getIsRowSelected(rowId) || false,
-        } as any;
-
-        // --- export API (use your existing exportClientData/exportServerData)
-        api.export = {
-            exportCSV: async (options: DataTableExportApiOptions = {}) => {
-                const fn = options.filename ?? exportFilename;
-                const chunkSize = options.chunkSize ?? exportChunkSize;
-                const strictTotalCheck = options.strictTotalCheck ?? exportStrictTotalCheck;
-                const sanitizeCSV = options.sanitizeCSV ?? exportSanitizeCSV;
-
-                const mode: "client" | "server" = dataMode === "server" && !!onServerExportRef.current ? "server" : "client";
-
-                await runExportWithPolicy({
-                    format: "csv",
-                    filename: fn,
-                    mode,
-                    execute: async (controller) => {
-                        // TODO: keep your state-change event mapping (starting/progress/completed/cancel/error)
-                        if (mode === "server" && onServerExportRef.current) {
-                            await exportServerData(tableRef.current, {
-                                format: "csv",
-                                filename: fn,
-                                fetchData: (filters: any, selection: any, signal?: AbortSignal) =>
-                                    onServerExportRef.current?.(filters, selection, signal),
-                                currentFilters: {
-                                    globalFilter: tableRef.current.getState().globalFilter,
-                                    columnFilter: tableRef.current.getState().columnFilter,
-                                    sorting: tableRef.current.getState().sorting,
-                                    pagination: tableRef.current.getState().pagination,
-                                },
-                                selection: tableRef.current.getSelectionState?.(),
-                                onProgress: handleExportProgressInternal,
-                                onComplete: onExportCompleteRef.current,
-                                onError: onExportErrorRef.current,
-                                onStateChange: (s: any) => handleExportStateChangeInternal({ ...s, mode, format: "csv", filename: fn, queueLength: queuedExportCount } as any),
-                                signal: controller.signal,
-                                chunkSize,
-                                strictTotalCheck,
-                                sanitizeCSV,
-                            });
-                            return;
-                        }
-
-                        await exportClientData(tableRef.current, {
-                            format: "csv",
-                            filename: fn,
-                            onProgress: handleExportProgressInternal,
-                            onComplete: onExportCompleteRef.current,
-                            onError: onExportErrorRef.current,
-                            onStateChange: (s: any) => handleExportStateChangeInternal({ ...s, mode, format: "csv", filename: fn, queueLength: queuedExportCount } as any),
-                            signal: controller.signal,
-                            sanitizeCSV,
-                        });
-                    },
-                });
-            },
-
-            exportExcel: async (options: DataTableExportApiOptions = {}) => {
-                const fn = options.filename ?? exportFilename;
-                const chunkSize = options.chunkSize ?? exportChunkSize;
-                const strictTotalCheck = options.strictTotalCheck ?? exportStrictTotalCheck;
-                const sanitizeCSV = options.sanitizeCSV ?? exportSanitizeCSV;
-
-                const mode: "client" | "server" = dataMode === "server" && !!onServerExportRef.current ? "server" : "client";
-
-                await runExportWithPolicy({
-                    format: "excel",
-                    filename: fn,
-                    mode,
-                    execute: async (controller) => {
-                        // TODO: keep your state-change event mapping (starting/progress/completed/cancel/error)
-                        if (mode === "server" && onServerExportRef.current) {
-                            await exportServerData(tableRef.current, {
-                                format: "excel",
-                                filename: fn,
-                                fetchData: (filters: any, selection: any, signal?: AbortSignal) =>
-                                    onServerExportRef.current?.(filters, selection, signal),
-                                currentFilters: {
-                                    globalFilter: tableRef.current.getState().globalFilter,
-                                    columnFilter: tableRef.current.getState().columnFilter,
-                                    sorting: tableRef.current.getState().sorting,
-                                    pagination: tableRef.current.getState().pagination,
-                                },
-                                selection: tableRef.current.getSelectionState?.(),
-                                onProgress: handleExportProgressInternal,
-                                onComplete: onExportCompleteRef.current,
-                                onError: onExportErrorRef.current,
-                                onStateChange: (s: any) => handleExportStateChangeInternal({ ...s, mode, format: "csv", filename: fn, queueLength: queuedExportCount } as any),
-                                signal: controller.signal,
-                                chunkSize,
-                                strictTotalCheck,
-                                sanitizeCSV,
-                            });
-                            return;
-                        }
-
-                        await exportClientData(tableRef.current, {
-                            format: "excel",
-                            filename: fn,
-                            onProgress: handleExportProgressInternal,
-                            onComplete: onExportCompleteRef.current,
-                            onError: onExportErrorRef.current,
-                            onStateChange: (s: any) => handleExportStateChangeInternal({ ...s, mode, format: "csv", filename: fn, queueLength: queuedExportCount } as any),
-                            signal: controller.signal,
-                            sanitizeCSV,
-                        });
-                    },
-                });
-            },
-
-            exportServerData: async (options: { format: 'csv' | 'excel'; filename?: string; fetchData: (filters?: Partial<any>, selection?: SelectionState, signal?: AbortSignal) => Promise<any>; pageSize?: number; includeHeaders?: boolean; chunkSize?: number; strictTotalCheck?: boolean; sanitizeCSV?: boolean }) => {
-                const { format, filename: fn = exportFilename, fetchData: customFetchData, chunkSize: cs = exportChunkSize, strictTotalCheck: st = exportStrictTotalCheck, sanitizeCSV: san = exportSanitizeCSV } = options;
-                await runExportWithPolicy({
-                    format,
-                    filename: fn,
-                    mode: "server",
-                    execute: async (controller) => {
-                        await exportServerData(tableRef.current, {
-                            format,
-                            filename: fn,
-                            fetchData: customFetchData,
-                            currentFilters: { globalFilter: tableRef.current.getState().globalFilter, columnFilter: tableRef.current.getState().columnFilter, sorting: tableRef.current.getState().sorting, pagination: tableRef.current.getState().pagination },
-                            selection: tableRef.current.getSelectionState?.(),
-                            onProgress: handleExportProgressInternal,
-                            onComplete: onExportCompleteRef.current,
-                            onError: onExportErrorRef.current,
-                            onStateChange: (s: any) => handleExportStateChangeInternal({ ...s, mode: "server", format, filename: fn, queueLength: queuedExportCount } as any),
-                            signal: controller.signal,
-                            chunkSize: cs,
-                            strictTotalCheck: st,
-                            sanitizeCSV: san,
-                        });
-                    },
-                });
-            },
-            isExporting: () => exportControllerRef.current != null,
-            cancelExport: () => handleCancelExport(),
-        } as any;
-    }, [dataMode, exportChunkSize, exportFilename, exportSanitizeCSV, exportStrictTotalCheck, fetchData, handleCancelExport, handleColumnFilterChangeHandler, handleExportProgressInternal, handleExportStateChangeInternal, initialStateConfig, isServerMode, isServerPagination, isServerSorting, resetAllAndReload, resetPageToFirst, runExportWithPolicy, triggerRefresh, queuedExportCount, tableTotalRow, idKey, tableRef, uiRef, serverDataRef, dataRef, onSortingChangeRef, onPaginationChangeRef, onGlobalFilterChangeRef, onColumnDragEndRef, onColumnPinningChangeRef, onColumnSizingChangeRef, onServerExportRef, onExportCompleteRef, onExportErrorRef]);
-
-    // --- imperative handlers (used by TanStack callbacks above or view)
-    const handleSortingChange = useCallback(
-        (updaterOrValue: Updater<SortingState>) => {
-            const prev = uiRef.current.sorting;
-            const next = typeof updaterOrValue === "function" ? updaterOrValue(prev) : updaterOrValue;
-            const cleaned = (next || []).filter((s: any) => s?.id);
-            onSortingChangeRef.current?.(cleaned);
-            nextFetchDelayRef.current = 0;
-            dispatch({ type: "SET_SORTING_RESET_PAGE", payload: cleaned });
-        },
-        [onSortingChangeRef, uiRef]
-    );
-
-    const handlePaginationChange = useCallback(
-        (updater: Updater<PaginationState>) => {
-            const prev = uiRef.current.pagination;
-            const next = typeof updater === "function" ? updater(prev) : updater;
-            onPaginationChangeRef.current?.(next);
-            nextFetchDelayRef.current = 0;
-            dispatch({ type: "SET_PAGINATION", payload: next });
-        },
-        [onPaginationChangeRef, uiRef]
-    );
-
-    const handleGlobalFilterChange = useCallback(
-        (updaterOrValue: Updater<string>) => {
-            const prev = uiRef.current.globalFilter;
-            const next = typeof updaterOrValue === "function" ? updaterOrValue(prev) : updaterOrValue;
-            onGlobalFilterChangeRef.current?.(next);
-            nextFetchDelayRef.current = 400;
-            dispatch({ type: "SET_GLOBAL_FILTER_RESET_PAGE", payload: next });
-        },
-        [onGlobalFilterChangeRef, uiRef]
-    );
-
-    const handleColumnOrderChange = useCallback(
-        (updated: Updater<ColumnOrderState>) => {
-            const prev = uiRef.current.columnOrder;
-            const next = typeof updated === "function" ? updated(prev) : updated;
-            dispatch({ type: "SET_COLUMN_ORDER", payload: next });
-            onColumnDragEndRef.current?.(next);
-        },
-        [onColumnDragEndRef, uiRef]
-    );
-
-    const handleColumnPinningChange = useCallback(
-        (updated: Updater<ColumnPinningState>) => {
-            const prev = uiRef.current.columnPinning;
-            const next = typeof updated === "function" ? updated(prev) : updated;
-            dispatch({ type: "SET_COLUMN_PINNING", payload: next });
-            onColumnPinningChangeRef.current?.(next);
-        },
-        [onColumnPinningChangeRef, uiRef]
-    );
-
-    const handleColumnVisibilityChange = useCallback(
-        (updated: any) => {
-            const prev = uiRef.current.columnVisibility;
-            const next = typeof updated === "function" ? updated(prev) : updated;
-            dispatch({ type: "SET_COLUMN_VISIBILITY", payload: next });
-            onColumnVisibilityChangeRef.current?.(next);
-        },
-        [onColumnVisibilityChangeRef, uiRef]
-    );
-
-    const handleColumnSizingChange = useCallback(
-        (updated: any) => {
-            const prev = uiRef.current.columnSizing;
-            const next = typeof updated === "function" ? updated(prev) : updated;
-            dispatch({ type: "SET_COLUMN_SIZING", payload: next });
-            onColumnSizingChangeRef.current?.(next);
-        },
-        [onColumnSizingChangeRef, uiRef]
-    );
-
-    const handleColumnReorder = useCallback(
-        (draggedId: string, targetId: string) => {
-            const currentOrder =
-                uiRef.current.columnOrder.length > 0
-                    ? uiRef.current.columnOrder
-                    : enhancedColumns.map((c: any, idx: number) => c.id ?? c.accessorKey ?? `column_${idx}`);
-
-            const from = currentOrder.indexOf(draggedId);
-            const to = currentOrder.indexOf(targetId);
-            if (from === -1 || to === -1) return;
-
-            const next = [...currentOrder];
-            next.splice(from, 1);
-            next.splice(to, 0, draggedId);
-
-            handleColumnOrderChange(next);
-        },
-        [enhancedColumns, handleColumnOrderChange, uiRef]
-    );
-
-    // optional: selection callback
-    useEffect(() => {
-        onSelectionChangeRef.current?.(ui.selectionState);
-    }, [onSelectionChangeRef, ui.selectionState]);
-
-
-
-    // --- provider props
-    const providerProps = useMemo(
-        () => ({
-            table,
-            apiRef,
-            dataMode,
-            tableSize: ui.tableSize,
-            onTableSizeChange: (size: DataTableSize) => dispatch({ type: "SET_TABLE_SIZE", payload: size }),
-            columnFilter: ui.columnFilter,
-            onChangeColumnFilter: (f: ColumnFilterState) => handleColumnFilterChangeHandler(f, false),
-            slots,
-            slotProps,
-            isExporting,
-            exportController,
-            exportPhase,
-            exportProgress,
-            onCancelExport: handleCancelExport,
-            exportFilename,
-            onExportProgress,
-            onExportComplete,
-            onExportError,
-            onServerExport,
-        }),
-        [
-            table,
-            dataMode,
-            ui.tableSize,
-            ui.columnFilter,
-            slots,
-            slotProps,
-            isExporting,
-            exportController,
-            exportPhase,
-            exportProgress,
-            handleCancelExport,
-            exportFilename,
-            onExportProgress,
-            onExportComplete,
-            onExportError,
-            onServerExport,
-            handleColumnFilterChangeHandler,
-        ]
-    );
-
-
-    return {
-        table,
-        refs: {
-            tableContainerRef,
-            apiRef,
-            exportControllerRef,
-        },
-        derived: {
-            isServerMode,
-            isServerPagination,
-            isServerFiltering,
-            isServerSorting,
-            tableData,
-            tableTotalRow,
-            tableLoading,
-            rows,
-            visibleLeafColumns: table.getVisibleLeafColumns,
-            useFixedLayout,
-            tableStyle,
-            isExporting,
-            exportPhase,
-            exportProgress,
-            isSomeRowsSelected,
-            selectedRowCount,
-        },
-        state: ui,
-        actions: {
-            fetchData,
-            handleSortingChange,
-            handlePaginationChange,
-            handleGlobalFilterChange,
-            handleColumnFilterChangeHandler,
-            handleColumnOrderChange,
-            handleColumnPinningChange,
-            handleColumnVisibilityChange,
-            handleColumnSizingChange,
-            handleColumnReorder,
-            resetAllAndReload,
-            triggerRefresh,
-            setTableSize: (size: DataTableSize) => dispatch({ type: "SET_TABLE_SIZE", payload: size }),
-            handleCancelExport,
-            renderRowModel: { rowVirtualizer },
-        },
-        api: apiRef.current!,
-        providerProps,
-    };
-}