@maptiler/sdk 3.8.0-rc8 → 3.9.0-rc.1

package/dist/src/ImageViewer/ImageViewer.d.ts

@@ -1,8 +1,10 @@
-import { DoubleClickZoomHandler, DragPanHandler, EaseToOptions, PointLike, TwoFingersTouchZoomRotateHandler, default as MapLibre } from 'maplibre-gl';
-import { FlyToOptions, MapDataEvent, MapOptions, JumpToOptions, ScrollZoomHandler, BoxZoomHandler, KeyboardHandler, CooperativeGesturesHandler } from '..';
+import { default as MaplibreGL } from 'maplibre-gl';
+import { EaseToOptions, DoubleClickZoomHandler, DragPanHandler, TwoFingersTouchZoomRotateHandler, FlyToOptions, MapOptions, JumpToOptions, ScrollZoomHandler, BoxZoomHandler, KeyboardHandler, CooperativeGesturesHandler, LngLat, MapDataEvent, PointLike } from '..';
 import { Map } from '../Map';
+import { ImageViewerFitImageToBoundsControl } from '../controls/ImageViewerFitImageToBoundsControl';
+import { lngLatToPxInternalSymbolKey, pxToLngLatInternalSymbolKey, sdkSymbolKey } from './symbols';
+declare const Evented: typeof MaplibreGL.Evented;
 export type AllowedConstrcutorOptions = "container" | "apiKey" | "maxZoom" | "minZoom" | "zoom" | "bearing";
-declare const Evented: typeof MapLibre.Evented;
 export type ImageViewerFlyToOptions = Omit<FlyToOptions, "pitch"> & {
     center: [number, number];
 };
@@ -13,12 +15,31 @@ export type ImageViewerEaseToOptions = Omit<EaseToOptions, "pitch"> & {
     center: [number, number];
 };
 export type ImageViewerConstructorOptions = Pick<MapOptions, AllowedConstrcutorOptions> & {
+    /**
+     * The UUID of the image.
+     */
     imageUUID: string;
+    /**
+     * Whether to show debug information.
+     */
     debug?: boolean;
+    /**
+     * The center of the image.
+     */
     center?: [number, number];
+    /**
+     * Whether to show a control to fit the image to the viewport.
+     */
     fitToBoundsControl?: boolean;
+    /**
+     * Whether to show a navigation control.
+     */
     navigationControl?: boolean;
 };
+/**
+ * The metadata of the image. This is the shape of the response from the API.
+ * And used to convert px to lnglat and vice versa.
+ */
 export type ImageMetadata = {
     id: string;
     description: string;
@@ -45,7 +66,6 @@ export default class ImageViewer extends Evented {
     /**
      * The metadata of the image.
      *
-     * @internal
      */
     private imageMetadata?;
     /**
@@ -55,7 +75,7 @@ export default class ImageViewer extends Evented {
      * We do not want to have to extend the Map class and give access to
      * methods and properties that operate in LngLat space.   *
      */
-    private sdk;
+    [sdkSymbolKey]: Map;
     /**
      * The options for the ImageViewer.
      *
@@ -78,10 +98,30 @@ export default class ImageViewer extends Evented {
      * The version of the ImageViewer / SDK.
      */
     get version(): string;
+    /**
+     * The control to fit the image to the viewport.
+     */
+    fitToBoundsControlInstance: ImageViewerFitImageToBoundsControl;
     /**
      * The constructor for the ImageViewer.
      *
      * @param {Partial<ImageViewerConstructorOptions>} imageViewerConstructorOptions - The options for the ImageViewer.
+     * @example
+     * ```ts
+     * import "@maptiler/sdk/dist/maptiler-sdk.css"; // import css
+     * import { ImageViewer } from "@maptiler/sdk"; // import the sdk
+     *
+     * const imageViewer = new ImageViewer({
+     *   container: document.getElementById("map"),
+     *   imageUUID: "01986025-ceb9-7487-9ea6-7a8637dcc1a1",
+     *   debug: true, // show tile boundaries, padding, collision boxes etc
+     *   fitToBoundsControl: true, // show a control to fit the image to the viewport
+     *   navigationControl: true, // show a navigation control
+     *   center: [0, 0], // center in pixels
+     *   zoom: 1, // zoom level
+     *   bearing: 0, // bearing
+     * });
+     * ```
      */
     constructor(imageViewerConstructorOptions: Partial<ImageViewerConstructorOptions>);
     /**
@@ -253,21 +293,24 @@ export default class ImageViewer extends Evented {
      *
      * @param {ImageViewerFlyToOptions} options - The options for the fly to.
      * @param {MapDataEvent} eventData - The event data.
+     * @returns {ImageViewer} The ImageViewer instance.
      */
-    flyTo(options: ImageViewerFlyToOptions, eventData?: MapDataEvent): Map;
+    flyTo(options: ImageViewerFlyToOptions, eventData?: MapDataEvent): this;
     /**
      * Jump to a given center.
      *
      * @param {ImageViewerJumpToOptions} options - The options for the jump to.
      * @param {MapDataEvent} eventData - The event data.
+     * @returns {ImageViewer} The ImageViewer instance.
      */
-    jumpTo(options: ImageViewerJumpToOptions, eventData?: MapDataEvent): Map;
+    jumpTo(options: ImageViewerJumpToOptions, eventData?: MapDataEvent): this;
     /**
      * Set the zoom level.
      *
      * @param {number} zoom - The zoom level.
+     * @returns {ImageViewer} The ImageViewer instance.
      */
-    setZoom(zoom: number): void;
+    setZoom(zoom: number): this;
     /**
      * Get the zoom level.
      *
@@ -275,45 +318,78 @@ export default class ImageViewer extends Evented {
      */
     getZoom(): number;
     /**
-     * Get the center of the ImageViewer.
+     * Get the center of the ImageViewer in pixels.
      *
      * @internal
      * @returns {[number, number]} The center of the ImageViewer.
      */
     getCenter(): [number, number];
     /**
-     * Set the center of the ImageViewer.
+     * Set the center of the ImageViewer in pixels.
      *
      * @param {number} center - The center of the ImageViewer.
+     * @returns {ImageViewer} The ImageViewer instance.
      */
-    setCenter(center: [number, number]): void;
+    setCenter(center: [number, number]): this;
     /**
-     * Set the bearing of the ImageViewer.
+     * Set the bearing of the ImageViewer in degrees.
      *
      * @param {number} bearing - The bearing of the ImageViewer.
+     * @returns {ImageViewer} The ImageViewer instance.
      */
-    setBearing(bearing: number): void;
+    setBearing(bearing: number): this;
     /**
-     * Get the bearing of the ImageViewer.
+     * Get the bearing of the ImageViewer in degrees.
      *
      * @returns {number} The bearing of the ImageViewer.
      */
     getBearing(): number;
     /**
-     * Pan by a given delta.
+     * Pan by a given delta in pixels.
      *
      * @param {PointLike} delta - The delta to pan by.
      * @param {ImageViewerEaseToOptions} options - The options for the pan.
      * @param {any} eventData - The event data.
+     * @returns {ImageViewer} The ImageViewer instance.
      */
-    panBy(delta: PointLike, options?: ImageViewerEaseToOptions, eventData?: any): void;
+    panBy(delta: PointLike, options?: ImageViewerEaseToOptions, eventData?: any): this;
     /**
-     * Pan to a given center.
+     * Pan to a given center in pixels.
      *
      * @param {number} center - The center to pan to.
      * @param {ImageViewerEaseToOptions} options - The options for the pan.
      * @param {any} eventData - The event data.
+     * @returns {ImageViewer} The ImageViewer instance.
+     */
+    panTo(center: [number, number], options?: ImageViewerEaseToOptions, eventData?: any): this;
+    /**
+     * Get the image metadata.
+     *
+     * @returns {ImageMetadata} The image metadata.
+     */
+    getImageMetadata(): ImageMetadata | undefined;
+    /**
+     * Get the visible bounds of the image in the viewport in imagePixels.
+     * [topLeft, bottomRight]
+     *
+     * @returns {[[number, number], [number, number]]} The visible bounds of the image.
+     */
+    getImageBounds(): number[][];
+    /**
+     * Set the bounds of the image.
+     *
+     * @param {[[number, number], [number, number]]} bounds - The bounds of the image.
+     * @returns {ImageViewer} The ImageViewer instance.
+     */
+    fitImageBounds([tl, br]: [[number, number], [number, number]]): this;
+    /**
+     * Destroys the ImageViewer, removes the map instance and all event listeners. Useful for cleanup.
+     *
+     * @returns {ImageViewer} The ImageViewer instance.
      */
-    panTo(center: [number, number], options?: ImageViewerEaseToOptions, eventData?: any): void;
+    remove(): void;
+    pointIsWithinImageBounds(px: [number, number]): boolean;
+    [lngLatToPxInternalSymbolKey]: (lngLat: LngLat) => [number, number];
+    [pxToLngLatInternalSymbolKey]: (px: [number, number]) => LngLat;
 }
 export {};

package/dist/src/ImageViewer/ImageViewerMarker.d.ts

@@ -0,0 +1,236 @@
+import { Alignment, Subscription, MarkerOptions, PointLike, Popup } from '../index';
+import { default as MapLibreGL } from 'maplibre-gl';
+import { default as ImageViewer } from './ImageViewer';
+declare const Evented: typeof MapLibreGL.Evented;
+export type ImageViewerMarkerOptions = MarkerOptions & {};
+export interface ImageViewerMarkerInterface {
+    on(event: MarkerEventTypes, listener: (e: ImageViewerMarkerEvent) => void): Subscription;
+    off(event: MarkerEventTypes, listener: (e: ImageViewerMarkerEvent) => void): void;
+    fire(event: ImageViewerMarkerEvent): void;
+    getPosition(): [number, number];
+    getOffset(): PointLike;
+    getPitchAlignment(): Alignment;
+    getPopup(): Popup;
+    getRotation(): number;
+    getRotationAlignment(): Alignment;
+    isDraggable(): boolean;
+    remove(): void;
+    removeClassName(className: string): void;
+    setDraggable(draggable: boolean): void;
+    setPosition(px: [number, number]): void;
+    setOffset(offset: PointLike): void;
+    setOpacity(opacity?: string, opacityWhenCovered?: string): void;
+    setPitchAlignment(pitchAlignment: Alignment): void;
+    setPopup(popup: Popup): void;
+    setRotation(rotation: number): void;
+    setRotationAlignment(rotationAlignment: Alignment): void;
+    setSubpixelPositioning(subpixelPositioning: boolean): void;
+    toggleClassName(className: string): void;
+    togglePopup(): void;
+}
+export declare class ImageViewerMarker extends Evented {
+    private viewer;
+    private readonly marker;
+    private readonly position;
+    constructor({ ...markerOptions }: ImageViewerMarkerOptions);
+    /**
+     * Adds the ImageViewerMarker to an instance of ImageViewer.
+     *
+     * @param {ImageViewer} viewer - The instance of ImageViewer to add the ImageViewerMarker to.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    addTo(viewer: ImageViewer): this;
+    /**
+     * Adds a class name to the ImageViewerMarker.
+     *
+     * @param {string} className - The class name to add to the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    addClassName(className: string): this;
+    /**
+     * Gets the element of the ImageViewerMarker.
+     *
+     * @returns {HTMLElement} The element of the ImageViewerMarker.
+     */
+    getElement(): HTMLElement;
+    /**
+     * Gets the position of the ImageViewerMarker.
+     *
+     * @returns {PointLike} The position of the ImageViewerMarker.
+     * @see  [PointLike](https://docs.maptiler.com/sdk-js/api/geography/#pointlike)
+     *
+     */
+    getPosition(): [number, number];
+    /**
+     * Gets the offset of the ImageViewerMarker.
+     *
+     * @returns {PointLike} The offset of the ImageViewerMarker.
+     * @see  [PointLike](https://docs.maptiler.com/sdk-js/api/geography/#pointlike)
+     */
+    getOffset(): MapLibreGL.Point;
+    /**
+     * Gets the pitch alignment of the ImageViewerMarker.
+     *
+     * @returns {Alignment} The pitch alignment of the ImageViewerMarker.
+     * @see  [MapLibreGL.Alignment](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/Alignment/)
+     */
+    getPitchAlignment(): Alignment;
+    /**
+     * Gets the popup of the ImageViewerMarker.
+     *
+     * @returns {Popup} The popup of the ImageViewerMarker.
+     * @see [Popup](https://docs.maptiler.com/sdk-js/api/markers/#popup)
+     */
+    getPopup(): MapLibreGL.Popup;
+    /**
+     * Gets the rotation of the ImageViewerMarker.
+     *
+     * @returns {number} The rotation of the ImageViewerMarker.
+     */
+    getRotation(): number;
+    /**
+     * Gets the rotation alignment of the ImageViewerMarker.
+     *
+     * @returns {Alignment} The rotation alignment of the ImageViewerMarker.
+     * @see  [MapLibreGL.Alignment](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/Alignment/)
+     */
+    getRotationAlignment(): Alignment;
+    /**
+     * Checks if the ImageViewerMarker is draggable.
+     *
+     * @returns {boolean} True if the ImageViewerMarker is draggable, false otherwise.
+     */
+    isDraggable(): boolean;
+    /**
+     * Fires an event on the ImageViewerMarker.
+     *
+     * @param {MarkerEventTypes | Event} event - The event to fire.
+     * @param {Record<string, any>} data - The data to fire the event with.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    fire(event: MarkerEventTypes | Event, data?: Record<string, any>): this;
+    /**
+     * Removes an event listener from the ImageViewerMarker.
+     *
+     * @param {MarkerEventTypes} event - The event to remove the listener from.
+     * @param {ImageViewerMarkerEvent} listener - The listener to remove.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    off(event: MarkerEventTypes, listener: (e: ImageViewerMarkerEvent) => void): this;
+    /**
+     * Adds an event listener to the ImageViewerMarker.
+     *
+     * @param {MarkerEventTypes} event - The event to add the listener to.
+     * @param {ImageViewerMarkerEvent} listener - The listener to add.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    on(event: MarkerEventTypes, listener: (e: ImageViewerMarkerEvent) => void): Subscription;
+    /**
+     * Checks if the ImageViewerMarker is within the image bounds.
+     *
+     * @returns {boolean} True if the ImageViewerMarker is within the image bounds, false otherwise.
+     */
+    isWithinImageBounds(): boolean;
+    /**
+     * Removes the ImageViewerMarker from the ImageViewer and cleans up the event listeners.
+     *
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    remove(): this;
+    /**
+     * Removes a class name from the ImageViewerMarker dom element.
+     *
+     * @param {string} className - The class name to remove from the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    removeClassName(className: string): this;
+    /**
+     * Sets the draggable state of the ImageViewerMarker.
+     *
+     * @param {boolean} draggable - The draggable state of the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    setDraggable(draggable: boolean): this;
+    /**
+     * Sets the position of the ImageViewerMarker.
+     *
+     * @param {[number, number]} px - The position of the ImageViewerMarker in image pixels.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    setPosition(px: [number, number]): this;
+    /**
+     * Sets the offset of the ImageViewerMarker.
+     *
+     * @param {PointLike} offset - The offset of the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    setOffset(offset: PointLike): this;
+    /**
+     * Sets the opacity of the ImageViewerMarker.
+     *
+     * @param {string} opacity - The opacity of the ImageViewerMarker.
+     * @param {string} opacityWhenCovered - The opacity of the ImageViewerMarker when covered.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    setOpacity(opacity?: string, opacityWhenCovered?: string): this;
+    /**
+     * Sets the pitch alignment of the ImageViewerMarker.
+     *
+     * @param {Alignment} pitchAlignment - The pitch alignment of the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     * @see  [MapLibreGL.Alignment](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/Alignment/)
+     */
+    setPitchAlignment(pitchAlignment: Alignment): this;
+    /**
+     * Sets the popup of the ImageViewerMarker.
+     *
+     * @param {Popup} popup - The popup of the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     * @see [Popup](https://docs.maptiler.com/sdk-js/api/markers/#popup)
+     */
+    setPopup(popup: Popup): this;
+    /**
+     * Sets the rotation of the ImageViewerMarker.
+     *
+     * @param {number} rotation - The rotation of the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    setRotation(rotation: number): this;
+    /**
+     * Sets the rotation alignment of the ImageViewerMarker.
+     *
+     * @param {Alignment} rotationAlignment - The rotation alignment of the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     * @see  [MapLibreGL.Alignment](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/Alignment/)
+     */
+    setRotationAlignment(rotationAlignment: Alignment): this;
+    /**
+     * Sets if subpixel positioning is enabled for the ImageViewerMarker.
+     *
+     * @param {boolean} subpixelPositioning - The subpixel positioning of the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    setSubpixelPositioning(subpixelPositioning: boolean): this;
+    /**
+     * Toggles a class name on the ImageViewerMarker dom element.
+     *
+     * @param {string} className - The class name to toggle on the ImageViewerMarker.
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    toggleClassName(className: string): this;
+    /**
+     * Toggles the popup of the ImageViewerMarker.
+     *
+     * @returns {ImageViewerMarker} The ImageViewerMarker instance.
+     */
+    togglePopup(): this;
+}
+declare const MARKER_EVENT_TYPES: readonly ["dragstart", "drag", "dragend"];
+type MarkerEventTypes = (typeof MARKER_EVENT_TYPES)[number];
+export declare class ImageViewerMarkerEvent {
+    readonly type: string;
+    readonly target: ImageViewerMarker;
+    [key: string]: any;
+    constructor(type: MarkerEventTypes, marker: ImageViewerMarker, data: Record<string, any>);
+}
+export {};

package/dist/src/ImageViewer/events.d.ts

@@ -6,6 +6,9 @@ export declare class ImageViewerEvent {
     readonly target: ImageViewer;
     readonly originalEvent: MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null;
     [key: string]: any;
+    imageX: number;
+    imageY: number;
+    isOutOfBounds: boolean;
     constructor(type: string, viewer: ImageViewer, originalEvent?: MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null, data?: Record<string, any>);
 }
 declare const BASE_MAP_EVENT_TYPES: readonly ["idle", "render", "load", "remove", "idle"];
@@ -16,7 +19,7 @@ declare const CAMERA_EVENTS: readonly ["moveend", "movestart", "move", "zoomend"
 declare const UI_EVENTS: readonly ["click", "dblclick", "mousedown", "mouseup", "mousemove", "mouseout", "mouseover", "contextmenu", "touchstart", "touchend", "touchmove", "touchcancel"];
 declare const COOPERATIVE_GESTURE_EVENTS: readonly ["cooperativegestureprevented"];
 declare const DATA_EVENTS: readonly ["data", "dataloading", "sourcedata", "sourcedataloading", "dataabort", "sourcedataabort"];
-export declare const IMAGE_VIEWER_EVENT_TYPES: ("data" | "error" | "load" | "idle" | "remove" | "render" | "resize" | "webglcontextlost" | "webglcontextrestored" | "dataloading" | "sourcedataloading" | "sourcedata" | "dataabort" | "sourcedataabort" | "boxzoomcancel" | "boxzoomstart" | "boxzoomend" | "touchcancel" | "touchmove" | "touchend" | "touchstart" | "click" | "contextmenu" | "dblclick" | "mousemove" | "mouseup" | "mousedown" | "mouseout" | "mouseover" | "movestart" | "move" | "moveend" | "zoomstart" | "zoom" | "zoomend" | "rotatestart" | "rotate" | "rotateend" | "dragstart" | "drag" | "dragend" | "cooperativegestureprevented")[];
+export declare const IMAGE_VIEWER_EVENT_TYPES: ("error" | "load" | "idle" | "remove" | "render" | "resize" | "webglcontextlost" | "webglcontextrestored" | "dataloading" | "data" | "sourcedataloading" | "sourcedata" | "dataabort" | "sourcedataabort" | "boxzoomcancel" | "boxzoomstart" | "boxzoomend" | "touchcancel" | "touchmove" | "touchend" | "touchstart" | "click" | "contextmenu" | "dblclick" | "mousemove" | "mouseup" | "mousedown" | "mouseout" | "mouseover" | "movestart" | "move" | "moveend" | "zoomstart" | "zoom" | "zoomend" | "rotatestart" | "rotate" | "rotateend" | "dragstart" | "drag" | "dragend" | "cooperativegestureprevented")[];
 type BaseMapEventKeys = (typeof BASE_MAP_EVENT_TYPES)[number];
 type UiEventKeys = (typeof UI_EVENTS)[number];
 type CameraEventKeys = (typeof CAMERA_EVENTS)[number];
@@ -25,7 +28,7 @@ type ResizeEventKeys = (typeof RESIZE_EVENTS)[number];
 type WebglContextEventKeys = (typeof WEBGL_CONTEXT_EVENTS)[number];
 type DataEventKeys = (typeof DATA_EVENTS)[number];
 type CooperativeGestureEventKeys = (typeof COOPERATIVE_GESTURE_EVENTS)[number];
-export type ImageViewerEventTypes = BaseMapEventKeys | UiEventKeys | CameraEventKeys | ErrorEventKeys | ResizeEventKeys | WebglContextEventKeys | DataEventKeys | CooperativeGestureEventKeys | "imageviewerready" | "imagevieweriniterror";
+export type ImageViewerEventTypes = BaseMapEventKeys | UiEventKeys | CameraEventKeys | ErrorEventKeys | ResizeEventKeys | WebglContextEventKeys | DataEventKeys | CooperativeGestureEventKeys | "imageviewerready" | "imagevieweriniterror" | "beforeremove";
 type LngLatToPixel = (lngLat: LngLat) => [number, number];
 interface SetupGlobalMapEventForwarderOptions {
     map: Map;

package/dist/src/ImageViewer/index.d.ts

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

package/dist/src/ImageViewer/symbols.d.ts

@@ -0,0 +1,3 @@
+export declare const sdkSymbolKey: unique symbol;
+export declare const lngLatToPxInternalSymbolKey: unique symbol;
+export declare const pxToLngLatInternalSymbolKey: unique symbol;

package/dist/src/Map.d.ts

@@ -1,4 +1,4 @@
-import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions } from 'maplibre-gl';
+import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions, ProjectionSpecification } from 'maplibre-gl';
 import { ReferenceMapStyle, MapStyleVariant } from '@maptiler/client';
 import { SdkConfig } from './config';
 import { LanguageInfo } from './language';
@@ -90,6 +90,10 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo"> & {
      * Show the full screen control. (default: `false`, will show if `true`)
      */
     fullscreenControl?: boolean | ControlPosition;
+    /**
+     * Detect custom external controls. (default: `false`, will detect automatically if `true`)
+     */
+    customControls?: boolean | string;
     /**
      * Display a minimap in a user defined corner of the map. (default: `bottom-left` corner)
      * If set to true, the map will assume it is a minimap and forego the attribution control.
@@ -151,7 +155,33 @@ export declare class Map extends maplibregl.Map {
      * If an option is not set it will internally revert to the default option
      * unless explicitly set when calling.
      */
-    setSpace(space: CubemapDefinition): void;
+    setSpace(space: CubemapDefinition | boolean, updateOptions?: boolean): void;
+    /**
+     * Enables the animations for the space layer.
+     */
+    enableSpaceAnimations(): void;
+    /**
+     * Disables the animations for the space layer.
+     */
+    disableSpaceAnimations(): void;
+    /**
+     * Enables the animations for the halo layer.
+     */
+    enableHaloAnimations(): void;
+    /**
+     * Disables the animations for the halo layer.
+     */
+    disableHaloAnimations(): void;
+    /**
+     * Sets whether the halo layer should be animated in and out.
+     * @param active - Whether the animation should be active.
+     */
+    setHaloAnimationActive(active: boolean): void;
+    /**
+     * Sets whether the space layer should be animated in and out.
+     * @param active - Whether the animation should be active.
+     */
+    setSpaceAnimationActive(active: boolean): void;
     private setSpaceFromStyle;
     private setHaloFromStyle;
     private initSpace;
@@ -409,6 +439,15 @@ export declare class Map extends maplibregl.Map {
      *  map.setTransformRequest((url: string, resourceType: string) => {});
      */
     setTransformRequest(transformRequest: RequestTransformFunction): this;
+    /**
+     * Gets the {@link ProjectionSpecification}.
+     * @returns the projection specification.
+     * @example
+     * ```ts
+     * let projection = map.getProjection();
+     * ```
+     */
+    getProjection(): ProjectionSpecification;
     /**
      * Returns whether a globe projection is currently being used
      */
@@ -421,6 +460,7 @@ export declare class Map extends maplibregl.Map {
      * Activate the mercator projection.
      */
     enableMercatorProjection(): void;
+    setProjection(projection: maplibregl.ProjectionSpecification): this;
     /**
      * Returns `true` is the language was ever updated, meaning changed
      * from what is delivered in the style.

package/dist/src/controls/MaptilerCustomControl.d.ts

@@ -0,0 +1,17 @@
+import { Map as SDKMap } from '../Map';
+import { IControl, MapLibreEvent } from 'maplibre-gl';
+export type MaptilerCustomControlCallback<E> = (map: SDKMap, element: HTMLElement, event: E) => void;
+/**
+ * The MaptilerCustomControl allows any existing element to become a map control.
+ */
+export declare class MaptilerCustomControl implements IControl {
+    #private;
+    /**
+     * @param selectorOrElement Element to be used as control, specified as either reference to element itself or a CSS selector to find the element in DOM
+     * @param onClick Function called when the element is clicked
+     * @param onRender Function called every time the underlying map renders a new state
+     */
+    constructor(selectorOrElement: string | HTMLElement, onClick?: MaptilerCustomControlCallback<Event>, onRender?: MaptilerCustomControlCallback<MapLibreEvent>);
+    onAdd(map: SDKMap): HTMLElement;
+    onRemove(): void;
+}

package/dist/src/controls/MaptilerExternalControl.d.ts

@@ -0,0 +1,25 @@
+import { Map as SDKMap } from '../Map';
+import { IControl } from 'maplibre-gl';
+import { MaptilerCustomControl, MaptilerCustomControlCallback } from './MaptilerCustomControl';
+export type MaptilerExternalControlType = "zoom-in" | "zoom-out" | "toggle-projection" | "toggle-terrain" | "reset-view" | "reset-bearing" | "reset-pitch" | "reset-roll";
+/**
+ * The MaptilerExternalControl allows any existing element to automatically become a map control. Used for detected controls if `customControls` config is turned on.
+ */
+export declare class MaptilerExternalControl extends MaptilerCustomControl implements IControl {
+    #private;
+    static controlCallbacks: Record<MaptilerExternalControlType, MaptilerCustomControlCallback<Event>>;
+    /**
+     * Constructs an instance of External Control to have a predefined functionality
+     * @param controlElement Element to be used as control, specified as reference to element itself
+     * @param controlType One of the predefined types of functionality
+     */
+    constructor(controlElement: HTMLElement, controlType?: MaptilerExternalControlType);
+    onAdd(map: SDKMap): HTMLElement;
+    onRemove(): void;
+    /**
+     * Configure a child element to be part of this control and to have a predefined functionality added
+     * @param controlElement Element that is a descendant of the control element and that optionally should have some functionality
+     * @param controlType One of the predefined types of functionality
+     */
+    configureGroupItem(controlElement: HTMLElement, controlType: MaptilerExternalControlType | undefined): void;
+}

package/dist/src/controls/MaptilerProjectionControl.d.ts

@@ -12,3 +12,4 @@ export declare class MaptilerProjectionControl implements IControl {
     private toggleProjection;
     private updateProjectionIcon;
 }
+export declare function toggleProjection(map: SDKMap): void;

package/dist/src/controls/MaptilerTerrainControl.d.ts

@@ -14,3 +14,4 @@ export declare class MaptilerTerrainControl implements IControl {
     _toggleTerrain(): void;
     _updateTerrainIcon(): void;
 }
+export declare function toggleTerrain(map: SDKMap): void;

package/dist/src/controls/index.d.ts

@@ -1,3 +1,5 @@
+export * from './MaptilerCustomControl';
+export * from './MaptilerExternalControl';
 export * from './MaptilerGeolocateControl';
 export * from './MaptilerLogoControl';
 export * from './MaptilerTerrainControl';

package/dist/src/custom-layers/CubemapLayer/CubemapLayer.d.ts

@@ -96,6 +96,7 @@ declare class CubemapLayer implements CustomLayerInterface {
      * @private
      */
     private options;
+    private animationActive;
     /**
      * Creates a new instance of CubemapLayer
      *
@@ -186,6 +187,7 @@ declare class CubemapLayer implements CustomLayerInterface {
      * @private
      */
     private animateOut;
+    setAnimationActive(active: boolean): void;
     /**
      * Renders the cubemap layer to the WebGL context.
      * This method is called internally during the rendering phase of the map.
@@ -214,7 +216,7 @@ declare class CubemapLayer implements CustomLayerInterface {
      * and if so, it updates the cubemap faces.
      * Finally, it calls `updateCubemap` to apply the changes and trigger a repaint of the map.
      */
-    setCubemap(cubemap: CubemapDefinition): Promise<void>;
+    setCubemap(spec: CubemapDefinition | boolean): Promise<void>;
     /**
      * Shows the cubemap layer by setting its visibility to "visible".
      * This method is used to make the cubemap layer visible on the map.
@@ -226,5 +228,5 @@ declare class CubemapLayer implements CustomLayerInterface {
      */
     hide(): void;
 }
-export declare function validateSpaceSpecification(space: CubemapDefinition | boolean): boolean;
+export declare function validateSpaceSpecification(space?: CubemapDefinition | boolean): boolean;
 export { CubemapLayer };