@automattic/charts 4.11.1 → 4.13.0

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

@@ -11,10 +11,13 @@ import userEvent from '@testing-library/user-event';
 import { GlobalChartsProvider } from '../../../providers';
 import { useGlobalChartsContext } from '../../../providers/chart-context/hooks/use-global-charts-context';
 import { steadyTrafficData } from '../../../stories/sample-data';
+import { selectedBarRingBounds } from '../../../test-utils/selected-bar-ring';
 import BarChart, { BarChartUnresponsive } from '../bar-chart';
 import { useBarChartOptions } from '../private';
+import { useBarColors } from '../use-bar-colors';
 import type { GlobalChartsContextValue } from '../../../providers/chart-context/types';
 import type { DataPointDate, SeriesData } from '../../../types';
+import type { RenderTooltipParams } from '../../../visx/types';
 
 // Mock useElementSize to return non-zero dimensions in jsdom so charts render
 const mockRefCallback = jest.fn();
@@ -22,6 +25,17 @@ jest.mock( '../../../hooks/use-element-size', () => ( {
 	useElementSize: () => [ mockRefCallback, 500, 300 ],
 } ) );
 
+const geometryOf = ( element: Element ) =>
+	[ 'x', 'y', 'width', 'height' ].map( name =>
+		Number( element.getAttribute( name ) ).toFixed( 2 )
+	);
+
+const selectedRingGeometry = () =>
+	Object.values( selectedBarRingBounds() ).map( value => value.toFixed( 2 ) );
+
+// eslint-disable-next-line testing-library/no-node-access -- visx renders the bars and takes no test id.
+const visxBars = () => document.querySelectorAll( '.visx-bar' );
+
 describe( 'BarChart', () => {
 	const defaultProps = {
 		width: 500,
@@ -1644,7 +1658,7 @@ describe( 'BarChart', () => {
 			expect( screen.queryByTestId( 'bar-chart-patterns' ) ).not.toBeInTheDocument();
 		} );
 
-		test( 'comparison shadow reuses the primary bar pattern when patterns are enabled', () => {
+		test( 'fills the comparison bar with its own pattern when patterns are enabled', () => {
 			renderWithTheme( {
 				withPatterns: true,
 				data: [
@@ -1670,9 +1684,7 @@ describe( 'BarChart', () => {
 
 			const shadow = screen.getAllByTestId( /^bar-chart-comparison-\d+-\d+$/ )[ 0 ];
 			const shadowFill = shadow.getAttribute( 'fill' );
-			// Shadow is filled with a pattern, not a solid color, and it references the PRIMARY
-			// series' pattern (index 0) rather than the comparison series' own index.
-			expect( shadowFill ).toMatch( /^url\(#bar-pattern-.+-0\)$/ );
+			expect( shadowFill ).toMatch( /^url\(#bar-pattern-.+-1\)$/ );
 		} );
 	} );
 
@@ -2014,6 +2026,39 @@ describe( 'BarChart', () => {
 				expect( tooltip ).toHaveTextContent( 'Previous period: 15' );
 			} );
 
+			test( 'pairs the comparison value by date when the bars have empty labels', async () => {
+				const user = userEvent.setup();
+				renderWithTheme( {
+					withTooltips: true,
+					data: [
+						{
+							label: 'This period',
+							group: 'views',
+							data: [
+								{ date: new Date( '2024-01-01' ), value: 10, label: '' },
+								{ date: new Date( '2024-01-02' ), value: 20, label: '' },
+							],
+						},
+						{
+							label: 'Previous period',
+							group: 'views',
+							options: { type: 'comparison' as const },
+							data: [
+								{ date: new Date( '2024-01-01' ), value: 15, label: '' },
+								{ date: new Date( '2024-01-02' ), value: 25, label: '' },
+							],
+						},
+					],
+				} );
+
+				screen.getByRole( 'application', { name: /bar chart/i } ).focus();
+				await user.keyboard( '{ArrowRight}{ArrowRight}' );
+
+				const tooltip = screen.getByTestId( 'chart-tooltip-1' );
+				expect( tooltip ).toHaveTextContent( 'This period: 20' );
+				expect( tooltip ).toHaveTextContent( 'Previous period: 25' );
+			} );
+
 			test( 'keyboard navigation past the first slot stays on the primary bar, not the comparison series', async () => {
 				const user = userEvent.setup();
 				renderWithTheme( {
@@ -2275,7 +2320,7 @@ describe( 'BarChart', () => {
 					await user.keyboard( '{ArrowRight}' );
 
 					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveTextContent( 'No data' );
-					expect( screen.queryByTestId( 'bar-chart-keyboard-highlight' ) ).not.toBeInTheDocument();
+					expect( screen.queryByTestId( 'bar-chart-selected-ring' ) ).not.toBeInTheDocument();
 				} );
 
 				test( 'outlines the first rendered bar for the first bucket with a reading', async () => {
@@ -2286,9 +2331,7 @@ describe( 'BarChart', () => {
 					await user.keyboard( '{ArrowRight}{ArrowRight}' );
 
 					expect( screen.getByTestId( 'chart-tooltip-1' ) ).toHaveTextContent( '20' );
-					expect( screen.getByTestId( 'bar-chart-keyboard-highlight' ) ).toHaveTextContent(
-						/\.visx-bar:nth-child\(1\) \{/
-					);
+					expect( selectedRingGeometry() ).toEqual( geometryOf( visxBars()[ 0 ] ) );
 				} );
 
 				test( 'skips the bars an earlier series left out when outlining a later series', async () => {
@@ -2319,9 +2362,7 @@ describe( 'BarChart', () => {
 					await user.keyboard( '{ArrowRight}{ArrowRight}{ArrowRight}{ArrowRight}' );
 
 					expect( screen.getByTestId( 'chart-tooltip-3' ) ).toHaveTextContent( '15' );
-					expect( screen.getByTestId( 'bar-chart-keyboard-highlight' ) ).toHaveTextContent(
-						/\.visx-bar:nth-child\(4\) \{/
-					);
+					expect( selectedRingGeometry() ).toEqual( geometryOf( visxBars()[ 3 ] ) );
 				} );
 			} );
 		} );
@@ -2705,8 +2746,11 @@ describe( 'BarChart', () => {
 	} );
 
 	describe( 'Comparison Series', () => {
-		it( 'renders a translucent shadow behind the primary bar for a comparison series', () => {
-			const data = [
+		it.each( [
+			[ 'opaque, in the colors the charts context reports', undefined ],
+			[ 'translucent, in the series colors, under the deprecated theme opacity', 0.5 ],
+		] )( 'draws a comparison bar behind the primary bar, %s', ( _case, opacity ) => {
+			const data: SeriesData[] = [
 				{
 					label: 'This year',
 					group: 'views',
@@ -2725,18 +2769,56 @@ describe( 'BarChart', () => {
 					],
 				},
 			];
-			render( <BarChart data={ data } width={ 400 } height={ 300 } /> );
+			let barColors: string[] = [];
+			const CaptureBarColors = () => {
+				barColors = useBarColors()( data );
+				return null;
+			};
+			render(
+				<GlobalChartsProvider
+					theme={ opacity ? { barChart: { barStyles: { comparison: { opacity } } } } : undefined }
+				>
+					<CaptureBarColors />
+					<BarChart data={ data } width={ 400 } height={ 300 } />
+				</GlobalChartsProvider>
+			);
 
-			// two comparison shadow rects (one per data point)
-			// Match individual rect testids like bar-chart-comparison-1-0 (not the group wrapper)
+			const [ primaryColor, comparisonColor ] = barColors;
 			const shadows = screen.getAllByTestId( /^bar-chart-comparison-\d+-\d+$/ );
 			expect( shadows ).toHaveLength( 2 );
-			expect( shadows[ 0 ] ).toHaveAttribute( 'opacity', '0.5' );
+			expect( shadows[ 0 ] ).toHaveAttribute( 'fill', comparisonColor );
+			expect( shadows[ 0 ].attributes.getNamedItem( 'opacity' )?.value ).toBe(
+				opacity ? String( opacity ) : undefined
+			);
+			expect( comparisonColor === primaryColor ).toBe( !! opacity );
 
-			// primary bars still render for the single primary series (visx .visx-bar)
 			// eslint-disable-next-line testing-library/no-node-access
 			const bars = document.querySelectorAll( '.visx-bar' );
 			expect( bars.length ).toBeGreaterThanOrEqual( 2 );
+			expect( bars[ 0 ] ).toHaveAttribute( 'fill', primaryColor );
+		} );
+
+		it( "fills a comparison bar in its datum's own color, as a primary bar does", () => {
+			render(
+				<BarChart
+					width={ 400 }
+					height={ 300 }
+					data={ [
+						{ label: 'This year', group: 'views', data: [ { label: 'Jan', value: 100 } ] },
+						{
+							label: 'Last year',
+							group: 'views',
+							options: { type: 'comparison' as const },
+							data: [ { label: 'Jan', value: 80, color: '#123456' } ],
+						},
+					] }
+				/>
+			);
+
+			expect( screen.getByTestId( 'bar-chart-comparison-1-0' ) ).toHaveAttribute(
+				'fill',
+				'#123456'
+			);
 		} );
 
 		it( 'hides the comparison shadow group from assistive technology', () => {
@@ -2787,7 +2869,6 @@ describe( 'BarChart', () => {
 
 			const shadows = screen.getAllByTestId( /^bar-chart-comparison-\d+-\d+$/ );
 			expect( shadows ).toHaveLength( 2 );
-			expect( shadows[ 0 ] ).toHaveAttribute( 'opacity', '0.5' );
 		} );
 
 		it( 'expands value-axis domain to include comparison values exceeding the primary max', () => {
@@ -3507,6 +3588,87 @@ describe( 'BarChart', () => {
 			expect( screen.queryByRole( 'tooltip' ) ).not.toBeInTheDocument();
 		} );
 
+		const labelledViews = [
+			{ label: 'Apr', value: 29 },
+			{ label: 'May', value: 19 },
+		];
+		const april = new Date( '2025-04-01T00:00:00Z' );
+		const may = new Date( '2025-05-01T00:00:00Z' );
+
+		it.each( [
+			{
+				name: 'aligned series',
+				views: labelledViews,
+				visitors: [
+					{ label: 'Apr', value: 112 },
+					{ label: 'May', value: 80 },
+				],
+				presses: 3,
+				rows: [ 'Views=19@1', 'Visitors=80@1' ],
+				nearest: 'Views',
+			},
+			{
+				name: 'ragged series',
+				views: labelledViews,
+				visitors: [ { label: 'May', value: 80 } ],
+				presses: 2,
+				rows: [ 'Views=19@1', 'Visitors=80@0' ],
+				nearest: 'Visitors',
+			},
+			{
+				name: 'dated points with empty labels',
+				views: [
+					{ date: april, label: '', value: 29 },
+					{ date: may, label: '', value: 19 },
+				],
+				visitors: [
+					{ date: april, label: '', value: 112 },
+					{ date: may, label: '', value: 80 },
+				],
+				presses: 3,
+				rows: [ 'Views=19@1', 'Visitors=80@1' ],
+				nearest: 'Views',
+			},
+		] )(
+			'gives the keyboard tooltip only the bars at the selected category: $name',
+			async ( { views, visitors, presses, rows, nearest } ) => {
+				const user = userEvent.setup();
+				const renderTooltip = ( { tooltipData }: RenderTooltipParams< DataPointDate > ) => (
+					<div>
+						<span data-testid="nearest">{ tooltipData?.nearestDatum?.key }</span>
+						{ Object.entries( tooltipData?.datumByKey ?? {} ).map(
+							( [ key, { datum, index } ] ) => (
+								<span
+									key={ key }
+									data-testid="row"
+								>{ `${ key }=${ datum.value }@${ index }` }</span>
+							)
+						) }
+					</div>
+				);
+
+				renderWithTheme( {
+					withTooltips: true,
+					renderTooltip,
+					data: [
+						{ label: 'Views', data: views, options: {} },
+						{ label: 'Visitors', data: visitors, options: {} },
+					],
+				} );
+
+				screen.getByRole( 'application', { name: /bar chart/i } ).focus();
+				for ( let i = 0; i < presses; i++ ) {
+					await user.keyboard( '{ArrowRight}' );
+				}
+
+				expect( screen.getAllByTestId( 'row' ).map( row => row.textContent ) ).toEqual(
+					expect.arrayContaining( rows )
+				);
+				expect( screen.getAllByTestId( 'row' ) ).toHaveLength( rows.length );
+				expect( screen.getByTestId( 'nearest' ) ).toHaveTextContent( nearest );
+			}
+		);
+
 		it( 'stops at the last visible slot on a standard chart', async () => {
 			const user = userEvent.setup();
 

package/src/charts/bar-chart/test/use-bar-legend-items.test.tsx

@@ -0,0 +1,81 @@
+import { renderHook } from '@testing-library/react';
+import { useChartLegendItems } from '../../../components/legend';
+import { GlobalChartsProvider } from '../../../providers';
+import { useBarColors } from '../use-bar-colors';
+import { useBarLegendItems } from '../use-bar-legend-items';
+import type { SeriesData } from '../../../types';
+import type { ReactNode } from 'react';
+
+const wrapper = ( { children }: { children: ReactNode } ) => (
+	<GlobalChartsProvider>{ children }</GlobalChartsProvider>
+);
+
+const twoMetricData: SeriesData[] = [
+	{ label: 'Views', group: 'views', data: [ { label: 'Mon', value: 100 } ] },
+	{
+		label: 'Views — previous',
+		group: 'views',
+		options: { type: 'comparison' },
+		data: [ { label: 'Mon', value: 90 } ],
+	},
+	{ label: 'Visitors', group: 'visitors', data: [ { label: 'Mon', value: 50 } ] },
+	{
+		label: 'Visitors — previous',
+		group: 'visitors',
+		options: { type: 'comparison' },
+		data: [ { label: 'Mon', value: 40 } ],
+	},
+];
+const perMetricLabel = ( metric: string ) => `${ metric } (Prev. 7 days)`;
+
+describe( 'useBarLegendItems', () => {
+	test.each( [
+		[
+			'takes the grouped comparison tints, a collapsed group in its comparison tint,',
+			'grouped',
+			[ 1, 3, 1, 3 ],
+		],
+		[ 'takes the opaque overlap bar colors', 'overlap', [ 0, 2, 1, 3 ] ],
+	] as const )( '%s with layout %s', ( _case, layout, colorOrder ) => {
+		const { result } = renderHook(
+			() => ( {
+				items: useBarLegendItems( twoMetricData, {
+					collapseGroups: true,
+					comparisonSeriesItems: perMetricLabel,
+					layout,
+				} ),
+				getBarColors: useBarColors(),
+			} ),
+			{ wrapper }
+		);
+		const colors = result.current.getBarColors( twoMetricData, { layout } );
+
+		expect( result.current.items.map( item => item.color ) ).toEqual(
+			colorOrder.map( index => colors[ index ] )
+		);
+	} );
+
+	test( 'lists one item per series in slot order, primaries first, with layout overlap', () => {
+		const { result } = renderHook(
+			() => useBarLegendItems( twoMetricData, { layout: 'overlap' } ),
+			{ wrapper }
+		);
+
+		expect( result.current.map( item => item.label ) ).toEqual(
+			[ 0, 2, 1, 3 ].map( index => twoMetricData[ index ].label )
+		);
+	} );
+
+	test( "returns the chart legend's own items without a layout", () => {
+		const options = { collapseGroups: true };
+		const { result } = renderHook(
+			() => ( {
+				bar: useBarLegendItems( twoMetricData, options ),
+				chart: useChartLegendItems( twoMetricData, options ),
+			} ),
+			{ wrapper }
+		);
+
+		expect( result.current.bar ).toEqual( result.current.chart );
+	} );
+} );

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

@@ -1,4 +1,5 @@
 import type {
+	BarChartLayout,
 	BaseChartProps,
 	DataPointDate,
 	SeriesData,
@@ -33,6 +34,8 @@ export interface BarChartProps extends BaseChartProps< SeriesData[] >, SeriesVis
 	/** CSS class for each primary bar, in addition to visx-bar. */
 	barClassName?: ( datum: DataPointDate ) => string | undefined;
 	orientation?: 'horizontal' | 'vertical';
+	/** Defaults to `grouped`. */
+	layout?: BarChartLayout;
 	withPatterns?: boolean;
 	showZeroValues?: boolean;
 	/** Highlight the active band across the plot when tooltips are enabled. */

package/src/charts/bar-chart/use-bar-colors.ts

@@ -0,0 +1,46 @@
+import { useCallback } from 'react';
+import { useGlobalChartsContext } from '../../providers/chart-context/hooks/use-global-charts-context';
+import { BACKGROUND_FALLBACK } from '../../providers/chart-context/private/catalog-pointers';
+import { getGroupedBarColors } from './private/grouped-bars';
+import { getOverlapBarColors } from './private/overlap-bars';
+import type { BarChartLayout, SeriesData } from '../../types';
+
+export type GetBarColors = (
+	series: SeriesData[],
+	options?: { layout?: BarChartLayout }
+) => string[];
+
+/**
+ * Reads the colors `BarChart` fills series with, so a custom tooltip or legend can match the bars.
+ *
+ * @return A function from series and a layout to each series' bar color, by index.
+ */
+export function useBarColors(): GetBarColors {
+	const {
+		getElementStyles,
+		backgroundColor = BACKGROUND_FALLBACK,
+		theme,
+	} = useGlobalChartsContext();
+	const comparisonOpacity = theme.barChart?.barStyles?.comparison?.opacity;
+
+	return useCallback< GetBarColors >(
+		( series, { layout = 'grouped' } = {} ) => {
+			const colors = series.map( ( data, index ) => getElementStyles( { data, index } ).color );
+
+			if ( layout !== 'overlap' ) {
+				// The deprecated comparison opacity keeps the translucent bars in their series colors.
+				return comparisonOpacity === undefined
+					? getGroupedBarColors( series, colors, backgroundColor )
+					: colors;
+			}
+
+			return getOverlapBarColors(
+				series,
+				colors,
+				[ getElementStyles( { index: 0 } ).color, getElementStyles( { index: 1 } ).color ],
+				backgroundColor
+			);
+		},
+		[ getElementStyles, backgroundColor, comparisonOpacity ]
+	);
+}

package/src/charts/bar-chart/use-bar-legend-items.ts

@@ -0,0 +1,87 @@
+import { useMemo } from 'react';
+import { useChartLegendItems } from '../../components/legend/hooks/use-chart-legend-items';
+import { useBarColors } from './use-bar-colors';
+import type { ChartLegendOptions } from '../../components/legend/hooks/use-chart-legend-items';
+import type { BaseLegendItem } from '../../components/legend/types';
+import type { BarChartLayout, LegendShape, SeriesData } from '../../types';
+
+export type BarLegendOptions = Omit< ChartLegendOptions, 'seriesColors' > & {
+	/** The layout the bars are drawn in. Unset, the items are the chart legend's own. */
+	layout?: BarChartLayout;
+};
+
+const isComparison = ( data: SeriesData[], label: string | undefined ) =>
+	data.some( series => series.label === label && series.options?.type === 'comparison' );
+
+/**
+ * Applies what a bar layout changes about a legend: overlap lists every primary before every comparison, as it draws their slots, with every swatch opaque like its bar; a collapsed grouped item takes its comparison's tint, the wider bar that frames the group.
+ *
+ * @param data         - The series the items were built from.
+ * @param items        - The legend items.
+ * @param layout       - The layout the bars are drawn in.
+ * @param seriesColors - Each series' bar color, by index.
+ * @return The legend items.
+ */
+function forBarLayout(
+	data: SeriesData[],
+	items: BaseLegendItem[],
+	layout: BarChartLayout,
+	seriesColors: string[]
+): BaseLegendItem[] {
+	if ( layout === 'overlap' ) {
+		const opaque = items.map( item =>
+			item.shapeStyle ? { ...item, shapeStyle: { ...item.shapeStyle, opacity: undefined } } : item
+		);
+		// Static items, such as a comparison item, follow the series items and keep their place.
+		const seriesItems = opaque.filter( item => item.seriesLabels );
+		const firstLabel = ( item: BaseLegendItem ) => item.seriesLabels?.[ 0 ];
+
+		return [
+			...seriesItems.filter( item => ! isComparison( data, firstLabel( item ) ) ),
+			...seriesItems.filter( item => isComparison( data, firstLabel( item ) ) ),
+			...opaque.filter( item => ! item.seriesLabels ),
+		];
+	}
+
+	return items.map( item => {
+		if ( ( item.seriesLabels?.length ?? 0 ) < 2 ) {
+			return item;
+		}
+		const comparisonIndex = data.findIndex(
+			series => series.options?.type === 'comparison' && item.seriesLabels?.includes( series.label )
+		);
+
+		return comparisonIndex === -1 ? item : { ...item, color: seriesColors[ comparisonIndex ] };
+	} );
+}
+
+/**
+ * Builds legend items that match `BarChart`'s bars in a layout, for a custom legend or a chart's own.
+ *
+ * @param data        - The series the chart draws.
+ * @param options     - The legend options, and the layout the bars are drawn in.
+ * @param legendShape - The shape of the legend swatches.
+ * @return The legend items.
+ */
+export function useBarLegendItems(
+	data: SeriesData[],
+	options: BarLegendOptions = {},
+	legendShape?: LegendShape< SeriesData[], number >
+): BaseLegendItem[] {
+	const { layout } = options;
+	const getBarColors = useBarColors();
+	const seriesColors = useMemo(
+		() => ( layout ? getBarColors( data, { layout } ) : undefined ),
+		[ data, layout, getBarColors ]
+	);
+	const chartLegendOptions = useMemo(
+		(): ChartLegendOptions => ( { ...options, seriesColors } ),
+		[ options, seriesColors ]
+	);
+	const items = useChartLegendItems( data, chartLegendOptions, legendShape );
+
+	return useMemo(
+		() => ( layout && seriesColors ? forBarLayout( data, items, layout, seriesColors ) : items ),
+		[ data, items, layout, seriesColors ]
+	);
+}

package/src/charts/conversion-funnel-chart/conversion-funnel-chart.module.scss

@@ -52,13 +52,28 @@
 	height: 100%;
 
 	&--animated {
-		transition:
-			opacity var(--wpds-motion-duration-lg)
-			var(--wpds-motion-easing-subtle);
+
+		.step-text,
+		.funnel-bar,
+		.bar-container {
+			transition:
+				opacity var(--wpds-motion-duration-lg) var(--wpds-motion-easing-subtle),
+				background-color var(--wpds-motion-duration-lg) var(--wpds-motion-easing-subtle);
+		}
 	}
 
+	// Dim the contents, not the step: opacity on an ancestor would also fade
+	// the bar's focus ring.
 	&--blurred {
-		opacity: 0.3;
+
+		.step-text,
+		.funnel-bar {
+			opacity: 0.3;
+		}
+
+		.bar-container {
+			background-color: color-mix(in sRGB, var(--a8c-charts-color-surface-secondary) 30%, transparent);
+		}
 	}
 }
 
@@ -119,20 +134,18 @@
 	}
 }
 
-.tooltip-title {
+.tooltip-title,
+.tooltip-label,
+.tooltip-value {
 	color: var(--a8c-charts-color-label);
 	font-size: var(--wpds-typography-font-size-sm);
 	font-style: normal;
 	font-weight: var(--wpds-typography-font-weight-default);
-	line-height: var(--wpds-typography-line-height-xs);
+	line-height: var(--wpds-typography-line-height-sm);
 }
 
-.tooltip-content {
-	color: var(--a8c-charts-color-label);
-	font-size: var(--wpds-typography-font-size-md);
-	font-style: normal;
+.tooltip-value {
 	font-weight: var(--wpds-typography-font-weight-emphasis);
-	line-height: var(--wpds-typography-line-height-sm);
 }
 
 .empty-state {