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

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

@@ -1,11 +1,12 @@
 /**
  * External dependencies
  */
-import Color from 'colorjs.io';
+import { get, OKLCH, type ColorTypes } from 'colorjs.io/fn';
 
 /**
  * Internal dependencies
  */
+import './register-color-spaces';
 import { clampToGamut } from './utils';
 import {
 	WHITE,
@@ -13,7 +14,7 @@ import {
 	LIGHTNESS_EPSILON,
 	MAX_BISECTION_ITERATIONS,
 } from './constants';
-import { getCachedContrast } from './cache-utils';
+import { getContrast } from './color-utils';
 import { type TaperChromaOptions, taperChroma } from './taper-chroma';
 
 /**
@@ -28,22 +29,20 @@ import { type TaperChromaOptions, taperChroma } from './taper-chroma';
  * @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';
@@ -51,43 +50,42 @@ export function findColorMeetingRequirements(
 		};
 		taperChromaOptions?: TaperChromaOptions;
 		strict?: boolean;
-		debug?: boolean;
 	} = {}
-): { color: Color; reached: boolean; achieved: number } {
+): { color: ColorTypes; reached: boolean; achieved: 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: seed, 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 );
-
-		if ( debug ) {
-			// eslint-disable-next-line no-console
-			console.log(
-				`Succeeded with ${ lightnessConstraint.type } lightness`,
-				lightnessConstraint.value,
-				colorWithExactL.oklch.l
-			);
-		}
+		return clampToGamut( {
+			spaceId: 'oklch',
+			coords: [ newL, newC, get( seed, [ OKLCH, 'h' ] ) ],
+		} );
+	}
+
+	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 );
 
 		// If the L constraint is of "force" type, apply it even when it doesn't
 		// meet the contrast target.
@@ -106,36 +104,24 @@ export function findColorMeetingRequirements(
 	// Set the boundary based on the direction.
 	const mostContrastingL = direction === 'lighter' ? 1 : 0;
 	const mostContrastingColor = direction === 'lighter' ? WHITE : BLACK;
-	const highestPossibleContrast = getCachedContrast(
-		reference,
-		mostContrastingColor
-	);
+	const highestContrast = getContrast( reference, mostContrastingColor );
 
 	// If even the most contrasting color can't reach the target,
 	// the target is unreachable.
-	if ( highestPossibleContrast < target ) {
+	if ( highestContrast < 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).`
+				) }:1 unreachable in ${ direction } direction` +
+					`(boundary achieves ${ highestContrast.toFixed( 3 ) }:1).`
 			);
 		}
 
-		if ( debug ) {
-			// eslint-disable-next-line no-console
-			console.log(
-				'Did not succeeded because it reached the limit',
-				mostContrastingL
-			);
-		}
 		return {
 			color: mostContrastingColor,
 			reached: false,
-			achieved: highestPossibleContrast,
+			achieved: highestContrast,
 		};
 	}
 
@@ -143,48 +129,53 @@ 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 worseL = get( reference, [ OKLCH, 'l' ] );
+	let worseContrast = 1;
+	let replacedWorse = false;
 	let betterL = mostContrastingL;
+	let betterContrast = highestContrast;
+	let replacedBetter = false;
 
-	let bestContrastFound = highestPossibleContrast;
-	let resultingColor = mostContrastingColor;
+	let bestColor: ColorTypes = mostContrastingColor;
+	let bestContrast = highestContrast;
 
-	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;
+	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 );
 
-		if ( taperChromaOptions ) {
-			( { l: newL, c: newC } = taperChroma(
-				seed,
-				newL,
-				taperChromaOptions
-			) );
-		}
+		bestColor = getColorForL( newL );
+		bestContrast = getContrast( reference, bestColor );
 
-		const newColor = clampToGamut(
-			new Color( 'oklch', [ newL, newC, seed.oklch.h ] )
-		);
-		const newContrast = getCachedContrast( reference, newColor );
+		if ( Math.abs( bestContrast - target ) <= LIGHTNESS_EPSILON ) {
+			break;
+		}
 
-		if ( newContrast >= target ) {
+		// Update one of the boundary L values, using the Illinois method.
+		if ( bestContrast >= 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;
+			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;
 		}
 	}
 
 	return {
-		color: resultingColor,
+		color: bestColor,
 		reached: true,
-		achieved: bestContrastFound,
+		achieved: bestContrast,
 	};
 }

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

@@ -1,12 +1,21 @@
 /**
  * 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,
@@ -36,7 +45,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 +54,8 @@ function calculateRamp( {
 	mainDir,
 	oppDir,
 	pinLightness,
-	debug = false,
 }: {
-	seed: Color;
+	seed: ColorTypes;
 	sortedSteps: ( keyof Ramp )[];
 	config: RampConfig;
 	mainDir: RampDirection;
@@ -57,7 +64,6 @@ function calculateRamp( {
 		stepName: keyof Ramp;
 		value: number;
 	};
-	debug?: boolean;
 } ) {
 	const rampResults = {} as Record<
 		keyof Ramp,
@@ -69,7 +75,7 @@ function calculateRamp( {
 
 	// 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 ) {
@@ -91,7 +97,7 @@ function calculateRamp( {
 		if ( sameAsIfPossible ) {
 			const candidateColor = calculatedColors.get( sameAsIfPossible );
 			if ( candidateColor ) {
-				const candidateContrast = getCachedContrast(
+				const candidateContrast = getContrast(
 					referenceColor,
 					candidateColor
 				);
@@ -111,7 +117,7 @@ function calculateRamp( {
 		}
 
 		function computeDirection(
-			color: Color,
+			color: ColorTypes,
 			followDirection: FollowDirection
 		): RampDirection {
 			if ( followDirection === 'main' ) {
@@ -163,7 +169,6 @@ function calculateRamp( {
 				strict: false,
 				lightnessConstraint,
 				taperChromaOptions,
-				debug,
 			}
 		);
 
@@ -179,7 +184,7 @@ function calculateRamp( {
 			// 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 impactWeight = 1 / getContrast( seed, referenceColor );
 			const weightedDeficit = deficitVsTarget * impactWeight;
 
 			// Track the most impactful failure for seed optimization
@@ -213,7 +218,6 @@ export function buildRamp(
 	{
 		mainDirection,
 		pinLightness,
-		debug = false,
 		rescaleToFitContrastTargets = true,
 	}: {
 		mainDirection?: RampDirection;
@@ -222,12 +226,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 }": ${
@@ -263,32 +266,17 @@ export function buildRamp(
 		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(),
-			sortedSteps,
-			config,
-			mainDir,
-			oppDir,
-			pinLightness,
-		} );
-	}
-
 	if (
 		! SATISFIED_ALL_CONTRAST_REQUIREMENTS &&
 		rescaleToFitContrastTargets
 	) {
-		let worseSeedL = seed.oklch.l;
+		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;
@@ -302,20 +290,13 @@ export function buildRamp(
 			i++
 		) {
 			const newSeed = clampToGamut(
-				seed.clone().set( {
-					l: ( worseSeedL + betterSeedL ) / 2,
-				} )
+				set(
+					clone( seed ),
+					[ OKLCH, 'l' ],
+					( worseSeedL + betterSeedL ) / 2
+				)
 			);
 
-			if ( debug ) {
-				// eslint-disable-next-line no-console
-				console.log( `Iteration ${ i }`, {
-					worseSeedL,
-					newSeedL: ( worseSeedL + betterSeedL ) / 2,
-					betterSeedL,
-				} );
-			}
-
 			const iterationResults = calculateRamp( {
 				seed: newSeed,
 				sortedSteps,
@@ -323,35 +304,20 @@ export function buildRamp(
 				mainDir,
 				oppDir,
 				pinLightness,
-				debug,
 			} );
 
 			if ( iterationResults.SATISFIED_ALL_CONTRAST_REQUIREMENTS ) {
-				betterSeedL = newSeed.oklch.l;
+				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 = newSeed.oklch.l;
+				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 = 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,
-				} );
+				worseSeedL = get( newSeed, [ OKLCH, 'l' ] );
 			}
 		}
 	}

package/src/color-ramps/lib/register-color-spaces.ts

@@ -0,0 +1,13 @@
+/**
+ * External dependencies
+ */
+import { ColorSpace, OKLCH, P3, sRGB, HSL } from 'colorjs.io/fn';
+
+// Ensures that all color spaces used in color ramps are registered globally, a
+// requirement for using colorjs.io's procedural API.
+//
+// See: https://colorjs.io/docs/procedural
+ColorSpace.register( sRGB );
+ColorSpace.register( OKLCH );
+ColorSpace.register( P3 );
+ColorSpace.register( HSL );

package/src/color-ramps/lib/taper-chroma.ts

@@ -1,8 +1,20 @@
-// npm i colorjs.io
 /**
  * External dependencies
  */
-import Color from 'colorjs.io';
+import {
+	get,
+	inGamut,
+	OKLCH,
+	P3,
+	sRGB,
+	type ColorTypes,
+	type ColorObject,
+} from 'colorjs.io/fn';
+
+/**
+ * Internal dependencies
+ */
+import './register-color-spaces';
 
 export interface TaperChromaOptions {
 	gamut?: 'p3' | 'srgb'; // target gamut (default "p3")
@@ -29,11 +41,12 @@ export interface TaperChromaOptions {
  * @param options
  */
 export function taperChroma(
-	seed: Color, // already OKLCH
+	seed: ColorTypes, // already OKLCH
 	lTarget: number, // [0..1]
 	options: TaperChromaOptions = {}
-): { l: number; c: number } {
+): { l: number; c: number } | ColorObject {
 	const gamut = options.gamut ?? 'p3';
+	const gamutSpace = gamut === 'p3' ? P3 : sRGB;
 	const alpha = options.alpha ?? 0.65; // 0.7-0.8 works well for accent surface
 	const carry = options.carry ?? 0.5;
 	const cUpperBound = options.cUpperBound ?? 0.45;
@@ -43,8 +56,8 @@ export function taperChroma(
 	const kDark = options.kDark ?? 0.85;
 	const achromaEpsilon = options.achromaEpsilon ?? 0.005;
 
-	const cSeed = Math.max( 0, seed.oklch.c );
-	let hSeed = Number( seed.oklch.h );
+	const cSeed = Math.max( 0, get( seed, [ OKLCH, 'c' ] ) );
+	let hSeed = Number( get( seed, [ OKLCH, 'h' ] ) );
 
 	const chromaIsTiny = cSeed < achromaEpsilon;
 	const hueIsInvalid = ! Number.isFinite( hSeed );
@@ -54,17 +67,25 @@ export function taperChroma(
 			hSeed = normalizeHue( options.hueFallback );
 		} else {
 			// Respect achromatic intent: grayscale at target L
-			return new Color( 'oklch', [ clamp01( lTarget ), 0, 0 ] );
+			return {
+				spaceId: 'oklch',
+				coords: [ clamp01( lTarget ), 0, 0 ],
+			};
 		}
 	}
 
 	// Capacity at seed and target
-	const lSeed = clamp01( seed.oklch.l );
-	const cmaxSeed = getCachedMaxChromaAtLH( lSeed, hSeed, gamut, cUpperBound );
+	const lSeed = clamp01( get( seed, [ OKLCH, 'l' ] ) );
+	const cmaxSeed = getCachedMaxChromaAtLH(
+		lSeed,
+		hSeed,
+		gamutSpace,
+		cUpperBound
+	);
 	const cmaxTarget = getCachedMaxChromaAtLH(
 		clamp01( lTarget ),
 		hSeed,
-		gamut,
+		gamutSpace,
 		cUpperBound
 	);
 
@@ -89,10 +110,13 @@ export function taperChroma(
 
 	// Downward-only clamp (preserve L & H)
 	const lOut = clamp01( lTarget );
-	const candidate = new Color( 'oklch', [ lOut, cPlanned, hSeed ] );
-	if ( ! candidate.inGamut( gamut ) ) {
+	const candidate: ColorTypes = {
+		spaceId: 'oklch',
+		coords: [ lOut, cPlanned, hSeed ],
+	};
+	if ( ! inGamut( candidate, gamutSpace ) ) {
 		const cap = Math.min( cPlanned, cUpperBound );
-		cPlanned = getCachedMaxChromaAtLH( lOut, hSeed, gamut, cap );
+		cPlanned = getCachedMaxChromaAtLH( lOut, hSeed, gamutSpace, cap );
 	}
 
 	cPlanned = Math.min( cPlanned, cSeed );
@@ -178,16 +202,17 @@ function quantize( x: number, step: number ): number {
 function getCachedMaxChromaAtLH(
 	l: number,
 	h: number,
-	gamut: 'p3' | 'srgb',
+	gamutSpace: typeof P3 | typeof sRGB,
 	cap: number
 ): number {
+	const gamut = gamutSpace === P3 ? 'p3' : 'srgb';
 	const key = keyMax( l, h, gamut, cap );
 	const hit = maxChromaCache.get( key );
 	if ( typeof hit === 'number' ) {
 		return hit;
 	}
 
-	const computed = maxInGamutChromaAtLH( l, h, gamut, cap );
+	const computed = maxInGamutChromaAtLH( l, h, gamutSpace, cap );
 	maxChromaCache.set( key, computed );
 	return computed;
 }
@@ -196,13 +221,13 @@ function getCachedMaxChromaAtLH(
  * Binary-search the max in-gamut chroma at fixed (L,H) in the target gamut
  * @param l
  * @param h
- * @param gamut
+ * @param gamutSpace
  * @param cap
  */
 function maxInGamutChromaAtLH(
 	l: number,
 	h: number,
-	gamut: 'p3' | 'srgb',
+	gamutSpace: typeof P3 | typeof sRGB,
 	cap: number
 ): number {
 	let lo = 0;
@@ -214,8 +239,11 @@ function maxInGamutChromaAtLH(
 
 	for ( let i = 0; i < 18; i++ ) {
 		const mid = ( lo + hi ) / 2;
-		const probe = new Color( 'oklch', [ lFixed, mid, hFixed ] );
-		if ( probe.inGamut( gamut ) ) {
+		const probe: ColorTypes = {
+			spaceId: 'oklch',
+			coords: [ lFixed, mid, hFixed ],
+		};
+		if ( inGamut( probe, gamutSpace ) ) {
 			ok = mid;
 			lo = mid;
 		} else {

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

@@ -1,11 +1,12 @@
 /**
  * External dependencies
  */
-import type Color from 'colorjs.io';
+import { toGamut, to, P3, OKLCH, type ColorTypes } from 'colorjs.io/fn';
 
 /**
  * Internal dependencies
  */
+import './register-color-spaces';
 import {
 	WHITE,
 	BLACK,
@@ -14,16 +15,14 @@ import {
 	ACCENT_SCALE_BASE_LIGHTNESS_THRESHOLDS,
 } from './constants';
 import type { Ramp, RampStepConfig, RampDirection } from './types';
-import { getCachedContrast } from './cache-utils';
+import { getContrast } from './color-utils';
 
 /**
  * Make sure that a color is valid in the p3 gamut, and converts it to oklch.
  * @param c
  */
-export const clampToGamut = ( c: Color ) =>
-	c
-		.toGamut( { space: 'p3', method: 'css' } ) // map into Display-P3 using CSS OKLCH method
-		.to( 'oklch' );
+export const clampToGamut = ( c: ColorTypes ) =>
+	to( toGamut( c, { space: P3, method: 'css' } ), OKLCH ); // map into Display-P3 using CSS OKLCH method
 
 /**
  * Build a dependency graph from the steps configuration
@@ -119,14 +118,14 @@ export function sortByDependency(
  * ramp direction value.
  */
 export function computeBetterFgColorDirection(
-	seed: Color,
+	seed: ColorTypes,
 	preferLighter?: boolean
 ): {
 	better: RampDirection;
 	worse: RampDirection;
 } {
-	const contrastAgainstBlack = getCachedContrast( seed, BLACK );
-	const contrastAgainstWhite = getCachedContrast( seed, WHITE );
+	const contrastAgainstBlack = getContrast( seed, BLACK );
+	const contrastAgainstWhite = getContrast( seed, WHITE );
 
 	return contrastAgainstBlack >
 		contrastAgainstWhite +