maplibre-gl-basemap-control 0.13.0 → 0.14.3

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
@@ -151,11 +152,13 @@ destructive style change, so the missing key can be entered and the basemap retr
 const control = new BasemapControl({
   defaultBasemapId: 'maptiler-streets',
   mapTilerApiKey: 'YOUR_MAPTILER_API_KEY',
+  cartoApiKey: 'YOUR_CARTO_API_KEY',
   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',
 });
 ```
 
@@ -203,6 +206,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
@@ -297,11 +355,13 @@ API key and load straight from `https://styles.maptoolkit.org/{styleId}.json`:
 | `panelWidth` | `number` | `340` | Floating panel width in pixels |
 | `className` | `string` | `''` | Extra class for the control button container |
 | `mapTilerApiKey` | `string` | `undefined` | Initial MapTiler API key for built-in MapTiler styles |
+| `cartoApiKey` | `string` | `undefined` | Initial CARTO API key for built-in CARTO raster basemaps |
 | `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) |
@@ -366,10 +426,12 @@ const control = new BasemapControl({
 - `toggleBasemap(id)` - Add the raster basemap if inactive, otherwise remove it
 - `isBasemapActive(id)` - Whether the basemap is currently active
 - `setMapTilerApiKey(apiKey)` - Set or update the MapTiler API key used by MapTiler styles
+- `setCartoApiKey(apiKey)` - Set or update the CARTO API key used by CARTO raster basemaps
 - `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

package/dist/{BasemapControl-Cdg7HMeU.js → BasemapControl-CSw9YZ4S.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";
@@ -623,10 +661,10 @@ const DEFAULT_BASEMAPS = [
     description: "Light basemap for data overlays.",
     attribution: CARTO_ATTRIBUTION,
     tiles: [
-      "https://a.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
-      "https://b.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
-      "https://c.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
-      "https://d.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png"
+      "https://a.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png?key={api-key}",
+      "https://b.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png?key={api-key}",
+      "https://c.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png?key={api-key}",
+      "https://d.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png?key={api-key}"
     ],
     maxzoom: 20,
     tags: ["carto", "light", "positron"]
@@ -638,7 +676,7 @@ const DEFAULT_BASEMAPS = [
     category: "Light",
     description: "Light basemap without labels.",
     attribution: CARTO_ATTRIBUTION,
-    tiles: ["https://a.basemaps.cartocdn.com/light_nolabels/{z}/{x}/{y}.png"],
+    tiles: ["https://a.basemaps.cartocdn.com/light_nolabels/{z}/{x}/{y}.png?key={api-key}"],
     maxzoom: 20,
     tags: ["carto", "light", "no labels"]
   }),
@@ -650,7 +688,7 @@ const DEFAULT_BASEMAPS = [
     description: "Carto Positron labels layer.",
     attribution: CARTO_ATTRIBUTION,
     tiles: [
-      "https://a.basemaps.cartocdn.com/light_only_labels/{z}/{x}/{y}.png"
+      "https://a.basemaps.cartocdn.com/light_only_labels/{z}/{x}/{y}.png?key={api-key}"
     ],
     maxzoom: 20,
     tags: ["carto", "labels"]
@@ -663,10 +701,10 @@ const DEFAULT_BASEMAPS = [
     description: "Dark basemap for high-contrast overlays.",
     attribution: CARTO_ATTRIBUTION,
     tiles: [
-      "https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
-      "https://b.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
-      "https://c.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png",
-      "https://d.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png"
+      "https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png?key={api-key}",
+      "https://b.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png?key={api-key}",
+      "https://c.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png?key={api-key}",
+      "https://d.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png?key={api-key}"
     ],
     maxzoom: 20,
     tags: ["carto", "dark", "matter"]
@@ -678,7 +716,7 @@ const DEFAULT_BASEMAPS = [
     category: "Dark",
     description: "Dark basemap without labels.",
     attribution: CARTO_ATTRIBUTION,
-    tiles: ["https://a.basemaps.cartocdn.com/dark_nolabels/{z}/{x}/{y}.png"],
+    tiles: ["https://a.basemaps.cartocdn.com/dark_nolabels/{z}/{x}/{y}.png?key={api-key}"],
     maxzoom: 20,
     tags: ["carto", "dark", "no labels"]
   }),
@@ -689,7 +727,7 @@ const DEFAULT_BASEMAPS = [
     category: "Labels",
     description: "Carto Dark Matter labels layer.",
     attribution: CARTO_ATTRIBUTION,
-    tiles: ["https://a.basemaps.cartocdn.com/dark_only_labels/{z}/{x}/{y}.png"],
+    tiles: ["https://a.basemaps.cartocdn.com/dark_only_labels/{z}/{x}/{y}.png?key={api-key}"],
     maxzoom: 20,
     tags: ["carto", "dark", "labels"]
   }),
@@ -701,10 +739,10 @@ const DEFAULT_BASEMAPS = [
     description: "Detailed street basemap with subtle styling.",
     attribution: CARTO_ATTRIBUTION,
     tiles: [
-      "https://a.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png",
-      "https://b.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png",
-      "https://c.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png",
-      "https://d.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png"
+      "https://a.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key={api-key}",
+      "https://b.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key={api-key}",
+      "https://c.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key={api-key}",
+      "https://d.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}.png?key={api-key}"
     ],
     maxzoom: 20,
     tags: ["carto", "street", "voyager"]
@@ -717,7 +755,7 @@ const DEFAULT_BASEMAPS = [
     description: "Carto Voyager without labels.",
     attribution: CARTO_ATTRIBUTION,
     tiles: [
-      "https://a.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png"
+      "https://a.basemaps.cartocdn.com/rastertiles/voyager_nolabels/{z}/{x}/{y}.png?key={api-key}"
     ],
     maxzoom: 20,
     tags: ["carto", "voyager", "no labels"]
@@ -730,7 +768,7 @@ const DEFAULT_BASEMAPS = [
     description: "Carto Voyager labels layer.",
     attribution: CARTO_ATTRIBUTION,
     tiles: [
-      "https://a.basemaps.cartocdn.com/rastertiles/voyager_only_labels/{z}/{x}/{y}.png"
+      "https://a.basemaps.cartocdn.com/rastertiles/voyager_only_labels/{z}/{x}/{y}.png?key={api-key}"
     ],
     maxzoom: 20,
     tags: ["carto", "voyager", "labels"]
@@ -743,7 +781,7 @@ const DEFAULT_BASEMAPS = [
     description: "Carto Voyager labels-under variant.",
     attribution: CARTO_ATTRIBUTION,
     tiles: [
-      "https://a.basemaps.cartocdn.com/rastertiles/voyager_labels_under/{z}/{x}/{y}.png"
+      "https://a.basemaps.cartocdn.com/rastertiles/voyager_labels_under/{z}/{x}/{y}.png?key={api-key}"
     ],
     maxzoom: 20,
     tags: ["carto", "voyager", "labels"]
@@ -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",
@@ -1726,6 +1888,10 @@ const MAPTILER_API_KEY_QUERY = "?key";
 const MAPTILER_API_KEY_EMPTY_QUERY = "?key=";
 const AWS_REGION_PLACEHOLDER = "{aws-region}";
 const PROVIDER_CREDENTIAL_HELP = {
+  carto: {
+    url: "https://carto.com/basemaps/apikey/",
+    label: "Get a CARTO API key"
+  },
   amazon: {
     url: "https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html",
     label: "Get an Amazon API key"
@@ -1746,6 +1912,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 +1929,14 @@ const PROVIDER_CREDENTIAL_HELP = {
     label: "Get a Google Maps API key"
   }
 };
+const RASTER_KEY_LABELS = {
+  carto: "CARTO API key",
+  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;
@@ -1812,11 +1990,13 @@ class BasemapControl {
     // stacked raster overlay so each can be added or removed independently.
     __publicField(this, "_managedRasters", new globalThis.Map());
     __publicField(this, "_mapTilerApiKey", "");
+    __publicField(this, "_cartoApiKey", "");
     __publicField(this, "_amazonApiKey", "");
     __publicField(this, "_awsRegion", "");
     __publicField(this, "_mapboxAccessToken", "");
     __publicField(this, "_protomapsApiKey", "");
     __publicField(this, "_stadiaApiKey", "");
+    __publicField(this, "_tiandituApiKey", "");
     __publicField(this, "_tomtomApiKey", "");
     __publicField(this, "_hereApiKey", "");
     __publicField(this, "_googleMapsApiKey", "");
@@ -1876,11 +2056,13 @@ class BasemapControl {
     });
     this._options = { ...DEFAULT_OPTIONS, ...options };
     this._mapTilerApiKey = (options == null ? void 0 : options.mapTilerApiKey) ?? "";
+    this._cartoApiKey = (options == null ? void 0 : options.cartoApiKey) ?? "";
     this._amazonApiKey = (options == null ? void 0 : options.amazonApiKey) ?? "";
     this._awsRegion = (options == null ? void 0 : options.awsRegion) ?? "us-east-1";
     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) ?? "";
@@ -1999,6 +2181,12 @@ class BasemapControl {
     this._renderContent();
     this._emit({ type: "statechange", state: this.getState() });
   }
+  setCartoApiKey(apiKey) {
+    this._cartoApiKey = apiKey;
+    this._clearError();
+    this._renderContent();
+    this._emit({ type: "statechange", state: this.getState() });
+  }
   setAmazonCredentials(apiKey, awsRegion = this._awsRegion) {
     this._amazonApiKey = apiKey;
     this._awsRegion = awsRegion;
@@ -2024,6 +2212,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();
@@ -2136,12 +2330,16 @@ class BasemapControl {
       let resolvedStyleUrl;
       if (isOverlay) {
         await this._waitForStyleReady();
+        const resolvedRasterTiles = basemap.source.type === "raster" ? await this._resolveRasterTiles(basemap) : void 0;
+        if (basemap.source.type === "vector-overlay") {
+          this._resolveVectorOverlaySource(basemap, basemap.source);
+        }
         if (effectiveMode === "replace") {
           this._removeManagedBasemap();
         } else {
           this._removeManagedRaster(basemap.id);
         }
-        managedRaster = await this._addOverlay(basemap);
+        managedRaster = await this._addOverlay(basemap, resolvedRasterTiles);
       } else {
         const styleUrl = this._resolveStyleUrl(basemap);
         resolvedStyleUrl = styleUrl;
@@ -2598,6 +2796,23 @@ class BasemapControl {
   // missing-credential error, so the two never drift (#837).
   _providerFieldDefs() {
     return [
+      {
+        provider: "carto",
+        label: "CARTO",
+        has: this._hasCartoBasemaps(),
+        fields: [
+          {
+            className: "basemap-control-carto-key",
+            type: "password",
+            placeholder: "CARTO API key",
+            ariaLabel: "CARTO API key",
+            value: this._cartoApiKey,
+            onInput: (value) => {
+              this._cartoApiKey = value;
+            }
+          }
+        ]
+      },
       {
         provider: "maptiler",
         label: "MapTiler",
@@ -2666,6 +2881,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",
@@ -3082,9 +3314,15 @@ class BasemapControl {
   _hasProtomapsBasemaps() {
     return this._basemaps.some((basemap) => basemap.provider === "protomaps");
   }
+  _hasCartoBasemaps() {
+    return this._basemaps.some((basemap) => basemap.provider === "carto");
+  }
   _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 +3339,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._hasCartoBasemaps() || 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") {
@@ -3248,15 +3486,15 @@ class BasemapControl {
   }
   // Add a stackable overlay (raster tiles or a vector overlay) to the map,
   // resolving any provider credentials first.
-  async _addOverlay(basemap) {
+  async _addOverlay(basemap, resolvedRasterTiles) {
     if (basemap.source.type === "vector-overlay") {
       return this._addVectorOverlay(basemap, basemap.source);
     }
-    return this._addRasterBasemap(basemap);
+    return this._addRasterBasemap(basemap, resolvedRasterTiles);
   }
-  async _addRasterBasemap(basemap) {
+  async _addRasterBasemap(basemap, resolvedTiles) {
     if (!this._map || basemap.source.type !== "raster") return void 0;
-    const tiles = await this._resolveRasterTiles(basemap);
+    const tiles = resolvedTiles ?? await this._resolveRasterTiles(basemap);
     const sourceId = `${CONTROL_SOURCE_PREFIX}-${basemap.id}`;
     const layerId = [CONTROL_LAYER_PREFIX, basemap.id].filter(Boolean).join("-");
     const beforeId = this._getBasemapInsertBeforeId();
@@ -3358,9 +3596,11 @@ class BasemapControl {
     return tiles.map((tile) => tile.split(API_KEY_PLACEHOLDER).join(encoded));
   }
   _rasterApiKeyFor(provider) {
+    if (provider === "carto") return this._cartoApiKey.trim();
     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 +3628,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 +3864,4 @@ export {
   getBasemapCategories as g,
   resolveBasemapProviders as r
 };
-//# sourceMappingURL=BasemapControl-Cdg7HMeU.js.map
+//# sourceMappingURL=BasemapControl-CSw9YZ4S.js.map