@wordpress/components 19.8.3 → 19.10.0

package/src/text/test/{index.js → index.tsx}

@@ -59,14 +59,20 @@ describe( 'Text', () => {
 
 	test( 'should render as another element', () => {
 		const { container } = render( <Text as="div">Lorem ipsum.</Text> );
-		expect( container.firstChild.nodeName ).toBe( 'DIV' );
+		expect( container.firstChild?.nodeName ).toBe( 'DIV' );
 	} );
 
 	test( 'should render align', () => {
-		const { container } = render(
+		const { container: centerAlignedContainer } = render(
 			<Text align="center">Lorem ipsum.</Text>
 		);
-		expect( container.firstChild ).toHaveStyle( { textAlign: 'center' } );
+		const { container: defaultAlignedContainer } = render(
+			<Text>Lorem ipsum.</Text>
+		);
+
+		expect(
+			defaultAlignedContainer.children[ 0 ]
+		).toMatchStyleDiffSnapshot( centerAlignedContainer.children[ 0 ] );
 	} );
 
 	test( 'should render color', () => {
@@ -89,7 +95,7 @@ describe( 'Text', () => {
 		const wrapper = render(
 			<Text highlightWords={ [ 'm' ] }>Lorem ipsum.</Text>
 		);
-		expect( wrapper.container.firstChild.childNodes ).toHaveLength( 5 );
+		expect( wrapper.container.firstChild?.childNodes ).toHaveLength( 5 );
 		const words = await wrapper.findAllByText( 'm' );
 		expect( words ).toHaveLength( 2 );
 		words.forEach( ( word ) => expect( word.tagName ).toEqual( 'MARK' ) );
@@ -100,7 +106,7 @@ describe( 'Text', () => {
 			<Text 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( container.firstChild?.childNodes ).toHaveLength( 1 );
 	} );
 
 	test( 'should render highlighted words with highlightCaseSensitive', () => {
@@ -112,7 +118,7 @@ describe( 'Text', () => {
 
 		expect( container.firstChild ).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( container.firstChild?.childNodes ).toHaveLength( 1 );
 	} );
 
 	test( 'should render isBlock', () => {

package/src/text-control/index.tsx

@@ -0,0 +1,84 @@
+/**
+ * External dependencies
+ */
+import type { ChangeEvent, ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '../base-control';
+import type { WordPressComponentProps } from '../ui/context';
+import type { TextControlProps } from './types';
+
+function UnforwardedTextControl(
+	props: WordPressComponentProps< TextControlProps, 'input', false >,
+	ref: ForwardedRef< HTMLInputElement >
+) {
+	const {
+		label,
+		hideLabelFromVision,
+		value,
+		help,
+		className,
+		onChange,
+		type = 'text',
+		...additionalProps
+	} = props;
+	const instanceId = useInstanceId( TextControl );
+	const id = `inspector-text-control-${ instanceId }`;
+	const onChangeValue = ( event: ChangeEvent< HTMLInputElement > ) =>
+		onChange( event.target.value );
+
+	return (
+		<BaseControl
+			label={ label }
+			hideLabelFromVision={ hideLabelFromVision }
+			id={ id }
+			help={ help }
+			className={ className }
+		>
+			<input
+				className="components-text-control__input"
+				type={ type }
+				id={ id }
+				value={ value }
+				onChange={ onChangeValue }
+				aria-describedby={ !! help ? id + '__help' : undefined }
+				ref={ ref }
+				{ ...additionalProps }
+			/>
+		</BaseControl>
+	);
+}
+
+/**
+ * TextControl components let users enter and edit text.
+ *
+ *
+ * @example
+ * ```jsx
+ * import { TextControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyTextControl = () => {
+ *   const [ className, setClassName ] = useState( '' );
+ *
+ *   return (
+ *     <TextControl
+ *       label="Additional CSS Class"
+ *       value={ className }
+ *       onChange={ ( value ) => setClassName( value ) }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export const TextControl = forwardRef( UnforwardedTextControl );
+
+export default TextControl;

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

@@ -0,0 +1,66 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import TextControl from '..';
+
+const meta: ComponentMeta< typeof TextControl > = {
+	component: TextControl,
+	title: 'Components/TextControl',
+	argTypes: {
+		onChange: {
+			action: 'onChange',
+		},
+		value: {
+			control: { type: null },
+		},
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const DefaultTemplate: ComponentStory< typeof TextControl > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ value, setValue ] = useState( '' );
+
+	return (
+		<TextControl
+			{ ...args }
+			value={ value }
+			onChange={ ( v ) => {
+				setValue( v );
+				onChange( v );
+			} }
+		/>
+	);
+};
+
+export const Default: ComponentStory<
+	typeof TextControl
+> = DefaultTemplate.bind( {} );
+Default.args = {};
+
+export const WithLabelAndHelpText: ComponentStory<
+	typeof TextControl
+> = DefaultTemplate.bind( {} );
+WithLabelAndHelpText.args = {
+	...Default.args,
+	label: 'Label Text',
+	help: 'Help text to explain the input.',
+};

package/src/text-control/types.ts

@@ -0,0 +1,29 @@
+/**
+ * External dependencies
+ */
+import type { HTMLInputTypeAttribute } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+
+export type TextControlProps = Pick<
+	BaseControlProps,
+	'className' | 'hideLabelFromVision' | 'help' | 'label'
+> & {
+	/**
+	 * A function that receives the value of the input.
+	 */
+	onChange: ( value: string ) => void;
+	/**
+	 * The current value of the input.
+	 */
+	value: string | number;
+	/**
+	 * Type of the input element to render. Defaults to "text".
+	 *
+	 * @default 'text'
+	 */
+	type?: HTMLInputTypeAttribute;
+};

package/src/toggle-group-control/toggle-group-control-option-icon/component.tsx

@@ -1,14 +1,10 @@
-/**
- * WordPress dependencies
- */
-import { Icon } from '@wordpress/icons';
-
 /**
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../../ui/context';
 import type { ToggleGroupControlOptionIconProps } from '../types';
 import { ToggleGroupControlOptionBase } from '../toggle-group-control-option-base';
+import Icon from '../../icon';
 
 export default function ToggleGroupControlOptionIcon(
 	props: WordPressComponentProps<

package/src/toolbar-group/style.scss

@@ -5,6 +5,8 @@
 	display: inline-flex;
 	flex-shrink: 0;
 	flex-wrap: wrap;
+	padding-left: $grid-unit-15 * 0.5; // 6px.
+	padding-right: $grid-unit-15 * 0.5;
 
 	// Unset for nested toolbar groups. Increase specificity.
 	& .components-toolbar-group.components-toolbar-group {
@@ -13,6 +15,24 @@
 	}
 
 	line-height: 0;
+
+	// Size multiple sequential buttons to be optically balanced.
+	// Icons are 36px, as set by a 24px icon and 12px padding.
+	.components-button.components-button, // This needs specificity to override padding values inherited from the button component.
+	.components-button.has-icon.has-icon {
+		min-width: $block-toolbar-height - $grid-unit-15;
+		padding-left: $grid-unit-15 * 0.5; // 6px.
+		padding-right: $grid-unit-15 * 0.5;
+
+		svg {
+			min-width: $button-size-small; // This is the optimal icon size, and we size the whole button after this.
+		}
+
+		&::before {
+			left: 2px;
+			right: 2px;
+		}
+	}
 }
 
 // Legacy toolbar group

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

@@ -64,7 +64,7 @@ exports[`ToolsPanel first and last panel items should apply first/last classes t
   color: #1e1e1e;
   line-height: 1.2;
   margin: 0;
-  color: #050505;
+  color: #1e1e1e;
   font-size: calc(1.95 * 13px);
   font-weight: 600;
   display: block;
@@ -167,7 +167,7 @@ exports[`ToolsPanel first and last panel items should apply first/last classes t
         <button
           aria-expanded="false"
           aria-haspopup="true"
-          aria-label="View options"
+          aria-label="Panel header options"
           class="components-button components-dropdown-menu__toggle is-small has-icon"
           type="button"
         >

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

@@ -161,7 +161,7 @@ const renderPanel = () => {
  */
 const getMenuButton = () => {
 	return screen.getByRole( 'button', {
-		name: /view([\w\s]+)options/i,
+		name: /Panel([\w\s]+)header([\w\s]+)options/i,
 	} );
 };
 
@@ -178,7 +178,6 @@ const openDropdownMenu = () => {
 
 // Opens dropdown then selects the menu item by label before simulating a click.
 const selectMenuItem = async ( label ) => {
-	openDropdownMenu();
 	const menuItem = await screen.findByText( label );
 	fireEvent.click( menuItem );
 };
@@ -289,18 +288,30 @@ describe( 'ToolsPanel', () => {
 
 		it( 'should render panel item when corresponding menu item is selected', async () => {
 			renderPanel();
+			await openDropdownMenu();
 			await selectMenuItem( altControlProps.label );
 			const control = await screen.findByText( 'Alt control' );
 
 			expect( control ).toBeInTheDocument();
+
+			// Test the aria live announcement.
+			const announcement = await screen.getByText( 'Alt is now visible' );
+			expect( announcement ).toHaveAttribute( 'aria-live', 'assertive' );
 		} );
 
 		it( 'should prevent optional panel item rendering when toggled off via menu item', async () => {
 			renderPanel();
+			await openDropdownMenu();
 			await selectMenuItem( controlProps.label );
 			const control = screen.queryByText( 'Example control' );
 
 			expect( control ).not.toBeInTheDocument();
+
+			// Test the aria live announcement.
+			const announcement = await screen.getByText(
+				'Example hidden and reset to default'
+			);
+			expect( announcement ).toHaveAttribute( 'aria-live', 'assertive' );
 		} );
 
 		it( 'should continue to render shown by default item after it is toggled off via menu item', async () => {
@@ -319,10 +330,17 @@ describe( 'ToolsPanel', () => {
 
 			expect( control ).toBeInTheDocument();
 
+			await openDropdownMenu();
 			await selectMenuItem( controlProps.label );
 			const resetControl = screen.getByText( 'Default control' );
 
 			expect( resetControl ).toBeInTheDocument();
+
+			// Test the aria live announcement.
+			const announcement = await screen.getByText(
+				'Example reset to default'
+			);
+			expect( announcement ).toHaveAttribute( 'aria-live', 'assertive' );
 		} );
 
 		it( 'should render appropriate menu groups', async () => {
@@ -657,6 +675,8 @@ describe( 'ToolsPanel', () => {
 
 		it( 'should call onDeselect callback when menu item is toggled off', async () => {
 			renderPanel();
+
+			await openDropdownMenu();
 			await selectMenuItem( controlProps.label );
 
 			expect( controlProps.onSelect ).not.toHaveBeenCalled();
@@ -665,6 +685,8 @@ describe( 'ToolsPanel', () => {
 
 		it( 'should call onSelect callback when menu item is toggled on', async () => {
 			renderPanel();
+
+			await openDropdownMenu();
 			await selectMenuItem( altControlProps.label );
 
 			expect( altControlProps.onSelect ).toHaveBeenCalledTimes( 1 );
@@ -673,6 +695,8 @@ describe( 'ToolsPanel', () => {
 
 		it( 'should call resetAll callback when its menu item is selected', async () => {
 			renderPanel();
+
+			await openDropdownMenu();
 			await selectMenuItem( 'Reset all' );
 
 			expect( resetAll ).toHaveBeenCalledTimes( 1 );
@@ -688,6 +712,7 @@ describe( 'ToolsPanel', () => {
 		it( 'should call onDeselect after previous reset all', async () => {
 			renderPanel();
 
+			await openDropdownMenu();
 			await selectMenuItem( 'Reset all' ); // Initial control is displayed by default.
 			await selectMenuItem( controlProps.label ); // Re-display control.
 
@@ -715,9 +740,8 @@ describe( 'ToolsPanel', () => {
 			openDropdownMenu();
 
 			const defaultItem = screen.getByText( 'Nested Control 1' );
-			const defaultMenuItem = screen.getByRole( 'menuitemcheckbox', {
+			const defaultMenuItem = screen.getByRole( 'menuitem', {
 				name: 'Reset Nested Control 1',
-				checked: true,
 			} );
 
 			const altItem = screen.getByText( 'Nested Control 2' );
@@ -754,9 +778,8 @@ describe( 'ToolsPanel', () => {
 			openDropdownMenu();
 
 			const defaultItem = screen.getByText( 'Nested Control 1' );
-			const defaultMenuItem = screen.getByRole( 'menuitemcheckbox', {
+			const defaultMenuItem = screen.getByRole( 'menuitem', {
 				name: 'Reset Nested Control 1',
-				checked: true,
 			} );
 
 			const altItem = screen.getByText( 'Nested Control 2' );
@@ -807,6 +830,7 @@ describe( 'ToolsPanel', () => {
 			expect( secondItem ).toBeInTheDocument();
 
 			// Toggle on the first item.
+			await openDropdownMenu();
 			await selectMenuItem( altControlProps.label );
 
 			// The order of items should be as per their original source order.
@@ -964,7 +988,7 @@ describe( 'ToolsPanel', () => {
 			isShownByDefault: false,
 		};
 
-		it( 'should render appropriate icon for the dropdown menu where there are default controls', async () => {
+		it( 'should render appropriate labels and descriptions for the dropdown menu where there are default controls', async () => {
 			render(
 				<ToolsPanel { ...defaultProps }>
 					<ToolsPanelItem { ...defaultControls }>
@@ -977,13 +1001,18 @@ describe( 'ToolsPanel', () => {
 			);
 
 			const optionsDisplayedIcon = screen.getByRole( 'button', {
-				name: 'View options',
+				name: 'Panel header options',
 			} );
 
 			expect( optionsDisplayedIcon ).toBeInTheDocument();
+
+			// The dropdown toggle doesn't have a description when an option is displayed.
+			// In this case the default control is displayed.
+			expect( optionsDisplayedIcon ).not.toHaveAccessibleDescription();
 		} );
 
-		it( 'should render appropriate icons for the dropdown menu where there are no default controls', async () => {
+		it( 'should render appropriate labels and descriptions for the dropdown menu where there are no default controls', async () => {
+			// All options are inactive.
 			render(
 				<ToolsPanel { ...defaultProps }>
 					<ToolsPanelItem { ...optionalControls }>
@@ -992,25 +1021,49 @@ describe( 'ToolsPanel', () => {
 				</ToolsPanel>
 			);
 
-			// There are unactivated, optional menu items in the Tools Panel dropdown.
 			const optionsHiddenIcon = screen.getByRole( 'button', {
-				name: 'View and add options',
+				name: 'Panel header options',
 			} );
 
+			// The dropdown toggle has a description indicating that all options are hidden.
 			expect( optionsHiddenIcon ).toBeInTheDocument();
+			expect( optionsHiddenIcon ).toHaveAccessibleDescription(
+				'All options are currently hidden'
+			);
 
+			// Activate one of the options.
+			await openDropdownMenu();
 			await selectMenuItem( optionalControls.label );
 
-			// There are now NO unactivated, optional menu items in the Tools Panel dropdown.
-			expect(
-				screen.queryByRole( 'button', { name: 'View and add options' } )
-			).not.toBeInTheDocument();
-
 			const optionsDisplayedIcon = screen.getByRole( 'button', {
-				name: 'View options',
+				name: 'Panel header options',
 			} );
 
-			expect( optionsDisplayedIcon ).toBeInTheDocument();
+			// The dropdown toggle no longer has a description.
+			expect( optionsDisplayedIcon ).not.toHaveAccessibleDescription();
+		} );
+	} );
+
+	describe( 'reset all button', () => {
+		it( "should disable the reset all button when there's nothing to reset", async () => {
+			await renderPanel();
+			await openDropdownMenu();
+
+			const resetAllItem = await screen.findByRole( 'menuitem', {
+				disabled: false,
+			} );
+			expect( resetAllItem ).toBeInTheDocument();
+
+			await selectMenuItem( 'Reset all' );
+
+			// Test the aria live announcement.
+			const announcement = await screen.getByText( 'All options reset' );
+			expect( announcement ).toHaveAttribute( 'aria-live', 'assertive' );
+
+			const disabledResetAllItem = await screen.findByRole( 'menuitem', {
+				disabled: true,
+			} );
+			expect( disabledResetAllItem ).toBeInTheDocument();
 		} );
 	} );
 

package/src/tools-panel/tools-panel-header/component.tsx

@@ -6,6 +6,7 @@ import type { ForwardedRef } from 'react';
 /**
  * WordPress dependencies
  */
+import { speak } from '@wordpress/a11y';
 import { check, reset, moreVertical, plus } from '@wordpress/icons';
 import { __, _x, sprintf } from '@wordpress/i18n';
 
@@ -24,11 +25,8 @@ import type {
 	ToolsPanelHeaderProps,
 } from '../types';
 
-const noop = () => {};
-
 const DefaultControlsGroup = ( {
 	items,
-	onClose,
 	toggleItem,
 }: ToolsPanelControlsGroupProps ) => {
 	if ( ! items.length ) {
@@ -38,27 +36,41 @@ const DefaultControlsGroup = ( {
 	return (
 		<MenuGroup>
 			{ items.map( ( [ label, hasValue ] ) => {
-				const icon = hasValue ? reset : check;
-				const itemLabel = hasValue
-					? sprintf(
-							// translators: %s: The name of the control being reset e.g. "Padding".
-							__( 'Reset %s' ),
-							label
-					  )
-					: undefined;
+				if ( hasValue ) {
+					return (
+						<MenuItem
+							key={ label }
+							role="menuitem"
+							icon={ reset }
+							label={ sprintf(
+								// translators: %s: The name of the control being reset e.g. "Padding".
+								__( 'Reset %s' ),
+								label
+							) }
+							onClick={ () => {
+								toggleItem( label );
+								speak(
+									sprintf(
+										// translators: %s: The name of the control being reset e.g. "Padding".
+										__( '%s reset to default' ),
+										label
+									),
+									'assertive'
+								);
+							} }
+						>
+							{ label }
+						</MenuItem>
+					);
+				}
 
 				return (
 					<MenuItem
 						key={ label }
-						icon={ icon }
-						isSelected={ true }
-						disabled={ ! hasValue }
-						label={ itemLabel }
-						onClick={ () => {
-							toggleItem( label );
-							onClose();
-						} }
 						role="menuitemcheckbox"
+						icon={ check }
+						isSelected
+						aria-disabled
 					>
 						{ label }
 					</MenuItem>
@@ -70,7 +82,6 @@ const DefaultControlsGroup = ( {
 
 const OptionalControlsGroup = ( {
 	items,
-	onClose,
 	toggleItem,
 }: ToolsPanelControlsGroupProps ) => {
 	if ( ! items.length ) {
@@ -99,8 +110,26 @@ const OptionalControlsGroup = ( {
 						isSelected={ isSelected }
 						label={ itemLabel }
 						onClick={ () => {
+							if ( isSelected ) {
+								speak(
+									sprintf(
+										// translators: %s: The name of the control being reset e.g. "Padding".
+										__( '%s hidden and reset to default' ),
+										label
+									),
+									'assertive'
+								);
+							} else {
+								speak(
+									sprintf(
+										// translators: %s: The name of the control being reset e.g. "Padding".
+										__( '%s is now visible' ),
+										label
+									),
+									'assertive'
+								);
+							}
 							toggleItem( label );
-							onClose();
 						} }
 						role="menuitemcheckbox"
 					>
@@ -135,12 +164,18 @@ const ToolsPanelHeader = (
 	const defaultItems = Object.entries( menuItems?.default || {} );
 	const optionalItems = Object.entries( menuItems?.optional || {} );
 	const dropDownMenuIcon = areAllOptionalControlsHidden ? plus : moreVertical;
-	const dropDownMenuLabelText = areAllOptionalControlsHidden
-		? _x(
-				'View and add options',
-				'Button label to reveal tool panel options'
-		  )
-		: _x( 'View options', 'Button label to reveal tool panel options' );
+	const dropDownMenuLabelText = sprintf(
+		// translators: %s: The name of the tool e.g. "Color" or "Typography".
+		_x( '%s options', 'Button label to reveal tool panel options' ),
+		labelText
+	);
+	const dropdownMenuDescriptionText = areAllOptionalControlsHidden
+		? __( 'All options are currently hidden' )
+		: undefined;
+
+	const canResetAll = [ ...defaultItems, ...optionalItems ].some(
+		( [ , isSelected ] ) => isSelected
+	);
 
 	return (
 		<HStack { ...headerProps } ref={ forwardedRef }>
@@ -152,26 +187,33 @@ const ToolsPanelHeader = (
 					icon={ dropDownMenuIcon }
 					label={ dropDownMenuLabelText }
 					menuProps={ { className: dropdownMenuClassName } }
-					toggleProps={ { isSmall: true } }
+					toggleProps={ {
+						isSmall: true,
+						describedBy: dropdownMenuDescriptionText,
+					} }
 				>
-					{ ( { onClose = noop } ) => (
+					{ () => (
 						<>
 							<DefaultControlsGroup
 								items={ defaultItems }
-								onClose={ onClose }
 								toggleItem={ toggleItem }
 							/>
 							<OptionalControlsGroup
 								items={ optionalItems }
-								onClose={ onClose }
 								toggleItem={ toggleItem }
 							/>
 							<MenuGroup>
 								<MenuItem
+									aria-disabled={ ! canResetAll }
 									variant={ 'tertiary' }
 									onClick={ () => {
-										resetAll();
-										onClose();
+										if ( canResetAll ) {
+											resetAll();
+											speak(
+												__( 'All options reset' ),
+												'assertive'
+											);
+										}
 									} }
 								>
 									{ __( 'Reset all' ) }