@automattic/charts 1.4.2 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "1.4.2",
+	"version": "1.5.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -63,7 +63,7 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.1.10",
+		"@automattic/number-formatters": "^1.2.0",
 		"@babel/runtime": "7.29.2",
 		"@react-spring/web": "9.7.5",
 		"@visx/annotation": "^3.12.0",
@@ -83,9 +83,9 @@
 		"@visx/vendor": "^3.12.0",
 		"@visx/xychart": "^3.12.0",
 		"@wordpress/i18n": "^6.0.0",
-		"@wordpress/icons": "^12.0.0",
+		"@wordpress/icons": "^13.0.0",
 		"@wordpress/theme": "0.13.0",
-		"@wordpress/ui": "0.11.0",
+		"@wordpress/ui": "0.13.0",
 		"clsx": "2.1.1",
 		"date-fns": "^4.1.0",
 		"deepmerge": "4.3.1",

package/src/charts/area-chart/area-chart.tsx

@@ -35,6 +35,7 @@ import { SingleChartContext, type SingleChartRef } from '../private/single-chart
 import { SvgEmptyState } from '../private/svg-empty-state';
 import { getCurveType, getFormatter, guessOptimalNumTicks } from '../private/time-axis';
 import { withResponsive } from '../private/with-responsive';
+import { useXZoom, ZoomResetButton, ZoomSelectionRect } from '../private/x-zoom';
 import styles from './area-chart.module.scss';
 import { AreaChartScalesRef, HoverGlyphs, validateData } from './private';
 import type { AreaChartProps } from './types';
@@ -68,6 +69,8 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 			onPointerUp,
 			onPointerMove,
 			onPointerOut,
+			zoomable = false,
+			rescaleYOnLegendToggle = true,
 			children,
 			gridVisibility,
 			gap = 'md',
@@ -86,6 +89,12 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 		const [ isNavigating, setIsNavigating ] = useState( false );
 		const internalChartRef = useRef< SingleChartRef >( null );
 
+		const zoom = useXZoom< Date >( {
+			enabled: zoomable,
+			chartRef: internalChartRef,
+			userHandlers: { onPointerDown, onPointerMove, onPointerUp },
+		} );
+
 		const { legendChildren, nonLegendChildren } = useChartChildren( children, 'AreaChart' );
 		const [ measuredChartHeight, setMeasuredChartHeight ] = useState< number | undefined >();
 
@@ -136,12 +145,14 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 		} );
 
 		// Computed from the full data set (ignoring legend visibility) so the y-axis stays
-		// fixed when series are toggled off — otherwise visx auto-fits to the remaining data
-		// and the chart appears to rescale. Skipped for non-default stack offsets, which
-		// reshape the y-extent (`expand` → [0,1], `wiggle`/`silhouette` → centred around
-		// zero) — letting visx derive the domain is correct there.
+		// fixed when series are toggled off - otherwise visx auto-fits to the remaining
+		// data and the chart's baseline appears to move. Opt-in via
+		// `rescaleYOnLegendToggle={ false }`. Skipped for non-default stack offsets,
+		// which reshape the y-extent (`expand` -> [0,1], `wiggle`/`silhouette` -> centred
+		// around zero); letting visx derive the domain is correct there.
 		const fixedYDomain = useMemo< [ number, number ] | undefined >( () => {
 			if (
+				rescaleYOnLegendToggle ||
 				! legendInteractive ||
 				! dataSorted.length ||
 				! dataSorted[ 0 ].data.length ||
@@ -184,7 +195,7 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 			}
 			if ( max === -Infinity ) return undefined;
 			return [ Math.min( 0, min ), max ];
-		}, [ dataSorted, stacked, stackOffset, legendInteractive ] );
+		}, [ dataSorted, stacked, stackOffset, legendInteractive, rescaleYOnLegendToggle ] );
 
 		const chartOptions = useMemo( () => {
 			const formatter = options?.axis?.x?.tickFormat || getFormatter( dataSorted );
@@ -209,6 +220,7 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 				xScale: {
 					type: 'time' as const,
 					...options?.xScale,
+					...( zoom.domain ? { domain: zoom.domain } : {} ),
 				},
 				yScale: {
 					type: 'linear' as const,
@@ -219,7 +231,7 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 					...options?.yScale,
 				},
 			};
-		}, [ options, dataSorted, width, stacked, fixedYDomain ] );
+		}, [ options, dataSorted, width, stacked, fixedYDomain, zoom.domain ] );
 
 		const defaultMargin = useChartMargin( height, chartOptions, dataSorted, theme );
 
@@ -378,7 +390,8 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 								onBlur={ onChartBlur }
 							>
 								{ chartHeight > 0 && (
-									<div ref={ chartRef }>
+									<div ref={ chartRef } style={ { position: 'relative' } }>
+										{ zoomable && zoom.domain && <ZoomResetButton onClick={ zoom.reset } /> }
 										<XYChart
 											theme={ theme }
 											width={ width }
@@ -386,9 +399,9 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 											margin={ { ...defaultMargin, ...margin } }
 											xScale={ chartOptions.xScale }
 											yScale={ chartOptions.yScale }
-											onPointerDown={ onPointerDown }
-											onPointerUp={ onPointerUp }
-											onPointerMove={ onPointerMove }
+											onPointerDown={ zoom.handlers.onPointerDown }
+											onPointerUp={ zoom.handlers.onPointerUp }
+											onPointerMove={ zoom.handlers.onPointerMove }
 											onPointerOut={ onPointerOut }
 											pointerEventsDataKey="nearest"
 										>
@@ -456,6 +469,7 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 												height={ height || chartHeight }
 												margin={ margin }
 											/>
+											{ zoomable && <ZoomSelectionRect drag={ zoom.drag } /> }
 										</XYChart>
 									</div>
 								) }

package/src/charts/area-chart/test/area-chart.test.tsx

@@ -240,7 +240,7 @@ describe( 'AreaChart', () => {
 			expect( keyboardCall![ 0 ].tooltipData?.nearestDatum?.key ).not.toBe( 'Series A' );
 		} );
 
-		test( 'y-axis domain stays fixed across legend toggles', async () => {
+		test( 'y-axis rescales across legend toggles by default', async () => {
 			const user = userEvent.setup();
 			const ref = createRef< SingleChartRef >();
 			render(
@@ -248,7 +248,7 @@ describe( 'AreaChart', () => {
 					<AreaChartUnresponsive
 						{ ...defaultProps }
 						showLegend
-						chartId="test-interactive-domain"
+						chartId="test-interactive-domain-rescale"
 						legend={ { interactive: true } }
 						ref={ ref }
 					/>
@@ -262,13 +262,82 @@ describe( 'AreaChart', () => {
 
 			await user.click( screen.getByText( 'Series A' ) );
 
+			const afterToggleDomain = (
+				ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined
+			 )?.domain();
+			// Hiding Series A drops the upper bound; visx should refit.
+			expect( afterToggleDomain ).toBeDefined();
+			expect( afterToggleDomain![ 1 ] ).toBeLessThan( initialDomain![ 1 ] );
+		} );
+
+		test( 'y-axis stays pinned for unstacked area when rescaleYOnLegendToggle is false', async () => {
+			// Exercises the non-stacked branch of fixedYDomain, which scans the
+			// raw min/max across all series rather than summing stack columns.
+			const user = userEvent.setup();
+			const ref = createRef< SingleChartRef >();
+			render(
+				<GlobalChartsProvider>
+					<AreaChartUnresponsive
+						{ ...defaultProps }
+						showLegend
+						chartId="test-interactive-domain-pin-unstacked"
+						legend={ { interactive: true } }
+						stacked={ false }
+						rescaleYOnLegendToggle={ false }
+						ref={ ref }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			const initialDomain = (
+				ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined
+			 )?.domain();
+			expect( initialDomain ).toBeDefined();
+			// defaultProps has values up to 20; pinned-unstacked should cover the max.
+			expect( initialDomain![ 1 ] ).toBeGreaterThanOrEqual( 20 );
+
+			await user.click( screen.getByText( 'Series A' ) );
+
+			const afterToggleDomain = (
+				ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined
+			 )?.domain();
+			expect( afterToggleDomain ).toEqual( initialDomain );
+		} );
+
+		test( 'y-axis stays pinned when rescaleYOnLegendToggle is false', async () => {
+			const user = userEvent.setup();
+			const ref = createRef< SingleChartRef >();
+			render(
+				<GlobalChartsProvider>
+					<AreaChartUnresponsive
+						{ ...defaultProps }
+						showLegend
+						chartId="test-interactive-domain-pin"
+						legend={ { interactive: true } }
+						rescaleYOnLegendToggle={ false }
+						ref={ ref }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			const initialDomain = (
+				ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined
+			 )?.domain();
+			expect( initialDomain ).toBeDefined();
+
+			await user.click( screen.getByText( 'Series A' ) );
+
 			const afterToggleDomain = (
 				ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined
 			 )?.domain();
 			expect( afterToggleDomain ).toEqual( initialDomain );
 		} );
 
-		test( 'supports negative stacked values without clipping', () => {
+		test( 'supports negative stacked values without clipping (with pinned Y)', () => {
+			// The mixed-sign full-extent pin only kicks in when the consumer
+			// opts into pinned-Y behavior; visx's natural domain derivation for
+			// a `stackOffset: 'none'` stack does not extend below zero for
+			// purely-negative series, which is what this test guards against.
 			const ref = createRef< SingleChartRef >();
 			render(
 				<GlobalChartsProvider>
@@ -278,6 +347,7 @@ describe( 'AreaChart', () => {
 						chartId="test-interactive-negative"
 						showLegend
 						legend={ { interactive: true } }
+						rescaleYOnLegendToggle={ false }
 						data={ [
 							{
 								label: 'Pos',

package/src/charts/area-chart/types.ts

@@ -47,5 +47,20 @@ export interface AreaChartProps extends BaseChartProps< SeriesData[] > {
 	 * @default false when stacked, true when overlapping
 	 */
 	withStroke?: boolean;
+	/**
+	 * Enable drag-to-zoom on the X axis. The user drags horizontally to
+	 * select a range; the X axis rescales to that range. A small reset
+	 * button appears in the top-right of the chart while zoomed.
+	 */
+	zoomable?: boolean;
+	/**
+	 * When using an interactive legend, controls whether the Y axis rescales
+	 * to fit only the visible series. Defaults to `true`, matching the
+	 * intuitive default for LineChart and BarChart. Set to `false` to pin
+	 * the Y axis to the full data extent so toggling legend items off does
+	 * not move the chart's baseline.
+	 * @default true
+	 */
+	rescaleYOnLegendToggle?: boolean;
 	children?: ReactNode;
 }

package/src/charts/line-chart/line-chart.tsx

@@ -37,6 +37,7 @@ import { SingleChartContext, type SingleChartRef } from '../private/single-chart
 import { SvgEmptyState } from '../private/svg-empty-state';
 import { getCurveType, getFormatter, guessOptimalNumTicks } from '../private/time-axis';
 import { withResponsive } from '../private/with-responsive';
+import { useXZoom, ZoomResetButton, ZoomSelectionRect } from '../private/x-zoom';
 import styles from './line-chart.module.scss';
 import { LineChartAnnotation, LineChartAnnotationsOverlay, LineChartGlyph } from './private';
 import type { RenderLineGlyphProps, LineChartProps, TooltipDatum } from './types';
@@ -177,6 +178,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 			onPointerUp = undefined,
 			onPointerMove = undefined,
 			onPointerOut = undefined,
+			zoomable = false,
 			children,
 			gridVisibility,
 			gap = 'md',
@@ -195,6 +197,12 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 		const [ isNavigating, setIsNavigating ] = useState( false );
 		const internalChartRef = useRef< SingleChartRef >( null );
 
+		const zoom = useXZoom< Date >( {
+			enabled: zoomable,
+			chartRef: internalChartRef,
+			userHandlers: { onPointerDown, onPointerMove, onPointerUp },
+		} );
+
 		// Process children for composition API (Legend, etc.)
 		const { legendChildren, nonLegendChildren } = useChartChildren( children, 'LineChart' );
 		const [ measuredChartHeight, setMeasuredChartHeight ] = useState< number | undefined >();
@@ -273,6 +281,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 				xScale: {
 					type: 'time' as const,
 					...options?.xScale,
+					...( zoom.domain ? { domain: zoom.domain } : {} ),
 				},
 				yScale: {
 					type: 'linear' as const,
@@ -281,7 +290,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 					...options?.yScale,
 				},
 			};
-		}, [ options, dataSorted, width ] );
+		}, [ options, dataSorted, width, zoom.domain ] );
 
 		const tooltipRenderGlyph = useMemo( () => {
 			return ( props: GlyphProps< DataPointDate > ) => {
@@ -412,7 +421,8 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 								onBlur={ onChartBlur }
 							>
 								{ chartHeight > 0 && (
-									<div ref={ chartRef }>
+									<div ref={ chartRef } style={ { position: 'relative' } }>
+										{ zoomable && zoom.domain && <ZoomResetButton onClick={ zoom.reset } /> }
 										<XYChart
 											theme={ theme }
 											width={ width }
@@ -424,9 +434,9 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 											// xScale and yScale could be set in Axis as well, but they are `scale` props there.
 											xScale={ chartOptions.xScale }
 											yScale={ chartOptions.yScale }
-											onPointerDown={ onPointerDown }
-											onPointerUp={ onPointerUp }
-											onPointerMove={ onPointerMove }
+											onPointerDown={ zoom.handlers.onPointerDown }
+											onPointerUp={ zoom.handlers.onPointerUp }
+											onPointerMove={ zoom.handlers.onPointerMove }
 											onPointerOut={ onPointerOut }
 											pointerEventsDataKey="nearest"
 										>
@@ -556,6 +566,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 												height={ height }
 												margin={ margin }
 											/>
+											{ zoomable && <ZoomSelectionRect drag={ zoom.drag } /> }
 										</XYChart>
 									</div>
 								) }

package/src/charts/line-chart/types.ts

@@ -41,6 +41,12 @@ export interface LineChartProps extends BaseChartProps< SeriesData[] > {
 		showVertical?: boolean;
 		showHorizontal?: boolean;
 	};
+	/**
+	 * Enable drag-to-zoom on the X axis. The user drags horizontally to
+	 * select a range; the X axis rescales to that range. A small reset
+	 * button appears in the top-right of the chart while zoomed.
+	 */
+	zoomable?: boolean;
 	children?: ReactNode;
 }
 

package/src/charts/private/test/x-zoom.test.tsx

@@ -0,0 +1,142 @@
+import { act, renderHook } from '@testing-library/react';
+import { useRef } from 'react';
+import { useXZoom } from '../x-zoom';
+import type { SingleChartRef } from '../single-chart-context';
+import type { EventHandlerParams } from '@visx/xychart';
+
+// A fake scale that lets the hook convert pixel positions to data values.
+// The hook only uses `.invert()`; everything else can be stubbed.
+const fakeXScale = ( ( x: number ) => x * 2 ) as unknown as ( ( v: number ) => number ) & {
+	invert: ( v: number ) => number;
+};
+( fakeXScale as unknown as { invert: ( v: number ) => number } ).invert = v => v * 2;
+
+const makeChartRef = (
+	scale: { invert?: ( v: number ) => unknown } | null = fakeXScale as unknown as {
+		invert: ( v: number ) => unknown;
+	}
+) =>
+	( {
+		current: {
+			getScales: () => ( scale ? { xScale: scale, yScale: scale } : null ),
+			getChartDimensions: () => ( { width: 0, height: 0, margin: {} } ),
+		},
+	} ) as unknown as ReturnType< typeof useRef< SingleChartRef > >;
+
+const makeParams = ( x: number ): EventHandlerParams< object > =>
+	( {
+		key: '',
+		index: 0,
+		datum: {},
+		event: new Event( 'pointerdown' ) as unknown as PointerEvent,
+		svgPoint: { x, y: 0 },
+	} ) as unknown as EventHandlerParams< object >;
+
+describe( 'useXZoom', () => {
+	test( 'commits a domain on pointerup after dragging more than minDragPixels', () => {
+		const chartRef = makeChartRef();
+		const { result } = renderHook( () => useXZoom< number >( { enabled: true, chartRef } ) );
+
+		act( () => result.current.handlers.onPointerDown( makeParams( 100 ) ) );
+		act( () => result.current.handlers.onPointerMove( makeParams( 200 ) ) );
+		act( () => result.current.handlers.onPointerUp( makeParams( 200 ) ) );
+
+		// fakeXScale.invert(x) = x * 2.
+		expect( result.current.domain ).toEqual( [ 200, 400 ] );
+		expect( result.current.drag ).toBeNull();
+	} );
+
+	test( 'discards drags shorter than minDragPixels', () => {
+		const chartRef = makeChartRef();
+		const { result } = renderHook( () => useXZoom< number >( { enabled: true, chartRef } ) );
+
+		act( () => result.current.handlers.onPointerDown( makeParams( 100 ) ) );
+		act( () => result.current.handlers.onPointerMove( makeParams( 103 ) ) );
+		act( () => result.current.handlers.onPointerUp( makeParams( 103 ) ) );
+
+		expect( result.current.domain ).toBeNull();
+		expect( result.current.drag ).toBeNull();
+	} );
+
+	test( 'normalises right-to-left drags', () => {
+		const chartRef = makeChartRef();
+		const { result } = renderHook( () => useXZoom< number >( { enabled: true, chartRef } ) );
+
+		act( () => result.current.handlers.onPointerDown( makeParams( 300 ) ) );
+		act( () => result.current.handlers.onPointerMove( makeParams( 100 ) ) );
+		act( () => result.current.handlers.onPointerUp( makeParams( 100 ) ) );
+
+		expect( result.current.domain ).toEqual( [ 200, 600 ] );
+	} );
+
+	test( 'reset clears the committed domain', () => {
+		const chartRef = makeChartRef();
+		const { result } = renderHook( () => useXZoom< number >( { enabled: true, chartRef } ) );
+
+		act( () => result.current.handlers.onPointerDown( makeParams( 100 ) ) );
+		act( () => result.current.handlers.onPointerMove( makeParams( 200 ) ) );
+		act( () => result.current.handlers.onPointerUp( makeParams( 200 ) ) );
+		expect( result.current.domain ).not.toBeNull();
+		act( () => result.current.reset() );
+		expect( result.current.domain ).toBeNull();
+	} );
+
+	test( 'is a passthrough when disabled', () => {
+		const chartRef = makeChartRef();
+		const userOnPointerDown = jest.fn();
+		const { result } = renderHook( () =>
+			useXZoom< number >( {
+				enabled: false,
+				chartRef,
+				userHandlers: { onPointerDown: userOnPointerDown },
+			} )
+		);
+
+		act( () => result.current.handlers.onPointerDown( makeParams( 100 ) ) );
+		act( () => result.current.handlers.onPointerMove( makeParams( 200 ) ) );
+		act( () => result.current.handlers.onPointerUp( makeParams( 200 ) ) );
+
+		expect( userOnPointerDown ).toHaveBeenCalledTimes( 1 );
+		expect( result.current.domain ).toBeNull();
+		expect( result.current.drag ).toBeNull();
+	} );
+
+	test( 'forwards events to user handlers when zoom is enabled', () => {
+		const chartRef = makeChartRef();
+		const userOnPointerDown = jest.fn();
+		const userOnPointerMove = jest.fn();
+		const userOnPointerUp = jest.fn();
+		const { result } = renderHook( () =>
+			useXZoom< number >( {
+				enabled: true,
+				chartRef,
+				userHandlers: {
+					onPointerDown: userOnPointerDown,
+					onPointerMove: userOnPointerMove,
+					onPointerUp: userOnPointerUp,
+				},
+			} )
+		);
+
+		act( () => result.current.handlers.onPointerDown( makeParams( 100 ) ) );
+		act( () => result.current.handlers.onPointerMove( makeParams( 200 ) ) );
+		act( () => result.current.handlers.onPointerUp( makeParams( 200 ) ) );
+
+		expect( userOnPointerDown ).toHaveBeenCalledTimes( 1 );
+		expect( userOnPointerMove ).toHaveBeenCalledTimes( 1 );
+		expect( userOnPointerUp ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'leaves domain null when the X scale has no invert function', () => {
+		const chartRef = makeChartRef( {
+			/* no invert */
+		} );
+		const { result } = renderHook( () => useXZoom< number >( { enabled: true, chartRef } ) );
+
+		act( () => result.current.handlers.onPointerDown( makeParams( 100 ) ) );
+		act( () => result.current.handlers.onPointerMove( makeParams( 200 ) ) );
+		act( () => result.current.handlers.onPointerUp( makeParams( 200 ) ) );
+
+		expect( result.current.domain ).toBeNull();
+	} );
+} );

package/src/charts/private/x-zoom.module.scss

@@ -0,0 +1,45 @@
+.x-zoom {
+
+	&__selection {
+		fill: var(--charts-zoom-selection-fill, rgba(56, 88, 233, 0.16));
+		stroke: var(--charts-zoom-selection-stroke, rgba(56, 88, 233, 0.65));
+		stroke-width: var(--wpds-border-width-xs, 1px);
+		pointer-events: none;
+	}
+
+	&__reset {
+		position: absolute;
+		top: var(--wpds-dimension-gap-sm, 8px);
+		right: var(--wpds-dimension-gap-sm, 8px);
+		z-index: 2;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 28px;
+		height: 28px;
+		padding: 0;
+		background: var(--charts-zoom-reset-bg, rgba(255, 255, 255, 0.92));
+		color: var(--charts-zoom-reset-fg, #1e1e1e);
+		border:
+			var(--wpds-border-width-xs, 1px) solid
+			var(--charts-zoom-reset-border, rgba(0, 0, 0, 0.16));
+		border-radius: var(--wpds-border-radius-md, 4px);
+		cursor: pointer;
+		box-shadow: 0 1px 2px rgba(0, 0, 0, 0.08);
+
+		&:hover {
+			background: var(--charts-zoom-reset-bg-hover, rgba(255, 255, 255, 1));
+		}
+
+		&:focus-visible {
+			outline: 2px solid var(--charts-zoom-reset-focus, #3858e9);
+			outline-offset: 1px;
+		}
+	}
+
+	&__reset-icon {
+		width: 16px;
+		height: 16px;
+		flex-shrink: 0;
+	}
+}