@trackunit/react-map 0.2.142 → 0.2.144

package/index.cjs.js

@@ -5584,38 +5584,134 @@ const isWithinBounds = (position, bounds) => {
     const lngInside = minLng > maxLng ? lng >= minLng || lng <= maxLng : lng >= minLng && lng <= maxLng;
     return lngInside && lat >= minLat && lat <= maxLat;
 };
-const overlaps = (a, b, footprint) => {
-    // Shortest angular longitude delta so labels near the antimeridian (e.g. 179.9° and
-    // -179.9°) are correctly seen as ~0.2° apart, not ~359.8°, matching `isWithinBounds`.
-    const rawLngDelta = Math.abs(a[0] - b[0]);
-    const lngDelta = Math.min(rawLngDelta, 360 - rawLngDelta);
-    return lngDelta < footprint.widthDeg && Math.abs(a[1] - b[1]) < footprint.heightDeg;
+/**
+ * Longitude of the view box centre, antimeridian-aware: a crossing box (minLng > maxLng, e.g.
+ * 170→-170) centres near ±180, not near 0. Used as the reference for unwrapping.
+ */
+const boundsCentreLng = (bounds) => {
+    const [minLng, , maxLng] = bounds;
+    return minLng > maxLng ? (minLng + maxLng + 360) / 2 : (minLng + maxLng) / 2;
+};
+/**
+ * Unwraps a longitude onto a continuous axis within ±180° of `reference`, so a viewport that
+ * straddles the antimeridian becomes one continuous span (e.g. -176 → 184 next to 176). All
+ * centroid/distance/overlap math then uses plain deltas with no ±180° discontinuity.
+ */
+const unwrapLng = (lng, reference) => lng - 360 * Math.round((lng - reference) / 360);
+const overlaps = (a, b, footprint) => Math.abs(a[0] - b[0]) < footprint.widthDeg && Math.abs(a[1] - b[1]) < footprint.heightDeg;
+const sqDistance = (a, b) => {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    return dx * dx + dy * dy;
 };
 /**
- * Chooses which markers render a label so that no two labels overlap.
+ * Chooses which markers render a label so that no two labels overlap, in priority order.
  *
- * Greedy placement: walks `items` in order, skips any outside the view box,
- * and adds a label only when its nominal footprint does not collide with an
- * already-placed one, stopping at `ceiling`. The budget is emergent — however
- * many non-overlapping labels fit, bounded by the ceiling.
+ * 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).
  *
- * Deterministic: identical input yields an identical set. Phase 1 places in the
- * caller-provided order; priority ordering, dispersion, and pin-on-a-stick
- * displacement layer on top in later phases.
+ * 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.
  */
-const buildLabelPlacement = ({ items, getId, getPosition, bounds, footprint, ceiling, }) => {
+const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, ceiling, previousIds, }) => {
     const shown = new Set();
     const placed = [];
-    for (const item of items) {
+    // Reference longitude for unwrapping: the view-box centre when clipping, else the lowest-id
+    // item's longitude — a fixed, order-independent anchor so the result never depends on input
+    // order (a plain "first item" reference would not; see the order-independence guarantee above).
+    let referenceLng;
+    if (bounds !== null) {
+        referenceLng = boundsCentreLng(bounds);
+    }
+    else {
+        let refItem;
+        let refId;
+        for (const item of items) {
+            const id = getId(item);
+            if (refId === undefined || id < refId) {
+                refId = id;
+                refItem = item;
+            }
+        }
+        referenceLng = refItem === undefined ? 0 : getPosition(refItem)[0];
+    }
+    const planar = (item) => {
+        const p = getPosition(item);
+        return [unwrapLng(p[0], referenceLng), p[1]];
+    };
+    // Below this squared distance a point is inside every label footprint, so it always overlaps.
+    const minFootprintSq = Math.min(footprint.widthDeg, footprint.heightDeg) ** 2;
+    // Try to place a group of same-tier candidates, most-dispersed-first, collision-gated.
+    const placeGroup = (group) => {
+        // Sort by id first so every tie below resolves by id ascending, deterministically.
+        const pool = group
+            .map(item => ({ id: getId(item), point: planar(item) }))
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        while (pool.length > 0 && shown.size < ceiling) {
+            let bestIndex = 0;
+            if (placed.length === 0) {
+                // Seed the very first label on the candidate nearest the group centroid so the
+                // spread fans out evenly from the middle.
+                let cx = 0;
+                let cy = 0;
+                for (const c of pool) {
+                    cx += c.point[0];
+                    cy += c.point[1];
+                }
+                const centroid = [cx / pool.length, cy / pool.length];
+                let bestSeedDist = Infinity;
+                pool.forEach((c, index) => {
+                    const d = sqDistance(c.point, centroid);
+                    if (d < bestSeedDist) {
+                        bestSeedDist = d;
+                        bestIndex = index;
+                    }
+                });
+            }
+            else {
+                // Pick the candidate whose nearest already-placed label is farthest away.
+                let bestMinDist = -1;
+                pool.forEach((c, index) => {
+                    let minDist = Infinity;
+                    for (const other of placed) {
+                        const d = sqDistance(other, c.point);
+                        if (d < minDist)
+                            minDist = d;
+                    }
+                    if (minDist > bestMinDist) {
+                        bestMinDist = minDist;
+                        bestIndex = index;
+                    }
+                });
+                // Even the most-dispersed remaining candidate sits inside a placed footprint → every
+                // candidate now overlaps something placed, so none can be added. Stop scanning this group.
+                if (bestMinDist < minFootprintSq)
+                    break;
+            }
+            const [chosen] = pool.splice(bestIndex, 1);
+            if (chosen === undefined)
+                break;
+            if (placed.some(other => overlaps(other, chosen.point, footprint)))
+                continue;
+            shown.add(chosen.id);
+            placed.push(chosen.point);
+        }
+    };
+    for (const tier of focus.tiers) {
         if (shown.size >= ceiling)
             break;
-        const position = getPosition(item);
-        if (bounds !== null && !isWithinBounds(position, bounds))
-            continue;
-        if (placed.some(other => overlaps(other, position, footprint)))
+        const candidates = items.filter(item => !shown.has(getId(item)) && tier.match(item) && (bounds === null || isWithinBounds(getPosition(item), bounds)));
+        if (previousIds === undefined) {
+            placeGroup(candidates);
             continue;
-        shown.add(getId(item));
-        placed.push(position);
+        }
+        placeGroup(candidates.filter(item => previousIds.has(getId(item))));
+        placeGroup(candidates.filter(item => !previousIds.has(getId(item))));
     }
     return shown;
 };
@@ -5658,21 +5754,47 @@ const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx }) => {
 
 const EMPTY_LABEL_IDS = new Set();
 /**
- * Viewport-driven label placement: returns the ids of the markers that should
- * render a label such that no two labels overlap, bounded by `ceiling`.
+ * 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`.
  *
- * Derives an upper-bound pill footprint (`labelFootprintDeg`) and delegates
- * selection to the pure `buildLabelPlacement`. Exposed as a hook so the placement
- * participates in React's stability model and later phases can hold incumbency
- * state here without changing the public surface.
+ * 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`.
  */
-const useLabelPlacement = ({ enabled, items, getId, getPosition, bounds, zoom, paddingPx, ceiling, }) => react.useMemo(() => {
-    if (!enabled)
+const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, ceiling, }) => {
+    const [snapshot, setSnapshot] = react.useState(() => ({
+        focusId: focus.id,
+        ids: EMPTY_LABEL_IDS,
+    }));
+    if (!enabled) {
+        if (snapshot.ids !== EMPTY_LABEL_IDS || snapshot.focusId !== focus.id) {
+            setSnapshot({ focusId: focus.id, ids: EMPTY_LABEL_IDS });
+        }
         return EMPTY_LABEL_IDS;
+    }
+    const prevIds = snapshot.focusId === focus.id ? snapshot.ids : EMPTY_LABEL_IDS;
     const latitudeDeg = bounds === null ? 0 : (bounds[1] + bounds[3]) / 2;
     const footprint = labelFootprintDeg({ zoom, latitudeDeg, paddingPx });
-    return buildLabelPlacement({ items, getId, getPosition, bounds, footprint, ceiling });
-}, [enabled, items, getId, getPosition, bounds, zoom, paddingPx, ceiling]);
+    const result = buildLabelPlacement({
+        items,
+        getId,
+        getPosition,
+        focus,
+        bounds,
+        footprint,
+        ceiling,
+        previousIds: prevIds,
+    });
+    // Return the previous reference when content is identical — keeps downstream caches stable.
+    const stable = result.size === prevIds.size && [...result].every(id => prevIds.has(id)) ? prevIds : result;
+    if (stable !== snapshot.ids || focus.id !== snapshot.focusId) {
+        setSnapshot({ focusId: focus.id, ids: stable });
+    }
+    return stable;
+};
 
 // ============================================================================
 // Helpers

package/index.esm.js

@@ -5583,38 +5583,134 @@ const isWithinBounds = (position, bounds) => {
     const lngInside = minLng > maxLng ? lng >= minLng || lng <= maxLng : lng >= minLng && lng <= maxLng;
     return lngInside && lat >= minLat && lat <= maxLat;
 };
-const overlaps = (a, b, footprint) => {
-    // Shortest angular longitude delta so labels near the antimeridian (e.g. 179.9° and
-    // -179.9°) are correctly seen as ~0.2° apart, not ~359.8°, matching `isWithinBounds`.
-    const rawLngDelta = Math.abs(a[0] - b[0]);
-    const lngDelta = Math.min(rawLngDelta, 360 - rawLngDelta);
-    return lngDelta < footprint.widthDeg && Math.abs(a[1] - b[1]) < footprint.heightDeg;
+/**
+ * Longitude of the view box centre, antimeridian-aware: a crossing box (minLng > maxLng, e.g.
+ * 170→-170) centres near ±180, not near 0. Used as the reference for unwrapping.
+ */
+const boundsCentreLng = (bounds) => {
+    const [minLng, , maxLng] = bounds;
+    return minLng > maxLng ? (minLng + maxLng + 360) / 2 : (minLng + maxLng) / 2;
+};
+/**
+ * Unwraps a longitude onto a continuous axis within ±180° of `reference`, so a viewport that
+ * straddles the antimeridian becomes one continuous span (e.g. -176 → 184 next to 176). All
+ * centroid/distance/overlap math then uses plain deltas with no ±180° discontinuity.
+ */
+const unwrapLng = (lng, reference) => lng - 360 * Math.round((lng - reference) / 360);
+const overlaps = (a, b, footprint) => Math.abs(a[0] - b[0]) < footprint.widthDeg && Math.abs(a[1] - b[1]) < footprint.heightDeg;
+const sqDistance = (a, b) => {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    return dx * dx + dy * dy;
 };
 /**
- * Chooses which markers render a label so that no two labels overlap.
+ * Chooses which markers render a label so that no two labels overlap, in priority order.
  *
- * Greedy placement: walks `items` in order, skips any outside the view box,
- * and adds a label only when its nominal footprint does not collide with an
- * already-placed one, stopping at `ceiling`. The budget is emergent — however
- * many non-overlapping labels fit, bounded by the ceiling.
+ * 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).
  *
- * Deterministic: identical input yields an identical set. Phase 1 places in the
- * caller-provided order; priority ordering, dispersion, and pin-on-a-stick
- * displacement layer on top in later phases.
+ * 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.
  */
-const buildLabelPlacement = ({ items, getId, getPosition, bounds, footprint, ceiling, }) => {
+const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, ceiling, previousIds, }) => {
     const shown = new Set();
     const placed = [];
-    for (const item of items) {
+    // Reference longitude for unwrapping: the view-box centre when clipping, else the lowest-id
+    // item's longitude — a fixed, order-independent anchor so the result never depends on input
+    // order (a plain "first item" reference would not; see the order-independence guarantee above).
+    let referenceLng;
+    if (bounds !== null) {
+        referenceLng = boundsCentreLng(bounds);
+    }
+    else {
+        let refItem;
+        let refId;
+        for (const item of items) {
+            const id = getId(item);
+            if (refId === undefined || id < refId) {
+                refId = id;
+                refItem = item;
+            }
+        }
+        referenceLng = refItem === undefined ? 0 : getPosition(refItem)[0];
+    }
+    const planar = (item) => {
+        const p = getPosition(item);
+        return [unwrapLng(p[0], referenceLng), p[1]];
+    };
+    // Below this squared distance a point is inside every label footprint, so it always overlaps.
+    const minFootprintSq = Math.min(footprint.widthDeg, footprint.heightDeg) ** 2;
+    // Try to place a group of same-tier candidates, most-dispersed-first, collision-gated.
+    const placeGroup = (group) => {
+        // Sort by id first so every tie below resolves by id ascending, deterministically.
+        const pool = group
+            .map(item => ({ id: getId(item), point: planar(item) }))
+            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        while (pool.length > 0 && shown.size < ceiling) {
+            let bestIndex = 0;
+            if (placed.length === 0) {
+                // Seed the very first label on the candidate nearest the group centroid so the
+                // spread fans out evenly from the middle.
+                let cx = 0;
+                let cy = 0;
+                for (const c of pool) {
+                    cx += c.point[0];
+                    cy += c.point[1];
+                }
+                const centroid = [cx / pool.length, cy / pool.length];
+                let bestSeedDist = Infinity;
+                pool.forEach((c, index) => {
+                    const d = sqDistance(c.point, centroid);
+                    if (d < bestSeedDist) {
+                        bestSeedDist = d;
+                        bestIndex = index;
+                    }
+                });
+            }
+            else {
+                // Pick the candidate whose nearest already-placed label is farthest away.
+                let bestMinDist = -1;
+                pool.forEach((c, index) => {
+                    let minDist = Infinity;
+                    for (const other of placed) {
+                        const d = sqDistance(other, c.point);
+                        if (d < minDist)
+                            minDist = d;
+                    }
+                    if (minDist > bestMinDist) {
+                        bestMinDist = minDist;
+                        bestIndex = index;
+                    }
+                });
+                // Even the most-dispersed remaining candidate sits inside a placed footprint → every
+                // candidate now overlaps something placed, so none can be added. Stop scanning this group.
+                if (bestMinDist < minFootprintSq)
+                    break;
+            }
+            const [chosen] = pool.splice(bestIndex, 1);
+            if (chosen === undefined)
+                break;
+            if (placed.some(other => overlaps(other, chosen.point, footprint)))
+                continue;
+            shown.add(chosen.id);
+            placed.push(chosen.point);
+        }
+    };
+    for (const tier of focus.tiers) {
         if (shown.size >= ceiling)
             break;
-        const position = getPosition(item);
-        if (bounds !== null && !isWithinBounds(position, bounds))
-            continue;
-        if (placed.some(other => overlaps(other, position, footprint)))
+        const candidates = items.filter(item => !shown.has(getId(item)) && tier.match(item) && (bounds === null || isWithinBounds(getPosition(item), bounds)));
+        if (previousIds === undefined) {
+            placeGroup(candidates);
             continue;
-        shown.add(getId(item));
-        placed.push(position);
+        }
+        placeGroup(candidates.filter(item => previousIds.has(getId(item))));
+        placeGroup(candidates.filter(item => !previousIds.has(getId(item))));
     }
     return shown;
 };
@@ -5657,21 +5753,47 @@ const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx }) => {
 
 const EMPTY_LABEL_IDS = new Set();
 /**
- * Viewport-driven label placement: returns the ids of the markers that should
- * render a label such that no two labels overlap, bounded by `ceiling`.
+ * 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`.
  *
- * Derives an upper-bound pill footprint (`labelFootprintDeg`) and delegates
- * selection to the pure `buildLabelPlacement`. Exposed as a hook so the placement
- * participates in React's stability model and later phases can hold incumbency
- * state here without changing the public surface.
+ * 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`.
  */
-const useLabelPlacement = ({ enabled, items, getId, getPosition, bounds, zoom, paddingPx, ceiling, }) => useMemo(() => {
-    if (!enabled)
+const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, ceiling, }) => {
+    const [snapshot, setSnapshot] = useState(() => ({
+        focusId: focus.id,
+        ids: EMPTY_LABEL_IDS,
+    }));
+    if (!enabled) {
+        if (snapshot.ids !== EMPTY_LABEL_IDS || snapshot.focusId !== focus.id) {
+            setSnapshot({ focusId: focus.id, ids: EMPTY_LABEL_IDS });
+        }
         return EMPTY_LABEL_IDS;
+    }
+    const prevIds = snapshot.focusId === focus.id ? snapshot.ids : EMPTY_LABEL_IDS;
     const latitudeDeg = bounds === null ? 0 : (bounds[1] + bounds[3]) / 2;
     const footprint = labelFootprintDeg({ zoom, latitudeDeg, paddingPx });
-    return buildLabelPlacement({ items, getId, getPosition, bounds, footprint, ceiling });
-}, [enabled, items, getId, getPosition, bounds, zoom, paddingPx, ceiling]);
+    const result = buildLabelPlacement({
+        items,
+        getId,
+        getPosition,
+        focus,
+        bounds,
+        footprint,
+        ceiling,
+        previousIds: prevIds,
+    });
+    // Return the previous reference when content is identical — keeps downstream caches stable.
+    const stable = result.size === prevIds.size && [...result].every(id => prevIds.has(id)) ? prevIds : result;
+    if (stable !== snapshot.ids || focus.id !== snapshot.focusId) {
+        setSnapshot({ focusId: focus.id, ids: stable });
+    }
+    return stable;
+};
 
 // ============================================================================
 // Helpers

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.142",
+  "version": "0.2.144",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "2.13.15",
+    "@trackunit/react-components": "2.13.16",
     "@trackunit/css-class-variance-utilities": "2.0.10",
-    "@trackunit/react-form-components": "2.6.63",
-    "@trackunit/react-core-hooks": "1.21.55",
+    "@trackunit/react-form-components": "2.6.64",
+    "@trackunit/react-core-hooks": "1.21.56",
     "@trackunit/geo-json-utils": "1.15.42",
-    "@trackunit/i18n-library-translation": "2.4.55",
+    "@trackunit/i18n-library-translation": "2.4.56",
     "react-minimal-pie-chart": "^8.4.0",
     "@trackunit/react-map-adapter-shared": "0.0.124",
     "@trackunit/react-map-color-utils": "0.0.103",

package/src/layers/buildLabelPlacement.d.ts

@@ -1,29 +1,35 @@
 import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
 import type { LabelFootprintDeg } from "./internal/labelFootprint";
+import type { MapFocus } from "./mapFocus";
 type Position = readonly [number, number, ...Array<number>];
 export type BuildLabelPlacementParams<TAsset> = Readonly<{
-    /** Candidate markers, in the order they should be considered for a label. */
     items: ReadonlyArray<TAsset>;
     getId: (item: TAsset) => string;
     getPosition: (item: TAsset) => Position;
+    /** Priority tiers, evaluated high→low; only tier-matching items are label-eligible. */
+    focus: MapFocus<TAsset>;
     /** Current camera view box; candidates outside it are skipped. `null` disables clipping. */
     bounds: Readonly<GeoJsonBbox> | null;
-    /** Nominal geo footprint every label is assumed to occupy, for collision testing. */
+    /** Geo footprint every label is assumed to occupy, for collision testing. */
     footprint: LabelFootprintDeg;
     /** Maximum number of labels to place (DOM-node ceiling). */
     ceiling: number;
+    /** Previously-shown ids — kept preferentially within their tier (hysteresis). */
+    previousIds?: ReadonlySet<string>;
 }>;
 /**
- * Chooses which markers render a label so that no two labels overlap.
+ * Chooses which markers render a label so that no two labels overlap, in priority order.
  *
- * Greedy placement: walks `items` in order, skips any outside the view box,
- * and adds a label only when its nominal footprint does not collide with an
- * already-placed one, stopping at `ceiling`. The budget is emergent — however
- * many non-overlapping labels fit, bounded by the ceiling.
+ * 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).
  *
- * Deterministic: identical input yields an identical set. Phase 1 places in the
- * caller-provided order; priority ordering, dispersion, and pin-on-a-stick
- * displacement layer on top in later phases.
+ * 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.
  */
-export declare const buildLabelPlacement: <TAsset>({ items, getId, getPosition, bounds, footprint, ceiling, }: BuildLabelPlacementParams<TAsset>) => ReadonlySet<string>;
+export declare const buildLabelPlacement: <TAsset>({ items, getId, getPosition, focus, bounds, footprint, ceiling, previousIds, }: BuildLabelPlacementParams<TAsset>) => ReadonlySet<string>;
 export {};

package/src/layers/useLabelPlacement.d.ts

@@ -1,14 +1,17 @@
 import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
+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 without computing placement. */
+    /** When false the hook returns a stable empty set and clears incumbency memory. */
     enabled: boolean;
-    /** Candidate markers, in the order they should be considered for a label. */
+    /** Candidate markers; only those matching a `focus` tier are label-eligible. */
     items: ReadonlyArray<TAsset>;
     /** Stable id accessor — pass a referentially stable function (module const or `useCallback`). */
     getId: (item: TAsset) => string;
     /** Stable position accessor — pass a referentially stable function. */
     getPosition: (item: TAsset) => Position;
+    /** Priority tiers (label order); `focus.id` also keys the incumbency memory. */
+    focus: MapFocus<TAsset>;
     /** Current camera view box; candidates outside it are skipped. `null` disables clipping and converts the footprint at the equator. */
     bounds: Readonly<GeoJsonBbox> | null;
     /** Current camera zoom; drives the px→geo footprint scale. */
@@ -19,13 +22,15 @@ export type UseLabelPlacementParams<TAsset> = Readonly<{
     ceiling: number;
 }>;
 /**
- * Viewport-driven label placement: returns the ids of the markers that should
- * render a label such that no two labels overlap, bounded by `ceiling`.
+ * 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`.
  *
- * Derives an upper-bound pill footprint (`labelFootprintDeg`) and delegates
- * selection to the pure `buildLabelPlacement`. Exposed as a hook so the placement
- * participates in React's stability model and later phases can hold incumbency
- * state here without changing the public surface.
+ * 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`.
  */
-export declare const useLabelPlacement: <TAsset>({ enabled, items, getId, getPosition, bounds, zoom, paddingPx, ceiling, }: UseLabelPlacementParams<TAsset>) => ReadonlySet<string>;
+export declare const useLabelPlacement: <TAsset>({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, ceiling, }: UseLabelPlacementParams<TAsset>) => ReadonlySet<string>;
 export {};