@automattic/charts 4.8.0 → 4.9.0

package/src/charts/private/pie-keyboard-navigation/test/order-arcs-for-navigation.test.ts

@@ -0,0 +1,34 @@
+import { orderArcsForNavigation } from '../order-arcs-for-navigation';
+
+const half = Math.PI / 2;
+
+describe( 'orderArcsForNavigation', () => {
+	it.each( [
+		[
+			'full pie, clockwise from 12 o’clock',
+			[
+				{ id: 'b', startAngle: Math.PI, endAngle: 2 * Math.PI },
+				{ id: 'a', startAngle: 0, endAngle: Math.PI },
+			],
+			[ 'a', 'b' ],
+		],
+		[
+			'clockwise semi-circle, left to right',
+			[
+				{ id: 'right', startAngle: 0, endAngle: half },
+				{ id: 'left', startAngle: -half, endAngle: 0 },
+			],
+			[ 'left', 'right' ],
+		],
+		[
+			'counter-clockwise semi-circle, left to right',
+			[
+				{ id: 'right', startAngle: half, endAngle: 0 },
+				{ id: 'left', startAngle: 0, endAngle: -half },
+			],
+			[ 'left', 'right' ],
+		],
+	] )( 'orders a %s', ( _, arcs, expected ) => {
+		expect( orderArcsForNavigation( arcs ).map( arc => arc.id ) ).toEqual( expected );
+	} );
+} );

package/src/charts/private/pie-keyboard-navigation/test/selected-segment-ring.test.ts

@@ -0,0 +1,14 @@
+import { toSvgId } from '../selected-segment-ring';
+
+describe( 'toSvgId', () => {
+	it.each( [
+		[ 'devices:1', 'devices/1' ],
+		[ 'a_3a_', 'a:' ],
+		[ ':r1:', '_r1_' ],
+	] )( 'keeps %s and %s apart', ( first, second ) => {
+		const ids = [ toSvgId( first ), toSvgId( second ) ];
+
+		expect( ids[ 0 ] ).not.toBe( ids[ 1 ] );
+		ids.forEach( id => expect( id ).toMatch( /^[A-Za-z0-9_-]+$/ ) );
+	} );
+} );

package/src/charts/private/pie-keyboard-navigation/use-pie-keyboard-navigation.ts

@@ -0,0 +1,139 @@
+import { useTooltip } from '@visx/tooltip';
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+import { useKeyboardNavigation } from '../../../components/tooltip';
+import type { DataPointPercentageCalculated } from '../../../types';
+import type { MouseEvent } from 'react';
+
+interface UsePieKeyboardNavigationProps< Arc > {
+	/** The visible arcs in `orderArcsForNavigation` order, which indexes run over. */
+	navigationArcs: Arc[];
+	withTooltips: boolean;
+	tooltipOffsetX: number;
+	tooltipOffsetY: number;
+}
+
+export const usePieKeyboardNavigation = < Arc extends { data: DataPointPercentageCalculated } >( {
+	navigationArcs,
+	withTooltips,
+	tooltipOffsetX,
+	tooltipOffsetY,
+}: UsePieKeyboardNavigationProps< Arc > ) => {
+	const chartRef = useRef< HTMLDivElement >( null );
+	const svgRef = useRef< SVGSVGElement >( null );
+	const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >( undefined );
+	const [ isNavigating, setIsNavigating ] = useState( false );
+	const { tooltipOpen, tooltipLeft, tooltipTop, tooltipData, hideTooltip, showTooltip } =
+		useTooltip< DataPointPercentageCalculated >();
+
+	const {
+		tooltipRef: focusTooltip,
+		onChartFocus,
+		onChartBlur,
+		onChartKeyDown,
+		onChartPointerMove,
+	} = useKeyboardNavigation( {
+		selectedIndex,
+		setSelectedIndex,
+		isNavigating,
+		setIsNavigating,
+		chartRef,
+		totalPoints: navigationArcs.length,
+		visibleSeriesKey: JSON.stringify( navigationArcs.map( arcDatum => arcDatum.data.label ) ),
+	} );
+
+	const selectedArc = selectedIndex === undefined ? undefined : navigationArcs[ selectedIndex ];
+
+	const keyboardTooltip = useRef< HTMLDivElement | null >( null );
+	const tooltipLostFocus = useRef( false );
+
+	// React detaches the ref before removing the node, so the tooltip still holds focus here.
+	const tooltipRef = useCallback(
+		( element: HTMLDivElement | null ) => {
+			if ( element ) {
+				keyboardTooltip.current = element;
+				focusTooltip( element );
+			} else if (
+				keyboardTooltip.current?.ownerDocument.activeElement === keyboardTooltip.current
+			) {
+				tooltipLostFocus.current = true;
+			}
+		},
+		[ focusTooltip ]
+	);
+
+	// Arrow keys mount the next tooltip in the same commit, so focus only reaches the body when the selection's tooltip went away.
+	useLayoutEffect( () => {
+		if ( ! tooltipLostFocus.current ) {
+			return;
+		}
+		tooltipLostFocus.current = false;
+		const { activeElement, body } = chartRef.current?.ownerDocument ?? document;
+		if ( activeElement === null || activeElement === body ) {
+			chartRef.current?.focus();
+		}
+	} );
+
+	const getSegmentHandlers = ( data: DataPointPercentageCalculated, navigationIndex: number ) => ( {
+		onMouseMove: ( event: MouseEvent< SVGElement > ) => {
+			onChartPointerMove( navigationIndex );
+			if ( ! withTooltips ) {
+				return;
+			}
+
+			// The tooltip renders inside `chartRef`, so pointer coordinates are taken relative to it.
+			const bounds = chartRef.current?.getBoundingClientRect();
+			if ( ! bounds ) {
+				return;
+			}
+
+			showTooltip( {
+				tooltipData: data,
+				tooltipLeft: event.clientX - bounds.left + tooltipOffsetX,
+				tooltipTop: event.clientY - bounds.top + tooltipOffsetY,
+			} );
+		},
+		onMouseLeave: withTooltips ? hideTooltip : undefined,
+	} );
+
+	/**
+	 * Anchors the keyboard tooltip at `point`, an offset from the origin of the group the arcs are drawn in.
+	 *
+	 * @param originX - The group's x in SVG coordinates.
+	 * @param originY - The group's y in SVG coordinates.
+	 * @param point   - The point relative to the group, such as an arc centroid.
+	 * @return The anchor in SVG coordinates, or undefined without tooltips.
+	 */
+	const getKeyboardTooltipAnchor = useCallback(
+		( originX: number, originY: number, [ x, y ]: [ number, number ] ) =>
+			withTooltips
+				? { left: originX + x + tooltipOffsetX, top: originY + y + tooltipOffsetY }
+				: undefined,
+		[ withTooltips, tooltipOffsetX, tooltipOffsetY ]
+	);
+
+	return {
+		chartRef,
+		svgRef,
+		selectedArc,
+		getSegmentHandlers,
+		getKeyboardTooltipAnchor,
+		selectionOutputProps: {
+			withTooltips,
+			selectedIndex,
+			selectedData: selectedArc?.data,
+			chartRef,
+			svgRef,
+			tooltipRef,
+			pointerTooltip: tooltipOpen
+				? { data: tooltipData, left: tooltipLeft || 0, top: tooltipTop || 0 }
+				: undefined,
+		},
+		chartProps: {
+			role: 'application',
+			tabIndex: 0,
+			onKeyDown: onChartKeyDown,
+			onFocus: onChartFocus,
+			onBlur: onChartBlur,
+		} as const,
+	};
+};

package/src/charts/private/x-zoom/test/x-zoom.test.tsx

@@ -212,11 +212,12 @@ describe( 'ZoomResetButton', () => {
 
 	test( 'keyboard activation survives the chart wrapper keydown handler', async () => {
 		const onClick = jest.fn();
-		// Mirrors the chart's grid wrapper, whose keyboard-navigation handler
+		// Mirrors the chart's focusable container, whose keyboard-navigation handler
 		// calls preventDefault() on bubbled keydowns — which would cancel the
 		// native Enter/Space button activation.
 		render(
-			<div role="grid" tabIndex={ 0 } onKeyDown={ preventDefaultKeydown }>
+			// eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- mirrors the charts' container.
+			<div role="application" tabIndex={ 0 } onKeyDown={ preventDefaultKeydown }>
 				<ZoomResetButton onClick={ onClick } />
 			</div>
 		);

package/src/components/tooltip/test/xy-chart-tooltip.test.tsx

@@ -42,7 +42,7 @@ const renderChart = ( scope?: HTMLElement, tooltipPlacement?: 'auto' | 'below-ax
 const openTooltip = async () => {
 	const user = userEvent.setup();
 
-	screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+	screen.getByRole( 'application', { name: /line chart/i } ).focus();
 	await user.keyboard( '{ArrowRight}' );
 
 	return screen.getByTestId( 'xy-chart-tooltip-crosshair-vertical' );
@@ -99,7 +99,7 @@ describe( 'XYChartTooltip', () => {
 		const user = userEvent.setup();
 		renderChart( undefined, 'below-axis' );
 		await openTooltip();
-		const focus = jest.spyOn( screen.getByRole( 'grid' ), 'focus' );
+		const focus = jest.spyOn( screen.getByRole( 'application' ), 'focus' );
 		try {
 			await user.keyboard( keys );
 			expect( focus ).toHaveBeenCalledWith( { preventScroll: true } );
@@ -115,7 +115,7 @@ describe( 'XYChartTooltip', () => {
 		const user = userEvent.setup();
 		renderChart();
 		await openTooltip();
-		const focus = jest.spyOn( screen.getByRole( 'grid' ), 'focus' );
+		const focus = jest.spyOn( screen.getByRole( 'application' ), 'focus' );
 		try {
 			await user.keyboard( keys );
 			expect( focus ).toHaveBeenCalledWith();
@@ -131,7 +131,7 @@ describe( 'XYChartTooltip', () => {
 	} );
 } );
 
-// Mirrors the charts' markup: the focusable grid wraps the element `chartRef` points at.
+// Mirrors the charts' markup: the focusable chart container wraps the element `chartRef` points at.
 const NavigationHarness = ( {
 	totalPoints,
 	trackBlur = false,
@@ -155,8 +155,9 @@ const NavigationHarness = ( {
 
 	return (
 		<>
+			{ /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- mirrors the charts' container. */ }
 			<div
-				role="grid"
+				role="application"
 				aria-label="Harness"
 				tabIndex={ 0 }
 				onKeyDown={ onChartKeyDown }
@@ -179,7 +180,7 @@ describe( 'useKeyboardNavigation', () => {
 		const user = userEvent.setup();
 		const view = render( <NavigationHarness totalPoints={ 6 } /> );
 
-		screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+		screen.getByRole( 'application', { name: 'Harness' } ).focus();
 		for ( let i = 0; i < presses; i++ ) {
 			await user.keyboard( '{ArrowRight}' );
 		}
@@ -188,13 +189,13 @@ describe( 'useKeyboardNavigation', () => {
 		return { user, view };
 	};
 
-	it( 'moves the selection to the last point when the count shrinks while the grid has focus', async () => {
+	it( 'moves the selection to the last point when the count shrinks while the chart has focus', async () => {
 		const { view } = await navigate( 6 );
 
 		view.rerender( <NavigationHarness totalPoints={ 3 } /> );
 
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '2' );
-		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+		expect( screen.getByRole( 'application', { name: 'Harness' } ) ).toHaveFocus();
 	} );
 
 	// In range rather than past the end: the effect reconciles on any count change, not only an overflow.
@@ -207,24 +208,24 @@ describe( 'useKeyboardNavigation', () => {
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
 	} );
 
-	it( 'returns focus to the grid on Escape when there are no points', async () => {
+	it( 'returns focus to the chart on Escape when there are no points', async () => {
 		const user = userEvent.setup();
 		render( <NavigationHarness totalPoints={ 0 } /> );
 
 		screen.getByRole( 'button', { name: 'Inside' } ).focus();
 		await user.keyboard( '{Escape}' );
 
-		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+		expect( screen.getByRole( 'application', { name: 'Harness' } ) ).toHaveFocus();
 	} );
 
-	it( 'returns focus to the grid when the count drops to zero while focus is in the chart', async () => {
+	it( 'returns focus to the chart when the count drops to zero while focus is in the chart', async () => {
 		const { view } = await navigate( 2 );
 
 		screen.getByRole( 'button', { name: 'Inside' } ).focus();
 		view.rerender( <NavigationHarness totalPoints={ 0 } /> );
 
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
-		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+		expect( screen.getByRole( 'application', { name: 'Harness' } ) ).toHaveFocus();
 	} );
 
 	it( 'hands a keyboard selection to the pointer and continues from where the pointer is', async () => {
@@ -234,7 +235,7 @@ describe( 'useKeyboardNavigation', () => {
 		await user.hover( screen.getByTestId( 'point-4' ) );
 
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
-		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+		expect( screen.getByRole( 'application', { name: 'Harness' } ) ).toHaveFocus();
 
 		await user.keyboard( '{ArrowRight}' );
 
@@ -254,13 +255,13 @@ describe( 'useKeyboardNavigation', () => {
 	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' } );
+		const chart = screen.getByRole( 'application', { name: 'Harness' } );
 
-		act( () => grid.focus() );
+		act( () => chart.focus() );
 		await user.keyboard( '{ArrowRight}{ArrowRight}' );
 		await user.hover( screen.getByTestId( 'point-4' ) );
 		act( () => screen.getByRole( 'button', { name: 'Outside' } ).focus() );
-		act( () => grid.focus() );
+		act( () => chart.focus() );
 		await user.keyboard( '{ArrowRight}' );
 
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '0' );
@@ -281,7 +282,7 @@ describe( 'useKeyboardNavigation', () => {
 		const user = userEvent.setup();
 		render( <NavigationHarness totalPoints={ 6 } /> );
 
-		screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+		screen.getByRole( 'application', { name: 'Harness' } ).focus();
 		await user.hover( screen.getByTestId( 'point-4' ) );
 		await user.keyboard( '{ArrowRight}' );
 
@@ -301,7 +302,7 @@ describe( 'useKeyboardNavigation', () => {
 		const { onKeyDown, stop } = recordPageKeyDown();
 
 		try {
-			screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+			screen.getByRole( 'application', { name: 'Harness' } ).focus();
 			await user.keyboard( '{ArrowDown}{PageDown}[Space]' );
 
 			expect( onKeyDown ).toHaveBeenCalledTimes( 3 );
@@ -320,7 +321,7 @@ describe( 'useKeyboardNavigation', () => {
 		const { onKeyDown, stop } = recordPageKeyDown();
 
 		try {
-			screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+			screen.getByRole( 'application', { name: 'Harness' } ).focus();
 			await user.keyboard( '{Escape}' );
 
 			expect( onKeyDown.mock.calls[ 0 ][ 0 ].defaultPrevented ).toBe( false );

package/src/components/tooltip/xy-chart-tooltip.tsx

@@ -261,10 +261,10 @@ export const useKeyboardNavigation = ( {
 	preventTooltipScroll = false,
 	visibleSeriesKey,
 }: UseKeyboardNavigationProps ) => {
-	// `chartRef` sits inside the focusable grid, so the grid is what focus returns to and is measured against.
+	// `chartRef` sits inside the focusable chart container, so that container is what focus returns to and is measured against.
 	const getChartRoot = useCallback(
 		(): HTMLElement | null =>
-			chartRef.current?.closest< HTMLElement >( '[role="grid"]' ) ?? chartRef.current,
+			chartRef.current?.closest< HTMLElement >( '[role="application"]' ) ?? chartRef.current,
 		[ chartRef ]
 	);
 
@@ -401,7 +401,7 @@ export const useKeyboardNavigation = ( {
 				pointerIndex.current = undefined;
 			}
 
-			// WAI-ARIA grid: arrows stop at the first and last cell.
+			// Arrows stop at the first and last point.
 			if ( event.key === 'ArrowRight' ) {
 				event.preventDefault();
 				setIsNavigating( true );

package/src/types.ts

@@ -191,7 +191,7 @@ export type DataPointDate = {
 	color?: string;
 };
 
-export type LeaderboardEntry = {
+type LeaderboardEntryFields = {
 	/**
 	 * Unique internal key (e.g., 'key-direct')
 	 */
@@ -245,7 +245,8 @@ export type LeaderboardEntry = {
 	 * For links or other interactive affordances (external-link icons, info
 	 * tooltips), put them in the `label` render prop instead of using onClick —
 	 * a row is either a button (onClick) or carries interactive label content,
-	 * never both, since interactive elements cannot be nested in HTML.
+	 * never both, since interactive elements cannot be nested in HTML. The
+	 * exception is a row that sets `hasInteractiveLabel`.
 	 */
 	onClick?: ( event: MouseEvent< HTMLButtonElement > ) => void;
 
@@ -261,6 +262,21 @@ export type LeaderboardEntry = {
 	ariaLabel?: string;
 };
 
+export type LeaderboardEntry = LeaderboardEntryFields &
+	(
+		| { hasInteractiveLabel?: false }
+		| {
+				/**
+				 * Set when the `label` holds its own link or button. The row's button
+				 * then sits behind the row instead of around it, so both stay operable.
+				 * Requires `onClick`, and `ariaLabel` since the button wraps no text.
+				 */
+				hasInteractiveLabel: true;
+				onClick: ( event: MouseEvent< HTMLButtonElement > ) => void;
+				ariaLabel: string;
+		  }
+	);
+
 export type GradientStop = {
 	offset: string;
 	color?: string;