@automattic/charts 4.0.0 → 4.1.1

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
+		);
+	} );
+} );

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

@@ -411,6 +411,19 @@ const mockRects = () =>
 		} as DOMRect;
 	} );
 
+describe( 'HeatmapChart keyboard tooltip', () => {
+	test( 'opens on the selected cell without row labels', async () => {
+		renderChart( { withTooltips: true } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		const user = userEvent.setup();
+
+		grid.focus();
+		await user.keyboard( '{ArrowDown}' );
+
+		expect( within( screen.getByRole( 'tooltip' ) ).getByText( '1' ) ).toBeInTheDocument();
+	} );
+} );
+
 describe( 'HeatmapChart tooltip position', () => {
 	afterEach( () => {
 		jest.restoreAllMocks();
@@ -432,3 +445,81 @@ describe( 'HeatmapChart tooltip position', () => {
 		} );
 	} );
 } );
+
+describe( 'HeatmapChart summary column', () => {
+	const withTotals: HeatmapColumn[] = [
+		...data,
+		{ label: 'Total', summary: true, data: [ { value: 400 }, { value: 200 }, { value: null } ] },
+	];
+
+	test( 'keeps the summary column out of the color scale', () => {
+		renderChart( { data: withTotals } );
+		// 4 is still the data maximum, so it keeps full intensity.
+		expect(
+			screen
+				.getByRole( 'gridcell', { name: 'W2: 4' } )
+				.style.getPropertyValue( '--a8c-charts-heatmap-cell-intensity' )
+		).toBe( '1' );
+		expect(
+			screen
+				.getByRole( 'gridcell', { name: 'Total: 400' } )
+				.style.getPropertyValue( '--a8c-charts-heatmap-cell-intensity' )
+		).toBe( '' );
+	} );
+
+	test( 'draws every summary cell, printing its figure even in compact mode', () => {
+		renderChart( { data: withTotals, compact: true } );
+		expect( screen.getAllByTestId( 'heatmap-cell-summary' ) ).toHaveLength( 3 );
+		expect( screen.getByRole( 'gridcell', { name: 'Total: 400' } ) ).toHaveTextContent( '400' );
+		expect( screen.getByRole( 'gridcell', { name: 'Total: No data' } ) ).toBeEmptyDOMElement();
+		expect( screen.getByRole( 'grid' ) ).toHaveAttribute( 'aria-colcount', '3' );
+	} );
+
+	test( 'sets a summary apart from the data on either side, but not from another summary', () => {
+		renderChart( {
+			data: [
+				{ label: 'Lead', summary: true, data: [ { value: 7 }, { value: 8 }, { value: 9 } ] },
+				...withTotals,
+				{ label: 'Mean', summary: true, data: [ { value: 2 }, { value: 1 }, { value: 3 } ] },
+			],
+		} );
+
+		const lead = screen.getByRole( 'gridcell', { name: 'Lead: 7' } );
+		expect( lead ).toHaveClass( 'heatmap-chart__gap-end' );
+		expect( lead ).not.toHaveClass( 'heatmap-chart__gap-start' );
+
+		const total = screen.getByRole( 'gridcell', { name: 'Total: 400' } );
+		expect( total ).toHaveClass( 'heatmap-chart__gap-start' );
+		expect( total ).not.toHaveClass( 'heatmap-chart__gap-end' );
+
+		const mean = screen.getByRole( 'gridcell', { name: 'Mean: 2' } );
+		expect( mean ).not.toHaveClass( 'heatmap-chart__gap-start' );
+		expect( mean ).not.toHaveClass( 'heatmap-chart__gap-end' );
+		expect( screen.getByRole( 'gridcell', { name: 'W1: 1' } ) ).not.toHaveClass(
+			'heatmap-chart__gap-start'
+		);
+	} );
+
+	test( 'keeps the summary track content-sized when the data tracks are capped', () => {
+		renderChart( { data: withTotals, maxCellWidth: 32 } );
+
+		expect( screen.getByRole( 'grid', { name: /heatmap/i } ) ).toHaveStyle( {
+			gridTemplateColumns: 'auto minmax(0px, 32px) minmax(0px, 32px) minmax(auto, max-content)',
+		} );
+	} );
+
+	test( 'reaches the summary column by keyboard, with its tooltip', async () => {
+		renderChart( { data: withTotals, withTooltips: true } );
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		const user = userEvent.setup();
+
+		grid.focus();
+		await user.keyboard( '{ArrowDown}{ArrowRight}{ArrowRight}' );
+
+		expect( grid ).toHaveAttribute(
+			'aria-activedescendant',
+			expect.stringMatching( /-cell-2-0$/ )
+		);
+		expect( within( screen.getByRole( 'tooltip' ) ).getByText( '400' ) ).toBeInTheDocument();
+	} );
+} );

package/src/charts/heatmap-chart/test/use-calendar-heatmap-data.test.tsx

@@ -0,0 +1,118 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+
+// Los Angeles runs behind UTC, the half `zoned-calendar-data` cannot cover: a label
+// formatter that stops reading UTC renders the proxy on the previous day only here.
+import { render } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../providers';
+import { useCalendarHeatmapData } from '../use-calendar-heatmap-data';
+import type { DataPointDate } from '../../../types';
+import type { CalendarHeatmapOptions, CalendarHeatmapResult } from '../types';
+
+// 2026-08-03 08:00 in Asia/Tokyo, 2026-08-02 16:00 in America/Los_Angeles.
+const series: DataPointDate[] = [ { date: new Date( '2026-08-02T23:00:00Z' ), value: 7 } ];
+
+// Aug 3 in UTC, Aug 2 in this file's zone, so a bucket tells the two apart.
+const runtimeVsUtc: DataPointDate[] = [ { date: new Date( '2026-08-03T05:00:00Z' ), value: 7 } ];
+
+describe( 'useCalendarHeatmapData', () => {
+	let result: CalendarHeatmapResult;
+	let renders = 0;
+
+	const Calendar = ( {
+		options,
+		points = series,
+	}: {
+		options?: CalendarHeatmapOptions;
+		points?: DataPointDate[];
+	} ) => {
+		result = useCalendarHeatmapData( points, { weekStartsOn: 1, ...options } );
+		renders++;
+		return null;
+	};
+
+	beforeEach( () => {
+		renders = 0;
+	} );
+
+	const bucketedLabels = () =>
+		result.data
+			.flatMap( column => column.data )
+			.filter( cell => cell.value !== null )
+			.map( cell => cell.label );
+
+	it( "takes the provider's locale and time zone", () => {
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<Calendar />
+			</GlobalChartsProvider>
+		);
+
+		expect( bucketedLabels() ).toEqual( [ 'Mo., 3. Aug. 2026' ] );
+		expect( result.rowLabels ).toEqual( [ 'Mo', '', 'Mi', '', 'Fr', '', '' ] );
+	} );
+
+	it( 'lets an option win over the provider', () => {
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<Calendar options={ { timeZone: 'America/Los_Angeles' } } />
+			</GlobalChartsProvider>
+		);
+
+		expect( bucketedLabels() ).toEqual( [ 'So., 2. Aug. 2026' ] );
+	} );
+
+	it( 'reads an explicit undefined as unset rather than as an override', () => {
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<Calendar options={ { locale: undefined, timeZone: undefined } } />
+			</GlobalChartsProvider>
+		);
+
+		expect( bucketedLabels() ).toEqual( [ 'Mo., 3. Aug. 2026' ] );
+	} );
+
+	it( 'falls back to the runtime with no provider around it', () => {
+		render( <Calendar points={ runtimeVsUtc } /> );
+
+		expect( result.rowLabels ).toEqual( [ 'Mon', '', 'Wed', '', 'Fri', '', '' ] );
+		// rowLabels only prove the locale fell back; the bucket proves the zone did.
+		expect( bucketedLabels() ).toEqual( [ 'Sun, Aug 2, 2026' ] );
+	} );
+
+	it( 'holds its result across a re-render that rebuilds the options object', () => {
+		const { rerender } = render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<Calendar options={ { gridSpan: { start: '2026-07-06' } } } />
+			</GlobalChartsProvider>
+		);
+		const first = result;
+
+		rerender(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<Calendar options={ { gridSpan: { start: '2026-07-06' } } } />
+			</GlobalChartsProvider>
+		);
+
+		expect( renders ).toBeGreaterThan( 1 );
+		expect( result ).toBe( first );
+	} );
+
+	it( 'rebuilds when the provider changes zone', () => {
+		const { rerender } = render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<Calendar />
+			</GlobalChartsProvider>
+		);
+		expect( bucketedLabels() ).toEqual( [ 'Mo., 3. Aug. 2026' ] );
+
+		rerender(
+			<GlobalChartsProvider locale="de-DE" timeZone="America/Los_Angeles">
+				<Calendar />
+			</GlobalChartsProvider>
+		);
+
+		expect( bucketedLabels() ).toEqual( [ 'So., 2. Aug. 2026' ] );
+	} );
+} );

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

@@ -11,6 +11,14 @@ describe( 'getValueExtent', () => {
 		expect( getValueExtent( data ) ).toEqual( [ 0, 20 ] );
 	} );
 
+	test( 'leaves summary columns out of the extent', () => {
+		const withTotals: HeatmapColumn[] = [
+			...data,
+			{ label: 'Total', summary: true, data: [ { value: 500 }, { value: 900 }, { value: null } ] },
+		];
+		expect( getValueExtent( withTotals ) ).toEqual( [ 0, 20 ] );
+	} );
+
 	test( 'returns [0, 0] for all-empty data', () => {
 		expect( getValueExtent( [ { data: [ { value: null } ] } ] ) ).toEqual( [ 0, 0 ] );
 	} );

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

@@ -0,0 +1,248 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-chatham.mjs
+ */
+
+// Chatham runs ahead of UTC. A worker behind it renders a UTC-midnight proxy on
+// its own day, so it cannot tell the grid's UTC arithmetic from local arithmetic.
+import { buildCalendarHeatmapData } from '../build-calendar-data';
+import type { DataPointDate } from '../../../types';
+
+const labelsCarryingValues = ( data: ReturnType< typeof buildCalendarHeatmapData >[ 'data' ] ) =>
+	data.flatMap( column => column.data ).filter( cell => cell.value !== null );
+
+// 2026-08-03 08:00 in Asia/Tokyo, 2026-08-02 16:00 in America/Los_Angeles.
+const nearMidnight: DataPointDate[] = [ { date: new Date( '2026-08-02T23:00:00Z' ), value: 7 } ];
+
+describe( 'buildCalendarHeatmapData bucketing in a host time zone', () => {
+	test( "buckets an instant on the host's day, not the runtime's", () => {
+		const tokyo = buildCalendarHeatmapData( nearMidnight, {
+			weekStartsOn: 1,
+			timeZone: 'Asia/Tokyo',
+		} );
+		const losAngeles = buildCalendarHeatmapData( nearMidnight, {
+			weekStartsOn: 1,
+			timeZone: 'America/Los_Angeles',
+		} );
+
+		expect( labelsCarryingValues( tokyo.data ).map( cell => cell.label ) ).toEqual( [
+			'Mon, Aug 3, 2026',
+		] );
+		expect( labelsCarryingValues( losAngeles.data ).map( cell => cell.label ) ).toEqual( [
+			'Sun, Aug 2, 2026',
+		] );
+	} );
+
+	test( 'places the grid on the host zone week, so the two zones differ by a column', () => {
+		// Aug 2 2026 is a Sunday and Aug 3 a Monday, so a Monday week start puts the
+		// two readings in different weeks entirely.
+		const tokyo = buildCalendarHeatmapData( nearMidnight, {
+			weekStartsOn: 1,
+			timeZone: 'Asia/Tokyo',
+		} );
+
+		expect( tokyo.data[ 0 ].data[ 0 ].value ).toBe( 7 );
+		expect( tokyo.data[ 0 ].data[ 6 ].hidden ).toBe( true );
+	} );
+
+	test( 'a UTC offset works where an IANA name would', () => {
+		const { data } = buildCalendarHeatmapData( nearMidnight, {
+			weekStartsOn: 1,
+			timeZone: '+09:00',
+		} );
+
+		expect( labelsCarryingValues( data ).map( cell => cell.label ) ).toEqual( [
+			'Mon, Aug 3, 2026',
+		] );
+	} );
+} );
+
+describe( 'buildCalendarHeatmapData date semantics', () => {
+	test( 'a bare yyyy-MM-dd is a calendar day, and no zone moves it', () => {
+		const series: DataPointDate[] = [ { dateString: '2024-01-03', value: 5 } ];
+
+		for ( const timeZone of [ undefined, 'Asia/Tokyo', 'America/Los_Angeles' ] ) {
+			const { data } = buildCalendarHeatmapData( series, { weekStartsOn: 1, timeZone } );
+			expect( labelsCarryingValues( data ).map( cell => cell.label ) ).toEqual( [
+				'Wed, Jan 3, 2024',
+			] );
+		}
+	} );
+
+	test( 'a datetime with no offset keeps the day it was written with', () => {
+		const series: DataPointDate[] = [ { dateString: '2024-01-03T23:30:00', value: 5 } ];
+		const { data } = buildCalendarHeatmapData( series, {
+			weekStartsOn: 1,
+			timeZone: 'Pacific/Kiritimati',
+		} );
+
+		expect( labelsCarryingValues( data ).map( cell => cell.label ) ).toEqual( [
+			'Wed, Jan 3, 2024',
+		] );
+	} );
+
+	test( 'a string carrying an offset is an instant, and the host zone re-dates it', () => {
+		const series: DataPointDate[] = [ { dateString: '2024-01-03T23:30:00Z', value: 5 } ];
+		const { data } = buildCalendarHeatmapData( series, {
+			weekStartsOn: 1,
+			timeZone: 'Asia/Tokyo',
+		} );
+
+		expect( labelsCarryingValues( data ).map( cell => cell.label ) ).toEqual( [
+			'Thu, Jan 4, 2024',
+		] );
+	} );
+
+	test( 'drops an instant no four-digit day key can hold', () => {
+		// `Date` reaches year 275760; a wider key would also sort before every other.
+		const outOfRange = [ { date: new Date( 1e15 ), value: 3 } ];
+
+		expect( buildCalendarHeatmapData( outOfRange ) ).toEqual( { data: [], rowLabels: [] } );
+		expect(
+			labelsCarryingValues(
+				buildCalendarHeatmapData( [ ...outOfRange, { dateString: '2024-01-03', value: 5 } ], {
+					weekStartsOn: 1,
+				} ).data
+			).map( cell => cell.label )
+		).toEqual( [ 'Wed, Jan 3, 2024' ] );
+		expect( console ).toHaveWarned();
+	} );
+
+	test( 'falls through to dateString when date is an Invalid Date', () => {
+		const { data } = buildCalendarHeatmapData(
+			[ { date: new Date( 'not a date' ), dateString: '2024-01-03', value: 5 } ],
+			{ weekStartsOn: 1 }
+		);
+
+		expect( labelsCarryingValues( data ).map( cell => cell.label ) ).toEqual( [
+			'Wed, Jan 3, 2024',
+		] );
+	} );
+
+	test( 'drops a written date that names no real day', () => {
+		expect( buildCalendarHeatmapData( [ { dateString: '2024-02-30', value: 5 } ] ) ).toEqual( {
+			data: [],
+			rowLabels: [],
+		} );
+		expect( console ).toHaveWarned();
+	} );
+} );
+
+describe( 'buildCalendarHeatmapData grid bounds are compared as calendar days', () => {
+	// Fri Jan 5 2024, 14:00 UTC: a time of day must not make a bound look earlier than
+	// the series and widen the grid.
+	const afternoon = [ { date: new Date( '2024-01-05T14:00:00Z' ), value: 5 } ];
+
+	test( 'a bound equal to the series start does not widen the grid', () => {
+		const { data } = buildCalendarHeatmapData( afternoon, {
+			weekStartsOn: 1,
+			timeZone: 'UTC',
+			gridSpan: { start: '2024-01-05' },
+		} );
+
+		// Mon Jan 1 to Thu Jan 4 precede the bound: the ragged edge, not filler.
+		expect( data[ 0 ].data.slice( 0, 4 ).map( cell => cell.hidden ) ).toEqual( [
+			true,
+			true,
+			true,
+			true,
+		] );
+		expect( data[ 0 ].data.slice( 0, 4 ).some( cell => cell.placeholder ) ).toBe( false );
+	} );
+
+	test( 'a bound genuinely earlier still widens it', () => {
+		const { data } = buildCalendarHeatmapData( afternoon, {
+			weekStartsOn: 1,
+			timeZone: 'UTC',
+			gridSpan: { start: '2024-01-04' },
+		} );
+
+		expect( data[ 0 ].data.slice( 0, 4 ).every( cell => cell.placeholder === true ) ).toBe( true );
+	} );
+
+	test( 'a bound genuinely later widens it too', () => {
+		const { data } = buildCalendarHeatmapData( afternoon, {
+			weekStartsOn: 1,
+			timeZone: 'UTC',
+			gridSpan: { end: '2024-01-12' },
+		} );
+
+		expect( data ).toHaveLength( 2 );
+		expect( data[ 1 ].data.slice( 0, 5 ).every( cell => cell.placeholder === true ) ).toBe( true );
+	} );
+
+	test( 'warns once and falls back on a bound that names no day', () => {
+		const { data } = buildCalendarHeatmapData( afternoon, {
+			weekStartsOn: 1,
+			timeZone: 'UTC',
+			gridSpan: { start: '2023-12' },
+		} );
+
+		expect( data ).toHaveLength( 1 );
+		expect( console ).toHaveWarned();
+	} );
+} );
+
+describe( 'buildCalendarHeatmapData labels in a host locale', () => {
+	// Three whole December weeks, so the first month keeps its label.
+	const series: DataPointDate[] = [
+		{ dateString: '2023-12-11', value: 1 },
+		{ dateString: '2024-01-03', value: 5 },
+	];
+
+	test( 'writes row, month and cell labels in the locale', () => {
+		const { data, rowLabels } = buildCalendarHeatmapData( series, {
+			weekStartsOn: 1,
+			locale: 'de-DE',
+		} );
+
+		expect( rowLabels ).toEqual( [ 'Mo', '', 'Mi', '', 'Fr', '', '' ] );
+		expect( data.map( column => column.label ) ).toEqual( [ 'Dez', '', '', 'Jan' ] );
+		expect( data[ 3 ].data[ 2 ].label ).toBe( 'Mi., 3. Jan. 2024' );
+	} );
+
+	test( 'does not let the locale override an explicit weekStartsOn', () => {
+		// de-DE starts its week on Monday; the caller asked for Sunday.
+		const { rowLabels } = buildCalendarHeatmapData( series, {
+			weekStartsOn: 0,
+			locale: 'de-DE',
+		} );
+
+		expect( rowLabels ).toEqual( [ 'So', '', 'Di', '', 'Do', '', '' ] );
+	} );
+
+	test( 'repairs a WordPress locale and falls back rather than throwing on a bad one', () => {
+		expect(
+			buildCalendarHeatmapData( series, { weekStartsOn: 1, locale: 'de_DE' } ).rowLabels
+		).toEqual( [ 'Mo', '', 'Mi', '', 'Fr', '', '' ] );
+
+		expect( () =>
+			buildCalendarHeatmapData( series, {
+				weekStartsOn: 1,
+				locale: 'not a tag',
+				timeZone: 'Nowhere/Fictional',
+			} )
+		).not.toThrow();
+		expect( console ).toHaveWarned();
+	} );
+} );
+
+describe( 'buildCalendarHeatmapData across a DST transition', () => {
+	// Chile moves its clocks on 2024-09-08, at midnight rather than in the small
+	// hours, which is where local-midnight day arithmetic loses a day.
+	const daily: DataPointDate[] = Array.from( { length: 14 }, ( _, index ) => ( {
+		date: new Date( Date.UTC( 2024, 8, 2 + index, 16 ) ),
+		value: index,
+	} ) );
+
+	test( 'draws every day exactly once', () => {
+		const { data } = buildCalendarHeatmapData( daily, {
+			weekStartsOn: 1,
+			timeZone: 'America/Santiago',
+		} );
+
+		expect( data ).toHaveLength( 2 );
+		expect( labelsCarryingValues( data ) ).toHaveLength( 14 );
+		expect( data[ 0 ].data.map( cell => cell.value ) ).toEqual( [ 0, 1, 2, 3, 4, 5, 6 ] );
+		expect( data[ 1 ].data.map( cell => cell.value ) ).toEqual( [ 7, 8, 9, 10, 11, 12, 13 ] );
+	} );
+} );

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

@@ -28,6 +28,12 @@ export type HeatmapColumn = {
 	/** x-axis label for this column. Empty/omitted renders blank. */
 	label?: string;
 	data: HeatmapCell[];
+	/**
+	 * A per-row roll-up such as a total or an average. Left out of the color
+	 * scale, drawn unfilled with its figure always printed, on an `auto` track
+	 * one gap apart from the data beside it. The chart never computes it.
+	 */
+	summary?: boolean;
 };
 
 export type HeatmapTooltipData = {
@@ -76,3 +82,32 @@ export interface HeatmapChartProps
 	renderTooltip?: ( data: HeatmapTooltipData ) => ReactNode;
 	children?: ReactNode;
 }
+
+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;
+};

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

@@ -0,0 +1,42 @@
+import { useMemo } from 'react';
+import { useChartFormatting } from '../../providers';
+import { buildCalendarHeatmapData } from './build-calendar-data';
+import type { CalendarHeatmapOptions, CalendarHeatmapResult } from './types';
+import type { DataPointDate } from '../../types';
+
+/**
+ * `buildCalendarHeatmapData` with the locale and zone taken from
+ * `GlobalChartsProvider` where the caller names neither.
+ *
+ * @param series  - Points to bucket. Held by reference, so a caller that rebuilds it each render defeats the memo.
+ * @param options - As for `buildCalendarHeatmapData`; `locale` and `timeZone` win over the provider.
+ * @return Columns and row labels for `HeatmapChart`.
+ */
+export const useCalendarHeatmapData = (
+	series: DataPointDate[],
+	options: CalendarHeatmapOptions = {}
+): CalendarHeatmapResult => {
+	const formatting = useChartFormatting();
+
+	// `??` rather than a spread, so an explicit `undefined` in `options` reads as
+	// "unset" and still picks the provider up.
+	const locale = options.locale ?? formatting.locale;
+	const timeZone = options.timeZone ?? formatting.timeZone;
+	const { weekStartsOn, hideOutOfRangeDays } = options;
+	const gridStart = options.gridSpan?.start;
+	const gridEnd = options.gridSpan?.end;
+
+	// Options are spread into primitives: the object itself is rebuilt on each render,
+	// even by a caller that memoized its own, and would defeat this memo.
+	return useMemo(
+		() =>
+			buildCalendarHeatmapData( series, {
+				locale,
+				timeZone,
+				weekStartsOn,
+				hideOutOfRangeDays,
+				gridSpan: { start: gridStart, end: gridEnd },
+			} ),
+		[ series, locale, timeZone, weekStartsOn, hideOutOfRangeDays, gridStart, gridEnd ]
+	);
+};

package/src/charts/leaderboard-chart/types.ts

@@ -36,9 +36,9 @@ export interface LeaderboardChartProps
 	secondaryColor?: string;
 
 	/**
-	 * Formatter for values
+	 * Formatter for values. May return an element, e.g. to attach a tooltip.
 	 */
-	valueFormatter?: ( value: number ) => string;
+	valueFormatter?: ( value: number ) => ReactNode;
 
 	/**
 	 * Formatter for delta values