Charts: Standardize Legend stories and documentation

[adamwoodnz]

Fixes CHARTS-183: Standardize legend stories and docs
Fixes CHARTS-187: Fix composition legend interactivity in WithCompositionLegend stories

Proposed changes

• Standardized legend stories for BarChart, LineChart, PieChart, Donut, PieSemiCircleChart, and LeaderboardChart to WithLegend (props-based) and WithCompositionLegend (composition API).
• Removed redundant legend stories (e.g., WithInteractiveLegend, CustomLegendPositioning) as their functionality is now covered by the standardized stories and shared controls.
• Retained the CustomLegend donut story — it demonstrates the render prop API, a distinct pattern not covered by the standard two.
• Updated the Legend component documentation (index.docs.mdx) to prioritize composition API examples for chart integration.
• Updated the Legend component stories (index.stories.tsx) to include composition examples.
• Removed redundant orientation="horizontal" from stories and docs Source blocks where it matched the default.
• Fixed WithCompositionLegend stories not wiring legend.interactive to the parent chart component, so toggling interactivity in Storybook now correctly filters series visibility (CHARTS-187).
• Added explicit args to BarChart and LineChart WithCompositionLegend stories so Storybook Controls panel shows initialized values.

Other information

• Generate changelog entries for this PR (using AI).

Related product discussion/links

• CHARTS-183 Standardize legend stories and docs
• CHARTS-187 Fix composition legend interactivity

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

No.

Testing instructions

• Verify Chart Stories:
  • Go to Storybook for each of the following charts: BarChart, LineChart, PieChart, Donut, PieSemiCircleChart, LeaderboardChart.
  • Confirm that each chart has two legend stories: "WithLegend" and "WithCompositionLegend". Donut additionally has "CustomLegend".
  • For both stories, verify that all legend controls (position, alignment, orientation, shape, interactive, styles) are available and functional.
• Verify Composition Legend Interactivity (CHARTS-187):
  • In any WithCompositionLegend story, enable the legendInteractive control.
  • Click a legend item to toggle series visibility — the chart should update accordingly.
• Verify Legend Component Documentation:
  • Go to the Legend component documentation in Storybook (/charts/?path=/docs/components-legend--docs).
  • Ensure the "Integration with Charts" section prominently features the composition API pattern as the primary example.
• Verify Donut CustomLegend:
  • Go to the Donut Chart stories and confirm the CustomLegend story renders with the custom render prop layout (grid with formatted values and comparison deltas).

Linear Issues: CHARTS-183, CHARTS-187

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[github-actions]

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 cursor/CHARTS-183-legend-stories-and-documentation-ab2a branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack cursor/CHARTS-183-legend-stories-and-documentation-ab2a

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]

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 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:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. 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!

[adamwoodnz]

@cursoragent fix the lint issues please

[cursor]

Fixed the trailing newline in donut.stories.tsx that was causing the ESLint failure. Pushed the fix.

  

[jp-launch-control]

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report

[adamwoodnz]

@claude review please

[claude]

Claude finished @adamwoodnz's task in 2m 11s —— View job

---

PR Review

• Gather context and understand request
• Read changed files
• Analyze code and provide review feedback

---

Overall: Clean, well-executed standardization. The CHARTS-187 fix is correctly implemented across all charts. A few minor nits below.

---

CHARTS-187 Fix: Legend Interactivity

The core fix is correct and consistent: all WithCompositionLegend stories now pass legend={ { interactive: legend?.interactive } } to the parent chart so toggling the control actually filters series visibility. Good.

---

Minor Issues

1. Missing args on BarChart and LineChart WithCompositionLegend stories

BarChart.WithCompositionLegend (line 257) and LineChart.WithCompositionLegend (line 160) have no args object, while all other chart composition stories (LeaderboardChart, PieChart, DonutChart, PieSemiCircleChart) define explicit args.

These work because the render function spreads Default.args, but Controls won't have initialized state in the Storybook panel. Leaderboard and Donut define proper args — this is the better pattern.

2. PieChart.WithCompositionLegend doesn't spread Default.args

In pie-chart/stories/index.stories.tsx (line 193-217):

render: args => {
    const legend = extractLegendConfig( args );
    return (
        <PieChart
            { ...args }          // ← no ...Default.args
            legend={ { interactive: legend?.interactive } }
            chartId="composition-pie-chart"
        >

Compare to BarChart and LineChart composition stories which do { ...Default.args } { ...args }. Without spreading Default.args, the PieChart composition story won't use thickness: 1, gapScale: 0, cornerScale: 0, containerWidth/Height from the default, so it may render differently from WithLegend. That said, the args: { data } is so minimal it's probably intentional here (uses component defaults), so this is a minor nit.

3. AlignmentOptions and CustomShape in Legend stories don't strip theme args

Default and Vertical in legend/stories/index.stories.tsx have custom render functions that destructure away themeName and accentColor before spreading onto Legend. But AlignmentOptions (line 296) and CustomShape (line 373) lack custom render functions and would pass those theme args directly to Legend. This was present before this PR so likely not a regression, but it's inconsistent.

4. ManySeries LineChart story has showLegend: true

ManySeries (line 131-136) adds showLegend: true to its args, making it partly overlap with WithLegend. The purpose of ManySeries is to demonstrate data volume — legend being enabled there adds scope creep. Not changed in this PR though.

---

Positive Highlights

• Standardization is clean: exactly two legend stories per chart (WithLegend + WithCompositionLegend) with identical description strings.
• Restoring CustomLegend in donut is the right call — it's a genuinely distinct pattern from the standard two.
• The legend docs reorganization is much improved: composition API is now primary, standalone/decoupled usage is clearly secondary.
• New WithLineChart and WithBarChart stories in the Legend component stories are good additions for the docs page.
• Changelog entry included.

---

Verdict

The PR achieves its goals well. The CHARTS-187 fix is solid. The nits above (missing args on BarChart/LineChart composition stories, no Default.args spread on PieChart) are worth a follow-up if you want tighter consistency, but they're not blocking. Ready to merge after a quick sanity check in Storybook.

[Copilot]

Pull request overview

This PR standardizes legend stories across all chart types (BarChart, LineChart, PieChart, Donut, PieSemiCircleChart, LeaderboardChart) to a consistent WithLegend/WithCompositionLegend pattern, removes redundant stories, updates Legend documentation to prioritize the composition API, and fixes composition legend interactivity by wiring legend.interactive to the parent chart.

Changes:

• Consolidated legend stories to two per chart (WithLegend for props-based, WithCompositionLegend for composition API), removing WithInteractiveLegend, CustomLegendPositioning, etc.
• Fixed WithCompositionLegend stories by passing legend={ { interactive: legend?.interactive } } to the parent chart so interactivity toggling works.
• Updated Legend documentation to recommend composition API as the primary integration pattern.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
charts/src/components/legend/stories/index.stories.tsx	Replaced hook-based chart stories with composition API examples
charts/src/components/legend/stories/index.docs.mdx	Rewritten to prioritize composition API, removed hook-based examples
charts/src/charts/pie-semi-circle-chart/stories/index.stories.tsx	Standardized to WithLegend/WithCompositionLegend, removed redundant stories
charts/src/charts/pie-chart/stories/index.stories.tsx	Standardized to WithLegend/WithCompositionLegend, removed redundant stories
charts/src/charts/pie-chart/stories/donut.stories.tsx	Standardized to WithLegend/WithCompositionLegend, removed redundant stories
charts/src/charts/line-chart/stories/index.stories.tsx	Standardized to WithLegend/WithCompositionLegend, removed redundant stories
charts/src/charts/leaderboard-chart/stories/index.stories.tsx	Standardized to WithLegend/WithCompositionLegend, removed redundant stories
charts/src/charts/bar-chart/stories/index.stories.tsx	Standardized to WithLegend/WithCompositionLegend, removed redundant stories
charts/changelog/CHARTS-183-legend-stories-and-documentation	Changelog entry