@trackunit/react-map 0.2.163 → 0.2.167

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.163",
+  "version": "0.2.167",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "3.1.3",
-    "@trackunit/css-class-variance-utilities": "2.0.17",
-    "@trackunit/react-form-components": "2.7.4",
-    "@trackunit/react-core-hooks": "1.22.2",
-    "@trackunit/geo-json-utils": "1.15.50",
-    "@trackunit/i18n-library-translation": "2.5.2",
+    "@trackunit/react-components": "3.1.5",
+    "@trackunit/css-class-variance-utilities": "2.0.18",
+    "@trackunit/react-form-components": "2.7.7",
+    "@trackunit/react-core-hooks": "1.22.3",
+    "@trackunit/geo-json-utils": "1.15.51",
+    "@trackunit/i18n-library-translation": "2.5.3",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.134",
-    "@trackunit/react-map-color-utils": "0.0.110",
-    "@trackunit/ui-design-tokens": "1.15.38",
+    "@trackunit/react-map-adapter-shared": "0.0.136",
+    "@trackunit/react-map-color-utils": "0.0.111",
+    "@trackunit/ui-design-tokens": "1.15.39",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.39.10",
     "tailwind-merge": "^2.0.0",

package/src/layers/buildLabelPlacement.d.ts

@@ -1,35 +1,60 @@
 import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
-import type { LabelFootprintDeg } from "./internal/labelFootprint";
+import type { StickPositioning } from "../markers/model/markerDomTypes";
+import type { DegreesPerPixel, LabelFootprintDeg } from "./internal/labelFootprint";
+import { type StickOffset } from "./internal/stickSolver";
 import type { MapFocus } from "./mapFocus";
 type Position = readonly [number, number, ...Array<number>];
+/** Where a chosen label renders: at its geo anchor, or displaced on a leader-line stick. */
+export type LabelPlacement = Readonly<{
+    mode: "anchor";
+}> | Readonly<{
+    mode: "stick";
+    stickPositioning: StickPositioning;
+}>;
 export type BuildLabelPlacementParams<TAsset> = Readonly<{
     items: ReadonlyArray<TAsset>;
     getId: (item: TAsset) => string;
     getPosition: (item: TAsset) => Position;
-    /** Priority tiers, evaluated high→low; only tier-matching items are label-eligible. */
+    /** Priority tiers, evaluated high→low; only tier-matching items are label-eligible (Tier B). */
     focus: MapFocus<TAsset>;
     /** Current camera view box; candidates outside it are skipped. `null` disables clipping. */
     bounds: Readonly<GeoJsonBbox> | null;
-    /** Geo footprint every label is assumed to occupy, for collision testing. */
+    /** Geo footprint every label occupies for collision (may be narrowed for density). */
     footprint: LabelFootprintDeg;
-    /** Maximum number of labels to place (DOM-node ceiling). */
+    /** Degrees per screen pixel at the current zoom/latitude — maps the px stick ring into geo. */
+    degreesPerPixel: DegreesPerPixel;
+    /**
+     * Maximum number of labels to place (DOM-node ceiling), across both tiers. Tier A counts toward
+     * it, so the "never dropped" guarantee only holds while `tierACount + |in-view mustShowIds| ≤
+     * ceiling`; callers must keep the guaranteed set within the ceiling.
+     */
     ceiling: number;
-    /** Previously-shown ids — kept preferentially within their tier (hysteresis). */
+    /** Size of the guaranteed set: the top-N by priority within the view box are never dropped. */
+    tierACount: number;
+    /** Always-guaranteed ids (e.g. the selected asset) — Tier A even if they match no tier. */
+    mustShowIds?: ReadonlySet<string>;
+    /** Previously-shown ids — kept preferentially within their Tier-B tier (hysteresis). */
     previousIds?: ReadonlySet<string>;
+    /** Previously-chosen stick offsets by id — reused so a displaced label does not swing. */
+    previousStickOffsets?: ReadonlyMap<string, StickOffset>;
 }>;
 /**
- * Chooses which markers render a label so that no two labels overlap, in priority order.
+ * Chooses which markers render a label, and how, in priority order.
+ *
+ * **Tier A (guaranteed):** every in-view `mustShowIds` marker (regardless of tier), plus the
+ * top-`tierACount` eligible markers by priority — the latter chosen high→low tier then, within a
+ * tier, by spatial spread so one cluster cannot consume the whole guarantee. None are dropped: each
+ * takes its anchor if collision-free, else a candidate-ring solver finds a leader-line **stick**
+ * offset (kept on-canvas), else it stays at the anchor overlapping. Tier A uses the same `footprint`
+ * as Tier B, so a guaranteed label may overlap a denser neighbour a little (accepted trade-off).
  *
- * Walks `focus.tiers` high→low; only items matching a tier are eligible. Within each tier,
- * incumbents (in `previousIds`) are considered before newcomers, and each group is visited in
- * dynamic **farthest-point** order — the candidate whose nearest-neighbour distance to every
- * already-placed label is largest is tried first — so labels spread across the view box rather
- * than lumping. Each pick is collision-tested against the placed footprints and skipped if it
- * would overlap. Placement stops at `ceiling`; the budget is otherwise emergent (what fits).
+ * **Tier B (collision-fill):** the remaining eligible markers, walked high→low tier, placed at their
+ * anchor only if collision-free with the (possibly narrower) `footprint`, most-dispersed-first, until
+ * the `ceiling` is hit. Incumbents (`previousIds`) are preferred within their tier (hysteresis).
  *
- * All geometry runs in longitudes unwrapped around the view-box centre, so a viewport crossing
- * the antimeridian is handled correctly. Deterministic: all ties (centroid seed and
- * farthest-point) break by `getId` ascending, so the result is independent of server return order.
+ * All geometry runs in longitudes unwrapped around the view-box centre, so a viewport crossing the
+ * 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, ceiling, previousIds, }: BuildLabelPlacementParams<TAsset>) => ReadonlySet<string>;
+export declare const buildLabelPlacement: <TAsset>({ items, getId, getPosition, focus, bounds, footprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }: BuildLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
 export {};

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

@@ -23,15 +23,22 @@ export type LabelFootprintParams = Readonly<{
     latitudeDeg: number;
     /** Extra spacing added around every label — the density dial. */
     paddingPx: number;
+    /**
+     * Assumed label-text width in px for the collision box. Defaults to the render cap
+     * `MARKER_TUNING.pill.maxLabelWidthPx`, which makes the box a true upper bound so no two labels
+     * ever overlap. A smaller value packs labels denser but lets a name wider than the assumption
+     * overlap its neighbour — a deliberate density/overlap trade-off, tuned in the browser.
+     */
+    labelWidthPx?: number;
 }>;
 /**
- * Upper-bound label footprint as a geo-space width/height, for collision testing.
+ * 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). We size the collision
- * box to that upper bound — widest pill that can render — so the box is never smaller
- * than what paints, which is what keeps the "no two labels overlap" guarantee honest.
- * Density is tuned via `paddingPx`, not by shrinking the box.
+ * 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`.
  */
-export declare const labelFootprintDeg: ({ zoom, latitudeDeg, paddingPx }: LabelFootprintParams) => LabelFootprintDeg;
+export declare const labelFootprintDeg: ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }: LabelFootprintParams) => LabelFootprintDeg;

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

@@ -0,0 +1,16 @@
+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<{
+    point: PlanarPoint;
+    footprint: LabelFootprintDeg;
+}>;
+/**
+ * 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
+ * placement core and the stick solver so Tier A and Tier B collide by exactly the same rule.
+ */
+export declare const overlaps: (a: PlanarPoint, aFootprint: LabelFootprintDeg, b: PlanarPoint, bFootprint: LabelFootprintDeg) => boolean;
+/** Squared euclidean distance between two planar points. */
+export declare const sqDistance: (a: PlanarPoint, b: PlanarPoint) => number;

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

@@ -0,0 +1,62 @@
+import type { StickPositioning } from "../../markers/model/markerDomTypes";
+import type { DegreesPerPixel, LabelFootprintDeg } from "./labelFootprint";
+import { type PlacedLabel, type PlanarPoint } from "./placementGeometry";
+type PolarStick = Extract<StickPositioning, {
+    type: "polar";
+}>;
+/** Polar stick offset in screen pixels — the incumbency hint and the solver's own output shape. */
+export type StickOffset = Readonly<{
+    angleRad: number;
+    distancePx: number;
+}>;
+/** A chosen stick: the polar positioning to render, plus the rendered pill centre to reserve. */
+export type StickSolution = Readonly<{
+    positioning: PolarStick;
+    pillCentre: PlanarPoint;
+}>;
+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). */
+    footprint: LabelFootprintDeg;
+    /** Degrees spanned per screen pixel at the current zoom/latitude — converts the px ring to geo. */
+    degreesPerPixel: DegreesPerPixel;
+    /**
+     * Planar view box `[minLng, minLat, maxLng, maxLat]` (unwrapped). When given, a candidate whose
+     * displaced pill would fall outside it (inset by half the pill) is rejected, so a guaranteed label
+     * is not pushed off-canvas and clipped. `undefined` disables the check.
+     */
+    viewBox?: readonly [number, number, number, number];
+    /** Innermost ring distance in px (typically `MARKER_TUNING.stick.defaultPositioning.distance`). */
+    baseDistancePx: number;
+    /** Radius increment per ring in px. */
+    radiusStepPx: number;
+    /** Number of rings tried outward from the base distance. */
+    radiusSteps: number;
+    /** Candidate angles per ring (evenly spaced, starting straight up). */
+    anglesPerRing: number;
+    /** Previously-chosen offset for this asset — tried first so a stable label does not swing. */
+    previousOffset?: StickOffset;
+}>;
+/**
+ * Finds a stick offset for a guaranteed (Tier-A) label whose anchor is taken.
+ *
+ * Searches a candidate ring — `anglesPerRing` evenly-spaced angles, at increasing radii from
+ * `baseDistancePx` outward (`radiusSteps` rings). At the shortest ring that has room it aims the
+ * stick into the **most open direction** — the footprint-free angle whose displaced label is
+ * farthest from every other label — preferring angles whose leader line does not cross a label, and
+ * breaking ties straight-up-first for determinism. Candidates whose pill would fall outside `viewBox`
+ * are rejected so a guaranteed label is not pushed off-canvas. If a ring offers only line-crossing
+ * angles it keeps looking outward for a clean one, else falls back to the most-open crossing angle of
+ * the innermost ring that had room; if every candidate is rejected it returns `undefined` (the caller
+ * then keeps the label at its anchor — never dropped). `previousOffset` is reused only while it stays
+ * footprint-free, on-canvas and line-clear, so a clean stick keeps its direction between settles.
+ *
+ * Geometry matches the renderer: the collision/reserved point is the **rendered pill centre**
+ * (`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 {};

package/src/layers/useLabelPlacement.d.ts

@@ -1,8 +1,9 @@
 import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
+import { type LabelPlacement } from "./buildLabelPlacement";
 import type { MapFocus } from "./mapFocus";
 type Position = readonly [number, number, ...Array<number>];
 export type UseLabelPlacementParams<TAsset> = Readonly<{
-    /** When false the hook returns a stable empty set and clears incumbency memory. */
+    /** When false the hook returns a stable empty map and clears incumbency memory. */
     enabled: boolean;
     /** Candidate markers; only those matching a `focus` tier are label-eligible. */
     items: ReadonlyArray<TAsset>;
@@ -18,19 +19,31 @@ export type UseLabelPlacementParams<TAsset> = Readonly<{
     zoom: number;
     /** Spacing added around every label footprint — the density dial. */
     paddingPx: number;
+    /** Assumed label-text width for the footprint; defaults to the render cap. Smaller = denser. */
+    labelWidthPx?: number;
     /** Maximum number of labels to place (DOM-node ceiling). */
     ceiling: number;
+    /** Guaranteed set size: the top-N by priority within the view box are never dropped (Tier A). */
+    tierACount: number;
+    /** Always-guaranteed ids (selected/hovered/proximity) — Tier A regardless of priority rank. */
+    mustShowIds?: ReadonlySet<string>;
+    /**
+     * 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
+     * view box moves ahead of the data. Does not clear incumbency memory (unlike `enabled: false`).
+     */
+    frozen?: boolean;
 }>;
 /**
- * Viewport-driven label placement with hysteresis: returns the ids of the markers that should
- * render a label such that no two labels overlap, in priority order, bounded by `ceiling`.
+ * Viewport-driven label placement with hysteresis: returns a map of the markers that should render
+ * a label to how they render it (`anchor` or a displaced `stick`), no two overlapping, in priority
+ * order, bounded by `ceiling`.
  *
- * Stateful wrapper around the pure {@link buildLabelPlacement} — feeds the previous result back
- * as `previousIds` so labels that were shown stay shown across pan/zoom refetches (incumbents
- * that leave the view box drop via candidate clipping). Memory resets when `focus.id` changes,
- * not on viewport change. Returns the previous `Set` reference when content is unchanged so
- * downstream `useMemo`/callbacks stay stable. Same render-phase-setState pattern as
- * `useExpandedIds`.
+ * Stateful wrapper around the pure {@link buildLabelPlacement} — feeds the previous result back as
+ * `previousIds` (so Tier-B labels stay shown across pan/zoom refetches) and as `previousStickOffsets`
+ * (so a displaced Tier-A label keeps its stick direction). Memory resets when `focus.id` changes,
+ * 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, ceiling, }: UseLabelPlacementParams<TAsset>) => ReadonlySet<string>;
+export declare const useLabelPlacement: <TAsset>({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, frozen, }: UseLabelPlacementParams<TAsset>) => ReadonlyMap<string, LabelPlacement>;
 export {};

package/migrations/entry.js.map

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