From 77dec0bceb19c1b01accbb9cc26f5bd13c05a65a Mon Sep 17 00:00:00 2001 From: Caleb Allen Date: Wed, 18 Mar 2026 13:53:53 -0400 Subject: [PATCH] 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 --- .planning/REQUIREMENTS.md | 8 +- .planning/ROADMAP.md | 6 +- .planning/STATE.md | 31 ++-- .../phases/18-batch-edit/18-02-SUMMARY.md | 139 ++++++++++++++++++ 4 files changed, 163 insertions(+), 21 deletions(-) create mode 100644 .planning/phases/18-batch-edit/18-02-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 9e1b169..e25b9c1 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -38,9 +38,9 @@ Requirements for v1.2 Tag Editing milestone. Each maps to roadmap phases. ### Batch Edit - [x] **BATCH-01**: User can select multiple tracks and open batch editor -- [ ] **BATCH-02**: Batch editor uses three-state field model (keep original / set value / clear field) +- [x] **BATCH-02**: Batch editor uses three-state field model (keep original / set value / clear field) - [x] **BATCH-03**: Batch editor shows progress indicator for large selections -- [ ] **BATCH-04**: User can set cover art for all selected tracks at once +- [x] **BATCH-04**: User can set cover art for all selected tracks at once ## Future Requirements @@ -108,9 +108,9 @@ Which phases cover which requirements. Updated during roadmap creation. | EDIT-03 | Phase 17 | Complete | | EDIT-04 | Phase 17 | Complete | | BATCH-01 | Phase 18 | Complete | -| BATCH-02 | Phase 18 | Pending | +| BATCH-02 | Phase 18 | Complete | | BATCH-03 | Phase 18 | Complete | -| BATCH-04 | Phase 18 | Pending | +| BATCH-04 | Phase 18 | Complete | **Coverage:** - v1.2 requirements: 20 total diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 40e6194..376ca33 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -43,7 +43,7 @@ - [x] **Phase 15: Schema Migration & Write Safety** — FTS5 contentless_delete migration and atomic file write utility (completed 2026-03-16) - [x] **Phase 16: Tag Writing & Database Sync** — Format-specific tag writers (MP3, FLAC, cover art) with inline DB + FTS5 update pipeline (3 plans) (completed 2026-03-17) - [x] **Phase 17: Single Track Edit** — End-to-end single track editing: UI → file write → DB sync → view refresh (completed 2026-03-18) -- [ ] **Phase 18: Batch Edit** — Multi-select batch editing with three-state field model, progress, and batch cover art +- [x] **Phase 18: Batch Edit** — Multi-select batch editing with three-state field model, progress, and batch cover art (completed 2026-03-18) - [ ] **Phase 19: OGG Vorbis Tag Writing** — Custom OGG page rewriter for Vorbis Comment tag writing (stretch) ## Phase Details @@ -101,7 +101,7 @@ Plans: 2. Each field in the batch editor shows one of three states: "keep original" (mixed values, no change), "set to value" (apply this value to all selected tracks), or "clear field" (remove this value from all) — the user can see which fields differ across the selection and choose per-field what to do 3. For batch operations on 10+ tracks, a progress indicator shows how many tracks have been processed — the user is never left staring at a frozen UI wondering if the operation is working 4. User can set cover art for all selected tracks at once — the same image is embedded in every selected file -**Plans:** 1/2 plans executed +**Plans:** 2/2 plans complete Plans: - [ ] 18-01-PLAN.md — Backend batch write endpoint with progress events, cancellation, and partial failure - [ ] 18-02-PLAN.md — Frontend batch mode in track-details with three-state editing, confirmation, progress UI, and view wiring @@ -140,7 +140,7 @@ Plans: | 15. Schema Migration & Write Safety | 2/2 | Complete | 2026-03-16 | - | | 16. Tag Writing & Database Sync | 3/3 | Complete | 2026-03-17 | - | | 17. Single Track Edit | 2/2 | Complete | 2026-03-18 | - | -| 18. Batch Edit | 1/2 | In Progress| | - | +| 18. Batch Edit | 2/2 | Complete | 2026-03-18 | - | | 19. OGG Vorbis Tag Writing | v1.2 | 0/? | Not started | - | --- diff --git a/.planning/STATE.md b/.planning/STATE.md index 30a421d..31e82ab 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,12 +3,12 @@ gsd_state_version: 1.0 milestone: v1.2 milestone_name: Tag Editing status: in-progress -last_updated: "2026-03-18T17:02:40Z" +last_updated: "2026-03-18T18:30:00Z" progress: - total_phases: 3 - completed_phases: 3 - total_plans: 8 - completed_plans: 8 + total_phases: 4 + completed_phases: 4 + total_plans: 9 + completed_plans: 9 --- # YellowJacket — Project State @@ -22,10 +22,10 @@ See: .planning/PROJECT.md (updated 2026-03-16) ## Current Position -Phase: Phase 18 — Batch Edit (in progress) -Plan: 18-02 in progress (tasks 1-2 complete, task 3 checkpoint:human-verify pending) -Status: 18-02 batch edit UI — track-details batch mode and view context menus wired -Last activity: 2026-03-18 — 18-02 tasks 1-2 committed, awaiting human verification of batch edit flow +Phase: Phase 18 — Batch Edit (complete) +Plan: 18-02 complete (all tasks done, human verification approved) +Status: Phase 18 complete — all batch edit requirements fulfilled (BATCH-01 through BATCH-04) +Last activity: 2026-03-18 — 18-02 completed with batch edit UI verified and approved ### Phase Overview @@ -34,7 +34,7 @@ Last activity: 2026-03-18 — 18-02 tasks 1-2 committed, awaiting human verifica | 15. Schema Migration & Write Safety | Complete (2/2 plans) | | 16. Tag Writing & Database Sync | Complete (3/3 plans) | | 17. Single Track Edit | Complete (2/2 plans) | -| 18. Batch Edit | In progress (1/? plans) | +| 18. Batch Edit | Complete (2/2 plans) | | 19. OGG Vorbis Tag Writing | Not started | ### v1.2 Requirement Coverage @@ -65,6 +65,7 @@ Last activity: 2026-03-18 — 18-02 tasks 1-2 committed, awaiting human verifica | 17 | 01 | 11min | 2 | 11 | | 17 | 02 | 25min | 2 | 8 | | 18 | 01 | 6min | 2 | 6 | +| 18 | 02 | ~30min | 3 | 5 | ## Accumulated Context @@ -104,6 +105,8 @@ Decisions from v1.0 and v1.1 are archived in PROJECT.md Key Decisions table. Key | suppressEvents flag for batch event coalescing | Prevents N TrackMetadataChanged events during batch; single emission after completion | | Per-track pipeline lock (not batch-wide) | Avoids blocking scan for entire batch duration; each track acquires/releases independently | | BatchResult struct return (not error) | Partial success always communicated; Wails serializes as JSON for frontend | +| Three-state field model via implicit editValues dirty tracking | Untouched = keep, typed = set, cleared = clear — no explicit state enum needed | +| Confirmation overlay within dialog (not separate dialog) | Simpler DOM management, consistent visual context for batch save guard | ### v1.2 Roadmap Decisions @@ -144,9 +147,9 @@ Decisions from v1.0 and v1.1 are archived in PROJECT.md Key Decisions table. Key ### Last Session **Date:** 2026-03-18 -**What happened:** Phase 18 Plan 02 tasks 1-2 complete — batch edit mode added to track-details component (showBatch API, merged fields, confirmation dialog, progress bar, results view, batch cover art) and all 4 view context menus wired to call showBatch for multi-select. -**Where we stopped:** 18-02 task 3 checkpoint:human-verify pending — need to verify batch edit flow in running app -**Next action:** Run `wails dev`, test batch edit flow, then continue 18-02 task 3 verification +**What happened:** Phase 18 complete — Plan 02 batch edit UI verified and approved. All batch edit requirements (BATCH-01 through BATCH-04) fulfilled. Field labels added to all track-details states during verification. +**Where we stopped:** Phase 18 complete. Phase 19 (OGG Vorbis Tag Writing) not yet started. +**Next action:** Plan Phase 19 or complete v1.2 milestone if OGG is deferred --- *State initialized: 2026-02-27* @@ -160,4 +163,4 @@ Decisions from v1.0 and v1.1 are archived in PROJECT.md Key Decisions table. Key | 19 | fix phantom playlist tracks with multi-root path resolution | 2026-03-16 | 9144ded | [19-fix-phantom-playlist-tracks](./quick/19-fix-phantom-playlist-tracks/) | Last activity: 2026-03-16 - Completed quick task 19: fix phantom playlist tracks with multi-root path resolution -*Last updated: 2026-03-18 — Completed 18-01 (batch write backend, progress events, cancellation)* +*Last updated: 2026-03-18 — Phase 18 complete (batch edit: backend + frontend UI, all BATCH requirements fulfilled)* diff --git a/.planning/phases/18-batch-edit/18-02-SUMMARY.md b/.planning/phases/18-batch-edit/18-02-SUMMARY.md new file mode 100644 index 0000000..7c5ff3d --- /dev/null +++ b/.planning/phases/18-batch-edit/18-02-SUMMARY.md @@ -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*