@automattic/charts 4.4.0 → 4.6.0

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 ] >();

package/src/index.ts

@@ -82,7 +82,13 @@ export type {
 	PieSemiCircleChartProps,
 	PieSemiCircleChartRenderTooltipParams,
 } from './charts/pie-semi-circle-chart';
-export type { GeoChartProps, GeoRegion, GeoResolution, GeoChartError } from './charts/geo-chart';
+export type {
+	GeoChartProps,
+	GeoRegion,
+	GeoResolution,
+	GeoDisplayMode,
+	GeoChartError,
+} from './charts/geo-chart';
 export type { LegendValueDisplay, BaseLegendItem } from './components/legend';
 export type { TrendIndicatorProps, TrendDirection } from './components/trend-indicator';
 export type { LineStyles, GridStyles, EventHandlerParams } from '@visx/xychart';

package/src/providers/chart-context/global-charts-provider.tsx

@@ -1,4 +1,4 @@
-import { hsl as d3Hsl } from '@visx/vendor/d3-color';
+import { color as d3Color } from '@visx/vendor/d3-color';
 import {
 	createContext,
 	useCallback,
@@ -17,6 +17,7 @@ import {
 	getItemShapeStyles,
 	getSeriesBarStyles,
 	getSeriesLineStyles,
+	isValidHexColor,
 	mergeThemes,
 	resolveCssVariable,
 	normalizeColorToHex,
@@ -24,13 +25,39 @@ import {
 import { sanitizeFormatting } from '../../utils/date-formatting';
 // Imported from the module rather than the `chart-scope` barrel: the barrel also pulls `use-standalone-scope-class`, which imports `GlobalChartsContext` back from this file. That cycle resolves today only because the binding is read lazily inside the hook body.
 import { ChartScopeContext } from '../chart-scope/chart-scope-context';
-import { getChartColor, type ColorCache } from './private/get-chart-color';
-import { SERIES_PALETTE_POINTERS } from './private/series-palette';
+import {
+	BACKGROUND_FALLBACK,
+	CATALOG_POINTERS,
+	LABEL_FALLBACK,
+	LABEL_INVERSE_FALLBACK,
+} from './private/catalog-pointers';
+import { createPaletteGenerator } from './private/palette-generator';
+import { SERIES_PALETTE_POINTERS, SERIES_SLOT_1_FALLBACK } from './private/series-palette';
 import { defaultTheme } from './themes';
 import type { GlobalChartsContextValue, ChartRegistration } from './types';
 import type { ChartTheme, CompleteChartTheme } from '../../types';
 import type { FC, ReactNode } from 'react';
 
+interface ColorCache {
+	colors: string[];
+	background: string;
+	labelColors: string[];
+	colorAt: ( index: number ) => string;
+}
+
+// A see-through color (transparent, or any alpha below 1) says nothing about what it will look like
+// over the chart, so it resolves to null rather than let its RGB leak into the palette.
+const resolveOpaqueHex = ( pointer: string, element: HTMLElement | null ): string | null => {
+	const raw = resolveCssVariable( pointer, element );
+	if ( ! raw || d3Color( raw )?.opacity !== 1 ) {
+		return null;
+	}
+	const hex = normalizeColorToHex( pointer, element, resolveCssVariable );
+	return isValidHexColor( hex ) ? hex : null;
+};
+
+const PLACEHOLDER_LABEL_COLORS = [ LABEL_FALLBACK, LABEL_INVERSE_FALLBACK ];
+
 export const GlobalChartsContext = createContext< GlobalChartsContextValue | null >( null );
 
 export interface GlobalChartsProviderProps {
@@ -81,12 +108,17 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 	// Cache expensive color computations that only change when theme colors change
 	// Using useState + useLayoutEffect instead of useMemo to ensure CSS variables
 	// in <style> tags are applied to the DOM before we try to resolve them
+	// Seeded with what slot 1 resolves to where no DOM answers, so a one-series first render
+	// never builds the candidate grid and SSR matches the unthemed client palette.
 	const [ colorCache, setColorCache ] = useState< ColorCache >( () => ( {
 		colors: [],
-		hues: [],
-		existingHslColors: [],
-		minHue: 360,
-		maxHue: 0,
+		background: BACKGROUND_FALLBACK,
+		labelColors: PLACEHOLDER_LABEL_COLORS,
+		colorAt: createPaletteGenerator(
+			[ SERIES_SLOT_1_FALLBACK ],
+			BACKGROUND_FALLBACK,
+			PLACEHOLDER_LABEL_COLORS
+		),
 	} ) );
 
 	// Track if the color palette has been resolved from the DOM
@@ -100,45 +132,29 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 	useLayoutEffect( () => {
 		setIsColorPaletteResolved( false );
 		const resolvedColors: string[] = [];
-		const hues: number[] = [];
-		const existingHslColors: Array< [ number, number, number ] > = [];
-		let minHue = 360;
-		let maxHue = 0;
 
 		for ( const color of SERIES_PALETTE_POINTERS ) {
-			// Normalize color to hex format, handling CSS variables, RGB, HSL, etc.
-			// This uses normalizeColorToHex which resolves CSS variables and converts
-			// rgb(), rgba(), hsl() formats to hex
 			const normalizedColor = normalizeColorToHex( color, wrapperRef.current, resolveCssVariable );
 
-			// Only process valid hex colors. An unset palette slot returns its own
-			// `var()` unchanged, so this is also what compacts the palette: slots the
-			// consumer never set drop out here and `getChartColor` generates past
-			// whatever survived.
-			if ( normalizedColor.startsWith( '#' ) ) {
+			// An unset palette slot returns its own `var()` unchanged, so this is also what
+			// compacts the palette: a slot the consumer never set drops out here.
+			if ( isValidHexColor( normalizedColor ) ) {
 				resolvedColors.push( normalizedColor );
-				const hslColor = d3Hsl( normalizedColor );
-				// d3Hsl returns NaN values for invalid colors
-				if ( ! isNaN( hslColor.h ) ) {
-					const hslTuple: [ number, number, number ] = [
-						hslColor.h,
-						hslColor.s * 100,
-						hslColor.l * 100,
-					];
-					hues.push( hslTuple[ 0 ] );
-					existingHslColors.push( hslTuple );
-					minHue = Math.min( minHue, hslTuple[ 0 ] );
-					maxHue = Math.max( maxHue, hslTuple[ 0 ] );
-				}
 			}
 		}
 
+		const backgroundHex =
+			resolveOpaqueHex( CATALOG_POINTERS.background, wrapperRef.current ) ?? BACKGROUND_FALLBACK;
+		// The two roles pie labels choose between on a fill; one left see-through is never painted there.
+		const labelColors = [ CATALOG_POINTERS.label, CATALOG_POINTERS.labelInverse ]
+			.map( pointer => resolveOpaqueHex( pointer, wrapperRef.current ) )
+			.filter( ( hex ): hex is string => hex !== null );
+
 		setColorCache( {
 			colors: resolvedColors,
-			hues,
-			existingHslColors,
-			minHue,
-			maxHue,
+			background: backgroundHex,
+			labelColors,
+			colorAt: createPaletteGenerator( resolvedColors, backgroundHex, labelColors ),
 		} );
 	}, [] );
 
@@ -152,9 +168,9 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 		() => new Map()
 	);
 
-	// Keyed on the resolved colors rather than the cache object, so a consumer passing an inline
-	// `theme` cannot reset the map on every render.
-	const paletteKey = colorCache.colors.join( ',' );
+	// Keyed on the resolved colors, background and labels, not the cache object, so a consumer passing an
+	// inline `theme` cannot reset the map on every render.
+	const paletteKey = `${ colorCache.colors.join( ',' ) }|${ colorCache.background }|${ colorCache.labelColors.join( ',' ) }`;
 
 	useEffect( () => {
 		// Create a completely new Map instance to trigger dependencies, e.g. useChartLegendItems
@@ -206,13 +222,13 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 				// Use map size as index to assign colors sequentially (0, 1, 2...)
 				// ensuring each new group gets the next available palette color
 				const assignedCount = groupToColorMap.size;
-				const color = getChartColor( assignedCount, colorCache );
+				const color = colorCache.colorAt( assignedCount );
 				groupToColorMap.set( group, color );
 
 				return color;
 			}
 
-			return getChartColor( index, colorCache );
+			return colorCache.colorAt( index );
 		},
 		[ colorCache, groupToColorMap ]
 	);

package/src/providers/chart-context/private/catalog-pointers.ts

@@ -4,9 +4,17 @@ import { SERIES_PALETTE_POINTERS } from './series-palette';
  * The `var()` chain for each color JS has to hand to something. Nothing here is resolved in JS —
  * the chain lands on the element; the terminal literal covers SSR and jsdom. See TOKENS.md.
  */
+/** Terminal literals the provider also generates from before its first read, so SSR and the first client render agree. */
+export const BACKGROUND_FALLBACK = '#ffffff';
+export const LABEL_FALLBACK = '#1e1e1e';
+export const LABEL_INVERSE_FALLBACK = '#f0f0f0';
+
 export const CATALOG_POINTERS = {
-	background: 'var(--a8c-charts-color-background, #fff)',
+	background: `var(--a8c-charts-color-background, ${ BACKGROUND_FALLBACK })`,
+	label: `var(--a8c-charts-color-label, ${ LABEL_FALLBACK })`,
 	labelAxis: 'var(--a8c-charts-color-label-axis, #1e1e1e)',
+	labelInverse: `var(--a8c-charts-color-label-inverse, ${ LABEL_INVERSE_FALLBACK })`,
+	labelBackground: 'var(--a8c-charts-color-label-background, transparent)',
 	grid: 'var(--a8c-charts-color-grid, #dbdbdb)',
 	// The y pair resolves to `none`: that axis carries labels only until a consumer declares them.
 	axisX: 'var(--a8c-charts-color-axis-x, #dbdbdb)',