@wordpress/theme 0.1.1-next.2f1c7c01b.0 → 0.2.0

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

@@ -7,16 +7,22 @@ import { get, OKLCH, type ColorTypes } from 'colorjs.io/fn';
  * Internal dependencies
  */
 import './register-color-spaces';
-import { clampToGamut } from './utils';
-import {
-	WHITE,
-	BLACK,
-	LIGHTNESS_EPSILON,
-	MAX_BISECTION_ITERATIONS,
-} from './constants';
+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
@@ -28,7 +34,6 @@ import { type TaperChromaOptions, taperChroma } from './taper-chroma';
  * @param target
  * @param direction
  * @param options
- * @param options.strict
  * @param options.lightnessConstraint
  * @param options.lightnessConstraint.type
  * @param options.lightnessConstraint.value
@@ -42,20 +47,22 @@ export function findColorMeetingRequirements(
 	{
 		lightnessConstraint,
 		taperChromaOptions,
-		strict = true,
 	}: {
 		lightnessConstraint?: {
 			type: 'force' | 'onlyIfSucceeds';
 			value: number;
 		};
 		taperChromaOptions?: TaperChromaOptions;
-		strict?: boolean;
 	} = {}
-): { color: ColorTypes; 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, reached: true, achieved: 1 };
+		return {
+			color: reference,
+			reached: true,
+			achieved: 1,
+		};
 	}
 
 	function getColorForL( l: number ): ColorTypes {
@@ -80,48 +87,45 @@ export function findColorMeetingRequirements(
 		} );
 	}
 
+	// 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 highestContrast = getContrast( reference, mostContrastingColor );
-
-	// If even the most contrasting color can't reach the target,
-	// the target is unreachable.
-	if ( highestContrast < target ) {
-		if ( strict ) {
-			throw new Error(
-				`Contrast target ${ target.toFixed(
-					2
-				) }:1 unreachable in ${ direction } direction` +
-					`(boundary achieves ${ highestContrast.toFixed( 3 ) }:1).`
-			);
-		}
-
+	// 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,
+			reached: cdiff( highestContrast, target ) >= -CONTRAST_EPSILON,
 			achieved: highestContrast,
+			deficit: cdiff( target, highestContrast ),
 		};
 	}
 
@@ -129,53 +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 = get( reference, [ OKLCH, 'l' ] );
-	let worseContrast = 1;
-	let replacedWorse = false;
-	let betterL = mostContrastingL;
-	let betterContrast = highestContrast;
-	let replacedBetter = false;
-
-	let bestColor: ColorTypes = mostContrastingColor;
-	let bestContrast = highestContrast;
-
-	for ( let i = 0; i < MAX_BISECTION_ITERATIONS; i++ ) {
-		// Linear interpolation between worse and better L values, weighted by the contrast difference.
-		const newL =
-			( worseL * ( betterContrast - target ) -
-				betterL * ( worseContrast - target ) ) /
-			( betterContrast - worseContrast );
-
-		bestColor = getColorForL( newL );
-		bestContrast = getContrast( reference, bestColor );
-
-		if ( Math.abs( bestContrast - target ) <= LIGHTNESS_EPSILON ) {
-			break;
-		}
-
-		// Update one of the boundary L values, using the Illinois method.
-		if ( bestContrast >= target ) {
-			betterL = newL;
-			betterContrast = bestContrast;
-			if ( replacedBetter ) {
-				worseContrast = ( worseContrast + target ) / 2;
-			}
-			replacedBetter = true;
-			replacedWorse = false;
-		} else {
-			worseL = newL;
-			worseContrast = bestContrast;
-			if ( replacedWorse ) {
-				betterContrast = ( betterContrast + target ) / 2;
-			}
-			replacedWorse = true;
-			replacedBetter = false;
-		}
-	}
+	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: bestColor,
 		reached: true,
-		achieved: bestContrast,
+		achieved: target,
+		// Negative number that specifies how much room we have.
+		deficit: cdiff( target, highestContrast ),
 	};
 }

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

@@ -22,6 +22,8 @@ import {
 	sortByDependency,
 	computeBetterFgColorDirection,
 	adjustContrastTarget,
+	stepsForStep,
+	solveWithBisect,
 } from './utils';
 
 import type {
@@ -31,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.
@@ -69,9 +71,9 @@ function calculateRamp( {
 		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.
@@ -85,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 }`
@@ -96,23 +98,27 @@ function calculateRamp( {
 		// Check if we can reuse color from the `sameAsIfPossible` config option
 		if ( sameAsIfPossible ) {
 			const candidateColor = calculatedColors.get( sameAsIfPossible );
-			if ( candidateColor ) {
-				const candidateContrast = getContrast(
-					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
 			}
 		}
 
@@ -166,7 +172,6 @@ function calculateRamp( {
 			adjustedTarget,
 			computedDir,
 			{
-				strict: false,
 				lightnessConstraint,
 				taperChromaOptions,
 			}
@@ -174,24 +179,14 @@ function calculateRamp( {
 
 		// 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 / getContrast( 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
@@ -204,11 +199,11 @@ function calculateRamp( {
 				! contrast.ignoreWhenAdjustingSeed && ! searchResults.reached,
 		};
 	}
-
 	return {
 		rampResults,
-		SATISFIED_ALL_CONTRAST_REQUIREMENTS,
-		UNSATISFIED_DIRECTION,
+		maxDeficit,
+		maxDeficitDirection,
+		maxDeficitStep,
 	};
 }
 
@@ -255,81 +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,
-	} );
-	const toReturn = {
-		ramp: rampResults,
-		direction: mainDir,
-	} as RampResult;
+	const { rampResults, maxDeficit, maxDeficitDirection, maxDeficitStep } =
+		calculateRamp( {
+			seed,
+			sortedSteps,
+			config,
+			mainDir,
+			oppDir,
+			pinLightness,
+		} );
 
-	if (
-		! SATISFIED_ALL_CONTRAST_REQUIREMENTS &&
-		rescaleToFitContrastTargets
-	) {
-		let worseSeedL = get( 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(
-				set(
-					clone( seed ),
-					[ OKLCH, 'l' ],
-					( worseSeedL + betterSeedL ) / 2
-				)
-			);
+	let bestRamp = rampResults;
 
+	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,
 			} );
 
-			if ( iterationResults.SATISFIED_ALL_CONTRAST_REQUIREMENTS ) {
-				betterSeedL = get( 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 = get( 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 = get( newSeed, [ OKLCH, 'l' ] );
-			}
+			// 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,
 	},

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

@@ -13,8 +13,10 @@ import {
 	UNIVERSAL_CONTRAST_TOPUP,
 	WHITE_TEXT_CONTRAST_MARGIN,
 	ACCENT_SCALE_BASE_LIGHTNESS_THRESHOLDS,
+	MAX_BISECTION_ITERATIONS,
+	CONTRAST_EPSILON,
 } from './constants';
-import type { Ramp, RampStepConfig, RampDirection } from './types';
+import type { Ramp, RampConfig, RampDirection } from './types';
 import { getContrast } from './color-utils';
 
 /**
@@ -28,7 +30,7 @@ export const clampToGamut = ( c: ColorTypes ) =>
  * Build a dependency graph from the steps configuration
  * @param config - The steps configuration object
  */
-function buildDependencyGraph( config: Record< keyof Ramp, RampStepConfig > ): {
+function buildDependencyGraph( config: RampConfig ): {
 	dependencies: Map< keyof Ramp, ( keyof Ramp | 'seed' )[] >;
 	dependents: Map< keyof Ramp | 'seed', ( keyof Ramp )[] >;
 } {
@@ -66,9 +68,7 @@ function buildDependencyGraph( config: Record< keyof Ramp, RampStepConfig > ): {
  * Topologically sort steps based on their dependencies
  * @param config - The steps configuration object
  */
-export function sortByDependency(
-	config: Record< keyof Ramp, RampStepConfig >
-): ( keyof Ramp )[] {
+export function sortByDependency( config: RampConfig ): ( keyof Ramp )[] {
 	const { dependents } = buildDependencyGraph( config );
 	const result: ( keyof Ramp )[] = [];
 	const visited = new Set< keyof Ramp | 'seed' >();
@@ -108,6 +108,37 @@ export function sortByDependency(
 
 	return result;
 }
+/**
+ * Return minimal set of steps that are needed to calculate `stepName` from the seed.
+ * @param stepName Name of the step.
+ * @param config   Configuration of the ramp.
+ * @return Array of steps that `stepName` depends on.
+ */
+export function stepsForStep(
+	stepName: keyof Ramp,
+	config: RampConfig
+): ( keyof Ramp )[] {
+	const result = new Set< keyof Ramp >();
+	function visit( step: keyof Ramp | 'seed' ) {
+		if ( step === 'seed' || result.has( step ) ) {
+			return;
+		}
+
+		const stepConfig = config[ step ];
+		if ( ! stepConfig ) {
+			return;
+		}
+
+		visit( stepConfig.contrast.reference );
+		if ( stepConfig.sameAsIfPossible ) {
+			visit( stepConfig.sameAsIfPossible );
+		}
+
+		result.add( step );
+	}
+	visit( stepName );
+	return Array.from( result );
+}
 
 /**
  * Finds out whether a lighter or a darker foreground color achieves a better
@@ -158,3 +189,76 @@ export function clampAccentScaleReferenceLightness(
 	const thresholds = ACCENT_SCALE_BASE_LIGHTNESS_THRESHOLDS[ direction ];
 	return Math.max( thresholds.min, Math.min( thresholds.max, rawLightness ) );
 }
+
+/**
+ * Find the value of of `L` (luminance) that produces a `C` (color) that has a
+ * `value` (contrast delta) equal to zero.
+ * @param calculateC     Calculate `C` from a given `L`.
+ * @param calculateValue Calculate value (delta) for a given `C`.
+ * @param initLowerL     Initial lower value of `L`.
+ * @param initLowerValue Initial lower delta (negative).
+ * @param initUpperL     Initial upper value of `L`.
+ * @param initUpperValue Initial upper delta (positive).
+ * @return Resulting value of type `C`.
+ */
+export function solveWithBisect< C >(
+	calculateC: ( l: number ) => C,
+	calculateValue: ( t: C ) => number,
+	initLowerL: number,
+	initLowerValue: number,
+	initUpperL: number,
+	initUpperValue: number
+): C {
+	let lowerL = initLowerL;
+	let lowerValue = initLowerValue;
+	let lowerReplaced = false;
+
+	let upperL = initUpperL;
+	let upperValue = initUpperValue;
+	let upperReplaced = false;
+
+	let bestC: C;
+	let bestValue: number;
+	let iterations = 0;
+
+	while ( true ) {
+		iterations++;
+
+		// Linear interpolation: find the point where a line would cross the zero axis.
+		const newL =
+			( lowerL * upperValue - upperL * lowerValue ) /
+			( upperValue - lowerValue );
+
+		bestC = calculateC( newL );
+		bestValue = calculateValue( bestC );
+
+		if (
+			Math.abs( bestValue ) <= CONTRAST_EPSILON ||
+			iterations >= MAX_BISECTION_ITERATIONS
+		) {
+			break;
+		}
+
+		// Update the lower/upper bracket values. When only one side is repeatedly updated,
+		// apply so-called "Illinois trick" for faster convergence: halve the opposite value.
+		if ( bestValue <= 0 ) {
+			lowerL = newL;
+			lowerValue = bestValue;
+			if ( lowerReplaced ) {
+				upperValue /= 2;
+			}
+			lowerReplaced = true;
+			upperReplaced = false;
+		} else {
+			upperL = newL;
+			upperValue = bestValue;
+			if ( upperReplaced ) {
+				lowerValue /= 2;
+			}
+			upperReplaced = true;
+			lowerReplaced = false;
+		}
+	}
+
+	return bestC;
+}