@automattic/charts 3.1.1 → 4.0.0

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

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

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

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

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( '' );
-	} );
-} );

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

@@ -1,118 +0,0 @@
-import {
-	THEME_LAYERED_ROLES,
-	themeLayerVar,
-	themeOverrideVars,
-} from '../private/theme-override-vars';
-
-describe( 'themeOverrideVars', () => {
-	it( 'returns nothing for an absent theme', () => {
-		expect( themeOverrideVars( undefined ) ).toEqual( { vars: {}, roles: [] } );
-	} );
-
-	it( 'returns nothing for a theme that overrides no mapped role', () => {
-		expect( themeOverrideVars( { tickLength: 8 } ) ).toEqual( { vars: {}, roles: [] } );
-	} );
-
-	// The value is published one layer outside the role — `chart-scope.scss` declares the role as `var(<role>-theme, <catalog default>)`. Published as the role itself, a value that is invalid at computed-value time (`var(--wpds-token)` with the token unset) would make the role invalid too, and every bare `var(--a8c-charts-color-grid)` read site would paint `unset` instead of falling back to the catalog default.
-	it( 'maps a grid stroke override onto the grid role’s theme layer', () => {
-		expect( themeOverrideVars( { gridStyles: { stroke: 'red' } } ) ).toEqual( {
-			vars: { '--a8c-charts-color-grid-theme': 'red' },
-			roles: [ '--a8c-charts-color-grid' ],
-		} );
-	} );
-
-	it( 'maps every supported role at once', () => {
-		expect(
-			themeOverrideVars( {
-				backgroundColor: '#111',
-				gridStyles: { stroke: '#222' },
-				xAxisLineStyles: { stroke: '#333' },
-				xTickLineStyles: { stroke: '#444' },
-				svgLabelSmall: { fill: '#555' },
-			} )
-		).toEqual( {
-			vars: {
-				'--a8c-charts-color-background-theme': '#111',
-				'--a8c-charts-color-grid-theme': '#222',
-				'--a8c-charts-color-axis-theme': '#333',
-				'--a8c-charts-color-tick-theme': '#444',
-				'--a8c-charts-color-label-axis-theme': '#555',
-			},
-			roles: [
-				'--a8c-charts-color-background',
-				'--a8c-charts-color-grid',
-				'--a8c-charts-color-axis',
-				'--a8c-charts-color-tick',
-				'--a8c-charts-color-label-axis',
-			],
-		} );
-	} );
-
-	it( 'publishes only theme-layer variables, never a catalog role directly', () => {
-		const { vars } = themeOverrideVars( {
-			backgroundColor: '#111',
-			gridStyles: { stroke: '#222' },
-			xAxisLineStyles: { stroke: '#333' },
-			xTickLineStyles: { stroke: '#444' },
-			svgLabelSmall: { fill: '#555' },
-		} );
-
-		expect( Object.keys( vars ) ).toEqual( THEME_LAYERED_ROLES.map( themeLayerVar ) );
-	} );
-
-	// The narrow role is the whole point: the broad `--a8c-charts-color-label` is also read by legend labels, heatmap cell values, funnel labels and the line-chart tooltip, none of which `svgLabelSmall.fill` moved before the role was published as a custom property.
-	it( 'publishes an svg label override as the narrow axis-label role, not the broad one', () => {
-		expect( themeOverrideVars( { svgLabelSmall: { fill: 'red' } } ) ).toEqual( {
-			vars: { '--a8c-charts-color-label-axis-theme': 'red' },
-			roles: [ '--a8c-charts-color-label-axis' ],
-		} );
-	} );
-
-	it( 'ignores a value that is itself a pointer at the role it would override', () => {
-		expect(
-			themeOverrideVars( { gridStyles: { stroke: 'var(--a8c-charts-color-grid, #dbdbdb)' } } ).vars
-		).toEqual( {} );
-	} );
-
-	// A skipped value still reports its role, so `withCatalogPointers` restores the theme field. Without that, CSS would paint the catalog default while visx painted the consumer's literal — the divergence this whole mechanism exists to remove.
-	it( 'still reports the role of a value it refuses to publish', () => {
-		expect(
-			themeOverrideVars( {
-				gridStyles: { stroke: 'var(--brand, var(--a8c-charts-color-grid, red))' },
-			} )
-		).toEqual( { vars: {}, roles: [ '--a8c-charts-color-grid' ] } );
-	} );
-
-	// `var()` allows whitespace after the opening paren. The role reads its theme layer, so a value naming the role closes a cycle through the catalog entry: CSS marks every custom property in a cycle invalid at computed-value time, and the role's own fallback is not used, so the token resolves to nothing at all.
-	it( 'ignores a self-referential pointer padded with whitespace', () => {
-		expect(
-			themeOverrideVars( { gridStyles: { stroke: 'var( --a8c-charts-color-grid, #dbdbdb )' } } )
-				.vars
-		).toEqual( {} );
-	} );
-
-	it( 'still emits a value that merely mentions a different role', () => {
-		expect(
-			themeOverrideVars( { gridStyles: { stroke: 'var( --a8c-charts-color-axis, #dbdbdb )' } } )
-				.vars
-		).toEqual( {
-			'--a8c-charts-color-grid-theme': 'var( --a8c-charts-color-axis, #dbdbdb )',
-		} );
-	} );
-
-	// A mapped role can be a strict prefix of another custom property — a catalog role such as `--a8c-charts-color-label` of `--a8c-charts-color-label-axis`, the role's own theme layer, or a name the consumer defined themselves. A prefix match would read a legitimate cross-property pointer as a self-reference and silently drop the override, so the role must be followed by something that cannot continue an identifier.
-	it( 'does not mistake a longer property name for the role it guards', () => {
-		expect(
-			themeOverrideVars( {
-				xAxisLineStyles: { stroke: 'var(--a8c-charts-color-axis-emphasis, #000)' },
-			} ).vars
-		).toEqual( { '--a8c-charts-color-axis-theme': 'var(--a8c-charts-color-axis-emphasis, #000)' } );
-	} );
-
-	// `resolveCssVariable` also accepts a bare custom-property name with no `var()` wrapper, so `theme={ { gridStyles: { stroke: '--a8c-charts-color-grid' } } }` is legal input. It forms no cycle, so it must be caught explicitly or it survives as a literal string value and drops silently at the use site.
-	it( 'ignores a self-referential pointer written as a bare custom-property name', () => {
-		expect(
-			themeOverrideVars( { gridStyles: { stroke: '--a8c-charts-color-grid' } } ).vars
-		).toEqual( {} );
-	} );
-} );

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

@@ -1,47 +0,0 @@
-import { mergeThemes } from '../../../utils';
-import { withCatalogPointers } from '../private/with-catalog-pointers';
-import { defaultTheme } from '../themes';
-import type { ChartTheme } from '../../../types';
-
-describe( 'withCatalogPointers', () => {
-	it( 'restores every overridden role to its catalog pointer, without mutating the input theme', () => {
-		const merged = mergeThemes( defaultTheme, {
-			backgroundColor: '#111',
-			gridStyles: { stroke: '#222' },
-			xAxisLineStyles: { stroke: '#333' },
-			xTickLineStyles: { stroke: '#444' },
-			svgLabelSmall: { fill: '#555' },
-		} as Partial< ChartTheme > );
-
-		const result = withCatalogPointers( merged, [
-			'--a8c-charts-color-background',
-			'--a8c-charts-color-grid',
-			'--a8c-charts-color-axis',
-			'--a8c-charts-color-tick',
-			'--a8c-charts-color-label-axis',
-		] );
-
-		expect( result.backgroundColor ).toBe( defaultTheme.backgroundColor );
-		expect( result.gridStyles.stroke ).toBe( defaultTheme.gridStyles.stroke );
-		expect( result.xAxisLineStyles.stroke ).toBe( defaultTheme.xAxisLineStyles.stroke );
-		expect( result.xTickLineStyles.stroke ).toBe( defaultTheme.xTickLineStyles.stroke );
-		expect( result.svgLabelSmall.fill ).toBe( defaultTheme.svgLabelSmall.fill );
-
-		expect( merged.backgroundColor ).toBe( '#111' );
-		expect( merged.gridStyles.stroke ).toBe( '#222' );
-	} );
-
-	it( 'leaves fields alone when no role was overridden', () => {
-		const merged = mergeThemes( defaultTheme, {
-			tickLength: 8,
-			leaderboardChart: { deltaColors: [ 'red', 'grey', 'green' ] },
-		} as Partial< ChartTheme > );
-
-		const result = withCatalogPointers( merged, [] );
-
-		expect( result.tickLength ).toBe( 8 );
-		expect( result.gridStyles.stroke ).toBe( defaultTheme.gridStyles.stroke );
-		// Not a mapped role, so its literal survives even when other roles are being restored.
-		expect( result.leaderboardChart.deltaColors ).toEqual( [ 'red', 'grey', 'green' ] );
-	} );
-} );

package/src/styles/test/wpds-fallbacks.test.ts

@@ -1,131 +0,0 @@
-import { globSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import dsTokenFallbacks from '@wordpress/theme/postcss-plugins/postcss-ds-token-fallbacks';
-
-const SOURCE = join( __dirname, '..', '..' );
-
-// @wordpress/theme publishes its token map only through this plugin. The `Declaration`
-// visitor rewrites a declaration's `value` in place and reads nothing else off the node,
-// so a synthetic node is enough to ask it what a token is worth. It throws on a token the
-// installed design system does not define, which is how a rename surfaces here.
-const { Declaration: rewriteValue } = dsTokenFallbacks() as {
-	Declaration: ( declaration: { value: string } ) => void;
-};
-
-const normalize = ( value: string ): string => value.replace( /\s+/g, ' ' ).trim();
-
-/**
- * Reports the fallback expression the installed design system defines for a token.
- *
- * @param token - A `--wpds-*` custom property name.
- * @return The design system's value for it.
- */
-function specFallback( token: string ): string {
-	const declaration = { value: `var(${ token })` };
-	rewriteValue( declaration );
-
-	// The plugin is expected to throw on a token the design system does not define. Should a
-	// future version return the reference untouched instead, slicing off a prefix that isn't
-	// there would yield a fragment of the token name and fail some later assertion with a
-	// value nothing wrote. Fail here, naming the token, rather than there.
-	const prefix = `var(${ token }, `;
-
-	if ( ! declaration.value.startsWith( prefix ) || ! declaration.value.endsWith( ')' ) ) {
-		throw new Error(
-			`@wordpress/theme did not supply a fallback for ${ token } — got "${ declaration.value }".`
-		);
-	}
-
-	return declaration.value.slice( prefix.length, -1 );
-}
-
-type Reference = {
-	file: string;
-	token: string;
-	/** The written fallback, or null where the reference is bare. */
-	fallback: string | null;
-};
-
-/**
- * Finds every `--wpds-*` reference in a file. Scanning for the closing parenthesis by depth, rather than matching a regex, keeps a fallback that is itself a function call or a nested `var()` intact — `cubic-bezier(0.15, 0, 0.15, 1)` and `var(--wp-admin-theme-color, #3858e9)` both end at a parenthesis an inner call opened.
- *
- * @param source - The file's contents.
- * @param file   - Its path, relative to `src`.
- * @return Every reference the file makes.
- */
-function referencesIn( source: string, file: string ): Reference[] {
-	const opener = /var\(\s*(--wpds-[\w-]+)\s*/g;
-	const references: Reference[] = [];
-	let match;
-
-	while ( ( match = opener.exec( source ) ) !== null ) {
-		const token = match[ 1 ];
-
-		if ( source[ opener.lastIndex ] !== ',' ) {
-			references.push( { file, token, fallback: null } );
-			continue;
-		}
-
-		let index = opener.lastIndex + 1;
-		let depth = 1;
-
-		while ( index < source.length && depth > 0 ) {
-			if ( source[ index ] === '(' ) {
-				depth++;
-			} else if ( source[ index ] === ')' ) {
-				depth--;
-			}
-
-			if ( depth > 0 ) {
-				index++;
-			}
-		}
-
-		references.push( {
-			file,
-			token,
-			fallback: normalize( source.slice( opener.lastIndex + 1, index ) ),
-		} );
-	}
-
-	return references;
-}
-
-const references = globSync( '**/*.{scss,css,ts,tsx,mdx}', { cwd: SOURCE } )
-	// Paths are relative to `src`, so a top-level `src/test/` arrives without a leading slash.
-	.filter( file => ! /(^|\/)test\//.test( file ) )
-	.flatMap( file => referencesIn( readFileSync( join( SOURCE, file ), 'utf8' ), file ) );
-
-describe( 'design token references', () => {
-	it( 'finds the references, so a broken scan cannot pass as a clean one', () => {
-		expect( references.length ).toBeGreaterThan( 30 );
-	} );
-
-	// Every fallback here is hand-written, because both of this package's consumption paths
-	// have to carry it: `@wordpress/build` apps read `dist/`, while webpack apps resolve the
-	// SCSS through the `jetpack:src` export condition and compile it themselves. Neither
-	// build injects fallbacks, so a bare reference in a stylesheet renders as nothing at all
-	// in a host that has not loaded the design-system stylesheet — and WordPress ships none.
-	//
-	// A bare reference in TS can be deliberate: `stories/theme-config.tsx` seeds a series
-	// colour from a token `ThemeProvider` generates, where resolving to nothing is the
-	// wanted behaviour when no provider is above the chart.
-	it( 'writes a fallback for every token a stylesheet reads', () => {
-		expect(
-			references.filter(
-				reference => reference.fallback === null && /\.(scss|css)$/.test( reference.file )
-			)
-		).toEqual( [] );
-	} );
-
-	// This is the check that keeps a hand-written value honest. It is what `499` — a font
-	// weight that was spec once and drifted — needed and did not have.
-	it( 'writes the design system value as that fallback', () => {
-		const drifted = references
-			.filter( reference => reference.fallback !== null )
-			.map( reference => ( { ...reference, spec: normalize( specFallback( reference.token ) ) } ) )
-			.filter( reference => reference.fallback !== reference.spec );
-
-		expect( drifted ).toEqual( [] );
-	} );
-} );