leaflet-rotate 0.4.0 → 0.5.0

package/dist/leaflet-rotate-src.js

@@ -30,11 +30,15 @@ var leafletRotate = (() => {
      * Resets the 3D CSS transform of `el` so it is translated by `offset` pixels,
      * optionally scaled by `scale`, and rotated around `pivot` when `bearing` is set.
      *
-     * @param {HTMLElement} el
-     * @param {L.Point} offset
-     * @param {Number} scale
-     * @param {Number} bearing
-     * @param {L.Point} pivot
+     * @param {HTMLElement} el Element to transform.
+     * @param {L.Point} [offset] Translation in pixels; defaults to the origin.
+     * @param {number} [scale] Optional scale factor.
+     * @param {number} [bearing] Optional rotation in radians.
+     * @param {L.Point} [pivot] Point in pixels around which to rotate.
+     * 
+     * @returns {void}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     setTransform(el, offset, scale, bearing, pivot) {
       let pos = offset || new L.Point(0, 0);
@@ -48,11 +52,15 @@ var leafletRotate = (() => {
      * Sets the position of `el` to `point`, using CSS transforms or top/left positioning
      * depending on browser support, and optionally rotating it around `pivot`.
      *
-     * @param {HTMLElement} el
-     * @param {L.Point} point
-     * @param {Number} bearing
-     * @param {L.Point} pivot
-     * @param {Number} scale
+     * @param {HTMLElement} el Element to position.
+     * @param {L.Point} point Position in pixels.
+     * @param {number} [bearing] Rotation in radians; zero or omitted uses Leaflet positioning.
+     * @param {L.Point} [pivot] Point in pixels around which to rotate.
+     * @param {number} [scale] Optional scale factor.
+     * 
+     * @returns {void}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     setPosition(el, point, bearing, pivot, scale) {
       if (!bearing) {
@@ -64,8 +72,11 @@ var leafletRotate = (() => {
     /**
      * Returns the position assigned to `el`.
      *
-     * @param {HTMLElement} el
-     * @returns {L.Point}
+     * @param {HTMLElement} el Element whose Leaflet position is requested.
+     * 
+     * @returns {L.Point} Stored Leaflet position, or the position measured by Leaflet.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     getPosition(el) {
       return el._leaflet_pos || domUtilProto.getPosition(el);
@@ -88,7 +99,10 @@ var leafletRotate = (() => {
      * ⎡ x' ⎤ = ⎡ cos θ  -sin θ ⎤ ⎡ x ⎤
      * ⎣ y' ⎦   ⎣ sin θ   cos θ ⎦ ⎣ y ⎦
      * 
-     * @param theta must be given in radians.
+     * @param {number} theta Rotation angle in radians, counterclockwise.
+     * @returns {L.Point} Rotated point (or this point when theta is zero).
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     rotate(theta) {
       return this.rotateFrom(theta, new L.Point(0, 0));
@@ -102,10 +116,12 @@ var leafletRotate = (() => {
      * 
      * same as `this.subtract(pivot).rotate(theta).add(pivot)`
      * 
-     * @param {Number} theta 
-     * @param {L.Point} pivot 
+     * @param {number} theta Rotation angle in radians, counterclockwise.
+     * @param {L.Point} pivot Point to rotate around.
      * 
      * @returns {L.Point}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     rotateFrom(theta, pivot) {
       if (!theta) {
@@ -132,17 +148,41 @@ var leafletRotate = (() => {
   var divOverlayProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.DivOverlay.prototype));
   L.DivOverlay.include({
     /**
-     * Update L.Popup and L.Tooltip anchor positions after
-     * the map is moved by calling `map.setBearing(theta)`
+     * Extend overlay event subscriptions to refresh position after map rotation and pitch.
      * 
      * @listens L.Map~rotate
+     * @listens L.Map~pitch
+     *
+     * @returns {Object} Leaflet event map for the overlay.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     getEvents() {
-      return Object.assign(divOverlayProto.getEvents.apply(this, arguments), { rotate: this._updatePosition });
+      const events = Object.assign(divOverlayProto.getEvents.apply(this, arguments), {
+        rotate: this._updatePosition,
+        pitch: this._updatePitchEvents
+      });
+      if (this._map && this._map._pitch) {
+        events.move = this._updatePosition;
+      }
+      return events;
+    },
+    /**
+     * Listen to map movement only while pitch is non-zero.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    _updatePitchEvents() {
+      if (this._map._pitch) {
+        this._map.on("move", this._updatePosition, this);
+      } else {
+        this._map.off("move", this._updatePosition, this);
+      }
     },
     /**
-     * 0. update element anchor point (divOverlayProto v1.9.3)
-     * 1. rotate around anchor point (subtract anchor -> rotate point -> add anchor)
+     * Reposition the overlay after map movement, applying rotation/pitch-aware coordinates.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     _updatePosition() {
       if (!this._map) {
@@ -170,8 +210,11 @@ var leafletRotate = (() => {
   var popupProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.Popup.prototype));
   L.Popup.include({
     /**
-     * 0. update element anchor point (popupProto v1.9.3)
-     * 1. rotate around anchor point (subtract anchor -> rotate point -> add anchor)
+     * Update the popup position during zoom animation and transform it into map-pane coordinates.
+     *
+     * @param {Object} e Zoom animation event.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     _animateZoom(e) {
       popupProto._animateZoom.apply(this, arguments);
@@ -182,9 +225,13 @@ var leafletRotate = (() => {
       }
     },
     /**
-     * Fix for L.popup({ keepInView = true })
+     * Pan the map when a popup with auto-pan enabled would extend beyond the viewport.
      * 
      * @see https://github.com/fnicollet/Leaflet/pull/21
+     *
+     * @fires L.Map#autopanstart
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     _adjustPan() {
       if (!this.options.autoPan || this._map._panAnim && this._map._panAnim._inProgress) {
@@ -222,6 +269,13 @@ var leafletRotate = (() => {
   // src/layer/Tooltip.js
   var tooltipProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.Tooltip.prototype));
   L.Tooltip.include({
+    /**
+     * Reposition the tooltip during zoom animation using transformed map coordinates.
+     *
+     * @param {Object} e Zoom animation event.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _animateZoom(e) {
       if (!this._map._rotate) {
         return tooltipProto._animateZoom.apply(this, arguments);
@@ -230,6 +284,11 @@ var leafletRotate = (() => {
       pos = this._map.rotatedPointToMapPanePoint(pos);
       this._setPosition(pos);
     },
+    /**
+     * Recompute tooltip screen position after map movement.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _updatePosition() {
       if (!this._map._rotate) {
         return tooltipProto._updatePosition.apply(this, arguments);
@@ -243,6 +302,14 @@ var leafletRotate = (() => {
   // src/layer/marker/Icon.js
   var iconProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.Icon.prototype));
   L.Icon.include({
+    /**
+     * Set marker icon dimensions and anchor styles, including the rotation origin.
+     * 
+     * @param {HTMLImageElement} img Icon or shadow element.
+     * @param {string} name Icon style key (`icon` or `shadow`).
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _setIconStyles(img, name) {
       const options = this.options;
       let sizeOption = options[name + "Size"];
@@ -267,27 +334,38 @@ var leafletRotate = (() => {
   var markerProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.Marker.prototype));
   L.Marker.mergeOptions({
     /**
-     * Rotation of this marker in rad
+     * Rotation of the marker icon in radians.
      * 
      * @type {Number}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     rotation: 0,
     /**
-     * Rotate this marker when map rotates
+     * Rotate the marker icon when the map bearing changes.
+     *
+     * Combine with `keepUpright: true` to keep the marker readable while
+     * preserving its line alignment.
      * 
      * @type {Boolean}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     rotateWithView: false,
     /**
-     * Flip a rotated marker when needed to keep it upright
+     * Flip the icon when needed to keep it upright while map-aligned.
      *
      * @type {Boolean}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     keepUpright: false,
     /**
-     * Scale of the marker icon
+     * Optional scale of the marker icon and shadow.
      * 
      * @type {Number}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     scale: void 0
   });
@@ -299,6 +377,13 @@ var leafletRotate = (() => {
     //     }
     //     this._draggable.updateMapBearing(this._marker._map._bearing);
     // },
+    /**
+     * Update a dragged marker's geographic position from its transformed icon position.
+     * 
+     * @param {Object} e Marker drag event with `latlng` and `oldLatLng` fields.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _onDrag(e) {
       const marker = this._marker, rotated_marker = marker.options.rotation || marker.options.rotateWithView, shadow = marker._shadow;
       let iconPos = L.DomUtil.getPosition(marker._icon);
@@ -316,6 +401,13 @@ var leafletRotate = (() => {
       else marker.fire("move", e);
       marker.fire("drag", e);
     },
+    /**
+     * Reposition the marker after a drag ends, then run Leaflet's drag-end logic.
+     * 
+     * @param {Object} e Marker drag-end event.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _onDragEnd(e) {
       if (this._marker._map._rotate) {
         this._marker.update();
@@ -325,14 +417,42 @@ var leafletRotate = (() => {
   };
   L.Marker.include({
     /**
-     * Update L.Marker anchor position after the map
-     * is moved by calling `map.setBearing(theta)`
+     * Extend marker event subscriptions to reposition its icon after bearing or pitch changes.
      * 
      * @listens L.Map~rotate
+     * @listens L.Map~pitch
+     * 
+     * @returns {Object} Leaflet event map for the marker.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     getEvents() {
-      return Object.assign(markerProto.getEvents.apply(this, arguments), { rotate: this.update });
+      const events = Object.assign(markerProto.getEvents.apply(this, arguments), {
+        rotate: this.update,
+        pitch: this._updatePitchEvents
+      });
+      if (this._map && this._map._pitch) {
+        events.move = this.update;
+      }
+      return events;
     },
+    /**
+     * Subscribe to map movement while pitch is active to keep the icon aligned.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    _updatePitchEvents() {
+      if (this._map._pitch) {
+        this._map.on("move", this.update, this);
+      } else {
+        this._map.off("move", this.update, this);
+      }
+    },
+    /**
+     * Install rotation-aware drag callbacks when marker dragging is enabled.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _initInteraction() {
       const ret = markerProto._initInteraction.apply(this, arguments);
       if (this.dragging && this.dragging.enabled() && this._map && this._map._rotate) {
@@ -347,6 +467,13 @@ var leafletRotate = (() => {
       }
       return ret;
     },
+    /**
+     * Position and rotate the marker icon and shadow in map-pane coordinates.
+     * 
+     * @param {L.Point} pos Marker anchor in layer-point coordinates.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _setPos(pos) {
       if (this._map._rotate) {
         pos = this._map.rotatedPointToMapPanePoint(pos);
@@ -377,6 +504,15 @@ var leafletRotate = (() => {
     //     }
     //     this._icon.style.zIndex = Math.round(this._zIndex + offset);
     // },
+    /**
+     * Set the marker icon's rotation and redraw it.
+     * 
+     * @param {number} rotation Angle in radians.
+     * 
+     * @returns {void}
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     setRotation(rotation) {
       this.options.rotation = rotation;
       this.update();
@@ -387,10 +523,13 @@ var leafletRotate = (() => {
   var gridLayerProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.GridLayer.prototype));
   L.GridLayer.include({
     /**
-     * Redraw L.TileLayer bounds after the map is
-     * moved by just calling `map.setBearing(theta)`
+     * Add a throttled tile refresh after map bearing changes.
      * 
      * @listens L.Map~rotate
+     * 
+     * @returns {Object} Leaflet event map for the grid layer.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     getEvents() {
       const events = gridLayerProto.getEvents.apply(this, arguments);
@@ -402,6 +541,15 @@ var leafletRotate = (() => {
       }
       return events;
     },
+    /**
+     * Return tile pixel bounds that cover the rotated viewport.
+     * 
+     * @param {L.LatLng} center View center used to calculate bounds.
+     * 
+     * @returns {L.Bounds} Pixel bounds covered by the layer's tiles.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _getTiledPixelBounds(center) {
       if (!this._map._rotate) {
         return gridLayerProto._getTiledPixelBounds.apply(this, arguments);
@@ -414,21 +562,45 @@ var leafletRotate = (() => {
   var rendererProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.Renderer.prototype));
   var rendererBase = Object.getPrototypeOf(L.Renderer.prototype);
   var rendererGetEvents = rendererProto.getEvents || rendererBase.getEvents;
+  var rendererOnMoveEnd = rendererProto._onMoveEnd || rendererBase._onMoveEnd;
   L.Renderer.include({
     /**
-     * Redraw L.Canvas and L.SVG renderer bounds after the
-     * map is moved by just calling `map.setBearing(theta)`
+     * Subscribe the renderer to map rotation so its visible bounds are recalculated.
      * 
      * @listens L.Map~rotate
+     * 
+     * @returns {Object} Leaflet event map for the renderer.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     getEvents() {
       const events = rendererGetEvents.apply(this, arguments);
-      return L.version.startsWith("2.") ? events : Object.assign(events, { rotate: this._update });
+      return Object.assign(events, { rotate: this._onRotate });
     },
     /**
-     * Fix for `map.flyTo()` when `false === map.options.zoomAnimation`
+     * Reproject vector paths and refresh renderer bounds after bearing changes.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
+    _onRotate() {
+      if (!this._map._rotate) {
+        return;
+      }
+      this._onZoomEnd();
+      if (L.version.startsWith("2.")) {
+        this._onMoveEnd();
+      } else {
+        this._update();
+      }
+    },
+    /**
+     * Add the zoom-animation class needed for correct renderer transforms in Leaflet 1.
+     *
+     * Fixes `map.flyTo()` when `map.options.zoomAnimation` is false.
      * 
      * @see https://github.com/Leaflet/Leaflet/pull/8794
+     * 
+     * @since leaflet-rotate (v0.2.0)
      */
     onAdd() {
       rendererProto.onAdd.apply(this, arguments);
@@ -437,6 +609,8 @@ var leafletRotate = (() => {
       }
     },
     /**
+     * Update the renderer transform during zoom animation, accounting for rotated coordinates.
+     *
      * @FIXME layer drifts on `map.setZoom()` (eg. zoom during animation)
      * 
      * the main cause seems to be related to `this._updateTransform(path._center, path._zoom))`
@@ -451,9 +625,14 @@ var leafletRotate = (() => {
      * @see https://github.com/Leaflet/Leaflet/pull/8103
      * @see https://github.com/Leaflet/Leaflet/issues/7466
      * 
-     * @TODO rechek this changes from leaflet@v1.9.3
+     * @TODO recheck these changes against leaflet@v1.9.3
      * 
      * @see https://github.com/Leaflet/Leaflet/compare/v1.7.0...v1.9.3
+     * 
+     * @param {L.LatLng} center Target map center.
+     * @param {number} zoom Target zoom level.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     _updateTransform(center, zoom) {
       if (L.version.startsWith("2.")) {
@@ -473,9 +652,16 @@ var leafletRotate = (() => {
       const scale = this._map.getZoomScale(zoom, this._zoom), offset = this._map._latLngToNewLayerPoint(this._topLeft, zoom, center);
       L.DomUtil.setTransform(this._container, offset, scale);
     },
+    /**
+     * Recalculate bounds and finish renderer updates after movement on Leaflet 2.
+     *
+     * @param {Object} ev Map movement event.
+     * 
+     * @since leaflet-rotate (v0.4.0)
+     */
     _onMoveEnd(ev) {
       if (!L.version.startsWith("2.") || !this._map._rotate) {
-        return rendererBase._onMoveEnd.apply(this, arguments);
+        return rendererOnMoveEnd.apply(this, arguments);
       }
       this._bounds = this._map._getPaddedPixelBounds(this.options.padding);
       this._topLeft = this._map.layerPointToLatLng(this._bounds.min);
@@ -486,6 +672,11 @@ var leafletRotate = (() => {
       this._resizeContainer();
       this._onSettled(ev);
     },
+    /**
+     * Resize the renderer container to cover the pitch-aware map bounds.
+     * 
+     * @since leaflet-rotate (v0.4.0)
+     */
     _resizeContainer() {
       if (!L.version.startsWith("2.") || !this._map._rotate || !this._bounds) {
         return rendererBase._resizeContainer.apply(this, arguments);
@@ -530,6 +721,11 @@ var leafletRotate = (() => {
     //         this._layers[id]._update();
     //     }
     // },
+    /**
+     * Recalculate renderer bounds and cached view state.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _update() {
       if (!this._map._rotate) {
         return rendererProto._update.apply(this, arguments);
@@ -543,8 +739,35 @@ var leafletRotate = (() => {
 
   // src/map/Map.js
   var mapProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.Map.prototype));
-  L.Map.mergeOptions({ rotate: false, bearing: 0 });
+  L.Map.mergeOptions({
+    /**
+     * @type {boolean} Enable bearing and pitch transformations.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
+    rotate: false,
+    /**
+     * @type {number} Initial map bearing in degrees.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
+    bearing: 0,
+    /**
+     * @type {number} Initial map pitch in degrees, clamped to 0–85.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    pitch: 0
+  });
   L.Map.include({
+    /**
+     * Apply an immediate animated-zoom frame without waiting for a transition delay.
+     *
+     * @param {L.LatLng} center Target center.
+     * @param {number} zoom Target zoom level.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _animateZoomNoDelay(center, zoom) {
       if (!this._mapPane) {
         return;
@@ -556,17 +779,24 @@ var leafletRotate = (() => {
       this._onZoomTransitionEnd();
     },
     /**
-     * @param {(HTMLElement|String)} id html selector
-     * @param {Object} [options={}] leaflet map options
+     * Initialize the Leaflet map and apply its initial bearing and pitch.
+     * 
+     * @param {HTMLElement|string} id Map container element or its ID.
+     * @param {Object} [options={}] Leaflet map options, including `rotate`, `bearing`, and `pitch`.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     initialize(id, options) {
       if (options.rotate) {
         this._rotate = true;
         this._bearing = 0;
+        this._pitch = 0;
       }
       mapProto.initialize.apply(this, arguments);
       if (this.options.rotate) {
+        this.on("resize", this._updatePitchTransform, this);
         this.setBearing(this.options.bearing);
+        this.setPitch(this.options.pitch);
       }
     },
     /**
@@ -574,26 +804,41 @@ var leafletRotate = (() => {
      * returns the corresponding pixel coordinate relative to
      * the [origin pixel](#map-getpixelorigin).
      * 
-     * @param {L.Point} point pixel screen coordinates
-     * @returns {L.Point} transformed pixel point
+     * @param {L.Point|number[]} point Pixel coordinate in the map container.
+     * 
+     * @returns {L.Point} Corresponding layer-point coordinate.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     containerPointToLayerPoint(point) {
       if (!this._rotate) {
         return mapProto.containerPointToLayerPoint.apply(this, arguments);
       }
+      if (this._pitch) {
+        return this._transformPitchPoint(
+          toPoint(point).subtract(this._getMapPanePos()),
+          this._pitchInverseTransform
+        );
+      }
       return toPoint(point).subtract(this._getMapPanePos()).rotateFrom(-this._bearing, this._getRotatePanePos()).subtract(this._getRotatePanePos());
     },
     /**
      * Given a pixel coordinate relative to the [origin pixel](#map-getpixelorigin),
      * returns the corresponding pixel coordinate relative to the map container.
      * 
-     * @param {L.Point} point pixel screen coordinates
-     * @returns {L.Point} transformed pixel point
+     * @param {L.Point|number[]} point Pixel coordinate in layer-point space.
+     * 
+     * @returns {L.Point} Corresponding pixel coordinate in the map container.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     layerPointToContainerPoint(point) {
       if (!this._rotate) {
         return mapProto.layerPointToContainerPoint.apply(this, arguments);
       }
+      if (this._pitch) {
+        return this._transformPitchPoint(point, this._pitchTransform).add(this._getMapPanePos());
+      }
       return toPoint(point).add(this._getRotatePanePos()).rotateFrom(this._bearing, this._getRotatePanePos()).add(this._getMapPanePos());
     },
     /**
@@ -603,12 +848,16 @@ var leafletRotate = (() => {
      * (rotatePane) --> (mapPane)
      * (rotatePane) --> (norotatePane)
      * 
-     * @param {L.Point} point pixel screen coordinates
-     * @returns {L.Point}
+     * @param {L.Point|number[]} point Point in the rotated pane.
+     * 
+     * @returns {L.Point} Corresponding point in map-pane coordinates.
      * 
-     * @since leaflet-rotate (v0.1)
+     * @since leaflet-rotate (v0.1.0)
      */
     rotatedPointToMapPanePoint(point) {
+      if (this._pitch) {
+        return this._transformPitchPoint(point, this._pitchTransform);
+      }
       return toPoint(point).rotate(this._bearing)._add(this._getRotatePanePos());
     },
     /**
@@ -618,11 +867,16 @@ var leafletRotate = (() => {
      * (mapPane) --> (rotatePane)
      * (norotatePane) --> (rotatePane)
      * 
-     * @param {L.Point} point pixel screen coordinates
+     * @param {L.Point|number[]} point Point in map-pane coordinates.
      * 
-     * @since leaflet-rotate (v0.1)
+     * @returns {L.Point} Corresponding point in the rotated pane.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     mapPanePointToRotatedPoint(point) {
+      if (this._pitch) {
+        return this._transformPitchPoint(point, this._pitchInverseTransform);
+      }
       return toPoint(point)._subtract(this._getRotatePanePos()).rotate(-this._bearing);
     },
     // latLngToLayerPoint(latlng) {
@@ -638,10 +892,11 @@ var leafletRotate = (() => {
      * 
      * @see https://github.com/ronikar/Leaflet/blob/5c480ef959b947c3beed7065425a5a36c486262b/src/map/Map.js#L1114-L1135
      * 
-     * @param {L.LatLngBounds} bounds 
-     * @returns {L.Bounds}
+     * @param {L.LatLngBounds} bounds Geographic bounds to project.
      * 
-     * @since leaflet-rotate (v0.2)
+     * @returns {L.Bounds} Axis-aligned bounds in container-pixel coordinates.
+     * 
+     * @since leaflet-rotate (v0.2.0)
      */
     mapBoundsToContainerBounds(bounds) {
       if (!this._rotate && mapProto.mapBoundsToContainerBounds) {
@@ -657,14 +912,13 @@ var leafletRotate = (() => {
       ]);
     },
     /**
-     * Returns geographical bounds visible in the current map view
+     * Return the geographic bounds of the current viewport, accounting for rotation and pitch.
      * 
-     * @TODO find out  if map bounds calculated by `L.Map::getBounds()`
-     *       function should match the `rotatePane` or `norotatePane` bounds
+     * The result is the smallest geographic bounds containing all four viewport corners.
      * 
-     * @see https://github.com/fnicollet/Leaflet/issues/7
+     * @returns {L.LatLngBounds} Geographic bounds visible in the map viewport.
      * 
-     * @returns {L.LatLngBounds}
+     * @since leaflet-rotate (v0.1.0)
      */
     getBounds() {
       if (!this._rotate) {
@@ -699,15 +953,19 @@ var leafletRotate = (() => {
     //       return new L.Bounds(topLeftPoint, topLeftPoint.add(this.getSize()));
     // },
     /**
-     * Change map rotation
+     * Set the map bearing, optionally animating to the new value.
+     * 
+     * @param {number} theta Target bearing in degrees; normalized to [0, 360).
+     * @param {Object} [options] Animation options.
+     * @param {boolean} [options.animate=false] Animate the change.
+     * @param {number} [options.duration=0.25] Animation duration in seconds.
+     * @param {number} [options.easeLinearity=0.5] Easing curve linearity.
+     * 
+     * @returns {void}
      * 
-     * @param {number} theta map degrees
-     * @param {Object} [options] animation options
-     * @param {boolean} [options.animate=false]
-     * @param {number} [options.duration=0.25] animation duration in seconds
-     * @param {number} [options.easeLinearity=0.5]
+     * @fires L.Map#rotate
      * 
-     * @since leaflet-rotate (v0.1)
+     * @since leaflet-rotate (v0.1.0)
      */
     setBearing(theta, options) {
       if (!this._rotate) {
@@ -746,20 +1004,145 @@ var leafletRotate = (() => {
       }
       this._setBearing(theta);
     },
-    _setBearing(theta) {
+    /**
+     * Apply a bearing immediately and update the rotated pane and map coordinates.
+     * 
+     * @param {number} theta Bearing in degrees.
+     * @param {L.LatLng} [mapCenter] Center to preserve while applying the change.
+     * 
+     * @fires L.Map#rotate
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
+    _setBearing(theta, mapCenter) {
+      if (!mapCenter && this._loaded) {
+        mapCenter = this.getCenter();
+      }
       const bearing = L.Util.wrapNum(theta, [0, 360]) * (Math.PI / 180), center = this._getPixelCenter(), oldPos = this._getRotatePanePos().rotateFrom(-this._bearing, center), newPos = oldPos.rotateFrom(bearing, center);
-      L.DomUtil.setPosition(this._rotatePane, oldPos, bearing, center);
       this._pivot = center;
       this._bearing = bearing;
       this._rotatePanePos = newPos;
+      if (this._pitch) {
+        this._rotatePane._leaflet_pos = oldPos;
+        this._updatePitchTransform();
+      } else {
+        L.DomUtil.setPosition(this._rotatePane, oldPos, bearing, center);
+      }
+      if (mapCenter) {
+        this._pixelOrigin = this.project(mapCenter, this._zoom).subtract(this.containerPointToLayerPoint(this.getSize().divideBy(2)));
+        delete this._lastCenter;
+        this.fire("move");
+      }
       this.fire("rotate");
     },
     /**
-     * Get current map rotation
+     * Transform a point with a projective matrix, accepting DOMMatrix or its 2D inverse.
+     * 
+     * @param {L.Point|number[]} point Input pixel coordinate.
+     * @param {DOMMatrix|Object} matrix Forward or inverse transformation matrix.
+     * 
+     * @returns {L.Point} Transformed pixel coordinate.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    _transformPitchPoint(point, matrix) {
+      point = toPoint(point);
+      if (!(matrix instanceof DOMMatrix)) {
+        const denominator = matrix.g * point.x + matrix.h * point.y + matrix.i;
+        return new L.Point(
+          (matrix.a * point.x + matrix.b * point.y + matrix.c) / denominator,
+          (matrix.d * point.x + matrix.e * point.y + matrix.f) / denominator
+        );
+      }
+      const transformed = new DOMPoint(point.x, point.y).matrixTransform(matrix);
+      return new L.Point(transformed.x / transformed.w, transformed.y / transformed.w);
+    },
+    /**
+     * Apply the current pitch/bearing CSS transform and cache its forward and inverse matrices.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    _updatePitchTransform() {
+      if (!this._pitch || !this._rotatePane) {
+        return;
+      }
+      const pivot = this._getPixelCenter(), size = this.getSize(), perspective = Math.max(1, size.y * 1.5), position = this._rotatePane._leaflet_pos || new L.Point(0, 0), transform = `translate3d(${pivot.x}px,${pivot.y}px,0) perspective(${perspective}px) rotateX(${this.getPitch()}deg) rotateZ(${this.getBearing()}deg) translate3d(${position.x - pivot.x}px,${position.y - pivot.y}px,0)`;
+      this._rotatePane.style.transformOrigin = "0 0";
+      this._rotatePane.style.transform = transform;
+      const matrix = this._pitchTransform = new DOMMatrix(getComputedStyle(this._rotatePane).transform), a = matrix.m11, b = matrix.m21, c = matrix.m41, d = matrix.m12, e = matrix.m22, f = matrix.m42, g = matrix.m14, h = matrix.m24, i = matrix.m44, determinant = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g);
+      this._pitchInverseTransform = {
+        a: (e * i - f * h) / determinant,
+        b: (c * h - b * i) / determinant,
+        c: (b * f - c * e) / determinant,
+        d: (f * g - d * i) / determinant,
+        e: (a * i - c * g) / determinant,
+        f: (c * d - a * f) / determinant,
+        g: (d * h - e * g) / determinant,
+        h: (b * g - a * h) / determinant,
+        i: (a * e - b * d) / determinant
+      };
+    },
+    /**
+     * Set the map pitch in degrees. Values are clamped to the range 0–85.
+     *
+     * @param {number} pitch Pitch angle in degrees; clamped to [0, 85].
+     * 
+     * @returns {L.Map} This map instance.
+     * 
+     * @fires L.Map#pitch
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    setPitch(pitch) {
+      this._setPitchAndBearing(pitch, this.getBearing());
+      return this;
+    },
+    /**
+     * Update pitch and bearing together, preserving the current map center.
+     * Used by the Ctrl+drag handler to avoid applying two separate transforms.
+     * 
+     * @param {number} pitch Pitch angle in degrees.
+     * @param {number} bearing Bearing angle in degrees.
+     * 
+     * @fires L.Map#pitch
+     * @fires L.Map#rotate
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    _setPitchAndBearing(pitch, bearing) {
+      if (!this._rotate) {
+        return;
+      }
+      const clampedPitch = Math.max(0, Math.min(pitch, 85)) * (Math.PI / 180), clampedBearing = L.Util.wrapNum(bearing, [0, 360]) * (Math.PI / 180), pitchChanged = clampedPitch !== this._pitch;
+      if (!pitchChanged && clampedBearing === this._bearing) {
+        return;
+      }
+      const mapCenter = this._loaded ? this.getCenter() : void 0;
+      if (pitchChanged) {
+        this._pitch = clampedPitch;
+        this._rotatePane.style.transformOrigin = L.version.startsWith("2.") ? "0 0" : "";
+      }
+      this._setBearing(bearing, mapCenter);
+      if (pitchChanged) {
+        this.fire("pitch");
+      }
+    },
+    /**
+     * Get the current map pitch in degrees.
+     * 
+     * @returns {number} Pitch angle in degrees.
+     * 
+     * @since leaflet-rotate (0.5.0)
+     */
+    getPitch() {
+      return (this._pitch || 0) * (180 / Math.PI);
+    },
+    /**
+     * Get the current map bearing. Enable the `rotate` map option before calling.
      * 
-     * @returns {number} theta map degrees
+     * @returns {number} Bearing in degrees, normalized to [0, 360).
      * 
-     * @since leaflet-rotate (v0.1)
+     * @since leaflet-rotate (v0.1.0)
      */
     getBearing() {
       return this._bearing * (180 / Math.PI);
@@ -771,7 +1154,10 @@ var leafletRotate = (() => {
      * 
      * @param {String} name leaflet pane
      * @param {HTMLElement} [container] parent element
+     * 
      * @returns {HTMLElement} pane container
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     // createPane(name, container) {
     //     if (!this._rotate || name == 'mapPane') {
@@ -801,6 +1187,12 @@ var leafletRotate = (() => {
      * - tooltipPane [HTMLElement = 650]    - Pane for tooltips.
      * - popupPane   [HTMLElement = 700]    - Pane for popups.
      */
+    /**
+     * Create the map's panes, placing tile/vector layers in the transformed pane
+     * and markers/overlays in the pane that remains upright.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _initPanes() {
       const panes = this._panes = {};
       this._paneRenderers = {};
@@ -839,13 +1231,15 @@ var leafletRotate = (() => {
      * 
      * @see https://github.com/Raruto/leaflet-rotate/issues/18
      * 
-     * @param {L.LatLng} latlng coordinates
-     * @param {Object} [options={}] padding options
+     * @param {L.LatLng} latlng Geographic point to keep visible.
+     * @param {Object} [options={}] Padding options (`padding`, `paddingTopLeft`, `paddingBottomRight`).
      * 
      * @returns {L.Map} current map instance
+     * 
+     * @since leaflet-rotate (v0.1.4)
      */
     panInside(latlng, options) {
-      if (!this._rotate || Math.abs(this._bearing).toFixed(1) < 0.1) {
+      if (!this._rotate || !this._pitch && Math.abs(this._bearing).toFixed(1) < 0.1) {
         return mapProto.panInside.apply(this, arguments);
       }
       options = options || {};
@@ -871,9 +1265,12 @@ var leafletRotate = (() => {
      *
      * @see https://github.com/fnicollet/Leaflet/issues/7
      * 
-     * @param {L.LatLngBounds} bounds coordinates
-     * @param {Object} [options] pan options
-     * @returns {L.Map} current map instance
+     * @param {L.LatLngBounds} bounds Geographic bounds to fit inside the viewport.
+     * @param {Object} [options] Pan animation options.
+     * 
+     * @returns {L.Map} This map instance.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     // panInsideBounds(bounds, options) {
     //     this._enforcingBounds = true;
@@ -938,14 +1335,16 @@ var leafletRotate = (() => {
      * instead returns the minimum zoom level on which the map view fits into
      * the given bounds in its entirety.
      * 
-     * @param {L.LatLngBounds} bounds
-     * @param {Boolean} [inside=false]
-     * @param {L.Point} [padding=[0,0]]
+     * @param {L.LatLngBounds} bounds Geographic bounds to fit.
+     * @param {boolean} [inside=false] Fit the viewport inside bounds instead of bounds inside the viewport.
+     * @param {L.Point|number[]} [padding=[0,0]] Pixel padding around the viewport.
+     * 
+     * @returns {number} Zoom level satisfying the fit.
      * 
-     * @returns {Number} zoom level
+     * @since leaflet-rotate (v0.1.0)
      */
     getBoundsZoom(bounds, inside, padding) {
-      if (!this._rotate || Math.abs(this._bearing).toFixed(1) < 0.1) {
+      if (!this._rotate || !this._pitch && Math.abs(this._bearing).toFixed(1) < 0.1) {
         return mapProto.getBoundsZoom.apply(this, arguments);
       }
       bounds = bounds instanceof L.LatLngBounds ? bounds : new L.LatLngBounds(bounds);
@@ -968,19 +1367,30 @@ var leafletRotate = (() => {
     //    return this.containerPointToLayerPoint(this.getSize()._divideBy(2));
     // },
     /**
-     * Offset of the specified place to the current center in pixels
+     * Return the pixel offset from the current center to the given geographic point.
      * 
-     * @param {L.LatLng} latlng map coordinates
+     * @param {L.LatLng} latlng Geographic point.
+     * 
+     * @returns {L.Point} Offset in layer pixels, adjusted for bearing and pitch.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     _getCenterOffset(latlng) {
       let centerOffset = mapProto._getCenterOffset.apply(this, arguments);
-      if (this._rotate) {
+      if (this._pitch) {
+        const center = this.getSize()._divideBy(2);
+        centerOffset = this.containerPointToLayerPoint(center.add(centerOffset)).subtract(this.containerPointToLayerPoint(center));
+      } else if (this._rotate) {
         centerOffset = centerOffset.rotate(this._bearing);
       }
       return centerOffset;
     },
     /**
-     * @since leaflet-rotate (v0.1)
+     * Return the current position of the rotated pane.
+     * 
+     * @returns {L.Point} Rotated-pane position in map-pane coordinates.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     _getRotatePanePos() {
       return this._rotatePanePos || new L.Point(0, 0);
@@ -989,6 +1399,16 @@ var leafletRotate = (() => {
     //    const topLeft = this._getNewPixelOrigin(center, zoom);
     //    return this.project(latlng, zoom)._subtract(topLeft);
     //},
+    /**
+     * Calculate the pixel origin for a target view while preserving bearing-aware alignment.
+     * 
+     * @param {L.LatLng} center Target center.
+     * @param {number} zoom Target zoom level.
+     * 
+     * @returns {L.Point} New pixel origin.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _getNewPixelOrigin(center, zoom) {
       if (!this._rotate || L.version.startsWith("2.")) {
         return mapProto._getNewPixelOrigin.apply(this, arguments);
@@ -997,7 +1417,14 @@ var leafletRotate = (() => {
       return this.project(center, zoom).rotate(this._bearing)._subtract(viewHalf)._add(this._getMapPanePos())._add(this._getRotatePanePos()).rotate(-this._bearing)._round();
     },
     /**
-     * @since leaflet-rotate (v0.2)
+     * Calculate the pixel bounds needed to cover the transformed viewport.
+     * 
+     * @param {L.LatLng} [center=this.getCenter()] Target center.
+     * @param {number} [zoom=this.getZoom()] Target zoom level.
+     * 
+     * @returns {L.Bounds} Pixel bounds in projected map coordinates.
+     * 
+     * @since leaflet-rotate (v0.2.0)
      * 
      * @see src\layer\tile\GridLayer::_getTiledPixelBounds()
      */
@@ -1016,9 +1443,9 @@ var leafletRotate = (() => {
       return new L.Bounds(pixelCenter.subtract(halfSize), pixelCenter.add(halfSize));
     },
     /**
-     * @since leaflet-rotate (v0.2)
+     * @since leaflet-rotate (v0.2.0)
      * 
-     * @return {L.Point} map pivot point (center)
+     * @returns {L.Point} Map pivot point in pixel coordinates.
      */
     _getPixelCenter() {
       if (!this._rotate && mapProto._getPixelCenter) {
@@ -1027,9 +1454,13 @@ var leafletRotate = (() => {
       return this.getSize()._divideBy(2)._subtract(this._getMapPanePos());
     },
     /**
-     * @since leaflet-rotate (v0.2)
-     * 
      * @see src\layer\vector\Renderer::_update()
+     * 
+     * @param {number} padding Bounds padding as a fraction of map size.
+     * 
+     * @returns {L.Bounds} Padded bounds in layer-point coordinates.
+     * 
+     * @since leaflet-rotate (v0.2.0)
      */
     _getPaddedPixelBounds(padding) {
       if (!this._rotate && mapProto._getPaddedPixelBounds) {
@@ -1043,6 +1474,15 @@ var leafletRotate = (() => {
         this.containerPointToLayerPoint([padMax.x, padMax.y]).floor()
       ]);
     },
+    /**
+     * Build and fire Leaflet's location-found event, including the device heading.
+     * 
+     * @param {GeolocationPosition} pos Browser geolocation result.
+     * 
+     * @fires L.Map#locationfound
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _handleGeolocationResponse(pos) {
       if (!this._container._leaflet_id) {
         return;
@@ -1070,6 +1510,7 @@ var leafletRotate = (() => {
      * @see https://github.com/ronikar/Leaflet/blob/5c480ef959b947c3beed7065425a5a36c486262b/src/geo/LatLngBounds.js#L253-L264
      * 
      * @param {L.Bounds} points 
+     * 
      * @returns {L.Bounds}
      */
     // toCircumscribedBounds(points) {
@@ -1084,6 +1525,11 @@ var leafletRotate = (() => {
 
   // src/map/handler/CompassBearing.js
   L.Map.CompassBearing = L.Handler.extend({
+    /**
+     * @param {L.Map} map Map whose bearing follows device orientation.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     initialize(map) {
       this._map = map;
       if ("ondeviceorientationabsolute" in window) {
@@ -1093,6 +1539,11 @@ var leafletRotate = (() => {
       }
       this._throttled = L.Util.throttle(this._onDeviceOrientation, 100, this);
     },
+    /**
+     * Subscribe to the supported device-orientation event, if available.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     addHooks() {
       if (this._map._rotate && this.__deviceOrientationEvent) {
         L.DomEvent.on(window, this.__deviceOrientationEvent, this._throttled, this);
@@ -1100,12 +1551,19 @@ var leafletRotate = (() => {
         this.disable();
       }
     },
+    /**
+     * Unsubscribe from device orientation when the handler is disabled.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     removeHooks() {
       if (this._map._rotate && this.__deviceOrientationEvent) {
         L.DomEvent.off(window, this.__deviceOrientationEvent, this._throttled, this);
       }
     },
     /**
+     * Apply a device orientation reading to the map bearing.
+     *
      * `DeviceOrientationEvent.absolute` - Indicates whether the device is providing absolute
      *                                     orientation values (relatives to Magnetic North) or
      *                                     using some arbitrary frame determined by the device.
@@ -1122,6 +1580,10 @@ var leafletRotate = (() => {
      * @see https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent/absolute
      * @see https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent/alpha
      * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/orientation
+     *
+     * @param {DeviceOrientationEvent} e Orientation reading from the browser.
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     _onDeviceOrientation(e) {
       let angle = e.webkitCompassHeading != null ? e.webkitCompassHeading : e.alpha;
@@ -1150,11 +1612,18 @@ var leafletRotate = (() => {
      *
      * @type {Boolean}
      * 
+     * @since leaflet-rotate (v0.1.0)
+     * 
      * @see https://developer.mozilla.org/docs/Web/API/MutationObserver
      */
     trackContainerMutation: false
   });
   L.Map.ContainerMutation = L.Handler.extend({
+    /**
+     * Start observing the map container's style attribute.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     addHooks() {
       if (!this._observer) {
         this._observer = new MutationObserver(L.Util.bind(this._map.invalidateSize, this._map));
@@ -1167,6 +1636,11 @@ var leafletRotate = (() => {
         attributeFilter: ["style"]
       });
     },
+    /**
+     * Stop observing container mutations.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     removeHooks() {
       this._observer.disconnect();
     }
@@ -1183,26 +1657,50 @@ var leafletRotate = (() => {
   }
   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
   });
   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;
       if (!e.touches || e.touches.length !== 2 || map._animatingZoom || this._zooming || this._rotating) {
@@ -1236,6 +1734,13 @@ var leafletRotate = (() => {
       L.DomEvent.on(document, "touchmove", this._onTouchMove, this).on(document, "touchend touchcancel", this._onTouchEnd, this);
       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;
@@ -1267,8 +1772,8 @@ var leafletRotate = (() => {
           if (scale === 1 && delta.x === 0 && delta.y === 0) {
             return;
           }
-          const alpha = -map.getBearing() * (Math.PI / 180);
-          this._center = map.unproject(map.project(this._pinchStartLatLng).subtract(delta.rotate(alpha)));
+          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(mapDelta));
         }
       }
       if (!this._moved) {
@@ -1286,6 +1791,11 @@ var leafletRotate = (() => {
       }
       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;
@@ -1311,14 +1821,26 @@ var leafletRotate = (() => {
      * Whether the map can be rotated with a two-finger rotation gesture
      * 
      * @type {Boolean}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     touchRotate: false
   });
   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;
     }
@@ -1328,33 +1850,170 @@ var leafletRotate = (() => {
   // src/map/handler/ShiftKeyRotate.js
   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)
      */
-    shiftKeyRotate: true
+    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.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;
     }
   });
-  L.Map.addInitHook("addHandler", "shiftKeyRotate", L.Map.ShiftKeyRotate);
   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();
     }
@@ -1370,6 +2029,8 @@ var leafletRotate = (() => {
      * for touch-capable web browsers.
      * 
      * @type {(Boolean|String)}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     touchZoom: L.Browser.touch,
     /**
@@ -1380,15 +2041,27 @@ var leafletRotate = (() => {
      * when pinch-zooming.
      * 
      * @type {Boolean}
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     bounceAtZoomLimits: false
   });
   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;
@@ -1402,6 +2075,15 @@ var leafletRotate = (() => {
       position: "topleft",
       closeOnZeroBearing: true
     },
+    /**
+     * Create the control element and subscribe to map rotation.
+     * 
+     * @param {L.Map} map
+     * 
+     * @returns {HTMLElement} Control container.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     onAdd(map) {
       const container = this._container = L.DomUtil.create("div", "leaflet-control-rotate leaflet-bar");
       const arrow = this._arrow = L.DomUtil.create("span", "leaflet-control-rotate-arrow");
@@ -1426,9 +2108,23 @@ var leafletRotate = (() => {
       }
       return container;
     },
+    /**
+     * Remove the map event listener when the control is detached.
+     * 
+     * @param {L.Map} map
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     onRemove(map) {
       map.off("rotate", this._restyle, this);
     },
+    /**
+     * Begin dragging the control's bearing indicator.
+     * 
+     * @param {MouseEvent} e Mouse-down event.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _handleMouseDown(e) {
       L.DomEvent.stop(e);
       this.dragging = true;
@@ -1436,11 +2132,25 @@ var leafletRotate = (() => {
       this.dragstartY = e.pageY;
       L.DomEvent.on(document, "mousemove", this._handleMouseDrag, this).on(document, "mouseup", this._handleMouseUp, this);
     },
+    /**
+     * End bearing-indicator dragging and remove document listeners.
+     * 
+     * @param {MouseEvent} e Mouse-up event.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _handleMouseUp(e) {
       L.DomEvent.stop(e);
       this.dragging = false;
       L.DomEvent.off(document, "mousemove", this._handleMouseDrag, this).off(document, "mouseup", this._handleMouseUp, this);
     },
+    /**
+     * Set bearing from the horizontal drag distance.
+     * 
+     * @param {MouseEvent} e Mouse-move event.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _handleMouseDrag(e) {
       if (!this.dragging) {
         return;
@@ -1448,6 +2158,14 @@ var leafletRotate = (() => {
       const deltaX = e.clientX - this.dragstartX;
       this._map.setBearing(deltaX);
     },
+    /**
+     * Cycle through touch, compass, and locked rotation modes.
+     * Compass mode may require permission from the browser.
+     * 
+     * @param {Event} ev Control click event.
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _cycleState(ev) {
       if (!this._map) {
         return;
@@ -1467,6 +2185,13 @@ var leafletRotate = (() => {
       }
       this._restyle();
     },
+    /**
+     * Update the control icon and visibility to match the current mode.
+     * 
+     * @listens L.Map#rotate
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     _restyle() {
       if (!this._map.options.rotate) {
         this._link.classList.add("leaflet-disabled");
@@ -1494,6 +2219,14 @@ var leafletRotate = (() => {
     L.control.rotate = (options) => new L.Control.Rotate(options);
   }
   L.Map.mergeOptions({
+    /**
+     * Add the rotation control automatically. Set to `false` to disable,
+     * or pass an options object to configure the control.
+     * 
+     * @type {boolean|Object}
+     * 
+     * @since leaflet-rotate (v0.1.0)
+     */
     rotateControl: true
   });
   L.Map.addInitHook(function() {