@automattic/charts 4.12.0 → 4.14.0

package/src/charts/conversion-funnel-chart/test/use-funnel-selection.test.ts

@@ -2,205 +2,40 @@ import { act, renderHook } from '@testing-library/react';
 import { useFunnelSelection } from '../private/use-funnel-selection';
 
 describe( 'useFunnelSelection', () => {
-	describe( 'Initial State', () => {
-		it( 'starts with no step selected', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
+	it( 'starts with no step selected', () => {
+		const { result } = renderHook( () => useFunnelSelection() );
 
-			const stepState = result.current.getStepState( 'test-step' );
-			expect( stepState.isClicked ).toBe( false );
-			expect( stepState.isBlurred ).toBe( false );
+		expect( result.current.getStepState( 'cart' ) ).toEqual( {
+			isSelected: false,
+			isBlurred: false,
 		} );
 	} );
 
-	describe( 'Bar Click Handling', () => {
-		it( 'selects a step when bar is clicked', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
+	it( 'selects one step and blurs the others', () => {
+		const { result } = renderHook( () => useFunnelSelection() );
 
-			act( () => {
-				result.current.handleBarClick( 'test-step' );
-			} );
+		act( () => result.current.selectStep( 'sessions' ) );
+		act( () => result.current.selectStep( 'cart' ) );
 
-			const stepState = result.current.getStepState( 'test-step' );
-			expect( stepState.isClicked ).toBe( true );
-			expect( stepState.isBlurred ).toBe( false );
+		expect( result.current.getStepState( 'cart' ) ).toEqual( {
+			isSelected: true,
+			isBlurred: false,
 		} );
-
-		it( 'blurs other steps when one is selected', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
-
-			act( () => {
-				result.current.handleBarClick( 'selected-step' );
-			} );
-
-			const selectedState = result.current.getStepState( 'selected-step' );
-			const otherState = result.current.getStepState( 'other-step' );
-
-			expect( selectedState.isClicked ).toBe( true );
-			expect( selectedState.isBlurred ).toBe( false );
-			expect( otherState.isClicked ).toBe( false );
-			expect( otherState.isBlurred ).toBe( true );
-		} );
-
-		it( 'deselects step when clicking the same bar again', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
-
-			// First click to select
-			act( () => {
-				result.current.handleBarClick( 'test-step' );
-			} );
-
-			let stepState = result.current.getStepState( 'test-step' );
-			expect( stepState.isClicked ).toBe( true );
-
-			// Second click to deselect
-			act( () => {
-				result.current.handleBarClick( 'test-step' );
-			} );
-
-			stepState = result.current.getStepState( 'test-step' );
-			expect( stepState.isClicked ).toBe( false );
-			expect( stepState.isBlurred ).toBe( false );
-		} );
-
-		it( 'switches selection when clicking different bar', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
-
-			// Select first step
-			act( () => {
-				result.current.handleBarClick( 'step1' );
-			} );
-
-			// Select second step
-			act( () => {
-				result.current.handleBarClick( 'step2' );
-			} );
-
-			const step1State = result.current.getStepState( 'step1' );
-			const step2State = result.current.getStepState( 'step2' );
-
-			expect( step1State.isClicked ).toBe( false );
-			expect( step1State.isBlurred ).toBe( true );
-			expect( step2State.isClicked ).toBe( true );
-			expect( step2State.isBlurred ).toBe( false );
-		} );
-	} );
-
-	describe( 'Keyboard Handling', () => {
-		it( 'selects step on Enter key', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
-			const mockEvent = {
-				key: 'Enter',
-				preventDefault: jest.fn(),
-				stopPropagation: jest.fn(),
-			} as unknown as React.KeyboardEvent;
-
-			act( () => {
-				result.current.handleBarKeyDown( 'test-step', mockEvent );
-			} );
-
-			const stepState = result.current.getStepState( 'test-step' );
-			expect( stepState.isClicked ).toBe( true );
-			expect( mockEvent.preventDefault ).toHaveBeenCalled();
-			// Note: stopPropagation is not called in keyboard handler
-		} );
-
-		it( 'selects step on Space key', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
-			const mockEvent = {
-				key: ' ',
-				preventDefault: jest.fn(),
-				stopPropagation: jest.fn(),
-			} as unknown as React.KeyboardEvent;
-
-			act( () => {
-				result.current.handleBarKeyDown( 'test-step', mockEvent );
-			} );
-
-			const stepState = result.current.getStepState( 'test-step' );
-			expect( stepState.isClicked ).toBe( true );
-			expect( mockEvent.preventDefault ).toHaveBeenCalled();
-			// Note: stopPropagation is not called in keyboard handler
-		} );
-
-		it( 'ignores other keys', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
-			const mockEvent = {
-				key: 'Tab',
-				preventDefault: jest.fn(),
-				stopPropagation: jest.fn(),
-			} as unknown as React.KeyboardEvent;
-
-			act( () => {
-				result.current.handleBarKeyDown( 'test-step', mockEvent );
-			} );
-
-			const stepState = result.current.getStepState( 'test-step' );
-			expect( stepState.isClicked ).toBe( false );
-			expect( mockEvent.preventDefault ).not.toHaveBeenCalled();
-			expect( mockEvent.stopPropagation ).not.toHaveBeenCalled();
-		} );
-	} );
-
-	describe( 'Clear Selection', () => {
-		it( 'clears selection when clearSelection is called', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
-
-			// First select a step
-			act( () => {
-				result.current.handleBarClick( 'test-step' );
-			} );
-
-			let stepState = result.current.getStepState( 'test-step' );
-			expect( stepState.isClicked ).toBe( true );
-
-			// Clear selection
-			act( () => {
-				result.current.clearSelection();
-			} );
-
-			stepState = result.current.getStepState( 'test-step' );
-			expect( stepState.isClicked ).toBe( false );
-			expect( stepState.isBlurred ).toBe( false );
+		expect( result.current.getStepState( 'sessions' ) ).toEqual( {
+			isSelected: false,
+			isBlurred: true,
 		} );
 	} );
 
-	describe( 'getStepState', () => {
-		it( 'returns correct state for unselected steps', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
-
-			const stepState = result.current.getStepState( 'test-step' );
-			expect( stepState ).toEqual( {
-				isClicked: false,
-				isBlurred: false,
-			} );
-		} );
-
-		it( 'returns correct state for selected step', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
+	it( 'clears the selection and hides the tooltip', () => {
+		const hideTooltip = jest.fn();
+		const { result } = renderHook( () => useFunnelSelection( hideTooltip ) );
 
-			act( () => {
-				result.current.handleBarClick( 'selected-step' );
-			} );
+		act( () => result.current.selectStep( 'cart' ) );
+		act( () => result.current.clearSelection() );
 
-			const stepState = result.current.getStepState( 'selected-step' );
-			expect( stepState ).toEqual( {
-				isClicked: true,
-				isBlurred: false,
-			} );
-		} );
-
-		it( 'returns correct state for blurred steps', () => {
-			const { result } = renderHook( () => useFunnelSelection() );
-
-			act( () => {
-				result.current.handleBarClick( 'selected-step' );
-			} );
-
-			const blurredStepState = result.current.getStepState( 'other-step' );
-			expect( blurredStepState ).toEqual( {
-				isClicked: false,
-				isBlurred: true,
-			} );
-		} );
+		expect( result.current.selectedStepId ).toBeNull();
+		expect( result.current.getStepState( 'sessions' ).isBlurred ).toBe( false );
+		expect( hideTooltip ).toHaveBeenCalled();
 	} );
 } );

package/src/charts/conversion-funnel-chart/types.ts

@@ -42,12 +42,32 @@ export interface MainMetricRenderProps {
 	changeColor?: string;
 }
 
+/**
+ * A labeled line in a funnel step's tooltip
+ */
+export interface FunnelTooltipRow {
+	label: string;
+	value: string;
+}
+
+/**
+ * What a funnel step's tooltip shows below or beside the step's name. Screen readers read the same content after the name.
+ */
+export interface FunnelTooltipContent {
+	/** Shown on the name's line, e.g. the step's count */
+	value?: string;
+	/** Labeled lines below the name */
+	rows?: FunnelTooltipRow[];
+}
+
 /**
  * Render prop for customizing tooltip content
  */
 export interface TooltipRenderProps {
 	step: FunnelStep;
 	index: number;
+	/** The step's tooltip content. Screen readers read the whole rendered tooltip as the step's description. */
+	content: FunnelTooltipContent;
 	top: number;
 	left: number;
 	/** @deprecated The tooltip box draws the package surface; this is no longer set. */
@@ -81,6 +101,8 @@ export interface ConversionFunnelChartProps extends Pick<
 	renderMainMetric?: ( props: MainMetricRenderProps ) => React.ReactNode;
 	/** Custom render function for tooltip content */
 	renderTooltip?: ( props: TooltipRenderProps ) => React.ReactNode;
+	/** What each step's tooltip shows, which screen readers also read after the step's name. Defaults to the count and the conversion rate. */
+	getTooltipContent?: ( step: FunnelStep, index: number ) => FunnelTooltipContent;
 	/** Inline styles merged over the tooltip box defaults. */
 	tooltipStyle?: React.CSSProperties;
 }

package/src/charts/leaderboard-chart/leaderboard-chart.module.scss

@@ -49,7 +49,13 @@
 		}
 
 		.label {
-			padding-left: var(--wpds-dimension-padding-sm);
+			padding-inline-start: var(--a8c-charts-dimension-leaderboard-label-inset);
+		}
+
+		// The bar's 100% height needs a track that fills the row,
+		// not one sized to its content.
+		.barTrack {
+			align-self: stretch;
 		}
 	}
 
@@ -74,6 +80,20 @@
 				var(--a8c-charts-motion-easing-entrance) both;
 		}
 
+		// Grows from zero, which is its inline-end edge.
+		&--negative {
+			transform-origin: right;
+		}
+
+		// transform-origin has no logical keywords, so mirror both origins in RTL.
+		[dir="rtl"] &--animated {
+			transform-origin: right;
+		}
+
+		[dir="rtl"] &--negative {
+			transform-origin: left;
+		}
+
 		@keyframes stretch {
 
 			from {
@@ -85,11 +105,31 @@
 			}
 		}
 	}
+
+	.barTrack {
+		display: grid;
+
+		.bar {
+			grid-column: 2;
+			justify-self: start;
+		}
+
+		.bar--negative {
+			grid-column: 1;
+			justify-self: end;
+		}
+	}
 }
 
+// Spans the row's value and delta tracks and lays its cells out on them, so
+// the values and the deltas each end on their own column edge whatever width
+// the other takes.
 .valueContainer {
+	display: grid;
+	grid-column: 2 / -1;
+	grid-template-columns: subgrid;
 	align-items: center;
-	justify-content: flex-end;
+	justify-items: end;
 }
 
 .deltaValue {

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

@@ -23,6 +23,10 @@ import { getAllHiddenMessage } from '../private/svg-empty-state';
 import { withResponsive } from '../private/with-responsive';
 import { useFittedRowCount, useLeaderboardLegendItems } from './hooks';
 import styles from './leaderboard-chart.module.scss';
+import {
+	resolveLeaderboardEntries,
+	type ResolvedLeaderboardEntry,
+} from './private/resolve-leaderboard-entries';
 import type { LeaderboardChartProps } from './types';
 import type { LeaderboardEntry } from '../../types';
 
@@ -75,15 +79,15 @@ const getBarWidth = ( share: number ): string =>
 	`calc(${ share }% - var(--a8c-charts-dimension-leaderboard-bar-hover-inset, 0px) * ${ share } / 100)`;
 
 const hasPreviousValue = (
-	entry: LeaderboardEntry
-): entry is LeaderboardEntry & {
+	entry: ResolvedLeaderboardEntry
+): entry is ResolvedLeaderboardEntry & {
 	previousValue: number;
 	previousShare: number;
 } => entry.previousValue != null && entry.previousShare != null;
 
 const hasDeltaValue = (
-	entry: LeaderboardEntry
-): entry is LeaderboardEntry & {
+	entry: ResolvedLeaderboardEntry
+): entry is ResolvedLeaderboardEntry & {
 	previousValue: number;
 	previousShare: number;
 	delta: number;
@@ -107,6 +111,56 @@ const BarLabel = ( { label }: { label: LeaderboardEntry[ 'label' ] } ) => (
 	<>{ typeof label === 'string' ? <Text className={ styles.label }>{ label }</Text> : label }</>
 );
 
+/** The largest negative and positive share magnitudes, which size each side of zero. */
+type DivergingScale = { negative: number; positive: number };
+
+const Bar = ( {
+	share,
+	color,
+	animation,
+	divergingScale,
+}: {
+	share: number;
+	color: string;
+	animation?: boolean;
+	divergingScale?: DivergingScale;
+} ) => {
+	const isNegative = share < 0;
+	const sideMax = divergingScale?.[ isNegative ? 'negative' : 'positive' ];
+	// A diverging bar is measured against the largest share on its own side of zero.
+	const width = sideMax ? ( Math.abs( share ) / sideMax ) * 100 : Math.abs( share );
+
+	const bar = (
+		<div
+			data-testid="leaderboard-chart-bar"
+			className={ clsx( styles.bar, {
+				[ styles[ 'bar--animated' ] ]: animation,
+				[ styles[ 'bar--negative' ] ]: divergingScale && isNegative,
+			} ) }
+			style={ {
+				width: getBarWidth( width ),
+				backgroundColor: color,
+			} }
+		></div>
+	);
+
+	if ( ! divergingScale ) {
+		return bar;
+	}
+
+	// Each side is as wide as its share of the full range, so zero sits where the range crosses it.
+	return (
+		<div
+			className={ styles.barTrack }
+			style={ {
+				gridTemplateColumns: `${ divergingScale.negative }fr ${ divergingScale.positive }fr`,
+			} }
+		>
+			{ bar }
+		</div>
+	);
+};
+
 const BarWithLabel = ( {
 	entry,
 	withComparison,
@@ -114,51 +168,53 @@ const BarWithLabel = ( {
 	primaryColor,
 	secondaryColor,
 	animation,
+	divergingScale,
 	isPrimaryVisible = true,
 	isComparisonVisible = true,
 }: {
-	entry: LeaderboardEntry;
+	entry: ResolvedLeaderboardEntry;
 	withComparison?: boolean;
 	withOverlayLabel?: boolean;
 	primaryColor: string;
 	secondaryColor: string;
+	divergingScale?: DivergingScale;
 	isPrimaryVisible?: boolean;
 	isComparisonVisible?: boolean;
 	animation?: boolean;
 } ) => {
 	const showComparisonBar = withComparison && ! withOverlayLabel && isComparisonVisible;
 
+	const bars = (
+		<>
+			{ isPrimaryVisible && (
+				<Bar
+					share={ entry.currentShare }
+					color={ primaryColor }
+					animation={ animation }
+					divergingScale={ divergingScale }
+				/>
+			) }
+
+			{ showComparisonBar && hasPreviousValue( entry ) && (
+				<Bar
+					share={ entry.previousShare }
+					color={ secondaryColor }
+					animation={ animation }
+					divergingScale={ divergingScale }
+				/>
+			) }
+		</>
+	);
+
 	return (
 		<div
 			className={ clsx( styles.barWithLabelContainer, {
 				[ styles[ 'is-overlay' ] ]: withOverlayLabel,
 			} ) }
+			data-testid={ divergingScale ? 'leaderboard-chart-diverging-row' : undefined }
 		>
 			<BarLabel label={ entry.label } />
-
-			{ isPrimaryVisible && (
-				<div
-					className={ clsx( styles.bar, {
-						[ styles[ 'bar--animated' ] ]: animation,
-					} ) }
-					style={ {
-						width: getBarWidth( entry.currentShare ),
-						backgroundColor: primaryColor,
-					} }
-				></div>
-			) }
-
-			{ showComparisonBar && hasPreviousValue( entry ) && (
-				<div
-					className={ clsx( styles.bar, {
-						[ styles[ 'bar--animated' ] ]: animation,
-					} ) }
-					style={ {
-						width: getBarWidth( entry.previousShare ),
-						backgroundColor: secondaryColor,
-					} }
-				></div>
-			) }
+			{ bars }
 		</div>
 	);
 };
@@ -174,6 +230,7 @@ const BarWithLabel = ( {
  * @param props.height           - Optional height of the chart container in pixels
  * @param props.withComparison   - Whether to show comparison data
  * @param props.withOverlayLabel - Whether to overlay the label on top of the bar
+ * @param props.negativeBars     - How a negative value draws: from a shared zero point, or as an empty bar
  * @param props.primaryColor     - Primary color for current period bars
  * @param props.secondaryColor   - Secondary color for comparison period bars
  * @param props.valueFormatter   - Custom formatter for values
@@ -198,6 +255,7 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 	height: propHeight,
 	withComparison = false,
 	withOverlayLabel = false,
+	negativeBars = 'diverge',
 	primaryColor,
 	secondaryColor,
 	valueFormatter = defaultValueFormatter,
@@ -267,6 +325,33 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 		return ! isPrimaryVisible;
 	}, [ isPrimaryVisible, isComparisonVisible, withComparison, withOverlayLabel ] );
 
+	const withComparisonBars = withComparison && ! withOverlayLabel;
+
+	const resolvedData = useMemo(
+		() =>
+			resolveLeaderboardEntries( data ?? [], {
+				includePrevious: withComparisonBars,
+				clampNegative: negativeBars === 'clamp',
+			} ),
+		[ data, withComparisonBars, negativeBars ]
+	);
+
+	// One negative share puts every row on a shared zero point, so the bars stay comparable.
+	const divergingScale = useMemo( (): DivergingScale | undefined => {
+		const scale = { negative: 0, positive: 0 };
+		for ( const entry of resolvedData ) {
+			const shares = [ entry.currentShare ];
+			if ( withComparisonBars && hasPreviousValue( entry ) ) {
+				shares.push( entry.previousShare );
+			}
+			for ( const share of shares ) {
+				const side = share < 0 ? 'negative' : 'positive';
+				scale[ side ] = Math.max( scale[ side ], Math.abs( share ) );
+			}
+		}
+		return scale.negative > 0 ? scale : undefined;
+	}, [ resolvedData, withComparisonBars ] );
+
 	// Validate data
 	const isDataValid = Boolean( data && data.length > 0 );
 
@@ -300,6 +385,11 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 		data
 	);
 	const shouldFitRows = fitRows && isMeasurable;
+	// Comparing adds a delta track so the values and the deltas each line up in a column
+	// of their own; with either series hidden the grid keeps its two tracks.
+	const showComparisonColumn = withComparison && isComparisonVisible;
+	const templateColumns =
+		showComparisonColumn && isPrimaryVisible ? 'minmax(0, 1fr) auto auto' : 'minmax(0, 1fr) auto';
 
 	// Handle empty or undefined data
 	if ( ! data || data.length === 0 ) {
@@ -393,12 +483,12 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 						<Grid
 							role="list"
 							aria-label={ ariaLabel ?? __( 'Leaderboard chart', 'jetpack-charts' ) }
-							templateColumns="minmax(0, 1fr) auto"
+							templateColumns={ templateColumns }
 							rowGap={ ROW_GAP }
 							columnGap={ COLUMN_GAP }
 							data-leaderboard-grid
 						>
-							{ data.map( ( entry, rowIndex ) => {
+							{ resolvedData.map( ( entry, rowIndex ) => {
 								// visibility, not clipping: hidden rows keep their geometry (so a
 								// taller container can reveal them) but leave hit testing, focus,
 								// and the accessibility tree.
@@ -406,7 +496,6 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 									shouldFitRows && rowIndex >= fittedCount
 										? ( { visibility: 'hidden' } as const )
 										: undefined;
-								const showComparisonColumn = withComparison && isComparisonVisible;
 								const hasPreviousPeriodValue = hasPreviousValue( entry );
 								const hasDelta = hasDeltaValue( entry );
 								const showComparisonValue = showComparisonColumn && hasDelta;
@@ -426,15 +515,14 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 												withOverlayLabel={ withOverlayLabel }
 												primaryColor={ resolvedPrimaryColor }
 												secondaryColor={ resolvedSecondaryColor }
+												divergingScale={ divergingScale }
 												isPrimaryVisible={ isPrimaryVisible }
 												isComparisonVisible={ isComparisonVisible }
 												animation={ animation && ! loading && ! prefersReducedMotion }
 											/>
 										</Stack>
 
-										<Stack
-											direction="row"
-											gap="xs"
+										<div
 											className={ clsx( styles.valueContainer, {
 												[ styles.overlayLabel ]: withOverlayLabel,
 											} ) }
@@ -463,7 +551,7 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 													</VisuallyHidden>
 												</Text>
 											) }
-										</Stack>
+										</div>
 									</>
 								);
 

package/src/charts/leaderboard-chart/private/resolve-leaderboard-entries.ts

@@ -0,0 +1,53 @@
+import type { LeaderboardEntry } from '../../../types';
+
+export type ResolvedLeaderboardEntry = LeaderboardEntry & { currentShare: number };
+
+const toShare = ( value: number, max: number ) => ( max === 0 ? 0 : ( value / max ) * 100 );
+
+const toDelta = ( currentValue: number, previousValue: number | undefined ) => {
+	if ( previousValue == null ) {
+		return undefined;
+	}
+	if ( previousValue === 0 ) {
+		return currentValue === 0 ? 0 : undefined;
+	}
+	return ( ( currentValue - previousValue ) / Math.abs( previousValue ) ) * 100;
+};
+
+/**
+ * Fills in the shares and delta an entry omits, derived from its values.
+ *
+ * @param data                    - Leaderboard entries; passed shares and delta win over derived ones.
+ * @param options                 - Resolver options.
+ * @param options.includePrevious - Whether previous values count toward the shared max.
+ * @param options.clampNegative   - Whether a negative share draws as an empty bar instead of below zero.
+ * @return Entries with `currentShare` always set.
+ */
+export function resolveLeaderboardEntries(
+	data: LeaderboardEntry[],
+	{ includePrevious, clampNegative = false }: { includePrevious: boolean; clampNegative?: boolean }
+): ResolvedLeaderboardEntry[] {
+	const magnitude = clampNegative ? ( value: number ) => Math.max( value, 0 ) : Math.abs;
+	const clamp = ( share: number ) => ( clampNegative ? Math.max( share, 0 ) : share );
+
+	const max = data.reduce( ( largest, { currentValue, previousValue } ) => {
+		const previous = includePrevious && previousValue != null ? magnitude( previousValue ) : 0;
+		return Math.max( largest, magnitude( currentValue ), previous );
+	}, 0 );
+
+	return data.map( entry => {
+		const passedOrDerivedPrevious =
+			entry.previousShare ??
+			( entry.previousValue != null ? toShare( entry.previousValue, max ) : undefined );
+		const previousShare =
+			passedOrDerivedPrevious !== undefined ? clamp( passedOrDerivedPrevious ) : undefined;
+		const delta = entry.delta ?? toDelta( entry.currentValue, entry.previousValue );
+
+		return {
+			...entry,
+			currentShare: clamp( entry.currentShare ?? toShare( entry.currentValue, max ) ),
+			...( previousShare !== undefined && { previousShare } ),
+			...( delta !== undefined && { delta } ),
+		};
+	} );
+}