@ons/design-system 72.9.2 → 72.10.1

package/components/chart/chart.js

@@ -1,6 +1,7 @@
 import Highcharts from 'highcharts';
 import 'highcharts/modules/accessibility';
 import 'highcharts/modules/annotations';
+import 'highcharts/highcharts-more';
 
 import CommonChartOptions from './common-chart-options';
 import SpecificChartOptions from './specific-chart-options';
@@ -8,8 +9,13 @@ import LineChart from './line-chart';
 import BarChart from './bar-chart';
 import ColumnChart from './column-chart';
 import ScatterChart from './scatter-chart';
+import Boxplot from './boxplot';
 import AnnotationsOptions from './annotations-options';
+import RangeAnnotationsOptions from './range-annotations-options';
+import ReferenceLineAnnotationsOptions from './reference-line-annotations-options';
+import { preparePlotLinesAndBands, mergeConfigs } from './utilities';
 import AreaChart from './area-chart';
+import ColumnRangeChart from './columnrange-chart';
 
 class HighchartsBaseChart {
     static selector() {
@@ -29,8 +35,18 @@ class HighchartsBaseChart {
         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.annotations = JSON.parse(this.node.querySelector(`[data-highcharts-annotations--${this.id}]`).textContent);
+            this.annotationsOptions = new AnnotationsOptions(this.annotations);
+        }
+        if (this.node.querySelector(`[data-highcharts-range-annotations--${this.id}]`)) {
+            this.rangeAnnotations = JSON.parse(this.node.querySelector(`[data-highcharts-range-annotations--${this.id}]`).textContent);
+            this.rangeAnnotationsOptions = new RangeAnnotationsOptions(this.rangeAnnotations);
+        }
+        if (this.node.querySelector(`[data-highcharts-reference-line-annotations--${this.id}]`)) {
+            this.referenceLineAnnotations = JSON.parse(
+                this.node.querySelector(`[data-highcharts-reference-line-annotations--${this.id}]`).textContent,
+            );
+            this.referenceLineAnnotationsOptions = new ReferenceLineAnnotationsOptions(this.referenceLineAnnotations);
         }
         this.percentageHeightDesktop = this.node.dataset.highchartsPercentageHeightDesktop;
         this.percentageHeightMobile = this.node.dataset.highchartsPercentageHeightMobile;
@@ -47,13 +63,22 @@ class HighchartsBaseChart {
             ? parseInt(this.node.dataset.highchartsYAxisTickIntervalDesktop)
             : undefined;
         this.commonChartOptions = new CommonChartOptions(this.xAxisTickIntervalDesktop, this.yAxisTickIntervalDesktop);
+        this.estimateLineLabel = this.node.dataset.highchartsEstimateLineLabel;
+        this.uncertainyRangeLabel = this.node.dataset.highchartsUncertaintyRangeLabel;
+        this.customReferenceLineValue = this.node.dataset.highchartsCustomReferenceLineValue
+            ? parseFloat(this.node.dataset.highchartsCustomReferenceLineValue)
+            : undefined;
+
         this.specificChartOptions = new SpecificChartOptions(this.theme, this.chartType, this.config);
         this.lineChart = new LineChart();
         this.barChart = new BarChart();
         this.columnChart = new ColumnChart();
         this.areaChart = new AreaChart();
         this.scatterChart = new ScatterChart();
+        this.columnRangeChart = new ColumnRangeChart();
+        this.boxplot = new Boxplot();
         this.extraLines = this.checkForExtraLines();
+        this.extraScatter = this.checkForExtraScatter();
         if (window.isCommonChartOptionsDefined === undefined) {
             this.setCommonChartOptions();
             window.isCommonChartOptionsDefined = true;
@@ -62,6 +87,7 @@ class HighchartsBaseChart {
         this.setSpecificChartOptions();
         this.setResponsiveOptions();
         this.setLoadEvent();
+        this.setRenderEvent();
         this.setWindowResizeEvent();
         this.chart = Highcharts.chart(chartNode, this.config);
     }
@@ -71,83 +97,80 @@ class HighchartsBaseChart {
         return this.chartType === 'line' ? 0 : this.config.series.filter((series) => series.type === 'line').length;
     };
 
+    // Used to ensure that extra line series always overlay the column series
+    updateExtraLineZIndex = () => {
+        this.config.series.forEach((series) => {
+            if (series.type === 'line') {
+                series.zIndex = this.config.series.length + 1;
+            }
+        });
+    };
+
+    // Check for the number of extra line series in the config
+    checkForExtraScatter = () => {
+        return this.chartType === 'scatter' ? 0 : this.config.series.filter((series) => series.type === 'scatter').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 columnRangeChartOptions = this.columnRangeChart.getColumnRangeChartOptions();
         const columnChartOptions = this.columnChart.getColumnChartOptions(this.config, this.useStackedLayout, this.extraLines);
         const areaChartOptions = this.areaChart.getAreaChartOptions();
         const scatterChartOptions = this.scatterChart.getScatterChartOptions();
+        const boxplotOptions = this.boxplot.getBoxplotOptions(this.config, this.useStackedLayout, this.extraLines);
         // Merge specificChartOptions with the existing config
-        this.config = this.mergeConfigs(this.config, specificChartOptions);
+        this.config = mergeConfigs(this.config, specificChartOptions);
 
         if (this.chartType === 'line') {
             // Merge the line chart options with the existing config
-            this.config = this.mergeConfigs(this.config, lineChartOptions);
+            this.config = mergeConfigs(this.config, lineChartOptions);
         }
 
         if (this.chartType === 'bar') {
             // Merge the bar chart options with the existing config
-            this.config = this.mergeConfigs(this.config, barChartOptions);
+            this.config = mergeConfigs(this.config, barChartOptions);
+        }
+        if (this.chartType === 'columnrange') {
+            // Merge the bar chart options with the existing config
+            this.config = mergeConfigs(this.config, columnRangeChartOptions);
         }
         if (this.chartType === 'column') {
             // Merge the column chart options with the existing config
-            this.config = this.mergeConfigs(this.config, columnChartOptions);
+            this.config = mergeConfigs(this.config, columnChartOptions);
         }
         if (this.chartType === 'area') {
             // Merge the area chart options with the existing config
-            this.config = this.mergeConfigs(this.config, areaChartOptions);
+            this.config = mergeConfigs(this.config, areaChartOptions);
         }
         if (this.chartType === 'scatter') {
             // Merge the scatter chart options with the existing config
-            this.config = this.mergeConfigs(this.config, scatterChartOptions);
+            this.config = mergeConfigs(this.config, scatterChartOptions);
+        }
+        if (this.chartType === 'boxplot') {
+            // Merge the boxplot chart options with the existing config
+            this.config = mergeConfigs(this.config, boxplotOptions);
         }
 
         if (this.extraLines > 0) {
-            this.config = this.mergeConfigs(this.config, this.lineChart.getLineChartOptions());
+            this.updateExtraLineZIndex();
+            this.config = mergeConfigs(this.config, this.lineChart.getLineChartOptions());
+            this.config = mergeConfigs(this.config, this.lineChart.getExtraLineChartOptions(this.config.series.length + 1));
             if (this.chartType === 'column') {
-                this.config = this.mergeConfigs(this.config, columnChartOptions);
+                this.config = mergeConfigs(this.config, columnChartOptions);
+            }
+        }
+        if (this.extraScatter > 0) {
+            if (this.chartType === 'columnrange') {
+                this.config = mergeConfigs(this.config, columnRangeChartOptions);
             }
         }
 
@@ -166,19 +189,29 @@ class HighchartsBaseChart {
     // All responsive rules should be defined here to avoid overriding existing rules
     setResponsiveOptions = () => {
         let mobileChartOptions = this.commonChartOptions.getMobileOptions(this.xAxisTickIntervalMobile, this.yAxisTickIntervalMobile);
-        if (this.chartType === 'column') {
+        if (this.chartType === 'column' || this.chartType === 'boxplot') {
             const mobileColumnChartOptions = this.columnChart.getColumnChartMobileOptions(
                 this.config,
                 this.useStackedLayout,
                 this.extraLines,
             );
-            mobileChartOptions = this.mergeConfigs(mobileChartOptions, mobileColumnChartOptions);
+            mobileChartOptions = mergeConfigs(mobileChartOptions, mobileColumnChartOptions);
         }
 
         if (!this.config.responsive) {
             this.config.responsive = {};
         }
 
+        const { desktopAllPlotLinesAndBands, mobileAllPlotLinesAndBands } = preparePlotLinesAndBands(
+            this.annotations,
+            this.rangeAnnotations,
+            this.rangeAnnotationsOptions,
+            this.referenceLineAnnotationsOptions,
+            this.specificChartOptions,
+            this.chartType,
+            this.customReferenceLineValue,
+        );
+
         let rules = [
             {
                 condition: {
@@ -198,6 +231,7 @@ class HighchartsBaseChart {
                 },
                 chartOptions: {
                     annotations: this.annotationsOptions ? this.annotationsOptions.getAnnotationsOptionsMobile() : undefined,
+                    ...(mobileAllPlotLinesAndBands != {} ? mobileAllPlotLinesAndBands : null),
                 },
             },
             {
@@ -206,6 +240,7 @@ class HighchartsBaseChart {
                 },
                 chartOptions: {
                     annotations: this.annotationsOptions ? this.annotationsOptions.getAnnotationsOptionsDesktop() : undefined,
+                    ...(desktopAllPlotLinesAndBands != {} ? desktopAllPlotLinesAndBands : null),
                 },
             },
         ];
@@ -238,6 +273,15 @@ class HighchartsBaseChart {
             if (this.chartType === 'scatter') {
                 this.scatterChart.updateMarkers(currentChart);
             }
+            if (this.chartType === 'columnrange') {
+                this.columnRangeChart.updateColumnRangeChartHeight(this.config, currentChart);
+                this.commonChartOptions.hideDataLabels(currentChart.series);
+
+                if (this.extraScatter > 0) {
+                    const scatterSeries = currentChart.series.filter((series) => series.type === 'scatter');
+                    this.scatterChart.updateMarkersForConfidenceLevels(scatterSeries);
+                }
+            }
             if (this.chartType != 'bar') {
                 this.commonChartOptions.adjustChartHeight(currentChart, this.percentageHeightDesktop, this.percentageHeightMobile);
             }
@@ -257,6 +301,18 @@ class HighchartsBaseChart {
         };
     };
 
+    setRenderEvent = () => {
+        if (!this.config.chart.events) {
+            this.config.chart.events = {};
+        }
+        this.config.chart.events.render = (event) => {
+            const currentChart = event.target;
+            if (this.rangeAnnotationsOptions) {
+                this.rangeAnnotationsOptions.addLine(currentChart);
+            }
+        };
+    };
+
     // Set resize events - throttled to 50ms
     // All resize events should be defined here to avoid overriding existing events
     setWindowResizeEvent = () => {

package/components/chart/columnrange-chart.js

@@ -0,0 +1,94 @@
+import ChartConstants from './chart-constants';
+
+class ColumnRangeChart {
+    constructor() {
+        this.constants = ChartConstants.constants();
+    }
+
+    getColumnRangeChartOptions = () => {
+        return {
+            plotOptions: {
+                columnrange: {
+                    color: this.constants.uncertaintyRangeColor, // Set the default color for the column range
+                    pointWidth: 20, // Fixed bar height
+                    pointPadding: 0,
+                    groupPadding: 0,
+                    borderWidth: 0,
+                    borderRadius: 0,
+                    dataLabels: {
+                        enabled: false,
+                    },
+                },
+            },
+            xAxis: {
+                // Update the category label colours for bar charts
+                labels: {
+                    style: {
+                        color: this.constants.categoryLabelColor,
+                    },
+                    useHTML: false,
+                },
+                // remove the tick marks for bar charts
+                tickWidth: 0,
+                tickLength: 0,
+                gridlineWidth: 0,
+                tickColor: 'transparent',
+                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,
+                    },
+                },
+                tickLength: 0,
+                tickWidth: 0,
+                tickColor: 'transparent',
+                gridlineWidth: 0,
+                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,
+                },
+            },
+            legend: {
+                symbolRadius: 0,
+                itemStyle: {
+                    fontSize: this.constants.defaultFontSize,
+                    color: this.constants.legendLabelColor,
+                },
+            },
+        };
+    };
+
+    // 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
+    updateColumnRangeChartHeight = (config, currentChart) => {
+        const numberOfCategories = config.xAxis.categories.length;
+        let barHeight = 20; // 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;
+
+        groupSpacing = 14;
+        categoriesTotalHeight = numberOfCategories * barHeight;
+
+        totalSpaceHeight = numberOfCategories * 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 ColumnRangeChart;

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

@@ -81,15 +81,6 @@ class CommonChartOptions {
                 },
                 lineColor: this.constants.gridLineColor,
                 gridLineColor: this.constants.gridLineColor,
-                // Add zero line
-                plotLines: [
-                    {
-                        color: this.constants.zeroLineColor,
-                        width: 1.5,
-                        value: 0,
-                        zIndex: 2,
-                    },
-                ],
                 // Add tick marks
                 tickWidth: 1,
                 tickLength: 6,
@@ -122,8 +113,6 @@ class CommonChartOptions {
             },
             plotOptions: {
                 series: {
-                    // disables the tooltip on hover
-                    enableMouseTracking: false,
                     animation: false,
 
                     // disables the legend item hover
@@ -138,6 +127,9 @@ class CommonChartOptions {
                     },
                 },
             },
+            tooltip: {
+                animation: false,
+            },
         };
     }
 
@@ -145,6 +137,9 @@ class CommonChartOptions {
 
     getMobileOptions = (xAxisTickInterval, yAxisTickInterval) => {
         return {
+            tooltip: {
+                enabled: false,
+            },
             xAxis: {
                 tickInterval: xAxisTickInterval,
             },
@@ -165,7 +160,7 @@ class CommonChartOptions {
     };
 
     disableLegendForSingleSeries = (config) => {
-        if (config.series.length === 1) {
+        if (config.chart.type != 'boxplot' && config.series.length === 1) {
             config.legend = {
                 enabled: false,
             };
@@ -175,24 +170,71 @@ class CommonChartOptions {
 
     updateLegendSymbols = (chart) => {
         if (chart.legend.options.enabled) {
-            chart.legend.allItems.forEach((item) => {
+            chart.legend.allItems.forEach((item, index) => {
                 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 || {};
+                const { label, symbol, line } = legendItem || {};
 
                 if (seriesType === 'line') {
-                    label?.attr({
-                        x: 30, // Adjust label position to account for longer line
-                    });
-                } else {
-                    // Set the symbol size for bar / column series
+                    // This is the case for the column plus line chart - the series type is
+                    // line, but the chart type is column. In this case we show a simple
+                    // line symbol in the legend, but we need to move the label to the right
+                    // to account for the longer line symbol
+                    if (chart.userOptions.chart.type !== 'line') {
+                        label?.attr({
+                            x: 30, // Adjust label position to account for longer line
+                        });
+                    }
+
+                    // This is the scenario for a line chart with markers disabled
+                    // We have custom code in line-chart.js to update the last point to
+                    // display as a symbol. This code checks if there is no symbol in the legend
+                    // (which means it is a line chart with markers disabled)
+                    // and if so, it updates the legend to display as a symbol rather than as a line
+                    // We only to this for chart types that are explicitly line charts - i.e. not column with line
+                    if (!symbol && label && label.element && chart.userOptions.chart.type === 'line') {
+                        // Hide the line in the legend
+                        if (line) {
+                            line.hide();
+                        }
+
+                        // Create a custom symbol for the legend using the line marker symbol options
+                        const renderer = chart.renderer;
+                        const bbox = label.element.getBBox();
+                        const markerStyle = this.constants.lineMarkerStyles[index % this.constants.lineMarkerStyles.length];
+
+                        const legendSymbol = renderer
+                            .symbol(markerStyle.symbol, bbox.x - 30, bbox.y + 4, 12, markerStyle.radius, markerStyle.radius)
+                            .attr({
+                                fill: item.color,
+                                stroke: item.color,
+                                'stroke-width': 1,
+                                width: 12,
+                                height: 12,
+                            });
+
+                        legendSymbol.add(label.parentGroup);
+                        label?.attr({
+                            x: 15, // Adjust label position to account for shorter space that the symbol takes up
+                        });
+                    }
+                } else if (seriesType === 'columnrange') {
                     symbol.attr({
-                        width: 12,
-                        height: 12,
+                        width: 14,
+                        height: 14,
                         y: 8,
                     });
+                } else {
+                    if (!symbol) return;
+                    // Update the symbol width and height
+                    // For column, bar and other chart types
+                    else {
+                        symbol.attr({
+                            width: 12,
+                            height: 12,
+                            y: 8,
+                        });
+                    }
                 }
             });
         }

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

@@ -52,7 +52,7 @@
         ],
         "annotations": [
             {
-                "text": "A test annotation",
+                "text": "A test point annotation",
                 "point": {"x": 2, "y": 3},
                 "labelOffsetX": 40,
                 "labelOffsetY": -30

package/components/chart/example-bar-chart-with-point-range-and-reference-line-annotations.njk

@@ -0,0 +1,95 @@
+{% 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": false,
+                "name": "Jan-25"
+            }
+        ],
+        "annotations": [
+            {
+                "text": "A test point annotation",
+                "point": {"x": 2, "y": 3},
+                "labelOffsetX": 40,
+                "labelOffsetY": -30
+            }
+        ],
+        "rangeAnnotations": [
+            {
+                "text": "A test x axis range annotation",
+                "range": {"axisValue1": 1, "axisValue2": 2},
+                "axis": "x",
+                "labelOffsetX": 10,
+                "labelOffsetY": -60
+            },
+            {
+                "text": "A test y axis range annotation with a width of 80px",
+                "range": {"axisValue1": 5, "axisValue2": 6},
+                "axis": "y",
+                "labelOffsetX": -80,
+                "labelOffsetY": 220,
+                "labelWidth": 80
+            }
+        ],
+        "referenceLineAnnotations": [
+            {
+                "text": "A test x axis reference line annotation",
+                "value": 8,
+                "axis": "x",
+                "labelOffsetY": -30
+            },
+            {
+                "text": "A test y axis reference line annotation",
+                "value": 1.5,
+                "axis": "y",
+                "labelWidth": 100,
+                "labelOffsetX": 10,
+                "labelOffsetY": 140
+            }
+        ]
+    })
+}}