@ackplus/react-tanstack-data-table 1.1.12 → 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,
@@ -252,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]);
 
 
@@ -309,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 });
@@ -317,7 +350,7 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
             return;
         }
 
-        const filters: TableFiltersForFetch = {
+        const filters: Partial<TableFiltersForFetch> = {
             globalFilter,
             pagination,
             columnFilter,
@@ -325,15 +358,20 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
             ...overrides,
         };
 
-        console.log('Fetching data', filters);
-
         if (logger.isLevelEnabled('info')) {
-            logger.info('Requesting data', { filters });
+            logger.info('Requesting data', {
+                filters,
+                reason: options?.meta?.reason,
+                force: options?.meta?.force,
+            });
         }
 
         try {
             const delay = options?.delay ?? 300; // respects 0
-            const result = await debouncedFetch(filters, delay);
+            const result = await debouncedFetch(filters, {
+                debounceDelay: delay,
+                meta: options?.meta,
+            });
 
             if (logger.isLevelEnabled('info')) {
                 logger.info('Fetch resolved', {
@@ -342,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')) {
@@ -364,6 +402,25 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         logger,
     ]);
 
+    const normalizeRefreshOptions = useCallback((
+        options?: boolean | DataRefreshOptions,
+        fallbackReason: string = 'refresh'
+    ) => {
+        if (typeof options === 'boolean') {
+            return {
+                resetPagination: options,
+                force: false,
+                reason: fallbackReason,
+            };
+        }
+
+        return {
+            resetPagination: options?.resetPagination ?? false,
+            force: options?.force ?? false,
+            reason: options?.reason ?? fallbackReason,
+        };
+    }, []);
+
 
     const handleSelectionStateChange = useCallback((updaterOrValue) => {
         setSelectionState((prevState) => {
@@ -634,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,
@@ -670,13 +736,14 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         if (!onDataStateChange) return;
 
         const live = table.getState();
+        const liveColumnFilter = live.columnFilter;
 
         // only keep what you persist/store
         const payload = {
             sorting: live.sorting,
             pagination: live.pagination,
             globalFilter: live.globalFilter,
-            columnFilter: live.columnFilter,
+            columnFilter: liveColumnFilter,
             columnVisibility: live.columnVisibility,
             columnSizing: live.columnSizing,
             columnOrder: live.columnOrder,
@@ -708,8 +775,7 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
     const getResetState = useCallback((): Partial<TableState> => {
         const resetSorting = initialStateConfig.sorting || [];
         const resetGlobalFilter = initialStateConfig.globalFilter ?? '';
-        const resetColumnFilter =
-            initialStateConfig.columnFilter || { filters: [], logic: 'AND', pendingFilters: [], pendingLogic: 'AND' };
+        const resetColumnFilter = initialStateConfig.columnFilter;
 
         const resetPagination = enablePagination
             ? (initialStateConfig.pagination || { pageIndex: 0, pageSize: 10 })
@@ -723,6 +789,126 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         };
     }, [initialStateConfig, enablePagination]);
 
+    const applyDataMutation = useCallback((
+        action: DataMutationAction,
+        updater: (rows: T[]) => T[],
+        details: Partial<Omit<DataMutationContext<T>, 'action' | 'previousData' | 'nextData'>> = {}
+    ) => {
+        const previousData = [...tableData];
+        const nextData = updater(previousData);
+
+        if (nextData === previousData) return nextData;
+
+        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,
+                    },
+                }
+            );
+            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();
 
@@ -730,7 +916,10 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         setGlobalFilter(resetState.globalFilter ?? '');
         setColumnFilter(resetState.columnFilter as any);
 
-        if (resetState.pagination) setPagination(resetState.pagination);
+        if (resetState.pagination) {
+            setPagination(resetState.pagination);
+            onPaginationChange?.(resetState.pagination);
+        }
 
         setSelectionState(initialSelectionState);
         setExpanded({});
@@ -741,8 +930,139 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         setColumnOrder(initialStateConfig.columnOrder || []);
         setColumnPinning(initialStateConfig.columnPinning || { left: [], right: [] });
 
-        if (onFetchData) fetchData(resetState, { delay: 0 });
-    }, [getResetState, initialSelectionState, initialStateConfig, onFetchData, fetchData]);
+        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));
+                }
+            };
+
+            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;
+                }
+
+                if (exportConcurrency === 'cancelAndRestart') {
+                    activeController.abort();
+                }
+            }
+
+            await startExecution();
+        },
+        [
+            exportConcurrency,
+            handleExportStateChangeInternal,
+            onExportError,
+            setExportControllerSafely,
+        ]
+    );
 
     const dataTableApi = useMemo(() => {
         // helpers (avoid repeating boilerplate)
@@ -783,6 +1103,14 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
             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,
@@ -1075,146 +1403,163 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
             // Data Management (kept same, but ensure state changes go through handlers)
             // -------------------------------
             data: {
-                refresh: (resetPagination = false) => {
-                    const allState = table.getState();
-                    const current = allState.pagination;
-
-                    const nextPagination = {
-                        pageIndex: resetPagination ? 0 : current?.pageIndex ?? 0,
-                        pageSize: current?.pageSize ?? initialStateConfig.pagination?.pageSize ?? 10,
-                    };
-
-                    // must go through handler so server fetch triggers
-                    applyPagination(nextPagination);
-
-                    // emit persisted state (your emitTableState effect will also do it)
-                    onDataStateChange?.({ ...allState, pagination: nextPagination });
-
-                    fetchData?.({ pagination: nextPagination });
-
-                    if (logger.isLevelEnabled("debug")) {
-                        logger.debug("Refreshing data", { nextPagination, allState });
-                    }
+                refresh: (options?: boolean | DataRefreshOptions) => {
+                    void triggerRefresh(options, 'refresh');
                 },
 
-                reload: () => {
-                    const allState = table.getState();
-                    onDataStateChange?.(allState);
-                    fetchData?.();
-                    if (logger.isLevelEnabled("debug")) {
-                        logger.info("Reloading data", allState);
-                    }
+                reload: (options: DataRefreshOptions = {}) => {
+                    void triggerRefresh(
+                        {
+                            ...options,
+                            resetPagination: options.resetPagination ?? false,
+                            reason: options.reason ?? 'reload',
+                        },
+                        'reload'
+                    );
                 },
 
-                resetAll: () => resetAllAndReload({ resetLayout: true }),
+                resetAll: () => resetAllAndReload(),
 
-                getAllData: () => table.getRowModel().rows?.map((row) => row.original) || [],
-                getRowData: (rowId: string) =>
-                    table.getRowModel().rows?.find((row) => String(row.original[idKey]) === rowId)?.original,
-                getRowByIndex: (index: number) => table.getRowModel().rows?.[index]?.original,
+                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>) => {
-                    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);
+                    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>) => {
-                    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);
-                    }
+                    applyDataMutation('updateRowByIndex', (rowsToMutate) => {
+                        if (!rowsToMutate[index]) return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData[index] = { ...nextData[index], ...updates };
+                        return nextData;
+                    }, { index });
                 },
 
                 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);
+                    applyDataMutation('insertRow', (rowsToMutate) => {
+                        const nextData = [...rowsToMutate];
+                        nextData.splice(clampInsertIndex(nextData, index), 0, newRow);
+                        return nextData;
+                    }, { index });
                 },
 
                 deleteRow: (rowId: string) => {
-                    const newData = (table.getRowModel().rows || []).filter((row) => String(row.original[idKey]) !== rowId);
-                    setServerData?.(newData.map((r) => r.original) || []);
-                    if (logger.isLevelEnabled("debug")) logger.debug(`Deleting row ${rowId}`);
+                    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) => {
-                    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}`);
+                    applyDataMutation('deleteRowByIndex', (rowsToMutate) => {
+                        if (index < 0 || index >= rowsToMutate.length) return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData.splice(index, 1);
+                        return nextData;
+                    }, { index });
                 },
 
                 deleteSelectedRows: () => {
-                    const selectedRows = table.getSelectedRows?.() || [];
-                    if (selectedRows.length === 0) return;
-
-                    const selectedIds = new Set(selectedRows.map((row) => String(row.original[idKey])));
-                    const newData = (table.getRowModel().rows || [])
-                        .filter((row) => !selectedIds.has(String(row.original[idKey])))
-                        .map((row) => row.original);
+                    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?.(),
+                        });
+                    }
 
-                    setServerData(newData);
+                    const deletableRowIdSet = new Set(deletableRowIds);
+                    applyDataMutation(
+                        'deleteSelectedRows',
+                        (rowsToMutate) =>
+                            rowsToMutate.filter((row, index) => !deletableRowIdSet.has(String(generateRowId(row, index, idKey)))),
+                        { rowIds: deletableRowIds }
+                    );
                     table.deselectAll?.();
-
-                    if (logger.isLevelEnabled("debug")) logger.debug("Deleting selected rows");
                 },
 
-                replaceAllData: (newData: T[]) => setServerData?.(newData),
+                replaceAllData: (newData: T[]) => {
+                    applyDataMutation('replaceAllData', () => [...newData]);
+                },
 
                 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 || []);
+                    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) => {
-                    const newData = (table.getRowModel().rows || []).map((row) => row.original);
-                    if (startIndex !== undefined) newData.splice(startIndex, 0, ...newRows);
-                    else newData.push(...newRows);
-                    setServerData?.(newData);
+                    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);
-                    const newData = (table.getRowModel().rows || [])
-                        .filter((row) => !idsToDelete.has(String(row.original[idKey])))
-                        .map((row) => row.original);
-                    setServerData(newData);
+                    applyDataMutation(
+                        'deleteMultipleRows',
+                        (rowsToMutate) =>
+                            rowsToMutate.filter((row, index) => !idsToDelete.has(String(generateRowId(row, index, idKey)))),
+                        { rowIds }
+                    );
                 },
 
                 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);
+                    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) => {
-                    const newData = (table.getRowModel().rows || []).map((row) => row.original);
-                    if (newData[index]) {
-                        newData[index] = { ...newData[index], [fieldName]: value };
-                        setServerData?.(newData);
-                    }
+                    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) =>
-                    (table.getRowModel().rows || []).filter((row) => predicate(row.original)).map((row) => row.original),
+                findRows: (predicate: (row: T) => boolean) => tableData.filter(predicate),
 
-                findRowIndex: (predicate: (row: T) => boolean) =>
-                    (table.getRowModel().rows || []).findIndex((row) => predicate(row.original)),
+                findRowIndex: (predicate: (row: T) => boolean) => tableData.findIndex(predicate),
 
-                getDataCount: () => (table.getRowModel().rows || []).length || 0,
+                getDataCount: () => tableData.length,
                 getFilteredDataCount: () => table.getFilteredRowModel().rows.length,
             },
 
@@ -1229,7 +1574,7 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
                     applySorting(initialStateConfig.sorting || []);
                     applyGlobalFilter(initialStateConfig.globalFilter ?? "");
                 },
-                resetAll: () => resetAllAndReload({ resetLayout: true }),
+                resetAll: () => resetAllAndReload(),
                 saveLayout: () => ({
                     columnVisibility: table.getState().columnVisibility,
                     columnSizing: table.getState().columnSizing,
@@ -1267,99 +1612,200 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
             // Export (unchanged mostly)
             // -------------------------------
             export: {
-                exportCSV: async (options: any = {}) => {
-                    const { filename = exportFilename } = options;
-
-                    try {
-                        const controller = new AbortController();
-                        setExportController?.(controller);
-
-                        if (dataMode === "server" && onServerExport) {
-                            const currentFilters = {
-                                globalFilter: table.getState().globalFilter,
-                                columnFilter: table.getState().columnFilter,
-                                sorting: table.getState().sorting,
-                                pagination: table.getState().pagination,
+                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 (logger.isLevelEnabled("debug")) logger.debug("Server export CSV", { currentFilters });
+                            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 exportServerData(table, {
-                                format: "csv",
-                                filename,
-                                fetchData: (filters: any, selection: any) => onServerExport(filters, selection),
-                                currentFilters,
-                                selection: table.getSelectionState?.(),
-                                onProgress: onExportProgress,
-                                onComplete: onExportComplete,
-                                onError: onExportError,
-                            });
-                        } else {
                             await exportClientData(table, {
                                 format: "csv",
                                 filename,
-                                onProgress: onExportProgress,
+                                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 {
-                        const controller = new AbortController();
-                        setExportController?.(controller);
-
-                        if (dataMode === "server" && onServerExport) {
-                            const currentFilters = {
-                                globalFilter: table.getState().globalFilter,
-                                columnFilter: table.getState().columnFilter,
-                                sorting: table.getState().sorting,
-                                pagination: table.getState().pagination,
+                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 (logger.isLevelEnabled("debug")) logger.debug("Server export Excel", { currentFilters });
+                            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 exportServerData(table, {
-                                format: "excel",
-                                filename,
-                                fetchData: (filters: any, selection: any) => onServerExport(filters, selection),
-                                currentFilters,
-                                selection: table.getSelectionState?.(),
-                                onProgress: onExportProgress,
-                                onComplete: onExportComplete,
-                                onError: onExportError,
-                            });
-                        } else {
                             await exportClientData(table, {
                                 format: "excel",
                                 filename,
-                                onProgress: onExportProgress,
+                                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: any) => {
-                    const { format, filename = exportFilename, fetchData: fetchFn = onServerExport } = options;
+                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" });
@@ -1367,41 +1813,67 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
                         return;
                     }
 
-                    try {
-                        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, {
-                            format,
-                            filename,
-                            fetchData: (filters: any, selection: any) => fetchFn(filters, selection),
-                            currentFilters,
-                            selection: table.getSelectionState?.(),
-                            onProgress: onExportProgress,
-                            onComplete: onExportComplete,
-                            onError: onExportError,
-                        });
-                    } catch (error: any) {
-                        onExportError?.({ message: error.message || "Export failed", code: "EXPORT_ERROR" });
-                        if (logger.isLevelEnabled("debug")) logger.debug("Server export data failed", error);
-                    } finally {
-                        setExportController?.(null);
-                    }
+                    await runExportWithPolicy({
+                        format,
+                        filename,
+                        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,
+                            });
+                        }
+                    });
                 },
 
                 isExporting: () => isExporting || false,
                 cancelExport: () => {
-                    exportController?.abort();
-                    setExportController?.(null);
+                    const activeController = exportControllerRef.current;
+                    if (!activeController) {
+                        return;
+                    }
+                    activeController.abort();
+                    setExportControllerSafely((current) => (current === activeController ? null : current));
                     if (logger.isLevelEnabled("debug")) logger.debug("Export cancelled");
                 },
             },
@@ -1421,17 +1893,26 @@ export const DataTable = forwardRef<DataTableApi<any>, DataTableProps<any>>(func
         initialStateConfig,
         enablePagination,
         idKey,
-        onDataStateChange,
-        fetchData,
+        triggerRefresh,
+        applyDataMutation,
+        tableData,
+        selectionState,
         // export
         exportFilename,
-        onExportProgress,
+        exportChunkSize,
+        exportStrictTotalCheck,
+        exportSanitizeCSV,
         onExportComplete,
         onExportError,
+        onExportCancel,
         onServerExport,
-        exportController,
+        queuedExportCount,
         isExporting,
         dataMode,
+        handleExportProgressInternal,
+        handleExportStateChangeInternal,
+        runExportWithPolicy,
+        setExportControllerSafely,
         logger,
         resetAllAndReload,
     ]);
@@ -1571,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
@@ -1658,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}