@trackunit/react-map 0.2.125 → 0.2.127

package/index.cjs.js

@@ -1059,17 +1059,18 @@ const FallbackAnnotationContent = ({ store }) => {
     return (jsxRuntime.jsx("div", { className: "pointer-events-none col-start-1 row-start-1 self-end justify-self-start", children: jsxRuntime.jsx(AnnotationStack, { annotations: displayAnnotations, isExiting: isExiting }) }));
 };
 const DEBOUNCE_DELAY = 200;
-const cvaLoadingOverlay = cssClassVarianceUtilities.cvaMerge([
-    "pointer-events-none",
-    "col-start-1",
-    "row-start-1",
-    "flex",
-    "items-start",
-    "justify-center",
-    "transition-[opacity,display]",
-    "duration-150",
-    "ease-in-out",
-], {
+const cvaLoadingOverlay = cssClassVarianceUtilities.cva({
+    base: [
+        "pointer-events-none",
+        "col-start-1",
+        "row-start-1",
+        "flex",
+        "items-start",
+        "justify-center",
+        "transition-[opacity,display]",
+        "duration-150",
+        "ease-in-out",
+    ],
     variants: {
         visible: {
             true: ["opacity-100"],
@@ -1900,7 +1901,7 @@ const Custom = ({ config, overlaySide = undefined, resolved, placement }) => {
 };
 
 /** Shared padding for interactive menu items (button, toggle, stepper, select, radioGroup). */
-const cvaControlMenuItemBase = cssClassVarianceUtilities.cvaMerge(["px-3", "py-2"]);
+const cvaControlMenuItemBase = cssClassVarianceUtilities.cva({ base: ["px-3", "py-2"] });
 // ============================================================================
 // Cross-Cutting Middleware
 // ============================================================================
@@ -2697,21 +2698,22 @@ const ControlsInner = ({ api, controls, className }) => {
 // shallow equality is sufficient; no custom comparator needed.
 const Controls = react.memo(ControlsInner);
 
-const cvaMapPreview = cssClassVarianceUtilities.cvaMerge([
-    "relative",
-    "h-[72px]",
-    "w-[72px]",
-    "overflow-clip",
-    "[--radius:theme(borderRadius.xl)]",
-    "[--border:2px]",
-    "rounded-[var(--radius)]",
-    "before:pointer-events-none",
-    "before:absolute",
-    "before:inset-0",
-    "before:z-10",
-    "before:rounded-[var(--radius)]",
-    "before:border-[length:var(--border)]",
-], {
+const cvaMapPreview = cssClassVarianceUtilities.cva({
+    base: [
+        "relative",
+        "h-[72px]",
+        "w-[72px]",
+        "overflow-clip",
+        "[--radius:theme(borderRadius.xl)]",
+        "[--border:2px]",
+        "rounded-[var(--radius)]",
+        "before:pointer-events-none",
+        "before:absolute",
+        "before:inset-0",
+        "before:z-10",
+        "before:rounded-[var(--radius)]",
+        "before:border-[length:var(--border)]",
+    ],
     variants: {
         selected: {
             true: ["before:border-primary-500", "before:ring-2", "before:ring-inset", "before:ring-white"],
@@ -3980,19 +3982,21 @@ const resolveMarkerDomSize = (size, direction, form) => {
  * properties that need to animate, intentionally excluding `width` to prevent
  * non-composited layout thrashing. See `MarkerAnimatedSurface.tsx` for details.
  */
-const cvaMapMarker = cssClassVarianceUtilities.cvaMerge([
-    "inline-flex",
-    "items-center",
-    "relative",
-    "overflow-hidden",
-    "select-none",
-    "cursor-pointer",
-    "rounded-full",
-    "outline-none",
-    "focus-visible:ring-2",
-    "focus-visible:ring-info-500",
-    "focus-visible:ring-offset-2",
-]);
+const cvaMapMarker = cssClassVarianceUtilities.cva({
+    base: [
+        "inline-flex",
+        "items-center",
+        "relative",
+        "overflow-hidden",
+        "select-none",
+        "cursor-pointer",
+        "rounded-full",
+        "outline-none",
+        "focus-visible:ring-2",
+        "focus-visible:ring-info-500",
+        "focus-visible:ring-offset-2",
+    ],
+});
 /**
  * Label span inside pill markers.
  *
@@ -4005,19 +4009,14 @@ const cvaMapMarker = cssClassVarianceUtilities.cvaMerge([
  * alone biases the text upward (extra space below). `overflow-x: clip` gives the
  * horizontal ellipsis without a vertical clip on the span itself.
  */
-const cvaPillLabel = cssClassVarianceUtilities.cvaMerge([
-    "min-w-0",
-    "flex-1",
-    "overflow-x-clip",
-    "whitespace-nowrap",
-    "text-ellipsis",
-    "font-medium",
-    "leading-none",
-]);
+const cvaPillLabel = cssClassVarianceUtilities.cva({
+    base: ["min-w-0", "flex-1", "overflow-x-clip", "whitespace-nowrap", "text-ellipsis", "font-medium", "leading-none"],
+});
 /**
  * Inner indicator disc: marker fill via `--marker-color`, border via CSS `color-mix` on that token (plan §5).
  */
-const cvaMarkerIndicator = cssClassVarianceUtilities.cvaMerge(["rounded-full", "bg-[var(--marker-color)]", "flex", "items-center", "justify-center"], {
+const cvaMarkerIndicator = cssClassVarianceUtilities.cva({
+    base: ["rounded-full", "bg-[var(--marker-color)]", "flex", "items-center", "justify-center"],
     variants: {
         size: {
             xs: ["h-2", "w-2"],
@@ -5579,6 +5578,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
 // ============================================================================
@@ -6403,20 +6498,21 @@ const extractSinglePartInfo = (geometry) => {
     }
 };
 
-const cvaShapeLabel = cssClassVarianceUtilities.cvaMerge([
-    "select-none",
-    "inline-flex",
-    "items-center",
-    "gap-1",
-    "whitespace-nowrap",
-    "px-2",
-    "py-0.5",
-    "text-xs",
-    "font-medium",
-    "leading-tight",
-    "transition-opacity",
-    "duration-150",
-], {
+const cvaShapeLabel = cssClassVarianceUtilities.cva({
+    base: [
+        "select-none",
+        "inline-flex",
+        "items-center",
+        "gap-1",
+        "whitespace-nowrap",
+        "px-2",
+        "py-0.5",
+        "text-xs",
+        "font-medium",
+        "leading-tight",
+        "transition-opacity",
+        "duration-150",
+    ],
     variants: {
         theme: {
             light: ["shadow-sm"],
@@ -6473,7 +6569,8 @@ const EDGE_LABEL_BORDER_RADIUS = {
         right: "3px 0 3px 3px",
     },
 };
-const cvaFitMode = cssClassVarianceUtilities.cvaMerge([], {
+const cvaFitMode = cssClassVarianceUtilities.cva({
+    base: [],
     variants: {
         fitMode: {
             fits: ["pointer-events-auto"],
@@ -12208,6 +12305,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

@@ -3,7 +3,7 @@ import { useNamespaceTranslation, registerTranslations } from '@trackunit/i18n-l
 import { INITIAL_CAMERA_STATE, INITIAL_MAP_STATUS, KEYBOARD_PAN_AMOUNT, KEYBOARD_ZOOM_AMOUNT, mapAppearanceSchema, DEFAULT_MAP_APPEARANCE, WORLD_BBOX, INITIAL_INTERACTION_STATE, mapThemeSchema, mergeAntimeridianFeatures, extractSourceData, computeMarkerDomPortalZIndex, densifyGeodesicFeatures, angularDistance, intermediatePoint, GEODESIC_MAX_SEGMENT_KM, geometryTypeToShapeType, resolveStrokeColors } from '@trackunit/react-map-adapter-shared';
 export { ANCHOR_SELECTOR, DEFAULT_MAP_APPEARANCE, HIT_SURFACE_SELECTOR, INITIAL_CAMERA_STATE, INITIAL_INTERACTION_STATE, INITIAL_MAP_STATE, INITIAL_MAP_STATUS, computeMarkerDomPortalZIndex, defineAdapter, geometryTypeToShapeType, mapAppearanceSchema, mapThemeSchema, mapTypeSchema } from '@trackunit/react-map-adapter-shared';
 import { useSyncExternalStore, useMemo, useState, useRef, useCallback, useLayoutEffect, useEffect, useReducer, createContext, useContext, memo, Suspense, useId, Fragment as Fragment$1, forwardRef } from 'react';
-import { cvaMerge } from '@trackunit/css-class-variance-utilities';
+import { cva } from '@trackunit/css-class-variance-utilities';
 import { Tooltip, useMergeRefs, Icon, Spinner, Text, useMeasure, useContainerBreakpoints, useDebounce, useWatch, useKeyboardShortcut, IconButton, ToggleGroup as ToggleGroup$1, useIsFullscreen, Popover, PopoverTrigger, PopoverContent, MoreMenu, useHover as useHover$1, cvaInteractableItem, useLocalStorageReducer } from '@trackunit/react-components';
 import { twMerge } from 'tailwind-merge';
 import { useFloating, autoUpdate, offset, flip, useHover, safePolygon, useInteractions, shift, hide, useDismiss, useRole } from '@floating-ui/react';
@@ -1058,17 +1058,18 @@ const FallbackAnnotationContent = ({ store }) => {
     return (jsx("div", { className: "pointer-events-none col-start-1 row-start-1 self-end justify-self-start", children: jsx(AnnotationStack, { annotations: displayAnnotations, isExiting: isExiting }) }));
 };
 const DEBOUNCE_DELAY = 200;
-const cvaLoadingOverlay = cvaMerge([
-    "pointer-events-none",
-    "col-start-1",
-    "row-start-1",
-    "flex",
-    "items-start",
-    "justify-center",
-    "transition-[opacity,display]",
-    "duration-150",
-    "ease-in-out",
-], {
+const cvaLoadingOverlay = cva({
+    base: [
+        "pointer-events-none",
+        "col-start-1",
+        "row-start-1",
+        "flex",
+        "items-start",
+        "justify-center",
+        "transition-[opacity,display]",
+        "duration-150",
+        "ease-in-out",
+    ],
     variants: {
         visible: {
             true: ["opacity-100"],
@@ -1899,7 +1900,7 @@ const Custom = ({ config, overlaySide = undefined, resolved, placement }) => {
 };
 
 /** Shared padding for interactive menu items (button, toggle, stepper, select, radioGroup). */
-const cvaControlMenuItemBase = cvaMerge(["px-3", "py-2"]);
+const cvaControlMenuItemBase = cva({ base: ["px-3", "py-2"] });
 // ============================================================================
 // Cross-Cutting Middleware
 // ============================================================================
@@ -2696,21 +2697,22 @@ const ControlsInner = ({ api, controls, className }) => {
 // shallow equality is sufficient; no custom comparator needed.
 const Controls = memo(ControlsInner);
 
-const cvaMapPreview = cvaMerge([
-    "relative",
-    "h-[72px]",
-    "w-[72px]",
-    "overflow-clip",
-    "[--radius:theme(borderRadius.xl)]",
-    "[--border:2px]",
-    "rounded-[var(--radius)]",
-    "before:pointer-events-none",
-    "before:absolute",
-    "before:inset-0",
-    "before:z-10",
-    "before:rounded-[var(--radius)]",
-    "before:border-[length:var(--border)]",
-], {
+const cvaMapPreview = cva({
+    base: [
+        "relative",
+        "h-[72px]",
+        "w-[72px]",
+        "overflow-clip",
+        "[--radius:theme(borderRadius.xl)]",
+        "[--border:2px]",
+        "rounded-[var(--radius)]",
+        "before:pointer-events-none",
+        "before:absolute",
+        "before:inset-0",
+        "before:z-10",
+        "before:rounded-[var(--radius)]",
+        "before:border-[length:var(--border)]",
+    ],
     variants: {
         selected: {
             true: ["before:border-primary-500", "before:ring-2", "before:ring-inset", "before:ring-white"],
@@ -3979,19 +3981,21 @@ const resolveMarkerDomSize = (size, direction, form) => {
  * properties that need to animate, intentionally excluding `width` to prevent
  * non-composited layout thrashing. See `MarkerAnimatedSurface.tsx` for details.
  */
-const cvaMapMarker = cvaMerge([
-    "inline-flex",
-    "items-center",
-    "relative",
-    "overflow-hidden",
-    "select-none",
-    "cursor-pointer",
-    "rounded-full",
-    "outline-none",
-    "focus-visible:ring-2",
-    "focus-visible:ring-info-500",
-    "focus-visible:ring-offset-2",
-]);
+const cvaMapMarker = cva({
+    base: [
+        "inline-flex",
+        "items-center",
+        "relative",
+        "overflow-hidden",
+        "select-none",
+        "cursor-pointer",
+        "rounded-full",
+        "outline-none",
+        "focus-visible:ring-2",
+        "focus-visible:ring-info-500",
+        "focus-visible:ring-offset-2",
+    ],
+});
 /**
  * Label span inside pill markers.
  *
@@ -4004,19 +4008,14 @@ const cvaMapMarker = cvaMerge([
  * alone biases the text upward (extra space below). `overflow-x: clip` gives the
  * horizontal ellipsis without a vertical clip on the span itself.
  */
-const cvaPillLabel = cvaMerge([
-    "min-w-0",
-    "flex-1",
-    "overflow-x-clip",
-    "whitespace-nowrap",
-    "text-ellipsis",
-    "font-medium",
-    "leading-none",
-]);
+const cvaPillLabel = cva({
+    base: ["min-w-0", "flex-1", "overflow-x-clip", "whitespace-nowrap", "text-ellipsis", "font-medium", "leading-none"],
+});
 /**
  * Inner indicator disc: marker fill via `--marker-color`, border via CSS `color-mix` on that token (plan §5).
  */
-const cvaMarkerIndicator = cvaMerge(["rounded-full", "bg-[var(--marker-color)]", "flex", "items-center", "justify-center"], {
+const cvaMarkerIndicator = cva({
+    base: ["rounded-full", "bg-[var(--marker-color)]", "flex", "items-center", "justify-center"],
     variants: {
         size: {
             xs: ["h-2", "w-2"],
@@ -5578,6 +5577,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
 // ============================================================================
@@ -6402,20 +6497,21 @@ const extractSinglePartInfo = (geometry) => {
     }
 };
 
-const cvaShapeLabel = cvaMerge([
-    "select-none",
-    "inline-flex",
-    "items-center",
-    "gap-1",
-    "whitespace-nowrap",
-    "px-2",
-    "py-0.5",
-    "text-xs",
-    "font-medium",
-    "leading-tight",
-    "transition-opacity",
-    "duration-150",
-], {
+const cvaShapeLabel = cva({
+    base: [
+        "select-none",
+        "inline-flex",
+        "items-center",
+        "gap-1",
+        "whitespace-nowrap",
+        "px-2",
+        "py-0.5",
+        "text-xs",
+        "font-medium",
+        "leading-tight",
+        "transition-opacity",
+        "duration-150",
+    ],
     variants: {
         theme: {
             light: ["shadow-sm"],
@@ -6472,7 +6568,8 @@ const EDGE_LABEL_BORDER_RADIUS = {
         right: "3px 0 3px 3px",
     },
 };
-const cvaFitMode = cvaMerge([], {
+const cvaFitMode = cva({
+    base: [],
     variants: {
         fitMode: {
             fits: ["pointer-events-auto"],
@@ -12120,4 +12217,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.125",
+  "version": "0.2.127",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "2.12.0",
-    "@trackunit/css-class-variance-utilities": "1.14.28",
-    "@trackunit/react-form-components": "2.6.47",
-    "@trackunit/react-core-hooks": "1.21.40",
-    "@trackunit/geo-json-utils": "1.15.30",
-    "@trackunit/i18n-library-translation": "2.4.40",
+    "@trackunit/react-components": "2.13.1",
+    "@trackunit/css-class-variance-utilities": "2.0.0",
+    "@trackunit/react-form-components": "2.6.49",
+    "@trackunit/react-core-hooks": "1.21.42",
+    "@trackunit/geo-json-utils": "1.15.32",
+    "@trackunit/i18n-library-translation": "2.4.42",
     "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.113",
+    "@trackunit/react-map-color-utils": "0.0.93",
+    "@trackunit/ui-design-tokens": "1.15.20",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.39.10",
     "tailwind-merge": "^2.0.0",

package/src/controls/renderingRules.d.ts

@@ -1,7 +1,12 @@
 import type { AvailableSpace, Compactness, ControlConfig, MenuItemConfig, Placement, RenderContext, ResolvedControlProps, ResolvedControlPropsBase } from "./types";
 export type { AvailableSpace, Compactness, Placement, RenderContext, ResolvedControlProps, ResolvedControlPropsBase };
 /** Shared padding for interactive menu items (button, toggle, stepper, select, radioGroup). */
-export declare const cvaControlMenuItemBase: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const cvaControlMenuItemBase: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
 /** Context available to all middleware and resolvers */
 export type MiddlewareContext = Readonly<{
     renderContext: RenderContext;

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 {};

package/src/layers/useShapes/ShapeLabelPill.d.ts

@@ -9,9 +9,28 @@ type ShapeLabelPillProps = Readonly<{
     "data-testid"?: string;
     children: ReactNode;
 }>;
-export declare const cvaShapeLabel: (props?: ({
-    theme?: "light" | "dark" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const cvaShapeLabel: import("cva").CVAComponent<Omit<{
+    base: string[];
+    variants: {
+        theme: {
+            light: string[];
+            dark: string[];
+        };
+    };
+}, "defaultVariants"> & {
+    variants: {
+        theme: {
+            light: string[];
+            dark: string[];
+        };
+    };
+    defaultVariants: Omit<{}, never>;
+}, {
+    theme: {
+        light: string[];
+        dark: string[];
+    };
+}>;
 /**
  * Shared styled container for shape labels (edge labels and annotation labels).
  *

package/src/markers/shared/mapMarkerVariants.d.ts

@@ -12,7 +12,12 @@
  * properties that need to animate, intentionally excluding `width` to prevent
  * non-composited layout thrashing. See `MarkerAnimatedSurface.tsx` for details.
  */
-export declare const cvaMapMarker: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const cvaMapMarker: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
 /**
  * Label span inside pill markers.
  *
@@ -25,11 +30,62 @@ export declare const cvaMapMarker: (props?: import("class-variance-authority/typ
  * alone biases the text upward (extra space below). `overflow-x: clip` gives the
  * horizontal ellipsis without a vertical clip on the span itself.
  */
-export declare const cvaPillLabel: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+export declare const cvaPillLabel: import("cva").CVAComponent<Omit<{
+    base: string[];
+}, "defaultVariants"> & {
+    variants: unknown;
+    defaultVariants: Omit<{}, never>;
+}, unknown>;
 /**
  * Inner indicator disc: marker fill via `--marker-color`, border via CSS `color-mix` on that token (plan §5).
  */
-export declare const cvaMarkerIndicator: (props?: ({
-    size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
-    theme?: "light" | "dark" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const cvaMarkerIndicator: import("cva").CVAComponent<Omit<{
+    base: string[];
+    variants: {
+        size: {
+            xs: string[];
+            sm: string[];
+            md: string[];
+            lg: string[];
+            xl: string[];
+        };
+        theme: {
+            light: string[];
+            dark: string[];
+        };
+    };
+    defaultVariants: {
+        size: "md";
+        theme: "light";
+    };
+}, "defaultVariants"> & {
+    variants: {
+        size: {
+            xs: string[];
+            sm: string[];
+            md: string[];
+            lg: string[];
+            xl: string[];
+        };
+        theme: {
+            light: string[];
+            dark: string[];
+        };
+    };
+    defaultVariants: Omit<{}, "size" | "theme"> & {
+        size: "md";
+        theme: "light";
+    };
+}, {
+    size: {
+        xs: string[];
+        sm: string[];
+        md: string[];
+        lg: string[];
+        xl: string[];
+    };
+    theme: {
+        light: string[];
+        dark: string[];
+    };
+}>;

package/src/stories/_storyCoordUtils.d.ts

@@ -1,8 +1,57 @@
 /** Pads numeric string: 3-digit int part + reserved sign column to avoid layout shift when sign flips. */
 export declare const formatPaddedNumber: (n: number, decimals: number) => string;
-export declare const cvaCoordCell: (props?: ({
-    variant?: "lng" | "lat" | "we" | "sn" | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string;
-export declare const cvaStateDisplay: (props?: ({
-    expanded?: boolean | null | undefined;
-} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const cvaCoordCell: import("cva").CVAComponent<Omit<{
+    base: string[];
+    variants: {
+        variant: {
+            lng: string[];
+            lat: string[];
+            we: string[];
+            sn: string[];
+        };
+    };
+}, "defaultVariants"> & {
+    variants: {
+        variant: {
+            lng: string[];
+            lat: string[];
+            we: string[];
+            sn: string[];
+        };
+    };
+    defaultVariants: Omit<{}, never>;
+}, {
+    variant: {
+        lng: string[];
+        lat: string[];
+        we: string[];
+        sn: string[];
+    };
+}>;
+export declare const cvaStateDisplay: import("cva").CVAComponent<Omit<{
+    base: string[];
+    variants: {
+        expanded: {
+            true: string[];
+            false: string[];
+        };
+    };
+    defaultVariants: {
+        expanded: true;
+    };
+}, "defaultVariants"> & {
+    variants: {
+        expanded: {
+            true: string[];
+            false: string[];
+        };
+    };
+    defaultVariants: Omit<{}, "expanded"> & {
+        expanded: true;
+    };
+}, {
+    expanded: {
+        true: string[];
+        false: string[];
+    };
+}>;

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"]}