@automattic/charts 3.1.0 → 3.2.0

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

@@ -500,6 +500,57 @@ describe( 'LineChart', () => {
 			expect( ticks.length ).toBeGreaterThan( 1 );
 		} );
 
+		test( 'keeps the derived month formatter when tickFormat is passed as undefined.', () => {
+			renderWithTheme( {
+				width: 800,
+				options: { axis: { x: { tickFormat: undefined } } },
+				data: [
+					{
+						label: 'Series A',
+						data: [
+							{ date: new Date( '2024-01-01' ), value: 10 },
+							{ date: new Date( '2024-04-01' ), value: 20 },
+							{ date: new Date( '2024-07-01' ), value: 30 },
+							{ date: new Date( '2024-10-01' ), value: 40 },
+							{ date: new Date( '2025-03-01' ), value: 50 },
+						],
+					},
+				],
+			} );
+
+			// January is absent: formatMonthOrYearTick renders it as the year instead.
+			const ticks = screen.getAllByText( /^(Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)$/ );
+			expect( ticks.length ).toBeGreaterThan( 1 );
+			expect(
+				screen.queryByText( /^(February|March|April|June|July|August|September|October)$/ )
+			).not.toBeInTheDocument();
+		} );
+
+		test( 'honors an explicit tickFormat over the derived formatter.', () => {
+			renderWithTheme( {
+				width: 800,
+				options: {
+					axis: {
+						x: {
+							tickFormat: ( date: Date | number ) =>
+								`tick-${ new Date( Number( date ) ).getUTCMonth() }`,
+						},
+					},
+				},
+				data: [
+					{
+						label: 'Series A',
+						data: [
+							{ date: new Date( '2024-01-01' ), value: 10 },
+							{ date: new Date( '2024-07-01' ), value: 30 },
+						],
+					},
+				],
+			} );
+
+			expect( screen.getAllByText( /^tick-\d+$/ ).length ).toBeGreaterThan( 0 );
+		} );
+
 		test( 'renders ticks in year format.', () => {
 			renderWithTheme( {
 				width: 800,
@@ -1102,6 +1153,53 @@ describe( 'LineChart', () => {
 			} );
 		} );
 
+		describe( 'Activation', () => {
+			const SERIES_A = {
+				label: 'Series A',
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 10 },
+					{ date: new Date( '2024-01-02' ), value: 20 },
+				],
+				options: {},
+			};
+			const SERIES_B = {
+				label: 'Series B',
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 15 },
+					{ date: new Date( '2024-01-02' ), value: 25 },
+				],
+				options: {},
+			};
+
+			// Navigation steps through x positions; the first series names the point.
+			test( 'Enter hands the selected point to onDatumActivate', async () => {
+				const user = userEvent.setup();
+				const onDatumActivate = jest.fn();
+				renderWithTheme( { data: [ SERIES_A, SERIES_B ], onDatumActivate } );
+
+				screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+				await user.keyboard( '{ArrowRight}{ArrowRight}{Enter}' );
+
+				expect( onDatumActivate ).toHaveBeenCalledTimes( 1 );
+				expect( onDatumActivate ).toHaveBeenCalledWith( {
+					datum: SERIES_A.data[ 1 ],
+					index: 1,
+					key: 'Series A',
+				} );
+			} );
+
+			test( 'Enter with no point selected activates nothing', async () => {
+				const user = userEvent.setup();
+				const onDatumActivate = jest.fn();
+				renderWithTheme( { data: [ SERIES_A ], onDatumActivate } );
+
+				screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+				await user.keyboard( '{Enter}' );
+
+				expect( onDatumActivate ).not.toHaveBeenCalled();
+			} );
+		} );
+
 		describe( 'Arrow Key Navigation', () => {
 			test( 'right arrow key navigates to next data point', async () => {
 				const user = userEvent.setup();

package/src/charts/sparkline/sparkline.tsx

@@ -1,6 +1,6 @@
 import clsx from 'clsx';
-import { useMemo, forwardRef } from 'react';
-import { useGlobalChartsTheme } from '../../providers';
+import { useContext, useMemo, forwardRef } from 'react';
+import { GlobalChartsContext, useGlobalChartsTheme } from '../../providers';
 import { LineChartUnresponsive } from '../line-chart';
 import { withResponsive } from '../private/with-responsive';
 import styles from './sparkline.module.scss';
@@ -60,6 +60,9 @@ const SparklineComponent = forwardRef< HTMLDivElement, SparklineProps >(
 		ref
 	) => {
 		const theme = useGlobalChartsTheme();
+		// Read through the context rather than `useGlobalChartsContext()`, which throws: Sparkline
+		// renders standalone too, and only the LineChart it delegates to supplies a provider.
+		const chartsContext = useContext( GlobalChartsContext );
 
 		// Get theme defaults for sparkline
 		const themeStrokeWidth = theme.sparkline?.strokeWidth ?? 1.5;
@@ -127,7 +130,10 @@ const SparklineComponent = forwardRef< HTMLDivElement, SparklineProps >(
 		if ( data.length === 1 ) {
 			const cx = width / 2;
 			const cy = height / 2;
-			const resolvedColor = color || '#000000';
+			// The multi-point path lets LineChart resolve the palette; a lone circle has to ask for
+			// the same slot itself, or omitting `color` paints black instead of the series color.
+			const resolvedColor =
+				color || chartsContext?.getElementStyles( { index: 0 } ).color || '#000000';
 
 			return (
 				<div

package/src/charts/sparkline/types.ts

@@ -47,7 +47,7 @@ export interface SparklineProps {
 
 	/**
 	 * Color for the line stroke (hex or CSS color)
-	 * @default Theme color (first color in theme.colors array)
+	 * @default The first series palette color (`--a8c-charts-color-series-1`)
 	 */
 	color?: string;
 

package/src/components/tooltip/accessible-tooltip.tsx

@@ -1,7 +1,10 @@
 import { Tooltip, TooltipContext } from '@visx/xychart';
 import clsx from 'clsx';
 import { useContext, useEffect, useCallback, useMemo, useRef } from 'react';
+import { useGlobalChartsTheme } from '../../providers';
+import { useChartScopeElement } from '../../providers/chart-scope';
 import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
+import { resolveCssVariable } from '../../utils';
 import type { SeriesData, DataPointDate } from '../../types';
 import type { RenderTooltipParams, XyChartTooltipProps } from '../../visx/types';
 import type { ReactNode } from 'react';
@@ -45,9 +48,21 @@ export const AccessibleTooltip: React.FC< AccessibleTooltipProps > = ( {
 	keyboardFocusedClassName,
 	series = [],
 	mode = 'group',
+	verticalCrosshairStyle,
+	horizontalCrosshairStyle,
 	...props
 } ) => {
 	const tooltipContext = useContext( TooltipContext );
+	const scopeElement = useChartScopeElement();
+	const gridStroke = useGlobalChartsTheme().gridStyles?.stroke;
+
+	// The crosshair is painted in a portal outside the scope, so it needs a resolved color; see TOKENS.md#the-svg-bridge.
+	const crosshairStroke = useMemo( () => {
+		const stroke = gridStroke ? resolveCssVariable( gridStroke, scopeElement ) : null;
+
+		// Passing `stroke: undefined` would erase the crosshair: it overrides visx's own value, and SVG's initial `stroke` is `none`.
+		return stroke ? { stroke } : undefined;
+	}, [ gridStroke, scopeElement ] );
 
 	const tooltipData = useMemo( () => {
 		if ( mode !== 'individual' ) return [];
@@ -158,7 +173,14 @@ export const AccessibleTooltip: React.FC< AccessibleTooltipProps > = ( {
 		};
 	}, [ renderTooltip, selectedIndex, tooltipRef, keyboardFocusedClassName ] );
 
-	return <Tooltip { ...props } renderTooltip={ focusableRenderTooltip } />;
+	return (
+		<Tooltip
+			{ ...props }
+			verticalCrosshairStyle={ { ...crosshairStroke, ...verticalCrosshairStyle } }
+			horizontalCrosshairStyle={ { ...crosshairStroke, ...horizontalCrosshairStyle } }
+			renderTooltip={ focusableRenderTooltip }
+		/>
+	);
 };
 
 // Keyboard navigation hook for charts
@@ -172,6 +194,11 @@ interface UseKeyboardNavigationProps {
 	 * Total number of navigation points (length of tooltip data array)
 	 */
 	totalPoints: number;
+	/**
+	 * Called with the selected index on Enter or Space, so a chart can treat the
+	 * keyboard selection the way it treats a click.
+	 */
+	onActivate?: ( index: number ) => void;
 }
 
 export const useKeyboardNavigation = ( {
@@ -181,6 +208,7 @@ export const useKeyboardNavigation = ( {
 	setIsNavigating,
 	chartRef,
 	totalPoints,
+	onActivate,
 }: UseKeyboardNavigationProps ) => {
 	// Focus the tooltip as soon as it is rendered
 	const tooltipRef = useCallback(
@@ -237,9 +265,11 @@ export const useKeyboardNavigation = ( {
 				setSelectedIndex( undefined );
 				setIsNavigating( false );
 				chartRef.current?.focus();
+			} else if ( ( event.key === 'Enter' || event.key === ' ' ) && selectedIndex !== undefined ) {
+				onActivate?.( selectedIndex );
 			}
 		},
-		[ totalPoints, selectedIndex, setSelectedIndex, setIsNavigating, chartRef ]
+		[ totalPoints, selectedIndex, setSelectedIndex, setIsNavigating, chartRef, onActivate ]
 	);
 
 	return {

package/src/components/tooltip/test/accessible-tooltip.test.tsx

@@ -0,0 +1,68 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { LineChartUnresponsive } from '../../../charts/line-chart/line-chart';
+import { GlobalChartsProvider } from '../../../providers';
+import { ChartScopeContext } from '../../../providers/chart-scope';
+import type { ReactNode } from 'react';
+
+// A real chart is the harness rather than the subject: the crosshairs render only once visx has a data context and an open tooltip. The unresponsive export is what lets the test own the scope element — `withResponsive` otherwise provides its own wrapper as the scope.
+const renderChart = ( scope?: HTMLElement ) => {
+	const chart = (
+		<LineChartUnresponsive
+			width={ 500 }
+			height={ 300 }
+			data={ [
+				{
+					label: 'Series A',
+					data: [
+						{ date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' },
+						{ date: new Date( '2024-01-02' ), value: 20, label: 'Jan 2' },
+					],
+					options: {},
+				},
+			] }
+			withTooltips
+			withTooltipCrosshairs={ { showVertical: true } }
+			withGradientFill={ false }
+		/>
+	);
+
+	const scoped: ReactNode = scope ? (
+		<ChartScopeContext.Provider value={ scope }>{ chart }</ChartScopeContext.Provider>
+	) : (
+		chart
+	);
+
+	return render( <GlobalChartsProvider>{ scoped }</GlobalChartsProvider> );
+};
+
+const openTooltip = async () => {
+	const user = userEvent.setup();
+
+	screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+	await user.keyboard( '{ArrowRight}' );
+
+	// eslint-disable-next-line testing-library/no-node-access -- visx owns the crosshair and hardcodes its class name, so there is no attribute to reach it by.
+	return document.querySelector( '.visx-crosshair-vertical line' );
+};
+
+describe( 'AccessibleTooltip', () => {
+	// The crosshair is painted in a portal outside the scope element; see TOKENS.md#the-svg-bridge.
+	it( 'reads the grid role from the scope element', async () => {
+		const scope = document.createElement( 'div' );
+		scope.style.setProperty( '--a8c-charts-color-grid', 'rgb(1, 2, 3)' );
+		document.body.appendChild( scope );
+
+		renderChart( scope );
+
+		await expect( openTooltip() ).resolves.toHaveAttribute( 'stroke', 'rgb(1, 2, 3)' );
+
+		document.body.removeChild( scope );
+	} );
+
+	it( 'falls back to the catalog default when the role is unset', async () => {
+		renderChart();
+
+		await expect( openTooltip() ).resolves.toHaveAttribute( 'stroke', '#dbdbdb' );
+	} );
+} );

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 ) );