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

package/dist/Map.d.ts

@@ -1,13 +1,15 @@
-import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions, ProjectionSpecification, FlyToOptions, EaseToOptions, FitBoundsOptions, AnimationOptions, LngLatBoundsLike, LngLatLike } from 'maplibre-gl';
+import { Map as MapMLGL, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions, ProjectionSpecification, FlyToOptions, EaseToOptions, FitBoundsOptions, AnimationOptions, LngLatBoundsLike, LngLatLike, AllPaintProperties, AllLayoutProperties, MapEventType, MapLayerEventType, Listener, Subscription, TerrainSpecification, Event as EventML } from 'maplibre-gl';
 import { ReferenceMapStyle, MapStyleVariant } from '@maptiler/client';
 import { SdkConfig } from './config';
 import { LanguageInfo } from './language';
+import { AdaptiveColorSet } from './adaptive-colors';
 import { MinimapOptionsInput } from './controls/Minimap';
 import { PreloadTilesForBoundsOptions, PreloadTilesForCameraPositionsOptions, PreloadTilesOptions, WithTilePreload } from './tile-preloading/types';
 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;
@@ -16,6 +18,45 @@ export type LoadWithTerrainEvent = {
         exaggeration: number;
     };
 };
+/**
+ * Shape of an event fired by the SDK on top of the MapLibre events,
+ * with the properties passed to `fire(type, properties)` merged in.
+ */
+type SDKMapEvent<TType extends string, TProps extends object = object> = EventML<TType> & {
+    target: Map;
+} & TProps;
+/**
+ * Events fired by the MapTiler SDK `Map` in addition to the MapLibre ones.
+ */
+export type MaptilerMapEventType = {
+    /** Fired once the map style and the SDK controls are ready */
+    ready: SDKMapEvent<"ready">;
+    /** Fired once the map is loaded and the terrain (if any) is ready */
+    loadWithTerrain: LoadWithTerrainEvent;
+    /** Fired when the WebGL context is lost unexpectedly (i.e. not after `map.remove()`) */
+    webglContextLost: SDKMapEvent<"webglContextLost">;
+    terrainAnimationStart: SDKMapEvent<"terrainAnimationStart", {
+        terrain: TerrainSpecification | null;
+    }>;
+    terrainAnimationStop: SDKMapEvent<"terrainAnimationStop", {
+        terrain: TerrainSpecification | null;
+    }>;
+    "projection.change": SDKMapEvent<"projection.change", {
+        projection: ProjectionSpecification;
+    }>;
+    "cubemaplayer:animateindone": SDKMapEvent<"cubemaplayer:animateindone", Partial<CubemapLayer>>;
+    "cubemaplayer:animateoutdone": SDKMapEvent<"cubemaplayer:animateoutdone", Partial<CubemapLayer>>;
+    "cubemaplayer:onremove": SDKMapEvent<"cubemaplayer:onremove", Partial<CubemapLayer>>;
+    "radialgradientlayer:animateindone": SDKMapEvent<"radialgradientlayer:animateindone", Partial<RadialGradientLayer>>;
+    "radialgradientlayer:animateoutdone": SDKMapEvent<"radialgradientlayer:animateoutdone", Partial<RadialGradientLayer>>;
+    "radialgradientlayer:onremove": SDKMapEvent<"radialgradientlayer:onremove", Partial<RadialGradientLayer>>;
+};
+/**
+ * All the events that can be listened to on a MapTiler SDK `Map`: the MapLibre ones plus the SDK ones.
+ * Since MapLibre v6.3, `on`/`once`/`off`/`fire` only accept the keys of `MapEventType`,
+ * so the SDK `Map` overrides them to accept its own events as well.
+ */
+export type MapEventTypeSDK = MapEventType & MaptilerMapEventType;
 export declare const GeolocationType: {
     POINT: "POINT";
     COUNTRY: "COUNTRY";
@@ -25,6 +66,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
  */
@@ -157,6 +203,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.
      *
@@ -169,11 +235,6 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo" | "attribut
      * Default: Unless this is set explicitly to false, the SDK version will be logged to the console.
      */
     logSDKVersion?: boolean;
-    /**
-     * Whether to enable the RTL plugin or import a different one.
-     * Default is undefined, which means the plugin is enabled by default.
-     */
-    rtlTextPlugin?: boolean | string;
     /**
      * Whether to enable the experimental tile preloading feature.
      * Default is false.
@@ -202,8 +263,36 @@ export interface ProjectionChangeOptions {
 /**
  * The Map class can be instanciated to display a map in a `<div>`
  */
-export declare class Map extends maplibregl.Map {
+export declare class Map extends MapMLGL {
     readonly telemetry: Telemetry;
+    /**
+     * 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(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(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(type: keyof MapEventTypeSDK, listener: Listener): this;
+    /**
+     * Fires an event. Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
+     */
+    fire(event: MapEventTypeSDK[keyof MapEventTypeSDK]): this;
+    fire(type: keyof MapEventTypeSDK, properties?: object): this;
     private space?;
     private halo?;
     getSpace(): CubemapLayer | undefined;
@@ -261,6 +350,7 @@ export declare class Map extends maplibregl.Map {
     private terrainAnimationDuration;
     private monitoredStyleUrls;
     private styleInProcess;
+    private currentStyleId?;
     private curentProjection;
     private originalLabelStyle;
     private isStyleLocalized;
@@ -310,6 +400,25 @@ export declare class Map extends maplibregl.Map {
      */
     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;
+    /**
+     * Returns the default (adaptive) colours for the current style — the colours
+     * markers fall back to when none are set. Resolved from {@link getStyleId},
+     * or the stylesheet's `id` when that's `undefined`; unknown styles resolve to
+     * the `base` colours.
+     * @returns The current style's colour set. The object is frozen and shared, so spread it to modify a copy.
+     * @example
+     * ```ts
+     * const { innerColor, outerColor } = map.getAdaptiveColorsForCurrentStyle();
+     * ```
+     */
+    getAdaptiveColorsForCurrentStyle(): AdaptiveColorSet;
     /**
      * Adds a [MapLibre style layer](https://maplibre.org/maplibre-style-spec/layers)
      * to the map's style.
@@ -361,6 +470,49 @@ export declare class Map extends maplibregl.Map {
      * ```
      */
     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)
@@ -399,7 +551,7 @@ export declare class Map extends maplibregl.Map {
      * map.setPaintProperty('my-layer', 'fill-color', '#faafee');
      * ```
      */
-    setPaintProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    setPaintProperty<K extends keyof AllPaintProperties>(layerId: string, name: K, value: AllPaintProperties[K], options?: StyleSetterOptions): this;
     /**
      * Sets the value of a layout property in the specified style layer.
      * Layout properties define how the layer is styled.
@@ -413,7 +565,7 @@ export declare class Map extends maplibregl.Map {
      * @param options - Options object.
      * @returns `this`
      */
-    setLayoutProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    setLayoutProperty<K extends keyof AllLayoutProperties>(layerId: string, name: K, value: AllLayoutProperties[K], options?: StyleSetterOptions): this;
     /**
      * Sets the value of the style's glyphs property.
      *
@@ -509,7 +661,11 @@ export declare class Map extends maplibregl.Map {
      */
     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;
     /**
@@ -530,7 +686,7 @@ export declare class Map extends maplibregl.Map {
      * Sets the projection to a {@linkcode ProjectionSpecification}.
      * @param projection - the projection specification to set
      */
-    setProjection(projection: maplibregl.ProjectionSpecification): this;
+    setProjection(projection: ProjectionSpecification): this;
     /**
      * Forget the persisted projection - from both constructor option and result of any `map.setProjection(..., { persist: true })` calls.
      */
@@ -684,3 +840,4 @@ export declare class Map extends maplibregl.Map {
      */
     private resolveCameraPosition;
 }
+export {};