' +
'
' +
') + ')
' +
tuning + checkbox + accuracyBadge(key) + fmtBadge(song) + overlay +
@@ -724,6 +750,169 @@
}, { passive: true });
}
+ // ── A–Z jump rail interaction ─────────────────────────────────────────────
+ // The rail jumps within the contiguous, server-paged grid. Because the grid
+ // is forward-only infinite scroll (no virtualization), reaching a letter that
+ // isn't loaded yet means paging forward until its first card exists, then
+ // scrolling to it — the same rows the user would have scrolled past. The rail
+ // only offers letters the server reports as present for the active sort+filter
+ // (so a tap always terminates at a real card). A keyset-seek + virtualized
+ // window is the scaling follow-up for very large libraries.
+ function railEl() { return document.getElementById('v3-songs-azrail'); }
+ function railBubbleEl() { return document.getElementById('v3-songs-azbubble'); }
+ function railVisible() { return state.view === 'grid' && !!railSortColumn(); }
+
+ let _railToken = 0;
+ async function refreshRail() {
+ const rail = railEl();
+ if (!rail) return;
+ if (!railVisible()) { rail.classList.add('hidden'); railBubbleEl()?.classList.add('hidden'); return; }
+ const col = railSortColumn();
+ // A newer refresh (sort/filter/search/provider change) supersedes this
+ // one — a slow stats response must not repaint a rail the grid moved on.
+ const myToken = ++_railToken;
+ // Present letters for the active sort+filter (filter-synced; counts
+ // songs). `sort_letters=1` opts into the active-sort breakdown so the
+ // dashboard / v2 tree (which read only `letters`) skip the extra query.
+ const stats = await jget('/api/library/stats?' + queryParams({ sort_letters: 1 }).toString());
+ if (_railToken !== myToken || !railVisible()) { // changed mid-fetch
+ if (_railToken === myToken) rail.classList.add('hidden');
+ return;
+ }
+ // Prefer the active-sort breakdown. `letters` is the artist distinct-
+ // count, so it only matches the cards on an artist sort; a legacy/third-
+ // party provider that predates `sort_letters` returns none, in which
+ // case a title sort would advertise wrong letters — hide the rail then.
+ let letters = stats && stats.sort_letters;
+ if (!letters) {
+ if (col === 'artist') letters = (stats && stats.letters) || {};
+ else { rail.classList.add('hidden'); railBubbleEl()?.classList.add('hidden'); return; }
+ }
+ state.railLetters = letters;
+ // No present letters (empty or fully-filtered grid) → nothing to jump
+ // to; hide the rail instead of rendering a column of disabled buttons.
+ if (!Object.keys(letters).length) { rail.classList.add('hidden'); railBubbleEl()?.classList.add('hidden'); return; }
+ const desc = state.sort.endsWith('-desc');
+ const order = desc ? RAIL_BUCKETS.slice().reverse() : RAIL_BUCKETS;
+ // Roving tabindex: only the first present letter is in the tab order;
+ // the rest are reached with the arrow keys (see bindRailOnce). Avoids
+ // dumping up to 27 tab stops into the page.
+ let firstPresent = true;
+ rail.innerHTML = order.map((L) => {
+ const n = letters[L] || 0;
+ const present = n > 0;
+ const tabbable = present && firstPresent;
+ if (tabbable) firstPresent = false;
+ const name = L === '#' ? 'non-alphabetical' : L;
+ return '';
+ }).join('');
+ rail.classList.remove('hidden');
+ bindRailOnce();
+ }
+
+ function _setRailActive(letter) {
+ railEl()?.querySelectorAll('.v3-azrail-letter').forEach((b) => {
+ b.classList.toggle('is-active', b.getAttribute('data-letter') === letter);
+ });
+ }
+ function _showBubble(letter) { const b = railBubbleEl(); if (b) { b.textContent = letter; b.classList.remove('hidden'); } }
+ function _hideBubble() { railBubbleEl()?.classList.add('hidden'); }
+
+ async function _loadNextAwait() {
+ if (state.loading) { await _waitForGridIdle(); return loadedCount() < state.total; }
+ if (loadedCount() >= state.total) return false;
+ state.page++;
+ await loadGrid(false);
+ return loadedCount() < state.total;
+ }
+
+ let _jumpToken = 0;
+ async function jumpToLetter(letter) {
+ const grid = document.getElementById('v3-songs-grid');
+ if (!grid || state.view !== 'grid' || !letter) return;
+ _setRailActive(letter);
+ const sel = '[data-letter="' + ((window.CSS && CSS.escape) ? CSS.escape(letter) : letter) + '"]';
+ const myToken = ++_jumpToken; // a newer jump supersedes this one
+ // Page forward until the bucket's first card is loaded (or list
+ // exhausted). The guard is the page count the current total implies
+ // (+2 slack) rather than a fixed cap, so even a very large library
+ // stays reachable while a runaway loop is still bounded.
+ let guard = 0;
+ const maxPages = Math.ceil((state.total || 0) / PAGE_SIZE) + 2;
+ while (!grid.querySelector(sel) && loadedCount() < state.total
+ && _jumpToken === myToken && guard++ < maxPages) {
+ const more = await _loadNextAwait();
+ if (!more) break;
+ }
+ if (_jumpToken !== myToken) return;
+ const target = grid.querySelector(sel);
+ if (!target) return;
+ const main = document.getElementById('v3-main');
+ const toolbar = document.getElementById('v3-songs-toolbar');
+ const pad = (toolbar ? toolbar.offsetHeight : 0) + 12; // clear the sticky toolbar
+ if (main) {
+ const top = target.getBoundingClientRect().top - main.getBoundingClientRect().top + main.scrollTop - pad;
+ main.scrollTo({ top: Math.max(0, top), behavior: 'smooth' });
+ } else {
+ target.scrollIntoView({ block: 'start', behavior: 'smooth' });
+ }
+ }
+
+ function bindRailOnce() {
+ const rail = railEl();
+ if (!rail || rail._bound) return;
+ rail._bound = true;
+ let dragging = false, moved = false, lastDrag = null;
+ const letterAtY = (y) => {
+ const els = rail.querySelectorAll('.v3-azrail-letter');
+ if (!els.length) return null;
+ for (const el of els) { const r = el.getBoundingClientRect(); if (y >= r.top && y <= r.bottom) return el; }
+ return y < els[0].getBoundingClientRect().top ? els[0] : els[els.length - 1]; // clamp past ends
+ };
+ rail.addEventListener('click', (e) => {
+ const btn = e.target.closest('.v3-azrail-letter');
+ if (!btn || btn.disabled) return;
+ if (moved) { moved = false; return; } // a drag already handled it
+ jumpToLetter(btn.getAttribute('data-letter'));
+ });
+ rail.addEventListener('pointerdown', (e) => {
+ const btn = e.target.closest('.v3-azrail-letter');
+ if (!btn) return;
+ dragging = true; moved = false; lastDrag = null;
+ try { rail.setPointerCapture(e.pointerId); } catch (_) { /* */ }
+ _showBubble(btn.getAttribute('data-letter'));
+ });
+ rail.addEventListener('pointermove', (e) => {
+ if (!dragging) return;
+ const el = letterAtY(e.clientY);
+ if (!el || el.disabled) return;
+ moved = true;
+ const L = el.getAttribute('data-letter');
+ _showBubble(L);
+ if (L !== lastDrag) { lastDrag = L; jumpToLetter(L); } // only on change
+ });
+ const end = () => { dragging = false; _hideBubble(); };
+ rail.addEventListener('pointerup', end);
+ rail.addEventListener('pointercancel', end);
+ rail.addEventListener('keydown', (e) => {
+ if (e.key !== 'ArrowUp' && e.key !== 'ArrowDown') return;
+ const btns = [...rail.querySelectorAll('.v3-azrail-letter:not([disabled])')];
+ const i = btns.indexOf(document.activeElement);
+ if (i < 0) return;
+ e.preventDefault();
+ const next = btns[i + (e.key === 'ArrowDown' ? 1 : -1)];
+ if (next) {
+ btns[i].setAttribute('tabindex', '-1'); // roving tabindex follows focus
+ next.setAttribute('tabindex', '0');
+ next.focus();
+ jumpToLetter(next.getAttribute('data-letter'));
+ }
+ });
+ }
+
// Pin the sticky toolbar directly beneath the sticky topbar. Both live in
// the #v3-main scroller, so without an explicit offset they share top:0 and
// the toolbar covers the topbar's song search. The topbar has two responsive
@@ -913,12 +1102,19 @@
// state.q) and needs a refresh rather than a scroll-preserving no-op.
state.renderedHash = _libraryStateHash();
updateFilterBadge();
+ // A sort/filter/search/view change rebuilds the grid from page 0, so any
+ // in-flight letter jump is now paging through a dataset that's about to
+ // be discarded — supersede it so it can't scroll the rebuilt grid.
+ _jumpToken++;
// Keep a handle on the load so callers (notably the scroll restore on
// screen re-entry) can await page-0 actually landing before paging
// deeper. The visibility/scroll resets below stay synchronous.
document.getElementById('v3-songs-grid')?.classList.toggle('hidden', state.view !== 'grid');
document.getElementById('v3-songs-tree')?.classList.toggle('hidden', state.view !== 'tree');
document.getElementById('lib-folder-tree')?.classList.toggle('hidden', state.view !== 'folder');
+ // Refresh the A–Z jump rail (shows only for the grid + alphabetical
+ // sorts; hides itself otherwise). Independent of the grid load.
+ refreshRail();
{ const _fc = document.getElementById('lib-folder-controls'); if (_fc) _fc.style.display = state.view === 'folder' ? 'flex' : 'none'; }
if (state.view === 'folder') {
_applyMainScrollTop(0);
@@ -985,6 +1181,10 @@
'' +
'' +
'' +
+ // A–Z jump rail (grid + alphabetical sorts only; populated by
+ // refreshRail). The bubble shows the current letter while dragging.
+ '' +
+ '' +
// Filter drawer + overlay
'' +
'' +
diff --git a/static/v3/v3.css b/static/v3/v3.css
index 996c072..7c1a70a 100644
--- a/static/v3/v3.css
+++ b/static/v3/v3.css
@@ -1117,3 +1117,75 @@ html.fb-immersive #v3-main > .screen.active {
inset: 0;
overflow: hidden;
}
+
+/* — A–Z jump rail (v3 Songs grid; static/v3/songs.js) — */
+/* Fixed to the right edge next to the scroller's scrollbar; vertically
+ centered. Shown only for the grid view + alphabetical (artist/title) sorts. */
+.v3-azrail {
+ position: fixed;
+ right: 2px;
+ top: 50%;
+ transform: translateY(-50%);
+ z-index: 25;
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ max-height: 84vh;
+ padding: 4px 1px;
+ user-select: none;
+ -webkit-user-select: none;
+ touch-action: none; /* let a drag scrub the rail without scrolling the page */
+}
+.v3-azrail-letter {
+ appearance: none;
+ -webkit-appearance: none;
+ background: none;
+ border: 0;
+ color: #94a3b8; /* fb-textDim */
+ font-size: .62rem;
+ font-weight: 700;
+ line-height: 1.05;
+ padding: 1px 4px;
+ margin: 0;
+ cursor: pointer;
+ border-radius: 4px;
+}
+.v3-azrail-letter:hover:not([disabled]),
+.v3-azrail-letter.is-active {
+ color: #0ea5e9; /* fb-primary */
+}
+.v3-azrail-letter:focus-visible {
+ outline: 2px solid #38bdf8; /* fb-primaryHi */
+ outline-offset: 1px;
+}
+.v3-azrail-letter[disabled] {
+ color: rgba(148, 163, 184, .28);
+ cursor: default;
+}
+/* Drag indicator bubble (Android fast-scroll pattern). */
+.v3-azbubble {
+ position: fixed;
+ right: 2.6rem;
+ top: 50%;
+ transform: translateY(-50%);
+ z-index: 26;
+ width: 2.6rem;
+ height: 2.6rem;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ border-radius: .7rem;
+ background: #0ea5e9; /* fb-primary */
+ color: #f8fafc; /* fb-text */
+ font-size: 1.15rem;
+ font-weight: 800;
+ box-shadow: 0 6px 22px rgba(0, 0, 0, .45);
+ pointer-events: none;
+}
+.v3-azrail.hidden,
+.v3-azbubble.hidden { display: none; }
+/* Coarse-pointer / short viewports: the 27-letter rail can crowd a phone edge.
+ Tighten it; a collapse-to-anchors pass is a follow-up. */
+@media (max-height: 640px) {
+ .v3-azrail-letter { font-size: .55rem; padding: 0 4px; }
+}
diff --git a/tests/js/v3_az_rail.test.js b/tests/js/v3_az_rail.test.js
new file mode 100644
index 0000000..047e725
--- /dev/null
+++ b/tests/js/v3_az_rail.test.js
@@ -0,0 +1,85 @@
+// Pins the v3 Songs A–Z jump rail wiring in static/v3/songs.js.
+//
+// The rail lets a user jump the library grid to artists/titles starting with a
+// letter (Plex/Radarr/iOS-contacts pattern). Because the grid is forward-only,
+// server-paged infinite scroll, the jump pages through to the target card then
+// scrolls — and the rail only offers letters the server reports present for the
+// active sort+filter (so a tap always terminates at a real card). It is shown
+// only for the grid view + alphabetical (artist/title) sorts.
+//
+// Source-level only — same strategy as tests/js/highway_3d_camera_framing.test.js.
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SONGS_JS = path.join(__dirname, '..', '..', 'static', 'v3', 'songs.js');
+const src = fs.readFileSync(SONGS_JS, 'utf8');
+
+test('the rail is context-gated to grid view + alphabetical sorts', () => {
+ // railSortColumn returns the active alpha column or null (recent/year/tuning).
+ assert.match(src, /function\s+railSortColumn\s*\(\)/);
+ assert.match(src, /state\.sort === 'artist'[\s\S]*?return 'artist'/);
+ assert.match(src, /state\.sort === 'title'[\s\S]*?return 'title'/);
+ assert.match(
+ src,
+ /function\s+railVisible\s*\(\)\s*\{\s*return\s+state\.view === 'grid'\s*&&\s*!!railSortColumn\(\)/,
+ 'the rail must be visible only for the grid view + an alphabetical sort',
+ );
+});
+
+test('cards carry a data-letter bucket and non-A–Z buckets under #', () => {
+ assert.match(src, /data-letter="'\s*\+\s*esc\(songBucket\(song\)\)/,
+ 'each card must tag its sort-letter bucket via songBucket(song)');
+ assert.match(
+ src,
+ /function\s+songBucket[\s\S]*?\(ch >= 'A' && ch <= 'Z'\)\s*\?\s*ch\s*:\s*'#'/,
+ 'songBucket must bucket non-A–Z first chars under "#"',
+ );
+});
+
+test('refreshRail reads present letters from the stats endpoint (sort-aware)', () => {
+ assert.match(src, /\/api\/library\/stats\?'\s*\+\s*queryParams/,
+ 'refreshRail must query /api/library/stats with the active filter params');
+ // Opts into the active-sort breakdown so non-rail callers skip the scan.
+ assert.match(src, /queryParams\(\{\s*sort_letters:\s*1\s*\}\)/,
+ 'refreshRail must request the sort_letters breakdown');
+ assert.match(src, /letters\s*=\s*stats\s*&&\s*stats\.sort_letters/,
+ 'refreshRail must prefer the active-sort breakdown (sort_letters)');
+ // The legacy artist `letters` is only a valid fallback for an artist sort;
+ // a title sort with no sort_letters hides the rail rather than mislabel it.
+ assert.match(src, /col === 'artist'[\s\S]*?stats\.letters/,
+ 'refreshRail must only fall back to letters for an artist sort');
+ // Absent letters are disabled (non-interactive), not just dimmed.
+ assert.match(src, /present\s*\?\s*''\s*:\s*' disabled'/);
+});
+
+test('reload() refreshes the rail', () => {
+ assert.match(src, /function reload\s*\([\s\S]*?refreshRail\(\)/,
+ 'reload() must call refreshRail() so the rail tracks filter/sort/view changes');
+});
+
+test('the rail + drag bubble are rendered in the Songs markup', () => {
+ assert.match(src, /id="v3-songs-azrail"[\s\S]*?aria-label="Jump to letter"/);
+ assert.match(src, /id="v3-songs-azbubble"/);
+});
+
+test('jumpToLetter pages through to the target then scrolls (load-through)', () => {
+ // Forward-paging helper used to load rows up to the target letter.
+ assert.match(src, /async function\s+_loadNextAwait\s*\(\)/);
+ assert.match(
+ src,
+ /async function\s+jumpToLetter[\s\S]*?_loadNextAwait\(\)[\s\S]*?(scrollTo|scrollIntoView)/,
+ 'jumpToLetter must page forward (_loadNextAwait) then scroll to the target card',
+ );
+ // A token guards against overlapping jumps (drag scrubbing) — newest wins.
+ assert.match(src, /_jumpToken\s*===\s*myToken/);
+});
+
+test('the rail supports pointer drag-scrub + keyboard arrows', () => {
+ assert.match(src, /addEventListener\('pointerdown'/);
+ assert.match(src, /addEventListener\('pointermove'/);
+ assert.match(src, /ArrowUp'[\s\S]*?ArrowDown'|ArrowDown'[\s\S]*?ArrowUp'/,
+ 'arrow keys must move between present letters');
+});
diff --git a/tests/test_library_filters.py b/tests/test_library_filters.py
index 1f09795..3205243 100644
--- a/tests/test_library_filters.py
+++ b/tests/test_library_filters.py
@@ -398,6 +398,39 @@ def test_query_stats_groups_non_ascii_artist_letters_under_hash(client, server_m
assert stats["letters"] == {"#": 1}
+def test_query_stats_sort_letters_artist_counts_songs(client, server_mod):
+ """The v3 jump rail's `sort_letters` counts SONGS per first-letter bucket
+ of the active sort column (vs `letters`, which counts distinct artists).
+ Two songs by the same A-artist → letters {A:1}, sort_letters {A:2}."""
+ _put(server_mod, filename="a1.archive", title="Song One", artist="Abba")
+ _put(server_mod, filename="a2.archive", title="Song Two", artist="Abba")
+ _put(server_mod, filename="b1.archive", title="Another", artist="Beck")
+ _put(server_mod, filename="num.archive", title="Track", artist="2Pac")
+
+ # sort_letters=1 opts into the active-sort breakdown (the jump rail path).
+ stats = client.get("/api/library/stats", params={"sort": "artist", "sort_letters": 1}).json()
+ assert stats["letters"] == {"A": 1, "B": 1, "#": 1} # distinct artists
+ assert stats["sort_letters"] == {"A": 2, "B": 1, "#": 1} # songs
+
+ # Without the opt-in, the extra breakdown is not computed or returned.
+ plain = client.get("/api/library/stats", params={"sort": "artist"}).json()
+ assert "sort_letters" not in plain
+ assert plain["letters"] == {"A": 1, "B": 1, "#": 1}
+
+
+def test_query_stats_sort_letters_follow_title_sort(client, server_mod):
+ """With a title sort, the rail buckets key on the TITLE's first letter,
+ not the artist's, so a tap lands on a real card in the grid's order."""
+ _put(server_mod, filename="z1.archive", title="Apple", artist="Zztop")
+ _put(server_mod, filename="z2.archive", title="Banana", artist="Zztop")
+
+ stats = client.get("/api/library/stats", params={"sort": "title", "sort_letters": 1}).json()
+ assert stats["sort_letters"] == {"A": 1, "B": 1}
+ # The legacy artist breakdown is unchanged regardless of sort — both songs
+ # share one artist, so it stays a single distinct-artist Z bucket.
+ assert stats["letters"] == {"Z": 1}
+
+
def test_query_stats_ignores_null_letter_counts(server_mod):
"""Legacy/corrupt rows can surface as NULL-ish letter aggregate
rows on some SQLite builds. The stats endpoint should ignore those
@@ -429,9 +462,13 @@ def test_query_stats_ignores_null_letter_counts(server_mod):
server_mod.meta_db.conn.close()
server_mod.meta_db.conn = FakeConn()
- stats = server_mod.meta_db.query_stats()
+ stats = server_mod.meta_db.query_stats(want_sort_letters=True)
- assert stats == {"total_songs": 1, "total_artists": 1, "letters": {"T": 1}}
+ # `sort_letters` (the v3 jump-rail breakdown) shares the GROUP BY letter
+ # path in this fake, so it surfaces the same single live bucket when the
+ # caller opts in.
+ assert stats == {"total_songs": 1, "total_artists": 1,
+ "letters": {"T": 1}, "sort_letters": {"T": 1}}
def test_compound_sort_with_legacy_dir_desc_doesnt_error(client, seeded):
diff --git a/tests/test_library_providers.py b/tests/test_library_providers.py
index 8a06874..b6e7b6f 100644
--- a/tests/test_library_providers.py
+++ b/tests/test_library_providers.py
@@ -213,7 +213,9 @@ def test_registered_provider_handles_library_endpoints(server_mod, client):
assert stats["letters"] == {"R": 1}
assert "page" not in provider.stats_kwargs
assert "size" not in provider.stats_kwargs
- assert "sort" not in provider.stats_kwargs
+ # `sort` is forwarded to query_stats now (the v3 jump rail keys its
+ # present-letter breakdown on the active sort column); defaults to "artist".
+ assert provider.stats_kwargs.get("sort") == "artist"
tunings = client.get("/api/library/tuning-names", params={"provider": "remote:frodo"}).json()
assert tunings["tunings"][0]["name"] == "E Standard"