yonlu/yellowjacket
1
1
Fork 0
Code Issues 55 Pull Requests 6 Actions Packages Projects Releases 12 Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
yonlu
2026-03-18 13:53:53 -04:00
parent d430ad884b
commit 77dec0bceb
4 changed files with 163 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/REQUIREMENTS.md
+4 -4
View File
@@ -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
.planning/ROADMAP.md
+3 -3
View File
@@ -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 | - |
---
.planning/STATE.md
+17 -14
View File
@@ -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)*
.planning/phases/18-batch-edit/18-02-SUMMARY.md
+139
View File
@@ -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*