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

src/plots/cartesian/axes.js

src/components/shapes/defaults.js

src/components/shapes/helpers.js

src/plots/cartesian/axes.js

src/components/shapes/attributes.js

src/components/shapes/constants.js

Co-authored-by: Alex Johnson <alex@plot.ly>

src/components/shapes/attributes.js

src/components/shapes/defaults.js

src/components/shapes/draw.js

src/components/shapes/calc_autorange.js

src/components/shapes/defaults.js

src/components/shapes/draw.js

emilykl · 2026-01-22T21:48:29Z

src/components/shapes/helpers.js

+        var hasDrawnY = yParams.drawn !== undefined;
+
+        // Use vertex indices for array refs (same converter for all params in segment)
+        var segmentX2p = (isArrayXref && xSizemode !== 'pixel') ? x2p[xVertexIndex] : x2p;


Wait, so if isArrayXref is true but xSizemode is 'pixel', the variable segmentX2P gets assigned the value of x2p, but x2p would be an array of functions, not a function, correct? That seems like a bug. Unless I'm missing something.

emilykl · 2026-01-22T21:50:18Z

src/plots/cartesian/axes.js

 *     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`
+ * extraOption: fallback value, only required if it's different from `dflt`


What is the reason for changing this docstring? The previous version seems clearer.

Or if you want to rephrase without the question mark, could say something like Additional non-axis value to allow. Only required if different from dflt

emilykl · 2026-01-22T22:09:30Z

src/components/shapes/attributes.js

            'a fixed width while maintaining a position relative to data or',
-            'plot fraction.'
+            'plot fraction.',
+            'Note: *pixel* mode is not supported when `xref` is an array.'


Suggested change

'Note: *pixel* mode is not supported when `xref` is an array.'

'Note: `xsizemode` *pixel* is not supported when `xref` is an array.'

emilykl · 2026-01-22T22:10:22Z

src/components/shapes/attributes.js

            'a fixed height while maintaining a position relative to data or',
-            'plot fraction.'
+            'plot fraction.',
+            'Note: *pixel* mode is not supported when `yref` is an array.'


Suggested change

'Note: *pixel* mode is not supported when `yref` is an array.'

'Note: `ysizemode` *pixel* is not supported when `xref` is an array.'

emilykl · 2026-01-22T22:19:44Z

test/jasmine/tests/shapes_test.js

+                {type: 'path', xref: ['x', 'x2'], yref: ['y', 'y2'], path: 'M1,1L2,2'}
+            ]
+        }).then(function() {
+            expect(getShape(0)).not.toBe(null);


hm. This isn't quite right. getShape(n) will never return null, it will either return a selection of size 1, or it will fail the assertion inside the function.

I mean it WORKS in that this test will still fail if each shape isn't present exactly once, but the logic is bad.

emilykl · 2026-01-22T22:21:42Z

test/jasmine/tests/shapes_test.js

+            var lineExpectedRight = xa2.l2p(2) + xa2._offset;
+            var lineBBox = getBoundingBox(0);
+
+            expect(lineBBox.left).toBeCloseTo(lineExpectedLeft);


Is there a reason why top and bottom aren't tested in this test?

emilykl · 2026-01-22T22:22:19Z

test/jasmine/tests/shapes_test.js

+            var lineExpectedTop = ya2.l2p(20) + ya2._offset;
+            var lineBBox = getBoundingBox(0);
+
+            expect(lineBBox.bottom).toBeCloseTo(lineExpectedBottom);


Similarly, is there a reason why left and right aren't tested here?

emilykl · 2026-01-22T22:24:30Z

test/jasmine/tests/shapes_test.js

+        .then(done, done.fail);
+    });
+
+    it('updates shape when panning a referenced axis', function(done) {


This doesn't really test panning, it only tests updating the axis range via relayout. Test description should reflect that.

emilykl · 2026-01-23T15:08:46Z

test/jasmine/tests/shapes_test.js

+                x0: 0, x1: 5, y0: 0, y1: 5
+            }]
+        }).then(function() {
+            expect(gd._fullLayout.xaxis.range[0]).toBeLessThan(1);


It would be less than 1 even without the shape, since there is a data point at x=1. Should test that it's less than 0 (and test for a lower bound as well).

Same goes for the y axis.

Also the test is only checking xaxis.range[0], yaxis.range[0], xaxis2.range[1] and yaxis2.range[1].

Should also be checked: xaxis.range[1], yaxis.range[1], xaxis2.range[0] and yaxis2.range[0].

emilykl · 2026-01-23T15:12:56Z

test/image/mocks/multi_axis_shapes.json

@alexshoe Could you add a label to each of these shapes to make sure everything works as expected?

emilykl · 2026-01-23T15:16:40Z

@alexshoe This is looking really good. 🎉

I left some minor comments on the implementation (mostly style and readability) and also noticed some issues with the Jasmine tests. Could you do a pass through all the Jasmine tests and make sure they make sense, are testing the right things, etc.

I also realized there's a pretty good chance that shape.label.texttemplate won't play nice with this feature at all. I would expect variables x0, x1, y0, y1 to work as expected, but the remaining ones simply don't make any sense when the endpoints are associated with different axes. Can you test out what happens? There should be a decent error case (ignore the variable, perhaps?) rather than a catastrophic failure or showing the wrong information.

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