chartjs-plugin-chart2music 0.6.1 → 0.7.0

package/README.md

@@ -1,117 +1,133 @@
 # chartjs-plugin-chart2music
-[![npm version](https://badge.fury.io/js/chartjs-plugin-chart2music.svg)](https://badge.fury.io/js/chartjs-plugin-chart2music)
 
-**This is a beta release of this plugin. Not all chart.js features are supported yet.**
+[![npm version](https://badge.fury.io/js/chartjs-plugin-chart2music.svg)](https://www.npmjs.com/package/chartjs-plugin-chart2music)
 
-Turns your chart.js charts into music so the blind can hear data. This plugin will automatically add Chart2Music, an interactive sonification library, to your chart.js charts. The contents of the chart element will be modified to best support screen reader users, and the interactions will be visually synchronized to provide support for keyboard-only users.
+`chartjs-plugin-chart2music` connects [Chart.js](https://www.chartjs.org/) charts to [Chart2Music](https://chart2music.com/), providing keyboard navigation, screen-reader output, and interactive data sonification. Focus a chart to explore its data with the keyboard; the active data point is also highlighted on the visual chart.
 
-[Check out our CodePen collection of examples using the plugin.](https://codepen.io/collection/VYEvEQ)
+This plugin is in beta. The supported chart types and integration points are listed below.
 
-## Getting started
+## Install and use
 
-Add the chartjs2music plugin to your existing chart.js code like this:
+```bash
+npm install chart.js chartjs-plugin-chart2music
+```
+
+Register the plugin globally:
 
 ```js
-import {Chart} from "chart.js/auto";
-import chartjs2music from "chartjs-plugin-chart2music";
+import Chart from "chart.js/auto";
+import chart2music from "chartjs-plugin-chart2music";
 
-Chart.register(chartjs2music);
+Chart.register(chart2music);
+
+new Chart(canvasElement, {
+    type: "bar",
+    data: {
+        labels: ["Q1", "Q2", "Q3", "Q4"],
+        datasets: [{label: "Revenue", data: [1, 4, 2, 8]}]
+    }
+});
 ```
 
-That will register the plugin globally. Alternatively, if you only want to enable for a given chart, you can do this:
+Or add it to one chart only:
 
 ```js
-import {Chart} from "chart.js/auto";
-import chartjs2music from "chartjs-plugin-chart2music";
-
 new Chart(canvasElement, {
     type: "bar",
     data: {
-        datasets: [{
-            data: [1,4,2,8]
-        }]
+        datasets: [{data: [1, 4, 2, 8]}]
     },
-    plugins: [chartjs2music]
-})
-
+    plugins: [chart2music]
+});
 ```
 
-## Available options
+When no `cc` element is supplied, the plugin creates a caption element immediately after the canvas. Supply your own element when you need to control where the Chart2Music output appears.
 
-The following plugin options are available:
-* `errorCallback` - A callback that will return errors if any arise while the plugin works.
-* `cc` - the equivalent of the [chart2music option `cc`](https://chart2music.com/docs/API/Config#axes)
-* `audioEngine` - the equivalent of the [chart2music option `audioEngine`](https://chart2music.com/docs/API/Config#cc)
-* `axes` - the equivalent of the [chart2music option `axes`](https://chart2music.com/docs/API/Config#axes)
-* `lang` - the language your user speaks. The available languages that Chart2Music supports are: "en", "de", "es", "fr", "it". The default is "en". If you would like to add translations for another language, [Chart2Music is open to PRs](https://github.com/julianna-langston/chart2music).
+## Plugin options
 
-Here's an example for providing options:
-```js
-import {Chart} from "chart.js/auto";
-import chartjs2music from "chartjs-plugin-chart2music";
+Configure the plugin through `options.plugins.chartjs2music`:
 
+```js
 new Chart(canvasElement, {
     type: "bar",
     data: {
-        datasets: [{
-            data: [1,4,2,8]
-        }]
+        labels: ["Q1", "Q2", "Q3", "Q4"],
+        datasets: [{label: "Revenue", data: [1, 4, 2, 8]}]
     },
     options: {
         plugins: {
             chartjs2music: {
-                // All errors should be logged as errors
-                errorCallback: console.error,
-                // Here's a div I made to be the CC
-                cc: myDiv,
-                // The Y values should all be money
+                cc: outputElement,
+                lang: "en",
                 axes: {
+                    x: {label: "Quarter"},
                     y: {
-                        format: (value) => "$" + value
+                        label: "Revenue",
+                        format: (value) => `$${value.toLocaleString()}`
                     }
-                }
+                },
+                options: {
+                    enableSound: true,
+                    onFocusCallback: (point) => console.log(point),
+                    onSelectCallback: ({point}) => console.log(point)
+                },
+                errorCallback: console.error
             }
         }
-    },
-    plugins: [chartjs2music]
+    }
 });
 ```
 
-If you are using TypeScript, replace the first 4 lines with this:
-```ts
-import {Chart, type ChartTypeRegistry} from "chart.js/auto";
-import chartjs2music from "chartjs-plugin-chart2music";
+Available plugin options:
 
-new Chart(canvasElement, {
-    type: "bar" as keyof ChartTypeRegistry,
+- `cc`: Element that receives Chart2Music's accessible chart caption. Optional.
+- `lang`: Chart2Music language. Supported values include `en`, `de`, `es`, `fr`, and `it`; default is `en`.
+- `axes`: Chart2Music axis configuration, including labels and value formatters.
+- `audioEngine`: A custom Chart2Music audio engine.
+- `options`: Chart2Music interaction options such as `enableSound`, `onFocusCallback`, and `onSelectCallback`.
+- `errorCallback`: Receives errors while the plugin initializes or updates a chart.
+
+## Supported charts
+
+The plugin supports Chart.js bar, line, pie, doughnut, polar area, and scatter charts, including mixed bar/line configurations. It also supports:
+
+- Box plots from [`@sgratzl/chartjs-chart-boxplot`](https://www.npmjs.com/package/@sgratzl/chartjs-chart-boxplot).
+- Matrix plots from [`chartjs-chart-matrix`](https://www.npmjs.com/package/chartjs-chart-matrix).
+- Word clouds from [`chartjs-chart-wordcloud`](https://www.npmjs.com/package/chartjs-chart-wordcloud).
+- Chart titles, axis titles, minimum and maximum values, linear and logarithmic axes, custom axis formatting, dataset visibility, and chart data updates.
+
+Visual-only Chart.js settings such as color, padding, and line thickness do not affect the sonification. Advanced Chart.js parsing configurations and nonstandard axis identifiers are not currently supported.
+
+## Future support
+
+Planned support includes:
+
+- Chart subtitles.
+- Radar plots.
+- Error bars via [`chartjs-chart-error-bars`](https://www.npmjs.com/package/chartjs-chart-error-bars).
+- Parallel coordinate plots via [`chartjs-chart-pcp`](https://www.npmjs.com/package/chartjs-chart-pcp).
+- Zoom interactions via [`chartjs-plugin-zoom`](https://www.npmjs.com/package/chartjs-plugin-zoom).
+
+## Examples and Storybook
+
+The repository includes runnable chart configurations under [`stories/charts`](./stories/charts), covering the supported chart types and plugin integrations. A Storybook catalogue exposes these examples as Bar, Line, Multi-chart, Distribution, Circular, Scatter, Matrix, Word cloud, and Options stories.
+
+```bash
+npm run storybook
+```
+
+Build the static Storybook site with:
+
+```bash
+npm run build-storybook
 ```
 
-## Supported features
-
-This plugin is currently in beta, so not all of the chart.js features are currently supported.
-
-A quick list of chart.js features we currently support includes:
-* Chart types: bar, doughnut, line, pie, polar, radar, scatter, and combinations therein.
-* Boxplots using the `@sgratzl/chartjs-chart-boxplot` plugin (only support boxplots when there are no other chart types present)
-* Wordclouds using the `chartjs-chart-wordcloud` plugin
-* Axes options: `title`, `min`, `max`, `type="linear"`, `type="logarithmic"`.
-* Chart title
-* Most data structures (not including `parsing` or non-standard axes identifiers)
-* Dataset visibility (when you show/hide a category from the legend)
-
-Note that visual-specific chart features are ignored. This includes things like color, padding, line thickness, etc.
-
-Things we plan to support in the future:
-* Interactions and updates
-* Other chart.js plugins
-* Complex `parsing` options for data
-* Date/Time support for axes
-* Subtitle
-* Radar charts
-* Custom formatting for axis tick values
-
-Plugins we plan to support in the future:
-* [chartjs-char-error-bars](https://www.npmjs.com/package/chartjs-chart-error-bars)
-* [chartjs-chart-matrix](https://www.npmjs.com/package/chartjs-chart-matrix)
-* [chartjs-chart-pcp](https://www.npmjs.com/package/chartjs-chart-pcp)
-* [chartjs-plugin-zoom](https://www.npmjs.com/package/chartjs-plugin-zoom)
+More examples are available in the [CodePen collection](https://codepen.io/collection/VYEvEQ).
+
+## Development
+
+```bash
+npm test
+npm run build
+npm run depcheck
+```

package/dist/plugin.amd.js

@@ -84,7 +84,8 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
         boxplot: "box",
         radar: "bar",
         wordCloud: "bar",
-        scatter: "scatter"
+        scatter: "scatter",
+        matrix: "matrix"
     };
     const processChartType = (chart) => {
         const topLevelType = chart.config.type;
@@ -134,13 +135,13 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
         }
         return axis;
     };
-    const generateAxes = (chart) => {
+    const generateAxes = (chart, options) => {
         const axes = {
             x: {
                 ...generateAxisInfo(chart.options?.scales?.x, chart),
             },
             y: {
-                format: (value) => value.toLocaleString(),
+                format: options?.axes?.y?.format || ((value) => value.toLocaleString()),
                 ...generateAxisInfo(chart.options?.scales?.y, chart),
             }
         };
@@ -159,6 +160,55 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
         }
         return data;
     };
+    const labelIndex = (labels, value) => {
+        let index = labels.indexOf(value);
+        if (index === -1) {
+            labels.push(value);
+            index = labels.length - 1;
+        }
+        return index;
+    };
+    const processMatrixDataPoints = (data, datasetIndex, xLabels, yLabels) => {
+        return data.map((point, index) => {
+            const x = typeof point.x === "string" ? labelIndex(xLabels, point.x) : point.x;
+            const y = typeof point.y === "string" ? labelIndex(yLabels, point.y) : point.y;
+            return {
+                ...point,
+                x,
+                y,
+                custom: {
+                    ...point.custom,
+                    group: datasetIndex,
+                    datasetIndex,
+                    index
+                }
+            };
+        });
+    };
+    const processMatrixData = (data) => {
+        const xLabels = [];
+        const yLabels = [];
+        // Chart2Music represents matrix rows as groups and columns as points within
+        // each group. This preserves two-dimensional keyboard navigation.
+        const result = {};
+        data.datasets.forEach((obj, index) => {
+            const points = processMatrixDataPoints(obj.data, index, xLabels, yLabels);
+            points.forEach((point) => {
+                const rowLabel = typeof point.y === "number" && yLabels[point.y] !== undefined
+                    ? yLabels[point.y]
+                    : String(point.y);
+                const groupName = data.datasets.length === 1
+                    ? rowLabel
+                    : `${obj.label ?? `Group ${index + 1}`}: ${rowLabel}`;
+                if (!result[groupName]) {
+                    result[groupName] = [];
+                }
+                result[groupName].push(point);
+            });
+        });
+        Object.values(result).forEach((row) => row.sort((a, b) => a.x - b.x));
+        return { groups: Object.keys(result), data: result, xLabels, yLabels };
+    };
     const scrubX = (data) => {
         const blackboard = JSON.parse(JSON.stringify(data));
         let labels = [];
@@ -173,11 +223,18 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
             });
             return { labels, data: blackboard };
         }
+        else {
+            // Grouped
+            return undefined;
+        }
     };
     const processData = (data, c2m_types) => {
         if (c2m_types === "box") {
             return processBoxData(data);
         }
+        if (c2m_types === "matrix") {
+            return processMatrixData(data);
+        }
         let groups = [];
         if (data.datasets.length === 1) {
             return {
@@ -209,26 +266,36 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
         canvas.insertAdjacentElement("afterend", cc);
         return cc;
     };
+    const createDataSnapshot = (chart) => {
+        return JSON.stringify({
+            datasets: chart.data.datasets.map(ds => ds.data),
+            labels: chart.data.labels
+        });
+    };
     const displayPoint = (chart) => {
         if (!chartStates.has(chart)) {
             return;
         }
-        const { c2m: ref, visible_groups } = chartStates.get(chart);
+        const { c2m: ref } = chartStates.get(chart);
         const { point, index } = ref.getCurrent();
+        // Use Chart2Music's internal visible group tracking
+        // @ts-ignore - accessing internal Chart2Music property
+        const visibleGroupIndices = ref._visible_group_indices?.slice(1) || [];
         try {
             const highlightElements = [];
             if ("custom" in point) {
+                const customPoint = point;
                 highlightElements.push({
-                    // @ts-ignore
-                    datasetIndex: point.custom.group,
-                    // @ts-ignore
-                    index: point.custom.index
+                    datasetIndex: customPoint.custom.datasetIndex ?? customPoint.custom.group,
+                    index: customPoint.custom.index
                 });
             }
             else {
-                visible_groups.forEach((datasetIndex) => {
+                // For stacked charts, Chart2Music includes an "All" group at index 0,
+                // so we subtract 1 to get the actual dataset index
+                visibleGroupIndices.forEach((groupIndex) => {
                     highlightElements.push({
-                        datasetIndex,
+                        datasetIndex: groupIndex - 1,
                         index
                     });
                 });
@@ -244,11 +311,10 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
     const generateChart = (chart, options) => {
         const { valid, c2m_types, invalidType } = processChartType(chart);
         if (!valid) {
-            // @ts-ignore
             options.errorCallback?.(`Unable to connect chart2music to chart. The chart is of type "${invalidType}", which is not one of the supported chart types for this plugin. This plugin supports: ${Object.keys(chartjs_c2m_converter).join(", ")}`);
             return;
         }
-        let axes = generateAxes(chart);
+        let axes = generateAxes(chart, options);
         if (chart.config.type === "wordCloud") {
             delete axes.x.minimum;
             delete axes.x.maximum;
@@ -263,8 +329,20 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
         }
         // Generate CC element
         const cc = determineCCElement(chart.canvas, options.cc);
-        const { data, groups } = processData(chart.data, c2m_types);
+        const processedData = processData(chart.data, c2m_types);
+        const { data } = processedData;
         // lastDataObj = JSON.stringify(data);
+        if (c2m_types === "matrix") {
+            if (processedData.xLabels?.length > 0) {
+                axes.x.valueLabels = processedData.xLabels.slice(0);
+            }
+            if (processedData.yLabels?.length > 0) {
+                // Category labels provide the Matrix Plot's Y-axis formatter.
+                // The general numeric formatter would otherwise announce row indexes.
+                delete axes.y.format;
+                axes.y.valueLabels = processedData.yLabels.slice(0);
+            }
+        }
         let scrub = scrubX(data);
         if (scrub?.labels && scrub?.labels?.length > 0) { // Something was scrubbed
             if (!chart.data.labels || chart.data.labels.length === 0) {
@@ -286,6 +364,13 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
                 ...(options.axes?.y)
             },
         };
+        // Start with plugin's internal onFocusCallback
+        const pluginOnFocusCallback = () => {
+            displayPoint(chart);
+        };
+        // Merge user's options, wrapping onFocusCallback if provided
+        const userOptions = options.options || {};
+        const userOnFocusCallback = userOptions.onFocusCallback;
         const c2mOptions = {
             cc,
             element: chart.canvas,
@@ -294,10 +379,13 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
             title: determineChartTitle(chart.options),
             axes,
             options: {
-                // @ts-ignore
-                onFocusCallback: () => {
-                    displayPoint(chart);
-                }
+                ...userOptions,
+                onFocusCallback: userOnFocusCallback
+                    ? (point) => {
+                        pluginOnFocusCallback();
+                        userOnFocusCallback(point);
+                    }
+                    : pluginOnFocusCallback
             }
         };
         if (Array.isArray(c2mOptions.data)) {
@@ -306,8 +394,9 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
                     return {
                         ...point,
                         custom: {
-                            group: 0,
-                            index
+                            ...point.custom,
+                            group: point.custom?.group ?? 0,
+                            index: point.custom?.index ?? index
                         }
                     };
                 });
@@ -326,10 +415,11 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
             }
         }
         else {
-            const groups = Object.keys(c2mOptions.data);
+            const dataObj = c2mOptions.data;
+            const groups = Object.keys(dataObj);
             groups.forEach((groupName, groupNumber) => {
-                if (!isNaN(c2mOptions.data[groupName][0])) {
-                    c2mOptions.data[groupName] = c2mOptions.data[groupName].map((num, index) => {
+                if (!isNaN(dataObj[groupName][0])) {
+                    dataObj[groupName] = dataObj[groupName].map((num, index) => {
                         return {
                             x: index,
                             y: num,
@@ -341,26 +431,25 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
                     });
                 }
                 else {
-                    c2mOptions.data[groupName] = c2mOptions.data[groupName].map((point, index) => {
+                    dataObj[groupName] = dataObj[groupName].map((point, index) => {
                         return {
                             ...point,
                             custom: {
-                                group: groupNumber,
-                                index
+                                ...point.custom,
+                                group: point.custom?.group ?? groupNumber,
+                                index: point.custom?.index ?? index
                             }
                         };
                     });
                 }
             });
         }
-        // @ts-ignore
         if (chart.config.options?.scales?.x?.stacked) {
-            // @ts-ignore
-            c2mOptions.options.stack = true;
+            if (c2mOptions.options) {
+                c2mOptions.options.stack = true;
+            }
         }
-        // @ts-ignore
         if (options.audioEngine) {
-            // @ts-ignore
             c2mOptions.audioEngine = options.audioEngine;
         }
         if (c2mOptions.data.length === 0) {
@@ -372,7 +461,6 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
         const { err, data: c2m } = c2mChart(c2mOptions);
         /* istanbul-ignore-next */
         if (err) {
-            // @ts-ignore
             options.errorCallback?.(err);
             return;
         }
@@ -381,12 +469,32 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
         }
         chartStates.set(chart, {
             c2m,
-            visible_groups: groups?.map((g, i) => i) ?? []
+            lastDataSnapshot: createDataSnapshot(chart)
         });
+        if (c2m_types === "matrix") {
+            const matrixKeydown = (event) => {
+                if (event.key !== "ArrowUp" && event.key !== "ArrowDown") {
+                    return;
+                }
+                event.preventDefault();
+                event.stopImmediatePropagation();
+                const actions = c2m._availableActions;
+                if (event.key === "ArrowUp") {
+                    actions.next_category();
+                }
+                else {
+                    actions.previous_category();
+                }
+            };
+            chart.canvas.addEventListener("keydown", matrixKeydown, true);
+            const state = chartStates.get(chart);
+            state.matrixKeydown = matrixKeydown;
+            state.matrixKeydownTarget = chart.canvas;
+        }
     };
     const plugin = {
         id: "chartjs2music",
-        afterInit: (chart, args, options) => {
+        afterInit: (chart, _args, options) => {
             if (!chartStates.has(chart)) {
                 generateChart(chart, options);
                 // Remove tooltip when the chart blurs
@@ -413,19 +521,17 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
             if (!chartStates.has(chart)) {
                 generateChart(chart, options);
             }
-            const { c2m: ref, visible_groups } = chartStates.get(chart);
+            const { c2m: ref } = chartStates.get(chart);
             if (!ref) {
                 return;
             }
-            // @ts-ignore
-            const groups = ref._groups.slice(0);
-            // @ts-ignore
-            if (ref._options.stack) {
+            const refInternal = ref;
+            const groups = refInternal._groups.slice(0);
+            if (refInternal._options.stack) {
                 groups.shift();
             }
             if (args.mode === "hide") {
                 const err = ref.setCategoryVisibility(groups[args.index], false);
-                visible_groups.splice(args.index, 1);
                 if (err) {
                     console.error(err);
                 }
@@ -433,24 +539,49 @@ define(['chart2music'], (function (c2mChart) { 'use strict';
             }
             if (args.mode === "show") {
                 const err = ref.setCategoryVisibility(groups[args.index], true);
-                visible_groups.push(args.index);
                 if (err) {
                     console.error(err);
                 }
                 return;
             }
         },
+        afterDatasetsUpdate: (chart, _args, options) => {
+            const state = chartStates.get(chart);
+            if (!state?.c2m)
+                return;
+            // Check if data has changed
+            const currentSnapshot = createDataSnapshot(chart);
+            if (currentSnapshot === state.lastDataSnapshot) {
+                return; // No data change, skip update
+            }
+            // Get chart type
+            const { valid, c2m_types } = processChartType(chart);
+            if (!valid)
+                return;
+            // Process data and generate axes
+            const { data } = processData(chart.data, c2m_types);
+            const axes = generateAxes(chart, options);
+            // Update Chart2Music with new data
+            state.c2m.setData(data, axes);
+            // Update snapshot
+            state.lastDataSnapshot = currentSnapshot;
+        },
         afterDestroy: (chart) => {
-            const { c2m: ref } = chartStates.get(chart);
-            if (!ref) {
+            const state = chartStates.get(chart);
+            if (!state?.c2m) {
                 return;
             }
+            const { c2m: ref } = state;
+            if (state?.matrixKeydown && state.matrixKeydownTarget) {
+                state.matrixKeydownTarget.removeEventListener("keydown", state.matrixKeydown, true);
+            }
             ref.cleanUp();
         },
         defaults: {
             cc: null,
             audioEngine: null,
-            errorCallback: null
+            errorCallback: null,
+            options: {}
         }
     };