@trackunit/react-map 0.2.210 → 0.2.211

package/index.cjs.js

@@ -5888,10 +5888,10 @@ const useFitToContent = (api, handles, options) => {
 };
 
 /**
- * Single dev-warning channel for `useHeatmap` (invalid data, invalid style).
+ * Single dev-warning channel for `useHeatmap` (invalid data, invalid style, unhandled render errors).
  */
 const warnHeatmap = (message, ...details) => {
-    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped or defaulted and must stay visible
+    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped or defaulted and render errors without onError must stay visible
     console.warn(`[useHeatmap] ${message}`, ...details);
 };
 
@@ -6040,8 +6040,41 @@ const EMPTY_CONTROLS$2 = {};
  * - Renderers: ADR-0029 (`libs/react/map/docs/adr/0029-heatmap-provider-specific-renderers.md`).
  */
 const useHeatmap = (options) => {
-    const { id, name, data, getPosition, getWeight, style, controls, loading, fitParticipation = "all" } = options;
+    const { id, name, data, getPosition, getWeight, style, onError, controls, loading, fitParticipation = "all", } = options;
     const layerReady = useLayerReady(loading);
+    const onErrorRef = react.useRef(onError);
+    react.useEffect(() => {
+        onErrorRef.current = onError;
+    }, [onError]);
+    const errorHandler = reactCoreHooks.useErrorHandlerOrNull();
+    // Sentry at most once per layer/code per hook mount, like the shape hooks' fill-tiling reports.
+    const sentryReportedKeysRef = react.useRef(new Set());
+    const captureOnce = react.useCallback((key, message, cause, fingerprintCode) => {
+        if (errorHandler === null || sentryReportedKeysRef.current.has(key))
+            return;
+        sentryReportedKeysRef.current.add(key);
+        errorHandler.captureException(new Error(message, { cause }), {
+            level: "warning",
+            fingerprint: ["react-map", "heatmap", fingerprintCode],
+        });
+    }, [errorHandler]);
+    const reportError = react.useCallback((error) => {
+        const payload = JSON.stringify({ layerId: error.layerId, code: error.code });
+        captureOnce(`${error.layerId}:${error.code}`, `Heatmap failed to render: ${payload}`, error.cause, error.code);
+        const handler = onErrorRef.current;
+        if (handler !== undefined) {
+            // Adapters call this mid-sync; a throwing handler must not skip the rest of the layer snapshot.
+            try {
+                handler(error);
+            }
+            catch (handlerError) {
+                warnHeatmap(`onError for heatmap "${error.layerId}" threw.`, handlerError, error.cause);
+                captureOnce(`${error.layerId}:on-error-threw`, `Heatmap onError threw: ${payload}`, handlerError, "on-error-threw");
+            }
+            return;
+        }
+        warnHeatmap(`Heatmap "${error.layerId}" failed to render (${error.code}).`, error.cause);
+    }, [captureOnce]);
     // Keyed on `data` (adjust-state-during-render + isEqual) so inline accessors
     // don't re-normalize the whole dataset on every render. Accessor changes
     // apply on the next `data` change.
@@ -6078,6 +6111,7 @@ const useHeatmap = (options) => {
         layerType: "heatmap",
         features: normalized.features,
         style: resolvedStyle,
+        onError: reportError,
         pointCount: normalized.features.features.length,
         totalCount: data.length,
     }), [
@@ -6090,6 +6124,7 @@ const useHeatmap = (options) => {
         fitParticipation,
         normalized.features,
         resolvedStyle,
+        reportError,
         data.length,
     ]);
 };
@@ -8482,6 +8517,7 @@ function toMapLayer(handle) {
                 id: handle.id,
                 features: handle.features,
                 style: handle.style,
+                onError: handle.onError,
             };
         default: {
             const exhaustiveCheck = handle;

package/index.esm.js

@@ -5887,10 +5887,10 @@ const useFitToContent = (api, handles, options) => {
 };
 
 /**
- * Single dev-warning channel for `useHeatmap` (invalid data, invalid style).
+ * Single dev-warning channel for `useHeatmap` (invalid data, invalid style, unhandled render errors).
  */
 const warnHeatmap = (message, ...details) => {
-    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped or defaulted and must stay visible
+    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped or defaulted and render errors without onError must stay visible
     console.warn(`[useHeatmap] ${message}`, ...details);
 };
 
@@ -6039,8 +6039,41 @@ const EMPTY_CONTROLS$2 = {};
  * - Renderers: ADR-0029 (`libs/react/map/docs/adr/0029-heatmap-provider-specific-renderers.md`).
  */
 const useHeatmap = (options) => {
-    const { id, name, data, getPosition, getWeight, style, controls, loading, fitParticipation = "all" } = options;
+    const { id, name, data, getPosition, getWeight, style, onError, controls, loading, fitParticipation = "all", } = options;
     const layerReady = useLayerReady(loading);
+    const onErrorRef = useRef(onError);
+    useEffect(() => {
+        onErrorRef.current = onError;
+    }, [onError]);
+    const errorHandler = useErrorHandlerOrNull();
+    // Sentry at most once per layer/code per hook mount, like the shape hooks' fill-tiling reports.
+    const sentryReportedKeysRef = useRef(new Set());
+    const captureOnce = useCallback((key, message, cause, fingerprintCode) => {
+        if (errorHandler === null || sentryReportedKeysRef.current.has(key))
+            return;
+        sentryReportedKeysRef.current.add(key);
+        errorHandler.captureException(new Error(message, { cause }), {
+            level: "warning",
+            fingerprint: ["react-map", "heatmap", fingerprintCode],
+        });
+    }, [errorHandler]);
+    const reportError = useCallback((error) => {
+        const payload = JSON.stringify({ layerId: error.layerId, code: error.code });
+        captureOnce(`${error.layerId}:${error.code}`, `Heatmap failed to render: ${payload}`, error.cause, error.code);
+        const handler = onErrorRef.current;
+        if (handler !== undefined) {
+            // Adapters call this mid-sync; a throwing handler must not skip the rest of the layer snapshot.
+            try {
+                handler(error);
+            }
+            catch (handlerError) {
+                warnHeatmap(`onError for heatmap "${error.layerId}" threw.`, handlerError, error.cause);
+                captureOnce(`${error.layerId}:on-error-threw`, `Heatmap onError threw: ${payload}`, handlerError, "on-error-threw");
+            }
+            return;
+        }
+        warnHeatmap(`Heatmap "${error.layerId}" failed to render (${error.code}).`, error.cause);
+    }, [captureOnce]);
     // Keyed on `data` (adjust-state-during-render + isEqual) so inline accessors
     // don't re-normalize the whole dataset on every render. Accessor changes
     // apply on the next `data` change.
@@ -6077,6 +6110,7 @@ const useHeatmap = (options) => {
         layerType: "heatmap",
         features: normalized.features,
         style: resolvedStyle,
+        onError: reportError,
         pointCount: normalized.features.features.length,
         totalCount: data.length,
     }), [
@@ -6089,6 +6123,7 @@ const useHeatmap = (options) => {
         fitParticipation,
         normalized.features,
         resolvedStyle,
+        reportError,
         data.length,
     ]);
 };
@@ -8481,6 +8516,7 @@ function toMapLayer(handle) {
                 id: handle.id,
                 features: handle.features,
                 style: handle.style,
+                onError: handle.onError,
             };
         default: {
             const exhaustiveCheck = handle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.210",
+  "version": "0.2.211",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -14,7 +14,7 @@
     "@trackunit/geo-json-utils": "1.18.6",
     "@trackunit/i18n-library-translation": "2.8.6",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.157",
+    "@trackunit/react-map-adapter-shared": "0.0.158",
     "@trackunit/react-map-color-utils": "0.0.132",
     "@trackunit/shared-utils": "1.19.6",
     "@trackunit/ui-design-tokens": "1.18.6",

package/src/index.d.ts

@@ -24,7 +24,7 @@ export type { ControlMiddleware, MiddlewareContext } from "./controls/renderingR
 export type { CategoryMetadata } from "./controls/collapseControls";
 export type { ClusterEntity, Entity, MapInteractionState, MarkerEntity, RouteEntity, ShapeEntity, ShapeType, } from "@trackunit/react-map-adapter-shared";
 export { geometryTypeToShapeType, INITIAL_INTERACTION_STATE } from "@trackunit/react-map-adapter-shared";
-export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterInfo, ClusterRenderState, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, FitParticipation, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapLayerHandle, HeatmapRgbaColor, ImageOverlayHandle, LayerHandle, LayerMeta, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, MarkerLayerHandle, RenderConfig, RenderMedium, ResolutionContext, RouteLayerHandle, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeLayerHandle, ShapeOverlapConfig, ShapeStyle, ShapeStyleOverrides, ShapesUnderCursorHit, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "./layers/types";
+export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterInfo, ClusterRenderState, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, FitParticipation, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapLayerHandle, HeatmapRenderError, HeatmapRgbaColor, ImageOverlayHandle, LayerHandle, LayerMeta, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, MarkerLayerHandle, RenderConfig, RenderMedium, ResolutionContext, RouteLayerHandle, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeLayerHandle, ShapeOverlapConfig, ShapeStyle, ShapeStyleOverrides, ShapesUnderCursorHit, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "./layers/types";
 export { computeMarkerDomPortalZIndex } from "./layers/types";
 export { ANCHOR_SELECTOR, HIT_SURFACE_SELECTOR } from "@trackunit/react-map-adapter-shared";
 export { ClusterMarker, type ClusterMarkerProps, type ClusterMarkerStickInput, type ClusterSegment, } from "./clusters/ClusterMarker";

package/src/layers/types.d.ts

@@ -1,12 +1,12 @@
 import type { GeoJsonBbox, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, GeoJsonPosition } from "@trackunit/geo-json-utils";
-import type { AdaptiveMarkerResolution, ClusterConfig, ClusterRenderConfig, HeatmapRenderStyle, RenderConfig, RouteStyle, ShapeInteractiveMode, ShapeStyle } from "@trackunit/react-map-adapter-shared";
+import type { AdaptiveMarkerResolution, ClusterConfig, ClusterRenderConfig, HeatmapRenderError, HeatmapRenderStyle, RenderConfig, RouteStyle, ShapeInteractiveMode, ShapeStyle } from "@trackunit/react-map-adapter-shared";
 import type { CategoryKey, ControlConfig } from "../controls/types";
 import type { ShapeDecoration } from "./useShapes/shapeDecorations";
 import type { ShapesUnderCursorHit } from "./useShapes/shapeFillTiling";
 import type { ShapeLabelResolutionContext } from "./useShapes/shapeLabelResolution";
 import type { ResolveShapeStackOrder } from "./useShapes/shapeStackOrder";
 export type { ShapesUnderCursorHit };
-export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapRenderStyle, HeatmapRgbaColor, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "@trackunit/react-map-adapter-shared";
+export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapRenderError, HeatmapRenderStyle, HeatmapRgbaColor, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "@trackunit/react-map-adapter-shared";
 export { computeMarkerDomPortalZIndex } from "@trackunit/react-map-adapter-shared";
 /**
  * Controls whether a layer's bounds are included in fit-to-content operations.
@@ -191,6 +191,8 @@ export interface HeatmapLayerHandle extends LayerMeta {
     readonly layerType: "heatmap";
     readonly features: GeoJsonFeatureCollection;
     readonly style: HeatmapRenderStyle;
+    /** Stable error reporter forwarded to the adapter; calls the consumer's latest `onError` or warns. */
+    readonly onError: (error: HeatmapRenderError) => void;
 }
 /**
  * Discriminated union of all layer handle types.

package/src/layers/useHeatmap/useHeatmap.d.ts

@@ -1,4 +1,5 @@
 import type { GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { HeatmapRenderError } from "@trackunit/react-map-adapter-shared";
 import type { CategoryKey, ControlConfig } from "../../controls/types";
 import type { FitParticipation, HeatmapLayerHandle } from "../types";
 export type HeatmapStyle = Readonly<{
@@ -21,6 +22,14 @@ export type UseHeatmapOptions<TItem> = Readonly<{
     getPosition: (item: TItem) => GeoJsonPosition | null;
     getWeight?: (item: TItem) => number;
     style?: HeatmapStyle;
+    /**
+     * Called once per failed renderer load or update (for example when the Google deck.gl chunk fails to load).
+     * The basemap and other layers keep rendering. Without it, failures are logged with `console.warn`.
+     * Failures are reported to the app's error handler (Sentry) either way.
+     * After a renderer failure (for example WebGL context loss on Google), the heatmap stays hidden until the next map
+     * layer or interaction change triggers a retry; nothing retries on an idle map.
+     */
+    onError?: (error: HeatmapRenderError) => void;
     controls?: Partial<Record<CategoryKey, ReadonlyArray<ControlConfig>>>;
     loading?: boolean;
     fitParticipation?: FitParticipation;

package/src/layers/useHeatmap/utils/warnHeatmap.d.ts

@@ -1,4 +1,4 @@
 /**
- * Single dev-warning channel for `useHeatmap` (invalid data, invalid style).
+ * Single dev-warning channel for `useHeatmap` (invalid data, invalid style, unhandled render errors).
  */
 export declare const warnHeatmap: (message: string, ...details: ReadonlyArray<unknown>) => void;