@wordpress/components 22.1.0 → 23.1.0

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/test/index.tsx

@@ -18,6 +18,12 @@ import {
 	ToggleGroupControlOptionIcon,
 } from '../index';
 
+jest.useFakeTimers();
+
+function getWrappingPopoverElement( element: HTMLElement ) {
+	return element.closest( '.components-popover' );
+}
+
 describe( 'ToggleGroupControl', () => {
 	const options = (
 		<>
@@ -51,6 +57,7 @@ describe( 'ToggleGroupControl', () => {
 
 			expect( container ).toMatchSnapshot();
 		} );
+
 		it( 'with icons', () => {
 			const { container } = render(
 				<ToggleGroupControl
@@ -110,11 +117,17 @@ describe( 'ToggleGroupControl', () => {
 
 		await user.hover( firstRadio );
 
+		const tooltip = await screen.findByText(
+			'Click for Delicious Gnocchi'
+		);
+
 		await waitFor( () =>
 			expect(
-				screen.getByText( 'Click for Delicious Gnocchi' )
-			).toBeVisible()
+				getWrappingPopoverElement( tooltip )
+			).toBePositionedPopover()
 		);
+
+		expect( tooltip ).toBeVisible();
 	} );
 
 	it( 'should not render tooltip', async () => {

package/src/toolbar/style.scss

@@ -21,7 +21,7 @@
 		padding-right: $grid-unit-20;
 
 		// Don't show the focus inherited by the Button component.
-		&:focus:enabled {
+		&:focus:not(:disabled) {
 			box-shadow: none;
 			outline: none;
 		}

package/src/toolbar-group/test/index.js

@@ -76,15 +76,19 @@ describe( 'ToolbarGroup', () => {
 				],
 			];
 
-			const { container } = render(
-				<ToolbarGroup controls={ controls } />
-			);
+			render( <ToolbarGroup controls={ controls } /> );
 
 			const buttons = screen.getAllByRole( 'button' );
+
 			expect( buttons ).toHaveLength( 2 );
-			expect(
-				container.querySelector( '.has-left-divider button' )
-			).toBe( buttons[ 1 ] );
+			// eslint-disable-next-line testing-library/no-node-access
+			expect( buttons[ 0 ].parentElement ).not.toHaveClass(
+				'has-left-divider'
+			);
+			// eslint-disable-next-line testing-library/no-node-access
+			expect( buttons[ 1 ].parentElement ).toHaveClass(
+				'has-left-divider'
+			);
 		} );
 
 		it( 'should call the clickHandler on click.', () => {

package/src/tools-panel/stories/index.js

@@ -494,7 +494,7 @@ export const WithConditionallyRenderedControl = () => {
 	);
 };
 
-export { ToolsPanelWithItemGroupSlot } from './tools-panel-with-item-group-slot';
+export { ToolsPanelWithItemGroupSlot } from './utils/tools-panel-with-item-group-slot';
 
 const PanelWrapperView = styled.div`
 	font-size: 13px;

package/src/tools-panel/stories/{tools-panel-with-item-group-slot.js → utils/tools-panel-with-item-group-slot.js}

@@ -12,17 +12,20 @@ import { useContext, useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Button from '../../button';
-import ColorIndicator from '../../color-indicator';
-import ColorPalette from '../../color-palette';
-import Dropdown from '../../dropdown';
-import Panel from '../../panel';
-import { FlexItem } from '../../flex';
-import { HStack } from '../../h-stack';
-import { Item, ItemGroup } from '../../item-group';
-import { ToolsPanel, ToolsPanelItem, ToolsPanelContext } from '..';
-import { createSlotFill, Provider as SlotFillProvider } from '../../slot-fill';
-import { useCx } from '../../utils';
+import Button from '../../../button';
+import ColorIndicator from '../../../color-indicator';
+import ColorPalette from '../../../color-palette';
+import Dropdown from '../../../dropdown';
+import Panel from '../../../panel';
+import { FlexItem } from '../../../flex';
+import { HStack } from '../../../h-stack';
+import { Item, ItemGroup } from '../../../item-group';
+import { ToolsPanel, ToolsPanelItem, ToolsPanelContext } from '../..';
+import {
+	createSlotFill,
+	Provider as SlotFillProvider,
+} from '../../../slot-fill';
+import { useCx } from '../../../utils';
 
 // Available border colors.
 const colors = [

package/src/tools-panel/test/index.js

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import { render, screen, fireEvent, within } from '@testing-library/react';
+import { act } from 'react-test-renderer';
 
 /**
  * Internal dependencies
@@ -170,9 +171,10 @@ const getMenuButton = () => {
  *
  * @return {HTMLElement} The menuButton.
  */
-const openDropdownMenu = () => {
+const openDropdownMenu = async () => {
 	const menuButton = getMenuButton();
 	fireEvent.click( menuButton );
+	await act( () => Promise.resolve() );
 	return menuButton;
 };
 
@@ -240,16 +242,16 @@ describe( 'ToolsPanel', () => {
 			expect( menu ).not.toBeInTheDocument();
 		} );
 
-		it( 'should render panel menu when at least one panel item', () => {
+		it( 'should render panel menu when at least one panel item', async () => {
 			renderPanel();
 
-			const menuButton = openDropdownMenu();
+			const menuButton = await openDropdownMenu();
 			expect( menuButton ).toBeInTheDocument();
 		} );
 
 		it( 'should render reset all item in menu', async () => {
 			renderPanel();
-			openDropdownMenu();
+			await openDropdownMenu();
 
 			const resetAllItem = await screen.findByRole( 'menuitem' );
 
@@ -258,7 +260,7 @@ describe( 'ToolsPanel', () => {
 
 		it( 'should render panel menu items correctly', async () => {
 			renderPanel();
-			openDropdownMenu();
+			await openDropdownMenu();
 
 			const menuItems = await screen.findAllByRole( 'menuitemcheckbox' );
 
@@ -355,7 +357,7 @@ describe( 'ToolsPanel', () => {
 					</ToolsPanelItem>
 				</ToolsPanel>
 			);
-			openDropdownMenu();
+			await openDropdownMenu();
 
 			const menuGroups = screen.getAllByRole( 'group' );
 
@@ -419,7 +421,7 @@ describe( 'ToolsPanel', () => {
 			let linkedItem = screen.queryByText( 'Linked control' );
 			expect( linkedItem ).not.toBeInTheDocument();
 
-			openDropdownMenu();
+			await openDropdownMenu();
 
 			// The linked control should initially appear in the optional controls
 			// menu group. There should be three menu groups: default controls,
@@ -503,7 +505,7 @@ describe( 'ToolsPanel', () => {
 
 			// The conditional control should not yet appear in the default controls
 			// menu group.
-			openDropdownMenu();
+			await openDropdownMenu();
 			let menuGroups = screen.getAllByRole( 'group' );
 			let defaultItem = within( menuGroups[ 0 ] ).queryByText(
 				'Conditional'
@@ -735,7 +737,7 @@ describe( 'ToolsPanel', () => {
 
 		it( 'should render grouped items within the menu', async () => {
 			renderGroupedItemsInPanel();
-			openDropdownMenu();
+			await openDropdownMenu();
 
 			const defaultItem = screen.getByText( 'Nested Control 1' );
 			const defaultMenuItem = screen.getByRole( 'menuitem', {
@@ -771,9 +773,9 @@ describe( 'ToolsPanel', () => {
 			expect( altItem ).not.toBeInTheDocument();
 		} );
 
-		it( 'should render wrapped items within the menu', () => {
+		it( 'should render wrapped items within the menu', async () => {
 			renderWrappedItemInPanel();
-			openDropdownMenu();
+			await openDropdownMenu();
 
 			const defaultItem = screen.getByText( 'Nested Control 1' );
 			const defaultMenuItem = screen.getByRole( 'menuitem', {
@@ -1073,7 +1075,10 @@ describe( 'ToolsPanel', () => {
 						<ToolsPanelItem { ...altControlProps }>
 							<div>Item 1</div>
 						</ToolsPanelItem>
-						<ToolsPanelItem { ...controlProps }>
+						<ToolsPanelItem
+							{ ...controlProps }
+							data-testid="item-2"
+						>
 							<div>Item 2</div>
 						</ToolsPanelItem>
 					</ToolsPanelItems>
@@ -1081,6 +1086,7 @@ describe( 'ToolsPanel', () => {
 						<ToolsPanelItem
 							{ ...altControlProps }
 							label="Item 3"
+							data-testid="item-3"
 							isShownByDefault={ true }
 						>
 							<div>Item 3</div>
@@ -1111,8 +1117,8 @@ describe( 'ToolsPanel', () => {
 			expect( item3 ).toBeInTheDocument();
 			expect( screen.queryByText( 'Item 4' ) ).not.toBeInTheDocument();
 
-			expect( item2.parentElement ).toHaveClass( 'first' );
-			expect( item3.parentElement ).toHaveClass( 'last' );
+			expect( screen.getByTestId( 'item-2' ) ).toHaveClass( 'first' );
+			expect( screen.getByTestId( 'item-3' ) ).toHaveClass( 'last' );
 		} );
 	} );
 } );

package/src/tooltip/README.md

@@ -46,6 +46,13 @@ The tooltip text to show on focus or hover.
 -   Type: `String`
 -   Required: No
 
+### shortcut (web only)
+
+-   Type: `string` or `object`
+-   Required: No
+
+If shortcut is a string, it is expecting the display text. If shortcut is an object, it will accept the properties of `display` (string) and `ariaLabel` (string).
+
 ### delay (web only)
 
 Time in milliseconds to wait before showing tooltip after the tooltip's visibility is toggled. This prop is currently only available for the web platforms.