@wordpress/components 22.1.0 → 23.1.0

package/src/tab-panel/types.ts

@@ -3,6 +3,11 @@
  */
 import type { ReactNode } from 'react';
 
+/**
+ * Internal dependencies
+ */
+import type { IconType } from '../icon';
+
 type Tab = {
 	/**
 	 * The key of the tab.
@@ -18,11 +23,14 @@ type Tab = {
 	className?: string;
 } & Record< any, any >;
 
-export type TabButtonProps = {
+export type TabButtonProps< IconProps = unknown > = {
 	children: ReactNode;
 	className?: string;
+	icon?: IconType< IconProps >;
+	label?: string;
 	onClick: ( event: MouseEvent ) => void;
 	selected: boolean;
+	showTooltip?: boolean;
 	tabId: string;
 };
 
@@ -62,4 +70,15 @@ export type TabPanelProps = {
 	 * Array of tab objects. Each tab object should contain at least a `name` and a `title`.
 	 */
 	tabs: Tab[];
+	/**
+	 * When `true`, the tab will be selected when receiving focus (automatic tab
+	 * activation). When `false`, the tab will be selected only when clicked
+	 * (manual tab activation). See the official W3C docs for more info.
+	 * .
+	 *
+	 * @default true
+	 *
+	 * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/
+	 */
+	selectOnMove?: boolean;
 };

package/src/text/test/__snapshots__/index.tsx.snap

@@ -36,6 +36,7 @@ exports[`Text should render highlighted words with highlightCaseSensitive 1`] =
     class="components-truncate components-text emotion-0 emotion-1"
     data-wp-c16t="true"
     data-wp-component="Text"
+    role="heading"
   >
     <span
       class=""

package/src/text/test/index.tsx

@@ -19,133 +19,185 @@ describe( 'Text', () => {
 	} );
 
 	test( 'should render optimizeReadabilityFor', () => {
-		const { container } = render(
-			<Text optimizeReadabilityFor="blue">Lorem ipsum.</Text>
+		render(
+			<Text role="heading" optimizeReadabilityFor="blue">
+				Lorem ipsum.
+			</Text>
 		);
-		expect( container.firstChild ).toHaveStyle( {
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
 			color: COLORS.white,
 		} );
 	} );
 
 	test( 'should render truncate', () => {
-		const { container } = render( <Text truncate>Lorem ipsum.</Text> );
-		expect( container.firstChild ).toHaveStyle( {
+		render(
+			<Text role="heading" truncate>
+				Lorem ipsum.
+			</Text>
+		);
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
 			textOverflow: 'ellipsis',
 		} );
 	} );
 
 	test( 'should render size', () => {
-		const { container } = render( <Text size="title">Lorem ipsum.</Text> );
-		expect( container.firstChild ).toHaveStyle( {
+		render(
+			<Text role="heading" size="title">
+				Lorem ipsum.
+			</Text>
+		);
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
 			fontSize: getFontSize( 'title' ),
 		} );
 	} );
 
 	test( 'should render custom size', () => {
-		const { container } = render( <Text size={ 15 }>Lorem ipsum.</Text> );
-		expect( container.firstChild ).toHaveStyle( {
+		render(
+			<Text role="heading" size={ 15 }>
+				Lorem ipsum.
+			</Text>
+		);
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
 			fontSize: getFontSize( 15 ),
 		} );
 	} );
 
 	test( 'should render variant', () => {
-		const { container } = render(
-			<Text variant="muted">Lorem ipsum.</Text>
+		render(
+			<Text role="heading" variant="muted">
+				Lorem ipsum.
+			</Text>
 		);
-		expect( container.firstChild ).toHaveStyle( {
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
 			color: COLORS.gray[ 700 ],
 		} );
 	} );
 
 	test( 'should render as another element', () => {
-		const { container } = render( <Text as="div">Lorem ipsum.</Text> );
-		expect( container.firstChild?.nodeName ).toBe( 'DIV' );
+		render(
+			<Text role="heading" as="div">
+				Lorem ipsum.
+			</Text>
+		);
+		expect( screen.getByRole( 'heading' )?.nodeName ).toBe( 'DIV' );
 	} );
 
 	test( 'should render align', () => {
-		const { container: centerAlignedContainer } = render(
-			<Text align="center">Lorem ipsum.</Text>
-		);
-		const { container: defaultAlignedContainer } = render(
-			<Text>Lorem ipsum.</Text>
+		render(
+			<>
+				<Text role="heading" align="center">
+					Lorem ipsum.
+				</Text>
+				<Text role="note">Lorem ipsum.</Text>
+			</>
 		);
 
-		expect(
-			defaultAlignedContainer.children[ 0 ]
-		).toMatchStyleDiffSnapshot( centerAlignedContainer.children[ 0 ] );
+		expect( screen.getByRole( 'note' ) ).toMatchStyleDiffSnapshot(
+			screen.getByRole( 'heading' )
+		);
 	} );
 
 	test( 'should render color', () => {
-		const { container } = render(
-			<Text color="orange">Lorem ipsum.</Text>
+		render(
+			<Text role="heading" color="orange">
+				Lorem ipsum.
+			</Text>
 		);
-		expect( container.firstChild ).toHaveStyle( { color: 'orange' } );
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
+			color: 'orange',
+		} );
 	} );
 
 	test( 'should render display', () => {
-		const { container } = render(
-			<Text display="inline-flex">Lorem ipsum.</Text>
+		render(
+			<Text role="heading" display="inline-flex">
+				Lorem ipsum.
+			</Text>
 		);
-		expect( container.firstChild ).toHaveStyle( {
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
 			display: 'inline-flex',
 		} );
 	} );
 
 	test( 'should render highlighted words', async () => {
-		const { container } = render(
-			<Text highlightWords={ [ 'm' ] }>Lorem ipsum.</Text>
+		render(
+			<Text role="heading" highlightWords={ [ 'm' ] }>
+				Lorem ipsum.
+			</Text>
 		);
-		expect( container.firstChild?.childNodes ).toHaveLength( 5 );
+		expect( screen.getByRole( 'heading' )?.childNodes ).toHaveLength( 5 );
 		const words = await screen.findAllByText( 'm' );
 		expect( words ).toHaveLength( 2 );
 		words.forEach( ( word ) => expect( word.tagName ).toEqual( 'MARK' ) );
 	} );
 
 	test( 'should render highlighted words with undefined passed', () => {
-		const { container } = render(
-			<Text highlightWords={ undefined }>Lorem ipsum.</Text>
+		render(
+			<Text role="heading" highlightWords={ undefined }>
+				Lorem ipsum.
+			</Text>
 		);
 		// It'll have a length of 1 because there shouldn't be anything but the single span being rendered.
-		expect( container.firstChild?.childNodes ).toHaveLength( 1 );
+		expect( screen.getByRole( 'heading' )?.childNodes ).toHaveLength( 1 );
 	} );
 
 	test( 'should render highlighted words with highlightCaseSensitive', () => {
 		const { container } = render(
-			<Text highlightCaseSensitive highlightWords={ [ 'IPSUM' ] }>
+			<Text
+				role="heading"
+				highlightCaseSensitive
+				highlightWords={ [ 'IPSUM' ] }
+			>
 				Lorem ipsum.
 			</Text>
 		);
 
 		expect( container ).toMatchSnapshot();
 		// It'll have a length of 1 because there shouldn't be anything but the single span being rendered.
-		expect( container.firstChild?.childNodes ).toHaveLength( 1 );
+		expect( screen.getByRole( 'heading' )?.childNodes ).toHaveLength( 1 );
 	} );
 
 	test( 'should render isBlock', () => {
-		const { container } = render( <Text isBlock>Lorem ipsum.</Text> );
-		expect( container.firstChild ).toHaveStyle( {
+		render(
+			<Text role="heading" isBlock>
+				Lorem ipsum.
+			</Text>
+		);
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
 			display: 'block',
 		} );
 	} );
 
 	test( 'should render lineHeight', () => {
-		const { container } = render(
-			<Text lineHeight={ 1.5 }>Lorem ipsum.</Text>
+		render(
+			<Text role="heading" lineHeight={ 1.5 }>
+				Lorem ipsum.
+			</Text>
 		);
-		expect( container.firstChild ).toHaveStyle( { lineHeight: '1.5' } );
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
+			lineHeight: '1.5',
+		} );
 	} );
 
 	test( 'should render upperCase', () => {
-		const { container } = render( <Text upperCase>Lorem ipsum.</Text> );
-		expect( container.firstChild ).toHaveStyle( {
+		render(
+			<Text role="heading" upperCase>
+				Lorem ipsum.
+			</Text>
+		);
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
 			textTransform: 'uppercase',
 		} );
 	} );
 
 	test( 'should render weight', () => {
-		const { container } = render(
-			<Text weight={ 700 }>Lorem ipsum.</Text>
+		render(
+			<Text role="heading" weight={ 700 }>
+				Lorem ipsum.
+			</Text>
 		);
-		expect( container.firstChild ).toHaveStyle( { fontWeight: '700' } );
+		expect( screen.getByRole( 'heading' ) ).toHaveStyle( {
+			fontWeight: '700',
+		} );
 	} );
 } );

package/src/text-control/stories/index.tsx

@@ -19,7 +19,6 @@ const meta: ComponentMeta< typeof TextControl > = {
 	argTypes: {
 		help: { control: { type: 'text' } },
 		label: { control: { type: 'text' } },
-		type: { control: { type: 'text' } },
 		onChange: { action: 'onChange' },
 		value: { control: { type: null } },
 	},

package/src/text-control/types.ts

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import type { HTMLInputTypeAttribute } from 'react';
-
 /**
  * Internal dependencies
  */
@@ -29,5 +24,5 @@ export type TextControlProps = Pick<
 	 *
 	 * @default 'text'
 	 */
-	type?: HTMLInputTypeAttribute;
+	type?: 'email' | 'number' | 'password' | 'tel' | 'text' | 'search' | 'url';
 };

package/src/text-highlight/test/index.tsx

@@ -11,6 +11,7 @@ import TextHighlight from '..';
 const getMarks = ( container: Element ) =>
 	// Use querySelectorAll because the `mark` role is not officially supported
 	// yet. This should be changed to `getByRole` when it is.
+	// eslint-disable-next-line testing-library/no-node-access
 	Array.from( container.querySelectorAll( 'mark' ) );
 
 const defaultText =

package/src/theme/README.md

@@ -17,7 +17,7 @@ const Example = () => {
 	return (
 		<Theme accent="red">
 			<Button variant="primary">I'm red</Button>
-			<Theme accent="blue">
+			<Theme accent="blue" background="black">
 				<Button variant="primary">I'm blue</Button>
 			</Theme>
 		</Theme>
@@ -29,6 +29,36 @@ const Example = () => {
 
 ### `accent`: `string`
 
-Used to set 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 — 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.
+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

@@ -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' } },
+};