maplibre-gl 3.1.0 → 3.2.0-pre.2

package/src/source/geojson_source.ts

@@ -1,22 +1,23 @@
 import {Event, ErrorEvent, Evented} from '../util/evented';
 
 import {extend} from '../util/util';
-import EXTENT from '../data/extent';
+import {EXTENT} from '../data/extent';
 import {ResourceType} from '../util/request_manager';
-import browser from '../util/browser';
+import {browser} from '../util/browser';
 
 import type {Source} from './source';
-import type Map from '../ui/map';
-import type Dispatcher from '../util/dispatcher';
-import type Tile from './tile';
-import type Actor from '../util/actor';
+import type {Map} from '../ui/map';
+import type {Dispatcher} from '../util/dispatcher';
+import type {Tile} from './tile';
+import type {Actor} from '../util/actor';
 import type {Callback} from '../types/callback';
 import type {GeoJSONSourceSpecification, PromoteIdSpecification} from '@maplibre/maplibre-gl-style-spec';
 import type {GeoJSONSourceDiff} from './geojson_source_diff';
+import type {Options, ClusterProperties} from 'supercluster';
 
 export type GeoJSONSourceOptions = GeoJSONSourceSpecification & {
-    workerOptions?: any;
-    collectResourceTiming: boolean;
+    workerOptions?: WorkerOptions;
+    collectResourceTiming?: boolean;
 }
 
 export type GeoJsonSourceOptions = {
@@ -38,23 +39,28 @@ export type WorkerOptions = {
         linemetrics?: boolean;
         generateId?: boolean;
     };
-    superclusterOptions?: {
-        maxZoom?: number;
-        miniPoints?: number;
-        extent?: number;
-        radius?: number;
-        log?: boolean;
-        generateId?: boolean;
-    };
-    clusterProperties?: any;
+    superclusterOptions?: Options<any, any>;
+    clusterProperties?: ClusterProperties;
     fliter?: any;
     promoteId?: any;
     collectResourceTiming?: boolean;
 }
 
+/**
+ * The cluster options to set
+ */
 export type SetClusterOptions = {
+    /**
+     * Whether or not to cluster
+     */
     cluster?: boolean;
+    /**
+     * The cluster's max zoom
+     */
     clusterMaxZoom?: number;
+    /**
+     * The cluster's radius
+     */
     clusterRadius?: number;
 }
 
@@ -62,13 +68,18 @@ export type SetClusterOptions = {
  * A source containing GeoJSON.
  * (See the [Style Specification](https://maplibre.org/maplibre-style-spec/#sources-geojson) for detailed documentation of options.)
  *
+ * @group Sources
+ *
  * @example
+ * ```ts
  * map.addSource('some id', {
  *     type: 'geojson',
  *     data: 'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_ports.geojson'
  * });
+ * ```
  *
  * @example
+ * ```ts
  * map.addSource('some id', {
  *    type: 'geojson',
  *    data: {
@@ -86,8 +97,10 @@ export type SetClusterOptions = {
  *        }]
  *    }
  * });
+ * ```
  *
  * @example
+ * ```ts
  * map.getSource('some id').setData({
  *   "type": "FeatureCollection",
  *   "features": [{
@@ -99,12 +112,13 @@ export type SetClusterOptions = {
  *       }
  *   }]
  * });
- * @see [Draw GeoJSON points](https://maplibre.org/maplibre-gl-js-docs/example/geojson-markers/)
- * @see [Add a GeoJSON line](https://maplibre.org/maplibre-gl-js-docs/example/geojson-line/)
- * @see [Create a heatmap from points](https://maplibre.org/maplibre-gl-js-docs/example/heatmap/)
- * @see [Create and style clusters](https://maplibre.org/maplibre-gl-js-docs/example/cluster/)
+ * ```
+ * @see [Draw GeoJSON points](https://maplibre.org/maplibre-gl-js/docs/examples/geojson-markers/)
+ * @see [Add a GeoJSON line](https://maplibre.org/maplibre-gl-js/docs/examples/geojson-line/)
+ * @see [Create a heatmap from points](https://maplibre.org/maplibre-gl-js/docs/examples/heatmap/)
+ * @see [Create and style clusters](https://maplibre.org/maplibre-gl-js/docs/examples/cluster/)
  */
-class GeoJSONSource extends Evented implements Source {
+export class GeoJSONSource extends Evented implements Source {
     type: 'geojson';
     id: string;
     minzoom: number;
@@ -125,7 +139,7 @@ class GeoJSONSource extends Evented implements Source {
     _removed: boolean;
 
     /**
-     * @private
+     * @hidden
      */
     constructor(id: string, options: GeoJSONSourceOptions, dispatcher: Dispatcher, eventedParent: Evented) {
         super();
@@ -192,9 +206,9 @@ class GeoJSONSource extends Evented implements Source {
         }
     }
 
-    load() {
+    load = () => {
         this._updateWorkerData();
-    }
+    };
 
     onAdd(map: Map) {
         this.map = map;
@@ -204,10 +218,10 @@ class GeoJSONSource extends Evented implements Source {
     /**
      * Sets the GeoJSON data and re-renders the map.
      *
-     * @param {Object|string} data A GeoJSON data object or a URL to one. The latter is preferable in the case of large GeoJSON files.
-     * @returns {GeoJSONSource} this
+     * @param data - A GeoJSON data object or a URL to one. The latter is preferable in the case of large GeoJSON files.
+     * @returns `this`
      */
-    setData(data: GeoJSON.GeoJSON | string) {
+    setData(data: GeoJSON.GeoJSON | string): this {
         this._data = data;
         this._updateWorkerData();
 
@@ -226,10 +240,10 @@ class GeoJSONSource extends Evented implements Source {
      *
      * Updates are applied on a best-effort basis, updating an ID that does not exist will not result in an error.
      *
-     * @param {GeoJSONSourceDiff} diff The changes that need to be applied.
-     * @returns {GeoJSONSource} this
+     * @param diff - The changes that need to be applied.
+     * @returns `this`
      */
-    updateData(diff: GeoJSONSourceDiff) {
+    updateData(diff: GeoJSONSourceDiff): this {
         this._updateWorkerData(diff);
 
         return this;
@@ -237,14 +251,15 @@ class GeoJSONSource extends Evented implements Source {
 
     /**
      * To disable/enable clustering on the source options
-     * @param {SetClusterOptions} options The options to set
-     * @returns {GeoJSONSource} this
+     * @param options - The options to set
+     * @returns `this`
      * @example
+     * ```ts
      * map.getSource('some id').setClusterOptions({cluster: false});
      * map.getSource('some id').setClusterOptions({cluster: false, clusterRadius: 50, clusterMaxZoom: 14});
-     *
+     * ```
      */
-    setClusterOptions(options:SetClusterOptions) {
+    setClusterOptions(options: SetClusterOptions): this {
         this.workerOptions.cluster = options.cluster;
         if (options) {
             if (options.clusterRadius !== undefined) this.workerOptions.superclusterOptions.radius = options.clusterRadius;
@@ -257,11 +272,11 @@ class GeoJSONSource extends Evented implements Source {
     /**
      * For clustered sources, fetches the zoom at which the given cluster expands.
      *
-     * @param clusterId The value of the cluster's `cluster_id` property.
-     * @param callback A callback to be called when the zoom value is retrieved (`(error, zoom) => { ... }`).
-     * @returns {GeoJSONSource} this
+     * @param clusterId - The value of the cluster's `cluster_id` property.
+     * @param callback - A callback to be called when the zoom value is retrieved (`(error, zoom) => { ... }`).
+     * @returns `this`
      */
-    getClusterExpansionZoom(clusterId: number, callback: Callback<number>) {
+    getClusterExpansionZoom(clusterId: number, callback: Callback<number>): this {
         this.actor.send('geojson.getClusterExpansionZoom', {clusterId, source: this.id}, callback);
         return this;
     }
@@ -269,11 +284,11 @@ class GeoJSONSource extends Evented implements Source {
     /**
      * For clustered sources, fetches the children of the given cluster on the next zoom level (as an array of GeoJSON features).
      *
-     * @param clusterId The value of the cluster's `cluster_id` property.
-     * @param callback A callback to be called when the features are retrieved (`(error, features) => { ... }`).
-     * @returns {GeoJSONSource} this
+     * @param clusterId - The value of the cluster's `cluster_id` property.
+     * @param callback - A callback to be called when the features are retrieved (`(error, features) => { ... }`).
+     * @returns `this`
      */
-    getClusterChildren(clusterId: number, callback: Callback<Array<GeoJSON.Feature>>) {
+    getClusterChildren(clusterId: number, callback: Callback<Array<GeoJSON.Feature>>): this {
         this.actor.send('geojson.getClusterChildren', {clusterId, source: this.id}, callback);
         return this;
     }
@@ -281,29 +296,31 @@ class GeoJSONSource extends Evented implements Source {
     /**
      * For clustered sources, fetches the original points that belong to the cluster (as an array of GeoJSON features).
      *
-     * @param clusterId The value of the cluster's `cluster_id` property.
-     * @param limit The maximum number of features to return.
-     * @param offset The number of features to skip (e.g. for pagination).
-     * @param callback A callback to be called when the features are retrieved (`(error, features) => { ... }`).
-     * @returns {GeoJSONSource} this
+     * @param clusterId - The value of the cluster's `cluster_id` property.
+     * @param limit - The maximum number of features to return.
+     * @param offset - The number of features to skip (e.g. for pagination).
+     * @param callback - A callback to be called when the features are retrieved (`(error, features) => { ... }`).
+     * @returns `this`
      * @example
-     * // Retrieve cluster leaves on click
+     * Retrieve cluster leaves on click
+     * ```ts
      * map.on('click', 'clusters', function(e) {
-     *   var features = map.queryRenderedFeatures(e.point, {
+     *   let features = map.queryRenderedFeatures(e.point, {
      *     layers: ['clusters']
      *   });
      *
-     *   var clusterId = features[0].properties.cluster_id;
-     *   var pointCount = features[0].properties.point_count;
-     *   var clusterSource = map.getSource('clusters');
+     *   let clusterId = features[0].properties.cluster_id;
+     *   let pointCount = features[0].properties.point_count;
+     *   let clusterSource = map.getSource('clusters');
      *
      *   clusterSource.getClusterLeaves(clusterId, pointCount, 0, function(error, features) {
      *     // Print cluster leaves in the console
      *     console.log('Cluster leaves:', error, features);
      *   })
      * });
+     * ```
      */
-    getClusterLeaves(clusterId: number, limit: number, offset: number, callback: Callback<Array<GeoJSON.Feature>>) {
+    getClusterLeaves(clusterId: number, limit: number, offset: number, callback: Callback<Array<GeoJSON.Feature>>): this {
         this.actor.send('geojson.getClusterLeaves', {
             source: this.id,
             clusterId,
@@ -313,10 +330,11 @@ class GeoJSONSource extends Evented implements Source {
         return this;
     }
 
-    /*
+    /**
      * Responsible for invoking WorkerSource's geojson.loadData target, which
      * handles loading the geojson data and preparing to serve it up as tiles,
      * using geojson-vt or supercluster as appropriate.
+     * @param diff - the diff object
      */
     _updateWorkerData(diff?: GeoJSONSourceDiff) {
         const options = extend({}, this.workerOptions);
@@ -419,16 +437,14 @@ class GeoJSONSource extends Evented implements Source {
         this.actor.send('removeSource', {type: this.type, source: this.id});
     }
 
-    serialize() {
+    serialize = (): GeoJSONSourceSpecification => {
         return extend({}, this._options, {
             type: this.type,
             data: this._data
         });
-    }
+    };
 
     hasTransition() {
         return false;
     }
 }
-
-export default GeoJSONSource;

package/src/source/geojson_source_diff.ts

@@ -1,16 +1,53 @@
+/**
+ * A way to indentify a feature, either by string or by number
+ */
 export type GeoJSONFeatureId = number | string;
-export interface GeoJSONSourceDiff {
+
+/**
+ * The geojson source diff object
+ */
+export type GeoJSONSourceDiff = {
+    /**
+     * When set to `true` it will remove all features
+     */
     removeAll?: boolean;
+    /**
+     * An array of features IDs to remove
+     */
     remove?: Array<GeoJSONFeatureId>;
+    /**
+     * An array of features to add
+     */
     add?: Array<GeoJSON.Feature>;
+    /**
+     * An array of update objects
+     */
     update?: Array<GeoJSONFeatureDiff>;
 }
 
-export interface GeoJSONFeatureDiff {
+/**
+ * A geojson feature diff object
+ */
+export type GeoJSONFeatureDiff = {
+    /**
+     * The feature ID
+     */
     id: GeoJSONFeatureId;
+    /**
+     * If it's a new geometry, place it here
+     */
     newGeometry?: GeoJSON.Geometry;
+    /**
+     * Setting to `true` will remove all preperties
+     */
     removeAllProperties?: boolean;
+    /**
+     * The properties keys to remove
+     */
     removeProperties?: Array<string>;
+    /**
+     * The properties to add or update along side their values
+     */
     addOrUpdateProperties?: Array<{key: string; value: any}>;
 }
 

package/src/source/geojson_worker_source.test.ts

@@ -1,9 +1,9 @@
-import GeoJSONWorkerSource, {LoadGeoJSONParameters} from './geojson_worker_source';
-import StyleLayerIndex from '../style/style_layer_index';
+import {GeoJSONWorkerSource, LoadGeoJSONParameters} from './geojson_worker_source';
+import {StyleLayerIndex} from '../style/style_layer_index';
 import {OverscaledTileID} from './tile_id';
 import perf from '../util/performance';
 import {LayerSpecification} from '@maplibre/maplibre-gl-style-spec';
-import Actor from '../util/actor';
+import {Actor} from '../util/actor';
 import {WorkerTileParameters} from './worker_source';
 import {setPerformance} from '../util/test/util';
 import {type FakeServer, fakeServer} from 'nise';

package/src/source/geojson_worker_source.ts

@@ -2,11 +2,11 @@ import {getJSON} from '../util/ajax';
 
 import {RequestPerformance} from '../util/performance';
 import rewind from '@mapbox/geojson-rewind';
-import GeoJSONWrapper from './geojson_wrapper';
+import {GeoJSONWrapper} from './geojson_wrapper';
 import vtpbf from 'vt-pbf';
-import Supercluster from 'supercluster';
+import Supercluster, {type Options, type ClusterProperties} from 'supercluster';
 import geojsonvt from 'geojson-vt';
-import VectorTileWorkerSource from './vector_tile_worker_source';
+import {VectorTileWorkerSource} from './vector_tile_worker_source';
 import {createExpression} from '@maplibre/maplibre-gl-style-spec';
 
 import type {
@@ -14,8 +14,8 @@ import type {
     WorkerTileCallback,
 } from '../source/worker_source';
 
-import type Actor from '../util/actor';
-import type StyleLayerIndex from '../style/style_layer_index';
+import type {Actor} from '../util/actor';
+import type {StyleLayerIndex} from '../style/style_layer_index';
 
 import type {LoadVectorDataCallback} from './vector_tile_worker_source';
 import type {RequestParameters, ResponseCallback} from '../util/ajax';
@@ -25,13 +25,16 @@ import {isUpdateableGeoJSON, type GeoJSONSourceDiff, applySourceDiff, toUpdateab
 
 export type LoadGeoJSONParameters = {
     request?: RequestParameters;
+    /**
+     * Literal GeoJSON data. Must be provided if `request.url` is not.
+     */
     data?: string;
     dataDiff?: GeoJSONSourceDiff;
     source: string;
     cluster: boolean;
-    superclusterOptions?: any;
+    superclusterOptions?: Options<any, any>;
     geojsonVtOptions?: any;
-    clusterProperties?: any;
+    clusterProperties?: ClusterProperties;
     filter?: Array<unknown>;
     promoteId?: string;
 };
@@ -82,10 +85,8 @@ function loadGeoJSONTile(params: WorkerTileParameters, callback: LoadVectorDataC
  * representation.  To do so, create it with
  * `new GeoJSONWorkerSource(actor, layerIndex, customLoadGeoJSONFunction)`.
  * For a full example, see [mapbox-gl-topojson](https://github.com/developmentseed/mapbox-gl-topojson).
- *
- * @private
  */
-class GeoJSONWorkerSource extends VectorTileWorkerSource {
+export class GeoJSONWorkerSource extends VectorTileWorkerSource {
     _pendingCallback: Callback<{
         resourceTiming?: {[_: string]: Array<PerformanceResourceTiming>};
         abandoned?: boolean;
@@ -95,10 +96,9 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
     _dataUpdateable = new Map<GeoJSONFeatureId, GeoJSON.Feature>();
 
     /**
-     * @param [loadGeoJSON] Optional method for custom loading/parsing of
+     * @param loadGeoJSON - Optional method for custom loading/parsing of
      * GeoJSON based on parameters passed from the main-thread Source.
      * See {@link GeoJSONWorkerSource#loadGeoJSON}.
-     * @private
      */
     constructor(actor: Actor, layerIndex: StyleLayerIndex, availableImages: Array<string>, loadGeoJSON?: LoadGeoJSON | null) {
         super(actor, layerIndex, availableImages, loadGeoJSONTile);
@@ -119,9 +119,8 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
      * When a `loadData` request comes in while a previous one is being processed,
      * the previous one is aborted.
      *
-     * @param params
-     * @param callback
-     * @private
+     * @param params - the parameters
+     * @param callback - the callback for completion or error
      */
     loadData(params: LoadGeoJSONParameters, callback: Callback<{
         resourceTiming?: {[_: string]: Array<PerformanceResourceTiming>};
@@ -188,9 +187,8 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
     * If the tile is loaded, uses the implementation in VectorTileWorkerSource.
     * Otherwise, such as after a setData() call, we load the tile fresh.
     *
-    * @param params
-    * @param params.uid The UID for this tile.
-    * @private
+    * @param params - the parameters
+    * @param callback - the callback for completion or error
     */
     reloadTile(params: WorkerTileParameters, callback: WorkerTileCallback) {
         const loaded = this.loaded,
@@ -210,11 +208,9 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
      * GeoJSON is loaded and parsed from `params.url` if it exists, or else
      * expected as a literal (string or object) `params.data`.
      *
-     * @param params
-     * @param [params.url] A URL to the remote GeoJSON data.
-     * @param [params.data] Literal GeoJSON data. Must be provided if `params.url` is not.
-     * @returns {Cancelable} A Cancelable object.
-     * @private
+     * @param params - the parameters
+     * @param callback - the callback for completion or error
+     * @returns A Cancelable object.
      */
     loadGeoJSON = (params: LoadGeoJSONParameters, callback: ResponseCallback<any>): Cancelable => {
         const {promoteId} = params;
@@ -297,7 +293,7 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
     }
 }
 
-function getSuperclusterOptions({superclusterOptions, clusterProperties}: { superclusterOptions?: any; clusterProperties?: any}) {
+function getSuperclusterOptions({superclusterOptions, clusterProperties}: LoadGeoJSONParameters) {
     if (!clusterProperties || !superclusterOptions) return superclusterOptions;
 
     const mapExpressions = {};
@@ -335,5 +331,3 @@ function getSuperclusterOptions({superclusterOptions, clusterProperties}: { supe
 
     return superclusterOptions;
 }
-
-export default GeoJSONWorkerSource;

package/src/source/geojson_wrapper.test.ts

@@ -1,4 +1,4 @@
-import Wrapper from './geojson_wrapper';
+import {GeoJSONWrapper} from './geojson_wrapper';
 
 describe('geojsonwrapper', () => {
     test('linestring', () => {
@@ -8,7 +8,7 @@ describe('geojsonwrapper', () => {
             tags: {hello: 'world'}
         }];
 
-        const wrap = new Wrapper(features as any);
+        const wrap = new GeoJSONWrapper(features as any);
         const feature = wrap.feature(0);
 
         expect(feature).toBeTruthy();
@@ -25,7 +25,7 @@ describe('geojsonwrapper', () => {
             tags: {}
         }];
 
-        const wrap = new Wrapper(features as any);
+        const wrap = new GeoJSONWrapper(features as any);
         const feature = wrap.feature(0);
         expect(feature.loadGeometry()).toEqual([[{x: 0, y: 1}]]);
     });

package/src/source/geojson_wrapper.ts

@@ -3,7 +3,7 @@ import Point from '@mapbox/point-geometry';
 import mvt from '@mapbox/vector-tile';
 import type {VectorTileFeature, VectorTileLayer, VectorTile} from '@mapbox/vector-tile';
 const toGeoJSON = mvt.VectorTileFeature.prototype.toGeoJSON;
-import EXTENT from '../data/extent';
+import {EXTENT} from '../data/extent';
 
 // The feature type used by geojson-vt and supercluster. Should be extracted to
 // global type and used in module definitions for those two modules.
@@ -70,7 +70,7 @@ class FeatureWrapper implements VectorTileFeature {
     }
 }
 
-class GeoJSONWrapper implements VectorTile, VectorTileLayer {
+export class GeoJSONWrapper implements VectorTile, VectorTileLayer {
     layers: {[_: string]: VectorTileLayer};
     name: string;
     extent: number;
@@ -89,5 +89,3 @@ class GeoJSONWrapper implements VectorTile, VectorTileLayer {
         return new FeatureWrapper(this._features[i]);
     }
 }
-
-export default GeoJSONWrapper;

package/src/source/image_source.test.ts

@@ -1,16 +1,17 @@
-import ImageSource from './image_source';
+import {ImageSource} from './image_source';
 import {Evented} from '../util/evented';
-import Transform from '../geo/transform';
+import {Transform} from '../geo/transform';
 import {extend} from '../util/util';
 import {fakeXhr} from 'nise';
 import {RequestManager} from '../util/request_manager';
-import Dispatcher from '../util/dispatcher';
+import {Dispatcher} from '../util/dispatcher';
 import {stubAjaxGetImage} from '../util/test/util';
-import Tile from './tile';
+import {Tile} from './tile';
 import {OverscaledTileID} from './tile_id';
-import VertexBuffer from '../gl/vertex_buffer';
-import SegmentVector from '../data/segment';
-import Texture from '../render/texture';
+import {VertexBuffer} from '../gl/vertex_buffer';
+import {SegmentVector} from '../data/segment';
+import {Texture} from '../render/texture';
+import type {ImageSourceSpecification} from '@maplibre/maplibre-gl-style-spec';
 
 function createSource(options) {
     options = extend({
@@ -177,7 +178,7 @@ describe('ImageSource', () => {
     test('serialize url and coordinates', () => {
         const source = createSource({url: '/image.png'});
 
-        const serialized = source.serialize();
+        const serialized = source.serialize() as ImageSourceSpecification;
         expect(serialized.type).toBe('image');
         expect(serialized.url).toBe('/image.png');
         expect(serialized.coordinates).toEqual([[0, 0], [1, 0], [1, 1], [0, 1]]);