@wordpress/theme 0.1.0

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

@@ -0,0 +1,161 @@
+/**
+ * External dependencies
+ */
+import type Color from 'colorjs.io';
+
+/**
+ * Internal dependencies
+ */
+import {
+	WHITE,
+	BLACK,
+	UNIVERSAL_CONTRAST_TOPUP,
+	WHITE_TEXT_CONTRAST_MARGIN,
+	ACCENT_SCALE_BASE_LIGHTNESS_THRESHOLDS,
+} from './constants';
+import type { Ramp, RampStepConfig, RampDirection } from './types';
+import { getCachedContrast } from './cache-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' );
+
+/**
+ * Build a dependency graph from the steps configuration
+ * @param config - The steps configuration object
+ */
+function buildDependencyGraph( config: Record< keyof Ramp, RampStepConfig > ): {
+	dependencies: Map< keyof Ramp, ( keyof Ramp | 'seed' )[] >;
+	dependents: Map< keyof Ramp | 'seed', ( keyof Ramp )[] >;
+} {
+	const dependencies = new Map< keyof Ramp, ( keyof Ramp | 'seed' )[] >();
+	const dependents = new Map< keyof Ramp | 'seed', ( keyof Ramp )[] >();
+
+	// Initialize maps
+	Object.keys( config ).forEach( ( step ) => {
+		dependencies.set( step as keyof Ramp, [] );
+	} );
+	dependents.set( 'seed', [] );
+	Object.keys( config ).forEach( ( step ) => {
+		dependents.set( step as keyof Ramp, [] );
+	} );
+
+	// Build the graph
+	Object.entries( config ).forEach( ( [ stepName, stepConfig ] ) => {
+		const step = stepName as keyof Ramp;
+		const reference = stepConfig.contrast.reference;
+
+		dependencies.get( step )!.push( reference );
+		dependents.get( reference )!.push( step );
+
+		// Add dependency for sameAsIfPossible
+		if ( stepConfig.sameAsIfPossible ) {
+			dependencies.get( step )!.push( stepConfig.sameAsIfPossible );
+			dependents.get( stepConfig.sameAsIfPossible )!.push( step );
+		}
+	} );
+
+	return { dependencies, dependents };
+}
+
+/**
+ * Topologically sort steps based on their dependencies
+ * @param config - The steps configuration object
+ */
+export function sortByDependency(
+	config: Record< keyof Ramp, RampStepConfig >
+): ( keyof Ramp )[] {
+	const { dependents } = buildDependencyGraph( config );
+	const result: ( keyof Ramp )[] = [];
+	const visited = new Set< keyof Ramp | 'seed' >();
+	const visiting = new Set< keyof Ramp | 'seed' >();
+
+	function visit( node: keyof Ramp | 'seed' ): void {
+		if ( visiting.has( node ) ) {
+			throw new Error(
+				`Circular dependency detected involving step: ${ String(
+					node
+				) }`
+			);
+		}
+		if ( visited.has( node ) ) {
+			return;
+		}
+
+		visiting.add( node );
+
+		// Visit all dependents (steps that depend on this node)
+		const nodeDependents = dependents.get( node ) || [];
+		nodeDependents.forEach( ( dependent ) => {
+			visit( dependent );
+		} );
+
+		visiting.delete( node );
+		visited.add( node );
+
+		// Add to result only if it's a step (not 'seed')
+		if ( node !== 'seed' ) {
+			result.unshift( node ); // Add to front for correct topological order
+		}
+	}
+
+	// Start with seed - this will recursively visit all reachable nodes
+	visit( 'seed' );
+
+	return result;
+}
+
+/**
+ * Finds out whether a lighter or a darker foreground color achieves a better
+ * contrast against the seed
+ * @param seed
+ * @param preferLighter Whether the check should favor white foreground color
+ * @return An object with "better" and "worse" properties, each holding a
+ * ramp direction value.
+ */
+export function computeBetterFgColorDirection(
+	seed: Color,
+	preferLighter?: boolean
+): {
+	better: RampDirection;
+	worse: RampDirection;
+} {
+	const contrastAgainstBlack = getCachedContrast( seed, BLACK );
+	const contrastAgainstWhite = getCachedContrast( seed, WHITE );
+
+	return contrastAgainstBlack >
+		contrastAgainstWhite +
+			( preferLighter ? WHITE_TEXT_CONTRAST_MARGIN : 0 )
+		? { better: 'darker', worse: 'lighter' }
+		: { better: 'lighter', worse: 'darker' };
+}
+
+export function adjustContrastTarget( target: number ) {
+	if ( target === 1 ) {
+		return 1;
+	}
+
+	// Add a little top up to take into account any rounding error and algo imprecisions.
+	return target + UNIVERSAL_CONTRAST_TOPUP;
+}
+
+/**
+ * Prevent the accent scale from referencing a lightness value that
+ * would prevent the algorithm from complying with the requirements
+ * and cause it to generate unexpected results.
+ * @param rawLightness
+ * @param direction
+ * @return The clamped lightness value
+ */
+export function clampAccentScaleReferenceLightness(
+	rawLightness: number,
+	direction: RampDirection
+) {
+	const thresholds = ACCENT_SCALE_BASE_LIGHTNESS_THRESHOLDS[ direction ];
+	return Math.max( thresholds.min, Math.min( thresholds.max, rawLightness ) );
+}

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

@@ -0,0 +1,264 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryObj } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { RampTable } from './ramp-table';
+import { buildBgRamp, buildAccentRamp, checkAccessibleCombinations } from '..';
+import { DEFAULT_SEED_COLORS } from '../lib/constants';
+
+const ColorGen = ( props: {
+	background: string;
+	primary: string;
+	children: React.ReactNode;
+} ) => {
+	return <div>{ props.children }</div>;
+};
+
+const meta: Meta< typeof ColorGen > = {
+	title: 'Design System/Theme Provider/Color Scales',
+	component: ColorGen,
+	argTypes: {
+		background: {
+			control: { type: 'color', presetColors: [ '#1e1e1e', '#f8f8f8' ] },
+		},
+		primary: {
+			control: {
+				type: 'color',
+				presetColors: [ '#3858e9', '#069e08', '#873eff' ],
+			},
+		},
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { canvas: { sourceState: 'shown' } },
+	},
+	tags: [ 'status-experimental' ],
+};
+export default meta;
+
+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 bgRampObj = {
+			seed: {
+				name: 'surface2' as const,
+				value: bgSeed,
+			},
+			ramp: bgRamp.ramp,
+		};
+
+		const primaryRampObj = {
+			seed: {
+				name: 'bgFill1' as const,
+				value: primarySeed,
+			},
+			ramp: buildAccentRamp( { seed: primarySeed, bgRamp } ).ramp,
+		};
+		const infoRampObj = {
+			seed: {
+				name: 'bgFill1' as const,
+				value: DEFAULT_SEED_COLORS.info,
+			},
+			ramp: buildAccentRamp( {
+				seed: 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,
+		};
+		const warningRampObj = {
+			seed: {
+				name: 'bgFill1' as const,
+				value: DEFAULT_SEED_COLORS.warning,
+			},
+			ramp: buildAccentRamp( {
+				seed: DEFAULT_SEED_COLORS.warning,
+				bgRamp,
+			} ).ramp,
+		};
+		const errorRampObj = {
+			seed: {
+				name: 'bgFill1' as const,
+				value: DEFAULT_SEED_COLORS.error,
+			},
+			ramp: buildAccentRamp( {
+				seed: DEFAULT_SEED_COLORS.error,
+				bgRamp,
+			} ).ramp,
+		};
+
+		const unmetTargets = checkAccessibleCombinations( {
+			bgRamp,
+		} );
+
+		return (
+			<div
+				style={ {
+					display: 'flex',
+					flexDirection: 'column',
+					gap: '32px',
+				} }
+			>
+				<RampTable
+					ramps={ [
+						bgRampObj,
+						primaryRampObj,
+						infoRampObj,
+						successRampObj,
+						warningRampObj,
+						errorRampObj,
+					] }
+				/>
+
+				{ unmetTargets.length === 0 ? (
+					<p>All accessibility targets met</p>
+				) : (
+					<ul>
+						{ unmetTargets.map(
+							(
+								{
+									bgName,
+									bgColor,
+									fgName,
+									fgColor,
+									unmetContrast,
+								},
+								i
+							) => (
+								<li key={ i }>
+									<span
+										style={ {
+											width: 20,
+											height: 20,
+											backgroundColor: fgColor,
+											display: 'inline-block',
+										} }
+									></span>
+									{ fgName } over
+									<span
+										style={ {
+											width: 20,
+											height: 20,
+											backgroundColor: bgColor,
+											display: 'inline-block',
+										} }
+									></span>
+									{ bgName } did not meet { unmetContrast }
+								</li>
+							)
+						) }
+					</ul>
+				) }
+			</div>
+		);
+	},
+	args: {},
+};
+
+export const SampleCombinations: StoryObj< typeof ColorGen > = {
+	render: () => {
+		const combinations = [
+			// WordPress (light / dark)
+			{
+				background: '#f8f8f8',
+				primary: '#3858e9',
+			},
+			{
+				background: '#1e1e1e',
+				primary: '#3858e9',
+			},
+			// WP Classic
+			{
+				background: '#1d2327',
+				primary: '#2271b1',
+			},
+			// WP Light
+			{
+				background: '#e5e5e5',
+				primary: '#d64e07',
+			},
+			// WP Blue
+			{
+				background: '#096484',
+				primary: '#52accc',
+			},
+			// WP Coffee
+			{
+				background: '#46403c',
+				primary: '#c7a589',
+			},
+			// WP Ectoplasm
+			{
+				background: '#413256',
+				primary: '#a3b745',
+			},
+			// WP Ocean
+			{
+				background: '#627c83',
+				primary: '#9ebaa0',
+			},
+			// Sunrise
+			{
+				background: '#b43c38',
+				primary: '#dd823b',
+			},
+		];
+
+		const ramps = combinations.map( ( { background, primary } ) => {
+			const bgRamp = buildBgRamp( { seed: background } );
+
+			const bgRampObj = {
+				seed: {
+					name: 'surface2' as const,
+					value: background,
+				},
+				ramp: bgRamp.ramp,
+			};
+
+			const primaryRampObj = {
+				seed: {
+					name: 'bgFill1' as const,
+					value: primary,
+				},
+				ramp: buildAccentRamp( { seed: primary, bgRamp } ).ramp,
+			};
+
+			return [ bgRampObj, primaryRampObj ];
+		} );
+
+		return (
+			<div
+				style={ { display: 'flex', flexDirection: 'column', gap: 16 } }
+			>
+				{ ramps.map( ( r, i ) => (
+					<RampTable key={ i } ramps={ r } />
+				) ) }
+			</div>
+		);
+	},
+	argTypes: {
+		background: {
+			control: false,
+		},
+		primary: {
+			control: false,
+		},
+	},
+};

package/src/color-ramps/stories/ramp-table.tsx

@@ -0,0 +1,212 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { Ramp } from '../lib/types';
+
+// TODO: show token groups better
+const RAMP_TOKENS_ORDER: { tokenName: keyof Ramp; abbr: string }[] = [
+	{ tokenName: 'surface1', abbr: 'SF1' },
+	{ tokenName: 'surface2', abbr: 'SF2' },
+	{ tokenName: 'surface3', abbr: 'SF3' },
+	{ tokenName: 'surface4', abbr: 'SF4' },
+	{ tokenName: 'surface5', abbr: 'SF5' },
+	{ tokenName: 'surface6', abbr: 'SF6' },
+	{ tokenName: 'bgFill1', abbr: 'BGF1' },
+	{ tokenName: 'bgFill2', abbr: 'BGF2' },
+	{ tokenName: 'bgFillInverted1', abbr: 'BGFI1' },
+	{ tokenName: 'bgFillInverted2', abbr: 'BGFI2' },
+	{ tokenName: 'bgFillDark', abbr: 'BGFD' },
+	{ tokenName: 'stroke1', abbr: 'ST1' },
+	{ tokenName: 'stroke2', abbr: 'ST2' },
+	{ tokenName: 'stroke3', abbr: 'ST3' },
+	{ tokenName: 'stroke4', abbr: 'ST4' },
+	{ tokenName: 'fgSurface1', abbr: 'FGS1' },
+	{ tokenName: 'fgSurface2', abbr: 'FGS2' },
+	{ tokenName: 'fgSurface3', abbr: 'FGS3' },
+	{ tokenName: 'fgSurface4', abbr: 'FGS4' },
+	{ tokenName: 'fgFill', abbr: 'FGF' },
+	{ tokenName: 'fgFillInverted', abbr: 'FGFI' },
+	{ tokenName: 'fgFillDark', abbr: 'FGFD' },
+];
+
+type RampTableProps = {
+	ramps: {
+		seed: {
+			name: keyof Ramp;
+			value: string;
+		};
+		ramp: Record<
+			keyof Ramp,
+			{
+				color: string;
+				warning: boolean;
+			}
+		>;
+	}[];
+};
+export const RampTable = forwardRef< HTMLDivElement, RampTableProps >(
+	function RampTable( { ramps }, forwardedRef ) {
+		return (
+			<div
+				style={ { width: '100%', overflowX: 'scroll' } }
+				ref={ forwardedRef }
+			>
+				<div
+					style={ {
+						display: 'grid',
+						gridTemplateColumns: `repeat(${ RAMP_TOKENS_ORDER.length }, minmax(max-content, 1fr))`,
+						fontFamily: '-apple-system, "system-ui", sans-serif',
+						alignItems: 'end',
+					} }
+				>
+					{ RAMP_TOKENS_ORDER.map( ( { tokenName, abbr } ) => (
+						<div
+							key={ tokenName }
+							style={ {
+								textAlign: 'center',
+								padding: '8px 4px',
+								fontSize: 11,
+								fontWeight: 500,
+								color: ramps[ 0 ].ramp.fgSurface4.color,
+							} }
+						>
+							{ abbr }
+						</div>
+					) ) }
+					{ ramps.map( ( { seed, ramp }, i ) =>
+						RAMP_TOKENS_ORDER.map( ( { tokenName } ) => (
+							<div
+								key={ `${ seed }-${ i }-${ tokenName }` }
+								style={ {
+									marginBlockStart: i !== 0 ? 4 : 0,
+									backgroundColor: ramp[ tokenName ].color,
+									display: 'grid',
+									gridTemplateRows: '20px 1fr',
+									placeItems: 'center',
+									height: tokenName === seed.name ? 60 : 40,
+									minWidth: 32,
+									fontSize: 14,
+									outline: ramp[ tokenName ].warning
+										? '2px solid red'
+										: '',
+									outlineOffset: '-2px',
+								} }
+							>
+								{ tokenName === seed.name ? (
+									<div
+										style={ {
+											backgroundColor: seed.value,
+											height: 20,
+											gridRowStart: 1,
+											gridRowEnd: 2,
+											display: 'grid',
+											placeItems: 'center',
+											width: '100%',
+											fontSize: 8,
+											fontWeight: 500,
+											color:
+												tokenName === 'surface2'
+													? ramp.fgSurface4.color
+													: ramp.fgFill.color,
+										} }
+									>
+										SEED
+									</div>
+								) : null }
+								{ [
+									'surface3',
+									'bgFill1',
+									'bgFillInverted1',
+									'bgFillDark',
+								].includes( tokenName ) ? (
+									<span
+										style={ {
+											padding: '2px 6px',
+											display: 'flex',
+											alignItems: 'center',
+											gap: 2,
+											gridRowStart:
+												tokenName === seed.name ? 2 : 1,
+											gridRowEnd: 3,
+										} }
+									>
+										{ tokenName === 'surface3' ? (
+											<>
+												<span
+													style={ {
+														color: ramp.fgSurface1
+															.color,
+													} }
+												>
+													Aa
+												</span>
+												<span
+													style={ {
+														color: ramp.fgSurface2
+															.color,
+													} }
+												>
+													Aa
+												</span>
+												<span
+													style={ {
+														color: ramp.fgSurface3
+															.color,
+													} }
+												>
+													Aa
+												</span>
+												<span
+													style={ {
+														color: ramp.fgSurface4
+															.color,
+													} }
+												>
+													Aa
+												</span>
+											</>
+										) : null }
+										{ tokenName === 'bgFill1' ? (
+											<span
+												style={ {
+													color: ramp.fgFill.color,
+												} }
+											>
+												Aa
+											</span>
+										) : null }
+										{ tokenName === 'bgFillInverted1' ? (
+											<span
+												style={ {
+													color: ramp.fgFillInverted
+														.color,
+												} }
+											>
+												Aa
+											</span>
+										) : null }
+										{ tokenName === 'bgFillDark' ? (
+											<span
+												style={ {
+													color: ramp.fgFillDark
+														.color,
+												} }
+											>
+												Aa
+											</span>
+										) : null }
+									</span>
+								) : null }
+							</div>
+						) )
+					) }
+				</div>
+			</div>
+		);
+	}
+);