Charts: Add standalone Legend component #44245

annacmc · 2025-07-09T13:36:30Z

related to: CHARTS-50: Standalone Legend Component

Proposed changes:

This feature adds a flexible standalone Legend component that can work
independently with manual data or automatically integrate with charts through a
shared context system. The new useChartLegendData hook processes chart data
(SeriesData, DataPointPercentage) into legend format, while the Chart Context
allows legends to be shared between multiple charts using chartId props. All
existing chart components have been updated to support this system while
maintaining backward compatibility.

Other information:

Have you written new tests for your changes, if applicable? (Tests split to follow-up PR for easier review)
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

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

No data tracking changes.

Testing instructions:

  - Storybook: npm run storybook
  - Tests: npm test
  - TypeScript: npm run typecheck
  - Build: npm run build

Storybook Testing

Navigate to Legend stories (JS Packages/Charts/Composites/Legend)
Test all chart stories: Line Chart, Bar Chart, Pie Chart, Pie Semi-Circle Chart
Verify legends render correctly in all orientations (horizontal/vertical)
Check console for errors or warnings
Test legend stories specifically to ensure legends still work properly

Core Functionality

Standalone legends: Display independently without charts using manual data
Context integration: Charts with showLegend={false} still provide data to
standalone legends via chartId
Multiple charts: Verify multiple chart instances don't interfere with each other
Legend data accuracy: Colors, labels, values, and glyphs display correctly

Performance & Quality

Tests: npm test - all tests should pass
TypeScript: npm run typecheck - should pass without errors
Build: npm run build - completes without errors
Re-renders: No performance regressions, memoization working properly

Regression Testing

Visual consistency: Charts render as before (no visual changes)
Legend integration: Chart legends continue working when showLegend={true}
Chart context: Proper chart registration/unregistration
Cross-compatibility: All chart types work with new legend system

github-actions · 2025-07-09T13:37: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), and enable the add/charts-50-standalone-legend-component branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack add/charts-50-standalone-legend-component

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

github-actions · 2025-07-09T13:37:36Z

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-07-09T13:50:06Z

Code Coverage Summary

Coverage changed in 5 files.

File	Coverage	Δ%	Δ Uncovered
projects/js-packages/charts/src/components/bar-chart/bar-chart.tsx	71/77 (92.21%)	-0.94%	1 ❤️‍🩹
projects/js-packages/charts/src/components/line-chart/line-chart.tsx	98/104 (94.23%)	-0.67%	1 ❤️‍🩹
projects/js-packages/charts/src/components/pie-chart/pie-chart.tsx	51/55 (92.73%)	-1.27%	1 ❤️‍🩹
projects/js-packages/charts/src/components/pie-semi-circle-chart/pie-semi-circle-chart.tsx	52/52 (100.00%)	0.00%	0 💚
projects/js-packages/charts/src/providers/chart-context/chart-context.tsx	20/20 (100.00%)	0.00%	0 💚

2 files are newly checked for coverage.

File	Coverage
projects/js-packages/charts/src/components/legend/use-chart-legend-data.ts	22/27 (81.48%) 💚
projects/js-packages/charts/src/components/legend/legend.tsx	7/8 (87.50%) 💚

Full summary · PHP report · JS report

_{Coverage check overridden by

Coverage tests to be added later
Use to ignore the Code coverage requirement check when tests will be added in a follow-up PR
.}

- Create ChartLegendOptions interface with showValues, withGlyph, glyphSize, and renderGlyph options - Add ChartLegendProps interface extending LegendProps with chartId for future context integration - Implement useChartLegendData hook with overloads for SeriesData[] and DataPoint[]/DataPointPercentage[] - Support both series data and point data with proper color, shape, and glyph handling - Include valueDisplay preference for DataPointPercentage items - Return properly typed LegendItemWithGlyph[] or LegendItemWithoutGlyph[] arrays

- Create ChartLegend component as a wrapper around BaseLegend - Accept chartId prop for future context integration - Pass through all legend props to BaseLegend for consistent behavior - Enables standalone legend usage independent of chart showLegend prop

- Replace inline legend items creation with useChartLegendData hook - Pass withGlyph and glyphSize options to maintain existing functionality - Eliminates duplicate legend creation logic - Maintains all existing legend behavior and styling

- Replace inline legend items creation with useChartLegendData hook - Add useChartTheme hook to get provider theme for consistent legend colors - Move hook call to proper position to avoid rules-of-hooks violation - Remove duplicate legend creation logic - Maintains all existing legend behavior and styling

- Replace inline legend items creation with useChartLegendData hook in both components - Enable showValues option for both charts to display percentages in legend - Move hook calls to proper position to avoid rules-of-hooks violations - Remove duplicate legend creation logic - Maintain valueDisplay support for properly formatted percentage values - Keep all existing legend behavior and styling

- Export ChartLegend component and useChartLegendData hook from main index - Export ChartLegendProps and ChartLegendOptions types - Add chart-legend module index file with all exports - Makes standalone legend functionality available to consumers

- Create multiple story examples showing different usage patterns - Include stories for standalone usage, chart integration, and alignment options - Add stories demonstrating usage with LineChart, BarChart, and PieChart - Include examples for multiple charts sharing a legend - Add comprehensive test suite for ChartLegend component and useChartLegendData hook - Test both SeriesData and DataPointPercentage data types - Test memoization, glyph handling, and value display functionality - Fix TypeScript any usage in mock functions

- Resolve merge conflicts from chart context foundation PR - Fix duplicate legendItems declarations in PieChart and PieSemiCircleChart - Maintain custom color handling in PieSemiCircleChart using accessors - Fix type-only import for AnnotationStyles - Fix duplicate identifier in ChartLegend stories

- Add chart context integration to automatically retrieve legend data - Support chartId prop for standalone usage - Maintain fallback to items prop for manual data passing - Add story demonstrating standalone usage with chartId - Component works with showLegend=false charts - Accepts all BaseLegend props through inheritance

- Create validateSeriesData for line/bar charts - Create validatePercentageData for pie charts - Create validateSemiCircleData for semi-circle charts - Create validateBarChartData for bar-specific validation - Eliminates ~60 lines of duplicated validation code

- Enhances existing Legend to support chartId prop - Automatically retrieves legend data from chart context - Falls back to manual items prop for backward compatibility - Enables standalone legend usage with <Legend chartId="my-chart" />

- Extract formatPointValue for consistent value formatting - Extract createBaseLegendItem for common legend item creation - Extract processSeriesData and processPointData functions - Eliminates ~50 lines of duplicated mapping logic - Improves code readability and testability

- Split LegendProps into BaseLegendProps and LegendProps - BaseLegendProps for direct usage (items required) - LegendProps for context usage (items optional, chartId added) - Export new Legend component alongside BaseLegend - Export useChartLegendData and ChartLegendOptions

…ive sizing

annacmc · 2025-07-24T12:46:22Z

Thanks so much @adamwoodnz for such a thorough check and review, it's ended up being quite the mission of a PR to work through. I believe I've fixed up and addressed all of your comments with the exception of:

Better Storybook demos and docs
Vertical alignment legend issues

Both are coming in followups to this PR. If you get a chance, take another look through and see if you think this is okay enough now as it is to get it merged and keep moving forward 😄

🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

kangzj · 2025-07-24T23:41:15Z

projects/js-packages/charts/src/components/legend/use-chart-legend-data.ts

+ * @param options - Configuration options for legend generation
+ * @return Array of legend items ready for display
+ */
+export function useChartLegendData<


Love this hook 🪝

kangzj · 2025-07-25T00:34:38Z

projects/js-packages/charts/src/components/pie-semi-circle-chart/pie-semi-circle-chart.tsx

@@ -275,7 +287,7 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 			) }

 			{ showLegend && (
-				<Legend
+				<BaseLegend


I wonder why chartId is not passed here, which is not consistent with the implementation in line chart

projects/js-packages/charts/src/index.ts

…alone-legend-component' into add/charts-50-standalone-legend-component

kangzj · 2025-07-25T00:58:29Z

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

-				shapeStyle: group?.options?.legendShapeStyle,
-			} ) ),
-		[ dataSorted, getColor ]
+	// Memoize metadata to prevent unnecessary re-registration


Let's centralize the logic to useChartRegistration so that it wouldn't have to be repeated every time.

kangzj · 2025-07-25T00:59:19Z

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

@@ -347,17 +346,28 @@ const BarChartInternal: FC< BarChartProps > = ( {
 					className={ styles[ 'bar-chart__legend' ] }
 					shape={ legendShape }
 					ref={ legendRef }
+					chartId={ chartId }


I changed BaseLengend to Legend like what's happening in line chart. Please revert if this was intentional.

kangzj

I went ahead a tweaked a couple of small things. Hope you don't mind.

Maybe it's worth to take another review from @adamwoodnz, but it otherwise looks good to me!

------UPDATE------
It's awesome to see the standalone legends. Really cool 👍

kangzj · 2025-07-25T01:08:45Z

Notice some minor cutoff for pie chart with legend but I don't think it's related to the PR:

kangzj · 2025-07-25T01:10:49Z

Hi @adamwoodnz & @annacmc, I'm curious to hear your thoughts - is it possible we consolidate the providers for themes, annotations (is this one internal) and legends to reduce the burden of chart lib adoption?

annacmc · 2025-07-25T01:28:45Z

Notice some minor cutoff for pie chart with legend but I don't think it's related to the PR:

I believe this is specifically only a problem with the vertical legends, which a fix is coming in its own PR soon 😄

adamwoodnz · 2025-07-25T01:30:55Z

Hi @adamwoodnz & @annacmc, I'm curious to hear your thoughts - is it possible we consolidate the providers for themes, annotations (is this one internal) and legends to reduce the burden of chart lib adoption?

I initially tried adding the internal line chart context to the chart context, but it was complicated. I eventually decided I couldn't think of a reason another chart would need access to that information, so I kept it simple and scoped it to the chart instance. In terms of adoption friction; I don't think a consumer would ever need to deal with it as it currently stands, as it's constructed by the chart for the sole purpose of the annotations overlay.

I can see a benefit to the chart context providing the theme though.

adamwoodnz

Clipping issues seem fixed, nice!

LGTM

annacmc self-assigned this Jul 9, 2025

annacmc requested a review from Copilot July 9, 2025 13:36

github-actions bot added [JS Package] Charts [Status] In Progress RNA labels Jul 9, 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 Jul 9, 2025

This comment was marked as outdated.

Sign in to view

annacmc force-pushed the add/charts-50-standalone-legend-component branch 2 times, most recently from ce9977f to b018ace Compare July 11, 2025 10:07

annacmc requested a review from Copilot July 14, 2025 23:51

This comment was marked as outdated.

Sign in to view

annacmc requested a review from Copilot July 15, 2025 08:57

This comment was marked as outdated.

Sign in to view

annacmc and others added 14 commits July 16, 2025 09:23

Add ChartLegend exports to package API

36fe909

- Export ChartLegend component and useChartLegendData hook from main index - Export ChartLegendProps and ChartLegendOptions types - Add chart-legend module index file with all exports - Makes standalone legend functionality available to consumers

changelog

ad3bb4a

Add context-aware Legend component

5da4e04

- Enhances existing Legend to support chartId prop - Automatically retrieves legend data from chart context - Falls back to manual items prop for backward compatibility - Enables standalone legend usage with <Legend chartId="my-chart" />

Remove hardcoded dimensions from dashboard PieChart to enable respons…

4b4bfde

…ive sizing

annacmc requested a review from adamwoodnz July 24, 2025 12:46

Remove unnecessary space character from legend value

75df5dc

🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

kangzj reviewed Jul 24, 2025

View reviewed changes

annacmc and others added 4 commits July 25, 2025 10:29

Merge branch 'trunk' into add/charts-50-standalone-legend-component

701da72

fix responsive height calculation for line chart

bfb564a

should probably be better always manipulate the container

cc07742

Merge branch 'trunk' into add/charts-50-standalone-legend-component

1f3b3d9

kangzj reviewed Jul 25, 2025

View reviewed changes

make legend implementation consistent

c59730d

kangzj reviewed Jul 25, 2025

View reviewed changes

projects/js-packages/charts/src/index.ts Show resolved Hide resolved

annacmc force-pushed the add/charts-50-standalone-legend-component branch from b022a55 to 701da72 Compare July 25, 2025 00:45

kangzj added 2 commits July 25, 2025 12:51

Merge remote-tracking branch 'refs/remotes/origin/add/charts-50-stand…

7aecb7f

…alone-legend-component' into add/charts-50-standalone-legend-component

revert unnecessary change

addfb32

kangzj reviewed Jul 25, 2025

View reviewed changes

kangzj previously approved these changes Jul 25, 2025

View reviewed changes

fix typing

1682004

kangzj dismissed their stale review via 1682004 July 25, 2025 01:07

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

kangzj approved these changes Jul 25, 2025

View reviewed changes

adamwoodnz approved these changes Jul 25, 2025

View reviewed changes

annacmc merged commit 506284f into trunk Jul 25, 2025
84 checks passed

annacmc deleted the add/charts-50-standalone-legend-component branch July 25, 2025 04:32

github-actions bot removed the [Status] In Progress label Jul 25, 2025

Charts: Add standalone Legend component #44245

Charts: Add standalone Legend component #44245

Uh oh!

Conversation

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

Uh oh!

Proposed changes:

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 Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

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

Uh oh!

Code Coverage Summary

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

annacmc commented Jul 24, 2025

Uh oh!

kangzj Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

kangzj Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kangzj Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

kangzj Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

kangzj left a comment • 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 commented Jul 25, 2025

Uh oh!

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

Uh oh!

Uh oh!

annacmc commented Jul 25, 2025

Uh oh!

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

Uh oh!

Uh oh!

adamwoodnz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

annacmc commented Jul 9, 2025 •

edited

Loading

github-actions bot commented Jul 9, 2025 •

edited

Loading

github-actions bot commented Jul 9, 2025 •

edited

Loading

jp-launch-control bot commented Jul 9, 2025 •

edited

Loading

kangzj left a comment •

edited

Loading

kangzj commented Jul 25, 2025 •

edited

Loading

adamwoodnz commented Jul 25, 2025 •

edited

Loading