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

package/README.md

@@ -1406,6 +1406,182 @@ When defining a new _ramp_, the colors can be an RGB array (`[number, number, nu
 
 Many methods are available on color ramps, such as getting the `<canvas>` element of it, rescaling it, flipping it or [resampling it in a non-linear way](colorramp.md). Read more on [our reference page](https://docs.maptiler.com/sdk-js/api/color-ramp/) and have a look at our [examples](https://docs.maptiler.com/sdk-js/examples/?q=colorramp) to see how they work.
 
+### Markers
+
+The SDK's `Marker` is designed for MapTiler maps. It is built on the MapLibre marker and adds built-in shapes and sizes, colours that follow the active MapTiler style, collision handling, interaction states, transitions and animations.
+
+#### Adding markers
+
+Create a marker, give it a position, and add it through the map. Markers added this way take part in collision handling and follow the style's colours:
+
+```ts
+import { Map, Marker } from "@maptiler/sdk";
+
+const marker = new Marker({ lngLat: [8.54, 47.37], shape: "bubble-circle", size: "m", content: "A1" });
+map.addMarker(marker);
+
+// or straight from options
+map.addMarker({ lngLat: [8.55, 47.38], shape: "circle" });
+map.addMarkers([
+  { lngLat: [8.53, 47.36], shape: "square" },
+  new Marker({ shape: "circle" }).setLngLat([8.56, 47.39]),
+]);
+
+map.getMarker(marker.id);
+map.getMarkers();
+map.removeMarker(marker.id);
+map.removeMarkers(); // all markers, or pass a list of ids
+```
+
+Removing a marker plays its exit animation first, if it has one (see [Animations](#animations)). Pass `{ immediate: true }` to `removeMarker()` or `removeMarkers()` to remove markers straight away.
+
+> [!WARNING]
+> `marker.addTo(map)` is deprecated. It now delegates to `map.addMarker(marker)` and logs a one-time warning. Use `map.addMarker()` instead.
+
+#### Appearance
+
+```ts
+const marker = new Marker({
+  shape: "maptiler", // "circle" | "square" | "bubble-circle" | "bubble-square" | "maptiler" | "maptiler-full"
+  size: "l", // "xs" | "s" | "m" | "l"
+  shadow: "soft", // "none" | "soft" | "medium" | "strong"
+  content: "42", // text shown inside the marker
+  outline: true,
+  scale: [1.2, 1.2],
+  title: "Zurich", // native tooltip
+});
+```
+
+The appearance options have matching setters and getters, such as `setShape()`, `setSize()` or `getContent()`.
+
+Unless you set them, the marker's colours (`innerColor`, `outerColor`, `contentColor` and `outlineColor`) are picked for the current MapTiler style and update when the style changes. A colour you set explicitly stays fixed, and setting it back to `undefined` returns it to the style's colour:
+
+```ts
+marker.setInnerColor("#ff5a1f");
+marker.setInnerColor(undefined); // back to the style's colour
+```
+
+Instead of text, a marker can show an image, or any HTML or SVG element, for example one managed by React:
+
+```ts
+new Marker({ url: "https://example.com/icon.svg" });
+new Marker({ element: myElement });
+```
+
+With `element`, the shape and size options do not apply. The colour and shadow options are set on the element as CSS custom properties, so its own styles can use them.
+
+#### Collisions
+
+By default, markers are always shown even when they overlap. To declutter the map, choose what happens when markers collide. Where markers overlap, the one with the higher `priority` wins:
+
+```ts
+// default for every marker on the map
+map.setMarkerCollisionOptions({ behaviour: "hide-by-priority" });
+
+// or per marker
+new Marker({ priority: 10, collisionBehaviour: "minimize-by-priority" });
+```
+
+- `always-show`: never hidden (the default)
+- `hide-by-priority`: hidden behind a higher-priority marker
+- `minimize-by-priority`: shrinks to a small dot behind a higher-priority marker. `minimizedOptions` changes how the minimized marker looks.
+
+`setMarkerCollisionOptions()` also sets the `proximityPadding` used for `markerproximity` events and the duration and easing of the hide and show fade. `marker.getCollisionDisplayState()` returns `"visible"`, `"hidden"` or `"minimized"`.
+
+Markers fire `markeroverlap` and `markerproximity` when other markers start or stop colliding with them:
+
+```ts
+marker.on("markeroverlap", ({ entered, exited, current }) => {
+  console.log(`${current.length} markers overlap this one`);
+});
+```
+
+#### Interaction states
+
+Change a marker's look while it is hovered, focused, pressed or dragged. The marker returns to its own values when the state ends:
+
+```ts
+const marker = new Marker({
+  draggable: true,
+  states: {
+    hover: { scale: [1.2, 1.2] },
+    active: { shadow: "strong" },
+    dragging: { opacity: 0.6 },
+  },
+});
+
+marker.setUIState("focus", { outline: 3 });
+```
+
+#### Transitions
+
+Ease a property to its new value instead of jumping to it. `position`, `scale`, `rotation` and the four colours can be transitioned, each with `[duration, easing?, delay?]`:
+
+```ts
+const marker = new Marker({
+  transitions: {
+    position: [600, "QuadraticInOut"],
+    innerColor: [300],
+  },
+});
+
+marker.setLngLat([8.6, 47.4]); // glides to the new position
+marker.setTransitionForProperty("scale", [200, "CubicOut"]);
+```
+
+The `transitionstart` and `transitionend` events report the property being transitioned.
+
+#### Animations
+
+Play an animation when a marker is added, loop one while it is on the map, and play another when it is removed:
+
+```ts
+const marker = new Marker({
+  animations: {
+    enter: { preset: "drop" }, // "grow" | "drop" | "pop" | "bounce" | "fade"
+    idle: { preset: "pulsescale", iterations: 3 }, // "pulsescale" | "pulseopacity" | "ring" | "bounce"
+    exit: { preset: "fade", duration: 300 }, // "shrink" | "fade" | "pop" | "explode"
+  },
+});
+
+map.addMarker(marker); // plays "drop"
+map.removeMarker(marker.id); // plays "fade", then removes the marker
+map.removeMarker(marker.id, { immediate: true }); // removes it without the exit animation
+```
+
+Each animation also accepts `duration`, `delay`, `easing` and `magnitude`. Instead of a preset, `custom` takes a function called every frame with the animation's progress (`0` to `1`) and the marker. Animations fire events such as `enteranimationstart`, `idleanimationiteration` and `exitanimationend`.
+
+#### Altitude (experimental)
+
+Raise a marker above the ground. The marker is placed in 3D, so it stays in the right place as the camera moves, with terrain and under globe projection:
+
+```ts
+marker.setAltitude(500); // 500 m above the terrain under the marker
+marker.setAltitude(1200, { relativeTo: "sea" }); // 1200 m above sea level
+marker.setAltitude(false); // back on the map surface
+
+marker.setGroundLine(true); // dashed line from the marker down to the ground
+```
+
+Style the ground line with your own CSS on the `maptiler-marker-groundline` class, or add a class of your own with `setGroundLine(true, { className: "my-line" })`.
+
+#### The MapLibre marker
+
+Compared with the MapLibre marker:
+- The `color` option is removed. Use `innerColor`, `outerColor`, `contentColor` and `outlineColor`.
+- `scale` is a 2D vector, `[x, y]`.
+- `setRotation()` rotates the marker's shape rather than its container.
+
+The plain MapLibre marker is still available as `MarkerMLGL`:
+
+```ts
+import { MarkerMLGL } from "@maptiler/sdk";
+
+new MarkerMLGL({ color: "#f00" }).setLngLat([8.54, 47.37]).addTo(map);
+```
+
+See `demos/16-maptiler-markers.html` to `demos/20-marker-altitude.html` for examples.
+
 ### Camera routes and animations
 
 The SDK comes with several classes to help with animations, particularly route animations.
@@ -1438,7 +1614,8 @@ const marker = new Marker().setLngLat(
     -7.449346225791231,
     39.399728941536836,
   )
-).addTo(map);
+);
+map.addMarker(marker);
 
 // TimeUpdate is fired every frame
 animation.addEventListener(AnimationEventTypes.TimeUpdate, (e) => {

package/dist/ImageViewer/ImageViewer.d.ts

@@ -1,5 +1,6 @@
 import { EaseToOptions, DoubleClickZoomHandler, DragPanHandler, TwoFingersTouchZoomRotateHandler, FlyToOptions, MapOptions, JumpToOptions, ScrollZoomHandler, BoxZoomHandler, KeyboardHandler, CooperativeGesturesHandler, LngLat, PointLike } from '..';
 import { Map } from '../Map';
+import { ImageViewerEventType } from './events';
 import { Evented } from 'maplibre-gl';
 import { ImageViewerFitImageToBoundsControl } from '../controls/ImageViewerFitImageToBoundsControl';
 import { lngLatToPxInternalSymbolKey, pxToLngLatInternalSymbolKey } from './symbols';
@@ -49,7 +50,7 @@ export type ImageMetadata = {
     maxzoom: number;
     tileSize: number;
 };
-export default class ImageViewer extends Evented {
+export default class ImageViewer extends Evented<ImageViewerEventType> {
     /**
      * The UUID of the image.
      *

package/dist/ImageViewer/events.d.ts

@@ -1,16 +1,24 @@
 import { Map } from '../Map';
 import { default as ImageViewer } from './ImageViewer';
-import { LngLat } from 'maplibre-gl';
-export declare class ImageViewerEvent {
-    readonly type: string;
-    readonly target: ImageViewer;
-    readonly originalEvent: MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null;
+import { Event as EventML, LngLat } from 'maplibre-gl';
+type ImageViewerOriginalEvent = MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null;
+export declare class ImageViewerEvent extends EventML<ImageViewerEventTypes> {
+    target: ImageViewer;
+    originalEvent: ImageViewerOriginalEvent;
     [key: string]: any;
     imageX: number;
     imageY: number;
     isOutOfBounds: boolean;
-    constructor(type: string, viewer: ImageViewer, originalEvent?: MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null, data?: Record<string, any>);
+    constructor(type: ImageViewerEventTypes, viewer: ImageViewer, originalEvent?: ImageViewerOriginalEvent, data?: Record<string, any>);
 }
+/** Fired when the viewer fails to load its image. */
+export type ImageViewerInitErrorEvent = EventML<"imagevieweriniterror"> & {
+    error: Error;
+};
+/** Event payloads keyed by event type — every event is an {@link ImageViewerEvent}, apart from the init error. */
+export type ImageViewerEventType = Record<Exclude<ImageViewerEventTypes, "imagevieweriniterror">, ImageViewerEvent> & {
+    imagevieweriniterror: ImageViewerInitErrorEvent;
+};
 declare const BASE_MAP_EVENT_TYPES: readonly ["idle", "render", "load", "remove", "idle"];
 declare const ERROR_EVENTS: readonly ["error"];
 declare const RESIZE_EVENTS: readonly ["resize"];

package/dist/ImageViewer/index.d.ts

@@ -1,5 +1,5 @@
 export { default as ImageViewer } from './ImageViewer';
 export { ImageViewerMarker, ImageViewerMarkerEvent, type ImageViewerMarkerOptions } from './ImageViewerMarker';
-export type { ImageViewerEventTypes } from './events';
+export type { ImageViewerEventTypes, ImageViewerEventType, ImageViewerInitErrorEvent } from './events';
 export type { ImageViewerConstructorOptions, ImageViewerFlyToOptions, ImageViewerJumpToOptions, ImageMetadata } from './ImageViewer';
 export { ImageViewerEvent } from './events';

package/dist/ImageViewer/monkeyPatchML.d.ts

@@ -1,4 +1,4 @@
-import { LngLat, Marker, Point, PositionAnchor, TransformConstrainFunction } from '../index';
+import { LngLat, MarkerMLGL as Marker, Point, PositionAnchor, TransformConstrainFunction } from '../index';
 export declare function unprojectFromWorldCoordinates(worldSize: number, point: Point): LngLat;
 export declare const overpanningUnderzoomingTransformConstrain: TransformConstrainFunction;
 export declare const anchorTranslate: Record<PositionAnchor, string>;

package/dist/Map.d.ts

@@ -8,6 +8,7 @@ import { Telemetry } from './Telemetry';
 import { CubemapDefinition, CubemapLayer, CubemapLayerConstructorOptions } from './custom-layers/CubemapLayer';
 import { GradientDefinition, RadialGradientLayer, RadialGradientLayerConstructorOptions } from './custom-layers/RadialGradientLayer';
 import { StyleSpecificationWithMetaData } from './custom-layers/extractCustomLayerStyle';
+import { MapTilerMarkerOptions, Marker, MarkerCollisionOptions, RemoveMarkerOptions } from '.';
 export type LoadWithTerrainEvent = {
     type: "loadWithTerrain";
     target: Map;
@@ -55,6 +56,25 @@ export type MaptilerMapEventType = {
  * so the SDK `Map` overrides them to accept its own events as well.
  */
 export type MapEventTypeSDK = MapEventType & MaptilerMapEventType;
+/**
+ * An event as an SDK `Map` listener receives it. MapLibre types its events' target as its
+ * own `Map`, which lacks the SDK members, but the target is always the SDK `Map` that fired it.
+ *
+ * The target is intersected in, rather than remapped over every event, so the SDK `Map`'s
+ * `on`/`once`/`off` stay assignable to MapLibre's — the SDK `Map` is passed to MapLibre controls and layers.
+ * @example
+ * ```ts
+ * const onClick = (e: MapEventSDK<"click">) => console.log(e.lngLat, e.target.getSpace());
+ * map.on("click", onClick);
+ * ```
+ */
+export type MapEventSDK<T extends keyof MapEventTypeSDK> = MapEventTypeSDK[T] & object & {
+    target: Map;
+};
+/** A layer event as an SDK `Map` listener receives it — see {@link MapEventSDK}. */
+export type MapLayerEventSDK<T extends keyof MapLayerEventType> = MapLayerEventType[T] & object & {
+    target: Map;
+};
 export declare const GeolocationType: {
     POINT: "POINT";
     COUNTRY: "COUNTRY";
@@ -64,6 +84,11 @@ export declare const GeolocationType: {
  * if falls back to the default Mercator
  */
 export type ProjectionTypes = "mercator" | "globe" | undefined;
+/**
+ * Default zoom at/above which a `"globe"` projection request switches to flat mercator — see
+ * {@link MapOptions.globeMercatorSwitchZoom}.
+ */
+export declare const DEFAULT_GLOBE_MERCATOR_SWITCH_ZOOM = 11;
 /**
  * The {@link AttributionControl} options object
  */
@@ -196,6 +221,26 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo" | "attribut
      * If not provided, the style takes precedence. If provided, overwrite the style.
      */
     projection?: ProjectionTypes;
+    /**
+     * MapLibre's plain `type: "globe"` already resolves to
+     * `["interpolate", ["linear"], ["zoom"], 11, "vertical-perspective", 12, "mercator"]` —
+     * vertical-perspective below zoom 11, linearly blended into flat mercator between 11 and 12.
+     * That blend is a MapLibre bug for anything that places objects via its per-projection model
+     * matrix (marker altitude, `maptiler-3d-js`): the matrix isn't well-defined mid-blend, only
+     * once it's settled fully at one end, so objects placed while zooming through 11-12 jump
+     * around.
+     *
+     * Whenever a projection change resolves to `"globe"` (constructor option, `setProjection`, or
+     * the {@link MaptilerProjectionControl}), the SDK requests
+     * `{ type: ["step", ["zoom"], "vertical-perspective", globeMercatorSwitchZoom, "mercator"] }`
+     * instead of the literal string — spherical below this zoom, flat mercator at and above it,
+     * snapping instantly at the threshold instead of blending across that zoom band.
+     *
+     * Set to `false` to request MapLibre's own `"globe"` literally instead, blend bug and all.
+     *
+     * Default: `11`
+     */
+    globeMercatorSwitchZoom?: number | false;
     /**
      * Turn on/off spacebox.
      *
@@ -242,24 +287,24 @@ export declare class Map extends MapMLGL {
      * Adds a listener for events of a specified type, optionally limited to features in one or more layers.
      * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
      */
-    on<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventType[T] & object) => void): Subscription;
-    on<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventTypeSDK[T] & object) => void): Subscription;
+    on<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventSDK<T>) => void): Subscription;
+    on<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventSDK<T>) => void): Subscription;
     on(type: keyof MapEventTypeSDK, listener: Listener): Subscription;
     /**
      * Adds a listener that will be called only once to a specified event type, optionally limited to features in one or more layers.
      * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
      */
-    once<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventType[T] & object) => void): this;
-    once<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[]): Promise<MapLayerEventType[T] & object>;
-    once<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventTypeSDK[T] & object) => void): this;
-    once<T extends keyof MapEventTypeSDK>(type: T): Promise<MapEventTypeSDK[T] & object>;
+    once<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventSDK<T>) => void): this;
+    once<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[]): Promise<MapLayerEventSDK<T>>;
+    once<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventSDK<T>) => void): this;
+    once<T extends keyof MapEventTypeSDK>(type: T): Promise<MapEventSDK<T>>;
     once(type: keyof MapEventTypeSDK, listener?: Listener): this | Promise<any>;
     /**
      * Removes an event listener previously added with {@link Map.on} or {@link Map.once}.
      * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
      */
-    off<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventType[T] & object) => void): this;
-    off<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventTypeSDK[T] & object) => void): this;
+    off<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventSDK<T>) => void): this;
+    off<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventSDK<T>) => void): this;
     off(type: keyof MapEventTypeSDK, listener: Listener): this;
     /**
      * Fires an event. Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
@@ -323,6 +368,7 @@ export declare class Map extends MapMLGL {
     private terrainAnimationDuration;
     private monitoredStyleUrls;
     private styleInProcess;
+    private currentStyleId?;
     private curentProjection;
     private originalLabelStyle;
     private isStyleLocalized;
@@ -372,6 +418,13 @@ export declare class Map extends MapMLGL {
      */
     setStyle(style: null | ReferenceMapStyle | MapStyleVariant | StyleSpecification | StyleSpecificationWithMetaData | string, options?: StyleSwapOptions & StyleOptions): this;
     private spaceboxLoadingState;
+    /**
+     * Returns the id of the current MapTiler style (e.g. `"streets-v4-dark"`),
+     * derived from the value passed to the constructor or `setStyle`.
+     * `undefined` when the style is a custom `StyleSpecification` or a URL that
+     * doesn't follow the MapTiler Cloud `/maps/<id>/style.json` shape.
+     */
+    getStyleId(): string | undefined;
     /**
      * Adds a [MapLibre style layer](https://maplibre.org/maplibre-style-spec/layers)
      * to the map's style.
@@ -423,6 +476,49 @@ export declare class Map extends MapMLGL {
      * ```
      */
     removeLayer(id: string): this;
+    /**
+     * Adds a marker to the map, registering it for collision handling and style-aware colours.
+     * Plays the marker's `enter` animation, if it has one.
+     * @param markerOrMarkerConfig - A `Marker`, or the options to create one from.
+     */
+    addMarker(markerOrMarkerConfig: Marker | MapTilerMarkerOptions): this;
+    /**
+     * Removes a marker from the map, playing its `exit` animation first, if it has one.
+     * @param id - Id of the marker to remove.
+     * @param options.immediate - Removes the marker straight away, without its `exit` animation.
+     */
+    removeMarker(id: string, options?: RemoveMarkerOptions): this;
+    /**
+     * Adds several markers to the map. See {@link Map.addMarker}.
+     * @param markers - `Marker`s, or the options to create them from.
+     */
+    addMarkers(markers: (Marker | MapTilerMarkerOptions)[]): this;
+    /**
+     * Removes several markers from the map, playing their `exit` animations first, if they have them.
+     * @param markerIds - Ids of the markers to remove. Removes every marker when omitted.
+     * @param options.immediate - Removes the markers straight away, without their `exit` animations.
+     */
+    removeMarkers(markerIds?: string[], options?: RemoveMarkerOptions): this;
+    /** Returns every marker added to the map. */
+    getMarkers(): Marker[];
+    /** Returns the marker with the given id, or `undefined` if it isn't on the map. */
+    getMarker(id: string): Marker | undefined;
+    /**
+     * Configures marker collision detection for this 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 upright box enclosing it,
+     *   which is cheaper per pair but over-reports collisions for rotated
+     *   markers (it never misses a real one).
+     * @param options.behaviour - Default collision behaviour applied to every
+     *   marker on this map (`always-show` | `hide-by-priority` |
+     *   `minimize-by-priority`). 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"`.
+     */
+    setMarkerCollisionOptions(options: MarkerCollisionOptions): this;
     /**
      * Sets the zoom extent for the specified style layer. The zoom extent includes the
      * [minimum zoom level](https://maplibre.org/maplibre-style-spec/layers/#minzoom)
@@ -571,7 +667,11 @@ export declare class Map extends MapMLGL {
      */
     getProjection(): ProjectionSpecification;
     /**
-     * Returns whether a globe projection is currently being used
+     * Returns whether a globe-family projection is currently configured — `"globe"`,
+     * `"vertical-perspective"`, or the `globeMercatorSwitchZoom` step expression this class
+     * requests for `"globe"` (see {@link MapOptions.globeMercatorSwitchZoom}). This reflects the
+     * configured projection, not the instantaneous rendered state — under the step expression it
+     * stays `true` even after zooming past the switch threshold into flat mercator rendering.
      */
     isGlobeProjection(): boolean;
     /**