@automattic/charts 4.8.0 → 4.10.0

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/components/tooltip/test/xy-chart-tooltip.test.tsx

@@ -42,7 +42,7 @@ const renderChart = ( scope?: HTMLElement, tooltipPlacement?: 'auto' | 'below-ax
 const openTooltip = async () => {
 	const user = userEvent.setup();
 
-	screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+	screen.getByRole( 'application', { name: /line chart/i } ).focus();
 	await user.keyboard( '{ArrowRight}' );
 
 	return screen.getByTestId( 'xy-chart-tooltip-crosshair-vertical' );
@@ -99,7 +99,7 @@ describe( 'XYChartTooltip', () => {
 		const user = userEvent.setup();
 		renderChart( undefined, 'below-axis' );
 		await openTooltip();
-		const focus = jest.spyOn( screen.getByRole( 'grid' ), 'focus' );
+		const focus = jest.spyOn( screen.getByRole( 'application' ), 'focus' );
 		try {
 			await user.keyboard( keys );
 			expect( focus ).toHaveBeenCalledWith( { preventScroll: true } );
@@ -115,7 +115,7 @@ describe( 'XYChartTooltip', () => {
 		const user = userEvent.setup();
 		renderChart();
 		await openTooltip();
-		const focus = jest.spyOn( screen.getByRole( 'grid' ), 'focus' );
+		const focus = jest.spyOn( screen.getByRole( 'application' ), 'focus' );
 		try {
 			await user.keyboard( keys );
 			expect( focus ).toHaveBeenCalledWith();
@@ -131,7 +131,7 @@ describe( 'XYChartTooltip', () => {
 	} );
 } );
 
-// Mirrors the charts' markup: the focusable grid wraps the element `chartRef` points at.
+// Mirrors the charts' markup: the focusable chart container wraps the element `chartRef` points at.
 const NavigationHarness = ( {
 	totalPoints,
 	trackBlur = false,
@@ -155,8 +155,9 @@ const NavigationHarness = ( {
 
 	return (
 		<>
+			{ /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- mirrors the charts' container. */ }
 			<div
-				role="grid"
+				role="application"
 				aria-label="Harness"
 				tabIndex={ 0 }
 				onKeyDown={ onChartKeyDown }
@@ -179,7 +180,7 @@ describe( 'useKeyboardNavigation', () => {
 		const user = userEvent.setup();
 		const view = render( <NavigationHarness totalPoints={ 6 } /> );
 
-		screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+		screen.getByRole( 'application', { name: 'Harness' } ).focus();
 		for ( let i = 0; i < presses; i++ ) {
 			await user.keyboard( '{ArrowRight}' );
 		}
@@ -188,13 +189,13 @@ describe( 'useKeyboardNavigation', () => {
 		return { user, view };
 	};
 
-	it( 'moves the selection to the last point when the count shrinks while the grid has focus', async () => {
+	it( 'moves the selection to the last point when the count shrinks while the chart has focus', async () => {
 		const { view } = await navigate( 6 );
 
 		view.rerender( <NavigationHarness totalPoints={ 3 } /> );
 
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '2' );
-		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+		expect( screen.getByRole( 'application', { name: 'Harness' } ) ).toHaveFocus();
 	} );
 
 	// In range rather than past the end: the effect reconciles on any count change, not only an overflow.
@@ -207,24 +208,24 @@ describe( 'useKeyboardNavigation', () => {
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
 	} );
 
-	it( 'returns focus to the grid on Escape when there are no points', async () => {
+	it( 'returns focus to the chart on Escape when there are no points', async () => {
 		const user = userEvent.setup();
 		render( <NavigationHarness totalPoints={ 0 } /> );
 
 		screen.getByRole( 'button', { name: 'Inside' } ).focus();
 		await user.keyboard( '{Escape}' );
 
-		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+		expect( screen.getByRole( 'application', { name: 'Harness' } ) ).toHaveFocus();
 	} );
 
-	it( 'returns focus to the grid when the count drops to zero while focus is in the chart', async () => {
+	it( 'returns focus to the chart when the count drops to zero while focus is in the chart', async () => {
 		const { view } = await navigate( 2 );
 
 		screen.getByRole( 'button', { name: 'Inside' } ).focus();
 		view.rerender( <NavigationHarness totalPoints={ 0 } /> );
 
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
-		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+		expect( screen.getByRole( 'application', { name: 'Harness' } ) ).toHaveFocus();
 	} );
 
 	it( 'hands a keyboard selection to the pointer and continues from where the pointer is', async () => {
@@ -234,7 +235,7 @@ describe( 'useKeyboardNavigation', () => {
 		await user.hover( screen.getByTestId( 'point-4' ) );
 
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
-		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+		expect( screen.getByRole( 'application', { name: 'Harness' } ) ).toHaveFocus();
 
 		await user.keyboard( '{ArrowRight}' );
 
@@ -254,13 +255,13 @@ describe( 'useKeyboardNavigation', () => {
 	it( 'restarts from the first point once focus leaves after the pointer took over', async () => {
 		const user = userEvent.setup();
 		render( <NavigationHarness totalPoints={ 6 } trackBlur /> );
-		const grid = screen.getByRole( 'grid', { name: 'Harness' } );
+		const chart = screen.getByRole( 'application', { name: 'Harness' } );
 
-		act( () => grid.focus() );
+		act( () => chart.focus() );
 		await user.keyboard( '{ArrowRight}{ArrowRight}' );
 		await user.hover( screen.getByTestId( 'point-4' ) );
 		act( () => screen.getByRole( 'button', { name: 'Outside' } ).focus() );
-		act( () => grid.focus() );
+		act( () => chart.focus() );
 		await user.keyboard( '{ArrowRight}' );
 
 		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '0' );
@@ -281,7 +282,7 @@ describe( 'useKeyboardNavigation', () => {
 		const user = userEvent.setup();
 		render( <NavigationHarness totalPoints={ 6 } /> );
 
-		screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+		screen.getByRole( 'application', { name: 'Harness' } ).focus();
 		await user.hover( screen.getByTestId( 'point-4' ) );
 		await user.keyboard( '{ArrowRight}' );
 
@@ -301,7 +302,7 @@ describe( 'useKeyboardNavigation', () => {
 		const { onKeyDown, stop } = recordPageKeyDown();
 
 		try {
-			screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+			screen.getByRole( 'application', { name: 'Harness' } ).focus();
 			await user.keyboard( '{ArrowDown}{PageDown}[Space]' );
 
 			expect( onKeyDown ).toHaveBeenCalledTimes( 3 );
@@ -320,7 +321,7 @@ describe( 'useKeyboardNavigation', () => {
 		const { onKeyDown, stop } = recordPageKeyDown();
 
 		try {
-			screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+			screen.getByRole( 'application', { name: 'Harness' } ).focus();
 			await user.keyboard( '{Escape}' );
 
 			expect( onKeyDown.mock.calls[ 0 ][ 0 ].defaultPrevented ).toBe( false );

package/src/components/tooltip/xy-chart-tooltip.tsx

@@ -261,10 +261,10 @@ export const useKeyboardNavigation = ( {
 	preventTooltipScroll = false,
 	visibleSeriesKey,
 }: UseKeyboardNavigationProps ) => {
-	// `chartRef` sits inside the focusable grid, so the grid is what focus returns to and is measured against.
+	// `chartRef` sits inside the focusable chart container, so that container is what focus returns to and is measured against.
 	const getChartRoot = useCallback(
 		(): HTMLElement | null =>
-			chartRef.current?.closest< HTMLElement >( '[role="grid"]' ) ?? chartRef.current,
+			chartRef.current?.closest< HTMLElement >( '[role="application"]' ) ?? chartRef.current,
 		[ chartRef ]
 	);
 
@@ -401,7 +401,7 @@ export const useKeyboardNavigation = ( {
 				pointerIndex.current = undefined;
 			}
 
-			// WAI-ARIA grid: arrows stop at the first and last cell.
+			// Arrows stop at the first and last point.
 			if ( event.key === 'ArrowRight' ) {
 				event.preventDefault();
 				setIsNavigating( true );

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

@@ -191,7 +191,7 @@ export type DataPointDate = {
 	color?: string;
 };
 
-export type LeaderboardEntry = {
+type LeaderboardEntryFields = {
 	/**
 	 * Unique internal key (e.g., 'key-direct')
 	 */
@@ -245,7 +245,8 @@ export type LeaderboardEntry = {
 	 * For links or other interactive affordances (external-link icons, info
 	 * tooltips), put them in the `label` render prop instead of using onClick —
 	 * a row is either a button (onClick) or carries interactive label content,
-	 * never both, since interactive elements cannot be nested in HTML.
+	 * never both, since interactive elements cannot be nested in HTML. The
+	 * exception is a row that sets `hasInteractiveLabel`.
 	 */
 	onClick?: ( event: MouseEvent< HTMLButtonElement > ) => void;
 
@@ -261,6 +262,21 @@ export type LeaderboardEntry = {
 	ariaLabel?: string;
 };
 
+export type LeaderboardEntry = LeaderboardEntryFields &
+	(
+		| { hasInteractiveLabel?: false }
+		| {
+				/**
+				 * Set when the `label` holds its own link or button. The row's button
+				 * then sits behind the row instead of around it, so both stay operable.
+				 * Requires `onClick`, and `ariaLabel` since the button wraps no text.
+				 */
+				hasInteractiveLabel: true;
+				onClick: ( event: MouseEvent< HTMLButtonElement > ) => void;
+				ariaLabel: string;
+		  }
+	);
+
 export type GradientStop = {
 	offset: string;
 	color?: string;
@@ -378,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 */
@@ -638,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
@@ -658,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;
 };
 
 /**
@@ -688,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.
 	 */

package/src/utils/resolve-font-size.ts

@@ -1,13 +1,16 @@
+const toFontSize = ( size: number ): number | undefined =>
+	Number.isFinite( size ) && size >= 0 ? size : undefined;
+
 /**
  * Resolve a theme `fontSize` value into a plain number suitable for
  * canvas-based measurement (e.g. `getStringWidth`).
  *
  * Accepts:
- * - A number — returned as-is
+ * - A finite, non-negative number — returned as-is
  * - A pixel string like `"12px"` — parsed and returned as a number
  *
- * Returns `undefined` for any other input (missing value, NaN, or
- * relative units like `rem`/`em`/`%`/`vh`) so callers can fall back to
+ * Returns `undefined` for any other input (missing value, a non-finite or
+ * negative size, or relative units like `rem`/`em`/`%`/`vh`) so callers can fall back to
  * their own default. Relative units are intentionally rejected because
  * we cannot resolve them to absolute pixels here without a parent
  * computed style, and silently returning the unitless prefix
@@ -18,19 +21,15 @@
  */
 export const resolveFontSize = ( val?: number | string ): number | undefined => {
 	if ( typeof val === 'number' ) {
-		return isNaN( val ) ? undefined : val;
+		return toFontSize( val );
 	}
 
 	if ( typeof val === 'string' ) {
 		// Only accept plain numeric strings or pixel values.
 		// Reject rem, em, %, vh, vw, etc. — they cannot be resolved to
 		// absolute pixels without a computed style context.
-		const match = val.trim().match( /^(-?\d+\.?\d*|-?\.\d+)(px)?$/ );
-		if ( ! match ) {
-			return undefined;
-		}
-		const parsed = parseFloat( match[ 1 ] );
-		return isNaN( parsed ) ? undefined : parsed;
+		const match = val.trim().match( /^\+?((?:\d*\.)?\d+)(px)?$/ );
+		return match ? toFontSize( parseFloat( match[ 1 ] ) ) : undefined;
 	}
 
 	return undefined;

package/src/utils/test/resolve-font-size.test.ts

@@ -11,8 +11,8 @@ describe( 'resolveFontSize', () => {
 			expect( resolveFontSize( 13.5 ) ).toBe( 13.5 );
 		} );
 
-		it( 'returns undefined for NaN', () => {
-			expect( resolveFontSize( NaN ) ).toBeUndefined();
+		it.each( [ NaN, Infinity, -12 ] )( 'returns undefined for %p', val => {
+			expect( resolveFontSize( val ) ).toBeUndefined();
 		} );
 	} );
 
@@ -25,8 +25,17 @@ describe( 'resolveFontSize', () => {
 		it( 'parses pixel strings', () => {
 			expect( resolveFontSize( '12px' ) ).toBe( 12 );
 			expect( resolveFontSize( '13.5px' ) ).toBe( 13.5 );
+			expect( resolveFontSize( '.5px' ) ).toBe( 0.5 );
+			expect( resolveFontSize( '+12px' ) ).toBe( 12 );
 		} );
 
+		it.each( [ '12.px', '12.', '-12px', '-.5', '9'.repeat( 400 ) + 'px' ] )(
+			'rejects %p, which is not a valid font size',
+			val => {
+				expect( resolveFontSize( val ) ).toBeUndefined();
+			}
+		);
+
 		it( 'trims whitespace before parsing', () => {
 			expect( resolveFontSize( '  14px  ' ) ).toBe( 14 );
 		} );