@automattic/charts 4.0.0 → 4.1.0

package/src/components/tooltip/test/accessible-tooltip.test.tsx

@@ -6,7 +6,7 @@ import { ChartScopeContext } from '../../../providers/chart-scope';
 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.
-const renderChart = ( scope?: HTMLElement ) => {
+const renderChart = ( scope?: HTMLElement, tooltipPlacement?: 'auto' | 'below-axis' ) => {
 	const chart = (
 		<LineChartUnresponsive
 			width={ 500 }
@@ -22,6 +22,7 @@ const renderChart = ( scope?: HTMLElement ) => {
 				},
 			] }
 			withTooltips
+			tooltipPlacement={ tooltipPlacement }
 			withTooltipCrosshairs={ { showVertical: true } }
 			withGradientFill={ false }
 		/>
@@ -59,6 +60,32 @@ describe( 'AccessibleTooltip', () => {
 		document.body.removeChild( scope );
 	} );
 
+	it( 'keeps the existing focus scrolling for automatic tooltips', async () => {
+		const focus = jest.spyOn( HTMLElement.prototype, 'focus' );
+		try {
+			renderChart();
+			await openTooltip();
+
+			expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveFocus();
+			expect( focus ).toHaveBeenLastCalledWith();
+		} finally {
+			focus.mockRestore();
+		}
+	} );
+
+	it( 'focuses below-axis keyboard tooltips without scrolling their ancestors', async () => {
+		const focus = jest.spyOn( HTMLElement.prototype, 'focus' );
+		try {
+			renderChart( undefined, 'below-axis' );
+			await openTooltip();
+
+			expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveFocus();
+			expect( focus ).toHaveBeenCalledWith( { preventScroll: true } );
+		} finally {
+			focus.mockRestore();
+		}
+	} );
+
 	it( 'falls back to the catalog default when the role is unset', async () => {
 		renderChart();
 

package/src/components/tooltip/test/bounded-tooltip.test.tsx

@@ -12,6 +12,7 @@ describe( 'getBoundedPosition', () => {
 				top: 20,
 				...OFFSETS,
 				box: BOX,
+				wrapper: { left: 0, top: 0, right: 600, bottom: 300 },
 				bounds: { left: 0, top: 0, right: 600, bottom: 300 },
 			} )
 		).toEqual( { x: 50, y: 30 } );
@@ -24,6 +25,7 @@ describe( 'getBoundedPosition', () => {
 				top: 280,
 				...OFFSETS,
 				box: BOX,
+				wrapper: { left: 0, top: 0, right: 600, bottom: 300 },
 				bounds: { left: 0, top: 0, right: 600, bottom: 300 },
 			} )
 		).toEqual( { x: 282, y: 234 } );
@@ -38,23 +40,54 @@ describe( 'getBoundedPosition', () => {
 				top: 50,
 				...OFFSETS,
 				box: BOX,
+				wrapper: { left: 0, top: 0, right: 346, bottom: 200 },
 				bounds: { left: 0, top: 0, right: 346, bottom: 200 },
 			} )
 		).toEqual( { x: 138, y: 60 } );
 	} );
 
 	test( 'may leave the wrapper as long as it stays inside the clipping ancestor', () => {
-		// The wrapper starts 40px inside its clipping card, so the box can reach
-		// 40px past the wrapper's left edge, and stops there.
+		// Neither side fits the 346px wrapper, and the clipping card ends 14px
+		// past its right edge, so the box keeps the near side and stops there.
 		expect(
 			getBoundedPosition( {
 				left: 173,
 				top: 50,
 				...OFFSETS,
 				box: BOX,
+				wrapper: { left: 0, top: 0, right: 346, bottom: 200 },
 				bounds: { left: -40, top: -60, right: 360, bottom: 200 },
 			} )
-		).toEqual( { x: -40, y: 60 } );
+		).toEqual( { x: 152, y: 60 } );
+	} );
+
+	test( 'flips up to stay inside the wrapper even when the page below has room', () => {
+		// The box fits above the anchor inside the 200px wrapper, so it goes
+		// there rather than below the chart, where the page would cover it.
+		expect(
+			getBoundedPosition( {
+				left: 40,
+				top: 180,
+				...OFFSETS,
+				box: BOX,
+				wrapper: { left: 0, top: 0, right: 600, bottom: 200 },
+				bounds: { left: 0, top: 0, right: 1024, bottom: 768 },
+			} )
+		).toEqual( { x: 50, y: 134 } );
+	} );
+
+	test( 'flips up when the wrapper fits below but the clipping ancestor does not', () => {
+		// A scrolled container cuts the wrapper off 20px under the anchor.
+		expect(
+			getBoundedPosition( {
+				left: 40,
+				top: 100,
+				...OFFSETS,
+				box: BOX,
+				wrapper: { left: 0, top: 0, right: 600, bottom: 300 },
+				bounds: { left: 0, top: -50, right: 600, bottom: 120 },
+			} )
+		).toEqual( { x: 50, y: 54 } );
 	} );
 } );
 
@@ -100,11 +133,74 @@ describe( 'BoundedTooltip', () => {
 			</div>
 		);
 
-		// Neither side of the anchor fits inside the card, so the box stops at
-		// the card's left edge, 40px outside the wrapper.
-		expect( screen.getByTestId( 'box' ) ).toHaveStyle( { transform: 'translate(-40px, 60px)' } );
+		// Neither side of the anchor fits the wrapper, so the box keeps the near
+		// side and stops at the card's right edge, 14px outside the wrapper.
+		expect( screen.getByTestId( 'box' ) ).toHaveStyle( { transform: 'translate(152px, 60px)' } );
 	} );
 
+	test( 'keeps the box inside the wrapper when nothing clips and the anchor sits low', () => {
+		jest.spyOn( Element.prototype, 'getBoundingClientRect' ).mockImplementation( function (
+			this: Element
+		) {
+			return this.classList.contains( 'visx-tooltip' )
+				? rect( 0, 0, 150, 100 )
+				: rect( 100, 100, 600, 200 );
+		} );
+
+		render(
+			<div style={ { position: 'relative' } }>
+				<BoundedTooltip left={ 300 } top={ 180 } data-testid="box">
+					content
+				</BoundedTooltip>
+			</div>
+		);
+
+		// The viewport has room below the wrapper, but that is where the page's
+		// own content paints over the box; above the anchor it fits in the chart.
+		expect( screen.getByTestId( 'box' ) ).toHaveStyle( { transform: 'translate(310px, 70px)' } );
+	} );
+
+	test.each( [
+		{ anchor: 20, x: 0, pointerLeft: 14 },
+		{ anchor: 150, x: 46, pointerLeft: 98 },
+		{ anchor: 280, x: 92, pointerLeft: 182 },
+	] )(
+		'keeps the below-axis pointer at x=$anchor after clamping',
+		( { anchor, x, pointerLeft } ) => {
+			jest.spyOn( Element.prototype, 'getBoundingClientRect' ).mockImplementation( function (
+				this: Element
+			) {
+				return this.classList.contains( 'visx-tooltip' )
+					? rect( 0, 0, 208, 36 )
+					: rect( 0, 0, 300, 100 );
+			} );
+
+			render(
+				<div style={ { overflow: 'hidden' } }>
+					<div style={ { position: 'relative' } }>
+						<BoundedTooltip placement="below-axis" left={ anchor } top={ 100 } data-testid="box">
+							content
+						</BoundedTooltip>
+					</div>
+				</div>
+			);
+
+			expect( screen.getByTestId( 'box' ) ).toHaveStyle( {
+				transform: `translate(${ x }px, 106px)`,
+			} );
+			expect( screen.getByTestId( 'tooltip-axis-pointer' ) ).toHaveStyle( {
+				left: `${ pointerLeft }px`,
+				top: '-6px',
+				width: '12px',
+				height: '6px',
+			} );
+			expect( screen.getByTestId( 'tooltip-axis-pointer' ) ).toHaveAttribute(
+				'aria-hidden',
+				'true'
+			);
+		}
+	);
+
 	test( 'falls back to the viewport when nothing clips', () => {
 		jest.spyOn( Element.prototype, 'getBoundingClientRect' ).mockImplementation( function (
 			this: Element

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

@@ -131,6 +131,54 @@ describe( 'XyChartTooltip', () => {
 		);
 	} );
 
+	test( 'anchors below the x-axis label band without moving datum glyphs or crosshairs', async () => {
+		const originalRect = Element.prototype.getBoundingClientRect;
+		const rectSpy = jest
+			.spyOn( Element.prototype, 'getBoundingClientRect' )
+			.mockImplementation( function ( this: Element ) {
+				const rect = originalRect.call( this );
+				return this.classList.contains( 'visx-tooltip' )
+					? { ...rect, width: 80, height: 30, right: rect.left + 80, bottom: rect.top + 30 }
+					: rect;
+			} );
+
+		try {
+			renderChart(
+				{
+					tooltipPlacement: 'below-axis',
+					snapTooltipToDatumY: true,
+					showDatumGlyph: true,
+					showVerticalCrosshair: true,
+					showHorizontalCrosshair: true,
+				},
+				undefined,
+				{ top: 10, right: 20, bottom: 30, left: 40 }
+			);
+
+			const box = await screen.findByTestId( 'tooltip-box' );
+			expect( box ).toHaveStyle( { transform: 'translate(70px, 106px)' } );
+			expect( screen.getByTestId( 'wrapper' ) ).toContainElement( box );
+			expect( screen.getByTestId( 'tooltip-axis-pointer' ) ).toHaveStyle( {
+				left: '34px',
+				top: '-6px',
+			} );
+			expect( screen.getByTestId( 'xy-chart-tooltip-glyph-group-A' ) ).toHaveAttribute(
+				'transform',
+				'translate(110, 40)'
+			);
+			expect( screen.getByTestId( 'xy-chart-tooltip-crosshair-vertical' ) ).toHaveAttribute(
+				'y2',
+				'70'
+			);
+			expect( screen.getByTestId( 'xy-chart-tooltip-crosshair-horizontal' ) ).toHaveAttribute(
+				'y1',
+				'40'
+			);
+		} finally {
+			rectSpy.mockRestore();
+		}
+	} );
+
 	test( 'draws one glyph per series in the SVG at the datum position', async () => {
 		renderChart( { showSeriesGlyphs: true }, BOTH_SERIES );
 
@@ -235,6 +283,38 @@ describe( 'XyChartTooltip', () => {
 		expect( horizontal ).toHaveAttribute( 'x2', '180' );
 	} );
 
+	test( 'applies crosshair paint without allowing geometry overrides', async () => {
+		const consumerStyle = {
+			stroke: 'purple',
+			strokeWidth: 8,
+			className: 'custom-crosshair',
+			x1: 999,
+			transform: 'translate(100 0)',
+			style: { strokeOpacity: 0.25, transform: 'translateX(100px)' },
+		};
+		renderChart( {
+			snapTooltipToDatumX: true,
+			snapTooltipToDatumY: true,
+			showVerticalCrosshair: true,
+			showHorizontalCrosshair: true,
+			verticalCrosshairStyle: consumerStyle,
+			horizontalCrosshairStyle: consumerStyle,
+		} );
+
+		for ( const direction of [ 'vertical', 'horizontal' ] ) {
+			const guide = await screen.findByTestId( `xy-chart-tooltip-crosshair-${ direction }` );
+			expect( guide ).toHaveAttribute( 'stroke', 'purple' );
+			expect( guide ).toHaveAttribute( 'stroke-width', '8' );
+			expect( guide ).toHaveClass( 'custom-crosshair' );
+			expect( guide ).toHaveStyle( { 'stroke-opacity': '0.25', transform: 'none' } );
+			expect( guide ).not.toHaveAttribute( 'transform' );
+			expect( guide ).toHaveAttribute( 'x1', direction === 'vertical' ? '100' : '0' );
+			expect( guide ).toHaveAttribute( 'x2', direction === 'vertical' ? '100' : '200' );
+			expect( guide ).toHaveAttribute( 'y1', direction === 'vertical' ? '0' : '50' );
+			expect( guide ).toHaveAttribute( 'y2', direction === 'vertical' ? '100' : '50' );
+		}
+	} );
+
 	test( 'stacks the box above the chart overlays, with zIndex as the override', async () => {
 		const { unmount } = renderChart();
 		await expect( screen.findByTestId( 'tooltip-box' ) ).resolves.toHaveStyle( { zIndex: '3' } );
@@ -244,6 +324,26 @@ describe( 'XyChartTooltip', () => {
 		await expect( screen.findByTestId( 'tooltip-box' ) ).resolves.toHaveStyle( { zIndex: '9' } );
 	} );
 
+	test.each( [ 'auto', 'below-axis' ] as const )(
+		'preserves %s background and stacking with a partial style override',
+		async tooltipPlacement => {
+			const { unmount } = renderChart( { tooltipPlacement } );
+			const defaultBox = await screen.findByTestId( 'tooltip-box' );
+			const background = defaultBox.style.backgroundColor;
+			expect( background ).not.toBe( '' );
+			expect( background ).not.toBe( 'transparent' );
+			unmount();
+
+			renderChart( { tooltipPlacement, style: { color: 'red' } } );
+
+			await expect( screen.findByTestId( 'tooltip-box' ) ).resolves.toHaveStyle( {
+				backgroundColor: background,
+				zIndex: '3',
+				color: 'rgb(255, 0, 0)',
+			} );
+		}
+	);
+
 	test( 'accepts the portal-era options without passing them to the box', async () => {
 		renderChart( { scroll: true, debounce: 50, resizeObserverPolyfill: undefined } );
 

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

@@ -3,11 +3,36 @@ import { DataContext, TooltipContext } from '@visx/xychart';
 import { useCallback, useContext, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { BoundedTooltip } from './private/bounded-tooltip';
-import type { RenderTooltipGlyphProps, XyChartTooltipProps } from '../../visx/types';
+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 ) )
+		);
+
+	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';
 // Above the chart's own overlays (the zoom reset button sits at 2). The chart
@@ -83,7 +108,9 @@ const XyChartTooltipContent = < Datum extends object >( {
 	verticalCrosshairStyle,
 	horizontalCrosshairStyle,
 	detectBounds = true,
+	tooltipPlacement = 'auto',
 	zIndex = DEFAULT_TOOLTIP_Z_INDEX,
+	style,
 	...rest
 }: XyChartTooltipContentProps< Datum > ) => {
 	const tooltipProps = Object.fromEntries(
@@ -125,9 +152,12 @@ const XyChartTooltipContent = < Datum extends object >( {
 	const nearestDatum = tooltipContext.tooltipData?.nearestDatum;
 	let { tooltipLeft, tooltipTop } = tooltipContext;
 
-	if ( nearestDatum && ( snapTooltipToDatumX || snapTooltipToDatumY ) ) {
+	if (
+		nearestDatum &&
+		( snapTooltipToDatumX || snapTooltipToDatumY || tooltipPlacement === 'below-axis' )
+	) {
 		const { left, top } = getDatumLeftTop( nearestDatum.key, nearestDatum.datum );
-		if ( snapTooltipToDatumX && isValidNumber( left ) ) {
+		if ( ( snapTooltipToDatumX || tooltipPlacement === 'below-axis' ) && isValidNumber( left ) ) {
 			tooltipLeft = left;
 		}
 		if ( snapTooltipToDatumY && isValidNumber( top ) ) {
@@ -183,15 +213,17 @@ const XyChartTooltipContent = < Datum extends object >( {
 	const marginTop = margin?.top ?? 0;
 	const marginLeft = margin?.left ?? 0;
 
-	const TooltipComponent = detectBounds ? BoundedTooltip : Tooltip;
+	const TooltipComponent =
+		detectBounds || tooltipPlacement === 'below-axis' ? BoundedTooltip : Tooltip;
 	const boxStyle: CSSProperties = {
 		...defaultStyles,
 		zIndex,
-		background: theme?.backgroundColor ?? 'white',
+		backgroundColor: theme?.backgroundColor ?? 'white',
 		boxShadow: `0 1px 2px ${
 			theme?.htmlLabel?.color ? `${ theme.htmlLabel.color }55` : '#22222255'
 		}`,
 		...theme?.htmlLabel,
+		...style,
 	};
 
 	return (
@@ -201,26 +233,26 @@ const XyChartTooltipContent = < Datum extends object >( {
 					<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 }
-						stroke={ crosshairStroke }
-						strokeWidth={ CROSSHAIR_STROKE_WIDTH }
-						{ ...verticalCrosshairStyle }
 					/>
 				) }
 				{ 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 }
-						stroke={ crosshairStroke }
-						strokeWidth={ CROSSHAIR_STROKE_WIDTH }
-						{ ...horizontalCrosshairStyle }
 					/>
 				) }
 				{ glyphs }
@@ -229,10 +261,15 @@ const XyChartTooltipContent = < Datum extends object >( {
 				createPortal(
 					<TooltipComponent
 						left={ tooltipLeft }
-						top={ tooltipTop }
+						top={
+							tooltipPlacement === 'below-axis'
+								? marginTop + innerHeight + ( margin?.bottom ?? 0 )
+								: tooltipTop
+						}
 						style={ boxStyle }
 						applyPositionStyle
 						{ ...tooltipProps }
+						{ ...( tooltipPlacement === 'below-axis' && { placement: tooltipPlacement } ) }
 					>
 						{ tooltipContent }
 					</TooltipComponent>,
@@ -259,7 +296,8 @@ const XyChartTooltipContent = < Datum extends object >( {
  * 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.
+ * 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.

package/src/hooks/test/use-chart-data-transform-zone.test.tsx

@@ -0,0 +1,36 @@
+import { render, screen } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../providers';
+import { useChartDataTransform } from '../use-chart-data-transform';
+import type { SeriesData } from '../../types';
+
+// One reference, reused across both renders, so only the zone can invalidate the memo.
+const data: SeriesData[] = [
+	{ label: 'Series A', data: [ { dateString: '2026-08-02', value: 1 } ] },
+];
+
+const Probe = () => {
+	const [ series ] = useChartDataTransform( data );
+	const point = series.data[ 0 ] as { date?: Date };
+
+	return <span data-testid="instant">{ point.date?.toISOString() }</span>;
+};
+
+describe( 'useChartDataTransform', () => {
+	it( 're-dates its points when only the provider time zone changes', () => {
+		const { rerender } = render(
+			<GlobalChartsProvider timeZone="Asia/Tokyo">
+				<Probe />
+			</GlobalChartsProvider>
+		);
+
+		expect( screen.getByTestId( 'instant' ) ).toHaveTextContent( '2026-08-01T15:00:00.000Z' );
+
+		rerender(
+			<GlobalChartsProvider timeZone="Pacific/Auckland">
+				<Probe />
+			</GlobalChartsProvider>
+		);
+
+		expect( screen.getByTestId( 'instant' ) ).toHaveTextContent( '2026-08-01T12:00:00.000Z' );
+	} );
+} );