Multi-axis Shapes

draftlogs/7666_add.md

@@ -0,0 +1 @@
+ - Add support for shapes to reference multiple axes [[#7666](https://github.com/plotly/plotly.js/pull/7666)]

src/components/shapes/attributes.js

@@ -1,13 +1,14 @@
 'use strict';
 
-var annAttrs = require('../annotations/attributes');
+var cartesianConstants = require('../../plots/cartesian/constants');
 var fontAttrs = require('../../plots/font_attributes');
 var scatterLineAttrs = require('../../traces/scatter/attributes').line;
 var dash = require('../drawing/attributes').dash;
 var extendFlat = require('../../lib/extend').extendFlat;
 var templatedArray = require('../../plot_api/plot_template').templatedArray;
 var axisPlaceableObjs = require('../../constants/axis_placeable_objects');
 var basePlotAttributes = require('../../plots/attributes');
+var annAttrs = require('../annotations/attributes');
 const { shapeTexttemplateAttrs, templatefallbackAttrs } = require('../../plots/template_attributes');
 var shapeLabelTexttemplateVars = require('./label_texttemplate');
 
@@ -115,9 +116,13 @@ module.exports = templatedArray('shape', {
  },
 
  xref: extendFlat({}, annAttrs.xref, {
+ arrayOk: true,
  description: [
  "Sets the shape's x coordinate axis.",
- axisPlaceableObjs.axisRefDescription('x', 'left', 'right')
+ axisPlaceableObjs.axisRefDescription('x', 'left', 'right'),
+ 'If an array of axis IDs is provided, each `x` value will refer to the corresponding axis,',
+ 'e.g., [\'x\', \'x2\'] for a rectangle, line, or circle means `x0` uses the `x` axis and `x1` uses the `x2` axis.',
+ 'Path shapes using an array should have one entry for each x coordinate in the string.',
  ].join(' ')
  }),
  xsizemode: {
@@ -134,7 +139,8 @@ module.exports = templatedArray('shape', {
  'of data or plot fraction but `x0`, `x1` and x coordinates within `path`',
  'are pixels relative to `xanchor`. This way, the shape can have',
  'a fixed width while maintaining a position relative to data or',
- 'plot fraction.'
+ 'plot fraction.',
+ 'Note: `xsizemode` *pixel* is not supported when `xref` is an array.'
  ].join(' ')
  },
  xanchor: {
@@ -183,9 +189,13 @@ module.exports = templatedArray('shape', {
  ].join(' ')
  },
  yref: extendFlat({}, annAttrs.yref, {
+ arrayOk: true,
  description: [
  "Sets the shape's y coordinate axis.",
- axisPlaceableObjs.axisRefDescription('y', 'bottom', 'top')
+ axisPlaceableObjs.axisRefDescription('y', 'bottom', 'top'),
+ 'If an array of axis IDs is provided, each `y` value will refer to the corresponding axis,',
+ 'e.g., [\'y\', \'y2\'] for a rectangle, line, or circle means `y0` uses the `y` axis and `y1` uses the `y2` axis.',
+ 'Path shapes using an array should have one entry for each y coordinate in the string.',
  ].join(' ')
  }),
  ysizemode: {
@@ -202,7 +212,8 @@ module.exports = templatedArray('shape', {
  'of data or plot fraction but `y0`, `y1` and y coordinates within `path`',
  'are pixels relative to `yanchor`. This way, the shape can have',
  'a fixed height while maintaining a position relative to data or',
- 'plot fraction.'
+ 'plot fraction.',
+ 'Note: `ysizemode` *pixel* is not supported when `yref` is an array.'
  ].join(' ')
  },
  yanchor: {

src/components/shapes/calc_autorange.js

@@ -21,19 +21,29 @@ module.exports = function calcAutorange(gd) {
  var xRefType = Axes.getRefType(shape.xref);
  var yRefType = Axes.getRefType(shape.yref);
 
- // paper and axis domain referenced shapes don't affect autorange
- if(shape.xref !== 'paper' && xRefType !== 'domain') {
+ if(xRefType === 'array') {
+ const extremesForRefArray = calcArrayRefAutorange(gd, shape, 'x');
+ Object.entries(extremesForRefArray).forEach(([axID, axExtremes]) => {
+ ax = Axes.getFromId(gd, axID);
+ shape._extremes[ax._id] = Axes.findExtremes(ax, axExtremes, calcXPaddingOptions(shape));
+ });
+ } else if(shape.xref !== 'paper' && xRefType !== 'domain') {
+ // paper and axis domain referenced shapes don't affect autorange
  ax = Axes.getFromId(gd, shape.xref);
-
  bounds = shapeBounds(ax, shape, constants.paramIsX);
  if(bounds) {
  shape._extremes[ax._id] = Axes.findExtremes(ax, bounds, calcXPaddingOptions(shape));
  }
  }
 
- if(shape.yref !== 'paper' && yRefType !== 'domain') {
+ if(yRefType === 'array') {
+ const extremesForRefArray = calcArrayRefAutorange(gd, shape, 'y');
+ Object.entries(extremesForRefArray).forEach(([axID, axExtremes]) => {
+ ax = Axes.getFromId(gd, axID);
+ shape._extremes[ax._id] = Axes.findExtremes(ax, axExtremes, calcYPaddingOptions(shape));
+ });
+ } else if(shape.yref !== 'paper' && yRefType !== 'domain') {
  ax = Axes.getFromId(gd, shape.yref);
-
  bounds = shapeBounds(ax, shape, constants.paramIsY);
  if(bounds) {
  shape._extremes[ax._id] = Axes.findExtremes(ax, bounds, calcYPaddingOptions(shape));
@@ -42,6 +52,60 @@ module.exports = function calcAutorange(gd) {
  }
 };
 
+/**
+ * Calculate autorange extremes for shapes that reference multiple axes (array refs).
+ *
+ * @param {object} gd - main graph div object
+ * @param {object} shape - shape object
+ * @param {string} axLetter - 'x' or 'y' indicating which axis dimension to process
+ * @returns {object} - mapping of axis IDs to arrays of converted coordinate values
+ */
+function calcArrayRefAutorange(gd, shape, axLetter) {
+ const refs = shape[axLetter + 'ref'];
+ const paramsToUse = axLetter === 'x' ? constants.paramIsX : constants.paramIsY;
+
+ function addToAxisGroup(ref, val) {
+ if(ref === 'paper' || Axes.getRefType(ref) === 'domain') return;
+ if(!axisGroups[ref]) axisGroups[ref] = [];
+ axisGroups[ref].push(val);
+ }
+
+ // group coordinates by axis reference so we can calculate the extremes for each axis
+ const axisGroups = {};
+ if(shape.type === 'path' && shape.path) {
+ const segments = shape.path.match(constants.segmentRE) || [];
+ var refIndex = 0;
+ for(var i = 0; i < segments.length; i++) {
+ const segment = segments[i];
+ const command = segment.charAt(0);
+ const drawnIndex = paramsToUse[command].drawn;
+
+ if(drawnIndex === undefined) continue;
+
+ const params = segment.slice(1).match(constants.paramRE);
+ if(params && params.length > drawnIndex) {
+ addToAxisGroup(refs[refIndex], params[drawnIndex]);
+ refIndex++;
+ }
+ }
+ } else {
+ addToAxisGroup(refs[0], shape[axLetter + '0']);
+ addToAxisGroup(refs[1], shape[axLetter + '1']);
+ }
+
+ // Convert coordinates to data values
+ const convertedGroups = {};
+ for(const axId in axisGroups) {
+ const ax = Axes.getFromId(gd, axId);
+ if(!ax) continue;
+ var convertVal = (ax.type === 'category' || ax.type === 'multicategory') ? ax.r2c : ax.d2c;
+ if(ax.type === 'date') convertVal = helpers.decodeDate(convertVal);
+ convertedGroups[ax._id] = axisGroups[axId].map(convertVal);
+ }
+
+ return convertedGroups;
+}
+
 function calcXPaddingOptions(shape) {
  return calcPaddingOptions(shape.line.width, shape.xsizemode, shape.x0, shape.x1, shape.path, false);
 }

src/components/shapes/constants.js

@@ -33,7 +33,7 @@ module.exports = {
  Q: {1: true, 3: true, drawn: 3},
  C: {1: true, 3: true, 5: true, drawn: 5},
  T: {1: true, drawn: 1},
- S: {1: true, 3: true, drawn: 5},
+ S: {1: true, 3: true, drawn: 3},
  // A: {1: true, 6: true},
  Z: {}
  },

src/components/shapes/defaults.js

@@ -68,77 +68,138 @@ function handleShapeDefaults(shapeIn, shapeOut, fullLayout) {
  var ySizeMode = coerce('ysizemode');
 
  // positioning
- var axLetters = ['x', 'y'];
- for (var i = 0; i < 2; i++) {
- var axLetter = axLetters[i];
+ const dflts = [0.25, 0.75];
+ const pixelDflts = [0, 10];
+
+ ['x', 'y'].forEach(axLetter => {
  var attrAnchor = axLetter + 'anchor';
  var sizeMode = axLetter === 'x' ? xSizeMode : ySizeMode;
  var gdMock = { _fullLayout: fullLayout };
  var ax;
  var pos2r;
  var r2pos;
 
- // xref, yref
- var axRef = Axes.coerceRef(shapeIn, shapeOut, gdMock, axLetter, undefined, 'paper');
- var axRefType = Axes.getRefType(axRef);
-
- if (axRefType === 'range') {
- ax = Axes.getFromId(gdMock, axRef);
- ax._shapeIndices.push(shapeOut._index);
- r2pos = helpers.rangeToShapePosition(ax);
- pos2r = helpers.shapePositionToRange(ax);
- if (ax.type === 'category' || ax.type === 'multicategory') {
- coerce(axLetter + '0shift');
- coerce(axLetter + '1shift');
- }
+ // xref, yref - handle both string and array values
+ var axRef;
+ const refAttr = axLetter + 'ref';
+ const inputRef = shapeIn[refAttr];
+
+ if(Array.isArray(inputRef) && inputRef.length > 0) {
+ // Array case: use coerceRefArray for validation
+ const expectedLen = helpers.countDefiningCoords(shapeType, path, axLetter);
+ axRef = Axes.coerceRefArray(shapeIn, shapeOut, gdMock, axLetter, undefined, 'paper', expectedLen);
+ shapeOut['_' + axLetter + 'refArray'] = true;
  } else {
- pos2r = r2pos = Lib.identity;
+ // String/undefined case: use coerceRef
+ axRef = Axes.coerceRef(shapeIn, shapeOut, gdMock, axLetter, undefined, 'paper');
  }
 
- // Coerce x0, x1, y0, y1
- if (noPath) {
- var dflt0 = 0.25;
- var dflt1 = 0.75;
-
- // hack until V3.0 when log has regular range behavior - make it look like other
- // ranges to send to coerce, then put it back after
- // this is all to give reasonable default position behavior on log axes, which is
- // a pretty unimportant edge case so we could just ignore this.
- var attr0 = axLetter + '0';
- var attr1 = axLetter + '1';
- var in0 = shapeIn[attr0];
- var in1 = shapeIn[attr1];
- shapeIn[attr0] = pos2r(shapeIn[attr0], true);
- shapeIn[attr1] = pos2r(shapeIn[attr1], true);
-
- if (sizeMode === 'pixel') {
- coerce(attr0, 0);
- coerce(attr1, 10);
+ if(Array.isArray(axRef)) {
+ // Register the shape with all referenced axes for redrawing purposes
+ axRef.forEach(function(ref) {
+ if(Axes.getRefType(ref) === 'range') {
+ ax = Axes.getFromId(gdMock, ref);
+ if(ax && ax._shapeIndices.indexOf(shapeOut._index) === -1) {
+ ax._shapeIndices.push(shapeOut._index);
+ }
+ }
+ });
+
+ if(noPath) {
+ [0, 1].forEach(function(i) {
+ const ref = axRef[i];
+ const refType = Axes.getRefType(ref);
+ if(refType === 'range') {
+ ax = Axes.getFromId(gdMock, ref);
+ pos2r = helpers.shapePositionToRange(ax);
+ r2pos = helpers.rangeToShapePosition(ax);
+ if(ax.type === 'category' || ax.type === 'multicategory') {
+ coerce(axLetter + i + 'shift');
+ }
+ } else {
+ pos2r = r2pos = Lib.identity;
+ }
+
+ const attr = axLetter + i;
+ const inValue = shapeIn[attr];
+ shapeIn[attr] = pos2r(shapeIn[attr], true);
+
+ if(sizeMode === 'pixel') {
+ coerce(attr, pixelDflts[i]);
+ } else {
+ Axes.coercePosition(shapeOut, gdMock, coerce, ref, attr, dflts[i]);
+ }
+
+ shapeOut[attr] = r2pos(shapeOut[attr]);
+ shapeIn[attr] = inValue;
+
+ if(i === 0 && sizeMode === 'pixel') {
+ const inAnchor = shapeIn[attrAnchor];
+ shapeIn[attrAnchor] = pos2r(shapeIn[attrAnchor], true);
+ Axes.coercePosition(shapeOut, gdMock, coerce, ref, attrAnchor, 0.25);
+ shapeOut[attrAnchor] = r2pos(shapeOut[attrAnchor]);
+ shapeIn[attrAnchor] = inAnchor;
+ }
+ });
+ }
+ } else {
+ const axRefType = Axes.getRefType(axRef);
+
+ if(axRefType === 'range') {
+ ax = Axes.getFromId(gdMock, axRef);
+ ax._shapeIndices.push(shapeOut._index);
+ r2pos = helpers.rangeToShapePosition(ax);
+ pos2r = helpers.shapePositionToRange(ax);
+ if(noPath && (ax.type === 'category' || ax.type === 'multicategory')) {
+ coerce(axLetter + '0shift');
+ coerce(axLetter + '1shift');
+ }
  } else {
- Axes.coercePosition(shapeOut, gdMock, coerce, axRef, attr0, dflt0);
- Axes.coercePosition(shapeOut, gdMock, coerce, axRef, attr1, dflt1);
+ pos2r = r2pos = Lib.identity;
  }
 
- // hack part 2
- shapeOut[attr0] = r2pos(shapeOut[attr0]);
- shapeOut[attr1] = r2pos(shapeOut[attr1]);
- shapeIn[attr0] = in0;
- shapeIn[attr1] = in1;
- }
+ // Coerce x0, x1, y0, y1
+ if(noPath) {
+ // hack until V3.0 when log has regular range behavior - make it look like other
+ // ranges to send to coerce, then put it back after
+ // this is all to give reasonable default position behavior on log axes, which is
+ // a pretty unimportant edge case so we could just ignore this.
+ const attr0 = axLetter + '0';
+ const attr1 = axLetter + '1';
+ const in0 = shapeIn[attr0];
+ const in1 = shapeIn[attr1];
+ shapeIn[attr0] = pos2r(shapeIn[attr0], true);
+ shapeIn[attr1] = pos2r(shapeIn[attr1], true);
+
+ if(sizeMode === 'pixel') {
+ coerce(attr0, pixelDflts[0]);
+ coerce(attr1, pixelDflts[1]);
+ } else {
+ Axes.coercePosition(shapeOut, gdMock, coerce, axRef, attr0, dflts[0]);
+ Axes.coercePosition(shapeOut, gdMock, coerce, axRef, attr1, dflts[1]);
+ }
+
+ // hack part 2
+ shapeOut[attr0] = r2pos(shapeOut[attr0]);
+ shapeOut[attr1] = r2pos(shapeOut[attr1]);
+ shapeIn[attr0] = in0;
+ shapeIn[attr1] = in1;
+ }
 
- // Coerce xanchor and yanchor
-if (sizeMode === 'pixel') {
- // Hack for log axis described above
-var inAnchor = shapeIn[attrAnchor];
- shapeIn[attrAnchor] = pos2r(shapeIn[attrAnchor], true);
+// Coerce xanchor and yanchor
+ if(sizeMode === 'pixel') {
+// Hack for log axis described above
+ const inAnchor = shapeIn[attrAnchor];
+shapeIn[attrAnchor] = pos2r(shapeIn[attrAnchor], true);
 
- Axes.coercePosition(shapeOut, gdMock, coerce, axRef, attrAnchor, 0.25);
+Axes.coercePosition(shapeOut, gdMock, coerce, axRef, attrAnchor, 0.25);
 
- // Hack part 2
- shapeOut[attrAnchor] = r2pos(shapeOut[attrAnchor]);
- shapeIn[attrAnchor] = inAnchor;
+ // Hack part 2
+ shapeOut[attrAnchor] = r2pos(shapeOut[attrAnchor]);
+ shapeIn[attrAnchor] = inAnchor;
+ }
  }
- }
+ });
 
  if (noPath) {
  Lib.noneOrAll(shapeIn, shapeOut, ['x0', 'x1', 'y0', 'y1']);