highcharts-rails 5.0.12 → 5.0.13

data/app/assets/javascripts/highcharts/modules/broken-axis.js

@@ -1,5 +1,5 @@
 /**
- * @license Highcharts JS v5.0.12 (2017-05-24)
+ * @license Highcharts JS v5.0.13 (2017-07-27)
  *
  * (c) 2009-2017 Torstein Honsi
  *
@@ -347,19 +347,80 @@
         H.Series.prototype.gappedPath = function() {
             var gapSize = this.options.gapSize,
                 points = this.points.slice(),
-                i = points.length - 1;
+                i = points.length - 1,
+                yAxis = this.yAxis,
+                xRange,
+                stack;
+
+            /**
+             * Defines when to display a gap in the graph, together with the `gapUnit`
+             * option.
+             * 
+             * When the `gapUnit` is `relative` (default), a gap size of 5 means
+             * that if the distance between two points is greater than five times
+             * that of the two closest points, the graph will be broken.
+             *
+             * When the `gapUnit` is `value`, the gap is based on absolute axis values,
+             * which on a datetime axis is milliseconds.
+             * 
+             * In practice, this option is most often used to visualize gaps in
+             * time series. In a stock chart, intraday data is available for daytime
+             * hours, while gaps will appear in nights and weekends.
+             * 
+             * @type {Number}
+             * @see [xAxis.breaks](#xAxis.breaks)
+             * @sample {highstock} stock/plotoptions/series-gapsize/
+             *         Setting the gap size to 2 introduces gaps for weekends in daily
+             *         datasets.
+             * @default 0
+             * @product highstock
+             * @apioption plotOptions.series.gapSize
+             */
+
+            /**
+             * Together with `gapSize`, this option defines where to draw gaps in the 
+             * graph.
+             *
+             * @type {String}
+             * @see [gapSize](plotOptions.series.gapSize)
+             * @default relative
+             * @validvalues ["relative", "value"]
+             * @since 5.0.13
+             * @product highstock
+             * @apioption plotOptions.series.gapUnit
+             */
 
             if (gapSize && i > 0) { // #5008
 
+                // Gap unit is relative
+                if (this.options.gapUnit !== 'value') {
+                    gapSize *= this.closestPointRange;
+                }
+
                 // extension for ordinal breaks
                 while (i--) {
-                    if (points[i + 1].x - points[i].x > this.closestPointRange * gapSize) {
+                    if (points[i + 1].x - points[i].x > gapSize) {
+                        xRange = (points[i].x + points[i + 1].x) / 2;
+
                         points.splice( // insert after this one
                             i + 1,
                             0, {
-                                isNull: true
+                                isNull: true,
+                                x: xRange
                             }
                         );
+
+                        // For stacked chart generate empty stack items, #6546
+                        if (this.options.stacking) {
+                            stack = yAxis.stacks[this.stackKey][xRange] = new H.StackItem(
+                                yAxis,
+                                yAxis.options.stackLabels,
+                                false,
+                                xRange,
+                                this.stack
+                            );
+                            stack.total = 0;
+                        }
                     }
                 }
             }

data/app/assets/javascripts/highcharts/modules/data.js

@@ -1,5 +1,5 @@
 /**
- * @license Highcharts JS v5.0.12 (2017-05-24)
+ * @license Highcharts JS v5.0.13 (2017-07-27)
  * Data module
  *
  * (c) 2012-2017 Torstein Honsi

data/app/assets/javascripts/highcharts/modules/drilldown.js

@@ -1,5 +1,5 @@
 /**
- * @license Highcharts JS v5.0.12 (2017-05-24)
+ * @license Highcharts JS v5.0.13 (2017-07-27)
  * Highcharts Drilldown module
  * 
  * Author: Torstein Honsi
@@ -46,28 +46,158 @@
         extend(defaultOptions.lang, {
             drillUpText: '◁ Back to {series.name}'
         });
+
+        /**
+         * Options for drill down, the concept of inspecting increasingly high 
+         * resolution data through clicking on chart items like columns or pie slices.
+         *
+         * The drilldown feature requires the drilldown.js file to be loaded, 
+         * found in the modules directory of the download package, or online at 
+         * (code.highcharts.com/modules/drilldown.js)[code.highcharts.com/modules/drilldown.js].
+         *
+         * @type {Object}
+         * @optionparent drilldown
+         */
         defaultOptions.drilldown = {
 
+
+            /**
+             * Additional styles to apply to the X axis label for a point that
+             * has drilldown data. By default it is underlined and blue to invite
+             * to interaction.
+             * 
+             * @type {CSSObject}
+             * @see In [styled mode](http://www.highcharts.com/docs/chart-design-and-
+             * style/style-by-css), active label styles can be set with the `.highcharts-
+             * drilldown-axis-label` class.
+             * @sample {highcharts} highcharts/drilldown/labels/ Label styles
+             * @default { "cursor": "pointer", "color": "#003399", "fontWeight": "bold", "textDecoration": "underline" }
+             * @since 3.0.8
+             * @product highcharts highmaps
+             */
             activeAxisLabelStyle: {
+
+                /**
+                 */
                 cursor: 'pointer',
+
+                /**
+                 */
                 color: '#003399',
+
+                /**
+                 */
                 fontWeight: 'bold',
+
+                /**
+                 */
                 textDecoration: 'underline'
             },
+
+            /**
+             * Additional styles to apply to the data label of a point that has
+             * drilldown data. By default it is underlined and blue to invite to
+             * interaction.
+             * 
+             * @type {CSSObject}
+             * @see In [styled mode](http://www.highcharts.com/docs/chart-design-and-
+             * style/style-by-css), active data label styles can be applied with
+             * the `.highcharts-drilldown-data-label` class.
+             * @sample {highcharts} highcharts/drilldown/labels/ Label styles
+             * @default { "cursor": "pointer", "color": "#003399", "fontWeight": "bold", "textDecoration": "underline" }
+             * @since 3.0.8
+             * @product highcharts highmaps
+             */
             activeDataLabelStyle: {
+
+                /**
+                 */
                 cursor: 'pointer',
+
+                /**
+                 */
                 color: '#003399',
+
+                /**
+                 */
                 fontWeight: 'bold',
+
+                /**
+                 */
                 textDecoration: 'underline'
             },
 
+
+            /**
+             * Set the animation for all drilldown animations. Animation of a drilldown
+             * occurs when drilling between a column point and a column series,
+             * or a pie slice and a full pie series. Drilldown can still be used
+             * between series and points of different types, but animation will
+             * not occur.
+             * 
+             * The animation can either be set as a boolean or a configuration
+             * object. If `true`, it will use the 'swing' jQuery easing and a duration
+             * of 500 ms. If used as a configuration object, the following properties
+             * are supported:
+             * 
+             * <dl>
+             * 
+             * <dt>duration</dt>
+             * 
+             * <dd>The duration of the animation in milliseconds.</dd>
+             * 
+             * <dt>easing</dt>
+             * 
+             * <dd>A string reference to an easing function set on the `Math` object.
+             * See [the easing demo](http://jsfiddle.net/gh/get/library/pure/highcharts/highcharts/tree/master/samples/highcharts/plotoptions/series-
+             * animation-easing/).</dd>
+             * 
+             * </dl>
+             * 
+             * @type {Boolean|Object}
+             * @since 3.0.8
+             * @product highcharts highmaps
+             */
             animation: {
+
+                /**
+                 */
                 duration: 500
             },
+
+            /**
+             * Options for the drill up button that appears when drilling down
+             * on a series. The text for the button is defined in [lang.drillUpText](#lang.
+             * drillUpText).
+             * 
+             * @type {Object}
+             * @sample {highcharts} highcharts/drilldown/drillupbutton/ Drill up button
+             * @sample {highmaps} highcharts/drilldown/drillupbutton/ Drill up button
+             * @since 3.0.8
+             * @product highcharts highmaps
+             */
             drillUpButton: {
+
+                /**
+                 * Positioning options for the button within the `relativeTo` box.
+                 * Available properties are `x`, `y`, `align` and `verticalAlign`.
+                 * 
+                 * @type {Object}
+                 * @since 3.0.8
+                 * @product highcharts highmaps
+                 */
                 position: {
+
+                    /**
+                     */
                     align: 'right',
+
+                    /**
+                     */
                     x: -10,
+
+                    /**
+                     */
                     y: 10
                 }
                 // relativeTo: 'plotBox'
@@ -75,6 +205,72 @@
             }
         };
 
+
+
+        /**
+         * Fires when a drilldown point is clicked, before the new series is
+         * added. This event is also utilized for async drilldown, where the
+         * seriesOptions are not added by option, but rather loaded async. Note
+         * that when clicking a category label to trigger multiple series drilldown,
+         * one `drilldown` event is triggered per point in the category.
+         * 
+         * Event arguments:
+         * 
+         * <dl>
+         * 
+         * <dt>`category`</dt>
+         * 
+         * <dd>If a category label was clicked, which index.</dd>
+         * 
+         * <dt>`point`</dt>
+         * 
+         * <dd>The originating point.</dd>
+         * 
+         * <dt>`originalEvent`</dt>
+         * 
+         * <dd>The original browser event (usually click) that triggered the
+         * drilldown.</dd>
+         * 
+         * <dt>`points`</dt>
+         * 
+         * <dd>If a category label was clicked, this array holds all points
+         * corresponing to the category.</dd>
+         * 
+         * <dt>`seriesOptions`</dt>
+         * 
+         * <dd>Options for the new series</dd>
+         * 
+         * </dl>
+         * 
+         * @type {Function}
+         * @context Chart
+         * @sample {highcharts} highcharts/drilldown/async/ Async drilldown
+         * @since 3.0.8
+         * @product highcharts highmaps
+         * @apioption chart.events.drilldown
+         */
+
+        /**
+         * Fires when drilling up from a drilldown series.
+         * 
+         * @type {Function}
+         * @context Chart
+         * @since 3.0.8
+         * @product highcharts highmaps
+         * @apioption chart.events.drillup
+         */
+
+        /**
+         * In a chart with multiple drilldown series, this event fires after
+         * all the series have been drilled up.
+         * 
+         * @type {Function}
+         * @context Chart
+         * @since 4.2.4
+         * @product highcharts highmaps
+         * @apioption chart.events.drillupall
+         */
+
         /**
          * A general fadeIn method
          */
@@ -282,10 +478,10 @@
 
         /**
          * When the chart is drilled down to a child series, calling `chart.drillUp()`
-         * will drill up to the parent series.
+         * will drill up to the parent series. Requires the drilldown module.
          *
+         * @function drillUp
          * @memberOf Highcharts.Chart
-         * @name #drillUp
          */
         Chart.prototype.drillUp = function() {
             var chart = this,
@@ -380,8 +576,6 @@
         };
 
 
-        ColumnSeries.prototype.supportsDrilldown = true;
-
         /**
          * When drilling up, keep the upper series invisible until the lower series has
          * moved into place
@@ -550,7 +744,6 @@
 
         if (PieSeries) {
             extend(PieSeries.prototype, {
-                supportsDrilldown: true,
                 animateDrillupTo: ColumnSeries.prototype.animateDrillupTo,
                 animateDrillupFrom: ColumnSeries.prototype.animateDrillupFrom,
 
@@ -758,11 +951,19 @@
             proceed.call(this);
 
             each(this.points, function(point) {
-                var pointCSS = {};
+                var dataLabelsOptions = point.options.dataLabels,
+                    pointCSS = pick(
+                        point.dlOptions,
+                        dataLabelsOptions && dataLabelsOptions.style, {}
+                    );
+
                 if (point.drilldown && point.dataLabel) {
                     if (css.color === 'contrast') {
                         pointCSS.color = renderer.getContrast(point.color || this.color);
                     }
+                    if (dataLabelsOptions && dataLabelsOptions.color) {
+                        pointCSS.color = dataLabelsOptions.color;
+                    }
                     point.dataLabel
                         .addClass('highcharts-drilldown-data-label');
 
@@ -775,26 +976,42 @@
             }, this);
         });
 
+
+        var applyCursorCSS = function(element, cursor, addClass) {
+            element[addClass ? 'addClass' : 'removeClass']('highcharts-drilldown-point');
+
+
+            element.css({
+                cursor: cursor
+            });
+
+        };
+
         // Mark the trackers with a pointer 
         var drawTrackerWrapper = function(proceed) {
             proceed.call(this);
             each(this.points, function(point) {
                 if (point.drilldown && point.graphic) {
-                    point.graphic.addClass('highcharts-drilldown-point');
-
-
-                    point.graphic.css({
-                        cursor: 'pointer'
-                    });
-
+                    applyCursorCSS(point.graphic, 'pointer', true);
                 }
             });
         };
 
-        objectEach(seriesTypes, function(seriesType) {
-            if (seriesType.prototype.supportsDrilldown) {
-                wrap(seriesType.prototype, 'drawTracker', drawTrackerWrapper);
+        var setPointStateWrapper = function(proceed, state) {
+            var ret = proceed.apply(this, Array.prototype.slice.call(arguments, 1));
+
+            if (this.drilldown && this.series.halo && state === 'hover') {
+                applyCursorCSS(this.series.halo, 'pointer', true);
+            } else if (this.series.halo) {
+                applyCursorCSS(this.series.halo, 'auto', false);
             }
+            return ret;
+        };
+
+
+        objectEach(seriesTypes, function(seriesType) {
+            wrap(seriesType.prototype, 'drawTracker', drawTrackerWrapper);
+            wrap(seriesType.prototype.pointClass.prototype, 'setState', setPointStateWrapper);
         });
 
     }(Highcharts));

data/app/assets/javascripts/highcharts/modules/exporting.js

@@ -1,5 +1,5 @@
 /**
- * @license Highcharts JS v5.0.12 (2017-05-24)
+ * @license Highcharts JS v5.0.13 (2017-07-27)
  * Exporting module
  *
  * (c) 2010-2017 Torstein Honsi
@@ -49,6 +49,9 @@
             isFirefoxBrowser = /firefox/i.test(userAgent);
 
         // Add language
+        /**
+         * @apioption lang
+         */
         extend(defaultOptions.lang, {
             printChart: 'Print chart',
             downloadPNG: 'Download PNG image',
@@ -60,6 +63,10 @@
 
         // Buttons and menus are collected in a separate config option set called 'navigation'.
         // This can be extended later to add control buttons like zoom and pan right click menus.
+
+        /**
+         * @apioption navigation
+         */
         defaultOptions.navigation = {
             buttonOptions: {
                 theme: {},
@@ -77,91 +84,503 @@
 
 
         // Presentational attributes
-        merge(true, defaultOptions.navigation, {
-            menuStyle: {
-                border: '1px solid #999999',
-                background: '#ffffff',
-                padding: '5px 0'
-            },
-            menuItemStyle: {
-                padding: '0.5em 1em',
-                background: 'none',
-                color: '#333333',
-                fontSize: isTouchDevice ? '14px' : '11px',
-                transition: 'background 250ms, color 250ms'
-            },
-            menuItemHoverStyle: {
-                background: '#335cad',
-                color: '#ffffff'
-            },
-            buttonOptions: {
-                symbolFill: '#666666',
-                symbolStroke: '#666666',
-                symbolStrokeWidth: 3,
-                theme: {
-                    fill: '#ffffff', // capture hover
-                    stroke: 'none',
-                    padding: 5
+
+        merge(true, defaultOptions.navigation,
+            /**
+             * A collection of options for buttons and menus appearing in the exporting module.
+             * @type {Object}
+             * @optionparent navigation
+             */
+            {
+
+                /**
+                 * CSS styles for the popup menu appearing by default when the export
+                 * icon is clicked. This menu is rendered in HTML.
+                 * 
+                 * @type {CSSObject}
+                 * @see In [styled mode](http://www.highcharts.com/docs/chart-design-and-
+                 * style/style-by-css), the menu is styled with the `.highcharts-menu`
+                 * class.
+                 * @sample {highcharts} highcharts/navigation/menustyle/ Light gray menu background
+                 * @sample {highstock} highcharts/navigation/menustyle/ Light gray menu background
+                 * @sample {highmaps} highcharts/navigation/menustyle/ Light gray menu background
+                 * @default { "border": "1px solid #999999", "background": "#ffffff", "padding": "5px 0" }
+                 * @since 2.0
+                 * @product highcharts highstock highmaps
+                 */
+                menuStyle: {
+
+                    /**
+                     */
+                    border: '1px solid #999999',
+
+                    /**
+                     */
+                    background: '#ffffff',
+
+                    /**
+                     */
+                    padding: '5px 0'
+                },
+
+                /**
+                 * CSS styles for the individual items within the popup menu appearing
+                 * by default when the export icon is clicked. The menu items are rendered
+                 * in HTML.
+                 * 
+                 * @type {CSSObject}
+                 * @see In [styled mode](http://www.highcharts.com/docs/chart-design-and-
+                 * style/style-by-css), the menu items are styled with the `.highcharts-
+                 * menu-item` class.
+                 * @sample {highcharts} highcharts/navigation/menuitemstyle/ Add a grey stripe to the left
+                 * @sample {highstock} highcharts/navigation/menuitemstyle/ Add a grey stripe to the left
+                 * @sample {highmaps} highcharts/navigation/menuitemstyle/ Add a grey stripe to the left
+                 * @default { "padding": "0.5em 1em", "color": "#333333", "background": "none" }
+                 * @since 2.0
+                 * @product highcharts highstock highmaps
+                 */
+                menuItemStyle: {
+
+                    /**
+                     */
+                    padding: '0.5em 1em',
+
+                    /**
+                     */
+                    background: 'none',
+
+                    /**
+                     */
+                    color: '#333333',
+
+                    /**
+                     */
+                    fontSize: isTouchDevice ? '14px' : '11px',
+
+                    /**
+                     */
+                    transition: 'background 250ms, color 250ms'
+                },
+
+                /**
+                 * CSS styles for the hover state of the individual items within the
+                 * popup menu appearing by default when the export icon is clicked.
+                 *  The menu items are rendered in HTML.
+                 * 
+                 * @type {CSSObject}
+                 * @see In [styled mode](http://www.highcharts.com/docs/chart-design-and-
+                 * style/style-by-css), the menu items are styled with the `.highcharts-
+                 * menu-item` class.
+                 * @sample {highcharts} highcharts/navigation/menuitemhoverstyle/ Bold text on hover
+                 * @sample {highstock} highcharts/navigation/menuitemhoverstyle/ Bold text on hover
+                 * @sample {highmaps} highcharts/navigation/menuitemhoverstyle/ Bold text on hover
+                 * @default { "background": "#335cad", "color": "#ffffff" }
+                 * @since 2.0
+                 * @product highcharts highstock highmaps
+                 */
+                menuItemHoverStyle: {
+
+                    /**
+                     */
+                    background: '#335cad',
+
+                    /**
+                     */
+                    color: '#ffffff'
+                },
+
+                /**
+                 * A collection of options for buttons appearing in the exporting module.
+                 * 
+                 * 
+                 * In [styled mode](http://www.highcharts.com/docs/chart-design-and-
+                 * style/style-by-css), the buttons are styled with the `.highcharts-
+                 * contextbutton` and `.highcharts-button-symbol` class.
+                 * 
+                 * @product highcharts highstock highmaps
+                 */
+                buttonOptions: {
+
+                    /**
+                     * Fill color for the symbol within the button.
+                     * 
+                     * @type {Color}
+                     * @sample {highcharts} highcharts/navigation/buttonoptions-symbolfill/ Blue symbol stroke for one of the buttons
+                     * @sample {highstock} highcharts/navigation/buttonoptions-symbolfill/ Blue symbol stroke for one of the buttons
+                     * @sample {highmaps} highcharts/navigation/buttonoptions-symbolfill/ Blue symbol stroke for one of the buttons
+                     * @default #666666
+                     * @since 2.0
+                     * @product highcharts highstock highmaps
+                     */
+                    symbolFill: '#666666',
+
+                    /**
+                     * The color of the symbol's stroke or line.
+                     * 
+                     * @type {Color}
+                     * @sample {highcharts} highcharts/navigation/buttonoptions-symbolstroke/ Blue symbol stroke
+                     * @sample {highstock} highcharts/navigation/buttonoptions-symbolstroke/ Blue symbol stroke
+                     * @sample {highmaps} highcharts/navigation/buttonoptions-symbolstroke/ Blue symbol stroke
+                     * @default #666666
+                     * @since 2.0
+                     * @product highcharts highstock highmaps
+                     */
+                    symbolStroke: '#666666',
+
+                    /**
+                     * The pixel stroke width of the symbol on the button.
+                     * 
+                     * @type {Number}
+                     * @sample {highcharts} highcharts/navigation/buttonoptions-height/ Bigger buttons
+                     * @sample {highstock} highcharts/navigation/buttonoptions-height/ Bigger buttons
+                     * @sample {highmaps} highcharts/navigation/buttonoptions-height/ Bigger buttons
+                     * @default 1
+                     * @since 2.0
+                     * @product highcharts highstock highmaps
+                     */
+                    symbolStrokeWidth: 3,
+
+                    /**
+                     * A configuration object for the button theme. The object accepts
+                     * SVG properties like `stroke-width`, `stroke` and `fill`. Tri-state
+                     * button styles are supported by the `states.hover` and `states.select`
+                     * objects.
+                     * 
+                     * @type {Object}
+                     * @sample {highcharts} highcharts/navigation/buttonoptions-theme/ Theming the buttons
+                     * @sample {highstock} highcharts/navigation/buttonoptions-theme/ Theming the buttons
+                     * @sample {highmaps} highcharts/navigation/buttonoptions-theme/ Theming the buttons
+                     * @since 3.0
+                     * @product highcharts highstock highmaps
+                     */
+                    theme: {
+
+                        /**
+                         */
+                        fill: '#ffffff', // capture hover
+
+                        /**
+                         */
+                        stroke: 'none',
+
+                        /**
+                         */
+                        padding: 5
+                    }
                 }
-            }
-        });
+            });
 
 
 
         // Add the export related options
+
+        /**
+         * Options for the exporting module. For an overview on the matter, see [the docs](http://www.highcharts.com/docs/export-module/export-module-overview).
+         * @type {Object}
+         * @optionparent exporting
+         */
         defaultOptions.exporting = {
             //enabled: true,
             //filename: 'chart',
+
+            /**
+             * Default MIME type for exporting if `chart.exportChart()` is called
+             * without specifying a `type` option. Possible values are `image/png`,
+             *  `image/jpeg`, `application/pdf` and `image/svg+xml`.
+             * 
+             * @validvalue ["image/png", "image/jpeg", "application/pdf", "image/svg+xml"]
+             * @type {String}
+             * @default image/png
+             * @since 2.0
+             * @product highcharts highstock highmaps
+             */
             type: 'image/png',
+
+            /**
+             * The URL for the server module converting the SVG string to an image
+             * format. By default this points to Highchart's free web service.
+             * 
+             * @type {String}
+             * @default https://export.highcharts.com
+             * @since 2.0
+             * @product highcharts highstock highmaps
+             */
             url: 'https://export.highcharts.com/',
             //width: undefined,
+
+            /**
+             * When printing the chart from the menu item in the burger menu, if
+             * the on-screen chart exceeds this width, it is resized. After printing
+             * or cancelled, it is restored. The default width makes the chart
+             * fit into typical paper format. Note that this does not affect the
+             * chart when printing the web page as a whole.
+             * 
+             * @type {Number}
+             * @default 780
+             * @since 4.2.5
+             * @product highcharts highstock highmaps
+             */
             printMaxWidth: 780,
+
+            /**
+             * Defines the scale or zoom factor for the exported image compared
+             * to the on-screen display. While for instance a 600px wide chart
+             * may look good on a website, it will look bad in print. The default
+             * scale of 2 makes this chart export to a 1200px PNG or JPG.
+             * 
+             * @type {Number}
+             * @see [chart.width](#chart.width), [exporting.sourceWidth](#exporting.
+             * sourceWidth)
+             * @sample {highcharts} highcharts/exporting/scale/ Scale demonstrated
+             * @sample {highstock} highcharts/exporting/scale/ Scale demonstrated
+             * @sample {highmaps} maps/exporting/scale/ Scale demonstrated
+             * @default 2
+             * @since 3.0
+             * @product highcharts highstock highmaps
+             */
             scale: 2,
+
+            /**
+             * Options for the export related buttons, print and export. In addition
+             * to the default buttons listed here, custom buttons can be added.
+             * See [navigation.buttonOptions](#navigation.buttonOptions) for general
+             * options.
+             * 
+             * @product highcharts highstock highmaps
+             */
             buttons: {
+
+                /**
+                 * Options for the export button.
+                 * 
+                 * In [styled mode](http://www.highcharts.com/docs/chart-design-and-
+                 * style/style-by-css), export button styles can be applied with the
+                 * `.highcharts-contextbutton` class.
+                 * 
+                 * @extends navigation.buttonOptions
+                 * @product highcharts highstock highmaps
+                 */
                 contextButton: {
+
+                    /**
+                     */
                     className: 'highcharts-contextbutton',
+
+                    /**
+                     */
                     menuClassName: 'highcharts-contextmenu',
                     //x: -10,
+
+                    /**
+                     * The symbol for the button. Points to a definition function in
+                     * the `Highcharts.Renderer.symbols` collection. The default `exportIcon`
+                     * function is part of the exporting module.
+                     * 
+                     * @validvalue ["circle", "square", "diamond", "triangle", "triangle-down", "menu"]
+                     * @type {String}
+                     * @sample {highcharts} highcharts/exporting/buttons-contextbutton-symbol/ Use a circle for symbol
+                     * @sample {highstock} highcharts/exporting/buttons-contextbutton-symbol/ Use a circle for symbol
+                     * @sample {highmaps} highcharts/exporting/buttons-contextbutton-symbol/ Use a circle for symbol
+                     * @default menu
+                     * @since 2.0
+                     * @product highcharts highstock highmaps
+                     */
                     symbol: 'menu',
+
+                    /**
+                     */
                     _titleKey: 'contextButtonTitle',
-                    menuItems: [{
-                        textKey: 'printChart',
-                        onclick: function() {
-                            this.print();
-                        }
-                    }, {
-                        separator: true
-                    }, {
-                        textKey: 'downloadPNG',
-                        onclick: function() {
-                            this.exportChart();
-                        }
-                    }, {
-                        textKey: 'downloadJPEG',
-                        onclick: function() {
-                            this.exportChart({
-                                type: 'image/jpeg'
-                            });
-                        }
-                    }, {
-                        textKey: 'downloadPDF',
-                        onclick: function() {
-                            this.exportChart({
-                                type: 'application/pdf'
-                            });
-                        }
-                    }, {
-                        textKey: 'downloadSVG',
-                        onclick: function() {
-                            this.exportChart({
-                                type: 'image/svg+xml'
-                            });
-                        }
-                    }]
+
+                    /**
+                     * A collection of config options for the menu items. Each options
+                     * object consists of a `text` option which is a string to show in
+                     * the menu item, as well as an `onclick` parameter which is a callback
+                     * function to run on click.
+                     * 
+                     * By default, there is the "Print" menu item plus one menu item
+                     * for each of the available export types. Menu items can be customized
+                     * by defining a new array of items and assigning `null` to unwanted
+                     * positions (see override example below).
+                     * 
+                     * @type {Array<Object>}
+                     * @sample {highcharts} highcharts/exporting/buttons-contextbutton-onclick/ Skip the menu and export the chart directly
+                     * @sample {highcharts} highcharts/exporting/buttons-contextbutton-menuitems/ Override the menu items
+                     * @sample {highstock} highcharts/exporting/buttons-contextbutton-onclick/ Skip the menu and export the chart directly
+                     * @sample {highstock} highcharts/exporting/buttons-contextbutton-menuitems/ Override the menu items
+                     * @sample {highmaps} highcharts/exporting/buttons-contextbutton-onclick/ Skip the menu and export the chart directly
+                     * @sample {highmaps} highcharts/exporting/buttons-contextbutton-menuitems/ Override the menu items
+                     * @since 2.0
+                     * @product highcharts highstock highmaps
+                     */
+                    menuItems: [
+                        'printChart',
+                        'separator',
+                        'downloadPNG',
+                        'downloadJPEG',
+                        'downloadPDF',
+                        'downloadSVG'
+                    ]
+                }
+            },
+            // docs. Created API item with since:next. Add information and link to sample
+            // from menuItems too.
+
+            /**
+             * An object consisting of definitions for the menu items in the context
+             * menu. Each key value pair has a `key` that is referenced in the
+             * [menuItems](#exporting.buttons.contextButton.menuItems) setting,
+             * and a `value`, which is an object with the following properties:
+             * 
+             * <dl>
+             * 
+             * <dt>onclick</dt>
+             * 
+             * <dd>The click handler for the menu item</dd>
+             * 
+             * <dt>text</dt>
+             * 
+             * <dd>The text for the menu item</dd>
+             * 
+             * <dt>textKey</dt>
+             * 
+             * <dd>If internationalization is required, the key to a language string</dd>
+             * 
+             * </dl>
+             * 
+             * @type {Object}
+             * @sample {highcharts} highcharts/exporting/menuitemdefinitions/ Menu item definitions
+             * @sample {highstock} highcharts/exporting/menuitemdefinitions/ Menu item definitions
+             * @sample {highmaps} highcharts/exporting/menuitemdefinitions/ Menu item definitions
+             * @since next
+             * @product highcharts highstock highmaps
+             */
+            menuItemDefinitions: {
+
+                /**
+                 */
+                printChart: {
+
+                    /**
+                     */
+                    textKey: 'printChart',
+
+                    /**
+                     */
+                    onclick: function() {
+                        this.print();
+                    }
+                },
+
+                /**
+                 */
+                separator: {
+
+                    /**
+                     */
+                    separator: true
+                },
+
+                /**
+                 */
+                downloadPNG: {
+
+                    /**
+                     */
+                    textKey: 'downloadPNG',
+
+                    /**
+                     */
+                    onclick: function() {
+                        this.exportChart();
+                    }
+                },
+
+                /**
+                 */
+                downloadJPEG: {
+
+                    /**
+                     */
+                    textKey: 'downloadJPEG',
+
+                    /**
+                     */
+                    onclick: function() {
+                        this.exportChart({
+                            type: 'image/jpeg'
+                        });
+                    }
+                },
+
+                /**
+                 */
+                downloadPDF: {
+
+                    /**
+                     */
+                    textKey: 'downloadPDF',
+
+                    /**
+                     */
+                    onclick: function() {
+                        this.exportChart({
+                            type: 'application/pdf'
+                        });
+                    }
+                },
+
+                /**
+                 */
+                downloadSVG: {
+
+                    /**
+                     */
+                    textKey: 'downloadSVG',
+
+                    /**
+                     */
+                    onclick: function() {
+                        this.exportChart({
+                            type: 'image/svg+xml'
+                        });
+                    }
                 }
             }
         };
 
+        /**
+         * Fires after a chart is printed through the context menu item or the
+         * `Chart.print` method. Requires the exporting module.
+         * 
+         * @type {Function}
+         * @context Chart
+         * @sample {highcharts} highcharts/chart/events-beforeprint-afterprint/
+         *         Rescale the chart to print
+         * @sample {highstock} highcharts/chart/events-beforeprint-afterprint/
+         *         Rescale the chart to print
+         * @sample {highmaps} highcharts/chart/events-beforeprint-afterprint/
+         *         Rescale the chart to print
+         * @since 4.1.0
+         * @apioption chart.events.afterPrint
+         */
+
+        /**
+         * Fires before a chart is printed through the context menu item or
+         * the `Chart.print` method. Requires the exporting module.
+         * 
+         * @type {Function}
+         * @context Chart
+         * @sample {highcharts} highcharts/chart/events-beforeprint-afterprint/
+         *         Rescale the chart to print
+         * @sample {highstock} highcharts/chart/events-beforeprint-afterprint/
+         *         Rescale the chart to print
+         * @sample {highmaps} highcharts/chart/events-beforeprint-afterprint/
+         *         Rescale the chart to print
+         * @since 4.1.0
+         * @apioption chart.events.beforePrint
+         */
+
+
         // Add the H.post utility
         H.post = function(url, data, formAttributes) {
             // create the form
@@ -192,8 +611,11 @@
         extend(Chart.prototype, /** @lends Highcharts.Chart.prototype */ {
 
             /**
-             * A collection of fixes on the produced SVG to account for expando properties,
-             * browser bugs, VML problems and other. Returns a cleaned SVG.
+             * Exporting module only. A collection of fixes on the produced SVG to
+             * account for expando properties, browser bugs, VML problems and other.
+             * Returns a cleaned SVG.
+             *
+             * @private
              */
             sanitizeSVG: function(svg, options) {
                 // Move HTML into a foreignObject
@@ -255,7 +677,13 @@
             },
 
             /**
-             * Return innerHTML of chart. Used as hook for plugins.
+             * Return the unfiltered innerHTML of the chart container. Used as hook for
+             * plugins. In styled mode, it also takes care of inlining CSS style rules.
+             *
+             * @see  Chart#getSVG
+             *
+             * @returns {String}
+             *          The unfiltered SVG of the chart.
              */
             getChartHTML: function() {
 
@@ -538,7 +966,9 @@
             },
 
             /**
-             * Display a popup menu for choosing the export type
+             * Display a popup menu for choosing the export type.
+             *
+             * @private
              *
              * @param {String} className An identifier for the menu
              * @param {Array} items A collection with text and onclicks for the items
@@ -615,7 +1045,12 @@
 
                     // create the items
                     each(items, function(item) {
-                        if (item) {
+
+                        if (typeof item === 'string') {
+                            item = chart.options.exporting.menuItemDefinitions[item];
+                        }
+
+                        if (H.isObject(item, true)) {
                             var element;
 
                             if (item.separator) {
@@ -683,7 +1118,9 @@
             },
 
             /**
-             * Add the export button to the chart
+             * Add the export button to the chart, with options.
+             *
+             * @private
              */
             addButton: function(options) {
                 var chart = this,
@@ -796,7 +1233,9 @@
             },
 
             /**
-             * Destroy the buttons.
+             * Destroy the export buttons.
+             *
+             * @private
              */
             destroyExport: function(e) {
                 var chart = e ? e.target : this,