@trackunit/react-map 0.2.203 → 0.2.206

package/index.cjs.js

@@ -5887,6 +5887,57 @@ const useFitToContent = (api, handles, options) => {
     return react.useMemo(() => ({ hasFitted, isWaiting, fitNow }), [hasFitted, isWaiting, fitNow]);
 };
 
+/**
+ * Single dev-warning channel for `useHeatmap` (invalid data).
+ */
+const warnHeatmap = (message, ...details) => {
+    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped and must stay visible
+    console.warn(`[useHeatmap] ${message}`, ...details);
+};
+
+/**
+ * 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.
+ */
+const normalizeHeatmapData = ({ data, getPosition, getWeight, }) => {
+    const features = [];
+    const positions = [];
+    let invalidPositionCount = 0;
+    let invalidWeightCount = 0;
+    for (const item of data) {
+        const position = getPosition(item);
+        if (position === null)
+            continue;
+        const parsedPosition = geoJsonUtils.geoJsonPositionSchema.safeParse(position);
+        if (!parsedPosition.success) {
+            invalidPositionCount++;
+            continue;
+        }
+        const weight = getWeight?.(item) ?? 1;
+        if (weight === 0)
+            continue;
+        if (!Number.isFinite(weight) || weight < 0) {
+            invalidWeightCount++;
+            continue;
+        }
+        positions.push(parsedPosition.data);
+        features.push({
+            type: "Feature",
+            geometry: { type: "Point", coordinates: parsedPosition.data },
+            properties: { weight },
+        });
+    }
+    if (invalidPositionCount > 0 || invalidWeightCount > 0) {
+        warnHeatmap(`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.`);
+    }
+    return {
+        features: { type: "FeatureCollection", features },
+        positions,
+    };
+};
+
 const EMPTY_CONTROLS$2 = {};
 /**
  * Weighted point heatmap layer handle (provider-agnostic).
@@ -5898,31 +5949,15 @@ const EMPTY_CONTROLS$2 = {};
 const useHeatmap = (options) => {
     const { id, name, data, getPosition, getWeight, style, controls, loading, fitParticipation = "all" } = options;
     const layerReady = useLayerReady(loading);
-    const normalized = react.useMemo(() => {
-        const features = [];
-        const positions = [];
-        for (const item of data) {
-            const position = getPosition(item);
-            if (position === null)
-                continue;
-            const parsedPosition = geoJsonUtils.geoJsonPositionSchema.safeParse(position);
-            if (!parsedPosition.success)
-                continue;
-            const weight = getWeight?.(item) ?? 1;
-            if (!Number.isFinite(weight) || weight <= 0)
-                continue;
-            positions.push(parsedPosition.data);
-            features.push({
-                type: "Feature",
-                geometry: { type: "Point", coordinates: parsedPosition.data },
-                properties: { weight },
-            });
-        }
-        return {
-            features: { type: "FeatureCollection", features },
-            positions,
-        };
-    }, [data, getPosition, getWeight]);
+    // 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.
+    const [prevData, setPrevData] = react.useState(data);
+    const [normalized, setNormalized] = react.useState(() => normalizeHeatmapData({ data, getPosition, getWeight }));
+    if (data !== prevData && !esToolkit.isEqual(data, prevData)) {
+        setPrevData(data);
+        setNormalized(normalizeHeatmapData({ data, getPosition, getWeight }));
+    }
     const resolvedStyle = react.useMemo(() => ({
         radiusPixels: style?.radiusPixels ?? 30,
         intensity: style?.intensity ?? 1,
@@ -5959,6 +5994,65 @@ const useHeatmap = (options) => {
     ]);
 };
 
+const WEB_MERCATOR_TILE_SIZE_PX = 256;
+/**
+ * Degrees of longitude/latitude spanned by a single screen pixel at `zoom`,
+ * near `latitudeDeg`, under Web Mercator.
+ *
+ * Longitude degrees-per-pixel is constant everywhere; latitude degrees-per-pixel
+ * scales by `cos(latitude)` because Mercator stretches higher latitudes. Used to
+ * convert a pixel label footprint into a geo bounding box so collision runs in
+ * the same lng/lat space the marker positions already live in.
+ */
+const degreesPerPixel$1 = (zoom, latitudeDeg) => {
+    const worldWidthPx = WEB_MERCATOR_TILE_SIZE_PX * 2 ** zoom;
+    const lng = 360 / worldWidthPx;
+    return { lng, lat: lng * Math.cos((latitudeDeg * Math.PI) / 180) };
+};
+/**
+ * Label footprint as a geo-space width/height, for collision testing.
+ *
+ * A rendered pill's size does NOT follow the zoom circle-size tier: `MapMarker` lays every pill out
+ * at the fixed {@link MARKER_PILL_CONTENT_LAYOUT_SIZE}, and the label text is capped at
+ * `maxLabelWidthPx` (ellipsis beyond). By default the box is sized to that cap — the widest pill
+ * that can render — so it is never smaller than what paints (no two labels overlap). Callers can pass
+ * a smaller `labelWidthPx` to pack denser at the cost of occasional overlap for long names; density
+ * is otherwise tuned via `paddingPx`.
+ */
+const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }) => {
+    const { circle, pillPaddingY } = MARKER_SIZE_MAP[MARKER_PILL_CONTENT_LAYOUT_SIZE];
+    const { maxLabelWidthPx, gapPx, paddingRightPx } = MARKER_TUNING.pill;
+    // Assumed text width: the render cap by default (upper bound → no overlap), or a caller override.
+    const textWidthPx = labelWidthPx ?? maxLabelWidthPx;
+    // Left pad (== pillPaddingY) + icon disc + gap + label text + right pad. Assume the icon disc is
+    // present (the wider case).
+    const widthPx = pillPaddingY + circle + gapPx + textWidthPx + paddingRightPx + 2 * paddingPx;
+    const heightPx = markerPillOuterHeightPx(MARKER_PILL_CONTENT_LAYOUT_SIZE) + 2 * paddingPx;
+    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
+    return { widthDeg: widthPx * perPixel.lng, heightDeg: heightPx * perPixel.lat };
+};
+/**
+ * Physical pill dimensions in px, **as the renderer paints them** (unpadded) — the full envelope at
+ * the render cap, matching `MapMarkerStickSurface` (`computeFullPillEnvelopeWidth` + the fixed md pill
+ * height). The stick solver uses these for tip / pill-centre geometry, kept distinct from the padded
+ * collision footprint (`labelFootprintDeg`, which adds `2 * paddingPx`) used only for keep-out — so the
+ * reserved pill centre lands where the pill actually paints. Assumes the icon disc is present (the wider
+ * case) and no direction indicator, mirroring `labelFootprintDeg`'s assumptions. Zoom-independent.
+ */
+const PHYSICAL_PILL_PX = {
+    widthPx: computeFullPillEnvelopeWidth(MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_TUNING.pill.maxLabelWidthPx, true, false),
+    heightPx: markerPillOuterHeightPx(MARKER_PILL_CONTENT_LAYOUT_SIZE),
+};
+/**
+ * Geo footprint for a circular on-screen obstacle (a cluster bubble or a marker pin) from its pixel
+ * diameter, so labels can collision-avoid it. A square box of side `diameterPx` centred on the
+ * obstacle — slightly conservative vs the inscribed circle, which is the safe side for a keep-out.
+ */
+const obstacleFootprintDeg = ({ zoom, latitudeDeg, diameterPx, }) => {
+    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
+    return { widthDeg: diameterPx * perPixel.lng, heightDeg: diameterPx * perPixel.lat };
+};
+
 /**
  * Do two label footprints overlap? Each is a box of its own size centred on its point, so the boxes
  * overlap when the centres are closer than the sum of their half-extents in each axis. Shared by the
@@ -5978,6 +6072,8 @@ const UP_ANGLE_RAD = -Math.PI / 2;
 /** Anchor pin radius in px (the `xs` dot, 8px + 2px border): only feeds the tip's soft floor. */
 const ANCHOR_DOT_RADIUS_PX = 5;
 const collidesWithPlaced = (point, footprint, placed) => placed.some(other => overlaps(point, footprint, other.point, other.footprint));
+/** Like {@link collidesWithPlaced} but only against cluster obstacles — the relaxed fallback's hard set. */
+const collidesWithClusters = (point, footprint, placed) => placed.some(other => other.isCluster === true && overlaps(point, footprint, other.point, other.footprint));
 /** Liang–Barsky: does the segment a→b enter the axis-aligned box [minX,minY]–[maxX,maxY]? */
 const segmentIntersectsBox = (a, b, minX, minY, maxX, maxY) => {
     const dx = b[0] - a[0];
@@ -6044,13 +6140,16 @@ const clearanceSq = (point, placed) => {
  * (`resolveTentativeTip` + `computePillCSSPlacement`), not the raw polar tip; the line is tested to
  * that tip.
  */
-const findStickOffset = ({ anchor, placed, footprint, degreesPerPixel, viewBox, baseDistancePx, radiusStepPx, radiusSteps, anglesPerRing, previousOffset, }) => {
-    // Recover the pill's px dimensions from the geo footprint (inverse of `labelFootprintDeg`), so the
-    // pill-centre geometry matches what the renderer paints.
-    const pillWidthPx = footprint.widthDeg / degreesPerPixel.lng;
-    const pillHeightPx = footprint.heightDeg / degreesPerPixel.lat;
-    const halfWidthDeg = footprint.widthDeg / 2;
-    const halfHeightDeg = footprint.heightDeg / 2;
+const findStickOffset = ({ anchor, placed, footprint, pillWidthPx, pillHeightPx, degreesPerPixel, viewBox, baseDistancePx, radiusStepPx, radiusSteps, anglesPerRing, previousOffset, clusterClearFallback, }) => {
+    // Geometry uses the physical (as-painted) pill size; the view-box clamp insets by its half-extents,
+    // so a pill that visually fits is not rejected. The padded `footprint` is used only for keep-out
+    // (`collidesWithPlaced`), not here — that separation is the point of SAGA-855.
+    // Known limitation: the reserved keep-out box (the narrower `footprint`) is centred on the physical
+    // pill centre, so for a lateral stick it no longer covers the pill's near (disc) end by a few px — a
+    // later label can clip that strip. The proper fix is the asymmetric "protect the disc" keep-out
+    // tracked in SAGA-873; accepted as-is here (small, disc-side).
+    const halfWidthDeg = (pillWidthPx * degreesPerPixel.lng) / 2;
+    const halfHeightDeg = (pillHeightPx * degreesPerPixel.lat) / 2;
     const outsideViewBox = (point) => viewBox !== undefined &&
         (point[0] < viewBox[0] + halfWidthDeg ||
             point[0] > viewBox[2] - halfWidthDeg ||
@@ -6123,7 +6222,36 @@ const findStickOffset = ({ anchor, placed, footprint, degreesPerPixel, viewBox,
             };
         }
     }
-    return fallback;
+    if (fallback !== undefined)
+        return fallback;
+    if (clusterClearFallback !== true)
+        return undefined;
+    let bestOnCanvas;
+    let bestOffCanvas;
+    for (let ring = 0; ring < radiusSteps; ring++) {
+        const distance = baseDistancePx + ring * radiusStepPx;
+        for (let a = 0; a < anglesPerRing; a++) {
+            const angleRad = UP_ANGLE_RAD + a * angleStep;
+            const { pillCentre } = geometryFor(angleRad, distance);
+            if (collidesWithClusters(pillCentre, footprint, placed))
+                continue;
+            const clearance = clearanceSq(pillCentre, placed);
+            if (outsideViewBox(pillCentre)) {
+                if (beats(clearance, bestOffCanvas))
+                    bestOffCanvas = { angleRad, distance, pillCentre, clearance };
+            }
+            else if (beats(clearance, bestOnCanvas)) {
+                bestOnCanvas = { angleRad, distance, pillCentre, clearance };
+            }
+        }
+    }
+    const chosen = bestOnCanvas ?? bestOffCanvas;
+    return chosen === undefined
+        ? undefined
+        : {
+            positioning: { type: "polar", angleRad: chosen.angleRad, distance: chosen.distance },
+            pillCentre: chosen.pillCentre,
+        };
 };
 
 const EMPTY_IDS = new Set();
@@ -6265,7 +6393,11 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
     // distant to overlap any label. Unwrapped around the same reference longitude as items.
     if (clusterPositions !== undefined && clusterFootprint !== undefined) {
         for (const position of clusterPositions) {
-            placed.push({ point: [unwrapLng(position[0], referenceLng), position[1]], footprint: clusterFootprint });
+            placed.push({
+                point: [unwrapLng(position[0], referenceLng), position[1]],
+                footprint: clusterFootprint,
+                isCluster: true,
+            });
         }
     }
     // ---- Tier A membership ----
@@ -6307,10 +6439,15 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
             placed.push({ point: candidate.point, footprint });
             continue;
         }
+        // If the anchor sits on a cluster, allow the solver's relaxed fallback to displace off it (clearing
+        // clusters, overlapping labels if need be) rather than leave a guaranteed label covering a cluster.
+        const anchorOnCluster = placed.some(other => other.isCluster === true && overlaps(other.point, other.footprint, candidate.point, footprint));
         const stick = findStickOffset({
             anchor: candidate.point,
             placed,
             footprint,
+            pillWidthPx: PHYSICAL_PILL_PX.widthPx,
+            pillHeightPx: PHYSICAL_PILL_PX.heightPx,
             degreesPerPixel,
             viewBox: planarViewBox,
             baseDistancePx: STICK_BASE_DISTANCE_PX,
@@ -6318,6 +6455,7 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
             radiusSteps: STICK_RADIUS_STEPS,
             anglesPerRing: STICK_ANGLES_PER_RING,
             previousOffset: previousStickOffsets?.get(candidate.id),
+            clusterClearFallback: anchorOnCluster,
         });
         if (stick !== undefined) {
             placements.set(candidate.id, { mode: "stick", stickPositioning: stick.positioning });
@@ -6398,53 +6536,6 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
     return placements;
 };
 
-const WEB_MERCATOR_TILE_SIZE_PX = 256;
-/**
- * Degrees of longitude/latitude spanned by a single screen pixel at `zoom`,
- * near `latitudeDeg`, under Web Mercator.
- *
- * Longitude degrees-per-pixel is constant everywhere; latitude degrees-per-pixel
- * scales by `cos(latitude)` because Mercator stretches higher latitudes. Used to
- * convert a pixel label footprint into a geo bounding box so collision runs in
- * the same lng/lat space the marker positions already live in.
- */
-const degreesPerPixel$1 = (zoom, latitudeDeg) => {
-    const worldWidthPx = WEB_MERCATOR_TILE_SIZE_PX * 2 ** zoom;
-    const lng = 360 / worldWidthPx;
-    return { lng, lat: lng * Math.cos((latitudeDeg * Math.PI) / 180) };
-};
-/**
- * Label footprint as a geo-space width/height, for collision testing.
- *
- * A rendered pill's size does NOT follow the zoom circle-size tier: `MapMarker` lays every pill out
- * at the fixed {@link MARKER_PILL_CONTENT_LAYOUT_SIZE}, and the label text is capped at
- * `maxLabelWidthPx` (ellipsis beyond). By default the box is sized to that cap — the widest pill
- * that can render — so it is never smaller than what paints (no two labels overlap). Callers can pass
- * a smaller `labelWidthPx` to pack denser at the cost of occasional overlap for long names; density
- * is otherwise tuned via `paddingPx`.
- */
-const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }) => {
-    const { circle, pillPaddingY } = MARKER_SIZE_MAP[MARKER_PILL_CONTENT_LAYOUT_SIZE];
-    const { maxLabelWidthPx, gapPx, paddingRightPx } = MARKER_TUNING.pill;
-    // Assumed text width: the render cap by default (upper bound → no overlap), or a caller override.
-    const textWidthPx = labelWidthPx ?? maxLabelWidthPx;
-    // Left pad (== pillPaddingY) + icon disc + gap + label text + right pad. Assume the icon disc is
-    // present (the wider case).
-    const widthPx = pillPaddingY + circle + gapPx + textWidthPx + paddingRightPx + 2 * paddingPx;
-    const heightPx = markerPillOuterHeightPx(MARKER_PILL_CONTENT_LAYOUT_SIZE) + 2 * paddingPx;
-    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
-    return { widthDeg: widthPx * perPixel.lng, heightDeg: heightPx * perPixel.lat };
-};
-/**
- * Geo footprint for a circular on-screen obstacle (a cluster bubble or a marker pin) from its pixel
- * diameter, so labels can collision-avoid it. A square box of side `diameterPx` centred on the
- * obstacle — slightly conservative vs the inscribed circle, which is the safe side for a keep-out.
- */
-const obstacleFootprintDeg = ({ zoom, latitudeDeg, diameterPx, }) => {
-    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
-    return { widthDeg: diameterPx * perPixel.lng, heightDeg: diameterPx * perPixel.lat };
-};
-
 const EMPTY_PLACEMENTS = new Map();
 /**
  * Assumed cluster-bubble diameter (px) for the obstacle footprint — a conservative constant that

package/index.esm.js

@@ -5886,6 +5886,57 @@ const useFitToContent = (api, handles, options) => {
     return useMemo(() => ({ hasFitted, isWaiting, fitNow }), [hasFitted, isWaiting, fitNow]);
 };
 
+/**
+ * Single dev-warning channel for `useHeatmap` (invalid data).
+ */
+const warnHeatmap = (message, ...details) => {
+    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped and must stay visible
+    console.warn(`[useHeatmap] ${message}`, ...details);
+};
+
+/**
+ * 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.
+ */
+const normalizeHeatmapData = ({ data, getPosition, getWeight, }) => {
+    const features = [];
+    const positions = [];
+    let invalidPositionCount = 0;
+    let invalidWeightCount = 0;
+    for (const item of data) {
+        const position = getPosition(item);
+        if (position === null)
+            continue;
+        const parsedPosition = geoJsonPositionSchema.safeParse(position);
+        if (!parsedPosition.success) {
+            invalidPositionCount++;
+            continue;
+        }
+        const weight = getWeight?.(item) ?? 1;
+        if (weight === 0)
+            continue;
+        if (!Number.isFinite(weight) || weight < 0) {
+            invalidWeightCount++;
+            continue;
+        }
+        positions.push(parsedPosition.data);
+        features.push({
+            type: "Feature",
+            geometry: { type: "Point", coordinates: parsedPosition.data },
+            properties: { weight },
+        });
+    }
+    if (invalidPositionCount > 0 || invalidWeightCount > 0) {
+        warnHeatmap(`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.`);
+    }
+    return {
+        features: { type: "FeatureCollection", features },
+        positions,
+    };
+};
+
 const EMPTY_CONTROLS$2 = {};
 /**
  * Weighted point heatmap layer handle (provider-agnostic).
@@ -5897,31 +5948,15 @@ const EMPTY_CONTROLS$2 = {};
 const useHeatmap = (options) => {
     const { id, name, data, getPosition, getWeight, style, controls, loading, fitParticipation = "all" } = options;
     const layerReady = useLayerReady(loading);
-    const normalized = useMemo(() => {
-        const features = [];
-        const positions = [];
-        for (const item of data) {
-            const position = getPosition(item);
-            if (position === null)
-                continue;
-            const parsedPosition = geoJsonPositionSchema.safeParse(position);
-            if (!parsedPosition.success)
-                continue;
-            const weight = getWeight?.(item) ?? 1;
-            if (!Number.isFinite(weight) || weight <= 0)
-                continue;
-            positions.push(parsedPosition.data);
-            features.push({
-                type: "Feature",
-                geometry: { type: "Point", coordinates: parsedPosition.data },
-                properties: { weight },
-            });
-        }
-        return {
-            features: { type: "FeatureCollection", features },
-            positions,
-        };
-    }, [data, getPosition, getWeight]);
+    // 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.
+    const [prevData, setPrevData] = useState(data);
+    const [normalized, setNormalized] = useState(() => normalizeHeatmapData({ data, getPosition, getWeight }));
+    if (data !== prevData && !isEqual(data, prevData)) {
+        setPrevData(data);
+        setNormalized(normalizeHeatmapData({ data, getPosition, getWeight }));
+    }
     const resolvedStyle = useMemo(() => ({
         radiusPixels: style?.radiusPixels ?? 30,
         intensity: style?.intensity ?? 1,
@@ -5958,6 +5993,65 @@ const useHeatmap = (options) => {
     ]);
 };
 
+const WEB_MERCATOR_TILE_SIZE_PX = 256;
+/**
+ * Degrees of longitude/latitude spanned by a single screen pixel at `zoom`,
+ * near `latitudeDeg`, under Web Mercator.
+ *
+ * Longitude degrees-per-pixel is constant everywhere; latitude degrees-per-pixel
+ * scales by `cos(latitude)` because Mercator stretches higher latitudes. Used to
+ * convert a pixel label footprint into a geo bounding box so collision runs in
+ * the same lng/lat space the marker positions already live in.
+ */
+const degreesPerPixel$1 = (zoom, latitudeDeg) => {
+    const worldWidthPx = WEB_MERCATOR_TILE_SIZE_PX * 2 ** zoom;
+    const lng = 360 / worldWidthPx;
+    return { lng, lat: lng * Math.cos((latitudeDeg * Math.PI) / 180) };
+};
+/**
+ * Label footprint as a geo-space width/height, for collision testing.
+ *
+ * A rendered pill's size does NOT follow the zoom circle-size tier: `MapMarker` lays every pill out
+ * at the fixed {@link MARKER_PILL_CONTENT_LAYOUT_SIZE}, and the label text is capped at
+ * `maxLabelWidthPx` (ellipsis beyond). By default the box is sized to that cap — the widest pill
+ * that can render — so it is never smaller than what paints (no two labels overlap). Callers can pass
+ * a smaller `labelWidthPx` to pack denser at the cost of occasional overlap for long names; density
+ * is otherwise tuned via `paddingPx`.
+ */
+const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }) => {
+    const { circle, pillPaddingY } = MARKER_SIZE_MAP[MARKER_PILL_CONTENT_LAYOUT_SIZE];
+    const { maxLabelWidthPx, gapPx, paddingRightPx } = MARKER_TUNING.pill;
+    // Assumed text width: the render cap by default (upper bound → no overlap), or a caller override.
+    const textWidthPx = labelWidthPx ?? maxLabelWidthPx;
+    // Left pad (== pillPaddingY) + icon disc + gap + label text + right pad. Assume the icon disc is
+    // present (the wider case).
+    const widthPx = pillPaddingY + circle + gapPx + textWidthPx + paddingRightPx + 2 * paddingPx;
+    const heightPx = markerPillOuterHeightPx(MARKER_PILL_CONTENT_LAYOUT_SIZE) + 2 * paddingPx;
+    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
+    return { widthDeg: widthPx * perPixel.lng, heightDeg: heightPx * perPixel.lat };
+};
+/**
+ * Physical pill dimensions in px, **as the renderer paints them** (unpadded) — the full envelope at
+ * the render cap, matching `MapMarkerStickSurface` (`computeFullPillEnvelopeWidth` + the fixed md pill
+ * height). The stick solver uses these for tip / pill-centre geometry, kept distinct from the padded
+ * collision footprint (`labelFootprintDeg`, which adds `2 * paddingPx`) used only for keep-out — so the
+ * reserved pill centre lands where the pill actually paints. Assumes the icon disc is present (the wider
+ * case) and no direction indicator, mirroring `labelFootprintDeg`'s assumptions. Zoom-independent.
+ */
+const PHYSICAL_PILL_PX = {
+    widthPx: computeFullPillEnvelopeWidth(MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_TUNING.pill.maxLabelWidthPx, true, false),
+    heightPx: markerPillOuterHeightPx(MARKER_PILL_CONTENT_LAYOUT_SIZE),
+};
+/**
+ * Geo footprint for a circular on-screen obstacle (a cluster bubble or a marker pin) from its pixel
+ * diameter, so labels can collision-avoid it. A square box of side `diameterPx` centred on the
+ * obstacle — slightly conservative vs the inscribed circle, which is the safe side for a keep-out.
+ */
+const obstacleFootprintDeg = ({ zoom, latitudeDeg, diameterPx, }) => {
+    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
+    return { widthDeg: diameterPx * perPixel.lng, heightDeg: diameterPx * perPixel.lat };
+};
+
 /**
  * Do two label footprints overlap? Each is a box of its own size centred on its point, so the boxes
  * overlap when the centres are closer than the sum of their half-extents in each axis. Shared by the
@@ -5977,6 +6071,8 @@ const UP_ANGLE_RAD = -Math.PI / 2;
 /** Anchor pin radius in px (the `xs` dot, 8px + 2px border): only feeds the tip's soft floor. */
 const ANCHOR_DOT_RADIUS_PX = 5;
 const collidesWithPlaced = (point, footprint, placed) => placed.some(other => overlaps(point, footprint, other.point, other.footprint));
+/** Like {@link collidesWithPlaced} but only against cluster obstacles — the relaxed fallback's hard set. */
+const collidesWithClusters = (point, footprint, placed) => placed.some(other => other.isCluster === true && overlaps(point, footprint, other.point, other.footprint));
 /** Liang–Barsky: does the segment a→b enter the axis-aligned box [minX,minY]–[maxX,maxY]? */
 const segmentIntersectsBox = (a, b, minX, minY, maxX, maxY) => {
     const dx = b[0] - a[0];
@@ -6043,13 +6139,16 @@ const clearanceSq = (point, placed) => {
  * (`resolveTentativeTip` + `computePillCSSPlacement`), not the raw polar tip; the line is tested to
  * that tip.
  */
-const findStickOffset = ({ anchor, placed, footprint, degreesPerPixel, viewBox, baseDistancePx, radiusStepPx, radiusSteps, anglesPerRing, previousOffset, }) => {
-    // Recover the pill's px dimensions from the geo footprint (inverse of `labelFootprintDeg`), so the
-    // pill-centre geometry matches what the renderer paints.
-    const pillWidthPx = footprint.widthDeg / degreesPerPixel.lng;
-    const pillHeightPx = footprint.heightDeg / degreesPerPixel.lat;
-    const halfWidthDeg = footprint.widthDeg / 2;
-    const halfHeightDeg = footprint.heightDeg / 2;
+const findStickOffset = ({ anchor, placed, footprint, pillWidthPx, pillHeightPx, degreesPerPixel, viewBox, baseDistancePx, radiusStepPx, radiusSteps, anglesPerRing, previousOffset, clusterClearFallback, }) => {
+    // Geometry uses the physical (as-painted) pill size; the view-box clamp insets by its half-extents,
+    // so a pill that visually fits is not rejected. The padded `footprint` is used only for keep-out
+    // (`collidesWithPlaced`), not here — that separation is the point of SAGA-855.
+    // Known limitation: the reserved keep-out box (the narrower `footprint`) is centred on the physical
+    // pill centre, so for a lateral stick it no longer covers the pill's near (disc) end by a few px — a
+    // later label can clip that strip. The proper fix is the asymmetric "protect the disc" keep-out
+    // tracked in SAGA-873; accepted as-is here (small, disc-side).
+    const halfWidthDeg = (pillWidthPx * degreesPerPixel.lng) / 2;
+    const halfHeightDeg = (pillHeightPx * degreesPerPixel.lat) / 2;
     const outsideViewBox = (point) => viewBox !== undefined &&
         (point[0] < viewBox[0] + halfWidthDeg ||
             point[0] > viewBox[2] - halfWidthDeg ||
@@ -6122,7 +6221,36 @@ const findStickOffset = ({ anchor, placed, footprint, degreesPerPixel, viewBox,
             };
         }
     }
-    return fallback;
+    if (fallback !== undefined)
+        return fallback;
+    if (clusterClearFallback !== true)
+        return undefined;
+    let bestOnCanvas;
+    let bestOffCanvas;
+    for (let ring = 0; ring < radiusSteps; ring++) {
+        const distance = baseDistancePx + ring * radiusStepPx;
+        for (let a = 0; a < anglesPerRing; a++) {
+            const angleRad = UP_ANGLE_RAD + a * angleStep;
+            const { pillCentre } = geometryFor(angleRad, distance);
+            if (collidesWithClusters(pillCentre, footprint, placed))
+                continue;
+            const clearance = clearanceSq(pillCentre, placed);
+            if (outsideViewBox(pillCentre)) {
+                if (beats(clearance, bestOffCanvas))
+                    bestOffCanvas = { angleRad, distance, pillCentre, clearance };
+            }
+            else if (beats(clearance, bestOnCanvas)) {
+                bestOnCanvas = { angleRad, distance, pillCentre, clearance };
+            }
+        }
+    }
+    const chosen = bestOnCanvas ?? bestOffCanvas;
+    return chosen === undefined
+        ? undefined
+        : {
+            positioning: { type: "polar", angleRad: chosen.angleRad, distance: chosen.distance },
+            pillCentre: chosen.pillCentre,
+        };
 };
 
 const EMPTY_IDS = new Set();
@@ -6264,7 +6392,11 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
     // distant to overlap any label. Unwrapped around the same reference longitude as items.
     if (clusterPositions !== undefined && clusterFootprint !== undefined) {
         for (const position of clusterPositions) {
-            placed.push({ point: [unwrapLng(position[0], referenceLng), position[1]], footprint: clusterFootprint });
+            placed.push({
+                point: [unwrapLng(position[0], referenceLng), position[1]],
+                footprint: clusterFootprint,
+                isCluster: true,
+            });
         }
     }
     // ---- Tier A membership ----
@@ -6306,10 +6438,15 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
             placed.push({ point: candidate.point, footprint });
             continue;
         }
+        // If the anchor sits on a cluster, allow the solver's relaxed fallback to displace off it (clearing
+        // clusters, overlapping labels if need be) rather than leave a guaranteed label covering a cluster.
+        const anchorOnCluster = placed.some(other => other.isCluster === true && overlaps(other.point, other.footprint, candidate.point, footprint));
         const stick = findStickOffset({
             anchor: candidate.point,
             placed,
             footprint,
+            pillWidthPx: PHYSICAL_PILL_PX.widthPx,
+            pillHeightPx: PHYSICAL_PILL_PX.heightPx,
             degreesPerPixel,
             viewBox: planarViewBox,
             baseDistancePx: STICK_BASE_DISTANCE_PX,
@@ -6317,6 +6454,7 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
             radiusSteps: STICK_RADIUS_STEPS,
             anglesPerRing: STICK_ANGLES_PER_RING,
             previousOffset: previousStickOffsets?.get(candidate.id),
+            clusterClearFallback: anchorOnCluster,
         });
         if (stick !== undefined) {
             placements.set(candidate.id, { mode: "stick", stickPositioning: stick.positioning });
@@ -6397,53 +6535,6 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
     return placements;
 };
 
-const WEB_MERCATOR_TILE_SIZE_PX = 256;
-/**
- * Degrees of longitude/latitude spanned by a single screen pixel at `zoom`,
- * near `latitudeDeg`, under Web Mercator.
- *
- * Longitude degrees-per-pixel is constant everywhere; latitude degrees-per-pixel
- * scales by `cos(latitude)` because Mercator stretches higher latitudes. Used to
- * convert a pixel label footprint into a geo bounding box so collision runs in
- * the same lng/lat space the marker positions already live in.
- */
-const degreesPerPixel$1 = (zoom, latitudeDeg) => {
-    const worldWidthPx = WEB_MERCATOR_TILE_SIZE_PX * 2 ** zoom;
-    const lng = 360 / worldWidthPx;
-    return { lng, lat: lng * Math.cos((latitudeDeg * Math.PI) / 180) };
-};
-/**
- * Label footprint as a geo-space width/height, for collision testing.
- *
- * A rendered pill's size does NOT follow the zoom circle-size tier: `MapMarker` lays every pill out
- * at the fixed {@link MARKER_PILL_CONTENT_LAYOUT_SIZE}, and the label text is capped at
- * `maxLabelWidthPx` (ellipsis beyond). By default the box is sized to that cap — the widest pill
- * that can render — so it is never smaller than what paints (no two labels overlap). Callers can pass
- * a smaller `labelWidthPx` to pack denser at the cost of occasional overlap for long names; density
- * is otherwise tuned via `paddingPx`.
- */
-const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }) => {
-    const { circle, pillPaddingY } = MARKER_SIZE_MAP[MARKER_PILL_CONTENT_LAYOUT_SIZE];
-    const { maxLabelWidthPx, gapPx, paddingRightPx } = MARKER_TUNING.pill;
-    // Assumed text width: the render cap by default (upper bound → no overlap), or a caller override.
-    const textWidthPx = labelWidthPx ?? maxLabelWidthPx;
-    // Left pad (== pillPaddingY) + icon disc + gap + label text + right pad. Assume the icon disc is
-    // present (the wider case).
-    const widthPx = pillPaddingY + circle + gapPx + textWidthPx + paddingRightPx + 2 * paddingPx;
-    const heightPx = markerPillOuterHeightPx(MARKER_PILL_CONTENT_LAYOUT_SIZE) + 2 * paddingPx;
-    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
-    return { widthDeg: widthPx * perPixel.lng, heightDeg: heightPx * perPixel.lat };
-};
-/**
- * Geo footprint for a circular on-screen obstacle (a cluster bubble or a marker pin) from its pixel
- * diameter, so labels can collision-avoid it. A square box of side `diameterPx` centred on the
- * obstacle — slightly conservative vs the inscribed circle, which is the safe side for a keep-out.
- */
-const obstacleFootprintDeg = ({ zoom, latitudeDeg, diameterPx, }) => {
-    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
-    return { widthDeg: diameterPx * perPixel.lng, heightDeg: diameterPx * perPixel.lat };
-};
-
 const EMPTY_PLACEMENTS = new Map();
 /**
  * Assumed cluster-bubble diameter (px) for the obstacle footprint — a conservative constant that

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.203",
+  "version": "0.2.206",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "3.8.0",
-    "@trackunit/css-class-variance-utilities": "2.3.3",
-    "@trackunit/react-form-components": "2.10.6",
-    "@trackunit/react-core-hooks": "1.25.3",
-    "@trackunit/geo-json-utils": "1.18.3",
-    "@trackunit/i18n-library-translation": "2.8.3",
+    "@trackunit/react-components": "3.8.1",
+    "@trackunit/css-class-variance-utilities": "2.3.4",
+    "@trackunit/react-form-components": "2.10.7",
+    "@trackunit/react-core-hooks": "1.25.4",
+    "@trackunit/geo-json-utils": "1.18.4",
+    "@trackunit/i18n-library-translation": "2.8.4",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.154",
-    "@trackunit/react-map-color-utils": "0.0.129",
-    "@trackunit/shared-utils": "1.19.3",
-    "@trackunit/ui-design-tokens": "1.18.3",
+    "@trackunit/react-map-adapter-shared": "0.0.155",
+    "@trackunit/react-map-color-utils": "0.0.130",
+    "@trackunit/shared-utils": "1.19.4",
+    "@trackunit/ui-design-tokens": "1.18.4",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.52.0",
     "tailwind-merge": "^2.0.0",

package/src/layers/buildLabelPlacement.d.ts

@@ -1,6 +1,6 @@
 import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
 import type { StickPositioning } from "../markers/model/markerDomTypes";
-import type { DegreesPerPixel, LabelFootprintDeg } from "./internal/labelFootprint";
+import { type DegreesPerPixel, type LabelFootprintDeg } from "./internal/labelFootprint";
 import { type StickOffset } from "./internal/stickSolver";
 import type { MapFocus } from "./mapFocus";
 type Position = readonly [number, number, ...Array<number>];

package/src/layers/internal/labelFootprint.d.ts

@@ -42,6 +42,18 @@ export type LabelFootprintParams = Readonly<{
  * is otherwise tuned via `paddingPx`.
  */
 export declare const labelFootprintDeg: ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }: LabelFootprintParams) => LabelFootprintDeg;
+/**
+ * Physical pill dimensions in px, **as the renderer paints them** (unpadded) — the full envelope at
+ * the render cap, matching `MapMarkerStickSurface` (`computeFullPillEnvelopeWidth` + the fixed md pill
+ * height). The stick solver uses these for tip / pill-centre geometry, kept distinct from the padded
+ * collision footprint (`labelFootprintDeg`, which adds `2 * paddingPx`) used only for keep-out — so the
+ * reserved pill centre lands where the pill actually paints. Assumes the icon disc is present (the wider
+ * case) and no direction indicator, mirroring `labelFootprintDeg`'s assumptions. Zoom-independent.
+ */
+export declare const PHYSICAL_PILL_PX: Readonly<{
+    widthPx: number;
+    heightPx: number;
+}>;
 /**
  * Geo footprint for a circular on-screen obstacle (a cluster bubble or a marker pin) from its pixel
  * diameter, so labels can collision-avoid it. A square box of side `diameterPx` centred on the

package/src/layers/internal/placementGeometry.d.ts

@@ -1,10 +1,14 @@
 import type { LabelFootprintDeg } from "./labelFootprint";
 /** An unwrapped lng/lat point used by label placement (longitudes made continuous per viewport). */
 export type PlanarPoint = readonly [number, number];
-/** A placed label: its centre plus the footprint it occupies (Tier A and Tier B use different sizes). */
-export type PlacedLabel = Readonly<{
+/**
+ * A placed obstacle: its centre plus the footprint it occupies. `isCluster` marks a cluster bubble
+ * (a hard keep-out that the stick solver's relaxed fallback still honours, unlike label obstacles).
+ */
+export type PlacedObstacle = Readonly<{
     point: PlanarPoint;
     footprint: LabelFootprintDeg;
+    isCluster?: boolean;
 }>;
 /**
  * Do two label footprints overlap? Each is a box of its own size centred on its point, so the boxes

package/src/layers/internal/stickSolver.d.ts

@@ -1,6 +1,6 @@
 import type { StickPositioning } from "../../markers/model/markerDomTypes";
 import type { DegreesPerPixel, LabelFootprintDeg } from "./labelFootprint";
-import { type PlacedLabel, type PlanarPoint } from "./placementGeometry";
+import { type PlacedObstacle, type PlanarPoint } from "./placementGeometry";
 type PolarStick = Extract<StickPositioning, {
     type: "polar";
 }>;
@@ -18,9 +18,17 @@ export type StickSolverParams = Readonly<{
     /** Asset anchor as an unwrapped lng/lat point (same planar space as `placed`). */
     anchor: PlanarPoint;
     /** Already-placed labels (unwrapped lng/lat + footprint) to avoid. */
-    placed: ReadonlyArray<PlacedLabel>;
-    /** Geo footprint of the displaced label (same box used for anchor collisions). */
+    placed: ReadonlyArray<PlacedObstacle>;
+    /** Geo footprint of the displaced label — the padded box, used **only** for keep-out collision. */
     footprint: LabelFootprintDeg;
+    /**
+     * Physical pill width in px, as the renderer paints it (unpadded full envelope). Drives the tip /
+     * pill-centre geometry and the view-box clamp, so the reserved centre matches where the pill paints —
+     * distinct from the padded `footprint` used for collision.
+     */
+    pillWidthPx: number;
+    /** Physical pill height in px, as the renderer paints it (unpadded). See `pillWidthPx`. */
+    pillHeightPx: number;
     /** Degrees spanned per screen pixel at the current zoom/latitude — converts the px ring to geo. */
     degreesPerPixel: DegreesPerPixel;
     /**
@@ -39,6 +47,13 @@ export type StickSolverParams = Readonly<{
     anglesPerRing: number;
     /** Previously-chosen offset for this asset — tried first so a stable label does not swing. */
     previousOffset?: StickOffset;
+    /**
+     * When true and no clean offset exists, run a relaxed last-resort scan that clears all **clusters**
+     * but may overlap other labels — so a guaranteed label whose anchor sits on a cluster is displaced
+     * off it rather than kept on the cluster. Set by the caller only when the anchor overlaps a cluster;
+     * for label-only crowding it stays false so the label keeps its anchor (fewer leader lines).
+     */
+    clusterClearFallback?: boolean;
 }>;
 /**
  * Finds a stick offset for a guaranteed (Tier-A) label whose anchor is taken.
@@ -58,5 +73,5 @@ export type StickSolverParams = Readonly<{
  * (`resolveTentativeTip` + `computePillCSSPlacement`), not the raw polar tip; the line is tested to
  * that tip.
  */
-export declare const findStickOffset: ({ anchor, placed, footprint, degreesPerPixel, viewBox, baseDistancePx, radiusStepPx, radiusSteps, anglesPerRing, previousOffset, }: StickSolverParams) => StickSolution | undefined;
+export declare const findStickOffset: ({ anchor, placed, footprint, pillWidthPx, pillHeightPx, degreesPerPixel, viewBox, baseDistancePx, radiusStepPx, radiusSteps, anglesPerRing, previousOffset, clusterClearFallback, }: StickSolverParams) => StickSolution | undefined;
 export {};

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

@@ -1,4 +1,4 @@
-import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { GeoJsonPosition } from "@trackunit/geo-json-utils";
 import type { CategoryKey, ControlConfig } from "../../controls/types";
 import type { FitParticipation, HeatmapLayerHandle } from "../types";
 export type HeatmapStyle = Readonly<{

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

@@ -0,0 +1,19 @@
+import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { GeoJsonFeatureCollection } from "../../types";
+export type NormalizedHeatmapData = Readonly<{
+    features: GeoJsonFeatureCollection;
+    positions: ReadonlyArray<GeoJsonPosition>;
+}>;
+type NormalizeHeatmapDataOptions<TItem> = Readonly<{
+    data: ReadonlyArray<TItem>;
+    getPosition: (item: TItem) => GeoJsonPosition | null;
+    getWeight: ((item: TItem) => number) | undefined;
+}>;
+/**
+ * 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.
+ */
+export declare const normalizeHeatmapData: <TItem>({ data, getPosition, getWeight, }: NormalizeHeatmapDataOptions<TItem>) => NormalizedHeatmapData;
+export {};

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

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