@automattic/charts 3.1.1 → 4.0.0

package/src/charts/bar-chart/private/test/use-bar-chart-options-formatting.test.tsx

@@ -0,0 +1,69 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { renderHook } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../../providers';
+import { useBarChartOptions } from '../use-bar-chart-options';
+import type { SeriesData } from '../../../../types';
+import type { ReactNode } from 'react';
+
+// The runtime locale stays en-US: a bucket labeled in German, on Tokyo's
+// calendar day, can only come from the provider.
+
+// 15:30 UTC is Aug 2 in Los Angeles and Aug 3 in Tokyo.
+const START = new Date( '2026-08-02T15:30:00Z' );
+
+const daily: SeriesData[] = [
+	{
+		label: 'Series A',
+		data: Array.from( { length: 14 }, ( _, i ) => ( {
+			date: new Date( START.getTime() + i * 24 * 60 * 60 * 1000 ),
+			value: 10 + i,
+		} ) ),
+		options: {},
+	},
+];
+
+const withProvider =
+	( props: { locale?: string; timeZone?: string } = {} ) =>
+	( { children }: { children: ReactNode } ) => (
+		<GlobalChartsProvider { ...props }>{ children }</GlobalChartsProvider>
+	);
+
+const optionsFor = (
+	props?: { locale?: string; timeZone?: string },
+	options?: Parameters< typeof useBarChartOptions >[ 2 ]
+) =>
+	renderHook( () => useBarChartOptions( daily, false, options ), {
+		wrapper: withProvider( props ),
+	} ).result.current;
+
+describe( 'useBarChartOptions with a host formatting context', () => {
+	it( 'labels the tooltip bucket in the provider locale and time zone', () => {
+		const { tooltip } = optionsFor( { locale: 'de-DE', timeZone: 'Asia/Tokyo' } );
+
+		expect( tooltip.labelFormatter( START.getTime(), 0, [] ) ).toBe( '3. August 2026' );
+	} );
+
+	it( 'labels a weekly bucket in the provider locale and time zone', () => {
+		const { tooltip } = optionsFor(
+			{ locale: 'de-DE', timeZone: 'Asia/Tokyo' },
+			{ axis: { x: { tickResolution: 'week' } } }
+		);
+
+		expect( tooltip.labelFormatter( START.getTime(), 0, [] ) ).toBe( 'Week of 3. August 2026' );
+	} );
+
+	it( 'labels the axis ticks in the provider locale and time zone', () => {
+		const { axis } = optionsFor( { locale: 'de-DE', timeZone: 'Asia/Tokyo' } );
+
+		expect( axis.x.tickFormat( START, 0, [] ) ).toBe( '3. Aug.' );
+	} );
+
+	it( 'falls back to the runtime locale and zone when the provider supplies none', () => {
+		const { tooltip, axis } = optionsFor();
+
+		expect( tooltip.labelFormatter( START.getTime(), 0, [] ) ).toBe( 'August 2, 2026' );
+		expect( axis.x.tickFormat( START, 0, [] ) ).toBe( 'Aug 2' );
+	} );
+} );

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

@@ -2,10 +2,19 @@ import { formatNumberCompact } from '@automattic/number-formatters';
 import { __, sprintf } from '@wordpress/i18n';
 import { useMemo } from 'react';
 import { useDeepMemo } from '../../../hooks';
-import { getBandTickValues, getBucketResolution, getFormatter } from '../../private/time-axis';
+import { useChartFormatting } from '../../../providers';
+import { getBucketResolution } from '../../../utils/bucket-info';
+import { createDateFormatter } from '../../../utils/date-formatting';
+import { getBandTickValues, getFormatter } from '../../private/time-axis';
 import { TruncatedXTickComponent, TruncatedYTickComponent } from './truncated-tick-component';
 import type { EnhancedDataPoint } from '../../../hooks/use-zero-value-display';
-import type { DataPointDate, BaseChartProps, SeriesData, TickResolution } from '../../../types';
+import type {
+	DataPointDate,
+	BaseChartProps,
+	ChartFormatting,
+	SeriesData,
+	TickResolution,
+} from '../../../types';
 import type { TickFormatter } from '@visx/axis';
 
 /** Outer padding of the category band scale (space at the chart edges). */
@@ -24,7 +33,7 @@ const TOOLTIP_FORMAT_BY_RESOLUTION: Record<
 	Exclude< TickResolution, 'week' >,
 	Intl.DateTimeFormatOptions
 > = {
-	hour: { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', hour12: true },
+	hour: { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric' },
 	day: { year: 'numeric', month: 'long', day: 'numeric' },
 	month: { year: 'numeric', month: 'long' },
 	year: { year: 'numeric' },
@@ -36,31 +45,33 @@ const TOOLTIP_FORMAT_BY_RESOLUTION: Record<
  *
  * @param data           - Date-based series, already parsed and sorted by `useChartDataTransform`.
  * @param tickResolution - Caller-declared bucket resolution, when known.
+ * @param formatting     - Host locale and time zone.
  * @return Tooltip label formatter.
  */
-const getTooltipFormatter = ( data: SeriesData[], tickResolution?: TickResolution ) => {
+const getTooltipFormatter = (
+	data: SeriesData[],
+	tickResolution: TickResolution | undefined,
+	formatting: ChartFormatting
+) => {
 	// Only a declared 'week' reaches this branch: seven-day spacing is
 	// indistinguishable from sparse daily data, so inference reports 'day'.
 	if ( tickResolution === 'week' ) {
+		const formatDay = createDateFormatter( TOOLTIP_FORMAT_BY_RESOLUTION.day, formatting );
 		return ( timestamp: number ) =>
 			sprintf(
 				/* translators: %s is the first day of the week the bar covers. */
 				__( 'Week of %s', 'jetpack-charts' ),
-				new Date( timestamp ).toLocaleDateString( undefined, {
-					year: 'numeric',
-					month: 'long',
-					day: 'numeric',
-				} )
+				formatDay( timestamp )
 			);
 	}
 
-	// Fall back to the day format rather than `undefined` options, which would
-	// print a full locale date-time for an unrecognised `tickResolution`.
+	// Fall back to the day format rather than empty options, which would print a
+	// bare numeric date for an unrecognized `tickResolution`.
 	const format =
 		TOOLTIP_FORMAT_BY_RESOLUTION[ getBucketResolution( data, tickResolution ) ] ??
 		TOOLTIP_FORMAT_BY_RESOLUTION.day;
 
-	return ( timestamp: number ) => new Date( timestamp ).toLocaleString( undefined, format );
+	return createDateFormatter( format, formatting );
 };
 
 const identity = ( label: string ) => label;
@@ -152,6 +163,7 @@ export function useBarChartOptions(
 	// Callers reasonably pass an object literal, which is a fresh reference every
 	// render and would defeat every memo below.
 	const stableOptions = useDeepMemo( options );
+	const formatting = useChartFormatting();
 
 	// `labelOverflow` and `tickResolution` are consumed by this hook rather than
 	// forwarded — visx has an axis prop for neither — and `tickFormat` is merged
@@ -202,11 +214,11 @@ export function useBarChartOptions(
 		// formatter, which narrows with the overall span as well as the bucket
 		// size; the tooltip stays at the bucket's own granularity.
 		const hasLabels = Boolean( data?.[ 0 ]?.data?.[ 0 ]?.label );
-		const timeTickFormatter = hasLabels ? null : getFormatter( data, tickResolution );
+		const timeTickFormatter = hasLabels ? null : getFormatter( data, tickResolution, formatting );
 		const labelFormatter = timeTickFormatter ? byBucket( timeTickFormatter ) : identity;
 		const tooltipDatumFormatter = hasLabels
 			? labelFormatter
-			: byBucket( getTooltipFormatter( data, tickResolution ) );
+			: byBucket( getTooltipFormatter( data, tickResolution, formatting ) );
 		const valueFormatter = formatNumberCompact as TickFormatter< unknown >;
 
 		const bandDomain = timeTickFormatter ? getBandDomain( data, isSeriesRendered ) : null;
@@ -244,7 +256,7 @@ export function useBarChartOptions(
 				yScale: bandScale,
 			},
 		};
-	}, [ data, tickResolution, isSeriesRendered ] );
+	}, [ data, tickResolution, isSeriesRendered, formatting ] );
 
 	return useMemo( () => {
 		const orientationKey = horizontal ? 'horizontal' : 'vertical';

package/src/charts/bar-chart/test/bar-chart-pointer-events.test.tsx

@@ -0,0 +1,67 @@
+import { render } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../providers';
+import BarChart from '../bar-chart';
+import type { ReactNode } from 'react';
+
+// jsdom gives every element a zero-sized box, so visx can never resolve a
+// pointer to a datum here. Standing `XYChart` in for a prop recorder keeps this
+// test on the part jsdom can answer: that the handlers reach the chart at all.
+// Whether a bar then reports the datum under the pointer is a browser question.
+const mockXYChart = jest.fn();
+jest.mock( '@visx/xychart', () => {
+	const actual = jest.requireActual( '@visx/xychart' );
+
+	return {
+		__esModule: true,
+		...actual,
+		XYChart: ( props: { children?: ReactNode } ) => {
+			mockXYChart( props );
+			return <svg />;
+		},
+	};
+} );
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+const DATA = [
+	{
+		label: 'Series A',
+		data: [
+			{ date: new Date( '2024-01-01' ), value: 10 },
+			{ date: new Date( '2024-01-02' ), value: 20 },
+		],
+		options: {},
+	},
+];
+
+/**
+ * Render the chart with the recorder standing in for `XYChart`.
+ *
+ * @param props - Props layered onto the defaults.
+ * @return The render result.
+ */
+function renderBarChart( props = {} ) {
+	return render(
+		<GlobalChartsProvider>
+			<BarChart width={ 500 } height={ 300 } data={ DATA } { ...props } />
+		</GlobalChartsProvider>
+	);
+}
+
+describe( 'BarChart pointer events', () => {
+	beforeEach( () => mockXYChart.mockClear() );
+
+	test( 'hands the pointer handlers to the chart, so a bar can be clicked', () => {
+		const onPointerDown = jest.fn();
+		const onPointerUp = jest.fn();
+
+		renderBarChart( { onPointerDown, onPointerUp } );
+
+		const props = mockXYChart.mock.calls.at( -1 )[ 0 ];
+		expect( props.onPointerDown ).toBe( onPointerDown );
+		expect( props.onPointerUp ).toBe( onPointerUp );
+	} );
+} );

package/src/charts/bar-chart/test/bar-chart.test.tsx

@@ -996,6 +996,85 @@ describe( 'BarChart', () => {
 			} );
 		} );
 
+		describe( 'Activation', () => {
+			const SERIES_A = {
+				label: 'Series A',
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 10 },
+					{ date: new Date( '2024-01-02' ), value: 20 },
+				],
+				options: {},
+			};
+			const SERIES_B = {
+				label: 'Series B',
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 15 },
+					{ date: new Date( '2024-01-02' ), value: 25 },
+				],
+				options: {},
+			};
+
+			test( 'Enter hands the selected bar to onDatumActivate', async () => {
+				const user = userEvent.setup();
+				const onDatumActivate = jest.fn();
+				renderWithTheme( { withTooltips: true, data: [ SERIES_A ], onDatumActivate } );
+
+				screen.getByRole( 'grid', { name: /bar chart/i } ).focus();
+				await user.keyboard( '{ArrowRight}{ArrowRight}{Enter}' );
+
+				expect( onDatumActivate ).toHaveBeenCalledTimes( 1 );
+				expect( onDatumActivate ).toHaveBeenCalledWith( {
+					datum: SERIES_A.data[ 1 ],
+					index: 1,
+					key: 'Series A',
+				} );
+			} );
+
+			test( 'Space activates the selected bar too', async () => {
+				const user = userEvent.setup();
+				const onDatumActivate = jest.fn();
+				renderWithTheme( { withTooltips: true, data: [ SERIES_A ], onDatumActivate } );
+
+				screen.getByRole( 'grid', { name: /bar chart/i } ).focus();
+				await user.keyboard( '{ArrowRight}[Space]' );
+
+				expect( onDatumActivate ).toHaveBeenCalledWith( {
+					datum: SERIES_A.data[ 0 ],
+					index: 0,
+					key: 'Series A',
+				} );
+			} );
+
+			// The navigation index strides series-major within each data point, the
+			// order the highlight outlines bars in, so the second stop is the second
+			// series' first bar.
+			test( 'walks the series at each data point before the next point', async () => {
+				const user = userEvent.setup();
+				const onDatumActivate = jest.fn();
+				renderWithTheme( { withTooltips: true, data: [ SERIES_A, SERIES_B ], onDatumActivate } );
+
+				screen.getByRole( 'grid', { name: /bar chart/i } ).focus();
+				await user.keyboard( '{ArrowRight}{ArrowRight}{Enter}' );
+
+				expect( onDatumActivate ).toHaveBeenCalledWith( {
+					datum: SERIES_B.data[ 0 ],
+					index: 0,
+					key: 'Series B',
+				} );
+			} );
+
+			test( 'Enter with no bar selected activates nothing', async () => {
+				const user = userEvent.setup();
+				const onDatumActivate = jest.fn();
+				renderWithTheme( { withTooltips: true, data: [ SERIES_A ], onDatumActivate } );
+
+				screen.getByRole( 'grid', { name: /bar chart/i } ).focus();
+				await user.keyboard( '{Enter}' );
+
+				expect( onDatumActivate ).not.toHaveBeenCalled();
+			} );
+		} );
+
 		describe( 'Arrow Key Navigation', () => {
 			test( 'right arrow key navigates to next data point', async () => {
 				const user = userEvent.setup();

package/src/charts/bar-list-chart/bar-list-chart.tsx

@@ -2,8 +2,10 @@ import { formatNumberCompact } from '@automattic/number-formatters';
 import { Group } from '@visx/group';
 import { createScale, scaleBand } from '@visx/scale';
 import { Text, type TextProps } from '@visx/text';
+import clsx from 'clsx';
 import { useContext, useMemo } from 'react';
-import { GlobalChartsContext, GlobalChartsProvider } from '../../providers';
+import { GlobalChartsContext, GlobalChartsProvider, useGlobalChartsContext } from '../../providers';
+import { isValidHexColor, lightenHexColor } from '../../utils';
 import { BarChartUnresponsive } from '../bar-chart';
 import { withResponsive } from '../private/with-responsive';
 import type { SeriesData } from '../..';
@@ -211,6 +213,14 @@ const getDefaultYOffset = (
 	return -( barThickness + GAP_BETWEEN_BARS );
 };
 
+// How far a single-series bar fill travels from white toward the series color.
+//
+// With one series the label is drawn *on* the bar, so the fill is a text background and has to keep
+// contrast with `--a8c-charts-color-label`. At full strength the catalog seed `#3858e9` leaves
+// `#1e1e1e` at 2.97:1; this puts it at 9.0:1. Multi-series bars keep full strength — the label is
+// lifted clear of them, so nothing is read against the fill.
+const BAR_TINT_TOWARD_SERIES = 0.4;
+
 const BarListChartInternal: FC< BarListChartProps > = ( {
 	data,
 	width,
@@ -222,8 +232,38 @@ const BarListChartInternal: FC< BarListChartProps > = ( {
 		bottom: 0,
 		top: 0,
 	},
+	className,
 	...rest
 } ) => {
+	const { getElementStyles } = useGlobalChartsContext();
+
+	// A series carrying its own stroke is left alone — the consumer asked for that exact color.
+	const tintedData = useMemo( () => {
+		if ( data.length > 1 ) {
+			return data;
+		}
+
+		return data.map( ( series, index ) => {
+			if ( series.options?.stroke ) {
+				return series;
+			}
+
+			const { color } = getElementStyles( { data: series, index } );
+
+			if ( ! isValidHexColor( color ) ) {
+				return series;
+			}
+
+			return {
+				...series,
+				options: {
+					...series.options,
+					stroke: lightenHexColor( color, 1 - BAR_TINT_TOWARD_SERIES ),
+				},
+			};
+		} );
+	}, [ data, getElementStyles ] );
+
 	const chartOptions = useMemo( () => {
 		const isMultiSeries = data.length > 1;
 
@@ -260,7 +300,10 @@ const BarListChartInternal: FC< BarListChartProps > = ( {
 		<BarChartUnresponsive
 			orientation="horizontal"
 			gridVisibility={ 'none' }
-			data={ data }
+			// The root carries `bar-chart` too, since a bar list renders through one. This class is
+			// how a consumer reaches a bar list without reaching every bar chart.
+			className={ clsx( 'bar-list-chart', className ) }
+			data={ tintedData }
 			width={ width }
 			height={ height }
 			margin={ margin }

package/src/charts/bar-list-chart/test/bar-list-chart.test.tsx

@@ -66,4 +66,42 @@ describe( 'BarListChart', () => {
 		renderChart( { data: [] } );
 		expect( screen.queryByText( 'Behemoth hat ' ) ).not.toBeInTheDocument();
 	} );
+
+	describe( 'single-series bar tint', () => {
+		// visx renders the bars, so they carry no attribute of our own to query by.
+		/* eslint-disable testing-library/no-node-access */
+		const barFills = () =>
+			Array.from(
+				screen.getByRole( 'grid' ).querySelectorAll< SVGRectElement >( '.visx-bar-group rect' )
+			).map( bar => bar.getAttribute( 'fill' ) );
+		/* eslint-enable testing-library/no-node-access */
+
+		// `lightenHexColor( '#3858e9', 1 - BAR_TINT_TOWARD_SERIES )` — the catalog seed traveling
+		// 40% from white toward the series color. Asserted as a literal so a change to the tint has
+		// to be made deliberately here rather than tracking the implementation.
+		const TINTED_SEED = '#afbcf6';
+
+		test( 'tints the bar so the label it carries stays readable', () => {
+			renderChart();
+			expect( barFills() ).not.toHaveLength( 0 );
+			barFills().forEach( fill => expect( fill ).toBe( TINTED_SEED ) );
+		} );
+
+		test( 'leaves a series carrying its own stroke at full strength', () => {
+			renderChart( {
+				data: salesByProduct.map( series => ( {
+					...series,
+					options: { ...series.options, stroke: '#ff0000' },
+				} ) ),
+			} );
+			expect( barFills() ).not.toHaveLength( 0 );
+			barFills().forEach( fill => expect( fill ).toBe( '#ff0000' ) );
+		} );
+
+		test( 'leaves multi-series bars at full strength, where the label is lifted clear', () => {
+			renderChart( { data: salesByChannel } );
+			expect( barFills() ).not.toHaveLength( 0 );
+			expect( barFills() ).not.toContain( TINTED_SEED );
+		} );
+	} );
 } );

package/src/charts/conversion-funnel-chart/conversion-funnel-chart.module.scss

@@ -1,4 +1,5 @@
 .conversion-funnel-chart {
+	position: relative;
 
 	&--loading {
 		opacity: 0.6;
@@ -14,21 +15,29 @@
 	overflow: hidden;
 	color: var(--a8c-charts-color-label);
 	text-overflow: ellipsis;
-	font-size: var(--wpds-typography-font-size-xl, 20px);
+	font-size: var(--wpds-typography-font-size-xl);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
-	line-height: var(--wpds-typography-line-height-sm, 20px);
+	font-weight: var(--wpds-typography-font-weight-emphasis);
+	line-height: var(--wpds-typography-line-height-sm);
 	margin: 0;
 }
 
 .change-indicator {
 	overflow: hidden;
 	text-overflow: ellipsis;
-	font-size: var(--wpds-typography-font-size-md, 13px);
+	font-size: var(--wpds-typography-font-size-md);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
-	line-height: var(--wpds-typography-line-height-sm, 20px);
+	font-weight: var(--wpds-typography-font-weight-emphasis);
+	line-height: var(--wpds-typography-line-height-sm);
 	margin: 0;
+
+	&--positive {
+		color: var(--a8c-charts-color-trend-up);
+	}
+
+	&--negative {
+		color: var(--a8c-charts-color-trend-down);
+	}
 }
 
 .funnel-container {
@@ -44,8 +53,8 @@
 
 	&--animated {
 		transition:
-			opacity var(--wpds-motion-duration-lg, 300ms)
-			var(--wpds-motion-easing-subtle, cubic-bezier(0.15, 0, 0.15, 1));
+			opacity var(--wpds-motion-duration-lg)
+			var(--wpds-motion-easing-subtle);
 	}
 
 	&--blurred {
@@ -55,9 +64,9 @@
 
 .step-label {
 	color: var(--a8c-charts-color-label-secondary);
-	font-size: var(--wpds-typography-font-size-sm, 12px);
-	font-weight: var(--wpds-typography-font-weight-default, 400);
-	line-height: var(--wpds-typography-line-height-xs, 16px);
+	font-size: var(--wpds-typography-font-size-sm);
+	font-weight: var(--wpds-typography-font-weight-default);
+	line-height: var(--wpds-typography-line-height-xs);
 	white-space: nowrap;
 	overflow: hidden;
 	text-overflow: ellipsis;
@@ -65,14 +74,15 @@
 
 .step-rate {
 	color: var(--a8c-charts-color-label);
-	font-size: var(--wpds-typography-font-size-md, 13px);
-	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
-	line-height: var(--wpds-typography-line-height-xs, 16px);
+	font-size: var(--wpds-typography-font-size-md);
+	font-weight: var(--wpds-typography-font-weight-emphasis);
+	line-height: var(--wpds-typography-line-height-xs);
 }
 
 .bar-container {
 	flex: 1;
 	border-radius: var(--a8c-charts-border-radius-bar);
+	background-color: var(--a8c-charts-color-surface-secondary);
 	position: relative;
 	cursor: pointer;
 }
@@ -108,30 +118,30 @@
 	background: var(--a8c-charts-color-surface);
 
 	// Override .visx-tooltip inline styles.
-	border-radius: var(--wpds-border-radius-md, 4px) !important;
-	padding: var(--wpds-dimension-padding-md, 12px) !important;
+	border-radius: var(--wpds-border-radius-md) !important;
+	padding: var(--wpds-dimension-padding-md) !important;
 	box-shadow: var(--a8c-charts-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005) !important;
 
 }
 
 .tooltip-title {
 	color: var(--a8c-charts-color-label);
-	font-size: var(--wpds-typography-font-size-sm, 12px);
+	font-size: var(--wpds-typography-font-size-sm);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-default, 400);
-	line-height: var(--wpds-typography-line-height-xs, 16px);
+	font-weight: var(--wpds-typography-font-weight-default);
+	line-height: var(--wpds-typography-line-height-xs);
 }
 
 .tooltip-content {
 	color: var(--a8c-charts-color-label);
-	font-size: var(--wpds-typography-font-size-md, 13px);
+	font-size: var(--wpds-typography-font-size-md);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-emphasis, 600);
-	line-height: var(--wpds-typography-line-height-sm, 20px);
+	font-weight: var(--wpds-typography-font-weight-emphasis);
+	line-height: var(--wpds-typography-line-height-sm);
 }
 
 .empty-state {
 	text-align: center;
 	color: var(--a8c-charts-color-label-secondary);
-	font-size: var(--wpds-typography-font-size-lg, 15px);
+	font-size: var(--wpds-typography-font-size-lg);
 }