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/accessibility/README.md

@@ -0,0 +1,3 @@
+# accessibility
+
+While anticipating more accessibility libraries in the future, as of today this is a trivial wrapper over the `sonification` directory.

src/accessibility/sonification/README.md

@@ -0,0 +1,33 @@
+# `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*.
+
+
+* `initClosedCaptionDiv(gd, config)` finds or creates the closed caption div, depending on `config`.
+ * `config` is equal to `defaultConfig.closedCaptions`.
+
+### 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/accessibility/sonification/all_codecs.js

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

src/accessibility/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/accessibility/sonification/index.js

@@ -0,0 +1,104 @@
+'use strict';
+
+var c2m = require('chart2music');
+var Fx = require('../../components/fx');
+var Lib = require('../../lib');
+
+var codecs = require('./all_codecs').codecs;
+
+function initC2M(gd, defaultConfig) {
+ // TODO: should this be Lib.getGraphDiv()?
+ // TODO what is there besides a fullReset?
+ // TODO Do we need the capacity to add data (live listen?)
+ // TODO Do we need the capacity to reset all data
+ 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 = []; // TODO this probably needs to be stored in context-
+ // when data is updated this specific instance needs to be updated
+ // or the below function eneds to be reset to use the new instance of labels.
+ c2mContext.options.onFocusCallback = function(dataInfo) {
+ Fx.hover(gd, [{
+ curveNumber: labels.indexOf(dataInfo.slice),
+ pointNumber: dataInfo.index
+ }]);
+ };
+ // I generally don't like using closures like this.
+ // In this case it works out, we effectively treat 'labels'
+ // like a global, but it's a local.
+ // I'd rather the callback be given its c2m handler which
+ // could store extra data. Or bind c2mContext as `this`.
+
+ var titleText = gd._fullLayout.title?.text ?? 'Chart';
+ var ccElement = initClosedCaptionDiv(gd, c2mContext.ccOptions);
+
+ // TODO:
+ // I believe that title OR title.text could contain the information needed
+ // So we should stop if title is a type string
+ // Furthermore, I think that the traces would have to point to their axis,
+ // since it might not be x1, could be x2, etc
+ // So this really needs to be part of process()
+ var xAxisText = gd._fullLayout.xaxis?.title?.text ?? 'X Axis';
+ var yAxisText = gd._fullLayout.yaxis?.title?.text ?? 'Y Axis';
+
+ var c2mData = {};
+ var types = [];
+ var fullData = gd._fullData;
+ // TODO: We're looping through all traces, and that's fine, but it might be helpful to discern how things are organized
+ for(var i = 0; i < fullData.length; i++) {
+ var trace = fullData[i];
+ // TODO: what happens if this doesn't run, weird c2m errors
+ for(var codecI = 0; codecI < codecs.length; codecI++) {
+ var test = codecs[codecI].test(trace);
+ if (!test) continue;
+ var label = test.name ? test.name : i.toString() + ' ';
+
+ var labelCount = 0;
+ var originalLabel = label;
+ while (label in c2mData) {
+ labelCount++;
+ label = originalLabel + labelCount.toString();
+ }
+
+ labels.push(label);
+ types.push(test.type);
+ c2mData[label] = codecs[codecI].process(trace);
+ }
+ } // TODO add unsupported codec
+
+ c2mContext.c2mHandler = c2m.c2mChart({
+ title: titleText,
+ type: types,
+ axes: {
+ x: { // needs to be generated
+ label: xAxisText
+ },
+ y: {
+ label: yAxisText
+ },
+ },
+ element: gd,
+ cc: ccElement,
+ data: c2mData,
+ options: c2mContext.options,
+ info: c2mContext.info
+ });
+ // TODO: We need to handle the possible error that c2mChart returns
+}
+exports.initC2M = initC2M;
+
+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);
+ }
+}
+
+exports.initClosedCaptionDiv = initClosedCaptionDiv;

src/accessibility/sonification/xy_scatter_codec.js

@@ -0,0 +1,27 @@
+'use strict';
+// This codec serves for one x axis and one y axis
+
+function test(trace) {
+ if(!trace) return null;
+ if(!trace.type || trace.type !== 'scatter') return null;
+ // TODO: I think we can have an x OR a y
+ if((trace.y === undefined || trace.y.length === 0) && (trace.x === undefined || trace.x.length === 0)) return null;
+ return {type: 'scatter', name: trace.name};
+}
+exports.test = test;
+
+function process(trace) {
+ var traceData = [];
+ var x = trace.x && trace.x.length !== 0 ? trace.x : [];
+ var y = trace.y && trace.y.length !== 0 ? trace.y : [];
+
+ for(var p = 0; p < Math.max(x.length, y.length); p++) {
+ traceData.push({ // TODO I think we're copying the data here, bad.
+ x: x[p] ? x[p] : p,
+ y: y[p] ? y[p] : p,
+ label: trace.text[p] ? trace.text[p] : p
+ });
+ }
+ return traceData;
+}
+exports.process = process;