Adjust default setting and compute position based on xref and yref

Author: hannahker

src/components/legend/attributes.js

@@ -163,14 +163,17 @@ module.exports = {
         max: 3,
         editType: 'legend',
         description: [
-            'Sets the x position (in normalized coordinates) of the legend.',
-            'Defaults to *1.02* for vertical legends and',
-            'defaults to *0* for horizontal legends.'
+            'Sets the x position with respect to `xref` (in normalized coordinates) of the legend.',
+            'When `xref` is *paper*, defaults to *1.02* for vertical legends and',
+            'defaults to *0* for horizontal legends.',
+            'When `xref` is *container*, defaults to *1* for vertical legends and',
+            'defaults to *0* for horizontal legends.',
+            'Must be between *0* and *1* if `xref` is *container*.'
         ].join(' ')
     },
     xref: {
         valType: 'enumerated',
-        dflt: 'container',
+        dflt: 'paper',
         values: ['container', 'paper'],
         editType: 'layoutstyle',
         description: [
@@ -199,15 +202,17 @@ module.exports = {
         max: 3,
         editType: 'legend',
         description: [
-            'Sets the y position (in normalized coordinates) of the legend.',
-            'Defaults to *1* for vertical legends,',
+            'Sets the y position with respect to `yref` (in normalized coordinates) of the legend.',
+            'When `yref` is *paper*, defaults to *1* for vertical legends,',
             'defaults to *-0.1* for horizontal legends on graphs w/o range sliders and',
-            'defaults to *1.1* for horizontal legends on graph with one or multiple range sliders.'
+            'defaults to *1.1* for horizontal legends on graph with one or multiple range sliders.',
+            'When `yref` is *container*, defaults to *1*.',
+            'Must be between *0* and *1* if `yref` is *container*.'
         ].join(' ')
     },
     yref: {
         valType: 'enumerated',
-        dflt: 'container',
+        dflt: 'paper',
         values: ['container', 'paper'],
         editType: 'layoutstyle',
         description: [

src/components/legend/defaults.js

@@ -101,26 +101,48 @@ function groupDefaults(legendId, layoutIn, layoutOut, fullData) {
     coerce('borderwidth');
 
     var orientation = coerce('orientation');
+
+    var yref = coerce('yref');
+    var xref = coerce('xref');
+
     var isHorizontal = orientation === 'h';
+    var isPaperY = yref === 'paper';
+    var isPaperX = xref === 'paper';
     var defaultX, defaultY, defaultYAnchor;
 
+    // TODO: Adjust default xanchor if needed for container ref?
+    // TODO: Constrain x or y if container ref to be within 0-1
     if(isHorizontal) {
         defaultX = 0;
 
         if(Registry.getComponentMethod('rangeslider', 'isVisible')(layoutIn.xaxis)) {
-            defaultY = 1.1;
-            defaultYAnchor = 'bottom';
+            if(isPaperY) {
+                defaultY = 1.1;
+                defaultYAnchor = 'bottom';
+            } else {
+                defaultY = 1;
+                defaultYAnchor = 'top';
+            }
         } else {
             // maybe use y=1.1 / yanchor=bottom as above
             //   to avoid https://github.com/plotly/plotly.js/issues/1199
             //   in v3
-            defaultY = -0.1;
-            defaultYAnchor = 'top';
+            if(isPaperY) {
+                defaultY = -0.1;
+                defaultYAnchor = 'top';
+            } else {
+                defaultY = 0;
+                defaultYAnchor = 'bottom';
+            }
         }
     } else {
-        defaultX = 1.02;
         defaultY = 1;
         defaultYAnchor = 'auto';
+        if(isPaperX) {
+            defaultX = 1.02;
+        } else {
+            defaultX = 1;
+        }
     }
 
     coerce('traceorder', defaultOrder);

src/components/legend/draw.js

@@ -163,9 +163,21 @@ function drawOne(gd, opts) {
                 // draw the remaining pieces below
                 if(expMargin) return;
 
-                var lx = gs.l + gs.w * legendObj.x - FROM_TL[getXanchor(legendObj)] * legendObj._width;
-                var ly = gs.t + gs.h * (1 - legendObj.y) - FROM_TL[getYanchor(legendObj)] * legendObj._effHeight;
+                if(legendObj.xref === 'paper') {
+                    var lx = gs.l + gs.w * legendObj.x - FROM_TL[getXanchor(legendObj)] * legendObj._width;
+                } else {
+                    legendObj.x = Lib.constrain(legendObj.x, 0, 1); // TODO: Move this to defaults setting?
+                    var lx = fullLayout.width * legendObj.x - FROM_TL[getXanchor(legendObj)] * legendObj._width;
+                }
+
+                if(legendObj.yref === 'paper') {
+                    var ly = gs.t + gs.h * (1 - legendObj.y) - FROM_TL[getYanchor(legendObj)] * legendObj._effHeight;
+                } else {
+                    legendObj.y = Lib.constrain(legendObj.y, 0, 1); // TODO: Move this to defaults setting?
+                    var ly = fullLayout.height * (1 - legendObj.y) - FROM_TL[getYanchor(legendObj)] * legendObj._effHeight;
+                }
 
+                // TODO: Does this also apply if y/xref=container?
                 if(fullLayout.margin.autoexpand) {
                     var lx0 = lx;
                     var ly0 = ly;

test/image/mocks/legend_outside.json

@@ -54,9 +54,15 @@
    "layout":{
       "showlegend":true,
       "legend":{
-         "x":1,
-         "y":1,
-         "xanchor":"left"
+         "x": 0,
+         "y": 0,
+         "xref": "container",
+         "yref": "container",
+         "orientation": "h"
+      },
+      "margin": {
+         "t": 75,
+         "r": 115
       }
    }
 }

test/plot-schema.json

@@ -2964,7 +2964,7 @@
      "valType": "boolean"
     },
     "x": {
-     "description": "Sets the x position (in normalized coordinates) of the legend. Defaults to *1.02* for vertical legends and defaults to *0* for horizontal legends.",
+     "description": "Sets the x position with respect to `xref` (in normalized coordinates) of the legend. When `xref` is *paper*, defaults to *1.02* for vertical legends and defaults to *0* for horizontal legends. When `xref` is *container*, defaults to *1* for vertical legends and defaults to *0* for horizontal legends. Must be between *0* and *1* if `xref` is *container*.",
      "editType": "legend",
      "max": 3,
      "min": -2,
@@ -2984,7 +2984,7 @@
     },
     "xref": {
      "description": "Sets the container `x` refers to. *container* spans the entire `width` of the plot. *paper* refers to the width of the plotting area only.",
-     "dflt": "container",
+     "dflt": "paper",
      "editType": "layoutstyle",
      "valType": "enumerated",
      "values": [
@@ -2993,7 +2993,7 @@
      ]
     },
     "y": {
-     "description": "Sets the y position (in normalized coordinates) of the legend. Defaults to *1* for vertical legends, defaults to *-0.1* for horizontal legends on graphs w/o range sliders and defaults to *1.1* for horizontal legends on graph with one or multiple range sliders.",
+     "description": "Sets the y position with respect to `yref` (in normalized coordinates) of the legend. When `yref` is *paper*, defaults to *1* for vertical legends, defaults to *-0.1* for horizontal legends on graphs w/o range sliders and defaults to *1.1* for horizontal legends on graph with one or multiple range sliders. When `yref` is *container*, defaults to *1*. Must be between *0* and *1* if `yref` is *container*.",
      "editType": "legend",
      "max": 3,
      "min": -2,
@@ -3012,7 +3012,7 @@
     },
     "yref": {
      "description": "Sets the container `y` refers to. *container* spans the entire `height` of the plot. *paper* refers to the height of the plotting area only.",
-     "dflt": "container",
+     "dflt": "paper",
      "editType": "layoutstyle",
      "valType": "enumerated",
      "values": [