@automattic/charts 1.10.0 → 1.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "1.10.0",
+	"version": "1.10.2",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -63,7 +63,7 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.2.5",
+		"@automattic/number-formatters": "^1.2.7",
 		"@babel/runtime": "7.29.7",
 		"@react-spring/web": "10.1.1",
 		"@visx/annotation": "^4.0.0",
@@ -107,11 +107,11 @@
 		"@types/jest": "^30.0.0",
 		"@types/react": "18.3.28",
 		"@types/react-dom": "18.3.7",
-		"@typescript/native-preview": "7.0.0-dev.20260225.1",
+		"@typescript/native-preview": "7.0.0-dev.20260707.2",
 		"@visx/glyph": "4.0.0",
-		"@wordpress/components": "36.1.0",
-		"@wordpress/element": "8.2.0",
-		"@wordpress/private-apis": "1.50.0",
+		"@wordpress/components": "37.0.0",
+		"@wordpress/element": "8.3.0",
+		"@wordpress/private-apis": "1.51.0",
 		"babel-jest": "30.4.1",
 		"identity-obj-proxy": "^3.0.0",
 		"jest": "30.4.2",
@@ -122,7 +122,7 @@
 		"sass-embedded": "1.97.3",
 		"storybook": "10.4.6",
 		"tsdown": "0.22.2",
-		"typescript": "5.9.3"
+		"typescript": "6.0.3"
 	},
 	"peerDependencies": {
 		"react": "^18.0.0 || ^19.0.0",

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

@@ -5,6 +5,13 @@
 	font-size: var(--wpds-typography-font-size-sm, 12px);
 }
 
+// Height-capped grids are content-sized vertically, so the wrapper hugs them
+// instead of stretching — the consumer decides how to place it in leftover
+// space. Width-only caps keep the normal full-height layout.
+.heatmap-chart--height-capped {
+	height: max-content;
+}
+
 .heatmap-chart__empty {
 	padding: var(--wpds-dimension-padding-lg, 16px);
 	color: var(--wpds-color-foreground-content-neutral-weak, #707070);
@@ -17,8 +24,8 @@
 	gap: var(--heatmap-cell-gap, var(--wpds-dimension-gap-xs, 4px));
 	flex: 1 1 0;
 	width: 100%;
-	// Floor so the grid stays usable when the parent has no explicit height.
-	min-height: 200px;
+	// Override flex's auto minimum so short widgets do not scroll.
+	min-height: 0;
 
 	&:focus-visible {
 		outline:
@@ -36,6 +43,15 @@
 	min-height: 0;
 }
 
+// A cell-height cap makes the row tracks content-bound, so the grid must not
+// stretch: leftover container height would otherwise be absorbed by the auto
+// label row. A width-only cap does not change vertical flex sizing.
+.heatmap-chart__grid--height-capped {
+	flex: 0 0 auto;
+	height: max-content;
+	min-height: 0;
+}
+
 .heatmap-chart__row {
 	display: contents;
 }
@@ -71,10 +87,17 @@
 	background: var(--wpds-color-background-track-neutral-weak, #f0f0f0);
 }
 
+// An empty grid slot (calendar ragged edges): keeps its track but paints and
+// captures nothing. `visibility` (not `display`) so the slot still sizes.
+.heatmap-chart__cell--hidden {
+	visibility: hidden;
+	pointer-events: none;
+}
+
 // Floor the mix at 15% so the lowest value stays visibly tinted, distinct from
 // an empty cell.
 .heatmap-chart__cell--filled {
-	background: color-mix(in sRGB, var(--heatmap-primary) calc((0.15 + 0.85 * var(--intensity)) * 100%), transparent);
+	background: color-mix(in sRGB, var(--heatmap-primary) calc((0.15 + 0.85 * var(--intensity)) * 100%), var(--heatmap-bg, #fff));
 }
 
 .heatmap-chart__cell--selected {
@@ -99,5 +122,5 @@
 	width: var(--wpds-dimension-size-3xs, 12px);
 	height: var(--wpds-dimension-size-3xs, 12px);
 	border-radius: var(--wpds-border-radius-sm, 2px);
-	background: color-mix(in sRGB, var(--heatmap-primary) calc((0.15 + 0.85 * var(--intensity)) * 100%), transparent);
+	background: color-mix(in sRGB, var(--heatmap-primary) calc((0.15 + 0.85 * var(--intensity)) * 100%), var(--heatmap-bg, #fff));
 }

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

@@ -2,15 +2,7 @@ import { formatNumber, formatNumberCompact } from '@automattic/number-formatters
 import { useTooltip, useTooltipInPortal } from '@visx/tooltip';
 import { __ } from '@wordpress/i18n';
 import clsx from 'clsx';
-import {
-	createContext,
-	useCallback,
-	useContext,
-	useEffect,
-	useMemo,
-	useRef,
-	useState,
-} from 'react';
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import {
 	GlobalChartsProvider,
 	useChartId,
@@ -20,7 +12,7 @@ import {
 import { attachSubComponents } from '../../utils';
 import {
 	isValidHexColor,
-	lightenHexColor,
+	mixHexColors,
 	normalizeColorToHex,
 	prefersLightText,
 } from '../../utils/color-utils';
@@ -30,19 +22,18 @@ 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 { getValueExtent, getNormalizedValue, HeatmapLegend, isPresent } from './private';
+import {
+	getValueExtent,
+	getNormalizedValue,
+	HeatmapContext,
+	HeatmapLegend,
+	isPresent,
+} from './private';
+import type { HeatmapContextValue } from './private';
 import type { HeatmapChartProps, HeatmapTooltipData } from './types';
 import type { ResponsiveConfig } from '../private/with-responsive';
 import type { CSSProperties, FC } from 'react';
 
-export type HeatmapContextValue = {
-	extent: [ number, number ];
-	/** The resolved primary color (full intensity); the legend mixes toward it in CSS. */
-	primaryColorHex: string;
-};
-
-export const HeatmapContext = createContext< HeatmapContextValue | null >( null );
-
 // Mirrors the color-mix floor in heatmap-chart.module.scss (.heatmap-chart__cell--filled):
 // the rendered fill is the primary mixed over the chart background at 0.15 + 0.85 * intensity.
 const CELL_MIX_FLOOR = 0.15;
@@ -55,6 +46,10 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	className,
 	compact = false,
 	showValues,
+	maxCellWidth,
+	maxCellHeight,
+	minCellWidth,
+	minCellHeight,
 	rowLabels = [],
 	primaryColor,
 	gap = 'md',
@@ -63,7 +58,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	children,
 } ) => {
 	const chartId = useChartId( providedChartId );
-	const { getElementStyles, theme } = useGlobalChartsContext();
+	const { getElementStyles, resolveThemeColor, theme } = useGlobalChartsContext();
 	const { heatmapChart: heatmapChartSettings } = theme;
 	const { nonLegendChildren } = useChartChildren( children, 'HeatmapChart' );
 
@@ -84,14 +79,22 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		overrideColor: primaryColor || heatmapChartSettings.primaryColor,
 	} );
 
-	// Pick the in-cell text color from the cell's actual blended fill luminance (not the data
-	// value), so light text is only used where it out-contrasts dark text. Falls back to dark
-	// text when the primary isn't a resolvable hex (e.g. a bare CSS token).
+	// Resolve the background in the provider's theme scope so the blended-fill text
+	// color tracks a themed (e.g. dark) background.
+	const chartBackgroundHex = resolveThemeColor( theme.backgroundColor );
+
+	// Choose text color from the blended fill, not the raw value.
+	// If either color cannot resolve to hex, keep dark text.
 	const primaryHex = normalizeColorToHex( primaryColorHex );
 	const cellHasLightText = ( intensity: number ): boolean =>
 		isValidHexColor( primaryHex ) &&
+		isValidHexColor( chartBackgroundHex ) &&
 		prefersLightText(
-			lightenHexColor( primaryHex, 1 - ( CELL_MIX_FLOOR + ( 1 - CELL_MIX_FLOOR ) * intensity ) )
+			mixHexColors(
+				primaryHex,
+				chartBackgroundHex,
+				1 - ( CELL_MIX_FLOOR + ( 1 - CELL_MIX_FLOOR ) * intensity )
+			)
 		);
 
 	const extent = useMemo( () => getValueExtent( data ), [ data ] );
@@ -126,6 +129,11 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		hideTooltip();
 	}, [ hideTooltip ] );
 
+	const isCellHidden = useCallback(
+		( col: number, row: number ) => data[ col ]?.data[ row ]?.hidden === true,
+		[ data ]
+	);
+
 	const onChartKeyDown = useCallback(
 		( event: React.KeyboardEvent< HTMLDivElement > ) => {
 			if (
@@ -145,26 +153,46 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 			event.preventDefault();
 
 			if ( selectedIndex === undefined ) {
-				setSelectedIndex( 0 );
+				// 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 ) ) {
+						setSelectedIndex( index );
+						return;
+					}
+				}
 				return;
 			}
 
-			let col = Math.floor( selectedIndex / rows );
-			let row = selectedIndex % rows;
-
+			let stepCol = 0;
+			let stepRow = 0;
 			if ( event.key === 'ArrowRight' ) {
-				col = Math.min( col + 1, columns - 1 );
+				stepCol = 1;
 			} else if ( event.key === 'ArrowLeft' ) {
-				col = Math.max( col - 1, 0 );
+				stepCol = -1;
 			} else if ( event.key === 'ArrowDown' ) {
-				row = Math.min( row + 1, rows - 1 );
+				stepRow = 1;
 			} else if ( event.key === 'ArrowUp' ) {
-				row = Math.max( row - 1, 0 );
+				stepRow = -1;
+			}
+
+			// Step past hidden slots to the next navigable cell in the pressed
+			// direction; when only hidden slots (or the edge) remain that way,
+			// the selection stays put.
+			let col = Math.floor( selectedIndex / rows );
+			let row = selectedIndex % rows;
+			do {
+				col += stepCol;
+				row += stepRow;
+			} while ( col >= 0 && col < columns && row >= 0 && row < rows && isCellHidden( col, row ) );
+
+			if ( col < 0 || col >= columns || row < 0 || row >= rows ) {
+				return;
 			}
 
 			setSelectedIndex( col * rows + row );
 		},
-		[ rows, columns, selectedIndex, hideTooltip ]
+		[ rows, columns, selectedIndex, hideTooltip, isCellHidden ]
 	);
 
 	const handleCellMouseMove = useCallback(
@@ -244,11 +272,21 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		);
 	}
 
-	const trackSize = compact ? 'var(--heatmap-cell-size)' : 'minmax(0, 1fr)';
+	// Non-compact tracks split the container by default; a max cap makes them
+	// stop growing there instead, so sparse ranges keep sensible cell sizes,
+	// and a min floor makes the grid overflow (for a scrollable wrapper)
+	// rather than crushing cells on long ranges.
+	const columnTrack = compact
+		? 'var(--heatmap-cell-size)'
+		: `minmax(${ minCellWidth ?? 0 }px, ${ maxCellWidth ? `${ maxCellWidth }px` : '1fr' })`;
+	const rowTrack = compact
+		? 'var(--heatmap-cell-size)'
+		: `minmax(${ minCellHeight ?? 0 }px, ${ maxCellHeight ? `${ maxCellHeight }px` : '1fr' })`;
 	const gridStyle: Record< string, string | number > = {
 		'--heatmap-primary': primaryColorHex,
-		gridTemplateColumns: `auto repeat(${ columns }, ${ trackSize })`,
-		gridTemplateRows: `auto repeat(${ rows }, ${ trackSize })`,
+		'--heatmap-bg': theme.backgroundColor,
+		gridTemplateColumns: `auto repeat(${ columns }, ${ columnTrack })`,
+		gridTemplateRows: `auto repeat(${ rows }, ${ rowTrack })`,
 	};
 	if ( compact ) {
 		gridStyle[ '--heatmap-cell-gap' ] = `${ compactCellGap }px`;
@@ -260,6 +298,12 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 			? `${ chartId }-cell-${ Math.floor( selectedIndex / rows ) }-${ selectedIndex % rows }`
 			: undefined;
 
+	// A capped row track makes the chart content-sized vertically: neither the
+	// wrapper nor the grid stretches, or the leftover container height would
+	// land in the auto label row. A width-only cap must keep the normal vertical
+	// flex sizing, so it does not opt into this class.
+	const heightCapped = ! compact && Boolean( maxCellHeight );
+
 	return (
 		<HeatmapContext.Provider value={ heatmapContext }>
 			<SingleChartContext.Provider value={ { chartId } }>
@@ -269,7 +313,9 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 					legendChildren={ [] }
 					trailingContent={ nonLegendChildren }
 					gap={ gap }
-					className={ clsx( 'heatmap-chart', styles[ 'heatmap-chart' ], className ) }
+					className={ clsx( 'heatmap-chart', styles[ 'heatmap-chart' ], className, {
+						[ styles[ 'heatmap-chart--height-capped' ] ]: heightCapped,
+					} ) }
 					// Explicit dimensions (the unresponsive export) pin the size; otherwise
 					// width/height are unset and the grid fills its container via CSS. The
 					// responsive export drops the measured pixels so reflow stays fluid.
@@ -289,20 +335,22 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 						onKeyDown={ onChartKeyDown }
 						className={ clsx( styles[ 'heatmap-chart__grid' ], {
 							[ styles[ 'heatmap-chart__grid--compact' ] ]: compact,
+							[ styles[ 'heatmap-chart__grid--height-capped' ] ]: heightCapped,
 						} ) }
 						style={ gridStyle as CSSProperties }
 					>
-						{ /* Corner gutter + column labels; aria-hidden, since each cell's label carries the text. */ }
-						<span aria-hidden="true" />
-						{ data.map( ( column, columnIndex ) => (
-							<span
-								key={ `col-${ columnIndex }` }
-								aria-hidden="true"
-								className={ styles[ 'heatmap-chart__col-label' ] }
-							>
-								{ column.label }
-							</span>
-						) ) }
+						{ /* Header row preserves the grid structure; cell aria-labels include this text. */ }
+						<div role="row" aria-hidden="true" className={ styles[ 'heatmap-chart__row' ] }>
+							<span />
+							{ data.map( ( column, columnIndex ) => (
+								<span
+									key={ `col-${ columnIndex }` }
+									className={ styles[ 'heatmap-chart__col-label' ] }
+								>
+									{ column.label }
+								</span>
+							) ) }
+						</div>
 
 						{ Array.from( { length: rows } ).map( ( _row, rowIndex ) => {
 							const labelVisible = ! compact || rowIndex % 2 === 0;
@@ -318,6 +366,24 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 									</span>
 									{ data.map( ( column, columnIndex ) => {
 										const cell = column.data[ rowIndex ];
+
+										// A hidden cell keeps its grid slot (so the rest of the
+										// column doesn't shift) but paints nothing and takes no
+										// interaction — a calendar's ragged edges.
+										if ( cell?.hidden ) {
+											return (
+												<div
+													key={ `cell-${ columnIndex }-${ rowIndex }` }
+													data-testid="heatmap-cell-hidden"
+													aria-hidden="true"
+													className={ clsx(
+														styles[ 'heatmap-chart__cell' ],
+														styles[ 'heatmap-chart__cell--hidden' ]
+													) }
+												/>
+											);
+										}
+
 										const value = cell?.value ?? null;
 										const present = isPresent( value );
 										const normalized = present ? getNormalizedValue( value, extent ) : 0;
@@ -360,7 +426,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 											>
 												{ drawValues && present && (
 													<span className={ styles[ 'heatmap-chart__cell-value' ] }>
-														{ /* Compact so large values fit the cell; tooltip + aria-label keep full precision. */ }
+														{ /* Compact display; tooltip and aria-label keep full precision. */ }
 														{ formatNumberCompact( value ) }
 													</span>
 												) }

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

@@ -25,9 +25,19 @@ const toDate = ( point: DataPointDate ): Date | null => {
 
 export const buildCalendarHeatmapData = (
 	series: DataPointDate[],
-	options: { weekStartsOn?: 0 | 1 } = {}
+	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;
+	} = {}
 ): CalendarHeatmapResult => {
 	const weekStartsOn = options.weekStartsOn ?? 1;
+	const hideOutOfRangeDays = options.hideOutOfRangeDays ?? true;
 
 	const entries = series
 		.map( point => ( { date: toDate( point ), value: point.value } ) )
@@ -53,26 +63,51 @@ 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' );
+
 	const rowLabels = Array.from( { length: 7 }, ( _, row ) =>
 		LABELLED_ROWS.includes( row ) ? format( addDays( gridStart, row ), 'EEE' ) : ''
 	);
 
+	// 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();
+	let firstMonthWeeks = 0;
+	while (
+		firstMonthWeeks < weekCount &&
+		addDays( gridStart, firstMonthWeeks * 7 ).getMonth() === firstMonth
+	) {
+		firstMonthWeeks++;
+	}
+	const spansLaterMonth = firstMonthWeeks < weekCount;
+	const showFirstMonthLabel = ! spansLaterMonth || firstMonthWeeks >= MIN_FIRST_MONTH_WEEKS;
+
 	const data: HeatmapColumn[] = [];
 	let previousMonth = -1;
 	for ( let week = 0; week < weekCount; week++ ) {
 		const columnStart = addDays( gridStart, week * 7 );
 		const month = columnStart.getMonth();
-		const label = month !== previousMonth ? format( columnStart, 'MMM' ) : '';
+		const isNewMonth = month !== previousMonth;
+		const label =
+			isNewMonth && ( week !== 0 || showFirstMonthLabel ) ? format( columnStart, 'MMM' ) : '';
 		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' );
-			cells.push( {
+			const cell: HeatmapCell = {
 				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;
+			}
+			cells.push( cell );
 		}
 		data.push( { label, data: cells } );
 	}

package/src/charts/heatmap-chart/private/heatmap-context.ts

@@ -0,0 +1,10 @@
+import { createContext } from 'react';
+
+export type HeatmapContextValue = {
+	extent: [ number, number ];
+	/** The resolved primary color (full intensity); the legend mixes toward it in CSS. */
+	primaryColorHex: string;
+};
+
+/** Shared by the chart and legend without importing back from `heatmap-chart.tsx`. */
+export const HeatmapContext = createContext< HeatmapContextValue | null >( null );

package/src/charts/heatmap-chart/private/heatmap-legend.tsx

@@ -2,8 +2,8 @@ import { __ } from '@wordpress/i18n';
 import { Stack, Text } from '@wordpress/ui';
 import { useContext } from 'react';
 import { useGlobalChartsTheme } from '../../../providers';
-import { HeatmapContext } from '../heatmap-chart';
 import styles from '../heatmap-chart.module.scss';
+import { HeatmapContext } from './heatmap-context';
 import type { CSSProperties, FC } from 'react';
 
 export interface HeatmapLegendProps {
@@ -15,7 +15,7 @@ export interface HeatmapLegendProps {
 
 export const HeatmapLegend: FC< HeatmapLegendProps > = ( { steps = 5, lessLabel, moreLabel } ) => {
 	const context = useContext( HeatmapContext );
-	const { legend } = useGlobalChartsTheme();
+	const { legend, backgroundColor } = useGlobalChartsTheme();
 	if ( ! context ) {
 		return null;
 	}
@@ -38,6 +38,7 @@ export const HeatmapLegend: FC< HeatmapLegendProps > = ( { steps = 5, lessLabel,
 							style={
 								{
 									'--heatmap-primary': primaryColorHex,
+									'--heatmap-bg': backgroundColor,
 									'--intensity': intensity,
 								} as CSSProperties
 							}

package/src/charts/heatmap-chart/private/index.ts

@@ -1,5 +1,7 @@
 export { getValueExtent, getNormalizedValue, isPresent } from './use-heatmap-colors';
 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 { HeatmapLegendProps } from './heatmap-legend';
+export type { HeatmapContextValue } from './heatmap-context';

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

@@ -31,7 +31,11 @@ export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 };
 
 /**
- * Normalize a value to 0–1 within the extent. A flat extent (min === max) maps to 1.
+ * Normalize a value to 0–1 within the extent. A flat extent (min === max)
+ * maps to 1 — every cell is equally the "highest" — except an all-zero
+ * extent, which maps to 0 so a no-activity grid renders at the scale's
+ * bottom instead of full intensity.
+ *
  * @param value  - The value to normalize
  * @param extent - Tuple of [min, max] values for the normalization range
  * @return Normalized value between 0 and 1
@@ -39,7 +43,7 @@ export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 export const getNormalizedValue = ( value: number, extent: [ number, number ] ): number => {
 	const [ min, max ] = extent;
 	if ( min === max ) {
-		return 1;
+		return max === 0 ? 0 : 1;
 	}
 	return Math.min( 1, Math.max( 0, ( value - min ) / ( max - min ) ) );
 };

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

@@ -33,9 +33,43 @@ describe( 'buildCalendarHeatmapData', () => {
 		expect( data[ 0 ].data[ 1 ].value ).toBeNull(); // Tue Jan 2 has no datum
 	} );
 
+	test( 'hides the week-completion days outside the span by default', () => {
+		const midWeek: DataPointDate[] = [
+			{ dateString: '2024-01-03', value: 5 }, // Wed
+			{ dateString: '2024-01-09', value: 2 }, // Tue (2nd week)
+		];
+		const { data } = buildCalendarHeatmapData( midWeek, {
+			weekStartsOn: 1,
+		} );
+
+		// Mon Jan 1 and Tue Jan 2 precede the span — hidden; Wed Jan 3 opens it.
+		expect( data[ 0 ].data[ 0 ].hidden ).toBe( true );
+		expect( data[ 0 ].data[ 1 ].hidden ).toBe( true );
+		expect( data[ 0 ].data[ 2 ].hidden ).toBeUndefined();
+
+		// Thu Jan 4 is inside the span with no entry — a blank cell, not hidden.
+		expect( data[ 0 ].data[ 3 ].hidden ).toBeUndefined();
+		expect( data[ 0 ].data[ 3 ].value ).toBeNull();
+
+		// Tue Jan 9 closes the span; Wed Jan 10 onward is hidden.
+		expect( data[ 1 ].data[ 1 ].hidden ).toBeUndefined();
+		expect( data[ 1 ].data[ 2 ].hidden ).toBe( true );
+		expect( data[ 1 ].data[ 6 ].hidden ).toBe( true );
+	} );
+
+	test( 'out-of-span days stay blank cells when hideOutOfRangeDays is false', () => {
+		const midWeek: DataPointDate[] = [ { dateString: '2024-01-03', value: 5 } ]; // Wed
+		const { data } = buildCalendarHeatmapData( midWeek, {
+			weekStartsOn: 1,
+			hideOutOfRangeDays: false,
+		} );
+		expect( data[ 0 ].data[ 0 ].hidden ).toBeUndefined();
+		expect( data[ 0 ].data[ 0 ].value ).toBeNull();
+	} );
+
 	test( 'labels only the first column of each month', () => {
 		const multiMonth: DataPointDate[] = [
-			{ dateString: '2024-01-29', value: 1 },
+			{ dateString: '2024-01-01', value: 1 },
 			{ dateString: '2024-02-05', value: 1 },
 		];
 		const { data } = buildCalendarHeatmapData( multiMonth );
@@ -44,6 +78,28 @@ describe( 'buildCalendarHeatmapData', () => {
 		expect( labels ).toContain( 'Feb' );
 	} );
 
+	test( 'suppresses a partial first month label so it cannot collide with the next', () => {
+		// Jan 29 is the only January column; February should be the first visible label.
+		const partialFirstMonth: DataPointDate[] = [
+			{ dateString: '2024-01-29', value: 1 },
+			{ dateString: '2024-02-05', value: 1 },
+		];
+		const { data } = buildCalendarHeatmapData( partialFirstMonth, { weekStartsOn: 1 } );
+		expect( data[ 0 ].label ).toBe( '' );
+		expect( data.map( c => c.label ).filter( Boolean )[ 0 ] ).toBe( 'Feb' );
+	} );
+
+	test( 'keeps the first month label when the range never reaches a second month', () => {
+		// Single-month ranges keep their lone month label.
+		const singleMonth: DataPointDate[] = [
+			{ dateString: '2024-01-01', value: 1 },
+			{ dateString: '2024-01-03', value: 2 },
+		];
+		const { data } = buildCalendarHeatmapData( singleMonth, { weekStartsOn: 1 } );
+		expect( data ).toHaveLength( 1 );
+		expect( data[ 0 ].label ).toBe( 'Jan' );
+	} );
+
 	test( 'filters out entries with unparseable or missing dates', () => {
 		const mixed: DataPointDate[] = [
 			{ dateString: '2024-01-01', value: 3 },