@automattic/charts 0.56.4 → 0.56.6

package/src/hooks/test/{use-element-height.test.tsx → use-element-size.test.tsx}

@@ -1,5 +1,5 @@
 import { renderHook, waitFor } from '@testing-library/react';
-import { useElementHeight } from '../use-element-height';
+import { useElementSize } from '../use-element-size';
 
 // Mock ResizeObserver
 class MockResizeObserver {
@@ -25,13 +25,12 @@ class MockResizeObserver {
 // Store original ResizeObserver
 const originalResizeObserver = globalThis.ResizeObserver;
 
-describe( 'useElementHeight', () => {
+describe( 'useElementSize', () => {
 	let mockResizeObserver;
 
 	beforeEach( () => {
 		mockResizeObserver = MockResizeObserver;
 		globalThis.ResizeObserver = mockResizeObserver;
-		globalThis.window.ResizeObserver = mockResizeObserver;
 	} );
 
 	afterEach( () => {
@@ -39,75 +38,82 @@ describe( 'useElementHeight', () => {
 		jest.clearAllMocks();
 	} );
 
-	it( 'should return initial height of 0 by default', () => {
-		const { result } = renderHook( () => useElementHeight() );
-		const [ refCallback, height ] = result.current;
+	it( 'should return initial dimensions of 0 by default', () => {
+		const { result } = renderHook( () => useElementSize() );
+		const [ refCallback, width, height ] = result.current;
 
+		expect( width ).toBe( 0 );
 		expect( height ).toBe( 0 );
 		expect( typeof refCallback ).toBe( 'function' );
 	} );
 
-	it( 'should return custom initial height when provided', () => {
-		const { result } = renderHook( () => useElementHeight( { initialHeight: 100 } ) );
-		const [ , height ] = result.current;
+	it( 'should return custom initial dimensions when provided', () => {
+		const { result } = renderHook( () =>
+			useElementSize( { initialWidth: 200, initialHeight: 100 } )
+		);
+		const [ , width, height ] = result.current;
 
+		expect( width ).toBe( 200 );
 		expect( height ).toBe( 100 );
 	} );
 
-	it( 'should update height when element is attached', async () => {
+	it( 'should update dimensions when element is attached', async () => {
 		const mockElement = {
-			getBoundingClientRect: jest.fn( () => ( { height: 150 } ) ),
+			getBoundingClientRect: jest.fn( () => ( { width: 300, height: 150 } ) ),
 		};
 
-		const { result } = renderHook( () => useElementHeight() );
+		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
 		// Attach the element
 		refCallback( mockElement as unknown as HTMLDivElement );
 
 		await waitFor( () => {
-			expect( result.current[ 1 ] ).toBe( 150 );
+			expect( result.current[ 1 ] ).toBe( 300 );
+			expect( result.current[ 2 ] ).toBe( 150 );
 		} );
 
 		expect( mockElement.getBoundingClientRect ).toHaveBeenCalled();
 	} );
 
-	it( 'should handle element with zero height', async () => {
+	it( 'should handle element with zero dimensions', async () => {
 		const mockElement = {
-			getBoundingClientRect: jest.fn( () => ( { height: 0 } ) ),
+			getBoundingClientRect: jest.fn( () => ( { width: 0, height: 0 } ) ),
 		};
 
-		const { result } = renderHook( () => useElementHeight() );
+		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
 		refCallback( mockElement as unknown as HTMLDivElement );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 0 );
+			expect( result.current[ 2 ] ).toBe( 0 );
 		} );
 	} );
 
-	it( 'should handle getBoundingClientRect returning undefined height', async () => {
+	it( 'should handle getBoundingClientRect returning undefined dimensions', async () => {
 		const mockElement = {
-			getBoundingClientRect: jest.fn( () => ( { height: undefined } ) ),
+			getBoundingClientRect: jest.fn( () => ( { width: undefined, height: undefined } ) ),
 		};
 
-		const { result } = renderHook( () => useElementHeight() );
+		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
 		refCallback( mockElement as unknown as HTMLDivElement );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 0 );
+			expect( result.current[ 2 ] ).toBe( 0 );
 		} );
 	} );
 
 	it( 'should disconnect previous observer when new element is attached', () => {
 		const mockElement1 = {
-			getBoundingClientRect: jest.fn( () => ( { height: 100 } ) ),
+			getBoundingClientRect: jest.fn( () => ( { width: 100, height: 100 } ) ),
 		};
 		const mockElement2 = {
-			getBoundingClientRect: jest.fn( () => ( { height: 200 } ) ),
+			getBoundingClientRect: jest.fn( () => ( { width: 200, height: 200 } ) ),
 		};
 
 		const disconnectSpy = jest.fn();
@@ -119,7 +125,7 @@ describe( 'useElementHeight', () => {
 
 		jest.spyOn( globalThis, 'ResizeObserver' ).mockImplementation( () => mockObserver );
 
-		const { result } = renderHook( () => useElementHeight() );
+		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
 		// Attach first element
@@ -133,7 +139,7 @@ describe( 'useElementHeight', () => {
 
 	it( 'should disconnect observer when element is removed (null)', () => {
 		const mockElement = {
-			getBoundingClientRect: jest.fn( () => ( { height: 100 } ) ),
+			getBoundingClientRect: jest.fn( () => ( { width: 100, height: 100 } ) ),
 		};
 
 		const disconnectSpy = jest.fn();
@@ -145,7 +151,7 @@ describe( 'useElementHeight', () => {
 
 		jest.spyOn( globalThis, 'ResizeObserver' ).mockImplementation( () => mockObserver );
 
-		const { result } = renderHook( () => useElementHeight() );
+		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
 		// Attach element
@@ -159,7 +165,7 @@ describe( 'useElementHeight', () => {
 
 	it( 'should create ResizeObserver and observe element', () => {
 		const mockElement = {
-			getBoundingClientRect: jest.fn( () => ( { height: 100 } ) ),
+			getBoundingClientRect: jest.fn( () => ( { width: 100, height: 100 } ) ),
 		};
 
 		const observeSpy = jest.fn();
@@ -171,7 +177,7 @@ describe( 'useElementHeight', () => {
 
 		jest.spyOn( globalThis, 'ResizeObserver' ).mockImplementation( () => mockObserver );
 
-		const { result } = renderHook( () => useElementHeight() );
+		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
 		refCallback( mockElement as unknown as HTMLDivElement );
@@ -181,7 +187,7 @@ describe( 'useElementHeight', () => {
 	} );
 
 	it( 'should maintain stable refCallback reference across re-renders', () => {
-		const { result, rerender } = renderHook( () => useElementHeight() );
+		const { result, rerender } = renderHook( () => useElementSize() );
 
 		const firstRefCallback = result.current[ 0 ];
 
@@ -195,26 +201,27 @@ describe( 'useElementHeight', () => {
 
 	it( 'should work with different element types', async () => {
 		const mockSpanElement = {
-			getBoundingClientRect: jest.fn( () => ( { height: 50 } ) ),
+			getBoundingClientRect: jest.fn( () => ( { width: 75, height: 50 } ) ),
 		};
 
-		const { result } = renderHook( () => useElementHeight() );
+		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
 		refCallback( mockSpanElement as unknown as HTMLDivElement );
 
 		await waitFor( () => {
-			expect( result.current[ 1 ] ).toBe( 50 );
+			expect( result.current[ 1 ] ).toBe( 75 );
+			expect( result.current[ 2 ] ).toBe( 50 );
 		} );
 	} );
 
-	it( 'should update height when ResizeObserver callback is triggered', async () => {
+	it( 'should update dimensions when ResizeObserver callback is triggered', async () => {
 		let resizeCallback;
 		const mockElement = {
 			getBoundingClientRect: jest
 				.fn()
-				.mockReturnValueOnce( { height: 100 } )
-				.mockReturnValueOnce( { height: 200 } ),
+				.mockReturnValueOnce( { width: 100, height: 100 } )
+				.mockReturnValueOnce( { width: 200, height: 150 } ),
 		};
 
 		jest.spyOn( globalThis, 'ResizeObserver' ).mockImplementation( callback => {
@@ -226,13 +233,14 @@ describe( 'useElementHeight', () => {
 			};
 		} );
 
-		const { result } = renderHook( () => useElementHeight() );
+		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
 		refCallback( mockElement as unknown as HTMLDivElement );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 100 );
+			expect( result.current[ 2 ] ).toBe( 100 );
 		} );
 
 		// Simulate resize
@@ -240,6 +248,7 @@ describe( 'useElementHeight', () => {
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 200 );
+			expect( result.current[ 2 ] ).toBe( 150 );
 		} );
 
 		expect( mockElement.getBoundingClientRect ).toHaveBeenCalledTimes( 2 );
@@ -247,7 +256,7 @@ describe( 'useElementHeight', () => {
 
 	it( 'should handle unmount properly', () => {
 		const mockElement = {
-			getBoundingClientRect: jest.fn( () => ( { height: 100 } ) ),
+			getBoundingClientRect: jest.fn( () => ( { width: 100, height: 100 } ) ),
 		};
 
 		const disconnectSpy = jest.fn();
@@ -257,7 +266,7 @@ describe( 'useElementHeight', () => {
 			unobserve: jest.fn(),
 		} ) );
 
-		const { result, unmount } = renderHook( () => useElementHeight() );
+		const { result, unmount } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
 		refCallback( mockElement as unknown as HTMLDivElement );

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-element-size.ts

@@ -0,0 +1,43 @@
+import { useState, useCallback, useRef } from 'react';
+
+/**
+ * Hook to measure the width and height of a DOM element.
+ * Returns a ref callback to attach to the element and the current dimensions in pixels.
+ *
+ * @param {object} props               - Optional props.
+ * @param {number} props.initialWidth  - The initial width to use.
+ * @param {number} props.initialHeight - The initial height to use.
+ *
+ * @return {[Function, number, number]} A tuple containing a ref callback, width, and height in pixels
+ */
+export function useElementSize< T extends HTMLElement = HTMLDivElement >( {
+	initialWidth = 0,
+	initialHeight = 0,
+}: {
+	initialWidth?: number;
+	initialHeight?: number;
+} = {} ): [ ( node: T | null ) => void, number, number ] {
+	const [ width, setWidth ] = useState( initialWidth );
+	const [ height, setHeight ] = useState( initialHeight );
+	const observerRef = useRef< ResizeObserver | null >( null );
+
+	const refCallback = useCallback( ( node: T | null ) => {
+		if ( observerRef.current ) {
+			observerRef.current.disconnect();
+			observerRef.current = null;
+		}
+		if ( node ) {
+			const handleResize = () => {
+				const rect = node.getBoundingClientRect();
+				setWidth( rect.width || 0 );
+				setHeight( rect.height || 0 );
+			};
+			handleResize();
+			const resizeObserver = new ResizeObserver( handleResize );
+			resizeObserver.observe( node );
+			observerRef.current = resizeObserver;
+		}
+	}, [] );
+
+	return [ refCallback, width, height ];
+}

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

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

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

@@ -107,6 +107,10 @@ export function useTooltipPortalRelocator(
 				return;
 			}
 
+			// Hide the portal immediately to prevent the tooltip from
+			// flashing at (0,0) before visx calculates the correct position.
+			node.style.opacity = '0';
+
 			// 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
@@ -131,6 +135,13 @@ export function useTooltipPortalRelocator(
 			if ( focusedElement ) {
 				focusedElement.focus();
 			}
+
+			// Reveal after two animation frames so visx has positioned the tooltip.
+			requestAnimationFrame( () => {
+				requestAnimationFrame( () => {
+					node.style.opacity = '';
+				} );
+			} );
 		};
 
 		// Patch document.body.removeChild so visx Portal unmount doesn't throw

package/src/types.ts

@@ -7,6 +7,7 @@ import type { LegendShape } from '@visx/legend/lib/types';
 import type { ScaleInput, ScaleType } from '@visx/scale';
 import type { TextProps } from '@visx/text/lib/Text';
 import type { EventHandlerParams, GlyphProps, GridStyles, LineStyles } from '@visx/xychart';
+import type { GapSize } from '@wordpress/theme';
 import type { CSSProperties, PointerEvent, ReactNode } from 'react';
 import type { GoogleDataTableColumn, GoogleDataTableRow } from 'react-google-charts';
 
@@ -364,15 +365,17 @@ export type BaseChartProps< T = DataPoint | DataPointDate | LeaderboardEntry > =
 	 */
 	className?: string;
 	/**
-	 * Width of the chart in pixels
+	 * Width of the chart container in pixels. When omitted, the chart fills its parent's width.
 	 */
 	width?: number;
 	/**
-	 * Height of the chart in pixels
+	 * Height of the chart container in pixels. When omitted, the chart fills its parent's height.
 	 */
 	height?: number;
 	/**
-	 * Size of the chart in pixels for pie and donut charts
+	 * Maximum diameter of the pie in pixels (pie and donut charts only).
+	 * The pie will shrink if the container is smaller than this value.
+	 * When omitted, the pie fills the available space.
 	 */
 	size?: number;
 	/**
@@ -457,6 +460,13 @@ export type BaseChartProps< T = DataPoint | DataPointDate | LeaderboardEntry > =
 	 */
 	animation?: boolean;
 
+	/**
+	 * Gap between chart elements (SVG, legend, children).
+	 * Uses WordPress design system tokens.
+	 * @default 'md'
+	 */
+	gap?: GapSize;
+
 	/**
 	 * More options for the chart.
 	 */