@automattic/charts 0.56.7 → 0.57.0

package/src/hooks/test/use-zero-value-display.test.tsx

@@ -0,0 +1,206 @@
+import { renderHook } from '@testing-library/react';
+import { useZeroValueDisplay } from '../use-zero-value-display';
+import type { SeriesData } from '../../types';
+
+describe( 'useZeroValueDisplay', () => {
+	const mockData: SeriesData[] = [
+		{
+			label: 'Series 1',
+			data: [
+				{ label: 'A', value: 0 },
+				{ label: 'B', value: 100 },
+				{ label: 'C', value: 200 },
+			],
+		},
+	];
+
+	test( 'returns original data when disabled', () => {
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( mockData, { enabled: false, valueAxisLength: 100 } )
+		);
+		expect( result.current ).toBe( mockData );
+	} );
+
+	test( 'returns original data when valueAxisLength is not provided', () => {
+		const { result } = renderHook( () => useZeroValueDisplay( mockData, { enabled: true } ) );
+		expect( result.current ).toBe( mockData );
+	} );
+
+	test( 'adds visualValue for zero values', () => {
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( mockData, { enabled: true, valueAxisLength: 100 } )
+		);
+
+		const enhancedData = result.current;
+		expect( enhancedData[ 0 ].data[ 0 ] ).toHaveProperty( 'visualValue' );
+		expect(
+			( enhancedData[ 0 ].data[ 0 ] as { visualValue?: number } ).visualValue
+		).toBeGreaterThan( 0 );
+	} );
+
+	test( 'adds visualValue for near-zero values that would render below minimum', () => {
+		const data: SeriesData[] = [
+			{
+				label: 'Series 1',
+				data: [
+					{ label: 'A', value: 1 }, // Would render as 1px (below 3px minimum)
+					{ label: 'B', value: 100 },
+				],
+			},
+		];
+
+		// With axis=100 and max=100, 3px threshold = 3
+		// Value of 1 < 3, so it gets boosted to 3
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( data, { enabled: true, valueAxisLength: 100 } )
+		);
+
+		const enhancedData = result.current;
+		expect( enhancedData[ 0 ].data[ 0 ] ).toHaveProperty( 'visualValue' );
+		expect( ( enhancedData[ 0 ].data[ 0 ] as { visualValue?: number } ).visualValue ).toBe( 3 );
+	} );
+
+	test( 'does not add visualValue for values above minimum threshold', () => {
+		const data: SeriesData[] = [
+			{
+				label: 'Series 1',
+				data: [
+					{ label: 'A', value: 10 }, // Would render as 10px (above 3px minimum)
+					{ label: 'B', value: 100 },
+				],
+			},
+		];
+
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( data, { enabled: true, valueAxisLength: 100 } )
+		);
+
+		const enhancedData = result.current;
+		expect( enhancedData[ 0 ].data[ 0 ] ).not.toHaveProperty( 'visualValue' );
+		expect( enhancedData[ 0 ].data[ 1 ] ).not.toHaveProperty( 'visualValue' );
+	} );
+
+	test( 'zero values get 2px equivalent (1px less than near-zero)', () => {
+		// mockData has values [0, 100, 200], max = 200
+		// zeroVisualValue = (2 / 100) * 200 = 4
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( mockData, { enabled: true, valueAxisLength: 100 } )
+		);
+
+		const visualValue = ( result.current[ 0 ].data[ 0 ] as { visualValue?: number } ).visualValue;
+		expect( visualValue ).toBe( 4 ); // 2px equivalent
+	} );
+
+	test( 'near-zero values get 3px equivalent', () => {
+		const data: SeriesData[] = [
+			{
+				label: 'Series 1',
+				data: [
+					{ label: 'A', value: 1 }, // Would render as 1px
+					{ label: 'B', value: 100 },
+				],
+			},
+		];
+
+		// minNonZeroValue = (3 / 100) * 100 = 3
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( data, { enabled: true, valueAxisLength: 100 } )
+		);
+
+		const visualValue = ( result.current[ 0 ].data[ 0 ] as { visualValue?: number } ).visualValue;
+		expect( visualValue ).toBe( 3 ); // 3px equivalent
+	} );
+
+	test( 'zeros and near-zeros have 1px visual difference', () => {
+		const data: SeriesData[] = [
+			{
+				label: 'Series 1',
+				data: [
+					{ label: 'Zero', value: 0 },
+					{ label: 'NearZero', value: 1 },
+					{ label: 'Max', value: 100 },
+				],
+			},
+		];
+
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( data, { enabled: true, valueAxisLength: 100 } )
+		);
+
+		const zeroVisual = ( result.current[ 0 ].data[ 0 ] as { visualValue?: number } ).visualValue;
+		const nearZeroVisual = ( result.current[ 0 ].data[ 1 ] as { visualValue?: number } )
+			.visualValue;
+
+		// Zero = 2px equivalent (2), near-zero = 3px equivalent (3)
+		expect( zeroVisual ).toBe( 2 );
+		expect( nearZeroVisual ).toBe( 3 );
+		expect( nearZeroVisual! - zeroVisual! ).toBe( 1 ); // 1px difference
+	} );
+
+	test( 'handles data with only zero values', () => {
+		const zeroOnlyData: SeriesData[] = [
+			{
+				label: 'Series 1',
+				data: [
+					{ label: 'A', value: 0 },
+					{ label: 'B', value: 0 },
+				],
+			},
+		];
+
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( zeroOnlyData, { enabled: true, valueAxisLength: 100 } )
+		);
+
+		// Should return original data since there are no non-zero values to calculate from
+		expect( result.current ).toBe( zeroOnlyData );
+	} );
+
+	test( 'negative near-zero values preserve sign when boosted', () => {
+		const data: SeriesData[] = [
+			{
+				label: 'Series 1',
+				data: [
+					{ label: 'NegativeNearZero', value: -1 }, // Would render as 1px (below 3px minimum)
+					{ label: 'NegativeLarge', value: -100 },
+					{ label: 'PositiveMax', value: 100 },
+				],
+			},
+		];
+
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( data, { enabled: true, valueAxisLength: 100 } )
+		);
+
+		const negativeNearZero = result.current[ 0 ].data[ 0 ] as { visualValue?: number };
+
+		// Should have a boosted magnitude but keep the negative sign
+		expect( negativeNearZero.visualValue ).toBeLessThan( 0 );
+		expect( Math.abs( negativeNearZero.visualValue! ) ).toBeGreaterThan( 1 );
+	} );
+
+	test( 'null values remain untouched without visualValue', () => {
+		const data: SeriesData[] = [
+			{
+				label: 'Series 1',
+				data: [
+					{ label: 'NullValue', value: null },
+					{ label: 'NonZero', value: 50 },
+				],
+			},
+		];
+
+		const { result } = renderHook( () =>
+			useZeroValueDisplay( data, { enabled: true, valueAxisLength: 100 } )
+		);
+
+		const nullPoint = result.current[ 0 ].data[ 0 ] as {
+			value: number | null;
+			visualValue?: number;
+		};
+
+		// The original null value should be preserved and no visualValue should be added
+		expect( nullPoint.value ).toBeNull();
+		expect( nullPoint ).not.toHaveProperty( 'visualValue' );
+	} );
+} );

package/src/hooks/use-zero-value-display.ts

@@ -11,57 +11,86 @@ export interface EnhancedSeriesData extends Omit< SeriesData, 'data' > {
 
 export interface UseZeroValueDisplayOptions {
 	enabled: boolean;
-	minValueRatio?: number;
-	maxValueRatio?: number;
+	/**
+	 * The pixel length of the value axis (height for vertical charts, width for
+	 * horizontal charts). Used to calculate a minimum visible value that ensures
+	 * zero-value bars are at least MIN_PIXEL_HEIGHT pixels tall along that axis.
+	 */
+	valueAxisLength?: number;
 }
 
+/**
+ * Minimum pixel size for near-zero bars (non-zero values that would render too small).
+ * Using 3px to be visible but not misleading - larger values might look like actual data.
+ */
+const MIN_PIXEL_SIZE = 3;
+
+/**
+ * Pixel size for zero-value bars (1px less than near-zero to be visually distinguishable).
+ */
+const ZERO_PIXEL_SIZE = MIN_PIXEL_SIZE - 1;
+
 export const useZeroValueDisplay = (
 	data: SeriesData[],
 	options: UseZeroValueDisplayOptions = { enabled: false }
 ): SeriesData[] | EnhancedSeriesData[] => {
-	const { enabled, minValueRatio = 0.6, maxValueRatio = 0.008 } = options;
+	const { enabled, valueAxisLength } = options;
 
 	return useMemo( () => {
-		if ( ! enabled ) return data;
-
-		// Collect all non-zero, non-null values (both positive and negative)
-		const nonZeroValues: number[] = [];
+		if ( ! enabled || ! valueAxisLength || valueAxisLength <= 0 ) return data;
 
+		// Find max absolute value
+		let maxAbsoluteValue = 0;
 		for ( const series of data ) {
 			for ( const point of series.data ) {
 				if ( point.value !== null && point.value !== 0 ) {
-					nonZeroValues.push( point.value );
+					maxAbsoluteValue = Math.max( maxAbsoluteValue, Math.abs( point.value ) );
 				}
 			}
 		}
 
-		if ( nonZeroValues.length === 0 ) return data;
-
-		// Convert to absolute values to find the range
-		const absoluteValues = nonZeroValues.map( Math.abs );
+		if ( maxAbsoluteValue === 0 ) return data;
 
-		// Calculate min and max based on absolute values
-		const minAbsoluteValue = Math.min( ...absoluteValues );
-		const maxAbsoluteValue = Math.max( ...absoluteValues );
-
-		// Calculate minimum visible value using absolute range
-		const minVisibleValue = Math.min(
-			minAbsoluteValue * minValueRatio,
-			maxAbsoluteValue * maxValueRatio
+		// Calculate values that render as specific pixel sizes, clamped to maxAbsoluteValue
+		// to prevent visual distortion when valueAxisLength is very small
+		const minNonZeroValue = Math.min(
+			( MIN_PIXEL_SIZE / valueAxisLength ) * maxAbsoluteValue,
+			maxAbsoluteValue
+		);
+		const zeroVisualValue = Math.min(
+			( ZERO_PIXEL_SIZE / valueAxisLength ) * maxAbsoluteValue,
+			maxAbsoluteValue
 		);
 
 		return data.map( series => ( {
 			...series,
-			data: series.data.map( ( point ): EnhancedDataPoint => {
+			data: series.data.map( ( point: DataPointDate ): EnhancedDataPoint => {
+				// Zero values get a smaller visual representation (2px)
 				if ( point.value === 0 ) {
 					return {
 						...point,
-						visualValue: minVisibleValue,
+						visualValue: zeroVisualValue,
+					};
+				}
+
+				// Null values should remain untouched
+				if ( point.value === null ) {
+					return point;
+				}
+
+				const absValue = Math.abs( point.value );
+
+				// Near-zero values that would render below MIN_PIXEL_SIZE get boosted to 3px
+				// Preserve the sign for negative values
+				if ( absValue < minNonZeroValue ) {
+					return {
+						...point,
+						visualValue: Math.sign( point.value ) * minNonZeroValue,
 					};
 				}
 
 				return point;
 			} ),
 		} ) );
-	}, [ data, enabled, minValueRatio, maxValueRatio ] );
+	}, [ data, enabled, valueAxisLength ] );
 };

package/src/index.ts

@@ -37,7 +37,13 @@ export type {
 	PieSemiCircleChartRenderTooltipParams,
 } from './charts/pie-semi-circle-chart';
 export type { GeoChartProps, GeoRegion, GeoResolution } from './charts/geo-chart';
-export type { LegendValueDisplay, BaseLegendItem } from './components/legend';
+export type {
+	LegendValueDisplay,
+	BaseLegendItem,
+	LegendItemStyles,
+	LegendLabelStyles,
+	LegendShapeStyles,
+} from './components/legend';
 export type { TrendIndicatorProps, TrendDirection } from './components/trend-indicator';
 export type { LineStyles, GridStyles, EventHandlerParams } from '@visx/xychart';
 export type {

package/src/providers/chart-context/test/chart-context.test.tsx

@@ -987,10 +987,12 @@ describe( 'ChartContext', () => {
 
 			const extendedTheme = {
 				...mockTheme,
-				legendShapeStyles: [
-					{ fill: '#LEGEND1', stroke: '#BORDER1' },
-					{ fill: '#LEGEND2', strokeWidth: 3 },
-				],
+				legend: {
+					shapeStyles: [
+						{ fill: '#LEGEND1', stroke: '#BORDER1' },
+						{ fill: '#LEGEND2', strokeWidth: 3 },
+					],
+				},
 			};
 
 			render(
@@ -1087,7 +1089,9 @@ describe( 'ChartContext', () => {
 						},
 					},
 				},
-				legendShapeStyles: [ { fill: '#LEGEND1', stroke: '#BORDER1' } ],
+				legend: {
+					shapeStyles: [ { fill: '#LEGEND1', stroke: '#BORDER1' } ],
+				},
 			};
 
 			render(
@@ -1234,7 +1238,9 @@ describe( 'ChartContext', () => {
 				...mockTheme,
 				glyphs: [ mockGlyph ],
 				seriesLineStyles: [ { strokeWidth: 2 } ],
-				legendShapeStyles: [ { fill: '#SHAPE1' } ],
+				legend: {
+					shapeStyles: [ { fill: '#SHAPE1' } ],
+				},
 			};
 
 			render(

package/src/providers/chart-context/themes.ts

@@ -17,12 +17,14 @@ const defaultTheme: CompleteChartTheme = {
 	gridColorDark: '',
 	xTickLineStyles: { stroke: 'black' },
 	xAxisLineStyles: { stroke: '#DCDCDE', strokeWidth: 1 },
-	legendLabelStyles: {
-		color: 'var(--jp-gray-80, #2c3338)',
+	legend: {
+		labelStyles: {
+			color: 'var(--jp-gray-80, #2c3338)',
+		},
+		containerStyles: {},
+		shapeStyles: [],
 	},
-	legendContainerStyles: {},
 	seriesLineStyles: [],
-	legendShapeStyles: [],
 	glyphs: [],
 	svgLabelSmall: { fill: 'var(--jp-gray-80, #2c3338)' },
 	annotationStyles: {

package/src/types.ts

@@ -210,14 +210,17 @@ export type ChartTheme = {
 	xAxisLineStyles?: LineStyles;
 	/** Styles for series lines */
 	seriesLineStyles?: LineStyles[];
-	/** Styles for legend shapes */
-	legendShapeStyles?: Record< string, unknown >[];
 	/** Array of render functions for glyphs */
 	glyphs?: Array< < Datum extends object >( props: GlyphProps< Datum > ) => ReactNode >;
-	/** Styles for legend labels */
-	legendLabelStyles?: CSSProperties;
-	/** Styles for legend container */
-	legendContainerStyles?: CSSProperties;
+	/** Legend specific settings */
+	legend?: {
+		/** Styles for legend shapes */
+		shapeStyles?: Record< string, unknown >[];
+		/** Styles for legend labels */
+		labelStyles?: CSSProperties;
+		/** Styles for legend container */
+		containerStyles?: CSSProperties;
+	};
 	/** Styles for small SVG text (eg. axis tick labels), passed through to the XYChart theme. */
 	svgLabelSmall?: TextProps;
 	annotationStyles?: AnnotationStyles;
@@ -287,6 +290,7 @@ export type CompleteChartTheme = Required< ChartTheme > & {
 	lineChart: {
 		lineStyles: Record< NonNullable< SeriesDataOptions[ 'type' ] >, LineStyles >;
 	};
+	legend: Required< NonNullable< ChartTheme[ 'legend' ] > >;
 	sparkline: Required< NonNullable< ChartTheme[ 'sparkline' ] > > & {
 		margin: Required< NonNullable< ChartTheme[ 'sparkline' ] >[ 'margin' ] >;
 	};
@@ -446,7 +450,7 @@ export type BaseChartProps< T = DataPoint | DataPointDate | LeaderboardEntry > =
 	legendItemClassName?: string;
 	/**
 	 * Enable interactive legend items that can toggle series visibility.
-	 * Supported for LineChart, PieChart, and PieSemiCircleChart.
+	 * Supported for all chart types that render series.
 	 * Requires chartId and GlobalChartsProvider.
 	 * For pie charts, percentages are recalculated so visible segments total 100%.
 	 */

package/src/utils/get-styles.ts

@@ -62,7 +62,7 @@ export function getItemShapeStyles(
 ): Record< string, unknown > {
 	const seriesShapeStyles = series.options?.legendShapeStyle ?? {};
 	const lineStyles = legendShape === 'line' ? getSeriesLineStyles( series, index, theme ) : {};
-	const themeShapeStyles = theme.legendShapeStyles?.[ index ];
+	const themeShapeStyles = theme.legend?.shapeStyles?.[ index ];
 
 	const itemShapeStyles = {
 		...seriesShapeStyles,

package/src/utils/test/get-styles.test.ts

@@ -20,10 +20,12 @@ describe( 'Series styling utility functions', () => {
 			},
 		},
 		seriesLineStyles: [ { strokeWidth: 2 }, { strokeWidth: 3, strokeDasharray: '2 2' } ],
-		legendShapeStyles: [
-			{ fill: '#LEGEND1', stroke: '#BORDER1' },
-			{ fill: '#LEGEND2', strokeWidth: 3 },
-		],
+		legend: {
+			shapeStyles: [
+				{ fill: '#LEGEND1', stroke: '#BORDER1' },
+				{ fill: '#LEGEND2', strokeWidth: 3 },
+			],
+		},
 	};
 
 	describe( 'getSeriesStroke', () => {
@@ -152,7 +154,7 @@ describe( 'Series styling utility functions', () => {
 			};
 
 			const result = getItemShapeStyles( comparisonSeries, 0, mockTheme as ChartTheme, 'rect' );
-			expect( result ).toEqual( mockTheme.legendShapeStyles[ 0 ] );
+			expect( result ).toEqual( mockTheme.legend.shapeStyles[ 0 ] );
 		} );
 
 		it( 'merges custom shape styles with line styles for line shape', () => {
@@ -186,13 +188,13 @@ describe( 'Series styling utility functions', () => {
 				mockTheme as ChartTheme,
 				'rect'
 			);
-			expect( result ).toEqual( mockTheme.legendShapeStyles[ 1 ] );
+			expect( result ).toEqual( mockTheme.legend.shapeStyles[ 1 ] );
 		} );
 
 		it( 'returns empty object when no theme shape styles and no meaningful custom styles', () => {
 			const themeWithoutShapeStyles = {
 				...mockTheme,
-				legendShapeStyles: undefined,
+				legend: { shapeStyles: undefined },
 			} as ChartTheme;
 
 			const result = getItemShapeStyles( mockSeriesData, 0, themeWithoutShapeStyles, 'rect' );
@@ -254,7 +256,7 @@ describe( 'Series styling utility functions', () => {
 
 		it( 'works without legendShape parameter', () => {
 			const result = getItemShapeStyles( mockSeriesData, 0, mockTheme as ChartTheme );
-			expect( result ).toEqual( mockTheme.legendShapeStyles[ 0 ] );
+			expect( result ).toEqual( mockTheme.legend.shapeStyles[ 0 ] );
 		} );
 
 		it( 'handles other legendShape string values like "circle"', () => {
@@ -265,7 +267,7 @@ describe( 'Series styling utility functions', () => {
 
 			const result = getItemShapeStyles( comparisonSeries, 0, mockTheme as ChartTheme, 'circle' );
 			// Should not include line styles for circle shape
-			expect( result ).toEqual( mockTheme.legendShapeStyles[ 0 ] );
+			expect( result ).toEqual( mockTheme.legend.shapeStyles[ 0 ] );
 		} );
 
 		it( 'handles React component as legendShape parameter', () => {
@@ -282,7 +284,7 @@ describe( 'Series styling utility functions', () => {
 				CustomShape
 			);
 			// Should not include line styles for component shape
-			expect( result ).toEqual( mockTheme.legendShapeStyles[ 0 ] );
+			expect( result ).toEqual( mockTheme.legend.shapeStyles[ 0 ] );
 		} );
 
 		it( 'prioritizes series line styles over theme line styles when legendShape is line', () => {