maplibre-gl 6.2.0 → 6.4.0

package/src/ui/marker.ts

@@ -18,6 +18,19 @@ import type {PointLike} from './camera.ts';
  */
 export type Alignment = 'map' | 'viewport' | 'auto';
 
+/**
+ * Screen-pixel deltas applied when a focused draggable marker is moved with the arrow keys.
+ */
+const ARROW_KEY_DELTAS: Partial<Record<KeyboardEvent['key'], [number, number]>> = {
+    ArrowLeft: [-1, 0],
+    ArrowRight: [1, 0],
+    ArrowUp: [0, -1],
+    ArrowDown: [0, 1]
+};
+
+const KEYBOARD_DRAG_SMALL_STEP = 1;
+const KEYBOARD_DRAG_LARGE_STEP = 10;
+
 /**
  * The {@link Marker} options object
  */
@@ -52,6 +65,10 @@ export type MarkerOptions = {
     scale?: number;
     /**
      * A boolean indicating whether or not a marker is able to be dragged to a new position on the map.
+     * A draggable default marker also becomes keyboard focusable and, while focused, moves by
+     * 1 screen pixel per arrow-key press (10 with Shift), firing the same `dragstart`/`drag`/`dragend`
+     * events as pointer dragging. Markers with a custom `element` keep their focusability and
+     * keyboard behavior application-owned.
      * @defaultValue false
      */
     draggable?: boolean;
@@ -222,12 +239,13 @@ export class Marker extends Evented<MarkerEventType> {
     _rotation: number;
     _pitchAlignment: Alignment;
     _rotationAlignment: Alignment;
-    _originalTabIndex: string; // original tabindex of _element
     _opacity: string;
     _opacityWhenCovered: string;
     _opacityTimeout: ReturnType<typeof setTimeout>;
     _subpixelPositioning: boolean;
     _roleManaged: boolean;
+    _tabIndexManaged: boolean;
+    _keyboardDragActive: boolean;
 
     /**
      * @param options - the options
@@ -243,6 +261,8 @@ export class Marker extends Evented<MarkerEventType> {
         this._subpixelPositioning = options?.subpixelPositioning || false;
         this._isDragging = false;
         this._roleManaged = false;
+        this._tabIndexManaged = false;
+        this._keyboardDragActive = false;
         this._state = 'inactive';
         this._rotation = options?.rotation || 0;
         this._rotationAlignment = options?.rotationAlignment || 'auto';
@@ -447,6 +467,12 @@ export class Marker extends Evented<MarkerEventType> {
             delete this._map;
         }
         this._element.removeEventListener('click', this._onClick);
+        this._element.removeEventListener('keydown', this._onKeyDown);
+        this._element.removeEventListener('keyup', this._onKeyUp);
+        this._element.removeEventListener('blur', this._onBlur);
+        this._element.removeEventListener('keypress', this._onKeyPress);
+        // Drop any in-flight keyboard drag silently, like a pointer drag interrupted by remove().
+        this._keyboardDragActive = false;
         this._element.remove();
         if (this._popup) this._popup.remove();
         return this;
@@ -520,10 +546,6 @@ export class Marker extends Evented<MarkerEventType> {
             this._popup.remove();
             this._popup = null;
             this._element.removeEventListener('keypress', this._onKeyPress);
-
-            if (!this._originalTabIndex) {
-                this._element.removeAttribute('tabindex');
-            }
         }
 
         if (popup) {
@@ -544,13 +566,10 @@ export class Marker extends Evented<MarkerEventType> {
             }
             this._popup = popup;
 
-            this._originalTabIndex = this._element.getAttribute('tabindex');
-            if (!this._originalTabIndex) {
-                this._element.setAttribute('tabindex', '0');
-            }
             this._element.addEventListener('keypress', this._onKeyPress);
         }
 
+        this._updateTabIndex();
         this._updateAccessibilityRole();
         return this;
     }
@@ -581,6 +600,57 @@ export class Marker extends Evented<MarkerEventType> {
         }
     };
 
+    /**
+     * Move a focused draggable default marker with the arrow keys
+     * (1 screen pixel per keydown; 10 with Shift).
+     * Mirrors the pointer drag gesture: the position updates before `dragstart`
+     * fires on the first movement, every movement fires `drag`, and releasing
+     * the arrow key (or losing focus) fires `dragend`. Holding a key down
+     * produces repeated `drag` events within a single gesture.
+     */
+    _onKeyDown = (e: KeyboardEvent): void => {
+        // Custom marker elements own their keyboard behavior (#7790).
+        if (!this._defaultMarker || !this._draggable || !this._map || !this._lngLat) return;
+        // Leave keys originating from elements nested inside the marker to the application.
+        if (e.composedPath()[0] !== this._element) return;
+        // Leave Alt/Ctrl/Meta shortcuts to the browser and the application.
+        if (e.altKey || e.ctrlKey || e.metaKey) return;
+
+        const delta = ARROW_KEY_DELTAS[e.key];
+        if (!delta) return;
+
+        e.preventDefault();
+        // The marker element lives in the canvas container, so without this the
+        // map's KeyboardHandler would also pan (or rotate/pitch with Shift) the camera.
+        e.stopPropagation();
+
+        const step = e.shiftKey ? KEYBOARD_DRAG_LARGE_STEP : KEYBOARD_DRAG_SMALL_STEP;
+        const pos = this._map.project(this._lngLat);
+        this.setLngLat(this._map.unproject(new Point(pos.x + delta[0] * step, pos.y + delta[1] * step)));
+
+        if (!this._keyboardDragActive) {
+            this._keyboardDragActive = true;
+            this.fire(new MarkerDragEvent('dragstart'));
+        }
+        this.fire(new MarkerDragEvent('drag'));
+    };
+
+    _onKeyUp = (e: KeyboardEvent): void => {
+        if (!ARROW_KEY_DELTAS[e.key]) return;
+        this._endKeyboardDrag();
+    };
+
+    _onBlur = (): void => {
+        this._endKeyboardDrag();
+    };
+
+    _endKeyboardDrag(): void {
+        if (this._keyboardDragActive) {
+            this._keyboardDragActive = false;
+            this.fire(new MarkerDragEvent('dragend'));
+        }
+    }
+
     _onMapClick = (e: MapMouseEvent): void => {
         const targetElement = e.originalEvent.target;
         const element = this._element;
@@ -851,7 +921,10 @@ export class Marker extends Evented<MarkerEventType> {
     };
 
     /**
-     * Sets the `draggable` property and functionality of the marker
+     * Sets the `draggable` property and functionality of the marker.
+     * A draggable default marker is also keyboard focusable and movable with the
+     * arrow keys (see {@link MarkerOptions.draggable}); custom marker elements keep
+     * their focusability and keyboard behavior application-owned.
      * @param shouldBeDraggable - Turns drag functionality on/off
      */
     setDraggable(shouldBeDraggable?: boolean): this {
@@ -870,6 +943,20 @@ export class Marker extends Evented<MarkerEventType> {
             }
         }
 
+        if (this._defaultMarker) {
+            if (this._draggable) {
+                this._element.addEventListener('keydown', this._onKeyDown);
+                this._element.addEventListener('keyup', this._onKeyUp);
+                this._element.addEventListener('blur', this._onBlur);
+            } else {
+                this._element.removeEventListener('keydown', this._onKeyDown);
+                this._element.removeEventListener('keyup', this._onKeyUp);
+                this._element.removeEventListener('blur', this._onBlur);
+                this._endKeyboardDrag();
+            }
+        }
+
+        this._updateTabIndex();
         this._updateAccessibilityRole();
         return this;
     }
@@ -882,6 +969,29 @@ export class Marker extends Evented<MarkerEventType> {
         return this._draggable;
     }
 
+    /**
+     * Keep the marker element focusable while it has built-in keyboard behavior.
+     * A popup makes any marker element interactive; dragging only manages
+     * focusability for the default marker so custom elements stay
+     * application-owned (#7790). A tabindex supplied by the application is
+     * never added, changed, or removed here.
+     */
+    _updateTabIndex(): void {
+        const needsTabIndex = !!this._popup || (this._defaultMarker && this._draggable);
+        if (needsTabIndex) {
+            if (!this._element.hasAttribute('tabindex')) {
+                this._element.setAttribute('tabindex', '0');
+                this._tabIndexManaged = true;
+            }
+        } else if (this._tabIndexManaged) {
+            // Only remove the value we set; the application may have overridden it since.
+            if (this._element.getAttribute('tabindex') === '0') {
+                this._element.removeAttribute('tabindex');
+            }
+            this._tabIndexManaged = false;
+        }
+    }
+
     /**
      * Keep the default marker role aligned with interactivity.
      * Default markers need a role because `aria-label` is set in {@link Marker.addTo}.

package/src/ui/popup.test.ts

@@ -32,7 +32,7 @@ describe('popup', () => {
             .addTo(map);
 
         expect(popup.isOpen()).toBeTruthy();
-        expect(popup.getElement().classList.contains('maplibregl-popup')).toBeTruthy();
+        expect(popup.getElement().classList).toContain('maplibregl-popup');
     });
 
     test('Popup.addTo adds a .maplibregl-popup element', () => {
@@ -258,10 +258,10 @@ describe('popup', () => {
     test('Popup provides LngLat accessors', () => {
         expect(new Popup().getLngLat()).toBeUndefined();
 
-        expect(new Popup().setLngLat([1, 2]).getLngLat() instanceof LngLat).toBeTruthy();
+        expect(new Popup().setLngLat([1, 2]).getLngLat()).toBeInstanceOf(LngLat);
         expect(new Popup().setLngLat([1, 2]).getLngLat()).toEqual(new LngLat(1, 2));
 
-        expect(new Popup().setLngLat(new LngLat(1, 2)).getLngLat() instanceof LngLat).toBeTruthy();
+        expect(new Popup().setLngLat(new LngLat(1, 2)).getLngLat()).toBeInstanceOf(LngLat);
         expect(new Popup().setLngLat(new LngLat(1, 2)).getLngLat()).toEqual(new LngLat(1, 2));
 
     });
@@ -382,7 +382,7 @@ describe('popup', () => {
             .setText('Test')
             .addTo(map);
 
-        expect(popup.getElement().classList.contains('maplibregl-popup-anchor-top-left')).toBeTruthy();
+        expect(popup.getElement().classList).toContain('maplibregl-popup-anchor-top-left');
     });
 
     const cases =  [
@@ -413,7 +413,7 @@ describe('popup', () => {
             vi.spyOn(map, 'project').mockReturnValue(point);
             popup.setLngLat([0, 0]);
 
-            expect(popup.getElement().classList.contains(`maplibregl-popup-anchor-${anchor}`)).toBeTruthy();
+            expect(popup.getElement().classList).toContain(`maplibregl-popup-anchor-${anchor}`);
         });
 
     const transformCases = cases.map(([anchor, _point, transform]) => [anchor, transform] as const);
@@ -449,7 +449,7 @@ describe('popup', () => {
         vi.spyOn(map, 'project').mockReturnValue(point);
         popup.setLngLat([0, 0]);
 
-        expect(popup.getElement().classList.contains('maplibregl-popup-anchor-top')).toBeTruthy();
+        expect(popup.getElement().classList).toContain('maplibregl-popup-anchor-top');
     });
 
     test('Popup is offset via a PointLike offset option', () => {
@@ -563,22 +563,22 @@ describe('popup', () => {
             .addTo(map);
 
         const popupContainer = popup.getElement();
-        expect(popupContainer.classList.contains('some')).toBeTruthy();
-        expect(popupContainer.classList.contains('classes')).toBeTruthy();
+        expect(popupContainer.classList).toContain('some');
+        expect(popupContainer.classList).toContain('classes');
 
         const addClassNameMethodPopupInstance = popup.addClassName('addedClass');
-        expect(popupContainer.classList.contains('addedClass')).toBeTruthy();
+        expect(popupContainer.classList).toContain('addedClass');
         expect(addClassNameMethodPopupInstance).toBeInstanceOf(Popup);
 
         const removeClassNameMethodPopupInstance = popup.removeClassName('addedClass');
-        expect(!popupContainer.classList.contains('addedClass')).toBeTruthy();
+        expect(popupContainer.classList).not.toContain('addedClass');
         expect(removeClassNameMethodPopupInstance).toBeInstanceOf(Popup);
 
         popup.toggleClassName('toggle');
-        expect(popupContainer.classList.contains('toggle')).toBeTruthy();
+        expect(popupContainer.classList).toContain('toggle');
 
         popup.toggleClassName('toggle');
-        expect(!popupContainer.classList.contains('toggle')).toBeTruthy();
+        expect(popupContainer.classList).not.toContain('toggle');
 
         expect(() => popup.addClassName('should throw exception')).toThrow(window.DOMException);
         expect(() => popup.removeClassName('should throw exception')).toThrow(window.DOMException);
@@ -1063,8 +1063,8 @@ describe('popup', () => {
                 .trackPointer()
                 .addTo(map);
 
-            expect(popup.getElement().classList.contains('maplibregl-popup-track-pointer')).toBeTruthy();
-            expect(map._canvasContainer.classList.contains('maplibregl-track-pointer')).toBeTruthy();
+            expect(popup.getElement().classList).toContain('maplibregl-popup-track-pointer');
+            expect(map._canvasContainer.classList).toContain('maplibregl-track-pointer');
 
             popup.remove();
         });

package/src/util/evented.test.ts

@@ -1,8 +1,13 @@
 import {describe, test, expect, vi} from 'vitest';
 import {Event, Evented} from './evented.ts';
 
+class StubbedEvent extends Event<'a' | 'b'> {
+    foo?: string;
+    foz?: string;
+}
+
 // `Evented` is abstract, so use a minimal concrete subclass to exercise its behavior.
-class StubbedEvented extends Evented {}
+class StubbedEvented extends Evented<Record<StubbedEvent['type'], StubbedEvent>> {}
 
 describe('Evented', () => {
 
@@ -10,8 +15,8 @@ describe('Evented', () => {
         const evented = new StubbedEvented();
         const listener = vi.fn();
         evented.on('a', listener);
-        evented.fire(new Event('a'));
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
+        evented.fire(new StubbedEvent('a'));
         expect(listener).toHaveBeenCalledTimes(2);
     });
 
@@ -19,8 +24,8 @@ describe('Evented', () => {
         const evented = new StubbedEvented();
         const listener = vi.fn();
         evented.once('a', listener);
-        evented.fire(new Event('a'));
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
+        evented.fire(new StubbedEvent('a'));
         expect(listener).toHaveBeenCalledTimes(1);
         expect(evented.listens('a')).toBeFalsy();
     });
@@ -29,17 +34,17 @@ describe('Evented', () => {
         const evented = new StubbedEvented();
         const listener = vi.fn();
         const subscription = evented.on('a', listener);
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
         subscription.unsubscribe();
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
         expect(listener).toHaveBeenCalledTimes(1);
     });
 
     test('returns a promise when no listener is provided to "once" method', async () => {
         const evented = new StubbedEvented();
         const promise = evented.once('a');
-        evented.fire(new Event('a'));
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
+        evented.fire(new StubbedEvent('a'));
         await promise;
         expect(evented.listens('a')).toBeFalsy();
 
@@ -50,7 +55,7 @@ describe('Evented', () => {
         evented.on('a', (data) => {
             expect(data.foo).toBe('bar');
         });
-        evented.fire(new Event('a', {foo: 'bar'}));
+        evented.fire(new StubbedEvent('a', {foo: 'bar'}));
 
     });
 
@@ -59,7 +64,7 @@ describe('Evented', () => {
         evented.on('a', (data) => {
             expect(data.target).toBe(evented);
         });
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
 
     });
 
@@ -68,7 +73,7 @@ describe('Evented', () => {
         evented.on('a', (data) => {
             expect(data.type).toBe('a');
         });
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
 
     });
 
@@ -77,7 +82,7 @@ describe('Evented', () => {
         const listener = vi.fn();
         evented.on('a', listener);
         evented.off('a', listener);
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
         expect(listener).not.toHaveBeenCalled();
     });
 
@@ -86,7 +91,7 @@ describe('Evented', () => {
         const listener = vi.fn();
         evented.once('a', listener);
         evented.off('a', listener);
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
         expect(listener).not.toHaveBeenCalled();
     });
 
@@ -95,9 +100,9 @@ describe('Evented', () => {
         const listener = vi.fn();
         evented.once('a', () => {
             listener();
-            evented.fire(new Event('a'));
+            evented.fire(new StubbedEvent('a'));
         });
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
         expect(listener).toHaveBeenCalledTimes(1);
     });
 
@@ -124,7 +129,7 @@ describe('Evented', () => {
         evented.on('a', () => {
             evented.on('a', nestedListener);
         });
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
 
         expect(nestedListener).not.toHaveBeenCalled();
     });
@@ -147,7 +152,7 @@ describe('Evented', () => {
         evented.on('a', listenerA);
         evented.on('a', listenerB);
         evented.on('a', listenerA);
-        evented.fire(new Event('a'));
+        evented.fire(new StubbedEvent('a'));
         expect(listenerA).toHaveBeenCalledTimes(1);
         expect(order).toEqual(['A', 'B']);
 
@@ -162,8 +167,8 @@ describe('evented parents', () => {
         const eventedSink = new StubbedEvented();
         eventedSource.setEventedParent(eventedSink);
         eventedSink.on('a', listener);
-        eventedSource.fire(new Event('a'));
-        eventedSource.fire(new Event('a'));
+        eventedSource.fire(new StubbedEvent('a'));
+        eventedSource.fire(new StubbedEvent('a'));
         expect(listener).toHaveBeenCalledTimes(2);
     });
 
@@ -174,7 +179,7 @@ describe('evented parents', () => {
         eventedSink.on('a', (data) => {
             expect(data.foo).toBe('bar');
         });
-        eventedSource.fire(new Event('a', {foo: 'bar'}));
+        eventedSource.fire(new StubbedEvent('a', {foo: 'bar'}));
 
     });
 
@@ -185,7 +190,7 @@ describe('evented parents', () => {
         eventedSink.on('a', (data) => {
             expect(data.foz).toBe('baz');
         });
-        eventedSource.fire(new Event('a', {foo: 'bar'}));
+        eventedSource.fire(new StubbedEvent('a', {foo: 'bar'}));
 
     });
 
@@ -196,7 +201,7 @@ describe('evented parents', () => {
         eventedSink.on('a', (data) => {
             expect(data.foz).toBe('baz');
         });
-        eventedSource.fire(new Event('a', {foo: 'bar'}));
+        eventedSource.fire(new StubbedEvent('a', {foo: 'bar'}));
 
     });
 
@@ -208,7 +213,7 @@ describe('evented parents', () => {
         eventedSink.on('a', (data) => {
             expect(data.target).toBe(eventedSource);
         });
-        eventedSource.fire(new Event('a'));
+        eventedSource.fire(new StubbedEvent('a'));
 
     });
 
@@ -219,7 +224,7 @@ describe('evented parents', () => {
         eventedSink.on('a', listener);
         eventedSource.setEventedParent(eventedSink);
         eventedSource.setEventedParent(null);
-        eventedSource.fire(new Event('a'));
+        eventedSource.fire(new StubbedEvent('a'));
         expect(listener).not.toHaveBeenCalled();
     });
 
@@ -236,11 +241,11 @@ describe('evented parents', () => {
         const eventedSource = new StubbedEvented();
         const eventedParent = new StubbedEvented();
         let i = 0;
-        eventedSource.setEventedParent(eventedParent, () => i++);
+        eventedSource.setEventedParent(eventedParent, () => ({counter: i++}));
         eventedSource.on('a', () => {});
-        eventedSource.fire(new Event('a'));
+        eventedSource.fire(new StubbedEvent('a'));
         expect(i).toBe(1);
-        eventedSource.fire(new Event('a'));
+        eventedSource.fire(new StubbedEvent('a'));
         expect(i).toBe(2);
 
     });