@wordpress/components 37.0.0 → 38.0.0

package/src/theme/README.md

@@ -1,47 +0,0 @@
-# Theme
-
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
-`Theme` allows defining theme variables for components in the `@wordpress/components` package.
-
-Multiple `Theme` components can be nested in order to override specific theme variables.
-
-## Props
-
-### `accent`: `string`
-
-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.
-
-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.
-
--   Required: No
-
-### `background`: `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.
-
--   Required: No
-
-## Writing themeable components
-
-If you would like your custom component to be themeable as a child of the `Theme` component, it should use these color variables. (This is a work in progress, and this list of variables may change. We do not recommend using these variables in production at this time.)
-
--  `--wp-components-color-accent`: The accent color.
--  `--wp-components-color-accent-darker-10`: A slightly darker version of the accent color.
--  `--wp-components-color-accent-darker-20`: An even darker version of the accent color.
--  `--wp-components-color-accent-inverted`: The foreground color when the accent color is the background, for example when placing text on the accent color.
--  `--wp-components-color-background`: The background color.
--  `--wp-components-color-foreground`: The foreground color, for example text.
--  `--wp-components-color-foreground-inverted`: The foreground color when the foreground color is the background, for example when placing text on the foreground color.
--  Grayscale:
-   -  `--wp-components-color-gray-100`: Used for light gray backgrounds.
-   -  `--wp-components-color-gray-200`: Used sparingly for light borders.
-   -	`--wp-components-color-gray-300`: Used for most borders.
-   -	`--wp-components-color-gray-400`
-   -	`--wp-components-color-gray-600`: Meets 3:1 UI or large text contrast against white.
-   -	`--wp-components-color-gray-700`: Meets 4.6:1 text contrast against white.
-   -	`--wp-components-color-gray-800`

package/src/theme/color-algorithms.ts

@@ -1,142 +0,0 @@
-/**
- * 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 || '#3858e9';
-	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,80 +0,0 @@
-import clsx from 'clsx';
-import type { CSSProperties } from 'react';
-
-import { useMemo } from '@wordpress/element';
-
-import type { ThemeOutputValues, ThemeProps } from './types';
-import type { WordPressComponentProps } from '../context';
-import { generateThemeVariables } from './color-algorithms';
-import styles from './style.module.scss';
-import { PolymorphicElement } from '../utils/polymorphic-element';
-
-const getColorVariables = ( {
-	colors,
-}: ThemeOutputValues ): CSSProperties => ( {
-	'--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,
-	...Object.fromEntries(
-		Object.entries( colors.gray ?? {} ).map( ( [ key, value ] ) => [
-			`--wp-components-color-gray-${ key }`,
-			value,
-		] )
-	),
-} );
-
-/**
- * `Theme` allows defining theme variables for components in the `@wordpress/components` package.
- *
- * Multiple `Theme` components can be nested in order to override specific theme variables.
- *
- *
- * ```jsx
- * const Example = () => {
- *   return (
- *     <Theme accent="red">
- *       <Button variant="primary">I'm red</Button>
- *       <Theme accent="blue">
- *         <Button variant="primary">I'm blue</Button>
- *       </Theme>
- *     </Theme>
- *   );
- * };
- * ```
- */
-function Theme( {
-	accent,
-	background,
-	className,
-	style,
-	...props
-}: WordPressComponentProps< ThemeProps, 'div', true > ) {
-	const themeVariables = useMemo(
-		() =>
-			getColorVariables(
-				generateThemeVariables( { accent, background } )
-			),
-		[ accent, background ]
-	);
-	const wrapperStyle = useMemo(
-		() => ( {
-			...themeVariables,
-			...style,
-		} ),
-		[ style, themeVariables ]
-	);
-
-	return (
-		<PolymorphicElement
-			className={ clsx( styles.wrapper, className ) }
-			style={ wrapperStyle }
-			{ ...props }
-		/>
-	);
-}
-
-export default Theme;

package/src/theme/stories/index.story.tsx

@@ -1,127 +0,0 @@
-/**
- * External dependencies
- */
-import type { Meta, StoryFn } from '@storybook/react-vite';
-
-/**
- * Internal dependencies
- */
-import Theme from '../index';
-import Button from '../../button';
-import { generateThemeVariables, checkContrasts } from '../color-algorithms';
-import { HStack } from '../../h-stack';
-
-const meta: Meta< typeof Theme > = {
-	component: Theme,
-	title: 'Components/Utilities/Theme',
-	id: 'components-theme',
-	argTypes: {
-		accent: { control: { type: 'color' } },
-		background: { control: { type: 'color' } },
-	},
-	tags: [ 'status-private' ],
-	parameters: {
-		controls: { expanded: true },
-		docs: { canvas: { sourceState: 'shown' } },
-		componentStatus: {
-			status: 'not-recommended',
-			whereUsed: 'global',
-			notes: 'This is an internal experiment and not meant for external use. Will be superseded by `@wordpress/theme`.',
-		},
-	},
-};
-export default meta;
-
-const Template: StoryFn< typeof Theme > = ( args ) => (
-	<Theme { ...args }>
-		<Button __next40pxDefaultSize variant="primary">
-			Hello
-		</Button>
-	</Theme>
-);
-
-export const Default = Template.bind( {} );
-Default.args = {};
-
-export const Nested: StoryFn< typeof Theme > = ( args ) => (
-	<Theme accent="crimson">
-		<Button __next40pxDefaultSize variant="primary">
-			Outer theme (hardcoded)
-		</Button>
-
-		<Theme { ...args }>
-			<Button __next40pxDefaultSize variant="primary">
-				Inner theme (set via Storybook controls)
-			</Button>
-		</Theme>
-	</Theme>
-);
-Nested.args = {
-	accent: 'blue',
-};
-
-/**
- * The rest of the required colors are generated based on the given accent and background colors.
- */
-export const ColorScheme: StoryFn< typeof Theme > = ( {
-	accent,
-	background,
-} ) => {
-	const { colors } = generateThemeVariables( { accent, background } );
-	const { gray, ...otherColors } = colors;
-	/* eslint-disable @typescript-eslint/no-unused-vars */
-	const contrastIssues = Object.entries(
-		checkContrasts( { accent, background }, colors )
-	).filter( ( [ _, error ] ) => !! error );
-	/* eslint-enable @typescript-eslint/no-unused-vars */
-
-	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: '#3858e9',
-	background: '#fff',
-};
-ColorScheme.argTypes = {
-	children: { table: { disable: true } },
-};
-ColorScheme.parameters = {
-	docs: { canvas: { sourceState: 'hidden' } },
-};

package/src/theme/style.module.scss

@@ -1,4 +0,0 @@
-.wrapper {
-	/* stylelint-disable-next-line declaration-property-value-disallowed-list -- Preserve Theme's currentColor fallback when no foreground variable is generated. */
-	color: var(--wp-components-color-foreground, currentColor);
-}

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

@@ -1,100 +0,0 @@
-/**
- * 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: '#1a1a1a' } );
-			expect( console ).toHaveWarnedWith(
-				'wp.components.Theme: The background color ("#1a1a1a") does not have sufficient contrast against the accent color ("#3858e9").'
-			);
-		} );
-
-		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

@@ -1,151 +0,0 @@
-import { render, screen } from '@testing-library/react';
-import type { ReactNode } from 'react';
-
-import Theme from '../';
-
-type MyThemableComponentProps = {
-	children: ReactNode;
-};
-
-const MyThemableComponent = ( props: MyThemableComponentProps ) => {
-	return (
-		<div
-			{ ...props }
-			style={ {
-				color: 'var(--wp-components-color-accent)',
-			} }
-		/>
-	);
-};
-
-describe( 'Theme', () => {
-	it( 'should support the as prop', () => {
-		render( <Theme as="section" data-testid="theme" /> );
-
-		expect( screen.getByTestId( 'theme' ) ).toHaveProperty(
-			'tagName',
-			'SECTION'
-		);
-	} );
-
-	it( 'lets user styles override generated theme variables', () => {
-		render(
-			<Theme
-				accent="#123abc"
-				style={ { '--wp-components-color-accent': '#654321' } }
-				data-testid="theme"
-			/>
-		);
-
-		expect( screen.getByTestId( 'theme' ) ).toHaveStyle( {
-			'--wp-components-color-accent': '#654321',
-		} );
-	} );
-
-	describe( 'accent color', () => {
-		it( 'does not define the accent color (and its variations) as a CSS variable when the `accent` prop is undefined', () => {
-			render(
-				<Theme data-testid="theme">
-					<MyThemableComponent>Inner</MyThemableComponent>
-				</Theme>
-			);
-
-			const innerElementStyles = window.getComputedStyle(
-				screen.getByTestId( 'theme' )
-			);
-
-			[
-				'--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( 'defines the accent color (and its variations) as a CSS variable', () => {
-			render(
-				<Theme accent="#123abc" data-testid="theme">
-					<MyThemableComponent>Inner</MyThemableComponent>
-				</Theme>
-			);
-
-			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( '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( '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.each( [ 'accent', 'background' ] )( '%s', ( propName ) => {
-			it.each( [
-				// Keywords
-				'currentcolor',
-				'initial',
-				'reset',
-				'inherit',
-				'revert',
-				'unset',
-				// CSS Custom properties
-				'var( --my-variable )',
-			] )( 'should warn when the value is "%s"', ( value ) => {
-				render( <Theme { ...{ [ propName ]: value } } /> );
-				expect( console ).toHaveWarned();
-			} );
-		} );
-	} );
-} );