highcharts 6.1.1 → 6.2.0

package/es-modules/parts/Legend.js

@@ -1,11 +1,14 @@
 /**
- * (c) 2010-2017 Torstein Honsi
+ * (c) 2010-2018 Torstein Honsi
  *
  * License: www.highcharts.com/license
  */
+
 'use strict';
+
 import Highcharts from './Globals.js';
 import './Utilities.js';
+
 var H = Highcharts,
 
     addEvent = H.addEvent,
@@ -25,10 +28,17 @@ var H = Highcharts,
 
 /**
  * The overview of the chart's series. The legend object is instanciated
- * internally in the chart constructor, and available from `chart.legend`. Each
- * chart has only one legend.
+ * internally in the chart constructor, and is available from the `chart.legend`
+ * property. Each chart has only one legend.
  *
  * @class
+ * @name Highcharts.Legend
+ *
+ * @param {Highcharts.Chart} chart
+ *        The chart instance.
+ *
+ * @param {Highcharts.LegendOptions} options
+ *        Legend options.
  */
 Highcharts.Legend = function (chart, options) {
     this.init(chart, options);
@@ -40,9 +50,23 @@ Highcharts.Legend.prototype = {
      * Initialize the legend.
      *
      * @private
+     * @function Highcharts.Legend#init
+     *
+     * @param {Highcharts.Chart} chart
+     *        The chart instance.
+     *
+     * @param {Highcharts.LegendOptions} options
+     *        Legend options.
      */
     init: function (chart, options) {
 
+        /**
+         * Chart of this legend.
+         *
+         * @readonly
+         * @name Highcharts.Legend#chart
+         * @type {Highcharts.Chart}
+         */
         this.chart = chart;
 
         this.setOptions(options);
@@ -72,10 +96,23 @@ Highcharts.Legend.prototype = {
         }
     },
 
+    /**
+     * @private
+     * @function Highcharts.Legend#setOptions
+     *
+     * @param {Highcharts.LegendOptions} options
+     */
     setOptions: function (options) {
 
         var padding = pick(options.padding, 8);
 
+        /**
+         * Legend options.
+         *
+         * @readonly
+         * @name Highcharts.Legend#options
+         * @type {Highcharts.LegendOptions}
+         */
         this.options = options;
 
         
@@ -94,13 +131,20 @@ Highcharts.Legend.prototype = {
     /**
      * Update the legend with new options. Equivalent to running `chart.update`
      * with a legend configuration option.
-     * @param  {LegendOptions} options
-     *         Legend options.
-     * @param  {Boolean} [redraw=true]
-     *         Whether to redraw the chart.
      *
      * @sample highcharts/legend/legend-update/
      *         Legend update
+     *
+     * @function Highcharts.Legend#update
+     *
+     * @param {Highcharts.LegendOptions} options
+     *        Legend options.
+     *
+     * @param {boolean} [redraw=true]
+     *        Whether to redraw the chart.
+     *
+     * @todo
+     * Make events official: Fires the event `afterUpdate`.
      */
     update: function (options, redraw) {
         var chart = this.chart;
@@ -119,10 +163,16 @@ Highcharts.Legend.prototype = {
      * Set the colors for the legend item.
      *
      * @private
-     * @param  {Series|Point} item
-     *         A Series or Point instance
-     * @param  {Boolean} visible
-     *         Dimmed or colored
+     * @function Highcharts.Legend#colorizeItem
+     *
+     * @param {Highcharts.Point|Highcharts.Series} item
+     *        A Series or Point instance
+     *
+     * @param {boolean} [visible=false]
+     *        Dimmed or colored
+     *
+     * @todo
+     * Make events official: Fires the event `afterColorizeItem`.
      */
     colorizeItem: function (item, visible) {
         item.legendGroup[visible ? 'removeClass' : 'addClass'](
@@ -168,6 +218,10 @@ Highcharts.Legend.prototype = {
         fireEvent(this, 'afterColorizeItem', { item: item, visible: visible });
     },
 
+    /**
+     * @private
+     * @function Highcharts.Legend#positionItems
+     */
     positionItems: function () {
 
         // Now that the legend width and height are established, put the items
@@ -183,7 +237,9 @@ Highcharts.Legend.prototype = {
      * Position the legend item.
      *
      * @private
-     * @param {Series|Point} item
+     * @function Highcharts.Legend#positionItem
+     *
+     * @param {Highcharts.Point|Highcharts.Series} item
      *        The item to position
      */
     positionItem: function (item) {
@@ -215,7 +271,10 @@ Highcharts.Legend.prototype = {
     /**
      * Destroy a single legend item, used internally on removing series items.
      *
-     * @param {Series|Point} item
+     * @private
+     * @function Highcharts.Legend#destroyItem
+     *
+     * @param {Highcharts.Point|Highcharts.Series} item
      *        The item to remove
      */
     destroyItem: function (item) {
@@ -239,6 +298,9 @@ Highcharts.Legend.prototype = {
     /**
      * Destroy the legend. Used internally. To reflow objects, `chart.redraw`
      * must be called after destruction.
+     *
+     * @private
+     * @function Highcharts.Legend#destroy
      */
     destroy: function () {
         function destroyItems(key) {
@@ -270,6 +332,7 @@ Highcharts.Legend.prototype = {
      * Position the checkboxes after the width is determined.
      *
      * @private
+     * @function Highcharts.Legend#positionCheckboxes
      */
     positionCheckboxes: function () {
         var alignAttr = this.group && this.group.alignAttr,
@@ -290,8 +353,12 @@ Highcharts.Legend.prototype = {
                         left: (alignAttr.translateX + item.checkboxOffset +
                             checkbox.x - 20) + 'px',
                         top: top + 'px',
-                        display: top > translateY - 6 && top < translateY +
-                            clipHeight - 6 ? '' : 'none'
+                        display: this.proximate || (
+                            top > translateY - 6 &&
+                            top < translateY + clipHeight - 6
+                        ) ?
+                            '' :
+                            'none'
                     });
                 }
             }, this);
@@ -302,6 +369,7 @@ Highcharts.Legend.prototype = {
      * Render the legend title on top of the legend.
      *
      * @private
+     * @function Highcharts.Legend#renderTitle
      */
     renderTitle: function () {
         var options = this.options,
@@ -312,6 +380,13 @@ Highcharts.Legend.prototype = {
 
         if (titleOptions.text) {
             if (!this.title) {
+                /**
+                 * SVG element of the legend title.
+                 *
+                 * @readonly
+                 * @name Highcharts.Legend#title
+                 * @type {Highcharts.SVGElement}
+                 */
                 this.title = this.chart.renderer.label(
                         titleOptions.text,
                         padding - 3,
@@ -340,8 +415,10 @@ Highcharts.Legend.prototype = {
     /**
      * Set the legend item text.
      *
-     * @param  {Series|Point} item
-     *         The item for which to update the text in the legend.
+     * @function Highcharts.Legend#setText
+     *
+     * @param {Highcharts.Point|Highcharts.Series} item
+     *        The item for which to update the text in the legend.
      */
     setText: function (item) {
         var options = this.options;
@@ -357,7 +434,9 @@ Highcharts.Legend.prototype = {
      * function.
      *
      * @private
-     * @param {Series|Point} item
+     * @function Highcharts.Legend#renderItem
+     *
+     * @param {Highcharts.Point|Highcharts.Series} item
      *        The item to render.
      */
     renderItem: function (item) {
@@ -491,6 +570,9 @@ Highcharts.Legend.prototype = {
      * maxItemWidth from the previous loop.
      *
      * @private
+     * @function Highcharts.Legend#layoutItem
+     *
+     * @param {Highcharts.Point|Highcharts.Series} item
      */
     layoutItem: function (item) {
 
@@ -559,8 +641,16 @@ Highcharts.Legend.prototype = {
      * Get all items, which is one item per series for most series and one
      * item per point for pie series and its derivatives.
      *
-     * @return {Array<Series|Point>}
+     * @private
+     * @function Highcharts.Legend#getAllItems
+     *
+     * @return {Array<Highcharts.Point|Highcharts.Series>}
      *         The current items in the legend.
+     *
+     * @fires Highcharts.Legend#event:afterGetAllItems
+     *
+     * @todo
+     * Make events official: Fires the event `afterGetAllItems`.
      */
     getAllItems: function () {
         var allItems = [];
@@ -596,7 +686,10 @@ Highcharts.Legend.prototype = {
      * Get a short, three letter string reflecting the alignment and layout.
      *
      * @private
-     * @return {String} The alignment, empty string if floating
+     * @function Highcharts.Legend#getAlignment
+     *
+     * @return {string}
+     *         The alignment, empty string if floating
      */
     getAlignment: function () {
         var options = this.options;
@@ -619,6 +712,11 @@ Highcharts.Legend.prototype = {
      * reserved for horizontal legends and left or right for vertical ones.
      *
      * @private
+     * @function Highcharts.Legend#adjustMargins
+     *
+     * @param {Array<number>} margin
+     *
+     * @param {number} spacing
      */
     adjustMargins: function (margin, spacing) {
         var chart = this.chart,
@@ -662,6 +760,10 @@ Highcharts.Legend.prototype = {
         }
     },
 
+    /**
+     * @private
+     * @function Highcharts.Legend#proximatePositions
+     */
     proximatePositions: function () {
         var chart = this.chart,
             boxes = [],
@@ -688,7 +790,8 @@ Highcharts.Legend.prototype = {
                 height = item.legendGroup.getBBox().height;
                 boxes.push({
                     target: item.visible ?
-                        lastPoint.plotY - 0.3 * height :
+                        (lastPoint ? lastPoint.plotY : item.xAxis.height) -
+                            0.3 * height :
                         chart.plotHeight,
                     size: height,
                     item: item
@@ -708,6 +811,9 @@ Highcharts.Legend.prototype = {
      * `chart.render`. If called after, it will only rearrange items instead
      * of creating new ones. Called internally on initial render and after
      * redraws.
+     *
+     * @private
+     * @function Highcharts.Legend#render
      */
     render: function () {
         var legend = this,
@@ -729,6 +835,13 @@ Highcharts.Legend.prototype = {
         legend.lastItemY = 0;
 
         if (!legendGroup) {
+            /**
+             * SVG group of the legend.
+             *
+             * @readonly
+             * @name Highcharts.Legend#group
+             * @type {Highcharts.SVGElement}
+             */
             legend.group = legendGroup = renderer.g('legend')
                 .attr({ zIndex: 7 })
                 .add();
@@ -755,6 +868,14 @@ Highcharts.Legend.prototype = {
             allItems.reverse();
         }
 
+        /**
+         * All items for the legend, which is an array of series for most series
+         * and an array of points for pie series and its derivatives.
+         *
+         * @readonly
+         * @name Highcharts.Legend#allItems
+         * @type {Array<Highcharts.Point|Highcharts.Series>}
+         */
         legend.allItems = allItems;
         legend.display = display = !!allItems.length;
 
@@ -777,6 +898,13 @@ Highcharts.Legend.prototype = {
 
         // Draw the border and/or background
         if (!box) {
+            /**
+             * SVG element of the legend box.
+             *
+             * @readonly
+             * @name Highcharts.Legend#box
+             * @type {Highcharts.SVGElement}
+             */
             legend.box = box = renderer.rect()
                 .addClass('highcharts-legend-box')
                 .attr({
@@ -845,6 +973,11 @@ Highcharts.Legend.prototype = {
      * below the legend.
      *
      * @private
+     * @function Highcharts.Legend#handleOverflow
+     *
+     * @param {number} legendHeight
+     *
+     * @return {number}
      */
     handleOverflow: function (legendHeight) {
         var legend = this,
@@ -1006,10 +1139,15 @@ Highcharts.Legend.prototype = {
 
     /**
      * Scroll the legend by a number of pages.
-     * @param  {Number} scrollBy
-     *         The number of pages to scroll.
-     * @param  {AnimationOptions} animation
-     *         Whether and how to apply animation.
+     *
+     * @private
+     * @function Highcharts.Legend#scroll
+     *
+     * @param {number} scrollBy
+     *        The number of pages to scroll.
+     *
+     * @param {Highcharts.AnimationOptionsObject} animation
+     *        Whether and how to apply animation.
      */
     scroll: function (scrollBy, animation) {
         var pages = this.pages,
@@ -1086,17 +1224,25 @@ Highcharts.Legend.prototype = {
 
 };
 
-/*
- * LegendSymbolMixin
+/**
+ * Legend symbol mixin.
+ *
+ * @private
+ * @mixin Highcharts.LegendSymbolMixin
  */
-
 H.LegendSymbolMixin = {
 
     /**
      * Get the series' symbol in the legend
      *
-     * @param {Object} legend The legend object
-     * @param {Object} item The series (this) or point
+     * @private
+     * @function Highcharts.LegendSymbolMixin.drawRectangle
+     *
+     * @param {Highcharts.Legend} legend
+     *        The legend object
+     *
+     * @param {Highcharts.Point|Highcharts.Series} item
+     *        The series (this) or point
      */
     drawRectangle: function (legend, item) {
         var options = legend.options,
@@ -1123,7 +1269,11 @@ H.LegendSymbolMixin = {
      * to create custom symbols through
      * Highcharts.seriesTypes[type].prototype.drawLegendSymbols.
      *
-     * @param {Object} legend The legend object
+     * @private
+     * @function Highcharts.LegendSymbolMixin.drawLineMarker
+     *
+     * @param {Highcharts.Legend} legend
+     *        The legend object.
      */
     drawLineMarker: function (legend) {
 

package/es-modules/parts/LogarithmicAxis.js

@@ -1,22 +1,39 @@
 /**
- * (c) 2010-2017 Torstein Honsi
+ * (c) 2010-2018 Torstein Honsi
  *
  * License: www.highcharts.com/license
  */
+
 'use strict';
+
 import H from './Globals.js';
 import './Utilities.js';
+
 var Axis = H.Axis,
     getMagnitude = H.getMagnitude,
     map = H.map,
     normalizeTickInterval = H.normalizeTickInterval,
     pick = H.pick;
-/**
+
+/*
  * Methods defined on the Axis prototype
  */
 
 /**
- * Set the tick positions of a logarithmic axis
+ * Set the tick positions of a logarithmic axis.
+ *
+ * @private
+ * @function Highcharts.Axis#getLogTickPositions
+ *
+ * @param {number} interval
+ *
+ * @param {number} min
+ *
+ * @param {number} max
+ *
+ * @param {number} minor
+ *
+ * @return {Array<number>}
  */
 Axis.prototype.getLogTickPositions = function (interval, min, max, minor) {
     var axis = this,
@@ -127,10 +144,26 @@ Axis.prototype.getLogTickPositions = function (interval, min, max, minor) {
     return positions;
 };
 
+/**
+ * @private
+ * @function Highcharts.Axis#log2lin
+ *
+ * @param {number} num
+ *
+ * @return {number}
+ */
 Axis.prototype.log2lin = function (num) {
     return Math.log(num) / Math.LN10;
 };
 
+/**
+ * @private
+ * @function Highcharts.Axis#lin2log
+ *
+ * @param {number} num
+ *
+ * @return {number}
+ */
 Axis.prototype.lin2log = function (num) {
     return Math.pow(10, num);
 };

package/es-modules/parts/MSPointer.js

@@ -1,12 +1,15 @@
 /**
- * (c) 2010-2017 Torstein Honsi
+ * (c) 2010-2018 Torstein Honsi
  *
  * License: www.highcharts.com/license
  */
+
 'use strict';
+
 import H from './Globals.js';
 import './Utilities.js';
 import './Pointer.js';
+
 var addEvent = H.addEvent,
     charts = H.charts,
     css = H.css,
@@ -57,10 +60,15 @@ if (!hasTouch && (win.PointerEvent || win.MSPointerEvent)) {
             }
         };
 
-    /**
-     * Extend the Pointer prototype with methods for each event handler and more
-     */
+    // Extend the Pointer prototype with methods for each event handler and more
     extend(Pointer.prototype, /** @lends Pointer.prototype */ {
+
+        /**
+         * @private
+         * @function Highcharts.Pointer#onContainerPointerDown
+         *
+         * @param {Highcharts.PointerEventObject} e
+         */
         onContainerPointerDown: function (e) {
             translateMSPointer(
                 e,
@@ -75,6 +83,13 @@ if (!hasTouch && (win.PointerEvent || win.MSPointerEvent)) {
                 }
             );
         },
+
+        /**
+         * @private
+         * @function Highcharts.Pointer#onContainerPointerMove
+         *
+         * @param {Highcharts.PointerEventObject} e
+         */
         onContainerPointerMove: function (e) {
             translateMSPointer(
                 e,
@@ -88,6 +103,13 @@ if (!hasTouch && (win.PointerEvent || win.MSPointerEvent)) {
                 }
             );
         },
+
+        /**
+         * @private
+         * @function Highcharts.Pointer#onDocumentPointerUp
+         *
+         * @param {Highcharts.PointerEventObject} e
+         */
         onDocumentPointerUp: function (e) {
             translateMSPointer(
                 e,
@@ -101,6 +123,11 @@ if (!hasTouch && (win.PointerEvent || win.MSPointerEvent)) {
 
         /**
          * Add or remove the MS Pointer specific events
+         *
+         * @private
+         * @function Highcharts.Pointer#batchMSEvents
+         *
+         * @param {Function} fn
          */
         batchMSEvents: function (fn) {
             fn(