Data Tables & Track Lists
Relevant source files
The following files were used as context for generating this wiki page:
TrackTable provides the native macOS interface for displaying track collections within Spotty. It renders information-dense lists for search results, album views, and playlists, supporting complex behaviors such as multi-selection, custom sorting, and metadata enrichment.
The system distinguishes between two primary variants: catalog and playlist. The catalog variant emphasizes discovery with metadata like BPM and Key, while the playlist variant prioritizes organization with artwork, "Date Added" fields, and nested headers.
Sources: Sources/Spotty/Views/TrackTable.swift:7-21
Component Architecture
The TrackTable is a SwiftUI View that utilizes the native macOS Table component for catalog views and a custom List implementation for playlist views to support variable headers.
Data Model and Display Cache
To ensure performance during sorting and filtering, the system uses a TrackTableDisplayCache. This cache holds TrackTableRow objects, which wrap CatalogTrack entities with pre-calculated sort values derived from the CatalogMetadataRepository.
Table Variants
The behavior and appearance of the list change based on the TrackTableVariant enum:
| Variant | Layout Type | Primary Columns | Default Sort |
|---|---|---|---|
catalog | Native Table | Title, Artist, Album, Popularity, BPM, Key, Time | None |
playlist | Custom List | # (Index), Title/Artist, Album, Date Added, Duration | Date Added (Reverse) |
Sources: Sources/Spotty/Views/TrackTable.swift:7-21, Sources/Spotty/Views/TrackTable.swift:204-245
Metadata Enrichment & Sorting
Spotty enriches standard track data (Title, Artist, Album) with extended attributes fetched via the TrackAttributesProviding service. This data is managed by the CatalogMetadataRepository.
Enrichment Process
- Discovery: When a track collection is loaded,
loadTrackAttributesidentifies URIs missing metadata. - Batching: URIs are batched (default size 100) and limited to a request cap (1,000) to avoid overloading the service.
- Caching: Fetched
TrackAttributes(Popularity, BPM, Key) are stored in the repository and mapped toTrackTableRowinstances.
Sorting Logic
Sorting uses KeyPathComparator objects. Specific logic is applied to music-theoretical data:
- Camelot Key: Sorts numerically based on the Camelot string (e.g., "8B" before "10A").
- BPM: Rounds decimal values to the nearest integer for display and sorting.
- Missing Data: Entries with missing attributes are consistently placed at the end of the sort order.
Sources: Tests/SpottyBoundaryTests/FormattingAndSortingChecks.swift:10-43, Tests/SpottyBoundaryTests/FormattingAndSortingChecks.swift:94-136
Playlist Management
In the playlist variant, the track list supports specific identifiers and mutations.
Occurrence Identifiers (UIDs)
Playlists use a uid (unique occurrence identifier) rather than a track URI for item management. This allows the system to distinguish between multiple instances of the same track in one playlist. Operations like removeFromPlaylist and moveItemsInPlaylist require these UIDs.
Sources: Sources/Spotty/Spotify/PathfinderPlaylist.swift:75-87
User Interactions
TrackTable implements standard macOS interaction patterns:
- Playback: Double-click or Return key plays the selected track.
- Queue: Context menu provides "Add to Queue" for the current selection.
- Playlist Editing: If
playlistActionsare provided, users can "Add to Playlist" (selecting from owned playlists) or "Remove from Playlist".
Sources: Sources/Spotty/Views/TrackTable.swift:115-155, Sources/Spotty/Views/TrackTable.swift:343-356
Layout and Presentation
The playlist layout includes specialized headers that respond to scroll position.
Media Detail Headers
MediaDetailHeader provides the artwork-led identity at the top of the list. It dynamically adjusts its size based on the available width, switching between horizontalHeader and compactHeader layouts.
Sources: Sources/Spotty/Views/MediaDetailHeader.swift:39-65
Summary
The TrackTable serves as the central data visualization component in Spotty. By combining native macOS table performance with a robust metadata enrichment system, it provides users with technical track details (BPM, Key) and efficient playlist management tools, maintaining architectural separation between the view state and the account-scoped metadata repository.