@automattic/charts 1.4.0 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "1.4.0",
+	"version": "1.4.2",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -63,7 +63,7 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.1.7",
+		"@automattic/number-formatters": "^1.1.10",
 		"@babel/runtime": "7.29.2",
 		"@react-spring/web": "9.7.5",
 		"@visx/annotation": "^3.12.0",
@@ -84,7 +84,7 @@
 		"@visx/xychart": "^3.12.0",
 		"@wordpress/i18n": "^6.0.0",
 		"@wordpress/icons": "^12.0.0",
-		"@wordpress/theme": "0.11.0",
+		"@wordpress/theme": "0.13.0",
 		"@wordpress/ui": "0.11.0",
 		"clsx": "2.1.1",
 		"date-fns": "^4.1.0",
@@ -110,16 +110,16 @@
 		"@types/react-dom": "18.3.7",
 		"@typescript/native-preview": "7.0.0-dev.20260225.1",
 		"@visx/glyph": "3.12.0",
-		"@wordpress/components": "32.6.0",
-		"@wordpress/element": "6.44.0",
-		"@wordpress/private-apis": "1.44.0",
-		"babel-jest": "30.3.0",
+		"@wordpress/components": "33.1.0",
+		"@wordpress/element": "6.46.0",
+		"@wordpress/private-apis": "1.46.0",
+		"babel-jest": "30.4.1",
 		"babel-plugin-react-remove-properties": "^0.3.1",
 		"esbuild": "0.27.4",
 		"esbuild-plugin-babel": "^0.2.3",
 		"esbuild-sass-plugin": "^3.1.0",
 		"identity-obj-proxy": "^3.0.0",
-		"jest": "30.3.0",
+		"jest": "30.4.2",
 		"jest-extended": "7.0.0",
 		"postcss": "8.5.14",
 		"postcss-modules": "6.0.1",

package/src/charts/area-chart/area-chart.tsx

@@ -1,5 +1,5 @@
 import { formatNumberCompact } from '@automattic/number-formatters';
-import { XYChart, AreaSeries, AreaStack, Grid, Axis } from '@visx/xychart';
+import { XYChart, AnimatedAreaSeries, AnimatedAreaStack, Grid, Axis } from '@visx/xychart';
 import { __ } from '@wordpress/i18n';
 import clsx from 'clsx';
 import {
@@ -135,6 +135,57 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 			totalPoints: dataSorted[ 0 ]?.data.length || 0,
 		} );
 
+		// Computed from the full data set (ignoring legend visibility) so the y-axis stays
+		// fixed when series are toggled off — otherwise visx auto-fits to the remaining data
+		// and the chart appears to rescale. Skipped for non-default stack offsets, which
+		// reshape the y-extent (`expand` → [0,1], `wiggle`/`silhouette` → centred around
+		// zero) — letting visx derive the domain is correct there.
+		const fixedYDomain = useMemo< [ number, number ] | undefined >( () => {
+			if (
+				! legendInteractive ||
+				! dataSorted.length ||
+				! dataSorted[ 0 ].data.length ||
+				( stacked && stackOffset !== 'none' )
+			) {
+				return undefined;
+			}
+
+			if ( stacked ) {
+				// d3-stack with `offset: 'none'` stacks positives upward from 0 and
+				// negatives downward from 0, so we need both extremes.
+				const numPoints = Math.max( ...dataSorted.map( s => s.data.length ) );
+				let posMax = 0;
+				let negMin = 0;
+				for ( let i = 0; i < numPoints; i++ ) {
+					let posSum = 0;
+					let negSum = 0;
+					for ( const series of dataSorted ) {
+						const v = Number( series.data[ i ]?.value );
+						if ( Number.isNaN( v ) ) continue;
+						if ( v >= 0 ) posSum += v;
+						else negSum += v;
+					}
+					if ( posSum > posMax ) posMax = posSum;
+					if ( negSum < negMin ) negMin = negSum;
+				}
+				return [ negMin, posMax ];
+			}
+
+			let max = -Infinity;
+			let min = Infinity;
+			for ( const series of dataSorted ) {
+				for ( const point of series.data ) {
+					const v = Number( point?.value );
+					if ( ! Number.isNaN( v ) ) {
+						if ( v > max ) max = v;
+						if ( v < min ) min = v;
+					}
+				}
+			}
+			if ( max === -Infinity ) return undefined;
+			return [ Math.min( 0, min ), max ];
+		}, [ dataSorted, stacked, stackOffset, legendInteractive ] );
+
 		const chartOptions = useMemo( () => {
 			const formatter = options?.axis?.x?.tickFormat || getFormatter( dataSorted );
 
@@ -164,10 +215,11 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 					nice: true,
 					// Stacked areas should always include zero so the baseline is meaningful.
 					zero: stacked,
+					...( fixedYDomain ? { domain: fixedYDomain } : {} ),
 					...options?.yScale,
 				},
 			};
-		}, [ options, dataSorted, width, stacked ] );
+		}, [ options, dataSorted, width, stacked, fixedYDomain ] );
 
 		const defaultMargin = useChartMargin( height, chartOptions, dataSorted, theme );
 
@@ -191,11 +243,48 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 		} );
 
 		const prefersReducedMotion = usePrefersReducedMotion();
+		const animationEnabled = !! animation && ! prefersReducedMotion;
 
 		const accessors = {
 			xAccessor: ( d: DataPointDate ) => d?.date,
 			yAccessor: ( d: DataPointDate ) => d?.value,
 		};
+		const zeroYAccessor = useCallback( () => 0, [] );
+
+		// Hidden series are still registered with visx (so paths can interpolate), but their
+		// data points should not appear in the tooltip.
+		const visibleLabels = useMemo(
+			() => new Set( seriesWithVisibility.filter( s => s.isVisible ).map( s => s.series.label ) ),
+			[ seriesWithVisibility ]
+		);
+		const filteredRenderTooltip = useCallback(
+			( params: Parameters< typeof renderTooltip >[ 0 ] ) => {
+				if ( ! legendInteractive ) return renderTooltip( params );
+				const datumByKey = params?.tooltipData?.datumByKey;
+				if ( ! datumByKey ) return renderTooltip( params );
+				const filtered = Object.fromEntries(
+					Object.entries( datumByKey ).filter( ( [ key ] ) => visibleLabels.has( key ) )
+				);
+				if ( Object.keys( filtered ).length === 0 ) return null;
+				// `nearestDatum` may still point at a hidden series; re-point it at the first
+				// visible entry so consumers that read it (e.g. for the tooltip heading) don't
+				// surface hidden-series state.
+				const nearestDatum = params?.tooltipData?.nearestDatum;
+				const nextNearest =
+					nearestDatum && visibleLabels.has( nearestDatum.key )
+						? nearestDatum
+						: { ...Object.values( filtered )[ 0 ], distance: nearestDatum?.distance ?? 0 };
+				return renderTooltip( {
+					...params,
+					tooltipData: {
+						...params.tooltipData,
+						datumByKey: filtered,
+						nearestDatum: nextNearest,
+					} as typeof params.tooltipData,
+				} );
+			},
+			[ renderTooltip, legendInteractive, visibleLabels ]
+		);
 
 		// Defaults that depend on stacked vs overlapping mode.
 		const resolvedFillOpacity = fillOpacity ?? ( stacked ? 0.85 : 0.4 );
@@ -224,6 +313,33 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 		const visibleSeries = seriesWithVisibility.filter( ( { isVisible } ) => isVisible );
 		const curve = getCurveType( curveType, smoothing );
 
+		// Visx's `<AreaStack>` keys each `<Area>` by `stackIndex-dataKey`, so filtering out
+		// a hidden series would shift indexes and remount every path. Instead we keep every
+		// series mounted and zero out hidden ones via `yAccessor` — react-spring then
+		// interpolates the `d` attribute, giving a smooth "going down" effect for the
+		// hidden area and a smooth re-flow for the rest.
+		const renderSeries = ( {
+			series: seriesData,
+			index,
+			isVisible,
+		}: ( typeof seriesWithVisibility )[ number ] ) => {
+			const { color, lineStyles } = getElementStyles( { data: seriesData, index } );
+			return (
+				<AnimatedAreaSeries
+					key={ seriesData?.label || index }
+					dataKey={ seriesData?.label }
+					data={ seriesData.data as DataPointDate[] }
+					xAccessor={ accessors.xAccessor }
+					yAccessor={ isVisible || ! legendInteractive ? accessors.yAccessor : zeroYAccessor }
+					fill={ color }
+					fillOpacity={ resolvedFillOpacity }
+					{ ...( stacked ? {} : { renderLine: resolvedWithStroke, curve } ) }
+					lineProps={ { stroke: color, ...lineStyles } }
+					data-testid={ `area-chart-series-${ index }` }
+				/>
+			);
+		};
+
 		return (
 			<SingleChartContext.Provider
 				value={ {
@@ -241,7 +357,7 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 					className={ clsx(
 						'area-chart',
 						styles[ 'area-chart' ],
-						{ [ styles[ 'area-chart--animated' ] ]: animation && ! prefersReducedMotion },
+						{ [ styles[ 'area-chart--animated' ] ]: animationEnabled },
 						className
 					) }
 					style={ { width, height } }
@@ -295,62 +411,16 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 											) : null }
 
 											{ ! allSeriesHidden && stacked && (
-												<AreaStack
+												<AnimatedAreaStack
 													curve={ curve }
 													offset={ stackOffset }
 													renderLine={ resolvedWithStroke }
 												>
-													{ visibleSeries.map( ( { series: seriesData, index } ) => {
-														const { color, lineStyles } = getElementStyles( {
-															data: seriesData,
-															index,
-														} );
-
-														return (
-															<AreaSeries
-																key={ seriesData?.label || index }
-																dataKey={ seriesData?.label }
-																data={ seriesData.data as DataPointDate[] }
-																{ ...accessors }
-																fill={ color }
-																fillOpacity={ resolvedFillOpacity }
-																lineProps={ {
-																	stroke: color,
-																	...lineStyles,
-																} }
-																data-testid={ `area-chart-series-${ index }` }
-															/>
-														);
-													} ) }
-												</AreaStack>
+													{ seriesWithVisibility.map( renderSeries ) }
+												</AnimatedAreaStack>
 											) }
 
-											{ ! allSeriesHidden &&
-												! stacked &&
-												visibleSeries.map( ( { series: seriesData, index } ) => {
-													const { color, lineStyles } = getElementStyles( {
-														data: seriesData,
-														index,
-													} );
-
-													return (
-														<AreaSeries
-															key={ seriesData?.label || index }
-															dataKey={ seriesData?.label }
-															data={ seriesData.data as DataPointDate[] }
-															{ ...accessors }
-															fill={ color }
-															fillOpacity={ resolvedFillOpacity }
-															renderLine={ resolvedWithStroke }
-															curve={ curve }
-															lineProps={ {
-																stroke: color,
-																...lineStyles,
-															} }
-															data-testid={ `area-chart-series-${ index }` }
-														/>
-													);
-												} ) }
+											{ ! allSeriesHidden && ! stacked && seriesWithVisibility.map( renderSeries ) }
 
 											{ withTooltips && (
 												<>
@@ -359,7 +429,7 @@ const AreaChartInternal = forwardRef< SingleChartRef, AreaChartProps >(
 														snapTooltipToDatumX
 														// Stacked mode: yAccessor returns raw value, not stacked y — snapping mispositions.
 														snapTooltipToDatumY={ ! stacked }
-														renderTooltip={ renderTooltip }
+														renderTooltip={ filteredRenderTooltip }
 														showVerticalCrosshair={ withTooltipCrosshairs?.showVertical }
 														showHorizontalCrosshair={ withTooltipCrosshairs?.showHorizontal }
 														selectedIndex={ selectedIndex }

package/src/charts/area-chart/test/area-chart.test.tsx

@@ -148,6 +148,196 @@ describe( 'AreaChart', () => {
 		} );
 	} );
 
+	describe( 'Interactive legend', () => {
+		test( 'keeps every series mounted after hiding one (stacked)', async () => {
+			const user = userEvent.setup();
+			renderWithProvider( {
+				showLegend: true,
+				chartId: 'test-interactive-stacked',
+				legend: { interactive: true },
+			} );
+
+			expect( screen.getByTestId( 'area-chart-series-0' ) ).toBeInTheDocument();
+			expect( screen.getByTestId( 'area-chart-series-1' ) ).toBeInTheDocument();
+
+			await user.click( screen.getByText( 'Series A' ) );
+
+			// Both series remain in the DOM (hidden one is zeroed via yAccessor,
+			// not unmounted) so that visx stack indices stay stable.
+			expect( screen.getByTestId( 'area-chart-series-0' ) ).toBeInTheDocument();
+			expect( screen.getByTestId( 'area-chart-series-1' ) ).toBeInTheDocument();
+		} );
+
+		test( 'keeps every series mounted after hiding one (unstacked)', async () => {
+			const user = userEvent.setup();
+			renderWithProvider( {
+				stacked: false,
+				showLegend: true,
+				chartId: 'test-interactive-unstacked',
+				legend: { interactive: true },
+			} );
+
+			await user.click( screen.getByText( 'Series A' ) );
+
+			expect( screen.getByTestId( 'area-chart-series-0' ) ).toBeInTheDocument();
+			expect( screen.getByTestId( 'area-chart-series-1' ) ).toBeInTheDocument();
+		} );
+
+		test( 'tooltip omits hidden series after toggle', async () => {
+			const user = userEvent.setup();
+			renderWithProvider( {
+				showLegend: true,
+				chartId: 'test-interactive-tooltip',
+				legend: { interactive: true },
+			} );
+
+			await user.click( screen.getByText( 'Series A' ) );
+
+			// Open a tooltip via keyboard navigation, then verify the hidden
+			// series' label is absent from the rendered tooltip rows.
+			const chart = screen.getByRole( 'grid', { name: /area chart/i } );
+			chart.focus();
+			await user.keyboard( '{ArrowRight}' );
+
+			const tooltip = await screen.findByRole( 'tooltip' );
+			expect( tooltip ).not.toHaveTextContent( 'Series A' );
+			expect( tooltip ).toHaveTextContent( 'Series B' );
+		} );
+
+		test( 'renderTooltip receives only visible series in datumByKey', async () => {
+			const user = userEvent.setup();
+			const renderTooltip = jest.fn( () => <div>tooltip</div> );
+			renderWithProvider( {
+				showLegend: true,
+				chartId: 'test-interactive-render-tooltip',
+				legend: { interactive: true },
+				renderTooltip,
+			} );
+
+			await user.click( screen.getByText( 'Series A' ) );
+			const chart = screen.getByRole( 'grid', { name: /area chart/i } );
+			chart.focus();
+			await user.keyboard( '{ArrowRight}' );
+
+			// `renderTooltip` may be called for non-keyboard events too, but the
+			// keyboard-driven call must have filtered datumByKey down to visible series.
+			const calls = renderTooltip.mock.calls as unknown as Array<
+				[
+					{
+						tooltipData?: {
+							datumByKey?: Record< string, unknown >;
+							nearestDatum?: { key: string };
+						};
+					},
+				]
+			>;
+			const keyboardCall = calls.find( ( [ params ] ) => params?.tooltipData?.datumByKey );
+			expect( keyboardCall ).toBeDefined();
+			const keys = Object.keys( keyboardCall![ 0 ].tooltipData!.datumByKey! );
+			expect( keys ).toContain( 'Series B' );
+			expect( keys ).not.toContain( 'Series A' );
+			// And `nearestDatum` should never point at a hidden series.
+			expect( keyboardCall![ 0 ].tooltipData?.nearestDatum?.key ).not.toBe( 'Series A' );
+		} );
+
+		test( 'y-axis domain stays fixed across legend toggles', async () => {
+			const user = userEvent.setup();
+			const ref = createRef< SingleChartRef >();
+			render(
+				<GlobalChartsProvider>
+					<AreaChartUnresponsive
+						{ ...defaultProps }
+						showLegend
+						chartId="test-interactive-domain"
+						legend={ { interactive: true } }
+						ref={ ref }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			const initialDomain = (
+				ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined
+			 )?.domain();
+			expect( initialDomain ).toBeDefined();
+
+			await user.click( screen.getByText( 'Series A' ) );
+
+			const afterToggleDomain = (
+				ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined
+			 )?.domain();
+			expect( afterToggleDomain ).toEqual( initialDomain );
+		} );
+
+		test( 'supports negative stacked values without clipping', () => {
+			const ref = createRef< SingleChartRef >();
+			render(
+				<GlobalChartsProvider>
+					<AreaChartUnresponsive
+						width={ 500 }
+						height={ 300 }
+						chartId="test-interactive-negative"
+						showLegend
+						legend={ { interactive: true } }
+						data={ [
+							{
+								label: 'Pos',
+								data: [
+									{ date: new Date( '2024-01-01' ), value: 10 },
+									{ date: new Date( '2024-01-02' ), value: 20 },
+								],
+							},
+							{
+								label: 'Neg',
+								data: [
+									{ date: new Date( '2024-01-01' ), value: -5 },
+									{ date: new Date( '2024-01-02' ), value: -15 },
+								],
+							},
+						] }
+						ref={ ref }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			const [ min, max ] =
+				( ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined )?.domain() ??
+				[];
+			expect( min ).toBeLessThanOrEqual( -15 );
+			expect( max ).toBeGreaterThanOrEqual( 20 );
+		} );
+
+		test( 'does not pin domain for non-default stack offsets', () => {
+			const ref = createRef< SingleChartRef >();
+			render(
+				<GlobalChartsProvider>
+					<AreaChartUnresponsive
+						{ ...defaultProps }
+						chartId="test-interactive-expand"
+						showLegend
+						legend={ { interactive: true } }
+						stackOffset="expand"
+						ref={ ref }
+					/>
+				</GlobalChartsProvider>
+			);
+
+			// `expand` normalises to [0,1]; if we accidentally pinned the raw-sum
+			// domain (e.g. [0, 35]), the top of the domain would be far above 1.
+			const [ min, max ] =
+				( ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined )?.domain() ??
+				[];
+			expect( min ).toBeGreaterThanOrEqual( 0 );
+			expect( max ).toBeLessThanOrEqual( 1.001 );
+		} );
+	} );
+
+	describe( 'Without GlobalChartsProvider', () => {
+		test( 'self-wraps in a provider when none is present', () => {
+			render( <AreaChartUnresponsive { ...defaultProps } /> );
+			expect( screen.getByRole( 'grid', { name: /area chart/i } ) ).toBeInTheDocument();
+		} );
+	} );
+
 	describe( 'Accessibility', () => {
 		test( 'chart container has expected ARIA attributes', () => {
 			renderWithProvider();
@@ -233,6 +423,19 @@ describe( 'AreaChart', () => {
 			expect( glyphs ).toHaveLength( 2 );
 		} );
 
+		test( 'renders glyphs in unstacked mode with interactive legend', async () => {
+			renderWithProvider( {
+				stacked: false,
+				showLegend: true,
+				chartId: 'test-unstacked-interactive',
+				legend: { interactive: true },
+			} );
+			await focusFirstDatum();
+
+			const glyphs = screen.getAllByTestId( /^area-chart-hover-glyph-/ );
+			expect( glyphs ).toHaveLength( 2 );
+		} );
+
 		test( 'renders glyphs only for series with a datum at the hovered x (mismatched x-domains)', async () => {
 			// Each series' data[0] is a different date. Keyboard nav fires
 			// showTooltip for every series at its own data[selectedIndex];

package/AGENTS.md

@@ -1,78 +0,0 @@
-# AGENTS.md
-
-Package-specific guidance for AI agents working in `projects/js-packages/charts`.
-
-## CRITICAL Rules
-
-- Do not invent behavior in docs. If unsure, verify implementation and stories first.
-- Do not assume wildcard exports like `./*` or `./providers/*` — they don't exist. Check the explicit exports in `package.json`.
-
-## Changelog
-
-Run from monorepo root:
-
-```bash
-jp changelog add js-packages/charts -s patch -t changed -e "Charts: <user-facing change>."
-```
-
-## Architecture Decisions (Do Not "Fix" These)
-
-- Accessibility behavior (keyboard navigation, accessible tooltips) is core chart behavior, not optional polish.
-- Charts are responsive by default — do not add external responsive wrappers that conflict with built-in sizing semantics.
-
-## WordPress UI + Theme Integration
-
-The package is migrating to WordPress UI and Theme as its defaults. When adding or changing code, follow these defaults unless the task explicitly says otherwise:
-
-- **Design tokens (WPDS).** In SCSS, use `var(--wpds-dimension-*, <fallback>)`, `var(--wpds-border-*, <fallback>)`, and `var(--wpds-typography-*, <fallback>)` instead of hardcoded px values for spacing, padding, margins, border radius, border width, font size, and font weight. Fallbacks must match the WPDS spec value for that token — do not invent fallback values.
-- **UI primitives.** Prefer `Stack` and the stable `Text` from `@wordpress/ui` over ad-hoc flexbox or raw `<span>`/`<div>` for layout and text. Do not use `__experimental*` exports from `@wordpress/components` (e.g. `__experimentalText`, `__experimentalHStack`) — use the stable `@wordpress/ui` equivalents. Exception: `__experimentalGrid` has no stable alternative yet and is acceptable to use for now.
-- **Theming.** Theming flows through `@wordpress/theme`'s `ThemeProvider` (unlocked via private APIs in Storybook; see `src/stories/chart-decorator.tsx`). Do not manually override DS tokens in stories or components to achieve theming — pass a color through `ThemeProvider` instead.
-- **Chart element styles.** Read chart element styles via `getElementStyles` from `GlobalChartsProvider`, not directly from `theme`. This is the supported path for color/style resolution across themes.
-
-## Documentation Workflow
-
-- For docs tasks agents should use the skill at `.agents/skills/charts-docs.md`.
-- For public chart/component docs, maintain the standard set when applicable: `[feature-name].stories.tsx` + `.docs.mdx` + `.api.mdx`. Some docs are intentionally guide-only and skip the full triplet.
-- Only include animation docs when the component actually supports an `animation` prop.
-
-## Conventions
-
-- Preserve backward compatibility for existing public APIs unless a breaking change is explicitly requested.
-- Prefer extending existing chart components/patterns over introducing new surface area.
-- Reuse existing hooks/providers/utilities before adding new abstractions.
-- Avoid `!important` unless there is no viable alternative and the rationale is documented.
-- Add focused behavioral tests for changed behavior; avoid speculative tests for unimplemented behavior.
-- Verify behavior/UI changes in Storybook using browser automation, not only unit tests.
-- Prefer charts-scoped PR titles (e.g. `Charts: ...`, `CHARTS-###: ...`).
-- Include test steps and visual evidence (screenshots/GIFs) in PR descriptions for UI changes.
-
-## Common Pitfalls
-
-- Claiming Rollup is used for builds (it's tsup).
-- Documenting props or behavior not present in stories and implementation.
-- Refactoring core composition/provider patterns as if they are accidental complexity.
-- Defining new chart prop interfaces that diverge from established base chart contracts (for example, not aligning with `BaseChartProps` when appropriate).
-- Using ad-hoc flexbox layouts where established layout primitives (e.g. `Stack` from `@wordpress/ui`) should be preferred.
-- Accessing colors/styles directly from `theme` rather than using `getElementStyles` from `GlobalChartsProvider`.
-- Hardcoding px values in SCSS for spacing, borders, or typography where a WPDS token (`--wpds-dimension-*`, `--wpds-border-*`, `--wpds-typography-*`) exists.
-- CSS variable fallback values that diverge from the WPDS spec for that token.
-- Using `__experimental*` exports from `@wordpress/components` (e.g. `__experimentalText`, `__experimentalHStack`) instead of the stable `@wordpress/ui` equivalents. (`__experimentalGrid` is excepted — no stable alternative exists yet.)
-- Manually overriding DS tokens in stories or components to achieve theming instead of passing a color through `@wordpress/theme`'s `ThemeProvider`.
-- Responsive wrappers that conflict with component sizing semantics (fixed-height charts, resize behavior, aspect-ratio assumptions).
-- Updating `.docs.mdx` without the corresponding `.api.mdx` when API docs are affected.
-- Not checking CSF file references in `.docs.mdx` when changing or removing stories.
-- Stories that don't visibly demonstrate documented behavior/props, or render clipped due to container sizing.
-- Breaking MDX `<Source code={\`...\` } />` rendering by malformed/flattened indentation inside template literals.
-- Tooltip styles/positioning that only work on default backgrounds or fail at chart edges.
-- Using mock/placeholder series data in production code.
-- Avoidable multi-pass data transformations in render paths when a single pass suffices.
-- CSS layout/overflow workarounds without documenting why they're needed.
-
-## Definition of Done
-
-- Behavior verified in Storybook and/or tests, not only by static checks.
-- Edits remain in package boundaries; avoid unrelated refactors.
-
-## References
-
-- Published Storybook: `https://automattic.github.io/jetpack-storybook/?path=/docs/js-packages-charts-library`