@automattic/charts 4.13.0 → 4.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "4.13.0",
+	"version": "4.14.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -63,7 +63,7 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.2.12",
+		"@automattic/number-formatters": "^1.3.0",
 		"@babel/runtime": "7.29.7",
 		"@date-fns/tz": "1.5.0",
 		"@react-spring/web": "10.1.2",
@@ -83,10 +83,10 @@
 		"@visx/tooltip": "^4.0.0",
 		"@visx/vendor": "^4.0.0",
 		"@visx/xychart": "^4.0.0",
-		"@wordpress/i18n": "^6.0.0",
-		"@wordpress/icons": "^18.0.0",
-		"@wordpress/theme": "2.3.0",
-		"@wordpress/ui": "0.24.0",
+		"@wordpress/i18n": "^7.0.0",
+		"@wordpress/icons": "^19.0.0",
+		"@wordpress/theme": "3.0.0",
+		"@wordpress/ui": "0.25.0",
 		"clsx": "2.1.1",
 		"date-fns": "^4.1.0",
 		"deepmerge": "4.3.1",
@@ -111,9 +111,9 @@
 		"@types/react-dom": "19.3.0",
 		"@typescript/native-preview": "7.0.0-dev.20260707.2",
 		"@visx/glyph": "4.0.0",
-		"@wordpress/components": "42.0.0",
-		"@wordpress/element": "9.0.0",
-		"@wordpress/private-apis": "2.0.0",
+		"@wordpress/components": "43.0.0",
+		"@wordpress/element": "10.0.0",
+		"@wordpress/private-apis": "3.0.0",
 		"babel-jest": "30.5.2",
 		"identity-obj-proxy": "^3.0.0",
 		"jest": "30.5.2",

package/src/charts/leaderboard-chart/leaderboard-chart.module.scss

@@ -49,7 +49,7 @@
 		}
 
 		.label {
-			padding-left: var(--wpds-dimension-padding-sm);
+			padding-inline-start: var(--a8c-charts-dimension-leaderboard-label-inset);
 		}
 
 		// The bar's 100% height needs a track that fills the row,

package/src/charts/leaderboard-chart/leaderboard-chart.tsx

@@ -23,6 +23,10 @@ import { getAllHiddenMessage } from '../private/svg-empty-state';
 import { withResponsive } from '../private/with-responsive';
 import { useFittedRowCount, useLeaderboardLegendItems } from './hooks';
 import styles from './leaderboard-chart.module.scss';
+import {
+	resolveLeaderboardEntries,
+	type ResolvedLeaderboardEntry,
+} from './private/resolve-leaderboard-entries';
 import type { LeaderboardChartProps } from './types';
 import type { LeaderboardEntry } from '../../types';
 
@@ -75,15 +79,15 @@ const getBarWidth = ( share: number ): string =>
 	`calc(${ share }% - var(--a8c-charts-dimension-leaderboard-bar-hover-inset, 0px) * ${ share } / 100)`;
 
 const hasPreviousValue = (
-	entry: LeaderboardEntry
-): entry is LeaderboardEntry & {
+	entry: ResolvedLeaderboardEntry
+): entry is ResolvedLeaderboardEntry & {
 	previousValue: number;
 	previousShare: number;
 } => entry.previousValue != null && entry.previousShare != null;
 
 const hasDeltaValue = (
-	entry: LeaderboardEntry
-): entry is LeaderboardEntry & {
+	entry: ResolvedLeaderboardEntry
+): entry is ResolvedLeaderboardEntry & {
 	previousValue: number;
 	previousShare: number;
 	delta: number;
@@ -128,6 +132,7 @@ const Bar = ( {
 
 	const bar = (
 		<div
+			data-testid="leaderboard-chart-bar"
 			className={ clsx( styles.bar, {
 				[ styles[ 'bar--animated' ] ]: animation,
 				[ styles[ 'bar--negative' ] ]: divergingScale && isNegative,
@@ -167,7 +172,7 @@ const BarWithLabel = ( {
 	isPrimaryVisible = true,
 	isComparisonVisible = true,
 }: {
-	entry: LeaderboardEntry;
+	entry: ResolvedLeaderboardEntry;
 	withComparison?: boolean;
 	withOverlayLabel?: boolean;
 	primaryColor: string;
@@ -225,6 +230,7 @@ const BarWithLabel = ( {
  * @param props.height           - Optional height of the chart container in pixels
  * @param props.withComparison   - Whether to show comparison data
  * @param props.withOverlayLabel - Whether to overlay the label on top of the bar
+ * @param props.negativeBars     - How a negative value draws: from a shared zero point, or as an empty bar
  * @param props.primaryColor     - Primary color for current period bars
  * @param props.secondaryColor   - Secondary color for comparison period bars
  * @param props.valueFormatter   - Custom formatter for values
@@ -249,6 +255,7 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 	height: propHeight,
 	withComparison = false,
 	withOverlayLabel = false,
+	negativeBars = 'diverge',
 	primaryColor,
 	secondaryColor,
 	valueFormatter = defaultValueFormatter,
@@ -318,11 +325,21 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 		return ! isPrimaryVisible;
 	}, [ isPrimaryVisible, isComparisonVisible, withComparison, withOverlayLabel ] );
 
+	const withComparisonBars = withComparison && ! withOverlayLabel;
+
+	const resolvedData = useMemo(
+		() =>
+			resolveLeaderboardEntries( data ?? [], {
+				includePrevious: withComparisonBars,
+				clampNegative: negativeBars === 'clamp',
+			} ),
+		[ data, withComparisonBars, negativeBars ]
+	);
+
 	// One negative share puts every row on a shared zero point, so the bars stay comparable.
 	const divergingScale = useMemo( (): DivergingScale | undefined => {
-		const withComparisonBars = withComparison && ! withOverlayLabel;
 		const scale = { negative: 0, positive: 0 };
-		for ( const entry of data ?? [] ) {
+		for ( const entry of resolvedData ) {
 			const shares = [ entry.currentShare ];
 			if ( withComparisonBars && hasPreviousValue( entry ) ) {
 				shares.push( entry.previousShare );
@@ -333,7 +350,7 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 			}
 		}
 		return scale.negative > 0 ? scale : undefined;
-	}, [ data, withComparison, withOverlayLabel ] );
+	}, [ resolvedData, withComparisonBars ] );
 
 	// Validate data
 	const isDataValid = Boolean( data && data.length > 0 );
@@ -471,7 +488,7 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 							columnGap={ COLUMN_GAP }
 							data-leaderboard-grid
 						>
-							{ data.map( ( entry, rowIndex ) => {
+							{ resolvedData.map( ( entry, rowIndex ) => {
 								// visibility, not clipping: hidden rows keep their geometry (so a
 								// taller container can reveal them) but leave hit testing, focus,
 								// and the accessibility tree.

package/src/charts/leaderboard-chart/private/resolve-leaderboard-entries.ts

@@ -0,0 +1,53 @@
+import type { LeaderboardEntry } from '../../../types';
+
+export type ResolvedLeaderboardEntry = LeaderboardEntry & { currentShare: number };
+
+const toShare = ( value: number, max: number ) => ( max === 0 ? 0 : ( value / max ) * 100 );
+
+const toDelta = ( currentValue: number, previousValue: number | undefined ) => {
+	if ( previousValue == null ) {
+		return undefined;
+	}
+	if ( previousValue === 0 ) {
+		return currentValue === 0 ? 0 : undefined;
+	}
+	return ( ( currentValue - previousValue ) / Math.abs( previousValue ) ) * 100;
+};
+
+/**
+ * Fills in the shares and delta an entry omits, derived from its values.
+ *
+ * @param data                    - Leaderboard entries; passed shares and delta win over derived ones.
+ * @param options                 - Resolver options.
+ * @param options.includePrevious - Whether previous values count toward the shared max.
+ * @param options.clampNegative   - Whether a negative share draws as an empty bar instead of below zero.
+ * @return Entries with `currentShare` always set.
+ */
+export function resolveLeaderboardEntries(
+	data: LeaderboardEntry[],
+	{ includePrevious, clampNegative = false }: { includePrevious: boolean; clampNegative?: boolean }
+): ResolvedLeaderboardEntry[] {
+	const magnitude = clampNegative ? ( value: number ) => Math.max( value, 0 ) : Math.abs;
+	const clamp = ( share: number ) => ( clampNegative ? Math.max( share, 0 ) : share );
+
+	const max = data.reduce( ( largest, { currentValue, previousValue } ) => {
+		const previous = includePrevious && previousValue != null ? magnitude( previousValue ) : 0;
+		return Math.max( largest, magnitude( currentValue ), previous );
+	}, 0 );
+
+	return data.map( entry => {
+		const passedOrDerivedPrevious =
+			entry.previousShare ??
+			( entry.previousValue != null ? toShare( entry.previousValue, max ) : undefined );
+		const previousShare =
+			passedOrDerivedPrevious !== undefined ? clamp( passedOrDerivedPrevious ) : undefined;
+		const delta = entry.delta ?? toDelta( entry.currentValue, entry.previousValue );
+
+		return {
+			...entry,
+			currentShare: clamp( entry.currentShare ?? toShare( entry.currentValue, max ) ),
+			...( previousShare !== undefined && { previousShare } ),
+			...( delta !== undefined && { delta } ),
+		};
+	} );
+}

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

@@ -81,6 +81,22 @@ describe( 'LeaderboardChart', () => {
 		expect( screen.getByText( '-8%' ) ).toBeInTheDocument();
 	} );
 
+	it( 'derives the delta of entries that pass only values', () => {
+		render(
+			<LeaderboardChart
+				data={ [
+					{ id: 'up', label: 'Up', currentValue: 100, previousValue: 80 },
+					{ id: 'down', label: 'Down', currentValue: 50, previousValue: 100 },
+				] }
+				withComparison={ true }
+				deltaFormatter={ testDeltaFormatter }
+			/>
+		);
+
+		expect( screen.getByText( '25delta' ) ).toBeInTheDocument();
+		expect( screen.getByText( '-50delta' ) ).toBeInTheDocument();
+	} );
+
 	it( 'shows a placeholder when a row has no previous value', () => {
 		render(
 			<LeaderboardChart
@@ -170,6 +186,31 @@ describe( 'LeaderboardChart', () => {
 		expect( screen.queryAllByTestId( 'leaderboard-chart-diverging-row' ) ).toHaveLength( expected );
 	} );
 
+	it( 'keeps every bar on one side when negative bars clamp', () => {
+		const data = [
+			{ ...mockData[ 0 ], currentShare: undefined, currentValue: -40 },
+			mockData[ 1 ],
+		];
+		render( <LeaderboardChart data={ data } withComparison negativeBars="clamp" /> );
+
+		expect( screen.queryAllByTestId( 'leaderboard-chart-diverging-row' ) ).toHaveLength( 0 );
+	} );
+
+	it.each( [
+		[ 'comparison bars draw', false, /^calc\(50%/ ],
+		[ 'the overlay label hides comparison bars', true, /^calc\(100%/ ],
+	] )( 'sizes the current bar against the max when %s', ( _, withOverlayLabel, expected ) => {
+		const data = [
+			{ id: 'a', label: 'A', currentValue: 50, previousValue: 100 },
+			{ id: 'b', label: 'B', currentValue: 25, previousValue: 10 },
+		] as LeaderboardEntry[];
+		render(
+			<LeaderboardChart data={ data } withComparison withOverlayLabel={ withOverlayLabel } />
+		);
+
+		expect( screen.getAllByTestId( 'leaderboard-chart-bar' )[ 0 ].style.width ).toMatch( expected );
+	} );
+
 	it( 'shows custom label when provided', () => {
 		render(
 			<LeaderboardChart

package/src/charts/leaderboard-chart/test/resolve-leaderboard-entries.test.ts

@@ -0,0 +1,146 @@
+import { resolveLeaderboardEntries } from '../private/resolve-leaderboard-entries';
+import type { LeaderboardEntry } from '../../../types';
+
+type EntryInput = Partial< LeaderboardEntry > & { currentValue: number };
+
+const toEntries = ( rows: EntryInput[] ) =>
+	rows.map( ( row, index ) => ( {
+		id: `row-${ index }`,
+		label: `Row ${ index }`,
+		...row,
+	} ) ) as LeaderboardEntry[];
+
+describe( 'resolveLeaderboardEntries', () => {
+	const comparisonRows = [
+		{ currentValue: 50, previousValue: 100 },
+		{ currentValue: 25, previousValue: 40 },
+	];
+
+	it( 'derives both shares and delta against one max across both periods', () => {
+		const result = resolveLeaderboardEntries( toEntries( comparisonRows ), {
+			includePrevious: true,
+		} );
+
+		expect(
+			result.map( ( { currentShare, previousShare, delta } ) => ( {
+				currentShare,
+				previousShare,
+				delta,
+			} ) )
+		).toEqual( [
+			{ currentShare: 50, previousShare: 100, delta: -50 },
+			{ currentShare: 25, previousShare: 40, delta: -37.5 },
+		] );
+	} );
+
+	it( 'lets a negative previous value set the max', () => {
+		const [ entry ] = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 10, previousValue: -40 } ] ),
+			{ includePrevious: true }
+		);
+
+		expect( entry ).toMatchObject( { currentShare: 25, previousShare: -100 } );
+	} );
+
+	it( 'ignores previous values for the max when comparison bars are not drawn', () => {
+		const result = resolveLeaderboardEntries( toEntries( comparisonRows ), {
+			includePrevious: false,
+		} );
+
+		expect( result.map( ( { currentShare } ) => currentShare ) ).toEqual( [ 100, 50 ] );
+	} );
+
+	it( 'keeps passed fields and derives the rest', () => {
+		const [ entry ] = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 50, currentShare: 10, previousValue: 100, delta: 7 } ] ),
+			{ includePrevious: true }
+		);
+
+		expect( entry ).toMatchObject( { currentShare: 10, delta: 7, previousShare: 100 } );
+	} );
+
+	it( 'derives a missing share from the max over every row, passed or not', () => {
+		const result = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 10, currentShare: 100 }, { currentValue: 20 } ] ),
+			{ includePrevious: false }
+		);
+
+		expect( result.map( ( { currentShare } ) => currentShare ) ).toEqual( [ 100, 100 ] );
+	} );
+
+	it( 'keeps the sign of negative values', () => {
+		const result = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: -30 }, { currentValue: 60 } ] ),
+			{ includePrevious: false }
+		);
+
+		expect( result.map( ( { currentShare } ) => currentShare ) ).toEqual( [ -50, 100 ] );
+	} );
+
+	it( 'clamps negative shares to 0 and sizes the rest against the largest positive value', () => {
+		const result = resolveLeaderboardEntries(
+			toEntries( [
+				{ currentValue: -90, previousValue: 30 },
+				{ currentValue: 60, previousValue: -10, previousShare: -20 },
+			] ),
+			{ includePrevious: true, clampNegative: true }
+		);
+
+		expect(
+			result.map( ( { currentShare, previousShare, delta } ) => ( {
+				currentShare,
+				previousShare,
+				delta,
+			} ) )
+		).toEqual( [
+			{ currentShare: 0, previousShare: 50, delta: -400 },
+			{ currentShare: 100, previousShare: 0, delta: 700 },
+		] );
+	} );
+
+	it.each( [
+		{ currentValue: 5, previousValue: -10, expected: 150 },
+		{ currentValue: 0, previousValue: 0, expected: 0 },
+		{ currentValue: 5, previousValue: 0, expected: undefined },
+		{ currentValue: 5, previousValue: undefined, expected: undefined },
+	] )(
+		'derives delta $expected for current $currentValue and previous $previousValue',
+		( { currentValue, previousValue, expected } ) => {
+			const [ entry ] = resolveLeaderboardEntries(
+				toEntries( [ { currentValue, previousValue } ] ),
+				{ includePrevious: true }
+			);
+
+			expect( entry.delta ).toBe( expected );
+		}
+	);
+
+	it( 'sizes rows without a previous value against the shared max', () => {
+		const result = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 50, previousValue: 100 }, { currentValue: 25 } ] ),
+			{ includePrevious: true }
+		);
+
+		expect( result.map( ( { currentShare } ) => currentShare ) ).toEqual( [ 50, 25 ] );
+		expect( result[ 1 ] ).not.toHaveProperty( 'previousShare' );
+	} );
+
+	it( 'gives shares of 0 when every value is 0', () => {
+		const [ entry ] = resolveLeaderboardEntries(
+			toEntries( [ { currentValue: 0, previousValue: 0 } ] ),
+			{ includePrevious: true }
+		);
+
+		expect( entry ).toMatchObject( { currentShare: 0, previousShare: 0, delta: 0 } );
+	} );
+
+	it( 'leaves other fields untouched', () => {
+		const onClick = jest.fn();
+		const [ entry ] = resolveLeaderboardEntries(
+			toEntries( [ { id: 'a', label: 'A', currentValue: 1, onClick } ] ),
+			{ includePrevious: false }
+		);
+
+		expect( entry ).toMatchObject( { id: 'a', label: 'A', onClick } );
+	} );
+} );

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

@@ -30,6 +30,12 @@ export interface LeaderboardChartProps extends Pick<
 	 */
 	withOverlayLabel?: boolean;
 
+	/**
+	 * How a negative value draws: `diverge` puts every row on a shared zero point, `clamp` draws it as an empty bar.
+	 * @default 'diverge'
+	 */
+	negativeBars?: 'diverge' | 'clamp';
+
 	/**
 	 * Primary color for current period bars
 	 */

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

@@ -217,24 +217,27 @@ export const BaseLegend: ForwardRefExoticComponent<
 
 		// Create event handlers to avoid inline arrow functions
 		const createClickHandler = useCallback(
-			( seriesLabels: string[], itemInteractive: boolean ) => {
+			( seriesLabels: string[], itemInteractive: boolean, onToggle?: () => void ) => {
 				if ( ! itemInteractive ) {
 					return undefined;
 				}
-				return () => handleLegendClick( seriesLabels );
+				return onToggle ? () => onToggle() : () => handleLegendClick( seriesLabels );
 			},
 			[ handleLegendClick ]
 		);
 
 		const createKeyDownHandler = useCallback(
-			( seriesLabels: string[], itemInteractive: boolean ) => {
+			( seriesLabels: string[], itemInteractive: boolean, onToggle?: () => void ) => {
 				if ( ! itemInteractive ) {
 					return undefined;
 				}
+				const toggle = onToggle ?? ( () => handleLegendClick( seriesLabels ) );
 				return ( event: KeyboardEvent ) => {
 					if ( event.key === 'Enter' || event.key === ' ' ) {
 						event.preventDefault();
-						handleLegendClick( seriesLabels );
+						if ( ! event.repeat ) {
+							toggle();
+						}
 					}
 				};
 			},
@@ -278,11 +281,13 @@ export const BaseLegend: ForwardRefExoticComponent<
 							const seriesLabels = matchedItem?.seriesLabels?.length
 								? matchedItem.seriesLabels
 								: [ label.text ];
-							const visible =
-								matchedItem?.interactive === false || isSeriesVisible( seriesLabels[ 0 ] );
 							const itemInteractive = interactive && matchedItem?.interactive !== false;
-							const handleClick = createClickHandler( seriesLabels, itemInteractive );
-							const handleKeyDown = createKeyDownHandler( seriesLabels, itemInteractive );
+							const onToggle = itemInteractive ? matchedItem?.onToggle : undefined;
+							const visible = matchedItem?.onToggle
+								? matchedItem.pressed
+								: matchedItem?.interactive === false || isSeriesVisible( seriesLabels[ 0 ] );
+							const handleClick = createClickHandler( seriesLabels, itemInteractive, onToggle );
+							const handleKeyDown = createKeyDownHandler( seriesLabels, itemInteractive, onToggle );
 
 							return (
 								<LegendItem

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

@@ -900,6 +900,131 @@ describe( 'BaseLegend', () => {
 		} );
 	} );
 
+	describe( 'Controlled items', () => {
+		const VisibilityProbe = () => {
+			const { isSeriesVisible } = useGlobalChartsContext();
+			return (
+				<output data-testid="views-visible">
+					{ String( isSeriesVisible( 'test-chart', 'Views' ) ) }
+				</output>
+			);
+		};
+
+		it.each( [ false, true ] )( 'takes the pressed state from the item (%s)', pressed => {
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend
+						items={ [ { label: 'Previous period', color: '#000', pressed, onToggle: jest.fn() } ] }
+						interactive
+						chartId="test-chart"
+					/>
+				</GlobalChartsProvider>
+			);
+
+			expect( screen.getByRole( 'button', { name: /Previous period/ } ) ).toHaveAttribute(
+				'aria-pressed',
+				String( pressed )
+			);
+		} );
+
+		it.each( [ 'click', 'Enter', ' ' ] )(
+			'calls onToggle on %s and leaves series visibility alone',
+			async interaction => {
+				const user = userEvent.setup();
+				const onToggle = jest.fn();
+				render(
+					<GlobalChartsProvider>
+						<BaseLegend
+							items={ [
+								{
+									label: 'Previous period',
+									color: '#000',
+									seriesLabels: [ 'Views' ],
+									pressed: false,
+									onToggle,
+								},
+							] }
+							interactive
+							chartId="test-chart"
+						/>
+						<VisibilityProbe />
+					</GlobalChartsProvider>
+				);
+
+				const button = screen.getByRole( 'button', { name: /Previous period/ } );
+				if ( interaction === 'click' ) {
+					await user.click( button );
+				} else {
+					button.focus();
+					await user.keyboard( interaction === ' ' ? ' ' : '{Enter}' );
+				}
+
+				expect( onToggle ).toHaveBeenCalledTimes( 1 );
+				expect( onToggle ).toHaveBeenCalledWith();
+				expect( screen.getByTestId( 'views-visible' ) ).toHaveTextContent( 'true' );
+			}
+		);
+
+		it( 'ignores key repeats while Enter is held', async () => {
+			const user = userEvent.setup();
+			const onToggle = jest.fn();
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend
+						items={ [ { label: 'Previous period', color: '#000', pressed: false, onToggle } ] }
+						interactive
+						chartId="test-chart"
+					/>
+				</GlobalChartsProvider>
+			);
+
+			screen.getByRole( 'button', { name: /Previous period/ } ).focus();
+			await user.keyboard( '{Enter>3/}' );
+
+			expect( onToggle ).toHaveBeenCalledTimes( 1 );
+		} );
+
+		const renderStaticControlledItem = ( pressed: boolean ) => {
+			const onToggle = jest.fn();
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend
+						items={ [
+							{
+								label: 'Previous period',
+								color: '#000',
+								seriesLabels: [ 'Views' ],
+								pressed,
+								onToggle,
+							},
+						] }
+						interactive={ false }
+						chartId="test-chart"
+					/>
+				</GlobalChartsProvider>
+			);
+			return { item: screen.getByTestId( 'legend-item' ), onToggle };
+		};
+
+		it( 'stays static in a legend that is not interactive', async () => {
+			const user = userEvent.setup();
+			const { item, onToggle } = renderStaticControlledItem( true );
+
+			expect( screen.queryByRole( 'button' ) ).not.toBeInTheDocument();
+			expect( item ).not.toHaveClass( 'legend-item--inactive' );
+			expect( item ).not.toHaveAttribute( 'aria-label' );
+			await user.click( item );
+			expect( onToggle ).not.toHaveBeenCalled();
+		} );
+
+		it( 'dims an item that is not pressed in a legend that is not interactive', () => {
+			const { item } = renderStaticControlledItem( false );
+
+			expect( item ).toHaveClass( 'legend-item--inactive' );
+			expect( item ).toHaveAttribute( 'aria-label', 'Previous period: hidden' );
+		} );
+	} );
+
 	describe( 'Non-interactive legend reflects hidden state', () => {
 		const HiddenSeriesHarness = ( { interactive }: { interactive: boolean } ) => {
 			const context = useGlobalChartsContext();

package/src/components/legend/types.ts

@@ -65,4 +65,12 @@ export type BaseLegendItem = {
 	interactive?: boolean;
 	/** Label of the series this static item describes; the item is left out while it is hidden. */
 	describesSeries?: string;
-};
+} & (
+	| {
+			/** Pressed state of the toggle. */
+			pressed: boolean;
+			/** Makes an interactive legend item a toggle the consumer controls, instead of a series toggle. */
+			onToggle: () => void;
+	  }
+	| { pressed?: never; onToggle?: never }
+);

package/src/styles/chart-scope.scss

@@ -87,6 +87,7 @@
 
 	--a8c-charts-dimension-leaderboard-row-gap: var(--wpds-dimension-gap-md);
 	--a8c-charts-dimension-leaderboard-column-gap: var(--wpds-dimension-gap-xs);
+	--a8c-charts-dimension-leaderboard-label-inset: var(--wpds-dimension-padding-sm);
 	--a8c-charts-dimension-legend-column-gap: var(--wpds-dimension-gap-lg);
 	--a8c-charts-dimension-legend-row-gap: var(--wpds-dimension-gap-sm);
 }

package/src/types.ts

@@ -214,20 +214,18 @@ type LeaderboardEntryFields = {
 	previousValue?: number;
 
 	/**
-	 * Width of current bar, as % of the largest absolute value across rows. A negative share
-	 * extends the bar from a shared zero point toward the inline start, for every row.
+	 * Width of current bar, as %. Derived from the values when omitted; a passed value wins.
+	 * A negative share extends the bar from a shared zero point toward the inline start, for every row.
 	 */
-	currentShare: number;
+	currentShare?: number;
 
 	/**
-	 * Width of previous bar, as % of the largest absolute value across rows. Omit when this
-	 * row has no matching comparison-period value.
+	 * Width of previous bar, as %. Derived from `previousValue` when omitted; a passed value wins.
 	 */
 	previousShare?: number;
 
 	/**
-	 * 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.
+	 * Percentage change. Derived from the values when omitted; a passed value wins.
 	 */
 	delta?: number;