Multi-axis Shapes #7666

alexshoe · 2025-12-04T22:05:01Z

Description:

Extends xref and yref to accept arrays, allowing shapes to span multiple subplots with each vertex anchored to a different axis. See #7151 for more information.

Example:

shapes: [{  
  type: 'rect',  
  x0: 0, 
  x1: 1, 
  y0: 0, 
  y1: 1,  
  xref: ['x', 'x2'],  // x0 uses 'x', x1 uses 'x2'  
  yref: ['y', 'y2']   // y0 uses 'y', y1 uses 'y2'
}]

Progress:

Step 1: Attributes & validation
- Extend xref and yref to allow array values
- Add helper function to check number of defining coordinates of a shape
- Update value validation to work with array values
Step 2: Refactor coordinate conversion
Step 3: Update shape rendering
Step 4: Addressing editable shapes
Step 5: Tests + documentation

src/components/shapes/helpers.js

emilykl · 2025-12-04T23:24:38Z

src/components/shapes/helpers.js

+        // 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++;


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.

src/plots/cartesian/axes.js

emilykl · 2025-12-04T23:41:51Z

src/plots/cartesian/axes.js

+        }
+    }
+
+    containerOut[refAttr] = axRef;


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.

just documenting that we chatted about this and decided we'd look deeper into Lib.coerce + if it's alright to not call it here.

src/plots/cartesian/axes.js

src/components/shapes/defaults.js

camdecoster · 2025-12-08T18:33:31Z

src/components/shapes/defaults.js

+                if(Axes.getRefType(ref) === 'range') {
+                    ax = Axes.getFromId(gdMock, ref);
+                    if(ax && ax._shapeIndices.indexOf(shapeOut._index) === -1) {
+                        ax._shapeIndices.push(shapeOut._index);
+                    }
+                }


Does anything need to happen in the else case?

I don't believe so since a paper value would not have a valid axis to register with, and paper/domain values wouldn't require a redraw in case of panning/changes to the axis.

camdecoster · 2025-12-08T18:40:08Z

src/components/shapes/helpers.js

+    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++;
+    });
+    return coordCount;


Could you transform this into an Array.reduce call and return that?

src/plots/cartesian/axes.js

camdecoster · 2025-12-08T19:16:28Z

src/plots/cartesian/axes.js

+ *     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?


Did you mean for this to be a question?

Oops, I just copied this from the original coerceRef comment, I'll fix this

alexshoe added 3 commits December 2, 2025 14:02

Extend xref and yref attributes

c8be45f

Add function to help validate number of defining shape vertices

a7b3bb2

Update shape defaults to handle an array of references

ace820b

alexshoe assigned emilykl Dec 4, 2025