leaflet-rotate 0.4.0 → 0.5.1

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
  *
@@ -53,6 +55,7 @@ export * from './map/handler/CompassBearing';
 export * from './map/handler/ContainerMutation';
 export * from './map/handler/TouchGestures';
 export * from './map/handler/TouchRotate';
+export * from './map/handler/TouchPitch';
 export * from './map/handler/ShiftKeyRotate';
 export * from './map/handler/TouchZoom';
 

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);
@@ -20,11 +27,39 @@ L.GridLayer.include({
             if (!this._onRotate) {
                 this._onRotate = L.Util.throttle(this._onMoveEnd, this.options.updateInterval, this);
             }
-            events.rotate = this._onRotate;
+            events.rotate = this._onRotateEvent;
         }
         return events;
     },
 
+    /**
+     * Keep tile levels aligned when a bearing/pitch change shifts the pixel origin
+     * (eg. when the rotation pivot is not the view center), then refresh tiles (throttled).
+     * 
+     * @listens L.Map~rotate
+     * 
+     * @since leaflet-rotate (0.5.1)
+     */
+    _onRotateEvent() {
+        const map = this._map;
+        if (!map) { return; }
+        const origin = map.getPixelOrigin();
+        if (this._rotateOrigin && !this._rotateOrigin.equals(origin) && !map._animatingZoom && this._levels) {
+            this._setZoomTransforms(map.getCenter(), map.getZoom());
+        }
+        this._rotateOrigin = origin;
+        this._onRotate();
+    },
+
+    /**
+     * 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);