# XWUIMarketplaceBrowse

A vehicle-marketplace browse surface that knows it is aggregating more than one
source: listings carry the platform they came from, chip rows filter by country
and by platform, and each card can link straight out to the origin site. It is
the index page of a cross-border aggregator, not a generic card grid.

## When to use

- An aggregator front page or search result set spanning several countries and
  several source platforms.
- Any listing grid where provenance matters and the user must see which site a
  result came from.
- A country- or platform-scoped view: set `data.country` or `data.platform` and
  the grid renders that slice.

For a listing grid with no country/platform dimension, compose `XWUICardX` in a
layout component instead.

## Data, or an API base

There are two ways to feed it:

- Hand it `listings`, `platforms` and `countries` directly. Countries carry a
  `count` for the chip badge; platforms carry `logoUrl` and `baseUrl` so cards
  can link out.
- Set `data.apiBase` and the component fetches listings from
  `{apiBase}/search/listings` and platforms from `{apiBase}/providers` (falling
  back to `/connectors`). A host such as `vehicles-web` passes
  `/api/vehicles/v1`.

A listing is `{ id, title, make, model, year, price, currency, mileageKm, city,
country, platformId, platformName, platformLogoUrl, photoUrl, dealCategory,
dealScore, href }`. `dealCategory` pairs with `XWUIDealTierIndicator`, so the
price verdict your valuation service produced renders on the card.

Opening a card is delegated, not owned: cards carry a `data-act` prefix
(`openAct`, default `open-listing`) and the host decides whether that means a
route change or a new tab to `href`.

## Configuration surface

`data`: `listings`, `platforms`, `countries`, `country` (active ISO-2 filter, or
empty for all), `platform` (active platform id, or empty for all), `title`,
`subtitle`, `emptyTitle`, `emptyDescription`, `apiBase`.

`config`: `columns`, `showCountryChips`, `showPlatformChips`, `openAct`,
`locale`, `className`.

## Basic Usage

A marketplace index browsed by country and platform: each country carries its
listing `count` and each platform its `baseUrl`, so cards can link straight out
to the source site.

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: A multi-country, multi-platform listing index.
```

## Showcase

A full multi-country listing grid with flag and platform chips, a
country-filtered view, a compact grid with the chip rows hidden, and the empty
state shown when a search yields no results.

```example
file: examples/Showcase.ts
html: examples/Showcase.html
title: Showcase
description: Filtered, compact and empty variants of the browse grid.
```

```api
```