@automattic/charts 3.2.0 → 4.1.0

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

@@ -352,24 +352,21 @@ describe( 'HeatmapChart', () => {
 		expect( grid.style.getPropertyValue( '--a8c-charts-color-heatmap-primary' ) ).toBe( '#abcdef' );
 	} );
 
-	test( 'resolves primaryColor from the chart theme', () => {
-		render(
-			<GlobalChartsProvider theme={ { heatmapChart: { primaryColor: '#0a0b0c' } } }>
-				<HeatmapChart width={ 500 } height={ 300 } data={ data } />
-			</GlobalChartsProvider>
-		);
-		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
-		expect( grid.style.getPropertyValue( '--a8c-charts-color-heatmap-primary' ) ).toBe( '#0a0b0c' );
-	} );
+	test( 'falls back to the first palette slot when no primaryColor prop is set', () => {
+		const scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-series-1', '#0a0b0c' );
+		document.body.appendChild( scope );
 
-	test( 'falls back to the palette colors[0] when no prop or theme primaryColor is set', () => {
 		render(
-			<GlobalChartsProvider theme={ { colors: [ '#0a0b0c' ] } }>
+			<GlobalChartsProvider>
 				<HeatmapChart width={ 500 } height={ 300 } data={ data } />
-			</GlobalChartsProvider>
+			</GlobalChartsProvider>,
+			{ container: scope }
 		);
 		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
 		expect( grid.style.getPropertyValue( '--a8c-charts-color-heatmap-primary' ) ).toBe( '#0a0b0c' );
+
+		document.body.removeChild( scope );
 	} );
 
 	test( 'the unresponsive export pins explicit width and height', () => {
@@ -393,3 +390,136 @@ describe( 'HeatmapChart', () => {
 		expect( chart ).not.toHaveStyle( { height: '300px' } );
 	} );
 } );
+
+// Chart container at (100, 50); the tooltip box measures 120x40. Everything
+// else the charts measure (wrapper, clipping lookups) reports the container.
+const mockRects = () =>
+	jest.spyOn( Element.prototype, 'getBoundingClientRect' ).mockImplementation( function (
+		this: Element
+	) {
+		const box = this.classList.contains( 'visx-tooltip' );
+		return {
+			left: box ? 0 : 100,
+			top: box ? 0 : 50,
+			width: box ? 120 : 400,
+			height: box ? 40 : 300,
+			right: box ? 120 : 500,
+			bottom: box ? 40 : 350,
+			x: box ? 0 : 100,
+			y: box ? 0 : 50,
+			toJSON: () => ( {} ),
+		} 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();
+	} );
+
+	test( 'places the box relative to the chart root, at the pointer plus the offsets', async () => {
+		mockRects();
+		renderChart( { withTooltips: true, rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+
+		await userEvent.setup().pointer( {
+			target: screen.getAllByTestId( 'heatmap-cell' )[ 0 ],
+			coords: { clientX: 180, clientY: 140 },
+		} );
+
+		// (180, 140) is (80, 90) inside the root; the box adds 10px each way.
+		await expect( screen.findByRole( 'tooltip' ) ).resolves.toBeInTheDocument();
+		expect( screen.getByTestId( 'bounded-tooltip' ) ).toHaveStyle( {
+			transform: 'translate(90px, 100px)',
+		} );
+	} );
+} );
+
+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 '../private';
+
+// 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 '../private/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 = {
@@ -69,8 +75,8 @@ export interface HeatmapChartProps
 	/** Floor a cell's height (px) in non-compact mode; see `minCellWidth`. */
 	minCellHeight?: number;
 	/**
-	 * Color the cell scale interpolates toward at the highest value
-	 * (this prop > theme `heatmapChart.primaryColor` > palette `colors[0]`).
+	 * Color the cell scale interpolates toward at the highest value. Defaults to the
+	 * first series palette slot, `--a8c-charts-color-series-1`.
 	 */
 	primaryColor?: string;
 	renderTooltip?: ( data: HeatmapTooltipData ) => ReactNode;

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 './private';
+import type { CalendarHeatmapOptions, CalendarHeatmapResult } from './private';
+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/hooks/use-fitted-row-count.ts

@@ -13,8 +13,8 @@ export const SUBPIXEL_TOLERANCE = 0.5;
  * Counts how many leading rows fit inside the content container.
  *
  * Rows are read from the DOM rather than derived from constants: row height
- * depends on the theme's row gap, label wrapping, and whatever a caller renders
- * as a label, so any restated number would drift.
+ * depends on `--a8c-charts-dimension-leaderboard-row-gap`, label wrapping, and
+ * whatever a caller renders as a label, so any restated number would drift.
  *
  * Every row is a direct grid child marked with `data-row-index`; interactive rows
  * use a button wrapper and non-interactive rows use a div wrapper.

package/src/charts/leaderboard-chart/hooks/use-leaderboard-legend-items.ts

@@ -1,6 +1,6 @@
 import { __ } from '@wordpress/i18n';
 import { useMemo } from 'react';
-import { useGlobalChartsTheme, useGlobalChartsContext } from '../../../providers';
+import { useGlobalChartsContext } from '../../../providers';
 import type { BaseLegendItem } from '../../../components/legend';
 import type { LeaderboardEntry } from '../../../types';
 
@@ -35,7 +35,6 @@ export function useLeaderboardLegendItems( {
 		comparison?: string;
 	};
 } ): BaseLegendItem[] {
-	const { leaderboardChart: leaderboardChartSettings } = useGlobalChartsTheme();
 	const { getElementStyles } = useGlobalChartsContext();
 
 	return useMemo( () => {
@@ -48,7 +47,7 @@ export function useLeaderboardLegendItems( {
 		// Add current period legend item
 		const { color: resolvedPrimaryColor } = getElementStyles( {
 			index: 0,
-			overrideColor: primaryColor || leaderboardChartSettings.primaryColor,
+			overrideColor: primaryColor,
 		} );
 
 		items.push( {
@@ -60,7 +59,7 @@ export function useLeaderboardLegendItems( {
 		if ( withComparison && ! withOverlayLabel ) {
 			const { color: resolvedSecondaryColor } = getElementStyles( {
 				index: 1,
-				overrideColor: secondaryColor || leaderboardChartSettings.secondaryColor,
+				overrideColor: secondaryColor,
 			} );
 
 			items.push( {
@@ -76,7 +75,6 @@ export function useLeaderboardLegendItems( {
 		secondaryColor,
 		withComparison,
 		legendLabels,
-		leaderboardChartSettings,
 		getElementStyles,
 		withOverlayLabel,
 	] );