property x0shift, x1shift, y0shift, y1shift for adjusting the shape coordinates

draftlogs/7005_add.md

@@ -0,0 +1 @@
+ - Add property x_shift/y_shift for shapes/selections referencing (multi-)category axes [[#7005](https://github.com/plotly/plotly.js/pull/7005)]

src/components/selections/attributes.js

@@ -54,6 +54,29 @@ module.exports = overrideAll(templatedArray('selection', {
         description: 'Sets the selection\'s end y position.'
     },
 
+    xshift: {
+        valType: 'number',
+        dflt: 0,
+        min: -0.5,
+        max: 0.5,
+        editType: 'calc',
+        description: [
+            'Only relevant if xref is a (multi-)category axes. Shifts x0 and x1 by a fraction of',
+            'the reference unit.'
+        ].join(' ')
+    },
+    yshift: {
+        valType: 'number',
+        dflt: 0,
+        min: -0.5,
+        max: 0.5,
+        editType: 'calc',
+        description: [
+            'Only relevant if yref is a (multi-)category axes. Shifts y0 and y1 by a fraction of',
+            'the reference unit.'
+        ].join(' ')
+    },
+
     path: {
         valType: 'string',
         editType: 'arraydraw',

src/components/selections/defaults.js

@@ -49,6 +49,8 @@ function handleSelectionDefaults(selectionIn, selectionOut, fullLayout) {
     coerce('line.color');
     coerce('line.width');
     coerce('line.dash');
+    coerce('xshift');
+    coerce('yshift');
 
     // positioning
     var axLetters = ['x', 'y'];

src/components/shapes/attributes.js

@@ -169,7 +169,17 @@ module.exports = templatedArray('shape', {
             'See `type` and `xsizemode` for more info.'
         ].join(' ')
     },
-
+    xshift: {
+        valType: 'number',
+        dflt: 0,
+        min: -0.5,
+        max: 0.5,
+        editType: 'calc',
+        description: [
+            'Only relevant if xref is a (multi-)category axes. Shifts x0 and x1 by a fraction of',
+            'the reference unit.'
+        ].join(' ')
+    },
     yref: extendFlat({}, annAttrs.yref, {
         description: [
             'Sets the shape\'s y coordinate axis.',
@@ -220,7 +230,17 @@ module.exports = templatedArray('shape', {
             'See `type` and `ysizemode` for more info.'
         ].join(' ')
     },
-
+    yshift: {
+        valType: 'number',
+        dflt: 0,
+        min: -0.5,
+        max: 0.5,
+        editType: 'calc',
+        description: [
+            'Only relevant if yref is a (multi-)category axes. Shifts y0 and y1 by a fraction of',
+            'the reference unit.'
+        ].join(' ')
+    },
     path: {
         valType: 'string',
         editType: 'calc+arraydraw',

src/components/shapes/calc_autorange.js

@@ -27,7 +27,7 @@ module.exports = function calcAutorange(gd) {
             var vx1 = shape.xsizemode === 'pixel' ? shape.xanchor : shape.x1;
             ax = Axes.getFromId(gd, shape.xref);
 
-            bounds = shapeBounds(ax, vx0, vx1, shape.path, constants.paramIsX);
+            bounds = shapeBounds(ax, vx0, vx1, shape.path, shape.xshift, constants.paramIsX);
             if(bounds) {
                 shape._extremes[ax._id] = Axes.findExtremes(ax, bounds, calcXPaddingOptions(shape));
             }
@@ -38,7 +38,7 @@ module.exports = function calcAutorange(gd) {
             var vy1 = shape.ysizemode === 'pixel' ? shape.yanchor : shape.y1;
             ax = Axes.getFromId(gd, shape.yref);
 
-            bounds = shapeBounds(ax, vy0, vy1, shape.path, constants.paramIsY);
+            bounds = shapeBounds(ax, vy0, vy1, shape.path, shape.yshift, constants.paramIsY);
             if(bounds) {
                 shape._extremes[ax._id] = Axes.findExtremes(ax, bounds, calcYPaddingOptions(shape));
             }
@@ -77,8 +77,13 @@ function calcPaddingOptions(lineWidth, sizeMode, v0, v1, path, isYAxis) {
     }
 }
 
-function shapeBounds(ax, v0, v1, path, paramsToUse) {
-    var convertVal = (ax.type === 'category' || ax.type === 'multicategory') ? ax.r2c : ax.d2c;
+function shapeBounds(ax, v0, v1, path, shift, paramsToUse) {
+    var convertVal;
+    if(ax.type === 'category' || ax.type === 'multicategory') {
+        convertVal = function(v) { return ax.r2c(v) + shift; };
+    } else {
+        convertVal = ax.d2c;
+    }
 
     if(v0 !== undefined) return [convertVal(v0), convertVal(v1)];
     if(!path) return;

src/components/shapes/defaults.js

@@ -75,6 +75,9 @@ function handleShapeDefaults(shapeIn, shapeOut, fullLayout) {
         var pos2r;
         var r2pos;
 
+        coerce('xshift');
+        coerce('yshift');
+
         // xref, yref
         var axRef = Axes.coerceRef(shapeIn, shapeOut, gdMock, axLetter, undefined,
             'paper');

src/components/shapes/display_labels.js

@@ -89,10 +89,12 @@ module.exports = function drawLabel(gd, index, options, shapeGroup) {
         // Setup conversion functions
         var xa = Axes.getFromId(gd, options.xref);
         var xRefType = Axes.getRefType(options.xref);
+        var xShift = options.xshift;
         var ya = Axes.getFromId(gd, options.yref);
         var yRefType = Axes.getRefType(options.yref);
-        var x2p = helpers.getDataToPixel(gd, xa, false, xRefType);
-        var y2p = helpers.getDataToPixel(gd, ya, true, yRefType);
+        var yShift = options.yshift;
+        var x2p = helpers.getDataToPixel(gd, xa, xShift, false, xRefType);
+        var y2p = helpers.getDataToPixel(gd, ya, yShift, true, yRefType);
         shapex0 = x2p(options.x0);
         shapex1 = x2p(options.x1);
         shapey0 = y2p(options.y0);

src/components/shapes/draw.js

@@ -225,10 +225,12 @@ function setupDragElement(gd, shapePath, shapeOptions, index, shapeLayer, editHe
     // setup conversion functions
     var xa = Axes.getFromId(gd, shapeOptions.xref);
     var xRefType = Axes.getRefType(shapeOptions.xref);
+    var xShift = shapeOptions.xshift;
     var ya = Axes.getFromId(gd, shapeOptions.yref);
     var yRefType = Axes.getRefType(shapeOptions.yref);
-    var x2p = helpers.getDataToPixel(gd, xa, false, xRefType);
-    var y2p = helpers.getDataToPixel(gd, ya, true, yRefType);
+    var yShift = shapeOptions.yshift;
+    var x2p = helpers.getDataToPixel(gd, xa, xShift, false, xRefType);
+    var y2p = helpers.getDataToPixel(gd, ya, yShift, true, yRefType);
     var p2x = helpers.getPixelToData(gd, xa, false, xRefType);
     var p2y = helpers.getPixelToData(gd, ya, true, yRefType);
 

src/components/shapes/helpers.js

@@ -53,7 +53,7 @@ exports.extractPathCoords = function(path, paramsToUse, isRaw) {
     return extractedCoordinates;
 };
 
-exports.getDataToPixel = function(gd, axis, isVertical, refType) {
+exports.getDataToPixel = function(gd, axis, shift, isVertical, refType) {
     var gs = gd._fullLayout._size;
     var dataToPixel;
 
@@ -66,7 +66,15 @@ exports.getDataToPixel = function(gd, axis, isVertical, refType) {
             var d2r = exports.shapePositionToRange(axis);
 
             dataToPixel = function(v) {
-                return axis._offset + axis.r2p(d2r(v, true));
+                var shiftPixels = 0;
+                if(axis.type === 'category' || axis.type === 'multicategory') {
+                    if(isVertical) {
+                        shiftPixels = -1 * ((gs.h - axis.r2p(d2r(0.5, true))) * shift);
+                    } else {
+                        shiftPixels = axis.r2p(d2r(0.5, true)) * shift;
+                    }
+                }
+                return axis._offset + axis.r2p(d2r(v, true)) + (shiftPixels || 0);
             };
 
             if(axis.type === 'date') dataToPixel = exports.decodeDate(dataToPixel);
@@ -179,6 +187,8 @@ exports.getPathString = function(gd, options) {
     var ya = Axes.getFromId(gd, options.yref);
     var gs = gd._fullLayout._size;
     var x2r, x2p, y2r, y2p;
+    var shiftUnitX = 0;
+    var shiftUnitY = 0;
     var x0, x1, y0, y1;
 
     if(xa) {
@@ -187,6 +197,9 @@ exports.getPathString = function(gd, options) {
         } else {
             x2r = exports.shapePositionToRange(xa);
             x2p = function(v) { return xa._offset + xa.r2p(x2r(v, true)); };
+            if(xa.type === 'category' || xa.type === 'multicategory') {
+                shiftUnitX = xa.r2p(x2r(0.5, true));
+            }
         }
     } else {
         x2p = function(v) { return gs.l + gs.w * v; };
@@ -198,6 +211,9 @@ exports.getPathString = function(gd, options) {
         } else {
             y2r = exports.shapePositionToRange(ya);
             y2p = function(v) { return ya._offset + ya.r2p(y2r(v, true)); };
+            if(ya.type === 'category' || ya.type === 'multicategory') {
+                shiftUnitY = gs.h - ya.r2p(y2r(0.5, true));
+            }
         }
     } else {
         y2p = function(v) { return gs.t + gs.h * (1 - v); };
@@ -208,23 +224,22 @@ exports.getPathString = function(gd, options) {
         if(ya && ya.type === 'date') y2p = exports.decodeDate(y2p);
         return convertPath(options, x2p, y2p);
     }
-
     if(options.xsizemode === 'pixel') {
         var xAnchorPos = x2p(options.xanchor);
-        x0 = xAnchorPos + options.x0;
-        x1 = xAnchorPos + options.x1;
+        x0 = xAnchorPos + options.x0 + shiftUnitX * options.xshift;
+        x1 = xAnchorPos + options.x1 + shiftUnitX * options.xshift;
     } else {
-        x0 = x2p(options.x0);
-        x1 = x2p(options.x1);
+        x0 = x2p(options.x0) + shiftUnitX * options.xshift;
+        x1 = x2p(options.x1) + shiftUnitX * options.xshift;
     }
 
     if(options.ysizemode === 'pixel') {
         var yAnchorPos = y2p(options.yanchor);
-        y0 = yAnchorPos - options.y0;
-        y1 = yAnchorPos - options.y1;
+        y0 = yAnchorPos - options.y0 - shiftUnitY * options.yshift;
+        y1 = yAnchorPos - options.y1 - shiftUnitY * options.yshift;
     } else {
-        y0 = y2p(options.y0);
-        y1 = y2p(options.y1);
+        y0 = y2p(options.y0) - shiftUnitY * options.yshift;
+        y1 = y2p(options.y1) - shiftUnitY * options.yshift;
     }
 
     if(type === 'line') return 'M' + x0 + ',' + y0 + 'L' + x1 + ',' + y1;

test/image/mocks/zzz_shape_shift_horizontal.json

@@ -0,0 +1,87 @@
+{
+    "data": [
+        {
+            "y": [
+                ["A", "A", "B", "B"], ["C", "D", "C", "D"]
+            ],
+            "x": [
+                1, 2, 3, 4
+            ],
+            "type": "bar",
+            "marker": {
+                "color": "rgba(153, 217, 234, 1)"
+            },
+            "orientation": "h"
+        },
+        {
+            "y": [
+                ["A", "A", "B", "B"], ["C", "D", "C", "D"]
+            ],
+            "x": [
+                4, 3, 2, 1
+            ],
+            "type": "bar",
+            "orientation": "h"
+        }
+    ],
+    "layout": {
+        "shapes": [
+            {
+                "layer": "above",
+                "type": "rect",
+                "label": {
+                    "text": "around A,D",
+                    "textposition": "bottom center",
+                    "textangle": 0
+                },
+                "line": {
+                  "color": "black",
+                  "width": 3.0
+                },
+                "y0": ["A", "C"],
+                "y1": ["A", "D"],
+                "x0": 0,
+                "x1": 0.25,
+                "yshift": 0.5,
+                "xref": "paper"
+            },
+            {
+                "layer": "above",
+                "type": "line",
+                "label": {
+                    "text": "on B,D",
+                    "textposition": "middle",
+                    "textangle": 0
+                },
+                "line": {
+                  "color": "blue",
+                  "width": 3.0
+                },
+                "y0": ["B", "D"],
+                "y1": ["B", "D"],
+                "x0": 0,
+                "x1": 0.25,
+                "xref": "paper"
+            },
+            {
+                "layer": "above",
+                "type": "line",
+                "label": {
+                    "text": "Before B,D",
+                    "textposition": "middle",
+                    "textangle": 0
+                },
+                "line": {
+                  "color": "green",
+                  "width": 3.0
+                },
+                "y0": ["B", "D"],
+                "y1": ["B", "D"],
+                "x0": 0,
+                "x1": 0.25,
+                "yshift": -0.5,
+                "xref": "paper"
+            }
+        ]
+    }
+}

test/image/mocks/zzz_shape_shift_vertical.json

@@ -0,0 +1,65 @@
+{
+    "data": [
+        {
+            "x": [
+                "A", "B", "C", "D"
+            ],
+            "y": [
+                1, 2, 3, 4
+            ],
+            "type": "bar"
+        }
+    ],
+    "layout": {
+        "width": 600,
+        "shapes": [
+            {
+                "layer": "above",
+                "type": "line",
+                "label": {
+                    "text": "right from A",
+                    "textposition": "end",
+                    "textangle": 0
+                },
+                "line": {
+                  "color": "yellow",
+                  "width": 3.0
+                },
+                "x0": "A",
+                "x1": "A",
+                "y0": 0,
+                "y1": 0.5,
+                "xshift": 0.5,
+                "yref": "paper"
+            },
+            {
+                "layer": "above",
+                "type": "line",
+                "label": {
+                    "text": "slightly left from D",
+                    "textposition": "end",
+                    "textangle": 0
+                },
+                "line": {
+                  "color": "pink",
+                  "width": 3.0
+                },
+                "x0": 3,
+                "x1": 3,
+                "y0": 0,
+                "y1": 0.5,
+                "xshift": -0.25,
+                "yref": "paper"
+            }
+        ],
+        "selections": [
+            {
+                "x0": 0,
+                "x1": 4,
+                "y0": 1,
+                "y1": 3,
+                "xshift": -0.5
+            }
+        ]
+    }
+}