Skip to content

Multi-axis Shapes #7666

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
alexshoe wants to merge 4 commits into
base: master
Choose a base branch
from
+104 −12
Draft

Multi-axis Shapes #7666

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c8be45f
Extend `xref` and `yref` attributes
alexshoe Dec 2, 2025
a7b3bb2
Add function to help validate number of defining shape vertices
alexshoe Dec 3, 2025
ace820b
Update shape defaults to handle an array of references
alexshoe Dec 4, 2025
a910d42
Modify shape xref/yref coercion logic
alexshoe Dec 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 14 additions & 6 deletions src/components/shapes/attributes.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,12 +119,16 @@ module.exports = templatedArray('shape', {
].join(' ')
},

xref: extendFlat({}, annAttrs.xref, {
xref: {
valType: 'any',
editType: 'calc',
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 means `x0` uses the `x` axis and `x1` uses the `x2` axis).',
].join(' ')
}),
},
xsizemode: {
valType: 'enumerated',
values: ['scaled', 'pixel'],
Expand Down Expand Up @@ -193,12 +197,16 @@ module.exports = templatedArray('shape', {
'corresponds to the end of the category.'
].join(' ')
},
yref: extendFlat({}, annAttrs.yref, {
yref: {
valType: 'any',
editType: 'calc',
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 means `y0` uses the `y` axis and `y1` uses the `y2` axis).',
].join(' ')
}),
},
ysizemode: {
valType: 'enumerated',
values: ['scaled', 'pixel'],
Expand Down
33 changes: 27 additions & 6 deletions src/components/shapes/defaults.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,18 +66,39 @@ function handleShapeDefaults(shapeIn, shapeOut, fullLayout) {

// positioning
var axLetters = ['x', 'y'];
for(var i = 0; i < 2; i++) {
var axLetter = axLetters[i];
axLetters.forEach(function(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');
// xref, yref - handle both string and array values
var axRef;
var refAttr = axLetter + 'ref';
var inputRef = shapeIn[refAttr];

if(Array.isArray(inputRef) && inputRef.length > 0) {
// Array case: use coerceRefArray for validation
var expectedLen = helpers.countDefiningCoords(shapeType, path);
axRef = Axes.coerceRefArray(shapeIn, shapeOut, gdMock, axLetter, undefined, 'paper', expectedLen);
shapeOut['_' + axLetter + 'refArray'] = true;

// Need to 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);
}
}
});
} else {
// String/undefined case: use coerceRef
axRef = Axes.coerceRef(shapeIn, shapeOut, gdMock, axLetter, undefined, 'paper');
}

var axRefType = Axes.getRefType(axRef);

if(axRefType === 'range') {
Expand Down Expand Up @@ -136,7 +157,7 @@ function handleShapeDefaults(shapeIn, shapeOut, fullLayout) {
shapeOut[attrAnchor] = r2pos(shapeOut[attrAnchor]);
shapeIn[attrAnchor] = inAnchor;
}
}
});

if(noPath) {
Lib.noneOrAll(shapeIn, shapeOut, ['x0', 'x1', 'y0', 'y1']);
Expand Down
19 changes: 19 additions & 0 deletions src/components/shapes/helpers.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,25 @@ exports.extractPathCoords = function(path, paramsToUse, isRaw) {
return extractedCoordinates;
};

exports.countDefiningCoords = function(shapeType, path) {
// non-path shapes always have 2 defining coordinates
if(shapeType !== 'path') return 2;
if(!path) return 0;

var segments = path.match(constants.segmentRE);
if(!segments) return 0;

var coordCount = 0;
segments.forEach(function(segment) {
// for each path command, check if there is a drawn coordinate
var segmentType = segment.charAt(0);
var hasDrawnX = constants.paramIsX[segmentType].drawn !== undefined;
var hasDrawnY = constants.paramIsY[segmentType].drawn !== undefined;
if(hasDrawnX || hasDrawnY) coordCount++;
Comment on lines +66 to +70
Copy link
Contributor

@emilykl emilykl Dec 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm. H and V segments cause an odd usability issue I hadn't considered: if a path contains H and V segments then the expected lengths of xref and yref may be different, and the corresponding list items will be "out of sync" with respect to which path segments they correspond to (i.e. it will not always be the case that xref[n] and yref[n] refer to the same path segment).

For example here is a rectangular path: M0,0H10V5H0Z (see visualization)

There are four segments (not counting Z), but only 3 x-values and 2 y-values are needed to define the shape. So you would have:

{
    "path": "M0,0H10V5H0Z",
    "xref": ["x", "x2", "x"],
    "yref": ["y", "y2"],
}

which is a bit odd, and sort a high cognitive load for the user to figure out the right xref and yref lists.

That said, it seems probably better than the other alternative that comes to mind, which would be to force the user to add an xref and a yref for every single segment, even if it will be ignored for some segments.

});
return coordCount;
};

exports.getDataToPixel = function(gd, axis, shift, isVertical, refType) {
var gs = gd._fullLayout._size;
var dataToPixel;
Expand Down
44 changes: 44 additions & 0 deletions src/plots/cartesian/axes.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ var Drawing = require('../../components/drawing');

var axAttrs = require('./layout_attributes');
var cleanTicks = require('./clean_ticks');
var cartesianConstants = require('./constants');

var constants = require('../../constants/numerical');
var ONEMAXYEAR = constants.ONEMAXYEAR;
Expand Down Expand Up @@ -124,6 +125,49 @@ axes.coerceRef = function(containerIn, containerOut, gd, attr, dflt, extraOption
return Lib.coerce(containerIn, containerOut, attrDef, refAttr);
};

/*
* Coerce an array of axis references. Used by shapes for per-coordinate axis references.
*
* attr: the attribute we're generating a reference for. Should end in 'x' or 'y'
* but can be prefixed, like 'ax' for annotation's arrow x
* dflt: the default to coerce to, or blank to use the first axis (falling back on
* extraOption if there is no axis)
* extraOption: aside from existing axes with this letter, what non-axis value is allowed?
* Only required if it's different from `dflt`
*/
axes.coerceRefArray = function(containerIn, containerOut, gd, attr, dflt, extraOption, expectedLen) {
var axLetter = attr.charAt(attr.length - 1);
var axlist = gd._fullLayout._subplots[axLetter + 'axis'];
var refAttr = attr + 'ref';
var axRef = containerIn[refAttr];

// Build the axis list, which we use to validate the axis references
if(!dflt) dflt = axlist[0] || (typeof extraOption === 'string' ? extraOption : extraOption[0]);
axlist = axlist.concat(axlist.map(function(x) { return x + ' domain'; }));
axlist = axlist.concat(extraOption ? extraOption : []);

// Handle array length mismatch
Copy link
Contributor

@emilykl emilykl Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should probably raise a warning in both of these cases

if(axRef.length > expectedLen) {
// if the array is longer than the expected length, truncate it
Lib.warn('Array attribute ' + refAttr + ' has more entries than expected, truncating to ' + expectedLen);
axRef = axRef.slice(0, expectedLen);
} else if(axRef.length < expectedLen) {
// if the array is shorter than the expected length, extend using the default value
Lib.warn('Array attribute ' + refAttr + ' has fewer entries than expected, extending with default value');
axRef = axRef.concat(Array(expectedLen - axRef.length).fill(dflt));
}

// Check all references, replace with default if invalid
for(var i = 0; i < axRef.length; i++) {
if(!axlist.includes(axRef[i])) {
axRef[i] = dflt;
}
}

containerOut[refAttr] = axRef;
Copy link
Contributor

@emilykl emilykl Dec 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The core Lib.coerce() function uses more complex logic here for setting the attribute in the out container -- I'm not 100% sure whether that's needed here, but something to verify.

return axRef;
};

/*
* Get the type of an axis reference. This can be 'range', 'domain', or 'paper'.
* This assumes ar is a valid axis reference and returns 'range' if it doesn't
Expand Down