add circle to GeolocateControl showing accuracy of position

src/css/mapbox-gl.css

@@ -761,6 +761,13 @@ a.mapboxgl-ctrl-logo.mapboxgl-compact {
     display: none;
 }
 
+.mapboxgl-user-location-accuracy-circle {
+    background-color: #1da1f233;
+    width: 1px;
+    height: 1px;
+    border-radius: 100%;
+}
+
 .mapboxgl-crosshair,
 .mapboxgl-crosshair .mapboxgl-interactive,
 .mapboxgl-crosshair .mapboxgl-interactive:active {

src/ui/control/geolocate_control.js

@@ -15,6 +15,7 @@ type Options = {
     positionOptions?: PositionOptions,
     fitBoundsOptions?: AnimationOptions & CameraOptions,
     trackUserLocation?: boolean,
+    showAccuracy?: boolean,
     showUserLocation?: boolean
 };
 
@@ -28,6 +29,7 @@ const defaultOptions: Options = {
         maxZoom: 15
     },
     trackUserLocation: false,
+    showAccuracy: true,
     showUserLocation: true
 };
 
@@ -78,6 +80,7 @@ let noTimeout = false;
  * @param {Object} [options.positionOptions={enableHighAccuracy: false, timeout: 6000}] A Geolocation API [PositionOptions](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions) object.
  * @param {Object} [options.fitBoundsOptions={maxZoom: 15}] A [`fitBounds`](#map#fitbounds) options object to use when the map is panned and zoomed to the user's location. The default is to use a `maxZoom` of 15 to limit how far the map will zoom in for very accurate locations.
  * @param {Object} [options.trackUserLocation=false] If `true` the Geolocate Control becomes a toggle button and when active the map will receive updates to the user's location as it changes.
+ * @param {Object} [options.showAccuracy=true] If trackUserLocation is true, by default a transparent circle will be drawn around the user location indicating the accuracy (95% confidence level) of the user's location. Set to `false` to disable.
  * @param {Object} [options.showUserLocation=true] By default a dot will be shown on the map at the user's location. Set to `false` to disable.
  *
  * @example
@@ -94,12 +97,15 @@ class GeolocateControl extends Evented {
     options: Options;
     _container: HTMLElement;
     _dotElement: HTMLElement;
+    _circleElement: HTMLElement;
     _geolocateButton: HTMLButtonElement;
     _geolocationWatchID: number;
     _timeoutId: ?TimeoutID;
     _watchState: 'OFF' | 'ACTIVE_LOCK' | 'WAITING_ACTIVE' | 'ACTIVE_ERROR' | 'BACKGROUND' | 'BACKGROUND_ERROR';
     _lastKnownPosition: any;
     _userLocationDotMarker: Marker;
+    _accuracyCircleMarker: Marker;
+    _accuracy: number;
     _setup: boolean; // set to true once the control has been setup
 
     constructor(options: Options) {
@@ -109,6 +115,7 @@ class GeolocateControl extends Evented {
         bindAll([
             '_onSuccess',
             '_onError',
+            '_onZoom',
             '_finish',
             '_setupUI',
             '_updateCamera',
@@ -120,6 +127,7 @@ class GeolocateControl extends Evented {
         this._map = map;
         this._container = DOM.create('div', `mapboxgl-ctrl mapboxgl-ctrl-group`);
         checkGeolocationSupport(this._setupUI);
+        this._map.on('zoom', this._onZoom);
         return this._container;
     }
 
@@ -130,12 +138,16 @@ class GeolocateControl extends Evented {
             this._geolocationWatchID = (undefined: any);
         }
 
-        // clear the marker from the map
+        // clear the markers from the map
         if (this.options.showUserLocation && this._userLocationDotMarker) {
             this._userLocationDotMarker.remove();
         }
+        if (this.options.showAccuracy && this._accuracyCircleMarker) {
+            this._accuracyCircleMarker.remove();
+        }
 
         DOM.remove(this._container);
+        this._map.off('zoom', this._onZoom);
         this._map = (undefined: any);
         numberOfWatches = 0;
         noTimeout = false;
@@ -251,9 +263,21 @@ class GeolocateControl extends Evented {
 
     _updateMarker(position: ?Position) {
         if (position) {
-            this._userLocationDotMarker.setLngLat([position.coords.longitude, position.coords.latitude]).addTo(this._map);
+            const center = new LngLat(position.coords.longitude, position.coords.latitude);
+            this._accuracyCircleMarker.setLngLat(center).addTo(this._map);
+            this._userLocationDotMarker.setLngLat(center).addTo(this._map);
+            this._accuracy = position.coords.accuracy;
+            this._onZoom();
         } else {
             this._userLocationDotMarker.remove();
+            this._accuracyCircleMarker.remove();
+        }
+    }
+
+    _onZoom() {
+        if (this.options.trackUserLocation && this.options.showAccuracy) {
+            assert(this._circleElement);
+            updateCircleRadius(this._map, this._circleElement, this._accuracy);
         }
     }
 
@@ -326,9 +350,11 @@ class GeolocateControl extends Evented {
         // when showUserLocation is enabled, keep the Geolocate button disabled until the device location marker is setup on the map
         if (this.options.showUserLocation) {
             this._dotElement = DOM.create('div', 'mapboxgl-user-location-dot');
-
             this._userLocationDotMarker = new Marker(this._dotElement);
 
+            this._circleElement = DOM.create('div', 'mapboxgl-user-location-accuracy-circle');
+            this._accuracyCircleMarker = new Marker(this._circleElement);
+
             if (this.options.trackUserLocation) this._watchState = 'OFF';
         }
 
@@ -476,6 +502,28 @@ class GeolocateControl extends Evented {
 
 export default GeolocateControl;
 
+function getDistance(latlng1, latlng2) {
+    // Uses spherical law of cosines approximation.
+    const R = 6371000;
+
+    const rad = Math.PI / 180,
+        lat1 = latlng1.lat * rad,
+        lat2 = latlng2.lat * rad,
+        a = Math.sin(lat1) * Math.sin(lat2) +
+          Math.cos(lat1) * Math.cos(lat2) * Math.cos((latlng2.lng - latlng1.lng) * rad);
+
+    const maxMeters = R * Math.acos(Math.min(a, 1));
+    return maxMeters;
+}
+
+function updateCircleRadius(map, circle, accuracy) {
+    const y = map._container.clientHeight / 2;
+    const metersPerPixel = getDistance(map.unproject([0, y]), map.unproject([1, y]));
+    const circleDiameter = Math.ceil(2.0 * accuracy / metersPerPixel);
+    circle.style.width = `${circleDiameter}px`;
+    circle.style.height = `${circleDiameter}px`;
+}
+
 /* Geolocate Control Watch States
  * This is the private state of the control.
  *

test/unit/ui/control/geolocate.test.js

@@ -422,3 +422,60 @@ test('GeolocateControl switches to BACKGROUND state on map manipulation', (t) =>
     geolocate._geolocateButton.dispatchEvent(click);
     geolocation.send({latitude: 10, longitude: 20, accuracy: 30, timestamp: 40});
 });
+
+test('GeolocateControl accuracy circle not shown if showAccuracy = false', (t) => {
+    const map = createMap(t);
+    const geolocate = new GeolocateControl({
+        trackUserLocation: true,
+        showUserLocation: true,
+        showAccuracy: false,
+    });
+    map.addControl(geolocate);
+
+    const click = new window.Event('click');
+
+    geolocate.once('geolocate', () => {
+        map.jumpTo({
+            center: [10, 20]
+        });
+        map.once('zoomend', () => {
+            t.ok(!geolocate._circleElement.style.width);
+            t.end();
+        });
+        map.zoomTo(10, {duration: 0});
+    });
+
+    geolocate._geolocateButton.dispatchEvent(click);
+    geolocation.send({latitude: 10, longitude: 20, accuracy: 700});
+});
+
+test('GeolocateControl accuracy circle radius matches reported accuracy', (t) => {
+    const map = createMap(t);
+    const geolocate = new GeolocateControl({
+        trackUserLocation: true,
+        showUserLocation: true,
+    });
+    map.addControl(geolocate);
+
+    const click = new window.Event('click');
+
+    geolocate.once('geolocate', () => {
+        t.ok(geolocate._accuracyCircleMarker._map, 'userLocation accuracy circle marker on map');
+        t.equal(geolocate._accuracy, 700);
+        map.jumpTo({
+            center: [10, 20]
+        });
+        map.once('zoomend', () => {
+            t.equal(geolocate._circleElement.style.width, '20px'); // 700m = 20px at zoom 10
+            map.once('zoomend', () => {
+                t.equal(geolocate._circleElement.style.width, '79px'); // 700m = 79px at zoom 12
+                t.end();
+            });
+            map.zoomTo(12, {duration: 0});
+        });
+        map.zoomTo(10, {duration: 0});
+    });
+
+    geolocate._geolocateButton.dispatchEvent(click);
+    geolocation.send({latitude: 10, longitude: 20, accuracy: 700});
+});