@automattic/charts 4.8.0 → 4.9.0

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

@@ -4,6 +4,7 @@ import { __ } from '@wordpress/i18n';
 import clsx from 'clsx';
 import isEqual from 'fast-deep-equal';
 import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { flushSync } from 'react-dom';
 import { BoundedTooltip, TOOLTIP_Z_INDEX } from '../../components/tooltip/private/bounded-tooltip';
 import { useIsomorphicLayoutEffect } from '../../hooks';
 import {
@@ -23,6 +24,7 @@ import { useStandaloneScopeClass } from '../../providers/chart-scope';
 import { attachSubComponents } from '../../utils';
 import { isValidHexColor, normalizeColorToHex } from '../../utils/color-utils';
 import { createCssVariableResolver } from '../../utils/resolve-css-var';
+import { warnOnce } from '../../utils/warn-once';
 import { Center } from '../private/center';
 import { useChartChildren } from '../private/chart-composition';
 import { ChartInstanceContext } from '../private/chart-instance-context';
@@ -31,6 +33,7 @@ import { pickLabelTextColorForFill, resolveLabelRoles } from '../private/label-t
 import { withResponsive } from '../private/with-responsive';
 import styles from './heatmap-chart.module.scss';
 import {
+	fitCompactCells,
 	getHeatmapScale,
 	getValueExtent,
 	getNormalizedValue,
@@ -39,6 +42,7 @@ import {
 	isEmptyValue,
 	isPresent,
 	resolveColumnGroups,
+	wrapColumnGroups,
 } from './private';
 import {
 	firstCalendarCell,
@@ -47,7 +51,7 @@ import {
 	stepCalendarCell,
 	stepGridCell,
 } from './private/keyboard-navigation';
-import type { HeatmapContextValue } from './private';
+import type { CompactCellFit, HeatmapContextValue } from './private';
 import type { CellBlock, CellPosition } from './private/keyboard-navigation';
 import type { HeatmapChartProps, HeatmapTooltipData } from './types';
 import type { LabelRoles, LabelTextColor } from '../private/label-text-color';
@@ -68,6 +72,27 @@ const NO_ROW_LABELS: string[] = [];
 
 const TOOLTIP_BOX_STYLE: CSSProperties = { zIndex: TOOLTIP_Z_INDEX };
 
+const largest = ( root: Element, selector: string, size: 'offsetWidth' | 'offsetHeight' ) =>
+	Math.max(
+		0,
+		...Array.from( root.querySelectorAll< HTMLElement >( selector ), el => el[ size ] )
+	);
+
+// The box the grid may fill: the chart's own box less its other in-flow children
+// (the legend, say) and the gaps between them.
+const gridBox = ( chart: HTMLElement, grid: HTMLElement ) => {
+	let height = chart.clientHeight;
+	const rowGap = parseFloat( getComputedStyle( chart ).rowGap ) || 0;
+	Array.from( chart.children ).forEach( child => {
+		const { display, position } = getComputedStyle( child );
+		if ( child === grid || display === 'none' || position === 'absolute' || position === 'fixed' ) {
+			return;
+		}
+		height -= ( child as HTMLElement ).offsetHeight + rowGap;
+	} );
+	return { width: chart.clientWidth, height };
+};
+
 // The cell's own label wins; otherwise the group, column and row labels name it.
 const cellName = ( info: HeatmapTooltipData ) =>
 	info.cellLabel ||
@@ -80,6 +105,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	height = 0,
 	className,
 	compact = false,
+	fitCells = false,
 	showValues,
 	maxCellWidth,
 	maxCellHeight,
@@ -110,16 +136,11 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		useTooltip< HeatmapTooltipData >();
 	const standaloneScopeClass = useStandaloneScopeClass();
 	const containerRef = useRef< HTMLDivElement >( null );
+	const chartRef = useRef< HTMLDivElement >( null );
 	const [ labelRoles, setLabelRoles ] = useState< LabelRoles | null >( null );
-	// The chart root positions the tooltip, so pointer and cell coordinates are
-	// measured against it — found by its id rather than by walking up, so
-	// whatever ChartLayout wraps the grid in cannot shift the origin.
 	const getTooltipOrigin = useCallback(
-		() =>
-			containerRef.current
-				?.closest( `[data-chart-id="heatmap-chart-${ chartId }"]` )
-				?.getBoundingClientRect() ?? null,
-		[ chartId ]
+		() => chartRef.current?.getBoundingClientRect() ?? null,
+		[]
 	);
 
 	const { color: primaryColorHex } = getElementStyles( {
@@ -189,6 +210,67 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 
 	const { compactCellGap, compactCellSize, groupGap } = heatmapChartSettings;
 	const drawValues = showValues ?? ! compact;
+	const hasColumnLabels = data.some( column => Boolean( column.label ) );
+	const hasGroups = groupLayout.groups.length > 0;
+
+	const [ fit, setFit ] = useState< CompactCellFit | null >( null );
+	// A summary track is as wide as its figure, which the fit cannot size as a cell.
+	const hasSummary = data.some( column => column.summary );
+	const fitting = compact && fitCells && ! hasSummary;
+	if ( fitCells && ! fitting ) {
+		warnOnce(
+			'heatmap:fitCells',
+			'fitCells applies only in compact mode without summary columns, so the cells keep their size.'
+		);
+	}
+	useIsomorphicLayoutEffect( () => {
+		const chart = chartRef.current;
+		const grid = containerRef.current;
+		if ( ! fitting || ! chart || ! grid ) {
+			setFit( null );
+			return;
+		}
+		const measure = () => {
+			const next = fitCompactCells( {
+				...gridBox( chart, grid ),
+				layout: groupLayout,
+				rows,
+				cellGap: compactCellGap,
+				groupGap,
+				rowLabelWidth: largest( grid, `.${ styles[ 'heatmap-chart__row-label' ] }`, 'offsetWidth' ),
+				columnLabelHeight: hasColumnLabels
+					? largest( grid, `.${ styles[ 'heatmap-chart__col-label' ] }`, 'offsetHeight' )
+					: null,
+				groupLabelHeight: hasGroups
+					? largest( grid, `.${ styles[ 'heatmap-chart__group-label' ] }`, 'offsetHeight' )
+					: null,
+				minCellSize: compactCellSize,
+			} );
+			setFit( previous => ( isEqual( previous, next ) ? previous : next ) );
+		};
+		measure();
+		if ( typeof ResizeObserver === 'undefined' ) {
+			return;
+		}
+		// Commit before later observers in this delivery read the grid, or they see the
+		// old cells at the new width, and before paint, so that frame is never drawn.
+		const observer = new ResizeObserver( () => flushSync( measure ) );
+		observer.observe( chart );
+		return () => observer.disconnect();
+	}, [
+		fitting,
+		groupLayout,
+		rows,
+		hasColumnLabels,
+		hasGroups,
+		compactCellGap,
+		compactCellSize,
+		groupGap,
+	] );
+	const wrapped = useMemo(
+		() => ( fit ? wrapColumnGroups( groupLayout, fit.bands ) : null ),
+		[ fit, groupLayout ]
+	);
 
 	const buildTooltipData = useCallback(
 		( columnIndex: number, rowIndex: number ): HeatmapTooltipData => {
@@ -376,12 +458,18 @@ 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;
+	const placed = wrapped ?? groupLayout;
+	const columnLine = ( columnIndex: number ) => placed.columns[ columnIndex ].line;
+	const bandOf = ( columnIndex: number ) => placed.columns[ columnIndex ].band;
+	const { bands } = placed;
+	// Each band repeats the label row, the data rows and the group-label row, and
+	// the next starts one group gap below.
+	const bandRowCount = ( hasColumnLabels ? 1 : 0 ) + rows + ( hasGroups ? 1 : 0 ) + 1;
+	const labelRowOf = ( band: number ) => 1 + band * bandRowCount;
+	const dataRowOf = ( band: number, rowIndex: number ) =>
+		labelRowOf( band ) + ( hasColumnLabels ? 1 : 0 ) + rowIndex;
 	// 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
@@ -392,23 +480,33 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	// 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( ' ' );
+	// Wrapped bands share one set of slots, each as wide as its widest group.
+	const columnTracks = wrapped
+		? wrapped.slotSpans
+				.map( ( span, slot ) =>
+					[ ...( slot > 0 ? [ gapTrack ] : [] ), ...Array( span ).fill( columnTrack ) ].join( ' ' )
+				)
+				.join( ' ' )
+		: data
+				.map( ( column, columnIndex ) =>
+					groupLayout.columns[ columnIndex ].gapBefore
+						? `${ gapTrack } ${ dataTrack( column ) }`
+						: dataTrack( column )
+				)
+				.join( ' ' );
+	const bandTracks = `${ hasColumnLabels ? 'auto ' : '' }repeat(${ rows }, ${ rowTrack })${
+		hasGroups ? ' auto' : ''
+	}`;
 	const gridStyle: Record< string, string | number > = {
 		...fillVars,
 		gridTemplateColumns: `auto ${ columnTracks }`,
-		gridTemplateRows: `${ hasColumnLabels ? 'auto ' : '' }repeat(${ rows }, ${ rowTrack })${
-			hasGroups ? ' auto' : ''
-		}`,
+		gridTemplateRows: Array( bands ).fill( bandTracks ).join( ` ${ groupGap }px ` ),
 	};
 	if ( compact ) {
 		gridStyle[ '--a8c-charts-dimension-heatmap-cell-gap' ] = `${ compactCellGap }px`;
-		gridStyle[ '--a8c-charts-dimension-heatmap-cell-size' ] = `${ compactCellSize }px`;
+		gridStyle[ '--a8c-charts-dimension-heatmap-cell-size' ] = `${
+			fit?.cellSize ?? compactCellSize
+		}px`;
 	}
 
 	// A summary column sits one gap apart from the data on either side; two
@@ -445,6 +543,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 					legendChildren={ [] }
 					trailingContent={ nonLegendChildren }
 					gap={ gap }
+					rootRef={ chartRef }
 					className={ clsx( 'heatmap-chart', styles[ 'heatmap-chart' ], className, {
 						[ styles[ 'heatmap-chart--height-capped' ] ]: heightCapped,
 					} ) }
@@ -475,11 +574,14 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 						{ /* 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 } } />
+								<span style={ { gridColumn: 1, gridRow: labelRowOf( 0 ) } } />
 								{ data.map( ( column, columnIndex ) => (
 									<span
 										key={ `col-${ columnIndex }` }
-										style={ { gridColumn: columnLine( columnIndex ), gridRow: 1 } }
+										style={ {
+											gridColumn: columnLine( columnIndex ),
+											gridRow: labelRowOf( bandOf( columnIndex ) ),
+										} }
 										className={ clsx( styles[ 'heatmap-chart__col-label' ], {
 											[ styles[ 'heatmap-chart__col-label--summary' ] ]: column.summary,
 											...summaryGaps( columnIndex ),
@@ -493,7 +595,6 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 
 						{ Array.from( { length: rows } ).map( ( _row, rowIndex ) => {
 							const labelVisible = ! compact || rowIndex % 2 === 0;
-							const gridRow = firstDataRow + rowIndex;
 							return (
 								<div
 									key={ `row-${ rowIndex }` }
@@ -501,16 +602,22 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 									aria-rowindex={ rowIndex + 1 }
 									className={ styles[ 'heatmap-chart__row' ] }
 								>
-									<span
-										aria-hidden="true"
-										className={ styles[ 'heatmap-chart__row-label' ] }
-										style={ { gridColumn: 1, gridRow } }
-									>
-										{ labelVisible ? ( rowLabels[ rowIndex ] ?? '' ) : '' }
-									</span>
+									{ Array.from( { length: bands } ).map( ( _band, band ) => (
+										<span
+											key={ `row-label-${ band }` }
+											aria-hidden="true"
+											className={ styles[ 'heatmap-chart__row-label' ] }
+											style={ { gridColumn: 1, gridRow: dataRowOf( band, rowIndex ) } }
+										>
+											{ labelVisible ? ( rowLabels[ rowIndex ] ?? '' ) : '' }
+										</span>
+									) ) }
 									{ data.map( ( column, columnIndex ) => {
 										const cell = column.data[ rowIndex ];
-										const placement = { gridColumn: columnLine( columnIndex ), gridRow };
+										const placement = {
+											gridColumn: columnLine( columnIndex ),
+											gridRow: dataRowOf( bandOf( columnIndex ), rowIndex ),
+										};
 
 										// A hidden cell keeps its grid slot (so the rest of the
 										// column doesn't shift) but paints nothing and takes no
@@ -611,14 +718,14 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 						} ) }
 						{ hasGroups && (
 							<div role="row" aria-hidden="true" className={ styles[ 'heatmap-chart__row' ] }>
-								{ groupLayout.groups.map( ( group, groupIndex ) => (
+								{ placed.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,
+											gridRow: dataRowOf( group.band, rows ),
 										} }
 									>
 										{ group.label }

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

@@ -2,10 +2,12 @@ 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 } )[];
+	/** One per data column: its grid column line and band, whether a gap track precedes it, and its group's index. */
+	columns: { line: number; band: number; gapBefore: boolean; group?: number }[];
+	/** The groups as given, each with the grid column line and band its label sits on; none when any was unusable. */
+	groups: ( HeatmapColumnGroup & { line: number; band: number } )[];
+	/** Rows of groups the columns are laid out on. */
+	bands: number;
 };
 
 const isSpan = ( span: number ) => Number.isInteger( span ) && span > 0;
@@ -26,9 +28,11 @@ export const resolveColumnGroups = (
 	const ungrouped = (): ColumnGroupLayout => ( {
 		columns: Array.from( { length: columnCount }, ( _, index ) => ( {
 			line: firstLine + index,
+			band: 0,
 			gapBefore: false,
 		} ) ),
 		groups: [],
+		bands: 1,
 	} );
 
 	// An empty grid draws nothing, so static groups awaiting data are not a misuse.
@@ -55,17 +59,84 @@ export const resolveColumnGroups = (
 		if ( groupIndex > 0 ) {
 			line += 1;
 		}
-		laidOut.push( { ...group, line } );
+		laidOut.push( { ...group, line, band: 0 } );
 		for ( let offset = 0; offset < group.span; offset++ ) {
-			columns.push( { line, gapBefore: groupIndex > 0 && offset === 0, group: groupIndex } );
+			columns.push( {
+				line,
+				band: 0,
+				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 } );
+		columns.push( { line, band: 0, gapBefore: false } );
 		line += 1;
 	}
 
-	return { columns, groups: laidOut };
+	return { columns, groups: laidOut, bands: 1 };
+};
+
+export type WrappedColumnGroupLayout = ColumnGroupLayout & {
+	/** Columns per group slot: the widest group in that position on any band. */
+	slotSpans: number[];
+};
+
+/**
+ * Wraps the groups onto bands of equal group count, each band starting back at
+ * the first data line so the groups line up in slots down the bands.
+ *
+ * @param layout - The unwrapped layout from `resolveColumnGroups`.
+ * @param bands  - Bands to aim for; the groups split as evenly as whole bands allow.
+ * @return The wrapped layout, or null when there is nothing to wrap: one band, one group, or a column outside every group.
+ */
+export const wrapColumnGroups = (
+	layout: ColumnGroupLayout,
+	bands: number
+): WrappedColumnGroupLayout | null => {
+	const { columns, groups } = layout;
+	if ( bands < 2 || groups.length < 2 || columns.some( column => column.group === undefined ) ) {
+		return null;
+	}
+
+	const perBand = Math.ceil( groups.length / bands );
+	const slotSpans: number[] = Array( perBand ).fill( 0 );
+	groups.forEach( ( group, index ) => {
+		const slot = index % perBand;
+		slotSpans[ slot ] = Math.max( slotSpans[ slot ], group.span );
+	} );
+	const slotLines: number[] = [];
+	let line = columns[ 0 ].line;
+	slotSpans.forEach( ( span, slot ) => {
+		if ( slot > 0 ) {
+			line += 1;
+		}
+		slotLines.push( line );
+		line += span;
+	} );
+
+	const wrappedGroups = groups.map( ( group, index ) => ( {
+		...group,
+		line: slotLines[ index % perBand ],
+		band: Math.floor( index / perBand ),
+	} ) );
+	const wrappedColumns = columns.map( column => {
+		const group = column.group as number;
+		const offset = column.line - groups[ group ].line;
+		return {
+			...column,
+			line: wrappedGroups[ group ].line + offset,
+			band: wrappedGroups[ group ].band,
+			gapBefore: offset === 0 && group % perBand > 0,
+		};
+	} );
+
+	return {
+		columns: wrappedColumns,
+		groups: wrappedGroups,
+		bands: Math.ceil( groups.length / perBand ),
+		slotSpans,
+	};
 };

package/src/charts/heatmap-chart/private/fit-compact-cells.ts

@@ -0,0 +1,72 @@
+import { wrapColumnGroups } from './column-groups';
+import type { ColumnGroupLayout } from './column-groups';
+
+export type CompactCellFitInput = {
+	/** Width and height (px) the grid may take. */
+	width: number;
+	height: number;
+	/** The unwrapped layout; every band count is tried through `wrapColumnGroups` on it. */
+	layout: ColumnGroupLayout;
+	rows: number;
+	cellGap: number;
+	groupGap: number;
+	/** Label track and row sizes (px); null for a label row the grid does not draw. */
+	rowLabelWidth: number;
+	columnLabelHeight: number | null;
+	groupLabelHeight: number | null;
+	/** Smallest cell worth drawing; below it the grid stays on one band and overflows. */
+	minCellSize: number;
+};
+
+export type CompactCellFit = { bands: number; cellSize: number };
+
+/**
+ * Largest whole-pixel square cell, and the band count giving it, for a compact grid in a box.
+ *
+ * @param input - The box, the grid's layout, and its fixed gaps and label sizes.
+ * @return The fit; one band at `minCellSize` when no band count reaches it.
+ */
+export const fitCompactCells = ( input: CompactCellFitInput ): CompactCellFit => {
+	const { width, height, layout, rows, cellGap, groupGap, minCellSize } = input;
+	const columns = layout.columns.length;
+	if ( columns === 0 || rows === 0 ) {
+		return { bands: 1, cellSize: minCellSize };
+	}
+
+	const maxBands = Math.max( 1, layout.groups.length );
+	const labelHeights = ( input.columnLabelHeight ?? 0 ) + ( input.groupLabelHeight ?? 0 );
+	const bandTracks =
+		( input.columnLabelHeight === null ? 0 : 1 ) +
+		rows +
+		( input.groupLabelHeight === null ? 0 : 1 );
+	let best: CompactCellFit | null = null;
+
+	for ( let target = 1; target <= maxBands; target++ ) {
+		const wrapped = target > 1 ? wrapColumnGroups( layout, target ) : null;
+		const { bands } = wrapped ?? layout;
+		const cellColumns = wrapped
+			? wrapped.slotSpans.reduce( ( sum, span ) => sum + span, 0 )
+			: columns;
+		const gapTracks = wrapped
+			? wrapped.slotSpans.length - 1
+			: layout.columns.filter( column => column.gapBefore ).length;
+		// The row-label track, the cell tracks and the group-gap tracks, one cell gap apart.
+		const columnTracks = 1 + cellColumns + gapTracks;
+		const byWidth =
+			( width - input.rowLabelWidth - gapTracks * groupGap - ( columnTracks - 1 ) * cellGap ) /
+			cellColumns;
+
+		// Each band's tracks, plus one group-gap track between bands.
+		const rowTracks = bands * bandTracks + ( bands - 1 );
+		const fixedHeight =
+			bands * labelHeights + ( bands - 1 ) * groupGap + ( rowTracks - 1 ) * cellGap;
+		const byHeight = ( height - fixedHeight ) / ( bands * rows );
+
+		const cellSize = Math.floor( Math.min( byWidth, byHeight ) );
+		if ( cellSize >= minCellSize && ( ! best || cellSize > best.cellSize ) ) {
+			best = { bands, cellSize };
+		}
+	}
+
+	return best ?? { bands: 1, cellSize: minCellSize };
+};

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

@@ -1,13 +1,15 @@
 import { __ } from '@wordpress/i18n';
 import { Stack, Text } from '@wordpress/ui';
+import clsx from 'clsx';
 import { useContext } from 'react';
 import { useGlobalChartsTheme } from '../../../providers';
 import styles from '../heatmap-chart.module.scss';
 import { HeatmapContext } from './heatmap-context';
+import { isEmptyValue } from './use-heatmap-colors';
 import type { CSSProperties, FC } from 'react';
 
 export interface HeatmapLegendProps {
-	/** Number of swatches in the scale. Default 5. */
+	/** Number of color swatches in the scale, not counting the empty-cell swatch. Default 5. */
 	steps?: number;
 	/**
 	 * `swatches` spaces the steps out as cell-sized squares; `bar` joins them
@@ -29,8 +31,9 @@ export const HeatmapLegend: FC< HeatmapLegendProps > = ( {
 	if ( ! context ) {
 		return null;
 	}
-	const { fillVars } = context;
+	const { extent, fillVars } = context;
 	const labelStyle = legend.labelStyles;
+	const showsEmptyCell = isEmptyValue( 0, extent );
 
 	return (
 		<Stack direction="row" gap="xs" align="center">
@@ -48,6 +51,15 @@ export const HeatmapLegend: FC< HeatmapLegendProps > = ( {
 				data-testid="heatmap-legend-scale"
 				className={ variant === 'bar' ? styles[ 'heatmap-chart__legend-scale--bar' ] : undefined }
 			>
+				{ showsEmptyCell && (
+					<span
+						data-testid="heatmap-legend-empty-swatch"
+						className={ clsx(
+							styles[ 'heatmap-chart__legend-swatch' ],
+							styles[ 'heatmap-chart__legend-swatch--empty' ]
+						) }
+					/>
+				) }
 				{ Array.from( { length: steps }, ( _, index ) => {
 					const intensity = steps <= 1 ? 1 : index / ( steps - 1 );
 					return (

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

@@ -4,5 +4,7 @@ export { HeatmapLegend } from './heatmap-legend';
 export { HeatmapContext } from './heatmap-context';
 export type { HeatmapLegendProps } from './heatmap-legend';
 export type { HeatmapContextValue } from './heatmap-context';
-export { resolveColumnGroups } from './column-groups';
-export type { ColumnGroupLayout } from './column-groups';
+export { resolveColumnGroups, wrapColumnGroups } from './column-groups';
+export type { ColumnGroupLayout, WrappedColumnGroupLayout } from './column-groups';
+export { fitCompactCells } from './fit-compact-cells';
+export type { CompactCellFit } from './fit-compact-cells';

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

@@ -1,4 +1,4 @@
-import { resolveColumnGroups } from '../private/column-groups';
+import { resolveColumnGroups, wrapColumnGroups } from '../private/column-groups';
 
 const lines = ( columns: { line: number }[] ) => columns.map( column => column.line );
 const gaps = ( columns: { gapBefore: boolean }[] ) => columns.map( column => column.gapBefore );
@@ -16,6 +16,7 @@ describe( 'resolveColumnGroups', () => {
 		expect( resolveColumnGroups( [ { label: 'A', span: 3 } ], 0, 2 ) ).toEqual( {
 			columns: [],
 			groups: [],
+			bands: 1,
 		} );
 		expect( console ).not.toHaveWarned();
 	} );
@@ -30,9 +31,9 @@ describe( 'resolveColumnGroups', () => {
 		expect( lines( layout.columns ) ).toEqual( [ 2, 3, 5, 7, 8 ] );
 		expect( gaps( layout.columns ) ).toEqual( [ false, false, true, true, false ] );
 		expect( layout.groups ).toEqual( [
-			{ label: 'A', span: 2, line: 2 },
-			{ label: 'B', span: 1, line: 5 },
-			{ label: 'C', span: 2, line: 7 },
+			{ label: 'A', span: 2, line: 2, band: 0 },
+			{ label: 'B', span: 1, line: 5, band: 0 },
+			{ label: 'C', span: 2, line: 7, band: 0 },
 		] );
 		expect( layout.columns.map( column => column.group ) ).toEqual( [ 0, 0, 1, 2, 2 ] );
 	} );
@@ -81,3 +82,39 @@ describe( 'resolveColumnGroups', () => {
 		expect( console ).toHaveWarned();
 	} );
 } );
+
+describe( 'wrapColumnGroups', () => {
+	const groups = [
+		{ label: 'A', span: 2 },
+		{ label: 'B', span: 1 },
+		{ label: 'C', span: 2 },
+	];
+
+	test( 'restarts each band at the first line, aligning the groups in slots as wide as their widest', () => {
+		const wrapped = wrapColumnGroups( resolveColumnGroups( groups, 5, 2 ), 2 );
+		expect( wrapped?.slotSpans ).toEqual( [ 2, 1 ] );
+		expect(
+			wrapped?.columns.map( ( { line, band, gapBefore } ) => [ line, band, gapBefore ] )
+		).toEqual( [
+			[ 2, 0, false ],
+			[ 3, 0, false ],
+			[ 5, 0, true ],
+			[ 2, 1, false ],
+			[ 3, 1, false ],
+		] );
+		expect( wrapped?.groups.map( ( { label, line, band } ) => [ label, line, band ] ) ).toEqual( [
+			[ 'A', 2, 0 ],
+			[ 'B', 5, 0 ],
+			[ 'C', 2, 1 ],
+		] );
+	} );
+
+	test.each( [
+		[ 'one band', groups, 5, 1 ],
+		[ 'an ungrouped tail', groups, 6, 2 ],
+	] )( 'leaves the layout unwrapped for %s', ( _, columnGroups, columnCount, bands ) => {
+		expect(
+			wrapColumnGroups( resolveColumnGroups( columnGroups, columnCount, 2 ), bands )
+		).toBeNull();
+	} );
+} );

package/src/charts/heatmap-chart/test/fit-compact-cells.test.ts

@@ -0,0 +1,59 @@
+import { resolveColumnGroups } from '../private/column-groups';
+import { fitCompactCells } from '../private/fit-compact-cells';
+
+const monthGroups = Array.from( { length: 12 }, ( _, index ) => ( {
+	label: `M${ index + 1 }`,
+	span: 7,
+} ) );
+
+// Twelve month calendars, weekdays across and six weeks down, labelled beneath.
+const months = {
+	layout: resolveColumnGroups( monthGroups, 84, 2 ),
+	rows: 6,
+	cellGap: 2,
+	groupGap: 16,
+	rowLabelWidth: 0,
+	columnLabelHeight: null,
+	groupLabelHeight: 22,
+	minCellSize: 11,
+};
+
+describe( 'fitCompactCells', () => {
+	test.each( [
+		[ 'a one-row tile keeps one band at the floor', 1189, 110, { bands: 1, cellSize: 11 } ],
+		[ 'a wide one-row tile grows its single band', 1900, 130, { bands: 1, cellSize: 16 } ],
+		[ 'a two-row tile wraps into two bands of six', 1189, 300, { bands: 2, cellSize: 17 } ],
+		[ 'a tall narrow tile wraps into four bands of three', 372, 641, { bands: 4, cellSize: 14 } ],
+		[
+			'a narrow tile wraps rather than overflow at the floor',
+			320,
+			641,
+			{ bands: 4, cellSize: 11 },
+		],
+	] )( '%s', ( _, width, height, expected ) => {
+		expect( fitCompactCells( { ...months, width, height } ) ).toEqual( expected );
+	} );
+
+	test( 'sizes a grid with an ungrouped tail for the one band it can draw', () => {
+		const layout = resolveColumnGroups( monthGroups.slice( 0, 3 ), 22, 2 );
+		expect( fitCompactCells( { ...months, layout, width: 400, height: 400 } ) ).toEqual( {
+			bands: 1,
+			cellSize: 14,
+		} );
+	} );
+
+	test( 'leaves room for the row-label track and the column-label row', () => {
+		expect(
+			fitCompactCells( {
+				...months,
+				layout: resolveColumnGroups( undefined, 10, 2 ),
+				rows: 2,
+				groupLabelHeight: null,
+				rowLabelWidth: 40,
+				columnLabelHeight: 20,
+				width: 300,
+				height: 100,
+			} )
+		).toEqual( { bands: 1, cellSize: 24 } );
+	} );
+} );