docs(18-02): complete batch edit UI plan

- SUMMARY.md with task commits, deviations, and self-check - STATE.md updated: Phase 18 complete, all BATCH requirements fulfilled - ROADMAP.md updated: 2/2 plans complete for Phase 18 - REQUIREMENTS.md updated: BATCH-02 and BATCH-04 marked complete
2026-03-18 13:53:53 -04:00
parent d430ad884b
commit 77dec0bceb
4 changed files with 163 additions and 21 deletions
@@ -0,0 +1,139 @@
+---
+phase: 18-batch-edit
+plan: 02
+subsystem: ui
+tags: [lit, batch-edit, track-details, three-state, progress, wails]
+
+# Dependency graph
+requires:
+  - phase: 18-batch-edit/01
+    provides: BatchWriteTrackTags method, CancelBatchWrite, BatchWriteProgress event, BatchResult types
+  - phase: 17-single-track-edit
+    provides: Track-details dialog, single-track edit flow, cover art editing, WriteTrackTagsByPath pipeline
+provides:
+  - Batch edit mode in track-details component (showBatch API)
+  - Three-state field model (keep/set/clear) via dirty-tracking editValues
+  - Confirmation dialog with change summary before batch save
+  - Live progress bar with "N of M" counter during batch writes
+  - Batch cancel button wired to CancelBatchWrite
+  - Results view with success/failure counts and expandable failure details
+  - Batch cover art pick/clear for all selected tracks
+  - All 4 view components (track-list, cover-grid, queue-panel, playlist-details) dispatch to showBatch for multi-select
+affects: [19-ogg-vorbis]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [getMergedFields for batch field aggregation, three-state implicit dirty tracking, confirmation overlay pattern, Wails EventsOn/Off for progress streaming]
+
+key-files:
+  created: []
+  modified:
+    - frontend/src/components/track-details/track-details.ts
+    - frontend/src/components/track-list/track-list.ts
+    - frontend/src/components/cover-grid/cover-grid.ts
+    - frontend/src/components/queue-panel/queue-panel.ts
+    - frontend/src/components/playlist-details/playlist-details.ts
+
+key-decisions:
+  - "Three-state field model via implicit editValues dirty tracking — untouched fields not in editValues (keep), typed fields in editValues (set), cleared fields in editValues with empty string (clear)"
+  - "Confirmation overlay within dialog rather than separate dialog — simpler implementation, consistent UX"
+  - "Field labels added to all track-details states for consistency (single/batch, read/edit)"
+
+patterns-established:
+  - "showBatch(tracks, coverArt, coverArtMixed) as public batch entry API alongside existing show()"
+  - "getMergedFields() for computing shared vs mixed values across N tracks"
+  - "openBatchTrackDetails(filePaths) method pattern on each view component"
+
+requirements-completed: [BATCH-01, BATCH-02, BATCH-03, BATCH-04]
+
+# Metrics
+duration: ~30min
+completed: 2026-03-18
+---
+
+# Phase 18 Plan 02: Frontend Batch Edit UI Summary
+
+**Batch edit mode in track-details dialog with three-state field editing, merged value display, confirmation guard, live progress bar, partial failure reporting, and batch cover art — wired from all 4 view context menus**
+
+## Performance
+
+- **Duration:** ~30 min (across checkpoint session)
+- **Started:** 2026-03-18T17:02:40Z
+- **Completed:** 2026-03-18T18:30:00Z
+- **Tasks:** 3 (2 auto + 1 checkpoint:human-verify)
+- **Files modified:** 5
+
+## Accomplishments
+- Track-details component extended with full batch mode: showBatch() API, merged field summary, three-state editing, confirmation dialog, progress bar with Wails event streaming, results view with failure details, batch cover art
+- All 4 view components (track-list, cover-grid, queue-panel, playlist-details) branch on selection count — 1 track → single mode, 2+ tracks → batch mode via openBatchTrackDetails
+- Field labels added to all track-details states (single/batch, read/edit) for consistency
+- Human verification confirmed all batch edit flows work: summary view, editing, confirmation, progress, results, cover art, and single-track regression
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add batch mode to track-details component** - `6dab32b` (feat)
+2. **Task 2: Update all view context menu handlers for batch mode** - `656985a` (feat)
+3. **Task 3: Verify complete batch edit flow** - checkpoint:human-verify (approved)
+
+Additional fix commits during verification:
+- `9df2d67` — fix(18-02): add field labels above title/artist/album inputs in batch edit mode
+- `d430ad8` — fix(18-02): add field labels to all track-details states (single/batch, read/edit)
+
+## Files Created/Modified
+- `frontend/src/components/track-details/track-details.ts` — Batch mode: showBatch(), getMergedFields(), three-state editing, confirmation overlay, progress bar, results view, batch cover art, field labels
+- `frontend/src/components/track-list/track-list.ts` — openBatchTrackDetails with album-based cover art resolution
+- `frontend/src/components/cover-grid/cover-grid.ts` — openBatchTrackDetails with album-based cover art resolution
+- `frontend/src/components/queue-panel/queue-panel.ts` — openBatchTrackDetails resolving queue tracks to library tracks
+- `frontend/src/components/playlist-details/playlist-details.ts` — openBatchTrackDetails with album-based cover art resolution
+
+## Decisions Made
+- Three-state field model implemented via implicit dirty tracking in editValues map — no explicit "state" enum needed; the existing onEditInput handler naturally creates the keep/set/clear distinction
+- Confirmation dialog implemented as an overlay within the existing dialog rather than spawning a second dialog — simpler DOM management and consistent visual context
+- Field labels added across all track-details rendering states (not just batch edit) during verification for visual consistency
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Added field labels to batch edit inputs**
+- **Found during:** Task 3 (human verification checkpoint)
+- **Issue:** Batch edit mode inputs lacked field labels, making it unclear which field was which
+- **Fix:** Added visible labels above title/artist/album inputs in batch edit mode
+- **Files modified:** frontend/src/components/track-details/track-details.ts
+- **Verification:** Visual inspection in running app
+- **Committed in:** `9df2d67`
+
+**2. [Rule 1 - Bug] Added field labels to all track-details states**
+- **Found during:** Task 3 (human verification checkpoint)
+- **Issue:** After adding labels to batch edit, single-track mode also lacked consistent labels
+- **Fix:** Added field labels to single-track read and edit modes for consistency
+- **Files modified:** frontend/src/components/track-details/track-details.ts
+- **Verification:** Visual inspection confirming labels appear in all 4 states (single read, single edit, batch read, batch edit)
+- **Committed in:** `d430ad8`
+
+---
+
+**Total deviations:** 2 auto-fixed (2 bugs — missing UI labels)
+**Impact on plan:** Both fixes improve usability. No scope creep — labels were implicit in the plan's field display requirements.
+
+## Issues Encountered
+None
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Phase 18 complete — all batch edit requirements (BATCH-01 through BATCH-04) fulfilled
+- Phase 19 (OGG Vorbis Tag Writing) can proceed independently — depends on Phase 16 backend, not Phase 18
+
+## Self-Check: PASSED
+
+All 5 key files verified on disk. All 4 task/fix commits (6dab32b, 656985a, 9df2d67, d430ad8) verified in git log.
+
+---
+*Phase: 18-batch-edit*
+*Completed: 2026-03-18*