Add fitbounds support for map subplots

scattermap, choroplethmap and densitymap traces currently need center
and zoom set by hand. The geo subplot has supported auto-fitting since
#4419; this ports the same idea over to the MapLibre-backed map
subplot.

Setting layout.map.fitbounds to 'locations' or 'geojson' computes a
lon/lat bounding box from the visible map-type traces on that subplot
(choropleth features use the matched geometry or the full input
geojson depending on the mode, same distinction as geo.fitbounds) and
feeds it into MapLibre's cameraForBounds to get a center and zoom.

Auto-fit only kicks in when the user hasn't set center or zoom
explicitly, mirroring how geo.fitbounds and cartesian autorange treat
"auto" as the absence of an explicit value rather than an override.
Once the user pans or zooms the map by hand, fitbounds gets cleared
back to false on that interaction so it stops recomputing the view on
every subsequent draw, the same way geo's zoom handler clears
fitbounds after a GUI zoom.

viewInitial (used for double-click reset) is now captured after the
fitbounds computation runs, so resetting the view lands back on the
fitted framing instead of the pre-fit default.

Fixes #3434

Author: kirthi-b

src/plots/map/constants.js

@@ -86,5 +86,9 @@ module.exports = {
 
     mapOnErrorMsg: 'Map error.',
 
+    // padding (in css pixels) applied around the computed data bounding box
+    // when `fitbounds` is set, so that points/features near the edge of the
+    // data aren't drawn flush against the subplot's edge.
+    fitboundsPadding: 30,
 
 };

src/plots/map/index.js

@@ -55,14 +55,10 @@ exports.plot = function plot(gd) {
             fullLayout[id]._subplot = map;
         }
 
-        if(!map.viewInitial) {
-            map.viewInitial = {
-                center: Lib.extendFlat({}, opts.center),
-                zoom: opts.zoom,
-                bearing: opts.bearing,
-                pitch: opts.pitch
-            };
-        }
+        // N.B. `viewInitial` is captured inside `Map.prototype.createMap`,
+        // *after* `fitbounds` (if any) has had a chance to compute
+        // `center` / `zoom`, so that resetting the view lands back on the
+        // auto-fit framing rather than the pre-fit default.
 
         map.plot(subplotCalcData, fullLayout, gd._promises);
     }

src/plots/map/layout_attributes.js

@@ -78,6 +78,20 @@ var attrs = module.exports = overrideAll({
         ].join(' ')
     },
 
+    fitbounds: {
+        valType: 'enumerated',
+        values: [false, 'locations', 'geojson'],
+        dflt: false,
+        editType: 'plot',
+        description: [
+            'Determines if this subplot\'s view settings are auto-computed to fit trace data.',
+            'This only takes effect when `center` and `zoom` are not explicitly set.',
+            'If *locations*, only the trace\'s visible locations are considered in the `fitbounds` computations.',
+            'If *geojson*, the entire trace input `geojson` (if provided) is considered in the `fitbounds` computations,',
+            'Defaults to *false*.'
+        ].join(' ')
+    },
+
     bounds: {
         west: {
             valType: 'number',

src/plots/map/layout_defaults.js

@@ -18,12 +18,24 @@ module.exports = function supplyLayoutDefaults(layoutIn, layoutOut, fullData) {
 
 function handleDefaults(containerIn, containerOut, coerce) {
     coerce('style');
+
+    // `fitbounds` only auto-computes `center` and `zoom` when the user has
+    // not explicitly set either of them - mirrors the `geo.fitbounds` /
+    // cartesian `autorange` convention of auto behavior being the absence
+    // of an explicit value, rather than fitbounds overriding a user choice.
+    var centerIn = containerIn.center;
+    var hasExplicitCenter = !!centerIn && (centerIn.lon !== undefined || centerIn.lat !== undefined);
+    var hasExplicitZoom = containerIn.zoom !== undefined;
+
     coerce('center.lon');
     coerce('center.lat');
     coerce('zoom');
     coerce('bearing');
     coerce('pitch');
 
+    var fitbounds = coerce('fitbounds');
+    containerOut._fitboundsAuto = Boolean(fitbounds) && !hasExplicitCenter && !hasExplicitZoom;
+
     var west = coerce('bounds.west');
     var east = coerce('bounds.east');
     var south = coerce('bounds.south');

src/plots/map/map.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var maplibregl = require('maplibre-gl');
+var isNumeric = require('fast-isnumeric');
 
 var Lib = require('../../lib');
 var geoUtils = require('../../lib/geo_location_utils');
@@ -149,6 +150,20 @@ proto.createMap = function(calcData, fullLayout, resolve, reject) {
     Promise.all(promises).then(function() {
         self.fillBelowLookup(calcData, fullLayout);
         self.updateData(calcData);
+        self.updateFitbounds(calcData, fullLayout);
+
+        // capture the view *after* fitbounds has had a chance to compute
+        // center/zoom, so that double-clicking to reset the view lands back
+        // on the auto-fit framing rather than the pre-fit default.
+        if(!self.viewInitial) {
+            self.viewInitial = {
+                center: Lib.extendFlat({}, opts.center),
+                zoom: opts.zoom,
+                bearing: opts.bearing,
+                pitch: opts.pitch
+            };
+        }
+
         self.updateLayout(fullLayout);
         self.resolveOnRender(resolve);
     }).catch(reject);
@@ -182,6 +197,7 @@ proto.updateMap = function(calcData, fullLayout, resolve, reject) {
     Promise.all(promises).then(function() {
         self.fillBelowLookup(calcData, fullLayout);
         self.updateData(calcData);
+        self.updateFitbounds(calcData, fullLayout);
         self.updateLayout(fullLayout);
         self.resolveOnRender(resolve);
     }).catch(reject);
@@ -327,6 +343,34 @@ proto.updateData = function(calcData) {
     }
 };
 
+// Auto-compute `center` / `zoom` from the visible trace data on this
+// subplot, mirroring `geo.fitbounds`. Only takes effect when the user has
+// not explicitly set `center` or `zoom` (see `_fitboundsAuto`, computed in
+// layout_defaults.js) and leaves the manual pan/zoom values in place once
+// the user has interacted with the map - see the `moveend` handler in
+// `initFx` below, which clears `fitbounds` on GUI edits.
+proto.updateFitbounds = function(calcData, fullLayout) {
+    var opts = fullLayout[this.id];
+    if(!opts._fitboundsAuto) return;
+
+    var box = computeFitboundsBox(calcData, opts.fitbounds);
+    if(!box) return;
+
+    var bounds = [[box.lonMin, box.latMin], [box.lonMax, box.latMax]];
+
+    var camera;
+    try {
+        camera = this.map.cameraForBounds(bounds, {padding: constants.fitboundsPadding});
+    } catch(e) {
+        Lib.warn('Something went wrong during ' + this.id + ' fitbounds computations.');
+        return;
+    }
+    if(!camera) return;
+
+    opts.center = {lon: camera.center.lng, lat: camera.center.lat};
+    opts.zoom = camera.zoom;
+};
+
 proto.updateLayout = function(fullLayout) {
     var map = this.map;
     var opts = fullLayout[this.id];
@@ -429,14 +473,28 @@ proto.initFx = function(calcData, fullLayout) {
 
         if(evt.originalEvent || self.wheeling) {
             var optsNow = fullLayoutNow[self.id];
-            Registry.call('_storeDirectGUIEdit', gd.layout, fullLayoutNow._preGUI, self.getViewEdits(optsNow));
+
+            // once the user has manually panned/zoomed, `fitbounds` must
+            // stop recomputing `center` / `zoom` on subsequent draws -
+            // mirrors `geo.fitbounds` getting cleared on GUI zoom/pan.
+            var hadFitbounds = Boolean(optsNow.fitbounds);
+            var viewEdits = self.getViewEdits(optsNow);
+            if(hadFitbounds) viewEdits[self.id + '.fitbounds'] = false;
+            Registry.call('_storeDirectGUIEdit', gd.layout, fullLayoutNow._preGUI, viewEdits);
 
             var viewNow = self.getView();
             optsNow._input.center = optsNow.center = viewNow.center;
             optsNow._input.zoom = optsNow.zoom = viewNow.zoom;
             optsNow._input.bearing = optsNow.bearing = viewNow.bearing;
             optsNow._input.pitch = optsNow.pitch = viewNow.pitch;
-            gd.emit('plotly_relayout', self.getViewEditsWithDerived(viewNow));
+
+            var eventEdits = self.getViewEditsWithDerived(viewNow);
+            if(hadFitbounds) {
+                optsNow._input.fitbounds = optsNow.fitbounds = false;
+                optsNow._fitboundsAuto = false;
+                eventEdits[self.id + '.fitbounds'] = false;
+            }
+            gd.emit('plotly_relayout', eventEdits);
         }
         if(evt.originalEvent && evt.originalEvent.type === 'mouseup') {
             self.dragging = false;
@@ -811,4 +869,72 @@ function convertCenter(center) {
     return [center.lon, center.lat];
 }
 
+function extendLonLatBounds(box, lon, lat) {
+    if(!isNumeric(lon) || !isNumeric(lat)) return;
+    if(lon < box.lonMin) box.lonMin = lon;
+    if(lon > box.lonMax) box.lonMax = lon;
+    if(lat < box.latMin) box.latMin = lat;
+    if(lat > box.latMax) box.latMax = lat;
+    box.any = true;
+}
+
+// Compute a lon/lat bounding box from the visible map-type traces
+// (scattermap, densitymap, choroplethmap) on this subplot, to feed into
+// MapLibre's `cameraForBounds`. Point-based traces (scattermap,
+// densitymap) contribute their `lon`/`lat` values directly; choroplethmap
+// traces contribute either the bounding box of their matched geometries
+// (`fitbounds: 'locations'`) or of the entire input `geojson`
+// (`fitbounds: 'geojson'`), analogous to `geo.fitbounds`.
+function computeFitboundsBox(calcData, fitbounds) {
+    var box = {lonMin: Infinity, lonMax: -Infinity, latMin: Infinity, latMax: -Infinity, any: false};
+
+    for(var i = 0; i < calcData.length; i++) {
+        var calcTrace = calcData[i];
+        var trace = calcTrace[0].trace;
+        if(trace.visible !== true) continue;
+
+        if(trace.type === 'choroplethmap') {
+            if(fitbounds === 'geojson') {
+                var geojsonIn = geoUtils.getTraceGeojson(trace);
+                if(geojsonIn) {
+                    var bbox = geoUtils.computeBbox(geojsonIn);
+                    extendLonLatBounds(box, bbox[0], bbox[1]);
+                    extendLonLatBounds(box, bbox[2], bbox[3]);
+                }
+            } else {
+                for(var j = 0; j < calcTrace.length; j++) {
+                    var fOut = calcTrace[j].fOut;
+                    if(fOut) {
+                        var fbbox = geoUtils.computeBbox(fOut);
+                        extendLonLatBounds(box, fbbox[0], fbbox[1]);
+                        extendLonLatBounds(box, fbbox[2], fbbox[3]);
+                    }
+                }
+            }
+        } else {
+            for(var k = 0; k < calcTrace.length; k++) {
+                var lonlat = calcTrace[k].lonlat;
+                if(lonlat) extendLonLatBounds(box, lonlat[0], lonlat[1]);
+            }
+        }
+    }
+
+    if(!box.any) return null;
+
+    // a single point (or multiple coincident points) collapses the box to
+    // zero width/height, which some `cameraForBounds` implementations turn
+    // into a non-finite zoom - pad it out to a small but non-degenerate
+    // region centered on the point.
+    if(box.lonMin === box.lonMax) {
+        box.lonMin -= 0.1;
+        box.lonMax += 0.1;
+    }
+    if(box.latMin === box.latMax) {
+        box.latMin -= 0.1;
+        box.latMax += 0.1;
+    }
+
+    return box;
+}
+
 module.exports = Map;