@wordpress/components 21.2.0 → 22.0.0

package/src/mobile/bottom-sheet/test/range-cell.native.js

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import { AccessibilityInfo } from 'react-native';
-import { create, act } from 'react-test-renderer';
+import { render, fireEvent } from 'test/helpers';
 
 /**
  * Internal dependencies
@@ -21,17 +21,19 @@ jest.mock( '@wordpress/compose', () => ( {
 	) ),
 } ) );
 
-const isScreenReaderEnabled = Promise.resolve( true );
 beforeAll( () => {
-	// Mock async native module to avoid act warning
-	AccessibilityInfo.isScreenReaderEnabled = jest.fn(
-		() => isScreenReaderEnabled
+	AccessibilityInfo.isScreenReaderEnabled.mockResolvedValue(
+		Promise.resolve( true )
 	);
 } );
 
+afterAll( () => {
+	AccessibilityInfo.isScreenReaderEnabled.mockReset();
+} );
+
 it( 'allows modifying units via a11y actions', async () => {
 	const mockOpenUnitPicker = jest.fn();
-	const renderer = create(
+	const { getByA11yLabel } = render(
 		<RangeCell
 			label="Opacity"
 			minimumValue={ 0 }
@@ -41,17 +43,18 @@ it( 'allows modifying units via a11y actions', async () => {
 			openUnitPicker={ mockOpenUnitPicker }
 		/>
 	);
-	// Await async update to component state to avoid act warning
-	await act( () => isScreenReaderEnabled );
-	const { onAccessibilityAction } = renderer.toJSON().props;
 
-	onAccessibilityAction( { nativeEvent: { actionName: 'activate' } } );
+	const opacityControl = getByA11yLabel( /Opacity/ );
+	fireEvent( opacityControl, 'accessibilityAction', {
+		nativeEvent: { actionName: 'activate' },
+	} );
+
 	expect( mockOpenUnitPicker ).toHaveBeenCalled();
 } );
 
 describe( 'when range lacks an adjustable unit', () => {
 	it( 'disallows modifying units via a11y actions', async () => {
-		const renderer = create(
+		const { getByA11yLabel } = render(
 			<RangeCell
 				label="Opacity"
 				minimumValue={ 0 }
@@ -60,10 +63,9 @@ describe( 'when range lacks an adjustable unit', () => {
 				onChange={ jest.fn() }
 			/>
 		);
-		// Await async update to component state to avoid act warning
-		await act( () => isScreenReaderEnabled );
-		const { onAccessibilityAction } = renderer.toJSON().props;
 
+		const opacityControl = getByA11yLabel( /Opacity/ );
+		const { onAccessibilityAction } = opacityControl.props;
 		expect( () =>
 			onAccessibilityAction( { nativeEvent: { actionName: 'activate' } } )
 		).not.toThrow();

package/src/modal/README.md

@@ -150,118 +150,117 @@ const MyModal = () => {
 The set of props accepted by the component will be specified below.
 Props not included in this set will be applied to the input elements.
 
-#### title
+#### `aria.describedby`: `string`
 
-This property is used as the modal header's title.
-
-Titles are required for accessibility reasons, see `aria.labelledby` and `contentLabel` for other ways to provide a title.
+If this property is added, it will be added to the modal content `div` as `aria-describedby`.
 
--   Type: `String`
 -   Required: No
 
-#### onRequestClose
+#### `aria.labelledby`: `string`
 
-This function is called to indicate that the modal should be closed.
+If this property is added, it will be added to the modal content `div` as `aria-labelledby`.
+Use this when you are rendering the title yourself within the modal's content area instead of using the `title` prop. This ensures the title is usable by assistive technology.
 
--   Type: `function`
--   Required: Yes
+Titles are required for accessibility reasons, see `contentLabel` and `title` for other ways to provide a title.
 
-#### contentLabel
+-   Required: No
+-   Default: if the `title` prop is provided, this will default to the id of the element that renders `title`
 
-If this property is added, it will be added to the modal content `div` as `aria-label`.
+#### `bodyOpenClassName`: `string`
 
-Titles are required for accessibility reasons, see `aria.labelledby` and `title` for other ways to provide a title.
+Class name added to the body element when the modal is open.
 
--   Type: `String`
 -   Required: No
+-   Default: `modal-open`
 
-#### aria.labelledby
+#### `className`: `string`
 
-If this property is added, it will be added to the modal content `div` as `aria-labelledby`.
-Use this when you are rendering the title yourself within the modal's content area instead of using the `title` prop. This ensures the title is usable by assistive technology.
-
-Titles are required for accessibility reasons, see `contentLabel` and `title` for other ways to provide a title.
+If this property is added, it will an additional class name to the modal content `div`.
 
--   Type: `String`
 -   Required: No
--   Default: if the `title` prop is provided, this will default to the id of the element that renders `title`
 
-#### aria.describedby
+#### `contentLabel`: `string`
 
-If this property is added, it will be added to the modal content `div` as `aria-describedby`.
+If this property is added, it will be added to the modal content `div` as `aria-label`.
+
+Titles are required for accessibility reasons, see `aria.labelledby` and `title` for other ways to provide a title.
 
--   Type: `String`
 -   Required: No
 
-#### focusOnMount
+#### `focusOnMount`: `boolean | 'firstElement'`
 
 If this property is true, it will focus the first tabbable element rendered in the modal.
 
--   Type: `boolean`
 -   Required: No
--   Default: true
+-   Default: `true`
 
-#### shouldCloseOnEsc
+#### `isDismissible`: `boolean`
 
-If this property is added, it will determine whether the modal requests to close when the escape key is pressed.
+If this property is set to false, the modal will not display a close icon and cannot be dismissed.
 
--   Type: `boolean`
 -   Required: No
--   Default: true
+-   Default: `true`
 
-#### shouldCloseOnClickOutside
+#### `isFullScreen`: `boolean`
 
-If this property is added, it will determine whether the modal requests to close when a mouse click occurs outside of the modal content.
+This property when set to `true` will render a full screen modal.
 
--   Type: `boolean`
 -   Required: No
--   Default: true
+-   Default: `false`
 
-#### isDismissible
+#### `onRequestClose`: ``
 
-If this property is set to false, the modal will not display a close icon and cannot be dismissed.
+This function is called to indicate that the modal should be closed.
 
--   Type: `boolean`
--   Required: No
--   Default: true
+-   Required: Yes
 
-#### className
+#### `overlayClassName`: `string`
 
-If this property is added, it will an additional class name to the modal content `div`.
+If this property is added, it will an additional class name to the modal overlay `div`.
 
--   Type: `String`
 -   Required: No
 
-#### role
+#### `role`: `AriaRole`
 
 If this property is added, it will override the default role of the modal.
 
--   Type: `String`
 -   Required: No
 -   Default: `dialog`
 
-#### overlayClassName
+#### `shouldCloseOnClickOutside`: `boolean`
 
-If this property is added, it will an additional class name to the modal overlay `div`.
+If this property is added, it will determine whether the modal requests to close when a mouse click occurs outside of the modal content.
 
--   Type: `String`
 -   Required: No
+-   Default: `true`
 
-#### isFullScreen
+#### `shouldCloseOnEsc`: `boolean`
 
-This property when set to `true` will render a full screen modal.
+If this property is added, it will determine whether the modal requests to close when the escape key is pressed.
+
+-   Required: No
+-   Default: `true`
+
+#### `style`: `CSSProperties`
+
+If this property is added, it will be added to the modal frame `div`.
+
+-   Required: No
+
+#### `title`: `string`
+
+This property is used as the modal header's title.
+
+Titles are required for accessibility reasons, see `aria.labelledby` and `contentLabel` for other ways to provide a title.
 
--   Type: `boolean`
 -   Required: No
--   Default: `false`
 
-#### __experimentalHideHeader
+#### `__experimentalHideHeader`: `boolean`
 
 When set to `true`, the Modal's header (including the icon, title and close button) will not be rendered.
 
-*Warning*: This property is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+_Warning_: This property is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 
--   Type: `boolean`
 -   Required: No
 -   Default: `false`
 

package/src/modal/{aria-helper.js → aria-helper.ts}

@@ -1,5 +1,3 @@
-// @ts-nocheck
-
 const LIVE_REGION_ARIA_ROLES = new Set( [
 	'alert',
 	'status',
@@ -8,7 +6,7 @@ const LIVE_REGION_ARIA_ROLES = new Set( [
 	'timer',
 ] );
 
-let hiddenElements = [],
+let hiddenElements: Element[] = [],
 	isHidden = false;
 
 /**
@@ -21,9 +19,9 @@ let hiddenElements = [],
  * we should consider removing these helper functions in favor of
  * `aria-modal="true"`.
  *
- * @param {Element} unhiddenElement The element that should not be hidden.
+ * @param {HTMLDivElement} unhiddenElement The element that should not be hidden.
  */
-export function hideApp( unhiddenElement ) {
+export function hideApp( unhiddenElement?: HTMLDivElement ) {
 	if ( isHidden ) {
 		return;
 	}
@@ -47,13 +45,13 @@ export function hideApp( unhiddenElement ) {
  *
  * @return {boolean} Whether the element should not be hidden from screen-readers.
  */
-export function elementShouldBeHidden( element ) {
+export function elementShouldBeHidden( element: Element ) {
 	const role = element.getAttribute( 'role' );
 	return ! (
 		element.tagName === 'SCRIPT' ||
 		element.hasAttribute( 'aria-hidden' ) ||
 		element.hasAttribute( 'aria-live' ) ||
-		LIVE_REGION_ARIA_ROLES.has( role )
+		( role && LIVE_REGION_ARIA_ROLES.has( role ) )
 	);
 }
 

package/src/modal/{index.js → index.tsx}

@@ -1,9 +1,8 @@
-// @ts-nocheck
-
 /**
  * External dependencies
  */
 import classnames from 'classnames';
+import type { ForwardedRef, KeyboardEvent, UIEvent } from 'react';
 
 /**
  * WordPress dependencies
@@ -33,11 +32,15 @@ import { close } from '@wordpress/icons';
 import * as ariaHelper from './aria-helper';
 import Button from '../button';
 import StyleProvider from '../style-provider';
+import type { ModalProps } from './types';
 
 // Used to count the number of open modals.
 let openModalCount = 0;
 
-function Modal( props, forwardedRef ) {
+function UnforwardedModal(
+	props: ModalProps,
+	forwardedRef: ForwardedRef< HTMLDivElement >
+) {
 	const {
 		bodyOpenClassName = 'modal-open',
 		role = 'dialog',
@@ -48,8 +51,8 @@ function Modal( props, forwardedRef ) {
 		isDismissible = true,
 		/* Accessibility. */
 		aria = {
-			labelledby: null,
-			describedby: null,
+			labelledby: undefined,
+			describedby: undefined,
 		},
 		onRequestClose,
 		icon,
@@ -64,7 +67,7 @@ function Modal( props, forwardedRef ) {
 		__experimentalHideHeader = false,
 	} = props;
 
-	const ref = useRef();
+	const ref = useRef< HTMLDivElement >();
 	const instanceId = useInstanceId( Modal );
 	const headingId = title
 		? `components-modal-header-${ instanceId }`
@@ -94,7 +97,7 @@ function Modal( props, forwardedRef ) {
 		};
 	}, [ bodyOpenClassName ] );
 
-	function handleEscapeKeyDown( event ) {
+	function handleEscapeKeyDown( event: KeyboardEvent< HTMLDivElement > ) {
 		if (
 			shouldCloseOnEsc &&
 			event.code === 'Escape' &&
@@ -108,8 +111,8 @@ function Modal( props, forwardedRef ) {
 	}
 
 	const onContentContainerScroll = useCallback(
-		( e ) => {
-			const scrollY = e?.target?.scrollTop ?? -1;
+		( e: UIEvent< HTMLDivElement > ) => {
+			const scrollY = e?.currentTarget?.scrollTop ?? -1;
 
 			if ( ! hasScrolledContent && scrollY > 0 ) {
 				setHasScrolledContent( true );
@@ -147,9 +150,9 @@ function Modal( props, forwardedRef ) {
 					] ) }
 					role={ role }
 					aria-label={ contentLabel }
-					aria-labelledby={ contentLabel ? null : headingId }
+					aria-labelledby={ contentLabel ? undefined : headingId }
 					aria-describedby={ aria.describedby }
-					tabIndex="-1"
+					tabIndex={ -1 }
 					{ ...( shouldCloseOnClickOutside
 						? focusOutsideProps
 						: {} ) }
@@ -204,4 +207,37 @@ function Modal( props, forwardedRef ) {
 	);
 }
 
-export default forwardRef( Modal );
+/**
+ * Modals give users information and choices related to a task they’re trying to
+ * accomplish. They can contain critical information, require decisions, or
+ * involve multiple tasks.
+ *
+ * ```jsx
+ * import { Button, Modal } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyModal = () => {
+ *   const [ isOpen, setOpen ] = useState( false );
+ *   const openModal = () => setOpen( true );
+ *   const closeModal = () => setOpen( false );
+ *
+ *   return (
+ *     <>
+ *       <Button variant="secondary" onClick={ openModal }>
+ *         Open Modal
+ *       </Button>
+ *       { isOpen && (
+ *         <Modal title="This is my modal" onRequestClose={ closeModal }>
+ *           <Button variant="secondary" onClick={ closeModal }>
+ *             My custom close button
+ *           </Button>
+ *         </Modal>
+ *       ) }
+ *     </>
+ *   );
+ * };
+ * ```
+ */
+export const Modal = forwardRef( UnforwardedModal );
+
+export default Modal;

package/src/modal/stories/{index.js → index.tsx}

@@ -1,33 +1,56 @@
 /**
  * External dependencies
  */
-import { boolean, text } from '@storybook/addon-knobs';
+import type { ComponentStory, ComponentMeta } from '@storybook/react';
 
 /**
- * Internal dependencies
+ * WordPress dependencies
  */
-import Button from '../../button';
-import Icon from '../../icon';
-import Modal from '../';
+import { useState } from '@wordpress/element';
 
 /**
- * WordPress dependencies
+ * Internal dependencies
  */
-import { useState } from '@wordpress/element';
-import { wordpress } from '@wordpress/icons';
+import Button from '../../button';
+import Modal from '../';
+import type { ModalProps } from '../types';
 
-export default {
-	title: 'Components/Modal',
+const meta: ComponentMeta< typeof Modal > = {
 	component: Modal,
+	title: 'Components/Modal',
+	argTypes: {
+		children: {
+			control: { type: null },
+		},
+		onKeyDown: {
+			control: { type: null },
+		},
+		focusOnMount: {
+			control: { type: 'boolean' },
+		},
+		role: {
+			control: { type: 'text' },
+		},
+		onRequestClose: {
+			action: 'onRequestClose',
+		},
+	},
 	parameters: {
-		knobs: { disable: false },
+		controls: { expanded: true },
 	},
 };
+export default meta;
 
-const ModalExample = ( props ) => {
+const Template: ComponentStory< typeof Modal > = ( {
+	onRequestClose,
+	...args
+} ) => {
 	const [ isOpen, setOpen ] = useState( false );
 	const openModal = () => setOpen( true );
-	const closeModal = () => setOpen( false );
+	const closeModal: ModalProps[ 'onRequestClose' ] = ( event ) => {
+		setOpen( false );
+		onRequestClose( event );
+	};
 
 	return (
 		<>
@@ -36,9 +59,9 @@ const ModalExample = ( props ) => {
 			</Button>
 			{ isOpen && (
 				<Modal
-					{ ...props }
 					onRequestClose={ closeModal }
 					style={ { maxWidth: '600px' } }
+					{ ...args }
 				>
 					<p>
 						Lorem ipsum dolor sit amet, consectetur adipiscing elit,
@@ -61,32 +84,14 @@ const ModalExample = ( props ) => {
 	);
 };
 
-export const _default = () => {
-	const title = text( 'title', 'Title' );
-	const showIcon = boolean( 'icon', false );
-	const isDismissible = boolean( 'isDismissible', true );
-	const focusOnMount = boolean( 'focusOnMount', true );
-	const shouldCloseOnEsc = boolean( 'shouldCloseOnEsc', true );
-	const shouldCloseOnClickOutside = boolean(
-		'shouldCloseOnClickOutside',
-		true
-	);
-	const __experimentalHideHeader = boolean(
-		'__experimentalHideHeader',
-		false
-	);
-
-	const iconComponent = showIcon ? <Icon icon={ wordpress } /> : null;
-
-	const modalProps = {
-		icon: iconComponent,
-		focusOnMount,
-		isDismissible,
-		shouldCloseOnEsc,
-		shouldCloseOnClickOutside,
-		title,
-		__experimentalHideHeader,
-	};
-
-	return <ModalExample { ...modalProps } />;
+export const Default: ComponentStory< typeof Modal > = Template.bind( {} );
+Default.args = {
+	title: 'Title',
+};
+Default.parameters = {
+	docs: {
+		source: {
+			code: '',
+		},
+	},
 };

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

@@ -8,10 +8,15 @@ import { render, screen, within } from '@testing-library/react';
  */
 import Modal from '../';
 
+const noop = () => {};
+
 describe( 'Modal', () => {
 	it( 'applies the aria-describedby attribute when provided', () => {
 		render(
-			<Modal aria={ { describedby: 'description-id' } }>
+			<Modal
+				aria={ { describedby: 'description-id' } }
+				onRequestClose={ noop }
+			>
 				{ /* eslint-disable-next-line no-restricted-syntax */ }
 				<p id="description-id">Description</p>
 			</Modal>
@@ -24,7 +29,7 @@ describe( 'Modal', () => {
 
 	it( 'applies the aria-labelledby attribute when provided', () => {
 		render(
-			<Modal aria={ { labelledby: 'title-id' } }>
+			<Modal aria={ { labelledby: 'title-id' } } onRequestClose={ noop }>
 				{ /* eslint-disable-next-line no-restricted-syntax */ }
 				<h1 id="title-id">Modal Title Text</h1>
 			</Modal>
@@ -39,6 +44,7 @@ describe( 'Modal', () => {
 			<Modal
 				title="Modal Title Attribute"
 				aria={ { labelledby: 'title-id' } }
+				onRequestClose={ noop }
 			>
 				{ /* eslint-disable-next-line no-restricted-syntax */ }
 				<h1 id="title-id">Modal Title Text</h1>
@@ -51,7 +57,11 @@ describe( 'Modal', () => {
 
 	it( 'hides the header when the `__experimentalHideHeader` prop is used', () => {
 		render(
-			<Modal title="Test Title" __experimentalHideHeader>
+			<Modal
+				title="Test Title"
+				__experimentalHideHeader
+				onRequestClose={ noop }
+			>
 				<p>Modal content</p>
 			</Modal>
 		);