# Map foundations
> What @sdxc/ui/map is for, the server-first rules its maps share, and every variable it reads.

Places on a map beside the list they belong to: price pins for stays, a courier riding a route, a pin that lights up while its row is hovered.

A map renders on the server, so its pins are real links before any script loads. `GeoMap` then hands the same markers to MapLibre for dragging and zooming; `MapCanvas` stays a drawing.

Import the components from `@sdxc/ui/map` and the theme once from `@sdxc/ui/theme.css`.

## When to reach for it

- Search results whose rows and pins should point at each other.
- A delivery or ride whose marker moves along a route as it streams.
- A listing's location, drawn in the page with no third-party map.
- A real map of places by longitude and latitude, with clusters and "search this area".

## Shared ideas

- **Pins are links.** A pin with `href` is an `<a>`, otherwise a button that can open a popover; both work without script.
- **One coordinate space.** Art, routes, markers and pins share the stage's viewBox, so a crop moves all of them together.
- **Linked by key.** Rows and pins sharing a `data-map-key` light each other through `mapLink` or one `MapCanvasSync`.
- **Real streets, or your own.** `GeoMap` draws OpenFreeMap's light and dark streets by default; pass a GeoJSON region you ship, or another style URL, as `basemap`.
- **Progress as a variable.** A route marker reads `--ui-map-progress`, so any island moves it by setting one property.

## CSS variables

Every custom property the namespace reads or declares. Reads the neutral role for pins, hairlines and surfaces, and brand for routes, markers and a brand-toned pin. The roles are documented on Theming.

### Stage and pins

Set on the map or an ancestor to restyle every part at once.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-map-radius` | `0.75rem` | The corner of the map's stage. |
| `--ui-map-ground` | `the neutral tint` | The stage's fill behind the art. |

### GeoMap basemap

Each defaults to a mix with the page background, so the map follows dark mode.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-map-land` | `a tint of the background` | Land polygons. |
| `--ui-map-water` | `a blue mix` | Seas, lakes and rivers. |
| `--ui-map-park` | `a green mix` | Parks and woods. |
| `--ui-map-road` | `the raised surface` | Roads, major ones wider. |
| `--ui-map-label` | `the muted text` | Place names. |

### Routes and markers

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-map-route-color` | `the brand solid` | A route's line. |
| `--ui-map-route-width` | `3` | A route's line width, in viewBox units. |
| `--ui-map-marker-color` | `the brand solid` | The default marker's dot. |
| `--ui-map-progress` | `the `progress` prop` | How far along its route a marker sits, from 0 to 1. |
