@ons/design-system 72.5.0 → 72.8.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

@@ -40,6 +40,7 @@ class BarChart {
                     style: {
                         color: this.constants.categoryLabelColor,
                     },
+                    useHTML: false,
                 },
                 // remove the tick marks for bar charts
                 tickWidth: 0,
@@ -48,6 +49,14 @@ class BarChart {
                 title: { align: 'high', textAlign: 'middle', reserveSpace: false, rotation: 0, y: -25, useHTML: true },
             },
             yAxis: {
+                labels: {
+                    rotation: 0,
+                    useHTML: true,
+                    style: {
+                        whiteSpace: 'nowrap',
+                        color: this.constants.categoryLabelColor,
+                    },
+                },
                 title: {
                     // Override the y Axis title settings for bar charts where the y axis is horizontal
                     textAlign: 'right',
@@ -76,6 +85,10 @@ class BarChart {
                 // 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 {
@@ -112,9 +125,9 @@ class BarChart {
 
     // 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) => {
+    updateBarChartHeight = (config, currentChart, useStackedLayout, 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 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;

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,42 @@ 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);
-
-        this.commonChartOptions = new CommonChartOptions();
+        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.xAxisTickIntervalMobile = parseInt(this.node.dataset.highchartsXAxisTickIntervalMobile);
+        this.xAxisTickIntervalDesktop = parseInt(this.node.dataset.highchartsXAxisTickIntervalDesktop);
+        this.yAxisTickIntervalMobile = parseInt(this.node.dataset.highchartsYAxisTickIntervalMobile);
+        this.yAxisTickIntervalDesktop = parseInt(this.node.dataset.highchartsYAxisTickIntervalDesktop);
+        this.commonChartOptions = new CommonChartOptions(this.xAxisTickIntervalDesktop, this.yAxisTickIntervalDesktop);
         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 +117,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 +138,111 @@ 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(
+            this.xAxisTickIntervalMobile,
+            this.yAxisTickIntervalMobile,
+        );
+        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

@@ -2,7 +2,7 @@ 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() {
+    constructor(xAxisTickInterval, yAxisTickInterval) {
         this.constants = ChartConstants.constants();
 
         this.options = {
@@ -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
                 },
@@ -91,9 +96,12 @@ class CommonChartOptions {
                 tickWidth: 1,
                 tickLength: 6,
                 tickColor: this.constants.gridLineColor,
+                tickInterval: yAxisTickInterval,
             },
             xAxis: {
                 labels: {
+                    useHTML: true,
+                    rotation: 0,
                     style: {
                         color: this.constants.axisLabelColor,
                         fontSize: this.constants.desktopFontSize,
@@ -112,6 +120,7 @@ class CommonChartOptions {
                 tickWidth: 1,
                 tickLength: 6,
                 tickColor: this.constants.gridLineColor,
+                tickInterval: xAxisTickInterval,
             },
             plotOptions: {
                 series: {
@@ -131,55 +140,49 @@ 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 = (xAxisTickInterval, yAxisTickInterval) => {
+        return {
+            legend: {
+                itemStyle: {
+                    fontSize: this.constants.mobileFontSize,
+                },
+            },
+            xAxis: {
+                labels: {
+                    style: {
+                        fontSize: this.constants.mobileFontSize,
+                    },
+                },
+                title: {
+                    style: {
+                        fontSize: this.constants.mobileFontSize,
+                    },
+                },
+                tickInterval: xAxisTickInterval,
+            },
+            yAxis: {
+                labels: {
+                    style: {
+                        fontSize: this.constants.mobileFontSize,
+                    },
+                },
+                title: {
+                    style: {
+                        fontSize: this.constants.mobileFontSize,
+                    },
+                },
+                tickInterval: yAxisTickInterval,
+            },
+        };
+    };
+
+    hideDataLabels = (series) => {
+        series.forEach((series) => {
             series.update({
                 dataLabels: {
                     enabled: false,
@@ -188,13 +191,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": {