@ons/design-system 72.3.0 → 72.5.0

package/components/chart/chart.js

@@ -0,0 +1,157 @@
+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 Highcharts from 'highcharts';
+import 'highcharts/modules/accessibility';
+
+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);
+
+        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();
+        if (window.isCommonChartOptionsDefined === undefined) {
+            this.setCommonChartOptions();
+            window.isCommonChartOptionsDefined = true;
+        }
+        this.hideDataLabels = this.checkHideDataLabels();
+        this.setSpecificChartOptions();
+        this.setLoadEvent();
+        this.setWindowResizeEvent();
+        this.chart = Highcharts.chart(chartNode, this.config);
+    }
+
+    // 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);
+        }
+    };
+
+    // 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;
+    };
+
+    // Create the load event for various chart types
+    setLoadEvent = () => {
+        if (!this.config.chart.events) {
+            this.config.chart.events = {};
+        }
+        this.config.chart.events.load = (event) => {
+            const currentChart = event.target;
+            // Disable the legend for single series charts
+            this.commonChartOptions.disableLegendForSingleSeries(currentChart);
+            if (this.chartType === 'line') {
+                this.lineChart.updateLastPointMarker(currentChart);
+                this.commonChartOptions.hideDataLabels(currentChart);
+            }
+            if (this.chartType === 'bar') {
+                this.barChart.updateBarChartHeight(this.config, currentChart, this.useStackedLayout);
+                if (!this.hideDataLabels) {
+                    this.barChart.postLoadDataLabels(currentChart);
+                } else {
+                    this.commonChartOptions.hideDataLabels(currentChart);
+                }
+            }
+            if (this.chartType === 'column') {
+                this.columnChart.updatePointPadding(this.config, currentChart, this.useStackedLayout);
+                this.commonChartOptions.hideDataLabels(currentChart);
+            }
+            currentChart.redraw(false);
+        };
+    };
+
+    // Set resize events - throttled to 100ms
+    setWindowResizeEvent = () => {
+        if (this.chartType === 'column' || this.chartType === 'bar') {
+            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);
+                    }
+                }, 100);
+            });
+        }
+    };
+}
+
+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) => {
+        const numberOfCategories = config.xAxis.categories.length;
+        const numberOfSeries = currentChart.series.length; // Get number of bar 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;

package/components/chart/common-chart-options.js

@@ -0,0 +1,200 @@
+import ChartConstants from './chart-constants';
+
+// Options that are common to all chart types - these are set once in the Highcharts.setOptions() method
+class CommonChartOptions {
+    constructor() {
+        this.constants = ChartConstants.constants();
+
+        this.options = {
+            chart: {
+                backgroundColor: 'transparent',
+                style: {
+                    fontFamily: '"OpenSans", "Helvetica Neue", arial, sans-serif',
+                    color: '#222222',
+                },
+            },
+            legend: {
+                align: 'left',
+                verticalAlign: 'top',
+                layout: 'horizontal',
+                // Symbol width and height in the legend. May be overridden for individual chart types
+                symbolWidth: 12,
+                symbolHeight: 12,
+                margin: 50,
+                itemHoverStyle: {
+                    color: this.constants.labelColor, // Prevents the text from changing color on hover
+                },
+                itemStyle: {
+                    cursor: 'default', // ensures that it does not change to a hand (pointer) on hover.
+                    color: this.constants.labelColor,
+                    fontSize: this.constants.desktopFontSize,
+                    fontWeight: 'normal',
+                },
+                // Disable click event on legend
+                // There is currently an issue because the legend items are still buttons
+                // and therefore the screen reader still announces that they can be clicked
+                events: {
+                    itemClick: () => {
+                        return false;
+                    },
+                },
+                accessibility: {
+                    keyboardNavigation: {
+                        enabled: false, // Prevents focus on legend items while keeping screen reader support
+                    },
+                },
+            },
+            // Remove the chart title as rendered by Highcharts, as this is rendered in the surrounding component
+            title: {
+                text: '',
+            },
+            credits: {
+                // Remove Highcharts watermark
+                enabled: false,
+            },
+            accessibility: {
+                enabled: true,
+            },
+            yAxis: {
+                labels: {
+                    style: {
+                        color: this.constants.axisLabelColor,
+                        fontSize: this.constants.desktopFontSize,
+                    },
+                },
+                title: {
+                    text: '', // Remove the default title rendered by Highcharts if not provided
+                    align: 'high',
+                    textAlign: 'middle',
+                    reserveSpace: false,
+                    useHTML: true,
+                    offset: 15,
+                    rotation: 0,
+                    y: -25,
+                    style: {
+                        color: this.constants.axisLabelColor,
+                        fontSize: this.constants.desktopFontSize,
+                    },
+                },
+                lineColor: this.constants.gridLineColor,
+                gridLineColor: this.constants.gridLineColor,
+                // Add zero line
+                plotLines: [
+                    {
+                        color: this.constants.zeroLineColor,
+                        width: 1,
+                        value: 0,
+                        zIndex: 2,
+                    },
+                ],
+                // Add tick marks
+                tickWidth: 1,
+                tickLength: 6,
+                tickColor: this.constants.gridLineColor,
+            },
+            xAxis: {
+                labels: {
+                    style: {
+                        color: this.constants.axisLabelColor,
+                        fontSize: this.constants.desktopFontSize,
+                    },
+                },
+                title: {
+                    align: 'high',
+                    style: {
+                        color: this.constants.axisLabelColor,
+                        fontSize: this.constants.desktopFontSize,
+                    },
+                },
+                lineColor: this.constants.gridLineColor,
+                gridLineColor: this.constants.gridLineColor,
+                // Add tick marks
+                tickWidth: 1,
+                tickLength: 6,
+                tickColor: this.constants.gridLineColor,
+            },
+            plotOptions: {
+                series: {
+                    // disables the tooltip on hover
+                    enableMouseTracking: false,
+                    animation: false,
+
+                    // disables the legend item hover
+                    states: {
+                        inactive: {
+                            opacity: 1, // Prevent dimming of other series
+                            enabled: false,
+                        },
+                        hover: {
+                            enabled: false, // Disable the hover effect
+                        },
+                    },
+                },
+            },
+            // Adjust font size for smaller width of chart
+            // Note this is not the same as the viewport width
+            responsive: {
+                rules: [
+                    {
+                        condition: {
+                            maxWidth: 400,
+                        },
+                        chartOptions: {
+                            legend: {
+                                itemStyle: {
+                                    fontSize: this.constants.mobileFontSize,
+                                },
+                            },
+                            xAxis: {
+                                labels: {
+                                    style: {
+                                        fontSize: this.constants.mobileFontSize,
+                                    },
+                                },
+                                title: {
+                                    style: {
+                                        fontSize: this.constants.mobileFontSize,
+                                    },
+                                },
+                            },
+                            yAxis: {
+                                labels: {
+                                    style: {
+                                        fontSize: this.constants.mobileFontSize,
+                                    },
+                                },
+                                title: {
+                                    style: {
+                                        fontSize: this.constants.mobileFontSize,
+                                    },
+                                },
+                            },
+                        },
+                    },
+                ],
+            },
+        };
+    }
+
+    getOptions = () => this.options;
+
+    hideDataLabels = (currentChart) => {
+        currentChart.series.forEach((series) => {
+            series.update({
+                dataLabels: {
+                    enabled: false,
+                },
+            });
+        });
+    };
+
+    disableLegendForSingleSeries = (currentChart) => {
+        if (currentChart.series.length === 1) {
+            currentChart.legend.update({
+                enabled: false,
+            });
+        }
+    };
+}
+
+export default CommonChartOptions;

package/components/chart/example-bar-chart.njk

@@ -0,0 +1,54 @@
+{% from "components/chart/_macro.njk" import onsChart %}
+
+{{
+    onsChart({
+        "chartType": "bar",
+        "description": "Volume sales, seasonally adjusted, Great Britain, January 2022 to January 2025",
+        "theme": "primary",
+        "title": "Food stores showed a strong rise on the month, while non-food stores fell",
+        "subtitle": "Figure 6: Upward contribution from housing and household services (including energy) saw the annual CPIH inflation rate rise",
+        "id": "uuid",
+        "caption": "Source: Monthly Business Survey, Retail Sales Inquiry from the Office for National Statistics",
+        "download": {
+            'title': 'Download Figure 1 data',
+            'itemsList': [
+                {
+                    "text": "Excel spreadsheet (XLSX format, 18KB)",
+                    "url": "#"
+                },
+                {
+                    "text": "Simple text file (CSV format, 25KB)",
+                    "url": "#"
+                },
+                {
+                    "text": "Image (PNG format, 25KB)",
+                    "url": "#"
+                }
+            ]
+        },
+        "xAxis": {
+            "categories": [
+                "All retailing",
+                "All retailing excluding Automotive fuel",
+                "Food stores",
+                "Department stores",
+                "Other non-food stores",
+                "Textile clothing \u0026 footwear stores",
+                "Household goods stores",
+                "Non-store retailing",
+                "Automotive fuel"
+            ],
+            "type": "linear"
+        },
+        "yAxis": {
+            "title": "Percent (%)"
+        },
+        "series": [
+            {
+                "data": [1.7, 2.1, 5.6, 0, -0.6, -2.7, -1.7, 2.4, -1.2],
+                "dataLabels": true,
+                "name": "Jan-25"
+            }
+        ]
+    })
+}}

package/components/chart/example-clustered-bar-chart.njk

@@ -0,0 +1,60 @@
+{% from "components/chart/_macro.njk" import onsChart %}
+
+{{
+    onsChart({
+        "chartType": "bar",
+        "description": "Volume sales, seasonally adjusted, Great Britain, January 2022 to January 2025",
+        "theme": "primary",
+        "title": "Food stores showed a strong rise on the month, while non-food stores fell",
+        "subtitle": "Figure 6: Upward contribution from housing and household services (including energy) saw the annual CPIH inflation rate rise",
+        "id": "uuid",
+        "caption": "Source: Monthly Business Survey, Retail Sales Inquiry from the Office for National Statistics",
+        "download": {
+            'title': 'Download Figure 1 data',
+            'itemsList': [
+                {
+                    "text": "Excel spreadsheet (XLSX format, 18KB)",
+                    "url": "#"
+                },
+                {
+                    "text": "Simple text file (CSV format, 25KB)",
+                    "url": "#"
+                },
+                {
+                    "text": "Image (PNG format, 25KB)",
+                    "url": "#"
+                }
+            ]
+        },
+        "legend": true,
+        "series": [
+            {
+                "data": [-6.2, 1.5, -15.9, 1.7],
+                "dataLabels": false,
+                "name": "2022"
+            },
+            {
+                "data": [-2.9, -2.7, -2.9, -3.5],
+                "dataLabels": false,
+                "name": "2023"
+            },
+            {
+                "data": [-1.6, 1.2, 3.2, 3.8],
+                "dataLabels": false,
+                "name": "2024"
+            }
+        ],
+        "xAxis": {
+            "categories": [
+                "Food stores",
+                "Non-food stores",
+                "Non-store retailing ",
+                "Automotive fuel"
+            ],
+            "type": "linear"
+        },
+        "yAxis": {
+            "title": "Percent (%)"
+        }
+    })
+}}

package/components/chart/example-clustered-column-chart.njk

@@ -0,0 +1,72 @@
+{% from "components/chart/_macro.njk" import onsChart %}
+
+{{
+    onsChart({
+        "chartType": "column",
+        "description": "Volume sales, monthly percentage change, seasonally adjusted, Great Britain, October 2024",
+        "theme": "alternate",
+        "title": "Clothing stores fell back, following three months of growth",
+        "subtitle": "Volume sales, monthly percentage change, seasonally adjusted, Great Britain, October 2024",
+        "id": "uuid",
+        "caption": "Source: Monthly Business Survey, Retail Sales Inquiry from the Office for National Statistics",
+        "download": {
+            'title': 'Download Figure 1 data',
+            'itemsList': [
+                {
+                    "text": "Excel spreadsheet (XLSX format, 18KB)",
+                    "url": "#"
+                },
+                {
+                    "text": "Simple text file (CSV format, 25KB)",
+                    "url": "#"
+                },
+                {
+                    "text": "Image (PNG format, 25KB)",
+                    "url": "#"
+                }
+            ]
+        },
+        "legend": {
+            "enabled": true
+        },
+        "series": [
+            {
+                "data": [6.2, 1.5, 15.9, 1.7],
+                "dataLabels": false,
+                "name": "2022"
+            },
+            {
+                "data": [2.9, -2.7, 2.9, 3.5],
+                "dataLabels": false,
+                "name": "2023"
+            },
+            {
+                "data": [-1.6, 1.2, 3.2, 3.8],
+                "dataLabels": false,
+                "name": "2024"
+            },
+            {
+                "data": [3.0, 2, 5.6, 2.1],
+                "dataLabels": false,
+                "name": "2025"
+            },
+            {
+                "data": [2.0, 2, 3, 4],
+                "dataLabels": false,
+                "name": "2026"
+            }
+        ],
+        "xAxis": {
+            "categories": [
+                "Food stores",
+                "Non-food stores",
+                "Non-store retailing ",
+                "Automotive fuel"
+            ],
+            "type": "linear"
+        },
+        "yAxis": {
+            "title": "2022"
+        }
+    })
+}}

package/components/chart/example-column-chart.njk

@@ -0,0 +1,52 @@
+{% from "components/chart/_macro.njk" import onsChart %}
+
+{{
+    onsChart({
+        "chartType": "column",
+        "description": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
+        "theme": "primary",
+        "title": "Figure 6: Net debt as a percentage of GDP remains at levels last seen in the early 1960s",
+        "subtitle": "Public sector net debt excluding public sector banks, percentage of gross domestic product (GDP), UK, financial year ending (FYE) 1901 to October 2024",
+        "id": "uuid",
+        "caption": "Source: Public sector finances from the Office for Budget Responsibility (OBR) and the Office for National Statistics",
+        "download": {
+            'title': 'Download Figure 1 data',
+            'itemsList': [
+                {
+                    "text": "Excel spreadsheet (XLSX format, 18KB)",
+                    "url": "#"
+                },
+                {
+                    "text": "Simple text file (CSV format, 25KB)",
+                    "url": "#"
+                },
+                {
+                    "text": "Image (PNG format, 25KB)",
+                    "url": "#"
+                }
+            ]
+        },
+        "legend": false,
+        "series": [
+            {
+                "data": [
+                    37.8, 41.0, 43.0, 42.9, 41.8, 39.8, 37.9, 38.2, 37.6, 36.7,
+                    33.9, 31.8
+                ],
+                "dataLabels": false,
+                "name": "Public sector net debt as a % of GDP (PSND)"
+            }
+        ],
+        "xAxis": {
+            "categories": [
+                "Mar 1901", "Mar 1902", "Mar 1903", "Mar 1904", "Mar 1905", "Mar 1906", "Mar 1907", "Mar 1908", "Mar 1909", "Mar 1910",
+                "Mar 1911", "Mar 1912"
+            ],
+            "title":  "Years",
+            "type": "linear"
+        },
+        "yAxis": {
+            "title": "Percentage of GDP"
+        }
+    })
+}}