Charts: Standardize Legend stories and documentation

projects/js-packages/charts/changelog/CHARTS-183-legend-stories-and-documentation

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Standardize legend stories and documentation across all chart types.

projects/js-packages/charts/src/charts/bar-chart/stories/index.stories.tsx

@@ -238,18 +238,16 @@ SmartFormatting.parameters = {
 	},
 };
 
-export const WithInteractiveLegend: Story = {
+export const WithLegend: Story = {
 	args: {
 		...Default.args,
 		showLegend: true,
-		legendInteractive: true,
-		chartId: 'bar-chart-with-interactive-legend',
 	},
 	parameters: {
 		docs: {
 			description: {
 				story:
-					'Bar chart with interactive legend. Click on legend items to toggle series visibility. When all series are hidden, a message will be displayed prompting you to click legend items to show data again.',
+					'Props-based legend using `showLegend` and the `legend` config object. Use Storybook controls to adjust legend position, alignment, orientation, shape, and interactivity.',
 			},
 		},
 	},
@@ -260,41 +258,24 @@ export const WithCompositionLegend: StoryObj< typeof BarChart > = {
 	render: args => {
 		const legend = extractLegendConfig( args );
 		return (
-			<BarChart { ...Default.args } { ...args } chartId="composition-bar-chart">
+			<BarChart
+				{ ...Default.args }
+				{ ...args }
+				legend={ { interactive: legend?.interactive } }
+				chartId="composition-bar-chart"
+			>
 				<BarChart.Legend { ...legend } />
 			</BarChart>
 		);
 	},
-	parameters: {
-		docs: {
-			description: {
-				story:
-					'Demonstrates using the composition API with `<BarChart.Legend />` as a child component. This provides the same functionality as the `showLegend` prop but allows for more flexible composition patterns.',
-			},
-		},
-	},
-};
-
-// Story showcasing legend customization controls
-export const CustomLegendPositioning: Story = {
 	args: {
-		withTooltips: true,
-		data: medalCountsData.slice( 0, 3 ), // Use first 3 series for cleaner legend
-		gridVisibility: 'x',
-		maxWidth: 1200,
-		resizeDebounceTime: 300,
-		containerHeight: '400px',
-		// showLegend defaults to false, explicitly enabling for demonstration
-		showLegend: true,
-		legendOrientation: 'vertical',
-		legendAlignment: 'start',
-		legendPosition: 'top',
+		...Default.args,
 	},
 	parameters: {
 		docs: {
 			description: {
 				story:
-					'Bar chart with top-left positioned vertical legend. This demonstrates non-default legend positioning to showcase different legend placement possibilities.',
+					'Composition API using `<BarChart.Legend />` as a child component for explicit legend placement and configuration. This is the recommended approach for flexible legend positioning.',
 			},
 		},
 	},

projects/js-packages/charts/src/charts/leaderboard-chart/stories/index.stories.tsx

@@ -384,17 +384,12 @@ export const WithLegend: Story = {
 		loading: false,
 		showLegend: true,
 	},
-};
-
-export const CustomLegendLabels: Story = {
-	args: {
-		data: sampleData,
-		withComparison: true,
-		loading: false,
-		showLegend: true,
-		legendLabels: {
-			primary: 'Aug 11-Sep 9, 2025',
-			comparison: 'Jul 11-Aug 11, 2025',
+	parameters: {
+		docs: {
+			description: {
+				story:
+					'Props-based legend using `showLegend` and the `legend` config object. Use Storybook controls to adjust legend position, alignment, orientation, shape, and interactivity.',
+			},
 		},
 	},
 };
@@ -403,7 +398,11 @@ export const WithCompositionLegend: Story = {
 	render: args => {
 		const legend = extractLegendConfig( args );
 		return (
-			<LeaderboardChart { ...args } chartId="composition-leaderboard-chart">
+			<LeaderboardChart
+				{ ...args }
+				legend={ { interactive: legend?.interactive } }
+				chartId="composition-leaderboard-chart"
+			>
 				<LeaderboardChart.Legend
 					{ ...legend }
 					shapeStyles={ { width: 8, height: 8, ...legend?.shapeStyles } }
@@ -424,29 +423,7 @@ export const WithCompositionLegend: Story = {
 		docs: {
 			description: {
 				story:
-					'Demonstrates the composition API allowing flexible component composition. The chart can be used with traditional props or with explicit child components for more control over legend positioning and styling.',
-			},
-		},
-	},
-};
-
-export const InteractiveLegend: Story = {
-	args: {
-		data: sampleData,
-		withComparison: true,
-		loading: false,
-		showLegend: true,
-		legendInteractive: true,
-		legendLabels: {
-			primary: 'Current period',
-			comparison: 'Previous period',
-		},
-	},
-	parameters: {
-		docs: {
-			description: {
-				story:
-					'Interactive legend allows users to click legend items to toggle the visibility of current and previous period data. Click on the legend items to show/hide the corresponding bars and values. When all series are hidden, a message is displayed.',
+					'Composition API using `<LeaderboardChart.Legend />` as a child component for explicit legend placement and configuration. This is the recommended approach for flexible legend positioning.',
 			},
 		},
 	},

projects/js-packages/charts/src/charts/line-chart/stories/index.stories.tsx

@@ -141,38 +141,17 @@ Animation.args = {
 	animation: true,
 };
 
-export const WithInteractiveLegend: StoryObj< typeof LineChart > = Template.bind( {} );
-WithInteractiveLegend.args = {
+export const WithLegend: StoryObj< typeof LineChart > = Template.bind( {} );
+WithLegend.args = {
 	...lineChartStoryArgs,
-	chartId: 'interactive-legend-demo',
 	showLegend: true,
-	legendInteractive: true,
 };
 
-WithInteractiveLegend.parameters = {
+WithLegend.parameters = {
 	docs: {
 		description: {
 			story:
-				'Line chart with interactive legend. Click or tap legend items to toggle series visibility. Use Tab to focus legend items, then Enter or Space to toggle. Series colors remain stable when toggling visibility.',
-		},
-	},
-};
-
-export const CustomLegendPositioning: StoryObj< typeof LineChart > = Template.bind( {} );
-CustomLegendPositioning.args = {
-	...lineChartStoryArgs,
-	showLegend: true,
-	legendAlignment: 'start',
-	legendPosition: 'top',
-	legendOrientation: 'horizontal',
-	withLegendGlyph: true,
-};
-
-CustomLegendPositioning.parameters = {
-	docs: {
-		description: {
-			story:
-				'Line chart with top-left positioned horizontal legend. This demonstrates non-default legend positioning to showcase different legend placement possibilities with temperature data for London, Canberra, and Mars.',
+				'Props-based legend using `showLegend` and the `legend` config object. Use Storybook controls to adjust legend position, alignment, orientation, shape, and interactivity.',
 		},
 	},
 };
@@ -182,15 +161,24 @@ export const WithCompositionLegend: StoryObj< typeof LineChart > = {
 	render: args => {
 		const legend = extractLegendConfig( args );
 		return (
-			<LineChart { ...Default.args } { ...args } chartId="composition-line-chart">
+			<LineChart
+				{ ...Default.args }
+				{ ...args }
+				legend={ { interactive: legend?.interactive } }
+				chartId="composition-line-chart"
+			>
 				<LineChart.Legend { ...legend } />
 			</LineChart>
 		);
 	},
+	args: {
+		...Default.args,
+	},
 	parameters: {
 		docs: {
 			description: {
-				story: 'Legend used with LineChart using the composition API, positioned below the chart.',
+				story:
+					'Composition API using `<LineChart.Legend />` as a child component for explicit legend placement and configuration. This is the recommended approach for flexible legend positioning.',
 			},
 		},
 	},

projects/js-packages/charts/src/charts/pie-chart/stories/donut.stories.tsx

@@ -5,7 +5,6 @@ import {
 } from '@wordpress/components';
 import { Fragment } from 'react';
 import { BaseLegendItem } from '../../../components/legend/types';
-import { GlobalChartsProvider } from '../../../providers';
 import {
 	chartDecorator,
 	sharedChartArgTypes,
@@ -217,50 +216,26 @@ export const WithLegend: Story = {
 		showLegend: true,
 		containerHeight: '500px',
 	},
-};
-
-export const WithCompositionLegend: Story = {
-	render: args => {
-		const legend = extractLegendConfig( args );
-		return (
-			<PieChart { ...args } size={ 300 } thickness={ 0.5 } chartId="composition-donut-chart">
-				<Group>
-					<Text textAnchor="middle" verticalAnchor="middle" fontSize={ 16 } y={ -8 }>
-						User Stats
-					</Text>
-					<Text textAnchor="middle" verticalAnchor="middle" fontSize={ 14 } y={ 12 } fill="#666">
-						100K Total
-					</Text>
-				</Group>
-				<PieChart.Legend { ...legend } />
-			</PieChart>
-		);
-	},
-	args: {
-		data,
-		thickness: 0.5,
-	},
 	parameters: {
 		docs: {
 			description: {
 				story:
-					'Demonstrates the donut chart composition API, allowing flexible combination of chart elements and legends.',
+					'Props-based legend using `showLegend` and the `legend` config object. Use Storybook controls to adjust legend position, alignment, orientation, shape, and interactivity.',
 			},
 		},
 	},
 };
 
-export const InteractiveLegend: Story = {
-	render: args => (
-		<GlobalChartsProvider>
-			<PieChartUnresponsive
-				chartId="interactive-donut-chart"
-				size={ args.size }
-				data={ args.data }
+export const WithCompositionLegend: Story = {
+	render: args => {
+		const legend = extractLegendConfig( args );
+		return (
+			<PieChart
+				{ ...args }
+				size={ 300 }
 				thickness={ 0.5 }
-				showLegend={ true }
-				legend={ extractLegendConfig( args ) }
-				legendValueDisplay={ args.legendValueDisplay }
+				legend={ { interactive: legend?.interactive } }
+				chartId="composition-donut-chart"
 			>
 				<Group>
 					<Text textAnchor="middle" verticalAnchor="middle" fontSize={ 16 } y={ -8 }>
@@ -270,68 +245,19 @@ export const InteractiveLegend: Story = {
 						100K Total
 					</Text>
 				</Group>
-				<p style={ { color: '#666' } }>
-					Click legend items to show/hide segments. The total value updates dynamically.
-				</p>
-			</PieChartUnresponsive>
-		</GlobalChartsProvider>
-	),
+				<PieChart.Legend { ...legend } />
+			</PieChart>
+		);
+	},
 	args: {
 		data,
 		thickness: 0.5,
-		legendInteractive: true,
 	},
 	parameters: {
 		docs: {
 			description: {
 				story:
-					'Interactive donut chart with clickable legend. Segments can be hidden/shown, and percentages recalculate automatically. Requires chartId and GlobalChartsProvider.',
-			},
-		},
-	},
-};
-
-export const CustomLegendPositioning: Story = {
-	args: {
-		...Default.args,
-		thickness: 0.4,
-		showLegend: true,
-		legendOrientation: 'vertical',
-		legendAlignment: 'start',
-		legendPosition: 'top',
-		containerHeight: '450px',
-		data: [
-			{
-				label: 'Desktop',
-				value: 45000,
-				valueDisplay: '45K',
-				percentage: 45,
-			},
-			{
-				label: 'Mobile',
-				value: 35000,
-				valueDisplay: '35K',
-				percentage: 35,
-			},
-			{
-				label: 'Tablet',
-				value: 20000,
-				valueDisplay: '20K',
-				percentage: 20,
-			},
-		],
-		children: (
-			<Group>
-				<Text textAnchor="middle" verticalAnchor="middle" fontSize={ 18 } y={ -8 }>
-					Distribution
-				</Text>
-			</Group>
-		),
-	},
-	parameters: {
-		docs: {
-			description: {
-				story: 'Donut chart with vertical legend positioned at the top left.',
+					'Composition API using `<PieChart.Legend />` as a child component for explicit legend placement and configuration. This is the recommended approach for flexible legend positioning.',
 			},
 		},
 	},