@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/DataTable/{__tests__/test-utils/sharedTestUtils.tsx → test-utils/sharedTestUtils.ts}

@@ -4,36 +4,45 @@
  * @package @jmruthers/pace-core
  * @module Components/DataTable/Tests/Utilities
  * @since 0.3.0
- * 
+ *
  * Shared utilities and helpers for DataTable tests to reduce duplication
  * and provide consistent testing patterns across the test suite.
  */
-import type { DataTableAction, DataTableFeatureConfig } from '../../types';
-// AccessLevel removed - use AccessLevel type from rbac/types.ts if needed
+
+import type { DataTableAction, DataTableFeatureConfig, DataRecord } from '../types';
 import '@testing-library/jest-dom';
-import React from 'react';
+import {
+  MockDataTableContext,
+  MockDataTableErrorBoundary,
+  MockDataTableModals,
+  MockDataTableToolbar,
+  MockDeleteIcon,
+  MockEditIcon,
+  MockLoadingState,
+  MockPaginationControls,
+  MockUnifiedTableBody,
+} from './MockDataTableComponents';
 
-// Mock icon components
-const MockEditIcon = ({ className }: { className?: string }) => <span className={className} data-testid="edit-icon">Edit</span>;
-const MockDeleteIcon = ({ className }: { className?: string }) => <span className={className} data-testid="delete-icon">Delete</span>;
+/** Overrides for TanStack table mock (partial shape). */
+type TanStackTableMockOverrides = Record<string, unknown>;
 
 /**
  * Common mock implementations for DataTable components
  */
 export const mockComponents = {
-  DataTableContext: vi.fn(({ children }: any) => <section data-testid="data-table-context">{children}</section>),
-  DataTableToolbar: vi.fn(() => <nav data-testid="data-table-toolbar">Toolbar</nav>),
-  UnifiedTableBody: vi.fn(() => <main data-testid="unified-table-body">Body</main>),
-  DataTableModals: vi.fn(() => <section data-testid="data-table-modals">Modals</section>),
-  PaginationControls: vi.fn(() => <nav data-testid="pagination-controls">Pagination</nav>),
-  LoadingState: vi.fn(() => <section data-testid="loading-state">Loading</section>),
-  DataTableErrorBoundary: vi.fn(({ children }: any) => <section data-testid="error-boundary">{children}</section>),
+  DataTableContext: vi.fn(MockDataTableContext),
+  DataTableToolbar: vi.fn(MockDataTableToolbar),
+  UnifiedTableBody: vi.fn(MockUnifiedTableBody),
+  DataTableModals: vi.fn(MockDataTableModals),
+  PaginationControls: vi.fn(MockPaginationControls),
+  LoadingState: vi.fn(MockLoadingState),
+  DataTableErrorBoundary: vi.fn(MockDataTableErrorBoundary),
 };
 
 /**
  * Common TanStack Table mock configuration
  */
-export const createTanStackTableMock = (overrides: any = {}) => ({
+export const createTanStackTableMock = (overrides: TanStackTableMockOverrides = {}) => ({
   getHeaderGroups: vi.fn(() => [
     {
       id: 'header-group-1',
@@ -45,7 +54,7 @@ export const createTanStackTableMock = (overrides: any = {}) => ({
           getContext: vi.fn(() => ({})),
         },
         {
-          id: 'email', 
+          id: 'email',
           isPlaceholder: false,
           column: { columnDef: { header: 'Email' } },
           getContext: vi.fn(() => ({})),
@@ -59,7 +68,7 @@ export const createTanStackTableMock = (overrides: any = {}) => ({
       ],
     },
   ]),
-  getRowModel: vi.fn(() => ({ 
+  getRowModel: vi.fn(() => ({
     rows: [
       {
         id: '1',
@@ -96,7 +105,7 @@ export const createTanStackTableMock = (overrides: any = {}) => ({
     globalFilter: '',
     pagination: { pageIndex: 0, pageSize: 10 },
     grouping: [],
-    expanded: {}
+    expanded: {},
   })),
   setGlobalFilter: vi.fn(),
   setColumnVisibility: vi.fn(),
@@ -115,7 +124,7 @@ export const createTanStackTableMock = (overrides: any = {}) => ({
 /**
  * Common mock for TanStack Table module
  */
-export const createTanStackTableModuleMock = (tableMock: any = {}) => ({
+export const createTanStackTableModuleMock = (tableMock: TanStackTableMockOverrides = {}) => ({
   useReactTable: vi.fn(() => createTanStackTableMock(tableMock)),
   getCoreRowModel: vi.fn(),
   getFilteredRowModel: vi.fn(),
@@ -135,33 +144,33 @@ export const createPerformanceUtilsMock = () => ({
     constructor(_config: unknown) {
       // Mock constructor - config parameter kept for API compatibility
     }
-    getChunk = vi.fn(() => [])
-    getMemoryUsage = vi.fn(() => 5)
-    clear = vi.fn()
+    getChunk = vi.fn(() => []);
+    getMemoryUsage = vi.fn(() => 5);
+    clear = vi.fn();
   },
   SearchIndex: class MockSearchIndex {
     constructor(_config: unknown) {
       // Mock constructor - config parameter kept for API compatibility
     }
-    buildIndex = vi.fn()
-    search = vi.fn(() => [{ id: '1', name: 'Test User' }])
+    buildIndex = vi.fn();
+    search = vi.fn(() => [{ id: '1', name: 'Test User' }]);
   },
   PerformanceMonitor: class MockPerformanceMonitor {
     constructor() {
       // Mock constructor - no initialization needed
     }
-    startRender = vi.fn()
-    endRender = vi.fn()
+    startRender = vi.fn();
+    endRender = vi.fn();
   },
   VisibilityTracker: class MockVisibilityTracker {
     constructor() {
       // Mock constructor - no initialization needed
     }
-    observe = vi.fn()
-    unobserve = vi.fn()
-    disconnect = vi.fn()
-    destroy = vi.fn()
-    onVisibilityChange = vi.fn(() => vi.fn())
+    observe = vi.fn();
+    unobserve = vi.fn();
+    disconnect = vi.fn();
+    destroy = vi.fn();
+    onVisibilityChange = vi.fn(() => vi.fn());
   },
   determinePaginationMode: vi.fn((size: number) => {
     if (size < 1000) return 'client';
@@ -170,40 +179,55 @@ export const createPerformanceUtilsMock = () => ({
     return 'server';
   }),
   getOptimalPageSizeOptions: vi.fn(() => [10, 25, 50, 100]),
-  debounce: vi.fn((fn: Function) => fn),
+  debounce: vi.fn((fn: (() => void) | (() => Promise<void>)) => fn),
 });
 
 /**
  * Common mock for utils
  */
 export const createUtilsMock = () => ({
-  cn: vi.fn((...classes: any[]) => classes.filter(Boolean).join(' ')),
+  cn: vi.fn((...classes: Array<string | undefined | null | false>) => classes.filter(Boolean).join(' ')),
 });
 
+/** User-like record for test data generators */
+interface TestUserRecord extends DataRecord {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+/** Column-like shape for test data generators */
+interface TestColumnShape extends DataRecord {
+  id: string;
+  header: string;
+  accessorKey: string;
+}
+
 /**
  * Common test data generators
  */
 export const testDataGenerators = {
-  createUser: (id: number, overrides: any = {}) => ({
+  createUser: (id: number, overrides: Partial<TestUserRecord> = {}): TestUserRecord => ({
     id: `user-${id}`,
     name: `User ${id}`,
     email: `user${id}@example.com`,
     role: 'user',
     ...overrides,
   }),
-  
-  createUsers: (count: number) => 
+
+  createUsers: (count: number): TestUserRecord[] =>
     Array.from({ length: count }, (_, i) => testDataGenerators.createUser(i + 1)),
-  
-  createColumn: (id: string, overrides: any = {}) => ({
+
+  createColumn: (id: string, overrides: Partial<TestColumnShape> = {}): TestColumnShape => ({
     id,
     header: id.charAt(0).toUpperCase() + id.slice(1),
     accessorKey: id,
     ...overrides,
   }),
-  
-  createColumns: (fields: string[] = ['name', 'email', 'role']) =>
-    fields.map(field => testDataGenerators.createColumn(field)),
+
+  createColumns: (fields: string[] = ['name', 'email', 'role']): TestColumnShape[] =>
+    fields.map((field) => testDataGenerators.createColumn(field)),
 };
 
 /**
@@ -227,12 +251,13 @@ export const testFeatures = {
     columnReordering: false,
     hierarchical: false,
   }),
-  
+
   createWithEnabled: (features: string[]): DataTableFeatureConfig => {
     const defaultFeatures = testFeatures.createDefault();
-    features.forEach(feature => {
-      if (feature in defaultFeatures) {
-        (defaultFeatures as any)[feature] = true;
+    features.forEach((feature) => {
+      const key = feature as keyof DataTableFeatureConfig;
+      if (key in defaultFeatures) {
+        (defaultFeatures as Record<keyof DataTableFeatureConfig, boolean>)[key] = true;
       }
     });
     return defaultFeatures;
@@ -242,7 +267,7 @@ export const testFeatures = {
 /**
  * Common test actions
  */
-export const testActions: DataTableAction<any>[] = [
+export const testActions: DataTableAction<DataRecord>[] = [
   {
     label: 'Edit',
     icon: MockEditIcon,
@@ -271,12 +296,12 @@ export const testPermissions = {
  * Common test scenarios
  */
 export const testScenarios = {
-  emptyData: [],
+  emptyData: [] as DataRecord[],
   singleRow: [testDataGenerators.createUser(1)],
   multipleRows: testDataGenerators.createUsers(5),
   largeDataset: testDataGenerators.createUsers(1000),
-  invalidData: null as any,
-  malformedData: [{ invalid: 'data' }],
+  invalidData: null as unknown as DataRecord[],
+  malformedData: [{ invalid: 'data' }] as DataRecord[],
 };
 
 /**
@@ -287,12 +312,12 @@ export const testAssertions = {
     const table = document.querySelector('table');
     expect(table).toBeInTheDocument();
   },
-  
+
   rendersMockedCells: (expectedCount: number) => {
     const cells = document.querySelectorAll('text:contains("Mocked Cell")');
     expect(cells).toHaveLength(expectedCount);
   },
-  
+
   hasCorrectStructure: () => {
     expect(document.querySelector('[data-testid="data-table-context"]')).toBeInTheDocument();
     expect(document.querySelector('[data-testid="data-table-toolbar"]')).toBeInTheDocument();
@@ -307,19 +332,21 @@ export const testCleanup = {
   clearAllMocks: () => {
     vi.clearAllMocks();
   },
-  
+
   resetModules: () => {
     vi.resetModules();
   },
-  
+
   restoreAllMocks: () => {
     vi.restoreAllMocks();
   },
 };
 
 /**
- * Common test error handling
+ * Common test error handling.
+ * Test utility: intentionally mocks console for suppressed error/warning/log output in tests.
  */
+/* eslint-disable no-console */
 export const testErrorHandling = {
   suppressConsoleErrors: () => {
     const originalError = console.error;
@@ -328,7 +355,7 @@ export const testErrorHandling = {
       console.error = originalError;
     };
   },
-  
+
   suppressConsoleWarnings: () => {
     const originalWarn = console.warn;
     console.warn = vi.fn();
@@ -336,16 +363,16 @@ export const testErrorHandling = {
       console.warn = originalWarn;
     };
   },
-  
+
   suppressAllConsole: () => {
     const originalError = console.error;
     const originalWarn = console.warn;
     const originalLog = console.log;
-    
+
     console.error = vi.fn();
     console.warn = vi.fn();
     console.log = vi.fn();
-    
+
     return () => {
       console.error = originalError;
       console.warn = originalWarn;
@@ -353,6 +380,12 @@ export const testErrorHandling = {
     };
   },
 };
+/* eslint-enable no-console */
+
+/** Non-standard Performance with memory (Chrome DevTools). */
+interface PerformanceWithMemory extends Performance {
+  memory?: { usedJSHeapSize: number };
+}
 
 /**
  * Common test performance utilities
@@ -364,20 +397,18 @@ export const testPerformance = {
     const end = performance.now();
     return end - start;
   },
-  
+
   measureMemoryUsage: () => {
-    if ('memory' in performance) {
-      return (performance as any).memory.usedJSHeapSize;
-    }
-    return 0;
+    const perf = performance as PerformanceWithMemory;
+    return perf.memory?.usedJSHeapSize ?? 0;
   },
-  
+
   waitForStableRender: async (maxWait = 1000) => {
-    return new Promise(resolve => {
+    return new Promise<void>((resolve) => {
       const start = performance.now();
       const check = () => {
         if (performance.now() - start > maxWait) {
-          resolve(undefined);
+          resolve();
         } else {
           requestAnimationFrame(check);
         }

package/src/components/DataTable/{__tests__/test-utils.ts → test-utils.ts}

@@ -8,7 +8,7 @@
  * for creating feature configurations and test data.
  */
 
-import type { DataTableFeatureConfig } from '../types';
+import type { DataTableFeatureConfig } from './types';
 
 /**
  * Creates a default feature configuration for testing

package/src/components/DataTable/types/actions.ts

@@ -0,0 +1,71 @@
+/**
+ * @file DataTable action type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import React from 'react';
+import type { DataRecord } from './base';
+
+/** Boolean condition or predicate evaluated against a row */
+export type ActionCondition<TData extends DataRecord> = boolean | ((row: TData) => boolean);
+
+/**
+ * Action definition for DataTable rows.
+ * Defines custom actions that can be performed on table rows.
+ */
+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?: 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) */
+  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;
+  /** 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;
+}
+
+/** Actions prop for row components (MemoizedRow, etc.). */
+export type RowActionsProp<TData extends DataRecord = DataRecord> = DataTableAction<TData>[];
+
+/** 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;
+}

package/src/components/DataTable/types/base.ts

@@ -0,0 +1,39 @@
+/**
+ * @file DataTable base type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+// Extend TanStack Table types to include custom meta properties (must be in a loaded file)
+declare module '@tanstack/react-table' {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ColumnMeta<TData, TValue> {
+    /** Text alignment for the column content */
+    align?: 'left' | 'right' | 'center';
+    /** Column type for styling purposes */
+    type?: 'text' | 'number' | 'date' | 'boolean' | 'custom';
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ColumnDefBase<TData, TValue> {
+    /** Alternative accessor key used while editing */
+    editAccessorKey?: string;
+  }
+}
+
+/** Core value types that can exist in a data record */
+export type CellValue = string | number | boolean | null | undefined | Date;
+
+/**
+ * Base data record type - all DataTable data must extend this.
+ * 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) => RowId;

package/src/components/DataTable/types/columns.ts

@@ -0,0 +1,125 @@
+/**
+ * @file DataTable column type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import React from 'react';
+import type { ColumnDef } from '@tanstack/react-table';
+import type { DataRecord } from './base';
+
+/** Aggregate configuration */
+export interface AggregateConfig {
+  field: string;
+  function: 'sum' | 'avg' | 'count' | 'min' | 'max';
+  label: string;
+}
+
+/**
+ * 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;
+  /** 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 */
+  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<{ row: TData }>;
+  /** Field type for editing (text, select, date, checkbox, etc.) */
+  fieldType?: 'text' | 'select' | 'date' | 'number' | 'boolean' | 'checkbox';
+  /** Options for select fields - can be simple items or grouped with labels and separators */
+  fieldOptions?: Array<
+    | { value: string | number; label: string }
+    | { type: 'group'; label: string; items: Array<{ value: string | number; label: string }> }
+    | { type: 'separator' }
+  >;
+  /** Enable keyboard search/filtering in select dropdowns within editable columns (default: true). */
+  selectSearchable?: boolean;
+  /** Enable creating new items in select dropdowns (default: false) */
+  creatable?: boolean;
+  /** Callback to create a new item when user types non-matching text in select dropdown */
+  onCreateNew?: (inputValue: string) => Promise<string | number> | string | number;
+  /** Maximum height for select dropdown content (default: "20rem") */
+  selectMaxHeight?: string;
+  /** Custom className for select content dropdown */
+  selectContentClassName?: string;
+  /** Custom style for select content dropdown */
+  selectContentStyle?: React.CSSProperties;
+  /** Hide spinner arrows on number input fields (default: true for DataTable) */
+  hideNumberSpinners?: boolean;
+  /** Filter type for column filtering (text, select, number, date) */
+  filterType?: 'text' | 'select' | 'number' | 'date';
+  /** Options for select filters (alternative to fieldOptions) */
+  filterSelectOptions?: Array<{ value: string | number; label: string }>;
+  /** Whether this column is editable in edit mode (default: true) */
+  editable?: boolean;
+  /** Alternative CSV headers that should map to this column during import */
+  importAliases?: string[];
+
+  /** 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;
+
+  /**
+   * Aggregation function for grouped rows.
+   * If not provided, grouped rows will show empty/undefined for this column.
+   */
+  aggregateFn?: (rows: TData[], column: DataTableColumn<TData>) => unknown;
+  /** Optional: Custom cell renderer for aggregated values in grouped rows. */
+  aggregateCell?: (value: unknown, rows: TData[], column: DataTableColumn<TData>) => React.ReactNode;
+}
+
+/**
+ * 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' | 'checkbox';
+  /** Options for select based editors */
+  fieldOptions?: Array<
+    | { value: string | number; label: string }
+    | { type: 'group'; label: string; items: Array<{ value: string | number; label: string }> }
+    | { type: 'separator' }
+  >;
+  selectSearchable?: boolean;
+  creatable?: boolean;
+  onCreateNew?: (inputValue: string) => Promise<string | number> | string | number;
+  hideNumberSpinners?: 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;
+}

package/src/components/DataTable/types/export.ts

@@ -0,0 +1,32 @@
+/**
+ * @file DataTable export type definitions
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Types
+ */
+
+import type { DataRecord } from './base';
+import type { DataTableColumn } from './columns';
+
+/**
+ * Options provided to the onExport handler for custom export functionality
+ */
+export interface ExportOptions<TData extends DataRecord> {
+  /** Filtered table rows with getValue() method for proper accessorFn evaluation */
+  tableRows: Array<{
+    original: TData;
+    getValue: (columnId: string) => unknown;
+    id: string;
+  }>;
+  /** All column definitions passed to the DataTable */
+  allColumns: DataTableColumn<TData>[];
+  /** Currently visible columns in the table */
+  visibleColumns: DataTableColumn<TData>[];
+  /** Mapping of column IDs to TanStack table column instances (for getValue() calls) */
+  columnIdToTableColumn: Map<string, unknown>;
+  /** Raw data array (unfiltered) */
+  data: TData[];
+  /** Default filename generated from table title */
+  filename: string;
+  /** TanStack table instance for advanced operations */
+  table: unknown;
+}