@automattic/charts 4.3.0 → 4.5.0

package/src/providers/chart-context/private/perceptual-color.ts

@@ -0,0 +1,219 @@
+import { relativeLuminance, validateHexColor } from '../../../utils';
+
+export type Lab = readonly [ number, number, number ];
+
+/** A color as seen in normal vision, then under deuteranopia and protanopia. */
+export type ColorViews = readonly [ Lab, Lab, Lab ];
+
+type Matrix = readonly number[];
+
+// Machado, Oliveira and Fernandes (2009), severity 1.0, on linear sRGB.
+const DEUTERANOPIA: Matrix = [
+	0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.01182, 0.04294, 0.968881,
+];
+const PROTANOPIA: Matrix = [
+	0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998,
+];
+
+const DEGREES = Math.PI / 180;
+
+const toLinear = ( channel: number ): number =>
+	channel <= 0.04045 ? channel / 12.92 : Math.pow( ( channel + 0.055 ) / 1.055, 2.4 );
+
+const fromLinear = ( channel: number ): number =>
+	channel <= 0.0031308 ? 12.92 * channel : 1.055 * Math.pow( channel, 1 / 2.4 ) - 0.055;
+
+const hexToLinear = ( hex: string ): number[] => {
+	validateHexColor( hex );
+	return [ 1, 3, 5 ].map( start =>
+		toLinear( parseInt( hex.slice( start, start + 2 ), 16 ) / 255 )
+	);
+};
+
+const linearToHex = ( linear: number[] ): string =>
+	'#' +
+	linear
+		.map( channel =>
+			Math.round( Math.min( 1, Math.max( 0, fromLinear( channel ) ) ) * 255 )
+				.toString( 16 )
+				.padStart( 2, '0' )
+		)
+		.join( '' );
+
+const simulate = ( matrix: Matrix, [ r, g, b ]: number[] ): number[] =>
+	[ 0, 3, 6 ].map( row =>
+		Math.min( 1, Math.max( 0, matrix[ row ] * r + matrix[ row + 1 ] * g + matrix[ row + 2 ] * b ) )
+	);
+
+const linearToLab = ( [ r, g, b ]: number[] ): Lab => {
+	const x = ( 0.4124564 * r + 0.3575761 * g + 0.1804375 * b ) / 0.95047;
+	const y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
+	const z = ( 0.0193339 * r + 0.119192 * g + 0.9503041 * b ) / 1.08883;
+	const f = ( t: number ): number =>
+		t > 216 / 24389 ? Math.cbrt( t ) : ( ( 24389 / 27 ) * t + 16 ) / 116;
+	return [ 116 * f( y ) - 16, 500 * ( f( x ) - f( y ) ), 200 * ( f( y ) - f( z ) ) ];
+};
+
+/**
+ * CIEDE2000 color difference between two CIELAB colors.
+ *
+ * @param first  - First color in CIELAB.
+ * @param second - Second color in CIELAB.
+ * @return ΔE00; about 10 is where two chart categories stop being reliably distinguishable.
+ */
+export const deltaE2000 = ( first: Lab, second: Lab ): number => {
+	const [ l1, a1, b1 ] = first;
+	const [ l2, a2, b2 ] = second;
+	const chromaMean = ( Math.hypot( a1, b1 ) + Math.hypot( a2, b2 ) ) / 2;
+	const g = 0.5 * ( 1 - Math.sqrt( chromaMean ** 7 / ( chromaMean ** 7 + 25 ** 7 ) ) );
+	const a1p = a1 * ( 1 + g );
+	const a2p = a2 * ( 1 + g );
+	const c1p = Math.hypot( a1p, b1 );
+	const c2p = Math.hypot( a2p, b2 );
+	const hueOf = ( a: number, b: number ): number =>
+		a === 0 && b === 0 ? 0 : ( Math.atan2( b, a ) / DEGREES + 360 ) % 360;
+	const h1p = hueOf( a1p, b1 );
+	const h2p = hueOf( a2p, b2 );
+	const chromatic = c1p * c2p !== 0;
+
+	let hueDelta = chromatic ? h2p - h1p : 0;
+	if ( hueDelta > 180 ) {
+		hueDelta -= 360;
+	} else if ( hueDelta < -180 ) {
+		hueDelta += 360;
+	}
+
+	const lightnessDelta = l2 - l1;
+	const chromaDelta = c2p - c1p;
+	const hueDifference = 2 * Math.sqrt( c1p * c2p ) * Math.sin( ( hueDelta * DEGREES ) / 2 );
+	const lightnessMean = ( l1 + l2 ) / 2;
+	const chromaMeanPrime = ( c1p + c2p ) / 2;
+
+	let hueMean = h1p + h2p;
+	if ( chromatic ) {
+		if ( Math.abs( h1p - h2p ) > 180 ) {
+			hueMean += hueMean < 360 ? 360 : -360;
+		}
+		hueMean /= 2;
+	}
+
+	const t =
+		1 -
+		0.17 * Math.cos( ( hueMean - 30 ) * DEGREES ) +
+		0.24 * Math.cos( 2 * hueMean * DEGREES ) +
+		0.32 * Math.cos( ( 3 * hueMean + 6 ) * DEGREES ) -
+		0.2 * Math.cos( ( 4 * hueMean - 63 ) * DEGREES );
+	const lightnessScale =
+		1 + ( 0.015 * ( lightnessMean - 50 ) ** 2 ) / Math.sqrt( 20 + ( lightnessMean - 50 ) ** 2 );
+	const chromaScale = 1 + 0.045 * chromaMeanPrime;
+	const hueScale = 1 + 0.015 * chromaMeanPrime * t;
+	const rotation =
+		-2 *
+		Math.sqrt( chromaMeanPrime ** 7 / ( chromaMeanPrime ** 7 + 25 ** 7 ) ) *
+		Math.sin( 60 * Math.exp( -( ( ( hueMean - 275 ) / 25 ) ** 2 ) ) * DEGREES );
+
+	const lightnessTerm = lightnessDelta / lightnessScale;
+	const chromaTerm = chromaDelta / chromaScale;
+	const hueTerm = hueDifference / hueScale;
+
+	return Math.sqrt(
+		lightnessTerm ** 2 + chromaTerm ** 2 + hueTerm ** 2 + rotation * chromaTerm * hueTerm
+	);
+};
+
+/**
+ * A hex color in CIELAB as seen in normal vision, under deuteranopia and under protanopia.
+ *
+ * @param  hex - Six-digit hex color.
+ * @return The three views.
+ * @throws {Error} if hex string is malformed
+ */
+export const hexToViews = ( hex: string ): ColorViews => {
+	const linear = hexToLinear( hex );
+	return [
+		linearToLab( linear ),
+		linearToLab( simulate( DEUTERANOPIA, linear ) ),
+		linearToLab( simulate( PROTANOPIA, linear ) ),
+	];
+};
+
+/**
+ * The smallest ΔE00 between two colors across the three views.
+ *
+ * @param first  - First color's views.
+ * @param second - Second color's views.
+ * @return The distance in the view where the two are hardest to tell apart.
+ */
+export const viewDistance = ( first: ColorViews, second: ColorViews ): number =>
+	Math.min(
+		deltaE2000( first[ 0 ], second[ 0 ] ),
+		deltaE2000( first[ 1 ], second[ 1 ] ),
+		deltaE2000( first[ 2 ], second[ 2 ] )
+	);
+
+/**
+ * Convert an OKLCH color to sRGB hex.
+ *
+ * @param lightness - OKLab L, 0 to 1.
+ * @param chroma    - OKLCH C.
+ * @param hue       - Hue in degrees.
+ * @return Hex color, or null when the color is outside the sRGB gamut.
+ */
+export const oklchToHex = ( lightness: number, chroma: number, hue: number ): string | null => {
+	const a = chroma * Math.cos( hue * DEGREES );
+	const b = chroma * Math.sin( hue * DEGREES );
+	const l = ( lightness + 0.3963377774 * a + 0.2158037573 * b ) ** 3;
+	const m = ( lightness - 0.1055613458 * a - 0.0638541728 * b ) ** 3;
+	const s = ( lightness - 0.0894841775 * a - 1.291485548 * b ) ** 3;
+	const linear = [
+		4.0767416621 * l - 3.3077633306 * m + 0.2309645873 * s,
+		-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+		-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+	];
+	const tolerance = 1e-4;
+	if ( linear.some( channel => channel < -tolerance || channel > 1 + tolerance ) ) {
+		return null;
+	}
+	return linearToHex( linear );
+};
+
+/**
+ * OKLCH chroma and hue of a hex color.
+ *
+ * @param  hex - Six-digit hex color.
+ * @return Chroma, and hue in degrees from 0 to 360.
+ * @throws {Error} if hex string is malformed
+ */
+export const hexToOklch = ( hex: string ): { chroma: number; hue: number } => {
+	const [ r, g, b ] = hexToLinear( hex );
+	const l = Math.cbrt( 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b );
+	const m = Math.cbrt( 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b );
+	const s = Math.cbrt( 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b );
+	const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+	const bAxis = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+	return {
+		chroma: Math.hypot( a, bAxis ),
+		hue: ( Math.atan2( bAxis, a ) / DEGREES + 360 ) % 360,
+	};
+};
+
+/**
+ * WCAG contrast ratio between two relative luminances.
+ *
+ * @param first  - First relative luminance.
+ * @param second - Second relative luminance.
+ * @return Ratio from 1 to 21.
+ */
+export const luminanceContrastRatio = ( first: number, second: number ): number =>
+	( Math.max( first, second ) + 0.05 ) / ( Math.min( first, second ) + 0.05 );
+
+/**
+ * WCAG contrast ratio between two hex colors.
+ *
+ * @param  first  - First hex color.
+ * @param  second - Second hex color.
+ * @return Ratio from 1 to 21.
+ * @throws {Error} if either hex string is malformed
+ */
+export const contrastRatio = ( first: string, second: string ): number =>
+	luminanceContrastRatio( relativeLuminance( first ), relativeLuminance( second ) );

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

@@ -23,7 +23,7 @@ export const seriesRole = ( slot: number ): string => `--a8c-charts-color-series
  * 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';
+export const SERIES_SLOT_1_FALLBACK = '#3858e9';
 
 /** The catalog pointer for every slot, in slot order. */
 export const SERIES_PALETTE_POINTERS: readonly string[] = Array.from(

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

@@ -4,6 +4,7 @@ import { GlobalChartsProvider } from '../global-charts-provider';
 import { useChartId } from '../hooks/use-chart-id';
 import { useChartRegistration } from '../hooks/use-chart-registration';
 import { useGlobalChartsContext } from '../hooks/use-global-charts-context';
+import { createPaletteGenerator } from '../private/palette-generator';
 import { defaultTheme } from '../themes';
 import type { BaseLegendItem } from '../../../components/legend';
 import type { SeriesData } from '../../../types';
@@ -1893,13 +1894,22 @@ describe( 'ChartContext', () => {
 			return <div>Test</div>;
 		};
 
-		const renderWithSlots = ( slots: Array< string | undefined > ) => {
+		const renderWithSlots = (
+			slots: Array< string | undefined >,
+			extraRoles?: Record< string, string >
+		) => {
 			slots.forEach( ( color, slot ) => {
 				if ( color !== undefined ) {
 					container.style.setProperty( `--a8c-charts-color-series-${ slot + 1 }`, color );
 				}
 			} );
 
+			if ( extraRoles ) {
+				Object.entries( extraRoles ).forEach( ( [ property, value ] ) =>
+					container.style.setProperty( property, value )
+				);
+			}
+
 			return render(
 				<GlobalChartsProvider>
 					<TestComponent />
@@ -1990,19 +2000,16 @@ describe( 'ChartContext', () => {
 		} );
 
 		describe( 'Error Handling', () => {
-			it( 'keeps an unparseable value without crashing', () => {
+			it( 'compacts out an unparseable value without crashing', () => {
 				expect( () => renderWithSlots( [ '#invalid', '#ff0000' ] ) ).not.toThrow();
 
-				expect( colorAt( 0 ) ).toBe( '#invalid' );
-				expect( colorAt( 1 ) ).toBe( '#ff0000' );
+				expect( colorAt( 0 ) ).toBe( '#ff0000' );
 			} );
 
-			it( 'keeps malformed hex values without crashing', () => {
+			it( 'compacts out malformed hex values without crashing', () => {
 				expect( () => renderWithSlots( [ '#ff', '#gggggg', '#00ff00' ] ) ).not.toThrow();
 
-				expect( colorAt( 0 ) ).toBe( '#ff' );
-				expect( colorAt( 1 ) ).toBe( '#gggggg' );
-				expect( colorAt( 2 ) ).toBe( '#00ff00' );
+				expect( colorAt( 0 ) ).toBe( '#00ff00' );
 			} );
 
 			it( 'keeps resolving the later slots after one fails to convert', () => {
@@ -2034,6 +2041,79 @@ describe( 'ChartContext', () => {
 			} );
 		} );
 
+		describe( 'Background-aware generation', () => {
+			const seed = '#3858e9';
+			const labels = [ '#1e1e1e', '#f0f0f0' ];
+
+			it( 'wires the resolved dark background into the generator', () => {
+				// Fixture guard: proves index 1 actually depends on the background for this seed,
+				// so a match below can't pass by coincidence.
+				const onDark = createPaletteGenerator( [ seed ], '#1e1e1e', labels )( 1 );
+				const onLight = createPaletteGenerator( [ seed ], '#ffffff', labels )( 1 );
+				expect( onDark ).not.toBe( onLight );
+
+				renderWithSlots( [ seed ], { '--a8c-charts-color-background': '#1e1e1e' } );
+
+				expect( colorAt( 1 ) ).toBe( onDark );
+			} );
+
+			it( 'falls back to a white background when the resolved value does not normalize to hex', () => {
+				renderWithSlots( [ seed ], { '--a8c-charts-color-background': 'not-a-real-color' } );
+
+				expect( colorAt( 1 ) ).toBe( createPaletteGenerator( [ seed ], '#ffffff', labels )( 1 ) );
+			} );
+
+			it( 'falls back to a white background when the background is transparent', () => {
+				const onWhite = createPaletteGenerator( [ seed ], '#ffffff', labels )( 1 );
+				const onBlack = createPaletteGenerator( [ seed ], '#000000', labels )( 1 );
+				expect( onWhite ).not.toBe( onBlack );
+
+				renderWithSlots( [ seed ], { '--a8c-charts-color-background': 'transparent' } );
+
+				expect( colorAt( 1 ) ).toBe( onWhite );
+			} );
+
+			it( 'falls back to a white background when the background is a translucent color', () => {
+				const onWhite = createPaletteGenerator( [ seed ], '#ffffff', labels )( 1 );
+				const onBlack = createPaletteGenerator( [ seed ], '#000000', labels )( 1 );
+				expect( onWhite ).not.toBe( onBlack );
+
+				renderWithSlots( [ seed ], { '--a8c-charts-color-background': 'rgba(0, 0, 0, 0.5)' } );
+
+				expect( colorAt( 1 ) ).toBe( onWhite );
+			} );
+
+			it( 'wires the resolved label colors into the generator, leaving out a see-through one', () => {
+				const firstSix = ( at: ( index: number ) => string ) =>
+					Array.from( { length: 6 }, ( _, index ) => at( index ) );
+				const inverseOnly = firstSix(
+					createPaletteGenerator( [ seed ], '#ffffff', [ '#f0f0f0' ] )
+				);
+				expect( inverseOnly ).not.toEqual(
+					firstSix( createPaletteGenerator( [ seed ], '#ffffff', labels ) )
+				);
+
+				renderWithSlots( [ seed ], { '--a8c-charts-color-label': 'transparent' } );
+
+				expect( firstSix( colorAt ) ).toEqual( inverseOnly );
+			} );
+
+			it( 'uses the resolved background for group colors when no seed resolves', () => {
+				const background = '#1e1e1e';
+
+				// An unparseable slot 1 keeps the resolved palette empty even after resolution;
+				// an unset slot 1 would instead fall back to its own terminal literal.
+				renderWithSlots( [ '#invalid' ], { '--a8c-charts-color-background': background } );
+
+				const groupColor = contextValue.getElementStyles( {
+					data: createMockDataWithGroup( 'test-group' ),
+					index: 0,
+				} ).color;
+
+				expect( groupColor ).toBe( createPaletteGenerator( [], background, labels )( 0 ) );
+			} );
+		} );
+
 		describe( 'Server-Side Rendering', () => {
 			// Slot 1's terminal literal is the palette's only carrier under SSR.
 			it( 'falls back to the seed when getComputedStyle is unavailable', () => {

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

@@ -0,0 +1,27 @@
+import { render } from '@testing-library/react';
+import { GlobalChartsProvider } from '../global-charts-provider';
+import { useGlobalChartsContext } from '../hooks/use-global-charts-context';
+
+describe( 'GlobalChartsProvider before the palette resolves', () => {
+	it( 'renders the same colors an unthemed page resolves to', () => {
+		const renders: string[][] = [];
+
+		const FirstColors = () => {
+			const { getElementStyles } = useGlobalChartsContext();
+			renders.push(
+				Array.from( { length: 6 }, ( _, index ) => getElementStyles( { index } ).color )
+			);
+			return null;
+		};
+
+		render(
+			<GlobalChartsProvider>
+				<FirstColors />
+			</GlobalChartsProvider>
+		);
+
+		expect( renders.length ).toBeGreaterThan( 1 );
+		expect( renders[ 0 ][ 0 ] ).toBe( '#3858e9' );
+		expect( renders[ 0 ] ).toEqual( renders[ renders.length - 1 ] );
+	} );
+} );

package/src/providers/chart-context/test/palette-generator.test.ts

@@ -0,0 +1,181 @@
+import {
+	createPaletteGenerator,
+	MIN_BACKGROUND_CONTRAST,
+	MIN_LABEL_CONTRAST,
+	PREFERRED_SEPARATION,
+} from '../private/palette-generator';
+import { contrastRatio, hexToOklch, hexToViews, viewDistance } from '../private/perceptual-color';
+
+// `--wp-admin-theme-color` for each wp-admin color scheme, as `@wordpress/base-styles` sets it.
+const WP_ADMIN_THEME_COLORS = Object.entries( {
+	light: '#007cba',
+	modern: '#3858e9',
+	blue: '#437aa8',
+	coffee: '#916745',
+	ectoplasm: '#646c3e',
+	midnight: '#cf4339',
+	ocean: '#567958',
+	sunrise: '#ad631e',
+} );
+const PALETTE_SIZE = 6;
+const LABEL_COLORS = [ '#1e1e1e', '#f0f0f0' ];
+
+const paletteOf = (
+	seeds: string[],
+	background: string,
+	size = PALETTE_SIZE,
+	labelColors: string[] = LABEL_COLORS
+): string[] => {
+	const colorAt = createPaletteGenerator( seeds, background, labelColors );
+	return Array.from( { length: size }, ( _, index ) => colorAt( index ) );
+};
+
+const minPairwiseDistance = ( palette: string[] ): number => {
+	const views = palette.map( hexToViews );
+	let min = Infinity;
+	for ( let i = 0; i < views.length; i++ ) {
+		for ( let j = i + 1; j < views.length; j++ ) {
+			min = Math.min( min, viewDistance( views[ i ], views[ j ] ) );
+		}
+	}
+	return min;
+};
+
+describe( 'createPaletteGenerator', () => {
+	it( 'returns the seeds first, in order', () => {
+		const colorAt = createPaletteGenerator( [ '#ff0000', '#00ff00' ], '#ffffff' );
+		expect( colorAt( 0 ) ).toBe( '#ff0000' );
+		expect( colorAt( 1 ) ).toBe( '#00ff00' );
+	} );
+
+	describe.each( [ '#ffffff', '#1e1e1e' ] )( 'on %s', background => {
+		it.each( WP_ADMIN_THEME_COLORS )(
+			'keeps a palette seeded with the %s scheme (%s) separable in every vision view up to six colors',
+			( _scheme, seed ) => {
+				expect( minPairwiseDistance( paletteOf( [ seed ], background ) ) ).toBeGreaterThanOrEqual(
+					PREFERRED_SEPARATION
+				);
+			}
+		);
+
+		it.each( WP_ADMIN_THEME_COLORS )(
+			'gives every color generated from the %s scheme (%s) 3:1 against the background',
+			( _scheme, seed ) => {
+				paletteOf( [ seed ], background )
+					.slice( 1 )
+					.forEach( color => {
+						expect( contrastRatio( color, background ) ).toBeGreaterThanOrEqual(
+							MIN_BACKGROUND_CONTRAST
+						);
+					} );
+			}
+		);
+
+		it.each( WP_ADMIN_THEME_COLORS )(
+			'gives every color generated from the %s scheme (%s) a label color with 4.5:1 on it',
+			( _scheme, seed ) => {
+				paletteOf( [ seed ], background )
+					.slice( 1 )
+					.forEach( color => {
+						const best = Math.max( ...LABEL_COLORS.map( label => contrastRatio( color, label ) ) );
+						expect( best ).toBeGreaterThanOrEqual( MIN_LABEL_CONTRAST );
+					} );
+			}
+		);
+	} );
+
+	it( 'keeps 3:1 against the background when no fill can reach 4.5:1 with the label colors', () => {
+		paletteOf( [ '#3858e9' ], '#ffffff', PALETTE_SIZE, [ '#777777' ] )
+			.slice( 1 )
+			.forEach( color => {
+				expect( contrastRatio( color, '#ffffff' ) ).toBeGreaterThanOrEqual(
+					MIN_BACKGROUND_CONTRAST
+				);
+			} );
+	} );
+
+	it.each( WP_ADMIN_THEME_COLORS )(
+		'sets the first generated color further from the %s scheme seed (%s) than the second',
+		( _scheme, seed ) => {
+			const [ seedColor, first, second ] = paletteOf( [ seed ], '#ffffff', 3 ).map( hexToViews );
+			expect( viewDistance( seedColor, first ) ).toBeGreaterThan(
+				viewDistance( seedColor, second )
+			);
+		}
+	);
+
+	it.each( [ '#007cba', '#3858e9', '#437aa8' ] )(
+		'places the second generated color just ahead of %s on the hue wheel',
+		seed => {
+			const seedHue = hexToOklch( seed ).hue;
+			const walkedHue = hexToOklch( paletteOf( [ seed ], '#ffffff', 3 )[ 2 ] ).hue;
+			expect( ( walkedHue - seedHue + 360 ) % 360 ).toBeLessThan( 45 );
+		}
+	);
+
+	it( 'shares one generator between calls with the same inputs, whatever their case', () => {
+		const first = createPaletteGenerator( [ '#3858E9' ], '#FFFFFF', LABEL_COLORS );
+		expect( createPaletteGenerator( [ '#3858e9' ], '#ffffff', LABEL_COLORS ) ).toBe( first );
+		expect( createPaletteGenerator( [ '#3858e9' ], '#1e1e1e', LABEL_COLORS ) ).not.toBe( first );
+		expect( createPaletteGenerator( [ '#3858e9' ], '#ffffff' ) ).not.toBe( first );
+	} );
+
+	it( 'returns the same colors whatever order they are asked for in', () => {
+		const inOrder = paletteOf( [ '#3858e9' ], '#ffffff', 8 );
+		const colorAt = createPaletteGenerator( [ '#3858e9' ], '#ffffff', LABEL_COLORS );
+		expect( colorAt( 7 ) ).toBe( inOrder[ 7 ] );
+		expect( colorAt( 5 ) ).toBe( inOrder[ 5 ] );
+	} );
+
+	it( 'never repeats a seed or an earlier generated color', () => {
+		const palette = paletteOf( [ '#3858e9', '#e14d43', '#04a4cc' ], '#ffffff', 12 );
+		expect( new Set( palette ).size ).toBe( palette.length );
+	} );
+
+	it( 'still generates when no candidate reaches 3:1 against the background', () => {
+		const palette = paletteOf( [ '#3858e9' ], '#777777' );
+		palette.forEach( color => expect( color ).toMatch( /^#[0-9a-f]{6}$/ ) );
+		expect( new Set( palette ).size ).toBe( palette.length );
+	} );
+
+	it( 'generates from nothing when there are no seeds', () => {
+		const palette = paletteOf( [], '#ffffff', 3 );
+		palette.forEach( color => expect( color ).toMatch( /^#[0-9a-f]{6}$/ ) );
+		expect( minPairwiseDistance( palette ) ).toBeGreaterThanOrEqual( 15 );
+	} );
+
+	it( 'keeps generating past a small non-empty legible set without throwing', () => {
+		// #9b9b9b has 5 legible candidates in the grid, so asking for 10 falls back to the rest of it.
+		const palette = paletteOf( [], '#9b9b9b', 10 );
+		palette.forEach( color => expect( color ).toMatch( /^#[0-9a-f]{6}$/ ) );
+		expect( new Set( palette ).size ).toBe( palette.length );
+	} );
+
+	it( 'never regenerates a color equal to a seed', () => {
+		// #9b9b9b has exactly 5 legible candidates, so seeding one and asking for the rest of
+		// the pool (plus one more, which forces the first grid fallback) exhausts it deterministically.
+		const legible = paletteOf( [], '#9b9b9b', 5 );
+		const seed = legible[ 0 ];
+		const generated = paletteOf( [ seed ], '#9b9b9b', 6 ).slice( 1 );
+		expect( generated ).not.toContain( seed );
+	} );
+
+	it( 'excludes a seed from the grid even when it is given in uppercase', () => {
+		const legible = paletteOf( [], '#9b9b9b', 5 );
+		const seed = legible[ 0 ];
+		const generated = paletteOf( [ seed.toUpperCase() ], '#9b9b9b', 6 ).slice( 1 );
+		expect( generated ).not.toContain( seed );
+	} );
+
+	it( 'repeats rather than throws once the whole grid is used up', () => {
+		// The candidate grid holds roughly 2,757 distinct in-gamut colors; 3000 comfortably exceeds it.
+		const palette = paletteOf( [], '#ffffff', 3000 );
+		palette.forEach( color => expect( color ).toMatch( /^#[0-9a-f]{6}$/ ) );
+		const placedCount = new Set( palette ).size;
+		expect( placedCount ).toBeLessThan( palette.length );
+
+		// The repeats cycle through the colors placed before the grid ran out, not always the first.
+		expect( palette[ placedCount ] ).toBe( palette[ 0 ] );
+		expect( palette[ placedCount + 1 ] ).toBe( palette[ 1 ] );
+	} );
+} );

package/src/providers/chart-context/test/perceptual-color.test.ts

@@ -0,0 +1,75 @@
+import {
+	contrastRatio,
+	deltaE2000,
+	hexToOklch,
+	hexToViews,
+	oklchToHex,
+	viewDistance,
+} from '../private/perceptual-color';
+
+describe( 'deltaE2000', () => {
+	// Sharma, Wu and Dalal (2005) reference pairs.
+	it.each( [
+		[ [ 50, 2.6772, -79.7751 ], [ 50, 0, -82.7485 ], 2.0425 ],
+		[ [ 50, 2.5, 0 ], [ 50, 0, -2.5 ], 4.3065 ],
+		[ [ 50, 2.5, 0 ], [ 73, 25, -18 ], 27.1492 ],
+		[ [ 2.0776, 0.0795, -1.135 ], [ 0.9033, -0.0636, -0.5514 ], 0.9082 ],
+	] as const )( 'matches the reference value for %j vs %j', ( a, b, expected ) => {
+		expect( deltaE2000( a, b ) ).toBeCloseTo( expected, 4 );
+	} );
+
+	it( 'is zero for identical colors', () => {
+		expect( deltaE2000( [ 40, 10, -20 ], [ 40, 10, -20 ] ) ).toBe( 0 );
+	} );
+} );
+
+describe( 'viewDistance', () => {
+	it( 'collapses a red/green pair under color vision deficiency', () => {
+		const red = hexToViews( '#cc4444' );
+		const green = hexToViews( '#669900' );
+		const [ normal ] = red.map( ( view, i ) => deltaE2000( view, green[ i ] ) );
+		expect( normal ).toBeGreaterThan( 30 );
+		expect( viewDistance( red, green ) ).toBeLessThan( 15 );
+	} );
+
+	it( 'keeps a blue/orange pair apart in every view', () => {
+		expect( viewDistance( hexToViews( '#1f4bd0' ), hexToViews( '#dd823b' ) ) ).toBeGreaterThan(
+			30
+		);
+	} );
+} );
+
+describe( 'oklchToHex', () => {
+	it( 'converts an in-gamut color', () => {
+		expect( oklchToHex( 0.627955, 0.257683, 29.2339 ) ).toBe( '#ff0000' );
+	} );
+
+	it( 'returns null outside the sRGB gamut', () => {
+		expect( oklchToHex( 0.9, 0.3, 140 ) ).toBeNull();
+	} );
+} );
+
+describe( 'hexToOklch', () => {
+	it( 'is the inverse of oklchToHex', () => {
+		const { chroma, hue } = hexToOklch( '#ff0000' );
+		expect( chroma ).toBeCloseTo( 0.257683, 3 );
+		expect( hue ).toBeCloseTo( 29.2339, 1 );
+	} );
+
+	it( 'keeps hue between 0 and 360 for a color whose angle is negative', () => {
+		const { hue } = hexToOklch( '#ff00ff' );
+		expect( hue ).toBeGreaterThanOrEqual( 0 );
+		expect( hue ).toBeLessThan( 360 );
+	} );
+} );
+
+describe( 'contrastRatio', () => {
+	it( 'is 21 for black on white, in either order', () => {
+		expect( contrastRatio( '#000000', '#ffffff' ) ).toBeCloseTo( 21, 5 );
+		expect( contrastRatio( '#ffffff', '#000000' ) ).toBeCloseTo( 21, 5 );
+	} );
+
+	it( 'is 1 for identical colors', () => {
+		expect( contrastRatio( '#3858e9', '#3858e9' ) ).toBe( 1 );
+	} );
+} );

package/src/test-utils/zoned-parsing-suite.ts

@@ -1,6 +1,6 @@
 import { parseAsLocalDate } from '../utils/date-parsing';
 
-// `@wordpress/jest-console` registers the matcher but ships no types for it.
+// The `jetpack-js-tools` console guard registers the matcher but ships no types for it.
 declare global {
 	// eslint-disable-next-line @typescript-eslint/no-namespace
 	namespace jest {

package/src/utils/color-utils.ts

@@ -52,9 +52,11 @@ export const hexToRgba = ( hex: string, alpha: number ): string => {
 };
 
 /**
- * Calculate the perceptual distance between two HSL colors
- * @param hsl1 - first color in HSL format [h, s, l]
- * @param hsl2 - second color in HSL format [h, s, l]
+ * Weighted Euclidean distance between two HSL colors.
+ *
+ * @deprecated Not perceptual and blind to color vision deficiency, so charts no longer use it; it will be removed in a future major version.
+ * @param      hsl1 - first color in HSL format [h, s, l]
+ * @param      hsl2 - second color in HSL format [h, s, l]
  * @return distance value (0-100+, lower means more similar)
  */
 export const getColorDistance = (

package/src/utils/test/date-formatting.test.ts

@@ -1,6 +1,6 @@
 import { createDateFormatter, createZonedClock, sanitizeFormatting } from '../date-formatting';
 
-// `@wordpress/jest-console` registers the matcher but ships no types for it.
+// The `jetpack-js-tools` console guard registers the matcher but ships no types for it.
 declare global {
 	// eslint-disable-next-line @typescript-eslint/no-namespace
 	namespace jest {