docs(13-02): complete library filter UI plan

- SUMMARY.md with library filter implementation details - STATE.md updated: Phase 13 complete (2/2 plans) - ROADMAP.md updated with plan progress - REQUIREMENTS.md: PLAY-01, PLAY-02, PLAY-03 marked complete
2026-03-16 09:44:29 -04:00
parent 42b8cf9f52
commit 70e3814985
4 changed files with 172 additions and 21 deletions
@@ -0,0 +1,147 @@
+---
+phase: 13-library-views-phantom-tracks
+plan: 02
+subsystem: frontend, ui
+tags: [lit, wails, library-filter, dropdown, multi-library]
+
+# Dependency graph
+requires:
+  - phase: 13-library-views-phantom-tracks
+    provides: Library-filtered Go query methods and Wails bindings
+provides:
+  - Library filter dropdown component in top bar
+  - All browse views (tracks, albums, artists, genres) filter by selected library
+  - Detail views (artist-details, genre-details) respect library filter
+  - Search results respect library filter (via filtered data source)
+  - Playlists remain unfiltered (cross-library by design)
+affects: [frontend-navigation, queue-context]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - Conditional ByLibrary/unfiltered call pattern in library-store
+    - Library filter state as store singleton (null = All Libraries)
+    - Native select dropdown for compact filter UI
+
+key-files:
+  created:
+    - frontend/src/components/library-filter/library-filter.ts
+  modified:
+    - frontend/src/store/library-store.ts
+    - frontend/src/store/controllers/library-controller.ts
+    - frontend/index.html
+    - frontend/index.ts
+    - frontend/src/components/cover-grid/cover-grid.ts
+    - frontend/src/components/cover-grid/album-selection.ts
+    - frontend/src/components/artists-view/artists-view.ts
+    - frontend/src/components/genres-view/genres-view.ts
+    - frontend/src/components/genre-details/genre-details.ts
+    - frontend/wailsjs/go/library/Library.d.ts
+    - frontend/wailsjs/go/library/Library.js
+
+key-decisions:
+  - "Client-side search with library-filtered data source — no backend SearchTracksByLibrary needed since search is already client-side via rankTracks"
+  - "Null selectedLibraryId = All Libraries (no persistence, resets on restart)"
+  - "Native select element for dropdown — compact, accessible, no custom widget overhead"
+  - "getAlbumsByArtistNameCached returns null when library filter active — forces backend query for consistency"
+
+patterns-established:
+  - "ByLibrary conditional call pattern: check selectedLibraryId, call ByLibrary or unfiltered variant"
+
+requirements-completed: [VIEW-01, VIEW-02, VIEW-03, VIEW-04, PLAY-01, PLAY-02, PLAY-03]
+
+# Metrics
+duration: 9min
+completed: 2026-03-16
+---
+
+# Phase 13 Plan 02: Library Filter UI & View Wiring Summary
+
+**Library filter dropdown in top bar with conditional ByLibrary queries across all browse views, detail views, and search — playlists remain unfiltered**
+
+## Performance
+
+- **Duration:** 9 min
+- **Started:** 2026-03-16T13:32:45Z
+- **Completed:** 2026-03-16T13:41:49Z
+- **Tasks:** 1 (of 2 — Task 2 is human verification checkpoint)
+- **Files modified:** 12
+
+## Accomplishments
+- Created library-filter dropdown component that loads library list from backend and sets store filter
+- Modified library-store to conditionally call ByLibrary or unfiltered queries based on selectedLibraryId
+- Wired all browse views (tracks, albums, artists, genres) to automatically use filtered data
+- Wired detail views (genre-details direct Wails call, artist-details via store, cover-grid album dropdown) to respect filter
+- Updated album-selection helper for library-aware drag/context-menu file path resolution
+- Verified playlists use separate PlaylistStore — not affected by library filter
+- Verified search is client-side (rankTracks on loaded data) — inherits filter automatically
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add library filter state + dropdown + wire all views** - `42b8cf9` (feat)
+
+**Task 2:** checkpoint:human-verify (pending user verification)
+
+## Files Created/Modified
+- `frontend/src/components/library-filter/library-filter.ts` - NEW: Library filter dropdown component
+- `frontend/src/store/library-store.ts` - selectedLibraryId state, ByLibrary conditional calls, getLibraries()
+- `frontend/src/store/controllers/library-controller.ts` - Pass-through for selectedLibraryId, setSelectedLibrary, getLibraries
+- `frontend/index.html` - Added `<library-filter>` to top bar
+- `frontend/index.ts` - Import library-filter component
+- `frontend/src/components/cover-grid/cover-grid.ts` - GetAlbumTracksByLibrary in dropdown
+- `frontend/src/components/cover-grid/album-selection.ts` - Library-aware fetchAlbumTracks helper
+- `frontend/src/components/artists-view/artists-view.ts` - GetAlbumsByArtistByLibrary + GetAlbumTracksByLibrary
+- `frontend/src/components/genres-view/genres-view.ts` - GetTracksByGenreByLibrary for context menu
+- `frontend/src/components/genre-details/genre-details.ts` - GetTracksByGenreByLibrary for track loading
+- `frontend/wailsjs/go/library/Library.d.ts` - Regenerated with ByLibrary bindings
+- `frontend/wailsjs/go/library/Library.js` - Regenerated with ByLibrary bindings
+
+## Decisions Made
+- Search is entirely client-side (rankTracks filters already-loaded tracks), so no backend SearchTracksByLibrary call needed — the library filter naturally scopes search results via the filtered track list
+- Used native `<select>` element for dropdown rather than a custom Lit component — compact, accessible, matches search bar height
+- Library filter resets on app restart (no localStorage persistence) per CONTEXT.md requirement
+- `getAlbumsByArtistNameCached` returns null when library filter active to avoid stale cross-library data
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Wails bindings not yet generated for ByLibrary methods**
+- **Found during:** Task 1 (start)
+- **Issue:** Plan 13-01 added Go methods but bindings weren't regenerated
+- **Fix:** Ran `wails generate module` before implementation
+- **Files modified:** frontend/wailsjs/go/library/Library.d.ts, Library.js
+- **Verification:** All ByLibrary imports resolve correctly
+- **Committed in:** 42b8cf9
+
+**2. [Rule 1 - Bug] Info type uses lowercase property names (id, name) not uppercase**
+- **Found during:** Task 1 (TypeScript typecheck)
+- **Issue:** library-filter.ts used `lib.ID` and `lib.Name` but Wails-generated Info type uses `lib.id` and `lib.name`
+- **Fix:** Changed to lowercase property access
+- **Files modified:** frontend/src/components/library-filter/library-filter.ts
+- **Verification:** `tsc --noEmit` passes cleanly
+- **Committed in:** 42b8cf9
+
+---
+
+**Total deviations:** 2 auto-fixed (1 blocking, 1 bug)
+**Impact on plan:** Both fixes required for compilation. No scope creep.
+
+## Issues Encountered
+None
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- All automated implementation complete — awaiting human verification checkpoint (Task 2)
+- After verification: Phase 13 complete, multi-library support fully delivered
+- v1.1 milestone only needs final Phase 13 checkpoint approval
+
+---
+*Phase: 13-library-views-phantom-tracks*
+*Completed: 2026-03-16*