feat(geo): support min/max scale limits

fixes #5191

Author: mojoaxel

src/components/modebar/buttons.js

@@ -533,8 +533,18 @@ function handleGeo(gd, ev) {
 
         if(attr === 'zoom') {
             var scale = geoLayout.projection.scale;
+            var minScale = geoLayout.projection.minScale;
+            var maxScale = geoLayout.projection.maxScale;
+
             var newScale = (val === 'in') ? 2 * scale : 0.5 * scale;
 
+            // make sure the scale is within the min/max bounds
+            if (newScale > maxScale) {
+                newScale = maxScale;
+            } else if (newScale < minScale) {
+                newScale = minScale;
+            }
+
             Registry.call('_guiRelayout', gd, id + '.projection.scale', newScale);
         }
     }

src/plots/geo/geo.js

@@ -709,6 +709,13 @@ function getProjection(geoLayout) {
         return projection.getPath().bounds(object);
     };
 
+    // https://github.com/d3/d3-zoom/blob/master/README.md#zoom_scaleExtent
+    projection.scaleExtent = function() {
+        var minScale = projLayout.minScale * 100;
+        var maxScale = projLayout.maxScale * 100;
+        return [ minScale, maxScale ];
+    };
+
     // adapted from d3 v4:
     // https://github.com/d3/d3-geo/blob/master/src/projection/fit.js
     projection.fitExtent = function(extent, object) {

src/plots/geo/layout_attributes.js

@@ -174,9 +174,31 @@ var attrs = module.exports = overrideAll({
             min: 0,
             dflt: 1,
             description: [
-                'Zooms in or out on the map view.',
-                'A scale of *1* corresponds to the largest zoom level',
-                'that fits the map\'s lon and lat ranges. '
+                'Initial zoom level of the map view.',
+                'A scale of *1* (100%) corresponds to the base zoom level',
+                'that fits the map\'s lon and lat ranges.'
+            ].join(' ')
+        },
+        minScale: {
+            valType: 'number',
+            role: 'info',
+            min: 0,
+            dflt: 0,
+            description: [
+                'Minimal zoom level of the map view.',
+                'A minScale of *0.5* (50%) corresponds to a zoom level',
+                'where the map has half the size of base zoom level.'
+            ].join(' ')
+        },
+        maxScale: {
+            valType: 'number',
+            role: 'info',
+            min: 0,
+            dflt: Infinity,
+            description: [
+                'Maximal zoom level of the map view.',
+                'A maxScale of *2* (200%) corresponds to a zoom level',
+                'where the map is twice as big as the base layer.'
             ].join(' ')
         },
     },

src/plots/geo/layout_defaults.js

@@ -162,6 +162,8 @@ function handleGeoDefaults(geoLayoutIn, geoLayoutOut, coerce, opts) {
     }
 
     coerce('projection.scale');
+    coerce('projection.minScale');
+    coerce('projection.maxScale');
 
     show = coerce('showland', !visible ? false : undefined);
     if(show) coerce('landcolor');
@@ -206,6 +208,8 @@ function handleGeoDefaults(geoLayoutIn, geoLayoutOut, coerce, opts) {
     // clear attributes that will get auto-filled later
     if(fitBounds) {
         delete geoLayoutOut.projection.scale;
+        delete geoLayoutOut.projection.minScale;
+        delete geoLayoutOut.projection.maxScale;
 
         if(isScoped) {
             delete geoLayoutOut.center.lon;

src/plots/geo/zoom.js

@@ -41,6 +41,7 @@ module.exports = createGeoZoom;
 function initZoom(geo, projection) {
     return d3.behavior.zoom()
         .translate(projection.translate())
+        .scaleExtent(projection.scaleExtent())
         .scale(projection.scale());
 }