maplibre-gl 3.1.0 → 3.2.0-pre.2

package/src/ui/handler/shim/drag_pan.ts

@@ -1,26 +1,48 @@
 import type {MousePanHandler} from '../mouse';
-import type TouchPanHandler from './../touch_pan';
+import type {TouchPanHandler} from './../touch_pan';
 
+/**
+ * A {@link DragPanHandler} options object
+ */
 export type DragPanOptions = {
+    /**
+     * factor used to scale the drag velocity
+     * @defaultValue 0
+     */
     linearity?: number;
+    /**
+     * easing function applled to `map.panTo` when applying the drag.
+     * @param t - the easing function
+     * @defaultValue bezier(0, 0, 0.3, 1)
+     */
     easing?: (t: number) => number;
+    /**
+     * the maximum value of the drag velocity.
+     * @defaultValue 1400
+     */
     deceleration?: number;
+    /**
+     * the rate at which the speed reduces after the pan ends.
+     * @defaultValue 2500
+     */
     maxSpeed?: number;
 };
 
 /**
  * The `DragPanHandler` allows the user to pan the map by clicking and dragging
  * the cursor.
+ *
+ * @group Handlers
  */
-export default class DragPanHandler {
+export class DragPanHandler {
 
     _el: HTMLElement;
     _mousePan: MousePanHandler;
     _touchPan: TouchPanHandler;
-    _inertiaOptions: DragPanOptions;
+    _inertiaOptions: DragPanOptions | boolean;
 
     /**
-     * @private
+     * @hidden
     */
     constructor(el: HTMLElement, mousePan: MousePanHandler, touchPan: TouchPanHandler) {
         this._el = el;
@@ -31,23 +53,19 @@ export default class DragPanHandler {
     /**
      * Enables the "drag to pan" interaction.
      *
-     * @param {Object} [options] Options object
-     * @param {number} [options.linearity=0] factor used to scale the drag velocity
-     * @param {Function} [options.easing=bezier(0, 0, 0.3, 1)] easing function applled to `map.panTo` when applying the drag.
-     * @param {number} [options.maxSpeed=1400] the maximum value of the drag velocity.
-     * @param {number} [options.deceleration=2500] the rate at which the speed reduces after the pan ends.
-     *
+     * @param options - Options object
      * @example
+     * ```ts
      *   map.dragPan.enable();
-     * @example
      *   map.dragPan.enable({
      *      linearity: 0.3,
      *      easing: bezier(0, 0, 0.3, 1),
      *      maxSpeed: 1400,
      *      deceleration: 2500,
      *   });
+     * ```
      */
-    enable(options?: DragPanOptions) {
+    enable(options?: DragPanOptions | boolean) {
         this._inertiaOptions = options || {};
         this._mousePan.enable();
         this._touchPan.enable();
@@ -58,7 +76,9 @@ export default class DragPanHandler {
      * Disables the "drag to pan" interaction.
      *
      * @example
+     * ```ts
      * map.dragPan.disable();
+     * ```
      */
     disable() {
         this._mousePan.disable();
@@ -69,7 +89,7 @@ export default class DragPanHandler {
     /**
      * Returns a Boolean indicating whether the "drag to pan" interaction is enabled.
      *
-     * @returns {boolean} `true` if the "drag to pan" interaction is enabled.
+     * @returns `true` if the "drag to pan" interaction is enabled.
      */
     isEnabled() {
         return this._mousePan.isEnabled() && this._touchPan.isEnabled();
@@ -78,7 +98,7 @@ export default class DragPanHandler {
     /**
      * Returns a Boolean indicating whether the "drag to pan" interaction is active, i.e. currently being used.
      *
-     * @returns {boolean} `true` if the "drag to pan" interaction is active.
+     * @returns `true` if the "drag to pan" interaction is active.
      */
     isActive() {
         return this._mousePan.isActive() || this._touchPan.isActive();

package/src/ui/handler/shim/drag_rotate.ts

@@ -1,25 +1,29 @@
 import type {MousePitchHandler, MouseRotateHandler} from '../mouse';
 
+export type DragRotateHandlerOptions = {
+    /**
+     * Control the map pitch in addition to the bearing
+     * @defaultValue true
+     */
+    pitchWithRotate: boolean;
+}
+
 /**
  * The `DragRotateHandler` allows the user to rotate the map by clicking and
  * dragging the cursor while holding the right mouse button or `ctrl` key.
+ *
+ * @group Handlers
  */
-export default class DragRotateHandler {
+export class DragRotateHandler {
 
     _mouseRotate: MouseRotateHandler;
     _mousePitch: MousePitchHandler;
     _pitchWithRotate: boolean;
 
     /**
-     * @param {Object} [options]
-     * @param {number} [options.bearingSnap] The threshold, measured in degrees, that determines when the map's
-     *   bearing will snap to north.
-     * @param {bool} [options.pitchWithRotate=true] Control the map pitch in addition to the bearing
-     * @private
-     */
-    constructor(options: {
-        pitchWithRotate: boolean;
-    }, mouseRotate: MouseRotateHandler, mousePitch: MousePitchHandler) {
+     * @hidden
+    */
+    constructor(options: DragRotateHandlerOptions, mouseRotate: MouseRotateHandler, mousePitch: MousePitchHandler) {
         this._pitchWithRotate = options.pitchWithRotate;
         this._mouseRotate = mouseRotate;
         this._mousePitch = mousePitch;
@@ -29,7 +33,9 @@ export default class DragRotateHandler {
      * Enables the "drag to rotate" interaction.
      *
      * @example
+     * ```ts
      * map.dragRotate.enable();
+     * ```
      */
     enable() {
         this._mouseRotate.enable();
@@ -40,7 +46,9 @@ export default class DragRotateHandler {
      * Disables the "drag to rotate" interaction.
      *
      * @example
+     * ```ts
      * map.dragRotate.disable();
+     * ```
      */
     disable() {
         this._mouseRotate.disable();
@@ -50,7 +58,7 @@ export default class DragRotateHandler {
     /**
      * Returns a Boolean indicating whether the "drag to rotate" interaction is enabled.
      *
-     * @returns {boolean} `true` if the "drag to rotate" interaction is enabled.
+     * @returns `true` if the "drag to rotate" interaction is enabled.
      */
     isEnabled() {
         return this._mouseRotate.isEnabled() && (!this._pitchWithRotate || this._mousePitch.isEnabled());
@@ -59,7 +67,7 @@ export default class DragRotateHandler {
     /**
      * Returns a Boolean indicating whether the "drag to rotate" interaction is active, i.e. currently being used.
      *
-     * @returns {boolean} `true` if the "drag to rotate" interaction is active.
+     * @returns `true` if the "drag to rotate" interaction is active.
      */
     isActive() {
         return this._mouseRotate.isActive() || this._mousePitch.isActive();

package/src/ui/handler/shim/two_fingers_touch.ts

@@ -1,5 +1,5 @@
-import type {TwoFingersTouchZoomHandler, TwoFingersTouchRotateHandler} from '../two_fingers_touch';
-import type TapDragZoomHandler from '../tap_drag_zoom';
+import type {TwoFingersTouchZoomHandler, TwoFingersTouchRotateHandler, AroundCenterOptions} from '../two_fingers_touch';
+import type {TapDragZoomHandler} from '../tap_drag_zoom';
 
 /**
  * The `TwoFingersTouchZoomRotateHandler` allows the user to zoom and rotate the map by
@@ -7,8 +7,10 @@ import type TapDragZoomHandler from '../tap_drag_zoom';
  *
  * They can zoom with one finger by double tapping and dragging. On the second tap,
  * hold the finger down and drag up or down to zoom in or out.
+ *
+ * @group Handlers
  */
-export default class TwoFingersTouchZoomRotateHandler {
+export class TwoFingersTouchZoomRotateHandler {
 
     _el: HTMLElement;
     _touchZoom: TwoFingersTouchZoomHandler;
@@ -18,7 +20,7 @@ export default class TwoFingersTouchZoomRotateHandler {
     _enabled: boolean;
 
     /**
-     * @private
+     * @hidden
     */
     constructor(el: HTMLElement, touchZoom: TwoFingersTouchZoomHandler, touchRotate: TwoFingersTouchRotateHandler, tapDragZoom: TapDragZoomHandler) {
         this._el = el;
@@ -32,17 +34,15 @@ export default class TwoFingersTouchZoomRotateHandler {
     /**
      * Enables the "pinch to rotate and zoom" interaction.
      *
-     * @param {Object} [options] Options object.
-     * @param {string} [options.around] If "center" is passed, map will zoom around the center
+     * @param options - Options object.
      *
      * @example
-     *   map.touchZoomRotate.enable();
-     * @example
-     *   map.touchZoomRotate.enable({ around: 'center' });
+     * ```ts
+     * map.touchZoomRotate.enable();
+     * map.touchZoomRotate.enable({ around: 'center' });
+     * ```
      */
-    enable(options?: {
-        around?: 'center';
-    } | null) {
+    enable(options?: AroundCenterOptions | boolean | null) {
         this._touchZoom.enable(options);
         if (!this._rotationDisabled) this._touchRotate.enable(options);
         this._tapDragZoom.enable();
@@ -53,7 +53,9 @@ export default class TwoFingersTouchZoomRotateHandler {
      * Disables the "pinch to rotate and zoom" interaction.
      *
      * @example
-     *   map.touchZoomRotate.disable();
+     * ```ts
+     * map.touchZoomRotate.disable();
+     * ```
      */
     disable() {
         this._touchZoom.disable();
@@ -65,7 +67,7 @@ export default class TwoFingersTouchZoomRotateHandler {
     /**
      * Returns a Boolean indicating whether the "pinch to rotate and zoom" interaction is enabled.
      *
-     * @returns {boolean} `true` if the "pinch to rotate and zoom" interaction is enabled.
+     * @returns `true` if the "pinch to rotate and zoom" interaction is enabled.
      */
     isEnabled() {
         return this._touchZoom.isEnabled() &&
@@ -76,7 +78,7 @@ export default class TwoFingersTouchZoomRotateHandler {
     /**
      * Returns true if the handler is enabled and has detected the start of a zoom/rotate gesture.
      *
-     * @returns {boolean} //eslint-disable-line
+     * @returns `true` if the handler is active, `false` otherwise
      */
     isActive() {
         return this._touchZoom.isActive() || this._touchRotate.isActive() || this._tapDragZoom.isActive();
@@ -87,7 +89,9 @@ export default class TwoFingersTouchZoomRotateHandler {
      * interaction enabled.
      *
      * @example
-     *   map.touchZoomRotate.disableRotation();
+     * ```ts
+     * map.touchZoomRotate.disableRotation();
+     * ```
      */
     disableRotation() {
         this._rotationDisabled = true;
@@ -98,8 +102,10 @@ export default class TwoFingersTouchZoomRotateHandler {
      * Enables the "pinch to rotate" interaction.
      *
      * @example
-     *   map.touchZoomRotate.enable();
-     *   map.touchZoomRotate.enableRotation();
+     * ```ts
+     * map.touchZoomRotate.enable();
+     * map.touchZoomRotate.enableRotation();
+     * ```
      */
     enableRotation() {
         this._rotationDisabled = false;

package/src/ui/handler/tap_drag_zoom.test.ts

@@ -0,0 +1,113 @@
+import {beforeMapTest} from '../../util/test/util';
+import simulate from '../../../test/unit/lib/simulate_interaction';
+import {Map, MapOptions} from '../map';
+
+function createMap() {
+    return new Map({container: window.document.createElement('div')} as any as MapOptions);
+}
+
+function setupEvents(map: Map) {
+    const zoomstart = jest.fn();
+    map.on('zoomstart', zoomstart);
+
+    const zoom = jest.fn();
+    map.on('zoom', zoom);
+
+    const zoomend = jest.fn();
+    map.on('zoomend', zoomend);
+
+    return {
+        zoomstart,
+        zoom,
+        zoomend
+    };
+}
+
+beforeEach(() => {
+    beforeMapTest();
+});
+
+describe('tap_drag_zoom', () => {
+    test('TapDragZoomHandler fires zoomstart, zoom, and zoomend at appropriate times in response to a double-tap and drag gesture', () => {
+        const map = createMap();
+        const target = map.getCanvas();
+
+        const {zoomstart, zoom, zoomend} = setupEvents(map);
+
+        const pointTouchOptions = {
+            touches: [{target, clientX: 100, clientY: 100}]
+        };
+
+        simulate.touchstart(target, pointTouchOptions);
+        simulate.touchend(target);
+        simulate.touchstart(target, pointTouchOptions);
+        map._renderTaskQueue.run();
+
+        expect(zoomstart).not.toHaveBeenCalled();
+        expect(zoom).not.toHaveBeenCalled();
+        expect(zoomend).not.toHaveBeenCalled();
+
+        simulate.touchmove(target, {
+            touches: [{target, clientX: 100, clientY: 110}]
+        });
+        map._renderTaskQueue.run();
+
+        expect(zoomstart).toHaveBeenCalled();
+        expect(zoom).toHaveBeenCalled();
+        expect(zoomend).not.toHaveBeenCalled();
+
+        simulate.touchend(target);
+        map._renderTaskQueue.run();
+        expect(zoomend).toHaveBeenCalled();
+
+    });
+
+    test('TapDragZoomHandler does not fire zoom on tap and drag if touchstart events are > 500ms apart', done => {
+        const map = createMap();
+        const target = map.getCanvas();
+
+        const {zoomstart, zoom, zoomend} = setupEvents(map);
+
+        const pointTouchOptions = {
+            touches: [{target, clientX: 100, clientY: 100}]
+        };
+
+        simulate.touchstart(target, pointTouchOptions);
+        simulate.touchend(target);
+        setTimeout(() => {
+            simulate.touchstart(target, pointTouchOptions);
+            simulate.touchmove(target, {
+                touches: [{target, clientX: 100, clientY: 110}]
+            });
+            map._renderTaskQueue.run();
+
+            expect(zoomstart).not.toHaveBeenCalled();
+            expect(zoom).not.toHaveBeenCalled();
+            expect(zoomend).not.toHaveBeenCalled();
+            done();
+        }, 510);
+    });
+
+    test('TapDragZoomHandler does not zoom on double-tap and drag if touchstart events are in different locations (>30px apart)', () => {
+        const map = createMap();
+        const target = map.getCanvas();
+
+        const {zoomstart, zoom, zoomend} = setupEvents(map);
+
+        simulate.touchstart(target, {
+            touches: [{target, clientX: 100, clientY: 100}]
+        });
+        simulate.touchend(target);
+        simulate.touchstart(target, {
+            touches: [{target, clientX: 140, clientY: 100}]
+        });
+        simulate.touchmove(target, {
+            touches: [{target, clientX: 140, clientY: 110}]
+        });
+        map._renderTaskQueue.run();
+
+        expect(zoomstart).not.toHaveBeenCalled();
+        expect(zoom).not.toHaveBeenCalled();
+        expect(zoomend).not.toHaveBeenCalled();
+    });
+});

package/src/ui/handler/tap_drag_zoom.ts

@@ -1,13 +1,15 @@
-import {TapRecognizer, MAX_TAP_INTERVAL} from './tap_recognizer';
+import {Handler} from '../handler_manager';
+import {TapRecognizer, MAX_TAP_INTERVAL, MAX_DIST} from './tap_recognizer';
 import type Point from '@mapbox/point-geometry';
 
-export default class TapDragZoomHandler {
+export class TapDragZoomHandler implements Handler {
 
     _enabled: boolean;
     _active: boolean;
     _swipePoint: Point;
     _swipeTouch: number;
     _tapTime: number;
+    _tapPoint: Point;
     _tap: TapRecognizer;
 
     constructor() {
@@ -25,23 +27,28 @@ export default class TapDragZoomHandler {
         delete this._swipePoint;
         delete this._swipeTouch;
         delete this._tapTime;
+        delete this._tapPoint;
         this._tap.reset();
     }
 
     touchstart(e: TouchEvent, points: Array<Point>, mapTouches: Array<Touch>) {
         if (this._swipePoint) return;
 
-        if (this._tapTime && e.timeStamp - this._tapTime > MAX_TAP_INTERVAL) {
-            this.reset();
-        }
-
         if (!this._tapTime) {
             this._tap.touchstart(e, points, mapTouches);
-        } else if (mapTouches.length > 0) {
-            this._swipePoint = points[0];
-            this._swipeTouch = mapTouches[0].identifier;
-        }
+        } else {
+            const swipePoint = points[0];
+
+            const soonEnough = e.timeStamp - this._tapTime < MAX_TAP_INTERVAL;
+            const closeEnough =  this._tapPoint.dist(swipePoint) < MAX_DIST;
 
+            if (!soonEnough || !closeEnough) {
+                this.reset();
+            } else if (mapTouches.length > 0) {
+                this._swipePoint = swipePoint;
+                this._swipeTouch = mapTouches[0].identifier;
+            }
+        }
     }
 
     touchmove(e: TouchEvent, points: Array<Point>, mapTouches: Array<Touch>) {
@@ -70,6 +77,7 @@ export default class TapDragZoomHandler {
             const point = this._tap.touchend(e, points, mapTouches);
             if (point) {
                 this._tapTime = e.timeStamp;
+                this._tapPoint = point;
             }
         } else if (this._swipePoint) {
             if (mapTouches.length === 0) {

package/src/ui/handler/tap_recognizer.ts

@@ -11,7 +11,7 @@ function getCentroid(points: Array<Point>) {
 
 export const MAX_TAP_INTERVAL = 500;
 const MAX_TOUCH_TIME = 500;
-const MAX_DIST = 30;
+export const MAX_DIST = 30;
 
 export class SingleTapRecognizer {
 

package/src/ui/handler/tap_zoom.ts

@@ -1,9 +1,10 @@
 import {TapRecognizer} from './tap_recognizer';
 import type Point from '@mapbox/point-geometry';
-import type Map from '../map';
-import TransformProvider from './transform-provider';
+import type {Map} from '../map';
+import {TransformProvider} from './transform-provider';
+import {Handler} from '../handler_manager';
 
-export default class TapZoomHandler {
+export class TapZoomHandler implements Handler {
     _tr: TransformProvider;
     _enabled: boolean;
     _active: boolean;

package/src/ui/handler/touch_pan.ts

@@ -1,9 +1,10 @@
 import Point from '@mapbox/point-geometry';
 import {indexTouches} from './handler_util';
-import type Map from '../map';
+import type {Map} from '../map';
 import {GestureOptions} from '../map';
+import {Handler} from '../handler_manager';
 
-export default class TouchPanHandler {
+export class TouchPanHandler implements Handler {
 
     _enabled: boolean;
     _active: boolean;

package/src/ui/handler/transform-provider.ts

@@ -1,15 +1,15 @@
-import type Map from '../map';
+import type {Map} from '../map';
 import type {PointLike} from '../camera';
-import type Transform from '../../geo/transform';
+import type {Transform} from '../../geo/transform';
 import Point from '@mapbox/point-geometry';
-import LngLat from '../../geo/lng_lat';
+import {LngLat} from '../../geo/lng_lat';
 
 /**
  * Shared utilities for the Handler classes to access the correct camera state.
  * If Camera.transformCameraUpdate is specified, the "desired state" of camera may differ from the state used for rendering.
  * The handlers need the "desired state" to track accumulated changes.
  */
-class TransformProvider {
+export class TransformProvider {
     _map: Map;
 
     constructor(map: Map) {
@@ -40,5 +40,3 @@ class TransformProvider {
         return this.transform.pointLocation(Point.convert(point), this._map.terrain);
     }
 }
-
-export default TransformProvider;

package/src/ui/handler/two_fingers_touch.test.ts

@@ -1,6 +1,6 @@
-import Map, {MapOptions} from '../map';
-import Marker from '../marker';
-import DOM from '../../util/dom';
+import {Map, MapOptions} from '../map';
+import {Marker} from '../marker';
+import {DOM} from '../../util/dom';
 import simulate from '../../../test/unit/lib/simulate_interaction';
 import {beforeMapTest} from '../../util/test/util';