@mapvx/web-js 3.1.0 → 3.2.0-dev.1

package/dist/es/domain/models/mapConfig.d.ts

@@ -74,6 +74,94 @@ export declare const DEFAULT_TILE_CACHE_CONFIG: Required<MapTileCacheConfig>;
  * @internal
  */
 export declare const MAPLIBRE_MAX_TILE_CACHE_HARD_CAP = 100000;
+/**
+ * Configuration for automatic marker label collision avoidance.
+ *
+ * When enabled, a marker's text label (see `MarkerConfig.textPosition`) is
+ * treated as a preferred starting side rather than a fixed placement: the
+ * SDK checks it against neighboring markers' icons and labels, moves it to
+ * a free side (right/top/left/bottom) when its preferred side is occupied,
+ * and hides it entirely when no side is collision-free. The marker's icon
+ * itself never moves.
+ *
+ * @example
+ * ```typescript
+ * const markerLayoutConfig: MarkerLayoutConfig = {
+ *   enabled: true,
+ *   minZoomForLabels: 17,
+ *   gapPx: 8,
+ *   maxLabelWidthPx: 160,
+ * };
+ * ```
+ *
+ * @group Configuration
+ */
+export interface MarkerLayoutConfig {
+    /**
+     * Enable automatic label collision avoidance.
+     * When false, labels always render at their configured `textPosition`,
+     * exactly like before this feature existed.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Zoom level below which no label is rendered at all. Markers keep their
+     * icons; only the text is withheld.
+     *
+     * Motivated by dense maps: zoomed out, hundreds of pins share a few
+     * hundred pixels and nearly every label would be hidden by collision
+     * avoidance anyway, one at a time and in an order the caller cannot
+     * predict. A single threshold makes that state deliberate and uniform —
+     * pins only, then labels once the camera is close enough for them to fit.
+     *
+     * Evaluated continuously as the camera moves, so labels appear the moment
+     * the zoom crosses the threshold rather than when the gesture ends.
+     *
+     * Labels withheld by this threshold are not obstacles: they never occupy
+     * space for their neighbors, so nothing is displaced on their behalf.
+     *
+     * Requires `enabled: true`: `enabled: false` short-circuits the entire
+     * layout pass, so the threshold is never evaluated either.
+     *
+     * @default -Infinity (no threshold — labels are placed at every zoom)
+     */
+    minZoomForLabels?: number;
+    /**
+     * Horizontal gap, in pixels, between an icon and a label placed to its
+     * left or right. Drives both the collision math and the rendered offset
+     * (published as the `--mapvx-label-gap` CSS custom property).
+     * @default 8
+     */
+    gapPx?: number;
+    /**
+     * Vertical gap, in pixels, between an icon and a label placed above or
+     * below it. Drives both the collision math and the rendered offset
+     * (published as the `--mapvx-label-vertical-gap` CSS custom property).
+     * @default 4
+     */
+    verticalGapPx?: number;
+    /**
+     * Extra buffer, in pixels, added around every box when testing for
+     * collisions between a marker and its *neighbors*. Higher values leave
+     * more visual breathing room between labels/icons at the cost of hiding
+     * labels sooner under crowding. A label's distance from its own icon is
+     * set by `gapPx`/`verticalGapPx` alone and is unaffected by this.
+     * @default 4
+     */
+    paddingPx?: number;
+    /**
+     * Default maximum label width, in pixels, before truncation. Applied to
+     * every marker added through `addMarker`, and overridable per marker via
+     * `MarkerConfig.maxLabelWidthPx`.
+     * @default 200
+     */
+    maxLabelWidthPx?: number;
+}
+/**
+ * Default values for marker layout configuration
+ * @internal
+ */
+export declare const DEFAULT_MARKER_LAYOUT_CONFIG: Required<MarkerLayoutConfig>;
 /**
  * Basic configuration for the map.
  * Provides essential settings for initializing and customizing map behavior.
@@ -123,6 +211,7 @@ export declare const MAPLIBRE_MAX_TILE_CACHE_HARD_CAP = 100000;
  * @property authToken - (Optional) Authentication token for accessing protected map resources. Required for loading map related data from Portal.
  * @property apiUrl - (Optional) Injected by SDK when creating map; base API URL for map requests.
  * @property mapvxRequestContext - (Optional) Injected by SDK when creating map; context sent as headers to public-api.mapvx.com.
+ * @property markerLayout - (Optional) Automatic marker label collision avoidance configuration.
  */
 export interface MapConfig {
     /**
@@ -350,6 +439,13 @@ export interface MapConfig {
      * @see {@link MapTileCacheConfig} for available options
      */
     tileCache?: MapTileCacheConfig;
+    /**
+     * Automatic marker label collision avoidance configuration.
+     * Controls how marker text labels move or hide to avoid overlapping
+     * neighboring markers.
+     * @see {@link MarkerLayoutConfig} for available options
+     */
+    markerLayout?: MarkerLayoutConfig;
     /**
      * Mode of the map.
      * Controls the mode of the map.

package/dist/es/domain/models/mapConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapConfig.d.ts","sourceRoot":"","sources":["../../../../src/domain/models/mapConfig.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mapConfig.d.ts","sourceRoot":"","sources":["../../../../src/domain/models/mapConfig.ts"],"names":[],"mappings":"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"}

package/dist/es/domain/models/mapConfig.js

@@ -1,3 +1,4 @@
+import { DEFAULT_MAX_LABEL_WIDTH_PX } from "./marker";
 /**
  * Default values for tile cache configuration
  * @internal
@@ -18,4 +19,16 @@ export const DEFAULT_TILE_CACHE_CONFIG = {
  * @internal
  */
 export const MAPLIBRE_MAX_TILE_CACHE_HARD_CAP = 100000;
+/**
+ * Default values for marker layout configuration
+ * @internal
+ */
+export const DEFAULT_MARKER_LAYOUT_CONFIG = {
+    enabled: true,
+    minZoomForLabels: Number.NEGATIVE_INFINITY,
+    gapPx: 8,
+    verticalGapPx: 4,
+    paddingPx: 4,
+    maxLabelWidthPx: DEFAULT_MAX_LABEL_WIDTH_PX,
+};
 //# sourceMappingURL=mapConfig.js.map

package/dist/es/domain/models/mapConfig.js.map

@@ -1 +1 @@
-{"version":3,"file":"mapConfig.js","sourceRoot":"","sources":["../../../../src/domain/models/mapConfig.ts"],"names":[],"mappings":"AAsEA;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAiC;IACrE,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE,GAAG;IACb,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,aAAa;IACpC,sBAAsB,EAAE,IAAI;IAC5B,oBAAoB,EAAE,KAAK;IAC3B,wBAAwB,EAAE,CAAC;CAC5B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,MAAO,CAAA"}
+{"version":3,"file":"mapConfig.js","sourceRoot":"","sources":["../../../../src/domain/models/mapConfig.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAA;AAqErD;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAiC;IACrE,OAAO,EAAE,IAAI;IACb,QAAQ,EAAE,GAAG;IACb,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,aAAa;IACpC,sBAAsB,EAAE,IAAI;IAC5B,oBAAoB,EAAE,KAAK;IAC3B,wBAAwB,EAAE,CAAC;CAC5B,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,MAAO,CAAA;AA2FvD;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAiC;IACxE,OAAO,EAAE,IAAI;IACb,gBAAgB,EAAE,MAAM,CAAC,iBAAiB;IAC1C,KAAK,EAAE,CAAC;IACR,aAAa,EAAE,CAAC;IAChB,SAAS,EAAE,CAAC;IACZ,eAAe,EAAE,0BAA0B;CAC5C,CAAA"}

package/dist/es/domain/models/marker.d.ts

@@ -25,6 +25,20 @@ export declare enum TextPosition {
     /** Text positioned below the icon */
     bottom = 3
 }
+/**
+ * Fallback icon width/height, in pixels, used whenever a marker is created
+ * without explicit `iconProperties`.
+ *
+ * @group Markers
+ */
+export declare const DEFAULT_ICON_SIZE_PX = 40;
+/**
+ * Fallback maximum label width, in pixels, used whenever neither the marker
+ * nor the map's `markerLayout` configuration specifies one.
+ *
+ * @group Markers
+ */
+export declare const DEFAULT_MAX_LABEL_WIDTH_PX = 200;
 /**
  * Alignment options for marker rotation and pitch behavior.
  * Controls how the marker responds to map rotation and pitch changes.
@@ -69,10 +83,33 @@ export interface MarkerConfig {
      */
     floorId?: string;
     /**
-     * The position of the marker's text relative to its container.
+     * The preferred position of the marker's text relative to its icon.
+     *
+     * This is a starting preference, not a guaranteed final placement: when
+     * automatic label collision avoidance is enabled (see `markerLayout` on
+     * `MapConfig`), the SDK may move the label to a different side (or hide it)
+     * to avoid overlapping a neighboring marker's icon or label.
      * @see {@link TextPosition} for available positioning options
      */
     textPosition?: TextPosition;
+    /**
+     * Maximum width, in pixels, of the marker's text label before it is
+     * truncated with an ellipsis. Also used as the label's footprint when
+     * computing automatic collision avoidance, so the visual cap and the
+     * layout math always agree.
+     *
+     * Defaults to the map-level `markerLayout.maxLabelWidthPx`, which itself
+     * defaults to {@link DEFAULT_MAX_LABEL_WIDTH_PX}.
+     */
+    maxLabelWidthPx?: number;
+    /**
+     * Priority used to resolve label collisions: when two markers' labels
+     * would overlap, the one with the higher `labelPriority` keeps its
+     * preferred position (or any non-colliding position) first, and the other
+     * is displaced or hidden. Ties are broken by the order markers were added.
+     * @defaultValue 0
+     */
+    labelPriority?: number;
     /**
      * The icon element to be displayed within the marker.
      * Can be either a URL string or an HTML element.
@@ -97,6 +134,11 @@ export interface MarkerConfig {
     /**
      * The HTML element associated with the marker.
      * If provided, this element will be used instead of the icon and text properties.
+     *
+     * Pair it with `iconProperties` when the element's footprint is known:
+     * that pins the marker's own box (and therefore its anchor point) instead
+     * of letting the element size it, and gives automatic label collision
+     * avoidance an exact rect to work with.
      */
     element?: HTMLElement;
     /**
@@ -185,6 +227,114 @@ export interface TextProperties {
      */
     textShadow?: string;
 }
+/**
+ * Utility class for creating and manipulating marker elements on a map.
+ * Provides static methods for marker element creation and styling.
+ */
+export declare class MarkerUtils {
+    /**
+     * Creates a container element for the marker and adds the icon and text
+     * according to the properties specified in the `MarkerConfig` object.
+     *
+     * @param marker - `MarkerConfig` object containing the marker configuration
+     * @returns Marker container element ready to be added to the map
+     *
+     * @example
+     * ```typescript
+     * const markerElement = MarkerUtils.createMarkerElement(markerConfig);
+     * map.addLayer(markerElement);
+     * ```
+     */
+    static createMarkerElement(marker: MarkerConfig): HTMLElement;
+    /**
+     * Appends the marker's text label (if any) to the container, positioned
+     * around whichever element (icon or custom `element`) is already there.
+     *
+     * @param markerConfig - Configuration object containing text properties
+     * @param container - Container element to append the label to
+     * @returns The same container, with the label appended when text is present
+     */
+    private static setAndCreateText;
+    /**
+     * Creates an icon element with proper styling.
+     *
+     * @param marker - Marker configuration
+     * @param iconWidth - Width of the icon
+     * @param iconHeight - Height of the icon
+     * @returns Icon element ready to be added to the container
+     */
+    private static createIconElement;
+    /**
+     * Creates a text container, absolutely positioned around the marker's icon
+     * via CSS (see `.text-container` in styles.css), so the label never affects
+     * the container's own box.
+     *
+     * @param textElement - The text element to contain
+     * @param textPosition - Desired position relative to the icon
+     * @param maxLabelWidthPx - Maximum label width in pixels before truncation
+     * @returns Container with text positioned using CSS classes
+     */
+    private static createTextContainer;
+    /**
+     * Resolves an optional {@link TextPosition} to its default (`right`), the
+     * same default `createTextContainer` has always applied.
+     */
+    static resolveTextPosition(textPosition?: TextPosition): TextPosition;
+    /**
+     * Swaps a text container's position class, keeping exactly one of
+     * `top|bottom|left|right` applied at a time.
+     */
+    private static setTextPositionClass;
+    /**
+     * Repositions (or hides) a marker's already-rendered text label at
+     * runtime, without rebuilding any DOM. Used both by automatic collision
+     * avoidance and by anything else that needs to move a label after
+     * creation.
+     *
+     * @param textContainer - The `.text-container` element to reposition
+     * @param position - Side of the icon the label should render on
+     * @param hidden - Whether the label should be hidden (kept measurable via
+     *   `visibility`, never removed via `display`, so it can be measured again
+     *   to decide whether it fits once something else changes)
+     *
+     * @example
+     * ```typescript
+     * MarkerUtils.applyTextPosition(textEl, TextPosition.left, false);
+     * ```
+     */
+    static applyTextPosition(textContainer: HTMLElement, position: TextPosition, hidden: boolean): void;
+    /**
+     * Creates and returns an icon element for the marker, using the image URL
+     * specified in the `MarkerConfig` object.
+     *
+     * @param marker - `MarkerConfig` object containing the marker configuration
+     * @returns Marker icon element with proper styling and dimensions
+     *
+     * @example
+     * ```typescript
+     * const iconElement = MarkerUtils.createIcon(markerConfig);
+     * container.appendChild(iconElement);
+     * ```
+     */
+    static createIcon(marker: MarkerConfig): HTMLElement;
+    /**
+     * Creates and returns a text element for the marker container, applying
+     * custom text styles if provided in the marker properties.
+     *
+     * @param text - Text content to display
+     * @param properties - Optional text styling properties
+     * @returns Text element with applied styles
+     *
+     * @example
+     * ```typescript
+     * const textElement = MarkerUtils.createTextElement("Coffee Shop", {
+     *   fontSize: "14px",
+     *   color: "#333333"
+     * });
+     * ```
+     */
+    private static createTextElement;
+}
 /**
  * Custom implementation of a MapLibre Marker with additional functionality.
  * Extends the base MapLibre Marker class with MapVX-specific features.
@@ -215,6 +365,59 @@ export declare class MarkerAttribute extends Marker {
      * Used for indoor navigation and floor-specific marker management.
      */
     floorId?: string;
+    /**
+     * Resolved icon dimensions (defaults to {@link DEFAULT_ICON_SIZE_PX} square
+     * when unspecified), matching whatever `MarkerUtils.createMarkerElement`
+     * rendered. Used by automatic label collision avoidance to compute the
+     * icon's on-screen rect without a DOM measurement — except when
+     * {@link measureIconFromDom} is set.
+     * @internal
+     */
+    iconSize: {
+        width: number;
+        height: number;
+    };
+    /**
+     * The `PositionAnchor` this marker was created with, needed by automatic
+     * label collision avoidance to translate a screen point into the icon's
+     * on-screen rect the same way MapLibre itself does.
+     * @internal
+     */
+    anchorType: PositionAnchor;
+    /**
+     * The marker's preferred text position, used as the first candidate by
+     * automatic label collision avoidance before it tries the other sides.
+     * @internal
+     */
+    preferredTextPosition: TextPosition;
+    /**
+     * Priority used to resolve label collisions; see
+     * {@link MarkerConfig.labelPriority}.
+     * @internal
+     */
+    labelPriority: number;
+    /**
+     * Cached reference to this marker's `.text-container` element, if it has
+     * a text label. Avoids querying the DOM on every layout pass.
+     * @internal
+     */
+    textContainerEl?: HTMLElement;
+    /**
+     * True when the marker renders a caller-supplied `element` and no
+     * `iconProperties` declared its footprint. In that case {@link iconSize}
+     * is only a fallback and automatic label collision avoidance measures the
+     * marker element's real box from the DOM instead.
+     * @internal
+     */
+    measureIconFromDom: boolean;
+    /**
+     * The config this marker currently renders from. {@link updateIcon} merges
+     * its (usually partial) config on top of this one, so an update that omits
+     * `iconProperties`, `textPosition` or `labelPriority` keeps whatever the
+     * marker already had instead of silently snapping back to the SDK defaults
+     * — both in the DOM it rebuilds and in the layout state derived from it.
+     */
+    private currentConfig;
     /**
      * Constructs a new `MarkerAttribute` object with the specified properties.
      *
@@ -231,6 +434,29 @@ export declare class MarkerAttribute extends Marker {
      * ```
      */
     constructor(markerConfig: MarkerConfig);
+    /**
+     * Derives the state automatic label collision avoidance reads (icon box,
+     * preferred label side, priority, label element) from a fully-resolved
+     * config. It is what assigns the fields declared with `!` above — the
+     * constructor always calls it, but TypeScript can't see through the
+     * indirection. Shared by the constructor and {@link updateIcon} so the two can
+     * never drift apart.
+     */
+    private applyLayoutState;
+    /**
+     * Merges an update on top of the marker's current config, so a partial
+     * update such as `{ id, coordinate, icon }` keeps the marker's existing
+     * icon dimensions, label side and priority.
+     *
+     * `element` is deliberately *not* carried forward: it and `icon` are
+     * mutually exclusive rendering paths, and `updateIcon` has always chosen
+     * the path named by the update itself.
+     */
+    private mergeConfig;
+    /**
+     * Finds this marker's `.text-container` child element, if it has one.
+     */
+    private findTextContainerEl;
     /**
      * Adds the marker attribute to the specified map.
      *
@@ -246,6 +472,11 @@ export declare class MarkerAttribute extends Marker {
     /**
      * Updates the icon of the marker attribute based on the specified marker configuration.
      *
+     * The config is merged on top of the one the marker currently renders
+     * from, so a partial update keeps every property it omits — passing only
+     * `{ icon }` no longer resets the marker's icon dimensions, preferred
+     * label side or label priority to their defaults.
+     *
      * @param marker - `MarkerConfig` object containing the new marker configuration
      *
      * @example

package/dist/es/domain/models/marker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../../../src/domain/models/marker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../../../src/domain/models/marker.ts"],"names":[],"mappings":"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"}