@wordpress/components 19.9.0 → 19.12.0

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/textarea-control/README.md

@@ -100,47 +100,41 @@ The set of props accepted by the component will be specified below.
 
 Props not included in this set will be applied to the textarea element.
 
-#### label
+#### `help`: `string | WPElement`
 
-If this property is added, a label will be generated using label property as the content.
+If this property is added, a help text will be generated using help property as the content.
 
--   Type: `String`
 -   Required: No
 
-#### hideLabelFromVision
+#### `hideLabelFromVision`: `boolean`
 
 If true, the label will only be visible to screen readers.
 
--   Type: `Boolean`
 -   Required: No
 
-#### help
+#### `label`: `string`
 
-If this property is added, a help text will be generated using help property as the content.
+If this property is added, a label will be generated using label property as the content.
 
--   Type: `String|WPElement`
 -   Required: No
 
-#### rows
+#### `onChange`: `( value: string ) => void`
 
-The number of rows the textarea should contain. Defaults to four.
+A function that receives the new value of the textarea each time it changes.
 
--   Type: `String`
--   Required: No
--   Default: 4
+-   Required: Yes
 
-#### value
+#### `rows`: `number`
 
-The current value of the textarea.
+The number of rows the textarea should contain.
 
--   Type: `String`
--   Required: Yes
+-   Required: No
+-   Default: 4
 
-#### onChange
+#### `value`: `string`
 
-A function that receives the new value of the textarea each time it changes.
+The current value of the textarea.
 
--   Type: `function`
 -   Required: Yes
 
 ## Related components

package/src/textarea-control/index.tsx

@@ -0,0 +1,86 @@
+/**
+ * External dependencies
+ */
+import type { ChangeEvent } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '../base-control';
+import { StyledTextarea } from './styles/textarea-control-styles';
+import type { TextareaControlProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+
+/**
+ * TextareaControls are TextControls that allow for multiple lines of text, and
+ * wrap overflow text onto a new line. They are a fixed height and scroll
+ * vertically when the cursor reaches the bottom of the field.
+ *
+ * ```jsx
+ * import { TextareaControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyTextareaControl = () => {
+ *   const [ text, setText ] = useState( '' );
+ *
+ *   return (
+ *     <TextareaControl
+ *       label="Text"
+ *       help="Enter some text"
+ *       value={ text }
+ *       onChange={ ( value ) => setText( value ) }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function TextareaControl(
+	// ref is omitted until we have `WordPressComponentPropsWithoutRef` or add
+	// ref forwarding to TextareaControl.
+	props: Omit<
+		WordPressComponentProps< TextareaControlProps, 'textarea', false >,
+		'ref'
+	>
+) {
+	const {
+		label,
+		hideLabelFromVision,
+		value,
+		help,
+		onChange,
+		rows = 4,
+		className,
+		...additionalProps
+	} = props;
+	const instanceId = useInstanceId( TextareaControl );
+	const id = `inspector-textarea-control-${ instanceId }`;
+	const onChangeValue = ( event: ChangeEvent< HTMLTextAreaElement > ) =>
+		onChange( event.target.value );
+
+	return (
+		<BaseControl
+			label={ label }
+			hideLabelFromVision={ hideLabelFromVision }
+			id={ id }
+			help={ help }
+			className={ className }
+		>
+			<StyledTextarea
+				className="components-textarea-control__input"
+				id={ id }
+				rows={ rows }
+				onChange={ onChangeValue }
+				aria-describedby={ !! help ? id + '__help' : undefined }
+				value={ value }
+				{ ...additionalProps }
+			/>
+		</BaseControl>
+	);
+}
+
+export default TextareaControl;

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

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

package/src/textarea-control/types.ts

@@ -0,0 +1,30 @@
+/**
+ * External dependencies
+ */
+import type { TextareaHTMLAttributes } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+
+export type TextareaControlProps = Pick<
+	BaseControlProps,
+	'hideLabelFromVision' | 'help' | 'label'
+> & {
+	/**
+	 * A function that receives the new value of the textarea each time it
+	 * changes.
+	 */
+	onChange: ( value: string ) => void;
+	/**
+	 * The current value of the textarea.
+	 */
+	value: string;
+	/**
+	 * The number of rows the textarea should contain.
+	 *
+	 * @default 4
+	 */
+	rows?: TextareaHTMLAttributes< HTMLTextAreaElement >[ 'rows' ];
+};

package/src/toggle-group-control/test/__snapshots__/index.js.snap

@@ -173,12 +173,9 @@ exports[`ToggleGroupControl should render correctly with icons 1`] = `
       id="toggle-group-control-1"
       role="radiogroup"
     >
-      <iframe
+      <div
         aria-hidden="true"
-        frameborder="0"
-        src="about:blank"
-        style="display: block; opacity: 0; position: absolute; top: 0px; left: 0px; height: 100%; width: 100%; overflow: hidden; pointer-events: none; z-index: -1;"
-        tabindex="-1"
+        style="position: absolute; top: 0px; left: 0px; right: 0px; bottom: 0px; pointer-events: none; opacity: 0; overflow: hidden; z-index: -1;"
       />
       <div
         class="emotion-8 emotion-9"
@@ -402,12 +399,9 @@ exports[`ToggleGroupControl should render correctly with text options 1`] = `
       id="toggle-group-control-0"
       role="radiogroup"
     >
-      <iframe
+      <div
         aria-hidden="true"
-        frameborder="0"
-        src="about:blank"
-        style="display: block; opacity: 0; position: absolute; top: 0px; left: 0px; height: 100%; width: 100%; overflow: hidden; pointer-events: none; z-index: -1;"
-        tabindex="-1"
+        style="position: absolute; top: 0px; left: 0px; right: 0px; bottom: 0px; pointer-events: none; opacity: 0; overflow: hidden; z-index: -1;"
       />
       <div
         class="emotion-8 emotion-9"

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

@@ -4,14 +4,18 @@
 import type { ForwardedRef } from 'react';
 // eslint-disable-next-line no-restricted-imports
 import { RadioGroup, useRadioState } from 'reakit';
-import useResizeAware from 'react-resize-aware';
 
 /**
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
 import { useRef, useMemo } from '@wordpress/element';
-import { useMergeRefs, useInstanceId, usePrevious } from '@wordpress/compose';
+import {
+	useMergeRefs,
+	useInstanceId,
+	usePrevious,
+	useResizeObserver,
+} from '@wordpress/compose';
 
 /**
  * Internal dependencies
@@ -49,7 +53,7 @@ function ToggleGroupControl(
 	} = useContextSystem( props, 'ToggleGroupControl' );
 	const cx = useCx();
 	const containerRef = useRef();
-	const [ resizeListener, sizes ] = useResizeAware();
+	const [ resizeListener, sizes ] = useResizeObserver();
 	const baseId = useInstanceId(
 		ToggleGroupControl,
 		'toggle-group-control'

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