@automattic/charts 4.5.0 → 4.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "4.5.0",
+	"version": "4.7.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {

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

@@ -114,16 +114,6 @@
 	}
 }
 
-.tooltip-wrapper {
-	background: var(--a8c-charts-color-surface);
-
-	// Override .visx-tooltip inline styles.
-	border-radius: var(--wpds-border-radius-md) !important;
-	padding: var(--wpds-dimension-padding-md) !important;
-	box-shadow: var(--a8c-charts-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005) !important;
-
-}
-
 .tooltip-title {
 	color: var(--a8c-charts-color-label);
 	font-size: var(--wpds-typography-font-size-sm);

package/src/charts/conversion-funnel-chart/conversion-funnel-chart.tsx

@@ -36,6 +36,7 @@ import type { FunnelStep, ConversionFunnelChartProps } from './types';
  * @param props.renderStepRate   - Custom render function for step rates
  * @param props.renderMainMetric - Custom render function for the entire main metric section
  * @param props.renderTooltip    - Custom render function for tooltip content
+ * @param props.tooltipStyle     - Inline styles merged over the tooltip box defaults
  * @return JSX element representing the conversion funnel chart
  */
 const ConversionFunnelChartInternal: FC< ConversionFunnelChartProps > = ( {
@@ -52,6 +53,7 @@ const ConversionFunnelChartInternal: FC< ConversionFunnelChartProps > = ( {
 	renderStepRate,
 	renderMainMetric,
 	renderTooltip,
+	tooltipStyle,
 } ) => {
 	const chartId = useChartId( providedChartId );
 	const { getElementStyles, isColorPaletteResolved } = useGlobalChartsContext();
@@ -412,7 +414,6 @@ const ConversionFunnelChartInternal: FC< ConversionFunnelChartProps > = ( {
 								index: steps.findIndex( s => s.id === ( tooltipData as FunnelStep ).id ),
 								top: tooltipTop,
 								left: tooltipLeft,
-								className: styles[ 'tooltip-wrapper' ],
 							} )
 						: renderDefaultTooltip( tooltipData as FunnelStep );
 
@@ -423,7 +424,8 @@ const ConversionFunnelChartInternal: FC< ConversionFunnelChartProps > = ( {
 						<BoundedTooltip
 							top={ tooltipTop }
 							left={ tooltipLeft }
-							className={ clsx( standaloneScopeClass, styles[ 'tooltip-wrapper' ] ) }
+							className={ standaloneScopeClass }
+							style={ tooltipStyle }
 						>
 							{ tooltipContent }
 						</BoundedTooltip>

package/src/charts/conversion-funnel-chart/test/conversion-funnel-chart.test.tsx

@@ -427,10 +427,20 @@ describe( 'ConversionFunnelChart', () => {
 				index: 1,
 				top: expect.any( Number ),
 				left: expect.any( Number ),
-				className: 'tooltip-wrapper',
 			} );
 		} );
 
+		it( 'merges tooltipStyle onto the tooltip box', async () => {
+			const user = userEvent.setup();
+			renderWithoutTheme(
+				<ConversionFunnelChart { ...defaultProps } tooltipStyle={ { background: 'purple' } } />
+			);
+
+			await user.click( screen.getByRole( 'button', { name: /cart/i } ) );
+
+			expect( screen.getByTestId( 'bounded-tooltip' ) ).toHaveStyle( { background: 'purple' } );
+		} );
+
 		it( 'disables tooltip when renderTooltip returns null', async () => {
 			const user = userEvent.setup();
 			const customRenderTooltip = jest.fn( () => null );

package/src/charts/conversion-funnel-chart/types.ts

@@ -50,6 +50,7 @@ export interface TooltipRenderProps {
 	index: number;
 	top: number;
 	left: number;
+	/** @deprecated The tooltip box draws the package surface; this is no longer set. */
 	className?: string;
 }
 
@@ -80,4 +81,6 @@ export interface ConversionFunnelChartProps extends Pick<
 	renderMainMetric?: ( props: MainMetricRenderProps ) => React.ReactNode;
 	/** Custom render function for tooltip content */
 	renderTooltip?: ( props: TooltipRenderProps ) => React.ReactNode;
+	/** Inline styles merged over the tooltip box defaults. */
+	tooltipStyle?: React.CSSProperties;
 }

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

@@ -130,6 +130,7 @@ function normalizeGeoChartError( eventArgs: unknown ): GeoChartError {
  * @param props.height            - Height of the chart in pixels
  * @param props.region            - Region to display ('world', 'US', or ISO 3166-1 alpha-2 code)
  * @param props.resolution        - Resolution level ('countries', 'provinces', or 'metros')
+ * @param props.displayMode       - Plot rows as shaded areas ('regions') or markers ('markers')
  * @param props.domain            - Country code whose viewpoint sets the disputed borders
  * @param props.onError           - Optional callback for Google Charts errors
  * @param props.className         - Additional CSS class name for the chart container
@@ -143,6 +144,7 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 	height,
 	region = 'world',
 	resolution = 'countries',
+	displayMode = 'regions',
 	domain,
 	onError,
 	renderPlaceholder,
@@ -264,6 +266,7 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 		() => ( {
 			...( region !== 'world' && { region } ),
 			...( resolution !== 'countries' && { resolution } ),
+			...( displayMode !== 'regions' && { displayMode } ),
 			...( domain && { domain } ),
 			colorAxis: { colors: [ lightColorHex, fullColorHex ] },
 			backgroundColor: backgroundColorHex,
@@ -276,6 +279,7 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 		[
 			region,
 			resolution,
+			displayMode,
 			domain,
 			lightColorHex,
 			fullColorHex,

package/src/charts/geo-chart/index.ts

@@ -1,2 +1,8 @@
 export { default as GeoChart, GeoChartUnresponsive } from './geo-chart';
-export type { GeoChartProps, GeoRegion, GeoResolution, GeoChartError } from './types';
+export type {
+	GeoChartProps,
+	GeoRegion,
+	GeoResolution,
+	GeoDisplayMode,
+	GeoChartError,
+} from './types';

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

@@ -224,6 +224,14 @@ describe( 'GeoChart', () => {
 			expect( options.domain ).toBe( 'IN' );
 		} );
 
+		test( 'passes the markers display mode so rows draw as points, not shaded areas', () => {
+			renderWithTheme( { displayMode: 'markers' } );
+
+			const options = JSON.parse( screen.getByTestId( 'chart-options' ).textContent || '{}' );
+
+			expect( options.displayMode ).toBe( 'markers' );
+		} );
+
 		test( 'does not include resolution in options when set to countries (default)', () => {
 			renderWithTheme();
 

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

@@ -15,6 +15,13 @@ export type GeoRegion = 'world' | ( string & {} );
  */
 export type GeoResolution = 'countries' | 'provinces' | 'metros';
 
+/**
+ * How the map plots its rows.
+ * - 'regions': Shades each area the rows name
+ * - 'markers': Draws a sized, colored circle per row; a row can name a place or give `[ latitude, longitude ]` as its first two columns
+ */
+export type GeoDisplayMode = 'regions' | 'markers';
+
 export interface GeoChartError {
 	id?: string;
 	message?: string;
@@ -48,6 +55,11 @@ export interface GeoChartProps extends Pick<
 	 * @default 'countries'
 	 */
 	resolution?: GeoResolution;
+	/**
+	 * How the map plots its rows: shaded areas, or one marker per row.
+	 * @default 'regions'
+	 */
+	displayMode?: GeoDisplayMode;
 	/**
 	 * ISO 3166-1 alpha-2 code of the country whose viewpoint sets the disputed borders
 	 * (e.g., 'IN' draws Kashmir as India shows it). Google's default borders apply when omitted.

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

@@ -183,12 +183,19 @@ $focus-ring-width: var(--wpds-border-width-focus);
 	font-size: var(--wpds-typography-font-size-md);
 }
 
-// Light text on fills dark enough to out-contrast dark text (decided in JS from
-// the blended fill luminance).
-.heatmap-chart__cell--strong .heatmap-chart__cell-value {
+// Chosen per cell in JS from the blended fill; see pickLabelTextColorForFill.
+.heatmap-chart__cell-value--inverse {
 	color: var(--a8c-charts-color-label-inverse);
 }
 
+.heatmap-chart__cell-value--black {
+	color: #000;
+}
+
+.heatmap-chart__cell-value--white {
+	color: #fff;
+}
+
 .heatmap-chart__legend-label {
 	color: var(--a8c-charts-color-label);
 }

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

@@ -1,10 +1,11 @@
 import { formatNumber, formatNumberCompact } from '@automattic/number-formatters';
-import { defaultStyles as visxTooltipStyles, useTooltip } from '@visx/tooltip';
+import { useTooltip } from '@visx/tooltip';
 import { __ } from '@wordpress/i18n';
 import clsx from 'clsx';
+import isEqual from 'fast-deep-equal';
 import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
-import tooltipStyles from '../../components/tooltip/base-tooltip.module.scss';
 import { BoundedTooltip, TOOLTIP_Z_INDEX } from '../../components/tooltip/private/bounded-tooltip';
+import { useIsomorphicLayoutEffect } from '../../hooks';
 import {
 	GlobalChartsProvider,
 	useChartId,
@@ -13,19 +14,16 @@ import {
 	GlobalChartsContext,
 } from '../../providers';
 import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
+import { blendRgb, hexToRgb } from '../../providers/chart-context/private/perceptual-color';
 import { useStandaloneScopeClass } from '../../providers/chart-scope';
 import { attachSubComponents } from '../../utils';
-import {
-	isValidHexColor,
-	mixHexColors,
-	normalizeColorToHex,
-	prefersLightText,
-} from '../../utils/color-utils';
-import { resolveCssVariable } from '../../utils/resolve-css-var';
+import { isValidHexColor, normalizeColorToHex } from '../../utils/color-utils';
+import { createCssVariableResolver, 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 { pickLabelTextColorForFill, resolveLabelRoles } from '../private/label-text-color';
 import { withResponsive } from '../private/with-responsive';
 import styles from './heatmap-chart.module.scss';
 import {
@@ -46,6 +44,7 @@ import {
 import type { HeatmapContextValue } from './private';
 import type { CellBlock, CellPosition } from './private/keyboard-navigation';
 import type { HeatmapChartProps, HeatmapTooltipData } from './types';
+import type { LabelRoles, LabelTextColor } from '../private/label-text-color';
 import type { ResponsiveConfig } from '../private/with-responsive';
 import type { CSSProperties, FC } from 'react';
 
@@ -53,15 +52,19 @@ import type { CSSProperties, FC } from 'react';
 // the rendered fill is the primary mixed over the chart background at 0.15 + 0.85 * intensity.
 const CELL_MIX_FLOOR = 0.15;
 
+// `label` is the stylesheet's default, so it needs no modifier.
+const CELL_VALUE_MODIFIER: Record< LabelTextColor, string | undefined > = {
+	label: undefined,
+	'label-inverse': styles[ 'heatmap-chart__cell-value--inverse' ],
+	black: styles[ 'heatmap-chart__cell-value--black' ],
+	white: styles[ 'heatmap-chart__cell-value--white' ],
+};
+
 // One instance, not a `[]` default in the signature: `buildTooltipData` keys on
 // it, and a fresh array per render re-ran the keyboard tooltip effect endlessly.
 const NO_ROW_LABELS: string[] = [];
 
-// The dark variant is painted by the `.surface` class, so its style carries no box.
-const TOOLTIP_BOX_STYLES: Record< 'light' | 'dark', CSSProperties > = {
-	light: { ...visxTooltipStyles, zIndex: TOOLTIP_Z_INDEX },
-	dark: { zIndex: TOOLTIP_Z_INDEX },
-};
+const TOOLTIP_BOX_STYLE: CSSProperties = { zIndex: TOOLTIP_Z_INDEX };
 
 // The cell's own label wins; otherwise the group, column and row labels name it.
 const cellName = ( info: HeatmapTooltipData ) =>
@@ -88,14 +91,13 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	gap = 'md',
 	withTooltips = false,
 	renderTooltip,
-	tooltipVariant = 'light',
 	tooltipStyle,
 	children,
 } ) => {
 	const chartId = useChartId( providedChartId );
 	const tooltipBoxStyle = tooltipStyle
-		? { ...TOOLTIP_BOX_STYLES[ tooltipVariant ], ...tooltipStyle }
-		: TOOLTIP_BOX_STYLES[ tooltipVariant ];
+		? { ...TOOLTIP_BOX_STYLE, ...tooltipStyle }
+		: TOOLTIP_BOX_STYLE;
 	const { getElementStyles, theme } = useGlobalChartsContext();
 	const scopeElement = useChartScopeElement();
 	const { heatmapChart: heatmapChartSettings } = theme;
@@ -106,6 +108,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 		useTooltip< HeatmapTooltipData >();
 	const standaloneScopeClass = useStandaloneScopeClass();
 	const containerRef = useRef< HTMLDivElement >( null );
+	const [ labelRoles, setLabelRoles ] = useState< LabelRoles | null >( null );
 	// The chart root positions the tooltip, so pointer and cell coordinates are
 	// measured against it — found by its id rather than by walking up, so
 	// whatever ChartLayout wraps the grid in cannot shift the origin.
@@ -131,18 +134,34 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 	);
 
 	// Choose text color from the blended fill, not the raw value.
-	// If either color cannot resolve to hex, keep dark text.
+	// If either color cannot resolve to hex, keep the stylesheet's default role.
 	const primaryHex = normalizeColorToHex( primaryColorHex );
-	const cellHasLightText = ( intensity: number ): boolean =>
-		isValidHexColor( primaryHex ) &&
-		isValidHexColor( chartBackgroundHex ) &&
-		prefersLightText(
-			mixHexColors(
-				primaryHex,
-				chartBackgroundHex,
-				1 - ( CELL_MIX_FLOOR + ( 1 - CELL_MIX_FLOOR ) * intensity )
-			)
-		);
+	const cellMix =
+		isValidHexColor( primaryHex ) && isValidHexColor( chartBackgroundHex )
+			? { primary: hexToRgb( primaryHex ), background: hexToRgb( chartBackgroundHex ) }
+			: null;
+	const cellTextColor = ( intensity: number ): LabelTextColor =>
+		cellMix
+			? pickLabelTextColorForFill(
+					blendRgb(
+						cellMix.primary,
+						cellMix.background,
+						CELL_MIX_FLOOR + ( 1 - CELL_MIX_FLOOR ) * intensity
+					),
+					labelRoles,
+					'label'
+				)
+			: 'label';
+
+	// Read inside the chart's own class, where the cell text inherits them. Keyed on `data` too,
+	// because the grid is not mounted while there is nothing to draw.
+	useIsomorphicLayoutEffect( () => {
+		if ( ! containerRef.current ) {
+			return;
+		}
+		const next = resolveLabelRoles( createCssVariableResolver( containerRef.current ) );
+		setLabelRoles( previous => ( isEqual( previous, next ) ? previous : next ) );
+	}, [ data, className, primaryColorHex, chartBackgroundHex ] );
 
 	const extent = useMemo( () => getValueExtent( data ), [ data ] );
 	const heatmapContext = useMemo< HeatmapContextValue >(
@@ -547,8 +566,6 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 												data-row={ rowIndex }
 												className={ clsx( styles[ 'heatmap-chart__cell' ], {
 													[ styles[ 'heatmap-chart__cell--filled' ] ]: filled,
-													[ styles[ 'heatmap-chart__cell--strong' ] ]:
-														filled && cellHasLightText( normalized ),
 													[ styles[ 'heatmap-chart__cell--summary' ] ]: column.summary,
 													...summaryGaps( columnIndex ),
 													[ styles[ 'heatmap-chart__cell--selected' ] ]:
@@ -566,7 +583,12 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 												onMouseLeave={ handleCellMouseLeave }
 											>
 												{ ( drawValues || column.summary ) && present && (
-													<span className={ styles[ 'heatmap-chart__cell-value' ] }>
+													<span
+														className={ clsx(
+															styles[ 'heatmap-chart__cell-value' ],
+															filled && CELL_VALUE_MODIFIER[ cellTextColor( normalized ) ]
+														) }
+													>
 														{ /* Compact display; tooltip and aria-label keep full precision. */ }
 														{ formatNumberCompact( value ) }
 													</span>
@@ -596,12 +618,7 @@ const HeatmapChartInternal: FC< HeatmapChartProps > = ( {
 						) }
 					</div>
 					{ withTooltips && tooltipOpen && tooltipData && (
-						<BoundedTooltip
-							top={ tooltipTop }
-							left={ tooltipLeft }
-							className={ tooltipVariant === 'dark' ? tooltipStyles.surface : undefined }
-							style={ tooltipBoxStyle }
-						>
+						<BoundedTooltip top={ tooltipTop } left={ tooltipLeft } style={ tooltipBoxStyle }>
 							<div className={ standaloneScopeClass } role="tooltip" tabIndex={ -1 }>
 								{ ( renderTooltip ?? defaultRenderTooltip )( tooltipData ) }
 							</div>

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' ],
 		} );
@@ -480,6 +468,122 @@ const mockRects = () =>
 		} as DOMRect;
 	} );
 
+describe( 'HeatmapChart value text contrast', () => {
+	// Extent 0..100, so each value is its own intensity in hundredths.
+	const scale: HeatmapColumn[] = [
+		{ label: 'W1', data: [ { value: 0 }, { value: 85 }, { 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( '0' ) ).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( '85' ) ).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( '0' ) ).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( '0' ) ).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' );
+
+		[ '0', '85', '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/types.ts

@@ -107,13 +107,9 @@ export interface HeatmapChartProps extends Omit<
 	 */
 	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);