# GeoMap

> A geographic map that renders on the server: real longitude and latitude projected with Web Mercator onto a stage, a vector basemap as SVG, markers as links or buttons that cluster when close, popups, routes and zoom links that work without script; an island makes it draggable.

```ts
import { GeoMap } from "@sdxc/ui/map";
```

The map stage: a region at the full size of its parent (20rem tall at least) that draws the
basemap as SVG, writes place names, clusters close markers into bubbles and shows the
controls, then hands the stage to the island, which mounts MapLibre in it when WebGL works.

## Examples

```tsx
<GeoMap id="stays-map" label="Stays in Lisbon" center={[-9.14, 38.72]} zoom={12} labels={labels} navigation={{ href: (view) => `?zoom=${view.zoom}&center=${view.center}` }}>
	<GeoMap.Marker at={[-9.15, 38.71]} label="$182" href="/stays/1" mapKey="1" />
</GeoMap>
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `id` | `string` | The stage's id, which the island finds it by. |
| `label` | `string` | The map's accessible name, such as "Stays in Lisbon". |
| `center` | `LngLat` | The point at the middle of the stage. |
| `zoom` | `number` |  |
| `minZoom?` | `number` |  |
| `maxZoom?` | `number` |  |
| `basemap?` | `Basemap` | What the map is drawn on: a MapLibre style pair, or your own GeoJSON. |
| `controls?` | `Control[]` |  |
| `navigation?` | `Navigation` | Turns zoom controls and clusters into links that work without script. |
| `labels` | `Labels` |  |
| `clusterRadius?` | `number` | Distance in pixels under which markers gather into one bubble. |
| `viewport?` | `Pixel` | Stage size in pixels assumed on the server for the bounds a search area submits. |
| `workerUrl?` | `string` | Where the island loads MapLibre's worker from, such as a bundler's `?url` import. |
| `children?` | `RemixNode` | GeoMap.Marker, GeoMap.Route and GeoMap.Area elements. |

Also accepts everything in `Omit<TagProps<"div">, "children" | "id">`.


### GeoMap.Marker

One marker: a pill whose tail tips onto its point, as a link with `href` or a button otherwise.

| Prop | Type | Description |
| --- | --- | --- |
| `mix?` | `TagProps<"span">["mix"]` | Mixins for the marker, which renders as either a link or a button. |
| `at` | `LngLat` |  |
| `label` | `RemixNode` | The pill's content, such as a price; with text it names the marker. |
| `href?` | `string` | Renders the marker as a link; a popup then opens on hover and focus. |
| `highlighted?` | `boolean` | Lights the marker as if pointed at, such as while its listing is hovered. |
| `current?` | `boolean` | Marks the selected marker: inverted colors, drawn above the rest, never clustered. |
| `tone?` | `"brand" \| "neutral"` |  |
| `mapKey?` | `string` | Record key shared with a listing row, linked through `mapLink`. |
| `children?` | `RemixNode` | A GeoMap.Popup. |

Also accepts everything in `Omit<TagProps<"button">, "children" | "mix">`.


### GeoMap.Popup

A card a marker opens, anchored above its pin with CSS anchor positioning and flipped below when the top has no room.

| Prop | Type | Description |
| --- | --- | --- |
| `children?` | `RemixNode` |  |

Also accepts everything in `Omit<TagProps<"div">, "id" | "popover" | "style">`.


### GeoMap.Route

Draws a route along real coordinates: a light casing, the whole line dashed and the travelled share solid on top.

| Prop | Type | Description |
| --- | --- | --- |
| `path` | `LngLat[]` |  |
| `progress?` | `number` | Share of the route travelled, from 0 to 1, drawn solid; the rest is dashed. |
| `children?` | `RemixNode` | GeoMap.RouteMarker elements. |

Also accepts everything in `Omit<TagProps<"svg">, "children" | "viewBox">`.


### GeoMap.RouteMarker

Places a glyph along its route with CSS motion paths.

| Prop | Type | Description |
| --- | --- | --- |
| `at?` | `"progress" \| "start" \| "end"` | `progress` follows the route's progress and the live `--ui-map-progress` property; a number is a fixed share. |
| `children?` | `RemixNode` | SVG glyph centred on the origin; a dot with a halo when omitted. |

Also accepts everything in `Omit<TagProps<"g">, "children" | "style">`.


### GeoMap.Area

A "Search this area" button for a search form: hidden fields carry the bounds, middle and zoom the page was drawn at, and once the visitor pans or zooms, the island rewrites them and reveals the button, which submits the form named by `form`.

| Prop | Type | Description |
| --- | --- | --- |
| `form` | `string` | The id of the form the fields and the button belong to. |
| `label` | `RemixNode` | The button's content, such as "Search this area". |
| `name?` | `string` | Field receiving `west,south,east,north`. |
| `centerName?` | `string` | Field receiving `longitude,latitude` of the middle. |
| `zoomName?` | `string` | Field receiving the zoom. |

Also accepts everything in `Omit<TagProps<"button">, "children" | "form" | "type">`.


## Types

| Name | Values | What it decides |
| --- | --- | --- |
| `Control` | `"zoom" \| "reset" \| "locate" \| "fullscreen"` | A control the map can show in its top corner. |
