@trackunit/react-map 0.2.259 → 0.2.260

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.cjs.js CHANGED
@@ -6464,10 +6464,15 @@ const PHYSICAL_PILL_PX = {
6464
6464
  * Geo footprint for a circular on-screen obstacle (a cluster bubble or a marker pin) from its pixel
6465
6465
  * diameter, so labels can collision-avoid it. A square box of side `diameterPx` centred on the
6466
6466
  * obstacle — slightly conservative vs the inscribed circle, which is the safe side for a keep-out.
6467
+ *
6468
+ * `extraWidthPx` widens the box horizontally only (added to the width, not the height). Collision
6469
+ * tests a label at its assumed `labelWidthPx`, but the pill can paint up to the wider render cap;
6470
+ * passing that gap here keeps a long name placed flush against the obstacle from painting over it
6471
+ * (SAGA-943/736). Zero by default, so a plain obstacle stays a square.
6467
6472
  */
6468
- const obstacleFootprintDeg = ({ zoom, latitudeDeg, diameterPx, }) => {
6473
+ const obstacleFootprintDeg = ({ zoom, latitudeDeg, diameterPx, extraWidthPx = 0, }) => {
6469
6474
  const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
6470
- return { widthDeg: diameterPx * perPixel.lng, heightDeg: diameterPx * perPixel.lat };
6475
+ return { widthDeg: (diameterPx + extraWidthPx) * perPixel.lng, heightDeg: diameterPx * perPixel.lat };
6471
6476
  };
6472
6477
 
6473
6478
  /**
@@ -6777,7 +6782,7 @@ const disperseSelect = (pool, count, seeds) => {
6777
6782
  * antimeridian is handled correctly. Deterministic: ties break by `getId` ascending, so the result is
6778
6783
  * independent of server return order. Returns a placement map keyed by id.
6779
6784
  */
6780
- const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, clusterPositions, clusterFootprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }) => {
6785
+ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, clusterObstacles, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }) => {
6781
6786
  const placements = new Map();
6782
6787
  const placed = [];
6783
6788
  // Reference longitude for unwrapping: the view-box centre when clipping, else the lowest-id
@@ -6808,8 +6813,6 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6808
6813
  const planarViewBox = bounds === null
6809
6814
  ? undefined
6810
6815
  : [unwrapLng(bounds[0], referenceLng), bounds[1], unwrapLng(bounds[2], referenceLng), bounds[3]];
6811
- // Below this squared distance a point is inside every Tier-B footprint, so it always overlaps.
6812
- const minFootprintSq = Math.min(footprint.widthDeg, footprint.heightDeg) ** 2;
6813
6816
  // ---- Seed cluster bubbles as hard obstacles (SAGA-736) ----
6814
6817
  // Pushed into `placed` before any label, so every collision test (Tier-A anchor, stick candidates,
6815
6818
  // Tier-B anchor) already avoids clusters — no per-tier special-casing needed. Seeded as given, with
@@ -6817,8 +6820,8 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6817
6820
  // be overlapped by an in-view edge label (anchor labels are not view-box clipped), so clipping by
6818
6821
  // centre would reopen that gap. Cluster counts are small, and a genuinely far cluster is simply too
6819
6822
  // distant to overlap any label. Unwrapped around the same reference longitude as items.
6820
- if (clusterPositions !== undefined && clusterFootprint !== undefined) {
6821
- for (const position of clusterPositions) {
6823
+ if (clusterObstacles !== undefined) {
6824
+ for (const { position, footprint: clusterFootprint } of clusterObstacles) {
6822
6825
  placed.push({
6823
6826
  point: [unwrapLng(position[0], referenceLng), position[1]],
6824
6827
  footprint: clusterFootprint,
@@ -6826,6 +6829,22 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6826
6829
  });
6827
6830
  }
6828
6831
  }
6832
+ // Squared centre distance below which a candidate is guaranteed to overlap its nearest placed
6833
+ // obstacle — the inscribed-circle radius of the summed half-extents. The Tier-B early-out keys off
6834
+ // this: once even the best-placed candidate is this close to something, nothing else can fit. Labels
6835
+ // all share `footprint`, but per-cluster keep-outs (SAGA-943) can be SMALLER, so the bound must track
6836
+ // the smallest placed obstacle — assuming every obstacle is label-sized would drop a label that
6837
+ // actually clears a small bubble. Only clusters are smaller than a label; later-placed labels reuse
6838
+ // `footprint`, so computing this over the seeded obstacles here stays valid for the Tier-B pass.
6839
+ let minObstacleWidthDeg = footprint.widthDeg;
6840
+ let minObstacleHeightDeg = footprint.heightDeg;
6841
+ for (const obstacle of placed) {
6842
+ if (obstacle.footprint.widthDeg < minObstacleWidthDeg)
6843
+ minObstacleWidthDeg = obstacle.footprint.widthDeg;
6844
+ if (obstacle.footprint.heightDeg < minObstacleHeightDeg)
6845
+ minObstacleHeightDeg = obstacle.footprint.heightDeg;
6846
+ }
6847
+ const guaranteedOverlapDistSq = Math.min((footprint.widthDeg + minObstacleWidthDeg) / 2, (footprint.heightDeg + minObstacleHeightDeg) / 2) ** 2;
6829
6848
  // ---- Tier A membership ----
6830
6849
  const mustShow = mustShowIds ?? EMPTY_IDS;
6831
6850
  // Must-show is guaranteed even if it matches no tier (e.g. a selected asset with null state).
@@ -6929,8 +6948,9 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6929
6948
  bestIndex = index;
6930
6949
  }
6931
6950
  });
6932
- // Every remaining candidate sits inside a placed footprint → none can be added. Stop.
6933
- if (bestMinDist < minFootprintSq)
6951
+ // Even the best remaining candidate is guaranteed to overlap its nearest obstacle → none can
6952
+ // be added. Stop. Bound tracks the smallest obstacle, so labels near small clusters still place.
6953
+ if (bestMinDist < guaranteedOverlapDistSq)
6934
6954
  break;
6935
6955
  }
6936
6956
  const [chosen] = pool.splice(bestIndex, 1);
@@ -6962,12 +6982,6 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6962
6982
  };
6963
6983
 
6964
6984
  const EMPTY_PLACEMENTS = new Map();
6965
- /**
6966
- * Assumed cluster-bubble diameter (px) for the obstacle footprint — a conservative constant that
6967
- * covers up to a 3-digit count. Slightly over-reserving is the safe side for a hard "never cover a
6968
- * cluster" keep-out. Tunable in the browser.
6969
- */
6970
- const CLUSTER_OBSTACLE_DIAMETER_PX = 44;
6971
6985
  const samePlacement = (a, b) => {
6972
6986
  if (a.mode === "anchor")
6973
6987
  return b.mode === "anchor";
@@ -7011,7 +7025,7 @@ const stickOffsetsFrom = (placements) => {
7011
7025
  * not on viewport change. Returns the previous map reference when content is unchanged so downstream
7012
7026
  * `useMemo`/callbacks stay stable. Same render-phase-setState pattern as `useExpandedIds`.
7013
7027
  */
7014
- const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, clusterPositions, frozen, }) => {
7028
+ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, clusters, frozen, }) => {
7015
7029
  const [snapshot, setSnapshot] = react.useState(() => ({
7016
7030
  focusId: focus.id,
7017
7031
  placements: EMPTY_PLACEMENTS,
@@ -7032,6 +7046,10 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
7032
7046
  // One footprint for both tiers: `labelWidthPx` narrows the width only (height stays full, so
7033
7047
  // labels never overlap vertically). A guaranteed label may overlap a denser neighbour a little.
7034
7048
  const footprint = labelFootprintDeg({ zoom, latitudeDeg, paddingPx, labelWidthPx });
7049
+ // A label collides at `labelWidthPx` but can paint up to the render cap. Widen each cluster keep-out
7050
+ // horizontally by that gap so a long name placed flush against a bubble still can't paint over it —
7051
+ // the keep-out tracks the painted width, not the (narrower) collision width (SAGA-943/736).
7052
+ const clusterKeepOutExtraWidthPx = Math.max(0, MARKER_TUNING.pill.maxLabelWidthPx - (labelWidthPx ?? MARKER_TUNING.pill.maxLabelWidthPx));
7035
7053
  return buildLabelPlacement({
7036
7054
  items,
7037
7055
  getId,
@@ -7039,10 +7057,19 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
7039
7057
  focus,
7040
7058
  bounds,
7041
7059
  footprint,
7042
- clusterPositions,
7043
- clusterFootprint: clusterPositions === undefined
7044
- ? undefined
7045
- : obstacleFootprintDeg({ zoom, latitudeDeg, diameterPx: CLUSTER_OBSTACLE_DIAMETER_PX }),
7060
+ // Each cluster's keep-out is sized from its own rendered diameter (via the same sizer the cluster
7061
+ // marker renders with), so the biggest bubbles are never clipped and small ones are not
7062
+ // over-reserved (SAGA-943). Resting form: a hovered/selected pie (clustering off) opens larger than
7063
+ // its keep-out — a narrow, transient corner we accept rather than over-reserve every resting pie.
7064
+ clusterObstacles: clusters?.map(({ position, count, markerSize }) => ({
7065
+ position,
7066
+ footprint: obstacleFootprintDeg({
7067
+ zoom,
7068
+ latitudeDeg,
7069
+ diameterPx: resolveClusterBubbleSize({ count, markerSize, state: "default" }).diameterPx,
7070
+ extraWidthPx: clusterKeepOutExtraWidthPx,
7071
+ }),
7072
+ })),
7046
7073
  degreesPerPixel: degreesPerPixel$1(zoom, latitudeDeg),
7047
7074
  ceiling,
7048
7075
  tierACount,
@@ -7065,7 +7092,7 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
7065
7092
  ceiling,
7066
7093
  tierACount,
7067
7094
  mustShowIds,
7068
- clusterPositions,
7095
+ clusters,
7069
7096
  prev,
7070
7097
  ]);
7071
7098
  // Return the previous reference when content is identical — keeps downstream caches stable.
package/index.esm.js CHANGED
@@ -6463,10 +6463,15 @@ const PHYSICAL_PILL_PX = {
6463
6463
  * Geo footprint for a circular on-screen obstacle (a cluster bubble or a marker pin) from its pixel
6464
6464
  * diameter, so labels can collision-avoid it. A square box of side `diameterPx` centred on the
6465
6465
  * obstacle — slightly conservative vs the inscribed circle, which is the safe side for a keep-out.
6466
+ *
6467
+ * `extraWidthPx` widens the box horizontally only (added to the width, not the height). Collision
6468
+ * tests a label at its assumed `labelWidthPx`, but the pill can paint up to the wider render cap;
6469
+ * passing that gap here keeps a long name placed flush against the obstacle from painting over it
6470
+ * (SAGA-943/736). Zero by default, so a plain obstacle stays a square.
6466
6471
  */
6467
- const obstacleFootprintDeg = ({ zoom, latitudeDeg, diameterPx, }) => {
6472
+ const obstacleFootprintDeg = ({ zoom, latitudeDeg, diameterPx, extraWidthPx = 0, }) => {
6468
6473
  const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
6469
- return { widthDeg: diameterPx * perPixel.lng, heightDeg: diameterPx * perPixel.lat };
6474
+ return { widthDeg: (diameterPx + extraWidthPx) * perPixel.lng, heightDeg: diameterPx * perPixel.lat };
6470
6475
  };
6471
6476
 
6472
6477
  /**
@@ -6776,7 +6781,7 @@ const disperseSelect = (pool, count, seeds) => {
6776
6781
  * antimeridian is handled correctly. Deterministic: ties break by `getId` ascending, so the result is
6777
6782
  * independent of server return order. Returns a placement map keyed by id.
6778
6783
  */
6779
- const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, clusterPositions, clusterFootprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }) => {
6784
+ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, clusterObstacles, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }) => {
6780
6785
  const placements = new Map();
6781
6786
  const placed = [];
6782
6787
  // Reference longitude for unwrapping: the view-box centre when clipping, else the lowest-id
@@ -6807,8 +6812,6 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6807
6812
  const planarViewBox = bounds === null
6808
6813
  ? undefined
6809
6814
  : [unwrapLng(bounds[0], referenceLng), bounds[1], unwrapLng(bounds[2], referenceLng), bounds[3]];
6810
- // Below this squared distance a point is inside every Tier-B footprint, so it always overlaps.
6811
- const minFootprintSq = Math.min(footprint.widthDeg, footprint.heightDeg) ** 2;
6812
6815
  // ---- Seed cluster bubbles as hard obstacles (SAGA-736) ----
6813
6816
  // Pushed into `placed` before any label, so every collision test (Tier-A anchor, stick candidates,
6814
6817
  // Tier-B anchor) already avoids clusters — no per-tier special-casing needed. Seeded as given, with
@@ -6816,8 +6819,8 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6816
6819
  // be overlapped by an in-view edge label (anchor labels are not view-box clipped), so clipping by
6817
6820
  // centre would reopen that gap. Cluster counts are small, and a genuinely far cluster is simply too
6818
6821
  // distant to overlap any label. Unwrapped around the same reference longitude as items.
6819
- if (clusterPositions !== undefined && clusterFootprint !== undefined) {
6820
- for (const position of clusterPositions) {
6822
+ if (clusterObstacles !== undefined) {
6823
+ for (const { position, footprint: clusterFootprint } of clusterObstacles) {
6821
6824
  placed.push({
6822
6825
  point: [unwrapLng(position[0], referenceLng), position[1]],
6823
6826
  footprint: clusterFootprint,
@@ -6825,6 +6828,22 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6825
6828
  });
6826
6829
  }
6827
6830
  }
6831
+ // Squared centre distance below which a candidate is guaranteed to overlap its nearest placed
6832
+ // obstacle — the inscribed-circle radius of the summed half-extents. The Tier-B early-out keys off
6833
+ // this: once even the best-placed candidate is this close to something, nothing else can fit. Labels
6834
+ // all share `footprint`, but per-cluster keep-outs (SAGA-943) can be SMALLER, so the bound must track
6835
+ // the smallest placed obstacle — assuming every obstacle is label-sized would drop a label that
6836
+ // actually clears a small bubble. Only clusters are smaller than a label; later-placed labels reuse
6837
+ // `footprint`, so computing this over the seeded obstacles here stays valid for the Tier-B pass.
6838
+ let minObstacleWidthDeg = footprint.widthDeg;
6839
+ let minObstacleHeightDeg = footprint.heightDeg;
6840
+ for (const obstacle of placed) {
6841
+ if (obstacle.footprint.widthDeg < minObstacleWidthDeg)
6842
+ minObstacleWidthDeg = obstacle.footprint.widthDeg;
6843
+ if (obstacle.footprint.heightDeg < minObstacleHeightDeg)
6844
+ minObstacleHeightDeg = obstacle.footprint.heightDeg;
6845
+ }
6846
+ const guaranteedOverlapDistSq = Math.min((footprint.widthDeg + minObstacleWidthDeg) / 2, (footprint.heightDeg + minObstacleHeightDeg) / 2) ** 2;
6828
6847
  // ---- Tier A membership ----
6829
6848
  const mustShow = mustShowIds ?? EMPTY_IDS;
6830
6849
  // Must-show is guaranteed even if it matches no tier (e.g. a selected asset with null state).
@@ -6928,8 +6947,9 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6928
6947
  bestIndex = index;
6929
6948
  }
6930
6949
  });
6931
- // Every remaining candidate sits inside a placed footprint → none can be added. Stop.
6932
- if (bestMinDist < minFootprintSq)
6950
+ // Even the best remaining candidate is guaranteed to overlap its nearest obstacle → none can
6951
+ // be added. Stop. Bound tracks the smallest obstacle, so labels near small clusters still place.
6952
+ if (bestMinDist < guaranteedOverlapDistSq)
6933
6953
  break;
6934
6954
  }
6935
6955
  const [chosen] = pool.splice(bestIndex, 1);
@@ -6961,12 +6981,6 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
6961
6981
  };
6962
6982
 
6963
6983
  const EMPTY_PLACEMENTS = new Map();
6964
- /**
6965
- * Assumed cluster-bubble diameter (px) for the obstacle footprint — a conservative constant that
6966
- * covers up to a 3-digit count. Slightly over-reserving is the safe side for a hard "never cover a
6967
- * cluster" keep-out. Tunable in the browser.
6968
- */
6969
- const CLUSTER_OBSTACLE_DIAMETER_PX = 44;
6970
6984
  const samePlacement = (a, b) => {
6971
6985
  if (a.mode === "anchor")
6972
6986
  return b.mode === "anchor";
@@ -7010,7 +7024,7 @@ const stickOffsetsFrom = (placements) => {
7010
7024
  * not on viewport change. Returns the previous map reference when content is unchanged so downstream
7011
7025
  * `useMemo`/callbacks stay stable. Same render-phase-setState pattern as `useExpandedIds`.
7012
7026
  */
7013
- const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, clusterPositions, frozen, }) => {
7027
+ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, clusters, frozen, }) => {
7014
7028
  const [snapshot, setSnapshot] = useState(() => ({
7015
7029
  focusId: focus.id,
7016
7030
  placements: EMPTY_PLACEMENTS,
@@ -7031,6 +7045,10 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
7031
7045
  // One footprint for both tiers: `labelWidthPx` narrows the width only (height stays full, so
7032
7046
  // labels never overlap vertically). A guaranteed label may overlap a denser neighbour a little.
7033
7047
  const footprint = labelFootprintDeg({ zoom, latitudeDeg, paddingPx, labelWidthPx });
7048
+ // A label collides at `labelWidthPx` but can paint up to the render cap. Widen each cluster keep-out
7049
+ // horizontally by that gap so a long name placed flush against a bubble still can't paint over it —
7050
+ // the keep-out tracks the painted width, not the (narrower) collision width (SAGA-943/736).
7051
+ const clusterKeepOutExtraWidthPx = Math.max(0, MARKER_TUNING.pill.maxLabelWidthPx - (labelWidthPx ?? MARKER_TUNING.pill.maxLabelWidthPx));
7034
7052
  return buildLabelPlacement({
7035
7053
  items,
7036
7054
  getId,
@@ -7038,10 +7056,19 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
7038
7056
  focus,
7039
7057
  bounds,
7040
7058
  footprint,
7041
- clusterPositions,
7042
- clusterFootprint: clusterPositions === undefined
7043
- ? undefined
7044
- : obstacleFootprintDeg({ zoom, latitudeDeg, diameterPx: CLUSTER_OBSTACLE_DIAMETER_PX }),
7059
+ // Each cluster's keep-out is sized from its own rendered diameter (via the same sizer the cluster
7060
+ // marker renders with), so the biggest bubbles are never clipped and small ones are not
7061
+ // over-reserved (SAGA-943). Resting form: a hovered/selected pie (clustering off) opens larger than
7062
+ // its keep-out — a narrow, transient corner we accept rather than over-reserve every resting pie.
7063
+ clusterObstacles: clusters?.map(({ position, count, markerSize }) => ({
7064
+ position,
7065
+ footprint: obstacleFootprintDeg({
7066
+ zoom,
7067
+ latitudeDeg,
7068
+ diameterPx: resolveClusterBubbleSize({ count, markerSize, state: "default" }).diameterPx,
7069
+ extraWidthPx: clusterKeepOutExtraWidthPx,
7070
+ }),
7071
+ })),
7045
7072
  degreesPerPixel: degreesPerPixel$1(zoom, latitudeDeg),
7046
7073
  ceiling,
7047
7074
  tierACount,
@@ -7064,7 +7091,7 @@ const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds,
7064
7091
  ceiling,
7065
7092
  tierACount,
7066
7093
  mustShowIds,
7067
- clusterPositions,
7094
+ clusters,
7068
7095
  prev,
7069
7096
  ]);
7070
7097
  // Return the previous reference when content is identical — keeps downstream caches stable.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trackunit/react-map",
3
- "version": "0.2.259",
3
+ "version": "0.2.260",
4
4
  "repository": "https://github.com/Trackunit/manager",
5
5
  "license": "SEE LICENSE IN LICENSE.txt",
6
6
  "engines": {
package/src/index.d.ts CHANGED
@@ -59,7 +59,7 @@ export { buildExpandedIds, useExpandedIds, type MapFocus, type MapFocusTier, typ
59
59
  export { useRoute, type UseRouteOptions, type UseRouteReturn } from "./layers/routes/useRoute";
60
60
  export { useFitToContent, type FitToContentOptions, type FitToContentResult } from "./layers/useFitToContent";
61
61
  export { useHeatmap, type HeatmapStyle, type UseHeatmapOptions, type UseHeatmapReturn, } from "./layers/useHeatmap/useHeatmap";
62
- export { useLabelPlacement, type UseLabelPlacementParams } from "./layers/useLabelPlacement";
62
+ export { useLabelPlacement, type LabelPlacementCluster, type UseLabelPlacementParams, } from "./layers/useLabelPlacement";
63
63
  export { useLayers, type UseLayersReturn } from "./layers/useLayers";
64
64
  export { DEFAULT_MARKER_SIZE_BREAKPOINTS, MARKER_DISC_BORDER_WIDTH_PX, type MarkerSizeBreakpoint, type PickMarkerSizeOptions, type PickRenderMediumOptions, type PickSymbolDiameterOptions, } from "./layers/useMarkers/adaptiveHelpers";
65
65
  export { useMarkers, type UseMarkersOptions, type UseMarkersReturn } from "./layers/useMarkers/useMarkers";
@@ -4,6 +4,11 @@ import { type DegreesPerPixel, type LabelFootprintDeg } from "./internal/labelFo
4
4
  import { type StickOffset } from "./internal/stickSolver";
5
5
  import type { MapFocus } from "./mapFocus";
6
6
  type Position = readonly [number, number, ...Array<number>];
7
+ /** A cluster bubble seeded as a hard obstacle: its position and the geo footprint it occupies. */
8
+ export type ClusterObstacle = Readonly<{
9
+ position: Position;
10
+ footprint: LabelFootprintDeg;
11
+ }>;
7
12
  /** Where a chosen label renders: at its geo anchor, or displaced on a leader-line stick. */
8
13
  export type LabelPlacement = Readonly<{
9
14
  mode: "anchor";
@@ -22,16 +27,16 @@ export type BuildLabelPlacementParams<TAsset> = Readonly<{
22
27
  /** Geo footprint every label occupies for collision (may be narrowed for density). */
23
28
  footprint: LabelFootprintDeg;
24
29
  /**
25
- * Cluster bubble positions (raw lng/lat), seeded as **hard** obstacles so no label of any tier is
26
- * placed over a cluster. Unwrapped like items and seeded as given — the caller passes the in-view /
27
- * near-view set; not re-clipped here, so an edge cluster whose bubble is partly on-screen is still
28
- * avoided (clipping by centre would let an in-view edge label cover it). Marker pins are deliberately
29
- * NOT obstacles — routing labels around a dense pin field is self-defeating and not the industry norm
30
- * (deck.gl collision groups / Maplex soft weight ignore point symbols); see SAGA-736.
30
+ * Cluster bubbles, seeded as **hard** obstacles so no label of any tier is placed over a cluster.
31
+ * Each carries its own `footprint` sized from the bubble's real rendered diameter, so a big
32
+ * count-scaled bubble reserves more keep-out than a small one (SAGA-943). Unwrapped like items and
33
+ * seeded as given — the caller passes the in-view / near-view set; not re-clipped here, so an edge
34
+ * cluster whose bubble is partly on-screen is still avoided (clipping by centre would let an in-view
35
+ * edge label cover it). Marker pins are deliberately NOT obstacles — routing labels around a dense
36
+ * pin field is self-defeating and not the industry norm (deck.gl collision groups / Maplex soft
37
+ * weight ignore point symbols); see SAGA-736.
31
38
  */
32
- clusterPositions?: ReadonlyArray<Position>;
33
- /** Geo footprint each cluster obstacle occupies (bubble size). Required when `clusterPositions` is set. */
34
- clusterFootprint?: LabelFootprintDeg;
39
+ clusterObstacles?: ReadonlyArray<ClusterObstacle>;
35
40
  /** Degrees per screen pixel at the current zoom/latitude — maps the px stick ring into geo. */
36
41
  degreesPerPixel: DegreesPerPixel;
37
42
  /**
@@ -67,5 +72,5 @@ export type BuildLabelPlacementParams<TAsset> = Readonly<{
67
72
  * antimeridian is handled correctly. Deterministic: ties break by `getId` ascending, so the result is
68
73
  * independent of server return order. Returns a placement map keyed by id.
69
74
  */
70
- export declare const buildLabelPlacement: <TAsset>({ items, getId, getPosition, focus, bounds, footprint, clusterPositions, clusterFootprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }: BuildLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
75
+ export declare const buildLabelPlacement: <TAsset>({ items, getId, getPosition, focus, bounds, footprint, clusterObstacles, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }: BuildLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
71
76
  export {};
@@ -58,9 +58,15 @@ export declare const PHYSICAL_PILL_PX: Readonly<{
58
58
  * Geo footprint for a circular on-screen obstacle (a cluster bubble or a marker pin) from its pixel
59
59
  * diameter, so labels can collision-avoid it. A square box of side `diameterPx` centred on the
60
60
  * obstacle — slightly conservative vs the inscribed circle, which is the safe side for a keep-out.
61
+ *
62
+ * `extraWidthPx` widens the box horizontally only (added to the width, not the height). Collision
63
+ * tests a label at its assumed `labelWidthPx`, but the pill can paint up to the wider render cap;
64
+ * passing that gap here keeps a long name placed flush against the obstacle from painting over it
65
+ * (SAGA-943/736). Zero by default, so a plain obstacle stays a square.
61
66
  */
62
- export declare const obstacleFootprintDeg: ({ zoom, latitudeDeg, diameterPx, }: Readonly<{
67
+ export declare const obstacleFootprintDeg: ({ zoom, latitudeDeg, diameterPx, extraWidthPx, }: Readonly<{
63
68
  zoom: number;
64
69
  latitudeDeg: number;
65
70
  diameterPx: number;
71
+ extraWidthPx?: number;
66
72
  }>) => LabelFootprintDeg;
@@ -1,7 +1,18 @@
1
1
  import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
2
+ import type { MarkerDomSize } from "../markers/model/markerDomTypes";
2
3
  import { type LabelPlacement } from "./buildLabelPlacement";
3
4
  import type { MapFocus } from "./mapFocus";
4
5
  type Position = readonly [number, number, ...Array<number>];
6
+ /**
7
+ * A cluster bubble passed to placement: its position, member `count`, and the single-marker `markerSize`
8
+ * at the current zoom (`undefined` when clustering is on → donut). Placement sizes the keep-out from
9
+ * these so it matches the bubble's real rendered diameter and never clips the largest (SAGA-943).
10
+ */
11
+ export type LabelPlacementCluster = Readonly<{
12
+ position: Position;
13
+ count: number;
14
+ markerSize: MarkerDomSize | undefined;
15
+ }>;
5
16
  export type UseLabelPlacementParams<TAsset> = Readonly<{
6
17
  /** When false the hook returns a stable empty map and clears incumbency memory. */
7
18
  enabled: boolean;
@@ -27,8 +38,13 @@ export type UseLabelPlacementParams<TAsset> = Readonly<{
27
38
  tierACount: number;
28
39
  /** Always-guaranteed ids (selected/hovered/proximity) — Tier A regardless of priority rank. */
29
40
  mustShowIds?: ReadonlySet<string>;
30
- /** Cluster bubble positions (raw lng/lat) — seeded as hard obstacles so labels never cover a cluster. */
31
- clusterPositions?: ReadonlyArray<Position>;
41
+ /**
42
+ * Cluster bubbles — seeded as hard obstacles so labels never cover a cluster. Each carries its member
43
+ * `count` and the single-marker `markerSize` at the current zoom (`undefined` → donut form); the hook
44
+ * resolves these to the bubble's real rendered diameter, so the keep-out matches its actual size — big
45
+ * count-scaled bubbles reserve more than small ones, and nothing clips the largest (SAGA-943).
46
+ */
47
+ clusters?: ReadonlyArray<LabelPlacementCluster>;
32
48
  /**
33
49
  * When true, hold the last placement unchanged instead of recomputing — for use while a viewport
34
50
  * refetch is in flight, so labels resettle once (when data lands) rather than blinking as the
@@ -47,5 +63,5 @@ export type UseLabelPlacementParams<TAsset> = Readonly<{
47
63
  * not on viewport change. Returns the previous map reference when content is unchanged so downstream
48
64
  * `useMemo`/callbacks stay stable. Same render-phase-setState pattern as `useExpandedIds`.
49
65
  */
50
- export declare const useLabelPlacement: <TAsset>({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, clusterPositions, frozen, }: UseLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
66
+ export declare const useLabelPlacement: <TAsset>({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, clusters, frozen, }: UseLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
51
67
  export {};