@automattic/charts 3.2.0 → 4.0.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 } }
@@ -279,6 +280,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,172 @@
+import { Tooltip, defaultStyles } from '@visx/tooltip';
+import { useLayoutEffect, useRef, useState } from 'react';
+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;
+};
+
+const DEFAULT_OFFSET = 10;
+
+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. 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.
+ *
+ * @param params            - Anchor, offsets, the box size and the bounds 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.bounds     - Edges the box must keep inside, in wrapper coordinates.
+ * @return The box's top-left corner, rounded to whole pixels.
+ */
+export const getBoundedPosition = ( {
+	left,
+	top,
+	offsetLeft,
+	offsetTop,
+	box,
+	bounds,
+}: {
+	left: number;
+	top: number;
+	offsetLeft: number;
+	offsetTop: number;
+	box: Size;
+	bounds: Bounds;
+} ) => {
+	const rightX = left + offsetLeft;
+	const leftX = left - offsetLeft - box.width;
+	const rightOverflow = rightX + box.width - bounds.right;
+	const leftOverflow = bounds.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;
+	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 ) );
+
+	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.
+ *
+ * @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.
+ * @return The tooltip box.
+ */
+export const BoundedTooltip = ( {
+	left = 0,
+	top = 0,
+	offsetLeft = DEFAULT_OFFSET,
+	offsetTop = DEFAULT_OFFSET,
+	style = defaultStyles,
+	unstyled = false,
+	children,
+	...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,
+			box: { width: own.width, height: own.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 ] );
+
+	const x = position?.x ?? left + offsetLeft;
+	const y = position?.y ?? top + 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 }
+		>
+			{ children }
+		</Tooltip>
+	);
+};

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

@@ -42,12 +42,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)' );

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

@@ -0,0 +1,129 @@
+import { render, screen } from '@testing-library/react';
+import { BoundedTooltip, getBoundedPosition } from '../private/bounded-tooltip';
+
+const BOX = { width: 208, height: 36 };
+const OFFSETS = { offsetLeft: 10, offsetTop: 10 };
+
+describe( 'getBoundedPosition', () => {
+	test( 'sits below and to the right of the anchor when that fits', () => {
+		expect(
+			getBoundedPosition( {
+				left: 40,
+				top: 20,
+				...OFFSETS,
+				box: BOX,
+				bounds: { left: 0, top: 0, right: 600, bottom: 300 },
+			} )
+		).toEqual( { x: 50, y: 30 } );
+	} );
+
+	test( 'flips to the other side when the near side clips more', () => {
+		expect(
+			getBoundedPosition( {
+				left: 500,
+				top: 280,
+				...OFFSETS,
+				box: BOX,
+				bounds: { left: 0, top: 0, right: 600, bottom: 300 },
+			} )
+		).toEqual( { x: 282, y: 234 } );
+	} );
+
+	test( 'pins the box to the edge when neither side fits, instead of spilling', () => {
+		// A 208px box mid-way across a 346px plot: neither side fits, so the box
+		// keeps the near side and parks at the right edge instead of spilling.
+		expect(
+			getBoundedPosition( {
+				left: 173,
+				top: 50,
+				...OFFSETS,
+				box: BOX,
+				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.
+		expect(
+			getBoundedPosition( {
+				left: 173,
+				top: 50,
+				...OFFSETS,
+				box: BOX,
+				bounds: { left: -40, top: -60, right: 360, bottom: 200 },
+			} )
+		).toEqual( { x: -40, y: 60 } );
+	} );
+} );
+
+const rect = ( left: number, top: number, width: number, height: number ) =>
+	( {
+		left,
+		top,
+		width,
+		height,
+		right: left + width,
+		bottom: top + height,
+		x: left,
+		y: top,
+		toJSON: () => ( {} ),
+	} ) as DOMRect;
+
+describe( 'BoundedTooltip', () => {
+	afterEach( () => {
+		jest.restoreAllMocks();
+	} );
+
+	test( 'keeps the box inside an overflow-hidden ancestor that is wider than the wrapper', () => {
+		// Card at x=400 (400 wide, overflow hidden); plot wrapper at x=440, 346 wide.
+		jest.spyOn( Element.prototype, 'getBoundingClientRect' ).mockImplementation( function (
+			this: Element
+		) {
+			if ( this.classList.contains( 'visx-tooltip' ) ) {
+				return rect( 0, 0, 208, 36 );
+			}
+			if ( this.getAttribute( 'data-testid' ) === 'card' ) {
+				return rect( 400, 100, 400, 400 );
+			}
+			return rect( 440, 160, 346, 200 );
+		} );
+
+		render(
+			<div data-testid="card" style={ { overflow: 'hidden' } }>
+				<div style={ { position: 'relative' } }>
+					<BoundedTooltip left={ 173 } top={ 50 } data-testid="box">
+						content
+					</BoundedTooltip>
+				</div>
+			</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)' } );
+	} );
+
+	test( 'falls back to the viewport when nothing clips', () => {
+		jest.spyOn( Element.prototype, 'getBoundingClientRect' ).mockImplementation( function (
+			this: Element
+		) {
+			return this.classList.contains( 'visx-tooltip' )
+				? rect( 0, 0, 208, 36 )
+				: rect( 900, 0, 346, 200 );
+		} );
+
+		render(
+			<div style={ { position: 'relative' } }>
+				<BoundedTooltip left={ 173 } top={ 50 } data-testid="box">
+					content
+				</BoundedTooltip>
+			</div>
+		);
+
+		// JSDOM's viewport is 1024px wide and the wrapper starts at 900: the box
+		// flips left of the anchor and stops at the viewport's right edge.
+		expect( screen.getByTestId( 'box' ) ).toHaveStyle( { transform: 'translate(-84px, 60px)' } );
+	} );
+} );