@wordpress/components 26.0.1-next.5a1d1283.0 → 26.0.1

package/src/modal/aria-helper.ts

@@ -6,8 +6,7 @@ const LIVE_REGION_ARIA_ROLES = new Set( [
 	'timer',
 ] );
 
-let hiddenElements: Element[] = [],
-	isHidden = false;
+const hiddenElementsByDepth: Element[][] = [];
 
 /**
  * Hides all elements in the body element from screen-readers except
@@ -19,31 +18,28 @@ let hiddenElements: Element[] = [],
  * we should consider removing these helper functions in favor of
  * `aria-modal="true"`.
  *
- * @param {HTMLDivElement} unhiddenElement The element that should not be hidden.
+ * @param modalElement The element that should not be hidden.
  */
-export function hideApp( unhiddenElement?: HTMLDivElement ) {
-	if ( isHidden ) {
-		return;
-	}
+export function modalize( modalElement?: HTMLDivElement ) {
 	const elements = Array.from( document.body.children );
-	elements.forEach( ( element ) => {
-		if ( element === unhiddenElement ) {
-			return;
-		}
+	const hiddenElements: Element[] = [];
+	hiddenElementsByDepth.push( hiddenElements );
+	for ( const element of elements ) {
+		if ( element === modalElement ) continue;
+
 		if ( elementShouldBeHidden( element ) ) {
 			element.setAttribute( 'aria-hidden', 'true' );
 			hiddenElements.push( element );
 		}
-	} );
-	isHidden = true;
+	}
 }
 
 /**
  * Determines if the passed element should not be hidden from screen readers.
  *
- * @param {HTMLElement} element The element that should be checked.
+ * @param element The element that should be checked.
  *
- * @return {boolean} Whether the element should not be hidden from screen-readers.
+ * @return Whether the element should not be hidden from screen-readers.
  */
 export function elementShouldBeHidden( element: Element ) {
 	const role = element.getAttribute( 'role' );
@@ -56,16 +52,12 @@ export function elementShouldBeHidden( element: Element ) {
 }
 
 /**
- * Makes all elements in the body that have been hidden by `hideApp`
- * visible again to screen-readers.
+ * Accessibly reveals the elements hidden by the latest modal.
  */
-export function showApp() {
-	if ( ! isHidden ) {
-		return;
-	}
-	hiddenElements.forEach( ( element ) => {
+export function unmodalize() {
+	const hiddenElements = hiddenElementsByDepth.pop();
+	if ( ! hiddenElements ) return;
+
+	for ( const element of hiddenElements )
 		element.removeAttribute( 'aria-hidden' );
-	} );
-	hiddenElements = [];
-	isHidden = false;
 }

package/src/modal/index.tsx

@@ -2,7 +2,12 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import type { ForwardedRef, KeyboardEvent, UIEvent } from 'react';
+import type {
+	ForwardedRef,
+	KeyboardEvent,
+	MutableRefObject,
+	UIEvent,
+} from 'react';
 
 /**
  * WordPress dependencies
@@ -15,12 +20,13 @@ import {
 	useState,
 	forwardRef,
 	useLayoutEffect,
+	createContext,
+	useContext,
 } from '@wordpress/element';
 import {
 	useInstanceId,
 	useFocusReturn,
 	useFocusOnMount,
-	__experimentalUseFocusOutside as useFocusOutside,
 	useConstrainedTabbing,
 	useMergeRefs,
 } from '@wordpress/compose';
@@ -36,8 +42,13 @@ 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;
+// Used to track and dismiss the prior modal when another opens unless nested.
+const ModalContext = createContext<
+	MutableRefObject< ModalProps[ 'onRequestClose' ] | undefined >[]
+>( [] );
+
+// Used to track body class names applied while modals are open.
+const bodyOpenClasses = new Map< string, number >();
 
 function UnforwardedModal(
 	props: ModalProps,
@@ -66,25 +77,44 @@ function UnforwardedModal(
 		contentLabel,
 		onKeyDown,
 		isFullScreen = false,
+		size,
 		headerActions = null,
 		__experimentalHideHeader = false,
 	} = props;
 
 	const ref = useRef< HTMLDivElement >();
+
 	const instanceId = useInstanceId( Modal );
 	const headingId = title
 		? `components-modal-header-${ instanceId }`
 		: aria.labelledby;
-	const focusOnMountRef = useFocusOnMount( focusOnMount );
+
+	// The focus hook does not support 'firstContentElement' but this is a valid
+	// value for the Modal's focusOnMount prop. The following code ensures the focus
+	// hook will focus the first focusable node within the element to which it is applied.
+	// When `firstContentElement` is passed as the value of the focusOnMount prop,
+	// the focus hook is applied to the Modal's content element.
+	// Otherwise, the focus hook is applied to the Modal's ref. This ensures that the
+	// focus hook will focus the first element in the Modal's **content** when
+	// `firstContentElement` is passed.
+	const focusOnMountRef = useFocusOnMount(
+		focusOnMount === 'firstContentElement' ? 'firstElement' : focusOnMount
+	);
 	const constrainedTabbingRef = useConstrainedTabbing();
 	const focusReturnRef = useFocusReturn();
-	const focusOutsideProps = useFocusOutside( onRequestClose );
 	const contentRef = useRef< HTMLDivElement >( null );
 	const childrenContainerRef = useRef< HTMLDivElement >( null );
 
 	const [ hasScrolledContent, setHasScrolledContent ] = useState( false );
 	const [ hasScrollableContent, setHasScrollableContent ] = useState( false );
 
+	let sizeClass;
+	if ( isFullScreen || size === 'fill' ) {
+		sizeClass = 'is-full-screen';
+	} else if ( size ) {
+		sizeClass = `has-size-${ size }`;
+	}
+
 	// Determines whether the Modal content is scrollable and updates the state.
 	const isContentScrollable = useCallback( () => {
 		if ( ! contentRef.current ) {
@@ -100,20 +130,51 @@ function UnforwardedModal(
 		}
 	}, [ contentRef ] );
 
+	// Accessibly isolates/unisolates the modal.
 	useEffect( () => {
-		openModalCount++;
+		ariaHelper.modalize( ref.current );
+		return () => ariaHelper.unmodalize();
+	}, [] );
 
-		if ( openModalCount === 1 ) {
-			ariaHelper.hideApp( ref.current );
-			document.body.classList.add( bodyOpenClassName );
-		}
+	// Keeps a fresh ref for the subsequent effect.
+	const refOnRequestClose = useRef< ModalProps[ 'onRequestClose' ] >();
+	useEffect( () => {
+		refOnRequestClose.current = onRequestClose;
+	}, [ onRequestClose ] );
+
+	// The list of `onRequestClose` callbacks of open (non-nested) Modals. Only
+	// one should remain open at a time and the list enables closing prior ones.
+	const dismissers = useContext( ModalContext );
+	// Used for the tracking and dismissing any nested modals.
+	const nestedDismissers = useRef< typeof dismissers >( [] );
+
+	// Updates the stack tracking open modals at this level and calls
+	// onRequestClose for any prior and/or nested modals as applicable.
+	useEffect( () => {
+		dismissers.push( refOnRequestClose );
+		const [ first, second ] = dismissers;
+		if ( second ) first?.current?.();
 
+		const nested = nestedDismissers.current;
 		return () => {
-			openModalCount--;
+			nested[ 0 ]?.current?.();
+			dismissers.shift();
+		};
+	}, [ dismissers ] );
 
-			if ( openModalCount === 0 ) {
-				document.body.classList.remove( bodyOpenClassName );
-				ariaHelper.showApp();
+	// Adds/removes the value of bodyOpenClassName to body element.
+	useEffect( () => {
+		const theClass = bodyOpenClassName;
+		const oneMore = 1 + ( bodyOpenClasses.get( theClass ) ?? 0 );
+		bodyOpenClasses.set( theClass, oneMore );
+		document.body.classList.add( bodyOpenClassName );
+		return () => {
+			const oneLess = bodyOpenClasses.get( theClass )! - 1;
+			if ( oneLess === 0 ) {
+				document.body.classList.remove( theClass );
+				bodyOpenClasses.delete( theClass );
+			} else {
+				bodyOpenClasses.set( theClass, oneLess );
 			}
 		};
 	}, [ bodyOpenClassName ] );
@@ -148,7 +209,7 @@ function UnforwardedModal(
 
 		if (
 			shouldCloseOnEsc &&
-			event.code === 'Escape' &&
+			( event.code === 'Escape' || event.key === 'Escape' ) &&
 			! event.defaultPrevented
 		) {
 			event.preventDefault();
@@ -177,12 +238,9 @@ function UnforwardedModal(
 		onPointerUp: React.PointerEventHandler< HTMLDivElement >;
 	} = {
 		onPointerDown: ( event ) => {
-			if ( event.isPrimary && event.target === event.currentTarget ) {
+			if ( event.target === event.currentTarget ) {
 				pressTarget = event.target;
-				// Avoids loss of focus yet also leaves `useFocusOutside`
-				// practically useless with its only potential trigger being
-				// programmatic focus movement. TODO opt for either removing
-				// the hook or enhancing it such that this isn't needed.
+				// Avoids focus changing so that focus return works as expected.
 				event.preventDefault();
 			}
 		},
@@ -199,7 +257,7 @@ function UnforwardedModal(
 		},
 	};
 
-	return createPortal(
+	const modal = (
 		// eslint-disable-next-line jsx-a11y/no-static-element-interactions
 		<div
 			ref={ useMergeRefs( [ ref, forwardedRef ] ) }
@@ -214,25 +272,22 @@ function UnforwardedModal(
 				<div
 					className={ classnames(
 						'components-modal__frame',
-						className,
-						{
-							'is-full-screen': isFullScreen,
-						}
+						sizeClass,
+						className
 					) }
 					style={ style }
 					ref={ useMergeRefs( [
 						constrainedTabbingRef,
 						focusReturnRef,
-						focusOnMountRef,
+						focusOnMount !== 'firstContentElement'
+							? focusOnMountRef
+							: null,
 					] ) }
 					role={ role }
 					aria-label={ contentLabel }
 					aria-labelledby={ contentLabel ? undefined : headingId }
 					aria-describedby={ aria.describedby }
 					tabIndex={ -1 }
-					{ ...( shouldCloseOnClickOutside
-						? focusOutsideProps
-						: {} ) }
 					onKeyDown={ onKeyDown }
 				>
 					<div
@@ -283,11 +338,27 @@ function UnforwardedModal(
 								) }
 							</div>
 						) }
-						<div ref={ childrenContainerRef }>{ children }</div>
+
+						<div
+							ref={ useMergeRefs( [
+								childrenContainerRef,
+								focusOnMount === 'firstContentElement'
+									? focusOnMountRef
+									: null,
+							] ) }
+						>
+							{ children }
+						</div>
 					</div>
 				</div>
 			</StyleProvider>
-		</div>,
+		</div>
+	);
+
+	return createPortal(
+		<ModalContext.Provider value={ nestedDismissers.current }>
+			{ modal }
+		</ModalContext.Provider>,
 		document.body
 	);
 }

package/src/modal/stories/index.story.tsx

@@ -28,7 +28,8 @@ const meta: Meta< typeof Modal > = {
 			control: { type: null },
 		},
 		focusOnMount: {
-			control: { type: 'boolean' },
+			options: [ true, false, 'firstElement', 'firstContentElement' ],
+			control: { type: 'select' },
 		},
 		role: {
 			control: { type: 'text' },
@@ -60,11 +61,7 @@ const Template: StoryFn< typeof Modal > = ( { onRequestClose, ...args } ) => {
 				Open Modal
 			</Button>
 			{ isOpen && (
-				<Modal
-					onRequestClose={ closeModal }
-					style={ { maxWidth: '600px' } }
-					{ ...args }
-				>
+				<Modal onRequestClose={ closeModal } { ...args }>
 					<p>
 						Lorem ipsum dolor sit amet, consectetur adipiscing elit,
 						sed do eiusmod tempor incididunt ut labore et magna
@@ -100,6 +97,12 @@ Default.parameters = {
 	},
 };
 
+export const WithsizeSmall: StoryFn< typeof Modal > = Template.bind( {} );
+WithsizeSmall.args = {
+	size: 'small',
+};
+WithsizeSmall.storyName = 'With size: small';
+
 const LikeButton = () => {
 	const [ isLiked, setIsLiked ] = useState( false );
 	return (

package/src/modal/style.scss

@@ -50,6 +50,26 @@
 				max-width: none;
 			}
 		}
+
+		&.has-size-small,
+		&.has-size-medium,
+		&.has-size-large {
+			width: 100%;
+		}
+
+		// The following widths were selected to align with existing baselines
+		// found elsewhere in the editor.
+		// See https://github.com/WordPress/gutenberg/pull/54471#issuecomment-1723818809
+		&.has-size-small {
+			max-width: $modal-width-small;
+		}
+		&.has-size-medium {
+			max-width: $modal-width-medium;
+		}
+		&.has-size-large {
+			max-width: $modal-width-large;
+		}
+
 	}
 
 	@include break-large() {
@@ -140,7 +160,7 @@
 	}
 
 	&.is-scrollable:focus-visible {
-		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color);
+		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
 
 		// Windows High Contrast mode will show this outline, but not the box-shadow.
 		outline: 2px solid transparent;