@automattic/charts 4.2.0 → 4.4.0

package/src/charts/bar-chart/private/classified-bar-series.tsx

@@ -0,0 +1,85 @@
+import { DataContext, GlyphSeries } from '@visx/xychart';
+import clsx from 'clsx';
+import { useCallback, useContext, useMemo } from 'react';
+import { createGroupScale } from './band-scale';
+import { getValueScaleBaseline } from './comparison-bars-geometry';
+import type { BandScale } from './band-scale';
+import type { DataPointDate } from '../../../types';
+import type { BarChartProps } from '../types';
+import type { AxisScale } from '@visx/axis';
+import type { GlyphProps, SeriesProps } from '@visx/xychart';
+
+type Props = Pick<
+	SeriesProps< AxisScale, AxisScale, DataPointDate >,
+	'xAccessor' | 'yAccessor'
+> & {
+	dataKey: string;
+	data: DataPointDate[];
+	colorAccessor: ( datum: DataPointDate ) => string;
+	barClassName: NonNullable< BarChartProps[ 'barClassName' ] >;
+	primaryKeys: string[];
+	groupPadding: number;
+};
+
+const ClassifiedBarSeries = ( { barClassName, primaryKeys, groupPadding, ...props }: Props ) => {
+	const { xScale, yScale, horizontal } = useContext( DataContext );
+	const bandScale = ( horizontal ? yScale : xScale ) as BandScale | undefined;
+	const valueScale = horizontal ? xScale : yScale;
+	const groupScale = useMemo(
+		() => createGroupScale( primaryKeys, bandScale?.bandwidth?.() ?? 0, groupPadding ),
+		[ primaryKeys, bandScale, groupPadding ]
+	);
+	const renderGlyph = useCallback(
+		( {
+			datum,
+			x,
+			y,
+			color,
+			onBlur,
+			onFocus,
+			onPointerMove,
+			onPointerOut,
+			onPointerUp,
+		}: GlyphProps< DataPointDate > ) => {
+			if ( ! bandScale?.bandwidth || ! valueScale ) return null;
+			const baseline = getValueScaleBaseline(
+				valueScale as Parameters< typeof getValueScaleBaseline >[ 0 ]
+			);
+			const position =
+				Number( bandScale( ( horizontal ? props.yAccessor : props.xAccessor )( datum ) ) ) +
+				( groupScale( props.dataKey ) ?? 0 );
+			const value = horizontal ? x : y;
+			return (
+				<rect
+					className={ clsx( 'visx-bar', barClassName( datum ) ) }
+					// visx's own Bars makes a bar focusable on the same condition.
+					tabIndex={ onFocus || onBlur ? 0 : undefined }
+					onBlur={ onBlur }
+					onFocus={ onFocus }
+					onPointerMove={ onPointerMove }
+					onPointerOut={ onPointerOut }
+					onPointerUp={ onPointerUp }
+					// Same arithmetic as visx BaseBarGroup, so rounding matches the unclassified bars.
+					x={ horizontal ? baseline + Math.min( 0, value - baseline ) : position }
+					y={ horizontal ? position : baseline + Math.min( 0, value - baseline ) }
+					width={ horizontal ? Math.abs( value - baseline ) : groupScale.bandwidth() }
+					height={ horizontal ? groupScale.bandwidth() : Math.abs( value - baseline ) }
+					fill={ color }
+				/>
+			);
+		},
+		[
+			bandScale,
+			valueScale,
+			horizontal,
+			groupScale,
+			props.dataKey,
+			props.xAccessor,
+			props.yAccessor,
+			barClassName,
+		]
+	);
+	return <GlyphSeries { ...props } renderGlyph={ renderGlyph } />;
+};
+
+export default ClassifiedBarSeries;

package/src/charts/bar-chart/private/comparison-bars-geometry.ts

@@ -3,9 +3,8 @@ export type ComparisonRect = { x: number; y: number; width: number; height: numb
 type ValueScale = ( ( v: number ) => number ) & { range: () => unknown[] };
 
 /**
- * Output position of a value scale's baseline: zero if in-domain, else the
- * nearest range edge. Mirrors visx's getScaleBaseline so comparison shadows
- * sit on the same baseline as primary bars.
+ * Mirrors visx's getScaleBaseline so comparison shadows and primary bars
+ * share the same baseline, including out-of-domain zero values.
  *
  * @param {ValueScale} scale - The continuous value scale.
  * @return {number} The baseline output position in pixels.
@@ -20,9 +19,7 @@ export function getValueScaleBaseline( scale: ValueScale ): number {
 			? Math.min( Math.max( minOutput, maybeZero ), maxOutput )
 			: maxOutput;
 	}
-	return Number.isFinite( maybeZero )
-		? Math.min( Math.max( maybeZero, minOutput ), maxOutput )
-		: minOutput;
+	return Number.isFinite( maybeZero ) ? Math.max( maybeZero, minOutput ) : minOutput;
 }
 
 /**

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

@@ -1,5 +1,6 @@
 export { useBarChartOptions } from './use-bar-chart-options';
 export { TruncatedXTickComponent, TruncatedYTickComponent } from './truncated-tick-component';
+export { default as ClassifiedBarSeries } from './classified-bar-series';
 export { ComparisonBars } from './comparison-bars';
 export type { ComparisonSeriesEntry } from './comparison-bars';
 export {
@@ -9,5 +10,6 @@ export {
 	COMPARISON_TICK_GAP_FACTOR,
 } from './comparison-constants';
 export { BASE_BAND_PADDING_INNER } from './use-bar-chart-options';
+export { countRenderedBars, isBarRendered } from './value-domain';
 export { BandHighlight } from './band-highlight';
 export { BandTooltip } from './band-tooltip';

package/src/charts/bar-chart/private/test/band-highlight.test.tsx

@@ -7,7 +7,7 @@ import { GlobalChartsProvider } from '../../../../providers';
 import { CATALOG_POINTERS } from '../../../../providers/chart-context/private/catalog-pointers';
 import { BarChartUnresponsive } from '../../bar-chart';
 import { BandHighlight } from '../band-highlight';
-import type { BandHighlightSelection } from '../../bar-chart';
+import type { BandHighlightSelection } from '../../types';
 
 const xScale = scaleBand( { domain: [ 'Jan', 'Feb' ], range: [ 10, 210 ] } );
 const dataContext = {
@@ -25,7 +25,7 @@ const Fixture = ( { label = 'Jan', onChange } ) => {
 				value={
 					{
 						tooltipOpen: true,
-						tooltipData: { nearestDatum: { key: 'scores', datum: { label, value: 50 } } },
+						tooltipData: { nearestDatum: { key: 'scores', index: 0, datum: { label, value: 50 } } },
 					} as never
 				}
 			>
@@ -38,6 +38,20 @@ const Fixture = ( { label = 'Jan', onChange } ) => {
 };
 
 describe( 'BandHighlight', () => {
+	test( 'reports the initial selection and clears it on unmount', () => {
+		const onChange = jest.fn();
+		const { unmount } = render( <Fixture onChange={ onChange } /> );
+		expect( onChange ).toHaveBeenLastCalledWith(
+			expect.objectContaining( {
+				key: 'scores',
+				index: 0,
+				datum: { label: 'Jan', value: 50 },
+			} )
+		);
+		unmount();
+		expect( onChange ).toHaveBeenLastCalledWith( null );
+	} );
+
 	test( 'uses the catalog surface fill', () => {
 		render( <Fixture onChange={ undefined } /> );
 		expect( screen.getByTestId( 'bar-chart-band-highlight' ) ).toHaveAttribute(
@@ -79,6 +93,7 @@ describe( 'BandHighlight', () => {
 	test.each( [ { withTooltips: false }, { data: [] } ] )(
 		'clears the selected band when the highlight unmounts with %j',
 		async props => {
+			const warn = jest.spyOn( console, 'warn' ).mockImplementation( () => {} );
 			const user = userEvent.setup();
 			const onChange = jest.fn();
 			const chartProps = {
@@ -103,6 +118,17 @@ describe( 'BandHighlight', () => {
 					<BarChartUnresponsive { ...chartProps } { ...props } />
 				</GlobalChartsProvider>
 			);
+			rerender(
+				<GlobalChartsProvider>
+					<BarChartUnresponsive
+						{ ...chartProps }
+						{ ...props }
+						onBandHighlightChange={ jest.fn() }
+					/>
+				</GlobalChartsProvider>
+			);
+			expect( warn ).toHaveBeenCalledTimes( 'withTooltips' in props ? 1 : 0 );
+			warn.mockRestore();
 			expect( onChange ).toHaveBeenLastCalledWith( null );
 		}
 	);

package/src/charts/bar-chart/private/test/comparison-bars-geometry.test.ts

@@ -9,12 +9,11 @@ describe( 'getValueScaleBaseline', () => {
 		expect( getValueScaleBaseline( scale ) ).toBe( 200 );
 	} );
 
-	it( 'clamps to the end (range max) when 0 is outside an ascending range scale', () => {
+	it( 'preserves an out-of-range zero baseline for an ascending scale', () => {
 		// horizontal linear scale: range [0, 200], domain [-100, -10] (zero excluded)
 		const scale = ( ( v: number ) => ( ( v + 100 ) / 90 ) * 200 ) as never;
 		( scale as { range: () => number[] } ).range = () => [ 0, 200 ];
-		// scale(0) = (100/90)*200 ≈ 222 -> clamped to 200
-		expect( getValueScaleBaseline( scale ) ).toBe( 200 );
+		expect( getValueScaleBaseline( scale ) ).toBeCloseTo( 222.222222 );
 	} );
 } );
 

package/src/charts/bar-chart/private/test/value-domain.test.ts

@@ -0,0 +1,100 @@
+import { getValueScaleDomain } from '../value-domain';
+import type { DataPointDate, SeriesData } from '../../../../types';
+
+const series = (
+	values: Array< number | null >,
+	options?: SeriesData[ 'options' ],
+	label = 'Series'
+): SeriesData => ( {
+	label,
+	data: values.map( ( value, index ) => ( {
+		date: new Date( 2026, index, 1 ),
+		value,
+	} ) ),
+	options,
+} );
+
+const allRendered = () => true;
+
+describe( 'getValueScaleDomain', () => {
+	test( 'anchors a varying series at zero', () => {
+		expect( getValueScaleDomain( [ series( [ 10, 20, 30 ] ) ], true, allRendered ) ).toEqual( [
+			0, 30,
+		] );
+	} );
+
+	test( 'spans zero for a varying negative series', () => {
+		expect( getValueScaleDomain( [ series( [ -10, -20 ] ) ], true, allRendered ) ).toEqual( [
+			-20, 0,
+		] );
+	} );
+
+	test( 'leaves a varying series to visx when zero is opted out', () => {
+		expect( getValueScaleDomain( [ series( [ 10, 20, 30 ] ) ], false, allRendered ) ).toBeNull();
+	} );
+
+	test( 'anchors a flat series at zero so its bars have height', () => {
+		expect( getValueScaleDomain( [ series( [ 500, 500, 500 ] ) ], false, allRendered ) ).toEqual( [
+			0, 500,
+		] );
+	} );
+
+	test( 'anchors a single-bucket window at zero', () => {
+		expect( getValueScaleDomain( [ series( [ 42 ] ) ], false, allRendered ) ).toEqual( [ 0, 42 ] );
+	} );
+
+	test( 'spans zero for a flat negative series', () => {
+		expect( getValueScaleDomain( [ series( [ -5, -5 ] ) ], false, allRendered ) ).toEqual( [
+			-5, 0,
+		] );
+	} );
+
+	test( 'falls back to a unit domain when every value is zero', () => {
+		expect( getValueScaleDomain( [ series( [ 0, 0 ] ) ], false, allRendered ) ).toEqual( [ 0, 1 ] );
+	} );
+
+	test( 'falls back to a unit domain when every value is zero in comparison mode', () => {
+		const data = [ series( [ 0, 0 ] ), series( [ 0, 0 ], { type: 'comparison' } ) ];
+		expect( getValueScaleDomain( data, true, allRendered ) ).toEqual( [ 0, 1 ] );
+	} );
+
+	test( 'falls back to a unit domain when no bucket has a reading', () => {
+		expect( getValueScaleDomain( [ series( [ null, null ] ) ], false, allRendered ) ).toEqual( [
+			0, 1,
+		] );
+	} );
+
+	test( 'ignores buckets with no reading when fitting a varying series', () => {
+		expect( getValueScaleDomain( [ series( [ null, 10, 20 ] ) ], false, allRendered ) ).toBeNull();
+	} );
+
+	test( 'keeps zero in the domain across every series in comparison mode', () => {
+		const data = [ series( [ 10, 20 ] ), series( [ 5, 40 ], { type: 'comparison' } ) ];
+		expect( getValueScaleDomain( data, true, allRendered ) ).toEqual( [ 0, 40 ] );
+	} );
+
+	test( 'anchors a flat series at zero when the varying series beside it is hidden', () => {
+		const data = [
+			series( [ 500, 500 ], undefined, 'Flat' ),
+			series( [ 10, 900 ], undefined, 'Varying' ),
+		];
+		const isSeriesRendered = ( s: SeriesData ) => s.label !== 'Varying';
+		expect( getValueScaleDomain( data, false, isSeriesRendered ) ).toEqual( [ 0, 500 ] );
+	} );
+
+	test( 'anchors the remaining varying series at zero when a sibling is hidden', () => {
+		const data = [ series( [ 10, 50 ], undefined, 'A' ), series( [ 15, 25 ], undefined, 'B' ) ];
+		const isSeriesRendered = ( s: SeriesData ) => s.label !== 'A';
+		expect( getValueScaleDomain( data, true, isSeriesRendered ) ).toEqual( [ 0, 25 ] );
+	} );
+
+	test( 'reads visualValue in preference to value', () => {
+		const data: SeriesData[] = [
+			{
+				label: 'Series',
+				data: [ { date: new Date( 2026, 0, 1 ), value: 0, visualValue: 2 } as DataPointDate ],
+			},
+		];
+		expect( getValueScaleDomain( data, false, allRendered ) ).toEqual( [ 0, 2 ] );
+	} );
+} );

package/src/charts/bar-chart/private/use-bar-chart-options.ts

@@ -7,7 +7,7 @@ import { getBucketResolution } from '../../../utils/bucket-info';
 import { createDateFormatter } from '../../../utils/date-formatting';
 import { getBandTickValues, getFormatter } from '../../private/time-axis';
 import { TruncatedXTickComponent, TruncatedYTickComponent } from './truncated-tick-component';
-import type { EnhancedDataPoint } from '../../../hooks/use-zero-value-display';
+import { getBarValue, getValueScaleDomain } from './value-domain';
 import type {
 	DataPointDate,
 	BaseChartProps,
@@ -207,6 +207,7 @@ export function useBarChartOptions(
 		const linearScale = {
 			type: 'linear' as const,
 			nice: true,
+			// XYChart defaults `zero` to true, which would stretch a caller's domain to 0.
 			zero: false,
 		};
 
@@ -223,12 +224,6 @@ export function useBarChartOptions(
 
 		const bandDomain = timeTickFormatter ? getBandDomain( data, isSeriesRendered ) : null;
 
-		const valueAccessor = ( d: DataPointDate | EnhancedDataPoint ) => {
-			// Use visualValue for bar rendering if available (for zero values), otherwise use value
-			const enhancedPoint = d as EnhancedDataPoint;
-			return enhancedPoint?.visualValue !== undefined ? enhancedPoint.visualValue : d?.value;
-		};
-
 		return {
 			timeAxis: bandDomain &&
 				timeTickFormatter && {
@@ -240,7 +235,7 @@ export function useBarChartOptions(
 				yTickFormat: valueFormatter,
 				tooltipLabelFormatter: tooltipDatumFormatter,
 				xAccessor: bucketAccessor,
-				yAccessor: valueAccessor,
+				yAccessor: getBarValue,
 				gridVisibility: 'x',
 				xScale: bandScale,
 				yScale: linearScale,
@@ -249,7 +244,7 @@ export function useBarChartOptions(
 				xTickFormat: valueFormatter,
 				yTickFormat: labelFormatter,
 				tooltipLabelFormatter: tooltipDatumFormatter,
-				xAccessor: valueAccessor,
+				xAccessor: getBarValue,
 				yAccessor: bucketAccessor,
 				gridVisibility: 'y',
 				xScale: linearScale,
@@ -271,36 +266,14 @@ export function useBarChartOptions(
 			yScale: baseYScale,
 		} = defaultOptions[ orientationKey ];
 
-		// When comparison series are present, visx only sees primary BarSeries and computes
-		// a too-narrow domain. Compute an explicit domain spanning all series so comparison
-		// shadows aren't clipped. Skip when the user has already provided an explicit domain.
-		let valueScaleDomainOverride: { domain?: [ number, number ] } = {};
+		const valueScaleOptions = horizontal ? stableOptions.xScale : stableOptions.yScale;
 		const hasComparisonSeries = data.some( s => s.options?.type === 'comparison' );
-		if ( hasComparisonSeries ) {
-			const valueAxisIsY = ! horizontal;
-			const userDomain = valueAxisIsY ? stableOptions.yScale?.domain : stableOptions.xScale?.domain;
-			if ( ! userDomain ) {
-				const allValues: number[] = [];
-				data.forEach( series => {
-					series.data.forEach( d => {
-						const enhanced = d as { visualValue?: number };
-						const v =
-							enhanced.visualValue !== undefined ? enhanced.visualValue : ( d.value as number );
-						if ( typeof v === 'number' && Number.isFinite( v ) ) {
-							allValues.push( v );
-						}
-					} );
-				} );
-				if ( allValues.length > 0 ) {
-					// Keep zero in the domain so bar length stays proportional to value — a
-					// non-zero baseline would exaggerate differences between periods. Math.max
-					// keeps zero on the far side too, so charts with negative values still span 0.
-					valueScaleDomainOverride = {
-						domain: [ Math.min( 0, ...allValues ), Math.max( 0, ...allValues ) ],
-					};
-				}
-			}
-		}
+		// Comparison shadows share the primary bars' scale, so they force zero even when the caller opted out.
+		const includeZero = hasComparisonSeries || valueScaleOptions?.zero !== false;
+		const domain = valueScaleOptions?.domain
+			? null
+			: getValueScaleDomain( data, includeZero, isSeriesRendered );
+		const valueScaleDomainOverride: { domain?: [ number, number ] } = domain ? { domain } : {};
 
 		const xScale = {
 			...baseXScale,
@@ -367,5 +340,5 @@ export function useBarChartOptions(
 				labelFormatter: dateAxisTickFormat || defaultTooltipLabelFormatter,
 			},
 		};
-	}, [ defaultOptions, axisConfig, stableOptions, horizontal, data ] );
+	}, [ defaultOptions, axisConfig, stableOptions, horizontal, data, isSeriesRendered ] );
 }

package/src/charts/bar-chart/private/value-domain.ts

@@ -0,0 +1,90 @@
+import type { EnhancedDataPoint } from '../../../hooks/use-zero-value-display';
+import type { DataPoint, DataPointDate, SeriesData } from '../../../types';
+
+/** Domain for a value axis that has nothing to scale, so its ticks still read 0 to 1. */
+const EMPTY_DOMAIN: [ number, number ] = [ 0, 1 ];
+
+/**
+ * The value a bar is drawn at, preferring `visualValue` so a zero still shows a sliver.
+ *
+ * A missing reading is NaN, not null: `ComparisonBars` coerces the value with `Number()`,
+ * which turns null into 0 and would draw a comparison shadow at the baseline.
+ *
+ * @param point - A data point handed to visx.
+ * @return The bar value, or NaN when the bucket has no reading.
+ */
+export const getBarValue = ( point: DataPoint | DataPointDate | EnhancedDataPoint ): number => {
+	const enhanced = point as EnhancedDataPoint;
+	const value = enhanced?.visualValue !== undefined ? enhanced.visualValue : point?.value;
+	return value ?? NaN;
+};
+
+/**
+ * Whether visx renders a bar for a point.
+ *
+ * @param point - A data point handed to visx.
+ * @return True when the point has a finite bar value.
+ */
+export const isBarRendered = ( point: DataPoint | DataPointDate | EnhancedDataPoint ): boolean =>
+	Number.isFinite( getBarValue( point ) );
+
+/**
+ * How many bars visx renders for a list of points.
+ *
+ * @param points - Data points handed to visx.
+ * @return The number of points that get a bar.
+ */
+export const countRenderedBars = (
+	points: ReadonlyArray< DataPoint | DataPointDate | EnhancedDataPoint >
+): number => points.filter( isBarRendered ).length;
+
+/**
+ * An explicit domain for the value scale, or null to let visx fit one to the data.
+ *
+ * Zero goes into the domain here rather than through the scale's `zero` flag: visx applies
+ * `nice` before `zero`, which would leave the axis topping out at a raw maximum.
+ *
+ * @param data             - Every series handed to the chart.
+ * @param includeZero      - Whether the domain must span zero.
+ * @param isSeriesRendered - Whether visx mounts a series, i.e. the legend shows it.
+ * @return Value domain, or null when visx should fit its own.
+ */
+export const getValueScaleDomain = (
+	data: SeriesData[],
+	includeZero: boolean,
+	isSeriesRendered: ( series: SeriesData ) => boolean
+): [ number, number ] | null => {
+	let min = Infinity;
+	let max = -Infinity;
+
+	// Only hidden series are skipped. Comparison series count too: visx sees just the
+	// primary BarSeries and would fit a domain too narrow for the comparison shadows.
+	for ( const series of data ) {
+		if ( ! isSeriesRendered( series ) ) {
+			continue;
+		}
+		for ( const point of series.data ) {
+			const value = getBarValue( point );
+			if ( ! Number.isFinite( value ) ) {
+				continue;
+			}
+			min = Math.min( min, value );
+			max = Math.max( max, value );
+		}
+	}
+
+	if ( min === Infinity ) {
+		return [ ...EMPTY_DOMAIN ];
+	}
+
+	// A flat series fitted by visx collapses to zero height, so it is anchored at zero regardless.
+	if ( min === max ) {
+		return min === 0 ? [ ...EMPTY_DOMAIN ] : [ Math.min( 0, min ), Math.max( 0, max ) ];
+	}
+
+	if ( includeZero ) {
+		return [ Math.min( 0, min ), Math.max( 0, max ) ];
+	}
+
+	return null;
+};