Update shape defaults to handle an array of references

plotly · alexshoe · Dec 2, 2025 · Dec 3, 2025 · Dec 4, 2025 · Dec 5, 2025
commit ace820b9396cb0e065ee5bd2b3c344c50c34bc98
diff --git a/src/components/shapes/defaults.js b/src/components/shapes/defaults.js
@@ -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(path, noPath);
+            axRef = Axes.coerceRefArray(shapeIn, shapeOut, gdMock, axLetter, 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') {
@@ -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']);

diff --git a/src/plots/cartesian/axes.js b/src/plots/cartesian/axes.js
@@ -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;
@@ -124,6 +125,44 @@ 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, expectedLen) {
+    var axLetter = attr.charAt(attr.length - 1);
+    var axlist = gd._fullLayout._subplots[axLetter + 'axis'];
+    axlist = axlist.concat(axlist.map(function(x) { return x + ' domain'; }));
+    var refAttr = attr + 'ref';
+    var axRef = containerIn[refAttr];
+    var dflt = axlist.length ? axlist[0] : 'paper';
+
+    // Handle array length mismatch
+    if(axRef.length > expectedLen) {
+        // if the array is longer than the expected length, truncate it
+        axRef = axRef.slice(0, expectedLen);
+    } else if(axRef.length < expectedLen) {
+        // if the array is shorter than the expected length, extend using the 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(!(axRef[i] === 'paper' || cartesianConstants.idRegex[axLetter].test(axRef[i]))) {
+            axRef[i] = dflt;
+        }
+    }
+
+    containerOut[refAttr] = axRef;
+    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
@@ -134,6 +173,7 @@ axes.coerceRef = function(containerIn, containerOut, gd, attr, dflt, extraOption
  */
 axes.getRefType = function(ar) {
     if(ar === undefined) { return ar; }
+    if(Array.isArray(ar)) { return 'array'; }
     if(ar === 'paper') { return 'paper'; }
     if(ar === 'pixel') { return 'pixel'; }
     if(/( domain)$/.test(ar)) { return 'domain'; } else { return 'range'; }