@maptiler/sdk 3.8.0-rc4 → 3.8.0-rc7

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

@@ -1,16 +1,50 @@
-import { DoubleClickZoomHandler, DragPanHandler, EaseToOptions, PointLike, TwoFingersTouchZoomRotateHandler } from 'maplibre-gl';
+import { DoubleClickZoomHandler, DragPanHandler, EaseToOptions, PointLike, TwoFingersTouchZoomRotateHandler, default as MapLibre } from 'maplibre-gl';
 import { FlyToOptions, MapDataEvent, MapOptions, JumpToOptions, ScrollZoomHandler, BoxZoomHandler, KeyboardHandler, CooperativeGesturesHandler } from '..';
 import { Map } from '../Map';
-import { Evented } from '../';
-type AllowedConstrcutorOptions = "container" | "apiKey" | "maxZoom" | "minZoom" | "zoom" | "bearing";
-type ImageViewerConstructorOptions = Pick<MapOptions, AllowedConstrcutorOptions> & {
+export type AllowedConstrcutorOptions = "container" | "apiKey" | "maxZoom" | "minZoom" | "zoom" | "bearing";
+declare const Evented: typeof MapLibre.Evented;
+export type ImageViewerFlyToOptions = Omit<FlyToOptions, "pitch"> & {
+    center: [number, number];
+};
+export type ImageViewerJumpToOptions = Omit<JumpToOptions, "pitch"> & {
+    center: [number, number];
+};
+export type ImageViewerEaseToOptions = Omit<EaseToOptions, "pitch"> & {
+    center: [number, number];
+};
+export type ImageViewerConstructorOptions = Pick<MapOptions, AllowedConstrcutorOptions> & {
     imageUUID: string;
     debug?: boolean;
     center?: [number, number];
 };
+export type ImageMetadata = {
+    id: string;
+    description: string;
+    attribution: string;
+    width: number;
+    height: number;
+    minzoom: number;
+    maxzoom: number;
+    tileSize: number;
+};
 export default class ImageViewer extends Evented {
+    /**
+     * The UUID of the image.
+     *
+     * @internal
+     */
     private imageUUID;
+    /**
+     * Whether to enable debug mode.
+     *
+     * @internal
+     */
     private debug;
+    /**
+     * The metadata of the image.
+     *
+     * @internal
+     */
     private imageMetadata?;
     /**
      * Why not extend the Map class?
@@ -20,47 +54,254 @@ export default class ImageViewer extends Evented {
      * methods and properties that operate in LngLat space.   *
      */
     private sdk;
+    /**
+     * The options for the ImageViewer.
+     *
+     * @internal
+     */
     private options;
+    /**
+     * The size of the image.
+     *
+     * @internal
+     */
     private imageSize?;
+    /**
+     * The padded size max.
+     *
+     * @internal
+     */
     private paddedSizeMax?;
+    /**
+     * The version of the ImageViewer / SDK.
+     */
     get version(): string;
+    /**
+     * The constructor for the ImageViewer.
+     *
+     * @param {Partial<ImageViewerConstructorOptions>} imageViewerConstructorOptions - The options for the ImageViewer.
+     */
     constructor(imageViewerConstructorOptions: Partial<ImageViewerConstructorOptions>);
+    /**
+     * Waits for the ImageViewer to be ready.
+     *
+     * @returns {Promise<void>}
+     */
     onReadyAsync(): Promise<void>;
-    init(): Promise<void>;
-    fetchImageMetadata(): Promise<void>;
-    addImageSource(): void;
+    /**
+     * Initializes the ImageViewer
+     *  - fetches the image metadata
+     *  - adds the image source to the sdk instance
+     *  - sets the center to the middle of the image (if center is not provided)
+     *  - monkeypatches the maplibre-gl sdk transform method to allow for overpanning and underzooming.
+     *  - sets up global event forwarding / intercepting from the map instance
+     *  - sets the center to the middle of the image (if center is not provided)
+     *
+     * @internal
+     * @returns {Promise<void>}
+     */
+    private init;
+    /**
+     * Fetches the image metadata from the API.
+     *
+     * @internal
+     * @returns {Promise<void>}
+     */
+    private fetchImageMetadata;
+    /**
+     * Adds the image source to the sdk instance.
+     *
+     * @internal
+     * @returns {void}
+     */
+    private addImageSource;
+    /**
+     * Triggers a repaint of the ImageViewer. Same as map.triggerRepaint().
+     *
+     * @internal
+     * @returns {void}
+     */
     triggerRepaint(): void;
+    /**
+     * The scroll zoom handler.
+     *
+     * @internal
+     * @returns {ScrollZoomHandler}
+     */
     get scrollZoom(): ScrollZoomHandler;
+    /**
+     * The scroll zoom handler.
+     *
+     * @internal
+     * @param {ScrollZoomHandler} value - The scroll zoom handler.
+     */
     set scrollZoom(value: ScrollZoomHandler);
+    /**
+     * The box zoom handler.
+     *
+     * @internal
+     * @returns {BoxZoomHandler}
+     */
     get boxZoom(): BoxZoomHandler;
+    /**
+     * The box zoom handler.
+     *
+     * @internal
+     * @param {BoxZoomHandler} value - The box zoom handler.
+     */
     set boxZoom(value: BoxZoomHandler);
+    /**
+     * The drag pan handler.
+     *
+     * @internal
+     * @returns {DragPanHandler}
+     */
     get dragPan(): DragPanHandler;
+    /**
+     * The drag pan handler.
+     *
+     * @internal
+     * @param {DragPanHandler} value - The drag pan handler.
+     */
     set dragPan(value: DragPanHandler);
+    /**
+     * The keyboard handler.
+     *
+     * @internal
+     * @returns {KeyboardHandler}
+     */
     get keyboard(): KeyboardHandler;
+    /**
+     * The keyboard handler.
+     *
+     * @internal
+     * @param {KeyboardHandler} value - The keyboard handler.
+     */
     set keyboard(value: KeyboardHandler);
+    /**
+     * The double click zoom handler.
+     *
+     * @internal
+     * @returns {DoubleClickZoomHandler}
+     */
     get doubleClickZoom(): DoubleClickZoomHandler;
+    /**
+     * The double click zoom handler.
+     *
+     * @internal
+     * @param {DoubleClickZoomHandler} value - The double click zoom handler.
+     */
     set doubleClickZoom(value: DoubleClickZoomHandler);
+    /**
+     * The touch zoom rotate handler.
+     *
+     * @internal
+     * @returns {TwoFingersTouchZoomRotateHandler}
+     */
     get touchZoomRotate(): TwoFingersTouchZoomRotateHandler;
+    /**
+     * The touch zoom rotate handler.
+     *
+     * @internal
+     * @param {TwoFingersTouchZoomRotateHandler} value - The touch zoom rotate handler.
+     */
     set touchZoomRotate(value: TwoFingersTouchZoomRotateHandler);
+    /**
+     * The cooperative gestures handler.
+     *
+     * @internal
+     * @returns {CooperativeGesturesHandler}
+     */
     get cooperativeGestures(): CooperativeGesturesHandler;
+    /**
+     * The cooperative gestures handler.
+     *
+     * @internal
+     * @param {CooperativeGesturesHandler} value - The cooperative gestures handler.
+     */
     set cooperativeGestures(value: CooperativeGesturesHandler);
+    /**
+     * Converts a LngLat to a px coordinate, based on the image metadata.
+     *
+     * @internal
+     * @param {LngLat} lngLat - The LngLat to convert.
+     * @returns {[number, number]} The px coordinate.
+     */
     private lngLatToPx;
+    /**
+     * Converts a px coordinate to a LngLat, based on the image metadata.
+     *
+     * @internal
+     * @param {LngLat} lngLat - The LngLat to convert.
+     * @returns {[number, number]} The px coordinate.
+     */
     private pxToLngLat;
-    flyTo(options: Omit<ImageViewerFlyToOptions, "bearing" | "pitch">, eventData?: MapDataEvent): Map;
-    jumpTo(options: Omit<ImageViewerJumpToOptions, "bearing" | "pitch">, eventData?: MapDataEvent): Map;
+    /**
+     * Fly to a given center.
+     *
+     * @param {ImageViewerFlyToOptions} options - The options for the fly to.
+     * @param {MapDataEvent} eventData - The event data.
+     */
+    flyTo(options: ImageViewerFlyToOptions, eventData?: MapDataEvent): Map;
+    /**
+     * Jump to a given center.
+     *
+     * @param {ImageViewerJumpToOptions} options - The options for the jump to.
+     * @param {MapDataEvent} eventData - The event data.
+     */
+    jumpTo(options: ImageViewerJumpToOptions, eventData?: MapDataEvent): Map;
+    /**
+     * Set the zoom level.
+     *
+     * @param {number} zoom - The zoom level.
+     */
     setZoom(zoom: number): void;
+    /**
+     * Get the zoom level.
+     *
+     * @returns {number} The zoom level.
+     */
     getZoom(): number;
+    /**
+     * Get the center of the ImageViewer.
+     *
+     * @internal
+     * @returns {[number, number]} The center of the ImageViewer.
+     */
     getCenter(): [number, number];
+    /**
+     * Set the center of the ImageViewer.
+     *
+     * @param {number} center - The center of the ImageViewer.
+     */
     setCenter(center: [number, number]): void;
+    /**
+     * Set the bearing of the ImageViewer.
+     *
+     * @param {number} bearing - The bearing of the ImageViewer.
+     */
     setBearing(bearing: number): void;
+    /**
+     * Get the bearing of the ImageViewer.
+     *
+     * @returns {number} The bearing of the ImageViewer.
+     */
     getBearing(): number;
-    panBy(delta: PointLike, options?: EaseToOptions, eventData?: any): void;
-    panTo(center: [number, number], options?: EaseToOptions, eventData?: any): void;
+    /**
+     * Pan by a given delta.
+     *
+     * @param {PointLike} delta - The delta to pan by.
+     * @param {ImageViewerEaseToOptions} options - The options for the pan.
+     * @param {any} eventData - The event data.
+     */
+    panBy(delta: PointLike, options?: ImageViewerEaseToOptions, eventData?: any): void;
+    /**
+     * Pan to a given center.
+     *
+     * @param {number} center - The center to pan to.
+     * @param {ImageViewerEaseToOptions} options - The options for the pan.
+     * @param {any} eventData - The event data.
+     */
+    panTo(center: [number, number], options?: ImageViewerEaseToOptions, eventData?: any): void;
 }
-type ImageViewerFlyToOptions = Omit<FlyToOptions, "bearing" | "pitch"> & {
-    center: [number, number];
-};
-type ImageViewerJumpToOptions = Omit<JumpToOptions, "bearing" | "pitch"> & {
-    center: [number, number];
-};
 export {};

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

@@ -5,10 +5,27 @@ export declare class ImageViewerEvent {
     readonly type: string;
     readonly target: ImageViewer;
     readonly originalEvent: MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null;
-    readonly data?: Record<string, any>;
+    [key: string]: any;
     constructor(type: string, viewer: ImageViewer, originalEvent?: MouseEvent | TouchEvent | WheelEvent | WebGLContextEvent | null, data?: Record<string, any>);
 }
-export declare const ALL_MAP_EVENT_TYPES: string[];
+declare const BASE_MAP_EVENT_TYPES: readonly ["idle", "render", "load", "remove", "idle"];
+declare const ERROR_EVENTS: readonly ["error"];
+declare const RESIZE_EVENTS: readonly ["resize"];
+declare const WEBGL_CONTEXT_EVENTS: readonly ["webglcontextlost", "webglcontextrestored"];
+declare const CAMERA_EVENTS: readonly ["moveend", "movestart", "move", "zoomend", "zoomstart", "zoom", "rotatestart", "rotateend", "rotate", "dragstart", "dragend", "drag", "boxzoomcancel", "boxzoomend", "boxzoomstart"];
+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")[];
+type BaseMapEventKeys = (typeof BASE_MAP_EVENT_TYPES)[number];
+type UiEventKeys = (typeof UI_EVENTS)[number];
+type CameraEventKeys = (typeof CAMERA_EVENTS)[number];
+type ErrorEventKeys = (typeof ERROR_EVENTS)[number];
+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";
 type LngLatToPixel = (lngLat: LngLat) => [number, number];
 interface SetupGlobalMapEventForwarderOptions {
     map: Map;
@@ -17,6 +34,11 @@ interface SetupGlobalMapEventForwarderOptions {
 }
 /**
  * Sets up event forwarding from Map to ImageViewer with proper categorization
+ * @param {SetupGlobalMapEventForwarderOptions} options - The options for setting up the event forwarder.
+ * @param {Map} options.map - The map to forward events from.
+ * @param {ImageViewer} options.viewer - The viewer to forward events to.
+ * @param {LngLatToPixel} options.lngLatToPx - A function to convert LngLat to pixel coordinates.
+ * @returns {void}
  */
 export declare function setupGlobalMapEventForwarder({ map, viewer, lngLatToPx }: SetupGlobalMapEventForwarderOptions): void;
 export {};

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

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

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

@@ -0,0 +1,4 @@
+import { LngLat, Point } from '../index';
+import { Map } from '../Map';
+export declare function unprojectFromWorldCoordinates(worldSize: number, point: Point): LngLat;
+export declare function monkeyPatchMapTransformInstance(instance: Map): void;

package/dist/src/Map.d.ts

@@ -6,6 +6,7 @@ import { MinimapOptionsInput } from './controls/Minimap';
 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';
 export type LoadWithTerrainEvent = {
     type: "loadWithTerrain";
     target: Map;
@@ -153,8 +154,6 @@ export declare class Map extends maplibregl.Map {
     setSpace(space: CubemapDefinition): void;
     private setSpaceFromStyle;
     private setHaloFromStyle;
-    private setSpaceFromCurrentStyle;
-    private setHaloFromCurrentStyle;
     private initSpace;
     private initHalo;
     getHalo(): RadialGradientLayer | undefined;
@@ -219,7 +218,8 @@ export declare class Map extends maplibregl.Map {
      * - a shorthand with only the MapTIler style name (eg. `"streets-v2"`)
      * - a longer form with the prefix `"maptiler://"` (eg. `"maptiler://streets-v2"`)
      */
-    setStyle(style: null | ReferenceMapStyle | MapStyleVariant | StyleSpecification | string, options?: StyleSwapOptions & StyleOptions): this;
+    setStyle(style: null | ReferenceMapStyle | MapStyleVariant | StyleSpecification | StyleSpecificationWithMetaData | string, options?: StyleSwapOptions & StyleOptions): this;
+    private spaceboxLoadingState;
     /**
      * Adds a [MapLibre style layer](https://maplibre.org/maplibre-style-spec/layers)
      * to the map's style.

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

@@ -117,7 +117,9 @@ declare class CubemapLayer implements CustomLayerInterface {
      * It creates a new Object3D instance with the specified vertex and fragment shaders,
      * attributes, and uniforms. The cubemap will be rendered using this configuration.
      */
-    updateCubemap(): void;
+    updateCubemap({ facesNeedUpdate }?: {
+        facesNeedUpdate: boolean;
+    }): void;
     /**
      * Called when the layer is added to the map.
      * Initializes the cubemap and sets up the WebGL context.
@@ -224,4 +226,5 @@ declare class CubemapLayer implements CustomLayerInterface {
      */
     hide(): void;
 }
+export declare function validateSpaceSpecification(space: CubemapDefinition | boolean): boolean;
 export { CubemapLayer };

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

@@ -84,6 +84,12 @@ export declare class RadialGradientLayer implements CustomLayerInterface {
      * @returns void
      */
     onAdd(map: MapSDK, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    /**
+     * Returns the current gradient configuration of the radial gradient layer.
+     *
+     * @returns {GradientDefinition} The current gradient configuration.
+     */
+    getConfig(): GradientDefinition;
     /**
      * Animates the radial gradient into view by gradually scaling from 0 to the target scale.
      *
@@ -126,3 +132,4 @@ export declare class RadialGradientLayer implements CustomLayerInterface {
     show(): void;
     hide(): void;
 }
+export declare function validateHaloSpecification(halo: RadialGradientLayerConstructorOptions | boolean): boolean;

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

@@ -3,3 +3,4 @@ import { CubemapLayer } from './CubemapLayer';
 export { RadialGradientLayer, CubemapLayer };
 export * from './RadialGradientLayer/types';
 export * from './CubemapLayer/types';
+export type { StyleSpecificationWithMetaData } from './extractCustomLayerStyle';

package/dist/src/index.d.ts

@@ -77,8 +77,8 @@ export { MapTouchEvent } from './MLAdapters/MapTouchEvent';
 export { MapMouseEvent } from './MLAdapters/MapMouseEvent';
 export { Map, GeolocationType, type MapOptions, type LoadWithTerrainEvent } from './Map';
 export * from './controls';
-export { type AutomaticStaticMapOptions, type BoundedStaticMapOptions, type BufferToPixelDataFunction, type ByIdGeocodingOptions, type CenteredStaticMapOptions, type CommonForwardAndReverseGeocodingOptions, type CoordinateExport, type CoordinateGrid, type CoordinateId, type CoordinateSearch, type CoordinateSearchResult, type CoordinateTransformResult, type CoordinateTransformation, type Coordinates, type CoordinatesSearchOptions, type CoordinatesTransformOptions, type DefaultTransformation, type ElevationAtOptions, type ElevationBatchOptions, type FeatureHierarchy, type FetchFunction, type GeocodingFeature, type GeocodingOptions, type GeocodingSearchResult, type GeolocationInfoOptions, type GeolocationResult, type GetDataOptions, type LanguageGeocodingOptions, MapStyle, type MapStylePreset, type MapStyleType, MapStyleVariant, type PixelData, ReferenceMapStyle, type ReverseGeocodingOptions, ServiceError, type StaticMapBaseOptions, type StaticMapMarker, type TileJSON, type XYZ, bufferToPixelDataBrowser, circumferenceAtLatitude, coordinates, data, elevation, expandMapStyle, geocoding, geolocation, getBufferToPixelDataParser, getTileCache, mapStylePresetList, math, misc, staticMaps, styleToStyle, type LanguageInfo, areSameLanguages, toLanguageInfo, isLanguageInfo, getAutoLanguage, getLanguageInfoFromFlag, getLanguageInfoFromCode, getLanguageInfoFromKey, } from '@maptiler/client';
-export { default as ImageViewer } from './ImageViewer/ImageViewer';
+export { type AutomaticStaticMapOptions, type BoundedStaticMapOptions, type BufferToPixelDataFunction, type ByIdGeocodingOptions, type CenteredStaticMapOptions, type CommonForwardAndReverseGeocodingOptions, type CoordinateExport, type CoordinateGrid, type CoordinateId, type CoordinateSearch, type CoordinateSearchResult, type CoordinateTransformResult, type CoordinateTransformation, type Coordinates, type CoordinatesSearchOptions, type CoordinatesTransformOptions, type DefaultTransformation, type ElevationAtOptions, type ElevationBatchOptions, type FeatureHierarchy, type FetchFunction, type GeocodingFeature, type GeocodingOptions, type GeocodingSearchResult, type GeolocationInfoOptions, type GeolocationResult, type GetDataOptions, type LanguageGeocodingOptions, MapStyle, type MapStylePreset, type MapStyleType, MapStyleVariant, type PixelData, ReferenceMapStyle, type ReverseGeocodingOptions, ServiceError, type StaticMapBaseOptions, type StaticMapMarker, type TileJSON, type XYZ, bufferToPixelDataBrowser, circumferenceAtLatitude, coordinates, data, elevation, expandMapStyle, geocoding, geolocation, getBufferToPixelDataParser, getTileCache, mapStylePresetList, math, misc, staticMaps, styleToStyle, type LanguageInfo, areSameLanguages, toLanguageInfo, isLanguageInfo, getAutoLanguage, getLanguageInfoFromFlag, getLanguageInfoFromCode, getLanguageInfoFromKey, canParsePixelData, } from '@maptiler/client';
+export * from './ImageViewer';
 export { getWebGLSupportError, displayWebGLContextLostWarning } from './tools';
 export { config, SdkConfig } from './config';
 export * from './language';

package/dist/src/{ImageViewer/utils.d.ts → utils/errors.d.ts}

@@ -1,5 +1,5 @@
 export declare class FetchError extends Error {
     status: number;
     statusText: string;
-    constructor(response: Response, resource: string);
+    constructor(response: Response, resource: string, module: string);
 }

package/dist/src/utils/webgl-utils.d.ts

@@ -16,7 +16,7 @@ export declare function loadShader({ gl, type, source }: {
  *
  * @returns WebGL program
  */
-export declare function createShadersSetProgram({ gl, vertexShaderSource, fragmentShaderSource }: {
+export declare function createShaderProgram({ gl, vertexShaderSource, fragmentShaderSource }: {
     gl: WebGLContext;
     vertexShaderSource: string;
     fragmentShaderSource: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maptiler/sdk",
-  "version": "3.8.0-rc4",
+  "version": "3.8.0-rc7",
   "description": "The Javascript & TypeScript map SDK tailored for MapTiler Cloud",
   "author": "MapTiler",
   "module": "dist/maptiler-sdk.mjs",
@@ -89,7 +89,7 @@
     "@koa/cors": "^5.0.0",
     "@koa/router": "^13.1.1",
     "@maplibre/maplibre-gl-style-spec": "~23.3.0",
-    "@maptiler/client": "~2.4.0",
+    "@maptiler/client": "~2.5.0",
     "events": "^3.3.0",
     "gl-matrix": "^3.4.3",
     "js-base64": "^3.7.7",