@automattic/charts 3.2.0 → 4.1.0

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,122 +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;
 };
 
+/**
+ * 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++;
 	}
@@ -142,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/heatmap-legend.tsx

@@ -15,7 +15,7 @@ export interface HeatmapLegendProps {
 
 export const HeatmapLegend: FC< HeatmapLegendProps > = ( { steps = 5, lessLabel, moreLabel } ) => {
 	const context = useContext( HeatmapContext );
-	const { legend, backgroundColor } = useGlobalChartsTheme();
+	const { legend } = useGlobalChartsTheme();
 	if ( ! context ) {
 		return null;
 	}
@@ -24,7 +24,11 @@ export const HeatmapLegend: FC< HeatmapLegendProps > = ( { steps = 5, lessLabel,
 
 	return (
 		<Stack direction="row" gap="xs" align="center">
-			<Text variant="body-sm" style={ labelStyle }>
+			<Text
+				variant="body-sm"
+				className={ styles[ 'heatmap-chart__legend-label' ] }
+				style={ labelStyle }
+			>
 				{ lessLabel ?? __( 'Less', 'jetpack-charts' ) }
 			</Text>
 			<Stack direction="row" gap="xs">
@@ -38,7 +42,6 @@ export const HeatmapLegend: FC< HeatmapLegendProps > = ( { steps = 5, lessLabel,
 							style={
 								{
 									'--a8c-charts-color-heatmap-primary': primaryColorHex,
-									'--a8c-charts-color-heatmap-background': backgroundColor,
 									'--a8c-charts-heatmap-cell-intensity': intensity,
 								} as CSSProperties
 							}
@@ -46,7 +49,11 @@ export const HeatmapLegend: FC< HeatmapLegendProps > = ( { steps = 5, lessLabel,
 					);
 				} ) }
 			</Stack>
-			<Text variant="body-sm" style={ labelStyle }>
+			<Text
+				variant="body-sm"
+				className={ styles[ 'heatmap-chart__legend-label' ] }
+				style={ labelStyle }
+			>
 				{ moreLabel ?? __( 'More', 'jetpack-charts' ) }
 			</Text>
 		</Stack>

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';

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

@@ -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', () => {

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

@@ -0,0 +1,70 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-chatham.mjs
+ */
+
+import { civilDate, instantDayReader, pointDayKey, startOfCivilWeek } from '../private/civil-day';
+
+const readUtc = instantDayReader( 'UTC' );
+
+describe( 'civilDate', () => {
+	test( 'rejects a day the calendar does not have', () => {
+		expect( civilDate( '2024-02-30' ) ).toBeNull();
+		expect( civilDate( '2024-13-01' ) ).toBeNull();
+	} );
+
+	test( 'reads a year below 1000 as itself, not as 19xx', () => {
+		expect( civilDate( '0099-01-05' )?.getUTCFullYear() ).toBe( 99 );
+	} );
+} );
+
+describe( 'instantDayReader', () => {
+	test( 'drops a year too wide for a four-digit key', () => {
+		expect( readUtc( new Date( 1e15 ) ) ).toBeNull();
+	} );
+} );
+
+describe( 'pointDayKey', () => {
+	// The same instant, written four ways ISO 8601 allows.
+	test.each( [ 'Z', '+00:00', '+0000', '+00' ] )( 'reads an offset written %s', offset => {
+		expect(
+			pointDayKey( { dateString: `2024-01-03T23:30:00${ offset }`, value: 1 }, readUtc )
+		).toBe( '2024-01-03' );
+	} );
+
+	test( 'an hour-only offset re-dates the point like a full one', () => {
+		const readTokyo = instantDayReader( 'Asia/Tokyo' );
+
+		// 04:30 UTC, so Tokyo has already turned over to the 4th.
+		expect( pointDayKey( { dateString: '2024-01-03T23:30:00-05', value: 1 }, readTokyo ) ).toBe(
+			'2024-01-04'
+		);
+		expect( pointDayKey( { dateString: '2024-01-03T23:30:00-05:00', value: 1 }, readTokyo ) ).toBe(
+			'2024-01-04'
+		);
+	} );
+
+	test( 'a datetime with no offset keeps the day it was written with', () => {
+		expect( pointDayKey( { dateString: '2024-01-03T23:30:00', value: 1 }, readUtc ) ).toBe(
+			'2024-01-03'
+		);
+	} );
+
+	test( 'falls through to dateString when date carries an unreadable year', () => {
+		expect(
+			pointDayKey( { date: new Date( 1e15 ), dateString: '2024-01-03', value: 1 }, readUtc )
+		).toBe( '2024-01-03' );
+	} );
+} );
+
+describe( 'startOfCivilWeek', () => {
+	test.each( [
+		[ 1 as const, '2024-01-01' ],
+		[ 0 as const, '2023-12-31' ],
+	] )( 'rounds Wed Jan 3 2024 down for weekStartsOn %i', ( weekStartsOn, expected ) => {
+		const wednesday = civilDate( '2024-01-03' );
+
+		expect( startOfCivilWeek( wednesday!, weekStartsOn ).toISOString().slice( 0, 10 ) ).toBe(
+			expected
+		);
+	} );
+} );