maplibre-gl-basemap-control 0.4.1 → 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 |
@@ -193,6 +236,7 @@ https://api.mapbox.com/styles/v1/mapbox/{styleId}?access_token={api-key}
 | `allowMultiple` | `boolean` | `false` | Stack raster basemaps instead of replacing the active one |
 | `showMultipleToggle` | `boolean` | `true` | Show the in-panel toggle that switches between adding and replacing |
 | `resizable` | `boolean` | `true` | Allow resizing the panel by dragging its bottom-left or bottom-right corner |
+| `confirmStyleReplace` | `(confirmation) => boolean \| Promise<boolean>` | `undefined` | Confirm before a style basemap replaces stacked raster basemaps (only invoked in `allowMultiple` mode with at least one raster stacked); return `false` to cancel |
 
 ### Multiple Basemaps
 
@@ -222,6 +266,22 @@ a style basemap always replaces the active basemaps (and clears any stacked rast
 overlays). Use the `before_id` input to control where each raster basemap is
 inserted relative to existing layers.
 
+Because that swap is destructive in stack mode, you can pass `confirmStyleReplace`
+to confirm before the stacked rasters are discarded. It is only invoked in
+`allowMultiple` mode when at least one raster basemap is currently stacked, and
+receives the `{ basemap, replacedBasemapIds }` it is about to replace. Return (or
+resolve to) `false` to cancel and keep the current basemaps.
+
+```typescript
+const control = new BasemapControl({
+  allowMultiple: true,
+  confirmStyleReplace: ({ basemap, replacedBasemapIds }) =>
+    window.confirm(
+      `Switching to "${basemap.name}" will remove ${replacedBasemapIds.length} stacked basemap(s). Continue?`,
+    ),
+});
+```
+
 ### Methods
 
 - `setBasemap(id)` - Apply a basemap and remove the previous plugin-managed basemap
@@ -232,6 +292,9 @@ inserted relative to existing layers.
 - `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