@automattic/charts 4.1.1 → 4.3.0

package/src/charts/heatmap-chart/heatmap-chart.tsx

@@ -1,9 +1,10 @@
 import { formatNumber, formatNumberCompact } from '@automattic/number-formatters';
-import { useTooltip } from '@visx/tooltip';
+import { defaultStyles as visxTooltipStyles, useTooltip } from '@visx/tooltip';
 import { __ } from '@wordpress/i18n';
 import clsx from 'clsx';
 import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
-import { BoundedTooltip } from '../../components/tooltip/private/bounded-tooltip';
+import tooltipStyles from '../../components/tooltip/base-tooltip.module.scss';
+import { BoundedTooltip, TOOLTIP_Z_INDEX } from '../../components/tooltip/private/bounded-tooltip';
 import {
 	GlobalChartsProvider,
 	useChartId,
@@ -33,8 +34,17 @@ import {
 	HeatmapContext,
 	HeatmapLegend,
 	isPresent,
+	resolveColumnGroups,
 } from './private';
+import {
+	firstCalendarCell,
+	firstGridCell,
+	isNavigationKey,
+	stepCalendarCell,
+	stepGridCell,
+} from './private/keyboard-navigation';
 import type { HeatmapContextValue } from './private';
+import type { CellBlock, CellPosition } from './private/keyboard-navigation';
 import type { HeatmapChartProps, HeatmapTooltipData } from './types';
 import type { ResponsiveConfig } from '../private/with-responsive';
 import type { CSSProperties, FC } from 'react';
@@ -47,6 +57,17 @@ const CELL_MIX_FLOOR = 0.15;
 // it, and a fresh array per render re-ran the keyboard tooltip effect endlessly.
 const NO_ROW_LABELS: string[] = [];
 
+// The dark variant is painted by the `.surface` class, so its style carries no box.
+const TOOLTIP_BOX_STYLES: Record< 'light' | 'dark', CSSProperties > = {
+	light: { ...visxTooltipStyles, zIndex: TOOLTIP_Z_INDEX },
+	dark: { zIndex: TOOLTIP_Z_INDEX },
+};
+
+// The cell's own label wins; otherwise the group, column and row labels name it.
+const cellName = ( info: HeatmapTooltipData ) =>
+	info.cellLabel ||
+	[ info.groupLabel, info.columnLabel, info.rowLabel ].filter( Boolean ).join( ' ' );
+
 const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	data,
 	chartId: providedChartId,
@@ -60,19 +81,27 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	minCellWidth,
 	minCellHeight,
 	rowLabels = NO_ROW_LABELS,
+	columnGroups,
+	keyboardNavigation = 'grid',
+	ariaLabel,
 	primaryColor,
 	gap = 'md',
 	withTooltips = false,
 	renderTooltip,
+	tooltipVariant = 'light',
+	tooltipStyle,
 	children,
 } ) => {
 	const chartId = useChartId( providedChartId );
+	const tooltipBoxStyle = tooltipStyle
+		? { ...TOOLTIP_BOX_STYLES[ tooltipVariant ], ...tooltipStyle }
+		: TOOLTIP_BOX_STYLES[ tooltipVariant ];
 	const { getElementStyles, theme } = useGlobalChartsContext();
 	const scopeElement = useChartScopeElement();
 	const { heatmapChart: heatmapChartSettings } = theme;
 	const { nonLegendChildren } = useChartChildren( children, 'HeatmapChart' );
 
-	const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >();
+	const [ selected, setSelected ] = useState< CellPosition | undefined >();
 	const { tooltipOpen, tooltipLeft, tooltipTop, tooltipData, showTooltip, hideTooltip } =
 		useTooltip< HeatmapTooltipData >();
 	const standaloneScopeClass = useStandaloneScopeClass();
@@ -123,27 +152,34 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 
 	const columns = data.length;
 	const rows = Math.max( 0, ...data.map( column => column.data.length ) );
+	// Line 1 is the row-label track, so the data columns start on line 2.
+	const groupLayout = useMemo(
+		() => resolveColumnGroups( columnGroups, columns, 2 ),
+		[ columnGroups, columns ]
+	);
 
-	const { compactCellGap, compactCellSize } = heatmapChartSettings;
+	const { compactCellGap, compactCellSize, groupGap } = heatmapChartSettings;
 	const drawValues = showValues ?? ! compact;
 
 	const buildTooltipData = useCallback(
 		( columnIndex: number, rowIndex: number ): HeatmapTooltipData => {
 			const cell = data[ columnIndex ]?.data[ rowIndex ];
+			const group = groupLayout.columns[ columnIndex ]?.group;
 			return {
 				value: cell?.value ?? null,
 				rowLabel: rowLabels[ rowIndex ],
 				columnLabel: data[ columnIndex ]?.label,
+				groupLabel: group === undefined ? undefined : groupLayout.groups[ group ]?.label,
 				cellLabel: cell?.label,
 				row: rowIndex,
 				column: columnIndex,
 			};
 		},
-		[ data, rowLabels ]
+		[ data, rowLabels, groupLayout ]
 	);
 
 	const onChartBlur = useCallback( () => {
-		setSelectedIndex( undefined );
+		setSelected( undefined );
 		hideTooltip();
 	}, [ hideTooltip ] );
 
@@ -157,65 +193,49 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		[ data ]
 	);
 
+	// Calendar navigation reads each column group as a page; ungrouped columns
+	// (or the whole grid without groups) make a page of their own.
+	const blocks = useMemo< CellBlock[] >( () => {
+		const grouped = groupLayout.groups.map( ( group, index ) => {
+			const start = groupLayout.columns.findIndex( column => column.group === index );
+			return { start, end: start + group.span };
+		} );
+		const groupedEnd = grouped.length ? grouped[ grouped.length - 1 ].end : 0;
+		return groupedEnd < columns ? [ ...grouped, { start: groupedEnd, end: columns } ] : grouped;
+	}, [ groupLayout, columns ] );
+
 	const onChartKeyDown = useCallback(
 		( event: React.KeyboardEvent< HTMLDivElement > ) => {
-			if (
-				! [ 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Escape', 'Tab' ].includes(
-					event.key
-				)
-			) {
-				return;
-			}
-
 			if ( event.key === 'Tab' || event.key === 'Escape' ) {
-				setSelectedIndex( undefined );
+				setSelected( undefined );
 				hideTooltip();
 				return;
 			}
-
-			event.preventDefault();
-
-			if ( selectedIndex === undefined ) {
-				// Start at the first navigable cell (a calendar's leading edge
-				// slots may be hidden).
-				for ( let index = 0; index < columns * rows; index++ ) {
-					if ( ! isCellInert( Math.floor( index / rows ), index % rows ) ) {
-						setSelectedIndex( index );
-						return;
-					}
-				}
+			if ( ! isNavigationKey( event.key, keyboardNavigation ) ) {
 				return;
 			}
 
-			let stepCol = 0;
-			let stepRow = 0;
-			if ( event.key === 'ArrowRight' ) {
-				stepCol = 1;
-			} else if ( event.key === 'ArrowLeft' ) {
-				stepCol = -1;
-			} else if ( event.key === 'ArrowDown' ) {
-				stepRow = 1;
-			} else if ( event.key === 'ArrowUp' ) {
-				stepRow = -1;
-			}
+			event.preventDefault();
 
-			// Step past hidden slots to the next navigable cell in the pressed
-			// direction; when only hidden slots (or the edge) remain that way,
-			// the selection stays put.
-			let col = Math.floor( selectedIndex / rows );
-			let row = selectedIndex % rows;
-			do {
-				col += stepCol;
-				row += stepRow;
-			} while ( col >= 0 && col < columns && row >= 0 && row < rows && isCellInert( col, row ) );
-
-			if ( col < 0 || col >= columns || row < 0 || row >= rows ) {
+			const grid = { columns, rows, isInert: isCellInert };
+			if ( selected === undefined ) {
+				setSelected(
+					keyboardNavigation === 'calendar'
+						? firstCalendarCell( grid, blocks )
+						: firstGridCell( grid )
+				);
 				return;
 			}
 
-			setSelectedIndex( col * rows + row );
+			const next =
+				keyboardNavigation === 'calendar'
+					? stepCalendarCell( grid, blocks, selected, event.key )
+					: stepGridCell( grid, selected, event.key );
+			if ( next ) {
+				setSelected( next );
+			}
 		},
-		[ rows, columns, selectedIndex, hideTooltip, isCellInert ]
+		[ rows, columns, selected, hideTooltip, isCellInert, keyboardNavigation, blocks ]
 	);
 
 	const handleCellMouseMove = useCallback(
@@ -239,51 +259,62 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		[ withTooltips, showTooltip, buildTooltipData, getTooltipOrigin ]
 	);
 
+	const getCellElement = useCallback(
+		( col: number, row: number ) =>
+			typeof document !== 'undefined'
+				? document.getElementById( `${ chartId }-cell-${ col }-${ row }` )
+				: null,
+		[ chartId ]
+	);
+
 	const handleCellMouseLeave = useCallback( () => {
 		// Keyboard selection owns the tooltip; don't let a mouse-out clear it.
-		if ( withTooltips && selectedIndex === undefined ) {
+		if ( withTooltips && selected === undefined ) {
 			hideTooltip();
 		}
-	}, [ withTooltips, selectedIndex, hideTooltip ] );
+	}, [ withTooltips, selected, hideTooltip ] );
+
+	// A data refresh that shrinks the grid would leave the selection on a slot that
+	// no longer exists; navigating from there has nothing to step from.
+	useEffect( () => {
+		if ( selected && ( selected.column >= columns || selected.row >= rows ) ) {
+			setSelected( undefined );
+		}
+	}, [ selected, columns, rows ] );
+
+	// Focus stays on the grid (aria-activedescendant), so the browser never scrolls
+	// the selected cell into a scroll container's view on its own. Keyed on the
+	// selection alone: a data refresh must not scroll the user back to it.
+	useEffect( () => {
+		if ( selected === undefined ) {
+			return;
+		}
+		const cell = getCellElement( selected.column, selected.row );
+		cell?.scrollIntoView?.( { block: 'nearest', inline: 'nearest' } );
+	}, [ selected, getCellElement ] );
 
 	// Anchor the tooltip at the selected cell's center on keyboard nav. Cleared on blur/Escape,
 	// not here, so a mouse hover (no selection) isn't affected.
 	useEffect( () => {
-		if ( ! withTooltips || selectedIndex === undefined ) {
+		if ( ! withTooltips || selected === undefined ) {
 			return;
 		}
 		const origin = getTooltipOrigin();
 		if ( ! origin ) {
 			return;
 		}
-		const col = Math.floor( selectedIndex / rows );
-		const row = selectedIndex % rows;
-		const cell =
-			typeof document !== 'undefined'
-				? document.getElementById( `${ chartId }-cell-${ col }-${ row }` )
-				: null;
-		const rect = cell?.getBoundingClientRect();
+		const rect = getCellElement( selected.column, selected.row )?.getBoundingClientRect();
 		showTooltip( {
 			tooltipLeft: rect ? rect.left + rect.width / 2 - origin.left : 0,
 			tooltipTop: rect ? rect.top + rect.height / 2 - origin.top : 0,
-			tooltipData: buildTooltipData( col, row ),
+			tooltipData: buildTooltipData( selected.column, selected.row ),
 		} );
-	}, [
-		selectedIndex,
-		withTooltips,
-		rows,
-		chartId,
-		buildTooltipData,
-		showTooltip,
-		getTooltipOrigin,
-	] );
+	}, [ selected, withTooltips, getCellElement, buildTooltipData, showTooltip, getTooltipOrigin ] );
 
 	const defaultRenderTooltip = useCallback(
 		( info: HeatmapTooltipData ) => (
 			<div>
-				<strong>
-					{ info.cellLabel || `${ info.columnLabel ?? '' } ${ info.rowLabel ?? '' }`.trim() }
-				</strong>
+				<strong>{ cellName( info ) }</strong>
 				<div>
 					{ info.value === null ? __( 'No data', 'jetpack-charts' ) : formatNumber( info.value ) }
 				</div>
@@ -316,19 +347,35 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	const rowTrack = compact
 		? 'var(--a8c-charts-dimension-heatmap-cell-size)'
 		: `minmax(${ minCellHeight ?? 0 }px, ${ maxCellHeight ? `${ maxCellHeight }px` : '1fr' })`;
+	const hasColumnLabels = data.some( column => Boolean( column.label ) );
+	const hasGroups = groupLayout.groups.length > 0;
+	// Every item is placed by hand rather than auto-flowed, so the template can
+	// carry gap tracks that hold no cell.
+	const columnLine = ( columnIndex: number ) => groupLayout.columns[ columnIndex ].line;
+	const firstDataRow = hasColumnLabels ? 2 : 1;
 	// A summary column takes a content-sized track: a roll-up is wider than a
 	// cell, and a shared track would stretch every cell to fit it. `max-content`
 	// as the max keeps the leftover width out of it once the data tracks hit
 	// `maxCellWidth`, where a plain `auto` would absorb it.
-	const columnTracks = data.some( column => column.summary )
-		? data
-				.map( column => ( column.summary ? 'minmax(auto, max-content)' : columnTrack ) )
-				.join( ' ' )
-		: `repeat(${ columns }, ${ columnTrack })`;
+	const dataTrack = ( column: ( typeof data )[ number ] ) =>
+		column.summary ? 'minmax(auto, max-content)' : columnTrack;
+	// The group gap is a track of its own: a margin cannot widen a fixed or
+	// minmax track the way it widens the summary's auto track. Compact cells
+	// are fixed, so there the gaps share the leftover width instead.
+	const gapTrack = compact ? `minmax(${ groupGap }px, 1fr)` : `${ groupGap }px`;
+	const columnTracks = data
+		.map( ( column, columnIndex ) =>
+			groupLayout.columns[ columnIndex ].gapBefore
+				? `${ gapTrack } ${ dataTrack( column ) }`
+				: dataTrack( column )
+		)
+		.join( ' ' );
 	const gridStyle: Record< string, string | number > = {
 		'--a8c-charts-color-heatmap-primary': primaryColorHex,
 		gridTemplateColumns: `auto ${ columnTracks }`,
-		gridTemplateRows: `auto repeat(${ rows }, ${ rowTrack })`,
+		gridTemplateRows: `${ hasColumnLabels ? 'auto ' : '' }repeat(${ rows }, ${ rowTrack })${
+			hasGroups ? ' auto' : ''
+		}`,
 	};
 	if ( compact ) {
 		gridStyle[ '--a8c-charts-dimension-heatmap-cell-gap' ] = `${ compactCellGap }px`;
@@ -350,10 +397,9 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		};
 	};
 
-	const activeDescendant =
-		selectedIndex !== undefined
-			? `${ chartId }-cell-${ Math.floor( selectedIndex / rows ) }-${ selectedIndex % rows }`
-			: undefined;
+	const activeDescendant = selected
+		? `${ chartId }-cell-${ selected.column }-${ selected.row }`
+		: undefined;
 
 	// A capped row track makes the chart content-sized vertically: neither the
 	// wrapper nor the grid stretches, or the leftover container height would
@@ -383,7 +429,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 					<div
 						ref={ containerRef }
 						role="grid"
-						aria-label={ __( 'Heatmap chart', 'jetpack-charts' ) }
+						aria-label={ ariaLabel ?? __( 'Heatmap chart', 'jetpack-charts' ) }
 						aria-rowcount={ rows }
 						aria-colcount={ columns }
 						aria-activedescendant={ activeDescendant }
@@ -392,28 +438,33 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 						onKeyDown={ onChartKeyDown }
 						className={ clsx( styles[ 'heatmap-chart__grid' ], {
 							[ styles[ 'heatmap-chart__grid--compact' ] ]: compact,
+							[ styles[ 'heatmap-chart__grid--flex-gaps' ] ]: compact && hasGroups,
 							[ styles[ 'heatmap-chart__grid--height-capped' ] ]: heightCapped,
 						} ) }
 						style={ gridStyle as CSSProperties }
 					>
-						{ /* Header row preserves the grid structure; cell aria-labels include this text. */ }
-						<div role="row" aria-hidden="true" className={ styles[ 'heatmap-chart__row' ] }>
-							<span />
-							{ data.map( ( column, columnIndex ) => (
-								<span
-									key={ `col-${ columnIndex }` }
-									className={ clsx( styles[ 'heatmap-chart__col-label' ], {
-										[ styles[ 'heatmap-chart__col-label--summary' ] ]: column.summary,
-										...summaryGaps( columnIndex ),
-									} ) }
-								>
-									{ column.label }
-								</span>
-							) ) }
-						</div>
+						{ /* Decorative: cell aria-labels already carry the column name. */ }
+						{ hasColumnLabels && (
+							<div role="row" aria-hidden="true" className={ styles[ 'heatmap-chart__row' ] }>
+								<span style={ { gridColumn: 1, gridRow: 1 } } />
+								{ data.map( ( column, columnIndex ) => (
+									<span
+										key={ `col-${ columnIndex }` }
+										style={ { gridColumn: columnLine( columnIndex ), gridRow: 1 } }
+										className={ clsx( styles[ 'heatmap-chart__col-label' ], {
+											[ styles[ 'heatmap-chart__col-label--summary' ] ]: column.summary,
+											...summaryGaps( columnIndex ),
+										} ) }
+									>
+										{ column.label }
+									</span>
+								) ) }
+							</div>
+						) }
 
 						{ Array.from( { length: rows } ).map( ( _row, rowIndex ) => {
 							const labelVisible = ! compact || rowIndex % 2 === 0;
+							const gridRow = firstDataRow + rowIndex;
 							return (
 								<div
 									key={ `row-${ rowIndex }` }
@@ -421,11 +472,16 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 									aria-rowindex={ rowIndex + 1 }
 									className={ styles[ 'heatmap-chart__row' ] }
 								>
-									<span aria-hidden="true" className={ styles[ 'heatmap-chart__row-label' ] }>
-										{ labelVisible ? rowLabels[ rowIndex ] ?? '' : '' }
+									<span
+										aria-hidden="true"
+										className={ styles[ 'heatmap-chart__row-label' ] }
+										style={ { gridColumn: 1, gridRow } }
+									>
+										{ labelVisible ? ( rowLabels[ rowIndex ] ?? '' ) : '' }
 									</span>
 									{ data.map( ( column, columnIndex ) => {
 										const cell = column.data[ rowIndex ];
+										const placement = { gridColumn: columnLine( columnIndex ), gridRow };
 
 										// A hidden cell keeps its grid slot (so the rest of the
 										// column doesn't shift) but paints nothing and takes no
@@ -436,6 +492,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 													key={ `cell-${ columnIndex }-${ rowIndex }` }
 													data-testid="heatmap-cell-hidden"
 													aria-hidden="true"
+													style={ placement }
 													className={ clsx(
 														styles[ 'heatmap-chart__cell' ],
 														styles[ 'heatmap-chart__cell--hidden' ]
@@ -454,6 +511,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 													key={ `cell-${ columnIndex }-${ rowIndex }` }
 													data-testid="heatmap-cell-placeholder"
 													aria-hidden="true"
+													style={ placement }
 													className={ clsx(
 														styles[ 'heatmap-chart__cell' ],
 														styles[ 'heatmap-chart__cell--placeholder' ]
@@ -467,12 +525,8 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 										// A summary cell is on another scale, so it takes no fill.
 										const filled = present && ! column.summary;
 										const normalized = filled ? getNormalizedValue( value, extent ) : 0;
-										const flatIndex = columnIndex * rows + rowIndex;
 										const info = buildTooltipData( columnIndex, rowIndex );
-										const accessibleName =
-											info.cellLabel ||
-											`${ info.columnLabel ?? '' } ${ info.rowLabel ?? '' }`.trim();
-										const accessibleLabel = `${ accessibleName }: ${
+										const accessibleLabel = `${ cellName( info ) }: ${
 											info.value === null
 												? __( 'No data', 'jetpack-charts' )
 												: formatNumber( info.value )
@@ -498,14 +552,15 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 													[ styles[ 'heatmap-chart__cell--summary' ] ]: column.summary,
 													...summaryGaps( columnIndex ),
 													[ styles[ 'heatmap-chart__cell--selected' ] ]:
-														selectedIndex === flatIndex,
+														selected?.column === columnIndex && selected?.row === rowIndex,
 												} ) }
 												style={
-													filled
-														? ( {
-																'--a8c-charts-heatmap-cell-intensity': normalized,
-														  } as CSSProperties )
-														: undefined
+													{
+														...placement,
+														...( filled
+															? { '--a8c-charts-heatmap-cell-intensity': normalized }
+															: {} ),
+													} as CSSProperties
 												}
 												onMouseMove={ handleCellMouseMove }
 												onMouseLeave={ handleCellMouseLeave }
@@ -522,9 +577,31 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 								</div>
 							);
 						} ) }
+						{ hasGroups && (
+							<div role="row" aria-hidden="true" className={ styles[ 'heatmap-chart__row' ] }>
+								{ groupLayout.groups.map( ( group, groupIndex ) => (
+									<span
+										key={ `group-${ groupIndex }` }
+										data-testid="heatmap-group-label"
+										className={ styles[ 'heatmap-chart__group-label' ] }
+										style={ {
+											gridColumn: `${ group.line } / span ${ group.span }`,
+											gridRow: firstDataRow + rows,
+										} }
+									>
+										{ group.label }
+									</span>
+								) ) }
+							</div>
+						) }
 					</div>
 					{ withTooltips && tooltipOpen && tooltipData && (
-						<BoundedTooltip top={ tooltipTop } left={ tooltipLeft }>
+						<BoundedTooltip
+							top={ tooltipTop }
+							left={ tooltipLeft }
+							className={ tooltipVariant === 'dark' ? tooltipStyles.surface : undefined }
+							style={ tooltipBoxStyle }
+						>
 							<div className={ standaloneScopeClass } role="tooltip" tabIndex={ -1 }>
 								{ ( renderTooltip ?? defaultRenderTooltip )( tooltipData ) }
 							</div>

package/src/charts/heatmap-chart/index.ts

@@ -1,11 +1,17 @@
 export { default as HeatmapChart, HeatmapChartUnresponsive } from './heatmap-chart';
 export { buildCalendarHeatmapData } from './build-calendar-data';
+export { buildMonthCalendarHeatmapData } from './build-month-calendar-data';
 export { useCalendarHeatmapData } from './use-calendar-heatmap-data';
+export { useMonthCalendarHeatmapData } from './use-month-calendar-heatmap-data';
 export type {
 	CalendarHeatmapOptions,
 	CalendarHeatmapResult,
 	HeatmapChartProps,
 	HeatmapColumn,
+	HeatmapColumnGroup,
 	HeatmapCell,
 	HeatmapTooltipData,
+	MonthCalendarHeatmapOptions,
+	MonthCalendarHeatmapRange,
+	MonthCalendarHeatmapResult,
 } from './types';

package/src/charts/heatmap-chart/private/civil-day.ts

@@ -1,4 +1,5 @@
 import { parseISO } from 'date-fns';
+import { createDateFormatter } from '../../../utils/date-formatting';
 import { hasTimezone } from '../../../utils/date-parsing';
 import type { DataPointDate } from '../../../types';
 
@@ -27,6 +28,31 @@ const KEY_OPTIONS: Intl.DateTimeFormatOptions = {
 
 const DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})/;
 
+/**
+ * Label formatters for UTC proxies, so both calendar layouts name a day alike.
+ *
+ * `gregory` keeps a locale whose default calendar is not Gregorian (fa-IR) from
+ * splitting one grid month across two names.
+ *
+ * @param locale - BCP 47 locale.
+ * @return Weekday, month and full-day formatters.
+ */
+export const civilLabelFormatters = ( locale: string ) => {
+	const formatting = { locale, timeZone: 'UTC' };
+	return {
+		formatWeekday: createDateFormatter( { weekday: 'short', calendar: 'gregory' }, formatting ),
+		formatMonth: createDateFormatter( { month: 'short', calendar: 'gregory' }, formatting ),
+		formatMonthYear: createDateFormatter(
+			{ month: 'short', year: 'numeric', calendar: 'gregory' },
+			formatting
+		),
+		formatDay: createDateFormatter(
+			{ weekday: 'short', month: 'short', day: 'numeric', year: 'numeric', calendar: 'gregory' },
+			formatting
+		),
+	};
+};
+
 const pad = ( value: number, length: number ) => String( value ).padStart( length, '0' );
 
 /**

package/src/charts/heatmap-chart/private/column-groups.ts

@@ -0,0 +1,71 @@
+import { warnOnce } from '../../../utils/warn-once';
+import type { HeatmapColumnGroup } from '../types';
+
+export type ColumnGroupLayout = {
+	/** One per data column: its grid column line, whether a gap track precedes it, and its group's index. */
+	columns: { line: number; gapBefore: boolean; group?: number }[];
+	/** The groups as given, each with the grid column line its label starts on; none when any was unusable. */
+	groups: ( HeatmapColumnGroup & { line: number } )[];
+};
+
+const isSpan = ( span: number ) => Number.isInteger( span ) && span > 0;
+
+/**
+ * Validates column groups and lays them over the columns.
+ *
+ * @param groups      - Groups as passed to the chart.
+ * @param columnCount - Number of data columns.
+ * @param firstLine   - Grid column line of the first data column.
+ * @return Grid column lines for every column and group; no groups when the input was unusable.
+ */
+export const resolveColumnGroups = (
+	groups: HeatmapColumnGroup[] | undefined,
+	columnCount: number,
+	firstLine: number
+): ColumnGroupLayout => {
+	const ungrouped = (): ColumnGroupLayout => ( {
+		columns: Array.from( { length: columnCount }, ( _, index ) => ( {
+			line: firstLine + index,
+			gapBefore: false,
+		} ) ),
+		groups: [],
+	} );
+
+	// An empty grid draws nothing, so static groups awaiting data are not a misuse.
+	if ( ! groups || groups.length === 0 || columnCount === 0 ) {
+		return ungrouped();
+	}
+
+	const spans = groups.map( group => group.span );
+	const total = spans.reduce( ( sum, span ) => sum + span, 0 );
+	if ( ! spans.every( isSpan ) || total > columnCount ) {
+		warnOnce(
+			`heatmap:columnGroups:${ JSON.stringify( spans ) }:${ columnCount }`,
+			`columnGroups spans ${ JSON.stringify(
+				spans
+			) } must be positive integers that fit the ${ columnCount } columns, so no groups are drawn.`
+		);
+		return ungrouped();
+	}
+
+	const columns: ColumnGroupLayout[ 'columns' ] = [];
+	const laidOut: ColumnGroupLayout[ 'groups' ] = [];
+	let line = firstLine;
+	groups.forEach( ( group, groupIndex ) => {
+		if ( groupIndex > 0 ) {
+			line += 1;
+		}
+		laidOut.push( { ...group, line } );
+		for ( let offset = 0; offset < group.span; offset++ ) {
+			columns.push( { line, gapBefore: groupIndex > 0 && offset === 0, group: groupIndex } );
+			line += 1;
+		}
+	} );
+	// An ungrouped tail opens no further gap.
+	while ( columns.length < columnCount ) {
+		columns.push( { line, gapBefore: false } );
+		line += 1;
+	}
+
+	return { columns, groups: laidOut };
+};