@automattic/charts 4.4.0 → 4.6.0

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 {

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

@@ -1,223 +0,0 @@
-import { hsl as d3Hsl } from '@visx/vendor/d3-color';
-import { getColorDistance } from '../../../utils';
-
-export interface ColorCache {
-	colors: string[];
-	hues: number[];
-	existingHslColors: Array< [ number, number, number ] >;
-	minHue: number;
-	maxHue: number;
-}
-
-/**
- * Golden ratio for mathematically pleasing color distribution
- * Used to generate evenly spaced hues that are visually distinct
- */
-const GOLDEN_RATIO = 0.618033988749;
-
-/**
- * Minimum perceptual distance between colors to ensure visual distinction
- * Based on weighted HSL distance calculation optimized for chart readability
- */
-const MIN_COLOR_DISTANCE = 25;
-
-/**
- * Maximum attempts to find a sufficiently different color
- * Prevents infinite loops while allowing reasonable search space
- */
-const MAX_COLOR_GENERATION_ATTEMPTS = 50;
-
-/**
- * Color variation attempt offset
- * Small increment to explore slightly different color variations per attempt
- */
-const VARIATION_ATTEMPT_OFFSET = 0.1;
-
-// Saturation configuration for generated colors
-
-/**
- * Base saturation percentage for generated colors
- * 45% provides muted, professional colors without being washed out
- */
-const BASE_SATURATION = 45;
-
-/**
- * Number of saturation variation steps
- * Creates 3 different saturation levels for variety
- */
-const SATURATION_VARIATION_STEPS = 3;
-
-/**
- * Saturation increment per variation step
- * 10% increments provide subtle variation while keeping colors muted
- * Results in saturation levels: 45%, 55%, 65%
- */
-const SATURATION_INCREMENT = 10;
-
-// Lightness configuration for WCAG AA accessibility compliance
-
-/**
- * Base lightness percentage for generated colors
- * 35% ensures sufficient contrast against white backgrounds for WCAG AA compliance
- * WCAG AA requires 4.5:1 contrast ratio for normal text
- */
-const BASE_LIGHTNESS = 35;
-
-/**
- * Number of lightness variation steps
- * Creates 4 different lightness levels for variety
- */
-const LIGHTNESS_VARIATION_STEPS = 4;
-
-/**
- * Lightness increment per variation step
- * 8% increments provide subtle lightness variation while maintaining accessibility
- * Results in lightness levels: 35%, 43%, 51%, 59%
- * All levels maintain WCAG AA compliance against white backgrounds
- */
-const LIGHTNESS_INCREMENT = 8;
-
-// Hue range expansion and constraints
-
-/**
- * Minimum hue range in degrees to ensure sufficient color variety
- * 60 degrees provides reasonable color spread even for narrow palettes
- */
-const MIN_HUE_RANGE_DEGREES = 60;
-
-/**
- * Hue range expansion factor
- * 1.3x expansion provides slightly more variety than the original palette
- */
-const HUE_RANGE_EXPANSION_FACTOR = 1.3;
-
-/**
- * Threshold for detecting hue wrap-around (color wheel boundary crossing)
- * 180 degrees indicates the colors span more than half the color wheel
- */
-const HUE_WRAP_THRESHOLD_DEGREES = 180;
-
-/**
- * Full color wheel rotation in degrees
- */
-const FULL_HUE_ROTATION_DEGREES = 360;
-
-/**
- * Factor for single color hue range
- */
-const SINGLE_COLOR_HUE_RANGE_FACTOR = 0.33;
-
-/**
- * Get a color from the colors array or generate a new color using the golden ratio
- *
- * @param index      - the index of the color to get
- * @param colorCache - pre-computed color data for performance
- * @return a color from the colors array or a new color using the golden ratio
- */
-export const getChartColor = ( index: number, colorCache: ColorCache ): string => {
-	const {
-		colors,
-		hues,
-		existingHslColors,
-		minHue: cachedMinHue,
-		maxHue: cachedMaxHue,
-	} = colorCache;
-
-	if ( index < colors.length ) {
-		return colors[ index ];
-	}
-
-	let minHue = cachedMinHue;
-	let maxHue = cachedMaxHue;
-
-	// Generate additional colors using golden ratio, avoiding similar colors
-	for ( let attempt = 0; attempt < MAX_COLOR_GENERATION_ATTEMPTS; attempt++ ) {
-		// Calculate hue using golden ratio distribution with variation per attempt
-		// Formula: ((base_index + attempt_variation) * golden_ratio * 360°) mod 360°
-		// This ensures mathematically pleasing spacing while allowing slight shifts per attempt
-		let hue =
-			( ( index - colors.length + attempt * VARIATION_ATTEMPT_OFFSET ) *
-				GOLDEN_RATIO *
-				FULL_HUE_ROTATION_DEGREES ) %
-			FULL_HUE_ROTATION_DEGREES;
-
-		// If we have existing colors, constrain new colors to their hue range
-		if ( hues.length > 0 ) {
-			// Handle hue wrap-around (e.g., if colors span across 0 degrees)
-			let hueRange = maxHue - minHue;
-
-			// If there's only one color, use a set hue range for limited variety
-			if ( hues.length === 1 ) {
-				hueRange = FULL_HUE_ROTATION_DEGREES * SINGLE_COLOR_HUE_RANGE_FACTOR;
-			} else if ( hueRange > HUE_WRAP_THRESHOLD_DEGREES ) {
-				// If the range is very large, it might be wrapping around the color wheel
-				// Check if a smaller range exists when considering wrap-around
-				const altMinHue = Math.min( ...hues.filter( h => h > HUE_WRAP_THRESHOLD_DEGREES ) );
-				const altMaxHue =
-					Math.max( ...hues.filter( h => h < HUE_WRAP_THRESHOLD_DEGREES ) ) +
-					FULL_HUE_ROTATION_DEGREES;
-				const altRange = altMaxHue - altMinHue;
-
-				if ( altRange < hueRange ) {
-					minHue = altMinHue;
-					maxHue = altMaxHue;
-					hueRange = altRange;
-				}
-			}
-
-			// Expand the range slightly to provide some variation
-			const expandedRange = Math.max(
-				hueRange * HUE_RANGE_EXPANSION_FACTOR,
-				MIN_HUE_RANGE_DEGREES
-			);
-			const rangeCenter = ( minHue + maxHue ) / 2;
-			const expandedMin = rangeCenter - expandedRange / 2;
-
-			// Map the generated hue to the expanded range
-			hue = expandedMin + ( hue / FULL_HUE_ROTATION_DEGREES ) * expandedRange;
-
-			// Normalize to 0-360 range
-			hue =
-				( ( hue % FULL_HUE_ROTATION_DEGREES ) + FULL_HUE_ROTATION_DEGREES ) %
-				FULL_HUE_ROTATION_DEGREES;
-		}
-
-		const saturation =
-			BASE_SATURATION + ( ( index + attempt ) % SATURATION_VARIATION_STEPS ) * SATURATION_INCREMENT;
-		const lightness =
-			BASE_LIGHTNESS + ( ( index + attempt ) % LIGHTNESS_VARIATION_STEPS ) * LIGHTNESS_INCREMENT;
-
-		const candidateHsl: [ number, number, number ] = [ hue, saturation, lightness ];
-
-		// Check if this color is sufficiently different from existing colors
-		let isSufficientlyDifferent = true;
-		for ( const existingHsl of existingHslColors ) {
-			if ( getColorDistance( candidateHsl, existingHsl ) < MIN_COLOR_DISTANCE ) {
-				isSufficientlyDifferent = false;
-				break;
-			}
-		}
-
-		if ( isSufficientlyDifferent ) {
-			// d3-color uses 0-1 scale for saturation and lightness
-			return d3Hsl( Math.round( hue ), saturation / 100, lightness / 100 ).formatHex();
-		}
-	}
-
-	// Fallback if we couldn't find a sufficiently different color
-	// Formula: ((base_index) * golden_ratio * 360°) mod 360°
-	// This ensures mathematically pleasing spacing while maintaining consistency
-	const fallbackHue =
-		( ( index - colors.length ) * GOLDEN_RATIO * FULL_HUE_ROTATION_DEGREES ) %
-		FULL_HUE_ROTATION_DEGREES;
-	const fallbackSaturation =
-		BASE_SATURATION + ( index % SATURATION_VARIATION_STEPS ) * SATURATION_INCREMENT;
-	const fallbackLightness =
-		BASE_LIGHTNESS + ( index % LIGHTNESS_VARIATION_STEPS ) * LIGHTNESS_INCREMENT;
-	// d3-color uses 0-1 scale for saturation and lightness
-	return d3Hsl(
-		Math.round( fallbackHue ),
-		fallbackSaturation / 100,
-		fallbackLightness / 100
-	).formatHex();
-};