Merge pull request #6024 from plotly/h-colorbar

Introduce horizontal colorbars

draftlogs/6024_add.md

@@ -0,0 +1 @@
+ - Introduce horizontal colorbars [[#6024](https://github.com/plotly/plotly.js/pull/6024)]

src/components/colorbar/attributes.js

@@ -7,16 +7,12 @@ var overrideAll = require('../../plot_api/edit_types').overrideAll;
 
 
 module.exports = overrideAll({
-// TODO: only right is supported currently
-//     orient: {
-//         valType: 'enumerated',
-//         values: ['left', 'right', 'top', 'bottom'],
-//         dflt: 'right',
-//         description: [
-//             'Determines which side are the labels on',
-//             '(so left and right make vertical bars, etc.)'
-//         ].join(' ')
-//     },
+    orientation: {
+        valType: 'enumerated',
+        values: ['h', 'v'],
+        dflt: 'v',
+        description: 'Sets the orientation of the colorbar.'
+    },
     thicknessmode: {
         valType: 'enumerated',
         values: ['fraction', 'pixels'],
@@ -61,21 +57,23 @@ module.exports = overrideAll({
     },
     x: {
         valType: 'number',
-        dflt: 1.02,
         min: -2,
         max: 3,
         description: [
-            'Sets the x position of the color bar (in plot fraction).'
+            'Sets the x position of the color bar (in plot fraction).',
+            'Defaults to 1.02 when `orientation` is *v* and',
+            '0.5 when `orientation` is *h*.'
         ].join(' ')
     },
     xanchor: {
         valType: 'enumerated',
         values: ['left', 'center', 'right'],
-        dflt: 'left',
         description: [
             'Sets this color bar\'s horizontal position anchor.',
             'This anchor binds the `x` position to the *left*, *center*',
-            'or *right* of the color bar.'
+            'or *right* of the color bar.',
+            'Defaults to *left* when `orientation` is *v* and',
+            '*center* when `orientation` is *h*.'
         ].join(' ')
     },
     xpad: {
@@ -86,21 +84,23 @@ module.exports = overrideAll({
     },
     y: {
         valType: 'number',
-        dflt: 0.5,
         min: -2,
         max: 3,
         description: [
-            'Sets the y position of the color bar (in plot fraction).'
+            'Sets the y position of the color bar (in plot fraction).',
+            'Defaults to 0.5 when `orientation` is *v* and',
+            '1.02 when `orientation` is *h*.'
         ].join(' ')
     },
     yanchor: {
         valType: 'enumerated',
         values: ['top', 'middle', 'bottom'],
-        dflt: 'middle',
         description: [
             'Sets this color bar\'s vertical position anchor',
             'This anchor binds the `y` position to the *top*, *middle*',
-            'or *bottom* of the color bar.'
+            'or *bottom* of the color bar.',
+            'Defaults to *middle* when `orientation` is *v* and',
+            '*bottom* when `orientation` is *h*.'
         ].join(' ')
     },
     ypad: {
@@ -143,18 +143,26 @@ module.exports = overrideAll({
             'In other cases the default is *hide past div*.'
         ].join(' ')
     }),
+
+    // ticklabelposition: not used directly, as values depend on orientation
+    // left/right options are for x axes, and top/bottom options are for y axes
     ticklabelposition: {
         valType: 'enumerated',
         values: [
             'outside', 'inside',
             'outside top', 'inside top',
+            'outside left', 'inside left',
+            'outside right', 'inside right',
             'outside bottom', 'inside bottom'
         ],
         dflt: 'outside',
         description: [
-            'Determines where tick labels are drawn.'
+            'Determines where tick labels are drawn relative to the ticks.',
+            'Left and right options are used when `orientation` is *h*,',
+            'top and bottom when `orientation` is *v*.'
         ].join(' ')
     },
+
     ticklen: axesAttrs.ticklen,
     tickwidth: axesAttrs.tickwidth,
     tickcolor: axesAttrs.tickcolor,
@@ -193,10 +201,11 @@ module.exports = overrideAll({
         side: {
             valType: 'enumerated',
             values: ['right', 'top', 'bottom'],
-            dflt: 'top',
             description: [
                 'Determines the location of color bar\'s title',
                 'with respect to the color bar.',
+                'Defaults to *top* when `orientation` if *v* and ',
+                'defaults to *right* when `orientation` if *h*.',
                 'Note that the title\'s location used to be set',
                 'by the now deprecated `titleside` attribute.'
             ].join(' ')

src/components/colorbar/defaults.js

@@ -18,23 +18,30 @@ module.exports = function colorbarDefaults(containerIn, containerOut, layout) {
         return Lib.coerce(colorbarIn, colorbarOut, attributes, attr, dflt);
     }
 
+    var margin = layout.margin || {t: 0, b: 0, l: 0, r: 0};
+    var w = layout.width - margin.l - margin.r;
+    var h = layout.height - margin.t - margin.b;
+
+    var orientation = coerce('orientation');
+    var isVertical = orientation === 'v';
+
     var thicknessmode = coerce('thicknessmode');
     coerce('thickness', (thicknessmode === 'fraction') ?
-        30 / (layout.width - layout.margin.l - layout.margin.r) :
+        30 / (isVertical ? w : h) :
         30
     );
 
     var lenmode = coerce('lenmode');
     coerce('len', (lenmode === 'fraction') ?
         1 :
-        layout.height - layout.margin.t - layout.margin.b
+        isVertical ? h : w
     );
 
-    coerce('x');
-    coerce('xanchor');
+    coerce('x', isVertical ? 1.02 : 0.5);
+    coerce('xanchor', isVertical ? 'left' : 'center');
     coerce('xpad');
-    coerce('y');
-    coerce('yanchor');
+    coerce('y', isVertical ? 0.5 : 1.02);
+    coerce('yanchor', isVertical ? 'middle' : 'bottom');
     coerce('ypad');
     Lib.noneOrAll(colorbarIn, colorbarOut, ['x', 'y']);
 
@@ -44,7 +51,22 @@ module.exports = function colorbarDefaults(containerIn, containerOut, layout) {
     coerce('borderwidth');
     coerce('bgcolor');
 
-    var ticklabelposition = coerce('ticklabelposition');
+    var ticklabelposition = Lib.coerce(colorbarIn, colorbarOut, {
+        ticklabelposition: {
+            valType: 'enumerated',
+            dflt: 'outside',
+            values: isVertical ? [
+                'outside', 'inside',
+                'outside top', 'inside top',
+                'outside bottom', 'inside bottom'
+            ] : [
+                'outside', 'inside',
+                'outside left', 'inside left',
+                'outside right', 'inside right'
+            ]
+        }
+    }, 'ticklabelposition');
+
     coerce('ticklabeloverflow', ticklabelposition.indexOf('inside') !== -1 ? 'hide past domain' : 'hide past div');
 
     handleTickValueDefaults(colorbarIn, colorbarOut, coerce, 'linear');
@@ -66,5 +88,5 @@ module.exports = function colorbarDefaults(containerIn, containerOut, layout) {
         size: Lib.bigFont(tickFont.size)
     });
     Lib.coerceFont(coerce, 'title.font', dfltTitleFont);
-    coerce('title.side');
+    coerce('title.side', isVertical ? 'top' : 'right');
 };