Add shapes.layer value "belowtraces" for drawing shapes in between gridlines and traces

Author: my-tien

src/components/shapes/attributes.js

@@ -110,10 +110,10 @@ module.exports = templatedArray('shape', {
 
     layer: {
         valType: 'enumerated',
-        values: ['below', 'above'],
+        values: ['below', 'above', 'belowtraces'],
         dflt: 'above',
         editType: 'arraydraw',
-        description: 'Specifies whether shapes are drawn below or above traces.'
+        description: 'Specifies whether shapes are drawn below gridlines (*below*), between gridlines and traces (*belowtraces*) or above traces (*above*).'
     },
 
     xref: extendFlat({}, annAttrs.xref, {

src/components/shapes/draw.js

@@ -91,10 +91,12 @@ function drawOne(gd, index) {
     // TODO: use d3 idioms instead of deleting and redrawing every time
     if(!options._input || options.visible !== true) return;
 
-    if(options.layer !== 'below') {
+    if(options.layer === 'above') {
         drawShape(gd._fullLayout._shapeUpperLayer);
     } else if(options.xref === 'paper' || options.yref === 'paper') {
         drawShape(gd._fullLayout._shapeLowerLayer);
+    } else if(options.layer === 'belowtraces') {
+        drawShape(plotinfo.shapelayerBelowTraces);
     } else {
         if(plotinfo._hadPlotinfo) {
             var mainPlot = plotinfo.mainplotinfo || plotinfo;

src/plots/cartesian/index.js

@@ -465,6 +465,10 @@ function makeSubplotLayer(gd, plotinfo) {
             plotinfo.gridlayer = ensureSingle(plotgroup, 'g', 'gridlayer');
             plotinfo.zerolinelayer = ensureSingle(plotgroup, 'g', 'zerolinelayer');
 
+            var belowTracesLayer = ensureSingle(plotgroup, 'g', 'layer-below-traces');
+            plotinfo.shapelayerBelowTraces = ensureSingle(belowTracesLayer, 'g', 'shapelayer');
+            plotinfo.imagelayerBelowTraces = ensureSingle(belowTracesLayer, 'g', 'imagelayer');
+
             ensureSingle(plotgroup, 'path', 'xlines-below');
             ensureSingle(plotgroup, 'path', 'ylines-below');
             plotinfo.overlinesBelow = ensureSingle(plotgroup, 'g', 'overlines-below');

test/image/mocks/shapes_layer_below_traces.json

@@ -0,0 +1,126 @@
+{
+  "data": [
+    {
+      "name": "scatter",
+      "x": [
+        "A",
+        "B",
+        "C",
+        "D",
+        2000.0
+      ],
+      "y": [
+        100,
+        200,
+        150,
+        190,
+        50
+      ],
+      "type": "scatter"
+    },
+    {
+      "name": "bar",
+      "x": [
+        "A",
+        "B",
+        "C",
+        "D",
+        2000.0
+      ],
+      "y": [
+        50,
+        70,
+        90,
+        35,
+        55
+      ],
+      "type": "bar"
+    }
+  ],
+  "layout": {
+    "shapes": [
+      {
+        "name": "dashdot line",
+        "fillcolor": "rgba(179,179,179,0.6)",
+        "layer": "above",
+        "line": {
+          "color": "rgba(66,127,109,0.6)",
+          "dash": "dashdot"
+        },
+        "type": "line",
+        "x0": 0.75,
+        "x1": 0.75,
+        "xref": "x",
+        "y0": 0.0,
+        "y1": 1.0,
+        "yref": "paper"
+      },
+      {
+        "name": "horizontal line",
+        "fillcolor": "rgba(179,179,179,1)",
+        "layer": "above",
+        "line": {
+          "color": "rgba(0,0,0,1)"
+        },
+        "type": "line",
+        "x0": 0.0,
+        "x1": 1.0,
+        "xref": "paper",
+        "y0": 120.0,
+        "y1": 120.0,
+        "yref": "y"
+      },
+      {
+        "name": "blue rect",
+        "fillcolor": "rgba(108,173,225,0.8)",
+        "layer": "belowtraces",
+        "line": {
+          "color": "rgba(108,173,225,0.8)"
+        },
+        "type": "rect",
+        "x0": "B",
+        "x1": "D",
+        "xref": "x",
+        "y0": 40,
+        "y1": 70.0
+      },
+      {
+        "name": "big rect",
+        "fillcolor": "rgba(179,179,179,1)",
+        "layer": "below",
+        "line": {
+          "color": "rgba(179,179,179,1)"
+        },
+        "type": "rect",
+        "x0": "C",
+        "x1": 0.25,
+        "xref": "x",
+        "y0": 0.0,
+        "y1": 1.0,
+        "yref": "paper"
+      },
+      {
+        "name": "dashed rect",
+        "fillcolor": "rgba(130,143,198,1)",
+        "layer": "belowtraces",
+        "line": {
+          "color": "rgba(0,0,0,1)",
+          "dash": "dash",
+          "width": 3.0
+        },
+        "type": "rect",
+        "x0": "D",
+        "x1": 5,
+        "y0": 140,
+        "y1": 200
+      }
+    ],
+    "yaxis": {
+      "insiderange": [
+        "0",
+        "215"
+      ],
+      "type": "linear"
+    }
+  }
+}

test/plot-schema.json

@@ -7708,13 +7708,14 @@
        }
       },
       "layer": {
-       "description": "Specifies whether shapes are drawn below or above traces.",
+       "description": "Specifies whether shapes are drawn below gridlines (*below*), between gridlines and traces (*belowtraces*) or above traces (*above*).",
        "dflt": "above",
        "editType": "arraydraw",
        "valType": "enumerated",
        "values": [
         "below",
-        "above"
+        "above",
+        "belowtraces"
        ]
       },
       "legend": {