@automattic/charts 4.6.0 → 4.8.0

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

@@ -15,7 +15,7 @@ import {
 	useCallback,
 } from 'react';
 import { Legend, useChartLegendItems } from '../../components/legend';
-import { AccessibleTooltip, useKeyboardNavigation } from '../../components/tooltip';
+import { XYChartTooltip, useKeyboardNavigation } from '../../components/tooltip';
 import {
 	useXYChartTheme,
 	useChartDataTransform,
@@ -66,7 +66,7 @@ import type { RenderTooltipParams } from '../../visx/types';
 import type { ResponsiveConfig } from '../private/with-responsive';
 import type { TickFormatter } from '@visx/axis';
 import type { GlyphProps } from '@visx/xychart';
-import type { CSSProperties, FC, Ref } from 'react';
+import type { FC, Ref } from 'react';
 
 const defaultRenderGlyph = < Datum extends object >( props: RenderLineGlyphProps< Datum > ) => {
 	return <DefaultGlyph { ...props } key={ props.key } />;
@@ -116,13 +116,11 @@ const TooltipDate: FC< { date?: Date; displayResolution: Exclude< TickResolution
  * one row per visible series (label + formatted value), sorted descending by
  * value. Reused by AreaChart, which has the same multi-series shape.
  *
- * @param params       - visx tooltip data and the chart's optional `bucketInfo`.
- * @param contentStyle - Explicit tooltip content color overrides.
+ * @param params - visx tooltip data and the chart's optional `bucketInfo`.
  * @return Tooltip JSX, or `null` when no datum is hovered.
  */
 export const renderDefaultTooltip = (
-	params: RenderTooltipParams< DataPointDate > & { bucketInfo?: BucketInfo },
-	contentStyle?: Pick< CSSProperties, 'color' | 'background' | 'backgroundColor' >
+	params: RenderTooltipParams< DataPointDate > & { bucketInfo?: BucketInfo }
 ) => {
 	const { tooltipData, bucketInfo } = params;
 	const nearestDatum = tooltipData?.nearestDatum?.datum;
@@ -141,11 +139,7 @@ export const renderDefaultTooltip = (
 		} );
 
 	return (
-		<div
-			className={ styles[ 'line-chart__tooltip' ] }
-			data-testid="line-chart-tooltip-content"
-			style={ contentStyle }
-		>
+		<div data-testid="line-chart-tooltip-content">
 			<div className={ styles[ 'line-chart__tooltip-date' ] }>
 				<TooltipDate
 					date={ nearestDatum.date }
@@ -153,13 +147,7 @@ export const renderDefaultTooltip = (
 				/>
 			</div>
 			{ tooltipPoints.map( point => (
-				<Stack
-					key={ point.key }
-					direction="row"
-					align="center"
-					justify="space-between"
-					className={ styles[ 'line-chart__tooltip-row' ] }
-				>
+				<Stack key={ point.key } direction="row" align="center" justify="space-between">
 					<span className={ styles[ 'line-chart__tooltip-label' ] }>{ point.key }:</span>
 					<span className={ styles[ 'line-chart__tooltip-value' ] }>
 						{ formatReading( point.value ) }
@@ -577,32 +565,12 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 			yAccessor: ( d: DataPointDate ) => d?.value,
 		};
 
-		const resolvedTooltipStyle = useMemo( () => {
-			if ( renderTooltip !== renderDefaultTooltip || ! tooltipStyle ) return tooltipStyle;
-			if ( ! tooltipStyle.color || tooltipStyle.background || tooltipStyle.backgroundColor ) {
-				return tooltipStyle;
-			}
-			return {
-				backgroundColor: 'var(--a8c-charts-color-tooltip-surface, rgb(0 0 0 / 85%))',
-				...tooltipStyle,
-			};
-		}, [ renderTooltip, tooltipStyle ] );
-
 		// Augments every renderTooltip call with the chart's bucket classification,
 		// default or custom, so a heading keyed on it can't disagree with the axis.
 		const tooltipRenderer = useMemo(
 			() => ( params: RenderTooltipParams< DataPointDate > ) =>
-				renderTooltip === renderDefaultTooltip
-					? renderDefaultTooltip(
-							{ ...params, bucketInfo },
-							{
-								color: tooltipStyle?.color,
-								background: tooltipStyle?.background,
-								backgroundColor: tooltipStyle?.backgroundColor,
-							}
-						)
-					: renderTooltip( { ...params, bucketInfo } ),
-			[ renderTooltip, bucketInfo, tooltipStyle ]
+				renderTooltip( { ...params, bucketInfo } ),
+			[ renderTooltip, bucketInfo ]
 		);
 
 		if ( error ) {
@@ -816,11 +784,11 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 											</ZoomClip>
 
 											{ withTooltips && (
-												<AccessibleTooltip
+												<XYChartTooltip
 													detectBounds
 													snapTooltipToDatumX
 													tooltipPlacement={ tooltipPlacement }
-													style={ resolvedTooltipStyle }
+													style={ tooltipStyle }
 													snapTooltipToDatumY
 													showSeriesGlyphs
 													renderTooltip={ tooltipRenderer }

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

@@ -140,54 +140,26 @@ describe( 'LineChart', () => {
 			} );
 		}
 	);
-	test.each( [
-		[
-			{ color: 'white' },
-			'rgb(255, 255, 255)',
-			'var(--a8c-charts-color-tooltip-surface, rgb(0 0 0 / 85%))',
-			{ color: 'rgb(255, 255, 255)' },
-		],
-		[ { backgroundColor: 'white' }, 'var(--a8c-charts-color-label)', 'rgb(255, 255, 255)', {} ],
-		[ { background: 'white' }, 'var(--a8c-charts-color-label)', 'white', {} ],
-		[
-			{ color: 'white', background: 'black' },
-			'rgb(255, 255, 255)',
-			'black',
-			{ color: 'rgb(255, 255, 255)' },
-		],
-	] )(
-		'applies directional tooltip color defaults: %j',
-		async ( tooltipStyle, color, background, containerColorStyle ) => {
-			const user = userEvent.setup();
-			const defaults = document.createElement( 'style' );
-			defaults.textContent = `.line-chart__tooltip {
-				color: var(--a8c-charts-color-label);
-				background: var(--a8c-charts-color-surface);
-			}`;
-			renderWithTheme( { tooltipStyle } );
-			const chart = screen.getByTestId( 'line-chart' );
-			chart.appendChild( defaults );
-			chart.style.setProperty( '--a8c-charts-color-label', '#000' );
-			chart.style.setProperty( '--a8c-charts-color-label-axis', '#aaa' );
-			chart.style.setProperty( '--a8c-charts-color-surface', '#fff' );
-			screen.getByRole( 'grid', { name: /line chart/i } ).focus();
-			await user.keyboard( '{ArrowRight}' );
+	test( 'passes a color-only tooltipStyle through with no background added', async () => {
+		const user = userEvent.setup();
+		renderWithTheme( { tooltipStyle: { color: 'white' } } );
+		screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+		await user.keyboard( '{ArrowRight}' );
 
-			const content = screen.getByTestId( 'line-chart-tooltip-content' );
-			expect( content ).toHaveStyle( {
-				color,
-				[ 'backgroundColor' in tooltipStyle ? 'background-color' : 'background' ]:
-					'background' in tooltipStyle || 'backgroundColor' in tooltipStyle
-						? background
-						: 'var(--a8c-charts-color-surface)',
-			} );
-			const container = screen.getByTestId( 'bounded-tooltip' );
-			expect( container ).toHaveStyle( {
-				...containerColorStyle,
-				[ 'background' in tooltipStyle ? 'background' : 'background-color' ]: background,
-			} );
-		}
-	);
+		const box = screen.getByTestId( 'bounded-tooltip' );
+		expect( box ).toHaveStyle( { color: 'rgb(255, 255, 255)' } );
+		expect( box ).not.toHaveAttribute( 'style', expect.stringContaining( 'background' ) );
+	} );
+
+	test( 'paints a tooltipStyle background on the box, not on the default content', async () => {
+		const user = userEvent.setup();
+		renderWithTheme( { tooltipStyle: { background: 'black' } } );
+		screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'bounded-tooltip' ) ).toHaveStyle( { background: 'black' } );
+		expect( screen.getByTestId( 'line-chart-tooltip-content' ) ).not.toHaveAttribute( 'style' );
+	} );
 
 	test( 'preserves the existing tooltip colors for noncolor overrides', async () => {
 		const user = userEvent.setup();

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

@@ -22,5 +22,14 @@
 		&--on-light {
 			fill: var(--a8c-charts-color-label, #1e1e1e);
 		}
+
+		// Neither role reaches AA on this slice; see pickLabelTextColor.
+		&--black {
+			fill: #000;
+		}
+
+		&--white {
+			fill: #fff;
+		}
 	}
 }

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

@@ -3,10 +3,11 @@ import { Pie } from '@visx/shape';
 import { useTooltip } from '@visx/tooltip';
 import { color as d3Color } from '@visx/vendor/d3-color';
 import clsx from 'clsx';
+import isEqual from 'fast-deep-equal';
 import { useCallback, useContext, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { Legend, useChartLegendItems } from '../../components/legend';
-import { BaseTooltip } from '../../components/tooltip';
 import { BoundedTooltip } from '../../components/tooltip/private/bounded-tooltip';
+import { LabelValueContent } from '../../components/tooltip/private/label-value-content';
 import {
 	useDataWithPercentages,
 	useLegendVisibilityData,
@@ -21,20 +22,14 @@ import {
 	GlobalChartsContext,
 } from '../../providers';
 import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
-import { contrastRatio } from '../../providers/chart-context/private/perceptual-color';
 import { useStandaloneScopeClass } from '../../providers/chart-scope';
-import {
-	attachSubComponents,
-	createCssVariableResolver,
-	isValidHexColor,
-	normalizeColorToHex,
-	resolveFontSize,
-} from '../../utils';
+import { attachSubComponents, createCssVariableResolver, resolveFontSize } from '../../utils';
 import { getStringWidth } from '../../visx/text';
 import { Center } from '../private/center';
 import { ChartSVG, ChartHTML, useChartChildren } from '../private/chart-composition';
 import { ChartInstanceContext } from '../private/chart-instance-context';
 import { ChartLayout } from '../private/chart-layout';
+import { pickLabelTextColor, resolveLabelRoles } from '../private/label-text-color';
 import { RadialWipeAnimation } from '../private/radial-wipe-animation/';
 import { getAllHiddenMessage, SvgEmptyState } from '../private/svg-empty-state';
 import { withResponsive, ResponsiveConfig } from '../private/with-responsive';
@@ -47,7 +42,8 @@ import type {
 	Optional,
 } from '../../types';
 import type { ChartComponentWithComposition } from '../private/chart-composition';
-import type { SVGProps, MouseEvent, ReactNode, FC } from 'react';
+import type { LabelRoles, LabelTextColor } from '../private/label-text-color';
+import type { JSX, SVGProps, MouseEvent, ReactNode, FC } from 'react';
 
 /**
  * Parameters passed to the renderTooltip function for pie charts.
@@ -61,13 +57,13 @@ export type PieChartRenderTooltipParams = {
 
 /**
  * Default tooltip renderer for pie charts.
- * Renders a BaseTooltip with the hovered segment's data.
+ * Renders the default `label: value` tooltip content for the hovered segment.
  *
  * @param {PieChartRenderTooltipParams} params - The tooltip parameters containing the hovered data point
  * @return {ReactNode} The rendered tooltip content
  */
 const renderDefaultPieTooltip = ( { tooltipData }: PieChartRenderTooltipParams ): ReactNode => {
-	return <BaseTooltip data={ tooltipData } top={ 0 } left={ 0 } renderContainer={ false } />;
+	return <LabelValueContent data={ tooltipData } />;
 };
 
 export interface PieChartProps extends BaseChartProps< DataPointPercentage[] > {
@@ -131,7 +127,7 @@ export interface PieChartProps extends BaseChartProps< DataPointPercentage[] > {
 
 	/**
 	 * Custom render function for tooltip content.
-	 * When provided, replaces the default BaseTooltip with custom content.
+	 * When provided, replaces the default `label: value` tooltip with custom content.
 	 */
 	renderTooltip?: ( params: PieChartRenderTooltipParams ) => ReactNode;
 }
@@ -170,48 +166,12 @@ const validateData = ( data: DataPointPercentage[] ) => {
 	return { isValid: true, message: '' };
 };
 
-/**
- * The label pointers, resolved at the pie chart's own root element so JS and CSS agree on what paints.
- */
-interface ResolvedLabelPointers {
-	/** True while a label plate is set; the label text then always uses the inverse role. */
-	hasPlate: boolean;
-	labelHex: string;
-	labelInverseHex: string;
-	/** True when the inverse role is see-through, so only the `label` role can be seen on a fill. */
-	isInverseSeeThrough: boolean;
-}
-
-/**
- * Whether a pie slice's label should use the dark `label` role instead of the default `label-inverse` role.
- *
- * A label plate always wins: the text sits on the plate, not the slice fill, so it never flips.
- * Otherwise the role that contrasts more with the resolved slice fill wins. `null` pointers (not
- * yet resolved, or labels off) keep the default inverse role.
- *
- * @param fill     - The slice's resolved fill color.
- * @param pointers - The label pointers, resolved at the chart's own root element.
- * @return Whether the label needs dark text.
- */
-const labelNeedsDarkText = ( fill: string, pointers: ResolvedLabelPointers | null ): boolean => {
-	if ( ! pointers || pointers.hasPlate ) {
-		return false;
-	}
-
-	const fillHex = normalizeColorToHex( fill );
-	if ( ! isValidHexColor( fillHex ) || ! isValidHexColor( pointers.labelHex ) ) {
-		return false;
-	}
-	if ( pointers.isInverseSeeThrough ) {
-		return true;
-	}
-	if ( ! isValidHexColor( pointers.labelInverseHex ) ) {
-		return false;
-	}
-
-	return (
-		contrastRatio( fillHex, pointers.labelHex ) > contrastRatio( fillHex, pointers.labelInverseHex )
-	);
+// `label-inverse` is the stylesheet's default, so it needs no modifier.
+const LABEL_TEXT_MODIFIER: Record< LabelTextColor, string | undefined > = {
+	label: styles[ 'pie-chart__label-text--on-light' ],
+	'label-inverse': undefined,
+	black: styles[ 'pie-chart__label-text--black' ],
+	white: styles[ 'pie-chart__label-text--white' ],
 };
 
 /**
@@ -258,7 +218,8 @@ const PieChartInternal = ( {
 	// The element the chart's own `className` lands on, so an override set there reaches this
 	// decision the same way it reaches CSS.
 	const rootRef = useRef< HTMLDivElement >( null );
-	const [ labelPointers, setLabelPointers ] = useState< ResolvedLabelPointers | null >( null );
+	// Null until read, and while a label plate is set: text on the plate keeps the inverse role.
+	const [ labelRoles, setLabelRoles ] = useState< LabelRoles | null >( null );
 
 	const onMouseLeave = useCallback( () => {
 		if ( ! withTooltips ) {
@@ -279,28 +240,11 @@ const PieChartInternal = ( {
 
 		const resolve = createCssVariableResolver( rootRef.current );
 		const rawLabelBackground = resolve( CATALOG_POINTERS.labelBackground );
-		// Hex drops alpha, so a see-through label role would win the comparison and paint nothing.
-		const rawLabel = resolve( CATALOG_POINTERS.label );
-		const isLabelOpaque = rawLabel ? d3Color( rawLabel )?.opacity === 1 : false;
-		const rawLabelInverse = resolve( CATALOG_POINTERS.labelInverse );
-		const labelInverseColor = rawLabelInverse ? d3Color( rawLabelInverse ) : null;
 		// A plate value d3 cannot parse (CSS Color 4 syntax, say) is still one CSS paints, so it counts.
 		const plateColor = rawLabelBackground ? d3Color( rawLabelBackground ) : null;
-		const next: ResolvedLabelPointers = {
-			hasPlate: rawLabelBackground ? ! plateColor || plateColor.opacity > 0 : false,
-			labelHex: isLabelOpaque ? normalizeColorToHex( CATALOG_POINTERS.label, null, resolve ) : '',
-			labelInverseHex: normalizeColorToHex( CATALOG_POINTERS.labelInverse, null, resolve ),
-			isInverseSeeThrough: labelInverseColor ? labelInverseColor.opacity < 1 : false,
-		};
-		setLabelPointers( previous =>
-			previous &&
-			previous.hasPlate === next.hasPlate &&
-			previous.labelHex === next.labelHex &&
-			previous.labelInverseHex === next.labelInverseHex &&
-			previous.isInverseSeeThrough === next.isInverseSeeThrough
-				? previous
-				: next
-		);
+		const hasPlate = rawLabelBackground ? ! plateColor || plateColor.opacity > 0 : false;
+		const next = hasPlate ? null : resolveLabelRoles( resolve );
+		setLabelRoles( previous => ( isEqual( previous, next ) ? previous : next ) );
 	}, [ showLabels, className, isColorPaletteResolved, isValid ] );
 
 	// Calculate percentages from values (single source of truth)
@@ -538,10 +482,12 @@ const PieChartInternal = ( {
 																		pointerEvents="none"
 																	/>
 																	<text
-																		className={ clsx( styles[ 'pie-chart__label-text' ], {
-																			[ styles[ 'pie-chart__label-text--on-light' ] ]:
-																				labelNeedsDarkText( fill, labelPointers ),
-																		} ) }
+																		className={ clsx(
+																			styles[ 'pie-chart__label-text' ],
+																			LABEL_TEXT_MODIFIER[
+																				pickLabelTextColor( fill, labelRoles, 'label-inverse' )
+																			]
+																		) }
 																		data-testid="pie-label"
 																		x={ centroidX }
 																		y={ centroidY }

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

@@ -187,17 +187,17 @@ describe( 'PieChart', () => {
 
 		test( "compares against a label-inverse override set on the chart's own class", () => {
 			injectedStyle = document.createElement( 'style' );
-			// Matches the slice fill exactly, so the inverse role loses to the default dark label role.
-			injectedStyle.textContent = '.overridden-pie { --a8c-charts-color-label-inverse: #1e3a8a; }';
+			// Black out-contrasts the dark label role on a light slice, where the default inverse would lose.
+			injectedStyle.textContent = '.overridden-pie { --a8c-charts-color-label-inverse: #000000; }';
 			document.head.appendChild( injectedStyle );
 
 			renderWithTheme( {
-				data: [ { label: 'Dark', value: 100, color: '#1e3a8a' } ],
+				data: [ { label: 'Light', value: 100, color: '#f5d76e' } ],
 				className: 'overridden-pie',
 			} );
 
 			const [ label ] = screen.getAllByTestId( 'pie-label' );
-			expect( label ).toHaveClass( 'pie-chart__label-text--on-light' );
+			expect( label ).not.toHaveClass( 'pie-chart__label-text--on-light' );
 		} );
 
 		test( 'keeps the inverse label color when the plate uses color syntax d3 cannot parse', () => {
@@ -239,7 +239,7 @@ describe( 'PieChart', () => {
 				.forEach( label => expect( label ).not.toHaveClass( 'pie-chart__label-text--on-light' ) );
 		} );
 
-		test( 'uses the label role on every slice when the inverse role is see-through', () => {
+		test( 'never picks a see-through inverse role, falling back to white where the label role fails', () => {
 			injectedStyle = document.createElement( 'style' );
 			injectedStyle.textContent =
 				'.clear-inverse-pie { --a8c-charts-color-label-inverse: rgba(255, 255, 255, 0); }';
@@ -247,9 +247,22 @@ describe( 'PieChart', () => {
 
 			renderWithTheme( { data: contrastData, className: 'clear-inverse-pie' } );
 
-			screen
-				.getAllByTestId( 'pie-label' )
-				.forEach( label => expect( label ).toHaveClass( 'pie-chart__label-text--on-light' ) );
+			const [ light, dark ] = screen.getAllByTestId( 'pie-label' );
+			expect( light ).toHaveClass( 'pie-chart__label-text--on-light' );
+			expect( dark ).toHaveClass( 'pie-chart__label-text--white' );
+		} );
+
+		test( 'falls back to black or white on a slice where neither label role reaches AA', () => {
+			renderWithTheme( {
+				data: [
+					{ label: 'Mid-light', value: 50, color: '#516dec' },
+					{ label: 'Mid-dark', value: 50, color: '#4663ea' },
+				],
+			} );
+
+			const [ midLight, midDark ] = screen.getAllByTestId( 'pie-label' );
+			expect( midLight ).toHaveClass( 'pie-chart__label-text--black' );
+			expect( midDark ).toHaveClass( 'pie-chart__label-text--white' );
 		} );
 
 		test( 'keeps the inverse label color when the fill cannot be resolved', () => {

package/src/charts/pie-semi-circle-chart/pie-semi-circle-chart.tsx

@@ -5,8 +5,8 @@ import { useTooltip } from '@visx/tooltip';
 import clsx from 'clsx';
 import { useCallback, useContext, useMemo, useRef } from 'react';
 import { Legend, useChartLegendItems } from '../../components/legend';
-import { BaseTooltip } from '../../components/tooltip';
 import { BoundedTooltip } from '../../components/tooltip/private/bounded-tooltip';
+import { LabelValueContent } from '../../components/tooltip/private/label-value-content';
 import {
 	useDataWithPercentages,
 	useLegendVisibilityData,
@@ -53,7 +53,7 @@ export type PieSemiCircleChartRenderTooltipParams = {
 
 /**
  * Default tooltip renderer for semi-circle pie charts.
- * Renders a BaseTooltip with the hovered segment's data.
+ * Renders the default `label: value` tooltip content for the hovered segment.
  *
  * @param {PieSemiCircleChartRenderTooltipParams} params - The tooltip parameters containing the hovered data point
  * @return {ReactNode} The rendered tooltip content
@@ -61,7 +61,7 @@ export type PieSemiCircleChartRenderTooltipParams = {
 const renderDefaultPieSemiCircleTooltip = ( {
 	tooltipData,
 }: PieSemiCircleChartRenderTooltipParams ): ReactNode => {
-	return <BaseTooltip data={ tooltipData } top={ 0 } left={ 0 } renderContainer={ false } />;
+	return <LabelValueContent data={ tooltipData } />;
 };
 
 const PAD_ANGLE = 0.03; // Padding between segments
@@ -122,7 +122,7 @@ export interface PieSemiCircleChartProps extends BaseChartProps< DataPointPercen
 
 	/**
 	 * Custom render function for tooltip content.
-	 * When provided, replaces the default BaseTooltip with custom content.
+	 * When provided, replaces the default `label: value` tooltip with custom content.
 	 */
 	renderTooltip?: ( params: PieSemiCircleChartRenderTooltipParams ) => ReactNode;
 }

package/src/charts/pie-semi-circle-chart/test/pie-semi-circle-chart.test.tsx

@@ -96,7 +96,7 @@ describe( 'PieSemiCircleChart', () => {
 
 		await user.hover( firstSegment );
 
-		// Wait for tooltip to be visible - it should show in the BaseTooltip component
+		// Wait for tooltip to be visible - it should show the default label: value content
 		const tooltip = await screen.findByRole( 'tooltip' );
 		expect( tooltip ).toHaveTextContent( 'MacOS' );
 

package/src/charts/private/chart-composition/chart-html.tsx

@@ -1,4 +1,4 @@
-import type { FC, PropsWithChildren } from 'react';
+import type { JSX, FC, PropsWithChildren } from 'react';
 
 /**
  * Compound component for HTML children in charts.

package/src/charts/private/chart-composition/chart-svg.tsx

@@ -1,4 +1,4 @@
-import type { FC, PropsWithChildren } from 'react';
+import type { JSX, FC, PropsWithChildren } from 'react';
 
 /**
  * Compound component for SVG children in charts.

package/src/charts/private/label-text-color.ts

@@ -0,0 +1,116 @@
+import { color as d3Color } from '@visx/vendor/d3-color';
+import isEqual from 'fast-deep-equal';
+import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
+import { MIN_LABEL_CONTRAST } from '../../providers/chart-context/private/palette-generator';
+import {
+	blendRgb,
+	hexToRgb,
+	luminanceContrastRatio,
+	rgbLuminance,
+} from '../../providers/chart-context/private/perceptual-color';
+import { isValidHexColor, normalizeColorToHex } from '../../utils/color-utils';
+import type { Rgb } from '../../providers/chart-context/private/perceptual-color';
+
+// The browser paints the fill on 8-bit channels, which can cost a mid-tone ~0.03 of contrast.
+const ROUNDING_HEADROOM = 0.05;
+
+/** Which color a label drawn on a fill paints with: one of the two catalog roles, or the black/white floor. */
+export type LabelTextColor = 'label' | 'label-inverse' | 'black' | 'white';
+
+/** A label role as the chart's own element resolves it. `unreadable` keeps the raw value, which CSS may still paint. */
+export type ResolvedRole =
+	{ kind: 'color'; rgb: Rgb; alpha: number } | { kind: 'unreadable'; raw: string | null };
+
+export interface LabelRoles {
+	label: ResolvedRole;
+	labelInverse: ResolvedRole;
+}
+
+const resolveRole = (
+	pointer: string,
+	resolve: ( value: string ) => string | null
+): ResolvedRole => {
+	const raw = resolve( pointer );
+	// d3 reads no CSS Color 4 syntax (`rgb(0 0 0)`, `oklch()`), though the browser paints it.
+	const parsed = raw ? d3Color( raw ) : null;
+	if ( ! parsed ) {
+		return { kind: 'unreadable', raw };
+	}
+	// d3 gives `transparent` NaN channels; with no alpha they never reach the composite anyway.
+	const { r, g, b } = parsed.opacity > 0 ? parsed.rgb() : { r: 0, g: 0, b: 0 };
+	return { kind: 'color', rgb: [ r, g, b ], alpha: parsed.opacity };
+};
+
+/**
+ * Reads both label roles at the element the label text inherits from, so JS and CSS agree on what paints.
+ *
+ * @param resolve - A CSS variable resolver bound to that element.
+ * @return The resolved label roles.
+ */
+export const resolveLabelRoles = ( resolve: ( value: string ) => string | null ): LabelRoles => ( {
+	label: resolveRole( CATALOG_POINTERS.label, resolve ),
+	labelInverse: resolveRole( CATALOG_POINTERS.labelInverse, resolve ),
+} );
+
+// Text with alpha shows the fill through it, so it is measured as the blend the browser paints.
+const roleContrast = ( role: ResolvedRole, fill: Rgb, fillLuminance: number ): number => {
+	if ( role.kind === 'unreadable' ) {
+		return 0;
+	}
+	return luminanceContrastRatio(
+		fillLuminance,
+		rgbLuminance( blendRgb( role.rgb, fill, role.alpha ) )
+	);
+};
+
+/**
+ * Picks the label color for text drawn on a fill: the role that contrasts more, or black/white when neither reaches AA.
+ *
+ * Both roles set to one color is a host's choice to keep that color, so it never falls back.
+ *
+ * @param fill        - The fill the text sits on, as unrounded sRGB channels.
+ * @param roles       - The label roles resolved at the chart's element, or null before they are read.
+ * @param defaultRole - The role the chart's stylesheet paints when nothing can be decided.
+ * @return The color the label should paint with.
+ */
+export const pickLabelTextColorForFill = (
+	fill: Rgb,
+	roles: LabelRoles | null,
+	defaultRole: 'label' | 'label-inverse'
+): LabelTextColor => {
+	if ( ! roles || isEqual( roles.label, roles.labelInverse ) ) {
+		return defaultRole;
+	}
+
+	const fillLuminance = rgbLuminance( fill );
+	const labelContrast = roleContrast( roles.label, fill, fillLuminance );
+	const inverseContrast = roleContrast( roles.labelInverse, fill, fillLuminance );
+	if ( Math.max( labelContrast, inverseContrast ) >= MIN_LABEL_CONTRAST + ROUNDING_HEADROOM ) {
+		return labelContrast > inverseContrast ? 'label' : 'label-inverse';
+	}
+
+	// On any opaque fill one of these reaches at least 4.58:1.
+	return luminanceContrastRatio( fillLuminance, 0 ) > luminanceContrastRatio( fillLuminance, 1 )
+		? 'black'
+		: 'white';
+};
+
+/**
+ * `pickLabelTextColorForFill` for a fill given as a color.
+ *
+ * @param fill        - The fill, in any color syntax `normalizeColorToHex` reads.
+ * @param roles       - The label roles resolved at the chart's element, or null before they are read.
+ * @param defaultRole - The role the chart's stylesheet paints when nothing can be decided.
+ * @return The color the label should paint with.
+ */
+export const pickLabelTextColor = (
+	fill: string,
+	roles: LabelRoles | null,
+	defaultRole: 'label' | 'label-inverse'
+): LabelTextColor => {
+	const fillHex = normalizeColorToHex( fill );
+	if ( ! isValidHexColor( fillHex ) ) {
+		return defaultRole;
+	}
+	return pickLabelTextColorForFill( hexToRgb( fillHex ), roles, defaultRole );
+};

package/src/charts/private/radial-wipe-animation/radial-wipe-animation.tsx

@@ -9,6 +9,8 @@
  * - A white mask makes the area visible, while a black mask makes the area invisible.
  */
 
+import type { JSX } from 'react';
+
 type Angle = `${ number }deg` | `${ number }rad` | `${ number }grad` | `${ number }turn` | 0 | '0';
 
 /**

package/src/charts/private/svg-empty-state/svg-empty-state.tsx

@@ -1,6 +1,6 @@
 import { Center } from '../center';
 import styles from './svg-empty-state.module.scss';
-import type { FC, ReactNode } from 'react';
+import type { JSX, FC, ReactNode } from 'react';
 
 interface SvgEmptyStateProps {
 	/** X coordinate of the center point */