Add a higher order component to constrain Tab keyboard navigation.

components/higher-order/with-focus-contain/README.md

@@ -0,0 +1,7 @@
+# withFocusContain
+
+`withFocusContain` is a React [higher-order component](https://facebook.github.io/react/docs/higher-order-components.html) adding the ability to constrain keyboard navigation with the Tab key within a component. For accessibility reasons, some UI components need to constrain Tab navigation, for example modal dialogs or similar UI. Use of this component is recommended only in cases where a way to navigate away from the wrapped component is implemented by other means, usually by pressing the Escape key or using a specific UI control, e.g. a "Close" button.
+
+## Usage
+
+Wrap your original component with `withFocusContain`.

components/higher-order/with-focus-contain/index.js

@@ -0,0 +1,57 @@
+/**
+ * WordPress dependencies
+ */
+import { Component, createRef } from '@wordpress/element';
+import { keycodes } from '@wordpress/utils';
+import { focus } from '@wordpress/dom';
+
+const { TAB } = keycodes;
+
+const withFocusContain = ( WrappedComponent ) => {
+	return class extends Component {
+		constructor() {
+			super( ...arguments );
+
+			this.focusContainRef = createRef();
+			this.handleTabBehaviour = this.handleTabBehaviour.bind( this );
+		}
+
+		handleTabBehaviour( event ) {
+			if ( event.keyCode !== TAB ) {
+				return;
+			}
+
+			const tabbables = focus.tabbable.find( this.focusContainRef.current );
+			if ( ! tabbables.length ) {
+				return;
+			}
+			const firstTabbable = tabbables[ 0 ];
+			const lastTabbable = tabbables[ tabbables.length - 1 ];
+
+			if ( event.shiftKey && event.target === firstTabbable ) {
+				event.preventDefault();
+				lastTabbable.focus();
+			} else if ( ! event.shiftKey && event.target === lastTabbable ) {
+				event.preventDefault();
+				firstTabbable.focus();
+			}
+		}
+
+		render() {
+			// Disable reason: this component is non-interactive, but must capture
+			// events from the wrapped component to determine when the Tab key is used.
+			/* eslint-disable jsx-a11y/no-static-element-interactions */
+			return (
+				<div
+					onKeyDown={ this.handleTabBehaviour }
+					ref={ this.focusContainRef }
+				>
+					<WrappedComponent { ...this.props } />
+				</div>
+			);
+			/* eslint-enable jsx-a11y/no-static-element-interactions */
+		}
+	};
+};
+
+export default withFocusContain;

components/popover/index.js

@@ -17,12 +17,13 @@ import { keycodes } from '@wordpress/utils';
 import './style.scss';
 import { computePopoverPosition } from './utils';
 import withFocusReturn from '../higher-order/with-focus-return';
+import withFocusContain from '../higher-order/with-focus-contain';
 import PopoverDetectOutside from './detect-outside';
 import IconButton from '../icon-button';
 import ScrollLock from '../scroll-lock';
 import { Slot, Fill } from '../slot-fill';
 
-const FocusManaged = withFocusReturn( ( { children } ) => children );
+const FocusManaged = withFocusContain( withFocusReturn( ( { children } ) => children ) );
 
 const { ESCAPE } = keycodes;