@automattic/charts 4.7.0 → 4.9.0

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 { primaryColorHex } = 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 (
@@ -57,7 +69,7 @@ export const HeatmapLegend: FC< HeatmapLegendProps > = ( {
 							className={ styles[ 'heatmap-chart__legend-swatch' ] }
 							style={
 								{
-									'--a8c-charts-color-heatmap-primary': primaryColorHex,
+									...fillVars,
 									'--a8c-charts-heatmap-cell-intensity': intensity,
 								} as CSSProperties
 							}

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

@@ -0,0 +1,74 @@
+import { MIN_BACKGROUND_CONTRAST } from '../../../providers/chart-context/private/palette-generator';
+import { contrastRatio } from '../../../providers/chart-context/private/perceptual-color';
+import { mixHexColors, relativeLuminance } from '../../../utils/color-utils';
+
+/** Contrast the highest step aims for against the background, so the steps stay apart. */
+export const HEATMAP_HIGH_CONTRAST = 9;
+
+const STEPS = 200;
+
+export type HeatmapScale = {
+	low: string;
+	high: string;
+};
+
+// Measured on the rounded hex the browser paints, so an endpoint never lands under its threshold.
+const firstMeeting = ( from: string, to: string, meets: ( color: string ) => boolean ) => {
+	for ( let step = 0; step <= STEPS; step++ ) {
+		const color = mixHexColors( from, to, step / STEPS );
+		if ( meets( color ) ) {
+			return color;
+		}
+	}
+	return null;
+};
+
+/**
+ * The two ends of the heatmap fill scale: 3:1 against the background and the empty cell at the
+ * low end, toward 9:1 against the background at the high end.
+ *
+ * @param primary    - The resolved primary color, as six-digit hex.
+ * @param background - The resolved chart background, as six-digit hex.
+ * @param emptyCell  - The resolved empty-cell color, as six-digit hex, when it is opaque.
+ * @return The scale ends, as six-digit hex.
+ */
+export const getHeatmapScale = (
+	primary: string,
+	background: string,
+	emptyCell?: string | null
+): HeatmapScale => {
+	const primaryStandsOut = contrastRatio( primary, background ) >= MIN_BACKGROUND_CONTRAST;
+	// The scale deepens to black or white on the primary's own side of the background, so it never
+	// crosses it. A primary too close to the background takes whichever contrasts more.
+	const towardWhite = primaryStandsOut
+		? relativeLuminance( primary ) > relativeLuminance( background )
+		: contrastRatio( '#ffffff', background ) > contrastRatio( '#000000', background );
+	const extreme = towardWhite ? '#ffffff' : '#000000';
+
+	const lowAgainst = ( references: string[] ) => {
+		const meets = ( color: string ) =>
+			references.every( reference => contrastRatio( color, reference ) >= MIN_BACKGROUND_CONTRAST );
+		return (
+			( primaryStandsOut ? firstMeeting( background, primary, meets ) : null ) ??
+			firstMeeting( primary, extreme, meets )
+		);
+	};
+	// Only `high` can miss: black or white tops out near 4.58:1 on a mid-tone background.
+	const high =
+		firstMeeting(
+			primary,
+			extreme,
+			color => contrastRatio( color, background ) >= HEATMAP_HIGH_CONTRAST
+		) ?? extreme;
+
+	// The lowest step sits beside empty cells, so it stands apart from them too, unless an
+	// empty-cell color far from the background would push it past the high end.
+	const againstEmptyCell = emptyCell ? lowAgainst( [ background, emptyCell ] ) : null;
+	const low =
+		againstEmptyCell &&
+		contrastRatio( againstEmptyCell, background ) <= contrastRatio( high, background )
+			? againstEmptyCell
+			: lowAgainst( [ background ] );
+
+	return { low: low ?? extreme, high };
+};

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

@@ -1,7 +1,10 @@
-export { getValueExtent, getNormalizedValue, isPresent } from './use-heatmap-colors';
+export { getValueExtent, getNormalizedValue, isEmptyValue, isPresent } from './use-heatmap-colors';
+export { getHeatmapScale } from './heatmap-scale';
 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/private/use-heatmap-colors.ts

@@ -4,14 +4,16 @@ export const isPresent = ( value: number | null | undefined ): value is number =
 	value !== null && value !== undefined && ! isNaN( value );
 
 /**
- * Get the min and max values from heatmap data, ignoring null/NaN. Summary
- * columns stay out: a roll-up on the scale would flatten every real cell.
+ * Get the min and max values from heatmap data, ignoring null/NaN and the zeros
+ * `isEmptyValue` paints as empty. Summary columns stay out: a roll-up on the
+ * scale would flatten every real cell.
  * @param data - The heatmap columns
  * @return Tuple of [min, max] values
  */
 export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 	let min = Infinity;
 	let max = -Infinity;
+	let hasZero = false;
 	for ( const column of data ) {
 		if ( column.summary ) {
 			continue;
@@ -20,6 +22,10 @@ export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 			if ( ! isPresent( cell.value ) ) {
 				continue;
 			}
+			if ( cell.value === 0 ) {
+				hasZero = true;
+				continue;
+			}
 			if ( cell.value < min ) {
 				min = cell.value;
 			}
@@ -28,17 +34,29 @@ export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 			}
 		}
 	}
+	if ( hasZero && min < 0 ) {
+		max = Math.max( max, 0 );
+	}
 	if ( min === Infinity ) {
 		return [ 0, 0 ];
 	}
 	return [ min, max ];
 };
 
+/**
+ * Whether a value paints as an empty cell: a zero in data with no negatives
+ * counts nothing, so it must not look like the lowest step of activity.
+ *
+ * @param value  - The cell value
+ * @param extent - The extent from `getValueExtent`
+ * @return True when the cell takes the empty-cell color
+ */
+export const isEmptyValue = ( value: number, extent: [ number, number ] ): boolean =>
+	value === 0 && extent[ 0 ] >= 0;
+
 /**
  * Normalize a value to 0–1 within the extent. A flat extent (min === max)
- * maps to 1 — every cell is equally the "highest" — except an all-zero
- * extent, which maps to 0 so a no-activity grid renders at the scale's
- * bottom instead of full intensity.
+ * maps to 1, since every cell is equally the "highest".
  *
  * @param value  - The value to normalize
  * @param extent - Tuple of [min, max] values for the normalization range
@@ -47,7 +65,7 @@ export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 export const getNormalizedValue = ( value: number, extent: [ number, number ] ): number => {
 	const [ min, max ] = extent;
 	if ( min === max ) {
-		return max === 0 ? 0 : 1;
+		return 1;
 	}
 	return Math.min( 1, Math.max( 0, ( value - min ) / ( max - min ) ) );
 };

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 } );
+	} );
+} );

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

@@ -1,4 +1,4 @@
-import { render, screen, within } from '@testing-library/react';
+import { act, render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { GlobalChartsProvider } from '../../../providers';
 import { buildMonthCalendarHeatmapData } from '../build-month-calendar-data';
@@ -172,6 +172,49 @@ describe( 'HeatmapChart', () => {
 		).toHaveLength( 4 );
 	} );
 
+	test.each( [
+		[ 'with zeros painted empty', data, 1 ],
+		[ 'with negative values', [ { label: 'W1', data: [ { value: -2 }, { value: 0 } ] } ], 0 ],
+	] )( 'starts the legend scale with an empty-cell swatch %s', ( _case, rows, count ) => {
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ rows }>
+					<HeatmapChart.Legend variant="bar" />
+				</HeatmapChart>
+			</GlobalChartsProvider>
+		);
+		const empty = screen.queryAllByTestId( 'heatmap-legend-empty-swatch' );
+		const scale = screen.getByTestId( 'heatmap-legend-scale' );
+
+		expect( empty ).toHaveLength( count );
+		expect( within( scale ).getAllByTestId( 'heatmap-legend-swatch' ) ).toHaveLength( 5 );
+		expect(
+			within( scale )
+				.getAllByTestId( /^heatmap-legend-(empty-)?swatch$/ )
+				.slice( 0, count )
+		).toEqual( empty );
+	} );
+
+	test( 'paints the legend on the same scale as the cells', () => {
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } primaryColor="#3858e9">
+					<HeatmapChart.Legend />
+				</HeatmapChart>
+			</GlobalChartsProvider>
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+
+		for ( const swatch of screen.getAllByTestId( 'heatmap-legend-swatch' ) ) {
+			for ( const end of [ 'primary', 'low', 'high' ] ) {
+				const property = `--a8c-charts-color-heatmap-${ end }`;
+				expect( swatch.style.getPropertyValue( property ) ).toBe(
+					grid.style.getPropertyValue( property )
+				);
+			}
+		}
+	} );
+
 	test( 'ArrowDown moves focus within a column, ArrowRight moves to next column', async () => {
 		renderChart( { rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
 		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
@@ -409,6 +452,78 @@ describe( 'HeatmapChart', () => {
 		expect( grid.style.getPropertyValue( '--a8c-charts-color-heatmap-primary' ) ).toBe( '#abcdef' );
 	} );
 
+	test( 'leaves the fill to the stylesheet when the primary color cannot resolve to hex', () => {
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } primaryColor="oklch(0.6 0.2 260)">
+					<HeatmapChart.Legend />
+				</HeatmapChart>
+			</GlobalChartsProvider>
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		const swatches = screen.getAllByTestId( 'heatmap-legend-swatch' );
+
+		for ( const element of [ grid, ...swatches ] ) {
+			expect( element.style.getPropertyValue( '--a8c-charts-color-heatmap-primary' ) ).toBe(
+				'oklch(0.6 0.2 260)'
+			);
+			expect( element.style.getPropertyValue( '--a8c-charts-color-heatmap-low' ) ).toBe( '' );
+			expect( element.style.getPropertyValue( '--a8c-charts-color-heatmap-high' ) ).toBe( '' );
+		}
+		expect( screen.getByText( '4' ) ).toHaveClass( 'heatmap-chart__cell-value', { exact: true } );
+	} );
+
+	test( 'builds the scale for white on a see-through background, as the palette does', () => {
+		const scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-background', 'transparent' );
+		document.body.appendChild( scope );
+
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } primaryColor="#3858e9" />
+			</GlobalChartsProvider>,
+			{ container: scope }
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+
+		expect( grid.style.getPropertyValue( '--a8c-charts-color-heatmap-low' ) ).toBe( '#6c83ef' );
+		expect( grid.style.getPropertyValue( '--a8c-charts-color-heatmap-high' ) ).toBe( '#283ea5' );
+
+		document.body.removeChild( scope );
+	} );
+
+	test( 'reads the computed style once per re-render for the fill scale', () => {
+		const { rerender } = renderChart();
+		const spy = jest.spyOn( window, 'getComputedStyle' );
+
+		rerender(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } />
+			</GlobalChartsProvider>
+		);
+
+		expect( spy ).toHaveBeenCalledTimes( 1 );
+		spy.mockRestore();
+	} );
+
+	test( 'paints a zero as an empty cell, still announcing its value', () => {
+		renderChart();
+		const zero = screen.getByRole( 'gridcell', { name: 'W2: 0' } );
+
+		expect( zero ).not.toHaveClass( 'heatmap-chart__cell--filled' );
+		expect( zero.style.getPropertyValue( '--a8c-charts-heatmap-cell-intensity' ) ).toBe( '' );
+		expect( screen.getByRole( 'gridcell', { name: 'W1: 1' } ) ).toHaveClass(
+			'heatmap-chart__cell--filled'
+		);
+	} );
+
+	test( 'puts the lowest non-zero value on the lowest step', () => {
+		renderChart();
+		const lowest = screen.getByRole( 'gridcell', { name: 'W1: 1' } );
+
+		expect( lowest.style.getPropertyValue( '--a8c-charts-heatmap-cell-intensity' ) ).toBe( '0' );
+	} );
+
 	test( 'falls back to the first palette slot when no primaryColor prop is set', () => {
 		const scope = document.createElement( 'div' );
 		scope.style.setProperty( '--a8c-charts-color-series-1', '#0a0b0c' );
@@ -469,9 +584,9 @@ const mockRects = () =>
 	} );
 
 describe( 'HeatmapChart value text contrast', () => {
-	// Extent 0..100, so each value is its own intensity in hundredths.
+	// The low end, a mid-tone, and the high end of the scale.
 	const scale: HeatmapColumn[] = [
-		{ label: 'W1', data: [ { value: 0 }, { value: 85 }, { value: 100 } ] },
+		{ label: 'W1', data: [ { value: 1 }, { value: 30 }, { value: 100 } ] },
 	];
 
 	let injectedStyle: HTMLStyleElement | null = null;
@@ -497,14 +612,14 @@ describe( 'HeatmapChart value text contrast', () => {
 	test( 'picks the label role that reaches AA on light and dark cells', () => {
 		renderScale();
 
-		expect( screen.getByText( '0' ) ).toHaveClass( 'heatmap-chart__cell-value', { exact: true } );
+		expect( screen.getByText( '1' ) ).toHaveClass( 'heatmap-chart__cell-value', { exact: true } );
 		expect( screen.getByText( '100' ) ).toHaveClass( 'heatmap-chart__cell-value--inverse' );
 	} );
 
 	test( 'falls back to black on a mid-tone cell where neither role reaches AA', () => {
 		renderScale();
 
-		expect( screen.getByText( '85' ) ).toHaveClass( 'heatmap-chart__cell-value--black' );
+		expect( screen.getByText( '30' ) ).toHaveClass( 'heatmap-chart__cell-value--black' );
 	} );
 
 	test( 'reads the label roles once data arrives after an empty first render', () => {
@@ -542,7 +657,7 @@ describe( 'HeatmapChart value text contrast', () => {
 
 		renderScale( 'translucent-heatmap' );
 
-		expect( screen.getByText( '0' ) ).toHaveClass( 'heatmap-chart__cell-value--black' );
+		expect( screen.getByText( '1' ) ).toHaveClass( 'heatmap-chart__cell-value--black' );
 		expect( screen.getByText( '100' ) ).toHaveClass( 'heatmap-chart__cell-value--inverse' );
 	} );
 
@@ -565,7 +680,7 @@ describe( 'HeatmapChart value text contrast', () => {
 		);
 
 		expect( screen.getByText( '7' ) ).toHaveClass( 'heatmap-chart__cell-value', { exact: true } );
-		expect( screen.getByText( '0' ) ).toHaveClass( 'heatmap-chart__cell-value--inverse' );
+		expect( screen.getByText( '1' ) ).toHaveClass( 'heatmap-chart__cell-value--inverse' );
 	} );
 
 	test( "keeps one color when both label roles are set to it on the chart's own class", () => {
@@ -576,7 +691,7 @@ describe( 'HeatmapChart value text contrast', () => {
 
 		renderScale( 'pinned-heatmap' );
 
-		[ '0', '85', '100' ].forEach( value =>
+		[ '1', '30', '100' ].forEach( value =>
 			expect( screen.getByText( value ) ).toHaveClass( 'heatmap-chart__cell-value', {
 				exact: true,
 			} )
@@ -851,6 +966,114 @@ describe( 'HeatmapChart column groups', () => {
 	} );
 } );
 
+describe( 'HeatmapChart fitCells', () => {
+	const threeMonths = Array.from( { length: 6 }, ( _, index ) => ( {
+		data: [ { value: index }, { value: index + 1 } ],
+	} ) );
+	const columnGroups = [
+		{ label: 'Jan', span: 2 },
+		{ label: 'Feb', span: 2 },
+		{ label: 'Mar', span: 2 },
+	];
+
+	let widthSpy: jest.SpyInstance;
+	let heightSpy: jest.SpyInstance;
+
+	beforeEach( () => {
+		widthSpy = jest.spyOn( Element.prototype, 'clientWidth', 'get' ).mockReturnValue( 400 );
+		heightSpy = jest.spyOn( Element.prototype, 'clientHeight', 'get' ).mockReturnValue( 400 );
+	} );
+
+	afterEach( () => {
+		widthSpy.mockRestore();
+		heightSpy.mockRestore();
+	} );
+
+	test( 'wraps the groups that fit better on a second band below the first, cells grown to match', () => {
+		renderChart( { data: threeMonths, columnGroups, compact: true, fitCells: true } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		expect( grid.style.getPropertyValue( '--a8c-charts-dimension-heatmap-cell-size' ) ).toBe(
+			'91px'
+		);
+		const [ , feb, mar ] = screen.getAllByTestId( 'heatmap-group-label' );
+		expect( feb ).toHaveStyle( { gridColumn: '5 / span 2', gridRow: '3' } );
+		// Band one takes rows 1-2, its labels 3 and the gap 4, so band two's labels sit on 7.
+		expect( mar ).toHaveStyle( { gridColumn: '2 / span 2', gridRow: '7' } );
+		const marchCell = screen
+			.getAllByTestId( 'heatmap-cell' )
+			.find( element => element.dataset.column === '4' && element.dataset.row === '0' );
+		expect( marchCell ).toHaveStyle( { gridColumn: '2', gridRow: '5' } );
+	} );
+
+	test( 'keeps the theme size, with a warning, when a column is a summary', () => {
+		renderChart( {
+			data: [
+				...threeMonths,
+				{ label: 'Total', summary: true, data: [ { value: 1 }, { value: 2 } ] },
+			],
+			columnGroups,
+			compact: true,
+			fitCells: true,
+		} );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		expect( grid.style.getPropertyValue( '--a8c-charts-dimension-heatmap-cell-size' ) ).toBe(
+			'11px'
+		);
+		expect( console ).toHaveWarned();
+	} );
+
+	test( 'leaves the grid the box less the content beside it', () => {
+		const offsetHeight = jest
+			.spyOn( HTMLElement.prototype, 'offsetHeight', 'get' )
+			.mockImplementation( function ( this: HTMLElement ) {
+				return this.dataset.testid === 'beside-grid' ? 100 : 0;
+			} );
+		try {
+			renderChart( {
+				data: threeMonths,
+				columnGroups,
+				compact: true,
+				fitCells: true,
+				children: <div data-testid="beside-grid" />,
+			} );
+			const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+			expect( grid.style.getPropertyValue( '--a8c-charts-dimension-heatmap-cell-size' ) ).toBe(
+				'66px'
+			);
+		} finally {
+			offsetHeight.mockRestore();
+		}
+	} );
+
+	test( 'refits within the resize delivery, before later observers read the grid', () => {
+		const observers: ResizeObserverCallback[] = [];
+		const original = window.ResizeObserver;
+		window.ResizeObserver = class {
+			constructor( private callback: ResizeObserverCallback ) {}
+			observe() {
+				observers.push( this.callback );
+			}
+			unobserve() {}
+			disconnect() {}
+		} as unknown as typeof ResizeObserver;
+		try {
+			renderChart( { data: threeMonths, columnGroups, compact: true, fitCells: true } );
+			const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+			heightSpy.mockReturnValue( 100 );
+			let cellSize = '';
+			act( () => {
+				observers.forEach( callback => callback( [], {} as ResizeObserver ) );
+				cellSize = grid.style.getPropertyValue( '--a8c-charts-dimension-heatmap-cell-size' );
+			} );
+			expect( cellSize ).toBe( '48px' );
+			const [ , , mar ] = screen.getAllByTestId( 'heatmap-group-label' );
+			expect( mar ).toHaveStyle( { gridRow: '3' } );
+		} finally {
+			window.ResizeObserver = original;
+		}
+	} );
+} );
+
 describe( 'HeatmapChart calendar navigation', () => {
 	const calendar = ( range: { start: string; end: string }, days: string[] ) =>
 		buildMonthCalendarHeatmapData(