@maptiler/sdk 3.1.0-rc6 → 3.1.0-rc8

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/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,14 @@
+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;
+}

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

@@ -0,0 +1,16 @@
+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;
+}

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 MapOptions {
+    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,6 @@
+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;

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

@@ -0,0 +1,29 @@
+import { CustomLayerInterface, CustomRenderMethodInput } from 'maplibre-gl';
+import { Map as MapSDK } from '../../Map';
+import { WebGLContext } from '../../utils/webgl-utils';
+import { CubemapDefinition, CubemapLayerConstructorOptions } from './types';
+declare class CubemapLayer implements CustomLayerInterface {
+    id: string;
+    type: CustomLayerInterface["type"];
+    renderingMode: CustomLayerInterface["renderingMode"];
+    private map;
+    private faces?;
+    private useCubemapTexture;
+    private currentFadeOpacity;
+    private cubeMapNeedsUpdate;
+    private bgColor;
+    private gl;
+    private cubemap?;
+    private texture?;
+    constructor(cubemapConfig: CubemapLayerConstructorOptions | true);
+    updateCubemap(): void;
+    onAdd(map: MapSDK, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    onRemove(_map: MapSDK, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    prerender(gl: WebGLContext, _options: CustomRenderMethodInput): void;
+    private animateIn;
+    render(gl: WebGLRenderingContext | WebGL2RenderingContext, _options: CustomRenderMethodInput): void;
+    setCubemap(cubemap: CubemapDefinition): void;
+    show(): void;
+    hide(): void;
+}
+export { CubemapLayer };

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

@@ -0,0 +1,3 @@
+declare const VERTICES: number[];
+declare const INDICES: number[];
+export { VERTICES, INDICES };

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

@@ -0,0 +1,2 @@
+export * from './CubemapLayer';
+export * from './types';

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

@@ -0,0 +1,6 @@
+import { CubemapFaces } from './types';
+export declare function loadCubemapTexture({ gl, faces, onLoadedCallback }: {
+    gl: WebGLRenderingContext | WebGL2RenderingContext;
+    faces?: CubemapFaces;
+    onLoadedCallback?: () => void;
+}): WebGLTexture | undefined;

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

@@ -0,0 +1,37 @@
+export declare enum CubemapImagesPresets {
+    UNIVERSE_DARK = "universe-dark"
+}
+export type CubemapLayerConstructorOptions = CubemapDefinition & {};
+export type CubemapDefinition = {
+    path: {
+        baseUrl: string;
+        format?: "png" | "jpg" | "webp";
+    };
+    faces?: never;
+    preset?: never;
+    color?: string;
+} | {
+    faces: CubemapFaces;
+    path?: never;
+    preset?: never;
+    color?: string;
+} | {
+    preset: string;
+    path?: never;
+    faces?: never;
+    color?: string;
+} | {
+    color: string;
+    path?: never;
+    faces?: never;
+    preset?: never;
+};
+export declare enum CubemapFaceNames {
+    POSITIVE_X = "pX",
+    NEGATIVE_X = "nX",
+    POSITIVE_Y = "pY",
+    NEGATIVE_Y = "nY",
+    POSITIVE_Z = "pZ",
+    NEGATIVE_Z = "nZ"
+}
+export type CubemapFaces = Record<CubemapFaceNames, string>;

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

@@ -0,0 +1,23 @@
+import { CustomLayerInterface, CustomRenderMethodInput } from 'maplibre-gl';
+import { Map as MapSDK } from '../../Map';
+import { GradientDefinition, RadialGradientLayerOptions } from './types';
+export declare class RadialGradientLayer implements CustomLayerInterface {
+    id: string;
+    type: CustomLayerInterface["type"];
+    renderingMode: CustomLayerInterface["renderingMode"];
+    private gradient;
+    private scale;
+    private map;
+    private plane?;
+    constructor(gradient: RadialGradientLayerOptions | boolean);
+    onAdd(map: MapSDK, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    onRemove(_map: MapSDK, gl: WebGLRenderingContext | WebGL2RenderingContext): void;
+    prerender(_gl: WebGLRenderingContext | WebGL2RenderingContext, _options: CustomRenderMethodInput): void;
+    render(gl: WebGLRenderingContext | WebGL2RenderingContext, options: CustomRenderMethodInput): void;
+    /**
+     * Value settings methods
+     */
+    setGradient(gradient: GradientDefinition): void;
+    show(): void;
+    hide(): void;
+}

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

@@ -0,0 +1,2 @@
+export * from './RadialGradientLayer';
+export * from './types';

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

@@ -0,0 +1,11 @@
+import { Object3D } from '../../utils/webgl-utils';
+export type Color = string;
+export type GradientStop = number;
+export type RadialGradientLayerOptions = GradientDefinition;
+export type GradientDefinition = {
+    stops: Array<[GradientStop, Color]>;
+    scale: number;
+};
+export type GradientAttributeKey = "vertexPosition";
+export type GradientUniformKey = "stopsNumber" | "stops" | "colors";
+export type GradientPlaneObject3D = Pick<Object3D<GradientAttributeKey, GradientUniformKey>, "shaderProgram" | "programInfo" | "positionBuffer">;

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

@@ -0,0 +1,17 @@
+import { Map as MapSDK } from '../Map';
+import { StyleSpecification } from 'maplibre-gl';
+import { CubemapLayerConstructorOptions, RadialGradientLayerOptions } from 'custom-layers';
+export type StyleSpecificationWithMetaData = StyleSpecification & {
+    metadata?: {
+        "maptiler:copyright": string;
+        maptiler?: {
+            halo: RadialGradientLayerOptions;
+            space: CubemapLayerConstructorOptions;
+        };
+    };
+};
+export interface IExtractCustomLayerStyleOptions {
+    map: MapSDK;
+    property: "halo" | "space";
+}
+export default function extractCustomLayerStyle<T extends CubemapLayerConstructorOptions | RadialGradientLayerOptions | null>(options: IExtractCustomLayerStyleOptions): T | null;

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

@@ -0,0 +1,5 @@
+import { RadialGradientLayer } from './RadialGradientLayer';
+import { CubemapLayer } from './CubemapLayer';
+export { RadialGradientLayer, CubemapLayer };
+export * from './RadialGradientLayer/types';
+export * from './CubemapLayer/types';

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

@@ -0,0 +1,13 @@
+import { takeScreenshot } from './screenshot';
+import { addPolyline, addPolygon, addPoint, addHeatmap } from './vectorlayerhelpers';
+export type { ZoomStringValues, ZoomNumberValues, PropertyValues, CommonShapeLayerOptions, PolylineLayerOptions, PolygonLayerOptions, PointLayerOptions, HeatmapLayerOptions, } from './vectorlayerhelpers';
+/**
+ * Helpers are a set of functions to facilitate the creation of sources and layers
+ */
+export declare const helpers: {
+    addPolyline: typeof addPolyline;
+    addPolygon: typeof addPolygon;
+    addPoint: typeof addPoint;
+    addHeatmap: typeof addHeatmap;
+    takeScreenshot: typeof takeScreenshot;
+};

package/dist/src/helpers/screenshot.d.ts

@@ -0,0 +1,18 @@
+import { Map as MapSDK } from '../Map';
+/**
+ * Takes a screenshot (PNG file) of the curent map view.
+ * Depending on the options, this function can automatically trigger a download of te file.
+ */
+export declare function takeScreenshot(map: MapSDK, options?: {
+    /**
+     * If `true`, this function will trigger a download in addition to returning a blob.
+     * Default: `false`
+     */
+    download?: boolean;
+    /**
+     * Only if `options.download` is `true`. Indicates the filename under which
+     * the file will be downloaded.
+     * Default: `"maptiler_screenshot.png"`
+     */
+    filename?: string;
+}): Promise<Blob>;

package/dist/src/helpers/stylehelper.d.ts

@@ -0,0 +1,28 @@
+import { DataDrivenPropertyValueSpecification, ExpressionSpecification } from 'maplibre-gl';
+import { ColorRamp } from '../ColorRamp';
+import { DataDrivenStyle, PropertyValues, ZoomNumberValues, ZoomStringValues } from './vectorlayerhelpers';
+export type ColorPalette = [string, string, string, string];
+export declare const colorPalettes: Array<ColorPalette>;
+export declare function getRandomColor(): string;
+export declare function generateRandomSourceName(): string;
+export declare function generateRandomLayerName(): string;
+/**
+ * Linera interpolation to find a value at an arbitrary zoom level, given a list of tuple zoom-value
+ */
+export declare function lerpZoomNumberValues(znv: ZoomNumberValues, z: number): number;
+export declare function paintColorOptionsToPaintSpec(color: ZoomStringValues): DataDrivenPropertyValueSpecification<string>;
+export declare function rampedOptionsToLayerPaintSpec(ramp: ZoomNumberValues): DataDrivenPropertyValueSpecification<number>;
+export declare function computeRampedOutlineWidth(lineWidth: number | ZoomNumberValues, outlineWidth: number | ZoomNumberValues): number | DataDrivenPropertyValueSpecification<number>;
+export declare function rampedPropertyValueWeight(ramp: PropertyValues, property: string): DataDrivenPropertyValueSpecification<number>;
+/**
+ * Create a dash array from a string pattern that uses underscore and whitespace characters
+ */
+export declare function dashArrayMaker(pattern: string): Array<number>;
+export declare function colorDrivenByProperty(style: DataDrivenStyle, property: string): DataDrivenPropertyValueSpecification<string>;
+export declare function radiusDrivenByProperty(style: DataDrivenStyle, property: string, zoomCompensation?: boolean): DataDrivenPropertyValueSpecification<number>;
+export declare function radiusDrivenByPropertyHeatmap(style: PropertyValues, property: string, zoomCompensation?: boolean): DataDrivenPropertyValueSpecification<number>;
+/**
+ * Turns a ColorRamp instance into a MapLibre style for ramping the opacity, driven by a property
+ */
+export declare function opacityDrivenByProperty(colorramp: ColorRamp, property: string): DataDrivenPropertyValueSpecification<number>;
+export declare function heatmapIntensityFromColorRamp(colorRamp: ColorRamp, steps?: number): ExpressionSpecification;