Try: useMergeRefs (#27768)

* Try: useMergeRefs * update lock file * Rebase fixes * Add docs * Clearer documentation * wip * wip * Add docs for unit tests * Convert new additions
WordPress · Feb 11, 2021 · 95551d9 · 95551d9
1 parent ac9e3cb
commit 95551d9
Show file tree

Hide file tree

Showing 21 changed files with 344 additions and 100 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/block-editor/package.json b/packages/block-editor/package.json
@@ -60,7 +60,6 @@
 		"lodash": "^4.17.19",
 		"memize": "^1.1.0",
 		"react-autosize-textarea": "^7.1.0",
-		"react-merge-refs": "^1.0.0",
 		"react-spring": "^8.0.19",
 		"redux-multi": "^0.1.12",
 		"rememo": "^3.0.0",

diff --git a/packages/block-editor/src/components/iframe/index.js b/packages/block-editor/src/components/iframe/index.js
@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import mergeRefs from 'react-merge-refs';
 import { compact, map } from 'lodash';
 import tinycolor from 'tinycolor2';
 
@@ -16,6 +15,7 @@ import {
 	forwardRef,
 } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
+import { useMergeRefs } from '@wordpress/compose';
 
 /**
  * Internal dependencies
@@ -211,7 +211,7 @@ function Iframe( { contentRef, editorStyles, children, head, ...props }, ref ) {
 	return (
 		<iframe
 			{ ...props }
-			ref={ useCallback( mergeRefs( [ ref, setRef ] ), [] ) }
+			ref={ useMergeRefs( [ ref, setRef ] ) }
 			tabIndex="0"
 			title={ __( 'Editor canvas' ) }
 			name="editor-canvas"

diff --git a/packages/components/package.json b/packages/components/package.json
@@ -59,7 +59,6 @@
 		"moment": "^2.22.1",
 		"re-resizable": "^6.4.0",
 		"react-dates": "^17.1.1",
-		"react-merge-refs": "^1.0.0",
 		"react-resize-aware": "^3.1.0",
 		"react-spring": "^8.0.20",
 		"react-use-gesture": "^9.0.0",

diff --git a/packages/components/src/modal/frame.js b/packages/components/src/modal/frame.js
@@ -2,7 +2,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import mergeRefs from 'react-merge-refs';
 
 /**
  * WordPress dependencies
@@ -14,6 +13,7 @@ import {
 	useFocusReturn,
 	useFocusOnMount,
 	useConstrainedTabbing,
+	useMergeRefs,
 } from '@wordpress/compose';
 
 /**
@@ -57,7 +57,7 @@ function ModalFrameContent( {
 			<div
 				className={ classnames( 'components-modal__frame', className ) }
 				style={ style }
-				ref={ mergeRefs( [
+				ref={ useMergeRefs( [
 					constrainedTabbingRef,
 					focusReturnRef,
 					focusOnMountRef,

diff --git a/packages/components/src/panel/body.js b/packages/components/src/panel/body.js
@@ -3,12 +3,11 @@
  */
 import classnames from 'classnames';
 import { noop } from 'lodash';
-import mergeRefs from 'react-merge-refs';
 
 /**
  * WordPress dependencies
  */
-import { useReducedMotion } from '@wordpress/compose';
+import { useReducedMotion, useMergeRefs } from '@wordpress/compose';
 import { forwardRef, useRef } from '@wordpress/element';
 import { chevronUp, chevronDown } from '@wordpress/icons';
 
@@ -77,7 +76,7 @@ export function PanelBody(
 	} );
 
 	return (
-		<div className={ classes } ref={ mergeRefs( [ nodeRef, ref ] ) }>
+		<div className={ classes } ref={ useMergeRefs( [ nodeRef, ref ] ) }>
 			<PanelBodyTitle
 				icon={ icon }
 				isOpened={ isOpened }

diff --git a/packages/components/src/popover/index.js b/packages/components/src/popover/index.js
@@ -2,17 +2,11 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import mergeRefs from 'react-merge-refs';
 
 /**
  * WordPress dependencies
  */
-import {
-	useRef,
-	useState,
-	useLayoutEffect,
-	useCallback,
-} from '@wordpress/element';
+import { useRef, useState, useLayoutEffect } from '@wordpress/element';
 import { getRectangleFromRange } from '@wordpress/dom';
 import { ESCAPE } from '@wordpress/keycodes';
 import deprecated from '@wordpress/deprecated';
@@ -23,6 +17,7 @@ import {
 	__experimentalUseFocusOutside as useFocusOutside,
 	useConstrainedTabbing,
 	useFocusReturn,
+	useMergeRefs,
 } from '@wordpress/compose';
 import { close } from '@wordpress/icons';
 
@@ -492,13 +487,12 @@ const Popover = ( {
 	const focusReturnRef = useFocusReturn();
 	const focusOnMountRef = useFocusOnMount( focusOnMount );
 	const focusOutsideProps = useFocusOutside( handleOnFocusOutside );
-	const allRefs = [
+	const mergedRefs = useMergeRefs( [
 		containerRef,
 		focusOnMount ? constrainedTabbingRef : null,
 		focusOnMount ? focusReturnRef : null,
 		focusOnMount ? focusOnMountRef : null,
-	];
-	const mergedRefs = useCallback( mergeRefs( allRefs ), allRefs );
+	] );
 
 	// Event handlers
 	const maybeClose = ( event ) => {

diff --git a/packages/compose/README.md b/packages/compose/README.md
@@ -282,6 +282,24 @@ _Returns_
 
 -   `boolean`: return value of the media query.
 
+<a name="useMergeRefs" href="#useMergeRefs">#</a> **useMergeRefs**
+
+Merges refs into one ref callback. Ensures the merged ref callbacks are only
+called when it changes (as a result of a `useCallback` dependency update) or
+when the ref value changes. If you don't wish a ref callback to be called on
+every render, wrap it with `useCallback( ref, [] )`.
+Dependencies can be added, but when a dependency changes, the old ref
+callback will be called with `null` and the new ref callback will be called
+with the same node.
+
+_Parameters_
+
+-   _refs_ `Array<(RefObject|RefCallback)>`: The refs to be merged.
+
+_Returns_
+
+-   `RefCallback`: The merged ref callback.
+
 <a name="usePrevious" href="#usePrevious">#</a> **usePrevious**
 
 Use something's value from the previous render.

diff --git a/packages/compose/package.json b/packages/compose/package.json
@@ -36,7 +36,6 @@
 		"lodash": "^4.17.19",
 		"memize": "^1.1.0",
 		"mousetrap": "^1.6.5",
-		"react-merge-refs": "^1.0.0",
 		"react-resize-aware": "^3.1.0",
 		"use-memo-one": "^1.1.1"
 	},

diff --git a/packages/compose/src/hooks/use-callback-ref/index.js b/packages/compose/src/hooks/use-callback-ref/index.js
diff --git a/packages/compose/src/hooks/use-constrained-tabbing/index.js b/packages/compose/src/hooks/use-constrained-tabbing/index.js
@@ -3,11 +3,7 @@
  */
 import { TAB } from '@wordpress/keycodes';
 import { focus } from '@wordpress/dom';
-
-/**
- * Internal dependencies
- */
-import useCallbackRef from '../use-callback-ref';
+import { useCallback } from '@wordpress/element';
 
 /**
  * In Dialogs/modals, the tabbing must be constrained to the content of
@@ -31,7 +27,7 @@ import useCallbackRef from '../use-callback-ref';
  * ```
  */
 function useConstrainedTabbing() {
-	const ref = useCallbackRef( ( node ) => {
+	const ref = useCallback( ( node ) => {
 		if ( ! node ) {
 			return;
 		}

diff --git a/packages/compose/src/hooks/use-dialog/index.js b/packages/compose/src/hooks/use-dialog/index.js
@@ -1,12 +1,7 @@
-/**
- * External dependencies
- */
-import mergeRefs from 'react-merge-refs';
-
 /**
  * WordPress dependencies
  */
-import { useRef, useEffect } from '@wordpress/element';
+import { useRef, useEffect, useCallback } from '@wordpress/element';
 import { ESCAPE } from '@wordpress/keycodes';
 
 /**
@@ -16,7 +11,7 @@ import useConstrainedTabbing from '../use-constrained-tabbing';
 import useFocusOnMount from '../use-focus-on-mount';
 import useFocusReturn from '../use-focus-return';
 import useFocusOutside from '../use-focus-outside';
-import useCallbackRef from '../use-callback-ref';
+import useMergeRefs from '../use-merge-refs';
 
 /**
  * Returns a ref and props to apply to a dialog wrapper to enable the following behaviors:
@@ -36,7 +31,7 @@ function useDialog( options ) {
 	const focusOnMountRef = useFocusOnMount();
 	const focusReturnRef = useFocusReturn();
 	const focusOutsideProps = useFocusOutside( options.onClose );
-	const closeOnEscapeRef = useCallbackRef( ( node ) => {
+	const closeOnEscapeRef = useCallback( ( node ) => {
 		if ( ! node ) {
 			return;
 		}
@@ -51,7 +46,7 @@ function useDialog( options ) {
 	}, [] );
 
 	return [
-		mergeRefs( [
+		useMergeRefs( [
 			constrainedTabbingRef,
 			focusReturnRef,
 			focusOnMountRef,

diff --git a/packages/compose/src/hooks/use-focus-on-mount/index.js b/packages/compose/src/hooks/use-focus-on-mount/index.js
@@ -1,14 +1,9 @@
 /**
  * WordPress dependencies
  */
-import { useRef, useEffect } from '@wordpress/element';
+import { useRef, useEffect, useCallback } from '@wordpress/element';
 import { focus } from '@wordpress/dom';
 
-/**
- * Internal dependencies
- */
-import useCallbackRef from '../use-callback-ref';
-
 /**
  * Hook used to focus the first tabbable element on mount.
  *
@@ -36,7 +31,7 @@ export default function useFocusOnMount( focusOnMount = 'firstElement' ) {
 		focusOnMountRef.current = focusOnMount;
 	}, [ focusOnMount ] );
 
-	return useCallbackRef( ( node ) => {
+	return useCallback( ( node ) => {
 		if ( ! node || focusOnMountRef.current === false ) {
 			return;
 		}

diff --git a/packages/compose/src/hooks/use-focus-return/index.js b/packages/compose/src/hooks/use-focus-return/index.js
@@ -1,12 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { useRef, useEffect } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
-import useCallbackRef from '../use-callback-ref';
+import { useRef, useEffect, useCallback } from '@wordpress/element';
 
 /**
  * When opening modals/sidebars/dialogs, the focus
@@ -40,7 +35,7 @@ function useFocusReturn( onFocusReturn ) {
 		onFocusReturnRef.current = onFocusReturn;
 	}, [ onFocusReturn ] );
 
-	return useCallbackRef( ( node ) => {
+	return useCallback( ( node ) => {
 		if ( node ) {
 			// Set ref to be used when unmounting.
 			ref.current = node;