maplibre-gl-components 0.3.0 → 0.5.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, search, vector data loader, feature inspector, 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,6 +9,11 @@ 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
+- **SearchControl** - Collapsible place search with geocoding and fly-to functionality
+- **VectorDatasetControl** - Load GeoJSON files via file upload or drag-and-drop
+- **InspectControl** - Click on features to view their properties/attributes
 - **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
@@ -27,7 +32,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, SearchControl, VectorDatasetControl } from 'maplibre-gl-components';
 import 'maplibre-gl-components/style.css';
 
 const map = new maplibregl.Map({
@@ -37,6 +42,39 @@ 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 search control
+const searchControl = new SearchControl({
+  placeholder: 'Search for a place...',
+  flyToZoom: 14,
+  showMarker: true,
+});
+map.addControl(searchControl, 'top-right');
+
+// Add a vector dataset loader (file upload and drag-drop)
+const vectorControl = new VectorDatasetControl({
+  fitBounds: true,
+});
+map.addControl(vectorControl, 'top-left');
+
+vectorControl.on('load', (event) => {
+  console.log('Loaded:', event.dataset?.filename);
+});
+
+// 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',
@@ -75,7 +113,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, SearchControlReact, VectorDatasetReact } from 'maplibre-gl-components/react';
 import 'maplibre-gl-components/style.css';
 
 function MyMap() {
@@ -104,6 +142,38 @@ function MyMap() {
 
       {map && (
         <>
+          <VectorDatasetReact
+            map={map}
+            fitBounds
+            position="top-left"
+            onDatasetLoad={(dataset) => console.log('Loaded:', dataset.filename)}
+          />
+
+          <SearchControlReact
+            map={map}
+            placeholder="Search for a place..."
+            flyToZoom={14}
+            showMarker
+            position="top-right"
+            onResultSelect={(result) => console.log('Selected:', result.name)}
+          />
+
+          <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"
@@ -248,6 +318,326 @@ 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
+
+### SearchControl
+
+A collapsible place search control with geocoding support.
+
+```typescript
+interface SearchControlOptions {
+  position?: ControlPosition;
+  visible?: boolean;                     // Default: true
+  collapsed?: boolean;                   // Start collapsed (icon only). Default: true
+  placeholder?: string;                  // Search input placeholder. Default: 'Search places...'
+  geocoderUrl?: string;                  // Geocoding API URL. Default: Nominatim
+  maxResults?: number;                   // Max results to show. Default: 5
+  debounceMs?: number;                   // Debounce delay in ms. Default: 300
+  flyToZoom?: number;                    // Zoom level when selecting result. Default: 14
+  showMarker?: boolean;                  // Show marker at selected location. Default: true
+  markerColor?: string;                  // Marker color. Default: '#4264fb'
+  collapseOnSelect?: boolean;            // Collapse after selecting. Default: true
+  clearOnSelect?: boolean;               // Clear results after selecting. Default: true
+  geocoder?: (query: string) => Promise<SearchResult[]>;  // Custom geocoder function
+  backgroundColor?: string;
+  borderRadius?: number;
+  opacity?: number;
+  width?: number;                        // Expanded width in pixels. Default: 280
+  fontSize?: number;
+  fontColor?: string;
+  minzoom?: number;
+  maxzoom?: number;
+}
+
+interface SearchResult {
+  id: string;                            // Unique identifier
+  name: string;                          // Place name
+  displayName: string;                   // Full display name with address
+  lng: number;                           // Longitude
+  lat: number;                           // Latitude
+  bbox?: [number, number, number, number];  // Bounding box [west, south, east, north]
+  type?: string;                         // Place type (city, street, etc.)
+  importance?: number;                   // Relevance score
+}
+
+// Methods
+searchControl.show()
+searchControl.hide()
+searchControl.expand()                   // Expand to show input
+searchControl.collapse()                 // Collapse to icon only
+searchControl.toggle()                   // Toggle expanded/collapsed
+searchControl.search(query)              // Perform a search
+searchControl.selectResult(result)       // Select a result and fly to it
+searchControl.clear()                    // Clear search and marker
+searchControl.update(options)
+searchControl.getState()
+searchControl.on('resultselect', handler)  // Listen for result selection
+searchControl.on('search', handler)        // Listen for search completion
+searchControl.on('clear', handler)         // Listen for clear events
+```
+
+**Geocoding:**
+By default, SearchControl uses [Nominatim](https://nominatim.openstreetmap.org/) (OpenStreetMap) for geocoding, which is free and requires no API key. You can also provide a custom geocoder function for other services.
+
+```typescript
+// Using custom geocoder
+const searchControl = new SearchControl({
+  geocoder: async (query) => {
+    const response = await fetch(`https://my-geocoder.com/search?q=${query}`);
+    const data = await response.json();
+    return data.map(item => ({
+      id: item.id,
+      name: item.name,
+      displayName: item.address,
+      lng: item.longitude,
+      lat: item.latitude,
+    }));
+  },
+});
+```
+
+### VectorDatasetControl
+
+A control for loading GeoJSON files via file upload button or drag-and-drop.
+
+```typescript
+interface VectorDatasetControlOptions {
+  position?: ControlPosition;
+  visible?: boolean;                     // Default: true
+  showDropZone?: boolean;                // Show overlay when dragging. Default: true
+  acceptedExtensions?: string[];         // File extensions. Default: ['.geojson', '.json']
+  multiple?: boolean;                    // Allow multiple files. Default: true
+  defaultStyle?: VectorLayerStyle;       // Default styling for loaded layers
+  fitBounds?: boolean;                   // Fit map to loaded data. Default: true
+  fitBoundsPadding?: number;             // Padding for fitBounds. Default: 50
+  maxFileSize?: number;                  // Max file size in bytes. Default: 50MB
+  backgroundColor?: string;
+  borderRadius?: number;
+  opacity?: number;
+  minzoom?: number;
+  maxzoom?: number;
+}
+
+interface VectorLayerStyle {
+  fillColor?: string;                    // Polygon fill. Default: '#3388ff'
+  fillOpacity?: number;                  // Polygon fill opacity. Default: 0.3
+  strokeColor?: string;                  // Line/outline color. Default: '#3388ff'
+  strokeWidth?: number;                  // Line width. Default: 2
+  strokeOpacity?: number;                // Line opacity. Default: 1
+  circleRadius?: number;                 // Point radius. Default: 6
+  circleColor?: string;                  // Point color. Default: '#3388ff'
+  circleStrokeColor?: string;            // Point outline. Default: '#ffffff'
+  circleStrokeWidth?: number;            // Point outline width. Default: 2
+}
+
+interface LoadedDataset {
+  id: string;                            // Unique ID
+  filename: string;                      // Original filename
+  sourceId: string;                      // MapLibre source ID
+  layerIds: string[];                    // MapLibre layer IDs
+  featureCount: number;                  // Number of features
+  geometryTypes: string[];               // Geometry types present
+  loadedAt: Date;                        // When loaded
+}
+
+// Methods
+vectorControl.show()
+vectorControl.hide()
+vectorControl.getLoadedDatasets()        // Get all loaded datasets
+vectorControl.removeDataset(id)          // Remove a dataset by ID
+vectorControl.removeAllDatasets()        // Remove all datasets
+vectorControl.loadGeoJSON(geojson, filename)  // Programmatically load GeoJSON
+vectorControl.update(options)
+vectorControl.getState()
+vectorControl.on('load', handler)        // Fired when a dataset is loaded
+vectorControl.on('error', handler)       // Fired when an error occurs
+```
+
+**Loading Methods:**
+- Click the upload button to open a file picker
+- Drag and drop GeoJSON files directly onto the map
+
+**Supported Formats:**
+- GeoJSON (.geojson, .json)
+- FeatureCollection, Feature, or raw Geometry objects
+
+### 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
+
+### InspectControl
+
+A control for inspecting vector features on the map. Click on features to view their properties/attributes in a popup.
+
+```typescript
+interface InspectControlOptions {
+  position?: ControlPosition;
+  visible?: boolean;                     // Default: true
+  enabled?: boolean;                     // Start with inspect mode on. Default: false
+  maxFeatures?: number;                  // Max features at click point. Default: 10
+  includeLayers?: string[];              // Only inspect these layers
+  excludeLayers?: string[];              // Skip these layers
+  highlightStyle?: InspectHighlightStyle; // Style for selected feature
+  excludeProperties?: string[];          // Properties to hide (e.g., internal IDs)
+  showGeometryType?: boolean;            // Show geometry type badge. Default: true
+  showLayerName?: boolean;               // Show layer name. Default: true
+  maxWidth?: number;                     // Popup max width. Default: 320
+  maxHeight?: number;                    // Popup content max height. Default: 300
+  backgroundColor?: string;
+  borderRadius?: number;
+  opacity?: number;
+  fontSize?: number;
+  fontColor?: string;
+  minzoom?: number;
+  maxzoom?: number;
+}
+
+interface InspectHighlightStyle {
+  fillColor?: string;                    // Polygon fill. Default: '#ffff00'
+  fillOpacity?: number;                  // Polygon fill opacity. Default: 0.3
+  strokeColor?: string;                  // Line/outline color. Default: '#ffff00'
+  strokeWidth?: number;                  // Line width. Default: 3
+  circleRadius?: number;                 // Point radius. Default: 10
+  circleStrokeWidth?: number;            // Point outline. Default: 3
+}
+
+interface InspectedFeature {
+  id: string;                            // Unique inspection ID
+  feature: GeoJSON.Feature;              // The GeoJSON feature
+  layerId: string;                       // MapLibre layer ID
+  sourceId: string;                      // MapLibre source ID
+  lngLat: [number, number];              // Click coordinates
+}
+
+// Methods
+inspectControl.show()
+inspectControl.hide()
+inspectControl.enable()                  // Enable inspect mode
+inspectControl.disable()                 // Disable inspect mode
+inspectControl.toggle()                  // Toggle inspect mode on/off
+inspectControl.isEnabled()               // Check if inspect mode is enabled
+inspectControl.clear()                   // Clear current inspection
+inspectControl.getInspectedFeatures()    // Get all features at click point
+inspectControl.getSelectedFeature()      // Get currently selected feature
+inspectControl.selectFeature(index)      // Select feature by index
+inspectControl.nextFeature()             // Navigate to next feature
+inspectControl.previousFeature()         // Navigate to previous feature
+inspectControl.update(options)
+inspectControl.getState()
+inspectControl.on('enable', handler)     // Fired when inspect mode is enabled
+inspectControl.on('disable', handler)    // Fired when inspect mode is disabled
+inspectControl.on('featureselect', handler)  // Fired when a feature is selected
+inspectControl.on('clear', handler)      // Fired when inspection is cleared
+```
+
+**Usage:**
+1. Click the info button to enable inspect mode
+2. Click on any vector feature on the map
+3. View properties in the popup
+4. Use < > buttons to navigate when multiple features are at the same location
+5. Click elsewhere or the button again to disable
+
 ## Built-in Colormaps
 
 ### Sequential
@@ -353,12 +743,16 @@ const colorbar = new Colorbar({
 ## React Hooks
 
 ```typescript
-import { useColorbar, useLegend, useHtmlControl } from 'maplibre-gl-components/react';
+import { useColorbar, useLegend, useHtmlControl, useBasemap, useTerrain, useSearchControl, useVectorDataset } 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 });
+  const search = useSearchControl({ collapsed: true });
+  const vectorDataset = useVectorDataset();
 
   return (
     <>
@@ -368,10 +762,35 @@ 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>
+      <button onClick={() => search.toggle()}>
+        Toggle Search
       </button>
 
+      <SearchControlReact
+        map={map}
+        collapsed={search.state.collapsed}
+        onResultSelect={(result) => search.selectResult(result)}
+      />
+
+      <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}
         {...colorbar.state}
@@ -404,6 +823,34 @@ 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;
+}
+
+/* Override search control styles */
+.maplibre-gl-search {
+  background: rgba(255, 255, 255, 0.95);
+}
+
+.maplibre-gl-search-toggle:hover {
+  color: #0078d7;
+}
+
+/* Override vector dataset control styles */
+.maplibre-gl-vector-dataset-button:hover {
+  color: #0078d7;
+}
+
+.maplibre-gl-vector-dataset-dropzone {
+  background: rgba(0, 120, 215, 0.2);
+}
 ```
 
 ## Examples