highcharts 6.1.4 → 6.2.0

package/es-modules/modules/xrange.src.js

@@ -1,12 +1,13 @@
 /**
  * X-range series module
  *
- * (c) 2010-2017 Torstein Honsi, Lars A. V. Cabrera
+ * (c) 2010-2018 Torstein Honsi, Lars A. V. Cabrera
  *
  * License: www.highcharts.com/license
  */
 
 'use strict';
+
 import H from '../parts/Globals.js';
 
 var addEvent = H.addEvent,
@@ -24,16 +25,47 @@ var addEvent = H.addEvent,
     Point = H.Point,
     Series = H.Series;
 
+/**
+ * Return color of a point based on its category.
+ *
+ * @param {object} series The series which the point belongs to.
+ * @param {object} point The point to calculate its color for.
+ * @returns {object} Returns an object containing the properties color and
+ * colorIndex.
+ */
+var getColorByCategory = function getColorByCategory(series, point) {
+    var colors = series.options.colors || series.chart.options.colors,
+        colorCount = colors ?
+            colors.length :
+            series.chart.options.chart.colorCount,
+        colorIndex = point.y % colorCount,
+        color = colors && colors[colorIndex];
+
+    return {
+        colorIndex: colorIndex,
+        color: color
+    };
+};
+
+/**
+ * @private
+ * @class
+ * @name Highcharts.seriesTypes.xrange
+ *
+ * @augments Highcharts.Series
+ */
+seriesType('xrange', 'column'
+
 /**
  * The X-range series displays ranges on the X axis, typically time intervals
  * with a start and end date.
  *
  * @extends      {plotOptions.column}
  * @excluding    boostThreshold,crisp,cropThreshold,depth,edgeColor,edgeWidth,
- *               findNearestPointBy,getExtremesFromAll,grouping,groupPadding,
- *               negativeColor,pointInterval,pointIntervalUnit,pointPlacement,
+ *               findNearestPointBy,getExtremesFromAll,negativeColor,
+ *               pointInterval,pointIntervalUnit,pointPlacement,
  *               pointRange,pointStart,softThreshold,stacking,threshold,data
- * @product      highcharts highstock
+ * @product      highcharts highstock gantt
  * @sample       {highcharts} highcharts/demo/x-range/
  *               X-range
  * @sample       {highcharts} highcharts/css/x-range/
@@ -41,18 +73,20 @@ var addEvent = H.addEvent,
  * @sample       {highcharts} highcharts/chart/inverted-xrange/
  *               Inverted X-range
  * @since        6.0.0
+ * @product      highcharts highstock
  * @optionparent plotOptions.xrange
  */
-seriesType('xrange', 'column', {
+, {
+
     /**
      * A partial fill for each point, typically used to visualize how much of
      * a task is performed. The partial fill object can be set either on series
      * or point level.
      *
-     * @sample    {highcharts} highcharts/demo/x-range
-     *            X-range with partial fill
-     * @type      {Object}
-     * @product   highcharts highstock
+     * @sample {highcharts} highcharts/demo/x-range
+     *         X-range with partial fill
+     *
+     * @product   highcharts highstock gantt
      * @apioption plotOptions.xrange.partialFill
      */
 
@@ -60,22 +94,42 @@ seriesType('xrange', 'column', {
      * The fill color to be used for partial fills. Defaults to a darker shade
      * of the point color.
      *
-     * @type      {Color}
-     * @product   highcharts highstock
+     * @type      {Highcharts.ColorString}
+     * @product   highcharts highstock gantt
      * @apioption plotOptions.xrange.partialFill.fill
      */
 
+    /**
+     * A partial fill for each point, typically used to visualize how much of
+     * a task is performed. The partial fill object can be set either on series
+     * or point level.
+     *
+     * @sample    {highcharts} highcharts/demo/x-range
+     *            X-range with partial fill
+     * @type      {Object}
+     * @extends   plotOptions.xrange.partialFill
+     * @apioption series.xrange.data.partialFill
+     */
+
+
     /**
      * In an X-range series, this option makes all points of the same Y-axis
      * category the same color.
      */
     colorByPoint: true,
+
     dataLabels: {
+
         verticalAlign: 'middle',
+
         inside: true,
+
         /**
          * The default formatter for X-range data labels displays the percentage
          * of the partial fill amount.
+         *
+         * @type    {Highcharts.FormatterCallbackFunction}
+         * @default function () { return (amount * 100) + '%'; }
          */
         formatter: function () {
             var point = this.point,
@@ -89,24 +143,35 @@ seriesType('xrange', 'column', {
             return (amount * 100) + '%';
         }
     },
+
     tooltip: {
+
         headerFormat: '<span style="font-size: 0.85em">{point.x} - {point.x2}</span><br/>',
+
         pointFormat: '<span style="color:{point.color}">\u25CF</span> {series.name}: <b>{point.yCategory}</b><br/>'
     },
+
     borderRadius: 3,
+
     pointRange: 0
 
 }, {
+
     type: 'xrange',
     parallelArrays: ['x', 'x2', 'y'],
     requireSorting: false,
     animate: seriesTypes.line.prototype.animate,
     cropShoulder: 1,
     getExtremesFromAll: true,
-
+    autoIncrement: H.noop,
     /**
      * Borrow the column series metrics, but with swapped axes. This gives free
      * access to features like groupPadding, grouping, pointWidth etc.
+     *
+     * @private
+     * @function Higcharts.seriesTypes.xrange#getColumnMetrics
+     *
+     * @return {Highcharts.ColumnMetricsObject}
      */
     getColumnMetrics: function () {
         var metrics,
@@ -132,6 +197,21 @@ seriesType('xrange', 'column', {
     /**
      * Override cropData to show a point where x or x2 is outside visible range,
      * but one of them is inside.
+     *
+     * @private
+     * @function Highcharts.seriesTypes.xrange#cropData
+     *
+     * @param {Array<number>} xData
+     *
+     * @param {Array<number>} yData
+     *
+     * @param {number} min
+     *
+     * @param {number} max
+     *
+     * @param {number} [cropShoulder]
+     *
+     * @return {*}
      */
     cropData: function (xData, yData, min, max) {
 
@@ -145,11 +225,19 @@ seriesType('xrange', 'column', {
         return crop;
     },
 
+    /**
+     * @private
+     * @function Highcharts.seriesTypes.xrange#translatePoint
+     *
+     * @param {Highcharts.Point} point
+     */
     translatePoint: function (point) {
         var series = this,
             xAxis = series.xAxis,
+            yAxis = series.yAxis,
             metrics = series.columnMetrics,
-            minPointLength = series.options.minPointLength || 0,
+            options = series.options,
+            minPointLength = options.minPointLength || 0,
             plotX = point.plotX,
             posX = pick(point.x2, point.x + (point.len || 0)),
             plotX2 = xAxis.translate(posX, 0, 0, 0, 1),
@@ -158,8 +246,10 @@ seriesType('xrange', 'column', {
             shapeArgs,
             partialFill,
             inverted = this.chart.inverted,
-            borderWidth = pick(series.options.borderWidth, 1),
+            borderWidth = pick(options.borderWidth, 1),
             crisper = borderWidth % 2 / 2,
+            yOffset = metrics.offset,
+            pointHeight = Math.round(metrics.width),
             dlLeft,
             dlRight,
             dlWidth;
@@ -176,11 +266,27 @@ seriesType('xrange', 'column', {
         plotX = Math.max(plotX, -10);
         plotX2 = Math.min(Math.max(plotX2, -10), xAxis.len + 10);
 
+        // Handle individual pointWidth
+        if (defined(point.options.pointWidth)) {
+            yOffset -= (Math.ceil(point.options.pointWidth) - pointHeight) / 2;
+            pointHeight = Math.ceil(point.options.pointWidth);
+        }
+
+        // Apply pointPlacement to the Y axis
+        if (
+            options.pointPlacement &&
+            isNumber(point.plotY) &&
+            yAxis.categories
+        ) {
+            point.plotY = yAxis
+                .translate(point.y, 0, 1, 0, 1, options.pointPlacement);
+        }
+
         point.shapeArgs = {
             x: Math.floor(Math.min(plotX, plotX2)) + crisper,
-            y: Math.floor(point.plotY + metrics.offset) + crisper,
+            y: Math.floor(point.plotY + yOffset) + crisper,
             width: Math.round(Math.abs(plotX2 - plotX)),
-            height: Math.round(metrics.width),
+            height: pointHeight,
             r: series.options.borderRadius
         };
 
@@ -203,7 +309,7 @@ seriesType('xrange', 'column', {
 
         // Tooltip position
         point.tooltipPos[0] += inverted ? 0 : length / 2;
-        point.tooltipPos[1] -= inverted ? length / 2 : metrics.width / 2;
+        point.tooltipPos[1] -= inverted ? -length / 2 : metrics.width / 2;
 
         // Add a partShapeArgs to the point, based on the shapeArgs property
         partialFill = point.partialFill;
@@ -237,8 +343,17 @@ seriesType('xrange', 'column', {
                 height: shapeArgs.height
             };
         }
+
+        // Category from Y axis
+        if (yAxis.categories) {
+            point.category = yAxis.categories[point.y];
+        }
     },
 
+    /**
+     * @private
+     * @function Highcharts.seriesTypes.xrange#translate
+     */
     translate: function () {
         columnType.prototype.translate.apply(this, arguments);
         each(this.points, function (point) {
@@ -252,10 +367,14 @@ seriesType('xrange', 'column', {
      * This override turns point.graphic into a group containing the original
      * graphic and an overlay displaying the partial fill.
      *
-     * @param   {Object} point an instance of Point in the series
-     * @param   {string} verb 'animate' (animates changes) or 'attr' (sets
-     *                   options)
-     * @returns {void}
+     * @private
+     * @function Highcharts.seriesTypes.xrange#drawPoint
+     *
+     * @param {Highcharts.Point} point
+     *        An instance of Point in the series.
+     *
+     * @param {"animate"|"attr"} verb
+     *        'animate' (animates changes) or 'attr' (sets options)
      */
     drawPoint: function (point, verb) {
         var series = this,
@@ -350,6 +469,10 @@ seriesType('xrange', 'column', {
         }
     },
 
+    /**
+     * @private
+     * @function Highcharts.seriesTypes.xrange#drawPoints
+     */
     drawPoints: function () {
         var series = this,
             verb = series.getAnimationVerb();
@@ -365,7 +488,10 @@ seriesType('xrange', 'column', {
      * Returns "animate", or "attr" if the number of points is above the
      * animation limit.
      *
-     * @returns {String}
+     * @private
+     * @function Highcharts.seriesTypes.xrange#getAnimationVerb
+     *
+     * @return {string}
      */
     getAnimationVerb: function () {
         return this.chart.pointCount < (this.options.animationLimit || 250) ?
@@ -375,6 +501,12 @@ seriesType('xrange', 'column', {
     /**
      * Override to remove stroke from points.
      * For partial fill.
+     *
+     * @ignore
+     * @private
+     * @function Highcharts.seriesTypes.xrange#pointAttribs
+     *
+     * @return {*}
      * /
     pointAttribs: function () {
         var series = this,
@@ -385,46 +517,67 @@ seriesType('xrange', 'column', {
     }
     //*/
 
-// Point class properties
-}, {
+}, { // Point class properties
+    /**
+     * Extend applyOptions so that `colorByPoint` for x-range means that one
+     * color is applied per Y axis category.
+     *
+     * @private
+     * @function Highcharts.Point#applyOptions
+     *
+     * @return {Highcharts.Series}
+     */
+    applyOptions: function () {
+        var point = Point.prototype.applyOptions.apply(this, arguments),
+            series = point.series,
+            colorByPoint;
+
+        if (series.options.colorByPoint && !point.options.color) {
+            colorByPoint = getColorByCategory(series, point);
+            
+            point.color = colorByPoint.color;
+            
+            if (!point.options.colorIndex) {
+                point.colorIndex = colorByPoint.colorIndex;
+            }
+        }
 
+        return point;
+    },
     /**
-     * Extend init so that `colorByPoint` for x-range means that one color is
-     * applied per Y axis category.
+     * Extend init to have y default to 0.
+     *
+     * @private
+     * @function Highcharts.Point#init
+     *
+     * @return {Highcharts.Series}
      */
     init: function () {
-
         Point.prototype.init.apply(this, arguments);
 
-        var colors,
-            series = this.series,
-            colorCount = series.chart.options.chart.colorCount;
-
         if (!this.y) {
             this.y = 0;
         }
 
-        
-        if (series.options.colorByPoint) {
-            colors = series.options.colors || series.chart.options.colors;
-            colorCount = colors.length;
-
-            if (!this.options.color && colors[this.y % colorCount]) {
-                this.color = colors[this.y % colorCount];
-            }
-        }
-        
-        this.colorIndex = pick(this.options.colorIndex, this.y % colorCount);
-
         return this;
     },
 
+    /**
+     * @private
+     * @function Highcharts.Point#setState
+     */
     setState: function () {
         Point.prototype.setState.apply(this, arguments);
 
         this.series.drawPoint(this, this.series.getAnimationVerb());
     },
 
+    /**
+     * @private
+     * @function Highcharts.Point#getLabelConfig
+     *
+     * @return {Highcharts.PointLabelObject}
+     */
     // Add x2 and yCategory to the available properties for tooltip formats
     getLabelConfig: function () {
         var point = this,
@@ -437,15 +590,19 @@ seriesType('xrange', 'column', {
     },
     tooltipDateKeys: ['x', 'x2'],
 
+    /**
+     * @private
+     * @function Highcharts.Point#isValid
+     *
+     * @return {boolean}
+     */
     isValid: function () {
         return typeof this.x === 'number' &&
             typeof this.x2 === 'number';
     }
 });
 
-/**
- * Max x2 should be considered in xAxis extremes
- */
+// Max x2 should be considered in xAxis extremes
 addEvent(Axis, 'afterGetSeriesExtremes', function () {
     var axis = this,
         axisSeries = axis.series,
@@ -475,13 +632,12 @@ addEvent(Axis, 'afterGetSeriesExtremes', function () {
  * An `xrange` series. If the [type](#series.xrange.type) option is not
  * specified, it is inherited from [chart.type](#chart.type).
  *
- * @type      {Object}
  * @extends   series,plotOptions.xrange
  * @excluding boostThreshold,crisp,cropThreshold,depth,edgeColor,edgeWidth,
- *            findNearestPointBy,getExtremesFromAll,grouping,groupPadding,
+ *            findNearestPointBy,getExtremesFromAll,
  *            negativeColor,pointInterval,pointIntervalUnit,pointPlacement,
  *            pointRange,pointStart,softThreshold,stacking,threshold
- * @product   highcharts highstock
+ * @product   highcharts highstock gantt
  * @apioption series.xrange
  */
 
@@ -508,30 +664,54 @@ addEvent(Axis, 'afterGetSeriesExtremes', function () {
  *     }]
  *  ```
  *
- * @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>|*>}
  * @extends   series.line.data
- * @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
+ * @product   highcharts highstock gantt
  * @apioption series.xrange.data
  */
 
+/**
+ * The starting X value of the range point.
+ *
+ * @sample {highcharts} highcharts/demo/x-range
+ *         X-range
+ *
+ * @type      {number}
+ * @product   highcharts highstock gantt
+ * @apioption series.xrange.data.x
+ */
+
 /**
  * The ending X value of the range point.
  *
- * @sample    {highcharts} highcharts/demo/x-range
- *            X-range
- * @type      {Number}
- * @product   highcharts highstock
- * @apioption plotOptions.xrange.data.x2
+ * @sample {highcharts} highcharts/demo/x-range
+ *         X-range
+ *
+ * @type      {number}
+ * @product   highcharts highstock gantt
+ * @apioption series.xrange.data.x2
+ */
+
+/**
+ * The Y value of the range point.
+ *
+ * @sample {highcharts} highcharts/demo/x-range
+ *         X-range
+ *
+ * @type      {number}
+ * @product   highcharts highstock gantt
+ * @apioption series.xrange.data.y
  */
 
 /**
@@ -539,27 +719,27 @@ addEvent(Axis, 'afterGetSeriesExtremes', function () {
  * a task is performed. The partial fill object can be set either on series
  * or point level.
  *
- * @sample    {highcharts} highcharts/demo/x-range
- *            X-range with partial fill
- * @type      {Object|Number}
- * @product   highcharts highstock
- * @apioption plotOptions.xrange.data.partialFill
+ * @sample {highcharts} highcharts/demo/x-range
+ *         X-range with partial fill
+ *
+ * @product   highcharts highstock gantt
+ * @apioption series.xrange.data.partialFill
  */
 
 /**
  * The amount of the X-range point to be filled. Values can be 0-1 and are
  * converted to percentages in the default data label formatter.
  *
- * @type      {Number}
- * @product   highcharts highstock
- * @apioption plotOptions.xrange.data.partialFill.amount
+ * @type      {number}
+ * @product   highcharts highstock gantt
+ * @apioption series.xrange.data.partialFill.amount
  */
 
 /**
  * The fill color to be used for partial fills. Defaults to a darker shade
  * of the point color.
  *
- * @type      {Color}
- * @product   highcharts highstock
- * @apioption plotOptions.xrange.data.partialFill.fill
+ * @type      {Highcharts.ColorString}
+ * @product   highcharts highstock gantt
+ * @apioption series.xrange.data.partialFill.fill
  */