@automattic/charts 4.11.0 → 4.12.0

package/src/charts/bar-chart/private/slot-tooltip-members.tsx

@@ -0,0 +1,29 @@
+import { TooltipContext } from '@visx/xychart';
+import { useContext, useEffect } from 'react';
+import type { DataPointDate } from '../../../types';
+
+/** A bar at the keyboard-selected category. */
+export type SlotMember = { key: string; datum: DataPointDate };
+
+/**
+ * Fills the tooltip with every bar of the keyboard-selected category, and only those.
+ *
+ * The last member shown becomes the tooltip's nearest datum, so the caller lists the keyboard stop last.
+ *
+ * @param props         - Component props.
+ * @param props.members - The category's bars, the keyboard stop last.
+ * @param props.index   - The selected data point.
+ * @return No visual content.
+ */
+export function SlotTooltipMembers( { members, index }: { members: SlotMember[]; index: number } ) {
+	const { showTooltip, updateTooltip } = useContext( TooltipContext ) ?? {};
+
+	useEffect( () => {
+		updateTooltip?.( state => ( { ...state, tooltipData: undefined } ) );
+		members.forEach( ( { key, datum } ) => showTooltip?.( { key, datum, index } ) );
+		// `showTooltip` and `updateTooltip` are stable; the context object is not.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [ members, index ] );
+
+	return null;
+}

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

@@ -0,0 +1,84 @@
+import { DataContext, GlyphSeries } from '@visx/xychart';
+import clsx from 'clsx';
+import { useCallback, useContext, useMemo } from 'react';
+import { createGroupScale } from './band-scale';
+import { computeSlotRect, 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?: BarChartProps[ 'barClassName' ];
+	/** The slots of a category, in the order the band lays them out. */
+	slotKeys: string[];
+	/** The slot the bars sit in. */
+	slotKey: string;
+	/** The bars' thickness as a share of the slot, centered in it. */
+	thickness: number;
+	groupPadding: number;
+};
+
+const SlottedBarSeries = ( {
+	barClassName,
+	slotKeys,
+	slotKey,
+	thickness,
+	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( slotKeys, bandScale?.bandwidth?.() ?? 0, groupPadding ),
+		[ slotKeys, bandScale, groupPadding ]
+	);
+	const renderGlyph = useCallback(
+		( { datum, x, y, color }: GlyphProps< DataPointDate > ) => {
+			if ( ! bandScale?.bandwidth || ! valueScale ) return null;
+			const baseline = getValueScaleBaseline(
+				valueScale as Parameters< typeof getValueScaleBaseline >[ 0 ]
+			);
+			const rect = computeSlotRect( {
+				horizontal: !! horizontal,
+				bandPosition: Number(
+					bandScale( ( horizontal ? props.yAccessor : props.xAccessor )( datum ) )
+				),
+				slotOffset: groupScale( slotKey ) ?? 0,
+				slotThickness: groupScale.bandwidth(),
+				valuePositions: [ baseline, horizontal ? x : y ],
+				widthFactor: thickness,
+			} );
+			return (
+				<rect
+					{ ...rect }
+					className={ clsx( 'visx-bar', barClassName?.( datum ) ) }
+					fill={ color }
+				/>
+			);
+		},
+		[
+			bandScale,
+			valueScale,
+			horizontal,
+			groupScale,
+			slotKey,
+			thickness,
+			props.xAccessor,
+			props.yAccessor,
+			barClassName,
+		]
+	);
+	// BandTooltip owns pointer selection: these handlers subscribe after it and would rank bars by their tops, not their slots.
+	return <GlyphSeries { ...props } enableEvents={ false } renderGlyph={ renderGlyph } />;
+};
+
+export default SlottedBarSeries;

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

@@ -1,4 +1,4 @@
-import { computeComparisonRect, getValueScaleBaseline } from '../comparison-bars-geometry';
+import { computeSlotRect, getValueScaleBaseline } from '../comparison-bars-geometry';
 
 describe( 'getValueScaleBaseline', () => {
 	it( 'clamps to the bottom (range max) when 0 is below the domain (vertical, descending range)', () => {
@@ -17,29 +17,22 @@ describe( 'getValueScaleBaseline', () => {
 	} );
 } );
 
-describe( 'computeComparisonRect', () => {
+describe( 'computeSlotRect', () => {
 	const base = {
 		bandPosition: 100,
 		slotOffset: 10,
 		slotThickness: 40,
-		valuePosition: 50,
-		baseline: 200,
 		widthFactor: 1.5,
 	};
 
 	it( 'centers a 150% wide shadow on the primary slot (vertical)', () => {
-		const r = computeComparisonRect( { ...base, horizontal: false } );
+		const r = computeSlotRect( { ...base, horizontal: false, valuePositions: [ 200, 50 ] } );
 		// slotStart=110, center=110+20=130, shadowThickness=60, shadowStart=130-30=100
 		expect( r ).toEqual( { x: 100, y: 50, width: 60, height: 150 } );
 	} );
 
 	it( 'centers a 150% tall shadow on the primary slot (horizontal)', () => {
-		const r = computeComparisonRect( {
-			...base,
-			horizontal: true,
-			valuePosition: 150,
-			baseline: 0,
-		} );
+		const r = computeSlotRect( { ...base, horizontal: true, valuePositions: [ 0, 150 ] } );
 		// slotStart=110, center=130, shadowThickness=60, shadowStart=100
 		expect( r ).toEqual( { x: 0, y: 100, width: 150, height: 60 } );
 	} );

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

@@ -56,12 +56,12 @@ const seriesData: SeriesData = {
 };
 
 const comparisonEntries: ComparisonSeriesEntry[] = [
-	{ series: seriesData, index: 0, primaryKey: 'current', primaryIndex: 0 },
+	{ series: seriesData, index: 0, primaryKey: 'current' },
 ];
 
 const getElementStyles = () => ( {
 	color: '#f00',
-	barStyles: { widthFactor: 1.5, opacity: 0.5 },
+	barStyles: { widthFactor: 1.5 },
 	lineStyles: {} as never,
 	glyph: undefined as never,
 	shapeStyles: {} as never,
@@ -94,7 +94,6 @@ describe( 'ComparisonBars', () => {
 		const rects = screen.getAllByTestId( /^bar-chart-comparison-0-/ );
 		expect( rects ).toHaveLength( 2 );
 		expect( rects[ 0 ] ).toHaveAttribute( 'fill', '#f00' );
-		expect( rects[ 0 ] ).toHaveAttribute( 'opacity', '0.5' );
 		// width == widthFactor (1.5) * groupScale.bandwidth()
 		expect( Number( rects[ 0 ].getAttribute( 'width' ) ) ).toBeCloseTo(
 			1.5 * groupScale.bandwidth()

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

@@ -0,0 +1,87 @@
+import { contrastRatio } from '../../../../providers/chart-context/private/perceptual-color';
+import { getGroupedBarColors } from '../grouped-bars';
+import { tintWithContrast } from '../overlap-bars';
+import type { SeriesData } from '../../../../types';
+
+const series = ( label: string, group?: string, options: SeriesData[ 'options' ] = {} ) => ( {
+	label,
+	group,
+	data: [],
+	options,
+} );
+
+const BLUE = '#3858e9';
+const GREEN = '#008a20';
+
+describe( 'getGroupedBarColors', () => {
+	it.each( [ [ '#ffffff' ], [ '#1e1e1e' ] ] )(
+		'tints each comparison to 3:1 against %s and keeps its primary at 3:1 against the tint',
+		background => {
+			const data = [
+				series( 'Views', 'views' ),
+				series( 'Previous views', 'views', { type: 'comparison' } ),
+				series( 'Visitors', 'visitors' ),
+				series( 'Previous visitors', 'visitors', { type: 'comparison' } ),
+			];
+			const [ views, previousViews, visitors, previousVisitors ] = getGroupedBarColors(
+				data,
+				[ BLUE, BLUE, GREEN, GREEN ],
+				background
+			);
+
+			for ( const [ primary, comparison ] of [
+				[ views, previousViews ],
+				[ visitors, previousVisitors ],
+			] ) {
+				expect( contrastRatio( comparison, background ) ).toBeGreaterThanOrEqual( 3 );
+				expect( contrastRatio( comparison, background ) ).toBeLessThan( 3.1 );
+				expect( contrastRatio( primary, comparison ) ).toBeGreaterThanOrEqual( 3 );
+			}
+		}
+	);
+
+	it( 'pairs a comparison without a group with the only primary', () => {
+		const [ primary, comparison ] = getGroupedBarColors(
+			[ series( 'Views' ), series( 'Previous', undefined, { type: 'comparison' } ) ],
+			[ BLUE, GREEN ],
+			'#ffffff'
+		);
+
+		expect( contrastRatio( primary, comparison ) ).toBeGreaterThanOrEqual( 3 );
+	} );
+
+	it( "keeps a primary's own stroke and tints its comparison from it", () => {
+		const [ primary, comparison ] = getGroupedBarColors(
+			[
+				series( 'Views', 'views', { stroke: '#ff0000' } ),
+				series( 'Previous', 'views', { type: 'comparison' } ),
+			],
+			[ '#ff0000', BLUE ],
+			'#ffffff'
+		);
+
+		expect( [ primary, comparison ] ).toEqual( [
+			'#ff0000',
+			tintWithContrast( '#ff0000', '#ffffff' ),
+		] );
+	} );
+
+	it.each( [
+		[
+			'a comparison stroked in a color of its own',
+			[
+				series( 'Views', 'views' ),
+				series( 'Previous', 'views', { type: 'comparison', stroke: '#dbdbdb' } ),
+			],
+			[ BLUE, '#dbdbdb' ],
+		],
+		[
+			'a primary color that is not hex',
+			[ series( 'Views', 'views' ), series( 'Previous', 'views', { type: 'comparison' } ) ],
+			[ 'currentColor', 'currentColor' ],
+		],
+		[ 'no comparison', [ series( 'Views' ), series( 'Visitors' ) ], [ BLUE, GREEN ] ],
+	] )( 'keeps the colors given with %s', ( _case, data, colors ) => {
+		expect( getGroupedBarColors( data, colors, '#ffffff' ) ).toEqual( colors );
+	} );
+} );

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

@@ -0,0 +1,159 @@
+import { contrastRatio } from '../../../../providers/chart-context/private/perceptual-color';
+import { relativeLuminance } from '../../../../utils/color-utils';
+import { getOverlapBarColors, getOverlapPlacements, tintWithContrast } from '../overlap-bars';
+import type { SeriesData } from '../../../../types';
+
+const series = ( label: string, group?: string, options: SeriesData[ 'options' ] = {} ) => ( {
+	label,
+	group,
+	data: [],
+	options,
+} );
+
+const VIEWS_AND_VISITORS: SeriesData[] = [
+	series( 'Views', 'views' ),
+	series( 'Previous views', 'views', { type: 'comparison' } ),
+	series( 'Visitors', 'visitors' ),
+	series( 'Previous visitors', 'visitors', { type: 'comparison' } ),
+];
+
+const BLUE = '#3858e9';
+const GREEN = '#008a20';
+
+describe( 'getOverlapPlacements', () => {
+	it( 'puts primaries and comparisons in their own slots, with each group a layer in order of first appearance', () => {
+		expect( getOverlapPlacements( VIEWS_AND_VISITORS ) ).toEqual( [
+			{ slot: 'primary', layer: 0, thickness: 1 },
+			{ slot: 'comparison', layer: 0, thickness: 1 },
+			{ slot: 'primary', layer: 1, thickness: 0.5 },
+			{ slot: 'comparison', layer: 1, thickness: 0.5 },
+		] );
+	} );
+
+	it.each( [
+		[ 'one group', [ series( 'Views', 'views' ) ], [ 1 ] ],
+		[
+			'three groups',
+			[ series( 'A', 'a' ), series( 'B', 'b' ), series( 'C', 'c' ) ],
+			[ 1, 0.75, 0.5 ],
+		],
+	] )( 'narrows each layer in front with %s', ( _case, data, thicknesses ) => {
+		expect( getOverlapPlacements( data ).map( ( { thickness } ) => thickness ) ).toEqual(
+			thicknesses
+		);
+	} );
+} );
+
+describe( 'getOverlapBarColors', () => {
+	const colorsOf = ( data: SeriesData[] ) =>
+		data.map( item => item.options?.stroke ?? ( item.group === 'views' ? BLUE : GREEN ) );
+
+	it.each( [
+		[ 'a light background', '#ffffff', -1 ],
+		[ 'a dark background', '#1e1e1e', 1 ],
+	] )(
+		'tints the back bar to 3:1 against %s and moves the front bar away from it to 3:1',
+		( _case, background, direction ) => {
+			const [ back, previousBack, front, previousFront ] = getOverlapBarColors(
+				VIEWS_AND_VISITORS,
+				colorsOf( VIEWS_AND_VISITORS ),
+				[ BLUE, GREEN ],
+				background
+			);
+
+			for ( const [ slotBack, slotFront ] of [
+				[ back, front ],
+				[ previousBack, previousFront ],
+			] ) {
+				expect( contrastRatio( slotBack, background ) ).toBeGreaterThanOrEqual( 3 );
+				expect( contrastRatio( slotBack, background ) ).toBeLessThan( 3.1 );
+				expect( contrastRatio( slotFront, slotBack ) ).toBeGreaterThanOrEqual( 3 );
+				expect( Math.sign( relativeLuminance( slotFront ) - relativeLuminance( slotBack ) ) ).toBe(
+					direction
+				);
+			}
+		}
+	);
+
+	it( 'turns the front bar back toward the background when the far side cannot reach 3:1', () => {
+		const background = '#686884';
+		const [ back, , front ] = getOverlapBarColors(
+			VIEWS_AND_VISITORS,
+			colorsOf( VIEWS_AND_VISITORS ),
+			[ '#9f4902', GREEN ],
+			background
+		);
+
+		expect( contrastRatio( front, back ) ).toBeGreaterThanOrEqual( 3 );
+	} );
+
+	it( "tones each slot from its palette color, not from the series' group colors", () => {
+		const toned = getOverlapBarColors(
+			VIEWS_AND_VISITORS,
+			colorsOf( VIEWS_AND_VISITORS ),
+			[ BLUE, GREEN ],
+			'#ffffff'
+		);
+		const regrouped = getOverlapBarColors(
+			VIEWS_AND_VISITORS,
+			[ '#111111', '#222222', '#333333', '#444444' ],
+			[ BLUE, GREEN ],
+			'#ffffff'
+		);
+
+		expect( regrouped ).toEqual( toned );
+	} );
+
+	it( "tones a slot from its back series' own stroke", () => {
+		const data = [
+			series( 'Views', 'views', { stroke: GREEN } ),
+			series( 'Visitors', 'visitors' ),
+		];
+		const [ back ] = getOverlapBarColors( data, [ GREEN, BLUE ], [ BLUE, BLUE ], '#ffffff' );
+
+		expect( back ).toBe( tintWithContrast( GREEN, '#ffffff' ) );
+	} );
+
+	it.each( [ BLUE, '#dbdbdb' ] )( 'tints a bar alone in its slot from %s, as a back bar', base => {
+		const [ bar ] = getOverlapBarColors(
+			[ series( 'Comments' ) ],
+			[ base ],
+			[ base, GREEN ],
+			'#ffffff'
+		);
+
+		expect( bar ).toBe( tintWithContrast( base, '#ffffff' ) );
+	} );
+
+	it.each( [
+		[
+			'a front series stroked in a color of its own',
+			[
+				series( 'Previous views', 'views', { type: 'comparison', stroke: '#dbdbdb' } ),
+				series( 'Previous visitors', 'visitors', { type: 'comparison', stroke: '#707070' } ),
+			],
+			[ '#dbdbdb', '#707070' ],
+			'#ffffff',
+		],
+		[
+			'a bar alone in its slot stroked in a color of its own',
+			[ series( 'Previous comments', 'comments', { type: 'comparison', stroke: '#dbdbdb' } ) ],
+			[ '#dbdbdb' ],
+			'#ffffff',
+		],
+		[
+			'a base that is not hex',
+			[ series( 'Views', 'views', { stroke: 'currentColor' } ), series( 'Visitors', 'visitors' ) ],
+			[ 'currentColor', BLUE ],
+			'#ffffff',
+		],
+		[
+			'a background that is not hex',
+			[ series( 'Views', 'views' ), series( 'Visitors', 'visitors' ) ],
+			[ BLUE, GREEN ],
+			'transparent',
+		],
+	] )( 'keeps the colors given with %s', ( _case, data, colors, background ) => {
+		expect( getOverlapBarColors( data, colors, [ BLUE, GREEN ], background ) ).toEqual( colors );
+	} );
+} );

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

@@ -0,0 +1,89 @@
+import { useCallback, useMemo } from 'react';
+import { isSameCategory } from './use-overlap-slots';
+import type { OverlapSlots } from './use-overlap-slots';
+import type { DataPointDate, SeriesData } from '../../../types';
+
+type SeriesEntry = { series: SeriesData; index: number };
+
+/** A bar the keyboard can stop at. */
+export type StopBar = { datum: DataPointDate; index: number; key: string };
+
+export type BarStops = {
+	count: number;
+	/** The series `XYChartTooltip` reads a stop's datum from. Overlap has none: `SlotTooltipMembers` fills its tooltip. */
+	series: SeriesData[];
+	/** Changes when the stops do, so keyboard navigation starts over. */
+	key: string;
+	barAt: ( stop: number ) => StopBar | undefined;
+	stopOf: ( key: string, dataPointIndex: number ) => number | undefined;
+};
+
+/**
+ * Lays out the keyboard stops: one per slot and category in an overlap layout, else one per primary bar, series-major within each category.
+ *
+ * @param overlapSlots   - The overlap layout, or undefined for a grouped one.
+ * @param primaryEntries - The visible primary series.
+ * @return The stops.
+ */
+export function useBarStops(
+	overlapSlots: OverlapSlots | undefined,
+	primaryEntries: SeriesEntry[]
+): BarStops {
+	const series = useMemo(
+		() => ( overlapSlots ? [] : primaryEntries.map( entry => entry.series ) ),
+		[ overlapSlots, primaryEntries ]
+	);
+
+	const count =
+		overlapSlots?.positions.length ??
+		Math.max( 0, ...series.map( item => item.data.length ) ) * series.length;
+
+	const key = useMemo(
+		() => JSON.stringify( overlapSlots?.keys ?? series.map( item => item.label ) ),
+		[ overlapSlots, series ]
+	);
+
+	const barAt = useCallback(
+		( stop: number ): StopBar | undefined => {
+			if ( overlapSlots ) {
+				const position = overlapSlots.positions[ stop ];
+				return (
+					position && {
+						datum: position.datum,
+						index: position.dataPointIndex,
+						key: position.key,
+					}
+				);
+			}
+			if ( ! series.length ) {
+				return undefined;
+			}
+			const index = Math.floor( stop / series.length );
+			const item = series[ stop % series.length ];
+			const datum = item?.data[ index ] as DataPointDate | undefined;
+			return item && datum ? { datum, index, key: item.label } : undefined;
+		},
+		[ overlapSlots, series ]
+	);
+
+	const stopOf = useCallback(
+		( seriesKey: string, dataPointIndex: number ): number | undefined => {
+			if ( overlapSlots ) {
+				const hovered = overlapSlots.entries.find( entry => entry.series.label === seriesKey )
+					?.series.data[ dataPointIndex ] as DataPointDate | undefined;
+				const slotKey = overlapSlots.slotOf( seriesKey );
+				const stop = hovered
+					? overlapSlots.positions.findIndex(
+							position => position.slotKey === slotKey && isSameCategory( position.datum, hovered )
+						)
+					: -1;
+				return stop >= 0 ? stop : undefined;
+			}
+			const seriesIndex = series.findIndex( item => item.label === seriesKey );
+			return seriesIndex >= 0 ? dataPointIndex * series.length + seriesIndex : undefined;
+		},
+		[ overlapSlots, series ]
+	);
+
+	return { count, series, key, barAt, stopOf };
+}