@automattic/charts 4.11.1 → 4.13.0

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

@@ -0,0 +1,183 @@
+import { MIN_BACKGROUND_CONTRAST } from '../../../providers/chart-context/private/palette-generator';
+import { contrastRatio } from '../../../providers/chart-context/private/perceptual-color';
+import { isValidHexColor, mixHexColors } from '../../../utils/color-utils';
+import type { SeriesData } from '../../../types';
+
+export const PRIMARY_SLOT = 'primary';
+export const COMPARISON_SLOT = 'comparison';
+
+const OVERLAP_SLOTS = [ PRIMARY_SLOT, COMPARISON_SLOT ] as const;
+
+/** Thickness of the front-most layer, as a share of its slot. */
+const FRONT_THICKNESS = 0.5;
+
+const SEARCH_STEPS = 16;
+
+/** Where a series sits in an overlap layout. */
+export type OverlapPlacement = {
+	slot: ( typeof OVERLAP_SLOTS )[ number ];
+	/** 0 for the first `group` in the data, which is drawn at the back. */
+	layer: number;
+	/** The bar's thickness as a share of its slot. */
+	thickness: number;
+};
+
+/**
+ * Places each series of an overlap layout: primaries in one slot and comparisons in the other, with each `group` a layer, back to front in order of first appearance.
+ *
+ * @param series - The series to place.
+ * @return Each series' placement, by index.
+ */
+export function getOverlapPlacements( series: SeriesData[] ): OverlapPlacement[] {
+	const layerByGroup = new Map< string | undefined, number >();
+
+	series.forEach( ( { group } ) => {
+		if ( ! layerByGroup.has( group ) ) {
+			layerByGroup.set( group, layerByGroup.size );
+		}
+	} );
+
+	const layerCount = layerByGroup.size;
+
+	return series.map( item => {
+		const layer = layerByGroup.get( item.group ) ?? 0;
+
+		return {
+			slot: item.options?.type === 'comparison' ? COMPARISON_SLOT : PRIMARY_SLOT,
+			layer,
+			thickness: layerCount > 1 ? 1 - ( layer * ( 1 - FRONT_THICKNESS ) ) / ( layerCount - 1 ) : 1,
+		};
+	} );
+}
+
+/**
+ * Blends `from` toward `to` and returns the blend nearest the point where `passes` changes, on its passing side.
+ *
+ * @param from   - Where the blend starts.
+ * @param to     - Where the blend ends.
+ * @param passes - A test that changes at most once along the blend.
+ * @return A hex color.
+ */
+function blendToEdge( from: string, to: string, passes: ( color: string ) => boolean ): string {
+	const passesAtStart = passes( from );
+	let low = 0;
+	let high = 1;
+
+	for ( let step = 0; step < SEARCH_STEPS; step++ ) {
+		const middle = ( low + high ) / 2;
+
+		if ( passes( mixHexColors( from, to, middle ) ) === passesAtStart ) {
+			low = middle;
+		} else {
+			high = middle;
+		}
+	}
+
+	return mixHexColors( from, to, passesAtStart ? low : high );
+}
+
+const awayFrom = ( background: string ): string =>
+	contrastRatio( background, '#000000' ) >= contrastRatio( background, '#ffffff' )
+		? '#000000'
+		: '#ffffff';
+
+const opposite = ( end: string ): string => ( end === '#000000' ? '#ffffff' : '#000000' );
+
+/**
+ * The tone of a color nearest the background that keeps 3:1 against it.
+ *
+ * @param color      - A hex color.
+ * @param background - The hex chart background.
+ * @return A hex color.
+ */
+export function tintWithContrast( color: string, background: string ): string {
+	const passes = ( tone: string ) => contrastRatio( tone, background ) >= MIN_BACKGROUND_CONTRAST;
+
+	return blendToEdge( color, passes( color ) ? background : awayFrom( background ), passes );
+}
+
+/**
+ * The tone of a color nearest the original that keeps 3:1 against the bar it is drawn over, on the far side of that bar from the background when that side can reach 3:1.
+ *
+ * @param color      - A hex color.
+ * @param under      - The hex color of the bar behind it.
+ * @param background - The hex chart background.
+ * @return A hex color.
+ */
+export function shadeWithContrast( color: string, under: string, background: string ): string {
+	const passes = ( tone: string ) => contrastRatio( tone, under ) >= MIN_BACKGROUND_CONTRAST;
+	// Starting from a color on the background's side of `under` would cross it, so the search could not tell which side it ended on.
+	const start =
+		contrastRatio( color, background ) > contrastRatio( under, background ) ? color : under;
+
+	if ( passes( start ) ) {
+		return start;
+	}
+
+	const away = awayFrom( background );
+
+	return blendToEdge( start, passes( away ) ? away : opposite( away ), passes );
+}
+
+/**
+ * The colors an overlap layout fills its series with: per slot, the back layer tinted to 3:1 against the background and each layer in front shaded to 3:1 against the one behind. A slot whose front-most series has its own `stroke` keeps its colors as given.
+ *
+ * @param series     - Every series of the chart.
+ * @param colors     - Each series' resolved color.
+ * @param slotColors - The palette color of each slot, primaries first.
+ * @param background - The hex chart background.
+ * @return Each series' fill, by index.
+ */
+export function getOverlapBarColors(
+	series: SeriesData[],
+	colors: string[],
+	slotColors: readonly [ string, string ],
+	background: string
+): string[] {
+	const placements = getOverlapPlacements( series );
+	const barColors = [ ...colors ];
+
+	OVERLAP_SLOTS.forEach( ( slot, slotIndex ) => {
+		const members = placements.flatMap( ( placement, index ) =>
+			placement.slot === slot ? [ { index, layer: placement.layer } ] : []
+		);
+
+		if ( ! members.length ) {
+			return;
+		}
+
+		const layers = [ ...new Set( members.map( ( { layer } ) => layer ) ) ].sort(
+			( a, b ) => a - b
+		);
+		const back = members.find( ( { layer } ) => layer === layers[ 0 ] );
+		const base =
+			back && series[ back.index ].options?.stroke ? colors[ back.index ] : slotColors[ slotIndex ];
+		const isFrontStroked = members.some(
+			( { index, layer } ) =>
+				layer === layers[ layers.length - 1 ] && !! series[ index ].options?.stroke
+		);
+
+		// A paint such as `currentColor` or `url(#gradient)` cannot be toned, so the slot keeps the colors it was given.
+		if ( isFrontStroked || ! isValidHexColor( base ) || ! isValidHexColor( background ) ) {
+			return;
+		}
+
+		const toneByLayer = new Map< number, string >();
+		let under: string | undefined;
+
+		layers.forEach( layer => {
+			const tone =
+				under === undefined
+					? tintWithContrast( base, background )
+					: shadeWithContrast( base, under, background );
+			toneByLayer.set( layer, tone );
+			under = tone;
+		} );
+
+		members.forEach( ( { index, layer } ) => {
+			barColors[ index ] = toneByLayer.get( layer ) ?? colors[ index ];
+		} );
+	} );
+
+	return barColors;
+}

package/src/charts/bar-chart/private/selected-bar-ring.tsx

@@ -0,0 +1,84 @@
+import { DataContext } from '@visx/xychart';
+import { useContext } from 'react';
+import { SelectedRing } from '../../private/selected-ring/selected-ring';
+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 { FC } from 'react';
+
+/** The slot the keyboard has selected. */
+export type SelectedBar = {
+	/** The data of the bars the slot draws at the selected category, which the ring encloses; only bars the chart draws (a finite value). */
+	data: DataPointDate[];
+	/** The selected slot. */
+	slotKey: string;
+	/** The thickness of the slot's widest bar, as a share of the slot. */
+	thickness: number;
+};
+
+type AnyScale = ( ( input: unknown ) => number ) &
+	Partial< Pick< BandScale, 'bandwidth' > > & { range: () => unknown[] };
+
+/**
+ * Marks the keyboard-selected slot with a two-tone ring outside its edge, so the ring reads against any bar color.
+ *
+ * @param props              - Component props.
+ * @param props.chartId      - The chart's id, which keeps the clip path unique on a page with several charts.
+ * @param props.selected     - The selected slot.
+ * @param props.slotKeys     - The slots, in the order the band lays them out.
+ * @param props.groupPadding - The padding between slots.
+ * @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 ring, or nothing when the slot has no position.
+ */
+export const SelectedBarRing: FC< {
+	chartId: string;
+	selected: SelectedBar;
+	slotKeys: string[];
+	groupPadding: number;
+	horizontal: boolean;
+	xAccessor: ( d: DataPointDate ) => string | number | Date | undefined;
+	yAccessor: ( d: DataPointDate ) => number | undefined;
+} > = ( { chartId, selected, slotKeys, groupPadding, horizontal, xAccessor, yAccessor } ) => {
+	const context = useContext( DataContext );
+	const bandScale = ( horizontal ? context?.yScale : context?.xScale ) as AnyScale | undefined;
+	const valueScale = ( horizontal ? context?.xScale : context?.yScale ) as AnyScale | undefined;
+	const bandwidth = bandScale?.bandwidth?.() ?? 0;
+	const [ category ] = selected.data;
+
+	if ( ! bandScale || ! valueScale || ! bandwidth || ! category ) {
+		return null;
+	}
+
+	const groupScale = createGroupScale( slotKeys, bandwidth, groupPadding );
+	const slotOffset = groupScale( selected.slotKey );
+	const bandPosition = Number(
+		bandScale( ( horizontal ? yAccessor : xAccessor )( category ) as never )
+	);
+	if ( slotOffset == null || ! Number.isFinite( bandPosition ) ) {
+		return null;
+	}
+
+	const valuePositions = selected.data.map( datum =>
+		Number( valueScale( Number( ( horizontal ? xAccessor : yAccessor )( datum ) ) as never ) )
+	);
+
+	const rect = computeSlotRect( {
+		horizontal,
+		bandPosition,
+		slotOffset,
+		slotThickness: groupScale.bandwidth(),
+		valuePositions: [ getValueScaleBaseline( valueScale ), ...valuePositions ],
+		widthFactor: selected.thickness,
+	} );
+	return (
+		<SelectedRing
+			chartId={ chartId }
+			d={ `M${ rect.x } ${ rect.y }h${ rect.width }v${ rect.height }h${ -rect.width }Z` }
+			side="outside"
+			testId="bar-chart-selected-ring"
+		/>
+	);
+};

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

@@ -0,0 +1,28 @@
+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; index: number };
+
+/**
+ * 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.
+ * @return No visual content.
+ */
+export function SlotTooltipMembers( { members }: { members: SlotMember[] } ) {
+	const { showTooltip, updateTooltip } = useContext( TooltipContext ) ?? {};
+
+	useEffect( () => {
+		updateTooltip?.( state => ( { ...state, tooltipData: undefined } ) );
+		members.forEach( member => showTooltip?.( member ) );
+		// `showTooltip` and `updateTooltip` are stable; the context object is not.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [ members ] );
+
+	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 );
+	} );
+} );