@automattic/charts 4.11.0 → 4.12.0

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

@@ -31,10 +31,10 @@ import { pickLabelTextColor, resolveLabelRoles } from '../private/label-text-col
 import {
 	orderArcsForNavigation,
 	PieSelectionOutput,
-	SelectedSegmentRing,
 	usePieKeyboardNavigation,
 } from '../private/pie-keyboard-navigation';
 import { RadialWipeAnimation } from '../private/radial-wipe-animation/';
+import { SelectedRing } from '../private/selected-ring/selected-ring';
 import { getAllHiddenMessage, SvgEmptyState } from '../private/svg-empty-state';
 import { withResponsive, ResponsiveConfig } from '../private/with-responsive';
 import styles from './pie-chart.module.scss';
@@ -503,7 +503,12 @@ const PieChartInternal = ( {
 								{ /* Unmasked so the entry wipe cannot hide the focus indicator. */ }
 								{ selectedArc && (
 									<Group top={ centerY } left={ centerX }>
-										<SelectedSegmentRing chartId={ chartId } d={ path( selectedArc ) || '' } />
+										<SelectedRing
+											chartId={ chartId }
+											d={ path( selectedArc ) || '' }
+											side="inside"
+											testId="pie-selected-ring"
+										/>
 									</Group>
 								) }
 								{ ! allSegmentsHidden && (

package/src/charts/pie-semi-circle-chart/pie-semi-circle-chart.tsx

@@ -26,10 +26,10 @@ import { ChartLayout } from '../private/chart-layout';
 import {
 	orderArcsForNavigation,
 	PieSelectionOutput,
-	SelectedSegmentRing,
 	usePieKeyboardNavigation,
 } from '../private/pie-keyboard-navigation';
 import { RadialWipeAnimation } from '../private/radial-wipe-animation';
+import { SelectedRing } from '../private/selected-ring/selected-ring';
 import { getAllHiddenMessage, SvgEmptyState } from '../private/svg-empty-state';
 import { withResponsive } from '../private/with-responsive';
 import styles from './pie-semi-circle-chart.module.scss';
@@ -429,7 +429,12 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 								{ /* Unmasked so the entry wipe cannot hide the focus indicator. */ }
 								{ selectedArc && (
 									<Group top={ height } left={ width / 2 }>
-										<SelectedSegmentRing chartId={ chartId } d={ path( selectedArc ) || '' } />
+										<SelectedRing
+											chartId={ chartId }
+											d={ path( selectedArc ) || '' }
+											side="inside"
+											testId="pie-selected-ring"
+										/>
 									</Group>
 								) }
 								{ ! allSegmentsHidden && (

package/src/charts/private/pie-keyboard-navigation/index.ts

@@ -1,4 +1,3 @@
 export { orderArcsForNavigation } from './order-arcs-for-navigation';
 export { PieSelectionOutput } from './pie-selection-output';
-export { SelectedSegmentRing } from './selected-segment-ring';
 export { usePieKeyboardNavigation } from './use-pie-keyboard-navigation';

package/src/charts/private/{pie-keyboard-navigation/pie-keyboard-navigation.module.scss → selected-ring/selected-ring.module.scss}

@@ -1,16 +1,21 @@
-// The clip to the segment removes the outer half of each stroke,
-// so widths are doubled.
-.selected-ring__contrast,
-.selected-ring__focus {
+// The clip removes one half of each stroke, so widths are doubled.
+.selected-ring__far,
+.selected-ring__edge {
 	fill: none;
 }
 
+.selected-ring__far {
+	stroke-width: calc(4 * var(--wpds-border-width-focus));
+}
+
+.selected-ring__edge {
+	stroke-width: calc(2 * var(--wpds-border-width-focus));
+}
+
 .selected-ring__contrast {
 	stroke: var(--a8c-charts-color-background, #fff);
-	stroke-width: calc(4 * var(--wpds-border-width-focus));
 }
 
 .selected-ring__focus {
 	stroke: var(--wpds-color-stroke-focus);
-	stroke-width: calc(2 * var(--wpds-border-width-focus));
 }

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

@@ -0,0 +1,73 @@
+import clsx from 'clsx';
+import styles from './selected-ring.module.scss';
+
+type Tone = 'contrast' | 'focus';
+
+/** Which side of the shape's edge the ring is drawn on. */
+export type SelectedRingSide = 'inside' | 'outside';
+
+interface SelectedRingProps {
+	/** The chart's id, which keeps the clip path unique on a page with several charts. */
+	chartId: string;
+	/** The selected shape's path. */
+	d: string;
+	/** `inside` keeps the ring clear of the SVG edge; `outside` leaves the shape's fill uncovered. */
+	side: SelectedRingSide;
+	testId?: string;
+}
+
+// The tone at the edge is drawn last, over the wider tone beyond it.
+const TONES: Record< SelectedRingSide, [ far: Tone, edge: Tone ] > = {
+	inside: [ 'contrast', 'focus' ],
+	outside: [ 'focus', 'contrast' ],
+};
+
+const EVERYWHERE = 'M-1e6 -1e6H1e6V1e6H-1e6Z';
+
+/**
+ * Encodes `value` for an SVG id, losslessly so distinct chart ids never share a clip path.
+ *
+ * @param value - Any string.
+ * @return `value` with each character outside `[A-Za-z0-9-]` written as `_<hex code point>_`.
+ */
+export const toSvgId = ( value: string ) =>
+	Array.from( value, character =>
+		/[A-Za-z0-9-]/.test( character )
+			? character
+			: `_${ character.codePointAt( 0 )?.toString( 16 ) }_`
+	).join( '' );
+
+/**
+ * Marks a selected shape with a focus-colored ring and a contrast ring, so it reads against any fill.
+ *
+ * @param {SelectedRingProps} props - Component props
+ * @return {JSX.Element} The ring
+ */
+export const SelectedRing = ( { chartId, d, side, testId }: SelectedRingProps ) => {
+	const clipId = `selected-ring-clip-${ toSvgId( chartId ) }`;
+	const clipPath = `url(#${ clipId })`;
+	const [ far, edge ] = TONES[ side ];
+
+	return (
+		<g pointerEvents="none" aria-hidden="true">
+			<clipPath id={ clipId }>
+				{ side === 'inside' ? (
+					<path d={ d } />
+				) : (
+					<path d={ `${ EVERYWHERE } ${ d }` } clipRule="evenodd" />
+				) }
+			</clipPath>
+			<path
+				d={ d }
+				clipPath={ clipPath }
+				className={ clsx( styles[ 'selected-ring__far' ], styles[ `selected-ring__${ far }` ] ) }
+			/>
+			<path
+				d={ d }
+				clipPath={ clipPath }
+				className={ clsx( styles[ 'selected-ring__edge' ], styles[ `selected-ring__${ edge }` ] ) }
+				data-testid={ testId }
+			/>
+		</g>
+	);
+};

package/src/charts/private/{pie-keyboard-navigation/test/selected-segment-ring.test.ts → selected-ring/test/selected-ring.test.ts}

@@ -1,4 +1,4 @@
-import { toSvgId } from '../selected-segment-ring';
+import { toSvgId } from '../selected-ring';
 
 describe( 'toSvgId', () => {
 	it.each( [

package/src/components/legend/hooks/test/use-chart-legend-items.test.tsx

@@ -421,6 +421,26 @@ describe( 'useChartLegendItems', () => {
 			expect( result.current[ 2 ].color ).toBe( result.current[ 0 ].color );
 		} );
 
+		test( 'colors each swatch, comparison items included, from seriesColors by series index', () => {
+			const seriesColors = [ '#111111', '#222222', '#333333', '#444444' ];
+			const { result } = renderHook(
+				() =>
+					useChartLegendItems( twoMetricData, {
+						collapseGroups: true,
+						comparisonSeriesItems: perMetricLabel,
+						seriesColors,
+					} ),
+				{ wrapper }
+			);
+
+			expect( result.current.map( item => item.color ) ).toEqual( [
+				'#111111',
+				'#333333',
+				'#222222',
+				'#444444',
+			] );
+		} );
+
 		test( 'adds nothing when no series is a comparison', () => {
 			const { result } = renderHook(
 				() => useChartLegendItems( [ comparisonData[ 0 ] ], { comparisonItem: true } ),

package/src/components/legend/hooks/use-chart-legend-items.ts

@@ -41,6 +41,25 @@ export interface ChartLegendOptions {
 	comparisonItem?: SeriesChartLegendConfig[ 'comparisonItem' ];
 	/** One static item per comparison series instead; see `SeriesChartLegendConfig`. */
 	comparisonSeriesItems?: SeriesChartLegendConfig[ 'comparisonSeriesItems' ];
+	/** Each series' swatch color, by index, in place of its series color. */
+	seriesColors?: string[];
+}
+
+/**
+ * Wraps `getElementStyles` so a swatch takes the color given for its series.
+ * @param getElementStyles - Function to get element styles
+ * @param seriesColors     - Each series' swatch color, by index
+ * @return Element styles with the given color
+ */
+function withSeriesColors(
+	getElementStyles: ( params: GetElementStylesParams ) => ElementStyles,
+	seriesColors: string[]
+): ( params: GetElementStylesParams ) => ElementStyles {
+	return params => {
+		const styles = getElementStyles( params );
+
+		return { ...styles, color: seriesColors[ params.index ] ?? styles.color };
+	};
 }
 
 /**
@@ -386,9 +405,10 @@ export function useChartLegendItems<
 		collapseGroups = false,
 		comparisonItem = false,
 		comparisonSeriesItems,
+		seriesColors,
 		renderGlyph,
 	} = options;
-	const { getElementStyles } = useGlobalChartsContext();
+	const { getElementStyles: getSeriesStyles } = useGlobalChartsContext();
 
 	return useMemo( () => {
 		if ( ! data || ! Array.isArray( data ) || data.length === 0 ) {
@@ -398,6 +418,9 @@ export function useChartLegendItems<
 		// Handle SeriesData (multiple series with data points)
 		if ( 'data' in data[ 0 ] ) {
 			const seriesData = data as SeriesData[];
+			const getElementStyles = seriesColors
+				? withSeriesColors( getSeriesStyles, seriesColors )
+				: getSeriesStyles;
 			const items = processSeriesData(
 				seriesData,
 				getElementStyles,
@@ -440,7 +463,7 @@ export function useChartLegendItems<
 		// Handle DataPointDate or DataPointPercentageCalculated (single data points)
 		return processPointData(
 			data as ( DataPointDate | DataPointPercentageCalculated )[],
-			getElementStyles,
+			getSeriesStyles,
 			showValues,
 			legendValueDisplay,
 			withGlyph,
@@ -450,7 +473,7 @@ export function useChartLegendItems<
 		);
 	}, [
 		data,
-		getElementStyles,
+		getSeriesStyles,
 		showValues,
 		legendValueDisplay,
 		withGlyph,
@@ -458,6 +481,7 @@ export function useChartLegendItems<
 		collapseGroups,
 		comparisonItem,
 		comparisonSeriesItems,
+		seriesColors,
 		renderGlyph,
 		legendShape,
 	] );

package/src/components/tooltip/xy-chart-tooltip.tsx

@@ -152,7 +152,8 @@ export const XYChartTooltip: React.FC< XYChartTooltipProps > = ( {
 		hasKeyboardSelection.current = true;
 
 		if ( mode === 'group' ) {
-			// Show all series at the selected data point index in single tooltip.
+			// visx merges each shown datum into the previous tooltip data, so start empty or a series dropped from `series` keeps its row.
+			closeTooltipNow();
 			series.forEach( ( s, index ) => {
 				if ( selectedIndex < s.data.length ) {
 					const datum = s.data[ selectedIndex ];
@@ -292,7 +293,7 @@ export const useKeyboardNavigation = ( {
 	const previousTotalPoints = useRef( totalPoints );
 	const previousVisibleSeriesKey = useRef( visibleSeriesKey );
 
-	// Hiding or showing a series moves every index onto a different bar. The count alone misses a
+	// Hiding or showing a series re-points every index. The count alone misses a
 	// swap that keeps it the same, such as hiding one series while revealing another of equal length.
 	// Clear rather than clamp once focus has left the chart: a new tooltip would pull focus back.
 	useEffect( () => {

package/src/index.ts

@@ -1,6 +1,11 @@
 // Charts
 export { AreaChart, AreaChartUnresponsive } from './charts/area-chart';
-export { BarChart, BarChartUnresponsive } from './charts/bar-chart';
+export {
+	BarChart,
+	BarChartUnresponsive,
+	useBarColors,
+	useBarLegendItems,
+} from './charts/bar-chart';
 export { BarListChart, BarListChartUnresponsive } from './charts/bar-list-chart';
 export { ConversionFunnelChart } from './charts/conversion-funnel-chart';
 export { GeoChart, GeoChartUnresponsive } from './charts/geo-chart';
@@ -76,6 +81,7 @@ export type {
 	LegendShape,
 	LegendShapeLabel,
 	LegendShapeRenderProps,
+	BarChartLayout,
 } from './types';
 export type * from './visx/types';
 export type { PieChartProps, PieChartRenderTooltipParams } from './charts/pie-chart';
@@ -109,7 +115,7 @@ export type { LegendProps, BaseLegendProps, ChartLegendOptions } from './compone
 
 // Previously available via '@automattic/charts/bar-chart', '@automattic/charts/line-chart', etc.
 export type { AreaChartProps } from './charts/area-chart';
-export type { BarChartProps, BandHighlightSelection } from './charts/bar-chart';
+export type { BarChartProps, BandHighlightSelection, BarLegendOptions } from './charts/bar-chart';
 export type {
 	BarListChartProps,
 	RenderLabelProps,

package/src/providers/chart-context/global-charts-provider.tsx

@@ -371,6 +371,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 			theme: providerTheme,
 			formatting,
 			getElementStyles,
+			backgroundColor: colorCache.background,
 			toggleSeriesVisibility,
 			setSeriesVisibility,
 			setChartHiddenSeries,
@@ -388,6 +389,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 			providerTheme,
 			formatting,
 			getElementStyles,
+			colorCache.background,
 			toggleSeriesVisibility,
 			setSeriesVisibility,
 			setChartHiddenSeries,

package/src/providers/chart-context/test/chart-context.test.tsx

@@ -5,7 +5,6 @@ import { useChartId } from '../hooks/use-chart-id';
 import { useChartRegistration } from '../hooks/use-chart-registration';
 import { useGlobalChartsContext } from '../hooks/use-global-charts-context';
 import { createPaletteGenerator } from '../private/palette-generator';
-import { defaultTheme } from '../themes';
 import type { BaseLegendItem } from '../../../components/legend';
 import type { SeriesData } from '../../../types';
 import type { GlobalChartsContextValue } from '../types';
@@ -1168,12 +1167,9 @@ describe( 'ChartContext', () => {
 				legendShape: 'rect',
 			} );
 
-			// Should get theme legend shape styles (not line styles), with the comparison bar
-			// opacity layered on so the swatch matches the translucent comparison bar.
 			expect( styles.shapeStyles ).toEqual( {
 				fill: '#LEGEND1',
 				stroke: '#BORDER1',
-				opacity: 0.5,
 			} );
 		} );
 	} );
@@ -2144,13 +2140,4 @@ describe( 'ChartContext', () => {
 			} );
 		} );
 	} );
-
-	describe( 'defaultTheme', () => {
-		it( 'exposes default barChart comparison styles', () => {
-			expect( defaultTheme.barChart.barStyles.comparison ).toEqual( {
-				widthFactor: 1.5,
-				opacity: 0.5,
-			} );
-		} );
-	} );
 } );

package/src/providers/chart-context/themes.ts

@@ -49,7 +49,6 @@ const defaultTheme: CompleteChartTheme = {
 		barStyles: {
 			comparison: {
 				widthFactor: 1.5,
-				opacity: 0.5,
 			},
 		},
 	},

package/src/providers/chart-context/types.ts

@@ -41,6 +41,8 @@ export interface GlobalChartsContextValue {
 	/** Locale and time zone every date the charts print is rendered in. */
 	formatting: ChartFormatting;
 	getElementStyles: ( params: GetElementStylesParams ) => ElementStyles;
+	/** The chart background as an opaque hex, for colors that must keep contrast against it. Optional so a hand-built context value still type-checks. */
+	backgroundColor?: string;
 	// Series visibility management shared by charts, legends, and programmatic controls.
 	toggleSeriesVisibility: ( chartId: string, seriesLabel: string ) => void;
 	setSeriesVisibility: ( chartId: string, seriesLabel: string, visible: boolean ) => void;

package/src/test-utils/selected-bar-ring.ts

@@ -0,0 +1,14 @@
+import { screen } from '@testing-library/react';
+
+const NUMBER = /-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/gi;
+
+/**
+ * The box the bar chart's selected ring outlines, read from its path.
+ *
+ * @return The ring's x, y, width and height.
+ */
+export const selectedBarRingBounds = () => {
+	const d = screen.getByTestId( 'bar-chart-selected-ring' ).getAttribute( 'd' ) ?? '';
+	const [ x, y, width, height ] = ( d.match( NUMBER ) ?? [] ).map( Number );
+	return { x, y, width, height };
+};

package/src/types.ts

@@ -306,14 +306,22 @@ export type SeriesData = {
 
 /**
  * Visual styling for a bar series of a given semantic type (e.g. 'comparison').
- * `widthFactor` is the bar width relative to the primary bar slot (1.5 = 150%);
- * `opacity` sets the shadow translucency.
+ * `widthFactor` is the bar width relative to the primary bar slot (1.5 = 150%).
  */
 export type BarStyles = {
 	widthFactor?: number;
+	/**
+	 * Draws the comparison bar translucent, in its primary's color, instead of the opaque tones the chart picks.
+	 * @deprecated Comparison bars are opaque. Leave this unset; set the comparison series' `options.stroke` for a color of its own.
+	 */
 	opacity?: number;
 };
 
+/**
+ * How a bar chart places its series in a category. `grouped` puts each primary series in a slot of its own; `overlap` puts every primary in one slot and every comparison in a second, and overlaps the `group`s within each slot.
+ */
+export type BarChartLayout = 'grouped' | 'overlap';
+
 export type MultipleDataPointsDate = {
 	label: string;
 	data: DataPointDate[];

package/src/charts/private/pie-keyboard-navigation/selected-segment-ring.tsx

@@ -1,47 +0,0 @@
-import styles from './pie-keyboard-navigation.module.scss';
-
-interface SelectedSegmentRingProps {
-	/** The chart's id, which keeps the clip path unique on a page with several charts. */
-	chartId: string;
-	/** The selected segment's path, from the same arc generator that draws the segment. */
-	d: string;
-}
-
-/**
- * Encodes `value` for an SVG id, losslessly so distinct chart ids never share a clip path.
- *
- * @param value - Any string.
- * @return `value` with each character outside `[A-Za-z0-9-]` written as `_<hex code point>_`.
- */
-export const toSvgId = ( value: string ) =>
-	Array.from( value, character =>
-		/[A-Za-z0-9-]/.test( character )
-			? character
-			: `_${ character.codePointAt( 0 )?.toString( 16 ) }_`
-	).join( '' );
-
-/**
- * Marks the selected segment with a two-tone ring drawn inside its edge, so the SVG edge cannot cut it off.
- *
- * @param {SelectedSegmentRingProps} props - Component props
- * @return {JSX.Element} The ring
- */
-export const SelectedSegmentRing = ( { chartId, d }: SelectedSegmentRingProps ) => {
-	const clipId = `pie-selected-ring-clip-${ toSvgId( chartId ) }`;
-	const clipPath = `url(#${ clipId })`;
-
-	return (
-		<g pointerEvents="none" aria-hidden="true">
-			<clipPath id={ clipId }>
-				<path d={ d } />
-			</clipPath>
-			<path d={ d } clipPath={ clipPath } className={ styles[ 'selected-ring__contrast' ] } />
-			<path
-				d={ d }
-				clipPath={ clipPath }
-				className={ styles[ 'selected-ring__focus' ] }
-				data-testid="pie-selected-ring"
-			/>
-		</g>
-	);
-};