@maptiler/sdk 5.0.0-rc.2 → 5.0.0-rc.3

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;

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

@@ -0,0 +1,31 @@
+/** Design-space size (px) of the built-in icon paths. */
+export declare const MARKER_ICON_VIEWBOX_SIZE = 16;
+/** Path data of each built-in icon, keyed by the name used as the marker `icon` option. */
+export declare const MARKER_ICONS: {
+    readonly attraction: "M6.15385 1C5.472 1 5.22806 1.62092 4.92308 2.23077L4.30769 3.46154H1.84615C0.823385 3.46154 0 4.28492 0 5.30769V11.4615C0 12.4843 0.823385 13.3077 1.84615 13.3077H14.1538C15.1766 13.3077 16 12.4843 16 11.4615V5.30769C16 4.28492 15.1766 3.46154 14.1538 3.46154H11.6923L11.0769 2.23077C10.7692 1.61538 10.528 1 9.84615 1H6.15385ZM1.84615 4.69231C2.18597 4.69231 2.46154 4.96788 2.46154 5.30769C2.46154 5.64751 2.18597 5.92308 1.84615 5.92308C1.50634 5.92308 1.23077 5.64751 1.23077 5.30769C1.23077 4.96788 1.50634 4.69231 1.84615 4.69231ZM8 4.69231C10.0393 4.69231 11.6923 6.34535 11.6923 8.38462C11.6923 10.4239 10.0393 12.0769 8 12.0769C5.96074 12.0769 4.30769 10.4239 4.30769 8.38462C4.30769 6.34535 5.96074 4.69231 8 4.69231ZM8 6.53846C6.98043 6.53846 6.15385 7.36505 6.15385 8.38462C6.15385 9.40419 6.98043 10.2308 8 10.2308C9.01957 10.2308 9.84615 9.40419 9.84615 8.38462C9.84615 7.36505 9.01957 6.53846 8 6.53846Z";
+    readonly bar: "M8 0.0855713C5.55162 0.0855713 -0.569328 0.391619 0.0427664 1.00371L7.38791 8.6549V13.5517C7.38791 14.7758 3.71534 14.1638 3.71534 16H12.2847C12.2847 14.1638 8.61209 14.7758 8.61209 13.5517V8.6549L15.9572 1.00371C16.5693 0.391619 10.4484 0.0855713 8 0.0855713ZM8 1.30976C11.0605 1.30976 13.8149 1.61581 13.8149 1.61581L12.8968 2.53395H3.10324L2.1851 1.61581C2.1851 1.61581 4.93953 1.30976 8 1.30976Z";
+    readonly cafe: "M13.3333 4.94657H12.6667V2.27991H2V7.61324C2.01773 10.5587 4.41987 12.932 7.36533 12.9143C9.246 12.903 10.9816 11.902 11.9333 10.2799H13.3333C14.8061 10.2799 16 9.08604 16 7.61324C16 6.14044 14.8061 4.94657 13.3333 4.94657ZM13.3333 8.94657H12.48C12.5983 8.51177 12.6611 8.06377 12.6667 7.61324V6.27991H13.3333C14.0697 6.27991 14.6667 6.87684 14.6667 7.61324C14.6667 8.34964 14.0697 8.94657 13.3333 8.94657ZM12.6667 14.9466C12.6667 15.3147 12.3681 15.6132 12 15.6132H2.66667C2.29853 15.6132 2 15.3147 2 14.9466C2 14.5784 2.29853 14.2799 2.66667 14.2799H12C12.3681 14.2799 12.6667 14.5784 12.6667 14.9466Z";
+    readonly car: "M15.8031 6.66575L14.2769 5.2479L12.9231 2.54021C12.8068 2.35115 12.6438 2.19522 12.4498 2.08743C12.2558 1.97965 12.0373 1.92365 11.8154 1.92482H4.18462C3.96268 1.92365 3.74418 1.97965 3.55017 2.08743C3.35616 2.19522 3.19317 2.35115 3.07692 2.54021L1.72308 5.2479L0.196923 6.66575C0.134751 6.72341 0.0851657 6.79329 0.0512785 6.87102C0.0173913 6.94875 -6.65933e-05 7.03264 1.90887e-07 7.11744V12.3864C1.90887e-07 12.5496 0.0648351 12.7061 0.180242 12.8215C0.295649 12.9369 0.452175 13.0017 0.615385 13.0017H3.07692C3.32308 13.0017 3.69231 12.7556 3.69231 12.5094V11.771H12.3077V12.3864C12.3077 12.6325 12.5538 13.0017 12.8 13.0017H15.3846C15.5478 13.0017 15.7044 12.9369 15.8198 12.8215C15.9352 12.7061 16 12.5496 16 12.3864V7.11744C16.0001 7.03264 15.9826 6.94875 15.9487 6.87102C15.9148 6.79329 15.8652 6.72341 15.8031 6.66575ZM4.30769 3.15559H11.6923L12.9231 5.61713H3.07692L4.30769 3.15559ZM4.92308 8.81713C4.92308 9.06328 4.55385 9.30944 4.30769 9.30944H1.72308C1.47692 9.30944 1.23077 8.94021 1.23077 8.69405V7.34021C1.35385 6.97098 1.6 6.72482 1.96923 6.8479L4.43077 7.34021C4.67692 7.34021 4.92308 7.70944 4.92308 7.95559V8.81713ZM14.7692 8.69405C14.7692 8.94021 14.5231 9.30944 14.2769 9.30944H11.6923C11.4462 9.30944 11.0769 9.06328 11.0769 8.81713V7.95559C11.0769 7.70944 11.3231 7.34021 11.5692 7.34021L14.0308 6.8479C14.4 6.72482 14.6462 6.97098 14.7692 7.34021V8.69405Z";
+    readonly circle: "M15 8C15 11.866 11.866 15 8 15C4.13395 15 1 11.866 1 8C1 4.13395 4.13395 1 8 1C11.866 1 15 4.13395 15 8Z";
+    readonly clothes: "M3.69231 1.46387L0 4.54079V7.61771H3.69231V15.0023H12.3077V7.61771H16V4.54079L12.3077 1.46387H10.4615L8 6.38694L5.53846 1.46387H3.69231Z";
+    readonly diamond: "M7.43002 0.247964L1.38484 7.01536C1.29154 7.11866 1.23746 7.24927 1.2311 7.3846C1.22475 7.51991 1.26647 7.64322 1.34972 7.75383L7.39232 15.7047C7.46103 15.7961 7.55206 15.8704 7.65775 15.9218C7.76344 15.9732 7.8807 16 7.99971 16C8.11871 16 8.23598 15.9732 8.34166 15.9218C8.44735 15.8704 8.53837 15.7961 8.60709 15.7047L14.6497 7.75383C14.7329 7.64322 14.7747 7.51991 14.7683 7.3846C14.7619 7.24927 14.7079 7.11866 14.6146 7.01536L8.56931 0.247964C8.49923 0.170253 8.41197 0.107828 8.31359 0.0650093C8.2152 0.0221785 8.10808 0 7.99965 0C7.89121 0 7.78409 0.0221785 7.6857 0.0650093C7.58732 0.107828 7.5001 0.170253 7.43002 0.247964Z";
+    readonly flag: "M9.19698 1.04277C5.67775 3.38889 3.33152 1.04277 3.33152 1.04277V9.25435C3.33152 9.25435 5.67763 11.6005 9.19698 9.25435C12.7162 6.90824 15.0624 9.25435 15.0624 9.25435V1.04277C15.0624 1.04277 12.7163 -1.30346 9.19698 1.04277ZM1.5719 0.16295C1.27862 0.16295 0.985352 0.456223 0.985352 1.04277V15.1202C0.985352 16.2933 2.15847 16.2933 2.15847 15.1202V1.04277C2.15847 0.456223 1.86517 0.16295 1.5719 0.16295Z";
+    readonly heart: "M15.3237 7.92352C13.9869 10.4942 10.4108 13.9904 8.38846 15.8528C8.17104 16.049 7.84039 16.049 7.62296 15.8528C5.58924 13.9904 2.01309 10.4942 0.676312 7.92352C-2.26002 2.26794 5.14365 -1.50244 8 4.15313C10.8564 -1.50244 18.26 2.26794 15.3237 7.92352Z";
+    readonly hospital: "M7.38462 0C6.64615 0 6.15385 0.492308 6.15385 1.23077V6.15385H1.23077C0.492308 6.15385 0 6.64615 0 7.38462V8.61539C0 9.35385 0.492308 9.84615 1.23077 9.84615H6.15385V14.7692C6.15385 15.5077 6.64615 16 7.38462 16H8.61539C9.35385 16 9.84615 15.5077 9.84615 14.7692V9.84615H14.7692C15.5077 9.84615 16 9.35385 16 8.61539V7.38462C16 6.64615 15.5077 6.15385 14.7692 6.15385H9.84615V1.23077C9.84615 0.492308 9.35385 0 8.61539 0H7.38462Z";
+    readonly lodging: "M0.533333 2.68237C0.213333 2.68237 0 2.89571 0 3.21571V13.349C0 13.669 0.213333 13.8824 0.533333 13.8824C0.853333 13.8824 1.06667 13.669 1.06667 13.349V11.749H14.9333V13.349C14.9333 13.669 15.1467 13.8824 15.4667 13.8824C15.7867 13.8824 16 13.669 16 13.349V11.2157C16 10.8957 15.7867 10.6824 15.4667 10.6824H1.06667V3.21571C1.06667 2.89571 0.853333 2.68237 0.533333 2.68237ZM3.73333 3.21571C2.88 3.21571 2.13333 3.96237 2.13333 4.81571C2.13333 5.66904 2.88 6.41571 3.73333 6.41571C4.58667 6.41571 5.33333 5.66904 5.33333 4.81571C5.33333 3.96237 4.58667 3.21571 3.73333 3.21571ZM7.46667 4.28237C5.86667 4.28237 5.86667 5.88237 5.86667 5.88237V7.48237H2.66667C2.34667 7.48237 2.13333 7.69571 2.13333 8.01571V9.08237C2.13333 9.40237 2.34667 9.61571 2.66667 9.61571H16V6.94904C16 4.28237 13.3333 4.28237 13.3333 4.28237H7.46667Z";
+    readonly mall: "M0.537767 1.53638C0.240509 1.53638 0 1.78812 0 2.09663C0 2.40515 0.240509 2.65476 0.537767 2.65476H2.34532C2.60222 2.65476 2.82447 2.8415 2.87491 3.10254L4.14265 9.68341C4.29329 10.4666 4.95386 11.0289 5.72323 11.0289H12.3584C13.0861 11.0289 13.7248 10.5246 13.9165 9.79589L14.943 5.88684C15.0755 5.38359 14.9743 4.8435 14.669 4.4289C14.3637 4.0143 13.89 3.77103 13.3869 3.77103H4.09971L3.92795 2.88396C3.7773 2.10081 3.11468 1.53638 2.34532 1.53638H0.537767ZM6.27122 12.1876C5.38013 12.1876 4.65792 12.9371 4.65792 13.862C4.65792 14.7868 5.38013 15.5364 6.27122 15.5364C7.16231 15.5364 7.88452 14.7868 7.88452 13.862C7.88452 12.9371 7.16231 12.1876 6.27122 12.1876ZM11.4137 12.1876C10.5227 12.1876 9.80045 12.9371 9.80045 13.862C9.80045 14.7868 10.5227 15.5364 11.4137 15.5364C12.3048 15.5364 13.027 14.7868 13.027 13.862C13.027 12.9371 12.3048 12.1876 11.4137 12.1876Z";
+    readonly maptiler: "M2.37305 8.90062C1.87565 8.40322 1.87565 7.59678 2.37305 7.09938L7.09938 2.37305C7.59678 1.87565 8.40322 1.87565 8.90062 2.37305L13.6269 7.09938C14.1243 7.59678 14.1243 8.40322 13.6269 8.90062L8.90062 13.6269C8.40322 14.1243 7.59678 14.1243 7.09938 13.6269L2.37305 8.90062Z";
+    readonly park: "M15.3892 5.82267C15.4031 4.97604 14.9206 4.19935 14.1555 3.83655C14.0908 3.03544 13.4171 2.42109 12.6135 2.43022C12.4916 2.43997 12.3715 2.46489 12.2558 2.50424C12.1809 1.69005 11.4602 1.09076 10.6461 1.16564C10.327 1.195 10.0261 1.32712 9.78853 1.54202C9.78853 0.690332 9.0982 0 8.24651 0C7.39482 0 6.70449 0.690332 6.70449 1.54202C6.70449 1.54202 6.75384 1.56669 6.75384 1.6037C6.12297 1.06251 5.17284 1.1353 4.63165 1.76629C4.44895 1.97934 4.32941 2.23914 4.28661 2.51658C4.09132 2.45428 3.88704 2.42517 3.68213 2.43022C2.66021 2.42171 1.8248 3.24318 1.81629 4.2651C1.81419 4.51158 1.86144 4.75584 1.95507 4.98381C0.97743 5.25705 0.40639 6.27121 0.679636 7.24885C0.852589 7.86776 1.33617 8.35133 1.95507 8.52429C2.26755 9.49009 3.30391 10.0198 4.2697 9.70732C4.93006 9.49366 5.41376 8.92632 5.52022 8.24056C5.74597 8.43682 6.02514 8.56142 6.32207 8.5983V14.7664L4.28661 16H10.4547L8.4809 14.7664V12.2992C9.39143 11.1994 10.5676 10.3502 11.898 9.83192C12.8864 10.0637 13.8755 9.45049 14.1073 8.46224C14.1423 8.31285 14.1586 8.15963 14.1555 8.00617C14.1591 7.94042 14.1591 7.87454 14.1555 7.80879C14.9206 7.44598 15.4031 6.6693 15.3892 5.82267ZM8.4809 11.3863V7.14264C8.81435 7.73564 9.44127 8.10325 10.1216 8.10486H10.467C10.4863 8.64654 10.7436 9.1522 11.1702 9.48651C10.1639 9.94788 9.25203 10.5921 8.4809 11.3863Z";
+    readonly restaurant: "M3.59759 0L2.53093 5.86667C2.37477 6.72533 4.43119 7.1264 4.39759 8L4.13093 14.9333C4.08997 15.9993 5.19759 16 5.19759 16C5.19759 16 6.30522 15.9993 6.26426 14.9333L5.99759 8C5.9641 7.12789 7.84655 6.74048 7.86426 5.86667L6.79759 0H6.26426L6.53093 4.26667L5.73093 4.8L5.46426 0H4.93093L4.66426 4.8L3.86426 4.26667L4.13093 0H3.59759ZM12.6643 0C11.8788 0 10.5691 0.69856 10.0455 1.74581C9.60911 2.53131 9.46426 4.28608 9.46426 5.33333V8C9.46426 8.87275 10.6279 9.06667 11.0643 9.06667L10.5309 14.9333C10.4344 15.9956 11.5976 16 11.5976 16C11.5976 16 12.6643 16 12.6643 14.9333V0Z";
+    readonly shop: "M15.3765 5.05681H13.063L12.57 2.11122C12.3676 1.20327 11.6829 0.479765 10.7875 0.227556C10.3459 0.08546 9.88595 0.00884942 9.42211 0H6.5903C6.12646 0.00884942 5.66655 0.08546 5.22496 0.227556C4.32952 0.479765 3.64483 1.20327 3.44243 2.11122L2.9494 5.05681H0.635905C0.286858 5.05466 0.00215981 5.33595 1.06675e-05 5.68512C-0.000368593 5.75073 0.00936577 5.81596 0.0290873 5.87854L2.40579 13.843C2.65408 14.6326 3.38592 15.1699 4.2136 15.1704H11.7988C12.6218 15.1645 13.3471 14.6282 13.594 13.843L15.9707 5.87854C16.0755 5.54555 15.8904 5.19069 15.5574 5.08589C15.4989 5.06743 15.4379 5.0577 15.3765 5.05681ZM4.23888 5.05681L4.694 2.31349C4.79602 1.85522 5.1663 1.50503 5.62951 1.42855C5.94088 1.33045 6.26401 1.2752 6.5903 1.2642H9.42211C9.75258 1.27406 10.0801 1.32931 10.3956 1.42855C10.8588 1.50503 11.229 1.85522 11.3311 2.31349L11.7735 5.05681H4.18831H4.23888Z";
+    readonly square: "M13.7273 15H2.27273C1.5698 15 1 14.4302 1 13.7273V2.27273C1 1.5698 1.5698 1 2.27273 1H13.7273C14.4302 1 15 1.5698 15 2.27273V13.7273C15 14.4302 14.4302 15 13.7273 15Z";
+    readonly star: "M7.99953 0L5.79263 5.51724H0.275391L4.68918 9.37931L2.48229 16L7.99953 12.1379L13.5168 16L11.3099 9.37931L15.7237 5.51724H10.2064L7.99953 0Z";
+    readonly triangle: "M8.04732 0C7.68449 0 7.44634 0.21809 7.28991 0.473348L0.094645 12.2128C0 12.3075 0 12.4968 0 12.6862C0 13.3489 0.473348 13.5382 0.852051 13.5382H15.1479C15.6213 13.5382 16 13.3489 16 12.6862C16 12.4969 16 12.4021 15.9054 12.2128L8.80472 0.473348C8.64989 0.217228 8.35464 0 8.04732 0Z";
+    readonly water: "M8.00038 16C10.5565 16 13.5388 14.4144 13.5388 10.3784C13.5388 7.63968 9.27846 1.5856 8.00038 0C6.86426 1.5856 2.46191 7.49547 2.46191 10.3784C2.46191 14.4144 5.44422 16 8.00038 16Z";
+};
+/** Built-in icon drawn as marker content; `maptiler` is the MapTiler mark (the `maptiler` shape's default content). */
+export type MapTilerMarkerIcon = keyof typeof MARKER_ICONS;
+/** Names of the built-in marker icons. */
+export declare const MARKER_ICON_NAMES: MapTilerMarkerIcon[];
+/** Returns the path data of a built-in icon, or `undefined` when unknown. */
+export declare function getMarkerIconPath(name: string): string | undefined;

package/dist/Marker/marker-state-helpers.d.ts

@@ -0,0 +1,2 @@
+import { MapTilerMarkerUIStateName, MapTilerMarkerUIStates, UIStateSpec } from './types';
+export declare function flattenUIStates(states: MapTilerMarkerUIStates, active: ReadonlySet<MapTilerMarkerUIStateName>): UIStateSpec;

package/dist/Marker/marker-svg-config.d.ts

@@ -0,0 +1,84 @@
+import { MapTilerMarkerIcon, MapTilerMarkerSize, MapTilerMarkerShape } from './types';
+/** Sizes that render a shape SVG — `xs` renders a plain dot instead. */
+export type ShapeSize = Exclude<MapTilerMarkerSize, "xs">;
+/**
+ * Region content is confined to: the inner fill (on bubble-square, body and tail).
+ * Images fill it edge to edge; text and elements are clipped to it.
+ * `x`/`y`/`w`/`h` are the bounding box of the path `d`; `round` is set when the region is a
+ * circle, which narrows towards its top and bottom (text fitting measures against the chord).
+ */
+export type ShapeClip = {
+    d: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    round: boolean;
+};
+/**
+ * Geometry of one shape at one size, in CSS px. The SVG viewBox is the
+ * marker box (`SIZE_PX[size]` square), so one unit is one pixel and every
+ * value below is taken 1:1 from the design.
+ */
+export type ShapeGeometry = {
+    /** Path data of the body, painted in the outer colour. */
+    outer: string;
+    /** Path data of the fill, painted in the inner colour — drawn in order, as separate elements like the design. */
+    inner: string[];
+    clip: ShapeClip;
+    /** Centre of the content box (text, icon, element). */
+    content: {
+        cx: number;
+        cy: number;
+    };
+};
+export type ShapeDescriptor = {
+    /** Which point of the shape sits on the marker's geographic location — the box centre, or the tail tip at the bottom edge of the box. */
+    anchor: "bottom" | "center";
+    /** Built-in icon shown when the marker has no content of its own — drawn exactly like `icon` content. */
+    defaultIcon?: MapTilerMarkerIcon;
+    /** Per-size geometry. Sizes are drawn individually (fixed ring width, padding), not scaled from one another. */
+    sizes: Record<ShapeSize, ShapeGeometry>;
+};
+/** Content sizing per marker size, shared by every shape (px). */
+export type ContentMetrics = {
+    /** Content box — element content is sized to it. */
+    box: number;
+    /** Icon / SVG-glyph box. */
+    icon: number;
+    /** Text font size. */
+    font: number;
+    /**
+     * Distance from the content-box centre down to the text baseline. Whole pixels,
+     * so flat letter bottoms land on one crisp row on 1× screens (a half-pixel
+     * baseline reads as text sitting low).
+     */
+    baseline: number;
+    /**
+     * Font size and baseline for a one-character label — a single letter or digit is drawn larger than a
+     * longer label. The baseline is chosen so the capitals sit optically centred (a hair above the
+     * centre); it may sit on a half pixel when no whole pixel does that.
+     */
+    singleChar?: {
+        font: number;
+        baseline: number;
+    };
+};
+/** Path data of a circle — two half-circle arcs, so it can also be drawn with `new Path2D(d)`. */
+export declare function circlePath(cx: number, cy: number, r: number): string;
+export declare const SHAPES: Record<MapTilerMarkerShape, ShapeDescriptor>;
+/**
+ * Geometry of a shape at a size. `xs` has no shape geometry (it renders a
+ * dot); it resolves to `fallback` so callers holding a hidden shape SVG
+ * still get valid numbers.
+ */
+export declare function getShapeGeometry(shapeKey: MapTilerMarkerShape, sizeKey: MapTilerMarkerSize, fallback?: ShapeSize): ShapeGeometry;
+/**
+ * Pixel offset (MapLibre `offset` convention, +y down) that places the
+ * shape's anchor point on the marker's lngLat instead of the element centre
+ * (MapLibre's default `center` anchor). Bottom-anchored shapes have their
+ * tail tip on the bottom edge of the marker box at every size.
+ * @param shapeKey - Shape variant.
+ * @param sizeKey - Size key; `xs` renders a centered dot, so no offset.
+ */
+export declare function getShapeAnchorOffset(shapeKey: MapTilerMarkerShape, sizeKey: MapTilerMarkerSize): [number, number];

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

@@ -0,0 +1,12 @@
+export declare const FlushDOMUpdatesSymbol: unique symbol;
+export declare const PendingUpdatesSymbol: unique symbol;
+export declare const MarkerElementSymbol: unique symbol;
+export declare const DetachFromDOMSymbol: unique symbol;
+export declare const RefreshAdaptiveColorSymbol: unique symbol;
+export declare const CollisionFootprintSymbol: unique symbol;
+export declare const EmitCollisionDiffSymbol: unique symbol;
+export declare const ApplyCollisionDisplayStateSymbol: unique symbol;
+export declare const MeasuredElementSizeSymbol: unique symbol;
+export declare const ClearFocusStateSymbol: unique symbol;
+export declare const ApplyAltitudeFrameSymbol: unique symbol;
+export declare const AttachToMapSymbol: unique symbol;

package/dist/Marker/marker-text-fit.d.ts

@@ -0,0 +1,20 @@
+import { ShapeGeometry } from './marker-svg-config';
+/** Font size and baseline (px, relative to the content centre) a label is drawn with. */
+export type LabelMetrics = {
+    font: number;
+    baseline: number;
+};
+/**
+ * Calls `onLoad` once the marker font at `px` has loaded, so a label measured with a fallback
+ * font's widths can be fitted again. Does nothing when the font is already loaded.
+ */
+export declare function onLabelFontLoad(label: string, px: number, onLoad: () => void): Promise<void>;
+/**
+ * Shrinks a multi-character label that is wider than the fill so it isn't clipped. A label that
+ * already fits (and a single character) keeps `nominal`. The baseline scales with the font
+ * size, on a whole pixel, so the capitals stay centred.
+ * @param label - The text to draw.
+ * @param nominal - Font size and baseline of the marker size for this label.
+ * @param geometry - Shape the label sits in.
+ */
+export declare function fitLabel(label: string, nominal: LabelMetrics, geometry: ShapeGeometry): LabelMetrics;