@ons/design-system 72.3.0 → 72.5.0

package/components/chart/_macro.spec.js

@@ -0,0 +1,437 @@
+/** @jest-environment jsdom */
+
+import * as cheerio from 'cheerio';
+
+import axe from '../../tests/helpers/axe';
+import { renderComponent } from '../../tests/helpers/rendering';
+import {
+    EXAMPLE_LINE_CHART_REQUIRED_PARAMS,
+    EXAMPLE_LINE_CHART_WITH_CONFIG_PARAMS,
+    EXAMPLE_BAR_CHART_PARAMS,
+    EXAMPLE_COLUMN_CHART_PARAMS,
+} from './_test-examples';
+
+describe('Macro: Chart', () => {
+    describe('FOR: Line Chart', () => {
+        describe('GIVEN: Params: required', () => {
+            describe('WHEN: required params are provided', () => {
+                const $ = cheerio.load(renderComponent('chart', EXAMPLE_LINE_CHART_REQUIRED_PARAMS));
+
+                test('THEN: it passes jest-axe checks', async () => {
+                    const results = await axe($.html());
+                    expect(results).toHaveNoViolations();
+                });
+
+                test('THEN: it renders the subtitle', () => {
+                    expect($('.ons-chart__subtitle').text()).toBe('A sample subtitle');
+                });
+
+                test('THEN: it renders the chart container with the correct data attributes', () => {
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-type')).toBe('line');
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-title')).toBe('Example Line Chart');
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-id')).toBe('chart-123');
+                });
+
+                test('THEN: it includes the Highcharts JSON config', () => {
+                    const configScript = $(`script[data-highcharts-config--chart-123]`).html();
+                    expect(configScript).toContain('"text":"X Axis Title"');
+                    expect(configScript).toContain('"text":"Y Axis Title"');
+                });
+
+                test('THEN: it does NOT render optional fields', () => {
+                    expect($('figcaption').length).toBe(0);
+                    expect($('.ons-chart__download-title').length).toBe(0);
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Theme', () => {
+            describe('WHEN: theme is provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_LINE_CHART_REQUIRED_PARAMS,
+                        theme: 'primary',
+                    }),
+                );
+
+                test('THEN: it renders the chart container with the correct theme', () => {
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-theme')).toBe('primary');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Heading Level', () => {
+            describe('WHEN: heading level is provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_LINE_CHART_REQUIRED_PARAMS,
+                        headingLevel: 3,
+                        download: {
+                            title: 'Download Chart Data',
+                            itemsList: [
+                                { text: 'Download as PNG', url: 'https://example.com/chart.png' },
+                                { text: 'Download as CSV', url: 'https://example.com/chart.csv' },
+                            ],
+                        },
+                    }),
+                );
+
+                test('THEN: renders title with correct tag', () => {
+                    expect($('.ons-chart__title')[0].tagName).toBe('h3');
+                });
+
+                test('THEN: renders subtitle with correct tag', () => {
+                    expect($('.ons-chart__subtitle')[0].tagName).toBe('h4');
+                });
+
+                test('THEN: renders download title with correct tag', () => {
+                    expect($('.ons-chart__download-title')[0].tagName).toBe('h5');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Config', () => {
+            describe('WHEN: config params are provided', () => {
+                const $ = cheerio.load(renderComponent('chart', EXAMPLE_LINE_CHART_WITH_CONFIG_PARAMS));
+                const configScript = $(`script[data-highcharts-config--chart-456]`).html();
+
+                test('THEN: it renders the legend when enabled', () => {
+                    expect(configScript).toContain('"enabled":true');
+                });
+
+                test('THEN: it includes correct xAxis properties', () => {
+                    expect(configScript).toContain('"text":"X Axis Label"');
+                    expect(configScript).toContain('"categories":["A","B","C"]');
+                    expect(configScript).toContain('"type":"linear"');
+                });
+
+                test('THEN: it includes correct yAxis properties', () => {
+                    expect(configScript).toContain('"text":"Y Axis Label"');
+                    expect(configScript).toContain('"labels":{"format":"{value:,.f}"}');
+                });
+
+                test('THEN: it includes correct series data', () => {
+                    expect(configScript).toContain('"name":"Category 1"');
+                    expect(configScript).toContain('"data":[5,15,25]');
+                    expect(configScript).toContain('"name":"Category 2"');
+                    expect(configScript).toContain('"data":[10,20,30]');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Caption', () => {
+            describe('WHEN: caption is provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_LINE_CHART_REQUIRED_PARAMS,
+                        caption: 'This is an example caption for the chart.',
+                    }),
+                );
+
+                test('THEN: it renders the caption when provided', () => {
+                    expect($('figcaption').text()).toBe('This is an example caption for the chart.');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Description', () => {
+            describe('WHEN: description is provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_LINE_CHART_REQUIRED_PARAMS,
+                        description: 'An accessible description for screen readers.',
+                    }),
+                );
+
+                test('THEN: it renders the description for accessibility', () => {
+                    expect($('.ons-u-vh').text()).toBe('An accessible description for screen readers.');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Download', () => {
+            describe('WHEN: download object are provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_LINE_CHART_REQUIRED_PARAMS,
+                        download: {
+                            title: 'Download Chart Data',
+                            itemsList: [
+                                { text: 'Download as PNG', url: 'https://example.com/chart.png' },
+                                { text: 'Download as CSV', url: 'https://example.com/chart.csv' },
+                            ],
+                        },
+                    }),
+                );
+
+                test('THEN: it renders the download section correctly', () => {
+                    expect($('.ons-chart__download-title').text()).toBe('Download Chart Data');
+
+                    const downloadLinks = $('.ons-chart__download-title').next().find('li a');
+                    expect(downloadLinks.eq(0).text()).toBe('Download as PNG');
+                    expect(downloadLinks.eq(0).attr('href')).toBe('https://example.com/chart.png');
+                    expect(downloadLinks.eq(1).text()).toBe('Download as CSV');
+                    expect(downloadLinks.eq(1).attr('href')).toBe('https://example.com/chart.csv');
+                });
+            });
+        });
+    });
+
+    describe('FOR: Bar Chart', () => {
+        describe('GIVEN: Params: required', () => {
+            describe('WHEN: required params are provided', () => {
+                const $ = cheerio.load(renderComponent('chart', EXAMPLE_BAR_CHART_PARAMS));
+
+                test('THEN: it passes jest-axe checks', async () => {
+                    const results = await axe($.html());
+                    expect(results).toHaveNoViolations();
+                });
+
+                test('THEN: it renders the chart container with the correct data attributes', () => {
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-type')).toBe('bar');
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-theme')).toBe('alternate');
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-title')).toBe('Example Bar Chart');
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-id')).toBe('bar-chart-123');
+                });
+
+                test('THEN: it does NOT render optional fields', () => {
+                    expect($('figcaption').length).toBe(0);
+                    expect($('.ons-chart__download-title').length).toBe(0);
+                });
+
+                test('THEN: it includes the Highcharts JSON config', () => {
+                    const configScript = $(`script[data-highcharts-config--bar-chart-123]`).html();
+                    expect(configScript).toContain('"text":"X Axis Title"');
+                    expect(configScript).toContain('"text":"Y Axis Title"');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Config', () => {
+            describe('WHEN: config params are provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_BAR_CHART_PARAMS,
+                        legend: true,
+                    }),
+                );
+
+                test('THEN: it renders the legend when enabled', () => {
+                    const configScript = $(`script[data-highcharts-config--bar-chart-123]`).html();
+                    expect(configScript).toContain('"enabled":true');
+                });
+
+                test('THEN: it includes correct xAxis and yAxis titles', () => {
+                    const configScript = $(`script[data-highcharts-config--bar-chart-123]`).html();
+                    expect(configScript).toContain('"text":"X Axis Title"');
+                    expect(configScript).toContain('"text":"Y Axis Title"');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Caption', () => {
+            describe('WHEN: caption is provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_BAR_CHART_PARAMS,
+                        caption: 'This is an example caption for the chart.',
+                    }),
+                );
+
+                test('THEN: it renders the caption when provided', () => {
+                    expect($('figcaption').text()).toBe('This is an example caption for the chart.');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Description', () => {
+            describe('WHEN: description is provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_BAR_CHART_PARAMS,
+                        description: 'An accessible description for screen readers.',
+                    }),
+                );
+
+                test('THEN: it renders the description for accessibility', () => {
+                    expect($('.ons-u-vh').text()).toBe('An accessible description for screen readers.');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Download', () => {
+            describe('WHEN: download object are provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_BAR_CHART_PARAMS,
+                        download: {
+                            title: 'Download Chart Data',
+                            itemsList: [
+                                { text: 'Download as PNG', url: 'https://example.com/chart.png' },
+                                { text: 'Download as CSV', url: 'https://example.com/chart.csv' },
+                            ],
+                        },
+                    }),
+                );
+
+                test('THEN: it renders the download section correctly', () => {
+                    expect($('.ons-chart__download-title').text()).toBe('Download Chart Data');
+
+                    const downloadLinks = $('.ons-chart__download-title').next().find('li a');
+                    expect(downloadLinks.eq(0).text()).toBe('Download as PNG');
+                    expect(downloadLinks.eq(0).attr('href')).toBe('https://example.com/chart.png');
+                    expect(downloadLinks.eq(1).text()).toBe('Download as CSV');
+                    expect(downloadLinks.eq(1).attr('href')).toBe('https://example.com/chart.csv');
+                });
+            });
+        });
+
+        describe('GIVEN: Stacked Bar Chart', () => {
+            describe('WHEN: Stacked layout is enabled', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_BAR_CHART_PARAMS,
+                        useStackedLayout: true,
+                    }),
+                );
+
+                test('THEN: it includes stacking in the config', () => {
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-use-stacked-layout')).toBe('true');
+                });
+
+                test('THEN: it renders a bar chart with stacked series', () => {
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-type')).toBe('bar');
+                });
+            });
+        });
+    });
+
+    describe('FOR: Column Chart', () => {
+        describe('GIVEN: Params: required', () => {
+            describe('WHEN: required params are provided', () => {
+                const $ = cheerio.load(renderComponent('chart', EXAMPLE_COLUMN_CHART_PARAMS));
+
+                test('THEN: it passes jest-axe checks', async () => {
+                    const results = await axe($.html());
+                    expect(results).toHaveNoViolations();
+                });
+
+                test('THEN: it renders the chart container with the correct data attributes', () => {
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-type')).toBe('column');
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-theme')).toBe('alternate');
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-title')).toBe('Example Column Chart');
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-id')).toBe('column-chart-123');
+                });
+
+                test('THEN: it does NOT render optional fields', () => {
+                    expect($('figcaption').length).toBe(0);
+                    expect($('.ons-chart__download-title').length).toBe(0);
+                });
+
+                test('THEN: it includes the Highcharts JSON config', () => {
+                    const configScript = $(`script[data-highcharts-config--column-chart-123]`).html();
+                    expect(configScript).toContain('"text":"X Axis Title"');
+                    expect(configScript).toContain('"text":"Y Axis Title"');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Config', () => {
+            describe('WHEN: config params are provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_COLUMN_CHART_PARAMS,
+                        legend: true,
+                    }),
+                );
+
+                test('THEN: it renders the legend when enabled', () => {
+                    const configScript = $(`script[data-highcharts-config--column-chart-123]`).html();
+                    expect(configScript).toContain('"enabled":true');
+                });
+
+                test('THEN: it includes correct xAxis and yAxis titles', () => {
+                    const configScript = $(`script[data-highcharts-config--column-chart-123]`).html();
+                    expect(configScript).toContain('"text":"X Axis Title"');
+                    expect(configScript).toContain('"text":"Y Axis Title"');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Caption', () => {
+            describe('WHEN: caption is provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_COLUMN_CHART_PARAMS,
+                        caption: 'This is an example caption for the chart.',
+                    }),
+                );
+
+                test('THEN: it renders the caption when provided', () => {
+                    expect($('figcaption').text()).toBe('This is an example caption for the chart.');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Description', () => {
+            describe('WHEN: description is provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_COLUMN_CHART_PARAMS,
+                        description: 'An accessible description for screen readers.',
+                    }),
+                );
+
+                test('THEN: it renders the description for accessibility', () => {
+                    expect($('.ons-u-vh').text()).toBe('An accessible description for screen readers.');
+                });
+            });
+        });
+
+        describe('GIVEN: Params: Download', () => {
+            describe('WHEN: download object are provided', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_COLUMN_CHART_PARAMS,
+                        download: {
+                            title: 'Download Chart Data',
+                            itemsList: [
+                                { text: 'Download as PNG', url: 'https://example.com/chart.png' },
+                                { text: 'Download as CSV', url: 'https://example.com/chart.csv' },
+                            ],
+                        },
+                    }),
+                );
+
+                test('THEN: it renders the download section correctly', () => {
+                    expect($('.ons-chart__download-title').text()).toBe('Download Chart Data');
+
+                    const downloadLinks = $('.ons-chart__download-title').next().find('li a');
+                    expect(downloadLinks.eq(0).text()).toBe('Download as PNG');
+                    expect(downloadLinks.eq(0).attr('href')).toBe('https://example.com/chart.png');
+                    expect(downloadLinks.eq(1).text()).toBe('Download as CSV');
+                    expect(downloadLinks.eq(1).attr('href')).toBe('https://example.com/chart.csv');
+                });
+            });
+        });
+
+        describe('GIVEN: Stacked Column Chart', () => {
+            describe('WHEN: Stacked layout is enabled', () => {
+                const $ = cheerio.load(
+                    renderComponent('chart', {
+                        ...EXAMPLE_COLUMN_CHART_PARAMS,
+                        useStackedLayout: true,
+                    }),
+                );
+
+                test('THEN: it includes stacking in the config', () => {
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-use-stacked-layout')).toBe('true');
+                });
+
+                test('THEN: it renders a column chart with stacked series', () => {
+                    expect($('[data-highcharts-base-chart]').attr('data-highcharts-type')).toBe('column');
+                });
+            });
+        });
+    });
+});

package/components/chart/bar-chart.js

@@ -0,0 +1,160 @@
+import ChartConstants from './chart-constants';
+
+class BarChart {
+    constructor() {
+        this.constants = ChartConstants.constants();
+    }
+
+    getBarChartOptions = (useStackedLayout) => {
+        return {
+            plotOptions: {
+                bar: {
+                    // Set the width of the bars to be 30px
+                    // The spacing is worked out in the specific-chart-options.js file
+                    pointWidth: 30, // Fixed bar height
+                    pointPadding: 0,
+                    groupPadding: 0,
+                    borderWidth: 0,
+                    borderRadius: 0,
+                    // Set the data labels to be enabled and positioned outside the bars
+                    // We can add custom formatting on each chart to move the labels inside the bars if the bar is wide enough
+                    dataLabels: {
+                        enabled: true,
+                        inside: false,
+                        style: {
+                            textOutline: 'none',
+                            // The design system does not include a semibold font weight, so we use 700 (bold) as an alternative.
+                            fontWeight: '700',
+                            color: this.constants.labelColor,
+                            fontSize: this.constants.mobileFontSize,
+                        },
+                    },
+                },
+                series: {
+                    stacking: useStackedLayout ? 'normal' : null,
+                },
+            },
+            xAxis: {
+                // Update the category label colours for bar charts
+                labels: {
+                    style: {
+                        color: this.constants.categoryLabelColor,
+                    },
+                },
+                // remove the tick marks for bar charts
+                tickWidth: 0,
+                tickLength: 0,
+                tickColor: 'transparent',
+                title: { align: 'high', textAlign: 'middle', reserveSpace: false, rotation: 0, y: -25, useHTML: true },
+            },
+            yAxis: {
+                title: {
+                    // Override the y Axis title settings for bar charts where the y axis is horizontal
+                    textAlign: 'right',
+                    offset: undefined,
+                    y: 0,
+                    reserveSpace: true,
+                    useHTML: false,
+                },
+            },
+        };
+    };
+
+    // Updates the config to move the data labels inside the bars, but only if the bar is wide enough
+    // This may also need to run when the chart is resized
+    postLoadDataLabels = (currentChart) => {
+        const insideOptions = {
+            dataLabels: this.getBarChartLabelsInsideOptions(),
+        };
+        const outsideOptions = {
+            dataLabels: this.getBarChartLabelsOutsideOptions(),
+        };
+
+        currentChart.series.forEach((series) => {
+            const points = series.data;
+            points.forEach((point) => {
+                // Get the actual width of the data label
+                const labelWidth = point.dataLabel && point.dataLabel.getBBox().width;
+                // Move the data labels inside the bar if the bar is wider than the label plus some padding
+                if (point.shapeArgs.height > labelWidth + 20) {
+                    point.update(insideOptions, false);
+                } else {
+                    point.update(outsideOptions, false);
+                }
+            });
+        });
+
+        currentChart.redraw();
+    };
+
+    getBarChartLabelsInsideOptions = () => ({
+        inside: true,
+        align: 'right',
+        verticalAlign: 'middle',
+        style: {
+            color: 'white',
+            fontWeight: 'bold',
+        },
+    });
+
+    getBarChartLabelsOutsideOptions = () => ({
+        inside: false,
+        align: undefined,
+        verticalAlign: undefined,
+        style: {
+            textOutline: 'none',
+            // The design system does not include a semibold font weight, so we use 700 (bold) as an alternative.
+            fontWeight: '700',
+            color: this.constants.labelColor,
+            fontSize: this.constants.mobileFontSize,
+        },
+    });
+
+    // This updates the height of the vertical axis and overall chart to fit the number of categories
+    // Note that the vertical axis on a bar chart is the x axis
+    updateBarChartHeight = (config, currentChart, useStackedLayout) => {
+        const numberOfCategories = config.xAxis.categories.length;
+        const numberOfSeries = currentChart.series.length; // Get number of bar series
+        let barHeight = 30; // Height of each individual bar - set in bar-chart-plot-options
+        let groupSpacing = 0; // Space we want between category groups, or between series groups for cluster charts
+        let categoriesTotalHeight = 0;
+        let totalSpaceHeight = 0;
+        if (useStackedLayout == false && numberOfSeries > 1) {
+            // slightly lower bar height for cluster charts
+            barHeight = 28;
+            // for cluster charts there is no space between the bars within a series, and 14px between each series
+            groupSpacing = 14;
+            // lower barHeight for series with 3 categories or more
+            if (numberOfSeries >= 3) {
+                barHeight = 20;
+            }
+            categoriesTotalHeight = numberOfCategories * barHeight * numberOfSeries;
+
+            totalSpaceHeight = numberOfCategories * groupSpacing;
+            // work out the group padding for cluster charts which is measured in xAxis units.
+            const plotHeight = categoriesTotalHeight + totalSpaceHeight;
+            const xUnitHeight = plotHeight / numberOfCategories;
+            const groupPadding = groupSpacing / 2 / xUnitHeight;
+            currentChart.series.forEach((series) => {
+                series.update({
+                    groupPadding: groupPadding,
+                    pointWidth: barHeight,
+                });
+            });
+        } else {
+            groupSpacing = 10;
+            categoriesTotalHeight = numberOfCategories * barHeight;
+            totalSpaceHeight = (numberOfCategories - 1) * groupSpacing;
+        }
+
+        config.xAxis.height = categoriesTotalHeight + totalSpaceHeight;
+        const totalHeight = currentChart.plotTop + config.xAxis.height + currentChart.marginBottom;
+        if (totalHeight !== currentChart.chartHeight) {
+            currentChart.setSize(null, totalHeight, false);
+        }
+
+        currentChart.redraw();
+    };
+}
+
+export default BarChart;

package/components/chart/chart-constants.js

@@ -0,0 +1,21 @@
+class ChartConstants {
+    static constants() {
+        const constants = {
+            primaryTheme: ['#206095', '#27a0cc', '#003c57', '#118c7b', '#a8bd3a', '#871a5b', '#f66068', '#746cb1', '#22d0b6'],
+            // Alternate theme colours from https://service-manual.ons.gov.uk/data-visualisation/colours/using-colours-in-charts
+            alternateTheme: ['#206095', '#27A0CC', '#871A5B', '#A8BD3A', '#F66068'],
+            labelColor: '#414042',
+            axisLabelColor: '#707071',
+            categoryLabelColor: '#414042',
+            gridLineColor: '#d9d9d9',
+            zeroLineColor: '#b3b3b3',
+            // Responsive font sizes
+            mobileFontSize: '0.75rem', // 12px
+            desktopFontSize: '0.875rem', // 14px
+        };
+
+        return constants;
+    }
+}
+
+export default ChartConstants;

package/components/chart/chart.dom.js

@@ -0,0 +1,8 @@
+import HighchartsBaseChart from './chart';
+import domready from '../../js/domready';
+
+domready(async () => {
+    [HighchartsBaseChart].forEach((Component) => {
+        document.querySelectorAll(Component.selector()).forEach((el) => new Component(el));
+    });
+});