@automattic/charts 4.1.1 → 4.3.0

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

@@ -3,7 +3,7 @@ import { DataContext, TooltipContext } from '@visx/xychart';
 import { useCallback, useContext, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { isValidHexColor } from '../../utils';
-import { BoundedTooltip } from './private/bounded-tooltip';
+import { BoundedTooltip, TOOLTIP_Z_INDEX } from './private/bounded-tooltip';
 import type {
 	CrosshairStyle,
 	RenderTooltipGlyphProps,
@@ -36,9 +36,6 @@ const crosshairPaintProps = ( props: CrosshairStyle = {} ) => {
 };
 const DEFAULT_GLYPH_RADIUS = 4;
 const FALLBACK_COLOR = '#222';
-// Above the chart's own overlays (the zoom reset button sits at 2). The chart
-// wrapper isolates its stacking context, so this never competes with page chrome.
-const DEFAULT_TOOLTIP_Z_INDEX = 3;
 // Portal-era options, accepted for compatibility and dropped before the box
 // renders: it sits in the chart wrapper and moves with it, and nothing
 // measures it any more.
@@ -110,7 +107,8 @@ const XyChartTooltipContent = < Datum extends object >( {
 	horizontalCrosshairStyle,
 	detectBounds = true,
 	tooltipPlacement = 'auto',
-	zIndex = DEFAULT_TOOLTIP_Z_INDEX,
+	tooltipAnchorTop,
+	zIndex = TOOLTIP_Z_INDEX,
 	style,
 	...rest
 }: XyChartTooltipContentProps< Datum > ) => {
@@ -171,7 +169,9 @@ const XyChartTooltipContent = < Datum extends object >( {
 		const size = Number( glyphStyle?.radius ?? DEFAULT_GLYPH_RADIUS );
 		const labelColor = theme?.htmlLabel?.color ?? FALLBACK_COLOR;
 		// visx colours a lone nearest-datum glyph like the gridlines and series glyphs like labels.
-		const fallbackColor = showSeriesGlyphs ? labelColor : theme?.gridStyles?.stroke ?? labelColor;
+		const fallbackColor = showSeriesGlyphs
+			? labelColor
+			: ( theme?.gridStyles?.stroke ?? labelColor );
 		let entries: Array< { key: string; datum: Datum; index: number } > = [];
 		if ( showSeriesGlyphs ) {
 			entries = Object.values( tooltipContext.tooltipData?.datumByKey ?? {} );
@@ -214,8 +214,7 @@ const XyChartTooltipContent = < Datum extends object >( {
 	const marginTop = margin?.top ?? 0;
 	const marginLeft = margin?.left ?? 0;
 
-	const TooltipComponent =
-		detectBounds || tooltipPlacement === 'below-axis' ? BoundedTooltip : Tooltip;
+	const TooltipComponent = detectBounds || tooltipPlacement !== 'auto' ? BoundedTooltip : Tooltip;
 	const boxStyle: CSSProperties = {
 		...defaultStyles,
 		zIndex,
@@ -265,12 +264,12 @@ const XyChartTooltipContent = < Datum extends object >( {
 						top={
 							tooltipPlacement === 'below-axis'
 								? marginTop + innerHeight + ( margin?.bottom ?? 0 )
-								: tooltipTop
+								: ( tooltipAnchorTop ?? tooltipTop )
 						}
 						style={ boxStyle }
 						applyPositionStyle
 						{ ...tooltipProps }
-						{ ...( tooltipPlacement === 'below-axis' && { placement: tooltipPlacement } ) }
+						{ ...( tooltipPlacement !== 'auto' && { placement: tooltipPlacement } ) }
 					>
 						{ tooltipContent }
 					</TooltipComponent>,

package/src/hooks/test/use-chart-margin.test.tsx

@@ -353,6 +353,41 @@ describe( 'useChartMargin', () => {
 
 			expect( result.current.left ).toBe( 20 );
 		} );
+
+		it( 'measures ticks from readings that exist', () => {
+			const partialData = [
+				{
+					label: 'Series 1',
+					data: [
+						{ date: new Date( '2024-01-01' ), value: null },
+						{ date: new Date( '2024-01-02' ), value: 100 },
+						{ date: new Date( '2024-01-03' ), value: 200 },
+					],
+				},
+			];
+
+			renderHook( () => useChartMargin( 300, optionsBase, partialData, baseTheme ) );
+
+			const ticks = mockGetLongestTickWidth.mock.calls[ 0 ][ 0 ] as number[];
+			expect( Math.min( ...ticks ) ).toBe( 100 );
+		} );
+
+		it( 'measures a unit range when no bucket has a reading', () => {
+			const allNullData = [
+				{
+					label: 'Series 1',
+					data: [
+						{ date: new Date( '2024-01-01' ), value: null },
+						{ date: new Date( '2024-01-02' ), value: null },
+					],
+				},
+			];
+
+			renderHook( () => useChartMargin( 300, optionsBase, allNullData, baseTheme ) );
+
+			const ticks = mockGetLongestTickWidth.mock.calls[ 0 ][ 0 ] as number[];
+			expect( Math.max( ...ticks ) ).toBe( 1 );
+		} );
 	} );
 
 	describe( 'horizontal y ticks', () => {

package/src/hooks/test/use-element-size.test.tsx

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { useElementSize } from '../use-element-size';
 
 // Mock ResizeObserver
@@ -66,7 +66,7 @@ describe( 'useElementSize', () => {
 		const [ refCallback ] = result.current;
 
 		// Attach the element
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 300 );
@@ -84,7 +84,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 0 );
@@ -100,7 +100,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 0 );
@@ -129,10 +129,10 @@ describe( 'useElementSize', () => {
 		const [ refCallback ] = result.current;
 
 		// Attach first element
-		refCallback( mockElement1 as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement1 as unknown as HTMLDivElement ) );
 
 		// Attach second element
-		refCallback( mockElement2 as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement2 as unknown as HTMLDivElement ) );
 
 		expect( disconnectSpy ).toHaveBeenCalled();
 	} );
@@ -155,10 +155,10 @@ describe( 'useElementSize', () => {
 		const [ refCallback ] = result.current;
 
 		// Attach element
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		// Remove element
-		refCallback( null as unknown as HTMLDivElement );
+		act( () => refCallback( null as unknown as HTMLDivElement ) );
 
 		expect( disconnectSpy ).toHaveBeenCalled();
 	} );
@@ -180,7 +180,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		expect( globalThis.ResizeObserver ).toHaveBeenCalled();
 		expect( observeSpy ).toHaveBeenCalledWith( mockElement );
@@ -207,7 +207,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockSpanElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockSpanElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 75 );
@@ -236,7 +236,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 100 );
@@ -244,7 +244,7 @@ describe( 'useElementSize', () => {
 		} );
 
 		// Simulate resize
-		resizeCallback();
+		act( () => resizeCallback() );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 200 );
@@ -269,7 +269,7 @@ describe( 'useElementSize', () => {
 		const { result, unmount } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 		unmount();
 
 		// The observer should be cleaned up when the hook unmounts

package/src/hooks/use-chart-margin.tsx

@@ -111,8 +111,13 @@ export const useChartMargin = (
 			return options.axis.y.tickValues;
 		}
 
-		const minY = Math.min( ...allDataPoints.map( d => d.value ) );
-		const maxY = Math.max( ...allDataPoints.map( d => d.value ) );
+		const values = allDataPoints
+			.map( d => d.value )
+			.filter(
+				( value ): value is number => typeof value === 'number' && Number.isFinite( value )
+			);
+		const minY = values.length ? Math.min( ...values ) : 0;
+		const maxY = values.length ? Math.max( ...values ) : 1;
 		const yScale = createScale( {
 			...options.yScale,
 			// A pinned domain is what the axis actually renders, so measure those

package/src/hooks/use-xychart-theme.ts

@@ -23,7 +23,7 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 		// One resolver for all three, so they share a single getComputedStyle call.
 		const resolve = createCssVariableResolver( scopeElement );
 		const resolveColor = ( value?: string ): string | undefined =>
-			value ? resolve( value ) ?? value : value;
+			value ? ( resolve( value ) ?? value ) : value;
 
 		const seriesColors: string[] = JSON.parse( seriesColorKey );
 

package/src/index.ts

@@ -10,7 +10,9 @@ export {
 	HeatmapChart,
 	HeatmapChartUnresponsive,
 	buildCalendarHeatmapData,
+	buildMonthCalendarHeatmapData,
 	useCalendarHeatmapData,
+	useMonthCalendarHeatmapData,
 } from './charts/heatmap-chart';
 export { LeaderboardChart, LeaderboardChartUnresponsive } from './charts/leaderboard-chart';
 export { LineChart, LineChartUnresponsive } from './charts/line-chart';
@@ -95,7 +97,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 } from './charts/bar-chart';
+export type { BarChartProps, BandHighlightSelection } from './charts/bar-chart';
 export type {
 	BarListChartProps,
 	RenderLabelProps,
@@ -112,10 +114,14 @@ export type {
 export type {
 	HeatmapChartProps,
 	HeatmapColumn,
+	HeatmapColumnGroup,
 	HeatmapCell,
 	HeatmapTooltipData,
 	CalendarHeatmapOptions,
 	CalendarHeatmapResult,
+	MonthCalendarHeatmapOptions,
+	MonthCalendarHeatmapRange,
+	MonthCalendarHeatmapResult,
 } from './charts/heatmap-chart';
 export type { LeaderboardChartProps } from './charts/leaderboard-chart';
 export type {

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

@@ -219,7 +219,7 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( {
 
 	const getElementStyles = useCallback< GlobalChartsContextValue[ 'getElementStyles' ] >(
 		( { data, index, overrideColor, legendShape } ) => {
-			const isSeriesData = data && typeof data === 'object' && 'data' in data && 'options' in data;
+			const isSeriesData = data && typeof data === 'object' && 'data' in data;
 			// DataPointPercentage has a numeric 'value' directly, unlike SeriesData which has 'data' array
 			const isPointPercentageData =
 				data &&

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

@@ -1318,11 +1318,11 @@ describe( 'ChartContext', () => {
 			expect( styles ).toHaveProperty( 'glyph' );
 			expect( styles ).toHaveProperty( 'shapeStyles' );
 
-			// Verify types
+			// A series without an `options` key is still a series, so theme styles apply.
 			expect( typeof styles.color ).toBe( 'string' );
-			expect( typeof styles.lineStyles ).toBe( 'object' );
-			expect( typeof styles.glyph ).toBe( 'function' );
-			expect( typeof styles.shapeStyles ).toBe( 'object' );
+			expect( styles.lineStyles ).toEqual( { strokeWidth: 2 } );
+			expect( styles.glyph ).toBe( mockGlyph );
+			expect( styles.shapeStyles ).toEqual( { fill: '#SHAPE1' } );
 		} );
 
 		it( 'returns complete ElementStyles object for DataPointPercentage', () => {

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

@@ -61,6 +61,7 @@ const defaultTheme: CompleteChartTheme = {
 	heatmapChart: {
 		compactCellGap: 2,
 		compactCellSize: 11,
+		groupGap: 24,
 	},
 };
 

package/src/styles/test/chart-scope.test.ts

@@ -101,7 +101,7 @@ function parseTokensDoc(): Map< string, Entry > {
 		const token = /(--wp[\w-]+)/.exec( mapping );
 
 		entries.set( role, {
-			reads: unmapped ? null : derives?.[ 1 ] ?? token?.[ 1 ] ?? null,
+			reads: unmapped ? null : ( derives?.[ 1 ] ?? token?.[ 1 ] ?? null ),
 			fallback: fallback === '—' ? null : normalize( fallback ),
 		} );
 	}

package/src/types.ts

@@ -53,12 +53,7 @@ export type LegendShape< Data, Output > =
 	| ComponentClass< LegendShapeRenderProps< Data, Output > >;
 
 export type GoogleDataTableColumnType =
-	| 'string'
-	| 'number'
-	| 'boolean'
-	| 'date'
-	| 'datetime'
-	| 'timeofday';
+	'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'timeofday';
 
 export enum GoogleDataTableColumnRoleType {
 	annotation = 'annotation',
@@ -98,13 +93,7 @@ export type GoogleDataTableCell =
 export type GoogleDataTableRow = GoogleDataTableCell[];
 
 export type ChartType =
-	| 'area'
-	| 'bar'
-	| 'conversion-funnel'
-	| 'leaderboard'
-	| 'line'
-	| 'pie'
-	| 'pie-semi-circle';
+	'area' | 'bar' | 'conversion-funnel' | 'leaderboard' | 'line' | 'pie' | 'pie-semi-circle';
 
 export type OrientationType = ValueOf< typeof Orientation >;
 
@@ -145,6 +134,8 @@ export type ThemeAnnotationStyles = {
 export type DataPoint = {
 	label: string;
 	value: number;
+	/** Per-point fill override for BarChart; other built-in charts ignore it. */
+	color?: string;
 };
 
 /**
@@ -196,6 +187,8 @@ export type DataPointDate = {
 	dateString?: string;
 	value: number | null;
 	label?: string;
+	/** Per-point fill override for BarChart; other built-in charts ignore it. */
+	color?: string;
 };
 
 export type LeaderboardEntry = {
@@ -424,6 +417,8 @@ export type ChartTheme = {
 		compactCellGap?: number;
 		/** Fixed square cell size in px for compact mode */
 		compactCellSize?: number;
+		/** Gap in px between adjacent column groups; in compact mode the minimum, as the gaps share leftover width */
+		groupGap?: number;
 	};
 };
 
@@ -657,6 +652,12 @@ export type SeriesChartLegendConfig = ChartLegendConfig< SeriesData[] > & {
 	 * uncollapsed one toggles only its own.
 	 */
 	collapseGroups?: boolean;
+	/**
+	 * Append a static, non-interactive item explaining the comparison overlay whenever a series
+	 * has `options.type === 'comparison'`. Skipped when that series already has its own item.
+	 * Pass a string to replace the default label.
+	 */
+	comparisonItem?: boolean | string;
 };
 
 /**

package/src/utils/format-metric-value.ts

@@ -47,13 +47,13 @@ export const formatMetricValue = (
 							maximumFractionDigits: decimals ?? 2,
 							signDisplay,
 						},
-				  } )
+					} )
 				: formatNumber( numericValue, {
 						decimals: decimals ?? 2,
 						numberFormatOptions: {
 							signDisplay,
 						},
-				  } );
+					} );
 			return `$${ formatted }`;
 		}
 
@@ -80,13 +80,13 @@ export const formatMetricValue = (
 							maximumFractionDigits: decimals ?? 0,
 							signDisplay,
 						},
-				  } )
+					} )
 				: formatNumber( numericValue, {
 						decimals: decimals ?? 0,
 						numberFormatOptions: {
 							signDisplay,
 						},
-				  } );
+					} );
 		}
 	}
 };

package/src/utils/get-edge-tick-widths.ts

@@ -24,7 +24,7 @@ export const getEdgeTickWidths = < T extends AnyD3Scale >(
 
 	const lastIndex = ticks.length - 1;
 	const label = ( tick: ScaleInput< T >, index: number ) =>
-		String( formatTick ? formatTick( tick, index, [] ) ?? '' : tick );
+		String( formatTick ? ( formatTick( tick, index, [] ) ?? '' ) : tick );
 
 	return {
 		first: getStringWidth( label( ticks[ 0 ], 0 ), labelStyle ) ?? 0,

package/src/utils/get-styles.ts

@@ -103,7 +103,7 @@ export function getItemShapeStyles(
 	const hasExplicitStyles = Object.values( explicitStyles ).some(
 		value => value !== undefined && value !== null && value !== ''
 	);
-	const baseShapeStyles = hasExplicitStyles ? explicitStyles : themeShapeStyles ?? {};
+	const baseShapeStyles = hasExplicitStyles ? explicitStyles : ( themeShapeStyles ?? {} );
 
 	// Layer the comparison bar opacity on top so the swatch matches the translucent bar
 	// without discarding the base (custom or theme) shape styles.

package/src/visx/types.ts

@@ -12,15 +12,10 @@ export interface RenderTooltipGlyphProps< Datum extends object > extends GlyphPr
 	isNearestDatum: boolean;
 }
 
-export type TooltipPlacement = 'auto' | 'below-axis';
+export type TooltipPlacement = 'auto' | 'below-axis' | 'beside';
 
 type CrosshairPaintProperty =
-	| 'stroke'
-	| 'strokeWidth'
-	| 'strokeOpacity'
-	| 'strokeDasharray'
-	| 'strokeLinecap'
-	| 'opacity';
+	'stroke' | 'strokeWidth' | 'strokeOpacity' | 'strokeDasharray' | 'strokeLinecap' | 'opacity';
 
 export type CrosshairStyle = Pick< SVGProps< SVGLineElement >, CrosshairPaintProperty > & {
 	className?: string;
@@ -31,11 +26,13 @@ export type XyChartTooltipProps< Datum extends object > = {
 	renderTooltip: ( params: RenderTooltipParams< Datum > ) => ReactNode;
 	renderGlyph?: ( params: RenderTooltipGlyphProps< Datum > ) => ReactNode;
 	/**
-	 * Keep the panel below the x-axis label band, centered at the datum x and horizontally clamped.
-	 * Vertical bounds do not move this placement; clipping ancestors can still cut it off.
+	 * Use below-axis placement for centered axis anchoring, or beside placement to avoid vertical flipping.
+	 * Below-axis ignores vertical bounds; beside placement clamps to them.
 	 * @default 'auto'
 	 */
 	tooltipPlacement?: TooltipPlacement;
+	/** Override the tooltip top anchor in SVG coordinates, including negative offsets. */
+	tooltipAnchorTop?: number;
 	/** Merge overrides with the default box styles; use `unstyled` to strip the box styling. */
 	style?: VisxTooltipProps[ 'style' ];
 	snapTooltipToDatumX?: boolean;
@@ -52,7 +49,7 @@ export type XyChartTooltipProps< Datum extends object > = {
 	 * that clips its overflow, or the viewport when there is none. The box may
 	 * leave the chart wrapper. (It used to keep a body-level portal inside the
 	 * viewport.)
-	 * Ignored by `below-axis`.
+	 * Non-auto placements always apply their own bounds handling.
 	 * @default true
 	 */
 	detectBounds?: boolean;

package/src/components/legend/utils/label-transform-factory.ts

@@ -1,24 +0,0 @@
-import type { ItemTransformer, LabelFormatter } from '@visx/legend';
-import type { AnyD3Scale, ScaleInput } from '@visx/scale';
-
-/**
- * Returns a function which takes a Datum and index as input, and returns a formatted label object.
- * @param {object}                            root0             - The object to return the value of.
- * @param {AnyD3Scale}                        root0.scale       - The scale to use.
- * @param {LabelFormatter<ScaleInput<Scale>>} root0.labelFormat - The label format to use.
- * @return {ItemTransformer<ScaleInput<Scale>, ReturnType<Scale>>} The label transform factory.
- */
-export function labelTransformFactory< Scale extends AnyD3Scale >( {
-	scale,
-	labelFormat,
-}: {
-	scale: Scale;
-	labelFormat: LabelFormatter< ScaleInput< Scale > >;
-} ): ItemTransformer< ScaleInput< Scale >, ReturnType< Scale > > {
-	return ( d, i ) => ( {
-		datum: d,
-		index: i,
-		text: `${ labelFormat( d, i ) }`,
-		value: scale( d ),
-	} );
-}