@automattic/charts 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -63,7 +63,7 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.1.6",
+		"@automattic/number-formatters": "^1.1.7",
 		"@babel/runtime": "7.29.2",
 		"@react-spring/web": "9.7.5",
 		"@visx/annotation": "^3.12.0",
@@ -121,7 +121,7 @@
 		"identity-obj-proxy": "^3.0.0",
 		"jest": "30.3.0",
 		"jest-extended": "7.0.0",
-		"postcss": "8.5.6",
+		"postcss": "8.5.10",
 		"postcss-modules": "6.0.1",
 		"react": "18.3.1",
 		"react-dom": "18.3.1",

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

@@ -0,0 +1,23 @@
+.area-chart {
+	position: relative;
+
+	&--animated {
+
+		path {
+			transform-origin: 0 95%;
+			transform: scaleY(0);
+			animation: rise 1s ease-out forwards;
+		}
+	}
+
+	svg {
+		overflow: visible;
+	}
+}
+
+@keyframes rise {
+
+	to {
+		transform: scaleY(1);
+	}
+}

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

@@ -0,0 +1,444 @@
+import { formatNumberCompact } from '@automattic/number-formatters';
+import { XYChart, AreaSeries, AreaStack, Grid, Axis } from '@visx/xychart';
+import { __ } from '@wordpress/i18n';
+import clsx from 'clsx';
+import {
+	useMemo,
+	useContext,
+	forwardRef,
+	useImperativeHandle,
+	useState,
+	useRef,
+	useCallback,
+} from 'react';
+import { Legend, useChartLegendItems } from '../../components/legend';
+import { AccessibleTooltip, useKeyboardNavigation } from '../../components/tooltip';
+import {
+	useXYChartTheme,
+	useChartDataTransform,
+	useChartMargin,
+	usePrefersReducedMotion,
+} from '../../hooks';
+import {
+	GlobalChartsProvider,
+	GlobalChartsContext,
+	useChartId,
+	useChartRegistration,
+	useGlobalChartsContext,
+	useGlobalChartsTheme,
+} from '../../providers';
+import { attachSubComponents } from '../../utils';
+import { renderDefaultTooltip } from '../line-chart';
+import { useChartChildren } from '../private/chart-composition';
+import { ChartLayout } from '../private/chart-layout';
+import { SingleChartContext, type SingleChartRef } from '../private/single-chart-context';
+import { SvgEmptyState } from '../private/svg-empty-state';
+import { getCurveType, getFormatter, guessOptimalNumTicks } from '../private/time-axis';
+import { withResponsive } from '../private/with-responsive';
+import styles from './area-chart.module.scss';
+import { AreaChartScalesRef, HoverGlyphs, validateData } from './private';
+import type { AreaChartProps } from './types';
+import type { DataPointDate, Optional } from '../../types';
+import type { ResponsiveConfig } from '../private/with-responsive';
+import type { TickFormatter } from '@visx/axis';
+
+const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
+	(
+		{
+			data,
+			chartId: providedChartId,
+			width,
+			height,
+			className,
+			margin,
+			withTooltips = true,
+			withTooltipCrosshairs,
+			showLegend = false,
+			legend = {},
+			stacked = true,
+			stackOffset = 'none',
+			smoothing = true,
+			curveType,
+			fillOpacity,
+			withStroke,
+			renderTooltip = renderDefaultTooltip,
+			animation,
+			options = {},
+			onPointerDown,
+			onPointerUp,
+			onPointerMove,
+			onPointerOut,
+			children,
+			gridVisibility,
+			gap = 'md',
+		},
+		ref
+	) => {
+		const legendInteractive = legend.interactive ?? false;
+		const legendShape = legend.shape ?? 'rect';
+		const legendPosition = legend.position ?? 'bottom';
+
+		const providerTheme = useGlobalChartsTheme();
+		const theme = useXYChartTheme( data );
+		const chartId = useChartId( providedChartId );
+		const chartRef = useRef< HTMLDivElement >( null );
+		const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >( undefined );
+		const [ isNavigating, setIsNavigating ] = useState( false );
+		const internalChartRef = useRef< SingleChartRef >( null );
+
+		const { legendChildren, nonLegendChildren } = useChartChildren( children, 'AreaChart' );
+		const [ measuredChartHeight, setMeasuredChartHeight ] = useState< number | undefined >();
+
+		const handleContentHeightChange = useCallback(
+			( contentHeight: number ) => {
+				const chartHeight = contentHeight > 0 ? contentHeight : height;
+				setMeasuredChartHeight( chartHeight );
+			},
+			[ height ]
+		);
+
+		useImperativeHandle(
+			ref,
+			() => ( {
+				getScales: () => internalChartRef.current?.getScales() || null,
+				getChartDimensions: () =>
+					internalChartRef.current?.getChartDimensions() || { width: 0, height: 0, margin: {} },
+			} ),
+			[ internalChartRef ]
+		);
+
+		const dataSorted = useChartDataTransform( data );
+		const { getElementStyles, isSeriesVisible } = useGlobalChartsContext();
+
+		const seriesWithVisibility = useMemo( () => {
+			if ( ! chartId || ! legendInteractive ) {
+				return dataSorted.map( ( series, index ) => ( { series, index, isVisible: true } ) );
+			}
+			return dataSorted.map( ( series, index ) => ( {
+				series,
+				index,
+				isVisible: isSeriesVisible( chartId, series.label ),
+			} ) );
+		}, [ dataSorted, chartId, isSeriesVisible, legendInteractive ] );
+
+		const allSeriesHidden = useMemo(
+			() => seriesWithVisibility.every( ( { isVisible } ) => ! isVisible ),
+			[ seriesWithVisibility ]
+		);
+
+		const { tooltipRef, onChartFocus, onChartBlur, onChartKeyDown } = useKeyboardNavigation( {
+			selectedIndex,
+			setSelectedIndex,
+			isNavigating,
+			setIsNavigating,
+			chartRef,
+			totalPoints: dataSorted[ 0 ]?.data.length || 0,
+		} );
+
+		const chartOptions = useMemo( () => {
+			const formatter = options?.axis?.x?.tickFormat || getFormatter( dataSorted );
+
+			return {
+				axis: {
+					x: {
+						orientation: 'bottom' as const,
+						numTicks: guessOptimalNumTicks( dataSorted, width, formatter ),
+						tickFormat: formatter,
+						display: true,
+						...options?.axis?.x,
+					},
+					y: {
+						orientation: 'left' as const,
+						numTicks: 4,
+						tickFormat: formatNumberCompact as TickFormatter< number >,
+						display: true,
+						...options?.axis?.y,
+					},
+				},
+				xScale: {
+					type: 'time' as const,
+					...options?.xScale,
+				},
+				yScale: {
+					type: 'linear' as const,
+					nice: true,
+					// Stacked areas should always include zero so the baseline is meaningful.
+					zero: stacked,
+					...options?.yScale,
+				},
+			};
+		}, [ options, dataSorted, width, stacked ] );
+
+		const defaultMargin = useChartMargin( height, chartOptions, dataSorted, theme );
+
+		const error = validateData( dataSorted );
+		const isDataValid = ! error;
+
+		const legendOptions = useMemo( () => ( { withGlyph: false, glyphSize: 0 } ), [] );
+		const legendItems = useChartLegendItems( dataSorted, legendOptions, legendShape );
+
+		const chartMetadata = useMemo(
+			() => ( { stacked, stackOffset, smoothing, curveType } ),
+			[ stacked, stackOffset, smoothing, curveType ]
+		);
+
+		useChartRegistration( {
+			chartId,
+			legendItems,
+			chartType: 'area',
+			isDataValid,
+			metadata: chartMetadata,
+		} );
+
+		const prefersReducedMotion = usePrefersReducedMotion();
+
+		const accessors = {
+			xAccessor: ( d: DataPointDate ) => d?.date,
+			yAccessor: ( d: DataPointDate ) => d?.value,
+		};
+
+		// Defaults that depend on stacked vs overlapping mode.
+		const resolvedFillOpacity = fillOpacity ?? ( stacked ? 0.85 : 0.4 );
+		const resolvedWithStroke = withStroke ?? ! stacked;
+
+		if ( error ) {
+			return <div className={ clsx( 'area-chart', styles[ 'area-chart' ] ) }>{ error }</div>;
+		}
+
+		const legendElement = showLegend && (
+			<Legend
+				orientation={ legend.orientation ?? 'horizontal' }
+				alignment={ legend.alignment ?? 'center' }
+				position={ legendPosition }
+				labelStyles={ legend.labelStyles }
+				itemClassName={ legend.itemClassName }
+				itemStyles={ legend.itemStyles }
+				shapeStyles={ legend.shapeStyles }
+				className={ styles[ 'area-chart__legend' ] }
+				shape={ legendShape }
+				chartId={ chartId }
+				interactive={ legendInteractive }
+			/>
+		);
+
+		const visibleSeries = seriesWithVisibility.filter( ( { isVisible } ) => isVisible );
+		const curve = getCurveType( curveType, smoothing );
+
+		return (
+			<SingleChartContext.Provider
+				value={ {
+					chartId,
+					chartRef: internalChartRef,
+					chartWidth: width,
+					chartHeight: measuredChartHeight || 0,
+				} }
+			>
+				<ChartLayout
+					legendPosition={ legendPosition }
+					legendElement={ legendElement }
+					legendChildren={ legendChildren }
+					gap={ gap }
+					className={ clsx(
+						'area-chart',
+						styles[ 'area-chart' ],
+						{ [ styles[ 'area-chart--animated' ] ]: animation && ! prefersReducedMotion },
+						className
+					) }
+					style={ { width, height } }
+					data-testid="area-chart"
+					trailingContent={ nonLegendChildren }
+					onContentHeightChange={ handleContentHeightChange }
+				>
+					{ ( { contentHeight } ) => {
+						const chartHeight = contentHeight > 0 ? contentHeight : height;
+
+						return (
+							<div
+								role="grid"
+								aria-label={ __( 'Area chart', 'jetpack-charts' ) }
+								tabIndex={ 0 }
+								onKeyDown={ onChartKeyDown }
+								onFocus={ onChartFocus }
+								onBlur={ onChartBlur }
+							>
+								{ chartHeight > 0 && (
+									<div ref={ chartRef }>
+										<XYChart
+											theme={ theme }
+											width={ width }
+											height={ chartHeight }
+											margin={ { ...defaultMargin, ...margin } }
+											xScale={ chartOptions.xScale }
+											yScale={ chartOptions.yScale }
+											onPointerDown={ onPointerDown }
+											onPointerUp={ onPointerUp }
+											onPointerMove={ onPointerMove }
+											onPointerOut={ onPointerOut }
+											pointerEventsDataKey="nearest"
+										>
+											{ gridVisibility !== 'none' && <Grid columns={ false } numTicks={ 4 } /> }
+											{ chartOptions.axis.x.display && <Axis { ...chartOptions.axis.x } /> }
+											{ chartOptions.axis.y.display && <Axis { ...chartOptions.axis.y } /> }
+
+											{ allSeriesHidden ? (
+												<SvgEmptyState
+													x={ width / 2 }
+													y={ chartHeight / 2 }
+													width={ width }
+													height={ chartHeight }
+												>
+													{ __(
+														'All series are hidden. Click legend items to show data.',
+														'jetpack-charts'
+													) }
+												</SvgEmptyState>
+											) : null }
+
+											{ ! allSeriesHidden && stacked && (
+												<AreaStack
+													curve={ curve }
+													offset={ stackOffset }
+													renderLine={ resolvedWithStroke }
+												>
+													{ visibleSeries.map( ( { series: seriesData, index } ) => {
+														const { color, lineStyles } = getElementStyles( {
+															data: seriesData,
+															index,
+														} );
+
+														return (
+															<AreaSeries
+																key={ seriesData?.label || index }
+																dataKey={ seriesData?.label }
+																data={ seriesData.data as DataPointDate[] }
+																{ ...accessors }
+																fill={ color }
+																fillOpacity={ resolvedFillOpacity }
+																lineProps={ {
+																	stroke: color,
+																	...lineStyles,
+																} }
+																data-testid={ `area-chart-series-${ index }` }
+															/>
+														);
+													} ) }
+												</AreaStack>
+											) }
+
+											{ ! allSeriesHidden &&
+												! stacked &&
+												visibleSeries.map( ( { series: seriesData, index } ) => {
+													const { color, lineStyles } = getElementStyles( {
+														data: seriesData,
+														index,
+													} );
+
+													return (
+														<AreaSeries
+															key={ seriesData?.label || index }
+															dataKey={ seriesData?.label }
+															data={ seriesData.data as DataPointDate[] }
+															{ ...accessors }
+															fill={ color }
+															fillOpacity={ resolvedFillOpacity }
+															renderLine={ resolvedWithStroke }
+															curve={ curve }
+															lineProps={ {
+																stroke: color,
+																...lineStyles,
+															} }
+															data-testid={ `area-chart-series-${ index }` }
+														/>
+													);
+												} ) }
+
+											{ withTooltips && (
+												<>
+													<AccessibleTooltip
+														detectBounds
+														snapTooltipToDatumX
+														// Stacked mode: yAccessor returns raw value, not stacked y — snapping mispositions.
+														snapTooltipToDatumY={ ! stacked }
+														renderTooltip={ renderTooltip }
+														showVerticalCrosshair={ withTooltipCrosshairs?.showVertical }
+														showHorizontalCrosshair={ withTooltipCrosshairs?.showHorizontal }
+														selectedIndex={ selectedIndex }
+														tooltipRef={ tooltipRef }
+														keyboardFocusedClassName={
+															styles[ 'area-chart__tooltip--keyboard-focused' ]
+														}
+														series={ dataSorted }
+													/>
+													<HoverGlyphs
+														visibleSeries={ visibleSeries }
+														stacked={ stacked }
+														stackOffset={ stackOffset }
+														getElementStyles={ getElementStyles }
+														strokeColor={ providerTheme.backgroundColor }
+													/>
+												</>
+											) }
+
+											<AreaChartScalesRef
+												chartRef={ internalChartRef }
+												width={ width }
+												// `||` — responsive HOC may pass `height = 0` before measurement.
+												height={ height || chartHeight }
+												margin={ margin }
+											/>
+										</XYChart>
+									</div>
+								) }
+							</div>
+						);
+					} }
+				</ChartLayout>
+			</SingleChartContext.Provider>
+		);
+	}
+);
+
+type AreaChartSubComponents = {
+	Legend: typeof Legend;
+};
+
+type AreaChartBaseProps = Optional< AreaChartProps, 'width' | 'height' | 'size' >;
+
+type AreaChartComponent = React.ForwardRefExoticComponent<
+	AreaChartBaseProps & React.RefAttributes< SingleChartRef >
+> &
+	AreaChartSubComponents;
+
+type AreaChartResponsiveComponent = React.ForwardRefExoticComponent<
+	AreaChartBaseProps & ResponsiveConfig & React.RefAttributes< SingleChartRef >
+> &
+	AreaChartSubComponents;
+
+const AreaChartWithProvider = forwardRef< SingleChartRef, AreaChartProps >( ( props, ref ) => {
+	const existingContext = useContext( GlobalChartsContext );
+
+	if ( existingContext ) {
+		return <AreaChartInternal { ...props } ref={ ref } />;
+	}
+
+	return (
+		<GlobalChartsProvider>
+			<AreaChartInternal { ...props } ref={ ref } />
+		</GlobalChartsProvider>
+	);
+} );
+
+AreaChartWithProvider.displayName = 'AreaChart';
+
+const AreaChart = attachSubComponents( AreaChartWithProvider, {
+	Legend: Legend,
+} ) as AreaChartComponent;
+
+const AreaChartResponsive = attachSubComponents(
+	withResponsive< AreaChartProps >( AreaChartWithProvider ),
+	{
+		Legend: Legend,
+	}
+) as AreaChartResponsiveComponent;
+
+export { AreaChartResponsive as default, AreaChart as AreaChartUnresponsive };

package/src/charts/area-chart/index.ts

@@ -0,0 +1,2 @@
+export { default as AreaChart, AreaChartUnresponsive } from './area-chart';
+export type { AreaChartProps } from './types';

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

@@ -0,0 +1,2 @@
+export { validateData } from './validate-data';
+export { AreaChartScalesRef, HoverGlyphs, type VisibleSeriesEntry } from './overlays';

package/src/charts/area-chart/private/overlays.tsx

@@ -0,0 +1,123 @@
+import { DataContext, TooltipContext } from '@visx/xychart';
+import { useContext, useImperativeHandle } from 'react';
+import type { ElementStyles, GetElementStylesParams } from '../../../providers';
+import type { DataPointDate, SeriesData } from '../../../types';
+import type { SingleChartRef } from '../../private/single-chart-context';
+import type { FC, ReactNode, Ref } from 'react';
+
+export type VisibleSeriesEntry = { series: SeriesData; index: number; isVisible: boolean };
+
+// AreaChart only configures time + linear scales; cast to a callable shape
+// instead of spreading `any`. `Number(...)` + `isFinite` guards every call.
+type ScaleFn = ( input: Date | number ) => number;
+
+// Bridges visx's `DataContext` to the chart's `SingleChartRef` so consumers
+// can read scales and dimensions imperatively. Must be inside `<XYChart>`.
+export const AreaChartScalesRef: FC< {
+	chartRef?: Ref< SingleChartRef >;
+	width: number;
+	height: number;
+	margin?: { top?: number; right?: number; bottom?: number; left?: number };
+} > = ( { chartRef, width, height, margin } ) => {
+	const context = useContext( DataContext );
+
+	useImperativeHandle(
+		chartRef,
+		() => ( {
+			getScales: () => {
+				if ( ! context?.xScale || ! context?.yScale ) return null;
+				return { xScale: context.xScale, yScale: context.yScale };
+			},
+			getChartDimensions: () => ( { width, height, margin: margin || {} } ),
+		} ),
+		[ context, width, height, margin ]
+	);
+
+	return null;
+};
+
+// Hover indicators for each visible series. visx's `showSeriesGlyphs`
+// mispositions on AreaStack (its registered yAccessor expects a stack-bar
+// but receives the unwrapped datum, yielding NaN), so we compute positions
+// from the chart's scales: cumulative top edge for stacked + offset='none'
+// (matches d3-stack — missing values count as 0); raw y for unstacked.
+// Skipped for `expand`/`wiggle`/`silhouette` — exact positions there would
+// need re-running the d3-stack layout.
+export const HoverGlyphs: FC< {
+	visibleSeries: VisibleSeriesEntry[];
+	stacked: boolean;
+	stackOffset: 'none' | 'expand' | 'wiggle' | 'silhouette';
+	getElementStyles: ( params: GetElementStylesParams ) => ElementStyles;
+	strokeColor: string;
+} > = ( { visibleSeries, stacked, stackOffset, getElementStyles, strokeColor } ) => {
+	const dataContext = useContext( DataContext );
+	const tooltipContext = useContext( TooltipContext );
+
+	const xScale = dataContext?.xScale as ScaleFn | undefined;
+	const yScale = dataContext?.yScale as ScaleFn | undefined;
+	const tooltipOpen = tooltipContext?.tooltipOpen;
+	const nearestDatum = tooltipContext?.tooltipData?.nearestDatum?.datum as
+		| DataPointDate
+		| undefined;
+
+	if (
+		! tooltipOpen ||
+		! xScale ||
+		! yScale ||
+		! nearestDatum ||
+		! nearestDatum.date ||
+		( stacked && stackOffset !== 'none' )
+	) {
+		return null;
+	}
+
+	const xPx = Number( xScale( nearestDatum.date ) );
+	if ( ! Number.isFinite( xPx ) ) return null;
+
+	const hoveredTime = nearestDatum.date.getTime();
+	let cumulative = 0;
+	const circles: ReactNode[] = [];
+
+	// Always advance `cumulative` (d3-stack treats missing/null as 0), but
+	// only render a glyph when the series has a real value at this x.
+	for ( const { series, index } of visibleSeries ) {
+		const datum = series.data.find(
+			d => ( d as DataPointDate ).date?.getTime() === hoveredTime
+		) as DataPointDate | undefined;
+
+		const value = datum?.value ?? 0;
+		if ( stacked ) {
+			cumulative += value;
+		}
+
+		if ( ! datum || datum.value == null ) {
+			continue;
+		}
+
+		const yPx = Number( yScale( stacked ? cumulative : value ) );
+		if ( ! Number.isFinite( yPx ) ) continue;
+
+		const { color } = getElementStyles( { data: series, index } );
+		circles.push(
+			<circle
+				key={ series.label || index }
+				cx={ xPx }
+				cy={ yPx }
+				r={ 4 }
+				fill={ color }
+				stroke={ strokeColor }
+				strokeWidth={ 1.5 }
+				paintOrder="fill"
+				data-testid={ `area-chart-hover-glyph-${ index }` }
+			/>
+		);
+	}
+
+	if ( circles.length === 0 ) return null;
+
+	return (
+		<g pointerEvents="none" className="area-chart__hover-glyphs">
+			{ circles }
+		</g>
+	);
+};

package/src/charts/area-chart/private/validate-data.ts

@@ -0,0 +1,31 @@
+import { __ } from '@wordpress/i18n';
+import type { DataPoint, DataPointDate, SeriesData } from '../../../types';
+
+/**
+ * Up-front data validation. Returns a localised error message when the chart
+ * cannot safely render, otherwise `null`. Catches the cases that would
+ * NaN-cascade through the tick formatter and stack layout: empty top-level
+ * array, empty per-series data, null/NaN values, invalid dates.
+ *
+ * @param data - Series data passed to AreaChart.
+ * @return Error message, or `null` if the data is renderable.
+ */
+export const validateData = ( data: SeriesData[] ) => {
+	if ( ! data?.length ) return __( 'No data available', 'jetpack-charts' );
+
+	const hasEmptySeries = data.some( series => ! series.data?.length );
+	if ( hasEmptySeries ) return __( 'No data available', 'jetpack-charts' );
+
+	const hasInvalidData = data.some( series =>
+		series.data.some(
+			( point: DataPointDate | DataPoint ) =>
+				isNaN( point.value as number ) ||
+				point.value === null ||
+				point.value === undefined ||
+				( 'date' in point && point.date && isNaN( point.date.getTime() ) )
+		)
+	);
+
+	if ( hasInvalidData ) return __( 'Invalid data', 'jetpack-charts' );
+	return null;
+};