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;