maplibre-gl-components 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open Geospatial Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,380 @@
+# maplibre-gl-components
+
+Legend, colorbar, 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)
+
+## Features
+
+- **Colorbar** - Continuous gradient legends with built-in matplotlib colormaps
+- **Legend** - Categorical legends with color swatches and labels
+- **HtmlControl** - Flexible HTML content control for custom info panels
+- **React Support** - First-class React components and hooks
+- **TypeScript** - Full type definitions included
+- **20+ Built-in Colormaps** - viridis, plasma, terrain, jet, and more
+
+## Installation
+
+```bash
+npm install maplibre-gl-components
+```
+
+## Quick Start
+
+### Vanilla JavaScript/TypeScript
+
+```typescript
+import maplibregl from 'maplibre-gl';
+import { Colorbar, Legend, HtmlControl } from 'maplibre-gl-components';
+import 'maplibre-gl-components/style.css';
+
+const map = new maplibregl.Map({
+  container: 'map',
+  style: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
+  center: [-98, 38.5],
+  zoom: 4,
+});
+
+// Add a colorbar
+const colorbar = new Colorbar({
+  colormap: 'viridis',
+  vmin: 0,
+  vmax: 100,
+  label: 'Temperature',
+  units: '°C',
+  orientation: 'vertical',
+});
+map.addControl(colorbar, 'bottom-right');
+
+// Add a legend
+const legend = new Legend({
+  title: 'Land Cover',
+  items: [
+    { label: 'Forest', color: '#228B22' },
+    { label: 'Water', color: '#4169E1' },
+    { label: 'Urban', color: '#808080' },
+  ],
+  collapsible: true,
+});
+map.addControl(legend, 'bottom-left');
+
+// Add an HTML control
+const htmlControl = new HtmlControl({
+  html: '<div><strong>Stats:</strong> 1,234 features</div>',
+});
+map.addControl(htmlControl, 'top-left');
+
+// Update HTML dynamically
+htmlControl.setHtml('<div><strong>Stats:</strong> 5,678 features</div>');
+```
+
+### React
+
+```tsx
+import { useState, useEffect, useRef } from 'react';
+import maplibregl from 'maplibre-gl';
+import { ColorbarReact, LegendReact, HtmlControlReact } from 'maplibre-gl-components/react';
+import 'maplibre-gl-components/style.css';
+
+function MyMap() {
+  const mapContainer = useRef<HTMLDivElement>(null);
+  const [map, setMap] = useState<maplibregl.Map | null>(null);
+  const [stats, setStats] = useState('Loading...');
+
+  useEffect(() => {
+    if (!mapContainer.current) return;
+
+    const mapInstance = new maplibregl.Map({
+      container: mapContainer.current,
+      style: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
+      center: [-98, 38.5],
+      zoom: 4,
+    });
+
+    mapInstance.on('load', () => setMap(mapInstance));
+
+    return () => mapInstance.remove();
+  }, []);
+
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <div ref={mapContainer} style={{ width: '100%', height: '100%' }} />
+
+      {map && (
+        <>
+          <ColorbarReact
+            map={map}
+            colormap="viridis"
+            vmin={0}
+            vmax={100}
+            label="Temperature"
+            units="°C"
+            position="bottom-right"
+          />
+
+          <LegendReact
+            map={map}
+            title="Categories"
+            items={[
+              { label: 'Low', color: '#2166ac' },
+              { label: 'High', color: '#b2182b' },
+            ]}
+            position="bottom-left"
+            collapsible
+          />
+
+          <HtmlControlReact
+            map={map}
+            html={`<div><strong>Stats:</strong> ${stats}</div>`}
+            position="top-left"
+          />
+        </>
+      )}
+    </div>
+  );
+}
+```
+
+## API Reference
+
+### Colorbar
+
+A continuous gradient colorbar control.
+
+```typescript
+interface ColorbarOptions {
+  colormap?: ColormapName | string[];  // Colormap name or custom colors
+  colorStops?: ColorStop[];            // Fine-grained color control
+  vmin?: number;                       // Minimum value (default: 0)
+  vmax?: number;                       // Maximum value (default: 1)
+  label?: string;                      // Title/label
+  units?: string;                      // Units suffix
+  orientation?: 'horizontal' | 'vertical';
+  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  barThickness?: number;               // Bar width/height in pixels
+  barLength?: number;                  // Bar length in pixels
+  ticks?: { count?: number; values?: number[]; format?: (v: number) => string };
+  visible?: boolean;
+  backgroundColor?: string;
+  opacity?: number;
+  fontSize?: number;
+  fontColor?: string;
+}
+
+// Methods
+colorbar.show()
+colorbar.hide()
+colorbar.update(options)
+colorbar.getState()
+colorbar.on(event, handler)
+colorbar.off(event, handler)
+```
+
+### Legend
+
+A categorical legend control.
+
+```typescript
+interface LegendOptions {
+  title?: string;
+  items?: LegendItem[];                // { label, color, shape?, icon? }
+  position?: ControlPosition;
+  visible?: boolean;
+  collapsible?: boolean;
+  collapsed?: boolean;
+  width?: number;
+  maxHeight?: number;
+  swatchSize?: number;
+  backgroundColor?: string;
+  opacity?: number;
+  fontSize?: number;
+  fontColor?: string;
+}
+
+interface LegendItem {
+  label: string;
+  color: string;
+  shape?: 'square' | 'circle' | 'line';
+  strokeColor?: string;
+  icon?: string;                       // URL to icon image
+}
+
+// Methods
+legend.show()
+legend.hide()
+legend.expand()
+legend.collapse()
+legend.toggle()
+legend.setItems(items)
+legend.addItem(item)
+legend.removeItem(label)
+legend.update(options)
+legend.getState()
+```
+
+### HtmlControl
+
+A flexible HTML content control.
+
+```typescript
+interface HtmlControlOptions {
+  html?: string;                       // HTML content
+  element?: HTMLElement;               // Or provide a DOM element
+  position?: ControlPosition;
+  visible?: boolean;
+  backgroundColor?: string;
+  padding?: number;
+  borderRadius?: number;
+  opacity?: number;
+  maxWidth?: number;
+  maxHeight?: number;
+}
+
+// Methods
+htmlControl.show()
+htmlControl.hide()
+htmlControl.setHtml(html)              // Update HTML content
+htmlControl.setElement(element)        // Set DOM element
+htmlControl.getElement()               // Get content container
+htmlControl.update(options)
+htmlControl.getState()
+```
+
+## Built-in Colormaps
+
+### Sequential
+- `viridis` - Perceptually uniform, colorblind-friendly
+- `plasma` - Perceptually uniform
+- `inferno` - Perceptually uniform
+- `magma` - Perceptually uniform
+- `cividis` - Colorblind-friendly
+
+### Diverging
+- `coolwarm` - Blue to red through white
+- `bwr` - Blue-white-red
+- `seismic` - Blue to red
+- `RdBu` - Red to blue
+- `RdYlBu` - Red-yellow-blue
+- `RdYlGn` - Red-yellow-green
+- `spectral` - Rainbow-like diverging
+
+### Miscellaneous
+- `jet` - Classic rainbow
+- `rainbow` - Full spectrum
+- `turbo` - Improved rainbow
+- `terrain` - Elevation-like
+- `ocean` - Ocean depths
+- `hot` - Black-red-yellow-white
+- `cool` - Cyan to magenta
+- `gray` - Grayscale
+- `bone` - Blue-tinted grayscale
+
+### Custom Colors
+
+```typescript
+// Use an array of colors
+const colorbar = new Colorbar({
+  colormap: ['#0000ff', '#00ff00', '#ffff00', '#ff0000'],
+  vmin: 0,
+  vmax: 100,
+});
+
+// Or use color stops for precise control
+const colorbar = new Colorbar({
+  colorStops: [
+    { position: 0, color: '#0000ff' },
+    { position: 0.3, color: '#00ff00' },
+    { position: 0.7, color: '#ffff00' },
+    { position: 1, color: '#ff0000' },
+  ],
+  vmin: 0,
+  vmax: 100,
+});
+```
+
+## React Hooks
+
+```typescript
+import { useColorbar, useLegend, useHtmlControl } from 'maplibre-gl-components/react';
+
+function MyComponent() {
+  const colorbar = useColorbar({ colormap: 'viridis', vmin: 0, vmax: 100 });
+  const legend = useLegend({ items: [...] });
+  const htmlControl = useHtmlControl({ html: '...' });
+
+  return (
+    <>
+      <button onClick={() => colorbar.setColormap('plasma')}>
+        Change Colormap
+      </button>
+      <button onClick={() => legend.toggle()}>
+        Toggle Legend
+      </button>
+      <button onClick={() => htmlControl.setHtml('<div>Updated!</div>')}>
+        Update HTML
+      </button>
+
+      <ColorbarReact
+        map={map}
+        {...colorbar.state}
+        vmin={colorbar.state.vmin}
+        vmax={colorbar.state.vmax}
+      />
+    </>
+  );
+}
+```
+
+## Styling
+
+The default styles can be customized using CSS:
+
+```css
+/* Override colorbar styles */
+.maplibre-gl-colorbar {
+  background: rgba(0, 0, 0, 0.8);
+  color: white;
+}
+
+/* Override legend styles */
+.maplibre-gl-legend {
+  font-size: 14px;
+  border-radius: 8px;
+}
+
+/* Override HTML control styles */
+.maplibre-gl-html-control {
+  max-width: 400px;
+}
+```
+
+## Examples
+
+See the [examples](./examples/) directory for complete working examples:
+
+- **Basic Example** - Vanilla TypeScript with all three components
+- **React Example** - React with hooks and dynamic updates
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Run tests
+npm test
+
+# Build for production
+npm run build
+
+# Build examples
+npm run build:examples
+```
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.