# XWUIMap

Multi-provider map on the in-house engine. **No third-party map library and no CDN** - Leaflet and its five plugins were removed on 2026-08-30 and everything below now ships in the bundle.

Supports OSM / Esri / Wikimedia / CartoDB / OpenTopoMap / OpenWeather / Yandex / Google / Bing / SPL (and any custom tile URL) as TileProviders, composes them into named Themes (base + overlay + reference layers), supports custom CRS (Yandex EPSG:3395 ellipsoidal Mercator built in), PBF vector tiles, marker clustering, heatmaps, declarative shape rendering (marker / circle / polyline / rectangle / polygon), and an opt-in drawing API.

## Production notes

- **`showLoadingSkeleton`** - loading overlay during bootstrap (default true). Failures show a Retry button via `retryBootstrap()`.
- **`config.xwgis`** - set `true` or `{ enabled: true }` to delegate providers, geocoding, playback, live tracking, and track replay to `@exonware/xwgis`.
- **Live tracking** - `connectTracking(wsUrl, { apiBaseUrl })` + `subscribeTracking(assetId)` for WebSocket feeds; `fetchTrackHistory(assetId, from, to)` for REST history; `fetchAndReplayTrackHistory(...)` or `startTrackReplay(track)` for playback.
- **Search providers** - `nominatim`, `mapbox`, `pelias`, `google` (`googleApiKey`), `here` (`hereApiKey`), `esri` (`esriApiKey`), `maptiler` (`maptilerApiKey`), `bing` (`bingApiKey`). Set `config.xwgis.apiBaseUrl` for xwgis-api track history.
- **`whenReady()`** - bootstrap is async (it waits for the container to have a real size); await `map.whenReady()` before calling map APIs.
- **`getMapInstance()`** - returns the `XWUIGISMapEngine`, not a Leaflet `Map`. See `components/_shared/map/engine.ts`.
- **`mapOptions`** was a Leaflet options passthrough and is **removed** - it could no longer do anything.
- **`config.splAccessToken`** - overrides the built-in public ATLAS token. Only needed with your own ATLAS account.
- **`config.enableRestrictedProviders`** - Google and Bing ship **on by default**. Set `false` to build a strictly first-party-licensed provider set; these are unofficial tile endpoints and licensing them is the deploying site's obligation.
- **`config.features.search.nominatimUrl`** - use a self-hosted Nominatim instance in production; the public OSM endpoint has strict rate limits.
- **Form / non-map reverse geocode** - use [`src/utils/geocode.ts`](../../../utils/geocode.ts) (`locateCity` / `reverseGeocode` / `nearestCity`). Same Nominatim family + dedupe cache as map search; products can autofill city selects without mounting a map.
- **Popups** - `marker.popup` and `shape.popup` are bound as raw HTML; only pass trusted content.
- **CRS** - the map CRS is fixed at init from the initial theme. Themes requiring a different CRS need a new component instance.

## Basic Usage

Minimal XWUIMap markup - single custom element with marker data via attribute.

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: Minimal XWUIMap markup - single custom element with marker data via attribute.
```

## estately.com - Real-estate marketplace

Saudi (Riyadh) property browser with clustered markers, filter chips, price heatmap toggle, and bilingual EN/AR labels with on-the-fly RTL switch.

```example
file: examples/Estately.ts
html: examples/Estately.html
title: estately.com - Real-estate marketplace
description: Saudi (Riyadh) property browser with clustered markers, filter chips, price heatmap toggle, and bilingual EN/AR labels with on-the-fly RTL switch.
```

```api
```