@automattic/charts 4.0.0 → 4.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "4.0.0",
+	"version": "4.1.1",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -63,8 +63,9 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.2.8",
+		"@automattic/number-formatters": "^1.2.9",
 		"@babel/runtime": "7.29.7",
+		"@date-fns/tz": "1.4.1",
 		"@react-spring/web": "10.1.1",
 		"@visx/annotation": "^4.0.0",
 		"@visx/axis": "^4.0.0",
@@ -113,9 +114,9 @@
 		"@wordpress/components": "40.0.0",
 		"@wordpress/element": "8.6.0",
 		"@wordpress/private-apis": "1.54.0",
-		"babel-jest": "30.4.1",
+		"babel-jest": "30.5.1",
 		"identity-obj-proxy": "^3.0.0",
-		"jest": "30.4.2",
+		"jest": "30.5.1",
 		"jest-extended": "7.0.0",
 		"magic-string": "0.30.21",
 		"react": "18.3.1",

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

@@ -411,6 +411,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 
 						return (
 							<div
+								ref={ chartRef }
 								role="grid"
 								aria-label={ __( 'Area chart', 'jetpack-charts' ) }
 								tabIndex={ 0 }
@@ -419,7 +420,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 								onBlur={ onChartBlur }
 							>
 								{ chartHeight > 0 && (
-									<div ref={ chartRef } className={ plotStyles[ 'xy-plot' ] }>
+									<div className={ plotStyles[ 'xy-plot' ] }>
 										{ zoomable && zoom.domain && <ZoomResetButton onClick={ zoom.reset } /> }
 										<XYChart
 											theme={ theme }

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

@@ -52,6 +52,37 @@ describe( 'AreaChart', () => {
 		);
 	};
 
+	test.each( [ [ 'Escape', '{Escape}' ] ] )(
+		'returns focus to the grid after %s',
+		async ( _name, keys ) => {
+			jest.useFakeTimers();
+			try {
+				const user = userEvent.setup( { advanceTimers: jest.advanceTimersByTime } );
+				renderWithProvider();
+				const chart = screen.getByRole( 'grid', { name: /area chart/i } );
+
+				await user.tab();
+				expect( chart ).toHaveFocus();
+				await user.keyboard( '{ArrowRight}' );
+				expect( screen.getByRole( 'tooltip' ) ).toHaveFocus();
+
+				await user.keyboard( keys );
+				await act( async () => {
+					jest.advanceTimersByTime( 5000 );
+				} );
+				expect( chart ).toHaveFocus();
+				expect( screen.queryByRole( 'tooltip' ) ).not.toBeInTheDocument();
+
+				await user.keyboard( '{ArrowRight}' );
+				const tooltip = screen.getByRole( 'tooltip' );
+				expect( tooltip ).toHaveFocus();
+				expect( tooltip ).toHaveTextContent( 'Series A:10' );
+			} finally {
+				jest.useRealTimers();
+			}
+		}
+	);
+
 	describe( 'Data Validation', () => {
 		test( 'shows error when data is empty', () => {
 			renderWithProvider( { data: [] } );

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

@@ -0,0 +1,189 @@
+import { createDateFormatter, sanitizeFormatting } from '../../utils/date-formatting';
+import { warnOnce } from '../../utils/warn-once';
+import {
+	addCivilDays,
+	civilDate,
+	civilKey,
+	civilWeekSpan,
+	instantDayReader,
+	pointDayKey,
+	startOfCivilWeek,
+	writtenDayKey,
+} from './private/civil-day';
+import type { CivilDate, DayKey } from './private/civil-day';
+import type {
+	CalendarHeatmapOptions,
+	CalendarHeatmapResult,
+	HeatmapCell,
+	HeatmapColumn,
+} from './types';
+import type { DataPointDate } from '../../types';
+
+/** Rows that get a weekday label (Mon, Wed, Fri with a Monday week start). */
+const LABELLED_ROWS = [ 0, 2, 4 ];
+
+/**
+ * Resolve one grid bound: an unparseable or narrowing value falls back to the
+ * series' own bound, so the grid can only ever be widened.
+ *
+ * @param bound     - Requested bound as `yyyy-MM-dd`, if any.
+ * @param fallback  - The series' own bound on this side.
+ * @param direction - Which way the bound is allowed to move.
+ * @return The day key to draw to.
+ */
+const widenTo = (
+	bound: string | undefined,
+	fallback: DayKey,
+	direction: 'earlier' | 'later'
+): DayKey => {
+	const key = bound ? writtenDayKey( bound ) : null;
+	if ( ! key ) {
+		if ( bound ) {
+			warnOnce(
+				`heatmap:gridSpan:${ bound }`,
+				`gridSpan.${ direction === 'earlier' ? 'start' : 'end' } ${ JSON.stringify(
+					bound
+				) } is not a \`yyyy-MM-dd\` day, so the grid is drawn over the series' own span.`
+			);
+		}
+		return fallback;
+	}
+
+	if ( direction === 'earlier' ) {
+		return key < fallback ? key : fallback;
+	}
+
+	return key > fallback ? key : fallback;
+};
+
+/**
+ * Lay a day-bucketed series out as calendar columns.
+ *
+ * @param series  - Points to bucket.
+ * @param options - Grid shape, plus the locale and zone to read days in.
+ * @return Columns and row labels for `HeatmapChart`.
+ */
+export const buildCalendarHeatmapData = (
+	series: DataPointDate[],
+	options: CalendarHeatmapOptions = {}
+): CalendarHeatmapResult => {
+	const weekStartsOn = options.weekStartsOn ?? 1;
+	const hideOutOfRangeDays = options.hideOutOfRangeDays ?? true;
+
+	// The provider sanitizes what it holds, but this function is called outside it too.
+	const { locale, timeZone } = sanitizeFormatting( {
+		locale: options.locale,
+		timeZone: options.timeZone,
+	} );
+
+	const readInstant = instantDayReader( timeZone );
+
+	const valueByDay = new Map< DayKey, number | null >();
+	let minDayKey: DayKey | undefined;
+	let maxDayKey: DayKey | undefined;
+	for ( const point of series ) {
+		const key = pointDayKey( point, readInstant );
+		if ( ! key ) {
+			const offending = point.dateString ?? ( point.date && String( point.date ) );
+			warnOnce(
+				`heatmap:unreadableDate:${ offending }`,
+				offending
+					? `${ JSON.stringify(
+							offending
+					  ) } is not a day this can read, so its point is left out of the calendar. A \`dateString\` must start \`yyyy-MM-dd\`.`
+					: 'A point carries neither `date` nor `dateString`, so it is left out of the calendar.'
+			);
+			continue;
+		}
+
+		valueByDay.set( key, point.value );
+		// Day keys are fixed-width, so lexicographic order is chronological order.
+		if ( ! minDayKey || key < minDayKey ) {
+			minDayKey = key;
+		}
+		if ( ! maxDayKey || key > maxDayKey ) {
+			maxDayKey = key;
+		}
+	}
+
+	if ( ! minDayKey || ! maxDayKey ) {
+		return { data: [], rowLabels: [] };
+	}
+
+	const requestedMinDayKey = widenTo( options.gridSpan?.start, minDayKey, 'earlier' );
+	const gridMaxDayKey = widenTo( options.gridSpan?.end, maxDayKey, 'later' );
+
+	// Both are `DayKey`s, so they already round-tripped through `civilDate` once, and it
+	// is a pure function of the string: re-parsing them here cannot fail.
+	const requestedMinDate = civilDate( requestedMinDayKey ) as CivilDate;
+	const gridMaxDate = civilDate( gridMaxDayKey ) as CivilDate;
+
+	// The grid walks UTC proxies, so the label formatters read UTC. The host's zone
+	// was already spent on bucketing.
+	const labelFormatting = { locale, timeZone: 'UTC' };
+	const formatWeekday = createDateFormatter( { weekday: 'short' }, labelFormatting );
+	const formatMonth = createDateFormatter( { month: 'short' }, labelFormatting );
+	const formatDay = createDateFormatter(
+		{ weekday: 'short', month: 'short', day: 'numeric', year: 'numeric' },
+		labelFormatting
+	);
+
+	const gridStart = startOfCivilWeek( requestedMinDate, weekStartsOn );
+
+	// `gridStart` rounds a start bound down to its week; those days are filler like the
+	// rest of the widened span, not a ragged edge that would notch the first column.
+	const gridMinDayKey = requestedMinDayKey < minDayKey ? civilKey( gridStart ) : requestedMinDayKey;
+	const weekCount = civilWeekSpan( gridStart, gridMaxDate, weekStartsOn );
+
+	const rowLabels = Array.from( { length: 7 }, ( _, row ) =>
+		LABELLED_ROWS.includes( row ) ? formatWeekday( addCivilDays( gridStart, row ) ) : ''
+	);
+
+	// Hide short partial first-month labels when a later month follows; compact
+	// cells make adjacent labels collide. Keep the label for single-month ranges.
+	const MIN_FIRST_MONTH_WEEKS = 2;
+	const firstMonth = gridStart.getUTCMonth();
+	let firstMonthWeeks = 0;
+	while (
+		firstMonthWeeks < weekCount &&
+		addCivilDays( gridStart, firstMonthWeeks * 7 ).getUTCMonth() === firstMonth
+	) {
+		firstMonthWeeks++;
+	}
+	const spansLaterMonth = firstMonthWeeks < weekCount;
+	const showFirstMonthLabel = ! spansLaterMonth || firstMonthWeeks >= MIN_FIRST_MONTH_WEEKS;
+
+	const data: HeatmapColumn[] = [];
+	let previousMonth = -1;
+	for ( let week = 0; week < weekCount; week++ ) {
+		const columnStart = addCivilDays( gridStart, week * 7 );
+		const month = columnStart.getUTCMonth();
+		const isNewMonth = month !== previousMonth;
+		const label =
+			isNewMonth && ( week !== 0 || showFirstMonthLabel ) ? formatMonth( columnStart ) : '';
+		previousMonth = month;
+
+		const cells: HeatmapCell[] = [];
+		for ( let row = 0; row < 7; row++ ) {
+			const day = addCivilDays( gridStart, week * 7 + row );
+			const key = civilKey( day );
+			const cell: HeatmapCell = {
+				label: formatDay( day ),
+				value: valueByDay.has( key ) ? ( valueByDay.get( key ) as number | null ) : null,
+			};
+			if ( key < gridMinDayKey || key > gridMaxDayKey ) {
+				// The days completing the grid's first and last week: the ragged edge.
+				if ( hideOutOfRangeDays ) {
+					cell.hidden = true;
+				}
+			} else if ( key < minDayKey || key > maxDayKey ) {
+				// Inside the grid the caller asked for, outside the series: filler.
+				cell.placeholder = true;
+			}
+			cells.push( cell );
+		}
+		data.push( { label, data: cells } );
+	}
+
+	return { data, rowLabels };
+};

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

@@ -113,6 +113,37 @@ $focus-ring-width: var(--wpds-border-width-focus);
 	background: color-mix(in sRGB, var(--a8c-charts-color-track) 45%, transparent);
 }
 
+// A roll-up beside the grid, on another scale from it: no fill, its figure
+// always printed and emphasised.
+.heatmap-chart__cell--summary {
+	background: none;
+}
+
+.heatmap-chart__col-label--summary {
+	font-weight: var(--wpds-typography-font-weight-emphasis);
+}
+
+.heatmap-chart__cell--summary .heatmap-chart__cell-value {
+	font-weight: var(--wpds-typography-font-weight-emphasis);
+}
+
+// Compact rows are `compactCellSize` tall, so the figure shrinks to fit them.
+.heatmap-chart__grid--compact .heatmap-chart__cell--summary .heatmap-chart__cell-value {
+	font-size: var(--wpds-typography-font-size-xs);
+	line-height: 1;
+}
+
+// Deliberately on top of the grid gap: one extra gap sets a summary column
+// apart from the data beside it, on cells and label alike, and the auto track
+// grows by the same amount.
+.heatmap-chart__gap-start {
+	margin-inline-start: var(--a8c-charts-dimension-heatmap-cell-gap, var(--wpds-dimension-gap-xs));
+}
+
+.heatmap-chart__gap-end {
+	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 {

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

@@ -43,6 +43,10 @@ import type { CSSProperties, FC } from 'react';
 // the rendered fill is the primary mixed over the chart background at 0.15 + 0.85 * intensity.
 const CELL_MIX_FLOOR = 0.15;
 
+// One instance, not a `[]` default in the signature: `buildTooltipData` keys on
+// it, and a fresh array per render re-ran the keyboard tooltip effect endlessly.
+const NO_ROW_LABELS: string[] = [];
+
 const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	data,
 	chartId: providedChartId,
@@ -55,7 +59,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	maxCellHeight,
 	minCellWidth,
 	minCellHeight,
-	rowLabels = [],
+	rowLabels = NO_ROW_LABELS,
 	primaryColor,
 	gap = 'md',
 	withTooltips = false,
@@ -312,9 +316,18 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	const rowTrack = compact
 		? 'var(--a8c-charts-dimension-heatmap-cell-size)'
 		: `minmax(${ minCellHeight ?? 0 }px, ${ maxCellHeight ? `${ maxCellHeight }px` : '1fr' })`;
+	// 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
+	// `maxCellWidth`, where a plain `auto` would absorb it.
+	const columnTracks = data.some( column => column.summary )
+		? data
+				.map( column => ( column.summary ? 'minmax(auto, max-content)' : columnTrack ) )
+				.join( ' ' )
+		: `repeat(${ columns }, ${ columnTrack })`;
 	const gridStyle: Record< string, string | number > = {
 		'--a8c-charts-color-heatmap-primary': primaryColorHex,
-		gridTemplateColumns: `auto repeat(${ columns }, ${ columnTrack })`,
+		gridTemplateColumns: `auto ${ columnTracks }`,
 		gridTemplateRows: `auto repeat(${ rows }, ${ rowTrack })`,
 	};
 	if ( compact ) {
@@ -322,6 +335,21 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		gridStyle[ '--a8c-charts-dimension-heatmap-cell-size' ] = `${ compactCellSize }px`;
 	}
 
+	// A summary column sits one gap apart from the data on either side; two
+	// summaries side by side share no extra gap.
+	const summaryGaps = ( columnIndex: number ) => {
+		if ( ! data[ columnIndex ]?.summary ) {
+			return {};
+		}
+
+		return {
+			[ styles[ 'heatmap-chart__gap-start' ] ]:
+				columnIndex > 0 && ! data[ columnIndex - 1 ]?.summary,
+			[ styles[ 'heatmap-chart__gap-end' ] ]:
+				columnIndex < columns - 1 && ! data[ columnIndex + 1 ]?.summary,
+		};
+	};
+
 	const activeDescendant =
 		selectedIndex !== undefined
 			? `${ chartId }-cell-${ Math.floor( selectedIndex / rows ) }-${ selectedIndex % rows }`
@@ -374,7 +402,10 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 							{ data.map( ( column, columnIndex ) => (
 								<span
 									key={ `col-${ columnIndex }` }
-									className={ styles[ 'heatmap-chart__col-label' ] }
+									className={ clsx( styles[ 'heatmap-chart__col-label' ], {
+										[ styles[ 'heatmap-chart__col-label--summary' ] ]: column.summary,
+										...summaryGaps( columnIndex ),
+									} ) }
 								>
 									{ column.label }
 								</span>
@@ -433,7 +464,9 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 
 										const value = cell?.value ?? null;
 										const present = isPresent( value );
-										const normalized = present ? getNormalizedValue( value, extent ) : 0;
+										// A summary cell is on another scale, so it takes no fill.
+										const filled = present && ! column.summary;
+										const normalized = filled ? getNormalizedValue( value, extent ) : 0;
 										const flatIndex = columnIndex * rows + rowIndex;
 										const info = buildTooltipData( columnIndex, rowIndex );
 										const accessibleName =
@@ -449,7 +482,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 											<div
 												key={ `cell-${ columnIndex }-${ rowIndex }` }
 												id={ `${ chartId }-cell-${ columnIndex }-${ rowIndex }` }
-												data-testid="heatmap-cell"
+												data-testid={ column.summary ? 'heatmap-cell-summary' : 'heatmap-cell' }
 												role="gridcell"
 												// Focus stays on the grid (aria-activedescendant); cells are
 												// focusable but out of the tab order.
@@ -459,14 +492,16 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 												data-column={ columnIndex }
 												data-row={ rowIndex }
 												className={ clsx( styles[ 'heatmap-chart__cell' ], {
-													[ styles[ 'heatmap-chart__cell--filled' ] ]: present,
+													[ styles[ 'heatmap-chart__cell--filled' ] ]: filled,
 													[ styles[ 'heatmap-chart__cell--strong' ] ]:
-														present && cellHasLightText( normalized ),
+														filled && cellHasLightText( normalized ),
+													[ styles[ 'heatmap-chart__cell--summary' ] ]: column.summary,
+													...summaryGaps( columnIndex ),
 													[ styles[ 'heatmap-chart__cell--selected' ] ]:
 														selectedIndex === flatIndex,
 												} ) }
 												style={
-													present
+													filled
 														? ( {
 																'--a8c-charts-heatmap-cell-intensity': normalized,
 														  } as CSSProperties )
@@ -475,7 +510,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 												onMouseMove={ handleCellMouseMove }
 												onMouseLeave={ handleCellMouseLeave }
 											>
-												{ drawValues && present && (
+												{ ( drawValues || column.summary ) && present && (
 													<span className={ styles[ 'heatmap-chart__cell-value' ] }>
 														{ /* Compact display; tooltip and aria-label keep full precision. */ }
 														{ formatNumberCompact( value ) }

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

@@ -1,4 +1,11 @@
 export { default as HeatmapChart, HeatmapChartUnresponsive } from './heatmap-chart';
-export { buildCalendarHeatmapData } from './private';
-export type { CalendarHeatmapResult } from './private';
-export type { HeatmapChartProps, HeatmapColumn, HeatmapCell, HeatmapTooltipData } from './types';
+export { buildCalendarHeatmapData } from './build-calendar-data';
+export { useCalendarHeatmapData } from './use-calendar-heatmap-data';
+export type {
+	CalendarHeatmapOptions,
+	CalendarHeatmapResult,
+	HeatmapChartProps,
+	HeatmapColumn,
+	HeatmapCell,
+	HeatmapTooltipData,
+} from './types';

package/src/charts/heatmap-chart/private/civil-day.ts

@@ -0,0 +1,174 @@
+import { parseISO } from 'date-fns';
+import { hasTimezone } from '../../../utils/date-parsing';
+import type { DataPointDate } from '../../../types';
+
+// Branded so a bare string or a real instant cannot pass as either. `civilDate` and
+// `writtenDayKey` validate what they mint; `civilKey` trusts its `CivilDate` argument.
+declare const dayKeyBrand: unique symbol;
+declare const civilDateBrand: unique symbol;
+
+/** A calendar day as `yyyy-MM-dd`; the key every cell is bucketed on. */
+export type DayKey = string & { readonly [ dayKeyBrand ]: true };
+
+/** A UTC-midnight `Date` standing for a civil day, never a real instant. */
+export type CivilDate = Date & { readonly [ civilDateBrand ]: true };
+
+const DAY_MS = 86400000;
+
+// A machine key, pinned so a locale like `th-TH-u-ca-buddhist-nu-thai` cannot key
+// cells on Buddhist years in Thai digits.
+const KEY_OPTIONS: Intl.DateTimeFormatOptions = {
+	calendar: 'gregory',
+	numberingSystem: 'latn',
+	year: 'numeric',
+	month: '2-digit',
+	day: '2-digit',
+};
+
+const DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})/;
+
+const pad = ( value: number, length: number ) => String( value ).padStart( length, '0' );
+
+/**
+ * The day a UTC proxy stands for.
+ *
+ * @param date - UTC proxy.
+ * @return Its day key.
+ */
+export const civilKey = ( date: CivilDate ): DayKey =>
+	`${ pad( date.getUTCFullYear(), 4 ) }-${ pad( date.getUTCMonth() + 1, 2 ) }-${ pad(
+		date.getUTCDate(),
+		2
+	) }` as DayKey;
+
+/**
+ * A day key as a UTC-midnight proxy. UTC has no DST, so every step below is exactly
+ * `DAY_MS`.
+ *
+ * @param key - Day key.
+ * @return The proxy, or null when the key names no real day.
+ */
+export const civilDate = ( key: string ): CivilDate | null => {
+	const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec( key );
+	if ( ! match ) {
+		return null;
+	}
+
+	// Via the setter rather than `Date.UTC`, which reads a two-digit year as 19xx.
+	const date = new Date( 0 ) as CivilDate;
+	date.setUTCFullYear( Number( match[ 1 ] ), Number( match[ 2 ] ) - 1, Number( match[ 3 ] ) );
+	date.setUTCHours( 0, 0, 0, 0 );
+
+	// Round-trip rather than range-check each part, so Feb 30 is rejected too.
+	return civilKey( date ) === key ? date : null;
+};
+
+/**
+ * The day a written date names, ignoring any time and zone it carries.
+ *
+ * @param text - `yyyy-MM-dd`, optionally followed by a time.
+ * @return Its day key, or null.
+ */
+export const writtenDayKey = ( text: string ): DayKey | null => {
+	const match = DATE_PREFIX.exec( text );
+	if ( ! match ) {
+		return null;
+	}
+
+	const key = `${ match[ 1 ] }-${ match[ 2 ] }-${ match[ 3 ] }`;
+	return civilDate( key ) ? ( key as DayKey ) : null;
+};
+
+/**
+ * Reads the day an instant falls on in a zone.
+ *
+ * @param timeZone - IANA zone name; absent leaves the runtime's own.
+ * @return Reader taking a `Date`, null for a day no key can hold.
+ */
+export const instantDayReader = ( timeZone?: string ) => {
+	const formatter = new Intl.DateTimeFormat( 'en-US', { ...KEY_OPTIONS, timeZone } );
+
+	return ( date: Date ): DayKey | null => {
+		const parts = formatter.formatToParts( date );
+		const read = ( type: Intl.DateTimeFormatPartTypes ) =>
+			parts.find( part => part.type === type )?.value ?? '';
+
+		const key = `${ pad( Number( read( 'year' ) ), 4 ) }-${ read( 'month' ) }-${ read( 'day' ) }`;
+		// A `Date` reaches year 275760, past the four digits a key holds, and a wider
+		// key would break the lexicographic ordering the buckets are sorted on.
+		return civilDate( key ) ? ( key as DayKey ) : null;
+	};
+};
+
+/**
+ * The day a series point belongs to.
+ *
+ * A `Date`, or a string carrying `Z` or an offset, is an instant read in the host's
+ * zone. Anything else is a wall clock the host wrote, so its date part is the day.
+ *
+ * @param point       - Series point.
+ * @param readInstant - Reader from `instantDayReader`.
+ * @return Its day key, or null when the point carries no usable date.
+ */
+export const pointDayKey = (
+	point: DataPointDate,
+	readInstant: ( date: Date ) => DayKey | null
+): DayKey | null => {
+	// An unusable `date` falls through to `dateString`: a host that fills both fields
+	// has a working value in the second. A year too wide for a key is unusable too.
+	if ( point.date instanceof Date && ! isNaN( point.date.getTime() ) ) {
+		const key = readInstant( point.date );
+		if ( key ) {
+			return key;
+		}
+	}
+
+	const text = point.dateString;
+	if ( ! text ) {
+		return null;
+	}
+
+	if ( ! hasTimezone( text ) ) {
+		return writtenDayKey( text );
+	}
+
+	const parsed = parseISO( text );
+	return isNaN( parsed.getTime() ) ? null : readInstant( parsed );
+};
+
+/**
+ * Steps a proxy by whole days.
+ *
+ * @param date - UTC proxy.
+ * @param days - Days to add; may be negative.
+ * @return The shifted proxy.
+ */
+export const addCivilDays = ( date: CivilDate, days: number ): CivilDate =>
+	new Date( date.getTime() + days * DAY_MS ) as CivilDate;
+
+/**
+ * Rounds a proxy down to its week.
+ *
+ * @param date         - UTC proxy.
+ * @param weekStartsOn - 0 for Sunday, 1 for Monday.
+ * @return The proxy for that week's first day.
+ */
+export const startOfCivilWeek = ( date: CivilDate, weekStartsOn: 0 | 1 ): CivilDate => {
+	const daysSinceWeekStart = ( date.getUTCDay() - weekStartsOn + 7 ) % 7;
+	return addCivilDays( date, -daysSinceWeekStart );
+};
+
+/**
+ * Counts the columns a span needs.
+ *
+ * @param from         - Earlier UTC proxy.
+ * @param to           - Later UTC proxy.
+ * @param weekStartsOn - 0 for Sunday, 1 for Monday.
+ * @return Columns needed to cover the span, inclusive.
+ */
+export const civilWeekSpan = ( from: CivilDate, to: CivilDate, weekStartsOn: 0 | 1 ): number =>
+	Math.floor(
+		( startOfCivilWeek( to, weekStartsOn ).getTime() -
+			startOfCivilWeek( from, weekStartsOn ).getTime() ) /
+			( 7 * DAY_MS )
+	) + 1;

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

@@ -1,7 +1,5 @@
 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 { CalendarHeatmapResult } from './build-calendar-data';
 export type { HeatmapLegendProps } from './heatmap-legend';
 export type { HeatmapContextValue } from './heatmap-context';

package/src/charts/heatmap-chart/private/use-heatmap-colors.ts

@@ -4,7 +4,8 @@ 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.
+ * 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.
  * @param data - The heatmap columns
  * @return Tuple of [min, max] values
  */
@@ -12,6 +13,9 @@ export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 	let min = Infinity;
 	let max = -Infinity;
 	for ( const column of data ) {
+		if ( column.summary ) {
+			continue;
+		}
 		for ( const cell of column.data ) {
 			if ( ! isPresent( cell.value ) ) {
 				continue;

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[] = [
@@ -113,6 +113,7 @@ describe( 'buildCalendarHeatmapData', () => {
 		expect( values ).toContain( 3 );
 		expect( values ).not.toContain( 9 );
 		expect( values ).not.toContain( 7 );
+		expect( console ).toHaveWarned();
 	} );
 
 	test( 'returns empty result when every entry has an invalid date', () => {
@@ -121,6 +122,7 @@ describe( 'buildCalendarHeatmapData', () => {
 			{ date: new Date( NaN ), value: 2 },
 		];
 		expect( buildCalendarHeatmapData( allInvalid ) ).toEqual( { data: [], rowLabels: [] } );
+		expect( console ).toHaveWarned();
 	} );
 
 	test( 'duplicate days keep the last value (no aggregation)', () => {
@@ -195,6 +197,7 @@ describe( 'buildCalendarHeatmapData with a grid wider than the series', () => {
 		} );
 
 		expect( data ).toHaveLength( 1 );
+		expect( console ).toHaveWarned();
 	} );
 
 	test( 'separates the ragged edge from the filler', () => {