@ons/design-system 72.4.0 → 72.6.0

package/components/chart/annotations-options.js

@@ -0,0 +1,78 @@
+import ChartConstants from './chart-constants';
+
+class AnnotationsOptions {
+    constructor(annotations) {
+        this.constants = ChartConstants.constants();
+        this.annotations = annotations;
+    }
+
+    getAnnotationsOptionsDesktop = () => {
+        let annotations = [
+            {
+                labels: [],
+                labelOptions: {
+                    shape: 'connector',
+                    borderColor: this.constants.labelColor,
+                    padding: 3,
+                    style: {
+                        color: this.constants.labelColor,
+                        fontSize: this.constants.desktopFontSize,
+                        width: 150,
+                        textAlign: 'left',
+                    },
+                },
+                draggable: '',
+            },
+        ];
+        this.annotations.forEach((annotation) => {
+            annotations[0].labels.push({
+                point: {
+                    x: annotation.point.x,
+                    y: annotation.point.y,
+                    xAxis: 0,
+                    yAxis: 0,
+                },
+                text: annotation.text,
+                x: annotation.labelOffsetX,
+                y: annotation.labelOffsetY,
+            });
+        });
+        return annotations;
+    };
+
+    getAnnotationsOptionsMobile = () => {
+        let annotations = [
+            {
+                labels: [],
+                labelOptions: {
+                    backgroundColor: 'transparent',
+                    borderColor: 'transparent',
+                    // We use css styling for the rounded number annotation at mobile
+                    useHTML: true,
+                    className: 'ons-chart__footnote-number',
+                },
+                draggable: '',
+            },
+        ];
+        this.annotations.forEach((annotation, index) => {
+            annotations[0].labels.push({
+                point: {
+                    x: annotation.point.x,
+                    y: annotation.point.y,
+                    xAxis: 0,
+                    yAxis: 0,
+                },
+                text: index + 1,
+                x: 0,
+                y: 0,
+                // Ensures the full label is read out by screen readers
+                accessibility: {
+                    description: annotation.text,
+                },
+            });
+        });
+        return annotations;
+    };
+}
+
+export default AnnotationsOptions;

package/components/chart/bar-chart.js

@@ -0,0 +1,164 @@
+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 (series.type == 'line') {
+                    // If we have a bar chart with an extra line, exit early for the line series
+                    return;
+                }
+                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, numberOfExtraLines) => {
+        const numberOfCategories = config.xAxis.categories.length;
+        const numberOfSeries = currentChart.series.length - numberOfExtraLines; // 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));
+    });
+});

package/components/chart/chart.js

@@ -0,0 +1,242 @@
+import Highcharts from 'highcharts';
+import 'highcharts/modules/accessibility';
+import 'highcharts/modules/annotations';
+
+import CommonChartOptions from './common-chart-options';
+import SpecificChartOptions from './specific-chart-options';
+import LineChart from './line-chart';
+import BarChart from './bar-chart';
+import ColumnChart from './column-chart';
+import AnnotationsOptions from './annotations-options';
+
+class HighchartsBaseChart {
+    static selector() {
+        return '[data-highcharts-base-chart]';
+    }
+
+    constructor(node) {
+        this.node = node;
+        this.chartType = this.node.dataset.highchartsType;
+        this.theme = this.node.dataset.highchartsTheme;
+        const chartNode = this.node.querySelector('[data-highcharts-chart]');
+        this.id = this.node.dataset.highchartsId;
+        this.useStackedLayout = this.node.hasAttribute('data-highcharts-use-stacked-layout');
+        this.config = JSON.parse(this.node.querySelector(`[data-highcharts-config--${this.id}]`).textContent);
+        if (this.node.querySelector(`[data-highcharts-annotations--${this.id}]`)) {
+            const annotations = JSON.parse(this.node.querySelector(`[data-highcharts-annotations--${this.id}]`).textContent);
+            this.annotationsOptions = new AnnotationsOptions(annotations);
+        }
+        this.percentageHeightDesktop = this.node.dataset.highchartsPercentageHeightDesktop;
+        this.percentageHeightMobile = this.node.dataset.highchartsPercentageHeightMobile;
+        this.commonChartOptions = new CommonChartOptions();
+        this.specificChartOptions = new SpecificChartOptions(this.theme, this.chartType, this.config);
+        this.lineChart = new LineChart();
+        this.barChart = new BarChart();
+        this.columnChart = new ColumnChart();
+        this.extraLines = this.checkForExtraLines();
+        if (window.isCommonChartOptionsDefined === undefined) {
+            this.setCommonChartOptions();
+            window.isCommonChartOptionsDefined = true;
+        }
+        this.hideDataLabels = this.checkHideDataLabels();
+        this.setSpecificChartOptions();
+        this.setResponsiveOptions();
+        this.setLoadEvent();
+        this.setWindowResizeEvent();
+        this.chart = Highcharts.chart(chartNode, this.config);
+    }
+
+    // Check for the number of extra line series in the config
+    checkForExtraLines = () => {
+        return this.chartType === 'line' ? 0 : this.config.series.filter((series) => series.type === 'line').length;
+    };
+
+    // Set up the global Highcharts options which are used for all charts
+    setCommonChartOptions = () => {
+        const chartOptions = this.commonChartOptions.getOptions();
+        Highcharts.setOptions(chartOptions);
+    };
+
+    // Utility function to merge two configs together
+    mergeConfigs = (baseConfig, newConfig) => {
+        // If newConfig is null/undefined, return baseConfig
+        if (!newConfig) return baseConfig;
+
+        // Create a new object to store the merged result
+        const merged = { ...baseConfig };
+
+        // Iterate through all keys in newConfig
+        Object.keys(newConfig).forEach((key) => {
+            // Get values from both configs for this key
+            const baseValue = merged[key];
+            const newValue = newConfig[key];
+
+            // If both values are objects (and not null), recursively merge them
+            if (
+                baseValue &&
+                newValue &&
+                typeof baseValue === 'object' &&
+                typeof newValue === 'object' &&
+                !Array.isArray(baseValue) &&
+                !Array.isArray(newValue)
+            ) {
+                merged[key] = this.mergeConfigs(baseValue, newValue);
+            } else {
+                // For non-objects and arrays use the new value
+                // If the new value is null/undefined, use the base value
+                merged[key] = newValue ?? baseValue;
+            }
+        });
+
+        return merged;
+    };
+
+    // Set up options for specific charts and chart types
+    setSpecificChartOptions = () => {
+        const specificChartOptions = this.specificChartOptions.getOptions();
+        const lineChartOptions = this.lineChart.getLineChartOptions();
+        const barChartOptions = this.barChart.getBarChartOptions(this.useStackedLayout);
+        const columnChartOptions = this.columnChart.getColumnChartOptions(this.useStackedLayout);
+        // Merge specificChartOptions with the existing config
+        this.config = this.mergeConfigs(this.config, specificChartOptions);
+
+        if (this.chartType === 'line') {
+            // Merge the line chart options with the existing config
+            this.config = this.mergeConfigs(this.config, lineChartOptions);
+        }
+
+        if (this.chartType === 'bar') {
+            // Merge the bar chart options with the existing config
+            this.config = this.mergeConfigs(this.config, barChartOptions);
+        }
+        if (this.chartType === 'column') {
+            // Merge the column chart options with the existing config
+            this.config = this.mergeConfigs(this.config, columnChartOptions);
+        }
+
+        if (this.extraLines > 0) {
+            this.config = this.mergeConfigs(this.config, this.lineChart.getLineChartOptions());
+            if (this.chartType === 'column') {
+                this.config = this.mergeConfigs(this.config, columnChartOptions);
+            }
+            if (this.chartType === 'bar') {
+                this.config = this.mergeConfigs(this.config, barChartOptions);
+            }
+        }
+
+        // Disable the legend for single series charts
+        this.commonChartOptions.disableLegendForSingleSeries(this.config);
+    };
+
+    // Check if the data labels should be hidden
+    // They should be hidden for clustered bar charts with more than 2 series, and also for stacked bar charts
+    checkHideDataLabels = () => {
+        return (this.chartType === 'bar' && this.config.series.length > 2) || this.useStackedLayout === true;
+    };
+
+    // Adjust font size and annotations for smaller width of chart
+    // Note this is not the same as the viewport width
+    // All responsive rules should be defined here to avoid overriding existing rules
+    setResponsiveOptions = () => {
+        const mobileCommonChartOptions = this.commonChartOptions.getMobileOptions();
+        if (!this.config.responsive) {
+            this.config.responsive = {};
+        }
+        // If these conditions change, the styling for the footnotes container query in _chart.scss needs to be updated
+        let rules = [
+            {
+                condition: {
+                    maxWidth: 400,
+                },
+                chartOptions: {
+                    ...mobileCommonChartOptions,
+                },
+            },
+            // We are using a slightly wider breakpoint for annotations
+            // to try and reduce the likelihood of them being automatically
+            // hidden by Highcharts
+            {
+                condition: {
+                    maxWidth: 600,
+                },
+                chartOptions: {
+                    annotations: this.annotationsOptions ? this.annotationsOptions.getAnnotationsOptionsMobile() : undefined,
+                },
+            },
+            {
+                condition: {
+                    minWidth: 601,
+                },
+                chartOptions: {
+                    annotations: this.annotationsOptions ? this.annotationsOptions.getAnnotationsOptionsDesktop() : undefined,
+                },
+            },
+        ];
+        this.config.responsive.rules = rules;
+    };
+
+    // Create the load event for various chart types
+    // All load events should be defined here to avoid overriding existing events
+    setLoadEvent = () => {
+        if (!this.config.chart.events) {
+            this.config.chart.events = {};
+        }
+        this.config.chart.events.load = (event) => {
+            const currentChart = event.target;
+            if (this.chartType === 'line') {
+                this.lineChart.updateLastPointMarker(currentChart.series);
+                this.commonChartOptions.hideDataLabels(currentChart.series);
+            }
+            if (this.chartType === 'bar') {
+                this.barChart.updateBarChartHeight(this.config, currentChart, this.useStackedLayout, this.extraLines);
+                if (!this.hideDataLabels) {
+                    this.barChart.postLoadDataLabels(currentChart);
+                } else {
+                    this.commonChartOptions.hideDataLabels(currentChart.series);
+                }
+            }
+            if (this.chartType === 'column') {
+                this.columnChart.updatePointPadding(this.config, currentChart, this.useStackedLayout, this.extraLines);
+                this.commonChartOptions.hideDataLabels(currentChart.series);
+            }
+            if (this.chartType != 'bar') {
+                this.commonChartOptions.adjustChartHeight(currentChart, this.percentageHeightDesktop, this.percentageHeightMobile);
+            }
+
+            // If the chart has an extra line or lines, hide the data labels for
+            // that series, update the last point marker
+            if (this.extraLines > 0) {
+                currentChart.series.forEach((series) => {
+                    if (series.type === 'line') {
+                        this.lineChart.updateLastPointMarker([series]);
+                        this.commonChartOptions.hideDataLabels([series]);
+                    }
+                });
+            }
+            // Update the legend items for all charts
+            this.commonChartOptions.updateLegendSymbols(currentChart);
+            currentChart.redraw(false);
+        };
+    };
+
+    // Set resize events - throttled to 50ms
+    // All resize events should be defined here to avoid overriding existing events
+    setWindowResizeEvent = () => {
+        window.addEventListener('resize', () => {
+            clearTimeout(this.resizeTimeout);
+            this.resizeTimeout = setTimeout(() => {
+                // Get the current rendered chart instance
+                const currentChart = Highcharts.charts.find((chart) => chart && chart.container === this.chart.container);
+                // Update the data labels when the window is resized
+                if (this.chartType === 'bar' && !this.hideDataLabels) {
+                    this.barChart.postLoadDataLabels(currentChart);
+                }
+                if (this.chartType != 'bar') {
+                    this.commonChartOptions.adjustChartHeight(currentChart, this.percentageHeightDesktop, this.percentageHeightMobile);
+                }
+            }, 50);
+        });
+    };
+}
+
+export default HighchartsBaseChart;

package/components/chart/column-chart.js

@@ -0,0 +1,48 @@
+class ColumnChart {
+    getColumnChartOptions = (useStackedLayout) => {
+        return {
+            plotOptions: {
+                column: {
+                    pointPadding: 0,
+                    groupPadding: 0,
+                    borderRadius: 0,
+                    borderWidth: 0,
+                },
+                series: {
+                    stacking: useStackedLayout ? 'normal' : null,
+                },
+            },
+        };
+    };
+
+    // Set the point padding between each bar to be 3% (an overall gap of 6%)
+    // For charts with fewer than 5 categories, we use a wider point padding of 4% (8% gap between bars)
+    // For cluster charts we use 0 for the point padding and a group padding of 4% (8% gap between bars)
+    updatePointPadding = (config, currentChart, stackedLayout, numberOfExtraLines) => {
+        const numberOfCategories = config.xAxis.categories.length;
+        const numberOfSeries = currentChart.series.length - numberOfExtraLines; // Get number of column series
+        let pointPadding = 0;
+        let groupPadding = 0;
+        // non-clustered charts or stacked charts
+        if (numberOfSeries === 1 || stackedLayout === true) {
+            if (numberOfCategories > 5) {
+                pointPadding = 0.03;
+            } else {
+                pointPadding = 0.04;
+            }
+        } else {
+            // clustered charts
+            groupPadding = 0.04;
+        }
+
+        // update the point width and padding
+        currentChart.series.forEach((series) => {
+            series.update({
+                pointPadding: pointPadding,
+                groupPadding: groupPadding,
+            });
+        });
+    };
+}
+
+export default ColumnChart;