@wordpress/theme 0.1.0 → 0.2.0

package/src/color-ramps/lib/find-color-with-constraints.ts

@@ -1,21 +1,28 @@
 /**
  * External dependencies
  */
-import Color from 'colorjs.io';
+import { get, OKLCH, type ColorTypes } from 'colorjs.io/fn';
 
 /**
  * Internal dependencies
  */
-import { clampToGamut } from './utils';
-import {
-	WHITE,
-	BLACK,
-	LIGHTNESS_EPSILON,
-	MAX_BISECTION_ITERATIONS,
-} from './constants';
-import { getCachedContrast } from './cache-utils';
+import './register-color-spaces';
+import { clampToGamut, solveWithBisect } from './utils';
+import { WHITE, BLACK, CONTRAST_EPSILON } from './constants';
+import { getContrast } from './color-utils';
 import { type TaperChromaOptions, taperChroma } from './taper-chroma';
 
+/**
+ * Difference of contrast values that grows linearly with the Y luminance.
+ * We get more precise linear interpolations when we use this.
+ * @param c1 First contrast.
+ * @param c2 Second contrast.
+ * @return Difference of logarithms.
+ */
+function cdiff( c1: number, c2: number ) {
+	return Math.log( c1 / c2 );
+}
+
 /**
  * Solve for L such that:
  *  - the L applied to the seed meets the contrast target against the reference
@@ -27,115 +34,98 @@ import { type TaperChromaOptions, taperChroma } from './taper-chroma';
  * @param target
  * @param direction
  * @param options
- * @param options.strict
- * @param options.debug
  * @param options.lightnessConstraint
  * @param options.lightnessConstraint.type
  * @param options.lightnessConstraint.value
  * @param options.taperChromaOptions
  */
 export function findColorMeetingRequirements(
-	reference: Color,
-	seed: Color,
+	reference: ColorTypes,
+	seed: ColorTypes,
 	target: number,
 	direction: 'lighter' | 'darker',
 	{
 		lightnessConstraint,
 		taperChromaOptions,
-		strict = true,
-		debug = false,
 	}: {
 		lightnessConstraint?: {
 			type: 'force' | 'onlyIfSucceeds';
 			value: number;
 		};
 		taperChromaOptions?: TaperChromaOptions;
-		strict?: boolean;
-		debug?: boolean;
 	} = {}
-): { color: Color; reached: boolean; achieved: number } {
+): { color: ColorTypes; reached: boolean; achieved: number; deficit?: number } {
 	// A target of 1 means same color.
 	// A target lower than 1 doesn't make sense.
 	if ( target <= 1 ) {
-		return { color: seed.clone(), reached: true, achieved: 1 };
+		return {
+			color: reference,
+			reached: true,
+			achieved: 1,
+		};
 	}
 
-	if ( lightnessConstraint ) {
-		// Apply a specific L value.
-		// Useful when pinning a step to a specific lightness, of to specify
-		// min/max L values.
-		let newL = lightnessConstraint.value;
-		let newC = seed.oklch.c;
+	function getColorForL( l: number ): ColorTypes {
+		let newL = l;
+		let newC = get( seed, [ OKLCH, 'c' ] );
 
 		if ( taperChromaOptions ) {
-			( { l: newL, c: newC } = taperChroma(
-				seed,
-				newL,
-				taperChromaOptions
-			) );
+			const tapered = taperChroma( seed, newL, taperChromaOptions );
+			// taperChroma returns either { l, c } or a ColorObject
+			if ( 'l' in tapered && 'c' in tapered ) {
+				newL = tapered.l;
+				newC = tapered.c;
+			} else {
+				// It's already a ColorObject, return it directly
+				return tapered;
+			}
 		}
 
-		const colorWithExactL = clampToGamut(
-			new Color( 'oklch', [ newL, newC, seed.oklch.h ] )
-		);
-		const exactLContrast = getCachedContrast( reference, colorWithExactL );
+		return clampToGamut( {
+			spaceId: 'oklch',
+			coords: [ newL, newC, get( seed, [ OKLCH, 'h' ] ) ],
+		} );
+	}
 
-		if ( debug ) {
-			// eslint-disable-next-line no-console
-			console.log(
-				`Succeeded with ${ lightnessConstraint.type } lightness`,
-				lightnessConstraint.value,
-				colorWithExactL.oklch.l
-			);
-		}
+	// Set the boundary based on the direction.
+	const mostContrastingL = direction === 'lighter' ? 1 : 0;
+	const mostContrastingColor = direction === 'lighter' ? WHITE : BLACK;
+	const highestContrast = getContrast( reference, mostContrastingColor );
+
+	if ( lightnessConstraint ) {
+		// Apply a specific L value.
+		// Useful when pinning a step to a specific lightness, of to specify
+		// min/max L values.
+		const colorWithExactL = getColorForL( lightnessConstraint.value );
+		const exactLContrast = getContrast( reference, colorWithExactL );
+		const exactLContrastMeetsTarget =
+			cdiff( exactLContrast, target ) >= -CONTRAST_EPSILON;
 
 		// If the L constraint is of "force" type, apply it even when it doesn't
 		// meet the contrast target.
 		if (
-			lightnessConstraint.type === 'force' ||
-			exactLContrast >= target
+			exactLContrastMeetsTarget ||
+			lightnessConstraint.type === 'force'
 		) {
 			return {
 				color: colorWithExactL,
-				reached: exactLContrast >= target,
+				reached: exactLContrastMeetsTarget,
 				achieved: exactLContrast,
+				deficit: exactLContrastMeetsTarget
+					? cdiff( exactLContrast, highestContrast )
+					: cdiff( target, exactLContrast ),
 			};
 		}
 	}
 
-	// Set the boundary based on the direction.
-	const mostContrastingL = direction === 'lighter' ? 1 : 0;
-	const mostContrastingColor = direction === 'lighter' ? WHITE : BLACK;
-	const highestPossibleContrast = getCachedContrast(
-		reference,
-		mostContrastingColor
-	);
-
-	// If even the most contrasting color can't reach the target,
-	// the target is unreachable.
-	if ( highestPossibleContrast < target ) {
-		if ( strict ) {
-			throw new Error(
-				`Contrast target ${ target.toFixed(
-					2
-				) }:1 unreachable in ${ direction } direction against ${ mostContrastingColor.toString() }` +
-					`(boundary achieves ${ highestPossibleContrast.toFixed(
-						3
-					) }:1).`
-			);
-		}
-
-		if ( debug ) {
-			// eslint-disable-next-line no-console
-			console.log(
-				'Did not succeeded because it reached the limit',
-				mostContrastingL
-			);
-		}
+	// If even the most contrasting color can't reach the target, the target is unreachable.
+	// On the other hand, if the contrast is very close to the target, we consider it reached.
+	if ( cdiff( highestContrast, target ) <= CONTRAST_EPSILON ) {
 		return {
 			color: mostContrastingColor,
-			reached: false,
-			achieved: highestPossibleContrast,
+			reached: cdiff( highestContrast, target ) >= -CONTRAST_EPSILON,
+			achieved: highestContrast,
+			deficit: cdiff( target, highestContrast ),
 		};
 	}
 
@@ -143,48 +133,25 @@ export function findColorMeetingRequirements(
 	// Originally this was seed.oklch.l — although it's an assumption that works
 	// only when we know for sure the direction of the search.
 	// TODO: can we bring this back to seed.oklch.l ?
-	let worseL = reference.oklch.l;
-	let betterL = mostContrastingL;
-
-	let bestContrastFound = highestPossibleContrast;
-	let resultingColor = mostContrastingColor;
-
-	for (
-		let i = 0;
-		i < MAX_BISECTION_ITERATIONS &&
-		Math.abs( betterL - worseL ) > LIGHTNESS_EPSILON;
-		i++
-	) {
-		let newL = ( worseL + betterL ) / 2;
-		let newC = seed.oklch.c;
-
-		if ( taperChromaOptions ) {
-			( { l: newL, c: newC } = taperChroma(
-				seed,
-				newL,
-				taperChromaOptions
-			) );
-		}
-
-		const newColor = clampToGamut(
-			new Color( 'oklch', [ newL, newC, seed.oklch.h ] )
-		);
-		const newContrast = getCachedContrast( reference, newColor );
-
-		if ( newContrast >= target ) {
-			betterL = newL;
-			// Only update the resulting color when the target is met, this ensuring
-			// at the end of the search the target is always met.
-			bestContrastFound = newContrast;
-			resultingColor = newColor;
-		} else {
-			worseL = newL;
-		}
-	}
+	const lowerL = get( reference, [ OKLCH, 'l' ] );
+	const lowerContrast = cdiff( 1, target );
+	const upperL = mostContrastingL;
+	const upperContrast = cdiff( highestContrast, target );
+
+	const bestColor = solveWithBisect(
+		getColorForL,
+		( c: ColorTypes ) => cdiff( getContrast( reference, c ), target ),
+		lowerL,
+		lowerContrast,
+		upperL,
+		upperContrast
+	);
 
 	return {
-		color: resultingColor,
+		color: bestColor,
 		reached: true,
-		achieved: bestContrastFound,
+		achieved: target,
+		// Negative number that specifies how much room we have.
+		deficit: cdiff( target, highestContrast ),
 	};
 }

package/src/color-ramps/lib/index.ts

@@ -1,18 +1,29 @@
 /**
  * External dependencies
  */
-import Color from 'colorjs.io';
+import {
+	clone,
+	get,
+	OKLCH,
+	parse,
+	set,
+	type ColorTypes,
+	type PlainColorObject,
+} from 'colorjs.io/fn';
 
 /**
  * Internal dependencies
  */
-import { getCachedContrast, getColorString } from './cache-utils';
+import './register-color-spaces';
+import { getContrast, getColorString } from './color-utils';
 import { findColorMeetingRequirements } from './find-color-with-constraints';
 import {
 	clampToGamut,
 	sortByDependency,
 	computeBetterFgColorDirection,
 	adjustContrastTarget,
+	stepsForStep,
+	solveWithBisect,
 } from './utils';
 
 import type {
@@ -22,7 +33,7 @@ import type {
 	RampConfig,
 	RampResult,
 } from './types';
-import { LIGHTNESS_EPSILON, MAX_BISECTION_ITERATIONS } from './constants';
+import { CONTRAST_EPSILON } from './constants';
 
 /**
  * Calculate a complete color ramp based on the provided configuration.
@@ -36,7 +47,6 @@ import { LIGHTNESS_EPSILON, MAX_BISECTION_ITERATIONS } from './constants';
  * @param params.pinLightness          - Optional lightness override for a given step
  * @param params.pinLightness.stepName
  * @param params.pinLightness.value
- * @param params.debug
  * @return Object containing ramp results and satisfaction status
  */
 function calculateRamp( {
@@ -46,9 +56,8 @@ function calculateRamp( {
 	mainDir,
 	oppDir,
 	pinLightness,
-	debug = false,
 }: {
-	seed: Color;
+	seed: ColorTypes;
 	sortedSteps: ( keyof Ramp )[];
 	config: RampConfig;
 	mainDir: RampDirection;
@@ -57,19 +66,18 @@ function calculateRamp( {
 		stepName: keyof Ramp;
 		value: number;
 	};
-	debug?: boolean;
 } ) {
 	const rampResults = {} as Record<
 		keyof Ramp,
 		{ color: string; warning: boolean }
 	>;
-	let SATISFIED_ALL_CONTRAST_REQUIREMENTS = true;
-	let UNSATISFIED_DIRECTION: RampDirection = 'lighter';
-	let MAX_WEIGHTED_DEFICIT = 0;
+	let maxDeficit = -Infinity;
+	let maxDeficitDirection: RampDirection = 'lighter';
+	let maxDeficitStep;
 
 	// Keep track of the calculated colors, as they are going to be useful
 	// when other colors reference them.
-	const calculatedColors = new Map< keyof Ramp | 'seed', Color >();
+	const calculatedColors = new Map< keyof Ramp | 'seed', ColorTypes >();
 	calculatedColors.set( 'seed', seed );
 
 	for ( const stepName of sortedSteps ) {
@@ -79,8 +87,8 @@ function calculateRamp( {
 			taperChromaOptions,
 			sameAsIfPossible,
 		} = config[ stepName ];
-		const referenceColor = calculatedColors.get( contrast.reference );
 
+		const referenceColor = calculatedColors.get( contrast.reference );
 		if ( ! referenceColor ) {
 			throw new Error(
 				`Reference color for step ${ stepName } not found: ${ contrast.reference }`
@@ -90,28 +98,32 @@ function calculateRamp( {
 		// Check if we can reuse color from the `sameAsIfPossible` config option
 		if ( sameAsIfPossible ) {
 			const candidateColor = calculatedColors.get( sameAsIfPossible );
-			if ( candidateColor ) {
-				const candidateContrast = getCachedContrast(
-					referenceColor,
-					candidateColor
+			if ( ! candidateColor ) {
+				throw new Error(
+					`Same-as color for step ${ stepName } not found: ${ sameAsIfPossible }`
 				);
-				const adjustedTarget = adjustContrastTarget( contrast.target );
-				// If the candidate meets the contrast requirement, use it
-				if ( candidateContrast >= adjustedTarget ) {
-					// Store the reused color
-					calculatedColors.set( stepName, candidateColor );
-					rampResults[ stepName ] = {
-						color: getColorString( candidateColor ),
-						warning: false,
-					};
-
-					continue; // Skip to next step
-				}
+			}
+
+			const candidateContrast = getContrast(
+				referenceColor,
+				candidateColor
+			);
+			const adjustedTarget = adjustContrastTarget( contrast.target );
+			// If the candidate meets the contrast requirement, use it
+			if ( candidateContrast >= adjustedTarget ) {
+				// Store the reused color
+				calculatedColors.set( stepName, candidateColor );
+				rampResults[ stepName ] = {
+					color: getColorString( candidateColor ),
+					warning: false,
+				};
+
+				continue; // Skip to next step
 			}
 		}
 
 		function computeDirection(
-			color: Color,
+			color: ColorTypes,
 			followDirection: FollowDirection
 		): RampDirection {
 			if ( followDirection === 'main' ) {
@@ -160,33 +172,21 @@ function calculateRamp( {
 			adjustedTarget,
 			computedDir,
 			{
-				strict: false,
 				lightnessConstraint,
 				taperChromaOptions,
-				debug,
 			}
 		);
 
 		// When the target contrast is not met, take note of it and use
 		// that information to guide the ramp calculation bisection.
-		if ( ! searchResults.reached && ! contrast.ignoreWhenAdjustingSeed ) {
-			SATISFIED_ALL_CONTRAST_REQUIREMENTS = false;
-
-			// Calculate constraint failure severity for seed optimization
-			// Use the relative deficit size, weighted by how changing the seed would impact this constraint
-			const deficitVsTarget = adjustedTarget - searchResults.achieved;
-
-			// Weight the deficit by how much seed adjustment would help this constraint
-			// If seed has low contrast vs reference, adjusting seed has high impact
-			// If seed has high contrast vs reference, adjusting seed has low impact
-			const impactWeight = 1 / getCachedContrast( seed, referenceColor );
-			const weightedDeficit = deficitVsTarget * impactWeight;
-
-			// Track the most impactful failure for seed optimization
-			if ( weightedDeficit > MAX_WEIGHTED_DEFICIT ) {
-				MAX_WEIGHTED_DEFICIT = weightedDeficit;
-				UNSATISFIED_DIRECTION = computedDir;
-			}
+		if (
+			! contrast.ignoreWhenAdjustingSeed &&
+			searchResults.deficit &&
+			searchResults.deficit > maxDeficit
+		) {
+			maxDeficit = searchResults.deficit;
+			maxDeficitDirection = computedDir;
+			maxDeficitStep = stepName;
 		}
 
 		// Store calculated color for future dependencies
@@ -199,11 +199,11 @@ function calculateRamp( {
 				! contrast.ignoreWhenAdjustingSeed && ! searchResults.reached,
 		};
 	}
-
 	return {
 		rampResults,
-		SATISFIED_ALL_CONTRAST_REQUIREMENTS,
-		UNSATISFIED_DIRECTION,
+		maxDeficit,
+		maxDeficitDirection,
+		maxDeficitStep,
 	};
 }
 
@@ -213,7 +213,6 @@ export function buildRamp(
 	{
 		mainDirection,
 		pinLightness,
-		debug = false,
 		rescaleToFitContrastTargets = true,
 	}: {
 		mainDirection?: RampDirection;
@@ -222,12 +221,11 @@ export function buildRamp(
 			value: number;
 		};
 		rescaleToFitContrastTargets?: boolean;
-		debug?: boolean;
 	} = {}
 ): RampResult {
-	let seed: Color;
+	let seed: PlainColorObject;
 	try {
-		seed = clampToGamut( new Color( seedArg ) );
+		seed = clampToGamut( parse( seedArg ) );
 	} catch ( error ) {
 		throw new Error(
 			`Invalid seed color "${ seedArg }": ${
@@ -252,118 +250,82 @@ export function buildRamp(
 	const sortedSteps = sortByDependency( config );
 
 	// Calculate the ramp with the initial seed.
-	const {
-		rampResults,
-		SATISFIED_ALL_CONTRAST_REQUIREMENTS,
-		UNSATISFIED_DIRECTION,
-	} = calculateRamp( {
-		seed,
-		sortedSteps,
-		config,
-		mainDir,
-		oppDir,
-		pinLightness,
-		debug,
-	} );
-	const toReturn = {
-		ramp: rampResults,
-		direction: mainDir,
-	} as RampResult;
-
-	if ( debug ) {
-		// eslint-disable-next-line no-console
-		console.log( `First run`, {
-			SATISFIED_ALL_CONTRAST_REQUIREMENTS,
-			UNSATISFIED_DIRECTION,
-			seed: seed.toString(),
+	const { rampResults, maxDeficit, maxDeficitDirection, maxDeficitStep } =
+		calculateRamp( {
+			seed,
 			sortedSteps,
 			config,
 			mainDir,
 			oppDir,
 			pinLightness,
 		} );
-	}
 
-	if (
-		! SATISFIED_ALL_CONTRAST_REQUIREMENTS &&
-		rescaleToFitContrastTargets
-	) {
-		let worseSeedL = seed.oklch.l;
-		// For a scale with the "lighter" direction, the contrast can be improved
-		// by darkening the seed. For "darker" direction, by lightening the seed.
-		let betterSeedL = UNSATISFIED_DIRECTION === 'lighter' ? 0 : 1;
-
-		// Binary search: try a new seed and recompute the whole ramp
-		// (TODO: try a smarter approach?)
-		for (
-			let i = 0;
-			i < MAX_BISECTION_ITERATIONS &&
-			Math.abs( betterSeedL - worseSeedL ) > LIGHTNESS_EPSILON;
-			i++
-		) {
-			const newSeed = clampToGamut(
-				seed.clone().set( {
-					l: ( worseSeedL + betterSeedL ) / 2,
-				} )
-			);
+	let bestRamp = rampResults;
 
-			if ( debug ) {
-				// eslint-disable-next-line no-console
-				console.log( `Iteration ${ i }`, {
-					worseSeedL,
-					newSeedL: ( worseSeedL + betterSeedL ) / 2,
-					betterSeedL,
-				} );
-			}
+	if ( maxDeficit > CONTRAST_EPSILON && rescaleToFitContrastTargets ) {
+		const iterSteps = stepsForStep( maxDeficitStep!, config );
 
+		function getSeedForL( l: number ): ColorTypes {
+			return clampToGamut( set( clone( seed ), [ OKLCH, 'l' ], l ) );
+		}
+
+		function getDeficitForSeed( s: ColorTypes ): number {
 			const iterationResults = calculateRamp( {
-				seed: newSeed,
-				sortedSteps,
+				seed: s,
+				sortedSteps: iterSteps,
 				config,
 				mainDir,
 				oppDir,
 				pinLightness,
-				debug,
 			} );
 
-			if ( iterationResults.SATISFIED_ALL_CONTRAST_REQUIREMENTS ) {
-				betterSeedL = newSeed.oklch.l;
-				// Only update toReturn when the ramp satisfies all constraints.
-				toReturn.ramp = iterationResults.rampResults;
-			} else if ( UNSATISFIED_DIRECTION !== mainDir ) {
-				// Failing constraint is in opposite direction to main ramp direction
-				// We've moved too far in mainDir, constrain the search
-				betterSeedL = newSeed.oklch.l;
-			} else {
-				// Failing constraint is in same direction as main ramp direction
-				// We haven't moved far enough in mainDir, continue searching
-				worseSeedL = newSeed.oklch.l;
-			}
-
-			if ( debug ) {
-				// eslint-disable-next-line no-console
-				console.log( `Retry #${ i }`, {
-					SATISFIED_ALL_CONTRAST_REQUIREMENTS,
-					UNSATISFIED_DIRECTION,
-					seed: newSeed.toString(),
-					sortedSteps,
-					config,
-					mainDir,
-					oppDir,
-					pinLightness,
-				} );
-			}
+			// If the constraints start failing in the opposite direction to the original
+			// iteration's direction, that means we've moved too far away from the target.
+			// Don't use the `maxDeficit` value because it's not related to our search,
+			// and might even be positive, which would confuse the bisection algorithm.
+			return iterationResults.maxDeficitDirection === maxDeficitDirection
+				? iterationResults.maxDeficit
+				: -maxDeficit;
 		}
+
+		// For a scale with the "lighter" direction, the contrast can be improved
+		// by darkening the seed. For "darker" direction, by lightening the seed.
+		const lowerSeedL = maxDeficitDirection === 'lighter' ? 0 : 1;
+		const lowerDeficit = -maxDeficit;
+		const upperSeedL = get( seed, [ OKLCH, 'l' ] );
+		const upperDeficit = maxDeficit;
+
+		const bestSeed = solveWithBisect(
+			getSeedForL,
+			getDeficitForSeed,
+			lowerSeedL,
+			lowerDeficit,
+			upperSeedL,
+			upperDeficit
+		);
+
+		// Calculate the final ramp with adjusted seed.
+		bestRamp = calculateRamp( {
+			seed: bestSeed,
+			sortedSteps,
+			config,
+			mainDir,
+			oppDir,
+			pinLightness,
+		} ).rampResults;
 	}
 
 	// Swap surface1 and surface3 for darker ramps to maintain visual elevation hierarchy.
 	// This ensures surface1 appears "behind" surface2, and surface3 appears "in front",
 	// regardless of the ramp's main direction.
 	if ( mainDir === 'darker' ) {
-		const tmpSurface1 = toReturn.ramp.surface1;
-		toReturn.ramp.surface1 = toReturn.ramp.surface3;
-		toReturn.ramp.surface3 = tmpSurface1;
+		const tmpSurface1 = bestRamp.surface1;
+		bestRamp.surface1 = bestRamp.surface3;
+		bestRamp.surface3 = tmpSurface1;
 	}
 
-	return toReturn;
+	return {
+		ramp: bestRamp,
+		direction: mainDir,
+	};
 }

package/src/color-ramps/lib/ramp-configs.ts

@@ -59,7 +59,7 @@ export const BG_RAMP_CONFIG: RampConfig = {
 		contrast: {
 			reference: 'surface2',
 			followDirection: 'opposite',
-			target: 1.02,
+			target: 1.06,
 			ignoreWhenAdjustingSeed: true,
 		},
 		taperChromaOptions: BG_SURFACE_TAPER_CHROMA,
@@ -75,7 +75,7 @@ export const BG_RAMP_CONFIG: RampConfig = {
 		contrast: {
 			reference: 'surface2',
 			followDirection: 'main',
-			target: 1.02,
+			target: 1.06,
 		},
 		taperChromaOptions: BG_SURFACE_TAPER_CHROMA,
 	},
@@ -83,7 +83,7 @@ export const BG_RAMP_CONFIG: RampConfig = {
 		contrast: {
 			reference: 'surface2',
 			followDirection: 'main',
-			target: 1.08,
+			target: 1.12,
 		},
 		taperChromaOptions: BG_SURFACE_TAPER_CHROMA,
 	},