@automattic/charts 3.2.0 → 4.1.0

package/src/charts/sparkline/test/sparkline.test.tsx

@@ -2,51 +2,39 @@
 
 import { render, screen } from '@testing-library/react';
 import { Sparkline, SparklineUnresponsive } from '../';
-import { GlobalChartsProvider, defaultTheme } from '../../../providers';
-import { customTheme } from '../../../stories/theme-config';
-
-const THEME_MAP = {
-	default: defaultTheme,
-	custom: customTheme,
-};
+import { GlobalChartsProvider } from '../../../providers';
 
 describe( 'Sparkline', () => {
 	const defaultData = [ 10, 25, 15, 30, 22, 35 ];
 
-	const renderWithTheme = ( props = {}, themeName = 'default' ) => {
-		const theme = THEME_MAP[ themeName ];
-
-		return render(
-			<GlobalChartsProvider theme={ theme }>
+	const renderResponsive = ( props = {} ) =>
+		render(
+			<GlobalChartsProvider>
 				<Sparkline data={ defaultData } { ...props } />
 			</GlobalChartsProvider>
 		);
-	};
-
-	const renderUnwrappedWithTheme = ( props = {}, themeName = 'default' ) => {
-		const theme = THEME_MAP[ themeName ];
 
-		return render(
-			<GlobalChartsProvider theme={ theme }>
+	const renderUnwrapped = ( props = {} ) =>
+		render(
+			<GlobalChartsProvider>
 				<SparklineUnresponsive data={ defaultData } { ...props } />
 			</GlobalChartsProvider>
 		);
-	};
 
 	describe( 'Basic Rendering', () => {
 		test( 'renders sparkline with valid data', () => {
-			renderUnwrappedWithTheme();
+			renderUnwrapped();
 			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
 		} );
 
 		test( 'applies custom className', () => {
-			renderUnwrappedWithTheme( { className: 'custom-class' } );
+			renderUnwrapped( { className: 'custom-class' } );
 			const sparkline = screen.getByTestId( 'sparkline' );
 			expect( sparkline ).toHaveClass( 'custom-class' );
 		} );
 
 		test( 'renders responsive variant', () => {
-			renderWithTheme();
+			renderResponsive();
 			// Responsive variant wraps in a div, so sparkline should exist
 			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
 		} );
@@ -54,12 +42,12 @@ describe( 'Sparkline', () => {
 
 	describe( 'Edge Cases', () => {
 		test( 'handles empty data array', () => {
-			renderUnwrappedWithTheme( { data: [] } );
+			renderUnwrapped( { data: [] } );
 			expect( screen.getByTestId( 'sparkline-empty' ) ).toBeInTheDocument();
 		} );
 
 		test( 'handles single data point', () => {
-			renderUnwrappedWithTheme( { data: [ 42 ] } );
+			renderUnwrapped( { data: [ 42 ] } );
 			const singlePoint = screen.getByTestId( 'sparkline-single-point' );
 			expect( singlePoint ).toBeInTheDocument();
 			// Should render a circle
@@ -68,51 +56,51 @@ describe( 'Sparkline', () => {
 		} );
 
 		test( 'handles two data points', () => {
-			renderUnwrappedWithTheme( { data: [ 10, 20 ] } );
+			renderUnwrapped( { data: [ 10, 20 ] } );
 			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
 		} );
 
 		test( 'handles negative values', () => {
-			renderUnwrappedWithTheme( { data: [ -10, -5, 0, 5, 10 ] } );
+			renderUnwrapped( { data: [ -10, -5, 0, 5, 10 ] } );
 			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
 		} );
 
 		test( 'handles flat line (all same values)', () => {
-			renderUnwrappedWithTheme( { data: [ 50, 50, 50, 50 ] } );
+			renderUnwrapped( { data: [ 50, 50, 50, 50 ] } );
 			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
 		} );
 	} );
 
 	describe( 'Styling Props', () => {
 		test( 'applies custom color', () => {
-			const { container } = renderUnwrappedWithTheme( { color: '#ff0000' } );
+			const { container } = renderUnwrapped( { color: '#ff0000' } );
 			// Check that SVG contains a path with the custom color
 			const path = container.querySelector( 'path[stroke="#ff0000"]' );
 			expect( path ).toBeInTheDocument();
 		} );
 
 		test( 'applies custom stroke width', () => {
-			const { container } = renderUnwrappedWithTheme( { strokeWidth: 4 } );
+			const { container } = renderUnwrapped( { strokeWidth: 4 } );
 			const path = container.querySelector( 'path[stroke-width="4"]' );
 			expect( path ).toBeInTheDocument();
 		} );
 
 		test( 'renders with gradient fill by default', () => {
-			const { container } = renderUnwrappedWithTheme();
+			const { container } = renderUnwrapped();
 			// Check for LinearGradient in SVG
 			const gradient = container.querySelector( 'linearGradient' );
 			expect( gradient ).toBeInTheDocument();
 		} );
 
 		test( 'disables gradient fill when withGradientFill is false', () => {
-			const { container } = renderUnwrappedWithTheme( { withGradientFill: false } );
+			const { container } = renderUnwrapped( { withGradientFill: false } );
 			// Should not have gradient
 			const gradient = container.querySelector( 'linearGradient' );
 			expect( gradient ).not.toBeInTheDocument();
 		} );
 
 		test( 'applies custom gradient config', () => {
-			const { container } = renderUnwrappedWithTheme( {
+			const { container } = renderUnwrapped( {
 				gradient: {
 					from: '#00ff00',
 					to: '#0000ff',
@@ -130,43 +118,28 @@ describe( 'Sparkline', () => {
 
 	describe( 'Dimensions', () => {
 		test( 'applies default dimensions', () => {
-			const { container } = renderUnwrappedWithTheme();
+			const { container } = renderUnwrapped();
 			const svg = container.querySelector( 'svg' );
 			expect( svg ).toHaveAttribute( 'width', '100' );
 			expect( svg ).toHaveAttribute( 'height', '40' );
 		} );
 
 		test( 'applies custom dimensions', () => {
-			const { container } = renderUnwrappedWithTheme( { width: 200, height: 80 } );
+			const { container } = renderUnwrapped( { width: 200, height: 80 } );
 			const svg = container.querySelector( 'svg' );
 			expect( svg ).toHaveAttribute( 'width', '200' );
 			expect( svg ).toHaveAttribute( 'height', '80' );
 		} );
 
 		test( 'applies custom margin', () => {
-			renderUnwrappedWithTheme( { margin: { top: 10, right: 10, bottom: 10, left: 10 } } );
+			renderUnwrapped( { margin: { top: 10, right: 10, bottom: 10, left: 10 } } );
 			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
 		} );
 	} );
 
-	describe( 'Theme Integration', () => {
-		test( 'uses default theme colors', () => {
-			const { container } = renderUnwrappedWithTheme( {}, 'default' );
-			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
-			// Should render with theme color if no color prop provided
-			const path = container.querySelector( 'path[stroke]' );
-			expect( path ).toBeInTheDocument();
-		} );
-
-		test( 'uses custom theme colors', () => {
-			const { container } = renderUnwrappedWithTheme( {}, 'custom' );
-			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
-			const path = container.querySelector( 'path[stroke]' );
-			expect( path ).toBeInTheDocument();
-		} );
-
-		test( 'color prop overrides theme color', () => {
-			const { container } = renderUnwrappedWithTheme( { color: '#custom' }, 'default' );
+	describe( 'Color', () => {
+		test( 'color prop overrides the palette default', () => {
+			const { container } = renderUnwrapped( { color: '#custom' } );
 			const path = container.querySelector( 'path[stroke="#custom"]' );
 			expect( path ).toBeInTheDocument();
 		} );
@@ -175,17 +148,17 @@ describe( 'Sparkline', () => {
 	describe( 'Data Transformation', () => {
 		test( 'handles large datasets', () => {
 			const largeData = Array.from( { length: 100 }, ( _, i ) => i * 2 );
-			renderUnwrappedWithTheme( { data: largeData } );
+			renderUnwrapped( { data: largeData } );
 			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
 		} );
 
 		test( 'handles small datasets', () => {
-			renderUnwrappedWithTheme( { data: [ 1, 2 ] } );
+			renderUnwrapped( { data: [ 1, 2 ] } );
 			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
 		} );
 
 		test( 'handles data with large range', () => {
-			renderUnwrappedWithTheme( { data: [ 1, 1000, 50, 500 ] } );
+			renderUnwrapped( { data: [ 1, 1000, 50, 500 ] } );
 			expect( screen.getByTestId( 'sparkline' ) ).toBeInTheDocument();
 		} );
 	} );

package/src/charts/sparkline/types.ts

@@ -6,7 +6,7 @@ export type GradientConfig = {
 	 */
 	from?: string;
 	/**
-	 * End color for gradient (defaults to theme backgroundColor)
+	 * End color for gradient (defaults to `--a8c-charts-color-background`)
 	 */
 	to?: string;
 	/**

package/src/components/legend/private/base-legend.module.scss

@@ -3,14 +3,14 @@
 }
 
 .legend-item {
-	font-size: var(--wpds-typography-font-size-md, 13px);
+	font-size: var(--wpds-typography-font-size-md);
 
 	&--interactive {
 		cursor: pointer;
 		user-select: none;
 		transition:
-			opacity var(--wpds-motion-duration-md, 200ms)
-			var(--wpds-motion-easing-subtle, cubic-bezier(0.15, 0, 0.15, 1));
+			opacity var(--wpds-motion-duration-md)
+			var(--wpds-motion-easing-subtle);
 
 		&:hover {
 			opacity: 0.8;
@@ -19,7 +19,7 @@
 		&:focus {
 			outline: 2px solid currentColor;
 			outline-offset: 2px;
-			border-radius: var(--wpds-border-radius-md, 4px);
+			border-radius: var(--wpds-border-radius-md);
 		}
 
 		&:focus:not(:focus-visible) {
@@ -36,6 +36,10 @@
 	}
 }
 
+.legend-item-label {
+	color: var(--a8c-charts-color-label);
+}
+
 .legend-item-text {
 
 	&--wrap {
@@ -54,6 +58,6 @@
 }
 
 .legend-item-value {
-	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
+	font-weight: var(--wpds-typography-font-weight-emphasis);
 	flex-shrink: 0; // Prevent value from shrinking when text is ellipsized
 }

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

@@ -1,10 +1,10 @@
-import { Tooltip, TooltipContext } from '@visx/xychart';
+import { TooltipContext } from '@visx/xychart';
 import clsx from 'clsx';
 import { useContext, useEffect, useCallback, useMemo, useRef } from 'react';
-import { useGlobalChartsTheme } from '../../providers';
-import { useChartScopeElement } from '../../providers/chart-scope';
-import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
+import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
+import { useChartScopeElement, useStandaloneScopeClass } from '../../providers/chart-scope';
 import { resolveCssVariable } from '../../utils';
+import { XyChartTooltip } from './xy-chart-tooltip';
 import type { SeriesData, DataPointDate } from '../../types';
 import type { RenderTooltipParams, XyChartTooltipProps } from '../../visx/types';
 import type { ReactNode } from 'react';
@@ -54,15 +54,16 @@ export const AccessibleTooltip: React.FC< AccessibleTooltipProps > = ( {
 } ) => {
 	const tooltipContext = useContext( TooltipContext );
 	const scopeElement = useChartScopeElement();
-	const gridStroke = useGlobalChartsTheme().gridStyles?.stroke;
 
-	// The crosshair is painted in a portal outside the scope, so it needs a resolved color; see TOKENS.md#the-svg-bridge.
+	// The stroke is read at the scope element, which a consumer can set outside the chart's own ancestors; see TOKENS.md#the-svg-bridge.
 	const crosshairStroke = useMemo( () => {
-		const stroke = gridStroke ? resolveCssVariable( gridStroke, scopeElement ) : null;
+		const stroke = resolveCssVariable( CATALOG_POINTERS.grid, scopeElement );
 
 		// Passing `stroke: undefined` would erase the crosshair: it overrides visx's own value, and SVG's initial `stroke` is `none`.
 		return stroke ? { stroke } : undefined;
-	}, [ gridStroke, scopeElement ] );
+	}, [ scopeElement ] );
+
+	const standaloneScopeClass = useStandaloneScopeClass();
 
 	const tooltipData = useMemo( () => {
 		if ( mode !== 'individual' ) return [];
@@ -156,7 +157,7 @@ export const AccessibleTooltip: React.FC< AccessibleTooltipProps > = ( {
 						tabIndex={ -1 }
 						role="tooltip"
 						aria-atomic="true"
-						className={ clsx( CHART_SCOPE_CLASS, keyboardFocusedClassName ) }
+						className={ clsx( standaloneScopeClass, keyboardFocusedClassName ) }
 						data-testid={ `chart-tooltip-${ selectedIndex }` }
 						key={ `chart-tooltip-${ selectedIndex }` }
 					>
@@ -166,15 +167,15 @@ export const AccessibleTooltip: React.FC< AccessibleTooltipProps > = ( {
 			}
 
 			return (
-				<div className={ CHART_SCOPE_CLASS } role="tooltip" aria-live="polite">
+				<div className={ standaloneScopeClass } role="tooltip" aria-live="polite">
 					{ tooltipContent }
 				</div>
 			);
 		};
-	}, [ renderTooltip, selectedIndex, tooltipRef, keyboardFocusedClassName ] );
+	}, [ renderTooltip, selectedIndex, tooltipRef, keyboardFocusedClassName, standaloneScopeClass ] );
 
 	return (
-		<Tooltip
+		<XyChartTooltip
 			{ ...props }
 			verticalCrosshairStyle={ { ...crosshairStroke, ...verticalCrosshairStyle } }
 			horizontalCrosshairStyle={ { ...crosshairStroke, ...horizontalCrosshairStyle } }
@@ -199,6 +200,7 @@ interface UseKeyboardNavigationProps {
 	 * keyboard selection the way it treats a click.
 	 */
 	onActivate?: ( index: number ) => void;
+	preventTooltipScroll?: boolean;
 }
 
 export const useKeyboardNavigation = ( {
@@ -209,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
@@ -279,6 +286,3 @@ export const useKeyboardNavigation = ( {
 		onChartKeyDown,
 	};
 };
-
-// Re-export the base Tooltip for backwards compatibility
-export { Tooltip };

package/src/components/tooltip/base-tooltip.module.scss

@@ -1,13 +1,13 @@
 .tooltip {
-	padding: var(--wpds-dimension-padding-sm, 8px);
+	padding: var(--wpds-dimension-padding-sm);
 	// No WPDS token fits a translucent dark tooltip surface:
 	// bg-interactive-neutral-strong is opaque, and there is no
 	// white-on-dark content foreground token. The role carries the
 	// hardcoded translucent value as its fallback.
 	background-color: var(--a8c-charts-color-tooltip-surface, rgba(0, 0, 0, 0.85));
 	color: #fff;
-	border-radius: var(--wpds-border-radius-md, 4px);
-	font-size: var(--wpds-typography-font-size-md, 13px);
+	border-radius: var(--wpds-border-radius-md);
+	font-size: var(--wpds-typography-font-size-md);
 	box-shadow: var(--a8c-charts-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005);
 	position: absolute;
 	pointer-events: none;

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

@@ -0,0 +1,227 @@
+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 };
+type Size = { width: number; height: number };
+
+export type BoundedTooltipProps = Omit< TooltipProps, 'left' | 'top' | 'applyPositionStyle' > & {
+	/** 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 );
+	return [ overflow, overflowX, overflowY ].some( value => value && value !== 'visible' );
+};
+
+// The first ancestor that cuts its overflow off. The box may leave the chart
+// wrapper but never this element, which is what a body-level portal used to
+// guarantee by never being inside one.
+const findClippingAncestor = ( wrapper: Element ): Element | null => {
+	let element = wrapper.parentElement;
+	while ( element && element !== document.body ) {
+		if ( isClipping( element ) ) {
+			return element;
+		}
+		element = element.parentElement;
+	}
+	return null;
+};
+
+/**
+ * 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 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; fixed placement preserves the axis's subpixel y.
+ */
+export const getBoundedPosition = ( {
+	left,
+	top,
+	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 - 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 - fit.bottom;
+	const upOverflow = fit.top - upY;
+	let y = downOverflow > 0 && downOverflow > upOverflow ? upY : downY;
+
+	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 ),
+	};
+};
+
+/**
+ * visx's `Tooltip`, positioned like its `TooltipWithBounds` but kept inside the
+ * nearest clipping ancestor — or the viewport when there is none — rather than
+ * inside its own parent. Rendered in-tree, a tooltip's parent is the chart
+ * wrapper, which is often narrower than the box; measuring against the parent
+ * 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. See `getBoundedPosition` for the
+ * below-axis exception.
+ *
+ * @param props            - visx `Tooltip` props.
+ * @param props.left       - Anchor x, in wrapper coordinates.
+ * @param props.top        - Anchor y, in wrapper coordinates.
+ * @param props.offsetLeft - Gap between the anchor and the box, horizontally.
+ * @param props.offsetTop  - Gap between the anchor and the box, vertically.
+ * @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 = ( {
+	left = 0,
+	top = 0,
+	offsetLeft = DEFAULT_OFFSET,
+	offsetTop = DEFAULT_OFFSET,
+	style = defaultStyles,
+	unstyled = false,
+	children,
+	placement = 'auto',
+	...rest
+}: BoundedTooltipProps ) => {
+	const nodeRef = useRef< HTMLDivElement >( null );
+	const clipRef = useRef< { wrapper: Element; clip: Element | null } | null >( null );
+	const [ position, setPosition ] = useState< { x: number; y: number } | null >( null );
+
+	useLayoutEffect( () => {
+		const node = nodeRef.current;
+		const wrapper = node?.parentElement;
+		if ( ! node || ! wrapper ) {
+			return;
+		}
+		if ( clipRef.current?.wrapper !== wrapper ) {
+			clipRef.current = { wrapper, clip: findClippingAncestor( wrapper ) };
+		}
+		const own = node.getBoundingClientRect();
+		const wrapperRect = wrapper.getBoundingClientRect();
+		const clipRect = clipRef.current.clip?.getBoundingClientRect() ?? {
+			left: 0,
+			top: 0,
+			right: window.innerWidth,
+			bottom: window.innerHeight,
+		};
+		const next = getBoundedPosition( {
+			left,
+			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,
+				right: clipRect.right - wrapperRect.left,
+				bottom: clipRect.bottom - wrapperRect.top,
+			},
+		} );
+		setPosition( current =>
+			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, placement ] );
+
+	const x = position?.x ?? left + offsetLeft;
+	const y = position?.y ?? top + ( placement === 'below-axis' ? POINTER_HEIGHT : offsetTop );
+
+	return (
+		<Tooltip
+			ref={ nodeRef }
+			data-testid="bounded-tooltip"
+			style={ {
+				position: 'absolute',
+				left: 0,
+				top: 0,
+				transform: `translate(${ x }px, ${ y }px)`,
+				...( ! unstyled && style ),
+			} }
+			{ ...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>
+	);
+};

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 }
 		/>
@@ -42,12 +43,11 @@ const openTooltip = async () => {
 	screen.getByRole( 'grid', { name: /line chart/i } ).focus();
 	await user.keyboard( '{ArrowRight}' );
 
-	// eslint-disable-next-line testing-library/no-node-access -- visx owns the crosshair and hardcodes its class name, so there is no attribute to reach it by.
-	return document.querySelector( '.visx-crosshair-vertical line' );
+	return screen.getByTestId( 'xy-chart-tooltip-crosshair-vertical' );
 };
 
 describe( 'AccessibleTooltip', () => {
-	// The crosshair is painted in a portal outside the scope element; see TOKENS.md#the-svg-bridge.
+	// The stroke is read at the scope element, not inherited through the DOM; see TOKENS.md#the-svg-bridge.
 	it( 'reads the grid role from the scope element', async () => {
 		const scope = document.createElement( 'div' );
 		scope.style.setProperty( '--a8c-charts-color-grid', 'rgb(1, 2, 3)' );
@@ -60,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();