@ackplus/react-tanstack-data-table 1.1.11 → 1.1.13

package/src/lib/data-table.tsx

@@ -41,9 +41,16 @@ import { TableHeader } from './components/headers';
 import { DataTablePagination } from './components/pagination';
 import { DataTableRow, LoadingRows, EmptyDataRow } from './components/rows';
 import { DataTableToolbar, BulkActionsToolbar } from './components/toolbar';
-import { DataTableProps } from './types/data-table.types';
-import { ColumnFilterState, TableFiltersForFetch, TableState } from './types';
-import { DataTableApi } from './types/data-table-api';
+import {
+    DataFetchMeta,
+    DataMutationAction,
+    DataMutationContext,
+    DataRefreshContext,
+    DataRefreshOptions,
+    DataTableProps,
+} from './types/data-table.types';
+import { ColumnFilterState, ExportPhase, ExportProgressPayload, ExportStateChange, TableFiltersForFetch, TableState } from './types';
+import { DataTableApi, DataTableExportApiOptions } from './types/data-table-api';
 import {
     createExpandingColumn,
     createSelectionColumn,
@@ -92,6 +99,8 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
     dataMode = 'client',
     initialLoadData = true,
     onFetchData,
+    onRefreshData,
+    onDataChange,
     onDataStateChange,
 
     // Selection props
@@ -145,11 +154,16 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
     sortingMode = 'client',
     onSortingChange,
     exportFilename = 'export',
+    exportConcurrency = 'cancelAndRestart',
+    exportChunkSize = 1000,
+    exportStrictTotalCheck = false,
+    exportSanitizeCSV = true,
     onExportProgress,
     onExportComplete,
     onExportError,
     onServerExport,
     onExportCancel,
+    onExportStateChange,
 
     // Styling props
     enableHover = true,
@@ -170,6 +184,7 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
     enableTableSizeControl = true,
     enableExport = false,
     enableReset = true,
+    enableRefresh = false,
 
     // Loading and empty states
     loading = false,
@@ -251,16 +266,32 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
     const [serverData, setServerData] = useState<T[] | null>(null);
     const [serverTotal, setServerTotal] = useState(0);
     const [exportController, setExportController] = useState<AbortController | null>(null);
+    const [exportProgress, setExportProgress] = useState<ExportProgressPayload>({});
+    const [exportPhase, setExportPhase] = useState<ExportPhase | null>(null);
+    const [queuedExportCount, setQueuedExportCount] = useState(0);
 
     // -------------------------------
     // Ref hooks (grouped together)
     // -------------------------------
     const tableContainerRef = useRef<HTMLDivElement>(null);
     const internalApiRef = useRef<DataTableApi<T>>(null);
+    const exportControllerRef = useRef<AbortController | null>(null);
+    const exportQueueRef = useRef<Promise<void>>(Promise.resolve());
+
+    const isExternallyControlledData = useMemo(
+        () => !onFetchData && (!!onDataChange || !!onRefreshData),
+        [onFetchData, onDataChange, onRefreshData]
+    );
 
     const { debouncedFetch, isLoading: fetchLoading } = useDebouncedFetch(onFetchData);
-    const tableData = useMemo(() => serverData ? serverData : data, [serverData, data]);
-    const tableTotalRow = useMemo(() => serverData ? serverTotal : totalRow || data.length, [serverData, serverTotal, totalRow, data]);
+    const tableData = useMemo(() => {
+        if (isExternallyControlledData) return data;
+        return serverData !== null ? serverData : data;
+    }, [isExternallyControlledData, serverData, data]);
+    const tableTotalRow = useMemo(
+        () => (isExternallyControlledData ? (totalRow || data.length) : (serverData !== null ? serverTotal : totalRow || data.length)),
+        [isExternallyControlledData, serverData, serverTotal, totalRow, data]
+    );
     const tableLoading = useMemo(() => onFetchData ? (loading || fetchLoading) : loading, [onFetchData, loading, fetchLoading]);
 
 
@@ -308,7 +339,10 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
     // -------------------------------
     // Callback hooks (grouped together)
     // -------------------------------
-    const fetchData = useCallback(async (overrides: Partial<TableState> = {}, options?: { delay?: number }) => {
+    const fetchData = useCallback(async (
+        overrides: Partial<TableState> = {},
+        options?: { delay?: number; meta?: DataFetchMeta }
+    ) => {
         if (!onFetchData) {
             if (logger.isLevelEnabled('debug')) {
                 logger.debug('onFetchData not provided, skipping fetch', { overrides, columnFilter, sorting, pagination });
@@ -316,7 +350,7 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
             return;
         }
 
-        const filters: TableFiltersForFetch = {
+        const filters: Partial<TableFiltersForFetch> = {
             globalFilter,
             pagination,
             columnFilter,
@@ -325,11 +359,19 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         };
 
         if (logger.isLevelEnabled('info')) {
-            logger.info('Requesting data', { filters });
+            logger.info('Requesting data', {
+                filters,
+                reason: options?.meta?.reason,
+                force: options?.meta?.force,
+            });
         }
 
         try {
-            const result = await debouncedFetch(filters, options === undefined ? 0 : options.delay || 300);
+            const delay = options?.delay ?? 300; // respects 0
+            const result = await debouncedFetch(filters, {
+                debounceDelay: delay,
+                meta: options?.meta,
+            });
 
             if (logger.isLevelEnabled('info')) {
                 logger.info('Fetch resolved', {
@@ -338,7 +380,7 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
                 });
             }
 
-            if (result?.data && result?.total !== undefined) {
+            if (result && Array.isArray(result.data) && result.total !== undefined) {
                 setServerData(result.data);
                 setServerTotal(result.total);
             } else if (logger.isLevelEnabled('warn')) {
@@ -360,76 +402,42 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         logger,
     ]);
 
-
-    const tableStateChange = useCallback((overrides: Partial<TableState> = {}) => {
-        if (!onDataStateChange) {
-            if (logger.isLevelEnabled('debug')) {
-                logger.debug('No onDataStateChange handler registered; skipping state update notification', { overrides });
-            }
-            return;
+    const normalizeRefreshOptions = useCallback((
+        options?: boolean | DataRefreshOptions,
+        fallbackReason: string = 'refresh'
+    ) => {
+        if (typeof options === 'boolean') {
+            return {
+                resetPagination: options,
+                force: false,
+                reason: fallbackReason,
+            };
         }
 
-        const currentState: Partial<TableState> = {
-            globalFilter,
-            columnFilter,
-            sorting,
-            pagination,
-            columnOrder,
-            columnPinning,
-            columnVisibility,
-            columnSizing,
-            ...overrides,
+        return {
+            resetPagination: options?.resetPagination ?? false,
+            force: options?.force ?? false,
+            reason: options?.reason ?? fallbackReason,
         };
-
-        if (logger.isLevelEnabled('debug')) {
-            logger.debug('Emitting tableStateChange', currentState);
-        }
-
-        onDataStateChange?.(currentState);
-    }, [
-        onDataStateChange,
-        globalFilter,
-        columnFilter,
-        sorting,
-        pagination,
-        columnOrder,
-        columnPinning,
-        columnVisibility,
-        columnSizing,
-        logger,
-    ]);
+    }, []);
 
 
     const handleSelectionStateChange = useCallback((updaterOrValue) => {
         setSelectionState((prevState) => {
-            const newSelectionState = typeof updaterOrValue === 'function'
-                ? updaterOrValue(prevState)
-                : updaterOrValue;
-            setTimeout(() => {
-                if (onSelectionChange) {
-                    onSelectionChange(newSelectionState);
-                }
-                if (onDataStateChange) {
-                    tableStateChange({ selectionState: newSelectionState });
-                }
-            }, 0);
-            return newSelectionState;
+            const next =
+                typeof updaterOrValue === 'function' ? updaterOrValue(prevState) : updaterOrValue;
+            onSelectionChange?.(next);
+            return next;
         });
-    }, [onSelectionChange, onDataStateChange, tableStateChange]);
+    }, [onSelectionChange]);
 
     const handleColumnFilterStateChange = useCallback((filterState: ColumnFilterState) => {
         if (!filterState || typeof filterState !== 'object') return;
 
         setColumnFilter(filterState);
-
-        if (onColumnFiltersChange) {
-            setTimeout(() => onColumnFiltersChange(filterState), 0);
-        }
-
-        if (onDataStateChange) {
-            setTimeout(() => tableStateChange({ columnFilter: filterState }), 0);
-        }
-    }, [onColumnFiltersChange, onDataStateChange, tableStateChange]);
+        onColumnFiltersChange?.(filterState);
+        return filterState;
+    }, [onColumnFiltersChange]);
 
 
     const resetPageToFirst = useCallback(() => {
@@ -445,43 +453,20 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         return newPagination;
     }, [pagination, logger, onPaginationChange]);
 
-    
-    const handleSortingChange = useCallback((updaterOrValue: any) => {
-        let newSorting = typeof updaterOrValue === 'function'
-            ? updaterOrValue(sorting)
-            : updaterOrValue;
-        newSorting = newSorting.filter((sort: any) => sort.id);
-        setSorting(newSorting);
-        onSortingChange?.(newSorting);
 
-        if (logger.isLevelEnabled('debug')) {
-            logger.debug('Sorting change applied', {
-                sorting: newSorting,
-                serverMode: isServerMode,
-                serverSorting: isServerSorting,
-            });
-        }
+    const handleSortingChange = useCallback((updaterOrValue: any) => {
 
-        if (isServerMode || isServerSorting) {
-            const pagination = resetPageToFirst();
-            if (logger.isLevelEnabled('debug')) {
-                logger.debug('Sorting change triggered server fetch', { pagination, sorting: newSorting });
+        setSorting((prev) => {
+            const next = typeof updaterOrValue === 'function' ? updaterOrValue(prev) : updaterOrValue;
+            const cleaned = next.filter((s: any) => s?.id);
+            onSortingChange?.(cleaned);
+            const nextPagination = resetPageToFirst();
+            if (isServerMode || isServerSorting) {
+                fetchData({ sorting: cleaned, pagination: nextPagination }, { delay: 0 });
             }
-            tableStateChange({ sorting: newSorting, pagination });
-            fetchData({
-                sorting: newSorting,
-                pagination,
-            });
-        } else if (onDataStateChange) {
-            const pagination = resetPageToFirst();
-            setTimeout(() => {
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Sorting change notified client state change', { pagination, sorting: newSorting });
-                }
-                tableStateChange({ sorting: newSorting, pagination });
-            }, 0);
-        }
-    }, [sorting, onSortingChange, logger, isServerMode, isServerSorting, onDataStateChange, resetPageToFirst, tableStateChange, fetchData]);
+            return cleaned;
+        });
+    }, [onSortingChange, isServerMode, isServerSorting, resetPageToFirst, fetchData]);
 
     const handleColumnOrderChange = useCallback((updatedColumnOrder: Updater<ColumnOrderState>) => {
         const newColumnOrder = typeof updatedColumnOrder === 'function'
@@ -493,144 +478,64 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         }
     }, [onColumnDragEnd, columnOrder]);
 
-    const handleColumnPinningChange = useCallback((updatedColumnPinning: Updater<ColumnPinningState>) => {
-        const newColumnPinning = typeof updatedColumnPinning === 'function'
-            ? updatedColumnPinning(columnPinning)
-            : updatedColumnPinning;
-        setColumnPinning(newColumnPinning);
-        if (onColumnPinningChange) {
-            onColumnPinningChange(newColumnPinning);
-        }
-    }, [onColumnPinningChange, columnPinning]);
+    const handleColumnPinningChange = useCallback(
+        (updater: Updater<ColumnPinningState>) => {
+            setColumnPinning((prev) => {
+                const next = typeof updater === "function" ? updater(prev) : updater;
+                // keep direct callback here (optional)
+                onColumnPinningChange?.(next);
+                return next;
+            });
+        },
+        [onColumnPinningChange]
+    );
 
     // Column visibility change handler - same pattern as column order
     const handleColumnVisibilityChange = useCallback((updater: any) => {
-        const newVisibility = typeof updater === 'function'
-            ? updater(columnVisibility)
-            : updater;
-        setColumnVisibility(newVisibility);
-
-        if (onColumnVisibilityChange) {
-            setTimeout(() => {
-                onColumnVisibilityChange(newVisibility);
-            }, 0);
-        }
-
-        if (onDataStateChange) {
-            setTimeout(() => {
-                tableStateChange({ columnVisibility: newVisibility });
-            }, 0);
-        }
-    }, [onColumnVisibilityChange, onDataStateChange, tableStateChange, columnVisibility]);
+        setColumnVisibility((prev) => {
+            const next = typeof updater === 'function' ? updater(prev) : updater;
+            onColumnVisibilityChange?.(next);
+            return next;
+        });
+    }, [onColumnVisibilityChange]);
 
     // Column sizing change handler - same pattern as column order
     const handleColumnSizingChange = useCallback((updater: any) => {
-        const newSizing = typeof updater === 'function'
-            ? updater(columnSizing)
-            : updater;
-        setColumnSizing(newSizing);
-
-        if (onColumnSizingChange) {
-            setTimeout(() => {
-                onColumnSizingChange(newSizing);
-            }, 0);
-        }
-
-        if (onDataStateChange) {
-            setTimeout(() => {
-                tableStateChange({ columnSizing: newSizing });
-            }, 0);
-        }
-    }, [onColumnSizingChange, onDataStateChange, tableStateChange, columnSizing]);
+        setColumnSizing((prev) => {
+            const next = typeof updater === 'function' ? updater(prev) : updater;
+            onColumnSizingChange?.(next);
+            return next;
+        });
+    }, [onColumnSizingChange]);
 
     const handlePaginationChange = useCallback((updater: any) => {
-        const newPagination = typeof updater === 'function' ? updater(pagination) : updater;
-        if (logger.isLevelEnabled('debug')) {
-            logger.debug('Pagination change requested', {
-                previous: pagination,
-                next: newPagination,
-                serverSide: isServerMode || isServerPagination,
-            });
-        }
-
-        // Update pagination state
-        setPagination(newPagination);
-        onPaginationChange?.(newPagination);
-
-        if (logger.isLevelEnabled('debug')) {
-            logger.debug('Pagination state updated', newPagination);
-        }
-
-        // Notify state change and fetch data if needed
-        if (isServerMode || isServerPagination) {
-            setTimeout(() => {
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Notifying server-side pagination change', newPagination);
-                }
-                tableStateChange({ pagination: newPagination });
-                fetchData({ pagination: newPagination });
-            }, 0);
-        } else if (onDataStateChange) {
-            setTimeout(() => {
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Notifying client-side pagination change', newPagination);
-                }
-                tableStateChange({ pagination: newPagination });
-            }, 0);
-        }
-    }, [
-        pagination,
-        isServerMode,
-        isServerPagination,
-        onDataStateChange,
-        fetchData,
-        tableStateChange,
-        logger,
-        onPaginationChange,
-    ]);
+        setPagination((prev) => {
+            const next = typeof updater === 'function' ? updater(prev) : updater;
+            onPaginationChange?.(next);
+            if (isServerMode || isServerPagination) {
+                fetchData({ pagination: next }, { delay: 0 });
+            }
+            return next;
+        });
+    }, [isServerMode, isServerPagination, fetchData, onPaginationChange]);
 
 
 
     const handleGlobalFilterChange = useCallback((updaterOrValue: any) => {
-        const newFilter = typeof updaterOrValue === 'function'
-            ? updaterOrValue(globalFilter)
-            : updaterOrValue;
-        setGlobalFilter(newFilter);
+        setGlobalFilter((prev) => {
+            const next = typeof updaterOrValue === 'function' ? updaterOrValue(prev) : updaterOrValue;
 
-        if (logger.isLevelEnabled('debug')) {
-            logger.debug('Global filter change applied', {
-                value: newFilter,
-                serverMode: isServerMode,
-                serverFiltering: isServerFiltering,
-            });
-        }
+            onGlobalFilterChange?.(next);
 
-        if (isServerMode || isServerFiltering) {
-            const pagination = resetPageToFirst();
-            setTimeout(() => {
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Global filter change triggering server fetch', {
-                        pagination,
-                        value: newFilter,
-                    });
-                }
-                tableStateChange({ globalFilter: newFilter, pagination });
-                fetchData({ globalFilter: newFilter, pagination });
-            }, 0);
-        } else if (onDataStateChange) {
-            const pagination = resetPageToFirst();
-            setTimeout(() => {
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Global filter change notifying client listeners', {
-                        pagination,
-                        value: newFilter,
-                    });
-                }
-                tableStateChange({ globalFilter: newFilter, pagination });
-            }, 0);
-        }
-        onGlobalFilterChange?.(newFilter);
-    }, [globalFilter, logger, isServerMode, isServerFiltering, onDataStateChange, onGlobalFilterChange, resetPageToFirst, tableStateChange, fetchData]);
+            if (isServerMode || isServerFiltering) {
+                const nextPagination = { pageIndex: 0, pageSize: pagination.pageSize };
+                setPagination(nextPagination);
+                fetchData({ globalFilter: next, pagination: nextPagination }, { delay: 0 });
+            }
+
+            return next;
+        });
+    }, [isServerMode, isServerFiltering, onGlobalFilterChange, fetchData, pagination.pageSize]);
 
     const onColumnFilterChangeHandler = useCallback((updater: any) => {
         const currentState = columnFilter;
@@ -648,24 +553,15 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
 
     const onColumnFilterApplyHandler = useCallback((appliedState: ColumnFilterState) => {
         const pagination = resetPageToFirst();
-
         if (isServerFiltering) {
-            tableStateChange({
-                columnFilter: appliedState,
-                pagination,
-            });
             fetchData({
                 columnFilter: appliedState,
                 pagination,
             });
-        } else if (onDataStateChange) {
-            setTimeout(() => tableStateChange({ columnFilter: appliedState, pagination }), 0);
         }
 
-        setTimeout(() => {
-            onColumnFiltersChange?.(appliedState);
-        }, 0);
-    }, [resetPageToFirst, isServerFiltering, onDataStateChange, tableStateChange, fetchData, onColumnFiltersChange]);
+        onColumnFiltersChange?.(appliedState);
+    }, [resetPageToFirst, isServerFiltering, fetchData, onColumnFiltersChange]);
 
     // -------------------------------
     // Table creation (after callbacks/memo)
@@ -795,12 +691,21 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
     // -------------------------------
     // Effects (after callbacks)
     // -------------------------------
+    useEffect(() => {
+        if (!isExternallyControlledData || serverData === null) return;
+        setServerData(null);
+        setServerTotal(0);
+    }, [isExternallyControlledData, serverData]);
+
     useEffect(() => {
         if (initialLoadData && onFetchData) {
             if (logger.isLevelEnabled('info')) {
                 logger.info('Initial data load triggered', { initialLoadData });
             }
-            fetchData({});
+            fetchData({}, {
+                delay: 0,
+                meta: { reason: 'initial' },
+            });
         } else if (logger.isLevelEnabled('debug')) {
             logger.debug('Skipping initial data load', {
                 initialLoadData,
@@ -825,501 +730,852 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
     }, [enableColumnDragging, enhancedColumns, columnOrder.length]);
 
 
-    const dataTableApi = useMemo(() => ({
-        table: {
-            getTable: () => table,
-        },
-        // Column Management
-        columnVisibility: {
-            showColumn: (columnId: string) => {
-                table.getColumn(columnId)?.toggleVisibility(true);
-            },
-            hideColumn: (columnId: string) => {
-                table.getColumn(columnId)?.toggleVisibility(false);
-            },
-            toggleColumn: (columnId: string) => {
-                table.getColumn(columnId)?.toggleVisibility();
-            },
-            showAllColumns: () => {
-                table.toggleAllColumnsVisible(true);
-            },
-            hideAllColumns: () => {
-                table.toggleAllColumnsVisible(false);
-            },
-            resetColumnVisibility: () => {
-                const initialVisibility = initialStateConfig.columnVisibility || {};
-                table.setColumnVisibility(initialVisibility);
-                // Manually trigger handler to ensure callbacks are called
-                handleColumnVisibilityChange(initialVisibility);
-            },
-        },
+    const lastSentRef = useRef<string>("");
 
-        // Column Ordering
-        columnOrdering: {
-            setColumnOrder: (columnOrder: ColumnOrderState) => {
-                table.setColumnOrder(columnOrder);
-            },
-            moveColumn: (columnId: string, toIndex: number) => {
-                const currentOrder = table.getState().columnOrder || [];
-                const currentIndex = currentOrder.indexOf(columnId);
-                if (currentIndex === -1) return;
+    const emitTableState = useCallback(() => {
+        if (!onDataStateChange) return;
 
-                const newOrder = [...currentOrder];
-                newOrder.splice(currentIndex, 1);
-                newOrder.splice(toIndex, 0, columnId);
+        const live = table.getState();
+        const liveColumnFilter = live.columnFilter;
 
-                table.setColumnOrder(newOrder);
-            },
-            resetColumnOrder: () => {
-                const initialOrder = enhancedColumns.map((col, index) => {
-                    if (col.id) return col.id;
-                    const anyCol = col as any;
-                    if (anyCol.accessorKey && typeof anyCol.accessorKey === 'string') {
-                        return anyCol.accessorKey;
-                    }
-                    return `column_${index}`;
-                });
-                table.setColumnOrder(initialOrder);
-                // Manually trigger handler to ensure callbacks are called
-                handleColumnOrderChange(initialOrder);
-            },
-        },
+        // only keep what you persist/store
+        const payload = {
+            sorting: live.sorting,
+            pagination: live.pagination,
+            globalFilter: live.globalFilter,
+            columnFilter: liveColumnFilter,
+            columnVisibility: live.columnVisibility,
+            columnSizing: live.columnSizing,
+            columnOrder: live.columnOrder,
+            columnPinning: live.columnPinning,
+        };
 
-        // Column Pinning
-        columnPinning: {
-            pinColumnLeft: (columnId: string) => {
-                const currentPinning = table.getState().columnPinning;
-                const newPinning = { ...currentPinning };
+        const key = JSON.stringify(payload);
+        if (key === lastSentRef.current) return;
 
-                // Remove from right if exists
-                newPinning.right = (newPinning.right || []).filter(id => id !== columnId);
-                // Add to left if not exists
-                newPinning.left = [...(newPinning.left || []).filter(id => id !== columnId), columnId];
+        lastSentRef.current = key;
+        onDataStateChange(payload);
+    }, [onDataStateChange, table]);
 
-                table.setColumnPinning(newPinning);
-            },
-            pinColumnRight: (columnId: string) => {
-                const currentPinning = table.getState().columnPinning;
-                const newPinning = { ...currentPinning };
+    useEffect(() => {
+        emitTableState();
+    }, [
+        emitTableState,
+        sorting,
+        pagination,
+        globalFilter,
+        columnFilter,
+        columnVisibility,
+        columnSizing,
+        columnOrder,
+        columnPinning,
+    ]);
 
-                // Remove from left if exists
-                newPinning.left = (newPinning.left || []).filter(id => id !== columnId);
-                // Add to right if not exists - prepend to beginning (appears rightmost to leftmost)
-                // First column pinned appears rightmost, second appears to its left, etc.
-                newPinning.right = [columnId, ...(newPinning.right || []).filter(id => id !== columnId)];
 
-                table.setColumnPinning(newPinning);
-            },
-            unpinColumn: (columnId: string) => {
-                const currentPinning = table.getState().columnPinning;
-                const newPinning = {
-                    left: (currentPinning.left || []).filter(id => id !== columnId),
-                    right: (currentPinning.right || []).filter(id => id !== columnId),
-                };
+    const getResetState = useCallback((): Partial<TableState> => {
+        const resetSorting = initialStateConfig.sorting || [];
+        const resetGlobalFilter = initialStateConfig.globalFilter ?? '';
+        const resetColumnFilter = initialStateConfig.columnFilter;
 
-                table.setColumnPinning(newPinning);
-            },
-            setPinning: (pinning: ColumnPinningState) => {
-                table.setColumnPinning(pinning);
-            },
-            resetColumnPinning: () => {
-                const initialPinning = initialStateConfig.columnPinning || { left: [], right: [] };
-                table.setColumnPinning(initialPinning);
-                // Manually trigger handler to ensure callbacks are called
-                handleColumnPinningChange(initialPinning);
-            },
-        },
+        const resetPagination = enablePagination
+            ? (initialStateConfig.pagination || { pageIndex: 0, pageSize: 10 })
+            : undefined;
 
-        // Column Resizing
-        columnResizing: {
-            resizeColumn: (columnId: string, width: number) => {
-                // Use table's setColumnSizing method
-                const currentSizing = table.getState().columnSizing;
-                table.setColumnSizing({
-                    ...currentSizing,
-                    [columnId]: width,
-                });
-            },
-            autoSizeColumn: (columnId: string) => {
-                // TanStack doesn't have built-in auto-size, so reset to default
-                table.getColumn(columnId)?.resetSize();
-            },
-            autoSizeAllColumns: () => {
-                const initialSizing = initialStateConfig.columnSizing || {};
-                table.setColumnSizing(initialSizing);
-                // Manually trigger handler to ensure callbacks are called
-                handleColumnSizingChange(initialSizing);
-            },
-            resetColumnSizing: () => {
-                const initialSizing = initialStateConfig.columnSizing || {};
-                table.setColumnSizing(initialSizing);
-                // Manually trigger handler to ensure callbacks are called
-                handleColumnSizingChange(initialSizing);
-            },
-        },
+        return {
+            sorting: resetSorting,
+            globalFilter: resetGlobalFilter,
+            columnFilter: resetColumnFilter,
+            ...(resetPagination ? { pagination: resetPagination } : {}),
+        };
+    }, [initialStateConfig, enablePagination]);
 
-        // Filtering
-        filtering: {
-            setGlobalFilter: (filter: string) => {
-                table.setGlobalFilter(filter);
-            },
-            clearGlobalFilter: () => {
-                table.setGlobalFilter('');
-            },
-            setColumnFilters: (filters: ColumnFilterState) => {
-                handleColumnFilterStateChange(filters);
-            },
-            addColumnFilter: (columnId: string, operator: string, value: any) => {
-                const newFilter = {
-                    id: `filter_${Date.now()}`,
-                    columnId,
-                    operator,
-                    value,
-                };
-                const columnFilter = table.getState().columnFilter;
-
-                const currentFilters = columnFilter.filters || [];
-                const newFilters = [...currentFilters, newFilter];
-                handleColumnFilterStateChange({
-                    filters: newFilters,
-                    logic: columnFilter.logic,
-                    pendingFilters: columnFilter.pendingFilters || [],
-                    pendingLogic: columnFilter.pendingLogic || 'AND',
-                });
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Adding column filter ${columnId} ${operator} ${value}`, newFilters);
-                }
-            },
-            removeColumnFilter: (filterId: string) => {
-                const columnFilter = table.getState().columnFilter;
-                const currentFilters = columnFilter.filters || [];
-                const newFilters = currentFilters.filter((f: any) => f.id !== filterId);
-                handleColumnFilterStateChange({
-                    filters: newFilters,
-                    logic: columnFilter.logic,
-                    pendingFilters: columnFilter.pendingFilters || [],
-                    pendingLogic: columnFilter.pendingLogic || 'AND',
-                });
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Removing column filter ${filterId}`, newFilters);
-                }
-            },
-            clearAllFilters: () => {
-                table.setGlobalFilter('');
-                handleColumnFilterStateChange({
-                    filters: [],
-                    logic: 'AND',
-                    pendingFilters: [],
-                    pendingLogic: 'AND',
-                });
-            },
-            resetFilters: () => {
-                handleColumnFilterStateChange({
-                    filters: [],
-                    logic: 'AND',
-                    pendingFilters: [],
-                    pendingLogic: 'AND',
-                });
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Resetting filters');
-                }
-            },
-        },
+    const applyDataMutation = useCallback((
+        action: DataMutationAction,
+        updater: (rows: T[]) => T[],
+        details: Partial<Omit<DataMutationContext<T>, 'action' | 'previousData' | 'nextData'>> = {}
+    ) => {
+        const previousData = [...tableData];
+        const nextData = updater(previousData);
 
-        // Sorting
-        sorting: {
-            setSorting: (sortingState: SortingState) => {
-                table.setSorting(sortingState);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Setting sorting`, sortingState);
-                }
-            },
-            sortColumn: (columnId: string, direction: 'asc' | 'desc' | false) => {
-                const column = table.getColumn(columnId);
-                if (!column) return;
-
-                if (direction === false) {
-                    column.clearSorting();
-                } else {
-                    column.toggleSorting(direction === 'desc');
-                }
-            },
-            clearSorting: () => {
-                table.setSorting([]);
-                // Manually trigger handler to ensure callbacks are called
-                handleSortingChange([]);
-            },
-            resetSorting: () => {
-                const initialSorting = initialStateConfig.sorting || [];
-                table.setSorting(initialSorting);
-                // Manually trigger handler to ensure callbacks are called
-                handleSortingChange(initialSorting);
-            },
-        },
+        if (nextData === previousData) return nextData;
 
-        // Pagination
-        pagination: {
-            goToPage: (pageIndex: number) => {
-                table.setPageIndex(pageIndex);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Going to page ${pageIndex}`);
-                }
-            },
-            nextPage: () => {
-                table.nextPage();
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Next page');
-                }
-            },
-            previousPage: () => {
-                table.previousPage();
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Previous page');
+        const nextTotal = Math.max(0, tableTotalRow + (nextData.length - previousData.length));
+
+        if (!isExternallyControlledData) {
+            setServerData(nextData);
+            setServerTotal(nextTotal);
+        }
+        onDataChange?.(nextData, {
+            action,
+            previousData,
+            nextData,
+            totalRow: nextTotal,
+            ...details,
+        });
+
+        if (logger.isLevelEnabled('debug')) {
+            logger.debug('Applied data mutation', {
+                action,
+                previousCount: previousData.length,
+                nextCount: nextData.length,
+                totalRow: nextTotal,
+            });
+        }
+
+        return nextData;
+    }, [isExternallyControlledData, logger, onDataChange, tableData, tableTotalRow]);
+
+    const buildRefreshContext = useCallback((
+        options: ReturnType<typeof normalizeRefreshOptions>,
+        paginationOverride?: { pageIndex: number; pageSize: number }
+    ): DataRefreshContext => {
+        const state = table.getState();
+        const nextPagination = paginationOverride || state.pagination || pagination;
+
+        return {
+            filters: {
+                globalFilter,
+                pagination: nextPagination,
+                columnFilter,
+                sorting,
+            },
+            state: {
+                sorting,
+                pagination: nextPagination,
+                globalFilter,
+                columnFilter,
+                columnVisibility: state.columnVisibility,
+                columnSizing: state.columnSizing,
+                columnOrder: state.columnOrder,
+                columnPinning: state.columnPinning,
+            },
+            options,
+        };
+    }, [table, pagination, globalFilter, columnFilter, sorting]);
+
+    const triggerRefresh = useCallback(async (
+        options?: boolean | DataRefreshOptions,
+        fallbackReason: string = 'refresh'
+    ) => {
+        const normalizedOptions = normalizeRefreshOptions(options, fallbackReason);
+        const nextPagination = enablePagination
+            ? {
+                pageIndex: normalizedOptions.resetPagination ? 0 : pagination.pageIndex,
+                pageSize: pagination.pageSize,
+            }
+            : undefined;
+
+        const shouldUpdatePagination = !!nextPagination
+            && (nextPagination.pageIndex !== pagination.pageIndex || nextPagination.pageSize !== pagination.pageSize);
+
+        if (nextPagination && shouldUpdatePagination) {
+            setPagination(nextPagination);
+            onPaginationChange?.(nextPagination);
+        }
+
+        const refreshContext = buildRefreshContext(normalizedOptions, nextPagination);
+
+        if (onRefreshData) {
+            await onRefreshData(refreshContext);
+            return;
+        }
+
+        if (onFetchData) {
+            await fetchData(
+                nextPagination ? { pagination: nextPagination } : {},
+                {
+                    delay: 0,
+                    meta: {
+                        reason: normalizedOptions.reason,
+                        force: normalizedOptions.force,
+                    },
                 }
-            },
-            setPageSize: (pageSize: number) => {
-                table.setPageSize(pageSize);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Setting page size to ${pageSize}`);
+            );
+            return;
+        }
+
+        if (logger.isLevelEnabled('debug')) {
+            logger.debug('Refresh skipped because no refresh handler is configured', refreshContext);
+        }
+    }, [
+        normalizeRefreshOptions,
+        enablePagination,
+        pagination,
+        onPaginationChange,
+        buildRefreshContext,
+        onRefreshData,
+        onFetchData,
+        fetchData,
+        logger,
+    ]);
+
+    const resetAllAndReload = useCallback(() => {
+        const resetState = getResetState();
+
+        setSorting(resetState.sorting || []);
+        setGlobalFilter(resetState.globalFilter ?? '');
+        setColumnFilter(resetState.columnFilter as any);
+
+        if (resetState.pagination) {
+            setPagination(resetState.pagination);
+            onPaginationChange?.(resetState.pagination);
+        }
+
+        setSelectionState(initialSelectionState);
+        setExpanded({});
+
+        // layout state
+        setColumnVisibility(initialStateConfig.columnVisibility || {});
+        setColumnSizing(initialStateConfig.columnSizing || {});
+        setColumnOrder(initialStateConfig.columnOrder || []);
+        setColumnPinning(initialStateConfig.columnPinning || { left: [], right: [] });
+
+        const resetOptions = normalizeRefreshOptions({
+            resetPagination: true,
+            force: true,
+            reason: 'reset',
+        }, 'reset');
+
+        const refreshContext = buildRefreshContext(resetOptions, resetState.pagination);
+
+        if (onRefreshData) {
+            void onRefreshData(refreshContext);
+            return;
+        }
+
+        if (onFetchData) {
+            void fetchData(resetState, {
+                delay: 0,
+                meta: {
+                    reason: resetOptions.reason,
+                    force: resetOptions.force,
+                },
+            });
+        }
+    }, [
+        getResetState,
+        initialSelectionState,
+        initialStateConfig,
+        onPaginationChange,
+        normalizeRefreshOptions,
+        buildRefreshContext,
+        onRefreshData,
+        onFetchData,
+        fetchData,
+    ]);
+
+    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((progress: ExportProgressPayload) => {
+        setExportProgress(progress || {});
+        onExportProgress?.(progress);
+    }, [onExportProgress]);
+
+    const handleExportStateChangeInternal = useCallback((state: ExportStateChange) => {
+        setExportPhase(state.phase);
+        if (
+            state.processedRows !== undefined
+            || state.totalRows !== undefined
+            || state.percentage !== undefined
+        ) {
+            setExportProgress({
+                processedRows: state.processedRows,
+                totalRows: state.totalRows,
+                percentage: state.percentage,
+            });
+        }
+        onExportStateChange?.(state);
+    }, [onExportStateChange]);
+
+    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((current) => (current === controller ? null : current));
                 }
-            },
-            goToFirstPage: () => {
-                table.setPageIndex(0);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Going to first page');
+            };
+
+            if (exportConcurrency === 'queue') {
+                setQueuedExportCount((prev) => prev + 1);
+                const runQueued = async (): Promise<void> => {
+                    setQueuedExportCount((prev) => Math.max(0, prev - 1));
+                    await startExecution();
+                };
+                const queuedPromise = exportQueueRef.current
+                    .catch(() => undefined)
+                    .then(runQueued);
+                exportQueueRef.current = queuedPromise;
+                return queuedPromise;
+            }
+
+            const activeController = exportControllerRef.current;
+            if (activeController) {
+                if (exportConcurrency === 'ignoreIfRunning') {
+                    handleExportStateChangeInternal({
+                        phase: 'error',
+                        mode,
+                        format,
+                        filename,
+                        message: 'An export is already running',
+                        code: 'EXPORT_IN_PROGRESS',
+                        endedAt: Date.now(),
+                    });
+                    onExportError?.({
+                        message: 'An export is already running',
+                        code: 'EXPORT_IN_PROGRESS',
+                    });
+                    return;
                 }
-            },
-            goToLastPage: () => {
-                const pageCount = table.getPageCount();
-                if (pageCount > 0) {
-                    table.setPageIndex(pageCount - 1);
-                    if (logger.isLevelEnabled('debug')) {
-                        logger.debug(`Going to last page ${pageCount - 1}`);
-                    }
+
+                if (exportConcurrency === 'cancelAndRestart') {
+                    activeController.abort();
                 }
-            },
-            resetPagination: () => {
-                const initialPagination = initialStateConfig.pagination || { pageIndex: 0, pageSize: 10 };
-                table.setPagination(initialPagination);
-                // Manually trigger handler to ensure callbacks are called
-                handlePaginationChange(initialPagination);
-            },
-        },
+            }
 
-        // Access via table methods: table.selectRow(), table.getIsRowSelected(), etc.
-        selection: {
-            selectRow: (rowId: string) => table.selectRow?.(rowId),
-            deselectRow: (rowId: string) => table.deselectRow?.(rowId),
-            toggleRowSelection: (rowId: string) => table.toggleRowSelected?.(rowId),
-            selectAll: () => table.selectAll?.(),
-            deselectAll: () => table.deselectAll?.(),
-            toggleSelectAll: () => table.toggleAllRowsSelected?.(),
-            getSelectionState: () => table.getSelectionState?.() || { ids: [], type: 'include' as const },
-            getSelectedRows: () => table.getSelectedRows(),
-            getSelectedCount: () => table.getSelectedCount(),
-            isRowSelected: (rowId) => table.getIsRowSelected(rowId) || false,
+            await startExecution();
         },
+        [
+            exportConcurrency,
+            handleExportStateChangeInternal,
+            onExportError,
+            setExportControllerSafely,
+        ]
+    );
 
-        // Data Management
-        data: {
-            refresh: (resetPagination = false) => {
-                const filters = table.getState();
-                const pagination = {
-                    pageIndex: resetPagination ? 0 : initialStateConfig.pagination?.pageIndex || 0,
-                    pageSize: filters.pagination?.pageSize || initialStateConfig.pagination?.pageSize || 10,
-                };
-                const allState = table.getState();
-                setPagination(pagination);
-                onDataStateChange?.({ ...allState, pagination });
-                fetchData?.({ pagination });
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Refreshing data using Ref', { pagination, allState });
-                }
-            },
-            reload: () => {
-                const allState = table.getState();
+    const dataTableApi = useMemo(() => {
+        // helpers (avoid repeating boilerplate)
+        const buildInitialOrder = () =>
+            enhancedColumns.map((col, index) => {
+                if ((col as any).id) return (col as any).id as string;
+                const anyCol = col as any;
+                if (anyCol.accessorKey && typeof anyCol.accessorKey === "string") return anyCol.accessorKey;
+                return `column_${index}`;
+            });
 
-                onDataStateChange?.(allState);
-                fetchData?.({});
-                if (logger.isLevelEnabled('debug')) {
-                    logger.info('Reloading data', allState);
-                }
-            },
-            // Data CRUD operations
-            getAllData: () => {
-                return table.getRowModel().rows?.map(row => row.original) || [];
-            },
-            getRowData: (rowId: string) => {
-                return table.getRowModel().rows?.find(row => String(row.original[idKey]) === rowId)?.original;
-            },
-            getRowByIndex: (index: number) => {
-                return table.getRowModel().rows?.[index]?.original;
-            },
-            updateRow: (rowId: string, updates: Partial<T>) => {
-                const newData = table.getRowModel().rows?.map(row => String(row.original[idKey]) === rowId
-                    ? {
-                        ...row.original,
-                        ...updates,
-                    }
-                    : row.original);
-                setServerData?.(newData || []);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Updating row ${rowId}`, updates);
-                }
-            },
-            updateRowByIndex: (index: number, updates: Partial<T>) => {
-                const newData = table.getRowModel().rows?.map(row => row.original);
-                if (newData?.[index]) {
-                    newData[index] = {
-                        ...newData[index]!,
-                        ...updates,
-                    };
-                    setServerData(newData);
-                    if (logger.isLevelEnabled('debug')) {
-                        logger.debug(`Updating row by index ${index}`, updates);
-                    }
-                }
-            },
-            insertRow: (newRow: T, index?: number) => {
-                const newData = table.getRowModel().rows?.map(row => row.original) || [];
-                if (index !== undefined) {
-                    newData.splice(index, 0, newRow);
-                } else {
-                    newData.push(newRow);
-                }
-                setServerData(newData || []);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Inserting row`, newRow);
-                }
-            },
-            deleteRow: (rowId: string) => {
-                const newData = (table.getRowModel().rows || [])?.filter(row => String(row.original[idKey]) !== rowId);
-                setServerData?.(newData?.map(row => row.original) || []);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Deleting row ${rowId}`);
-                }
-            },
-            deleteRowByIndex: (index: number) => {
-                const newData = (table.getRowModel().rows || [])?.map(row => row.original);
-                newData.splice(index, 1);
-                setServerData(newData);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Deleting row by index ${index}`);
-                }
-            },
-            deleteSelectedRows: () => {
-                const selectedRows = table.getSelectedRows?.() || [];
-                if (selectedRows.length === 0) return;
+        const applyColumnOrder = (next: ColumnOrderState) => {
+            // handleColumnOrderChange supports both Updater<ColumnOrderState> and array in your impl
+            handleColumnOrderChange(next as any);
+        };
 
-                const selectedIds = new Set(selectedRows.map(row => String(row.original[idKey])));
-                const newData = (table.getRowModel().rows || [])?.filter(row => !selectedIds.has(String(row.original[idKey])));
+        const applyPinning = (next: ColumnPinningState) => {
+            handleColumnPinningChange(next as any);
+        };
 
-                setServerData(newData?.map(row => row.original) || []);
-                table.deselectAll?.();
+        const applyVisibility = (next: Record<string, boolean>) => {
+            handleColumnVisibilityChange(next as any);
+        };
 
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Deleting selected rows');
-                }
-            },
-            replaceAllData: (newData: T[]) => {
-                setServerData?.(newData);
-            },
+        const applySizing = (next: Record<string, number>) => {
+            handleColumnSizingChange(next as any);
+        };
 
-            // Bulk operations
-            updateMultipleRows: (updates: Array<{ rowId: string; data: Partial<T> }>) => {
-                const updateMap = new Map(updates.map(u => [u.rowId, u.data]));
-                const newData = (table.getRowModel().rows || [])?.map(row => {
-                    const rowId = String(row.original[idKey]);
-                    const updateData = updateMap.get(rowId);
-                    return updateData ? {
-                        ...row.original,
-                        ...updateData,
-                    } : row.original;
-                });
-                setServerData(newData || []);
-            },
-            insertMultipleRows: (newRows: T[], startIndex?: number) => {
-                const newData = (table.getRowModel().rows || [])?.map(row => row.original);
-                if (startIndex !== undefined) {
-                    newData.splice(startIndex, 0, ...newRows);
-                } else {
-                    newData.push(...newRows);
-                }
-                setServerData?.(newData);
-            },
-            deleteMultipleRows: (rowIds: string[]) => {
-                const idsToDelete = new Set(rowIds);
-                const newData = (table.getRowModel().rows || [])?.filter(row => !idsToDelete.has(String(row.original[idKey])))?.map(row => row.original);
-                setServerData(newData);
-            },
+        const applyPagination = (next: any) => {
+            handlePaginationChange(next);
+        };
 
-            // Field-specific updates
-            updateField: (rowId: string, fieldName: keyof T, value: any) => {
-                const newData = (table.getRowModel().rows || [])?.map(row => String(row.original[idKey]) === rowId
-                    ? {
-                        ...row.original,
-                        [fieldName]: value,
-                    }
-                    : row.original);
-                setServerData?.(newData);
-            },
-            updateFieldByIndex: (index: number, fieldName: keyof T, value: any) => {
-                const newData = (table.getRowModel().rows || [])?.map(row => row.original);
-                if (newData[index]) {
-                    newData[index] = {
-                        ...newData[index],
-                        [fieldName]: value,
+        const applySorting = (next: any) => {
+            handleSortingChange(next);
+        };
+
+        const applyGlobalFilter = (next: any) => {
+            handleGlobalFilterChange(next);
+        };
+
+        const getRowIndexById = (rowsToSearch: T[], rowId: string) =>
+            rowsToSearch.findIndex((row, index) => String(generateRowId(row, index, idKey)) === rowId);
+
+        const clampInsertIndex = (rowsToMutate: T[], insertIndex?: number) => {
+            if (insertIndex === undefined) return rowsToMutate.length;
+            return Math.max(0, Math.min(insertIndex, rowsToMutate.length));
+        };
+
+        return {
+            table: {
+                getTable: () => table,
+            },
+
+            // -------------------------------
+            // Column Management
+            // -------------------------------
+            columnVisibility: {
+                showColumn: (columnId: string) => {
+                    applyVisibility({ ...table.getState().columnVisibility, [columnId]: true });
+                },
+                hideColumn: (columnId: string) => {
+                    applyVisibility({ ...table.getState().columnVisibility, [columnId]: false });
+                },
+                toggleColumn: (columnId: string) => {
+                    const curr = table.getState().columnVisibility?.[columnId] ?? true;
+                    applyVisibility({ ...table.getState().columnVisibility, [columnId]: !curr });
+                },
+                showAllColumns: () => {
+                    // set all known columns true
+                    const all: Record<string, boolean> = {};
+                    table.getAllLeafColumns().forEach((c) => (all[c.id] = true));
+                    applyVisibility(all);
+                },
+                hideAllColumns: () => {
+                    const all: Record<string, boolean> = {};
+                    table.getAllLeafColumns().forEach((c) => (all[c.id] = false));
+                    applyVisibility(all);
+                },
+                resetColumnVisibility: () => {
+                    const initialVisibility = initialStateConfig.columnVisibility || {};
+                    applyVisibility(initialVisibility);
+                },
+            },
+
+            // -------------------------------
+            // Column Ordering
+            // -------------------------------
+            columnOrdering: {
+                setColumnOrder: (nextOrder: ColumnOrderState) => {
+                    applyColumnOrder(nextOrder);
+                },
+                moveColumn: (columnId: string, toIndex: number) => {
+                    const currentOrder =
+                        (table.getState().columnOrder?.length ? table.getState().columnOrder : buildInitialOrder()) || [];
+                    const fromIndex = currentOrder.indexOf(columnId);
+                    if (fromIndex === -1) return;
+
+                    const next = [...currentOrder];
+                    next.splice(fromIndex, 1);
+                    next.splice(toIndex, 0, columnId);
+
+                    applyColumnOrder(next);
+                },
+                resetColumnOrder: () => {
+                    applyColumnOrder(buildInitialOrder());
+                },
+            },
+
+            // -------------------------------
+            // Column Pinning
+            // -------------------------------
+            columnPinning: {
+                pinColumnLeft: (columnId: string) => {
+                    const current = table.getState().columnPinning || { left: [], right: [] };
+                    const next: ColumnPinningState = {
+                        left: [...(current.left || []).filter((id) => id !== columnId), columnId],
+                        right: (current.right || []).filter((id) => id !== columnId),
+                    };
+                    applyPinning(next);
+                },
+                pinColumnRight: (columnId: string) => {
+                    const current = table.getState().columnPinning || { left: [], right: [] };
+                    const next: ColumnPinningState = {
+                        left: (current.left || []).filter((id) => id !== columnId),
+                        // keep your "prepend" behavior
+                        right: [columnId, ...(current.right || []).filter((id) => id !== columnId)],
+                    };
+                    applyPinning(next);
+                },
+                unpinColumn: (columnId: string) => {
+                    const current = table.getState().columnPinning || { left: [], right: [] };
+                    const next: ColumnPinningState = {
+                        left: (current.left || []).filter((id) => id !== columnId),
+                        right: (current.right || []).filter((id) => id !== columnId),
+                    };
+                    applyPinning(next);
+                },
+                setPinning: (pinning: ColumnPinningState) => {
+                    applyPinning(pinning);
+                },
+                resetColumnPinning: () => {
+                    const initialPinning = initialStateConfig.columnPinning || { left: [], right: [] };
+                    applyPinning(initialPinning);
+                },
+            },
+
+            // -------------------------------
+            // Column Resizing
+            // -------------------------------
+            columnResizing: {
+                resizeColumn: (columnId: string, width: number) => {
+                    const currentSizing = table.getState().columnSizing || {};
+                    applySizing({ ...currentSizing, [columnId]: width });
+                },
+                autoSizeColumn: (columnId: string) => {
+                    // safe to call tanstack helper; it will feed into onColumnSizingChange if wired,
+                    // but since you're controlled, we still prefer to update through handler:
+                    const col = table.getColumn(columnId);
+                    if (!col) return;
+
+                    col.resetSize();
+                    // after resetSize, read state and emit via handler so controlled stays synced
+                    applySizing({ ...(table.getState().columnSizing || {}) });
+                },
+                autoSizeAllColumns: () => {
+                    const initialSizing = initialStateConfig.columnSizing || {};
+                    applySizing(initialSizing);
+                },
+                resetColumnSizing: () => {
+                    const initialSizing = initialStateConfig.columnSizing || {};
+                    applySizing(initialSizing);
+                },
+            },
+
+            // -------------------------------
+            // Filtering
+            // -------------------------------
+            filtering: {
+                setGlobalFilter: (filter: string) => {
+                    applyGlobalFilter(filter);
+                },
+                clearGlobalFilter: () => {
+                    applyGlobalFilter("");
+                },
+                setColumnFilters: (filters: ColumnFilterState) => {
+                    handleColumnFilterStateChange(filters);
+                },
+                addColumnFilter: (columnId: string, operator: string, value: any) => {
+                    const newFilter = {
+                        id: `filter_${Date.now()}`,
+                        columnId,
+                        operator,
+                        value,
                     };
-                    setServerData?.(newData);
-                }
-            },
 
-            // Data queries
-            findRows: (predicate: (row: T) => boolean) => {
-                return (table.getRowModel().rows || [])?.filter(row => predicate(row.original))?.map(row => row.original);
-            },
-            findRowIndex: (predicate: (row: T) => boolean) => {
-                return (table.getRowModel().rows || [])?.findIndex(row => predicate(row.original));
-            },
-            getDataCount: () => {
-                return (table.getRowModel().rows || [])?.length || 0;
-            },
-            getFilteredDataCount: () => {
-                return table.getFilteredRowModel().rows.length;
-            },
-        },
+                    const current = table.getState().columnFilter;
+                    const currentFilters = current?.filters || [];
+                    const nextFilters = [...currentFilters, newFilter];
 
-        // Layout Management
-        layout: {
-            resetLayout: () => {
-                table.resetColumnSizing();
-                table.resetColumnVisibility();
-                table.resetSorting();
-                table.resetGlobalFilter();
-            },
-            resetAll: () => {
-                // Reset everything to initial state
-                table.resetColumnSizing();
-                table.resetColumnVisibility();
-                table.resetSorting();
-                table.resetGlobalFilter();
-                table.resetColumnOrder();
-                table.resetExpanded();
-                handleSelectionStateChange(initialSelectionState);
-                table.resetColumnPinning();
-
-                handleColumnFilterStateChange(initialStateConfig.columnFilter || { filters: [], logic: 'AND', pendingFilters: [], pendingLogic: 'AND' });
-
-                if (enablePagination) {
-                    table.setPagination(initialStateConfig.pagination || { pageIndex: 0, pageSize: 10 });
-                }
+                    handleColumnFilterStateChange({
+                        filters: nextFilters,
+                        logic: current?.logic,
+                        pendingFilters: current?.pendingFilters || [],
+                        pendingLogic: current?.pendingLogic || "AND",
+                    });
 
-                if (enableColumnPinning) {
-                    table.setColumnPinning(initialStateConfig.columnPinning || { left: [], right: [] });
-                }
-            },
-            saveLayout: () => {
-                return {
+                    if (logger.isLevelEnabled("debug")) {
+                        logger.debug(`Adding column filter ${columnId} ${operator} ${value}`, nextFilters);
+                    }
+                },
+                removeColumnFilter: (filterId: string) => {
+                    const current = table.getState().columnFilter;
+                    const currentFilters = current?.filters || [];
+                    const nextFilters = currentFilters.filter((f: any) => f.id !== filterId);
+
+                    handleColumnFilterStateChange({
+                        filters: nextFilters,
+                        logic: current?.logic,
+                        pendingFilters: current?.pendingFilters || [],
+                        pendingLogic: current?.pendingLogic || "AND",
+                    });
+
+                    if (logger.isLevelEnabled("debug")) {
+                        logger.debug(`Removing column filter ${filterId}`, nextFilters);
+                    }
+                },
+                clearAllFilters: () => {
+                    applyGlobalFilter("");
+                    handleColumnFilterStateChange({
+                        filters: [],
+                        logic: "AND",
+                        pendingFilters: [],
+                        pendingLogic: "AND",
+                    });
+                },
+                resetFilters: () => {
+                    handleColumnFilterStateChange({
+                        filters: [],
+                        logic: "AND",
+                        pendingFilters: [],
+                        pendingLogic: "AND",
+                    });
+
+                    if (logger.isLevelEnabled("debug")) {
+                        logger.debug("Resetting filters");
+                    }
+                },
+            },
+
+            // -------------------------------
+            // Sorting
+            // -------------------------------
+            sorting: {
+                setSorting: (sortingState: SortingState) => {
+                    applySorting(sortingState);
+                    if (logger.isLevelEnabled("debug")) logger.debug("Setting sorting", sortingState);
+                },
+
+                // NOTE: toggleSorting is okay, but can become "one behind" in controlled server mode.
+                // So we implement deterministic sorting through handler.
+                sortColumn: (columnId: string, direction: "asc" | "desc" | false) => {
+                    const current = table.getState().sorting || [];
+                    const filtered = current.filter((s: any) => s.id !== columnId);
+
+                    if (direction === false) {
+                        applySorting(filtered);
+                        return;
+                    }
+
+                    applySorting([{ id: columnId, desc: direction === "desc" }, ...filtered]);
+                },
+
+                clearSorting: () => {
+                    applySorting([]);
+                },
+                resetSorting: () => {
+                    const initialSorting = initialStateConfig.sorting || [];
+                    applySorting(initialSorting);
+                },
+            },
+
+            // -------------------------------
+            // Pagination
+            // -------------------------------
+            pagination: {
+                goToPage: (pageIndex: number) => {
+                    applyPagination((prev: any) => ({ ...prev, pageIndex }));
+                    if (logger.isLevelEnabled("debug")) logger.debug(`Going to page ${pageIndex}`);
+                },
+                nextPage: () => {
+                    applyPagination((prev: any) => ({ ...prev, pageIndex: (prev?.pageIndex ?? 0) + 1 }));
+                    if (logger.isLevelEnabled("debug")) logger.debug("Next page");
+                },
+                previousPage: () => {
+                    applyPagination((prev: any) => ({ ...prev, pageIndex: Math.max(0, (prev?.pageIndex ?? 0) - 1) }));
+                    if (logger.isLevelEnabled("debug")) logger.debug("Previous page");
+                },
+                setPageSize: (pageSize: number) => {
+                    // usually want pageIndex reset
+                    applyPagination(() => ({ pageIndex: 0, pageSize }));
+                    if (logger.isLevelEnabled("debug")) logger.debug(`Setting page size to ${pageSize}`);
+                },
+                goToFirstPage: () => {
+                    applyPagination((prev: any) => ({ ...prev, pageIndex: 0 }));
+                    if (logger.isLevelEnabled("debug")) logger.debug("Going to first page");
+                },
+                goToLastPage: () => {
+                    // pageCount can be derived; keep safe fallback
+                    const pageCount = table.getPageCount?.() ?? 0;
+                    if (pageCount > 0) {
+                        applyPagination((prev: any) => ({ ...prev, pageIndex: pageCount - 1 }));
+                        if (logger.isLevelEnabled("debug")) logger.debug(`Going to last page ${pageCount - 1}`);
+                    }
+                },
+                resetPagination: () => {
+                    const initialPagination = initialStateConfig.pagination || { pageIndex: 0, pageSize: 10 };
+                    applyPagination(initialPagination);
+                },
+            },
+
+            // -------------------------------
+            // Selection
+            // -------------------------------
+            selection: {
+                selectRow: (rowId: string) => table.selectRow?.(rowId),
+                deselectRow: (rowId: string) => table.deselectRow?.(rowId),
+                toggleRowSelection: (rowId: string) => table.toggleRowSelected?.(rowId),
+                selectAll: () => table.selectAll?.(),
+                deselectAll: () => table.deselectAll?.(),
+                toggleSelectAll: () => table.toggleAllRowsSelected?.(),
+                getSelectionState: () => table.getSelectionState?.() || ({ ids: [], type: "include" } as const),
+                getSelectedRows: () => table.getSelectedRows(),
+                getSelectedCount: () => table.getSelectedCount(),
+                isRowSelected: (rowId: string) => table.getIsRowSelected(rowId) || false,
+            },
+
+            // -------------------------------
+            // Data Management (kept same, but ensure state changes go through handlers)
+            // -------------------------------
+            data: {
+                refresh: (options?: boolean | DataRefreshOptions) => {
+                    void triggerRefresh(options, 'refresh');
+                },
+
+                reload: (options: DataRefreshOptions = {}) => {
+                    void triggerRefresh(
+                        {
+                            ...options,
+                            resetPagination: options.resetPagination ?? false,
+                            reason: options.reason ?? 'reload',
+                        },
+                        'reload'
+                    );
+                },
+
+                resetAll: () => resetAllAndReload(),
+
+                getAllData: () => [...tableData],
+                getRowData: (rowId: string) => {
+                    const rowIndex = getRowIndexById(tableData, rowId);
+                    return rowIndex === -1 ? undefined : tableData[rowIndex];
+                },
+                getRowByIndex: (index: number) => tableData[index],
+
+                updateRow: (rowId: string, updates: Partial<T>) => {
+                    applyDataMutation('updateRow', (rowsToMutate) => {
+                        const rowIndex = getRowIndexById(rowsToMutate, rowId);
+                        if (rowIndex === -1) return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData[rowIndex] = { ...nextData[rowIndex], ...updates };
+                        return nextData;
+                    }, { rowId });
+                },
+
+                updateRowByIndex: (index: number, updates: Partial<T>) => {
+                    applyDataMutation('updateRowByIndex', (rowsToMutate) => {
+                        if (!rowsToMutate[index]) return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData[index] = { ...nextData[index], ...updates };
+                        return nextData;
+                    }, { index });
+                },
+
+                insertRow: (newRow: T, index?: number) => {
+                    applyDataMutation('insertRow', (rowsToMutate) => {
+                        const nextData = [...rowsToMutate];
+                        nextData.splice(clampInsertIndex(nextData, index), 0, newRow);
+                        return nextData;
+                    }, { index });
+                },
+
+                deleteRow: (rowId: string) => {
+                    applyDataMutation('deleteRow', (rowsToMutate) => {
+                        const rowIndex = getRowIndexById(rowsToMutate, rowId);
+                        if (rowIndex === -1) return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData.splice(rowIndex, 1);
+                        return nextData;
+                    }, { rowId });
+                },
+
+                deleteRowByIndex: (index: number) => {
+                    applyDataMutation('deleteRowByIndex', (rowsToMutate) => {
+                        if (index < 0 || index >= rowsToMutate.length) return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData.splice(index, 1);
+                        return nextData;
+                    }, { index });
+                },
+
+                deleteSelectedRows: () => {
+                    const currentSelection = table.getSelectionState?.() || selectionState;
+                    const selectedIds = new Set((currentSelection.ids || []).map((id) => String(id)));
+                    const loadedRowIds = tableData.map((row, index) => String(generateRowId(row, index, idKey)));
+                    const deletableRowIds = currentSelection.type === 'exclude'
+                        ? loadedRowIds.filter((rowId) => !selectedIds.has(rowId))
+                        : loadedRowIds.filter((rowId) => selectedIds.has(rowId));
+
+                    if (deletableRowIds.length === 0) return;
+                    if (
+                        currentSelection.type === 'exclude'
+                        && table.getRowCount() > loadedRowIds.length
+                        && logger.isLevelEnabled('info')
+                    ) {
+                        logger.info('deleteSelectedRows in exclude mode removed currently loaded rows only', {
+                            removedRows: deletableRowIds.length,
+                            totalSelected: table.getSelectedCount?.(),
+                        });
+                    }
+
+                    const deletableRowIdSet = new Set(deletableRowIds);
+                    applyDataMutation(
+                        'deleteSelectedRows',
+                        (rowsToMutate) =>
+                            rowsToMutate.filter((row, index) => !deletableRowIdSet.has(String(generateRowId(row, index, idKey)))),
+                        { rowIds: deletableRowIds }
+                    );
+                    table.deselectAll?.();
+                },
+
+                replaceAllData: (newData: T[]) => {
+                    applyDataMutation('replaceAllData', () => [...newData]);
+                },
+
+                updateMultipleRows: (updates: Array<{ rowId: string; data: Partial<T> }>) => {
+                    const updateMap = new Map(updates.map((update) => [update.rowId, update.data]));
+                    applyDataMutation('updateMultipleRows', (rowsToMutate) =>
+                        rowsToMutate.map((row, index) => {
+                            const currentRowId = String(generateRowId(row, index, idKey));
+                            const updateData = updateMap.get(currentRowId);
+                            return updateData ? { ...row, ...updateData } : row;
+                        })
+                    );
+                },
+
+                insertMultipleRows: (newRows: T[], startIndex?: number) => {
+                    applyDataMutation('insertMultipleRows', (rowsToMutate) => {
+                        const nextData = [...rowsToMutate];
+                        nextData.splice(clampInsertIndex(nextData, startIndex), 0, ...newRows);
+                        return nextData;
+                    }, { index: startIndex });
+                },
+
+                deleteMultipleRows: (rowIds: string[]) => {
+                    const idsToDelete = new Set(rowIds);
+                    applyDataMutation(
+                        'deleteMultipleRows',
+                        (rowsToMutate) =>
+                            rowsToMutate.filter((row, index) => !idsToDelete.has(String(generateRowId(row, index, idKey)))),
+                        { rowIds }
+                    );
+                },
+
+                updateField: (rowId: string, fieldName: keyof T, value: any) => {
+                    applyDataMutation('updateField', (rowsToMutate) => {
+                        const rowIndex = getRowIndexById(rowsToMutate, rowId);
+                        if (rowIndex === -1) return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData[rowIndex] = { ...nextData[rowIndex], [fieldName]: value };
+                        return nextData;
+                    }, { rowId });
+                },
+
+                updateFieldByIndex: (index: number, fieldName: keyof T, value: any) => {
+                    applyDataMutation('updateFieldByIndex', (rowsToMutate) => {
+                        if (!rowsToMutate[index]) return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData[index] = { ...nextData[index], [fieldName]: value };
+                        return nextData;
+                    }, { index });
+                },
+
+                findRows: (predicate: (row: T) => boolean) => tableData.filter(predicate),
+
+                findRowIndex: (predicate: (row: T) => boolean) => tableData.findIndex(predicate),
+
+                getDataCount: () => tableData.length,
+                getFilteredDataCount: () => table.getFilteredRowModel().rows.length,
+            },
+
+            // -------------------------------
+            // Layout Management
+            // -------------------------------
+            layout: {
+                resetLayout: () => {
+                    // go through handlers so controlled state updates + emit works
+                    applySizing(initialStateConfig.columnSizing || {});
+                    applyVisibility(initialStateConfig.columnVisibility || {});
+                    applySorting(initialStateConfig.sorting || []);
+                    applyGlobalFilter(initialStateConfig.globalFilter ?? "");
+                },
+                resetAll: () => resetAllAndReload(),
+                saveLayout: () => ({
                     columnVisibility: table.getState().columnVisibility,
                     columnSizing: table.getState().columnSizing,
                     columnOrder: table.getState().columnOrder,
@@ -1328,251 +1584,337 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
                     pagination: table.getState().pagination,
                     globalFilter: table.getState().globalFilter,
                     columnFilter: table.getState().columnFilter,
-                };
-            },
-            restoreLayout: (layout: Partial<TableState>) => {
-                if (layout.columnVisibility) {
-                    table.setColumnVisibility(layout.columnVisibility);
-                }
-                if (layout.columnSizing) {
-                    table.setColumnSizing(layout.columnSizing);
-                }
-                if (layout.columnOrder) {
-                    table.setColumnOrder(layout.columnOrder);
-                }
-                if (layout.columnPinning) {
-                    table.setColumnPinning(layout.columnPinning);
-                }
-                if (layout.sorting) {
-                    table.setSorting(layout.sorting);
-                }
-                if (layout.pagination && enablePagination) {
-                    table.setPagination(layout.pagination);
-                }
-                if (layout.globalFilter !== undefined) {
-                    table.setGlobalFilter(layout.globalFilter);
-                }
-                if (layout.columnFilter) {
-                    handleColumnFilterStateChange(layout.columnFilter);
-                }
-            },
-        },
-
-        // Table State
-        state: {
-            getTableState: () => {
-                return table.getState();
-            },
-            getCurrentFilters: () => {
-                return table.getState().columnFilter;
-            },
-            getCurrentSorting: () => {
-                return table.getState().sorting;
-            },
-            getCurrentPagination: () => {
-                return table.getState().pagination;
-            },
-            // Backward compatibility: expose the raw selection array expected by older consumers
-            getCurrentSelection: () => {
-                return table.getSelectionState?.();
-            },
-        },
-
-        // Simplified Export
-        export: {
-            exportCSV: async (options: any = {}) => {
-                const { filename = exportFilename, } = options;
-
-                try {
-                    // Create abort controller for this export
-                    const controller = new AbortController();
-                    setExportController?.(controller);
-
-                    if (dataMode === 'server' && onServerExport) {
-                        // Server export with selection data
-                        const currentFilters = {
-                            globalFilter: table.getState().globalFilter,
-                            columnFilter: table.getState().columnFilter,
-                            sorting: table.getState().sorting,
-                            pagination: table.getState().pagination,
-                        };
-                        if (logger.isLevelEnabled('debug')) {
-                            logger.debug('Server export CSV', { currentFilters });
-                        }
-                        await exportServerData(table, {
-                            format: 'csv',
-                            filename,
-                            fetchData: (filters, selection) => onServerExport(filters, selection),
-                            currentFilters,
-                            selection: table.getSelectionState?.(),
-                            onProgress: onExportProgress,
-                            onComplete: onExportComplete,
-                            onError: onExportError,
-                        });
-                    } else {
-                        // Client export - auto-detect selected rows if not specified
-                        await exportClientData(table, {
-                            format: 'csv',
-                            filename,
-                            onProgress: onExportProgress,
-                            onComplete: onExportComplete,
-                            onError: onExportError,
-                        });
-                        if (logger.isLevelEnabled('debug')) {
-                            logger.debug('Client export CSV', filename);
+                }),
+                restoreLayout: (layout: Partial<TableState>) => {
+                    if (layout.columnVisibility) applyVisibility(layout.columnVisibility as any);
+                    if (layout.columnSizing) applySizing(layout.columnSizing as any);
+                    if (layout.columnOrder) applyColumnOrder(layout.columnOrder as any);
+                    if (layout.columnPinning) applyPinning(layout.columnPinning as any);
+                    if (layout.sorting) applySorting(layout.sorting as any);
+                    if (layout.pagination && enablePagination) applyPagination(layout.pagination as any);
+                    if (layout.globalFilter !== undefined) applyGlobalFilter(layout.globalFilter);
+                    if (layout.columnFilter) handleColumnFilterStateChange(layout.columnFilter as any);
+                },
+            },
+
+            // -------------------------------
+            // Table State
+            // -------------------------------
+            state: {
+                getTableState: () => table.getState(),
+                getCurrentFilters: () => table.getState().columnFilter,
+                getCurrentSorting: () => table.getState().sorting,
+                getCurrentPagination: () => table.getState().pagination,
+                getCurrentSelection: () => table.getSelectionState?.(),
+            },
+
+            // -------------------------------
+            // Export (unchanged mostly)
+            // -------------------------------
+            export: {
+                exportCSV: async (options: DataTableExportApiOptions = {}) => {
+                    const {
+                        filename = exportFilename,
+                        chunkSize = exportChunkSize,
+                        strictTotalCheck = exportStrictTotalCheck,
+                        sanitizeCSV = exportSanitizeCSV,
+                    } = options;
+                    const mode: 'client' | 'server' = dataMode === "server" && !!onServerExport ? 'server' : 'client';
+
+                    await runExportWithPolicy({
+                        format: 'csv',
+                        filename,
+                        mode,
+                        execute: async (controller) => {
+                            const toStateChange = (state: {
+                                phase: ExportPhase;
+                                processedRows?: number;
+                                totalRows?: number;
+                                percentage?: number;
+                                message?: string;
+                                code?: string;
+                            }) => {
+                                const isFinalPhase = state.phase === 'completed' || state.phase === 'cancelled' || state.phase === 'error';
+                                handleExportStateChangeInternal({
+                                    phase: state.phase,
+                                    mode,
+                                    format: 'csv',
+                                    filename,
+                                    processedRows: state.processedRows,
+                                    totalRows: state.totalRows,
+                                    percentage: state.percentage,
+                                    message: state.message,
+                                    code: state.code,
+                                    startedAt: state.phase === 'starting' ? Date.now() : undefined,
+                                    endedAt: isFinalPhase ? Date.now() : undefined,
+                                    queueLength: queuedExportCount,
+                                });
+                                if (state.phase === 'cancelled') {
+                                    onExportCancel?.();
+                                }
+                            };
+
+                            if (mode === 'server' && onServerExport) {
+                                const currentFilters = {
+                                    globalFilter: table.getState().globalFilter,
+                                    columnFilter: table.getState().columnFilter,
+                                    sorting: table.getState().sorting,
+                                    pagination: table.getState().pagination,
+                                };
+
+                                if (logger.isLevelEnabled("debug")) logger.debug("Server export CSV", { currentFilters });
+
+                                await exportServerData(table, {
+                                    format: "csv",
+                                    filename,
+                                    fetchData: (filters: any, selection: any, signal?: AbortSignal) =>
+                                        onServerExport(filters, selection, signal),
+                                    currentFilters,
+                                    selection: table.getSelectionState?.(),
+                                    onProgress: handleExportProgressInternal,
+                                    onComplete: onExportComplete,
+                                    onError: onExportError,
+                                    onStateChange: toStateChange,
+                                    signal: controller.signal,
+                                    chunkSize,
+                                    strictTotalCheck,
+                                    sanitizeCSV,
+                                });
+                                return;
+                            }
+
+                            await exportClientData(table, {
+                                format: "csv",
+                                filename,
+                                onProgress: handleExportProgressInternal,
+                                onComplete: onExportComplete,
+                                onError: onExportError,
+                                onStateChange: toStateChange,
+                                signal: controller.signal,
+                                sanitizeCSV,
+                            });
+
+                            if (logger.isLevelEnabled("debug")) logger.debug("Client export CSV", filename);
                         }
-                    }
-                } catch (error: any) {
-                    onExportError?.({
-                        message: error.message || 'Export failed',
-                        code: 'EXPORT_ERROR',
                     });
-                } finally {
-                    setExportController?.(null);
-                }
-            },
-            exportExcel: async (options: any = {}) => {
-                const { filename = exportFilename } = options;
-
-                try {
-                    // Create abort controller for this export
-                    const controller = new AbortController();
-                    setExportController?.(controller);
-
-                    if (dataMode === 'server' && onServerExport) {
-                        // Server export with selection data
-                        const currentFilters = {
-                            globalFilter: table.getState().globalFilter,
-                            columnFilter: table.getState().columnFilter,
-                            sorting: table.getState().sorting,
-                            pagination: table.getState().pagination,
-                        };
-
-                        if (logger.isLevelEnabled('debug')) {
-                            logger.debug('Server export Excel', { currentFilters });
-                        }
-                        await exportServerData(table, {
-                            format: 'excel',
-                            filename,
-                            fetchData: (filters, selection) => onServerExport(filters, selection),
-                            currentFilters,
-                            selection: table.getSelectionState?.(),
-                            onProgress: onExportProgress,
-                            onComplete: onExportComplete,
-                            onError: onExportError,
-                        });
-                    } else {
-                        // Client export - auto-detect selected rows if not specified
-                        await exportClientData(table, {
-                            format: 'excel',
-                            filename,
-                            onProgress: onExportProgress,
-                            onComplete: onExportComplete,
-                            onError: onExportError,
-                        });
-                        if (logger.isLevelEnabled('debug')) {
-                            logger.debug('Client export Excel', filename);
+                },
+
+                exportExcel: async (options: DataTableExportApiOptions = {}) => {
+                    const {
+                        filename = exportFilename,
+                        chunkSize = exportChunkSize,
+                        strictTotalCheck = exportStrictTotalCheck,
+                        sanitizeCSV = exportSanitizeCSV,
+                    } = options;
+                    const mode: 'client' | 'server' = dataMode === "server" && !!onServerExport ? 'server' : 'client';
+
+                    await runExportWithPolicy({
+                        format: 'excel',
+                        filename,
+                        mode,
+                        execute: async (controller) => {
+                            const toStateChange = (state: {
+                                phase: ExportPhase;
+                                processedRows?: number;
+                                totalRows?: number;
+                                percentage?: number;
+                                message?: string;
+                                code?: string;
+                            }) => {
+                                const isFinalPhase = state.phase === 'completed' || state.phase === 'cancelled' || state.phase === 'error';
+                                handleExportStateChangeInternal({
+                                    phase: state.phase,
+                                    mode,
+                                    format: 'excel',
+                                    filename,
+                                    processedRows: state.processedRows,
+                                    totalRows: state.totalRows,
+                                    percentage: state.percentage,
+                                    message: state.message,
+                                    code: state.code,
+                                    startedAt: state.phase === 'starting' ? Date.now() : undefined,
+                                    endedAt: isFinalPhase ? Date.now() : undefined,
+                                    queueLength: queuedExportCount,
+                                });
+                                if (state.phase === 'cancelled') {
+                                    onExportCancel?.();
+                                }
+                            };
+
+                            if (mode === 'server' && onServerExport) {
+                                const currentFilters = {
+                                    globalFilter: table.getState().globalFilter,
+                                    columnFilter: table.getState().columnFilter,
+                                    sorting: table.getState().sorting,
+                                    pagination: table.getState().pagination,
+                                };
+
+                                if (logger.isLevelEnabled("debug")) logger.debug("Server export Excel", { currentFilters });
+
+                                await exportServerData(table, {
+                                    format: "excel",
+                                    filename,
+                                    fetchData: (filters: any, selection: any, signal?: AbortSignal) =>
+                                        onServerExport(filters, selection, signal),
+                                    currentFilters,
+                                    selection: table.getSelectionState?.(),
+                                    onProgress: handleExportProgressInternal,
+                                    onComplete: onExportComplete,
+                                    onError: onExportError,
+                                    onStateChange: toStateChange,
+                                    signal: controller.signal,
+                                    chunkSize,
+                                    strictTotalCheck,
+                                    sanitizeCSV,
+                                });
+                                return;
+                            }
+
+                            await exportClientData(table, {
+                                format: "excel",
+                                filename,
+                                onProgress: handleExportProgressInternal,
+                                onComplete: onExportComplete,
+                                onError: onExportError,
+                                onStateChange: toStateChange,
+                                signal: controller.signal,
+                                sanitizeCSV,
+                            });
+
+                            if (logger.isLevelEnabled("debug")) logger.debug("Client export Excel", filename);
                         }
-                    }
-                } catch (error: any) {
-                    onExportError?.({
-                        message: error.message || 'Export failed',
-                        code: 'EXPORT_ERROR',
-                    });
-                    if (logger.isLevelEnabled('debug')) {
-                        logger.debug('Server export Excel failed', error);
-                    }
-                } finally {
-                    setExportController?.(null);
-                }
-            },
-            exportServerData: async (options) => {
-                const {
-                    format,
-                    filename = exportFilename,
-                    fetchData = onServerExport,
-                } = options;
-
-                if (!fetchData) {
-                    onExportError?.({
-                        message: 'No server export function provided',
-                        code: 'NO_SERVER_EXPORT',
                     });
-                    if (logger.isLevelEnabled('debug')) {
-                        logger.debug('Server export data failed', 'No server export function provided');
+                },
+
+                exportServerData: async (options: {
+                    format: 'csv' | 'excel';
+                    filename?: string;
+                    fetchData?: (
+                        filters?: Partial<TableState>,
+                        selection?: SelectionState,
+                        signal?: AbortSignal
+                    ) => Promise<any>;
+                    chunkSize?: number;
+                    strictTotalCheck?: boolean;
+                    sanitizeCSV?: boolean;
+                }) => {
+                    const {
+                        format,
+                        filename = exportFilename,
+                        fetchData: fetchFn = onServerExport,
+                        chunkSize = exportChunkSize,
+                        strictTotalCheck = exportStrictTotalCheck,
+                        sanitizeCSV = exportSanitizeCSV,
+                    } = options;
+
+                    if (!fetchFn) {
+                        onExportError?.({ message: "No server export function provided", code: "NO_SERVER_EXPORT" });
+                        if (logger.isLevelEnabled("debug")) logger.debug("Server export data failed", "No server export function provided");
+                        return;
                     }
-                    return;
-                }
 
-                try {
-                    // Create abort controller for this export
-                    const controller = new AbortController();
-                    setExportController?.(controller);
-
-                    const currentFilters = {
-                        globalFilter: table.getState().globalFilter,
-                        columnFilter: table.getState().columnFilter,
-                        sorting: table.getState().sorting,
-                        pagination: table.getState().pagination,
-                    };
-                    if (logger.isLevelEnabled('debug')) {
-                        logger.debug('Server export data', { currentFilters });
-                    }
-                    await exportServerData(table, {
+                    await runExportWithPolicy({
                         format,
                         filename,
-                        fetchData: (filters, selection) => fetchData(filters, selection),
-                        currentFilters,
-                        selection: table.getSelectionState?.(),
-                        onProgress: onExportProgress,
-                        onComplete: onExportComplete,
-                        onError: onExportError,
-                    });
-                } catch (error: any) {
-                    onExportError?.({
-                        message: error.message || 'Export failed',
-                        code: 'EXPORT_ERROR',
+                        mode: 'server',
+                        execute: async (controller) => {
+                            const currentFilters = {
+                                globalFilter: table.getState().globalFilter,
+                                columnFilter: table.getState().columnFilter,
+                                sorting: table.getState().sorting,
+                                pagination: table.getState().pagination,
+                            };
+
+                            if (logger.isLevelEnabled("debug")) logger.debug("Server export data", { currentFilters });
+
+                            await exportServerData(table, {
+                                format,
+                                filename,
+                                fetchData: (filters: any, selection: any, signal?: AbortSignal) =>
+                                    fetchFn(filters, selection, signal),
+                                currentFilters,
+                                selection: table.getSelectionState?.(),
+                                onProgress: handleExportProgressInternal,
+                                onComplete: onExportComplete,
+                                onError: onExportError,
+                                onStateChange: (state) => {
+                                    const isFinalPhase = state.phase === 'completed' || state.phase === 'cancelled' || state.phase === 'error';
+                                    handleExportStateChangeInternal({
+                                        phase: state.phase,
+                                        mode: 'server',
+                                        format,
+                                        filename,
+                                        processedRows: state.processedRows,
+                                        totalRows: state.totalRows,
+                                        percentage: state.percentage,
+                                        message: state.message,
+                                        code: state.code,
+                                        startedAt: state.phase === 'starting' ? Date.now() : undefined,
+                                        endedAt: isFinalPhase ? Date.now() : undefined,
+                                        queueLength: queuedExportCount,
+                                    });
+                                    if (state.phase === 'cancelled') {
+                                        onExportCancel?.();
+                                    }
+                                },
+                                signal: controller.signal,
+                                chunkSize,
+                                strictTotalCheck,
+                                sanitizeCSV,
+                            });
+                        }
                     });
-                    if (logger.isLevelEnabled('debug')) {
-                        logger.debug('Server export data failed', error);
+                },
+
+                isExporting: () => isExporting || false,
+                cancelExport: () => {
+                    const activeController = exportControllerRef.current;
+                    if (!activeController) {
+                        return;
                     }
-                } finally {
-                    setExportController?.(null);
-                }
+                    activeController.abort();
+                    setExportControllerSafely((current) => (current === activeController ? null : current));
+                    if (logger.isLevelEnabled("debug")) logger.debug("Export cancelled");
+                },
             },
-            // Export state
-            isExporting: () => isExporting || false,
-            cancelExport: () => {
-                exportController?.abort();
-                setExportController?.(null);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Export cancelled');
-                }
-            },
-        },
+        };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }), [
+    }, [
         table,
         enhancedColumns,
+        handleColumnOrderChange,
+        handleColumnPinningChange,
+        handleColumnVisibilityChange,
+        handleColumnSizingChange,
+        handlePaginationChange,
+        handleSortingChange,
+        handleGlobalFilterChange,
         handleColumnFilterStateChange,
-        idKey,
-        onDataStateChange,
-        fetchData,
-        enableColumnPinning,
+        initialStateConfig,
         enablePagination,
-        // Export dependencies
+        idKey,
+        triggerRefresh,
+        applyDataMutation,
+        tableData,
+        selectionState,
+        // export
         exportFilename,
-        onExportProgress,
+        exportChunkSize,
+        exportStrictTotalCheck,
+        exportSanitizeCSV,
         onExportComplete,
         onExportError,
+        onExportCancel,
         onServerExport,
-        exportController,
-        setExportController,
+        queuedExportCount,
         isExporting,
         dataMode,
-        selectMode,
-        onSelectionChange,
-        // Note: custom selection removed from dependency array
+        handleExportProgressInternal,
+        handleExportStateChangeInternal,
+        runExportWithPolicy,
+        setExportControllerSafely,
+        logger,
+        resetAllAndReload,
     ]);
 
     internalApiRef.current = dataTableApi;
@@ -1710,14 +2052,12 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
     // Export cancel callback
     // -------------------------------
     const handleCancelExport = useCallback(() => {
-        if (exportController) {
-            exportController.abort();
-            setExportController(null);
-            if (onExportCancel) {
-                onExportCancel();
-            }
+        const activeController = exportControllerRef.current;
+        if (activeController) {
+            activeController.abort();
+            setExportControllerSafely((current) => (current === activeController ? null : current));
         }
-    }, [exportController, onExportCancel]);
+    }, [setExportControllerSafely]);
 
     // -------------------------------
     // Slot components
@@ -1797,6 +2137,8 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
             slotProps={slotProps}
             isExporting={isExporting}
             exportController={exportController}
+            exportPhase={exportPhase}
+            exportProgress={exportProgress}
             onCancelExport={handleCancelExport}
             exportFilename={exportFilename}
             onExportProgress={onExportProgress}
@@ -1818,7 +2160,15 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
                         enableReset={enableReset}
                         enableTableSizeControl={enableTableSizeControl}
                         enableColumnPinning={enableColumnPinning}
+                        enableRefresh={enableRefresh}
                         {...toolbarSlotProps}
+                        refreshButtonProps={{
+                            loading: tableLoading, // disable while fetching
+                            showSpinnerWhileLoading: false,
+                            onRefresh: () => internalApiRef.current?.data?.refresh?.(true),
+                            ...toolbarSlotProps.refreshButtonProps,
+                        }}
+
                     />
                 ) : null}