@jmruthers/pace-core 0.6.9 → 0.6.11

package/src/components/DataTable/README.md

@@ -0,0 +1,155 @@
+# DataTable
+
+This directory contains the DataTable component, its tests, and supporting code.
+
+## Architecture
+
+- **Main flow:** `DataTable` → `DataTableCore` (hooks + props) → `DataTableLayout`. State and behaviour are driven by hooks (e.g. `useDataTableState`, `useDataTablePipeline`); only `ColumnFactory` in `core/` is used in production.
+- **Context API (internal):** `DataTableProvider` and `useDataTableContext` in `context/DataTableContext.tsx` provide shared table state for **custom layouts** only. They are not used by the main DataTable path and are not exported from the package. Use them only when building a custom layout that needs the same state shape.
+- **Testing:** See [TESTING.md](./TESTING.md) for coverage targets (utils/hooks ≥90%, components ≥70%), real vs mocked hooks, and integration-light strategy.
+
+## Test Suite
+
+The tests below are designed to prevent regressions and ensure critical functionality works correctly.
+
+## Test Files Overview
+
+### Regression Prevention Tests
+
+- **`DataTable.workflowValidation.test.tsx`** - Comprehensive workflow validation covering all core functionality
+- **`DataTable.regressionFixes.test.tsx`** - Documents specific fixes and prevents known regressions
+- **`DataTable.sorting.test.tsx`** - Comprehensive sorting functionality tests including visual indicators and accessibility
+
+### Existing Tests
+
+- **`DataTable.simple.test.tsx`** - Basic rendering tests
+- **`DataTable.integration.test.tsx`** - Cross-component integration tests
+- **`DataTable.performance.test.tsx`** - Performance benchmarks
+- **`DataTable.errorHandling.test.tsx`** - Error condition handling
+- **`DataTable.permissions.test.tsx`** - RBAC and permissions testing
+- **`DataTable.userWorkflows.test.tsx`** - User interaction flows
+
+## Test Strategy
+
+### 1. Workflow Validation (23 tests)
+The `DataTable.workflowValidation.test.tsx` file provides comprehensive coverage of:
+
+- **Basic Rendering Workflows (3 tests)**
+  - Data display validation
+  - Header rendering
+  - Actions column conditionals
+
+- **Editing Workflow Validation (5 tests)** 
+  - Actions column presence
+  - Edit button rendering and icons
+  - Handler requirements
+  - Click behavior validation
+
+- **Deletion Workflow Validation (4 tests)**
+  - Delete button rendering and icons
+  - Immediate handler execution
+  - Handler requirements
+
+- **Combined Features Validation (2 tests)**
+  - Both edit and delete enabled
+  - Mixed interactions
+
+- **Search Workflow Validation (3 tests)**
+  - Search functionality
+  - Filtering behavior
+  - Actions preservation during search
+
+- **Sorting Workflow Validation (4 tests)**
+  - Sortable column indicators (↕️ unsorted, ↑ ascending, ↓ descending)
+  - Click behavior for sorting
+  - Non-sortable column behavior
+  - Visual feedback and accessibility
+
+- **Data Integrity Validation (3 tests)**
+  - Exact prop data display
+  - Empty data handling
+  - Null/undefined value handling
+
+- **Accessibility Validation (3 tests)**
+  - Semantic table structure
+  - ARIA labels
+  - Keyboard navigation support
+
+### 2. Regression Fixes (13 tests)
+The `DataTable.regressionFixes.test.tsx` file documents specific fixes:
+
+- **Save and Cancel Actions in allActions Array (3 tests)**
+  - Validates the fix for the actions filtering logic
+  - Ensures Save/Cancel buttons are included in action processing
+
+- **Action Button Icons and Behavior (4 tests)**
+  - Pencil icons for Edit buttons
+  - Trash2 icons for Delete buttons
+  - Correct edit mode entry behavior
+  - Immediate delete handler execution
+
+- **Action Button Validation (3 tests)** 
+  - ARIA label maintenance
+  - Conditional actions column rendering
+  - Handler requirement enforcement
+
+- **Data Integrity Prevention (3 tests)**
+  - Exact data display
+  - Empty data graceful handling
+  - Semantic structure maintenance
+
+## Critical Regression Fix
+
+### The Save/Cancel Actions Bug
+**Issue**: Edit buttons appeared but Save/Cancel buttons didn't appear in edit mode.
+**Root Cause**: The action filtering logic in DataTable component only included `edit` and `delete` actions in the `allActions` array, excluding `save` and `cancel` actions.
+**Fix**: Updated the filtering logic to include all built-in actions:
+
+```typescript
+// BEFORE (broken):
+const editActions = builtInActions.filter(action => action.testId === 'edit');
+const deleteActions = builtInActions.filter(action => action.testId === 'delete');
+const allActions = [...(actions || []), ...editActions, ...deleteActions];
+
+// AFTER (fixed):
+const editActions = builtInActions.filter(action => action.testId === 'edit');
+const saveActions = builtInActions.filter(action => action.testId === 'save');
+const cancelActions = builtInActions.filter(action => action.testId === 'cancel');
+const deleteActions = builtInActions.filter(action => action.testId === 'delete');
+const allActions = [...(actions || []), ...editActions, ...saveActions, ...cancelActions, ...deleteActions];
+```
+
+## Running Tests
+
+Run all DataTable tests:
+```bash
+npm test -- src/components/DataTable/
+```
+
+Run specific test suites:
+```bash
+# Workflow validation tests
+npm test -- src/components/DataTable/DataTable.workflowValidation.test.tsx
+
+# Regression fix tests  
+npm test -- src/components/DataTable/DataTable.regressionFixes.test.tsx
+
+# Sorting functionality tests
+npm test -- src/components/DataTable/DataTable.sorting.test.tsx
+
+# Simple integration tests
+npm test -- src/components/DataTable/DataTable.simple.test.tsx
+```
+
+## Test Coverage Summary
+
+- **91 total tests** in new regression prevention suites
+- **100% pass rate** for workflow validation
+- **100% pass rate** for regression fixes
+- **100% pass rate** for auto-sizing functionality
+- **Critical action rendering validated**
+- **Search and data integrity confirmed**
+- **Auto-sizing behavior verified**
+- **Accessibility standards maintained**
+
+This test suite ensures DataTable reliability and prevents future regressions in critical editing workflows. 

package/src/components/DataTable/TESTING.md

@@ -0,0 +1,101 @@
+# DataTable Testing Strategy
+
+This document describes the DataTable test strategy, which tests run **real** vs **mocked** hooks, how to run integration-light tests, and Standard 8 coverage targets (utils/hooks ≥90%, components ≥70%).
+
+## Coverage Targets (Standard 8)
+
+- **Utils and hooks**: ≥90% line coverage
+- **Components**: ≥70% line coverage
+
+## Low-Coverage Files
+
+Measured via `npm run test:coverage`. Refresh this table after running coverage: remove files that meet targets; add any that fall below.
+
+### Hooks (target ≥90%)
+
+Unit tests have been added for: useDataTableEffectiveActions, useDataTableLayoutHandlers, useDataTableRenderGuard, useDataTableStateAndPersistence, useDataTableSuperAdmin. After coverage run, list any hooks still below 90% here.
+
+### Components (target ≥70%)
+
+ImportModal preview/summary sections are exercised via integration-light (filtering, column visibility, import modal, pagination, grouping). List any components still below 70% after coverage run.
+
+### Utils (target ≥90%)
+
+selectFieldUtils (including optionMatchesSearch) has dedicated unit tests. List any utils still below 90% after coverage run.
+
+### Test-only / mocks (excluded from targets)
+
+- test-utils (RenderDataTableComponents, renderDataTableTestUtils, dataFactories): test helpers; coverage optional.
+- mocks/DataTableCProvider.tsx: test mock; coverage optional.
+
+## Which Tests Run Real vs Mocked Hooks
+
+### Fully mocked (DataTableCore.test-setup.ts, DataTableCore.test.tsx)
+
+These tests render **DataTableCore** but mock the core DataTable hooks, so the **implementations** of the following are **not** executed:
+
+- `useDataTableState`
+- `useDataTableStateAndPersistence`
+- `useDataTablePipeline`
+- `useDataTablePerformance`
+- `useDataTableRenderGuard`
+- `useHierarchicalState`
+- `useColumnOrderPersistence`
+- `ColumnFactory`
+- `useDataTablePermissions`
+- `useTableColumns`
+- Hierarchical utils
+
+Use these tests for fast, isolated UI and prop behavior.
+
+### Integration-light (DataTableCore.integration.test.tsx)
+
+These tests render **DataTableCore** with **real** implementations of:
+
+- `useDataTableState`
+- `useDataTableStateAndPersistence`
+- `useDataTablePipeline`
+- `useDataTableDeletionBatching`
+- `useDataTableRenderGuard`
+- `useHierarchicalState`
+- `useColumnOrderPersistence`
+- `useTableColumns`
+- `ColumnFactory`
+- Data pipeline and table instance hooks
+
+Only the following are mocked (external I/O and environment):
+
+- `useUnifiedAuth`
+- `useCan` / `useResolvedScope` (RBAC)
+- `useDataTablePerformance` (client-side, no server fetch)
+- `useIsPrint`
+- Router is provided via `MemoryRouter` (real `useLocation`).
+
+Integration-light tests exercise the real DataTable hook chain and main components to improve coverage of DataTableCore, useDataTablePipeline, useDataTableStateAndPersistence, useDataTableTableInstance, etc.
+
+## Phase C: Real Child Hooks
+
+The **integration-light** tests (see above) are the primary path that runs the real DataTable hook chain (useDataTableState, useDataTableStateAndPersistence, useDataTablePipeline, etc.). No separate “with real child hooks” unit tests are required for the pipeline; integration-light fulfills that goal. Individual hook unit tests may continue to mock child hooks for speed and isolation.
+
+## How to Run Integration-Light Tests
+
+```bash
+# All DataTable tests (includes integration-light)
+npm test -- packages/core/src/components/DataTable/
+
+# Only integration-light suite
+npm test -- packages/core/src/components/DataTable/DataTableCore.integration.test.tsx
+```
+
+## Running Coverage
+
+```bash
+npm run test:coverage
+```
+
+Open the HTML report under `coverage/` (e.g. `coverage/index.html`) and drill into `packages/core/src/components/DataTable/` to see per-file line and branch coverage.
+
+## Unit test priorities
+
+1. **Hooks and utils first** — aim for ≥90% line coverage via unit tests (colocated `*.test.ts` / `*.test.tsx`).
+2. **Integration-light expansion** — add scenarios (filtering, column visibility, import, pagination, grouping) to reach ≥70% component coverage without isolated subcomponent unit tests.