leaflet-rotate 0.4.0 → 0.5.0

package/src/map/handler/ContainerMutation.js

@@ -1,7 +1,10 @@
 /**
- * Triggers `invalidateResize` when the map's DOM container mutates.
+ * Calls `invalidateSize()` when the map container's inline style changes.
  * 
  * @typedef L.Map.ContainerMutation
+ * @property {boolean} [trackContainerMutation=false] Observe inline style changes on the map container.
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 /**
@@ -19,6 +22,8 @@ L.Map.mergeOptions({
      *
      * @type {Boolean}
      * 
+     * @since leaflet-rotate (v0.1.0)
+     * 
      * @see https://developer.mozilla.org/docs/Web/API/MutationObserver
      */
     trackContainerMutation: false
@@ -27,6 +32,11 @@ L.Map.mergeOptions({
 
 L.Map.ContainerMutation = L.Handler.extend({
 
+    /**
+     * Start observing the map container's style attribute.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     addHooks() {
         // if (!L.Browser.mutation) { return; }
         if (!this._observer) {
@@ -41,6 +51,11 @@ L.Map.ContainerMutation = L.Handler.extend({
         });
     },
 
+    /**
+     * Stop observing container mutations.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     removeHooks() {
         // if (!L.Browser.mutation) { return; }
         this._observer.disconnect();
@@ -52,5 +67,7 @@ L.Map.ContainerMutation = L.Handler.extend({
  * Add Container mutation handler to L.Map (disabled unless `trackContainerMutation` is set).
  * 
  * @property {L.Map.ContainerMutation} trackContainerMutation
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 L.Map.addInitHook('addHandler', 'trackContainerMutation', L.Map.ContainerMutation);

package/src/map/handler/ShiftKeyRotate.js

@@ -1,55 +1,195 @@
 
 /**
- * Rotates the map on shift key + mousewheel scrolling (desktop).
+ * Handles Shift+wheel bearing changes and Ctrl+drag bearing/pitch changes.
  * 
  * @typedef L.Map.ShiftKeyRotate
+ * @property {boolean} [shiftKeyRotate=true] Enable Shift+wheel bearing rotation.
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 L.Map.mergeOptions({
 
     /**
-     * Whether the map can be rotated with shift + wheel scroll
+     * Whether Shift+wheel changes the map bearing.
+     * 
      * @type {Boolean}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     shiftKeyRotate: true,
 
+    /**
+     * Whether Ctrl+drag changes bearing and pitch.
+     * 
+     * @type {Boolean}
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    pitchDrag: true,
+
 });
 
 L.Map.ShiftKeyRotate = L.Handler.extend({
 
+    /**
+     * @param {L.Map} map Map controlled by this handler.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
+    initialize(map) {
+        this._map = map;
+        this._onMouseDownBound = this._onMouseDown.bind(this);
+        this._onMouseMoveBound = this._onMouseMove.bind(this);
+        this._onMouseUpBound = this._onMouseUp.bind(this);
+    },
+
+    /**
+     * Attach enabled wheel and pointer/mouse gesture listeners.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     addHooks() {
-        L.DomEvent.on(this._map._container, "wheel", this._handleShiftScroll, this);
-        // this._map.shiftKeyRotate.enable();
-        this._map.shiftKeyRotate.rotate = true;
+        if (this._map.options.shiftKeyRotate) {
+            L.DomEvent.on(this._map._container, "wheel", this._handleShiftScroll, this);
+        }
+        if (this._map.options.pitchDrag) {
+            this.addPitchHooks();
+        }
     },
 
+    /**
+     * Detach gesture listeners and cancel any active drag.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     removeHooks() {
         L.DomEvent.off(this._map._container, "wheel", this._handleShiftScroll, this);
-        this._map.shiftKeyRotate.rotate = false;
+        this.removePitchHooks();
+    },
+
+    /**
+     * Listen for the start of Ctrl+drag pitch gestures.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    addPitchHooks() {
+        if (this._pitchHooksAdded) { return; }
+        this._pitchEvents = L.version.startsWith('2.')
+            ? ['pointerdown', 'pointermove', 'pointerup pointercancel']
+            : ['mousedown', 'mousemove', 'mouseup'];
+        this._map._container.addEventListener(this._pitchEvents[0], this._onMouseDownBound, true);
+        this._pitchHooksAdded = true;
+    },
+
+    /**
+     * Stop listening for pitch gestures and remove active document listeners.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    removePitchHooks() {
+        if (!this._pitchHooksAdded) { return; }
+        this._map._container.removeEventListener(this._pitchEvents[0], this._onMouseDownBound, true);
+        this._onMouseUp();
+        delete this._pitchEvents;
+        this._pitchHooksAdded = false;
     },
 
+    /**
+     * Rotate the map in fixed increments while Shift is held during wheel input.
+     * 
+     * @param {WheelEvent} e Wheel event from the map container.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _handleShiftScroll(e) {
         if (e.shiftKey) {
             e.preventDefault();
             this._map.scrollWheelZoom.disable();
-            this._map.setBearing((this._map._bearing * (180 / Math.PI)) + Math.sign(e.deltaY) * 5);
+            this._map.setBearing(this._map.getBearing() + Math.sign(e.deltaY) * 5);
         } else {
             this._map.scrollWheelZoom.enable();
         }
     },
 
+    /**
+     * Start Ctrl+drag and capture subsequent movement outside the map.
+     * 
+     * @param {MouseEvent|PointerEvent} e Gesture start event.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    _onMouseDown(e) {
+        if (!this._map._rotate || !this._map.options.pitchDrag || !e.ctrlKey || e.button !== 0) { return; }
+
+        const scrollWheelZoom = this._map.scrollWheelZoom;
+        if (scrollWheelZoom && scrollWheelZoom._timer) {
+            clearTimeout(scrollWheelZoom._timer);
+            scrollWheelZoom._timer = null;
+            scrollWheelZoom._delta = 0;
+            scrollWheelZoom._startTime = null;
+        }
+
+        e.preventDefault();
+        e.stopPropagation();
+        e.stopImmediatePropagation();
+        this._lastX = e.clientX;
+        this._lastY = e.clientY;
+        document.addEventListener(this._pitchEvents[1], this._onMouseMoveBound);
+        for (const event of this._pitchEvents[2].split(' ')) {
+            document.addEventListener(event, this._onMouseUpBound);
+        }
+    },
+
+    /**
+     * Apply pointer movement to pitch (vertical) and bearing (horizontal).
+     * 
+     * @param {MouseEvent|PointerEvent} e Gesture movement event.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    _onMouseMove(e) {
+        this._map._setPitchAndBearing(
+            this._map.getPitch() + (this._lastY - e.clientY) * 0.5,
+            this._map.getBearing() + (e.clientX - this._lastX) * 0.8
+        );
+        this._lastX = e.clientX;
+        this._lastY = e.clientY;
+        e.preventDefault();
+    },
+
+    /**
+     * End Ctrl+drag and clear document-level listeners.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    _onMouseUp() {
+        if (!this._pitchEvents) { return; }
+        document.removeEventListener(this._pitchEvents[1], this._onMouseMoveBound);
+        for (const event of this._pitchEvents[2].split(' ')) {
+            document.removeEventListener(event, this._onMouseUpBound);
+        }
+        delete this._lastX;
+        delete this._lastY;
+    },
+
 });
 
 /**
- * Add ShiftKey handler to L.Map (enabled unless `shiftKeyRotate` is unset).
+ * Create the handler when either desktop rotation gesture is enabled.
  * 
- * @property {L.Map.ShiftKeyRotate} shiftKeyRotate
+ * @since leaflet-rotate (v0.1.0)
  */
-L.Map.addInitHook('addHandler', 'shiftKeyRotate', L.Map.ShiftKeyRotate);
-
-// decrease `scrollWheelZoom` handler priority over `shiftKeyRotate` handler
 L.Map.addInitHook(function() {
-    if (this.scrollWheelZoom.enabled() && this.shiftKeyRotate.enabled()) {
+    if (this.options.shiftKeyRotate) {
+        this.shiftKeyRotate = new L.Map.ShiftKeyRotate(this);
+        this.shiftKeyRotate.enable();
+    } else if (this.options.pitchDrag) {
+        this.shiftKeyRotate = new L.Map.ShiftKeyRotate(this);
+        this.shiftKeyRotate.addPitchHooks();
+        this.on('unload', this.shiftKeyRotate.removePitchHooks, this.shiftKeyRotate);
+    }
+    if (this.scrollWheelZoom.enabled() && this.options.shiftKeyRotate) {
         this.scrollWheelZoom.disable();
         this.scrollWheelZoom.enable();
     }

package/src/map/handler/TouchGestures.js

@@ -1,12 +1,27 @@
 /**
- * TouchGestures is both TouchZoom plus TouchRotate
+ * Shared implementation for two-finger pinch zoom and map rotation.
  * 
  * @see https://github.com/fnicollet/Leaflet/commit/a77af51a6b10f308d1b9a16552091d1d0aee8834
  * @see https://github.com/Leaflet/Leaflet/blob/v1.9.3/src/map/handler/Map.TouchZoom.js
  * 
  * @typedef L.Map.TouchGestures
+ * @property {boolean} [bounceAtZoomLimits] Whether pinch zoom may temporarily exceed zoom limits.
+ * @property {boolean} zoom Whether pinch zoom is enabled.
+ * @property {boolean} rotate Whether touch rotation is enabled.
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
+/**
+ * Convert a touch's client coordinates to coordinates relative to the map container.
+ * 
+ * @param {L.Map} map
+ * @param {Touch} touch
+ * 
+ * @returns {L.Point}
+ * 
+ * @since leaflet-rotate (v0.1.0)
+ */
 function touchToContainerPoint(map, touch) {
     const container = map.getContainer(),
         rect = container.getBoundingClientRect();
@@ -20,11 +35,11 @@ function touchToContainerPoint(map, touch) {
 L.Map.mergeOptions({
 
     /**
-     * Set it to false if you don't want the map to
-     * zoom beyond min/max zoom and then bounce back
-     * when pinch-zooming.
+     * Whether pinch zoom may temporarily exceed min/max zoom and bounce back.
      * 
      * @type {Boolean}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     bounceAtZoomLimits: true,
 
@@ -32,20 +47,44 @@ L.Map.mergeOptions({
 
 L.Map.TouchGestures = L.Handler.extend({
 
+    /**
+     * Initialize the shared handler from the map's touch zoom/rotation options.
+     * 
+     * @param {L.Map} map Map whose touch gestures are handled.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     initialize(map) {
         this._map = map;
         this.rotate = !!this._map.options.touchRotate;
         this.zoom = !!this._map.options.touchZoom;
     },
 
+    /**
+     * Listen for the start of two-finger gestures on the map container.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     addHooks() {
         L.DomEvent.on(this._map._container, 'touchstart', this._onTouchStart, this);
     },
 
+    /**
+     * Remove the touch-start listener.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     removeHooks() {
         L.DomEvent.off(this._map._container, 'touchstart', this._onTouchStart, this);
     },
 
+    /**
+     * Record initial touch points and start tracking a two-finger gesture.
+     * 
+     * @param {TouchEvent} e Touch-start event.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _onTouchStart(e) {
         const map = this._map;
 
@@ -89,6 +128,13 @@ L.Map.TouchGestures = L.Handler.extend({
         L.DomEvent.preventDefault(e);
     },
 
+    /**
+     * Update bearing and/or zoom while the two touch points move.
+     * 
+     * @param {TouchEvent} e Touch-move event.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _onTouchMove(e) {
         if (!e.touches || e.touches.length !== 2 || !(this._zooming || this._rotating)) { return; }
 
@@ -133,9 +179,12 @@ L.Map.TouchGestures = L.Handler.extend({
                 delta = p1._add(p2)._divideBy(2)._subtract(this._centerPoint);
                 if (scale === 1 && delta.x === 0 && delta.y === 0) { return; }
 
-                const alpha = -map.getBearing() * (Math.PI / 180);
+                const mapDelta = map._pitch
+                    ? map.containerPointToLayerPoint(this._centerPoint.add(delta))
+                        .subtract(map.containerPointToLayerPoint(this._centerPoint))
+                    : delta.rotate(-map.getBearing() * (Math.PI / 180));
 
-                this._center = map.unproject(map.project(this._pinchStartLatLng).subtract(delta.rotate(alpha)));
+                this._center = map.unproject(map.project(this._pinchStartLatLng).subtract(mapDelta));
             }
 
         }
@@ -159,6 +208,11 @@ L.Map.TouchGestures = L.Handler.extend({
         L.DomEvent.preventDefault(e);
     },
 
+    /**
+     * Finish the gesture, settle the zoom and remove document listeners.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _onTouchEnd() {
         if (!this._moved || !(this._zooming || this._rotating)) {
             this._zooming = false;
@@ -184,8 +238,10 @@ L.Map.TouchGestures = L.Handler.extend({
 });
 
 /**
- * Add Touch Gestures handler (enabled unless `touchGestures` is unset).
+ * Add the shared touch gesture handler to the map.
  * 
  * @property {L.Map.TouchGestures} touchGestures
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 L.Map.addInitHook('addHandler', 'touchGestures', L.Map.TouchGestures);

package/src/map/handler/TouchRotate.js

@@ -1,7 +1,10 @@
 /**
- * Rotates the map on two-finger (touch devices).
+ * Enables two-finger rotation through the shared touch-gesture handler.
  * 
  * @typedef L.Map.TouchRotate
+ * @property {boolean} [touchRotate=false] Enable two-finger map rotation.
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 L.Map.mergeOptions({
@@ -10,6 +13,8 @@ L.Map.mergeOptions({
      * Whether the map can be rotated with a two-finger rotation gesture
      * 
      * @type {Boolean}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     touchRotate: false,
 
@@ -17,11 +22,21 @@ L.Map.mergeOptions({
 
 L.Map.TouchRotate = L.Handler.extend({
 
+    /**
+     * Enable rotation handling in the map's shared touch gesture handler.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     addHooks() {
         this._map.touchGestures.enable();
         this._map.touchGestures.rotate = true;
     },
 
+    /**
+     * Disable rotation handling without affecting pinch zoom.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     removeHooks() {
         this._map.touchGestures.rotate = false;
     },
@@ -32,5 +47,7 @@ L.Map.TouchRotate = L.Handler.extend({
  * Add Touch Rotate handler (disabled unless `touchGestures` is set).
  * 
  * @property {L.Map.TouchGestures} touchGestures
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 L.Map.addInitHook('addHandler', 'touchRotate', L.Map.TouchRotate);

package/src/map/handler/TouchZoom.js

@@ -1,9 +1,13 @@
 /**
- * Adds pinch zoom rotation on mobile browsers
+ * Adds pinch zoom support through the shared touch-gesture handler.
  * 
  * @see https://github.com/Leaflet/Leaflet/blob/v1.9.3/src/map/handler/Map.TouchZoom.js
  * 
  * @external L.Map.TouchZoom
+ * @property {boolean|string} [touchZoom=L.Browser.touch] Enable pinch zoom; `'center'` zooms around the view center.
+ * @property {boolean} [bounceAtZoomLimits=false] Allow pinch zoom to exceed zoom limits before settling.
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 L.Map.mergeOptions({
@@ -16,6 +20,8 @@ L.Map.mergeOptions({
      * for touch-capable web browsers.
      * 
      * @type {(Boolean|String)}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     touchZoom: L.Browser.touch,
 
@@ -27,6 +33,8 @@ L.Map.mergeOptions({
      * when pinch-zooming.
      * 
      * @type {Boolean}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     bounceAtZoomLimits: false,
 
@@ -34,12 +42,22 @@ L.Map.mergeOptions({
 
 L.Map.TouchZoom = L.Handler.extend({
 
+    /**
+     * Enable pinch zoom handling and mark the shared touch handler as active.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     addHooks() {
         this._map._container.classList.add('leaflet-touch-zoom');
         this._map.touchGestures.enable();
         this._map.touchGestures.zoom = true;
     },
 
+    /**
+     * Disable pinch zoom handling while preserving touch rotation state.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     removeHooks() {
         this._map._container.classList.remove('leaflet-touch-zoom');
         this._map.touchGestures.zoom = false;
@@ -51,5 +69,7 @@ L.Map.TouchZoom = L.Handler.extend({
  * Add Touch Zoom handler (disabled unless `L.Browser.touch` is set).
  * 
  * @property {L.Map.TouchGestures} touchGestures
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 L.Map.addInitHook('addHandler', 'touchZoom', L.Map.TouchZoom);

package/test/features/rotation.feature

@@ -21,6 +21,36 @@ Feature: Rotating a Leaflet map
     When I animate the bearing to 90 degrees
     Then the bearing reaches 90 degrees gradually
 
+  @issue-72
+  Scenario: Pitch projects and reverses map coordinates
+    When I set the map pitch to 45 degrees
+    Then map coordinates stay consistent with the pitched view
+
+  @issue-72
+  Scenario: Ctrl-drag changes pitch and bearing without panning
+    When I change pitch and bearing with Ctrl-drag
+    Then pitch and bearing change without moving the map pane
+
+  @issue-72
+  Scenario: Pitched vector layers stay aligned while panning
+    When I drag the pitched map
+    Then vector layers stay aligned with their map coordinates
+
+  @issue-72
+  Scenario: Vector layers stay aligned after off-center zoom and rotation
+    When I zoom off-center then rotate the map
+    Then vector layers stay aligned with their map coordinates
+
+  @issue-72
+  Scenario: Ctrl-drag after panning keeps the map center stable
+    When I pan the map then Ctrl-drag
+    Then the map center stays stable during Ctrl-drag
+
+  @issue-72
+  Scenario: Ctrl-drag cancels a pending wheel zoom
+    When I Ctrl-drag while a wheel zoom is pending
+    Then the pending wheel zoom does not move the map
+
   @issue-25
   Scenario: Fit bounds zoom is stable
     When I fit the same bounds twice

package/test/index.html

@@ -83,7 +83,8 @@
 				: 'https://unpkg.com/leaflet@1.9.4/dist/leaflet.css';
 
 			if (version === '2') {
-				globalThis.L = await import('https://unpkg.com/leaflet@2.0.0-alpha.1/dist/leaflet.js');
+				await loadScript('https://unpkg.com/leaflet@2.0.0-alpha.1/dist/leaflet-global-src.js');
+				globalThis.L = globalThis.leaflet;
 			} else {
 				await loadScript('https://unpkg.com/leaflet@1.9.4/dist/leaflet-src.js');
 			}