@jmruthers/pace-core 0.5.76 → 0.5.78

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

@@ -0,0 +1,174 @@
+import { useCallback, useMemo } from 'react';
+import type {
+  ColumnFiltersState,
+  ExpandedState,
+  GroupingState,
+  PaginationState,
+  SortingState,
+  VisibilityState,
+} from '@tanstack/react-table';
+
+import type {
+  DataRecord,
+  DataTableState,
+  DataTableStateActions,
+} from './useDataTableState';
+
+export interface TableLayoutChange {
+  columnOrder: string[];
+  columnVisibility: VisibilityState;
+}
+
+export interface TableStateSnapshot<TData extends DataRecord> {
+  sorting: SortingState;
+  columnFilters: ColumnFiltersState;
+  columnVisibility: VisibilityState;
+  rowSelection: Record<string, boolean>;
+  grouping: GroupingState;
+  expanded: ExpandedState;
+  pagination: PaginationState;
+  globalFilter: string;
+  columnOrder: string[];
+}
+
+export interface TableHandlers {
+  onSortingChange: (updaterOrValue: unknown) => void;
+  onColumnFiltersChange: (updaterOrValue: unknown) => void;
+  onColumnVisibilityChange: (updaterOrValue: unknown) => void;
+  onRowSelectionChange: (updaterOrValue: unknown) => void;
+  onGroupingChange: (updaterOrValue: unknown) => void;
+  onExpandedChange: (updaterOrValue: unknown) => void;
+  onPaginationChange: (updaterOrValue: unknown) => void;
+  onColumnOrderChange: (updaterOrValue: unknown) => void;
+}
+
+interface UseTableHandlersOptions<TData extends DataRecord> {
+  state: DataTableState<TData>;
+  stateSnapshot: TableStateSnapshot<TData>;
+  actions: DataTableStateActions<TData>;
+  selection?: Record<string, boolean>;
+  onRowSelectionChange?: (selection: Record<string, boolean>) => void;
+  effectiveColumnOrder: string[];
+  canPersistVisibility: boolean;
+  canPersistOrder: boolean;
+  updateSavedColumnVisibility: (visibility: VisibilityState) => void;
+  updateColumnOrder: (order: string[]) => void;
+  onLayoutChange?: (layout: TableLayoutChange) => void;
+}
+
+export function useTableHandlers<TData extends DataRecord>({
+  state,
+  stateSnapshot,
+  actions,
+  selection,
+  onRowSelectionChange,
+  effectiveColumnOrder,
+  canPersistVisibility,
+  canPersistOrder,
+  updateSavedColumnVisibility,
+  updateColumnOrder,
+  onLayoutChange,
+}: UseTableHandlersOptions<TData>): TableHandlers {
+  const handleSortingChange = useCallback((updaterOrValue: unknown) => {
+    const nextValue = typeof updaterOrValue === 'function'
+      ? (updaterOrValue as (prev: SortingState) => SortingState)(stateSnapshot.sorting)
+      : updaterOrValue as SortingState;
+    actions.setSorting(nextValue);
+  }, [actions, stateSnapshot.sorting]);
+
+  const handleColumnFiltersChange = useCallback((updaterOrValue: unknown) => {
+    const nextValue = typeof updaterOrValue === 'function'
+      ? (updaterOrValue as (prev: ColumnFiltersState) => ColumnFiltersState)(stateSnapshot.columnFilters)
+      : updaterOrValue as ColumnFiltersState;
+    actions.setColumnFilters(nextValue);
+  }, [actions, stateSnapshot.columnFilters]);
+
+  const handleColumnVisibilityChange = useCallback((updaterOrValue: unknown) => {
+    const nextValue = typeof updaterOrValue === 'function'
+      ? (updaterOrValue as (prev: VisibilityState) => VisibilityState)(stateSnapshot.columnVisibility)
+      : updaterOrValue as VisibilityState;
+
+    actions.setColumnVisibility(nextValue);
+
+    if (canPersistVisibility) {
+      updateSavedColumnVisibility(nextValue);
+    }
+
+    onLayoutChange?.({
+      columnOrder: effectiveColumnOrder,
+      columnVisibility: nextValue,
+    });
+  }, [actions, stateSnapshot.columnVisibility, canPersistVisibility, updateSavedColumnVisibility, onLayoutChange, effectiveColumnOrder]);
+
+  const handleRowSelectionChange = useCallback((updaterOrValue: unknown) => {
+    const currentSelection = selection ?? state.rowSelection;
+    const nextSelection = typeof updaterOrValue === 'function'
+      ? (updaterOrValue as (prev: Record<string, boolean>) => Record<string, boolean>)(currentSelection)
+      : updaterOrValue as Record<string, boolean>;
+
+    if (selection === undefined) {
+      actions.setRowSelection(nextSelection);
+      return;
+    }
+
+    onRowSelectionChange?.(nextSelection);
+  }, [actions, selection, state.rowSelection, onRowSelectionChange]);
+
+  const handleGroupingChange = useCallback((updaterOrValue: unknown) => {
+    const nextValue = typeof updaterOrValue === 'function'
+      ? (updaterOrValue as (prev: GroupingState) => GroupingState)(stateSnapshot.grouping)
+      : updaterOrValue as GroupingState;
+    actions.setGrouping(nextValue);
+  }, [actions, stateSnapshot.grouping]);
+
+  const handleExpandedChange = useCallback((updaterOrValue: unknown) => {
+    const nextValue = typeof updaterOrValue === 'function'
+      ? (updaterOrValue as (prev: ExpandedState) => ExpandedState)(stateSnapshot.expanded)
+      : updaterOrValue as ExpandedState;
+    actions.setExpanded(nextValue);
+  }, [actions, stateSnapshot.expanded]);
+
+  const handlePaginationChange = useCallback((updaterOrValue: unknown) => {
+    const nextValue = typeof updaterOrValue === 'function'
+      ? (updaterOrValue as (prev: PaginationState) => PaginationState)(stateSnapshot.pagination)
+      : updaterOrValue as PaginationState;
+    actions.setPagination(nextValue);
+  }, [actions, stateSnapshot.pagination]);
+
+  const handleColumnOrderChange = useCallback((updaterOrValue: unknown) => {
+    const nextValue = typeof updaterOrValue === 'function'
+      ? (updaterOrValue as (prev: string[]) => string[])(stateSnapshot.columnOrder)
+      : updaterOrValue as string[];
+
+    actions.setColumnOrder(nextValue);
+
+    if (canPersistOrder) {
+      updateColumnOrder(nextValue);
+    }
+
+    onLayoutChange?.({
+      columnOrder: nextValue,
+      columnVisibility: stateSnapshot.columnVisibility,
+    });
+  }, [actions, stateSnapshot.columnOrder, stateSnapshot.columnVisibility, canPersistOrder, updateColumnOrder, onLayoutChange]);
+
+  return useMemo(() => ({
+    onSortingChange: handleSortingChange,
+    onColumnFiltersChange: handleColumnFiltersChange,
+    onColumnVisibilityChange: handleColumnVisibilityChange,
+    onRowSelectionChange: handleRowSelectionChange,
+    onGroupingChange: handleGroupingChange,
+    onExpandedChange: handleExpandedChange,
+    onPaginationChange: handlePaginationChange,
+    onColumnOrderChange: handleColumnOrderChange,
+  }), [
+    handleSortingChange,
+    handleColumnFiltersChange,
+    handleColumnVisibilityChange,
+    handleRowSelectionChange,
+    handleGroupingChange,
+    handleExpandedChange,
+    handlePaginationChange,
+    handleColumnOrderChange,
+  ]);
+}

package/src/components/DataTable/index.ts

@@ -28,9 +28,9 @@ export { useDataTablePerformance } from '../../hooks/useDataTablePerformance';
 export type { UseDataTablePerformanceOptions, UseDataTablePerformanceReturn } from '../../hooks/useDataTablePerformance';
 
 // Type definitions
-export type { 
-  DataTableColumn, 
-  DataTableAction, 
+export type {
+  DataTableColumn,
+  DataTableAction,
   DataTableToolbarButton,
   AggregateConfig,
   EmptyStateConfig,
@@ -38,6 +38,7 @@ export type {
   SimpleColumn,
   // Feature configuration types
   DataTableFeatureConfig,
+  NormalizedDataTableFeatureConfig,
   // Performance types
   PaginationMode,
   PerformanceConfig,
@@ -46,6 +47,11 @@ export type {
   SearchIndexConfig
 } from './types';
 
+export {
+  defaultDataTableFeatures,
+  normalizeDataTableFeatures,
+} from './types';
+
 // Re-export TanStack types for convenience
 export type { ColumnDef, SortingState, ColumnFiltersState } from '@tanstack/react-table';
 
@@ -58,3 +64,6 @@ export * from './components';
 // Utility functions
 export * from './utils';
 
+// Accessibility utilities
+export { announce } from './utils/a11yUtils';
+

package/src/components/DataTable/types.ts

@@ -32,14 +32,38 @@ declare module '@tanstack/react-table' {
 // ============================================================================
 
 /**
- * Generic data record type - all DataTable data must extend this
+ * Core value types that can exist in a data record
  */
-export type DataRecord = Record<string, any>;
+export type CellValue = string | number | boolean | null | undefined | Date;
+
+/**
+ * Base data record type - all DataTable data must extend this
+ * This is a marker type that allows any object to be used as a data record
+ * Individual implementations should define more specific types
+ */
+export interface DataRecord {
+  [key: string]: unknown;
+}
+
+/**
+ * Row ID type - always a string
+ */
+export type RowId = string;
 
 /**
  * Row identifier function type
  */
-export type GetRowId<TData extends DataRecord> = (row: TData, index: number) => string;
+export type GetRowId<TData extends DataRecord> = (row: TData, index: number) => RowId;
+
+/**
+ * Generic type for partial data updates
+ */
+export type PartialDataRecord<TData extends DataRecord> = Partial<TData>;
+
+/**
+ * Generic type for complete data records
+ */
+export type CompleteDataRecord<TData extends DataRecord> = TData;
 
 // ============================================================================
 // HIERARCHICAL DATA TYPES
@@ -182,6 +206,32 @@ export interface ServerSideResponse<TData extends DataRecord> {
   hasPreviousPage: boolean;
 }
 
+/**
+ * Unified pagination configuration for consistent behavior across modes
+ */
+export interface PaginationConfig {
+  /** Pagination mode */
+  mode: PaginationMode;
+  /** Available page size options */
+  pageSizeOptions?: number[];
+  /** Initial page size */
+  initialPageSize?: number;
+  /** Show enhanced pagination controls (jump to page, etc.) */
+  enhanced?: boolean;
+  /** Show performance mode indicator */
+  showPerformanceInfo?: boolean;
+}
+
+/**
+ * Pagination callbacks for server-side and hybrid modes
+ */
+export interface PaginationCallbacks {
+  /** Called when page index changes */
+  onPageChange?: (pageIndex: number) => void;
+  /** Called when page size changes */
+  onPageSizeChange?: (pageSize: number) => void;
+}
+
 /**
  * Data chunking configuration
  */
@@ -220,6 +270,8 @@ export interface DataTableColumn<TData extends DataRecord = DataRecord> extends
   id?: string;
   /** Accessor key for data */
   accessorKey?: string;
+  /** Alternative accessor key used while editing */
+  editAccessorKey?: string;
   /** Custom header label for the column */
   header: string;
   /** Whether this column should be searchable in global filter */
@@ -237,7 +289,7 @@ export interface DataTableColumn<TData extends DataRecord = DataRecord> extends
   /** Enable virtual scrolling for this column */
   virtualizable?: boolean;
   /** Custom cell renderer with memoization */
-  memoizedCell?: React.ComponentType<any>;
+  memoizedCell?: React.ComponentType<{ row: TData }>;
   /** Field type for editing (text, select, date, etc.) */
   fieldType?: 'text' | 'select' | 'date' | 'number' | 'boolean';
   /** Options for select fields */
@@ -260,6 +312,18 @@ export interface DataTableColumn<TData extends DataRecord = DataRecord> extends
   hideForChild?: boolean;
 }
 
+/**
+ * Extended column definition used when rendering editable rows
+ */
+export interface EditableColumnDef<TData extends DataRecord = DataRecord> extends DataTableColumn<TData> {
+  /** Whether the column can be edited */
+  editable?: boolean;
+  /** Field type used to determine edit control */
+  fieldType?: 'text' | 'select' | 'date' | 'number' | 'boolean';
+  /** Options for select based editors */
+  fieldOptions?: Array<{ value: string | number; label: string }>;
+}
+
 /**
  * Simple column interface for basic use cases
  */
@@ -281,6 +345,11 @@ export interface SimpleColumn<TData extends DataRecord = DataRecord> {
 /**
  * Action definition for row-level operations
  */
+/**
+ * Boolean condition or predicate evaluated against a row
+ */
+export type ActionCondition<TData extends DataRecord> = boolean | ((row: TData) => boolean);
+
 export interface DataTableAction<TData extends DataRecord> {
   /** Display label for the action */
   label: string;
@@ -291,9 +360,11 @@ export interface DataTableAction<TData extends DataRecord> {
   /** Visual variant */
   variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost';
   /** Whether action is disabled */
-  disabled?: (row: TData) => boolean;
+  disabled?: ActionCondition<TData>;
   /** Whether action is hidden (for RBAC) */
   hidden?: boolean;
+  /** Explicit visibility override */
+  visible?: ActionCondition<TData>;
   /** Test ID for testing */
   testId?: string;
   /** Whether this action should only show for parent rows (hierarchical mode) */
@@ -308,6 +379,12 @@ export interface DataTableAction<TData extends DataRecord> {
   parentLabel?: string;
   /** Label for child rows (overrides label when showForChild is true) */
   childLabel?: string;
+  /** Whether the action should be shown while the row is in edit mode */
+  showInEditMode?: boolean;
+  /** Whether the action should be hidden while the row is in view mode */
+  hideInViewMode?: boolean;
+  /** Whether the action should explicitly render while in view mode */
+  showInViewMode?: boolean;
 }
 
 /**
@@ -362,7 +439,7 @@ export interface EmptyStateConfig {
  * Unified feature configuration for DataTable
  * All features are disabled by default and must be explicitly enabled
  */
-export interface DataTableFeatureConfig {
+export interface DataTableFeatureFlags {
   // Core Features
   /** Enable global search functionality */
   search: boolean;
@@ -400,13 +477,56 @@ export interface DataTableFeatureConfig {
   columnReordering: boolean;
   /** Enable hierarchical parent/child rows */
   hierarchical: boolean;
-  
+
   // Performance
   // Virtualization is now handled automatically based on data size
-  
+
   // Layout
 }
 
+/**
+ * Consumer-facing feature configuration. All properties are optional and will be
+ * merged with {@link defaultDataTableFeatures} at runtime to keep the public API
+ * ergonomic while maintaining strict internal guarantees.
+ */
+export type DataTableFeatureConfig = Partial<DataTableFeatureFlags>;
+
+/** Fully normalized feature configuration used internally by the table. */
+export type NormalizedDataTableFeatureConfig = DataTableFeatureFlags;
+
+/** Default feature configuration with every capability disabled. */
+export const defaultDataTableFeatures: NormalizedDataTableFeatureConfig = {
+  search: false,
+  pagination: false,
+  sorting: false,
+  filtering: false,
+  import: false,
+  export: false,
+  selection: false,
+  creation: false,
+  editing: false,
+  deletion: false,
+  deleteSelected: false,
+  grouping: false,
+  columnVisibility: false,
+  columnReordering: false,
+  hierarchical: false,
+};
+
+/**
+ * Normalize a potentially partial feature configuration. This keeps the
+ * rendering pipeline simple and predictable because downstream consumers can
+ * rely on every flag being present.
+ */
+export function normalizeDataTableFeatures(
+  features?: DataTableFeatureConfig
+): NormalizedDataTableFeatureConfig {
+  return {
+    ...defaultDataTableFeatures,
+    ...(features ?? {}),
+  };
+}
+
 
 
 // ============================================================================
@@ -484,7 +604,7 @@ export interface DataTableProps<TData extends DataRecord> {
 
   // NEW: Unified feature configuration
   /** Feature configuration - all features are disabled by default */
-  features: DataTableFeatureConfig;
+  features?: DataTableFeatureConfig;
 
   // Hierarchical Configuration
   /** Hierarchical parent/child row configuration */