@trackunit/react-map 0.2.227 → 0.2.234-alpha-4632fb37afe.0

package/index.cjs.js

@@ -3455,8 +3455,17 @@ const useControls = (base, areas) => {
 /**
  * Single dev-warning channel for react-map hooks (invalid data, invalid style, unhandled render errors).
  * Messages are prefixed with the emitting hook, e.g. `[useHeatmap]`.
+ *
+ * Skipped in production builds: the warnings describe consumer mistakes a developer fixes
+ * once, and with polled data they would otherwise log on every data change. Vitest runs
+ * with `NODE_ENV` set to `test`, so specs can still spy on `console.warn`.
+ *
+ * Call it from effects, handlers and callbacks, never during render: pure normalizers
+ * return their warnings and `useDevWarnings` emits them once per result.
  */
 const consoleWarnMap = (source, message, ...details) => {
+    if (process.env.NODE_ENV === "production")
+        return;
     // eslint-disable-next-line no-console -- Intentional: the one react-map warning channel; invalid input is dropped or defaulted and render errors without onError must stay visible
     console.warn(`[${source}] ${message}`, ...details);
 };
@@ -5913,17 +5922,39 @@ const createLazyGetter = (compute) => {
     };
 };
 
+/** Shared empty result so hooks with nothing to report keep a stable reference. */
+const NO_DEV_WARNINGS = [];
+/**
+ * Emits a normalizer's warnings through the react-map dev-warning channel, from an
+ * effect rather than during render.
+ *
+ * Pure normalizers (`filterPositioned`, `normalizeHeatmapData`, ...) run inside render
+ * and must not log: StrictMode and discarded concurrent renders would log them twice.
+ * They return their warnings instead, and this hook emits each list once. The list's
+ * identity is the dedupe key, so StrictMode's double effect run and re-renders that
+ * keep the same normalized result add nothing; a new normalization pass (a new list)
+ * warns again, which is what a developer feeding new invalid data expects.
+ */
+const useDevWarnings = (source, warnings) => {
+    const emittedRef = react.useRef(null);
+    react.useEffect(() => {
+        if (warnings.length === 0 || emittedRef.current === warnings)
+            return;
+        emittedRef.current = warnings;
+        for (const message of warnings) {
+            consoleWarnMap(source, message);
+        }
+    }, [source, warnings]);
+};
+
 // ============================================================================
 // Constants
 // ============================================================================
 const EMPTY_CONTROLS$3 = {};
 const EMPTY_FEATURES$1 = { type: "FeatureCollection", features: [] };
-// ============================================================================
-// Internal helpers
-// ============================================================================
 /**
  * Filter waypoints to only valid GeoJSON positions. Invalid entries are dropped.
- * Logs console.warn once when any waypoints are filtered.
+ * Pure: it runs during render, so it returns one grouped warning instead of logging.
  */
 const filterValidWaypoints = (waypoints) => {
     const valid = [];
@@ -5933,12 +5964,11 @@ const filterValidWaypoints = (waypoints) => {
             valid.push(result.data);
         }
     }
-    if (valid.length < waypoints.length) {
-        const filtered = waypoints.length - valid.length;
-        // eslint-disable-next-line no-console -- Intentional: warn devs when invalid waypoints are passed; invalid entries are filtered out
-        console.warn(`[useRoute] Filtered ${filtered} invalid waypoint(s). Expected [longitude, latitude] with latitude between -90 and 90.`);
-    }
-    return valid;
+    const filtered = waypoints.length - valid.length;
+    const warnings = filtered > 0
+        ? [`Filtered ${filtered} invalid waypoint(s). Expected [longitude, latitude] with latitude between -90 and 90.`]
+        : NO_DEV_WARNINGS;
+    return { waypoints: valid, warnings };
 };
 /**
  * Convert waypoints to a GeoJSON FeatureCollection with a single LineString.
@@ -5986,7 +6016,9 @@ const useRoute = (options) => {
     // ---- Data readiness tracking ----
     const layerReady = useLayerReady(loading);
     // ---- Filter to valid waypoints only ----
-    const waypoints = react.useMemo(() => filterValidWaypoints(rawWaypoints), [rawWaypoints]);
+    const filtered = react.useMemo(() => filterValidWaypoints(rawWaypoints), [rawWaypoints]);
+    const waypoints = filtered.waypoints;
+    useDevWarnings("useRoute", filtered.warnings);
     // ---- Convert to GeoJSON ----
     const features = react.useMemo(() => toLineStringFeatureCollection(id, waypoints), [id, waypoints]);
     // ---- Lazy getBounds with cache ----
@@ -6101,8 +6133,7 @@ const useFitToContent = (api, handles, options) => {
             const stillPending = filterHandles(handlesRef.current, "initial").filter(h => h.loadsData && h.loading);
             if (stillPending.length > 0) {
                 const names = stillPending.map(h => h.name).join(", ");
-                // eslint-disable-next-line no-console -- Intentional: warn devs when layers are too slow to load
-                console.warn(`[useFitToContent] Timeout (${timeout}ms) reached. Fitting with available data. Still loading: ${names}`);
+                consoleWarnMap("useFitToContent", `Timeout (${timeout}ms) reached. Fitting with available data. Still loading: ${names}`);
             }
             performFit();
         }, timeout);
@@ -6134,7 +6165,8 @@ const useFitToContent = (api, handles, options) => {
  * Converts consumer items into weighted GeoJSON `Point` features.
  *
  * Null positions and zero weights are dropped silently. Invalid positions and
- * negative or non-finite weights are dropped with one grouped warning per pass.
+ * negative or non-finite weights are dropped and reported as one grouped warning
+ * per pass in `warnings`; the hook emits it from an effect, never during render.
  */
 const normalizeHeatmapData = ({ data, getPosition, getWeight, }) => {
     const features = [];
@@ -6164,12 +6196,15 @@ const normalizeHeatmapData = ({ data, getPosition, getWeight, }) => {
             properties: { weight },
         });
     }
-    if (invalidPositionCount > 0 || invalidWeightCount > 0) {
-        consoleWarnMap("useHeatmap", `Filtered ${invalidPositionCount} item(s) with invalid position and ${invalidWeightCount} item(s) with invalid weight. Expected [longitude, latitude] with longitude between -180 and 180, latitude between -90 and 90, and a finite weight >= 0.`);
-    }
+    const warnings = invalidPositionCount > 0 || invalidWeightCount > 0
+        ? [
+            `Filtered ${invalidPositionCount} item(s) with invalid position and ${invalidWeightCount} item(s) with invalid weight. Expected [longitude, latitude] with longitude between -180 and 180, latitude between -90 and 90, and a finite weight >= 0.`,
+        ]
+        : NO_DEV_WARNINGS;
     return {
         features: { type: "FeatureCollection", features },
         positions,
+        warnings,
     };
 };
 
@@ -6223,13 +6258,15 @@ const DEFAULT_HEATMAP_COLOR_RANGE = [
 const DEFAULT_PARSED_COLOR_RANGE = DEFAULT_HEATMAP_COLOR_RANGE.map(parseHeatmapColor).filter(sharedUtils.nonNullable);
 const resolveColorRange = (colorRange) => {
     if (colorRange === undefined)
-        return DEFAULT_PARSED_COLOR_RANGE;
+        return { colorRange: DEFAULT_PARSED_COLOR_RANGE, warning: null };
     const parsed = colorRange.map(parseHeatmapColor);
     const valid = parsed.filter(sharedUtils.nonNullable);
     if (colorRange.length >= 2 && valid.length === parsed.length)
-        return valid;
-    consoleWarnMap("useHeatmap", "colorRange needs at least two supported colours (#rgb, #rrggbb, #rrggbbaa, rgb(), rgba()); using the default.", colorRange);
-    return DEFAULT_PARSED_COLOR_RANGE;
+        return { colorRange: valid, warning: null };
+    return {
+        colorRange: DEFAULT_PARSED_COLOR_RANGE,
+        warning: `colorRange needs at least two supported colours (#rgb, #rrggbb, #rrggbbaa, rgb(), rgba()); using the default. Received: ${JSON.stringify(colorRange)}`,
+    };
 };
 const HEATMAP_STYLE_RULES = {
     radiusPixels: { defaultValue: 30, min: 1, max: 100 },
@@ -6239,7 +6276,8 @@ const HEATMAP_STYLE_RULES = {
 /**
  * Applies defaults and supported ranges so both adapters receive identical style values.
  *
- * Finite values are clamped; non-finite values fall back to the default with one warning.
+ * Finite values are clamped; non-finite values fall back to the default with one grouped
+ * warning. Pure: it runs inside a render-time `useMemo`, so it returns its warnings.
  */
 const resolveHeatmapStyle = (style) => {
     const nonFiniteKeys = [];
@@ -6254,16 +6292,20 @@ const resolveHeatmapStyle = (style) => {
         }
         return Math.min(rule.max, Math.max(rule.min, value));
     };
+    const colorRange = resolveColorRange(style?.colorRange);
     const resolved = {
         radiusPixels: resolveValue("radiusPixels"),
         intensity: resolveValue("intensity"),
         opacity: resolveValue("opacity"),
-        colorRange: resolveColorRange(style?.colorRange),
+        colorRange: colorRange.colorRange,
     };
+    const warnings = [];
     if (nonFiniteKeys.length > 0) {
-        consoleWarnMap("useHeatmap", `Non-finite style value(s) for ${nonFiniteKeys.join(", ")} replaced with defaults.`);
+        warnings.push(`Non-finite style value(s) for ${nonFiniteKeys.join(", ")} replaced with defaults.`);
     }
-    return resolved;
+    if (colorRange.warning !== null)
+        warnings.push(colorRange.warning);
+    return { style: resolved, warnings: warnings.length === 0 ? NO_DEV_WARNINGS : warnings };
 };
 
 const EMPTY_CONTROLS$2 = {};
@@ -6325,12 +6367,17 @@ const useHeatmap = (options) => {
     if (style?.colorRange !== colorRange && !esToolkit.isEqual(style?.colorRange, colorRange)) {
         setColorRange(style?.colorRange);
     }
-    const resolvedStyle = react.useMemo(() => resolveHeatmapStyle({
+    const resolved = react.useMemo(() => resolveHeatmapStyle({
         radiusPixels: style?.radiusPixels,
         intensity: style?.intensity,
         opacity: style?.opacity,
         colorRange,
     }), [style?.radiusPixels, style?.intensity, style?.opacity, colorRange]);
+    const resolvedStyle = resolved.style;
+    // Normalization and style resolution run during render and stay pure; their
+    // warnings are emitted once per pass from an effect (SAGA-907).
+    useDevWarnings("useHeatmap", normalized.warnings);
+    useDevWarnings("useHeatmap", resolved.warnings);
     const getBounds = react.useMemo(() => createLazyGetter(() => computeBoundsFromPositions(normalized.positions)), [normalized.positions]);
     const counts = react.useMemo(() => ({ total: data.length, points: normalized.features.features.length }), [data.length, normalized.features.features.length]);
     return react.useMemo(() => ({
@@ -7396,7 +7443,8 @@ const EMPTY_FEATURES = { type: "FeatureCollection", features: [] };
 const EMPTY_CONTROLS$1 = {};
 /**
  * Filter items to only those with valid positions and extract id + position.
- * Invalid positions (e.g. latitude out of range) are skipped. Logs once when any are filtered.
+ * Invalid positions (e.g. latitude out of range) are skipped. Pure: it runs during
+ * render, so it returns one grouped warning instead of logging.
  */
 const filterPositioned = (data, getPosition, getId) => {
     const result = [];
@@ -7413,11 +7461,12 @@ const filterPositioned = (data, getPosition, getId) => {
             }
         }
     }
-    if (invalidCount > 0) {
-        // eslint-disable-next-line no-console -- Intentional: warn devs when getPosition returns invalid GeoJSON; items are filtered out
-        console.warn(`[useMarkers] Filtered ${invalidCount} item(s) with invalid position. Expected [longitude, latitude] with latitude between -90 and 90.`);
-    }
-    return result;
+    const warnings = invalidCount > 0
+        ? [
+            `Filtered ${invalidCount} item(s) with invalid position. Expected [longitude, latitude] with latitude between -90 and 90.`,
+        ]
+        : NO_DEV_WARNINGS;
+    return { items: result, warnings };
 };
 /**
  * Convert positioned items to a GeoJSON FeatureCollection of Points.
@@ -7521,11 +7570,13 @@ const useMarkers = (options) => {
     // structurally-identical inline arrays do NOT trigger infinite re-renders.
     // The reference check short-circuits isEqual for the common stable-ref case.
     const [prevData, setPrevData] = react.useState(data);
-    const [positionedItems, setPositionedItems] = react.useState(() => filterPositioned(data, getPosition, getId));
+    const [positioned, setPositioned] = react.useState(() => filterPositioned(data, getPosition, getId));
     if (data !== prevData && !esToolkit.isEqual(data, prevData)) {
         setPrevData(data);
-        setPositionedItems(filterPositioned(data, getPosition, getId));
+        setPositioned(filterPositioned(data, getPosition, getId));
     }
+    const positionedItems = positioned.items;
+    useDevWarnings("useMarkers", positioned.warnings);
     // ---- Convert to GeoJSON FeatureCollection ----
     const features = react.useMemo(() => toPointFeatureCollection(positionedItems), [positionedItems]);
     // ---- Resolved server clusters (after resolveGroups entity-shape decisions) ----
@@ -9379,14 +9430,8 @@ const computeFillTiling = (input) => {
         }
         validFeatures.push(feature);
     }
-    if (droppedInvalidFeatures.length > 0) {
-        const idList = droppedInvalidFeatures
-            .map(entry => (entry.feature.id !== undefined ? String(entry.feature.id) : undefined))
-            .filter((id) => id !== undefined)
-            .join(", ") || "(no feature ids)";
-        // eslint-disable-next-line no-console -- Intentional: warn devs when schema-invalid polygonal geometry is excluded from fill tiling
-        console.warn(`[computeFillTiling] Excluded ${droppedInvalidFeatures.length} feature(s) with invalid polygonal geometry from fill tiling (full fill still renders; overlap clipping is skipped): ${idList}`);
-    }
+    // Dropped features are returned, not logged: this function runs inside the hook's
+    // recompute path and stays pure; the hook emits one dev warning per pass.
     // Densify before any polygon/boundary math so clip geometry follows great-circle
     // arcs on large polygons (mirrors the ADR-0024 precedent for edge labels). Always
     // defer to densifyGeodesicFeatures' per-feature resolution (geodesic override >
@@ -9419,11 +9464,7 @@ const computeFillTiling = (input) => {
     const featureToGroupKey = new Map();
     const featureZIndex = new Map();
     const { groups: overlapGroups, intersectionFailures } = buildOverlapGroups(records);
-    if (intersectionFailures.length > 0) {
-        const pairList = intersectionFailures.map(failure => `${failure.featureIdA}↔${failure.featureIdB}`).join(", ");
-        // eslint-disable-next-line no-console -- Intentional: warn devs when polygon-clipping fails on schema-valid geometry (SAGA-743); the pair is treated as non-overlapping and full fills still render
-        console.warn(`[computeFillTiling] polygon-clipping failed on ${intersectionFailures.length} feature pair(s); treated as non-overlapping (full fill still renders): ${pairList}`);
-    }
+    // Failures are returned for the hook to warn about and report (SAGA-743).
     for (const group of overlapGroups) {
         const contended = buildContendedShapes(group);
         const recordById = new Map(group.map(record => [record.id, record]));
@@ -9502,6 +9543,9 @@ const computeFillTiling = (input) => {
     };
 };
 
+/** Renders failing feature pairs as `a↔b, c↔d` for dev warnings and error reports. */
+const formatIntersectionFailurePairs = (failures) => failures.map(failure => `${failure.featureIdA}↔${failure.featureIdB}`).join(", ");
+
 const DEFAULT_ZOOM = 0;
 const DEFAULT_TILE_SIZE = 256;
 /**
@@ -9812,7 +9856,8 @@ const resolveIntersectionFailureDedupeKey = (layerHandleId, failure) => {
 /**
  * Report to Sentry each feature pair whose overlap test threw inside `polygon-clipping`
  * (SAGA-743), at most once per handle/pair per session.
- * Note: `computeFillTiling` emits `console.warn` separately.
+ * Note: the dev warning for this case is emitted by `useShapeFillTiling` from its recompute
+ * path (`computeFillTiling` itself is pure and logs nothing).
  */
 const captureFillTilingIntersectionFailures = (intersectionFailures, layerHandleId, sessionReportedDedupeKeys, report) => {
     for (const failure of intersectionFailures) {
@@ -11234,9 +11279,7 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
     const reportOverlapIntersectionFailures = react.useCallback((intersectionFailures, layerHandleId) => {
         if (intersectionFailures.length === 0)
             return;
-        const pairList = intersectionFailures.map(failure => `${failure.featureIdA}↔${failure.featureIdB}`).join(", ");
-        // eslint-disable-next-line no-console -- Intentional: warn devs when polygon-clipping fails on schema-valid geometry (SAGA-743); the pair is treated as non-overlapping and decorations still render
-        console.warn(`[useShapeDecorations] polygon-clipping failed on ${intersectionFailures.length} feature pair(s); treated as non-overlapping: ${pairList}`);
+        consoleWarnMap("useShapeDecorations", `polygon-clipping failed on ${intersectionFailures.length} feature pair(s); treated as non-overlapping: ${formatIntersectionFailurePairs(intersectionFailures)}`);
         if (errorHandler === null)
             return;
         captureFillTilingIntersectionFailures(intersectionFailures, layerHandleId, sessionReportedIntersectionKeysRef.current, payload => {
@@ -11659,7 +11702,8 @@ const captureOnce = (key, report, sessionReportedDedupeKeys, payload) => {
 };
 /**
  * Report to Sentry each dropped invalid feature via `report`, at most once per handle/feature per session.
- * Note: `computeFillTiling` emits `console.warn` separately.
+ * Note: the dev warning for this case is emitted by `useShapeFillTiling` from its recompute
+ * path (`computeFillTiling` itself is pure and logs nothing).
  */
 const captureDroppedInvalidFillTilingFeatures = (droppedInvalidFeatures, layerHandleId, sessionReportedDedupeKeys, report) => {
     for (const entry of droppedInvalidFeatures) {
@@ -11673,6 +11717,12 @@ const captureDroppedInvalidFillTilingFeatures = (droppedInvalidFeatures, layerHa
     }
 };
 
+/** Lists the ids of features dropped from fill tiling, or a placeholder when none carry an id. */
+const formatDroppedInvalidFeatureIds = (dropped) => dropped
+    .map(entry => (entry.feature.id !== undefined ? String(entry.feature.id) : undefined))
+    .filter(sharedUtils.nonNullable)
+    .join(", ") || "(no feature ids)";
+
 // ============================================================================
 // Default resolver
 // ============================================================================
@@ -12109,6 +12159,14 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
                 layerGeodesic: handle.style.geodesic,
                 featureStyles: handle.featureStyles,
             });
+            // The dev warnings live here, not in computeFillTiling: recompute runs from
+            // effects and idle callbacks, so the pure function stays silent (SAGA-907).
+            if (droppedInvalidFeatures.length > 0) {
+                consoleWarnMap("useShapes", `Excluded ${droppedInvalidFeatures.length} feature(s) with invalid polygonal geometry from fill tiling (full fill still renders; overlap clipping is skipped): ${formatDroppedInvalidFeatureIds(droppedInvalidFeatures)}`);
+            }
+            if (intersectionFailures.length > 0) {
+                consoleWarnMap("useShapes", `polygon-clipping failed on ${intersectionFailures.length} feature pair(s); treated as non-overlapping (full fill still renders): ${formatIntersectionFailurePairs(intersectionFailures)}`);
+            }
             if (errorHandler !== null && droppedInvalidFeatures.length > 0) {
                 captureDroppedInvalidFillTilingFeatures(droppedInvalidFeatures, handle.id, sessionReportedDedupeKeysRef.current, payload => {
                     errorHandler.captureException(new Error(`Schema-invalid polygonal geometry excluded from fill tiling: ${JSON.stringify(payload)}`), {