@fgv/ts-sudoku-ui 5.1.0-2 → 5.1.0-21

package/eslint.config.js

@@ -0,0 +1,18 @@
+// ESLint 9 flat config
+const nodeProfile = require('@rushstack/eslint-config/flat/profile/node');
+const packletsPlugin = require('@rushstack/eslint-config/flat/mixins/packlets');
+const tsdocPlugin = require('@rushstack/eslint-config/flat/mixins/tsdoc');
+
+module.exports = [
+  ...nodeProfile,
+  packletsPlugin,
+  ...tsdocPlugin,
+  {
+    // Override specific rules if needed
+    rules: {
+      '@rushstack/packlets/mechanics': 'warn',
+      // Disable no-new-null rule for React components where null is conventional
+      '@rushstack/no-new-null': 'off'
+    }
+  }
+];

package/lib/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.57.6"
+      "packageVersion": "7.57.7"
     }
   ]
 }

package/package.json

@@ -1,19 +1,9 @@
 {
   "name": "@fgv/ts-sudoku-ui",
-  "version": "5.1.0-2",
+  "version": "5.1.0-21",
   "description": "React components for interactive Sudoku puzzle entry and display",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
-  "scripts": {
-    "build": "heft build --clean",
-    "build-docs": "typedoc --options ./config/typedoc.json",
-    "build-all": "rushx build && rushx build-docs",
-    "clean": "heft clean",
-    "test": "heft test --clean",
-    "lint": "eslint src --ext .ts,.tsx",
-    "fixlint": "eslint src --ext .ts,.tsx --fix",
-    "coverage": "jest --coverage"
-  },
   "sideEffects": false,
   "keywords": [
     "typescript",
@@ -31,18 +21,16 @@
   },
   "homepage": "https://github.com/ErikFortune/fgv/tree/main/libraries/ts-sudoku-ui#readme",
   "dependencies": {
-    "@fgv/ts-sudoku-lib": "workspace:*",
-    "@fgv/ts-utils": "workspace:*",
-    "@fgv/ts-json-base": "workspace:*",
-    "tslib": "^2.8.1"
+    "tslib": "^2.8.1",
+    "@fgv/ts-sudoku-lib": "5.1.0-21",
+    "@fgv/ts-utils": "5.1.0-21",
+    "@fgv/ts-json-base": "5.1.0-21"
   },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
   "devDependencies": {
-    "@fgv/heft-dual-rig": "workspace:*",
-    "@fgv/ts-utils-jest": "workspace:*",
     "@types/react": "~19.2.8",
     "@types/react-dom": "~19.2.3",
     "react": "~19.2.3",
@@ -64,8 +52,8 @@
     "rimraf": "^6.1.2",
     "ts-jest": "^29.4.6",
     "typescript": "5.9.3",
-    "@rushstack/heft": "1.2.6",
-    "@rushstack/heft-web-rig": "1.4.2",
+    "@rushstack/heft": "1.2.7",
+    "@rushstack/heft-web-rig": "1.4.3",
     "@rushstack/eslint-config": "4.6.4",
     "@rushstack/heft-jest-plugin": "1.2.6",
     "@microsoft/api-documenter": "^7.28.2",
@@ -75,7 +63,10 @@
     "postcss": "~8.5.6",
     "autoprefixer": "~10.4.23",
     "typedoc": "~0.28.16",
-    "typedoc-plugin-markdown": "~4.9.0"
+    "typedoc-plugin-markdown": "~4.9.0",
+    "@fgv/heft-dual-rig": "5.1.0-21",
+    "@fgv/typedoc-compact-theme": "5.1.0-21",
+    "@fgv/ts-utils-jest": "5.1.0-21"
   },
   "exports": {
     ".": {
@@ -93,5 +84,15 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/ErikFortune/fgv.git"
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "build-docs": "typedoc --options ./config/typedoc.json",
+    "build-all": "rushx build && rushx build-docs",
+    "clean": "heft clean",
+    "test": "heft test --clean",
+    "lint": "eslint src --ext .ts,.tsx",
+    "fixlint": "eslint src --ext .ts,.tsx --fix",
+    "coverage": "jest --coverage"
   }
-}
+}

package/.test-failures-catalog.md

@@ -1,470 +0,0 @@
-# Test Failures Catalog - ts-sudoku-ui
-
-**Date**: 2025-01-27
-**Total Tests**: 309
-**Passing**: 262 (84.7%)
-**Failing**: 47 (15.3%)
-
----
-
-## Summary by Test Suite
-
-| Test Suite | Passing | Failing | Status |
-|------------|---------|---------|--------|
-| usePuzzleSession.test.ts | 30 | 5 | ⚠️ Partial |
-| SudokuGridEntry.test.tsx | 3 | 30 | ❌ Critical |
-| SudokuGridSudokuX.test.tsx | 7 | 12 | ❌ Major |
-| usePuzzleSessionNotes.test.ts | 0 | 0 | ❌ Timeout/OOM |
-
----
-
-## 1. usePuzzleSession.test.ts (5 failures)
-
-### Issue Type: Async Timing Problems
-
-**Root Cause**: Tests expect synchronous hook initialization, but `usePuzzleSession` uses `useEffect` for async initialization.
-
-### Failing Tests:
-
-#### 1.1 "should update when initial puzzle description changes"
-```typescript
-// Location: Line 93
-// Error: expect(received).toBe(expected)
-// Expected: "simple-puzzle"
-// Received: undefined
-```
-**Problem**: Session.id is undefined because useEffect hasn't completed
-**Fix Needed**: Increase waitFor timeout or add initial render wait
-
-#### 1.2 "should show immutable cells for pre-filled puzzle"
-```typescript
-// Location: Line 131
-// Error: expect(received).toBeGreaterThan(expected)
-// Expected: > 0
-// Received: 0
-```
-**Problem**: cellDisplayInfo array is empty before useEffect completes
-**Fix Needed**: Wait for cellDisplayInfo.length > 0 before assertions
-
-#### 1.3 "should not allow updates to immutable cells"
-```typescript
-// Location: Line 209
-// Error: expect(received).toBeGreaterThan(expected)
-// Expected: > 0
-// Received: 0
-```
-**Problem**: Same as 1.2 - cellDisplayInfo not populated yet
-**Fix Needed**: Same as 1.2
-
-#### 1.4 "should reset puzzle to initial state"
-```typescript
-// Location: Line 451
-// Error: expect(received).toBeGreaterThan(expected)
-// Expected: > 0
-// Received: 0
-```
-**Problem**: Same as 1.2 - cellDisplayInfo not populated yet
-**Fix Needed**: Same as 1.2
-
-#### 1.5 "should reset without error when session exists"
-```typescript
-// Location: Line 487
-// Error: expect(received).not.toBeNull()
-// Received: null
-```
-**Problem**: Session is null before useEffect completes
-**Fix Needed**: Wait for session to be non-null
-
-### Recommended Solution:
-```typescript
-// Option 1: Add longer timeout to waitFor
-await waitFor(() => {
-  expect(result.current.session).not.toBeNull();
-}, { timeout: 5000 });
-
-// Option 2: Make hook initialization synchronous
-// Move session creation outside useEffect if possible
-
-// Option 3: Use renderHook with initialProps and wait
-const { result } = renderHook(() => usePuzzleSession(puzzle));
-await waitFor(() => result.current.session !== null);
-```
-
----
-
-## 2. SudokuGridEntry.test.tsx (30 failures)
-
-### Issue Type: Component Not Rendering
-
-**Root Cause**: SudokuGridEntry component depends on usePuzzleSession hook, which has async initialization issues. Component doesn't render until session is ready.
-
-### Failing Tests: ALL 30 tests
-
-**Common Error Pattern**:
-```
-Unable to find an element by: [data-testid="sudoku-grid-entry"]
-
-<body id="test-root" />
-```
-
-### Test Categories:
-
-#### 2.1 Rendering Tests (5 failures)
-- should render loading state initially
-- should render main components after initialization
-- should apply custom className
-- should render with initial puzzle description
-- should render default puzzle when no initial description provided
-
-**Problem**: Component body is completely empty
-
-#### 2.2 Error Handling Tests (2 failures)
-- should show error state for invalid puzzle
-- should apply className even in error state
-
-**Problem**: Error state elements not found (sudoku-grid-entry-error)
-
-#### 2.3 Loading State Tests (1 failure)
-- should show loading state when session is null
-
-**Problem**: Cannot find sudoku-grid-entry element
-
-#### 2.4 Cell Interaction Tests (3 failures)
-- should handle cell selection
-- should handle cell value changes
-- should handle keyboard navigation
-
-**Problem**: Cannot find sudoku-grid child elements
-
-#### 2.5 Controls Integration Tests (4 failures)
-- should handle undo/redo operations
-- should handle reset operation
-- should handle export operation
-- should handle export with custom puzzle data
-
-**Problem**: Cannot find sudoku-controls element
-
-#### 2.6 Validation Display Tests (3 failures)
-- should show validation errors for duplicate values
-- should clear validation errors when conflicts resolved
-- should update validation display when cells change
-
-**Problem**: Cannot find validation-display element
-
-#### 2.7 Puzzle Type Tests (2 failures)
-- should handle standard Sudoku puzzles
-- should handle Sudoku X puzzles
-
-**Problem**: Component not rendering
-
-#### 2.8 Integration Edge Cases (4 failures)
-- should handle puzzle type changes
-- should handle rapid state updates
-- should maintain state consistency across operations
-- should handle all control operations in sequence
-
-**Problem**: Component not rendering
-
-#### 2.9 Layout Tests (2 failures)
-- should render components in correct order
-- should apply responsive styling
-
-**Problem**: Component not rendering
-
-#### 2.10 Additional Tests (4 more failures)
-All with same issue - component not rendering
-
-### Recommended Solution:
-
-**Immediate**: Fix usePuzzleSession async issues first (dependency blocker)
-
-**Then**:
-```typescript
-// Option 1: Update test setup to wait for component
-const customRender = (ui: React.ReactElement) => {
-  const result = render(ui);
-  return waitFor(() => {
-    expect(screen.getByTestId('sudoku-grid-entry')).toBeInTheDocument();
-  }).then(() => result);
-};
-
-// Option 2: Mock usePuzzleSession hook
-jest.mock('../../../hooks/usePuzzleSession', () => ({
-  usePuzzleSession: () => mockSessionData
-}));
-
-// Option 3: Fix SudokuGridEntry to show loading state while initializing
-// Add conditional rendering:
-if (!session) {
-  return <div data-testid="sudoku-grid-entry-loading">Loading...</div>;
-}
-```
-
----
-
-## 3. SudokuGridSudokuX.test.tsx (12 failures)
-
-### Issue Type: Missing Sudoku X Visual Features
-
-**Root Cause**: Diagonal line rendering and highlighting for Sudoku X puzzles not implemented or not working correctly.
-
-### Failing Tests:
-
-#### 3.1 Diagonal Line Rendering Tests (2 failures)
-
-**Test**: "should render diagonal lines for Sudoku X puzzles"
-```typescript
-// Location: Line 87
-// Error: expect(received).toBeGreaterThan(expected)
-// Expected: > 0
-// Received: 0
-```
-**Problem**: No diagonal line elements found in DOM
-**Looking for**: `[class*="diagonal"]`, `[class*="x-line"]`, `svg line`
-**Fix Needed**: Implement diagonal line rendering in SudokuGrid component
-
-**Test**: "should not render diagonal lines for standard Sudoku puzzles"
-- Likely passes if diagonal rendering is properly conditional
-
-#### 3.2 Cell Interaction Tests (3 failures)
-
-**Test**: "should highlight diagonal cells when cell on diagonal is selected"
-```typescript
-// Location: Line 157
-// Error: expect(received).toBeGreaterThan(expected)
-// Expected: > 0
-// Received: 0
-```
-**Problem**: No cells with diagonal highlight classes found
-**Looking for**: `[class*="diagonal-highlight"]`, `[class*="diagonal-cell"]`
-**Fix Needed**: Add diagonal cell highlighting when cell selected
-
-**Test**: "should handle click events on diagonal cells"
-```typescript
-// Error: Unable to find a label with the text of: /A1|cell.*0.*0/i
-```
-**Problem**: Cell aria-label doesn't match expected format
-**Current**: "Row 1, Column 1, empty"
-**Expected**: Pattern includes "A1" or "cell.*0.*0"
-**Fix Needed**: Update test matcher or cell aria-label format
-
-**Test**: "should handle keyboard navigation through diagonal cells"
-```typescript
-// Error: expect(jest.fn()).toHaveBeenCalled()
-// Expected: >= 1
-// Received: 0
-```
-**Problem**: onSelect callback not called during navigation
-**Fix Needed**: Verify keyboard navigation triggers onSelect for diagonal cells
-
-#### 3.3 Validation Error Display Tests (3 failures)
-
-**Test**: "should display validation errors for diagonal cells"
-```typescript
-// Error: expect(received).toBeGreaterThan(expected)
-// Expected: > 0
-// Received: 0
-```
-**Problem**: No error cells found for diagonal conflicts
-**Fix Needed**: Ensure diagonal validation creates visible error indicators
-
-**Test**: "should distinguish between different types of validation errors"
-- Similar to above
-
-**Test**: "should clear diagonal validation errors when conflict resolved"
-- Similar to above
-
-#### 3.4 Accessibility Tests (2 failures)
-
-**Test**: "should provide appropriate ARIA labels for diagonal cells"
-```typescript
-// Error: Unable to find a label with specified pattern
-```
-**Problem**: Aria-labels don't indicate diagonal membership
-**Fix Needed**: Add diagonal info to cell aria-labels
-
-**Test**: "should announce validation errors for diagonal constraints to screen readers"
-```typescript
-// Error: expect(received).toBeGreaterThan(expected)
-// Expected: > 0
-// Received: 0
-```
-**Problem**: No aria-live regions or error announcements
-**Fix Needed**: Add screen reader announcements for diagonal errors
-
-#### 3.5 Responsive Design Test (1 failure)
-
-**Test**: "should maintain diagonal line visibility at different zoom levels"
-```typescript
-// Error: expect(received).toBeGreaterThan(expected)
-// Expected: > 0
-// Received: 0
-```
-**Problem**: No diagonal lines to test
-**Fix Needed**: Implement diagonal lines first
-
-#### 3.6 Performance Test (1 failure)
-
-**Test**: "should not impact performance for standard Sudoku"
-- Dependency on diagonal rendering implementation
-
-### Recommended Solution:
-
-**Step 1**: Implement diagonal line rendering in SudokuGrid
-```typescript
-// In SudokuGrid component:
-{puzzleType === 'sudoku-x' && (
-  <div className="absolute inset-0 pointer-events-none">
-    <svg className="w-full h-full">
-      <line
-        x1="0"
-        y1="0"
-        x2="100%"
-        y2="100%"
-        className="diagonal-line"
-        stroke="currentColor"
-      />
-      <line
-        x1="100%"
-        y1="0"
-        x2="0"
-        y2="100%"
-        className="diagonal-line"
-        stroke="currentColor"
-      />
-    </svg>
-  </div>
-)}
-```
-
-**Step 2**: Add diagonal highlighting to cells
-```typescript
-// In SudokuCell or SudokuGrid:
-const isDiagonalCell = (row, col) => row === col || row + col === 8;
-const isOnSelectedDiagonal = selectedCell && isDiagonalCell(selectedCell.row, selectedCell.col);
-
-// Add class: isOnSelectedDiagonal ? 'diagonal-highlight' : ''
-```
-
-**Step 3**: Update aria-labels to include diagonal info
-```typescript
-aria-label={`Row ${row + 1}, Column ${col + 1}${
-  isDiagonalCell(row, col) ? ', diagonal' : ''
-}, ${value || 'empty'}`}
-```
-
-**Step 4**: Ensure validation errors show for diagonal conflicts
-- usePuzzleSession already checks diagonal duplicates (lines 139-150)
-- Verify error rendering in UI
-
----
-
-## 4. usePuzzleSessionNotes.test.ts (Timeout/OOM)
-
-### Issue Type: Build Error & Memory Exhaustion
-
-**Root Cause**: TypeScript compilation error causes infinite loop or memory leak during test execution.
-
-### Error Details:
-
-**TypeScript Error**:
-```
-src/hooks/usePuzzleSession.ts(258,28):
-error TS2802: Type 'Set<CellId>' can only be iterated through when using
-the '--downlevelIteration' flag or with a '--target' of 'es2015' or higher.
-```
-
-**Runtime Error**:
-```
-FATAL ERROR: Ineffective mark-compacts near heap limit
-Allocation failed - JavaScript heap out of memory
-```
-
-### Problematic Code:
-```typescript
-// Line 258 in usePuzzleSession.ts:
-for (const cellId of affectedCells) {  // affectedCells is a Set<CellId>
-  // ...
-}
-```
-
-### Recommended Solution:
-
-**Option 1**: Update tsconfig.json
-```json
-{
-  "compilerOptions": {
-    "downlevelIteration": true
-  }
-}
-```
-
-**Option 2**: Convert Set to Array
-```typescript
-// Before:
-for (const cellId of affectedCells) {
-
-// After:
-for (const cellId of Array.from(affectedCells)) {
-```
-
-**Option 3**: Use forEach
-```typescript
-affectedCells.forEach((cellId) => {
-  // ...
-});
-```
-
----
-
-## Priority Ranking
-
-### 🔴 Critical (Blocks other tests):
-1. **usePuzzleSession async timing** - Blocks SudokuGridEntry tests
-2. **usePuzzleSessionNotes TypeScript/OOM** - Prevents test suite completion
-
-### 🟡 High (Feature incomplete):
-3. **SudokuGridSudokuX diagonal rendering** - Core Sudoku X feature missing
-
-### 🟢 Medium (Integration tests):
-4. **SudokuGridEntry component tests** - Depends on #1
-
----
-
-## Estimated Fix Complexity
-
-| Issue | Lines of Code | Files | Complexity | Est. Time |
-|-------|---------------|-------|------------|-----------|
-| usePuzzleSession timing | ~50 | 1-2 | Medium | 1-2 hours |
-| usePuzzleSessionNotes TS | ~5 | 1 | Low | 15 mins |
-| Sudoku X diagonals | ~100-150 | 2-3 | High | 3-4 hours |
-| SudokuGridEntry tests | ~200 | 1 | Low* | 30 mins* |
-
-*After fixing dependencies
-
----
-
-## Next Steps
-
-1. ✅ Fix TypeScript compilation error (15 mins)
-2. ⏳ Fix usePuzzleSession async timing (1-2 hours)
-3. ⏳ Implement Sudoku X diagonal rendering (3-4 hours)
-4. ⏳ Re-run SudokuGridEntry tests (should auto-fix)
-
-**Total Estimated Time**: 5-7 hours
-
----
-
-## Test Coverage Impact
-
-**Current Coverage**: 78.48% statements, 80.55% branches
-
-**After Fixes**: Estimated 95%+ statements, 90%+ branches
-
-**Uncovered Areas**:
-- CageOverlay.tsx: 22.68% (Killer Sudoku feature)
-- CageSumIndicator.tsx: 35.95% (Killer Sudoku feature)
-- CageLookupManager.ts: 34.98% (Killer Sudoku utils)
-- CagePatternManager.ts: 62.44% (Killer Sudoku utils)
-
-These are separate Killer Sudoku features, not related to current test failures.

package/CHANGELOG.md

@@ -1,11 +0,0 @@
-# Change Log - @fgv/ts-sudoku-ui
-
-This log was last generated on Wed, 17 Dec 2025 18:08:09 GMT and should not be manually modified.
-
-## 5.0.2
-Wed, 17 Dec 2025 18:08:09 GMT
-
-### Updates
-
-- ui components for sudoku lib
-