@maptiler/sdk 4.2.0-rc.1 → 5.0.0-beta.m-r.1

package/dist/Marker/MarkerManager.d.ts

@@ -0,0 +1,137 @@
+import { Marker } from './Marker';
+import { Map as SDKMap } from '../Map';
+import { MarkerCollisionGroups, MarkerCollisionOptions } from './types';
+/**
+ * @class MarkerManagerImpl
+ * @description This singleton is used to batch marker updates and flush them to the DOM in a
+ * single animation frame to avoid multiple separate attribute writes
+ * It is not exposed as a public API and only used internally in the `Map` and `Marker` classes.
+ * It _may_ be used by multiple Maps.
+ */
+declare class MarkerManagerImpl {
+    private readonly dirty;
+    private animationFrameID;
+    private readonly markerMap;
+    private readonly mapIndex;
+    private readonly lastStyleId;
+    private readonly collisionState;
+    private readonly collisionPending;
+    private readonly dragEndHandlers;
+    private readonly altitudeState;
+    private altitudeLayerSequence;
+    private scheduleFlush;
+    private getOrCreateIndex;
+    private refreshAdaptiveColors;
+    register(marker: Marker, map: SDKMap): void;
+    deregister(marker: Marker, options?: {
+        deferDetach?: boolean;
+    }): void;
+    deregisterById(map: SDKMap, id: string): void;
+    deregisterAll(map: SDKMap, ids?: string[]): void;
+    getMap(marker: Marker): SDKMap | undefined;
+    /**
+     * Returns the id of the map's current style (e.g. `"streets-v4-dark"`), or
+     * `undefined` when it cannot be determined (custom style spec / URL).
+     * Falls back to the raw stylesheet's `id` field, since the id is not part
+     * of the serialized `StyleSpecification` returned by `map.getStyle()`.
+     */
+    getMapStyleId(map: SDKMap): string | undefined;
+    getMarkers(map: SDKMap): Marker[];
+    getMarker(map: SDKMap, id: string): Marker | undefined;
+    flushUpdates(): void;
+    addMarkerUpdateToQueue(marker: Marker): void;
+    cancelCuedUpdatesForMarker(marker: Marker): void;
+    /**
+     * Requests a full collision detection pass for a map's markers.
+     *
+     * The single entry point for everything that can change collisions —
+     * marker add / remove / move / drag, footprint changes, and camera
+     * `moveend`. Requests coalesce onto one animation frame, so a bulk add
+     * runs the pass once. During camera movement markers track their positions
+     * via MapLibre's own per-frame update; the pass itself only runs when
+     * movement settles (dense fields make it quadratic in overlapping pairs).
+     */
+    invalidateCollisions(map: SDKMap): void;
+    /**
+     * Collision groups from the latest detection pass: the full sets of
+     * mutually-colliding markers, with no priority or winner/loser resolution.
+     * The behaviour layer consumes these to decide what to do about collisions.
+     */
+    getCollisionGroups(map: SDKMap): MarkerCollisionGroups;
+    /**
+     * Configures collision detection for a map.
+     * @param options.proximityPadding - Distance in CSS px within which two
+     *   markers count as "in proximity". Overlap always uses 0.
+     * @param options.accuracy - `high` (default) tests rotated markers with
+     *   their actual rotated box; `low` uses the enclosing upright box, which
+     *   is cheaper but over-reports collisions for rotated markers.
+     * @param options.behaviour - Default collision behaviour for every marker
+     *   on the map; a marker's own `collisionBehaviour` option overrides it.
+     *   Defaults to `always-show`.
+     * @param options.transitionDuration - Duration in ms of the hide/show/minimize fade. Defaults to `150`.
+     * @param options.transitionEasing - CSS easing function for the fade. Defaults to `"ease"`.
+     */
+    setCollisionOptions(map: SDKMap, options: MarkerCollisionOptions): void;
+    /** Returns the fade-transition duration (ms) configured for `map`, or the SDK default if never configured. */
+    getCollisionTransitionDuration(map: SDKMap): number;
+    private applyCollisionTransitionVars;
+    private getOrCreateCollisionState;
+    /**
+     * The full detection pass. Builds each marker's screen box from its stored
+     * footprint and projected position (no DOM reads), finds intersecting
+     * pairs, derives collision groups, then diffs against the previous pass so
+     * markers only emit enter/exit transitions.
+     *
+     * Markers outside the (margin-padded) viewport never enter the pass: they
+     * are hidden outright — off screen there is nothing to show, and skipping
+     * them keeps the pair scan and placement proportional to what is actually
+     * visible. They rejoin (and fade back in) on the first pass that finds
+     * them near the viewport again. Consequence: collision events and
+     * `getCollisionGroups` only cover on-screen markers.
+     */
+    private runCollisionPass;
+    /**
+     * The behaviour layer: turns the pass's geometry into display states via
+     * greedy priority placement — `hide-by-priority` losers hide (and stop
+     * blocking), `minimize-by-priority` losers minimize (and keep reserving
+     * their full-size box, so priority order is strict). See
+     * {@link resolveDisplayStates}.
+     *
+     * Hide/minimize act on *overlap* only — the proximity padding stays an
+     * events-only concern; `collisionRadius` is the per-marker way to act at a
+     * distance.
+     */
+    private applyCollisionBehaviours;
+    /** Resolves a marker's collision behaviour against the map default. */
+    private effectiveBehaviour;
+    private getOrCreateCollisionSet;
+    private linkCollision;
+    /** Allocation-free set equality — dense passes must not allocate for unchanged collisions. */
+    private collisionSetsEqual;
+    private emitCollisionDiffs;
+    /**
+     * Starts driving `marker`'s per-frame altitude projection on `map`. Shared
+     * across every altitude-active marker on the map — several markers here
+     * still cost one no-op custom layer and one `render` listener, not one
+     * each. Called by {@link Marker.setAltitude} (and by {@link register} for
+     * a marker whose altitude was set before it had a map).
+     */
+    registerAltitudeParticipant(marker: Marker, map: SDKMap): void;
+    /** Stops driving `marker`'s altitude projection. Tears down the shared layer/listener once the last participant on `map` leaves. */
+    deregisterAltitudeParticipant(marker: Marker, map: SDKMap): void;
+    /**
+     * The shared, always-behind-markers container every marker's ground-line
+     * element gets appended to on this map — a sibling of the marker elements
+     * (both live in `map.getCanvasContainer()`), not a descendant of any one
+     * marker, so a long line can never inherit a marker's camera-depth
+     * z-index and paint over some *other* marker's icon. Created together
+     * with the rest of the per-map altitude state.
+     */
+    getGroundLineContainer(map: SDKMap): HTMLDivElement;
+    private getOrCreateAltitudeState;
+    private ensureAltitudeLayerInstalled;
+    private installAltitudeLayer;
+    private teardownAltitudeLayer;
+}
+export declare const MarkerManager: MarkerManagerImpl;
+export {};

package/dist/Marker/altitude-math.d.ts

@@ -0,0 +1,24 @@
+import { CustomLayerProjectionData, LngLat, Map as MLMap } from 'maplibre-gl';
+import { AltitudeReference } from './types';
+/** A screen-space position in CSS pixels, DOM convention (+y down). */
+export interface ScreenPoint {
+    x: number;
+    y: number;
+    /** Clip-space W — proportional to camera distance. For ordering points against each other, not a real distance. */
+    depth: number;
+}
+/**
+ * Projects `lngLat`/`altitudeMeters` to a screen point using the projection data MapLibre hands to custom layers each frame.
+ * A JS port of MapLibre's `projectTileFor3D` shader function, so it works under mercator, globe, and mid-morph between the two.
+ */
+export declare function projectLngLatAltitude(lngLat: LngLat, altitudeMeters: number, projectionData: CustomLayerProjectionData, map: MLMap): ScreenPoint | null;
+/**
+ * `groundBase` — MapLibre's own native marker position (terrain height, or 0 without terrain).
+ * `elevated` — the target: `nativeElevation + altitudeMeters` under `"ground"`, or plain `altitudeMeters` under `"sea"`.
+ * `belowGround` — `elevated` under `groundBase`, for fading markers DOM can't depth-test against terrain.
+ */
+export declare function computeAltitudeProjection(lngLat: LngLat, altitudeMeters: number, projectionData: CustomLayerProjectionData, map: MLMap, relativeTo: AltitudeReference): {
+    groundBase: ScreenPoint;
+    elevated: ScreenPoint;
+    belowGround: boolean;
+} | null;

package/dist/Marker/collision-helpers.d.ts

@@ -0,0 +1,160 @@
+import { MarkerOptions } from 'maplibre-gl';
+import { MarkerCollisionDisplayState } from './types';
+/**
+ * Pure geometry and grouping helpers for marker collision detection.
+ *
+ */
+/** Screen-space axis-aligned bounding box, in CSS pixels (+y down). */
+export type Bounds = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+/** A point in screen space from top left in px. */
+export type ScreenPoint = {
+    x: number;
+    y: number;
+};
+/**
+ * Screen-space oriented bounding box: the marker's actual rotated rectangle.
+ * `cos`/`sin` are precomputed from the rotation angle so both the SAT test
+ * and the enclosing-AABB derivation reuse them.
+ */
+export type OBB = {
+    /** Box center, screen px. */
+    cx: number;
+    cy: number;
+    /** Half extents along the box's own axes, px. */
+    hw: number;
+    hh: number;
+    /** Rotation of the box's axes (cos/sin of the angle). */
+    cos: number;
+    sin: number;
+};
+/**
+ * A marker's screen footprint, resolved from its props once per pass —
+ * never measured from the DOM inside the pass. (.getBoundingClientRect triggers layout)
+ */
+export type MarkerFootprint = {
+    /** Rendered width in CSS px, with 2-D scale applied. */
+    width: number;
+    /** Rendered height in CSS px, with 2-D scale applied. */
+    height: number;
+    /** Which point of the element sits on the marker's screen position. */
+    anchor: NonNullable<MarkerOptions["anchor"]>;
+    /** Screen-space pixel offset applied after projection (+y down). */
+    offset: [number, number];
+    /**
+     * Displacement from the element center to the rotation origin, in CSS px
+     * (+y down). Mirrors the inner wrapper's CSS `transform-origin`: `[0, 0]`
+     * for center-origin elements, `[0, height / 2]` for bottom-anchored shapes
+     * that rotate around their tip.
+     */
+    pivot: [number, number];
+    /** The marker's own rotation in degrees (its inner-shell CSS rotation). */
+    rotation: number;
+    /** `true` when the marker rotates with the map bearing (`rotationAlignment: "map"`). */
+    mapAligned: boolean;
+};
+/**
+ * Computes the screen-space oriented box of a marker.
+ *
+ * The box is rotated by `angleDeg` (map bearing for map-aligned markers plus
+ * the marker's own rotation). For unrotated (viewport-aligned) markers the
+ * rotation terms collapse to the plain box. Pitch is deliberately ignored —
+ * under pitch the true footprint foreshortens, so the full-height box
+ * over-reserves space, which fails safe.
+ *
+ * @param position - The marker's *screen* position (normally
+ *   `map.project(lngLat)`). Taken as an explicit argument so behaviours that
+ *   render a marker somewhere other than its geographic position can pass
+ *   the rendered point instead.
+ * @param footprint - The marker's resolved footprint.
+ * @param angleDeg - Total clockwise rotation of the box in degrees.
+ */
+export declare function computeMarkerOBB(position: ScreenPoint, footprint: MarkerFootprint, angleDeg: number): OBB;
+/**
+ * Returns the axis-aligned box enclosing an oriented box, inflated by
+ * `padding` on every side. Used as the broad-phase box: it can only
+ * over-include, never miss a real intersection.
+ */
+export declare function obbToAABB(obb: OBB, padding?: number): Bounds;
+/**
+ * Exact intersection test for two oriented boxes via the separating axis
+ * theorem: two convex boxes are disjoint if some axis of either box
+ * separates their projections, so only the four box axes need testing.
+ *
+ * SAT is the computational form of Minkowski-difference collision detection
+ * for convex polytopes — see
+ * https://en.wikipedia.org/wiki/Minkowski_addition#Collision_detection
+ *
+ * @param padding - Inflates both boxes' half extents; the two-box test then
+ *   answers "are the exact boxes within `2 * padding` of each other" the same
+ *   way the pre-inflated AABBs do for the axis-aligned path.
+ */
+export declare function obbIntersect(a: OBB, b: OBB, padding?: number): boolean;
+/** Returns `bounds` grown by `padding` px on every side. */
+export declare function inflateBounds(bounds: Bounds, padding: number): Bounds;
+/** The single intersection test — overlap and proximity both go through here. */
+export declare function boundsIntersect(a: Bounds, b: Bounds): boolean;
+/** Answers "which entries are near this box" for the detection pass. */
+export type CollisionCandidateSource<T> = {
+    query(bounds: Bounds): readonly T[];
+};
+/**
+ * The seam between the pairwise scan and the grouping/event logic.
+ *
+ * Currently a linear scan (O(n) per query, O(n²) per pass). When marker
+ * counts demand it, replace the internals with a spatial index (rbush /
+ * uniform grid) — callers only depend on `query`.
+ */
+export declare function createCandidateSource<T>(items: readonly T[], boundsOf: (item: T) => Bounds): CollisionCandidateSource<T>;
+/**
+ * How a marker participates in the greedy priority resolution.
+ * - `always` — always shown, but still reserves its space (blocks losers).
+ * - `hide` — hidden when it collides with an already-placed marker; frees
+ *   its space.
+ * - `minimize` — minimized when it collides with an already-placed marker;
+ *   still reserves its *full-size* box (renders small, blocks full), so
+ *   priority order is strict: a lower-priority marker can never show
+ *   full-size in space a minimized higher-priority marker occupies.
+ */
+export type ResolutionMode = "always" | "hide" | "minimize";
+/** One marker's input to {@link resolveDisplayStates}. */
+export type ResolutionEntry = {
+    mode: ResolutionMode;
+    /** Numeric priority; higher wins. */
+    priority: number;
+    /** Full-size box at the marker's rendered position. */
+    obb: OBB;
+};
+/**
+ * Greedy priority placement — the winner/loser resolution behind the
+ * hide/minimize collision behaviours.
+ *
+ * Entries are placed in priority order (ties: input order, i.e. registration
+ * order). Each entry is tested only against already-placed boxes; hidden
+ * markers free their space for lower-priority ones, while `always` and
+ * minimized markers keep reserving their full box. Rerunning on the same
+ * input always yields the same output — placement never feeds back into the
+ * boxes it is tested against, so results cannot oscillate between passes.
+ *
+ * @param entries - One entry per marker still in contention, in registration order.
+ * @param exact - `true` tests the rotated boxes (SAT), `false` their enclosing
+ *   upright boxes — mirrors the detection pass's `accuracy` setting.
+ * @returns Display state per entry, indexed like `entries`.
+ */
+export declare function resolveDisplayStates(entries: readonly ResolutionEntry[], exact?: boolean): MarkerCollisionDisplayState[];
+/**
+ * Derives collision groups (connected components) from pairwise collisions.
+ *
+ * Groups keep the *full set* of mutually-colliding items — no winners or
+ * losers — so consumers can inspect full collision sets rather than only
+ * the greedy placement outcome.
+ *
+ * @param items - All entries in the pass, indexable by the pair indices.
+ * @param pairs - Colliding index pairs `[i, j]`.
+ * @returns Components with two or more members; singletons are not groups.
+ */
+export declare function deriveCollisionGroups<T>(items: readonly T[], pairs: readonly [number, number][]): T[][];

package/dist/Marker/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Marker';
+export * from './types';

package/dist/Marker/marker-adaptive-colors.d.ts

@@ -0,0 +1,35 @@
+import { defaultReferenceStyleMap } from '@maptiler/client';
+/**
+ * Unversioned reference-style key, matching the reference styles of
+ * `MapStyle` from `@maptiler/client` (e.g. `MapStyle.STREETS` → `"streets"`).
+ */
+export type ReferenceStyleKey = Lowercase<keyof typeof defaultReferenceStyleMap>;
+/**
+ * Style key the marker colours can target: an unversioned reference-style id,
+ * optionally with a variant suffix (e.g. `"streets"`, `"streets-dark"`).
+ * Versioned style ids (`"streets-v4-dark"`) are normalised to this form by
+ * {@link getAdaptiveColors}.
+ */
+export type AdaptiveStyleKey = ReferenceStyleKey | `${ReferenceStyleKey}-${string}`;
+/** The colours of each marker part for one map style. */
+export type AdaptiveColorSet = {
+    /** Fill of the inner area. */
+    innerColor: string;
+    /** Fill of the outer body / border. */
+    outerColor: string;
+    /** Colour of the content (text, glyph). */
+    contentColor: string;
+    /** Stroke of the outline (only visible when an outline width is set). */
+    outlineColor: string;
+};
+/**
+ * Resolves the default marker colours for a given map style and shape.
+ *
+ * Lookup order: exact style key (version stripped, variant kept) → reference
+ * style without variant → `base`, so an unknown style id resolves to `base`.
+ * Shapes in {@link INVERTED_COLOR_SHAPES} get the style's colours swapped: the
+ * accent colour on the body and the mark, the body colour on the inner fill.
+ * @param styleId - Style id, versioned (`"streets-v4-dark"`) or not (`"streets-dark"`).
+ * @param shape - Marker shape key; omit for the colours of an ordinary shape.
+ */
+export declare function getAdaptiveColors(styleId: string, shape?: string): AdaptiveColorSet;

package/dist/Marker/marker-animation-presets.d.ts

@@ -0,0 +1,60 @@
+import { EasingFunctionName } from '../MaptilerAnimation/types';
+import { EnterAnimationPreset, ExitAnimationPreset, IdleAnimationPreset, Vector2 } from './types';
+/**
+ * An `enter`/`exit` preset's animated state at one end of its motion:
+ * opacity, 2-D scale, and a vertical `lift` offset in CSS px (used by
+ * `enter`'s `drop`/`bounce`; `0` elsewhere).
+ */
+export type LifecycleAnimationValue = {
+    opacity: number;
+    scale: Vector2;
+    lift: number;
+};
+/**
+ * The "hidden" end of `preset`'s `enter` animation — the value a marker
+ * eases from. `baseOpacity`/`baseScale` are the marker's own configured
+ * values, i.e. the "shown" end shared by every preset.
+ */
+export declare function enterPresetHiddenValue(preset: EnterAnimationPreset, baseOpacity: number, baseScale: Vector2): LifecycleAnimationValue;
+/**
+ * The "hidden" end of `preset`'s `exit` animation — the value a marker
+ * eases to. `baseOpacity`/`baseScale` are the marker's own configured
+ * values, i.e. the "shown" end shared by every preset.
+ */
+export declare function exitPresetHiddenValue(preset: ExitAnimationPreset, baseOpacity: number, baseScale: Vector2): LifecycleAnimationValue;
+/**
+ * Scales a preset's `hidden` value by `magnitude` — `1` (the default) is the
+ * full designed motion (`hidden` as-is), `0` is no motion at all (`shown`),
+ * values beyond `1` extrapolate past `hidden`.
+ */
+export declare function scaleLifecycleMagnitude(shown: LifecycleAnimationValue, hidden: LifecycleAnimationValue, magnitude: number): LifecycleAnimationValue;
+/**
+ * Which marker channel an idle preset animates. `value` at a keyframe
+ * multiplies the marker's base value for `scale`/`opacity` (rest = `1`), or
+ * is added to it for `rotation`/`lift` (rest = `0`).
+ */
+export type IdleAnimationChannel = "scale" | "opacity" | "rotation" | "lift";
+/**
+ * Scales an idle keyframe's `value` by `magnitude` around its channel's rest
+ * value (`1` for `scale`/`opacity`, `0` for `rotation`/`lift`) — `1` (the
+ * default) is the full designed motion, `0` is no motion at all (rest).
+ */
+export declare function scaleIdleMagnitude(channel: IdleAnimationChannel, value: number, magnitude: number): number;
+/** One control point in an idle preset's per-iteration curve. */
+export type IdleAnimationKeyframe = {
+    /** Position within one loop iteration, `0`–`1`. */
+    delta: number;
+    /** Channel value at this point — see {@link IdleAnimationChannel}. */
+    value: number;
+    /** Easing from the previous keyframe to this one. Defaults to `"Linear"`. */
+    easing?: EasingFunctionName;
+};
+export type IdlePresetConfig = {
+    channel: IdleAnimationChannel;
+    /**
+     * Always starts and ends at rest (`delta` `0` and `1`); every preset's
+     * animated motion is centered on `delta` `0.5`.
+     */
+    keyframes: IdleAnimationKeyframe[];
+};
+export declare const IDLE_PRESET_CONFIG: Record<IdleAnimationPreset, IdlePresetConfig>;

package/dist/Marker/marker-constants.d.ts

@@ -0,0 +1,111 @@
+import { MarkerOptions } from 'maplibre-gl';
+import { EasingFunctionName } from '../MaptilerAnimation/types';
+import { EnterAnimationPreset, ExitAnimationPreset, IdleAnimationPreset, MapTilerMarkerUIStateName, MapTilerMarkerShape, MapTilerMarkerSize, MapTilerMarkerShadow } from './types';
+import { AdaptiveColorSet, AdaptiveStyleKey } from './marker-adaptive-colors';
+import { ContentMetrics, ShapeSize } from './marker-svg-config';
+export declare const DEFAULT_SHAPE: MapTilerMarkerShape;
+export declare const DEFAULT_SIZE: MapTilerMarkerSize;
+/** Shadow used when `shadow` isn't set — per size, as in the design (L strong, M medium, S and the xs dot soft). */
+export declare const DEFAULT_SHADOW_BY_SIZE: Record<MapTilerMarkerSize, MapTilerMarkerShadow>;
+export declare const DEFAULT_OUTLINE_WIDTH = 2;
+/** Anchor used when `MarkerOptions.anchor` is unset (matches MapLibre's own default). */
+export declare const DEFAULT_ANCHOR: NonNullable<MarkerOptions["anchor"]>;
+/** Size a minimized marker renders at when `minimizedOptions.size` is unset. */
+export declare const DEFAULT_MINIMIZED_SIZE: MapTilerMarkerSize;
+/** Duration (ms) of transitions and animations when their `duration` is omitted. */
+export declare const DEFAULT_ANIMATION_DURATION_MS = 1000;
+/**
+ * Default proximity threshold in CSS px: two markers whose boxes come within
+ * this distance of each other are "in proximity". Overlap always uses 0.
+ */
+export declare const DEFAULT_PROXIMITY_PADDING = 4;
+/** Matches the fade duration in the SDK stylesheet (`.maptiler-marker-collision-fade`). */
+export declare const COLLISION_FADE_DURATION_MS = 150;
+export declare const SIZE_PX: Record<MapTilerMarkerSize, number>;
+export declare const SHADOW_FILTER: Record<MapTilerMarkerShadow, string>;
+/** Content sizing per marker size, shared by every shape (px). */
+export declare const CONTENT_METRICS: Record<ShapeSize, ContentMetrics>;
+/**
+ * Default marker colours per map style. `base` doubles as the fallback for
+ * styles without a dedicated entry.
+ */
+export declare const ADAPTIVE_COLORS: {
+    base: AdaptiveColorSet;
+} & Partial<Record<AdaptiveStyleKey, AdaptiveColorSet>>;
+/**
+ * Shapes whose default colours are the map style's, swapped: a blue body with a white inner fill and
+ * a blue mark. Colours set explicitly aren't touched.
+ */
+export declare const INVERTED_COLOR_SHAPES: readonly string[];
+export declare const ADAPTIVE_COLOR_KEYS: readonly ["outerColor", "innerColor", "contentColor", "outlineColor"];
+export declare const MAPLIBRE_MARKER_CONSTRUCTOR_OVERRIDES: MarkerOptions;
+export declare const CUSTOM_ELEMENT_MINIMIZED_KEYS: readonly ["innerColor", "outerColor", "contentColor", "shadow", "opacity"];
+export declare const MAPTILER_BASE_OPTIONS_KEYS: readonly ["lngLat", "shape", "size", "innerColor", "outerColor", "contentColor", "outline", "outlineColor", "shadow", "opacity", "opacityWhenCovered", "name", "title", "content", "htmlAttributes", "scale", "visible", "priority", "userData", "collisionBehaviour", "collisionRadius", "minimizedOptions", "rotation", "debug", "states", "transitions"];
+/** Pending props that change a marker's footprint and therefore its collisions. */
+export declare const FOOTPRINT_PROPS: readonly ["shape", "size", "scale", "rotation"];
+export declare const UI_STATE_PRIORITY: readonly MapTilerMarkerUIStateName[];
+/** Vertical offset (CSS px) `enter`'s `drop`/`bounce` start from on `enter`. */
+export declare const LIFECYCLE_LIFT_PX = 48;
+/** Default easing per `enter` preset, used when `MarkerAnimationOptions.easing` doesn't override it. */
+export declare const ENTER_PRESET_EASING: Record<EnterAnimationPreset, EasingFunctionName>;
+/** Default easing per `exit` preset, used when `MarkerAnimationOptions.easing` doesn't override it. */
+export declare const EXIT_PRESET_EASING: Record<ExitAnimationPreset, EasingFunctionName>;
+/** Scale multiplier `explode` grows the marker to (from its own base scale) while it fades out. */
+export declare const EXPLODE_SCALE_MULTIPLIER = 2;
+export declare const PULSE_SCALE_PEAK = 1.15;
+export declare const PULSE_OPACITY_PEAK = 0.45;
+export declare const RING_PEAK_DEG = 12;
+export declare const IDLE_BOUNCE_LIFT_PX = 14;
+/**
+ * Default loop duration (ms) per idle preset, used when
+ * `MarkerIdleAnimationOptions.duration` is omitted — overrides the generic
+ * `1000` documented on {@link MarkerAnimationOptions}. `pulsescale`/
+ * `pulseopacity` default to ~1Hz; `ring`/`bounce` recur every few seconds.
+ */
+export declare const IDLE_PRESET_DEFAULT_DURATION: Record<IdleAnimationPreset, number>;
+/** Design-space size (units) for SVG template glyphs. */
+export declare const GLYPH_VIEWBOX_SIZE = 24;
+/** Letter spacing of text content, in em. */
+export declare const TEXT_LETTER_SPACING_EM = -0.06;
+/** Font weight of text content — between Medium (500) and SemiBold (600); the marker font is variable (400–600). */
+export declare const TEXT_FONT_WEIGHT = 575;
+/** Font stack of marker text — keep in step with `.maptiler-sdk-marker-font` in `style_template.css`. */
+export declare const MARKER_FONT_FAMILY = "\"Inter\", \"MapTiler Inter\", system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
+/** Cap height of the marker font, in em (Inter) — the height of the letters a label has to fit. */
+export declare const TEXT_CAP_HEIGHT_EM = 0.727;
+/** Space kept free between a label and the edge of the inner fill, in px, so antialiased glyph edges aren't clipped. */
+export declare const TEXT_FIT_MARGIN_PX = 1;
+/** Smallest font size a label is shrunk to when it doesn't fit (px); below this it's clipped rather than made illegible. */
+export declare const TEXT_MIN_FONT_PX = 6;
+/** Width of the outer-colour ring around the xs dot's inner fill (px). */
+export declare const DOT_RING_PX = 2;
+/**
+ * Minimum margin in CSS px around the viewport within which markers still
+ * participate in the pass. Off-viewport markers are excluded and hidden, but
+ * a marker just past the edge must keep blocking its on-screen neighbours,
+ * or edge behaviour would churn while panning.
+ */
+export declare const VIEWPORT_CULL_MARGIN_PX = 200;
+/**
+ * Base z-index for camera-depth ordering among altitude-active markers (see
+ * the altitude render loop's `onRender`). Well above the small integers
+ * `priority` typically produces, so depth-ordered altitude markers land
+ * above statically-ordered ones rather than interleaving with them —
+ * "closer to the camera" is a different axis from "higher priority", and
+ * mixing the two into one ranking isn't attempted here.
+ */
+export declare const ALTITUDE_Z_INDEX_BASE = 1000;
+export declare const SVG_NS = "http://www.w3.org/2000/svg";
+export declare const DEBUG_COLOR = "#ff00ff";
+export declare const CUSTOM_ELEMENT_CLASSNAME = "marker-transform-wrapper";
+/** Added to every marker's wrapper element so marker text can pick up the SDK font. */
+export declare const MARKER_FONT_CLASSNAME = "maptiler-sdk-marker-font";
+export declare const SHAPE_SVG_CLASSNAME = "marker-shape";
+export declare const DEFAULT_CONTENT_CLASSNAME = "marker-default-content";
+export declare const MINIMIZED_DOT_CLASSNAME = "marker-minimized-dot";
+export declare const COLLISION_FADE_CLASSNAME = "maptiler-marker-collision-fade";
+export declare const COLLISION_HIDDEN_CLASSNAME = "maptiler-marker-collision-hidden";
+export declare const COLLISION_CULLED_CLASSNAME = "maptiler-marker-collision-culled";
+export declare const ALTITUDE_HIDDEN_CLASSNAME = "maptiler-marker-altitude-hidden";
+export declare const ALTITUDE_OCCLUDED_CLASSNAME = "maptiler-marker-altitude-occluded";
+export declare const GROUND_LINE_CLASSNAME = "maptiler-marker-groundline";

package/dist/Marker/marker-content-registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Produces marker content from template parameters.
+ * May return a string (rendered as marker text), an `HTMLElement` (rendered
+ * in a foreignObject sized to the content circle), or an `SVGElement`
+ * (treated like a content-type glyph, designed in a
+ * `GLYPH_VIEWBOX_SIZE`-unit square).
+ */
+export type MarkerTemplateFactory = (params?: Record<string, number | string>) => string | HTMLElement | SVGElement;
+/**
+ * Registers (or overrides) a template factory usable via the marker
+ * `template` / `templateParams` options.
+ * @param name - Identifier passed as `template`.
+ * @param factory - Template factory, see {@link MarkerTemplateFactory}.
+ */
+export declare function registerMarkerTemplate(name: string, factory: MarkerTemplateFactory): void;
+/** Returns the factory for a template, or `undefined` when unknown. */
+export declare function getMarkerTemplate(name: string): MarkerTemplateFactory | undefined;

package/dist/Marker/marker-dom-utils.d.ts

@@ -0,0 +1,66 @@
+import { MarkerOptions } from 'maplibre-gl';
+import { MapTilerMarkerOptions, PendingMarkerUpdates } from './types';
+/**
+ * Resolves the inner transform wrapper from a marker's outer root element
+ * (or returns `element` itself when it already is the wrapper, or has none).
+ * @param element - The marker's outer root element.
+ */
+export declare function resolveMarkerWrapper(element: HTMLElement): HTMLElement;
+/**
+ * Seeds the CSS custom properties that drive marker colors and shadow.
+ * Used on the generated wrapper, and on user-supplied custom elements so
+ * their styles can consume the same variables.
+ * @param element - Element to receive the custom properties.
+ * @param options - Resolved marker options.
+ */
+export declare function applyMarkerStyleVariables(element: HTMLElement | SVGElement, options: MapTilerMarkerOptions): void;
+/**
+ * Creates the root wrapper `div` for a marker, seeding all CSS custom
+ * properties and the initial `data-*` attributes used by {@link applyTransform}.
+ * @param options - Resolved marker options.
+ * @returns The outer root element, ready to be handed to MapLibre.
+ */
+export declare function createMarkerElement(options: MapTilerMarkerOptions): HTMLDivElement;
+/**
+ * Commits a batch of pending property updates onto a live marker element.
+ * Called by `Marker[FlushDOMUpdatesSymbol]()` when there are pending updates.
+ * A key being present in `props` (even with an `undefined` value) means
+ * "apply this property".
+ * @param element - The marker's outer root element.
+ * @param props - Pending property updates.
+ * @param styleId - Current map style id, used to resolve unset colours to their map-style defaults.
+ */
+export declare function updateMarkerElement(element: HTMLElement, props: PendingMarkerUpdates, styleId?: string): void;
+/** Toggles the collision-hidden fade (rules live in the SDK stylesheet). */
+export declare function applyCollisionHidden(element: HTMLElement, hidden: boolean): void;
+/** Removes the fade class — only call once no fade/dip is in flight, or it cuts the animation short. */
+export declare function releaseCollisionFadeClass(element: HTMLElement): void;
+/**
+ * `display: none`s a collision-hidden marker once its fade completes. Un-culling doesn't flush
+ * layout itself — {@link MarkerManagerImpl} batches that once per pass.
+ * @returns `true` when the call actually changed the culled state.
+ */
+export declare function applyCollisionCulled(element: HTMLElement, culled: boolean): boolean;
+/** Hides a marker with no valid altitude-projected position this frame (off-screen/behind camera). Not the below-ground case — see {@link applyAltitudeOccluded}. */
+export declare function applyAltitudeHidden(element: HTMLElement, hidden: boolean): void;
+/** Fades a below-ground marker (DOM markers aren't depth-tested against terrain) — position and pointer events stay real, only opacity changes. */
+export declare function applyAltitudeOccluded(element: HTMLElement, occluded: boolean): void;
+/** Minimized rendering for custom `element` markers: hides its content via `visibility` (keeps the layout box for positioning) and overlays a dot on the anchor point. SVG-root elements get hidden without a dot. */
+export declare function applyMinimizedDot(element: HTMLElement | SVGElement, anchor: NonNullable<MarkerOptions["anchor"]>, enabled: boolean): void;
+/** Sets the lifecycle-animation vertical offset in CSS px. Animation-only, bypasses {@link updateMarkerElement}'s batching. */
+export declare function applyLifecycleLift(element: HTMLElement, liftPx: number): void;
+/**
+ * Wraps `element` in a new container `div`.
+ * MapLibre requires a single root element per marker; this outer wrapper
+ * lets MapLibre apply its own transforms without interfering with the
+ * inner wrapper's scale/rotation transform.
+ * @param element - Element to wrap.
+ */
+export declare function wrap(element: HTMLElement): HTMLDivElement;
+/**
+ * Prevents MapLibre element events from firing when the outer root element
+ * is clicked but the inner wrapper is not — e.g. whitespace within the
+ * MapLibre-positioned container.
+ * @param parent - The marker's outer root element.
+ */
+export declare function forwardPointerEvents(parent: HTMLElement): void;