leaflet-rotate 0.4.0 → 0.5.0

package/src/map/Map.js

@@ -1,17 +1,64 @@
 /**
+ * Extends Leaflet maps with bearing rotation and 3D pitch.
+ *
  * @external L.Map
  * 
+ * @since leaflet-rotate (v0.1.0)
+ * 
  * @see https://github.com/Leaflet/Leaflet/blob/v1.9.3/src/map/Map.js
  */
 
+/**
+ * @event L.Map#rotate Fired after the map bearing changes.
+ * 
+ * @since leaflet-rotate (v0.1.0)
+ */
+
+/**
+ * @event L.Map#pitch Fired after the map pitch changes.
+ * 
+ * @since leaflet-rotate (0.5.0)
+ */
+
 import { toPoint } from '../geometry/Point';
 
 const 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; }
 
@@ -23,17 +70,24 @@ L.Map.include({
     },
 
     /**
-     * @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.setBearing(this.options.bearing);
+        if (this.options.rotate) {
+            this.on('resize', this._updatePitchTransform, this);
+            this.setBearing(this.options.bearing);
+            this.setPitch(this.options.pitch);
         }
     },
 
@@ -42,13 +96,22 @@ L.Map.include({
      * 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())
@@ -59,13 +122,19 @@ L.Map.include({
      * 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())
@@ -79,12 +148,16 @@ L.Map.include({
      * (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());
@@ -97,11 +170,16 @@ L.Map.include({
      * (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);
@@ -122,10 +200,11 @@ L.Map.include({
      * 
      * @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.
+     * 
+     * @returns {L.Bounds} Axis-aligned bounds in container-pixel coordinates.
      * 
-     * @since leaflet-rotate (v0.2)
+     * @since leaflet-rotate (v0.2.0)
      */
     mapBoundsToContainerBounds(bounds) {
         if (!this._rotate && mapProto.mapBoundsToContainerBounds) {
@@ -151,14 +230,13 @@ L.Map.include({
     },
 
     /**
-     * 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) {
@@ -202,15 +280,19 @@ L.Map.include({
     // },
 
     /**
-     * Change map rotation
+     * Set the map bearing, optionally animating to the new value.
      * 
-     * @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]
+     * @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.
      * 
-     * @since leaflet-rotate (v0.1)
+     * @returns {void}
+     * 
+     * @fires L.Map#rotate
+     * 
+     * @since leaflet-rotate (v0.1.0)
      */
     setBearing(theta, options) {
         if (!this._rotate) { return; }
@@ -260,28 +342,169 @@ L.Map.include({
         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);
 
-        // CSS transform
-        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() : undefined;
+        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);
@@ -294,7 +517,10 @@ L.Map.include({
      * 
      * @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') {
@@ -325,6 +551,12 @@ L.Map.include({
      * - 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 = {};
@@ -369,13 +601,15 @@ L.Map.include({
      * 
      * @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);
         }
 
@@ -419,9 +653,12 @@ L.Map.include({
      *
      * @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;
@@ -490,14 +727,16 @@ L.Map.include({
      * 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
+     * @returns {number} Zoom level satisfying the fit.
+     * 
+     * @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);
         }
 
@@ -539,20 +778,32 @@ L.Map.include({
     // },
 
     /**
-     * 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 Geographic point.
      * 
-     * @param {L.LatLng} latlng map coordinates
+     * @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);
@@ -564,6 +815,16 @@ L.Map.include({
     //    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);
@@ -579,7 +840,14 @@ L.Map.include({
     },
 
     /**
-     * @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()
      */
@@ -604,9 +872,9 @@ L.Map.include({
     },
 
     /**
-     * @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) {
@@ -616,9 +884,13 @@ L.Map.include({
     },
 
     /**
-     * @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) {
@@ -638,6 +910,15 @@ L.Map.include({
         ]);
     },
 
+    /**
+     * 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; }
 
@@ -678,6 +959,7 @@ L.Map.include({
      * @see https://github.com/ronikar/Leaflet/blob/5c480ef959b947c3beed7065425a5a36c486262b/src/geo/LatLngBounds.js#L253-L264
      * 
      * @param {L.Bounds} points 
+     * 
      * @returns {L.Bounds}
      */
     // toCircumscribedBounds(points) {

package/src/map/handler/CompassBearing.js

@@ -1,11 +1,19 @@
 /**
- * Rotates the map according to a smartphone's compass.
+ * Sets map bearing from device orientation when the browser exposes compass data.
  * 
  * @typedef L.Map.CompassBearing
+ * @property {L.Map.CompassBearing} compassBearing Map handler, enabled to follow device heading.
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 
 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;
         /** @see https://caniuse.com/?search=DeviceOrientation */
@@ -17,6 +25,11 @@ L.Map.CompassBearing = L.Handler.extend({
         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);
@@ -27,6 +40,11 @@ L.Map.CompassBearing = L.Handler.extend({
         }
     },
 
+    /**
+     * 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);
@@ -34,6 +52,8 @@ L.Map.CompassBearing = L.Handler.extend({
     },
 
     /**
+     * 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.
@@ -50,6 +70,10 @@ L.Map.CompassBearing = L.Handler.extend({
      * @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;
@@ -76,5 +100,7 @@ L.Map.CompassBearing = L.Handler.extend({
  * Add Compass bearing handler to L.Map (disabled unless `window.DeviceOrientationEvent` is set).
  * 
  * @property {L.Map.CompassBearing} compassBearing
+ * 
+ * @since leaflet-rotate (v0.1.0)
  */
 L.Map.addInitHook('addHandler', 'compassBearing', L.Map.CompassBearing);