@jmruthers/pace-core 0.5.76 → 0.5.78

package/src/components/DataTable/hooks/useKeyboardNavigation.ts

@@ -0,0 +1,447 @@
+/**
+ * @file Keyboard Navigation Hook for DataTable
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Hooks
+ * @since 0.4.0
+ * 
+ * Comprehensive keyboard navigation and focus management for DataTable.
+ * Implements roving tabindex pattern for efficient keyboard navigation.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { announce } from '../utils/a11yUtils';
+
+export interface KeyboardNavigationOptions {
+  /** Whether keyboard navigation is enabled */
+  enabled?: boolean;
+  /** Whether to announce navigation changes */
+  announceNavigation?: boolean;
+  /** Whether column reordering is supported */
+  supportsColumnReorder?: boolean;
+  /** Whether column resizing is supported */
+  supportsColumnResize?: boolean;
+  /** Callback when focus moves to a new cell */
+  onFocusChange?: (rowIndex: number, columnIndex: number) => void;
+  /** Table ref for DOM queries */
+  tableRef?: React.RefObject<HTMLTableElement>;
+}
+
+export interface KeyboardNavigationState {
+  /** Current focused row index */
+  focusedRowIndex: number;
+  /** Current focused column index */
+  focusedColumnIndex: number;
+  /** Whether keyboard navigation is active */
+  isNavigating: boolean;
+}
+
+export interface UseKeyboardNavigationReturn {
+  /** Current navigation state */
+  state: KeyboardNavigationState;
+  /** Focus a specific cell */
+  focusCell: (rowIndex: number, columnIndex: number) => void;
+  /** Move focus to next cell */
+  focusNext: () => void;
+  /** Move focus to previous cell */
+  focusPrevious: () => void;
+  /** Move focus up one row */
+  focusUp: () => void;
+  /** Move focus down one row */
+  focusDown: () => void;
+  /** Move focus to first cell in row */
+  focusRowStart: () => void;
+  /** Move focus to last cell in row */
+  focusRowEnd: () => void;
+  /** Move focus to first row */
+  focusTableStart: () => void;
+  /** Move focus to last row */
+  focusTableEnd: () => void;
+  /** Get tabindex for a cell */
+  getCellTabIndex: (rowIndex: number, columnIndex: number) => number;
+  /** Get keyboard event handlers for a cell */
+  getCellKeyboardHandlers: (rowIndex: number, columnIndex: number) => {
+    onKeyDown: (event: React.KeyboardEvent) => void;
+    onFocus: (event: React.FocusEvent) => void;
+    onBlur: (event: React.FocusEvent) => void;
+  };
+  /** Get keyboard event handlers for headers */
+  getHeaderKeyboardHandlers: (columnIndex: number, onSort?: () => void) => {
+    onKeyDown: (event: React.KeyboardEvent) => void;
+    onFocus: (event: React.FocusEvent) => void;
+  };
+  /** Reset focus state */
+  resetFocus: () => void;
+  /** Store focus for restoration */
+  storeFocus: () => void;
+  /** Restore previously stored focus */
+  restoreFocus: () => void;
+}
+
+/**
+ * Hook for managing keyboard navigation in DataTable
+ */
+export function useKeyboardNavigation(
+  rowCount: number,
+  columnCount: number,
+  options: KeyboardNavigationOptions = {}
+): UseKeyboardNavigationReturn {
+  const {
+    enabled = true,
+    announceNavigation = true,
+    supportsColumnReorder = false,
+    supportsColumnResize = false,
+    onFocusChange,
+    tableRef: externalTableRef,
+  } = options;
+
+  // Navigation state
+  const [state, setState] = useState<KeyboardNavigationState>({
+    focusedRowIndex: 0,
+    focusedColumnIndex: 0,
+    isNavigating: false,
+  });
+
+  // Refs for focus management
+  const internalTableRef = useRef<HTMLTableElement>(null);
+  const tableRef = externalTableRef || internalTableRef;
+  const storedFocusRef = useRef<{ rowIndex: number; columnIndex: number } | null>(null);
+  const navigationTimeoutRef = useRef<NodeJS.Timeout>();
+
+  // Helper to get cell element
+  const getCellElement = useCallback((rowIndex: number, columnIndex: number): HTMLElement | null => {
+    if (!tableRef.current) return null;
+    
+    const tbody = tableRef.current.querySelector('tbody');
+    if (!tbody) return null;
+    
+    const rows = tbody.querySelectorAll('tr[role="row"]');
+    const row = rows[rowIndex];
+    if (!row) return null;
+    
+    const cells = row.querySelectorAll('td[role="cell"], th[role="columnheader"]');
+    return cells[columnIndex] as HTMLElement || null;
+  }, []);
+
+  // Helper to get header element
+  const getHeaderElement = useCallback((columnIndex: number): HTMLElement | null => {
+    if (!tableRef.current) return null;
+    
+    const thead = tableRef.current.querySelector('thead');
+    if (!thead) return null;
+    
+    const headerRow = thead.querySelector('tr[role="row"]');
+    if (!headerRow) return null;
+    
+    const headers = headerRow.querySelectorAll('th[role="columnheader"]');
+    return headers[columnIndex] as HTMLElement || null;
+  }, []);
+
+  // Focus a specific cell
+  const focusCell = useCallback((rowIndex: number, columnIndex: number) => {
+    if (!enabled) return;
+    
+    // Clamp values to valid range
+    const clampedRowIndex = Math.max(0, Math.min(rowIndex, rowCount - 1));
+    const clampedColumnIndex = Math.max(0, Math.min(columnIndex, columnCount - 1));
+    
+    setState(prev => ({
+      ...prev,
+      focusedRowIndex: clampedRowIndex,
+      focusedColumnIndex: clampedColumnIndex,
+      isNavigating: true,
+    }));
+    
+    // Focus the actual element
+    const cellElement = getCellElement(clampedRowIndex, clampedColumnIndex);
+    if (cellElement) {
+      cellElement.focus();
+    }
+    
+    // Notify callback
+    onFocusChange?.(clampedRowIndex, clampedColumnIndex);
+    
+    // Announce navigation if enabled
+    if (announceNavigation) {
+      announce(`Row ${clampedRowIndex + 1}, Column ${clampedColumnIndex + 1}`);
+    }
+  }, [enabled, rowCount, columnCount, getCellElement, onFocusChange, announceNavigation]);
+
+  // Navigation functions
+  const focusNext = useCallback(() => {
+    const { focusedRowIndex, focusedColumnIndex } = state;
+    if (focusedColumnIndex < columnCount - 1) {
+      focusCell(focusedRowIndex, focusedColumnIndex + 1);
+    } else if (focusedRowIndex < rowCount - 1) {
+      focusCell(focusedRowIndex + 1, 0);
+    }
+  }, [state, columnCount, rowCount, focusCell]);
+
+  const focusPrevious = useCallback(() => {
+    const { focusedRowIndex, focusedColumnIndex } = state;
+    if (focusedColumnIndex > 0) {
+      focusCell(focusedRowIndex, focusedColumnIndex - 1);
+    } else if (focusedRowIndex > 0) {
+      focusCell(focusedRowIndex - 1, columnCount - 1);
+    }
+  }, [state, columnCount, focusCell]);
+
+  const focusUp = useCallback(() => {
+    const { focusedRowIndex, focusedColumnIndex } = state;
+    if (focusedRowIndex > 0) {
+      focusCell(focusedRowIndex - 1, focusedColumnIndex);
+    }
+  }, [state, focusCell]);
+
+  const focusDown = useCallback(() => {
+    const { focusedRowIndex, focusedColumnIndex } = state;
+    if (focusedRowIndex < rowCount - 1) {
+      focusCell(focusedRowIndex + 1, focusedColumnIndex);
+    }
+  }, [state, rowCount, focusCell]);
+
+  const focusRowStart = useCallback(() => {
+    const { focusedRowIndex } = state;
+    focusCell(focusedRowIndex, 0);
+  }, [state, focusCell]);
+
+  const focusRowEnd = useCallback(() => {
+    const { focusedRowIndex } = state;
+    focusCell(focusedRowIndex, columnCount - 1);
+  }, [state, columnCount, focusCell]);
+
+  const focusTableStart = useCallback(() => {
+    focusCell(0, 0);
+  }, [focusCell]);
+
+  const focusTableEnd = useCallback(() => {
+    focusCell(rowCount - 1, columnCount - 1);
+  }, [rowCount, columnCount, focusCell]);
+
+  // Get tabindex for roving tabindex pattern
+  const getCellTabIndex = useCallback((rowIndex: number, columnIndex: number): number => {
+    if (!enabled) return -1;
+    
+    // Only the focused cell should be tabbable
+    return (state.focusedRowIndex === rowIndex && state.focusedColumnIndex === columnIndex) ? 0 : -1;
+  }, [enabled, state.focusedRowIndex, state.focusedColumnIndex]);
+
+  // Cell keyboard handlers
+  const getCellKeyboardHandlers = useCallback((rowIndex: number, columnIndex: number) => {
+    const onKeyDown = (event: React.KeyboardEvent) => {
+      if (!enabled) return;
+      
+      switch (event.key) {
+        case 'ArrowRight':
+          event.preventDefault();
+          if (event.ctrlKey || event.metaKey) {
+            focusRowEnd();
+          } else {
+            focusNext();
+          }
+          break;
+          
+        case 'ArrowLeft':
+          event.preventDefault();
+          if (event.ctrlKey || event.metaKey) {
+            focusRowStart();
+          } else {
+            focusPrevious();
+          }
+          break;
+          
+        case 'ArrowDown':
+          event.preventDefault();
+          if (event.ctrlKey || event.metaKey) {
+            focusTableEnd();
+          } else {
+            focusDown();
+          }
+          break;
+          
+        case 'ArrowUp':
+          event.preventDefault();
+          if (event.ctrlKey || event.metaKey) {
+            focusTableStart();
+          } else {
+            focusUp();
+          }
+          break;
+          
+        case 'Home':
+          event.preventDefault();
+          if (event.ctrlKey || event.metaKey) {
+            focusTableStart();
+          } else {
+            focusRowStart();
+          }
+          break;
+          
+        case 'End':
+          event.preventDefault();
+          if (event.ctrlKey || event.metaKey) {
+            focusTableEnd();
+          } else {
+            focusRowEnd();
+          }
+          break;
+          
+        case 'Tab':
+          // Let Tab work normally for accessibility
+          break;
+          
+        default:
+          // Don't prevent default for other keys
+          break;
+      }
+    };
+
+    const onFocus = (event: React.FocusEvent) => {
+      setState(prev => ({
+        ...prev,
+        focusedRowIndex: rowIndex,
+        focusedColumnIndex: columnIndex,
+        isNavigating: true,
+      }));
+      
+      onFocusChange?.(rowIndex, columnIndex);
+    };
+
+    const onBlur = (event: React.FocusEvent) => {
+      // Clear navigation state after a delay to allow for focus transitions
+      if (navigationTimeoutRef.current) {
+        clearTimeout(navigationTimeoutRef.current);
+      }
+      
+      navigationTimeoutRef.current = setTimeout(() => {
+        setState(prev => ({
+          ...prev,
+          isNavigating: false,
+        }));
+      }, 100);
+    };
+
+    return { onKeyDown, onFocus, onBlur };
+  }, [enabled, focusNext, focusPrevious, focusUp, focusDown, focusRowStart, focusRowEnd, focusTableStart, focusTableEnd, onFocusChange]);
+
+  // Header keyboard handlers
+  const getHeaderKeyboardHandlers = useCallback((columnIndex: number, onSort?: () => void) => {
+    const onKeyDown = (event: React.KeyboardEvent) => {
+      if (!enabled) return;
+      
+      switch (event.key) {
+        case 'Enter':
+        case ' ':
+          event.preventDefault();
+          onSort?.();
+          break;
+          
+        case 'ArrowRight':
+          event.preventDefault();
+          const nextHeader = getHeaderElement(columnIndex + 1);
+          if (nextHeader) {
+            nextHeader.focus();
+          }
+          break;
+          
+        case 'ArrowLeft':
+          event.preventDefault();
+          const prevHeader = getHeaderElement(columnIndex - 1);
+          if (prevHeader) {
+            prevHeader.focus();
+          }
+          break;
+          
+        case 'Home':
+          event.preventDefault();
+          const firstHeader = getHeaderElement(0);
+          if (firstHeader) {
+            firstHeader.focus();
+          }
+          break;
+          
+        case 'End':
+          event.preventDefault();
+          const lastHeader = getHeaderElement(columnCount - 1);
+          if (lastHeader) {
+            lastHeader.focus();
+          }
+          break;
+          
+        // Disable unsupported keyboard operations
+        case 'r':
+          if (!supportsColumnReorder && (event.ctrlKey || event.metaKey)) {
+            event.preventDefault();
+            announce('Column reordering is not supported');
+          }
+          break;
+          
+        case '=':
+        case '+':
+        case '-':
+          if (!supportsColumnResize && (event.ctrlKey || event.metaKey)) {
+            event.preventDefault();
+            announce('Column resizing is not supported');
+          }
+          break;
+      }
+    };
+
+    const onFocus = (event: React.FocusEvent) => {
+      // Headers don't participate in cell navigation state
+    };
+
+    return { onKeyDown, onFocus };
+  }, [enabled, getHeaderElement, columnCount, supportsColumnReorder, supportsColumnResize]);
+
+  // Focus management functions
+  const resetFocus = useCallback(() => {
+    setState({
+      focusedRowIndex: 0,
+      focusedColumnIndex: 0,
+      isNavigating: false,
+    });
+  }, []);
+
+  const storeFocus = useCallback(() => {
+    storedFocusRef.current = {
+      rowIndex: state.focusedRowIndex,
+      columnIndex: state.focusedColumnIndex,
+    };
+  }, [state.focusedRowIndex, state.focusedColumnIndex]);
+
+  const restoreFocus = useCallback(() => {
+    if (storedFocusRef.current) {
+      const { rowIndex, columnIndex } = storedFocusRef.current;
+      focusCell(rowIndex, columnIndex);
+      storedFocusRef.current = null;
+    }
+  }, [focusCell]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (navigationTimeoutRef.current) {
+        clearTimeout(navigationTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  return {
+    state,
+    focusCell,
+    focusNext,
+    focusPrevious,
+    focusUp,
+    focusDown,
+    focusRowStart,
+    focusRowEnd,
+    focusTableStart,
+    focusTableEnd,
+    getCellTabIndex,
+    getCellKeyboardHandlers,
+    getHeaderKeyboardHandlers,
+    resetFocus,
+    storeFocus,
+    restoreFocus,
+  };
+}

package/src/components/DataTable/hooks/useServerSideDataEffect.ts

@@ -0,0 +1,94 @@
+/**
+ * @file Server-side data coordination hook
+ */
+
+import { useCallback, useEffect } from 'react';
+import type {
+  DataRecord,
+  PaginationMode,
+  ServerSideConfig,
+  ServerSideParams,
+} from '../types';
+import type {
+  SortingState,
+  ColumnFiltersState,
+  GroupingState,
+  PaginationState,
+} from '@tanstack/react-table';
+
+export interface UseServerSideDataEffectParams<TData extends DataRecord> {
+  finalPaginationMode: PaginationMode;
+  serverSide?: ServerSideConfig<TData>;
+  pagination: PaginationState;
+  sorting: SortingState;
+  columnFilters: ColumnFiltersState;
+  grouping: GroupingState;
+  searchQuery: string;
+  tableDataLength: number;
+  fetchServerData: (params: ServerSideParams) => Promise<void>;
+  cleanup?: () => void;
+}
+
+export function useServerSideDataEffect<TData extends DataRecord>({
+  finalPaginationMode,
+  serverSide,
+  pagination,
+  sorting,
+  columnFilters,
+  grouping,
+  searchQuery,
+  tableDataLength,
+  fetchServerData,
+  cleanup,
+}: UseServerSideDataEffectParams<TData>) {
+  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.pageIndex,
+    pagination.pageSize,
+    sorting,
+    columnFilters,
+    searchQuery,
+    grouping,
+    fetchServerData,
+  ]);
+
+  useEffect(() => {
+    if (finalPaginationMode !== 'server' || !serverSide) {
+      return;
+    }
+
+    if (tableDataLength > 0) {
+      return;
+    }
+
+    handleServerSideChange();
+  }, [
+    finalPaginationMode,
+    serverSide,
+    tableDataLength,
+    handleServerSideChange,
+  ]);
+
+  useEffect(() => () => {
+    cleanup?.();
+  }, [cleanup]);
+
+  return handleServerSideChange;
+}
+

package/src/components/DataTable/hooks/useTableColumns.ts

@@ -12,9 +12,9 @@
 import React, { useMemo } from 'react';
 import { Checkbox } from '../../Checkbox/Checkbox';
 import { ColumnFactory } from '../core/ColumnFactory';
-import type { 
-  DataTableFeatureConfig, 
-  DataTableColumn, 
+import type {
+  NormalizedDataTableFeatureConfig,
+  DataTableColumn,
   DataTableAction,
   DataRecord
 } from '../types';
@@ -23,7 +23,7 @@ import type { HeaderContext, CellContext } from '@tanstack/react-table';
 
 export interface UseTableColumnsOptions<TData extends DataRecord> {
   columns: DataTableColumn<TData>[];
-  features: DataTableFeatureConfig;
+  features: NormalizedDataTableFeatureConfig;
   effectiveActions: DataTableAction<TData>[];
   columnOrder: string[];
 }
@@ -65,14 +65,14 @@ export function useTableColumns<TData extends DataRecord>({
         const isSomeSelected = table.getIsSomePageRowsSelected();
         return React.createElement(Checkbox, {
           checked: isAllSelected ? true : isSomeSelected ? 'indeterminate' : false,
-          onCheckedChange: (value: any) => table.toggleAllPageRowsSelected(!!value),
+          onCheckedChange: (value: boolean | 'indeterminate') => table.toggleAllPageRowsSelected(!!value),
           'aria-label': "Select all"
         });
       },
       cell: ({ row }: CellContext<TData, unknown>) => {
         return React.createElement(Checkbox, {
           checked: row.getIsSelected(),
-          onCheckedChange: (value: any) => row.toggleSelected(!!value),
+          onCheckedChange: (value: boolean | 'indeterminate') => row.toggleSelected(!!value),
           'aria-label': "Select row"
         });
       },
@@ -89,7 +89,10 @@ export function useTableColumns<TData extends DataRecord>({
     const actionsColumn: ColumnDef<TData> | null = effectiveActions.length > 0 ? 
       ColumnFactory.createActionColumn(effectiveActions, {
         header: 'Actions',
-        size: 120,
+        size: 1, // Shrink to fit content
+        minSize: 0,
+        maxSize: 0,
+        meta: { align: 'right' },
       }) : null;
 
     // Build final columns array respecting columnOrder