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

package/dist/lib/data-table.js

@@ -89,7 +89,7 @@ const DEFAULT_INITIAL_STATE = {
  */
 exports.DataTable = (0, react_1.forwardRef)(function DataTable({ initialState, columns, data = [], totalRow = 0, idKey = 'id', extraFilter = null, footerFilter = null, 
 // Data management mode (MUI DataGrid style)
-dataMode = 'client', initialLoadData = true, onFetchData, onDataStateChange, 
+dataMode = 'client', initialLoadData = true, onFetchData, onRefreshData, onDataChange, onDataStateChange, 
 // Selection props
 enableRowSelection = false, enableMultiRowSelection = true, selectMode = 'page', isRowSelectable, onSelectionChange, 
 // Row click props
@@ -111,7 +111,7 @@ enablePagination = false, paginationMode = 'client',
 // Filtering props
 enableGlobalFilter = true, enableColumnFilter = false, filterMode = 'client', 
 // Sorting props
-enableSorting = true, sortingMode = 'client', onSortingChange, exportFilename = 'export', onExportProgress, onExportComplete, onExportError, onServerExport, onExportCancel, 
+enableSorting = true, sortingMode = 'client', onSortingChange, exportFilename = 'export', exportConcurrency = 'cancelAndRestart', exportChunkSize = 1000, exportStrictTotalCheck = false, exportSanitizeCSV = true, onExportProgress, onExportComplete, onExportError, onServerExport, onExportCancel, onExportStateChange, 
 // Styling props
 enableHover = true, enableStripes = false, tableProps = {}, fitToScreen = true, tableSize: initialTableSize = 'medium', 
 // Sticky header/footer props
@@ -119,7 +119,7 @@ enableStickyHeaderOrFooter = false, maxHeight = '400px',
 // Virtualization props
 enableVirtualization = false, estimateRowHeight = 52, 
 // Toolbar props
-enableTableSizeControl = true, enableExport = false, enableReset = true, 
+enableTableSizeControl = true, enableExport = false, enableReset = true, enableRefresh = false, 
 // Loading and empty states
 loading = false, emptyMessage = 'No data available', skeletonRows = 5, 
 // Column filters props
@@ -184,14 +184,24 @@ logging, }, ref) {
     const [serverData, setServerData] = (0, react_1.useState)(null);
     const [serverTotal, setServerTotal] = (0, react_1.useState)(0);
     const [exportController, setExportController] = (0, react_1.useState)(null);
+    const [exportProgress, setExportProgress] = (0, react_1.useState)({});
+    const [exportPhase, setExportPhase] = (0, react_1.useState)(null);
+    const [queuedExportCount, setQueuedExportCount] = (0, react_1.useState)(0);
     // -------------------------------
     // Ref hooks (grouped together)
     // -------------------------------
     const tableContainerRef = (0, react_1.useRef)(null);
     const internalApiRef = (0, react_1.useRef)(null);
+    const exportControllerRef = (0, react_1.useRef)(null);
+    const exportQueueRef = (0, react_1.useRef)(Promise.resolve());
+    const isExternallyControlledData = (0, react_1.useMemo)(() => !onFetchData && (!!onDataChange || !!onRefreshData), [onFetchData, onDataChange, onRefreshData]);
     const { debouncedFetch, isLoading: fetchLoading } = (0, debounced_fetch_utils_1.useDebouncedFetch)(onFetchData);
-    const tableData = (0, react_1.useMemo)(() => serverData ? serverData : data, [serverData, data]);
-    const tableTotalRow = (0, react_1.useMemo)(() => serverData ? serverTotal : totalRow || data.length, [serverData, serverTotal, totalRow, data]);
+    const tableData = (0, react_1.useMemo)(() => {
+        if (isExternallyControlledData)
+            return data;
+        return serverData !== null ? serverData : data;
+    }, [isExternallyControlledData, serverData, data]);
+    const tableTotalRow = (0, react_1.useMemo)(() => (isExternallyControlledData ? (totalRow || data.length) : (serverData !== null ? serverTotal : totalRow || data.length)), [isExternallyControlledData, serverData, serverTotal, totalRow, data]);
     const tableLoading = (0, react_1.useMemo)(() => onFetchData ? (loading || fetchLoading) : loading, [onFetchData, loading, fetchLoading]);
     const enhancedColumns = (0, react_1.useMemo)(() => {
         let columnsMap = [...columns];
@@ -239,7 +249,7 @@ logging, }, ref) {
     // Callback hooks (grouped together)
     // -------------------------------
     const fetchData = (0, react_1.useCallback)(async (overrides = {}, options) => {
-        var _a, _b;
+        var _a, _b, _c, _d, _e;
         if (!onFetchData) {
             if (logger.isLevelEnabled('debug')) {
                 logger.debug('onFetchData not provided, skipping fetch', { overrides, columnFilter, sorting, pagination });
@@ -254,17 +264,25 @@ logging, }, ref) {
             ...overrides,
         };
         if (logger.isLevelEnabled('info')) {
-            logger.info('Requesting data', { filters });
+            logger.info('Requesting data', {
+                filters,
+                reason: (_a = options === null || options === void 0 ? void 0 : options.meta) === null || _a === void 0 ? void 0 : _a.reason,
+                force: (_b = options === null || options === void 0 ? void 0 : options.meta) === null || _b === void 0 ? void 0 : _b.force,
+            });
         }
         try {
-            const result = await debouncedFetch(filters, options === undefined ? 0 : options.delay || 300);
+            const delay = (_c = options === null || options === void 0 ? void 0 : options.delay) !== null && _c !== void 0 ? _c : 300; // respects 0
+            const result = await debouncedFetch(filters, {
+                debounceDelay: delay,
+                meta: options === null || options === void 0 ? void 0 : options.meta,
+            });
             if (logger.isLevelEnabled('info')) {
                 logger.info('Fetch resolved', {
-                    rows: (_b = (_a = result === null || result === void 0 ? void 0 : result.data) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0,
+                    rows: (_e = (_d = result === null || result === void 0 ? void 0 : result.data) === null || _d === void 0 ? void 0 : _d.length) !== null && _e !== void 0 ? _e : 0,
                     total: result === null || result === void 0 ? void 0 : result.total,
                 });
             }
-            if ((result === null || result === void 0 ? void 0 : result.data) && (result === null || result === void 0 ? void 0 : result.total) !== undefined) {
+            if (result && Array.isArray(result.data) && result.total !== undefined) {
                 setServerData(result.data);
                 setServerTotal(result.total);
             }
@@ -286,67 +304,35 @@ logging, }, ref) {
         debouncedFetch,
         logger,
     ]);
-    const tableStateChange = (0, react_1.useCallback)((overrides = {}) => {
-        if (!onDataStateChange) {
-            if (logger.isLevelEnabled('debug')) {
-                logger.debug('No onDataStateChange handler registered; skipping state update notification', { overrides });
-            }
-            return;
+    const normalizeRefreshOptions = (0, react_1.useCallback)((options, fallbackReason = 'refresh') => {
+        var _a, _b, _c;
+        if (typeof options === 'boolean') {
+            return {
+                resetPagination: options,
+                force: false,
+                reason: fallbackReason,
+            };
         }
-        const currentState = {
-            globalFilter,
-            columnFilter,
-            sorting,
-            pagination,
-            columnOrder,
-            columnPinning,
-            columnVisibility,
-            columnSizing,
-            ...overrides,
+        return {
+            resetPagination: (_a = options === null || options === void 0 ? void 0 : options.resetPagination) !== null && _a !== void 0 ? _a : false,
+            force: (_b = options === null || options === void 0 ? void 0 : options.force) !== null && _b !== void 0 ? _b : false,
+            reason: (_c = options === null || options === void 0 ? void 0 : options.reason) !== null && _c !== void 0 ? _c : fallbackReason,
         };
-        if (logger.isLevelEnabled('debug')) {
-            logger.debug('Emitting tableStateChange', currentState);
-        }
-        onDataStateChange === null || onDataStateChange === void 0 ? void 0 : onDataStateChange(currentState);
-    }, [
-        onDataStateChange,
-        globalFilter,
-        columnFilter,
-        sorting,
-        pagination,
-        columnOrder,
-        columnPinning,
-        columnVisibility,
-        columnSizing,
-        logger,
-    ]);
+    }, []);
     const handleSelectionStateChange = (0, react_1.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 === null || onSelectionChange === void 0 ? void 0 : onSelectionChange(next);
+            return next;
         });
-    }, [onSelectionChange, onDataStateChange, tableStateChange]);
+    }, [onSelectionChange]);
     const handleColumnFilterStateChange = (0, react_1.useCallback)((filterState) => {
         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 === null || onColumnFiltersChange === void 0 ? void 0 : onColumnFiltersChange(filterState);
+        return filterState;
+    }, [onColumnFiltersChange]);
     const resetPageToFirst = (0, react_1.useCallback)(() => {
         if (logger.isLevelEnabled('info')) {
             logger.info('Resetting to first page due to state change', {
@@ -360,40 +346,17 @@ logging, }, ref) {
         return newPagination;
     }, [pagination, logger, onPaginationChange]);
     const handleSortingChange = (0, react_1.useCallback)((updaterOrValue) => {
-        let newSorting = typeof updaterOrValue === 'function'
-            ? updaterOrValue(sorting)
-            : updaterOrValue;
-        newSorting = newSorting.filter((sort) => sort.id);
-        setSorting(newSorting);
-        onSortingChange === null || onSortingChange === void 0 ? void 0 : onSortingChange(newSorting);
-        if (logger.isLevelEnabled('debug')) {
-            logger.debug('Sorting change applied', {
-                sorting: newSorting,
-                serverMode: isServerMode,
-                serverSorting: isServerSorting,
-            });
-        }
-        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) => s === null || s === void 0 ? void 0 : s.id);
+            onSortingChange === null || onSortingChange === void 0 ? void 0 : 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 = (0, react_1.useCallback)((updatedColumnOrder) => {
         const newColumnOrder = typeof updatedColumnOrder === 'function'
             ? updatedColumnOrder(columnOrder)
@@ -403,131 +366,52 @@ logging, }, ref) {
             onColumnDragEnd(newColumnOrder);
         }
     }, [onColumnDragEnd, columnOrder]);
-    const handleColumnPinningChange = (0, react_1.useCallback)((updatedColumnPinning) => {
-        const newColumnPinning = typeof updatedColumnPinning === 'function'
-            ? updatedColumnPinning(columnPinning)
-            : updatedColumnPinning;
-        setColumnPinning(newColumnPinning);
-        if (onColumnPinningChange) {
-            onColumnPinningChange(newColumnPinning);
-        }
-    }, [onColumnPinningChange, columnPinning]);
+    const handleColumnPinningChange = (0, react_1.useCallback)((updater) => {
+        setColumnPinning((prev) => {
+            const next = typeof updater === "function" ? updater(prev) : updater;
+            // keep direct callback here (optional)
+            onColumnPinningChange === null || onColumnPinningChange === void 0 ? void 0 : onColumnPinningChange(next);
+            return next;
+        });
+    }, [onColumnPinningChange]);
     // Column visibility change handler - same pattern as column order
     const handleColumnVisibilityChange = (0, react_1.useCallback)((updater) => {
-        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 === null || onColumnVisibilityChange === void 0 ? void 0 : onColumnVisibilityChange(next);
+            return next;
+        });
+    }, [onColumnVisibilityChange]);
     // Column sizing change handler - same pattern as column order
     const handleColumnSizingChange = (0, react_1.useCallback)((updater) => {
-        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 === null || onColumnSizingChange === void 0 ? void 0 : onColumnSizingChange(next);
+            return next;
+        });
+    }, [onColumnSizingChange]);
     const handlePaginationChange = (0, react_1.useCallback)((updater) => {
-        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 === null || onPaginationChange === void 0 ? void 0 : 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 === null || onPaginationChange === void 0 ? void 0 : onPaginationChange(next);
+            if (isServerMode || isServerPagination) {
+                fetchData({ pagination: next }, { delay: 0 });
+            }
+            return next;
+        });
+    }, [isServerMode, isServerPagination, fetchData, onPaginationChange]);
     const handleGlobalFilterChange = (0, react_1.useCallback)((updaterOrValue) => {
-        const newFilter = typeof updaterOrValue === 'function'
-            ? updaterOrValue(globalFilter)
-            : updaterOrValue;
-        setGlobalFilter(newFilter);
-        if (logger.isLevelEnabled('debug')) {
-            logger.debug('Global filter change applied', {
-                value: newFilter,
-                serverMode: isServerMode,
-                serverFiltering: isServerFiltering,
-            });
-        }
-        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 === null || onGlobalFilterChange === void 0 ? void 0 : onGlobalFilterChange(newFilter);
-    }, [globalFilter, logger, isServerMode, isServerFiltering, onDataStateChange, onGlobalFilterChange, resetPageToFirst, tableStateChange, fetchData]);
+        setGlobalFilter((prev) => {
+            const next = typeof updaterOrValue === 'function' ? updaterOrValue(prev) : updaterOrValue;
+            onGlobalFilterChange === null || onGlobalFilterChange === void 0 ? void 0 : onGlobalFilterChange(next);
+            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 = (0, react_1.useCallback)((updater) => {
         const currentState = columnFilter;
         const newState = typeof updater === 'function'
@@ -544,22 +428,13 @@ logging, }, ref) {
     const onColumnFilterApplyHandler = (0, react_1.useCallback)((appliedState) => {
         const pagination = resetPageToFirst();
         if (isServerFiltering) {
-            tableStateChange({
-                columnFilter: appliedState,
-                pagination,
-            });
             fetchData({
                 columnFilter: appliedState,
                 pagination,
             });
         }
-        else if (onDataStateChange) {
-            setTimeout(() => tableStateChange({ columnFilter: appliedState, pagination }), 0);
-        }
-        setTimeout(() => {
-            onColumnFiltersChange === null || onColumnFiltersChange === void 0 ? void 0 : onColumnFiltersChange(appliedState);
-        }, 0);
-    }, [resetPageToFirst, isServerFiltering, onDataStateChange, tableStateChange, fetchData, onColumnFiltersChange]);
+        onColumnFiltersChange === null || onColumnFiltersChange === void 0 ? void 0 : onColumnFiltersChange(appliedState);
+    }, [resetPageToFirst, isServerFiltering, fetchData, onColumnFiltersChange]);
     // -------------------------------
     // Table creation (after callbacks/memo)
     // -------------------------------
@@ -681,12 +556,21 @@ logging, }, ref) {
     // -------------------------------
     // Effects (after callbacks)
     // -------------------------------
+    (0, react_1.useEffect)(() => {
+        if (!isExternallyControlledData || serverData === null)
+            return;
+        setServerData(null);
+        setServerTotal(0);
+    }, [isExternallyControlledData, serverData]);
     (0, react_1.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', {
@@ -710,502 +594,739 @@ logging, }, ref) {
             setColumnOrder(initialOrder);
         }
     }, [enableColumnDragging, enhancedColumns, columnOrder.length]);
-    const dataTableApi = (0, react_1.useMemo)(() => ({
-        table: {
-            getTable: () => table,
-        },
-        // Column Management
-        columnVisibility: {
-            showColumn: (columnId) => {
-                var _a;
-                (_a = table.getColumn(columnId)) === null || _a === void 0 ? void 0 : _a.toggleVisibility(true);
-            },
-            hideColumn: (columnId) => {
-                var _a;
-                (_a = table.getColumn(columnId)) === null || _a === void 0 ? void 0 : _a.toggleVisibility(false);
-            },
-            toggleColumn: (columnId) => {
-                var _a;
-                (_a = table.getColumn(columnId)) === null || _a === void 0 ? void 0 : _a.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);
-            },
-        },
-        // Column Ordering
-        columnOrdering: {
-            setColumnOrder: (columnOrder) => {
-                table.setColumnOrder(columnOrder);
-            },
-            moveColumn: (columnId, toIndex) => {
-                const currentOrder = table.getState().columnOrder || [];
-                const currentIndex = currentOrder.indexOf(columnId);
-                if (currentIndex === -1)
-                    return;
-                const newOrder = [...currentOrder];
-                newOrder.splice(currentIndex, 1);
-                newOrder.splice(toIndex, 0, columnId);
-                table.setColumnOrder(newOrder);
-            },
-            resetColumnOrder: () => {
-                const initialOrder = enhancedColumns.map((col, index) => {
-                    if (col.id)
-                        return col.id;
-                    const anyCol = col;
-                    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);
-            },
-        },
-        // Column Pinning
-        columnPinning: {
-            pinColumnLeft: (columnId) => {
-                const currentPinning = table.getState().columnPinning;
-                const newPinning = { ...currentPinning };
-                // 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];
-                table.setColumnPinning(newPinning);
-            },
-            pinColumnRight: (columnId) => {
-                const currentPinning = table.getState().columnPinning;
-                const newPinning = { ...currentPinning };
-                // 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) => {
-                const currentPinning = table.getState().columnPinning;
-                const newPinning = {
-                    left: (currentPinning.left || []).filter(id => id !== columnId),
-                    right: (currentPinning.right || []).filter(id => id !== columnId),
-                };
-                table.setColumnPinning(newPinning);
-            },
-            setPinning: (pinning) => {
-                table.setColumnPinning(pinning);
-            },
-            resetColumnPinning: () => {
-                const initialPinning = initialStateConfig.columnPinning || { left: [], right: [] };
-                table.setColumnPinning(initialPinning);
-                // Manually trigger handler to ensure callbacks are called
-                handleColumnPinningChange(initialPinning);
-            },
-        },
-        // Column Resizing
-        columnResizing: {
-            resizeColumn: (columnId, width) => {
-                // Use table's setColumnSizing method
-                const currentSizing = table.getState().columnSizing;
-                table.setColumnSizing({
-                    ...currentSizing,
-                    [columnId]: width,
-                });
-            },
-            autoSizeColumn: (columnId) => {
-                var _a;
-                // TanStack doesn't have built-in auto-size, so reset to default
-                (_a = table.getColumn(columnId)) === null || _a === void 0 ? void 0 : _a.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);
-            },
-        },
-        // Filtering
-        filtering: {
-            setGlobalFilter: (filter) => {
-                table.setGlobalFilter(filter);
-            },
-            clearGlobalFilter: () => {
-                table.setGlobalFilter('');
-            },
-            setColumnFilters: (filters) => {
-                handleColumnFilterStateChange(filters);
-            },
-            addColumnFilter: (columnId, operator, value) => {
-                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) => {
-                const columnFilter = table.getState().columnFilter;
-                const currentFilters = columnFilter.filters || [];
-                const newFilters = currentFilters.filter((f) => 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',
+    const lastSentRef = (0, react_1.useRef)("");
+    const emitTableState = (0, react_1.useCallback)(() => {
+        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: liveColumnFilter,
+            columnVisibility: live.columnVisibility,
+            columnSizing: live.columnSizing,
+            columnOrder: live.columnOrder,
+            columnPinning: live.columnPinning,
+        };
+        const key = JSON.stringify(payload);
+        if (key === lastSentRef.current)
+            return;
+        lastSentRef.current = key;
+        onDataStateChange(payload);
+    }, [onDataStateChange, table]);
+    (0, react_1.useEffect)(() => {
+        emitTableState();
+    }, [
+        emitTableState,
+        sorting,
+        pagination,
+        globalFilter,
+        columnFilter,
+        columnVisibility,
+        columnSizing,
+        columnOrder,
+        columnPinning,
+    ]);
+    const getResetState = (0, react_1.useCallback)(() => {
+        var _a;
+        const resetSorting = initialStateConfig.sorting || [];
+        const resetGlobalFilter = (_a = initialStateConfig.globalFilter) !== null && _a !== void 0 ? _a : '';
+        const resetColumnFilter = initialStateConfig.columnFilter;
+        const resetPagination = enablePagination
+            ? (initialStateConfig.pagination || { pageIndex: 0, pageSize: 10 })
+            : undefined;
+        return {
+            sorting: resetSorting,
+            globalFilter: resetGlobalFilter,
+            columnFilter: resetColumnFilter,
+            ...(resetPagination ? { pagination: resetPagination } : {}),
+        };
+    }, [initialStateConfig, enablePagination]);
+    const applyDataMutation = (0, react_1.useCallback)((action, updater, details = {}) => {
+        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 === null || onDataChange === void 0 ? void 0 : 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 = (0, react_1.useCallback)((options, paginationOverride) => {
+        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 = (0, react_1.useCallback)(async (options, fallbackReason = '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 === null || onPaginationChange === void 0 ? void 0 : 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 = (0, react_1.useCallback)(() => {
+        var _a;
+        const resetState = getResetState();
+        setSorting(resetState.sorting || []);
+        setGlobalFilter((_a = resetState.globalFilter) !== null && _a !== void 0 ? _a : '');
+        setColumnFilter(resetState.columnFilter);
+        if (resetState.pagination) {
+            setPagination(resetState.pagination);
+            onPaginationChange === null || onPaginationChange === void 0 ? void 0 : 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 = (0, react_1.useCallback)((value) => {
+        setExportController((current) => {
+            const next = typeof value === 'function' ? value(current) : value;
+            exportControllerRef.current = next;
+            return next;
+        });
+    }, []);
+    const handleExportProgressInternal = (0, react_1.useCallback)((progress) => {
+        setExportProgress(progress || {});
+        onExportProgress === null || onExportProgress === void 0 ? void 0 : onExportProgress(progress);
+    }, [onExportProgress]);
+    const handleExportStateChangeInternal = (0, react_1.useCallback)((state) => {
+        setExportPhase(state.phase);
+        if (state.processedRows !== undefined
+            || state.totalRows !== undefined
+            || state.percentage !== undefined) {
+            setExportProgress({
+                processedRows: state.processedRows,
+                totalRows: state.totalRows,
+                percentage: state.percentage,
+            });
+        }
+        onExportStateChange === null || onExportStateChange === void 0 ? void 0 : onExportStateChange(state);
+    }, [onExportStateChange]);
+    const runExportWithPolicy = (0, react_1.useCallback)(async (options) => {
+        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 () => {
+                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(),
                 });
-            },
-            resetFilters: () => {
-                handleColumnFilterStateChange({
-                    filters: [],
-                    logic: 'AND',
-                    pendingFilters: [],
-                    pendingLogic: 'AND',
+                onExportError === null || onExportError === void 0 ? void 0 : onExportError({
+                    message: 'An export is already running',
+                    code: 'EXPORT_IN_PROGRESS',
                 });
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Resetting filters');
-                }
-            },
-        },
-        // Sorting
-        sorting: {
-            setSorting: (sortingState) => {
-                table.setSorting(sortingState);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Setting sorting`, sortingState);
-                }
-            },
-            sortColumn: (columnId, direction) => {
-                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);
-            },
-        },
-        // Pagination
-        pagination: {
-            goToPage: (pageIndex) => {
-                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');
-                }
-            },
-            setPageSize: (pageSize) => {
-                table.setPageSize(pageSize);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Setting page size to ${pageSize}`);
-                }
-            },
-            goToFirstPage: () => {
-                table.setPageIndex(0);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Going to first page');
-                }
-            },
-            goToLastPage: () => {
-                const pageCount = table.getPageCount();
-                if (pageCount > 0) {
-                    table.setPageIndex(pageCount - 1);
-                    if (logger.isLevelEnabled('debug')) {
-                        logger.debug(`Going to last page ${pageCount - 1}`);
+                return;
+            }
+            if (exportConcurrency === 'cancelAndRestart') {
+                activeController.abort();
+            }
+        }
+        await startExecution();
+    }, [
+        exportConcurrency,
+        handleExportStateChangeInternal,
+        onExportError,
+        setExportControllerSafely,
+    ]);
+    const dataTableApi = (0, react_1.useMemo)(() => {
+        // helpers (avoid repeating boilerplate)
+        const buildInitialOrder = () => enhancedColumns.map((col, index) => {
+            if (col.id)
+                return col.id;
+            const anyCol = col;
+            if (anyCol.accessorKey && typeof anyCol.accessorKey === "string")
+                return anyCol.accessorKey;
+            return `column_${index}`;
+        });
+        const applyColumnOrder = (next) => {
+            // handleColumnOrderChange supports both Updater<ColumnOrderState> and array in your impl
+            handleColumnOrderChange(next);
+        };
+        const applyPinning = (next) => {
+            handleColumnPinningChange(next);
+        };
+        const applyVisibility = (next) => {
+            handleColumnVisibilityChange(next);
+        };
+        const applySizing = (next) => {
+            handleColumnSizingChange(next);
+        };
+        const applyPagination = (next) => {
+            handlePaginationChange(next);
+        };
+        const applySorting = (next) => {
+            handleSortingChange(next);
+        };
+        const applyGlobalFilter = (next) => {
+            handleGlobalFilterChange(next);
+        };
+        const getRowIndexById = (rowsToSearch, rowId) => rowsToSearch.findIndex((row, index) => String((0, utils_1.generateRowId)(row, index, idKey)) === rowId);
+        const clampInsertIndex = (rowsToMutate, insertIndex) => {
+            if (insertIndex === undefined)
+                return rowsToMutate.length;
+            return Math.max(0, Math.min(insertIndex, rowsToMutate.length));
+        };
+        return {
+            table: {
+                getTable: () => table,
+            },
+            // -------------------------------
+            // Column Management
+            // -------------------------------
+            columnVisibility: {
+                showColumn: (columnId) => {
+                    applyVisibility({ ...table.getState().columnVisibility, [columnId]: true });
+                },
+                hideColumn: (columnId) => {
+                    applyVisibility({ ...table.getState().columnVisibility, [columnId]: false });
+                },
+                toggleColumn: (columnId) => {
+                    var _a, _b;
+                    const curr = (_b = (_a = table.getState().columnVisibility) === null || _a === void 0 ? void 0 : _a[columnId]) !== null && _b !== void 0 ? _b : true;
+                    applyVisibility({ ...table.getState().columnVisibility, [columnId]: !curr });
+                },
+                showAllColumns: () => {
+                    // set all known columns true
+                    const all = {};
+                    table.getAllLeafColumns().forEach((c) => (all[c.id] = true));
+                    applyVisibility(all);
+                },
+                hideAllColumns: () => {
+                    const all = {};
+                    table.getAllLeafColumns().forEach((c) => (all[c.id] = false));
+                    applyVisibility(all);
+                },
+                resetColumnVisibility: () => {
+                    const initialVisibility = initialStateConfig.columnVisibility || {};
+                    applyVisibility(initialVisibility);
+                },
+            },
+            // -------------------------------
+            // Column Ordering
+            // -------------------------------
+            columnOrdering: {
+                setColumnOrder: (nextOrder) => {
+                    applyColumnOrder(nextOrder);
+                },
+                moveColumn: (columnId, toIndex) => {
+                    var _a;
+                    const currentOrder = (((_a = table.getState().columnOrder) === null || _a === void 0 ? void 0 : _a.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) => {
+                    const current = table.getState().columnPinning || { left: [], right: [] };
+                    const next = {
+                        left: [...(current.left || []).filter((id) => id !== columnId), columnId],
+                        right: (current.right || []).filter((id) => id !== columnId),
+                    };
+                    applyPinning(next);
+                },
+                pinColumnRight: (columnId) => {
+                    const current = table.getState().columnPinning || { left: [], right: [] };
+                    const next = {
+                        left: (current.left || []).filter((id) => id !== columnId),
+                        // keep your "prepend" behavior
+                        right: [columnId, ...(current.right || []).filter((id) => id !== columnId)],
+                    };
+                    applyPinning(next);
+                },
+                unpinColumn: (columnId) => {
+                    const current = table.getState().columnPinning || { left: [], right: [] };
+                    const next = {
+                        left: (current.left || []).filter((id) => id !== columnId),
+                        right: (current.right || []).filter((id) => id !== columnId),
+                    };
+                    applyPinning(next);
+                },
+                setPinning: (pinning) => {
+                    applyPinning(pinning);
+                },
+                resetColumnPinning: () => {
+                    const initialPinning = initialStateConfig.columnPinning || { left: [], right: [] };
+                    applyPinning(initialPinning);
+                },
+            },
+            // -------------------------------
+            // Column Resizing
+            // -------------------------------
+            columnResizing: {
+                resizeColumn: (columnId, width) => {
+                    const currentSizing = table.getState().columnSizing || {};
+                    applySizing({ ...currentSizing, [columnId]: width });
+                },
+                autoSizeColumn: (columnId) => {
+                    // 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) => {
+                    applyGlobalFilter(filter);
+                },
+                clearGlobalFilter: () => {
+                    applyGlobalFilter("");
+                },
+                setColumnFilters: (filters) => {
+                    handleColumnFilterStateChange(filters);
+                },
+                addColumnFilter: (columnId, operator, value) => {
+                    const newFilter = {
+                        id: `filter_${Date.now()}`,
+                        columnId,
+                        operator,
+                        value,
+                    };
+                    const current = table.getState().columnFilter;
+                    const currentFilters = (current === null || current === void 0 ? void 0 : current.filters) || [];
+                    const nextFilters = [...currentFilters, newFilter];
+                    handleColumnFilterStateChange({
+                        filters: nextFilters,
+                        logic: current === null || current === void 0 ? void 0 : current.logic,
+                        pendingFilters: (current === null || current === void 0 ? void 0 : current.pendingFilters) || [],
+                        pendingLogic: (current === null || current === void 0 ? void 0 : current.pendingLogic) || "AND",
+                    });
+                    if (logger.isLevelEnabled("debug")) {
+                        logger.debug(`Adding column filter ${columnId} ${operator} ${value}`, nextFilters);
                     }
-                }
-            },
-            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) => { var _a; return (_a = table.selectRow) === null || _a === void 0 ? void 0 : _a.call(table, rowId); },
-            deselectRow: (rowId) => { var _a; return (_a = table.deselectRow) === null || _a === void 0 ? void 0 : _a.call(table, rowId); },
-            toggleRowSelection: (rowId) => { var _a; return (_a = table.toggleRowSelected) === null || _a === void 0 ? void 0 : _a.call(table, rowId); },
-            selectAll: () => { var _a; return (_a = table.selectAll) === null || _a === void 0 ? void 0 : _a.call(table); },
-            deselectAll: () => { var _a; return (_a = table.deselectAll) === null || _a === void 0 ? void 0 : _a.call(table); },
-            toggleSelectAll: () => { var _a; return (_a = table.toggleAllRowsSelected) === null || _a === void 0 ? void 0 : _a.call(table); },
-            getSelectionState: () => { var _a; return ((_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table)) || { ids: [], type: 'include' }; },
-            getSelectedRows: () => table.getSelectedRows(),
-            getSelectedCount: () => table.getSelectedCount(),
-            isRowSelected: (rowId) => table.getIsRowSelected(rowId) || false,
-        },
-        // Data Management
-        data: {
-            refresh: (resetPagination = false) => {
-                var _a, _b, _c;
-                const filters = table.getState();
-                const pagination = {
-                    pageIndex: resetPagination ? 0 : ((_a = initialStateConfig.pagination) === null || _a === void 0 ? void 0 : _a.pageIndex) || 0,
-                    pageSize: ((_b = filters.pagination) === null || _b === void 0 ? void 0 : _b.pageSize) || ((_c = initialStateConfig.pagination) === null || _c === void 0 ? void 0 : _c.pageSize) || 10,
-                };
-                const allState = table.getState();
-                setPagination(pagination);
-                onDataStateChange === null || onDataStateChange === void 0 ? void 0 : onDataStateChange({ ...allState, pagination });
-                fetchData === null || fetchData === void 0 ? void 0 : fetchData({ pagination });
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Refreshing data using Ref', { pagination, allState });
-                }
-            },
-            reload: () => {
-                const allState = table.getState();
-                onDataStateChange === null || onDataStateChange === void 0 ? void 0 : onDataStateChange(allState);
-                fetchData === null || fetchData === void 0 ? void 0 : fetchData({});
-                if (logger.isLevelEnabled('debug')) {
-                    logger.info('Reloading data', allState);
-                }
-            },
-            // Data CRUD operations
-            getAllData: () => {
-                var _a;
-                return ((_a = table.getRowModel().rows) === null || _a === void 0 ? void 0 : _a.map(row => row.original)) || [];
-            },
-            getRowData: (rowId) => {
-                var _a, _b;
-                return (_b = (_a = table.getRowModel().rows) === null || _a === void 0 ? void 0 : _a.find(row => String(row.original[idKey]) === rowId)) === null || _b === void 0 ? void 0 : _b.original;
-            },
-            getRowByIndex: (index) => {
-                var _a, _b;
-                return (_b = (_a = table.getRowModel().rows) === null || _a === void 0 ? void 0 : _a[index]) === null || _b === void 0 ? void 0 : _b.original;
-            },
-            updateRow: (rowId, updates) => {
-                var _a;
-                const newData = (_a = table.getRowModel().rows) === null || _a === void 0 ? void 0 : _a.map(row => String(row.original[idKey]) === rowId
-                    ? {
-                        ...row.original,
-                        ...updates,
+                },
+                removeColumnFilter: (filterId) => {
+                    const current = table.getState().columnFilter;
+                    const currentFilters = (current === null || current === void 0 ? void 0 : current.filters) || [];
+                    const nextFilters = currentFilters.filter((f) => f.id !== filterId);
+                    handleColumnFilterStateChange({
+                        filters: nextFilters,
+                        logic: current === null || current === void 0 ? void 0 : current.logic,
+                        pendingFilters: (current === null || current === void 0 ? void 0 : current.pendingFilters) || [],
+                        pendingLogic: (current === null || current === void 0 ? void 0 : current.pendingLogic) || "AND",
+                    });
+                    if (logger.isLevelEnabled("debug")) {
+                        logger.debug(`Removing column filter ${filterId}`, nextFilters);
                     }
-                    : row.original);
-                setServerData === null || setServerData === void 0 ? void 0 : setServerData(newData || []);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Updating row ${rowId}`, updates);
-                }
-            },
-            updateRowByIndex: (index, updates) => {
-                var _a;
-                const newData = (_a = table.getRowModel().rows) === null || _a === void 0 ? void 0 : _a.map(row => row.original);
-                if (newData === null || newData === void 0 ? void 0 : newData[index]) {
-                    newData[index] = {
-                        ...newData[index],
-                        ...updates,
-                    };
-                    setServerData(newData);
-                    if (logger.isLevelEnabled('debug')) {
-                        logger.debug(`Updating row by index ${index}`, updates);
+                },
+                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");
                     }
-                }
-            },
-            insertRow: (newRow, index) => {
-                var _a;
-                const newData = ((_a = table.getRowModel().rows) === null || _a === void 0 ? void 0 : _a.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) => {
-                var _a;
-                const newData = (_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.filter(row => String(row.original[idKey]) !== rowId);
-                setServerData === null || setServerData === void 0 ? void 0 : setServerData((newData === null || newData === void 0 ? void 0 : newData.map(row => row.original)) || []);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Deleting row ${rowId}`);
-                }
-            },
-            deleteRowByIndex: (index) => {
-                var _a;
-                const newData = (_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.map(row => row.original);
-                newData.splice(index, 1);
-                setServerData(newData);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug(`Deleting row by index ${index}`);
-                }
-            },
-            deleteSelectedRows: () => {
-                var _a, _b, _c;
-                const selectedRows = ((_a = table.getSelectedRows) === null || _a === void 0 ? void 0 : _a.call(table)) || [];
-                if (selectedRows.length === 0)
-                    return;
-                const selectedIds = new Set(selectedRows.map(row => String(row.original[idKey])));
-                const newData = (_b = (table.getRowModel().rows || [])) === null || _b === void 0 ? void 0 : _b.filter(row => !selectedIds.has(String(row.original[idKey])));
-                setServerData((newData === null || newData === void 0 ? void 0 : newData.map(row => row.original)) || []);
-                (_c = table.deselectAll) === null || _c === void 0 ? void 0 : _c.call(table);
-                if (logger.isLevelEnabled('debug')) {
-                    logger.debug('Deleting selected rows');
-                }
-            },
-            replaceAllData: (newData) => {
-                setServerData === null || setServerData === void 0 ? void 0 : setServerData(newData);
-            },
-            // Bulk operations
-            updateMultipleRows: (updates) => {
-                var _a;
-                const updateMap = new Map(updates.map(u => [u.rowId, u.data]));
-                const newData = (_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.map(row => {
-                    const rowId = String(row.original[idKey]);
-                    const updateData = updateMap.get(rowId);
-                    return updateData ? {
-                        ...row.original,
-                        ...updateData,
-                    } : row.original;
-                });
-                setServerData(newData || []);
-            },
-            insertMultipleRows: (newRows, startIndex) => {
-                var _a;
-                const newData = (_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.map(row => row.original);
-                if (startIndex !== undefined) {
-                    newData.splice(startIndex, 0, ...newRows);
-                }
-                else {
-                    newData.push(...newRows);
-                }
-                setServerData === null || setServerData === void 0 ? void 0 : setServerData(newData);
-            },
-            deleteMultipleRows: (rowIds) => {
-                var _a, _b;
-                const idsToDelete = new Set(rowIds);
-                const newData = (_b = (_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.filter(row => !idsToDelete.has(String(row.original[idKey])))) === null || _b === void 0 ? void 0 : _b.map(row => row.original);
-                setServerData(newData);
-            },
-            // Field-specific updates
-            updateField: (rowId, fieldName, value) => {
-                var _a;
-                const newData = (_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.map(row => String(row.original[idKey]) === rowId
-                    ? {
-                        ...row.original,
-                        [fieldName]: value,
+                },
+            },
+            // -------------------------------
+            // Sorting
+            // -------------------------------
+            sorting: {
+                setSorting: (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, direction) => {
+                    const current = table.getState().sorting || [];
+                    const filtered = current.filter((s) => s.id !== columnId);
+                    if (direction === false) {
+                        applySorting(filtered);
+                        return;
                     }
-                    : row.original);
-                setServerData === null || setServerData === void 0 ? void 0 : setServerData(newData);
-            },
-            updateFieldByIndex: (index, fieldName, value) => {
-                var _a;
-                const newData = (_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.map(row => row.original);
-                if (newData[index]) {
-                    newData[index] = {
-                        ...newData[index],
-                        [fieldName]: value,
-                    };
-                    setServerData === null || setServerData === void 0 ? void 0 : setServerData(newData);
-                }
-            },
-            // Data queries
-            findRows: (predicate) => {
-                var _a, _b;
-                return (_b = (_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.filter(row => predicate(row.original))) === null || _b === void 0 ? void 0 : _b.map(row => row.original);
-            },
-            findRowIndex: (predicate) => {
-                var _a;
-                return (_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.findIndex(row => predicate(row.original));
-            },
-            getDataCount: () => {
-                var _a;
-                return ((_a = (table.getRowModel().rows || [])) === null || _a === void 0 ? void 0 : _a.length) || 0;
-            },
-            getFilteredDataCount: () => {
-                return table.getFilteredRowModel().rows.length;
-            },
-        },
-        // 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 });
-                }
-                if (enableColumnPinning) {
-                    table.setColumnPinning(initialStateConfig.columnPinning || { left: [], right: [] });
-                }
-            },
-            saveLayout: () => {
-                return {
+                    applySorting([{ id: columnId, desc: direction === "desc" }, ...filtered]);
+                },
+                clearSorting: () => {
+                    applySorting([]);
+                },
+                resetSorting: () => {
+                    const initialSorting = initialStateConfig.sorting || [];
+                    applySorting(initialSorting);
+                },
+            },
+            // -------------------------------
+            // Pagination
+            // -------------------------------
+            pagination: {
+                goToPage: (pageIndex) => {
+                    applyPagination((prev) => ({ ...prev, pageIndex }));
+                    if (logger.isLevelEnabled("debug"))
+                        logger.debug(`Going to page ${pageIndex}`);
+                },
+                nextPage: () => {
+                    applyPagination((prev) => { var _a; return ({ ...prev, pageIndex: ((_a = prev === null || prev === void 0 ? void 0 : prev.pageIndex) !== null && _a !== void 0 ? _a : 0) + 1 }); });
+                    if (logger.isLevelEnabled("debug"))
+                        logger.debug("Next page");
+                },
+                previousPage: () => {
+                    applyPagination((prev) => { var _a; return ({ ...prev, pageIndex: Math.max(0, ((_a = prev === null || prev === void 0 ? void 0 : prev.pageIndex) !== null && _a !== void 0 ? _a : 0) - 1) }); });
+                    if (logger.isLevelEnabled("debug"))
+                        logger.debug("Previous page");
+                },
+                setPageSize: (pageSize) => {
+                    // usually want pageIndex reset
+                    applyPagination(() => ({ pageIndex: 0, pageSize }));
+                    if (logger.isLevelEnabled("debug"))
+                        logger.debug(`Setting page size to ${pageSize}`);
+                },
+                goToFirstPage: () => {
+                    applyPagination((prev) => ({ ...prev, pageIndex: 0 }));
+                    if (logger.isLevelEnabled("debug"))
+                        logger.debug("Going to first page");
+                },
+                goToLastPage: () => {
+                    var _a, _b;
+                    // pageCount can be derived; keep safe fallback
+                    const pageCount = (_b = (_a = table.getPageCount) === null || _a === void 0 ? void 0 : _a.call(table)) !== null && _b !== void 0 ? _b : 0;
+                    if (pageCount > 0) {
+                        applyPagination((prev) => ({ ...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) => { var _a; return (_a = table.selectRow) === null || _a === void 0 ? void 0 : _a.call(table, rowId); },
+                deselectRow: (rowId) => { var _a; return (_a = table.deselectRow) === null || _a === void 0 ? void 0 : _a.call(table, rowId); },
+                toggleRowSelection: (rowId) => { var _a; return (_a = table.toggleRowSelected) === null || _a === void 0 ? void 0 : _a.call(table, rowId); },
+                selectAll: () => { var _a; return (_a = table.selectAll) === null || _a === void 0 ? void 0 : _a.call(table); },
+                deselectAll: () => { var _a; return (_a = table.deselectAll) === null || _a === void 0 ? void 0 : _a.call(table); },
+                toggleSelectAll: () => { var _a; return (_a = table.toggleAllRowsSelected) === null || _a === void 0 ? void 0 : _a.call(table); },
+                getSelectionState: () => { var _a; return ((_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table)) || { ids: [], type: "include" }; },
+                getSelectedRows: () => table.getSelectedRows(),
+                getSelectedCount: () => table.getSelectedCount(),
+                isRowSelected: (rowId) => table.getIsRowSelected(rowId) || false,
+            },
+            // -------------------------------
+            // Data Management (kept same, but ensure state changes go through handlers)
+            // -------------------------------
+            data: {
+                refresh: (options) => {
+                    void triggerRefresh(options, 'refresh');
+                },
+                reload: (options = {}) => {
+                    var _a, _b;
+                    void triggerRefresh({
+                        ...options,
+                        resetPagination: (_a = options.resetPagination) !== null && _a !== void 0 ? _a : false,
+                        reason: (_b = options.reason) !== null && _b !== void 0 ? _b : 'reload',
+                    }, 'reload');
+                },
+                resetAll: () => resetAllAndReload(),
+                getAllData: () => [...tableData],
+                getRowData: (rowId) => {
+                    const rowIndex = getRowIndexById(tableData, rowId);
+                    return rowIndex === -1 ? undefined : tableData[rowIndex];
+                },
+                getRowByIndex: (index) => tableData[index],
+                updateRow: (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, updates) => {
+                    applyDataMutation('updateRowByIndex', (rowsToMutate) => {
+                        if (!rowsToMutate[index])
+                            return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData[index] = { ...nextData[index], ...updates };
+                        return nextData;
+                    }, { index });
+                },
+                insertRow: (newRow, index) => {
+                    applyDataMutation('insertRow', (rowsToMutate) => {
+                        const nextData = [...rowsToMutate];
+                        nextData.splice(clampInsertIndex(nextData, index), 0, newRow);
+                        return nextData;
+                    }, { index });
+                },
+                deleteRow: (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) => {
+                    applyDataMutation('deleteRowByIndex', (rowsToMutate) => {
+                        if (index < 0 || index >= rowsToMutate.length)
+                            return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData.splice(index, 1);
+                        return nextData;
+                    }, { index });
+                },
+                deleteSelectedRows: () => {
+                    var _a, _b, _c;
+                    const currentSelection = ((_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table)) || selectionState;
+                    const selectedIds = new Set((currentSelection.ids || []).map((id) => String(id)));
+                    const loadedRowIds = tableData.map((row, index) => String((0, utils_1.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: (_b = table.getSelectedCount) === null || _b === void 0 ? void 0 : _b.call(table),
+                        });
+                    }
+                    const deletableRowIdSet = new Set(deletableRowIds);
+                    applyDataMutation('deleteSelectedRows', (rowsToMutate) => rowsToMutate.filter((row, index) => !deletableRowIdSet.has(String((0, utils_1.generateRowId)(row, index, idKey)))), { rowIds: deletableRowIds });
+                    (_c = table.deselectAll) === null || _c === void 0 ? void 0 : _c.call(table);
+                },
+                replaceAllData: (newData) => {
+                    applyDataMutation('replaceAllData', () => [...newData]);
+                },
+                updateMultipleRows: (updates) => {
+                    const updateMap = new Map(updates.map((update) => [update.rowId, update.data]));
+                    applyDataMutation('updateMultipleRows', (rowsToMutate) => rowsToMutate.map((row, index) => {
+                        const currentRowId = String((0, utils_1.generateRowId)(row, index, idKey));
+                        const updateData = updateMap.get(currentRowId);
+                        return updateData ? { ...row, ...updateData } : row;
+                    }));
+                },
+                insertMultipleRows: (newRows, startIndex) => {
+                    applyDataMutation('insertMultipleRows', (rowsToMutate) => {
+                        const nextData = [...rowsToMutate];
+                        nextData.splice(clampInsertIndex(nextData, startIndex), 0, ...newRows);
+                        return nextData;
+                    }, { index: startIndex });
+                },
+                deleteMultipleRows: (rowIds) => {
+                    const idsToDelete = new Set(rowIds);
+                    applyDataMutation('deleteMultipleRows', (rowsToMutate) => rowsToMutate.filter((row, index) => !idsToDelete.has(String((0, utils_1.generateRowId)(row, index, idKey)))), { rowIds });
+                },
+                updateField: (rowId, fieldName, value) => {
+                    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, fieldName, value) => {
+                    applyDataMutation('updateFieldByIndex', (rowsToMutate) => {
+                        if (!rowsToMutate[index])
+                            return rowsToMutate;
+                        const nextData = [...rowsToMutate];
+                        nextData[index] = { ...nextData[index], [fieldName]: value };
+                        return nextData;
+                    }, { index });
+                },
+                findRows: (predicate) => tableData.filter(predicate),
+                findRowIndex: (predicate) => tableData.findIndex(predicate),
+                getDataCount: () => tableData.length,
+                getFilteredDataCount: () => table.getFilteredRowModel().rows.length,
+            },
+            // -------------------------------
+            // Layout Management
+            // -------------------------------
+            layout: {
+                resetLayout: () => {
+                    var _a;
+                    // go through handlers so controlled state updates + emit works
+                    applySizing(initialStateConfig.columnSizing || {});
+                    applyVisibility(initialStateConfig.columnVisibility || {});
+                    applySorting(initialStateConfig.sorting || []);
+                    applyGlobalFilter((_a = initialStateConfig.globalFilter) !== null && _a !== void 0 ? _a : "");
+                },
+                resetAll: () => resetAllAndReload(),
+                saveLayout: () => ({
                     columnVisibility: table.getState().columnVisibility,
                     columnSizing: table.getState().columnSizing,
                     columnOrder: table.getState().columnOrder,
@@ -1214,249 +1335,289 @@ logging, }, ref) {
                     pagination: table.getState().pagination,
                     globalFilter: table.getState().globalFilter,
                     columnFilter: table.getState().columnFilter,
-                };
-            },
-            restoreLayout: (layout) => {
-                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: () => {
-                var _a;
-                return (_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table);
-            },
-        },
-        // Simplified Export
-        export: {
-            exportCSV: async (options = {}) => {
-                var _a;
-                const { filename = exportFilename, } = options;
-                try {
-                    // Create abort controller for this export
-                    const controller = new AbortController();
-                    setExportController === null || setExportController === void 0 ? void 0 : 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 (0, utils_1.exportServerData)(table, {
-                            format: 'csv',
-                            filename,
-                            fetchData: (filters, selection) => onServerExport(filters, selection),
-                            currentFilters,
-                            selection: (_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table),
-                            onProgress: onExportProgress,
-                            onComplete: onExportComplete,
-                            onError: onExportError,
-                        });
-                    }
-                    else {
-                        // Client export - auto-detect selected rows if not specified
-                        await (0, utils_1.exportClientData)(table, {
-                            format: 'csv',
-                            filename,
-                            onProgress: onExportProgress,
-                            onComplete: onExportComplete,
-                            onError: onExportError,
-                        });
-                        if (logger.isLevelEnabled('debug')) {
-                            logger.debug('Client export CSV', filename);
+                }),
+                restoreLayout: (layout) => {
+                    if (layout.columnVisibility)
+                        applyVisibility(layout.columnVisibility);
+                    if (layout.columnSizing)
+                        applySizing(layout.columnSizing);
+                    if (layout.columnOrder)
+                        applyColumnOrder(layout.columnOrder);
+                    if (layout.columnPinning)
+                        applyPinning(layout.columnPinning);
+                    if (layout.sorting)
+                        applySorting(layout.sorting);
+                    if (layout.pagination && enablePagination)
+                        applyPagination(layout.pagination);
+                    if (layout.globalFilter !== undefined)
+                        applyGlobalFilter(layout.globalFilter);
+                    if (layout.columnFilter)
+                        handleColumnFilterStateChange(layout.columnFilter);
+                },
+            },
+            // -------------------------------
+            // Table State
+            // -------------------------------
+            state: {
+                getTableState: () => table.getState(),
+                getCurrentFilters: () => table.getState().columnFilter,
+                getCurrentSorting: () => table.getState().sorting,
+                getCurrentPagination: () => table.getState().pagination,
+                getCurrentSelection: () => { var _a; return (_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table); },
+            },
+            // -------------------------------
+            // Export (unchanged mostly)
+            // -------------------------------
+            export: {
+                exportCSV: async (options = {}) => {
+                    const { filename = exportFilename, chunkSize = exportChunkSize, strictTotalCheck = exportStrictTotalCheck, sanitizeCSV = exportSanitizeCSV, } = options;
+                    const mode = dataMode === "server" && !!onServerExport ? 'server' : 'client';
+                    await runExportWithPolicy({
+                        format: 'csv',
+                        filename,
+                        mode,
+                        execute: async (controller) => {
+                            var _a;
+                            const toStateChange = (state) => {
+                                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 === null || onExportCancel === void 0 ? void 0 : 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 (0, utils_1.exportServerData)(table, {
+                                    format: "csv",
+                                    filename,
+                                    fetchData: (filters, selection, signal) => onServerExport(filters, selection, signal),
+                                    currentFilters,
+                                    selection: (_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table),
+                                    onProgress: handleExportProgressInternal,
+                                    onComplete: onExportComplete,
+                                    onError: onExportError,
+                                    onStateChange: toStateChange,
+                                    signal: controller.signal,
+                                    chunkSize,
+                                    strictTotalCheck,
+                                    sanitizeCSV,
+                                });
+                                return;
+                            }
+                            await (0, utils_1.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) {
-                    onExportError === null || onExportError === void 0 ? void 0 : onExportError({
-                        message: error.message || 'Export failed',
-                        code: 'EXPORT_ERROR',
                     });
-                }
-                finally {
-                    setExportController === null || setExportController === void 0 ? void 0 : setExportController(null);
-                }
-            },
-            exportExcel: async (options = {}) => {
-                var _a;
-                const { filename = exportFilename } = options;
-                try {
-                    // Create abort controller for this export
-                    const controller = new AbortController();
-                    setExportController === null || setExportController === void 0 ? void 0 : 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 (0, utils_1.exportServerData)(table, {
-                            format: 'excel',
-                            filename,
-                            fetchData: (filters, selection) => onServerExport(filters, selection),
-                            currentFilters,
-                            selection: (_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table),
-                            onProgress: onExportProgress,
-                            onComplete: onExportComplete,
-                            onError: onExportError,
-                        });
-                    }
-                    else {
-                        // Client export - auto-detect selected rows if not specified
-                        await (0, utils_1.exportClientData)(table, {
-                            format: 'excel',
-                            filename,
-                            onProgress: onExportProgress,
-                            onComplete: onExportComplete,
-                            onError: onExportError,
-                        });
-                        if (logger.isLevelEnabled('debug')) {
-                            logger.debug('Client export Excel', filename);
+                },
+                exportExcel: async (options = {}) => {
+                    const { filename = exportFilename, chunkSize = exportChunkSize, strictTotalCheck = exportStrictTotalCheck, sanitizeCSV = exportSanitizeCSV, } = options;
+                    const mode = dataMode === "server" && !!onServerExport ? 'server' : 'client';
+                    await runExportWithPolicy({
+                        format: 'excel',
+                        filename,
+                        mode,
+                        execute: async (controller) => {
+                            var _a;
+                            const toStateChange = (state) => {
+                                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 === null || onExportCancel === void 0 ? void 0 : 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 (0, utils_1.exportServerData)(table, {
+                                    format: "excel",
+                                    filename,
+                                    fetchData: (filters, selection, signal) => onServerExport(filters, selection, signal),
+                                    currentFilters,
+                                    selection: (_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table),
+                                    onProgress: handleExportProgressInternal,
+                                    onComplete: onExportComplete,
+                                    onError: onExportError,
+                                    onStateChange: toStateChange,
+                                    signal: controller.signal,
+                                    chunkSize,
+                                    strictTotalCheck,
+                                    sanitizeCSV,
+                                });
+                                return;
+                            }
+                            await (0, utils_1.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) {
-                    onExportError === null || onExportError === void 0 ? void 0 : onExportError({
-                        message: error.message || 'Export failed',
-                        code: 'EXPORT_ERROR',
-                    });
-                    if (logger.isLevelEnabled('debug')) {
-                        logger.debug('Server export Excel failed', error);
-                    }
-                }
-                finally {
-                    setExportController === null || setExportController === void 0 ? void 0 : setExportController(null);
-                }
-            },
-            exportServerData: async (options) => {
-                var _a;
-                const { format, filename = exportFilename, fetchData = onServerExport, } = options;
-                if (!fetchData) {
-                    onExportError === null || onExportError === void 0 ? void 0 : 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;
-                }
-                try {
-                    // Create abort controller for this export
-                    const controller = new AbortController();
-                    setExportController === null || setExportController === void 0 ? void 0 : 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 });
+                },
+                exportServerData: async (options) => {
+                    const { format, filename = exportFilename, fetchData: fetchFn = onServerExport, chunkSize = exportChunkSize, strictTotalCheck = exportStrictTotalCheck, sanitizeCSV = exportSanitizeCSV, } = options;
+                    if (!fetchFn) {
+                        onExportError === null || onExportError === void 0 ? void 0 : 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;
                     }
-                    await (0, utils_1.exportServerData)(table, {
+                    await runExportWithPolicy({
                         format,
                         filename,
-                        fetchData: (filters, selection) => fetchData(filters, selection),
-                        currentFilters,
-                        selection: (_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table),
-                        onProgress: onExportProgress,
-                        onComplete: onExportComplete,
-                        onError: onExportError,
-                    });
-                }
-                catch (error) {
-                    onExportError === null || onExportError === void 0 ? void 0 : onExportError({
-                        message: error.message || 'Export failed',
-                        code: 'EXPORT_ERROR',
+                        mode: 'server',
+                        execute: async (controller) => {
+                            var _a;
+                            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 (0, utils_1.exportServerData)(table, {
+                                format,
+                                filename,
+                                fetchData: (filters, selection, signal) => fetchFn(filters, selection, signal),
+                                currentFilters,
+                                selection: (_a = table.getSelectionState) === null || _a === void 0 ? void 0 : _a.call(table),
+                                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 === null || onExportCancel === void 0 ? void 0 : 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 || setExportController === void 0 ? void 0 : 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 === null || exportController === void 0 ? void 0 : exportController.abort();
-                setExportController === null || setExportController === void 0 ? void 0 : 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;
     (0, react_1.useImperativeHandle)(ref, () => dataTableApi, [dataTableApi]);
@@ -1515,14 +1676,12 @@ logging, }, ref) {
     // Export cancel callback
     // -------------------------------
     const handleCancelExport = (0, react_1.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
     // -------------------------------
@@ -1539,7 +1698,12 @@ logging, }, ref) {
     // -------------------------------
     return ((0, jsx_runtime_1.jsx)(data_table_context_1.DataTableProvider, { table: table, apiRef: internalApiRef, dataMode: dataMode, tableSize: tableSize, onTableSizeChange: (size) => {
             setTableSize(size);
-        }, columnFilter: columnFilter, onChangeColumnFilter: handleColumnFilterStateChange, slots: slots, slotProps: slotProps, isExporting: isExporting, exportController: exportController, onCancelExport: handleCancelExport, exportFilename: exportFilename, onExportProgress: onExportProgress, onExportComplete: onExportComplete, onExportError: onExportError, onServerExport: onServerExport, children: (0, jsx_runtime_1.jsxs)(RootComponent, { ...rootSlotProps, children: [(enableGlobalFilter || extraFilter) ? ((0, jsx_runtime_1.jsx)(ToolbarComponent, { extraFilter: extraFilter, enableGlobalFilter: enableGlobalFilter, enableColumnVisibility: enableColumnVisibility, enableColumnFilter: enableColumnFilter, enableExport: enableExport, enableReset: enableReset, enableTableSizeControl: enableTableSizeControl, enableColumnPinning: enableColumnPinning, ...toolbarSlotProps })) : null, enableBulkActions && enableRowSelection && isSomeRowsSelected ? ((0, jsx_runtime_1.jsx)(BulkActionsComponent, { selectionState: selectionState, selectedRowCount: selectedRowCount, bulkActions: bulkActions, sx: {
+        }, columnFilter: columnFilter, onChangeColumnFilter: handleColumnFilterStateChange, slots: slots, slotProps: slotProps, isExporting: isExporting, exportController: exportController, exportPhase: exportPhase, exportProgress: exportProgress, onCancelExport: handleCancelExport, exportFilename: exportFilename, onExportProgress: onExportProgress, onExportComplete: onExportComplete, onExportError: onExportError, onServerExport: onServerExport, children: (0, jsx_runtime_1.jsxs)(RootComponent, { ...rootSlotProps, children: [(enableGlobalFilter || extraFilter) ? ((0, jsx_runtime_1.jsx)(ToolbarComponent, { extraFilter: extraFilter, enableGlobalFilter: enableGlobalFilter, enableColumnVisibility: enableColumnVisibility, enableColumnFilter: enableColumnFilter, enableExport: enableExport, enableReset: enableReset, enableTableSizeControl: enableTableSizeControl, enableColumnPinning: enableColumnPinning, enableRefresh: enableRefresh, ...toolbarSlotProps, refreshButtonProps: {
+                        loading: tableLoading, // disable while fetching
+                        showSpinnerWhileLoading: false,
+                        onRefresh: () => { var _a, _b, _c; return (_c = (_b = (_a = internalApiRef.current) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.refresh) === null || _c === void 0 ? void 0 : _c.call(_b, true); },
+                        ...toolbarSlotProps.refreshButtonProps,
+                    } })) : null, enableBulkActions && enableRowSelection && isSomeRowsSelected ? ((0, jsx_runtime_1.jsx)(BulkActionsComponent, { selectionState: selectionState, selectedRowCount: selectedRowCount, bulkActions: bulkActions, sx: {
                         position: 'relative',
                         zIndex: 2,
                         ...bulkActionsSlotProps.sx,