@jmruthers/pace-core 0.2.4

package/src/components/DataTable/types.ts

@@ -0,0 +1,475 @@
+/**
+ * @file DataTable Type Definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ * @since 0.2.0
+ */
+
+import React from 'react';
+import type { 
+  SortingState, 
+  ColumnFiltersState, 
+  VisibilityState, 
+  GroupingState, 
+  ExpandedState,
+  PaginationState,
+  ColumnDef
+} from '@tanstack/react-table';
+import type { ImportModalConfig } from './components/ImportModal';
+
+// ============================================================================
+// CORE DATA TYPES
+// ============================================================================
+
+/**
+ * Generic data record type - all DataTable data must extend this
+ */
+export type DataRecord = Record<string, any>;
+
+/**
+ * Row identifier function type
+ */
+export type GetRowId<TData extends DataRecord> = (row: TData, index: number) => string;
+
+// ============================================================================
+// HIERARCHICAL DATA TYPES
+// ============================================================================
+
+/**
+ * Hierarchical data row interface for parent/child relationships
+ */
+export interface HierarchicalDataRow extends DataRecord {
+  /** Whether this row is a parent row */
+  isParent: boolean;
+  /** For child rows, references the parent row ID */
+  parentId?: string;
+  /** Unique identifier for this row */
+  id: string;
+}
+
+/**
+ * Hierarchical configuration for DataTable
+ */
+export interface HierarchicalConfig {
+  /** Enable hierarchical functionality */
+  enabled: boolean;
+  /** Default expanded state - true = all expanded, false = all collapsed, array = specific IDs */
+  defaultExpanded?: boolean | string[];
+  /** Callback when expanded state changes */
+  onExpandedChange?: (expandedIds: string[]) => void;
+  /** Custom expand/collapse button component */
+  expandButton?: React.ComponentType<ExpandButtonProps>;
+  /** Visual indentation for child rows (in pixels) */
+  indentSize?: number;
+  /** Custom styling for parent rows */
+  parentRowClassName?: string;
+  /** Custom styling for child rows */
+  childRowClassName?: string;
+}
+
+/**
+ * Props for the expand/collapse button component
+ */
+export interface ExpandButtonProps {
+  /** Row ID */
+  rowId: string;
+  /** Whether the row is currently expanded */
+  isExpanded: boolean;
+  /** Whether this row has children */
+  hasChildren: boolean;
+  /** Click handler */
+  onClick: () => void;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+// ============================================================================
+// PERFORMANCE & PAGINATION TYPES
+// ============================================================================
+
+/**
+ * Pagination mode determines how data is handled
+ */
+export type PaginationMode = 'client' | 'server' | 'hybrid';
+
+/**
+ * Performance configuration for large datasets
+ */
+export interface PerformanceConfig {
+  /** Enable virtual scrolling */
+  virtualScrolling?: boolean;
+  /** Virtual scrolling overscan count */
+  overscan?: number;
+  /** Enable memoization of cell renderers */
+  memoizeCells?: boolean;
+  /** Enable debounced search */
+  debounceSearch?: number;
+  /** Enable data chunking for memory management */
+  enableChunking?: boolean;
+  /** Chunk size for data processing */
+  chunkSize?: number;
+  /** Enable Web Workers for heavy operations */
+  enableWebWorkers?: boolean;
+  /** Threshold for switching to server-side mode */
+  serverSideThreshold?: number;
+}
+
+/**
+ * Server-side data fetching configuration
+ */
+export interface ServerSideConfig<TData extends DataRecord> {
+  /** Function to fetch data from server */
+  fetchData: (params: ServerSideParams) => Promise<ServerSideResponse<TData>>;
+  /** Enable server-side sorting */
+  enableServerSorting?: boolean;
+  /** Enable server-side filtering */
+  enableServerFiltering?: boolean;
+  /** Enable server-side search */
+  enableServerSearch?: boolean;
+  /** Enable server-side pagination */
+  enableServerPagination?: boolean;
+  /** Debounce delay for server requests */
+  debounceMs?: number;
+  /** Cache duration for server responses */
+  cacheMs?: number;
+}
+
+/**
+ * Parameters sent to server for data fetching
+ */
+export interface ServerSideParams {
+  /** Current page index */
+  pageIndex: number;
+  /** Page size */
+  pageSize: number;
+  /** Sorting configuration */
+  sorting: SortingState;
+  /** Column filters */
+  columnFilters: ColumnFiltersState;
+  /** Global filter/search term */
+  globalFilter: string;
+  /** Grouping configuration */
+  grouping: GroupingState;
+}
+
+/**
+ * Response from server for data fetching
+ */
+export interface ServerSideResponse<TData extends DataRecord> {
+  /** Array of data records */
+  data: TData[];
+  /** Total number of records (for pagination) */
+  totalCount: number;
+  /** Current page index */
+  pageIndex: number;
+  /** Page size */
+  pageSize: number;
+  /** Total number of pages */
+  pageCount: number;
+  /** Whether there are more pages */
+  hasNextPage: boolean;
+  /** Whether there are previous pages */
+  hasPreviousPage: boolean;
+}
+
+/**
+ * Data chunking configuration
+ */
+export interface ChunkingConfig {
+  /** Size of each data chunk */
+  chunkSize: number;
+  /** Number of chunks to keep in memory */
+  maxChunksInMemory: number;
+  /** Enable progressive loading */
+  progressiveLoading?: boolean;
+}
+
+/**
+ * Search index configuration for performance
+ */
+export interface SearchIndexConfig {
+  /** Fields to index for search */
+  indexedFields: string[];
+  /** Enable fuzzy search */
+  fuzzySearch?: boolean;
+  /** Fuzzy search threshold */
+  fuzzyThreshold?: number;
+  /** Enable search highlighting */
+  enableHighlighting?: boolean;
+}
+
+// ============================================================================
+// COLUMN DEFINITIONS
+// ============================================================================
+
+/**
+ * Enhanced column definition that extends TanStack's ColumnDef
+ */
+export interface DataTableColumn<TData extends DataRecord = DataRecord> extends Omit<ColumnDef<TData>, 'id' | 'accessorKey'> {
+  /** Column identifier */
+  id?: string;
+  /** Accessor key for data */
+  accessorKey?: string;
+  /** Custom header label for the column */
+  header: string;
+  /** Whether this column should be searchable in global filter */
+  searchable?: boolean;
+  /** Enable sorting */
+  sortable?: boolean;
+  /** Enable column filter (inherits from ColumnDef) */
+  enableColumnFilter?: boolean;
+  /** Enable grouping (inherits from ColumnDef) */
+  enableGrouping?: boolean;
+  /** Enable hiding (inherits from ColumnDef) */
+  enableHiding?: boolean;
+  /** Aggregate configuration for this column */
+  aggregate?: AggregateConfig;
+  /** Enable virtual scrolling for this column */
+  virtualizable?: boolean;
+  /** Custom cell renderer with memoization */
+  memoizedCell?: React.ComponentType<any>;
+  /** Field type for editing (text, select, date, etc.) */
+  fieldType?: 'text' | 'select' | 'date' | 'number' | 'boolean';
+  /** Options for select fields */
+  fieldOptions?: Array<{ value: string | number; label: string }>;
+  /** Filter type for column filtering (text, select, number, date) */
+  filterType?: 'text' | 'select' | 'number' | 'date';
+  
+  // Hierarchical rendering
+  /** Custom renderer for parent rows */
+  renderForParent?: (row: TData) => React.ReactNode;
+  /** Custom renderer for child rows */
+  renderForChild?: (row: TData) => React.ReactNode;
+  /** Hide this column for parent rows */
+  hideForParent?: boolean;
+  /** Hide this column for child rows */
+  hideForChild?: boolean;
+}
+
+/**
+ * Simple column interface for basic use cases
+ */
+export interface SimpleColumn<TData extends DataRecord = DataRecord> {
+  /** Data accessor key */
+  key: keyof TData | string;
+  /** Display label */
+  label: string;
+  /** Enable sorting */
+  sortable?: boolean;
+  /** Enable filtering */
+  filterable?: boolean;
+}
+
+// ============================================================================
+// ACTION DEFINITIONS
+// ============================================================================
+
+/**
+ * Action definition for row-level operations
+ */
+export interface DataTableAction<TData extends DataRecord> {
+  /** Display label for the action */
+  label: string;
+  /** Icon component */
+  icon?: React.ComponentType<{ className?: string }>;
+  /** Action handler */
+  onClick: (row: TData) => void;
+  /** Visual variant */
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost';
+  /** Whether action is disabled */
+  disabled?: (row: TData) => boolean;
+  /** Test ID for testing */
+  testId?: string;
+  /** Whether this action should only show for parent rows (hierarchical mode) */
+  showForParent?: boolean;
+  /** Whether this action should only show for child rows (hierarchical mode) */
+  showForChild?: boolean;
+  /** Icon component for parent rows (overrides icon when showForParent is true) */
+  parentIcon?: React.ComponentType<{ className?: string }>;
+  /** Icon component for child rows (overrides icon when showForChild is true) */
+  childIcon?: React.ComponentType<{ className?: string }>;
+  /** Label for parent rows (overrides label when showForParent is true) */
+  parentLabel?: string;
+  /** Label for child rows (overrides label when showForChild is true) */
+  childLabel?: string;
+}
+
+/**
+ * Toolbar button definition
+ */
+export interface DataTableToolbarButton {
+  /** Display label */
+  label: string;
+  /** Icon component */
+  icon?: React.ComponentType<{ className?: string }>;
+  /** Click handler */
+  onClick: () => void;
+  /** Visual variant */
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost';
+  /** Whether button is disabled */
+  disabled?: boolean;
+  /** Test ID for testing */
+  testId?: string;
+}
+
+// ============================================================================
+// CONFIGURATION TYPES
+// ============================================================================
+
+/**
+ * Aggregate configuration
+ */
+export interface AggregateConfig {
+  field: string;
+  function: 'sum' | 'avg' | 'count' | 'min' | 'max';
+  label: string;
+}
+
+/**
+ * Empty state configuration
+ */
+export interface EmptyStateConfig {
+  title?: string;
+  description?: string;
+  icon?: React.ComponentType<{ className?: string }>;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+}
+
+// ============================================================================
+// FEATURE CONFIGURATION TYPES
+// ============================================================================
+
+/**
+ * Unified feature configuration for DataTable
+ * All features are disabled by default and must be explicitly enabled
+ */
+export interface DataTableFeatureConfig {
+  // Core Features
+  /** Enable global search functionality */
+  search: boolean;
+  /** Enable pagination controls */
+  pagination: boolean;
+  /** Enable column sorting */
+  sorting: boolean;
+  /** Enable column filtering */
+  filtering: boolean;
+  
+  // Data Management
+  /** Enable data import functionality */
+  import: boolean;
+  /** Enable data export functionality */
+  export: boolean;
+  
+  // Row Operations
+  /** Enable row selection for bulk operations */
+  selection: boolean;
+  /** Enable row creation */
+  creation: boolean;
+  /** Enable row editing */
+  editing: boolean;
+  /** Enable row deletion */
+  deletion: boolean;
+  /** Enable bulk deletion of selected rows */
+  deleteSelected: boolean;
+  
+  // Table Customization
+  /** Enable data grouping */
+  grouping: boolean;
+  /** Enable column visibility controls */
+  columnVisibility: boolean;
+  /** Enable column reordering */
+  columnReordering: boolean;
+  /** Enable hierarchical parent/child rows */
+  hierarchical: boolean;
+  
+  // Performance
+  // Virtualization is now handled automatically based on data size
+  
+  // Layout
+  /** Enable automatic column width adjustment based on content */
+  autoColumnSizing?: boolean;
+}
+
+
+
+// ============================================================================
+// MAIN COMPONENT PROPS
+// ============================================================================
+
+/**
+ * Enhanced DataTable props with unified feature configuration
+ */
+export interface DataTableProps<TData extends DataRecord> {
+  // Core data
+  /** Array of data to display */
+  data: TData[];
+  /** Column definitions - supports both DataTableColumn and SimpleColumn formats */
+  columns: (DataTableColumn<TData> | SimpleColumn<TData>)[];
+
+  // Display
+  /** Table title */
+  title?: string;
+  /** Table description */
+  description?: string;
+  /** Theme variant */
+  variant?: 'default' | 'compact' | 'spacious';
+  /** Custom CSS classes */
+  className?: string;
+
+  // NEW: Unified feature configuration
+  /** Feature configuration - all features are disabled by default */
+  features: DataTableFeatureConfig;
+
+  // Hierarchical Configuration
+  /** Hierarchical parent/child row configuration */
+  hierarchical?: HierarchicalConfig;
+
+  // Performance Configuration
+  /** Performance optimization settings */
+  performance?: PerformanceConfig;
+  /** Server-side data fetching configuration */
+  serverSide?: ServerSideConfig<TData>;
+  /** Pagination mode */
+  paginationMode?: PaginationMode;
+  /** Data chunking configuration */
+  chunking?: ChunkingConfig;
+  /** Search index configuration */
+  searchIndex?: SearchIndexConfig;
+  /** Initial page size for pagination */
+  initialPageSize?: number;
+
+  // Event handlers
+  /** Row edit handler */
+  onEditRow?: (row: TData, data: Partial<TData>) => void;
+  /** Row deletion handler */
+  onDeleteRow?: (row: TData) => void;
+  /** Row creation handler */
+  onCreateRow?: (data: Partial<TData>) => void;
+  /** Import handler */
+  onImport?: (data: TData[]) => void | Promise<void>;
+  /** Row selection change handler */
+  onRowSelectionChange?: (selection: Record<string, boolean>) => void;
+  /** Controlled selection state */
+  selection?: Record<string, boolean>;
+  /** Bulk delete selected rows handler */
+  onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
+
+  // Utilities
+  /** Function to get unique ID for each row */
+  getRowId?: GetRowId<TData>;
+  /** Loading state */
+  isLoading?: boolean;
+  /** Empty state customization */
+  emptyState?: EmptyStateConfig;
+  /** Aggregate configurations */
+  aggregates?: AggregateConfig[];
+
+  // Import Modal Configuration
+  /** Import modal configuration */
+  importModalConfig?: ImportModalConfig;
+}
+
+

package/src/components/DataTable/utils/__tests__/columnSizing.test.ts

@@ -0,0 +1,237 @@
+/**
+ * @file Column Sizing Utilities Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/utils/__tests__
+ * @since 0.4.33
+ * 
+ * Tests for column sizing utility functions.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { 
+  calculateContentWidth, 
+  calculateColumnWidths, 
+  getColumnSizingConfig 
+} from '../columnSizing';
+
+describe('Column Sizing Utilities', () => {
+  describe('calculateContentWidth', () => {
+    it('calculates width for normal content', () => {
+      const width = calculateContentWidth('Hello World', 80, 400, 32);
+      expect(width).toBeGreaterThan(80);
+      expect(width).toBeLessThan(400);
+    });
+
+    it('returns minWidth for empty content', () => {
+      const width = calculateContentWidth('', 80, 400, 32);
+      expect(width).toBe(80);
+    });
+
+    it('returns minWidth for null content', () => {
+      const width = calculateContentWidth(null as any, 80, 400, 32);
+      expect(width).toBe(80);
+    });
+
+    it('returns minWidth for undefined content', () => {
+      const width = calculateContentWidth(undefined as any, 80, 400, 32);
+      expect(width).toBe(80);
+    });
+
+    it('respects maxWidth constraint', () => {
+      const longText = 'A'.repeat(1000);
+      const width = calculateContentWidth(longText, 80, 400, 32);
+      expect(width).toBe(400);
+    });
+
+    it('respects minWidth constraint', () => {
+      const width = calculateContentWidth('A', 200, 400, 32);
+      expect(width).toBe(200);
+    });
+
+    it('uses default parameters correctly', () => {
+      const width = calculateContentWidth('Test');
+      expect(width).toBeGreaterThanOrEqual(80);
+      expect(width).toBeLessThan(400);
+    });
+
+    it('includes padding in calculation', () => {
+      const width1 = calculateContentWidth('Test', 80, 400, 0);
+      const width2 = calculateContentWidth('Test', 80, 400, 50);
+      expect(width2).toBeGreaterThan(width1);
+    });
+  });
+
+  describe('calculateColumnWidths', () => {
+    const testData = [
+      { id: '1', name: 'John', email: 'john@example.com', description: 'A short description' },
+      { id: '2', name: 'Jane', email: 'jane@example.com', description: 'A very long description that should make this column wider' },
+      { id: '3', name: 'Bob', email: 'bob@example.com', description: 'Medium length description' }
+    ];
+
+    const testColumns = [
+      { id: 'name', accessorKey: 'name', header: 'Name' },
+      { id: 'email', accessorKey: 'email', header: 'Email' },
+      { id: 'description', accessorKey: 'description', header: 'Description' }
+    ];
+
+    it('calculates widths for all columns', () => {
+      const widths = calculateColumnWidths(testData, testColumns);
+      
+      expect(widths).toHaveProperty('name');
+      expect(widths).toHaveProperty('email');
+      expect(widths).toHaveProperty('description');
+      
+      expect(widths.name).toBeGreaterThan(0);
+      expect(widths.email).toBeGreaterThan(0);
+      expect(widths.description).toBeGreaterThan(0);
+    });
+
+    it('makes wider columns for longer content', () => {
+      const widths = calculateColumnWidths(testData, testColumns);
+      
+      // Description column should be wider than name column
+      expect(widths.description).toBeGreaterThan(widths.name);
+    });
+
+    it('respects min and max width constraints', () => {
+      const widths = calculateColumnWidths(testData, testColumns, {
+        minWidth: 100,
+        maxWidth: 200
+      });
+      
+      Object.values(widths).forEach(width => {
+        expect(width).toBeGreaterThanOrEqual(100);
+        expect(width).toBeLessThanOrEqual(200);
+      });
+    });
+
+    it('handles empty data array', () => {
+      const widths = calculateColumnWidths([], testColumns);
+      
+      expect(widths).toHaveProperty('name');
+      expect(widths).toHaveProperty('email');
+      expect(widths).toHaveProperty('description');
+      
+      // Should still calculate widths based on headers
+      Object.values(widths).forEach(width => {
+        expect(width).toBeGreaterThan(0);
+      });
+    });
+
+    it('handles columns without id or accessorKey', () => {
+      const invalidColumns = [
+        { header: 'Valid Column', accessorKey: 'valid' },
+        { header: 'Invalid Column' }, // No id or accessorKey
+        { id: 'another', header: 'Another Valid' }
+      ];
+      
+      const widths = calculateColumnWidths(testData, invalidColumns);
+      
+      expect(widths).toHaveProperty('valid');
+      expect(widths).toHaveProperty('another');
+      expect(widths).not.toHaveProperty('undefined');
+    });
+
+    it('handles data with null/undefined values', () => {
+      const dataWithNulls = [
+        { id: '1', name: 'John', email: null, description: undefined },
+        { id: '2', name: null, email: 'jane@example.com', description: 'Valid description' }
+      ];
+      
+      const widths = calculateColumnWidths(dataWithNulls, testColumns);
+      
+      expect(widths).toHaveProperty('name');
+      expect(widths).toHaveProperty('email');
+      expect(widths).toHaveProperty('description');
+      
+      Object.values(widths).forEach(width => {
+        expect(width).toBeGreaterThan(0);
+      });
+    });
+
+    it('uses sample size limit for large datasets', () => {
+      const largeData = Array.from({ length: 10000 }, (_, i) => ({
+        id: i.toString(),
+        name: `User ${i}`,
+        email: `user${i}@example.com`,
+        description: `Description for user ${i}`
+      }));
+      
+      const widths = calculateColumnWidths(largeData, testColumns, {
+        sampleSize: 100
+      });
+      
+      expect(widths).toHaveProperty('name');
+      expect(widths).toHaveProperty('email');
+      expect(widths).toHaveProperty('description');
+    });
+
+    it('handles columns with accessorFn', () => {
+      const columnsWithFn = [
+        { id: 'name', accessorKey: 'name', header: 'Name' },
+        { 
+          id: 'fullName', 
+          accessorFn: (row: any) => `${row.firstName} ${row.lastName}`,
+          header: 'Full Name' 
+        }
+      ];
+      
+      const dataWithFn = [
+        { id: '1', name: 'John', firstName: 'John', lastName: 'Doe' },
+        { id: '2', name: 'Jane', firstName: 'Jane', lastName: 'Smith' }
+      ];
+      
+      const widths = calculateColumnWidths(dataWithFn, columnsWithFn);
+      
+      expect(widths).toHaveProperty('name');
+      expect(widths).toHaveProperty('fullName');
+    });
+  });
+
+  describe('getColumnSizingConfig', () => {
+    it('returns basic config when auto-sizing disabled', () => {
+      const config = getColumnSizingConfig(false);
+      
+      expect(config).toEqual({
+        columnResizeMode: 'onChange'
+      });
+    });
+
+    it('returns enhanced config when auto-sizing enabled', () => {
+      const config = getColumnSizingConfig(true);
+      
+      expect(config).toEqual({
+        columnResizeMode: 'onChange',
+        enableColumnResizing: true,
+        columnResizeDirection: 'ltr'
+      });
+    });
+
+    it('includes initial column sizes when provided', () => {
+      const columnWidths = { name: 150, email: 200, description: 300 };
+      const config = getColumnSizingConfig(true, columnWidths);
+      
+      expect(config).toEqual({
+        columnResizeMode: 'onChange',
+        enableColumnResizing: true,
+        columnResizeDirection: 'ltr',
+        initialState: {
+          columnSizing: columnWidths
+        }
+      });
+    });
+
+    it('handles empty column widths object', () => {
+      const config = getColumnSizingConfig(true, {});
+      
+      expect(config).toEqual({
+        columnResizeMode: 'onChange',
+        enableColumnResizing: true,
+        columnResizeDirection: 'ltr',
+        initialState: {
+          columnSizing: {}
+        }
+      });
+    });
+  });
+});