feat: add compass accuracy threshold for iOS (#422)

Introduce compassAccuracyThreshold option (default 45, in degrees) to filter inaccurate iOS compass readings using webkitCompassAccuracy. Uncalibrated readings (-1) are always rejected. Set to false to disable filtering. Has no effect on Android, which exposes no standardized accuracy field.

Adds tests for accuracy filtering behavior and a TypeScript declaration for the new option.

Refs #332

Author: KristjanESPERANTO

README.md

@@ -104,6 +104,7 @@ Possible options are listed in the following table. More details are [in the cod
 | `returnToPrevBounds` | `boolean`  | If set, save the map bounds just before centering to the user's location. When control is disabled, set the view back to the bounds that were saved. | `false` |
 | `cacheLocation` | `boolean` | Keep a cache of the location after the user deactivates the control. If set to false, the user has to wait until the locate API returns a new location before they see where they are again. | `true` |
 | `showCompass` | `boolean` | Show the compass bearing on top of the location marker | `true` |
+| `compassAccuracyThreshold` | `number` or `false` | Maximum allowed iOS compass accuracy in degrees (`webkitCompassAccuracy`) for displaying the compass. `-1` (uncalibrated) is always rejected. Set to `false` to always show the compass when heading data is available. | `45` |
 | `drawCircle` | `boolean`  | If set, a circle that shows the location accuracy is drawn. | `true` |
 | `drawMarker` | `boolean`  | If set, the marker at the users' location is drawn. | `true` |
 | `markerClass` | `class`  | The class to be used to create the marker. | `LocationMarker` |

spec/L.Control.Locate.spec.js

@@ -605,6 +605,89 @@ describe("LocateControl", () => {
       assert.strictEqual(control._compassHeading, 0, "Should treat 0 as a valid iOS heading");
     });
 
+    describe("iOS compass accuracy filter (compassAccuracyThreshold)", () => {
+      it("should reject uncalibrated iOS readings (webkitCompassAccuracy === -1) with default threshold", () => {
+        const control = new LocateControl({ showCompass: true });
+        map.addControl(control);
+        control._active = true;
+        control._compassHeading = 123;
+
+        control._onDeviceOrientation({ webkitCompassHeading: 90, webkitCompassAccuracy: -1, alpha: null });
+
+        assert.strictEqual(control._compassHeading, null, "Uncalibrated reading should clear compass");
+      });
+
+      it("should reject iOS readings above default threshold (45)", () => {
+        const control = new LocateControl({ showCompass: true });
+        map.addControl(control);
+        control._active = true;
+
+        control._onDeviceOrientation({ webkitCompassHeading: 90, webkitCompassAccuracy: 50, alpha: null });
+
+        assert.strictEqual(control._compassHeading, null, "Inaccurate reading should be rejected");
+      });
+
+      it("should accept iOS readings within default threshold", () => {
+        const control = new LocateControl({ showCompass: true });
+        map.addControl(control);
+        control._active = true;
+
+        control._onDeviceOrientation({ webkitCompassHeading: 90, webkitCompassAccuracy: 10, alpha: null });
+
+        assert.strictEqual(control._compassHeading, 90, "Accurate reading should pass through");
+      });
+
+      it("should respect custom compassAccuracyThreshold", () => {
+        const control = new LocateControl({ showCompass: true, compassAccuracyThreshold: 5 });
+        map.addControl(control);
+        control._active = true;
+
+        control._onDeviceOrientation({ webkitCompassHeading: 90, webkitCompassAccuracy: 10, alpha: null });
+
+        assert.strictEqual(control._compassHeading, null, "Reading above custom threshold should be rejected");
+      });
+
+      it("should disable filter when compassAccuracyThreshold is false", () => {
+        const control = new LocateControl({ showCompass: true, compassAccuracyThreshold: false });
+        map.addControl(control);
+        control._active = true;
+
+        control._onDeviceOrientation({ webkitCompassHeading: 90, webkitCompassAccuracy: -1, alpha: null });
+
+        assert.strictEqual(control._compassHeading, 90, "Filter disabled: even uncalibrated reading passes through");
+      });
+
+      it("should disable filter when compassAccuracyThreshold is not a number", () => {
+        const control = new LocateControl({ showCompass: true, compassAccuracyThreshold: null });
+        map.addControl(control);
+        control._active = true;
+
+        control._onDeviceOrientation({ webkitCompassHeading: 90, webkitCompassAccuracy: 99, alpha: null });
+
+        assert.strictEqual(control._compassHeading, 90, "Non-numeric threshold should disable filtering, not block all readings");
+      });
+
+      it("should pass through iOS readings when webkitCompassAccuracy is missing", () => {
+        const control = new LocateControl({ showCompass: true });
+        map.addControl(control);
+        control._active = true;
+
+        control._onDeviceOrientation({ webkitCompassHeading: 45, alpha: null });
+
+        assert.strictEqual(control._compassHeading, 45, "Missing accuracy field should not block reading (backward compatible)");
+      });
+
+      it("should not affect Android readings (alpha-based)", () => {
+        const control = new LocateControl({ showCompass: true, compassAccuracyThreshold: 5 });
+        map.addControl(control);
+        control._active = true;
+
+        control._onDeviceOrientation({ alpha: 90, absolute: true });
+
+        assert.strictEqual(control._compassHeading, 270, "Android reading should not be filtered");
+      });
+    });
+
     it("should compensate iOS heading with screen orientation angle", () => {
       const control = new LocateControl({ showCompass: true });
       map.addControl(control);

src/L.Control.Locate.d.ts

@@ -41,6 +41,7 @@ export interface LocateOptions extends ControlOptions {
   drawCircle?: boolean | undefined;
   drawMarker?: boolean | undefined;
   showCompass?: boolean | undefined;
+  compassAccuracyThreshold?: number | false | undefined;
   markerClass?: any;
   compassClass?: any;
   circleStyle?: PathOptions | undefined;

src/L.Control.Locate.js

@@ -274,6 +274,13 @@ const LocateControl = Control.extend({
     drawMarker: true,
     /** If set and supported then show the compass heading */
     showCompass: true,
+    /**
+     * iOS-only compass accuracy threshold (degrees).
+     * Show compass only when `webkitCompassAccuracy <= value`.
+     * `-1` (uncalibrated) is always rejected.
+     * Set to `false` to disable filtering. No effect on Android.
+     */
+    compassAccuracyThreshold: 45,
     /** The class to be used to create the marker. For example L.CircleMarker or L.Marker */
     markerClass: LocationMarker,
     /** The class us be used to create the compass bearing arrow */
@@ -899,7 +906,10 @@ const LocateControl = Control.extend({
   },
 
   /**
-   * Process and normalise compass events
+   * Process and normalise compass events.
+   *
+   * On iOS, optionally filters out inaccurate readings based on `compassAccuracyThreshold`.
+   * Android has no equivalent accuracy field and is therefore not filtered.
    */
   _onDeviceOrientation(e) {
     if (!this._active) {
@@ -908,11 +918,21 @@ const LocateControl = Control.extend({
 
     if (e.webkitCompassHeading != null) {
       // iOS: webkitCompassHeading is relative to device top.
+      const threshold = this.options.compassAccuracyThreshold;
+      const filterEnabled = typeof threshold === "number" && e.webkitCompassAccuracy != null;
+      // -1 means uncalibrated, always reject when filtering is on.
+      const tooInaccurate = filterEnabled && (e.webkitCompassAccuracy < 0 || e.webkitCompassAccuracy > threshold);
+
+      if (tooInaccurate) {
+        this._setCompassHeading();
+        return;
+      }
+
       // Compensate using current screen orientation when available.
       const screenAngle = window.screen?.orientation?.angle ?? 0;
       this._setCompassHeading((e.webkitCompassHeading + screenAngle) % 360);
     } else if (e.alpha !== null) {
-      // Android
+      // Android: no standardized accuracy field, reading is shown as-is.
       this._setCompassHeading(360 - e.alpha);
     }
   },