@trackunit/react-map 0.2.123 → 0.2.126

package/index.cjs.js

@@ -5579,6 +5579,102 @@ const useFitToContent = (api, handles, options) => {
     return react.useMemo(() => ({ hasFitted, isWaiting, fitNow }), [hasFitted, isWaiting, fitNow]);
 };
 
+const isWithinBounds = (position, bounds) => {
+    const [lng, lat] = position;
+    const [minLng, minLat, maxLng, maxLat] = 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;
+};
+/**
+ * Chooses which markers render a label so that no two labels overlap.
+ *
+ * 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.
+ *
+ * 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.
+ */
+const buildLabelPlacement = ({ items, getId, getPosition, bounds, footprint, ceiling, }) => {
+    const shown = new Set();
+    const placed = [];
+    for (const item of items) {
+        if (shown.size >= ceiling)
+            break;
+        const position = getPosition(item);
+        if (bounds !== null && !isWithinBounds(position, bounds))
+            continue;
+        if (placed.some(other => overlaps(other, position, footprint)))
+            continue;
+        shown.add(getId(item));
+        placed.push(position);
+    }
+    return shown;
+};
+
+const WEB_MERCATOR_TILE_SIZE_PX = 256;
+/**
+ * Degrees of longitude/latitude spanned by a single screen pixel at `zoom`,
+ * near `latitudeDeg`, under Web Mercator.
+ *
+ * Longitude degrees-per-pixel is constant everywhere; latitude degrees-per-pixel
+ * scales by `cos(latitude)` because Mercator stretches higher latitudes. Used to
+ * convert a pixel label footprint into a geo bounding box so collision runs in
+ * the same lng/lat space the marker positions already live in.
+ */
+const degreesPerPixel$1 = (zoom, latitudeDeg) => {
+    const worldWidthPx = WEB_MERCATOR_TILE_SIZE_PX * 2 ** zoom;
+    const lng = 360 / worldWidthPx;
+    return { lng, lat: lng * Math.cos((latitudeDeg * Math.PI) / 180) };
+};
+/**
+ * Upper-bound 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.
+ */
+const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx }) => {
+    const { circle, pillPaddingY } = MARKER_SIZE_MAP[MARKER_PILL_CONTENT_LAYOUT_SIZE];
+    const { maxLabelWidthPx, gapPx, paddingRightPx } = MARKER_TUNING.pill;
+    // Left pad (== pillPaddingY) + icon disc + gap + max label text + right pad. Assume the icon
+    // disc is present (the wider case) so the box stays an upper bound.
+    const widthPx = pillPaddingY + circle + gapPx + maxLabelWidthPx + paddingRightPx + 2 * paddingPx;
+    const heightPx = markerPillOuterHeightPx(MARKER_PILL_CONTENT_LAYOUT_SIZE) + 2 * paddingPx;
+    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
+    return { widthDeg: widthPx * perPixel.lng, heightDeg: heightPx * perPixel.lat };
+};
+
+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`.
+ *
+ * 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.
+ */
+const useLabelPlacement = ({ enabled, items, getId, getPosition, bounds, zoom, paddingPx, ceiling, }) => react.useMemo(() => {
+    if (!enabled)
+        return 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]);
+
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -12208,6 +12304,7 @@ exports.useExpandedIds = useExpandedIds;
 exports.useFitFeatureBounds = useFitFeatureBounds;
 exports.useFitToContent = useFitToContent;
 exports.useImageOverlay = useImageOverlay;
+exports.useLabelPlacement = useLabelPlacement;
 exports.useLayers = useLayers;
 exports.useMap = useMap;
 exports.useMapAnnotation = useMapAnnotation;

package/index.esm.js

@@ -5578,6 +5578,102 @@ const useFitToContent = (api, handles, options) => {
     return useMemo(() => ({ hasFitted, isWaiting, fitNow }), [hasFitted, isWaiting, fitNow]);
 };
 
+const isWithinBounds = (position, bounds) => {
+    const [lng, lat] = position;
+    const [minLng, minLat, maxLng, maxLat] = 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;
+};
+/**
+ * Chooses which markers render a label so that no two labels overlap.
+ *
+ * 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.
+ *
+ * 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.
+ */
+const buildLabelPlacement = ({ items, getId, getPosition, bounds, footprint, ceiling, }) => {
+    const shown = new Set();
+    const placed = [];
+    for (const item of items) {
+        if (shown.size >= ceiling)
+            break;
+        const position = getPosition(item);
+        if (bounds !== null && !isWithinBounds(position, bounds))
+            continue;
+        if (placed.some(other => overlaps(other, position, footprint)))
+            continue;
+        shown.add(getId(item));
+        placed.push(position);
+    }
+    return shown;
+};
+
+const WEB_MERCATOR_TILE_SIZE_PX = 256;
+/**
+ * Degrees of longitude/latitude spanned by a single screen pixel at `zoom`,
+ * near `latitudeDeg`, under Web Mercator.
+ *
+ * Longitude degrees-per-pixel is constant everywhere; latitude degrees-per-pixel
+ * scales by `cos(latitude)` because Mercator stretches higher latitudes. Used to
+ * convert a pixel label footprint into a geo bounding box so collision runs in
+ * the same lng/lat space the marker positions already live in.
+ */
+const degreesPerPixel$1 = (zoom, latitudeDeg) => {
+    const worldWidthPx = WEB_MERCATOR_TILE_SIZE_PX * 2 ** zoom;
+    const lng = 360 / worldWidthPx;
+    return { lng, lat: lng * Math.cos((latitudeDeg * Math.PI) / 180) };
+};
+/**
+ * Upper-bound 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.
+ */
+const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx }) => {
+    const { circle, pillPaddingY } = MARKER_SIZE_MAP[MARKER_PILL_CONTENT_LAYOUT_SIZE];
+    const { maxLabelWidthPx, gapPx, paddingRightPx } = MARKER_TUNING.pill;
+    // Left pad (== pillPaddingY) + icon disc + gap + max label text + right pad. Assume the icon
+    // disc is present (the wider case) so the box stays an upper bound.
+    const widthPx = pillPaddingY + circle + gapPx + maxLabelWidthPx + paddingRightPx + 2 * paddingPx;
+    const heightPx = markerPillOuterHeightPx(MARKER_PILL_CONTENT_LAYOUT_SIZE) + 2 * paddingPx;
+    const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
+    return { widthDeg: widthPx * perPixel.lng, heightDeg: heightPx * perPixel.lat };
+};
+
+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`.
+ *
+ * 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.
+ */
+const useLabelPlacement = ({ enabled, items, getId, getPosition, bounds, zoom, paddingPx, ceiling, }) => useMemo(() => {
+    if (!enabled)
+        return 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]);
+
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -12120,4 +12216,4 @@ const mockMapApi = (overrides) => {
  */
 setupLibraryTranslations();
 
-export { ClusterMarker, ClusterStick, Controls, DEFAULT_MARKER_SIZE_BREAKPOINTS, DefaultControls, Layers, MARKER_DARK_PILL, MARKER_DISC_BORDER_WIDTH_PX, MARKER_LIGHT_PILL, MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_SIZE_MAP, MARKER_TUNING, MapLoadingState, MapMarker, MapMarkerIcon, PanelIconButton, ShapeAnnotationLabel, buildExpandedIds, cvaMapMarker, cvaMarkerIndicator, mockMapApi, useAdaptiveMarkerHelpers, useAutoPanResolver, useCameraIdle, useCameraState, useClusterCountFormat, useControlStack, useControls, useDefaultControls, useDirectionIndicator, useEntitiesNearCursor, useExpandedIds, useFitFeatureBounds, useFitToContent, useImageOverlay, useLayers, useMap, useMapAnnotation, useMapAnnotations, useMapAppearanceControls, useMapKeyboardNavigation, useMarkerColors, useMarkerStateResolvers, useMarkers, usePanel, usePanelPreload, usePreviewMap, useRoute, useShapeLabelHelpers, useShapes, useViewportContext };
+export { ClusterMarker, ClusterStick, Controls, DEFAULT_MARKER_SIZE_BREAKPOINTS, DefaultControls, Layers, MARKER_DARK_PILL, MARKER_DISC_BORDER_WIDTH_PX, MARKER_LIGHT_PILL, MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_SIZE_MAP, MARKER_TUNING, MapLoadingState, MapMarker, MapMarkerIcon, PanelIconButton, ShapeAnnotationLabel, buildExpandedIds, cvaMapMarker, cvaMarkerIndicator, mockMapApi, useAdaptiveMarkerHelpers, useAutoPanResolver, useCameraIdle, useCameraState, useClusterCountFormat, useControlStack, useControls, useDefaultControls, useDirectionIndicator, useEntitiesNearCursor, useExpandedIds, useFitFeatureBounds, useFitToContent, useImageOverlay, useLabelPlacement, useLayers, useMap, useMapAnnotation, useMapAnnotations, useMapAppearanceControls, useMapKeyboardNavigation, useMarkerColors, useMarkerStateResolvers, useMarkers, usePanel, usePanelPreload, usePreviewMap, useRoute, useShapeLabelHelpers, useShapes, useViewportContext };

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.123",
+  "version": "0.2.126",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "2.11.7",
-    "@trackunit/css-class-variance-utilities": "1.14.28",
-    "@trackunit/react-form-components": "2.6.45",
-    "@trackunit/react-core-hooks": "1.21.39",
-    "@trackunit/geo-json-utils": "1.15.30",
-    "@trackunit/i18n-library-translation": "2.4.39",
+    "@trackunit/react-components": "2.13.0",
+    "@trackunit/css-class-variance-utilities": "1.14.29",
+    "@trackunit/react-form-components": "2.6.48",
+    "@trackunit/react-core-hooks": "1.21.41",
+    "@trackunit/geo-json-utils": "1.15.31",
+    "@trackunit/i18n-library-translation": "2.4.41",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.111",
-    "@trackunit/react-map-color-utils": "0.0.91",
-    "@trackunit/ui-design-tokens": "1.15.18",
+    "@trackunit/react-map-adapter-shared": "0.0.112",
+    "@trackunit/react-map-color-utils": "0.0.92",
+    "@trackunit/ui-design-tokens": "1.15.19",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.39.10",
     "tailwind-merge": "^2.0.0",

package/src/index.d.ts

@@ -53,6 +53,7 @@ export { useImageOverlay, type UseImageOverlayOptions, type UseImageOverlayRetur
 export { buildExpandedIds, useExpandedIds, type MapFocus, type MapFocusTier, type MapFocusTierDisplay, } from "./layers/mapFocus";
 export { useRoute, type UseRouteOptions, type UseRouteReturn } from "./layers/routes/useRoute";
 export { useFitToContent, type FitToContentOptions, type FitToContentResult } from "./layers/useFitToContent";
+export { useLabelPlacement, type UseLabelPlacementParams } from "./layers/useLabelPlacement";
 export { useLayers, type UseLayersReturn } from "./layers/useLayers";
 export { DEFAULT_MARKER_SIZE_BREAKPOINTS, MARKER_DISC_BORDER_WIDTH_PX, type MarkerSizeBreakpoint, type PickMarkerSizeOptions, type PickRenderMediumOptions, type PickSymbolDiameterOptions, } from "./layers/useMarkers/adaptiveHelpers";
 export { useMarkers, type UseMarkersOptions, type UseMarkersReturn } from "./layers/useMarkers/useMarkers";

package/src/layers/buildLabelPlacement.d.ts

@@ -0,0 +1,29 @@
+import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
+import type { LabelFootprintDeg } from "./internal/labelFootprint";
+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;
+    /** 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. */
+    footprint: LabelFootprintDeg;
+    /** Maximum number of labels to place (DOM-node ceiling). */
+    ceiling: number;
+}>;
+/**
+ * Chooses which markers render a label so that no two labels overlap.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare const buildLabelPlacement: <TAsset>({ items, getId, getPosition, bounds, footprint, ceiling, }: BuildLabelPlacementParams<TAsset>) => ReadonlySet<string>;
+export {};

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

@@ -0,0 +1,37 @@
+export type DegreesPerPixel = Readonly<{
+    lng: number;
+    lat: number;
+}>;
+/**
+ * Degrees of longitude/latitude spanned by a single screen pixel at `zoom`,
+ * near `latitudeDeg`, under Web Mercator.
+ *
+ * Longitude degrees-per-pixel is constant everywhere; latitude degrees-per-pixel
+ * scales by `cos(latitude)` because Mercator stretches higher latitudes. Used to
+ * convert a pixel label footprint into a geo bounding box so collision runs in
+ * the same lng/lat space the marker positions already live in.
+ */
+export declare const degreesPerPixel: (zoom: number, latitudeDeg: number) => DegreesPerPixel;
+export type LabelFootprintDeg = Readonly<{
+    widthDeg: number;
+    heightDeg: number;
+}>;
+export type LabelFootprintParams = Readonly<{
+    /** Current camera zoom. */
+    zoom: number;
+    /** Reference latitude (typically the viewport centre) for the lat-per-pixel scale. */
+    latitudeDeg: number;
+    /** Extra spacing added around every label — the density dial. */
+    paddingPx: number;
+}>;
+/**
+ * Upper-bound 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.
+ */
+export declare const labelFootprintDeg: ({ zoom, latitudeDeg, paddingPx }: LabelFootprintParams) => LabelFootprintDeg;

package/src/layers/useLabelPlacement.d.ts

@@ -0,0 +1,31 @@
+import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
+type Position = readonly [number, number, ...Array<number>];
+export type UseLabelPlacementParams<TAsset> = Readonly<{
+    /** When false the hook returns a stable empty set without computing placement. */
+    enabled: boolean;
+    /** Candidate markers, in the order they should be considered for a label. */
+    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;
+    /** Current camera view box; candidates outside it are skipped. `null` disables clipping. */
+    bounds: Readonly<GeoJsonBbox> | null;
+    /** Current camera zoom; drives the px→geo footprint scale. */
+    zoom: number;
+    /** Spacing added around every label footprint — the density dial. */
+    paddingPx: number;
+    /** Maximum number of labels to place (DOM-node ceiling). */
+    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`.
+ *
+ * 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.
+ */
+export declare const useLabelPlacement: <TAsset>({ enabled, items, getId, getPosition, bounds, zoom, paddingPx, ceiling, }: UseLabelPlacementParams<TAsset>) => ReadonlySet<string>;
+export {};