@automattic/charts 0.57.0 → 0.59.0

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

@@ -1,7 +1,7 @@
 import { renderHook } from '@testing-library/react';
 import { GlobalChartsProvider } from '../../../../providers';
 import { useChartLegendItems } from '../use-chart-legend-items';
-import type { DataPointPercentage, DataPointDate, SeriesData } from '../../../../types';
+import type { DataPointPercentageCalculated, DataPointDate, SeriesData } from '../../../../types';
 import type { ReactNode } from 'react';
 
 // Wrapper component to provide GlobalChartsProvider context
@@ -11,8 +11,8 @@ const wrapper = ( { children }: { children: ReactNode } ) => (
 
 describe( 'useChartLegendItems', () => {
 	describe( 'Number Formatting (i18n)', () => {
-		describe( 'DataPointPercentage', () => {
-			const percentageData: DataPointPercentage[] = [
+		describe( 'DataPointPercentageCalculated', () => {
+			const percentageData: DataPointPercentageCalculated[] = [
 				{ label: 'Item 1', value: 80000, percentage: 60.6 },
 				{ label: 'Item 2', value: 30000, percentage: 22.7 },
 				{ label: 'Item 3', value: 22000, percentage: 16.7 },
@@ -50,7 +50,7 @@ describe( 'useChartLegendItems', () => {
 			} );
 
 			test( 'uses valueDisplay when provided, falling back to formatted value', () => {
-				const dataWithDisplay: DataPointPercentage[] = [
+				const dataWithDisplay: DataPointPercentageCalculated[] = [
 					{ label: 'Item 1', value: 80000, percentage: 60, valueDisplay: 'Custom 80K' },
 					{ label: 'Item 2', value: 30000, percentage: 30 },
 				];
@@ -194,7 +194,9 @@ describe( 'useChartLegendItems', () => {
 		} );
 
 		test( 'handles data with zero values', () => {
-			const zeroData: DataPointPercentage[] = [ { label: 'Zero Value', value: 0, percentage: 0 } ];
+			const zeroData: DataPointPercentageCalculated[] = [
+				{ label: 'Zero Value', value: 0, percentage: 0 },
+			];
 
 			const { result } = renderHook(
 				() =>
@@ -209,7 +211,7 @@ describe( 'useChartLegendItems', () => {
 		} );
 
 		test( 'handles very large numbers', () => {
-			const largeData: DataPointPercentage[] = [
+			const largeData: DataPointPercentageCalculated[] = [
 				{ label: 'Large', value: 1234567890, percentage: 100 },
 			];
 
@@ -227,7 +229,7 @@ describe( 'useChartLegendItems', () => {
 		} );
 
 		test( 'handles decimal values', () => {
-			const decimalData: DataPointPercentage[] = [
+			const decimalData: DataPointPercentageCalculated[] = [
 				{ label: 'Decimal', value: 1234.5678, percentage: 100 },
 			];
 
@@ -247,7 +249,9 @@ describe( 'useChartLegendItems', () => {
 
 	describe( 'Label and Color', () => {
 		test( 'preserves label and color from data', () => {
-			const data: DataPointPercentage[] = [ { label: 'Test Label', value: 100, percentage: 100 } ];
+			const data: DataPointPercentageCalculated[] = [
+				{ label: 'Test Label', value: 100, percentage: 100 },
+			];
 
 			const { result } = renderHook(
 				() =>

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

@@ -6,7 +6,7 @@ import {
 	type ElementStyles,
 } from '../../../providers';
 import { formatPercentage } from '../../../utils';
-import type { SeriesData, DataPointDate, DataPointPercentage } from '../../../types';
+import type { SeriesData, DataPointDate, DataPointPercentageCalculated } from '../../../types';
 import type { BaseLegendItem } from '../types';
 import type { LegendShape } from '@visx/legend/lib/types';
 import type { GlyphProps } from '@visx/xychart';
@@ -31,7 +31,7 @@ export interface ChartLegendOptions {
  * @return Formatted value string
  */
 function formatPointValue(
-	point: DataPointDate | DataPointPercentage,
+	point: DataPointDate | DataPointPercentageCalculated,
 	showValues: boolean,
 	legendValueDisplay: LegendValueDisplay = 'percentage'
 ): string {
@@ -39,16 +39,15 @@ function formatPointValue(
 		return '';
 	}
 
-	// Handle DataPointPercentage (pie chart data)
+	// Handle DataPointPercentageCalculated (pie chart data with calculated percentage)
 	if ( 'percentage' in point ) {
-		const percentagePoint = point as DataPointPercentage;
 		switch ( legendValueDisplay ) {
 			case 'percentage':
-				return formatPercentage( percentagePoint.percentage );
+				return formatPercentage( point.percentage );
 			case 'value':
-				return formatNumber( percentagePoint.value );
+				return formatNumber( point.value );
 			case 'valueDisplay':
-				return percentagePoint.valueDisplay || formatNumber( percentagePoint.value );
+				return point.valueDisplay || formatNumber( point.value );
 			default:
 				return '';
 		}
@@ -145,7 +144,7 @@ function processSeriesData(
  * @return Array of processed legend items
  */
 function processPointData(
-	pointData: ( DataPointDate | DataPointPercentage )[],
+	pointData: ( DataPointDate | DataPointPercentageCalculated )[],
 	getElementStyles: ( params: GetElementStylesParams ) => ElementStyles,
 	showValues: boolean,
 	legendValueDisplay: LegendValueDisplay,
@@ -154,9 +153,9 @@ function processPointData(
 	renderGlyph?: < Datum extends object >( props: GlyphProps< Datum > ) => ReactNode,
 	legendShape?: LegendShape< SeriesData[], number >
 ): BaseLegendItem[] {
-	const mapper = ( point: DataPointDate | DataPointPercentage, index: number ) => {
+	const mapper = ( point: DataPointDate | DataPointPercentageCalculated, index: number ) => {
 		const { color, glyph, shapeStyles } = getElementStyles( {
-			data: point as DataPointPercentage,
+			data: point as DataPointPercentageCalculated,
 			index,
 			legendShape,
 		} );
@@ -182,7 +181,7 @@ function processPointData(
  * @return Array of legend items ready for display
  */
 export function useChartLegendItems<
-	T extends SeriesData[] | DataPointDate[] | DataPointPercentage[],
+	T extends SeriesData[] | DataPointDate[] | DataPointPercentageCalculated[],
 >(
 	data: T,
 	options: ChartLegendOptions = {},
@@ -215,9 +214,9 @@ export function useChartLegendItems<
 			);
 		}
 
-		// Handle DataPointDate or DataPointPercentage (single data points)
+		// Handle DataPointDate or DataPointPercentageCalculated (single data points)
 		return processPointData(
-			data as ( DataPointDate | DataPointPercentage )[],
+			data as ( DataPointDate | DataPointPercentageCalculated )[],
 			getElementStyles,
 			showValues,
 			legendValueDisplay,

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/legend.tsx

@@ -3,9 +3,21 @@ import { SingleChartContext } from '../../charts/private/single-chart-context';
 import { GlobalChartsContext } from '../../providers';
 import { BaseLegend } from './private';
 import type { LegendProps } from './types';
+import type { ChartType } from '../../types';
+import type { LegendShape } from '@visx/legend/lib/types';
+
+const defaultShapeByChartType: Partial<
+	Record< ChartType, Extract< LegendShape< unknown, unknown >, string > >
+> = {
+	line: 'line',
+	bar: 'rect',
+	pie: 'circle',
+	'pie-semi-circle': 'circle',
+	leaderboard: 'circle',
+};
 
 export const Legend = forwardRef< HTMLDivElement, LegendProps >(
-	( { chartId, items, ...props }, ref ) => {
+	( { chartId, items, shape, ...props }, ref ) => {
 		// Get context but don't throw if it doesn't exist
 		const context = useContext( GlobalChartsContext );
 		const singleChartContext = useContext( SingleChartContext );
@@ -14,12 +26,17 @@ export const Legend = forwardRef< HTMLDivElement, LegendProps >(
 		// When chartId is not provided, we use the context's chartId, meaning it is in a single chart context
 		const contextChartId = chartId ?? singleChartContext?.chartId;
 
-		// Use useMemo to ensure re-rendering when context changes
-		const contextItems = useMemo( () => {
-			return contextChartId && context
-				? context.getChartData( contextChartId )?.legendItems
-				: undefined;
-		}, [ contextChartId, context ] );
+		const chartData = useMemo(
+			() => ( contextChartId && context ? context.getChartData( contextChartId ) : undefined ),
+			[ contextChartId, context ]
+		);
+
+		const contextItems = chartData?.legendItems;
+
+		// Derive the default legend shape from the chart type when no explicit shape is provided
+		const resolvedShape =
+			shape ??
+			( chartData?.chartType ? defaultShapeByChartType[ chartData.chartType ] : undefined );
 
 		// Provided items take precedence over context items
 		const legendItems = ( items || contextItems ) as typeof items;
@@ -28,6 +45,14 @@ export const Legend = forwardRef< HTMLDivElement, LegendProps >(
 			return null;
 		}
 
-		return <BaseLegend ref={ ref } items={ legendItems } { ...props } chartId={ contextChartId } />;
+		return (
+			<BaseLegend
+				ref={ ref }
+				items={ legendItems }
+				shape={ resolvedShape }
+				{ ...props }
+				chartId={ contextChartId }
+			/>
+		);
 	}
 );

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={ {

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

@@ -1,8 +1,12 @@
 /* eslint-disable react/jsx-no-bind */
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { GlobalChartsProvider } from '../../../providers';
+import { useMemo } from 'react';
+import { SingleChartContext } from '../../../charts/private/single-chart-context';
+import { GlobalChartsProvider, useChartId, useChartRegistration } from '../../../providers';
+import { Legend } from '../legend';
 import { BaseLegend } from '../private/base-legend';
+import type { ChartType } from '../../../types';
 import type { LegendProps } from '../types';
 
 const TestShape: LegendProps[ 'shape' ] = props => {
@@ -425,6 +429,94 @@ describe( 'BaseLegend', () => {
 		} );
 	} );
 
+	describe( 'Legend shape defaults from chart type', () => {
+		const legendItems = [
+			{ label: 'Series 1', color: '#ff0000' },
+			{ label: 'Series 2', color: '#00ff00' },
+		];
+
+		const CustomShape: LegendProps[ 'shape' ] = props => (
+			<span data-testid="custom-shape" style={ { color: props.fill as string } } />
+		);
+
+		const ChartRegistrar = ( {
+			chartType,
+			chartId,
+		}: {
+			chartType: ChartType;
+			chartId: string;
+		} ) => {
+			const resolvedId = useChartId( chartId );
+			const metadata = useMemo( () => ( {} ), [] );
+			useChartRegistration( {
+				chartId: resolvedId,
+				legendItems,
+				chartType,
+				isDataValid: true,
+				metadata,
+			} );
+			return null;
+		};
+
+		const renderLegendWithChartType = (
+			chartType: ChartType,
+			explicitShape?: LegendProps[ 'shape' ]
+		) => {
+			const chartId = `test-${ chartType }`;
+
+			return render(
+				<GlobalChartsProvider>
+					<ChartRegistrar chartType={ chartType } chartId={ chartId } />
+					<SingleChartContext.Provider value={ { chartId } }>
+						<Legend shape={ explicitShape } />
+					</SingleChartContext.Provider>
+				</GlobalChartsProvider>
+			);
+		};
+
+		it( 'uses line shape for line chart type', () => {
+			renderLegendWithChartType( 'line' );
+			expect( screen.getByRole( 'list' ) ).toBeInTheDocument();
+			expect( screen.getAllByTestId( 'legend-item' ) ).toHaveLength( 2 );
+
+			const html = document.body.innerHTML;
+			expect( html ).toContain( '<line' );
+		} );
+
+		it( 'uses rect shape for bar chart type', () => {
+			renderLegendWithChartType( 'bar' );
+			expect( screen.getByRole( 'list' ) ).toBeInTheDocument();
+
+			// visx ShapeRect renders a <div> with inline background style inside
+			// .visx-legend-shape. No testids or roles on these elements, so direct
+			// node access is necessary.
+			// eslint-disable-next-line testing-library/no-node-access
+			const shapes = document.querySelectorAll( '.visx-legend-shape > div' );
+			expect( shapes ).toHaveLength( 2 );
+			shapes.forEach( shape => {
+				expect( ( shape as HTMLElement ).style.background ).toBeTruthy();
+			} );
+		} );
+
+		it( 'uses circle shape for pie chart type', () => {
+			renderLegendWithChartType( 'pie' );
+			expect( screen.getByRole( 'list' ) ).toBeInTheDocument();
+
+			const html = document.body.innerHTML;
+			expect( html ).toContain( '<circle' );
+			expect( html ).not.toContain( '<line' );
+		} );
+
+		it( 'allows explicit shape to override chart type default', () => {
+			renderLegendWithChartType( 'line', CustomShape );
+			expect( screen.getByRole( 'list' ) ).toBeInTheDocument();
+			expect( screen.getAllByTestId( 'custom-shape' ) ).toHaveLength( 2 );
+
+			const html = document.body.innerHTML;
+			expect( html ).not.toContain( '<line' );
+		} );
+	} );
+
 	describe( 'Interactive legend', () => {
 		it( 'renders interactive legend items with proper attributes', () => {
 			render(

package/src/components/legend/types.ts

@@ -1,4 +1,10 @@
 import { LegendOrdinal } from '@visx/legend';
+import type {
+	LegendItemStyles,
+	LegendLabelStyles,
+	LegendPosition,
+	LegendShapeStyles,
+} from '../../types';
 import type { GlyphProps, LineStyles } from '@visx/xychart';
 import type { ComponentProps, CSSProperties, ReactNode } from 'react';
 
@@ -7,43 +13,10 @@ type VisxLegendProps = Pick<
 	'className' | 'shape' | 'fill' | 'size' | 'labelFormat' | 'labelTransform'
 >;
 
-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 label text as a CSS value (e.g. '200px', '50%', '10rem').
-	 * When set, text overflow behavior is controlled by textOverflow.
-	 */
-	maxWidth?: string;
-	/**
-	 * Controls how text behaves when it exceeds maxWidth.
-	 * - 'ellipsis': Truncate with ellipsis (ideal for widgets/small devices)
-	 * - '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';
-	/**
-	 * TODO: Add 'left' | 'right' positioning support in future implementation
-	 */
-	position?: 'top' | 'bottom';
+	position?: LegendPosition;
 	alignment?: 'start' | 'center' | 'end';
 	/** Additional CSS class name for legend items. */
 	itemClassName?: string;

package/src/hooks/index.ts

@@ -4,9 +4,9 @@ export { useXYChartTheme } from './use-xychart-theme';
 export { useChartDataTransform } from './use-chart-data-transform';
 export { useChartMargin } from './use-chart-margin';
 export { useElementSize } from './use-element-size';
-export { useHasLegendChild } from './use-has-legend-child';
 export { useTextTruncation } from './use-text-truncation';
 export { useZeroValueDisplay } from './use-zero-value-display';
+export { useDataWithPercentages } from './use-data-with-percentages';
 export { useInteractiveLegendData } from './use-interactive-legend-data';
 export { usePrefersReducedMotion } from './use-prefers-reduced-motion';
 export { useTooltipPortalRelocator } from './use-tooltip-portal-relocator';

package/src/hooks/use-data-with-percentages.ts

@@ -0,0 +1,24 @@
+import { useMemo } from 'react';
+
+interface DataPointWithValue {
+	value: number;
+}
+
+/**
+ * Hook to calculate percentages from values for chart data.
+ * Ensures percentages are always derived from values (single source of truth).
+ *
+ * @param data - Array of data points with values
+ * @return Data with calculated percentages
+ */
+export const useDataWithPercentages = < T extends DataPointWithValue >(
+	data: T[]
+): ( T & { percentage: number } )[] => {
+	return useMemo( () => {
+		const totalValue = data.reduce( ( sum, segment ) => sum + segment.value, 0 );
+		return data.map( segment => ( {
+			...segment,
+			percentage: totalValue > 0 ? ( segment.value / totalValue ) * 100 : 0,
+		} ) );
+	}, [ data ] );
+};

package/src/hooks/use-interactive-legend-data.ts

@@ -2,7 +2,8 @@ import { useMemo } from 'react';
 
 /**
  * Data point interface for charts with interactive legends.
- * Requires label for series identification, value for calculations, and percentage for display.
+ * Requires label for series identification, value for calculations,
+ * and percentage (should be pre-calculated by the chart component).
  */
 interface DataPointWithPercentage {
 	label: string;
@@ -14,7 +15,7 @@ interface DataPointWithPercentage {
  * Parameters for the useInteractiveLegendData hook.
  */
 interface UseInteractiveLegendDataParams< T extends DataPointWithPercentage > {
-	/** The chart data to filter based on legend visibility */
+	/** The chart data with pre-calculated percentages */
 	data: T[];
 	/** Unique chart identifier, required for interactive legends */
 	chartId: string | undefined;
@@ -33,9 +34,9 @@ interface UseInteractiveLegendDataResult< T extends DataPointWithPercentage > {
 	/** Boolean indicating if all segments are hidden */
 	allSegmentsHidden: boolean;
 	/**
-	 * Legend data with recalculated percentages for visible items.
-	 * Uses original data for hidden items, but shows recalculated percentages for visible ones.
-	 * This ensures the legend displays accurate percentages while maintaining all entries.
+	 * Legend data with stable percentage formatting.
+	 * Hidden items keep their original percentage.
+	 * Visible items show recalculated percentages that total 100%.
 	 */
 	legendData: T[];
 }
@@ -85,8 +86,9 @@ export const useInteractiveLegendData = < T extends DataPointWithPercentage >( {
 	isSeriesVisible,
 }: UseInteractiveLegendDataParams< T > ): UseInteractiveLegendDataResult< T > => {
 	// Filter and recalculate data for interactive legends
+	// Note: data should already have percentages calculated by the chart component
 	const visibleData = useMemo( () => {
-		// If interactive mode is disabled or no chartId, return all data unchanged
+		// If interactive mode is disabled or no chartId, return data as-is
 		if ( ! chartId || ! legendInteractive ) {
 			return data;
 		}
@@ -99,9 +101,8 @@ export const useInteractiveLegendData = < T extends DataPointWithPercentage >( {
 			return [];
 		}
 
-		// Recalculate percentages so visible segments total 100%
+		// Recalculate percentages from values so visible segments total 100%
 		const totalValue = filtered.reduce( ( sum, segment ) => sum + segment.value, 0 );
-
 		return filtered.map( segment => ( {
 			...segment,
 			percentage: totalValue > 0 ? ( segment.value / totalValue ) * 100 : 0,
@@ -113,24 +114,26 @@ export const useInteractiveLegendData = < T extends DataPointWithPercentage >( {
 		return legendInteractive && visibleData.length === 0;
 	}, [ legendInteractive, visibleData ] );
 
-	// Prepare legend data with recalculated percentages for visible items
-	// This maintains all legend entries but shows updated percentages for visible segments
+	// Prepare legend data with percentages
+	// Hidden items keep their original percentage (calculated from all values)
+	// Visible items show recalculated percentages (totaling 100%)
 	const legendData = useMemo( () => {
 		if ( ! legendInteractive || ! chartId ) {
 			return data;
 		}
 
-		// Map original data to show recalculated percentages for visible items
+		// Build a Map for O(1) lookups instead of O(n) find() calls
+		const visibleDataMap = new Map( visibleData.map( d => [ d.label, d ] ) );
+
 		return data.map( segment => {
 			const isVisible = isSeriesVisible( chartId, segment.label );
 			if ( ! isVisible ) {
-				// Return original data for hidden items
+				// Hidden items keep original percentage
 				return segment;
 			}
 
-			// For visible items, find the recalculated percentage from visibleData
-			const recalculated = visibleData.find( d => d.label === segment.label );
-			return recalculated || segment;
+			// For visible items, get the recalculated percentage from visibleData
+			return visibleDataMap.get( segment.label ) || segment;
 		} );
 	}, [ data, visibleData, legendInteractive, chartId, isSeriesVisible ] );