@maptiler/sdk 3.9.0-rc.4 → 3.9.0-rc.5

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;

package/dist/src/config.d.ts

@@ -0,0 +1,85 @@
+import { default as EventEmitter } from 'events';
+import { LanguageInfo } from './language';
+import { FetchFunction } from '@maptiler/client';
+import { Unit } from './types';
+export declare const MAPTILER_SESSION_ID: string;
+/**
+ * Configuration class for the SDK
+ */
+declare class SdkConfig extends EventEmitter {
+    /**
+     * The primary language. By default, the language of the web browser is used.
+     */
+    primaryLanguage: LanguageInfo;
+    /**
+     * The secondary language, to overwrite the default language defined in the map style.
+     * This settings is highly dependant on the style compatibility and may not work in most cases.
+     */
+    secondaryLanguage?: LanguageInfo;
+    /**
+     * Setting on whether of not the SDK runs with a session logic.
+     * A "session" is started at the initialization of the SDK and finished when the browser
+     * page is being refreshed.
+     * When `session` is enabled (default: true), the extra URL param `mtsid` is added to queries
+     * on the MapTiler Cloud API. This allows MapTiler to enable "session based billing".
+     */
+    session: boolean;
+    /**
+     * Enables client-side caching of requests for tiles and fonts.
+     * The cached requests persist multiple browser sessions and will be reused when possible.
+     * Works only for requests to the MapTiler Cloud API when sessions are enabled.
+     */
+    caching: boolean;
+    /**
+     * Telemetry is enabled by default but can be opted-out by setting this value to `false`.
+     * The telemetry is very valuable to the team at MapTiler because it shares information
+     * about where to add the extra effort. It also helps spotting some incompatibility issues
+     * that may arise between the SDK and a specific version of a module.
+     *
+     * It consists in sending metrics about usage of the following features:
+     * - SDK version [string]
+     * - API key [string]
+     * - MapTiler sesion ID (if opted-in) [string]
+     * - if tile caching is enabled [boolean]
+     * - if language specified at initialization [boolean]
+     * - if terrain is activated at initialization [boolean]
+     * - if globe projection is activated at initialization [boolean]
+     *
+     * In addition, each official module will be added to a list, alongside its version number.
+     */
+    telemetry: boolean;
+    /**
+     * Unit to be used
+     */
+    private _unit;
+    /**
+     * MapTiler Cloud API key
+     */
+    private _apiKey;
+    /**
+     * Set the unit system
+     */
+    set unit(u: Unit);
+    /**
+     * Get the unit system
+     */
+    get unit(): Unit;
+    /**
+     * Set the MapTiler Cloud API key
+     */
+    set apiKey(k: string);
+    /**
+     * Get the MapTiler Cloud API key
+     */
+    get apiKey(): string;
+    /**
+     * Set a the custom fetch function to replace the default one
+     */
+    set fetch(f: FetchFunction);
+    /**
+     * Get the fetch fucntion
+     */
+    get fetch(): FetchFunction | null;
+}
+declare const config: SdkConfig;
+export { config, SdkConfig };

package/dist/src/constants/defaults.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Some default settings for the SDK
+ */
+declare const defaults: {
+    maptilerLogoURL: string;
+    maptilerURL: string;
+    maptilerApiHost: string;
+    telemetryURL: string;
+    rtlPluginURL: string;
+    primaryLanguage: import('@maptiler/client').LanguageInfo;
+    secondaryLanguage: import('@maptiler/client').LanguageInfo;
+    terrainSourceURL: string;
+    terrainSourceId: string;
+};
+export { defaults };

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/MaptilerGeolocateControl.d.ts

@@ -0,0 +1,21 @@
+import { GeolocateControl } from '../MLAdapters/GeolocateControl';
+/**
+ * The MaptilerGeolocateControl is an extension of the original GeolocateControl
+ * with a few changes. In this version, the active mode persists as long as the
+ * location is still centered. This means it's robust to rotation, pitch and zoom.
+ *
+ */
+export declare class MaptilerGeolocateControl extends GeolocateControl {
+    private lastUpdatedCenter;
+    /**
+     * Update the camera location to center on the current position
+     *
+     * @param {Position} position the Geolocation API Position
+     * @private
+     */
+    _updateCamera: (position: GeolocationPosition) => void;
+    _finishSetupUI: (supported: boolean) => void;
+    _updateCircleRadius(): void;
+    _onZoom: () => void;
+    _setErrorState(): void;
+}

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

@@ -0,0 +1,19 @@
+import { LogoControlOptions as LogoControlOptionsML } from 'maplibre-gl';
+import { LogoControl } from '../MLAdapters/LogoControl';
+import { Map as SDKMap } from '../Map';
+type LogoControlOptions = LogoControlOptionsML & {
+    logoURL?: string;
+    linkURL?: string;
+};
+/**
+ * This LogoControl extends the MapLibre LogoControl but instead can use any image URL and
+ * any link URL. By default this is using MapTiler logo and URL.
+ */
+export declare class MaptilerLogoControl extends LogoControl {
+    _compact: boolean;
+    private logoURL;
+    private linkURL;
+    constructor(options?: LogoControlOptions);
+    onAdd(map: SDKMap): HTMLElement;
+}
+export {};

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

@@ -0,0 +1,17 @@
+import { NavigationControlOptions } from 'maplibre-gl';
+import { NavigationControl } from '../MLAdapters/NavigationControl';
+type HTMLButtonElementPlus = HTMLButtonElement & {
+    clickFunction: (e?: Event) => unknown;
+};
+export declare class MaptilerNavigationControl extends NavigationControl {
+    constructor(options?: NavigationControlOptions);
+    /**
+     * Overloading: the button now stores its click callback so that we can later on delete it and replace it
+     */
+    _createButton(className: string, fn: (e?: Event) => unknown): HTMLButtonElementPlus;
+    /**
+     * Overloading: Limit how flat the compass icon can get
+     */
+    _rotateCompassArrow: () => void;
+}
+export {};

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

@@ -0,0 +1,15 @@
+import { Map as SDKMap } from '../Map';
+import { IControl } from 'maplibre-gl';
+/**
+ * A `MaptilerProjectionControl` control adds a button to switch from Mercator to Globe projection.
+ */
+export declare class MaptilerProjectionControl implements IControl {
+    map: SDKMap;
+    container: HTMLElement;
+    projectionButton: HTMLButtonElement;
+    onAdd(map: SDKMap): HTMLElement;
+    onRemove(): void;
+    private toggleProjection;
+    private updateProjectionIcon;
+}
+export declare function toggleProjection(map: SDKMap): void;

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

@@ -0,0 +1,17 @@
+import { Map as SDKMap } from '../Map';
+import { IControl } from 'maplibre-gl';
+/**
+ * A `MaptilerTerrainControl` control adds a button to turn terrain on and off
+ * by triggering the terrain logic that is already deployed in the Map object.
+ */
+export declare class MaptilerTerrainControl implements IControl {
+    _map: SDKMap;
+    _container: HTMLElement;
+    _terrainButton: HTMLButtonElement;
+    constructor();
+    onAdd(map: SDKMap): HTMLElement;
+    onRemove(): void;
+    _toggleTerrain(): void;
+    _updateTerrainIcon(): void;
+}
+export declare function toggleTerrain(map: SDKMap): void;

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

@@ -0,0 +1,57 @@
+import { Map as SDKMap, MapOptions } from '../Map';
+import { ControlPosition, CustomLayerInterface, FillLayerSpecification, FilterSpecification, IControl, LayerSpecification, LineLayerSpecification, SourceSpecification, StyleOptions, StyleSetterOptions, StyleSpecification, StyleSwapOptions } from 'maplibre-gl';
+import { MapStyleVariant, ReferenceMapStyle } from '@maptiler/client';
+export interface ParentRect {
+    lineLayout: LineLayerSpecification["layout"];
+    linePaint: LineLayerSpecification["paint"];
+    fillPaint: FillLayerSpecification["paint"];
+}
+export interface MinimapOptionsInput {
+    /**
+     * 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;
+    /**
+     * Set the zoom difference between the parent and the minimap
+     * If the parent is zoomed to 10 and the minimap is zoomed to 8, the zoomAdjust should be 2
+     * Default: -4
+     */
+    zoomAdjust?: number;
+    /** Set a zoom of the minimap and don't allow any future changes */
+    lockZoom?: number;
+    /** Adjust the pitch only if the user requests */
+    pitchAdjust?: boolean;
+    /** Set CSS properties of the container using object key-values */
+    containerStyle?: Record<string, string>;
+    /** Set the position of the minimap at either "top-left", "top-right", "bottom-left", or "bottom-right" */
+    position?: ControlPosition;
+    /** Set the parentRect fill and/or line options */
+    parentRect?: ParentRect;
+}
+export interface MinimapOptions extends Omit<MapOptions, "space" | "halo"> {
+    zoomAdjust: number;
+    pitchAdjust: boolean;
+    containerStyle: Record<string, string>;
+    parentRect?: ParentRect;
+}
+export default class Minimap implements IControl {
+    #private;
+    map: SDKMap;
+    constructor(options: MinimapOptionsInput, mapOptions: MapOptions);
+    setStyle(style: null | ReferenceMapStyle | MapStyleVariant | StyleSpecification | string, options?: StyleSwapOptions & StyleOptions): void;
+    addLayer(layer: (LayerSpecification & {
+        source?: string | SourceSpecification;
+    }) | CustomLayerInterface, beforeId?: string): SDKMap;
+    moveLayer(id: string, beforeId?: string): SDKMap;
+    removeLayer(id: string): this;
+    setLayerZoomRange(layerId: string, minzoom: number, maxzoom: number): this;
+    setFilter(layerId: string, filter?: FilterSpecification | null, options?: StyleSetterOptions): this;
+    setPaintProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    setLayoutProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    setGlyphs(glyphsUrl: string | null, options?: StyleSetterOptions): this;
+    onAdd(parentMap: SDKMap): HTMLElement;
+    onRemove(): void;
+}

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

@@ -0,0 +1,8 @@
+export * from './MaptilerCustomControl';
+export * from './MaptilerExternalControl';
+export * from './MaptilerGeolocateControl';
+export * from './MaptilerLogoControl';
+export * from './MaptilerTerrainControl';
+export * from './MaptilerNavigationControl';
+export * from './MaptilerProjectionControl';
+export * from './Minimap';

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

@@ -0,0 +1 @@
+export * from './xml';

package/dist/src/converters/xml.d.ts

@@ -0,0 +1,54 @@
+export interface Link {
+    href: string | null;
+}
+export interface XMLProperties {
+    links?: Link[];
+}
+export interface PlacemarkProperties {
+    name?: string;
+    address?: string;
+    styleUrl?: string;
+    description?: string;
+    styleHash?: string;
+    styleMapHash?: Record<string, string | null>;
+    timespan?: {
+        begin: string;
+        end: string;
+    };
+    timestamp?: string;
+    stroke?: string;
+    "stroke-opacity"?: number;
+    "stroke-width"?: number;
+    fill?: string;
+    "fill-opacity"?: number;
+    visibility?: string;
+    icon?: string;
+    coordTimes?: (string | null)[] | (string | null)[][];
+}
+/**
+ * create a function that converts a string to XML
+ * https://developer.mozilla.org/en-US/docs/Web/API/DOMParser
+ */
+export declare function str2xml(str: string): Document;
+/**
+ * Check one of the top level child node is of a given type ("gpx", "kml").
+ * The check is not case sensitive.
+ * @param doc
+ * @param nodeName
+ * @returns
+ */
+export declare function hasChildNodeWithName(doc: Document, nodeName: string): boolean;
+/**
+ * create a function that converts a XML to a string
+ * https://developer.mozilla.org/en-US/docs/Web/API/XMLSerializer
+ */
+export declare function xml2str(node: Node): string;
+/**
+ * Given a XML document using the GPX spec, return GeoJSON
+ */
+export declare function gpx(doc: string | Document): GeoJSON.FeatureCollection;
+/**
+ * Given a XML document using the KML spec, return GeoJSON
+ */
+export declare function kml(doc: string | Document, xml2string?: (node: Node) => string): GeoJSON.FeatureCollection;
+export declare function gpxOrKml(doc: string | Document): GeoJSON.FeatureCollection | null;