@automattic/charts 4.11.1 → 4.13.0

package/src/charts/bar-chart/private/band-tooltip.tsx

@@ -40,7 +40,8 @@ export function nearestBandIndex< Datum >(
 /**
  * Correct visx's range-based band inversion, which omits outer padding.
  * @param root0               - Registered series selection.
- * @param root0.keys          - Visible series keys.
+ * @param root0.keys          - Visible series keys, back to front where bars overlap.
+ * @param root0.slots         - Where series share slots: the slots of a category, in the order the band lays them out, and the slot each series sits in.
  * @param root0.groupPadding  - Padding between grouped bars.
  * @param root0.withTooltips  - Whether pointer events update the tooltip.
  * @param root0.onPointerDown - Receives the corrected pointer-down datum.
@@ -50,6 +51,7 @@ export function nearestBandIndex< Datum >(
  */
 export function BandTooltip( {
 	keys,
+	slots,
 	groupPadding,
 	withTooltips,
 	onPointerDown,
@@ -57,16 +59,17 @@ export function BandTooltip( {
 	onPointerMove,
 }: {
 	keys: string[];
+	slots?: { keys: string[]; slotOf: ( key: string ) => string };
 	groupPadding: number;
 	onPointerMove?: ( selection: PointerSelection ) => void;
 } & Pick< BarChartProps, 'withTooltips' | 'onPointerDown' | 'onPointerUp' > ) {
 	const { xScale, yScale, dataRegistry, horizontal } = useContext( DataContext );
-	const { showTooltip } = useContext( TooltipContext );
+	const { showTooltip, hideTooltip, updateTooltip } = useContext( TooltipContext );
 	const scale = ( horizontal ? yScale : xScale ) as BandScale | undefined;
 	const bandwidth = scale?.bandwidth?.() ?? 0;
 	const groupScale = useMemo(
-		() => createGroupScale( keys, bandwidth, groupPadding ),
-		[ keys, bandwidth, groupPadding ]
+		() => createGroupScale( slots?.keys ?? keys, bandwidth, groupPadding ),
+		[ slots, keys, bandwidth, groupPadding ]
 	);
 	const getSelections = useCallback(
 		( params: Parameters< PointerHandler >[ 0 ] ) => {
@@ -74,28 +77,26 @@ export function BandTooltip( {
 			if ( ! point || ! scale?.bandwidth ) {
 				return [];
 			}
+			const position = horizontal ? point.y : point.x;
 			const selections: PointerSelection[] = [];
+			const bands: number[] = [];
 			for ( const key of keys ) {
 				const entry = dataRegistry?.get( key );
 				if ( ! entry ) {
 					continue;
 				}
 				const accessor = horizontal ? entry.yAccessor : entry.xAccessor;
-				const index = nearestBandIndex(
-					entry.data,
-					accessor,
-					scale,
-					horizontal ? point.y : point.x
-				);
+				const index = nearestBandIndex( entry.data, accessor, scale, position );
 				if ( index < 0 ) {
 					continue;
 				}
 				const datum = entry.data[ index ];
-				const start = Number( scale( accessor( datum ) ) ) + Number( groupScale( key ) );
+				const band = Number( scale( accessor( datum ) ) );
+				const start = band + Number( groupScale( slots ? slots.slotOf( key ) : key ) );
 				const end = start + groupScale.step();
-				const position = horizontal ? point.y : point.x;
 				const distance =
 					position >= start && position <= end ? 0 : Math.abs( position - ( start + end ) / 2 );
+				bands.push( band );
 				selections.push( {
 					event: params.event,
 					key,
@@ -106,9 +107,19 @@ export function BandTooltip( {
 					distanceY: horizontal ? distance : 0,
 				} );
 			}
-			return selections;
+			if ( ! slots ) {
+				return selections;
+			}
+			// A series without a datum at the hovered category must not lend the tooltip a neighbor's.
+			const bandDistance = ( band: number ) => Math.abs( band + scale.bandwidth() / 2 - position );
+			const hoveredBand = bands.reduce< number | undefined >(
+				( best, band ) =>
+					best === undefined || bandDistance( band ) < bandDistance( best ) ? band : best,
+				undefined
+			);
+			return selections.filter( ( _, index ) => bands[ index ] === hoveredBand );
 		},
-		[ scale, dataRegistry, horizontal, keys, groupScale ]
+		[ scale, dataRegistry, horizontal, keys, slots, groupScale ]
 	);
 	const handlePointer = useCallback< PointerHandler >(
 		params => {
@@ -125,6 +136,10 @@ export function BandTooltip( {
 				onPointerMove?.( nearest );
 			}
 			if ( withTooltips && params?.event.type !== 'pointerup' ) {
+				if ( slots ) {
+					// visx merges each datum into the previous tooltip's, which would keep a bar the pointer has left.
+					updateTooltip( state => ( { ...state, tooltipData: undefined } ) );
+				}
 				selections.forEach( showTooltip );
 			}
 			const callback = params?.event.type === 'pointerdown' ? onPointerDown : onPointerUp;
@@ -135,9 +150,20 @@ export function BandTooltip( {
 				callback( nearest );
 			}
 		},
-		[ getSelections, withTooltips, showTooltip, onPointerDown, onPointerUp, onPointerMove ]
+		[
+			getSelections,
+			withTooltips,
+			slots,
+			showTooltip,
+			updateTooltip,
+			onPointerDown,
+			onPointerUp,
+			onPointerMove,
+		]
 	);
 	useEventEmitter( 'pointermove', withTooltips ? handlePointer : undefined );
+	// Slotted bars subscribe to no events, so nothing else closes the tooltip when the pointer leaves.
+	useEventEmitter( 'pointerout', withTooltips && slots ? hideTooltip : undefined );
 	useEventEmitter( 'pointerdown', handlePointer );
 	useEventEmitter( 'pointerup', onPointerUp ? handlePointer : undefined );
 	return null;

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

@@ -0,0 +1,132 @@
+import { BarGroup, BarSeries } from '@visx/xychart';
+import ClassifiedBarSeries from './classified-bar-series';
+import { SelectedBarRing } from './selected-bar-ring';
+import SlottedBarSeries from './slotted-bar-series';
+import type { SelectedBar } from './selected-bar-ring';
+import type { OverlapSlots } from './use-overlap-slots';
+import type { DataPointDate, SeriesData } from '../../../types';
+import type { BarChartProps } from '../types';
+import type { AxisScale } from '@visx/axis';
+import type { SeriesProps } from '@visx/xychart';
+import type { FC } from 'react';
+
+type Accessors = Pick<
+	SeriesProps< AxisScale, AxisScale, DataPointDate >,
+	'xAccessor' | 'yAccessor'
+>;
+
+type Props = Accessors & {
+	chartId: string;
+	overlapSlots: OverlapSlots | undefined;
+	selectedBar: SelectedBar | undefined;
+	primaryEntries: { series: SeriesData; index: number }[];
+	primaryKeys: string[];
+	getBarBackground: ( index: number ) => ( datum: DataPointDate ) => string;
+	barClassName: BarChartProps[ 'barClassName' ];
+	groupPadding: number;
+	horizontal: boolean;
+};
+
+/**
+ * Draws the bars in front of any comparison shadows, slotted for an overlap layout and grouped by visx otherwise, then the selected bar's ring.
+ *
+ * @param props                  - Component props.
+ * @param props.chartId          - The chart's id, which keeps the ring's clip path unique on a page with several charts.
+ * @param props.overlapSlots     - The overlap layout, or undefined for a grouped one.
+ * @param props.selectedBar      - The bar or slot the keyboard has selected.
+ * @param props.primaryEntries   - The visible primary series, for a grouped layout.
+ * @param props.primaryKeys      - Their labels, in group order.
+ * @param props.getBarBackground - Reads a series' bar fill.
+ * @param props.barClassName     - Adds classes to a bar.
+ * @param props.groupPadding     - The padding between the bars of a category.
+ * @param props.horizontal       - Whether the bars run horizontally.
+ * @param props.xAccessor        - Reads a datum's x value.
+ * @param props.yAccessor        - Reads a datum's y value.
+ * @return The bars.
+ */
+export const BarLayer: FC< Props > = ( {
+	chartId,
+	overlapSlots,
+	selectedBar,
+	primaryEntries,
+	primaryKeys,
+	getBarBackground,
+	barClassName,
+	groupPadding,
+	horizontal,
+	xAccessor,
+	yAccessor,
+} ) => {
+	let bars;
+	if ( overlapSlots ) {
+		bars = (
+			<g className="visx-bar-group">
+				{ overlapSlots.entries.map( ( { series, index } ) => (
+					<SlottedBarSeries
+						key={ series.label }
+						dataKey={ series.label }
+						data={ series.data as DataPointDate[] }
+						xAccessor={ xAccessor }
+						yAccessor={ yAccessor }
+						colorAccessor={ getBarBackground( index ) }
+						barClassName={ barClassName }
+						slotKeys={ overlapSlots.slotKeys }
+						slotKey={ overlapSlots.slotOf( series.label ) }
+						thickness={ overlapSlots.thicknessOf( series.label ) }
+						groupPadding={ groupPadding }
+					/>
+				) ) }
+			</g>
+		);
+	} else if ( barClassName ) {
+		bars = (
+			<g className="visx-bar-group">
+				{ primaryEntries.map( ( { series, index } ) => (
+					<ClassifiedBarSeries
+						key={ series.label }
+						dataKey={ series.label }
+						data={ series.data as DataPointDate[] }
+						xAccessor={ xAccessor }
+						yAccessor={ yAccessor }
+						colorAccessor={ getBarBackground( index ) }
+						barClassName={ barClassName }
+						primaryKeys={ primaryKeys }
+						groupPadding={ groupPadding }
+					/>
+				) ) }
+			</g>
+		);
+	} else {
+		bars = (
+			<BarGroup padding={ groupPadding }>
+				{ primaryEntries.map( ( { series, index } ) => (
+					<BarSeries
+						key={ series.label }
+						dataKey={ series.label }
+						data={ series.data as DataPointDate[] }
+						xAccessor={ xAccessor }
+						yAccessor={ yAccessor }
+						colorAccessor={ getBarBackground( index ) }
+					/>
+				) ) }
+			</BarGroup>
+		);
+	}
+
+	return (
+		<>
+			{ bars }
+			{ selectedBar && (
+				<SelectedBarRing
+					chartId={ chartId }
+					selected={ selectedBar }
+					slotKeys={ overlapSlots?.slotKeys ?? primaryKeys }
+					groupPadding={ groupPadding }
+					horizontal={ horizontal }
+					xAccessor={ xAccessor }
+					yAccessor={ yAccessor as ( datum: DataPointDate ) => number | undefined }
+				/>
+			) }
+		</>
+	);
+};

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

@@ -1,10 +1,9 @@
-export type ComparisonRect = { x: number; y: number; width: number; height: number };
+export type SlotRect = { x: number; y: number; width: number; height: number };
 
 type ValueScale = ( ( v: number ) => number ) & { range: () => unknown[] };
 
 /**
- * Mirrors visx's getScaleBaseline so comparison shadows and primary bars
- * share the same baseline, including out-of-domain zero values.
+ * Mirrors visx's getScaleBaseline so bars drawn outside visx share the baseline of its bars, including out-of-domain zero values.
  *
  * @param {ValueScale} scale - The continuous value scale.
  * @return {number} The baseline output position in pixels.
@@ -23,45 +22,34 @@ export function getValueScaleBaseline( scale: ValueScale ): number {
 }
 
 /**
- * Compute the rect for a comparison "shadow" bar, centered on the paired
- * primary bar slot and scaled by `widthFactor`.
+ * Compute the rect that spans `valuePositions` along the value axis, centered on a slot and scaled by `widthFactor` across it.
  *
- * @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.
+ * @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(slotKey): offset of the slot within the band.
+ * @param {number}   params.slotThickness  - groupScale.bandwidth(): slot thickness in px.
+ * @param {number[]} params.valuePositions - Output px the rect must reach, such as the baseline and each bar's value.
+ * @param {number}   params.widthFactor    - Thickness multiplier, e.g. 0.5 for half the slot.
+ * @return {SlotRect} The {x, y, width, height} of the rect.
  */
-export function computeComparisonRect( params: {
+export function computeSlotRect( params: {
 	horizontal: boolean;
 	bandPosition: number;
 	slotOffset: number;
 	slotThickness: number;
-	valuePosition: number;
-	baseline: number;
+	valuePositions: 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 );
+} ): SlotRect {
+	const { horizontal, bandPosition, slotOffset, slotThickness, valuePositions, widthFactor } =
+		params;
+	const thickness = slotThickness * widthFactor;
+	const start = bandPosition + slotOffset + slotThickness / 2 - thickness / 2;
+	const valueStart = Math.min( ...valuePositions );
+	const valueLength = Math.max( ...valuePositions ) - valueStart;
 
 	if ( horizontal ) {
-		return { x: valueStart, y: shadowStart, width: valueLength, height: shadowThickness };
+		return { x: valueStart, y: start, width: valueLength, height: thickness };
 	}
-	return { x: shadowStart, y: valueStart, width: shadowThickness, height: valueLength };
+	return { x: start, y: valueStart, width: thickness, height: valueLength };
 }

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

@@ -1,11 +1,8 @@
 import { DataContext } from '@visx/xychart';
 import { useContext } from 'react';
 import { createGroupScale } from './band-scale';
-import { computeComparisonRect, getValueScaleBaseline } from './comparison-bars-geometry';
-import {
-	DEFAULT_COMPARISON_OPACITY,
-	DEFAULT_COMPARISON_WIDTH_FACTOR,
-} from './comparison-constants';
+import { computeSlotRect, getValueScaleBaseline } from './comparison-bars-geometry';
+import { DEFAULT_COMPARISON_WIDTH_FACTOR } from './comparison-constants';
 import type { BandScale } from './band-scale';
 import type { ElementStyles, GetElementStylesParams } from '../../../providers';
 import type { DataPointDate, SeriesData } from '../../../types';
@@ -21,8 +18,6 @@ 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
@@ -30,7 +25,7 @@ export type ComparisonSeriesEntry = {
 type AnyScale = ( ( input: unknown ) => number ) &
 	Partial< Pick< BandScale, 'bandwidth' > > & { range: () => unknown[] };
 
-// Renders translucent "shadow" bars for comparison series behind their paired primary bars.
+// Renders the bars of comparison series, wider and 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.
@@ -42,8 +37,8 @@ export const ComparisonBars: FC< {
 	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;
+	/** Resolves a comparison bar's fill: its pattern when patterns are on, else its datum's or its series' color. */
+	resolveFill: ( entry: ComparisonSeriesEntry, datum: DataPointDate ) => string;
 } > = ( {
 	comparisonEntries,
 	primaryKeys,
@@ -90,10 +85,7 @@ export const ComparisonBars: FC< {
 		}
 
 		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.
 
@@ -114,13 +106,12 @@ export const ComparisonBars: FC< {
 				return;
 			}
 
-			const rect = computeComparisonRect( {
+			const rect = computeSlotRect( {
 				horizontal,
 				bandPosition,
 				slotOffset: slotOffset as number,
 				slotThickness,
-				valuePosition,
-				baseline,
+				valuePositions: [ baseline, valuePosition ],
 				widthFactor,
 			} );
 
@@ -133,8 +124,8 @@ export const ComparisonBars: FC< {
 					y={ rect.y }
 					width={ rect.width }
 					height={ rect.height }
-					fill={ fill }
-					opacity={ opacity }
+					fill={ resolveFill( entry, datum ) }
+					opacity={ barStyles?.opacity }
 				/>
 			);
 		} );

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

@@ -1,22 +1,16 @@
 // 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.
+// comparison 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
+ * How much wider the comparison bar 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.
+ * primary narrowing — the primary stays `1 / widthFactor` of the comparison.
  */
 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.
+ * Larger = more space between adjacent series; the comparison bar spans `1 - COMPARISON_INNER_GAP` of the step.
  */
 export const COMPARISON_INNER_GAP = 0.1;
 

package/src/charts/bar-chart/private/grouped-bars.ts

@@ -0,0 +1,68 @@
+import { isValidHexColor } from '../../../utils/color-utils';
+import { shadeWithContrast, tintWithContrast } from './overlap-bars';
+import type { SeriesData } from '../../../types';
+
+/**
+ * Pairs each comparison series with the primary of its `group`, or with the only primary.
+ *
+ * @param series - The chart's series.
+ * @return The index of each paired comparison's primary, keyed by the comparison's index.
+ */
+function getComparisonPrimaries( series: SeriesData[] ): Map< number, number > {
+	const primaries = series.flatMap( ( item, index ) =>
+		item.options?.type === 'comparison' ? [] : [ { group: item.group, index } ]
+	);
+	const primaryByGroup = new Map( primaries.map( ( { group, index } ) => [ group, index ] ) );
+	const onlyPrimary = primaries.length === 1 ? primaries[ 0 ].index : undefined;
+	const pairs = new Map< number, number >();
+
+	series.forEach( ( item, index ) => {
+		const primary =
+			item.options?.type === 'comparison'
+				? ( primaryByGroup.get( item.group ) ?? onlyPrimary )
+				: undefined;
+
+		if ( primary !== undefined ) {
+			pairs.set( index, primary );
+		}
+	} );
+
+	return pairs;
+}
+
+/**
+ * The colors a grouped bar chart fills its series with. A comparison takes the lightest tint of its primary's color that keeps 3:1 against the background, and the primary in front of it the shade that keeps 3:1 against that tint. A primary with its own `stroke` keeps it, and a comparison with its own, different `stroke` keeps the pair's colors as given.
+ *
+ * @param series     - The chart's series.
+ * @param colors     - Each series' resolved color.
+ * @param background - The hex chart background.
+ * @return Each series' fill, by index.
+ */
+export function getGroupedBarColors(
+	series: SeriesData[],
+	colors: string[],
+	background: string
+): string[] {
+	const barColors = [ ...colors ];
+
+	getComparisonPrimaries( series ).forEach( ( primary, comparison ) => {
+		const base = colors[ primary ];
+		const hasOwnColor =
+			!! series[ comparison ].options?.stroke &&
+			colors[ comparison ].toLowerCase() !== base.toLowerCase();
+
+		// A paint such as `currentColor` or `url(#gradient)` cannot be toned, so the pair keeps the colors it was given.
+		if ( hasOwnColor || ! isValidHexColor( base ) || ! isValidHexColor( background ) ) {
+			return;
+		}
+
+		const tint = tintWithContrast( base, background );
+		barColors[ comparison ] = tint;
+
+		if ( ! series[ primary ].options?.stroke ) {
+			barColors[ primary ] = shadeWithContrast( base, tint, background );
+		}
+	} );
+
+	return barColors;
+}

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

@@ -1,6 +1,12 @@
 export { useBarChartOptions } from './use-bar-chart-options';
 export { TruncatedXTickComponent, TruncatedYTickComponent } from './truncated-tick-component';
 export { default as ClassifiedBarSeries } from './classified-bar-series';
+export { default as SlottedBarSeries } from './slotted-bar-series';
+export { BarLayer } from './bar-layer';
+export { SelectedBarRing, type SelectedBar } from './selected-bar-ring';
+export { SlotTooltipMembers, type SlotMember } from './slot-tooltip-members';
+export { useOverlapSlots, getSelectedSlot, isSameCategory, membersAt } from './use-overlap-slots';
+export { useBarStops } from './use-bar-stops';
 export { ComparisonBars } from './comparison-bars';
 export type { ComparisonSeriesEntry } from './comparison-bars';
 export {
@@ -10,6 +16,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 { isBarRendered } from './value-domain';
 export { BandHighlight } from './band-highlight';
 export { BandTooltip } from './band-tooltip';