@automattic/charts 1.10.3 → 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/components/tooltip/base-tooltip.module.scss

@@ -2,8 +2,9 @@
 	padding: var(--wpds-dimension-padding-sm, 8px);
 	// No WPDS token fits a translucent dark tooltip surface:
 	// bg-interactive-neutral-strong is opaque, and there is no
-	// white-on-dark content foreground token.
-	background-color: rgba(0, 0, 0, 0.85);
+	// white-on-dark content foreground token. The role carries the
+	// hardcoded translucent value as its fallback.
+	background-color: var(--a8c-charts-color-tooltip-surface, rgba(0, 0, 0, 0.85));
 	color: #fff;
 	border-radius: var(--wpds-border-radius-md, 4px);
 	font-size: var(--wpds-typography-font-size-md, 13px);

package/src/components/trend-indicator/trend-indicator.module.scss

@@ -6,18 +6,19 @@
 	font-weight: var(--wpds-typography-font-weight-medium, 499);
 	line-height: 1;
 
-	// Trend colors use the documented --charts-trend-* override API, falling
-	// back to the accessible WPDS semantic tokens.
+	// Trend colours use the --a8c-charts-color-trend-* catalog roles, falling back
+	// to the deprecated --charts-trend-*-color override API and then to the
+	// accessible WPDS semantic tokens.
 	&--up {
-		color: var(--charts-trend-up-color, var(--wpds-color-foreground-content-success-weak, #008030));
+		color: var(--a8c-charts-color-trend-up, var(--charts-trend-up-color, var(--wpds-color-foreground-content-success-weak, #008030)));
 	}
 
 	&--down {
-		color: var(--charts-trend-down-color, var(--wpds-color-foreground-content-error-weak, #cc1818));
+		color: var(--a8c-charts-color-trend-down, var(--charts-trend-down-color, var(--wpds-color-foreground-content-error-weak, #cc1818)));
 	}
 
 	&--neutral {
-		color: var(--charts-trend-neutral-color, var(--wpds-color-foreground-content-neutral-weak, #707070));
+		color: var(--a8c-charts-color-trend-neutral, var(--charts-trend-neutral-color, var(--wpds-color-foreground-content-neutral-weak, #707070)));
 	}
 
 	&__icon {

package/src/index.ts

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

package/src/providers/chart-context/themes.ts

@@ -4,24 +4,31 @@ import type { CompleteChartTheme } from '../../types';
  * Default theme configuration
  */
 const defaultTheme: CompleteChartTheme = {
-	backgroundColor: 'var(--wpds-color-background-surface-neutral-strong, #fff)',
+	backgroundColor:
+		'var(--a8c-charts-color-background, var(--wpds-color-background-surface-neutral-strong, #fff))',
 	labelBackgroundColor: 'transparent', // label background color (transparent by default)
 	// White label text sits on top of arbitrary series colors, so it has no WPDS
-	// content-foreground equivalent and stays hardcoded (tokenization outlier).
-	labelTextColor: '#FFFFFF',
+	// content-foreground equivalent; the role carries the hardcoded value as its fallback.
+	labelTextColor: 'var(--a8c-charts-color-label-on-fill, #FFFFFF)',
 	colors: [ '#98C8DF', '#006DAB', '#A6DC80', '#1F9828', '#FF8C8F' ],
 	gridStyles: {
-		stroke: 'var(--wpds-color-stroke-surface-neutral, #dbdbdb)',
+		stroke: 'var(--a8c-charts-color-grid, var(--wpds-color-stroke-surface-neutral, #dbdbdb))',
 		strokeWidth: 1,
 	},
 	tickLength: 4,
 	gridColor: '',
 	gridColorDark: '',
-	xTickLineStyles: { stroke: 'var(--wpds-color-stroke-surface-neutral, #dbdbdb)', strokeWidth: 1 },
-	xAxisLineStyles: { stroke: 'var(--wpds-color-stroke-surface-neutral, #dbdbdb)', strokeWidth: 1 },
+	xTickLineStyles: {
+		stroke: 'var(--a8c-charts-color-tick, var(--wpds-color-stroke-surface-neutral, #dbdbdb))',
+		strokeWidth: 1,
+	},
+	xAxisLineStyles: {
+		stroke: 'var(--a8c-charts-color-axis, var(--wpds-color-stroke-surface-neutral, #dbdbdb))',
+		strokeWidth: 1,
+	},
 	legend: {
 		labelStyles: {
-			color: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
+			color: 'var(--a8c-charts-color-label, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
 		},
 		containerStyles: {},
 		shapeStyles: [],
@@ -34,26 +41,30 @@ const defaultTheme: CompleteChartTheme = {
 	// elements for axis labels and ticks. Setting `inherit` lets SVG text
 	// pick up the host application's font-family via normal CSS inheritance.
 	svgLabelSmall: {
-		fill: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
+		fill: 'var(--a8c-charts-color-label, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
 		fontFamily: 'inherit',
 	},
 	svgLabelBig: { fontFamily: 'inherit' },
 	annotationStyles: {
 		label: {
-			anchorLineStroke: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
-			backgroundFill: 'var(--wpds-color-background-surface-neutral-strong, #fff)',
+			anchorLineStroke:
+				'var(--a8c-charts-color-annotation, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
+			backgroundFill:
+				'var(--a8c-charts-color-background, var(--wpds-color-background-surface-neutral-strong, #fff))',
 		},
 		connector: {
-			stroke: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
+			stroke:
+				'var(--a8c-charts-color-annotation, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
 		},
 		circleSubject: {
 			stroke: 'transparent',
-			fill: 'var(--wpds-color-foreground-content-neutral, #1e1e1e)',
+			fill: 'var(--a8c-charts-color-annotation, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
 			radius: 5,
 		},
 	},
 	geoChart: {
-		featureFillColor: 'var(--wpds-color-background-surface-neutral-weak, #f4f4f4)',
+		featureFillColor:
+			'var(--a8c-charts-color-surface-secondary, var(--wpds-color-background-surface-neutral-weak, #f4f4f4))',
 	},
 	leaderboardChart: {
 		rowGap: 12,
@@ -61,15 +72,18 @@ const defaultTheme: CompleteChartTheme = {
 		labelSpacing: 'xs',
 		// [negative, neutral, positive]
 		deltaColors: [
-			'var(--wpds-color-foreground-content-error-weak, #cc1818)',
-			'var(--wpds-color-foreground-content-neutral-weak, #707070)',
-			'var(--wpds-color-foreground-content-success-weak, #008030)',
+			'var(--a8c-charts-color-trend-down, var(--wpds-color-foreground-content-error-weak, #cc1818))',
+			'var(--a8c-charts-color-trend-neutral, var(--wpds-color-foreground-content-neutral-weak, #707070))',
+			'var(--a8c-charts-color-trend-up, var(--wpds-color-foreground-content-success-weak, #008030))',
 		],
 	},
 	conversionFunnelChart: {
-		backgroundColor: 'var(--wpds-color-background-surface-neutral-weak, #f4f4f4)',
-		positiveChangeColor: 'var(--wpds-color-foreground-content-success-weak, #008030)',
-		negativeChangeColor: 'var(--wpds-color-foreground-content-error-weak, #cc1818)',
+		backgroundColor:
+			'var(--a8c-charts-color-surface-secondary, var(--wpds-color-background-surface-neutral-weak, #f4f4f4))',
+		positiveChangeColor:
+			'var(--a8c-charts-color-trend-up, var(--wpds-color-foreground-content-success-weak, #008030))',
+		negativeChangeColor:
+			'var(--a8c-charts-color-trend-down, var(--wpds-color-foreground-content-error-weak, #cc1818))',
 	},
 	lineChart: {
 		lineStyles: {

package/src/types.ts

@@ -208,8 +208,8 @@ export type LeaderboardEntry = {
 	previousShare?: number;
 
 	/**
-	 * Delta of the entry. Omit when this row has no matching comparison-period
-	 * value.
+	 * Delta of the entry. Omit when the percentage change is unavailable, such
+	 * as when the row has no comparison value or its previous value is zero.
 	 */
 	delta?: number;
 
@@ -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,48 +0,0 @@
-.x-zoom {
-
-	// The translucent rgba overlay colors (selection fill/stroke, reset
-	// background/border) have no WPDS equivalent and stay as-is; only the
-	// opaque foreground and focus colors are tokenized.
-	&__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, var(--wpds-color-foreground-content-neutral, #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: 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: var(--charts-zoom-reset-bg-hover, rgba(255, 255, 255, 1));
-		}
-
-		&:focus-visible {
-			outline: 2px solid var(--charts-zoom-reset-focus, var(--wpds-color-stroke-focus, #3858e9));
-			outline-offset: 1px;
-		}
-	}
-
-	&__reset-icon {
-		width: 16px;
-		height: 16px;
-		flex-shrink: 0;
-	}
-}