@automattic/charts 4.12.0 → 4.14.0

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

@@ -81,6 +81,22 @@ describe( 'LeaderboardChart', () => {
 		expect( screen.getByText( '-8%' ) ).toBeInTheDocument();
 	} );
 
+	it( 'derives the delta of entries that pass only values', () => {
+		render(
+			<LeaderboardChart
+				data={ [
+					{ id: 'up', label: 'Up', currentValue: 100, previousValue: 80 },
+					{ id: 'down', label: 'Down', currentValue: 50, previousValue: 100 },
+				] }
+				withComparison={ true }
+				deltaFormatter={ testDeltaFormatter }
+			/>
+		);
+
+		expect( screen.getByText( '25delta' ) ).toBeInTheDocument();
+		expect( screen.getByText( '-50delta' ) ).toBeInTheDocument();
+	} );
+
 	it( 'shows a placeholder when a row has no previous value', () => {
 		render(
 			<LeaderboardChart
@@ -152,6 +168,49 @@ describe( 'LeaderboardChart', () => {
 		expect( container.querySelectorAll( '.bar' ) ).toHaveLength( 2 );
 	} );
 
+	it.each( [
+		[ 'a current share is negative', { currentShare: -40 }, true, 2 ],
+		[ 'a comparison share is negative', { previousShare: -40 }, true, 2 ],
+		[ 'only a hidden comparison share is negative', { previousShare: -40 }, false, 0 ],
+		[
+			'only a share without a comparison value is negative',
+			{ previousShare: -40, previousValue: undefined },
+			true,
+			0,
+		],
+		[ 'every share is positive', {}, true, 0 ],
+	] )( 'diverges the bars from zero when %s', ( _, override, withComparison, expected ) => {
+		const data = [ { ...mockData[ 0 ], ...override }, mockData[ 1 ] ];
+		render( <LeaderboardChart data={ data } withComparison={ withComparison } /> );
+
+		expect( screen.queryAllByTestId( 'leaderboard-chart-diverging-row' ) ).toHaveLength( expected );
+	} );
+
+	it( 'keeps every bar on one side when negative bars clamp', () => {
+		const data = [
+			{ ...mockData[ 0 ], currentShare: undefined, currentValue: -40 },
+			mockData[ 1 ],
+		];
+		render( <LeaderboardChart data={ data } withComparison negativeBars="clamp" /> );
+
+		expect( screen.queryAllByTestId( 'leaderboard-chart-diverging-row' ) ).toHaveLength( 0 );
+	} );
+
+	it.each( [
+		[ 'comparison bars draw', false, /^calc\(50%/ ],
+		[ 'the overlay label hides comparison bars', true, /^calc\(100%/ ],
+	] )( 'sizes the current bar against the max when %s', ( _, withOverlayLabel, expected ) => {
+		const data = [
+			{ id: 'a', label: 'A', currentValue: 50, previousValue: 100 },
+			{ id: 'b', label: 'B', currentValue: 25, previousValue: 10 },
+		] as LeaderboardEntry[];
+		render(
+			<LeaderboardChart data={ data } withComparison withOverlayLabel={ withOverlayLabel } />
+		);
+
+		expect( screen.getAllByTestId( 'leaderboard-chart-bar' )[ 0 ].style.width ).toMatch( expected );
+	} );
+
 	it( 'shows custom label when provided', () => {
 		render(
 			<LeaderboardChart
@@ -748,6 +807,35 @@ describe( 'LeaderboardChart', () => {
 	describe( 'grid gaps', () => {
 		// eslint-disable-next-line testing-library/no-node-access -- The grid is rendered by `Grid` from @wordpress/components, which takes no test id.
 		const grid = () => document.querySelector< HTMLElement >( '[data-leaderboard-grid]' );
+		const templateColumns = () =>
+			grid().style.getPropertyValue( '--wp-components-grid-template-columns' );
+
+		it( 'lays the rows out without a delta track when not comparing', () => {
+			render( <LeaderboardChart data={ mockData } withComparison={ false } /> );
+
+			expect( templateColumns() ).toBe( 'minmax(0, 1fr) auto' );
+		} );
+
+		it.each( [ [ 'Previous period' ], [ 'Current period' ] ] )(
+			'adds a delta track when comparing and drops it while "%s" is hidden',
+			async legendItem => {
+				const user = userEvent.setup();
+				render(
+					<LeaderboardChart
+						data={ mockData }
+						withComparison={ true }
+						showLegend={ true }
+						legend={ { interactive: true } }
+					/>
+				);
+
+				expect( templateColumns() ).toBe( 'minmax(0, 1fr) auto auto' );
+
+				await user.click( screen.getByRole( 'button', { name: new RegExp( legendItem ) } ) );
+
+				expect( templateColumns() ).toBe( 'minmax(0, 1fr) auto' );
+			}
+		);
 
 		it( 'hands the catalog role to the grid', () => {
 			render( <LeaderboardChart data={ mockData } /> );

package/src/charts/leaderboard-chart/test/resolve-leaderboard-entries.test.ts

@@ -0,0 +1,146 @@
+import { resolveLeaderboardEntries } from '../private/resolve-leaderboard-entries';
+import type { LeaderboardEntry } from '../../../types';
+
+type EntryInput = Partial< LeaderboardEntry > & { currentValue: number };
+
+const toEntries = ( rows: EntryInput[] ) =>
+	rows.map( ( row, index ) => ( {
+		id: `row-${ index }`,
+		label: `Row ${ index }`,
+		...row,
+	} ) ) as LeaderboardEntry[];
+
+describe( 'resolveLeaderboardEntries', () => {
+	const comparisonRows = [
+		{ currentValue: 50, previousValue: 100 },
+		{ currentValue: 25, previousValue: 40 },
+	];
+
+	it( 'derives both shares and delta against one max across both periods', () => {
+		const result = resolveLeaderboardEntries( toEntries( comparisonRows ), {
+			includePrevious: true,
+		} );
+
+		expect(
+			result.map( ( { currentShare, previousShare, delta } ) => ( {
+				currentShare,
+				previousShare,
+				delta,
+			} ) )
+		).toEqual( [
+			{ currentShare: 50, previousShare: 100, delta: -50 },
+			{ currentShare: 25, previousShare: 40, delta: -37.5 },
+		] );
+	} );
+
+	it( 'lets a negative previous value set the max', () => {
+		const [ entry ] = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 10, previousValue: -40 } ] ),
+			{ includePrevious: true }
+		);
+
+		expect( entry ).toMatchObject( { currentShare: 25, previousShare: -100 } );
+	} );
+
+	it( 'ignores previous values for the max when comparison bars are not drawn', () => {
+		const result = resolveLeaderboardEntries( toEntries( comparisonRows ), {
+			includePrevious: false,
+		} );
+
+		expect( result.map( ( { currentShare } ) => currentShare ) ).toEqual( [ 100, 50 ] );
+	} );
+
+	it( 'keeps passed fields and derives the rest', () => {
+		const [ entry ] = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 50, currentShare: 10, previousValue: 100, delta: 7 } ] ),
+			{ includePrevious: true }
+		);
+
+		expect( entry ).toMatchObject( { currentShare: 10, delta: 7, previousShare: 100 } );
+	} );
+
+	it( 'derives a missing share from the max over every row, passed or not', () => {
+		const result = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 10, currentShare: 100 }, { currentValue: 20 } ] ),
+			{ includePrevious: false }
+		);
+
+		expect( result.map( ( { currentShare } ) => currentShare ) ).toEqual( [ 100, 100 ] );
+	} );
+
+	it( 'keeps the sign of negative values', () => {
+		const result = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: -30 }, { currentValue: 60 } ] ),
+			{ includePrevious: false }
+		);
+
+		expect( result.map( ( { currentShare } ) => currentShare ) ).toEqual( [ -50, 100 ] );
+	} );
+
+	it( 'clamps negative shares to 0 and sizes the rest against the largest positive value', () => {
+		const result = resolveLeaderboardEntries(
+			toEntries( [
+				{ currentValue: -90, previousValue: 30 },
+				{ currentValue: 60, previousValue: -10, previousShare: -20 },
+			] ),
+			{ includePrevious: true, clampNegative: true }
+		);
+
+		expect(
+			result.map( ( { currentShare, previousShare, delta } ) => ( {
+				currentShare,
+				previousShare,
+				delta,
+			} ) )
+		).toEqual( [
+			{ currentShare: 0, previousShare: 50, delta: -400 },
+			{ currentShare: 100, previousShare: 0, delta: 700 },
+		] );
+	} );
+
+	it.each( [
+		{ currentValue: 5, previousValue: -10, expected: 150 },
+		{ currentValue: 0, previousValue: 0, expected: 0 },
+		{ currentValue: 5, previousValue: 0, expected: undefined },
+		{ currentValue: 5, previousValue: undefined, expected: undefined },
+	] )(
+		'derives delta $expected for current $currentValue and previous $previousValue',
+		( { currentValue, previousValue, expected } ) => {
+			const [ entry ] = resolveLeaderboardEntries(
+				toEntries( [ { currentValue, previousValue } ] ),
+				{ includePrevious: true }
+			);
+
+			expect( entry.delta ).toBe( expected );
+		}
+	);
+
+	it( 'sizes rows without a previous value against the shared max', () => {
+		const result = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 50, previousValue: 100 }, { currentValue: 25 } ] ),
+			{ includePrevious: true }
+		);
+
+		expect( result.map( ( { currentShare } ) => currentShare ) ).toEqual( [ 50, 25 ] );
+		expect( result[ 1 ] ).not.toHaveProperty( 'previousShare' );
+	} );
+
+	it( 'gives shares of 0 when every value is 0', () => {
+		const [ entry ] = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 0, previousValue: 0 } ] ),
+			{ includePrevious: true }
+		);
+
+		expect( entry ).toMatchObject( { currentShare: 0, previousShare: 0, delta: 0 } );
+	} );
+
+	it( 'leaves other fields untouched', () => {
+		const onClick = jest.fn();
+		const [ entry ] = resolveLeaderboardEntries(
+			toEntries( [ { id: 'a', label: 'A', currentValue: 1, onClick } ] ),
+			{ includePrevious: false }
+		);
+
+		expect( entry ).toMatchObject( { id: 'a', label: 'A', onClick } );
+	} );
+} );

package/src/charts/leaderboard-chart/types.ts

@@ -30,6 +30,12 @@ export interface LeaderboardChartProps extends Pick<
 	 */
 	withOverlayLabel?: boolean;
 
+	/**
+	 * How a negative value draws: `diverge` puts every row on a shared zero point, `clamp` draws it as an empty bar.
+	 * @default 'diverge'
+	 */
+	negativeBars?: 'diverge' | 'clamp';
+
 	/**
 	 * Primary color for current period bars
 	 */

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

@@ -16,6 +16,7 @@ import {
 } from 'react';
 import { Legend, useChartLegendItems } from '../../components/legend';
 import { XYChartTooltip, useKeyboardNavigation } from '../../components/tooltip';
+import { getKeyboardStops } from '../../components/tooltip/private/keyboard-stops';
 import {
 	useXYChartTheme,
 	useChartDataTransform,
@@ -387,17 +388,18 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 			return min < max ? [ min, max ] : undefined;
 		}, [ rescaleYOnVisibilityChange, dataSorted, isSeriesVisible, options?.yScale ] );
 
-		// Keyboard navigation steps through x positions, and the grouped tooltip reads every
-		// visible series at that position; the first visible series with a point there names it.
+		const stops = useMemo( () => getKeyboardStops( visibleSeries ), [ visibleSeries ] );
+
+		// The grouped tooltip reads every visible series at a stop; the first visible series with a point there names it.
 		const activateSelectedPoint = useCallback(
-			( index: number ) => {
-				const series = visibleSeries.find( candidate => candidate.data[ index ] );
+			( stop: number ) => {
+				const match = stops.membersAt( stop )[ 0 ];
 
-				if ( series ) {
-					onDatumActivate?.( { datum: series.data[ index ], index, key: series.label } );
+				if ( match ) {
+					onDatumActivate?.( { datum: match.datum, index: match.index, key: match.series.label } );
 				}
 			},
-			[ visibleSeries, onDatumActivate ]
+			[ stops, onDatumActivate ]
 		);
 
 		const { tooltipRef, onChartFocus, onChartBlur, onChartKeyDown } = useKeyboardNavigation( {
@@ -406,7 +408,7 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 			isNavigating,
 			setIsNavigating,
 			chartRef,
-			totalPoints: Math.max( 0, ...visibleSeries.map( series => series.data.length ) ),
+			totalPoints: stops.count,
 			visibleSeriesKey,
 			onActivate: activateSelectedPoint,
 			preventTooltipScroll: tooltipPlacement === 'below-axis',

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/legend/private/base-legend.tsx

@@ -217,24 +217,27 @@ export const BaseLegend: ForwardRefExoticComponent<
 
 		// Create event handlers to avoid inline arrow functions
 		const createClickHandler = useCallback(
-			( seriesLabels: string[], itemInteractive: boolean ) => {
+			( seriesLabels: string[], itemInteractive: boolean, onToggle?: () => void ) => {
 				if ( ! itemInteractive ) {
 					return undefined;
 				}
-				return () => handleLegendClick( seriesLabels );
+				return onToggle ? () => onToggle() : () => handleLegendClick( seriesLabels );
 			},
 			[ handleLegendClick ]
 		);
 
 		const createKeyDownHandler = useCallback(
-			( seriesLabels: string[], itemInteractive: boolean ) => {
+			( seriesLabels: string[], itemInteractive: boolean, onToggle?: () => void ) => {
 				if ( ! itemInteractive ) {
 					return undefined;
 				}
+				const toggle = onToggle ?? ( () => handleLegendClick( seriesLabels ) );
 				return ( event: KeyboardEvent ) => {
 					if ( event.key === 'Enter' || event.key === ' ' ) {
 						event.preventDefault();
-						handleLegendClick( seriesLabels );
+						if ( ! event.repeat ) {
+							toggle();
+						}
 					}
 				};
 			},
@@ -278,11 +281,13 @@ export const BaseLegend: ForwardRefExoticComponent<
 							const seriesLabels = matchedItem?.seriesLabels?.length
 								? matchedItem.seriesLabels
 								: [ label.text ];
-							const visible =
-								matchedItem?.interactive === false || isSeriesVisible( seriesLabels[ 0 ] );
 							const itemInteractive = interactive && matchedItem?.interactive !== false;
-							const handleClick = createClickHandler( seriesLabels, itemInteractive );
-							const handleKeyDown = createKeyDownHandler( seriesLabels, itemInteractive );
+							const onToggle = itemInteractive ? matchedItem?.onToggle : undefined;
+							const visible = matchedItem?.onToggle
+								? matchedItem.pressed
+								: matchedItem?.interactive === false || isSeriesVisible( seriesLabels[ 0 ] );
+							const handleClick = createClickHandler( seriesLabels, itemInteractive, onToggle );
+							const handleKeyDown = createKeyDownHandler( seriesLabels, itemInteractive, onToggle );
 
 							return (
 								<LegendItem

package/src/components/legend/test/legend.test.tsx

@@ -900,6 +900,131 @@ describe( 'BaseLegend', () => {
 		} );
 	} );
 
+	describe( 'Controlled items', () => {
+		const VisibilityProbe = () => {
+			const { isSeriesVisible } = useGlobalChartsContext();
+			return (
+				<output data-testid="views-visible">
+					{ String( isSeriesVisible( 'test-chart', 'Views' ) ) }
+				</output>
+			);
+		};
+
+		it.each( [ false, true ] )( 'takes the pressed state from the item (%s)', pressed => {
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend
+						items={ [ { label: 'Previous period', color: '#000', pressed, onToggle: jest.fn() } ] }
+						interactive
+						chartId="test-chart"
+					/>
+				</GlobalChartsProvider>
+			);
+
+			expect( screen.getByRole( 'button', { name: /Previous period/ } ) ).toHaveAttribute(
+				'aria-pressed',
+				String( pressed )
+			);
+		} );
+
+		it.each( [ 'click', 'Enter', ' ' ] )(
+			'calls onToggle on %s and leaves series visibility alone',
+			async interaction => {
+				const user = userEvent.setup();
+				const onToggle = jest.fn();
+				render(
+					<GlobalChartsProvider>
+						<BaseLegend
+							items={ [
+								{
+									label: 'Previous period',
+									color: '#000',
+									seriesLabels: [ 'Views' ],
+									pressed: false,
+									onToggle,
+								},
+							] }
+							interactive
+							chartId="test-chart"
+						/>
+						<VisibilityProbe />
+					</GlobalChartsProvider>
+				);
+
+				const button = screen.getByRole( 'button', { name: /Previous period/ } );
+				if ( interaction === 'click' ) {
+					await user.click( button );
+				} else {
+					button.focus();
+					await user.keyboard( interaction === ' ' ? ' ' : '{Enter}' );
+				}
+
+				expect( onToggle ).toHaveBeenCalledTimes( 1 );
+				expect( onToggle ).toHaveBeenCalledWith();
+				expect( screen.getByTestId( 'views-visible' ) ).toHaveTextContent( 'true' );
+			}
+		);
+
+		it( 'ignores key repeats while Enter is held', async () => {
+			const user = userEvent.setup();
+			const onToggle = jest.fn();
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend
+						items={ [ { label: 'Previous period', color: '#000', pressed: false, onToggle } ] }
+						interactive
+						chartId="test-chart"
+					/>
+				</GlobalChartsProvider>
+			);
+
+			screen.getByRole( 'button', { name: /Previous period/ } ).focus();
+			await user.keyboard( '{Enter>3/}' );
+
+			expect( onToggle ).toHaveBeenCalledTimes( 1 );
+		} );
+
+		const renderStaticControlledItem = ( pressed: boolean ) => {
+			const onToggle = jest.fn();
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend
+						items={ [
+							{
+								label: 'Previous period',
+								color: '#000',
+								seriesLabels: [ 'Views' ],
+								pressed,
+								onToggle,
+							},
+						] }
+						interactive={ false }
+						chartId="test-chart"
+					/>
+				</GlobalChartsProvider>
+			);
+			return { item: screen.getByTestId( 'legend-item' ), onToggle };
+		};
+
+		it( 'stays static in a legend that is not interactive', async () => {
+			const user = userEvent.setup();
+			const { item, onToggle } = renderStaticControlledItem( true );
+
+			expect( screen.queryByRole( 'button' ) ).not.toBeInTheDocument();
+			expect( item ).not.toHaveClass( 'legend-item--inactive' );
+			expect( item ).not.toHaveAttribute( 'aria-label' );
+			await user.click( item );
+			expect( onToggle ).not.toHaveBeenCalled();
+		} );
+
+		it( 'dims an item that is not pressed in a legend that is not interactive', () => {
+			const { item } = renderStaticControlledItem( false );
+
+			expect( item ).toHaveClass( 'legend-item--inactive' );
+			expect( item ).toHaveAttribute( 'aria-label', 'Previous period: hidden' );
+		} );
+	} );
+
 	describe( 'Non-interactive legend reflects hidden state', () => {
 		const HiddenSeriesHarness = ( { interactive }: { interactive: boolean } ) => {
 			const context = useGlobalChartsContext();

package/src/components/legend/types.ts

@@ -65,4 +65,12 @@ export type BaseLegendItem = {
 	interactive?: boolean;
 	/** Label of the series this static item describes; the item is left out while it is hidden. */
 	describesSeries?: string;
-};
+} & (
+	| {
+			/** Pressed state of the toggle. */
+			pressed: boolean;
+			/** Makes an interactive legend item a toggle the consumer controls, instead of a series toggle. */
+			onToggle: () => void;
+	  }
+	| { pressed?: never; onToggle?: never }
+);

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 };
+};