@automattic/charts 3.0.0 → 3.1.0

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

@@ -20,11 +20,12 @@ import {
 	useGlobalChartsContext,
 	GlobalChartsContext,
 } from '../../providers';
+import { useDefaultHiddenSeries } from '../../providers/chart-context/hooks/use-default-hidden-series';
 import { attachSubComponents } from '../../utils';
 import { useChartChildren } from '../private/chart-composition';
+import { ChartInstanceContext } from '../private/chart-instance-context';
 import { ChartLayout } from '../private/chart-layout';
-import { SingleChartContext } from '../private/single-chart-context';
-import { SvgEmptyState } from '../private/svg-empty-state';
+import { getAllHiddenMessage, SvgEmptyState } from '../private/svg-empty-state';
 import { withResponsive } from '../private/with-responsive';
 import styles from './bar-chart.module.scss';
 import {
@@ -42,13 +43,14 @@ import type {
 	DataPointDate,
 	SeriesData,
 	SeriesChartLegendConfig,
+	SeriesVisibilityProps,
 	Optional,
 } from '../../types';
 import type { RenderTooltipParams } from '../../visx/types';
 import type { ResponsiveConfig } from '../private/with-responsive';
 import type { FC, ReactNode, ComponentType } from 'react';
 
-export interface BarChartProps extends BaseChartProps< SeriesData[] > {
+export interface BarChartProps extends BaseChartProps< SeriesData[] >, SeriesVisibilityProps {
 	/**
 	 * Legend configuration. Supports `collapseGroups` on top of the shared options.
 	 */
@@ -122,6 +124,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	orientation = 'vertical',
 	withPatterns = false,
 	showZeroValues = false,
+	defaultHiddenSeries,
 	animation,
 	children,
 	gap = 'md',
@@ -130,6 +133,11 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	const legendCollapseGroups = legend.collapseGroups ?? false;
 	const horizontal = orientation === 'horizontal';
 	const chartId = useChartId( providedChartId );
+	const hiddenSeries = useDefaultHiddenSeries( chartId, defaultHiddenSeries );
+	const isSeriesVisible = useCallback(
+		( seriesLabel: string ) => ! hiddenSeries.has( seriesLabel ),
+		[ hiddenSeries ]
+	);
 	const theme = useXYChartTheme( data );
 
 	const dataSorted = useChartDataTransform( data );
@@ -148,14 +156,14 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	);
 	const legendItems = useChartLegendItems( dataSorted, legendOptions );
 
-	const { getElementStyles, isSeriesVisible } = useGlobalChartsContext();
+	const { getElementStyles } = useGlobalChartsContext();
 
 	// A hidden series is unmounted, so it is not on the band scale either — the
-	// axis has to choose its tick values from what is left.
+	// axis has to choose its tick values from what is left. Visibility is owned by
+	// the provider, whether it changed through the legend or programmatically.
 	const isSeriesRendered = useCallback(
-		( series: SeriesData ) =>
-			! chartId || ! legendInteractive || isSeriesVisible( chartId, series.label ),
-		[ chartId, legendInteractive, isSeriesVisible ]
+		( series: SeriesData ) => isSeriesVisible( series.label ),
+		[ isSeriesVisible ]
 	);
 
 	const chartOptions = useBarChartOptions(
@@ -198,7 +206,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 		totalPoints,
 	} );
 
-	// Add visibility information to series when using interactive legends
+	// Add visibility information from the shared legend state.
 	const seriesWithVisibility = useMemo(
 		() =>
 			dataWithVisibleZeros.map( ( series, index ) => ( {
@@ -514,9 +522,10 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	);
 
 	return (
-		<SingleChartContext.Provider
+		<ChartInstanceContext.Provider
 			value={ {
 				chartId,
+				isSeriesVisible,
 				chartWidth: width,
 				chartHeight: measuredChartHeight || 0,
 			} }
@@ -606,10 +615,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 												width={ width }
 												height={ chartHeight }
 											>
-												{ __(
-													'All series are hidden. Click legend items to show data.',
-													'jetpack-charts'
-												) }
+												{ getAllHiddenMessage( legendInteractive, 'series' ) }
 											</SvgEmptyState>
 										) : null }
 
@@ -673,7 +679,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 					);
 				} }
 			</ChartLayout>
-		</SingleChartContext.Provider>
+		</ChartInstanceContext.Provider>
 	);
 };
 

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

@@ -1,8 +1,10 @@
-import { render, renderHook, screen, within } from '@testing-library/react';
+import { render, renderHook, screen, within, act } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { GlobalChartsProvider } from '../../../providers';
-import BarChart from '../bar-chart';
+import { useGlobalChartsContext } from '../../../providers/chart-context/hooks/use-global-charts-context';
+import BarChart, { BarChartUnresponsive } from '../bar-chart';
 import { useBarChartOptions } from '../private';
+import type { GlobalChartsContextValue } from '../../../providers/chart-context/types';
 import type { SeriesData } from '../../../types';
 
 // Mock useElementSize to return non-zero dimensions in jsdom so charts render
@@ -1017,6 +1019,64 @@ describe( 'BarChart', () => {
 				expect( screen.queryByTestId( 'chart-tooltip-0' ) ).not.toBeInTheDocument();
 			} );
 
+			test( 'keeps the tooltip open once the chart re-renders under it', async () => {
+				// visx hides its tooltip on a debounce and cancels only the most recently
+				// scheduled hide, so anything that re-runs the tooltip effect while nothing
+				// is shown leaves a hide pending that lands on the next tooltip. Seeding a
+				// hidden series re-renders the chart right after mount, which is exactly
+				// that shape.
+				jest.useFakeTimers();
+
+				try {
+					const user = userEvent.setup( { advanceTimers: jest.advanceTimersByTime } );
+					renderWithTheme( {
+						withTooltips: true,
+						defaultHiddenSeries: [ 'Series B' ],
+						data: [
+							{
+								label: 'Series A',
+								data: [
+									{ date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' },
+									{ date: new Date( '2024-01-02' ), value: 20, label: 'Jan 2' },
+								],
+								options: {},
+							},
+							{
+								label: 'Series B',
+								data: [
+									{ date: new Date( '2024-01-01' ), value: 15, label: 'Jan 1' },
+									{ date: new Date( '2024-01-02' ), value: 25, label: 'Jan 2' },
+								],
+								options: {},
+							},
+						],
+					} );
+
+					const chart = screen.getByRole( 'grid', { name: /bar chart/i } );
+					chart.focus();
+
+					await user.keyboard( '{ArrowRight}' );
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveTextContent( 'Series A' );
+
+					// Well past any pending hide.
+					await act( async () => {
+						jest.advanceTimersByTime( 5000 );
+					} );
+
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toBeInTheDocument();
+
+					// Leaving navigation still closes it.
+					await user.keyboard( '{Escape}' );
+					await act( async () => {
+						jest.advanceTimersByTime( 5000 );
+					} );
+
+					expect( screen.queryByTestId( 'chart-tooltip-0' ) ).not.toBeInTheDocument();
+				} finally {
+					jest.useRealTimers();
+				}
+			} );
+
 			test( 'left arrow key navigates to previous data point', async () => {
 				const user = userEvent.setup();
 				renderWithTheme( {
@@ -1918,6 +1978,133 @@ describe( 'BarChart', () => {
 				screen.getByText( /all series are hidden.*click legend items to show data/i )
 			).toBeInTheDocument();
 		} );
+
+		it( 'hides a series programmatically when the legend is not interactive', () => {
+			let context: GlobalChartsContextValue;
+			const Grab = () => {
+				context = useGlobalChartsContext();
+				return null;
+			};
+
+			render(
+				<GlobalChartsProvider>
+					<Grab />
+					<BarChartUnresponsive
+						width={ 500 }
+						height={ 300 }
+						showLegend={ true }
+						legend={ { interactive: false } }
+						chartId="test-programmatic-bar"
+						data={ [
+							{
+								label: 'Series A',
+								data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+								options: {},
+							},
+							{
+								label: 'Series B',
+								data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
+								options: {},
+							},
+						] }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			act( () => {
+				context.toggleSeriesVisibility( 'test-programmatic-bar', 'Series A' );
+				context.toggleSeriesVisibility( 'test-programmatic-bar', 'Series B' );
+			} );
+
+			expect( screen.getByText( /all series are hidden/i ) ).toBeInTheDocument();
+		} );
+
+		it( 'omits the click instruction when the legend cannot be clicked', () => {
+			let context: GlobalChartsContextValue;
+			const Grab = () => {
+				context = useGlobalChartsContext();
+				return null;
+			};
+
+			render(
+				<GlobalChartsProvider>
+					<Grab />
+					<BarChartUnresponsive
+						width={ 500 }
+						height={ 300 }
+						showLegend={ true }
+						legend={ { interactive: false } }
+						chartId="test-empty-copy-bar"
+						data={ [
+							{
+								label: 'Series A',
+								data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+								options: {},
+							},
+						] }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			act( () => {
+				context.toggleSeriesVisibility( 'test-empty-copy-bar', 'Series A' );
+			} );
+
+			expect( screen.getByText( 'All series are hidden.' ) ).toBeInTheDocument();
+			expect( screen.queryByText( /click legend items/i ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'still renders the other series when only one is hidden programmatically', () => {
+			// A test that hides every series would pass even if the chart still forced
+			// all series visible right up until `allSeriesHidden` short-circuited it —
+			// that shape of test masked a real bug in a sibling chart. Hiding exactly
+			// one of two series exercises the partial-hide render path: the bar count
+			// only drops to one if the hidden series' `BarSeries` is actually excluded
+			// from the `BarGroup`, not merely rendered with zero opacity.
+			let context: GlobalChartsContextValue;
+			const Grab = () => {
+				context = useGlobalChartsContext();
+				return null;
+			};
+
+			render(
+				<GlobalChartsProvider>
+					<Grab />
+					<BarChartUnresponsive
+						width={ 500 }
+						height={ 300 }
+						showLegend={ true }
+						legend={ { interactive: false } }
+						chartId="test-programmatic-partial-bar"
+						data={ [
+							{
+								label: 'Series A',
+								data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+								options: {},
+							},
+							{
+								label: 'Series B',
+								data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
+								options: {},
+							},
+						] }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			// eslint-disable-next-line testing-library/no-node-access
+			const svgElement = screen.getByRole( 'grid', { name: /bar chart/i } ).querySelector( 'svg' );
+			// eslint-disable-next-line testing-library/no-node-access
+			expect( svgElement?.querySelectorAll( '.visx-bar-group rect' ) ).toHaveLength( 2 );
+
+			act( () => {
+				context.toggleSeriesVisibility( 'test-programmatic-partial-bar', 'Series B' );
+			} );
+
+			expect( screen.queryByText( /all series are hidden/i ) ).not.toBeInTheDocument();
+			// eslint-disable-next-line testing-library/no-node-access
+			expect( svgElement?.querySelectorAll( '.visx-bar-group rect' ) ).toHaveLength( 1 );
+		} );
 	} );
 
 	describe( 'Legend group collapsing', () => {
@@ -1996,4 +2183,70 @@ describe( 'BarChart', () => {
 			).toBeInTheDocument();
 		} );
 	} );
+
+	describe( 'defaultHiddenSeries', () => {
+		it( 'renders a series hidden when named in defaultHiddenSeries', () => {
+			render(
+				<GlobalChartsProvider>
+					<BarChartUnresponsive
+						width={ 500 }
+						height={ 300 }
+						showLegend={ true }
+						legend={ { interactive: true } }
+						chartId="test-default-hidden-bar"
+						defaultHiddenSeries={ [ 'Series B' ] }
+						data={ [
+							{
+								label: 'Series A',
+								data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+								options: {},
+							},
+							{
+								label: 'Series B',
+								data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
+								options: {},
+							},
+						] }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			const items = screen.getAllByRole( 'button' );
+			expect( items[ 0 ] ).toHaveAttribute( 'aria-pressed', 'true' );
+			expect( items[ 1 ] ).toHaveAttribute( 'aria-pressed', 'false' );
+		} );
+
+		it( 'lets the user reveal a series seeded hidden', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<GlobalChartsProvider>
+					<BarChartUnresponsive
+						width={ 500 }
+						height={ 300 }
+						showLegend={ true }
+						legend={ { interactive: true } }
+						chartId="test-default-hidden-reveal-bar"
+						defaultHiddenSeries={ [ 'Series B' ] }
+						data={ [
+							{
+								label: 'Series A',
+								data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+								options: {},
+							},
+							{
+								label: 'Series B',
+								data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
+								options: {},
+							},
+						] }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			await user.click( screen.getAllByRole( 'button' )[ 1 ] );
+
+			expect( screen.getAllByRole( 'button' )[ 1 ] ).toHaveAttribute( 'aria-pressed', 'true' );
+		} );
+	} );
 } );

package/src/charts/conversion-funnel-chart/conversion-funnel-chart.module.scss

@@ -14,9 +14,9 @@
 	overflow: hidden;
 	color: var(--a8c-charts-color-label);
 	text-overflow: ellipsis;
-	font-size: var(--wpds-typography-font-size-xl, 18px);
+	font-size: var(--wpds-typography-font-size-xl, 20px);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-emphasis, 499);
+	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
 	line-height: var(--wpds-typography-line-height-sm, 20px);
 	margin: 0;
 }
@@ -26,7 +26,7 @@
 	text-overflow: ellipsis;
 	font-size: var(--wpds-typography-font-size-md, 13px);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-emphasis, 499);
+	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
 	line-height: var(--wpds-typography-line-height-sm, 20px);
 	margin: 0;
 }
@@ -66,7 +66,7 @@
 .step-rate {
 	color: var(--a8c-charts-color-label);
 	font-size: var(--wpds-typography-font-size-md, 13px);
-	font-weight: var(--wpds-typography-font-weight-emphasis, 499);
+	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
 	line-height: var(--wpds-typography-line-height-xs, 16px);
 }
 
@@ -126,12 +126,12 @@
 	color: var(--a8c-charts-color-label);
 	font-size: var(--wpds-typography-font-size-md, 13px);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-emphasis, 499);
+	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
 	line-height: var(--wpds-typography-line-height-sm, 20px);
 }
 
 .empty-state {
 	text-align: center;
 	color: var(--a8c-charts-color-label-secondary);
-	font-size: var(--wpds-typography-font-size-lg, 16px);
+	font-size: var(--wpds-typography-font-size-lg, 15px);
 }

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

@@ -1,3 +1,11 @@
 .container {
 	position: relative;
+
+	// Google gives its HTML tooltip no width, so the box shrink-to-fits against
+	// whatever room is left beside the hovered feature. Near a map edge that
+	// breaks even a short label across lines. Sizing to content keeps each line
+	// whole and grows the box instead.
+	:global(.google-visualization-tooltip) {
+		white-space: nowrap;
+	}
 }

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

@@ -103,6 +103,15 @@ $focus-ring-width: var(--wpds-border-width-focus, var(--wp-admin-border-width-fo
 	pointer-events: none;
 }
 
+// Grid filler: keeps its slot so the grid reads as continuous, but stands for a
+// day nothing was measured for — so it captures no pointer, and its track is
+// faded to keep it apart from a measured day that simply scored zero. Mixed
+// towards `transparent` rather than a lighter grey so it holds in either theme.
+.heatmap-chart__cell--placeholder {
+	pointer-events: none;
+	background: color-mix(in sRGB, var(--a8c-charts-color-track) 45%, transparent);
+}
+
 // 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

@@ -21,8 +21,8 @@ import {
 import { resolveCssVariable } from '../../utils/resolve-css-var';
 import { Center } from '../private/center';
 import { useChartChildren } from '../private/chart-composition';
+import { ChartInstanceContext } from '../private/chart-instance-context';
 import { ChartLayout } from '../private/chart-layout';
-import { SingleChartContext } from '../private/single-chart-context';
 import { withResponsive } from '../private/with-responsive';
 import styles from './heatmap-chart.module.scss';
 import {
@@ -136,8 +136,13 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		hideTooltip();
 	}, [ hideTooltip ] );
 
-	const isCellHidden = useCallback(
-		( col: number, row: number ) => data[ col ]?.data[ row ]?.hidden === true,
+	// Both empty-slot kinds are skipped by navigation: `hidden` paints nothing,
+	// `placeholder` paints an empty cell, and neither has a value to report.
+	const isCellInert = useCallback(
+		( col: number, row: number ) => {
+			const cell = data[ col ]?.data[ row ];
+			return cell?.hidden === true || cell?.placeholder === true;
+		},
 		[ data ]
 	);
 
@@ -163,7 +168,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 				// Start at the first navigable cell (a calendar's leading edge
 				// slots may be hidden).
 				for ( let index = 0; index < columns * rows; index++ ) {
-					if ( ! isCellHidden( Math.floor( index / rows ), index % rows ) ) {
+					if ( ! isCellInert( Math.floor( index / rows ), index % rows ) ) {
 						setSelectedIndex( index );
 						return;
 					}
@@ -191,7 +196,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 			do {
 				col += stepCol;
 				row += stepRow;
-			} while ( col >= 0 && col < columns && row >= 0 && row < rows && isCellHidden( col, row ) );
+			} while ( col >= 0 && col < columns && row >= 0 && row < rows && isCellInert( col, row ) );
 
 			if ( col < 0 || col >= columns || row < 0 || row >= rows ) {
 				return;
@@ -199,7 +204,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 
 			setSelectedIndex( col * rows + row );
 		},
-		[ rows, columns, selectedIndex, hideTooltip, isCellHidden ]
+		[ rows, columns, selectedIndex, hideTooltip, isCellInert ]
 	);
 
 	const handleCellMouseMove = useCallback(
@@ -313,7 +318,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 
 	return (
 		<HeatmapContext.Provider value={ heatmapContext }>
-			<SingleChartContext.Provider value={ { chartId } }>
+			<ChartInstanceContext.Provider value={ { chartId } }>
 				<ChartLayout
 					legendPosition="bottom"
 					// Legend renders via trailingContent, not the legend slot.
@@ -391,6 +396,24 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 											);
 										}
 
+										// Filler: drawn like an empty cell so the grid fills its
+										// container, but it stands for a day nothing was measured
+										// for, so it reports nothing to a pointer or a screen
+										// reader either.
+										if ( cell?.placeholder ) {
+											return (
+												<div
+													key={ `cell-${ columnIndex }-${ rowIndex }` }
+													data-testid="heatmap-cell-placeholder"
+													aria-hidden="true"
+													className={ clsx(
+														styles[ 'heatmap-chart__cell' ],
+														styles[ 'heatmap-chart__cell--placeholder' ]
+													) }
+												/>
+											);
+										}
+
 										const value = cell?.value ?? null;
 										const present = isPresent( value );
 										const normalized = present ? getNormalizedValue( value, extent ) : 0;
@@ -456,7 +479,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 						</TooltipInPortal>
 					) }
 				</ChartLayout>
-			</SingleChartContext.Provider>
+			</ChartInstanceContext.Provider>
 		</HeatmapContext.Provider>
 	);
 };

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

@@ -10,6 +10,36 @@ export type CalendarHeatmapResult = {
 /** Rows that get a weekday label (Mon, Wed, Fri with a Monday week start). */
 const LABELLED_ROWS = [ 0, 2, 4 ];
 
+/**
+ * Resolve one grid bound: an unparseable or narrowing value falls back to the
+ * series' own bound, so the grid can only ever be widened.
+ *
+ * @param bound     - Requested bound as `yyyy-MM-dd`, if any.
+ * @param fallback  - The series' own bound on this side.
+ * @param direction - Which way the bound is allowed to move.
+ * @return The bound to draw to.
+ */
+const widenTo = (
+	bound: string | undefined,
+	fallback: Date,
+	direction: 'earlier' | 'later'
+): Date => {
+	if ( ! bound ) {
+		return fallback;
+	}
+
+	const parsed = parseISO( bound );
+	if ( isNaN( parsed.getTime() ) ) {
+		return fallback;
+	}
+
+	if ( direction === 'earlier' ) {
+		return parsed < fallback ? parsed : fallback;
+	}
+
+	return parsed > fallback ? parsed : fallback;
+};
+
 const toDate = ( point: DataPointDate ): Date | null => {
 	if ( point.date instanceof Date && ! isNaN( point.date.getTime() ) ) {
 		return point.date;
@@ -34,6 +64,16 @@ export const buildCalendarHeatmapData = (
 		 * 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 };
 	} = {}
 ): CalendarHeatmapResult => {
 	const weekStartsOn = options.weekStartsOn ?? 1;
@@ -60,14 +100,27 @@ export const buildCalendarHeatmapData = (
 		}
 	}
 
-	const gridStart = startOfWeek( minDate, { weekStartsOn } );
-	const weekCount = differenceInCalendarWeeks( maxDate, gridStart, { weekStartsOn } ) + 1;
-
 	// 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' );
+
+	const gridMaxDayKey = format( gridMaxDate, 'yyyy-MM-dd' );
+
+	const gridStart = startOfWeek( gridMinDate, { 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;
+
 	const rowLabels = Array.from( { length: 7 }, ( _, row ) =>
 		LABELLED_ROWS.includes( row ) ? format( addDays( gridStart, row ), 'EEE' ) : ''
 	);
@@ -104,8 +157,15 @@ export const buildCalendarHeatmapData = (
 				label: format( day, 'EEE, MMM d, yyyy' ),
 				value: valueByDay.has( key ) ? ( valueByDay.get( key ) as number | null ) : null,
 			};
-			if ( hideOutOfRangeDays && ( key < minDayKey || key > maxDayKey ) ) {
-				cell.hidden = true;
+			if ( key < gridMinDayKey || key > gridMaxDayKey ) {
+				// The days completing the grid's first/last week: the calendar's
+				// ragged edge.
+				if ( hideOutOfRangeDays ) {
+					cell.hidden = true;
+				}
+			} else if ( key < minDayKey || key > maxDayKey ) {
+				// Inside the grid the caller asked for, outside the series: filler.
+				cell.placeholder = true;
 			}
 			cells.push( cell );
 		}