@ons/design-system 72.5.0 → 72.6.0

package/components/chart/chart.js

@@ -1,10 +1,13 @@
+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 Highcharts from 'highcharts';
-import 'highcharts/modules/accessibility';
+import AnnotationsOptions from './annotations-options';
 
 class HighchartsBaseChart {
     static selector() {
@@ -16,27 +19,38 @@ class HighchartsBaseChart {
         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();
@@ -99,6 +113,19 @@ class HighchartsBaseChart {
             // 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
@@ -107,50 +134,108 @@ class HighchartsBaseChart {
         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;
-            // Disable the legend for single series charts
-            this.commonChartOptions.disableLegendForSingleSeries(currentChart);
             if (this.chartType === 'line') {
-                this.lineChart.updateLastPointMarker(currentChart);
-                this.commonChartOptions.hideDataLabels(currentChart);
+                this.lineChart.updateLastPointMarker(currentChart.series);
+                this.commonChartOptions.hideDataLabels(currentChart.series);
             }
             if (this.chartType === 'bar') {
-                this.barChart.updateBarChartHeight(this.config, currentChart, this.useStackedLayout);
+                this.barChart.updateBarChartHeight(this.config, currentChart, this.useStackedLayout, this.extraLines);
                 if (!this.hideDataLabels) {
                     this.barChart.postLoadDataLabels(currentChart);
                 } else {
-                    this.commonChartOptions.hideDataLabels(currentChart);
+                    this.commonChartOptions.hideDataLabels(currentChart.series);
                 }
             }
             if (this.chartType === 'column') {
-                this.columnChart.updatePointPadding(this.config, currentChart, this.useStackedLayout);
-                this.commonChartOptions.hideDataLabels(currentChart);
+                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 100ms
+    // Set resize events - throttled to 50ms
+    // All resize events should be defined here to avoid overriding existing events
     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);
-            });
-        }
+        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);
+        });
     };
 }
 

package/components/chart/column-chart.js

@@ -18,9 +18,9 @@ class ColumnChart {
     // 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) => {
+    updatePointPadding = (config, currentChart, stackedLayout, numberOfExtraLines) => {
         const numberOfCategories = config.xAxis.categories.length;
-        const numberOfSeries = currentChart.series.length; // Get number of bar series
+        const numberOfSeries = currentChart.series.length - numberOfExtraLines; // Get number of column series
         let pointPadding = 0;
         let groupPadding = 0;
         // non-clustered charts or stacked charts

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

@@ -17,10 +17,15 @@ class CommonChartOptions {
                 align: 'left',
                 verticalAlign: 'top',
                 layout: 'horizontal',
-                // Symbol width and height in the legend. May be overridden for individual chart types
-                symbolWidth: 12,
-                symbolHeight: 12,
+                // Symbol width and height are set in a postLoad event, depending on the series type
+                // Default to the line width to ensure there is enough space for the overall legend item for line symbols
+                symbolWidth: 20,
                 margin: 50,
+                navigation: {
+                    // ensures that when the legend is long, there is no pagination or scrollbar
+                    enabled: false,
+                },
+                itemDistance: 30,
                 itemHoverStyle: {
                     color: this.constants.labelColor, // Prevents the text from changing color on hover
                 },
@@ -131,55 +136,47 @@ class CommonChartOptions {
                     },
                 },
             },
-            // 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) => {
+    getMobileOptions = () => {
+        return {
+            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,
+                    },
+                },
+            },
+        };
+    };
+
+    hideDataLabels = (series) => {
+        series.forEach((series) => {
             series.update({
                 dataLabels: {
                     enabled: false,
@@ -188,13 +185,63 @@ class CommonChartOptions {
         });
     };
 
-    disableLegendForSingleSeries = (currentChart) => {
-        if (currentChart.series.length === 1) {
-            currentChart.legend.update({
+    disableLegendForSingleSeries = (config) => {
+        if (config.series.length === 1) {
+            config.legend = {
                 enabled: false,
+            };
+            config.chart.marginTop = 50;
+        }
+    };
+
+    updateLegendSymbols = (chart) => {
+        if (chart.legend.options.enabled) {
+            chart.legend.allItems.forEach((item) => {
+                const { legendItem, userOptions } = item;
+                const seriesType = userOptions?.type;
+                // symbol is defined for bar / column series, and line is defined for line series
+                // if symbol is defined for a line series, it is the marker symbol
+                const { label, symbol } = legendItem || {};
+
+                if (seriesType === 'line') {
+                    symbol?.attr({
+                        x: 16, // Position the marker to the right of the line
+                    });
+
+                    label?.attr({
+                        x: 30, // Adjust label position to account for longer line
+                    });
+                } else {
+                    // Set the symbol size for bar / column series
+                    symbol.attr({
+                        width: 12,
+                        height: 12,
+                        y: 8,
+                    });
+                }
             });
         }
     };
+
+    adjustChartHeight = (currentChart, percentageHeightDesktop, percentageHeightMobile) => {
+        // get height and width of the plot area
+        const plotHeight = currentChart.plotHeight;
+        const plotWidth = currentChart.plotWidth;
+        // calculate the new plot height based on the percentage height
+        // default to the current height
+        let newPlotHeight = plotHeight;
+        if (plotWidth > 400) {
+            newPlotHeight = plotWidth * (percentageHeightDesktop / 100);
+        } else {
+            newPlotHeight = plotWidth * (percentageHeightMobile / 100);
+        }
+        const totalHeight = currentChart.plotTop + newPlotHeight + currentChart.marginBottom;
+
+        // set the new size of the chart
+        if (totalHeight !== currentChart.chartHeight) {
+            currentChart.setSize(null, totalHeight, false);
+        }
+    };
 }
 
 export default CommonChartOptions;

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

@@ -0,0 +1,62 @@
+{% 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"
+            }
+        ],
+        "annotations": [
+            {
+                "text": "A test annotation",
+                "point": {"x": 2, "y": 3},
+                "labelOffsetX": 40,
+                "labelOffsetY": -30
+            }
+        ]
+    })
+}}

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

@@ -38,6 +38,7 @@
                 "Non-store retailing",
                 "Automotive fuel"
             ],
+            "title": "Retailing",
             "type": "linear"
         },
         "yAxis": {

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

@@ -0,0 +1,64 @@
+{% 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,
+        "xAxis": {
+            "categories": ["One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine", "Ten"],
+            "type": "linear",
+            "title": "Categories"
+        },
+        "yAxis": {
+            "title": "Percent (%)"
+        },
+        "series": [
+            {
+                "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+                "dataLabels": true,
+                "name": "Values"
+            },
+            {
+                "data": [
+                    ["One", 6],
+                    ["Two", 4],
+                    ["Three", 5],
+                    ["Four", 7],
+                    ["Five", 2],
+                    ["Six", 9],
+                    ["Seven", 3],
+                    ["Eight", 8],
+                    ["Nine", 2],
+                    ["Ten", 1]
+                ],
+                "marker": true,
+                "dataLabels": false,
+                "name": "Another test data source",
+                "type": "line"
+            }
+        ]
+    })
+}}

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

@@ -67,6 +67,8 @@
         },
         "yAxis": {
             "title": "2022"
-        }
+        },
+        "percentageHeightDesktop": 35,
+        "percentageHeightMobile": 90
     })
 }}

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

@@ -0,0 +1,62 @@
+{% 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"
+        },
+        "percentageHeightDesktop": 35,
+        "percentageHeightMobile": 90,
+        "annotations": [
+            {
+                "text": "A test annotation",
+                "point": {"x": 11, "y": 31.8},
+                "labelOffsetX": 10,
+                "labelOffsetY": -50
+            }
+        ]
+    })
+}}

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

@@ -47,6 +47,8 @@
         },
         "yAxis": {
             "title": "Percentage of GDP"
-        }
+        },
+        "percentageHeightDesktop": 35,
+        "percentageHeightMobile": 90
     })
 }}