@automattic/charts 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "4.0.0",
+	"version": "4.1.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -65,6 +65,7 @@
 	"dependencies": {
 		"@automattic/number-formatters": "^1.2.8",
 		"@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",

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,5 @@
 export { default as HeatmapChart, HeatmapChartUnresponsive } from './heatmap-chart';
 export { buildCalendarHeatmapData } from './private';
-export type { CalendarHeatmapResult } from './private';
+export { useCalendarHeatmapData } from './use-calendar-heatmap-data';
+export type { CalendarHeatmapOptions, CalendarHeatmapResult } from './private';
 export type { HeatmapChartProps, HeatmapColumn, HeatmapCell, HeatmapTooltipData } from './types';

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

@@ -1,12 +1,48 @@
-import { addDays, differenceInCalendarWeeks, format, parseISO, startOfWeek } from 'date-fns';
+import { createDateFormatter, sanitizeFormatting } from '../../../utils/date-formatting';
+import { warnOnce } from '../../../utils/warn-once';
+import {
+	addCivilDays,
+	civilDate,
+	civilKey,
+	civilWeekSpan,
+	instantDayReader,
+	pointDayKey,
+	startOfCivilWeek,
+	writtenDayKey,
+} from './civil-day';
 import type { DataPointDate } from '../../../types';
 import type { HeatmapCell, HeatmapColumn } from '../types';
+import type { CivilDate, DayKey } from './civil-day';
 
 export type CalendarHeatmapResult = {
 	data: HeatmapColumn[];
 	rowLabels: string[];
 };
 
+export type CalendarHeatmapOptions = {
+	weekStartsOn?: 0 | 1;
+	/**
+	 * Mark the days completing the first and last week outside the series' span as
+	 * hidden cells rather than blank ones, giving the calendar ragged edges. Days
+	 * inside the span stay blank even where the series has no entry.
+	 */
+	hideOutOfRangeDays?: boolean;
+	/**
+	 * Draw the grid over this span (`yyyy-MM-dd` bounds) instead of the series' own.
+	 * Days inside the grid but outside the series become placeholder cells: painted,
+	 * but reporting nothing, since they were never measured. A start bound opens from
+	 * the beginning of its week, and bounds narrower than the series are ignored.
+	 */
+	gridSpan?: { start?: string; end?: string };
+	/** BCP-47 tag the labels are written in. Defaults to the runtime's locale. */
+	locale?: string;
+	/**
+	 * IANA zone the series' instants are bucketed into days in. Defaults to the
+	 * runtime's zone. A `dateString` carrying no offset is taken as written.
+	 */
+	timeZone?: string;
+};
+
 /** Rows that get a weekday label (Mon, Wed, Fri with a Monday week start). */
 const LABELLED_ROWS = [ 0, 2, 4 ];
 
@@ -17,125 +53,124 @@ const LABELLED_ROWS = [ 0, 2, 4 ];
  * @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 bound to draw to.
+ * @return The day key to draw to.
  */
 const widenTo = (
 	bound: string | undefined,
-	fallback: Date,
+	fallback: DayKey,
 	direction: 'earlier' | 'later'
-): Date => {
-	if ( ! bound ) {
-		return fallback;
-	}
-
-	const parsed = parseISO( bound );
-	if ( isNaN( parsed.getTime() ) ) {
+): 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 parsed < fallback ? parsed : fallback;
+		return key < fallback ? key : fallback;
 	}
 
-	return parsed > fallback ? parsed : fallback;
-};
-
-const toDate = ( point: DataPointDate ): Date | null => {
-	if ( point.date instanceof Date && ! isNaN( point.date.getTime() ) ) {
-		return point.date;
-	}
-	if ( point.dateString ) {
-		const parsed = parseISO( point.dateString );
-		if ( ! isNaN( parsed.getTime() ) ) {
-			return parsed;
-		}
-	}
-	return null;
+	return key > fallback ? key : fallback;
 };
 
-// Labels stay English on the browser's calendar, unlike the time axis: this is a
-// plain function the host calls outside the provider, so `GlobalChartsProvider`'s
-// `locale` and `timeZone` cannot reach it. CHARTS-266 has the detail.
+/**
+ * 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: {
-		weekStartsOn?: 0 | 1;
-		/**
-		 * Mark the days completing the first/last week outside the series'
-		 * date span as hidden cells (empty grid slots) instead of blank
-		 * cells, giving the calendar ragged edges. Days inside the span stay
-		 * blank cells even when the series has no entry for them.
-		 */
-		hideOutOfRangeDays?: boolean;
-		/**
-		 * Draw the grid over this span (`yyyy-MM-dd` bounds) instead of the
-		 * series' own. Days inside the grid but outside the series become
-		 * placeholder cells: painted as empty slots so a short series still
-		 * fills its container, but reporting nothing, since they were never
-		 * measured. A start bound is drawn from the beginning of its week, so
-		 * the grid always opens on a whole column. Bounds narrower than the
-		 * series are ignored — the grid never drops a day that carries data.
-		 */
-		gridSpan?: { start?: string; end?: string };
-	} = {}
+	options: CalendarHeatmapOptions = {}
 ): CalendarHeatmapResult => {
 	const weekStartsOn = options.weekStartsOn ?? 1;
 	const hideOutOfRangeDays = options.hideOutOfRangeDays ?? true;
 
-	const entries = series
-		.map( point => ( { date: toDate( point ), value: point.value } ) )
-		.filter( ( entry ): entry is { date: Date; value: number | null } => entry.date !== null );
-
-	if ( ! entries.length ) {
-		return { data: [], rowLabels: [] };
-	}
+	// 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;
+		}
 
-	const valueByDay = new Map< string, number | null >();
-	let minDate = entries[ 0 ].date;
-	let maxDate = entries[ 0 ].date;
-	for ( const { date, value } of entries ) {
-		valueByDay.set( format( date, 'yyyy-MM-dd' ), value );
-		if ( date < minDate ) {
-			minDate = date;
+		valueByDay.set( key, point.value );
+		// Day keys are fixed-width, so lexicographic order is chronological order.
+		if ( ! minDayKey || key < minDayKey ) {
+			minDayKey = key;
 		}
-		if ( date > maxDate ) {
-			maxDate = date;
+		if ( ! maxDayKey || key > maxDayKey ) {
+			maxDayKey = key;
 		}
 	}
 
-	// Day-key bounds for the ragged-edge option: calendar-day comparison, so
-	// entries carrying a time of day can't shift the span.
-	const minDayKey = format( minDate, 'yyyy-MM-dd' );
-	const maxDayKey = format( maxDate, 'yyyy-MM-dd' );
-
-	// The grid may run wider than the series, never narrower: a bound that would
-	// cut into the data is dropped rather than honoured.
-	const gridMinDate = widenTo( options.gridSpan?.start, minDate, 'earlier' );
-	const gridMaxDate = widenTo( options.gridSpan?.end, maxDate, 'later' );
+	if ( ! minDayKey || ! maxDayKey ) {
+		return { data: [], rowLabels: [] };
+	}
 
-	const gridMaxDayKey = format( gridMaxDate, 'yyyy-MM-dd' );
+	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 = startOfWeek( gridMinDate, { weekStartsOn } );
+	const gridStart = startOfCivilWeek( requestedMinDate, weekStartsOn );
 
-	// A start bound rarely lands on a week start, and `gridStart` rounds it down.
-	// The days it rounds past were no more measured than the rest of the widened
-	// span, so they are filler too; treating them as a ragged edge instead would
-	// notch the first column by however far the bound sat into its week.
-	const gridMinDayKey = format( gridMinDate < minDate ? gridStart : gridMinDate, 'yyyy-MM-dd' );
-	const weekCount = differenceInCalendarWeeks( gridMaxDate, gridStart, { weekStartsOn } ) + 1;
+	// `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 ) ? format( addDays( gridStart, row ), 'EEE' ) : ''
+		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.getMonth();
+	const firstMonth = gridStart.getUTCMonth();
 	let firstMonthWeeks = 0;
 	while (
 		firstMonthWeeks < weekCount &&
-		addDays( gridStart, firstMonthWeeks * 7 ).getMonth() === firstMonth
+		addCivilDays( gridStart, firstMonthWeeks * 7 ).getUTCMonth() === firstMonth
 	) {
 		firstMonthWeeks++;
 	}
@@ -145,24 +180,23 @@ export const buildCalendarHeatmapData = (
 	const data: HeatmapColumn[] = [];
 	let previousMonth = -1;
 	for ( let week = 0; week < weekCount; week++ ) {
-		const columnStart = addDays( gridStart, week * 7 );
-		const month = columnStart.getMonth();
+		const columnStart = addCivilDays( gridStart, week * 7 );
+		const month = columnStart.getUTCMonth();
 		const isNewMonth = month !== previousMonth;
 		const label =
-			isNewMonth && ( week !== 0 || showFirstMonthLabel ) ? format( columnStart, 'MMM' ) : '';
+			isNewMonth && ( week !== 0 || showFirstMonthLabel ) ? formatMonth( columnStart ) : '';
 		previousMonth = month;
 
 		const cells: HeatmapCell[] = [];
 		for ( let row = 0; row < 7; row++ ) {
-			const day = addDays( gridStart, week * 7 + row );
-			const key = format( day, 'yyyy-MM-dd' );
+			const day = addCivilDays( gridStart, week * 7 + row );
+			const key = civilKey( day );
 			const cell: HeatmapCell = {
-				label: format( day, 'EEE, MMM d, yyyy' ),
+				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/last week: the calendar's
-				// ragged edge.
+				// The days completing the grid's first and last week: the ragged edge.
 				if ( hideOutOfRangeDays ) {
 					cell.hidden = true;
 				}

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

@@ -2,6 +2,6 @@ export { getValueExtent, getNormalizedValue, isPresent } from './use-heatmap-col
 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 { CalendarHeatmapOptions, CalendarHeatmapResult } from './build-calendar-data';
 export type { HeatmapLegendProps } from './heatmap-legend';
 export type { HeatmapContextValue } from './heatmap-context';