@wordpress/theme 0.1.0 → 0.2.0

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,35 +1,36 @@
 /**
  * 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,
 	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 { getCachedContrast } from './cache-utils';
+import type { Ramp, RampConfig, RampDirection } from './types';
+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
  * @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 )[] >;
 } {
@@ -67,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' >();
@@ -109,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
@@ -119,14 +149,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 +
@@ -159,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;
+}

package/src/color-ramps/stories/index.story.tsx

@@ -44,9 +44,7 @@ export const Default: StoryObj< typeof ColorGen > = {
 	render: ( args ) => {
 		const bgSeed = args.background ?? DEFAULT_SEED_COLORS.bg;
 		const primarySeed = args.primary ?? DEFAULT_SEED_COLORS.primary;
-		const bgRamp = buildBgRamp( {
-			seed: bgSeed,
-		} );
+		const bgRamp = buildBgRamp( bgSeed );
 
 		const bgRampObj = {
 			seed: {
@@ -61,47 +59,42 @@ export const Default: StoryObj< typeof ColorGen > = {
 				name: 'bgFill1' as const,
 				value: primarySeed,
 			},
-			ramp: buildAccentRamp( { seed: primarySeed, bgRamp } ).ramp,
+			ramp: buildAccentRamp( primarySeed, bgRamp ).ramp,
 		};
 		const infoRampObj = {
 			seed: {
 				name: 'bgFill1' as const,
 				value: DEFAULT_SEED_COLORS.info,
 			},
-			ramp: buildAccentRamp( {
-				seed: DEFAULT_SEED_COLORS.info,
-				bgRamp,
-			} ).ramp,
+			ramp: buildAccentRamp( DEFAULT_SEED_COLORS.info, bgRamp ).ramp,
 		};
 		const successRampObj = {
 			seed: {
 				name: 'bgFill1' as const,
 				value: DEFAULT_SEED_COLORS.success,
 			},
-			ramp: buildAccentRamp( {
-				seed: DEFAULT_SEED_COLORS.success,
-				bgRamp,
-			} ).ramp,
+			ramp: buildAccentRamp( DEFAULT_SEED_COLORS.success, bgRamp ).ramp,
 		};
 		const warningRampObj = {
 			seed: {
 				name: 'bgFill1' as const,
 				value: DEFAULT_SEED_COLORS.warning,
 			},
-			ramp: buildAccentRamp( {
-				seed: DEFAULT_SEED_COLORS.warning,
-				bgRamp,
-			} ).ramp,
+			ramp: buildAccentRamp( DEFAULT_SEED_COLORS.warning, bgRamp ).ramp,
+		};
+		const cautionRampObj = {
+			seed: {
+				name: 'bgFill1' as const,
+				value: DEFAULT_SEED_COLORS.caution,
+			},
+			ramp: buildAccentRamp( DEFAULT_SEED_COLORS.caution, bgRamp ).ramp,
 		};
 		const errorRampObj = {
 			seed: {
 				name: 'bgFill1' as const,
 				value: DEFAULT_SEED_COLORS.error,
 			},
-			ramp: buildAccentRamp( {
-				seed: DEFAULT_SEED_COLORS.error,
-				bgRamp,
-			} ).ramp,
+			ramp: buildAccentRamp( DEFAULT_SEED_COLORS.error, bgRamp ).ramp,
 		};
 
 		const unmetTargets = checkAccessibleCombinations( {
@@ -123,6 +116,7 @@ export const Default: StoryObj< typeof ColorGen > = {
 						infoRampObj,
 						successRampObj,
 						warningRampObj,
+						cautionRampObj,
 						errorRampObj,
 					] }
 				/>
@@ -222,7 +216,7 @@ export const SampleCombinations: StoryObj< typeof ColorGen > = {
 		];
 
 		const ramps = combinations.map( ( { background, primary } ) => {
-			const bgRamp = buildBgRamp( { seed: background } );
+			const bgRamp = buildBgRamp( background );
 
 			const bgRampObj = {
 				seed: {
@@ -237,7 +231,7 @@ export const SampleCombinations: StoryObj< typeof ColorGen > = {
 					name: 'bgFill1' as const,
 					value: primary,
 				},
-				ramp: buildAccentRamp( { seed: primary, bgRamp } ).ramp,
+				ramp: buildAccentRamp( primary, bgRamp ).ramp,
 			};
 
 			return [ bgRampObj, primaryRampObj ];