@automattic/charts 4.11.1 → 4.12.0

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 } 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';

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"
+		/>
+	);
+};