leaflet-rotate 0.4.0 → 0.5.0

package/misc/leaflet-heat-rotate.js

@@ -1,3 +1,10 @@
+/*
+ * For Leaflet.heat (https://github.com/Leaflet/Leaflet.heat) or the heatmap.js
+ * Leaflet plugin (https://github.com/pa7/heatmap.js/tree/master/plugins/leaflet-heatmap),
+ * load this file after the heatmap plugin. It adapts heat redraw coordinates to
+ * the rotated pane.
+ */
+
 if (!L.HeatLayer && !globalThis.HeatmapOverlay) {
     throw new Error('Load Leaflet.heat or heatmap.js Leaflet plugin before this adapter.');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "leaflet-rotate",
-	"version": "0.4.0",
+	"version": "0.5.0",
 	"description": "A Leaflet plugin that allows to add rotation functionality to map tiles",
 	"type": "module",
 	"main": "dist/leaflet-rotate.js",

package/src/control/Rotate.js

@@ -1,11 +1,19 @@
 /**
- * A tri-state control for map rotation, states are:
+ * Leaflet control for changing map rotation and selecting a rotation mode.
+ * Its modes are:
  * 
- * - Locked (default)
- * - Unlocked (user can pinch-rotate)
- * - Follow (rotation follows device orientation, if available)
+ * - Locked: rotation gestures are disabled.
+ * - Touch: two-finger rotation is enabled.
+ * - Compass: bearing follows device orientation when supported and permitted.
  * 
- * @typedef L.Control.Rotate
+ * @class L.Control.Rotate
+ * 
+ * @extends L.Control
+ * 
+ * @property {string} [position='topleft'] Leaflet control position.
+ * @property {boolean} [closeOnZeroBearing=true] Hide the control when bearing is zero.
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 L.Control.Rotate = L.Control.extend({
@@ -15,6 +23,15 @@ L.Control.Rotate = L.Control.extend({
         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');
 
@@ -58,10 +75,24 @@ L.Control.Rotate = L.Control.extend({
         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;
@@ -72,6 +103,13 @@ L.Control.Rotate = L.Control.extend({
             .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;
@@ -81,12 +119,27 @@ L.Control.Rotate = L.Control.extend({
             .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; }
         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;
@@ -120,6 +173,13 @@ L.Control.Rotate = L.Control.extend({
         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');
@@ -160,9 +220,22 @@ if (L.control) {
 }
 
 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,
 });
 
+/**
+ * Add the configured rotation control to each newly initialized map.
+ * 
+ * @since leaflet-rotate (v0.1.0)
+ */
 L.Map.addInitHook(function() {
     if (this.options.rotateControl) {
         const options = typeof this.options.rotateControl === 'object' ? this.options.rotateControl : {};

package/src/dom/DomUtil.js

@@ -11,11 +11,15 @@ Object.assign(L.DomUtil, {
      * 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);
@@ -35,11 +39,15 @@ Object.assign(L.DomUtil, {
      * 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) {
@@ -53,8 +61,11 @@ Object.assign(L.DomUtil, {
     /**
      * 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);

package/src/dom/Draggable.js

@@ -1,4 +1,7 @@
 /**
+ * This plugin does not modify the `L.Draggable` API; it adapts marker drag
+ * coordinates in `L.Marker` when rotation or pitch is enabled.
+ *
  * @external L.Draggable
  * 
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/dom/Draggable.js
@@ -8,6 +11,8 @@
  * A class for making DOM elements draggable (including touch support).
  * Used internally for map and marker dragging. Only works for elements
  * that were positioned with [`L.DomUtil.setPosition`](#domutil-setposition).
+ *
+ * @since leaflet-rotate (v0.1.0)
  */
 
 L.Draggable.include({

package/src/geo/LatLngBounds.js

@@ -1,4 +1,9 @@
 /**
+ * Leaflet's `L.LatLngBounds` is not overridden by this plugin. Map methods
+ * such as `getBounds()` return standard Leaflet bounds containing the viewport.
+ *
+ * @since leaflet-rotate (v0.1.0)
+ *
  * @external L.LatLngBounds
  * 
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/geo/LatLngBounds.js

package/src/geometry/Bounds.js

@@ -1,4 +1,9 @@
 /**
+ * Leaflet's `L.Bounds` is not overridden by this plugin. Rotation-aware
+ * pixel bounds are calculated by the map and renderer extensions.
+ *
+ * @since leaflet-rotate (v0.1.0)
+ *
  * @external L.Bounds
  * 
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/geometry/Bounds.js

package/src/geometry/Point.js

@@ -12,7 +12,10 @@ Object.assign(L.Point.prototype, {
      * ⎡ 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))
@@ -27,10 +30,12 @@ Object.assign(L.Point.prototype, {
      * 
      * 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) { return this; }
@@ -49,6 +54,15 @@ Object.assign(L.Point.prototype, {
 
 });
 
+/**
+ * Convert an array or point-like object to an `L.Point`.
+ * 
+ * @param {L.Point|number[]|{x:number,y:number}|null} point Coordinate to convert.
+ * 
+ * @returns {L.Point|null} Existing point, converted point, or `null` for a null input.
+ * 
+ * @since leaflet-rotate (v0.1.0)
+ */
 export function toPoint(point) {
     if (point == null || point instanceof L.Point) {
         return point;

package/src/index.js

@@ -1,5 +1,7 @@
 /**
- * Export Leaflet classes in the same order as the core library
+ * Export Leaflet classes in the same order as the core library.
+ *
+ * @since leaflet-rotate (v0.1.0)
  * 
  * @external L
  *

package/src/layer/DivOverlay.js

@@ -1,7 +1,11 @@
 /**
+ * Keeps popup and tooltip screen positions aligned with rotated and pitched maps.
+ *
  * @external L.DivOverlay
  * 
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/layer/DivOverlay.js
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 import { toPoint } from '../geometry/Point';
@@ -11,18 +15,43 @@ const divOverlayProto = Object.defineProperties({}, Object.getOwnPropertyDescrip
 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) { return; }

package/src/layer/Popup.js

@@ -1,7 +1,11 @@
 /**
+ * Preserves popup positioning and auto-pan behavior on rotated maps.
+ *
  * @external L.Popup
  * 
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/layer/Popup.js
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 import { toPoint } from '../geometry/Point';
@@ -11,8 +15,11 @@ const popupProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(
 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);
@@ -24,9 +31,13 @@ L.Popup.include({
     },
 
     /**
-     * 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)) { return; }

package/src/layer/Tooltip.js

@@ -1,13 +1,24 @@
 /**
+ * Keeps tooltips positioned correctly when the map is rotated or pitched.
+ *
  * @external L.Tooltip
  * 
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/layer/Tooltip.js
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 const 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);
@@ -18,6 +29,11 @@ L.Tooltip.include({
         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);

package/src/layer/marker/Icon.js

@@ -1,13 +1,25 @@
 /**
+ * Applies icon-anchor transform origins so marker rotation pivots around its anchor.
+ *
  * @external L.Icon
  * 
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/layer/marker/Icon.js
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 const 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'];

package/src/layer/marker/Marker.js

@@ -1,7 +1,16 @@
 /**
+ * Adds rotation and pitch-aware positioning to Leaflet markers.
+ *
  * @external L.Marker
  * @external L.Handler.MarkerDrag
  * 
+ * @property {number} [rotation=0] Marker icon rotation in radians.
+ * @property {boolean} [rotateWithView=false] Rotate the icon with the map bearing.
+ * @property {boolean} [keepUpright=false] Flip a map-aligned icon to keep it upright.
+ * @property {number} [scale] Optional scale applied to the icon and shadow.
+ * 
+ * @since leaflet-rotate (v0.1.0)
+ * 
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/layer/marker/Marker.js
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/layer/marker/Marker.Drag.js
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/dom/Draggable.js
@@ -12,30 +21,41 @@ const markerProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors
 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: undefined,
 
@@ -52,6 +72,13 @@ const MarkerDrag = {
     //     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,
             /** @TODO use markerDragProto._onDrag */
@@ -86,6 +113,13 @@ const MarkerDrag = {
             .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();
@@ -98,15 +132,44 @@ const MarkerDrag = {
 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) {
@@ -123,6 +186,13 @@ L.Marker.include({
         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) {
 
         /** @TODO use markerProto._setPos */
@@ -165,6 +235,15 @@ L.Marker.include({
     //     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();

package/src/layer/tile/GridLayer.js

@@ -1,7 +1,11 @@
 /**
+ * Updates tile coverage for rotated map bounds.
+ *
  * @external L.GridLayer
  * 
  * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/layer/tile/GridLayer.js
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 const gridLayerProto = Object.defineProperties({}, Object.getOwnPropertyDescriptors(L.GridLayer.prototype));
@@ -9,10 +13,13 @@ const gridLayerProto = Object.defineProperties({}, Object.getOwnPropertyDescript
 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);
@@ -25,6 +32,15 @@ L.GridLayer.include({
         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);