@automattic/charts 0.16.2 → 0.18.0

package/src/components/leaderboard-chart/leaderboard-chart.tsx

@@ -0,0 +1,214 @@
+import { ProgressBar } from '@wordpress/components';
+import clsx from 'clsx';
+import { type FC } from 'react';
+import { formatMetricValue } from '../shared/format-metric-value';
+import styles from './leaderboard-chart.module.scss';
+export interface LeaderboardEntry {
+	/**
+	 * Unique internal key (e.g., 'key-direct')
+	 */
+	id: string;
+
+	/**
+	 * Human-readable name (e.g., 'Direct')
+	 */
+	label: string;
+
+	/**
+	 * Value of the entry
+	 */
+	currentValue: number;
+
+	/**
+	 * Value of the entry in the previous period
+	 */
+	previousValue: number;
+
+	/**
+	 * Width of current bar, as % of the current value
+	 */
+	currentShare: number;
+
+	/**
+	 * Width of previous bar, as % of the current value
+	 */
+	previousShare: number;
+
+	/**
+	 * Delta of the entry
+	 */
+	delta: number;
+}
+
+export interface LeaderboardChartProps {
+	/**
+	 * Array of leaderboard entries to display
+	 */
+	data: LeaderboardEntry[];
+
+	/**
+	 * Whether to show comparison data
+	 */
+	withComparison?: boolean;
+
+	/**
+	 * Primary color for current period bars
+	 */
+	primaryColor?: string;
+
+	/**
+	 * Secondary color for comparison period bars
+	 */
+	secondaryColor?: string;
+
+	/**
+	 * Formatter for values
+	 */
+	valueFormatter?: ( value: number ) => string;
+
+	/**
+	 * Formatter for delta values
+	 */
+	deltaFormatter?: ( value: number ) => string;
+
+	/**
+	 * Whether the chart is in loading state
+	 */
+	loading?: boolean;
+
+	/**
+	 * Additional CSS class name for the chart container
+	 */
+	className?: string;
+
+	/**
+	 * Custom styling for the chart container
+	 */
+	style?: React.CSSProperties;
+}
+
+/**
+ * Default value formatter using formatMetricValue
+ *
+ * @param value - The numeric value to format
+ * @return Formatted string representation of the value
+ */
+const defaultValueFormatter = ( value: number ): string => {
+	return formatMetricValue( value, 'number', {
+		useMultipliers: true,
+		decimals: 1,
+	} );
+};
+
+/**
+ * Default delta formatter using formatMetricValue
+ *
+ * @param value - The delta value to format
+ * @return Formatted percentage string
+ */
+const defaultDeltaFormatter = ( value: number ): string => {
+	return formatMetricValue( value / 100, 'average', {
+		decimals: 0,
+		signDisplay: 'exceptZero',
+	} );
+};
+
+/**
+ * LeaderboardChart component displays a ranked list of data with progress bars
+ * and optional comparison values.
+ *
+ * @param props                - Component props
+ * @param props.data           - Array of leaderboard entries to display
+ * @param props.withComparison - Whether to show comparison data
+ * @param props.primaryColor   - Primary color for current period bars
+ * @param props.secondaryColor - Secondary color for comparison period bars
+ * @param props.valueFormatter - Custom formatter for values
+ * @param props.deltaFormatter - Custom formatter for delta values
+ * @param props.loading        - Whether the chart is in loading state
+ * @param props.className      - Additional CSS class name
+ * @param props.style          - Custom styling for the chart container
+ * @return JSX element representing the leaderboard chart
+ */
+export const LeaderboardChart: FC< LeaderboardChartProps > = ( {
+	data,
+	withComparison = false,
+	primaryColor = '#3858E9',
+	secondaryColor = '#66BDFF',
+	valueFormatter = defaultValueFormatter,
+	deltaFormatter = defaultDeltaFormatter,
+	loading = false,
+	className,
+	style,
+} ) => {
+	// TODO: Integrate with ThemeProvider:
+	// 1. Use theme.colors for primaryColor/secondaryColor defaults
+	// 2. Get delta sign colors from theme instead of hardcoding
+	// 3. Add useChartTheme() hook like other chart components
+	const signColors = [ '#D63638', '#757575', '#008A20' ];
+
+	const chartStyle = {
+		'--primary-color': primaryColor,
+		'--secondary-color': secondaryColor,
+		...style,
+	} as React.CSSProperties;
+
+	// Handle empty or undefined data
+	if ( ! data || data.length === 0 ) {
+		return (
+			<div
+				className={ clsx( styles.leaderboardChart, loading && styles.loading, className ) }
+				style={ chartStyle }
+			>
+				<div className={ styles.emptyState }>{ loading ? 'Loading...' : 'No data available' }</div>
+			</div>
+		);
+	}
+
+	return (
+		<div
+			className={ clsx( styles.leaderboardChart, loading && styles.loading, className ) }
+			style={ chartStyle }
+		>
+			{ data.map( entry => {
+				const colorIndex = Math.sign( entry.delta ) + 1;
+				const deltaColor = signColors[ colorIndex ];
+
+				return (
+					<div key={ entry.id } className={ styles.entryContainer }>
+						<div className={ styles.labelContainer }>
+							<span className={ styles.entryLabel }>{ entry.label }</span>
+
+							<div className={ styles.progressContainer }>
+								<ProgressBar
+									value={ entry.currentShare }
+									className={ clsx( styles.progressBar, styles.primaryBar ) }
+								/>
+
+								{ withComparison && (
+									<ProgressBar
+										value={ entry.previousShare }
+										className={ clsx( styles.progressBar, styles.secondaryBar ) }
+									/>
+								) }
+							</div>
+						</div>
+
+						<div className={ styles.valueContainer }>
+							<span className={ styles.currentValue }>
+								{ valueFormatter( entry.currentValue ) }
+							</span>
+
+							{ withComparison && (
+								<span className={ styles.deltaValue } style={ { color: deltaColor } }>
+									{ deltaFormatter( entry.delta ) }
+								</span>
+							) }
+						</div>
+					</div>
+				);
+			} ) }
+		</div>
+	);
+};
+
+export default LeaderboardChart;

package/src/components/line-chart/line-chart-annotation-label-popover.tsx

@@ -0,0 +1,110 @@
+import { Gridicon } from '@automattic/jetpack-components';
+import clsx from 'clsx';
+import { useEffect, useId, useRef, useState } from 'react';
+import { isSafari } from '../shared/utils';
+import styles from './line-chart.module.scss';
+import type { ButtonWithPopover, PopoverElement, ToggleEvent } from '../../types';
+import type { FC } from 'react';
+
+export const POPOVER_BUTTON_SIZE = 44;
+
+interface LineChartAnnotationLabelWithPopoverProps {
+	title: string;
+	subtitle?: string;
+	renderLabel: FC< { title: string; subtitle?: string } >;
+	renderLabelPopover: FC< { title: string; subtitle?: string } >;
+}
+
+const LineChartAnnotationLabelWithPopover: FC< LineChartAnnotationLabelWithPopoverProps > = ( {
+	title,
+	subtitle,
+	renderLabel,
+	renderLabelPopover,
+} ) => {
+	const popoverId = useId();
+	const buttonRef = useRef< HTMLButtonElement >( null );
+	const popoverRef = useRef< HTMLDivElement >( null );
+	const [ isPositioned, setIsPositioned ] = useState( false );
+	const isBrowserSafari = isSafari();
+
+	useEffect( () => {
+		const button = buttonRef.current;
+		const popover = popoverRef.current;
+
+		if ( ! button || ! popover ) return;
+
+		const positionPopover = () => {
+			// Popover positioning in Safari is complicated due to issues with SVG foreign objects (https://bugs.webkit.org/show_bug.cgi?id=23113), so let it be positioned in the centre of the viewport.
+			if ( ! isBrowserSafari ) {
+				const buttonRect = button.getBoundingClientRect();
+				popover.style.left = `${ buttonRect.right }px`;
+				popover.style.top = `${ buttonRect.top }px`;
+			}
+
+			setIsPositioned( true );
+		};
+
+		// Position when popover shows
+		popover.addEventListener( 'toggle', ( e: ToggleEvent ) => {
+			if ( e.newState === 'open' ) {
+				positionPopover();
+			}
+		} );
+
+		// Initial positioning if already open
+		try {
+			if ( popover.matches( ':popover-open' ) ) {
+				positionPopover();
+			}
+		} catch {
+			// Ignore errors in test environments (e.g., JSDOM does not support :popover-open)
+		}
+	}, [ isBrowserSafari ] );
+
+	return (
+		<div className={ styles[ 'line-chart__annotation-label' ] }>
+			<button
+				ref={ buttonRef }
+				{ ...( { popovertarget: popoverId } as ButtonWithPopover ) }
+				className={ styles[ 'line-chart__annotation-label-trigger-button' ] }
+				style={ {
+					width: `${ POPOVER_BUTTON_SIZE }px`,
+					height: `${ POPOVER_BUTTON_SIZE }px`,
+					transform: `translate(${ POPOVER_BUTTON_SIZE / 2 }px, 0)`,
+				} }
+				aria-label={ title || 'View details' }
+			>
+				{ renderLabel( { title, subtitle } ) }
+			</button>
+			<div
+				ref={ popoverRef }
+				id={ popoverId }
+				{ ...( { popover: 'auto' } as PopoverElement ) }
+				className={ clsx(
+					styles[ 'line-chart__annotation-label-popover' ],
+					isPositioned && styles[ 'line-chart__annotation-label-popover--visible' ],
+					isBrowserSafari && styles[ 'line-chart__annotation-label-popover--safari' ]
+				) }
+				data-testid="line-chart-annotation-label-popover"
+			>
+				<div className={ styles[ 'line-chart__annotation-label-popover-header' ] }>
+					<div className={ styles[ 'line-chart__annotation-label-popover-content' ] }>
+						{ renderLabelPopover( { title, subtitle } ) }
+					</div>
+					<button
+						{ ...( {
+							popovertarget: popoverId,
+							popovertargetaction: 'hide',
+						} as ButtonWithPopover ) }
+						className={ styles[ 'line-chart__annotation-label-popover-close-button' ] }
+						aria-label="Close"
+					>
+						<Gridicon icon="cross" size={ 16 } />
+					</button>
+				</div>
+			</div>
+		</div>
+	);
+};
+
+export default LineChartAnnotationLabelWithPopover;

package/src/components/line-chart/line-chart-annotation.tsx

@@ -1,8 +1,19 @@
-import { Annotation, CircleSubject, Connector, Label, LineSubject } from '@visx/annotation';
+import {
+	Annotation,
+	CircleSubject,
+	Connector,
+	HtmlLabel,
+	Label,
+	LineSubject,
+} from '@visx/annotation';
 import { DataContext } from '@visx/xychart';
-import { merge } from 'lodash';
+import merge from 'deepmerge';
 import { useContext, useRef, useEffect, useState, useMemo } from 'react';
 import { useChartTheme } from '../../providers/theme/theme-provider';
+import { isSafari } from '../shared/utils';
+import LineChartAnnotationLabelWithPopover, {
+	POPOVER_BUTTON_SIZE,
+} from './line-chart-annotation-label-popover';
 import type { DataPointDate } from '../../types';
 import type { CircleSubjectProps } from '@visx/annotation/lib/components/CircleSubject';
 import type { ConnectorProps } from '@visx/annotation/lib/components/Connector';
@@ -15,7 +26,10 @@ export type AnnotationStyles = {
 	circleSubject?: Omit< CircleSubjectProps, 'x' | 'y' > & { fill?: string };
 	lineSubject?: Omit< LineSubjectProps, 'x' | 'y' >;
 	connector?: Omit< ConnectorProps, 'x' | 'y' | 'dx' | 'dy' >;
-	label?: Omit< LabelProps, 'title' | 'subtitle' >;
+	label?: Omit< LabelProps, 'title' | 'subtitle' | 'x' | 'y' > & {
+		x?: number | 'start' | 'end';
+		y?: number | 'start' | 'end';
+	};
 };
 
 type SubjectType = 'circle' | 'line-vertical' | 'line-horizontal';
@@ -30,6 +44,8 @@ export type LineChartAnnotationProps = {
 	subjectType?: SubjectType;
 	styles?: AnnotationStyles;
 	testId?: string;
+	renderLabel?: FC< { title: string; subtitle?: string } >;
+	renderLabelPopover?: FC< { title: string; subtitle?: string } >;
 };
 
 export const getLabelPosition = ( {
@@ -79,6 +95,7 @@ export const getLabelPosition = ( {
 
 	if ( effectiveX + annotationMaxWidth > xMax ) {
 		isFlippedHorizontally = true;
+
 		if ( subjectType === 'circle' ) {
 			dx = -dx; // Just flip to the left side with same offset
 		} else if ( subjectType === 'line-vertical' ) {
@@ -142,7 +159,7 @@ const getVerticalAnchor = (
 			return y - height < yMax ? 'start' : 'end';
 		}
 
-		return 'middle';
+		return 'start';
 	}
 
 	return undefined;
@@ -155,6 +172,8 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 	subjectType = 'circle',
 	styles: datumStyles,
 	testId,
+	renderLabel,
+	renderLabelPopover,
 } ) => {
 	const providerTheme = useChartTheme();
 	const { xScale, yScale } = useContext( DataContext ) || {};
@@ -162,11 +181,11 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 	const [ height, setHeight ] = useState< number | null >( null );
 
 	// Deep merge styles to preserve nested object properties
-	const styles = merge( {}, providerTheme.annotationStyles, datumStyles );
+	const styles = merge( providerTheme.annotationStyles ?? {}, datumStyles ?? {} );
 
 	// Measure the label height once after initial render
 	useEffect( () => {
-		if ( labelRef.current ) {
+		if ( labelRef.current?.getBBox ) {
 			const bbox = labelRef.current.getBBox();
 			setHeight( bbox.height );
 		}
@@ -183,6 +202,22 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 		const [ yMin, yMax ] = yScale.range().map( Number );
 		const [ xMin, xMax ] = xScale.range().map( Number );
 
+		// If a custom label is provided, use the provided position
+		if ( renderLabel ) {
+			return {
+				x,
+				dx: 0,
+				y,
+				dy: 0,
+				yMin,
+				yMax,
+				xMin,
+				xMax,
+				isFlippedHorizontally: false,
+				isFlippedVertically: false,
+			};
+		}
+
 		const position = getLabelPosition( {
 			subjectType,
 			x,
@@ -195,13 +230,61 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 		} );
 
 		return { x, y, yMin, yMax, xMin, xMax, ...position };
-	}, [ datum, xScale, yScale, subjectType, styles?.label?.maxWidth, height ] );
+	}, [ datum, xScale, yScale, subjectType, styles?.label?.maxWidth, height, renderLabel ] );
 
 	if ( ! positionData ) return null;
 
 	const { x, y, yMin, yMax, xMin, xMax, dx, dy, isFlippedHorizontally, isFlippedVertically } =
 		positionData;
 
+	const getLabelY = () => {
+		const labelY = styles?.label?.y;
+
+		if ( labelY === 'start' ) return yMax;
+		if ( labelY === 'end' ) return yMin;
+
+		return labelY;
+	};
+
+	const getLabelX = () => {
+		const labelX = styles?.label?.x;
+
+		if ( labelX === 'start' ) return xMin;
+		if ( labelX === 'end' ) return xMax;
+
+		return labelX;
+	};
+
+	const labelPosition = {
+		x: getLabelX(),
+		y: getLabelY(),
+	};
+
+	// Safari has a bug where children of an SVG foreignObject are not positioned correctly https://bugs.webkit.org/show_bug.cgi?id=23113
+	// This is a workaround to position the label correctly
+	const getSafariHTMLLabelPosition = () => {
+		const labelWidth = POPOVER_BUTTON_SIZE;
+		const labelHeight = POPOVER_BUTTON_SIZE;
+
+		return isSafari()
+			? {
+					transform: `translate(${
+						x +
+						( dx || 0 ) +
+						( typeof labelPosition.x === 'number' ? labelPosition.x - x : 0 ) -
+						labelWidth
+					}px, ${
+						y +
+						( dy || 0 ) +
+						( typeof labelPosition.y === 'number' ? labelPosition.y - y : 0 ) -
+						labelHeight
+					}px)`,
+					width: labelWidth,
+					height: labelHeight,
+			  }
+			: undefined;
+	};
+
 	return (
 		<g data-testid={ testId }>
 			<Annotation x={ x } y={ y } dx={ dx } dy={ dy }>
@@ -221,21 +304,39 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 						{ ...{ ...styles?.lineSubject, orientation: 'horizontal' } }
 					/>
 				) }
-				<g ref={ labelRef }>
-					<Label
-						title={ title }
-						subtitle={ subtitle }
-						{ ...styles?.label }
-						horizontalAnchor={ getHorizontalAnchor( subjectType, isFlippedHorizontally ) }
-						verticalAnchor={ getVerticalAnchor(
-							subjectType,
-							isFlippedVertically,
-							y,
-							yMax,
-							height ?? ANNOTATION_INIT_HEIGHT
-						) }
-					/>
-				</g>
+				{ renderLabel ? (
+					<HtmlLabel { ...styles?.label } { ...labelPosition }>
+						<div style={ getSafariHTMLLabelPosition() }>
+							{ renderLabelPopover ? (
+								<LineChartAnnotationLabelWithPopover
+									title={ title }
+									subtitle={ subtitle }
+									renderLabel={ renderLabel }
+									renderLabelPopover={ renderLabelPopover }
+								/>
+							) : (
+								renderLabel( { title, subtitle } )
+							) }
+						</div>
+					</HtmlLabel>
+				) : (
+					<g ref={ labelRef }>
+						<Label
+							title={ title }
+							subtitle={ subtitle }
+							{ ...styles?.label }
+							{ ...labelPosition }
+							horizontalAnchor={ getHorizontalAnchor( subjectType, isFlippedHorizontally ) }
+							verticalAnchor={ getVerticalAnchor(
+								subjectType,
+								isFlippedVertically,
+								y,
+								yMax,
+								height ?? ANNOTATION_INIT_HEIGHT
+							) }
+						/>
+					</g>
+				) }
 			</Annotation>
 		</g>
 	);

package/src/components/line-chart/line-chart-annotations-overlay.tsx

@@ -0,0 +1,135 @@
+import { DataContext } from '@visx/xychart';
+import { useEffect, useState, useCallback } from 'react';
+import { useLineChartContext } from './line-chart-context';
+import styles from './line-chart.module.scss';
+import type { AxisScale } from '@visx/axis';
+import type { FC, ReactNode } from 'react';
+
+export interface LineChartAnnotationsProps {
+	children?: ReactNode;
+}
+
+interface ScaleData {
+	xScale: AxisScale< Date >;
+	yScale: AxisScale< number >;
+}
+
+const LineChartAnnotationsOverlay: FC< LineChartAnnotationsProps > = ( { children } ) => {
+	const { chartRef, chartWidth, chartHeight } = useLineChartContext();
+
+	const [ scales, setScales ] = useState< ScaleData | null >( null );
+	const [ scalesStable, setScalesStable ] = useState< boolean >( false );
+
+	// Create a signature for scale data to enable easy comparison
+	const createScaleSignature = useCallback( ( scaleData: ScaleData ) => {
+		const xDomain = scaleData.xScale.domain();
+		const yDomain = scaleData.yScale.domain();
+		const xRange = scaleData.xScale.range();
+		const yRange = scaleData.yScale.range();
+
+		return `${ xDomain.join( ',' ) }-${ yDomain.join( ',' ) }-${ xRange.join(
+			','
+		) }-${ yRange.join( ',' ) }`;
+	}, [] );
+
+	// Get scales from chart ref and return them with signature for comparison
+	const getScalesData = useCallback( () => {
+		if ( chartRef?.current ) {
+			const scaleData = chartRef.current.getScales();
+
+			if ( scaleData ) {
+				const scaleInfo = {
+					xScale: scaleData.xScale as AxisScale< Date >,
+					yScale: scaleData.yScale as AxisScale< number >,
+				};
+
+				return {
+					scales: scaleInfo,
+					signature: createScaleSignature( scaleInfo ),
+				};
+			}
+		}
+
+		return null;
+	}, [ chartRef, createScaleSignature ] );
+
+	// The chart resizes on render so we need to monitor the scales until they stabilize
+	useEffect( () => {
+		let timeoutId: number | null = null;
+		let lastSignature: string | null = null;
+		let retryCount = 0;
+		const maxRetries = 20; // 20 * 50ms = 1 second max
+		const checkInterval = 50; // Check every 50ms
+
+		// Reset stability state when monitoring starts
+		setScalesStable( false );
+
+		const monitorScales = () => {
+			const currentScaleData = getScalesData();
+
+			// If we got scales, compare signatures
+			if ( currentScaleData ) {
+				// Check if scales have settled by comparing signatures
+				const scalesSettled = lastSignature && currentScaleData.signature === lastSignature;
+
+				if ( scalesSettled ) {
+					// Scales have stabilized, mark as stable
+					setScalesStable( true );
+					return;
+				}
+
+				// Update scales and remember signature for next comparison
+				setScales( currentScaleData.scales );
+				lastSignature = currentScaleData.signature;
+			}
+
+			// Continue monitoring if we haven't exceeded max retries
+			if ( retryCount < maxRetries ) {
+				retryCount++;
+				timeoutId = setTimeout( monitorScales, checkInterval ) as unknown as number;
+			}
+		};
+
+		monitorScales();
+
+		return () => {
+			if ( timeoutId ) {
+				clearTimeout( timeoutId );
+			}
+		};
+	}, [ getScalesData, chartWidth, chartHeight ] );
+
+	// Early return if no chart data available
+	if ( ! chartRef || ! children ) {
+		return null;
+	}
+
+	if ( ! scales || ! scalesStable ) {
+		return null;
+	}
+
+	// Create a DataContext value that mimics what visx provides
+	// We're intentionally providing minimal context for annotations to work
+	const dataContextValue = {
+		xScale: scales.xScale,
+		yScale: scales.yScale,
+		margin: { top: 0, right: 0, bottom: 0, left: 0 },
+		width: chartWidth,
+		height: chartHeight,
+	} as unknown as Parameters< typeof DataContext.Provider >[ 0 ][ 'value' ];
+
+	return (
+		<DataContext.Provider value={ dataContextValue }>
+			<svg
+				width={ chartWidth }
+				height={ chartHeight }
+				className={ styles[ 'line-chart__annotations-overlay' ] }
+				data-testid="line-chart-annotations-overlay"
+			>
+				{ children }
+			</svg>
+		</DataContext.Provider>
+	);
+};
+
+export default LineChartAnnotationsOverlay;

package/src/components/line-chart/line-chart-context.tsx

@@ -0,0 +1,28 @@
+import { createContext, useContext } from 'react';
+
+export interface LineChartRef {
+	getScales: () => { xScale: unknown; yScale: unknown } | null;
+	getChartDimensions: () => {
+		width: number;
+		height: number;
+		margin: { top?: number; right?: number; bottom?: number; left?: number };
+	};
+}
+
+// Local context for LineChart implicit state sharing
+export interface LineChartContextValue {
+	chartId: string;
+	chartRef: React.RefObject< LineChartRef >;
+	chartWidth: number;
+	chartHeight: number;
+}
+
+export const LineChartContext = createContext< LineChartContextValue | null >( null );
+
+export const useLineChartContext = (): LineChartContextValue => {
+	const context = useContext( LineChartContext );
+	if ( ! context ) {
+		throw new Error( 'useLineChartContext must be used within a LineChart component' );
+	}
+	return context;
+};