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,103 @@
+'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;
+ var labelCount = 0;
+ var originalLabel = label;
+ for (label in c2mData) {
+ labelCount++;
+ label = originalLabel + labelCount.toString();
+ }
+
+ 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;