maplibre-gl-components 0.12.2 → 0.14.0

package/README.md

@@ -29,6 +29,7 @@ Legend, colorbar, basemap switcher, terrain toggle, search, vector data loader,
 - **MinimapControl** - Inset overview map showing the current viewport extent with optional click-to-navigate
 - **ControlGrid** - Collapsible toolbar grid that hosts any combination of built-in and plugin controls
 - **addControlGrid** - One-call convenience function to add all default controls with customization
+- **Three.js Integration** - Re-exported helpers (`MapScene`, `SceneTransform`, `Sun`, `Creator`) from `@dvt3d/maplibre-three-plugin`
 - **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
@@ -1316,6 +1317,8 @@ interface PrintControlOptions {
   quality?: number;                    // JPEG quality 0-1 (default: 0.92)
   filename?: string;                   // Default filename without extension (default: 'map-export')
   title?: string;                      // Optional title rendered on the image
+  includeNorthArrow?: boolean;         // Include north arrow in export (default: false)
+  includeScaleBar?: boolean;           // Include scale bar in export (default: false)
   titleFontSize?: number;              // Title font size in pixels (default: 24)
   titleFontColor?: string;             // Title font color (default: '#333333')
   titleBackground?: string;            // Title background (default: 'rgba(255,255,255,0.8)')
@@ -1354,6 +1357,8 @@ const printControl = new PrintControl({
   filename: "my-map",
   format: "png",
   title: "My Map Title",
+  includeNorthArrow: true,
+  includeScaleBar: true,
 });
 map.addControl(printControl, "top-right");
 
@@ -1367,6 +1372,8 @@ const dataUrl = await printControl.exportMap({
   format: "jpeg",
   quality: 0.95,
   title: "Custom Title",
+  includeNorthArrow: true,
+  includeScaleBar: true,
 });
 
 // Export as PDF (requires jspdf)
@@ -1377,6 +1384,7 @@ await printControl.exportMap({ format: "pdf" });
 
 - Export as PNG, JPEG, or PDF
 - Optional title overlay rendered on the exported image
+- Optional north arrow and scale bar overlays in exported output
 - Customizable filename, quality, and export size
 - Copy to clipboard (PNG/JPEG only)
 - PDF export with auto landscape/portrait detection, fitted to A4 page
@@ -1473,6 +1481,7 @@ interface ControlGridOptions {
   gap?: number;                           // Gap between cells in pixels (default: 6)
   basemapStyleUrl?: string;               // Basemap style URL for SwipeControl
   excludeLayers?: string[];               // Layer patterns to exclude from SwipeControl
+  streetViewOptions?: Partial<StreetViewControlOptions>; // Optional API keys and StreetView config overrides
   backgroundColor?: string;
   padding?: number;
   borderRadius?: number;
@@ -1484,6 +1493,17 @@ interface ControlGridOptions {
 
 **Available default controls:** `fullscreen`, `globe`, `north`, `terrain`, `search`, `viewState`, `inspect`, `vectorDataset`, `basemap`, `cogLayer`, `minimap`, `measure`, `bookmark`, `print`, `zarrLayer`, `pmtilesLayer`, `stacLayer`, `stacSearch`, `addVector`, `geoEditor`, `lidar`, `planetaryComputer`, `gaussianSplat`, `streetView`, `swipe`, `usgsLidar`
 
+**StreetView env setup (for `streetView` default control):**
+
+```bash
+# .env
+VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key
+VITE_MAPILLARY_ACCESS_TOKEN=your_mapillary_access_token
+```
+
+`ControlGrid` auto-reads these values for the built-in `streetView` control. You can also override explicitly with `streetViewOptions`.
+Mapillary viewer CSS is bundled by `maplibre-gl-components`, so no extra `mapillary-js` CSS import is needed.
+
 ```typescript
 // Methods
 controlGrid.addControl(control)       // Add a control to the grid
@@ -1513,6 +1533,11 @@ const controlGrid = new ControlGrid({
   collapsible: true,
   collapsed: true,
   basemapStyleUrl: "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
+  streetViewOptions: {
+    // Optional explicit override (otherwise auto-read from VITE_* env vars)
+    googleApiKey: import.meta.env.VITE_GOOGLE_MAPS_API_KEY,
+    mapillaryAccessToken: import.meta.env.VITE_MAPILLARY_ACCESS_TOKEN,
+  },
   defaultControls: [
     "globe", "fullscreen", "north", "terrain", "search",
     "viewState", "inspect", "basemap", "measure", "bookmark",
@@ -1875,7 +1900,7 @@ See the [examples](./examples/) directory for complete working examples:
 - **Minimap Control Example** - Inset overview map with viewport rectangle
 - **Control Grid Example** - ControlGrid with all built-in and plugin controls
 - **addControlGrid Example** - One-call convenience function with all default controls
-
+- **Three.js Plugin Example** - Integrate `MapScene` from maplibre-three-plugin with a rotating 3D object
 
 ## Development