@automattic/charts 4.7.0 → 4.8.0

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

@@ -1,326 +1,436 @@
-import { Tooltip } from '@visx/tooltip';
-import { DataContext, TooltipContext } from '@visx/xychart';
+import { TooltipContext } from '@visx/xychart';
 import clsx from 'clsx';
-import { useCallback, useContext, useState } from 'react';
-import { createPortal } from 'react-dom';
-import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
-import styles from './base-tooltip.module.scss';
-import { BoundedTooltip, TOOLTIP_Z_INDEX } from './private/bounded-tooltip';
-import { TooltipTheme } from './private/tooltip-theme';
-import type {
-	CrosshairStyle,
-	RenderTooltipGlyphProps,
-	XyChartTooltipProps,
-} from '../../visx/types';
-import type { TooltipContextType } from '@visx/xychart';
-import type { CSSProperties, ReactNode } from 'react';
-
-const CROSSHAIR_STROKE_WIDTH = 1.5;
-const CROSSHAIR_PAINT_PROPERTIES = new Set( [
-	'stroke',
-	'strokeWidth',
-	'strokeOpacity',
-	'strokeDasharray',
-	'strokeLinecap',
-	'opacity',
-] );
-
-const crosshairPaintProps = ( props: CrosshairStyle = {} ) => {
-	const pickPaint = ( value: object ) =>
-		Object.fromEntries(
-			Object.entries( value ).filter( ( [ key ] ) => CROSSHAIR_PAINT_PROPERTIES.has( key ) )
-		);
+import { useContext, useEffect, useCallback, useMemo, useRef } from 'react';
+import { ChartInstanceContext } from '../../charts/private/chart-instance-context';
+import { useGlobalChartsContext } from '../../providers/chart-context/hooks/use-global-charts-context';
+import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
+import { useChartScopeElement, useStandaloneScopeClass } from '../../providers/chart-scope';
+import { resolveCssVariable } from '../../utils';
+import { XyChartTooltipOverlay } from './private/xy-chart-tooltip-overlay';
+import type { SeriesData, DataPointDate } from '../../types';
+import type { RenderTooltipParams, XyChartTooltipProps } from '../../visx/types';
+import type { ReactNode } from 'react';
 
-	return {
-		...pickPaint( props ),
-		...( props.className === undefined ? {} : { className: props.className } ),
-		...( props.style === undefined ? {} : { style: pickPaint( props.style ) } ),
-	};
-};
-const DEFAULT_GLYPH_RADIUS = 4;
-const FALLBACK_COLOR = '#222';
-// Portal-era options, accepted for compatibility and dropped before the box
-// renders: it sits in the chart wrapper and moves with it, and nothing
-// measures it any more.
-const PORTAL_OPTIONS = new Set( [ 'scroll', 'debounce', 'resizeObserverPolyfill' ] );
-
-type ScaleFn = ( value: unknown ) => number | undefined;
-
-const isValidNumber = ( value: unknown ): value is number =>
-	typeof value === 'number' && Number.isFinite( value );
-
-// Band scales place a datum at the start of its band; snapping targets the band's centre.
-// A d3 scale is a function that carries `bandwidth` as a property.
-const scaleBandwidth = ( scale: unknown ): number => {
-	const bandwidth = ( scale as { bandwidth?: unknown } | null | undefined )?.bandwidth;
-	return typeof bandwidth === 'function' ? Number( bandwidth() ) : 0;
+// Type for flattened tooltip data used in individual mode
+export type FlattenedTooltipData = {
+	datum: DataPointDate;
+	seriesLabel: string;
+	seriesIndex: number;
+	dataPointIndex: number;
 };
 
-const DefaultGlyph = < Datum extends object >( {
-	x,
-	y,
-	size,
-	color,
-	glyphStyle,
-	seriesKey,
-}: Omit< RenderTooltipGlyphProps< Datum >, 'key' > & { seriesKey: string } ) => {
-	const { theme } = useContext( DataContext ) || {};
-
-	return (
-		<circle
-			data-testid={ `xy-chart-tooltip-glyph-${ seriesKey }` }
-			cx={ x }
-			cy={ y }
-			r={ size }
-			fill={ color }
-			stroke={ theme?.backgroundColor }
-			strokeWidth={ CROSSHAIR_STROKE_WIDTH }
-			paintOrder="fill"
-			{ ...glyphStyle }
-		/>
-	);
-};
-
-const defaultRenderGlyph = < Datum extends object >( {
-	key,
-	...props
-}: RenderTooltipGlyphProps< Datum > ) => (
-	<DefaultGlyph key={ key } seriesKey={ key } { ...props } />
-);
-
-type XyChartTooltipContentProps< Datum extends object > = XyChartTooltipProps< Datum > & {
-	tooltipContext: TooltipContextType< Datum >;
-	/** The SVG's HTML parent once found. The box waits for it; the SVG overlay does not. */
-	container: HTMLElement | null;
-};
+/** The XY chart tooltip that LineChart, AreaChart and BarChart render; place it inside a visx `XYChart`. */
+interface XYChartTooltipProps extends Omit<
+	XyChartTooltipProps< DataPointDate >,
+	'renderTooltip'
+> {
+	renderTooltip?: ( params: RenderTooltipParams< DataPointDate > ) => ReactNode;
+	selectedIndex?: number | undefined;
+	tooltipRef?: ( element: HTMLDivElement | null ) => void;
+	keyboardFocusedClassName?: string;
+	/**
+	 * Flattened tooltip data prepared by parent component
+	 * Each index corresponds to one tooltip to show
+	 */
+	tooltipData?: FlattenedTooltipData[];
+	/**
+	 * For line charts: series data to show all series at selected data point
+	 * When provided, shows all series instead of individual tooltips
+	 */
+	series?: SeriesData[];
+	/**
+	 * Whether to combine tooltip information from multiple series into a single tooltip. This is useful for line charts.
+	 * Or to show individual tooltips for each series. This is useful for bar charts.
+	 */
+	mode?: 'individual' | 'group';
+}
 
-const XyChartTooltipContent = < Datum extends object >( {
-	tooltipContext,
-	container,
+export const XYChartTooltip: React.FC< XYChartTooltipProps > = ( {
 	renderTooltip,
-	renderGlyph = defaultRenderGlyph,
-	glyphStyle,
-	snapTooltipToDatumX = false,
-	snapTooltipToDatumY = false,
-	showVerticalCrosshair = false,
-	showHorizontalCrosshair = false,
-	showDatumGlyph = false,
-	showSeriesGlyphs = false,
+	selectedIndex,
+	tooltipRef,
+	keyboardFocusedClassName,
+	series = [],
+	mode = 'group',
 	verticalCrosshairStyle,
 	horizontalCrosshairStyle,
-	detectBounds = true,
-	tooltipPlacement = 'auto',
-	tooltipAnchorTop,
-	zIndex = TOOLTIP_Z_INDEX,
-	style,
-	...rest
-}: XyChartTooltipContentProps< Datum > ) => {
-	const tooltipProps = Object.fromEntries(
-		Object.entries( rest ).filter( ( [ key ] ) => ! PORTAL_OPTIONS.has( key ) )
-	) as Omit< typeof rest, 'scroll' | 'debounce' | 'resizeObserverPolyfill' >;
-	const {
-		colorScale,
-		theme,
-		innerHeight = 0,
-		innerWidth = 0,
-		margin,
-		xScale,
-		yScale,
-		dataRegistry,
-	} = useContext( DataContext ) || {};
-
-	const tooltipContent = renderTooltip ? renderTooltip( { ...tooltipContext, colorScale } ) : null;
-	if ( tooltipContent == null ) {
-		return null;
-	}
-
-	const scaleX = xScale as ScaleFn | undefined;
-	const scaleY = yScale as ScaleFn | undefined;
-
-	// Datum position in SVG coordinates, from the accessors the series registered.
-	const getDatumLeftTop = ( key: string, datum: Datum ) => {
-		const entry = dataRegistry?.get( key );
-		const left =
-			scaleX && entry?.xAccessor
-				? Number( scaleX( entry.xAccessor( datum ) ) ) + scaleBandwidth( xScale ) / 2
-				: undefined;
-		const top =
-			scaleY && entry?.yAccessor
-				? Number( scaleY( entry.yAccessor( datum ) ) ) + scaleBandwidth( yScale ) / 2
-				: undefined;
-		return { left, top };
-	};
+	...props
+} ) => {
+	const tooltipContext = useContext( TooltipContext );
+	const scopeElement = useChartScopeElement();
 
-	const nearestDatum = tooltipContext.tooltipData?.nearestDatum;
-	let { tooltipLeft, tooltipTop } = tooltipContext;
+	// The stroke is read at the scope element, which a consumer can set outside the chart's own ancestors; see TOKENS.md#the-svg-bridge.
+	const crosshairStroke = useMemo( () => {
+		const stroke = resolveCssVariable( CATALOG_POINTERS.grid, scopeElement );
 
-	if (
-		nearestDatum &&
-		( snapTooltipToDatumX || snapTooltipToDatumY || tooltipPlacement === 'below-axis' )
-	) {
-		const { left, top } = getDatumLeftTop( nearestDatum.key, nearestDatum.datum );
-		if ( ( snapTooltipToDatumX || tooltipPlacement === 'below-axis' ) && isValidNumber( left ) ) {
-			tooltipLeft = left;
-		}
-		if ( snapTooltipToDatumY && isValidNumber( top ) ) {
-			tooltipTop = top;
+		// Passing `stroke: undefined` would erase the crosshair: it overrides visx's own value, and SVG's initial `stroke` is `none`.
+		return stroke ? { stroke } : undefined;
+	}, [ scopeElement ] );
+
+	const standaloneScopeClass = useStandaloneScopeClass();
+
+	const tooltipData = useMemo( () => {
+		if ( mode !== 'individual' ) return [];
+		if ( series.length === 0 ) return [];
+
+		const maxDataPoints = Math.max( ...series.map( s => s.data.length ) );
+		const flattened: Array< {
+			datum: DataPointDate;
+			seriesLabel: string;
+			seriesIndex: number;
+			dataPointIndex: number;
+		} > = [];
+
+		// Pattern: [series1[0], series2[0], series3[0], series1[1], series2[1], series3[1], ...]
+		for ( let dataPointIndex = 0; dataPointIndex < maxDataPoints; dataPointIndex++ ) {
+			for ( let seriesIndex = 0; seriesIndex < series.length; seriesIndex++ ) {
+				const seriesData = series[ seriesIndex ];
+				if ( dataPointIndex < seriesData.data.length ) {
+					flattened.push( {
+						datum: seriesData.data[ dataPointIndex ] as DataPointDate,
+						seriesLabel: seriesData.label,
+						seriesIndex,
+						dataPointIndex,
+					} );
+				}
+			}
 		}
-	}
-
-	const glyphs: ReactNode[] = [];
-	if ( showDatumGlyph || showSeriesGlyphs ) {
-		const size = Number( glyphStyle?.radius ?? DEFAULT_GLYPH_RADIUS );
-		const labelColor = theme?.htmlLabel?.color ?? FALLBACK_COLOR;
-		// visx colours a lone nearest-datum glyph like the gridlines and series glyphs like labels.
-		const fallbackColor = showSeriesGlyphs
-			? labelColor
-			: ( theme?.gridStyles?.stroke ?? labelColor );
-		let entries: Array< { key: string; datum: Datum; index: number } > = [];
-		if ( showSeriesGlyphs ) {
-			entries = Object.values( tooltipContext.tooltipData?.datumByKey ?? {} );
-		} else if ( nearestDatum ) {
-			entries = [ nearestDatum ];
+
+		return flattened;
+	}, [ series, mode ] );
+
+	// Tracks whether this effect opened a tooltip, so it only closes its own.
+	const hasKeyboardSelection = useRef( false );
+
+	// visx's own `hideTooltip` is debounced by 400ms, long enough for a stale datum to be
+	// repainted against a changed series list. This is the undebounced close it wraps.
+	const closeTooltipNow = useCallback( () => {
+		tooltipContext?.updateTooltip( {
+			tooltipOpen: false,
+			tooltipLeft: undefined,
+			tooltipTop: undefined,
+			tooltipData: undefined,
+		} );
+		// Don't include tooltipContext in the dependency array to avoid loop.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [] );
+
+	const chartId = useContext( ChartInstanceContext )?.chartId;
+	const { getHiddenSeries } = useGlobalChartsContext();
+	const hiddenSeriesKey = chartId
+		? JSON.stringify( [ ...getHiddenSeries( chartId ) ].sort() )
+		: undefined;
+	const lastHiddenSeriesKey = useRef( hiddenSeriesKey );
+
+	// Hiding a series re-points every tooltip index at a different series, so a tooltip opened by
+	// the pointer would keep showing a datum that is no longer on the chart. Nothing else closes
+	// it: the pointer has not moved, so visx never fires the leave that would.
+	useEffect( () => {
+		const changed = lastHiddenSeriesKey.current !== hiddenSeriesKey;
+		lastHiddenSeriesKey.current = hiddenSeriesKey;
+
+		// A keyboard selection is reconciled by `useKeyboardNavigation` instead, which either
+		// re-shows the tooltip at a valid index or clears the selection for the branch below.
+		if ( changed && selectedIndex === undefined ) {
+			closeTooltipNow();
 		}
+	}, [ hiddenSeriesKey, selectedIndex, closeTooltipNow ] );
 
-		for ( const { key, datum, index } of entries ) {
-			const { left, top } = getDatumLeftTop( key, datum );
-			if ( ! isValidNumber( left ) || ! isValidNumber( top ) ) {
-				continue;
+	// Handle tooltip highlighting for keyboard navigation
+	useEffect( () => {
+		if ( selectedIndex === undefined ) {
+			// visx debounces the hide and cancels only the most recently scheduled one,
+			// so hiding on every run leaves earlier hides pending. One of those lands
+			// mid-navigation and closes the tooltip the user is reading.
+			if ( hasKeyboardSelection.current ) {
+				hasKeyboardSelection.current = false;
+				closeTooltipNow();
 			}
-			// The group carries the position and the renderer draws at the origin,
-			// as with visx's portal: a renderer that ignores `x` and `y` still lands
-			// on its datum.
-			glyphs.push(
-				<g
-					key={ key }
-					className="visx-tooltip-glyph"
-					data-testid={ `xy-chart-tooltip-glyph-group-${ key }` }
-					transform={ `translate(${ left }, ${ top })` }
-				>
-					{ renderGlyph( {
-						key,
-						color: colorScale?.( key ) ?? fallbackColor,
+			return;
+		}
+
+		hasKeyboardSelection.current = true;
+
+		if ( mode === 'group' ) {
+			// Show all series at the selected data point index in single tooltip.
+			series.forEach( ( s, index ) => {
+				if ( selectedIndex < s.data.length ) {
+					const datum = s.data[ selectedIndex ];
+
+					tooltipContext?.showTooltip( {
 						datum,
+						key: s.label,
 						index,
-						size,
-						x: 0,
-						y: 0,
-						glyphStyle,
-						isNearestDatum: nearestDatum?.key === key,
-					} ) }
-				</g>
-			);
+					} );
+				}
+			} );
+		} else if ( mode === 'individual' ) {
+			// Show individual tooltips for each datapoint from each series.
+			if ( selectedIndex < tooltipData.length ) {
+				const tooltipItem = tooltipData[ selectedIndex ];
+
+				tooltipContext?.showTooltip( {
+					datum: tooltipItem.datum,
+					key: tooltipItem.seriesLabel,
+					index: tooltipItem.dataPointIndex,
+				} );
+			}
 		}
-	}
-
-	const crosshairStroke = theme?.gridStyles?.stroke ?? theme?.htmlLabel?.color ?? FALLBACK_COLOR;
-	const marginTop = margin?.top ?? 0;
-	const marginLeft = margin?.left ?? 0;
-
-	const TooltipComponent = detectBounds || tooltipPlacement !== 'auto' ? BoundedTooltip : Tooltip;
-	const boxStyle: CSSProperties = { zIndex, ...style };
-	// BoundedTooltip themes its own box.
-	const themesOwnBox = TooltipComponent === Tooltip && ! tooltipProps.unstyled;
-	const box = (
-		<TooltipComponent
-			left={ tooltipLeft }
-			top={
-				tooltipPlacement === 'below-axis'
-					? marginTop + innerHeight + ( margin?.bottom ?? 0 )
-					: ( tooltipAnchorTop ?? tooltipTop )
+
+		// Don't include tooltipContext in the dependency array to avoid loop.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [ selectedIndex, tooltipData, series ] );
+
+	// Create a focusable renderTooltip that includes accessibility features
+	const focusableRenderTooltip = useMemo( () => {
+		if ( ! renderTooltip ) return undefined;
+
+		return ( params: RenderTooltipParams< DataPointDate > ) => {
+			const tooltipContent = renderTooltip( params );
+
+			if ( selectedIndex !== undefined ) {
+				return (
+					<div
+						ref={ tooltipRef }
+						tabIndex={ -1 }
+						role="tooltip"
+						aria-atomic="true"
+						className={ clsx( standaloneScopeClass, keyboardFocusedClassName ) }
+						data-testid={ `chart-tooltip-${ selectedIndex }` }
+						key={ `chart-tooltip-${ selectedIndex }` }
+					>
+						{ tooltipContent }
+					</div>
+				);
 			}
-			style={ boxStyle }
-			applyPositionStyle
-			{ ...tooltipProps }
-			className={ clsx(
-				themesOwnBox && [ CHART_SCOPE_CLASS, styles.surface ],
-				tooltipProps.className
-			) }
-			{ ...( tooltipPlacement !== 'auto' && { placement: tooltipPlacement } ) }
-		>
-			{ tooltipContent }
-		</TooltipComponent>
-	);
+
+			return (
+				<div className={ standaloneScopeClass } role="tooltip" aria-live="polite">
+					{ tooltipContent }
+				</div>
+			);
+		};
+	}, [ renderTooltip, selectedIndex, tooltipRef, keyboardFocusedClassName, standaloneScopeClass ] );
 
 	return (
-		<>
-			<g className="visx-tooltip-overlay" pointerEvents="none">
-				{ showVerticalCrosshair && isValidNumber( tooltipLeft ) && (
-					<line
-						className="visx-crosshair visx-crosshair-vertical"
-						data-testid="xy-chart-tooltip-crosshair-vertical"
-						stroke={ crosshairStroke }
-						strokeWidth={ CROSSHAIR_STROKE_WIDTH }
-						{ ...crosshairPaintProps( verticalCrosshairStyle ) }
-						x1={ tooltipLeft }
-						x2={ tooltipLeft }
-						y1={ marginTop }
-						y2={ marginTop + innerHeight }
-					/>
-				) }
-				{ showHorizontalCrosshair && isValidNumber( tooltipTop ) && (
-					<line
-						className="visx-crosshair visx-crosshair-horizontal"
-						data-testid="xy-chart-tooltip-crosshair-horizontal"
-						stroke={ crosshairStroke }
-						strokeWidth={ CROSSHAIR_STROKE_WIDTH }
-						{ ...crosshairPaintProps( horizontalCrosshairStyle ) }
-						x1={ marginLeft }
-						x2={ marginLeft + innerWidth }
-						y1={ tooltipTop }
-						y2={ tooltipTop }
-					/>
-				) }
-				{ glyphs }
-			</g>
-			{ container &&
-				createPortal( themesOwnBox ? <TooltipTheme>{ box }</TooltipTheme> : box, container ) }
-		</>
+		<XyChartTooltipOverlay
+			{ ...props }
+			verticalCrosshairStyle={ { ...crosshairStroke, ...verticalCrosshairStyle } }
+			horizontalCrosshairStyle={ { ...crosshairStroke, ...horizontalCrosshairStyle } }
+			renderTooltip={ focusableRenderTooltip }
+		/>
 	);
 };
 
-/**
- * In-tree replacement for `@visx/xychart`'s `Tooltip`.
- *
- * visx renders its tooltip box, glyphs and crosshairs through portals appended
- * to `document.body`. That puts them in the page's root stacking context, where
- * they paint above every sticky or fixed element that lives inside a nested
- * stacking context, and no z-index on that element can change the order. This
- * component draws the glyphs and crosshairs straight into the chart SVG and
- * renders the tooltip box into the SVG's parent element, so all of them stack
- * as ordinary descendants of the chart.
- *
- * Render it as a child of `XYChart`. The element wrapping that `XYChart` must
- * be `position: relative` with the SVG at its origin, and `isolation: isolate`:
- * the box is placed with the SVG-local coordinates visx reports, and the
- * isolation keeps the box's `zIndex` from competing with page chrome. The box
- * flips and clamps to stay inside the nearest ancestor that clips its overflow
- * (or the viewport), so it may extend past the chart wrapper but is never cut
- * off unless that ancestor is smaller than the box itself. Below-axis placement
- * pins it beneath the x-axis and applies horizontal bounds only.
- *
- * @param props - visx's `Tooltip` options. `scroll`, `debounce` and `resizeObserverPolyfill` are accepted and ignored.
- * @return An anchor in the SVG, plus the overlay and the tooltip box while the tooltip is open.
- */
-export const XyChartTooltip = < Datum extends object >( props: XyChartTooltipProps< Datum > ) => {
-	const tooltipContext = useContext( TooltipContext ) as TooltipContextType< Datum > | null;
-	const [ container, setContainer ] = useState< HTMLElement | null >( null );
-
-	// Children of XYChart render inside its SVG, and the box needs an HTML parent.
-	const anchorRef = useCallback( ( node: SVGGElement | null ) => {
-		setContainer( node?.ownerSVGElement?.parentElement ?? null );
-	}, [] );
+/** @deprecated Use `XYChartTooltip`. */
+export const AccessibleTooltip = XYChartTooltip;
 
-	return (
-		<>
-			<g ref={ anchorRef } data-testid="xy-chart-tooltip-anchor" />
-			{ tooltipContext?.tooltipOpen && (
-				<XyChartTooltipContent
-					{ ...props }
-					tooltipContext={ tooltipContext }
-					container={ container }
-				/>
-			) }
-		</>
+// Keyboard navigation hook for charts
+interface UseKeyboardNavigationProps {
+	selectedIndex: number | undefined;
+	setSelectedIndex: ( index: number | undefined ) => void;
+	isNavigating: boolean;
+	setIsNavigating: ( navigating: boolean ) => void;
+	chartRef: React.RefObject< HTMLDivElement >;
+	/**
+	 * Total number of navigation points (length of tooltip data array)
+	 */
+	totalPoints: number;
+	/**
+	 * Called with the selected index on Enter or Space, so a chart can treat the
+	 * keyboard selection the way it treats a click.
+	 */
+	onActivate?: ( index: number ) => void;
+	preventTooltipScroll?: boolean;
+	/**
+	 * Identity of the series the navigation indexes run over, for charts whose index space depends
+	 * on which series are visible. Swapping one hidden series for another of the same length leaves
+	 * `totalPoints` unchanged, so the count alone cannot detect it.
+	 */
+	visibleSeriesKey?: string;
+}
+
+export const useKeyboardNavigation = ( {
+	selectedIndex,
+	setSelectedIndex,
+	isNavigating,
+	setIsNavigating,
+	chartRef,
+	totalPoints,
+	onActivate,
+	preventTooltipScroll = false,
+	visibleSeriesKey,
+}: UseKeyboardNavigationProps ) => {
+	// `chartRef` sits inside the focusable grid, so the grid is what focus returns to and is measured against.
+	const getChartRoot = useCallback(
+		(): HTMLElement | null =>
+			chartRef.current?.closest< HTMLElement >( '[role="grid"]' ) ?? chartRef.current,
+		[ chartRef ]
+	);
+
+	const focusWithoutScrollIfNeeded = useCallback(
+		( element: HTMLElement | null | undefined ) => {
+			if ( preventTooltipScroll ) {
+				element?.focus( { preventScroll: true } );
+			} else {
+				element?.focus();
+			}
+		},
+		[ preventTooltipScroll ]
 	);
+
+	// Focus the tooltip as soon as it is rendered
+	const tooltipRef = useCallback(
+		( element: HTMLDivElement | null ) => {
+			if ( element && selectedIndex !== undefined ) {
+				focusWithoutScrollIfNeeded( element );
+			}
+		},
+		[ focusWithoutScrollIfNeeded, selectedIndex ]
+	);
+
+	const previousTotalPoints = useRef( totalPoints );
+	const previousVisibleSeriesKey = useRef( visibleSeriesKey );
+
+	// Hiding or showing a series moves every index onto a different bar. The count alone misses a
+	// swap that keeps it the same, such as hiding one series while revealing another of equal length.
+	// Clear rather than clamp once focus has left the chart: a new tooltip would pull focus back.
+	useEffect( () => {
+		const countChanged = previousTotalPoints.current !== totalPoints;
+		const seriesChanged = previousVisibleSeriesKey.current !== visibleSeriesKey;
+		previousTotalPoints.current = totalPoints;
+		previousVisibleSeriesKey.current = visibleSeriesKey;
+
+		if ( ( ! countChanged && ! seriesChanged ) || selectedIndex === undefined ) {
+			return;
+		}
+
+		const { activeElement } = document;
+		const focusIsInChart = activeElement !== null && !! getChartRoot()?.contains( activeElement );
+
+		// A swap that leaves the count alone gives the same index a different series, so unlike a
+		// count change there is no shorter range to clamp into.
+		if ( totalPoints === 0 || ! focusIsInChart || ! countChanged ) {
+			setSelectedIndex( undefined );
+			setIsNavigating( false );
+			// Clearing unmounts the focused tooltip, which would drop focus to the body.
+			if ( focusIsInChart ) {
+				focusWithoutScrollIfNeeded( getChartRoot() );
+			}
+			return;
+		}
+
+		setSelectedIndex( Math.min( selectedIndex, totalPoints - 1 ) );
+	}, [
+		selectedIndex,
+		totalPoints,
+		visibleSeriesKey,
+		setSelectedIndex,
+		setIsNavigating,
+		getChartRoot,
+		focusWithoutScrollIfNeeded,
+	] );
+
+	// Returning focus from the tooltip must not restore the selection Escape just cleared.
+	const onChartFocus = useCallback(
+		( event: React.FocusEvent< HTMLDivElement > ) => {
+			if ( event.currentTarget.contains( event.relatedTarget ) ) {
+				return;
+			}
+			if ( ! isNavigating && selectedIndex !== undefined ) {
+				setSelectedIndex( 0 );
+			}
+		},
+		[ 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(
+		( event: React.FocusEvent< HTMLDivElement > ) => {
+			setIsNavigating( false );
+			if ( ! event.currentTarget.contains( event.relatedTarget ) ) {
+				pointerIndex.current = undefined;
+			}
+		},
+		[ setIsNavigating ]
+	);
+
+	const onChartKeyDown = useCallback(
+		( event: React.KeyboardEvent< HTMLDivElement > ) => {
+			if ( event.key === 'Tab' || event.key === 'Escape' ) {
+				// Consuming Escape with nothing open would swallow the first Escape of a surrounding Modal.
+				if ( event.key === 'Escape' && selectedIndex !== undefined ) {
+					event.preventDefault();
+				}
+				focusWithoutScrollIfNeeded( getChartRoot() );
+				setSelectedIndex( undefined );
+				setIsNavigating( false );
+				pointerIndex.current = undefined;
+				return;
+			}
+
+			if ( totalPoints === 0 ) return;
+
+			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' ) {
+				event.preventDefault();
+				setIsNavigating( true );
+				setSelectedIndex( Math.min( currentSelectedIndex + 1, totalPoints - 1 ) );
+			} else if ( event.key === 'ArrowLeft' ) {
+				event.preventDefault();
+				setIsNavigating( true );
+				setSelectedIndex( Math.max( currentSelectedIndex - 1, 0 ) );
+			} else if ( ( event.key === 'Enter' || event.key === ' ' ) && selectedIndex !== undefined ) {
+				event.preventDefault();
+				onActivate?.( selectedIndex );
+			}
+		},
+		[
+			totalPoints,
+			selectedIndex,
+			setSelectedIndex,
+			setIsNavigating,
+			getChartRoot,
+			focusWithoutScrollIfNeeded,
+			onActivate,
+		]
+	);
+
+	return {
+		tooltipRef,
+		onChartFocus,
+		onChartBlur,
+		onChartKeyDown,
+		onChartPointerMove,
+	};
 };