@automattic/charts 4.3.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "4.3.0",
+	"version": "4.4.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {

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

@@ -35,6 +35,7 @@ import {
 	useBarChartOptions,
 	BandHighlight,
 	BandTooltip,
+	ClassifiedBarSeries,
 	ComparisonBars,
 	DEFAULT_COMPARISON_WIDTH_FACTOR,
 	COMPARISON_INNER_GAP,
@@ -111,6 +112,8 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	renderTooltip,
 	tooltipPlacement,
 	tooltipAnchorTop,
+	tooltipStyle,
+	barClassName,
 	options = {},
 	orientation = 'vertical',
 	withPatterns = false,
@@ -704,19 +707,37 @@ const BarChartInternal: FC< BarChartProps > = ( {
 											resolveFill={ resolveComparisonFill }
 										/>
 
-										<BarGroup padding={ groupPadding }>
-											{ primaryEntries.map( ( { series: seriesData, index } ) => (
-												<BarSeries
-													key={ seriesData?.label }
-													dataKey={ seriesData?.label }
-													data={ seriesData.data as DataPointDate[] }
-													yAccessor={ chartOptions.accessors.yAccessor }
-													xAccessor={ chartOptions.accessors.xAccessor }
-													colorAccessor={ getBarBackground( index ) }
-												/>
-											) ) }
-										</BarGroup>
-										{ /* Do not reorder: for one key the last showTooltip wins, so this must run after BarGroup. */ }
+										{ barClassName ? (
+											<g className="visx-bar-group">
+												{ primaryEntries.map( ( { series: seriesData, index } ) => (
+													<ClassifiedBarSeries
+														key={ seriesData.label }
+														dataKey={ seriesData.label }
+														data={ seriesData.data as DataPointDate[] }
+														xAccessor={ chartOptions.accessors.xAccessor }
+														yAccessor={ chartOptions.accessors.yAccessor }
+														colorAccessor={ getBarBackground( index ) }
+														barClassName={ barClassName }
+														primaryKeys={ primaryKeys }
+														groupPadding={ groupPadding }
+													/>
+												) ) }
+											</g>
+										) : (
+											<BarGroup padding={ groupPadding }>
+												{ primaryEntries.map( ( { series: seriesData, index } ) => (
+													<BarSeries
+														key={ seriesData?.label }
+														dataKey={ seriesData?.label }
+														data={ seriesData.data as DataPointDate[] }
+														yAccessor={ chartOptions.accessors.yAccessor }
+														xAccessor={ chartOptions.accessors.xAccessor }
+														colorAccessor={ getBarBackground( index ) }
+													/>
+												) ) }
+											</BarGroup>
+										) }
+										{ /* Do not reorder: for one key the last showTooltip wins, so this must run after the primary series. */ }
 										{ ( withTooltips || onPointerDown || onPointerUp ) && (
 											<BandTooltip
 												keys={ primaryKeys }
@@ -753,6 +774,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 											<AccessibleTooltip
 												tooltipPlacement={ tooltipPlacement }
 												tooltipAnchorTop={ tooltipAnchorTop }
+												style={ tooltipStyle }
 												detectBounds
 												snapTooltipToDatumX
 												snapTooltipToDatumY

package/src/charts/bar-chart/private/classified-bar-series.tsx

@@ -0,0 +1,85 @@
+import { DataContext, GlyphSeries } from '@visx/xychart';
+import clsx from 'clsx';
+import { useCallback, useContext, useMemo } from 'react';
+import { createGroupScale } from './band-scale';
+import { 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: NonNullable< BarChartProps[ 'barClassName' ] >;
+	primaryKeys: string[];
+	groupPadding: number;
+};
+
+const ClassifiedBarSeries = ( { barClassName, primaryKeys, 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( primaryKeys, bandScale?.bandwidth?.() ?? 0, groupPadding ),
+		[ primaryKeys, bandScale, groupPadding ]
+	);
+	const renderGlyph = useCallback(
+		( {
+			datum,
+			x,
+			y,
+			color,
+			onBlur,
+			onFocus,
+			onPointerMove,
+			onPointerOut,
+			onPointerUp,
+		}: GlyphProps< DataPointDate > ) => {
+			if ( ! bandScale?.bandwidth || ! valueScale ) return null;
+			const baseline = getValueScaleBaseline(
+				valueScale as Parameters< typeof getValueScaleBaseline >[ 0 ]
+			);
+			const position =
+				Number( bandScale( ( horizontal ? props.yAccessor : props.xAccessor )( datum ) ) ) +
+				( groupScale( props.dataKey ) ?? 0 );
+			const value = horizontal ? x : y;
+			return (
+				<rect
+					className={ clsx( 'visx-bar', barClassName( datum ) ) }
+					// visx's own Bars makes a bar focusable on the same condition.
+					tabIndex={ onFocus || onBlur ? 0 : undefined }
+					onBlur={ onBlur }
+					onFocus={ onFocus }
+					onPointerMove={ onPointerMove }
+					onPointerOut={ onPointerOut }
+					onPointerUp={ onPointerUp }
+					// Same arithmetic as visx BaseBarGroup, so rounding matches the unclassified bars.
+					x={ horizontal ? baseline + Math.min( 0, value - baseline ) : position }
+					y={ horizontal ? position : baseline + Math.min( 0, value - baseline ) }
+					width={ horizontal ? Math.abs( value - baseline ) : groupScale.bandwidth() }
+					height={ horizontal ? groupScale.bandwidth() : Math.abs( value - baseline ) }
+					fill={ color }
+				/>
+			);
+		},
+		[
+			bandScale,
+			valueScale,
+			horizontal,
+			groupScale,
+			props.dataKey,
+			props.xAccessor,
+			props.yAccessor,
+			barClassName,
+		]
+	);
+	return <GlyphSeries { ...props } renderGlyph={ renderGlyph } />;
+};
+
+export default ClassifiedBarSeries;

package/src/charts/bar-chart/private/comparison-bars-geometry.ts

@@ -3,9 +3,8 @@ export type ComparisonRect = { x: number; y: number; width: number; height: numb
 type ValueScale = ( ( v: number ) => number ) & { range: () => unknown[] };
 
 /**
- * Output position of a value scale's baseline: zero if in-domain, else the
- * nearest range edge. Mirrors visx's getScaleBaseline so comparison shadows
- * sit on the same baseline as primary bars.
+ * Mirrors visx's getScaleBaseline so comparison shadows and primary bars
+ * share the same baseline, including out-of-domain zero values.
  *
  * @param {ValueScale} scale - The continuous value scale.
  * @return {number} The baseline output position in pixels.
@@ -20,9 +19,7 @@ export function getValueScaleBaseline( scale: ValueScale ): number {
 			? Math.min( Math.max( minOutput, maybeZero ), maxOutput )
 			: maxOutput;
 	}
-	return Number.isFinite( maybeZero )
-		? Math.min( Math.max( maybeZero, minOutput ), maxOutput )
-		: minOutput;
+	return Number.isFinite( maybeZero ) ? Math.max( maybeZero, minOutput ) : minOutput;
 }
 
 /**

package/src/charts/bar-chart/private/index.ts

@@ -1,5 +1,6 @@
 export { useBarChartOptions } from './use-bar-chart-options';
 export { TruncatedXTickComponent, TruncatedYTickComponent } from './truncated-tick-component';
+export { default as ClassifiedBarSeries } from './classified-bar-series';
 export { ComparisonBars } from './comparison-bars';
 export type { ComparisonSeriesEntry } from './comparison-bars';
 export {

package/src/charts/bar-chart/private/test/comparison-bars-geometry.test.ts

@@ -9,12 +9,11 @@ describe( 'getValueScaleBaseline', () => {
 		expect( getValueScaleBaseline( scale ) ).toBe( 200 );
 	} );
 
-	it( 'clamps to the end (range max) when 0 is outside an ascending range scale', () => {
+	it( 'preserves an out-of-range zero baseline for an ascending scale', () => {
 		// horizontal linear scale: range [0, 200], domain [-100, -10] (zero excluded)
 		const scale = ( ( v: number ) => ( ( v + 100 ) / 90 ) * 200 ) as never;
 		( scale as { range: () => number[] } ).range = () => [ 0, 200 ];
-		// scale(0) = (100/90)*200 ≈ 222 -> clamped to 200
-		expect( getValueScaleBaseline( scale ) ).toBe( 200 );
+		expect( getValueScaleBaseline( scale ) ).toBeCloseTo( 222.222222 );
 	} );
 } );
 

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

@@ -14,7 +14,7 @@ import { steadyTrafficData } from '../../../stories/sample-data';
 import BarChart, { BarChartUnresponsive } from '../bar-chart';
 import { useBarChartOptions } from '../private';
 import type { GlobalChartsContextValue } from '../../../providers/chart-context/types';
-import type { SeriesData } from '../../../types';
+import type { DataPointDate, SeriesData } from '../../../types';
 
 // Mock useElementSize to return non-zero dimensions in jsdom so charts render
 const mockRefCallback = jest.fn();
@@ -60,6 +60,70 @@ describe( 'BarChart', () => {
 		);
 	};
 
+	test.each(
+		[ 'vertical', 'horizontal' ].flatMap( orientation =>
+			[
+				[ 10, 20, 30 ],
+				[ -20, -10, -30 ],
+				[ -20, 10, 30 ],
+			].map( values => ( { orientation, values } ) )
+		)
+	)(
+		'adds datum classes without changing $orientation bar attributes for $values',
+		async ( { orientation, values } ) => {
+			const series = {
+				...defaultProps.data[ 0 ],
+				data: defaultProps.data[ 0 ].data.map( ( datum, index ) => ( {
+					...datum,
+					value: values[ index ],
+				} ) ),
+			};
+			const props = {
+				orientation,
+				data: [ series, { ...series, label: 'Series B' } ],
+			};
+			const view = renderWithTheme( props );
+			await waitFor( () => expect( getBarRects() ).toHaveLength( 6 ) );
+			const attributes = () =>
+				Array.from( getBarRects(), bar =>
+					[ 'x', 'y', 'width', 'height', 'fill', 'tabindex' ].map( attribute =>
+						bar.getAttribute( attribute )
+					)
+				);
+			const original = attributes();
+			view.unmount();
+			renderWithTheme( {
+				...props,
+				barClassName: ( datum: DataPointDate ) =>
+					datum.value === values[ 0 ] ? 'first-value' : undefined,
+			} );
+			await waitFor( () => expect( getBarRects() ).toHaveLength( 6 ) );
+			expect( attributes() ).toEqual( original );
+			expect( getBarRects()[ 0 ] ).toHaveClass( 'visx-bar', 'first-value' );
+			expect( getBarRects()[ 1 ] ).not.toHaveClass( 'first-value' );
+			expect( getBarRects()[ 3 ] ).toHaveClass( 'first-value' );
+		}
+	);
+
+	test( 'applies tooltip style overrides while keeping keyboard tooltip content', async () => {
+		const user = userEvent.setup();
+		renderWithTheme( {
+			withTooltips: true,
+			barClassName: () => 'styled-bar',
+			tooltipStyle: { padding: 0, backgroundColor: 'transparent', boxShadow: 'none' },
+		} );
+		await user.tab();
+		await user.keyboard( '{ArrowRight}' );
+		const tooltip = await screen.findByRole( 'tooltip' );
+		expect( tooltip ).toHaveTextContent( 'Jan 1' );
+		expect( screen.getByTestId( 'bounded-tooltip' ) ).toHaveStyle( {
+			padding: '0px',
+			// jsdom normalizes transparent in computed styles.
+			'background-color': 'rgba(0, 0, 0, 0)',
+			'box-shadow': 'none',
+		} );
+	} );
+
 	describe( 'pointer selection and focus return', () => {
 		const screenTransform = Object.getOwnPropertyDescriptor( SVGElement.prototype, 'getScreenCTM' );
 		beforeAll( () => {
@@ -677,6 +741,71 @@ describe( 'BarChart', () => {
 		} );
 	} );
 
+	describe( 'Grid tick counts', () => {
+		const getPositions = ( selector: string, coordinate: string ) => {
+			// eslint-disable-next-line testing-library/no-node-access -- See the visx node constraint above.
+			const lines = screen.getByRole( 'grid' ).querySelectorAll( selector );
+			return Array.from( lines, line => Number( line.getAttribute( coordinate ) ) );
+		};
+
+		test.each( [ 'x', 'y' ] )( 'aligns an explicit tick count with the %s axis', axis => {
+			renderWithTheme( {
+				data: [
+					{
+						label: 'Views',
+						data: Array.from( { length: 8 }, ( _, index ) => ( {
+							label: `Day ${ index + 1 }`,
+							value: ( index + 1 ) * 10,
+						} ) ),
+					},
+				],
+				gridVisibility: 'xy',
+				options: {
+					axis: { [ axis ]: { numTicks: 2, tickFormat: String, axisClassName: 'test-value-axis' } },
+				},
+			} );
+			const grid = getPositions(
+				axis === 'x' ? '.visx-columns line' : '.visx-rows line',
+				`${ axis }1`
+			);
+			const ticks = getPositions( '.test-value-axis .visx-axis-tick line', `${ axis }1` );
+			expect( ticks.length ).toBeGreaterThan( 0 );
+			expect( grid ).toEqual( ticks );
+		} );
+
+		test.each( [ false, true ] )(
+			'preserves the default tick count (horizontal=%s)',
+			horizontal => {
+				const axis = horizontal ? 'x' : 'y';
+				const positionsFor = ( axisOptions: object ) => {
+					const { unmount } = renderWithTheme( {
+						orientation: horizontal ? 'horizontal' : 'vertical',
+						gridVisibility: 'xy',
+						options: {
+							axis: { [ axis ]: { axisClassName: 'test-value-axis', ...axisOptions } },
+						},
+					} );
+					const positions = {
+						grid: getPositions(
+							horizontal ? '.visx-columns line' : '.visx-rows line',
+							`${ axis }1`
+						),
+						ticks: getPositions( '.test-value-axis .visx-axis-tick line', `${ axis }1` ),
+					};
+					unmount();
+					return positions;
+				};
+
+				const omitted = positionsFor( {} );
+				const explicit = positionsFor( { numTicks: 4 } );
+
+				expect( omitted.ticks.length ).toBeGreaterThan( 0 );
+				expect( omitted.grid ).toEqual( omitted.ticks );
+				expect( omitted.grid ).toEqual( explicit.grid );
+			}
+		);
+	} );
+
 	describe( 'Grid Visibility', () => {
 		test( 'renders with different grid visibility options', () => {
 			const { rerender } = renderWithTheme( { gridVisibility: 'x' } );

package/src/charts/bar-chart/types.ts

@@ -6,7 +6,7 @@ import type {
 	SeriesVisibilityProps,
 } from '../../types';
 import type { RenderTooltipParams } from '../../visx/types';
-import type { ReactNode } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 
 export type BandHighlightSelection = {
 	datum: DataPointDate;
@@ -28,6 +28,10 @@ export interface BarChartProps extends BaseChartProps< SeriesData[] >, SeriesVis
 	tooltipPlacement?: 'auto' | 'beside';
 	/** Tooltip top anchor in SVG coordinates; negative offsets are supported. */
 	tooltipAnchorTop?: number;
+	/** Inline styles merged over the tooltip box defaults. */
+	tooltipStyle?: CSSProperties;
+	/** CSS class for each primary bar, in addition to visx-bar. */
+	barClassName?: ( datum: DataPointDate ) => string | undefined;
 	orientation?: 'horizontal' | 'vertical';
 	withPatterns?: boolean;
 	showZeroValues?: boolean;