pluriwave/openspec/changes/rediseno-funcional/specs/station-discovery-browse/spec.md

Station Discovery & Browse Specification

Purpose

Discovery content as the Buscar tab's landing state, active-filter pills, results counter, clear-all-filters, the Países browser over the verified /json/countries contract, and a client-side search-sort control. Traceable to WU5 (relocation), WU6 (Buscar), WU7 (Países + _get transport extraction).

Requirements

Requirement: Buscar Landing State Shows Discovery Content

Buscar MUST render the existing discovery content (near-you, genres, trending, countries entry point) as its landing state whenever no search query is entered. Entering a query MUST replace that landing state with search results.

Scenario: Empty query shows discovery content

• GIVEN the user opens the Buscar tab with no prior query
• WHEN the screen renders
• THEN near-you, genre, trending, and a Países entry point are visible

Scenario: Entering a query replaces the landing state

• GIVEN the Buscar tab is showing discovery content
• WHEN the user types a non-empty query
• THEN discovery content is replaced by the search-results view

Requirement: Active-Filter Pills and Results Counter

The search-results view MUST show each active filter (country, language, minimum quality) as a removable pill, and MUST show a results counter ("N RESULTADOS").

Scenario: Applying a filter shows a removable pill

• GIVEN the user has an active search
• WHEN they apply a country filter
• THEN a pill labeled with that country and a close (x) affordance appears
• AND the results counter reflects the filtered count

Scenario: Removing a pill re-runs the search without that filter

• GIVEN a country filter pill is active
• WHEN the user taps its close affordance
• THEN the filter is cleared and results/count update accordingly

Requirement: One-Tap Clear-All-Filters on Empty Results

When 1 or more filters are active and the resulting search has zero results, the system MUST offer a single action that clears every active filter at once ("Quitar los N filtros").

Scenario: Two active filters, zero results

• GIVEN country and quality filters are both active and yield 0 results
• WHEN the empty state renders
• THEN a "Quitar los 2 filtros" action is shown
• AND tapping it clears both filters in one action, not one at a time

Requirement: Países Browser Over the Verified Countries Contract

The Países screen (new second-level screen) MUST fetch from /json/countries (optional substring filter /json/countries/{filter}) and MUST NOT use /json/countrycodes, which is deprecated. It MUST parse the stationcount field as a string via int.tryParse, never as a direct int cast. Its request MUST NOT include lastcheckok, since that parameter is meaningful only for station-listing calls. Source: Engram reference/radio-browser-countries-endpoint (id 2500), verified against https://api.radio-browser.info/.

Scenario: Countries list renders with counts

• GIVEN /json/countries returns a list of country objects
• WHEN the Países screen loads
• THEN "Tus idiomas" and the full alphabetical list render with each country's parsed station count

Scenario: stationcount arrives as a JSON string (edge case, critical)

• GIVEN a country entry has "stationcount": "482" (a JSON string, not a number)
• WHEN the screen parses and renders that entry
• THEN it displays 482 without throwing a type-cast error

Scenario: Countries request omits the station-only filter

• GIVEN the Países screen issues its /json/countries request
• WHEN the outgoing request is inspected
• THEN it does NOT include lastcheckok

Requirement: Client-Side Search Sort Only

Buscar MUST expose an "Ordenar" control backed exclusively by client-side ordering (OrdenEmisoras). The system MUST NOT adopt the Radio Browser server-side order/reverse parameters for this control, because server-side ordering sorts the full result set before limit is applied while the app's client-side sort only reorders the page already fetched — adopting it would silently change which stations users see, not just their order. Every sort option rendered in the UI MUST map to a real OrdenEmisoras case; the system MUST NOT render an option that does not actually sort. Source: Engram reference/radio-browser-sort-order (id 2505), verified against https://api.radio-browser.info/.

Scenario: Selecting a sort option reorders the current page only

• GIVEN a set of search results is already fetched
• WHEN the user selects "Ordenar: calidad"
• THEN the currently-displayed page is reordered via OrdenEmisoras.calidad
• AND no new network request with an order parameter is issued

Scenario: Every rendered sort option is backed by a real case (regression guard)

• GIVEN the "Ordenar" control's rendered option list
• WHEN each option is checked against OrdenEmisoras
• THEN every option maps to an existing enum case with test coverage; no decorative option that does not sort is rendered

Requirement: Existing Station Calls Unchanged by Transport Extraction

Extracting _get's transport loop (server discovery, host rotation, bounded retries, User-Agent, timeout, status check, json.decode) into a shared helper for the Países call MUST NOT change the observable behavior of the 8 existing ServicioRadio station methods: obtenerPopulares, obtenerTendencias, buscarPorNombre, buscarPorPais, buscarPorIdioma, buscarPorTag, buscar, registrarClick.

Scenario: Characterization tests pass unchanged before and after extraction

• GIVEN characterization tests exist for all 8 station methods
• WHEN the transport loop is extracted from _get
• THEN all 8 tests pass identically before and after the extraction

Scenario: Station calls still send lastcheckok

• GIVEN any of the 8 station methods issues a request
• WHEN the outgoing request is inspected
• THEN it still includes lastcheckok=1, unchanged from before the extraction