maplibre-gl-components 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # maplibre-gl-components
 
-Legend, colorbar, and HTML control components for MapLibre GL JS maps.
+Legend, colorbar, basemap switcher, terrain toggle, and HTML control components for MapLibre GL JS maps.
 
 [![npm version](https://badge.fury.io/js/maplibre-gl-components.svg)](https://badge.fury.io/js/maplibre-gl-components)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -9,7 +9,10 @@ Legend, colorbar, and HTML control components for MapLibre GL JS maps.
 
 - **Colorbar** - Continuous gradient legends with built-in matplotlib colormaps
 - **Legend** - Categorical legends with color swatches and labels
+- **BasemapControl** - Interactive basemap switcher with 100+ providers from xyzservices
+- **TerrainControl** - Toggle 3D terrain on/off using free AWS Terrarium elevation tiles
 - **HtmlControl** - Flexible HTML content control for custom info panels
+- **Zoom-based Visibility** - Show/hide components at specific zoom levels with `minzoom`/`maxzoom`
 - **React Support** - First-class React components and hooks
 - **TypeScript** - Full type definitions included
 - **20+ Built-in Colormaps** - viridis, plasma, terrain, jet, and more
@@ -26,7 +29,7 @@ npm install maplibre-gl-components
 
 ```typescript
 import maplibregl from 'maplibre-gl';
-import { Colorbar, Legend, HtmlControl } from 'maplibre-gl-components';
+import { Colorbar, Legend, HtmlControl, BasemapControl, TerrainControl } from 'maplibre-gl-components';
 import 'maplibre-gl-components/style.css';
 
 const map = new maplibregl.Map({
@@ -36,6 +39,21 @@ const map = new maplibregl.Map({
   zoom: 4,
 });
 
+// Add a terrain toggle control
+const terrainControl = new TerrainControl({
+  exaggeration: 1.5,
+  hillshade: true,
+});
+map.addControl(terrainControl, 'top-right');
+
+// Add a basemap switcher
+const basemapControl = new BasemapControl({
+  defaultBasemap: 'OpenStreetMap.Mapnik',
+  showSearch: true,
+  filterGroups: ['OpenStreetMap', 'CartoDB', 'Stadia', 'Esri'],
+});
+map.addControl(basemapControl, 'top-left');
+
 // Add a colorbar
 const colorbar = new Colorbar({
   colormap: 'viridis',
@@ -74,7 +92,7 @@ htmlControl.setHtml('<div><strong>Stats:</strong> 5,678 features</div>');
 ```tsx
 import { useState, useEffect, useRef } from 'react';
 import maplibregl from 'maplibre-gl';
-import { ColorbarReact, LegendReact, HtmlControlReact } from 'maplibre-gl-components/react';
+import { ColorbarReact, LegendReact, HtmlControlReact, BasemapReact, TerrainReact } from 'maplibre-gl-components/react';
 import 'maplibre-gl-components/style.css';
 
 function MyMap() {
@@ -103,6 +121,22 @@ function MyMap() {
 
       {map && (
         <>
+          <TerrainReact
+            map={map}
+            exaggeration={1.5}
+            hillshade
+            position="top-right"
+            onTerrainChange={(enabled) => console.log('Terrain:', enabled)}
+          />
+
+          <BasemapReact
+            map={map}
+            defaultBasemap="OpenStreetMap.Mapnik"
+            showSearch
+            filterGroups={['OpenStreetMap', 'CartoDB', 'Stadia']}
+            position="top-left"
+          />
+
           <ColorbarReact
             map={map}
             colormap="viridis"
@@ -160,6 +194,8 @@ interface ColorbarOptions {
   opacity?: number;
   fontSize?: number;
   fontColor?: string;
+  minzoom?: number;                    // Min zoom level to show (default: 0)
+  maxzoom?: number;                    // Max zoom level to show (default: 24)
 }
 
 // Methods
@@ -190,6 +226,8 @@ interface LegendOptions {
   opacity?: number;
   fontSize?: number;
   fontColor?: string;
+  minzoom?: number;                    // Min zoom level to show (default: 0)
+  maxzoom?: number;                    // Max zoom level to show (default: 24)
 }
 
 interface LegendItem {
@@ -229,6 +267,8 @@ interface HtmlControlOptions {
   opacity?: number;
   maxWidth?: number;
   maxHeight?: number;
+  minzoom?: number;                    // Min zoom level to show (default: 0)
+  maxzoom?: number;                    // Max zoom level to show (default: 24)
 }
 
 // Methods
@@ -241,6 +281,113 @@ htmlControl.update(options)
 htmlControl.getState()
 ```
 
+### BasemapControl
+
+An interactive basemap switcher that loads providers from [xyzservices](https://github.com/geopandas/xyzservices).
+
+```typescript
+interface BasemapControlOptions {
+  basemaps?: BasemapItem[];            // Custom basemaps array
+  providersUrl?: string;               // URL to fetch providers.json (defaults to xyzservices)
+  defaultBasemap?: string;             // Initial basemap ID (e.g., 'OpenStreetMap.Mapnik')
+  position?: ControlPosition;
+  visible?: boolean;
+  collapsible?: boolean;               // Whether control is collapsible (default: true)
+  collapsed?: boolean;                 // Whether control starts collapsed (default: true)
+  displayMode?: 'dropdown' | 'gallery' | 'list';  // UI mode (default: 'dropdown')
+  showSearch?: boolean;                // Show search input (default: true)
+  filterGroups?: string[];             // Only include these provider groups
+  excludeGroups?: string[];            // Exclude these provider groups
+  excludeBroken?: boolean;             // Exclude broken providers (default: true)
+  backgroundColor?: string;
+  maxWidth?: number;
+  maxHeight?: number;
+  fontSize?: number;
+  fontColor?: string;
+  minzoom?: number;
+  maxzoom?: number;
+}
+
+interface BasemapItem {
+  id: string;                          // Unique identifier
+  name: string;                        // Display name
+  group?: string;                      // Provider group (e.g., 'OpenStreetMap')
+  url?: string;                        // XYZ tile URL template
+  style?: string;                      // MapLibre style URL
+  attribution?: string;
+  thumbnail?: string;                  // Preview image URL
+  maxZoom?: number;
+  minZoom?: number;
+  requiresApiKey?: boolean;
+  apiKey?: string;
+}
+
+// Methods
+basemapControl.show()
+basemapControl.hide()
+basemapControl.expand()
+basemapControl.collapse()
+basemapControl.toggle()
+basemapControl.setBasemap(basemapId)   // Switch to a basemap
+basemapControl.getBasemaps()           // Get available basemaps
+basemapControl.addBasemap(basemap)     // Add a custom basemap
+basemapControl.removeBasemap(id)       // Remove a basemap
+basemapControl.setApiKey(id, key)      // Set API key for a basemap
+basemapControl.getSelectedBasemap()    // Get currently selected basemap
+basemapControl.update(options)
+basemapControl.getState()
+basemapControl.on('basemapchange', handler)  // Listen for basemap changes
+```
+
+**Available Provider Groups:**
+- OpenStreetMap, CartoDB, Stadia, Esri, OpenTopoMap
+- Thunderforest, MapBox, MapTiler (require API keys)
+- NASAGIBS, OpenSeaMap, and 20+ more
+
+### TerrainControl
+
+A toggle control for 3D terrain rendering using free AWS Terrarium elevation tiles.
+
+```typescript
+interface TerrainControlOptions {
+  sourceUrl?: string;                   // Terrain tile URL (default: AWS Terrarium)
+  encoding?: 'terrarium' | 'mapbox';    // Terrain encoding (default: 'terrarium')
+  exaggeration?: number;                // Vertical scale factor (default: 1.0)
+  enabled?: boolean;                    // Initial terrain state (default: false)
+  hillshade?: boolean;                  // Add hillshade layer (default: true)
+  hillshadeExaggeration?: number;       // Hillshade intensity (default: 0.5)
+  position?: ControlPosition;
+  visible?: boolean;
+  backgroundColor?: string;
+  borderRadius?: number;
+  opacity?: number;
+  minzoom?: number;                     // Min zoom level to show (default: 0)
+  maxzoom?: number;                     // Max zoom level to show (default: 24)
+}
+
+// Methods
+terrainControl.show()
+terrainControl.hide()
+terrainControl.enable()                 // Enable terrain
+terrainControl.disable()                // Disable terrain
+terrainControl.toggle()                 // Toggle terrain on/off
+terrainControl.isEnabled()              // Check if terrain is enabled
+terrainControl.setExaggeration(value)   // Set vertical exaggeration (0.1 - 10.0)
+terrainControl.getExaggeration()        // Get current exaggeration
+terrainControl.enableHillshade()        // Enable hillshade layer
+terrainControl.disableHillshade()       // Disable hillshade layer
+terrainControl.toggleHillshade()        // Toggle hillshade layer
+terrainControl.update(options)
+terrainControl.getState()
+terrainControl.on('terrainchange', handler)  // Listen for terrain toggle
+```
+
+**Terrain Source:**
+The control uses free terrain tiles from AWS:
+- URL: `https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png`
+- Encoding: Terrarium RGB-encoded elevation data
+- No API key required
+
 ## Built-in Colormaps
 
 ### Sequential
@@ -293,15 +440,67 @@ const colorbar = new Colorbar({
 });
 ```
 
+## Zoom-based Visibility
+
+All components support `minzoom` and `maxzoom` options to control visibility based on the map's zoom level. This is useful for showing different legends at different zoom levels, similar to how map layers work.
+
+```typescript
+// Show legend only when zoomed in (zoom >= 10)
+const detailLegend = new Legend({
+  title: 'Detailed Features',
+  items: [...],
+  minzoom: 10,  // Only visible at zoom 10 and above
+});
+
+// Show legend only when zoomed out (zoom <= 8)
+const overviewLegend = new Legend({
+  title: 'Overview',
+  items: [...],
+  maxzoom: 8,  // Only visible at zoom 8 and below
+});
+
+// Show colorbar only within a specific zoom range
+const colorbar = new Colorbar({
+  colormap: 'viridis',
+  vmin: 0,
+  vmax: 100,
+  minzoom: 5,   // Visible from zoom 5...
+  maxzoom: 15,  // ...up to zoom 15
+});
+```
+
+### React Example
+
+```tsx
+<LegendReact
+  map={map}
+  title="Lidar Point Cloud"
+  items={[
+    { label: 'QL0 (Approx. <= 0.35m NPS)', color: '#003300' },
+    { label: 'QL1 (Approx. 0.35m NPS)', color: '#006600' },
+    { label: 'QL2 (Approx. 0.7m NPS)', color: '#00cc00' },
+    { label: 'QL3 (Approx. 1.4m NPS)', color: '#ccff00' },
+    { label: 'Other', color: '#99ccff' },
+  ]}
+  minzoom={8}
+  maxzoom={18}
+  position="top-left"
+/>
+```
+
+**Note:** The `visible` option takes precedence - if `visible` is `false`, the component will be hidden regardless of zoom level.
+
 ## React Hooks
 
 ```typescript
-import { useColorbar, useLegend, useHtmlControl } from 'maplibre-gl-components/react';
+import { useColorbar, useLegend, useHtmlControl, useBasemap, useTerrain } from 'maplibre-gl-components/react';
 
 function MyComponent() {
   const colorbar = useColorbar({ colormap: 'viridis', vmin: 0, vmax: 100 });
   const legend = useLegend({ items: [...] });
   const htmlControl = useHtmlControl({ html: '...' });
+  const basemap = useBasemap({ selectedBasemap: 'OpenStreetMap.Mapnik' });
+  const terrain = useTerrain({ enabled: false, exaggeration: 1.5 });
 
   return (
     <>
@@ -311,9 +510,25 @@ function MyComponent() {
       <button onClick={() => legend.toggle()}>
         Toggle Legend
       </button>
-      <button onClick={() => htmlControl.setHtml('<div>Updated!</div>')}>
-        Update HTML
+      <button onClick={() => basemap.setBasemap('CartoDB.Positron')}>
+        Change Basemap
       </button>
+      <button onClick={() => terrain.toggle()}>
+        Toggle Terrain
+      </button>
+
+      <TerrainReact
+        map={map}
+        enabled={terrain.state.enabled}
+        exaggeration={terrain.state.exaggeration}
+        onTerrainChange={(enabled) => terrain.setEnabled(enabled)}
+      />
+
+      <BasemapReact
+        map={map}
+        defaultBasemap={basemap.state.selectedBasemap}
+        onBasemapChange={(b) => basemap.setBasemap(b.id)}
+      />
 
       <ColorbarReact
         map={map}
@@ -347,6 +562,16 @@ The default styles can be customized using CSS:
 .maplibre-gl-html-control {
   max-width: 400px;
 }
+
+/* Override basemap control styles */
+.maplibre-gl-basemap {
+  max-width: 300px;
+}
+
+/* Override terrain control styles */
+.maplibre-gl-terrain-button {
+  color: #0078d7;
+}
 ```
 
 ## Examples