@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/DataTable/components/DataTableCore.tsx

@@ -8,37 +8,23 @@
  * This is the main component that consumers will use.
  */
 
-import React, { useMemo, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { useReactTable, type SortingState } from '@tanstack/react-table';
+import React, { useMemo, useCallback } from 'react';
+import type { SortingState } from '@tanstack/react-table';
 import { useLocation } from 'react-router-dom';
-import { Edit, Trash2 } from 'lucide-react';
-import { useDataTablePerformance } from '../../../hooks/useDataTablePerformance';
-import { LoadingState } from './LoadingState';
-import { DataTableLayout } from './DataTableLayout';
-import { DataTableErrorBoundary } from './DataTableErrorBoundary';
-import { useColumnOrderPersistence } from '../hooks/useColumnOrderPersistence';
-import { useColumnVisibilityPersistence } from '../hooks/useColumnVisibilityPersistence';
-import { useDataTableState } from '../hooks/useDataTableState';
-import { useDataTableDataPipeline } from '../hooks/useDataTableDataPipeline';
-import { useServerSideDataEffect } from '../hooks/useServerSideDataEffect';
-import { useEffectiveColumnOrder } from '../hooks/useEffectiveColumnOrder';
-import { useTableHandlers, type TableStateSnapshot } from '../hooks/useTableHandlers';
-import { useDataTableConfiguration } from '../hooks/useDataTableConfiguration';
-import { AccessDeniedPage } from './AccessDeniedPage';
-// NOTE: All toast() calls in this component use the default timeout (5 seconds).
-// Do NOT set duration or timeout properties - let the toast system use its default.
-import { toast } from '../../../hooks/useToast';
+import { useIsPrint } from '../../../hooks/useIsPrint';
+import { LoadingState } from '../ui/table/LoadingState';
+import { DataTableLayout } from '../ui/layout/DataTableLayout';
+import { DataTableErrorBoundary } from '../ui/layout/DataTableErrorBoundary';
+import { useDataTableDeletionBatching } from '../hooks/useDataTableDeletionBatching';
+import { useDataTableStateAndPersistence } from '../hooks/useDataTableStateAndPersistence';
+import { useDataTablePipeline } from '../hooks/useDataTablePipeline';
+import { useDataTableRenderGuard } from '../hooks/useDataTableRenderGuard';
+import { AccessDeniedPage } from '../ui/shared/AccessDeniedPage';
 import { useUnifiedAuth } from '../../../providers/services/UnifiedAuthProvider';
 import { useDataTablePermissions } from '../hooks/useDataTablePermissions';
-import { useTableColumns } from '../hooks/useTableColumns';
-import { initializeLiveRegion } from '../utils/a11yUtils';
-import { useKeyboardNavigation } from '../hooks/useKeyboardNavigation';
 import { getRowIdSafe } from '../utils/rowUtils';
 import { createLogger } from '../../../utils/core/logger';
-import { usePermissionTracking } from './hooks/usePermissionTracking';
-import { useImportModalFocus } from './hooks/useImportModalFocus';
-import { toCellValueRecord } from './cellValueUtils';
-
+import { usePermissionTracking } from '../hooks/usePermissionTracking';
 import {
   normalizeDataTableFeatures,
   type DataRecord,
@@ -106,7 +92,7 @@ export interface DataTableCoreProps<TData extends DataRecord> {
   onEditRow?: (row: TData, data: Partial<TData>) => void;
   onDeleteRow?: (row: TData) => void;
   onCreateRow?: (data: Partial<TData>) => void;
-  onImport?: (data: TData[]) => void | Promise<void>;
+  onImport?: (data: TData[]) => import('../ui/modals/importModalPersistence').ImportHandlerResult;
   onExport?: (options: import('../types').ExportOptions<TData>) => void | Promise<void>;
   onRowSelectionChange?: (selection: Record<string, boolean>) => void;
   selection?: Record<string, boolean>;
@@ -118,6 +104,8 @@ export interface DataTableCoreProps<TData extends DataRecord> {
   emptyState?: EmptyStateConfig | React.ReactElement;
   aggregates?: AggregateConfig[];
   importModalConfig?: ImportModalConfig;
+  /** Called when the import modal is closed (e.g. to refetch table data). */
+  onImportModalClose?: () => void;
   actions?: DataTableAction<TData>[];
   columnOrder?: string[];
   
@@ -170,6 +158,7 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
     emptyState,
     aggregates = [],
     importModalConfig,
+    onImportModalClose,
     actions = [],
     columnOrder: externalColumnOrder,
     defaultGrouping,
@@ -180,85 +169,26 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
   } = props;
   
   const logger = createLogger('DataTableCore');
-  
-  // Track deletion state to batch updates and prevent flashing
-  const [isDeleting, setIsDeleting] = useState(false);
-  const deletionTimeoutRef = useRef<NodeJS.Timeout | null>(null);
-  const pendingDeletionsRef = useRef<Set<string>>(new Set());
-  const dataSnapshotRef = useRef<TData[]>(data);
-  const dataChangeCountRef = useRef(0);
-  const previousDataLengthRef = useRef(data.length);
-  
-  // CRITICAL: Use useLayoutEffect to capture previous length synchronously
-  // This runs before paint, so we can detect changes before React commits
-  useLayoutEffect(() => {
-    const currentLength = data.length;
-    const previousLength = previousDataLengthRef.current;
-    
-    // Check if length decreased - this is the key detection
-    const lengthDecreased = currentLength < previousLength;
-    
-    if (lengthDecreased && !isDeleting) {
-      // Data length decreased - start deletion batching
-      const snapshotLength = dataSnapshotRef.current.length;
-      
-      // Data decrease detected (logging removed for performance)
-      
-      // If snapshot is larger, it's valid (has pre-deletion state)
-      // Otherwise, update it to preserve current state
-      if (snapshotLength <= currentLength) {
-        dataSnapshotRef.current = [...data];
-      }
-      
-      setIsDeleting(true);
-      
-      // Set timeout to reset after batching
-      if (deletionTimeoutRef.current) {
-        clearTimeout(deletionTimeoutRef.current);
-      }
-      deletionTimeoutRef.current = setTimeout(() => {
-        setIsDeleting(false);
-        dataSnapshotRef.current = data;
-        previousDataLengthRef.current = data.length;
-        // Batching complete (logging removed for performance)
-      }, 150);
-      
-      // Update previous length AFTER setting up batching
-      previousDataLengthRef.current = currentLength;
-    } else if (!lengthDecreased && !isDeleting) {
-      // No deletion - update snapshot and previous length normally
-      dataSnapshotRef.current = data;
-      previousDataLengthRef.current = currentLength;
-    } else if (isDeleting) {
-      // Already deleting - just update previous length for next comparison
-      previousDataLengthRef.current = currentLength;
-    }
-  }, [data, isDeleting]);
-  
-  // Keep data snapshot stable during deletions to prevent flashing
-  // Logging effect - runs after layout to show what happened
-  useEffect(() => {
-    dataChangeCountRef.current += 1;
-    
-    // Data prop changed (logging removed for performance)
-  }, [data, isDeleting]);
-  
-  // Use snapshot data during deletions to prevent flashing
-  // CRITICAL: If we're deleting and data length decreased, use snapshot to prevent flashing
-  const dataLengthChanged = data.length !== dataSnapshotRef.current.length;
-  const isDataDecreasing = data.length < dataSnapshotRef.current.length;
-  const effectiveData = (isDeleting && isDataDecreasing) ? dataSnapshotRef.current : data;
-  
-  // Effective data tracking (logging removed for performance)
-  
+
+  const { effectiveData, isDeleting, setIsDeleting, deletionRefs } =
+    useDataTableDeletionBatching<TData>(data);
+
   // ============================================================================
   // ALL HOOKS MUST BE CALLED IN THE SAME ORDER EVERY RENDER
+  // Responsibilities: useDataTableDeletionBatching (in-flight delete UI),
+  // useUnifiedAuth (user), useIsPrint (print), useDataTablePermissions (RBAC),
+  // usePermissionTracking (timeout/loading), useDataTableStateAndPersistence (state +
+  // column order/visibility), useDataTablePipeline (table instance + layout props),
+  // useDataTableRenderGuard (loading / access-denied gate).
   // ============================================================================
-  
+
   // MANDATORY: Get authenticated user - ALWAYS call this hook
   const authResult = useUnifiedAuth();
   const user = authResult.user;
 
+  // Detect print mode to disable pagination when printing
+  const isPrint = useIsPrint();
+
   const requestedFeatures = useMemo<NormalizedDataTableFeatureConfig>(() =>
     normalizeDataTableFeatures(incomingFeatures),
   [incomingFeatures]);
@@ -278,807 +208,117 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
   
   
   // ============================================================================
-  // UNIFIED STATE MANAGEMENT - Use ONLY useDataTableState for all state
+  // STATE AND PERSISTENCE - column order/visibility, core state, sync effects
   // ============================================================================
-  
-  const effectiveColumnOrder = useEffectiveColumnOrder({
+
+  const location = useLocation();
+
+  const {
+    state,
+    stateActions,
+    rowSelection,
+    effectiveColumnOrder,
+    updateSavedColumnVisibility,
+    updateColumnOrder,
+  } = useDataTableStateAndPersistence<TData>({
     columns,
     externalColumnOrder,
-    selectionEnabled: secureFeatures.selection,
-  });
-  
-  // ============================================================================
-  // COLUMN VISIBILITY PERSISTENCE - ALWAYS call these hooks
-  // ============================================================================
-  
-  const {
-    columnVisibility: savedColumnVisibility,
-    isLoaded: isColumnVisibilityLoaded,
-    updateColumnVisibility: updateSavedColumnVisibility,
-  } = useColumnVisibilityPersistence({
-    tableId: title ? `datatable-${title.toLowerCase().replace(/\s+/g, '-')}` : undefined,
-    defaultVisibility: initialColumnVisibilityProp || {},
-    enablePersistence: secureFeatures.columnVisibility,
+    title,
+    initialColumnVisibility: initialColumnVisibilityProp || {},
     storageKey,
-  });
-  
-  // Merge saved column visibility into initial state (saved visibility takes precedence over prop)
-  const initialColumnVisibility = useMemo(() => {
-    if (secureFeatures.columnVisibility && savedColumnVisibility && Object.keys(savedColumnVisibility).length > 0) {
-      return savedColumnVisibility;
-    }
-    // Fall back to prop if no saved visibility
-    return initialColumnVisibilityProp || {};
-  }, [secureFeatures.columnVisibility, savedColumnVisibility, initialColumnVisibilityProp]);
-  
-  // Get location for route-based key derivation
-  let location: { pathname: string } | null = null;
-  try {
-    // useLocation may not be available if React Router is not set up
-    const routerLocation = useLocation();
-    location = routerLocation;
-  } catch {
-    // Router not available, location will be null
-    location = null;
-  }
-
-  // Extract column field names for sensitive field filtering
-  const columnFieldNames = useMemo(() => {
-    return columns
-      .map((col) => col.accessorKey || col.id)
-      .filter((key): key is string => Boolean(key));
-  }, [columns]);
-  
-  // Use the centralized state management hook for ALL table state
-  // Note: 'actions' prop parameter is shadowed by destructuring, so we rename to stateActions
-  const { state, actions: stateActions } = useDataTableState<TData>({
+    secureFeatures: {
+      columnVisibility: secureFeatures.columnVisibility,
+      columnReordering: secureFeatures.columnReordering,
+      selection: secureFeatures.selection,
+    },
+    rbacPageId: rbac.pageId,
     initialPageSize,
-    columnIds: effectiveColumnOrder,
-    initialRowSelection: selection || {},
+    selection,
     onRowSelectionChange,
     defaultSorting: defaultSorting || [],
     defaultGrouping: defaultGrouping || [],
-    // Persistence props
-    rbacPageId: rbac.pageId,
-    title,
     location,
-    columnFieldNames,
   });
-  
-  // Apply saved visibility to state if available
-  useEffect(() => {
-    if (secureFeatures.columnVisibility && isColumnVisibilityLoaded && Object.keys(initialColumnVisibility).length > 0) {
-      stateActions.setColumnVisibility(initialColumnVisibility);
-    }
-  }, [secureFeatures.columnVisibility, isColumnVisibilityLoaded, initialColumnVisibility, stateActions]);
-  
-  // Initialize live region for accessibility announcements
-  useEffect(() => {
-    initializeLiveRegion();
-  }, []);
-  
-  // Row selection: prefer controlled prop, fall back to state
-  const rowSelection = selection !== undefined ? selection : state.rowSelection;
 
   const resolvedGetRowId = useCallback(
     (row: TData, index: number) => getRowIdSafe(row, index, getRowId),
     [getRowId]
   );
-  
-  // ============================================================================
-  // AUTO-EXPAND GROUPS WHEN DEFAULT GROUPING IS PROVIDED
-  // ============================================================================
-  
-  // Track if we've already initialized expansion state
-  const hasInitializedExpansion = useRef(false);
-  
-  // Auto-expand all groups when default grouping is provided (only once on mount)
-  useEffect(() => {
-    if (!hasInitializedExpansion.current && defaultGrouping && defaultGrouping.length > 0) {
-      stateActions.setExpanded(true); // Expand all groups
-      hasInitializedExpansion.current = true;
-    }
-  }, [defaultGrouping, stateActions]);
 
-  // Extract commonly used state values (only what's needed)
-  // Note: Most state values are accessed via state object directly when needed
-  
-  // ============================================================================
-  // PERFORMANCE HOOK - ALWAYS call this hook
-  // ============================================================================
-  
-  const performanceHook = useDataTablePerformance({
+  const pipeline = useDataTablePipeline<TData>({
     data,
+    effectiveData,
+    columns,
+    state,
+    stateActions,
+    rowSelection,
+    effectiveColumnOrder,
+    updateSavedColumnVisibility,
+    updateColumnOrder,
+    secureFeatures,
+    permissions,
+    deletionRefs,
+    isDeleting,
+    setIsDeleting,
+    onCreateRow,
+    onEditRow,
+    onDeleteRow,
+    onImport,
+    onExport,
+    onDeleteSelected,
+    actions,
+    resolvedGetRowId,
     performance,
     serverSide,
     chunking,
     searchIndex,
-  });
-
-  const {
-    paginationMode: detectedMode,
-    pageSizeOptions: optimizedPageSizeOptions,
-    isLoading: performanceLoading,
-    searchQuery,
-    setSearchQuery,
-    fetchServerData,
-    serverData,
-    cleanup,
-  } = performanceHook;
-
-  const finalPaginationMode = paginationMode || detectedMode;
-
-  // ============================================================================
-  // KEYBOARD NAVIGATION - ALWAYS call this hook
-  // ============================================================================
-  
-  const keyboardNavigation = useKeyboardNavigation(
-    data.length,
-    columns.length,
-    {
-      enabled: true,
-      announceNavigation: true,
-      supportsColumnReorder: secureFeatures.columnReordering,
-      supportsColumnResize: false, // Column resizing is not currently supported
-    }
-  );
-
-  const { lastFocusedElementRef } = useImportModalFocus(state.showImportModal, keyboardNavigation);
-
-  // ============================================================================
-  // HIERARCHICAL DATA VALIDATION AND PROCESSING - ALWAYS call these hooks
-  // ============================================================================
-  
-  const {
-    finalTableData,
-    dataCount: finalDataCount,
-    hierarchicalState,
-    hierarchicalValidation,
-  } = useDataTableDataPipeline<TData>({
-    data: effectiveData,
-    features: secureFeatures,
+    paginationMode,
+    initialPageSize,
+    externalIsLoading,
+    isPrint,
+    effectivePageId,
+    logger,
+    title,
+    description,
+    variant,
+    className,
+    emptyState,
+    virtualHeight,
     hierarchical,
-    sorting: state.sorting,
-    finalPaginationMode,
-    serverData,
-  });
-
-  useEffect(() => {
-    if (!hierarchicalValidation.isValid) {
-      logger.error('Hierarchical data validation failed:', hierarchicalValidation.errors);
-    }
-  }, [hierarchicalValidation, logger]);
-  
-  // Final table data tracking (logging removed for performance)
-
-  // Cleanup deletion timeout on unmount
-  useEffect(() => {
-    const pendingDeletions = pendingDeletionsRef.current;
-    return () => {
-      if (deletionTimeoutRef.current) {
-        clearTimeout(deletionTimeoutRef.current);
-      }
-      pendingDeletions.clear();
-    };
-  }, []);
-  
-  // Update data snapshot when data changes and we're not deleting
-  useEffect(() => {
-    if (!isDeleting && data !== dataSnapshotRef.current) {
-      dataSnapshotRef.current = data;
-    }
-  }, [data, isDeleting]);
-
-  // Cleanup deletion timeout on unmount
-  useEffect(() => {
-    return () => {
-      if (deletionTimeoutRef.current) {
-        clearTimeout(deletionTimeoutRef.current);
-      }
-    };
-  }, []);
-
-  const {
-    columnOrder: savedColumnOrder,
-    isLoaded: isColumnOrderLoaded,
-    updateColumnOrder,
-  } = useColumnOrderPersistence({
-    tableId: title ? `datatable-${title.toLowerCase().replace(/\s+/g, '-')}` : undefined,
-    defaultOrder: columns.map(col => col.id || col.accessorKey || ''),
-    enablePersistence: secureFeatures.columnReordering,
+    aggregates,
+    importModalConfig,
+    onImportModalClose,
     storageKey,
-  });
-
-  useEffect(() => {
-    if (
-      secureFeatures.columnReordering &&
-      isColumnOrderLoaded &&
-      savedColumnOrder &&
-      savedColumnOrder.length > 0
-    ) {
-      // Normalize: ensure 'select' is first if selection is enabled
-      const normalizedOrder = secureFeatures.selection && savedColumnOrder.includes('select')
-        ? ['select', ...savedColumnOrder.filter(id => id !== 'select')]
-        : savedColumnOrder;
-      stateActions.setColumnOrder(normalizedOrder);
-    }
-  }, [secureFeatures.columnReordering, secureFeatures.selection, isColumnOrderLoaded, savedColumnOrder, stateActions]);
-
-  // CRITICAL: Always ensure state.columnOrder has 'select' first if selection is enabled
-  // This fixes any state that gets out of sync (e.g., from localStorage or user reordering)
-  useEffect(() => {
-    if (secureFeatures.selection && state.columnOrder.includes('select') && state.columnOrder[0] !== 'select') {
-      const normalizedOrder = ['select', ...state.columnOrder.filter(id => id !== 'select')];
-      stateActions.setColumnOrder(normalizedOrder);
-      // Also update persisted order if persistence is enabled
-      if (secureFeatures.columnReordering) {
-        updateColumnOrder(normalizedOrder);
-      }
-    }
-  }, [secureFeatures.selection, secureFeatures.columnReordering, state.columnOrder, stateActions, updateColumnOrder]);
-
-  // ============================================================================
-  // CONFIGURATION RESOLUTION - ALWAYS call these hooks
-  // ============================================================================
-  
-  const finalPageSizeOptions = optimizedPageSizeOptions;
-  
-  const validatedInitialPageSize = useMemo(() => {
-    if (!secureFeatures.pagination || !finalPageSizeOptions.length) {
-      return initialPageSize;
-    }
-    
-    if (finalPageSizeOptions.includes(initialPageSize)) {
-      return initialPageSize;
-    }
-    
-    const sortedOptions = [...finalPageSizeOptions].sort((a, b) => a - b);
-    const closestOption = sortedOptions.reduce((prev, curr) => 
-      Math.abs(curr - initialPageSize) < Math.abs(prev - initialPageSize) ? curr : prev
-    );
-    
-    logger.warn(
-      `initialPageSize ${initialPageSize} is not available in page size options [${finalPageSizeOptions.join(', ')}]. Using closest option: ${closestOption}`
-    );
-    
-    return closestOption;
-  }, [initialPageSize, finalPageSizeOptions, secureFeatures.pagination, logger]);
-  
-  // Determine the effective pageSize to use (validated or current state)
-  // CRITICAL: This ensures we always pass a valid pageSize to TanStack Table configuration.
-  // An invalid pageSize can cause getPaginationRowModel() to return empty rows.
-  const effectivePageSize = useMemo(() => {
-    if (!secureFeatures.pagination || !finalPageSizeOptions.length) {
-      return state.pagination.pageSize;
-    }
-    
-    // If current pageSize is invalid (not in options), use validated value immediately
-    // This is a safety net in case the useEffect hasn't run yet
-    if (!finalPageSizeOptions.includes(state.pagination.pageSize)) {
-      return validatedInitialPageSize;
-    }
-    
-    return state.pagination.pageSize;
-  }, [state.pagination.pageSize, validatedInitialPageSize, secureFeatures.pagination, finalPageSizeOptions]);
-  
-  // CRITICAL FIX: Ensure pagination state always uses a valid pageSize and pageIndex
-  // An invalid pageSize (not in page size options) causes getPaginationRowModel() to return empty rows,
-  // which manifests as "DataTable shows record count but no rows" bug for large datasets.
-  // An out-of-bounds pageIndex (beyond available pages) also causes empty rows.
-  // This fixes the bug where DataTable shows record count but no rows for large datasets.
-  useEffect(() => {
-    if (secureFeatures.pagination && finalPageSizeOptions.length > 0) {
-      const needsFix = !finalPageSizeOptions.includes(state.pagination.pageSize);
-      
-      // Also check if pageIndex is out of bounds for the current data
-      const currentPageSize = effectivePageSize || validatedInitialPageSize;
-      const totalPages = currentPageSize > 0 ? Math.ceil(finalDataCount / currentPageSize) : 0;
-      const pageIndexOutOfBounds = totalPages > 0 && state.pagination.pageIndex >= totalPages;
-      
-      if (needsFix || pageIndexOutOfBounds) {
-        // PageSize is invalid OR pageIndex is out of bounds - correct both to prevent empty rows
-        stateActions.setPagination({
-          pageSize: validatedInitialPageSize,
-          pageIndex: 0, // Reset to first page when correcting pagination issues
-        });
-      }
-    }
-  }, [
-    secureFeatures.pagination, 
-    finalPageSizeOptions, 
-    state.pagination.pageSize, 
-    state.pagination.pageIndex,
-    validatedInitialPageSize, 
-    stateActions,
-    effectivePageSize,
-    finalDataCount
-  ]);
-  
-  // React 19 fix: Use useMemo to ensure isLoading updates when props change
-  // This prevents the component from getting stuck in loading state when externalIsLoading
-  // changes from true to false in React 19 with automatic memoization
-  const isLoading = useMemo(
-    () => externalIsLoading || performanceLoading,
-    [externalIsLoading, performanceLoading]
-  );
-  
-  // ============================================================================
-  // DATA PROCESSING - ALWAYS call these hooks
-  // ============================================================================
-  
-  // ============================================================================
-  // ACTIONS PROCESSING - ALWAYS call these hooks
-  // ============================================================================
-
-  // ============================================================================
-  // COLUMN PROCESSING - ALWAYS call these hooks
-  // ============================================================================
-
-  // ============================================================================
-  // TABLE CONFIGURATION - ALWAYS call these hooks
-  // ============================================================================
-
-  // ============================================================================
-  // SEARCH HANDLERS - ALWAYS call these hooks
-  // ============================================================================
-  
-  /**
-   * Handle search input changes.
-   * 
-   * When a search query is entered, we reset to the first page to show results
-   * from the beginning. This provides a better user experience when searching
-   * large datasets.
-   * 
-   * CRITICAL: Must sync both state.searchQuery (used by state management) and
-   * performance hook's searchQuery (used by table filtering and search index).
-   * 
-   * @param value - The search query string
-   */
-  const handleSearch = useCallback((value: string) => {
-    // Update both search query states to keep them in sync
-    stateActions.setSearchQuery(value);
-    setSearchQuery(value);
-    
-    // Reset to first page when searching to show results from the beginning
-    if (secureFeatures.pagination) {
-      stateActions.setPagination({ ...state.pagination, pageIndex: 0 });
-    }
-  }, [stateActions, setSearchQuery, secureFeatures.pagination, state.pagination]);
-
-  // ============================================================================
-  // SERVER-SIDE DATA FETCHING - ALWAYS call these hooks
-  // ============================================================================
-  
-  /**
-   * Handle server-side data fetching.
-   * 
-   * This function is called when any state that affects server-side data changes:
-   * - pagination (page/size)
-   * - sorting (column/sort order)
-   * - filtering (column filters or global search)
-   * - grouping
-   * 
-   * It collects all current table state and makes a single request to the server
-   * with those parameters, allowing for efficient server-side pagination, sorting,
-   * and filtering without loading all data client-side.
-   * 
-   * Early return guards prevent unnecessary server calls when:
-   * - Component is in client-side mode (finalPaginationMode !== 'server')
-   * - No server-side config is provided (!serverSide)
-   */
-  useServerSideDataEffect<TData>({
-    finalPaginationMode,
-    serverSide,
-    pagination: state.pagination,
-    sorting: state.sorting,
-    columnFilters: state.columnFilters,
-    grouping: state.grouping,
-    searchQuery,
-    tableDataLength: finalTableData.length,
-    fetchServerData,
-    cleanup,
-  });
-
-  // ============================================================================
-  // RBAC VALIDATION AND SECURE CONFIGURATION - ALWAYS call these hooks
-  // ============================================================================
-
-  // Wrap handlers - persistence is handled automatically via useDataTableState
-  // The state actions (clearCreationData, clearEditing) will automatically update persisted state
-  const wrappedOnCreateRow = onCreateRow;
-  const wrappedOnEditRow = onEditRow;
-
-  // MANDATORY: Handlers are automatically secured
-  const secureHandlers = useMemo(() => {
-    const handlers = {
-      onEditRow: permissions.canUpdate.can ? wrappedOnEditRow : undefined,
-      onDeleteRow: permissions.canDelete.can ? onDeleteRow : undefined,
-      onCreateRow: permissions.canCreate.can ? wrappedOnCreateRow : undefined,
-      onImport: permissions.canImport.can ? onImport : undefined,
-      onExport: permissions.canExport.can ? onExport : undefined,
-      onDeleteSelected: permissions.canDelete.can ? onDeleteSelected : undefined,
-    };
-    
-    return handlers;
-  }, [permissions.canUpdate.can, permissions.canDelete.can, permissions.canCreate.can, permissions.canImport.can, permissions.canExport.can, wrappedOnEditRow, onDeleteRow, wrappedOnCreateRow, onImport, onExport, onDeleteSelected]);
-
-  // MANDATORY: Process actions with RBAC checks
-  const effectiveActions = useMemo(() => {
-    // Create a new array to avoid mutating the original
-    const result = [...actions];
-    
-    // Add Edit action with RBAC check
-    if (secureFeatures.editing && secureHandlers.onEditRow && !result.some(a => a.label === 'Edit')) {
-      result.push({
-        label: 'Edit',
-        onClick: (row: TData) => {
-          if (!permissions.canUpdate.can) {
-            throw new Error('Insufficient permissions to edit this resource');
-          }
-
-          const rowIndex = data.findIndex(r => r === row);
-          const rowId = resolvedGetRowId(row, rowIndex >= 0 ? rowIndex : 0);
-
-          // Set the row into editing mode with the current row data
-          stateActions.setEditingRow(rowId, toCellValueRecord(row));
-        },
-        icon: Edit,
-        testId: 'edit',
-        hidden: !permissions.canUpdate.can,
-      });
-    }
-    
-    // Add Delete action with RBAC check
-    if (secureFeatures.deletion && secureHandlers.onDeleteRow && !result.some(a => a.label === 'Delete')) {
-      result.push({
-        label: 'Delete',
-        onClick: async (row: TData) => {
-          if (!permissions.canDelete.can) {
-            // NOTE: Toast notifications use default timeout (5 seconds) - do not set duration property
-            toast({
-              title: "Delete Failed",
-              description: "Insufficient permissions to delete this resource",
-              variant: "destructive"
-            });
-            return;
-          }
-          
-          // Get row ID for tracking - use current data, not effectiveData
-          const rowIndex = data.findIndex(r => r === row);
-          const rowId = resolvedGetRowId(row, rowIndex >= 0 ? rowIndex : 0);
-          
-          // Mark deletion as in progress and track this deletion
-          // CRITICAL: Set isDeleting and snapshot BEFORE calling the handler
-          // This prevents the parent's data update from causing a flash
-          if (!isDeleting) {
-            // Snapshot current data BEFORE deletion
-            dataSnapshotRef.current = [...data]; // Create a copy to prevent reference issues
-            setIsDeleting(true);
-          }
-          pendingDeletionsRef.current.add(rowId);
-          
-          // Clear any existing timeout
-          if (deletionTimeoutRef.current) {
-            clearTimeout(deletionTimeoutRef.current);
-          }
-          
-          try {
-            // Call the delete handler - this may update the parent's data prop
-            const result = secureHandlers.onDeleteRow!(row);
-            // Handle async operations (even though typed as void, handlers might return Promise)
-            if (result !== undefined && result !== null && typeof result === 'object' && 'then' in result && typeof (result as { then: unknown }).then === 'function') {
-              await (result as Promise<unknown>);
-            }
-            // Remove from pending deletions
-            pendingDeletionsRef.current.delete(rowId);
-            
-            // Reset deletion state after a delay to allow batching
-            // This prevents the table from refreshing after each individual deletion
-            deletionTimeoutRef.current = setTimeout(() => {
-              // Only reset if all deletions are complete
-              if (pendingDeletionsRef.current.size === 0) {
-                setIsDeleting(false);
-                // Update snapshot to latest data
-                dataSnapshotRef.current = data;
-                toast({
-                  title: "Delete Successful",
-                  description: "Row deleted successfully",
-                  variant: "default"
-                });
-              }
-            }, 150); // Delay to batch rapid deletions
-            
-          } catch (error) {
-            logger.error('Delete error:', error);
-            pendingDeletionsRef.current.delete(rowId);
-            if (pendingDeletionsRef.current.size === 0) {
-              setIsDeleting(false);
-              dataSnapshotRef.current = data;
-            }
-            toast({
-              title: "Delete Failed",
-              description: error instanceof Error ? error.message : 'Failed to delete row',
-              variant: "destructive"
-            });
-          }
-        },
-        icon: Trash2,
-        testId: 'delete',
-        variant: 'destructive' as const,
-        hidden: !permissions.canDelete.can,
-      });
-    }
-
-    return result;
-  }, [actions, secureFeatures, permissions, secureHandlers, resolvedGetRowId, stateActions, data, isDeleting, logger]);
-
-  // Normalize columnOrder for useTableColumns: ensure 'select' is always first
-  const normalizedColumnOrderForColumns = useMemo(() => {
-    if (secureFeatures.selection && state.columnOrder.includes('select')) {
-      return ['select', ...state.columnOrder.filter(id => id !== 'select')];
-    }
-    return state.columnOrder;
-  }, [state.columnOrder, secureFeatures.selection]);
-
-  // MANDATORY: Process columns with actions
-  const { enhancedColumns } = useTableColumns({
-    columns,
-    features: secureFeatures,
-    effectiveActions,
-    columnOrder: normalizedColumnOrderForColumns
-  });
-
-  // Use effective pageSize in pagination state snapshot to ensure table receives valid pageSize
-  const paginationStateWithValidatedSize = useMemo(() => ({
-    ...state.pagination,
-    pageSize: effectivePageSize,
-  }), [state.pagination, effectivePageSize]);
-  
-  const tableStateSnapshot = useMemo<TableStateSnapshot>(() => {
-    // Normalize columnOrder in snapshot: ensure 'select' is always first if selection is enabled
-    const normalizedColumnOrder = secureFeatures.selection && state.columnOrder.includes('select')
-      ? ['select', ...state.columnOrder.filter(id => id !== 'select')]
-      : state.columnOrder;
-    
-    return {
-      sorting: state.sorting,
-      columnFilters: state.columnFilters,
-      columnVisibility: state.columnVisibility,
-      rowSelection,
-      grouping: state.grouping,
-      expanded: state.expanded,
-      pagination: paginationStateWithValidatedSize,
-      globalFilter: searchQuery,
-      columnOrder: normalizedColumnOrder,
-    };
-  }, [
-    state.sorting,
-    state.columnFilters,
-    state.columnVisibility,
-    rowSelection,
-    state.grouping,
-    state.expanded,
-    paginationStateWithValidatedSize,
-    searchQuery,
-    state.columnOrder,
-    secureFeatures.selection,
-  ]);
-
-  const tableHandlers = useTableHandlers({
-    state,
-    stateSnapshot: tableStateSnapshot,
-    actions: stateActions,
     selection,
     onRowSelectionChange,
-    effectiveColumnOrder,
-    canPersistVisibility: secureFeatures.columnVisibility && Boolean(storageKey),
-    canPersistOrder: secureFeatures.columnReordering && Boolean(storageKey),
-    updateSavedColumnVisibility,
-    updateColumnOrder,
+    shouldAllowRenderAfterTimeout,
+    rbac,
+    enhancedPagination,
     onLayoutChange,
   });
 
-  // PERFORMANCE FIX: If permissions still loading after timeout, filter data to empty array
-  // This allows table structure to render but keeps data hidden until permissions confirm
-  // SECURITY: Data remains protected - only table structure (headers) will show
-  const safeTableData = useMemo(() => {
-    if (permissions.canRead.isLoading && shouldAllowRenderAfterTimeout) {
-      // Permissions still loading after timeout - return empty array to hide data
-      return [] as TData[];
-    }
-    if (!permissions.canRead.can) {
-      // Permissions denied - return empty array
-      return [] as TData[];
-    }
-    // Permissions confirmed - return actual data
-    return finalTableData as TData[];
-  }, [finalTableData, permissions.canRead.isLoading, permissions.canRead.can, shouldAllowRenderAfterTimeout]);
-
-  const tableConfig = useDataTableConfiguration({
-    data: safeTableData,
-    columns: enhancedColumns,
-    stateSnapshot: tableStateSnapshot,
-    handlers: tableHandlers,
-    features: secureFeatures,
-    getRowId: resolvedGetRowId,
-    finalPaginationMode,
-    finalDataCount: safeTableData.length > 0 ? finalDataCount : 0,
-    pageSize: effectivePageSize,
-    hasServerSideConfig: !!serverSide,
+  const renderGuard = useDataTableRenderGuard<TData>({
+    ...pipeline.guardInputs,
+    user,
+    permissions,
+    isPermissionLoading,
+    permissionElapsed,
+    shouldAllowRenderAfterTimeout,
+    logger,
+    LoadingComponent,
+    AccessDeniedPage,
   });
-  
 
-  const table = useReactTable(tableConfig);
-
-  // ============================================================================
-  // RBAC VALIDATION AND EARLY RETURNS - AFTER ALL HOOKS
-  // ============================================================================
-  
-  // DIAGNOSTIC: Log render state for debugging
-  const renderDiagnostics = {
-    hasUser: !!user,
-    userId: user?.id,
-    permissionLoading: permissions.canRead.isLoading,
-    permissionCan: permissions.canRead.can,
-    permissionError: permissions.canRead.error,
-    effectivePageId,
-    externalIsLoading,
-    performanceLoading,
-    computedIsLoading: isLoading,
-    dataLength: data.length,
-    finalTableDataLength: finalTableData.length,
-    columnsLength: columns.length,
-    tableRowsCount: table?.getRowModel().rows.length || 0,
-  };
-
-  // Log diagnostics in development mode
-  if (process.env.NODE_ENV === 'development') {
-    logger.debug('DataTable render diagnostics:', renderDiagnostics);
-  }
-
-  // MANDATORY: Every DataTable must have a user
-  if (!user) {
-    logger.error('DataTable render blocked: No user', renderDiagnostics);
+  if (renderGuard.gate === 'throw') {
     throw new Error('DataTable requires authenticated user for RBAC');
   }
-
-  // PERFORMANCE FIX: Allow rendering after timeout to prevent infinite blocking
-  // After 3 seconds, allow table to render but keep data hidden until permissions confirm
-  // This provides better UX while maintaining security (data remains protected)
-  // Note: permissionElapsed and shouldAllowRenderAfterTimeout are calculated above for useMemo
-  // Wait for permission check to complete before making access decisions
-  // BUT: After 3s timeout, allow table structure to render (data will remain hidden)
-  if (isPermissionLoading) {
-    // Enhanced diagnostics for hanging permission checks
-    if (permissionElapsed > 10000) {
-      logger.error('DataTableCore', 'DataTable: Permission check hanging (>10s)', {
-        ...renderDiagnostics,
-        permissionState: {
-          can: permissions.canRead.can,
-          isLoading: permissions.canRead.isLoading,
-          error: permissions.canRead.error?.message,
-        },
-        elapsedMs: permissionElapsed,
-        diagnostic: 'Permission check has been loading for over 10 seconds. This likely indicates a hanging database query or network issue. Check browser network tab for pending requests to Supabase.',
-        recommendation: 'Check: 1) Browser network tab for pending requests, 2) Supabase connection, 3) Database query performance, 4) Super admin check completion',
-      });
-    }
-    
-    if (process.env.NODE_ENV === 'development') {
-      logger.debug('DataTable render blocked: Permissions loading', {
-        ...renderDiagnostics,
-        permissionState: permissions.canRead,
-        elapsedMs: permissionElapsed,
-      });
-    }
-    return <LoadingComponent />;
-  }
-  
-  // If timeout reached but permissions still loading, log warning and proceed with caution
-  if (permissions.canRead.isLoading && shouldAllowRenderAfterTimeout) {
-    logger.warn('DataTable: Rendering after timeout - permissions still loading. Data will remain hidden until confirmed.', {
-      pageId: effectivePageId,
-      elapsedMs: permissionElapsed,
-      permissionState: permissions.canRead,
-    });
-    // Continue to render check below - we'll show empty state until permissions confirm
-  }
-
-  // MANDATORY: No data access without read permission
-  // SECURITY: If permissions are still loading after timeout, allow table structure but hide data
-  // If permissions are confirmed as denied, show access denied page
-  if (!permissions.canRead.isLoading && !permissions.canRead.can) {
-    logger.warn('Access denied - no read permission:', {
-      canRead: permissions.canRead,
-      pageId: effectivePageId,
-      isLoading: permissions.canRead.isLoading,
-      diagnostics: renderDiagnostics,
-    });
-    return <AccessDeniedPage resource={effectivePageId || 'unknown-page'} operation="read" />;
-  }
-  
-  // If permissions still loading after timeout, proceed to render but data will be empty/hidden
-  // The table structure will render, but rows will be empty until permissions confirm
-  if (permissions.canRead.isLoading && shouldAllowRenderAfterTimeout) {
-    // Log that we're proceeding with timeout
-    logger.debug('DataTable: Proceeding to render after timeout - permissions still loading', {
-      pageId: effectivePageId,
-      elapsedMs: permissionElapsed,
-    });
-    // Continue to render - data will be empty until permissions confirm
-  }
-
-  // ============================================================================
-  // RENDER
-  // ============================================================================
-  
-  if (isLoading) {
-    if (process.env.NODE_ENV === 'development') {
-      logger.debug('DataTable render blocked: External isLoading', {
-        ...renderDiagnostics,
-        isLoadingSource: {
-          externalIsLoading,
-          performanceLoading,
-          computed: isLoading,
-        },
-      });
-    }
-    return <LoadingComponent />;
-  }
-
-  // DIAGNOSTIC: Log successful render path
-  if (process.env.NODE_ENV === 'development') {
-    logger.debug('DataTable proceeding to render:', {
-      ...renderDiagnostics,
-      willRender: true,
-      tableState: {
-        rowCount: table?.getRowModel().rows.length || 0,
-        columnCount: table?.getVisibleFlatColumns().length || 0,
-        paginationMode: finalPaginationMode,
-      },
-    });
+  if (renderGuard.component) {
+    return renderGuard.component;
   }
 
   return (
     <DataTableLayout
-      table={table}
-      title={title}
-      description={description}
-      variant={variant}
-      className={className}
-      columns={columns}
-      secureFeatures={secureFeatures}
-      enhancedPagination={enhancedPagination}
-      searchQuery={searchQuery}
-      onSearch={handleSearch}
-      state={state}
-      stateActions={stateActions}
-      rowSelection={rowSelection}
-      onCreateRow={secureHandlers.onCreateRow}
-      onEditRow={secureHandlers.onEditRow}
-      onImport={secureHandlers.onImport}
-      onExport={secureHandlers.onExport}
-      onDeleteSelected={secureHandlers.onDeleteSelected}
-      rbac={rbac}
-      permissions={permissions}
-      effectiveActions={effectiveActions}
-      finalPageSizeOptions={finalPageSizeOptions}
-      finalPaginationMode={finalPaginationMode}
-      finalDataCount={finalDataCount}
-      isLoading={isLoading}
-      finalTableData={finalTableData}
-      aggregates={aggregates}
-      resolvedGetRowId={resolvedGetRowId}
-      data={data}
-      emptyState={emptyState}
-      virtualHeight={virtualHeight}
-      hierarchical={hierarchical}
-      hierarchicalState={hierarchicalState}
-      logger={logger}
-      secureHandlers={secureHandlers}
-      importModalConfig={importModalConfig}
-      keyboardNavigation={keyboardNavigation}
-      lastFocusedElementRef={lastFocusedElementRef}
+      {...(pipeline.layoutProps as unknown as React.ComponentProps<typeof DataTableLayout>)}
     />
   );
 }