maplibre-gl-basemap-control 0.12.0 → 0.14.0

package/README.md

@@ -8,7 +8,8 @@ A MapLibre GL JS control for searching and switching public basemaps. It keeps t
 ## Features
 
 - Search-first basemap picker inspired by QuickMapServices
-- Built-in catalog for common public basemaps, MapTiler styles, Amazon Location styles, and Mapbox styles
+- Built-in catalog for common public basemaps, MapTiler styles, Amazon Location styles, Mapbox styles, Maptoolkit styles, Protomaps styles, and Stadia Maps basemaps
+- Tianditu, Amap, and Tencent basemaps, served from inside mainland China
 - Stackable traffic overlays for TomTom, HERE, Mapbox, and Google
 - Custom basemap and provider definitions
 - MapLibre `IControl` implementation
@@ -138,11 +139,12 @@ The built-in catalog includes MapTiler styles such as Streets, Base, Dataviz, Ou
 Satellite Hybrid, Satellite Plain, Aquarelle, Backdrop, Landscape, Ocean, Toner, OpenStreetMap, and
 Winter. It also includes Amazon Location styles: Standard, Monochrome, Hybrid, and Satellite.
 Mapbox styles include Streets, Outdoors, Light, Dark, Satellite, Satellite Streets, Navigation Day,
-and Navigation Night.
+and Navigation Night. Protomaps styles include Light, Dark, White, Black, Grayscale, and Contrast.
 
-MapTiler and Amazon Location styles require API keys. Mapbox styles require an access token. Users
-can enter keys and tokens in the dedicated API keys view, opened from the key button in the panel
-header, or you can provide them when creating the control. When a basemap is selected before its key
+MapTiler, Amazon Location, and Protomaps styles require API keys. Mapbox styles require an access
+token. Users can enter keys and tokens in the dedicated API keys view, opened from the key button in
+the panel header, or you can provide them when creating the control. When a basemap is selected
+before its key
 is set, the control surfaces the error and the matching credential field inline, before any
 destructive style change, so the missing key can be entered and the basemap retried with Enter.
 
@@ -153,6 +155,9 @@ const control = new BasemapControl({
   amazonApiKey: 'YOUR_AMAZON_LOCATION_API_KEY',
   awsRegion: 'us-east-1',
   mapboxAccessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
+  protomapsApiKey: 'YOUR_PROTOMAPS_API_KEY',
+  stadiaApiKey: 'YOUR_STADIA_MAPS_API_KEY',
+  tiandituApiKey: 'YOUR_TIANDITU_API_KEY',
 });
 ```
 
@@ -174,6 +179,87 @@ Mapbox style URLs follow this form:
 https://api.mapbox.com/styles/v1/mapbox/{styleId}?access_token={api-key}
 ```
 
+Protomaps style URLs follow this form:
+
+```text
+https://api.protomaps.com/styles/v5/{styleId}/en.json?key={api-key}
+```
+
+### Stadia Maps and Stamen
+
+The catalog ships Stadia Maps' own styles (Alidade Smooth, Alidade Smooth Dark, Alidade Satellite,
+Outdoors, OSM Bright) and the Stadia x Stamen classics (Toner, Toner Lite, Toner Background, Toner
+Labels, Terrain, Terrain Background, Terrain Labels, Watercolor). Stadia has hosted the Stamen
+tilesets since 2023.
+
+These are raster tiles that take the key directly on each tile URL:
+
+```text
+https://tiles.stadiamaps.com/tiles/{slug}/{z}/{x}/{y}.png?api_key={api-key}
+```
+
+Alidade Satellite and Stamen Watercolor are served as `.jpg` instead. The `_labels` layers are
+transparent overlays, so pair them with `allowMultiple: true` to stack them over a base layer.
+
+> **Note.** Stadia also supports keyless access from allowlisted domains (localhost included), but
+> this control always sends `api_key`, so a key is required here. Set `stadiaApiKey` or enter it in
+> the panel's API keys view.
+
+### China Basemaps
+
+Most of the catalog is hosted outside mainland China with no presence inside it, so for users there
+OpenStreetMap, OpenFreeMap, Protomaps, Carto, Google, and Mapbox range from slow to unreachable. The
+catalog ships three providers that are served from inside China:
+
+| Basemap id | Provider | Datum | Credential |
+|------------|----------|-------|------------|
+| `tianditu-vector`, `tianditu-imagery`, `tianditu-terrain` and their `-labels` overlays | Tianditu (天地图) | CGCS2000 | `tiandituApiKey` |
+| `amap-street`, `amap-satellite`, `amap-labels` | Amap (高德地图) | GCJ-02 | none |
+| `tencent-street`, `tencent-dark` | Tencent Maps (腾讯地图) | GCJ-02 | none |
+
+They are searchable by their Chinese names as well as their English ones, so typing `天地图`, `高德`,
+or `腾讯` into the panel's filter finds them.
+
+> **The datum matters more than the speed.** Chinese law requires public map services to publish in
+> GCJ-02, an offset datum that displaces features by roughly 100-700 m from WGS84. Neither this
+> control nor MapLibre applies the shift, so WGS84 data laid over Amap or Tencent will visibly
+> misalign. **Tianditu is the exception**: it publishes in CGCS2000, which is close enough to WGS84
+> for web mapping, so ordinary data overlays correctly. Prefer Tianditu whenever you are also
+> rendering your own data; reach for Amap or Tencent when the basemap is the whole point, or convert
+> your data to GCJ-02 first.
+
+Tianditu is China's official National Platform for Common Geospatial Information Services. Register
+a free key at [console.tianditu.gov.cn](https://console.tianditu.gov.cn/api/key), then set
+`tiandituApiKey` or enter it in the panel's API keys view. Its layers ride the `DataServer`
+endpoint, the xyz-shaped form of its WMTS services:
+
+```text
+https://t{0-7}.tianditu.gov.cn/DataServer?T={layer}&x={x}&y={y}&l={z}&tk={api-key}
+```
+
+Tianditu splits every basemap from its labels, so the `-labels` overlays are separate transparent
+layers. Pair them with `allowMultiple: true` to stack them over their base:
+
+```typescript
+const control = new BasemapControl({
+  allowMultiple: true,
+  tiandituApiKey: 'YOUR_TIANDITU_API_KEY',
+  defaultBasemapId: 'tianditu-vector',
+});
+await control.addBasemap('tianditu-vector-labels');
+```
+
+The same applies to `amap-labels`, a transparent roads-and-labels overlay meant to sit on top of
+`amap-satellite`. Note that `tianditu-terrain` and `tianditu-terrain-labels` are only published to
+zoom 14, where the vector and imagery layers reach 18, and Amap serves a "no imagery" placeholder
+rather than a 404 past zoom 18, so `amap-satellite` caps there and lets MapLibre overzoom.
+
+> **Terms of use.** Tianditu's key-based access is the sanctioned route and the one to build on. The
+> Amap and Tencent tile endpoints are widely used but are not documented public APIs, and carry the
+> same caveat as the keyless Google tiles below: fine for development and demos, but the operators
+> may rate-limit, change, or block them at any time. Obtain a commercial key from the provider before
+> shipping either one.
+
 ### Traffic Overlays
 
 The catalog ships real-time traffic overlays in the `Traffic` category. They are
@@ -214,10 +300,18 @@ key must have the Map Tiles API enabled.
 > few minutes to propagate). Make sure billing is enabled on the project too.
 
 The same `googleMapsApiKey` also upgrades the base Google basemaps
-(`google-maps`, `google-satellite`, `google-terrain`, `google-hybrid`). When a
-key is set they load from the authorized Map Tiles API (via a tile session, like
-Google Traffic); without a key they fall back to keyless `mt1.google.com` xyz
-tiles so they keep working out of the box.
+(`google-maps`, `google-satellite`, `google-terrain`, `google-hybrid`). By
+default these use the public keyless `mt1.google.com` xyz tiles, so they work out
+of the box; when a key is set they load from the authorized Map Tiles API instead
+(via a tile session, like Google Traffic).
+
+In the catalog definition this is the split between `source.tiles` and
+`source.sessionTiles`: `tiles` always holds the public keyless template, so
+reading `source.tiles` without a key gives a directly usable URL, while
+`sessionTiles` holds the Map Tiles API template (with its `{session}` and
+`{api-key}` placeholders) that is only used once a key is configured. Basemaps
+that cannot work keylessly, such as `google-traffic`, have no `sessionTiles` and
+keep the session template in `tiles`.
 
 > **Licensing caveat.** The keyless `mt1.google.com` tiles are Google Maps'
 > internal endpoints. They are **not** covered by any public or open license, and
@@ -228,6 +322,26 @@ tiles so they keep working out of the box.
 > so these basemaps use the authorized [Map Tiles API](https://developers.google.com/maps/documentation/tile)
 > (which requires the Map Tiles API enabled and billing on your project).
 
+## Maptoolkit Styles
+
+The catalog ships the seven [Maptoolkit](https://www.maptoolkit.org) vector styles. They need no
+API key and load straight from `https://styles.maptoolkit.org/{styleId}.json`:
+
+| Basemap id | Style | Category |
+|------------|-------|----------|
+| `maptoolkit-summer` | `summer` | Outdoor |
+| `maptoolkit-light` | `light` | Light |
+| `maptoolkit-hiking` | `hiking` | Outdoor |
+| `maptoolkit-cycling` | `cycling` | Cycling |
+| `maptoolkit-winter` | `winter` | Outdoor |
+| `maptoolkit-dark` | `dark` | Dark |
+| `maptoolkit-street` | `street` | Street |
+
+> **Attribution.** The Maptoolkit style JSONs carry no `attribution` on their sources, so the catalog
+> supplies the required "© Maptoolkit © OSM" credit links. Maptoolkit additionally requires the
+> Maptoolkit logo (at least 24px tall) to be visible and unobstructed on the map; add it to your own
+> UI, since the control cannot render it for you.
+
 ## API
 
 ### BasemapControl Options
@@ -243,6 +357,9 @@ tiles so they keep working out of the box.
 | `amazonApiKey` | `string` | `undefined` | Initial Amazon Location API key for built-in Amazon styles |
 | `awsRegion` | `string` | `'us-east-1'` | AWS region for built-in Amazon Location styles |
 | `mapboxAccessToken` | `string` | `undefined` | Initial Mapbox access token for built-in Mapbox styles and the Mapbox Traffic overlay |
+| `protomapsApiKey` | `string` | `undefined` | Initial Protomaps API key for built-in Protomaps styles |
+| `stadiaApiKey` | `string` | `undefined` | Initial Stadia Maps API key for built-in Stadia and Stadia x Stamen basemaps |
+| `tiandituApiKey` | `string` | `undefined` | Initial Tianditu API key (`tk`) for the built-in Tianditu basemaps |
 | `tomtomApiKey` | `string` | `undefined` | Initial TomTom API key for the TomTom Traffic overlays |
 | `hereApiKey` | `string` | `undefined` | Initial HERE API key for the HERE Traffic overlay |
 | `googleMapsApiKey` | `string` | `undefined` | Initial Google Maps API key (Map Tiles API) for the Google Traffic overlay and the base Google Maps/Satellite/Terrain/Hybrid basemaps (which fall back to keyless tiles without a key) |
@@ -309,6 +426,9 @@ const control = new BasemapControl({
 - `setMapTilerApiKey(apiKey)` - Set or update the MapTiler API key used by MapTiler styles
 - `setAmazonCredentials(apiKey, awsRegion)` - Set or update Amazon Location credentials
 - `setMapboxAccessToken(accessToken)` - Set or update the Mapbox access token
+- `setProtomapsApiKey(apiKey)` - Set or update the Protomaps API key used by Protomaps styles
+- `setStadiaApiKey(apiKey)` - Set or update the Stadia Maps API key used by Stadia basemaps
+- `setTiandituApiKey(apiKey)` - Set or update the Tianditu API key used by Tianditu basemaps
 - `setTomTomApiKey(apiKey)` - Set or update the TomTom API key used by TomTom Traffic overlays
 - `setHereApiKey(apiKey)` - Set or update the HERE API key used by the HERE Traffic overlay
 - `setGoogleMapsApiKey(apiKey)` - Set or update the Google Maps API key used by the Google Traffic overlay and the base Google basemaps