@automattic/charts 0.56.7 → 0.57.0

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

@@ -69,30 +69,36 @@ export const BaseLegend: ForwardRefExoticComponent<
 			orientation = 'horizontal',
 			position = 'bottom',
 			alignment = 'center',
-			maxWidth,
-			textOverflow = 'wrap',
 			shape = 'rect',
 			fill = valueOrIdentityString,
 			size = valueOrIdentityString,
 			labelFormat = valueOrIdentity,
 			labelTransform = labelTransformFactory,
-			shapeWidth = 16,
-			shapeHeight = 16,
-			shapeMargin = '2px 4px 2px 0',
-			labelAlign = 'left',
-			labelFlex = '0 0 auto', // Use natural width instead of expanding to fill space
-			labelMargin = '0 4px',
-			itemMargin = '0',
-			itemDirection = 'row',
-			legendLabelProps,
-			legendItemClassName,
+			itemStyles,
+			itemClassName,
+			labelStyles,
+			labelClassName,
+			shapeStyles,
 			render,
 			interactive = false,
 			chartId,
-			...legendItemProps
 		},
 		ref
 	) => {
+		const { margin: itemMargin = '0', flexDirection: itemDirection = 'row' } = itemStyles ?? {};
+		const {
+			justifyContent: labelJustifyContent = 'flex-start',
+			flex: labelFlex = '0 0 auto',
+			margin: labelMargin = '0 4px',
+			maxWidth,
+			textOverflow = 'wrap',
+		} = labelStyles ?? {};
+		const {
+			width: shapeWidth = 16,
+			height: shapeHeight = 16,
+			margin: shapeMargin = '2px 4px 2px 0',
+		} = shapeStyles ?? {};
+
 		const theme = useGlobalChartsTheme();
 		const context = useContext( GlobalChartsContext );
 
@@ -176,13 +182,14 @@ export const BaseLegend: ForwardRefExoticComponent<
 						) }
 						style={ {
 							flexDirection: orientationToFlexDirection[ orientation ],
-							...theme.legendContainerStyles,
+							...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 ];
 
 							return (
 								<LegendItem
@@ -191,7 +198,7 @@ export const BaseLegend: ForwardRefExoticComponent<
 										styles[ 'legend-item' ],
 										interactive && styles[ 'legend-item--interactive' ],
 										! visible && styles[ 'legend-item--inactive' ],
-										legendItemClassName
+										itemClassName
 									) }
 									data-testid="legend-item"
 									key={ `legend-${ label.text }-${ i }` }
@@ -211,7 +218,6 @@ export const BaseLegend: ForwardRefExoticComponent<
 											? `${ label.text }: ${ visible ? 'visible' : 'hidden' }. Toggle visibility.`
 											: undefined
 									}
-									{ ...legendItemProps }
 								>
 									{ items[ i ]?.renderGlyph ? (
 										<svg
@@ -246,24 +252,28 @@ export const BaseLegend: ForwardRefExoticComponent<
 										/>
 									) }
 									<LegendLabel
-										className={ clsx( 'visx-legend-label', styles[ 'legend-item-label' ] ) }
+										data-testid="legend-label"
+										className={ clsx(
+											'visx-legend-label',
+											styles[ 'legend-item-label' ],
+											labelClassName
+										) }
 										style={ {
-											justifyContent: labelAlign,
+											justifyContent: labelJustifyContent,
 											flex: labelFlex,
 											margin: labelMargin,
-											...theme.legendLabelStyles,
+											...theme.legend?.labelStyles,
 										} }
-										{ ...legendLabelProps }
 									>
 										<LegendText
 											text={ label.text }
 											textOverflow={ textOverflow }
 											maxWidth={ maxWidth }
 										/>
-										{ items.find( item => item.label === label.text )?.value && (
+										{ matchedItem?.value != null && matchedItem.value !== '' && (
 											<span className={ styles[ 'legend-item-value' ] }>
 												{ '\u00A0' }
-												{ items.find( item => item.label === label.text )?.value }
+												{ matchedItem.value }
 											</span>
 										) }
 									</LegendLabel>

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

@@ -46,12 +46,12 @@ describe( 'BaseLegend', () => {
 		expect( legendItems ).toHaveLength( 0 );
 	} );
 
-	test( 'applies legendItemClassName to legend items', () => {
+	test( 'applies itemClassName to legend items', () => {
 		render(
 			<BaseLegend
 				items={ defaultItems }
 				orientation="horizontal"
-				legendItemClassName="custom-legend-item"
+				itemClassName="custom-legend-item"
 			/>
 		);
 		const legendItems = screen.getAllByTestId( 'legend-item' );
@@ -60,16 +60,65 @@ describe( 'BaseLegend', () => {
 		} );
 	} );
 
+	test( 'applies labelClassName to legend labels', () => {
+		render(
+			<BaseLegend
+				items={ defaultItems }
+				orientation="horizontal"
+				labelClassName="custom-legend-label"
+			/>
+		);
+		const labels = screen.getAllByTestId( 'legend-label' );
+		labels.forEach( label => {
+			expect( label ).toHaveClass( 'custom-legend-label' );
+		} );
+	} );
+
 	test( 'handles missing values', () => {
 		const itemsWithoutValues = [
-			{ label: 'Item 1', color: '#ff0000', value: undefined },
-			{ label: 'Item 2', color: '#00ff00', value: undefined },
+			{ label: 'Item 1', color: '#ff0000' },
+			{ label: 'Item 2', color: '#00ff00' },
 		];
 		render( <BaseLegend items={ itemsWithoutValues } orientation="horizontal" /> );
 		expect( screen.getByText( 'Item 1' ) ).toBeInTheDocument();
 		expect( screen.getByText( 'Item 2' ) ).toBeInTheDocument();
 	} );
 
+	test( 'does not render value span for empty string values', () => {
+		const itemsWithEmptyValues = [
+			{ label: 'Item 1', color: '#ff0000', value: '' },
+			{ label: 'Item 2', color: '#00ff00', value: '' },
+		];
+		render( <BaseLegend items={ itemsWithEmptyValues } orientation="horizontal" /> );
+		expect( screen.getByText( 'Item 1' ) ).toBeInTheDocument();
+		expect( screen.getByText( 'Item 2' ) ).toBeInTheDocument();
+		expect( screen.queryByText( '\u00A0' ) ).not.toBeInTheDocument();
+	} );
+
+	test( 'renders numeric value of 0 without hiding it', () => {
+		const itemsWithZeroValue = [
+			{ label: 'Item 1', color: '#ff0000', value: 0 },
+			{ label: 'Item 2', color: '#00ff00', value: '0%' },
+		];
+		render( <BaseLegend items={ itemsWithZeroValue } orientation="horizontal" /> );
+		expect( screen.getByText( '0' ) ).toBeInTheDocument();
+		expect( screen.getByText( '0%' ) ).toBeInTheDocument();
+	} );
+
+	test( 'renders each value next to its corresponding label by index', () => {
+		const itemsWithDistinctValues = [
+			{ label: 'Alpha', value: '100', color: '#ff0000' },
+			{ label: 'Beta', value: '200', color: '#00ff00' },
+			{ label: 'Gamma', value: '300', color: '#0000ff' },
+		];
+		render( <BaseLegend items={ itemsWithDistinctValues } orientation="horizontal" /> );
+		const legendItems = screen.getAllByTestId( 'legend-item' );
+		expect( legendItems ).toHaveLength( 3 );
+		expect( legendItems[ 0 ] ).toHaveTextContent( /Alpha.*100/ );
+		expect( legendItems[ 1 ] ).toHaveTextContent( /Beta.*200/ );
+		expect( legendItems[ 2 ] ).toHaveTextContent( /Gamma.*300/ );
+	} );
+
 	test( 'applies custom className', () => {
 		render(
 			<BaseLegend items={ defaultItems } className="custom-legend" orientation="horizontal" />
@@ -106,108 +155,155 @@ describe( 'BaseLegend', () => {
 			{ label: 'Another Long Label for Testing', value: '30%', color: '#00ff00' },
 		];
 
-		test( 'renders with maxWidth constraint', () => {
-			render( <BaseLegend items={ longLabelItems } maxWidth="150px" orientation="horizontal" /> );
-			const legendItems = screen.getAllByTestId( 'legend-item' );
-			expect( legendItems ).toHaveLength( 2 );
-			// Note: maxWidth is applied to LegendLabel via inline styles,
-			// which is harder to test without DOM traversal
+		test( 'applies maxWidth and minWidth styles to label text', () => {
+			render(
+				<BaseLegend
+					items={ longLabelItems }
+					labelStyles={ { maxWidth: '150px' } }
+					orientation="horizontal"
+				/>
+			);
+			const labels = screen.getAllByText( /Long Label/ );
+			labels.forEach( label => {
+				expect( label ).toHaveStyle( { maxWidth: '150px', minWidth: 0 } );
+			} );
 		} );
 
-		test( 'renders with maxWidth as string', () => {
-			render( <BaseLegend items={ longLabelItems } maxWidth="10rem" orientation="horizontal" /> );
-			const legendItems = screen.getAllByTestId( 'legend-item' );
-			expect( legendItems ).toHaveLength( 2 );
-			// Note: maxWidth is applied to LegendLabel via inline styles
+		test( 'supports different CSS units for maxWidth', () => {
+			render(
+				<BaseLegend
+					items={ longLabelItems }
+					labelStyles={ { maxWidth: '10rem' } }
+					orientation="horizontal"
+				/>
+			);
+			const labels = screen.getAllByText( /Long Label/ );
+			labels.forEach( label => {
+				expect( label ).toHaveStyle( { maxWidth: '10rem' } );
+			} );
 		} );
 
-		test( 'renders correctly with and without maxWidth', () => {
+		test( 'does not apply maxWidth styles when omitted', () => {
 			const { rerender } = render(
 				<BaseLegend items={ longLabelItems } orientation="horizontal" />
 			);
 
-			// Without maxWidth, legend items should render normally
-			let legendItems = screen.getAllByTestId( 'legend-item' );
-			expect( legendItems ).toHaveLength( 2 );
+			let labels = screen.getAllByText( /Long Label/ );
+			labels.forEach( label => {
+				expect( label ).not.toHaveStyle( { maxWidth: '150px' } );
+			} );
 
-			// With maxWidth, legend items should still render
-			rerender( <BaseLegend items={ longLabelItems } maxWidth="150px" orientation="horizontal" /> );
-			legendItems = screen.getAllByTestId( 'legend-item' );
-			expect( legendItems ).toHaveLength( 2 );
+			rerender(
+				<BaseLegend
+					items={ longLabelItems }
+					labelStyles={ { maxWidth: '150px' } }
+					orientation="horizontal"
+				/>
+			);
+			labels = screen.getAllByText( /Long Label/ );
+			labels.forEach( label => {
+				expect( label ).toHaveStyle( { maxWidth: '150px', minWidth: 0 } );
+			} );
 		} );
 
-		test( 'renders with different textOverflow values', () => {
-			// Test ellipsis behavior - should render without errors
+		test( 'applies maxWidth styles for both textOverflow modes', () => {
 			const { rerender } = render(
 				<BaseLegend
 					items={ longLabelItems }
-					maxWidth="150px"
-					textOverflow="ellipsis"
+					labelStyles={ { maxWidth: '150px', textOverflow: 'ellipsis' } }
 					orientation="horizontal"
 				/>
 			);
 			let labels = screen.getAllByText( /Long Label/ );
-			expect( labels ).toHaveLength( 2 );
+			labels.forEach( label => {
+				expect( label ).toHaveStyle( { maxWidth: '150px', minWidth: 0 } );
+			} );
 
-			// Test wrap behavior - should render without errors
 			rerender(
 				<BaseLegend
 					items={ longLabelItems }
-					maxWidth="150px"
-					textOverflow="wrap"
+					labelStyles={ { maxWidth: '150px', textOverflow: 'wrap' } }
 					orientation="horizontal"
 				/>
 			);
 			labels = screen.getAllByText( /Long Label/ );
-			expect( labels ).toHaveLength( 2 );
+			labels.forEach( label => {
+				expect( label ).toHaveStyle( { maxWidth: '150px', minWidth: 0 } );
+			} );
 		} );
 
-		test( 'renders ellipsis mode without errors', () => {
-			// Render with ellipsis overflow
+		test( 'applies maxWidth=0px correctly', () => {
 			render(
 				<BaseLegend
 					items={ longLabelItems }
-					maxWidth="50px"
-					textOverflow="ellipsis"
+					labelStyles={ { maxWidth: '0px', textOverflow: 'ellipsis' } }
 					orientation="horizontal"
 				/>
 			);
-
-			// Verify the text is rendered
 			const labels = screen.getAllByText( /Long Label/ );
-			expect( labels ).toHaveLength( 2 );
+			labels.forEach( label => {
+				expect( label ).toHaveStyle( { maxWidth: '0px', minWidth: 0 } );
+			} );
 		} );
 
-		test( 'renders wrap mode without errors', () => {
-			// Render with wrap overflow
+		test( 'applies legend-item-text--ellipsis class when textOverflow is ellipsis and maxWidth is set', () => {
 			render(
 				<BaseLegend
 					items={ longLabelItems }
-					maxWidth="50px"
-					textOverflow="wrap"
+					labelStyles={ { maxWidth: '150px', textOverflow: 'ellipsis' } }
 					orientation="horizontal"
 				/>
 			);
+			const labels = screen.getAllByText( /Long Label/ );
+			labels.forEach( label => {
+				expect( label ).toHaveClass( 'legend-item-text--ellipsis' );
+				expect( label ).not.toHaveClass( 'legend-item-text--wrap' );
+			} );
+		} );
 
-			// Verify the text is rendered
+		test( 'applies legend-item-text--wrap class when textOverflow is wrap and maxWidth is set', () => {
+			render(
+				<BaseLegend
+					items={ longLabelItems }
+					labelStyles={ { maxWidth: '150px', textOverflow: 'wrap' } }
+					orientation="horizontal"
+				/>
+			);
 			const labels = screen.getAllByText( /Long Label/ );
-			expect( labels ).toHaveLength( 2 );
+			labels.forEach( label => {
+				expect( label ).toHaveClass( 'legend-item-text--wrap' );
+				expect( label ).not.toHaveClass( 'legend-item-text--ellipsis' );
+			} );
 		} );
 
-		test( 'handles maxWidth={0} correctly', () => {
-			// maxWidth={0} should apply 0-pixel constraint (not be treated as "no constraint")
+		test( 'does not apply overflow class when maxWidth is not set', () => {
 			render(
 				<BaseLegend
 					items={ longLabelItems }
-					maxWidth="0px"
-					textOverflow="ellipsis"
+					labelStyles={ { textOverflow: 'ellipsis' } }
 					orientation="horizontal"
 				/>
 			);
+			const labels = screen.getAllByText( /Long Label/ );
+			labels.forEach( label => {
+				expect( label ).not.toHaveClass( 'legend-item-text--ellipsis' );
+				expect( label ).not.toHaveClass( 'legend-item-text--wrap' );
+			} );
+		} );
 
-			// Should still render the legend items
-			const legendItems = screen.getAllByTestId( 'legend-item' );
-			expect( legendItems ).toHaveLength( 2 );
+		test( 'does not apply overflow class when maxWidth is not set and textOverflow is wrap', () => {
+			render(
+				<BaseLegend
+					items={ longLabelItems }
+					labelStyles={ { textOverflow: 'wrap' } }
+					orientation="horizontal"
+				/>
+			);
+			const labels = screen.getAllByText( /Long Label/ );
+			labels.forEach( label => {
+				expect( label ).not.toHaveClass( 'legend-item-text--wrap' );
+				expect( label ).not.toHaveClass( 'legend-item-text--ellipsis' );
+			} );
 		} );
 	} );
 

package/src/components/legend/types.ts

@@ -2,20 +2,22 @@ import { LegendOrdinal } from '@visx/legend';
 import type { GlyphProps, LineStyles } from '@visx/xychart';
 import type { ComponentProps, CSSProperties, ReactNode } from 'react';
 
-// See https://airbnb.io/visx/docs/legend#Ordinal for more details.
-type LegendOrdinalProps = Omit< ComponentProps< typeof LegendOrdinal >, 'scale' | 'direction' >;
+type VisxLegendProps = Pick<
+	ComponentProps< typeof LegendOrdinal >,
+	'className' | 'shape' | 'fill' | 'size' | 'labelFormat' | 'labelTransform'
+>;
 
-export type BaseLegendProps = Omit< LegendOrdinalProps, 'shapeStyle' > & {
-	items: BaseLegendItem[];
-	orientation?: 'horizontal' | 'vertical';
-	/**
-	 * TODO: Add 'left' | 'right' positioning support in future implementation
-	 */
-	position?: 'top' | 'bottom';
-	alignment?: 'start' | 'center' | 'end';
+export type LegendItemStyles = {
+	/** Margin around each legend item. */
+	margin?: CSSProperties[ 'margin' ];
+	/** Flex direction for items within each legend entry. */
+	flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
+};
+
+export type LegendLabelStyles = Pick< CSSProperties, 'justifyContent' | 'flex' | 'margin' > & {
 	/**
-	 * Maximum width for legend items. When set, text overflow behavior is controlled by textOverflow prop.
-	 * Should be a CSS value string (e.g. '200px', '50%', '10rem')
+	 * Maximum width for legend label text as a CSS value (e.g. '200px', '50%', '10rem').
+	 * When set, text overflow behavior is controlled by textOverflow.
 	 */
 	maxWidth?: string;
 	/**
@@ -24,11 +26,35 @@ export type BaseLegendProps = Omit< LegendOrdinalProps, 'shapeStyle' > & {
 	 * - 'wrap': Wrap text to multiple lines (default, ideal for larger displays)
 	 */
 	textOverflow?: 'ellipsis' | 'wrap';
+};
+
+export type LegendShapeStyles = {
+	/** Width of the legend shape in pixels. */
+	width?: number;
+	/** Height of the legend shape in pixels. */
+	height?: number;
+	/** Margin around the legend shape. */
+	margin?: CSSProperties[ 'margin' ];
+};
+
+export type BaseLegendProps = VisxLegendProps & {
+	items: BaseLegendItem[];
+	orientation?: 'horizontal' | 'vertical';
 	/**
-	 * Additional CSS class name for legend items.
-	 * This allows consumers to customize individual legend item styling.
+	 * TODO: Add 'left' | 'right' positioning support in future implementation
 	 */
-	legendItemClassName?: string;
+	position?: 'top' | 'bottom';
+	alignment?: 'start' | 'center' | 'end';
+	/** Additional CSS class name for legend items. */
+	itemClassName?: string;
+	/** CSS styles for each legend item (margin, flexDirection). */
+	itemStyles?: LegendItemStyles;
+	/** Additional CSS class name for legend labels. */
+	labelClassName?: string;
+	/** CSS styles for legend labels (justifyContent, flex, margin). */
+	labelStyles?: LegendLabelStyles;
+	/** Styles for legend shapes (width, height, margin). */
+	shapeStyles?: LegendShapeStyles;
 	/**
 	 * Function for rendering a custom legend layout.
 	 */
@@ -51,7 +77,7 @@ export type LegendProps = Omit< BaseLegendProps, 'items' > & {
 
 export type BaseLegendItem = {
 	label: string;
-	value: number | string;
+	value?: number | string;
 	color: string;
 	glyphSize?: number;
 	renderGlyph?: < Datum extends object >( props: GlyphProps< Datum > ) => ReactNode;