add Chart2Music keyboard and sound accessibility features

CONTRIBUTING.md

@@ -276,9 +276,9 @@ npm run baseline mock_*
 ```
 
 **IMPORTANT:** the `baseline`, `test-image` and `test-export` scripts do **not** bundle the source files before
-running the image tests. We recommend running `npm run watch` or `npm start` in
+running the image tests. We recommend running `npm start` in
 a separate tab to ensure that the most up-to-date code is used.
-Also if you are adding a new mock, you may need to re-run `npm start` or `npm run watch`
+Also if you are adding a new mock, you may need to re-run `npm start` 
 to be able to find the new mock in the browser.
 To help ensure valid attributes are used in your new mock(s), please run `npm run test-mock`
 or `npm run test-mock mock_name(s)` after adding new mocks or implementing any new attributes.

package.json

@@ -79,6 +79,7 @@
     "@turf/centroid": "^7.1.0",
     "base64-arraybuffer": "^1.0.2",
     "canvas-fit": "^1.5.0",
+    "chart2music": "^1.13.0",
     "color-alpha": "1.0.4",
     "color-normalize": "1.5.0",
     "color-parse": "2.0.0",

src/plot_api/plot_api.js

@@ -29,6 +29,7 @@ var manageArrays = require('./manage_arrays');
 var helpers = require('./helpers');
 var subroutines = require('./subroutines');
 var editTypes = require('./edit_types');
+var sonification = require('../sonification/enable_sonification');
 
 var AX_NAME_PATTERN = require('../plots/cartesian/constants').AX_NAME_PATTERN;
 
@@ -381,10 +382,14 @@ function _doPlot(gd, data, layout, config) {
         // happens outside of marginPushers where all the other automargins are
         // calculated. Would be much better to separate margin calculations from
         // component drawing - see https://github.com/plotly/plotly.js/issues/2704
-        Plots.doAutoMargin,
-        Plots.previousPromises
+        Plots.doAutoMargin
     );
 
+    if(gd._context.sonification.enabled) seq.push(sonification.enable_sonification);
+
+    seq.push(Plots.previousPromises);
+
+
     // even if everything we did was synchronous, return a promise
     // so that the caller doesn't care which route we took
     var plotDone = Lib.syncOrAsync(seq, gd);
@@ -2667,7 +2672,6 @@ function react(gd, data, layout, config) {
             setPlotContext(gd, config);
             configChanged = diffConfig(oldConfig, gd._context);
         }
-
         gd.data = data || [];
         helpers.cleanData(gd.data);
         gd.layout = layout || {};
@@ -2738,7 +2742,6 @@ function react(gd, data, layout, config) {
 
             Plots.doCalcdata(gd);
             subroutines.doAutoRangeAndConstraints(gd);
-
             seq.push(function() {
                 return Plots.transitionFromReact(gd, restyleFlags, relayoutFlags, oldFullLayout);
             });
@@ -3654,7 +3657,6 @@ function deleteFrames(gd, frameList) {
  */
 function purge(gd) {
     gd = Lib.getGraphDiv(gd);
-
     var fullLayout = gd._fullLayout || {};
     var fullData = gd._fullData || [];
 
@@ -3672,7 +3674,6 @@ function purge(gd) {
 
     // in contrast to _doPlots.purge which does NOT clear _context!
     delete gd._context;
-
     return gd;
 }
 

src/plot_api/plot_config.js

@@ -471,7 +471,20 @@ var configAttributes = {
             'instead of MM/DD/YYYY). Currently `grouping` and `currency` are ignored',
             'for our automatic number formatting, but can be used in custom formats.'
         ].join(' ')
-    }
+    },
+
+    sonification: {
+        valType: 'any',
+        dflt: {
+            enabled: false,
+            options: {},
+            info: {},
+            closedCaptions: {generate: false, elId: 'c2m-plotly-cc', elClassname: 'c2m-plotly-closed_captions'}
+        },
+        description: ['Sonification options: whether to enable, options to pass to the library, info to pass to the library, closedCaptions to control how plotly renders the closed-captions element.',
+            'chart2music is supported and options here include Options and Info from https://www.chart2music.com/docs/API/Config. '
+        ].join(' ')
+    },
 };
 
 var dfltConfig = {};

src/sonification/README.md

@@ -0,0 +1,29 @@
+# `plotly.js` wrapper for `chart2music`, sonified charts
+
+This wrapper attaches a context object to `gd._context._c2m` with the following properties:
+
+* `.options`: the options object as required by c2m
+* `.info`: the info object as required by c2m
+* `.ccOptions`: information about where to place the closed caption div
+* `.c2mHandler`: the object returned by calling the c2m library's initializer
+
+The first three have most of their values set by the defaults in *src/plot_api/plot_config.js*.
+
+
+### index.js
+
+**index.js** exposes the following api:
+
+* `initC2M(gd, defaultConfig)` full resets the `c2mChart` object.
+  * `defaultConfig` is equal to `gd._context.sonification`, as defined in *src/plot_api/plot_config.js*.
+
+### all_codecs.js
+**all_codecs.js** agregates all the individual **_codec.js* files, all are expect to export exactly two functions: `test` and `process`.
+
+I chose to aggregate all codecs in a separate file because it will ultimately be a 1-1 conversion if `plotly.js` adopts ES modules.
+
+## Writing a Codec
+
+This section is TODO
+
+chart2music supports N types of graphs. We should figure out how how to convert as many plotly types to chart2music types. I will write descriptions for each type in the folder, if not the actual code, along with what `test` must return and what `process` must return.

src/sonification/all_codecs.js

@@ -0,0 +1,5 @@
+'use strict';
+
+var scatterXY = require('./xy_scatter_codec');
+
+exports.codecs = [ scatterXY ];

src/sonification/enable_sonification.js

@@ -0,0 +1,10 @@
+'use strict';
+
+var c2mPlotly = require('.');
+
+function enable_sonification(gd) {
+    // Collecting defaults
+    var defaultConfig = gd._context.sonification;
+    c2mPlotly.initC2M(gd, defaultConfig);
+}
+exports.enable_sonification = enable_sonification;

src/sonification/index.js

@@ -0,0 +1,96 @@
+'use strict';
+
+var c2m = require('chart2music');
+var Fx = require('../components/fx');
+var Lib = require('../lib');
+
+var codecs = require('./all_codecs').codecs;
+
+/* initClosedCaptionDiv: Initialize the closed caption div with the given configuration.
+ * This function works by either creating a new div or returning the existing div
+*/
+function initClosedCaptionDiv(gd, config) {
+    if(config.generate) {
+        var closedCaptions = document.createElement('div');
+        closedCaptions.id = config.elId;
+        closedCaptions.className = config.elClassname;
+        gd.parentNode.insertBefore(closedCaptions, gd.nextSibling); // this really might not work
+        return closedCaptions;
+    } else {
+        return document.getElementById(config.elId);
+    }
+}
+
+/* initC2M: Initialize the chart2music library with the given configuration.
+ * This function works by resetting the c2m context of the given graph div
+ */
+function initC2M(gd, defaultConfig) {
+    var c2mContext = gd._context._c2m = {};
+    c2mContext.options = Lib.extendDeepAll({}, defaultConfig.options);
+    c2mContext.info = Lib.extendDeepAll({}, defaultConfig.info);
+    c2mContext.ccOptions = Lib.extendDeepAll({}, defaultConfig.closedCaptions);
+
+    var labels = []; 
+    // Set the onFocusCallback to highlight the hovered point
+    c2mContext.options.onFocusCallback = function(dataInfo) {
+        Fx.hover(gd, [{
+            curveNumber: labels.indexOf(dataInfo.slice),
+            pointNumber: dataInfo.index
+        }]);
+    };
+
+    var ccElement = initClosedCaptionDiv(gd, c2mContext.ccOptions);
+
+    // Get the chart, x, and y axis titles from the layout.
+    // This will be used for the closed captions. 
+    var titleText = 'Chart';
+    if((gd._fullLayout.title !== undefined) && (gd._fullLayout.title.text !== undefined)) {
+        titleText = gd._fullLayout.title.text;
+    }
+    var xAxisText = 'X Axis';
+    if((gd._fullLayout.xaxis !== undefined) &&
+      (gd._fullLayout.xaxis.title !== undefined) &&
+      (gd._fullLayout.xaxis.title.text !== undefined)) {
+        xAxisText = gd._fullLayout.xaxis.title.text;
+    }
+    var yAxisText = 'Y Axis';
+    if((gd._fullLayout.yaxis !== undefined) &&
+      (gd._fullLayout.yaxis.title !== undefined) &&
+      (gd._fullLayout.yaxis.title.text !== undefined)) {
+        yAxisText = gd._fullLayout.yaxis.title.text;
+    }
+
+    // Convert the data to the format that c2m expects
+    var c2mData = {};
+    var types = [];
+    var fullData = gd._fullData;
+
+    // Iterate through the traces and find the codec that matches the trace
+    for (var trace of fullData) {
+        for (var codec of codecs) {
+            var test = codec.test(trace);
+            if (!test) continue;
+
+            // Generate a unique label for the trace
+            var label = test.name;
+            labels.push(label);
+            types.push(test.type);
+            c2mData[label] = codec.process(trace);
+        }
+    }
+
+    c2mContext.c2mHandler = c2m.c2mChart({
+        title: titleText,
+        type: types,
+        axes: {
+            x: { label: xAxisText },
+            y: { label: yAxisText },
+        },
+        element: gd,
+        cc: ccElement,
+        data: c2mData,
+        options: c2mContext.options,
+        info: c2mContext.info
+    });
+}
+exports.initC2M = initC2M;