@wordpress/components 22.0.0 → 23.0.0

package/src/theme/color-algorithms.ts

@@ -0,0 +1,138 @@
+/**
+ * External dependencies
+ */
+import { colord, extend } from 'colord';
+import a11yPlugin from 'colord/plugins/a11y';
+import namesPlugin from 'colord/plugins/names';
+
+/**
+ * WordPress dependencies
+ */
+import warning from '@wordpress/warning';
+
+/**
+ * Internal dependencies
+ */
+import type { ThemeInputValues, ThemeOutputValues } from './types';
+import { COLORS } from '../utils';
+
+extend( [ namesPlugin, a11yPlugin ] );
+
+export function generateThemeVariables(
+	inputs: ThemeInputValues
+): ThemeOutputValues {
+	validateInputs( inputs );
+
+	const generatedColors = {
+		...generateAccentDependentColors( inputs.accent ),
+		...generateBackgroundDependentColors( inputs.background ),
+	};
+
+	warnContrastIssues( checkContrasts( inputs, generatedColors ) );
+
+	return { colors: generatedColors };
+}
+
+function validateInputs( inputs: ThemeInputValues ) {
+	for ( const [ key, value ] of Object.entries( inputs ) ) {
+		if ( typeof value !== 'undefined' && ! colord( value ).isValid() ) {
+			warning(
+				`wp.components.Theme: "${ value }" is not a valid color value for the '${ key }' prop.`
+			);
+		}
+	}
+}
+
+export function checkContrasts(
+	inputs: ThemeInputValues,
+	outputs: ThemeOutputValues[ 'colors' ]
+) {
+	const background = inputs.background || COLORS.white;
+	const accent = inputs.accent || '#007cba';
+	const foreground = outputs.foreground || COLORS.gray[ 900 ];
+	const gray = outputs.gray || COLORS.gray;
+
+	return {
+		accent: colord( background ).isReadable( accent )
+			? undefined
+			: `The background color ("${ background }") does not have sufficient contrast against the accent color ("${ accent }").`,
+		foreground: colord( background ).isReadable( foreground )
+			? undefined
+			: `The background color provided ("${ background }") does not have sufficient contrast against the standard foreground colors.`,
+		grays:
+			colord( background ).contrast( gray[ 600 ] ) >= 3 &&
+			colord( background ).contrast( gray[ 700 ] ) >= 4.5
+				? undefined
+				: `The background color provided ("${ background }") cannot generate a set of grayscale foreground colors with sufficient contrast. Try adjusting the color to be lighter or darker.`,
+	};
+}
+
+function warnContrastIssues( issues: ReturnType< typeof checkContrasts > ) {
+	for ( const error of Object.values( issues ) ) {
+		if ( error ) {
+			warning( 'wp.components.Theme: ' + error );
+		}
+	}
+}
+
+function generateAccentDependentColors( accent?: string ) {
+	if ( ! accent ) return {};
+
+	return {
+		accent,
+		accentDarker10: colord( accent ).darken( 0.1 ).toHex(),
+		accentDarker20: colord( accent ).darken( 0.2 ).toHex(),
+		accentInverted: getForegroundForColor( accent ),
+	};
+}
+
+function generateBackgroundDependentColors( background?: string ) {
+	if ( ! background ) return {};
+
+	const foreground = getForegroundForColor( background );
+
+	return {
+		background,
+		foreground,
+		foregroundInverted: getForegroundForColor( foreground ),
+		gray: generateShades( background, foreground ),
+	};
+}
+
+function getForegroundForColor( color: string ) {
+	return colord( color ).isDark() ? COLORS.white : COLORS.gray[ 900 ];
+}
+
+export function generateShades( background: string, foreground: string ) {
+	// How much darkness you need to add to #fff to get the COLORS.gray[n] color
+	const SHADES = {
+		100: 0.06,
+		200: 0.121,
+		300: 0.132,
+		400: 0.2,
+		600: 0.42,
+		700: 0.543,
+		800: 0.821,
+	};
+
+	// Darkness of COLORS.gray[ 900 ], relative to #fff
+	const limit = 0.884;
+
+	const direction = colord( background ).isDark() ? 'lighten' : 'darken';
+
+	// Lightness delta between the background and foreground colors
+	const range =
+		Math.abs(
+			colord( background ).toHsl().l - colord( foreground ).toHsl().l
+		) / 100;
+
+	const result: Record< number, string > = {};
+
+	Object.entries( SHADES ).forEach( ( [ key, value ] ) => {
+		result[ parseInt( key ) ] = colord( background )
+			[ direction ]( ( value / limit ) * range )
+			.toHex();
+	} );
+
+	return result as NonNullable< ThemeOutputValues[ 'colors' ][ 'gray' ] >;
+}

package/src/theme/index.tsx

@@ -1,18 +1,16 @@
 /**
- * External dependencies
+ * WordPress dependencies
  */
-import { colord, extend } from 'colord';
-import a11yPlugin from 'colord/plugins/a11y';
-import namesPlugin from 'colord/plugins/names';
+import { useMemo } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import type { ThemeProps } from './types';
 import type { WordPressComponentProps } from '../ui/context';
-import { Wrapper } from './styles';
-
-extend( [ namesPlugin, a11yPlugin ] );
+import { colorVariables, Wrapper } from './styles';
+import { generateThemeVariables } from './color-algorithms';
+import { useCx } from '../utils';
 
 /**
  * `Theme` allows defining theme variables for components in the `@wordpress/components` package.
@@ -36,16 +34,25 @@ extend( [ namesPlugin, a11yPlugin ] );
  * };
  * ```
  */
-function Theme( props: WordPressComponentProps< ThemeProps, 'div', true > ) {
-	const { accent } = props;
-	if ( accent && ! colord( accent ).isValid() ) {
-		// eslint-disable-next-line no-console
-		console.warn(
-			`wp.components.Theme: "${ accent }" is not a valid color value for the 'accent' prop.`
-		);
-	}
+function Theme( {
+	accent,
+	background,
+	className,
+	...props
+}: WordPressComponentProps< ThemeProps, 'div', true > ) {
+	const cx = useCx();
+	const classes = useMemo(
+		() =>
+			cx(
+				...colorVariables(
+					generateThemeVariables( { accent, background } )
+				),
+				className
+			),
+		[ accent, background, className, cx ]
+	);
 
-	return <Wrapper { ...props } />;
+	return <Wrapper className={ classes } { ...props } />;
 }
 
 export default Theme;

package/src/theme/stories/index.tsx

@@ -8,12 +8,15 @@ import type { ComponentMeta, ComponentStory } from '@storybook/react';
  */
 import Theme from '../index';
 import Button from '../../button';
+import { generateThemeVariables, checkContrasts } from '../color-algorithms';
+import { HStack } from '../../h-stack';
 
 const meta: ComponentMeta< typeof Theme > = {
 	component: Theme,
 	title: 'Components (Experimental)/Theme',
 	argTypes: {
 		accent: { control: { type: 'color' } },
+		background: { control: { type: 'color' } },
 	},
 	parameters: {
 		controls: { expanded: true },
@@ -45,3 +48,67 @@ export const Nested: ComponentStory< typeof Theme > = ( args ) => (
 Nested.args = {
 	accent: 'blue',
 };
+
+/**
+ * The rest of the required colors are generated based on the given accent and background colors.
+ */
+export const ColorScheme: ComponentStory< typeof Theme > = ( {
+	accent,
+	background,
+} ) => {
+	const { colors } = generateThemeVariables( { accent, background } );
+	const { gray, ...otherColors } = colors;
+	const contrastIssues = Object.entries(
+		checkContrasts( { accent, background }, colors )
+	).filter( ( [ _, error ] ) => !! error );
+
+	const Chip = ( { color, name }: { color: string; name: string } ) => (
+		<HStack justify="flex-start">
+			<div
+				style={ {
+					backgroundColor: color,
+					height: '1.25em',
+					width: 40,
+				} }
+			/>
+			<div style={ { fontSize: 14 } }>{ name }</div>
+		</HStack>
+	);
+
+	return (
+		<>
+			{ Object.entries( otherColors ).map( ( [ key, value ] ) => (
+				<Chip color={ value } name={ key } key={ key } />
+			) ) }
+			{ Object.entries( gray as NonNullable< typeof gray > ).map(
+				( [ key, value ] ) => (
+					<Chip
+						color={ value }
+						name={ `gray ${ key }` }
+						key={ key }
+					/>
+				)
+			) }
+			{ !! contrastIssues.length && (
+				<>
+					<h2>Contrast issues</h2>
+					<ul>
+						{ contrastIssues.map( ( [ key, error ] ) => (
+							<li key={ key }>{ error }</li>
+						) ) }
+					</ul>
+				</>
+			) }
+		</>
+	);
+};
+ColorScheme.args = {
+	accent: '#007cba',
+	background: '#fff',
+};
+ColorScheme.argTypes = {
+	children: { table: { disable: true } },
+};
+ColorScheme.parameters = {
+	docs: { source: { state: 'closed' } },
+};

package/src/theme/styles.ts

@@ -1,28 +1,33 @@
 /**
  * External dependencies
  */
-import { colord } from 'colord';
 import styled from '@emotion/styled';
 import { css } from '@emotion/react';
 
 /**
  * Internal dependencies
  */
-import type { ThemeProps } from './types';
+import type { ThemeOutputValues } from './types';
 
-const accentColor = ( { accent }: ThemeProps ) =>
-	accent
-		? css`
-				--wp-components-color-accent: ${ accent };
-				--wp-components-color-accent-darker-10: ${ colord( accent )
-					.darken( 0.1 )
-					.toHex() };
-				--wp-components-color-accent-darker-20: ${ colord( accent )
-					.darken( 0.2 )
-					.toHex() };
-		  `
-		: undefined;
+export const colorVariables = ( { colors }: ThemeOutputValues ) => {
+	const shades = Object.entries( colors.gray || {} )
+		.map( ( [ k, v ] ) => `--wp-components-color-gray-${ k }: ${ v };` )
+		.join( '' );
 
-export const Wrapper = styled.div< ThemeProps >`
-	${ accentColor }
-`;
+	return [
+		css`
+			--wp-components-color-accent: ${ colors.accent };
+			--wp-components-color-accent-darker-10: ${ colors.accentDarker10 };
+			--wp-components-color-accent-darker-20: ${ colors.accentDarker20 };
+			--wp-components-color-accent-inverted: ${ colors.accentInverted };
+
+			--wp-components-color-background: ${ colors.background };
+			--wp-components-color-foreground: ${ colors.foreground };
+			--wp-components-color-foreground-inverted: ${ colors.foregroundInverted };
+
+			${ shades }
+		`,
+	];
+};
+
+export const Wrapper = styled.div``;

package/src/theme/test/color-algorithms.ts

@@ -0,0 +1,100 @@
+/**
+ * External dependencies
+ */
+import { colord } from 'colord';
+
+/**
+ * Internal dependencies
+ */
+import { COLORS } from '../../utils';
+
+/**
+ * Internal dependencies
+ */
+import { generateShades, generateThemeVariables } from '../color-algorithms';
+
+describe( 'Theme color algorithms', () => {
+	describe( 'generateThemeVariables', () => {
+		it( 'should allow explicitly undefined values', () => {
+			generateThemeVariables( {
+				accent: undefined,
+				background: undefined,
+			} );
+			expect( console ).not.toHaveWarned();
+		} );
+
+		it( 'should warn if invalid colors are passed', () => {
+			generateThemeVariables( { accent: 'var(--invalid)' } );
+			expect( console ).toHaveWarned();
+		} );
+
+		it( 'should warn if standard foreground colors are not readable against background', () => {
+			generateThemeVariables( { background: '#777' } );
+			expect( console ).toHaveWarnedWith(
+				'wp.components.Theme: The background color provided ("#777") does not have sufficient contrast against the standard foreground colors.'
+			);
+		} );
+
+		it( 'should warn if accent color is not readable against background', () => {
+			generateThemeVariables( { background: '#fefefe' } );
+			expect( console ).not.toHaveWarned();
+
+			generateThemeVariables( {
+				accent: '#000',
+				background: '#fff',
+			} );
+			expect( console ).not.toHaveWarned();
+
+			generateThemeVariables( {
+				accent: '#111',
+				background: '#000',
+			} );
+			expect( console ).toHaveWarnedWith(
+				'wp.components.Theme: The background color ("#000") does not have sufficient contrast against the accent color ("#111").'
+			);
+
+			generateThemeVariables( { background: '#eee' } );
+			expect( console ).toHaveWarnedWith(
+				'wp.components.Theme: The background color ("#eee") does not have sufficient contrast against the accent color ("#007cba").'
+			);
+		} );
+
+		it( 'should warn if a readable grayscale cannot be generated', () => {
+			generateThemeVariables( { background: '#ddd' } );
+			expect( console ).toHaveWarnedWith(
+				'wp.components.Theme: The background color provided ("#ddd") cannot generate a set of grayscale foreground colors with sufficient contrast. Try adjusting the color to be lighter or darker.'
+			);
+		} );
+	} );
+
+	describe( 'generateShades', () => {
+		it( 'should generate the default WP shades when the default WP background/foreground colors are given', () => {
+			const shades = generateShades( '#fff', '#1e1e1e' );
+
+			Object.entries( shades ).forEach( ( [ k, color ] ) => {
+				const key = parseInt( k, 10 ) as keyof typeof shades;
+				const normalizedExpectedColor = colord(
+					COLORS.gray[ key ]
+				).toHex();
+
+				expect( color ).toBe( normalizedExpectedColor );
+			} );
+		} );
+
+		it.each( [
+			[ '#000', '#fff' ], // wide delta
+			[ '#fff', '#000' ], // flipped
+			[ '#eee', '#fff' ], // narrow delta
+		] )( 'should generate unique shades (bg: %s, fg: %s)', ( bg, fg ) => {
+			const shades = generateShades( bg, fg );
+
+			// The darkest and lightest shades should be different from the fg/bg colors
+			expect( colord( shades[ 100 ] ).isEqual( bg ) ).toBe( false );
+			expect( colord( shades[ 800 ] ).isEqual( fg ) ).toBe( false );
+
+			// The shades should be unique
+			const shadeValues = Object.values( shades );
+			expect( shadeValues ).toHaveLength( new Set( shadeValues ).size );
+		} );
+	} );
+} );

package/src/theme/test/index.tsx

@@ -28,59 +28,93 @@ describe( 'Theme', () => {
 	describe( 'accent color', () => {
 		it( 'it does not define the accent color (and its variations) as a CSS variable when the `accent` prop is undefined', () => {
 			render(
-				<Theme>
+				<Theme data-testid="theme">
 					<MyThemableComponent>Inner</MyThemableComponent>
 				</Theme>
 			);
 
-			const inner = screen.getByText( 'Inner' );
-
-			if ( inner?.parentElement === null ) {
-				throw new Error(
-					'Somehow the `Theme` component does not render a DOM element?'
-				);
-			}
-
 			const innerElementStyles = window.getComputedStyle(
-				inner?.parentElement
+				screen.getByTestId( 'theme' )
 			);
 
-			expect(
-				innerElementStyles.getPropertyValue(
-					'--wp-components-color-accent'
-				)
-			).toBe( '' );
-
-			expect(
-				innerElementStyles.getPropertyValue(
-					'--wp-components-color-accent-darker-10'
-				)
-			).toBe( '' );
-
-			expect(
-				innerElementStyles.getPropertyValue(
-					'--wp-components-color-accent-darker-20'
-				)
-			).toBe( '' );
+			[
+				'--wp-components-color-accent',
+				'--wp-components-color-accent-darker-10',
+				'--wp-components-color-accent-darker-20',
+				'--wp-components-color-accent-inverted',
+			].forEach( ( cssVariable ) => {
+				expect(
+					innerElementStyles.getPropertyValue( cssVariable )
+				).toBe( '' );
+			} );
 		} );
 
 		it( 'it defines the accent color (and its variations) as a CSS variable', () => {
 			render(
-				<Theme accent="#123abc">
+				<Theme accent="#123abc" data-testid="theme">
 					<MyThemableComponent>Inner</MyThemableComponent>
 				</Theme>
 			);
 
-			const inner = screen.getByText( 'Inner' );
-
-			expect( inner?.parentElement ).toHaveStyle( {
+			expect( screen.getByTestId( 'theme' ) ).toHaveStyle( {
 				'--wp-components-color-accent': '#123abc',
 				'--wp-components-color-accent-darker-10': '#0e2c8d',
 				'--wp-components-color-accent-darker-20': '#091d5f',
+				'--wp-components-color-accent-inverted': '#fff',
+			} );
+		} );
+	} );
+
+	describe( 'background color', () => {
+		it( 'it does not define the background color (and its dependent colors) as a CSS variable when the `background` prop is undefined', () => {
+			render(
+				<Theme data-testid="theme">
+					<MyThemableComponent>Inner</MyThemableComponent>
+				</Theme>
+			);
+
+			const innerElementStyles = window.getComputedStyle(
+				screen.getByTestId( 'theme' )
+			);
+
+			[
+				'--wp-components-color-background',
+				'--wp-components-color-foreground',
+				'--wp-components-color-foreground-inverted',
+				...[ '100', '200', '300', '400', '600', '700', '800' ].map(
+					( shade ) => `--wp-components-color-gray-${ shade }`
+				),
+			].forEach( ( cssVariable ) => {
+				expect(
+					innerElementStyles.getPropertyValue( cssVariable )
+				).toBe( '' );
+			} );
+		} );
+
+		it( 'it defines the background color (and its dependent colors) as a CSS variable', () => {
+			render(
+				<Theme background="#ffffff" data-testid="theme">
+					<MyThemableComponent>Inner</MyThemableComponent>
+				</Theme>
+			);
+
+			expect( screen.getByTestId( 'theme' ) ).toHaveStyle( {
+				'--wp-components-color-background': '#ffffff',
+				'--wp-components-color-foreground': '#1e1e1e',
+				'--wp-components-color-foreground-inverted': '#fff',
+				'--wp-components-color-gray-100': '#f0f0f0',
+				'--wp-components-color-gray-200': '#e0e0e0',
+				'--wp-components-color-gray-300': '#dddddd',
+				'--wp-components-color-gray-400': '#cccccc',
+				'--wp-components-color-gray-600': '#949494',
+				'--wp-components-color-gray-700': '#757575',
+				'--wp-components-color-gray-800': '#2f2f2f',
 			} );
 		} );
+	} );
 
-		describe( 'unsupported values', () => {
+	describe( 'unsupported values', () => {
+		describe.each( [ 'accent', 'background' ] )( '%s', ( propName ) => {
 			it.each( [
 				// Keywords
 				'currentcolor',
@@ -91,9 +125,8 @@ describe( 'Theme', () => {
 				'unset',
 				// CSS Custom properties
 				'var( --my-variable )',
-			] )( 'should warn when the value is "%s"', ( accentValue ) => {
-				render( <Theme accent={ accentValue } /> );
-
+			] )( 'should warn when the value is "%s"', ( value ) => {
+				render( <Theme { ...{ [ propName ]: value } } /> );
 				expect( console ).toHaveWarned();
 			} );
 		} );

package/src/theme/types.ts

@@ -3,17 +3,57 @@
  */
 import type { ReactNode } from 'react';
 
-export type ThemeProps = {
+export type ThemeInputValues = {
 	/**
-	 * Used to set the accent color (used by components as the primary color).
+	 * The accent color (used by components as the primary color).
 	 *
 	 * If an accent color is not defined, the default fallback value is the original
-	 * WP Admin main theme color. No all valid CSS color syntaxes are supported —
+	 * WP Admin main theme color. Not all valid CSS color syntaxes are supported —
 	 * in particular, keywords (like `'currentcolor'`, `'inherit'`, `'initial'`,
 	 * `'revert'`, `'unset'`...) and CSS custom properties (e.g.
 	 * `var(--my-custom-property)`) are _not_ supported values for this property.
 	 */
 	accent?: string;
+	/**
+	 * The background color.
+	 *
+	 * If a component explicitly has a background, it will be this color.
+	 * Otherwise, this color will simply be used to determine what the foreground colors should be.
+	 * The actual background color will need to be set on the component's container element.
+	 *
+	 * If a background color is not defined, the default fallback value is #fff.
+	 * Not all valid CSS color syntaxes are supported —
+	 * in particular, keywords (like `'currentcolor'`, `'inherit'`, `'initial'`,
+	 * `'revert'`, `'unset'`...) and CSS custom properties (e.g.
+	 * `var(--my-custom-property)`) are _not_ supported values for this property.
+	 */
+	background?: string;
+};
+
+export type ThemeOutputValues = {
+	colors: Partial< {
+		accent: string;
+		accentDarker10: string;
+		accentDarker20: string;
+		/** Foreground color to use when accent color is the background. */
+		accentInverted: string;
+		background: string;
+		foreground: string;
+		/** Foreground color to use when foreground color is the background. */
+		foregroundInverted: string;
+		gray: {
+			100: string;
+			200: string;
+			300: string;
+			400: string;
+			600: string;
+			700: string;
+			800: string;
+		};
+	} >;
+};
+
+export type ThemeProps = ThemeInputValues & {
 	/**
 	 * The children elements.
 	 */

package/src/toggle-control/index.tsx

@@ -12,6 +12,7 @@ import { useInstanceId } from '@wordpress/compose';
 /**
  * Internal dependencies
  */
+import { FlexBlock } from '../flex';
 import FormToggle from '../form-toggle';
 import BaseControl from '../base-control';
 import type { WordPressComponentProps } from '../ui/context/wordpress-component';
@@ -94,12 +95,13 @@ export function ToggleControl( {
 					aria-describedby={ describedBy }
 					disabled={ disabled }
 				/>
-				<label
+				<FlexBlock
+					as="label"
 					htmlFor={ id }
 					className="components-toggle-control__label"
 				>
 					{ label }
-				</label>
+				</FlexBlock>
 			</HStack>
 		</BaseControl>
 	);

package/src/toggle-group-control/stories/index.tsx

@@ -81,6 +81,7 @@ Default.args = {
 		{ value: 'right', label: 'Right' },
 		{ value: 'justify', label: 'Justify' },
 	].map( mapPropsToOptionComponent ),
+	isBlock: true,
 	label: 'Label',
 };
 
@@ -121,6 +122,7 @@ WithIcons.args = {
 		{ value: 'uppercase', label: 'Uppercase', icon: formatUppercase },
 		{ value: 'lowercase', label: 'Lowercase', icon: formatLowercase },
 	].map( mapPropsToOptionIconComponent ),
+	isBlock: false,
 };
 
 /**