@automattic/charts 0.56.3 → 0.56.5

package/src/hooks/test/use-tooltip-portal-relocator.test.ts

@@ -0,0 +1,216 @@
+/* eslint-disable testing-library/no-node-access */
+import { renderHook } from '@testing-library/react';
+import { useTooltipPortalRelocator } from '../use-tooltip-portal-relocator';
+
+// In the production build, CSS module class names are hashed (e.g. "a8ccharts-abc123").
+// In jest, the SCSS module import is stubbed to a filename string, so
+// styles.relocatedPortal resolves to undefined and classList.add() is a no-op.
+// We mock the module to return a proper class map so we can assert on class names.
+jest.mock( '../use-tooltip-portal-relocator.module.scss', () => ( {
+	__esModule: true,
+	default: { relocatedPortal: 'relocatedPortal' },
+} ) );
+
+/**
+ * Create a mock visx tooltip portal node for testing.
+ * @return {HTMLDivElement} A div mimicking a visx tooltip portal.
+ */
+function createVisxPortalNode(): HTMLDivElement {
+	const portal = document.createElement( 'div' );
+	const child = document.createElement( 'div' );
+	child.className = 'visx-tooltip';
+	portal.appendChild( child );
+	return portal;
+}
+
+/**
+ * Sets up a container, ref, and renders the hook.
+ * Optionally appends a visx portal node to document.body before rendering.
+ * @param options            - Setup options.
+ * @param options.withPortal - If true, creates and appends a visx portal before rendering.
+ * @return                      Setup result with container, ref, unmount, and optionally the portal node.
+ */
+function setupHook( { withPortal = false } = {} ) {
+	const container = document.createElement( 'div' );
+	document.body.appendChild( container );
+
+	let portal: HTMLDivElement | undefined;
+	if ( withPortal ) {
+		portal = createVisxPortalNode();
+		document.body.appendChild( portal );
+	}
+
+	const ref = { current: container };
+	const { unmount } = renderHook( () => useTooltipPortalRelocator( ref ) );
+
+	return { container, ref, unmount, portal };
+}
+
+describe( 'useTooltipPortalRelocator', () => {
+	let nativeRemoveChild: typeof document.body.removeChild;
+
+	beforeAll( () => {
+		nativeRemoveChild = document.body.removeChild;
+	} );
+
+	afterEach( () => {
+		// Restore native removeChild and clear all body children to prevent
+		// leaked portals from interfering with subsequent tests.
+		document.body.removeChild = nativeRemoveChild;
+		while ( document.body.firstChild ) {
+			nativeRemoveChild.call( document.body, document.body.firstChild );
+		}
+	} );
+
+	test( 'does nothing when containerRef is undefined', () => {
+		const { unmount } = renderHook( () => useTooltipPortalRelocator( undefined ) );
+		const portal = createVisxPortalNode();
+		document.body.appendChild( portal );
+		expect( portal.parentNode ).toBe( document.body );
+		unmount();
+	} );
+
+	test( 'does nothing when containerRef.current is null', () => {
+		const nullRef = { current: null };
+		const { unmount } = renderHook( () => useTooltipPortalRelocator( nullRef ) );
+		const portal = createVisxPortalNode();
+		document.body.appendChild( portal );
+		expect( portal.parentNode ).toBe( document.body );
+		unmount();
+	} );
+
+	test( 'relocates existing visx portal nodes into the container', () => {
+		const { container, unmount, portal } = setupHook( { withPortal: true } );
+		expect( portal!.parentNode ).toBe( container );
+		unmount();
+	} );
+
+	test( 'applies relocated-portal class to relocated portals', () => {
+		const { unmount, portal } = setupHook( { withPortal: true } );
+		expect( portal! ).toHaveClass( 'relocatedPortal' );
+		unmount();
+	} );
+
+	test( 'does not relocate newly added non-visx nodes', async () => {
+		const { unmount } = setupHook();
+
+		const regularDiv = document.createElement( 'div' );
+		regularDiv.id = 'some-id';
+		document.body.appendChild( regularDiv );
+
+		// MutationObserver is async — wait for microtask
+		await new Promise( resolve => setTimeout( resolve, 0 ) );
+
+		expect( regularDiv.parentNode ).toBe( document.body );
+		unmount();
+	} );
+
+	test( 'observes and relocates newly added portal nodes', async () => {
+		const { container, unmount } = setupHook();
+
+		const portal = createVisxPortalNode();
+		document.body.appendChild( portal );
+
+		// MutationObserver is async — wait for microtask
+		await new Promise( resolve => setTimeout( resolve, 0 ) );
+
+		expect( portal.parentNode ).toBe( container );
+		unmount();
+	} );
+
+	test( 'patched removeChild handles relocated nodes without throwing', () => {
+		const { unmount, portal } = setupHook( { withPortal: true } );
+
+		// Portal is now in container, but visx will call document.body.removeChild(portal)
+		expect( () => document.body.removeChild( portal! ) ).not.toThrow();
+		expect( portal!.parentNode ).toBeNull();
+		unmount();
+	} );
+
+	test( 'patched removeChild delegates to original for non-relocated nodes', () => {
+		const { unmount } = setupHook();
+
+		const regularDiv = document.createElement( 'div' );
+		document.body.appendChild( regularDiv );
+		expect( () => document.body.removeChild( regularDiv ) ).not.toThrow();
+		expect( regularDiv.parentNode ).toBeNull();
+		unmount();
+	} );
+
+	test( 'cleanup restores removeChild when it has not been wrapped by others', () => {
+		const originalRemoveChild = document.body.removeChild;
+		const { unmount } = setupHook();
+
+		// removeChild should be patched
+		expect( document.body.removeChild ).not.toBe( originalRemoveChild );
+
+		unmount();
+
+		// Should be restored
+		expect( document.body.removeChild ).toBe( originalRemoveChild );
+	} );
+
+	test( 'cleanup leaves removeChild when another wrapper was installed after ours', () => {
+		const { unmount } = setupHook();
+
+		// Simulate another library wrapping removeChild after our patch
+		const ourPatch = document.body.removeChild;
+		const thirdPartyWrapper = function < T extends Node >( child: T ): T {
+			return ourPatch.call( document.body, child );
+		};
+		document.body.removeChild = thirdPartyWrapper;
+
+		unmount();
+
+		// Should NOT restore — third party wrapper is still in place
+		expect( document.body.removeChild ).toBe( thirdPartyWrapper );
+	} );
+
+	test( 'cleanup moves relocated nodes back to document.body', () => {
+		const { container, unmount, portal } = setupHook( { withPortal: true } );
+
+		expect( portal!.parentNode ).toBe( container );
+
+		unmount();
+
+		// Node should be moved back to body on cleanup
+		expect( portal!.parentNode ).toBe( document.body );
+	} );
+
+	test( 'cleanup removes relocated-portal class from nodes', () => {
+		const { unmount, portal } = setupHook( { withPortal: true } );
+
+		expect( portal! ).toHaveClass( 'relocatedPortal' );
+
+		unmount();
+
+		expect( portal! ).not.toHaveClass( 'relocatedPortal' );
+	} );
+
+	test( 'ref-counting allows multiple instances to share the patch', () => {
+		const container1 = document.createElement( 'div' );
+		const container2 = document.createElement( 'div' );
+		document.body.appendChild( container1 );
+		document.body.appendChild( container2 );
+
+		const ref1 = { current: container1 };
+		const ref2 = { current: container2 };
+
+		const originalRemoveChild = document.body.removeChild;
+
+		const { unmount: unmountFirst } = renderHook( () => useTooltipPortalRelocator( ref1 ) );
+		const patchedFn = document.body.removeChild;
+		const { unmount: unmountSecond } = renderHook( () => useTooltipPortalRelocator( ref2 ) );
+
+		// Both should share the same patched removeChild
+		expect( document.body.removeChild ).toBe( patchedFn );
+
+		// Unmounting the first should keep the patch (ref count > 0)
+		unmountFirst();
+		expect( document.body.removeChild ).toBe( patchedFn );
+
+		// Unmounting the second should restore the original
+		unmountSecond();
+		expect( document.body.removeChild ).toBe( originalRemoveChild );
+	} );
+} );

package/src/hooks/use-chart-margin.tsx

@@ -4,6 +4,79 @@ import { getLongestTickWidth } from '../utils';
 import type { BaseChartProps, DataPointDate, SeriesData } from '../types';
 import type { XYChartTheme } from '@visx/xychart';
 
+/**
+ * Base top margin used when no dynamic adjustments are necessary.
+ */
+const DEFAULT_MARGIN_TOP = 10;
+
+/**
+ * Base right margin used when no dynamic adjustments are necessary.
+ */
+const DEFAULT_MARGIN_RIGHT = 20;
+
+/**
+ * Base bottom margin used for charts with a bottom X-axis.
+ * This is large enough for typical font sizes and will be increased
+ * dynamically when tick labels require more space.
+ */
+const DEFAULT_MARGIN_BOTTOM = 20;
+
+/**
+ * Base left margin used when no dynamic adjustments are necessary.
+ */
+const DEFAULT_MARGIN_LEFT = 20;
+
+/**
+ * Bottom margin to use when the X-axis is rendered at the top.
+ * We only need a small buffer below the chart in that case.
+ */
+const DEFAULT_BOTTOM_FOR_TOP_AXIS = 10;
+
+/**
+ * Fallback font size used when we cannot derive a font size
+ * from the theme or axis styles for X-axis tick labels.
+ */
+const DEFAULT_FONT_SIZE = 12;
+
+/**
+ * Fallback tick length used when tickLength is not provided
+ * by the theme for either axis.
+ */
+const DEFAULT_TICK_LENGTH = 8;
+
+/**
+ * Fallback width used for Y-axis tick labels when we cannot
+ * measure them via getLongestTickWidth.
+ */
+const DEFAULT_Y_TICK_WIDTH = 40;
+
+const resolveFontSize = ( val?: number | string ): number | undefined => {
+	if ( typeof val === 'number' && ! isNaN( val ) ) {
+		return val;
+	}
+
+	if ( typeof val === 'string' ) {
+		const parsed = parseFloat( val );
+		return isNaN( parsed ) ? undefined : parsed;
+	}
+
+	return undefined;
+};
+
+const getXAxisLabelMetrics = ( theme: XYChartTheme, orientation: 'top' | 'bottom' ) => {
+	const xAxisStyles =
+		orientation === 'top' ? theme.axisStyles?.x?.top : theme.axisStyles?.x?.bottom;
+
+	const fontSize =
+		resolveFontSize( xAxisStyles?.axisLabel?.fontSize ) ||
+		resolveFontSize( theme.svgLabelSmall?.fontSize ) ||
+		DEFAULT_FONT_SIZE;
+
+	const tickLength = xAxisStyles?.tickLength ?? DEFAULT_TICK_LENGTH;
+
+	return { fontSize, tickLength };
+};
+
 export const useChartMargin = (
 	height: number,
 	options: BaseChartProps[ 'options' ],
@@ -34,8 +107,12 @@ export const useChartMargin = (
 
 	return useMemo( () => {
 		// Default margin is for bottom axis labels.
-		const defaultMargin = { top: 10, right: 20, bottom: 20, left: 20 };
-		const defaultTickWidth = 40;
+		const defaultMargin = {
+			top: DEFAULT_MARGIN_TOP,
+			right: DEFAULT_MARGIN_RIGHT,
+			bottom: DEFAULT_MARGIN_BOTTOM,
+			left: DEFAULT_MARGIN_LEFT,
+		};
 
 		// Auto-calculate margin for y axis labels based on orientation and tick width.
 		const yAxisOrientation = options.axis?.y?.orientation;
@@ -46,7 +123,7 @@ export const useChartMargin = (
 			options.axis?.y?.tickFormat,
 			yAxisStyles.axisLabel
 		);
-		const yMarginValue = ( yTickWidth ?? defaultTickWidth ) + ( yAxisStyles?.tickLength ?? 0 );
+		const yMarginValue = ( yTickWidth ?? DEFAULT_Y_TICK_WIDTH ) + ( yAxisStyles?.tickLength ?? 0 );
 
 		if ( yAxisOrientation === 'right' ) {
 			defaultMargin.right = yMarginValue;
@@ -54,9 +131,18 @@ export const useChartMargin = (
 			defaultMargin.left = yMarginValue;
 		}
 
-		if ( options.axis?.x?.orientation === 'top' ) {
-			defaultMargin.top = 20;
-			defaultMargin.bottom = 10;
+		// Dynamically compute X-axis margin (bottom by default, or top if orientation is 'top').
+		// This mirrors Y-axis behavior where margin is based on label size and tick length,
+		// but keeps the padding minimal so consumers can control container spacing themselves.
+		const xOrientation = options.axis?.x?.orientation === 'top' ? 'top' : 'bottom';
+		const { fontSize, tickLength } = getXAxisLabelMetrics( theme, xOrientation );
+		const computedXMargin = fontSize + tickLength;
+
+		if ( xOrientation === 'top' ) {
+			defaultMargin.top = Math.max( defaultMargin.top, computedXMargin );
+			defaultMargin.bottom = DEFAULT_BOTTOM_FOR_TOP_AXIS;
+		} else {
+			defaultMargin.bottom = Math.max( defaultMargin.bottom, computedXMargin );
 		}
 
 		return defaultMargin;

package/src/hooks/use-tooltip-portal-relocator.module.scss

@@ -0,0 +1,10 @@
+.relocatedPortal {
+	position: fixed;
+	top: 0;
+	left: 0;
+	width: 0;
+	height: 0;
+	overflow: visible;
+	z-index: 1;
+	pointer-events: none;
+}

package/src/hooks/use-tooltip-portal-relocator.ts

@@ -0,0 +1,177 @@
+import { useEffect } from 'react';
+import styles from './use-tooltip-portal-relocator.module.scss';
+import type { RefObject } from 'react';
+
+/**
+ * Detects whether a DOM node is a visx chart tooltip portal.
+ *
+ * visx renders tooltips via `ReactDOM.createPortal` into plain `<div>` elements
+ * appended to `document.body`. These portals have no id or className and contain
+ * a child element with the class `visx-tooltip`.
+ * @param node - The DOM node to check.
+ * @return Whether the node is a visx tooltip portal div.
+ */
+function isVisxPortalNode( node: Node ): node is HTMLDivElement {
+	return (
+		node instanceof HTMLDivElement &&
+		node.parentElement === document.body &&
+		! node.id &&
+		! node.className &&
+		node.querySelector( '.visx-tooltip' ) !== null
+	);
+}
+
+// Shared state for the document.body.removeChild patch.
+// Reference-counted so multiple hook instances can coexist safely.
+let patchRefCount = 0;
+let origRemoveChild: typeof document.body.removeChild | null = null;
+let patchedRemoveChild: typeof document.body.removeChild | null = null;
+const relocatedNodes = new WeakSet< Node >();
+
+/**
+ * Installs (or increments the ref count of) the shared removeChild patch.
+ */
+function installRemoveChildPatch() {
+	if ( patchRefCount++ > 0 ) {
+		return;
+	}
+	origRemoveChild = document.body.removeChild;
+	patchedRemoveChild = function < T extends Node >( this: HTMLElement, child: T ): T {
+		if ( relocatedNodes.has( child ) && child.parentNode !== this ) {
+			relocatedNodes.delete( child );
+			child.parentNode?.removeChild( child );
+			return child;
+		}
+		return origRemoveChild!.call( this, child );
+	};
+	document.body.removeChild = patchedRemoveChild;
+}
+
+/**
+ * Decrements the ref count and removes the patch when no instances remain.
+ * If another library has since wrapped our patch, we leave it in place to
+ * avoid breaking their chain — our function becomes a transparent pass-through
+ * once all relocated nodes have been cleaned up.
+ */
+function uninstallRemoveChildPatch() {
+	if ( --patchRefCount > 0 ) {
+		return;
+	}
+	// Only revert if removeChild is still our function. If something else
+	// has wrapped it, reverting would break their patch.
+	if ( document.body.removeChild === patchedRemoveChild ) {
+		document.body.removeChild = origRemoveChild!;
+	}
+	origRemoveChild = null;
+	patchedRemoveChild = null;
+}
+
+/**
+ * Relocates visx chart tooltip portals from `document.body` into a target
+ * container element. This allows the tooltips to participate in the same CSS
+ * stacking context as other elements in the container (e.g. a sticky header),
+ * so z-index ordering works correctly between them.
+ *
+ * The relocated portal divs use `position: fixed` at the viewport origin to
+ * preserve the tooltip coordinate system (visx calculates positions relative
+ * to the viewport).
+ *
+ * Because the visx Portal class calls `document.body.removeChild(node)` during
+ * unmount, we patch `document.body.removeChild` to gracefully handle nodes that
+ * were moved out of body. Without this, React throws a "not a child of this
+ * node" error when tooltips unmount.
+ *
+ * **Important:** The container and its ancestors must not have CSS `transform`,
+ * `perspective`, or `filter` properties set, as these create a new containing
+ * block for `position: fixed` children, breaking viewport-relative positioning.
+ *
+ * @param containerRef - Ref to the element that portals should be relocated into.
+ *                     The element referenced here, or one of its ancestors,
+ *                     should establish the desired stacking context (for example
+ *                     by using position and z-index).
+ */
+export function useTooltipPortalRelocator(
+	containerRef: RefObject< HTMLElement | null > | undefined
+) {
+	useEffect( () => {
+		const container = containerRef?.current;
+		if ( ! container ) {
+			return;
+		}
+
+		// Track nodes relocated by this instance so we can move them back on cleanup.
+		const instanceNodes = new Set< Node >();
+
+		const relocateNode = ( node: Node ) => {
+			if ( ! isVisxPortalNode( node ) ) {
+				return;
+			}
+
+			// Position the portal at the viewport origin so visx's
+			// absolute-positioned tooltip coordinates remain correct.
+			// Zero-size with overflow: visible so it doesn't affect layout
+			// but tooltip content still renders. pointerEvents: none on the
+			// wrapper is intentional — tooltip inner elements manage their own.
+			node.classList.add( styles.relocatedPortal );
+
+			// Remember the focused element before moving the node — relocating
+			// a DOM subtree causes the browser to blur any focused descendants.
+			const { activeElement } = node.ownerDocument;
+			const focusedElement =
+				activeElement instanceof HTMLElement && node.contains( activeElement )
+					? activeElement
+					: null;
+
+			// Insert at the start of the container (before header and content).
+			container.insertBefore( node, container.firstChild );
+			relocatedNodes.add( node );
+			instanceNodes.add( node );
+
+			// Restore focus that was lost due to the DOM move.
+			if ( focusedElement ) {
+				focusedElement.focus();
+			}
+		};
+
+		// Patch document.body.removeChild so visx Portal unmount doesn't throw
+		// when it tries to remove a node we already moved out of body.
+		installRemoveChildPatch();
+
+		// Relocate any portals that already exist.
+		for ( const child of Array.from( document.body.children ) ) {
+			relocateNode( child );
+		}
+
+		// Watch for new portals being appended to body.
+		const observer = new MutationObserver( mutations => {
+			for ( const mutation of mutations ) {
+				for ( const node of mutation.addedNodes ) {
+					relocateNode( node );
+				}
+			}
+		} );
+
+		observer.observe( document.body, { childList: true } );
+
+		return () => {
+			// Disconnect first to avoid the observer re-relocating nodes
+			// as we move them back to body.
+			observer.disconnect();
+
+			// Move relocated nodes back to body so visx can clean them up
+			// normally with the original removeChild.
+			for ( const node of instanceNodes ) {
+				if ( node instanceof HTMLElement ) {
+					node.classList.remove( styles.relocatedPortal );
+				}
+				if ( node.parentNode === container ) {
+					document.body.appendChild( node );
+				}
+				relocatedNodes.delete( node );
+			}
+			instanceNodes.clear();
+
+			uninstallRemoveChildPatch();
+		};
+	}, [ containerRef ] );
+}

package/src/providers/chart-context/global-charts-provider.tsx

@@ -8,6 +8,7 @@ import {
 	useLayoutEffect,
 	useRef,
 } from 'react';
+import { useTooltipPortalRelocator } from '../../hooks/use-tooltip-portal-relocator';
 import {
 	getItemShapeStyles,
 	getSeriesLineStyles,
@@ -26,9 +27,22 @@ export const GlobalChartsContext = createContext< GlobalChartsContextValue | nul
 export interface GlobalChartsProviderProps {
 	children: ReactNode;
 	theme?: Partial< ChartTheme >;
+	/**
+	 * Optional ref to an element that chart tooltip portals should be relocated into.
+	 * When provided, visx tooltip portals (normally appended to document.body) will be
+	 * moved into this container so they participate in the same effective CSS stacking context.
+	 * The element referenced here, or one of its ancestors, should establish the desired
+	 * stacking context (for example by using `position` and `z-index`) so that tooltips
+	 * appear above the relevant chart content.
+	 */
+	portalContainer?: React.RefObject< HTMLElement | null >;
 }
 
-export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { children, theme } ) => {
+export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
+	children,
+	theme,
+	portalContainer,
+} ) => {
 	const [ charts, setCharts ] = useState< Map< string, ChartRegistration > >( () => new Map() );
 	// Track hidden series per chart: chartId -> Set<seriesLabel>
 	const [ hiddenSeries, setHiddenSeries ] = useState< Map< string, Set< string > > >(
@@ -38,6 +52,9 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 	// Ref to the wrapper element for resolving scoped CSS variables
 	const wrapperRef = useRef< HTMLDivElement >( null );
 
+	// Relocate tooltip portals into the wrapper (or a consumer-provided container) for z-index control.
+	useTooltipPortalRelocator( portalContainer ?? wrapperRef );
+
 	const providerTheme: CompleteChartTheme = useMemo( () => {
 		return theme ? mergeThemes( defaultTheme, theme ) : defaultTheme;
 	}, [ theme ] );

package/tsup.config.ts

@@ -1,3 +1,4 @@
+import babel from 'esbuild-plugin-babel';
 import { sassPlugin, postcssModules } from 'esbuild-sass-plugin';
 import { defineConfig } from 'tsup';
 import pkg from './package.json';
@@ -23,6 +24,16 @@ export default defineConfig( {
 		'.png': 'file',
 	},
 	esbuildPlugins: [
+		babel( {
+			filter: /\.tsx$/,
+			config: {
+				presets: [
+					'@babel/preset-typescript',
+					[ '@babel/preset-react', { runtime: 'automatic' } ],
+				],
+				plugins: [ [ 'react-remove-properties', { properties: [ 'data-testid' ] } ] ],
+			},
+		} ),
 		sassPlugin( {
 			filter: /\.module\.(css|scss)$/,
 			embedded: true,