@automattic/charts 0.57.0 → 0.58.0

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

@@ -60,7 +60,7 @@ describe( 'PieChart', () => {
 		test( 'renders legend when showLegend is true', () => {
 			renderWithTheme( {
 				showLegend: true,
-				legendPosition: 'top',
+				legend: { position: 'top' },
 			} );
 
 			// Check that legend container is rendered using accessible queries
@@ -72,7 +72,7 @@ describe( 'PieChart', () => {
 		test( 'renders correct number of legend items', () => {
 			renderWithTheme( {
 				showLegend: true,
-				legendPosition: 'top',
+				legend: { position: 'top' },
 			} );
 
 			// Use getAllByTestId to find legend items
@@ -83,7 +83,7 @@ describe( 'PieChart', () => {
 		test( 'chart renders with legend at top position', () => {
 			renderWithTheme( {
 				showLegend: true,
-				legendPosition: 'top',
+				legend: { position: 'top' },
 			} );
 
 			// Verify the chart renders without errors when legend is at top
@@ -98,7 +98,7 @@ describe( 'PieChart', () => {
 		test( 'chart renders with legend at bottom position', () => {
 			renderWithTheme( {
 				showLegend: true,
-				legendPosition: 'bottom',
+				legend: { position: 'bottom' },
 			} );
 
 			// Verify the chart renders without errors when legend is at bottom
@@ -379,7 +379,7 @@ describe( 'PieChart', () => {
 			renderWithTheme( {
 				data: testData,
 				showLegend: true,
-				legendInteractive: true,
+				legend: { interactive: true },
 				chartId: 'test-interactive-pie-chart',
 			} );
 
@@ -411,7 +411,7 @@ describe( 'PieChart', () => {
 			renderWithTheme( {
 				data: testData,
 				showLegend: true,
-				legendInteractive: true,
+				legend: { interactive: true },
 				chartId: 'test-all-hidden-pie-chart',
 			} );
 
@@ -450,7 +450,7 @@ describe( 'PieChart', () => {
 			renderWithTheme( {
 				data: testData,
 				showLegend: true,
-				legendInteractive: false,
+				legend: { interactive: false },
 				chartId: 'test-non-interactive-pie-chart',
 			} );
 
@@ -474,7 +474,7 @@ describe( 'PieChart', () => {
 			renderWithTheme( {
 				data: testData,
 				showLegend: true,
-				legendInteractive: true,
+				legend: { interactive: true },
 				chartId: 'test-color-consistency-pie-chart',
 			} );
 
@@ -506,7 +506,7 @@ describe( 'PieChart', () => {
 			renderWithTheme( {
 				data: testData,
 				showLegend: true,
-				legendInteractive: true,
+				legend: { interactive: true },
 				legendValueDisplay: 'percentage',
 				chartId: 'test-percentage-recalc-pie-chart',
 			} );

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

@@ -17,7 +17,12 @@ import {
 	GlobalChartsContext,
 } from '../../providers';
 import { attachSubComponents } from '../../utils';
-import { ChartSVG, ChartHTML, useChartChildren } from '../private/chart-composition';
+import {
+	ChartSVG,
+	ChartHTML,
+	useChartChildren,
+	renderLegendSlot,
+} from '../private/chart-composition';
 import { RadialWipeAnimation } from '../private/radial-wipe-animation';
 import { SingleChartContext } from '../private/single-chart-context';
 import { withResponsive } from '../private/with-responsive';
@@ -98,13 +103,6 @@ export interface PieSemiCircleChartProps extends BaseChartProps< DataPointPercen
 	 */
 	legendValueDisplay?: LegendValueDisplay;
 
-	/**
-	 * Enable interactive legend items that can toggle segment visibility.
-	 * Requires chartId and GlobalChartsProvider.
-	 * When segments are hidden, percentages are recalculated so visible segments total 100%.
-	 */
-	legendInteractive?: boolean;
-
 	/**
 	 * Horizontal offset for tooltip positioning in pixels (default: 0)
 	 */
@@ -167,15 +165,8 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 	clockwise = true,
 	withTooltips = false,
 	showLegend = false,
-	legendOrientation = 'horizontal',
-	legendPosition = 'bottom',
-	legendAlignment = 'center',
-	legendMaxWidth,
-	legendTextOverflow = 'wrap',
-	legendItemClassName,
-	legendShape = 'circle',
+	legend = {},
 	legendValueDisplay = 'percentage',
-	legendInteractive = false,
 	label,
 	animation,
 	note,
@@ -186,6 +177,9 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 	renderTooltip = renderDefaultPieSemiCircleTooltip,
 	gap = 'md',
 } ) => {
+	const legendInteractive = legend.interactive ?? false;
+	const legendPosition = legend.position ?? 'bottom';
+
 	const chartId = useChartId( providedChartId );
 	// Measure the SVG wrapper to calculate constrained dimensions
 	const [ svgWrapperRef, svgWrapperWidth, svgWrapperHeight ] = useElementSize< HTMLDivElement >();
@@ -277,7 +271,7 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 	const legendItems = useChartLegendItems( legendData, legendOptions );
 
 	// Process children to extract compound components
-	const { svgChildren, htmlChildren, otherChildren } = useChartChildren(
+	const { svgChildren, htmlChildren, legendChildren, otherChildren } = useChartChildren(
 		children,
 		'PieSemiCircleChart'
 	);
@@ -349,12 +343,14 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 
 	const legendElement = showLegend && (
 		<Legend
-			orientation={ legendOrientation }
+			orientation={ legend.orientation ?? 'horizontal' }
 			position={ legendPosition }
-			alignment={ legendAlignment }
-			labelStyles={ { maxWidth: legendMaxWidth, textOverflow: legendTextOverflow } }
-			itemClassName={ legendItemClassName }
-			shape={ legendShape }
+			alignment={ legend.alignment ?? 'center' }
+			labelStyles={ legend.labelStyles }
+			itemClassName={ legend.itemClassName }
+			itemStyles={ legend.itemStyles }
+			shapeStyles={ legend.shapeStyles }
+			shape={ legend.shape ?? 'circle' }
 			chartId={ chartId }
 			interactive={ legendInteractive }
 		/>
@@ -387,6 +383,7 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 				data-testid="pie-chart-container"
 			>
 				{ legendPosition === 'top' && legendElement }
+				{ renderLegendSlot( legendChildren, 'top' ) }
 
 				<div ref={ svgWrapperRef } className={ styles[ 'pie-semi-circle-chart__svg-wrapper' ] }>
 					<svg
@@ -483,7 +480,8 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 					</svg>
 				</div>
 
-				{ legendPosition !== 'top' && legendElement }
+				{ legendPosition === 'bottom' && legendElement }
+				{ renderLegendSlot( legendChildren, 'bottom' ) }
 
 				{ withTooltips && tooltipOpen && tooltipData && (
 					<TooltipInPortal top={ tooltipTop || 0 } left={ tooltipLeft || 0 }>

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

@@ -29,10 +29,10 @@ const mockData = [
 ];
 
 // Helper function to render component with providers
-const renderPieChart = props =>
+const renderPieChart = ( props, children = undefined ) =>
 	render(
 		<GlobalChartsProvider>
-			<PieSemiCircleChart { ...props } />
+			<PieSemiCircleChart { ...props }>{ children }</PieSemiCircleChart>
 		</GlobalChartsProvider>
 	);
 
@@ -256,6 +256,34 @@ describe( 'PieSemiCircleChart', () => {
 		} );
 	} );
 
+	describe( 'Composition Legend', () => {
+		test( 'renders composition legend as child component', () => {
+			renderPieChart( { data: mockData }, <PieSemiCircleChart.Legend /> );
+
+			expect( screen.getAllByTestId( 'legend-item' ) ).toHaveLength( 2 );
+			expect( screen.getByText( 'Category A' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Category B' ) ).toBeInTheDocument();
+		} );
+
+		test( 'renders composition legend regardless of showLegend value', () => {
+			renderPieChart( { data: mockData, showLegend: false }, <PieSemiCircleChart.Legend /> );
+
+			expect( screen.getAllByTestId( 'legend-item' ) ).toHaveLength( 2 );
+		} );
+
+		test( 'renders composition legend in top position', () => {
+			renderPieChart( { data: mockData }, <PieSemiCircleChart.Legend position="top" /> );
+
+			expect( screen.getAllByTestId( 'legend-item' ) ).toHaveLength( 2 );
+
+			// Legend should appear before the chart SVG in DOM order
+			const html = document.body.innerHTML;
+			expect( html.indexOf( 'data-testid="legend-horizontal"' ) ).toBeLessThan(
+				html.indexOf( 'data-testid="pie-chart-svg"' )
+			);
+		} );
+	} );
+
 	describe( 'Interactive Legend', () => {
 		test( 'filters segments when interactive legend is enabled and segment is toggled', async () => {
 			const user = userEvent.setup();
@@ -267,7 +295,7 @@ describe( 'PieSemiCircleChart', () => {
 			renderPieChart( {
 				data: testData,
 				showLegend: true,
-				legendInteractive: true,
+				legend: { interactive: true },
 				chartId: 'test-interactive-semi-circle-chart',
 			} );
 
@@ -299,7 +327,7 @@ describe( 'PieSemiCircleChart', () => {
 			renderPieChart( {
 				data: testData,
 				showLegend: true,
-				legendInteractive: true,
+				legend: { interactive: true },
 				chartId: 'test-all-hidden-semi-circle-chart',
 			} );
 
@@ -326,7 +354,7 @@ describe( 'PieSemiCircleChart', () => {
 			renderPieChart( {
 				data: testData,
 				showLegend: true,
-				legendInteractive: false,
+				legend: { interactive: false },
 				chartId: 'test-non-interactive-semi-circle-chart',
 			} );
 

package/src/charts/private/chart-composition/index.ts

@@ -1,4 +1,6 @@
 export { ChartSVG } from './chart-svg';
 export { ChartHTML } from './chart-html';
+export { renderLegendSlot } from './render-legend-slot';
 export { useChartChildren } from './use-chart-children';
+export type { LegendChild } from './use-chart-children';
 export type { BaseChartSubComponents, ChartComponentWithComposition } from './types';

package/src/charts/private/chart-composition/render-legend-slot.ts

@@ -0,0 +1,22 @@
+import { createElement, Fragment } from 'react';
+import type { LegendChild } from './use-chart-children';
+import type { LegendPosition } from '../../../types';
+import type { ReactNode } from 'react';
+
+/**
+ * Renders legend children filtered by position slot.
+ *
+ * @param {LegendChild[]}  legendChildren - The legend children to filter and render
+ * @param {LegendPosition} position       - The position slot to render
+ * @return {ReactNode[]} Array of legend elements for the given position
+ */
+export function renderLegendSlot(
+	legendChildren: LegendChild[],
+	position: LegendPosition
+): ReactNode[] {
+	return legendChildren
+		.filter( l => l.position === position )
+		.map( ( l, i ) =>
+			createElement( Fragment, { key: `legend-${ position }-${ i }` }, l.element )
+		);
+}

package/src/charts/private/chart-composition/test/render-legend-slot.test.tsx

@@ -0,0 +1,60 @@
+import { createElement } from 'react';
+import { renderLegendSlot } from '../render-legend-slot';
+import type { LegendChild } from '../use-chart-children';
+
+const makeLegend = ( position: 'top' | 'bottom', label: string ): LegendChild => ( {
+	element: createElement( 'div', null, label ),
+	position,
+} );
+
+describe( 'renderLegendSlot', () => {
+	it( 'should return an empty array when given no children', () => {
+		expect( renderLegendSlot( [], 'top' ) ).toHaveLength( 0 );
+	} );
+
+	it( 'should return an empty array when no children match the position', () => {
+		const children = [ makeLegend( 'bottom', 'Legend 1' ) ];
+
+		expect( renderLegendSlot( children, 'top' ) ).toHaveLength( 0 );
+	} );
+
+	it( 'should return a single matching child', () => {
+		const children = [ makeLegend( 'top', 'Legend 1' ) ];
+		const view = renderLegendSlot( children, 'top' );
+
+		expect( view ).toHaveLength( 1 );
+		expect( view[ 0 ] ).toHaveProperty( 'key', 'legend-top-0' );
+	} );
+
+	it( 'should return multiple matching children in order', () => {
+		const children = [ makeLegend( 'bottom', 'Legend 1' ), makeLegend( 'bottom', 'Legend 2' ) ];
+		const view = renderLegendSlot( children, 'bottom' );
+
+		expect( view ).toHaveLength( 2 );
+		expect( view[ 0 ] ).toHaveProperty( 'key', 'legend-bottom-0' );
+		expect( view[ 1 ] ).toHaveProperty( 'key', 'legend-bottom-1' );
+	} );
+
+	it( 'should filter out children with a different position', () => {
+		const children = [
+			makeLegend( 'top', 'Top Legend' ),
+			makeLegend( 'bottom', 'Bottom Legend' ),
+			makeLegend( 'top', 'Another Top Legend' ),
+		];
+
+		expect( renderLegendSlot( children, 'top' ) ).toHaveLength( 2 );
+		expect( renderLegendSlot( children, 'bottom' ) ).toHaveLength( 1 );
+	} );
+
+	it( 'should produce distinct keys for top and bottom slots', () => {
+		const children = [ makeLegend( 'top', 'Top' ), makeLegend( 'bottom', 'Bottom' ) ];
+		const [ topElement, bottomElement ] = [
+			renderLegendSlot( children, 'top' )[ 0 ],
+			renderLegendSlot( children, 'bottom' )[ 0 ],
+		];
+
+		expect( topElement ).toHaveProperty( 'key', 'legend-top-0' );
+		expect( bottomElement ).toHaveProperty( 'key', 'legend-bottom-0' );
+		expect( topElement ).not.toEqual( bottomElement );
+	} );
+} );

package/src/charts/private/chart-composition/test/use-chart-children.test.tsx

@@ -1,5 +1,6 @@
 import { renderHook } from '@testing-library/react';
 import { Group } from '@visx/group';
+import { Legend } from '../../../../components/legend';
 import { ChartSVG, ChartHTML } from '../index';
 import { useChartChildren } from '../use-chart-children';
 
@@ -22,6 +23,7 @@ describe( 'useChartChildren', () => {
 
 		expect( result.current.svgChildren ).toHaveLength( 1 );
 		expect( result.current.htmlChildren ).toHaveLength( 0 );
+		expect( result.current.legendChildren ).toHaveLength( 0 );
 		expect( result.current.otherChildren ).toHaveLength( 0 );
 	} );
 
@@ -58,6 +60,7 @@ describe( 'useChartChildren', () => {
 
 		expect( result.current.svgChildren ).toHaveLength( 1 );
 		expect( result.current.htmlChildren ).toHaveLength( 1 );
+		expect( result.current.legendChildren ).toHaveLength( 0 );
 		expect( result.current.otherChildren ).toHaveLength( 0 );
 	} );
 
@@ -112,6 +115,7 @@ describe( 'useChartChildren', () => {
 
 		expect( result.current.svgChildren ).toHaveLength( 0 );
 		expect( result.current.htmlChildren ).toHaveLength( 0 );
+		expect( result.current.legendChildren ).toHaveLength( 0 );
 		expect( result.current.otherChildren ).toHaveLength( 0 );
 	} );
 
@@ -128,4 +132,91 @@ describe( 'useChartChildren', () => {
 
 		expect( result.current.svgChildren ).toHaveLength( 3 );
 	} );
+
+	it( 'should extract Legend children to legendChildren with default position bottom', () => {
+		const children = <Legend />;
+
+		const { result } = renderHook( () => useChartChildren( children, 'TestChart' ) );
+
+		expect( result.current.legendChildren ).toHaveLength( 1 );
+		expect( result.current.legendChildren[ 0 ].position ).toBe( 'bottom' );
+		expect( result.current.otherChildren ).toHaveLength( 0 );
+	} );
+
+	it( 'should extract Legend children with position top', () => {
+		const children = <Legend position="top" />;
+
+		const { result } = renderHook( () => useChartChildren( children, 'TestChart' ) );
+
+		expect( result.current.legendChildren ).toHaveLength( 1 );
+		expect( result.current.legendChildren[ 0 ].position ).toBe( 'top' );
+		expect( result.current.otherChildren ).toHaveLength( 0 );
+	} );
+
+	it( 'should default to bottom for invalid position values', () => {
+		// @ts-expect-error -- testing invalid runtime value
+		const children = <Legend position="left" />;
+
+		const { result } = renderHook( () => useChartChildren( children, 'TestChart' ) );
+
+		expect( result.current.legendChildren ).toHaveLength( 1 );
+		expect( result.current.legendChildren[ 0 ].position ).toBe( 'bottom' );
+	} );
+
+	it( 'should exclude Legend children from nonLegendChildren', () => {
+		const children = [
+			<Legend key="legend" position="top" />,
+			<div key="other">Other Content</div>,
+		];
+
+		const { result } = renderHook( () => useChartChildren( children, 'TestChart' ) );
+
+		expect( result.current.legendChildren ).toHaveLength( 1 );
+		expect( result.current.nonLegendChildren ).toHaveLength( 1 );
+	} );
+
+	it( 'should preserve original child order in nonLegendChildren', () => {
+		const children = [
+			<div key="first">First</div>,
+			<Legend key="legend" position="top" />,
+			<Group key="group">
+				<text>SVG</text>
+			</Group>,
+			<div key="last">Last</div>,
+		];
+
+		const { result } = renderHook( () => useChartChildren( children, 'TestChart' ) );
+
+		expect( result.current.nonLegendChildren ).toHaveLength( 3 );
+		// Verify order matches original (minus the Legend)
+		expect( ( result.current.nonLegendChildren[ 0 ] as React.ReactElement ).key ).toBe( 'first' );
+		expect( ( result.current.nonLegendChildren[ 1 ] as React.ReactElement ).key ).toBe( 'group' );
+		expect( ( result.current.nonLegendChildren[ 2 ] as React.ReactElement ).key ).toBe( 'last' );
+	} );
+
+	it( 'should return empty nonLegendChildren when all children are Legends', () => {
+		const children = [
+			<Legend key="top" position="top" />,
+			<Legend key="bottom" position="bottom" />,
+		];
+
+		const { result } = renderHook( () => useChartChildren( children, 'TestChart' ) );
+
+		expect( result.current.legendChildren ).toHaveLength( 2 );
+		expect( result.current.nonLegendChildren ).toHaveLength( 0 );
+	} );
+
+	it( 'should extract multiple Legend children by position', () => {
+		const children = [
+			<Legend key="top" position="top" />,
+			<Legend key="bottom" position="bottom" />,
+		];
+
+		const { result } = renderHook( () => useChartChildren( children, 'TestChart' ) );
+
+		expect( result.current.legendChildren ).toHaveLength( 2 );
+		expect( result.current.legendChildren[ 0 ].position ).toBe( 'top' );
+		expect( result.current.legendChildren[ 1 ].position ).toBe( 'bottom' );
+		expect( result.current.otherChildren ).toHaveLength( 0 );
+	} );
 } );

package/src/charts/private/chart-composition/use-chart-children.ts

@@ -1,11 +1,21 @@
 import { Group } from '@visx/group';
 import { useMemo, Children, isValidElement } from 'react';
-import type { ReactNode } from 'react';
+import { Legend } from '../../../components/legend';
+import type { LegendPosition } from '../../../types';
+import type { ReactElement, ReactNode } from 'react';
+
+export type LegendChild = {
+	element: ReactElement;
+	position: LegendPosition;
+};
 
 interface ChartChildren {
 	svgChildren: ReactNode[];
 	htmlChildren: ReactNode[];
+	legendChildren: LegendChild[];
 	otherChildren: ReactNode[];
+	/** All children except Legend, in original order. */
+	nonLegendChildren: ReactNode[];
 }
 
 /**
@@ -21,10 +31,23 @@ export function useChartChildren( children: ReactNode, chartType: string ): Char
 	return useMemo( () => {
 		const svg: ReactNode[] = [];
 		const html: ReactNode[] = [];
+		const legend: LegendChild[] = [];
 		const other: ReactNode[] = [];
+		const nonLegend: ReactNode[] = [];
 
 		Children.forEach( children, child => {
 			if ( isValidElement( child ) ) {
+				// Extract Legend children for position-based slot rendering
+				if ( child.type === Legend ) {
+					const rawPosition = child.props?.position;
+					const position =
+						rawPosition === 'top' || rawPosition === 'bottom' ? rawPosition : 'bottom';
+
+					legend.push( { element: child as ReactElement, position } );
+
+					return;
+				}
+
 				// Check displayName for compound components
 				const childType = child.type as { displayName?: string };
 				const displayName = childType?.displayName;
@@ -51,8 +74,17 @@ export function useChartChildren( children: ReactNode, chartType: string ): Char
 					other.push( child );
 				}
 			}
+
+			// Preserve original order of all non-Legend children
+			nonLegend.push( child );
 		} );
 
-		return { svgChildren: svg, htmlChildren: html, otherChildren: other };
+		return {
+			svgChildren: svg,
+			htmlChildren: html,
+			legendChildren: legend,
+			otherChildren: other,
+			nonLegendChildren: nonLegend,
+		};
 	}, [ children, chartType ] );
 }

package/src/components/legend/index.ts

@@ -1,11 +1,4 @@
 export { Legend } from './legend';
 export { useChartLegendItems } from './hooks/use-chart-legend-items';
-export type {
-	LegendProps,
-	BaseLegendProps,
-	BaseLegendItem,
-	LegendItemStyles,
-	LegendLabelStyles,
-	LegendShapeStyles,
-} from './types';
+export type { LegendProps, BaseLegendProps, BaseLegendItem } from './types';
 export type { ChartLegendOptions, LegendValueDisplay } from './hooks/use-chart-legend-items';

package/src/components/legend/private/base-legend.module.scss

@@ -1,4 +1,5 @@
 .legend {
+	align-self: stretch;
 
 	&--horizontal {
 		display: flex;
@@ -11,52 +12,33 @@
 		display: flex;
 		flex-direction: column;
 		gap: 8px;
-
-		&.legend--alignment-start {
-			align-items: flex-start;
-		}
-
-		&.legend--alignment-center {
-			align-items: center;
-		}
-
-		&.legend--alignment-end {
-			align-items: flex-end;
-		}
 	}
 
-	// Position-based styles
-	&--position-top {
-		position: relative;
-
-		&.legend--alignment-start {
-			justify-content: flex-start;
-		}
-
-		&.legend--alignment-center {
-			justify-content: center;
-		}
+	&--alignment-start {
+		justify-content: flex-start;
+	}
 
-		&.legend--alignment-end {
-			justify-content: flex-end;
-		}
+	&--alignment-center {
+		justify-content: center;
 	}
 
-	&--position-bottom {
-		position: relative;
+	&--alignment-end {
+		justify-content: flex-end;
+	}
 
-		&.legend--alignment-start {
-			justify-content: flex-start;
-		}
+	// Vertical legends align on the cross-axis instead
+	&--vertical.legend--alignment-start {
+		align-items: flex-start;
+	}
 
-		&.legend--alignment-center {
-			justify-content: center;
-		}
+	&--vertical.legend--alignment-center {
+		align-items: center;
+	}
 
-		&.legend--alignment-end {
-			justify-content: flex-end;
-		}
+	&--vertical.legend--alignment-end {
+		align-items: flex-end;
 	}
+
 }
 
 .legend-item {

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

@@ -67,7 +67,6 @@ export const BaseLegend: ForwardRefExoticComponent<
 			items,
 			className,
 			orientation = 'horizontal',
-			position = 'bottom',
 			alignment = 'center',
 			shape = 'rect',
 			fill = valueOrIdentityString,
@@ -177,7 +176,6 @@ export const BaseLegend: ForwardRefExoticComponent<
 							styles.legend,
 							styles[ `legend--${ orientation }` ],
 							styles[ `legend--alignment-${ alignment }` ],
-							styles[ `legend--position-${ position }` ],
 							className
 						) }
 						style={ {