@automattic/charts 2.0.0 → 3.0.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/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,9 +38,6 @@ 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
 	toggleSeriesVisibility: ( chartId: string, seriesLabel: string ) => void;
 	isSeriesVisible: ( chartId: string, seriesLabel: string ) => 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';

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

@@ -0,0 +1,24 @@
+import { renderHook } from '@testing-library/react';
+import { ChartScopeContext, useChartScopeElement } from '../index';
+import type { ReactNode } from 'react';
+
+describe( 'useChartScopeElement', () => {
+	// The default has to stay null rather than `document.documentElement`: a chart with no scope above it must resolve nothing and fall back to its theme literal, not silently read the document root again.
+	it( 'returns null with no scope above it', () => {
+		const { result } = renderHook( () => useChartScopeElement() );
+
+		expect( result.current ).toBeNull();
+	} );
+
+	it( 'returns the enclosing scope element', () => {
+		const scope = document.createElement( 'div' );
+
+		const { result } = renderHook( () => useChartScopeElement(), {
+			wrapper: ( { children }: { children: ReactNode } ) => (
+				<ChartScopeContext.Provider value={ scope }>{ children }</ChartScopeContext.Provider>
+			),
+		} );
+
+		expect( result.current ).toBe( scope );
+	} );
+} );

package/src/providers/chart-scope/test/use-standalone-scope-class.test.tsx

@@ -0,0 +1,20 @@
+import { renderHook } from '@testing-library/react';
+import { CHART_SCOPE_CLASS } from '../../../styles/chart-scope-class';
+import { GlobalChartsProvider } from '../../chart-context/global-charts-provider';
+import { useStandaloneScopeClass } from '../use-standalone-scope-class';
+
+describe( 'useStandaloneScopeClass', () => {
+	it( 'returns the scope class with no provider above it', () => {
+		const { result } = renderHook( () => useStandaloneScopeClass() );
+
+		expect( result.current ).toBe( CHART_SCOPE_CLASS );
+	} );
+
+	it( 'returns undefined inside a GlobalChartsProvider', () => {
+		const { result } = renderHook( () => useStandaloneScopeClass(), {
+			wrapper: ( { children } ) => <GlobalChartsProvider>{ children }</GlobalChartsProvider>,
+		} );
+
+		expect( result.current ).toBeUndefined();
+	} );
+} );

package/src/providers/chart-scope/use-chart-scope-element.ts

@@ -0,0 +1,9 @@
+import { useContext } from 'react';
+import { ChartScopeContext } from './chart-scope-context';
+
+/**
+ * Returns the nearest chart scope element, or `null` when rendered outside any scope (and during SSR, before the ref is attached).
+ *
+ * @return {HTMLElement | null} The nearest chart scope element, or `null`.
+ */
+export const useChartScopeElement = (): HTMLElement | null => useContext( ChartScopeContext );

package/src/providers/chart-scope/use-standalone-scope-class.ts

@@ -0,0 +1,13 @@
+import { useContext } from 'react';
+import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
+import { GlobalChartsContext } from '../chart-context/global-charts-provider';
+
+/**
+ * Returns the catalog class when there is no `GlobalChartsProvider` above this component, and `undefined` when there is.
+ *
+ * Standalone components need the catalog to resolve at all, but inside a provider the tokens already inherit — re-declaring them there would shadow a consumer override set anywhere in the tree.
+ *
+ * @return The scope class name, or undefined when a provider is present.
+ */
+export const useStandaloneScopeClass = (): string | undefined =>
+	useContext( GlobalChartsContext ) ? undefined : CHART_SCOPE_CLASS;

package/src/providers/index.ts

@@ -1 +1,2 @@
 export * from './chart-context';
+export * from './chart-scope';

package/src/styles/chart-scope-class.ts

@@ -0,0 +1,6 @@
+/**
+ * Stable class that carries the `--a8c-charts-*` catalog. Applied to the `GlobalChartsProvider` wrapper, to portal-rendered surfaces (which sit outside the provider tree), and to standalone components when no provider is above them.
+ *
+ * Deliberately unhashed: consumers are documented as being able to target it to override a token on the provider element.
+ */
+export const CHART_SCOPE_CLASS = 'a8c-charts-scope';

package/src/styles/chart-scope.scss

@@ -0,0 +1,83 @@
+// The single mapping point between the --a8c-charts-* catalog and WordPress
+// design-system tokens.
+
+// Declared on the GlobalChartsProvider wrapper — not at :root — because
+// @wordpress/theme's ThemeProvider emits its generated --wpds-* ramp as inline
+// styles on its own wrapper div, not on the document root. Substituting at the
+// provider means a ThemeProvider above it is picked up; substituting at :root
+// would miss it entirely.
+
+// :where() keeps the rule at zero specificity so any consumer rule
+// targeting the same element wins. Chart roots deliberately do NOT
+// re-declare these: an element's own declaration beats an inherited one,
+// so re-declaring lower down would shadow a consumer override set inside
+// the provider tree.
+
+// The five roles a `theme` prop field can override read a `*-theme` variable
+// first, which GlobalChartsProvider writes inline from that field. Publishing
+// the consumer's value one layer out, rather than as the role itself, is what
+// keeps the catalog default reachable: a value that is invalid at
+// computed-value time (a fallback-less `var()` naming a token nothing set,
+// which is how premium-analytics passes its grid stroke) invalidates only the
+// `*-theme` variable, and the role's own fallback still resolves the mapped
+// --wpds-* token. Written as the role directly, that same value made the role
+// guaranteed-invalid and took every bare `var(--a8c-charts-color-grid)` read
+// site with it — gridlines painted `unset` instead of the spec grey.
+// `src/styles/test/chart-scope.test.ts` pins which roles carry the layer.
+
+// Declares custom properties only. This stylesheet must never change layout.
+:where(.a8c-charts-scope) {
+	--a8c-charts-color-grid: var(--a8c-charts-color-grid-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
+	--a8c-charts-color-axis: var(--a8c-charts-color-axis-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
+	--a8c-charts-color-tick: var(--a8c-charts-color-tick-theme, var(--wpds-color-stroke-surface-neutral, #dbdbdb));
+	--a8c-charts-color-label: var(--wpds-color-foreground-content-neutral, #1e1e1e);
+	--a8c-charts-color-label-secondary: var(--wpds-color-foreground-content-neutral-weak, #707070);
+	--a8c-charts-color-label-inverse: var(--wpds-color-foreground-interactive-neutral-strong, #f0f0f0);
+	// White label text sits on arbitrary series colours, so it has no WPDS
+	// content-foreground equivalent.
+	--a8c-charts-color-label-on-fill: #fff;
+	// The SVG axis and tick labels. `svgLabelSmall.fill` publishes THIS role, so
+	// deriving from --a8c-charts-color-label is safe and wanted: the theme field
+	// moves only these labels, while setting the broad role in CSS still moves
+	// every label at once. (--a8c-charts-color-surface cannot derive the same
+	// way — see its comment; there the theme field owns the broad role.)
+	--a8c-charts-color-label-axis: var(--a8c-charts-color-label-axis-theme, var(--a8c-charts-color-label));
+	--a8c-charts-color-annotation: var(--wpds-color-foreground-content-neutral, #1e1e1e);
+	--a8c-charts-color-trend-up: var(--wpds-color-foreground-content-success-weak, #008030);
+	--a8c-charts-color-trend-down: var(--wpds-color-foreground-content-error-weak, #cc1818);
+	--a8c-charts-color-trend-neutral: var(--wpds-color-foreground-content-neutral-weak, #707070);
+	--a8c-charts-color-background: var(--a8c-charts-color-background-theme, var(--wpds-color-background-surface-neutral-strong, #fff));
+	// Surfaces that float over the chart — tooltips, the annotation label, the
+	// zoom-reset control. Same WPDS token as --a8c-charts-color-background, and
+	// deliberately NOT derived from it: `backgroundColor` publishes the
+	// background role, so deriving would let that theme field repaint these too.
+	// Sibling of the background role, not a child of it.
+	--a8c-charts-color-surface: var(--wpds-color-background-surface-neutral-strong, #fff);
+	--a8c-charts-color-surface-secondary: var(--wpds-color-background-surface-neutral-weak, #f4f4f4);
+	--a8c-charts-color-track: var(--wpds-color-background-track-neutral-weak, #f0f0f0);
+	// Translucent dark surface; no WPDS token carries this.
+	--a8c-charts-color-tooltip-surface: rgb(0 0 0 / 85%);
+	--a8c-charts-color-zoom-selection: var(--wpds-color-background-interactive-brand-strong, #3858e9);
+	--a8c-charts-color-zoom-selection-stroke: var(--wpds-color-stroke-interactive-brand, #3858e9);
+
+	// @wordpress/theme 1.0.0 removed the whole --wpds-elevation-* group while the
+	// elevation model is redefined (gutenberg#80099). These carry the removed spec
+	// values literally until a replacement token exists.
+	--a8c-charts-elevation-xs:
+		0 1px 1px 0 #00000008,
+		0 1px 2px 0 #00000005,
+		0 3px 3px 0 #00000005,
+		0 4px 4px 0 #00000003;
+	--a8c-charts-elevation-sm:
+		0 1px 2px 0 #0000000d,
+		0 2px 3px 0 #0000000a,
+		0 6px 6px 0 #00000008,
+		0 8px 8px 0 #00000005;
+
+	--a8c-charts-motion-duration-entrance: var(--wpds-motion-duration-xl, 400ms);
+	--a8c-charts-motion-easing-entrance: var(--wpds-motion-easing-expressive, cubic-bezier(0.25, 0, 0, 1));
+	--a8c-charts-border-radius-bar: var(--wpds-border-radius-md, 4px);
+	--a8c-charts-border-radius-cell: var(--wpds-border-radius-sm, 2px);
+	// Pill shape; no WPDS radius reaches it.
+	--a8c-charts-border-radius-leaderboard-bar: 9999px;
+}

package/src/styles/test/chart-scope.test.ts

@@ -0,0 +1,165 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+	THEME_LAYERED_ROLES,
+	themeLayerVar,
+} from '../../providers/chart-context/private/theme-override-vars';
+
+const stylesheet = readFileSync( join( __dirname, '..', 'chart-scope.scss' ), 'utf8' );
+const tokensDoc = readFileSync( join( __dirname, '..', '..', '..', 'TOKENS.md' ), 'utf8' );
+
+type Entry = {
+	/** The custom property this one reads, or null when the value is a literal. */
+	reads: string | null;
+	/** The `var()` fallback, or the whole value when it reads nothing. */
+	fallback: string | null;
+};
+
+const normalize = ( value: string ): string => value.replace( /\s+/g, ' ' ).trim();
+
+/**
+ * Unwraps the theme layer a `theme`-prop-overridable role carries, so the tables in `TOKENS.md` keep documenting what a role ultimately resolves to — its `--wpds-*` token and spec fallback — rather than restating the override plumbing in every row. Which roles carry the layer is pinned separately below.
+ *
+ * @param name  - The declared property name.
+ * @param value - Its normalized value.
+ * @return The value with a leading `var(<name>-theme, … )` wrapper removed.
+ */
+function stripThemeLayer( name: string, value: string ): string {
+	const layered = new RegExp( `^var\\(\\s*${ themeLayerVar( name ) }\\s*,\\s*(.*)\\)$`, 's' ).exec(
+		value
+	);
+
+	return layered ? layered[ 1 ].trim() : value;
+}
+
+/**
+ * Parses each catalog declaration in the stylesheet into the property it reads and the fallback it carries. Splitting the `var()` arguments at the *first* comma keeps a fallback that is itself a function call intact — `cubic-bezier(0.25, 0, 0, 1)` would otherwise be truncated at its first argument.
+ *
+ * @return Every declared `--a8c-charts-*` property, keyed by name.
+ */
+function parseStylesheet(): Map< string, Entry > {
+	const body = stylesheet.slice( stylesheet.indexOf( '{' ) + 1, stylesheet.lastIndexOf( '}' ) );
+	const entries = new Map< string, Entry >();
+
+	for ( const declaration of body
+		.split( '\n' )
+		.map( line => line.trim() )
+		.filter( line => line && ! line.startsWith( '//' ) )
+		.join( '\n' )
+		.split( ';' ) ) {
+		const separator = declaration.indexOf( ':' );
+
+		if ( separator === -1 ) {
+			continue;
+		}
+
+		const name = declaration.slice( 0, separator ).trim();
+		const value = stripThemeLayer( name, normalize( declaration.slice( separator + 1 ) ) );
+		const wrapped = /^var\(\s*(.*)\)$/s.exec( value );
+
+		if ( ! wrapped ) {
+			entries.set( name, { reads: null, fallback: value } );
+			continue;
+		}
+
+		const args = wrapped[ 1 ];
+		const comma = args.indexOf( ',' );
+
+		entries.set(
+			name,
+			comma === -1
+				? { reads: args.trim(), fallback: null }
+				: { reads: args.slice( 0, comma ).trim(), fallback: normalize( args.slice( comma + 1 ) ) }
+		);
+	}
+
+	return entries;
+}
+
+/**
+ * Parses the catalog tables in `TOKENS.md` — the ones whose header is `Role | Maps to …` — into the same shape as the stylesheet, so the two can be compared directly. Other tables in the document (theme-field mappings, deprecated aliases) are skipped.
+ *
+ * @return Every documented role, keyed by name.
+ */
+function parseTokensDoc(): Map< string, Entry > {
+	const entries = new Map< string, Entry >();
+	const lines = tokensDoc.split( '\n' );
+	let inCatalogTable = false;
+
+	for ( const line of lines ) {
+		if ( ! line.trim().startsWith( '|' ) ) {
+			inCatalogTable = false;
+			continue;
+		}
+
+		const cells = line
+			.split( '|' )
+			.slice( 1, -1 )
+			.map( cell => cell.trim() );
+
+		if ( cells[ 0 ] === 'Role' ) {
+			inCatalogTable = cells[ 1 ]?.startsWith( 'Maps to' ) ?? false;
+			continue;
+		}
+
+		if ( ! inCatalogTable || cells.length !== 3 || /^-+$/.test( cells[ 0 ] ) ) {
+			continue;
+		}
+
+		const [ role, mapping, fallback ] = cells.map( cell => cell.replace( /`/g, '' ) );
+		// A "none" cell explains *why* there is no mapping, and that explanation can
+		// name a `--wpds-*` token itself (the removed elevation group). Read it as
+		// "no mapping" before looking for a token name inside it.
+		const unmapped = mapping.startsWith( '_(none' );
+		const derives = /derives from (--[\w-]+)/.exec( mapping );
+		const wpds = /(--wpds-[\w-]+)/.exec( mapping );
+
+		entries.set( role, {
+			reads: unmapped ? null : derives?.[ 1 ] ?? wpds?.[ 1 ] ?? null,
+			fallback: fallback === '—' ? null : normalize( fallback ),
+		} );
+	}
+
+	return entries;
+}
+
+const declared = parseStylesheet();
+const documented = parseTokensDoc();
+
+describe( 'chart scope catalog', () => {
+	it( 'documents every declared role, and declares every documented one', () => {
+		expect( [ ...documented.keys() ].sort() ).toEqual( [ ...declared.keys() ].sort() );
+	} );
+
+	// The tables in TOKENS.md restate the stylesheet for consumers who only have the
+	// published package. This is the check that stops the two drifting apart.
+	it.each( [ ...declared.keys() ] )( 'documents %s with the value it is declared with', token => {
+		expect( documented.get( token ) ).toEqual( declared.get( token ) );
+	} );
+
+	// The layer is what keeps a `theme` prop override from being able to take its role down with it: an override that is invalid at computed-value time only invalidates `<role>-theme`, and the role's own fallback still resolves the mapped token. Drop the layer from a role and that role's overrides go back to blanking every read site.
+	it.each( THEME_LAYERED_ROLES )( 'declares %s reading its theme layer first', role => {
+		expect( stylesheet ).toMatch(
+			new RegExp( `${ role }:\\s*var\\(\\s*${ themeLayerVar( role ) }\\s*,` )
+		);
+	} );
+
+	it( 'gives a theme layer to the overridable roles and to nothing else', () => {
+		const layered = [ ...declared.keys() ].filter( role =>
+			new RegExp( `${ role }:\\s*var\\(\\s*${ themeLayerVar( role ) }\\s*,` ).test( stylesheet )
+		);
+
+		expect( layered.sort() ).toEqual( [ ...THEME_LAYERED_ROLES ].sort() );
+	} );
+
+	it( 'scopes the catalog to :where(.a8c-charts-scope) rather than :root', () => {
+		expect( stylesheet ).toMatch( /:where\(\.a8c-charts-scope\)\s*{/ );
+		expect( stylesheet ).not.toMatch( /(^|\s):root\s*{/ );
+	} );
+
+	it( 'declares custom properties only, so this stylesheet cannot change layout', () => {
+		expect( [ ...declared.keys() ].every( name => name.startsWith( '--a8c-charts-' ) ) ).toBe(
+			true
+		);
+	} );
+} );