@automattic/charts 4.6.0 → 4.8.0

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

@@ -0,0 +1,336 @@
+import { DataContext, TooltipContext } from '@visx/xychart';
+import { useCallback, useContext, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { TooltipBox } from '../tooltip-box';
+import { BoundedTooltip, TOOLTIP_Z_INDEX } from './bounded-tooltip';
+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';
+// Portal-era options, accepted for compatibility and dropped before the box
+// renders: it sits in the chart wrapper and moves with it, and nothing
+// measures it any more.
+const PORTAL_OPTIONS = new Set( [ 'scroll', 'debounce', 'resizeObserverPolyfill' ] );
+
+type ScaleFn = ( value: unknown ) => number | undefined;
+
+const isValidNumber = ( value: unknown ): value is number =>
+	typeof value === 'number' && Number.isFinite( value );
+
+// Band scales place a datum at the start of its band; snapping targets the band's centre.
+// A d3 scale is a function that carries `bandwidth` as a property.
+const scaleBandwidth = ( scale: unknown ): number => {
+	const bandwidth = ( scale as { bandwidth?: unknown } | null | undefined )?.bandwidth;
+	return typeof bandwidth === 'function' ? Number( bandwidth() ) : 0;
+};
+
+const DefaultGlyph = < Datum extends object >( {
+	x,
+	y,
+	size,
+	color,
+	glyphStyle,
+	seriesKey,
+}: Omit< RenderTooltipGlyphProps< Datum >, 'key' > & { seriesKey: string } ) => {
+	const { theme } = useContext( DataContext ) || {};
+
+	return (
+		<circle
+			data-testid={ `xy-chart-tooltip-glyph-${ seriesKey }` }
+			cx={ x }
+			cy={ y }
+			r={ size }
+			fill={ color }
+			stroke={ theme?.backgroundColor }
+			strokeWidth={ CROSSHAIR_STROKE_WIDTH }
+			paintOrder="fill"
+			{ ...glyphStyle }
+		/>
+	);
+};
+
+const defaultRenderGlyph = < Datum extends object >( {
+	key,
+	...props
+}: RenderTooltipGlyphProps< Datum > ) => (
+	<DefaultGlyph key={ key } seriesKey={ key } { ...props } />
+);
+
+type XyChartTooltipContentProps< Datum extends object > = XyChartTooltipProps< Datum > & {
+	tooltipContext: TooltipContextType< Datum >;
+	/** The SVG's HTML parent once found. The box waits for it; the SVG overlay does not. */
+	container: HTMLElement | null;
+};
+
+const XyChartTooltipContent = < Datum extends object >( {
+	tooltipContext,
+	container,
+	renderTooltip,
+	renderGlyph = defaultRenderGlyph,
+	glyphStyle,
+	snapTooltipToDatumX = false,
+	snapTooltipToDatumY = false,
+	showVerticalCrosshair = false,
+	showHorizontalCrosshair = false,
+	showDatumGlyph = false,
+	showSeriesGlyphs = false,
+	verticalCrosshairStyle,
+	horizontalCrosshairStyle,
+	detectBounds = true,
+	tooltipPlacement = 'auto',
+	tooltipAnchorTop,
+	zIndex = TOOLTIP_Z_INDEX,
+	style,
+	...rest
+}: XyChartTooltipContentProps< Datum > ) => {
+	const tooltipProps = Object.fromEntries(
+		Object.entries( rest ).filter( ( [ key ] ) => ! PORTAL_OPTIONS.has( key ) )
+	) as Omit< typeof rest, 'scroll' | 'debounce' | 'resizeObserverPolyfill' >;
+	const {
+		colorScale,
+		theme,
+		innerHeight = 0,
+		innerWidth = 0,
+		margin,
+		xScale,
+		yScale,
+		dataRegistry,
+	} = useContext( DataContext ) || {};
+
+	const tooltipContent = renderTooltip ? renderTooltip( { ...tooltipContext, colorScale } ) : null;
+	if ( tooltipContent == null ) {
+		return null;
+	}
+
+	const scaleX = xScale as ScaleFn | undefined;
+	const scaleY = yScale as ScaleFn | undefined;
+
+	// Datum position in SVG coordinates, from the accessors the series registered.
+	const getDatumLeftTop = ( key: string, datum: Datum ) => {
+		const entry = dataRegistry?.get( key );
+		const left =
+			scaleX && entry?.xAccessor
+				? Number( scaleX( entry.xAccessor( datum ) ) ) + scaleBandwidth( xScale ) / 2
+				: undefined;
+		const top =
+			scaleY && entry?.yAccessor
+				? Number( scaleY( entry.yAccessor( datum ) ) ) + scaleBandwidth( yScale ) / 2
+				: undefined;
+		return { left, top };
+	};
+
+	const nearestDatum = tooltipContext.tooltipData?.nearestDatum;
+	let { tooltipLeft, tooltipTop } = tooltipContext;
+
+	if (
+		nearestDatum &&
+		( snapTooltipToDatumX || snapTooltipToDatumY || tooltipPlacement === 'below-axis' )
+	) {
+		const { left, top } = getDatumLeftTop( nearestDatum.key, nearestDatum.datum );
+		if ( ( snapTooltipToDatumX || tooltipPlacement === 'below-axis' ) && isValidNumber( left ) ) {
+			tooltipLeft = left;
+		}
+		if ( snapTooltipToDatumY && isValidNumber( top ) ) {
+			tooltipTop = top;
+		}
+	}
+
+	const glyphs: ReactNode[] = [];
+	if ( showDatumGlyph || showSeriesGlyphs ) {
+		const size = Number( glyphStyle?.radius ?? DEFAULT_GLYPH_RADIUS );
+		const labelColor = theme?.htmlLabel?.color ?? FALLBACK_COLOR;
+		// visx colours a lone nearest-datum glyph like the gridlines and series glyphs like labels.
+		const fallbackColor = showSeriesGlyphs
+			? labelColor
+			: ( theme?.gridStyles?.stroke ?? labelColor );
+		let entries: Array< { key: string; datum: Datum; index: number } > = [];
+		if ( showSeriesGlyphs ) {
+			entries = Object.values( tooltipContext.tooltipData?.datumByKey ?? {} );
+		} else if ( nearestDatum ) {
+			entries = [ nearestDatum ];
+		}
+
+		for ( const { key, datum, index } of entries ) {
+			const { left, top } = getDatumLeftTop( key, datum );
+			if ( ! isValidNumber( left ) || ! isValidNumber( top ) ) {
+				continue;
+			}
+			// The group carries the position and the renderer draws at the origin,
+			// as with visx's portal: a renderer that ignores `x` and `y` still lands
+			// on its datum.
+			glyphs.push(
+				<g
+					key={ key }
+					className="visx-tooltip-glyph"
+					data-testid={ `xy-chart-tooltip-glyph-group-${ key }` }
+					transform={ `translate(${ left }, ${ top })` }
+				>
+					{ renderGlyph( {
+						key,
+						color: colorScale?.( key ) ?? fallbackColor,
+						datum,
+						index,
+						size,
+						x: 0,
+						y: 0,
+						glyphStyle,
+						isNearestDatum: nearestDatum?.key === key,
+					} ) }
+				</g>
+			);
+		}
+	}
+
+	const crosshairStroke = theme?.gridStyles?.stroke ?? theme?.htmlLabel?.color ?? FALLBACK_COLOR;
+	const marginTop = margin?.top ?? 0;
+	const marginLeft = margin?.left ?? 0;
+
+	const boxStyle: CSSProperties = { zIndex, ...style };
+	const { offsetLeft = 10, offsetTop = 10, unstyled, className, ...boxProps } = tooltipProps;
+	const anchorTop =
+		tooltipPlacement === 'below-axis'
+			? marginTop + innerHeight + ( margin?.bottom ?? 0 )
+			: ( tooltipAnchorTop ?? tooltipTop );
+	const box =
+		detectBounds || tooltipPlacement !== 'auto' ? (
+			<BoundedTooltip
+				left={ tooltipLeft }
+				top={ anchorTop }
+				offsetLeft={ offsetLeft }
+				offsetTop={ offsetTop }
+				unstyled={ unstyled }
+				className={ className }
+				style={ boxStyle }
+				{ ...boxProps }
+				{ ...( tooltipPlacement !== 'auto' && { placement: tooltipPlacement } ) }
+			>
+				{ tooltipContent }
+			</BoundedTooltip>
+		) : (
+			<TooltipBox
+				role="presentation"
+				unstyled={ unstyled }
+				className={ className }
+				style={ {
+					position: 'absolute',
+					left: ( tooltipLeft ?? 0 ) + offsetLeft,
+					top: ( anchorTop ?? 0 ) + offsetTop,
+					...( ! unstyled && boxStyle ),
+				} }
+				{ ...boxProps }
+			>
+				{ tooltipContent }
+			</TooltipBox>
+		);
+
+	return (
+		<>
+			<g className="visx-tooltip-overlay" pointerEvents="none">
+				{ showVerticalCrosshair && isValidNumber( tooltipLeft ) && (
+					<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 }
+					/>
+				) }
+				{ 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 }
+					/>
+				) }
+				{ glyphs }
+			</g>
+			{ container && createPortal( box, container ) }
+		</>
+	);
+};
+
+/**
+ * In-tree replacement for `@visx/xychart`'s `Tooltip`.
+ *
+ * visx renders its tooltip box, glyphs and crosshairs through portals appended
+ * to `document.body`. That puts them in the page's root stacking context, where
+ * they paint above every sticky or fixed element that lives inside a nested
+ * stacking context, and no z-index on that element can change the order. This
+ * component draws the glyphs and crosshairs straight into the chart SVG and
+ * renders the tooltip box into the SVG's parent element, so all of them stack
+ * as ordinary descendants of the chart.
+ *
+ * Render it as a child of `XYChart`. The element wrapping that `XYChart` must
+ * be `position: relative` with the SVG at its origin, and `isolation: isolate`:
+ * the box is placed with the SVG-local coordinates visx reports, and the
+ * 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. 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.
+ */
+export const XyChartTooltipOverlay = < Datum extends object >(
+	props: XyChartTooltipProps< Datum >
+) => {
+	const tooltipContext = useContext( TooltipContext ) as TooltipContextType< Datum > | null;
+	const [ container, setContainer ] = useState< HTMLElement | null >( null );
+
+	// Children of XYChart render inside its SVG, and the box needs an HTML parent.
+	const anchorRef = useCallback( ( node: SVGGElement | null ) => {
+		setContainer( node?.ownerSVGElement?.parentElement ?? null );
+	}, [] );
+
+	return (
+		<>
+			<g ref={ anchorRef } data-testid="xy-chart-tooltip-anchor" />
+			{ tooltipContext?.tooltipOpen && (
+				<XyChartTooltipContent
+					{ ...props }
+					tooltipContext={ tooltipContext }
+					container={ container }
+				/>
+			) }
+		</>
+	);
+};

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

@@ -126,6 +126,87 @@ describe( 'BoundedTooltip', () => {
 		jest.restoreAllMocks();
 	} );
 
+	test( 'draws the package surface, not the visx default box', () => {
+		render(
+			<BoundedTooltip left={ 10 } top={ 10 } data-testid="box">
+				content
+			</BoundedTooltip>
+		);
+		const box = screen.getByTestId( 'box' );
+		expect( box ).toHaveClass( 'surface' );
+		expect( box ).not.toHaveStyle( { backgroundColor: 'white' } );
+		// toHaveStyle can't assert an absent inline style; box.style reads the empty string directly.
+		// eslint-disable-next-line jest-dom/prefer-to-have-style
+		expect( box.style.boxShadow ).toBe( '' );
+		// eslint-disable-next-line jest-dom/prefer-to-have-style
+		expect( box.style.padding ).toBe( '' );
+	} );
+
+	test( 'keeps a caller class beside the surface', () => {
+		render(
+			<BoundedTooltip left={ 10 } top={ 10 } className="extra" data-testid="box">
+				content
+			</BoundedTooltip>
+		);
+		expect( screen.getByTestId( 'box' ) ).toHaveClass( 'surface', 'extra' );
+	} );
+
+	test( 'drops the surface when unstyled', () => {
+		render(
+			<BoundedTooltip left={ 10 } top={ 10 } unstyled data-testid="box">
+				content
+			</BoundedTooltip>
+		);
+		expect( screen.getByTestId( 'box' ) ).not.toHaveClass( 'surface' );
+		expect( screen.getByTestId( 'box' ) ).not.toHaveClass( 'a8c-charts-tooltip-scope' );
+	} );
+
+	test( 're-declares the chart catalog on a styled box under its own class, out of reach of page-wide chart overrides', () => {
+		render(
+			<BoundedTooltip left={ 10 } top={ 10 } data-testid="box">
+				content
+			</BoundedTooltip>
+		);
+		const box = screen.getByTestId( 'box' );
+		expect( box ).toHaveClass( 'a8c-charts-tooltip-scope', 'surface' );
+		expect( box ).not.toHaveClass( 'a8c-charts-scope' );
+	} );
+
+	test( 'measures against the positioned wrapper past a display: contents element', () => {
+		jest.spyOn( Element.prototype, 'getBoundingClientRect' ).mockImplementation( function (
+			this: Element
+		) {
+			if ( this.classList.contains( 'visx-tooltip' ) ) {
+				return rect( 0, 0, 208, 36 );
+			}
+			return this.getAttribute( 'data-testid' ) === 'contents'
+				? rect( 0, 0, 0, 0 )
+				: rect( 0, 0, 600, 200 );
+		} );
+
+		render(
+			<div style={ { position: 'relative', overflow: 'hidden' } }>
+				<div data-testid="contents" style={ { display: 'contents' } }>
+					<BoundedTooltip left={ 300 } top={ 50 } unstyled data-testid="box">
+						content
+					</BoundedTooltip>
+				</div>
+			</div>
+		);
+
+		// Measured against the zero-size contents element, the box would flip to (82, 4).
+		expect( screen.getByTestId( 'box' ) ).toHaveStyle( { transform: 'translate(310px, 60px)' } );
+	} );
+
+	test( 'lets an inline style override the surface', () => {
+		render(
+			<BoundedTooltip left={ 10 } top={ 10 } style={ { background: 'red' } } data-testid="box">
+				content
+			</BoundedTooltip>
+		);
+		expect( screen.getByTestId( 'box' ) ).toHaveStyle( { background: 'red' } );
+	} );
+
 	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 (
@@ -209,7 +290,7 @@ describe( 'BoundedTooltip', () => {
 				left: `${ pointerLeft }px`,
 				top: '-6px',
 				width: '12px',
-				height: '6px',
+				height: '7px',
 			} );
 			expect( screen.getByTestId( 'tooltip-axis-pointer' ) ).toHaveAttribute(
 				'aria-hidden',

package/src/components/tooltip/test/tool-tip.test.tsx

@@ -27,13 +27,20 @@ describe( 'BaseTooltip', () => {
 		expect( screen.getByText( 'Custom Child Content' ) ).toBeInTheDocument();
 	} );
 
-	test( 'applies correct positioning styles', () => {
+	it( 'places a legacy box centered above its point', () => {
 		render( <BaseTooltip { ...defaultProps } /> );
-		const tooltip = screen.getByRole( 'tooltip' );
-		expect( tooltip ).toHaveStyle( {
+		expect( screen.getByRole( 'tooltip' ) ).toHaveStyle( {
+			position: 'absolute',
 			top: '100px',
 			left: '200px',
+			transform: 'translate(-50%, -100%)',
 		} );
+		expect( screen.getByRole( 'tooltip' ) ).toHaveClass( 'visx-tooltip', 'surface' );
+	} );
+
+	it( 'renders in flow without top and left', () => {
+		render( <BaseTooltip>Content</BaseTooltip> );
+		expect( screen.getByRole( 'tooltip' ) ).not.toHaveStyle( { position: 'absolute' } );
 	} );
 
 	test( 'handles missing valueDisplay', () => {

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

@@ -0,0 +1,53 @@
+import { render, screen } from '@testing-library/react';
+import { createRef } from 'react';
+import { TooltipBox } from '../tooltip-box';
+
+describe( 'TooltipBox', () => {
+	it( 'renders the styled box with the class consumers target', () => {
+		render( <TooltipBox>Content</TooltipBox> );
+		const box = screen.getByRole( 'tooltip' );
+		expect( box ).toHaveTextContent( 'Content' );
+		expect( box ).toHaveClass( 'visx-tooltip', 'surface', 'a8c-charts-tooltip-scope' );
+		expect( box ).not.toHaveClass( 'a8c-charts-scope' );
+	} );
+
+	it( 'leaves positioning to the caller', () => {
+		render(
+			<TooltipBox style={ { position: 'absolute', left: 12, top: 34 } }>Content</TooltipBox>
+		);
+		expect( screen.getByRole( 'tooltip' ) ).toHaveStyle( {
+			position: 'absolute',
+			left: '12px',
+			top: '34px',
+		} );
+	} );
+
+	it( 'keeps a caller class beside the surface', () => {
+		render( <TooltipBox className="custom">Content</TooltipBox> );
+		expect( screen.getByRole( 'tooltip' ) ).toHaveClass( 'surface', 'custom' );
+	} );
+
+	it( 'drops the surface and scope class when unstyled, keeping style', () => {
+		render(
+			<TooltipBox unstyled style={ { left: 5 } }>
+				Content
+			</TooltipBox>
+		);
+		const box = screen.getByRole( 'tooltip' );
+		expect( box ).not.toHaveClass( 'surface' );
+		expect( box ).not.toHaveClass( 'a8c-charts-tooltip-scope' );
+		expect( box ).toHaveClass( 'visx-tooltip' );
+		expect( box ).toHaveStyle( { left: '5px' } );
+	} );
+
+	it( 'lets the caller replace the role', () => {
+		render( <TooltipBox role="presentation">Content</TooltipBox> );
+		expect( screen.queryByRole( 'tooltip' ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'forwards its ref to the box', () => {
+		const ref = createRef< HTMLDivElement >();
+		render( <TooltipBox ref={ ref }>Content</TooltipBox> );
+		expect( ref.current ).toBe( screen.getByRole( 'tooltip' ) );
+	} );
+} );

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

@@ -0,0 +1,61 @@
+import { render, screen } from '@testing-library/react';
+import { resolveCssVariable } from '../../../utils/resolve-css-var';
+import { TooltipTheme } from '../private/tooltip-theme';
+
+jest.mock( '@wordpress/theme', () => ( { ...jest.requireActual( '@wordpress/theme' ) } ) );
+jest.mock( '../../../utils/resolve-css-var', () => ( { resolveCssVariable: jest.fn() } ) );
+
+const theme = jest.requireMock( '@wordpress/theme' );
+const { ThemeProvider } = jest.requireActual( '@wordpress/theme' );
+
+const spyOnThemeProvider = () =>
+	jest.spyOn( theme, 'ThemeProvider' ).mockImplementation( ( { children } ) => children );
+
+describe( 'TooltipTheme', () => {
+	afterEach( () => {
+		jest.restoreAllMocks();
+		theme.ThemeProvider = ThemeProvider;
+	} );
+
+	test( 'renders the box unthemed when core exports no public ThemeProvider', () => {
+		theme.ThemeProvider = undefined;
+		jest.mocked( resolveCssVariable ).mockReturnValue( '#1e1e1e' );
+
+		render( <TooltipTheme>box</TooltipTheme> );
+
+		expect( screen.getByText( 'box' ) ).toBeInTheDocument();
+	} );
+
+	test.each( [ 'rgba(0, 0, 0, 0.85)', 'not-a-color', null ] )(
+		'seeds the default surface when the surface role resolves to %p',
+		value => {
+			const provider = spyOnThemeProvider();
+			jest.mocked( resolveCssVariable ).mockReturnValue( value );
+
+			render( <TooltipTheme>box</TooltipTheme> );
+
+			expect( provider.mock.calls[ 0 ][ 0 ] ).toMatchObject( {
+				color: { background: '#1e1e1e' },
+			} );
+		}
+	);
+
+	test( 'seeds an opaque surface role as hex', () => {
+		const provider = spyOnThemeProvider();
+		jest.mocked( resolveCssVariable ).mockReturnValue( 'rgb(255, 255, 255)' );
+
+		render( <TooltipTheme>box</TooltipTheme> );
+
+		expect( provider.mock.calls[ 0 ][ 0 ] ).toMatchObject( {
+			color: { background: '#ffffff' },
+		} );
+	} );
+
+	test( 'renders with the real ThemeProvider when the surface role is translucent', () => {
+		jest.mocked( resolveCssVariable ).mockReturnValue( 'rgba(0, 0, 0, 0.85)' );
+
+		render( <TooltipTheme>box</TooltipTheme> );
+
+		expect( screen.getByText( 'box' ) ).toBeInTheDocument();
+	} );
+} );