@automattic/charts 4.12.0 → 4.13.0

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

@@ -9,6 +9,7 @@ import { useGlobalChartsContext } from '../../../providers/chart-context/hooks/u
 import LineChart, { LineChartUnresponsive, renderDefaultTooltip } from '../line-chart';
 import type { GlobalChartsContextValue } from '../../../providers/chart-context/types';
 import type { DataPointDate, SeriesData } from '../../../types';
+import type { RenderTooltipParams } from '../../../visx/types';
 import type { ChartInstanceRef } from '../../private/chart-instance-context';
 import type { RenderLineGlyphProps } from '../types';
 
@@ -1696,6 +1697,80 @@ describe( 'LineChart', () => {
 			} );
 		} );
 
+		describe( 'Keyboard stops by date', () => {
+			const point = ( day: number, value: number | null ) => ( {
+				date: new Date( `2024-01-0${ day }` ),
+				value,
+			} );
+			const rowsTooltip = ( { tooltipData }: RenderTooltipParams< DataPointDate > ) => (
+				<div data-testid="rows-tooltip">
+					{ Object.values( tooltipData?.datumByKey ?? {} )
+						.map( ( { key, datum } ) => `${ key }=${ datum.value }` )
+						.sort()
+						.join( ';' ) }
+				</div>
+			);
+			const renderRows = ( data: SeriesData[], props = {} ) => {
+				renderWithTheme( { data, withTooltips: true, renderTooltip: rowsTooltip, ...props } );
+				screen.getByRole( 'application', { name: /line chart/i } ).focus();
+			};
+
+			it( 'stops at every date any series has and reads each series there', async () => {
+				const user = userEvent.setup();
+				renderRows( [
+					{ label: 'A', data: [ point( 1, 1 ), point( 2, 2 ), point( 3, 3 ) ] },
+					{ label: 'B', data: [ point( 2, 20 ), point( 4, 40 ) ] },
+				] );
+
+				const expected = [
+					{ text: 'A=1', stop: 0 },
+					{ text: 'A=2;B=20', stop: 1 },
+					{ text: 'A=3', stop: 2 },
+					{ text: 'B=40', stop: 3 },
+					{ text: 'B=40', stop: 3 },
+				];
+				for ( const { text, stop } of expected ) {
+					await user.keyboard( '{ArrowRight}' );
+					await waitFor( () => {
+						expect( screen.getByTestId( `chart-tooltip-${ stop }` ) ).toBeInTheDocument();
+						expect( screen.getByTestId( 'rows-tooltip' ) ).toHaveTextContent(
+							new RegExp( `^${ text }$` )
+						);
+					} );
+				}
+			} );
+
+			it( 'keeps a null point at the selected date', async () => {
+				const user = userEvent.setup();
+				renderRows( [
+					{ label: 'A', data: [ point( 1, 1 ), point( 2, 2 ) ] },
+					{ label: 'B', data: [ point( 1, null ), point( 2, 20 ) ] },
+				] );
+
+				await user.keyboard( '{ArrowRight}' );
+				await expect( screen.findByTestId( 'rows-tooltip' ) ).resolves.toHaveTextContent(
+					/^A=1;B=null$/
+				);
+			} );
+
+			it( 'activates the first visible series with a point at the selected date', async () => {
+				const user = userEvent.setup();
+				const onDatumActivate = jest.fn();
+				const seriesB = { label: 'Series B', data: [ point( 1, 10 ), point( 2, 20 ) ] };
+				renderRows( [ { label: 'Series A', data: [ point( 2, 2 ) ] }, seriesB ], {
+					onDatumActivate,
+				} );
+
+				await user.keyboard( '{ArrowRight}{Enter}' );
+
+				expect( onDatumActivate ).toHaveBeenCalledWith( {
+					key: 'Series B',
+					index: 0,
+					datum: seriesB.data[ 0 ],
+				} );
+			} );
+		} );
+
 		describe( 'Arrow Key Navigation', () => {
 			test.each( [ 'auto', 'below-axis' ] as const )(
 				'right arrow key navigates with %s tooltips',

package/src/components/tooltip/private/at-nearest-date.ts

@@ -0,0 +1,49 @@
+import type { AxisScale } from '@visx/axis';
+import type { DataRegistryEntry, TooltipContextType } from '@visx/xychart';
+
+type TooltipData< Datum extends object > = TooltipContextType< Datum >[ 'tooltipData' ];
+
+type Registry< Datum extends object > = {
+	entries: () => DataRegistryEntry< AxisScale, AxisScale, Datum >[];
+};
+
+const timeOf = ( datum: object ): number | undefined =>
+	( datum as { date?: Date } ).date?.getTime();
+
+/**
+ * Lists every registered series at the nearest datum's date, each with its own point there.
+ *
+ * The pointer hands each series its own nearest point, which for a series that skips that date, or that the pointer sits nearer another date of, is a neighbor's.
+ *
+ * @param tooltipData - The tooltip data visx collected.
+ * @param registry    - The chart's data registry.
+ * @return The tooltip data, unchanged when the nearest datum has no date.
+ */
+export const atNearestDate = < Datum extends object >(
+	tooltipData: TooltipData< Datum >,
+	registry: Registry< Datum > | undefined
+): TooltipData< Datum > => {
+	const nearest = tooltipData?.nearestDatum?.datum;
+	const time = nearest ? timeOf( nearest ) : undefined;
+
+	if ( ! tooltipData || time === undefined ) {
+		return tooltipData;
+	}
+
+	const datumByKey: NonNullable< TooltipData< Datum > >[ 'datumByKey' ] = {};
+	for ( const { key, data } of registry?.entries() ?? [] ) {
+		const index = data.findIndex( datum => timeOf( datum ) === time );
+		if ( index !== -1 ) {
+			datumByKey[ key ] = { key, index, datum: data[ index ] };
+		}
+	}
+
+	// Stacked series register points without a date, so their own nearest point is kept when it is at that date.
+	for ( const [ key, entry ] of Object.entries( tooltipData.datumByKey ) ) {
+		if ( ! datumByKey[ key ] && timeOf( entry.datum ) === time ) {
+			datumByKey[ key ] = entry;
+		}
+	}
+
+	return { ...tooltipData, datumByKey };
+};

package/src/components/tooltip/private/keyboard-stops.ts

@@ -0,0 +1,67 @@
+import type { DataPointDate, SeriesData } from '../../../types';
+
+/** A series' point at a keyboard stop. */
+export type StopMember = { series: SeriesData; datum: DataPointDate; index: number };
+
+export type KeyboardStops = {
+	count: number;
+	membersAt: ( stop: number ) => StopMember[];
+};
+
+const timeOf = ( point: unknown ): number | undefined =>
+	( point as DataPointDate | undefined )?.date?.getTime();
+
+const getXPositions = ( series: SeriesData[] ): number[] => {
+	const positions = new Set< number >();
+
+	for ( const { data } of series ) {
+		for ( const point of data ) {
+			const time = timeOf( point );
+			if ( time !== undefined ) {
+				positions.add( time );
+			}
+		}
+	}
+
+	return [ ...positions ].sort( ( a, b ) => a - b );
+};
+
+/**
+ * Keyboard stops over the series: the sorted union of their dates, or array indexes when no point has a date.
+ *
+ * Once any point has a date, a series of undated points has no stop.
+ *
+ * @param series - The series to step through.
+ * @return The stop count, and each series' point at a stop.
+ */
+export const getKeyboardStops = ( series: SeriesData[] ): KeyboardStops => {
+	const positions = getXPositions( series );
+
+	if ( positions.length === 0 ) {
+		return {
+			count: Math.max( 0, ...series.map( ( { data } ) => data.length ) ),
+			membersAt: stop =>
+				series.flatMap( s =>
+					stop < s.data.length
+						? [ { series: s, datum: s.data[ stop ] as DataPointDate, index: stop } ]
+						: []
+				),
+		};
+	}
+
+	return {
+		count: positions.length,
+		membersAt: stop => {
+			const time = positions[ stop ];
+			if ( time === undefined ) {
+				return [];
+			}
+			return series.flatMap( s => {
+				const index = s.data.findIndex( point => timeOf( point ) === time );
+				return index === -1
+					? []
+					: [ { series: s, datum: s.data[ index ] as DataPointDate, index } ];
+			} );
+		},
+	};
+};

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

@@ -2,13 +2,15 @@ import { DataContext, TooltipContext } from '@visx/xychart';
 import { useCallback, useContext, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { TooltipBox } from '../tooltip-box';
+import { atNearestDate } from './at-nearest-date';
 import { BoundedTooltip, TOOLTIP_Z_INDEX } from './bounded-tooltip';
 import type {
 	CrosshairStyle,
 	RenderTooltipGlyphProps,
 	XyChartTooltipProps,
 } from '../../../visx/types';
-import type { TooltipContextType } from '@visx/xychart';
+import type { AxisScale } from '@visx/axis';
+import type { DataContextType, TooltipContextType } from '@visx/xychart';
 import type { CSSProperties, ReactNode } from 'react';
 
 const CROSSHAIR_STROKE_WIDTH = 1.5;
@@ -314,6 +316,9 @@ export const XyChartTooltipOverlay = < Datum extends object >(
 	props: XyChartTooltipProps< Datum >
 ) => {
 	const tooltipContext = useContext( TooltipContext ) as TooltipContextType< Datum > | null;
+	const dataRegistry = (
+		useContext( DataContext ) as DataContextType< AxisScale, AxisScale, Datum >
+	 )?.dataRegistry;
 	const [ container, setContainer ] = useState< HTMLElement | null >( null );
 
 	// Children of XYChart render inside its SVG, and the box needs an HTML parent.
@@ -327,7 +332,10 @@ export const XyChartTooltipOverlay = < Datum extends object >(
 			{ tooltipContext?.tooltipOpen && (
 				<XyChartTooltipContent
 					{ ...props }
-					tooltipContext={ tooltipContext }
+					tooltipContext={ {
+						...tooltipContext,
+						tooltipData: atNearestDate( tooltipContext.tooltipData, dataRegistry ),
+					} }
 					container={ container }
 				/>
 			) }

package/src/components/tooltip/test/keyboard-stops.test.ts

@@ -0,0 +1,36 @@
+import { getKeyboardStops } from '../private/keyboard-stops';
+
+describe( 'getKeyboardStops', () => {
+	it( 'gives a stop past the last date no members, even for undated points', () => {
+		const stops = getKeyboardStops( [
+			{ label: 'Dated', data: [ { date: new Date( '2025-04-01T00:00:00Z' ), value: 1 } ] },
+			{ label: 'Undated', data: [ { label: 'Apr', value: 2 } ] },
+		] );
+
+		expect( stops.count ).toBe( 1 );
+		expect( stops.membersAt( 1 ) ).toEqual( [] );
+	} );
+
+	it( 'steps through array indexes when no point has a date', () => {
+		const first = {
+			label: 'First',
+			data: [
+				{ label: 'Jan', value: 1 },
+				{ label: 'Feb', value: 2 },
+			],
+		};
+		const second = { label: 'Second', data: [ { label: 'Jan', value: 3 } ] };
+		const stops = getKeyboardStops( [ first, second ] );
+
+		expect( stops.count ).toBe( 2 );
+		expect( stops.membersAt( 0 ).map( ( { series, index } ) => [ series.label, index ] ) ).toEqual(
+			[
+				[ 'First', 0 ],
+				[ 'Second', 0 ],
+			]
+		);
+		expect( stops.membersAt( 1 ).map( ( { series, index } ) => [ series.label, index ] ) ).toEqual(
+			[ [ 'First', 1 ] ]
+		);
+	} );
+} );

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

@@ -1,10 +1,13 @@
 import { act, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { useCallback, useRef, useState } from 'react';
+import { BarSeries, LineSeries, TooltipContext, XYChart } from '@visx/xychart';
+import { useCallback, useContext, useEffect, useRef, useState } from 'react';
 import { LineChartUnresponsive } from '../../../charts/line-chart/line-chart';
 import { GlobalChartsProvider } from '../../../providers';
 import { ChartScopeContext } from '../../../providers/chart-scope';
 import { AccessibleTooltip, XYChartTooltip, useKeyboardNavigation } from '../xy-chart-tooltip';
+import type { DataPointDate } from '../../../types';
+import type { RenderTooltipParams } from '../../../visx/types';
 import type { ReactNode } from 'react';
 
 // A real chart is the harness rather than the subject: the crosshairs render only once visx has a data context and an open tooltip. The unresponsive export is what lets the test own the scope element — `withResponsive` otherwise provides its own wrapper as the scope.
@@ -48,6 +51,46 @@ const openTooltip = async () => {
 	return screen.getByTestId( 'xy-chart-tooltip-crosshair-vertical' );
 };
 
+const individualItems = [ 'First', 'Second' ].map( label => ( {
+	label,
+	data: [ { label: 'Jan', value: 10 } ],
+	options: {},
+} ) );
+const xAccessor = ( d: DataPointDate ) => d.label;
+const yAccessor = ( d: DataPointDate ) => d.value;
+const xScale = { type: 'band' } as const;
+const yScale = { type: 'linear' } as const;
+const renderKeys = ( { tooltipData }: RenderTooltipParams< DataPointDate > ) => (
+	<div data-testid="keys">{ Object.keys( tooltipData?.datumByKey ?? {} ).join( ',' ) }</div>
+);
+
+const IndividualHarness = () => {
+	const [ selectedIndex, setSelectedIndex ] = useState( 0 );
+	const selectSecond = useCallback( () => setSelectedIndex( 1 ), [] );
+	return (
+		<GlobalChartsProvider>
+			<button onClick={ selectSecond }>next</button>
+			<XYChart width={ 300 } height={ 200 } xScale={ xScale } yScale={ yScale }>
+				{ individualItems.map( item => (
+					<BarSeries
+						key={ item.label }
+						dataKey={ item.label }
+						data={ item.data }
+						xAccessor={ xAccessor }
+						yAccessor={ yAccessor }
+					/>
+				) ) }
+				<XYChartTooltip
+					mode="individual"
+					series={ individualItems }
+					selectedIndex={ selectedIndex }
+					renderTooltip={ renderKeys }
+				/>
+			</XYChart>
+		</GlobalChartsProvider>
+	);
+};
+
 describe( 'XYChartTooltip', () => {
 	it( 'keeps AccessibleTooltip as an alias', () => {
 		expect( AccessibleTooltip ).toBe( XYChartTooltip );
@@ -129,8 +172,99 @@ describe( 'XYChartTooltip', () => {
 
 		await expect( openTooltip() ).resolves.toHaveAttribute( 'stroke', '#dbdbdb' );
 	} );
+
+	it( 'lists only the selected item in individual mode as the selection moves', async () => {
+		const user = userEvent.setup();
+
+		render( <IndividualHarness /> );
+		await expect( screen.findByTestId( 'keys' ) ).resolves.toHaveTextContent( /^First$/ );
+
+		await user.click( screen.getByRole( 'button', { name: 'next' } ) );
+
+		await expect( screen.findByTestId( 'keys' ) ).resolves.toHaveTextContent( /^Second$/ );
+	} );
+
+	// Between April and May, visx hands Views its April point and Previous period, which has no April, its May point.
+	it.each( [
+		[ 'leaves out a series with no point at the nearest date', 0, 90, 'Views=10', false ],
+		[
+			'reads every series at the nearest date, not at its own nearest point',
+			90,
+			0,
+			'Views=40,Previous period=30',
+			true,
+		],
+	] )( '%s', async ( _name, viewsDistance, previousDistance, rows, previousGlyph ) => {
+		render(
+			<PointerHarness viewsDistance={ viewsDistance } previousDistance={ previousDistance } />
+		);
+
+		await expect( screen.findByTestId( 'rows' ) ).resolves.toHaveTextContent( rows );
+		expect( screen.getByTestId( 'xy-chart-tooltip-glyph-Views' ) ).toBeInTheDocument();
+		expect( !! screen.queryByTestId( 'xy-chart-tooltip-glyph-Previous period' ) ).toBe(
+			previousGlyph
+		);
+	} );
 } );
 
+const april = { date: new Date( '2025-04-01' ), value: 10 };
+const may = { date: new Date( '2025-05-01' ), value: 40 };
+const previousMay = { date: new Date( '2025-05-01' ), value: 30 };
+const dateAccessor = ( d: DataPointDate ) => d.date;
+const timeScale = { type: 'time' } as const;
+const renderRows = ( { tooltipData }: RenderTooltipParams< DataPointDate > ) => (
+	<div data-testid="rows">
+		{ Object.entries( tooltipData?.datumByKey ?? {} )
+			.map( ( [ key, { datum } ] ) => `${ key }=${ datum.value }` )
+			.join( ',' ) }
+	</div>
+);
+
+type PointerDistances = { viewsDistance: number; previousDistance: number };
+
+const ReportPointer = ( { viewsDistance, previousDistance }: PointerDistances ) => {
+	const tooltipContext = useContext( TooltipContext );
+	useEffect( () => {
+		tooltipContext?.showTooltip( {
+			key: 'Views',
+			datum: april,
+			index: 0,
+			distanceX: viewsDistance,
+			distanceY: 0,
+		} );
+		tooltipContext?.showTooltip( {
+			key: 'Previous period',
+			datum: previousMay,
+			index: 0,
+			distanceX: previousDistance,
+			distanceY: 0,
+		} );
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [] );
+	return null;
+};
+
+const PointerHarness = ( distances: PointerDistances ) => (
+	<GlobalChartsProvider>
+		<XYChart width={ 300 } height={ 200 } xScale={ timeScale } yScale={ yScale }>
+			<LineSeries
+				dataKey="Views"
+				data={ [ april, may ] }
+				xAccessor={ dateAccessor }
+				yAccessor={ yAccessor }
+			/>
+			<LineSeries
+				dataKey="Previous period"
+				data={ [ previousMay ] }
+				xAccessor={ dateAccessor }
+				yAccessor={ yAccessor }
+			/>
+			<ReportPointer { ...distances } />
+			<XYChartTooltip renderTooltip={ renderRows } showSeriesGlyphs />
+		</XYChart>
+	</GlobalChartsProvider>
+);
+
 // Mirrors the charts' markup: the focusable chart container wraps the element `chartRef` points at.
 const NavigationHarness = ( {
 	totalPoints,

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

@@ -6,6 +6,7 @@ import { useGlobalChartsContext } from '../../providers/chart-context/hooks/use-
 import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
 import { useChartScopeElement, useStandaloneScopeClass } from '../../providers/chart-scope';
 import { resolveCssVariable } from '../../utils';
+import { getKeyboardStops } from './private/keyboard-stops';
 import { XyChartTooltipOverlay } from './private/xy-chart-tooltip-overlay';
 import type { SeriesData, DataPointDate } from '../../types';
 import type { RenderTooltipParams, XyChartTooltipProps } from '../../visx/types';
@@ -34,7 +35,7 @@ interface XYChartTooltipProps extends Omit<
 	 */
 	tooltipData?: FlattenedTooltipData[];
 	/**
-	 * For line charts: series data to show all series at selected data point
+	 * For line charts: series data to show every series at the selected date
 	 * When provided, shows all series instead of individual tooltips
 	 */
 	series?: SeriesData[];
@@ -99,6 +100,8 @@ export const XYChartTooltip: React.FC< XYChartTooltipProps > = ( {
 		return flattened;
 	}, [ series, mode ] );
 
+	const stops = useMemo( () => getKeyboardStops( series ), [ series ] );
+
 	// Tracks whether this effect opened a tooltip, so it only closes its own.
 	const hasKeyboardSelection = useRef( false );
 
@@ -154,22 +157,15 @@ export const XYChartTooltip: React.FC< XYChartTooltipProps > = ( {
 		if ( mode === 'group' ) {
 			// visx merges each shown datum into the previous tooltip data, so start empty or a series dropped from `series` keeps its row.
 			closeTooltipNow();
-			series.forEach( ( s, index ) => {
-				if ( selectedIndex < s.data.length ) {
-					const datum = s.data[ selectedIndex ];
-
-					tooltipContext?.showTooltip( {
-						datum,
-						key: s.label,
-						index,
-					} );
-				}
+			stops.membersAt( selectedIndex ).forEach( ( { series: member, datum, index } ) => {
+				tooltipContext?.showTooltip( { datum, key: member.label, index } );
 			} );
 		} else if ( mode === 'individual' ) {
 			// Show individual tooltips for each datapoint from each series.
 			if ( selectedIndex < tooltipData.length ) {
 				const tooltipItem = tooltipData[ selectedIndex ];
 
+				tooltipContext?.updateTooltip( state => ( { ...state, tooltipData: undefined } ) );
 				tooltipContext?.showTooltip( {
 					datum: tooltipItem.datum,
 					key: tooltipItem.seriesLabel,
@@ -180,7 +176,7 @@ export const XYChartTooltip: React.FC< XYChartTooltipProps > = ( {
 
 		// Don't include tooltipContext in the dependency array to avoid loop.
 		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [ selectedIndex, tooltipData, series ] );
+	}, [ selectedIndex, tooltipData, stops ] );
 
 	// Create a focusable renderTooltip that includes accessibility features
 	const focusableRenderTooltip = useMemo( () => {

package/src/index.ts

@@ -124,6 +124,8 @@ export type {
 export type {
 	ConversionFunnelChartProps,
 	FunnelStep,
+	FunnelTooltipContent,
+	FunnelTooltipRow,
 	StepLabelRenderProps,
 	StepRateRenderProps,
 	MainMetricRenderProps,

package/src/types.ts

@@ -214,13 +214,14 @@ type LeaderboardEntryFields = {
 	previousValue?: number;
 
 	/**
-	 * Width of current bar, as % of the current value
+	 * Width of current bar, as % of the largest absolute value across rows. A negative share
+	 * extends the bar from a shared zero point toward the inline start, for every row.
 	 */
 	currentShare: number;
 
 	/**
-	 * Width of previous bar, as % of the current value. Omit when this row has
-	 * no matching comparison-period value.
+	 * Width of previous bar, as % of the largest absolute value across rows. Omit when this
+	 * row has no matching comparison-period value.
 	 */
 	previousShare?: number;