@automattic/charts 4.9.0 → 4.10.0

package/src/charts/pie-semi-circle-chart/pie-semi-circle-chart.tsx

@@ -129,11 +129,6 @@ export interface PieSemiCircleChartProps extends BaseChartProps< DataPointPercen
 	 * When provided, replaces the default `label: value` tooltip with custom content.
 	 */
 	renderTooltip?: ( params: PieSemiCircleChartRenderTooltipParams ) => ReactNode;
-
-	/**
-	 * Accessible name of the chart. Defaults to a localized "Semi-circle chart".
-	 */
-	ariaLabel?: string;
 }
 
 // Base props type with optional responsive properties

package/src/charts/private/pie-keyboard-navigation/pie-tooltip.tsx

@@ -1,6 +1,11 @@
-import { BoundedTooltip } from '../../../components/tooltip/private/bounded-tooltip';
+import {
+	BoundedTooltip,
+	TOOLTIP_Z_INDEX,
+} from '../../../components/tooltip/private/bounded-tooltip';
 import { useStandaloneScopeClass } from '../../../providers/chart-scope';
-import type { ReactNode } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
+
+const TOOLTIP_BOX_STYLE: CSSProperties = { zIndex: TOOLTIP_Z_INDEX };
 
 interface PieTooltipProps {
 	top: number;
@@ -21,7 +26,7 @@ export const PieTooltip = ( {
 	const standaloneScopeClass = useStandaloneScopeClass();
 
 	return (
-		<BoundedTooltip top={ top } left={ left }>
+		<BoundedTooltip top={ top } left={ left } style={ TOOLTIP_BOX_STYLE }>
 			{ selectedIndex === undefined ? (
 				<div className={ standaloneScopeClass } role="tooltip">
 					{ children }

package/src/charts/test/accessible-name.test.tsx

@@ -0,0 +1,181 @@
+import { render, screen } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../providers';
+import { salesByProduct } from '../../stories/sample-data';
+import { AreaChartUnresponsive } from '../area-chart';
+import { BarChartUnresponsive } from '../bar-chart';
+import { BarListChartUnresponsive } from '../bar-list-chart';
+import { ConversionFunnelChart } from '../conversion-funnel-chart';
+import { GeoChartUnresponsive } from '../geo-chart';
+import { HeatmapChart } from '../heatmap-chart';
+import { LeaderboardChartUnresponsive } from '../leaderboard-chart';
+import { LineChartUnresponsive } from '../line-chart';
+import { PieChartUnresponsive } from '../pie-chart';
+import { PieSemiCircleChartUnresponsive } from '../pie-semi-circle-chart';
+import type { GeoData } from '../../types';
+import type { ReactElement } from 'react';
+
+jest.mock( 'react-google-charts', () => ( { Chart: () => <div /> } ) );
+
+const series = [
+	{
+		label: 'Series A',
+		data: [
+			{ date: new Date( '2024-01-01' ), value: 10 },
+			{ date: new Date( '2024-01-02' ), value: 20 },
+		],
+	},
+];
+
+const slices = [
+	{ label: 'MacOS', value: 30, valueDisplay: '30', percentage: 60 },
+	{ label: 'Linux', value: 20, valueDisplay: '20', percentage: 40 },
+];
+
+const geoData: GeoData = [
+	[ 'Country', 'Value' ],
+	[ 'US', 100 ],
+	[ 'CA', 50 ],
+	[ 'GB', 25 ],
+];
+
+const funnelSteps = [
+	{ id: 'sessions', label: 'Sessions', rate: 100, count: 10000 },
+	{ id: 'cart', label: 'Cart', rate: 71.1, count: 7110 },
+	{ id: 'checkout', label: 'Checkout', rate: 52.5, count: 5250 },
+	{ id: 'purchase', label: 'Purchase', rate: 10.3, count: 1030 },
+];
+
+const heatmapData = [
+	{ label: 'W1', data: [ { value: 1 }, { value: 2 }, { value: null } ] },
+	{ label: 'W2', data: [ { value: 3 }, { value: 0 }, { value: 4 } ] },
+];
+
+const leaderboardData = [
+	{
+		id: 'direct',
+		label: 'Direct',
+		currentValue: 12500,
+		previousValue: 10000,
+		currentShare: 100,
+		previousShare: 80,
+		delta: 25,
+	},
+	{
+		id: 'social',
+		label: 'Social Media',
+		currentValue: 8750,
+		previousValue: 9500,
+		currentShare: 70,
+		previousShare: 76,
+		delta: -8,
+	},
+];
+
+const CHARTS: [ string, string, string, ( ariaLabel?: string ) => ReactElement ][] = [
+	[
+		'line',
+		'application',
+		'Line chart',
+		ariaLabel => (
+			<LineChartUnresponsive
+				data={ series }
+				width={ 400 }
+				height={ 300 }
+				withGradientFill={ false }
+				ariaLabel={ ariaLabel }
+			/>
+		),
+	],
+	[
+		'area',
+		'application',
+		'Area chart',
+		ariaLabel => (
+			<AreaChartUnresponsive data={ series } width={ 400 } height={ 300 } ariaLabel={ ariaLabel } />
+		),
+	],
+	[
+		'bar',
+		'application',
+		'Bar chart',
+		ariaLabel => (
+			<BarChartUnresponsive data={ series } width={ 400 } height={ 300 } ariaLabel={ ariaLabel } />
+		),
+	],
+	[
+		'bar list',
+		'application',
+		'Bar list chart',
+		ariaLabel => (
+			<BarListChartUnresponsive
+				data={ salesByProduct }
+				width={ 400 }
+				height={ 300 }
+				ariaLabel={ ariaLabel }
+			/>
+		),
+	],
+	[
+		'pie',
+		'application',
+		'Pie chart',
+		ariaLabel => <PieChartUnresponsive data={ slices } size={ 300 } ariaLabel={ ariaLabel } />,
+	],
+	[
+		'semi-circle',
+		'application',
+		'Semi-circle chart',
+		ariaLabel => (
+			<PieSemiCircleChartUnresponsive data={ slices } width={ 300 } ariaLabel={ ariaLabel } />
+		),
+	],
+	[
+		'geo',
+		'group',
+		'Geo chart',
+		ariaLabel => (
+			<GeoChartUnresponsive data={ geoData } width={ 800 } height={ 400 } ariaLabel={ ariaLabel } />
+		),
+	],
+	[
+		'conversion funnel',
+		'group',
+		'Conversion funnel chart',
+		ariaLabel => (
+			<ConversionFunnelChart mainRate={ 25 } steps={ funnelSteps } ariaLabel={ ariaLabel } />
+		),
+	],
+	[
+		'heatmap',
+		'grid',
+		'Heatmap chart',
+		ariaLabel => (
+			<HeatmapChart data={ heatmapData } width={ 500 } height={ 300 } ariaLabel={ ariaLabel } />
+		),
+	],
+	[
+		'leaderboard',
+		'list',
+		'Leaderboard chart',
+		ariaLabel => (
+			<LeaderboardChartUnresponsive
+				data={ leaderboardData }
+				width={ 400 }
+				height={ 300 }
+				ariaLabel={ ariaLabel }
+			/>
+		),
+	],
+];
+
+it.each( CHARTS )(
+	'names the %s chart from ariaLabel, or its default',
+	( _chart, role, defaultName, renderChart ) => {
+		const { unmount } = render( <GlobalChartsProvider>{ renderChart() }</GlobalChartsProvider> );
+		expect( screen.getByRole( role, { name: defaultName } ) ).toBeInTheDocument();
+		unmount();
+
+		render( <GlobalChartsProvider>{ renderChart( 'Views by day' ) }</GlobalChartsProvider> );
+		expect( screen.getByRole( role, { name: 'Views by day' } ) ).toBeInTheDocument();
+	}
+);

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

@@ -257,6 +257,23 @@ describe( 'useChartLegendItems', () => {
 				data: [ { label: 'Mon', value: 90 } ],
 			},
 		];
+		const twoMetricData: 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: 40 } ],
+			},
+		];
+		const perMetricLabel = ( metric: string ) => `${ metric } (Prev. 7 days)`;
 
 		test( 'is off by default', () => {
 			const { result } = renderHook(
@@ -300,15 +317,58 @@ describe( 'useChartLegendItems', () => {
 			expect( result.current.map( item => item.label ) ).toEqual( [ 'Views', 'Previous period' ] );
 		} );
 
-		test( 'adds nothing when the comparison series already has its own item', () => {
+		test( 'names one static item per compared metric with comparisonSeriesItems', () => {
 			const { result } = renderHook(
-				() => useChartLegendItems( comparisonData, { comparisonItem: true } ),
+				() =>
+					useChartLegendItems(
+						twoMetricData,
+						{ collapseGroups: true, comparisonSeriesItems: perMetricLabel },
+						'line'
+					),
 				{ wrapper }
 			);
 
-			expect( result.current.map( item => item.label ) ).toEqual( [ 'Views', 'Views — previous' ] );
+			expect( result.current.map( item => item.label ) ).toEqual( [
+				'Views',
+				'Visitors',
+				'Views (Prev. 7 days)',
+				'Visitors (Prev. 7 days)',
+			] );
+			expect(
+				result.current.slice( 2 ).map( ( { interactive, describesSeries } ) => ( {
+					interactive,
+					describesSeries,
+				} ) )
+			).toEqual( [
+				{ interactive: false, describesSeries: 'Views — previous' },
+				{ interactive: false, describesSeries: 'Visitors — previous' },
+			] );
+			expect( result.current[ 2 ].color ).toBe( result.current[ 0 ].color );
+			expect( result.current[ 3 ].color ).toBe( result.current[ 1 ].color );
 		} );
 
+		test.each( [
+			[
+				'comparisonItem',
+				comparisonData,
+				{ comparisonItem: true },
+				[ 'Views', 'Views — previous' ],
+			],
+			[
+				'comparisonSeriesItems',
+				twoMetricData,
+				{ comparisonSeriesItems: perMetricLabel },
+				[ 'Views', 'Views — previous', 'Visitors', 'Visitors — previous' ],
+			],
+		] )(
+			'adds nothing for %s when the comparison series already has its own item',
+			( _name, data, options, expected ) => {
+				const { result } = renderHook( () => useChartLegendItems( data, options ), { wrapper } );
+
+				expect( result.current.map( item => item.label ) ).toEqual( expected );
+			}
+		);
+
 		test( 'styles a current-period series by its own line styles, not the theme index', () => {
 			const theme = {
 				seriesLineStyles: [ { strokeWidth: 2 } ],

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

@@ -8,10 +8,12 @@ import {
 } from '../../../providers';
 import { formatPercentage } from '../../../utils';
 import type {
+	ComparisonItemLabel,
 	SeriesData,
 	DataPointDate,
 	DataPointPercentageCalculated,
 	LegendShape,
+	SeriesChartLegendConfig,
 } from '../../../types';
 import type { BaseLegendItem } from '../types';
 import type { GlyphProps } from '@visx/xychart';
@@ -36,7 +38,9 @@ export interface ChartLegendOptions {
 	 * `options.type === 'comparison'`. Skipped when that series already has its own
 	 * item. Pass a string to replace the default label.
 	 */
-	comparisonItem?: boolean | string;
+	comparisonItem?: SeriesChartLegendConfig[ 'comparisonItem' ];
+	/** One static item per comparison series instead; see `SeriesChartLegendConfig`. */
+	comparisonSeriesItems?: SeriesChartLegendConfig[ 'comparisonSeriesItems' ];
 }
 
 /**
@@ -276,6 +280,48 @@ function buildComparisonLegendItem(
 	return { label, color, shapeStyle: shapeStyles, interactive: false };
 }
 
+/**
+ * Builds one static item per comparison series folded into another series' item, named after
+ * that item and styled like the comparison series itself.
+ * @param seriesData       - The series data to search for comparison series
+ * @param items            - The legend items already built from the series
+ * @param formatLabel      - Names an item after the label of the item it was folded into
+ * @param getElementStyles - Function to get element styles
+ * @param legendShape      - The shape type for legend items (string literal or React component)
+ * @return The legend items, in series order
+ */
+function buildPerSeriesComparisonItems(
+	seriesData: SeriesData[],
+	items: BaseLegendItem[],
+	formatLabel: ComparisonItemLabel,
+	getElementStyles: ( params: GetElementStylesParams ) => ElementStyles,
+	legendShape?: LegendShape< SeriesData[], number >
+): BaseLegendItem[] {
+	return seriesData.flatMap( ( series, index ) => {
+		const owner = items.find( item => item.seriesLabels?.includes( series.label ) );
+
+		if (
+			series.options?.type !== 'comparison' ||
+			! owner ||
+			owner.seriesLabels?.[ 0 ] === series.label
+		) {
+			return [];
+		}
+
+		const { color, shapeStyles } = getElementStyles( { data: series, index, legendShape } );
+
+		return [
+			{
+				label: formatLabel( owner.label ),
+				color,
+				shapeStyle: shapeStyles,
+				interactive: false,
+				describesSeries: series.label,
+			},
+		];
+	} );
+}
+
 /**
  * Processes point data into legend items
  * @param pointData          - The point data to process
@@ -339,6 +385,7 @@ export function useChartLegendItems<
 		glyphSize = 8,
 		collapseGroups = false,
 		comparisonItem = false,
+		comparisonSeriesItems,
 		renderGlyph,
 	} = options;
 	const { getElementStyles } = useGlobalChartsContext();
@@ -361,6 +408,20 @@ export function useChartLegendItems<
 				renderGlyph,
 				legendShape
 			);
+
+			if ( comparisonSeriesItems ) {
+				return [
+					...items,
+					...buildPerSeriesComparisonItems(
+						seriesData,
+						items,
+						comparisonSeriesItems,
+						getElementStyles,
+						legendShape
+					),
+				];
+			}
+
 			const comparison = comparisonItem
 				? buildComparisonLegendItem(
 						seriesData,
@@ -396,6 +457,7 @@ export function useChartLegendItems<
 		glyphSize,
 		collapseGroups,
 		comparisonItem,
+		comparisonSeriesItems,
 		renderGlyph,
 		legendShape,
 	] );

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

@@ -11,6 +11,7 @@ import {
 	forwardRef,
 	useCallback,
 	useContext,
+	useMemo,
 } from 'react';
 import { ChartInstanceContext } from '../../../charts/private/chart-instance-context';
 import { useTextTruncation } from '../../../hooks';
@@ -115,7 +116,7 @@ export const BaseLegend: ForwardRefExoticComponent<
 > = forwardRef< HTMLDivElement, BaseLegendProps >(
 	(
 		{
-			items,
+			items: allItems,
 			className,
 			orientation = 'horizontal',
 			alignment = 'center',
@@ -154,6 +155,31 @@ export const BaseLegend: ForwardRefExoticComponent<
 		const chartInstanceContext = useContext( ChartInstanceContext );
 		const standaloneScopeClass = useStandaloneScopeClass();
 
+		// Disabling interaction for the whole legend still preserves its series' visibility state.
+		const isSeriesVisible = useCallback(
+			( seriesLabel: string ) => {
+				if ( chartInstanceContext?.isSeriesVisible ) {
+					return chartInstanceContext.isSeriesVisible( seriesLabel );
+				}
+				if ( ! chartId || ! context ) {
+					return true;
+				}
+				return context.isSeriesVisible( chartId, seriesLabel );
+			},
+			[ chartId, chartInstanceContext, context ]
+		);
+
+		const items = useMemo(
+			() =>
+				allItems.filter(
+					item =>
+						item.interactive !== false ||
+						! item.describesSeries ||
+						isSeriesVisible( item.describesSeries )
+				),
+			[ allItems, isSeriesVisible ]
+		);
+
 		// Keep duplicate labels: a static comparison item can share a metric's name.
 		const domain = items.map( item => item.label );
 		const legendScale = scaleOrdinal( {
@@ -189,20 +215,6 @@ export const BaseLegend: ForwardRefExoticComponent<
 			[ interactive, chartId, context ]
 		);
 
-		// Disabling interaction for the whole legend still preserves its series' visibility state.
-		const isSeriesVisible = useCallback(
-			( seriesLabel: string ) => {
-				if ( chartInstanceContext?.isSeriesVisible ) {
-					return chartInstanceContext.isSeriesVisible( seriesLabel );
-				}
-				if ( ! chartId || ! context ) {
-					return true;
-				}
-				return context.isSeriesVisible( chartId, seriesLabel );
-			},
-			[ chartId, chartInstanceContext, context ]
-		);
-
 		// Create event handlers to avoid inline arrow functions
 		const createClickHandler = useCallback(
 			( seriesLabels: string[], itemInteractive: boolean ) => {

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

@@ -801,6 +801,48 @@ describe( 'BaseLegend', () => {
 			expect( staticItem ).not.toHaveClass( 'legend-item--inactive' );
 		} );
 
+		it( 'leaves out a static item while its series is hidden, keeping later swatches aligned', async () => {
+			const user = userEvent.setup();
+			const items = [
+				{ label: 'Views', color: '#0000ff', seriesLabels: [ 'Views', 'Views · previous' ] },
+				{
+					label: 'Visitors',
+					color: '#00ff00',
+					seriesLabels: [ 'Visitors', 'Visitors · previous' ],
+				},
+				{
+					label: 'Views (Prev. 7 days)',
+					color: '#000088',
+					interactive: false,
+					describesSeries: 'Views · previous',
+				},
+				{
+					label: 'Visitors (Prev. 7 days)',
+					color: '#008800',
+					interactive: false,
+					describesSeries: 'Visitors · previous',
+				},
+			];
+
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend items={ items } interactive chartId="test-chart" shape={ TestShape } />
+				</GlobalChartsProvider>
+			);
+
+			await user.click( screen.getByRole( 'button', { name: /^Views/ } ) );
+
+			expect( screen.getAllByTestId( 'legend-item' ).map( item => item.textContent ) ).toEqual( [
+				'Views',
+				'Visitors',
+				'Visitors (Prev. 7 days)',
+			] );
+			expect( screen.getAllByTestId( 'legend-marker' )[ 2 ] ).toHaveAttribute( 'fill', '#008800' );
+
+			await user.click( screen.getByRole( 'button', { name: /^Views/ } ) );
+			expect( screen.getAllByTestId( 'legend-item' ) ).toHaveLength( 4 );
+		} );
+
 		it( 'keeps a comparison item distinct when its label collides', async () => {
 			const user = userEvent.setup();
 			const Example = () => {

package/src/components/legend/types.ts

@@ -63,4 +63,6 @@ export type BaseLegendItem = {
 	seriesLabels?: string[];
 	/** Set to false for a static item that cannot be toggled or dimmed. */
 	interactive?: boolean;
+	/** Label of the series this static item describes; the item is left out while it is hidden. */
+	describesSeries?: string;
 };

package/src/hooks/test/use-xychart-theme.test.tsx

@@ -1,4 +1,5 @@
 import { renderHook } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../providers';
 import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
 import { ChartScopeContext } from '../../providers/chart-scope';
 import { useXYChartTheme } from '../use-xychart-theme';
@@ -68,6 +69,27 @@ describe( 'useXYChartTheme', () => {
 		document.body.removeChild( scope );
 	} );
 
+	it.each( [
+		[ -12, 11 ],
+		[ Infinity, 11 ],
+		[ 14, 14 ],
+		[ '-12px', 11 ],
+		[ '12.px', 11 ],
+		[ '9'.repeat( 400 ) + 'px', 11 ],
+		[ '0.875rem', '0.875rem' ],
+		[ 'var(--size)', 'var(--size)' ],
+	] )( 'renders a theme fontSize of %p as %p', ( fontSize, expected ) => {
+		const wrapper = ( { children }: { children: ReactNode } ) => (
+			<GlobalChartsProvider theme={ { svgLabelSmall: { fontSize } } }>
+				{ children }
+			</GlobalChartsProvider>
+		);
+
+		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
+
+		expect( result.current.axisStyles.x.bottom.tickLabel.fontSize ).toBe( expected );
+	} );
+
 	it( 'gives the y axis its own roles, resolving to none', () => {
 		const { result } = renderHook( () => useXYChartTheme( [] ) );
 

package/src/hooks/use-xychart-theme.ts

@@ -3,9 +3,36 @@ import { useMemo } from 'react';
 import { useGlobalChartsTheme } from '../providers';
 import { CATALOG_POINTERS } from '../providers/chart-context/private/catalog-pointers';
 import { useChartScopeElement } from '../providers/chart-scope';
-import { createCssVariableResolver } from '../utils';
+import { createCssVariableResolver, resolveFontSize } from '../utils';
 import type { SeriesData } from '../types';
 
+type LabelStyle = { fontSize?: number | string };
+
+const STARTS_LIKE_A_NUMBER = /^[+-]?[\d.]/;
+const NON_NEGATIVE_CSS_NUMBER = /^\+?(?:\d*\.)?\d+(?:e[+-]?\d+)?(?:[a-z]+|%)?$/i;
+
+const isRenderableFontSize = ( fontSize: number | string ): boolean => {
+	if ( typeof fontSize === 'number' ) {
+		return resolveFontSize( fontSize ) !== undefined;
+	}
+	// A pattern, not `CSS.supports`, so SSR and the browser agree; `resolveFontSize` would drop renderable `rem`. Keywords, `var()` and `calc()` pass through.
+	const value = fontSize.trim();
+	if ( ! STARTS_LIKE_A_NUMBER.test( value ) ) {
+		return true;
+	}
+	return NON_NEGATIVE_CSS_NUMBER.test( value ) && Number.isFinite( parseFloat( value ) );
+};
+
+// visx writes `fontSize` straight onto `<text>`, where an invalid one renders at the browser's 16px default; dropping it lets visx use its own default.
+const withRenderableFontSize = < T extends LabelStyle >( style?: T ): T | undefined => {
+	if ( style?.fontSize === undefined || isRenderableFontSize( style.fontSize ) ) {
+		return style;
+	}
+	const rest = { ...style };
+	delete rest.fontSize;
+	return rest;
+};
+
 export const useXYChartTheme = ( data: SeriesData[] ) => {
 	const theme = useGlobalChartsTheme();
 	const scopeElement = useChartScopeElement();
@@ -47,7 +74,11 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 			xTickLineStyles: { ...theme.xTickLineStyles, stroke: CATALOG_POINTERS.tickX },
 			yAxisLineStyles: { stroke: CATALOG_POINTERS.axisY },
 			yTickLineStyles: { stroke: CATALOG_POINTERS.tickY },
-			svgLabelSmall: { ...theme.svgLabelSmall, fill: CATALOG_POINTERS.labelAxis },
+			svgLabelSmall: {
+				...withRenderableFontSize( theme.svgLabelSmall ),
+				fill: CATALOG_POINTERS.labelAxis,
+			},
+			svgLabelBig: withRenderableFontSize( theme.svgLabelBig ),
 		} );
 	}, [ theme, seriesColorKey, scopeElement ] );
 };

package/src/index.ts

@@ -68,6 +68,7 @@ export type {
 	LegendPosition,
 	ChartLegendConfig,
 	SeriesChartLegendConfig,
+	ComparisonItemLabel,
 	SeriesVisibilityProps,
 	BaseChartProps,
 	GoogleDataTableColumn,

package/src/types.ts

@@ -394,9 +394,15 @@ export type ChartTheme = {
 	 *
 	 * `fontFamily: 'inherit'` is load-bearing here — it overrides the font stack
 	 * `buildChartTheme` injects inline on SVG `<text>`.
+	 *
+	 * Give `fontSize` in pixels (`12` or `'12px'`). Margins and pie labels cannot measure `rem`, `em`, `%` or `var()`, so they use the default size and labels can clip (CHARTS-303). An invalid size is dropped.
 	 */
 	svgLabelSmall?: Omit< TextProps, 'fill' >;
-	/** Styles for large SVG text (eg. axis titles), passed through to the XYChart theme. */
+	/**
+	 * Styles for large SVG text (eg. axis titles), passed through to the XYChart theme.
+	 *
+	 * Give `fontSize` in pixels, as for `svgLabelSmall`.
+	 */
 	svgLabelBig?: TextProps;
 	annotationStyles?: ThemeAnnotationStyles;
 	/** LeaderboardChart specific settings */
@@ -654,6 +660,9 @@ export type ChartLegendConfig< T = DataPoint | DataPointDate | LeaderboardEntry
 	shapeStyles?: LegendShapeStyles;
 };
 
+/** Names a comparison series' legend item after the label of the series it is compared with. */
+export type ComparisonItemLabel = ( seriesLabel: string ) => string;
+
 /**
  * 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
@@ -674,6 +683,11 @@ export type SeriesChartLegendConfig = ChartLegendConfig< SeriesData[] > & {
 	 * Pass a string to replace the default label.
 	 */
 	comparisonItem?: boolean | string;
+	/**
+	 * Append one static item per comparison series instead, named by calling this with the label
+	 * of the series it is compared with, and left out while that series is hidden.
+	 */
+	comparisonSeriesItems?: ComparisonItemLabel;
 };
 
 /**
@@ -704,6 +718,10 @@ export type BaseChartProps< T = DataPoint | DataPointDate | LeaderboardEntry > =
 	 * Additional CSS class name for the chart container
 	 */
 	className?: string;
+	/**
+	 * Accessible name of the chart. Name it after what it shows, and give each chart on a page a different name. Each chart type has a localized default, such as "Line chart".
+	 */
+	ariaLabel?: string;
 	/**
 	 * Width of the chart container in pixels. When omitted, the chart fills its parent's width.
 	 */