@jmruthers/pace-core 0.4.1 → 0.5.3

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

@@ -0,0 +1,1027 @@
+/**
+ * @file DataTable Core Component
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Components
+ * @since 0.4.0
+ * 
+ * Core DataTable component that orchestrates all sub-components.
+ * This is the main component that consumers will use.
+ */
+
+import React, { useMemo, useCallback, useEffect, useState, useRef } from 'react';
+import { 
+  useReactTable, 
+  getCoreRowModel, 
+  getFilteredRowModel, 
+  getSortedRowModel, 
+  getPaginationRowModel, 
+  getGroupedRowModel, 
+  getExpandedRowModel,
+  flexRender,
+  type SortingState,
+  type ColumnDef,
+  type ColumnFiltersState,
+  type VisibilityState,
+  type GroupingState,
+  type ExpandedState,
+  type PaginationState,
+  type HeaderContext,
+  type CellContext,
+} from '@tanstack/react-table';
+import { Edit, Trash, ChevronUp, ChevronDown, ChevronsUpDown } from 'lucide-react';
+import { cn } from '../../../utils/cn';
+import { Checkbox } from '../../Checkbox/Checkbox';
+import { Button } from '../../Button/Button';
+import { getTableClasses, getMainContainerClasses } from '../styles';
+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 { DataTableErrorBoundary } from './DataTableErrorBoundary';
+import { useColumnOrderPersistence } from '../hooks/useColumnOrderPersistence';
+import { useHierarchicalState } from '../hooks/useHierarchicalState';
+import { useDataTableState } from '../hooks/useDataTableState';
+import { validateHierarchicalData, sortHierarchicalData } from '../utils/hierarchicalUtils';
+import { sortHierarchicalData as sortHierarchicalDataWithSorting } from '../utils/hierarchicalSorting';
+import { ColumnFactory } from '../core/ColumnFactory';
+import { AccessDeniedPage } from './AccessDeniedPage';
+import { useCan } from '../../../rbac/hooks';
+import { useUnifiedAuth } from '../../../providers/UnifiedAuthProvider';
+
+import type { 
+  DataRecord,
+  GetRowId,
+  ServerSideParams,
+  PerformanceConfig,
+  ServerSideConfig,
+  ChunkingConfig,
+  SearchIndexConfig,
+  PaginationMode,
+  EmptyStateConfig,
+  DataTableFeatureConfig,
+  DataTableColumn,
+  SimpleColumn,
+  AggregateConfig,
+  DataTableAction,
+  HierarchicalConfig,
+  HierarchicalDataRow,
+  DataTableRBACConfig,
+  RBACContext
+} from '../types';
+import type { ImportModalConfig } from './ImportModal';
+
+// ============================================================================
+// CORE COMPONENT PROPS
+// ============================================================================
+
+export interface DataTableCoreProps<TData extends DataRecord> {
+  // Core data
+  data: TData[];
+  columns: DataTableColumn<TData>[];
+  
+  // MANDATORY RBAC - NO OPTIONAL
+  /** RBAC configuration - REQUIRED for all DataTables */
+  rbac: DataTableRBACConfig;
+  
+  // Display
+  title?: string;
+  description?: string;
+  variant?: 'default' | 'compact' | 'spacious';
+  className?: string;
+  
+  // Feature configuration
+  features: DataTableFeatureConfig;
+  
+  // Hierarchical configuration
+  hierarchical?: HierarchicalConfig;
+  
+  // Performance props
+  performance?: PerformanceConfig;
+  serverSide?: ServerSideConfig<TData>;
+  paginationMode?: PaginationMode;
+  chunking?: ChunkingConfig;
+  searchIndex?: SearchIndexConfig;
+  virtualHeight?: number;
+  enhancedPagination?: boolean;
+  loadingComponent?: React.ComponentType;
+  errorComponent?: React.ComponentType<{ error: Error; retry: () => void }>;
+  initialPageSize?: number;
+  
+  // Event handlers
+  onEditRow?: (row: TData, data: Partial<TData>) => void;
+  onDeleteRow?: (row: TData) => void;
+  onCreateRow?: (data: Partial<TData>) => void;
+  onImport?: (data: TData[]) => void | Promise<void>;
+  onExport?: () => void;
+  onRowSelectionChange?: (selection: Record<string, boolean>) => void;
+  selection?: Record<string, boolean>;
+  onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
+  
+  // Utilities
+  getRowId?: GetRowId<TData>;
+  isLoading?: boolean;
+  emptyState?: EmptyStateConfig | React.ReactElement;
+  aggregates?: AggregateConfig[];
+  importModalConfig?: ImportModalConfig;
+  actions?: DataTableAction<TData>[];
+  columnOrder?: string[];
+}
+
+// ============================================================================
+// INTERNAL COMPONENT (USES CONTEXT)
+// ============================================================================
+
+function DataTableInternal<TData extends DataRecord>({
+  data,
+  columns,
+  rbac, // MANDATORY RBAC
+  title,
+  description,
+  variant = 'default',
+  className,
+  features,
+  hierarchical,
+  performance = {},
+  serverSide,
+  paginationMode,
+  chunking,
+  searchIndex,
+  virtualHeight = 600,
+  enhancedPagination = false,
+  loadingComponent: LoadingComponent = LoadingState,
+  errorComponent: ErrorComponent,
+  initialPageSize = 10,
+  onEditRow,
+  onDeleteRow,
+  onCreateRow,
+  onImport,
+  onExport,
+  onRowSelectionChange,
+  selection,
+  onDeleteSelected,
+  getRowId,
+  isLoading: externalIsLoading = false,
+  emptyState,
+  aggregates = [],
+  importModalConfig,
+  actions = [],
+  columnOrder: externalColumnOrder,
+}: DataTableCoreProps<TData>) {
+  
+  // ============================================================================
+  // MANDATORY RBAC ENFORCEMENT
+  // ============================================================================
+  
+  // MANDATORY: Get authenticated user
+  const authResult = useUnifiedAuth();
+  const user = authResult.user;
+  
+  // MANDATORY: Every DataTable must have a user and RBAC config
+  if (!user) {
+    throw new Error('DataTable requires authenticated user for RBAC');
+  }
+  
+  if (!rbac?.resource) {
+    throw new Error('DataTable requires rbac.resource for permission checking');
+  }
+
+  const scope = {
+    organisationId: user?.user_metadata?.organisationId || user?.app_metadata?.organisationId,
+    eventId: user?.user_metadata?.eventId || user?.app_metadata?.eventId,
+    appId: user?.user_metadata?.appId || user?.app_metadata?.appId,
+  };
+
+  // MANDATORY: Check all permissions upfront - ALWAYS enforce RBAC
+  const permissions = {
+    canRead: useCan(user.id, scope, `read:${rbac.resource}` as any, rbac.pageId),
+    canCreate: useCan(user.id, scope, `create:${rbac.resource}` as any, rbac.pageId),
+    canUpdate: useCan(user.id, scope, `update:${rbac.resource}` as any, rbac.pageId),
+    canDelete: useCan(user.id, scope, `delete:${rbac.resource}` as any, rbac.pageId),
+    canExport: useCan(user.id, scope, `manage:${rbac.resource}` as any, rbac.pageId), // Using manage for export/import
+    canImport: useCan(user.id, scope, `manage:${rbac.resource}` as any, rbac.pageId), // Using manage for export/import
+  };
+
+  // MANDATORY: No data access without read permission
+  if (!permissions.canRead.can) {
+    return <AccessDeniedPage resource={rbac?.resource || 'test-resource'} operation="read" />;
+  }
+
+  // MANDATORY: Features are automatically filtered by permissions
+  const secureFeatures: DataTableFeatureConfig = {
+    ...features,
+    creation: features.creation && permissions.canCreate.can,
+    editing: features.editing && permissions.canUpdate.can,
+    deletion: features.deletion && permissions.canDelete.can,
+    deleteSelected: features.deleteSelected && permissions.canDelete.can,
+    export: features.export && permissions.canExport.can,
+    import: features.import && permissions.canImport.can,
+  };
+
+  // MANDATORY: Handlers are automatically secured
+  const secureHandlers = {
+    onEditRow: permissions.canUpdate.can ? onEditRow : undefined,
+    onDeleteRow: permissions.canDelete.can ? onDeleteRow : undefined,
+    onCreateRow: permissions.canCreate.can ? onCreateRow : undefined,
+    onImport: permissions.canImport.can ? onImport : undefined,
+    onExport: permissions.canExport.can ? onExport : undefined,
+    onDeleteSelected: permissions.canDelete.can ? onDeleteSelected : undefined,
+  };
+  
+  // ============================================================================
+  // TABLE STATE MANAGEMENT (Single State Source)
+  // ============================================================================
+  
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({});
+  const [internalRowSelection, setInternalRowSelection] = useState<Record<string, boolean>>({});
+  const rowSelection = selection !== undefined ? selection : internalRowSelection;
+  const [columnOrder, setColumnOrder] = useState<string[]>(() => {
+    // Use external columnOrder if provided, otherwise derive from columns
+    if (externalColumnOrder && externalColumnOrder.length > 0) {
+      return externalColumnOrder;
+    }
+    return columns.map(col => col.id || col.accessorKey || '').filter(Boolean);
+  });
+
+  // Update columnOrder to include selection column if it's not already included
+  const effectiveColumnOrder = useMemo(() => {
+    if (features.selection && !columnOrder.includes('select')) {
+      return ['select', ...columnOrder];
+    }
+    return columnOrder;
+  }, [columnOrder, features.selection]);
+  const [grouping, setGrouping] = useState<GroupingState>([]);
+  const [expanded, setExpanded] = useState<ExpandedState>({});
+  
+  // ============================================================================
+  // PAGINATION STATE MANAGEMENT
+  // ============================================================================
+  
+  const [pagination, setPagination] = useState<PaginationState>({
+    pageIndex: 0,
+    pageSize: initialPageSize,
+  });
+  
+  // ============================================================================
+  // EDITING STATE MANAGEMENT
+  // ============================================================================
+  
+  // Use the centralized state management hook
+  const { state: tableState, actions: tableActions } = useDataTableState<TData>({
+    initialPageSize,
+    columnIds: effectiveColumnOrder,
+    initialRowSelection: selection,
+    onRowSelectionChange
+  });
+  
+  // Extract editing state from the centralized state
+  const isCreating = tableState.isCreating;
+  const creationData = tableState.creationData;
+  const editingRowId = tableState.editingRowId;
+  const editingData = tableState.editingData;
+  
+  // ============================================================================
+  // IMPORT MODAL STATE MANAGEMENT
+  // ============================================================================
+  
+  const [showImportModal, setShowImportModal] = useState(false);
+  
+  // ============================================================================
+  // FILTER ROW VISIBILITY STATE MANAGEMENT
+  // ============================================================================
+  
+  const [showFilterRow, setShowFilterRow] = useState(false);
+  
+  // ============================================================================
+  // PERFORMANCE HOOK
+  // ============================================================================
+  
+  const performanceHook = useDataTablePerformance({
+    data,
+    performance,
+    serverSide,
+    chunking,
+    searchIndex,
+  });
+
+  const {
+    paginationMode: detectedMode,
+    isVirtualized,
+    pageSizeOptions: optimizedPageSizeOptions,
+    processedData,
+    totalCount,
+    isLoading: performanceLoading,
+    searchQuery,
+    setSearchQuery,
+    fetchServerData,
+    serverData,
+    cleanup,
+  } = performanceHook;
+
+  // ============================================================================
+  // HIERARCHICAL DATA VALIDATION AND PROCESSING
+  // ============================================================================
+  
+  const hierarchicalValidation = useMemo(() => {
+    if (features.hierarchical && hierarchical?.enabled) {
+      return validateHierarchicalData(data as unknown as HierarchicalDataRow[]);
+    }
+    return { isValid: true, errors: [] };
+  }, [features.hierarchical, hierarchical?.enabled, data]);
+
+  const processedHierarchicalData = useMemo(() => {
+    if (features.hierarchical && hierarchical?.enabled && hierarchicalValidation.isValid) {
+      return sortHierarchicalData(data as unknown as HierarchicalDataRow[]);
+    }
+    return data;
+  }, [features.hierarchical, hierarchical?.enabled, hierarchicalValidation.isValid, data]);
+
+  // ============================================================================
+  // HIERARCHICAL STATE MANAGEMENT
+  // ============================================================================
+  
+  const hierarchicalState = useHierarchicalState(
+    processedHierarchicalData as unknown as HierarchicalDataRow[],
+    hierarchical
+  );
+
+  // ============================================================================
+  // COLUMN ORDER PERSISTENCE
+  // ============================================================================
+  
+  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: features.columnReordering,
+  });
+
+  // ============================================================================
+  // CONFIGURATION RESOLUTION
+  // ============================================================================
+  
+  const finalPaginationMode = paginationMode || detectedMode;
+  const finalPageSizeOptions = optimizedPageSizeOptions;
+  
+  const validatedInitialPageSize = useMemo(() => {
+    if (!features.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
+    );
+    
+    console.warn(
+      `DataTable: initialPageSize ${initialPageSize} is not available in page size options [${finalPageSizeOptions.join(', ')}]. Using closest option: ${closestOption}`
+    );
+    
+    return closestOption;
+  }, [initialPageSize, finalPageSizeOptions, features.pagination]);
+  
+  const isLoading = externalIsLoading || performanceLoading;
+  
+  // ============================================================================
+  // DATA PROCESSING
+  // ============================================================================
+  
+  // Data comparison utility to prevent unnecessary re-renders
+  const dataComparisonRef = useRef<TData[]>([]);
+  const renderCountRef = useRef(0);
+  const lastDataRef = useRef<TData[]>([]);
+  
+  const isDataEqual = useCallback((newData: TData[], oldData: TData[]) => {
+    if (newData.length !== oldData.length) return false;
+    return newData.every((item, index) => {
+      const oldItem = oldData[index];
+      if (!oldItem) return false;
+      // Shallow comparison of object keys
+      const newKeys = Object.keys(item);
+      const oldKeys = Object.keys(oldItem);
+      if (newKeys.length !== oldKeys.length) return false;
+      return newKeys.every(key => item[key] === oldItem[key]);
+    });
+  }, []);
+  
+  // Infinite loop detection and prevention
+  const preventInfiniteLoop = useCallback((newData: TData[]) => {
+    renderCountRef.current += 1;
+    
+    // If we've rendered too many times with the same data, return the last stable data
+    if (renderCountRef.current > 10 && isDataEqual(newData, lastDataRef.current)) {
+      console.warn('DataTable: Detected potential infinite loop, using last stable data');
+      return lastDataRef.current;
+    }
+    
+    // Reset counter if data actually changed
+    if (!isDataEqual(newData, lastDataRef.current)) {
+      renderCountRef.current = 0;
+      lastDataRef.current = newData;
+    }
+    
+    return newData;
+  }, [isDataEqual]);
+  
+  // Stabilize data references to prevent infinite loops
+  const baseData = useMemo(() => {
+    const newData = finalPaginationMode === 'server' ? (serverData?.data || []) : (processedHierarchicalData as TData[]);
+    
+    // Apply infinite loop prevention
+    const stableData = preventInfiniteLoop(newData);
+    
+    // Only update if data has actually changed
+    if (!isDataEqual(stableData, dataComparisonRef.current)) {
+      dataComparisonRef.current = stableData;
+    }
+    
+    return dataComparisonRef.current;
+  }, [finalPaginationMode, serverData?.data, processedHierarchicalData, preventInfiniteLoop, isDataEqual]);
+  
+  const tableData = useMemo(() => {
+    return features.hierarchical && hierarchical?.enabled 
+      ? hierarchicalState.visibleRows as unknown as TData[]
+      : baseData;
+  }, [features.hierarchical, hierarchical?.enabled, hierarchicalState.visibleRows, baseData]);
+  
+  const dataCount = useMemo(() => {
+    return finalPaginationMode === 'server' ? (serverData?.totalCount || 0) : data?.length || 0;
+  }, [finalPaginationMode, serverData?.totalCount, data?.length]);
+
+  // ============================================================================
+  // HIERARCHICAL SORTING
+  // ============================================================================
+  
+  const sortedTableData = useMemo(() => {
+    if (features.hierarchical && hierarchical?.enabled && sorting.length > 0) {
+      const hierarchicalVisibleRows = hierarchicalState.visibleRows as unknown as HierarchicalDataRow[];
+      return sortHierarchicalDataWithSorting(hierarchicalVisibleRows, sorting) as unknown as TData[];
+    }
+    return tableData;
+  }, [features.hierarchical, hierarchical?.enabled, hierarchicalState.visibleRows, sorting, tableData]);
+  
+  const finalTableData = useMemo(() => {
+    return features.hierarchical && hierarchical?.enabled && sorting.length > 0 
+      ? sortedTableData 
+      : tableData;
+  }, [features.hierarchical, hierarchical?.enabled, sorting.length, sortedTableData, tableData]);
+  
+  const finalDataCount = finalPaginationMode === 'server' ? (serverData?.totalCount || 0) : finalTableData?.length || 0;
+
+  // ============================================================================
+  // ACTIONS PROCESSING
+  // ============================================================================
+
+  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');
+          }
+          // Get the row ID using the provided getRowId function or fallback to row.id
+          const rowId = getRowId ? getRowId(row, 0) : (row as any).id || String(0);
+          // Set the row into editing mode with the current row data
+          tableActions.setEditingRow(rowId, { ...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: (row: TData) => {
+          if (!permissions.canDelete.can) {
+            throw new Error('Insufficient permissions to delete this resource');
+          }
+          secureHandlers.onDeleteRow!(row);
+        },
+        icon: Trash,
+        testId: 'delete',
+        variant: 'destructive' as const,
+        hidden: !permissions.canDelete.can,
+      });
+    }
+
+    return result;
+  }, [actions, secureFeatures, permissions, secureHandlers, getRowId, tableActions]);
+
+  // ============================================================================
+  // COLUMN PROCESSING
+  // ============================================================================
+  
+  const enhancedColumns = useMemo(() => {
+    // Create enhanced base columns
+    const baseColumns: ColumnDef<TData>[] = [...columns].map(column => ({
+      ...column,
+      enableSorting: features.sorting && (column.enableSorting !== false),
+      enableColumnFilter: features.filtering && (column.enableColumnFilter !== false),
+      enableGrouping: features.grouping && (column.enableGrouping !== false),
+    }));
+
+    // Create selection column if enabled
+    const selectionColumn: ColumnDef<TData> | null = features.selection ? {
+      id: 'select',
+      header: ({ table }: HeaderContext<TData, unknown>) => {
+        const isAllSelected = table.getIsAllPageRowsSelected();
+        const isSomeSelected = table.getIsSomePageRowsSelected();
+        return (
+          <Checkbox
+            checked={isAllSelected ? true : isSomeSelected ? 'indeterminate' : false}
+            onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
+            aria-label="Select all"
+          />
+        );
+      },
+      cell: ({ row }: CellContext<TData, unknown>) => (
+        <Checkbox
+          checked={row.getIsSelected()}
+          onCheckedChange={(value) => row.toggleSelected(!!value)}
+          aria-label="Select row"
+        />
+      ),
+      enableSorting: false,
+      enableColumnFilter: false,
+      enableGrouping: false,
+      enableHiding: false,
+      size: 50,
+      minSize: 50,
+      maxSize: 50,
+    } : null;
+
+    // Create actions column if there are actions
+    const actionsColumn: ColumnDef<TData> | null = effectiveActions.length > 0 ? 
+      ColumnFactory.createActionColumn(effectiveActions, {
+        header: 'Actions',
+        size: 120,
+      }) : null;
+
+    // Build final columns array respecting columnOrder
+    const finalColumns: ColumnDef<TData>[] = [];
+    
+    if (columnOrder && columnOrder.length > 0) {
+      // Create set of used column IDs for remaining columns check
+      const usedColumnIds = new Set(columnOrder);
+      
+      // Add selection column first if it wasn't in the order
+      if (selectionColumn && !usedColumnIds.has('select')) {
+        finalColumns.unshift(selectionColumn);
+      }
+      
+      // Use provided columnOrder to arrange columns
+      for (const columnId of columnOrder) {
+        if (columnId === 'select' && selectionColumn) {
+          finalColumns.push(selectionColumn);
+        } else if (columnId === 'actions' && actionsColumn) {
+          finalColumns.push(actionsColumn);
+        } else {
+          // Find the data column by id or accessorKey
+          const dataColumn = baseColumns.find(col => 
+            col.id === columnId || ('accessorKey' in col && String(col.accessorKey) === columnId)
+          );
+          if (dataColumn) {
+            finalColumns.push(dataColumn);
+          }
+        }
+      }
+      
+      // Add any remaining columns that weren't in the columnOrder
+      const remainingDataColumns = baseColumns.filter(col => {
+        const colId = col.id ? String(col.id) : ('accessorKey' in col ? String(col.accessorKey) : '');
+        return !usedColumnIds.has(colId);
+      });
+      finalColumns.push(...remainingDataColumns);
+      
+      // Add actions column if it wasn't in the order
+      if (actionsColumn && !usedColumnIds.has('actions')) {
+        finalColumns.push(actionsColumn);
+      }
+    } else {
+      // No columnOrder provided, use default behavior
+      if (selectionColumn) {
+        finalColumns.push(selectionColumn);
+      }
+      finalColumns.push(...baseColumns);
+      if (actionsColumn) {
+        finalColumns.push(actionsColumn);
+      }
+    }
+
+    return finalColumns;
+  }, [columns, features, effectiveActions, columnOrder]);
+
+  // ============================================================================
+  // COLUMN WIDTHS
+  // ============================================================================
+  
+
+  // ============================================================================
+  // TABLE CONFIGURATION
+  // ============================================================================
+  
+  // Memoize table configuration to prevent unnecessary re-creation
+  const tableConfig = useMemo(() => ({
+    data: finalTableData as TData[],
+    columns: enhancedColumns,
+    state: {
+      sorting,
+      columnFilters,
+      columnVisibility,
+      rowSelection,
+      grouping,
+      expanded,
+      pagination,
+      globalFilter: searchQuery,
+      columnOrder: effectiveColumnOrder,
+    },
+    initialState: {
+      expanded: features.grouping ? {} : undefined,
+    },
+    enableRowSelection: features.selection,
+    enableGrouping: features.grouping,
+    getRowId: getRowId || ((row: TData) => row?.id || row?.toString() || 'unknown'),
+    onSortingChange: setSorting,
+    onColumnFiltersChange: setColumnFilters,
+    onColumnVisibilityChange: setColumnVisibility,
+    onRowSelectionChange: (updaterOrValue: any) => {
+      const newSelection = typeof updaterOrValue === 'function' ? updaterOrValue(rowSelection) : updaterOrValue;
+      setInternalRowSelection(newSelection);
+      onRowSelectionChange?.(newSelection);
+    },
+    onGroupingChange: setGrouping,
+    onExpandedChange: setExpanded,
+    onPaginationChange: setPagination,
+    onColumnOrderChange: setColumnOrder,
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: finalPaginationMode === 'client' ? getFilteredRowModel() : undefined,
+    getSortedRowModel: finalPaginationMode === 'client' ? getSortedRowModel() : undefined,
+    getPaginationRowModel: features.pagination ? getPaginationRowModel() : undefined,
+    getGroupedRowModel: features.grouping ? getGroupedRowModel() : undefined,
+    getExpandedRowModel: features.grouping ? getExpandedRowModel() : undefined,
+    manualSorting: finalPaginationMode === 'server',
+    manualFiltering: finalPaginationMode === 'server',
+    manualPagination: finalPaginationMode === 'server',
+    pageCount: finalPaginationMode === 'server' ? Math.ceil(dataCount / pagination.pageSize) : undefined,
+  }), [
+    finalTableData,
+    enhancedColumns,
+    sorting,
+    columnFilters,
+    columnVisibility,
+    rowSelection,
+    grouping,
+    expanded,
+    pagination,
+    searchQuery,
+    effectiveColumnOrder,
+    features.selection,
+    features.grouping,
+    getRowId,
+    onRowSelectionChange,
+    finalPaginationMode,
+    features.pagination,
+    dataCount,
+    pagination.pageSize
+  ]);
+  
+  const table = useReactTable(tableConfig);
+
+  // ============================================================================
+  // SEARCH HANDLERS
+  // ============================================================================
+  
+  const handleSearch = useCallback((value: string) => {
+    setSearchQuery(value);
+    
+    if (features.pagination) {
+      setPagination(prev => ({ ...prev, pageIndex: 0 }));
+    }
+  }, [setSearchQuery, features.pagination]);
+
+  // ============================================================================
+  // SERVER-SIDE DATA FETCHING
+  // ============================================================================
+  
+  const handleServerSideChange = useCallback(async () => {
+    if (finalPaginationMode !== 'server' || !serverSide) return;
+
+    const params: ServerSideParams = {
+      pageIndex: pagination.pageIndex,
+      pageSize: pagination.pageSize,
+      sorting,
+      columnFilters,
+      globalFilter: searchQuery,
+      grouping,
+    };
+
+    await fetchServerData(params);
+  }, [
+    finalPaginationMode,
+    serverSide,
+    pagination,
+    sorting,
+    columnFilters,
+    searchQuery,
+    grouping,
+    fetchServerData,
+  ]);
+
+  // ============================================================================
+  // EFFECTS
+  // ============================================================================
+  
+  useEffect(() => {
+    if ((tableData?.length || 0) > 0 || finalPaginationMode === 'server') {
+      handleServerSideChange();
+    }
+  }, [handleServerSideChange, tableData?.length, finalPaginationMode]);
+
+  useEffect(() => {
+    return () => {
+      if (typeof cleanup === 'function') {
+        cleanup();
+      }
+    };
+  }, [cleanup]);
+
+  // ============================================================================
+  // RENDER
+  // ============================================================================
+  
+  if (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');
+
+  return (
+    <>
+      {/* Table with semantic HTML structure */}
+      <table className={getTableClasses({
+        isFixed: true,
+        variant,
+        className: cn('border-collapse relative w-full', className)
+      })} style={{ 
+        tableLayout: 'fixed', 
+        width: '100%' 
+      }}>
+        {/* Caption with title, description, and toolbar */}
+        <caption className="text-left pb-2">
+          {(title || description) && (
+            <>
+              {title && <h2 >{title}</h2>}
+              {description && <p>{description}</p>}
+            </>
+          )}
+          <>
+            <DataTableToolbar
+              features={secureFeatures}
+              globalFilter={searchQuery}
+              onGlobalFilterChange={handleSearch}
+              columns={columns}
+              grouping={grouping}
+              onGroupByChange={(columnId) => {
+                setGrouping(columnId ? [columnId] : []);
+              }}
+              tableColumns={table?.getAllColumns() || []}
+              onColumnVisibilityChange={(columnId, visible) => {
+                setColumnVisibility(prev => ({ ...prev, [columnId]: visible }));
+              }}
+              onCreateRow={secureFeatures.creation && secureHandlers.onCreateRow ? () => tableActions.setCreating(true) : undefined}
+              onImportClick={() => setShowImportModal(true)}
+              onExport={secureHandlers.onExport || (() => {
+                // Export logic here
+              })}
+              rowSelection={rowSelection}
+              onDeleteSelected={secureHandlers.onDeleteSelected}
+              onToggleFilterRow={() => setShowFilterRow(!showFilterRow)}
+              showFilterRow={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) => (
+            <tr key={headerGroup.id}>
+              {headerGroup.headers
+                .filter(header => {
+                  return typeof header.column.getIsVisible === 'function' 
+                    ? header.column.getIsVisible() 
+                    : true;
+                })
+                .map((header) => {
+                  const isSortable = header.column.getCanSort();
+                  const ariaSort = isSortable
+                    ? (header.column.getIsSorted() === 'asc'
+                        ? 'ascending'
+                        : header.column.getIsSorted() === 'desc'
+                        ? 'descending'
+                        : 'none')
+                    : undefined;
+                  return (
+                    <th
+                      key={header.id}
+                      {...(isSortable ? { 'aria-sort': ariaSort } : {})}
+                    >
+                      {header.isPlaceholder ? null : (
+                        isSortable ? (
+                          <Button
+                            variant="ghost"
+                            className="h-auto p-0 font-medium hover:bg-transparent"
+                            onClick={header.column.getToggleSortingHandler()}
+                            aria-label={`Sort by ${typeof header.column.columnDef.header === 'string' ? header.column.columnDef.header : 'column'}`}
+                            tabIndex={0}
+                          >
+                            <div className="flex items-center gap-1">
+                              {typeof header.column.columnDef.header === 'function'
+                                ? header.column.columnDef.header(header.getContext())
+                                : header.column.columnDef.header}
+                              {header.column.getIsSorted() === 'asc' ? (
+                                <ChevronUp className="h-4 w-4" />
+                              ) : header.column.getIsSorted() === 'desc' ? (
+                                <ChevronDown className="h-4 w-4" />
+                              ) : (
+                                <ChevronsUpDown className="h-4 w-4" />
+                              )}
+                            </div>
+                          </Button>
+                        ) : (
+                          <div>
+                            {typeof header.column.columnDef.header === 'function'
+                              ? header.column.columnDef.header(header.getContext())
+                              : header.column.columnDef.header}
+                          </div>
+                        )
+                      )}
+                    </th>
+                  );
+                })}
+            </tr>
+          ))}
+        </thead>
+
+        {/* Table body */}
+        <UnifiedTableBody
+            table={table}
+            isCreating={isCreating}
+            creationData={creationData}
+            onCreationDataChange={tableActions.setCreationData}
+            onSaveCreation={() => {
+              if (onCreateRow) {
+                onCreateRow(creationData as Partial<TData>);
+                tableActions.clearCreationData();
+                tableActions.setCreating(false);
+              }
+            }}
+            onCancelCreation={() => {
+              tableActions.clearCreationData();
+              tableActions.setCreating(false);
+            }}
+            editingRowId={editingRowId}
+            editingData={editingData}
+            onEditingDataChange={(data) => {
+              // Update the editing data in the centralized state
+              if (editingRowId) {
+                tableActions.setEditingRow(editingRowId, data);
+              }
+            }}
+            onSaveEditing={() => {
+              if (onEditRow && editingRowId) {
+                // Find the original row data
+                const originalRow = data.find(row => {
+                  const rowId = getRowId ? getRowId(row, 0) : (row as any).id || String(0);
+                  return rowId === editingRowId;
+                });
+                if (originalRow) {
+                  onEditRow(originalRow, editingData as Partial<TData>);
+                }
+              }
+              tableActions.clearEditing();
+            }}
+            onCancelEditing={() => {
+              tableActions.clearEditing();
+            }}
+            grouping={grouping}
+            aggregates={aggregates}
+            getRowId={getRowId}
+            emptyState={React.isValidElement(emptyState) ? undefined : emptyState as any}
+            isFiltered={searchQuery !== '' || columnFilters.length > 0}
+            onClearFilters={() => {
+              setSearchQuery('');
+              setColumnFilters([]);
+            }}
+            enableFiltering={features.filtering}
+            showFilterRow={showFilterRow}
+            enableColumnReordering={features.columnReordering}
+            onColumnOrderChange={setColumnOrder}
+            onColumnDrop={(draggedColumnId, targetColumnId) => {
+              // Handle column drop
+            }}
+            savedColumnOrder={savedColumnOrder}
+            enablePersistence={features.columnReordering}
+            tableId={title ? `datatable-${title.toLowerCase().replace(/\s+/g, '-')}` : undefined}
+            dataLength={finalTableData?.length || 0}
+            virtualHeight={virtualHeight}
+            forceVirtualization={false}
+            hierarchical={features.hierarchical && hierarchical?.enabled ? {
+              ...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 */}
+        {features.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={showImportModal}
+        onCloseImportModal={() => setShowImportModal(false)}
+        onImport={async (data) => {
+          if (onImport) {
+            const result = onImport(data);
+            if (result && typeof result.then === 'function') {
+              await result;
+            }
+          }
+          setShowImportModal(false);
+        }}
+        importModalConfig={importModalConfig}
+      />
+    </>
+  );
+}
+
+// ============================================================================
+// MAIN COMPONENT
+// ============================================================================
+
+export function DataTableCore<TData extends DataRecord>(props: DataTableCoreProps<TData>) {
+  return (
+    <DataTableErrorBoundary>
+      <DataTableInternal {...props} />
+    </DataTableErrorBoundary>
+  );
+}