@automattic/charts 3.2.0 → 4.1.0

package/src/utils/test/get-edge-tick-widths.test.ts

@@ -0,0 +1,55 @@
+import { getEdgeTickWidths } from '../get-edge-tick-widths';
+
+const mockGetStringWidth = jest.fn();
+jest.mock( '@visx/text', () => ( {
+	...jest.requireActual( '@visx/text' ),
+	getStringWidth: ( ...args: unknown[] ) => mockGetStringWidth( ...args ),
+} ) );
+
+describe( 'getEdgeTickWidths', () => {
+	beforeEach( () => {
+		mockGetStringWidth.mockReset();
+		mockGetStringWidth.mockImplementation( ( label: string ) => label.length );
+	} );
+
+	it( 'measures the formatted first and last ticks', () => {
+		const style = { fontSize: 11 };
+
+		const widths = getEdgeTickWidths( [ 1, 2, 3 ], value => `tick-${ value }`, style );
+
+		expect( widths ).toEqual( { first: 6, last: 6 } );
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( 'tick-1', style );
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( 'tick-3', style );
+	} );
+
+	it( 'passes each tick its own index', () => {
+		getEdgeTickWidths( [ 'a', 'b', 'c' ], ( value, index ) => `${ index }:${ value }` );
+
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( '0:a', undefined );
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( '2:c', undefined );
+	} );
+
+	it( 'measures a single tick as both edges', () => {
+		expect( getEdgeTickWidths( [ 42 ], value => `${ value }` ) ).toEqual( { first: 2, last: 2 } );
+	} );
+
+	it( 'measures the raw value when there is no formatter', () => {
+		getEdgeTickWidths( [ 'abcd' ] );
+
+		expect( mockGetStringWidth ).toHaveBeenCalledWith( 'abcd', undefined );
+	} );
+
+	it( 'returns nothing to reserve for an axis with no ticks', () => {
+		expect( getEdgeTickWidths( [] ) ).toEqual( { first: 0, last: 0 } );
+		expect( mockGetStringWidth ).not.toHaveBeenCalled();
+	} );
+
+	it( 'reserves nothing for a label the measurer cannot size', () => {
+		mockGetStringWidth.mockReturnValue( null );
+
+		expect( getEdgeTickWidths( [ 1, 2, 3 ], value => `tick-${ value }` ) ).toEqual( {
+			first: 0,
+			last: 0,
+		} );
+	} );
+} );

package/src/utils/test/get-styles.test.ts

@@ -13,8 +13,11 @@ describe( 'Series styling utility functions', () => {
 		options: {},
 	};
 
+	// `getSeriesStroke` takes the resolved palette as an argument rather than reading it
+	// off the theme, so this is a plain array of colors.
+	const palette = [ '#FF0000', '#00FF00', '#0000FF' ];
+
 	const mockTheme: Partial< ChartTheme > = {
-		colors: [ '#FF0000', '#00FF00', '#0000FF' ],
 		lineChart: {
 			lineStyles: {
 				comparison: {
@@ -40,17 +43,17 @@ describe( 'Series styling utility functions', () => {
 				options: { stroke: '#CUSTOM' },
 			};
 
-			const result = getSeriesStroke( seriesWithStroke, 0, mockTheme.colors );
+			const result = getSeriesStroke( seriesWithStroke, 0, palette );
 			expect( result ).toBe( '#CUSTOM' );
 		} );
 
-		it( 'returns theme color by index when no custom stroke', () => {
-			const result = getSeriesStroke( mockSeriesData, 1, mockTheme.colors );
+		it( 'returns the palette color by index when no custom stroke', () => {
+			const result = getSeriesStroke( mockSeriesData, 1, palette );
 			expect( result ).toBe( '#00FF00' ); // Second color
 		} );
 
-		it( 'wraps around theme colors when index exceeds array length', () => {
-			const result = getSeriesStroke( mockSeriesData, 5, mockTheme.colors );
+		it( 'wraps around the palette when index exceeds its length', () => {
+			const result = getSeriesStroke( mockSeriesData, 5, palette );
 			expect( result ).toBe( '#0000FF' ); // 5 % 3 = 2, third color
 		} );
 	} );
@@ -92,7 +95,7 @@ describe( 'Series styling utility functions', () => {
 		} );
 
 		it( 'returns empty object when no styles available', () => {
-			const themeWithoutStyles = { colors: [ '#FF0000' ] } as ChartTheme;
+			const themeWithoutStyles = { tickLength: 4 } as ChartTheme;
 			const result = getSeriesLineStyles( mockSeriesData, 0, themeWithoutStyles );
 			expect( result ).toEqual( {} );
 		} );

package/src/utils/test/merge-themes.test.ts

@@ -3,33 +3,24 @@ import type { ChartTheme } from '../../types';
 
 describe( 'mergeThemes', () => {
 	const baseTheme: ChartTheme = {
-		backgroundColor: '#FFFFFF',
-		colors: [ '#red', '#blue' ],
 		gridStyles: {
-			stroke: '#DCDCDE',
 			strokeWidth: 1,
 		},
 		tickLength: 4,
-		gridColor: '',
-		gridColorDark: '',
-		leaderboardChart: {
-			primaryColor: '#global-primary',
-			secondaryColor: '#global-secondary',
+		seriesLineStyles: [ { strokeWidth: 1 }, { strokeWidth: 2 } ],
+		sparkline: {
+			strokeWidth: 1.5,
+			margin: { top: 2, right: 2, bottom: 2, left: 2 },
 		},
 	};
 
 	const overrideTheme: ChartTheme = {
-		backgroundColor: '#F0F0F0',
-		colors: [ '#green', '#yellow' ],
 		gridStyles: {
-			stroke: '#000000',
 			strokeWidth: 2,
 		},
 		tickLength: 8,
-		gridColor: '',
-		gridColorDark: '',
-		leaderboardChart: {
-			primaryColor: '#local-primary',
+		sparkline: {
+			strokeWidth: 3,
 		},
 	};
 
@@ -41,60 +32,41 @@ describe( 'mergeThemes', () => {
 	it( 'should merge themes with local theme taking precedence for top-level properties', () => {
 		const result = mergeThemes( baseTheme, overrideTheme );
 
-		expect( result.backgroundColor ).toBe( '#F0F0F0' ); // from local
-		expect( result.tickLength ).toBe( 8 ); // from local
-		expect( result.colors ).toEqual( [ '#green', '#yellow' ] ); // from local (array replacement)
+		expect( result.tickLength ).toBe( 8 );
 	} );
 
 	it( 'should deeply merge nested objects with local theme taking precedence', () => {
 		const result = mergeThemes( baseTheme, overrideTheme );
 
-		// gridStyles should be merged
-		expect( result.gridStyles ).toEqual( {
-			stroke: '#000000', // from local
-			strokeWidth: 2, // from local
-		} );
+		expect( result.gridStyles ).toEqual( { strokeWidth: 2 } );
 
-		// leaderboardChart should be merged
-		expect( result.leaderboardChart ).toEqual( {
-			primaryColor: '#local-primary', // from local
-			secondaryColor: '#global-secondary', // from global (not overridden)
+		expect( result.sparkline ).toEqual( {
+			strokeWidth: 3, // from local
+			margin: { top: 2, right: 2, bottom: 2, left: 2 }, // from global (not overridden)
 		} );
 	} );
 
 	it( 'should use global theme properties when not defined in local theme', () => {
 		const partialLocalTheme: ChartTheme = {
-			backgroundColor: '#F0F0F0',
-			colors: [ '#green' ],
 			tickLength: 8,
-			gridColor: '',
-			gridColorDark: '',
 		};
 
 		const result = mergeThemes( baseTheme, partialLocalTheme );
 
-		expect( result.backgroundColor ).toBe( '#F0F0F0' ); // from local
-		expect( result.gridStyles ).toEqual( baseTheme.gridStyles ); // from global
-		expect( result.leaderboardChart ).toEqual( baseTheme.leaderboardChart ); // from global
+		expect( result.tickLength ).toBe( 8 );
+		expect( result.gridStyles ).toEqual( baseTheme.gridStyles );
+		expect( result.leaderboardChart ).toEqual( baseTheme.leaderboardChart );
 	} );
 
 	it( 'should handle array replacement correctly', () => {
-		const globalWithColors: ChartTheme = {
-			...baseTheme,
-			colors: [ '#red', '#blue', '#purple' ],
-		};
-
-		const localWithFewerColors: ChartTheme = {
+		const localWithFewerStyles: ChartTheme = {
 			...overrideTheme,
-			colors: [ '#green' ],
+			seriesLineStyles: [ { strokeWidth: 5 } ],
 		};
 
-		const result = mergeThemes( globalWithColors, localWithFewerColors );
+		const result = mergeThemes( baseTheme, localWithFewerStyles );
 
 		// Arrays should be replaced, not concatenated
-		expect( result.colors ).toEqual( [ '#green' ] );
-		expect( result.colors ).not.toContain( '#red' );
-		expect( result.colors ).not.toContain( '#blue' );
-		expect( result.colors ).not.toContain( '#purple' );
+		expect( result.seriesLineStyles ).toEqual( [ { strokeWidth: 5 } ] );
 	} );
 } );

package/src/utils/warn-once.ts

@@ -0,0 +1,23 @@
+/**
+ * `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 > };
+
+const warned = new Set< string >();
+
+/**
+ * Warns about a host-supplied value once per process, and never in production.
+ *
+ * @param key     - Identifies the value, so a bad prop on every point warns once.
+ * @param message - What the host got wrong and what happens instead.
+ */
+export const warnOnce = ( key: string, message: string ): void => {
+	if ( warned.has( key ) || process.env.NODE_ENV === 'production' ) {
+		return;
+	}
+
+	warned.add( key );
+	// eslint-disable-next-line no-console
+	console.warn( `[Charts] ${ message }` );
+};

package/src/visx/types.ts

@@ -1,7 +1,7 @@
 import type { PickD3Scale } from '@visx/scale';
 import type { TooltipProps as VisxTooltipProps, UseTooltipPortalOptions } from '@visx/tooltip';
 import type { GlyphProps, TooltipContextType } from '@visx/xychart';
-import type { ReactNode, SVGProps } from 'react';
+import type { CSSProperties, ReactNode, SVGProps } from 'react';
 
 export type RenderTooltipParams< Datum extends object > = TooltipContextType< Datum > & {
 	colorScale?: PickD3Scale< 'ordinal', string, string >;
@@ -12,20 +12,71 @@ export interface RenderTooltipGlyphProps< Datum extends object > extends GlyphPr
 	isNearestDatum: boolean;
 }
 
+export type TooltipPlacement = 'auto' | 'below-axis';
+
+type CrosshairPaintProperty =
+	| 'stroke'
+	| 'strokeWidth'
+	| 'strokeOpacity'
+	| 'strokeDasharray'
+	| 'strokeLinecap'
+	| 'opacity';
+
+export type CrosshairStyle = Pick< SVGProps< SVGLineElement >, CrosshairPaintProperty > & {
+	className?: string;
+	style?: Pick< CSSProperties, CrosshairPaintProperty >;
+};
+
 export type XyChartTooltipProps< Datum extends object > = {
 	renderTooltip: ( params: RenderTooltipParams< Datum > ) => ReactNode;
 	renderGlyph?: ( params: RenderTooltipGlyphProps< Datum > ) => ReactNode;
+	/**
+	 * Keep the panel below the x-axis label band, centered at the datum x and horizontally clamped.
+	 * Vertical bounds do not move this placement; clipping ancestors can still cut it off.
+	 * @default 'auto'
+	 */
+	tooltipPlacement?: TooltipPlacement;
+	/** Merge overrides with the default box styles; use `unstyled` to strip the box styling. */
+	style?: VisxTooltipProps[ 'style' ];
 	snapTooltipToDatumX?: boolean;
 	snapTooltipToDatumY?: boolean;
 	showVerticalCrosshair?: boolean;
 	showHorizontalCrosshair?: boolean;
 	showDatumGlyph?: boolean;
 	showSeriesGlyphs?: boolean;
-	verticalCrosshairStyle?: SVGProps< SVGLineElement >;
-	horizontalCrosshairStyle?: SVGProps< SVGLineElement >;
+	verticalCrosshairStyle?: CrosshairStyle;
+	horizontalCrosshairStyle?: CrosshairStyle;
 	glyphStyle?: SVGProps< SVGCircleElement >;
+	/**
+	 * Flip and clamp the tooltip box so it stays inside the nearest ancestor
+	 * that clips its overflow, or the viewport when there is none. The box may
+	 * leave the chart wrapper. (It used to keep a body-level portal inside the
+	 * viewport.)
+	 * Ignored by `below-axis`.
+	 * @default true
+	 */
+	detectBounds?: boolean;
+	/**
+	 * Stacking order of the tooltip box inside the chart wrapper, which isolates
+	 * its stacking context: the value never competes with page chrome outside
+	 * the chart.
+	 * @default 3
+	 */
+	zIndex?: number;
+	/**
+	 * @deprecated Accepted and ignored. The box renders inside the chart wrapper
+	 * and moves with it, so it needs no scroll tracking.
+	 */
+	scroll?: boolean;
+	/**
+	 * @deprecated Accepted and ignored. Nothing measures the box any more, so
+	 * there is no measurement to debounce.
+	 */
+	debounce?: number;
+	/**
+	 * @deprecated Accepted and ignored. No ResizeObserver is used.
+	 */
 	resizeObserverPolyfill?: UseTooltipPortalOptions[ 'polyfill' ];
-} & Omit< VisxTooltipProps, 'left' | 'top' | 'children' > &
-	Pick< UseTooltipPortalOptions, 'debounce' | 'detectBounds' | 'scroll' | 'zIndex' >;
+} & Omit< VisxTooltipProps, 'left' | 'top' | 'children' | 'applyPositionStyle' >;
 
 export type { LineStyles, GridStyles } from '@visx/xychart';

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

@@ -1,28 +0,0 @@
-import { renderHook } from '@testing-library/react';
-import { GlobalChartsProvider } from '../../providers/chart-context/global-charts-provider';
-import { ChartScopeContext } from '../../providers/chart-scope';
-import { useXYChartTheme } from '../use-xychart-theme';
-import type { ReactNode } from 'react';
-
-// A `theme` prop override reaches CSS-painted elements through the inline `--a8c-charts-*` var GlobalChartsProvider writes on its wrapper, and reaches 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-background', '#00ff00' );
-		document.body.appendChild( nestedOverride );
-
-		const wrapper = ( { children }: { children: ReactNode } ) => (
-			<GlobalChartsProvider theme={ { backgroundColor: 'rgb(255,0,0)' } }>
-				<ChartScopeContext.Provider value={ nestedOverride }>
-					{ children }
-				</ChartScopeContext.Provider>
-			</GlobalChartsProvider>
-		);
-
-		const { result } = renderHook( () => useXYChartTheme( [] ), { wrapper } );
-
-		expect( result.current.backgroundColor ).toBe( '#00ff00' );
-
-		document.body.removeChild( nestedOverride );
-	} );
-} );

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

@@ -1,131 +0,0 @@
-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 ],
-		[ '--a8c-charts-color-grid', theme => theme.gridStyles?.stroke ],
-		[ '--a8c-charts-color-axis', theme => theme.xAxisLineStyles?.stroke ],
-		[ '--a8c-charts-color-tick', theme => theme.xTickLineStyles?.stroke ],
-		[ '--a8c-charts-color-label-axis', theme => theme.svgLabelSmall?.fill ],
-		[ '--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.
- *
- * `chart-scope.scss` declares each of these roles as `var(<role>-theme, <catalog default>)`, so an override that is invalid at computed-value time — a fallback-less `var()` naming a token the host never set — only invalidates this variable, and the role still resolves its mapped `--wpds-*` token. Published as the role directly, such a value took the role and every bare `var(<role>)` read site down with it.
- *
- * @param role - The catalog role being overridden.
- * @return The custom property carrying the consumer's value.
- */
-export const themeLayerVar = ( role: string ): string => `${ role }-theme`;
-
-/** Every role whose catalog entry must read a theme layer. `src/styles/test/chart-scope.test.ts` checks the stylesheet against this. */
-export const THEME_LAYERED_ROLES: readonly string[] = ROLE_FOR_FIELD.map( ( [ role ] ) => role );
-
-/**
- * Whether a value reads the role it is being published for, which would make the catalog entry depend on itself.
- *
- * The dependency runs `<role>: var(<role>-theme, …)`, so a value naming `<role>` closes a cycle through the catalog entry. CSS marks every custom property in a cycle invalid at computed-value time — the role's own fallback is *not* used, so the token resolves to nothing and every chart loses that 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:
- *
- * `var()` permits whitespace after the opening paren, so testing for `var(<role>` misses `var( --a8c-charts-color-grid, … )`.
- *
- * Several roles are prefixes of others (`--a8c-charts-color-label` of `--a8c-charts-color-label-secondary`), and every role is a prefix of its own theme layer. A prefix match would read a legitimate cross-role pointer as a self-reference and silently drop the override, so the role must be followed by something that cannot continue an identifier — `-` included. A value naming `<role>-theme` is therefore not treated as a self-reference: that cycle is confined to the theme layer, which leaves the role free to fall back to the catalog default.
- *
- * `resolveCssVariable` also accepts a bare custom-property name with no `var()` wrapper (`--a8c-charts-color-grid`), so that is legal `theme` input too. It forms no cycle — custom properties accept arbitrary token streams — so it survives as a literal string and drops silently at the use site instead of falling back to the catalog default.
- *
- * @param value - The consumer's value for the field.
- * @param role  - The catalog role this value would override.
- * @return True when the value reads `role`, so it must not be published.
- */
-const readsOwnRole = ( value: string, role: string ): boolean =>
-	value.trim() === role ||
-	new RegExp( `var\\(\\s*${ role.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' ) }(?![\\w-])` ).test(
-		value
-	);
-
-export type ThemeOverrides = {
-	/** The custom properties to write on the provider wrapper. */
-	vars: Record< string, string >;
-	/** Every mapped role the consumer set a value for, whether or not it was published. */
-	roles: readonly string[];
-};
-
-/**
- * Maps a sparse consumer theme onto the theme-layer variables its overridden catalog roles read, so CSS-painted and JS-resolved 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.
- */
-export const themeOverrideVars = ( theme?: Partial< ChartTheme > ): ThemeOverrides => {
-	if ( ! theme ) {
-		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[] = [];
-
-	for ( const [ role, read ] of ROLE_FOR_FIELD ) {
-		const value = read( theme );
-
-		if ( typeof value !== 'string' || value === '' ) {
-			continue;
-		}
-
-		roles.push( role );
-
-		if ( ! readsOwnRole( value, role ) ) {
-			vars[ themeLayerVar( role ) ] = value;
-		}
-	}
-
-	return { vars, roles };
-};

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

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

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

@@ -1,29 +0,0 @@
-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( '' );
-	} );
-} );