maplibre-gl 3.1.0 → 3.2.0-pre.2

package/src/ui/popup.ts

@@ -1,14 +1,14 @@
-import {extend, bindAll} from '../util/util';
+import {extend} from '../util/util';
 import {Event, Evented} from '../util/evented';
 import {MapMouseEvent} from '../ui/events';
-import DOM from '../util/dom';
-import LngLat from '../geo/lng_lat';
+import {DOM} from '../util/dom';
+import {LngLat} from '../geo/lng_lat';
 import Point from '@mapbox/point-geometry';
-import smartWrap from '../util/smart_wrap';
+import {smartWrap} from '../util/smart_wrap';
 import {anchorTranslate, applyAnchorClass} from './anchor';
 
 import type {PositionAnchor} from './anchor';
-import type Map from './map';
+import type {Map} from './map';
 import type {LngLatLike} from '../geo/lng_lat';
 import type {PointLike} from './camera';
 
@@ -20,18 +20,61 @@ const defaultOptions = {
     maxWidth: '240px'
 };
 
+/**
+ * A pixel offset specified as:
+ * - a single number specifying a distance from the location
+ * - a {@link PointLike} specifying a constant offset
+ * - an object of {@link Point}s specifying an offset for each anchor position
+ * Negative offsets indicate left and up.
+ */
 export type Offset = number | PointLike | {
     [_ in PositionAnchor]: PointLike;
 };
 
 export type PopupOptions = {
+    /**
+     * If `true`, a close button will appear in the top right corner of the popup.
+     * @defaultValue true
+     */
     closeButton?: boolean;
+    /**
+     * If `true`, the popup will closed when the map is clicked.
+     * @defaultValue true
+     */
     closeOnClick?: boolean;
+    /**
+     * If `true`, the popup will closed when the map moves.
+     * @defaultValue false
+     */
     closeOnMove?: boolean;
+    /**
+     * If `true`, the popup will try to focus the first focusable element inside the popup.
+     * @defaultValue true
+     */
     focusAfterOpen?: boolean;
+    /**
+     * A string indicating the part of the Popup that should
+     * be positioned closest to the coordinate set via {@link Popup#setLngLat}.
+     * Options are `'center'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-left'`,
+     * `'top-right'`, `'bottom-left'`, and `'bottom-right'`. If unset the anchor will be
+     * dynamically set to ensure the popup falls within the map container with a preference
+     * for `'bottom'`.
+     */
     anchor?: PositionAnchor;
+    /**
+     * A pixel offset applied to the popup's location
+     */
     offset?: Offset;
+    /**
+     * Space-separated CSS class names to add to popup container
+     */
     className?: string;
+    /**
+     * A string that sets the CSS property of the popup's maximum width, eg `'300px'`.
+     * To ensure the popup resizes to fit its content, set this property to `'none'`.
+     * Available values can be found here: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width
+     * @defaultValue '240px'
+     */
     maxWidth?: string;
 };
 
@@ -48,35 +91,35 @@ const focusQuerySelector = [
 /**
  * A popup component.
  *
- * @param {PopupOptions} [options]
- * @param {boolean} [options.closeButton=true] If `true`, a close button will appear in the
- * top right corner of the popup.
- * @param {boolean} [options.closeOnClick=true] If `true`, the popup will closed when the
- * map is clicked.
- * @param {boolean} [options.closeOnMove=false] If `true`, the popup will closed when the
- * map moves.
- * @param {boolean} [options.focusAfterOpen=true] If `true`, the popup will try to focus the
- * first focusable element inside the popup.
- * @param {PositionAnchor} [options.anchor] - A string indicating the part of the Popup that should
- * be positioned closest to the coordinate set via {@link Popup#setLngLat}.
- * Options are `'center'`, `'top'`, `'bottom'`, `'left'`, `'right'`, `'top-left'`,
- * `'top-right'`, `'bottom-left'`, and `'bottom-right'`. If unset the anchor will be
- * dynamically set to ensure the popup falls within the map container with a preference
- * for `'bottom'`.
- * @param {number|PointLike|Object} [options.offset] -
- * A pixel offset applied to the popup's location specified as:
- * - a single number specifying a distance from the popup's location
- * - a {@link PointLike} specifying a constant offset
- * - an object of {@link Point}s specifying an offset for each anchor position
- * Negative offsets indicate left and up.
- * @param {string} [options.className] Space-separated CSS class names to add to popup container
- * @param {string} [options.maxWidth='240px'] -
- * A string that sets the CSS property of the popup's maximum width, eg `'300px'`.
- * To ensure the popup resizes to fit its content, set this property to `'none'`.
- * Available values can be found here: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width
+ * @group Markers and Controls
+ *
+ *
+ * @example
+ * Create a popup
+ * ```ts
+ * let popup = new maplibregl.Popup();
+ * // Set an event listener that will fire
+ * // any time the popup is opened
+ * popup.on('open', function(){
+ *   console.log('popup was opened');
+ * });
+ * ```
+ *
  * @example
- * var markerHeight = 50, markerRadius = 10, linearOffset = 25;
- * var popupOffsets = {
+ * Create a popup
+ * ```ts
+ * let popup = new maplibregl.Popup();
+ * // Set an event listener that will fire
+ * // any time the popup is closed
+ * popup.on('close', function(){
+ *   console.log('popup was closed');
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * let markerHeight = 50, markerRadius = 10, linearOffset = 25;
+ * let popupOffsets = {
  *  'top': [0, 0],
  *  'top-left': [0,0],
  *  'top-right': [0,0],
@@ -86,17 +129,24 @@ const focusQuerySelector = [
  *  'left': [markerRadius, (markerHeight - markerRadius) * -1],
  *  'right': [-markerRadius, (markerHeight - markerRadius) * -1]
  *  };
- * var popup = new maplibregl.Popup({offset: popupOffsets, className: 'my-class'})
+ * let popup = new maplibregl.Popup({offset: popupOffsets, className: 'my-class'})
  *   .setLngLat(e.lngLat)
  *   .setHTML("<h1>Hello World!</h1>")
  *   .setMaxWidth("300px")
  *   .addTo(map);
- * @see [Display a popup](https://maplibre.org/maplibre-gl-js-docs/example/popup/)
- * @see [Display a popup on hover](https://maplibre.org/maplibre-gl-js-docs/example/popup-on-hover/)
- * @see [Display a popup on click](https://maplibre.org/maplibre-gl-js-docs/example/popup-on-click/)
- * @see [Attach a popup to a marker instance](https://maplibre.org/maplibre-gl-js-docs/example/set-popup/)
+ * ```
+ * @see [Display a popup](https://maplibre.org/maplibre-gl-js/docs/examples/popup/)
+ * @see [Display a popup on hover](https://maplibre.org/maplibre-gl-js/docs/examples/popup-on-hover/)
+ * @see [Display a popup on click](https://maplibre.org/maplibre-gl-js/docs/examples/popup-on-click/)
+ * @see [Attach a popup to a marker instance](https://maplibre.org/maplibre-gl-js/docs/examples/set-popup/)
+ *
+ * ### Events
+ *
+ * @event `open` Fired when the popup is opened manually or programmatically. `popup` object that was opened
+ *
+ * @event `close` Fired when the popup is closed manually or programmatically. `popup` object that was closed
  */
-export default class Popup extends Evented {
+export class Popup extends Evented {
     _map: Map;
     options: PopupOptions;
     _content: HTMLElement;
@@ -110,25 +160,26 @@ export default class Popup extends Evented {
     constructor(options?: PopupOptions) {
         super();
         this.options = extend(Object.create(defaultOptions), options);
-        bindAll(['_update', '_onClose', 'remove', '_onMouseMove', '_onMouseUp', '_onDrag'], this);
     }
 
     /**
      * Adds the popup to a map.
      *
-     * @param {Map} map The MapLibre GL JS map to add the popup to.
-     * @returns {Popup} `this`
+     * @param map - The MapLibre GL JS map to add the popup to.
+     * @returns `this`
      * @example
+     * ```ts
      * new maplibregl.Popup()
      *   .setLngLat([0, 0])
      *   .setHTML("<h1>Null Island</h1>")
      *   .addTo(map);
-     * @see [Display a popup](https://maplibre.org/maplibre-gl-js-docs/example/popup/)
-     * @see [Display a popup on hover](https://maplibre.org/maplibre-gl-js-docs/example/popup-on-hover/)
-     * @see [Display a popup on click](https://maplibre.org/maplibre-gl-js-docs/example/popup-on-click/)
-     * @see [Show polygon information on click](https://maplibre.org/maplibre-gl-js-docs/example/polygon-popup-on-click/)
+     * ```
+     * @see [Display a popup](https://maplibre.org/maplibre-gl-js/docs/examples/popup/)
+     * @see [Display a popup on hover](https://maplibre.org/maplibre-gl-js/docs/examples/popup-on-hover/)
+     * @see [Display a popup on click](https://maplibre.org/maplibre-gl-js/docs/examples/popup-on-click/)
+     * @see [Show polygon information on click](https://maplibre.org/maplibre-gl-js/docs/examples/polygon-popup-on-click/)
      */
-    addTo(map: Map) {
+    addTo(map: Map): this {
         if (this._map) this.remove();
 
         this._map = map;
@@ -155,32 +206,13 @@ export default class Popup extends Evented {
             this._map.on('move', this._update);
         }
 
-        /**
-         * Fired when the popup is opened manually or programmatically.
-         *
-         * @event open
-         * @memberof Popup
-         * @instance
-         * @type {Object}
-         * @property {Popup} popup object that was opened
-         *
-         * @example
-         * // Create a popup
-         * var popup = new maplibregl.Popup();
-         * // Set an event listener that will fire
-         * // any time the popup is opened
-         * popup.on('open', function(){
-         *   console.log('popup was opened');
-         * });
-         *
-         */
         this.fire(new Event('open'));
 
         return this;
     }
 
     /**
-     * @returns {boolean} `true` if the popup is open, `false` if it is closed.
+     * @returns `true` if the popup is open, `false` if it is closed.
      */
     isOpen() {
         return !!this._map;
@@ -190,11 +222,13 @@ export default class Popup extends Evented {
      * Removes the popup from the map it has been added to.
      *
      * @example
-     * var popup = new maplibregl.Popup().addTo(map);
+     * ```ts
+     * let popup = new maplibregl.Popup().addTo(map);
      * popup.remove();
-     * @returns {Popup} `this`
+     * ```
+     * @returns `this`
      */
-    remove() {
+    remove = (): this => {
         if (this._content) {
             DOM.remove(this._content);
         }
@@ -215,29 +249,10 @@ export default class Popup extends Evented {
             delete this._map;
         }
 
-        /**
-         * Fired when the popup is closed manually or programmatically.
-         *
-         * @event close
-         * @memberof Popup
-         * @instance
-         * @type {Object}
-         * @property {Popup} popup object that was closed
-         *
-         * @example
-         * // Create a popup
-         * var popup = new maplibregl.Popup();
-         * // Set an event listener that will fire
-         * // any time the popup is closed
-         * popup.on('close', function(){
-         *   console.log('popup was closed');
-         * });
-         *
-         */
         this.fire(new Event('close'));
 
         return this;
-    }
+    };
 
     /**
      * Returns the geographical location of the popup's anchor.
@@ -246,19 +261,19 @@ export default class Popup extends Evented {
      * set by `setLngLat` because `Popup` wraps the anchor longitude across copies of the world to keep
      * the popup on screen.
      *
-     * @returns {LngLat} The geographical location of the popup's anchor.
+     * @returns The geographical location of the popup's anchor.
      */
-    getLngLat() {
+    getLngLat(): LngLat {
         return this._lngLat;
     }
 
     /**
      * Sets the geographical location of the popup's anchor, and moves the popup to it. Replaces trackPointer() behavior.
      *
-     * @param lnglat The geographical location to set as the popup's anchor.
-     * @returns {Popup} `this`
+     * @param lnglat - The geographical location to set as the popup's anchor.
+     * @returns `this`
      */
-    setLngLat(lnglat: LngLatLike) {
+    setLngLat(lnglat: LngLatLike): this {
         this._lngLat = LngLat.convert(lnglat);
         this._pos = null;
 
@@ -282,13 +297,15 @@ export default class Popup extends Evented {
      * Tracks the popup anchor to the cursor position on screens with a pointer device (it will be hidden on touchscreens). Replaces the `setLngLat` behavior.
      * For most use cases, set `closeOnClick` and `closeButton` to `false`.
      * @example
-     * var popup = new maplibregl.Popup({ closeOnClick: false, closeButton: false })
+     * ```ts
+     * let popup = new maplibregl.Popup({ closeOnClick: false, closeButton: false })
      *   .setHTML("<h1>Hello World!</h1>")
      *   .trackPointer()
      *   .addTo(map);
-     * @returns {Popup} `this`
+     * ```
+     * @returns `this`
      */
-    trackPointer() {
+    trackPointer(): this {
         this._trackPointer = true;
         this._pos = null;
         this._update();
@@ -309,16 +326,18 @@ export default class Popup extends Evented {
     /**
      * Returns the `Popup`'s HTML element.
      * @example
-     * // Change the `Popup` element's font size
-     * var popup = new maplibregl.Popup()
+     * Change the `Popup` element's font size
+     * ```ts
+     * let popup = new maplibregl.Popup()
      *   .setLngLat([-96, 37.8])
      *   .setHTML("<p>Hello World!</p>")
      *   .addTo(map);
-     * var popupElem = popup.getElement();
+     * let popupElem = popup.getElement();
      * popupElem.style.fontSize = "25px";
-     * @returns {HTMLElement} element
+     * ```
+     * @returns element
      */
-    getElement() {
+    getElement(): HTMLElement {
         return this._container;
     }
 
@@ -329,15 +348,17 @@ export default class Popup extends Evented {
      * so it cannot insert raw HTML. Use this method for security against XSS
      * if the popup content is user-provided.
      *
-     * @param text Textual content for the popup.
-     * @returns {Popup} `this`
+     * @param text - Textual content for the popup.
+     * @returns `this`
      * @example
-     * var popup = new maplibregl.Popup()
+     * ```ts
+     * let popup = new maplibregl.Popup()
      *   .setLngLat(e.lngLat)
      *   .setText('Hello, world!')
      *   .addTo(map);
+     * ```
      */
-    setText(text: string) {
+    setText(text: string): this {
         return this.setDOMContent(document.createTextNode(text));
     }
 
@@ -348,19 +369,21 @@ export default class Popup extends Evented {
      * used only with trusted content. Consider {@link Popup#setText} if
      * the content is an untrusted text string.
      *
-     * @param html A string representing HTML content for the popup.
-     * @returns {Popup} `this`
+     * @param html - A string representing HTML content for the popup.
+     * @returns `this`
      * @example
-     * var popup = new maplibregl.Popup()
+     * ```ts
+     * let popup = new maplibregl.Popup()
      *   .setLngLat(e.lngLat)
      *   .setHTML("<h1>Hello World!</h1>")
      *   .addTo(map);
-     * @see [Display a popup](https://maplibre.org/maplibre-gl-js-docs/example/popup/)
-     * @see [Display a popup on hover](https://maplibre.org/maplibre-gl-js-docs/example/popup-on-hover/)
-     * @see [Display a popup on click](https://maplibre.org/maplibre-gl-js-docs/example/popup-on-click/)
-     * @see [Attach a popup to a marker instance](https://maplibre.org/maplibre-gl-js-docs/example/set-popup/)
+     * ```
+     * @see [Display a popup](https://maplibre.org/maplibre-gl-js/docs/examples/popup/)
+     * @see [Display a popup on hover](https://maplibre.org/maplibre-gl-js/docs/examples/popup-on-hover/)
+     * @see [Display a popup on click](https://maplibre.org/maplibre-gl-js/docs/examples/popup-on-click/)
+     * @see [Attach a popup to a marker instance](https://maplibre.org/maplibre-gl-js/docs/examples/set-popup/)
      */
-    setHTML(html: string) {
+    setHTML(html: string): this {
         const frag = document.createDocumentFragment();
         const temp = document.createElement('body');
         let child;
@@ -377,20 +400,20 @@ export default class Popup extends Evented {
     /**
      * Returns the popup's maximum width.
      *
-     * @returns {string} The maximum width of the popup.
+     * @returns The maximum width of the popup.
      */
-    getMaxWidth() {
-        return this._container && this._container.style.maxWidth;
+    getMaxWidth(): string {
+        return this._container?.style.maxWidth;
     }
 
     /**
      * Sets the popup's maximum width. This is setting the CSS property `max-width`.
      * Available values can be found here: https://developer.mozilla.org/en-US/docs/Web/CSS/max-width
      *
-     * @param maxWidth A string representing the value for the maximum width.
-     * @returns {Popup} `this`
+     * @param maxWidth - A string representing the value for the maximum width.
+     * @returns `this`
      */
-    setMaxWidth(maxWidth: string) {
+    setMaxWidth(maxWidth: string): this {
         this.options.maxWidth = maxWidth;
         this._update();
         return this;
@@ -399,18 +422,20 @@ export default class Popup extends Evented {
     /**
      * Sets the popup's content to the element provided as a DOM node.
      *
-     * @param htmlNode A DOM node to be used as content for the popup.
-     * @returns {Popup} `this`
+     * @param htmlNode - A DOM node to be used as content for the popup.
+     * @returns `this`
      * @example
-     * // create an element with the popup content
-     * var div = document.createElement('div');
+     * Create an element with the popup content
+     * ```ts
+     * let div = document.createElement('div');
      * div.innerHTML = 'Hello, world!';
-     * var popup = new maplibregl.Popup()
+     * let popup = new maplibregl.Popup()
      *   .setLngLat(e.lngLat)
      *   .setDOMContent(div)
      *   .addTo(map);
+     * ```
      */
-    setDOMContent(htmlNode: Node) {
+    setDOMContent(htmlNode: Node): this {
         if (this._content) {
             // Clear out children first.
             while (this._content.hasChildNodes()) {
@@ -433,11 +458,13 @@ export default class Popup extends Evented {
     /**
      * Adds a CSS class to the popup container element.
      *
-     * @param {string} className Non-empty string with CSS class name to add to popup container
+     * @param className - Non-empty string with CSS class name to add to popup container
      *
      * @example
+     * ```ts
      * let popup = new maplibregl.Popup()
      * popup.addClassName('some-class')
+     * ```
      */
     addClassName(className: string) {
         if (this._container) {
@@ -448,11 +475,13 @@ export default class Popup extends Evented {
     /**
      * Removes a CSS class from the popup container element.
      *
-     * @param {string} className Non-empty string with CSS class name to remove from popup container
+     * @param className - Non-empty string with CSS class name to remove from popup container
      *
      * @example
+     * ```ts
      * let popup = new maplibregl.Popup()
      * popup.removeClassName('some-class')
+     * ```
      */
     removeClassName(className: string) {
         if (this._container) {
@@ -463,10 +492,10 @@ export default class Popup extends Evented {
     /**
      * Sets the popup's offset.
      *
-     * @param offset Sets the popup's offset.
-     * @returns {Popup} `this`
+     * @param offset - Sets the popup's offset.
+     * @returns `this`
      */
-    setOffset (offset?: Offset) {
+    setOffset (offset?: Offset): this {
         this.options.offset = offset;
         this._update();
         return this;
@@ -475,15 +504,17 @@ export default class Popup extends Evented {
     /**
      * Add or remove the given CSS class on the popup container, depending on whether the container currently has that class.
      *
-     * @param {string} className Non-empty string with CSS class name to add/remove
+     * @param className - Non-empty string with CSS class name to add/remove
      *
-     * @returns {boolean} if the class was removed return false, if class was added, then return true
+     * @returns if the class was removed return false, if class was added, then return true, undefined if there is no container
      *
      * @example
+     * ```ts
      * let popup = new maplibregl.Popup()
      * popup.toggleClassName('toggleClass')
+     * ```
      */
-    toggleClassName(className: string) {
+    toggleClassName(className: string): boolean | undefined {
         if (this._container) {
             return this._container.classList.toggle(className);
         }
@@ -499,19 +530,19 @@ export default class Popup extends Evented {
         }
     }
 
-    _onMouseUp(event: MapMouseEvent) {
+    _onMouseUp = (event: MapMouseEvent) => {
         this._update(event.point);
-    }
+    };
 
-    _onMouseMove(event: MapMouseEvent) {
+    _onMouseMove = (event: MapMouseEvent) => {
         this._update(event.point);
-    }
+    };
 
-    _onDrag(event: MapMouseEvent) {
+    _onDrag = (event: MapMouseEvent) => {
         this._update(event.point);
-    }
+    };
 
-    _update(cursor?: Point) {
+    _update = (cursor?: Point) => {
         const hasPosition = this._lngLat || this._trackPointer;
 
         if (!this._map || !hasPosition || !this._content) { return; }
@@ -521,8 +552,9 @@ export default class Popup extends Evented {
             this._tip       = DOM.create('div', 'maplibregl-popup-tip', this._container);
             this._container.appendChild(this._content);
             if (this.options.className) {
-                this.options.className.split(' ').forEach(name =>
-                    this._container.classList.add(name));
+                for (const name of this.options.className.split(' ')) {
+                    this._container.classList.add(name);
+                }
             }
 
             if (this._trackPointer) {
@@ -574,7 +606,7 @@ export default class Popup extends Evented {
         const offsetedPos = pos.add(offset[anchor]).round();
         DOM.setTransform(this._container, `${anchorTranslate[anchor]} translate(${offsetedPos.x}px,${offsetedPos.y}px)`);
         applyAnchorClass(this._container, anchor, 'popup');
-    }
+    };
 
     _focusFirstElement() {
         if (!this.options.focusAfterOpen || !this._container) return;
@@ -584,9 +616,9 @@ export default class Popup extends Evented {
         if (firstFocusable) firstFocusable.focus();
     }
 
-    _onClose() {
+    _onClose = () => {
         this.remove();
-    }
+    };
 }
 
 function normalizeOffset(offset?: Offset | null) {

package/src/util/actor.test.ts

@@ -1,5 +1,5 @@
-import Actor from './actor';
-import workerFactory from './web_worker';
+import {Actor} from './actor';
+import {workerFactory} from './web_worker';
 import {MessageBus} from '../../test/unit/lib/web_worker_mock';
 
 const originalWorker = global.Worker;
@@ -40,8 +40,8 @@ describe('Actor', () => {
 
         const worker = workerFactory();
 
-        const m1 = new Actor(worker, {}, 1);
-        const m2 = new Actor(worker, {}, 2);
+        const m1 = new Actor(worker, {}, '1');
+        const m2 = new Actor(worker, {}, '2');
 
         let callbackCount = 0;
         m1.send('test', {value: 1729}, (err, response) => {
@@ -78,14 +78,14 @@ describe('Actor', () => {
 
         new Actor(worker, {
             test () { done(); }
-        }, 1);
+        }, '1');
         new Actor(worker, {
             test () {
                 done('test failed');
             }
-        }, 2);
+        }, '2');
 
-        workerActor.send('test', {}, () => {}, 1);
+        workerActor.send('test', {}, () => {}, '1');
     });
 
     test('#remove unbinds event listener', done => {