leaflet-rotate 0.2.0 → 0.2.2

package/dist/leaflet-rotate.js

@@ -13,12 +13,24 @@
 
     L.extend(L.DomUtil, {
 
+        /**
+         * Resets the 3D CSS transform of `el` so it is
+         * translated by `offset` pixels and optionally
+         * scaled by `scale`. Does not have an effect if
+         * the browser doesn't support 3D CSS transforms.
+         * 
+         * @param {HTMLElement} el 
+         * @param {L.Point} offset 
+         * @param {Number} scale
+         * @param {Number} bearing 
+         * @param {L.Point} pivot 
+         */
         setTransform: function(el, offset, scale, bearing, pivot) {
             var pos = offset || new L.Point(0, 0);
 
             if (!bearing) {
                 offset = pos._round();
-                return domUtilProto.setTransform.call(this, el, offset, scale);
+                return domUtilProto.setTransform.apply(this, arguments);
             }
 
             pos = pos.rotateFrom(bearing, pivot);
@@ -29,9 +41,21 @@
                 ' rotate(' + bearing + 'rad)';
         },
 
-        setPosition: function(el, point, bearing, pivot) { // (HTMLElement, Point[, Boolean])
+        /**
+         * Sets the position of `el` to coordinates specified by
+         * `position`, using CSS translate or top/left positioning
+         * depending on the browser (used by Leaflet internally
+         * to position its layers).
+         * 
+         * @param {HTMLElement} el 
+         * @param {L.Point} point 
+         * @param {Number} bearing
+         * @param {L.Point} pivot 
+         * @param {Number} scale 
+         */
+        setPosition: function(el, point, bearing, pivot, scale) {
             if (!bearing) {
-                return domUtilProto.setPosition.call(this, el, point);
+                return domUtilProto.setPosition.apply(this, arguments);
             }
 
             /*eslint-disable */
@@ -39,15 +63,21 @@
             /*eslint-enable */
 
             if (L.Browser.any3d) {
-                L.DomUtil.setTransform(el, point, undefined, bearing, pivot);
+                L.DomUtil.setTransform(el, point, scale, bearing, pivot);
             } else {
                 el.style.left = point.x + 'px';
                 el.style.top = point.y + 'px';
             }
         },
 
-        // Constants for rotation
+        /**
+         * @constant radians = degrees × π/180°
+         */
         DEG_TO_RAD: Math.PI / 180,
+
+        /**
+         * @constant degrees = radians × 180°/π
+         */
         RAD_TO_DEG: 180 / Math.PI,
 
     });
@@ -58,8 +88,15 @@
      * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/dom/Draggable.js
      */
 
+    /**
+     * 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).
+     */
+
     L.Draggable.include({
 
+        /** @TODO */
         // updateMapBearing: function(mapBearing) {
         //     this._mapBearing = mapBearing;
         // },
@@ -94,6 +131,11 @@
          * 3. add (pivot.x, pivot.y) back
          * 
          * same as `this.subtract(pivot).rotate(theta).add(pivot)`
+         * 
+         * @param {Number} theta 
+         * @param {L.Point} pivot 
+         * 
+         * @returns {L.Point}
          */
         rotateFrom: function(theta, pivot) {
             if (!theta) { return this; }
@@ -122,16 +164,23 @@
 
     L.DivOverlay.include({
 
+        /**
+         * Update L.Popup and L.Tooltip anchor positions after
+         * the map is moved by calling `map.setBearing(theta)`
+         * 
+         * @listens L.Map~rotate
+         */
         getEvents: function() {
-            return L.extend(divOverlayProto.getEvents.call(this), { rotate: this._updatePosition });
+            return L.extend(divOverlayProto.getEvents.apply(this, arguments), { rotate: this._updatePosition });
         },
 
+        /**
+         * 0. update element anchor point (divOverlayProto v1.9.3)
+         * 1. rotate around anchor point (subtract anchor -> rotate point -> add anchor)
+         */
         _updatePosition: function() {
-            // 0. update anchor (leaflet v1.9.3)
-            divOverlayProto._updatePosition.call(this);
-            // 1. subtract anchor
-            // 2. rotate element
-            // 3. restore anchor
+            if (!this._map) { return; }
+            divOverlayProto._updatePosition.apply(this, arguments);
             if (this._map && this._map._rotate && this._zoomAnimated) {
                 var anchor = this._getAnchor();
                 var pos = L.DomUtil.getPosition(this._container).subtract(anchor);
@@ -152,12 +201,12 @@
 
     L.Popup.include({
 
+        /**
+         * 0. update element anchor point (popupProto v1.9.3)
+         * 1. rotate around anchor point (subtract anchor -> rotate point -> add anchor)
+         */
         _animateZoom: function(e) {
-            // 0. update anchor (leaflet v1.9.3)
-            popupProto._animateZoom.call(this, e);
-            // 1. subtract anchor
-            // 2. rotate element
-            // 3. restore anchor
+            popupProto._animateZoom.apply(this, arguments);
             if (this._map && this._map._rotate) {
                 var anchor = this._getAnchor();
                 var pos = L.DomUtil.getPosition(this._container).subtract(anchor);
@@ -166,7 +215,7 @@
         },
 
         /**
-         * Hot fix for L.Popup.mergeOptions({ keepInView: true, });
+         * Fix for L.popup({ keepInView = true })
          * 
          * @see https://github.com/fnicollet/Leaflet/pull/21
          */
@@ -188,8 +237,8 @@
 
             layerPos._add(L.DomUtil.getPosition(this._container));
 
-            // var containerPos = map.layerPointToContainerPoint(layerPos);
             /** @TODO use popupProto._adjustPan */
+            // var containerPos = map.layerPointToContainerPoint(layerPos);
             var containerPos = layerPos._add(this._map._getMapPanePos()),
                 padding = L.point(this.options.autoPanPadding),
                 paddingTL = L.point(this.options.autoPanPaddingTopLeft || padding),
@@ -240,7 +289,7 @@
 
         _animateZoom: function(e) {
             if (!this._map._rotate) {
-                return tooltipProto._animateZoom.call(this, e);
+                return tooltipProto._animateZoom.apply(this, arguments);
             }
             var pos = this._map._latLngToNewLayerPoint(this._latlng, e.zoom, e.center);
 
@@ -250,7 +299,7 @@
 
         _updatePosition: function() {
             if (!this._map._rotate) {
-                return tooltipProto._updatePosition.call(this);
+                return tooltipProto._updatePosition.apply(this, arguments);
             }
             var pos = this._map.latLngToLayerPoint(this._latlng);
 
@@ -304,20 +353,35 @@
      * @external L.Handler.MarkerDrag
      * 
      * @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
      */
 
     const markerProto = L.extend({}, L.Marker.prototype);
 
     L.Marker.mergeOptions({
 
-        // @option rotation: Number = 0
-        // Rotation of this marker in rad
+        /**
+         * Rotation of this marker in rad
+         * 
+         * @type {Number}
+         */
         rotation: 0,
 
-        // @option rotateWithView: Boolean = false
-        // Rotate this marker when map rotates
+        /**
+         * Rotate this marker when map rotates
+         * 
+         * @type {Boolean}
+         */
         rotateWithView: false,
 
+        /**
+         * Scale of the marker icon
+         * 
+         * @type {Number}
+         */
+        scale: undefined,
+
     });
 
     var markerDragProto; // retrived at runtime (see below: L.Marker::_initInteraction())
@@ -326,7 +390,7 @@
 
         // _onDragStart: function() {
         //     if (!this._marker._map._rotate) {
-        //         return markerDragProto._onDragStart.call(this)
+        //         return markerDragProto._onDragStart.apply(this, arguments);
         //     }
         //     this._draggable.updateMapBearing(this._marker._map._bearing);
         // },
@@ -369,24 +433,25 @@
             if (this._marker._map._rotate) {
                 this._marker.update();
             }
-            markerDragProto._onDragEnd.call(this, e);
+            markerDragProto._onDragEnd.apply(this, arguments);
         },
 
     };
 
     L.Marker.include({
 
+        /**
+         * Update L.Marker anchor position after the map
+         * is moved by calling `map.setBearing(theta)`
+         * 
+         * @listens L.Map~rotate
+         */
         getEvents: function() {
-            return L.extend(markerProto.getEvents.call(this), { rotate: this.update });
-        },
-
-        onAdd: function(map) {
-            markerProto.onAdd.call(this, map);
-            map.on('rotate', this.update, this);
+            return L.extend(markerProto.getEvents.apply(this, arguments), { rotate: this.update });
         },
 
         _initInteraction: function() {
-            var ret = markerProto._initInteraction.call(this);
+            var ret = markerProto._initInteraction.apply(this, arguments);
             if (this.dragging && this.dragging.enabled() && this._map && this._map._rotate) {
                 // L.Handler.MarkerDrag is used internally by L.Marker to make the markers draggable
                 markerDragProto = markerDragProto || Object.getPrototypeOf(this.dragging);
@@ -416,12 +481,12 @@
 
             /** @TODO use markerProto._setPos */
             if (this._icon) {
-                L.DomUtil.setPosition(this._icon, pos, bearing, pos);
+                L.DomUtil.setPosition(this._icon, pos, bearing, pos, this.options.scale);
             }
 
             /** @TODO use markerProto._setPos */
             if (this._shadow) {
-                L.DomUtil.setPosition(this._shadow, pos, bearing, pos);
+                L.DomUtil.setPosition(this._shadow, pos, bearing, pos, this.options.scale);
             }
 
             this._zIndex = pos.y + this.options.zIndexOffset;
@@ -429,12 +494,12 @@
             this._resetZIndex();
         },
 
-        _updateZIndex: function(offset) {
-            if (!this._map._rotate) {
-                return markerProto._updateZIndex.call(this, offset)
-            }
-            this._icon.style.zIndex = Math.round(this._zIndex + offset);
-        },
+        // _updateZIndex: function(offset) {
+        //     if (!this._map._rotate) {
+        //         return markerProto._updateZIndex.apply(this, arguments);
+        //     }
+        //     this._icon.style.zIndex = Math.round(this._zIndex + offset);
+        // },
 
         setRotation: function(rotation) {
             this.options.rotation = rotation;
@@ -453,8 +518,14 @@
 
     L.GridLayer.include({
 
+        /**
+         * Redraw L.TileLayer bounds after the map is
+         * moved by just calling `map.setBearing(theta)`
+         * 
+         * @listens L.Map~rotate
+         */
         getEvents: function() {
-            var events = gridLayerProto.getEvents.call(this);
+            var events = gridLayerProto.getEvents.apply(this, arguments);
             if (this._map._rotate && !this.options.updateWhenIdle) {
                 if (!this._onRotate) {
                     this._onRotate = L.Util.throttle(this._onMoveEnd, this.options.updateInterval, this);
@@ -466,7 +537,7 @@
 
         _getTiledPixelBounds: function(center) {
             if (!this._map._rotate) {
-                return gridLayerProto._getTiledPixelBounds.call(this, center);
+                return gridLayerProto._getTiledPixelBounds.apply(this, arguments);
             }
 
             return this._map._getNewPixelBounds(center, this._tileZoom);
@@ -474,35 +545,6 @@
 
     });
 
-    /**
-     * @external L.Canvas
-     * 
-     * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/layer/vector/Canvas.js
-     */
-
-    L.extend({}, L.Canvas.prototype);
-
-    L.Canvas.include({
-
-        // onAdd: function() {
-        //     canvasProto.onAdd.call(this);
-        //     // When rotating the canvas itself, it is cleared by some weird reason, so redraw.
-        //     this._map.on('rotate', this._redraw, this);
-        // },
-
-        // onRemove: function() {
-        //     canvasProto.onRemove.call(this);
-        //     this._map.off('rotate', this._redraw, this);
-        // },
-
-        // _update: function() {
-        //     canvasProto._update.call(this);
-        //     // Tell paths to redraw themselves
-        //     this.fire('update')
-        // },
-
-    });
-
     /**
      * @external L.Renderer
      * 
@@ -513,15 +555,15 @@
 
     L.Renderer.include({
 
-        // onAdd: function() {
-        //     rendererProto.onAdd.call(this);
-        //     // this._map.on('rotate', this._update, this);
-        // },
-
-        // onRemove: function() {
-        //     rendererProto.onRemove.call(this);
-        //     // this._map.off('rotate', this._update, this);
-        // },
+        /**
+         * Redraw L.Canvas and L.SVG renderer bounds after the
+         * map is moved by just calling `map.setBearing(theta)`
+         * 
+         * @listens L.Map~rotate
+         */
+        getEvents: function() {
+            return L.extend(rendererProto.getEvents.apply(this, arguments), { rotate: this._update });
+        },
 
         /**
          * @TODO rechek this changes from leaflet@v1.9.3
@@ -530,7 +572,7 @@
          */
         _updateTransform: function(center, zoom) {
             if (!this._map._rotate) {
-                return rendererProto._updateTransform.call(this, center, zoom);
+                return rendererProto._updateTransform.apply(this, arguments);
             }
             var scale = this._map.getZoomScale(zoom, this._zoom),
                 offset = this._map._latLngToNewLayerPoint(this._topLeft, zoom, center);
@@ -543,7 +585,7 @@
 
         _update: function() {
             if (!this._map._rotate) {
-                return rendererProto._update.call(this);
+                return rendererProto._update.apply(this, arguments);
             }
             // Update pixel bounds of renderer container (for positioning/sizing/clipping later)
             // Subclasses are responsible of firing the 'update' event.
@@ -555,25 +597,6 @@
 
     });
 
-    /**
-     * @external L.SVG
-     * 
-     * @see https://github.com/Leaflet/Leaflet/tree/v1.9.3/src/layer/vector/SVG.js
-     */
-
-    L.extend({}, L.SVG.prototype);
-
-    L.SVG.include({
-
-        // _update: function() {
-        //     svgProto._update.call(this);
-        //     if (this._map._rotate) {
-        //         this.fire('update');
-        //     }
-        // },
-
-    });
-
     /**
      * @external L.Map
      * 
@@ -595,7 +618,7 @@
                 this._rotate = true;
                 this._bearing = 0;
             }
-            mapProto.initialize.call(this, id, options);
+            mapProto.initialize.apply(this, arguments);
             if(this.options.rotate){
               this.setBearing(this.options.bearing);
             }
@@ -611,7 +634,7 @@
          */
         containerPointToLayerPoint: function(point) {
             if (!this._rotate) {
-                return mapProto.containerPointToLayerPoint.call(this, point);
+                return mapProto.containerPointToLayerPoint.apply(this, arguments);
             }
             return L.point(point)
                 .subtract(this._getMapPanePos())
@@ -626,9 +649,9 @@
          * @param {L.Point} point pixel screen coordinates
          * @returns {L.Point} transformed pixel point
          */
-        layerPointToContainerPoint: function(point) { // (Point)
+        layerPointToContainerPoint: function(point) {
             if (!this._rotate) {
-                return mapProto.layerPointToContainerPoint.call(this, point);
+                return mapProto.layerPointToContainerPoint.apply(this, arguments);
             }
             return L.point(point)
                 .add(this._getRotatePanePos())
@@ -645,6 +668,8 @@
          * 
          * @param {L.Point} point pixel screen coordinates
          * @returns {L.Point}
+         * 
+         * @since leaflet-rotate (v0.1)
          */
         rotatedPointToMapPanePoint: function(point) {
             return L.point(point)
@@ -660,6 +685,8 @@
          * (norotatePane) --> (rotatePane)
          * 
          * @param {L.Point} point pixel screen coordinates
+         * 
+         * @since leaflet-rotate (v0.1)
          */
         mapPanePointToRotatedPoint: function(point) {
             return L.point(point)
@@ -667,6 +694,31 @@
                 .rotate(-this._bearing);
         },
 
+        /**
+         * Given latlng bounds, returns the bounds in projected pixel
+         * relative to the map container.
+         * 
+         * @see https://github.com/ronikar/Leaflet/blob/5c480ef959b947c3beed7065425a5a36c486262b/src/map/Map.js#L1114-L1135
+         * 
+         * @param {L.LatLngBounds} bounds 
+         * @returns {L.Bounds}
+         * 
+         * @since leaflet-rotate (v0.2)
+         */
+        mapBoundsToContainerBounds: function (bounds) {
+            if (!this._rotate && mapProto.mapBoundsToContainerBounds) {
+                return mapProto.mapBoundsToContainerBounds.apply(this, arguments);
+            }
+            const nw = this.latLngToContainerPoint(bounds.getNorthWest()),
+                ne = this.latLngToContainerPoint(bounds.getNorthEast()),
+                sw = this.latLngToContainerPoint(bounds.getSouthWest()),
+                se = this.latLngToContainerPoint(bounds.getSouthEast());
+            return L.bounds([
+                L.point(Math.min(nw.x, ne.x, se.x, sw.x), Math.min(nw.y, ne.y, se.y, sw.y)), // [ minX, minY ]
+                L.point(Math.max(nw.x, ne.x, se.x, sw.x), Math.max(nw.y, ne.y, se.y, sw.y))  // [ maxX, maxY ]
+            ]);
+        },
+
         /**
          * Returns geographical bounds visible in the current map view
          * 
@@ -679,7 +731,7 @@
          */
         getBounds: function() {
             if (!this._rotate) {
-                return mapProto.getBounds.call(this);
+                return mapProto.getBounds.apply(this, arguments);
             }
 
             // SEE: https://github.com/fnicollet/Leaflet/pull/22
@@ -722,6 +774,8 @@
          * Change map rotation
          * 
          * @param {number} theta map degrees
+         * 
+         * @since leaflet-rotate (v0.1)
          */
         setBearing: function(theta) {
             if (!L.Browser.any3d || !this._rotate) { return; }
@@ -745,6 +799,8 @@
          * Get current map rotation
          * 
          * @returns {number} theta map degrees
+         * 
+         * @since leaflet-rotate (v0.1)
          */
         getBearing: function() {
             return this._bearing * L.DomUtil.RAD_TO_DEG;
@@ -761,7 +817,7 @@
          */
         // createPane: function(name, container) {
         //     if (!this._rotate || name == 'mapPane') {
-        //         return mapProto.createPane.call(this, name, container);
+        //         return mapProto.createPane.apply(this, arguments);
         //     }
         //     // init "rotatePane"
         //     if (!this._rotatePane) {
@@ -884,15 +940,108 @@
         //     this._enforcingBounds = true;
         //     var center = this.getCenter(),
         //         newCenter = this._limitCenter(center, this._zoom, L.latLngBounds(bounds));
-
+        //
         //     if (!center.equals(newCenter)) {
         //         this.panTo(newCenter, options);
         //     }
-
+        //
         //     this._enforcingBounds = false;
         //     return this;
         // },
 
+        // adjust center for view to get inside bounds
+        // _limitCenter(center, zoom, bounds) {
+        //
+        //     if (!bounds) { return center; }
+        //
+        //     const centerPoint = this.project(center, zoom),
+        //         viewHalf = this.getSize().divideBy(2),
+        //         viewBounds = new Bounds(centerPoint.subtract(viewHalf), centerPoint.add(viewHalf)),
+        //         offset = this._getBoundsOffset(viewBounds, bounds, zoom);
+        //
+        //     // If offset is less than a pixel, ignore.
+        //     // This prevents unstable projections from getting into
+        //     // an infinite loop of tiny offsets.
+        //     if (Math.abs(offset.x) <= 1 && Math.abs(offset.y) <= 1) {
+        //             return center;
+        //     }
+        //
+        //     return this.unproject(centerPoint.add(offset), zoom);
+        // },
+
+        // @method flyToBounds(bounds: LatLngBounds, options?: fitBounds options): this
+        // Sets the view of the map with a smooth animation like [`flyTo`](#map-flyto),
+        // but takes a bounds parameter like [`fitBounds`](#map-fitbounds).
+        // flyToBounds(bounds, options) {
+        //     const target = this._getBoundsCenterZoom(bounds, options);
+        //     return this.flyTo(target.center, target.zoom, options);
+        // },
+
+        // _getBoundsCenterZoom(bounds, options) {
+        //
+        //     options = options || {};
+        //     bounds = bounds.getBounds ? bounds.getBounds() : toLatLngBounds(bounds);
+        //
+        //     const paddingTL = L.point(options.paddingTopLeft || options.padding || [0, 0]),
+        //           paddingBR = L.point(options.paddingBottomRight || options.padding || [0, 0]);
+        //
+        //     let zoom = this.getBoundsZoom(bounds, false, paddingTL.add(paddingBR));
+        //
+        //     zoom = (typeof options.maxZoom === 'number') ? Math.min(options.maxZoom, zoom) : zoom;
+        //
+        //     if (zoom === Infinity) {
+        //         return { center: bounds.getCenter(), zoom };
+        //     }
+        //
+        //     return { center, zoom };
+        //
+        // },
+
+        /**
+         * Returns the maximum zoom level on which the given bounds fit to the map
+         * view in its entirety. If `inside` (optional) is set to `true`, the method
+         * 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]]
+         * 
+         * @returns {Number} zoom level
+         */
+        getBoundsZoom(bounds, inside, padding) {
+            if (!this._rotate || Math.abs(this._bearing).toFixed(1) < 0.1) {
+                return mapProto.getBoundsZoom.apply(this, arguments);
+            }
+
+            bounds = L.latLngBounds(bounds);
+            padding = L.point(padding || [0, 0]);
+
+            let zoom = this.getZoom() || 0;
+            const min = this.getMinZoom(),
+                    max = this.getMaxZoom(),
+                    /** @TODO use mapProto.getBoundsZoom */
+                    // nw = bounds.getNorthWest(),
+                    // se = bounds.getSouthEast(),
+                    // size = this.getSize().subtract(padding),
+                    // boundsSize = L.bounds(this.project(se, zoom), this.project(nw, zoom)).getSize(),
+                    size = this.getSize().subtract(padding),
+                    boundsSize = this.mapBoundsToContainerBounds(bounds).getSize(),
+                    snap = this.options.zoomSnap,
+                    scalex = size.x / boundsSize.x,
+                    scaley = size.y / boundsSize.y,
+                    scale = inside ? Math.max(scalex, scaley) : Math.min(scalex, scaley);
+
+            zoom = this.getScaleZoom(scale, zoom);
+
+            if (snap) {
+                zoom = Math.round(zoom / (snap / 100)) * (snap / 100); // don't jump if within 1% of a snap level
+                zoom = inside ? Math.ceil(zoom / snap) * snap : Math.floor(zoom / snap) * snap;
+            }
+
+            return Math.max(min, Math.min(max, zoom));
+        },
+
         /**
          * Layer point of the current center
          * 
@@ -908,13 +1057,16 @@
          * @param {L.LatLng} latlng map coordinates
          */
         _getCenterOffset: function(latlng) {
-            var centerOffset = mapProto._getCenterOffset.call(this, latlng);
+            var centerOffset = mapProto._getCenterOffset.apply(this, arguments);
             if (this._rotate) {
                 centerOffset = centerOffset.rotate(this._bearing);
             }
             return centerOffset;
         },
 
+        /**
+         * @since leaflet-rotate (v0.1)
+         */
         _getRotatePanePos: function() {
             return this._rotatePanePos || new L.Point(0, 0);
             // return L.DomUtil.getPosition(this._rotatePane) || new L.Point(0, 0);
@@ -923,7 +1075,7 @@
         _getNewPixelOrigin: function(center, zoom) {
             var viewHalf = this.getSize()._divideBy(2);
             if (!this._rotate) {
-                return mapProto._getNewPixelOrigin.call(this, center, zoom);
+                return mapProto._getNewPixelOrigin.apply(this, arguments);
             }
             return this.project(center, zoom)
                 .rotate(this._bearing)
@@ -1030,39 +1182,6 @@
             this.fire('locationfound', data);
         },
 
-        /**
-         * Given latlng bounds, returns the bounds in projected pixel
-         * relative to the map container.
-         * 
-         * @see https://github.com/ronikar/Leaflet/blob/5c480ef959b947c3beed7065425a5a36c486262b/src/map/Map.js#L1114-L1135
-         * 
-         * @param {L.LatLngBounds} bounds 
-         * @returns {L.Bounds}
-         */
-        // boundsToContainerBounds: function (bounds) {
-        //     if (this._rotate) {
-        //         var northWest = this.latLngToContainerPoint(bounds.getNorthWest());
-        //         var northEast = this.latLngToContainerPoint(bounds.getNorthEast());
-        //         var southWest = this.latLngToContainerPoint(bounds.getSouthWest());
-        //         var southEast = this.latLngToContainerPoint(bounds.getSouthEast());
-        //
-        //         var minX = Math.min(northWest.x, northEast.x, southEast.x, southWest.x);
-        //         var maxX = Math.max(northWest.x, northEast.x, southEast.x, southWest.x);
-        //         var minY = Math.min(northWest.y, northEast.y, southEast.y, southWest.y);
-        //         var maxY = Math.max(northWest.y, northEast.y, southEast.y, southWest.y);
-        //
-        //         return L.bounds(
-        //             L.point(minX, minY).multiplyBy(-1),
-        //             L.point(maxX, maxY).multiplyBy(-1).add(this.getSize())
-        //         );
-        //     } else {
-        //         return L.Bounds(
-        //             this.latLngToContainerPoint(bounds.getNorthWest()).multiplyBy(-1),
-        //             this.latLngToContainerPoint(bounds.getSouthEast()).multiplyBy(-1).add(this.getSize())
-        //         );
-        //     }
-        // },
-
         /**
          * @see https://github.com/ronikar/Leaflet/blob/5c480ef959b947c3beed7065425a5a36c486262b/src/geo/LatLngBounds.js#L253-L264
          * 
@@ -1113,9 +1232,11 @@
 
     });
 
-    // @section Handlers
-    // @property compassBearing: Handler
-    // Compass bearing handler.
+    /**
+     * Add Compass bearing handler to L.Map (disabled unless `window.DeviceOrientationEvent` is set).
+     * 
+     * @property {L.Map.CompassBearing} compassBearing
+     */
     L.Map.addInitHook('addHandler', 'compassBearing', L.Map.CompassBearing);
 
     /**
@@ -1124,14 +1245,23 @@
      * @typedef L.Map.ContainerMutation
      */
 
-    // @namespace Map
-    // @section Interaction Options
+    /**
+     * @TODO check again this file after leaflet v1.9.3 (eg. L.Browser.mutation).
+     * Mutation Observer support will likely be added by default in next releases.
+     */
+
     L.Map.mergeOptions({
 
-        // @option trackContainerMutation: Boolean = false
-        // Whether the map uses [mutation observers](https://developer.mozilla.org/docs/Web/API/MutationObserver)
-        // to detect changes in its container and trigger `invalidateSize`. Disabled
-        // by default due to support not being available in all web browsers.
+        /**
+         * Whether the map uses mutation observers to
+         * detect changes in its container and trigger
+         * `invalidateSize`. Disabled by default due to
+         * support not being available in all web browsers.
+         *
+         * @type {Boolean}
+         * 
+         * @see https://developer.mozilla.org/docs/Web/API/MutationObserver
+         */
         trackContainerMutation: false
 
     });
@@ -1139,15 +1269,10 @@
     L.Map.ContainerMutation = L.Handler.extend({
 
         addHooks: function() {
-            /** @TODO check again this property. Will likely be added in future releases (leaflet > v1.9.3) */
-            // if (!L.Browser.mutation) {
-            //     return;
-            // }
-
+            // if (!L.Browser.mutation) { return; }
             if (!this._observer) {
-                this._observer = new MutationObserver(L.Util.bind(this._onMutation, this));
+                this._observer = new MutationObserver(L.Util.bind(this._map.invalidateSize, this._map));
             }
-
             this._observer.observe(this._map.getContainer(), {
                 childList: false,
                 attributes: true,
@@ -1158,22 +1283,17 @@
         },
 
         removeHooks: function() {
-            /** @TODO check again this property. Will likely be added in future releases (leaflet > v1.9.3) */
-            // if (!L.Browser.mutation) {
-            //     return;
-            // }
+            // if (!L.Browser.mutation) { return; }
             this._observer.disconnect();
         },
 
-        _onMutation: function() {
-            this._map.invalidateSize();
-        },
-
     });
 
-    // @section Handlers
-    // @property containerMutation: Handler
-    // Container mutation handler (disabled unless [`trackContainerMutation`](#map-trackcontainermutation) is set).
+    /**
+     * Add Container mutation handler to L.Map (disabled unless `trackContainerMutation` is set).
+     * 
+     * @property {L.Map.ContainerMutation} trackContainerMutation
+     */
     L.Map.addInitHook('addHandler', 'trackContainerMutation', L.Map.ContainerMutation);
 
     /**
@@ -1185,13 +1305,15 @@
      * @typedef L.Map.TouchGestures
      */
 
-    // @namespace Map
-    // @section Interaction Options
     L.Map.mergeOptions({
 
-        // @option bounceAtZoomLimits: Boolean = true
-        // Set it to false if you don't want the map to zoom beyond min/max zoom
-        // and then bounce back when pinch-zooming.
+        /**
+         * Set it to false if you don't want the map to
+         * zoom beyond min/max zoom and then bounce back
+         * when pinch-zooming.
+         * 
+         * @type {Boolean}
+         */
         bounceAtZoomLimits: true,
 
     });
@@ -1270,8 +1392,14 @@
                 var bearingDelta = (theta - this._startTheta) * L.DomUtil.RAD_TO_DEG;
                 if (vector.y < 0) { bearingDelta += 180; }
                 if (bearingDelta) {
-                    /// TODO: The pivot should be the last touch point, but zoomAnimation manages to
-                    ///   overwrite the rotate pane position. Maybe related to #3529.
+                    /**
+                     * @TODO the pivot should be the last touch point,
+                     * but zoomAnimation manages to overwrite the rotate
+                     * pane position. Maybe related to #3529.
+                     * 
+                     * @see https://github.com/Leaflet/Leaflet/pull/3529
+                     * @see https://github.com/fnicollet/Leaflet/commit/a77af51a6b10f308d1b9a16552091d1d0aee8834
+                     */
                     map.setBearing(this._startBearing - bearingDelta);
                 }
             }
@@ -1339,9 +1467,11 @@
 
     });
 
-    // @section Handlers
-    // @property touchGestures: Handler
-    // Touch gestures handler.
+    /**
+     * Add Touch Gestures handler (enabled unless `touchGestures` is unset).
+     * 
+     * @property {L.Map.TouchGestures} touchGestures
+     */
     L.Map.addInitHook('addHandler', 'touchGestures', L.Map.TouchGestures);
 
     /**
@@ -1350,13 +1480,13 @@
      * @typedef L.Map.TouchRotate
      */
 
-    // @namespace Map
-    // @section Interaction Options
     L.Map.mergeOptions({
 
-        // @section Touch interaction options
-        // @option touchRotate: Boolean|String = *
-        // Whether the map can be rotated with a two-finger rotation gesture
+        /**
+         * Whether the map can be rotated with a two-finger rotation gesture
+         * 
+         * @type {Boolean}
+         */
         touchRotate: false,
 
     });
@@ -1374,24 +1504,25 @@
 
     });
 
-    // @section Handlers
-    // @property touchZoom: Handler
-    // Touch rotate handler.
+    /**
+     * Add Touch Rotate handler (disabled unless `touchGestures` is set).
+     * 
+     * @property {L.Map.TouchGestures} touchGestures
+     */
     L.Map.addInitHook('addHandler', 'touchRotate', L.Map.TouchRotate);
 
     /**
-     * Rotates the map on shift key + mouseheel scrolling (desktop).
+     * Rotates the map on shift key + mousewheel scrolling (desktop).
      * 
      * @typedef L.Map.ShiftKeyRotate
      */
 
-    // @namespace Map
-    // @section Interaction Options
     L.Map.mergeOptions({
 
-        // @section ShiftKey interaction options
-        // @option shiftKeyRotate: Boolean|String = *
-        // Whether the map can be rotated with a shit-wheel rotation
+        /**
+         * Whether the map can be rotated with shift + wheel scroll
+         * @type {Boolean}
+         */
         shiftKeyRotate: true,
 
     });
@@ -1421,12 +1552,14 @@
 
     });
 
-    // @section Handlers
-    // @property touchZoom: Handler
-    // Touch rotate handler.
+    /**
+     * Add ShiftKey handler to L.Map (enabled unless `shiftKeyRotate` is unset).
+     * 
+     * @property {L.Map.ShiftKeyRotate} shiftKeyRotate
+     */
     L.Map.addInitHook('addHandler', 'shiftKeyRotate', L.Map.ShiftKeyRotate);
 
-    // decrease "scrollWheelZoom" handler priority over "shiftKeyRotate" handler
+    // decrease `scrollWheelZoom` handler priority over `shiftKeyRotate` handler
     L.Map.addInitHook(function() {
         if (this.scrollWheelZoom.enabled() && this.shiftKeyRotate.enabled()) {
             this.scrollWheelZoom.disable();
@@ -1442,25 +1575,32 @@
      * @external L.Map.TouchZoom
      */
 
-    // @namespace Map
-    // @section Interaction Options
     L.Map.mergeOptions({
 
-        // @section Touch interaction options
-        // @option touchZoom: Boolean|String = *
-        // Whether the map can be zoomed by touch-dragging with two fingers. If
-        // passed `'center'`, it will zoom to the center of the view regardless of
-        // where the touch events (fingers) were. Enabled for touch-capable web
-        // browsers.
+        /**
+         * Whether the map can be zoomed by touch-dragging
+         * with two fingers. If passed `'center'`, it will
+         * zoom to the center of the view regardless of
+         * where the touch events (fingers) were. Enabled
+         * for touch-capable web browsers.
+         * 
+         * @type {(Boolean|String)}
+         */
         touchZoom: L.Browser.touch,
 
         /**
-         * @TODO check if this is a duplicate of `L.Map.TouchGestures::bounceAtZoomLimits`
+         * 
          */
 
-        // @option bounceAtZoomLimits: Boolean = true
-        // Set it to false if you don't want the map to zoom beyond min/max zoom
-        // and then bounce back when pinch-zooming.
+        /**
+         * @TODO check if this is a duplicate of `L.Map.TouchGestures::bounceAtZoomLimits`
+         * 
+         * Set it to false if you don't want the map to
+         * zoom beyond min/max zoom and then bounce back
+         * when pinch-zooming.
+         * 
+         * @type {Boolean}
+         */
         bounceAtZoomLimits: false,
 
     });
@@ -1480,9 +1620,11 @@
 
     });
 
-    // @section Handlers
-    // @property touchZoom: Handler
-    // Touch zoom handler.
+    /**
+     * Add Touch Zoom handler (disabled unless `L.Browser.touch` is set).
+     * 
+     * @property {L.Map.TouchGestures} touchGestures
+     */
     L.Map.addInitHook('addHandler', 'touchZoom', L.Map.TouchZoom);
 
     /**