@automattic/charts 2.0.1 → 3.1.0

package/src/providers/chart-context/test/theme-override-vars-guard.test.tsx

@@ -0,0 +1,29 @@
+import { render, screen } from '@testing-library/react';
+import { GlobalChartsProvider } from '../global-charts-provider';
+
+// The stock defaultTheme's mapped fields are themselves self-referential pointers (e.g. `gridStyles.stroke: 'var(--a8c-charts-color-grid, #dbdbdb)'`), so themeOverrideVars' own self-reference guard already filters them out no matter which theme object the provider passes in. That makes "reads theme, not providerTheme" unfalsifiable against the real default theme. Mocking the default here to a plain, non-pointer value removes that overlap, so this test only passes when the provider reads the raw consumer `theme` prop rather than the merged `providerTheme`.
+jest.mock( '../themes', () => {
+	const actual = jest.requireActual( '../themes' );
+	return {
+		...actual,
+		defaultTheme: {
+			...actual.defaultTheme,
+			gridStyles: { ...actual.defaultTheme.gridStyles, stroke: '#dbdbdb' },
+		},
+	};
+} );
+
+describe( 'GlobalChartsProvider wrapper style (discriminating guard test)', () => {
+	it( 'does not emit an instance override for a role the consumer left unset, even though the merged theme carries a concrete default value', () => {
+		render(
+			<GlobalChartsProvider theme={ { tickLength: 8 } }>
+				<div>child</div>
+			</GlobalChartsProvider>
+		);
+
+		const wrapper = screen.getByTestId( 'charts-scope' );
+
+		expect( wrapper.style.getPropertyValue( '--a8c-charts-color-grid-theme' ) ).toBe( '' );
+		expect( wrapper.style.getPropertyValue( '--a8c-charts-color-grid' ) ).toBe( '' );
+	} );
+} );

package/src/providers/chart-context/test/theme-override-vars.test.ts

@@ -0,0 +1,118 @@
+import {
+	THEME_LAYERED_ROLES,
+	themeLayerVar,
+	themeOverrideVars,
+} from '../private/theme-override-vars';
+
+describe( 'themeOverrideVars', () => {
+	it( 'returns nothing for an absent theme', () => {
+		expect( themeOverrideVars( undefined ) ).toEqual( { vars: {}, roles: [] } );
+	} );
+
+	it( 'returns nothing for a theme that overrides no mapped role', () => {
+		expect( themeOverrideVars( { tickLength: 8 } ) ).toEqual( { vars: {}, roles: [] } );
+	} );
+
+	// The value is published one layer outside the role — `chart-scope.scss` declares the role as `var(<role>-theme, <catalog default>)`. Published as the role itself, a value that is invalid at computed-value time (`var(--wpds-token)` with the token unset) would make the role invalid too, and every bare `var(--a8c-charts-color-grid)` read site would paint `unset` instead of falling back to the catalog default.
+	it( 'maps a grid stroke override onto the grid role’s theme layer', () => {
+		expect( themeOverrideVars( { gridStyles: { stroke: 'red' } } ) ).toEqual( {
+			vars: { '--a8c-charts-color-grid-theme': 'red' },
+			roles: [ '--a8c-charts-color-grid' ],
+		} );
+	} );
+
+	it( 'maps every supported role at once', () => {
+		expect(
+			themeOverrideVars( {
+				backgroundColor: '#111',
+				gridStyles: { stroke: '#222' },
+				xAxisLineStyles: { stroke: '#333' },
+				xTickLineStyles: { stroke: '#444' },
+				svgLabelSmall: { fill: '#555' },
+			} )
+		).toEqual( {
+			vars: {
+				'--a8c-charts-color-background-theme': '#111',
+				'--a8c-charts-color-grid-theme': '#222',
+				'--a8c-charts-color-axis-theme': '#333',
+				'--a8c-charts-color-tick-theme': '#444',
+				'--a8c-charts-color-label-axis-theme': '#555',
+			},
+			roles: [
+				'--a8c-charts-color-background',
+				'--a8c-charts-color-grid',
+				'--a8c-charts-color-axis',
+				'--a8c-charts-color-tick',
+				'--a8c-charts-color-label-axis',
+			],
+		} );
+	} );
+
+	it( 'publishes only theme-layer variables, never a catalog role directly', () => {
+		const { vars } = themeOverrideVars( {
+			backgroundColor: '#111',
+			gridStyles: { stroke: '#222' },
+			xAxisLineStyles: { stroke: '#333' },
+			xTickLineStyles: { stroke: '#444' },
+			svgLabelSmall: { fill: '#555' },
+		} );
+
+		expect( Object.keys( vars ) ).toEqual( THEME_LAYERED_ROLES.map( themeLayerVar ) );
+	} );
+
+	// The narrow role is the whole point: the broad `--a8c-charts-color-label` is also read by legend labels, heatmap cell values, funnel labels and the line-chart tooltip, none of which `svgLabelSmall.fill` moved before the role was published as a custom property.
+	it( 'publishes an svg label override as the narrow axis-label role, not the broad one', () => {
+		expect( themeOverrideVars( { svgLabelSmall: { fill: 'red' } } ) ).toEqual( {
+			vars: { '--a8c-charts-color-label-axis-theme': 'red' },
+			roles: [ '--a8c-charts-color-label-axis' ],
+		} );
+	} );
+
+	it( 'ignores a value that is itself a pointer at the role it would override', () => {
+		expect(
+			themeOverrideVars( { gridStyles: { stroke: 'var(--a8c-charts-color-grid, #dbdbdb)' } } ).vars
+		).toEqual( {} );
+	} );
+
+	// A skipped value still reports its role, so `withCatalogPointers` restores the theme field. Without that, CSS would paint the catalog default while visx painted the consumer's literal — the divergence this whole mechanism exists to remove.
+	it( 'still reports the role of a value it refuses to publish', () => {
+		expect(
+			themeOverrideVars( {
+				gridStyles: { stroke: 'var(--brand, var(--a8c-charts-color-grid, red))' },
+			} )
+		).toEqual( { vars: {}, roles: [ '--a8c-charts-color-grid' ] } );
+	} );
+
+	// `var()` allows whitespace after the opening paren. The role reads its theme layer, so a value naming the role closes a cycle through the catalog entry: CSS marks every custom property in a cycle invalid at computed-value time, and the role's own fallback is not used, so the token resolves to nothing at all.
+	it( 'ignores a self-referential pointer padded with whitespace', () => {
+		expect(
+			themeOverrideVars( { gridStyles: { stroke: 'var( --a8c-charts-color-grid, #dbdbdb )' } } )
+				.vars
+		).toEqual( {} );
+	} );
+
+	it( 'still emits a value that merely mentions a different role', () => {
+		expect(
+			themeOverrideVars( { gridStyles: { stroke: 'var( --a8c-charts-color-axis, #dbdbdb )' } } )
+				.vars
+		).toEqual( {
+			'--a8c-charts-color-grid-theme': 'var( --a8c-charts-color-axis, #dbdbdb )',
+		} );
+	} );
+
+	// A mapped role can be a strict prefix of another custom property — a catalog role such as `--a8c-charts-color-label` of `--a8c-charts-color-label-axis`, the role's own theme layer, or a name the consumer defined themselves. A prefix match would read a legitimate cross-property pointer as a self-reference and silently drop the override, so the role must be followed by something that cannot continue an identifier.
+	it( 'does not mistake a longer property name for the role it guards', () => {
+		expect(
+			themeOverrideVars( {
+				xAxisLineStyles: { stroke: 'var(--a8c-charts-color-axis-emphasis, #000)' },
+			} ).vars
+		).toEqual( { '--a8c-charts-color-axis-theme': 'var(--a8c-charts-color-axis-emphasis, #000)' } );
+	} );
+
+	// `resolveCssVariable` also accepts a bare custom-property name with no `var()` wrapper, so `theme={ { gridStyles: { stroke: '--a8c-charts-color-grid' } } }` is legal input. It forms no cycle, so it must be caught explicitly or it survives as a literal string value and drops silently at the use site.
+	it( 'ignores a self-referential pointer written as a bare custom-property name', () => {
+		expect(
+			themeOverrideVars( { gridStyles: { stroke: '--a8c-charts-color-grid' } } ).vars
+		).toEqual( {} );
+	} );
+} );

package/src/providers/chart-context/test/use-default-hidden-series-paint.test.tsx

@@ -0,0 +1,56 @@
+import { screen } from '@testing-library/react';
+import { flushSync } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { GlobalChartsProvider } from '../global-charts-provider';
+import { useDefaultHiddenSeries } from '../hooks/use-default-hidden-series';
+import { useGlobalChartsContext } from '../hooks/use-global-charts-context';
+import type { Root } from 'react-dom/client';
+
+describe( 'useDefaultHiddenSeries paint timing', () => {
+	let host: HTMLDivElement;
+	let root: Root;
+	let previousActEnvironment: boolean | undefined;
+
+	beforeEach( () => {
+		previousActEnvironment = globalThis.IS_REACT_ACT_ENVIRONMENT;
+		globalThis.IS_REACT_ACT_ENVIRONMENT = false;
+		host = document.createElement( 'div' );
+		document.body.appendChild( host );
+		root = createRoot( host );
+	} );
+
+	afterEach( () => {
+		flushSync( () => root.unmount() );
+		host.remove();
+		globalThis.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+	} );
+
+	it( 'updates provider visibility before the first paint', () => {
+		const Chart = () => {
+			useDefaultHiddenSeries( 'chart', [ 'Visitors' ] );
+			return null;
+		};
+
+		const Visibility = () => {
+			const { isSeriesVisible } = useGlobalChartsContext();
+			return (
+				<span data-testid="series-visibility">
+					{ isSeriesVisible( 'chart', 'Visitors' ) ? 'visible' : 'hidden' }
+				</span>
+			);
+		};
+
+		// flushSync lets us inspect the layout-effect result before a later passive
+		// effect could seed the provider.
+		flushSync( () => {
+			root.render(
+				<GlobalChartsProvider>
+					<Chart />
+					<Visibility />
+				</GlobalChartsProvider>
+			);
+		} );
+
+		expect( screen.getByTestId( 'series-visibility' ) ).toHaveTextContent( 'hidden' );
+	} );
+} );

package/src/providers/chart-context/test/use-default-hidden-series.ssr.test.tsx

@@ -0,0 +1,39 @@
+/** @jest-environment node */
+
+import { renderToStaticMarkup } from 'react-dom/server';
+import { useDefaultHiddenSeries } from '../hooks/use-default-hidden-series';
+
+const mockGetHiddenSeries = jest.fn( () => new Set( [ 'Provider hidden' ] ) );
+const mockSeedChartHiddenSeries = jest.fn();
+const mockHasSeededChart = jest.fn( () => false );
+
+jest.mock( '../hooks/use-global-charts-context', () => ( {
+	useGlobalChartsContext: () => ( {
+		getHiddenSeries: mockGetHiddenSeries,
+		seedChartHiddenSeries: mockSeedChartHiddenSeries,
+		hasSeededChart: mockHasSeededChart,
+	} ),
+} ) );
+
+describe( 'useDefaultHiddenSeries SSR', () => {
+	it( 'applies defaults to the server-rendered output before effects run', () => {
+		const Chart = () => {
+			const hiddenSeries = useDefaultHiddenSeries( 'chart', [ 'Visitors' ] );
+
+			return (
+				<>
+					{ [ 'Visitors', 'Views' ].map( label =>
+						! hiddenSeries.has( label ) ? <span key={ label }>{ label }</span> : null
+					) }
+				</>
+			);
+		};
+
+		const view = renderToStaticMarkup( <Chart /> );
+
+		expect( view ).not.toContain( 'Visitors' );
+		expect( view ).toContain( 'Views' );
+		expect( mockGetHiddenSeries ).not.toHaveBeenCalled();
+		expect( mockSeedChartHiddenSeries ).not.toHaveBeenCalled();
+	} );
+} );

package/src/providers/chart-context/test/use-default-hidden-series.test.tsx

@@ -0,0 +1,222 @@
+import { render, act } from '@testing-library/react';
+import { GlobalChartsProvider } from '../global-charts-provider';
+import { useDefaultHiddenSeries } from '../hooks/use-default-hidden-series';
+import { useGlobalChartsContext } from '../hooks/use-global-charts-context';
+import type { GlobalChartsContextValue } from '../types';
+
+describe( 'useDefaultHiddenSeries', () => {
+	let contextValue: GlobalChartsContextValue;
+	let resolvedHiddenSeries: Set< string >;
+
+	const Grab = () => {
+		contextValue = useGlobalChartsContext();
+		return null;
+	};
+
+	const Chart = ( { defaults, chartId = 'chart' }: { defaults?: string[]; chartId?: string } ) => {
+		resolvedHiddenSeries = useDefaultHiddenSeries( chartId, defaults );
+		return null;
+	};
+
+	it( 'hides the named series at mount', () => {
+		render(
+			<GlobalChartsProvider>
+				<Grab />
+				<Chart defaults={ [ 'Visitors' ] } />
+			</GlobalChartsProvider>
+		);
+
+		expect( contextValue.isSeriesVisible( 'chart', 'Visitors' ) ).toBe( false );
+		expect( contextValue.isSeriesVisible( 'chart', 'Views' ) ).toBe( true );
+	} );
+
+	it( 'writes nothing when no defaults are given', () => {
+		render(
+			<GlobalChartsProvider>
+				<Grab />
+				<Chart />
+			</GlobalChartsProvider>
+		);
+
+		expect( contextValue.getHiddenSeries( 'chart' ) ).toEqual( new Set() );
+	} );
+
+	it( 'reflects provider visibility changes after mount', () => {
+		render(
+			<GlobalChartsProvider>
+				<Grab />
+				<Chart />
+			</GlobalChartsProvider>
+		);
+
+		expect( resolvedHiddenSeries.has( 'Visitors' ) ).toBe( false );
+
+		act( () => {
+			contextValue.setSeriesVisibility( 'chart', 'Visitors', false );
+		} );
+
+		expect( resolvedHiddenSeries.has( 'Visitors' ) ).toBe( true );
+	} );
+
+	it( 'seeds the first defined value and ignores later values for the same chart ID', () => {
+		const Harness = ( { defaults }: { defaults?: string[] } ) => (
+			<GlobalChartsProvider>
+				<Grab />
+				<Chart defaults={ defaults } />
+			</GlobalChartsProvider>
+		);
+
+		const { rerender } = render( <Harness /> );
+
+		rerender( <Harness defaults={ [ 'Visitors' ] } /> );
+		expect( contextValue.getHiddenSeries( 'chart' ) ).toEqual( new Set( [ 'Visitors' ] ) );
+
+		rerender( <Harness defaults={ [ 'Views' ] } /> );
+		expect( contextValue.getHiddenSeries( 'chart' ) ).toEqual( new Set( [ 'Visitors' ] ) );
+	} );
+
+	it( 'treats an empty array as a defined default', () => {
+		const Harness = ( { defaults }: { defaults: string[] } ) => (
+			<GlobalChartsProvider>
+				<Grab />
+				<Chart defaults={ defaults } />
+			</GlobalChartsProvider>
+		);
+
+		const { rerender } = render( <Harness defaults={ [] } /> );
+
+		rerender( <Harness defaults={ [ 'Visitors' ] } /> );
+
+		expect( contextValue.getHiddenSeries( 'chart' ) ).toEqual( new Set() );
+	} );
+
+	it( 'does not re-hide a series the user revealed', () => {
+		const Harness = () => (
+			<GlobalChartsProvider>
+				<Grab />
+				<Chart defaults={ [ 'Visitors' ] } />
+			</GlobalChartsProvider>
+		);
+
+		const { rerender } = render( <Harness /> );
+
+		act( () => {
+			contextValue.setSeriesVisibility( 'chart', 'Visitors', true );
+		} );
+
+		rerender( <Harness /> );
+
+		expect( contextValue.isSeriesVisible( 'chart', 'Visitors' ) ).toBe( true );
+	} );
+
+	it( "keeps the reader's visibility choices across a remount", () => {
+		// The provider stays mounted; only the chart unmounts and comes back — a
+		// chart-type switch, a tab round-trip, a resize flipping tabs into a
+		// dropdown. None of those read as a new chart, so none may re-seed.
+		const Harness = ( { mounted }: { mounted: boolean } ) => (
+			<GlobalChartsProvider>
+				<Grab />
+				{ mounted && <Chart defaults={ [ 'Visitors' ] } /> }
+			</GlobalChartsProvider>
+		);
+
+		const { rerender } = render( <Harness mounted /> );
+
+		act( () => {
+			contextValue.setSeriesVisibility( 'chart', 'Views', false );
+		} );
+		expect( contextValue.isSeriesVisible( 'chart', 'Views' ) ).toBe( false );
+
+		rerender( <Harness mounted={ false } /> );
+		rerender( <Harness mounted /> );
+
+		expect( contextValue.isSeriesVisible( 'chart', 'Visitors' ) ).toBe( false );
+		expect( contextValue.isSeriesVisible( 'chart', 'Views' ) ).toBe( false );
+	} );
+
+	it( 'leaves a fully revealed chart revealed after a remount', () => {
+		// Revealing the last hidden series empties the chart's hidden set, and the
+		// provider drops the entry with it. The seeded record has to survive that,
+		// or the defaults come back the next time the chart mounts.
+		const Harness = ( { mounted }: { mounted: boolean } ) => (
+			<GlobalChartsProvider>
+				<Grab />
+				{ mounted && <Chart defaults={ [ 'Visitors' ] } /> }
+			</GlobalChartsProvider>
+		);
+
+		const { rerender } = render( <Harness mounted /> );
+
+		act( () => {
+			contextValue.setSeriesVisibility( 'chart', 'Visitors', true );
+		} );
+		expect( contextValue.getHiddenSeries( 'chart' ) ).toEqual( new Set() );
+
+		rerender( <Harness mounted={ false } /> );
+		rerender( <Harness mounted /> );
+
+		expect( contextValue.isSeriesVisible( 'chart', 'Visitors' ) ).toBe( true );
+	} );
+
+	it( 'retains provider visibility when remounted without defaults', () => {
+		const Harness = ( { defaults, mounted }: { defaults?: string[]; mounted: boolean } ) => (
+			<GlobalChartsProvider>
+				<Grab />
+				{ mounted && <Chart defaults={ defaults } /> }
+			</GlobalChartsProvider>
+		);
+
+		const { rerender } = render( <Harness defaults={ [ 'Visitors' ] } mounted /> );
+		expect( contextValue.isSeriesVisible( 'chart', 'Visitors' ) ).toBe( false );
+
+		rerender( <Harness mounted={ false } /> );
+		rerender( <Harness mounted /> );
+
+		expect( contextValue.isSeriesVisible( 'chart', 'Visitors' ) ).toBe( false );
+	} );
+
+	it( 'keeps the same set across renders until visibility changes', () => {
+		// Charts memoize their rendered series off this set. A fresh identity per
+		// render invalidates those memos, which re-runs the accessible tooltip's
+		// effect and closes a tooltip the user is still navigating with.
+		const Harness = () => (
+			<GlobalChartsProvider>
+				<Grab />
+				<Chart defaults={ [ 'Visitors' ] } />
+			</GlobalChartsProvider>
+		);
+
+		const { rerender } = render( <Harness /> );
+		const seeded = resolvedHiddenSeries;
+
+		rerender( <Harness /> );
+		expect( resolvedHiddenSeries ).toBe( seeded );
+
+		act( () => {
+			contextValue.setSeriesVisibility( 'chart', 'Views', false );
+		} );
+		expect( resolvedHiddenSeries ).not.toBe( seeded );
+	} );
+
+	it( 're-seeds the defaults when chartId changes mid-mount', () => {
+		// Same mount, only the chartId prop changes (e.g. <LineChart chartId={ metric } ... />
+		// with `metric` going 'views' -> 'clicks'), so the component never unmounts.
+		const Harness = ( { chartId }: { chartId: string } ) => (
+			<GlobalChartsProvider>
+				<Grab />
+				<Chart chartId={ chartId } defaults={ [ 'Visitors' ] } />
+			</GlobalChartsProvider>
+		);
+
+		const { rerender } = render( <Harness chartId="views" /> );
+
+		expect( contextValue.isSeriesVisible( 'views', 'Visitors' ) ).toBe( false );
+
+		rerender( <Harness chartId="clicks" /> );
+
+		// The new chart id gets the same declared defaults seeded...
+		expect( contextValue.isSeriesVisible( 'clicks', 'Visitors' ) ).toBe( false );
+		// ...and the old id's hidden set is left as it was, not silently cleared.
+		expect( contextValue.isSeriesVisible( 'views', 'Visitors' ) ).toBe( false );
+	} );
+} );

package/src/providers/chart-context/test/with-catalog-pointers.test.ts

@@ -0,0 +1,47 @@
+import { mergeThemes } from '../../../utils';
+import { withCatalogPointers } from '../private/with-catalog-pointers';
+import { defaultTheme } from '../themes';
+import type { ChartTheme } from '../../../types';
+
+describe( 'withCatalogPointers', () => {
+	it( 'restores every overridden role to its catalog pointer, without mutating the input theme', () => {
+		const merged = mergeThemes( defaultTheme, {
+			backgroundColor: '#111',
+			gridStyles: { stroke: '#222' },
+			xAxisLineStyles: { stroke: '#333' },
+			xTickLineStyles: { stroke: '#444' },
+			svgLabelSmall: { fill: '#555' },
+		} as Partial< ChartTheme > );
+
+		const result = withCatalogPointers( merged, [
+			'--a8c-charts-color-background',
+			'--a8c-charts-color-grid',
+			'--a8c-charts-color-axis',
+			'--a8c-charts-color-tick',
+			'--a8c-charts-color-label-axis',
+		] );
+
+		expect( result.backgroundColor ).toBe( defaultTheme.backgroundColor );
+		expect( result.gridStyles.stroke ).toBe( defaultTheme.gridStyles.stroke );
+		expect( result.xAxisLineStyles.stroke ).toBe( defaultTheme.xAxisLineStyles.stroke );
+		expect( result.xTickLineStyles.stroke ).toBe( defaultTheme.xTickLineStyles.stroke );
+		expect( result.svgLabelSmall.fill ).toBe( defaultTheme.svgLabelSmall.fill );
+
+		expect( merged.backgroundColor ).toBe( '#111' );
+		expect( merged.gridStyles.stroke ).toBe( '#222' );
+	} );
+
+	it( 'leaves fields alone when no role was overridden', () => {
+		const merged = mergeThemes( defaultTheme, {
+			tickLength: 8,
+			leaderboardChart: { deltaColors: [ 'red', 'grey', 'green' ] },
+		} as Partial< ChartTheme > );
+
+		const result = withCatalogPointers( merged, [] );
+
+		expect( result.tickLength ).toBe( 8 );
+		expect( result.gridStyles.stroke ).toBe( defaultTheme.gridStyles.stroke );
+		// Not a mapped role, so its literal survives even when other roles are being restored.
+		expect( result.leaderboardChart.deltaColors ).toEqual( [ 'red', 'grey', 'green' ] );
+	} );
+} );

package/src/providers/chart-context/themes.ts

@@ -4,31 +4,29 @@ import type { CompleteChartTheme } from '../../types';
  * Default theme configuration
  */
 const defaultTheme: CompleteChartTheme = {
-	backgroundColor:
-		'var(--a8c-charts-color-background, var(--wpds-color-background-surface-neutral-strong, #fff))',
+	backgroundColor: 'var(--a8c-charts-color-background, #fff)',
 	labelBackgroundColor: 'transparent', // label background color (transparent by default)
-	// White label text sits on top of arbitrary series colors, so it has no WPDS
-	// content-foreground equivalent; the role carries the hardcoded value as its fallback.
+	// White label text sits on top of arbitrary series colors, so it has no WPDS content-foreground equivalent. Every other colour here is a bare pointer at the catalog emitted by `chart-scope.scss`; the terminal literal is the last resort for the SSR and jsdom paths, where getComputedStyle resolves nothing.
 	labelTextColor: 'var(--a8c-charts-color-label-on-fill, #FFFFFF)',
 	colors: [ '#98C8DF', '#006DAB', '#A6DC80', '#1F9828', '#FF8C8F' ],
 	gridStyles: {
-		stroke: 'var(--a8c-charts-color-grid, var(--wpds-color-stroke-surface-neutral, #dbdbdb))',
+		stroke: 'var(--a8c-charts-color-grid, #dbdbdb)',
 		strokeWidth: 1,
 	},
 	tickLength: 4,
 	gridColor: '',
 	gridColorDark: '',
 	xTickLineStyles: {
-		stroke: 'var(--a8c-charts-color-tick, var(--wpds-color-stroke-surface-neutral, #dbdbdb))',
+		stroke: 'var(--a8c-charts-color-tick, #dbdbdb)',
 		strokeWidth: 1,
 	},
 	xAxisLineStyles: {
-		stroke: 'var(--a8c-charts-color-axis, var(--wpds-color-stroke-surface-neutral, #dbdbdb))',
+		stroke: 'var(--a8c-charts-color-axis, #dbdbdb)',
 		strokeWidth: 1,
 	},
 	legend: {
 		labelStyles: {
-			color: 'var(--a8c-charts-color-label, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
+			color: 'var(--a8c-charts-color-label, #1e1e1e)',
 		},
 		containerStyles: {},
 		shapeStyles: [],
@@ -41,30 +39,26 @@ const defaultTheme: CompleteChartTheme = {
 	// elements for axis labels and ticks. Setting `inherit` lets SVG text
 	// pick up the host application's font-family via normal CSS inheritance.
 	svgLabelSmall: {
-		fill: 'var(--a8c-charts-color-label, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
+		fill: 'var(--a8c-charts-color-label-axis, #1e1e1e)',
 		fontFamily: 'inherit',
 	},
 	svgLabelBig: { fontFamily: 'inherit' },
 	annotationStyles: {
 		label: {
-			anchorLineStroke:
-				'var(--a8c-charts-color-annotation, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
-			backgroundFill:
-				'var(--a8c-charts-color-background, var(--wpds-color-background-surface-neutral-strong, #fff))',
+			anchorLineStroke: 'var(--a8c-charts-color-annotation, #1e1e1e)',
+			backgroundFill: 'var(--a8c-charts-color-surface, #fff)',
 		},
 		connector: {
-			stroke:
-				'var(--a8c-charts-color-annotation, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
+			stroke: 'var(--a8c-charts-color-annotation, #1e1e1e)',
 		},
 		circleSubject: {
 			stroke: 'transparent',
-			fill: 'var(--a8c-charts-color-annotation, var(--wpds-color-foreground-content-neutral, #1e1e1e))',
+			fill: 'var(--a8c-charts-color-annotation, #1e1e1e)',
 			radius: 5,
 		},
 	},
 	geoChart: {
-		featureFillColor:
-			'var(--a8c-charts-color-surface-secondary, var(--wpds-color-background-surface-neutral-weak, #f4f4f4))',
+		featureFillColor: 'var(--a8c-charts-color-surface-secondary, #f4f4f4)',
 	},
 	leaderboardChart: {
 		rowGap: 12,
@@ -72,18 +66,15 @@ const defaultTheme: CompleteChartTheme = {
 		labelSpacing: 'xs',
 		// [negative, neutral, positive]
 		deltaColors: [
-			'var(--a8c-charts-color-trend-down, var(--wpds-color-foreground-content-error-weak, #cc1818))',
-			'var(--a8c-charts-color-trend-neutral, var(--wpds-color-foreground-content-neutral-weak, #707070))',
-			'var(--a8c-charts-color-trend-up, var(--wpds-color-foreground-content-success-weak, #008030))',
+			'var(--a8c-charts-color-trend-down, #cc1818)',
+			'var(--a8c-charts-color-trend-neutral, #707070)',
+			'var(--a8c-charts-color-trend-up, #008030)',
 		],
 	},
 	conversionFunnelChart: {
-		backgroundColor:
-			'var(--a8c-charts-color-surface-secondary, var(--wpds-color-background-surface-neutral-weak, #f4f4f4))',
-		positiveChangeColor:
-			'var(--a8c-charts-color-trend-up, var(--wpds-color-foreground-content-success-weak, #008030))',
-		negativeChangeColor:
-			'var(--a8c-charts-color-trend-down, var(--wpds-color-foreground-content-error-weak, #cc1818))',
+		backgroundColor: 'var(--a8c-charts-color-surface-secondary, #f4f4f4)',
+		positiveChangeColor: 'var(--a8c-charts-color-trend-up, #008030)',
+		negativeChangeColor: 'var(--a8c-charts-color-trend-down, #cc1818)',
 	},
 	lineChart: {
 		lineStyles: {

package/src/providers/chart-context/types.ts

@@ -38,11 +38,14 @@ export interface GlobalChartsContextValue {
 	getChartData: ( id: string ) => ChartRegistration | undefined;
 	theme: CompleteChartTheme;
 	getElementStyles: ( params: GetElementStylesParams ) => ElementStyles;
-	// Resolve a theme color or CSS variable to a hex string in the provider's scope.
-	// Resolves at call time so it tracks ambient theme changes (e.g. a light/dark switch).
-	resolveThemeColor: ( value: string ) => string;
-	// Series visibility management for interactive legends
+	// Series visibility management shared by charts, legends, and programmatic controls.
 	toggleSeriesVisibility: ( chartId: string, seriesLabel: string ) => void;
+	setSeriesVisibility: ( chartId: string, seriesLabel: string, visible: boolean ) => void;
+	setChartHiddenSeries: ( chartId: string, seriesLabels: readonly string[] ) => void;
+	/** Applies a chart's defaults once. A no-op for a chart that has already been seeded. */
+	seedChartHiddenSeries: ( chartId: string, seriesLabels: readonly string[] ) => void;
+	/** Whether this chart's defaults have already been seeded, in this or an earlier mount. */
+	hasSeededChart: ( chartId: string ) => boolean;
 	isSeriesVisible: ( chartId: string, seriesLabel: string ) => boolean;
 	getHiddenSeries: ( chartId: string ) => Set< string >;
 	isColorPaletteResolved: boolean;

package/src/providers/chart-scope/chart-scope-context.ts

@@ -0,0 +1,8 @@
+import { createContext } from 'react';
+
+/**
+ * The nearest chart element, published so JS token resolution reads the same CSS cascade that paints the chart's own colours.
+ *
+ * All JS token resolution reads this element rather than `document.documentElement`, so a `getComputedStyle` call sees the same `--a8c-charts-*` values — including any override set inside the provider tree — that a CSS-painted sibling element does.
+ */
+export const ChartScopeContext = createContext< HTMLElement | null >( null );

package/src/providers/chart-scope/index.ts

@@ -0,0 +1,3 @@
+export { ChartScopeContext } from './chart-scope-context';
+export { useChartScopeElement } from './use-chart-scope-element';
+export { useStandaloneScopeClass } from './use-standalone-scope-class';