@automattic/charts 4.0.0 → 4.1.0

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

@@ -58,7 +58,7 @@ import type { RenderTooltipParams } from '../../visx/types';
 import type { ResponsiveConfig } from '../private/with-responsive';
 import type { TickFormatter } from '@visx/axis';
 import type { GlyphProps } from '@visx/xychart';
-import type { FC, Ref } from 'react';
+import type { CSSProperties, FC, Ref } from 'react';
 
 const defaultRenderGlyph = < Datum extends object >( props: RenderLineGlyphProps< Datum > ) => {
 	return <DefaultGlyph { ...props } key={ props.key } />;
@@ -108,11 +108,13 @@ const TooltipDate: FC< { date?: Date; displayResolution: Exclude< TickResolution
  * one row per visible series (label + formatted value), sorted descending by
  * value. Reused by AreaChart, which has the same multi-series shape.
  *
- * @param params - visx `RenderTooltipParams< DataPointDate >`, plus the chart's optional `bucketInfo`.
+ * @param params       - visx tooltip data and the chart's optional `bucketInfo`.
+ * @param contentStyle - Explicit tooltip content color overrides.
  * @return Tooltip JSX, or `null` when no datum is hovered.
  */
 export const renderDefaultTooltip = (
-	params: RenderTooltipParams< DataPointDate > & { bucketInfo?: BucketInfo }
+	params: RenderTooltipParams< DataPointDate > & { bucketInfo?: BucketInfo },
+	contentStyle?: Pick< CSSProperties, 'color' | 'background' | 'backgroundColor' >
 ) => {
 	const { tooltipData, bucketInfo } = params;
 	const nearestDatum = tooltipData?.nearestDatum?.datum;
@@ -126,7 +128,11 @@ export const renderDefaultTooltip = (
 		.sort( ( a, b ) => b.value - a.value );
 
 	return (
-		<div className={ styles[ 'line-chart__tooltip' ] }>
+		<div
+			className={ styles[ 'line-chart__tooltip' ] }
+			data-testid="line-chart-tooltip-content"
+			style={ contentStyle }
+		>
 			<div className={ styles[ 'line-chart__tooltip-date' ] }>
 				<TooltipDate
 					date={ nearestDatum.date }
@@ -221,6 +227,8 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 			smoothing = true,
 			curveType,
 			renderTooltip = renderDefaultTooltip,
+			tooltipPlacement,
+			tooltipStyle,
 			withStartGlyphs = false,
 			withEndGlyphs = false,
 			animation,
@@ -354,6 +362,7 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 			chartRef,
 			totalPoints: dataSorted[ 0 ]?.data.length || 0,
 			onActivate: activateSelectedPoint,
+			preventTooltipScroll: tooltipPlacement === 'below-axis',
 		} );
 
 		const chartOptions = useMemo( () => {
@@ -473,12 +482,32 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 			yAccessor: ( d: DataPointDate ) => d?.value,
 		};
 
+		const resolvedTooltipStyle = useMemo( () => {
+			if ( renderTooltip !== renderDefaultTooltip || ! tooltipStyle ) return tooltipStyle;
+			if ( ! tooltipStyle.color || tooltipStyle.background || tooltipStyle.backgroundColor ) {
+				return tooltipStyle;
+			}
+			return {
+				backgroundColor: 'var(--a8c-charts-color-tooltip-surface, rgb(0 0 0 / 85%))',
+				...tooltipStyle,
+			};
+		}, [ renderTooltip, tooltipStyle ] );
+
 		// Augments every renderTooltip call with the chart's bucket classification,
 		// default or custom, so a heading keyed on it can't disagree with the axis.
 		const tooltipRenderer = useMemo(
 			() => ( params: RenderTooltipParams< DataPointDate > ) =>
-				renderTooltip( { ...params, bucketInfo } ),
-			[ renderTooltip, bucketInfo ]
+				renderTooltip === renderDefaultTooltip
+					? renderDefaultTooltip(
+							{ ...params, bucketInfo },
+							{
+								color: tooltipStyle?.color,
+								background: tooltipStyle?.background,
+								backgroundColor: tooltipStyle?.backgroundColor,
+							}
+					  )
+					: renderTooltip( { ...params, bucketInfo } ),
+			[ renderTooltip, bucketInfo, tooltipStyle ]
 		);
 
 		if ( error ) {
@@ -676,6 +705,8 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 												<AccessibleTooltip
 													detectBounds
 													snapTooltipToDatumX
+													tooltipPlacement={ tooltipPlacement }
+													style={ resolvedTooltipStyle }
 													snapTooltipToDatumY
 													showSeriesGlyphs
 													renderTooltip={ tooltipRenderer }
@@ -683,6 +714,8 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 													glyphStyle={ glyphStyle }
 													showVerticalCrosshair={ withTooltipCrosshairs?.showVertical }
 													showHorizontalCrosshair={ withTooltipCrosshairs?.showHorizontal }
+													verticalCrosshairStyle={ withTooltipCrosshairs?.verticalStyle }
+													horizontalCrosshairStyle={ withTooltipCrosshairs?.horizontalStyle }
 													selectedIndex={ selectedIndex }
 													tooltipRef={ tooltipRef }
 													keyboardFocusedClassName={

package/src/charts/line-chart/test/crosshair-style-types.test.ts

@@ -0,0 +1,31 @@
+import type { LineChartProps } from '../types';
+
+type Crosshairs = NonNullable< LineChartProps[ 'withTooltipCrosshairs' ] >;
+
+describe( 'line chart crosshair style types', () => {
+	test( 'accepts paint attributes', () => {
+		const crosshairs: Crosshairs = { verticalStyle: { stroke: 'purple', strokeWidth: 2 } };
+
+		expect( crosshairs.verticalStyle?.stroke ).toBe( 'purple' );
+	} );
+
+	test( 'reserves geometry attributes for the chart', () => {
+		const crosshairs: Crosshairs = {
+			// @ts-expect-error Crosshair coordinates are computed from the active datum.
+			verticalStyle: { x1: 12 },
+		};
+
+		const transformedCrosshairs: Crosshairs = {
+			// @ts-expect-error Crosshair transforms are not paint attributes.
+			verticalStyle: { transform: 'translate(100 0)' },
+		};
+		const transformedStyles: Crosshairs = {
+			// @ts-expect-error Inline crosshair styles accept only paint properties.
+			horizontalStyle: { style: { transform: 'translateX(100px)' } },
+		};
+
+		expect( crosshairs ).toBeDefined();
+		expect( transformedCrosshairs ).toBeDefined();
+		expect( transformedStyles ).toBeDefined();
+	} );
+} );

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

@@ -104,6 +104,106 @@ describe( 'LineChart', () => {
 		);
 	};
 
+	test.each( [ 'auto', 'below-axis' ] as const )(
+		'passes custom tooltip container and crosshair styles with %s placement',
+		async tooltipPlacement => {
+			const user = userEvent.setup();
+			renderWithTheme( {
+				withTooltipCrosshairs: {
+					showVertical: true,
+					showHorizontal: true,
+					verticalStyle: { stroke: 'purple', strokeWidth: 40, strokeOpacity: 0.12 },
+					horizontalStyle: { stroke: 'orange', strokeDasharray: '4 2' },
+				},
+				tooltipPlacement,
+				tooltipStyle: { backgroundColor: 'black', color: 'white', boxShadow: 'none' },
+			} );
+			screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+			await user.keyboard( '{ArrowRight}' );
+
+			const vertical = screen.getByTestId( 'xy-chart-tooltip-crosshair-vertical' );
+			expect( vertical ).toHaveAttribute( 'stroke', 'purple' );
+			expect( vertical ).toHaveAttribute( 'stroke-width', '40' );
+			expect( vertical ).toHaveAttribute( 'stroke-opacity', '0.12' );
+			const horizontal = screen.getByTestId( 'xy-chart-tooltip-crosshair-horizontal' );
+			expect( horizontal ).toHaveAttribute( 'stroke', 'orange' );
+			expect( horizontal ).toHaveAttribute( 'stroke-dasharray', '4 2' );
+			expect( screen.getByTestId( 'bounded-tooltip' ) ).toHaveStyle( {
+				'background-color': 'rgb(0, 0, 0)',
+				color: 'rgb(255, 255, 255)',
+				'box-shadow': 'none',
+			} );
+			expect( screen.getByTestId( 'line-chart-tooltip-content' ) ).toHaveStyle( {
+				color: 'rgb(255, 255, 255)',
+			} );
+		}
+	);
+	test.each( [
+		[
+			{ color: 'white' },
+			'rgb(255, 255, 255)',
+			'var(--a8c-charts-color-tooltip-surface, rgb(0 0 0 / 85%))',
+			{ color: 'rgb(255, 255, 255)' },
+		],
+		[ { backgroundColor: 'white' }, 'var(--a8c-charts-color-label)', 'rgb(255, 255, 255)', {} ],
+		[ { background: 'white' }, 'var(--a8c-charts-color-label)', 'white', {} ],
+		[
+			{ color: 'white', background: 'black' },
+			'rgb(255, 255, 255)',
+			'black',
+			{ color: 'rgb(255, 255, 255)' },
+		],
+	] )(
+		'applies directional tooltip color defaults: %j',
+		async ( tooltipStyle, color, background, containerColorStyle ) => {
+			const user = userEvent.setup();
+			const defaults = document.createElement( 'style' );
+			defaults.textContent = `.line-chart__tooltip {
+				color: var(--a8c-charts-color-label);
+				background: var(--a8c-charts-color-surface);
+			}`;
+			renderWithTheme( { tooltipStyle } );
+			const chart = screen.getByTestId( 'line-chart' );
+			chart.appendChild( defaults );
+			chart.style.setProperty( '--a8c-charts-color-label', '#000' );
+			chart.style.setProperty( '--a8c-charts-color-label-axis', '#aaa' );
+			chart.style.setProperty( '--a8c-charts-color-surface', '#fff' );
+			screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+			await user.keyboard( '{ArrowRight}' );
+
+			const content = screen.getByTestId( 'line-chart-tooltip-content' );
+			expect( content ).toHaveStyle( {
+				color,
+				[ 'backgroundColor' in tooltipStyle ? 'background-color' : 'background' ]:
+					'background' in tooltipStyle || 'backgroundColor' in tooltipStyle
+						? background
+						: 'var(--a8c-charts-color-surface)',
+			} );
+			const container = screen.getByTestId( 'bounded-tooltip' );
+			expect( container ).toHaveStyle( {
+				...containerColorStyle,
+				[ 'background' in tooltipStyle ? 'background' : 'background-color' ]: background,
+			} );
+		}
+	);
+
+	test( 'preserves the existing tooltip colors for noncolor overrides', async () => {
+		const user = userEvent.setup();
+		renderWithTheme( { tooltipStyle: { boxShadow: 'none' } } );
+		screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+		await user.keyboard( '{ArrowRight}' );
+
+		const content = screen.getByTestId( 'line-chart-tooltip-content' );
+		expect( content.style.getPropertyValue( 'color' ) ).toBe( '' );
+		expect( content.style.getPropertyValue( 'background' ) ).toBe( '' );
+		const container = screen.getByTestId( 'bounded-tooltip' );
+		expect( container ).toHaveStyle( { 'box-shadow': 'none' } );
+		expect( container.style.getPropertyValue( 'background' ) ).toBe( '' );
+		expect( container.style.getPropertyValue( 'color' ) ).not.toBe(
+			'var(--a8c-charts-color-label-inverse)'
+		);
+	} );
+
 	describe( 'Data Validation', () => {
 		test( 'handles empty data array', () => {
 			renderWithTheme( { data: [] } );
@@ -1225,44 +1325,53 @@ describe( 'LineChart', () => {
 		} );
 
 		describe( 'Arrow Key Navigation', () => {
-			test( 'right arrow key navigates to next data point', async () => {
-				const user = userEvent.setup();
-				renderWithTheme( {
-					data: [
-						{
-							label: 'Series A',
-							data: [
-								{ date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' },
-								{ date: new Date( '2024-01-02' ), value: 20, label: 'Jan 2' },
-							],
-							options: {},
-						},
-						{
-							label: 'Series B',
-							data: [
-								{ date: new Date( '2024-01-01' ), value: 15, label: 'Jan 1' },
-								{ date: new Date( '2024-01-02' ), value: 25, label: 'Jan 2' },
-							],
-							options: {},
-						},
-					],
-				} );
-
-				const chart = screen.getByRole( 'grid', { name: /line chart/i } );
-				chart.focus();
-
-				// Single tab should focus on the first tooltip.
-				await user.keyboard( '{ArrowRight}' );
-				expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveFocus();
-				expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveTextContent( 'Series A' );
-				expect( screen.queryByTestId( 'chart-tooltip-1' ) ).not.toBeInTheDocument();
-
-				// Second tab should focus on the second tooltip.
-				await user.keyboard( '{ArrowRight}' );
-				expect( screen.getByTestId( 'chart-tooltip-1' ) ).toHaveFocus();
-				expect( screen.getByTestId( 'chart-tooltip-1' ) ).toHaveTextContent( 'Series B' );
-				expect( screen.queryByTestId( 'chart-tooltip-0' ) ).not.toBeInTheDocument();
-			} );
+			test.each( [ 'auto', 'below-axis' ] as const )(
+				'right arrow key navigates with %s tooltips',
+				async tooltipPlacement => {
+					const user = userEvent.setup();
+					renderWithTheme( {
+						tooltipPlacement,
+						data: [
+							{
+								label: 'Series A',
+								data: [
+									{ date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' },
+									{ date: new Date( '2024-01-02' ), value: 20, label: 'Jan 2' },
+								],
+								options: {},
+							},
+							{
+								label: 'Series B',
+								data: [
+									{ date: new Date( '2024-01-01' ), value: 15, label: 'Jan 1' },
+									{ date: new Date( '2024-01-02' ), value: 25, label: 'Jan 2' },
+								],
+								options: {},
+							},
+						],
+					} );
+
+					const chart = screen.getByRole( 'grid', { name: /line chart/i } );
+					chart.focus();
+
+					// Single tab should focus on the first tooltip.
+					await user.keyboard( '{ArrowRight}' );
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveFocus();
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveAttribute( 'role', 'tooltip' );
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveAttribute(
+						'aria-atomic',
+						'true'
+					);
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveTextContent( 'Series A' );
+					expect( screen.queryByTestId( 'chart-tooltip-1' ) ).not.toBeInTheDocument();
+
+					// Second tab should focus on the second tooltip.
+					await user.keyboard( '{ArrowRight}' );
+					expect( screen.getByTestId( 'chart-tooltip-1' ) ).toHaveFocus();
+					expect( screen.getByTestId( 'chart-tooltip-1' ) ).toHaveTextContent( 'Series B' );
+					expect( screen.queryByTestId( 'chart-tooltip-0' ) ).not.toBeInTheDocument();
+				}
+			);
 
 			test( 'left arrow key navigates to previous data point', async () => {
 				const user = userEvent.setup();

package/src/charts/line-chart/test/zoned-date-string.test.tsx

@@ -0,0 +1,37 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-auckland.mjs
+ */
+import { render, screen } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../providers';
+import LineChart from '../line-chart';
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+// Naive day strings, the shape the Stats payload gives for day buckets.
+const data = [
+	{
+		label: 'Series A',
+		data: [
+			{ dateString: '2026-08-02', value: 1 },
+			{ dateString: '2026-08-03', value: 2 },
+			{ dateString: '2026-08-04', value: 3 },
+		],
+		options: {},
+	},
+];
+
+describe( 'dateString under a host time zone', () => {
+	it( 'dates a naive string in the host zone, not the viewer browser zone', () => {
+		render(
+			<GlobalChartsProvider locale="en-US" timeZone="Asia/Tokyo">
+				<LineChart width={ 500 } height={ 300 } withGradientFill={ false } data={ data } />
+			</GlobalChartsProvider>
+		);
+
+		const ticks = screen.getAllByText( /^[A-Z][a-z]{2} \d{1,2}$/ );
+		expect( ticks.map( tick => tick.textContent ) ).toEqual( [ 'Aug 2', 'Aug 3', 'Aug 4' ] );
+	} );
+} );

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

@@ -8,9 +8,9 @@ import type {
 	AnnotationStyles,
 	DataPoint,
 } from '../../types';
-import type { RenderTooltipParams } from '../../visx/types';
+import type { CrosshairStyle, RenderTooltipParams, XyChartTooltipProps } from '../../visx/types';
 import type { GlyphProps } from '@visx/xychart';
-import type { ReactNode, SVGProps, FC } from 'react';
+import type { ReactNode, SVGProps, FC, CSSProperties } from 'react';
 
 export type LineChartAnnotationProps = {
 	datum: DataPointDate;
@@ -41,6 +41,15 @@ export interface LineChartProps extends BaseChartProps< SeriesData[] >, SeriesVi
 	renderTooltip?: (
 		params: RenderTooltipParams< DataPointDate > & { bucketInfo?: BucketInfo }
 	) => ReactNode;
+	/**
+	 * Place the panel below the x-axis tick labels with a pointer at the datum x; horizontal bounds still apply.
+	 * @default 'auto'
+	 */
+	tooltipPlacement?: XyChartTooltipProps< DataPointDate >[ 'tooltipPlacement' ];
+	/**
+	 * Inline container styles; see Below-Axis Tooltips in stories/index.docs.mdx for content color overrides.
+	 */
+	tooltipStyle?: CSSProperties;
 	withStartGlyphs?: boolean;
 	withEndGlyphs?: boolean;
 	renderGlyph?: < Datum extends object >( props: GlyphProps< Datum > ) => ReactNode;
@@ -49,6 +58,8 @@ export interface LineChartProps extends BaseChartProps< SeriesData[] >, SeriesVi
 	withTooltipCrosshairs?: {
 		showVertical?: boolean;
 		showHorizontal?: boolean;
+		verticalStyle?: CrosshairStyle;
+		horizontalStyle?: CrosshairStyle;
 	};
 	/**
 	 * Enable drag-to-zoom on the X axis. The user drags horizontally to

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

@@ -123,18 +123,9 @@ describe( 'PieChart', () => {
 		test( 'hides labels when showLabels is false', () => {
 			renderWithTheme( { showLabels: false } );
 
-			// When showLabels is false, the chart should not display the data labels
-			// We filter out measurement elements by checking that text is not inside measurement element
-			const labelElements = screen.queryAllByText( ( content, element ) => {
-				// Check if this text element is not the measurement element
-				return (
-					( content === 'A' || content === 'B' ) &&
-					element?.id !== '__react_svg_text_measurement_id'
-				);
-			} );
-
-			// Labels should not be present in the rendered output (excluding measurement text)
-			expect( labelElements ).toHaveLength( 0 );
+			// A plain query, so this also fails if the measurement node stops being
+			// ignored — see tests/setup-text-measurement.js.
+			expect( screen.queryAllByText( /^[AB]$/ ) ).toHaveLength( 0 );
 		} );
 
 		test( 'shows labels when showLabels is explicitly true', () => {

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

@@ -200,6 +200,7 @@ interface UseKeyboardNavigationProps {
 	 * keyboard selection the way it treats a click.
 	 */
 	onActivate?: ( index: number ) => void;
+	preventTooltipScroll?: boolean;
 }
 
 export const useKeyboardNavigation = ( {
@@ -210,15 +211,20 @@ export const useKeyboardNavigation = ( {
 	chartRef,
 	totalPoints,
 	onActivate,
+	preventTooltipScroll = false,
 }: UseKeyboardNavigationProps ) => {
 	// Focus the tooltip as soon as it is rendered
 	const tooltipRef = useCallback(
 		( element: HTMLDivElement | null ) => {
 			if ( element && selectedIndex !== undefined ) {
-				element.focus();
+				if ( preventTooltipScroll ) {
+					element.focus( { preventScroll: true } );
+				} else {
+					element.focus();
+				}
 			}
 		},
-		[ selectedIndex ]
+		[ preventTooltipScroll, selectedIndex ]
 	);
 
 	// On each focus of chart, reset the selectedIndex to 0, if keyboard navigation is not already active

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

@@ -1,5 +1,6 @@
 import { Tooltip, defaultStyles } from '@visx/tooltip';
 import { useLayoutEffect, useRef, useState } from 'react';
+import type { TooltipPlacement } from '../../../visx/types';
 import type { TooltipProps } from '@visx/tooltip';
 
 type Bounds = { left: number; top: number; right: number; bottom: number };
@@ -9,9 +10,14 @@ export type BoundedTooltipProps = Omit< TooltipProps, 'left' | 'top' | 'applyPos
 	/** Anchor, in the coordinates of the positioned wrapper the box renders into. */
 	left?: number;
 	top?: number;
+	placement?: TooltipPlacement;
 };
 
 const DEFAULT_OFFSET = 10;
+const POINTER_HEIGHT = 6;
+
+const clamp = ( position: number, min: number, max: number, size: number ) =>
+	Math.min( Math.max( position, min ), Math.max( min, max - size ) );
 
 const isClipping = ( element: Element ) => {
 	const { overflow, overflowX, overflowY } = getComputedStyle( element );
@@ -33,19 +39,25 @@ const findClippingAncestor = ( wrapper: Element ): Element | null => {
 };
 
 /**
- * Where the box goes, in wrapper coordinates. Below and to the right of the
- * anchor; flipped to the other side when that side clips less, as visx's
- * `TooltipWithBounds` decides it; then clamped so the box stays inside
- * `bounds` whenever it fits at all.
+ * Where the box goes, in wrapper coordinates. Automatic placement flips to
+ * the side that clips less, then clamps inside `bounds`; below-axis placement
+ * is centered on the anchor and clamped horizontally.
+ *
+ * The flip measures against the visible part of the wrapper, its intersection
+ * with `bounds`. Only the clamp is bound by the page: a box that fits inside the
+ * chart on one side stays there, so it does not reach past the chart into
+ * siblings that paint over it.
  *
- * @param params            - Anchor, offsets, the box size and the bounds to keep inside.
+ * @param params            - Anchor, offsets, the box size and the rects to keep inside.
  * @param params.left       - Anchor x, in wrapper coordinates.
  * @param params.top        - Anchor y, in wrapper coordinates.
  * @param params.offsetLeft - Gap between the anchor and the box, horizontally.
  * @param params.offsetTop  - Gap between the anchor and the box, vertically.
  * @param params.box        - Rendered size of the box.
+ * @param params.wrapper    - The wrapper's own edges, in wrapper coordinates.
+ * @param params.placement  - Fixed below-axis placement or automatic flipping.
  * @param params.bounds     - Edges the box must keep inside, in wrapper coordinates.
- * @return The box's top-left corner, rounded to whole pixels.
+ * @return The box's top-left corner; fixed placement preserves the axis's subpixel y.
  */
 export const getBoundedPosition = ( {
 	left,
@@ -53,31 +65,53 @@ export const getBoundedPosition = ( {
 	offsetLeft,
 	offsetTop,
 	box,
+	wrapper,
 	bounds,
+	placement = 'auto',
 }: {
 	left: number;
 	top: number;
 	offsetLeft: number;
 	offsetTop: number;
 	box: Size;
+	wrapper: Bounds;
 	bounds: Bounds;
+	placement?: BoundedTooltipProps[ 'placement' ];
 } ) => {
+	if ( placement === 'below-axis' ) {
+		return {
+			x: Math.round( clamp( left - box.width / 2, bounds.left, bounds.right, box.width ) ),
+			y: top + POINTER_HEIGHT,
+		};
+	}
+
+	// The part of the wrapper that is not cut off: the flip keeps the box inside it.
+	const fit = {
+		left: Math.max( wrapper.left, bounds.left ),
+		top: Math.max( wrapper.top, bounds.top ),
+		right: Math.min( wrapper.right, bounds.right ),
+		bottom: Math.min( wrapper.bottom, bounds.bottom ),
+	};
+
 	const rightX = left + offsetLeft;
 	const leftX = left - offsetLeft - box.width;
-	const rightOverflow = rightX + box.width - bounds.right;
-	const leftOverflow = bounds.left - leftX;
+	const rightOverflow = rightX + box.width - fit.right;
+	const leftOverflow = fit.left - leftX;
 	let x = rightOverflow > 0 && rightOverflow > leftOverflow ? leftX : rightX;
 
 	const downY = top + offsetTop;
 	const upY = top - offsetTop - box.height;
-	const downOverflow = downY + box.height - bounds.bottom;
-	const upOverflow = bounds.top - upY;
+	const downOverflow = downY + box.height - fit.bottom;
+	const upOverflow = fit.top - upY;
 	let y = downOverflow > 0 && downOverflow > upOverflow ? upY : downY;
 
-	x = Math.min( Math.max( x, bounds.left ), Math.max( bounds.left, bounds.right - box.width ) );
-	y = Math.min( Math.max( y, bounds.top ), Math.max( bounds.top, bounds.bottom - box.height ) );
+	x = clamp( x, bounds.left, bounds.right, box.width );
+	y = clamp( y, bounds.top, bounds.bottom, box.height );
 
-	return { x: Math.round( x ), y: Math.round( y ) };
+	return {
+		x: Math.round( x ),
+		y: Math.round( y ),
+	};
 };
 
 /**
@@ -88,7 +122,8 @@ export const getBoundedPosition = ( {
  * alone would let the box spill into an `overflow: hidden` card and be cut off.
  *
  * Re-measures on every render, so a box whose content changes width between
- * two hovers is placed for its current size.
+ * two hovers is placed for its current size. See `getBoundedPosition` for the
+ * below-axis exception.
  *
  * @param props            - visx `Tooltip` props.
  * @param props.left       - Anchor x, in wrapper coordinates.
@@ -98,6 +133,7 @@ export const getBoundedPosition = ( {
  * @param props.style      - Box styles; visx's defaults unless `unstyled`.
  * @param props.unstyled   - Skip `style` and leave the box bare.
  * @param props.children   - Box content.
+ * @param props.placement  - Fixed below-axis placement or automatic flipping.
  * @return The tooltip box.
  */
 export const BoundedTooltip = ( {
@@ -108,6 +144,7 @@ export const BoundedTooltip = ( {
 	style = defaultStyles,
 	unstyled = false,
 	children,
+	placement = 'auto',
 	...rest
 }: BoundedTooltipProps ) => {
 	const nodeRef = useRef< HTMLDivElement >( null );
@@ -136,7 +173,9 @@ export const BoundedTooltip = ( {
 			top,
 			offsetLeft,
 			offsetTop,
+			placement,
 			box: { width: own.width, height: own.height },
+			wrapper: { left: 0, top: 0, right: wrapperRect.width, bottom: wrapperRect.height },
 			bounds: {
 				left: clipRect.left - wrapperRect.left,
 				top: clipRect.top - wrapperRect.top,
@@ -148,10 +187,10 @@ export const BoundedTooltip = ( {
 			current && current.x === next.x && current.y === next.y ? current : next
 		);
 		// `children` re-runs the measurement when the content, and so the box size, changes.
-	}, [ left, top, offsetLeft, offsetTop, children ] );
+	}, [ left, top, offsetLeft, offsetTop, children, placement ] );
 
 	const x = position?.x ?? left + offsetLeft;
-	const y = position?.y ?? top + offsetTop;
+	const y = position?.y ?? top + ( placement === 'below-axis' ? POINTER_HEIGHT : offsetTop );
 
 	return (
 		<Tooltip
@@ -166,6 +205,22 @@ export const BoundedTooltip = ( {
 			} }
 			{ ...rest }
 		>
+			{ placement === 'below-axis' && (
+				<span
+					aria-hidden="true"
+					data-testid="tooltip-axis-pointer"
+					style={ {
+						position: 'absolute',
+						left: left - x - POINTER_HEIGHT,
+						top: -POINTER_HEIGHT,
+						width: POINTER_HEIGHT * 2,
+						height: POINTER_HEIGHT,
+						background: 'inherit',
+						clipPath: 'polygon(50% 0, 100% 100%, 0 100%)',
+						pointerEvents: 'none',
+					} }
+				/>
+			) }
 			{ children }
 		</Tooltip>
 	);