@maptiler/sdk 3.8.0-rc2 → 3.8.0-rc4

package/dist/src/Map.d.ts

@@ -0,0 +1,431 @@
+import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions } from 'maplibre-gl';
+import { ReferenceMapStyle, MapStyleVariant } from '@maptiler/client';
+import { SdkConfig } from './config';
+import { LanguageInfo } from './language';
+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';
+export type LoadWithTerrainEvent = {
+    type: "loadWithTerrain";
+    target: Map;
+    terrain: {
+        source: string;
+        exaggeration: number;
+    };
+};
+export declare const GeolocationType: {
+    POINT: "POINT";
+    COUNTRY: "COUNTRY";
+};
+/**
+ * The type of projection, `undefined` means it's decided by the style and if the style does not contain any projection info,
+ * if falls back to the default Mercator
+ */
+export type ProjectionTypes = "mercator" | "globe" | undefined;
+/**
+ * Options to provide to the `Map` constructor
+ */
+export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo"> & {
+    /**
+     * Style of the map. Can be:
+     * - a full style URL (possibly with API key)
+     * - a shorthand with only the MapTIler style name (eg. `"streets-v2"`)
+     * - a longer form with the prefix `"maptiler://"` (eg. `"maptiler://streets-v2"`)
+     */
+    style?: ReferenceMapStyle | MapStyleVariant | StyleSpecification | string;
+    /**
+     * Define the language of the map. This can be done directly with a language ISO code (eg. "en"),
+     * the ISO code prepended with the OSM flag (eg. "name:en" or even just "name"),
+     * or with a built-in shorthand (eg. Language.ENGLISH).
+     * Note that this is equivalent to setting the `config.primaryLanguage` and will overwrite it.
+     */
+    language?: LanguageInfo | string;
+    /**
+     * Define the MapTiler Cloud API key to be used. This is strictly equivalent to setting
+     * `config.apiKey` and will overwrite it.
+     */
+    apiKey?: string;
+    /**
+     * Shows or hides the MapTiler logo in the bottom left corner.
+     *
+     * For paid plans:
+     * - `true` shows MapTiler logo
+     * - `false` hodes MapTiler logo
+     * - default: `false` (hide)
+     *
+     * For free plans: MapTiler logo always shows, regardless of the value.
+     */
+    maptilerLogo?: boolean;
+    /**
+     * Attribution text to show in an {@link AttributionControl}.
+     */
+    customAttribution?: string | Array<string>;
+    /**
+     * Enables 3D terrain if `true`. (default: `false`)
+     */
+    terrain?: boolean;
+    /**
+     * Exaggeration factor of the terrain. (default: `1`, no exaggeration)
+     */
+    terrainExaggeration?: number;
+    /**
+     * Show the navigation control. (default: `true`, will hide if `false`)
+     */
+    navigationControl?: boolean | ControlPosition;
+    /**
+     * Show the terrain control. (default: `false`, will show if `true`)
+     */
+    terrainControl?: boolean | ControlPosition;
+    /**
+     * Show the geolocate control. (default: `true`, will hide if `false`)
+     */
+    geolocateControl?: boolean | ControlPosition;
+    /**
+     * Show the scale control. (default: `false`, will show if `true`)
+     */
+    scaleControl?: boolean | ControlPosition;
+    /**
+     * Show the full screen control. (default: `false`, will show if `true`)
+     */
+    fullscreenControl?: boolean | ControlPosition;
+    /**
+     * 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.
+     */
+    minimap?: boolean | ControlPosition | MinimapOptionsInput;
+    /**
+     * attributionControl
+     */
+    forceNoAttributionControl?: boolean;
+    /**
+     * Method to position the map at a given geolocation. Only if:
+     * - `hash` is `false`
+     * - `center` is not provided
+     *
+     * If the value is `true` of `"POINT"` (given by `GeolocationType.POINT`) then the positionning uses the MapTiler Cloud
+     * Geolocation to find the non-GPS location point.
+     * The zoom level can be provided in the `Map` constructor with the `zoom` option or will be `13` if not provided.
+     *
+     * If the value is `"COUNTRY"` (given by `GeolocationType.COUNTRY`) then the map is centered around the bounding box of the country.
+     * In this case, the `zoom` option will be ignored.
+     *
+     * If the value is `false`, no geolocation is performed and the map centering and zooming depends on other options or on
+     * the built-in defaults.
+     *
+     * If this option is non-false and the options `center` is also provided, then `center` prevails.
+     *
+     * Default: `false`
+     */
+    geolocate?: (typeof GeolocationType)[keyof typeof GeolocationType] | boolean;
+    /**
+     * Show the projection control. (default: `false`, will show if `true`)
+     */
+    projectionControl?: boolean | ControlPosition;
+    /**
+     * Whether the projection should be "mercator" or "globe".
+     * If not provided, the style takes precedence. If provided, overwrite the style.
+     */
+    projection?: ProjectionTypes;
+    /**
+     * Turn on/off spacebox.
+     *
+     * Default: { color: "#1D29F1" }
+     */
+    space?: CubemapLayerConstructorOptions | boolean;
+    halo?: RadialGradientLayerConstructorOptions | boolean;
+};
+/**
+ * The Map class can be instanciated to display a map in a `<div>`
+ */
+export declare class Map extends maplibregl.Map {
+    readonly telemetry: Telemetry;
+    private space?;
+    private halo?;
+    getSpace(): CubemapLayer | undefined;
+    /**
+     * Sets the space for the map.
+     * @param {CubemapDefinition} space the `CubemapDefinition` options to set.
+     * @remarks This method, at present, ** overwrites ** the current config.
+     * If an option is not set it will internally revert to the default option
+     * unless explicitly set when calling.
+     */
+    setSpace(space: CubemapDefinition): void;
+    private setSpaceFromStyle;
+    private setHaloFromStyle;
+    private setSpaceFromCurrentStyle;
+    private setHaloFromCurrentStyle;
+    private initSpace;
+    private initHalo;
+    getHalo(): RadialGradientLayer | undefined;
+    setHalo(halo: GradientDefinition): void;
+    private options;
+    private isTerrainEnabled;
+    private terrainExaggeration;
+    private primaryLanguage;
+    private terrainGrowing;
+    private terrainFlattening;
+    private minimap?;
+    private forceLanguageUpdate;
+    private languageAlwaysBeenStyle;
+    private isReady;
+    private terrainAnimationDuration;
+    private monitoredStyleUrls;
+    private styleInProcess;
+    private curentProjection;
+    private originalLabelStyle;
+    private isStyleLocalized;
+    private languageIsUpdated;
+    constructor(options: MapOptions);
+    /**
+     * Recreates the map instance with the same options.
+     * Useful for WebGL context loss.
+     */
+    recreate(): void;
+    /**
+     * Set the duration (millisec) of the terrain animation for growing or flattening.
+     * Must be positive. (Built-in default: `1000` milliseconds)
+     */
+    setTerrainAnimationDuration(d: number): void;
+    /**
+     * Awaits for _this_ Map instance to be "loaded" and returns a Promise to the Map.
+     * If _this_ Map instance is already loaded, the Promise is resolved directly,
+     * otherwise, it is resolved as a result of the "load" event.
+     * @returns
+     */
+    onLoadAsync(): Promise<Map>;
+    /**
+     * Awaits for _this_ Map instance to be "ready" and returns a Promise to the Map.
+     * If _this_ Map instance is already ready, the Promise is resolved directly,
+     * otherwise, it is resolved as a result of the "ready" event.
+     * A map instance is "ready" when all the controls that can be managed by the contructor are
+     * dealt with. This happens after the "load" event, due to the asynchronous nature
+     * of some built-in controls.
+     */
+    onReadyAsync(): Promise<Map>;
+    /**
+     * Awaits for _this_ Map instance to be "loaded" as well as with terrain being non-null for the first time
+     * and returns a Promise to the Map.
+     * If _this_ Map instance is already loaded with terrain, the Promise is resolved directly,
+     * otherwise, it is resolved as a result of the "loadWithTerrain" event.
+     * @returns
+     */
+    onLoadWithTerrainAsync(): Promise<Map>;
+    private monitorStyleUrl;
+    /**
+     * Update the style of the map.
+     * Can be:
+     * - a full style URL (possibly with API key)
+     * - 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;
+    /**
+     * Adds a [MapLibre style layer](https://maplibre.org/maplibre-style-spec/layers)
+     * to the map's style.
+     *
+     * A layer defines how data from a specified source will be styled. Read more about layer types
+     * and available paint and layout properties in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/layers).
+     *
+     * @param layer - The layer to add,
+     * conforming to either the MapLibre Style Specification's [layer definition](https://maplibre.org/maplibre-style-spec/layers) or,
+     * less commonly, the {@link CustomLayerInterface} specification.
+     * The MapLibre Style Specification's layer definition is appropriate for most layers.
+     *
+     * @param beforeId - The ID of an existing layer to insert the new layer before,
+     * resulting in the new layer appearing visually beneath the existing layer.
+     * If this argument is not specified, the layer will be appended to the end of the layers array
+     * and appear visually above all other layers.
+     *
+     * @returns `this`
+     */
+    addLayer(layer: (LayerSpecification & {
+        source?: string | SourceSpecification;
+    }) | CustomLayerInterface, beforeId?: string): this;
+    /**
+     * Moves a layer to a different z-position.
+     *
+     * @param id - The ID of the layer to move.
+     * @param beforeId - The ID of an existing layer to insert the new layer before. When viewing the map, the `id` layer will appear beneath the `beforeId` layer. If `beforeId` is omitted, the layer will be appended to the end of the layers array and appear above all other layers on the map.
+     * @returns `this`
+     *
+     * @example
+     * Move a layer with ID 'polygon' before the layer with ID 'country-label'. The `polygon` layer will appear beneath the `country-label` layer on the map.
+     * ```ts
+     * map.moveLayer('polygon', 'country-label');
+     * ```
+     */
+    moveLayer(id: string, beforeId?: string): this;
+    /**
+     * Removes the layer with the given ID from the map's style.
+     *
+     * An {@link ErrorEvent} will be fired if the image parameter is invald.
+     *
+     * @param id - The ID of the layer to remove
+     * @returns `this`
+     *
+     * @example
+     * If a layer with ID 'state-data' exists, remove it.
+     * ```ts
+     * if (map.getLayer('state-data')) map.removeLayer('state-data');
+     * ```
+     */
+    removeLayer(id: string): 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)
+     * and [maximum zoom level](https://maplibre.org/maplibre-style-spec/layers/#maxzoom))
+     * at which the layer will be rendered.
+     *
+     * Note: For style layers using vector sources, style layers cannot be rendered at zoom levels lower than the
+     * minimum zoom level of the _source layer_ because the data does not exist at those zoom levels. If the minimum
+     * zoom level of the source layer is higher than the minimum zoom level defined in the style layer, the style
+     * layer will not be rendered at all zoom levels in the zoom range.
+     */
+    setLayerZoomRange(layerId: string, minzoom: number, maxzoom: number): this;
+    /**
+     * Sets the filter for the specified style layer.
+     *
+     * Filters control which features a style layer renders from its source.
+     * Any feature for which the filter expression evaluates to `true` will be
+     * rendered on the map. Those that are false will be hidden.
+     *
+     * Use `setFilter` to show a subset of your source data.
+     *
+     * To clear the filter, pass `null` or `undefined` as the second parameter.
+     */
+    setFilter(layerId: string, filter?: FilterSpecification | null, options?: StyleSetterOptions): this;
+    /**
+     * Sets the value of a paint property in the specified style layer.
+     *
+     * @param layerId - The ID of the layer to set the paint property in.
+     * @param name - The name of the paint property to set.
+     * @param value - The value of the paint property to set.
+     * Must be of a type appropriate for the property, as defined in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/).
+     * @param options - Options object.
+     * @returns `this`
+     * @example
+     * ```ts
+     * map.setPaintProperty('my-layer', 'fill-color', '#faafee');
+     * ```
+     */
+    setPaintProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    /**
+     * Sets the value of a layout property in the specified style layer.
+     * Layout properties define how the layer is styled.
+     * Layout properties for layers of the same type are documented together.
+     * Layers of different types have different layout properties.
+     * See the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/) for the complete list of layout properties.
+     * @param layerId - The ID of the layer to set the layout property in.
+     * @param name - The name of the layout property to set.
+     * @param value - The value of the layout property to set.
+     * Must be of a type appropriate for the property, as defined in the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/).
+     * @param options - Options object.
+     * @returns `this`
+     */
+    setLayoutProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    /**
+     * Sets the value of the style's glyphs property.
+     *
+     * @param glyphsUrl - Glyph URL to set. Must conform to the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/glyphs/).
+     * @param options - Options object.
+     * @returns `this`
+     * @example
+     * ```ts
+     * map.setGlyphs('https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf');
+     * ```
+     */
+    setGlyphs(glyphsUrl: string | null, options?: StyleSetterOptions): this;
+    private getStyleLanguage;
+    /**
+     * Define the primary language of the map. Note that not all the languages shorthands provided are available.
+     */
+    setLanguage(language: LanguageInfo | string): void;
+    /**
+     * Define the primary language of the map. Note that not all the languages shorthands provided are available.
+     */
+    private setPrimaryLanguage;
+    /**
+     * Get the primary language
+     * @returns
+     */
+    getPrimaryLanguage(): LanguageInfo;
+    /**
+     * Get the exaggeration factor applied to the terrain
+     * @returns
+     */
+    getTerrainExaggeration(): number;
+    /**
+     * Know if terrian is enabled or not
+     * @returns
+     */
+    hasTerrain(): boolean;
+    private growTerrain;
+    /**
+     * Enables the 3D terrain visualization
+     */
+    enableTerrain(exaggeration?: number): void;
+    /**
+     * Disable the 3D terrain visualization
+     */
+    disableTerrain(): void;
+    /**
+     * Sets the 3D terrain exageration factor.
+     * If the terrain was not enabled prior to the call of this method,
+     * the method `.enableTerrain()` will be called.
+     * If `animate` is `true`, the terrain transformation will be animated in the span of 1 second.
+     * If `animate` is `false`, no animated transition to the newly defined exaggeration.
+     */
+    setTerrainExaggeration(exaggeration: number, animate?: boolean): void;
+    /**
+     * Perform an action when the style is ready. It could be at the moment of calling this method
+     * or later.
+     */
+    private onStyleReady;
+    fitToIpBounds(): Promise<void>;
+    centerOnIpPoint(zoom: number | undefined): Promise<void>;
+    getCameraHash(): string;
+    /**
+     * Get the SDK config object.
+     * This is convenient to dispatch the SDK configuration to externally built layers
+     * that do not directly have access to the SDK configuration but do have access to a Map instance.
+     */
+    getSdkConfig(): SdkConfig;
+    /**
+     * Get the MapTiler session ID. Convenient to dispatch to externaly built component
+     * that do not directly have access to the SDK configuration but do have access to a Map instance.
+     * @returns
+     */
+    getMaptilerSessionId(): string;
+    /**
+     *  Updates the requestManager's transform request with a new function.
+     *
+     * @param transformRequest A callback run before the Map makes a request for an external URL. The callback can be used to modify the url, set headers, or set the credentials property for cross-origin requests.
+     *    Expected to return an object with a `url` property and optionally `headers` and `credentials` properties
+     *
+     * @returns {Map} `this`
+     *
+     *  @example
+     *  map.setTransformRequest((url: string, resourceType: string) => {});
+     */
+    setTransformRequest(transformRequest: RequestTransformFunction): this;
+    /**
+     * Returns whether a globe projection is currently being used
+     */
+    isGlobeProjection(): boolean;
+    /**
+     * Activate the globe projection.
+     */
+    enableGlobeProjection(): void;
+    /**
+     * Activate the mercator projection.
+     */
+    enableMercatorProjection(): void;
+    /**
+     * Returns `true` is the language was ever updated, meaning changed
+     * from what is delivered in the style.
+     * Returns `false` if language in use is the language from the style
+     * and has never been changed.
+     */
+    isLanguageUpdated(): boolean;
+}

package/dist/src/Point.d.ts

@@ -0,0 +1,177 @@
+/**
+ * This is TypeScript rewrite of the Point class to use instead of the version imported in MapLibre.
+ * It also uses a class instead of prototypes.
+ */
+/**
+ * Row major 2x2 matrix
+ */
+export type Matrix2 = [number, number, number, number];
+/**
+ * a point
+ */
+export declare class Point {
+    x: number;
+    y: number;
+    constructor(x: number, y: number);
+    private _matMult;
+    private _add;
+    private _sub;
+    private _mult;
+    private _div;
+    private _multByPoint;
+    private _divByPoint;
+    private _unit;
+    private _perp;
+    private _rotate;
+    private _rotateAround;
+    private _round;
+    /**
+     * Clone this point, returning a new point that can be modified
+     * without affecting the old one.
+     * @return {Point} the clone
+     */
+    clone(): Point;
+    /**
+     * Add this point's x & y coordinates to another point,
+     * yielding a new point.
+     * @param {Point} p the other point
+     * @return {Point} output point
+     */
+    add(p: Point): Point;
+    /**
+     * Subtract this point's x & y coordinates to from point,
+     * yielding a new point.
+     * @param {Point} p the other point
+     * @return {Point} output point
+     */
+    sub(p: Point): Point;
+    /**
+     * Multiply this point's x & y coordinates by point,
+     * yielding a new point.
+     * @param {Point} p the other point
+     * @return {Point} output point
+     */
+    multByPoint(p: Point): Point;
+    /**
+     * Divide this point's x & y coordinates by point,
+     * yielding a new point.
+     * @param {Point} p the other point
+     * @return {Point} output point
+     */
+    divByPoint(p: Point): Point;
+    /**
+     * Multiply this point's x & y coordinates by a factor,
+     * yielding a new point.
+     * @param {Number} k factor
+     * @return {Point} output point
+     */
+    mult(k: number): Point;
+    /**
+     * Divide this point's x & y coordinates by a factor,
+     * yielding a new point.
+     * @param {Point} k factor
+     * @return {Point} output point
+     */
+    div(k: number): Point;
+    /**
+     * Rotate this point around the 0, 0 origin by an angle a,
+     * given in radians
+     * @param {Number} a angle to rotate around, in radians
+     * @return {Point} output point
+     */
+    rotate(a: number): Point;
+    /**
+     * Rotate this point around p point by an angle a,
+     * given in radians
+     * @param {Number} a angle to rotate around, in radians
+     * @param {Point} p Point to rotate around
+     * @return {Point} output point
+     */
+    rotateAround(a: number, p: Point): Point;
+    /**
+     * Multiply this point by a 4x1 transformation matrix
+     * @param {Array<Number>} m transformation matrix
+     * @return {Point} output point
+     */
+    matMult(m: Matrix2): Point;
+    /**
+     * Calculate this point but as a unit vector from 0, 0, meaning
+     * that the distance from the resulting point to the 0, 0
+     * coordinate will be equal to 1 and the angle from the resulting
+     * point to the 0, 0 coordinate will be the same as before.
+     * @return {Point} unit vector point
+     */
+    unit(): Point;
+    /**
+     * Compute a perpendicular point, where the new y coordinate
+     * is the old x coordinate and the new x coordinate is the old y
+     * coordinate multiplied by -1
+     * @return {Point} perpendicular point
+     */
+    perp(): Point;
+    /**
+     * Return a version of this point with the x & y coordinates
+     * rounded to integers.
+     * @return {Point} rounded point
+     */
+    round(): Point;
+    /**
+     * Return the magnitude of this point: this is the Euclidean
+     * distance from the 0, 0 coordinate to this point's x and y
+     * coordinates.
+     * @return {Number} magnitude
+     */
+    mag(): number;
+    /**
+     * Judge whether this point is equal to another point, returning
+     * true or false.
+     * @param {Point} other the other point
+     * @return {boolean} whether the points are equal
+     */
+    equals(other: Point): boolean;
+    /**
+     * Calculate the distance from this point to another point
+     * @param {Point} p the other point
+     * @return {Number} distance
+     */
+    dist(p: Point): number;
+    /**
+     * Calculate the distance from this point to another point,
+     * without the square root step. Useful if you're comparing
+     * relative distances.
+     * @param {Point} p the other point
+     * @return {Number} distance
+     */
+    distSqr(p: Point): number;
+    /**
+     * Get the angle from the 0, 0 coordinate to this point, in radians
+     * coordinates.
+     * @return {Number} angle
+     */
+    angle(): number;
+    /**
+     * Get the angle from this point to another point, in radians
+     * @param {Point} b the other point
+     * @return {Number} angle
+     */
+    angleTo(b: Point): number;
+    /**
+     * Get the angle between this point and another point, in radians
+     * @param {Point} b the other point
+     * @return {Number} angle
+     */
+    angleWith(b: Point): number;
+    angleWithSep(x: number, y: number): number;
+    /**
+     * Construct a point from an array if necessary, otherwise if the input
+     * is already a Point, or an unknown type, return it unchanged
+     * @param {Array<number> | Point} a any kind of input value
+     * @return {Point} constructed point, or passed-through value.
+     * @example
+     * // this
+     * var point = Point.convert([0, 1]);
+     * // is equivalent to
+     * var point = new Point(0, 1);
+     */
+    static convert(a: Point | Array<number>): Point;
+}

package/dist/src/Telemetry.d.ts

@@ -0,0 +1,23 @@
+import { Map as MapSDK } from './Map';
+/**
+ * A Telemetry instance sends some usage and merics to a dedicated endpoint at MapTiler Cloud.
+ */
+export declare class Telemetry {
+    private map;
+    private registeredModules;
+    private viewerType;
+    /**
+     *
+     * @param map : a Map instance
+     * @param delay : a delay in milliseconds after which the payload is sent to MapTiler cloud (cannot be less than 1000ms)
+     */
+    constructor(map: MapSDK, delay?: number);
+    /**
+     * Register a module to the telemetry system of the SDK.
+     * The arguments `name` and `version` likely come from the package.json
+     * of each module.
+     */
+    registerModule(name: string, version: string): void;
+    registerViewerType(viewerType?: string): void;
+    private preparePayload;
+}

package/dist/src/caching.d.ts

@@ -0,0 +1,4 @@
+import { ResourceType } from 'maplibre-gl';
+export declare const CACHE_API_AVAILABLE: boolean;
+export declare function localCacheTransformRequest(reqUrl: URL, resourceType?: ResourceType): string;
+export declare function registerLocalCacheProtocol(): void;