feat(Modal): Add PreventModalAriaHidden component

src/Modal/ModalManager.js

@@ -9,7 +9,7 @@ import React, {
 } from 'react';
 
 import useEventListener from '../useEventListener';
-import {hideOthers} from 'aria-hidden';
+import {hideForModal} from './accessiblyHideModalBackground';
 
 const noop = () => {};
 
@@ -100,7 +100,7 @@ function ModalManager({children}) {
 	useEffect(() => {
 		if (modalStack.length) {
 			const topMostModal = modalStack[modalStack.length - 1];
-			const undoAriaHideOthers = hideOthers(topMostModal?.ref.current);
+			const undoAriaHideOthers = hideForModal(topMostModal?.ref.current);
 
 			return function cleanUp() {
 				undoAriaHideOthers();

src/Modal/README.mdx

@@ -18,7 +18,7 @@ React components and hooks for building accessible modals (dialogs).
 -   Handles focus management:
     -   Contain keyboard focus inside of the topmost modal
     -   Return keyboard focus to the element that triggered the modal after it is closed
-    -   Contain screen readers from navigating outside of the topmost modal
+    -   Contain screen reader navigation within the topmost modal
 -   Close the topmost modal when the <kbd>Esc</kbd> key is pressed
 -   Prevent scrolling "behind" the modal
 
@@ -153,3 +153,17 @@ function Modal({children, name, onRequestClose, ...otherProps}) {
 	);
 }
 ```
+
+### Preventing content outside of modals from being hidden to screen readers
+
+When a modal is open, the `aria-hidden` attribute will be applied to any elements outside of it. This is done to prevent users of screen reader software from accidentally navigating outside of the modal boundaries.
+
+If you want to prevent some elements (such as a live region used for accessible status updates) from being hidden in this way, you can wrap them in the `PreventModalAriaHidden` component:
+
+```jsx
+import {PreventModalAriaHidden} from 'base5-ui/Modal';
+
+<PreventModalAriaHidden>
+	<Status>...</Status>
+<PreventModalAriaHidden>
+```

src/Modal/accessiblyHideModalBackground.js

@@ -0,0 +1,27 @@
+import React from 'react';
+import {hideOthers} from 'aria-hidden';
+import PropTypes from 'prop-types';
+
+const PREVENT_ARIA_HIDDEN_ATTRIBUTE = 'data-prevent-aria-hidden';
+
+// hide everything except modalElement and elements with
+// the PREVENT_ARIA_HIDDEN_ATTRIBUTE
+function hideForModal(modalElement) {
+	return hideOthers([
+		modalElement,
+		...document.querySelectorAll(`[${PREVENT_ARIA_HIDDEN_ATTRIBUTE}]`),
+	]);
+}
+
+// A helper component that applies the PREVENT_ARIA_HIDDEN_ATTRIBUTE
+// to its (only) child component
+function PreventModalAriaHidden({children}) {
+	return React.cloneElement(React.Children.only(children), {
+		[PREVENT_ARIA_HIDDEN_ATTRIBUTE]: true,
+	});
+}
+PreventModalAriaHidden.propTypes = {
+	children: PropTypes.element.isRequired,
+};
+
+export {hideForModal, PreventModalAriaHidden};

src/Modal/index.js

@@ -8,5 +8,6 @@ export {
 } from './ModalManager';
 
 export {BodyScrollLock, useScrollLockStyles} from './BodyScrollLock';
+export {PreventModalAriaHidden} from './accessiblyHideModalBackground';
 
 export default Modal;