@jmruthers/pace-core 0.5.193 → 0.6.2

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

@@ -8,27 +8,15 @@
  * This is the main component that consumers will use.
  */
 
-import React, { useMemo, useCallback, useEffect, useState, useRef } from 'react';
-import { useReactTable, flexRender } from '@tanstack/react-table';
+import React, { useMemo, useCallback, useEffect, useRef } from 'react';
+import { useReactTable } from '@tanstack/react-table';
 import type {
   SortingState,
-  ColumnFiltersState,
-  VisibilityState,
-  GroupingState,
-  ExpandedState,
-  PaginationState,
 } from '@tanstack/react-table';
-import { Edit, Trash, ChevronUp, ChevronDown, ChevronsUpDown } from 'lucide-react';
-import { cn } from '../../../utils/core/cn';
-import { Checkbox } from '../../Checkbox/Checkbox';
-import { Button } from '../../Button/Button';
-import { getTableClasses, getMainContainerClasses } from '../styles';
+import { Edit, Trash } from 'lucide-react';
 import { useDataTablePerformance } from '../../../hooks/useDataTablePerformance';
-import { DataTableToolbar } from './DataTableToolbar';
-import { UnifiedTableBody } from './UnifiedTableBody';
-import { PaginationControls, EnhancedPaginationControls } from './PaginationControls';
 import { LoadingState } from './LoadingState';
-import { DataTableModals } from './DataTableModals';
+import { DataTableLayout } from './DataTableLayout';
 import { DataTableErrorBoundary } from './DataTableErrorBoundary';
 import { useColumnOrderPersistence } from '../hooks/useColumnOrderPersistence';
 import { useColumnVisibilityPersistence } from '../hooks/useColumnVisibilityPersistence';
@@ -41,20 +29,19 @@ import { useDataTableConfiguration } from '../hooks/useDataTableConfiguration';
 import type { TableStateSnapshot } from '../hooks/useTableHandlers';
 import { ColumnFactory } from '../core/ColumnFactory';
 import { AccessDeniedPage } from './AccessDeniedPage';
-import { useCan, useResolvedScope } from '../../../rbac/hooks';
 // 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 { exportToCSV, exportToCSVWithTableRows } from '../utils/exportUtils';
-import type { ExportOptions } from '../types';
 import { useUnifiedAuth } from '../../../providers/services/UnifiedAuthProvider';
-import { Scope } from '../../../rbac/types';
 import { useDataTablePermissions } from '../hooks/useDataTablePermissions';
 import { useTableColumns } from '../hooks/useTableColumns';
-import { initializeLiveRegion, announceSortChange } from '../utils/a11yUtils';
+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 { normalizeDataTableFeatures } from '../types';
 import type {
@@ -69,50 +56,23 @@ import type {
   DataTableFeatureConfig,
   NormalizedDataTableFeatureConfig,
   DataTableColumn,
-  SimpleColumn,
   AggregateConfig,
   DataTableAction,
   HierarchicalConfig,
   DataTableRBACConfig,
-  CellValue
 } from '../types';
 import type { ImportModalConfig } from './ImportModal';
 
-const isCellValue = (value: unknown): value is CellValue => {
-  if (value === null || value === undefined) {
-    return true;
-  }
-
-  if (value instanceof Date) {
-    return true;
-  }
-
-  const valueType = typeof value;
-  return valueType === 'string' || valueType === 'number' || valueType === 'boolean';
-};
-
-const toCellValueRecord = <TData extends DataRecord>(row: TData): Record<string, CellValue> => {
-  if (typeof row !== 'object' || row === null) {
-    return {};
-  }
-
-  return Object.entries(row).reduce<Record<string, CellValue>>((accumulator, [key, entryValue]) => {
-    if (isCellValue(entryValue)) {
-      accumulator[key] = entryValue;
-    } else if (entryValue && typeof entryValue === 'object' && 'toString' in entryValue) {
-      accumulator[key] = String(entryValue) as CellValue;
-    } else {
-      accumulator[key] = entryValue as CellValue;
-    }
-
-    return accumulator;
-  }, {});
-};
-
 // ============================================================================
 // CORE COMPONENT PROPS
 // ============================================================================
 
+/**
+ * Core DataTable component props.
+ * This is the internal component that handles all DataTable functionality.
+ * 
+ * @template TData - The type of data records in the table
+ */
 export interface DataTableCoreProps<TData extends DataRecord> {
   // Core data
   data: TData[];
@@ -159,7 +119,7 @@ export interface DataTableCoreProps<TData extends DataRecord> {
   // Utilities
   getRowId?: GetRowId<TData>;
   isLoading?: boolean;
-  emptyState?: EmptyStateConfig | React.ReactElement;
+  emptyState?: EmptyStateConfig | React.ReactElement<any>;
   aggregates?: AggregateConfig[];
   importModalConfig?: ImportModalConfig;
   actions?: DataTableAction<TData>[];
@@ -220,7 +180,7 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
     onLayoutChange,
   } = props;
   
-  const logger = React.useMemo(() => createLogger('DataTableCore'), []);
+  const logger = createLogger('DataTableCore');
   
   // ============================================================================
   // ALL HOOKS MUST BE CALLED IN THE SAME ORDER EVERY RENDER
@@ -236,6 +196,16 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
 
   // MANDATORY: Get permissions and secure features
   const { permissions, secureFeatures, effectivePageId } = useDataTablePermissions(rbac, requestedFeatures);
+
+  const {
+    permissionElapsed,
+    shouldAllowRenderAfterTimeout,
+    isPermissionLoading,
+  } = usePermissionTracking({
+    permissions,
+    effectivePageId,
+    logger,
+  });
   
   
   // ============================================================================
@@ -362,43 +332,7 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
     }
   );
 
-  const lastFocusedElementRef = useRef<HTMLElement | null>(null);
-  const wasImportModalOpenRef = useRef(false);
-
-  // Store focus when modals open, restore when they close
-  useEffect(() => {
-    if (state.showImportModal) {
-      wasImportModalOpenRef.current = true;
-      keyboardNavigation.storeFocus();
-      if (document.activeElement instanceof HTMLElement) {
-        lastFocusedElementRef.current = document.activeElement;
-      }
-    }
-  }, [state.showImportModal, keyboardNavigation]);
-
-  useEffect(() => {
-    if (!state.showImportModal) {
-      if (!wasImportModalOpenRef.current) {
-        return;
-      }
-      wasImportModalOpenRef.current = false;
-      // Restore focus after modal closes
-      setTimeout(() => {
-        const storedElement = lastFocusedElementRef.current;
-        lastFocusedElementRef.current = null;
-
-        const elementToRestore = storedElement?.isConnected
-          ? storedElement
-          : document.querySelector<HTMLElement>('[data-restore-target="datatable-import-button"]');
-
-        if (elementToRestore && typeof elementToRestore.focus === 'function') {
-          elementToRestore.focus();
-        } else {
-          keyboardNavigation.restoreFocus();
-        }
-      }, 100); // Small delay to ensure modal is fully closed
-    }
-  }, [state.showImportModal, keyboardNavigation]);
+  const { lastFocusedElementRef } = useImportModalFocus(state.showImportModal, keyboardNavigation);
 
   // ============================================================================
   // HIERARCHICAL DATA VALIDATION AND PROCESSING - ALWAYS call these hooks
@@ -540,7 +474,13 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
     finalDataCount
   ]);
   
-  const isLoading = externalIsLoading || performanceLoading;
+  // 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
@@ -773,15 +713,31 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
     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: finalTableData as TData[],
+    data: safeTableData,
     columns: enhancedColumns,
     stateSnapshot: tableStateSnapshot,
     handlers: tableHandlers,
     features: secureFeatures,
     getRowId: resolvedGetRowId,
     finalPaginationMode,
-    finalDataCount,
+    finalDataCount: safeTableData.length > 0 ? finalDataCount : 0,
     pageSize: effectivePageSize,
     hasServerSideConfig: !!serverSide,
   });
@@ -793,498 +749,172 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
   // 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);
     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
-  if (permissions.canRead.isLoading) {
+  // 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 (only check after loading completes)
-  if (!permissions.canRead.can) {
+  // 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 />;
   }
 
-  const PaginationComponent = enhancedPagination || finalPaginationMode !== 'client' 
-    ? EnhancedPaginationControls 
-    : PaginationControls;
-
-  // Calculate column counts for colgroup
-  const visibleColumns = table?.getVisibleFlatColumns() || [];
-  const dataColumns = visibleColumns.filter(col => 
-    col.id !== 'select' && col.id !== 'actions'
-  ).length;
-  const hasSelectColumn = visibleColumns.some(col => col.id === 'select');
-  const hasActionsColumn = visibleColumns.some(col => col.id === 'actions');
+  // 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,
+      },
+    });
+  }
 
   return (
-    <>
-      {/* Table with semantic HTML structure */}
-      <table 
-        className={getTableClasses({
-          isFixed: false, // Use auto table-layout so columns size based on content
-          variant,
-          className: cn('border-collapse relative w-full', className)
-        })}
-        aria-label={title}
-        aria-describedby={description ? 'table-description' : undefined}
-        aria-busy={isLoading ? 'true' : 'false'}
-      >
-        {/* Caption with title, description, and toolbar */}
-        <caption className="text-left pb-2">
-          {(title || description) && (
-            <>
-              {title && <h2 >{title}</h2>}
-              {description && <p id="table-description">{description}</p>}
-            </>
-          )}
-          <>
-            <DataTableToolbar
-              features={secureFeatures}
-              globalFilter={searchQuery}
-              onGlobalFilterChange={handleSearch}
-              columns={columns}
-              grouping={state.grouping}
-              onGroupByChange={(columnId) => {
-                stateActions.setGrouping(columnId ? [columnId] : []);
-              }}
-              tableColumns={table?.getAllColumns() || []}
-              onColumnVisibilityChange={(columnId: string, visible: boolean) => {
-                // Update visibility for specific column
-                stateActions.setColumnVisibility({ ...state.columnVisibility, [columnId]: visible });
-              }}
-              onCreateRow={secureFeatures.creation && secureHandlers.onCreateRow ? () => stateActions.setCreating(true) : undefined}
-              onImportClick={() => {
-                if (document.activeElement instanceof HTMLElement) {
-                  lastFocusedElementRef.current = document.activeElement;
-                }
-                stateActions.setImportModal(true);
-              }}
-              onExport={async () => {
-                try {
-                  // Prepare export options with all available data
-                  // Get the table rows (which have getValue() that properly evaluates accessorFn)
-                  const tableRows = table.getFilteredRowModel().rows;
-                  
-                  // Get only visible columns by checking the actual table columns
-                  // This approach is more reliable because it uses the table's actual column registry
-                  const tableColumns = table.getAllColumns();
-                  const visibleTableColumns = tableColumns.filter(col => {
-                    // Exclude system columns (selection, actions) and only include data columns
-                    const isSystemColumn = col.id === 'select' || col.id === 'actions';
-                    return !isSystemColumn && col.getIsVisible();
-                  });
-                  
-                  // Map table columns to visible columns
-                  const visibleColumns: DataTableColumn<TData>[] = [];
-                  
-                  // Store mapping of column IDs to table column instances for getValue() calls
-                  const columnIdToTableColumn = new Map<string, typeof visibleTableColumns[0]>();
-                  
-                  visibleTableColumns.forEach(tableCol => {
-                    // Find the original column definition that matches this table column
-                    const originalCol = columns.find(col => {
-                      const colId = col.id || col.accessorKey;
-                      return colId && String(colId) === tableCol.id;
-                    });
-                    
-                    if (!originalCol) return;
-                    
-                    // Store the table column for getValue() calls
-                    columnIdToTableColumn.set(tableCol.id, tableCol);
-                    
-                    // Add the display column (what's shown in the table)
-                    visibleColumns.push(originalCol);
-                  });
-                  
-                  // Generate filename with timestamp
-                  const timestamp = new Date().toISOString().split('T')[0];
-                  const filename = title ? `${title.replace(/[^a-z0-9]/gi, '_').toLowerCase()}_${timestamp}.csv` : `data_export_${timestamp}.csv`;
-                  
-                  // Create export options
-                  const exportOptions: ExportOptions<TData> = {
-                    tableRows,
-                    allColumns: columns,
-                    visibleColumns,
-                    columnIdToTableColumn,
-                    data,
-                    filename,
-                    table
-                  };
-                  
-                  // If custom handler provided, call it with options
-                  if (secureHandlers.onExport) {
-                    await secureHandlers.onExport(exportOptions);
-                    return;
-                  }
-                  
-                  // Default export: exports exactly what's shown in the table
-                  // Convert visible columns to ExportColumn format
-                  const exportColumns: Array<{
-                    header?: string;
-                    id?: string;
-                    accessorKey?: string;
-                    accessorFn?: (row: any) => any;
-                    editAccessorKey?: string;
-                    isIdColumn?: boolean;
-                  }> = exportOptions.visibleColumns.map(col => {
-                    const colId = col.id || col.accessorKey;
-                    const hasAccessorFn = 'accessorFn' in col && (col as any).accessorFn;
-                    
-                    return {
-                      ...col,
-                      header: typeof col.header === 'string' 
-                        ? col.header 
-                        : col.accessorKey || colId || 'Column',
-                      id: colId ? String(colId) : undefined,
-                      accessorFn: hasAccessorFn ? (col as any).accessorFn : undefined,
-                    };
-                  });
-                  
-                  // Export using table rows with getValue() for proper accessorFn evaluation
-                  // This ensures we get the same values that are displayed in the table
-                  await exportToCSVWithTableRows(
-                    exportOptions.tableRows, 
-                    exportColumns, 
-                    exportOptions.columnIdToTableColumn, 
-                    exportOptions.filename
-                  );
-                  
-                  // Show success toast notification
-                  // NOTE: Toast notifications use default timeout (5 seconds) - do not set duration property
-                  toast({
-                    title: "Export Successful",
-                    description: `Data exported to ${exportOptions.filename}`,
-                    variant: "default"
-                  });
-                } catch (error) {
-                  logger.error('Failed to export data:', error);
-                  
-                  // Show error toast notification to user
-                  const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
-                  toast({
-                    title: "Export Failed",
-                    description: `Failed to export data: ${errorMessage}`,
-                    variant: "destructive"
-                  });
-                }
-              }}
-              rowSelection={rowSelection}
-              onDeleteSelected={secureHandlers.onDeleteSelected ? async (selectedRows: Record<string, boolean>) => {
-                const selectedCount = Object.values(selectedRows).filter(Boolean).length;
-                if (selectedCount === 0) {
-                  toast({
-                    title: "No Selection",
-                    description: "Please select at least one row to delete",
-                    variant: "default"
-                  });
-                  return;
-                }
-                try {
-                  const result = secureHandlers.onDeleteSelected!(selectedRows) as any;
-                  // Handle async operations
-                  if (result !== undefined && result !== null && typeof result === 'object' && typeof result.then === 'function') {
-                    await result;
-                  }
-                  toast({
-                    title: "Delete Successful",
-                    description: `Successfully deleted ${selectedCount} ${selectedCount === 1 ? 'row' : 'rows'}`,
-                    variant: "default"
-                  });
-                } catch (error) {
-                  logger.error('Bulk delete error:', error);
-                  toast({
-                    title: "Delete Failed",
-                    description: error instanceof Error ? error.message : 'Failed to delete selected rows',
-                    variant: "destructive"
-                  });
-                }
-              } : undefined}
-              onToggleFilterRow={() => stateActions.setFilterRow(!state.showFilterRow)}
-              showFilterRow={state.showFilterRow}
-              rbac={rbac}
-              permissions={permissions}
-            />
-          </>
-        </caption>
-
-        {/* Column groups */}
-        <colgroup>
-          {hasSelectColumn && <col span={1} data-col-type="select"/>}
-          <col span={dataColumns} data-col-type="data" />
-          {hasActionsColumn && <col span={1} data-col-type="actions"/>}
-        </colgroup>
-
-        {/* Table header */}
-        <thead>
-          {table?.getHeaderGroups().map((headerGroup) => {
-            // Filter visible headers once to determine first and last
-            const visibleHeaders = headerGroup.headers.filter(header => {
-              return typeof header.column.getIsVisible === 'function' 
-                ? header.column.getIsVisible() 
-                : true;
-            });
-            
-            return (
-              <tr key={headerGroup.id}>
-                {visibleHeaders.map((header, index) => {
-                  const isFirst = index === 0;
-                  const isLast = index === visibleHeaders.length - 1;
-                  const isSortable = header.column.getCanSort();
-                  const ariaSort = isSortable
-                    ? (header.column.getIsSorted() === 'asc'
-                        ? 'ascending'
-                        : header.column.getIsSorted() === 'desc'
-                        ? 'descending'
-                        : 'none')
-                    : undefined;
-                  const isRightAligned = header.column.columnDef.meta?.align === 'right';
-                  
-                  // Create custom sort handler with accessibility announcement
-                  const handleSortClick = (event: React.MouseEvent) => {
-                    const originalHandler = header.column.getToggleSortingHandler();
-                    if (originalHandler) {
-                      originalHandler(event);
-                    }
-                    
-                    // Announce the sort change
-                    const columnName = typeof header.column.columnDef.header === 'string' 
-                      ? header.column.columnDef.header 
-                      : 'column';
-                    const currentSort = header.column.getIsSorted();
-                    const newSort = currentSort === 'asc' ? 'desc' : currentSort === 'desc' ? null : 'asc';
-                    announceSortChange(columnName, newSort);
-                  };
-                  
-                  // Get keyboard navigation handlers for this header
-                  const headerKeyboardHandlers = keyboardNavigation.getHeaderKeyboardHandlers(
-                    header.index,
-                    () => {
-                      // Sort handler for keyboard navigation
-                      const originalHandler = header.column.getToggleSortingHandler();
-                      if (originalHandler) {
-                        originalHandler({} as any);
-                      }
-                      
-                      // Announce the sort change
-                      const columnName = typeof header.column.columnDef.header === 'string' 
-                        ? header.column.columnDef.header 
-                        : 'column';
-                      const currentSort = header.column.getIsSorted();
-                      const newSort = currentSort === 'asc' ? 'desc' : currentSort === 'desc' ? null : 'asc';
-                      announceSortChange(columnName, newSort);
-                    }
-                  );
-                  
-                  return (
-                    <th
-                      key={header.id}
-                      className={cn(
-                        'px-3 py-2 bg-main-200',
-                        isRightAligned ? 'text-right' : 'text-left',
-                        isFirst && 'rounded-l-md',
-                        isLast && 'rounded-r-md'
-                      )}  
-                      scope="col"
-                      role="columnheader"
-                      {...(isSortable ? { 'aria-sort': ariaSort } : {})}
-                      {...(isSortable ? headerKeyboardHandlers : {})}
-                    >
-                      {header.isPlaceholder ? null : (
-                        isSortable ? (
-                          <Button
-                            variant="ghost"
-                            className={`h-auto p-0 font-bold hover:bg-transparent ${isRightAligned ? 'justify-end' : 'justify-start'}`}
-                            onClick={handleSortClick}
-                            {...headerKeyboardHandlers}
-                            aria-label={`Sort by ${typeof header.column.columnDef.header === 'string' ? header.column.columnDef.header : 'column'}`}
-                            tabIndex={0}
-                          >
-                            {typeof header.column.columnDef.header === 'function'
-                              ? header.column.columnDef.header(header.getContext())
-                              : header.column.columnDef.header}
-                            {header.column.getIsSorted() === 'asc' ? (
-                              <ChevronUp className="size-4" />
-                            ) : header.column.getIsSorted() === 'desc' ? (
-                              <ChevronDown className="size-4" />
-                            ) : (
-                              <ChevronsUpDown className="size-4" />
-                            )}
-                          </Button>
-                        ) : (
-                          typeof header.column.columnDef.header === 'function'
-                            ? header.column.columnDef.header(header.getContext())
-                            : header.column.columnDef.header
-                        )
-                      )}
-                    </th>
-                  );
-                })}
-              </tr>
-            );
-          })}
-        </thead>
-
-        {/* Table body */}
-        <UnifiedTableBody
-            table={table}
-            isCreating={isCreating}
-            creationData={creationData}
-            onCreationDataChange={stateActions.setCreationData}
-            onSaveCreation={() => {
-              if (onCreateRow) {
-                onCreateRow(creationData as Partial<TData>);
-                stateActions.clearCreationData();
-                stateActions.setCreating(false);
-              }
-            }}
-            onCancelCreation={() => {
-              stateActions.clearCreationData();
-              stateActions.setCreating(false);
-            }}
-            editingRowId={editingRowId}
-            editingData={editingData}
-            onEditingDataChange={(data) => {
-              // Update the editing data in the centralized state
-              if (editingRowId) {
-                stateActions.setEditingRow(editingRowId, data);
-              }
-            }}
-            onSaveEditing={() => {
-              if (onEditRow && editingRowId) {
-                // Find the original row data
-                const originalRow = data.find(row => {
-                  try {
-                    const rowId = resolvedGetRowId(row, 0);
-                    return rowId === editingRowId;
-                  } catch {
-                    return false;
-                  }
-                });
-                if (originalRow) {
-                  onEditRow(originalRow, editingData as Partial<TData>);
-                }
-              }
-              stateActions.clearEditing();
-            }}
-            onCancelEditing={() => {
-              stateActions.clearEditing();
-            }}
-            grouping={state.grouping}
-            aggregates={aggregates}
-            getRowId={resolvedGetRowId}
-            emptyState={React.isValidElement(emptyState) ? undefined : emptyState as any}
-            isFiltered={searchQuery !== '' || state.columnFilters.length > 0}
-            onClearFilters={() => {
-              // Clear both search query states to keep them in sync
-              stateActions.setSearchQuery('');
-              setSearchQuery('');
-              stateActions.setColumnFilters([]);
-            }}
-            enableFiltering={secureFeatures.filtering}
-            showFilterRow={showFilterRow}
-            dataLength={finalTableData?.length || 0}
-            virtualHeight={virtualHeight}
-            forceVirtualization={false}
-            hierarchical={secureFeatures.hierarchical && hierarchical?.enabled && hierarchicalState ? {
-              ...hierarchical,
-              state: hierarchicalState,
-              expandAll: hierarchicalState.expandAll,
-              collapseAll: hierarchicalState.collapseAll,
-              isAllExpanded: hierarchicalState.getExpandedIds().length > 0 && 
-                hierarchicalState.getExpandedIds().length === (finalTableData as any[]).filter(row => row.isParent).length,
-              hasAnyChildren: (finalTableData as any[]).some(row => row.isParent),
-            } : undefined}
-            actions={effectiveActions}
-            rbac={rbac}
-            permissions={permissions}
-          />
-
-        {/* Table footer with pagination */}
-        {secureFeatures.pagination && (
-          <tfoot>
-            <tr>
-              <td colSpan={visibleColumns.length}>
-                <PaginationComponent
-                  table={table}
-                  pageSizeOptions={finalPageSizeOptions}
-                  paginationMode={finalPaginationMode}
-                  totalCount={finalDataCount}
-                  isLoading={isLoading}
-                />
-              </td>
-            </tr>
-          </tfoot>
-        )}
-
-      </table>
-
-      {/* Modal Dialogs */}
-      <DataTableModals
-        showImportModal={state.showImportModal}
-        onCloseImportModal={() => stateActions.setImportModal(false)}
-        onImport={async (data: TData[]) => {
-          if (onImport) {
-            try {
-              const result = onImport(data);
-              if (result && typeof result.then === 'function') {
-                await result;
-              }
-              
-              // Show success toast
-              // NOTE: Toast notifications use default timeout (5 seconds) - do not set duration property
-              toast({
-                title: "Import Successful",
-                description: `Successfully imported ${data.length} ${data.length === 1 ? 'row' : 'rows'}`,
-                variant: "default"
-              });
-            } catch (error) {
-              logger.error('Import error:', error);
-              toast({
-                title: "Import Failed",
-                description: error instanceof Error ? error.message : 'Failed to import data',
-                variant: "destructive"
-              });
-              // Don't close modal on error so user can see the error
-              return;
-            }
-          } else {
-            logger.error('onImport handler not provided');
-            toast({
-              title: "Import Not Configured",
-              description: "Import functionality requires an onImport handler to be provided.",
-              variant: "destructive"
-            });
-            // Don't close modal so user can see the error
-            return;
-          }
-          stateActions.setImportModal(false);
-        }}
-        importModalConfig={importModalConfig}
-        columns={columns.map(col => ({
-          id: col.id,
-          accessorKey: col.accessorKey,
-          header: typeof col.header === 'string' ? col.header : undefined,
-          editAccessorKey: col.editAccessorKey,
-        }))}
-      />
-    </>
+    <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}
+    />
   );
 }
 
@@ -1292,6 +922,15 @@ function DataTableInternal<TData extends DataRecord>(props: DataTableCoreProps<T
 // MAIN COMPONENT
 // ============================================================================
 
+/**
+ * Core DataTable component implementation.
+ * This is the internal component that handles all DataTable functionality including
+ * state management, RBAC, performance optimizations, and feature rendering.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - DataTable configuration
+ * @returns The rendered DataTable with error boundary
+ */
 export function DataTableCore<TData extends DataRecord>(props: DataTableCoreProps<TData>) {
   return (
     <DataTableErrorBoundary>