@trackunit/react-map-adapter-mapbox 0.0.131 → 0.0.132

package/README.md

@@ -51,6 +51,12 @@ Use the exported directives instead of copying host lists. Add any origins requi
 
 Where Mapbox GL lacks a capability the Google Maps adapter gets natively, this adapter emulates it so consumers see identical behaviour regardless of provider. The clearest case is geodesic arcs: Google draws great-circle edges natively, while Mapbox renders Mercator straight lines, so this adapter densifies edges with `densifyGeodesicFeatures` from `@trackunit/react-map-adapter-shared` to match. Provider gaps are closed inside the adapter — never pushed up to application code.
 
+## Heatmaps
+
+- **Renderer:** Mapbox GL native `heatmap` layer + GeoJSON source (`MapboxLayerPort.syncHeatmap`).
+- **Contract:** shared `HeatmapSourceConfig`; style reload re-applies heatmap sources.
+- **ADR:** `libs/react/map/docs/adr/0029-heatmap-provider-specific-renderers.md` (monorepo).
+
 ## Dependencies
 
 Depends on `@trackunit/react-map-adapter-shared` and Mapbox GL–related dependencies used by the renderer. It does **not** import `@trackunit/react-map` (adapters are consumed *by* the map package, not the reverse).

package/index.cjs.js

@@ -226,6 +226,7 @@ class MapboxLayerPort {
         this.shapeSources = new Map();
         this.routeSources = new Map();
         this.overlaySources = new Map();
+        this.heatmapSources = new Map();
         // Snapshot queued before the map is connected / style is ready
         this.pendingSnapshot = null;
         // Last non-empty snapshot the consumer pushed. Preserved across `destroy()` so the React 18
@@ -414,6 +415,9 @@ class MapboxLayerPort {
         for (const id of [...this.overlaySources.keys()]) {
             this.removeImageOverlayInternal(id);
         }
+        for (const id of [...this.heatmapSources.keys()]) {
+            this.removeHeatmapInternal(id);
+        }
         // Remove style.load listener
         if (this.styleLoadHandler !== null && this.map !== null) {
             this.map.off("style.load", this.styleLoadHandler);
@@ -944,6 +948,47 @@ class MapboxLayerPort {
         }
         this.overlaySources.delete(id);
     }
+    /**
+     * Native Mapbox GL heatmap layer (ADR-0029).
+     *
+     * - Source: `heatmap-source-{id}`, layer: `heatmap-layer-{id}`.
+     * - Restored on style reload via `reapplySourcesAfterStyleChange`.
+     */
+    syncHeatmap(config) {
+        if (this.map === null)
+            return;
+        const existing = this.heatmapSources.get(config.id);
+        if (existing !== undefined && esToolkit.isEqual(existing.config, config))
+            return;
+        this.removeHeatmapInternal(config.id);
+        const sourceId = `heatmap-source-${config.id}`;
+        const layerId = `heatmap-layer-${config.id}`;
+        this.map.addSource(sourceId, {
+            type: "geojson",
+            data: toMapboxGeoJson(config.features),
+        });
+        this.map.addLayer({
+            id: layerId,
+            type: "heatmap",
+            source: sourceId,
+            paint: {
+                "heatmap-weight": ["coalesce", ["get", "weight"], 1],
+                "heatmap-radius": config.style.radiusPixels,
+                "heatmap-intensity": config.style.intensity,
+                "heatmap-opacity": config.style.opacity,
+            },
+        });
+        this.heatmapSources.set(config.id, { sourceId, layerId, config });
+    }
+    removeHeatmapInternal(id) {
+        const tracked = this.heatmapSources.get(id);
+        if (tracked === undefined)
+            return;
+        if (this.map !== null) {
+            safeRemoveLayersAndSource(this.map, [tracked.layerId], tracked.sourceId);
+        }
+        this.heatmapSources.delete(id);
+    }
     // ============================================================================
     // Private: Layer fade-in
     // ============================================================================
@@ -1006,6 +1051,7 @@ class MapboxLayerPort {
         const shapeIds = new Set(snapshot.layers.filter(l => l.layerType === "shapes").map(l => l.id));
         const routeIds = new Set(snapshot.layers.filter(l => l.layerType === "route").map(l => l.id));
         const overlayIds = new Set(snapshot.layers.filter(l => l.layerType === "image-overlay").map(l => l.id));
+        const heatmapIds = new Set(snapshot.layers.filter(l => l.layerType === "heatmap").map(l => l.id));
         for (const layer of snapshot.layers) {
             switch (layer.layerType) {
                 case "markers":
@@ -1020,6 +1066,9 @@ class MapboxLayerPort {
                 case "image-overlay":
                     this.syncImageOverlay(layer);
                     break;
+                case "heatmap":
+                    this.syncHeatmap(layer);
+                    break;
                 default: {
                     const exhaustiveCheck = layer;
                     throw new Error(`Unknown layer type: ${String(exhaustiveCheck)}`);
@@ -1042,6 +1091,10 @@ class MapboxLayerPort {
             if (!overlayIds.has(id))
                 this.removeImageOverlayInternal(id);
         }
+        for (const id of [...this.heatmapSources.keys()]) {
+            if (!heatmapIds.has(id))
+                this.removeHeatmapInternal(id);
+        }
         this.applyShapeSelectionState(snapshot.shapeSelection.handleId, snapshot.shapeSelection.featureId);
         this.applyShapeHoverState(snapshot.shapeHover.handleId, snapshot.shapeHover.featureId);
     }
@@ -2191,6 +2244,7 @@ class MapboxLayerPort {
         const shapeEntries = Array.from(this.shapeSources.entries());
         const routeEntries = Array.from(this.routeSources.entries());
         const overlayEntries = Array.from(this.overlaySources.entries());
+        const heatmapEntries = Array.from(this.heatmapSources.entries());
         const markerEntriesToRestore = Array.from(this.markerSources.entries()).filter(([, tracked]) => tracked.sourceId !== undefined);
         // Re-add shape sources/layers
         for (const [id, { config }] of shapeEntries) {
@@ -2216,6 +2270,11 @@ class MapboxLayerPort {
             this.overlaySources.delete(id);
             this.syncImageOverlay(config);
         }
+        // Re-add heatmap sources/layers
+        for (const [id, { config }] of heatmapEntries) {
+            this.heatmapSources.delete(id);
+            this.syncHeatmap(config);
+        }
         // DOM markers (mapboxgl.Marker) persist across style changes, but
         // WebGL circle layers/sources are removed. Re-add marker sources
         // that used circle layers (from pre-snapshot).

package/index.esm.js

@@ -225,6 +225,7 @@ class MapboxLayerPort {
         this.shapeSources = new Map();
         this.routeSources = new Map();
         this.overlaySources = new Map();
+        this.heatmapSources = new Map();
         // Snapshot queued before the map is connected / style is ready
         this.pendingSnapshot = null;
         // Last non-empty snapshot the consumer pushed. Preserved across `destroy()` so the React 18
@@ -413,6 +414,9 @@ class MapboxLayerPort {
         for (const id of [...this.overlaySources.keys()]) {
             this.removeImageOverlayInternal(id);
         }
+        for (const id of [...this.heatmapSources.keys()]) {
+            this.removeHeatmapInternal(id);
+        }
         // Remove style.load listener
         if (this.styleLoadHandler !== null && this.map !== null) {
             this.map.off("style.load", this.styleLoadHandler);
@@ -943,6 +947,47 @@ class MapboxLayerPort {
         }
         this.overlaySources.delete(id);
     }
+    /**
+     * Native Mapbox GL heatmap layer (ADR-0029).
+     *
+     * - Source: `heatmap-source-{id}`, layer: `heatmap-layer-{id}`.
+     * - Restored on style reload via `reapplySourcesAfterStyleChange`.
+     */
+    syncHeatmap(config) {
+        if (this.map === null)
+            return;
+        const existing = this.heatmapSources.get(config.id);
+        if (existing !== undefined && isEqual(existing.config, config))
+            return;
+        this.removeHeatmapInternal(config.id);
+        const sourceId = `heatmap-source-${config.id}`;
+        const layerId = `heatmap-layer-${config.id}`;
+        this.map.addSource(sourceId, {
+            type: "geojson",
+            data: toMapboxGeoJson(config.features),
+        });
+        this.map.addLayer({
+            id: layerId,
+            type: "heatmap",
+            source: sourceId,
+            paint: {
+                "heatmap-weight": ["coalesce", ["get", "weight"], 1],
+                "heatmap-radius": config.style.radiusPixels,
+                "heatmap-intensity": config.style.intensity,
+                "heatmap-opacity": config.style.opacity,
+            },
+        });
+        this.heatmapSources.set(config.id, { sourceId, layerId, config });
+    }
+    removeHeatmapInternal(id) {
+        const tracked = this.heatmapSources.get(id);
+        if (tracked === undefined)
+            return;
+        if (this.map !== null) {
+            safeRemoveLayersAndSource(this.map, [tracked.layerId], tracked.sourceId);
+        }
+        this.heatmapSources.delete(id);
+    }
     // ============================================================================
     // Private: Layer fade-in
     // ============================================================================
@@ -1005,6 +1050,7 @@ class MapboxLayerPort {
         const shapeIds = new Set(snapshot.layers.filter(l => l.layerType === "shapes").map(l => l.id));
         const routeIds = new Set(snapshot.layers.filter(l => l.layerType === "route").map(l => l.id));
         const overlayIds = new Set(snapshot.layers.filter(l => l.layerType === "image-overlay").map(l => l.id));
+        const heatmapIds = new Set(snapshot.layers.filter(l => l.layerType === "heatmap").map(l => l.id));
         for (const layer of snapshot.layers) {
             switch (layer.layerType) {
                 case "markers":
@@ -1019,6 +1065,9 @@ class MapboxLayerPort {
                 case "image-overlay":
                     this.syncImageOverlay(layer);
                     break;
+                case "heatmap":
+                    this.syncHeatmap(layer);
+                    break;
                 default: {
                     const exhaustiveCheck = layer;
                     throw new Error(`Unknown layer type: ${String(exhaustiveCheck)}`);
@@ -1041,6 +1090,10 @@ class MapboxLayerPort {
             if (!overlayIds.has(id))
                 this.removeImageOverlayInternal(id);
         }
+        for (const id of [...this.heatmapSources.keys()]) {
+            if (!heatmapIds.has(id))
+                this.removeHeatmapInternal(id);
+        }
         this.applyShapeSelectionState(snapshot.shapeSelection.handleId, snapshot.shapeSelection.featureId);
         this.applyShapeHoverState(snapshot.shapeHover.handleId, snapshot.shapeHover.featureId);
     }
@@ -2190,6 +2243,7 @@ class MapboxLayerPort {
         const shapeEntries = Array.from(this.shapeSources.entries());
         const routeEntries = Array.from(this.routeSources.entries());
         const overlayEntries = Array.from(this.overlaySources.entries());
+        const heatmapEntries = Array.from(this.heatmapSources.entries());
         const markerEntriesToRestore = Array.from(this.markerSources.entries()).filter(([, tracked]) => tracked.sourceId !== undefined);
         // Re-add shape sources/layers
         for (const [id, { config }] of shapeEntries) {
@@ -2215,6 +2269,11 @@ class MapboxLayerPort {
             this.overlaySources.delete(id);
             this.syncImageOverlay(config);
         }
+        // Re-add heatmap sources/layers
+        for (const [id, { config }] of heatmapEntries) {
+            this.heatmapSources.delete(id);
+            this.syncHeatmap(config);
+        }
         // DOM markers (mapboxgl.Marker) persist across style changes, but
         // WebGL circle layers/sources are removed. Re-add marker sources
         // that used circle layers (from pre-snapshot).

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@trackunit/react-map-adapter-mapbox",
-  "version": "0.0.131",
+  "version": "0.0.132",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-map-adapter-shared": "0.0.143",
-    "@trackunit/geo-json-utils": "1.16.2",
+    "@trackunit/react-map-adapter-shared": "0.0.144",
+    "@trackunit/geo-json-utils": "1.16.3",
     "mapbox-gl": "^3.18.1",
     "supercluster": "^8.0.1",
     "es-toolkit": "^1.39.10",

package/src/MapboxLayerPort.d.ts

@@ -41,6 +41,7 @@ export declare class MapboxLayerPort implements LayerPort {
     private readonly shapeSources;
     private readonly routeSources;
     private readonly overlaySources;
+    private readonly heatmapSources;
     private pendingSnapshot;
     private lastNonEmptySnapshot;
     private markerPortalDescriptors;
@@ -108,6 +109,14 @@ export declare class MapboxLayerPort implements LayerPort {
     private removeRouteSourceInternal;
     private syncImageOverlay;
     private removeImageOverlayInternal;
+    /**
+     * Native Mapbox GL heatmap layer (ADR-0029).
+     *
+     * - Source: `heatmap-source-{id}`, layer: `heatmap-layer-{id}`.
+     * - Restored on style reload via `reapplySourcesAfterStyleChange`.
+     */
+    private syncHeatmap;
+    private removeHeatmapInternal;
     /**
      * Wrapper around `map.addLayer` that starts the layer at opacity 0 and
      * animates to the target opacity via Mapbox's native paint transition system.

package/src/mapboxAdapter.d.ts

@@ -21,6 +21,9 @@ export declare const mapboxAdapter: (config: Readonly<Readonly<{
     language?: string;
     region?: string;
     theme?: import("@trackunit/react-map-adapter-shared").MapTheme;
+    mapType?: import("@trackunit/react-map-adapter-shared").MapType;
+    showRoads?: boolean;
+    showTraffic?: boolean;
     initialViewport?: import("@trackunit/react-map-adapter-shared").InitialViewport;
     restrictBounds?: import("@trackunit/geo-json-utils").GeoJsonBbox | null;
 }> & {
@@ -29,6 +32,9 @@ export declare const mapboxAdapter: (config: Readonly<Readonly<{
     language?: string;
     region?: string;
     theme?: import("@trackunit/react-map-adapter-shared").MapTheme;
+    mapType?: import("@trackunit/react-map-adapter-shared").MapType;
+    showRoads?: boolean;
+    showTraffic?: boolean;
     initialViewport?: import("@trackunit/react-map-adapter-shared").InitialViewport;
     restrictBounds?: import("@trackunit/geo-json-utils").GeoJsonBbox | null;
 }> & {