@automattic/charts 2.0.0 → 3.0.0

package/src/hooks/test/use-chart-margin.test.tsx

@@ -184,4 +184,64 @@ describe( 'useChartMargin', () => {
 		// This is larger than the 20px default bottom margin, so it should be used.
 		expect( result.current.bottom ).toBe( 25 );
 	} );
+
+	describe( 'horizontal y ticks', () => {
+		const horizontalOptions = ( tickFormat: ( value: string | number ) => string ) => ( {
+			...optionsBase,
+			axis: {
+				...optionsBase.axis,
+				y: { ...optionsBase.axis.y, orientation: Orientation.left, tickFormat },
+			},
+		} );
+
+		it( 'measures dated ticks by formatting the raw timestamps once', () => {
+			const formatHour = ( timestamp: string | number ) =>
+				new Date( timestamp ).toLocaleTimeString( undefined, { hour: 'numeric', hour12: true } );
+			const hourlyData = [
+				{
+					label: 'Series 1',
+					data: [
+						{ date: new Date( 2024, 0, 1, 6 ), value: 10 },
+						{ date: new Date( 2024, 0, 1, 7 ), value: 20 },
+					],
+				},
+			];
+
+			renderHook( () =>
+				useChartMargin( 300, horizontalOptions( formatHour ), hourlyData, baseTheme, true )
+			);
+
+			const [ ticks, measureFormatter ] = mockGetLongestTickWidth.mock.calls[ 0 ];
+			// Raw timestamps, so the formatter runs exactly once — formatting here
+			// and again while measuring would date-parse "6 AM" to "Invalid Date".
+			expect( ticks ).toEqual( [
+				new Date( 2024, 0, 1, 6 ).getTime(),
+				new Date( 2024, 0, 1, 7 ).getTime(),
+			] );
+			expect( measureFormatter ).toBe( formatHour );
+		} );
+
+		it( "measures labelled ticks through the caller's formatter", () => {
+			const withSuffix = ( label: string | number ) => `${ label } (total)`;
+			const labelledData = [
+				{
+					label: 'Series 1',
+					data: [
+						{ label: 'Mon', value: 10 },
+						{ label: 'Tuesday', value: 20 },
+					],
+				},
+			];
+
+			renderHook( () =>
+				useChartMargin( 300, horizontalOptions( withSuffix ), labelledData, baseTheme, true )
+			);
+
+			const [ ticks, measureFormatter ] = mockGetLongestTickWidth.mock.calls[ 0 ];
+			// A formatter that lengthens labels has to reach the measurement, or the
+			// margin under-measures and the widest label clips at the SVG edge.
+			expect( ticks ).toEqual( [ 'Mon', 'Tuesday' ] );
+			expect( measureFormatter ).toBe( withSuffix );
+		} );
+	} );
 } );

package/src/hooks/test/use-xychart-theme-provider-override.test.tsx

@@ -0,0 +1,28 @@
+import { renderHook } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../providers/chart-context/global-charts-provider';
+import { ChartScopeContext } from '../../providers/chart-scope';
+import { useXYChartTheme } from '../use-xychart-theme';
+import type { ReactNode } from 'react';
+
+// A `theme` prop override reaches CSS-painted elements through the inline `--a8c-charts-*` var GlobalChartsProvider writes on its wrapper, and reaches visx (SVG presentation attributes) through `providerTheme`. Before the fix, `providerTheme` carried the override's literal directly, so an element-level `--a8c-charts-color-grid` override set inside the provider tree had no effect on the JS-resolved value — the two paths could disagree. After the fix, `providerTheme` carries the catalog pointer for an overridden role, so both paths resolve through the same CSS cascade and the nearer element wins.
+describe( 'useXYChartTheme resolves a theme prop override through the CSS cascade', () => {
+	it( "an element override set inside the provider tree beats the provider's theme prop literal", () => {
+		const nestedOverride = document.createElement( 'div' );
+		nestedOverride.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
+		document.body.appendChild( nestedOverride );
+
+		const wrapper = ( { children }: { children: ReactNode } ) => (
+			<GlobalChartsProvider theme={ { gridStyles: { stroke: 'rgb(255,0,0)' } } }>
+				<ChartScopeContext.Provider value={ nestedOverride }>
+					{ children }
+				</ChartScopeContext.Provider>
+			</GlobalChartsProvider>
+		);
+
+		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
+
+		expect( result.current.gridStyles.stroke ).toBe( '#00ff00' );
+
+		document.body.removeChild( nestedOverride );
+	} );
+} );

package/src/hooks/test/use-xychart-theme-style-reads.test.tsx

@@ -0,0 +1,89 @@
+import { renderHook } from '@testing-library/react';
+import { ChartScopeContext } from '../../providers/chart-scope';
+import { useXYChartTheme } from '../use-xychart-theme';
+import type { SeriesData } from '../../types';
+import type { ReactNode } from 'react';
+
+// The theme resolves five catalog roles — background, grid, axis, tick and axis label. Each `getComputedStyle` call can force the browser to flush pending style, and this memo re-runs only when the scope element attaches or a series colour changes, so a dashboard mounting N charts pays the count below N times over.
+const STABLE_DATA: SeriesData[] = [];
+
+describe( 'useXYChartTheme style reads', () => {
+	let scope: HTMLElement;
+	let getComputedStyleSpy: jest.SpyInstance;
+
+	beforeEach( () => {
+		scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
+		document.body.appendChild( scope );
+		getComputedStyleSpy = jest.spyOn( window, 'getComputedStyle' );
+	} );
+
+	afterEach( () => {
+		getComputedStyleSpy.mockRestore();
+		scope.remove();
+	} );
+
+	const renderWithScope = ( data: SeriesData[] = STABLE_DATA ) =>
+		renderHook( ( { series }: { series: SeriesData[] } ) => useXYChartTheme( series ), {
+			initialProps: { series: data },
+			wrapper: ( { children }: { children: ReactNode } ) => (
+				<ChartScopeContext.Provider value={ scope }>{ children }</ChartScopeContext.Provider>
+			),
+		} );
+
+	it( 'reads every role from one computed-style snapshot, not one per role', () => {
+		scope.style.setProperty( '--a8c-charts-color-background', '#111111' );
+		scope.style.setProperty( '--a8c-charts-color-axis', '#222222' );
+
+		const { result } = renderWithScope();
+
+		expect( getComputedStyleSpy ).toHaveBeenCalledTimes( 1 );
+		expect( result.current.backgroundColor ).toBe( '#111111' );
+		expect( result.current.gridStyles.stroke ).toBe( '#00ff00' );
+		expect( result.current.axisStyles.x.bottom.axisLine.stroke ).toBe( '#222222' );
+	} );
+
+	it( 'does not re-read styles when the hook re-renders with the same inputs', () => {
+		const { rerender } = renderWithScope();
+
+		getComputedStyleSpy.mockClear();
+		rerender( { series: STABLE_DATA } );
+
+		expect( getComputedStyleSpy ).not.toHaveBeenCalled();
+	} );
+
+	// A caller passing an inline array literal — `<LineChart data={ [ … ] } />` — hands the hook a new array identity on every render. The memo keys on the series strokes instead, so the theme is not rebuilt and no style is read. Keyed on `data` this cost one query per render, and before the roles shared a snapshot it cost five.
+	it( 'does not rebuild when the caller passes a fresh data array of the same strokes', () => {
+		const { rerender } = renderWithScope( [] );
+
+		getComputedStyleSpy.mockClear();
+		rerender( { series: [] } );
+
+		expect( getComputedStyleSpy ).not.toHaveBeenCalled();
+	} );
+
+	it( 'rebuilds when a series stroke actually changes', () => {
+		const withStroke = ( stroke: string ) =>
+			[ { label: 'A', options: { stroke }, data: [] } ] as unknown as SeriesData[];
+		const { result, rerender } = renderWithScope( withStroke( 'rgba(0, 0, 0, 0.5)' ) );
+
+		getComputedStyleSpy.mockClear();
+		rerender( { series: withStroke( 'rebeccapurple' ) } );
+
+		expect( getComputedStyleSpy ).toHaveBeenCalledTimes( 1 );
+		expect( result.current.colors[ 0 ] ).toBe( 'rebeccapurple' );
+	} );
+
+	// The memo key serialises the strokes rather than joining them, so a colour containing a comma or a space survives the round-trip intact.
+	it( 'keeps a stroke that contains separators intact', () => {
+		const { result } = renderWithScope( [
+			{ label: 'A', options: { stroke: 'rgba(0, 0, 0, 0.5)' }, data: [] },
+			{ label: 'B', options: { stroke: 'var(--brand, #fff)' }, data: [] },
+		] as unknown as SeriesData[] );
+
+		expect( result.current.colors.slice( 0, 2 ) ).toEqual( [
+			'rgba(0, 0, 0, 0.5)',
+			'var(--brand, #fff)',
+		] );
+	} );
+} );

package/src/hooks/test/use-xychart-theme.test.tsx

@@ -0,0 +1,25 @@
+import { renderHook } from '@testing-library/react';
+import { ChartScopeContext } from '../../providers/chart-scope';
+import { useXYChartTheme } from '../use-xychart-theme';
+import type { ReactNode } from 'react';
+
+describe( 'useXYChartTheme', () => {
+	it( 'resolves grid colour against the scope element, not the document root', () => {
+		document.documentElement.style.setProperty( '--a8c-charts-color-grid', '#ff0000' );
+
+		const scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
+		document.body.appendChild( scope );
+
+		const wrapper = ( { children }: { children: ReactNode } ) => (
+			<ChartScopeContext.Provider value={ scope }>{ children }</ChartScopeContext.Provider>
+		);
+
+		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
+
+		expect( result.current.gridStyles.stroke ).toBe( '#00ff00' );
+
+		document.documentElement.style.removeProperty( '--a8c-charts-color-grid' );
+		document.body.removeChild( scope );
+	} );
+} );

package/src/hooks/use-chart-margin.tsx

@@ -75,10 +75,9 @@ export const useChartMargin = (
 		const allDataPoints = data.flatMap( series => series.data as DataPointDate[] );
 
 		if ( horizontal ) {
-			// When horizontal, y ticks renders fixed tick labels.
-			return allDataPoints.map(
-				d => d.label || options.axis?.y?.tickFormat( d.date.getTime(), 0, [] )
-			);
+			// When horizontal, y ticks render the category values; leave them raw so
+			// the axis tick formatter is applied exactly once, when measuring below.
+			return allDataPoints.map( d => d.label || d.date?.getTime() );
 		}
 
 		if ( options.axis?.y?.tickValues?.length ) {

package/src/hooks/use-xychart-theme.ts

@@ -1,22 +1,30 @@
 import { buildChartTheme } from '@visx/xychart';
 import { useMemo } from 'react';
 import { useGlobalChartsTheme } from '../providers';
-import { resolveCssVariable } from '../utils';
+import { useChartScopeElement } from '../providers/chart-scope';
+import { createCssVariableResolver } from '../utils';
 import type { SeriesData } from '../types';
 
-// visx applies grid, axis, and tick-label colors as SVG presentation attributes,
-// where CSS var() cannot resolve. Resolve WPDS tokens to concrete values (or their
-// fallbacks) before handing the theme to buildChartTheme.
-const resolveColor = ( value?: string ): string | undefined =>
-	value ? resolveCssVariable( value ) ?? value : value;
-
 export const useXYChartTheme = ( data: SeriesData[] ) => {
 	const theme = useGlobalChartsTheme();
+	const scopeElement = useChartScopeElement();
 
-	return useMemo( () => {
-		const seriesColors = ( data ?? [] )
+	// The only thing the theme takes from `data` is the series strokes, so key the memo on those rather than on the array's identity. A caller passing an inline literal — `<LineChart data={ [ … ] } />`, which the stories and several consumers do — otherwise rebuilds the whole theme on every render. Serialised rather than joined: a stroke can be `rgba(0, 0, 0, 0.5)` or `var(--brand, #fff)`, and any separator that reads naturally inside a colour cannot round-trip.
+	const seriesColorKey = JSON.stringify(
+		( data ?? [] )
 			.map( series => series.options?.stroke )
-			.filter( ( color ): color is string => Boolean( color ) );
+			.filter( ( color ): color is string => Boolean( color ) )
+	);
+
+	return useMemo( () => {
+		// visx applies grid, axis, and tick-label colours as SVG presentation attributes, where CSS var() cannot resolve. Resolve the catalog token against the chart's own scope element — never :root — so this reads any override set inside the provider tree, the same one a CSS-painted element would inherit.
+		//
+		// One resolver per theme build, so the five roles below share a single getComputedStyle call rather than taking one each: this memo re-runs only when the scope element attaches or a series colour changes, which for a dashboard of charts is the difference between two style queries per chart and ten.
+		const resolve = createCssVariableResolver( scopeElement );
+		const resolveColor = ( value?: string ): string | undefined =>
+			value ? resolve( value ) ?? value : value;
+
+		const seriesColors: string[] = JSON.parse( seriesColorKey );
 
 		return buildChartTheme( {
 			...theme,
@@ -39,5 +47,5 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 				fill: resolveColor( theme.svgLabelSmall.fill ),
 			},
 		} );
-	}, [ theme, data ] );
+	}, [ theme, seriesColorKey, scopeElement ] );
 };

package/src/index.ts

@@ -32,6 +32,8 @@ export {
 	useGlobalChartsTheme,
 	GlobalChartsContext,
 	defaultTheme,
+	useChartScopeElement,
+	useChartRegistration,
 } from './providers';
 
 // Types - explicit exports (excludes internal types like DataPointPercentageCalculated)
@@ -60,7 +62,6 @@ export type {
 	ChartLegendConfig,
 	SeriesChartLegendConfig,
 	BaseChartProps,
-	GridProps,
 	GoogleDataTableColumn,
 	GoogleDataTableColumnRoleType,
 	GoogleDataTableRow,
@@ -122,6 +123,12 @@ export type { ArcData } from './charts/pie-semi-circle-chart';
 export type { SparklineProps, GradientConfig, SparklineDataPoint } from './charts/sparkline';
 
 // Utilities
-export { parseAsLocalDate, formatMetricValue, formatPercentage, mergeThemes } from './utils';
+export {
+	parseAsLocalDate,
+	formatMetricValue,
+	formatPercentage,
+	mergeThemes,
+	resolveCssVariable,
+} from './utils';
 export * from './utils/color-utils';
 export type { MetricValueType } from './utils';

package/src/providers/chart-context/global-charts-provider.tsx

@@ -8,6 +8,11 @@ import {
 	useLayoutEffect,
 	useRef,
 } from 'react';
+// Side-effect import: emits the `--a8c-charts-*` catalog, scoped to the `a8c-charts-scope` class applied to this component's wrapper below. Every chart either sits under a `GlobalChartsProvider` or auto-mounts its own, so importing it here guarantees the catalog always reaches the bundle.
+//
+// This must be a direct import of the stylesheet, not through a re-export barrel: a barrel `.ts` file doesn't match this package's `sideEffects` glob (only `*.css`/`*.scss` do), so tsdown/Rolldown treats an unused barrel import as side-effect-free and drops it — taking the nested stylesheet import with it. The file also can't be named `*.module.scss`: it declares zero CSS-module class names (only a `:where()`-wrapped selector), and `@tsdown/css` marks a `.module.*` file's generated JS proxy `moduleSideEffects: false` (tree-shakeable unless a class name is read); a plain stylesheet gets `moduleSideEffects: "no-treeshake"` instead, so it always ships. `tools/assert-charts-scope-emitted.ts` fails `pnpm run build` if this regresses — a passing test suite alone does not catch a dropped stylesheet.
+import '../../styles/chart-scope.scss';
+import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
 import {
 	getItemShapeStyles,
 	getSeriesBarStyles,
@@ -16,11 +21,15 @@ import {
 	resolveCssVariable,
 	normalizeColorToHex,
 } from '../../utils';
+// Imported from the module rather than the `chart-scope` barrel: the barrel also pulls `use-standalone-scope-class`, which imports `GlobalChartsContext` back from this file. That cycle resolves today only because the binding is read lazily inside the hook body.
+import { ChartScopeContext } from '../chart-scope/chart-scope-context';
 import { getChartColor, type ColorCache } from './private/get-chart-color';
+import { themeOverrideVars } from './private/theme-override-vars';
+import { withCatalogPointers } from './private/with-catalog-pointers';
 import { defaultTheme } from './themes';
 import type { GlobalChartsContextValue, ChartRegistration } from './types';
 import type { ChartTheme, CompleteChartTheme } from '../../types';
-import type { FC, ReactNode } from 'react';
+import type { CSSProperties, FC, ReactNode } from 'react';
 
 export const GlobalChartsContext = createContext< GlobalChartsContextValue | null >( null );
 
@@ -38,10 +47,26 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 
 	// Ref to the wrapper element for resolving scoped CSS variables
 	const wrapperRef = useRef< HTMLDivElement >( null );
+	const [ scopeNode, setScopeNode ] = useState< HTMLElement | null >( null );
+
+	const setWrapperNode = useCallback( ( node: HTMLDivElement | null ) => {
+		wrapperRef.current = node;
+		setScopeNode( node );
+	}, [] );
+
+	// themeOverrideVars reads the raw `theme` prop, never `providerTheme` — feeding it the restored theme below would make an overridden role's pointer look like a self-reference and drop the var (see themeOverrideVars' own doc comment).
+	const { vars: overrideVars, roles: overriddenRoles } = useMemo(
+		() => themeOverrideVars( theme ),
+		[ theme ]
+	);
 
 	const providerTheme: CompleteChartTheme = useMemo( () => {
-		return theme ? mergeThemes( defaultTheme, theme ) : defaultTheme;
-	}, [ theme ] );
+		if ( ! theme ) {
+			return defaultTheme;
+		}
+
+		return withCatalogPointers( mergeThemes( defaultTheme, theme ), overriddenRoles );
+	}, [ theme, overriddenRoles ] );
 
 	// Cache expensive color computations that only change when theme colors change
 	// Using useState + useLayoutEffect instead of useMemo to ensure CSS variables
@@ -186,11 +211,6 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 		[ colorCache, groupToColorMap ]
 	);
 
-	const resolveThemeColor = useCallback< GlobalChartsContextValue[ 'resolveThemeColor' ] >(
-		value => ( value ? normalizeColorToHex( value, wrapperRef.current, resolveCssVariable ) : '' ),
-		[]
-	);
-
 	const getElementStyles = useCallback< GlobalChartsContextValue[ 'getElementStyles' ] >(
 		( { data, index, overrideColor, legendShape } ) => {
 			const isSeriesData = data && typeof data === 'object' && 'data' in data && 'options' in data;
@@ -269,7 +289,6 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			getChartData,
 			theme: providerTheme,
 			getElementStyles,
-			resolveThemeColor,
 			toggleSeriesVisibility,
 			isSeriesVisible,
 			getHiddenSeries,
@@ -282,7 +301,6 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 			getChartData,
 			providerTheme,
 			getElementStyles,
-			resolveThemeColor,
 			toggleSeriesVisibility,
 			isSeriesVisible,
 			getHiddenSeries,
@@ -292,8 +310,13 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 
 	return (
 		<GlobalChartsContext.Provider value={ value }>
-			<div ref={ wrapperRef } style={ { display: 'contents' } }>
-				{ children }
+			<div
+				ref={ setWrapperNode }
+				className={ CHART_SCOPE_CLASS }
+				data-testid="charts-scope"
+				style={ { display: 'contents', ...overrideVars } as CSSProperties }
+			>
+				<ChartScopeContext.Provider value={ scopeNode }>{ children }</ChartScopeContext.Provider>
 			</div>
 		</GlobalChartsContext.Provider>
 	);

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

@@ -0,0 +1,87 @@
+import type { ChartTheme } from '../../../types';
+
+// The consumer theme fields that correspond to an emitted catalog role, and the role each one overrides. Each role must be read by exactly the elements its field controlled before the role existed: `svgLabelSmall.fill` maps to the narrow `--a8c-charts-color-label-axis` rather than `--a8c-charts-color-label`, because the broad role is also read by legend labels, heatmap cell values, funnel labels and the line-chart tooltip, which that field never moved.
+const ROLE_FOR_FIELD: Array< [ string, ( theme: Partial< ChartTheme > ) => string | undefined ] > =
+	[
+		[ '--a8c-charts-color-background', theme => theme.backgroundColor ],
+		[ '--a8c-charts-color-grid', theme => theme.gridStyles?.stroke ],
+		[ '--a8c-charts-color-axis', theme => theme.xAxisLineStyles?.stroke ],
+		[ '--a8c-charts-color-tick', theme => theme.xTickLineStyles?.stroke ],
+		[ '--a8c-charts-color-label-axis', theme => theme.svgLabelSmall?.fill ],
+	];
+
+/**
+ * The variable a `theme` prop override is published as, one layer outside the role itself.
+ *
+ * `chart-scope.scss` declares each of these roles as `var(<role>-theme, <catalog default>)`, so an override that is invalid at computed-value time — a fallback-less `var()` naming a token the host never set — only invalidates this variable, and the role still resolves its mapped `--wpds-*` token. Published as the role directly, such a value took the role and every bare `var(<role>)` read site down with it.
+ *
+ * @param role - The catalog role being overridden.
+ * @return The custom property carrying the consumer's value.
+ */
+export const themeLayerVar = ( role: string ): string => `${ role }-theme`;
+
+/** Every role whose catalog entry must read a theme layer. `src/styles/test/chart-scope.test.ts` checks the stylesheet against this. */
+export const THEME_LAYERED_ROLES: readonly string[] = ROLE_FOR_FIELD.map( ( [ role ] ) => role );
+
+/**
+ * Whether a value reads the role it is being published for, which would make the catalog entry depend on itself.
+ *
+ * The dependency runs `<role>: var(<role>-theme, …)`, so a value naming `<role>` closes a cycle through the catalog entry. CSS marks every custom property in a cycle invalid at computed-value time — the role's own fallback is *not* used, so the token resolves to nothing and every chart loses that colour. Verified in Chrome: `--role-theme: var(--role, blue); --role: var(--role-theme, green)` leaves `--role` empty, not `green`.
+ *
+ * Three things this has to get right, none of which a plain substring test gets:
+ *
+ * `var()` permits whitespace after the opening paren, so testing for `var(<role>` misses `var( --a8c-charts-color-grid, … )`.
+ *
+ * Several roles are prefixes of others (`--a8c-charts-color-label` of `--a8c-charts-color-label-secondary`), and every role is a prefix of its own theme layer. A prefix match would read a legitimate cross-role pointer as a self-reference and silently drop the override, so the role must be followed by something that cannot continue an identifier — `-` included. A value naming `<role>-theme` is therefore not treated as a self-reference: that cycle is confined to the theme layer, which leaves the role free to fall back to the catalog default.
+ *
+ * `resolveCssVariable` also accepts a bare custom-property name with no `var()` wrapper (`--a8c-charts-color-grid`), so that is legal `theme` input too. It forms no cycle — custom properties accept arbitrary token streams — so it survives as a literal string and drops silently at the use site instead of falling back to the catalog default.
+ *
+ * @param value - The consumer's value for the field.
+ * @param role  - The catalog role this value would override.
+ * @return True when the value reads `role`, so it must not be published.
+ */
+const readsOwnRole = ( value: string, role: string ): boolean =>
+	value.trim() === role ||
+	new RegExp( `var\\(\\s*${ role.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' ) }(?![\\w-])` ).test(
+		value
+	);
+
+export type ThemeOverrides = {
+	/** The custom properties to write on the provider wrapper. */
+	vars: Record< string, string >;
+	/** Every mapped role the consumer set a value for, whether or not it was published. */
+	roles: readonly string[];
+};
+
+/**
+ * Maps a sparse consumer theme onto the theme-layer variables its overridden catalog roles read, so CSS-painted and JS-resolved colours read one source.
+ *
+ * A value that reads the role it would override is left unpublished — that is the default theme's own pointer surviving `mergeThemes`, and publishing it would invalidate the role. The role is still reported in `roles`: `withCatalogPointers` restores its theme field to the catalog pointer either way, so CSS and visx agree on the catalog default rather than visx painting a literal CSS never sees.
+ *
+ * @param theme - The consumer's `theme` prop, before merging with the default theme.
+ * @return The wrapper's custom properties, and the roles the consumer overrode.
+ */
+export const themeOverrideVars = ( theme?: Partial< ChartTheme > ): ThemeOverrides => {
+	if ( ! theme ) {
+		return { vars: {}, roles: [] };
+	}
+
+	const vars: Record< string, string > = {};
+	const roles: string[] = [];
+
+	for ( const [ role, read ] of ROLE_FOR_FIELD ) {
+		const value = read( theme );
+
+		if ( typeof value !== 'string' || value === '' ) {
+			continue;
+		}
+
+		roles.push( role );
+
+		if ( ! readsOwnRole( value, role ) ) {
+			vars[ themeLayerVar( role ) ] = value;
+		}
+	}
+
+	return { vars, roles };
+};

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

@@ -0,0 +1,50 @@
+import { defaultTheme } from '../themes';
+import type { CompleteChartTheme } from '../../../types';
+
+// Restores each overridden role's mapped theme field to the catalog pointer `defaultTheme` already carries for it, so the value comes from `themes.ts` itself rather than a second, hand-copied literal.
+const CATALOG_RESTORE_FOR_ROLE: Record<
+	string,
+	( theme: CompleteChartTheme ) => Partial< CompleteChartTheme >
+> = {
+	'--a8c-charts-color-background': () => ( { backgroundColor: defaultTheme.backgroundColor } ),
+	'--a8c-charts-color-grid': theme => ( {
+		gridStyles: { ...theme.gridStyles, stroke: defaultTheme.gridStyles.stroke },
+	} ),
+	'--a8c-charts-color-axis': theme => ( {
+		xAxisLineStyles: { ...theme.xAxisLineStyles, stroke: defaultTheme.xAxisLineStyles.stroke },
+	} ),
+	'--a8c-charts-color-tick': theme => ( {
+		xTickLineStyles: { ...theme.xTickLineStyles, stroke: defaultTheme.xTickLineStyles.stroke },
+	} ),
+	'--a8c-charts-color-label-axis': theme => ( {
+		svgLabelSmall: { ...theme.svgLabelSmall, fill: defaultTheme.svgLabelSmall.fill },
+	} ),
+};
+
+/**
+ * Restores the mapped theme fields of `overriddenRoles` to their catalog pointer, so the theme-layer variable `themeOverrideVars` writes on the provider wrapper is the only carrier for an overridden role — CSS and the JS bridge (`useXYChartTheme`) then resolve it through the same cascade instead of visx reading a baked literal that can disagree with a closer CSS override.
+ *
+ * This covers roles `themeOverrideVars` deliberately left unpublished as well as the ones it published. A value that reads its own role is not publishable, but leaving visx the consumer's literal is what the whole mechanism exists to prevent: `theme={ { gridStyles: { stroke: 'var(--brand, var(--a8c-charts-color-grid, red))' } } }` would have CSS paint the catalog default while visx painted `--brand`.
+ *
+ * Every field outside the five mapped roles is left exactly as `merged` provided it: those aren't published as theme-layer vars, so rewriting them would erase a consumer's override with no replacement carrier.
+ *
+ * @param merged          - The consumer theme merged onto `defaultTheme` (`mergeThemes` output).
+ * @param overriddenRoles - The catalog roles the consumer overrode, from `themeOverrideVars`.
+ * @return A new theme object; `merged` is not mutated.
+ */
+export const withCatalogPointers = (
+	merged: CompleteChartTheme,
+	overriddenRoles: readonly string[]
+): CompleteChartTheme => {
+	let result = merged;
+
+	for ( const role of overriddenRoles ) {
+		const restore = CATALOG_RESTORE_FOR_ROLE[ role ];
+
+		if ( restore ) {
+			result = { ...result, ...restore( result ) };
+		}
+	}
+
+	return result;
+};

package/src/providers/chart-context/test/chart-context.test.tsx

@@ -2536,46 +2536,6 @@ describe( 'ChartContext', () => {
 				expect( afterRerenderColor ).toBe( '#ff0000' );
 			} );
 		} );
-
-		describe( 'resolveThemeColor', () => {
-			let contextValue: GlobalChartsContextValue;
-
-			const TestComponent = () => {
-				contextValue = useGlobalChartsContext();
-				return <div>Test</div>;
-			};
-
-			const mountProvider = () =>
-				render(
-					<GlobalChartsProvider>
-						<TestComponent />
-					</GlobalChartsProvider>
-				);
-
-			it( 'resolves a CSS variable against the provider scope, not the document root', () => {
-				window.getComputedStyle = jest.fn( ( element: Element ) => ( {
-					getPropertyValue: ( prop: string ) =>
-						prop === '--surface' && element !== document.documentElement ? '#1e1e1e' : '#ffffff',
-				} ) ) as unknown as typeof window.getComputedStyle;
-
-				mountProvider();
-
-				expect( contextValue.resolveThemeColor( 'var(--surface, #fff)' ) ).toBe( '#1e1e1e' );
-			} );
-
-			it( 'passes a resolved color through to hex', () => {
-				mountProvider();
-
-				expect( contextValue.resolveThemeColor( '#abcdef' ) ).toBe( '#abcdef' );
-				expect( contextValue.resolveThemeColor( 'rgb(255, 0, 0)' ) ).toBe( '#ff0000' );
-			} );
-
-			it( 'returns an empty string for an empty value', () => {
-				mountProvider();
-
-				expect( contextValue.resolveThemeColor( '' ) ).toBe( '' );
-			} );
-		} );
 	} );
 
 	describe( 'defaultTheme', () => {

package/src/providers/chart-context/test/chart-scope-class.test.tsx

@@ -0,0 +1,19 @@
+import { render, screen } from '@testing-library/react';
+import { CHART_SCOPE_CLASS } from '../../../styles/chart-scope-class';
+import { GlobalChartsProvider } from '../global-charts-provider';
+
+describe( 'GlobalChartsProvider wrapper', () => {
+	it( 'carries the a8c-charts-scope class and nothing that affects layout', () => {
+		render(
+			<GlobalChartsProvider>
+				<div>child</div>
+			</GlobalChartsProvider>
+		);
+
+		const wrapper = screen.getByTestId( 'charts-scope' );
+
+		expect( wrapper ).toHaveClass( CHART_SCOPE_CLASS );
+		// The catalog needs an element to sit on; `display: contents` is what keeps that element out of the consumer's layout.
+		expect( wrapper.style.cssText.replace( /\s/g, '' ) ).toBe( 'display:contents;' );
+	} );
+} );

package/src/providers/chart-context/test/sparse-theme.test.ts

@@ -0,0 +1,35 @@
+import { defaultTheme } from '../themes';
+
+const flatten = ( value: unknown ): string[] => {
+	if ( typeof value === 'string' ) {
+		return [ value ];
+	}
+	if ( Array.isArray( value ) ) {
+		return value.flatMap( flatten );
+	}
+	if ( value && typeof value === 'object' ) {
+		return Object.values( value ).flatMap( flatten );
+	}
+	return [];
+};
+
+describe( 'defaultTheme', () => {
+	const strings = flatten( defaultTheme );
+
+	it( 'holds no --wpds-* mapping — that lives only in the catalog stylesheet', () => {
+		expect( strings.filter( value => value.includes( '--wpds-' ) ) ).toEqual( [] );
+	} );
+
+	it( 'points every themed colour at an --a8c-charts-* catalog role', () => {
+		const varStrings = strings.filter( value => value.startsWith( 'var(' ) );
+
+		expect( varStrings.length ).toBeGreaterThan( 0 );
+		expect( varStrings.every( value => value.startsWith( 'var(--a8c-charts-' ) ) ).toBe( true );
+	} );
+
+	it( 'gives every catalog pointer a terminal literal for the SSR and jsdom paths', () => {
+		const varStrings = strings.filter( value => value.startsWith( 'var(--a8c-charts-' ) );
+
+		expect( varStrings.every( value => value.includes( ',' ) ) ).toBe( true );
+	} );
+} );