@automattic/charts 1.11.0 → 1.12.0

package/src/components/legend/hooks/use-chart-legend-items.ts

@@ -25,6 +25,11 @@ export interface ChartLegendOptions {
 	showValues?: boolean;
 	legendValueDisplay?: LegendValueDisplay;
 	legendShape?: LegendShape< SeriesData[], number >;
+	/**
+	 * Collapse series that share a `group` into a single legend item, labelled by the group's
+	 * primary series. Off by default, so every series gets its own item.
+	 */
+	collapseGroups?: boolean;
 }
 
 /**
@@ -95,13 +100,90 @@ function applyGlyphToLegendItem(
 	return baseItem;
 }
 
+type SeriesGroupMember = { series: SeriesData; index: number };
+
+/**
+ * Buckets series by their `group`, preserving first-appearance order. Series with no group — or a
+ * group value unique to them — end up in a bucket of their own. Whether a multi-series bucket then
+ * collapses to a single legend item is decided by the caller: with `collapseGroups` on, every
+ * multi-member bucket collapses, and the comparison pattern only decides which member represents it.
+ * @param seriesData - The series data to group
+ * @return Ordered groups, each holding its member series with their original indices
+ */
+function groupSeriesForLegend( seriesData: SeriesData[] ): SeriesGroupMember[][] {
+	const groups: SeriesGroupMember[][] = [];
+	const groupIndexByKey = new Map< string, number >();
+
+	seriesData.forEach( ( series, index ) => {
+		const member: SeriesGroupMember = { series, index };
+		const key = series.group;
+
+		if ( key === undefined ) {
+			groups.push( [ member ] );
+			return;
+		}
+
+		const existing = groupIndexByKey.get( key );
+		if ( existing === undefined ) {
+			groupIndexByKey.set( key, groups.length );
+			groups.push( [ member ] );
+		} else {
+			groups[ existing ].push( member );
+		}
+	} );
+
+	return groups;
+}
+
 /**
- * Processes SeriesData into legend items
+ * Builds a single legend item from a representative series, tagging it with the series it controls
+ * @param member           - The series (with its original index) that provides the label/colour
+ * @param seriesLabels     - Every series label this item toggles (grouped) or just its own
+ * @param getElementStyles - Function to get element styles
+ * @param showValues       - Whether to show values in legend
+ * @param withGlyph        - Whether to include glyph rendering
+ * @param glyphSize        - Size of the glyph
+ * @param renderGlyph      - Component to render the glyph
+ * @param legendShape      - The shape type for legend items (string literal or React component)
+ * @return The processed legend item
+ */
+function buildSeriesLegendItem(
+	member: SeriesGroupMember,
+	seriesLabels: string[],
+	getElementStyles: ( params: GetElementStylesParams ) => ElementStyles,
+	showValues: boolean,
+	withGlyph: boolean,
+	glyphSize: number,
+	renderGlyph?: < Datum extends object >( props: GlyphProps< Datum > ) => ReactNode,
+	legendShape?: LegendShape< SeriesData[], number >
+): BaseLegendItem {
+	const { color, glyph, shapeStyles } = getElementStyles( {
+		data: member.series,
+		index: member.index,
+		legendShape,
+	} );
+
+	const baseItem: BaseLegendItem = {
+		label: member.series.label,
+		value: showValues ? member.series.data?.length?.toString() || '0' : '',
+		color,
+		shapeStyle: shapeStyles,
+		seriesLabels,
+	};
+
+	return applyGlyphToLegendItem( baseItem, withGlyph, glyph, renderGlyph, glyphSize );
+}
+
+/**
+ * Processes SeriesData into legend items. Every series keeps its own legend entry unless
+ * `collapseGroups` is set, in which case series sharing a `group` collapse to one item labelled by
+ * the group's primary (its first non-comparison member).
  * @param seriesData       - The series data to process
  * @param getElementStyles - Function to get element styles
  * @param showValues       - Whether to show values in legend
  * @param withGlyph        - Whether to include glyph rendering
  * @param glyphSize        - Size of the glyph
+ * @param collapseGroups   - Whether series sharing a group collapse to a single item
  * @param renderGlyph      - Component to render the glyph
  * @param legendShape      - The shape type for legend items (string literal or React component)
  * @return Array of processed legend items
@@ -112,27 +194,44 @@ function processSeriesData(
 	showValues: boolean,
 	withGlyph: boolean,
 	glyphSize: number,
+	collapseGroups: boolean,
 	renderGlyph?: < Datum extends object >( props: GlyphProps< Datum > ) => ReactNode,
 	legendShape?: LegendShape< SeriesData[], number >
 ): BaseLegendItem[] {
-	const mapper = ( series: SeriesData, index: number ) => {
-		const { color, glyph, shapeStyles } = getElementStyles( {
-			data: series,
-			index,
-			legendShape,
-		} );
+	const buildItem = ( member: SeriesGroupMember, seriesLabels: string[] ) =>
+		buildSeriesLegendItem(
+			member,
+			seriesLabels,
+			getElementStyles,
+			showValues,
+			withGlyph,
+			glyphSize,
+			renderGlyph,
+			legendShape
+		);
 
-		const baseItem: BaseLegendItem = {
-			label: series.label,
-			value: showValues ? series.data?.length?.toString() || '0' : '',
-			color,
-			shapeStyle: shapeStyles,
-		};
+	// Without collapsing there is no reason to bucket by group — mapping series directly keeps the
+	// original order, which matters for charts that already interleave grouped series for colour.
+	if ( ! collapseGroups ) {
+		return seriesData.map( ( series, index ) => buildItem( { series, index }, [ series.label ] ) );
+	}
 
-		return applyGlyphToLegendItem( baseItem, withGlyph, glyph, renderGlyph, glyphSize );
-	};
+	return groupSeriesForLegend( seriesData ).flatMap( members => {
+		if ( members.length > 1 ) {
+			const primary =
+				members.find( ( { series } ) => series.options?.type !== 'comparison' ) ?? members[ 0 ];
+
+			// Primary first so the interactive visibility check reads the series that owns the swatch.
+			const seriesLabels = [
+				primary.series.label,
+				...members.filter( member => member !== primary ).map( ( { series } ) => series.label ),
+			];
+
+			return [ buildItem( primary, seriesLabels ) ];
+		}
 
-	return seriesData.map( mapper );
+		return members.map( member => buildItem( member, [ member.series.label ] ) );
+	} );
 }
 
 /**
@@ -196,6 +295,7 @@ export function useChartLegendItems<
 		legendValueDisplay = 'percentage',
 		withGlyph = false,
 		glyphSize = 8,
+		collapseGroups = false,
 		renderGlyph,
 	} = options;
 	const { getElementStyles } = useGlobalChartsContext();
@@ -213,6 +313,7 @@ export function useChartLegendItems<
 				showValues,
 				withGlyph,
 				glyphSize,
+				collapseGroups,
 				renderGlyph,
 				legendShape
 			);
@@ -236,6 +337,7 @@ export function useChartLegendItems<
 		legendValueDisplay,
 		withGlyph,
 		glyphSize,
+		collapseGroups,
 		renderGlyph,
 		legendShape,
 	] );

package/src/components/legend/private/base-legend.tsx

@@ -116,9 +116,17 @@ export const BaseLegend: ForwardRefExoticComponent<
 
 		// Handle legend item clicks for interactive mode
 		const handleLegendClick = useCallback(
-			( seriesLabel: string ) => {
+			( seriesLabels: string[] ) => {
 				if ( interactive && chartId && context ) {
-					context.toggleSeriesVisibility( chartId, seriesLabel );
+					// Converge the whole group on the representative's next state: only toggle series that
+					// currently match it, so a desynced group (e.g. one member hidden programmatically)
+					// ends up uniformly hidden/shown after one click.
+					const representativeVisible = context.isSeriesVisible( chartId, seriesLabels[ 0 ] );
+					seriesLabels.forEach( label => {
+						if ( context.isSeriesVisible( chartId, label ) === representativeVisible ) {
+							context.toggleSeriesVisibility( chartId, label );
+						}
+					} );
 				}
 			},
 			[ interactive, chartId, context ]
@@ -137,24 +145,24 @@ export const BaseLegend: ForwardRefExoticComponent<
 
 		// Create event handlers to avoid inline arrow functions
 		const createClickHandler = useCallback(
-			( labelText: string ) => {
+			( seriesLabels: string[] ) => {
 				if ( ! interactive ) {
 					return undefined;
 				}
-				return () => handleLegendClick( labelText );
+				return () => handleLegendClick( seriesLabels );
 			},
 			[ interactive, handleLegendClick ]
 		);
 
 		const createKeyDownHandler = useCallback(
-			( labelText: string ) => {
+			( seriesLabels: string[] ) => {
 				if ( ! interactive ) {
 					return undefined;
 				}
 				return ( event: KeyboardEvent ) => {
 					if ( event.key === 'Enter' || event.key === ' ' ) {
 						event.preventDefault();
-						handleLegendClick( labelText );
+						handleLegendClick( seriesLabels );
 					}
 				};
 			},
@@ -185,10 +193,14 @@ export const BaseLegend: ForwardRefExoticComponent<
 						style={ theme.legend?.containerStyles }
 					>
 						{ labels.map( ( label, i ) => {
-							const visible = isSeriesVisible( label.text );
-							const handleClick = createClickHandler( label.text );
-							const handleKeyDown = createKeyDownHandler( label.text );
 							const matchedItem = items[ i ];
+							// A grouped item toggles/reads every series it controls; a plain item just its own.
+							const seriesLabels = matchedItem?.seriesLabels?.length
+								? matchedItem.seriesLabels
+								: [ label.text ];
+							const visible = isSeriesVisible( seriesLabels[ 0 ] );
+							const handleClick = createClickHandler( seriesLabels );
+							const handleKeyDown = createKeyDownHandler( seriesLabels );
 
 							return (
 								<LegendItem

package/src/components/legend/test/legend-config-types.test.tsx

@@ -0,0 +1,32 @@
+import type {
+	ChartLegendConfig,
+	SeriesChartLegendConfig,
+	DataPointPercentage,
+} from '../../../types';
+
+// Type-level tests. The assertions that matter are the `@ts-expect-error` directives, which the
+// package typecheck enforces — an unused directive is itself a compile error, so these fail loudly
+// if `collapseGroups` ever leaks onto the base config that point-based charts use.
+describe( 'collapseGroups legend config', () => {
+	test( 'is available on the series legend config', () => {
+		const seriesLegend: SeriesChartLegendConfig = { collapseGroups: true };
+
+		expect( seriesLegend.collapseGroups ).toBe( true );
+	} );
+
+	test( 'is not part of the base config point charts use', () => {
+		const pieLegend: ChartLegendConfig< DataPointPercentage[] > = {
+			// @ts-expect-error collapseGroups is only on SeriesChartLegendConfig — pie segments carry
+			// `group` purely to coordinate colours with other charts, not to collapse legend rows.
+			collapseGroups: true,
+		};
+
+		expect( pieLegend ).toBeDefined();
+	} );
+
+	test( 'leaves other legend options available on the base config', () => {
+		const pieLegend: ChartLegendConfig< DataPointPercentage[] > = { interactive: true };
+
+		expect( pieLegend.interactive ).toBe( true );
+	} );
+} );

package/src/components/legend/test/legend.test.tsx

@@ -3,7 +3,12 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { useMemo } from 'react';
 import { SingleChartContext } from '../../../charts/private/single-chart-context';
-import { GlobalChartsProvider, useChartId, useChartRegistration } from '../../../providers';
+import {
+	GlobalChartsProvider,
+	useChartId,
+	useChartRegistration,
+	useGlobalChartsContext,
+} from '../../../providers';
 import { Legend } from '../legend';
 import { BaseLegend } from '../private/base-legend';
 import type { ChartType } from '../../../types';
@@ -632,5 +637,120 @@ describe( 'BaseLegend', () => {
 			// Should still be visible (pressed)
 			expect( legendItems[ 0 ] ).toHaveAttribute( 'aria-pressed', 'true' );
 		} );
+
+		it( 'toggles every series in a group when a grouped item is clicked', async () => {
+			const user = userEvent.setup();
+
+			const groupedItems = [
+				{ label: 'Views', color: '#0000ff', seriesLabels: [ 'Views', 'Views — previous' ] },
+				{
+					label: 'Visitors',
+					color: '#00ff00',
+					seriesLabels: [ 'Visitors', 'Visitors — previous' ],
+				},
+			];
+
+			const VisibilityProbe = () => {
+				const { isSeriesVisible } = useGlobalChartsContext();
+				return (
+					<div>
+						<span data-testid="views">{ String( isSeriesVisible( 'test-chart', 'Views' ) ) }</span>
+						<span data-testid="views-prev">
+							{ String( isSeriesVisible( 'test-chart', 'Views — previous' ) ) }
+						</span>
+						<span data-testid="visitors">
+							{ String( isSeriesVisible( 'test-chart', 'Visitors' ) ) }
+						</span>
+					</div>
+				);
+			};
+
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend items={ groupedItems } interactive={ true } chartId="test-chart" />
+					<VisibilityProbe />
+				</GlobalChartsProvider>
+			);
+
+			expect( screen.getByTestId( 'views' ) ).toHaveTextContent( 'true' );
+			expect( screen.getByTestId( 'views-prev' ) ).toHaveTextContent( 'true' );
+
+			const buttons = screen.getAllByRole( 'button' );
+			await user.click( buttons[ 0 ] );
+
+			// One click hides both series in the Views group, leaving Visitors untouched.
+			expect( screen.getByTestId( 'views' ) ).toHaveTextContent( 'false' );
+			expect( screen.getByTestId( 'views-prev' ) ).toHaveTextContent( 'false' );
+			expect( screen.getByTestId( 'visitors' ) ).toHaveTextContent( 'true' );
+			expect( buttons[ 0 ] ).toHaveAttribute( 'aria-pressed', 'false' );
+		} );
+
+		it( 'converges a desynced group to a uniform state in one click', async () => {
+			const user = userEvent.setup();
+
+			const groupedItems = [
+				{ label: 'Views', color: '#0000ff', seriesLabels: [ 'Views', 'Views — previous' ] },
+			];
+
+			const DesyncProbe = () => {
+				const { isSeriesVisible, toggleSeriesVisibility } = useGlobalChartsContext();
+				return (
+					<div>
+						<button
+							data-testid="hide-previous"
+							onClick={ () => toggleSeriesVisibility( 'test-chart', 'Views — previous' ) }
+						>
+							hide previous
+						</button>
+						<span data-testid="views">{ String( isSeriesVisible( 'test-chart', 'Views' ) ) }</span>
+						<span data-testid="views-prev">
+							{ String( isSeriesVisible( 'test-chart', 'Views — previous' ) ) }
+						</span>
+					</div>
+				);
+			};
+
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend items={ groupedItems } interactive={ true } chartId="test-chart" />
+					<DesyncProbe />
+				</GlobalChartsProvider>
+			);
+
+			// Desync the group: hide only the comparison series programmatically.
+			await user.click( screen.getByTestId( 'hide-previous' ) );
+			expect( screen.getByTestId( 'views' ) ).toHaveTextContent( 'true' );
+			expect( screen.getByTestId( 'views-prev' ) ).toHaveTextContent( 'false' );
+
+			// Clicking the grouped item hides the whole group, not inverts each member.
+			const legendButton = screen.getAllByRole( 'button' )[ 0 ];
+			await user.click( legendButton );
+			expect( screen.getByTestId( 'views' ) ).toHaveTextContent( 'false' );
+			expect( screen.getByTestId( 'views-prev' ) ).toHaveTextContent( 'false' );
+
+			// And the next click shows the whole group again.
+			await user.click( legendButton );
+			expect( screen.getByTestId( 'views' ) ).toHaveTextContent( 'true' );
+			expect( screen.getByTestId( 'views-prev' ) ).toHaveTextContent( 'true' );
+		} );
+
+		it( 'falls back to the item label when seriesLabels is an empty array', async () => {
+			const user = userEvent.setup();
+
+			const items = [ { label: 'Views', color: '#0000ff', seriesLabels: [] as string[] } ];
+
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend items={ items } interactive={ true } chartId="test-chart" />
+				</GlobalChartsProvider>
+			);
+
+			const legendButton = screen.getByRole( 'button' );
+			expect( legendButton ).toHaveAttribute( 'aria-pressed', 'true' );
+
+			await user.click( legendButton );
+
+			expect( legendButton ).toHaveAttribute( 'aria-pressed', 'false' );
+		} );
 	} );
 } );

package/src/components/legend/types.ts

@@ -55,4 +55,10 @@ export type BaseLegendItem = {
 	glyphSize?: number;
 	renderGlyph?: < Datum extends object >( props: GlyphProps< Datum > ) => ReactNode;
 	shapeStyle?: CSSProperties & LineStyles;
+	/**
+	 * The series labels this legend item controls. For a grouped item this is every series
+	 * sharing the group (primary first); for a single series it is just its own label. Used by
+	 * the interactive legend to toggle a whole group's visibility from one item.
+	 */
+	seriesLabels?: string[];
 };

package/src/index.ts

@@ -57,6 +57,7 @@ export type {
 	LegendShapeStyles,
 	LegendPosition,
 	ChartLegendConfig,
+	SeriesChartLegendConfig,
 	BaseChartProps,
 	GridProps,
 	GoogleDataTableColumn,

package/src/types.ts

@@ -608,6 +608,22 @@ export type ChartLegendConfig< T = DataPoint | DataPointDate | LeaderboardEntry
 	shapeStyles?: LegendShapeStyles;
 };
 
+/**
+ * Legend config for charts built from `SeriesData` (line, bar, area). Adds `collapseGroups` on top
+ * of the shared config. It is intentionally absent from the base `ChartLegendConfig` so point-based
+ * charts (pie, semi-circle pie) — whose data points carry `group` only to coordinate colours — can't
+ * set it.
+ */
+export type SeriesChartLegendConfig = ChartLegendConfig< SeriesData[] > & {
+	/**
+	 * Collapse series that share a `group` into a single legend item, labelled by the group's
+	 * primary series (its first non-comparison member). Off by default, so every series keeps its
+	 * own item. Combines with `interactive`: a collapsed item toggles every series in its group, an
+	 * uncollapsed one toggles only its own.
+	 */
+	collapseGroups?: boolean;
+};
+
 /**
  * Base properties shared across all chart components
  */

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

@@ -1,50 +0,0 @@
-.x-zoom {
-
-	// The zoom control's bespoke colours are inlined, not exposed as
-	// --a8c-charts-color-zoom-* override vars. The control is slated for rework
-	// (reset button -> @wordpress/ui Button), so it is deliberately not a public
-	// theming surface. Focus tracks the shared --a8c-charts-color-focus role; the
-	// button text uses the WPDS content-foreground token.
-	&__selection {
-		fill: rgba(56, 88, 233, 0.16);
-		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: rgba(255, 255, 255, 0.92);
-		color: var(--wpds-color-foreground-content-neutral, #1e1e1e);
-		border:
-			var(--wpds-border-width-xs, 1px) solid
-			rgba(0, 0, 0, 0.16);
-		border-radius: var(--wpds-border-radius-md, 4px);
-		cursor: pointer;
-		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);
-
-		&:hover {
-			background: rgba(255, 255, 255, 1);
-		}
-
-		&:focus-visible {
-			outline: 2px solid var(--a8c-charts-color-focus, var(--wpds-color-stroke-focus, #3858e9));
-			outline-offset: 1px;
-		}
-	}
-
-	&__reset-icon {
-		width: 16px;
-		height: 16px;
-		flex-shrink: 0;
-	}
-}