maplibre-gl-basemap-control 0.13.0 → 0.14.0

package/README.md

@@ -9,6 +9,7 @@ A MapLibre GL JS control for searching and switching public basemaps. It keeps t
 
 - Search-first basemap picker inspired by QuickMapServices
 - 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
@@ -156,6 +157,7 @@ const control = new BasemapControl({
   mapboxAccessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
   protomapsApiKey: 'YOUR_PROTOMAPS_API_KEY',
   stadiaApiKey: 'YOUR_STADIA_MAPS_API_KEY',
+  tiandituApiKey: 'YOUR_TIANDITU_API_KEY',
 });
 ```
 
@@ -203,6 +205,61 @@ transparent overlays, so pair them with `allowMultiple: true` to stack them over
 > 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
@@ -302,6 +359,7 @@ API key and load straight from `https://styles.maptoolkit.org/{styleId}.json`:
 | `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) |
@@ -370,6 +428,7 @@ const control = new BasemapControl({
 - `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

package/dist/{BasemapControl-Cdg7HMeU.js → BasemapControl-CKgYscxI.js}

@@ -2,6 +2,7 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 const DEFAULT_BASEMAP_PROVIDERS = [
+  { id: "amap", name: "Amap", category: "Regional" },
   { id: "amazon", name: "Amazon Location", category: "General" },
   { id: "carto", name: "Carto", category: "General" },
   { id: "cyclosm", name: "CyclOSM", category: "Cycling" },
@@ -21,6 +22,8 @@ const DEFAULT_BASEMAP_PROVIDERS = [
   { id: "protomaps", name: "Protomaps", category: "Vector Styles" },
   { id: "stadia", name: "Stadia Maps", category: "General" },
   { id: "swisstopo", name: "Swiss Federal Geoportal", category: "Regional" },
+  { id: "tencent", name: "Tencent Maps", category: "Regional" },
+  { id: "tianditu", name: "Tianditu", category: "Regional" },
   { id: "tomtom", name: "TomTom", category: "Traffic" },
   { id: "topplusopen", name: "TopPlusOpen", category: "Regional" },
   { id: "usgs", name: "USGS", category: "United States" },
@@ -35,6 +38,7 @@ function rasterBasemap({
   attribution,
   tiles,
   maxzoom = 19,
+  scheme,
   tags = []
 }) {
   return {
@@ -49,7 +53,8 @@ function rasterBasemap({
       type: "raster",
       tiles,
       tileSize: 256,
-      maxzoom
+      maxzoom,
+      scheme
     },
     tags
   };
@@ -202,6 +207,35 @@ function stadiaRasterBasemap({
     tags: ["stadia", ...stamen ? ["stamen"] : [], ...tags]
   });
 }
+const TIANDITU_HOSTS = [0, 1, 2, 3, 4, 5, 6, 7];
+function tiandituRasterBasemap({
+  id,
+  name,
+  layer,
+  category,
+  description,
+  maxzoom = 18,
+  tags = []
+}) {
+  return rasterBasemap({
+    id,
+    name,
+    provider: "tianditu",
+    category,
+    description,
+    attribution: TIANDITU_ATTRIBUTION,
+    tiles: TIANDITU_HOSTS.map(
+      (host) => `https://t${host}.tianditu.gov.cn/DataServer?T=${layer}&x={x}&y={y}&l={z}&tk={api-key}`
+    ),
+    maxzoom,
+    tags: ["tianditu", "china", "天地图", ...tags]
+  });
+}
+function amapTiles(host, query) {
+  return [1, 2, 3, 4].map(
+    (index) => `https://${host}0${index}.is.autonavi.com/appmaptile?${query}&x={x}&y={y}&z={z}`
+  );
+}
 function sortProviders(providers) {
   return [...providers].sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -216,6 +250,10 @@ const STADIA_ATTRIBUTION = '&copy; <a href="https://stadiamaps.com/" target="_bl
 const STADIA_STAMEN_ATTRIBUTION = '&copy; <a href="https://stadiamaps.com/" target="_blank" rel="noopener">Stadia Maps</a> &copy; <a href="https://stamen.com/" target="_blank" rel="noopener">Stamen Design</a> &copy; <a href="https://openmaptiles.org/" target="_blank" rel="noopener">OpenMapTiles</a> &copy; OpenStreetMap contributors';
 const PROTOMAPS_ATTRIBUTION = '<a href="https://protomaps.com" target="_blank" rel="noopener">Protomaps</a> &copy; <a href="https://openstreetmap.org" target="_blank" rel="noopener">OpenStreetMap</a>';
 const OPENFREEMAP_ATTRIBUTION = "OpenFreeMap &copy; OpenMapTiles Data from OpenStreetMap";
+const TIANDITU_ATTRIBUTION = '&copy; <a href="https://www.tianditu.gov.cn" target="_blank" rel="noopener">天地图 Tianditu</a> (National Platform for Common Geospatial Information Services)';
+const AMAP_ATTRIBUTION = '&copy; <a href="https://www.amap.com" target="_blank" rel="noopener">高德地图 Amap</a>';
+const TENCENT_ATTRIBUTION = '&copy; <a href="https://map.qq.com" target="_blank" rel="noopener">腾讯地图 Tencent Maps</a>';
+const GCJ02_WARNING = "Tiles are in the GCJ-02 datum, so WGS84 data overlaid on them appears offset by roughly 100-700 m.";
 const TOMTOM_ATTRIBUTION = "&copy; TomTom";
 const HERE_ATTRIBUTION = "&copy; HERE";
 const GOOGLE_ATTRIBUTION = "&copy; Google";
@@ -1216,6 +1254,130 @@ const DEFAULT_BASEMAPS = [
     maxzoom: 18,
     tags: ["switzerland", "imagery"]
   }),
+  tiandituRasterBasemap({
+    id: "tianditu-vector",
+    name: "Tianditu Vector",
+    layer: "vec_w",
+    category: "Regional",
+    description: "China's official street map, reachable from mainland China. Published in CGCS2000, so WGS84 data overlays without a datum shift. Pair with Tianditu Vector Labels. Requires a free Tianditu API key.",
+    tags: ["vector", "street", "vec"]
+  }),
+  tiandituRasterBasemap({
+    id: "tianditu-vector-labels",
+    name: "Tianditu Vector Labels",
+    layer: "cva_w",
+    category: "Labels",
+    description: "Place name and road label overlay for Tianditu Vector. Requires a free Tianditu API key.",
+    tags: ["labels", "annotation", "overlay", "cva"]
+  }),
+  tiandituRasterBasemap({
+    id: "tianditu-imagery",
+    name: "Tianditu Imagery",
+    layer: "img_w",
+    category: "Imagery",
+    description: "China's official satellite imagery, reachable from mainland China. Pair with Tianditu Imagery Labels. Requires a free Tianditu API key.",
+    tags: ["imagery", "satellite", "img"]
+  }),
+  tiandituRasterBasemap({
+    id: "tianditu-imagery-labels",
+    name: "Tianditu Imagery Labels",
+    layer: "cia_w",
+    category: "Labels",
+    description: "Place name and road label overlay for Tianditu Imagery. Requires a free Tianditu API key.",
+    tags: ["labels", "annotation", "overlay", "cia"]
+  }),
+  tiandituRasterBasemap({
+    id: "tianditu-terrain",
+    name: "Tianditu Terrain",
+    layer: "ter_w",
+    category: "Terrain",
+    description: "China's official shaded relief terrain map. Pair with Tianditu Terrain Labels. Requires a free Tianditu API key.",
+    // The terrain pair is only published to zoom 14, unlike the vector and
+    // imagery layers, which reach 18.
+    maxzoom: 14,
+    tags: ["terrain", "relief", "hillshade", "ter"]
+  }),
+  tiandituRasterBasemap({
+    id: "tianditu-terrain-labels",
+    name: "Tianditu Terrain Labels",
+    layer: "cta_w",
+    category: "Labels",
+    description: "Place name label overlay for Tianditu Terrain. Requires a free Tianditu API key.",
+    maxzoom: 14,
+    tags: ["labels", "annotation", "overlay", "cta"]
+  }),
+  rasterBasemap({
+    id: "amap-street",
+    name: "Amap Street",
+    provider: "amap",
+    category: "Regional",
+    description: `Amap street map of China, reachable from mainland China. ${GCJ02_WARNING}`,
+    attribution: AMAP_ATTRIBUTION,
+    tiles: amapTiles("wprd", "lang=zh_cn&size=1&scl=1&style=7"),
+    tags: ["amap", "gaode", "高德", "china", "street", "gcj02"]
+  }),
+  rasterBasemap({
+    id: "amap-satellite",
+    name: "Amap Satellite",
+    provider: "amap",
+    category: "Imagery",
+    description: `Amap satellite imagery, reachable from mainland China. Pair with Amap Labels. ${GCJ02_WARNING}`,
+    attribution: AMAP_ATTRIBUTION,
+    tiles: amapTiles("webst", "style=6"),
+    // Past zoom 18 Amap returns a "no imagery" placeholder tile rather than a
+    // 404, so cap here and let MapLibre overzoom instead.
+    maxzoom: 18,
+    tags: ["amap", "gaode", "高德", "china", "satellite", "imagery", "gcj02"]
+  }),
+  rasterBasemap({
+    id: "amap-labels",
+    name: "Amap Labels",
+    provider: "amap",
+    category: "Labels",
+    description: `Transparent Amap road and label overlay, for use over Amap Satellite. ${GCJ02_WARNING}`,
+    attribution: AMAP_ATTRIBUTION,
+    tiles: amapTiles("webst", "style=8"),
+    tags: [
+      "amap",
+      "gaode",
+      "高德",
+      "china",
+      "labels",
+      "roads",
+      "overlay",
+      "gcj02"
+    ]
+  }),
+  rasterBasemap({
+    id: "tencent-street",
+    name: "Tencent Street",
+    provider: "tencent",
+    category: "Regional",
+    description: `Tencent street map of China, reachable from mainland China. ${GCJ02_WARNING}`,
+    attribution: TENCENT_ATTRIBUTION,
+    // Tencent numbers tile rows from the bottom, so the source is TMS rather
+    // than xyz; MapLibre flips `{y}` when `scheme` says so.
+    tiles: [0, 1, 2, 3].map(
+      (host) => `https://rt${host}.map.gtimg.com/tile?z={z}&x={x}&y={y}&styleid=1&scene=0`
+    ),
+    maxzoom: 18,
+    scheme: "tms",
+    tags: ["tencent", "qq", "腾讯", "china", "street", "gcj02"]
+  }),
+  rasterBasemap({
+    id: "tencent-dark",
+    name: "Tencent Dark",
+    provider: "tencent",
+    category: "Dark",
+    description: `Dark Tencent street map for high-contrast overlays, reachable from mainland China. ${GCJ02_WARNING}`,
+    attribution: TENCENT_ATTRIBUTION,
+    tiles: [0, 1, 2, 3].map(
+      (host) => `https://rt${host}.map.gtimg.com/tile?z={z}&x={x}&y={y}&styleid=4&scene=0`
+    ),
+    maxzoom: 18,
+    scheme: "tms",
+    tags: ["tencent", "qq", "腾讯", "china", "dark", "gcj02"]
+  }),
   rasterBasemap({
     id: "topplusopen-color",
     name: "TopPlusOpen Color",
@@ -1746,6 +1908,10 @@ const PROVIDER_CREDENTIAL_HELP = {
     url: "https://client.stadiamaps.com/signup/",
     label: "Get a Stadia Maps API key"
   },
+  tianditu: {
+    url: "https://console.tianditu.gov.cn/api/key",
+    label: "Get a Tianditu API key"
+  },
   tomtom: {
     url: "https://developer.tomtom.com/how-to-get-tomtom-api-key",
     label: "Get a TomTom API key"
@@ -1759,6 +1925,13 @@ const PROVIDER_CREDENTIAL_HELP = {
     label: "Get a Google Maps API key"
   }
 };
+const RASTER_KEY_LABELS = {
+  google: "Google Maps API key",
+  here: "HERE API key",
+  stadia: "Stadia Maps API key",
+  tianditu: "Tianditu API key",
+  tomtom: "TomTom API key"
+};
 const STYLE_AUTH_GRACE_MS = 2500;
 const MIN_PANEL_WIDTH = 240;
 const MIN_PANEL_HEIGHT = 200;
@@ -1817,6 +1990,7 @@ class BasemapControl {
     __publicField(this, "_mapboxAccessToken", "");
     __publicField(this, "_protomapsApiKey", "");
     __publicField(this, "_stadiaApiKey", "");
+    __publicField(this, "_tiandituApiKey", "");
     __publicField(this, "_tomtomApiKey", "");
     __publicField(this, "_hereApiKey", "");
     __publicField(this, "_googleMapsApiKey", "");
@@ -1881,6 +2055,7 @@ class BasemapControl {
     this._mapboxAccessToken = (options == null ? void 0 : options.mapboxAccessToken) ?? "";
     this._protomapsApiKey = (options == null ? void 0 : options.protomapsApiKey) ?? "";
     this._stadiaApiKey = (options == null ? void 0 : options.stadiaApiKey) ?? "";
+    this._tiandituApiKey = (options == null ? void 0 : options.tiandituApiKey) ?? "";
     this._tomtomApiKey = (options == null ? void 0 : options.tomtomApiKey) ?? "";
     this._hereApiKey = (options == null ? void 0 : options.hereApiKey) ?? "";
     this._googleMapsApiKey = (options == null ? void 0 : options.googleMapsApiKey) ?? "";
@@ -2024,6 +2199,12 @@ class BasemapControl {
     this._renderContent();
     this._emit({ type: "statechange", state: this.getState() });
   }
+  setTiandituApiKey(apiKey) {
+    this._tiandituApiKey = apiKey;
+    this._clearError();
+    this._renderContent();
+    this._emit({ type: "statechange", state: this.getState() });
+  }
   setTomTomApiKey(apiKey) {
     this._tomtomApiKey = apiKey;
     this._clearError();
@@ -2666,6 +2847,23 @@ class BasemapControl {
           }
         ]
       },
+      {
+        provider: "tianditu",
+        label: "Tianditu",
+        has: this._hasTiandituBasemaps(),
+        fields: [
+          {
+            className: "basemap-control-tianditu-key",
+            type: "password",
+            placeholder: "Tianditu API key",
+            ariaLabel: "Tianditu API key",
+            value: this._tiandituApiKey,
+            onInput: (value) => {
+              this._tiandituApiKey = value;
+            }
+          }
+        ]
+      },
       {
         provider: "tomtom",
         label: "TomTom",
@@ -3085,6 +3283,9 @@ class BasemapControl {
   _hasStadiaBasemaps() {
     return this._basemaps.some((basemap) => basemap.provider === "stadia");
   }
+  _hasTiandituBasemaps() {
+    return this._basemaps.some((basemap) => basemap.provider === "tianditu");
+  }
   _hasTomTomBasemaps() {
     return this._basemaps.some((basemap) => basemap.provider === "tomtom");
   }
@@ -3101,7 +3302,7 @@ class BasemapControl {
     );
   }
   _hasProviderSettings() {
-    return this._hasMapTilerBasemaps() || this._hasAmazonBasemaps() || this._hasMapboxBasemaps() || this._hasProtomapsBasemaps() || this._hasStadiaBasemaps() || this._hasTomTomBasemaps() || this._hasHereBasemaps() || this._hasGoogleApiKeyBasemaps();
+    return this._hasMapTilerBasemaps() || this._hasAmazonBasemaps() || this._hasMapboxBasemaps() || this._hasProtomapsBasemaps() || this._hasStadiaBasemaps() || this._hasTiandituBasemaps() || this._hasTomTomBasemaps() || this._hasHereBasemaps() || this._hasGoogleApiKeyBasemaps();
   }
   _resolveStyleUrl(basemap) {
     if (basemap.source.type !== "style" && basemap.source.type !== "vector-style") {
@@ -3361,6 +3562,7 @@ class BasemapControl {
     if (provider === "tomtom") return this._tomtomApiKey.trim();
     if (provider === "here") return this._hereApiKey.trim();
     if (provider === "stadia") return this._stadiaApiKey.trim();
+    if (provider === "tianditu") return this._tiandituApiKey.trim();
     if (provider === "google") return this._googleMapsApiKey.trim();
     return "";
   }
@@ -3388,7 +3590,7 @@ class BasemapControl {
     }
   }
   _missingRasterKeyError(provider) {
-    const label = provider === "tomtom" ? "TomTom API key" : provider === "here" ? "HERE API key" : provider === "stadia" ? "Stadia Maps API key" : provider === "google" ? "Google Maps API key" : "API key";
+    const label = RASTER_KEY_LABELS[provider] ?? "API key";
     const helpProvider = provider in PROVIDER_CREDENTIAL_HELP ? provider : "maptiler";
     return new MissingCredentialError(`Enter a ${label} before applying this layer.`, helpProvider);
   }
@@ -3624,4 +3826,4 @@ export {
   getBasemapCategories as g,
   resolveBasemapProviders as r
 };
-//# sourceMappingURL=BasemapControl-Cdg7HMeU.js.map
+//# sourceMappingURL=BasemapControl-CKgYscxI.js.map