Components: Add onFocusOutside alternative to Popover onClickOutside

lib/packages-dependencies.php

@@ -86,6 +86,7 @@
 		'wp-a11y',
 		'wp-api-fetch',
 		'wp-compose',
+		'wp-deprecated',
 		'wp-dom',
 		'wp-element',
 		'wp-hooks',

packages/components/CHANGELOG.md

@@ -1,15 +1,20 @@
-## 7.3.0 (Unreleased)
+## Unreleased
 
 ### New Features
 
 - Added a new `render` property to `FormFileUpload` component. Allowing users of the component to custom the UI for their needs.
 - Added a new `BaseControl.VisualLabel` component.
 - Added a new `preview` prop to the `Placeholder` component which allows to display a preview, for example a media preview when the Placeholder is used in media editing contexts.
+- Added a new `onFocusOutside` prop to the `Popover` component which serves in place of the existing `onClickOutside` to more accurately reflect all causes for focus transition.
 
 ### Bug fixes
 
 - Fix `instanceId` prop passed through to `Button` component via `MenuItems` producing React console error. Fixed by removing the unnecessary use of `withInstanceId` on the `MenuItems` component [#14599](https://github.com/WordPress/gutenberg/pull/14599)
 
+### Deprecations
+
+- The `Popover` component `onClickOutside` prop has been deprecated. Use `onFocusOutside` instead.
+
 ## 7.2.0 (2019-03-20)
 
 ### Improvements

packages/components/package.json

@@ -25,6 +25,7 @@
 		"@wordpress/a11y": "file:../a11y",
 		"@wordpress/api-fetch": "file:../api-fetch",
 		"@wordpress/compose": "file:../compose",
+		"@wordpress/deprecated": "file:../deprecated",
 		"@wordpress/dom": "file:../dom",
 		"@wordpress/element": "file:../element",
 		"@wordpress/hooks": "file:../hooks",

packages/components/src/popover/README.md

@@ -93,9 +93,11 @@ A callback invoked when the popover should be closed.
 - Type: `Function`
 - Required: No
 
-### onClickOutside
+### onFocusOutside
 
-A callback invoked when the user clicks outside the opened popover, passing the click event. The popover should be closed in response to this interaction. Defaults to `onClose`.
+A callback invoked when the focus leaves the opened popover. This should only be provided in advanced use-cases when a Popover should close under specific circumstances; for example, if the new `document.activeElement` is content of or otherwise controlling Popover visibility.
+
+Defaults to `onClose` when not provided.
 
 - Type: `Function`
 - Required: No

packages/components/src/popover/detect-outside.js

@@ -1,24 +1,21 @@
 /**
- * External dependencies
+ * WordPress dependencies
  */
-import clickOutside from 'react-click-outside';
+import { Component } from '@wordpress/element';
 
 /**
- * WordPress dependencies
+ * Internal dependencies
  */
-import { Component } from '@wordpress/element';
+import withFocusOutside from '../higher-order/with-focus-outside';
 
 class PopoverDetectOutside extends Component {
-	handleClickOutside( event ) {
-		const { onClickOutside } = this.props;
-		if ( onClickOutside ) {
-			onClickOutside( event );
-		}
+	handleFocusOutside( event ) {
+		this.props.onFocusOutside( event );
 	}
 
 	render() {
 		return this.props.children;
 	}
 }
 
-export default clickOutside( PopoverDetectOutside );
+export default withFocusOutside( PopoverDetectOutside );

packages/components/src/popover/index.js

@@ -10,6 +10,7 @@ import { Component, createRef } from '@wordpress/element';
 import { focus } from '@wordpress/dom';
 import { ESCAPE } from '@wordpress/keycodes';
 import isShallowEqual from '@wordpress/is-shallow-equal';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -40,6 +41,7 @@ class Popover extends Component {
 		this.getAnchorRect = this.getAnchorRect.bind( this );
 		this.computePopoverPosition = this.computePopoverPosition.bind( this );
 		this.maybeClose = this.maybeClose.bind( this );
+		this.onFocusOutside = this.onFocusOutside.bind( this );
 		this.throttledRefresh = this.throttledRefresh.bind( this );
 		this.refresh = this.refresh.bind( this );
 		this.refreshOnAnchorMove = this.refreshOnAnchorMove.bind( this );
@@ -94,6 +96,47 @@ class Popover extends Component {
 		this.toggleAutoRefresh( false );
 	}
 
+	/**
+	 * Shims an onFocusOutside callback to be compatible with a deprecated
+	 * onClickOutside prop function, if provided.
+	 *
+	 * @param {FocusEvent} event Focus event from onFocusOutside.
+	 */
+	onFocusOutside( event ) {
+		const { onClickOutside, onFocusOutside, onClose } = this.props;
+
+		// Defer to given `onFocusOutside` if specified. Call `onClose` only if
+		// both `onFocusOutside` and `onClickOutside` are unspecified. Doing so
+		// assures backwards-compatibility for prior `onClickOutside` default.
+		if ( onFocusOutside ) {
+			onFocusOutside( event );
+			return;
+		} else if ( ! onClickOutside ) {
+			onClose();
+			return;
+		}
+
+		// Simulate MouseEvent using FocusEvent#relatedTarget as emulated click
+		// target. MouseEvent constructor is unsupported in Internet Explorer.
+		let clickEvent;
+		try {
+			clickEvent = new window.MouseEvent( 'click' );
+		} catch ( error ) {
+			clickEvent = document.createEvent( 'MouseEvent' );
+			clickEvent.initMouseEvent( 'click', true, true, window, 0, 0, 0, 0, 0, false, false, false, false, 0, null );
+		}
+
+		Object.defineProperty( clickEvent, 'target', {
+			get: () => event.relatedTarget,
+		} );
+
+		deprecated( 'Popover onClickOutside prop', {
+			alternative: 'onFocusOutside',
+		} );
+
+		onClickOutside( clickEvent );
+	}
+
 	toggleAutoRefresh( isActive ) {
 		window.cancelAnimationFrame( this.rafHandle );
 
@@ -254,7 +297,6 @@ class Popover extends Component {
 			onClose,
 			children,
 			className,
-			onClickOutside = onClose,
 			noArrow,
 			// Disable reason: We generate the `...contentProps` rest as remainder
 			// of props which aren't explicitly handled by this component.
@@ -265,6 +307,8 @@ class Popover extends Component {
 			getAnchorRect,
 			expandOnMobile,
 			animate = true,
+			onClickOutside,
+			onFocusOutside,
 			/* eslint-enable no-unused-vars */
 			...contentProps
 		} = this.props;
@@ -308,7 +352,7 @@ class Popover extends Component {
 
 		/* eslint-disable jsx-a11y/no-static-element-interactions */
 		let content = (
-			<PopoverDetectOutside onClickOutside={ onClickOutside }>
+			<PopoverDetectOutside onFocusOutside={ this.onFocusOutside }>
 				<Animate
 					type={ animate && isReadyToAnimate ? 'appear' : null }
 					options={ { origin: animateYAxis + ' ' + animateXAxis } }

packages/components/src/popover/test/__snapshots__/index.js.snap

@@ -6,16 +6,18 @@ exports[`Popover #render() should pass additional props to portaled element 1`]
     tabindex="-1"
   >
     <div>
-      <div
-        class="components-popover is-bottom is-center components-animate__appear is-from-top"
-        role="tooltip"
-        style=""
-      >
+      <div>
         <div
-          class="components-popover__content"
-          tabindex="-1"
+          class="components-popover is-bottom is-center components-animate__appear is-from-top"
+          role="tooltip"
+          style=""
         >
-          Hello
+          <div
+            class="components-popover__content"
+            tabindex="-1"
+          >
+            Hello
+          </div>
         </div>
       </div>
     </div>
@@ -29,15 +31,17 @@ exports[`Popover #render() should render content 1`] = `
     tabindex="-1"
   >
     <div>
-      <div
-        class="components-popover is-bottom is-center components-animate__appear is-from-top"
-        style=""
-      >
+      <div>
         <div
-          class="components-popover__content"
-          tabindex="-1"
+          class="components-popover is-bottom is-center components-animate__appear is-from-top"
+          style=""
         >
-          Hello
+          <div
+            class="components-popover__content"
+            tabindex="-1"
+          >
+            Hello
+          </div>
         </div>
       </div>
     </div>