maplibre-gl 3.1.0 → 3.2.0-pre.2

package/src/source/image_source.ts

@@ -1,34 +1,57 @@
 import {CanonicalTileID} from './tile_id';
 import {Event, ErrorEvent, Evented} from '../util/evented';
-import ImageRequest from '../util/image_request';
+import {ImageRequest} from '../util/image_request';
 import {ResourceType} from '../util/request_manager';
-import EXTENT from '../data/extent';
+import {EXTENT} from '../data/extent';
 import {RasterBoundsArray} from '../data/array_types.g';
 import rasterBoundsAttributes from '../data/raster_bounds_attributes';
-import SegmentVector from '../data/segment';
-import Texture from '../render/texture';
-import MercatorCoordinate from '../geo/mercator_coordinate';
+import {SegmentVector} from '../data/segment';
+import {Texture} from '../render/texture';
+import {MercatorCoordinate} from '../geo/mercator_coordinate';
 
 import type {Source} from './source';
 import type {CanvasSourceSpecification} from './canvas_source';
-import type Map from '../ui/map';
-import type Dispatcher from '../util/dispatcher';
-import type Tile from './tile';
+import type {Map} from '../ui/map';
+import type {Dispatcher} from '../util/dispatcher';
+import type {Tile} from './tile';
 import type {Callback} from '../types/callback';
-import type VertexBuffer from '../gl/vertex_buffer';
+import type {VertexBuffer} from '../gl/vertex_buffer';
 import type {
     ImageSourceSpecification,
     VideoSourceSpecification
 } from '@maplibre/maplibre-gl-style-spec';
 import {Cancelable} from '../types/cancelable';
 
+/**
+ * Four geographical coordinates,
+ * represented as arrays of longitude and latitude numbers, which define the corners of the image.
+ * The coordinates start at the top left corner of the image and proceed in clockwise order.
+ * They do not have to represent a rectangle.
+ */
 export type Coordinates = [[number, number], [number, number], [number, number], [number, number]];
 
+/**
+ * The options object for the {@link ImageSource#updateImage} method
+ */
+export type UpdateImageOptions = {
+    /**
+     * Required image URL.
+     */
+    url: string;
+    /**
+     * The image coordinates
+     */
+    coordinates?: Coordinates;
+}
+
 /**
  * A data source containing an image.
  * (See the [Style Specification](https://maplibre.org/maplibre-style-spec/#sources-image) for detailed documentation of options.)
  *
+ * @group Sources
+ *
  * @example
+ * ```ts
  * // add to map
  * map.addSource('some id', {
  *    type: 'image',
@@ -42,7 +65,7 @@ export type Coordinates = [[number, number], [number, number], [number, number],
  * });
  *
  * // update coordinates
- * var mySource = map.getSource('some id');
+ * let mySource = map.getSource('some id');
  * mySource.setCoordinates([
  *     [-76.54335737228394, 39.18579907229748],
  *     [-76.52803659439087, 39.1838364847587],
@@ -62,8 +85,9 @@ export type Coordinates = [[number, number], [number, number], [number, number],
  * })
  *
  * map.removeSource('some id');  // remove
+ * ```
  */
-class ImageSource extends Evented implements Source {
+export class ImageSource extends Evented implements Source {
     type: string;
     id: string;
     minzoom: number;
@@ -86,7 +110,7 @@ class ImageSource extends Evented implements Source {
     _request: Cancelable;
 
     /**
-     * @private
+     * @hidden
      */
     constructor(id: string, options: ImageSourceSpecification | VideoSourceSpecification | CanvasSourceSpecification, dispatcher: Dispatcher, eventedParent: Evented) {
         super();
@@ -106,7 +130,7 @@ class ImageSource extends Evented implements Source {
         this.options = options;
     }
 
-    load(newCoordinates?: Coordinates, successCallback?: () => void) {
+    load = (newCoordinates?: Coordinates, successCallback?: () => void) => {
         this._loaded = false;
         this.fire(new Event('dataloading', {dataType: 'source'}));
 
@@ -129,7 +153,7 @@ class ImageSource extends Evented implements Source {
                 this._finishLoading();
             }
         });
-    }
+    };
 
     loaded(): boolean {
         return this._loaded;
@@ -139,18 +163,10 @@ class ImageSource extends Evented implements Source {
      * Updates the image URL and, optionally, the coordinates. To avoid having the image flash after changing,
      * set the `raster-fade-duration` paint property on the raster layer to 0.
      *
-     * @param {Object} options Options object.
-     * @param {string} [options.url] Required image URL.
-     * @param {Array<Array<number>>} [options.coordinates] Four geographical coordinates,
-     * represented as arrays of longitude and latitude numbers, which define the corners of the image.
-     * The coordinates start at the top left corner of the image and proceed in clockwise order.
-     * They do not have to represent a rectangle.
-     * @returns {ImageSource} this
+     * @param options - The options object.
+     * @returns `this`
      */
-    updateImage(options: {
-        url: string;
-        coordinates?: Coordinates;
-    }) {
+    updateImage(options: UpdateImageOptions): this {
         if (!options.url) {
             return this;
         }
@@ -187,13 +203,13 @@ class ImageSource extends Evented implements Source {
     /**
      * Sets the image's coordinates and re-renders the map.
      *
-     * @param {Array<Array<number>>} coordinates Four geographical coordinates,
+     * @param coordinates - Four geographical coordinates,
      * represented as arrays of longitude and latitude numbers, which define the corners of the image.
      * The coordinates start at the top left corner of the image and proceed in clockwise order.
      * They do not have to represent a rectangle.
-     * @returns {ImageSource} this
+     * @returns `this`
      */
-    setCoordinates(coordinates: Coordinates) {
+    setCoordinates(coordinates: Coordinates): this {
         this.coordinates = coordinates;
 
         // Calculate which mercator tile is suitable for rendering the video in
@@ -231,7 +247,7 @@ class ImageSource extends Evented implements Source {
         return this;
     }
 
-    prepare() {
+    prepare = () => {
         if (Object.keys(this.tiles).length === 0 || !this.image) {
             return;
         }
@@ -265,7 +281,7 @@ class ImageSource extends Evented implements Source {
         if (newTilesLoaded) {
             this.fire(new Event('data', {dataType: 'source', sourceDataType: 'idle', sourceId: this.id}));
         }
-    }
+    };
 
     loadTile(tile: Tile, callback: Callback<void>) {
         // We have a single tile -- whose coordinates are this.tileID -- that
@@ -284,13 +300,13 @@ class ImageSource extends Evented implements Source {
         }
     }
 
-    serialize(): any {
+    serialize = (): ImageSourceSpecification | VideoSourceSpecification | CanvasSourceSpecification => {
         return {
             type: 'image',
             url: this.options.url,
             coordinates: this.coordinates
         };
-    }
+    };
 
     hasTransition() {
         return false;
@@ -301,7 +317,7 @@ class ImageSource extends Evented implements Source {
  * Given a list of coordinates, get their center as a coordinate.
  *
  * @returns centerpoint
- * @private
+ * @hidden
  */
 export function getCoordinatesCenterTileID(coords: Array<MercatorCoordinate>) {
     let minX = Infinity;
@@ -327,5 +343,3 @@ export function getCoordinatesCenterTileID(coords: Array<MercatorCoordinate>) {
         Math.floor((minX + maxX) / 2 * tilesAtZoom),
         Math.floor((minY + maxY) / 2 * tilesAtZoom));
 }
-
-export default ImageSource;

package/src/source/load_tilejson.ts

@@ -2,7 +2,7 @@ import {pick, extend} from '../util/util';
 
 import {getJSON} from '../util/ajax';
 import {ResourceType} from '../util/request_manager';
-import browser from '../util/browser';
+import {browser} from '../util/browser';
 
 import type {RequestManager} from '../util/request_manager';
 import type {Callback} from '../types/callback';
@@ -10,7 +10,7 @@ import type {TileJSON} from '../types/tilejson';
 import type {Cancelable} from '../types/cancelable';
 import type {RasterDEMSourceSpecification, RasterSourceSpecification, VectorSourceSpecification} from '@maplibre/maplibre-gl-style-spec';
 
-export default function loadTileJson(
+export function loadTileJson(
     options: RasterSourceSpecification | RasterDEMSourceSpecification | VectorSourceSpecification,
     requestManager: RequestManager,
     callback: Callback<TileJSON>

package/src/source/pixels_to_tile_units.ts

@@ -1,4 +1,4 @@
-import EXTENT from '../data/extent';
+import {EXTENT} from '../data/extent';
 
 import type {OverscaledTileID} from './tile_id';
 
@@ -12,9 +12,8 @@ import type {OverscaledTileID} from './tile_id';
  * translation by pixelsToTileUnits(30, 6.5) tile units.
  *
  * @returns value in tile units
- * @private
  */
-export default function pixelsToTileUnits(
+export function pixelsToTileUnits(
     tile: {
         tileID: OverscaledTileID;
         tileSize: number;

package/src/source/query_features.test.ts

@@ -2,10 +2,10 @@ import {
     queryRenderedFeatures,
     querySourceFeatures
 } from './query_features';
-import SourceCache from './source_cache';
-import Transform from '../geo/transform';
+import {SourceCache} from './source_cache';
+import {Transform} from '../geo/transform';
 import Point from '@mapbox/point-geometry';
-import Dispatcher from '../util/dispatcher';
+import {Dispatcher} from '../util/dispatcher';
 
 describe('QueryFeatures#rendered', () => {
     test('returns empty object if source returns no tiles', () => {

package/src/source/query_features.ts

@@ -1,13 +1,56 @@
-import type SourceCache from './source_cache';
-import type StyleLayer from '../style/style_layer';
-import type CollisionIndex from '../symbol/collision_index';
-import type Transform from '../geo/transform';
+import type {SourceCache} from './source_cache';
+import type {StyleLayer} from '../style/style_layer';
+import type {CollisionIndex} from '../symbol/collision_index';
+import type {Transform} from '../geo/transform';
 import type {RetainedQueryData} from '../symbol/placement';
 import type {FilterSpecification} from '@maplibre/maplibre-gl-style-spec';
 import type {MapGeoJSONFeature} from '../util/vectortile_to_geojson';
 import type Point from '@mapbox/point-geometry';
 import {mat4} from 'gl-matrix';
 
+/**
+ * Options to pass to query the map for the rendered features
+ */
+export type QueryRenderedFeaturesOptions = {
+    /**
+     * An array of [style layer IDs](https://maplibre.org/maplibre-style-spec/#layer-id) for the query to inspect.
+     * Only features within these layers will be returned. If this parameter is undefined, all layers will be checked.
+     */
+    layers?: Array<string>;
+    /**
+     * A [filter](https://maplibre.org/maplibre-style-spec/layers/#filter) to limit query results.
+     */
+    filter?: FilterSpecification;
+    /**
+     * An array of string representing the available images
+     */
+    availableImages?: Array<string>;
+    /**
+     * Whether to check if the [options.filter] conforms to the MapLibre Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function.
+     */
+    validate?: boolean;
+};
+
+/**
+ * The options object related to the {@link Map#queryRenderedFeatures} method
+ */
+export type QuerySourceFeatureOptions = {
+    /**
+     * The name of the source layer to query. *For vector tile sources, this parameter is required.* For GeoJSON sources, it is ignored.
+     */
+    sourceLayer?: string;
+    /**
+     * A [filter](https://maplibre.org/maplibre-style-spec/layers/#filter)
+     * to limit query results.
+     */
+    filter?: FilterSpecification;
+    /**
+     * Whether to check if the [parameters.filter] conforms to the MapLibre Style Specification. Disabling validation is a performance optimization that should only be used if you have previously validated the values you will be passing to this function.
+     * @defaultValue true
+     */
+    validate?: boolean;
+}
+
 /*
  * Returns a matrix that can be used to convert from tile coordinates to viewport pixel coordinates.
  */
@@ -42,11 +85,7 @@ export function queryRenderedFeatures(
     styleLayers: {[_: string]: StyleLayer},
     serializedLayers: {[_: string]: any},
     queryGeometry: Array<Point>,
-    params: {
-        filter: FilterSpecification;
-        layers: Array<string>;
-        availableImages: Array<string>;
-    },
+    params: QueryRenderedFeaturesOptions,
     transform: Transform
 ): { [key: string]: Array<{featureIndex: number; feature: MapGeoJSONFeature}> } {
 
@@ -94,11 +133,7 @@ export function queryRenderedSymbols(styleLayers: {[_: string]: StyleLayer},
     serializedLayers: {[_: string]: StyleLayer},
     sourceCaches: {[_: string]: SourceCache},
     queryGeometry: Array<Point>,
-    params: {
-        filter: FilterSpecification;
-        layers: Array<string>;
-        availableImages: Array<string>;
-    },
+    params: QueryRenderedFeaturesOptions,
     collisionIndex: CollisionIndex,
     retainedQueryData: {
         [_: number]: RetainedQueryData;
@@ -166,11 +201,7 @@ export function queryRenderedSymbols(styleLayers: {[_: string]: StyleLayer},
     return result;
 }
 
-export function querySourceFeatures(sourceCache: SourceCache, params: {
-    sourceLayer?: string;
-    filter?: FilterSpecification;
-    validate?: boolean;
-}) {
+export function querySourceFeatures(sourceCache: SourceCache, params: QuerySourceFeatureOptions) {
     const tiles = sourceCache.getRenderableIds().map((id) => {
         return sourceCache.getTileByID(id);
     });

package/src/source/raster_dem_tile_source.test.ts

@@ -1,9 +1,9 @@
 import {fakeServer, FakeServer} from 'nise';
-import RasterDEMTileSource from './raster_dem_tile_source';
+import {RasterDEMTileSource} from './raster_dem_tile_source';
 import {OverscaledTileID} from './tile_id';
 import {RequestManager} from '../util/request_manager';
-import Dispatcher from '../util/dispatcher';
-import Tile from './tile';
+import {Dispatcher} from '../util/dispatcher';
+import {Tile} from './tile';
 
 function createSource(options, transformCallback?) {
     const source = new RasterDEMTileSource('id', options, {send() {}} as any as Dispatcher, options.eventedParent);

package/src/source/raster_dem_tile_source.ts

@@ -1,22 +1,38 @@
-import ImageRequest from '../util/image_request';
+import {ImageRequest} from '../util/image_request';
 import {ResourceType} from '../util/request_manager';
 import {extend, isImageBitmap} from '../util/util';
 import {Evented} from '../util/evented';
-import browser from '../util/browser';
-import offscreenCanvasSupported from '../util/offscreen_canvas_supported';
+import {browser} from '../util/browser';
+import {offscreenCanvasSupported} from '../util/offscreen_canvas_supported';
 import {OverscaledTileID} from './tile_id';
-import RasterTileSource from './raster_tile_source';
+import {RasterTileSource} from './raster_tile_source';
 // ensure DEMData is registered for worker transfer on main thread:
 import '../data/dem_data';
 
 import type {Source} from './source';
-import type Dispatcher from '../util/dispatcher';
-import type Tile from './tile';
+import type {Dispatcher} from '../util/dispatcher';
+import type {Tile} from './tile';
 import type {Callback} from '../types/callback';
 import type {RasterDEMSourceSpecification} from '@maplibre/maplibre-gl-style-spec';
 import type {ExpiryData} from '../util/ajax';
 
-class RasterDEMTileSource extends RasterTileSource implements Source {
+/**
+ * A source containing raster DEM tiles (See the [Style Specification](https://maplibre.org/maplibre-style-spec/) for detailed documentation of options.)
+ * This source can be used to show hillshading and 3D terrain
+ *
+ * @group Sources
+ *
+ * @example
+ * ```ts
+ * map.addSource('raster-dem-source', {
+ *      type: 'raster-dem',
+ *      url: 'https://demotiles.maplibre.org/terrain-tiles/tiles.json',
+ *      tileSize: 256
+ * });
+ * ```
+ * @see [3D Terrain](https://maplibre.org/maplibre-gl-js/docs/examples/3d-terrain/)
+ */
+export class RasterDEMTileSource extends RasterTileSource implements Source {
     encoding: 'mapbox' | 'terrarium';
 
     constructor(id: string, options: RasterDEMSourceSpecification, dispatcher: Dispatcher, eventedParent: Evented) {
@@ -132,7 +148,4 @@ class RasterDEMTileSource extends RasterTileSource implements Source {
             tile.actor.send('removeDEMTile', {uid: tile.uid, source: this.id});
         }
     }
-
 }
-
-export default RasterDEMTileSource;

package/src/source/raster_dem_tile_worker_source.test.ts

@@ -1,5 +1,5 @@
-import RasterDEMTileWorkerSource from './raster_dem_tile_worker_source';
-import DEMData from '../data/dem_data';
+import {RasterDEMTileWorkerSource} from './raster_dem_tile_worker_source';
+import {DEMData} from '../data/dem_data';
 import {WorkerDEMTileParameters} from './worker_source';
 
 describe('loadTile', () => {

package/src/source/raster_dem_tile_worker_source.ts

@@ -1,6 +1,6 @@
-import DEMData from '../data/dem_data';
+import {DEMData} from '../data/dem_data';
 import {RGBAImage} from '../util/image';
-import type Actor from '../util/actor';
+import type {Actor} from '../util/actor';
 import type {
     WorkerDEMTileParameters,
     WorkerDEMTileCallback,
@@ -8,7 +8,7 @@ import type {
 } from './worker_source';
 import {isImageBitmap} from '../util/util';
 
-class RasterDEMTileWorkerSource {
+export class RasterDEMTileWorkerSource {
     actor: Actor;
     loaded: {[_: string]: DEMData};
     offscreenCanvas: OffscreenCanvas;
@@ -54,5 +54,3 @@ class RasterDEMTileWorkerSource {
         }
     }
 }
-
-export default RasterDEMTileWorkerSource;

package/src/source/raster_tile_source.test.ts

@@ -1,9 +1,9 @@
-import RasterTileSource from './raster_tile_source';
+import {RasterTileSource} from './raster_tile_source';
 import {OverscaledTileID} from './tile_id';
 import {RequestManager} from '../util/request_manager';
-import Dispatcher from '../util/dispatcher';
+import {Dispatcher} from '../util/dispatcher';
 import {fakeServer, FakeServer} from 'nise';
-import Tile from './tile';
+import {Tile} from './tile';
 import {stubAjaxGetImage} from '../util/test/util';
 
 function createSource(options, transformCallback?) {

package/src/source/raster_tile_source.ts

@@ -1,18 +1,18 @@
 import {extend, pick} from '../util/util';
 
-import ImageRequest from '../util/image_request';
+import {ImageRequest} from '../util/image_request';
 
 import {ResourceType} from '../util/request_manager';
 import {Event, ErrorEvent, Evented} from '../util/evented';
-import loadTileJSON from './load_tilejson';
-import TileBounds from './tile_bounds';
-import Texture from '../render/texture';
+import {loadTileJson} from './load_tilejson';
+import {TileBounds} from './tile_bounds';
+import {Texture} from '../render/texture';
 
 import type {Source} from './source';
 import type {OverscaledTileID} from './tile_id';
-import type Map from '../ui/map';
-import type Dispatcher from '../util/dispatcher';
-import type Tile from './tile';
+import type {Map} from '../ui/map';
+import type {Dispatcher} from '../util/dispatcher';
+import type {Tile} from './tile';
 import type {Callback} from '../types/callback';
 import type {Cancelable} from '../types/cancelable';
 import type {
@@ -20,7 +20,36 @@ import type {
     RasterDEMSourceSpecification
 } from '@maplibre/maplibre-gl-style-spec';
 
-class RasterTileSource extends Evented implements Source {
+/**
+ * A source containing raster tiles (See the [Style Specification](https://maplibre.org/maplibre-style-spec/) for detailed documentation of options.)
+ *
+ * @group Sources
+ *
+ * @example
+ * ```ts
+ * map.addSource('raster-source', {
+ *     'type': 'raster',
+ *     'tiles': ['https://stamen-tiles.a.ssl.fastly.net/watercolor/{z}/{x}/{y}.jpg'],
+ *     'tileSize': 256,
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * map.addSource('wms-test-source', {
+ *      'type': 'raster',
+ * // use the tiles option to specify a WMS tile source URL
+ *      'tiles': [
+ *          'https://img.nj.gov/imagerywms/Natural2015?bbox={bbox-epsg-3857}&format=image/png&service=WMS&version=1.1.1&request=GetMap&srs=EPSG:3857&transparent=true&width=256&height=256&layers=Natural2015'
+ *      ],
+ *      'tileSize': 256
+ * });
+ * ```
+ * @see [Add a raster tile source](https://maplibre.org/maplibre-gl-js/docs/examples/map-tiles/)
+ * @see [Add a WMS source](https://maplibre.org/maplibre-gl-js/docs/examples/wms/)
+ * @see [Display a satellite map](https://maplibre.org/maplibre-gl-js/docs/examples/satellite-map/)
+ */
+export class RasterTileSource extends Evented implements Source {
     type: 'raster' | 'raster-dem';
     id: string;
     minzoom: number;
@@ -61,7 +90,7 @@ class RasterTileSource extends Evented implements Source {
     load() {
         this._loaded = false;
         this.fire(new Event('dataloading', {dataType: 'source'}));
-        this._tileJSONRequest = loadTileJSON(this._options, this.map._requestManager, (err, tileJSON) => {
+        this._tileJSONRequest = loadTileJson(this._options, this.map._requestManager, (err, tileJSON) => {
             this._tileJSONRequest = null;
             this._loaded = true;
             if (err) {
@@ -155,5 +184,3 @@ class RasterTileSource extends Evented implements Source {
         return false;
     }
 }
-
-export default RasterTileSource;

package/src/source/rtl_text_plugin.ts

@@ -1,5 +1,5 @@
 import {getArrayBuffer} from '../util/ajax';
-import browser from '../util/browser';
+import {browser} from '../util/browser';
 import {Event, Evented} from '../util/evented';
 import {isWorker} from '../util/util';
 
@@ -16,6 +16,9 @@ export type PluginState = {
     pluginURL: string;
 };
 
+/**
+ * An error callback
+ */
 type ErrorCallback = (error?: Error | null) => void;
 type PluginStateSyncCallback = (state: PluginState) => void;
 let _completionCallback = null;