@maptiler/sdk 3.8.0-rc7 → 3.8.0

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

@@ -13,10 +13,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;
@@ -80,6 +101,22 @@ export default class ImageViewer extends Evented {
      * 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>);
     /**
@@ -88,6 +125,7 @@ export default class ImageViewer extends Evented {
      * @returns {Promise<void>}
      */
     onReadyAsync(): Promise<void>;
+    shouldFitImageToViewport: boolean;
     /**
      * Initializes the ImageViewer
      *  - fetches the image metadata
@@ -101,6 +139,15 @@ export default class ImageViewer extends Evented {
      * @returns {Promise<void>}
      */
     private init;
+    /**
+     * Fits the image to the viewport.
+     *
+     * @param {Object} options - The options for the fit image to viewport.
+     * @param {boolean} options.ease - Whether to ease to the viewport bounds.
+     */
+    fitImageToViewport({ ease }?: {
+        ease?: boolean;
+    }): void;
     /**
      * Fetches the image metadata from the API.
      *
@@ -263,32 +310,32 @@ 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.
      */
     setCenter(center: [number, number]): void;
     /**
-     * Set the bearing of the ImageViewer.
+     * Set the bearing of the ImageViewer in degrees.
      *
      * @param {number} bearing - The bearing of the ImageViewer.
      */
     setBearing(bearing: number): void;
     /**
-     * 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.
@@ -296,7 +343,7 @@ export default class ImageViewer extends Evented {
      */
     panBy(delta: PointLike, options?: ImageViewerEaseToOptions, eventData?: any): void;
     /**
-     * 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.

package/dist/src/Map.d.ts

@@ -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): 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;

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

@@ -0,0 +1,13 @@
+import { IControl } from 'maplibre-gl';
+import { ImageViewer } from '../ImageViewer';
+import { Map as MapSDK } from '../Map';
+export declare class ImageViewerFitImageToBoundsControl implements IControl {
+    private viewer;
+    private container;
+    constructor({ imageViewer }: {
+        imageViewer: ImageViewer;
+    });
+    handleClick: () => void;
+    onAdd(_map: MapSDK): HTMLElement;
+    onRemove(): void;
+}

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 };

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

@@ -67,6 +67,12 @@ export declare class RadialGradientLayer implements CustomLayerInterface {
      * @type {Object3D<(typeof ATTRIBUTES_KEYS)[number], (typeof UNIFORMS_KEYS)[number]>}
      */
     private plane?;
+    /**
+     * Whether the halo should be animated in and out.
+     * @private
+     * @type {boolean}
+     */
+    private animationActive;
     /**
      * Creates a new RadialGradientLayer instance.
      *
@@ -128,7 +134,8 @@ export declare class RadialGradientLayer implements CustomLayerInterface {
      * @param {GradientDefinition} gradient - The new gradient definition to set for this layer.
      * @returns {Promise<void>} A promise that resolves when the new gradient is set and animated in.
      */
-    setGradient(gradient: GradientDefinition): Promise<void>;
+    setGradient(gradient: GradientDefinition | boolean): Promise<void>;
+    setAnimationActive(active: boolean): void;
     show(): void;
     hide(): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "3.8.0-rc7",
+  "version": "3.8.0",
   "description": "The Javascript & TypeScript map SDK tailored for MapTiler Cloud",
   "author": "MapTiler",
   "module": "dist/maptiler-sdk.mjs",
@@ -86,14 +86,11 @@
     "vitest": "^3.0.9"
   },
   "dependencies": {
-    "@koa/cors": "^5.0.0",
-    "@koa/router": "^13.1.1",
     "@maplibre/maplibre-gl-style-spec": "~23.3.0",
-    "@maptiler/client": "~2.5.0",
+    "@maptiler/client": "~2.5.1",
     "events": "^3.3.0",
     "gl-matrix": "^3.4.3",
     "js-base64": "^3.7.7",
-    "koa": "^3.0.0",
     "maplibre-gl": "~5.6.0",
     "uuid": "^11.0.5"
   }