@scoova/mgl 1.0.0

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

@@ -0,0 +1,338 @@
+import {browser} from '../../util/browser';
+import {Map} from '../map';
+import {DOM} from '../../util/dom';
+import simulate from '../../../test/unit/lib/simulate_interaction';
+import {beforeMapTest, sleep} from '../../util/test/util';
+
+function createMap(cooperativeGestures) {
+    return new Map({
+        container: DOM.create('div', '', window.document.body),
+        style: {
+            'version': 8,
+            'sources': {},
+            'layers': []
+        },
+        cooperativeGestures
+    });
+}
+
+beforeEach(() => {
+    beforeMapTest();
+});
+
+describe('CoopGesturesHandler', () => {
+
+    test('Does not zoom on wheel if no key is down', async () => {
+        const browserNow = jest.spyOn(browser, 'now');
+        let now = 1555555555555;
+        browserNow.mockReturnValue(now);
+
+        const map = createMap(true);
+        map._renderTaskQueue.run();
+
+        const cooperativegestureprevented = jest.fn();
+        map.on('cooperativegestureprevented', cooperativegestureprevented);
+
+        const startZoom = map.getZoom();
+        // simulate a single 'wheel' event
+        const wheelEvent = {type: 'wheel', deltaY: -simulate.magicWheelZoomDelta};
+        simulate.wheel(map.getCanvas(), wheelEvent);
+        map._renderTaskQueue.run();
+        expect(map.getContainer().querySelector('.maplibregl-cooperative-gesture-screen.maplibregl-show')).toBeInstanceOf(HTMLDivElement);
+
+        // ensure events are emitted when cooperative gesture is prevented
+        expect(cooperativegestureprevented).toHaveBeenCalledTimes(1);
+        expect(cooperativegestureprevented).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'cooperativegestureprevented',
+            gestureType: 'wheel_zoom',
+        }));
+        expect(cooperativegestureprevented.mock.calls[0][0].originalEvent).toMatchObject(wheelEvent);
+
+        now += 400;
+        browserNow.mockReturnValue(now);
+        map._renderTaskQueue.run();
+
+        const endZoom = map.getZoom();
+        expect(endZoom).toBeCloseTo(startZoom);
+
+        await sleep(200);
+
+        expect(map.getContainer().querySelector('.maplibregl-cooperative-gesture-screen.maplibregl-show')).toBeNull();
+        map.remove();
+    });
+
+    test('Zooms on wheel if no key is down after disabling cooperative gestures', () => {
+        const browserNow = jest.spyOn(browser, 'now');
+        let now = 1555555555555;
+        browserNow.mockReturnValue(now);
+
+        const map = createMap(true);
+        map.cooperativeGestures.disable();
+        map._renderTaskQueue.run();
+
+        const startZoom = map.getZoom();
+        // simulate a single 'wheel' event
+        simulate.wheel(map.getCanvas(), {type: 'wheel', deltaY: -simulate.magicWheelZoomDelta});
+        map._renderTaskQueue.run();
+
+        now += 400;
+        browserNow.mockReturnValue(now);
+        map._renderTaskQueue.run();
+
+        const endZoom = map.getZoom();
+        expect(endZoom - startZoom).toBeCloseTo(0.0285, 3);
+
+        map.remove();
+    });
+
+    test('Zooms on wheel if control key is down', () => {
+        // NOTE: This should pass regardless of whether cooperativeGestures is enabled or not
+        const browserNow = jest.spyOn(browser, 'now');
+        let now = 1555555555555;
+        browserNow.mockReturnValue(now);
+
+        const map = createMap(true);
+        map._renderTaskQueue.run();
+
+        const startZoom = map.getZoom();
+        // simulate a single 'wheel' event
+        simulate.wheel(map.getCanvas(), {type: 'wheel', deltaY: -simulate.magicWheelZoomDelta, ctrlKey: true});
+        map._renderTaskQueue.run();
+
+        now += 400;
+        browserNow.mockReturnValue(now);
+        map._renderTaskQueue.run();
+
+        const endZoom = map.getZoom();
+        expect(endZoom - startZoom).toBeCloseTo(0.0285, 3);
+
+        map.remove();
+    });
+
+    test('Zooms on trackpad pinch when metaKey is the bypass key', () => {
+        // NOTE: This should pass regardless of whether cooperativeGestures is enabled or not
+        const browserNow = jest.spyOn(browser, 'now');
+        let now = 1555555555555;
+        browserNow.mockReturnValue(now);
+
+        const map = createMap(true);
+
+        // pretend we're on a Mac, where the ctrlKey isn't the bypassKey
+        map.cooperativeGestures._bypassKey = 'metaKey';
+        map._renderTaskQueue.run();
+
+        const startZoom = map.getZoom();
+        // simulate a single 'wheel' trackpad pinch event
+        simulate.wheel(map.getCanvas(), {
+            type: 'wheel',
+            deltaY: -simulate.magicWheelZoomDelta,
+
+            // this is how a browser identifies a trackpad pinch
+            ctrlKey: true
+        });
+        map._renderTaskQueue.run();
+
+        now += 400;
+        browserNow.mockReturnValue(now);
+        map._renderTaskQueue.run();
+
+        const endZoom = map.getZoom();
+        expect(endZoom - startZoom).toBeCloseTo(0.0285, 3);
+
+        map.remove();
+    });
+
+    test('Does not show message if scrollZoom is disabled', () => {
+        // NOTE: This should pass regardless of whether cooperativeGestures is enabled or not
+        const browserNow = jest.spyOn(browser, 'now');
+        const now = 1555555555555;
+        browserNow.mockReturnValue(now);
+
+        const map = createMap(true);
+
+        const cooperativegestureprevented = jest.fn();
+        map.on('cooperativegestureprevented', cooperativegestureprevented);
+
+        map.scrollZoom.disable();
+        map._renderTaskQueue.run();
+
+        // simulate a single 'wheel' event
+        simulate.wheel(map.getCanvas(), {type: 'wheel', deltaY: -simulate.magicWheelZoomDelta});
+        map._renderTaskQueue.run();
+        expect(map.getContainer().querySelector('.maplibregl-cooperative-gesture-screen.maplibregl-show')).toBeNull();
+
+        // ensure events are not emitted when cooperative gesture is prevented
+        expect(cooperativegestureprevented).toHaveBeenCalledTimes(0);
+
+        map.remove();
+    });
+
+    test('Does not pan on touchmove with a single touch', () => {
+        const map = createMap(true);
+        const target = map.getCanvas();
+        const startCenter = map.getCenter();
+        map._renderTaskQueue.run();
+
+        const dragstart = jest.fn();
+        const drag      = jest.fn();
+        const dragend = jest.fn();
+        const cooperativegestureprevented = jest.fn();
+
+        map.on('dragstart', dragstart);
+        map.on('drag',      drag);
+        map.on('dragend', dragend);
+        map.on('cooperativegestureprevented', cooperativegestureprevented);
+
+        simulate.touchstart(target, {touches: [{target, clientX: 0, clientY: 0}]});
+        map._renderTaskQueue.run();
+
+        simulate.touchmove(target, {touches: [{target, clientX: 10, clientY: 10}]});
+        map._renderTaskQueue.run();
+
+        expect(map.getContainer().querySelector('.maplibregl-cooperative-gesture-screen.maplibregl-show')).toBeInstanceOf(HTMLDivElement);
+
+        // ensure events are emitted when cooperative gesture is prevented
+        expect(cooperativegestureprevented).toHaveBeenCalledTimes(1);
+        expect(cooperativegestureprevented).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'cooperativegestureprevented',
+            gestureType: 'touch_pan',
+        }));
+        expect(cooperativegestureprevented.mock.calls[0][0].originalEvent.touches[0].clientX).toBe(10);
+
+        simulate.touchend(target);
+        map._renderTaskQueue.run();
+
+        const endCenter = map.getCenter();
+        expect(endCenter.lng).toEqual(startCenter.lng);
+        expect(endCenter.lat).toEqual(startCenter.lat);
+
+        map.remove();
+    });
+
+    test('Pans on touchmove with a single touch after disabling cooperative gestures', () => {
+        const map = createMap(true);
+        const cooperativegestureprevented = jest.fn();
+        map.on('cooperativegestureprevented', cooperativegestureprevented);
+
+        map.cooperativeGestures.disable();
+        const target = map.getCanvasContainer();
+        const startCenter = map.getCenter();
+        map._renderTaskQueue.run();
+
+        simulate.touchstart(target, {touches: [{target, clientX: 0, clientY: 0}, {target, clientX: 1, clientY: 1}]});
+        map._renderTaskQueue.run();
+
+        simulate.touchmove(target, {touches: [{target, clientX: 10, clientY: 10}, {target, clientX: 11, clientY: 11}]});
+        map._renderTaskQueue.run();
+
+        expect(map.getContainer().querySelector('.maplibregl-cooperative-gesture-screen.maplibregl-show')).toBeNull();
+        expect(cooperativegestureprevented).toHaveBeenCalledTimes(0);
+
+        simulate.touchend(target);
+        map._renderTaskQueue.run();
+
+        const endCenter = map.getCenter();
+        expect(endCenter.lng).toBeGreaterThan(startCenter.lng);
+        expect(endCenter.lat).toBeGreaterThan(startCenter.lat);
+
+        map.remove();
+    });
+
+    test('Does pan on touchmove with a double touch but does not change pitch', () => {
+        const map = createMap(true);
+
+        const cooperativegestureprevented = jest.fn();
+        map.on('cooperativegestureprevented', cooperativegestureprevented);
+
+        const target = map.getCanvas();
+        const startCenter = map.getCenter();
+        const startPitch = map.getPitch();
+        map._renderTaskQueue.run();
+
+        simulate.touchstart(target, {touches: [{target, clientX: 0, clientY: 0}, {target, clientX: 1, clientY: 1}]});
+        map._renderTaskQueue.run();
+
+        simulate.touchmove(target, {touches: [{target, clientX: 10, clientY: 10}, {target, clientX: 11, clientY: 11}]});
+        map._renderTaskQueue.run();
+
+        expect(map.getContainer().querySelector('.maplibregl-cooperative-gesture-screen.maplibregl-show')).toBeNull();
+        expect(cooperativegestureprevented).toHaveBeenCalledTimes(0);
+
+        simulate.touchend(target);
+        map._renderTaskQueue.run();
+
+        const endCenter = map.getCenter();
+        expect(endCenter.lng).toBeGreaterThan(startCenter.lng);
+        expect(endCenter.lat).toBeGreaterThan(startCenter.lat);
+        expect(startPitch).toBe(map.getPitch());
+
+        map.remove();
+    });
+
+    test('Drag pitch works with 3 fingers', () => {
+        // NOTE: This should pass regardless of whether cooperativeGestures is enabled or not
+        const map = createMap(true);
+
+        const cooperativegestureprevented = jest.fn();
+        map.on('cooperativegestureprevented', cooperativegestureprevented);
+
+        const target = map.getCanvas();
+        const startPitch = map.getPitch();
+        map._renderTaskQueue.run();
+
+        simulate.touchstart(target, {touches: [{target, clientX: 0, clientY: 0}, {target, clientX: 1, clientY: 1}, {target, clientX: 2, clientY: 2}]});
+        map._renderTaskQueue.run();
+
+        simulate.touchmove(target, {touches: [{target, clientX: 0, clientY: -10}, {target, clientX: 1, clientY: -11}, {target, clientX: 2, clientY: -12}]});
+        map._renderTaskQueue.run();
+
+        expect(map.getContainer().querySelector('.maplibregl-cooperative-gesture-screen.maplibregl-show')).toBeNull();
+        expect(cooperativegestureprevented).toHaveBeenCalledTimes(0);
+
+        simulate.touchend(target);
+        map._renderTaskQueue.run();
+
+        const endPitch = map.getPitch();
+        expect(endPitch).toBeGreaterThan(startPitch);
+
+        map.remove();
+    });
+
+    test('Initially disabled cooperative gestures can be later enabled', () => {
+        const browserNow = jest.spyOn(browser, 'now');
+        let now = 1555555555555;
+        browserNow.mockReturnValue(now);
+
+        const map = createMap(false);
+        map._renderTaskQueue.run();
+
+        const startZoom = map.getZoom();
+        // simulate a single 'wheel' event
+        simulate.wheel(map.getCanvas(), {type: 'wheel', deltaY: -simulate.magicWheelZoomDelta});
+        map._renderTaskQueue.run();
+
+        now += 400;
+        browserNow.mockReturnValue(now);
+        map._renderTaskQueue.run();
+
+        const midZoom = map.getZoom();
+        expect(midZoom - startZoom).toBeCloseTo(0.0285, 3);
+
+        // Enable cooperative gestures
+        map.cooperativeGestures.enable();
+
+        // This 'wheel' event should not zoom
+        simulate.wheel(map.getCanvas(), {type: 'wheel', deltaY: -simulate.magicWheelZoomDelta});
+        map._renderTaskQueue.run();
+
+        now += 400;
+        browserNow.mockReturnValue(now);
+        map._renderTaskQueue.run();
+
+        const endZoom = map.getZoom();
+        expect(endZoom).toBeCloseTo(midZoom);
+
+        map.remove();
+    });
+
+});

package/src/ui/handler/cooperative_gestures.ts

@@ -0,0 +1,111 @@
+import {DOM} from '../../util/dom';
+import {Event} from '../../util/evented';
+import {Handler} from '../handler_manager';
+
+import type {Map} from '../map';
+
+/**
+ * The {@link CooperativeGesturesHandler} options object for the gesture settings
+ */
+export type GestureOptions = boolean;
+
+/**
+ * A `CooperativeGestureHandler` is a control that adds cooperative gesture info when user tries to zoom in/out.
+ *
+ * When the CooperativeGestureHandler blocks a gesture, it will emit a `cooperativegestureprevented` event.
+ *
+ * @group Handlers
+ *
+ * @example
+ * ```ts
+ * const map = new Map({
+ *   cooperativeGestures: true
+ * });
+ * ```
+ * @see [Example: cooperative gestures](https://maplibre.org/maplibre-gl-js/docs/examples/cooperative-gestures/)
+ **/
+export class CooperativeGesturesHandler implements Handler {
+    _options: GestureOptions;
+    _map: Map;
+    _container: HTMLElement;
+    /**
+     * This is the key that will allow to bypass the cooperative gesture protection
+     */
+    _bypassKey: 'metaKey' | 'ctrlKey' = navigator.userAgent.indexOf('Mac') !== -1 ? 'metaKey' : 'ctrlKey';
+    _enabled: boolean;
+
+    constructor(map: Map, options: GestureOptions) {
+        this._map = map;
+        this._options = options;
+        this._enabled = false;
+    }
+    isActive(): boolean {
+        return false;
+    }
+    reset(): void {}
+
+    _setupUI() {
+        if (this._container) return;
+        const mapCanvasContainer = this._map.getCanvasContainer();
+        // Add a cooperative gestures class (enable touch-action: pan-x pan-y;)
+        mapCanvasContainer.classList.add('maplibregl-cooperative-gestures');
+        this._container = DOM.create('div', 'maplibregl-cooperative-gesture-screen', mapCanvasContainer);
+        let desktopMessage = this._map._getUIString('CooperativeGesturesHandler.WindowsHelpText');
+        if (this._bypassKey === 'metaKey') {
+            desktopMessage = this._map._getUIString('CooperativeGesturesHandler.MacHelpText');
+        }
+        const mobileMessage = this._map._getUIString('CooperativeGesturesHandler.MobileHelpText');
+        // 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');
+    }
+
+    _destroyUI() {
+        if (this._container) {
+            DOM.remove(this._container);
+            const mapCanvasContainer = this._map.getCanvasContainer();
+            mapCanvasContainer.classList.remove('maplibregl-cooperative-gestures');
+        }
+        delete this._container;
+    }
+
+    enable() {
+        this._setupUI();
+        this._enabled = true;
+    }
+
+    disable() {
+        this._enabled = false;
+        this._destroyUI();
+    }
+
+    isEnabled() {
+        return this._enabled;
+    }
+
+    isBypassed(event: MouseEvent | WheelEvent | PointerEvent) {
+        return event[this._bypassKey];
+    }
+
+    notifyGestureBlocked(gestureType: 'wheel_zoom' | 'touch_pan', originalEvent: Event) {
+        if (!this._enabled) return;
+
+        // notify subscribers that a cooperative gesture was prevented
+        this._map.fire(new Event('cooperativegestureprevented', {gestureType, originalEvent}));
+
+        // Alert user how to scroll/pan
+        this._container.classList.add('maplibregl-show');
+        setTimeout(() => {
+            this._container.classList.remove('maplibregl-show');
+        }, 100);
+    }
+}

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

@@ -0,0 +1,151 @@
+import simulate from '../../../test/unit/lib/simulate_interaction';
+import {beforeMapTest, sleep} from '../../util/test/util';
+import {Map, MapOptions} from '../map';
+
+function createMap() {
+    return new Map({container: window.document.createElement('div')} as any as MapOptions);
+}
+
+async function simulateDoubleTap(map, delay = 100) {
+    const canvas = map.getCanvas();
+
+    simulate.touchstart(canvas, {touches: [{target: canvas, clientX: 0, clientY: 0}]});
+    simulate.touchend(canvas);
+
+    await sleep(delay);
+
+    simulate.touchstart(canvas, {touches: [{target: canvas, clientX: 0, clientY: 0}]});
+    simulate.touchend(canvas);
+    map._renderTaskQueue.run();
+}
+
+beforeEach(() => {
+    beforeMapTest();
+});
+
+describe('dbclick_zoom', () => {
+    test('DoubleClickZoomHandler zooms on dblclick event', () => {
+        const map = createMap();
+
+        const zoom = jest.fn();
+        map.on('zoomstart', zoom);
+
+        simulate.dblclick(map.getCanvas());
+        map._renderTaskQueue.run();
+
+        expect(zoom).toHaveBeenCalled();
+
+        map.remove();
+    });
+
+    test('DoubleClickZoomHandler does not zoom if preventDefault is called on the dblclick event', () => {
+        const map = createMap();
+
+        map.on('dblclick', e => e.preventDefault());
+
+        const zoom = jest.fn();
+        map.on('zoomstart', zoom);
+
+        simulate.dblclick(map.getCanvas());
+        map._renderTaskQueue.run();
+
+        expect(zoom).not.toHaveBeenCalled();
+
+        map.remove();
+    });
+
+    test('DoubleClickZoomHandler zooms on double tap if touchstart events are < 300ms apart', async () => {
+        const map = createMap();
+
+        const zoom = jest.fn();
+        map.on('zoomstart', zoom);
+
+        await simulateDoubleTap(map, 100);
+        expect(zoom).toHaveBeenCalled();
+
+        map.remove();
+    });
+
+    test('DoubleClickZoomHandler does not zoom on double tap if touchstart events are > 500ms apart', async () => {
+        const map = createMap();
+
+        const zoom = jest.fn();
+        map.on('zoom', zoom);
+
+        await simulateDoubleTap(map, 500);
+
+        expect(zoom).not.toHaveBeenCalled();
+        map.remove();
+    });
+
+    test('DoubleClickZoomHandler does not zoom on double tap if touchstart events are in different locations', async () => {
+        const map = createMap();
+
+        const zoom = jest.fn();
+        map.on('zoom', zoom);
+
+        const canvas = map.getCanvas();
+
+        simulate.touchstart(canvas, {touches: [{clientX: 0, clientY: 0}]});
+        simulate.touchend(canvas);
+        await sleep(100);
+        simulate.touchstart(canvas, {touches: [{clientX: 30.5, clientY: 30.5}]});
+        simulate.touchend(canvas);
+        map._renderTaskQueue.run();
+
+        expect(zoom).not.toHaveBeenCalled();
+
+        map.remove();
+    });
+
+    test('DoubleClickZoomHandler zooms on the second touchend event of a double tap', () => {
+        const map = createMap();
+
+        const zoom = jest.fn();
+        map.on('zoomstart', zoom);
+
+        const canvas = map.getCanvas();
+        const touchOptions = {touches: [{target: canvas, clientX: 0.5, clientY: 0.5}]};
+
+        simulate.touchstart(canvas, touchOptions);
+        simulate.touchend(canvas);
+        simulate.touchstart(canvas, touchOptions);
+        map._renderTaskQueue.run();
+        map._renderTaskQueue.run();
+        expect(zoom).not.toHaveBeenCalled();
+
+        simulate.touchcancel(canvas);
+        simulate.touchend(canvas);
+        map._renderTaskQueue.run();
+        expect(zoom).not.toHaveBeenCalled();
+
+        simulate.touchstart(canvas, touchOptions);
+        simulate.touchend(canvas);
+        simulate.touchstart(canvas, touchOptions);
+        map._renderTaskQueue.run();
+        expect(zoom).not.toHaveBeenCalled();
+
+        simulate.touchend(canvas);
+        map._renderTaskQueue.run();
+
+        expect(zoom).toHaveBeenCalled();
+
+    });
+
+    test('DoubleClickZoomHandler does not zoom on double tap if second touchend is >300ms after first touchstart', async () => {
+        const map = createMap();
+
+        const zoom = jest.fn();
+        map.on('zoom', zoom);
+
+        const canvas = map.getCanvas();
+
+        simulate.touchstart(canvas);
+        simulate.touchend(canvas);
+        simulate.touchstart(canvas);
+        await sleep(300);
+        simulate.touchend(canvas);
+        map._renderTaskQueue.run();
+        expect(zoom).not.toHaveBeenCalled();
+    });
+});