maplibre-gl-basemap-control 0.5.0 → 0.6.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, and Mapbox styles
+- Stackable traffic overlays for TomTom, HERE, Mapbox, and Google
 - Custom basemap and provider definitions
 - MapLibre `IControl` implementation
 - React wrapper and state hook
@@ -171,6 +172,45 @@ Mapbox style URLs follow this form:
 https://api.mapbox.com/styles/v1/mapbox/{styleId}?access_token={api-key}
 ```
 
+### Traffic Overlays
+
+The catalog ships real-time traffic overlays in the `Traffic` category. They are
+stackable overlays rather than full basemaps, so enable `allowMultiple: true` (or
+toggle "Add basemaps" in the panel) to lay them on top of any basemap. Click an
+active traffic layer again to remove it.
+
+| Basemap id | Provider | Credential |
+|------------|----------|------------|
+| `tomtom-traffic-flow-relative`, `tomtom-traffic-flow-absolute`, `tomtom-traffic-flow-relative-delay` | TomTom | `tomtomApiKey` |
+| `here-traffic-flow` | HERE | `hereApiKey` |
+| `mapbox-traffic` | Mapbox | `mapboxAccessToken` |
+| `google-traffic` | Google | `googleMapsApiKey` |
+
+```typescript
+const control = new BasemapControl({
+  allowMultiple: true,
+  tomtomApiKey: 'YOUR_TOMTOM_API_KEY',
+  hereApiKey: 'YOUR_HERE_API_KEY',
+  mapboxAccessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
+  googleMapsApiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
+});
+```
+
+The TomTom and HERE overlays are transparent raster flow tiles; Mapbox Traffic is
+a vector overlay colored by congestion level. Google Traffic uses the
+[Map Tiles API](https://developers.google.com/maps/documentation/tile/session_tokens):
+the control creates a tile session (with `layerTypes: ['layerTraffic']`) using your
+key, caches the session token until it expires, then loads the traffic tiles. The
+key must have the Map Tiles API enabled.
+
+> **Troubleshooting `API_KEY_SERVICE_BLOCKED`** ("Requests to this API tile method
+> ...Bootstrap are blocked"): this is a key restriction, not project API
+> enablement. Enabling the Map Tiles API on the project is not enough if the key
+> itself has an API allow-list. In Cloud Console go to **APIs & Services →
+> Credentials → your key → API restrictions** and either choose "Don't restrict
+> 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.
+
 ## API
 
 ### BasemapControl Options
@@ -185,7 +225,10 @@ https://api.mapbox.com/styles/v1/mapbox/{styleId}?access_token={api-key}
 | `mapTilerApiKey` | `string` | `undefined` | Initial MapTiler API key for built-in MapTiler styles |
 | `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 |
+| `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 |
 | `basemaps` | `BasemapDefinition[]` | `[]` | Custom basemaps to add or use |
 | `providers` | `BasemapProvider[]` | `[]` | Custom provider labels |
 | `includeDefaultBasemaps` | `boolean` | `true` | Include the built-in public catalog |
@@ -249,6 +292,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
+- `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
 - `getActiveBasemap()` - Return the most recently selected basemap definition
 - `getActiveBasemaps()` - Return all currently active basemap definitions
 - `getBasemaps()` - Return the catalog

package/dist/{BasemapControl-BITP2bjU.js → BasemapControl-CnjmO-_2.js}

@@ -7,6 +7,7 @@ const DEFAULT_BASEMAP_PROVIDERS = [
   { id: "cyclosm", name: "CyclOSM", category: "Cycling" },
   { id: "esri", name: "ESRI", category: "Imagery" },
   { id: "google", name: "Google", category: "General" },
+  { id: "here", name: "HERE", category: "Traffic" },
   { id: "mapbox", name: "Mapbox", category: "General" },
   { id: "maptiler", name: "MapTiler", category: "General" },
   { id: "nasa-gibs", name: "NASA GIBS", category: "Imagery" },
@@ -16,6 +17,7 @@ const DEFAULT_BASEMAP_PROVIDERS = [
   { id: "openstreetmap", name: "OpenStreetMap", category: "Community" },
   { id: "opentopomap", name: "OpenTopoMap", category: "Terrain" },
   { id: "swisstopo", name: "Swiss Federal Geoportal", category: "Regional" },
+  { id: "tomtom", name: "TomTom", category: "Traffic" },
   { id: "topplusopen", name: "TopPlusOpen", category: "Regional" },
   { id: "usgs", name: "USGS", category: "United States" },
   { id: "waymarkedtrails", name: "Waymarked Trails", category: "Outdoor" }
@@ -143,6 +145,44 @@ const MAPBOX_ATTRIBUTION = "© Mapbox © OpenStreetMap contributors";
 const MAPTILER_ATTRIBUTION = "© MapTiler © OpenStreetMap contributors";
 const OSM_ATTRIBUTION = "© OpenStreetMap contributors";
 const OPENFREEMAP_ATTRIBUTION = "OpenFreeMap © OpenMapTiles Data from OpenStreetMap";
+const TOMTOM_ATTRIBUTION = "© TomTom";
+const HERE_ATTRIBUTION = "© HERE";
+const GOOGLE_ATTRIBUTION = "© Google";
+const MAPBOX_TRAFFIC_CONGESTION_COLORS = [
+  "match",
+  ["get", "congestion"],
+  "low",
+  "#4caf50",
+  "moderate",
+  "#ffc107",
+  "heavy",
+  "#ff5722",
+  "severe",
+  "#b71c1c",
+  "#9e9e9e"
+];
+function rasterTrafficBasemap({
+  id,
+  name,
+  provider,
+  description,
+  attribution,
+  tiles,
+  maxzoom = 22,
+  tags = []
+}) {
+  return rasterBasemap({
+    id,
+    name,
+    provider,
+    category: "Traffic",
+    description,
+    attribution,
+    tiles,
+    maxzoom,
+    tags: ["traffic", "overlay", ...tags]
+  });
+}
 const DEFAULT_BASEMAPS = [
   rasterBasemap({
     id: "osm-standard",
@@ -1048,6 +1088,89 @@ const DEFAULT_BASEMAPS = [
       pitch: 60
     },
     tags: ["openfreemap", "vector", "style", "3d", "liberty"]
+  },
+  rasterTrafficBasemap({
+    id: "tomtom-traffic-flow-relative",
+    name: "TomTom Traffic Flow",
+    provider: "tomtom",
+    description: "TomTom traffic speeds relative to free-flow speed. Requires a TomTom API key.",
+    attribution: TOMTOM_ATTRIBUTION,
+    tiles: ["https://api.tomtom.com/traffic/map/4/tile/flow/relative0/{z}/{x}/{y}.png?key={api-key}"],
+    tags: ["tomtom", "flow", "relative"]
+  }),
+  rasterTrafficBasemap({
+    id: "tomtom-traffic-flow-absolute",
+    name: "TomTom Traffic Flow Absolute",
+    provider: "tomtom",
+    description: "TomTom traffic colored by absolute speed. Requires a TomTom API key.",
+    attribution: TOMTOM_ATTRIBUTION,
+    tiles: ["https://api.tomtom.com/traffic/map/4/tile/flow/absolute/{z}/{x}/{y}.png?key={api-key}"],
+    tags: ["tomtom", "flow", "absolute"]
+  }),
+  rasterTrafficBasemap({
+    id: "tomtom-traffic-flow-relative-delay",
+    name: "TomTom Traffic Flow Delay",
+    provider: "tomtom",
+    description: "TomTom traffic highlighting only roads delayed below free-flow speed. Requires a TomTom API key.",
+    attribution: TOMTOM_ATTRIBUTION,
+    tiles: [
+      "https://api.tomtom.com/traffic/map/4/tile/flow/relative-delay/{z}/{x}/{y}.png?key={api-key}"
+    ],
+    tags: ["tomtom", "flow", "delay"]
+  }),
+  rasterTrafficBasemap({
+    id: "here-traffic-flow",
+    name: "HERE Traffic Flow",
+    provider: "here",
+    description: "HERE real-time traffic flow overlay. Requires a HERE API key.",
+    attribution: HERE_ATTRIBUTION,
+    tiles: ["https://traffic.maps.hereapi.com/v3/flow/mc/{z}/{x}/{y}/png?apiKey={api-key}"],
+    tags: ["here", "flow"]
+  }),
+  {
+    id: "mapbox-traffic",
+    name: "Mapbox Traffic",
+    provider: "mapbox",
+    type: "vector-overlay",
+    category: "Traffic",
+    description: "Mapbox real-time traffic congestion overlay. Requires a Mapbox access token.",
+    attribution: MAPBOX_ATTRIBUTION,
+    source: {
+      type: "vector-overlay",
+      url: "mapbox://mapbox.mapbox-traffic-v1",
+      sourceLayer: "traffic",
+      layerType: "line",
+      layout: {
+        "line-join": "round",
+        "line-cap": "round"
+      },
+      paint: {
+        "line-width": ["interpolate", ["linear"], ["zoom"], 6, 1.5, 14, 4, 18, 8],
+        "line-color": MAPBOX_TRAFFIC_CONGESTION_COLORS
+      }
+    },
+    tags: ["mapbox", "traffic", "overlay", "congestion"]
+  },
+  {
+    id: "google-traffic",
+    name: "Google Traffic",
+    provider: "google",
+    type: "raster",
+    category: "Traffic",
+    description: "Google real-time traffic overlay via the Map Tiles API. Requires a Google Maps API key.",
+    attribution: GOOGLE_ATTRIBUTION,
+    source: {
+      type: "raster",
+      tiles: ["https://tile.googleapis.com/v1/2dtiles/{z}/{x}/{y}?session={session}&key={api-key}"],
+      tileSize: 256,
+      maxzoom: 22,
+      googleSession: {
+        mapType: "roadmap",
+        layerTypes: ["layerTraffic"],
+        overlay: true
+      }
+    },
+    tags: ["google", "traffic", "overlay"]
   }
 ];
 function combineProviders(defaults, custom = []) {
@@ -1125,6 +1248,18 @@ const PROVIDER_CREDENTIAL_HELP = {
   mapbox: {
     url: "https://docs.mapbox.com/help/getting-started/access-tokens/",
     label: "Get a Mapbox access token"
+  },
+  tomtom: {
+    url: "https://developer.tomtom.com/how-to-get-tomtom-api-key",
+    label: "Get a TomTom API key"
+  },
+  here: {
+    url: "https://www.here.com/get-started/pricing",
+    label: "Get a HERE API key"
+  },
+  google: {
+    url: "https://developers.google.com/maps/documentation/tile/get-api-key",
+    label: "Get a Google Maps API key"
   }
 };
 const MIN_PANEL_WIDTH = 240;
@@ -1158,6 +1293,13 @@ class BasemapControl {
     __publicField(this, "_amazonApiKey", "");
     __publicField(this, "_awsRegion", "");
     __publicField(this, "_mapboxAccessToken", "");
+    __publicField(this, "_tomtomApiKey", "");
+    __publicField(this, "_hereApiKey", "");
+    __publicField(this, "_googleMapsApiKey", "");
+    // Cached Google Map Tiles API session tokens keyed by their session config, so
+    // a traffic overlay reuses a token until it expires instead of creating a new
+    // session on every add. Keyed by the serialized config + API key.
+    __publicField(this, "_googleSessions", new globalThis.Map());
     __publicField(this, "_providerSettingsCollapsed", true);
     // Provider of the most recent missing-credential error, used to pick the
     // matching help link. Kept in sync with `_state.error` (both are set together
@@ -1197,6 +1339,9 @@ class BasemapControl {
     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._tomtomApiKey = (options == null ? void 0 : options.tomtomApiKey) ?? "";
+    this._hereApiKey = (options == null ? void 0 : options.hereApiKey) ?? "";
+    this._googleMapsApiKey = (options == null ? void 0 : options.googleMapsApiKey) ?? "";
     this._basemaps = createBasemapCatalog(
       options == null ? void 0 : options.basemaps,
       this._options.includeDefaultBasemaps
@@ -1324,6 +1469,25 @@ class BasemapControl {
     this._renderContent();
     this._emit({ type: "statechange", state: this.getState() });
   }
+  setTomTomApiKey(apiKey) {
+    this._tomtomApiKey = apiKey;
+    this._state = { ...this._state, error: void 0 };
+    this._renderContent();
+    this._emit({ type: "statechange", state: this.getState() });
+  }
+  setHereApiKey(apiKey) {
+    this._hereApiKey = apiKey;
+    this._state = { ...this._state, error: void 0 };
+    this._renderContent();
+    this._emit({ type: "statechange", state: this.getState() });
+  }
+  setGoogleMapsApiKey(apiKey) {
+    this._googleMapsApiKey = apiKey;
+    this._googleSessions.clear();
+    this._state = { ...this._state, error: void 0 };
+    this._renderContent();
+    this._emit({ type: "statechange", state: this.getState() });
+  }
   getActiveBasemap() {
     return this._basemaps.find((basemap) => basemap.id === this._state.activeBasemapId);
   }
@@ -1386,9 +1550,9 @@ class BasemapControl {
       this._handleError(error, basemap);
       throw error;
     }
-    const isRaster = basemap.source.type === "raster";
-    const effectiveMode = isRaster ? mode : "replace";
-    if (!isRaster && this._state.allowMultiple && this._managedRasters.size > 0 && this._options.confirmStyleReplace) {
+    const isOverlay = basemap.source.type === "raster" || basemap.source.type === "vector-overlay";
+    const effectiveMode = isOverlay ? mode : "replace";
+    if (!isOverlay && this._state.allowMultiple && this._managedRasters.size > 0 && this._options.confirmStyleReplace) {
       const replacedBasemapIds = [...this._managedRasters.keys()];
       let confirmed = false;
       try {
@@ -1403,14 +1567,14 @@ class BasemapControl {
     this._emit({ type: "statechange", state: this.getState() });
     try {
       let managedRaster;
-      if (isRaster) {
+      if (isOverlay) {
         await this._waitForStyleReady();
         if (effectiveMode === "replace") {
           this._removeManagedBasemap();
         } else {
           this._removeManagedRaster(basemap.id);
         }
-        managedRaster = this._addRasterBasemap(basemap);
+        managedRaster = await this._addOverlay(basemap);
       } else {
         const styleUrl = this._resolveStyleUrl(basemap);
         const styleOptions = this._getStyleOptions(basemap);
@@ -1457,8 +1621,8 @@ class BasemapControl {
   // In multiple mode a raster basemap click toggles the overlay on or off.
   _selectBasemap(id) {
     const basemap = this._basemaps.find((candidate) => candidate.id === id);
-    const isRaster = (basemap == null ? void 0 : basemap.source.type) === "raster";
-    if (this._state.allowMultiple && isRaster) {
+    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.toggleBasemap(id).catch(() => {
       });
       return;
@@ -1706,6 +1870,49 @@ class BasemapControl {
         })
       );
     }
+    if (this._hasTomTomBasemaps()) {
+      fields.appendChild(
+        this._createProviderSettingsInput({
+          className: "basemap-control-tomtom-key",
+          type: "password",
+          placeholder: "TomTom API key",
+          ariaLabel: "TomTom API key",
+          value: this._tomtomApiKey,
+          onInput: (value) => {
+            this._tomtomApiKey = value;
+          }
+        })
+      );
+    }
+    if (this._hasHereBasemaps()) {
+      fields.appendChild(
+        this._createProviderSettingsInput({
+          className: "basemap-control-here-key",
+          type: "password",
+          placeholder: "HERE API key",
+          ariaLabel: "HERE API key",
+          value: this._hereApiKey,
+          onInput: (value) => {
+            this._hereApiKey = value;
+          }
+        })
+      );
+    }
+    if (this._hasGoogleApiKeyBasemaps()) {
+      fields.appendChild(
+        this._createProviderSettingsInput({
+          className: "basemap-control-google-key",
+          type: "password",
+          placeholder: "Google Maps API key",
+          ariaLabel: "Google Maps API key",
+          value: this._googleMapsApiKey,
+          onInput: (value) => {
+            this._googleMapsApiKey = value;
+            this._googleSessions.clear();
+          }
+        })
+      );
+    }
     if (this._hasAmazonBasemaps()) {
       fields.appendChild(
         this._createProviderSettingsInput({
@@ -1885,7 +2092,7 @@ class BasemapControl {
       main.appendChild(meta);
       const type = document.createElement("span");
       type.className = "basemap-control-result-type";
-      type.textContent = basemap.type === "raster" ? "Raster" : "Style";
+      type.textContent = basemap.type === "raster" ? "Raster" : basemap.type === "vector-overlay" ? "Overlay" : "Style";
       row.appendChild(main);
       row.appendChild(type);
       if (basemap.attribution) {
@@ -1916,11 +2123,25 @@ class BasemapControl {
   _hasMapboxBasemaps() {
     return this._basemaps.some((basemap) => basemap.provider === "mapbox");
   }
+  _hasTomTomBasemaps() {
+    return this._basemaps.some((basemap) => basemap.provider === "tomtom");
+  }
+  _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.
+  _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)))
+    );
+  }
   _hasProviderSettings() {
-    return this._hasMapTilerBasemaps() || this._hasAmazonBasemaps() || this._hasMapboxBasemaps();
+    return this._hasMapTilerBasemaps() || this._hasAmazonBasemaps() || this._hasMapboxBasemaps() || this._hasTomTomBasemaps() || this._hasHereBasemaps() || this._hasGoogleApiKeyBasemaps();
   }
   _resolveStyleUrl(basemap) {
-    if (basemap.source.type === "raster") {
+    if (basemap.source.type !== "style" && basemap.source.type !== "vector-style") {
       throw new Error(`Basemap "${basemap.id}" is not a style basemap.`);
     }
     const url = basemap.source.url;
@@ -2048,14 +2269,23 @@ class BasemapControl {
   _isUrlLikeCredential(value) {
     return /^https?:\/\//i.test(value);
   }
-  _addRasterBasemap(basemap) {
+  // Add a stackable overlay (raster tiles or a vector overlay) to the map,
+  // resolving any provider credentials first.
+  async _addOverlay(basemap) {
+    if (basemap.source.type === "vector-overlay") {
+      return this._addVectorOverlay(basemap, basemap.source);
+    }
+    return this._addRasterBasemap(basemap);
+  }
+  async _addRasterBasemap(basemap) {
     if (!this._map || basemap.source.type !== "raster") return void 0;
+    const tiles = 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();
     const source = {
       type: "raster",
-      tiles: basemap.source.tiles,
+      tiles,
       tileSize: basemap.source.tileSize ?? 256,
       minzoom: basemap.source.minzoom,
       maxzoom: basemap.source.maxzoom,
@@ -2073,6 +2303,158 @@ class BasemapControl {
     this._managedRasters.set(basemap.id, managed);
     return managed;
   }
+  _addVectorOverlay(basemap, overlay) {
+    if (!this._map) return void 0;
+    const sourceId = `${CONTROL_SOURCE_PREFIX}-${basemap.id}`;
+    const layerId = [CONTROL_LAYER_PREFIX, basemap.id].filter(Boolean).join("-");
+    const beforeId = this._getBasemapInsertBeforeId();
+    const source = {
+      type: "vector",
+      ...this._resolveVectorOverlaySource(basemap, overlay),
+      minzoom: overlay.minzoom,
+      maxzoom: overlay.maxzoom,
+      attribution: basemap.attribution
+    };
+    const layer = {
+      id: layerId,
+      type: overlay.layerType ?? "line",
+      source: sourceId,
+      "source-layer": overlay.sourceLayer,
+      ...overlay.layout ? { layout: overlay.layout } : {},
+      ...overlay.paint ? { paint: overlay.paint } : {}
+    };
+    this._map.addSource(sourceId, source);
+    this._map.addLayer(layer, beforeId);
+    const managed = { sourceId, layerId, beforeId };
+    this._managedRasters.set(basemap.id, managed);
+    return managed;
+  }
+  // Resolves the `{url}` or `{tiles}` of a vector overlay, substituting provider
+  // credentials. Mapbox vector overlays are pointed at the v4 TileJSON endpoint
+  // with the access token, reusing the same resolver as Mapbox style sources.
+  _resolveVectorOverlaySource(basemap, overlay) {
+    if (basemap.provider === "mapbox") {
+      const accessToken = this._mapboxAccessToken.trim();
+      if (!accessToken) {
+        throw new MissingCredentialError(
+          "Enter a Mapbox access token before applying this overlay.",
+          "mapbox"
+        );
+      }
+      if (this._isUrlLikeCredential(accessToken)) {
+        throw new MissingCredentialError(
+          "Enter a valid Mapbox access token, not a URL.",
+          "mapbox"
+        );
+      }
+      const encoded = encodeURIComponent(accessToken);
+      if (overlay.url) {
+        return { url: this._resolveMapboxInternalUrl(overlay.url, encoded) };
+      }
+    }
+    if (overlay.url) return { url: overlay.url };
+    if (overlay.tiles) return { tiles: overlay.tiles };
+    throw new Error(`Vector overlay "${basemap.id}" has no url or tiles.`);
+  }
+  // Resolves the tile templates of a raster basemap, substituting provider
+  // credentials (and, for Google, a Map Tiles API session token). Throws a
+  // MissingCredentialError when a required key is absent so the panel can
+  // surface a "Get a ..." link and reveal the credential inputs.
+  async _resolveRasterTiles(basemap) {
+    if (basemap.source.type !== "raster") return [];
+    const { tiles, googleSession } = basemap.source;
+    if (googleSession) {
+      return this._resolveGoogleSessionTiles(tiles, googleSession);
+    }
+    if (!tiles.some((tile) => tile.includes(API_KEY_PLACEHOLDER))) {
+      return tiles;
+    }
+    const apiKey = this._rasterApiKeyFor(basemap.provider);
+    if (!apiKey) {
+      throw this._missingRasterKeyError(basemap.provider);
+    }
+    const encoded = encodeURIComponent(apiKey);
+    return tiles.map((tile) => tile.split(API_KEY_PLACEHOLDER).join(encoded));
+  }
+  _rasterApiKeyFor(provider) {
+    if (provider === "tomtom") return this._tomtomApiKey.trim();
+    if (provider === "here") return this._hereApiKey.trim();
+    if (provider === "google") return this._googleMapsApiKey.trim();
+    return "";
+  }
+  _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";
+    return new MissingCredentialError(`Enter a ${label} before applying this layer.`, helpProvider);
+  }
+  // Resolves Google tile templates by minting (or reusing) a Map Tiles API
+  // session token, then substituting both `{session}` and `{api-key}`.
+  async _resolveGoogleSessionTiles(tiles, config) {
+    const apiKey = this._googleMapsApiKey.trim();
+    if (!apiKey) {
+      throw new MissingCredentialError(
+        "Enter a Google Maps API key before applying this layer.",
+        "google"
+      );
+    }
+    const token = await this._getGoogleSessionToken(apiKey, config);
+    const encodedKey = encodeURIComponent(apiKey);
+    const encodedSession = encodeURIComponent(token);
+    return tiles.map(
+      (tile) => tile.split("{session}").join(encodedSession).split(API_KEY_PLACEHOLDER).join(encodedKey)
+    );
+  }
+  async _getGoogleSessionToken(apiKey, config) {
+    const cacheKey = `${apiKey}:${JSON.stringify(config)}`;
+    const cached = this._googleSessions.get(cacheKey);
+    if (cached && cached.expiry - 6e4 > Date.now()) {
+      return cached.token;
+    }
+    const response = await fetch(
+      `https://tile.googleapis.com/v1/createSession?key=${encodeURIComponent(apiKey)}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          mapType: config.mapType,
+          language: config.language ?? "en-US",
+          region: config.region ?? "US",
+          layerTypes: config.layerTypes,
+          overlay: config.overlay
+        })
+      }
+    );
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      throw new MissingCredentialError(
+        `Google could not create a tile session (HTTP ${response.status}). ${this._summarizeGoogleError(
+          detail
+        )}`.trim(),
+        "google"
+      );
+    }
+    const data = await response.json();
+    if (!data.session) {
+      throw new MissingCredentialError(
+        "Google did not return a tile session token. Check that the Map Tiles API is enabled for your key.",
+        "google"
+      );
+    }
+    const expirySeconds = data.expiry ? Number(data.expiry) : NaN;
+    const expiry = Number.isFinite(expirySeconds) ? expirySeconds * 1e3 : Date.now() + 60 * 60 * 1e3;
+    this._googleSessions.set(cacheKey, { token: data.session, expiry });
+    return data.session;
+  }
+  _summarizeGoogleError(detail) {
+    var _a;
+    if (!detail) return "";
+    try {
+      const parsed = JSON.parse(detail);
+      return ((_a = parsed.error) == null ? void 0 : _a.message) ?? "";
+    } catch {
+      return detail.slice(0, 200);
+    }
+  }
   _waitForStyleReady() {
     if (!this._map) return Promise.resolve();
     if (typeof this._map.isStyleLoaded !== "function" || this._map.isStyleLoaded()) {
@@ -2237,4 +2619,4 @@ export {
   getBasemapCategories as g,
   resolveBasemapProviders as r
 };
-//# sourceMappingURL=BasemapControl-BITP2bjU.js.map
+//# sourceMappingURL=BasemapControl-CnjmO-_2.js.map