~ knotless Search/
↑↓ move↵ open⇧↵ all results

geesawra.industries/hydraulophone

An unofficial YouTube Music app for iPhone, iPad, and Mac.

0
0
main
1284 lines · 39.8 KB Raw History
import HydraulophoneCore
import SwiftUI

@MainActor
final class LibraryViewModel: ObservableObject {
  private let service: any MusicService
  private var requestTask: Task<Void, Never>?
  private var requestGeneration = UUID()
  private var continuation: PaginationToken?
  private var seenContinuationValues: Set<String> = []

  @Published private(set) var playlists: [Playlist] = []
  @Published private(set) var isLoading = false
  @Published private(set) var isRefreshing = false
  @Published private(set) var isLoadingMore = false
  @Published private(set) var hasMore = false
  @Published var errorMessage: String?
  @Published private(set) var refreshErrorMessage: String?
  @Published private(set) var loadMoreErrorMessage: String?

  init(service: any MusicService) {
    self.service = service
  }

  deinit {
    requestTask?.cancel()
  }

  func clear() {
    requestTask?.cancel()
    requestTask = nil
    requestGeneration = UUID()
    playlists = []
    continuation = nil
    seenContinuationValues.removeAll()
    hasMore = false
    isLoading = false
    isRefreshing = false
    isLoadingMore = false
    errorMessage = nil
    refreshErrorMessage = nil
    loadMoreErrorMessage = nil
  }

  func cancelRequests() {
    requestTask?.cancel()
    requestTask = nil
    requestGeneration = UUID()
    isLoading = false
    isRefreshing = false
    isLoadingMore = false
  }

  /// Loads the first page. This remains the compatibility entry point used by
  /// the original view and by injected fakes.
  func load() async {
    guard !isLoading, !isRefreshing, !isLoadingMore else { return }
    requestTask?.cancel()
    let generation = UUID()
    requestGeneration = generation
    playlists = []
    continuation = nil
    seenContinuationValues.removeAll()
    hasMore = true
    isLoading = true
    errorMessage = nil
    refreshErrorMessage = nil
    loadMoreErrorMessage = nil

    let task = Task { [weak self] in
      guard let self else { return }
      await self.performInitialLoad(
        generation: generation,
        preserveContent: false,
        policy: .reload
      )
    }
    requestTask = task
    await withTaskCancellationHandler(
      operation: {
        await task.value
      },
      onCancel: {
        task.cancel()
      })
    if requestGeneration == generation {
      requestTask = nil
    }
  }

  func refresh() async {
    guard !isLoading, !isRefreshing, !isLoadingMore else { return }
    requestTask?.cancel()
    let generation = UUID()
    requestGeneration = generation
    isRefreshing = true
    refreshErrorMessage = nil
    loadMoreErrorMessage = nil

    let task = Task { [weak self] in
      guard let self else { return }
      await self.performInitialLoad(
        generation: generation,
        preserveContent: true,
        policy: .reload
      )
    }
    requestTask = task
    await withTaskCancellationHandler(
      operation: {
        await task.value
      },
      onCancel: {
        task.cancel()
      })
    if requestGeneration == generation {
      requestTask = nil
    }
  }

  func loadMoreIfNeeded(index: Int) async {
    guard !playlists.isEmpty, index >= max(playlists.count - 4, 0) else { return }
    await loadMore()
  }

  func loadMore() async {
    guard hasMore, let continuation, !isLoading, !isRefreshing, !isLoadingMore else {
      return
    }
    let generation = requestGeneration
    isLoadingMore = true
    loadMoreErrorMessage = nil

    let task = Task { [weak self] in
      guard let self else { return }
      await self.performMoreLoad(continuation: continuation, generation: generation)
    }
    requestTask = task
    await withTaskCancellationHandler(
      operation: {
        await task.value
      },
      onCancel: {
        task.cancel()
      })
    if requestGeneration == generation {
      requestTask = nil
    }
  }

  func retry() async {
    if let loadMoreErrorMessage, !loadMoreErrorMessage.isEmpty {
      await loadMore()
    } else {
      await load()
    }
  }

  func reloadAfterSessionTransition() async {
    await load()
  }

  private func performInitialLoad(
    generation: UUID,
    preserveContent: Bool,
    policy: CatalogLoadPolicy
  ) async {
    defer {
      if requestGeneration == generation {
        isLoading = false
        isRefreshing = false
      }
    }

    do {
      let page: Page<Playlist>
      if let paginatedService = service as? any PaginatedCatalogMusicService {
        page = try await paginatedService.playlistPage(
          continuation: nil,
          policy: policy
        )
      } else {
        page = Page(items: try await service.playlists())
      }
      guard requestGeneration == generation, !Task.isCancelled else { return }

      playlists = uniquePlaylists(page.items)
      continuation = nil
      seenContinuationValues.removeAll()
      hasMore = false
      if !page.items.isEmpty, let next = page.next,
        seenContinuationValues.insert(next.rawValue).inserted
      {
        continuation = next
        hasMore = true
      }
      if preserveContent {
        errorMessage = nil
        refreshErrorMessage = nil
      } else {
        errorMessage = nil
      }
    } catch is CancellationError {
      return
    } catch {
      guard requestGeneration == generation else { return }
      let message =
        (error as? LocalizedError)?.errorDescription ?? "Could not load playlists."
      if preserveContent {
        refreshErrorMessage = message
      } else {
        playlists = []
        continuation = nil
        hasMore = false
        errorMessage = message
      }
    }
  }

  private func performMoreLoad(
    continuation requestedContinuation: PaginationToken,
    generation: UUID
  ) async {
    defer {
      if requestGeneration == generation {
        isLoadingMore = false
      }
    }

    do {
      let page: Page<Playlist>
      if let paginatedService = service as? any PaginatedCatalogMusicService {
        page = try await paginatedService.playlistPage(
          continuation: requestedContinuation,
          policy: .cacheFirst
        )
      } else {
        page = Page(items: try await service.playlists())
      }
      guard requestGeneration == generation, !Task.isCancelled else { return }

      var existingIDs = Set(playlists.map(\.id))
      for playlist in page.items where existingIDs.insert(playlist.id).inserted {
        playlists.append(playlist)
      }
      updateContinuation(after: page)
      loadMoreErrorMessage = nil
    } catch is CancellationError {
      return
    } catch {
      guard requestGeneration == generation else { return }
      loadMoreErrorMessage =
        (error as? LocalizedError)?.errorDescription ?? "Could not load more playlists."
    }
  }

  private func uniquePlaylists(_ values: [Playlist]) -> [Playlist] {
    var seenIDs: Set<String> = []
    return values.filter { seenIDs.insert($0.id).inserted }
  }

  private func updateContinuation(after page: Page<Playlist>) {
    guard !page.items.isEmpty, let next = page.next else {
      continuation = nil
      hasMore = false
      return
    }
    guard seenContinuationValues.insert(next.rawValue).inserted else {
      continuation = nil
      hasMore = false
      return
    }
    continuation = next
    hasMore = true
  }
}

@MainActor
final class LibraryItemsViewModel: ObservableObject {
  private let service: any MusicService
  private var requestTask: Task<Void, Never>?
  private var requestGeneration = UUID()
  private var continuation: PaginationToken?
  private var seenContinuationValues = Set<String>()
  private var category: LibraryCategory?

  @Published private(set) var items: [HydraulophoneCore.LibraryItem] = []
  @Published private(set) var isLoading = false
  @Published private(set) var isRefreshing = false
  @Published private(set) var isLoadingMore = false
  @Published private(set) var hasMore = false
  @Published private(set) var errorMessage: String?
  @Published private(set) var refreshErrorMessage: String?
  @Published private(set) var loadMoreErrorMessage: String?

  init(service: any MusicService) {
    self.service = service
  }

  deinit {
    requestTask?.cancel()
  }

  func clear() {
    requestTask?.cancel()
    requestTask = nil
    requestGeneration = UUID()
    category = nil
    items = []
    continuation = nil
    seenContinuationValues.removeAll()
    hasMore = false
    isLoading = false
    isRefreshing = false
    isLoadingMore = false
    errorMessage = nil
    refreshErrorMessage = nil
    loadMoreErrorMessage = nil
  }

  func load(category requestedCategory: LibraryCategory) async {
    if category != requestedCategory {
      switchCategory(to: requestedCategory)
    }
    guard items.isEmpty, !isLoading else { return }
    await loadFirstPage(policy: .cacheFirst, preserveContent: false)
  }

  func refresh(category requestedCategory: LibraryCategory) async {
    guard category == requestedCategory, !isLoading, !isLoadingMore, !isRefreshing else { return }
    await loadFirstPage(policy: .reload, preserveContent: true)
  }

  func loadMoreIfNeeded(index: Int) async {
    guard !items.isEmpty, index >= max(items.count - 4, 0) else { return }
    await loadMore()
  }

  func loadMore() async {
    guard hasMore, let continuation, let category,
      !isLoading, !isRefreshing, !isLoadingMore
    else {
      return
    }
    let generation = requestGeneration
    isLoadingMore = true
    loadMoreErrorMessage = nil
    let task = Task { [weak self] in
      guard let self else { return }
      await self.performMoreLoad(
        category: category,
        continuation: continuation,
        generation: generation
      )
    }
    requestTask = task
    await task.value
    if requestGeneration == generation {
      requestTask = nil
    }
  }

  private func switchCategory(to category: LibraryCategory) {
    requestTask?.cancel()
    requestTask = nil
    requestGeneration = UUID()
    self.category = category
    items = []
    continuation = nil
    seenContinuationValues.removeAll()
    hasMore = false
    isLoading = false
    isRefreshing = false
    isLoadingMore = false
    errorMessage = nil
    refreshErrorMessage = nil
    loadMoreErrorMessage = nil
  }

  private func loadFirstPage(policy: CatalogLoadPolicy, preserveContent: Bool) async {
    guard let category else { return }
    let generation = requestGeneration
    isLoading = !preserveContent && items.isEmpty
    isRefreshing = preserveContent
    errorMessage = nil
    refreshErrorMessage = nil
    loadMoreErrorMessage = nil
    let task = Task { [weak self] in
      guard let self else { return }
      await self.performFirstPage(
        category: category,
        policy: policy,
        preserveContent: preserveContent,
        generation: generation
      )
    }
    requestTask = task
    await withTaskCancellationHandler(
      operation: { await task.value },
      onCancel: { task.cancel() }
    )
    if requestGeneration == generation {
      requestTask = nil
    }
  }

  private func performFirstPage(
    category: LibraryCategory,
    policy: CatalogLoadPolicy,
    preserveContent: Bool,
    generation: UUID
  ) async {
    defer {
      if requestGeneration == generation {
        isLoading = false
        isRefreshing = false
      }
    }
    do {
      let page = try await fetchPage(
        category: category,
        continuation: nil,
        policy: policy
      )
      guard requestGeneration == generation, !Task.isCancelled else { return }
      items = uniqueItems(page.items)
      seenContinuationValues.removeAll()
      updateContinuation(after: page, previous: nil)
    } catch is CancellationError {
      return
    } catch {
      guard requestGeneration == generation else { return }
      if preserveContent {
        refreshErrorMessage = message(for: error)
      } else {
        errorMessage = message(for: error)
      }
    }
  }

  private func performMoreLoad(
    category: LibraryCategory,
    continuation: PaginationToken,
    generation: UUID
  ) async {
    defer {
      if requestGeneration == generation {
        isLoadingMore = false
      }
    }
    do {
      let page = try await fetchPage(
        category: category,
        continuation: continuation,
        policy: .cacheFirst
      )
      guard requestGeneration == generation, !Task.isCancelled else { return }
      var existingIDs = Set(items.map(\.id))
      items.append(contentsOf: page.items.filter { existingIDs.insert($0.id).inserted })
      updateContinuation(after: page, previous: continuation)
    } catch is CancellationError {
      return
    } catch {
      guard requestGeneration == generation else { return }
      loadMoreErrorMessage = message(for: error)
    }
  }

  private func fetchPage(
    category: LibraryCategory,
    continuation: PaginationToken?,
    policy: CatalogLoadPolicy
  ) async throws -> Page<HydraulophoneCore.LibraryItem> {
    guard let libraryService = service as? any PaginatedLibraryMusicService else {
      throw CachedMusicServiceError.unsupported(.libraryPage)
    }
    return try await libraryService.libraryPage(
      category: category,
      continuation: continuation,
      policy: policy
    )
  }

  private func uniqueItems(_ values: [HydraulophoneCore.LibraryItem])
    -> [HydraulophoneCore.LibraryItem]
  {
    var seenIDs = Set<String>()
    return values.filter { seenIDs.insert($0.id).inserted }
  }

  private func updateContinuation(
    after page: Page<HydraulophoneCore.LibraryItem>,
    previous: PaginationToken?
  ) {
    guard !page.items.isEmpty, let next = page.next,
      next != previous,
      seenContinuationValues.insert(next.rawValue).inserted
    else {
      continuation = nil
      hasMore = false
      return
    }
    continuation = next
    hasMore = true
  }

  private func message(for error: Error) -> String {
    (error as? LocalizedError)?.errorDescription ?? "Could not load your library right now."
  }
}

struct LibraryView: View {
  @EnvironmentObject private var model: AppModel
  @ObservedObject private var downloads: TrackDownloadManager
  @StateObject private var viewModel: LibraryViewModel
  @StateObject private var categoryViewModel: LibraryItemsViewModel
  @State private var isGrid = true
  @State private var selectedCategory: LibraryCategory = .playlists
  @State private var cachedTracks: [CachedTrack] = []

  init(service: any MusicService, downloads: TrackDownloadManager) {
    _downloads = ObservedObject(wrappedValue: downloads)
    _viewModel = StateObject(wrappedValue: LibraryViewModel(service: service))
    _categoryViewModel = StateObject(wrappedValue: LibraryItemsViewModel(service: service))
    #if DEBUG
      let arguments = ProcessInfo.processInfo.arguments
      if arguments.contains("-HydraulophoneOfflineFixture") {
        _isGrid = State(initialValue: !arguments.contains("-HydraulophonePreviewLibraryList"))
      }
    #endif
  }

  var body: some View {
    TrackNavigationStack {
      // Keep navigation chrome and category selection on a stable container.
      // Loading -> ScrollView/List must replace only the content below it.
      VStack(spacing: 0) {
        if model.session?.isAuthenticated == true,
          !model.isRestoringSession,
          !model.isSessionTransitioning
        {
          categoryPicker
        }
        VStack(spacing: 0) {
          libraryContent
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity)
      }
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .background(HydraulophoneTheme.groupedBackground)
      .navigationTitle("Library")
      .navigationBarTitleDisplayMode(.large)
      .toolbar {
        ToolbarItemGroup(placement: .topBarTrailing) {
          if selectedCategory == .playlists,
            model.session?.isAuthenticated == true && !model.isRestoringSession
              && !model.isSessionTransitioning
          {
            Button {
              isGrid.toggle()
            } label: {
              Image(systemName: isGrid ? "list.bullet" : "square.grid.2x2")
                .frame(minWidth: 44, minHeight: 44)
            }
            .accessibilityLabel(isGrid ? "Show playlists as a list" : "Show playlists as a grid")
          }
        }
      }
      .task(id: "\(model.catalogSessionID)-\(model.isOfflineOnly)") {
        guard
          !model.isRestoringSession,
          !model.isSessionTransitioning,
          model.session?.isAuthenticated == true
        else {
          viewModel.clear()
          categoryViewModel.clear()
          return
        }
        if model.isOfflineOnly {
          viewModel.cancelRequests()
          categoryViewModel.clear()
          await refreshCachedTracks()
          return
        }
        if selectedCategory == .playlists {
          if viewModel.playlists.isEmpty {
            await viewModel.load()
          } else {
            await viewModel.refresh()
          }
        } else {
          if categoryViewModel.items.isEmpty {
            await categoryViewModel.load(category: selectedCategory)
          } else {
            await categoryViewModel.refresh(category: selectedCategory)
          }
        }
      }
      .onChange(of: selectedCategory) { _, category in
        if model.isOfflineOnly {
          categoryViewModel.clear()
          if category == .songs { Task { await refreshCachedTracks() } }
          return
        }
        if category == .playlists {
          Task { await viewModel.load() }
        } else {
          Task { await categoryViewModel.load(category: category) }
        }
      }
      .onChange(of: model.isSessionTransitioning) { _, isTransitioning in
        if isTransitioning {
          viewModel.clear()
          categoryViewModel.clear()
        } else if !model.isRestoringSession, model.session?.isAuthenticated == true,
          model.isOfflineOnly
        {
          Task { await refreshCachedTracks() }
        } else if !model.isRestoringSession, model.session?.isAuthenticated == true {
          Task {
            if selectedCategory == .playlists {
              await viewModel.reloadAfterSessionTransition()
            } else {
              await categoryViewModel.load(category: selectedCategory)
            }
          }
        }
      }
      .onChange(of: model.session) { _, session in
        if session?.isAuthenticated != true {
          viewModel.clear()
          categoryViewModel.clear()
        }
      }
      .onReceive(model.playback.$currentSong) { song in
        guard model.isOfflineOnly, let song else { return }
        Task {
          await model.trackCache.updateMetadata(for: song)
          cachedTracks = await model.trackCache.cachedTracks()
        }
      }
      .onChange(of: model.cachedTrackCount) { _, _ in
        guard model.isOfflineOnly else { return }
        Task { cachedTracks = await model.trackCache.cachedTracks() }
      }
      .navigationDestination(for: Playlist.self) { playlist in
        CollectionTracksView(playlist: playlist)
      }
      .navigationDestination(for: Album.self) { album in
        CollectionTracksView(album: album)
      }
      .navigationDestination(for: OfflineLibraryCollection.self) { collection in
        OfflineLibraryCollectionView(collection: collection)
      }
      .toolbar {
        ToolbarItem(placement: .topBarTrailing) {
          NavigationLink {
            DownloadsView(downloads: model.downloads)
          } label: {
            Label("Downloads", systemImage: "arrow.down.circle")
          }
        }
      }
    }
    .tint(HydraulophoneTheme.accent)
  }

  private var offlineSongs: [Song] {
    OfflineLibraryTracks.songs(cached: cachedTracks, downloaded: downloads.availableSongs)
      .map(downloads.songWithResolvedArtwork)
  }

  private func refreshCachedTracks() async {
    var knownSongs = model.playback.queue
    if let currentSong = model.playback.currentSong { knownSongs.append(currentSong) }
    var seenIDs = Set<String>()
    for song in knownSongs where seenIDs.insert(song.id).inserted {
      await model.trackCache.updateMetadata(for: song)
    }
    cachedTracks = await model.trackCache.cachedTracks()
  }

  @ViewBuilder
  private var libraryContent: some View {
    if model.isRestoringSession || model.isSessionTransitioning {
      restoringState
    } else if model.session?.isAuthenticated != true {
      signedOutState
    } else if selectedCategory != .playlists {
      libraryCategoryContent
    } else if !model.isOfflineOnly,
      (viewModel.isLoading || viewModel.isRefreshing) && viewModel.playlists.isEmpty
    {
      VStack(spacing: 14) {
        ProgressView()
          .controlSize(.large)
        Text("Loading your library…")
          .font(.subheadline)
          .foregroundStyle(.secondary)
      }
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .accessibilityElement(children: .combine)
      .accessibilityIdentifier("library.playlists.loading")
    } else if !model.isOfflineOnly, let errorMessage = viewModel.errorMessage,
      viewModel.playlists.isEmpty
    {
      HydraulophoneErrorState(
        title: "Could not load playlists",
        message: errorMessage,
        retry: {
          Task { await viewModel.retry() }
        }
      )
    } else if !model.isOfflineOnly, let refreshErrorMessage = viewModel.refreshErrorMessage,
      viewModel.playlists.isEmpty
    {
      HydraulophoneErrorState(
        title: "Playlist refresh failed",
        message: refreshErrorMessage,
        retry: {
          Task { await viewModel.refresh() }
        }
      )
    } else if viewModel.playlists.isEmpty {
      VStack(spacing: 12) {
        ContentUnavailableView(
          model.isOfflineOnly ? "No cached playlists" : "No playlists yet",
          systemImage: "rectangle.stack",
          description: Text(
            model.isOfflineOnly
              ? "Playlists will appear here when you’re online."
              : "Create a playlist in your music account and it will appear here.")
        )
        if !model.isOfflineOnly, viewModel.hasMore {
          libraryPaginationFooter
        }
      }
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .accessibilityElement(children: .contain)
      .accessibilityIdentifier("library.category.empty")
    } else {
      playlistCollection
        .safeAreaInset(edge: .top, spacing: 0) {
          if !model.isOfflineOnly, let errorMessage = viewModel.refreshErrorMessage {
            LibraryRefreshErrorBanner(
              message: errorMessage,
              retry: {
                Task { await viewModel.refresh() }
              }
            )
          }
        }
    }
  }

  private var categoryPicker: some View {
    Picker("Library category", selection: $selectedCategory) {
      ForEach(LibraryCategory.allCases) { category in
        Text(category.title).tag(category)
      }
    }
    .pickerStyle(.segmented)
    .labelsHidden()
    .padding(.horizontal, 16)
    .padding(.top, 4)
    .padding(.bottom, 8)
    .background(HydraulophoneTheme.groupedBackground)
    .accessibilityLabel("Library category")
  }

  @ViewBuilder
  private var libraryCategoryContent: some View {
    if model.isOfflineOnly && selectedCategory == .songs {
      if offlineSongs.isEmpty {
        ContentUnavailableView(
          "No cached songs", systemImage: "music.note.list",
          description: Text("Complete cached tracks and downloads will appear here.")
        )
        .frame(maxWidth: .infinity, maxHeight: .infinity)
        .accessibilityIdentifier("library.category.empty")
      } else {
        songCollection(offlineSongs, isOfflineList: true)
      }
    } else if model.isOfflineOnly && selectedCategory == .albums {
      let albums = OfflineLibraryTracks.albums(from: offlineSongs)
      if albums.isEmpty {
        offlineCollectionsUnavailable(
          title: "No cached albums",
          message: "Albums appear here when cached tracks include album information.")
      } else {
        offlineCollectionList(albums)
      }
    } else if model.isOfflineOnly && selectedCategory == .artists {
      let artists = OfflineLibraryTracks.artists(from: offlineSongs)
      if artists.isEmpty {
        offlineCollectionsUnavailable(
          title: "No cached artists",
          message: "Artists appear here when cached tracks include artist information.")
      } else {
        offlineCollectionList(artists)
      }
    } else if model.isOfflineOnly {
      ContentUnavailableView(
        "No cached \(selectedCategory.title.lowercased())",
        systemImage: selectedCategory == .playlists ? "rectangle.stack" : "square.stack",
        description: Text("\(selectedCategory.title) will appear here when you’re online.")
      )
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .accessibilityIdentifier("library.category.empty")
    } else if !model.isOfflineOnly && categoryViewModel.isLoading
      && categoryViewModel.items.isEmpty
    {
      VStack(spacing: 14) {
        ProgressView()
          .controlSize(.large)
        Text("Loading your \(selectedCategory.title.lowercased())…")
          .font(.subheadline)
          .foregroundStyle(.secondary)
      }
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .accessibilityElement(children: .combine)
      .accessibilityIdentifier("library.category.loading")
    } else if !model.isOfflineOnly, let errorMessage = categoryViewModel.errorMessage,
      categoryViewModel.items.isEmpty
    {
      HydraulophoneErrorState(
        title: "Could not load \(selectedCategory.title.lowercased())",
        message: errorMessage,
        retry: { Task { await categoryViewModel.load(category: selectedCategory) } }
      )
    } else if categoryViewModel.items.isEmpty {
      ContentUnavailableView(
        model.isOfflineOnly
          ? "No cached \(selectedCategory.title.lowercased())"
          : "No saved \(selectedCategory.title.lowercased()) yet",
        systemImage: selectedCategory == .songs ? "music.note.list" : "square.stack",
        description: Text(
          model.isOfflineOnly
            ? "\(selectedCategory.title) will appear here when you’re online."
            : "Saved \(selectedCategory.title.lowercased()) will appear here.")
      )
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .accessibilityIdentifier("library.category.empty")
    } else {
      if !model.isOfflineOnly, let message = categoryViewModel.refreshErrorMessage {
        LibraryRefreshErrorBanner(message: message) {
          Task { await categoryViewModel.refresh(category: selectedCategory) }
        }
      }
      categoryCollection
    }
  }

  private func offlineCollectionsUnavailable(title: String, message: String) -> some View {
    ContentUnavailableView(title, systemImage: "square.stack", description: Text(message))
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .accessibilityIdentifier("library.category.empty")
  }

  private func offlineCollectionList(_ collections: [OfflineLibraryCollection]) -> some View {
    ScrollView {
      LazyVStack(spacing: 0) {
        ForEach(collections) { collection in
          NavigationLink(value: collection) {
            OfflineLibraryCollectionRow(collection: collection)
          }
          .buttonStyle(.plain)
          .accessibilityIdentifier("library.offline.\(collection.kind).\(collection.id)")
          Divider()
        }
      }
      .padding(.horizontal, 16)
    }
    .refreshable { await refreshCachedTracks() }
  }

  @ViewBuilder
  private var categoryCollection: some View {
    switch selectedCategory {
    case .playlists:
      playlistCollection
    case .songs:
      let songs = categoryViewModel.items.compactMap { item -> Song? in
        guard case .song(let song) = item else { return nil }
        return song
      }
      songCollection(songs, isOfflineList: false)
    case .albums:
      let albums = categoryViewModel.items.compactMap { item -> Album? in
        guard case .album(let album) = item else { return nil }
        return album
      }
      ScrollView {
        LazyVStack(spacing: 0) {
          ForEach(Array(albums.enumerated()), id: \.element.id) { index, album in
            NavigationLink(value: album) {
              LibraryAlbumRow(album: album)
            }
            .buttonStyle(.plain)
            .accessibilityIdentifier("library.album.\(album.id)")
            .onAppear {
              if !model.isOfflineOnly {
                Task { await categoryViewModel.loadMoreIfNeeded(index: index) }
              }
            }
            Divider()
          }
          categoryPaginationFooter
        }
        .padding(.horizontal, 16)
      }
      .refreshable {
        if !model.isOfflineOnly { await categoryViewModel.refresh(category: selectedCategory) }
      }
    case .artists:
      let artists = categoryViewModel.items.compactMap { item -> Artist? in
        guard case .artist(let artist) = item else { return nil }
        return artist
      }
      ScrollView {
        LazyVStack(spacing: 0) {
          ForEach(Array(artists.enumerated()), id: \.element.id) { index, artist in
            NavigationLink(value: TrackDestination.artist(artist)) {
              LibraryArtistRow(artist: artist)
            }
            .buttonStyle(.plain)
            .onAppear {
              if !model.isOfflineOnly {
                Task { await categoryViewModel.loadMoreIfNeeded(index: index) }
              }
            }
            Divider()
          }
          categoryPaginationFooter
        }
        .padding(.horizontal, 16)
      }
      .refreshable {
        if !model.isOfflineOnly { await categoryViewModel.refresh(category: selectedCategory) }
      }
    }
  }

  @ViewBuilder
  private var categoryPaginationFooter: some View {
    if model.isOfflineOnly {
      EmptyView()
    } else if categoryViewModel.isLoadingMore {
      ProgressView("Loading more…")
        .frame(maxWidth: .infinity)
        .padding(.vertical, 10)
    } else if let message = categoryViewModel.loadMoreErrorMessage {
      HStack(spacing: 10) {
        Text(message)
          .font(.footnote)
          .foregroundStyle(.secondary)
          .frame(maxWidth: .infinity, alignment: .leading)
        Button("Retry") { Task { await categoryViewModel.loadMore() } }
          .frame(minHeight: 44)
      }
      .padding(.vertical, 4)
    } else if categoryViewModel.hasMore {
      Button("Load more") { Task { await categoryViewModel.loadMore() } }
        .frame(maxWidth: .infinity, minHeight: 44)
        .padding(.vertical, 4)
    } else {
      Text("End of \(selectedCategory.title.lowercased())")
        .font(.footnote)
        .foregroundStyle(.secondary)
        .frame(maxWidth: .infinity)
        .padding(.vertical, 10)
    }
  }

  @ViewBuilder
  private func songCollection(_ songs: [Song], isOfflineList: Bool) -> some View {
    ScrollView {
      LazyVStack(spacing: 0) {
        ForEach(Array(songs.enumerated()), id: \.element.id) { index, song in
          SongRow(
            song: song,
            accessibilityIdentifier: "library.song.\(song.id)",
            trackNumber: index + 1,
            playNext: { model.playback.enqueueNext(song) },
            addToQueue: { model.playback.enqueue(song) }
          ) {
            model.playback.setQueue(songs, startAt: index)
          }
          .onAppear {
            if !isOfflineList && !model.isOfflineOnly {
              Task { await categoryViewModel.loadMoreIfNeeded(index: index) }
            }
          }
          Divider()
        }
        if !isOfflineList { categoryPaginationFooter }
      }
      .padding(.horizontal, 16)
    }
    .refreshable {
      if !isOfflineList && !model.isOfflineOnly {
        await categoryViewModel.refresh(category: selectedCategory)
      } else if isOfflineList {
        await refreshCachedTracks()
      }
    }
  }

  private var restoringState: some View {
    VStack(spacing: 14) {
      ProgressView()
        .controlSize(.large)
      Text("Restoring your library…")
        .font(.subheadline)
        .foregroundStyle(.secondary)
    }
    .frame(maxWidth: .infinity, maxHeight: .infinity)
    .accessibilityElement(children: .combine)
    .accessibilityLabel("Restoring your library")
  }

  private var signedOutState: some View {
    ContentUnavailableView {
      Label("Your library is private", systemImage: "lock.circle")
    } description: {
      Text("Sign in to see your music account's songs, playlists, albums, and artists.")
    } actions: {
      Button("Sign In") {
        model.showingLogin = true
      }
      .buttonStyle(.borderedProminent)
      .tint(HydraulophoneTheme.accent)
    }
  }

  @ViewBuilder
  private var playlistCollection: some View {
    if isGrid {
      ScrollView {
        VStack(spacing: 16) {
          LazyVGrid(
            columns: [
              GridItem(.adaptive(minimum: 145), spacing: 18, alignment: .top)
            ],
            spacing: 24
          ) {
            ForEach(Array(viewModel.playlists.enumerated()), id: \.element.id) { index, playlist in
              NavigationLink(value: playlist) {
                PlaylistTile(playlist: playlist)
              }
              .buttonStyle(.plain)
              .accessibilityIdentifier(HydraulophoneAccessibilityID.playlist(playlist.id))
              .onAppear {
                if !model.isOfflineOnly { Task { await viewModel.loadMoreIfNeeded(index: index) } }
              }
            }
          }
          .padding(.horizontal, 20)
          .padding(.top, 8)
          libraryPaginationFooter
        }
        .padding(.bottom, 24)
      }
      .accessibilityIdentifier(HydraulophoneAccessibilityID.playlistCollection)
      .refreshable {
        if !model.isOfflineOnly { await viewModel.refresh() }
      }
    } else {
      List {
        ForEach(Array(viewModel.playlists.enumerated()), id: \.element.id) { index, playlist in
          NavigationLink(value: playlist) {
            PlaylistRow(playlist: playlist)
          }
          .buttonStyle(.plain)
          .accessibilityIdentifier(HydraulophoneAccessibilityID.playlist(playlist.id))
          .listRowInsets(EdgeInsets(top: 4, leading: 16, bottom: 4, trailing: 16))
          .onAppear {
            if !model.isOfflineOnly { Task { await viewModel.loadMoreIfNeeded(index: index) } }
          }
        }
        libraryPaginationFooter
          .listRowInsets(EdgeInsets(top: 4, leading: 16, bottom: 8, trailing: 16))
          .listRowSeparator(.hidden)
      }
      .listStyle(.plain)
      .accessibilityIdentifier(HydraulophoneAccessibilityID.playlistCollection)
      .refreshable {
        if !model.isOfflineOnly { await viewModel.refresh() }
      }
    }
  }

  @ViewBuilder
  private var libraryPaginationFooter: some View {
    if model.isOfflineOnly {
      EmptyView()
    } else if viewModel.isLoadingMore {
      ProgressView("Loading more playlists…")
        .frame(maxWidth: .infinity)
        .padding(.vertical, 10)
        .accessibilityElement(children: .combine)
    } else if let message = viewModel.loadMoreErrorMessage {
      HStack(spacing: 10) {
        Text(message)
          .font(.footnote)
          .foregroundStyle(.secondary)
          .frame(maxWidth: .infinity, alignment: .leading)
        Button("Retry") {
          Task { await viewModel.loadMore() }
        }
        .frame(minHeight: 44)
      }
      .padding(.vertical, 4)
      .accessibilityElement(children: .contain)
    } else if viewModel.hasMore && !viewModel.isLoading && !viewModel.isRefreshing {
      Button("Load more") {
        Task { await viewModel.loadMore() }
      }
      .frame(maxWidth: .infinity, minHeight: 44)
      .padding(.vertical, 4)
    } else if !viewModel.hasMore {
      Text("End of playlists")
        .font(.footnote)
        .foregroundStyle(.secondary)
        .frame(maxWidth: .infinity)
        .padding(.vertical, 10)
        .frame(maxWidth: .infinity)
        .accessibilityLabel("End of playlists")
    }
  }
}

private struct LibraryRefreshErrorBanner: View {
  let message: String
  let retry: () -> Void

  var body: some View {
    HStack(alignment: .top, spacing: 10) {
      Image(systemName: "exclamationmark.triangle.fill")
        .foregroundStyle(.orange)
      Text("Refresh failed: \(message)")
        .font(.footnote)
        .foregroundStyle(.secondary)
        .frame(maxWidth: .infinity, alignment: .leading)
      Button("Retry", action: retry)
        .font(.footnote.weight(.semibold))
        .frame(minHeight: 44)
    }
    .padding(.horizontal, 16)
    .padding(.vertical, 10)
    .background(.regularMaterial)
    .accessibilityElement(children: .combine)
    .accessibilityLabel("Playlist refresh failed. \(message)")
  }
}

private struct LibraryAlbumRow: View {
  let album: Album

  var body: some View {
    HStack(spacing: 12) {
      ArtworkView(url: album.thumbnailURL)
      VStack(alignment: .leading, spacing: 3) {
        Text(album.title)
          .font(.body.weight(.medium))
          .foregroundStyle(.primary)
          .lineLimit(2)
        if let subtitle = album.subtitle, !subtitle.isEmpty {
          Text(subtitle)
            .font(.subheadline)
            .foregroundStyle(.secondary)
            .lineLimit(1)
        }
      }
      Spacer(minLength: 8)
      Image(systemName: "chevron.right")
        .font(.subheadline.weight(.semibold))
        .foregroundStyle(.secondary)
        .accessibilityHidden(true)
    }
    .contentShape(Rectangle())
    .padding(.vertical, 7)
    .padding(.horizontal, 4)
    .accessibilityLabel("Open album \(album.title)")
    .accessibilityHint("Shows the songs on this album")
  }
}

private struct LibraryArtistRow: View {
  let artist: Artist

  var body: some View {
    HStack(spacing: 12) {
      ArtworkView(url: artist.thumbnailURL, cornerRadius: 26)
      Text(artist.title)
        .font(.body.weight(.medium))
        .foregroundStyle(.primary)
        .lineLimit(2)
      Spacer(minLength: 8)
    }
    .contentShape(Rectangle())
    .padding(.vertical, 7)
    .padding(.horizontal, 4)
    .accessibilityLabel(artist.title)
  }
}

private struct OfflineLibraryCollectionRow: View {
  let collection: OfflineLibraryCollection

  var body: some View {
    HStack(spacing: 12) {
      ArtworkView(
        url: collection.thumbnailURL,
        cornerRadius: collection.kind == .artist ? 26 : 10)
      VStack(alignment: .leading, spacing: 3) {
        Text(collection.title)
          .font(.body.weight(.medium))
          .foregroundStyle(.primary)
          .lineLimit(2)
        Text(collection.subtitle ?? "\(collection.songs.count) songs")
          .font(.subheadline)
          .foregroundStyle(.secondary)
          .lineLimit(1)
      }
      Spacer(minLength: 8)
      Image(systemName: "chevron.right")
        .font(.subheadline.weight(.semibold))
        .foregroundStyle(.secondary)
        .accessibilityHidden(true)
    }
    .contentShape(Rectangle())
    .padding(.vertical, 7)
    .padding(.horizontal, 4)
    .accessibilityLabel(
      "Open \(collection.kind == .album ? "album" : "artist") \(collection.title)")
  }
}

private struct OfflineLibraryCollectionView: View {
  @EnvironmentObject private var model: AppModel
  let collection: OfflineLibraryCollection

  var body: some View {
    ScrollView {
      VStack(alignment: .leading, spacing: 16) {
        HStack(spacing: 14) {
          ArtworkView(
            url: collection.thumbnailURL, size: 92,
            cornerRadius: collection.kind == .artist ? 46 : 12)
          VStack(alignment: .leading, spacing: 5) {
            Text(collection.title)
              .font(.title2.weight(.bold))
              .lineLimit(2)
            Text(collection.subtitle ?? "\(collection.songs.count) songs")
              .font(.subheadline)
              .foregroundStyle(.secondary)
          }
          Spacer(minLength: 0)
        }
        .padding(.horizontal, 16)
        .padding(.top, 12)

        LazyVStack(spacing: 0) {
          ForEach(Array(collection.songs.enumerated()), id: \.element.id) { index, song in
            SongRow(
              song: song, trackNumber: index + 1,
              playNext: { model.playback.enqueueNext(song) },
              addToQueue: { model.playback.enqueue(song) }
            ) {
              model.playback.setQueue(collection.songs, startAt: index)
            }
            Divider()
          }
        }
        .padding(.horizontal, 16)
      }
      .padding(.bottom, 20)
    }
    .background(HydraulophoneTheme.groupedBackground)
    .navigationTitle(collection.title)
    .navigationBarTitleDisplayMode(.inline)
  }
}