azure-maps-control 2.1.16 → 2.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azure-maps-control",
   "author": "Microsoft Corporation",
-  "version": "2.1.16",
+  "version": "2.2.0",
   "description": "Map SDK for Azure Maps",
   "keywords": [
     "azure",
@@ -24,7 +24,7 @@
     "posttest-filter": "npm run updatePackageVersionForTests -- --isPreTest false",
     "test-filter": "set \"TS_NODE_PROJECT=./test/tsconfig.json\" && mocha --parallel --exit --timeout 30000 --require ts-node/register",
     "thirdPartyNotices": "node ./bin/thirdPartyNotices.js",
-    "tslint": "node_modules/.bin/tslint --project ./tsconfig.json",
+    "lint": "eslint -c .eslintrc.json --ext .ts,.js src/",
     "updateEnvVariables": "node ./bin/updateEnvVariables.js",
     "updateExampleKeys": "node ./bin/updateExampleKeys.js",
     "updateTestSecrets": "node ./bin/updateTestSecrets.js",
@@ -42,11 +42,15 @@
     "@types/mapbox-gl": "^1.13.0",
     "@types/mocha": "^5.2.7",
     "@types/puppeteer": "^1.20.7",
+    "@typescript-eslint/eslint-plugin": "^5.33.0",
+    "@typescript-eslint/parser": "^5.33.0",
     "adal-angular": "^1.0.18",
     "atob": "^2.1.2",
     "azuremaps-maplibre-gl": "^1.14.0-rc4",
     "cypress-multi-reporters": "^1.5.0",
     "es-abstract": "^1.17.1",
+    "eslint": "^8.22.0",
+    "eslint-plugin-security": "^1.5.0",
     "estree-walker": "^1.0.1",
     "fs-extra": "^8.1.0",
     "glob": "^7.1.6",
@@ -68,8 +72,6 @@
     "rollup-plugin-uglify": "^6.0.4",
     "simplify-ts": "^1.0.2",
     "ts-node": "^8.10.2",
-    "tslint": "^5.20.1",
-    "tslint-microsoft-contrib": "^6.2.0",
     "typescript": "^3.7.2",
     "utf-8-validate": "^5.0.2",
     "uuid-random": "^1.3.2",

package/typings/index.d.ts

@@ -516,6 +516,78 @@ declare namespace atlas {
             constructor(geometries: Geometry[]);
         }
 
+        /**
+         * A `MercatorPoint` object represents a projected three dimensional position.
+         *
+         * `MercatorPoint` uses the web mercator projection ([EPSG:3857](https://epsg.io/3857)) with slightly different units:
+         * - the size of 1 unit is the width of the projected world instead of the "mercator meter"
+         * - the origin of the coordinate space is at the north-west corner instead of the middle.
+         *
+         * For example, `MercatorPoint(0, 0, 0)` is the north-west corner of the mercator world and
+         * `MercatorPoint(1, 1, 0)` is the south-east corner. If you are familiar with
+         * [vector tiles](https://github.com/mapbox/vector-tile-spec) it may be helpful to think
+         * of the coordinate space as the `0/0/0` tile with an extent of `1`.
+         *
+         * The `z` dimension of `MercatorPoint` is conformal. A cube in the mercator coordinate space would be rendered as a cube.
+         */
+        export class MercatorPoint extends Array<number> {
+            /**
+             * Constructs a MercatorPoint.
+             * @param x A points x position in mercator units.
+             * @param y A points y position in mercator units.
+             * @param z A points z position in mercator units.
+             */
+            constructor(x: number, y: number, z?: number);
+            /**
+             * Converts a position into a mercator point.
+             * @param position Position to convert.
+             * @returns A mercator point.
+             */
+            static fromPosition(position: Position): MercatorPoint;
+            /**
+             * Converts an array of positions into an array of mercator points.
+             * @param positions Array of positions to convert.
+             * @returns An array of  mercator points.
+             */
+            static fromPositions(positions: Position[]): MercatorPoint[];
+            /**
+             * Converts an array of positions into a Float32Array of mercator xyz values.
+             * @param positions Array of positions to convert.
+             * @returns A Float32Array of mercator xyz values.
+             */
+            static toFloat32Array(positions: Position[]): Float32Array;
+            /**
+             * Converts a mercator point into a map position.
+             * @param mercator Mercator point to convert.
+             * @returns A map position.
+             */
+            static toPosition(mercator: MercatorPoint): Position;
+            /**
+             * Converts an array of mercator points into an array of map positions.
+             * @param mercators Mercator points to convert.
+             * @returns An array of map positions.
+             */
+            static toPositions(mercators: MercatorPoint[]): Position[];
+            /**
+             * Determine the Mercator scale factor for a given latitude, see
+             * https://en.wikipedia.org/wiki/Mercator_projection#Scale_factor
+             *
+             * At the equator the scale factor will be 1, which increases at higher latitudes.
+             *
+             * @param latitude Latitude
+             * @returns The mercator scale factor.
+             */
+            static mercatorScale(latitude: number): number;
+            /**
+             * Returns the distance of 1 meter in `MercatorPoint` units at this latitude.
+             *
+             * For coordinates in real world units using meters, this naturally provides the scale
+             * to transform into `MercatorPoint`s.
+             *
+             * @returns {number} Distance of 1 meter in `MercatorPoint` units.
+             */
+            static meterInMercatorUnits(latitude: number): number;
+        }
     }
 
     //control classes
@@ -817,7 +889,6 @@ declare namespace atlas {
              * @param newOptions The new options of the bubble layer.
              */
             setOptions(options: BubbleLayerOptions): void;
-
         }
 
         export interface LayerEvents {
@@ -1072,6 +1143,27 @@ declare namespace atlas {
              */
             setOptions(options: TileLayerOptions): void;
         }
+
+        /**
+         * Enables custom rendering logic with access to the WebGL context of the map.
+         */
+         export class WebGLLayer extends Layer {
+            /**
+             * Constructs a new WebGLLayer.
+             * @param id The id of the layer. If not specified a random one will be generated.
+             * @param options The options of the WebGL layer.
+            */
+            constructor(id?: string, options?: WebGLLayerOptions);
+            /**
+             * Gets the options of the WebGL layer.
+             */
+            getOptions(): WebGLLayerOptions;
+            /**
+             * Sets the options of the WebGL layer.
+             * @param options The new options of the WebGL layer.
+             */
+            setOptions(options: WebGLLayerOptions): void;
+        }
     }
 
     //source classes
@@ -1907,8 +1999,9 @@ declare namespace atlas {
         /**
          * Set the map control's style options. Any options not specified will default to their current values.
          * @param options The options for setting the style of the map control.
+         * @param diff [true] If false, forces a 'full' style update, removing the current style and building the given one instead of attempting a diff-based update. Defaults to true.
          */
-        setStyle(options?: StyleOptions): void;
+        setStyle(options?: StyleOptions, diff?: boolean): void;
         /**
          * Returns the map control's current style settings.
          */
@@ -1970,6 +2063,14 @@ declare namespace atlas {
          * Stops any animated transition that is currently underway.
          */
         stop(): void;
+        /**
+         * Trigger the rendering of a single frame.
+         * Use this method with WebGL layers to repaint the map when the layer's
+         * properties or properties associated with the layer's source change.
+         * Calling this multiple times before the next frame is rendered will still
+         * result in only a single frame being rendered.
+         */
+        triggerRepaint(): void;
         /**
          * The callback used when styleOptions.autoResize is true.
          */
@@ -2093,6 +2194,10 @@ declare namespace atlas {
          * Returns the options for the popup.
          */
         getOptions(): PopupOptions;
+        /**
+         * Returns popup container element.
+         */
+        getPopupContainer(): HTMLElement
         /**
          * Attaches the popup to the HTML document in a hidden state.
          * @param map The map.
@@ -3519,6 +3624,16 @@ declare namespace atlas {
         tileUrl?: string;
     }
 
+    /**
+     * Options used to render graphics in a WebGLLayer.
+     */
+     export interface WebGLLayerOptions extends LayerOptions {
+        /**
+         * An object that contains the rendering logic.
+         */
+        renderer?: WebGLRenderer;
+    }
+
     /**
      * Available styles for a Control.
      */
@@ -4126,6 +4241,10 @@ declare namespace atlas {
      * The options for the map's style.
      */
     export interface StyleOptions extends Options {
+        /**
+         * If true, the gl context will be created with MSAA antialiasing, which can be useful for antialiasing WebGL layers.
+         */
+        antialias?: boolean;
         /**
          * If true the map will automatically resize whenever the window's size changes.
          * Otherwise map.resize() must be called.
@@ -4177,6 +4296,11 @@ declare namespace atlas {
          * @default true
          */
         showLogo?: boolean;
+        /**
+         * Specifies if the map should display labels
+         * @default true
+         */
+        showLabels?: boolean;
         /**
          * Specifies if the map should render an outline around each tile and the tile ID.
          * These tile boundaries are useful for debugging.
@@ -4357,7 +4481,12 @@ declare namespace atlas {
          * Allows a callback responsible for acquiring an authentication token to be provided.
          * Literal value `"anonymous"`
          */
-        anonymous = "anonymous"
+        anonymous = "anonymous",
+        /**
+         * The shared access signature authentication mechanism. Allows a callback responsible for acquiring a token to be provided on requests.
+         * Literal value `"sas"`.
+         */
+        sas = "sas"
     }
 
     /**
@@ -4395,11 +4524,15 @@ declare namespace atlas {
          */
         aadInstance?: string;
         /**
-         * A callback to use with the anonymous authentication mechanism.
+         * A callback to use with the anonymous/sas authentication mechanism.
          * This callback will be responsible for resolving to a authentication token.
          * E.g. fetching a CORS protected token from an endpoint.
          */
         getToken?: getAuthTokenCallback;
+        /**
+         * Optionally provide an initial token for sas authentication.
+         */
+        sasToken?: string;
         /**
          * Optionally provide an existing `AuthenticationContext` from the ADAL.js library.
          * This authentication context will be used to acquire the AAD token.
@@ -4427,6 +4560,11 @@ declare namespace atlas {
          * @param getTokenCallback Callback function responsible for resolving to an authentication token.
          */
         setTokenCallbackFunction?(getTokenCallback: getAuthTokenCallback): void;
+        /**
+         * Sets the required options to configure the sas authentication method.
+         * @param getTokenCallback Callback function responsible for resolving to an authentication token.
+         */
+        setSasCallbackFunction?(getTokenCallback: getAuthTokenCallback): void;
     }
 
     export type ResourceType =
@@ -4443,21 +4581,21 @@ declare namespace atlas {
         | 'Thumbnail';
 
     /**
-     * Represents the contents of the style set.
+     * Represents the contents of map configuration holding a list of styles available to them.
      */
-    export interface StyleSet {
+    export interface MapConfiguration {
         created?: string;
-        defaultStyle: string;
+        defaultConfiguration: string;
         description?: string;
         id?: string;
-        styles: StyleSetStyle[];
+        configurations: MapConfigurationStyle[];
         version?: number;
     }
 
     /**
      * Represents the info for a single style.
      */
-    export interface StyleSetStyle {
+    export interface MapConfigurationStyle {
         copyright?: string;
         displayName?: string;
         name: string;
@@ -4493,10 +4631,9 @@ declare namespace atlas {
          */
         domain?: string;
         /**
-         * The style set of the map. Determines which styles are available to be picked
-         * and what do they consist of (style names, thumbnails, URLs, etc).
+         * The map configuration defines the set of styles available to the map. 
          */
-        styleSet?: StyleSet;
+        mapConfiguration?: string | MapConfiguration;
         /**
          * Enable accessibility
          * default: true
@@ -4584,6 +4721,75 @@ declare namespace atlas {
     export interface AggregateExpression extends Array<any> {
     }
 
+    /**
+     * Interface for rendering WebGL graphics in a WebGLLayer.
+     */
+    export interface WebGLRenderer {
+        /**
+         * Either "2d" or "3d". Defaults to "2d".
+         */
+        renderingMode?: "2d" | "3d";
+
+        /**
+         * Optional method called when the layer has been added to the Map.
+         * This gives the layer a chance to initialize gl resources and register event listeners.
+         * @param map The Map this WebGL layer was just added to.
+         * @param gl The gl context for the map.
+         */
+        onAdd?(map: Map, gl: WebGLRenderingContext): void;
+
+        /**
+         * Optional method called when the layer has been removed from the Map.
+         * This gives the layer a chance to clean up gl resources and event listeners.
+         * @param map The Map this WebGL layer was just added to.
+         * @param gl The gl context for the map.
+         */
+        onRemove?(map: Map, gl: WebGLRenderingContext): void;
+
+        /**
+         * Optional method called during a render frame to allow a layer to prepare resources
+         * or render into a texture.
+         *
+         * The layer cannot make any assumptions about the current GL state and must bind a framebuffer
+         * before rendering.
+         * @param gl The map's gl context.
+         * @param matrix The map's camera matrix. It projects spherical mercator coordinates to gl
+         *               coordinates. The mercator coordinate  [0, 0] represents the top left corner of
+         *               the mercator world and  [1, 1] represents the bottom right corner. When the
+         *               renderingMode is  "3d" , the z coordinate is conformal. A box with identical
+         *               x, y, and z lengths in mercator units would be rendered as a cube.
+         *               MercatorCoordinate .fromLatLng can be used to project a  LngLat to a mercator
+         *               coordinate.
+         */
+        prerender?(gl: WebGLRenderingContext, matrix: number[]): void;
+
+        /**
+         * Called during a render frame allowing the layer to draw into the GL context.
+         *
+         * The layer can assume blending and depth state is set to allow the layer to properly blend
+         * and clip other layers. The layer cannot make any other assumptions about the current GL state.
+         *
+         * If the layer needs to render to a texture, it should implement the prerender method to do this
+         * and only use the render method for drawing directly into the main framebuffer.
+         *
+         * The blend function is set to gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA). This expects
+         * colors to be provided in premultiplied alpha form where the r, g and b values are already
+         * multiplied by the a value. If you are unable to provide colors in premultiplied form you may
+         * want to change the blend function to
+         * gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA).
+         *
+         * @param gl The map's gl context.
+         * @param matrix The map's camera matrix. It projects spherical mercator coordinates to gl
+         *               coordinates. The mercator coordinate  [0, 0] represents the top left corner of
+         *               the mercator world and  [1, 1] represents the bottom right corner. When the
+         *               renderingMode is  "3d" , the z coordinate is conformal. A box with identical
+         *               x, y, and z lengths in mercator units would be rendered as a cube.
+         *               MercatorCoordinate .fromLatLng can be used to project a  LngLat to a mercator
+         *               coordinate.
+         */
+        render(gl: WebGLRenderingContext, matrix: number[]): void;
+    }
+
     /**
      * A manager for the map control's authentication.
      * Exposed through the authentication property of the atlas.Map class.
@@ -4683,11 +4889,11 @@ declare namespace atlas {
          */
         add(eventType: "stylechanged", callback: (e: StyleChangedEvent) => void): void;
         /**
-         * Adds a styleset change event to the map.
-         * @param eventType A styleset changed event name
+         * Adds a mapConfiguration change event to the map.
+         * @param eventType A mapConfiguration changed event name
          * @param callback The event handler callback
          */
-        add(eventType: "stylesetchanged", callback: (e: StyleSet) => void): void;
+        add(eventType: "mapconfigurationchanged", callback: (e: MapConfiguration) => void): void;
         /**
          * Adds a wheel event to the map.
          * @param eventType The wheel event name.
@@ -4964,7 +5170,7 @@ declare namespace atlas {
          * @param eventType The event name.
          * @param callback The event handler callback.
          */
-        remove(eventType: string, callback: (e: void | atlas.layer.Layer | MapEvent | MapDataEvent | MapMouseEvent | MapTouchEvent | MapMouseWheelEvent | atlas.source.Source | string | StyleSet) => void): void;
+        remove(eventType: string, callback: (e: void | atlas.layer.Layer | MapEvent | MapDataEvent | MapMouseEvent | MapTouchEvent | MapMouseWheelEvent | atlas.source.Source | string | MapConfiguration) => void): void;
         /**
          * Removes an event listener from the DataSource(s).
          * @param eventType The event name.