@automattic/charts 1.11.0 → 1.12.0

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

@@ -1,6 +1,6 @@
 /* eslint-disable react/jsx-no-bind */
 
-import { render, screen, waitFor } from '@testing-library/react';
+import { render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { GlyphDiamond } from '@visx/glyph';
 import { createElement, createRef } from 'react';
@@ -1294,4 +1294,193 @@ describe( 'LineChart', () => {
 			'url(#chart-zoom-clip-zoomtest)'
 		);
 	} );
+
+	describe( 'Legend group collapsing', () => {
+		const comparisonPair = [
+			{
+				label: 'Views',
+				group: 'views',
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' },
+					{ date: new Date( '2024-01-02' ), value: 20, label: 'Jan 2' },
+				],
+			},
+			{
+				label: 'Views — previous',
+				group: 'views',
+				options: { type: 'comparison' as const },
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 8, label: 'Jan 1' },
+					{ date: new Date( '2024-01-02' ), value: 16, label: 'Jan 2' },
+				],
+			},
+		];
+
+		it( 'renders one legend item per series by default', () => {
+			renderWithTheme( {
+				showLegend: true,
+				chartId: '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: '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: '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: '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();
+		} );
+	} );
+
+	describe( 'Interactive Legend — value axis', () => {
+		const twoSeries = [
+			{
+				label: 'Views',
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' },
+					{ date: new Date( '2024-01-02' ), value: 20, label: 'Jan 2' },
+				],
+				options: {},
+			},
+			{
+				label: 'Visitors',
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 100, label: 'Jan 1' },
+					{ date: new Date( '2024-01-02' ), value: 200, label: 'Jan 2' },
+				],
+				options: {},
+			},
+		];
+		// Bare numbers inside the plot (scoped via the chart's grid role, away from visx's
+		// off-screen text-measurement SVGs) are value-axis ticks: the series labels carry no digits
+		// and the empty-state message is text-only.
+		const numericTick = /^[\d,]+$/;
+
+		it( 'pins the value axis when rescaleYOnVisibilityChange is false', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true },
+				rescaleYOnVisibilityChange: false,
+				chartId: 'line-stable-axis',
+				data: twoSeries,
+			} );
+
+			const chart = screen.getByRole( 'grid' );
+			const ticksBefore = within( chart )
+				.getAllByText( numericTick )
+				.map( el => el.textContent )
+				.sort();
+			expect( ticksBefore.length ).toBeGreaterThan( 0 );
+
+			// Hide the high-range Visitors series; with a pinned domain the axis keeps its ticks.
+			await user.click( screen.getAllByRole( 'button' )[ 1 ] );
+
+			const ticksAfter = within( chart )
+				.getAllByText( numericTick )
+				.map( el => el.textContent )
+				.sort();
+			expect( ticksAfter ).toEqual( ticksBefore );
+		} );
+
+		it( 'rescales the value axis by default when a series is toggled off', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true },
+				chartId: 'line-rescale-axis',
+				data: twoSeries,
+			} );
+
+			const chart = screen.getByRole( 'grid' );
+			const ticksBefore = within( chart )
+				.getAllByText( numericTick )
+				.map( el => el.textContent )
+				.sort();
+			expect( ticksBefore.length ).toBeGreaterThan( 0 );
+
+			// Default preserves the pre-existing behaviour: hiding the high-range Visitors series
+			// lets the axis rescale to the remaining Views range, so its ticks change.
+			await user.click( screen.getAllByRole( 'button' )[ 1 ] );
+
+			const ticksAfter = within( chart )
+				.getAllByText( numericTick )
+				.map( el => el.textContent )
+				.sort();
+			expect( ticksAfter ).not.toEqual( ticksBefore );
+		} );
+
+		it( 'drops the axes when all series are hidden so they do not collapse', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true },
+				chartId: 'line-hidden-axes',
+				data: twoSeries,
+			} );
+
+			const chart = screen.getByRole( 'grid' );
+			expect( within( chart ).getAllByText( numericTick ).length ).toBeGreaterThan( 0 );
+
+			const buttons = screen.getAllByRole( 'button' );
+			await user.click( buttons[ 0 ] );
+			await user.click( buttons[ 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( within( chart ).queryAllByText( numericTick ) ).toHaveLength( 0 );
+			expect(
+				screen.getByText( /all series are hidden.*click legend items to show data/i )
+			).toBeInTheDocument();
+		} );
+	} );
 } );

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

@@ -2,6 +2,7 @@ import type {
 	BaseChartProps,
 	DataPointDate,
 	SeriesData,
+	SeriesChartLegendConfig,
 	AnnotationStyles,
 	DataPoint,
 } from '../../types';
@@ -28,6 +29,10 @@ export type RenderLineGlyphProps< Datum extends object > = GlyphProps< Datum > &
 };
 
 export interface LineChartProps extends BaseChartProps< SeriesData[] > {
+	/**
+	 * Legend configuration. Supports `collapseGroups` on top of the shared options.
+	 */
+	legend?: SeriesChartLegendConfig;
 	withGradientFill: boolean;
 	smoothing?: boolean;
 	curveType?: CurveType;
@@ -47,6 +52,15 @@ export interface LineChartProps extends BaseChartProps< SeriesData[] > {
 	 * button appears in the top-right of the chart while zoomed.
 	 */
 	zoomable?: boolean;
+	/**
+	 * Whether the Y axis rescales to fit only the visible series when series are
+	 * hidden or shown through the interactive legend.
+	 * Defaults to `true` (the pre-existing behaviour). Set to `false` to pin the Y
+	 * axis to the full data extent so hiding series does not move the chart's
+	 * baseline — useful for comparison charts. Matches `AreaChart`.
+	 * @default true
+	 */
+	rescaleYOnVisibilityChange?: boolean;
 	children?: ReactNode;
 }
 

package/src/charts/private/x-zoom/index.ts

@@ -0,0 +1 @@
+export { useXZoom, ZoomClip, ZoomResetButton, ZoomSelectionRect } from './x-zoom';

package/src/charts/private/{test → x-zoom/test}/x-zoom.test.tsx

@@ -1,8 +1,10 @@
-import { act, renderHook } from '@testing-library/react';
+import { act, render, renderHook, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { useRef } from 'react';
-import { useXZoom } from '../x-zoom';
-import type { SingleChartRef } from '../single-chart-context';
+import { useXZoom, ZoomResetButton } from '../index';
+import type { SingleChartRef } from '../../single-chart-context';
 import type { EventHandlerParams } from '@visx/xychart';
+import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
 
 // A fake scale that lets the hook convert pixel positions to data values.
 // The hook only uses `.invert()`; everything else can be stubbed.
@@ -140,3 +142,44 @@ describe( 'useXZoom', () => {
 		expect( result.current.domain ).toBeNull();
 	} );
 } );
+
+const preventDefaultKeydown = ( event: ReactKeyboardEvent< HTMLDivElement > ) =>
+	event.preventDefault();
+
+describe( 'ZoomResetButton', () => {
+	test( 'renders a labelled button with a hover tooltip', () => {
+		const noop = jest.fn();
+		render( <ZoomResetButton onClick={ noop } /> );
+		const button = screen.getByTestId( 'chart-zoom-reset' );
+		expect( button.tagName ).toBe( 'BUTTON' );
+		expect( button ).toHaveClass( 'x-zoom__reset' );
+		expect( button ).toHaveAccessibleName( 'Reset zoom' );
+		// WPDS `IconButton` would supply a tooltip of its own, but it pulls in a
+		// CommonJS dependency that breaks Script Module consumers (see
+		// ZoomResetButton). `title` restores the hover hint on plain `Button`.
+		expect( button ).toHaveAttribute( 'title', 'Reset zoom' );
+	} );
+
+	test( 'fires onClick when activated', async () => {
+		const onClick = jest.fn();
+		render( <ZoomResetButton onClick={ onClick } /> );
+		await userEvent.click( screen.getByTestId( 'chart-zoom-reset' ) );
+		expect( onClick ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'keyboard activation survives the chart wrapper keydown handler', async () => {
+		const onClick = jest.fn();
+		// Mirrors the chart's grid wrapper, whose keyboard-navigation handler
+		// calls preventDefault() on bubbled keydowns — which would cancel the
+		// native Enter/Space button activation.
+		render(
+			<div role="grid" tabIndex={ 0 } onKeyDown={ preventDefaultKeydown }>
+				<ZoomResetButton onClick={ onClick } />
+			</div>
+		);
+		act( () => screen.getByTestId( 'chart-zoom-reset' ).focus() );
+		await userEvent.keyboard( '{Enter}' );
+		await userEvent.keyboard( ' ' );
+		expect( onClick ).toHaveBeenCalledTimes( 2 );
+	} );
+} );

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

@@ -0,0 +1,43 @@
+.x-zoom {
+
+	// The selection's translucency lives in the SVG opacity properties so
+	// the colors themselves can come straight from WPDS tokens.
+	&__selection {
+		fill: var(--a8c-charts-color-zoom-selection, var(--wpds-color-background-interactive-brand-strong, #3858e9));
+		fill-opacity: 0.16;
+		stroke: var(--a8c-charts-color-zoom-selection-stroke, var(--wpds-color-stroke-interactive-brand, #3858e9));
+		stroke-opacity: 0.65;
+		stroke-width: var(--wpds-border-width-xs, 1px);
+		pointer-events: none;
+	}
+
+	// Overlay placement and icon-only geometry — the visual treatment (border,
+	// hover/focus, sizing) comes from the WPDS Button. The elevation shadow is
+	// deliberately kept for separation from chart content (CHARTS-237
+	// design call, carrying over CHARTS-200's tokenization).
+	&__reset {
+		position: absolute;
+		top: var(--wpds-dimension-gap-sm, 8px);
+		right: var(--wpds-dimension-gap-sm, 8px);
+		z-index: 2;
+		box-shadow: var(--wpds-elevation-xs, 0 1px 1px 0 #00000008, 0 1px 2px 0 #00000005, 0 3px 3px 0 #00000005, 0 4px 4px 0 #00000003);
+
+		// `Button` is sized for a text label. These are the same three custom
+		// properties @wordpress/ui's own IconButton composition sets to make a
+		// square icon-only control; we set them directly because IconButton
+		// itself cannot be used here — it renders a Base UI tooltip, whose
+		// CommonJS `use-sync-external-store` dependency makes Rolldown emit a
+		// dynamic `require()` that throws in Script Module consumers.
+		--wp-ui-button-aspect-ratio: 1;
+		--wp-ui-button-padding-inline: 0;
+		--wp-ui-button-min-width: unset;
+
+		// WPDS outline-neutral is transparent-bodied at rest; give this
+		// floating control an opaque body so chart content doesn't show
+		// through it. Scoped to the rest state so the WPDS
+		// hover/active/focus backgrounds still apply.
+		&:not(:hover, :active, :focus) {
+			background-color: var(--a8c-charts-color-background, var(--wpds-color-background-surface-neutral-strong, #fff));
+		}
+	}
+}

package/src/charts/private/{x-zoom.tsx → x-zoom/x-zoom.tsx}

@@ -1,11 +1,12 @@
 import { DataContext } from '@visx/xychart';
 import { __ } from '@wordpress/i18n';
+import { Button } from '@wordpress/ui';
 import { useCallback, useContext, useMemo, useState } from 'react';
 import styles from './x-zoom.module.scss';
-import type { SingleChartRef } from './single-chart-context';
+import type { SingleChartRef } from '../single-chart-context';
 import type { AxisScale } from '@visx/axis';
 import type { EventHandlerParams } from '@visx/xychart';
-import type { ReactNode, RefObject } from 'react';
+import type { KeyboardEvent, ReactNode, RefObject } from 'react';
 
 const MIN_DRAG_PIXELS = 6;
 
@@ -170,40 +171,67 @@ export function ZoomClip( {
 }
 
 /**
- * Visible icon-only reset button rendered as an HTML overlay on top of
- * the chart container. The host should wrap its SVG in a `position: relative`
- * container so the button anchors correctly.
+ * Visible icon-only reset control rendered as an HTML overlay on top of the
+ * chart container, using the WPDS `Button`. The host should wrap its SVG in a
+ * `position: relative` container so the button anchors correctly.
+ *
+ * `IconButton` would be the natural fit, but it renders a Base UI tooltip whose
+ * CommonJS `use-sync-external-store` dependency makes Rolldown emit a dynamic
+ * `require()` into `dist`, which throws on evaluation in WordPress Script
+ * Module consumers. `Button` gives the same treatment without that dependency;
+ * the tooltip is replaced by `aria-label` + `title`.
  *
  * @param props         - Props.
  * @param props.onClick - Click handler. Typically the `reset` from `useXZoom`.
  * @return JSX element.
  */
 export function ZoomResetButton( { onClick }: { onClick: () => void } ) {
+	// The chart's keyboard-navigation wrapper calls preventDefault() on
+	// bubbled keydowns, which would cancel the native Enter/Space button
+	// activation. Keep activation keys out of its reach.
+	const stopActivationKeys = useCallback( ( event: KeyboardEvent< HTMLButtonElement > ) => {
+		if ( event.key === 'Enter' || event.key === ' ' ) {
+			event.stopPropagation();
+		}
+	}, [] );
 	const label = __( 'Reset zoom', 'jetpack-charts' );
 	return (
-		<button
-			type="button"
+		<Button
 			className={ styles[ 'x-zoom__reset' ] }
-			onClick={ onClick }
+			onKeyDown={ stopActivationKeys }
 			aria-label={ label }
 			title={ label }
+			variant="outline"
+			tone="neutral"
+			size="small"
+			onClick={ onClick }
 			data-testid="chart-zoom-reset"
 		>
-			<svg
-				className={ styles[ 'x-zoom__reset-icon' ] }
-				viewBox="0 0 24 24"
-				fill="none"
-				stroke="currentColor"
-				strokeWidth="2"
-				strokeLinecap="round"
-				strokeLinejoin="round"
-				aria-hidden="true"
-				focusable="false"
-			>
-				<circle cx="10" cy="10" r="6" />
-				<line x1="15" y1="15" x2="20" y2="20" />
-				<line x1="7" y1="10" x2="13" y2="10" />
-			</svg>
-		</button>
+			<Button.Icon
+				icon={
+					<svg
+						viewBox="0 0 24 24"
+						fill="none"
+						stroke="currentColor"
+						strokeWidth="2"
+						strokeLinecap="round"
+						strokeLinejoin="round"
+						aria-hidden="true"
+						focusable="false"
+					>
+						{ /*
+							Icons render edge-to-edge at 24px, so inset the glyph the
+							way @wordpress/icons glyphs do (drawn within roughly 4-20
+							of the viewBox, ~1.5px effective stroke).
+						*/ }
+						<g transform="translate(2.4 2.4) scale(0.8)">
+							<circle cx="10" cy="10" r="6" />
+							<line x1="15" y1="15" x2="20" y2="20" />
+							<line x1="7" y1="10" x2="13" y2="10" />
+						</g>
+					</svg>
+				}
+			/>
+		</Button>
 	);
 }

package/src/components/legend/hooks/test/use-chart-legend-items.test.tsx

@@ -265,4 +265,156 @@ describe( 'useChartLegendItems', () => {
 			expect( result.current[ 0 ].color ).toBeDefined();
 		} );
 	} );
+
+	describe( 'Group collapsing (SeriesData)', () => {
+		const groupedComparisonData: SeriesData[] = [
+			{ label: 'Views', group: 'views', data: [ { label: 'Mon', value: 100 } ] },
+			{
+				label: 'Views — previous',
+				group: 'views',
+				options: { type: 'comparison' as const },
+				data: [ { label: 'Mon', value: 90 } ],
+			},
+			{ label: 'Visitors', group: 'visitors', data: [ { label: 'Mon', value: 50 } ] },
+			{
+				label: 'Visitors — previous',
+				group: 'visitors',
+				options: { type: 'comparison' as const },
+				data: [ { label: 'Mon', value: 45 } ],
+			},
+		];
+
+		describe( 'by default', () => {
+			test( 'keeps one item per series for a comparison group', () => {
+				const { result } = renderHook( () => useChartLegendItems( groupedComparisonData ), {
+					wrapper,
+				} );
+
+				expect( result.current ).toHaveLength( 4 );
+				expect( result.current.map( item => item.label ) ).toEqual( [
+					'Views',
+					'Views — previous',
+					'Visitors',
+					'Visitors — previous',
+				] );
+			} );
+
+			test( 'gives each item only its own series label', () => {
+				const { result } = renderHook( () => useChartLegendItems( groupedComparisonData ), {
+					wrapper,
+				} );
+
+				expect( result.current.map( item => item.seriesLabels ) ).toEqual( [
+					[ 'Views' ],
+					[ 'Views — previous' ],
+					[ 'Visitors' ],
+					[ 'Visitors — previous' ],
+				] );
+			} );
+
+			test( 'preserves the original series order for interleaved groups', () => {
+				// `group` predates collapsing and was used for colour coordination, so existing
+				// charts may interleave grouped series. The default legend must not reorder them.
+				const interleaved: SeriesData[] = [
+					{ label: 'Views', group: 'views', data: [ { label: 'Mon', value: 100 } ] },
+					{ label: 'Visitors', group: 'visitors', data: [ { label: 'Mon', value: 50 } ] },
+					{
+						label: 'Views — previous',
+						group: 'views',
+						options: { type: 'comparison' as const },
+						data: [ { label: 'Mon', value: 90 } ],
+					},
+					{
+						label: 'Visitors — previous',
+						group: 'visitors',
+						options: { type: 'comparison' as const },
+						data: [ { label: 'Mon', value: 45 } ],
+					},
+				];
+
+				const { result } = renderHook( () => useChartLegendItems( interleaved ), { wrapper } );
+
+				expect( result.current.map( item => item.label ) ).toEqual( [
+					'Views',
+					'Visitors',
+					'Views — previous',
+					'Visitors — previous',
+				] );
+			} );
+		} );
+
+		describe( 'with collapseGroups enabled', () => {
+			const collapsed = () =>
+				renderHook( () => useChartLegendItems( groupedComparisonData, { collapseGroups: true } ), {
+					wrapper,
+				} );
+
+			test( 'collapses series that share a group into one item per group', () => {
+				const { result } = collapsed();
+
+				expect( result.current ).toHaveLength( 2 );
+			} );
+
+			test( 'uses the primary (non-comparison) series label for the grouped item', () => {
+				const { result } = collapsed();
+
+				expect( result.current[ 0 ].label ).toBe( 'Views' );
+				expect( result.current[ 1 ].label ).toBe( 'Visitors' );
+			} );
+
+			test( 'exposes all member series labels via seriesLabels, primary first', () => {
+				const { result } = collapsed();
+
+				expect( result.current[ 0 ].seriesLabels ).toEqual( [ 'Views', 'Views — previous' ] );
+				expect( result.current[ 1 ].seriesLabels ).toEqual( [ 'Visitors', 'Visitors — previous' ] );
+			} );
+
+			test( 'collapses a shared group that has no comparison series', () => {
+				const sharedGroupNoComparison: SeriesData[] = [
+					{ label: 'A', group: 'metrics', data: [ { label: 'x', value: 1 } ] },
+					{ label: 'B', group: 'metrics', data: [ { label: 'x', value: 2 } ] },
+				];
+
+				const { result } = renderHook(
+					() => useChartLegendItems( sharedGroupNoComparison, { collapseGroups: true } ),
+					{ wrapper }
+				);
+
+				expect( result.current ).toHaveLength( 1 );
+				expect( result.current[ 0 ].label ).toBe( 'A' );
+				expect( result.current[ 0 ].seriesLabels ).toEqual( [ 'A', 'B' ] );
+			} );
+
+			test( 'does not collapse series with distinct group values', () => {
+				const distinctGroups: SeriesData[] = [
+					{ label: 'A', group: 'a', data: [ { label: 'x', value: 1 } ] },
+					{ label: 'B', group: 'b', data: [ { label: 'x', value: 2 } ] },
+				];
+
+				const { result } = renderHook(
+					() => useChartLegendItems( distinctGroups, { collapseGroups: true } ),
+					{ wrapper }
+				);
+
+				expect( result.current ).toHaveLength( 2 );
+				expect( result.current.map( item => item.label ) ).toEqual( [ 'A', 'B' ] );
+			} );
+
+			test( 'leaves ungrouped series as individual items with their own seriesLabels', () => {
+				const ungrouped: SeriesData[] = [
+					{ label: 'One', data: [ { label: 'x', value: 1 } ] },
+					{ label: 'Two', data: [ { label: 'x', value: 2 } ] },
+				];
+
+				const { result } = renderHook(
+					() => useChartLegendItems( ungrouped, { collapseGroups: true } ),
+					{ wrapper }
+				);
+
+				expect( result.current ).toHaveLength( 2 );
+				expect( result.current[ 0 ].seriesLabels ).toEqual( [ 'One' ] );
+				expect( result.current[ 1 ].seriesLabels ).toEqual( [ 'Two' ] );
+			} );
+		} );
+	} );
 } );