@automattic/charts 1.11.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "1.11.0",
+	"version": "1.12.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -105,6 +105,7 @@
 		"@testing-library/user-event": "^14.4.3",
 		"@tsdown/css": "0.22.2",
 		"@types/jest": "^30.0.0",
+		"@types/node": "^24.12.0",
 		"@types/react": "18.3.28",
 		"@types/react-dom": "18.3.7",
 		"@typescript/native-preview": "7.0.0-dev.20260707.2",

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

@@ -70,7 +70,8 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 			onPointerMove,
 			onPointerOut,
 			zoomable = false,
-			rescaleYOnLegendToggle = true,
+			rescaleYOnVisibilityChange,
+			rescaleYOnLegendToggle,
 			children,
 			gridVisibility,
 			gap = 'md',
@@ -81,6 +82,9 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 		const legendShape = legend.shape ?? 'rect';
 		const legendPosition = legend.position ?? 'bottom';
 
+		// New prop wins; fall back to the deprecated `rescaleYOnLegendToggle`; default to rescaling.
+		const rescaleYOnVisibility = rescaleYOnVisibilityChange ?? rescaleYOnLegendToggle ?? true;
+
 		const providerTheme = useGlobalChartsTheme();
 		const theme = useXYChartTheme( data );
 		const chartId = useChartId( providedChartId );
@@ -147,12 +151,12 @@ 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's baseline appears to move. Opt-in via
-		// `rescaleYOnLegendToggle={ false }`. Skipped for non-default stack offsets,
+		// `rescaleYOnVisibilityChange={ 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 ||
+				rescaleYOnVisibility ||
 				! legendInteractive ||
 				! dataSorted.length ||
 				! dataSorted[ 0 ].data.length ||
@@ -195,7 +199,7 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 			}
 			if ( max === -Infinity ) return undefined;
 			return [ Math.min( 0, min ), max ];
-		}, [ dataSorted, stacked, stackOffset, legendInteractive, rescaleYOnLegendToggle ] );
+		}, [ dataSorted, stacked, stackOffset, legendInteractive, rescaleYOnVisibility ] );
 
 		const chartOptions = useMemo( () => {
 			const formatter = options?.axis?.x?.tickFormat || getFormatter( dataSorted );
@@ -238,7 +242,14 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 		const error = validateData( dataSorted );
 		const isDataValid = ! error;
 
-		const legendOptions = useMemo( () => ( { withGlyph: false, glyphSize: 0 } ), [] );
+		const legendOptions = useMemo(
+			() => ( {
+				withGlyph: false,
+				glyphSize: 0,
+				collapseGroups: legend.collapseGroups ?? false,
+			} ),
+			[ legend.collapseGroups ]
+		);
 		const legendItems = useChartLegendItems( dataSorted, legendOptions, legendShape );
 
 		const chartMetadata = useMemo(
@@ -405,9 +416,18 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 											onPointerOut={ onPointerOut }
 											pointerEventsDataKey="nearest"
 										>
-											{ gridVisibility !== 'none' && <Grid columns={ false } numTicks={ 4 } /> }
-											{ chartOptions.axis.x.display && <Axis { ...chartOptions.axis.x } /> }
-											{ chartOptions.axis.y.display && <Axis { ...chartOptions.axis.y } /> }
+											{ /* With every series hidden the value scale collapses, so the grid and axes
+											     are dropped while the empty state stands in — otherwise they render
+											     squished at the top. */ }
+											{ ! allSeriesHidden && gridVisibility !== 'none' && (
+												<Grid columns={ false } numTicks={ 4 } />
+											) }
+											{ ! allSeriesHidden && chartOptions.axis.x.display && (
+												<Axis { ...chartOptions.axis.x } />
+											) }
+											{ ! allSeriesHidden && chartOptions.axis.y.display && (
+												<Axis { ...chartOptions.axis.y } />
+											) }
 
 											{ allSeriesHidden ? (
 												<SvgEmptyState

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

@@ -333,6 +333,35 @@ describe( 'AreaChart', () => {
 			expect( afterToggleDomain ).toEqual( initialDomain );
 		} );
 
+		test( 'y-axis stays pinned when rescaleYOnVisibilityChange is false', async () => {
+			const user = userEvent.setup();
+			const ref = createRef< SingleChartRef >();
+			render(
+				<GlobalChartsProvider>
+					<AreaChartUnresponsive
+						{ ...defaultProps }
+						showLegend
+						chartId="test-interactive-domain-pin-new"
+						legend={ { interactive: true } }
+						rescaleYOnVisibilityChange={ 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 (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
@@ -544,4 +573,77 @@ describe( 'AreaChart', () => {
 			'url(#chart-zoom-clip-zoomtest)'
 		);
 	} );
+
+	describe( 'Legend group collapsing', () => {
+		const groupedData = [
+			{
+				label: 'Views',
+				group: 'views',
+				data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
+			},
+			{
+				label: 'Views — previous',
+				group: 'views',
+				options: { type: 'comparison' as const },
+				data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+			},
+		];
+
+		test( 'renders one legend item per series by default', () => {
+			renderWithProvider( { showLegend: true, data: groupedData } );
+
+			expect( screen.getByText( 'Views' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Views — previous' ) ).toBeInTheDocument();
+		} );
+
+		test( 'collapses a group to one item when legend.collapseGroups is set', () => {
+			renderWithProvider( {
+				showLegend: true,
+				legend: { collapseGroups: true },
+				data: groupedData,
+			} );
+
+			expect( screen.getByText( 'Views' ) ).toBeInTheDocument();
+			expect( screen.queryByText( 'Views — previous' ) ).not.toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'All series hidden', () => {
+		it( 'drops the grid so it does not collapse when every series is hidden', async () => {
+			const user = userEvent.setup();
+
+			renderWithProvider( {
+				showLegend: true,
+				legend: { interactive: true },
+				chartId: 'area-hidden-axes',
+				data: [
+					{
+						label: 'Series A',
+						data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+					},
+					{
+						label: 'Series B',
+						data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
+					},
+				],
+			} );
+
+			// The visx grid has no role/testid, so query its internal class from within the plot.
+			/* eslint-disable testing-library/no-node-access */
+			const plot = screen.getByRole( 'grid' );
+			expect( plot.querySelector( '.visx-rows' ) ).toBeInTheDocument();
+
+			const buttons = screen.getAllByRole( 'button' );
+			await user.click( buttons[ 0 ] );
+			await user.click( buttons[ 1 ] );
+
+			// With no visible data the value scale collapses, so the grid is removed rather than
+			// rendered squished at the top behind the empty state.
+			expect( plot.querySelector( '.visx-rows' ) ).not.toBeInTheDocument();
+			/* eslint-enable testing-library/no-node-access */
+			expect(
+				screen.getByText( /all series are hidden.*click legend items to show data/i )
+			).toBeInTheDocument();
+		} );
+	} );
 } );

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

@@ -1,9 +1,18 @@
-import type { BaseChartProps, DataPointDate, SeriesData } from '../../types';
+import type {
+	BaseChartProps,
+	DataPointDate,
+	SeriesData,
+	SeriesChartLegendConfig,
+} from '../../types';
 import type { RenderTooltipParams } from '../../visx/types';
 import type { CurveType } from '../line-chart/types';
 import type { ReactNode } from 'react';
 
 export interface AreaChartProps extends BaseChartProps< SeriesData[] > {
+	/**
+	 * Legend configuration. Supports `collapseGroups` on top of the shared options.
+	 */
+	legend?: SeriesChartLegendConfig;
 	/**
 	 * Whether series should be stacked on top of each other.
 	 * When false, series are rendered as overlapping filled areas.
@@ -54,13 +63,18 @@ export interface AreaChartProps extends BaseChartProps< SeriesData[] > {
 	 */
 	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.
+	 * Whether the Y axis rescales to fit only the visible series when series are
+	 * hidden or shown through the interactive legend.
+	 * Defaults to `true`, matching LineChart. Set to `false` to pin the Y axis to
+	 * the full data extent so hiding series does not move the chart's baseline.
 	 * @default true
 	 */
+	rescaleYOnVisibilityChange?: boolean;
+	/**
+	 * @deprecated Use `rescaleYOnVisibilityChange`. The behaviour keys off series
+	 * visibility changing, not specifically a legend toggle. Still honoured when
+	 * `rescaleYOnVisibilityChange` is not set.
+	 */
 	rescaleYOnLegendToggle?: boolean;
 	children?: ReactNode;
 }

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

@@ -37,12 +37,22 @@ import {
 	BASE_BAND_PADDING_INNER,
 } from './private';
 import type { ComparisonSeriesEntry } from './private';
-import type { BaseChartProps, DataPointDate, SeriesData, Optional } from '../../types';
+import type {
+	BaseChartProps,
+	DataPointDate,
+	SeriesData,
+	SeriesChartLegendConfig,
+	Optional,
+} from '../../types';
 import type { RenderTooltipParams } from '../../visx/types';
 import type { ResponsiveConfig } from '../private/with-responsive';
 import type { FC, ReactNode, ComponentType } from 'react';
 
 export interface BarChartProps extends BaseChartProps< SeriesData[] > {
+	/**
+	 * Legend configuration. Supports `collapseGroups` on top of the shared options.
+	 */
+	legend?: SeriesChartLegendConfig;
 	renderTooltip?: ( params: RenderTooltipParams< DataPointDate > ) => ReactNode;
 	orientation?: 'horizontal' | 'vertical';
 	withPatterns?: boolean;
@@ -117,6 +127,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	gap = 'md',
 } ) => {
 	const legendInteractive = legend.interactive ?? false;
+	const legendCollapseGroups = legend.collapseGroups ?? false;
 	const horizontal = orientation === 'horizontal';
 	const chartId = useChartId( providedChartId );
 	const theme = useXYChartTheme( data );
@@ -131,7 +142,11 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	} );
 
 	// Create legend items using the reusable hook
-	const legendItems = useChartLegendItems( dataSorted );
+	const legendOptions = useMemo(
+		() => ( { collapseGroups: legendCollapseGroups } ),
+		[ legendCollapseGroups ]
+	);
+	const legendItems = useChartLegendItems( dataSorted, legendOptions );
 	const chartOptions = useBarChartOptions( dataWithVisibleZeros, horizontal, options );
 	const defaultMargin = useChartMargin( height, chartOptions, dataSorted, theme, horizontal );
 	const chartRef = useRef< HTMLDivElement >( null );
@@ -544,11 +559,13 @@ const BarChartInternal: FC< BarChartProps > = ( {
 										horizontal={ horizontal }
 										pointerEventsDataKey="nearest"
 									>
-										<Grid
-											columns={ gridVisibility.includes( 'y' ) }
-											rows={ gridVisibility.includes( 'x' ) }
-											numTicks={ 4 }
-										/>
+										{ ! allSeriesHidden && (
+											<Grid
+												columns={ gridVisibility.includes( 'y' ) }
+												rows={ gridVisibility.includes( 'x' ) }
+												numTicks={ 4 }
+											/>
+										) }
 
 										{ withPatterns && (
 											<>
@@ -615,8 +632,15 @@ const BarChartInternal: FC< BarChartProps > = ( {
 											) ) }
 										</BarGroup>
 
-										<Axis { ...chartOptions.axis.x } />
-										<Axis { ...chartOptions.axis.y } />
+										{ /* With every series hidden there is no data to build the value scale from, so
+										     visx collapses the domain and the axes render squished at the top. Drop them
+										     while the empty state stands in. */ }
+										{ ! allSeriesHidden && (
+											<>
+												<Axis { ...chartOptions.axis.x } />
+												<Axis { ...chartOptions.axis.y } />
+											</>
+										) }
 
 										{ withTooltips && (
 											<AccessibleTooltip

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

@@ -1194,5 +1194,122 @@ describe( 'BarChart', () => {
 				screen.getByText( /all series are hidden.*click legend items to show data/i )
 			).toBeInTheDocument();
 		} );
+
+		it( 'drops the value-axis ticks when all series are hidden so the axes do not collapse', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				gridVisibility: 'both',
+				legend: { interactive: true },
+				chartId: 'test-hidden-axes-bar-chart',
+				data: [
+					{
+						label: 'Series A',
+						data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+						options: {},
+					},
+					{
+						label: 'Series B',
+						data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
+						options: {},
+					},
+				],
+			} );
+
+			// The value axis renders numeric tick labels while there is data to scale against.
+			// (Series labels carry no digits and the empty-state message is text-only, so a bare
+			// number can only be an axis tick.)
+			const numericTick = /^[\d,]+$/;
+			expect( screen.getAllByText( numericTick ).length ).toBeGreaterThan( 0 );
+
+			const legendItems = screen.getAllByRole( 'button' );
+			await user.click( legendItems[ 0 ] );
+			await user.click( legendItems[ 1 ] );
+
+			// With no visible data the value scale would collapse, so the axes are removed rather
+			// than rendered squished at the top — no tick labels remain.
+			expect( screen.queryAllByText( numericTick ) ).toHaveLength( 0 );
+			expect(
+				screen.getByText( /all series are hidden.*click legend items to show data/i )
+			).toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'Legend group collapsing', () => {
+		const comparisonPair = [
+			{
+				label: 'Views',
+				group: 'views',
+				data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
+			},
+			{
+				label: 'Views — previous',
+				group: 'views',
+				options: { type: 'comparison' as const },
+				data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+			},
+		];
+
+		it( 'renders one legend item per series by default', () => {
+			renderWithTheme( {
+				showLegend: true,
+				chartId: 'bar-legend-groups-default',
+				data: comparisonPair,
+			} );
+
+			expect( screen.getByText( 'Views' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Views — previous' ) ).toBeInTheDocument();
+		} );
+
+		it( 'collapses a group to one item when legend.collapseGroups is set', () => {
+			renderWithTheme( {
+				showLegend: true,
+				legend: { collapseGroups: true },
+				chartId: 'bar-legend-groups-collapsed',
+				data: comparisonPair,
+			} );
+
+			expect( screen.getByText( 'Views' ) ).toBeInTheDocument();
+			expect( screen.queryByText( 'Views — previous' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'toggles only the clicked series when interactive without collapseGroups', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true },
+				chartId: 'bar-legend-groups-interactive',
+				data: comparisonPair,
+			} );
+
+			const buttons = screen.getAllByRole( 'button' );
+			await user.click( buttons[ 0 ] );
+
+			expect( buttons[ 0 ] ).toHaveAttribute( 'aria-pressed', 'false' );
+			expect( buttons[ 1 ] ).toHaveAttribute( 'aria-pressed', 'true' );
+		} );
+
+		it( 'toggles the whole group when interactive with collapseGroups', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true, collapseGroups: true },
+				chartId: 'bar-legend-groups-interactive-collapsed',
+				data: comparisonPair,
+			} );
+
+			const buttons = screen.getAllByRole( 'button' );
+			expect( buttons ).toHaveLength( 1 );
+
+			await user.click( buttons[ 0 ] );
+
+			expect( buttons[ 0 ] ).toHaveAttribute( 'aria-pressed', 'false' );
+			expect(
+				screen.getByText( /all series are hidden.*click legend items to show data/i )
+			).toBeInTheDocument();
+		} );
 	} );
 } );

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

@@ -179,6 +179,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 			onPointerMove = undefined,
 			onPointerOut = undefined,
 			zoomable = false,
+			rescaleYOnVisibilityChange = true,
 			children,
 			gridVisibility,
 			gap = 'md',
@@ -186,6 +187,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 		ref
 	) => {
 		const legendInteractive = legend.interactive ?? false;
+		const legendCollapseGroups = legend.collapseGroups ?? false;
 		const legendShape = legend.shape ?? 'line';
 		const legendPosition = legend.position ?? 'bottom';
 
@@ -252,6 +254,28 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 			return seriesWithVisibility.every( ( { isVisible } ) => ! isVisible );
 		}, [ seriesWithVisibility ] );
 
+		// When the interactive legend can hide series and rescaling is opted out, pin the value axis
+		// to the full data range so it stays put as series are toggled instead of visx rescaling the
+		// domain to whatever is currently visible and making the axis jump. Default is to rescale,
+		// matching the pre-existing behaviour and AreaChart's `rescaleYOnVisibilityChange`.
+		const stableYDomain = useMemo< [ number, number ] | undefined >( () => {
+			if ( ! legendInteractive || rescaleYOnVisibilityChange ) {
+				return undefined;
+			}
+			let min = Infinity;
+			let max = -Infinity;
+			for ( const series of dataSorted ) {
+				for ( const point of series.data ?? [] ) {
+					const value = point?.value;
+					if ( typeof value === 'number' && Number.isFinite( value ) ) {
+						min = Math.min( min, value );
+						max = Math.max( max, value );
+					}
+				}
+			}
+			return min < max ? [ min, max ] : undefined;
+		}, [ legendInteractive, rescaleYOnVisibilityChange, dataSorted ] );
+
 		// Use the keyboard navigation hook
 		const { tooltipRef, onChartFocus, onChartBlur, onChartKeyDown } = useKeyboardNavigation( {
 			selectedIndex,
@@ -291,10 +315,11 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 					type: 'linear' as const,
 					nice: true,
 					zero: false,
+					...( stableYDomain ? { domain: stableYDomain } : {} ),
 					...options?.yScale,
 				},
 			};
-		}, [ options, dataSorted, width, zoom.domain ] );
+		}, [ options, dataSorted, width, zoom.domain, stableYDomain ] );
 
 		const tooltipRenderGlyph = useMemo( () => {
 			return ( props: GlyphProps< DataPointDate > ) => {
@@ -328,9 +353,10 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 			() => ( {
 				withGlyph: withLegendGlyph,
 				glyphSize: Math.max( 0, toNumber( glyphStyle?.radius ) ?? 4 ),
+				collapseGroups: legendCollapseGroups,
 				renderGlyph,
 			} ),
-			[ withLegendGlyph, glyphStyle?.radius, renderGlyph ]
+			[ withLegendGlyph, glyphStyle?.radius, legendCollapseGroups, renderGlyph ]
 		);
 
 		// Create legend items using the reusable hook
@@ -444,9 +470,18 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 											onPointerOut={ onPointerOut }
 											pointerEventsDataKey="nearest"
 										>
-											{ gridVisibility !== 'none' && <Grid columns={ false } numTicks={ 4 } /> }
-											{ chartOptions.axis.x.display && <Axis { ...chartOptions.axis.x } /> }
-											{ chartOptions.axis.y.display && <Axis { ...chartOptions.axis.y } /> }
+											{ /* With every series hidden there is no data to scale against, so the grid and
+											     axes are dropped while the empty state stands in — otherwise they render
+											     squished at the top. */ }
+											{ ! allSeriesHidden && gridVisibility !== 'none' && (
+												<Grid columns={ false } numTicks={ 4 } />
+											) }
+											{ ! allSeriesHidden && chartOptions.axis.x.display && (
+												<Axis { ...chartOptions.axis.x } />
+											) }
+											{ ! allSeriesHidden && chartOptions.axis.y.display && (
+												<Axis { ...chartOptions.axis.y } />
+											) }
 
 											{ allSeriesHidden ? (
 												<SvgEmptyState