#2498: Don't show cooperativeGestures messages when scrollZoom is dis…

src/ui/control/control.ts

@@ -4,7 +4,7 @@ import type {Map} from '../map';
  * A position defintion for the control to be placed, can be in one of the corners of the map.
  * When two or more controls are places in the same location they are stacked toward the center of the map.
  */
-export type ControlPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export type ControlPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'full';
 
 /**
  * Interface for interactive controls added to the map. This is a

src/ui/control/cooperative_gesture_contol.ts

@@ -0,0 +1,113 @@
+import {DOM} from '../../util/dom';
+
+import type {Map} from '../map';
+import type {ControlPosition, IControl} from './control';
+
+/**
+ * The {@link CooperativeGestureControl} options object
+ */
+/**
+ * An options object for the gesture settings
+ * @example
+ * ```ts
+ * let options = {
+ *   windowsHelpText: "Use Ctrl + scroll to zoom the map",
+ *   macHelpText: "Use ⌘ + scroll to zoom the map",
+ *   mobileHelpText: "Use two fingers to move the map",
+ * }
+ * ```
+ */
+export type GestureOptions = {
+    windowsHelpText?: string;
+    macHelpText?: string;
+    mobileHelpText?: string;
+};
+
+/**
+ * A `CooperativeGestureControl` is a control that adds cooperative gesture info when user tries to zoom in/out.
+ *
+ * @group Markers and Controls
+ *
+ * @example
+ * ```ts
+ * map.addControl(new maplibregl.CooperativeGestureControl({
+ *   windowsHelpText: "Use Ctrl + scroll to zoom the map",
+ *   macHelpText: "Use ⌘ + scroll to zoom the map",
+ *   mobileHelpText: "Use two fingers to move the map",
+ * }));
+ * ```
+ **/
+export class CooperativeGestureControl implements IControl {
+    options: boolean | GestureOptions;
+    _map: Map;
+    _container: HTMLElement;
+    _metaKey: keyof MouseEvent = navigator.userAgent.indexOf('Mac') !== -1 ? 'metaKey' : 'ctrlKey';
+
+    constructor(options: boolean | GestureOptions = {}) {
+        this.options = options;
+    }
+
+    getDefaultPosition(): ControlPosition {
+        return 'full';
+    }
+
+    /** {@inheritDoc IControl.onAdd} */
+    onAdd(map:Map) {
+        this._map = map;
+        const mapCanvasContainer = this._map.getCanvasContainer();
+        const cooperativeGestures = this._map.getCooperativeGestures();
+        this._container = DOM.create('div', 'maplibregl-cooperative-gesture-screen', this._map.getContainer());
+        let desktopMessage = typeof cooperativeGestures !== 'boolean' && cooperativeGestures.windowsHelpText ? cooperativeGestures.windowsHelpText : 'Use Ctrl + scroll to zoom the map';
+        if (this._metaKey === 'metaKey') {
+            desktopMessage = typeof cooperativeGestures !== 'boolean' && cooperativeGestures.macHelpText ? cooperativeGestures.macHelpText : 'Use ⌘ + scroll to zoom the map';
+        }
+        const mobileMessage = typeof cooperativeGestures !== 'boolean' && cooperativeGestures.mobileHelpText ? cooperativeGestures.mobileHelpText : 'Use two fingers to move the map';
+        // Create and append the desktop message div
+        const desktopDiv = document.createElement('div');
+        desktopDiv.className = 'maplibregl-desktop-message';
+        desktopDiv.textContent = desktopMessage;
+        this._container.appendChild(desktopDiv);
+        // Create and append the mobile message div
+        const mobileDiv = document.createElement('div');
+        mobileDiv.className = 'maplibregl-mobile-message';
+        mobileDiv.textContent = mobileMessage;
+        this._container.appendChild(mobileDiv);
+        // Remove cooperative gesture screen from the accessibility tree since screenreaders cannot interact with the map using gestures
+        this._container.setAttribute('aria-hidden', 'true');
+        // Add event to canvas container since gesture container is pointer-events: none
+        this._map.on('wheel', this._cooperativeGesturesOnWheel);
+        this._map.on('touchmove', this._cooperativeGesturesOnTouch);
+        // Add a cooperative gestures class (enable touch-action: pan-x pan-y;)
+        mapCanvasContainer.classList.add('maplibregl-cooperative-gestures');
+        return this._container;
+    }
+    /** {@inheritDoc IControl.onRemove} */
+    onRemove(map: Map) {
+        DOM.remove(this._container);
+        const mapCanvasContainer = map.getCanvasContainer();
+        map.off('wheel', this._cooperativeGesturesOnWheel);
+        map.off('touchmove', this._cooperativeGesturesOnTouch);
+        mapCanvasContainer.classList.remove('maplibregl-cooperative-gestures');
+        this._map = undefined;
+    }
+
+    _cooperativeGesturesOnTouch = () => {
+        this._onCooperativeGesture(false);
+    };
+
+    _cooperativeGesturesOnWheel = (event: WheelEvent) => {
+        this._onCooperativeGesture(event['originalEvent'][this._metaKey]);
+    };
+
+    _onCooperativeGesture(metaPress:boolean) {
+        if (!metaPress) {
+            // Alert user how to scroll/pan
+            this._container.classList.add('maplibregl-show');
+            setTimeout(() => {
+                this._container.classList.remove('maplibregl-show');
+            }, 100);
+        }
+        return false;
+    }
+
+}

src/ui/control/fullscreen_control.ts

@@ -3,8 +3,9 @@ import {DOM} from '../../util/dom';
 import {warnOnce} from '../../util/util';
 
 import {Event, Evented} from '../../util/evented';
-import type {Map, GestureOptions} from '../map';
+import type {Map} from '../map';
 import type {IControl} from './control';
+import {GestureOptions} from './cooperative_gesture_contol';
 
 /**
  * The {@link FullscreenControl} options

src/ui/handler/scroll_zoom.ts

@@ -31,6 +31,7 @@ const maxScalePerFrame = 2;
 export class ScrollZoomHandler implements Handler {
     _map: Map;
     _tr: TransformProvider;
+    _metaKey: keyof MouseEvent = navigator.userAgent.indexOf('Mac') !== -1 ? 'metaKey' : 'ctrlKey';
     _el: HTMLElement;
     _enabled: boolean;
     _active: boolean;
@@ -136,6 +137,8 @@ export class ScrollZoomHandler implements Handler {
         if (this.isEnabled()) return;
         this._enabled = true;
         this._aroundCenter = !!options && (options as AroundCenterOptions).around === 'center';
+        const cooperativeGestures = this._map.getCooperativeGestures();
+        if (cooperativeGestures) this._map.setCooperativeGestures(cooperativeGestures);
     }
 
     /**
@@ -147,14 +150,15 @@ export class ScrollZoomHandler implements Handler {
      * ```
      */
     disable() {
+        this._map.setCooperativeGestures(false);
         if (!this.isEnabled()) return;
         this._enabled = false;
     }
 
     wheel(e: WheelEvent) {
         if (!this.isEnabled()) return;
         if (this._map._cooperativeGestures) {
-            if (e[this._map._metaKey]) {
+            if (e[this._metaKey]) {
                 e.preventDefault();
             } else {
                 return;

src/ui/handler/touch_pan.ts

@@ -1,8 +1,9 @@
 import Point from '@mapbox/point-geometry';
 import {indexTouches} from './handler_util';
 import type {Map} from '../map';
-import {GestureOptions} from '../map';
+
 import {Handler} from '../handler_manager';
+import {GestureOptions} from '../control/cooperative_gesture_contol';
 
 export class TouchPanHandler implements Handler {
 
@@ -15,7 +16,6 @@ export class TouchPanHandler implements Handler {
     _clickTolerance: number;
     _sum: Point;
     _map: Map;
-    _cancelCooperativeMessage: boolean;
 
     constructor(options: {
         clickTolerance: number;
@@ -31,27 +31,13 @@ export class TouchPanHandler implements Handler {
         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>) {
         return this._calculateTransform(e, points, mapTouches);
     }
 
     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);

src/ui/map.test.ts

@@ -2677,6 +2677,12 @@ describe('Map', () => {
 
             expect(map.getContainer().querySelector('.maplibregl-cooperative-gesture-screen').getAttribute('aria-hidden')).toBeTruthy();
         });
+
+        test('cooperativeGesture container element is not available when scrollZoom disabled', () => {
+            const map = createMap({cooperativeGestures: true});
+            map.scrollZoom.disable();
+            expect(map.getContainer().querySelector('.maplibregl-cooperative-gesture-screen')).toBeFalsy();
+        });
     });
 
     describe('getCameraTargetElevation', () => {

src/ui/map.ts

@@ -65,6 +65,7 @@ import {Terrain} from '../render/terrain';
 import {RenderToTexture} from '../render/render_to_texture';
 import {config} from '../util/config';
 import type {QueryRenderedFeaturesOptions, QuerySourceFeatureOptions} from '../source/query_features';
+import {CooperativeGestureControl, GestureOptions} from './control/cooperative_gesture_contol';
 
 const version = packageJSON.version;
 
@@ -328,23 +329,6 @@ export type MapOptions = {
     maxCanvasSize?: [number, number];
 };
 
-/**
- * An options object for the gesture settings
- * @example
- * ```ts
- * let options = {
- *   windowsHelpText: "Use Ctrl + scroll to zoom the map",
- *   macHelpText: "Use ⌘ + scroll to zoom the map",
- *   mobileHelpText: "Use two fingers to move the map",
- * }
- * ```
- */
-export type GestureOptions = {
-    windowsHelpText?: string;
-    macHelpText?: string;
-    mobileHelpText?: string;
-};
-
 export type AddImageOptions = {
 
 }
@@ -450,15 +434,13 @@ export class Map extends Camera {
     style: Style;
     painter: Painter;
     handlers: HandlerManager;
-
     _container: HTMLElement;
     _canvasContainer: HTMLElement;
     _controlContainer: HTMLElement;
     _controlPositions: {[_: string]: HTMLElement};
     _interactive: boolean;
     _cooperativeGestures: boolean | GestureOptions;
-    _cooperativeGesturesScreen: HTMLElement;
-    _metaKey: keyof MouseEvent;
+    _cooperativeGesturesControl: CooperativeGestureControl;
     _showTileBoundaries: boolean;
     _showCollisionBoxes: boolean;
     _showPadding: boolean;
@@ -583,7 +565,6 @@ export class Map extends Camera {
 
         this._interactive = options.interactive;
         this._cooperativeGestures = options.cooperativeGestures;
-        this._metaKey = navigator.platform.indexOf('Mac') === 0 ? 'metaKey' : 'ctrlKey';
         this._maxTileCacheSize = options.maxTileCacheSize;
         this._maxTileCacheZoomLevels = options.maxTileCacheZoomLevels;
         this._failIfMajorPerformanceCaveat = options.failIfMajorPerformanceCaveat;
@@ -656,8 +637,8 @@ export class Map extends Camera {
 
         this.handlers = new HandlerManager(this, options as CompleteMapOptions);
 
-        if (this._cooperativeGestures) {
-            this._setupCooperativeGestures();
+        if (options.cooperativeGestures) {
+            this.setCooperativeGestures(options.cooperativeGestures);
         }
 
         const hashName = (typeof options.hash === 'string' && options.hash) || undefined;
@@ -751,7 +732,7 @@ export class Map extends Camera {
         const positionContainer = this._controlPositions[position];
         if (position.indexOf('bottom') !== -1) {
             positionContainer.insertBefore(controlElement, positionContainer.firstChild);
-        } else {
+        } else if (position !== 'full') {
             positionContainer.appendChild(controlElement);
         }
         return this;
@@ -1176,9 +1157,14 @@ export class Map extends Camera {
     setCooperativeGestures(gestureOptions?: GestureOptions | boolean | null): Map {
         this._cooperativeGestures = gestureOptions;
         if (this._cooperativeGestures) {
-            this._setupCooperativeGestures();
+            if (this._cooperativeGesturesControl) {
+                //remove existing control
+                this.removeControl(this._cooperativeGesturesControl);
+            }
+            this._cooperativeGesturesControl = new CooperativeGestureControl(this._cooperativeGestures);
+            this.addControl(this._cooperativeGesturesControl);
         } else {
-            this._destroyCooperativeGestures();
+            this.removeControl(this._cooperativeGesturesControl);
         }
 
         return this;
@@ -2934,45 +2920,12 @@ export class Map extends Camera {
         const controlContainer = this._controlContainer = DOM.create('div', 'maplibregl-control-container', container);
         const positions = this._controlPositions = {};
         ['top-left', 'top-right', 'bottom-left', 'bottom-right'].forEach((positionName) => {
-            positions[positionName] = DOM.create('div', `maplibregl-ctrl-${positionName} `, controlContainer);
+            positions[positionName] = DOM.create('div', `maplibregl-ctrl-${positionName}`, controlContainer);
         });
 
         this._container.addEventListener('scroll', this._onMapScroll, false);
     }
 
-    _cooperativeGesturesOnWheel = (event: WheelEvent) => {
-        this._onCooperativeGesture(event, event[this._metaKey], 1);
-    };
-
-    _setupCooperativeGestures() {
-        const container = this._container;
-        this._cooperativeGesturesScreen = DOM.create('div', 'maplibregl-cooperative-gesture-screen', container);
-        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';
-        }
-        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>
-        `;
-
-        // Remove cooperative gesture screen from the accessibility tree since screenreaders cannot interact with the map using gestures
-        this._cooperativeGesturesScreen.setAttribute('aria-hidden', 'true');
-
-        // Add event to canvas container since gesture container is pointer-events: none
-        this._canvasContainer.addEventListener('wheel', this._cooperativeGesturesOnWheel, false);
-
-        // Add a cooperative gestures class (enable touch-action: pan-x pan-y;)
-        this._canvasContainer.classList.add('maplibregl-cooperative-gestures');
-    }
-
-    _destroyCooperativeGestures() {
-        DOM.remove(this._cooperativeGesturesScreen);
-        this._canvasContainer.removeEventListener('wheel', this._cooperativeGesturesOnWheel, false);
-        this._canvasContainer.classList.remove('maplibregl-cooperative-gestures');
-    }
-
     _resizeCanvas(width: number, height: number, pixelRatio: number) {
         // Request the required canvas size taking the pixelratio into account.
         this._canvas.width = Math.floor(pixelRatio * width);
@@ -3047,17 +3000,6 @@ export 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.
      *
@@ -3285,9 +3227,6 @@ export class Map extends Camera {
         this._canvas.removeEventListener('webglcontextlost', this._contextLost, false);
         DOM.remove(this._canvasContainer);
         DOM.remove(this._controlContainer);
-        if (this._cooperativeGestures) {
-            this._destroyCooperativeGestures();
-        }
         this._container.classList.remove('maplibregl-map');
 
         PerformanceUtils.clearMetrics();