highcharts-rails 5.0.12 → 5.0.13

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

@@ -1,5 +1,5 @@
 /**
- * @license Highcharts JS v5.0.12 (2017-05-24)
+ * @license Highcharts JS v5.0.13 (2017-07-27)
  * Accessibility module
  *
  * (c) 2010-2017 Highsoft AS
@@ -86,19 +86,210 @@
         }
 
 
-        // Default a11y options
+        /**
+         * Accessibility options
+         * @type {Object}
+         * @optionparent
+         */
         H.setOptions({
+
+            /**
+             * Options for configuring accessibility for the chart. Requires the
+             * [accessibility module](//code.highcharts.com/modules/accessibility.
+             * js) to be loaded. For a description of the module and information
+             * on its features, see [Highcharts Accessibility](http://www.highcharts.
+             * com/docs/chart-concepts/accessibility).
+             * 
+             * @since 5.0.0
+             * @product highcharts highstock highmaps
+             */
             accessibility: {
+
+                /**
+                 * Enable accessibility features for the chart.
+                 * 
+                 * @type {Boolean}
+                 * @default true
+                 * @since 5.0.0
+                 * @product highcharts highstock highmaps
+                 */
                 enabled: true,
+
+                /**
+                 * When a series contains more points than this, we no longer expose
+                 * information about individual points to screen readers.
+                 * 
+                 * Set to `false` to disable.
+                 * 
+                 * @type {Number|Boolean}
+                 * @default 30
+                 * @since 5.0.0
+                 * @product highcharts highstock highmaps
+                 */
                 pointDescriptionThreshold: 30, // set to false to disable
+
+                /**
+                 * Options for keyboard navigation.
+                 * 
+                 * @type {Object}
+                 * @since 5.0.0
+                 * @product highcharts highstock highmaps
+                 */
                 keyboardNavigation: {
-                    enabled: true
-                    //	skipNullPoints: false
+
+                    /**
+                     * Enable keyboard navigation for the chart.
+                     * 
+                     * @type {Boolean}
+                     * @default true
+                     * @since 5.0.0
+                     */
+                    enabled: true,
+
+                    /**
+                     * Enable tab navigation for points. Without this, only arrow keys
+                     * can be used to navigate between points.
+                     * 
+                     * @type {Boolean}
+                     * @default {all} true
+                     * @since next
+                     */
+                    tabThroughPoints: true
+
+                    /**
+                     * Skip null points when navigating through points with the
+                     * keyboard.
+                     * 
+                     * @type {Boolean}
+                     * @default false
+                     * @since 5.0.0
+                     * @apioption accessibility.keyboardNavigation.skipNullPoints
+                     */
                 }
-                // describeSingleSeries: false
+
+                /**
+                 * Whether or not to add series descriptions to charts with a single
+                 * series.
+                 * 
+                 * @type {Boolean}
+                 * @default false
+                 * @since 5.0.0
+                 * @product highcharts highstock highmaps
+                 * @apioption accessibility.describeSingleSeries
+                 */
+
+                /**
+                 * Function to run upon clicking the "View as Data Table" link in the
+                 * screen reader region.
+                 * 
+                 * By default Highcharts will insert and set focus to a data table
+                 * representation of the chart.
+                 * 
+                 * @type {Function}
+                 * @since 5.0.0
+                 * @apioption accessibility.onTableAnchorClick
+                 */
+
+                /**
+                 * Date format to use for points on datetime axes when describing them
+                 * to screen reader users.
+                 * 
+                 * Defaults to the same format as in tooltip.
+                 * 
+                 * For an overview of the replacement codes, see [dateFormat](
+                 * #Highcharts.dateFormat).
+                 * 
+                 * @type {String}
+                 * @see [pointDateFormatter](#accessibility.pointDateFormatter)
+                 * @since 5.0.0
+                 * @apioption accessibility.pointDateFormat
+                 */
+
+                /**
+                 * Formatter function to determine the date/time format used with points
+                 * on datetime axes when describing them to screen reader users. Receives
+                 * one argument, `point`, referring to the point to describe. Should
+                 * return a date format string compatible with [dateFormat](#Highcharts.
+                 * dateFormat).
+                 * 
+                 * @type {Function}
+                 * @see [pointDateFormat](#accessibility.pointDateFormat)
+                 * @since 5.0.0
+                 * @apioption accessibility.pointDateFormatter
+                 */
+
+                /**
+                 * Formatter function to use instead of the default for point descriptions.
+                 * Receives one argument, `point`, referring to the point to describe.
+                 * Should return a String with the description of the point for a screen
+                 * reader user.
+                 * 
+                 * @type {Function}
+                 * @see [point.description](#series<line>.data.description)
+                 * @since 5.0.0
+                 * @apioption accessibility.pointDescriptionFormatter
+                 */
+
+                /**
+                 * A formatter function to create the HTML contents of the hidden screen
+                 * reader information region. Receives one argument, `chart`, referring
+                 * to the chart object. Should return a String with the HTML content
+                 * of the region.
+                 * 
+                 * The link to view the chart as a data table will be added automatically
+                 * after the custom HTML content.
+                 * 
+                 * @type {Function}
+                 * @default undefined
+                 * @since 5.0.0
+                 * @apioption accessibility.screenReaderSectionFormatter
+                 */
+
+                /**
+                 * Formatter function to use instead of the default for series descriptions.
+                 * Receives one argument, `series`, referring to the series to describe.
+                 * Should return a String with the description of the series for a
+                 * screen reader user.
+                 * 
+                 * @type {Function}
+                 * @see [series.description](#plotOptions.series.description)
+                 * @since 5.0.0
+                 * @apioption accessibility.seriesDescriptionFormatter
+                 */
             }
         });
 
+        /**
+         * A text description of the chart.
+         * 
+         * If the Accessibility module is loaded, this is included by default
+         * as a long description of the chart and its contents in the hidden
+         * screen reader information region.
+         * 
+         * @type {String}
+         * @see [typeDescription](#chart.typeDescription)
+         * @default undefined
+         * @since 5.0.0
+         * @apioption chart.description
+         */
+
+        /**
+         * A text description of the chart type.
+         * 
+         * If the Accessibility module is loaded, this will be included in the
+         * description of the chart in the screen reader information region.
+         * 
+         * 
+         * Highcharts will by default attempt to guess the chart type, but for
+         * more complex charts it is recommended to specify this property for
+         * clarity.
+         * 
+         * @type {String}
+         * @default undefined
+         * @since 5.0.0
+         * @apioption chart.typeDescription
+         */
+
         /**
          * HTML encode some characters vulnerable for XSS.
          * @param  {string} html The input string
@@ -370,14 +561,25 @@
         };
 
         // Function to highlight next/previous point in chart
-        // Returns highlighted point on success, false on failure (no adjacent point to highlight in chosen direction)
+        // Returns highlighted point on success, false on failure (no adjacent point to
+        // highlight in chosen direction)
         H.Chart.prototype.highlightAdjacentPoint = function(next) {
-            var series = this.series,
-                curPoint = this.highlightedPoint,
+            var chart = this,
+                series = chart.series,
+                curPoint = chart.highlightedPoint,
                 curPointIndex = curPoint && curPoint.index || 0,
                 curPoints = curPoint && curPoint.series.points,
+                lastSeries = chart.series && chart.series[chart.series.length - 1],
+                lastPoint = lastSeries && lastSeries.points &&
+                lastSeries.points[lastSeries.points.length - 1],
                 newSeries,
                 newPoint,
+                isSkipPoint = function(point) {
+                    return point.isNull &&
+                        chart.options.accessibility.keyboardNavigation.skipNullPoints ||
+                        point.series.options.skipKeyboardNavigation ||
+                        !point.series.visible;
+                },
                 // Handle connecting ends - where the points array has an extra last
                 // point that is a reference to the first one. We skip this.
                 forwardSkipAmount = curPoint && curPoint.series.connectEnds &&
@@ -388,43 +590,42 @@
                 return false;
             }
 
-            // Use first point if none already highlighted
             if (!curPoint) {
-                return series[0].points[0].highlight();
-            }
-
-            // Find index of current point in series.points array. Necessary for dataGrouping (and maybe zoom?)
-            if (curPoints[curPointIndex] !== curPoint) {
-                for (var i = 0; i < curPoints.length; ++i) {
-                    if (curPoints[i] === curPoint) {
-                        curPointIndex = i;
-                        break;
+                // No point is highlighted yet. Try first/last point depending on move
+                // direction
+                newPoint = next ? series[0].points[0] : lastPoint;
+            } else {
+                // We have a highlighted point.
+                // Find index of current point in series.points array. Necessary for
+                // dataGrouping (and maybe zoom?)
+                if (curPoints[curPointIndex] !== curPoint) {
+                    for (var i = 0; i < curPoints.length; ++i) {
+                        if (curPoints[i] === curPoint) {
+                            curPointIndex = i;
+                            break;
+                        }
                     }
                 }
-            }
 
-            // Grab next/prev point & series
-            newSeries = series[curPoint.series.index + (next ? 1 : -1)];
-            newPoint = curPoints[curPointIndex + (next ? forwardSkipAmount : -1)] ||
-                // Done with this series, try next one
-                newSeries &&
-                newSeries.points[next ? 0 : newSeries.points.length - (
-                    newSeries.connectEnds ? 2 : 1
-                )];
-
-            // If there is no adjacent point, we return false
-            if (newPoint === undefined) {
-                return false;
+                // Grab next/prev point & series
+                newSeries = series[curPoint.series.index + (next ? 1 : -1)];
+                newPoint = curPoints[curPointIndex + (next ? forwardSkipAmount : -1)] ||
+                    // Done with this series, try next one
+                    newSeries &&
+                    newSeries.points[next ? 0 : newSeries.points.length - (
+                        newSeries.connectEnds ? 2 : 1
+                    )];
+
+                // If there is no adjacent point, we return false
+                if (newPoint === undefined) {
+                    return false;
+                }
             }
 
             // Recursively skip null points or points in series that should be skipped
-            if (
-                newPoint.isNull &&
-                this.options.accessibility.keyboardNavigation.skipNullPoints ||
-                newPoint.series.options.skipKeyboardNavigation
-            ) {
-                this.highlightedPoint = newPoint;
-                return this.highlightAdjacentPoint(next);
+            if (isSkipPoint(newPoint)) {
+                chart.highlightedPoint = newPoint;
+                return chart.highlightAdjacentPoint(next);
             }
 
             // There is an adjacent point, highlight it
@@ -519,12 +720,15 @@
             // The module's keyCode handlers determine when to move to another module.
             // Validate holds a function to determine if there are prerequisites for this module to run that are not met.
             // Init holds a function to run once before any keyCodes are interpreted.
+            // Terminate holds a function to run once before moving to next/prev module.
             // transformTabs determines whether to transform tabs to left/right events or not. Defaults to true.
             function KeyboardNavigationModule(options) {
+                this.id = options.id;
                 this.keyCodeMap = options.keyCodeMap;
                 this.move = options.move;
                 this.validate = options.validate;
                 this.init = options.init;
+                this.terminate = options.terminate;
                 this.transformTabs = options.transformTabs !== false;
             }
             KeyboardNavigationModule.prototype = {
@@ -544,12 +748,15 @@
             };
             // Maintain abstraction between KeyboardNavigationModule and Highcharts
             // The chart object keeps track of a list of KeyboardNavigationModules that we move through
-            function navModuleFactory(keyMap, options) {
+            function navModuleFactory(id, keyMap, options) {
                 return new KeyboardNavigationModule(merge({
                     keyCodeMap: keyMap,
                     // Move to next/prev valid module, or undefined if none, and init it.
                     // Returns true on success and false if there is no valid module to move to.
                     move: function(direction) {
+                        if (this.terminate) {
+                            this.terminate(direction);
+                        }
                         chart.keyboardNavigationModuleIndex += direction;
                         var newModule = chart.keyboardNavigationModules[chart.keyboardNavigationModuleIndex];
                         if (newModule) {
@@ -566,6 +773,8 @@
                         chart.slipNextTab = true; // Allow next tab to slip, as we will have focus on chart now
                         return false;
                     }
+                }, {
+                    id: id
                 }, options));
             }
 
@@ -599,7 +808,7 @@
             // Each mode determines when to move to the next/prev mode.
             chart.keyboardNavigationModules = [
                 // Points
-                navModuleFactory([
+                navModuleFactory('points', [
                     // Left/Right
                     [
                         [37, 39],
@@ -634,26 +843,29 @@
                         }
                     ]
                 ], {
-                    // If coming back to points from other module, highlight last point
-                    init: function(direction) {
-                        var lastSeries = chart.series && chart.series[chart.series.length - 1],
-                            lastPoint = lastSeries && lastSeries.points && lastSeries.points[lastSeries.points.length - 1];
-                        if (direction < 0 && lastPoint) {
-                            lastPoint.highlight();
+                    // Always start highlighting from scratch when entering this module
+                    init: function() {
+                        delete chart.highlightedPoint;
+                    },
+                    // If leaving points, don't show tooltip anymore
+                    terminate: function() {
+                        if (chart.tooltip) {
+                            chart.tooltip.hide(0);
                         }
-                    }
+                        delete chart.highlightedPoint;
+                    },
+
+                    transformTabs: chart.options.accessibility.keyboardNavigation.tabThroughPoints
                 }),
 
                 // Exporting
-                navModuleFactory([
+                navModuleFactory('exporting', [
                     // Left/Up
                     [
                         [37, 38],
                         function() {
                             var i = chart.highlightedExportItem || 0,
-                                reachedEnd = true,
-                                series = chart.series,
-                                newSeries;
+                                reachedEnd = true;
                             // Try to highlight prev item in list. Highlighting e.g. separators will fail.
                             while (i--) {
                                 if (chart.highlightExportItem(i)) {
@@ -663,14 +875,6 @@
                             }
                             if (reachedEnd) {
                                 chart.hideExportMenu();
-                                // Wrap to last point
-                                if (series && series.length) {
-                                    newSeries = series[series.length - 1];
-                                    if (newSeries.points.length) {
-                                        newSeries.points[newSeries.points.length - 1].highlight();
-                                    }
-                                }
-                                // Try to move to prev module (should be points, since we wrapped to last point)
                                 return this.move(-1);
                             }
                         }
@@ -722,7 +926,7 @@
                 }),
 
                 // Map zoom
-                navModuleFactory([
+                navModuleFactory('mapZoom', [
                     // Up/down/left/right
                     [
                         [38, 40, 37, 39],
@@ -787,7 +991,7 @@
                 }),
 
                 // Highstock range selector (minus input boxes)
-                navModuleFactory([
+                navModuleFactory('rangeSelector', [
                     // Left/Right/Up/Down
                     [
                         [37, 39, 38, 40],
@@ -827,7 +1031,7 @@
                 }),
 
                 // Highstock range selector, input boxes
-                navModuleFactory([
+                navModuleFactory('rangeSelectorInput', [
                     // Tab/Up/Down
                     [
                         [9, 38, 40],
@@ -859,7 +1063,7 @@
                 }),
 
                 // Legend navigation
-                navModuleFactory([
+                navModuleFactory('legend', [
                     // Left/Right/Up/Down
                     [
                         [37, 39, 38, 40],
@@ -881,9 +1085,13 @@
                 ], {
                     // Only run this module if we have at least one legend - wait for it - item.
                     // Don't run if the legend is populated by a colorAxis.
+                    // Don't run if legend navigation is disabled.
                     validate: function() {
                         return chart.legend && chart.legend.allItems &&
-                            !(chart.colorAxis && chart.colorAxis.length);
+                            !(chart.colorAxis && chart.colorAxis.length) &&
+                            (chart.options.legend &&
+                                chart.options.legend.keyboardNavigation &&
+                                chart.options.legend.keyboardNavigation.enabled) !== false;
                     },
 
                     // Make elements focusable and accessible