@automattic/charts 4.1.0 → 4.2.0

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

@@ -9,11 +9,21 @@ import type { CSSProperties, FC } from 'react';
 export interface HeatmapLegendProps {
 	/** Number of swatches in the scale. Default 5. */
 	steps?: number;
+	/**
+	 * `swatches` spaces the steps out as cell-sized squares; `bar` joins them
+	 * into one continuous band with rounded ends. Default `swatches`.
+	 */
+	variant?: 'swatches' | 'bar';
 	lessLabel?: string;
 	moreLabel?: string;
 }
 
-export const HeatmapLegend: FC< HeatmapLegendProps > = ( { steps = 5, lessLabel, moreLabel } ) => {
+export const HeatmapLegend: FC< HeatmapLegendProps > = ( {
+	steps = 5,
+	variant = 'swatches',
+	lessLabel,
+	moreLabel,
+} ) => {
 	const context = useContext( HeatmapContext );
 	const { legend } = useGlobalChartsTheme();
 	if ( ! context ) {
@@ -31,13 +41,19 @@ export const HeatmapLegend: FC< HeatmapLegendProps > = ( { steps = 5, lessLabel,
 			>
 				{ lessLabel ?? __( 'Less', 'jetpack-charts' ) }
 			</Text>
-			<Stack direction="row" gap="xs">
+			<Stack
+				direction="row"
+				gap={ variant === 'bar' ? undefined : 'xs' }
+				aria-hidden="true"
+				data-testid="heatmap-legend-scale"
+				className={ variant === 'bar' ? styles[ 'heatmap-chart__legend-scale--bar' ] : undefined }
+			>
 				{ Array.from( { length: steps }, ( _, index ) => {
 					const intensity = steps <= 1 ? 1 : index / ( steps - 1 );
 					return (
 						<span
 							key={ index }
-							aria-hidden="true"
+							data-testid="heatmap-legend-swatch"
 							className={ styles[ 'heatmap-chart__legend-swatch' ] }
 							style={
 								{

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

@@ -1,7 +1,7 @@
 export { getValueExtent, getNormalizedValue, isPresent } from './use-heatmap-colors';
-export { buildCalendarHeatmapData } from './build-calendar-data';
 export { HeatmapLegend } from './heatmap-legend';
 export { HeatmapContext } from './heatmap-context';
-export type { CalendarHeatmapOptions, CalendarHeatmapResult } from './build-calendar-data';
 export type { HeatmapLegendProps } from './heatmap-legend';
 export type { HeatmapContextValue } from './heatmap-context';
+export { resolveColumnGroups } from './column-groups';
+export type { ColumnGroupLayout } from './column-groups';

package/src/charts/heatmap-chart/private/keyboard-navigation.ts

@@ -0,0 +1,201 @@
+export type CellPosition = { column: number; row: number };
+
+export type NavigationKey =
+	'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown' | 'PageUp' | 'PageDown';
+
+/** A run of columns read as one page in calendar navigation; `end` is exclusive. */
+export type CellBlock = { start: number; end: number };
+
+export type NavigableGrid = {
+	columns: number;
+	rows: number;
+	/** Whether the slot holds nothing to select (hidden or placeholder). */
+	isInert: ( column: number, row: number ) => boolean;
+};
+
+const ARROW_KEYS = [ 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown' ];
+const PAGE_KEYS = [ 'PageUp', 'PageDown' ];
+
+export const isNavigationKey = ( key: string, mode: 'grid' | 'calendar' ): key is NavigationKey =>
+	ARROW_KEYS.includes( key ) || ( mode === 'calendar' && PAGE_KEYS.includes( key ) );
+
+const inGrid = ( grid: NavigableGrid, { column, row }: CellPosition ) =>
+	column >= 0 && column < grid.columns && row >= 0 && row < grid.rows;
+
+const firstSelectable = ( grid: NavigableGrid, cells: CellPosition[] ) =>
+	cells.find( cell => inGrid( grid, cell ) && ! grid.isInert( cell.column, cell.row ) );
+
+/**
+ * Column-major scan for the first selectable cell.
+ *
+ * @param grid - The grid.
+ * @return The cell, or undefined when every slot is inert.
+ */
+export const firstGridCell = ( grid: NavigableGrid ): CellPosition | undefined => {
+	for ( let column = 0; column < grid.columns; column++ ) {
+		for ( let row = 0; row < grid.rows; row++ ) {
+			if ( ! grid.isInert( column, row ) ) {
+				return { column, row };
+			}
+		}
+	}
+	return undefined;
+};
+
+/**
+ * Steps across the grid in the key's direction, past inert slots, staying put at the edge.
+ *
+ * @param grid - The grid.
+ * @param from - The selected cell.
+ * @param key  - The arrow key.
+ * @return The next cell, or undefined to keep the selection.
+ */
+export const stepGridCell = (
+	grid: NavigableGrid,
+	from: CellPosition,
+	key: NavigationKey
+): CellPosition | undefined => {
+	const steps: Partial< Record< NavigationKey, [ number, number ] > > = {
+		ArrowRight: [ 1, 0 ],
+		ArrowLeft: [ -1, 0 ],
+		ArrowDown: [ 0, 1 ],
+		ArrowUp: [ 0, -1 ],
+	};
+	const step = steps[ key ];
+	if ( ! step ) {
+		return undefined;
+	}
+	const [ stepColumn, stepRow ] = step;
+
+	let cell = from;
+	do {
+		cell = { column: cell.column + stepColumn, row: cell.row + stepRow };
+	} while ( inGrid( grid, cell ) && grid.isInert( cell.column, cell.row ) );
+
+	return inGrid( grid, cell ) ? cell : undefined;
+};
+
+/**
+ * Every slot of the blocks in reading order: block by block, each a row at a time.
+ *
+ * @param grid   - The grid.
+ * @param blocks - The blocks, left to right.
+ * @return The slots in order.
+ */
+const readingOrder = ( grid: NavigableGrid, blocks: CellBlock[] ): CellPosition[] =>
+	blocks.flatMap( block =>
+		Array.from( { length: grid.rows }, ( _row, row ) =>
+			Array.from( { length: block.end - block.start }, ( _offset, offset ) => ( {
+				column: block.start + offset,
+				row,
+			} ) )
+		).flat()
+	);
+
+const blockOf = ( blocks: CellBlock[], column: number ) =>
+	blocks.findIndex( block => column >= block.start && column < block.end );
+
+/**
+ * The slots after a cell down its column (or before it, going up), continuing at the
+ * same column offset of each following block.
+ *
+ * @param grid      - The grid.
+ * @param blocks    - The blocks, left to right.
+ * @param from      - The selected cell.
+ * @param direction - 1 downwards, -1 upwards.
+ * @return The slots in order.
+ */
+const columnOrderFrom = (
+	grid: NavigableGrid,
+	blocks: CellBlock[],
+	from: CellPosition,
+	direction: 1 | -1
+): CellPosition[] => {
+	const blockIndex = blockOf( blocks, from.column );
+	if ( blockIndex < 0 ) {
+		return [];
+	}
+	const offset = from.column - blocks[ blockIndex ].start;
+	const cells: CellPosition[] = [];
+	const pushRows = ( column: number, startRow: number ) => {
+		for ( let row = startRow; row >= 0 && row < grid.rows; row += direction ) {
+			cells.push( { column, row } );
+		}
+	};
+
+	pushRows( from.column, from.row + direction );
+	for (
+		let index = blockIndex + direction;
+		index >= 0 && index < blocks.length;
+		index += direction
+	) {
+		const column = blocks[ index ].start + offset;
+		if ( column < blocks[ index ].end ) {
+			pushRows( column, direction === 1 ? 0 : grid.rows - 1 );
+		}
+	}
+	return cells;
+};
+
+/**
+ * The first selectable cell in calendar reading order.
+ *
+ * @param grid   - The grid.
+ * @param blocks - The blocks, left to right.
+ * @return The cell, or undefined when every slot is inert.
+ */
+export const firstCalendarCell = ( grid: NavigableGrid, blocks: CellBlock[] ) =>
+	firstSelectable( grid, readingOrder( grid, blocks ) );
+
+/**
+ * Steps through the blocks as pages of a calendar: Left/Right by one slot in reading
+ * order, Up/Down by one row (into the neighboring block past the edge), Page Up/Down
+ * to the same slot of the neighboring block or its nearest selectable cell.
+ *
+ * @param grid   - The grid.
+ * @param blocks - The blocks, left to right.
+ * @param from   - The selected cell.
+ * @param key    - The navigation key.
+ * @return The next cell, or undefined to keep the selection.
+ */
+export const stepCalendarCell = (
+	grid: NavigableGrid,
+	blocks: CellBlock[],
+	from: CellPosition,
+	key: NavigationKey
+): CellPosition | undefined => {
+	if ( key === 'ArrowRight' || key === 'ArrowLeft' ) {
+		const order = readingOrder( grid, blocks );
+		const index = order.findIndex( cell => cell.column === from.column && cell.row === from.row );
+		if ( index < 0 ) {
+			return undefined;
+		}
+		const ahead =
+			key === 'ArrowRight' ? order.slice( index + 1 ) : order.slice( 0, index ).reverse();
+		return firstSelectable( grid, ahead );
+	}
+
+	if ( key === 'ArrowDown' || key === 'ArrowUp' ) {
+		return firstSelectable(
+			grid,
+			columnOrderFrom( grid, blocks, from, key === 'ArrowDown' ? 1 : -1 )
+		);
+	}
+
+	const blockIndex = blockOf( blocks, from.column );
+	const target = blocks[ blockIndex + ( key === 'PageDown' ? 1 : -1 ) ];
+	if ( blockIndex < 0 || ! target ) {
+		return undefined;
+	}
+	const same = {
+		column: target.start + ( from.column - blocks[ blockIndex ].start ),
+		row: from.row,
+	};
+	const page = readingOrder( grid, [ target ] );
+	const at = page.findIndex(
+		cell => cell.row > same.row || ( cell.row === same.row && cell.column >= same.column )
+	);
+	const after = at === -1 ? [] : page.slice( at );
+	const before = page.slice( 0, at === -1 ? page.length : at ).reverse();
+	return firstSelectable( grid, after ) ?? firstSelectable( grid, before );
+};

package/src/charts/heatmap-chart/test/build-calendar-data.test.ts

@@ -1,4 +1,4 @@
-import { buildCalendarHeatmapData } from '../private/build-calendar-data';
+import { buildCalendarHeatmapData } from '../build-calendar-data';
 import type { DataPointDate } from '../../../types';
 
 const series: DataPointDate[] = [
@@ -269,4 +269,40 @@ describe( 'buildCalendarHeatmapData with a grid wider than the series', () => {
 		expect( data[ 0 ].data[ 0 ].hidden ).toBe( true );
 		expect( data[ 0 ].data[ 0 ].placeholder ).toBeUndefined();
 	} );
+
+	test( 'labels Gregorian months under a locale whose default calendar is not Gregorian', () => {
+		// fa-IR defaults to the Persian calendar, under which Sep 1 and Sep 30 fall in different months.
+		const september: DataPointDate[] = [
+			{ dateString: '2026-09-01', value: 1 },
+			{ dateString: '2026-09-30', value: 1 },
+		];
+		const { data } = buildCalendarHeatmapData( september, { weekStartsOn: 1, locale: 'fa-IR' } );
+
+		const gregorianMonth = new Intl.DateTimeFormat( 'fa-IR', {
+			month: 'short',
+			calendar: 'gregory',
+			timeZone: 'UTC',
+		} );
+		const gregorianDay = new Intl.DateTimeFormat( 'fa-IR', {
+			weekday: 'short',
+			month: 'short',
+			day: 'numeric',
+			year: 'numeric',
+			calendar: 'gregory',
+			timeZone: 'UTC',
+		} );
+
+		// The grid opens on Mon Aug 31, whose one-week month goes unlabeled, so the
+		// month label sits on the first September-starting column.
+		expect( data.map( column => column.label ).filter( Boolean ) ).toEqual( [
+			gregorianMonth.format( new Date( '2026-09-01T00:00:00Z' ) ),
+		] );
+		// Tue Sep 1 is column 0 row 1; Wed Sep 30 is column 4 row 2.
+		expect( data[ 0 ].data[ 1 ].label ).toBe(
+			gregorianDay.format( new Date( '2026-09-01T00:00:00Z' ) )
+		);
+		expect( data[ 4 ].data[ 2 ].label ).toBe(
+			gregorianDay.format( new Date( '2026-09-30T00:00:00Z' ) )
+		);
+	} );
 } );

package/src/charts/heatmap-chart/test/build-month-calendar-data.test.ts

@@ -0,0 +1,194 @@
+import { buildMonthCalendarHeatmapData } from '../build-month-calendar-data';
+
+const range = { start: '2026-08-01', end: '2026-09-14' };
+const cellAt = (
+	result: ReturnType< typeof buildMonthCalendarHeatmapData >,
+	month: number,
+	weekday: number,
+	week: number
+) => result.data[ month * 7 + weekday ].data[ week ];
+
+describe( 'buildMonthCalendarHeatmapData', () => {
+	test( 'draws one 7 × 6 block per month between the range ends', () => {
+		const { data, columnGroups } = buildMonthCalendarHeatmapData( {}, range, { locale: 'en-US' } );
+		expect( data ).toHaveLength( 14 );
+		data.forEach( column => {
+			expect( column.data ).toHaveLength( 6 );
+			expect( column.label ).toBeUndefined();
+		} );
+		expect( columnGroups ).toEqual( [
+			{ label: 'Aug', span: 7 },
+			{ label: 'Sep', span: 7 },
+		] );
+	} );
+
+	test( 'orders weekdays from Monday by default and from Sunday on request', () => {
+		// Aug 1 2026 is a Saturday.
+		const monday = buildMonthCalendarHeatmapData( { '2026-08-01': 1 }, range );
+		expect( cellAt( monday, 0, 5, 0 ).value ).toBe( 1 );
+		expect( cellAt( monday, 0, 0, 0 ).hidden ).toBe( true );
+
+		const sunday = buildMonthCalendarHeatmapData( { '2026-08-01': 1 }, range, { weekStartsOn: 0 } );
+		expect( cellAt( sunday, 0, 6, 0 ).value ).toBe( 1 );
+	} );
+
+	test( 'hides days outside the month and the rows past its last week', () => {
+		const result = buildMonthCalendarHeatmapData( {}, range );
+		// Aug 2026 runs Sat 1 → Mon 31 and needs all six rows from Monday Jul 27.
+		expect( cellAt( result, 0, 4, 0 ).hidden ).toBe( true ); // Fri Jul 31
+		expect( cellAt( result, 0, 0, 5 ).hidden ).toBeUndefined(); // Mon Aug 31
+		expect( cellAt( result, 0, 1, 5 ).hidden ).toBe( true ); // Tue Sep 1
+		// Sep 2026 fits in five rows from Monday Aug 31, so its sixth row is overflow.
+		expect( cellAt( result, 1, 0, 0 ).hidden ).toBe( true ); // Mon Aug 31
+		expect( cellAt( result, 1, 2, 4 ).hidden ).toBeUndefined(); // Wed Sep 30
+		expect( cellAt( result, 1, 0, 5 ).hidden ).toBe( true ); // Mon Oct 5
+	} );
+
+	test( 'fades days inside a drawn month but outside the range as placeholders', () => {
+		const result = buildMonthCalendarHeatmapData( {}, range );
+		// Sep 14 2026 is a Monday: row 2 col 0. Tue Sep 15 is the first day past the range.
+		expect( cellAt( result, 1, 0, 2 ).placeholder ).toBeUndefined();
+		expect( cellAt( result, 1, 1, 2 ).placeholder ).toBe( true );
+		expect( cellAt( result, 1, 1, 2 ).hidden ).toBeUndefined();
+		expect( cellAt( result, 1, 2, 4 ).placeholder ).toBe( true ); // Wed Sep 30
+	} );
+
+	test( 'fades days before a mid-month start', () => {
+		const result = buildMonthCalendarHeatmapData( {}, { start: '2026-08-10', end: '2026-08-20' } );
+		expect( cellAt( result, 0, 5, 0 ).placeholder ).toBe( true ); // Sat Aug 1
+		expect( cellAt( result, 0, 0, 1 ).placeholder ).toBe( true ); // Mon Aug 3
+		expect( cellAt( result, 0, 0, 2 ).placeholder ).toBeUndefined(); // Mon Aug 10
+	} );
+
+	test( 'reads values by day and leaves missing days null', () => {
+		const result = buildMonthCalendarHeatmapData(
+			{ '2026-08-03': 4, '2026-08-04': NaN, '2026-08-05': null },
+			range
+		);
+		expect( cellAt( result, 0, 0, 1 ).value ).toBe( 4 );
+		expect( cellAt( result, 0, 1, 1 ).value ).toBeNull();
+		expect( cellAt( result, 0, 2, 1 ).value ).toBeNull();
+		expect( cellAt( result, 0, 3, 1 ).value ).toBeNull();
+	} );
+
+	test( 'labels every day with its full date in the locale', () => {
+		// Read from Intl rather than spelled out: short month names drift between ICU builds.
+		const monthLabels = ( locale: string ) => {
+			const format = new Intl.DateTimeFormat( locale, {
+				month: 'short',
+				calendar: 'gregory',
+				timeZone: 'UTC',
+			} );
+			return [ '2026-08-01', '2026-09-01' ].map( day =>
+				format.format( new Date( `${ day }T00:00:00Z` ) )
+			);
+		};
+		const result = buildMonthCalendarHeatmapData( {}, range, { locale: 'en-US' } );
+		expect( cellAt( result, 0, 0, 1 ).label ).toBe( 'Mon, Aug 3, 2026' );
+		for ( const locale of [ 'fr-FR', 'ja-JP' ] ) {
+			const { columnGroups } = buildMonthCalendarHeatmapData( {}, range, { locale } );
+			expect( columnGroups.map( group => group.label ) ).toEqual( monthLabels( locale ) );
+		}
+	} );
+
+	test( 'labels Gregorian months under a locale whose default calendar is not Gregorian', () => {
+		const result = buildMonthCalendarHeatmapData(
+			{},
+			{ start: '2026-09-01', end: '2026-09-30' },
+			{ locale: 'fa-IR' }
+		);
+		const gregorian = new Intl.DateTimeFormat( 'fa-IR', {
+			month: 'short',
+			calendar: 'gregory',
+			timeZone: 'UTC',
+		} );
+		expect( result.columnGroups ).toEqual( [
+			{ label: gregorian.format( new Date( '2026-09-01T00:00:00Z' ) ), span: 7 },
+		] );
+	} );
+
+	test( 'handles a leap February and a range inside one month', () => {
+		const leap = buildMonthCalendarHeatmapData( {}, { start: '2028-02-01', end: '2028-02-29' } );
+		expect( leap.data ).toHaveLength( 7 );
+		// Feb 29 2028 is a Tuesday in the fifth week row.
+		expect( cellAt( leap, 0, 1, 4 ).hidden ).toBeUndefined();
+		expect( cellAt( leap, 0, 2, 4 ).hidden ).toBe( true );
+	} );
+
+	test( 'spans a year boundary', () => {
+		const { columnGroups } = buildMonthCalendarHeatmapData(
+			{},
+			{ start: '2025-10-01', end: '2026-09-14' },
+			{ locale: 'en-US' }
+		);
+		expect( columnGroups.map( group => group.label ) ).toEqual( [
+			'Oct',
+			'Nov',
+			'Dec',
+			'Jan',
+			'Feb',
+			'Mar',
+			'Apr',
+			'May',
+			'Jun',
+			'Jul',
+			'Aug',
+			'Sep',
+		] );
+	} );
+
+	test( 'adds the year to the month labels once a range passes twelve months', () => {
+		const thirteen = buildMonthCalendarHeatmapData(
+			{},
+			{ start: '2025-09-15', end: '2026-09-14' },
+			{ locale: 'en-US' }
+		);
+		const labels = thirteen.columnGroups.map( group => group.label );
+		expect( labels ).toHaveLength( 13 );
+		expect( labels[ 0 ] ).toBe( 'Sep 2025' );
+		expect( labels[ 12 ] ).toBe( 'Sep 2026' );
+
+		const twelve = buildMonthCalendarHeatmapData(
+			{},
+			{ start: '2025-10-01', end: '2026-09-14' },
+			{ locale: 'en-US' }
+		);
+		expect( twelve.columnGroups[ 0 ].label ).toBe( 'Oct' );
+	} );
+
+	test.each( [
+		[ '2026-08-29', 5, 4 ], // Sat
+		[ '2026-08-30', 6, 4 ], // Sun
+		[ '2026-08-31', 0, 5 ], // Mon
+	] )( 'measures from a start on %s and fades the month before it', ( start, weekday, week ) => {
+		const result = buildMonthCalendarHeatmapData( { [ start ]: 2 }, { start, end: '2026-09-14' } );
+		expect( cellAt( result, 0, weekday, week ) ).toMatchObject( { value: 2 } );
+		expect( cellAt( result, 0, weekday, week ).placeholder ).toBeUndefined();
+		expect( cellAt( result, 0, 0, 1 ).placeholder ).toBe( true ); // Mon Aug 3
+	} );
+
+	test( 'keeps a placeholder empty even when the map holds a value for that day', () => {
+		const result = buildMonthCalendarHeatmapData( { '2026-09-20': 7 }, range );
+		// Sun Sep 20 2026 sits past the range end in row 2.
+		expect( cellAt( result, 1, 6, 2 ) ).toMatchObject( { value: null, placeholder: true } );
+	} );
+
+	test.each( [
+		[ 'an unparseable start', { start: '2026-8-1', end: '2026-09-14' } ],
+		[ 'an unparseable end', { start: '2026-08-01', end: 'today' } ],
+		[ 'an impossible day', { start: '2026-02-30', end: '2026-03-01' } ],
+		[ 'a reversed range', { start: '2026-09-14', end: '2026-08-01' } ],
+	] )( 'returns an empty grid and warns once on %s', ( _, badRange ) => {
+		expect( buildMonthCalendarHeatmapData( {}, badRange ) ).toEqual( {
+			data: [],
+			columnGroups: [],
+		} );
+		expect( console ).toHaveWarned();
+	} );
+
+	test( 'skips keys that are not yyyy-MM-dd with one warning', () => {
+		const result = buildMonthCalendarHeatmapData( { 'Aug 3 2026': 9, '2026-08-03': 4 }, range );
+		expect( cellAt( result, 0, 0, 1 ).value ).toBe( 4 );
+		expect( console ).toHaveWarned();
+	} );
+} );

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

@@ -0,0 +1,83 @@
+import { resolveColumnGroups } from '../private/column-groups';
+
+const lines = ( columns: { line: number }[] ) => columns.map( column => column.line );
+const gaps = ( columns: { gapBefore: boolean }[] ) => columns.map( column => column.gapBefore );
+
+describe( 'resolveColumnGroups', () => {
+	test( 'no groups: consecutive lines from the first, no gaps', () => {
+		const layout = resolveColumnGroups( undefined, 3, 2 );
+		expect( layout.groups ).toEqual( [] );
+		expect( lines( layout.columns ) ).toEqual( [ 2, 3, 4 ] );
+		expect( gaps( layout.columns ) ).toEqual( [ false, false, false ] );
+		expect( resolveColumnGroups( [], 2, 2 ).columns ).toHaveLength( 2 );
+	} );
+
+	test( 'no columns: no groups and no warning, whatever the spans', () => {
+		expect( resolveColumnGroups( [ { label: 'A', span: 3 } ], 0, 2 ) ).toEqual( {
+			columns: [],
+			groups: [],
+		} );
+		expect( console ).not.toHaveWarned();
+	} );
+
+	test( 'skips one line before the first column of every group but the first', () => {
+		const groups = [
+			{ label: 'A', span: 2 },
+			{ label: 'B', span: 1 },
+			{ label: 'C', span: 2 },
+		];
+		const layout = resolveColumnGroups( groups, 5, 2 );
+		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 },
+		] );
+		expect( layout.columns.map( column => column.group ) ).toEqual( [ 0, 0, 1, 2, 2 ] );
+	} );
+
+	test( 'leaves columns past the last group ungrouped and ungapped', () => {
+		const layout = resolveColumnGroups( [ { label: 'A', span: 2 } ], 4, 2 );
+		expect( lines( layout.columns ) ).toEqual( [ 2, 3, 4, 5 ] );
+		expect( gaps( layout.columns ) ).toEqual( [ false, false, false, false ] );
+		expect( layout.columns.map( column => column.group ) ).toEqual( [
+			0,
+			0,
+			undefined,
+			undefined,
+		] );
+	} );
+
+	test.each( [
+		[ 'zero', 0 ],
+		[ 'negative', -1 ],
+		[ 'fractional', 1.5 ],
+		[ 'NaN', NaN ],
+	] )( 'warns once and drops every group on a %s span', ( _, span ) => {
+		const layout = resolveColumnGroups(
+			[
+				{ label: 'A', span: 1 },
+				{ label: 'B', span },
+			],
+			4,
+			2
+		);
+		expect( layout.groups ).toEqual( [] );
+		expect( lines( layout.columns ) ).toEqual( [ 2, 3, 4, 5 ] );
+		expect( console ).toHaveWarned();
+	} );
+
+	test( 'warns once and drops every group when the spans reach past the last column', () => {
+		const layout = resolveColumnGroups(
+			[
+				{ label: 'A', span: 3 },
+				{ label: 'B', span: 2 },
+			],
+			4,
+			2
+		);
+		expect( layout.groups ).toEqual( [] );
+		expect( console ).toHaveWarned();
+	} );
+} );