@ons/design-system 72.9.1 → 72.10.0

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,23 +35,46 @@ 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;
-        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.xAxisTickIntervalMobile = this.node.dataset.highchartsXAxisTickIntervalMobile
+            ? parseInt(this.node.dataset.highchartsXAxisTickIntervalMobile)
+            : undefined;
+        this.xAxisTickIntervalDesktop = this.node.dataset.highchartsXAxisTickIntervalDesktop
+            ? parseInt(this.node.dataset.highchartsXAxisTickIntervalDesktop)
+            : undefined;
+        this.yAxisTickIntervalMobile = this.node.dataset.highchartsYAxisTickIntervalMobile
+            ? parseInt(this.node.dataset.highchartsYAxisTickIntervalMobile)
+            : undefined;
+        this.yAxisTickIntervalDesktop = this.node.dataset.highchartsYAxisTickIntervalDesktop
+            ? 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.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;
@@ -54,6 +83,7 @@ class HighchartsBaseChart {
         this.setSpecificChartOptions();
         this.setResponsiveOptions();
         this.setLoadEvent();
+        this.setRenderEvent();
         this.setWindowResizeEvent();
         this.chart = Highcharts.chart(chartNode, this.config);
     }
@@ -63,83 +93,69 @@ class HighchartsBaseChart {
         return this.chartType === 'line' ? 0 : this.config.series.filter((series) => series.type === 'line').length;
     };
 
+    // 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.config = mergeConfigs(this.config, this.lineChart.getLineChartOptions());
             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);
             }
         }
 
@@ -158,19 +174,28 @@ 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.commonChartOptions,
+            this.chartType,
+        );
+
         let rules = [
             {
                 condition: {
@@ -190,6 +215,7 @@ class HighchartsBaseChart {
                 },
                 chartOptions: {
                     annotations: this.annotationsOptions ? this.annotationsOptions.getAnnotationsOptionsMobile() : undefined,
+                    ...(mobileAllPlotLinesAndBands != {} ? mobileAllPlotLinesAndBands : null),
                 },
             },
             {
@@ -198,6 +224,7 @@ class HighchartsBaseChart {
                 },
                 chartOptions: {
                     annotations: this.annotationsOptions ? this.annotationsOptions.getAnnotationsOptionsDesktop() : undefined,
+                    ...(desktopAllPlotLinesAndBands != {} ? desktopAllPlotLinesAndBands : null),
                 },
             },
         ];
@@ -230,6 +257,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);
             }
@@ -249,6 +285,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,
@@ -143,6 +134,25 @@ class CommonChartOptions {
 
     getOptions = () => this.options;
 
+    // TODO: A future ticket will add support for other plot lines which are not
+    // reference line annotations, and will be styled like the zero line
+    // See ticket https://jira.ons.gov.uk/browse/CCB-63
+    getPlotLines = () => {
+        // Add zero line
+        return {
+            yAxis: {
+                plotLines: [
+                    {
+                        color: this.constants.zeroLineColor,
+                        width: 1.5,
+                        value: 0,
+                        zIndex: 2,
+                    },
+                ],
+            },
+        };
+    };
+
     getMobileOptions = (xAxisTickInterval, yAxisTickInterval) => {
         return {
             xAxis: {
@@ -165,7 +175,7 @@ class CommonChartOptions {
     };
 
     disableLegendForSingleSeries = (config) => {
-        if (config.series.length === 1) {
+        if (config.chart.type != 'boxplot' && config.series.length === 1) {
             config.legend = {
                 enabled: false,
             };
@@ -183,20 +193,19 @@ class CommonChartOptions {
                 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 {
+                    if (!symbol) return;
                     // Set the symbol size for bar / column series
-                    symbol.attr({
-                        width: 12,
-                        height: 12,
-                        y: 8,
-                    });
+                    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
+            }
+        ]
+    })
+}}

package/components/chart/example-bar-with-confidence-levels.njk

@@ -0,0 +1,71 @@
+{% from "components/chart/_macro.njk" import onsChart %}
+
+{{
+    onsChart({
+        "chartType": "columnrange",
+        "isChartInverted": true,
+        "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": [
+                'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+                'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
+            ],
+            "type": "linear",
+            "title": "Categories"
+        },
+        "yAxis": {
+            "title": "Temperature ( °C )"
+        },
+        "series": [
+            {
+                "data": [
+                    [-9.5, 8.0],
+                    [-7.8, 8.3],
+                    [-13.1, 9.2],
+                    [-4.4, 15.7],
+                    [-1.0, 20.8],
+                    [3.1, 28.4],
+                    [5.9, 27.0],
+                    [4.6, 23.0],
+                    [4.9, 19.3],
+                    [-5.2, 11.6],
+                    [],
+                    [-10.5, 12.0],
+                    [-12.1, 18.5]
+                ],
+                "dataLabels": true,
+                "name": "Values"
+            },
+            {
+                "data": [1,2,3,4,5,6,7,8,9,10,3,11,12],
+                "marker": true,
+                "dataLabels": false,
+                "name": "Another test data source",
+                "type": "scatter"
+            }
+        ]
+    })
+}}

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

@@ -26,9 +26,7 @@
                 }
             ]
         },
-        "legend": {
-            "enabled": true
-        },
+        "legend": true,
         "series": [
             {
                 "data": [6.2, 1.5, 15.9, 1.7],

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

@@ -53,7 +53,7 @@
         "percentageHeightMobile": 90,
         "annotations": [
             {
-                "text": "A test annotation",
+                "text": "A test point annotation",
                 "point": {"x": 11, "y": 31.8},
                 "labelOffsetX": 10,
                 "labelOffsetY": -50