@automattic/charts 1.7.0 → 1.8.1

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

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import { __ } from '@wordpress/i18n';
-import { Stack } from '@wordpress/ui';
 import clsx from 'clsx';
 import { FC, useContext, useMemo } from 'react';
 import { Chart } from 'react-google-charts';
@@ -13,6 +12,7 @@ import { GlobalChartsContext, GlobalChartsProvider, useGlobalChartsContext } fro
 import { lightenHexColor, normalizeColorToHex } from '../../utils/color-utils';
 import { resolveCssVariable } from '../../utils/resolve-css-var';
 import { sanitizeHtml } from '../../utils/sanitize-html';
+import { Center } from '../private/center';
 import { withResponsive } from '../private/with-responsive';
 import styles from './geo-chart.module.scss';
 import { GeoChartProps } from './types';
@@ -60,15 +60,13 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 
 	// Render loading placeholder
 	const loadingPlaceholder = (
-		<Stack
-			align="center"
-			justify="center"
+		<Center
 			className={ clsx( 'geo-chart', styles.container, className ) }
 			data-testid="geo-chart-loading"
 			style={ { width, height } }
 		>
 			{ renderPlaceholder ? renderPlaceholder() : __( 'Loading map', 'jetpack-charts' ) }
-		</Stack>
+		</Center>
 	);
 
 	// Google charts doesn't accept CSS variables, so we need to convert them to hex colors
@@ -149,9 +147,7 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 	);
 
 	return (
-		<Stack
-			align="center"
-			justify="center"
+		<Center
 			className={ clsx( 'geo-chart', styles.container, className ) }
 			data-testid="geo-chart"
 			style={ { width, height, backgroundColor } }
@@ -164,7 +160,7 @@ const GeoChartInternal: FC< GeoChartProps > = ( {
 				options={ options }
 				loader={ loadingPlaceholder }
 			/>
-		</Stack>
+		</Center>
 	);
 };
 

package/src/charts/pie-chart/pie-chart.module.scss

@@ -7,8 +7,4 @@
 		width: 100%;
 	}
 
-	&__centering {
-		width: 100%;
-		height: 100%;
-	}
 }

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

@@ -2,7 +2,6 @@ import { Group } from '@visx/group';
 import { Pie } from '@visx/shape';
 import { useTooltip, useTooltipInPortal } from '@visx/tooltip';
 import { __ } from '@wordpress/i18n';
-import { Stack } from '@wordpress/ui';
 import clsx from 'clsx';
 import { useCallback, useContext, useMemo } from 'react';
 import { Legend, useChartLegendItems } from '../../components/legend';
@@ -22,6 +21,7 @@ import {
 } from '../../providers';
 import { attachSubComponents, resolveFontSize } from '../../utils';
 import { getStringWidth } from '../../visx/text';
+import { Center } from '../private/center';
 import { ChartSVG, ChartHTML, useChartChildren } from '../private/chart-composition';
 import { ChartLayout } from '../private/chart-layout';
 import { RadialWipeAnimation } from '../private/radial-wipe-animation/';
@@ -358,12 +358,7 @@ const PieChartInternal = ( {
 						: 0;
 
 					return (
-						<Stack
-							ref={ containerRef }
-							align="center"
-							justify="center"
-							className={ styles[ 'pie-chart__centering' ] }
-						>
+						<Center ref={ containerRef }>
 							<svg
 								viewBox={ `0 0 ${ width } ${ height }` }
 								preserveAspectRatio="xMidYMid meet"
@@ -493,7 +488,7 @@ const PieChartInternal = ( {
 									{ ! allSegmentsHidden && svgChildren }
 								</Group>
 							</svg>
-						</Stack>
+						</Center>
 					);
 				} }
 			</ChartLayout>

package/src/charts/pie-semi-circle-chart/pie-semi-circle-chart.module.scss

@@ -5,11 +5,6 @@
 		width: 100%;
 	}
 
-	&__centering {
-		width: 100%;
-		height: 100%;
-	}
-
 	.label {
 		font-weight: var(--wpds-typography-font-weight-medium, 499);
 		font-size: var(--wpds-typography-font-size-lg, 16px);

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

@@ -3,7 +3,6 @@ import { Pie } from '@visx/shape';
 import { Text } from '@visx/text';
 import { useTooltip, useTooltipInPortal } from '@visx/tooltip';
 import { __ } from '@wordpress/i18n';
-import { Stack } from '@wordpress/ui';
 import clsx from 'clsx';
 import { useCallback, useContext, useMemo } from 'react';
 import { Legend, useChartLegendItems } from '../../components/legend';
@@ -21,6 +20,7 @@ import {
 	GlobalChartsContext,
 } from '../../providers';
 import { attachSubComponents } from '../../utils';
+import { Center } from '../private/center';
 import { ChartSVG, ChartHTML, useChartChildren } from '../private/chart-composition';
 import { ChartLayout } from '../private/chart-layout';
 import { RadialWipeAnimation } from '../private/radial-wipe-animation';
@@ -397,12 +397,7 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 					const innerRadius = radius * ( 1 - thickness );
 
 					return (
-						<Stack
-							ref={ containerRef }
-							align="center"
-							justify="center"
-							className={ styles[ 'pie-semi-circle-chart__centering' ] }
-						>
+						<Center ref={ containerRef }>
 							<svg
 								width={ width }
 								height={ height }
@@ -491,7 +486,7 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 									) }
 								</Group>
 							</svg>
-						</Stack>
+						</Center>
 					);
 				} }
 			</ChartLayout>

package/src/charts/private/center/center.module.scss

@@ -0,0 +1,4 @@
+.center {
+	width: 100%;
+	height: 100%;
+}

package/src/charts/private/center/center.tsx

@@ -0,0 +1,33 @@
+import { Stack } from '@wordpress/ui';
+import clsx from 'clsx';
+import { forwardRef, type ComponentPropsWithoutRef } from 'react';
+import styles from './center.module.scss';
+
+export type CenterProps = ComponentPropsWithoutRef< typeof Stack >;
+
+/**
+ * Centers its children on both axes and fills its parent.
+ *
+ * A thin wrapper around `Stack` with `align="center"` and `justify="center"`
+ * defaults (both overridable) plus `width: 100%; height: 100%`. Reads more
+ * honestly than a `Stack` with both axes centered, and lets call sites drop
+ * ad-hoc `*__centering` classes. Forwards its ref and spreads remaining props
+ * onto the underlying `Stack`.
+ *
+ * @param props - Stack props; `align`/`justify` default to `"center"`.
+ * @param ref   - Forwarded to the underlying element.
+ * @return The centered layout element.
+ */
+export const Center = forwardRef< HTMLDivElement, CenterProps >(
+	( { align = 'center', justify = 'center', className, ...props }, ref ) => (
+		<Stack
+			ref={ ref }
+			align={ align }
+			justify={ justify }
+			className={ clsx( styles.center, className ) }
+			{ ...props }
+		/>
+	)
+);
+
+Center.displayName = 'Center';

package/src/charts/private/center/index.ts

@@ -0,0 +1,2 @@
+export { Center } from './center';
+export type { CenterProps } from './center';

package/src/charts/private/center/test/center.test.tsx

@@ -0,0 +1,60 @@
+import { render, screen } from '@testing-library/react';
+import { createRef } from 'react';
+import { Center } from '../index';
+
+describe( 'Center', () => {
+	test( 'renders its children', () => {
+		render(
+			<Center data-testid="center">
+				<span>Centered content</span>
+			</Center>
+		);
+		expect( screen.getByTestId( 'center' ) ).toHaveTextContent( 'Centered content' );
+	} );
+
+	test( 'merges a custom className with the center class', () => {
+		render(
+			<Center data-testid="center" className="custom-class">
+				child
+			</Center>
+		);
+		const el = screen.getByTestId( 'center' );
+		expect( el ).toHaveClass( 'center' );
+		expect( el ).toHaveClass( 'custom-class' );
+	} );
+
+	test( 'forwards its ref to the underlying element', () => {
+		const ref = createRef< HTMLDivElement >();
+		render( <Center ref={ ref }>child</Center> );
+		expect( ref.current ).toBeInstanceOf( HTMLElement );
+	} );
+
+	test( 'spreads arbitrary props through to the element', () => {
+		render(
+			<Center data-testid="center" style={ { width: 120 } }>
+				child
+			</Center>
+		);
+		expect( screen.getByTestId( 'center' ) ).toHaveStyle( { width: '120px' } );
+	} );
+
+	test( 'centers on both axes by default', () => {
+		render( <Center data-testid="center">child</Center> );
+		expect( screen.getByTestId( 'center' ) ).toHaveStyle( {
+			alignItems: 'center',
+			justifyContent: 'center',
+		} );
+	} );
+
+	test( 'allows overriding the align and justify defaults', () => {
+		render(
+			<Center data-testid="center" align="flex-start" justify="flex-end">
+				child
+			</Center>
+		);
+		expect( screen.getByTestId( 'center' ) ).toHaveStyle( {
+			alignItems: 'flex-start',
+			justifyContent: 'flex-end',
+		} );
+	} );
+} );

package/src/charts/private/svg-empty-state/svg-empty-state.module.scss

@@ -1,7 +1,5 @@
 .svg-empty-state {
 	text-align: center;
-	width: 100%;
-	height: 100%;
 	font-size: var(--wpds-typography-font-size-md, 13px);
 	color: var(--wpds-color-fg-content-neutral-weak, #6d6d6d);
 }

package/src/charts/private/svg-empty-state/svg-empty-state.tsx

@@ -1,4 +1,4 @@
-import { Stack } from '@wordpress/ui';
+import { Center } from '../center';
 import styles from './svg-empty-state.module.scss';
 import type { FC, ReactNode } from 'react';
 
@@ -32,9 +32,7 @@ interface SvgEmptyStateProps {
 export const SvgEmptyState: FC< SvgEmptyStateProps > = ( { x, y, width, height, children } ) => {
 	return (
 		<foreignObject x={ x - width / 2 } y={ y - height / 2 } width={ width } height={ height }>
-			<Stack align="center" justify="center" className={ styles[ 'svg-empty-state' ] }>
-				{ children }
-			</Stack>
+			<Center className={ styles[ 'svg-empty-state' ] }>{ children }</Center>
 		</foreignObject>
 	);
 };

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

@@ -10,6 +10,7 @@ import {
 } from 'react';
 import {
 	getItemShapeStyles,
+	getSeriesBarStyles,
 	getSeriesLineStyles,
 	mergeThemes,
 	resolveCssVariable,
@@ -206,6 +207,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 						( isPointPercentageData && data?.color ),
 				} ),
 				lineStyles: isSeriesData ? getSeriesLineStyles( data, index, providerTheme ) : {},
+				barStyles: isSeriesData ? getSeriesBarStyles( data, index, providerTheme ) : {},
 				glyph: providerTheme.glyphs?.[ index ],
 				shapeStyles: isSeriesData
 					? getItemShapeStyles( data, index, providerTheme, legendShape )

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

@@ -4,6 +4,7 @@ import { GlobalChartsProvider } from '../global-charts-provider';
 import { useChartId } from '../hooks/use-chart-id';
 import { useChartRegistration } from '../hooks/use-chart-registration';
 import { useGlobalChartsContext } from '../hooks/use-global-charts-context';
+import { defaultTheme } from '../themes';
 import type { BaseLegendItem } from '../../../components/legend';
 import type { ChartTheme, SeriesData } from '../../../types';
 import type { GlobalChartsContextValue } from '../types';
@@ -1165,10 +1166,12 @@ describe( 'ChartContext', () => {
 				legendShape: 'rect',
 			} );
 
-			// Should get theme legend shape styles, not line styles
+			// 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,
 			} );
 		} );
 	} );
@@ -2534,4 +2537,13 @@ 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

@@ -69,6 +69,14 @@ const defaultTheme: CompleteChartTheme = {
 			},
 		},
 	},
+	barChart: {
+		barStyles: {
+			comparison: {
+				widthFactor: 1.5,
+				opacity: 0.5,
+			},
+		},
+	},
 	sparkline: {
 		margin: { top: 2, right: 2, bottom: 2, left: 2 },
 		strokeWidth: 1.5,

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

@@ -1,6 +1,7 @@
 import { CSSProperties, ReactNode } from 'react';
 import type { BaseLegendItem } from '../../components/legend';
 import type {
+	BarStyles,
 	ChartType,
 	CompleteChartTheme,
 	DataPointPercentage,
@@ -25,6 +26,7 @@ export type GetElementStylesParams = {
 export type ElementStyles = {
 	color: string;
 	lineStyles: LineStyles;
+	barStyles: BarStyles;
 	glyph: < Datum extends object >( props: GlyphProps< Datum > ) => ReactNode;
 	shapeStyles: CSSProperties & LineStyles;
 };

package/src/types.ts

@@ -268,6 +268,16 @@ export type SeriesData = {
 	options?: SeriesDataOptions;
 };
 
+/**
+ * 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.
+ */
+export type BarStyles = {
+	widthFactor?: number;
+	opacity?: number;
+};
+
 export type MultipleDataPointsDate = {
 	label: string;
 	data: DataPointDate[];
@@ -388,6 +398,9 @@ export type ChartTheme = {
 	lineChart?: {
 		lineStyles?: Partial< Record< NonNullable< SeriesDataOptions[ 'type' ] >, LineStyles > >;
 	};
+	barChart?: {
+		barStyles?: Partial< Record< NonNullable< SeriesDataOptions[ 'type' ] >, BarStyles > >;
+	};
 	/** Sparkline specific settings */
 	sparkline?: {
 		/** Margin around the sparkline chart */
@@ -420,6 +433,9 @@ export type CompleteChartTheme = Required< ChartTheme > & {
 	lineChart: {
 		lineStyles: Record< NonNullable< SeriesDataOptions[ 'type' ] >, LineStyles >;
 	};
+	barChart: {
+		barStyles: Record< NonNullable< SeriesDataOptions[ 'type' ] >, BarStyles >;
+	};
 	legend: Required< NonNullable< ChartTheme[ 'legend' ] > >;
 	sparkline: Required< NonNullable< ChartTheme[ 'sparkline' ] > > & {
 		margin: Required< NonNullable< ChartTheme[ 'sparkline' ] >[ 'margin' ] >;

package/src/utils/get-styles.ts

@@ -1,4 +1,4 @@
-import type { ChartTheme, LegendShape, SeriesData } from '../types';
+import type { BarStyles, ChartTheme, LegendShape, SeriesData } from '../types';
 import type { LineStyles } from '@visx/xychart';
 
 /**
@@ -28,6 +28,25 @@ export function getSeriesLineStyles(
 	);
 }
 
+/**
+ * Utility to get consolidated bar styles for a series by semantic type.
+ * Mirrors getSeriesLineStyles: a series with `options.type` (e.g. 'comparison')
+ * resolves to `theme.barChart.barStyles[ type ]`.
+ *
+ * @param {SeriesData} seriesData    - The series data containing styling options
+ * @param {number}     index         - The index of the series in the data array
+ * @param {ChartTheme} providerTheme - The chart theme configuration
+ * @return {BarStyles} The consolidated bar styles for the series
+ */
+export function getSeriesBarStyles(
+	seriesData: SeriesData,
+	index: number,
+	providerTheme: ChartTheme
+): BarStyles {
+	const type = seriesData.options?.type;
+	return ( type && providerTheme?.barChart?.barStyles?.[ type ] ) ?? {};
+}
+
 /**
  * Utility function to get stroke color for a series
  *
@@ -61,22 +80,26 @@ export function getItemShapeStyles(
 ): Record< string, unknown > {
 	const seriesShapeStyles = series.options?.legendShapeStyle ?? {};
 	const lineStyles = legendShape === 'line' ? getSeriesLineStyles( series, index, theme ) : {};
+	// For non-line legends (e.g. bar 'rect'), reflect the comparison bar's opacity on the
+	// swatch so the legend marker matches the translucent comparison bar. Line-type legends
+	// convey comparison via the dashed stroke (lineStyles) instead.
+	const barOpacity =
+		legendShape !== 'line' ? getSeriesBarStyles( series, index, theme ).opacity : undefined;
+	const barShapeStyles = barOpacity !== undefined ? { opacity: barOpacity } : {};
 	const themeShapeStyles = theme.legend?.shapeStyles?.[ index ];
 
-	const itemShapeStyles = {
+	// Series-level styles (custom shape style + line styles) take precedence; otherwise fall
+	// back to the per-index theme shape styles.
+	const explicitStyles = {
 		...seriesShapeStyles,
 		...lineStyles,
 	};
+	const hasExplicitStyles = Object.values( explicitStyles ).some(
+		value => value !== undefined && value !== null && value !== ''
+	);
+	const baseShapeStyles = hasExplicitStyles ? explicitStyles : themeShapeStyles ?? {};
 
-	// Return item shape styles if they are not empty
-	if (
-		Object.values( itemShapeStyles ).some(
-			value => value !== undefined && value !== null && value !== ''
-		)
-	) {
-		return itemShapeStyles;
-	}
-
-	// Fallback to theme shape styles if defined
-	return themeShapeStyles ?? {};
+	// Layer the comparison bar opacity on top so the swatch matches the translucent bar
+	// without discarding the base (custom or theme) shape styles.
+	return { ...baseShapeStyles, ...barShapeStyles };
 }

package/src/utils/index.ts

@@ -13,7 +13,12 @@ export { formatPercentage } from './format-percentage';
 export { getLongestTickWidth } from './get-longest-tick-width';
 
 // Style and theming utilities
-export { getSeriesLineStyles, getSeriesStroke, getItemShapeStyles } from './get-styles';
+export {
+	getSeriesBarStyles,
+	getSeriesLineStyles,
+	getSeriesStroke,
+	getItemShapeStyles,
+} from './get-styles';
 
 // Browser detection utilities
 export { isSafari } from './is-safari';

package/src/utils/test/get-styles.test.ts

@@ -1,5 +1,10 @@
 import { ChartTheme } from '../../types';
-import { getSeriesLineStyles, getSeriesStroke, getItemShapeStyles } from '../get-styles';
+import {
+	getSeriesBarStyles,
+	getSeriesLineStyles,
+	getSeriesStroke,
+	getItemShapeStyles,
+} from '../get-styles';
 
 describe( 'Series styling utility functions', () => {
 	const mockSeriesData = {
@@ -157,6 +162,28 @@ describe( 'Series styling utility functions', () => {
 			expect( result ).toEqual( mockTheme.legend.shapeStyles[ 0 ] );
 		} );
 
+		it( 'applies the comparison bar opacity to the swatch for non-line legends', () => {
+			const themeWithBar = {
+				...mockTheme,
+				barChart: { barStyles: { comparison: { widthFactor: 1.5, opacity: 0.5 } } },
+				// No per-index legend shape styles, so the swatch reflects only the comparison opacity.
+				legend: { shapeStyles: [] },
+			} as ChartTheme;
+			const comparisonSeries = {
+				...mockSeriesData,
+				options: { type: 'comparison' as const },
+			};
+
+			// rect (bar) legend: swatch picks up the comparison opacity to match the bar.
+			const rectResult = getItemShapeStyles( comparisonSeries, 0, themeWithBar, 'rect' );
+			expect( rectResult ).toEqual( { opacity: 0.5 } );
+
+			// line legend: comparison is conveyed via the dashed stroke, not opacity.
+			const lineResult = getItemShapeStyles( comparisonSeries, 0, themeWithBar, 'line' );
+			expect( lineResult.opacity ).toBeUndefined();
+			expect( lineResult ).toMatchObject( { strokeDasharray: '4 4' } );
+		} );
+
 		it( 'merges custom shape styles with line styles for line shape', () => {
 			const customShapeStyle = { fill: '#CUSTOM' };
 			const comparisonSeries = {
@@ -330,4 +357,23 @@ describe( 'Series styling utility functions', () => {
 			} );
 		} );
 	} );
+
+	describe( 'getSeriesBarStyles', () => {
+		const themeWithBar = {
+			...mockTheme,
+			barChart: { barStyles: { comparison: { widthFactor: 1.5, opacity: 0.5 } } },
+		} as ChartTheme;
+
+		it( 'returns comparison bar styles when type is comparison', () => {
+			const comparisonSeries = { ...mockSeriesData, options: { type: 'comparison' as const } };
+			expect( getSeriesBarStyles( comparisonSeries, 0, themeWithBar ) ).toEqual( {
+				widthFactor: 1.5,
+				opacity: 0.5,
+			} );
+		} );
+
+		it( 'returns empty styles for a series with no type', () => {
+			expect( getSeriesBarStyles( mockSeriesData, 0, themeWithBar ) ).toEqual( {} );
+		} );
+	} );
 } );