maplibre-gl 2.2.0-pre.2 → 2.2.0

package/src/ui/handler/touch_pan.ts

@@ -1,5 +1,7 @@
 import Point from '@mapbox/point-geometry';
 import {indexTouches} from './handler_util';
+import type Map from '../map';
+import {GestureOptions} from '../map';
 
 export default class TouchPanHandler {
 
@@ -11,12 +13,16 @@ export default class TouchPanHandler {
     _minTouches: number;
     _clickTolerance: number;
     _sum: Point;
+    _map: Map;
+    _cancelCooperativeMessage: boolean;
 
     constructor(options: {
         clickTolerance: number;
-    }) {
-        this._minTouches = 1;
+        cooperativeGestures: boolean | GestureOptions;
+    }, map: Map) {
+        this._minTouches = options.cooperativeGestures ? 2 : 1;
         this._clickTolerance = options.clickTolerance || 1;
+        this._map = map;
         this.reset();
     }
 
@@ -24,6 +30,11 @@ export default class TouchPanHandler {
         this._active = false;
         this._touches = {};
         this._sum = new Point(0, 0);
+
+        // Put a delay on the cooperative gesture message so it's less twitchy
+        setTimeout(() => {
+            this._cancelCooperativeMessage = false;
+        }, 200);
     }
 
     touchstart(e: TouchEvent, points: Array<Point>, mapTouches: Array<Touch>) {
@@ -31,6 +42,15 @@ export default class TouchPanHandler {
     }
 
     touchmove(e: TouchEvent, points: Array<Point>, mapTouches: Array<Touch>) {
+        if (this._map._cooperativeGestures) {
+            if (this._minTouches === 2 && mapTouches.length < 2 && !this._cancelCooperativeMessage) {
+                // If coop gesture enabled, show panning info to user
+                this._map._onCooperativeGesture(e, false, mapTouches.length);
+            } else if (!this._cancelCooperativeMessage) {
+                // If user is successfully navigating, we don't need this warning until the touch resets
+                this._cancelCooperativeMessage = true;
+            }
+        }
         if (!this._active || mapTouches.length < this._minTouches) return;
         e.preventDefault();
         return this._calculateTransform(e, points, mapTouches);

package/src/ui/handler/touch_zoom_rotate.ts

@@ -1,5 +1,6 @@
 import Point from '@mapbox/point-geometry';
 import DOM from '../../util/dom';
+import type Map from '../map';
 
 class TwoTouchHandler {
 
@@ -23,7 +24,6 @@ class TwoTouchHandler {
     _move(points: [Point, Point], pinchAround: Point, e: TouchEvent) { return {}; } //eslint-disable-line
 
     touchstart(e: TouchEvent, points: Array<Point>, mapTouches: Array<Touch>) {
-        //console.log(e.target, e.targetTouches.length ? e.targetTouches[0].target : null);
         //log('touchstart', points, e.target.innerHTML, e.targetTouches.length ? e.targetTouches[0].target.innerHTML: undefined);
         if (this._firstTwoTouches || mapTouches.length < 2) return;
 
@@ -203,6 +203,13 @@ export class TouchPitchHandler extends TwoTouchHandler {
     _valid: boolean | void;
     _firstMove: number;
     _lastPoints: [Point, Point];
+    _map: Map;
+    _currentTouchCount: number;
+
+    constructor(map: Map) {
+        super();
+        this._map = map;
+    }
 
     reset() {
         super.reset();
@@ -211,6 +218,11 @@ export class TouchPitchHandler extends TwoTouchHandler {
         delete this._lastPoints;
     }
 
+    touchstart(e: TouchEvent, points: Array<Point>, mapTouches: Array<Touch>) {
+        super.touchstart(e, points, mapTouches);
+        this._currentTouchCount = mapTouches.length;
+    }
+
     _start(points: [Point, Point]) {
         this._lastPoints = points;
         if (isVertical(points[0].sub(points[1]))) {
@@ -221,6 +233,11 @@ export class TouchPitchHandler extends TwoTouchHandler {
     }
 
     _move(points: [Point, Point], center: Point, e: TouchEvent) {
+        // If cooperative gestures is enabled, we need a 3-finger minimum for this gesture to register
+        if (this._map._cooperativeGestures && this._currentTouchCount < 3) {
+            return;
+        }
+
         const vectorA = points[0].sub(this._lastPoints[0]);
         const vectorB = points[1].sub(this._lastPoints[1]);
 

package/src/ui/handler_manager.ts

@@ -195,7 +195,7 @@ class HandlerManager {
         const tapDragZoom = new TapDragZoomHandler();
         this._add('tapDragZoom', tapDragZoom);
 
-        const touchPitch = map.touchPitch = new TouchPitchHandler();
+        const touchPitch = map.touchPitch = new TouchPitchHandler(map);
         this._add('touchPitch', touchPitch);
 
         const mouseRotate = new MouseRotateHandler(options);
@@ -205,7 +205,7 @@ class HandlerManager {
         this._add('mousePitch', mousePitch, ['mouseRotate']);
 
         const mousePan = new MousePanHandler(options);
-        const touchPan = new TouchPanHandler(options);
+        const touchPan = new TouchPanHandler(options, map);
         map.dragPan = new DragPanHandler(el, mousePan, touchPan);
         this._add('mousePan', mousePan);
         this._add('touchPan', touchPan, ['touchZoom', 'touchRotate']);

package/src/ui/map.test.ts

@@ -227,7 +227,7 @@ describe('Map', () => {
             map.transform.lngRange = [-120, 140];
             map.transform.latRange = [-60, 80];
             map.transform.resize(600, 400);
-            expect(map.transform.zoom).toBe(0.6983039737971012);
+            expect(map.transform.zoom).toBe(0.6983039737971014);
             expect(map.transform.unmodified).toBeTruthy();
             map.setStyle(createStyle());
             map.on('style.load', () => {
@@ -598,8 +598,8 @@ describe('Map', () => {
             expect(parseFloat(map.getBounds().getCenter().lat.toFixed(10))).toBe(0);
 
             expect(toFixed(map.getBounds().toArray())).toEqual(toFixed([
-                [ -70.31249999999976, -57.326521225216965 ],
-                [ 70.31249999999977, 57.32652122521695 ] ]));
+                [-70.31249999999976, -57.326521225216965],
+                [70.31249999999977, 57.32652122521695]]));
         });
 
         test('rotated bounds', () => {
@@ -631,7 +631,7 @@ describe('Map', () => {
 
     describe('#setMaxBounds', () => {
         test('constrains map bounds', () => {
-            const map = createMap({zoom:0});
+            const map = createMap({zoom: 0});
             map.setMaxBounds([[-130.4297, 50.0642], [-61.52344, 24.20688]]);
             expect(
                 toFixed([[-130.4297000000, 7.0136641176], [-61.5234400000, 60.2398142283]])
@@ -639,7 +639,7 @@ describe('Map', () => {
         });
 
         test('when no argument is passed, map bounds constraints are removed', () => {
-            const map = createMap({zoom:0});
+            const map = createMap({zoom: 0});
             map.setMaxBounds([[-130.4297, 50.0642], [-61.52344, 24.20688]]);
             expect(
                 toFixed([[-166.28906999999964, -27.6835270554], [-25.664070000000066, 73.8248206697]])
@@ -664,12 +664,12 @@ describe('Map', () => {
 
     describe('#getMaxBounds', () => {
         test('returns null when no bounds set', () => {
-            const map = createMap({zoom:0});
+            const map = createMap({zoom: 0});
             expect(map.getMaxBounds()).toBeNull();
         });
 
         test('returns bounds', () => {
-            const map = createMap({zoom:0});
+            const map = createMap({zoom: 0});
             const bounds = [[-130.4297, 50.0642], [-61.52344, 24.20688]] as LngLatBoundsLike;
             map.setMaxBounds(bounds);
             expect(map.getMaxBounds().toArray()).toEqual(bounds);
@@ -718,14 +718,14 @@ describe('Map', () => {
     });
 
     test('#setMinZoom', () => {
-        const map = createMap({zoom:5});
+        const map = createMap({zoom: 5});
         map.setMinZoom(3.5);
         map.setZoom(1);
         expect(map.getZoom()).toBe(3.5);
     });
 
     test('unset minZoom', () => {
-        const map = createMap({minZoom:5});
+        const map = createMap({minZoom: 5});
         map.setMinZoom(null);
         map.setZoom(1);
         expect(map.getZoom()).toBe(1);
@@ -739,7 +739,7 @@ describe('Map', () => {
     });
 
     test('ignore minZooms over maxZoom', () => {
-        const map = createMap({zoom:2, maxZoom:5});
+        const map = createMap({zoom: 2, maxZoom: 5});
         expect(() => {
             map.setMinZoom(6);
         }).toThrow();
@@ -748,14 +748,14 @@ describe('Map', () => {
     });
 
     test('#setMaxZoom', () => {
-        const map = createMap({zoom:0});
+        const map = createMap({zoom: 0});
         map.setMaxZoom(3.5);
         map.setZoom(4);
         expect(map.getZoom()).toBe(3.5);
     });
 
     test('unset maxZoom', () => {
-        const map = createMap({maxZoom:5});
+        const map = createMap({maxZoom: 5});
         map.setMaxZoom(null);
         map.setZoom(6);
         expect(map.getZoom()).toBe(6);
@@ -769,7 +769,7 @@ describe('Map', () => {
     });
 
     test('ignore maxZooms over minZoom', () => {
-        const map = createMap({minZoom:5});
+        const map = createMap({minZoom: 5});
         expect(() => {
             map.setMaxZoom(4);
         }).toThrow();
@@ -779,13 +779,13 @@ describe('Map', () => {
 
     test('throw on maxZoom smaller than minZoom at init', () => {
         expect(() => {
-            createMap({minZoom:10, maxZoom:5});
+            createMap({minZoom: 10, maxZoom: 5});
         }).toThrow(new Error('maxZoom must be greater than or equal to minZoom'));
     });
 
     test('throw on maxZoom smaller than minZoom at init with falsey maxZoom', () => {
         expect(() => {
-            createMap({minZoom:1, maxZoom:0});
+            createMap({minZoom: 1, maxZoom: 0});
         }).toThrow(new Error('maxZoom must be greater than or equal to minZoom'));
     });
 
@@ -827,7 +827,7 @@ describe('Map', () => {
     });
 
     test('unset maxPitch', () => {
-        const map = createMap({maxPitch:10});
+        const map = createMap({maxPitch: 10});
         map.setMaxPitch(null);
         map.setPitch(20);
         expect(map.getPitch()).toBe(20);
@@ -841,7 +841,7 @@ describe('Map', () => {
     });
 
     test('ignore maxPitchs over minPitch', () => {
-        const map = createMap({minPitch:10});
+        const map = createMap({minPitch: 10});
         expect(() => {
             map.setMaxPitch(0);
         }).toThrow();

package/src/ui/map.ts

@@ -59,7 +59,6 @@ import type {ControlPosition, IControl} from './control/control';
 import type {MapGeoJSONFeature} from '../util/vectortile_to_geojson';
 
 /* eslint-enable no-use-before-define */
-
 export type MapOptions = {
     hash?: boolean | string;
     interactive?: boolean;
@@ -86,6 +85,7 @@ export type MapOptions = {
     doubleClickZoom?: boolean;
     touchZoomRotate?: boolean;
     touchPitch?: boolean;
+    cooperativeGestures?: boolean | GestureOptions;
     trackResize?: boolean;
     center?: LngLatLike;
     zoom?: number;
@@ -107,6 +107,12 @@ export type MapOptions = {
     pixelRatio?: number;
 };
 
+export type GestureOptions = {
+    windowsHelpText?: string;
+    macHelpText?: string;
+    mobileHelpText?: string;
+};
+
 // See article here: https://medium.com/terria/typescript-transforming-optional-properties-to-required-properties-that-may-be-undefined-7482cb4e1585
 type Complete<T> = {
     [P in keyof Required<T>]: Pick<T, P> extends Required<Pick<T, P>> ? T[P] : (T[P] | undefined);
@@ -146,6 +152,7 @@ const defaultOptions = {
     doubleClickZoom: true,
     touchZoomRotate: true,
     touchPitch: true,
+    cooperativeGestures: undefined,
 
     bearingSnap: 7,
     clickTolerance: 3,
@@ -217,6 +224,13 @@ const defaultOptions = {
  * @param {boolean} [options.doubleClickZoom=true] If `true`, the "double click to zoom" interaction is enabled (see {@link DoubleClickZoomHandler}).
  * @param {boolean|Object} [options.touchZoomRotate=true] If `true`, the "pinch to rotate and zoom" interaction is enabled. An `Object` value is passed as options to {@link TouchZoomRotateHandler#enable}.
  * @param {boolean|Object} [options.touchPitch=true] If `true`, the "drag to pitch" interaction is enabled. An `Object` value is passed as options to {@link TouchPitchHandler#enable}.
+ * @param {boolean|GestureOptions} [options.cooperativeGestures=undefined] If `true` or set to an options object, map is only accessible on desktop while holding Command/Ctrl and only accessible on mobile with two fingers. Interacting with the map using normal gestures will trigger an informational screen. With this option enabled, "drag to pitch" requires a three-finger gesture.
+ * A valid options object includes the following properties to customize the text on the informational screen. The values below are the defaults.
+ * {
+ *   windowsHelpText: "Use Ctrl + scroll to zoom the map",
+ *   macHelpText: "Use ⌘ + scroll to zoom the map",
+ *   mobileHelpText: "Use two fingers to move the map",
+ * }
  * @param {boolean} [options.trackResize=true] If `true`, the map will automatically resize when the browser window resizes.
  * @param {LngLatLike} [options.center=[0, 0]] The initial geographical centerpoint of the map. If `center` is not specified in the constructor options, MapLibre GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `[0, 0]` Note: MapLibre GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
  * @param {number} [options.zoom=0] The initial zoom level of the map. If `zoom` is not specified in the constructor options, MapLibre GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0`.
@@ -271,6 +285,9 @@ class Map extends Camera {
     _controlContainer: HTMLElement;
     _controlPositions: {[_: string]: HTMLElement};
     _interactive: boolean;
+    _cooperativeGestures: boolean | GestureOptions;
+    _cooperativeGesturesScreen: HTMLElement;
+    _metaPress: boolean;
     _showTileBoundaries: boolean;
     _showCollisionBoxes: boolean;
     _showPadding: boolean;
@@ -381,6 +398,7 @@ class Map extends Camera {
         super(transform, {bearingSnap: options.bearingSnap});
 
         this._interactive = options.interactive;
+        this._cooperativeGestures = options.cooperativeGestures;
         this._maxTileCacheSize = options.maxTileCacheSize;
         this._failIfMajorPerformanceCaveat = options.failIfMajorPerformanceCaveat;
         this._preserveDrawingBuffer = options.preserveDrawingBuffer;
@@ -446,6 +464,10 @@ class Map extends Camera {
 
         this.handlers = new HandlerManager(this, options as CompleteMapOptions);
 
+        if (this._cooperativeGestures) {
+            this._setupCooperativeGestures();
+        }
+
         const hashName = (typeof options.hash === 'string' && options.hash) || undefined;
         this._hash = options.hash && (new Hash(hashName)).addTo(this);
         // don't set position from options if set through hash
@@ -1039,7 +1061,7 @@ class Map extends Camera {
      * | [`dataabort`](#map.event:dataabort)                       |                           |
      * | [`sourcedataabort`](#map.event:sourcedataabort)           |                           |
      *
-     * @param {string | Listener} layerIdOrListener The ID of a style layer or a listener if no ID is provided. Event will only be triggered if its location
+     * @param {string | Listener} layer The ID of a style layer or a listener if no ID is provided. Event will only be triggered if its location
      * is within a visible feature in this layer. The event will have a `features` property containing
      * an array of the matching features. If `layerIdOrListener` is not supplied, the event will not have a `features` property.
      * Please note that many event types are not compatible with the optional `layerIdOrListener` parameter.
@@ -1129,7 +1151,7 @@ class Map extends Camera {
      * a visible portion of the specified layer from outside that layer or outside the map canvas. `mouseleave`
      * and `mouseout` events are triggered when the cursor leaves a visible portion of the specified layer, or leaves
      * the map canvas.
-     * @param {string} layerIdOrListener The ID of a style layer or a listener if no ID is provided. Only events whose location is within a visible
+     * @param {string} layer The ID of a style layer or a listener if no ID is provided. Only events whose location is within a visible
      * feature in this layer will trigger the listener. The event will have a `features` property containing
      * an array of the matching features.
      * @param {Function} listener The function to be called when the event is fired.
@@ -1173,7 +1195,7 @@ class Map extends Camera {
      * Removes an event listener for layer-specific events previously added with `Map#on`.
      *
      * @param {string} type The event type previously used to install the listener.
-     * @param {string} layerIdOrListener The layer ID or listener previously used to install the listener.
+     * @param {string} layer The layer ID or listener previously used to install the listener.
      * @param {Function} listener The function previously installed as a listener.
      * @returns {Map} `this`
      */
@@ -1892,7 +1914,10 @@ class Map extends Camera {
      * A layer defines how data from a specified source will be styled. Read more about layer types
      * and available paint and layout properties in the [MapLibre Style Specification](https://maplibre.org/maplibre-gl-js-docs/style-spec/#layers).
      *
-     * @param {Object | CustomLayerInterface} layer The layer to add, conforming to either the MapLibre Style Specification's [layer definition](https://maplibre.org/maplibre-gl-js-docs/style-spec/#layers) or, less commonly, the {@link CustomLayerInterface} specification.
+     * TODO: JSDoc can't pass @param {(LayerSpecification & {source?: string | SourceSpecification}) | CustomLayerInterface} layer The layer to add,
+     * @param {Object} layer
+     * conforming to either the MapLibre Style Specification's [layer definition](https://maplibre.org/maplibre-gl-js-docs/style-spec/#layers) or,
+     * less commonly, the {@link CustomLayerInterface} specification.
      * The MapLibre Style Specification's layer definition is appropriate for most layers.
      *
      * @param {string} layer.id A unique identifer that you define.
@@ -1900,10 +1925,10 @@ class Map extends Camera {
      * A list of layer types is available in the [MapLibre Style Specification](https://maplibre.org/maplibre-gl-js-docs/style-spec/layers/#type).
      *
      * (This can also be `custom`. For more information, see {@link CustomLayerInterface}.)
-     * @param {string | Object} [layer.source] The data source for the layer.
+     * @param {string | SourceSpecification} [layer.source] The data source for the layer.
      * Reference a source that has _already been defined_ using the source's unique id.
      * Reference a _new source_ using a source object (as defined in the [MapLibre Style Specification](https://maplibre.org/maplibre-gl-js-docs/style-spec/sources/)) directly.
-     * This is **required** for all `layer.type` options _except_ for `custom`.
+     * This is **required** for all `layer.type` options _except_ for `custom` and `background`.
      * @param {string} [layer.sourceLayer] (optional) The name of the source layer within the specified `layer.source` to use for this style layer.
      * This is only applicable for vector tile sources and is **required** when `layer.source` is of the type `vector`.
      * @param {array} [layer.filter] (optional) An expression specifying conditions on source features.
@@ -1994,7 +2019,7 @@ class Map extends Camera {
      * @see [Add a vector tile source](https://maplibre.org/maplibre-gl-js-docs/example/vector-source/)
      * @see [Add a WMS source](https://maplibre.org/maplibre-gl-js-docs/example/wms/)
      */
-    addLayer(layer: LayerSpecification | CustomLayerInterface, beforeId?: string) {
+    addLayer(layer: (LayerSpecification & {source?: string | SourceSpecification}) | CustomLayerInterface, beforeId?: string) {
         this._lazyInitEmptyStyle();
         this.style.addLayer(layer, beforeId);
         return this._update(true);
@@ -2410,6 +2435,35 @@ class Map extends Camera {
         this._container.addEventListener('scroll', this._onMapScroll, false);
     }
 
+    _setupCooperativeGestures() {
+        const container = this._container;
+        this._metaPress = false;
+        this._cooperativeGesturesScreen = DOM.create('div', 'maplibregl-cooperative-gesture-screen', container);
+        let modifierKeyName = 'Control';
+        let desktopMessage = typeof this._cooperativeGestures !== 'boolean' && this._cooperativeGestures.windowsHelpText ? this._cooperativeGestures.windowsHelpText : 'Use Ctrl + scroll to zoom the map';
+        if (navigator.platform.indexOf('Mac') === 0) {
+            desktopMessage = typeof this._cooperativeGestures !== 'boolean' && this._cooperativeGestures.macHelpText ? this._cooperativeGestures.macHelpText : 'Use ⌘ + scroll to zoom the map';
+            modifierKeyName = 'Meta';
+        }
+        const mobileMessage = typeof this._cooperativeGestures !== 'boolean' && this._cooperativeGestures.mobileHelpText ? this._cooperativeGestures.mobileHelpText : 'Use two fingers to move the map';
+        this._cooperativeGesturesScreen.innerHTML = `
+            <div class="maplibregl-desktop-message">${desktopMessage}</div>
+            <div class="maplibregl-mobile-message">${mobileMessage}</div>
+        `;
+        document.addEventListener('keydown', (event) => {
+            if (event.key === modifierKeyName) this._metaPress = true;
+        });
+        document.addEventListener('keyup', (event) => {
+            if (event.key === modifierKeyName) this._metaPress = false;
+        });
+        // Add event to canvas container since gesture container is pointer-events: none
+        this._canvasContainer.addEventListener('wheel', (e) => {
+            this._onCooperativeGesture(e, this._metaPress, 1);
+        }, false);
+        // Remove the traditional pan classes
+        this._canvasContainer.classList.remove('mapboxgl-touch-drag-pan', 'maplibregl-touch-drag-pan');
+    }
+
     _resizeCanvas(width: number, height: number, pixelRatio: number) {
         // Request the required canvas size taking the pixelratio into account.
         this._canvas.width = pixelRatio * width;
@@ -2465,6 +2519,17 @@ class Map extends Camera {
         return false;
     }
 
+    _onCooperativeGesture(event: any, metaPress, touches) {
+        if (!metaPress && touches < 2) {
+            // Alert user how to scroll/pan
+            this._cooperativeGesturesScreen.classList.add('maplibregl-show');
+            setTimeout(() => {
+                this._cooperativeGesturesScreen.classList.remove('maplibregl-show');
+            }, 100);
+        }
+        return false;
+    }
+
     /**
      * Returns a Boolean indicating whether the map is fully loaded.
      *
@@ -2714,6 +2779,9 @@ class Map extends Camera {
         this._canvas.removeEventListener('webglcontextlost', this._contextLost, false);
         DOM.remove(this._canvasContainer);
         DOM.remove(this._controlContainer);
+        if (this._cooperativeGestures) {
+            DOM.remove(this._cooperativeGesturesScreen);
+        }
         this._container.classList.remove('maplibregl-map', 'mapboxgl-map');
 
         PerformanceUtils.clearMetrics();