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

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;

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

@@ -0,0 +1,29 @@
+import { LngLat } from '../index';
+import { MaptilerAnimation } from '../MaptilerAnimation';
+import { MarkerTransitionSpec, Vector2 } from './types';
+import { LifecycleAnimationValue } from './marker-animation-presets';
+/** Bridges a transitionable property's real value to/from the flat numeric props {@link MaptilerAnimation} interpolates between. */
+export type TransitionValueCodec<T> = {
+    toNumeric(value: T): Record<string, number>;
+    fromNumeric(props: Record<string, number>): T;
+};
+export declare const scaleTransitionCodec: TransitionValueCodec<Vector2>;
+export declare const rotationTransitionCodec: TransitionValueCodec<number>;
+export declare const opacityTransitionCodec: TransitionValueCodec<number>;
+/** Bridges an `enter`/`exit` preset's combined opacity/scale/lift state to the numeric props {@link MaptilerAnimation} interpolates between. */
+export declare const lifecycleTransitionCodec: TransitionValueCodec<LifecycleAnimationValue>;
+export declare const positionTransitionCodec: TransitionValueCodec<LngLat>;
+export declare const colorTransitionCodec: TransitionValueCodec<string | undefined>;
+export type PropertyTransitionHandlers<T> = {
+    codec: TransitionValueCodec<T>;
+    onUpdate: (value: T) => void;
+    onStart: () => void;
+    onEnd: (value: T) => void;
+};
+/**
+ * Eases `from` to `to` over `spec`'s duration/easing/delay via a one-shot
+ * {@link MaptilerAnimation}, calling `onUpdate` every frame and `onEnd` once
+ * with the exact target value. The returned animation is already playing;
+ * callers own its lifetime — `.destroy()` it to cancel.
+ */
+export declare function runPropertyTransition<T>(from: T, to: T, spec: MarkerTransitionSpec, handlers: PropertyTransitionHandlers<T>): MaptilerAnimation;

package/dist/Marker/types.d.ts

@@ -0,0 +1,458 @@
+import { Event as EventML, LngLatLike, MarkerEventType, MarkerOptions } from 'maplibre-gl';
+import { EasingFunctionName } from '../MaptilerAnimation/types';
+import { Marker } from './Marker';
+import { MapTilerMarkerIcon } from './marker-icons';
+/** Visual shape of the marker body. */
+export type MapTilerMarkerShape = "circle" | "square" | "bubble-circle" | "bubble-square" | "maptiler" | "maptiler-full";
+/** T-shirt size for the marker. */
+export type MapTilerMarkerSize = "xs" | "s" | "m" | "l";
+/** Drop-shadow intensity applied beneath the marker. */
+export type MapTilerMarkerShadow = "none" | "soft" | "medium" | "strong";
+export type { MapTilerMarkerIcon } from './marker-icons';
+/** Behaviour when this marker spatially overlaps another. */
+export declare const CollisionBehaviour: {
+    /** No collision detection — marker is always shown. */
+    readonly ALWAYS_SHOW: "always-show";
+    /** Marker is hidden when it collides with a higher-priority marker. */
+    readonly HIDE_BY_PRIORITY: "hide-by-priority";
+    /** Marker is minimised to a simple point/circle when colliding with a higher-priority marker. */
+    readonly MINIMIZE_BY_PRIORITY: "minimize-by-priority";
+};
+export type CollisionBehaviour = (typeof CollisionBehaviour)[keyof typeof CollisionBehaviour];
+export type Vector2 = [number, number];
+/**
+ * Kind of spatial collision between two markers.
+ * - `overlap` — the markers' boxes intersect.
+ * - `proximity` — the boxes are within the configured proximity padding
+ *   (a superset of `overlap`).
+ */
+export type MarkerCollisionKind = "overlap" | "proximity";
+/**
+ * Payload of the `markeroverlap` / `markerproximity` events.
+ *
+ * Emitted on state change only: a marker fires when counterparts *enter* or
+ * *exit* collision with it, never for collisions that persist unchanged
+ * between passes.
+ */
+export type MarkerCollisionEventData = {
+    kind: MarkerCollisionKind;
+    /** Markers that started colliding with this marker in this pass. */
+    entered: Marker[];
+    /** Markers that stopped colliding with this marker in this pass (may already be removed from the map). */
+    exited: Marker[];
+    /** All markers currently colliding with this marker. */
+    current: Marker[];
+};
+/**
+ * Sets of mutually-colliding markers from the latest detection pass —
+ * connected components of the pairwise collision graph, with no
+ * winner/loser resolution applied.
+ */
+export type MarkerCollisionGroups = {
+    overlap: Marker[][];
+    proximity: Marker[][];
+};
+/**
+ * How precisely marker collision boxes track rotation.
+ * - `high` (default) — rotated markers are tested with their actual rotated
+ *   box (separating-axis test), so collisions match the rendered footprint.
+ * - `low` — rotated markers are tested with the upright box enclosing the
+ *   rotated one. Cheaper per pair, but over-reports collisions for elongated
+ *   markers at strong rotations (never misses a real one).
+ */
+export type MarkerCollisionAccuracy = "low" | "high";
+/** Per-map configuration of the marker collision engine. */
+export type MarkerCollisionOptions = {
+    /** Distance in CSS px within which two markers count as "in proximity". Overlap always uses 0. */
+    proximityPadding?: number;
+    /** Collision box accuracy for rotated markers. Defaults to `high`. */
+    accuracy?: MarkerCollisionAccuracy;
+    /**
+     * Default collision behaviour for every marker on the map. A marker's own
+     * `collisionBehaviour` option overrides it. Defaults to `always-show`
+     * (nothing is ever hidden until a behaviour is opted into).
+     */
+    behaviour?: CollisionBehaviour;
+    /**
+     * Duration in milliseconds of the hide/show/minimize fade transition
+     * markers go through under collision behaviours. Defaults to `150`.
+     */
+    transitionDuration?: number;
+    /**
+     * CSS easing function for the fade transition (e.g. `"ease"`,
+     * `"ease-in-out"`, `"linear"`, or a `cubic-bezier(...)` expression).
+     * Defaults to `"ease"`.
+     */
+    transitionEasing?: string;
+};
+/**
+ * How the collision engine is currently displaying a marker.
+ * - `visible` — displayed normally.
+ * - `hidden` — hidden because it lost to a higher-priority marker
+ *   (`hide-by-priority`), or sits outside the viewport (off-screen markers
+ *   are excluded from collision processing and hidden regardless of
+ *   behaviour).
+ * - `minimized` — displayed as its minimized variant (`minimize-by-priority`).
+ */
+export type MarkerCollisionDisplayState = "visible" | "hidden" | "minimized";
+/**
+ * Visual overrides applied while a `minimize-by-priority` marker is
+ * minimized. Merged over the default minimized appearance (`{ size: "xs" }`,
+ * which renders the marker as a small dot in its own colours). The marker's
+ * regular values are restored when it un-minimizes.
+ *
+ * Only affects markers built by the SVG system — markers constructed with a
+ * custom `element` minimize to a plain dot, of which only the colour fields
+ * apply (consumed as CSS custom properties).
+ */
+export type MarkerMinimizedOptions = Pick<MapTilerMarkerBaseOptions, "shape" | "size" | "innerColor" | "outerColor" | "contentColor" | "outline" | "outlineColor" | "shadow" | "opacity">;
+/**
+ * MapLibre-style expression that resolves to a numeric priority.
+ * Evaluated by the collision engine, not applied directly to the DOM.
+ */
+export type MarkerPriorityExpression = unknown[];
+/**
+ * What {@link Marker.setAltitude}'s meters are measured from.
+ * - `ground` (default) — above the terrain surface under the marker's
+ *   lngLat, via `map.queryTerrainElevation()`. Falls back to the flat
+ *   mercator plane (sea level) when terrain isn't enabled/loaded — so this
+ *   is a safe default whether or not the map has terrain.
+ * - `sea` — above sea level / the flat mercator plane outright, ignoring
+ *   terrain entirely, even when it's enabled.
+ * @experimental
+ */
+export type AltitudeReference = "ground" | "sea";
+/**
+ * Options for {@link Marker.setAltitude}.
+ * @experimental
+ */
+export type SetAltitudeOptions = {
+    /** What the altitude is measured from. Defaults to `"ground"`. */
+    relativeTo?: AltitudeReference;
+};
+/**
+ * Configures the optional dashed line from a marker down (or up) to its ground point. Off by default — see {@link Marker.setGroundLine}.
+ * @experimental
+ */
+export type GroundLineOptions = {
+    /**
+     * Extra class applied to the ground-line element alongside the default
+     * `maptiler-marker-groundline`. Style colour/width/dashing from your own
+     * stylesheet using either selector — the line carries no inline colour so
+     * your CSS always wins (see the `:where()`-scoped default in the SDK
+     * stylesheet, kept at zero specificity for exactly this reason).
+     */
+    className?: string;
+};
+/**
+ * Predefined `enter` animation types.
+ * - `fade` — opacity only.
+ * - `grow` — uniform scale from nothing, plus fade.
+ * - `pop` — uniform scale from nothing with a springy overshoot, plus fade.
+ * - `drop` — slides straight down into place, plus fade.
+ * - `bounce` — slides down into place with a bounce-settle, fully opaque throughout.
+ *
+ * See `marker-animation-presets.ts` for each preset's exact motion/easing config.
+ */
+export type EnterAnimationPreset = "grow" | "drop" | "pop" | "bounce" | "fade";
+/**
+ * Predefined `exit` animation types.
+ * - `fade` — opacity only.
+ * - `shrink` — uniform scale to nothing, fully opaque throughout.
+ * - `pop` — scale to nothing combined with a fade, springy overshoot.
+ * - `explode` — scales up (2x) while fading out.
+ *
+ * See `marker-animation-presets.ts` for each preset's exact motion/easing config.
+ */
+export type ExitAnimationPreset = "shrink" | "fade" | "pop" | "explode";
+/**
+ * Predefined `idle` animation types — each loops a single channel out and
+ * back to rest once per iteration, peaking at the midpoint (`delta` `0.5`).
+ * - `pulsescale` — scales up and back down, ~1 cycle/second by default.
+ * - `pulseopacity` — dims and back to full opacity, ~1 cycle/second by default.
+ * - `ring` — a rotational shake (several alternating wiggles) clustered around the midpoint, every few seconds by default.
+ * - `bounce` — a vertical hop clustered around the midpoint, every few seconds by default.
+ *
+ * See `marker-animation-presets.ts` for each preset's exact keyframe config.
+ */
+export type IdleAnimationPreset = "pulsescale" | "ring" | "pulseopacity" | "bounce";
+/** Fields shared by every enter/exit/idle animation spec, whether preset-based or {@link MarkerCustomAnimationOptions}. */
+export type MarkerAnimationBase = {
+    /** Overrides the preset's default easing. Defaults to `"Linear"`. Also applies to a `custom` animation's `alpha`. */
+    easing?: EasingFunctionName;
+    /** Duration in milliseconds. Defaults to `1000`. */
+    duration?: number;
+    /** Delay before the animation starts, in milliseconds. Defaults to `0`. */
+    delay?: number;
+};
+/** Configures a marker's `enter`/`exit`/`idle` animation via a predefined preset. */
+export type MarkerPresetAnimationOptions<Preset extends string> = MarkerAnimationBase & {
+    /** Predefined animation type. */
+    preset: Preset;
+    custom?: never;
+    /**
+     * Scales the preset's motion from rest (`0`) up to its full designed
+     * displacement (`1`, the default) — values beyond `1` exaggerate it.
+     * Has no effect on presets with no independent "how far" axis.
+     */
+    magnitude?: number;
+};
+/** Configures a marker's `enter`/`exit`/`idle` animation via a custom per-frame callback instead of a preset. */
+export type MarkerCustomAnimationOptions = MarkerAnimationBase & {
+    preset?: never;
+    magnitude?: never;
+    /**
+     * Called every frame with the already-eased progress (`0`–`1`, `easing`
+     * already applied) and the marker being animated. For `enter`, `0` is the
+     * starting (hidden) state and `1` is fully shown; for `exit`, `0` is fully
+     * shown and `1` is the end (hidden) state; for `idle`, `alpha` resets to
+     * `0` at the start of every loop iteration.
+     */
+    custom: (alpha: number, marker: Marker) => void;
+};
+/** Configures a marker's `enter` or `exit` lifecycle animation. */
+export type MarkerAnimationOptions<Preset extends string = EnterAnimationPreset | ExitAnimationPreset> = MarkerPresetAnimationOptions<Preset> | MarkerCustomAnimationOptions;
+/** Configures a marker's `idle` lifecycle animation. */
+export type MarkerIdleAnimationOptions = MarkerAnimationOptions<IdleAnimationPreset> & {
+    /** Number of loop iterations. Omit, or pass `Infinity`, to loop continuously. */
+    iterations?: number;
+};
+/**
+ * Lifecycle animations played as a marker enters, idles on, and exits the map.
+ */
+export type MapTilerMarkerAnimations = {
+    /** Played once the marker is added to a map. */
+    enter?: MarkerAnimationOptions<EnterAnimationPreset>;
+    /**
+     * Played when `remove()` is called. The marker stays on the map, still
+     * receiving updates, until this animation finishes.
+     */
+    exit?: MarkerAnimationOptions<ExitAnimationPreset>;
+    /**
+     * Looped while the marker sits on the map, after `enter` finishes (or
+     * immediately, if no `enter` is configured).
+     */
+    idle?: MarkerIdleAnimationOptions;
+};
+/**
+ * Event fired by a marker's lifecycle animations — `enter`/`exit` fire
+ * `start`/`end` once each; `idle` additionally fires `iteration` once per loop.
+ */
+export type MarkerLifecycleAnimationEventData = {
+    type: "enteranimationstart" | "enteranimationend" | "exitanimationstart" | "exitanimationend" | "idleanimationstart" | "idleanimationiteration" | "idleanimationend";
+    target: Marker;
+    /** The preset configured for the phase that fired this event, or `"custom"` for a {@link MarkerCustomAnimationOptions} animation. */
+    preset: EnterAnimationPreset | ExitAnimationPreset | IdleAnimationPreset | "custom";
+};
+/** Marker properties that can be eased from their old value to a new one instead of snapping. */
+export type MarkerTransitionProperty = "position" | "scale" | "rotation" | "outerColor" | "innerColor" | "contentColor" | "outlineColor";
+/**
+ * Configures how a transitionable property eases to a newly-set value.
+ * `[duration, easing?, delay?]`, all in milliseconds except `easing`.
+ * `easing` is any {@link EasingFunctionName}, defaulting to `"Linear"` when omitted.
+ * Defaults to no delay when omitted.
+ */
+export type MarkerTransitionSpec = [duration: number, easing?: EasingFunctionName, delay?: number];
+/** Per-property transition configuration, keyed by {@link MarkerTransitionProperty}. */
+export type MapTilerMarkerTransitions = Partial<Record<MarkerTransitionProperty, MarkerTransitionSpec>>;
+/**
+ * Event fired by a marker's `transitionstart` / `transitionend` — the same
+ * shape as MapLibre's own marker events (`type`, `target`), plus `props`.
+ */
+export type MarkerTransitionEventData = {
+    type: "transitionstart" | "transitionend";
+    target: Marker;
+    /**
+     * The property being transitioned, keyed to its value at the time of the
+     * event — the value it's easing from on `transitionstart`, the value it
+     * reached on `transitionend`.
+     */
+    props: Partial<Record<MarkerTransitionProperty, unknown>>;
+};
+/**
+ * Marker content driven by a built-in icon, drawn in the content colour and
+ * sized to the marker (16 / 12 / 8 px for `l` / `m` / `s`; `xs` shows no content).
+ */
+export type MarkerContentTypeIcon = {
+    /** Name of a built-in icon. */
+    icon: MapTilerMarkerIcon;
+    url?: never;
+    template?: never;
+    templateParams?: never;
+    element?: never;
+};
+/** Marker content driven by an image or SVG URL. */
+export type MarkerContentTypeImageUrl = {
+    /** URL of an image or SVG to render as marker content. */
+    url: string;
+    icon?: never;
+    template?: never;
+    templateParams?: never;
+    element?: never;
+};
+/** Marker content driven by a named template and its parameters. */
+export type MarkerContentTypeTemplate = {
+    /** Identifier for a registered template factory function. */
+    template: string;
+    /** Parameters forwarded to the template config function. */
+    templateParams?: Record<string, number | string>;
+    icon?: never;
+    url?: never;
+    element?: never;
+};
+/**
+ * Marker content driven by an existing DOM or SVG element.
+ * Useful when content is managed by a rendering engine such as React.
+ */
+export type MarkerContentTypeElement = {
+    /** An HTML or SVG element to use as marker content. */
+    element: HTMLElement | SVGElement;
+    icon?: never;
+    url?: never;
+    template?: never;
+    templateParams?: never;
+};
+/** Marker with no explicit content — uses the default marker appearance. */
+export type MarkerContentTypeNone = {
+    icon?: never;
+    url?: never;
+    template?: never;
+    templateParams?: never;
+    element?: never;
+};
+export type MarkerContent = MarkerContentTypeNone | MarkerContentTypeIcon | MarkerContentTypeImageUrl | MarkerContentTypeTemplate | MarkerContentTypeElement;
+/** UI "state" types that can restyle a marker. */
+export type MapTilerMarkerUIStateName = "hover" | "focus" | "active" | "dragging";
+/** Property overrides applied while a UI state is active. Keys are any settable marker property (e.g. `shape`, `opacity`, `scale`). */
+export type UIStateSpec = Partial<MapTilerMarkerElementProps>;
+/** Per-state property overrides, keyed by UI state name. */
+export type MapTilerMarkerUIStates = Partial<Record<MapTilerMarkerUIStateName, UIStateSpec>>;
+export type MapTilerMarkerBaseOptions = Omit<MarkerOptions, "scale" | "opacity" | "opacityWhenCovered" | "color"> & {
+    /** Position of the marker. Can also be set later with `setLngLat()`. */
+    lngLat?: LngLatLike;
+    /** Visual shape of the marker body. Defaults to `"maptiler"`. */
+    shape?: MapTilerMarkerShape;
+    /** Size of the marker. */
+    size?: MapTilerMarkerSize;
+    /**
+     * Fill colour of the inner area of the marker. Defaults to a colour chosen
+     * for the current map style, re-resolved whenever the style changes.
+     * Setting it explicitly makes the colour static.
+     */
+    innerColor?: string;
+    /** Fill colour of the outer area (body/border) of the marker. Defaults to the current map style's colour, like `innerColor`. */
+    outerColor?: string;
+    /** Colour applied to the marker content (icon, text, etc.). Defaults to the current map style's colour, like `innerColor`. */
+    contentColor?: string;
+    /** Outline width in pixels. Pass `true` to use the default width. */
+    outline?: true | number;
+    /** Colour of the marker outline. Defaults to the current map style's colour, like `innerColor`. */
+    outlineColor?: string;
+    /** Drop-shadow intensity. Defaults per size: `"strong"` at `l`, `"medium"` at `m`, `"soft"` at `s` and `xs`; use `"none"` to disable. */
+    shadow?: MapTilerMarkerShadow;
+    opacity?: number;
+    opacityWhenCovered?: number;
+    /**
+     * Optional marker name, added as a CSS class on the marker element.
+     * Must be safe for use as a CSS class name.
+     */
+    name?: string;
+    /** Applied to the `title` attribute of the marker's root element (native tooltip). */
+    title?: string;
+    /** Text content rendered inside the marker body. */
+    content?: string;
+    /** HTML attributes applied directly to the marker's root element. */
+    htmlAttributes?: Record<string, number | string>;
+    /** 2-D scale of the marker as `[x, y]`. Defaults to `[1, 1]`. */
+    scale?: Vector2;
+    /** Initial visibility of the marker. Defaults to `true`. TODO: not implemented yet. */
+    visible?: boolean;
+    /** Rendering priority used for collision detection. Accepts a numeric value or a MapLibre-style expression. */
+    priority?: number | MarkerPriorityExpression;
+    /** Lifecycle animations played as the marker enters, idles on, and exits the map. */
+    animations?: MapTilerMarkerAnimations;
+    /**
+     * Per-property easing applied when a transitionable property (`position`,
+     * `scale`, `rotation`, or a colour) is next set, instead of the change
+     * snapping immediately. See {@link setTransitionForProperty}.
+     */
+    transitions?: MapTilerMarkerTransitions;
+    /** Arbitrary user-defined data attached to the marker instance. */
+    userData?: Record<string, unknown>;
+    /** Behaviour when this marker spatially overlaps another. Overrides the map-level default (see `MarkerCollisionOptions`). */
+    collisionBehaviour?: CollisionBehaviour;
+    /**
+     * Visual overrides applied while the marker is minimized by the
+     * `minimize-by-priority` collision behaviour. Merged over the default
+     * minimized appearance (`{ size: "xs" }`).
+     */
+    minimizedOptions?: MarkerMinimizedOptions;
+    /** When `true`, renders a debug overlay showing the marker's bounding box and center point. */
+    debug?: boolean;
+    /**
+     * Collision detection radius in pixels.
+     * `0` means the marker's bounding box is used.
+     */
+    collisionRadius?: number;
+    /**
+     * Per-state property overrides applied while the marker is hovered,
+     * focused, active (pointer down), or being dragged.
+     */
+    states?: MapTilerMarkerUIStates;
+};
+/**
+ * Subset of {@link MapTilerMarkerBaseOptions} that applies when an external
+ * DOM/SVG element is supplied as marker content.  SVG-only layout fields
+ * (`shape`, `size`) are omitted because they only affect SVG generation.
+ * Color/shadow options are retained — they are applied as CSS custom properties
+ * on the supplied element and can be consumed by its styles.
+ */
+export type MapTilerMarkerBehaviourOptions = Omit<MapTilerMarkerBaseOptions, "shape" | "size">;
+/** Options for a marker whose content is a pre-built DOM/SVG element. */
+export type MapTilerMarkerElementOptions = MapTilerMarkerBehaviourOptions & MarkerContentTypeElement;
+/** Options for a marker whose content is generated from the built-in SVG system. */
+export type MapTilerMarkerSVGOptions = MapTilerMarkerBaseOptions & Exclude<MarkerContent, MarkerContentTypeElement>;
+type MapTilerMarkerElementPropKeys = "shape" | "outerColor" | "innerColor" | "contentColor" | "outline" | "outlineColor" | "shadow" | "opacity" | "title" | "content" | "htmlAttributes" | "rotation" | "scale" | "size" | "debug" | "priority";
+export type MapTilerMarkerElementProps = Pick<MapTilerMarkerBaseOptions, MapTilerMarkerElementPropKeys>;
+export type MapTilerMarkerOptions = MapTilerMarkerBaseOptions & MarkerContent;
+/**
+ * Batch of property updates waiting to be flushed to the DOM.
+ * A key being present (even with an `undefined` value) means "apply this
+ * property" — e.g. `{ shadow: undefined }` resets the shadow to its default.
+ */
+export type PendingMarkerUpdates = Partial<MapTilerMarkerElementProps>;
+/** Options for `map.removeMarker()` and `map.removeMarkers()`. */
+export type RemoveMarkerOptions = {
+    /** Removes the markers straight away, without playing their `exit` animation. Defaults to `false`. */
+    immediate?: boolean;
+};
+/**
+ * Shape of an event fired by the SDK `Marker` on top of the MapLibre events,
+ * with the properties passed to `fire(type, properties)` merged in.
+ */
+type SDKMarkerEvent<TType extends string, TProps extends object = object> = EventML<TType> & {
+    target: Marker;
+} & TProps;
+type LifecycleAnimationEvent<TType extends MarkerLifecycleAnimationEventData["type"]> = SDKMarkerEvent<TType, Pick<MarkerLifecycleAnimationEventData, "preset">>;
+/**
+ * Events fired by the MapTiler SDK `Marker` in addition to the MapLibre ones.
+ */
+export type MaptilerMarkerEventType = {
+    markeroverlap: SDKMarkerEvent<"markeroverlap", MarkerCollisionEventData>;
+    markerproximity: SDKMarkerEvent<"markerproximity", MarkerCollisionEventData>;
+    transitionstart: SDKMarkerEvent<"transitionstart", Pick<MarkerTransitionEventData, "props">>;
+    transitionend: SDKMarkerEvent<"transitionend", Pick<MarkerTransitionEventData, "props">>;
+    enteranimationstart: LifecycleAnimationEvent<"enteranimationstart">;
+    enteranimationend: LifecycleAnimationEvent<"enteranimationend">;
+    exitanimationstart: LifecycleAnimationEvent<"exitanimationstart">;
+    exitanimationend: LifecycleAnimationEvent<"exitanimationend">;
+    idleanimationstart: LifecycleAnimationEvent<"idleanimationstart">;
+    idleanimationiteration: LifecycleAnimationEvent<"idleanimationiteration">;
+    idleanimationend: LifecycleAnimationEvent<"idleanimationend">;
+};
+/**
+ * All the events that can be listened to on a MapTiler SDK `Marker`: the MapLibre ones plus the SDK ones.
+ * MapLibre's `on`/`once`/`off` only accept the keys of `MarkerEventType`,
+ * so the SDK `Marker` overrides them to accept its own events as well.
+ */
+export type MarkerEventTypeSDK = MarkerEventType & MaptilerMarkerEventType;