@automattic/charts 3.1.1 → 3.2.0

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

@@ -4,15 +4,15 @@ 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.
+// A `theme` prop override reaches CSS-painted elements through the inline `--a8c-charts-*` var GlobalChartsProvider writes on its wrapper, and reaches the values our own components read through `providerTheme`. Before the fix, `providerTheme` carried the override's literal directly, so an element-level `--a8c-charts-color-background` 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' );
+		nestedOverride.style.setProperty( '--a8c-charts-color-background', '#00ff00' );
 		document.body.appendChild( nestedOverride );
 
 		const wrapper = ( { children }: { children: ReactNode } ) => (
-			<GlobalChartsProvider theme={ { gridStyles: { stroke: 'rgb(255,0,0)' } } }>
+			<GlobalChartsProvider theme={ { backgroundColor: 'rgb(255,0,0)' } }>
 				<ChartScopeContext.Provider value={ nestedOverride }>
 					{ children }
 				</ChartScopeContext.Provider>
@@ -21,7 +21,7 @@ describe( 'useXYChartTheme resolves a theme prop override through the CSS cascad
 
 		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
 
-		expect( result.current.gridStyles.stroke ).toBe( '#00ff00' );
+		expect( result.current.backgroundColor ).toBe( '#00ff00' );
 
 		document.body.removeChild( nestedOverride );
 	} );

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

@@ -4,7 +4,7 @@ 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.
+// The theme resolves the background role and the five palette slots. 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 color changes, so a dashboard mounting N charts pays the count below N times over.
 const STABLE_DATA: SeriesData[] = [];
 
 describe( 'useXYChartTheme style reads', () => {
@@ -13,7 +13,6 @@ describe( 'useXYChartTheme style reads', () => {
 
 	beforeEach( () => {
 		scope = document.createElement( 'div' );
-		scope.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
 		document.body.appendChild( scope );
 		getComputedStyleSpy = jest.spyOn( window, 'getComputedStyle' );
 	} );
@@ -33,14 +32,13 @@ describe( 'useXYChartTheme style reads', () => {
 
 	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' );
+		scope.style.setProperty( '--a8c-charts-color-series-2', '#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' );
+		expect( result.current.colors ).toContain( '#222222' );
 	} );
 
 	it( 'does not re-read styles when the hook re-renders with the same inputs', () => {
@@ -74,16 +72,25 @@ describe( 'useXYChartTheme style reads', () => {
 		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.
+	// The memo key serializes the strokes rather than joining them, so a color containing a comma or a space survives the round-trip intact. `rgba(0, 0, 0, 0.5)` is the one that proves it: it holds both separators and comes back whole.
+	//
+	// The `var()` entry resolves to its fallback rather than passing through, which is the point of resolving the palette at all — visx paints these as SVG presentation attributes, where a `var()` resolves to nothing.
 	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)',
-		] );
+		expect( result.current.colors.slice( 0, 2 ) ).toEqual( [ 'rgba(0, 0, 0, 0.5)', '#fff' ] );
+	} );
+
+	// Four of the five palette slots carry no catalog default, so in jsdom they resolve to nothing. Passing those to visx unresolved would make them its default stroke for any series without an explicit one, painting nothing at all.
+	it( 'drops palette entries that resolve to nothing', () => {
+		const { result } = renderWithScope( [] );
+
+		expect( result.current.colors ).not.toEqual(
+			expect.arrayContaining( [ expect.stringContaining( 'var(' ) ] )
+		);
+		expect( result.current.colors.length ).toBeGreaterThan( 0 );
 	} );
 } );

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

@@ -4,11 +4,11 @@ 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' );
+	it( 'resolves background color against the scope element, not the document root', () => {
+		document.documentElement.style.setProperty( '--a8c-charts-color-background', '#ff0000' );
 
 		const scope = document.createElement( 'div' );
-		scope.style.setProperty( '--a8c-charts-color-grid', '#00ff00' );
+		scope.style.setProperty( '--a8c-charts-color-background', '#00ff00' );
 		document.body.appendChild( scope );
 
 		const wrapper = ( { children }: { children: ReactNode } ) => (
@@ -17,9 +17,54 @@ describe( 'useXYChartTheme', () => {
 
 		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
 
-		expect( result.current.gridStyles.stroke ).toBe( '#00ff00' );
+		expect( result.current.backgroundColor ).toBe( '#00ff00' );
+
+		document.documentElement.style.removeProperty( '--a8c-charts-color-background' );
+		document.body.removeChild( scope );
+	} );
+
+	// Resolving a paint-only color here would freeze it: visx writes whatever it is handed onto the element, so a literal stops following the cascade and an override set below the provider wrapper never reaches it. Handing visx the pointer instead lets it resolve at the element it paints. jsdom does not compute `var()`, so what the pointer resolves *to* is covered in Storybook; this pins that the chain survives the theme build intact.
+	it( 'hands visx the catalog pointer for paint-only colors rather than a resolved value', () => {
+		const scope = document.createElement( 'div' );
+		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( 'var(--a8c-charts-color-grid, #dbdbdb)' );
+		expect( result.current.axisStyles.x.bottom.axisLine.stroke ).toBe(
+			'var(--a8c-charts-color-axis, #dbdbdb)'
+		);
+		expect( result.current.axisStyles.x.bottom.tickLine.stroke ).toBe(
+			'var(--a8c-charts-color-tick, #dbdbdb)'
+		);
+		expect( result.current.axisStyles.x.bottom.tickLabel.fill ).toBe(
+			'var(--a8c-charts-color-label-axis, #1e1e1e)'
+		);
+
+		document.body.removeChild( scope );
+	} );
+
+	// The one label color that has to arrive resolved: visx paints it on a portal container appended to `document.body`, where the catalog is not declared, and concatenates it into `box-shadow: 0 1px 2px ${color}55`, which a `var()` chain would invalidate.
+	it( 'resolves the tooltip label color while the tick labels keep the pointer', () => {
+		const scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-label-axis', '#0000ff' );
+		document.body.appendChild( scope );
+
+		const wrapper = ( { children }: { children: ReactNode } ) => (
+			<ChartScopeContext.Provider value={ scope }>{ children }</ChartScopeContext.Provider>
+		);
+
+		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
+
+		expect( result.current.htmlLabel.color ).toBe( '#0000ff' );
+		expect( result.current.svgLabelSmall.fill ).toBe(
+			'var(--a8c-charts-color-label-axis, #1e1e1e)'
+		);
 
-		document.documentElement.style.removeProperty( '--a8c-charts-color-grid' );
 		document.body.removeChild( scope );
 	} );
 } );

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

@@ -9,7 +9,7 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 	const theme = useGlobalChartsTheme();
 	const scopeElement = useChartScopeElement();
 
-	// 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.
+	// 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. Serialized 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 color cannot round-trip.
 	const seriesColorKey = JSON.stringify(
 		( data ?? [] )
 			.map( series => series.options?.stroke )
@@ -17,35 +17,29 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 	);
 
 	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.
+		// Only what is read as a string is resolved here — the palette and `backgroundColor` — plus `htmlLabel.color` below, which is painted outside the scope. Resolving against the chart's own scope element, never :root, is what reads an override set inside the provider tree.
 		//
-		// 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.
+		// One resolver per theme build, so all three share a single getComputedStyle call.
 		const resolve = createCssVariableResolver( scopeElement );
 		const resolveColor = ( value?: string ): string | undefined =>
 			value ? resolve( value ) ?? value : value;
 
 		const seriesColors: string[] = JSON.parse( seriesColorKey );
 
+		// The palette gets the same treatment as every other color here, and needs it more: `theme.colors` is the one field that is always a `var()` chain, and the four slots without a catalog default resolve to nothing at all. visx builds its `colorScale` from this array and uses it as the default stroke for a series rendered without an explicit one, so an unresolved entry paints nothing rather than degrading. Entries that resolve to nothing are dropped so the scale compacts the way the provider's own palette does.
+		const paletteColors = [ ...seriesColors, ...( theme.colors ?? [] ) ]
+			.map( color => resolveColor( color ) )
+			.filter( ( color ): color is string => Boolean( color ) && ! color.includes( 'var(' ) );
+
+		// The tooltip is painted in a portal outside the scope, and visx concatenates this color into a `box-shadow` where a chain cannot take a suffix; see TOKENS.md#the-svg-bridge. Passing it explicitly leaves `svgLabelSmall.fill`, which visx derives it from, a chain for the SVG tick labels.
+		const htmlLabelColor = resolveColor( theme.svgLabelSmall?.fill );
+
+		// The grid, axis, tick and label colors are spread through untouched, and that is the whole mechanism: visx writes each one onto the element it paints — as an inline style for the grid, a presentation attribute elsewhere — and a `var()` chain resolves there natively. So the role is read at the painted element rather than snapshot at the provider wrapper, which is what makes an override on a chart's own class work, keeps a theme change live without a re-render, and leaves nothing to resolve during SSR. Resolving them here would freeze the color instead.
 		return buildChartTheme( {
 			...theme,
-			colors: [ ...seriesColors, ...( theme.colors ?? [] ) ],
+			colors: paletteColors,
 			backgroundColor: resolveColor( theme.backgroundColor ),
-			gridStyles: theme.gridStyles && {
-				...theme.gridStyles,
-				stroke: resolveColor( theme.gridStyles.stroke ),
-			},
-			xAxisLineStyles: theme.xAxisLineStyles && {
-				...theme.xAxisLineStyles,
-				stroke: resolveColor( theme.xAxisLineStyles.stroke ),
-			},
-			xTickLineStyles: theme.xTickLineStyles && {
-				...theme.xTickLineStyles,
-				stroke: resolveColor( theme.xTickLineStyles.stroke ),
-			},
-			svgLabelSmall: theme.svgLabelSmall && {
-				...theme.svgLabelSmall,
-				fill: resolveColor( theme.svgLabelSmall.fill ),
-			},
+			htmlLabel: htmlLabelColor ? { color: htmlLabelColor } : undefined,
 		} );
 	}, [ theme, seriesColorKey, scopeElement ] );
 };

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

@@ -24,6 +24,7 @@ import {
 // 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 { SERIES_PALETTE_POINTERS } from './private/series-palette';
 import { themeOverrideVars } from './private/theme-override-vars';
 import { withCatalogPointers } from './private/with-catalog-pointers';
 import { defaultTheme } from './themes';
@@ -91,45 +92,48 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 	// Resolves CSS variables from the wrapper element's scope to handle scoped variables
 	// Note: Only re-runs when providerTheme changes, not when wrapper element changes.
 	// This is intentional, as wrapperRef is expected to be stable for the lifetime of the provider.
+	// A remount is not a gap in that: effects always run on mount, so a new instance resolves
+	// against its own node. Only a node swap *within* one instance would go unseen, and the catalog
+	// is declared on the `.a8c-charts-scope` class rather than on a particular element, so the
+	// replacement carries the same computed values anyway.
 	useLayoutEffect( () => {
 		setIsColorPaletteResolved( false );
-		const { colors } = providerTheme;
 		const resolvedColors: string[] = [];
 		const hues: number[] = [];
 		const existingHslColors: Array< [ number, number, number ] > = [];
 		let minHue = 360;
 		let maxHue = 0;
 
-		// Process all colors once and cache the results
-		if ( Array.isArray( colors ) ) {
-			for ( const color of colors ) {
-				if ( color && typeof color === 'string' ) {
-					// Normalize color to hex format, handling CSS variables, RGB, HSL, etc.
-					// This uses normalizeColorToHex which resolves CSS variables and converts
-					// rgb(), rgba(), hsl() formats to hex
-					const normalizedColor = normalizeColorToHex(
-						color,
-						wrapperRef.current,
-						resolveCssVariable
-					);
-
-					// Only process valid hex colors
-					if ( normalizedColor.startsWith( '#' ) ) {
-						resolvedColors.push( normalizedColor );
-						const hslColor = d3Hsl( normalizedColor );
-						// d3Hsl returns NaN values for invalid colors
-						if ( ! isNaN( hslColor.h ) ) {
-							const hslTuple: [ number, number, number ] = [
-								hslColor.h,
-								hslColor.s * 100,
-								hslColor.l * 100,
-							];
-							hues.push( hslTuple[ 0 ] );
-							existingHslColors.push( hslTuple );
-							minHue = Math.min( minHue, hslTuple[ 0 ] );
-							maxHue = Math.max( maxHue, hslTuple[ 0 ] );
-						}
-					}
+		// Resolved from the theme rather than from `SERIES_PALETTE_POINTERS`, and it has to be. In a
+		// browser the two are equivalent — both name the same slots, and the wrapper's theme-layer
+		// vars answer either. But `withCatalogPointers` puts the consumer's own color in each
+		// pointer's terminal position, and that literal is the only carrier for the palette where
+		// `getComputedStyle` resolves nothing: SSR and jsdom. Walking the manifest instead makes
+		// every consumer palette collapse to the catalog seed there.
+		for ( const color of providerTheme.colors ?? SERIES_PALETTE_POINTERS ) {
+			// Normalize color to hex format, handling CSS variables, RGB, HSL, etc.
+			// This uses normalizeColorToHex which resolves CSS variables and converts
+			// rgb(), rgba(), hsl() formats to hex
+			const normalizedColor = normalizeColorToHex( color, wrapperRef.current, resolveCssVariable );
+
+			// Only process valid hex colors. An unset palette slot returns its own
+			// `var()` unchanged, so this is also what compacts the palette: slots the
+			// consumer never set drop out here and `getChartColor` generates past
+			// whatever survived.
+			if ( normalizedColor.startsWith( '#' ) ) {
+				resolvedColors.push( normalizedColor );
+				const hslColor = d3Hsl( normalizedColor );
+				// d3Hsl returns NaN values for invalid colors
+				if ( ! isNaN( hslColor.h ) ) {
+					const hslTuple: [ number, number, number ] = [
+						hslColor.h,
+						hslColor.s * 100,
+						hslColor.l * 100,
+					];
+					hues.push( hslTuple[ 0 ] );
+					existingHslColors.push( hslTuple );
+					minHue = Math.min( minHue, hslTuple[ 0 ] );
+					maxHue = Math.max( maxHue, hslTuple[ 0 ] );
 				}
 			}
 		}
@@ -153,11 +157,18 @@ export const GlobalChartsProvider: FC< GlobalChartsProviderProps > = ( { childre
 		() => new Map()
 	);
 
-	// Reset group color mappings when theme colors change
+	// Reset group color mappings when the resolved palette changes.
+	//
+	// Keyed on the resolved colors rather than on `providerTheme.colors`, which holds five
+	// catalog pointers and so does not move with a `theme.colors` change — a consumer's colors
+	// reach the palette through the theme-layer vars on the wrapper. Keying on content also stops
+	// a consumer passing an inline `theme` object from resetting the map on every render.
+	const paletteKey = colorCache.colors.join( ',' );
+
 	useEffect( () => {
 		// Create a completely new Map instance to trigger dependencies, e.g. useChartLegendItems
 		setGroupToColorMap( new Map() );
-	}, [ providerTheme.colors ] );
+	}, [ paletteKey ] );
 
 	const registerChart = useCallback( ( id: string, data: ChartRegistration ) => {
 		setCharts( prev => new Map( prev ).set( id, data ) );

package/src/providers/chart-context/private/series-palette.ts

@@ -0,0 +1,45 @@
+/**
+ * The series palette's slot manifest.
+ *
+ * Which slots exist is a fact about the catalog `chart-scope.scss` emits, not a theme value, so it
+ * is declared here rather than in `themes.ts`, which now derives `defaultTheme.colors` from it.
+ *
+ * That is as far as the separation goes, and the limit is worth knowing before the field is
+ * deleted. `GlobalChartsProvider` still resolves `providerTheme.colors`, not this manifest,
+ * because `withCatalogPointers` parks the consumer's own color in each pointer's terminal position
+ * and that literal is the palette's only carrier where `getComputedStyle` resolves nothing — SSR
+ * and jsdom. Swapping the provider onto this manifest passes in a browser and collapses every
+ * consumer palette to the catalog seed under jsdom; 24 tests say so. Removing `colors` therefore
+ * needs a different home for that literal first, not just a change of source here.
+ */
+
+/** How many series-palette slots the catalog emits. `theme.colors` entries past this are ignored. */
+export const SERIES_SLOT_COUNT = 5;
+
+/**
+ * The catalog role holding one series-palette slot.
+ *
+ * @param slot - The one-based slot number.
+ * @return The role name.
+ */
+export const seriesRole = ( slot: number ): string => `--a8c-charts-color-series-${ slot }`;
+
+/*
+ * Only slot 1 carries a terminal literal, and it is reached only where `getComputedStyle` resolves
+ * nothing — SSR and jsdom. The rest resolve to nothing until a consumer sets them, and the provider
+ * drops what resolves to nothing, so the palette compacts rather than repeating one color.
+ *
+ * The literal matches slot 1's own last-resort fallback in `chart-scope.scss`. It is deliberately
+ * the bare hex rather than that slot's full `var()` chain: this string is resolved against the DOM,
+ * where the chain has already been walked, and is only read at all when no DOM answered.
+ */
+const SERIES_SLOT_1_FALLBACK = '#3858e9';
+
+/** The catalog pointer for every slot, in slot order. */
+export const SERIES_PALETTE_POINTERS: readonly string[] = Array.from(
+	{ length: SERIES_SLOT_COUNT },
+	( _, index ) =>
+		index === 0
+			? `var(${ seriesRole( 1 ) }, ${ SERIES_SLOT_1_FALLBACK })`
+			: `var(${ seriesRole( index + 1 ) })`
+);

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

@@ -1,6 +1,15 @@
+import { SERIES_SLOT_COUNT, seriesRole } from './series-palette';
 import type { ChartTheme } from '../../../types';
 
+/*
+ * `process.env.NODE_ENV` is replaced by the bundler at build time. Declare a
+ * minimal `process` locally so this file type-checks as source under `jetpack:src`.
+ */
+declare const process: { env: Record< string, string | undefined > };
+
 // 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.
+//
+// `theme.colors` is the one field mapped by position rather than by name: entry N publishes slot N+1, which is what makes it sugar over the five slots rather than a second palette with its own precedence.
 const ROLE_FOR_FIELD: Array< [ string, ( theme: Partial< ChartTheme > ) => string | undefined ] > =
 	[
 		[ '--a8c-charts-color-background', theme => theme.backgroundColor ],
@@ -8,8 +17,37 @@ const ROLE_FOR_FIELD: Array< [ string, ( theme: Partial< ChartTheme > ) => strin
 		[ '--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 ],
+		[ '--a8c-charts-color-label-background', theme => theme.labelBackgroundColor ],
+		[ '--a8c-charts-color-label-on-fill', theme => theme.labelTextColor ],
+		...Array.from(
+			{ length: SERIES_SLOT_COUNT },
+			( _, index ): [ string, ( theme: Partial< ChartTheme > ) => string | undefined ] => [
+				seriesRole( index + 1 ),
+				theme => theme.colors?.[ index ],
+			]
+		),
 	];
 
+let warnedAboutExtraColors = false;
+
+/**
+ * Warns once when a consumer passes more colors than there are slots to publish them into.
+ *
+ * @param count - How many entries `theme.colors` holds.
+ */
+function warnOnceAboutExtraColors( count: number ): void {
+	if ( warnedAboutExtraColors || process.env.NODE_ENV === 'production' ) {
+		return;
+	}
+
+	warnedAboutExtraColors = true;
+	// eslint-disable-next-line no-console
+	console.warn(
+		`[Charts] theme.colors holds ${ count } colors and the palette has ${ SERIES_SLOT_COUNT } slots, so entries past the ${ SERIES_SLOT_COUNT }th are ignored. ` +
+			'Set a per-series color with `options.stroke` instead.'
+	);
+}
+
 /**
  * The variable a `theme` prop override is published as, one layer outside the role itself.
  *
@@ -26,7 +64,7 @@ export const THEME_LAYERED_ROLES: readonly string[] = ROLE_FOR_FIELD.map( ( [ ro
 /**
  * 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`.
+ * 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 color. 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:
  *
@@ -54,10 +92,12 @@ export type ThemeOverrides = {
 };
 
 /**
- * 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.
+ * Maps a sparse consumer theme onto the theme-layer variables its overridden catalog roles read, so CSS-painted and JS-resolved colors 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.
  *
+ * `theme.colors` publishes through the same mechanism, one slot per entry, so a CSS declaration of `--a8c-charts-color-series-N` still beats it and a short array leaves the later slots unset rather than blank.
+ *
  * @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.
  */
@@ -66,6 +106,10 @@ export const themeOverrideVars = ( theme?: Partial< ChartTheme > ): ThemeOverrid
 		return { vars: {}, roles: [] };
 	}
 
+	if ( Array.isArray( theme.colors ) && theme.colors.length > SERIES_SLOT_COUNT ) {
+		warnOnceAboutExtraColors( theme.colors.length );
+	}
+
 	const vars: Record< string, string > = {};
 	const roles: string[] = [];
 

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

@@ -1,11 +1,50 @@
 import { defaultTheme } from '../themes';
+import { SERIES_PALETTE_POINTERS, SERIES_SLOT_COUNT, seriesRole } from './series-palette';
 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.
+/**
+ * The pointer one palette slot is restored to.
+ *
+ * Unlike the other roles, this keeps the consumer's own color as the pointer's terminal literal instead of the catalog's. The literal is only ever reached where `getComputedStyle` resolves nothing — SSR and jsdom — and there the palette is the one field where falling back to the catalog default would be visible: every series would paint the same seeded blue. In a browser the slot resolves first, so a CSS declaration of it still outranks the consumer's `theme.colors`.
+ *
+ * @param index - The slot's zero-based index in `colors`.
+ * @param value - The merged theme's entry for it.
+ * @return The catalog pointer for that slot.
+ */
+const seriesPointer = ( index: number, value: string | undefined ): string => {
+	const role = seriesRole( index + 1 );
+
+	// Idempotent: `withCatalogPointers` runs this once per overridden slot, so from the second call on the array already holds pointers.
+	if ( typeof value === 'string' && value.startsWith( `var(${ role }` ) ) {
+		return value;
+	}
+
+	// A slot the consumer left empty keeps the catalog's own pointer, so a CSS declaration of it still reaches the palette.
+	if ( typeof value !== 'string' || value === '' ) {
+		return SERIES_PALETTE_POINTERS[ index ];
+	}
+
+	return `var(${ role }, ${ value })`;
+};
+
+// Restores each overridden role's mapped theme field to the catalog pointer already written for it — `defaultTheme` for the ordinary roles, `series-palette.ts` for the palette slots — so the value comes from the one place that declares it rather than a second, hand-copied literal.
+//
+// Every series slot restores the whole `colors` array, not just its own entry. `mergeThemes` replaces arrays outright, so a consumer passing two colors would otherwise leave a two-entry palette and put slots 3 to 5 out of reach of a CSS declaration that sets them.
 const CATALOG_RESTORE_FOR_ROLE: Record<
 	string,
 	( theme: CompleteChartTheme ) => Partial< CompleteChartTheme >
 > = {
+	// Each of the five entries rebuilds the whole array, so a consumer overriding every slot runs this five times. That is deliberate rather than merely tolerated: `seriesPointer` is idempotent, so every pass after the first is a no-op, and five allocations of a five-element array is not worth a special case in a map that is otherwise one entry per role.
+	...Object.fromEntries(
+		Array.from( { length: SERIES_SLOT_COUNT }, ( _, index ) => [
+			seriesRole( index + 1 ),
+			( theme: CompleteChartTheme ) => ( {
+				colors: SERIES_PALETTE_POINTERS.map( ( _pointer, slot ) =>
+					seriesPointer( slot, theme.colors?.[ slot ] )
+				),
+			} ),
+		] )
+	),
 	'--a8c-charts-color-background': () => ( { backgroundColor: defaultTheme.backgroundColor } ),
 	'--a8c-charts-color-grid': theme => ( {
 		gridStyles: { ...theme.gridStyles, stroke: defaultTheme.gridStyles.stroke },
@@ -19,6 +58,10 @@ const CATALOG_RESTORE_FOR_ROLE: Record<
 	'--a8c-charts-color-label-axis': theme => ( {
 		svgLabelSmall: { ...theme.svgLabelSmall, fill: defaultTheme.svgLabelSmall.fill },
 	} ),
+	'--a8c-charts-color-label-background': () => ( {
+		labelBackgroundColor: defaultTheme.labelBackgroundColor,
+	} ),
+	'--a8c-charts-color-label-on-fill': () => ( { labelTextColor: defaultTheme.labelTextColor } ),
 };
 
 /**
@@ -26,7 +69,7 @@ const CATALOG_RESTORE_FOR_ROLE: Record<
  *
  * 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.
+ * Every field outside the 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`.

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

@@ -20,16 +20,30 @@ describe( 'defaultTheme', () => {
 		expect( strings.filter( value => value.includes( '--wpds-' ) ) ).toEqual( [] );
 	} );
 
-	it( 'points every themed colour at an --a8c-charts-* catalog role', () => {
+	it( 'points every themed color 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 );
 	} );
 
+	// The palette slots past the first are the exception, below: a terminal literal there would be a color nobody chose.
 	it( 'gives every catalog pointer a terminal literal for the SSR and jsdom paths', () => {
-		const varStrings = strings.filter( value => value.startsWith( 'var(--a8c-charts-' ) );
+		const varStrings = strings
+			.filter( value => value.startsWith( 'var(--a8c-charts-' ) )
+			.filter( value => ! /^var\( *--a8c-charts-color-series-[2-9] *\)$/.test( value ) );
 
 		expect( varStrings.every( value => value.includes( ',' ) ) ).toBe( true );
 	} );
+
+	// Only slot 1 seeds a palette. The rest resolve to nothing until a consumer sets them, and the provider drops what resolves to nothing, so the palette compacts instead of repeating one color.
+	it( 'leaves the palette slots past the first with no default of their own', () => {
+		expect( defaultTheme.colors ).toEqual( [
+			'var(--a8c-charts-color-series-1, #3858e9)',
+			'var(--a8c-charts-color-series-2)',
+			'var(--a8c-charts-color-series-3)',
+			'var(--a8c-charts-color-series-4)',
+			'var(--a8c-charts-color-series-5)',
+		] );
+	} );
 } );