highcharts 6.1.4 → 6.2.0

package/es-modules/parts/ColumnSeries.js

@@ -1,19 +1,35 @@
 /**
- * (c) 2010-2017 Torstein Honsi
+ * (c) 2010-2018 Torstein Honsi
  *
  * License: www.highcharts.com/license
  */
+
+/**
+ * Adjusted width and x offset of the columns for grouping.
+ *
+ * @typedef Highcharts.ColumnMetricsObject
+ *
+ * @property {number} width
+ *           Width of the columns.
+ *
+ * @property {number} offset
+ *           Offset of the columns.
+ */
+
 'use strict';
+
 import H from './Globals.js';
 import './Utilities.js';
 import './Color.js';
 import './Legend.js';
 import './Series.js';
 import './Options.js';
+
 var animObject = H.animObject,
     color = H.color,
     each = H.each,
     extend = H.extend,
+    defined = H.defined,
     isNumber = H.isNumber,
     LegendSymbolMixin = H.LegendSymbolMixin,
     merge = H.merge,
@@ -22,35 +38,41 @@ var animObject = H.animObject,
     Series = H.Series,
     seriesType = H.seriesType,
     svg = H.svg;
+
 /**
  * The column series type.
  *
- * @constructor seriesTypes.column
- * @augments    Series
+ * @private
+ * @class
+ * @name Highcharts.seriesTypes.column
+ *
+ * @augments Highcharts.Series
  */
+seriesType('column', 'line'
 
 /**
  * Column series display one column per value along an X axis.
  *
- * @sample       {highcharts} highcharts/demo/column-basic/ Column chart
- * @sample       {highstock} stock/demo/column/ Column chart
+ * @sample {highcharts} highcharts/demo/column-basic/
+ *         Column chart
+ * @sample {highstock} stock/demo/column/
+ *         Column chart
  *
- * @extends      {plotOptions.line}
+ * @extends      plotOptions.line
+ * @excluding    connectNulls, dashStyle, gapSize, gapUnit, linecap,
+ *               lineWidth, marker, connectEnds, step
  * @product      highcharts highstock
- * @excluding    connectNulls,dashStyle,gapSize,gapUnit,linecap,lineWidth,
- *               marker,connectEnds,step
  * @optionparent plotOptions.column
  */
-seriesType('column', 'line', {
+, {
 
     /**
      * The corner radius of the border surrounding each column or bar.
      *
-     * @type    {Number}
-     * @sample  {highcharts} highcharts/plotoptions/column-borderradius/
-     *          Rounded columns
-     * @default 0
-     * @product highcharts highstock
+     * @sample {highcharts} highcharts/plotoptions/column-borderradius/
+     *         Rounded columns
+     *
+     * @product highcharts highstock gantt
      */
     borderRadius: 0,
 
@@ -64,15 +86,17 @@ seriesType('column', 'line', {
      * and instead this option gives the points individual color class names on
      * the form `highcharts-color-{n}`.
      *
-     * @type      {Boolean}
-     * @see       [series colors](#plotOptions.column.colors)
-     * @sample    {highcharts} highcharts/plotoptions/column-colorbypoint-false/
-     *            False by default
-     * @sample    {highcharts} highcharts/plotoptions/column-colorbypoint-true/
-     *            True
+     * @see [series colors](#plotOptions.column.colors)
+     *
+     * @sample {highcharts} highcharts/plotoptions/column-colorbypoint-false/
+     *         False by default
+     * @sample {highcharts} highcharts/plotoptions/column-colorbypoint-true/
+     *         True
+     *
+     * @type      {boolean}
      * @default   false
      * @since     2.0
-     * @product   highcharts highstock
+     * @product   highcharts highstock gantt
      * @apioption plotOptions.column.colorByPoint
      */
 
@@ -81,9 +105,9 @@ seriesType('column', 'line', {
      * of the global [colors](#colors) when [colorByPoint](
      * #plotOptions.column.colorByPoint) is true.
      *
-     * @type      {Array<Color>}
+     * @type      {Array<Highcharts.ColorString>}
      * @since     3.0
-     * @product   highcharts highstock
+     * @product   highcharts highstock gantt
      * @apioption plotOptions.column.colors
      */
 
@@ -95,21 +119,23 @@ seriesType('column', 'line', {
      * to `false` may look better, even though each column is rendered
      * blurry.
      *
-     * @sample  {highcharts} highcharts/plotoptions/column-crisp-false/
-     *          Crisp is false
+     * @sample {highcharts} highcharts/plotoptions/column-crisp-false/
+     *         Crisp is false
+     *
      * @since   5.0.10
-     * @product highcharts highstock
+     * @product highcharts highstock gantt
      */
     crisp: true,
 
     /**
      * Padding between each value groups, in x axis units.
      *
-     * @sample  {highcharts} highcharts/plotoptions/column-grouppadding-default/
-     *          0.2 by default
-     * @sample  {highcharts} highcharts/plotoptions/column-grouppadding-none/
-     *          No group padding - all columns are evenly spaced
-     * @product highcharts highstock
+     * @sample {highcharts} highcharts/plotoptions/column-grouppadding-default/
+     *         0.2 by default
+     * @sample {highcharts} highcharts/plotoptions/column-grouppadding-none/
+     *         No group padding - all columns are evenly spaced
+     *
+     * @product highcharts highstock gantt
      */
     groupPadding: 0.2,
 
@@ -118,14 +144,15 @@ seriesType('column', 'line', {
      * of each other. Non-grouped columns will be laid out individually
      * and overlap each other.
      *
-     * @type      {Boolean}
-     * @sample    {highcharts} highcharts/plotoptions/column-grouping-false/
-     *            Grouping disabled
-     * @sample    {highstock} highcharts/plotoptions/column-grouping-false/
-     *            Grouping disabled
+     * @sample {highcharts} highcharts/plotoptions/column-grouping-false/
+     *         Grouping disabled
+     * @sample {highstock} highcharts/plotoptions/column-grouping-false/
+     *         Grouping disabled
+     *
+     * @type      {boolean}
      * @default   true
      * @since     2.3.0
-     * @product   highcharts highstock
+     * @product   highcharts highstock gantt
      * @apioption plotOptions.column.grouping
      */
 
@@ -139,28 +166,30 @@ seriesType('column', 'line', {
      * of a bar in a bar chart. This prevents the columns from becoming
      * too wide when there is a small number of points in the chart.
      *
-     * @type      {Number}
-     * @see       [pointWidth](#plotOptions.column.pointWidth)
-     * @sample    {highcharts} highcharts/plotoptions/column-maxpointwidth-20/
-     *            Limited to 50
-     * @sample    {highstock} highcharts/plotoptions/column-maxpointwidth-20/
-     *            Limited to 50
-     * @default   null
+     * @see [pointWidth](#plotOptions.column.pointWidth)
+     *
+     * @sample {highcharts} highcharts/plotoptions/column-maxpointwidth-20/
+     *         Limited to 50
+     * @sample {highstock} highcharts/plotoptions/column-maxpointwidth-20/
+     *         Limited to 50
+     *
+     * @type      {number}
      * @since     4.1.8
-     * @product   highcharts highstock
+     * @product   highcharts highstock gantt
      * @apioption plotOptions.column.maxPointWidth
      */
 
     /**
      * Padding between each column or bar, in x axis units.
      *
-     * @sample  {highcharts} highcharts/plotoptions/column-pointpadding-default/
-     *          0.1 by default
-     * @sample  {highcharts} highcharts/plotoptions/column-pointpadding-025/
+     * @sample {highcharts} highcharts/plotoptions/column-pointpadding-default/
+     *         0.1 by default
+     * @sample {highcharts} highcharts/plotoptions/column-pointpadding-025/
      *          0.25
-     * @sample  {highcharts} highcharts/plotoptions/column-pointpadding-none/
-     *          0 for tightly packed columns
-     * @product highcharts highstock
+     * @sample {highcharts} highcharts/plotoptions/column-pointpadding-none/
+     *         0 for tightly packed columns
+     *
+     * @product highcharts highstock gantt
      */
     pointPadding: 0.1,
 
@@ -169,17 +198,30 @@ seriesType('column', 'line', {
      * `null`, the width is calculated from the `pointPadding` and
      * `groupPadding`.
      *
-     * @type      {Number}
-     * @see       [maxPointWidth](#plotOptions.column.maxPointWidth)
-     * @sample    {highcharts} highcharts/plotoptions/column-pointwidth-20/
-     *            20px wide columns regardless of chart width or the amount
-     *            of data points
-     * @default   null
+     * @see [maxPointWidth](#plotOptions.column.maxPointWidth)
+     *
+     * @sample {highcharts} highcharts/plotoptions/column-pointwidth-20/
+     *         20px wide columns regardless of chart width or the amount of data
+     *         points
+     *
+     * @type      {number}
      * @since     1.2.5
-     * @product   highcharts highstock
+     * @product   highcharts highstock gantt
      * @apioption plotOptions.column.pointWidth
      */
 
+    /**
+     * A pixel value specifying a fixed width for the column or bar. Overrides
+     * pointWidth on the series.
+     *
+     * @type      {Number}
+     * @see       [series.pointWidth](#plotOptions.column.pointWidth)
+     * @default   undefined
+     * @since     7.0.0
+     * @product   highcharts highstock gantt
+     * @apioption series.column.data.pointWidth
+     */
+
     /**
      * The minimal height for a column or width for a bar. By default,
      * 0 values are not shown. To visualize a 0 (or close to zero) point,
@@ -187,13 +229,12 @@ seriesType('column', 'line', {
      * column charts, minPointLength might not be respected for tightly
      * packed values.
      *
-     * @sample  {highcharts}
-     *          highcharts/plotoptions/column-minpointlength/
-     *          Zero base value
-     * @sample  {highcharts}
-     *          highcharts/plotoptions/column-minpointlength-pos-and-neg/
-     *          Positive and negative close to zero values
-     * @product highcharts highstock
+     * @sample {highcharts} highcharts/plotoptions/column-minpointlength/
+     *         Zero base value
+     * @sample {highcharts} highcharts/plotoptions/column-minpointlength-pos-and-neg/
+     *         Positive and negative close to zero values
+     *
+     * @product highcharts highstock gantt
      */
     minPointLength: 0,
 
@@ -205,9 +246,9 @@ seriesType('column', 'line', {
      * On the other hand, when the series contains more points than the
      * crop threshold, the series data is cropped to only contain points
      * that fall within the plot area. The advantage of cropping away invisible
-     * points is to increase performance on large series. .
+     * points is to increase performance on large series.
      *
-     * @product highcharts highstock
+     * @product highcharts highstock gantt
      */
     cropThreshold: 50,
 
@@ -221,12 +262,13 @@ seriesType('column', 'line', {
      * The default `null` means it is computed automatically, but this option
      * can be used to override the automatic value.
      *
-     * @type    {Number}
-     * @sample  {highcharts} highcharts/plotoptions/column-pointrange/
-     *          Set the point range to one day on a data set with one week
-     *          between the points
+     * @sample {highcharts} highcharts/plotoptions/column-pointrange/
+     *         Set the point range to one day on a data set with one week
+     *         between the points
+     *
+     * @type    {number|null}
      * @since   2.3
-     * @product highcharts highstock
+     * @product highcharts highstock gantt
      */
     pointRange: null,
 
@@ -237,29 +279,30 @@ seriesType('column', 'line', {
          * state options when a point is moused over or touched.
          *
          * @extends   plotOptions.series.states.hover
-         * @excluding halo,lineWidth,lineWidthPlus,marker
-         * @product   highcharts highstock
+         * @excluding halo, lineWidth, lineWidthPlus, marker
+         * @product   highcharts highstock gantt
          */
         hover: {
 
-            /** @ignore-option */
+            /**
+             * @ignore-option
+             */
             halo: false,
 
             /**
              * A specific border color for the hovered point. Defaults to
              * inherit the normal state border color.
              *
-             * @type      {Color}
-             * @product   highcharts
+             * @type      {Highcharts.ColorString}
+             * @product   highcharts gantt
              * @apioption plotOptions.column.states.hover.borderColor
              */
 
             /**
              * A specific color for the hovered point.
              *
-             * @type      {Color}
-             * @default   undefined
-             * @product   highcharts
+             * @type      {Highcharts.ColorString}
+             * @product   highcharts gantt
              * @apioption plotOptions.column.states.hover.color
              */
 
@@ -272,49 +315,66 @@ seriesType('column', 'line', {
              * In styled mode, the hover brightening is by default replaced
              * with a fill-opacity set in the `.highcharts-point:hover` rule.
              *
-             * @sample  {highcharts}
-             *          highcharts/plotoptions/column-states-hover-brightness/
-             *          Brighten by 0.5
-             * @product highcharts highstock
+             * @sample {highcharts} highcharts/plotoptions/column-states-hover-brightness/
+             *         Brighten by 0.5
+             *
+             * @product highcharts highstock gantt
              */
             brightness: 0.1
 
             
         },
+
         
 
         /**
          * Options for the selected point. These settings override the normal
          * state options when a point is selected.
          *
-         * @excluding halo,lineWidth,lineWidthPlus,marker
-         * @product highcharts highstock
+         * @extends   plotOptions.series.states.select
+         * @excluding halo, lineWidth, lineWidthPlus, marker
+         * @product   highcharts highstock gantt
          */
         select: {
+
             /**
              * A specific color for the selected point.
              *
-             * @type    {Color}
+             * @type    {Highcharts.ColorString}
              * @default #cccccc
-             * @product highcharts highstock
+             * @product highcharts highstock gantt
              */
             color: '#cccccc',
 
             /**
              * A specific border color for the selected point.
              *
-             * @type    {Color}
+             * @type    {Highcharts.ColorString}
              * @default #000000
-             * @product highcharts highstock
+             * @product highcharts highstock gantt
              */
             borderColor: '#000000'
         }
+
         
+
     },
 
     dataLabels: {
+
+        /**
+         * @type       {string|null}
+         */
         align: null, // auto
+
+        /**
+         * @type       {string|null}
+         */
         verticalAlign: null, // auto
+
+        /**
+         * @type       {number|null}
+         */
         y: null
     },
 
@@ -362,11 +422,12 @@ seriesType('column', 'line', {
      * In styled mode, the stroke width can be set with the `.highcharts-point`
      * rule.
      *
-     * @type      {Number}
-     * @sample    {highcharts} highcharts/plotoptions/column-borderwidth/
-     *            2px black border
+     * @sample {highcharts} highcharts/plotoptions/column-borderwidth/
+     *         2px black border
+     *
+     * @type      {number}
      * @default   1
-     * @product   highcharts highstock
+     * @product   highcharts highstock gantt
      * @apioption plotOptions.column.borderWidth
      */
 
@@ -376,11 +437,12 @@ seriesType('column', 'line', {
      * In styled mode, the border stroke can be set with the `.highcharts-point`
      * rule.
      *
-     * @type    {Color}
-     * @sample  {highcharts} highcharts/plotoptions/column-bordercolor/
-     *          Dark gray border
-     * @default #ffffff
-     * @product highcharts highstock
+     * @sample {highcharts} highcharts/plotoptions/column-bordercolor/
+     *         Dark gray border
+     *
+     * @type      {Highcharts.ColorString}
+     * @default   #ffffff
+     * @product   highcharts highstock gantt
      */
     borderColor: '#ffffff'
 
@@ -400,9 +462,8 @@ seriesType('column', 'line', {
      * Initialize the series. Extends the basic Series.init method by
      * marking other series of the same type as dirty.
      *
-     * @function #init
-     * @memberof seriesTypes.column
-     *
+     * @private
+     * @function Highcharts.seriesTypes.column#init
      */
     init: function () {
         Series.prototype.init.apply(this, arguments);
@@ -424,6 +485,11 @@ seriesType('column', 'line', {
     /**
      * Return the width and x offset of the columns adjusted for grouping,
      * groupPadding, pointPadding, pointWidth etc.
+     *
+     * @private
+     * @function Highcharts.seriesTypes.column#getColumnMetrics
+     *
+     * @return {Highcharts.ColumnMetricsObject}
      */
     getColumnMetrics: function () {
 
@@ -514,6 +580,19 @@ seriesType('column', 'line', {
 
     /**
      * Make the columns crisp. The edges are rounded to the nearest full pixel.
+     *
+     * @private
+     * @function Highcharts.seriesTypes.column#crispCol
+     *
+     * @param {number} x
+     *
+     * @param {number} y
+     *
+     * @param {number} w
+     *
+     * @param {number} h
+     *
+     * @return {*}
      */
     crispCol: function (x, y, w, h) {
         var chart = this.chart,
@@ -559,6 +638,9 @@ seriesType('column', 'line', {
     /**
      * Translate each point to the plot area coordinate system and find shape
      * positions
+     *
+     * @private
+     * @function Highcharts.seriesTypes.column#translate
      */
     translate: function () {
         var series = this,
@@ -576,11 +658,11 @@ seriesType('column', 'line', {
                 yAxis.getThreshold(threshold),
             minPointLength = pick(options.minPointLength, 5),
             metrics = series.getColumnMetrics(),
-            pointWidth = metrics.width,
+            seriesPointWidth = metrics.width,
             // postprocessed for border width
             seriesBarW = series.barW =
-                Math.max(pointWidth, 1 + 2 * borderWidth),
-            pointXOffset = series.pointXOffset = metrics.offset;
+                Math.max(seriesPointWidth, 1 + 2 * borderWidth),
+            seriesXOffset = series.pointXOffset = metrics.offset;
 
         if (chart.inverted) {
             translatedThreshold -= 0.5; // #3355
@@ -599,11 +681,12 @@ seriesType('column', 'line', {
         each(series.points, function (point) {
             var yBottom = pick(point.yBottom, translatedThreshold),
                 safeDistance = 999 + Math.abs(yBottom),
+                pointWidth = seriesPointWidth,
                 plotY = Math.min(
                     Math.max(-safeDistance, point.plotY),
                     yAxis.len + safeDistance
                 ), // Don't draw too far outside plot area (#1303, #2241, #4264)
-                barX = point.plotX + pointXOffset,
+                barX = point.plotX + seriesXOffset,
                 barW = seriesBarW,
                 barY = Math.min(plotY, yBottom),
                 up,
@@ -633,6 +716,13 @@ seriesType('column', 'line', {
                         translatedThreshold - (up ? minPointLength : 0);
             }
 
+            // Handle point.options.pointWidth
+            // TODO: Handle grouping/stacking as well. Calculate offset properly
+            if (defined(point.options.pointWidth)) {
+                pointWidth = barW = Math.ceil(point.options.pointWidth);
+                barX -= Math.round((pointWidth - seriesPointWidth) / 2);
+            }
+
             // Cache for access in polar
             point.barX = barX;
             point.pointWidth = pointWidth;
@@ -664,12 +754,24 @@ seriesType('column', 'line', {
 
     /**
      * Use a solid rectangle like the area series types
+     *
+     * @private
+     * @function Highcharts.seriesTypes.column#drawLegendSymbol
+     *
+     * @param {Highcharts.Legend} legend
+     *        The legend object
+     *
+     * @param {Highcharts.Series|Highcharts.Point} item
+     *        The series (this) or point
      */
     drawLegendSymbol: LegendSymbolMixin.drawRectangle,
 
 
     /**
      * Columns have no graph
+     *
+     * @private
+     * @function Highcharts.seriesTypes.column#drawGraph
      */
     drawGraph: function () {
         this.group[
@@ -680,6 +782,15 @@ seriesType('column', 'line', {
     
     /**
      * Get presentational attributes
+     *
+     * @private
+     * @function Highcharts.seriesTypes.column#pointAttribs
+     *
+     * @param {Highcharts.Point} point
+     *
+     * @param {string} state
+     *
+     * @return {Highcharts.Dictionary<any>}
      */
     pointAttribs: function (point, state) {
         var options = this.options,
@@ -742,6 +853,9 @@ seriesType('column', 'line', {
      * Draw the columns. For bars, the series.group is rotated, so the same
      * coordinates apply for columns and bars. This method is inherited by
      * scatter series.
+     *
+     * @private
+     * @function Highcharts.seriesTypes.column#drawPoints
      */
     drawPoints: function () {
         var series = this,
@@ -802,8 +916,13 @@ seriesType('column', 'line', {
     },
 
     /**
-     * Animate the column heights one by one from zero
-     * @param {Boolean} init Whether to initialize the animation or run it
+     * Animate the column heights one by one from zero.
+     *
+     * @private
+     * @function Highcharts.seriesTypes.column#animate
+     *
+     * @param {boolean} init
+     *        Whether to initialize the animation or run it
      */
     animate: function (init) {
         var series = this,
@@ -854,6 +973,9 @@ seriesType('column', 'line', {
 
     /**
      * Remove this series from the chart
+     *
+     * @private
+     * @function Highcharts.seriesTypes.column#remove
      */
     remove: function () {
         var series = this,
@@ -878,26 +1000,13 @@ seriesType('column', 'line', {
  * A `column` series. If the [type](#series.column.type) option is
  * not specified, it is inherited from [chart.type](#chart.type).
  *
- * @type      {Object}
  * @extends   series,plotOptions.column
- * @excluding connectNulls,dashStyle,dataParser,dataURL,gapSize,gapUnit,linecap,
- *            lineWidth,marker,connectEnds,step
+ * @excluding connectNulls, dashStyle, dataParser, dataURL, gapSize, gapUnit,
+ *            linecap, lineWidth, marker, connectEnds, step
  * @product   highcharts highstock
  * @apioption series.column
  */
 
-/**
- * @excluding halo,lineWidth,lineWidthPlus,marker
- * @product   highcharts highstock
- * @apioption series.column.states.hover
- */
-
-/**
- * @excluding halo,lineWidth,lineWidthPlus,marker
- * @product   highcharts highstock
- * @apioption series.column.states.select
- */
-
 /**
  * An array of data points for the series. For the `column` series type,
  * points can be given in the following ways:
@@ -943,19 +1052,20 @@ seriesType('column', 'line', {
  *     }]
  *  ```
  *
- * @type      {Array<Object|Array|Number>}
+ * @sample {highcharts} highcharts/chart/reflow-true/
+ *         Numerical values
+ * @sample {highcharts} highcharts/series/data-array-of-arrays/
+ *         Arrays of numeric x and y
+ * @sample {highcharts} highcharts/series/data-array-of-arrays-datetime/
+ *         Arrays of datetime x and y
+ * @sample {highcharts} highcharts/series/data-array-of-name-value/
+ *         Arrays of point.name and y
+ * @sample {highcharts} highcharts/series/data-array-of-objects/
+ *         Config objects
+ *
+ * @type      {Array<number|Array<number|string|Date>|*>}
  * @extends   series.line.data
  * @excluding marker
- * @sample    {highcharts} highcharts/chart/reflow-true/
- *            Numerical values
- * @sample    {highcharts} highcharts/series/data-array-of-arrays/
- *            Arrays of numeric x and y
- * @sample    {highcharts} highcharts/series/data-array-of-arrays-datetime/
- *            Arrays of datetime x and y
- * @sample    {highcharts} highcharts/series/data-array-of-name-value/
- *            Arrays of point.name and y
- * @sample    {highcharts} highcharts/series/data-array-of-objects/
- *            Config objects
  * @product   highcharts highstock
  * @apioption series.column.data
  */
@@ -966,10 +1076,10 @@ seriesType('column', 'line', {
  * In styled mode, the border stroke can be set with the `.highcharts-point`
  * rule.
  *
- * @type      {Color}
- * @sample    {highcharts} highcharts/plotoptions/column-bordercolor/
- *            Dark gray border
- * @default   undefined
+ * @sample {highcharts} highcharts/plotoptions/column-bordercolor/
+ *         Dark gray border
+ *
+ * @type      {Highcharts.ColorString}
  * @product   highcharts highstock
  * @apioption series.column.data.borderColor
  */
@@ -980,10 +1090,22 @@ seriesType('column', 'line', {
  * In styled mode, the stroke width can be set with the `.highcharts-point`
  * rule.
  *
- * @type      {Number}
- * @sample    {highcharts} highcharts/plotoptions/column-borderwidth/
- *            2px black border
- * @default   undefined
+ * @sample {highcharts} highcharts/plotoptions/column-borderwidth/
+ *         2px black border
+ *
+ * @type      {number}
  * @product   highcharts highstock
  * @apioption series.column.data.borderWidth
  */
+
+/**
+ * @excluding halo, lineWidth, lineWidthPlus, marker
+ * @product   highcharts highstock
+ * @apioption series.column.states.hover
+ */
+
+/**
+ * @excluding halo, lineWidth, lineWidthPlus, marker
+ * @product   highcharts highstock
+ * @apioption series.column.states.select
+ */