maplibre-gl-basemap-control 0.2.2 → 0.4.0

package/README.md

@@ -8,7 +8,7 @@ A MapLibre GL JS control for searching and switching public basemaps. It keeps t
 ## Features
 
 - Search-first basemap picker inspired by QuickMapServices
-- Built-in no-key catalog for common public basemaps
+- Built-in catalog for common public basemaps, MapTiler styles, Amazon Location styles, and Mapbox styles
 - Custom basemap and provider definitions
 - MapLibre `IControl` implementation
 - React wrapper and state hook
@@ -131,6 +131,46 @@ const control = new BasemapControl({
 
 Set `includeDefaultBasemaps: false` to use only your supplied catalog.
 
+## Keyed Provider Styles
+
+The built-in catalog includes MapTiler styles such as Streets, Base, Dataviz, Outdoor, Topo,
+Satellite Hybrid, Satellite Plain, Aquarelle, Backdrop, Landscape, Ocean, Toner, OpenStreetMap, and
+Winter. It also includes Amazon Location styles: Standard, Monochrome, Hybrid, and Satellite.
+Mapbox styles include Streets, Outdoors, Light, Dark, Satellite, Satellite Streets, Navigation Day,
+and Navigation Night.
+
+MapTiler and Amazon Location styles require API keys. Mapbox styles require an access token. Users
+can enter keys and tokens in the collapsible provider settings section in the control panel, or you
+can provide them when creating the control.
+
+```typescript
+const control = new BasemapControl({
+  defaultBasemapId: 'maptiler-streets',
+  mapTilerApiKey: 'YOUR_MAPTILER_API_KEY',
+  amazonApiKey: 'YOUR_AMAZON_LOCATION_API_KEY',
+  awsRegion: 'us-east-1',
+  mapboxAccessToken: 'YOUR_MAPBOX_ACCESS_TOKEN',
+});
+```
+
+The default MapTiler style URLs follow this form:
+
+```text
+https://api.maptiler.com/maps/{mapId}/style.json?key={api-key}
+```
+
+Amazon Location style URLs follow this form:
+
+```text
+https://maps.geo.{aws-region}.amazonaws.com/v2/styles/{mapStyle}/descriptor?key={api-key}
+```
+
+Mapbox style URLs follow this form:
+
+```text
+https://api.mapbox.com/styles/v1/mapbox/{styleId}?access_token={api-key}
+```
+
 ## API
 
 ### BasemapControl Options
@@ -142,15 +182,58 @@ Set `includeDefaultBasemaps: false` to use only your supplied catalog.
 | `title` | `string` | `'Basemaps'` | Panel title and button label |
 | `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 |
+| `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 |
 | `basemaps` | `BasemapDefinition[]` | `[]` | Custom basemaps to add or use |
 | `providers` | `BasemapProvider[]` | `[]` | Custom provider labels |
 | `includeDefaultBasemaps` | `boolean` | `true` | Include the built-in public catalog |
 | `defaultBasemapId` | `string` | `undefined` | Basemap to apply after the control is added |
+| `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 |
+
+### Multiple Basemaps
+
+By default, selecting a basemap replaces the active one. Set `allowMultiple: true`
+to stack raster basemaps instead: each click adds the selected raster basemap as
+an additional overlay, and clicking an already-active raster basemap removes it.
+This lets a project hold several raster basemaps at once and switch between them by
+toggling the entries in the panel.
+
+```typescript
+const control = new BasemapControl({
+  allowMultiple: true,
+});
+```
+
+The panel also shows an **Add basemaps** toggle so users can switch between adding
+and replacing at runtime. Hide it with `showMultipleToggle: false`.
+
+### Resizable Panel
+
+The panel can be resized by dragging either of its bottom corners (bottom-left or
+bottom-right). The resized width and height are reflected in `state.panelWidth` and
+`state.panelHeight`. Set `resizable: false` to disable the handles.
+
+Style basemaps cannot stack because they replace the entire map style, so selecting
+a style basemap always replaces the active basemaps (and clears any stacked raster
+overlays). Use the `before_id` input to control where each raster basemap is
+inserted relative to existing layers.
 
 ### Methods
 
 - `setBasemap(id)` - Apply a basemap and remove the previous plugin-managed basemap
-- `getActiveBasemap()` - Return the current basemap definition
+- `addBasemap(id)` - Add a raster basemap as an additional overlay (style basemaps replace instead)
+- `removeBasemap(id)` - Remove a previously added managed raster basemap
+- `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
+- `setAmazonCredentials(apiKey, awsRegion)` - Set or update Amazon Location credentials
+- `setMapboxAccessToken(accessToken)` - Set or update the Mapbox access token
+- `getActiveBasemap()` - Return the most recently selected basemap definition
+- `getActiveBasemaps()` - Return all currently active basemap definitions
 - `getBasemaps()` - Return the catalog
 - `setBasemaps(basemaps)` - Replace the catalog
 - `toggle()`, `expand()`, `collapse()` - Control panel visibility
@@ -164,7 +247,8 @@ before that layer.
 
 ### Events
 
-- `basemapchange`
+- `basemapchange` (includes a `mode` of `'replace'` or `'add'`)
+- `basemapremove`
 - `error`
 - `collapse`
 - `expand`