@automattic/charts 4.3.0 → 4.5.0

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

@@ -1,8 +1,9 @@
 import { Group } from '@visx/group';
 import { Pie } from '@visx/shape';
 import { useTooltip } from '@visx/tooltip';
+import { color as d3Color } from '@visx/vendor/d3-color';
 import clsx from 'clsx';
-import { useCallback, useContext, useMemo, useRef } from 'react';
+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';
@@ -19,8 +20,16 @@ import {
 	useGlobalChartsTheme,
 	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, resolveFontSize } from '../../utils';
+import {
+	attachSubComponents,
+	createCssVariableResolver,
+	isValidHexColor,
+	normalizeColorToHex,
+	resolveFontSize,
+} from '../../utils';
 import { getStringWidth } from '../../visx/text';
 import { Center } from '../private/center';
 import { ChartSVG, ChartHTML, useChartChildren } from '../private/chart-composition';
@@ -161,6 +170,50 @@ 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 )
+	);
+};
+
 /**
  * Renders a pie or donut chart using the provided data.
  *
@@ -202,6 +255,11 @@ const PieChartInternal = ( {
 	// The tooltip renders inside this element, so pointer coordinates are taken relative to it.
 	const containerRef = useRef< HTMLDivElement >( null );
 
+	// 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 );
+
 	const onMouseLeave = useCallback( () => {
 		if ( ! withTooltips ) {
 			return;
@@ -209,7 +267,41 @@ const PieChartInternal = ( {
 		hideTooltip();
 	}, [ withTooltips, hideTooltip ] );
 
-	const { getElementStyles, isSeriesVisible } = useGlobalChartsContext();
+	const { getElementStyles, isSeriesVisible, isColorPaletteResolved } = useGlobalChartsContext();
+	const { isValid, message } = validateData( data );
+
+	// Skipped when labels are off, or before the chart's own root element mounts (the invalid-data
+	// branch renders a plain div, so `rootRef` is not yet attached).
+	useLayoutEffect( () => {
+		if ( ! showLabels || ! rootRef.current ) {
+			return;
+		}
+
+		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
+		);
+	}, [ showLabels, className, isColorPaletteResolved, isValid ] );
 
 	// Calculate percentages from values (single source of truth)
 	const dataWithPercentages = useDataWithPercentages( data );
@@ -230,8 +322,6 @@ const PieChartInternal = ( {
 	// Create legend items using legendData (has recalculated percentages for visible items)
 	const legendItems = useChartLegendItems( legendData, legendOptions );
 
-	const { isValid, message } = validateData( data );
-
 	// Process children to extract compound components
 	const { svgChildren, htmlChildren, legendChildren, otherChildren } = useChartChildren(
 		children,
@@ -309,6 +399,7 @@ const PieChartInternal = ( {
 				legendElement={ legendElement }
 				legendChildren={ legendChildren }
 				gap={ gap }
+				rootRef={ rootRef }
 				className={ clsx(
 					'pie-chart',
 					styles[ 'pie-chart' ],
@@ -405,11 +496,12 @@ const PieChartInternal = ( {
 														} );
 													};
 
+													const fill = accessors.fill( arc.data );
 													const pathProps: SVGProps< SVGPathElement > & {
 														'data-testid'?: string;
 													} = {
 														d: pie.path( arc ) || '',
-														fill: accessors.fill( arc.data ),
+														fill,
 														'data-testid': 'pie-segment',
 													};
 
@@ -446,7 +538,11 @@ const PieChartInternal = ( {
 																		pointerEvents="none"
 																	/>
 																	<text
-																		className={ styles[ 'pie-chart__label-text' ] }
+																		className={ clsx( styles[ 'pie-chart__label-text' ], {
+																			[ styles[ 'pie-chart__label-text--on-light' ] ]:
+																				labelNeedsDarkText( fill, labelPointers ),
+																		} ) }
+																		data-testid="pie-label"
 																		x={ centroidX }
 																		y={ centroidY }
 																		dy=".33em"

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

@@ -149,6 +149,155 @@ describe( 'PieChart', () => {
 		} );
 	} );
 
+	describe( 'Label Text Contrast', () => {
+		const contrastData = [
+			{ label: 'Light', value: 60, color: '#f5d76e' },
+			{ label: 'Dark', value: 40, color: '#1e3a8a' },
+		];
+
+		let injectedStyle: HTMLStyleElement | null = null;
+
+		afterEach( () => {
+			if ( injectedStyle ) {
+				document.head.removeChild( injectedStyle );
+				injectedStyle = null;
+			}
+		} );
+
+		test( 'uses dark label text on a light slice', () => {
+			renderWithTheme( { data: contrastData } );
+
+			const [ light, dark ] = screen.getAllByTestId( 'pie-label' );
+			expect( light ).toHaveClass( 'pie-chart__label-text--on-light' );
+			expect( dark ).not.toHaveClass( 'pie-chart__label-text--on-light' );
+		} );
+
+		test( "keeps the inverse label color when a label plate is set on the chart's own class", () => {
+			injectedStyle = document.createElement( 'style' );
+			injectedStyle.textContent =
+				'.plated-pie { --a8c-charts-color-label-background: rgba(0, 0, 0, 0.75); }';
+			document.head.appendChild( injectedStyle );
+
+			renderWithTheme( { data: contrastData, className: 'plated-pie' } );
+
+			screen
+				.getAllByTestId( 'pie-label' )
+				.forEach( label => expect( label ).not.toHaveClass( 'pie-chart__label-text--on-light' ) );
+		} );
+
+		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; }';
+			document.head.appendChild( injectedStyle );
+
+			renderWithTheme( {
+				data: [ { label: 'Dark', value: 100, color: '#1e3a8a' } ],
+				className: 'overridden-pie',
+			} );
+
+			const [ label ] = screen.getAllByTestId( 'pie-label' );
+			expect( label ).toHaveClass( 'pie-chart__label-text--on-light' );
+		} );
+
+		test( 'keeps the inverse label color when the plate uses color syntax d3 cannot parse', () => {
+			injectedStyle = document.createElement( 'style' );
+			injectedStyle.textContent =
+				'.modern-plate-pie { --a8c-charts-color-label-background: rgb(0 0 0 / 50%); }';
+			document.head.appendChild( injectedStyle );
+
+			renderWithTheme( { data: contrastData, className: 'modern-plate-pie' } );
+
+			screen
+				.getAllByTestId( 'pie-label' )
+				.forEach( label => expect( label ).not.toHaveClass( 'pie-chart__label-text--on-light' ) );
+		} );
+
+		test( 'keeps the inverse label color when the label role is see-through', () => {
+			injectedStyle = document.createElement( 'style' );
+			injectedStyle.textContent =
+				'.clear-label-pie { --a8c-charts-color-label: rgba(0, 0, 0, 0); }';
+			document.head.appendChild( injectedStyle );
+
+			renderWithTheme( { data: contrastData, className: 'clear-label-pie' } );
+
+			screen
+				.getAllByTestId( 'pie-label' )
+				.forEach( label => expect( label ).not.toHaveClass( 'pie-chart__label-text--on-light' ) );
+		} );
+
+		test( 'keeps one label color on every slice when both label roles are the same', () => {
+			injectedStyle = document.createElement( 'style' );
+			injectedStyle.textContent =
+				'.single-label-pie { --a8c-charts-color-label: #ffffff; --a8c-charts-color-label-inverse: #ffffff; }';
+			document.head.appendChild( injectedStyle );
+
+			renderWithTheme( { data: contrastData, className: 'single-label-pie' } );
+
+			screen
+				.getAllByTestId( 'pie-label' )
+				.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', () => {
+			injectedStyle = document.createElement( 'style' );
+			injectedStyle.textContent =
+				'.clear-inverse-pie { --a8c-charts-color-label-inverse: rgba(255, 255, 255, 0); }';
+			document.head.appendChild( injectedStyle );
+
+			renderWithTheme( { data: contrastData, className: 'clear-inverse-pie' } );
+
+			screen
+				.getAllByTestId( 'pie-label' )
+				.forEach( label => expect( label ).toHaveClass( 'pie-chart__label-text--on-light' ) );
+		} );
+
+		test( 'keeps the inverse label color when the fill cannot be resolved', () => {
+			renderWithTheme( {
+				data: [ { label: 'Unresolved', value: 100, color: 'var(--not-set)' } ],
+			} );
+
+			screen
+				.getAllByTestId( 'pie-label' )
+				.forEach( label => expect( label ).not.toHaveClass( 'pie-chart__label-text--on-light' ) );
+		} );
+
+		describe( 'after an invalid-to-valid data transition', () => {
+			test( "keeps the inverse label color when a plate is set on the chart's own class", () => {
+				injectedStyle = document.createElement( 'style' );
+				injectedStyle.textContent =
+					'.plated-late-pie { --a8c-charts-color-label-background: rgba(0, 0, 0, 0.75); }';
+				document.head.appendChild( injectedStyle );
+
+				const { rerender } = renderWithTheme( { data: [], className: 'plated-late-pie' } );
+
+				rerender(
+					<GlobalChartsProvider>
+						<PieChart { ...defaultProps } data={ contrastData } className="plated-late-pie" />
+					</GlobalChartsProvider>
+				);
+
+				screen
+					.getAllByTestId( 'pie-label' )
+					.forEach( label => expect( label ).not.toHaveClass( 'pie-chart__label-text--on-light' ) );
+			} );
+
+			test( 'resolves the label pointers once the chart mounts its own root element', () => {
+				const { rerender } = renderWithTheme( { data: [] } );
+
+				rerender(
+					<GlobalChartsProvider>
+						<PieChart { ...defaultProps } data={ contrastData } />
+					</GlobalChartsProvider>
+				);
+
+				const [ light, dark ] = screen.getAllByTestId( 'pie-label' );
+				expect( light ).toHaveClass( 'pie-chart__label-text--on-light' );
+				expect( dark ).not.toHaveClass( 'pie-chart__label-text--on-light' );
+			} );
+		} );
+	} );
+
 	describe( 'Legend Value Display', () => {
 		// Values that give clean percentages: 60/100=60%, 23/100=23%, 17/100=17%
 		const testData = [

package/src/charts/private/chart-layout/chart-layout.tsx

@@ -5,7 +5,7 @@ import { renderLegendSlot } from '../chart-composition';
 import styles from './chart-layout.module.scss';
 import type { GapSize, LegendPosition } from '../../../types';
 import type { LegendChild } from '../chart-composition/use-chart-children';
-import type { CSSProperties, ReactNode } from 'react';
+import type { CSSProperties, ReactNode, Ref } from 'react';
 
 /**
  * Measurements provided to the render prop when ChartLayout handles resize listening.
@@ -36,6 +36,8 @@ export interface ChartLayoutProps {
 	gap?: GapSize;
 	/** Additional class names */
 	className?: string;
+	/** Ref to the root element, the one `className` lands on */
+	rootRef?: Ref< HTMLDivElement >;
 	/** Inline styles (width, height, etc.) */
 	style?: CSSProperties;
 	/** Test ID for the container */
@@ -53,6 +55,7 @@ export const ChartLayout = ( {
 	onContentHeightChange,
 	gap,
 	className,
+	rootRef,
 	style,
 	'data-testid': dataTestId,
 	'data-chart-id': dataChartId,
@@ -78,6 +81,7 @@ export const ChartLayout = ( {
 
 	return (
 		<Stack
+			ref={ rootRef }
 			direction="column"
 			gap={ gap }
 			className={ className }

package/src/components/tooltip/accessible-tooltip.tsx

@@ -341,10 +341,41 @@ export const useKeyboardNavigation = ( {
 		[ isNavigating, selectedIndex, setSelectedIndex ]
 	);
 
+	// The point the pointer took over a keyboard selection at, where the next arrow key continues from.
+	const pointerIndex = useRef< number | undefined >( undefined );
+
+	// The pointer is the latest input, so it ends a keyboard selection instead of competing with it.
+	const onChartPointerMove = useCallback(
+		( index: number ) => {
+			if ( selectedIndex === undefined ) {
+				if ( pointerIndex.current !== undefined ) {
+					pointerIndex.current = index;
+				}
+				return;
+			}
+			const root = getChartRoot();
+			const activeElement = root?.ownerDocument.activeElement;
+			// Focus elsewhere on the page stays there; a hover must not pull it back into the chart.
+			if ( activeElement && root.contains( activeElement ) ) {
+				pointerIndex.current = index;
+				focusWithoutScrollIfNeeded( root );
+			}
+			setSelectedIndex( undefined );
+			setIsNavigating( false );
+		},
+		[ selectedIndex, setSelectedIndex, setIsNavigating, getChartRoot, focusWithoutScrollIfNeeded ]
+	);
+
 	// On each blur of chart, keyboard navigation should restart from first tooltip
-	const onChartBlur = useCallback( () => {
-		setIsNavigating( false );
-	}, [ setIsNavigating ] );
+	const onChartBlur = useCallback(
+		( event: React.FocusEvent< HTMLDivElement > ) => {
+			setIsNavigating( false );
+			if ( ! event.currentTarget.contains( event.relatedTarget ) ) {
+				pointerIndex.current = undefined;
+			}
+		},
+		[ setIsNavigating ]
+	);
 
 	const onChartKeyDown = useCallback(
 		( event: React.KeyboardEvent< HTMLDivElement > ) => {
@@ -356,12 +387,16 @@ export const useKeyboardNavigation = ( {
 				focusWithoutScrollIfNeeded( getChartRoot() );
 				setSelectedIndex( undefined );
 				setIsNavigating( false );
+				pointerIndex.current = undefined;
 				return;
 			}
 
 			if ( totalPoints === 0 ) return;
 
-			const currentSelectedIndex = selectedIndex === undefined ? -1 : selectedIndex;
+			const currentSelectedIndex = selectedIndex ?? pointerIndex.current ?? -1;
+			if ( event.key === 'ArrowRight' || event.key === 'ArrowLeft' ) {
+				pointerIndex.current = undefined;
+			}
 
 			// WAI-ARIA grid: arrows stop at the first and last cell.
 			if ( event.key === 'ArrowRight' ) {
@@ -393,5 +428,6 @@ export const useKeyboardNavigation = ( {
 		onChartFocus,
 		onChartBlur,
 		onChartKeyDown,
+		onChartPointerMove,
 	};
 };

package/src/components/tooltip/test/accessible-tooltip.test.tsx

@@ -1,6 +1,6 @@
-import { render, screen } from '@testing-library/react';
+import { act, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { useRef, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
 import { LineChartUnresponsive } from '../../../charts/line-chart/line-chart';
 import { GlobalChartsProvider } from '../../../providers';
 import { ChartScopeContext } from '../../../providers/chart-scope';
@@ -128,11 +128,17 @@ describe( 'AccessibleTooltip', () => {
 } );
 
 // Mirrors the charts' markup: the focusable grid wraps the element `chartRef` points at.
-const NavigationHarness = ( { totalPoints }: { totalPoints: number } ) => {
+const NavigationHarness = ( {
+	totalPoints,
+	trackBlur = false,
+}: {
+	totalPoints: number;
+	trackBlur?: boolean;
+} ) => {
 	const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >();
 	const [ isNavigating, setIsNavigating ] = useState( false );
 	const chartRef = useRef< HTMLDivElement >( null );
-	const { onChartKeyDown } = useKeyboardNavigation( {
+	const { onChartKeyDown, onChartBlur, onChartPointerMove } = useKeyboardNavigation( {
 		selectedIndex,
 		setSelectedIndex,
 		isNavigating,
@@ -140,14 +146,24 @@ const NavigationHarness = ( { totalPoints }: { totalPoints: number } ) => {
 		chartRef,
 		totalPoints,
 	} );
+	const moveToFour = useCallback( () => onChartPointerMove( 4 ), [ onChartPointerMove ] );
+	const moveToOne = useCallback( () => onChartPointerMove( 1 ), [ onChartPointerMove ] );
 
 	return (
 		<>
-			<div role="grid" aria-label="Harness" tabIndex={ 0 } onKeyDown={ onChartKeyDown }>
+			<div
+				role="grid"
+				aria-label="Harness"
+				tabIndex={ 0 }
+				onKeyDown={ onChartKeyDown }
+				onBlur={ trackBlur ? onChartBlur : undefined }
+			>
 				<div ref={ chartRef } data-testid="selected-index">
 					{ selectedIndex ?? 'none' }
 					<button type="button">Inside</button>
 				</div>
+				<div data-testid="point-4" onPointerMove={ moveToFour } />
+				<div data-testid="point-1" onPointerMove={ moveToOne } />
 			</div>
 			<button type="button">Outside</button>
 		</>
@@ -207,6 +223,67 @@ describe( 'useKeyboardNavigation', () => {
 		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
 	} );
 
+	it( 'hands a keyboard selection to the pointer and continues from where the pointer is', async () => {
+		const { user } = await navigate( 2 );
+
+		screen.getByRole( 'button', { name: 'Inside' } ).focus();
+		await user.hover( screen.getByTestId( 'point-4' ) );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
+		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '5' );
+	} );
+
+	it( 'continues from the last point the pointer reached after taking over', async () => {
+		const { user } = await navigate( 2 );
+
+		await user.hover( screen.getByTestId( 'point-4' ) );
+		await user.hover( screen.getByTestId( 'point-1' ) );
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '2' );
+	} );
+
+	it( 'restarts from the first point once focus leaves after the pointer took over', async () => {
+		const user = userEvent.setup();
+		render( <NavigationHarness totalPoints={ 6 } trackBlur /> );
+		const grid = screen.getByRole( 'grid', { name: 'Harness' } );
+
+		act( () => grid.focus() );
+		await user.keyboard( '{ArrowRight}{ArrowRight}' );
+		await user.hover( screen.getByTestId( 'point-4' ) );
+		act( () => screen.getByRole( 'button', { name: 'Outside' } ).focus() );
+		act( () => grid.focus() );
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '0' );
+	} );
+
+	it( 'leaves focus outside the chart when the pointer ends a selection', async () => {
+		const { user } = await navigate( 2 );
+		const outside = screen.getByRole( 'button', { name: 'Outside' } );
+
+		outside.focus();
+		await user.hover( screen.getByTestId( 'point-4' ) );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
+		expect( outside ).toHaveFocus();
+	} );
+
+	it( 'ignores the pointer when there is no keyboard selection', async () => {
+		const user = userEvent.setup();
+		render( <NavigationHarness totalPoints={ 6 } /> );
+
+		screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+		await user.hover( screen.getByTestId( 'point-4' ) );
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '0' );
+	} );
+
 	// The page sees the event after the handler, so this is what a surrounding scroll or Modal gets.
 	const recordPageKeyDown = () => {
 		const onKeyDown = jest.fn< void, [ KeyboardEvent ] >();