wagesj45/mp3-com-meta-browser
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

UX: enable search input; add detailed UX elements TODO roadmap to AGENTS.md

Browse source
This commit is contained in:
Jordan Wages 2025-09-16 21:48:04 -05:00
commit 2ee403ddfb
2 changed files with 91 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

89
AGENTS.md
View file

@ -197,3 +197,92 @@ SELECT year, COUNT(*) FROM tracks GROUP BY year ORDER BY year;
- When editing `index.html`/`script.js`, include inline comments explaining assumptions.
- Verify changes against the schema above.
---
## TODOs / UX Elements Roadmap
Overview
- Views are "base" (replace main content) or "overlay" (stacked dialog) via `UX.replace(...)` and `UX.openOverlay(...)` in `script.js`.
- Each view pairs an HTML template in `index.html` (e.g., `tpl-...`) with a creator in `script.js` (e.g., `create...View(db)`), returning `{ kind, el, onShow?, destroy? }`.
- Use Bulma form/table/pagination patterns. Keep DOM small; paginate and debounce queries.
Shared Tasks
- [ ] Add small table/list renderer util in `script.js` to build rows safely (uses `escapeHtml`).
- [ ] Add shared pagination component (Prev/Next, page size select). Propagate `LIMIT/OFFSET`.
- [ ] Add common keyboard handlers: Enter to open selection; Esc to close overlays (already wired globally).
- [ ] Add loading/empty-state helpers for lists.
Primary Navigation (Hub)
- [ ] `tpl-nav` (base): Landing hub to choose "Search", "Browse Artists", "Browse Albums", "Browse Years", "Browse Genres", "Stats".
- [ ] `createNavView(db)`: Buttons/cards trigger `UX.replace(...)` to corresponding base views.
- [ ] Accessibility: initial focus on first action; arrow-key navigation across items; visible focus states.
Search (Existing)
- [x] `tpl-search` (base): Input is focusable; shows results area.
- [ ] Implement query execution with FTS join; debounce 250 ms; paginate results.
- SQL: `SELECT t.id, a.name AS artist, t.title, IFNULL(al.title,'') AS album, t.year, t.genre FROM fts_tracks f JOIN tracks t ON t.id=f.rowid JOIN artists a ON a.id=t.artist_id LEFT JOIN albums al ON al.id=t.album_id WHERE f MATCH ? ORDER BY rank LIMIT ? OFFSET ?`.
- [ ] Column sorts (toggle rank vs artist,title,year).
- [ ] Row activation opens Track overlay.
Browse Artists
- [ ] `tpl-browse-artists` (base): Alphabetical list, A–Z quick jump, mini filter box; paginated.
- [ ] `createBrowseArtistsView(db)`: Loads pages; clicking row opens Artist overlay.
- SQL: `SELECT id, name FROM artists ORDER BY name LIMIT ? OFFSET ?`.
- [ ] Optional prefix search using FTS prefix (`WHERE f MATCH 'artist:abc*'`) to accelerate filter.
Browse Albums
- [ ] `tpl-browse-albums` (base): List or grid with title, artist badge, year; paginated and sortable by artist/year/title.
- [ ] `createBrowseAlbumsView(db)`: Clicking item opens Album overlay.
- SQL: `SELECT al.id, al.title, al.year, a.name AS artist FROM albums al JOIN artists a ON a.id=al.artist_id ORDER BY a.name, al.year, al.title LIMIT ? OFFSET ?`.
Browse Years
- [ ] `tpl-browse-years` (base): Year histogram (counts) with list of tracks/albums when a year is selected; paginated.
- [ ] `createBrowseYearsView(db)`: Selecting a year shows tracks; rows open Album/Track overlays.
- SQL (counts): `SELECT year, COUNT(*) AS cnt FROM tracks WHERE year IS NOT NULL GROUP BY year ORDER BY year`.
- SQL (tracks by year): `SELECT t.id, t.title, a.name AS artist, IFNULL(al.title,'') AS album, t.genre FROM tracks t JOIN artists a ON a.id=t.artist_id LEFT JOIN albums al ON al.id=t.album_id WHERE t.year=? ORDER BY a.name, t.title LIMIT ? OFFSET ?`.
Browse Genres
- [ ] `tpl-browse-genres` (base): Genre chips with counts → selecting shows paginated tracks.
- [ ] `createBrowseGenresView(db)`: Genre list with counts; selecting lists tracks; rows open Track overlay.
- SQL (counts): `SELECT genre, COUNT(*) AS cnt FROM tracks WHERE genre IS NOT NULL AND genre!='' GROUP BY genre ORDER BY cnt DESC, genre`.
- SQL (tracks by genre): `SELECT t.id, t.title, a.name AS artist, IFNULL(al.title,'') AS album, t.year FROM tracks t JOIN artists a ON a.id=t.artist_id LEFT JOIN albums al ON al.id=t.album_id WHERE t.genre=? ORDER BY a.name, t.title LIMIT ? OFFSET ?`.
Stats
- [ ] `tpl-stats` (base): Lightweight metrics (totals, top artists, year distribution) linking into browse views.
- [ ] `createStatsView(db)`: Render summary cards; links navigate via `UX.replace(...)` with preselected filters.
- SQL (examples): totals from `COUNT(*)` on artists/albums/tracks; top artists via `SELECT a.name, COUNT(*) cnt FROM tracks t JOIN artists a ON a.id=t.artist_id GROUP BY a.id ORDER BY cnt DESC LIMIT 20`.
Artist Overlay
- [ ] `tpl-artist` (overlay): Header: name + counts; tabs: Albums | Top Tracks.
- [ ] `createArtistOverlay(db, artistId)`: Load artist name, counts, then tab content.
- SQL (albums): `SELECT id, title, year FROM albums WHERE artist_id=? ORDER BY year, title`.
- SQL (top tracks): `SELECT id, title, year, genre FROM tracks WHERE artist_id=? ORDER BY year, title LIMIT 100`.
- [ ] Actions: clicking album opens Album overlay; clicking track opens Track overlay.
Album Overlay
- [ ] `tpl-album` (overlay): Header with album title, artist, year; tracklist table with `track_no`, `title`, `duration_sec`, `bitrate_kbps`.
- [ ] `createAlbumOverlay(db, albumId)`: Load album+artist header; then tracklist.
- SQL (header): `SELECT al.title, al.year, a.name AS artist FROM albums al JOIN artists a ON a.id=al.artist_id WHERE al.id=?`.
- SQL (tracks): `SELECT id, track_no, title, duration_sec, bitrate_kbps FROM tracks WHERE album_id=? ORDER BY track_no, title`.
- [ ] Row activation opens Track overlay.
Track Overlay
- [ ] `tpl-track` (overlay): Show title, artist, album, year, genre, duration, bitrate, samplerate, channels, filesize, sha1 (if present), and `relpath` with a Copy button.
- [ ] `createTrackOverlay(db, trackId)`: Load detail from join; add Copy action for `relpath`.
- SQL: `SELECT t.*, a.name AS artist, al.title AS album FROM tracks t JOIN artists a ON a.id=t.artist_id LEFT JOIN albums al ON al.id=t.album_id WHERE t.id=?`.
Filters (Optional)
- [ ] `tpl-filters` (overlay): Advanced filters (year range, min bitrate, genre multi-select) applied to current base view.
- [ ] `createFiltersOverlay(db, onApply)`: Applies constraints and refreshes the invoking view.
Help/Meta Overlays
- [ ] `tpl-keyboard-shortcuts` (overlay): " / focus search", "Esc close overlay", "j/k navigate" if list navigation is added.
- [ ] `tpl-about` (overlay): About/help, privacy note.
- [ ] `tpl-error` (overlay): Friendly error with retry; used by views on failure.
Implementation Notes
- Use template IDs in `index.html` and instantiate via existing `instantiateTemplate` helper.
- Overlays must add `ux-view--overlay` class (done by UX manager) and include a close button that calls `UX.closeTop()`.
- Keep queries read-only; always `LIMIT ? OFFSET ?` for lists; avoid `SELECT *` except for single-row detail.
- Respect accessibility: label–input associations, `aria-live` only for async status, focus returned to opener on overlay close.
- Performance: debounce search 200–300 ms; cache prepared statements if beneficial; do not pre-render large lists.

3
index.html
View file

@ -44,7 +44,8 @@
<div class="field">
<label class="label" for="q">Search</label>
<div class="control">
<input id="q" name="q" class="input" type="search" placeholder="Search artist, title, album, genre…" disabled aria-disabled="true" data-ref="q" />
<!-- Input should be interactive when the search view shows; JS manages focus/state. -->
<input id="q" name="q" class="input" type="search" placeholder="Search artist, title, album, genre…" data-ref="q" />
</div>
<p class="help">Powered by in-browser SQLite FTS; no network queries.</p>
</div>