Android: Add sticky section headers to songs list with sort-aware grouping

[Copilot]

Implements sticky section headers for Android RecyclerView that adapt to TQL sort directives and provide contextual navigation actions.

Implementation

Section Grouping Logic

• Alphabetical (A-Z, #) for title/artist/album sorts
• Date-based (YYYY-MM) for date field sorts
• Single "Shuffle" header for shuffle mode
• Computed once per query change via SectionGroupingHelper

Sticky Rendering

• Custom ItemDecoration draws pinned header without ConcatAdapter overhead
• Multi-view type adapter pattern (header vs. song ViewHolders)
• Position mapping handles flattened list with interspersed headers

Interactive Menu

• BottomSheet on header tap: jump to section, scroll to top/current, change sort, exit shuffle
• Context-aware actions (shuffle exit only in shuffle mode)

Key Changes

Core Logic (new files in SectionHeader/)

// Sections computed from query plan
var sections = SectionGroupingHelper.ComputeSections(songs, queryPlan);

// Position conversion for scroll operations
int flatPosition = adapter.GetFlatPositionForSongIndex(songIndex);
recyclerView.SmoothScrollToPosition(flatPosition);

ViewModel Integration

• Added CurrentQueryPlan property to track sort state
• Reactive updates trigger section recomputation

Adapter Modifications

• GetItemViewType() distinguishes headers from songs
• RebuildListItems() flattens sections + songs on data changes
• Position helpers map between song indices and flat list positions

Architecture

TQL Query → RealmQueryPlan → SectionGroupingHelper → Flat List (H,S,S,H,S...) → ItemDecoration

Section computation complexity: O(n) per query change, O(1) during scroll.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Android: Add Sticky Section Headers to Songs List (Sort-Aware, Clickable)</issue_title>
<issue_description>- Description

Implement sticky section headers in the Android songs list to improve navigation and sorting clarity. Headers should adapt to current sort mode and support user interaction.

• Scope

Android native only (RecyclerView / Views)
Not MAUI, not cross-platform

• Requirements

Sticky Headers
Headers remain pinned while scrolling
Implement using RecyclerView + ConcatAdapter + ItemDecoration
No third-party libraries

Dynamic Header Grouping should be derived from the sort directive applied in TQL.
DESC / ASC played→ date sections
Asc / DESC title→ A–Z sections for title etc

SHUFFLE → single static header: "Shuffle"

• Clickable Headers
  Header tap opens a context menu (BottomSheet or PopupMenu)

Menu actions:
Jump to section
Change sort mode
Exit shuffle
Scroll to top
Scroll to current playing song
Jump List Support

Precompute section → adapter position mapping
Smooth scroll to selected section
Performance
No recomputation during scroll
Headers derived once per dataset change
Implementation Notes

Use ConcatAdapter for headers + songs
Headers are real ViewHolders
Sticky behavior via custom ItemDecoration
Sorting rebuilds section model and adapters
Acceptance Criteria
Headers stick correctly under toolbar
Correct grouping for all sort modes
Shuffle shows only one header
Header menu opens reliably
Jump navigation is accurate</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Android: Add Sticky Section Headers to Songs List (Sort-Aware, Clickable) #323

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.