Introduce direction attribute instead of more parameters for orientation

Author: wfr

draftlogs/7870_add.md

@@ -1 +1 @@
-- Add `right-left` and `bottom-up` values to Sankey `orientation`, with `left-right` and `top-down` as aliases for `h` and `v` [[#7870](https://github.com/plotly/plotly.js/pull/7870)]
+- Add `direction` attribute (`forward` / `reverse`) to the Sankey trace, controlling the flow direction along the `orientation` axis: `forward` keeps sources on the left (horizontal) or top (vertical), `reverse` moves them to the right or bottom [[#7870](https://github.com/plotly/plotly.js/pull/7870)]

src/traces/sankey/attributes.js

@@ -31,15 +31,24 @@ var attrs = (module.exports = overrideAll(
 
         orientation: {
             valType: 'enumerated',
-            values: ['v', 'h', 'left-right', 'right-left', 'top-down', 'bottom-up'],
+            values: ['v', 'h'],
             dflt: 'h',
             description: [
                 'Sets the orientation of the Sankey diagram.',
-                '`left-right` (synonym of the legacy value `h`) places sources on the left',
-                'with the flow running rightward; `right-left` places sources on the right',
-                'with the flow running leftward; `top-down` (synonym of the legacy value `v`)',
-                'places sources at the top with the flow running downward; `bottom-up` places',
-                'sources at the bottom with the flow running upward.'
+                'With `h` (the default), the flow runs horizontally.',
+                'With `v`, the flow runs vertically.',
+                'Use `direction` to control which side the sources are placed on.'
+            ].join(' ')
+        },
+
+        direction: {
+            valType: 'enumerated',
+            values: ['forward', 'reverse'],
+            dflt: 'forward',
+            description: [
+                'Sets the direction of the flow along the `orientation` axis.',
+                'With `forward` (the default), sources are on the left (horizontal) or top (vertical).',
+                'With `reverse`, sources are on the right (horizontal) or bottom (vertical).',
             ].join(' ')
         },
 

src/traces/sankey/defaults.js

@@ -101,6 +101,7 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     handleDomainDefaults(traceOut, layout, coerce);
 
     coerce('orientation');
+    coerce('direction');
     coerce('valueformat');
     coerce('valuesuffix');
 

src/traces/sankey/plot.js

@@ -193,15 +193,14 @@ module.exports = function plot(gd, calcData) {
                 hoverCenterX = (link.source.x1 + link.target.x0) / 2;
                 hoverCenterY = (link.y0 + link.y1) / 2;
             }
-            var orientation = link.trace.orientation;
+            var vertical = link.trace.orientation === 'v';
+            var reverse = link.trace.direction === 'reverse';
             var center = [hoverCenterX, hoverCenterY];
-            // Vertical orientations transpose x/y to match the group transform.
-            if(orientation === 'v' || orientation === 'top-down' || orientation === 'bottom-up') {
-                center.reverse();
-            }
-            // bottom-up / right-left additionally mirror the flow axis (matching the translate).
-            if(orientation === 'bottom-up') center[1] = d.parent.height - center[1];
-            if(orientation === 'right-left') center[0] = d.parent.width - center[0];
+            // Vertical orientation transposes x/y to match the group transform.
+            if(vertical) center.reverse();
+            // reverse direction additionally mirrors the flow axis (matching the translate).
+            if(vertical && reverse) center[1] = d.parent.height - center[1];
+            if(!vertical && reverse) center[0] = d.parent.width - center[0];
             center[0] += d.parent.translateX;
             center[1] += d.parent.translateY;
             return center;

src/traces/sankey/render.js

@@ -31,11 +31,10 @@ function sankeyModel(layout, d, traceIndex) {
     var calcData = unwrap(d);
     var trace = calcData.trace;
     var domain = trace.domain;
-    var horizontal = trace.orientation === 'h' ||
-        trace.orientation === 'left-right' ||
-        trace.orientation === 'right-left';
-    var rightLeft = trace.orientation === 'right-left';
-    var bottomUp = trace.orientation === 'bottom-up';
+    var horizontal = trace.orientation === 'h';
+    // reverse flips the source side along the flow axis: horizontal -> sources on the
+    // right (flow leftward), vertical -> sources at the bottom (flow upward).
+    var reverse = trace.direction === 'reverse';
     var nodePad = trace.node.pad;
     var nodeThickness = trace.node.thickness;
     var nodeAlign = {
@@ -289,8 +288,7 @@ function sankeyModel(layout, d, traceIndex) {
         trace: trace,
         guid: Lib.randstr(),
         horizontal: horizontal,
-        rightLeft: rightLeft,
-        bottomUp: bottomUp,
+        reverse: reverse,
         width: width,
         height: height,
         nodePad: trace.node.pad,
@@ -594,8 +592,7 @@ function nodeModel(d, n) {
         sizeAcross: d.width,
         forceLayouts: d.forceLayouts,
         horizontal: d.horizontal,
-        rightLeft: d.rightLeft,
-        bottomUp: d.bottomUp,
+        reverse: d.reverse,
         darkBackground: Color.color(n.color).isDark(),
         rgb: Color.rgb(n.color),
         alpha: Color.color(n.color).alpha(),
@@ -638,19 +635,19 @@ function salientEnough(d) {return (d.link.width > 1 || d.linkLineWidth > 0);}
 
 function sankeyTransform(d) {
     if(d.horizontal) {
-        if(d.rightLeft) {
-            // right-left: sources on the right, flow leftward; horizontal mirror of left-right.
+        if(d.reverse) {
+            // horizontal + reverse: sources on the right, flow leftward; a mirror of forward.
             return strTranslate(d.translateX + d.width, d.translateY) + 'matrix(-1 0 0 1 0 0)';
         }
-        // h / left-right: sources on the left, flow rightward.
+        // horizontal + forward: sources on the left, flow rightward.
         return strTranslate(d.translateX, d.translateY) + 'matrix(1 0 0 1 0 0)';
     }
-    if(d.bottomUp) {
-        // bottom-up: sources at the bottom, flow upward; a vertical mirror of top-down.
+    if(d.reverse) {
+        // vertical + reverse: sources at the bottom, flow upward; a mirror of forward.
         // Pure 90deg rotation (det +1) keeps the cross axis intact.
         return strTranslate(d.translateX, d.translateY + d.height) + 'matrix(0 -1 1 0 0 0)';
     }
-    // top-down (also 'v'): reflection about y=x, sources at the top, flow downward.
+    // vertical + forward: reflection about y=x, sources at the top, flow downward.
     return strTranslate(d.translateX, d.translateY) + 'matrix(0 1 1 0 0 0)';
 }
 
@@ -1071,9 +1068,9 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
         })
         .attr('text-anchor', function(d) {
             // vertical: labels are centered over the node. horizontal: aligned to the outer
-            // edge (right-left mirrors the layout, so the outer side and anchor flip).
+            // edge (reverse mirrors the layout, so the outer side and anchor flip).
             if(!d.horizontal) return 'middle';
-            return (d.left !== d.rightLeft) ? 'end' : 'start';
+            return (d.left !== d.reverse) ? 'end' : 'start';
         })
         .attr('transform', function(d) {
             var e = d3.select(this);
@@ -1088,9 +1085,9 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
             if(!d.horizontal) {
                 var posY = d.visibleHeight / 2;
                 // last Column (originalLayer === 1): put label towards center.
-                var posX = d.bottomUp ? 
+                var posX = d.reverse ?
                     (d.left ? -(pad + CAP_SHIFT * d.textFont.size) : (d.visibleWidth + pad)) : (d.left ? -pad : (d.visibleWidth + pad + CAP_SHIFT * d.textFont.size));
-                var flipV = d.bottomUp ? strRotate(90) : ('scale(-1,1)' + strRotate(90));
+                var flipV = d.reverse ? strRotate(90) : ('scale(-1,1)' + strRotate(90));
                 return strTranslate(posX, posY) + flipV;
             }
 
@@ -1102,10 +1099,10 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
             } else {
                 posX += d.visibleWidth;
             }
-            return strTranslate(posX, posY) + (d.rightLeft ? 'scale(-1,1)' : '');
+            return strTranslate(posX, posY) + (d.reverse ? 'scale(-1,1)' : '');
         });
 
     nodeLabel
         .transition()
         .ease(c.ease).duration(c.duration);
-};
+};

test/jasmine/tests/sankey_test.js

@@ -138,15 +138,24 @@ describe('sankey tests', function () {
             expect(fullTrace.domain.y).toEqual(attributes.domain.y.dflt, 'y domain by default');
         });
 
-        it('coerces the vertical orientation values', function() {
-            ['h', 'v', 'left-right', 'right-left', 'top-down', 'bottom-up'].forEach(function(o) {
+        it('coerces the orientation values', function() {
+            ['h', 'v'].forEach(function(o) {
                 expect(_supply({orientation: o}).orientation)
                     .toBe(o, o + ' is a valid orientation');
             });
             expect(_supply({orientation: 'sideways'}).orientation)
                 .toBe(attributes.orientation.dflt, 'invalid orientation falls back to default');
         });
 
+        it('coerces the direction values', function() {
+            ['forward', 'reverse'].forEach(function(dir) {
+                expect(_supply({direction: dir}).direction)
+                    .toBe(dir, dir + ' is a valid direction');
+            });
+            expect(_supply({direction: 'backward'}).direction)
+                .toBe(attributes.direction.dflt, 'invalid direction falls back to default');
+        });
+
         it("'Sankey' layout dependent specification should have proper types", function () {
             var fullTrace = _supplyWithLayout(
                 {},
@@ -385,38 +394,40 @@ describe('sankey tests', function () {
         });
         afterEach(destroyGraphDiv);
 
-        it('applies the correct group transform per orientation', function(done) {
+        it('applies the correct group transform per orientation and direction', function(done) {
             function groupTransform() {
                 return d3Select('.sankey').attr('transform');
             }
-            function plotWith(orientation) {
+            function plotWith(orientation, direction) {
                 var fig = Lib.extendDeep({}, mock);
                 fig.data[0].orientation = orientation;
+                if(direction !== undefined) fig.data[0].direction = direction;
                 // newPlot re-enters the trace, so the transform is set synchronously
                 // (no mid-transition interpolation to race against).
                 return Plotly.newPlot(gd, fig);
             }
 
             plotWith('h')
                 .then(function() {
+                    // forward is the default direction
                     expect(groupTransform()).toContain('matrix(1 0 0 1 0 0)');
-                    return plotWith('left-right'); // legacy synonym of h
+                    return plotWith('h', 'forward');
                 })
                 .then(function() {
                     expect(groupTransform()).toContain('matrix(1 0 0 1 0 0)');
-                    return plotWith('right-left');
+                    return plotWith('h', 'reverse');
                 })
                 .then(function() {
                     expect(groupTransform()).toContain('matrix(-1 0 0 1 0 0)');
-                    return plotWith('top-down');
+                    return plotWith('v', 'forward');
                 })
                 .then(function() {
                     expect(groupTransform()).toContain('matrix(0 1 1 0 0 0)');
-                    return plotWith('v'); // legacy synonym of top-down
+                    return plotWith('v'); // forward is the default direction
                 })
                 .then(function() {
                     expect(groupTransform()).toContain('matrix(0 1 1 0 0 0)');
-                    return plotWith('bottom-up');
+                    return plotWith('v', 'reverse');
                 })
                 .then(function() {
                     expect(groupTransform()).toContain('matrix(0 -1 1 0 0 0)');