@wordpress/components 21.2.0 → 21.3.0

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

package/src/modal/types.ts

@@ -0,0 +1,144 @@
+/**
+ * External dependencies
+ */
+import type {
+	AriaRole,
+	CSSProperties,
+	ReactNode,
+	KeyboardEventHandler,
+	KeyboardEvent,
+	SyntheticEvent,
+} from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import type { useFocusOnMount } from '@wordpress/compose';
+
+export type ModalProps = {
+	aria?: {
+		/**
+		 * If this property is added, it will be added to the modal content
+		 * `div` as `aria-describedby`.
+		 */
+		describedby?: 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.
+		 */
+		labelledby?: string;
+	};
+	/**
+	 * Class name added to the body element when the modal is open.
+	 *
+	 * @default 'modal-open'
+	 */
+	bodyOpenClassName?: string;
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
+	/**
+	 * If this property is added, it will an additional class name to the modal
+	 * content `div`.
+	 */
+	className?: string;
+	/**
+	 * Label on the close button.
+	 */
+	closeButtonLabel?: string;
+	/**
+	 * 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.
+	 */
+	contentLabel?: string;
+	/**
+	 * If this property is true, it will focus the first tabbable element
+	 * rendered in the modal.
+	 *
+	 * @default true
+	 */
+	focusOnMount?: Parameters< typeof useFocusOnMount >[ 0 ];
+	/**
+	 * If this property is added, an icon will be added before the title.
+	 */
+	icon?: JSX.Element;
+	/**
+	 * If this property is set to false, the modal will not display a close icon
+	 * and cannot be dismissed.
+	 *
+	 * @default true
+	 */
+	isDismissible?: boolean;
+	/**
+	 * This property when set to `true` will render a full screen modal.
+	 *
+	 * @default false
+	 */
+	isFullScreen?: boolean;
+	/**
+	 *  Handle the key down on the modal frame `div`.
+	 */
+	onKeyDown?: KeyboardEventHandler< HTMLDivElement >;
+	/**
+	 * This function is called to indicate that the modal should be closed.
+	 */
+	onRequestClose: (
+		event?: KeyboardEvent< HTMLDivElement > | SyntheticEvent
+	) => void;
+	/**
+	 * If this property is added, it will an additional class name to the modal
+	 * overlay `div`.
+	 */
+	overlayClassName?: string;
+	/**
+	 * If this property is added, it will override the default role of the
+	 * modal.
+	 *
+	 * @default 'dialog'
+	 */
+	role?: AriaRole;
+	/**
+	 * If this property is added, it will determine whether the modal requests
+	 * to close when a mouse click occurs outside of the modal content.
+	 *
+	 * @default true
+	 */
+	shouldCloseOnClickOutside?: boolean;
+	/**
+	 * If this property is added, it will determine whether the modal requests
+	 * to close when the escape key is pressed.
+	 *
+	 * @default true
+	 */
+	shouldCloseOnEsc?: boolean;
+	/**
+	 * If this property is added, it will be added to the modal frame `div`.
+	 */
+	style?: CSSProperties;
+	/**
+	 * 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.
+	 */
+	title?: string;
+	/**
+	 * 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.
+	 *
+	 * @default false
+	 */
+	__experimentalHideHeader?: boolean;
+};

package/src/navigation/test/index.js

@@ -220,7 +220,7 @@ describe( 'Navigation', () => {
 		render( <TestNavigation showBadge /> );
 
 		const menuItem = screen.getAllByRole( 'listitem' );
-		expect( menuItem[ 0 ].textContent ).toBe( 'Item 1' + '21' );
+		expect( menuItem[ 0 ] ).toHaveTextContent( 'Item 1' + '21' );
 	} );
 
 	it( 'should render menu titles when items exist', () => {

package/src/navigator/index.ts

@@ -1,5 +1,5 @@
-export { default as NavigatorProvider } from './navigator-provider';
-export { default as NavigatorScreen } from './navigator-screen';
-export { default as NavigatorButton } from './navigator-button';
-export { default as NavigatorBackButton } from './navigator-back-button';
+export { NavigatorProvider } from './navigator-provider';
+export { NavigatorScreen } from './navigator-screen';
+export { NavigatorButton } from './navigator-button';
+export { NavigatorBackButton } from './navigator-back-button';
 export { default as useNavigator } from './use-navigator';

package/src/navigator/navigator-back-button/component.tsx

@@ -11,7 +11,7 @@ import { View } from '../../view';
 import { useNavigatorBackButton } from './hook';
 import type { NavigatorBackButtonProps } from '../types';
 
-function NavigatorBackButton(
+function UnconnectedNavigatorBackButton(
 	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >,
 	forwardedRef: ForwardedRef< any >
 ) {
@@ -54,9 +54,9 @@ function NavigatorBackButton(
  * );
  * ```
  */
-const ConnectedNavigatorBackButton = contextConnect(
-	NavigatorBackButton,
+export const NavigatorBackButton = contextConnect(
+	UnconnectedNavigatorBackButton,
 	'NavigatorBackButton'
 );
 
-export default ConnectedNavigatorBackButton;
+export default NavigatorBackButton;

package/src/navigator/navigator-back-button/index.ts

@@ -1 +1 @@
-export { default } from './component';
+export { default as NavigatorBackButton } from './component';

package/src/navigator/navigator-button/component.tsx

@@ -11,7 +11,7 @@ import { View } from '../../view';
 import { useNavigatorButton } from './hook';
 import type { NavigatorButtonProps } from '../types';
 
-function NavigatorButton(
+function UnconnectedNavigatorButton(
 	props: WordPressComponentProps< NavigatorButtonProps, 'button' >,
 	forwardedRef: ForwardedRef< any >
 ) {
@@ -53,9 +53,9 @@ function NavigatorButton(
  * );
  * ```
  */
-const ConnectedNavigatorButton = contextConnect(
-	NavigatorButton,
+export const NavigatorButton = contextConnect(
+	UnconnectedNavigatorButton,
 	'NavigatorButton'
 );
 
-export default ConnectedNavigatorButton;
+export default NavigatorButton;

package/src/navigator/navigator-button/index.ts

@@ -1 +1 @@
-export { default } from './component';
+export { default as NavigatorButton } from './component';

package/src/navigator/navigator-provider/component.tsx

@@ -26,7 +26,7 @@ import type {
 	NavigatorContext as NavigatorContextType,
 } from '../types';
 
-function NavigatorProvider(
+function UnconnectedNavigatorProvider(
 	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) {
@@ -49,6 +49,7 @@ function NavigatorProvider(
 					...options,
 					path,
 					isBack: false,
+					hasRestoredFocus: false,
 				},
 			] );
 		},
@@ -62,6 +63,7 @@ function NavigatorProvider(
 				{
 					...locationHistory[ locationHistory.length - 2 ],
 					isBack: true,
+					hasRestoredFocus: false,
 				},
 			] );
 		}
@@ -129,9 +131,9 @@ function NavigatorProvider(
  * );
  * ```
  */
-const ConnectedNavigatorProvider = contextConnect(
-	NavigatorProvider,
+export const NavigatorProvider = contextConnect(
+	UnconnectedNavigatorProvider,
 	'NavigatorProvider'
 );
 
-export default ConnectedNavigatorProvider;
+export default NavigatorProvider;

package/src/navigator/navigator-provider/index.ts

@@ -1 +1 @@
-export { default } from './component';
+export { default as NavigatorProvider } from './component';