App Navigation
Relevant source files
The following files were used as context for generating this wiki page:
App Navigation in Spotty provides a native macOS interface for browsing Spotify content, managing the user library, and controlling playback state. It organizes the application into a standard three-pane layout consisting of a library sidebar, a central content area, and an optional inspector panel for queue and device management. The system follows established macOS structural patterns, including a unified toolbar with navigation history and search capabilities.
The navigation architecture emphasizes native behavior, preserving selection, focus, and scroll position across state updates. It uses SwiftUI's scene management and window styles to provide a visually calm, dark-themed experience tailored for Apple Silicon Macs.
Navigation Architecture and Root Structure
The RootView manages the top-level layout using an HSplitView to separate the sidebar from the primary content. It coordinates navigation state via a MediaSelectionModel and maintains history for back/forward operations.
The diagram shows the hierarchical layout of RootView and its primary structural components.
Sources: Sources/Spotty/RootView.swift:15-58
Navigation State Management
Navigation state is encapsulated in the SidebarSelection and MediaSelectionModel types. RootView tracks mediaSelectionRawValue to persist navigation through app lifecycles.
- Selection Binding:
RootViewprovides aselectionBindingto theSidebarViewto synchronize user clicks with the current route. - History: Back and forward stacks (
backHistory,forwardHistory) store raw values of the navigation model, limited to 100 entries. - Epoch Resets: The
accountEpochfrom the player triggers a full navigation reset when the authenticated session changes.
Sources: Sources/Spotty/RootView.swift:20-25, Sources/Spotty/RootView.swift:222-255
Primary Components
Sidebar (SidebarView)
The SidebarView lists the main library sections and user-owned playlists. It facilitates quick access to "Home", "Search", and "Liked Songs".
| Component | Target Destination | Source Data |
|---|---|---|
| Home | .destination(.home) | Static entry |
| Search | .destination(.search) | Static entry |
| Liked Songs | .destination(.liked) | HomeLibraryStore |
| Library Sections | .albums, .artists | HomeLibraryStore |
| Playlists | .playlist(uri) | PlaylistLibraryNode collection |
Sources: Sources/Spotty/Views/SidebarView.swift, Sources/Spotty/RootView.swift:110-149
Navigation Bar
The NavigationBar contains controls for traversing history and initiating searches. It uses SpottyPalette.navigationControl for its background and integrates with the window's unified toolbar style.
- History Controls: Back and forward buttons are enabled based on the availability of history stacks.
- Search Integration: A search field updates the
searchTextbinding, whichRootViewpasses to theSearchView. - Visual Transitions: The bar detects if the current view is "Home" to adjust its transparency or layout.
Sources: Sources/Spotty/Views/NavigationBar.swift, Sources/Spotty/RootView.swift:29-38
Content Detail Area
The detail view in RootView dynamically resolves based on the current SidebarSelection. It handles the presentation of tracks, albums, and artist details.
Sequence of events when a user selects a catalog item for navigation.
Sources: Sources/Spotty/RootView.swift:151-175
Inspector and Side Panel
The inspector panel, implemented as SidePanelView, provides contextual information without interrupting the main content flow. It is toggled via showsSidePanel and is typically anchored to the bottom right of the layout.
- Panel Modes: Supports switching between
.queueand.devices. - Metadata Integration: Accesses the
CatalogMetadataRepositoryto display details about currently playing or selected tracks. - Platform Design: Uses
inspectorColumnWidthto ensure macOS-standard sidebar dimensions (260pt - 360pt).
Sources: Sources/Spotty/Views/SidePanelView.swift, Sources/Spotty/RootView.swift:45-56
UI Guidelines and Implementation
Navigation behavior must adhere to the "Native UI agent guidance":
- Selection Persistence: Navigation must preserve selection and focus across metadata arrivals and window activation.
- Honest State: The UI renders error states (e.g.,
unavailableMedia) when items are missing from the loaded catalog rather than showing speculative data. - Performance: Artwork is downsampled to rendered Retina size and presentation caches are bound to the window lifecycle.
- Interaction: Drag-and-drop (
.draggable,.dropDestination) is explicitly excluded from the current product contract.
Sources: Sources/Spotty/Views/AGENTS.md, Sources/Spotty/RootView.swift:184-204
Summary
App Navigation in Spotty provides a robust, state-driven framework for macOS music browsing. By leveraging SwiftUI bindings and a centralized selection model, it ensures a consistent user experience between library management, content discovery, and playback control. The three-pane architecture allows users to maintain context while exploring the Spotify catalog, all while adhering to native macOS design principles.