@automattic/charts 4.1.1 → 4.3.0

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

@@ -1,5 +1,5 @@
 import type { BaseChartProps } from '../../types';
-import type { ReactNode } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 
 /** A single heatmap cell. `value: null` marks an empty cell. */
 export type HeatmapCell = {
@@ -36,19 +36,46 @@ export type HeatmapColumn = {
 	summary?: boolean;
 };
 
+/** A run of consecutive columns sharing one label beneath the grid. */
+export type HeatmapColumnGroup = {
+	label: string;
+	/** Columns covered; a positive integer. */
+	span: number;
+};
+
 export type HeatmapTooltipData = {
 	value: number | null;
 	rowLabel?: string;
 	columnLabel?: string;
+	/** Label of the column group the cell falls in, if any. */
+	groupLabel?: string;
 	cellLabel?: string;
 	row: number;
 	column: number;
 };
 
-export interface HeatmapChartProps
-	extends Omit< BaseChartProps< HeatmapColumn[] >, 'showLegend' | 'legend' | 'gridVisibility' > {
+export interface HeatmapChartProps extends Omit<
+	BaseChartProps< HeatmapColumn[] >,
+	'showLegend' | 'legend' | 'gridVisibility'
+> {
 	/** y-axis labels by row index. Empty entries render blank. */
 	rowLabels?: string[];
+	/**
+	 * Consecutive runs of columns sharing one label beneath the grid, set one
+	 * group gap apart. Runs from the first column; columns past the last group
+	 * stay ungrouped. Ignored, with a warning, when a span is not a positive
+	 * integer or the spans reach past the last column.
+	 */
+	columnGroups?: HeatmapColumnGroup[];
+	/**
+	 * How the arrow keys move the selection. `grid` steps across the whole grid.
+	 * `calendar` reads each column group as a page: Left/Right by one cell (wrapping
+	 * to the next row, then the next group), Up/Down by one row into the neighboring
+	 * group past the edge, Page Up/Down by one group. Default `grid`.
+	 */
+	keyboardNavigation?: 'grid' | 'calendar';
+	/** Accessible name of the grid. Defaults to a localized "Heatmap chart". */
+	ariaLabel?: string;
 	/** Compact mode: hide in-cell values, tighten gap, thin axis labels. Default false. */
 	compact?: boolean;
 	/** Render the numeric value inside each cell. Default `! compact`. */
@@ -80,6 +107,14 @@ export interface HeatmapChartProps
 	 */
 	primaryColor?: string;
 	renderTooltip?: ( data: HeatmapTooltipData ) => ReactNode;
+	/**
+	 * The tooltip box: `light` is the plain white box, `dark` the package's
+	 * tooltip surface, themed through `--a8c-charts-color-tooltip-surface`.
+	 * Default `light`.
+	 */
+	tooltipVariant?: 'light' | 'dark';
+	/** Inline styles merged onto the tooltip box, over the variant's own. */
+	tooltipStyle?: CSSProperties;
 	children?: ReactNode;
 }
 
@@ -111,3 +146,24 @@ export type CalendarHeatmapOptions = {
 	 */
 	timeZone?: string;
 };
+
+export type MonthCalendarHeatmapRange = {
+	/** First measured day, `yyyy-MM-dd`. */
+	start: string;
+	/** Last measured day, `yyyy-MM-dd`, inclusive. */
+	end: string;
+};
+
+export type MonthCalendarHeatmapOptions = {
+	/** 0 = Sunday, 1 = Monday. Default 1. */
+	weekStartsOn?: 0 | 1;
+	/** BCP-47 tag the month and day labels are written in. Defaults to the runtime's locale. */
+	locale?: string;
+};
+
+export type MonthCalendarHeatmapResult = {
+	/** For `HeatmapChart`'s `data`: 7 columns per month, 6 cells each. */
+	data: HeatmapColumn[];
+	/** For `HeatmapChart`'s `columnGroups`: one per month, in order. */
+	columnGroups: HeatmapColumnGroup[];
+};

package/src/charts/heatmap-chart/use-month-calendar-heatmap-data.ts

@@ -0,0 +1,34 @@
+import { useMemo } from 'react';
+import { useChartFormatting } from '../../providers';
+import { buildMonthCalendarHeatmapData } from './build-month-calendar-data';
+import type {
+	MonthCalendarHeatmapOptions,
+	MonthCalendarHeatmapRange,
+	MonthCalendarHeatmapResult,
+} from './types';
+
+/**
+ * `buildMonthCalendarHeatmapData` with the locale taken from `GlobalChartsProvider`
+ * where the caller names none.
+ *
+ * @param valueByDay - Value per `yyyy-MM-dd`. Held by reference, so a caller that rebuilds it each render defeats the memo.
+ * @param range      - As for `buildMonthCalendarHeatmapData`.
+ * @param options    - As for `buildMonthCalendarHeatmapData`; `locale` wins over the provider.
+ * @return Columns and groups for `HeatmapChart`.
+ */
+export const useMonthCalendarHeatmapData = (
+	valueByDay: Record< string, number | null >,
+	range: MonthCalendarHeatmapRange,
+	options: MonthCalendarHeatmapOptions = {}
+): MonthCalendarHeatmapResult => {
+	const formatting = useChartFormatting();
+	const locale = options.locale ?? formatting.locale;
+	const { weekStartsOn } = options;
+	const { start, end } = range;
+
+	// Spread into primitives: the option and range objects are rebuilt on each render.
+	return useMemo(
+		() => buildMonthCalendarHeatmapData( valueByDay, { start, end }, { locale, weekStartsOn } ),
+		[ valueByDay, start, end, locale, weekStartsOn ]
+	);
+};

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

@@ -1,20 +1,19 @@
 import { type ReactNode } from 'react';
 import { BaseChartProps, LeaderboardEntry } from '../../types';
 
-export interface LeaderboardChartProps
-	extends Pick<
-		BaseChartProps< LeaderboardEntry >,
-		| 'className'
-		| 'data'
-		| 'showLegend'
-		| 'legend'
-		| 'chartId'
-		| 'width'
-		| 'height'
-		| 'size'
-		| 'gap'
-		| 'animation'
-	> {
+export interface LeaderboardChartProps extends Pick<
+	BaseChartProps< LeaderboardEntry >,
+	| 'className'
+	| 'data'
+	| 'showLegend'
+	| 'legend'
+	| 'chartId'
+	| 'width'
+	| 'height'
+	| 'size'
+	| 'gap'
+	| 'animation'
+> {
 	/**
 	 * Whether to show comparison data
 	 */

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

@@ -1,5 +1,6 @@
-import { formatNumberCompact, formatNumber } from '@automattic/number-formatters';
+import { formatNumberCompact } from '@automattic/number-formatters';
 import { LinearGradient } from '@visx/gradient';
+import { scaleCanBeZeroed } from '@visx/scale';
 import { XYChart, AreaSeries, Grid, Axis, DataContext } from '@visx/xychart';
 import { __ } from '@wordpress/i18n';
 import { Stack } from '@wordpress/ui';
@@ -37,14 +38,21 @@ import { useChartChildren } from '../private/chart-composition';
 import { ChartInstanceContext, type ChartInstanceRef } from '../private/chart-instance-context';
 import { ChartLayout } from '../private/chart-layout';
 import { DefaultGlyph } from '../private/default-glyph';
+import { formatReading, isInvalidReading, isReading } from '../private/readings';
 import { getAllHiddenMessage, SvgEmptyState } from '../private/svg-empty-state';
 import { getCurveType } from '../private/time-axis';
 import { buildTimeAxisOptions } from '../private/time-axis-options';
+import { hasOnlyWholeNumbers, WholeNumberTicks } from '../private/whole-number-ticks';
 import { withResponsive } from '../private/with-responsive';
 import { useXZoom, ZoomResetButton, ZoomSelectionRect, ZoomClip } from '../private/x-zoom';
 import plotStyles from '../private/xy-plot/xy-plot.module.scss';
 import styles from './line-chart.module.scss';
-import { LineChartAnnotation, LineChartAnnotationsOverlay, LineChartGlyph } from './private';
+import {
+	LineChartAnnotation,
+	LineChartAnnotationsOverlay,
+	LineChartGlyph,
+	NearestPointerEvents,
+} from './private';
 import type { RenderLineGlyphProps, LineChartProps, TooltipDatum } from './types';
 import type {
 	BucketInfo,
@@ -123,9 +131,14 @@ export const renderDefaultTooltip = (
 	const tooltipPoints: TooltipDatum[] = Object.entries( tooltipData?.datumByKey || {} )
 		.map( ( [ key, { datum } ] ) => ( {
 			key,
-			value: datum.value as number,
+			value: datum.value ?? null,
 		} ) )
-		.sort( ( a, b ) => b.value - a.value );
+		.sort( ( a, b ) => {
+			if ( a.value === null && b.value === null ) return 0;
+			if ( a.value === null ) return 1;
+			if ( b.value === null ) return -1;
+			return b.value - a.value;
+		} );
 
 	return (
 		<div
@@ -149,7 +162,7 @@ export const renderDefaultTooltip = (
 				>
 					<span className={ styles[ 'line-chart__tooltip-label' ] }>{ point.key }:</span>
 					<span className={ styles[ 'line-chart__tooltip-value' ] }>
-						{ formatNumber( point.value ) }
+						{ formatReading( point.value ) }
 					</span>
 				</Stack>
 			) ) }
@@ -158,22 +171,42 @@ export const renderDefaultTooltip = (
 };
 
 const validateData = ( data: SeriesData[] ) => {
-	if ( ! data?.length ) return 'No data available';
+	if ( ! data?.length ) return __( 'No data available', 'jetpack-charts' );
 
 	const hasInvalidData = data.some( series =>
 		series.data.some(
 			( point: DataPointDate | DataPoint ) =>
-				isNaN( point.value as number ) ||
-				point.value === null ||
-				point.value === undefined ||
+				isInvalidReading( point.value, { allowMissing: true } ) ||
 				( 'date' in point && point.date && isNaN( point.date.getTime() ) )
 		)
 	);
 
-	if ( hasInvalidData ) return 'Invalid data';
+	if ( hasInvalidData ) return __( 'Invalid data', 'jetpack-charts' );
 	return null;
 };
 
+// visx derives the y domain from the readings, which fails when they have no range: none at all
+// leaves no domain, and a flat line collapses it to one value that d3 draws mid-height.
+const getFallbackYDomain = (
+	readingExtent: [ number, number ] | undefined,
+	isLogScale: boolean
+): [ number, number ] | undefined => {
+	// A log scale cannot reach zero, so its empty axis starts at 1.
+	const emptyDomain: [ number, number ] = isLogScale ? [ 1, 10 ] : [ 0, 1 ];
+
+	if ( ! readingExtent ) {
+		return emptyDomain;
+	}
+
+	const [ min, max ] = readingExtent;
+
+	if ( min !== max || isLogScale ) {
+		return undefined;
+	}
+
+	return min === 0 ? emptyDomain : [ Math.min( 0, min ), Math.max( 0, max ) ];
+};
+
 // Inner component to access DataContext and provide scale data to ref
 const LineChartScalesRef: FC< {
 	chartRef?: Ref< ChartInstanceRef >;
@@ -249,6 +282,7 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 	) => {
 		const legendInteractive = legend.interactive ?? false;
 		const legendCollapseGroups = legend.collapseGroups ?? false;
+		const legendComparisonItem = legend.comparisonItem ?? false;
 		const legendShape = legend.shape ?? 'line';
 		const legendPosition = legend.position ?? 'bottom';
 
@@ -317,28 +351,42 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 			return seriesWithVisibility.every( ( { isVisible } ) => ! isVisible );
 		}, [ seriesWithVisibility ] );
 
-		// When series visibility changes — via the interactive legend or programmatically —
-		// and rescaling is opted out, pin the value axis to the full data range so it stays
-		// put instead of visx rescaling the domain to whatever is currently visible and
-		// making the axis jump. Default is to rescale, matching the pre-existing behaviour
-		// and AreaChart's `rescaleYOnVisibilityChange`.
-		const stableYDomain = useMemo< [ number, number ] | undefined >( () => {
-			if ( rescaleYOnVisibilityChange ) {
+		// The value extent of the series visx will scale to. Pinning the axis
+		// (`rescaleYOnVisibilityChange: false`) measures hidden series too, so hiding
+		// one leaves the axis where it is.
+		const yDomain = useMemo< [ number, number ] | undefined >( () => {
+			// A log scale cannot hold zero; visx ignores the flag there, and so does this.
+			const includeZero =
+				options?.yScale?.zero === true &&
+				scaleCanBeZeroed( { type: options.yScale.type ?? 'linear' } );
+			if ( rescaleYOnVisibilityChange && ! includeZero ) {
 				return undefined;
 			}
 			let min = Infinity;
 			let max = -Infinity;
 			for ( const series of dataSorted ) {
+				if ( rescaleYOnVisibilityChange && ! isSeriesVisible( series.label ) ) {
+					continue;
+				}
 				for ( const point of series.data ?? [] ) {
 					const value = point?.value;
-					if ( typeof value === 'number' && Number.isFinite( value ) ) {
+					if ( isReading( value ) ) {
 						min = Math.min( min, value );
 						max = Math.max( max, value );
 					}
 				}
 			}
+			// Zero goes into the domain rather than through the scale's `zero` flag: visx
+			// applies `nice` before `zero`, which leaves the top of a zeroed axis unrounded.
+			if ( includeZero ) {
+				if ( min === Infinity ) {
+					return undefined;
+				}
+				// A series that is all zeros has no span, and d3 draws a spanless domain at mid-height.
+				return max === 0 && min === 0 ? [ 0, 1 ] : [ Math.min( 0, min ), Math.max( 0, max ) ];
+			}
 			return min < max ? [ min, max ] : undefined;
-		}, [ rescaleYOnVisibilityChange, dataSorted ] );
+		}, [ rescaleYOnVisibilityChange, dataSorted, isSeriesVisible, options?.yScale ] );
 
 		// Keyboard navigation steps through x positions, and the grouped tooltip
 		// reads every series at that position; the first series names the point.
@@ -365,7 +413,37 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 			preventTooltipScroll: tooltipPlacement === 'below-axis',
 		} );
 
+		// visx's d3.extent skips null/undefined/NaN, so when every visible series is all null
+		// (e.g. entirely before a site launched) the y scale has no domain. Zoom filters nothing.
+		const visibleReadingExtent = useMemo< [ number, number ] | undefined >( () => {
+			let min = Infinity;
+			let max = -Infinity;
+			for ( const series of dataSorted ) {
+				if ( ! isSeriesVisible( series.label ) ) {
+					continue;
+				}
+				for ( const point of series.data ) {
+					const value = point?.value;
+					if ( isReading( value ) ) {
+						min = Math.min( min, value );
+						max = Math.max( max, value );
+					}
+				}
+			}
+			return min <= max ? [ min, max ] : undefined;
+		}, [ dataSorted, isSeriesVisible ] );
+
+		const hasWholeNumberValues = useMemo(
+			() => hasOnlyWholeNumbers( dataSorted.filter( series => isSeriesVisible( series.label ) ) ),
+			[ dataSorted, isSeriesVisible ]
+		);
+
 		const chartOptions = useMemo( () => {
+			const fallbackYDomain = getFallbackYDomain(
+				visibleReadingExtent,
+				options?.yScale?.type === 'log'
+			);
+
 			return {
 				axis: {
 					x: buildTimeAxisOptions( {
@@ -395,11 +473,21 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 					type: 'linear' as const,
 					nice: true,
 					zero: false,
-					...( stableYDomain ? { domain: stableYDomain } : {} ),
+					...( fallbackYDomain ? { domain: fallbackYDomain } : {} ),
+					...( yDomain ? { domain: yDomain } : {} ),
 					...options?.yScale,
 				},
 			};
-		}, [ options, dataSorted, width, zoom.domain, stableYDomain, formatting, isSeriesVisible ] );
+		}, [
+			options,
+			dataSorted,
+			width,
+			zoom.domain,
+			yDomain,
+			visibleReadingExtent,
+			formatting,
+			isSeriesVisible,
+		] );
 
 		// Classified from the rendered series, like the axis above: a hidden
 		// hourly line must not leave the tooltip naming an hour the axis dropped.
@@ -445,9 +533,16 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 				withGlyph: withLegendGlyph,
 				glyphSize: Math.max( 0, toNumber( glyphStyle?.radius ) ?? 4 ),
 				collapseGroups: legendCollapseGroups,
+				comparisonItem: legendComparisonItem,
 				renderGlyph,
 			} ),
-			[ withLegendGlyph, glyphStyle?.radius, legendCollapseGroups, renderGlyph ]
+			[
+				withLegendGlyph,
+				glyphStyle?.radius,
+				legendCollapseGroups,
+				legendComparisonItem,
+				renderGlyph,
+			]
 		);
 
 		// Create legend items using the reusable hook
@@ -505,7 +600,7 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 								background: tooltipStyle?.background,
 								backgroundColor: tooltipStyle?.backgroundColor,
 							}
-					  )
+						)
 					: renderTooltip( { ...params, bucketInfo } ),
 			[ renderTooltip, bucketInfo, tooltipStyle ]
 		);
@@ -584,24 +679,42 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 											// xScale and yScale could be set in Axis as well, but they are `scale` props there.
 											xScale={ chartOptions.xScale }
 											yScale={ chartOptions.yScale }
-											onPointerDown={ zoom.handlers.onPointerDown }
-											onPointerUp={ zoom.handlers.onPointerUp }
-											onPointerMove={ zoom.handlers.onPointerMove }
 											onPointerOut={ onPointerOut }
-											pointerEventsDataKey="nearest"
 										>
+											<NearestPointerEvents { ...zoom.handlers } />
 											{ /* With every series hidden there is no data to scale against, so the grid and
 											     axes are dropped while the empty state stands in — otherwise they render
 											     squished at the top. */ }
-											{ ! allSeriesHidden && gridVisibility !== 'none' && (
-												<Grid columns={ false } numTicks={ 4 } />
-											) }
-											{ ! allSeriesHidden && chartOptions.axis.x.display && (
-												<Axis { ...chartOptions.axis.x } />
-											) }
-											{ ! allSeriesHidden && chartOptions.axis.y.display && (
-												<Axis { ...chartOptions.axis.y } />
-											) }
+											<WholeNumberTicks
+												axis="y"
+												numTicks={ chartOptions.axis.y.numTicks }
+												enabled={
+													hasWholeNumberValues &&
+													! chartOptions.axis.y.tickValues &&
+													! options?.yScale?.domain
+												}
+											>
+												{ tickValues => (
+													<>
+														{ ! allSeriesHidden && gridVisibility !== 'none' && (
+															<Grid
+																columns={ false }
+																numTicks={ chartOptions.axis.y.numTicks }
+																{ ...{ tickValues: tickValues ?? chartOptions.axis.y.tickValues } }
+															/>
+														) }
+														{ ! allSeriesHidden && chartOptions.axis.x.display && (
+															<Axis { ...chartOptions.axis.x } />
+														) }
+														{ ! allSeriesHidden && chartOptions.axis.y.display && (
+															<Axis
+																{ ...chartOptions.axis.y }
+																{ ...( tickValues ? { tickValues } : {} ) }
+															/>
+														) }
+													</>
+												) }
+											</WholeNumberTicks>
 
 											{ allSeriesHidden ? (
 												<SvgEmptyState

package/src/charts/line-chart/private/index.ts

@@ -2,3 +2,4 @@ export { default as LineChartAnnotationLabelWithPopover } from './line-chart-ann
 export { default as LineChartAnnotationsOverlay } from './line-chart-annotations-overlay';
 export { default as LineChartAnnotation } from './line-chart-annotation';
 export { default as LineChartGlyph } from './line-chart-glyph';
+export { NearestPointerEvents } from './nearest-pointer-events';

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

@@ -269,7 +269,7 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 					}px)`,
 					width: labelWidth,
 					height: labelHeight,
-			  }
+				}
 			: undefined;
 	};
 

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

@@ -20,14 +20,28 @@ const LineChartGlyph: FC< LineChartGlyphProps > = ( {
 	const { xScale, yScale } = useContext( DataContext ) || {};
 	if ( ! xScale || ! yScale ) return null;
 
-	if ( data.data.length === 0 ) return null;
+	// Skip buckets with no reading so the edge glyph lands on the nearest real one.
+	const hasFiniteY = ( datum: ( typeof data.data )[ number ] ) => {
+		const scaledY = yScale( accessors.yAccessor( datum ) );
+		return typeof scaledY === 'number' && Number.isFinite( scaledY );
+	};
 
-	const point = position === 'start' ? data.data[ 0 ] : data.data[ data.data.length - 1 ];
+	const point =
+		position === 'start' ? data.data.find( hasFiniteY ) : data.data.findLast( hasFiniteY );
+
+	if ( ! point ) return null;
 
 	const x = xScale( accessors.xAccessor( point ) );
 	const y = yScale( accessors.yAccessor( point ) );
 
-	if ( typeof x !== 'number' || typeof y !== 'number' ) return null;
+	if (
+		typeof x !== 'number' ||
+		typeof y !== 'number' ||
+		! Number.isFinite( x ) ||
+		! Number.isFinite( y )
+	) {
+		return null;
+	}
 
 	const size = Math.max( 0, toNumber( glyphStyle?.radius ) ?? 4 );
 

package/src/charts/line-chart/private/nearest-pointer-events.tsx

@@ -0,0 +1,155 @@
+import { bisector } from '@visx/vendor/d3-array';
+import { DataContext, useEventEmitter } from '@visx/xychart';
+import { useCallback, useContext, useMemo } from 'react';
+import type { EventHandlerParams } from '@visx/xychart';
+
+type EmittedPointer = Parameters< NonNullable< Parameters< typeof useEventEmitter >[ 1 ] > >[ 0 ];
+type PointerParams = EventHandlerParams< object >;
+type PointerHandler = ( params: PointerParams ) => void;
+type Scale = ( ( value: unknown ) => unknown ) & { invert?: ( position: number ) => unknown };
+type Candidate = { params: PointerParams; isMissing: boolean };
+
+/**
+ * Find the datum nearest a pointer along x, in one series sorted by x.
+ *
+ * @param data      - The series' registered data, in ascending x order.
+ * @param xAccessor - Reads a datum's x value.
+ * @param xScale    - The chart's x scale.
+ * @param x         - Pointer x in SVG coordinates.
+ * @return Index of the nearest datum and its distance, or index -1 when none has a position.
+ */
+function nearestByX(
+	data: object[],
+	xAccessor: ( datum: object ) => unknown,
+	xScale: Scale,
+	x: number
+): { index: number; distance: number } {
+	const indexes =
+		typeof xScale.invert === 'function'
+			? [ bisector( xAccessor ).left( data, xScale.invert( x ) ) ].flatMap( index => [
+					index - 1,
+					index,
+				] )
+			: data.map( ( _datum, index ) => index );
+
+	return indexes
+		.filter( index => index >= 0 && index < data.length )
+		.reduce(
+			( best, index ) => {
+				const distance = Math.abs( Number( xScale( xAccessor( data[ index ] ) ) ) - x );
+				return distance < best.distance ? { index, distance } : best;
+			},
+			{ index: -1, distance: Infinity }
+		);
+}
+
+/**
+ * Pick the candidate to report: the closest placed reading, else the closest bucket with no reading along x.
+ *
+ * @param candidates - One candidate per series.
+ * @return The chosen candidate's params, or undefined when there are none.
+ */
+function pickNearest( candidates: Candidate[] ): PointerParams | undefined {
+	const placed = candidates
+		.map( ( { params } ) => params )
+		.filter( params => Number.isFinite( params.distanceY ) );
+	const missing = candidates
+		.filter( ( { isMissing } ) => isMissing )
+		.map( ( { params } ) => params );
+	// Same metric as visx's TooltipProvider, so a callback names the datum the tooltip shows.
+	const distance = ( params: PointerParams ) =>
+		placed.length
+			? Math.hypot( params.distanceX ?? 0, params.distanceY ?? 0 )
+			: ( params.distanceX ?? 0 );
+
+	return ( placed.length ? placed : missing ).reduce< PointerParams | undefined >(
+		( best, params ) => ( ! best || distance( params ) < distance( best ) ? params : best ),
+		undefined
+	);
+}
+
+/**
+ * Report pointer events at the nearest datum, including a bucket with no reading.
+ *
+ * visx's own nearest search measures y distance too, which is NaN for a null value, so a pointer
+ * over a bucket where no series has a reading fires no event at all.
+ *
+ * @param props               - Handlers to call.
+ * @param props.onPointerDown - Receives the nearest datum on pointer down.
+ * @param props.onPointerMove - Receives the nearest datum on pointer move.
+ * @param props.onPointerUp   - Receives the nearest datum on pointer up.
+ * @return No visual content.
+ */
+export function NearestPointerEvents( {
+	onPointerDown,
+	onPointerMove,
+	onPointerUp,
+}: {
+	onPointerDown?: PointerHandler;
+	onPointerMove?: PointerHandler;
+	onPointerUp?: PointerHandler;
+} ) {
+	const { xScale, yScale, dataRegistry } = useContext( DataContext );
+
+	const findNearest = useCallback(
+		( params: EmittedPointer ) => {
+			const point = params?.svgPoint;
+			if ( ! point || ! xScale || ! yScale || ! dataRegistry ) {
+				return undefined;
+			}
+			const candidates: Candidate[] = [];
+			for ( const key of dataRegistry.keys() ) {
+				const entry = dataRegistry.get( key );
+				if ( ! entry ) {
+					continue;
+				}
+				const { index, distance } = nearestByX(
+					entry.data,
+					entry.xAccessor,
+					xScale as Scale,
+					point.x
+				);
+				if ( index < 0 ) {
+					continue;
+				}
+				const datum = entry.data[ index ];
+				const value = entry.yAccessor( datum );
+				candidates.push( {
+					params: {
+						event: params.event,
+						svgPoint: point,
+						key,
+						datum,
+						index,
+						distanceX: distance,
+						distanceY: Math.abs( Number( ( yScale as Scale )( value ) ) - point.y ),
+					},
+					isMissing: value == null,
+				} );
+			}
+			return pickNearest( candidates );
+		},
+		[ xScale, yScale, dataRegistry ]
+	);
+
+	const handlers = useMemo( () => {
+		const report = ( handler?: PointerHandler ) =>
+			handler &&
+			( ( params: EmittedPointer ) => {
+				const nearest = findNearest( params );
+				if ( nearest ) {
+					handler( nearest );
+				}
+			} );
+		return {
+			pointerdown: report( onPointerDown ),
+			pointermove: report( onPointerMove ),
+			pointerup: report( onPointerUp ),
+		};
+	}, [ findNearest, onPointerDown, onPointerMove, onPointerUp ] );
+
+	useEventEmitter( 'pointerdown', handlers.pointerdown );
+	useEventEmitter( 'pointermove', handlers.pointermove );
+	useEventEmitter( 'pointerup', handlers.pointerup );
+	return null;
+}