Line chart - custom annotations #44131

adamwoodnz · 2025-06-30T03:34:09Z

Fixes CHARTS-47: Line Chart: Custom annotations

Proposed changes:

Adds support for custom annotations with interactivity

Optional renderLabel prop per annotation item which renders custom HTML instead of a basic label
Optional renderLabelPopover prop per annotation which turns the label into a button and will open a popup with custom HTML

Screenshots

Custom vertical line with popover	Custom circle with popover

Notes

Includes a breaking change to the annotations API, from an annotations prop to a compound component pattern, with declarative nested LineChart.Annotation components.

Due to a known issue with positioning within foreignObject elements in Safari, the popovers are positioned in the center of the viewport rather than next to the annotation. This can be improved in a further iteration.

The annotations are rendered in a separate layer above the tooltips, so they are focused individually for now. I think in a further iteration we should add handling similar to what we have for tooltips, so that the annotations overlay is one stop in the tabindex and annotations are focused within that, using arrow keys.

Other information:

Have you written new tests for your changes, if applicable?
Have you checked the E2E test CI results, and verified that your changes do not break them?
Have you tested your changes on WordPress.com, if applicable (if so, you'll see a generated comment below with a script to run)?

Jetpack product discussion

pcO4xN-2zR-p2

Does this pull request change what data or activity we track or use?

No

Testing instructions:

Run pnpm storybook in charts
Go to http://localhost:50240/?path=/story/js-packages-charts-types-line-chart-annotations--custom-vertical
Resize the chart to see the annotation positions update
Click the annotations to activate the popovers
Close the popovers by clicking outside or using the close button
Use your keyboard to focus the annotation and open and close the popover
Test in different browsers
Regression test the tooltip accessibility

github-actions · 2025-06-30T03:35:04Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add a "[Type]" label (Bug, Enhancement, Janitorial, Task).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

jp-launch-control · 2025-06-30T03:36:47Z

Code Coverage Summary

Coverage changed in 3 files.

File	Coverage	Δ%
projects/js-packages/charts/src/components/line-chart/line-chart-annotation.tsx	82/88 (93.18%)	1.63%
projects/js-packages/charts/src/components/line-chart/line-chart.tsx	93/98 (94.90%)	1.00%
projects/js-packages/charts/src/components/shared/utils.ts	9/9 (100.00%)	0.00%

3 files are newly checked for coverage.

File	Coverage
projects/js-packages/charts/src/components/line-chart/line-chart-annotation-label-popover.tsx	16/24 (66.67%) 💚
projects/js-packages/charts/src/components/line-chart/line-chart-context.tsx	5/6 (83.33%) 💚
projects/js-packages/charts/src/components/line-chart/line-chart-annotations-overlay.tsx	46/46 (100.00%) 💚

Full summary · PHP report · JS report

github-actions · 2025-07-01T00:15:26Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the charts-47-line-chart-custom-annotations branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack charts-47-line-chart-custom-annotations

bin/jetpack-downloader test jetpack-mu-wpcom-plugin charts-47-line-chart-custom-annotations

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

adamwoodnz · 2025-07-09T05:04:53Z

projects/js-packages/charts/src/components/line-chart/line-chart-annotation-label-popover.tsx

+		<div className={ styles[ 'line-chart__annotation-label' ] }>
+			<button
+				ref={ buttonRef }
+				{ ...( { popovertarget: popoverId } as ButtonWithPopover ) }


Using the popover API for these rather than a modal as it has:

Built-in Accessibility: The popover API automatically handles:

Focus management

ARIA attributes

Keyboard navigation (Escape key)

Screen reader announcements

Browser Behavior: Native handling of:

Click outside to close

Proper z-index stacking

Scroll behavior

Mobile touch interactions

Browser support is good: https://caniuse.com/mdn-api_htmlelement_popover

adamwoodnz · 2025-07-09T05:27:37Z

projects/js-packages/charts/src/components/line-chart/line-chart-annotation-label-popover.tsx

+					height: `${ POPOVER_BUTTON_SIZE }px`,
+					transform: `translate(${ POPOVER_BUTTON_SIZE / 2 }px, 0)`,
+				} }
+				aria-label={ title || 'View details' }


I found some other instances where we have static untranslated strings, should we be using @wordpress/i18n?

eg.

import { __ } from '@wordpress/i18n'; ... aria-label={ title ?? __( 'See details', 'automattic-charts' ) } ...

I agree - we need these translated for sure.

Issue: CHARTS-58: Charts: Translate all static strings

Copilot

Pull Request Overview

This PR adds support for fully customizable annotations on the LineChart component, including optional HTML labels and popovers.

Introduce renderLabel and renderLabelPopover props and refactor annotation rendering to use HtmlLabel and an external overlay.
Add a LineChartAnnotationsOverlay component and expose chart scales/dimensions via forwardRef for accurate positioning.
Update tests and Storybook stories to cover the new custom annotation and popover capabilities.

Reviewed Changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
projects/js-packages/charts/src/types.ts	Add Popover API attribute type definitions
projects/js-packages/charts/src/components/shared/utils.ts	Add `isSafari` helper
projects/js-packages/charts/src/components/line-chart/line-chart.tsx	Refactor to support forwarded ref and external overlay
projects/js-packages/charts/src/components/line-chart/line-chart-annotation.tsx	Add `renderLabel`/`renderLabelPopover` and HTML labels
projects/js-packages/charts/src/components/line-chart/line-chart-annotations-overlay.tsx	New overlay component
projects/js-packages/charts/src/components/line-chart/line-chart-annotation-label-popover.tsx	New popover button & positioning logic
projects/js-packages/charts/src/components/line-chart/test/*	Update and add tests for custom annotations
projects/js-packages/charts/src/components/line-chart/stories/annotation.stories.tsx	Add stories for custom annotations

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (2)

projects/js-packages/charts/src/components/line-chart/line-chart-annotation.tsx:47

[nitpick] The new renderLabel and renderLabelPopover props lack JSDoc comments. Consider adding descriptions for these hooks in LineChartAnnotationProps to clarify their purpose and usage.

	renderLabel?: FC< { title: string; subtitle?: string } >;

projects/js-packages/charts/src/components/line-chart/line-chart-annotation.tsx:162

[nitpick] The default vertical anchor was changed from 'middle' to 'start', which may misalign existing annotations. Verify whether this change is intentional or should be reverted to preserve the previous positioning.

		return 'start';

projects/js-packages/charts/src/components/shared/utils.ts

annacmc · 2025-07-09T05:53:59Z

Hey @adamwoodnz ! I've been working on a chart context feature that
enables modular legend management, and I'm curious about potential
collaboration opportunities with your annotations work.

Currently, chart context allows legends to be rendered independently from
charts - you can place a <Legend> component anywhere and it reads chart data
from context. This creates a really flexible architecture where multiple charts
can share legends, or legends can be positioned outside chart containers.

I'm wondering if we should explore extending this pattern to annotations as
well. Right now your implementation passes annotations as props directly to the
chart (which works great!), but I'm thinking about whether a context-based
approach might unlock similar modularity:

// Current approach

<LineChart annotations={annotationData} />

// Potential context approach

 <ChartProvider>
   <LineChart />
   <ChartAnnotations>
     <Annotation x="2023-01-01" y={100} label="Launch" />
   </ChartAnnotations>
 </ChartProvider>

This could enable things like shared annotations across multiple charts, or
annotations that respond to context-level events. The main challenge would be
that annotations need real-time access to scales/dimensions (which you've
solved elegantly with the ref pattern), whereas legends work with more static
data.

What are your thoughts? Worth exploring, or do you think the current prop-based
approach better serves the annotation use cases you're targeting?

adamwoodnz · 2025-07-09T22:48:27Z

Yeah I certainly think it's worth exploring, I'll take a look at your PR 👍

adamwoodnz · 2025-07-10T04:02:34Z

projects/js-packages/charts/src/components/line-chart/line-chart.tsx

+				{ /* Render annotations as external overlay to avoid interaction blocking */ }
+				{ annotations?.length && (
+					<LineChartAnnotationsOverlay
+						chartRef={ internalChartRef }
+						annotations={ annotations }
+						chartWidth={ width }
+						chartHeight={ height - ( showLegend ? legendHeight : 0 ) }
+					/>
 				) }


The XYChart renders a rect interaction layer over the whole chart which is used for tooltips, etc. If the annotations are rendered within the XYChart then they are not clickable, even with z-index changes. This means we need to render them above and create our own annotations overlay which handles synchronising the chart dimensions and scales for correct positioning of the annotations.

adamwoodnz · 2025-07-10T23:02:49Z

bugbot run

…fying label positioning logic and improving code clarity.

…dering in LineChart. Update renderLabel methods to utilize these new components, enhancing code clarity and maintainability.

…ing proper rendering only when scales are stable.

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

…for clarity and update import references accordingly.

…mensions. Update tests to ensure proper behavior when annotations are provided, absent, or empty.

…f interface methods.

…e area

Include the breaking change to the annotations API

adamwoodnz self-assigned this Jun 30, 2025

github-actions bot added [JS Package] Charts [Status] In Progress RNA labels Jun 30, 2025

github-actions bot added the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label Jun 30, 2025

adamwoodnz added [Type] Feature Development of a new feature and removed [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. labels Jun 30, 2025

adamwoodnz force-pushed the charts-47-line-chart-custom-annotations branch from 0cb5041 to c4bf347 Compare July 1, 2025 00:14

github-actions bot added the [Tests] Includes Tests label Jul 2, 2025

adamwoodnz force-pushed the charts-47-line-chart-custom-annotations branch 5 times, most recently from 5772d4a to f4ab227 Compare July 7, 2025 23:05

adamwoodnz commented Jul 9, 2025

View reviewed changes

adamwoodnz changed the title ~~Charts 47 line chart custom annotations~~ Line chart - custom annotations Jul 9, 2025

adamwoodnz requested a review from Copilot July 9, 2025 05:33

Copilot AI reviewed Jul 9, 2025

View reviewed changes

projects/js-packages/charts/src/components/shared/utils.ts Outdated Show resolved Hide resolved

adamwoodnz requested a review from a team July 10, 2025 03:32

adamwoodnz marked this pull request as ready for review July 10, 2025 03:32

adamwoodnz commented Jul 10, 2025

View reviewed changes

adamwoodnz force-pushed the charts-47-line-chart-custom-annotations branch from def84b6 to 3e33514 Compare July 10, 2025 22:59

adamwoodnz force-pushed the charts-47-line-chart-custom-annotations branch from 3e33514 to 7176c2d Compare July 11, 2025 01:39

adamwoodnz and others added 21 commits July 16, 2025 14:13

Refactor LineChartAnnotation to remove unused dx and dy props, simpli…

f77e892

…fying label positioning logic and improving code clarity.

Add DeployedIcon and AlertIcon components for improved annotation ren…

91a6441

…dering in LineChart. Update renderLabel methods to utilize these new components, enhancing code clarity and maintainability.

Unify tooltip and popover styles

fcfab1d

Add tests

fd22f30

Introduce scalesStable state to track when scales have settled, ensur…

472274b

…ing proper rendering only when scales are stable.

Improve popover positioining

b5c5e3e

- 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

913aece

Add popover tests

f620963

Fix typecheck

cf97599

Add annotation overlay tests

9743cc0

Rename LineChartAnnotations component to LineChartAnnotationsOverlay …

9337d30

…for clarity and update import references accordingly.

Add popover tests

5ebda9a

Enhance LineChart annotation tests to verify overlay rendering and di…

15c7978

…mensions. Update tests to ensure proper behavior when annotations are provided, absent, or empty.

Expose unwrapped LineChart component for testing and add tests for re…

0b80464

…f interface methods.

Fix tooltip keyboard navigation by moving annotations out of focusabl…

25a6598

…e area

Use annotation title for button aria-label

c76cab9

Improve Safari detection and comments

2dbbc55

Improve story styling

9953b53

Use composition for annotations with chart context

8b7aaac

Switch to compound component pattern

515d99a

fix build errors

16dd7d4

adamwoodnz dismissed annacmc’s stale review via 16dd7d4 July 16, 2025 02:27

adamwoodnz force-pushed the charts-47-line-chart-custom-annotations branch from e51b142 to 16dd7d4 Compare July 16, 2025 02:27

adamwoodnz added 3 commits July 16, 2025 14:35

Update tests

0230696

💄 Fix lint

1c87187

Update changelog

6616ff8

Include the breaking change to the annotations API

adamwoodnz force-pushed the charts-47-line-chart-custom-annotations branch from 972efef to 6616ff8 Compare July 16, 2025 20:07

adamwoodnz merged commit 2cf8757 into trunk Jul 16, 2025
85 checks passed

adamwoodnz deleted the charts-47-line-chart-custom-annotations branch July 16, 2025 21:26

github-actions bot removed the [Status] Needs Team Review Obsolete. Use Needs Review instead. label Jul 16, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Line chart - custom annotations #44131

Line chart - custom annotations #44131

Uh oh!

adamwoodnz commented Jun 30, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jun 30, 2025 •

edited

Loading

Uh oh!

jp-launch-control bot commented Jun 30, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jul 1, 2025 •

edited

Loading

Uh oh!

adamwoodnz Jul 9, 2025

Uh oh!

adamwoodnz Jul 9, 2025 •

edited

Loading

Uh oh!

kangzj Jul 14, 2025

Uh oh!

adamwoodnz Jul 16, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

annacmc commented Jul 9, 2025

Uh oh!

adamwoodnz commented Jul 9, 2025

Uh oh!

adamwoodnz Jul 10, 2025

Uh oh!

adamwoodnz commented Jul 10, 2025

Uh oh!

Uh oh!

Uh oh!

Line chart - custom annotations #44131

Line chart - custom annotations #44131

Uh oh!

Conversation

adamwoodnz commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes:

Screenshots

Notes

Other information:

Jetpack product discussion

Does this pull request change what data or activity we track or use?

Testing instructions:

Uh oh!

github-actions bot commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jp-launch-control bot commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Summary

Uh oh!

github-actions bot commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adamwoodnz Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

adamwoodnz Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kangzj Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

adamwoodnz Jul 16, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

annacmc commented Jul 9, 2025

Uh oh!

adamwoodnz commented Jul 9, 2025

Uh oh!

adamwoodnz Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

adamwoodnz commented Jul 10, 2025

Uh oh!

Uh oh!

Uh oh!

adamwoodnz commented Jun 30, 2025 •

edited

Loading

github-actions bot commented Jun 30, 2025 •

edited

Loading

jp-launch-control bot commented Jun 30, 2025 •

edited

Loading

github-actions bot commented Jul 1, 2025 •

edited

Loading

adamwoodnz Jul 9, 2025 •

edited

Loading