@wordpress/theme 0.1.0

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

@@ -0,0 +1,56 @@
+/**
+ * External dependencies
+ */
+import type Color from 'colorjs.io';
+
+/**
+ * Cache for WCAG contrast calculations
+ */
+const contrastCache = new Map< string, number >();
+
+/**
+ * Cache for color string representations
+ */
+const colorStringCache = new Map< Color, string >();
+
+/**
+ * Get cached string representation of a color
+ * @param color - Color object to stringify
+ * @return Cached string representation
+ */
+export function getColorString( color: Color ): string {
+	let str = colorStringCache.get( color );
+	if ( str === undefined ) {
+		str = color.to( 'srgb' ).toString( { format: 'hex', inGamut: true } );
+		colorStringCache.set( color, str );
+	}
+	return str;
+}
+
+/**
+ * Get cached contrast calculation between two colors
+ * @param colorA - First color
+ * @param colorB - Second color
+ * @return WCAG 2.1 contrast ratio
+ */
+export function getCachedContrast( colorA: Color, colorB: Color ): number {
+	const keyA = getColorString( colorA );
+	const keyB = getColorString( colorB );
+	const cacheKey =
+		keyA < keyB ? `${ keyA }|${ keyB }` : `${ keyB }|${ keyA }`;
+
+	let contrast = contrastCache.get( cacheKey );
+	if ( contrast === undefined ) {
+		contrast = colorA.contrastWCAG21( colorB );
+		contrastCache.set( cacheKey, contrast );
+	}
+	return contrast;
+}
+
+/**
+ * Clear all caches - useful for memory management or testing
+ */
+export function clearCaches(): void {
+	contrastCache.clear();
+	colorStringCache.clear();
+}

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

@@ -0,0 +1,85 @@
+/**
+ * External dependencies
+ */
+import Color from 'colorjs.io';
+
+/**
+ * Internal dependencies
+ */
+import type { Ramp } from './types';
+
+export const WHITE = new Color( '#fff' ).to( 'oklch' );
+export const BLACK = new Color( '#000' ).to( 'oklch' );
+
+// Margin added to target contrasts to counter for algorithm approximations
+// and rounding errors.
+export const UNIVERSAL_CONTRAST_TOPUP = 0.05;
+
+// When enabling "lighter direction" bias, this is the amount by which
+// black text contrast needs to be greater than white text contrast.
+// The higher the value, the stronger the preference for white text.
+// The current value has been determined empirically as the highest value
+// that won't cause the algo not to be able to correctly solve all contrasts.
+export const WHITE_TEXT_CONTRAST_MARGIN = 3.1;
+
+// These values are used as thresholds when trying to match the background
+// ramp's lightness while calculating an accent ramp. They prevent the accent
+// scale from being pinned to lightness values in the middle of the range,
+// which would cause the algorithm to struggle to satisfy the accent scale
+// constraints and therefore produce unexpected results.
+export const ACCENT_SCALE_BASE_LIGHTNESS_THRESHOLDS = {
+	lighter: { min: 0.2, max: 0.4 },
+	darker: { min: 0.75, max: 0.98 },
+} as const;
+
+// Minimum lightness difference noticed by the algorithm.
+export const LIGHTNESS_EPSILON = 1e-3;
+
+export const MAX_BISECTION_ITERATIONS = 25;
+
+export const CONTRAST_COMBINATIONS: {
+	bgs: ( keyof Ramp )[];
+	fgs: ( keyof Ramp )[];
+	target: number;
+}[] = [
+	{
+		bgs: [ 'surface1', 'surface2', 'surface3' ],
+		fgs: [ 'fgSurface3', 'fgSurface4' ],
+		target: 4.5,
+	},
+	{
+		bgs: [ 'surface4', 'surface5' ],
+		fgs: [ 'fgSurface4' ],
+		target: 4.5,
+	},
+	{
+		bgs: [ 'bgFill1' ],
+		fgs: [ 'fgFill' ],
+		target: 4.5,
+	},
+	{
+		bgs: [ 'bgFillInverted1' ],
+		fgs: [ 'fgFillInverted' ],
+		target: 4.5,
+	},
+	{
+		bgs: [ 'bgFillInverted1' ],
+		fgs: [ 'fgFillInverted' ],
+		target: 4.5,
+	},
+	{
+		bgs: [ 'surface1', 'surface2', 'surface3' ],
+		fgs: [ 'stroke3' ],
+		target: 3,
+	},
+];
+
+// Used when generating the DTCG tokens and the static color ramps.
+export const DEFAULT_SEED_COLORS = {
+	bg: '#f8f8f8',
+	primary: '#3858e9',
+	info: '#0090ff',
+	success: '#4ab866',
+	warning: '#f0b849',
+	error: '#cc1818',
+};

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

@@ -0,0 +1,190 @@
+/**
+ * External dependencies
+ */
+import Color from 'colorjs.io';
+
+/**
+ * Internal dependencies
+ */
+import { clampToGamut } from './utils';
+import {
+	WHITE,
+	BLACK,
+	LIGHTNESS_EPSILON,
+	MAX_BISECTION_ITERATIONS,
+} from './constants';
+import { getCachedContrast } from './cache-utils';
+import { type TaperChromaOptions, taperChroma } from './taper-chroma';
+
+/**
+ * Solve for L such that:
+ *  - the L applied to the seed meets the contrast target against the reference
+ *  - the search is performed in one direction (ie lighter / darker)
+ *  - more constraints can be applied around lightness
+ *  - chroma could be tapered
+ * @param reference
+ * @param seed
+ * @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,
+	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 } {
+	// 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 };
+	}
+
+	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;
+
+		if ( taperChromaOptions ) {
+			( { l: newL, c: newC } = taperChroma(
+				seed,
+				newL,
+				taperChromaOptions
+			) );
+		}
+
+		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
+			);
+		}
+
+		// 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
+		) {
+			return {
+				color: colorWithExactL,
+				reached: exactLContrast >= target,
+				achieved: 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
+			);
+		}
+		return {
+			color: mostContrastingColor,
+			reached: false,
+			achieved: highestPossibleContrast,
+		};
+	}
+
+	// Bracket: low fails, high meets.
+	// 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;
+		}
+	}
+
+	return {
+		color: resultingColor,
+		reached: true,
+		achieved: bestContrastFound,
+	};
+}

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

@@ -0,0 +1,369 @@
+/**
+ * External dependencies
+ */
+import Color from 'colorjs.io';
+
+/**
+ * Internal dependencies
+ */
+import { getCachedContrast, getColorString } from './cache-utils';
+import { findColorMeetingRequirements } from './find-color-with-constraints';
+import {
+	clampToGamut,
+	sortByDependency,
+	computeBetterFgColorDirection,
+	adjustContrastTarget,
+} from './utils';
+
+import type {
+	FollowDirection,
+	Ramp,
+	RampDirection,
+	RampConfig,
+	RampResult,
+} from './types';
+import { LIGHTNESS_EPSILON, MAX_BISECTION_ITERATIONS } from './constants';
+
+/**
+ * Calculate a complete color ramp based on the provided configuration.
+ *
+ * @param params                       - The calculation parameters
+ * @param params.seed                  - The base color to build the ramp from
+ * @param params.sortedSteps           - Steps sorted in dependency order
+ * @param params.config                - Ramp configuration defining contrast requirements
+ * @param params.mainDir               - Primary direction for the ramp (lighter/darker)
+ * @param params.oppDir                - Opposite direction from mainDir
+ * @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( {
+	seed,
+	sortedSteps,
+	config,
+	mainDir,
+	oppDir,
+	pinLightness,
+	debug = false,
+}: {
+	seed: Color;
+	sortedSteps: ( keyof Ramp )[];
+	config: RampConfig;
+	mainDir: RampDirection;
+	oppDir: RampDirection;
+	pinLightness?: {
+		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;
+
+	// 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 >();
+	calculatedColors.set( 'seed', seed );
+
+	for ( const stepName of sortedSteps ) {
+		const {
+			contrast,
+			lightness: stepLightnessConstraint,
+			taperChromaOptions,
+			sameAsIfPossible,
+		} = config[ stepName ];
+		const referenceColor = calculatedColors.get( contrast.reference );
+
+		if ( ! referenceColor ) {
+			throw new Error(
+				`Reference color for step ${ stepName } not found: ${ contrast.reference }`
+			);
+		}
+
+		// 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
+				);
+				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,
+			followDirection: FollowDirection
+		): RampDirection {
+			if ( followDirection === 'main' ) {
+				return mainDir;
+			}
+
+			if ( followDirection === 'opposite' ) {
+				return oppDir;
+			}
+
+			if ( followDirection === 'best' ) {
+				return computeBetterFgColorDirection(
+					color,
+					contrast.preferLighter
+				).better;
+			}
+
+			return followDirection;
+		}
+
+		const computedDir = computeDirection(
+			referenceColor,
+			contrast.followDirection
+		);
+
+		const adjustedTarget = adjustContrastTarget( contrast.target );
+
+		// Define the lightness constraint, if needed.
+		let lightnessConstraint;
+		if ( pinLightness?.stepName === stepName ) {
+			lightnessConstraint = {
+				value: pinLightness.value,
+				type: 'force',
+			} as const;
+		} else if ( stepLightnessConstraint ) {
+			lightnessConstraint = {
+				value: stepLightnessConstraint( computedDir ),
+				type: 'onlyIfSucceeds',
+			} as const;
+		}
+
+		// Calculate the color meeting the requirements
+		const searchResults = findColorMeetingRequirements(
+			referenceColor,
+			seed,
+			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;
+			}
+		}
+
+		// Store calculated color for future dependencies
+		calculatedColors.set( stepName, searchResults.color );
+
+		// Add to results
+		rampResults[ stepName ] = {
+			color: getColorString( searchResults.color ),
+			warning:
+				! contrast.ignoreWhenAdjustingSeed && ! searchResults.reached,
+		};
+	}
+
+	return {
+		rampResults,
+		SATISFIED_ALL_CONTRAST_REQUIREMENTS,
+		UNSATISFIED_DIRECTION,
+	};
+}
+
+export function buildRamp(
+	seedArg: string,
+	config: RampConfig,
+	{
+		mainDirection,
+		pinLightness,
+		debug = false,
+		rescaleToFitContrastTargets = true,
+	}: {
+		mainDirection?: RampDirection;
+		pinLightness?: {
+			stepName: keyof Ramp;
+			value: number;
+		};
+		rescaleToFitContrastTargets?: boolean;
+		debug?: boolean;
+	} = {}
+): RampResult {
+	let seed: Color;
+	try {
+		seed = clampToGamut( new Color( seedArg ) );
+	} catch ( error ) {
+		throw new Error(
+			`Invalid seed color "${ seedArg }": ${
+				error instanceof Error ? error.message : 'Unknown error'
+			}`
+		);
+	}
+
+	let mainDir: RampDirection = 'lighter';
+	let oppDir: RampDirection = 'darker';
+
+	if ( mainDirection ) {
+		mainDir = mainDirection;
+		oppDir = mainDirection === 'darker' ? 'lighter' : 'darker';
+	} else {
+		const { better, worse } = computeBetterFgColorDirection( seed );
+		mainDir = better;
+		oppDir = worse;
+	}
+
+	// Get the correct calculation order based on dependencies
+	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(),
+			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,
+				} )
+			);
+
+			if ( debug ) {
+				// eslint-disable-next-line no-console
+				console.log( `Iteration ${ i }`, {
+					worseSeedL,
+					newSeedL: ( worseSeedL + betterSeedL ) / 2,
+					betterSeedL,
+				} );
+			}
+
+			const iterationResults = calculateRamp( {
+				seed: newSeed,
+				sortedSteps,
+				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,
+				} );
+			}
+		}
+	}
+
+	// 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;
+	}
+
+	return toReturn;
+}