maplibre-gl-components 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # maplibre-gl-components
 
-Legend, colorbar, basemap switcher, terrain toggle, 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)
@@ -11,6 +11,9 @@ Legend, colorbar, basemap switcher, terrain toggle, and HTML control components
 - **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
@@ -29,7 +32,7 @@ npm install maplibre-gl-components
 
 ```typescript
 import maplibregl from 'maplibre-gl';
-import { Colorbar, Legend, HtmlControl, BasemapControl, TerrainControl } 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({
@@ -46,6 +49,24 @@ const terrainControl = new TerrainControl({
 });
 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',
@@ -92,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, BasemapReact, TerrainReact } 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() {
@@ -121,6 +142,22 @@ 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}
@@ -344,6 +381,147 @@ basemapControl.on('basemapchange', handler)  // Listen for basemap changes
 - 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.
@@ -388,6 +566,78 @@ The control uses free terrain tiles from AWS:
 - 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
@@ -493,7 +743,7 @@ const colorbar = new Colorbar({
 ## React Hooks
 
 ```typescript
-import { useColorbar, useLegend, useHtmlControl, useBasemap, useTerrain } 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 });
@@ -501,6 +751,8 @@ function MyComponent() {
   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 (
     <>
@@ -516,6 +768,15 @@ function MyComponent() {
       <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}
@@ -572,6 +833,24 @@ The default styles can be customized using CSS:
 .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