@trackunit/react-map 0.2.187 → 0.2.190

package/index.cjs.js

@@ -6116,7 +6116,7 @@ const disperseSelect = (pool, count, seeds) => {
  * antimeridian is handled correctly. Deterministic: ties break by `getId` ascending, so the result is
  * independent of server return order. Returns a placement map keyed by id.
  */
-const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }) => {
+const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, clusterPositions, clusterFootprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }) => {
     const placements = new Map();
     const placed = [];
     // Reference longitude for unwrapping: the view-box centre when clipping, else the lowest-id
@@ -6149,6 +6149,18 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
         : [unwrapLng(bounds[0], referenceLng), bounds[1], unwrapLng(bounds[2], referenceLng), bounds[3]];
     // Below this squared distance a point is inside every Tier-B footprint, so it always overlaps.
     const minFootprintSq = Math.min(footprint.widthDeg, footprint.heightDeg) ** 2;
+    // ---- Seed cluster bubbles as hard obstacles (SAGA-736) ----
+    // Pushed into `placed` before any label, so every collision test (Tier-A anchor, stick candidates,
+    // Tier-B anchor) already avoids clusters — no per-tier special-casing needed. Seeded as given, with
+    // no view-box clip: a cluster whose centre is just off-screen still shows its bubble on-screen and can
+    // be overlapped by an in-view edge label (anchor labels are not view-box clipped), so clipping by
+    // centre would reopen that gap. Cluster counts are small, and a genuinely far cluster is simply too
+    // 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 });
+        }
+    }
     // ---- Tier A membership ----
     const mustShow = mustShowIds ?? EMPTY_IDS;
     // Must-show is guaranteed even if it matches no tier (e.g. a selected asset with null state).
@@ -6316,8 +6328,23 @@ const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }) => {
     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
+ * covers up to a 3-digit count. Slightly over-reserving is the safe side for a hard "never cover a
+ * cluster" keep-out. Tunable in the browser.
+ */
+const CLUSTER_OBSTACLE_DIAMETER_PX = 44;
 const samePlacement = (a, b) => {
     if (a.mode === "anchor")
         return b.mode === "anchor";
@@ -6361,7 +6388,7 @@ const stickOffsetsFrom = (placements) => {
  * not on viewport change. Returns the previous map reference when content is unchanged so downstream
  * `useMemo`/callbacks stay stable. Same render-phase-setState pattern as `useExpandedIds`.
  */
-const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, frozen, }) => {
+const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, clusterPositions, frozen, }) => {
     const [snapshot, setSnapshot] = react.useState(() => ({
         focusId: focus.id,
         placements: EMPTY_PLACEMENTS,
@@ -6389,6 +6416,10 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
             focus,
             bounds,
             footprint,
+            clusterPositions,
+            clusterFootprint: clusterPositions === undefined
+                ? undefined
+                : obstacleFootprintDeg({ zoom, latitudeDeg, diameterPx: CLUSTER_OBSTACLE_DIAMETER_PX }),
             degreesPerPixel: degreesPerPixel$1(zoom, latitudeDeg),
             ceiling,
             tierACount,
@@ -6411,6 +6442,7 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
         ceiling,
         tierACount,
         mustShowIds,
+        clusterPositions,
         prev,
     ]);
     // Return the previous reference when content is identical — keeps downstream caches stable.

package/index.esm.js

@@ -6115,7 +6115,7 @@ const disperseSelect = (pool, count, seeds) => {
  * antimeridian is handled correctly. Deterministic: ties break by `getId` ascending, so the result is
  * independent of server return order. Returns a placement map keyed by id.
  */
-const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }) => {
+const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, clusterPositions, clusterFootprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }) => {
     const placements = new Map();
     const placed = [];
     // Reference longitude for unwrapping: the view-box centre when clipping, else the lowest-id
@@ -6148,6 +6148,18 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
         : [unwrapLng(bounds[0], referenceLng), bounds[1], unwrapLng(bounds[2], referenceLng), bounds[3]];
     // Below this squared distance a point is inside every Tier-B footprint, so it always overlaps.
     const minFootprintSq = Math.min(footprint.widthDeg, footprint.heightDeg) ** 2;
+    // ---- Seed cluster bubbles as hard obstacles (SAGA-736) ----
+    // Pushed into `placed` before any label, so every collision test (Tier-A anchor, stick candidates,
+    // Tier-B anchor) already avoids clusters — no per-tier special-casing needed. Seeded as given, with
+    // no view-box clip: a cluster whose centre is just off-screen still shows its bubble on-screen and can
+    // be overlapped by an in-view edge label (anchor labels are not view-box clipped), so clipping by
+    // centre would reopen that gap. Cluster counts are small, and a genuinely far cluster is simply too
+    // 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 });
+        }
+    }
     // ---- Tier A membership ----
     const mustShow = mustShowIds ?? EMPTY_IDS;
     // Must-show is guaranteed even if it matches no tier (e.g. a selected asset with null state).
@@ -6315,8 +6327,23 @@ const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }) => {
     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
+ * covers up to a 3-digit count. Slightly over-reserving is the safe side for a hard "never cover a
+ * cluster" keep-out. Tunable in the browser.
+ */
+const CLUSTER_OBSTACLE_DIAMETER_PX = 44;
 const samePlacement = (a, b) => {
     if (a.mode === "anchor")
         return b.mode === "anchor";
@@ -6360,7 +6387,7 @@ const stickOffsetsFrom = (placements) => {
  * not on viewport change. Returns the previous map reference when content is unchanged so downstream
  * `useMemo`/callbacks stay stable. Same render-phase-setState pattern as `useExpandedIds`.
  */
-const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, frozen, }) => {
+const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, clusterPositions, frozen, }) => {
     const [snapshot, setSnapshot] = useState(() => ({
         focusId: focus.id,
         placements: EMPTY_PLACEMENTS,
@@ -6388,6 +6415,10 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
             focus,
             bounds,
             footprint,
+            clusterPositions,
+            clusterFootprint: clusterPositions === undefined
+                ? undefined
+                : obstacleFootprintDeg({ zoom, latitudeDeg, diameterPx: CLUSTER_OBSTACLE_DIAMETER_PX }),
             degreesPerPixel: degreesPerPixel$1(zoom, latitudeDeg),
             ceiling,
             tierACount,
@@ -6410,6 +6441,7 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
         ceiling,
         tierACount,
         mustShowIds,
+        clusterPositions,
         prev,
     ]);
     // Return the previous reference when content is identical — keeps downstream caches stable.

package/migrations/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../../../libs/react/map/migrations/entry.ts"],"names":[],"mappings":"","sourcesContent":["export {};\n"]}

package/package.json

@@ -1,25 +1,25 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.187",
+  "version": "0.2.190",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "3.5.1",
-    "@trackunit/css-class-variance-utilities": "2.2.1",
-    "@trackunit/react-form-components": "2.9.1",
-    "@trackunit/react-core-hooks": "1.24.1",
-    "@trackunit/geo-json-utils": "1.17.1",
-    "@trackunit/i18n-library-translation": "2.7.1",
+    "@trackunit/react-components": "3.5.2",
+    "@trackunit/css-class-variance-utilities": "2.2.2",
+    "@trackunit/react-form-components": "2.9.2",
+    "@trackunit/react-core-hooks": "1.24.2",
+    "@trackunit/geo-json-utils": "1.17.2",
+    "@trackunit/i18n-library-translation": "2.7.2",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.148",
-    "@trackunit/react-map-color-utils": "0.0.123",
-    "@trackunit/shared-utils": "1.18.1",
-    "@trackunit/ui-design-tokens": "1.17.1",
+    "@trackunit/react-map-adapter-shared": "0.0.149",
+    "@trackunit/react-map-color-utils": "0.0.124",
+    "@trackunit/shared-utils": "1.18.2",
+    "@trackunit/ui-design-tokens": "1.17.2",
     "@floating-ui/react": "^0.26.25",
-    "es-toolkit": "^1.39.10",
+    "es-toolkit": "^1.52.0",
     "tailwind-merge": "^2.0.0",
     "zod": "^3.25.76"
   },

package/src/layers/buildLabelPlacement.d.ts

@@ -21,6 +21,17 @@ export type BuildLabelPlacementParams<TAsset> = Readonly<{
     bounds: Readonly<GeoJsonBbox> | null;
     /** Geo footprint every label occupies for collision (may be narrowed for density). */
     footprint: LabelFootprintDeg;
+    /**
+     * Cluster bubble positions (raw lng/lat), seeded as **hard** obstacles so no label of any tier is
+     * placed over a cluster. Unwrapped like items and seeded as given — the caller passes the in-view /
+     * near-view set; not re-clipped here, so an edge cluster whose bubble is partly on-screen is still
+     * avoided (clipping by centre would let an in-view edge label cover it). Marker pins are deliberately
+     * NOT obstacles — routing labels around a dense pin field is self-defeating and not the industry norm
+     * (deck.gl collision groups / Maplex soft weight ignore point symbols); see SAGA-736.
+     */
+    clusterPositions?: ReadonlyArray<Position>;
+    /** Geo footprint each cluster obstacle occupies (bubble size). Required when `clusterPositions` is set. */
+    clusterFootprint?: LabelFootprintDeg;
     /** Degrees per screen pixel at the current zoom/latitude — maps the px stick ring into geo. */
     degreesPerPixel: DegreesPerPixel;
     /**
@@ -56,5 +67,5 @@ export type BuildLabelPlacementParams<TAsset> = Readonly<{
  * antimeridian is handled correctly. Deterministic: ties break by `getId` ascending, so the result is
  * independent of server return order. Returns a placement map keyed by id.
  */
-export declare const buildLabelPlacement: <TAsset>({ items, getId, getPosition, focus, bounds, footprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }: BuildLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
+export declare const buildLabelPlacement: <TAsset>({ items, getId, getPosition, focus, bounds, footprint, clusterPositions, clusterFootprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }: BuildLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
 export {};

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

@@ -42,3 +42,13 @@ export type LabelFootprintParams = Readonly<{
  * is otherwise tuned via `paddingPx`.
  */
 export declare const labelFootprintDeg: ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }: LabelFootprintParams) => LabelFootprintDeg;
+/**
+ * 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.
+ */
+export declare const obstacleFootprintDeg: ({ zoom, latitudeDeg, diameterPx, }: Readonly<{
+    zoom: number;
+    latitudeDeg: number;
+    diameterPx: number;
+}>) => LabelFootprintDeg;

package/src/layers/useLabelPlacement.d.ts

@@ -27,6 +27,8 @@ export type UseLabelPlacementParams<TAsset> = Readonly<{
     tierACount: number;
     /** Always-guaranteed ids (selected/hovered/proximity) — Tier A regardless of priority rank. */
     mustShowIds?: ReadonlySet<string>;
+    /** Cluster bubble positions (raw lng/lat) — seeded as hard obstacles so labels never cover a cluster. */
+    clusterPositions?: ReadonlyArray<Position>;
     /**
      * When true, hold the last placement unchanged instead of recomputing — for use while a viewport
      * refetch is in flight, so labels resettle once (when data lands) rather than blinking as the
@@ -45,5 +47,5 @@ export type UseLabelPlacementParams<TAsset> = Readonly<{
  * not on viewport change. Returns the previous map reference when content is unchanged so downstream
  * `useMemo`/callbacks stay stable. Same render-phase-setState pattern as `useExpandedIds`.
  */
-export declare const useLabelPlacement: <TAsset>({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, frozen, }: UseLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
+export declare const useLabelPlacement: <TAsset>({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, clusterPositions, frozen, }: UseLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
 export {};