@automattic/charts 4.7.0 → 4.9.0

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

@@ -3,6 +3,12 @@
 // 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))));
+
 .heatmap-chart {
 	position: relative;
 	// Keeps the tooltip's z-index inside the chart, as `.xy-plot` does.
@@ -92,9 +98,9 @@ $focus-ring-width: var(--wpds-border-width-focus);
 
 // 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);
@@ -115,7 +121,7 @@ $focus-ring-width: var(--wpds-border-width-focus);
 	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
@@ -165,10 +171,8 @@ $focus-ring-width: var(--wpds-border-width-focus);
 	margin-inline-end: var(--a8c-charts-dimension-heatmap-cell-gap, var(--wpds-dimension-gap-xs));
 }
 
-// Floor the mix at 15% so the lowest value stays visibly tinted, distinct from
-// an empty cell.
 .heatmap-chart__cell--filled {
-	background: color-mix(in sRGB, var(--a8c-charts-color-heatmap-primary) calc((0.15 + 0.85 * var(--a8c-charts-heatmap-cell-intensity)) * 100%), var(--a8c-charts-color-background, #fff));
+	background: $heatmap-fill;
 }
 
 .heatmap-chart__cell--selected {
@@ -204,7 +208,11 @@ $focus-ring-width: var(--wpds-border-width-focus);
 	width: var(--wpds-dimension-size-3xs);
 	height: var(--wpds-dimension-size-3xs);
 	border-radius: var(--a8c-charts-border-radius-cell);
-	background: color-mix(in sRGB, var(--a8c-charts-color-heatmap-primary) calc((0.15 + 0.85 * var(--a8c-charts-heatmap-cell-intensity)) * 100%), var(--a8c-charts-color-background, #fff));
+	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.

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 {
@@ -13,12 +14,17 @@ import {
 	useGlobalChartsContext,
 	GlobalChartsContext,
 } from '../../providers';
-import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
+import {
+	BACKGROUND_FALLBACK,
+	CATALOG_POINTERS,
+} from '../../providers/chart-context/private/catalog-pointers';
 import { blendRgb, hexToRgb } from '../../providers/chart-context/private/perceptual-color';
+import { resolveOpaqueHex } from '../../providers/chart-context/private/resolve-opaque-hex';
 import { useStandaloneScopeClass } from '../../providers/chart-scope';
 import { attachSubComponents } from '../../utils';
 import { isValidHexColor, normalizeColorToHex } from '../../utils/color-utils';
-import { createCssVariableResolver, resolveCssVariable } from '../../utils/resolve-css-var';
+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';
@@ -27,12 +33,16 @@ 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,
 	HeatmapContext,
 	HeatmapLegend,
+	isEmptyValue,
 	isPresent,
 	resolveColumnGroups,
+	wrapColumnGroups,
 } from './private';
 import {
 	firstCalendarCell,
@@ -41,17 +51,13 @@ 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';
 import type { ResponsiveConfig } from '../private/with-responsive';
 import type { CSSProperties, FC } from 'react';
 
-// Mirrors the color-mix floor in heatmap-chart.module.scss (.heatmap-chart__cell--filled):
-// the rendered fill is the primary mixed over the chart background at 0.15 + 0.85 * intensity.
-const CELL_MIX_FLOOR = 0.15;
-
 // `label` is the stylesheet's default, so it needs no modifier.
 const CELL_VALUE_MODIFIER: Record< LabelTextColor, string | undefined > = {
 	label: undefined,
@@ -66,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 ||
@@ -78,6 +105,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	height = 0,
 	className,
 	compact = false,
+	fitCells = false,
 	showValues,
 	maxCellWidth,
 	maxCellHeight,
@@ -108,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( {
@@ -125,29 +148,37 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		overrideColor: primaryColor,
 	} );
 
-	// The cell blend substitutes this role at the cell; this read happens at the scope
-	// element, so an override on the chart's own class makes the two disagree. CHARTS-255.
-	const chartBackgroundHex = normalizeColorToHex(
-		CATALOG_POINTERS.background,
-		scopeElement,
-		resolveCssVariable
-	);
+	// Both read at the scope element, so an override on the chart's own class reaches neither the
+	// fill scale nor the text color (CHARTS-255). See-through counts as white, as for the palette.
+	const resolveAtScope = createCssVariableResolver( scopeElement );
+	const chartBackgroundHex =
+		resolveOpaqueHex( CATALOG_POINTERS.background, resolveAtScope ) ?? BACKGROUND_FALLBACK;
+	const emptyCellHex = resolveOpaqueHex( CATALOG_POINTERS.track, resolveAtScope );
 
-	// Choose text color from the blended fill, not the raw value.
-	// If either color cannot resolve to hex, keep the stylesheet's default role.
+	// If the primary cannot resolve to hex, the stylesheet falls back to its own blend.
 	const primaryHex = normalizeColorToHex( primaryColorHex );
-	const cellMix =
-		isValidHexColor( primaryHex ) && isValidHexColor( chartBackgroundHex )
-			? { primary: hexToRgb( primaryHex ), background: hexToRgb( chartBackgroundHex ) }
-			: null;
+	const scale = useMemo(
+		() =>
+			isValidHexColor( primaryHex )
+				? getHeatmapScale( primaryHex, chartBackgroundHex, emptyCellHex )
+				: null,
+		[ primaryHex, chartBackgroundHex, emptyCellHex ]
+	);
+	const fillVars = useMemo(
+		() => ( {
+			'--a8c-charts-color-heatmap-primary': primaryColorHex,
+			...( scale && {
+				'--a8c-charts-color-heatmap-low': scale.low,
+				'--a8c-charts-color-heatmap-high': scale.high,
+			} ),
+		} ),
+		[ primaryColorHex, scale ]
+	);
+	// Choose text color from the fill the cell paints, mirroring .heatmap-chart__cell--filled.
 	const cellTextColor = ( intensity: number ): LabelTextColor =>
-		cellMix
+		scale
 			? pickLabelTextColorForFill(
-					blendRgb(
-						cellMix.primary,
-						cellMix.background,
-						CELL_MIX_FLOOR + ( 1 - CELL_MIX_FLOOR ) * intensity
-					),
+					blendRgb( hexToRgb( scale.high ), hexToRgb( scale.low ), intensity ),
 					labelRoles,
 					'label'
 				)
@@ -165,8 +196,8 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 
 	const extent = useMemo( () => getValueExtent( data ), [ data ] );
 	const heatmapContext = useMemo< HeatmapContextValue >(
-		() => ( { extent, primaryColorHex } ),
-		[ extent, primaryColorHex ]
+		() => ( { extent, fillVars } ),
+		[ extent, fillVars ]
 	);
 
 	const columns = data.length;
@@ -179,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 => {
@@ -366,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
@@ -382,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 > = {
-		'--a8c-charts-color-heatmap-primary': primaryColorHex,
+		...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
@@ -435,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,
 					} ) }
@@ -465,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 ),
@@ -483,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 }` }
@@ -491,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
@@ -542,7 +659,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 										const value = cell?.value ?? null;
 										const present = isPresent( value );
 										// A summary cell is on another scale, so it takes no fill.
-										const filled = present && ! column.summary;
+										const filled = present && ! column.summary && ! isEmptyValue( value, extent );
 										const normalized = filled ? getNormalizedValue( value, extent ) : 0;
 										const info = buildTooltipData( columnIndex, rowIndex );
 										const accessibleLabel = `${ cellName( info ) }: ${
@@ -601,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-context.ts

@@ -2,8 +2,8 @@ import { createContext } from 'react';
 
 export type HeatmapContextValue = {
 	extent: [ number, number ];
-	/** The resolved primary color (full intensity); the legend mixes toward it in CSS. */
-	primaryColorHex: string;
+	/** The custom properties the fill reads, set on the grid and on each legend swatch. */
+	fillVars: Record< string, string >;
 };
 
 /** Shared by the chart and legend without importing back from `heatmap-chart.tsx`. */