@automattic/charts 4.11.1 → 4.13.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

@@ -51,6 +51,12 @@
 		.label {
 			padding-left: var(--wpds-dimension-padding-sm);
 		}
+
+		// The bar's 100% height needs a track that fills the row,
+		// not one sized to its content.
+		.barTrack {
+			align-self: stretch;
+		}
 	}
 
 	.bar {
@@ -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

@@ -107,6 +107,55 @@ 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
+			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,6 +163,7 @@ const BarWithLabel = ( {
 	primaryColor,
 	secondaryColor,
 	animation,
+	divergingScale,
 	isPrimaryVisible = true,
 	isComparisonVisible = true,
 }: {
@@ -122,43 +172,44 @@ const BarWithLabel = ( {
 	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>
 	);
 };
@@ -267,6 +318,23 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 		return ! isPrimaryVisible;
 	}, [ isPrimaryVisible, isComparisonVisible, withComparison, withOverlayLabel ] );
 
+	// One negative share puts every row on a shared zero point, so the bars stay comparable.
+	const divergingScale = useMemo( (): DivergingScale | undefined => {
+		const withComparisonBars = withComparison && ! withOverlayLabel;
+		const scale = { negative: 0, positive: 0 };
+		for ( const entry of data ?? [] ) {
+			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;
+	}, [ data, withComparison, withOverlayLabel ] );
+
 	// Validate data
 	const isDataValid = Boolean( data && data.length > 0 );
 
@@ -300,6 +368,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,7 +466,7 @@ 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
@@ -406,7 +479,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 +498,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 +534,7 @@ const LeaderboardChartInternal: FC< LeaderboardChartProps > = ( {
 													</VisuallyHidden>
 												</Text>
 											) }
-										</Stack>
+										</div>
 									</>
 								);
 

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

@@ -152,6 +152,24 @@ describe( 'LeaderboardChart', () => {
 		expect( container.querySelectorAll( '.bar' ) ).toHaveLength( 2 );
 	} );
 
+	it.each( [
+		[ 'a current share is negative', { currentShare: -40 }, true, 2 ],
+		[ 'a comparison share is negative', { previousShare: -40 }, true, 2 ],
+		[ 'only a hidden comparison share is negative', { previousShare: -40 }, false, 0 ],
+		[
+			'only a share without a comparison value is negative',
+			{ previousShare: -40, previousValue: undefined },
+			true,
+			0,
+		],
+		[ 'every share is positive', {}, true, 0 ],
+	] )( 'diverges the bars from zero when %s', ( _, override, withComparison, expected ) => {
+		const data = [ { ...mockData[ 0 ], ...override }, mockData[ 1 ] ];
+		render( <LeaderboardChart data={ data } withComparison={ withComparison } /> );
+
+		expect( screen.queryAllByTestId( 'leaderboard-chart-diverging-row' ) ).toHaveLength( expected );
+	} );
+
 	it( 'shows custom label when provided', () => {
 		render(
 			<LeaderboardChart
@@ -748,6 +766,35 @@ describe( 'LeaderboardChart', () => {
 	describe( 'grid gaps', () => {
 		// eslint-disable-next-line testing-library/no-node-access -- The grid is rendered by `Grid` from @wordpress/components, which takes no test id.
 		const grid = () => document.querySelector< HTMLElement >( '[data-leaderboard-grid]' );
+		const templateColumns = () =>
+			grid().style.getPropertyValue( '--wp-components-grid-template-columns' );
+
+		it( 'lays the rows out without a delta track when not comparing', () => {
+			render( <LeaderboardChart data={ mockData } withComparison={ false } /> );
+
+			expect( templateColumns() ).toBe( 'minmax(0, 1fr) auto' );
+		} );
+
+		it.each( [ [ 'Previous period' ], [ 'Current period' ] ] )(
+			'adds a delta track when comparing and drops it while "%s" is hidden',
+			async legendItem => {
+				const user = userEvent.setup();
+				render(
+					<LeaderboardChart
+						data={ mockData }
+						withComparison={ true }
+						showLegend={ true }
+						legend={ { interactive: true } }
+					/>
+				);
+
+				expect( templateColumns() ).toBe( 'minmax(0, 1fr) auto auto' );
+
+				await user.click( screen.getByRole( 'button', { name: new RegExp( legendItem ) } ) );
+
+				expect( templateColumns() ).toBe( 'minmax(0, 1fr) auto' );
+			}
+		);
 
 		it( 'hands the catalog role to the grid', () => {
 			render( <LeaderboardChart data={ mockData } /> );