/// Canonical route paths. Reference these constants instead of raw strings so
/// navigation targets are discoverable and refactor-safe.
abstract final class AppRoutes {
  static const String library = '/library';

  /// One album's tracks, reached from the Library's Albums tab. A child of
  /// [library] so it keeps the bottom nav and pops back into that tab; the
  /// derived album id rides as a path segment.
  static const String albumDetail = '/library/album';

  /// Builds the [albumDetail] location for a derived album [id].
  static String albumDetailPath(String id) =>
      '$albumDetail/${Uri.encodeComponent(id)}';

  /// One artist's catalog, reached from the Library's Artists tab. A child of
  /// [library] for the same reasons as [albumDetail].
  static const String artistDetail = '/library/artist';

  /// Builds the [artistDetail] location for a derived artist [id].
  static String artistDetailPath(String id) =>
      '$artistDetail/${Uri.encodeComponent(id)}';

  static const String playlists = '/playlists';

  /// Liked tracks, reached from the Playlists tab. A child of [playlists] so it
  /// keeps the bottom nav and pops back into that tab.
  static const String favorites = '/playlists/favorites';

  /// A single playlist's tracks. A child of [playlists] (so it keeps the bottom
  /// nav and pops back into that tab); the playlist id rides as a path segment.
  static const String playlistDetail = '/playlists/detail';

  /// Builds the [playlistDetail] location for a given playlist [id].
  static String playlistDetailPath(String id) => '$playlistDetail/$id';

  /// The "Smart mixes" section (automatic, Made-by-Linthra collections), reached
  /// from the Playlists tab. A child of [playlists] so it keeps the bottom nav
  /// and pops back into that tab.
  static const String smartMixes = '/playlists/smart';

  /// Builds the location for a single smart mix, identified by its kind [id]
  /// (`SmartPlaylistKind.id`), which rides as a path segment.
  static String smartMixPath(String id) => '$smartMixes/$id';

  static const String downloads = '/downloads';

  /// The Settings hub: a list of categories, each opening its own detail page
  /// below. The categories are children of [settings] so they keep the bottom
  /// nav and pop back into that tab.
  static const String settings = '/settings';

  /// "Connections" — the music-source connections (Jellyfin, Plex,
  /// Navidrome/Subsonic, local files). A child of [settings].
  static const String settingsConnections = '/settings/connections';

  /// "Music & playback" — default source and playback behaviour. A child of
  /// [settings].
  static const String settingsPlayback = '/settings/playback';

  /// "Cache & data" — smart pre-cache and the on-device cache limit. A child of
  /// [settings].
  static const String settingsCache = '/settings/cache';

  /// "Offline & downloads" — the Wi-Fi / mobile-data download policy. A child of
  /// [settings].
  static const String settingsDownloads = '/settings/downloads';

  /// "Appearance" — pick an in-app branding variant for the Linthra mark. Purely
  /// cosmetic; a child of [settings].
  static const String settingsAppearance = '/settings/appearance';

  /// "Diagnostics & support" — report a bug and copy a safe diagnostics
  /// snapshot. A child of [settings].
  static const String settingsDiagnostics = '/settings/diagnostics';

  /// "About" — version, build, and project links. A child of [settings].
  static const String settingsAbout = '/settings/about';

  /// "Support Linthra" — voluntary, optional ways to support development.
  /// Reached from About; a child of [settings] so it keeps the bottom nav and
  /// pops back into that tab. Free and open-source: nothing here gates a
  /// feature.
  static const String settingsSupport = '/settings/support';

  /// The "Report a bug" builder, reached from Diagnostics & support. A child of
  /// [settings] so it keeps the bottom nav and pops back into that tab.
  static const String reportBug = '/settings/report-bug';

  /// Full-screen now-playing view, pushed above the shell.
  static const String player = '/player';
}
