# MapBasemapControl

## Overview

`MapBasemapControl` switches between the six base maps: roads, grayscale, high contrast, night, satellite and terrain. `high-contrast` is also the accessibility route for the map itself, not just a stylistic option.

---

## Import

```tsx
import { Map, MapBasemapControl, type MapBasemap } from 'xertica-ui/ui';
```

---

## Prerequisites

- `satellite` and `terrain` come from the native `mapTypeId` and need no configuration.
- `grayscale`, `high-contrast` and `night` are faithful only with Cloud Styling behind a Map ID. Supply one through `basemapStyles`; without it, the map falls back to a CSS filter over the tile pane — an accepted degradation, and what applications already do by hand.

---

## Props

| Prop        | Type                                  | Default       | Description                      |
| ----------- | ------------------------------------- | ------------- | -------------------------------- |
| `value`     | `MapBasemap`                          | required      | The active base map.             |
| `onChange`  | `(basemap: MapBasemap) => void`       | required      | Called with the chosen base map. |
| `options`   | `Array<Exclude<MapBasemap, 'none'>>`  | all six       | Which base maps to offer.        |
| `labels`    | `Partial<Record<MapBasemap, string>>` | English       | Overrides the built-in labels.   |
| `variant`   | `'inline' \| 'overlay'`               | `'inline'`    | `overlay` floats over the map.   |
| `position`  | `MapOverlayPosition`                  | `'top-right'` | Anchor for `variant="overlay"`.  |
| `ariaLabel` | `string`                              | `"Base map"`  | Accessible name for the group.   |

---

## Example

```tsx
const [basemap, setBasemap] = useState<MapBasemap>('roads');

<Map
  height="520px"
  basemap={basemap}
  basemapStyles={{ night: { mapId: 'YOUR_NIGHT_MAP_ID' } }}
  markers={markers}
>
  <MapOverlay position="top-right">
    <MapBasemapControl value={basemap} onChange={setBasemap} />
  </MapOverlay>
</Map>;
```

---

## AI Rules

- **Always** keep `high-contrast` in `options` unless there is a specific reason to drop it — it is the map's accessibility route.
- **Always** pass the same `value` to `<Map basemap>` or the buttons will disagree with the tiles.
- **Always** configure a Cloud-styled `mapId` for `grayscale`, `high-contrast` and `night` in production. The CSS-filter fallback is a degradation, not the intended rendering.
- **Never** apply a basemap filter to the whole map container. The library filters the tile pane only; inverting a marker's color would break the token contract.
- `basemap="none"` draws no basemap at all — see the `Map` documentation for the keyless data layer.