@automattic/charts 4.8.0 → 4.10.0

package/src/charts/conversion-funnel-chart/test/conversion-funnel-chart.test.tsx

@@ -3,6 +3,11 @@ import userEvent from '@testing-library/user-event';
 import ConversionFunnelChart from '../conversion-funnel-chart';
 import type { FunnelStep } from '../types';
 
+let mockChartHeight = 0;
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ jest.fn(), 500, mockChartHeight ],
+} ) );
+
 // Mock data for testing
 const mockSteps: FunnelStep[] = [
 	{
@@ -42,6 +47,10 @@ const renderWithoutTheme = ( component: React.ReactElement ) => {
 };
 
 describe( 'ConversionFunnelChart', () => {
+	afterEach( () => {
+		mockChartHeight = 0;
+	} );
+
 	describe( 'Basic Rendering', () => {
 		it( 'renders the main conversion rate', () => {
 			renderWithoutTheme( <ConversionFunnelChart { ...defaultProps } /> );
@@ -116,6 +125,19 @@ describe( 'ConversionFunnelChart', () => {
 				height: '250px',
 			} );
 		} );
+
+		it.each( [
+			[ 'unmeasured', 0, 'xl' ],
+			[ 'short', 120, 'sm' ],
+			[ 'tall', 320, 'xl' ],
+		] )( 'spaces a %s (%ipx) chart with the %s gap', ( _, height, gap ) => {
+			mockChartHeight = height;
+			renderWithoutTheme( <ConversionFunnelChart { ...defaultProps } /> );
+
+			expect( screen.getByTestId( 'conversion-funnel-chart' ).style.gap ).toContain(
+				`gap-${ gap }`
+			);
+		} );
 	} );
 
 	describe( 'Empty State', () => {

package/src/charts/conversion-funnel-chart/types.ts

@@ -59,7 +59,7 @@ export interface TooltipRenderProps {
  */
 export interface ConversionFunnelChartProps extends Pick<
 	BaseChartProps,
-	'className' | 'chartId' | 'animation'
+	'className' | 'chartId' | 'animation' | 'ariaLabel'
 > {
 	/** Main conversion rate to highlight */
 	mainRate: number;

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

@@ -126,6 +126,7 @@ function normalizeGeoChartError( eventArgs: unknown ): GeoChartError {
  *
  * @param props                   - The props for the GeoChart component
  * @param props.data              - Data in Google Charts format (array of arrays with headers)
+ * @param props.ariaLabel         - Accessible name of the chart
  * @param props.width             - Width of the chart in pixels
  * @param props.height            - Height of the chart in pixels
  * @param props.region            - Region to display ('world', 'US', or ISO 3166-1 alpha-2 code)
@@ -140,6 +141,7 @@ function normalizeGeoChartError( eventArgs: unknown ): GeoChartError {
 const GeoChartInternal: FC< GeoChartProps > = ( {
 	className,
 	data,
+	ariaLabel,
 	width,
 	height,
 	region = 'world',
@@ -289,12 +291,23 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 		]
 	);
 
-	const chartEvents = useMemo< ReactGoogleChartEvent[] | undefined >( () => {
+	const chartEvents = useMemo< ReactGoogleChartEvent[] >( () => {
+		const readyEvent: ReactGoogleChartEvent = {
+			eventName: 'ready',
+			// Google hardcodes aria-label="A chart." on its SVG, which repeats the chart's own name.
+			callback: () => {
+				containerRef.current
+					?.querySelectorAll( 'svg' )
+					.forEach( svg => svg.setAttribute( 'aria-hidden', 'true' ) );
+			},
+		};
+
 		if ( ! onError ) {
-			return undefined;
+			return [ readyEvent ];
 		}
 
 		return [
+			readyEvent,
 			{
 				eventName: 'error',
 				callback: ( { eventArgs } ) => {
@@ -307,6 +320,8 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 	return (
 		<Center
 			ref={ containerRef }
+			role="group"
+			aria-label={ ariaLabel ?? __( 'Geo chart', 'jetpack-charts' ) }
 			className={ clsx( 'geo-chart', styles.container, className ) }
 			data-testid="geo-chart"
 			style={ { width, height } }

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

@@ -281,13 +281,18 @@ describe( 'GeoChart', () => {
 	} );
 
 	describe( 'Chart Events', () => {
-		test( 'does not pass chart events when onError is omitted', () => {
+		test( "hides Google's own SVG label from screen readers once the map is ready", () => {
 			renderWithTheme();
 
-			const chartEvents = screen.getByTestId( 'chart-events' );
-			const events = JSON.parse( chartEvents.textContent || '[]' );
+			const svg = document.createElementNS( 'http://www.w3.org/2000/svg', 'svg' );
+			screen.getByTestId( 'google-chart-mock' ).appendChild( svg );
 
-			expect( events ).toEqual( [] );
+			const chartProps = ChartMock.mock.calls[ ChartMock.mock.calls.length - 1 ]?.[ 0 ];
+			chartProps.chartEvents
+				.find( ( event: { eventName: string } ) => event.eventName === 'ready' )
+				.callback( {} );
+
+			expect( svg ).toHaveAttribute( 'aria-hidden', 'true' );
 		} );
 
 		test( 'calls onError when Google Charts emits an error', () => {

package/src/charts/geo-chart/types.ts

@@ -31,7 +31,7 @@ export interface GeoChartError {
 
 export interface GeoChartProps extends Pick<
 	BaseChartProps,
-	'className' | 'chartId' | 'width' | 'height'
+	'className' | 'chartId' | 'ariaLabel' | 'width' | 'height'
 > {
 	/**
 	 * Data in Google Charts native format for maximum flexibility.

package/src/charts/heatmap-chart/heatmap-chart.module.scss

@@ -3,6 +3,8 @@
 // module, so it needs no runtime cascade and never lands on the DOM.
 $focus-ring-width: var(--wpds-border-width-focus);
 
+$heatmap-empty-fill: var(--a8c-charts-color-track);
+
 // JS sets the ends (getHeatmapScale): 3:1 against background and empty cell at
 // the low end. Unresolved, the floor is 15% of the primary.
 $heatmap-fill: color-mix(in sRGB, var(--a8c-charts-color-heatmap-high, var(--a8c-charts-color-heatmap-primary)) calc(var(--a8c-charts-heatmap-cell-intensity) * 100%), var(--a8c-charts-color-heatmap-low, color-mix(in sRGB, var(--a8c-charts-color-heatmap-primary) 15%, var(--a8c-charts-color-background, #fff))));
@@ -96,9 +98,9 @@ $heatmap-fill: color-mix(in sRGB, var(--a8c-charts-color-heatmap-high, var(--a8c
 
 // Beneath its columns, set off from the last row by more than the cell gap.
 .heatmap-chart__group-label {
-	color: var(--a8c-charts-color-label-secondary);
-	font-size: var(--wpds-typography-font-size-xs);
-	line-height: var(--wpds-typography-line-height-xs);
+	color: var(--a8c-charts-color-label);
+	font-size: var(--wpds-typography-font-size-md);
+	line-height: var(--wpds-typography-line-height-sm);
 	white-space: nowrap;
 	text-align: center;
 	padding-block-start: var(--wpds-dimension-padding-xs);
@@ -119,7 +121,7 @@ $heatmap-fill: color-mix(in sRGB, var(--a8c-charts-color-heatmap-high, var(--a8c
 	min-height: 0;
 	border-radius: var(--a8c-charts-border-radius-cell);
 	// Empty (no-data) default; cells with a value override it below.
-	background: var(--a8c-charts-color-track);
+	background: $heatmap-empty-fill;
 }
 
 // An empty grid slot (calendar ragged edges): keeps its track but paints and
@@ -209,6 +211,10 @@ $heatmap-fill: color-mix(in sRGB, var(--a8c-charts-color-heatmap-high, var(--a8c
 	background: $heatmap-fill;
 }
 
+.heatmap-chart__legend-swatch--empty {
+	background: $heatmap-empty-fill;
+}
+
 // One band: the steps butt against each other and only the band's ends round.
 .heatmap-chart__legend-scale--bar {
 	overflow: hidden;

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