@wordpress/components 19.9.0 → 19.10.0

package/src/select-control/styles/select-control-styles.ts

@@ -8,11 +8,12 @@ import styled from '@emotion/styled';
  * Internal dependencies
  */
 import { COLORS, rtl } from '../../utils';
-import type { Size } from '../types';
+import type { SelectControlProps } from '../types';
 
-interface SelectProps {
-	disabled?: boolean;
-	selectSize?: Size;
+interface SelectProps extends Pick< SelectControlProps, 'disabled' > {
+	// Using `selectSize` instead of `size` to avoid a type conflict with the
+	// `size` HTML attribute of the `select` element.
+	selectSize?: SelectControlProps[ 'size' ];
 }
 
 const disabledStyles = ( { disabled }: SelectProps ) => {
@@ -23,14 +24,14 @@ const disabledStyles = ( { disabled }: SelectProps ) => {
 	} );
 };
 
-const fontSizeStyles = ( { selectSize }: SelectProps ) => {
+const fontSizeStyles = ( { selectSize = 'default' }: SelectProps ) => {
 	const sizes = {
 		default: '13px',
 		small: '11px',
 		'__unstable-large': '13px',
 	};
 
-	const fontSize = sizes[ selectSize as Size ];
+	const fontSize = sizes[ selectSize ];
 	const fontSizeMobile = '16px';
 
 	if ( ! fontSize ) return '';
@@ -44,7 +45,7 @@ const fontSizeStyles = ( { selectSize }: SelectProps ) => {
 	`;
 };
 
-const sizeStyles = ( { selectSize }: SelectProps ) => {
+const sizeStyles = ( { selectSize = 'default' }: SelectProps ) => {
 	const sizes = {
 		default: {
 			height: 30,
@@ -63,7 +64,7 @@ const sizeStyles = ( { selectSize }: SelectProps ) => {
 		},
 	};
 
-	const style = sizes[ selectSize as Size ] || sizes.default;
+	const style = sizes[ selectSize ];
 
 	return css( style );
 };

package/src/select-control/test/{select-control.js → select-control.tsx}

@@ -32,7 +32,7 @@ describe( 'SelectControl', () => {
 
 		expect( screen.getByText( 'Option 1' ) ).toBeInTheDocument();
 
-		const selectElement = screen.queryByLabelText( 'Select' );
+		const selectElement = screen.getByLabelText( 'Select' );
 
 		fireEvent.change( selectElement, {
 			target: { value: 'option-group-option-1' },
@@ -68,7 +68,7 @@ describe( 'SelectControl', () => {
 
 		expect( screen.getByText( 'Option 1' ) ).toBeInTheDocument();
 
-		const selectElement = screen.queryByLabelText( 'Select' );
+		const selectElement = screen.getByLabelText( 'Select' );
 
 		fireEvent.change( selectElement, {
 			target: { value: 'option-2' },

package/src/select-control/types.ts

@@ -1 +1,66 @@
-export type Size = 'default' | 'small' | '__unstable-large';
+/**
+ * External dependencies
+ */
+import type { ChangeEvent, FocusEvent, ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { InputBaseProps } from '../input-control/types';
+import type { BaseControlProps } from '../base-control/types';
+
+export interface SelectControlProps
+	extends Pick<
+			InputBaseProps,
+			| 'disabled'
+			| 'hideLabelFromVision'
+			| 'label'
+			| 'labelPosition'
+			| 'prefix'
+			| 'size'
+			| 'suffix'
+		>,
+		Pick< BaseControlProps, 'help' > {
+	/**
+	 * If this property is added, multiple values can be selected. The value passed should be an array.
+	 *
+	 * @default false
+	 */
+	multiple?: boolean;
+	onBlur?: ( event: FocusEvent< HTMLSelectElement > ) => void;
+	onFocus?: ( event: FocusEvent< HTMLSelectElement > ) => void;
+	/**
+	 * A function that receives the value of the new option that is being selected as input.
+	 *
+	 * If `multiple` is `true`, the value received is an array of the selected value.
+	 * Otherwise, the value received is a single value with the new selected value.
+	 */
+	onChange?: (
+		value: string | string[],
+		extra?: { event?: ChangeEvent< HTMLSelectElement > }
+	) => void;
+	options?: {
+		/**
+		 * The label to be shown to the user.
+		 */
+		label: string;
+		/**
+		 * The internal value used to choose the selected value.
+		 * This is also the value passed to `onChange` when the option is selected.
+		 */
+		value: string;
+		id?: string;
+		/**
+		 * Whether or not the option should have the disabled attribute.
+		 *
+		 * @default false
+		 */
+		disabled?: boolean;
+	}[];
+	value?: string | string[];
+	/**
+	 * As an alternative to the `options` prop, `optgroup`s and `options` can be
+	 * passed in as `children` for more customizability.
+	 */
+	children?: ReactNode;
+}

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/tools-panel/test/__snapshots__/index.js.snap

@@ -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();
 		} );
 	} );