@automattic/charts 4.6.0 → 4.8.0

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

@@ -0,0 +1,74 @@
+import { MIN_BACKGROUND_CONTRAST } from '../../../providers/chart-context/private/palette-generator';
+import { contrastRatio } from '../../../providers/chart-context/private/perceptual-color';
+import { mixHexColors, relativeLuminance } from '../../../utils/color-utils';
+
+/** Contrast the highest step aims for against the background, so the steps stay apart. */
+export const HEATMAP_HIGH_CONTRAST = 9;
+
+const STEPS = 200;
+
+export type HeatmapScale = {
+	low: string;
+	high: string;
+};
+
+// Measured on the rounded hex the browser paints, so an endpoint never lands under its threshold.
+const firstMeeting = ( from: string, to: string, meets: ( color: string ) => boolean ) => {
+	for ( let step = 0; step <= STEPS; step++ ) {
+		const color = mixHexColors( from, to, step / STEPS );
+		if ( meets( color ) ) {
+			return color;
+		}
+	}
+	return null;
+};
+
+/**
+ * The two ends of the heatmap fill scale: 3:1 against the background and the empty cell at the
+ * low end, toward 9:1 against the background at the high end.
+ *
+ * @param primary    - The resolved primary color, as six-digit hex.
+ * @param background - The resolved chart background, as six-digit hex.
+ * @param emptyCell  - The resolved empty-cell color, as six-digit hex, when it is opaque.
+ * @return The scale ends, as six-digit hex.
+ */
+export const getHeatmapScale = (
+	primary: string,
+	background: string,
+	emptyCell?: string | null
+): HeatmapScale => {
+	const primaryStandsOut = contrastRatio( primary, background ) >= MIN_BACKGROUND_CONTRAST;
+	// The scale deepens to black or white on the primary's own side of the background, so it never
+	// crosses it. A primary too close to the background takes whichever contrasts more.
+	const towardWhite = primaryStandsOut
+		? relativeLuminance( primary ) > relativeLuminance( background )
+		: contrastRatio( '#ffffff', background ) > contrastRatio( '#000000', background );
+	const extreme = towardWhite ? '#ffffff' : '#000000';
+
+	const lowAgainst = ( references: string[] ) => {
+		const meets = ( color: string ) =>
+			references.every( reference => contrastRatio( color, reference ) >= MIN_BACKGROUND_CONTRAST );
+		return (
+			( primaryStandsOut ? firstMeeting( background, primary, meets ) : null ) ??
+			firstMeeting( primary, extreme, meets )
+		);
+	};
+	// Only `high` can miss: black or white tops out near 4.58:1 on a mid-tone background.
+	const high =
+		firstMeeting(
+			primary,
+			extreme,
+			color => contrastRatio( color, background ) >= HEATMAP_HIGH_CONTRAST
+		) ?? extreme;
+
+	// The lowest step sits beside empty cells, so it stands apart from them too, unless an
+	// empty-cell color far from the background would push it past the high end.
+	const againstEmptyCell = emptyCell ? lowAgainst( [ background, emptyCell ] ) : null;
+	const low =
+		againstEmptyCell &&
+		contrastRatio( againstEmptyCell, background ) <= contrastRatio( high, background )
+			? againstEmptyCell
+			: lowAgainst( [ background ] );
+
+	return { low: low ?? extreme, high };
+};

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

@@ -1,4 +1,5 @@
-export { getValueExtent, getNormalizedValue, isPresent } from './use-heatmap-colors';
+export { getValueExtent, getNormalizedValue, isEmptyValue, isPresent } from './use-heatmap-colors';
+export { getHeatmapScale } from './heatmap-scale';
 export { HeatmapLegend } from './heatmap-legend';
 export { HeatmapContext } from './heatmap-context';
 export type { HeatmapLegendProps } from './heatmap-legend';

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

@@ -4,14 +4,16 @@ export const isPresent = ( value: number | null | undefined ): value is number =
 	value !== null && value !== undefined && ! isNaN( value );
 
 /**
- * Get the min and max values from heatmap data, ignoring null/NaN. Summary
- * columns stay out: a roll-up on the scale would flatten every real cell.
+ * Get the min and max values from heatmap data, ignoring null/NaN and the zeros
+ * `isEmptyValue` paints as empty. Summary columns stay out: a roll-up on the
+ * scale would flatten every real cell.
  * @param data - The heatmap columns
  * @return Tuple of [min, max] values
  */
 export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 	let min = Infinity;
 	let max = -Infinity;
+	let hasZero = false;
 	for ( const column of data ) {
 		if ( column.summary ) {
 			continue;
@@ -20,6 +22,10 @@ export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 			if ( ! isPresent( cell.value ) ) {
 				continue;
 			}
+			if ( cell.value === 0 ) {
+				hasZero = true;
+				continue;
+			}
 			if ( cell.value < min ) {
 				min = cell.value;
 			}
@@ -28,17 +34,29 @@ export const getValueExtent = ( data: HeatmapColumn[] ): [ number, number ] => {
 			}
 		}
 	}
+	if ( hasZero && min < 0 ) {
+		max = Math.max( max, 0 );
+	}
 	if ( min === Infinity ) {
 		return [ 0, 0 ];
 	}
 	return [ min, max ];
 };
 
+/**
+ * Whether a value paints as an empty cell: a zero in data with no negatives
+ * counts nothing, so it must not look like the lowest step of activity.
+ *
+ * @param value  - The cell value
+ * @param extent - The extent from `getValueExtent`
+ * @return True when the cell takes the empty-cell color
+ */
+export const isEmptyValue = ( value: number, extent: [ number, number ] ): boolean =>
+	value === 0 && extent[ 0 ] >= 0;
+
 /**
  * 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.
+ * maps to 1, since every cell is equally the "highest".
  *
  * @param value  - The value to normalize
  * @param extent - Tuple of [min, max] values for the normalization range
@@ -47,7 +65,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 max === 0 ? 0 : 1;
+		return 1;
 	}
 	return Math.min( 1, Math.max( 0, ( value - min ) / ( max - min ) ) );
 };

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

@@ -85,34 +85,22 @@ describe( 'HeatmapChart', () => {
 		await expect( screen.findByRole( 'tooltip' ) ).resolves.toBeInTheDocument();
 	} );
 
-	test( 'draws the light tooltip box by default', async () => {
-		renderChart( { withTooltips: true, rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
-		await userEvent.setup().hover( screen.getAllByTestId( 'heatmap-cell' )[ 0 ] );
-		await expect( screen.findByRole( 'tooltip' ) ).resolves.toBeInTheDocument();
-		const box = screen.getByTestId( 'bounded-tooltip' );
-		expect( box ).not.toHaveClass( 'surface' );
-		expect( box ).toHaveStyle( { backgroundColor: 'rgb(255, 255, 255)' } );
-		expect( box ).toHaveStyle( { zIndex: 3 } );
-	} );
-
-	test( 'draws the dark variant on the package tooltip surface, not the visx box', async () => {
-		renderChart( {
-			withTooltips: true,
-			tooltipVariant: 'dark',
-			rowLabels: [ 'Mon', 'Tue', 'Wed' ],
-		} );
-		await userEvent.setup().hover( screen.getAllByTestId( 'heatmap-cell' )[ 0 ] );
-		await expect( screen.findByRole( 'tooltip' ) ).resolves.toBeInTheDocument();
-		const box = screen.getByTestId( 'bounded-tooltip' );
-		expect( box ).toHaveClass( 'surface' );
-		expect( box ).not.toHaveStyle( { backgroundColor: 'rgb(255, 255, 255)' } );
-		expect( box ).not.toHaveStyle( { color: 'rgb(102, 102, 102)' } );
-	} );
+	test.each( [ undefined, 'light', 'dark' ] as const )(
+		'draws the tooltip on the package surface for tooltipVariant %s',
+		async tooltipVariant => {
+			renderChart( { withTooltips: true, tooltipVariant, rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
+			await userEvent.setup().hover( screen.getAllByTestId( 'heatmap-cell' )[ 0 ] );
+			await expect( screen.findByRole( 'tooltip' ) ).resolves.toBeInTheDocument();
+			const box = screen.getByTestId( 'bounded-tooltip' );
+			expect( box ).toHaveClass( 'surface' );
+			expect( box ).not.toHaveAttribute( 'style', expect.stringContaining( 'background' ) );
+			expect( box ).toHaveStyle( { zIndex: 3 } );
+		}
+	);
 
-	test( 'merges tooltipStyle over the variant box styles', async () => {
+	test( 'merges tooltipStyle over the box styles', async () => {
 		renderChart( {
 			withTooltips: true,
-			tooltipVariant: 'dark',
 			tooltipStyle: { padding: '2px 4px' },
 			rowLabels: [ 'Mon', 'Tue', 'Wed' ],
 		} );
@@ -184,6 +172,26 @@ describe( 'HeatmapChart', () => {
 		).toHaveLength( 4 );
 	} );
 
+	test( 'paints the legend on the same scale as the cells', () => {
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } primaryColor="#3858e9">
+					<HeatmapChart.Legend />
+				</HeatmapChart>
+			</GlobalChartsProvider>
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+
+		for ( const swatch of screen.getAllByTestId( 'heatmap-legend-swatch' ) ) {
+			for ( const end of [ 'primary', 'low', 'high' ] ) {
+				const property = `--a8c-charts-color-heatmap-${ end }`;
+				expect( swatch.style.getPropertyValue( property ) ).toBe(
+					grid.style.getPropertyValue( property )
+				);
+			}
+		}
+	} );
+
 	test( 'ArrowDown moves focus within a column, ArrowRight moves to next column', async () => {
 		renderChart( { rowLabels: [ 'Mon', 'Tue', 'Wed' ] } );
 		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
@@ -421,6 +429,78 @@ describe( 'HeatmapChart', () => {
 		expect( grid.style.getPropertyValue( '--a8c-charts-color-heatmap-primary' ) ).toBe( '#abcdef' );
 	} );
 
+	test( 'leaves the fill to the stylesheet when the primary color cannot resolve to hex', () => {
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } primaryColor="oklch(0.6 0.2 260)">
+					<HeatmapChart.Legend />
+				</HeatmapChart>
+			</GlobalChartsProvider>
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+		const swatches = screen.getAllByTestId( 'heatmap-legend-swatch' );
+
+		for ( const element of [ grid, ...swatches ] ) {
+			expect( element.style.getPropertyValue( '--a8c-charts-color-heatmap-primary' ) ).toBe(
+				'oklch(0.6 0.2 260)'
+			);
+			expect( element.style.getPropertyValue( '--a8c-charts-color-heatmap-low' ) ).toBe( '' );
+			expect( element.style.getPropertyValue( '--a8c-charts-color-heatmap-high' ) ).toBe( '' );
+		}
+		expect( screen.getByText( '4' ) ).toHaveClass( 'heatmap-chart__cell-value', { exact: true } );
+	} );
+
+	test( 'builds the scale for white on a see-through background, as the palette does', () => {
+		const scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-background', 'transparent' );
+		document.body.appendChild( scope );
+
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } primaryColor="#3858e9" />
+			</GlobalChartsProvider>,
+			{ container: scope }
+		);
+		const grid = screen.getByRole( 'grid', { name: /heatmap/i } );
+
+		expect( grid.style.getPropertyValue( '--a8c-charts-color-heatmap-low' ) ).toBe( '#6c83ef' );
+		expect( grid.style.getPropertyValue( '--a8c-charts-color-heatmap-high' ) ).toBe( '#283ea5' );
+
+		document.body.removeChild( scope );
+	} );
+
+	test( 'reads the computed style once per re-render for the fill scale', () => {
+		const { rerender } = renderChart();
+		const spy = jest.spyOn( window, 'getComputedStyle' );
+
+		rerender(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ data } />
+			</GlobalChartsProvider>
+		);
+
+		expect( spy ).toHaveBeenCalledTimes( 1 );
+		spy.mockRestore();
+	} );
+
+	test( 'paints a zero as an empty cell, still announcing its value', () => {
+		renderChart();
+		const zero = screen.getByRole( 'gridcell', { name: 'W2: 0' } );
+
+		expect( zero ).not.toHaveClass( 'heatmap-chart__cell--filled' );
+		expect( zero.style.getPropertyValue( '--a8c-charts-heatmap-cell-intensity' ) ).toBe( '' );
+		expect( screen.getByRole( 'gridcell', { name: 'W1: 1' } ) ).toHaveClass(
+			'heatmap-chart__cell--filled'
+		);
+	} );
+
+	test( 'puts the lowest non-zero value on the lowest step', () => {
+		renderChart();
+		const lowest = screen.getByRole( 'gridcell', { name: 'W1: 1' } );
+
+		expect( lowest.style.getPropertyValue( '--a8c-charts-heatmap-cell-intensity' ) ).toBe( '0' );
+	} );
+
 	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' );
@@ -480,6 +560,122 @@ const mockRects = () =>
 		} as DOMRect;
 	} );
 
+describe( 'HeatmapChart value text contrast', () => {
+	// The low end, a mid-tone, and the high end of the scale.
+	const scale: HeatmapColumn[] = [
+		{ label: 'W1', data: [ { value: 1 }, { value: 30 }, { value: 100 } ] },
+	];
+
+	let injectedStyle: HTMLStyleElement | null = null;
+
+	afterEach( () => {
+		injectedStyle?.remove();
+		injectedStyle = null;
+	} );
+
+	const renderScale = ( className?: string ) =>
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart
+					width={ 500 }
+					height={ 300 }
+					data={ scale }
+					primaryColor="#3858e9"
+					className={ className }
+				/>
+			</GlobalChartsProvider>
+		);
+
+	test( 'picks the label role that reaches AA on light and dark cells', () => {
+		renderScale();
+
+		expect( screen.getByText( '1' ) ).toHaveClass( 'heatmap-chart__cell-value', { exact: true } );
+		expect( screen.getByText( '100' ) ).toHaveClass( 'heatmap-chart__cell-value--inverse' );
+	} );
+
+	test( 'falls back to black on a mid-tone cell where neither role reaches AA', () => {
+		renderScale();
+
+		expect( screen.getByText( '30' ) ).toHaveClass( 'heatmap-chart__cell-value--black' );
+	} );
+
+	test( 'reads the label roles once data arrives after an empty first render', () => {
+		const { rerender } = render(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ [] } primaryColor="#3858e9" />
+			</GlobalChartsProvider>
+		);
+
+		rerender(
+			<GlobalChartsProvider>
+				<HeatmapChart width={ 500 } height={ 300 } data={ scale } primaryColor="#3858e9" />
+			</GlobalChartsProvider>
+		);
+
+		expect( screen.getByText( '100' ) ).toHaveClass( 'heatmap-chart__cell-value--inverse' );
+	} );
+
+	test( 'falls back to black or white when a label role uses syntax it cannot read', () => {
+		injectedStyle = document.createElement( 'style' );
+		injectedStyle.textContent =
+			'.modern-heatmap { --a8c-charts-color-label-inverse: rgb(255 255 255); }';
+		document.head.appendChild( injectedStyle );
+
+		renderScale( 'modern-heatmap' );
+
+		expect( screen.getByText( '100' ) ).toHaveClass( 'heatmap-chart__cell-value--white' );
+	} );
+
+	test( 'measures a translucent label role as it paints over each cell', () => {
+		injectedStyle = document.createElement( 'style' );
+		injectedStyle.textContent =
+			'.translucent-heatmap { --a8c-charts-color-label: rgba(30, 30, 30, 0.3); }';
+		document.head.appendChild( injectedStyle );
+
+		renderScale( 'translucent-heatmap' );
+
+		expect( screen.getByText( '1' ) ).toHaveClass( 'heatmap-chart__cell-value--black' );
+		expect( screen.getByText( '100' ) ).toHaveClass( 'heatmap-chart__cell-value--inverse' );
+	} );
+
+	test( 'leaves a summary value, which sits on no fill, on the default role', () => {
+		injectedStyle = document.createElement( 'style' );
+		injectedStyle.textContent =
+			'.swapped-heatmap { --a8c-charts-color-label: #f0f0f0; --a8c-charts-color-label-inverse: #1e1e1e; }';
+		document.head.appendChild( injectedStyle );
+
+		render(
+			<GlobalChartsProvider>
+				<HeatmapChart
+					width={ 500 }
+					height={ 300 }
+					className="swapped-heatmap"
+					primaryColor="#3858e9"
+					data={ [ ...scale, { label: 'Total', summary: true, data: [ { value: 7 } ] } ] }
+				/>
+			</GlobalChartsProvider>
+		);
+
+		expect( screen.getByText( '7' ) ).toHaveClass( 'heatmap-chart__cell-value', { exact: true } );
+		expect( screen.getByText( '1' ) ).toHaveClass( 'heatmap-chart__cell-value--inverse' );
+	} );
+
+	test( "keeps one color when both label roles are set to it on the chart's own class", () => {
+		injectedStyle = document.createElement( 'style' );
+		injectedStyle.textContent =
+			'.pinned-heatmap { --a8c-charts-color-label: #767676; --a8c-charts-color-label-inverse: #767676; }';
+		document.head.appendChild( injectedStyle );
+
+		renderScale( 'pinned-heatmap' );
+
+		[ '1', '30', '100' ].forEach( value =>
+			expect( screen.getByText( value ) ).toHaveClass( 'heatmap-chart__cell-value', {
+				exact: true,
+			} )
+		);
+	} );
+} );
+
 describe( 'HeatmapChart keyboard tooltip', () => {
 	test( 'opens on the selected cell without row labels', async () => {
 		renderChart( { withTooltips: true } );

package/src/charts/heatmap-chart/test/heatmap-scale.test.ts

@@ -0,0 +1,78 @@
+import { MIN_BACKGROUND_CONTRAST } from '../../../providers/chart-context/private/palette-generator';
+import { contrastRatio } from '../../../providers/chart-context/private/perceptual-color';
+import { mixHexColors } from '../../../utils/color-utils';
+import { getHeatmapScale, HEATMAP_HIGH_CONTRAST } from '../private/heatmap-scale';
+
+// The wp-admin scheme colors, then the pre-7.0 ones, which include a sunrise below 3:1 on white.
+const PRIMARIES = [
+	'#007cba',
+	'#3858e9',
+	'#437aa8',
+	'#916745',
+	'#646c3e',
+	'#cf4339',
+	'#567958',
+	'#ad631e',
+	'#0085ba',
+	'#dd823b',
+];
+
+describe.each( [
+	[ 'light', '#ffffff', '#f0f0f0' ],
+	[ 'dark', '#242424', '#272727' ],
+] )( 'getHeatmapScale on a %s background', ( _mode, background, emptyCell ) => {
+	it.each( PRIMARIES )(
+		'keeps the lowest step of %s at 3:1 against the background and empty cell, no further',
+		primary => {
+			const { low } = getHeatmapScale( primary, background, emptyCell );
+			const contrasts = [ contrastRatio( low, background ), contrastRatio( low, emptyCell ) ];
+
+			expect( Math.min( ...contrasts ) ).toBeGreaterThanOrEqual( MIN_BACKGROUND_CONTRAST );
+			expect( Math.min( ...contrasts ) ).toBeLessThan( MIN_BACKGROUND_CONTRAST + 0.1 );
+		}
+	);
+
+	it.each( PRIMARIES )( 'runs the scale of %s out to 9:1', primary => {
+		const { high } = getHeatmapScale( primary, background );
+
+		expect( contrastRatio( high, background ) ).toBeGreaterThanOrEqual( HEATMAP_HIGH_CONTRAST );
+	} );
+} );
+
+describe( 'getHeatmapScale', () => {
+	it( 'keeps a primary already past 9:1 as the high end', () => {
+		expect( getHeatmapScale( '#1d2327', '#ffffff' ).high ).toBe( '#1d2327' );
+	} );
+
+	it.each( [
+		[ '#ffffff', '#808080' ],
+		[ '#ffd000', '#767676' ],
+		[ '#3858e9', '#808080' ],
+		[ '#1e1e1e', '#999999' ],
+	] )( 'keeps every step of %s at 3:1 on a mid-gray %s', ( primary, background ) => {
+		const { low, high } = getHeatmapScale( primary, background );
+
+		for ( let step = 0; step <= 20; step++ ) {
+			expect(
+				contrastRatio( mixHexColors( low, high, step / 20 ), background )
+			).toBeGreaterThanOrEqual( MIN_BACKGROUND_CONTRAST );
+		}
+	} );
+
+	it.each( [
+		[ 'no step clears it', '#ffffff', '#555555' ],
+		[ 'clearing it would pass the high end', '#ffffff', '#767676' ],
+		[ 'clearing it would pass the high end', '#1e1e1e', '#6b6b6b' ],
+	] )(
+		'measures against the background alone when %s (%s, %s)',
+		( _case, background, emptyCell ) => {
+			expect( getHeatmapScale( '#3858e9', background, emptyCell ) ).toEqual(
+				getHeatmapScale( '#3858e9', background )
+			);
+		}
+	);
+
+	it( 'ends on black or white when the background leaves no room for 9:1', () => {
+		expect( getHeatmapScale( '#3858e9', '#808080' ).high ).toBe( '#000000' );
+	} );
+} );

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

@@ -1,4 +1,4 @@
-import { getValueExtent, getNormalizedValue } from '../private/use-heatmap-colors';
+import { getValueExtent, getNormalizedValue, isEmptyValue } from '../private/use-heatmap-colors';
 import type { HeatmapColumn } from '../types';
 
 const data: HeatmapColumn[] = [
@@ -7,8 +7,12 @@ const data: HeatmapColumn[] = [
 ];
 
 describe( 'getValueExtent', () => {
-	test( 'returns [min, max] ignoring null/NaN', () => {
-		expect( getValueExtent( data ) ).toEqual( [ 0, 20 ] );
+	test( 'returns [min, max] ignoring null/NaN and empty zeros', () => {
+		expect( getValueExtent( data ) ).toEqual( [ 5, 20 ] );
+	} );
+
+	test( 'keeps a zero in the extent when the data has negatives', () => {
+		expect( getValueExtent( [ { data: [ { value: -4 }, { value: 0 } ] } ] ) ).toEqual( [ -4, 0 ] );
 	} );
 
 	test( 'leaves summary columns out of the extent', () => {
@@ -16,11 +20,12 @@ describe( 'getValueExtent', () => {
 			...data,
 			{ label: 'Total', summary: true, data: [ { value: 500 }, { value: 900 }, { value: null } ] },
 		];
-		expect( getValueExtent( withTotals ) ).toEqual( [ 0, 20 ] );
+		expect( getValueExtent( withTotals ) ).toEqual( [ 5, 20 ] );
 	} );
 
 	test( 'returns [0, 0] for all-empty data', () => {
 		expect( getValueExtent( [ { data: [ { value: null } ] } ] ) ).toEqual( [ 0, 0 ] );
+		expect( getValueExtent( [ { data: [ { value: 0 }, { value: 0 } ] } ] ) ).toEqual( [ 0, 0 ] );
 	} );
 } );
 
@@ -39,8 +44,15 @@ describe( 'getNormalizedValue', () => {
 	test( 'returns 1 when min === max', () => {
 		expect( getNormalizedValue( 7, [ 7, 7 ] ) ).toBe( 1 );
 	} );
+} );
+
+describe( 'isEmptyValue', () => {
+	test( 'paints a zero as empty in data with no negatives', () => {
+		expect( isEmptyValue( 0, [ 0, 20 ] ) ).toBe( true );
+		expect( isEmptyValue( 5, [ 0, 20 ] ) ).toBe( false );
+	} );
 
-	test( 'returns 0 for an all-zero extent so a no-activity grid stays at the scale bottom', () => {
-		expect( getNormalizedValue( 0, [ 0, 0 ] ) ).toBe( 0 );
+	test( 'keeps a zero on the scale when the data has negatives', () => {
+		expect( isEmptyValue( 0, [ -4, 6 ] ) ).toBe( false );
 	} );
 } );

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

@@ -1,7 +1,7 @@
 import type { BaseChartProps } from '../../types';
 import type { CSSProperties, ReactNode } from 'react';
 
-/** A single heatmap cell. `value: null` marks an empty cell. */
+/** A single heatmap cell. `value: null` marks an empty cell, as does a zero when no value is negative. */
 export type HeatmapCell = {
 	/** Per-cell label used in the tooltip / accessible name. */
 	label?: string;
@@ -102,18 +102,15 @@ export interface HeatmapChartProps extends Omit<
 	/** Floor a cell's height (px) in non-compact mode; see `minCellWidth`. */
 	minCellHeight?: number;
 	/**
-	 * Color the cell scale interpolates toward at the highest value. Defaults to the
-	 * first series palette slot, `--a8c-charts-color-series-1`.
+	 * Color the cell scale is built from, deepened at the highest value toward 9:1
+	 * against the background. Defaults to the first series palette slot,
+	 * `--a8c-charts-color-series-1`.
 	 */
 	primaryColor?: string;
 	renderTooltip?: ( data: HeatmapTooltipData ) => ReactNode;
-	/**
-	 * The tooltip box: `light` is the plain white box, `dark` the package's
-	 * tooltip surface, themed through `--a8c-charts-color-tooltip-surface`.
-	 * Default `light`.
-	 */
+	/** @deprecated Every tooltip draws on the package tooltip surface; this prop has no effect. */
 	tooltipVariant?: 'light' | 'dark';
-	/** Inline styles merged onto the tooltip box, over the variant's own. */
+	/** Inline styles merged onto the tooltip box, over the surface's own. */
 	tooltipStyle?: CSSProperties;
 	children?: ReactNode;
 }

package/src/charts/line-chart/crosshair-style-types.fixture.ts

@@ -0,0 +1,23 @@
+/* istanbul ignore file */ // Compile-only: tsgo checks these assignments; nothing imports or runs them.
+import type { LineChartProps } from './types';
+
+type Crosshairs = NonNullable< LineChartProps[ 'withTooltipCrosshairs' ] >;
+
+export const paintCrosshairs: Crosshairs = {
+	verticalStyle: { stroke: 'purple', strokeWidth: 2 },
+};
+
+export const coordinateCrosshairs: Crosshairs = {
+	// @ts-expect-error Crosshair coordinates are computed from the active datum.
+	verticalStyle: { x1: 12 },
+};
+
+export const transformedCrosshairs: Crosshairs = {
+	// @ts-expect-error Crosshair transforms are not paint attributes.
+	verticalStyle: { transform: 'translate(100 0)' },
+};
+
+export const transformedStyles: Crosshairs = {
+	// @ts-expect-error Inline crosshair styles accept only paint properties.
+	horizontalStyle: { style: { transform: 'translateX(100px)' } },
+};

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

@@ -17,7 +17,6 @@
 		overflow: visible;
 	}
 
-	&__tooltip,
 	&__annotation-label-popover {
 		background: var(--a8c-charts-color-surface);
 		color: var(--a8c-charts-color-label);
@@ -29,10 +28,6 @@
 		padding-bottom: var(--wpds-dimension-padding-md);
 	}
 
-	&__tooltip-row {
-		padding: var(--wpds-dimension-padding-xs) 0;
-	}
-
 	&__tooltip-label {
 		font-weight: var(--wpds-typography-font-weight-emphasis);
 		padding-right: var(--wpds-dimension-padding-lg);