geo-morpher 0.1.0 → 0.1.1

package/README.md

@@ -1,24 +1,25 @@
 # geo-morpher
 
-Imperative GeoJSON morphing utilities for animating between regular geography and cartograms, packaged as a native JavaScript library with a MapLibre-first adapter and optional Leaflet helpers for DOM-heavy experiences.
+[![npm version](https://badge.fury.io/js/geo-morpher.svg)](https://badge.fury.io/js/geo-morpher)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+GeoJSON morphing utilities for animating between regular geography and cartograms, packaged as a native JavaScript library with a MapLibre-first adapter and Leaflet compatibility helpers.
 
 ![](demo.gif)
 
 
+## Status
+
+This library is currently in early-stage development (v0.1.0) and has recently completed a migration to a MapLibre-first adapter. The core morphing engine is stable, but the MapLibre adapter is new and under active development. Leaflet compatibility is maintained. Community feedback and contributions are welcome.
+
+
 ## Installation
 
 ```bash
 npm install geo-morpher
 ```
 
-Bring your own MapLibre or Leaflet instance (both listed as peer dependencies). MapLibre is the default rendering path and ships with GPU-accelerated layers; Leaflet stays available when you need direct DOM access.
-
-### Choosing an adapter
-
-- MapLibre adapter (`createMapLibreMorphLayers`, `createMapLibreGlyphLayer`) is the default. Use it for performance, style expression control, and WebGL-based effects.
-- Leaflet adapter (`createLeafletMorphLayers`, `createLeafletGlyphLayer`) remains supported for teams who want to manipulate markers, tooltips, or UI directly in the DOM.
-- Both adapters share the same `GeoMorpher` core, so you can swap adapters without recalculating morph data.
-- Examples under `examples/browser/` demonstrate both integrations; switch adapters by loading the corresponding entry point.
+Bring your own MapLibre or Leaflet instance (both listed as peer dependencies). MapLibre is the default adapter; Leaflet remains supported for backward compatibility.
 
 ## Usage
 
@@ -31,24 +32,17 @@ src/
   lib/             # Shared runtime utilities (OSGB projection)
   utils/           # Data enrichment and projection helpers
 data/              # Sample Oxford LSOA datasets
-examples/          # Runnable native JS scripts
+examples/          # Runnable browser demos (MapLibre & Leaflet)
 test/              # node:test coverage for core behaviours
 ```
 
-### MapLibre adapter
+### MapLibre adapter (default)
 
 - `createMapLibreMorphLayers` provisions GeoJSON sources and fill layers for regular, cartogram, and interpolated geometries, exposing an `updateMorphFactor` helper to drive tweening from UI controls.
 - `createMapLibreGlyphLayer` renders glyphs with `maplibregl.Marker` instances; enable `scaleWithZoom` to regenerate glyph markup as users zoom.
 - Pass your MapLibre namespace explicitly (`maplibreNamespace: maplibregl`) when calling glyph helpers in module-bundled builds where `maplibregl` is not attached to `globalThis`.
 - For heavy glyph scenes, consider upgrading to a [CustomLayerInterface](https://www.maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/) implementation that batches drawing on the GPU. The marker pipeline keeps the API simple while offering a documented migration path.
-- Track ongoing enhancements and open items in `docs/maplibre-migration-plan.md` before adopting advanced features like custom shader glyphs.
-
-### Leaflet adapter
-
-- `createLeafletMorphLayers` keeps the existing DOM-centric workflow for basemap blur/fade effects and marker overlays.
-- `createLeafletGlyphLayer` accepts any HTML, SVG, Canvas, or Leaflet icon—handy when you need tooltips, popups, and other DOM components under full control.
-- The basemap effect still uses DOM filters (`blur`, `opacity`, `grayscale`) and can target any Leaflet layer container.
-- Stick with Leaflet when you require deep integration with existing Leaflet plugins or server-rendered markup; migrate to MapLibre later without touching your data preparation code.
+- Track ongoing enhancements and open items in `docs/maplibre-migration-plan.md` before relying on the adapter in production.
 
 #### MapLibre basemap effects
 
@@ -144,9 +138,9 @@ const customProjection = {
 };
 ```
 
-See `examples/custom-projection.js` for detailed examples.
+See `examples/maplibre/projections/index.html` for a browser-based custom projection demo.
 
-### 2. Drop the morph straight into Leaflet
+### 2. Drop the morph straight into Leaflet (compat)
 
 ```js
 import L from "leaflet";
@@ -195,6 +189,8 @@ Provide either `basemapLayer` (any Leaflet layer with a container) or `basemapEf
 
 The glyph system is **completely customizable** with no hardcoded chart types. You provide a rendering function that can return any visualization you can create with HTML, SVG, Canvas, or third-party libraries like D3.js or Chart.js. The helper automatically keeps markers positioned and synchronized with the morphing geometry.
 
+See the full glyphs guide: `docs/glyphs.md`
+
 **Example with pie charts:**
 
 ```js
@@ -276,7 +272,6 @@ By default `createLeafletGlyphLayer` will surface whatever the core `GeoMorpher`
 | field        | type     | description |
 |--------------|----------|-------------|
 | `feature`    | GeoJSON Feature | The rendered feature taken from the requested geography (`regular`, `cartogram`, or tweened). Includes `feature.properties` and a `centroid` array. |
-enum{} | Resolved via `getFeatureId(feature)` (defaults to `feature.properties.code ?? feature.properties.id`). |
 | `featureId`  | string  | Resolved via `getFeatureId(feature)` (defaults to `feature.properties.code ?? feature.properties.id`). |
 | `data`       | object \| null | When using the built-in lookup this is the morpher key entry: `{ code, population, data }`. The `data` property holds the *enriched* GeoJSON feature returned from `GeoMorpher.prepare()`—handy when you stored additional indicators during enrichment. |
 | `morpher`    | `GeoMorpher` | The instance you passed in, allowing on-demand queries (`getInterpolatedLookup`, etc.). |
@@ -439,7 +434,7 @@ When `scaleWithZoom` is enabled:
 - Glyphs automatically update when users zoom in/out
 - Call `glyphLayer.destroy()` to clean up zoom listeners when removing the layer
 
-A complete example is available at `examples/browser/zoom-scaling-glyphs.html`.
+A complete example is available at `examples/leaflet/zoom-scaling-glyphs.html`.
 
 ### Legacy wrapper
 
@@ -459,17 +454,11 @@ const result = await geoMorpher({
 console.log(result.tweenLookup);
 ```
 
-### Native JS example
+### Node script (removed)
 
-A runnable script using the bundled Oxford datasets lives in `examples/native.js`:
+The previous Node-only example has been removed in favor of browser-based demos under `examples/maplibre` and `examples/leaflet`.
 
-```bash
-node examples/native.js
-```
-
-It loads `data/oxford_lsoas_regular.json` and `data/oxford_lsoas_cartogram.json`, mirrors their population/household properties into a basic dataset, and prints counts plus a sample tweened feature—all without any bundlers or UI frameworks.
-
-### Native browser examples (Leaflet & MapLibre)
+### Native browser examples (MapLibre & Leaflet)
 
 Serve the browser demos to see geo-morpher running on top of either Leaflet or MapLibre without a build step. Dependencies are resolved via import maps to CDN-hosted ES modules.
 
@@ -478,14 +467,17 @@ npm run examples:browser
 ```
 
 Then open:
-- Leaflet demo: <http://localhost:4173/examples/browser/index.html>
-- MapLibre demo: <http://localhost:4173/examples/browser/maplibre/index.html>
+- MapLibre demo: <http://localhost:4173/examples/maplibre/index.html>
+- Indonesia (MapLibre): <http://localhost:4173/examples/maplibre/indonesia/index.html>
+- MapLibre (Projections): <http://localhost:4173/examples/maplibre/projections/index.html>
+- Leaflet demo: <http://localhost:4173/examples/leaflet/index.html>
+- Leaflet zoom-scaling: <http://localhost:4173/examples/leaflet/zoom-scaling-glyphs.html>
 
 Each demo provides a morph slider and glyph overlays; the MapLibre version showcases GPU-driven rendering, paint-property basemap fading, and DOM marker glyphs running through the new adapter. (An internet connection is required to fetch CDN-hosted modules and map tiles.)
 
 **Additional examples:**
-- `examples/browser/maplibre/index.html` - MapLibre adaptation with basemap paint-property effects and layer toggles
-- `examples/browser/zoom-scaling-glyphs.html` - Demonstrates zoom-responsive waffle charts that resize to fill cartogram polygons as you zoom in/out
+- `examples/maplibre/index.html` - MapLibre adaptation with basemap paint-property effects and layer toggles
+- `examples/leaflet/zoom-scaling-glyphs.html` - Demonstrates zoom-responsive waffle charts that resize to fill cartogram polygons as you zoom in/out
 
 ## Testing
 
@@ -495,19 +487,11 @@ Run the bundled smoke tests with:
 npm test
 ```
 
-## Build & publish
-
-- `npm run build` compiles ESM and CJS bundles to `dist/` via Rollup.
-- `npm run clean` removes the generated `dist/` folder prior to fresh builds.
-- Publishing runs `npm run build` automatically through the `prepare` hook; verify outputs before executing `npm publish`.
-
-## Roadmap & pending updates
-
-- GPU-batched glyph rendering via MapLibre `CustomLayerInterface` remains on the roadmap for high-volume scenes—follow progress in `docs/maplibre-migration-plan.md`.
-- Adapter-level automated tests (Jest + MapLibre mocks) are planned to complement the current core-only test suite.
-- Post-processing basemap effects (true blur, grayscale for vector tiles) are being explored as custom layers; today, stick to opacity/brightness tweaks via `basemapEffect`.
-- Globe projection support will land after the MapLibre adapter stabilizes on the current release line; expect a follow-up example once the API settles.
-
 ## License
 
 MIT
+
+## Documentation
+
+- API Reference: `docs/api.md`
+- Glyphs Guide: `docs/glyphs.md`

package/examples/README.md

@@ -0,0 +1,53 @@
+# Examples
+
+These examples are split by adapter. MapLibre is the default; Leaflet is provided for compatibility.
+
+## Structure
+
+- `examples/maplibre/` – MapLibre GL JS demos (default)
+- `examples/leaflet/` – Leaflet demos (compatibility)
+
+## Run
+
+```bash
+npm run examples:browser
+```
+
+Open in your browser:
+
+### MapLibre
+- `http://localhost:4173/examples/maplibre/index.html`
+- `http://localhost:4173/examples/maplibre/indonesia/index.html`
+- `http://localhost:4173/examples/maplibre/projections/index.html`
+
+### Leaflet
+- `http://localhost:4173/examples/leaflet/index.html`
+- `http://localhost:4173/examples/leaflet/zoom-scaling-glyphs.html`
+
+## Import maps
+
+All examples use import maps. Ensure the following mappings (adjust as needed):
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "leaflet": "https://cdn.jsdelivr.net/npm/leaflet@1.9.4/+esm",
+    "npm:leaflet": "https://cdn.jsdelivr.net/npm/leaflet@1.9.4/+esm",
+    "maplibre-gl": "https://esm.sh/maplibre-gl@5.8.0?bundle",
+    "@turf/turf": "https://esm.sh/@turf/turf@6.5.0?bundle",
+    "@turf/helpers": "https://esm.sh/@turf/helpers@6.5.0?bundle",
+    "flubber": "https://esm.sh/flubber@0.4.2?bundle",
+    "lodash/isEmpty.js": "https://esm.sh/lodash@4.17.21/isEmpty?bundle",
+    "lodash/cloneDeep.js": "https://esm.sh/lodash@4.17.21/cloneDeep?bundle",
+    "lodash/keyBy.js": "https://esm.sh/lodash@4.17.21/keyBy?bundle",
+    "lodash/mapValues.js": "https://esm.sh/lodash@4.17.21/mapValues?bundle"
+  }
+}
+</script>
+```
+
+Notes:
+- `@turf/turf` and `flubber` must use esm.sh with `?bundle`.
+- Leaflet works with jsDelivr `+esm`.
+- Raw Node examples have been converted; all demos are browser-based.

package/examples/{browser → leaflet}/index.html

@@ -183,7 +183,6 @@
         "imports": {
             "npm:leaflet": "https://esm.sh/leaflet@1.9.4",
           "@turf/turf": "https://esm.sh/@turf/turf@6.5.0?bundle",
-          "@turf/helpers": "https://esm.sh/@turf/helpers@6.5.0?bundle",
           "flubber": "https://esm.sh/flubber@0.4.2?bundle",
           "lodash/cloneDeep.js": "https://esm.sh/lodash@4.17.21/cloneDeep?bundle",
           "lodash/keyBy.js": "https://esm.sh/lodash@4.17.21/keyBy?bundle",
@@ -257,4 +256,6 @@
     <script type="module" src="./main.js"></script>
 </body>
 
-</html>
+</html>
+
+

package/examples/{browser → leaflet}/main.js

@@ -91,40 +91,6 @@ async function bootstrap() {
       }
     }
 
-    const createPieChartSVG = (slices, { size = 56, stroke = "white" } = {}) => {
-      const radius = size / 2;
-      const center = radius;
-
-      const total = slices.reduce((sum, slice) => sum + Math.max(0, slice.value), 0);
-      if (!Number.isFinite(total) || total <= 0) {
-        return `<svg width="${size}" height="${size}"></svg>`;
-      }
-
-      let currentAngle = -Math.PI / 2;
-      const segments = slices
-        .filter((slice) => Number.isFinite(slice.value) && slice.value > 0)
-        .map((slice) => {
-          const angle = (slice.value / total) * Math.PI * 2;
-          const endAngle = currentAngle + angle;
-          const largeArc = angle > Math.PI ? 1 : 0;
-          const startX = center + radius * Math.cos(currentAngle);
-          const startY = center + radius * Math.sin(currentAngle);
-          const endX = center + radius * Math.cos(endAngle);
-          const endY = center + radius * Math.sin(endAngle);
-          const path = [
-            `M ${center} ${center}`,
-            `L ${startX.toFixed(2)} ${startY.toFixed(2)}`,
-            `A ${radius} ${radius} 0 ${largeArc} 1 ${endX.toFixed(2)} ${endY.toFixed(2)}`,
-            "Z",
-          ].join(" ");
-          currentAngle = endAngle;
-          return `<path d="${path}" fill="${slice.color}" stroke="${stroke}" stroke-width="1"></path>`;
-        });
-
-      const content = segments.join("");
-      return `<svg width="${size}" height="${size}" viewBox="0 0 ${size} ${size}">${content}</svg>`;
-    };
-
     const { group, regularLayer, tweenLayer, cartogramLayer, updateMorphFactor } =
       await createLeafletMorphLayers({
         morpher,
@@ -168,11 +134,34 @@ async function bootstrap() {
           return null;
         }
 
+        const radius = 26;
+        const size = 52;
+        const center = radius;
+        let currentAngle = -Math.PI / 2;
+        const total = slices.reduce((sum, s) => sum + s.value, 0);
+        const segments = slices.map((slice) => {
+          const angle = (slice.value / total) * Math.PI * 2;
+          const endAngle = currentAngle + angle;
+          const largeArc = angle > Math.PI ? 1 : 0;
+          const startX = center + radius * Math.cos(currentAngle);
+          const startY = center + radius * Math.sin(currentAngle);
+          const endX = center + radius * Math.cos(endAngle);
+          const endY = center + radius * Math.sin(endAngle);
+          const path = [
+            `M ${center} ${center}`,
+            `L ${startX.toFixed(2)} ${startY.toFixed(2)}`,
+            `A ${radius} ${radius} 0 ${largeArc} 1 ${endX.toFixed(2)} ${endY.toFixed(2)}`,
+            "Z",
+          ].join(" ");
+          currentAngle = endAngle;
+          return `<path d="${path}" fill="${slice.color}" stroke="white" stroke-width="1"></path>`;
+        });
+
         return {
-          html: createPieChartSVG(slices, { size: 52 }),
+          html: `<svg width="${size}" height="${size}" viewBox="0 0 ${size} ${size}">${segments.join("")}</svg>`,
           className: "pie-chart-marker",
-          iconSize: [52, 52],
-          iconAnchor: [26, 26],
+          iconSize: [size, size],
+          iconAnchor: [radius, radius],
         };
       },
     });
@@ -223,3 +212,5 @@ async function bootstrap() {
 }
 
 bootstrap();
+
+

package/examples/leaflet/zoom-scaling-glyphs.html

@@ -0,0 +1,121 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Zoom-Scaling Glyphs Demo - geo-morpher</title>
+    <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            background: #0f172a;
+            color: #e2e8f0;
+            overflow: hidden;
+        }
+        #map { width: 100vw; height: 100vh; }
+        .controls {
+            position: absolute; top: 20px; right: 20px; background: rgba(15, 23, 42, 0.95);
+            padding: 20px; border-radius: 12px; box-shadow: 0 10px 40px rgba(0, 0, 0, 0.5);
+            z-index: 1000; max-width: 320px; backdrop-filter: blur(10px); border: 1px solid rgba(148, 163, 184, 0.1);
+        }
+        h1 { font-size: 1.25rem; font-weight: 700; margin-bottom: 8px; color: #f1f5f9; }
+        .subtitle { font-size: 0.875rem; color: #94a3b8; margin-bottom: 20px; line-height: 1.4; }
+        .control-group { margin-bottom: 20px; }
+        .control-group:last-child { margin-bottom: 0; }
+        label { display: block; font-size: 0.875rem; font-weight: 600; margin-bottom: 8px; color: #cbd5e1; }
+        input[type="range"] {
+            width: 100%; height: 6px; background: #334155; border-radius: 3px; outline: none; -webkit-appearance: none;
+        }
+        input[type="range"]::-webkit-slider-thumb {
+            -webkit-appearance: none; appearance: none; width: 18px; height: 18px; background: #22c55e;
+            border-radius: 50%; cursor: pointer; box-shadow: 0 2px 8px rgba(34, 197, 94, 0.4);
+        }
+        input[type="range"]::-moz-range-thumb {
+            width: 18px; height: 18px; background: #22c55e; border-radius: 50%; cursor: pointer; border: none;
+            box-shadow: 0 2px 8px rgba(34, 197, 94, 0.4);
+        }
+        .value-display { display: inline-block; margin-left: 8px; font-weight: 700; color: #22c55e; font-variant-numeric: tabular-nums; }
+        .checkbox-group { display: flex; align-items: center; margin-top: 12px; }
+        .checkbox-group input[type="checkbox"] { margin-right: 8px; width: 18px; height: 18px; cursor: pointer; }
+        .checkbox-group label { margin: 0; cursor: pointer; font-weight: 500; }
+        .info-box { background: rgba(34, 197, 94, 0.1); border: 1px solid rgba(34, 197, 94, 0.3); border-radius: 8px; padding: 12px; font-size: 0.875rem; line-height: 1.5; color: #a7f3d0; }
+        .status { position: absolute; bottom: 20px; left: 20px; background: rgba(15, 23, 42, 0.95);
+            padding: 12px 16px; border-radius: 8px; font-size: 0.875rem; z-index: 1000; backdrop-filter: blur(10px);
+            border: 1px solid rgba(148, 163, 184, 0.1); }
+        .waffle-glyph { pointer-events: none; }
+        .waffle-glyph rect { transition: fill 0.2s ease; }
+        .legend { position: absolute; bottom: 20px; right: 20px; background: rgba(15, 23, 42, 0.95); padding: 16px; border-radius: 8px; z-index: 1000; backdrop-filter: blur(10px); border: 1px solid rgba(148, 163, 184, 0.1); }
+        .legend h3 { font-size: 0.875rem; font-weight: 600; margin-bottom: 12px; color: #f1f5f9; }
+        .legend-item { display: flex; align-items: center; margin-bottom: 8px; font-size: 0.8rem; }
+        .legend-item:last-child { margin-bottom: 0; }
+        .legend-square { width: 16px; height: 16px; margin-right: 8px; border: 1px solid rgba(255, 255, 255, 0.2); }
+    </style>
+</head>
+
+<body>
+    <div id="map"></div>
+
+    <div class="controls">
+        <h1>Zoom-Scaling Glyphs</h1>
+        <p class="subtitle">Waffle charts that resize with map zoom level</p>
+
+        <div class="control-group">
+            <label>
+                Morph Factor: <span class="value-display" id="factorValue">0.00</span>
+            </label>
+            <input type="range" id="morphFactor" min="0" max="1" step="0.01" value="0">
+        </div>
+
+        <div class="control-group">
+            <div class="checkbox-group">
+                <input type="checkbox" id="scaleToggle" checked>
+                <label for="scaleToggle">Scale glyphs with zoom</label>
+            </div>
+        </div>
+
+        <div class="info-box">
+            <strong>Try it:</strong> Zoom in/out to see waffle charts resize to match cartogram polygons. Toggle scaling
+            to compare behaviors.
+        </div>
+    </div>
+
+    <div class="status" id="status">Initializing...</div>
+
+    <div class="legend">
+        <h3>Waffle Chart Legend</h3>
+        <div class="legend-item">
+            <div class="legend-square" style="background: #4e79a7;"></div>
+            <span>Filled (population ratio)</span>
+        </div>
+        <div class="legend-item">
+            <div class="legend-square" style="background: #e0e0e0;"></div>
+            <span>Empty</span>
+        </div>
+    </div>
+
+    <script type="importmap">
+    {
+      "imports": {
+        "leaflet": "https://cdn.jsdelivr.net/npm/leaflet@1.9.4/+esm",
+        "npm:leaflet": "https://cdn.jsdelivr.net/npm/leaflet@1.9.4/+esm",
+        "@turf/turf": "https://esm.sh/@turf/turf@6.5.0?bundle",
+        "flubber": "https://esm.sh/flubber@0.4.2?bundle",
+        "lodash/isEmpty.js": "https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/isEmpty.js",
+        "lodash/cloneDeep.js": "https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/cloneDeep.js",
+        "lodash/keyBy.js": "https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/keyBy.js",
+        "lodash/mapValues.js": "https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/mapValues.js"
+      }
+    }
+  </script>
+    <script type="module" src="./zoom-scaling-glyphs.js"></script>
+</body>
+
+</html>
+
+