maplibre-gl-basemap-control 0.10.0 → 0.12.0

package/README.md

@@ -213,6 +213,21 @@ key must have the Map Tiles API enabled.
 > key" or add **Map Tiles API** to the allowed list, then save (changes can take a
 > 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.
+
+> **Licensing caveat.** The keyless `mt1.google.com` tiles are Google Maps'
+> internal endpoints. They are **not** covered by any public or open license, and
+> accessing Google map content outside an official Google Maps Platform API
+> violates the [Google Maps Platform Terms of Service](https://cloud.google.com/maps-platform/terms).
+> They are convenient for local development and demos, but Google may rate-limit,
+> change, or block them at any time. For production use, set a `googleMapsApiKey`
+> 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).
+
 ## API
 
 ### BasemapControl Options
@@ -230,7 +245,7 @@ key must have the Map Tiles API enabled.
 | `mapboxAccessToken` | `string` | `undefined` | Initial Mapbox access token for built-in Mapbox styles and the Mapbox Traffic overlay |
 | `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 |
+| `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) |
 | `basemaps` | `BasemapDefinition[]` | `[]` | Custom basemaps to add or use |
 | `providers` | `BasemapProvider[]` | `[]` | Custom provider labels |
 | `includeDefaultBasemaps` | `boolean` | `true` | Include the built-in public catalog |
@@ -296,7 +311,7 @@ const control = new BasemapControl({
 - `setMapboxAccessToken(accessToken)` - Set or update the Mapbox access token
 - `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
+- `setGoogleMapsApiKey(apiKey)` - Set or update the Google Maps API key used by the Google Traffic overlay and the base Google basemaps
 - `getActiveBasemap()` - Return the most recently selected basemap definition
 - `getActiveBasemaps()` - Return all currently active basemap definitions
 - `getBasemaps()` - Return the catalog

package/dist/{BasemapControl-DXJHjc6Z.cjs → BasemapControl-BbsxylnF.cjs}

@@ -151,8 +151,74 @@ const OPENFREEMAP_ATTRIBUTION = "OpenFreeMap © OpenMapTiles Data from OpenS
 const TOMTOM_ATTRIBUTION = "© TomTom";
 const HERE_ATTRIBUTION = "© HERE";
 const GOOGLE_ATTRIBUTION = "© Google";
-const EOX_S2CLOUDLESS_ATTRIBUTION = 'Sentinel-2 cloudless <a href="https://cloudless.eox.at" target="_blank" rel="noopener">EOxCloudless</a> by EOX IT Services GmbH (Contains modified Copernicus Sentinel data 2025)';
+const GOOGLE_2DTILES_URL = "https://tile.googleapis.com/v1/2dtiles/{z}/{x}/{y}?session={session}&key={api-key}";
+function googleRasterBasemap({
+  id,
+  name,
+  category,
+  description,
+  fallbackLyrs,
+  session,
+  tags
+}) {
+  return {
+    id,
+    name,
+    provider: "google",
+    type: "raster",
+    category,
+    description,
+    attribution: GOOGLE_ATTRIBUTION,
+    source: {
+      type: "raster",
+      tiles: [GOOGLE_2DTILES_URL],
+      fallbackTiles: [
+        `https://mt1.google.com/vt/lyrs=${fallbackLyrs}&x={x}&y={y}&z={z}`
+      ],
+      tileSize: 256,
+      maxzoom: 20,
+      googleSession: session
+    },
+    tags
+  };
+}
+const eoxS2CloudlessAttribution = (year) => `Sentinel-2 cloudless <a href="https://cloudless.eox.at" target="_blank" rel="noopener">EOxCloudless</a> by EOX IT Services GmbH (Contains modified Copernicus Sentinel data ${year})`;
+const EOX_S2CLOUDLESS_YEARS = [
+  2018,
+  2019,
+  2020,
+  2021,
+  2022,
+  2023,
+  2024,
+  2025
+];
+function eoxS2CloudlessBasemap(year) {
+  return rasterBasemap({
+    id: `eox-s2cloudless-${year}`,
+    name: `EOX Sentinel-2 cloudless ${year}`,
+    provider: "eox",
+    category: "Imagery",
+    description: `Cloudless Sentinel-2 satellite mosaic for ${year} (non-commercial use).`,
+    attribution: eoxS2CloudlessAttribution(year),
+    tiles: [
+      `https://tiles.maps.eox.at/wmts/1.0.0/s2cloudless-${year}_3857/default/GoogleMapsCompatible/{z}/{y}/{x}.jpg`
+    ],
+    maxzoom: 16,
+    tags: [
+      "eox",
+      "sentinel",
+      "satellite",
+      "imagery",
+      "cloudless",
+      "copernicus",
+      String(year)
+    ]
+  });
+}
 const EOX_TERRAIN_LIGHT_ATTRIBUTION = 'Terrain Light <a href="https://maps.eox.at" target="_blank" rel="noopener">EOX</a> (Data &copy; OpenStreetMap contributors and others, Rendering &copy; EOX)';
+const EOX_TERRAIN_ATTRIBUTION = 'Terrain <a href="https://maps.eox.at" target="_blank" rel="noopener">EOX</a> (Data &copy; OpenStreetMap contributors and others, Rendering &copy; EOX)';
+const EOX_OVERLAY_ATTRIBUTION = 'Overlay <a href="https://maps.eox.at" target="_blank" rel="noopener">EOX</a> (Data &copy; OpenStreetMap contributors and others, Rendering &copy; EOX)';
 const MAPBOX_TRAFFIC_CONGESTION_COLORS = [
   "match",
   ["get", "congestion"],
@@ -233,48 +299,44 @@ const DEFAULT_BASEMAPS = [
     tiles: ["https://tile.osm.ch/switzerland/{z}/{x}/{y}.png"],
     tags: ["osm", "switzerland", "regional"]
   }),
-  rasterBasemap({
+  googleRasterBasemap({
     id: "google-maps",
     name: "Google Maps",
-    provider: "google",
     category: "Street",
-    description: "Google road map tiles from the QGIS basemaps source.",
-    attribution: "&copy; Google",
-    tiles: ["https://mt1.google.com/vt/lyrs=m&x={x}&y={y}&z={z}"],
-    maxzoom: 20,
+    description: "Google road map tiles. Uses the Map Tiles API when a Google Maps API key is set, otherwise keyless xyz tiles.",
+    fallbackLyrs: "m",
+    session: { mapType: "roadmap" },
     tags: ["google", "street"]
   }),
-  rasterBasemap({
+  googleRasterBasemap({
     id: "google-satellite",
     name: "Google Satellite",
-    provider: "google",
     category: "Imagery",
-    description: "Google satellite tiles from the QGIS basemaps source.",
-    attribution: "&copy; Google",
-    tiles: ["https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}"],
-    maxzoom: 20,
+    description: "Google satellite tiles. Uses the Map Tiles API when a Google Maps API key is set, otherwise keyless xyz tiles.",
+    fallbackLyrs: "s",
+    session: { mapType: "satellite" },
     tags: ["google", "satellite", "imagery"]
   }),
-  rasterBasemap({
+  googleRasterBasemap({
     id: "google-terrain",
     name: "Google Terrain",
-    provider: "google",
     category: "Terrain",
-    description: "Google terrain tiles from the QGIS basemaps source.",
-    attribution: "&copy; Google",
-    tiles: ["https://mt1.google.com/vt/lyrs=p&x={x}&y={y}&z={z}"],
-    maxzoom: 20,
+    description: "Google terrain tiles. Uses the Map Tiles API when a Google Maps API key is set, otherwise keyless xyz tiles.",
+    fallbackLyrs: "p",
+    // The Map Tiles API requires `layerRoadmap` alongside the terrain map type
+    // for the terrain tiles to render.
+    session: { mapType: "terrain", layerTypes: ["layerRoadmap"] },
     tags: ["google", "terrain"]
   }),
-  rasterBasemap({
+  googleRasterBasemap({
     id: "google-hybrid",
     name: "Google Hybrid",
-    provider: "google",
     category: "Imagery",
-    description: "Google hybrid imagery tiles from the QGIS basemaps source.",
-    attribution: "&copy; Google",
-    tiles: ["https://mt1.google.com/vt/lyrs=y&x={x}&y={y}&z={z}"],
-    maxzoom: 20,
+    description: "Google hybrid imagery tiles. Uses the Map Tiles API when a Google Maps API key is set, otherwise keyless xyz tiles.",
+    fallbackLyrs: "y",
+    // Hybrid is satellite imagery with the roadmap layer (roads and labels)
+    // painted on top, matching the classic Google "hybrid" map type.
+    session: { mapType: "satellite", layerTypes: ["layerRoadmap"] },
     tags: ["google", "hybrid", "imagery"]
   }),
   amazonStyleBasemap({
@@ -738,26 +800,7 @@ const DEFAULT_BASEMAPS = [
     ],
     tags: ["esri", "terrain"]
   }),
-  rasterBasemap({
-    id: "eox-s2cloudless-2025",
-    name: "EOX Sentinel-2 cloudless 2025",
-    provider: "eox",
-    category: "Imagery",
-    description: "Cloudless Sentinel-2 satellite mosaic for 2025 (non-commercial use).",
-    attribution: EOX_S2CLOUDLESS_ATTRIBUTION,
-    tiles: [
-      "https://tiles.maps.eox.at/wmts/1.0.0/s2cloudless-2025_3857/default/GoogleMapsCompatible/{z}/{y}/{x}.jpg"
-    ],
-    maxzoom: 16,
-    tags: [
-      "eox",
-      "sentinel",
-      "satellite",
-      "imagery",
-      "cloudless",
-      "copernicus"
-    ]
-  }),
+  ...EOX_S2CLOUDLESS_YEARS.map(eoxS2CloudlessBasemap),
   rasterBasemap({
     id: "eox-terrain-light",
     name: "EOX Terrain Light",
@@ -771,6 +814,47 @@ const DEFAULT_BASEMAPS = [
     maxzoom: 14,
     tags: ["eox", "terrain", "light", "hillshade"]
   }),
+  rasterBasemap({
+    id: "eox-terrain",
+    name: "EOX Terrain",
+    provider: "eox",
+    category: "Terrain",
+    description: "Natural-like terrain basemap from EOX Maps (non-commercial use).",
+    attribution: EOX_TERRAIN_ATTRIBUTION,
+    // terrain_3857 is only published on EOX's "g" tile matrix set, which is the
+    // Web Mercator (GoogleMapsCompatible) grid under a different identifier.
+    tiles: [
+      "https://tiles.maps.eox.at/wmts/1.0.0/terrain_3857/default/g/{z}/{y}/{x}.jpg"
+    ],
+    maxzoom: 14,
+    tags: ["eox", "terrain", "hillshade"]
+  }),
+  rasterBasemap({
+    id: "eox-overlay",
+    name: "EOX Overlay",
+    provider: "eox",
+    category: "Labels",
+    description: "Transparent overlay with borders and points of interest from EOX Maps (non-commercial use).",
+    attribution: EOX_OVERLAY_ATTRIBUTION,
+    tiles: [
+      "https://tiles.maps.eox.at/wmts/1.0.0/overlay_3857/default/GoogleMapsCompatible/{z}/{y}/{x}.png"
+    ],
+    maxzoom: 14,
+    tags: ["eox", "overlay", "labels", "borders", "reference"]
+  }),
+  rasterBasemap({
+    id: "eox-overlay-bright",
+    name: "EOX Overlay Bright",
+    provider: "eox",
+    category: "Labels",
+    description: "Bright transparent overlay with borders and points of interest from EOX Maps (non-commercial use).",
+    attribution: EOX_OVERLAY_ATTRIBUTION,
+    tiles: [
+      "https://tiles.maps.eox.at/wmts/1.0.0/overlay_bright_3857/default/GoogleMapsCompatible/{z}/{y}/{x}.png"
+    ],
+    maxzoom: 14,
+    tags: ["eox", "overlay", "labels", "borders", "reference", "bright"]
+  }),
   rasterBasemap({
     id: "nasa-gibs-blue-marble",
     name: "Blue Marble",
@@ -1425,6 +1509,11 @@ class BasemapControl {
     // The basemap whose application last failed for a missing credential, so the
     // inline credential field's Enter key can re-attempt it (#837).
     __publicField(this, "_lastFailedBasemapId");
+    // The id of a just-applied basemap that is showing its keyless public tiles
+    // because no API key is set (currently the Google Maps/Satellite/Terrain/
+    // Hybrid basemaps). The panel offers an optional inline key input that
+    // upgrades it to the authorized tiles; leaving it blank keeps the fallback.
+    __publicField(this, "_optionalKeyBasemapId");
     // Detaches the listeners watching the in-flight style load (see
     // _watchStyleLoad). Set while a style swap is settling, cleared once it
     // succeeds, fails, or is superseded by a newer swap.
@@ -1733,6 +1822,7 @@ class BasemapControl {
         loading: false,
         error: void 0
       };
+      this._optionalKeyBasemapId = this._basemapUsesKeylessFallback(basemap) ? basemap.id : void 0;
       this._renderContent(true);
       this._emit({
         type: "basemapchange",
@@ -2361,6 +2451,55 @@ class BasemapControl {
   _retryLastFailedBasemap() {
     if (this._lastFailedBasemapId) this._selectBasemap(this._lastFailedBasemapId);
   }
+  // Renders the optional API key input shown after a basemap falls back to its
+  // keyless public tiles, so the user can enter a key to upgrade to the
+  // authorized provider tiles (or leave it blank to keep the public ones).
+  // Returns null unless such a basemap is the active selection and still keyless.
+  _createOptionalKeyPrompt() {
+    const id = this._optionalKeyBasemapId;
+    if (!id) return null;
+    const basemap = this._basemaps.find((candidate) => candidate.id === id);
+    if (!basemap || !this._state.activeBasemapIds.includes(id) || !this._basemapUsesKeylessFallback(basemap)) {
+      return null;
+    }
+    const def = this._providerFieldDefs().find(
+      (candidate) => candidate.provider === basemap.provider && candidate.has
+    );
+    if (!def) return null;
+    const wrapper = document.createElement("div");
+    wrapper.className = "basemap-control-optional-key";
+    const message = document.createElement("span");
+    message.className = "basemap-control-optional-key-message";
+    message.textContent = `Enter a ${def.fields[0].placeholder} to load the official ${def.label} tiles.`;
+    const help = PROVIDER_CREDENTIAL_HELP[def.provider];
+    if (help) {
+      message.appendChild(document.createTextNode(" "));
+      const link = document.createElement("a");
+      link.className = "basemap-control-status-link";
+      link.href = help.url;
+      link.target = "_blank";
+      link.rel = "noopener noreferrer";
+      link.textContent = help.label;
+      message.appendChild(link);
+    }
+    wrapper.appendChild(message);
+    const fields = document.createElement("div");
+    fields.className = "basemap-control-status-fields";
+    for (const field of def.fields) {
+      fields.appendChild(
+        this._createProviderSettingsInput({
+          ...field,
+          // Keep the field on screen while typing; Enter re-applies the basemap
+          // so the freshly entered key takes effect immediately.
+          rerenderOnInput: false,
+          clearErrorOnInput: false,
+          onEnter: () => this._reapplyBasemap(id)
+        })
+      );
+    }
+    wrapper.appendChild(fields);
+    return wrapper;
+  }
   _createProviderSettingsInput({
     className,
     type,
@@ -2482,7 +2621,15 @@ class BasemapControl {
       const inlineFields = this._createInlineCredentialFields();
       if (inlineFields) status.appendChild(inlineFields);
     } else {
-      status.textContent = `${resultCount} basemap${resultCount === 1 ? "" : "s"}`;
+      const count = document.createElement("span");
+      count.className = "basemap-control-status-message";
+      count.textContent = `${resultCount} basemap${resultCount === 1 ? "" : "s"}`;
+      status.appendChild(count);
+      const optionalKey = this._createOptionalKeyPrompt();
+      if (optionalKey) {
+        status.classList.add("has-optional-key");
+        status.appendChild(optionalKey);
+      }
     }
     return status;
   }
@@ -2563,9 +2710,10 @@ class BasemapControl {
   _hasHereBasemaps() {
     return this._basemaps.some((basemap) => basemap.provider === "here");
   }
-  // True when a Google basemap needs a Map Tiles API key. The existing Google
-  // raster basemaps (Maps/Satellite/etc.) use keyless tiles, so only session or
-  // api-key based Google layers (e.g. Google Traffic) require the key input.
+  // True when a Google basemap can use a Map Tiles API key. Session-based Google
+  // layers (Google Traffic, plus the base Maps/Satellite/Terrain/Hybrid layers
+  // that upgrade to the authorized Map Tiles API when a key is present) and any
+  // api-key based Google tiles reveal the key input.
   _hasGoogleApiKeyBasemaps() {
     return this._basemaps.some(
       (basemap) => basemap.provider === "google" && basemap.source.type === "raster" && (Boolean(basemap.source.googleSession) || basemap.source.tiles.some((tile) => tile.includes(API_KEY_PLACEHOLDER)))
@@ -2796,8 +2944,11 @@ class BasemapControl {
   // surface a "Get a ..." link and reveal the credential inputs.
   async _resolveRasterTiles(basemap) {
     if (basemap.source.type !== "raster") return [];
-    const { tiles, googleSession } = basemap.source;
+    const { tiles, googleSession, fallbackTiles } = basemap.source;
     if (googleSession) {
+      if (!this._googleMapsApiKey.trim() && (fallbackTiles == null ? void 0 : fallbackTiles.length)) {
+        return fallbackTiles;
+      }
       return this._resolveGoogleSessionTiles(tiles, googleSession);
     }
     if (!tiles.some((tile) => tile.includes(API_KEY_PLACEHOLDER))) {
@@ -2816,6 +2967,29 @@ class BasemapControl {
     if (provider === "google") return this._googleMapsApiKey.trim();
     return "";
   }
+  // True when a basemap is (or would be) served from its keyless public
+  // fallback tiles because its provider API key is not set. Drives the optional
+  // key prompt: these basemaps work without a key but can upgrade to the
+  // authorized provider tiles once one is entered.
+  _basemapUsesKeylessFallback(basemap) {
+    var _a;
+    return basemap.source.type === "raster" && Boolean(basemap.source.googleSession) && (((_a = basemap.source.fallbackTiles) == null ? void 0 : _a.length) ?? 0) > 0 && !this._rasterApiKeyFor(basemap.provider);
+  }
+  // Re-applies an already-active basemap so a newly entered key takes effect.
+  // Unlike `_selectBasemap`, this never toggles the basemap off in multiple
+  // mode: a stacked raster is re-added on top (replacing its prior instance),
+  // and a single-mode basemap is simply re-set.
+  _reapplyBasemap(id) {
+    const basemap = this._basemaps.find((candidate) => candidate.id === id);
+    const isOverlay = (basemap == null ? void 0 : basemap.source.type) === "raster" || (basemap == null ? void 0 : basemap.source.type) === "vector-overlay";
+    if (this._state.allowMultiple && isOverlay) {
+      this.addBasemap(id).catch(() => {
+      });
+    } else {
+      this.setBasemap(id).catch(() => {
+      });
+    }
+  }
   _missingRasterKeyError(provider) {
     const label = provider === "tomtom" ? "TomTom API key" : provider === "here" ? "HERE API key" : provider === "google" ? "Google Maps API key" : "API key";
     const helpProvider = provider in PROVIDER_CREDENTIAL_HELP ? provider : "maptiler";
@@ -3051,4 +3225,4 @@ exports.createBasemapCatalog = createBasemapCatalog;
 exports.filterBasemaps = filterBasemaps;
 exports.getBasemapCategories = getBasemapCategories;
 exports.resolveBasemapProviders = resolveBasemapProviders;
-//# sourceMappingURL=BasemapControl-DXJHjc6Z.cjs.map
+//# sourceMappingURL=BasemapControl-BbsxylnF.cjs.map