Line chart - custom annotations (#44131)

* Enhance LineChartAnnotation component with custom label support and improved label positioning

* Refactor LineChartAnnotation to accept custom label rendering via renderLabel prop.
* Update label positioning logic to accommodate custom dx and dy values.
* Modify annotation props to include additional label positioning options.
* Adjust LineChart component to pass down annotation props more efficiently.
* Add a new story for custom label rendering in annotation stories.

* Add changelog

* Fix regression on default annotation positioning

* Fix react popover attr naming

* Configure bottom custom annotation in story

* Wrap annotations in svg

* Refactor LineChart component to support forwarding refs and expose scale data

* Introduced LineChartRef interface to provide methods for accessing chart scales and dimensions.
* Refactored LineChart to use forwardRef, allowing parent components to interact with the chart's internal state.
* Created LineChartInternal component to manage data context and provide scale data via ref.
* Updated chart rendering logic to maintain existing functionality while enhancing flexibility.

* Use an overlay for positioning annotations above the interaction layer

* Remove debug annotations

* Fix positioning issues

* Refactor LineChartAnnotation and LineChartAnnotations components to remove external positioning logic and utilize DataContext for scale management. Simplified annotation rendering by directly passing props without calculating chart bounds.

* Improve data context types

* Wait for scales to be ready in tests

* Simplify scales ready state

* Fix svg getBBox not being available in jsdom

* Improve syncing of overlay scale

* Remove React from imports

* Fix custom label positoning in Safari

* Add @automattic/jetpack-components as a dependency in charts package

* Add LineChartAnnotationLabelWithPopover component for enhanced label popover functionality in line charts. Update LineChartAnnotation to support popover rendering and simplify annotation prop passing in LineChartAnnotations. Update stories to demonstrate new popover feature.

* Add missing position on line chart wrapper after rebase

* Refactor LineChartAnnotation to utilize POPOVER_BUTTON_SIZE constant for consistent button dimensions and simplify Safari label positioning logic.

* Move popoveer styles to scss

* Minor code cleanup

* Refactor LineChartAnnotation to remove unused dx and dy props, simplifying label positioning logic and improving code clarity.

* Add DeployedIcon and AlertIcon components for improved annotation rendering in LineChart. Update renderLabel methods to utilize these new components, enhancing code clarity and maintainability.

* Unify tooltip and popover styles

* Add tests

* Introduce scalesStable state to track when scales have settled, ensuring proper rendering only when scales are stable.

* Improve popover positioining

- fallback to centered position for Safari due to foreign object issues
- add space around popover to allow for hitting viewport boundaries

* Add popover api types

* Add popover tests

* Fix typecheck

* Add annotation overlay tests

* Rename LineChartAnnotations component to LineChartAnnotationsOverlay for clarity and update import references accordingly.

* Add popover tests

* Enhance LineChart annotation tests to verify overlay rendering and dimensions. Update tests to ensure proper behavior when annotations are provided, absent, or empty.

* Expose unwrapped LineChart component for testing and add tests for ref interface methods.

* Fix tooltip keyboard navigation by moving annotations out of focusable area

* Use annotation title for button aria-label

* Improve Safari detection and comments

* Improve story styling

* Use composition for annotations with chart context

* Switch to compound component pattern

* fix build errors

* Update tests

* 💄 Fix lint

* Update changelog

Include the breaking change to the annotations API

---------

Co-authored-by: Jasper Kang <[email protected]>

Author: adamwoodnz

pnpm-lock.yaml

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Line chart: Add support for custom interactive annotations. Includes a breaking change to the annotations API, from an `annotations` prop to a compound component pattern.

projects/js-packages/charts/changelog/line-chart-custom-annotations

@@ -48,6 +48,7 @@
 		"./style.css": "./dist/mjs/style.css"
 	},
 	"dependencies": {
+		"@automattic/jetpack-components": "workspace:*",
 		"@automattic/number-formatters": "workspace:*",
 		"@babel/runtime": "7.27.6",
 		"@react-spring/web": "9.7.5",

projects/js-packages/charts/package.json

@@ -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;

projects/js-packages/charts/src/components/line-chart/line-chart-annotation-label-popover.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 { 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 ) || {};
@@ -166,7 +185,7 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 
 	// 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>
 	);