@automattic/charts 1.7.0 → 1.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "1.7.0",
+	"version": "1.8.1",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -63,7 +63,7 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.2.4",
+		"@automattic/number-formatters": "^1.2.5",
 		"@babel/runtime": "7.29.7",
 		"@react-spring/web": "10.1.1",
 		"@visx/annotation": "^4.0.0",

package/src/charts/bar-chart/bar-chart.tsx

@@ -1,7 +1,7 @@
 import { formatNumber } from '@automattic/number-formatters';
 import { PatternLines, PatternCircles, PatternWaves, PatternHexagons } from '@visx/pattern';
 import { Axis, BarSeries, BarGroup, Grid, XYChart } from '@visx/xychart';
-import { __ } from '@wordpress/i18n';
+import { __, sprintf } from '@wordpress/i18n';
 import clsx from 'clsx';
 import { useCallback, useContext, useState, useRef, useMemo } from 'react';
 import { Legend, useChartLegendItems } from '../../components/legend';
@@ -27,7 +27,16 @@ import { SingleChartContext } from '../private/single-chart-context';
 import { SvgEmptyState } from '../private/svg-empty-state';
 import { withResponsive } from '../private/with-responsive';
 import styles from './bar-chart.module.scss';
-import { useBarChartOptions } from './private';
+import {
+	useBarChartOptions,
+	ComparisonBars,
+	DEFAULT_COMPARISON_WIDTH_FACTOR,
+	COMPARISON_INNER_GAP,
+	MAX_GROUP_PADDING,
+	COMPARISON_TICK_GAP_FACTOR,
+	BASE_BAND_PADDING_INNER,
+} from './private';
+import type { ComparisonSeriesEntry } from './private';
 import type { BaseChartProps, DataPointDate, SeriesData, Optional } from '../../types';
 import type { RenderTooltipParams } from '../../visx/types';
 import type { ResponsiveConfig } from '../private/with-responsive';
@@ -74,6 +83,19 @@ const validateData = ( data: SeriesData[] ) => {
 
 const getPatternId = ( chartId: string, index: number ) => `bar-pattern-${ chartId }-${ index }`;
 
+// A "label: value" tooltip row. The join is a translated format string so the
+// separator (a colon + space here) can be adapted per locale.
+const renderTooltipRow = ( label: string | undefined, value: string ) => (
+	<div className={ styles[ 'bar-chart__tooltip-row' ] }>
+		{ sprintf(
+			/* translators: 1: data series, period, or category label. 2: its formatted value. */
+			__( '%1$s: %2$s', 'jetpack-charts' ),
+			label,
+			value
+		) }
+	</div>
+);
+
 const BarChartInternal: FC< BarChartProps > = ( {
 	data,
 	chartId: providedChartId,
@@ -128,8 +150,12 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >( undefined );
 	const [ isNavigating, setIsNavigating ] = useState( false );
 
+	// Comparison series have no .visx-bar elements; count only primary series so
+	// keyboard navigation doesn't cycle phantom indices into comparison-only slots.
+	const primarySeriesForNav = dataWithVisibleZeros.filter( s => s.options?.type !== 'comparison' );
 	const totalPoints =
-		Math.max( 0, ...data.map( series => series.data?.length || 0 ) ) * data.length;
+		Math.max( 0, ...primarySeriesForNav.map( s => s.data?.length || 0 ) ) *
+		primarySeriesForNav.length;
 
 	// Use the keyboard navigation hook
 	const { tooltipRef, onChartFocus, onChartBlur, onChartKeyDown } = useKeyboardNavigation( {
@@ -164,6 +190,100 @@ const BarChartInternal: FC< BarChartProps > = ( {
 		return seriesWithVisibility.every( ( { isVisible } ) => ! isVisible );
 	}, [ seriesWithVisibility ] );
 
+	// Derive primary vs comparison entries for comparison mode support.
+	const primaryEntries = useMemo(
+		() =>
+			seriesWithVisibility.filter(
+				( { isVisible, series } ) => isVisible && series.options?.type !== 'comparison'
+			),
+		[ seriesWithVisibility ]
+	);
+
+	const primaryKeys = useMemo(
+		() => primaryEntries.map( ( { series } ) => series.label ),
+		[ primaryEntries ]
+	);
+
+	// The keyboard-navigation index space and the highlight CSS both stride over primary
+	// bars only; the accessible tooltip must use the same list, or its datum diverges from
+	// the highlighted bar once a comparison series shifts the indices.
+	const primarySeries = useMemo(
+		() => primaryEntries.map( ( { series } ) => series ),
+		[ primaryEntries ]
+	);
+
+	const comparisonEntries = useMemo( () => {
+		const primaryByGroup = new Map< string | undefined, { label: string; index: number } >(
+			primaryEntries.map( ( { series, index } ) => [
+				series.group,
+				{ label: series.label, index },
+			] )
+		);
+
+		const entries: ComparisonSeriesEntry[] = [];
+		seriesWithVisibility.forEach( ( { series, index, isVisible } ) => {
+			if ( ! isVisible || series.options?.type !== 'comparison' ) {
+				return;
+			}
+			const primary =
+				primaryByGroup.get( series.group ) ??
+				( primaryEntries.length === 1
+					? { label: primaryEntries[ 0 ].series.label, index: primaryEntries[ 0 ].index }
+					: undefined );
+			if ( ! primary || ! primaryKeys.includes( primary.label ) ) {
+				return;
+			}
+			entries.push( { series, index, primaryKey: primary.label, primaryIndex: primary.index } );
+		} );
+		return entries;
+	}, [ seriesWithVisibility, primaryEntries, primaryKeys ] );
+
+	// Comparison widthFactor (how much wider the shadow is than the primary) drives both the
+	// shadow width (in ComparisonBars) and the primary narrowing.
+	const comparisonWidthFactor = useMemo( () => {
+		if ( comparisonEntries.length === 0 ) return undefined;
+		return (
+			getElementStyles( {
+				data: comparisonEntries[ 0 ].series,
+				index: comparisonEntries[ 0 ].index,
+			} ).barStyles?.widthFactor ?? DEFAULT_COMPARISON_WIDTH_FACTOR
+		);
+	}, [ comparisonEntries, getElementStyles ] );
+
+	// Narrow the primary bars by widening the visx group padding — a real geometry change, so
+	// pattern fills and borders are not distorted (unlike a CSS transform/scale). The padding is
+	// set so the comparison shadow (drawn at slot × widthFactor) fills all but a small gap of each
+	// per-series step, leaving a small gap between series within a tick (the larger gap between
+	// ticks comes from the category band's own padding). Because shadow = step × (1 - p) ×
+	// widthFactor, choosing p = 1 - (1 - innerGap)/widthFactor makes the shadow span (1 - innerGap)
+	// of the step; the primary stays 1/widthFactor of the shadow.
+	const groupPadding = useMemo( () => {
+		const basePadding = chartOptions.barGroup.padding;
+		if ( ! comparisonWidthFactor || comparisonWidthFactor <= 1 ) {
+			return basePadding;
+		}
+		const p = 1 - ( 1 - COMPARISON_INNER_GAP ) / comparisonWidthFactor;
+		return Math.min( Math.max( p, basePadding ), MAX_GROUP_PADDING );
+	}, [ chartOptions.barGroup.padding, comparisonWidthFactor ] );
+
+	// In comparison mode, tighten the gap between ticks by reducing the category band's inner
+	// padding (the value axis is left untouched). COMPARISON_TICK_GAP_FACTOR is the multiplier.
+	const { xScale, yScale } = useMemo( () => {
+		if ( comparisonEntries.length === 0 ) {
+			return { xScale: chartOptions.xScale, yScale: chartOptions.yScale };
+		}
+		const tighten = < T extends object >( scale: T ): T =>
+			( {
+				...scale,
+				paddingInner:
+					( ( scale as { paddingInner?: number } ).paddingInner ?? BASE_BAND_PADDING_INNER ) *
+					COMPARISON_TICK_GAP_FACTOR,
+			} ) as T;
+		return horizontal
+			? { xScale: chartOptions.xScale, yScale: tighten( chartOptions.yScale ) }
+			: { xScale: tighten( chartOptions.xScale ), yScale: chartOptions.yScale };
+	}, [ comparisonEntries.length, chartOptions.xScale, chartOptions.yScale, horizontal ] );
+
 	const getBarBackground = useCallback(
 		( index: number ) => () =>
 			withPatterns
@@ -172,33 +292,61 @@ const BarChartInternal: FC< BarChartProps > = ( {
 		[ withPatterns, getElementStyles, dataSorted, chartId ]
 	);
 
+	// Comparison shadow fill: when patterns are on, reuse the paired primary's pattern so the
+	// shadow reads as the same series; otherwise use the comparison series' resolved color.
+	const resolveComparisonFill = useCallback(
+		( entry: ComparisonSeriesEntry ) =>
+			withPatterns
+				? `url(#${ getPatternId( chartId, entry.primaryIndex ) })`
+				: getElementStyles( { data: entry.series, index: entry.index } ).color,
+		[ withPatterns, chartId, getElementStyles ]
+	);
+
 	const renderDefaultTooltip = useCallback(
 		( { tooltipData }: RenderTooltipParams< DataPointDate > ) => {
 			const nearestDatum = tooltipData?.nearestDatum?.datum;
 			if ( ! nearestDatum ) return null;
 
+			const primaryKey = tooltipData?.nearestDatum?.key;
+			const categoryLabel = chartOptions.tooltip.labelFormatter(
+				nearestDatum.label || ( nearestDatum.date ? nearestDatum.date.getTime() : 0 ),
+				0,
+				[]
+			);
+
+			// Find the comparison value paired with the hovered primary series (same group)
+			// at the same category, so the tooltip can show both periods at once.
+			const comparisonEntry = comparisonEntries.find( entry => entry.primaryKey === primaryKey );
+			const comparisonDatum = comparisonEntry?.series.data.find( point => {
+				const p = point as DataPointDate;
+				return nearestDatum.label != null
+					? p.label === nearestDatum.label
+					: !! nearestDatum.date && !! p.date && p.date.getTime() === nearestDatum.date.getTime();
+			} ) as DataPointDate | undefined;
+
+			// With a paired comparison value, show the category as the header and one row
+			// per period (primary + comparison).
+			if ( comparisonEntry && comparisonDatum && comparisonDatum.value != null ) {
+				return (
+					<div className={ styles[ 'bar-chart__tooltip' ] }>
+						<div className={ styles[ 'bar-chart__tooltip-header' ] }>{ categoryLabel }</div>
+						{ renderTooltipRow( primaryKey, formatNumber( nearestDatum.value as number ) ) }
+						{ renderTooltipRow(
+							comparisonEntry.series.label,
+							formatNumber( comparisonDatum.value as number )
+						) }
+					</div>
+				);
+			}
+
 			return (
 				<div className={ styles[ 'bar-chart__tooltip' ] }>
-					<div className={ styles[ 'bar-chart__tooltip-header' ] }>
-						{ tooltipData?.nearestDatum?.key }
-					</div>
-					<div className={ styles[ 'bar-chart__tooltip-row' ] }>
-						<span className={ styles[ 'bar-chart__tooltip-label' ] }>
-							{ chartOptions.tooltip.labelFormatter(
-								nearestDatum.label || ( nearestDatum.date ? nearestDatum.date.getTime() : 0 ),
-								0,
-								[]
-							) }
-							:
-						</span>
-						<span className={ styles[ 'bar-chart__tooltip-value' ] }>
-							{ formatNumber( nearestDatum.value as number ) }
-						</span>
-					</div>
+					<div className={ styles[ 'bar-chart__tooltip-header' ] }>{ primaryKey }</div>
+					{ renderTooltipRow( categoryLabel, formatNumber( nearestDatum.value as number ) ) }
 				</div>
 			);
 		},
-		[ chartOptions.tooltip ]
+		[ chartOptions.tooltip, comparisonEntries ]
 	);
 
 	const renderPattern = useCallback(
@@ -240,8 +388,11 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	const createPatternBorderStyle = useCallback(
 		( index: number, color: string ) => {
 			const patternId = getPatternId( chartId, index );
+			// Border the primary bars and any comparison shadow reusing the same pattern,
+			// so a patterned shadow gets the same outline as its primary bar.
 			return `
-			.visx-bar[fill="url(#${ patternId })"] {
+			.visx-bar[fill="url(#${ patternId })"],
+			.bar-chart__comparison-bars rect[fill="url(#${ patternId })"] {
 				stroke: ${ color };
 				stroke-width: 1;
 				}
@@ -253,19 +404,21 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	const createKeyboardHighlightStyle = useCallback( () => {
 		if ( selectedIndex === undefined ) return '';
 
-		// Calculate which bar should be highlighted based on selectedIndex
+		// Use only primary entries — comparison series have no .visx-bar elements so
+		// their indices must not appear in the nth-child selector.
 		// Pattern: [series1[0], series2[0], series3[0], series1[1], series2[1], series3[1], ...]
-		const maxDataPoints = Math.max( ...data.map( s => s.data.length ) );
-		const dataPointIndex = Math.floor( selectedIndex / data.length );
-		const seriesIndex = selectedIndex % data.length;
+		const primaryCount = primaryEntries.length;
+		const maxDataPoints = Math.max( ...primaryEntries.map( e => e.series.data.length ) );
+		const dataPointIndex = Math.floor( selectedIndex / primaryCount );
+		const seriesIndex = selectedIndex % primaryCount;
 
 		// Only highlight if we're within valid bounds
-		if ( dataPointIndex >= maxDataPoints || seriesIndex >= data.length ) {
+		if ( dataPointIndex >= maxDataPoints || seriesIndex >= primaryCount ) {
 			return '';
 		}
 
-		const seriesData = data[ seriesIndex ];
-		if ( dataPointIndex >= seriesData.data.length ) {
+		const seriesData = primaryEntries[ seriesIndex ]?.series;
+		if ( ! seriesData || dataPointIndex >= seriesData.data.length ) {
 			return '';
 		}
 
@@ -286,7 +439,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 		`;
 
 		return generatedStyles;
-	}, [ selectedIndex, data, chartId ] );
+	}, [ selectedIndex, primaryEntries, chartId ] );
 
 	// Validate data first
 	const error = validateData( dataSorted );
@@ -386,8 +539,8 @@ const BarChartInternal: FC< BarChartProps > = ( {
 											...defaultMargin,
 											...margin,
 										} }
-										xScale={ chartOptions.xScale }
-										yScale={ chartOptions.yScale }
+										xScale={ xScale }
+										yScale={ yScale }
 										horizontal={ horizontal }
 										pointerEventsDataKey="nearest"
 									>
@@ -434,24 +587,32 @@ const BarChartInternal: FC< BarChartProps > = ( {
 											</SvgEmptyState>
 										) : null }
 
-										<BarGroup padding={ chartOptions.barGroup.padding }>
-											{ seriesWithVisibility.map( ( { series: seriesData, index, isVisible } ) => {
-												// Skip rendering invisible series
-												if ( ! isVisible ) {
-													return null;
-												}
+										<ComparisonBars
+											comparisonEntries={ comparisonEntries }
+											primaryKeys={ primaryKeys }
+											groupPadding={ groupPadding }
+											horizontal={ horizontal }
+											xAccessor={ chartOptions.accessors.xAccessor }
+											yAccessor={
+												chartOptions.accessors.yAccessor as (
+													d: DataPointDate
+												) => number | undefined
+											}
+											getElementStyles={ getElementStyles }
+											resolveFill={ resolveComparisonFill }
+										/>
 
-												return (
-													<BarSeries
-														key={ seriesData?.label }
-														dataKey={ seriesData?.label }
-														data={ seriesData.data as DataPointDate[] }
-														yAccessor={ chartOptions.accessors.yAccessor }
-														xAccessor={ chartOptions.accessors.xAccessor }
-														colorAccessor={ getBarBackground( index ) }
-													/>
-												);
-											} ) }
+										<BarGroup padding={ groupPadding }>
+											{ primaryEntries.map( ( { series: seriesData, index } ) => (
+												<BarSeries
+													key={ seriesData?.label }
+													dataKey={ seriesData?.label }
+													data={ seriesData.data as DataPointDate[] }
+													yAccessor={ chartOptions.accessors.yAccessor }
+													xAccessor={ chartOptions.accessors.xAccessor }
+													colorAccessor={ getBarBackground( index ) }
+												/>
+											) ) }
 										</BarGroup>
 
 										<Axis { ...chartOptions.axis.x } />
@@ -468,7 +629,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 												keyboardFocusedClassName={
 													styles[ 'bar-chart__tooltip--keyboard-focused' ]
 												}
-												series={ data }
+												series={ primarySeries }
 												mode="individual"
 											/>
 										) }

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

@@ -0,0 +1,70 @@
+export type ComparisonRect = { x: number; y: number; width: number; height: number };
+
+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.
+ *
+ * @param {ValueScale} scale - The continuous value scale.
+ * @return {number} The baseline output position in pixels.
+ */
+export function getValueScaleBaseline( scale: ValueScale ): number {
+	const [ a, b ] = scale.range().map( r => Number( r ) || 0 );
+	const isDescending = b < a;
+	const maybeZero = scale( 0 );
+	const [ minOutput, maxOutput ] = isDescending ? [ b, a ] : [ a, b ];
+	if ( isDescending ) {
+		return Number.isFinite( maybeZero )
+			? Math.min( Math.max( minOutput, maybeZero ), maxOutput )
+			: maxOutput;
+	}
+	return Number.isFinite( maybeZero )
+		? Math.min( Math.max( maybeZero, minOutput ), maxOutput )
+		: minOutput;
+}
+
+/**
+ * Compute the rect for a comparison "shadow" bar, centered on the paired
+ * primary bar slot and scaled by `widthFactor`.
+ *
+ * @param {object}  params               - Geometry inputs.
+ * @param {boolean} params.horizontal    - True for a horizontal bar chart, false for vertical.
+ * @param {number}  params.bandPosition  - bandScale(category): start px of the category band.
+ * @param {number}  params.slotOffset    - groupScale(primaryKey): offset of the primary slot within the band.
+ * @param {number}  params.slotThickness - groupScale.bandwidth(): primary bar thickness in px.
+ * @param {number}  params.valuePosition - valueScale(value): output px for the bar's data value.
+ * @param {number}  params.baseline      - getValueScaleBaseline(valueScale): zero-line output px.
+ * @param {number}  params.widthFactor   - Shadow thickness multiplier, e.g. 1.5 for 150% width.
+ * @return {ComparisonRect} The {x, y, width, height} of the shadow rect.
+ */
+export function computeComparisonRect( params: {
+	horizontal: boolean;
+	bandPosition: number;
+	slotOffset: number;
+	slotThickness: number;
+	valuePosition: number;
+	baseline: number;
+	widthFactor: number;
+} ): ComparisonRect {
+	const {
+		horizontal,
+		bandPosition,
+		slotOffset,
+		slotThickness,
+		valuePosition,
+		baseline,
+		widthFactor,
+	} = params;
+	const slotStart = bandPosition + slotOffset;
+	const shadowThickness = slotThickness * widthFactor;
+	const shadowStart = slotStart + slotThickness / 2 - shadowThickness / 2;
+	const valueStart = Math.min( valuePosition, baseline );
+	const valueLength = Math.abs( baseline - valuePosition );
+
+	if ( horizontal ) {
+		return { x: valueStart, y: shadowStart, width: valueLength, height: shadowThickness };
+	}
+	return { x: shadowStart, y: valueStart, width: shadowThickness, height: valueLength };
+}

package/src/charts/bar-chart/private/comparison-bars.tsx

@@ -0,0 +1,155 @@
+import { scaleBand } from '@visx/scale';
+import { DataContext } from '@visx/xychart';
+import { useContext } from 'react';
+import { computeComparisonRect, getValueScaleBaseline } from './comparison-bars-geometry';
+import {
+	DEFAULT_COMPARISON_OPACITY,
+	DEFAULT_COMPARISON_WIDTH_FACTOR,
+} from './comparison-constants';
+import type { ElementStyles, GetElementStylesParams } from '../../../providers';
+import type { DataPointDate, SeriesData } from '../../../types';
+import type { FC, ReactNode } from 'react';
+
+export type ComparisonSeriesEntry = {
+	series: SeriesData;
+	index: number;
+	primaryKey: string;
+	/** dataSorted index of the paired primary series (used to share its pattern fill). */
+	primaryIndex: number;
+};
+
+// Minimal shape we need from visx scales — avoids spreading `any` while
+// remaining compatible with both band and continuous scale return types.
+type AnyScale = ( ( input: unknown ) => number ) & {
+	bandwidth?: () => number;
+	range: () => unknown[];
+};
+
+// Renders translucent "shadow" bars for comparison series behind their paired primary bars.
+// IMPORTANT: each comparison datum's category key (label or date) must exactly match a key
+// used by the primary series — if it doesn't, bandScale() returns undefined and the shadow
+// is silently skipped. Ensure comparison data reuses the same label/date values as primary.
+export const ComparisonBars: FC< {
+	comparisonEntries: ComparisonSeriesEntry[];
+	primaryKeys: string[];
+	groupPadding: number;
+	horizontal: boolean;
+	xAccessor: ( d: DataPointDate ) => string | number | Date | undefined;
+	yAccessor: ( d: DataPointDate ) => number | undefined;
+	getElementStyles: ( params: GetElementStylesParams ) => ElementStyles;
+	/** Resolves the shadow fill — the paired primary's pattern when patterns are on, else a color. */
+	resolveFill: ( entry: ComparisonSeriesEntry ) => string;
+} > = ( {
+	comparisonEntries,
+	primaryKeys,
+	groupPadding,
+	horizontal,
+	xAccessor,
+	yAccessor,
+	getElementStyles,
+	resolveFill,
+} ) => {
+	const context = useContext( DataContext );
+	const xScale = context?.xScale as AnyScale | undefined;
+	const yScale = context?.yScale as AnyScale | undefined;
+
+	if ( ! xScale || ! yScale || primaryKeys.length === 0 ) {
+		return null;
+	}
+
+	// Vertical: band axis is x, value axis is y. Horizontal: reversed.
+	const bandScale = ( horizontal ? yScale : xScale ) as AnyScale;
+	const valueScale = ( horizontal ? xScale : yScale ) as AnyScale;
+
+	const bandwidth = bandScale.bandwidth ? bandScale.bandwidth() : 0;
+	if ( ! bandwidth ) {
+		return null;
+	}
+
+	// Rebuild visx's inner group scale exactly as BarGroup does.
+	const groupScale = scaleBand( {
+		domain: primaryKeys,
+		range: [ 0, bandwidth ],
+		padding: groupPadding,
+	} );
+	const slotThickness = groupScale.bandwidth();
+	const baseline = getValueScaleBaseline( valueScale );
+
+	// Vertical uses xAccessor for category label; horizontal uses yAccessor.
+	const bandAccessor = horizontal ? yAccessor : xAccessor;
+	const valueAccessor = horizontal ? xAccessor : yAccessor;
+
+	const rects: ReactNode[] = [];
+
+	comparisonEntries.forEach( entry => {
+		const { series, index, primaryKey } = entry;
+		const slotOffset = groupScale( primaryKey );
+		if ( slotOffset == null || ! Number.isFinite( slotOffset ) ) {
+			return;
+		}
+
+		const { barStyles } = getElementStyles( { data: series, index } );
+		const opacity = barStyles?.opacity ?? DEFAULT_COMPARISON_OPACITY; // safety net; CompleteChartTheme guarantees this value
+		const widthFactor = barStyles?.widthFactor ?? DEFAULT_COMPARISON_WIDTH_FACTOR;
+		// Fill is the paired primary's pattern (when patterns are on) or its resolved color.
+		const fill = resolveFill( entry );
+		// The shadow is `widthFactor` × the (narrowed) primary slot. bar-chart.tsx narrows the
+		// primary bars by widening the group padding so this ratio holds with real geometry.
+
+		( series.data as DataPointDate[] ).forEach( ( datum, i ) => {
+			const bandPosition = Number( bandScale( bandAccessor( datum ) as never ) );
+			const valuePosition = Number( valueScale( Number( valueAccessor( datum ) ) as never ) );
+
+			if ( ! Number.isFinite( bandPosition ) || ! Number.isFinite( valuePosition ) ) {
+				if ( process.env.NODE_ENV !== 'production' && ! Number.isFinite( bandPosition ) ) {
+					// eslint-disable-next-line no-console
+					console.warn(
+						`[Charts] ComparisonBars: datum key "${ String(
+							bandAccessor( datum )
+						) }" did not match any primary category. Shadow will not be rendered. ` +
+							'Ensure comparison series data uses the same label/date keys as the primary series.'
+					);
+				}
+				return;
+			}
+
+			const rect = computeComparisonRect( {
+				horizontal,
+				bandPosition,
+				slotOffset: slotOffset as number,
+				slotThickness,
+				valuePosition,
+				baseline,
+				widthFactor,
+			} );
+
+			rects.push(
+				<rect
+					key={ `${ index }-${ i }` }
+					data-testid={ `bar-chart-comparison-${ index }-${ i }` }
+					x={ rect.x }
+					y={ rect.y }
+					width={ rect.width }
+					height={ rect.height }
+					fill={ fill }
+					opacity={ opacity }
+				/>
+			);
+		} );
+	} );
+
+	if ( rects.length === 0 ) {
+		return null;
+	}
+
+	return (
+		<g
+			className="bar-chart__comparison-bars"
+			pointerEvents="none"
+			aria-hidden="true"
+			data-testid="bar-chart-comparison-bars"
+		>
+			{ rects }
+		</g>
+	);
+};

package/src/charts/bar-chart/private/comparison-constants.ts

@@ -0,0 +1,33 @@
+// Shared comparison-mode tuning constants. These drive the geometry of the
+// translucent "shadow" bars and how the primary bars are narrowed to sit in front of them.
+
+/**
+ * How much wider the comparison shadow is than the primary bar. Fallback used when the
+ * theme value (`barChart.barStyles.comparison.widthFactor`) is absent. Also drives the
+ * primary narrowing — the primary stays `1 / widthFactor` of the shadow.
+ */
+export const DEFAULT_COMPARISON_WIDTH_FACTOR = 1.5;
+
+/**
+ * Opacity of the comparison shadow. Fallback used when the theme value
+ * (`barChart.barStyles.comparison.opacity`) is absent.
+ */
+export const DEFAULT_COMPARISON_OPACITY = 0.5;
+
+/**
+ * Fraction of each per-series step left as a gap between bars within a single tick.
+ * Larger = more space between adjacent series; the shadow spans `1 - COMPARISON_INNER_GAP` of the step.
+ */
+export const COMPARISON_INNER_GAP = 0.1;
+
+/**
+ * Upper clamp on the computed group padding, so bars can never collapse to zero width
+ * even at very large `widthFactor` values.
+ */
+export const MAX_GROUP_PADDING = 0.9;
+
+/**
+ * Factor applied to the category band's `paddingInner` in comparison mode to tighten the
+ * gap between ticks. `0.75` = a 25% reduction of the tick-gap padding.
+ */
+export const COMPARISON_TICK_GAP_FACTOR = 0.75;

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

@@ -1,2 +1,11 @@
 export { useBarChartOptions } from './use-bar-chart-options';
 export { TruncatedXTickComponent, TruncatedYTickComponent } from './truncated-tick-component';
+export { ComparisonBars } from './comparison-bars';
+export type { ComparisonSeriesEntry } from './comparison-bars';
+export {
+	DEFAULT_COMPARISON_WIDTH_FACTOR,
+	COMPARISON_INNER_GAP,
+	MAX_GROUP_PADDING,
+	COMPARISON_TICK_GAP_FACTOR,
+} from './comparison-constants';
+export { BASE_BAND_PADDING_INNER } from './use-bar-chart-options';