[Hallmark] Rework the flat book list into readable adaptive rows #50

Open
opened 2026-09-18 13:55:47 +02:00 by alexander · 0 comments
Owner

Problem and outcome

The flat Books list currently uses large glass cards with 132 dp fixed row heights, full-height cover art, several metadata lines and repeated progress information. The fixed height competes with scalable text, while seven sort chips sit alongside a separate filter row.

Make the flat list easier to scan: bounded cover thumbnails, naturally sized rows, clear title/metadata hierarchy and distinct controls for filtering and sorting. Child of #48. Primary owner: UI & Experience. Source-based proposal requiring rendered validation, not proof that all sizes currently fail.

Proposed row design

  • Use a small, consistent square cover thumbnail, initially prototype roughly 64–72 dp at standard phone width. Treat this as a starting range, not a release requirement.
  • Make the text column flexible and the total row height content-driven with a minimum. Do not tie the thumbnail size to the expanded text height.
  • Lead with the title using existing Material typography. Allow at least two readable lines where needed; make full text available in details and accessibility. Avoid perpetual marquee text in a scanning list.
  • Show author as secondary text, then series/sequence when relevant. Missing author/series must not reserve multiple empty lines merely for equal card heights.
  • Prefer one concise progress statement: remaining time for in-progress books, duration for unstarted books, Finished for completed books. Keep any progress bar quiet. Do not repeat elapsed + remaining + total + percentage by default.
  • Use a shared list surface with modest spacing or subtle separators for the calmer default. Avoid an equally prominent rounded glass container around every row. Preserve existing user-selected appearance treatments through coherent semantic tokens and readable text grounds.
  • Keep whole-row tap opening details. Do not add autoplay, swipe-to-delete or a Play button to every general search/list row. Existing direct-play behavior in the series screen must remain available and distinct.
  • Indicate selected/pressed/focused states clearly and keep accessible text order meaningful. Decorative covers should not duplicate the title announcement.

Header hierarchy

  • Keep All / Continue / Downloaded as visible membership filters, with one clear selected state.
  • Replace the seven always-visible sort chips with a labelled control, e.g. “Sort: Last played”, opening a radio-choice menu or sheet.
  • Preserve every existing sort option and its direction. Reuse the current per-profile/library persistence.
  • Keep the active author/genre focus visible and easily cleared. Do not reset the chosen library when clearing search/filter scope.
  • Keep search available and make no-results recovery explicit. Ensure the header still leaves useful list area when keyboard, mini-player and large text are present.
  • Do not hide the only recovery control after a filter produces zero results.

Shared components and scope

Audit snapshot: main 8f0ff59266.

  • app/src/main/kotlin/com/example/shelfplayer/feature/browse/BookListUi.kt:53–195 (fixed rows/progress)
  • app/src/main/kotlin/com/example/shelfplayer/feature/browse/BookListUi.kt:202–230 (sort chips)
  • app/src/main/kotlin/com/example/shelfplayer/feature/browse/BookCover.kt:75–81 (full-height thumbnail)
  • app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeScreen.kt:1070–1080 and 1188–1193 (header/list wiring)

BookCard is shared: inspect all callers before changing its appearance. Use a narrowly scoped list variant or shared adaptive primitive as appropriate; preserve series-context membership, direct Play and any other caller's intended behavior. This issue does not redesign Home shelves (#49), profile picker, other Settings tabs, navigation or library policy.

Responsive and interaction states

  • Narrow screens: prioritize title and metadata; reduce thumbnail size before compressing text.
  • Large text: row expands vertically without clipping series or progress. No fixed total row height.
  • Wide screens: use a readable maximum list width with aligned rows, not oversized full-width cards.
  • Stable missing/loading/error artwork fallback; no row geometry jump on image completion.
  • Preserve loading, cached/offline, empty, filtered-empty and error distinctions. Do not replace valid cached rows with a full-screen failure.
  • Preserve scroll state on return from details and existing intended behavior when changing filters/sort.
  • Keep last row and all actions scrollable above floating playback controls.

Acceptance

  • Long title + author + series + long-duration progress remain readable at 320/375/414/768 dp and font scales 1.0/1.3/2.0.
  • Default-size list shows more useful book information per viewport than the current large-card presentation, without sacrificing target size or legibility. Evaluate with the same viewport/data, not an invented target count.
  • Every sort option remains available and persisted; active sort is visible without opening its menu.
  • Filters and collection scope are understandable and reversible, including zero results.
  • Row/details action and any existing series-specific play action remain independently accessible and correct.
  • Test offline/missing artwork, finished/unstarted/in-progress books, active playback and profile/library switching.
  • Validate light/dark/AMOLED/background packs, TalkBack, focus/pressed states, contrast and reduced motion.
  • Compare screenshots before/after using representative long metadata; add focused layout/interaction coverage and run applicable repository gates.
  • Run Hallmark's final review for hierarchy, restraint, consistency and interaction states. Re-read current main and follow docs/roadmap.md before implementing.
<!-- Hallmark · pre-emit critique: P5 H5 E4 S5 R5 V4 --> ## Problem and outcome The flat Books list currently uses large glass cards with 132 dp fixed row heights, full-height cover art, several metadata lines and repeated progress information. The fixed height competes with scalable text, while seven sort chips sit alongside a separate filter row. Make the flat list easier to scan: bounded cover thumbnails, naturally sized rows, clear title/metadata hierarchy and distinct controls for filtering and sorting. Child of #48. Primary owner: UI & Experience. Source-based proposal requiring rendered validation, not proof that all sizes currently fail. ## Proposed row design - Use a small, consistent square cover thumbnail, initially prototype roughly 64–72 dp at standard phone width. Treat this as a starting range, not a release requirement. - Make the text column flexible and the total row height content-driven with a minimum. Do not tie the thumbnail size to the expanded text height. - Lead with the title using existing Material typography. Allow at least two readable lines where needed; make full text available in details and accessibility. Avoid perpetual marquee text in a scanning list. - Show author as secondary text, then series/sequence when relevant. Missing author/series must not reserve multiple empty lines merely for equal card heights. - Prefer one concise progress statement: remaining time for in-progress books, duration for unstarted books, Finished for completed books. Keep any progress bar quiet. Do not repeat elapsed + remaining + total + percentage by default. - Use a shared list surface with modest spacing or subtle separators for the calmer default. Avoid an equally prominent rounded glass container around every row. Preserve existing user-selected appearance treatments through coherent semantic tokens and readable text grounds. - Keep whole-row tap opening details. Do not add autoplay, swipe-to-delete or a Play button to every general search/list row. Existing direct-play behavior in the series screen must remain available and distinct. - Indicate selected/pressed/focused states clearly and keep accessible text order meaningful. Decorative covers should not duplicate the title announcement. ## Header hierarchy - Keep All / Continue / Downloaded as visible membership filters, with one clear selected state. - Replace the seven always-visible sort chips with a labelled control, e.g. “Sort: Last played”, opening a radio-choice menu or sheet. - Preserve every existing sort option and its direction. Reuse the current per-profile/library persistence. - Keep the active author/genre focus visible and easily cleared. Do not reset the chosen library when clearing search/filter scope. - Keep search available and make no-results recovery explicit. Ensure the header still leaves useful list area when keyboard, mini-player and large text are present. - Do not hide the only recovery control after a filter produces zero results. ## Shared components and scope Audit snapshot: main 8f0ff5926687b3373703ee972dbb1392a0792d63. - app/src/main/kotlin/com/example/shelfplayer/feature/browse/BookListUi.kt:53–195 (fixed rows/progress) - app/src/main/kotlin/com/example/shelfplayer/feature/browse/BookListUi.kt:202–230 (sort chips) - app/src/main/kotlin/com/example/shelfplayer/feature/browse/BookCover.kt:75–81 (full-height thumbnail) - app/src/main/kotlin/com/example/shelfplayer/feature/home/HomeScreen.kt:1070–1080 and 1188–1193 (header/list wiring) BookCard is shared: inspect all callers before changing its appearance. Use a narrowly scoped list variant or shared adaptive primitive as appropriate; preserve series-context membership, direct Play and any other caller's intended behavior. This issue does not redesign Home shelves (#49), profile picker, other Settings tabs, navigation or library policy. ## Responsive and interaction states - Narrow screens: prioritize title and metadata; reduce thumbnail size before compressing text. - Large text: row expands vertically without clipping series or progress. No fixed total row height. - Wide screens: use a readable maximum list width with aligned rows, not oversized full-width cards. - Stable missing/loading/error artwork fallback; no row geometry jump on image completion. - Preserve loading, cached/offline, empty, filtered-empty and error distinctions. Do not replace valid cached rows with a full-screen failure. - Preserve scroll state on return from details and existing intended behavior when changing filters/sort. - Keep last row and all actions scrollable above floating playback controls. ## Acceptance - Long title + author + series + long-duration progress remain readable at 320/375/414/768 dp and font scales 1.0/1.3/2.0. - Default-size list shows more useful book information per viewport than the current large-card presentation, without sacrificing target size or legibility. Evaluate with the same viewport/data, not an invented target count. - Every sort option remains available and persisted; active sort is visible without opening its menu. - Filters and collection scope are understandable and reversible, including zero results. - Row/details action and any existing series-specific play action remain independently accessible and correct. - Test offline/missing artwork, finished/unstarted/in-progress books, active playback and profile/library switching. - Validate light/dark/AMOLED/background packs, TalkBack, focus/pressed states, contrast and reduced motion. - Compare screenshots before/after using representative long metadata; add focused layout/interaction coverage and run applicable repository gates. - Run Hallmark's final review for hierarchy, restraint, consistency and interaction states. Re-read current main and follow docs/roadmap.md before implementing.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#50
No description provided.