@jmruthers/pace-core 0.5.76 → 0.5.78

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

@@ -9,24 +9,14 @@
  */
 
 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,
+import { useReactTable, flexRender } 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/cn';
@@ -41,13 +31,14 @@ import { LoadingState } from './LoadingState';
 import { DataTableModals } from './DataTableModals';
 import { DataTableErrorBoundary } from './DataTableErrorBoundary';
 import { useColumnOrderPersistence } from '../hooks/useColumnOrderPersistence';
-import { useHierarchicalState } from '../hooks/useHierarchicalState';
+import { useColumnVisibilityPersistence } from '../hooks/useColumnVisibilityPersistence';
 import { useDataTableState } from '../hooks/useDataTableState';
-import { validateHierarchicalData } from '../utils/hierarchicalUtils';
-import { 
-  sortHierarchicalDataByStructure,
-  sortHierarchicalDataWithSorting 
-} from '../utils/hierarchicalSorting';
+import { useDataTableDataPipeline } from '../hooks/useDataTableDataPipeline';
+import { useServerSideDataEffect } from '../hooks/useServerSideDataEffect';
+import { useEffectiveColumnOrder } from '../hooks/useEffectiveColumnOrder';
+import { useTableHandlers } from '../hooks/useTableHandlers';
+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';
@@ -57,11 +48,14 @@ import { useUnifiedAuth } from '../../../providers/UnifiedAuthProvider';
 import { Scope } from '../../../rbac/types';
 import { useDataTablePermissions } from '../hooks/useDataTablePermissions';
 import { useTableColumns } from '../hooks/useTableColumns';
+import { initializeLiveRegion, announceSortChange } from '../utils/a11yUtils';
+import { useKeyboardNavigation } from '../hooks/useKeyboardNavigation';
+import { getRowIdSafe } from '../utils/rowUtils';
 
-import type { 
+import { normalizeDataTableFeatures } from '../types';
+import type {
   DataRecord,
   GetRowId,
-  ServerSideParams,
   PerformanceConfig,
   ServerSideConfig,
   ChunkingConfig,
@@ -69,16 +63,48 @@ import type {
   PaginationMode,
   EmptyStateConfig,
   DataTableFeatureConfig,
+  NormalizedDataTableFeatureConfig,
   DataTableColumn,
   SimpleColumn,
   AggregateConfig,
   DataTableAction,
   HierarchicalConfig,
-  HierarchicalDataRow,
-  DataTableRBACConfig
+  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
 // ============================================================================
@@ -97,9 +123,9 @@ export interface DataTableCoreProps<TData extends DataRecord> {
   description?: string;
   variant?: 'default' | 'compact' | 'spacious';
   className?: string;
-  
+
   // Feature configuration
-  features: DataTableFeatureConfig;
+  features?: DataTableFeatureConfig;
   
   // Hierarchical configuration
   hierarchical?: HierarchicalConfig;
@@ -138,6 +164,10 @@ export interface DataTableCoreProps<TData extends DataRecord> {
   // Default state configuration
   defaultGrouping?: string[];
   defaultSorting?: SortingState;
+  
+  // Persistence configuration
+  storageKey?: string;
+  onLayoutChange?: (layout: { columnOrder: string[]; columnVisibility: Record<string, boolean> }) => void;
 }
 
 // ============================================================================
@@ -152,7 +182,7 @@ function DataTableInternal<TData extends DataRecord>({
   description,
   variant = 'default',
   className,
-  features,
+  features: incomingFeatures = {},
   hierarchical,
   performance = {},
   serverSide,
@@ -181,6 +211,8 @@ function DataTableInternal<TData extends DataRecord>({
   columnOrder: externalColumnOrder,
   defaultGrouping,
   defaultSorting,
+  storageKey,
+  onLayoutChange,
 }: DataTableCoreProps<TData>) {
   
   // ============================================================================
@@ -191,27 +223,45 @@ function DataTableInternal<TData extends DataRecord>({
   const authResult = useUnifiedAuth();
   const user = authResult.user;
 
+  const requestedFeatures = useMemo<NormalizedDataTableFeatureConfig>(() =>
+    normalizeDataTableFeatures(incomingFeatures),
+  [incomingFeatures]);
+
   // MANDATORY: Get permissions and secure features
-  const { permissions, secureFeatures, effectivePageId } = useDataTablePermissions(rbac, features);
+  const { permissions, secureFeatures, effectivePageId } = useDataTablePermissions(rbac, requestedFeatures);
   
   // ============================================================================
   // UNIFIED STATE MANAGEMENT - Use ONLY useDataTableState for all state
   // ============================================================================
   
-  // Calculate initial column order - include selection column if needed
-  const baseColumnOrder = useMemo(() => {
-    if (externalColumnOrder && externalColumnOrder.length > 0) {
-      return externalColumnOrder;
-    }
-    return columns.map(col => col.id || col.accessorKey || '').filter(Boolean);
-  }, [externalColumnOrder, columns]);
+  const effectiveColumnOrder = useEffectiveColumnOrder({
+    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: {},
+    enablePersistence: secureFeatures.columnVisibility,
+    storageKey,
+  });
   
-  const effectiveColumnOrder = useMemo(() => {
-    if (features.selection && !baseColumnOrder.includes('select')) {
-      return ['select', ...baseColumnOrder];
+  // Merge saved column visibility into initial state
+  const initialColumnVisibility = useMemo(() => {
+    if (secureFeatures.columnVisibility && savedColumnVisibility && Object.keys(savedColumnVisibility).length > 0) {
+      return savedColumnVisibility;
     }
-    return baseColumnOrder;
-  }, [baseColumnOrder, features.selection]);
+    return {};
+  }, [secureFeatures.columnVisibility, savedColumnVisibility]);
   
   // Use the centralized state management hook for ALL table state
   // Note: 'actions' prop parameter is shadowed by destructuring, so we rename to stateActions
@@ -224,8 +274,25 @@ function DataTableInternal<TData extends DataRecord>({
     defaultGrouping: defaultGrouping || []
   });
   
+  // 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
@@ -262,8 +329,6 @@ function DataTableInternal<TData extends DataRecord>({
     paginationMode: detectedMode,
     isVirtualized,
     pageSizeOptions: optimizedPageSizeOptions,
-    processedData,
-    totalCount,
     isLoading: performanceLoading,
     searchQuery,
     setSearchQuery,
@@ -272,37 +337,63 @@ function DataTableInternal<TData extends DataRecord>({
     cleanup,
   } = performanceHook;
 
+  const finalPaginationMode = paginationMode || detectedMode;
+
   // ============================================================================
-  // HIERARCHICAL DATA VALIDATION AND PROCESSING - ALWAYS call these hooks
+  // KEYBOARD NAVIGATION - ALWAYS call this hook
   // ============================================================================
   
-  const hierarchicalValidation = useMemo(() => {
-    if (features.hierarchical && hierarchical?.enabled) {
-      return validateHierarchicalData(data as unknown as HierarchicalDataRow[]);
+  const keyboardNavigation = useKeyboardNavigation(
+    data.length,
+    columns.length,
+    {
+      enabled: true,
+      announceNavigation: true,
+      supportsColumnReorder: secureFeatures.columnReordering,
+      supportsColumnResize: false, // Column resizing is not currently supported
     }
-    return { isValid: true, errors: [] };
-  }, [features.hierarchical, hierarchical?.enabled, data]);
+  );
 
-  const processedHierarchicalData = useMemo(() => {
-    if (features.hierarchical && hierarchical?.enabled && hierarchicalValidation.isValid) {
-      return sortHierarchicalDataByStructure(data as unknown as HierarchicalDataRow[]);
+  // Store focus when modals open, restore when they close
+  useEffect(() => {
+    if (state.showImportModal) {
+      keyboardNavigation.storeFocus();
     }
-    return data;
-  }, [features.hierarchical, hierarchical?.enabled, hierarchicalValidation.isValid, data]);
+  }, [state.showImportModal, keyboardNavigation]);
 
-  // ============================================================================
-  // HIERARCHICAL STATE MANAGEMENT - ALWAYS call these hooks
-  // ============================================================================
-  
-  const hierarchicalState = useHierarchicalState(
-    processedHierarchicalData as unknown as HierarchicalDataRow[],
-    hierarchical
-  );
+  useEffect(() => {
+    if (!state.showImportModal) {
+      // Restore focus after modal closes
+      setTimeout(() => {
+        keyboardNavigation.restoreFocus();
+      }, 100); // Small delay to ensure modal is fully closed
+    }
+  }, [state.showImportModal, keyboardNavigation]);
 
   // ============================================================================
-  // COLUMN ORDER PERSISTENCE - ALWAYS call these hooks
+  // HIERARCHICAL DATA VALIDATION AND PROCESSING - ALWAYS call these hooks
   // ============================================================================
   
+  const {
+    finalTableData,
+    dataCount: finalDataCount,
+    hierarchicalState,
+    hierarchicalValidation,
+  } = useDataTableDataPipeline<TData>({
+    data,
+    features: secureFeatures,
+    hierarchical,
+    sorting: state.sorting,
+    finalPaginationMode,
+    serverData,
+  });
+
+  useEffect(() => {
+    if (!hierarchicalValidation.isValid && import.meta.env?.MODE === 'development') {
+      console.error('[DataTable] Hierarchical data validation failed:', hierarchicalValidation.errors);
+    }
+  }, [hierarchicalValidation]);
+
   const {
     columnOrder: savedColumnOrder,
     isLoaded: isColumnOrderLoaded,
@@ -310,18 +401,29 @@ function DataTableInternal<TData extends DataRecord>({
   } = useColumnOrderPersistence({
     tableId: title ? `datatable-${title.toLowerCase().replace(/\s+/g, '-')}` : undefined,
     defaultOrder: columns.map(col => col.id || col.accessorKey || ''),
-    enablePersistence: features.columnReordering,
+    enablePersistence: secureFeatures.columnReordering,
+    storageKey,
   });
 
+  useEffect(() => {
+    if (
+      secureFeatures.columnReordering &&
+      isColumnOrderLoaded &&
+      savedColumnOrder &&
+      savedColumnOrder.length > 0
+    ) {
+      stateActions.setColumnOrder(savedColumnOrder);
+    }
+  }, [secureFeatures.columnReordering, isColumnOrderLoaded, savedColumnOrder, stateActions]);
+
   // ============================================================================
   // CONFIGURATION RESOLUTION - ALWAYS call these hooks
   // ============================================================================
   
-  const finalPaginationMode = paginationMode || detectedMode;
   const finalPageSizeOptions = optimizedPageSizeOptions;
   
   const validatedInitialPageSize = useMemo(() => {
-    if (!features.pagination || !finalPageSizeOptions.length) {
+    if (!secureFeatures.pagination || !finalPageSizeOptions.length) {
       return initialPageSize;
     }
     
@@ -334,12 +436,14 @@ function DataTableInternal<TData extends DataRecord>({
       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}`
-    );
+    if (import.meta.env?.MODE === 'development') {
+      console.warn(
+        `DataTable: initialPageSize ${initialPageSize} is not available in page size options [${finalPageSizeOptions.join(', ')}]. Using closest option: ${closestOption}`
+      );
+    }
     
     return closestOption;
-  }, [initialPageSize, finalPageSizeOptions, features.pagination]);
+  }, [initialPageSize, finalPageSizeOptions, secureFeatures.pagination]);
   
   const isLoading = externalIsLoading || performanceLoading;
   
@@ -347,43 +451,6 @@ function DataTableInternal<TData extends DataRecord>({
   // DATA PROCESSING - ALWAYS call these hooks
   // ============================================================================
   
-  // Get base data based on pagination mode - use simple memoization
-  const baseData = useMemo(() => {
-    return finalPaginationMode === 'server' 
-      ? (serverData?.data || []) 
-      : (processedHierarchicalData as TData[]);
-  }, [finalPaginationMode, serverData?.data, processedHierarchicalData]);
-  
-  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 - ALWAYS call these hooks
-  // ============================================================================
-  
-  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 - ALWAYS call these hooks
   // ============================================================================
@@ -413,10 +480,10 @@ function DataTableInternal<TData extends DataRecord>({
     stateActions.setSearchQuery(value);
     
     // Reset to first page when searching to show results from the beginning
-    if (features.pagination) {
+    if (secureFeatures.pagination) {
       stateActions.setPagination({ ...state.pagination, pageIndex: 0 });
     }
-  }, [stateActions, features.pagination, state.pagination]);
+  }, [stateActions, secureFeatures.pagination, state.pagination]);
 
   // ============================================================================
   // SERVER-SIDE DATA FETCHING - ALWAYS call these hooks
@@ -439,68 +506,18 @@ function DataTableInternal<TData extends DataRecord>({
    * - Component is in client-side mode (finalPaginationMode !== 'server')
    * - No server-side config is provided (!serverSide)
    */
-  const handleServerSideChange = useCallback(async () => {
-    if (finalPaginationMode !== 'server' || !serverSide) return;
-
-    const params: ServerSideParams = {
-      pageIndex: state.pagination.pageIndex,
-      pageSize: state.pagination.pageSize,
-      sorting: state.sorting,
-      columnFilters: state.columnFilters,
-      globalFilter: searchQuery,
-      grouping: state.grouping,
-    };
-
-    await fetchServerData(params);
-  }, [
+  useServerSideDataEffect<TData>({
     finalPaginationMode,
     serverSide,
-    state.pagination,
-    state.sorting,
-    state.columnFilters,
+    pagination: state.pagination,
+    sorting: state.sorting,
+    columnFilters: state.columnFilters,
+    grouping: state.grouping,
     searchQuery,
-    state.grouping,
+    tableDataLength: finalTableData.length,
     fetchServerData,
-  ]);
-
-  // ============================================================================
-  // EFFECTS - ALWAYS call these hooks
-  // ============================================================================
-  
-  /**
-   * Effect: Trigger server-side data fetch when table state changes.
-   * 
-   * This effect watches for changes to table state that require a server-side fetch:
-   * - Sorting changes
-   * - Filtering changes
-   * - Pagination changes
-   * - Grouping changes
-   * 
-   * The effect includes multiple guards to prevent unnecessary server calls:
-   * - Skip if not in server-side mode
-   * - Skip if no server-side config provided
-   * - Skip if we already have data in client-side mode
-   * 
-   * This prevents infinite loops and unnecessary network requests.
-   */
-  useEffect(() => {
-    // Only trigger server-side fetch in server mode
-    if (finalPaginationMode !== 'server') return;
-    if (!serverSide) return;
-    
-    // For client-side mode with data, no server fetch needed
-    if (tableData && tableData.length > 0 && finalPaginationMode !== 'server') return;
-    
-    handleServerSideChange();
-  }, [handleServerSideChange, tableData, finalPaginationMode, serverSide]);
-
-  useEffect(() => {
-    return () => {
-      if (typeof cleanup === 'function') {
-        cleanup();
-      }
-    };
-  }, [cleanup]);
+    cleanup,
+  });
 
   // ============================================================================
   // RBAC VALIDATION AND SECURE CONFIGURATION - ALWAYS call these hooks
@@ -548,23 +565,12 @@ function DataTableInternal<TData extends DataRecord>({
           if (!permissions.canUpdate.can) {
             throw new Error('Insufficient permissions to edit this resource');
           }
-          // CRITICAL: Calculate rowId the same way as in DataTableBody
-          // Find the index of this row in the data array
-          let rowId: string;
-          if (getRowId) {
-            const rowIndex = data.findIndex(r => r === row);
-            rowId = getRowId(row, rowIndex);
-          } else {
-            rowId = (row as any).id;
-          }
-          
-          if (!rowId) {
-            console.error('[DataTable] Cannot edit row: no id found. Make sure to provide getRowId or ensure row data has an id property.');
-            return;
-          }
-          
+
+          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, { ...row });
+          stateActions.setEditingRow(rowId, toCellValueRecord(row));
         },
         icon: Edit,
         testId: 'edit',
@@ -599,7 +605,7 @@ function DataTableInternal<TData extends DataRecord>({
     }
 
     return result;
-  }, [actions, secureFeatures, permissions, secureHandlers, getRowId, stateActions]);
+  }, [actions, secureFeatures, permissions, secureHandlers, resolvedGetRowId, stateActions, data]);
 
   // MANDATORY: Process columns with actions
   const { enhancedColumns } = useTableColumns({
@@ -609,114 +615,17 @@ function DataTableInternal<TData extends DataRecord>({
     columnOrder: state.columnOrder
   });
 
-  // MANDATORY: Memoize table configuration to prevent unnecessary re-creation
-  const tableConfig = useMemo(() => ({
-    data: finalTableData as TData[],
-    columns: enhancedColumns,
-            state: {
-      sorting: state.sorting,
-      columnFilters: state.columnFilters,
-      columnVisibility: state.columnVisibility,
-      rowSelection,
-      grouping: state.grouping,
-      expanded: state.expanded,
-      pagination: state.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: (updaterOrValue: unknown) => {
-      const newSorting = typeof updaterOrValue === 'function' 
-        ? (updaterOrValue as (prev: SortingState) => SortingState)(state.sorting)
-        : updaterOrValue as SortingState;
-      stateActions.setSorting(newSorting);
-    },
-    onColumnFiltersChange: (updaterOrValue: unknown) => {
-      const newFilters = typeof updaterOrValue === 'function' 
-        ? (updaterOrValue as (prev: ColumnFiltersState) => ColumnFiltersState)(state.columnFilters)
-        : updaterOrValue as ColumnFiltersState;
-      stateActions.setColumnFilters(newFilters);
-    },
-    onColumnVisibilityChange: (updaterOrValue: unknown) => {
-      // Handle both function and value updates from TanStack Table
-      const newVisibility = typeof updaterOrValue === 'function' 
-        ? (updaterOrValue as (prev: VisibilityState) => VisibilityState)(state.columnVisibility) 
-        : updaterOrValue as VisibilityState;
-      stateActions.setColumnVisibility(newVisibility);
-    },
-    onRowSelectionChange: (updaterOrValue: unknown) => {
-      /**
-       * Row selection change handler supporting both controlled and uncontrolled modes.
-       * 
-       * TanStack Table can call with either:
-       * - A value: `{ rowId: true, rowId2: false }`
-       * - A function: `(prev) => ({ ...prev, rowId: true })`
-       * 
-       * We handle both patterns to support the full TanStack API.
-       */
-      const newSelection = typeof updaterOrValue === 'function' 
-        ? (updaterOrValue as (prev: Record<string, boolean>) => Record<string, boolean>)(selection !== undefined ? selection : state.rowSelection) 
-        : updaterOrValue as Record<string, boolean>;
-      
-      /**
-       * Controlled vs Uncontrolled Mode:
-       * 
-       * - Uncontrolled (selection prop is undefined): Update internal state
-       * - Controlled (selection prop is provided): Don't update internal state,
-       *   let parent manage state, but still notify parent of changes
-       * 
-       * This pattern allows DataTable to work both as a self-contained component
-       * and as a fully controlled component in complex forms/parent apps.
-       */
-      if (selection === undefined) {
-        stateActions.setRowSelection(newSelection);
-      }
-      
-      // Always notify parent component so it can react to selection changes
-      onRowSelectionChange?.(newSelection);
-    },
-    onGroupingChange: (updaterOrValue: unknown) => {
-      const newGrouping = typeof updaterOrValue === 'function' 
-        ? (updaterOrValue as (prev: GroupingState) => GroupingState)(state.grouping)
-        : updaterOrValue as GroupingState;
-      stateActions.setGrouping(newGrouping);
-    },
-    onExpandedChange: (updaterOrValue: unknown) => {
-      const newExpanded = typeof updaterOrValue === 'function' 
-        ? (updaterOrValue as (prev: ExpandedState) => ExpandedState)(state.expanded)
-        : updaterOrValue as ExpandedState;
-      stateActions.setExpanded(newExpanded);
-    },
-    onPaginationChange: (updaterOrValue: unknown) => {
-      const newPagination = typeof updaterOrValue === 'function' 
-        ? (updaterOrValue as (prev: PaginationState) => PaginationState)(state.pagination)
-        : updaterOrValue as PaginationState;
-      stateActions.setPagination(newPagination);
-    },
-    onColumnOrderChange: (updaterOrValue: unknown) => {
-      const newOrder = typeof updaterOrValue === 'function' 
-        ? (updaterOrValue as (prev: string[]) => string[])(state.columnOrder)
-        : updaterOrValue as string[];
-      stateActions.setColumnOrder(newOrder);
-    },
-    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 / state.pagination.pageSize) : undefined,
+  const tableStateSnapshot = useMemo<TableStateSnapshot<TData>>(() => ({
+    sorting: state.sorting,
+    columnFilters: state.columnFilters,
+    columnVisibility: state.columnVisibility,
+    rowSelection,
+    grouping: state.grouping,
+    expanded: state.expanded,
+    pagination: state.pagination,
+    globalFilter: searchQuery,
+    columnOrder: state.columnOrder,
   }), [
-    finalTableData,
-    enhancedColumns,
     state.sorting,
     state.columnFilters,
     state.columnVisibility,
@@ -725,16 +634,34 @@ function DataTableInternal<TData extends DataRecord>({
     state.expanded,
     state.pagination,
     searchQuery,
-    effectiveColumnOrder,
-    features.selection,
-    features.grouping,
-    getRowId,
+    state.columnOrder,
+  ]);
+
+  const tableHandlers = useTableHandlers({
+    state,
+    stateSnapshot: tableStateSnapshot,
+    actions: stateActions,
+    selection,
     onRowSelectionChange,
+    effectiveColumnOrder,
+    canPersistVisibility: secureFeatures.columnVisibility && Boolean(storageKey),
+    canPersistOrder: secureFeatures.columnReordering && Boolean(storageKey),
+    updateSavedColumnVisibility,
+    updateColumnOrder,
+    onLayoutChange,
+  });
+
+  const tableConfig = useDataTableConfiguration({
+    data: finalTableData as TData[],
+    columns: enhancedColumns,
+    stateSnapshot: tableStateSnapshot,
+    handlers: tableHandlers,
+    features: secureFeatures,
+    getRowId: resolvedGetRowId,
     finalPaginationMode,
-    features.pagination,
-    dataCount,
-    state.pagination.pageSize
-  ]);
+    finalDataCount,
+    pageSize: state.pagination.pageSize,
+  });
   
   const table = useReactTable(tableConfig);
 
@@ -776,20 +703,22 @@ function DataTableInternal<TData extends DataRecord>({
   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%' 
-      }}>
+      <table 
+        className={getTableClasses({
+          isFixed: true,
+          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>{description}</p>}
+              {description && <p id="table-description">{description}</p>}
             </>
           )}
           <>
@@ -871,9 +800,9 @@ function DataTableInternal<TData extends DataRecord>({
 
         {/* Column groups */}
         <colgroup>
-          {hasSelectColumn && <col span={1} data-col-type="select" />}
+          {hasSelectColumn && <col span={1} data-col-type="select" className="w-12" />}
           <col span={dataColumns} data-col-type="data" />
-          {hasActionsColumn && <col span={1} data-col-type="actions" />}
+          {hasActionsColumn && <col span={1} data-col-type="actions"/>}
         </colgroup>
 
         {/* Table header */}
@@ -895,39 +824,78 @@ function DataTableInternal<TData extends DataRecord>({
                         ? '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={`px-3 py-2 ${isRightAligned ? 'text-right' : 'text-left'}`}
+                      scope="col"
+                      role="columnheader"
                       {...(isSortable ? { 'aria-sort': ariaSort } : {})}
+                      {...(isSortable ? headerKeyboardHandlers : {})}
                     >
                       {header.isPlaceholder ? null : (
                         isSortable ? (
                           <Button
                             variant="ghost"
-                            className="h-auto p-0 font-medium hover:bg-transparent"
-                            onClick={header.column.getToggleSortingHandler()}
+                            className={`h-auto p-0 font-medium 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}
                           >
-                        <div className={`flex items-center gap-1 ${header.column.columnDef.meta?.align === 'right' ? 'justify-end' : ''}`}>
-                          {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 className={header.column.columnDef.meta?.align === 'right' ? 'text-right' : ''}>
                             {typeof header.column.columnDef.header === 'function'
                               ? header.column.columnDef.header(header.getContext())
                               : header.column.columnDef.header}
-                          </div>
+                            {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" />
+                            )}
+                          </Button>
+                        ) : (
+                          typeof header.column.columnDef.header === 'function'
+                            ? header.column.columnDef.header(header.getContext())
+                            : header.column.columnDef.header
                         )
                       )}
                     </th>
@@ -966,8 +934,12 @@ function DataTableInternal<TData extends DataRecord>({
               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;
+                  try {
+                    const rowId = resolvedGetRowId(row, 0);
+                    return rowId === editingRowId;
+                  } catch {
+                    return false;
+                  }
                 });
                 if (originalRow) {
                   onEditRow(originalRow, editingData as Partial<TData>);
@@ -980,19 +952,19 @@ function DataTableInternal<TData extends DataRecord>({
             }}
             grouping={state.grouping}
             aggregates={aggregates}
-            getRowId={getRowId}
+            getRowId={resolvedGetRowId}
             emptyState={React.isValidElement(emptyState) ? undefined : emptyState as any}
             isFiltered={searchQuery !== '' || state.columnFilters.length > 0}
             onClearFilters={() => {
               stateActions.setSearchQuery('');
               stateActions.setColumnFilters([]);
             }}
-            enableFiltering={features.filtering}
+            enableFiltering={secureFeatures.filtering}
             showFilterRow={showFilterRow}
             dataLength={finalTableData?.length || 0}
             virtualHeight={virtualHeight}
             forceVirtualization={false}
-            hierarchical={features.hierarchical && hierarchical?.enabled ? {
+            hierarchical={secureFeatures.hierarchical && hierarchical?.enabled && hierarchicalState ? {
               ...hierarchical,
               state: hierarchicalState,
               expandAll: hierarchicalState.expandAll,
@@ -1007,7 +979,7 @@ function DataTableInternal<TData extends DataRecord>({
           />
 
         {/* Table footer with pagination */}
-        {features.pagination && (
+        {secureFeatures.pagination && (
           <tfoot>
             <tr>
               <td colSpan={visibleColumns.length}>