@wordpress/compose 5.5.0 → 5.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/compose",
-	"version": "5.5.0",
+	"version": "5.8.0",
 	"description": "WordPress higher-order components (HOCs).",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -32,16 +32,15 @@
 		"@babel/runtime": "^7.16.0",
 		"@types/lodash": "^4.14.172",
 		"@types/mousetrap": "^1.6.8",
-		"@wordpress/deprecated": "^3.7.0",
-		"@wordpress/dom": "^3.7.0",
-		"@wordpress/element": "^4.5.0",
-		"@wordpress/is-shallow-equal": "^4.7.0",
-		"@wordpress/keycodes": "^3.7.0",
-		"@wordpress/priority-queue": "^2.7.0",
+		"@wordpress/deprecated": "^3.10.0",
+		"@wordpress/dom": "^3.10.0",
+		"@wordpress/element": "^4.8.0",
+		"@wordpress/is-shallow-equal": "^4.10.0",
+		"@wordpress/keycodes": "^3.10.0",
+		"@wordpress/priority-queue": "^2.10.0",
 		"clipboard": "^2.0.8",
 		"lodash": "^4.17.21",
 		"mousetrap": "^1.6.5",
-		"react-resize-aware": "^3.1.0",
 		"use-memo-one": "^1.1.1"
 	},
 	"peerDependencies": {
@@ -50,5 +49,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "1ba52312b56db563df2d8d4fba5b00613fb46d8c"
+	"gitHead": "a3e0b62091e8a8bdf5e2518e42d60d7098af48cc"
 }

package/src/hooks/use-copy-to-clipboard/index.js

@@ -35,7 +35,7 @@ function useUpdatedRef( value ) {
  * @return {import('react').Ref<TElementType>} A ref to assign to the target element.
  */
 export default function useCopyToClipboard( text, onSuccess ) {
-	// Store the dependencies as refs and continuesly update them so they're
+	// Store the dependencies as refs and continuously update them so they're
 	// fresh when the callback is called.
 	const textRef = useUpdatedRef( text );
 	const onSuccessRef = useUpdatedRef( onSuccess );

package/src/hooks/use-disabled/index.js

@@ -6,9 +6,13 @@ import { includes, debounce } from 'lodash';
 /**
  * WordPress dependencies
  */
-import { useCallback, useLayoutEffect, useRef } from '@wordpress/element';
 import { focus } from '@wordpress/dom';
 
+/**
+ * Internal dependencies
+ */
+import useRefEffect from '../use-ref-effect';
+
 /**
  * Names of control nodes which qualify for disabled behavior.
  *
@@ -33,11 +37,13 @@ const DISABLED_ELIGIBLE_NODE_NAMES = [
  * (input fields, links, buttons, etc.) need to be disabled. This hook adds the
  * behavior to disable nested DOM elements to the returned ref.
  *
- * @return {import('react').RefObject<HTMLElement>} Element Ref.
+ * @param {Object}   config            Configuration object.
+ * @param {boolean=} config.isDisabled Whether the element should be disabled.
+ * @return {import('react').RefCallback<HTMLElement>} Element Ref.
  *
  * @example
  * ```js
- * import { __experimentalUseDisabled as useDisabled } from '@wordpress/compose';
+ * import { useDisabled } from '@wordpress/compose';
  * const DisabledExample = () => {
  * 	const disabledRef = useDisabled();
  *	return (
@@ -49,65 +55,149 @@ const DISABLED_ELIGIBLE_NODE_NAMES = [
  * };
  * ```
  */
-export default function useDisabled() {
-	/** @type {import('react').RefObject<HTMLElement>} */
-	const node = useRef( null );
+export default function useDisabled( {
+	isDisabled: isDisabledProp = false,
+} = {} ) {
+	return useRefEffect(
+		( node ) => {
+			if ( isDisabledProp ) {
+				return;
+			}
 
-	const disable = () => {
-		if ( ! node.current ) {
-			return;
-		}
+			/** A variable keeping track of the previous updates in order to restore them. */
+			/** @type {Function[]} */
+			const updates = [];
 
-		focus.focusable.find( node.current ).forEach( ( focusable ) => {
-			if (
-				includes( DISABLED_ELIGIBLE_NODE_NAMES, focusable.nodeName )
-			) {
-				focusable.setAttribute( 'disabled', '' );
-			}
+			const disable = () => {
+				if ( node.style.getPropertyValue( 'user-select' ) !== 'none' ) {
+					const previousValue = node.style.getPropertyValue(
+						'user-select'
+					);
+					node.style.setProperty( 'user-select', 'none' );
+					node.style.setProperty( '-webkit-user-select', 'none' );
+					updates.push( () => {
+						if ( ! node.isConnected ) {
+							return;
+						}
+						node.style.setProperty( 'user-select', previousValue );
+						node.style.setProperty(
+							'-webkit-user-select',
+							previousValue
+						);
+					} );
+				}
 
-			if ( focusable.nodeName === 'A' ) {
-				focusable.setAttribute( 'tabindex', '-1' );
-			}
+				focus.focusable.find( node ).forEach( ( focusable ) => {
+					if (
+						includes(
+							DISABLED_ELIGIBLE_NODE_NAMES,
+							focusable.nodeName
+						) &&
+						// @ts-ignore
+						! focusable.disabled
+					) {
+						focusable.setAttribute( 'disabled', '' );
+						updates.push( () => {
+							if ( ! focusable.isConnected ) {
+								return;
+							}
+							// @ts-ignore
+							focusable.disabled = false;
+						} );
+					}
 
-			const tabIndex = focusable.getAttribute( 'tabindex' );
-			if ( tabIndex !== null && tabIndex !== '-1' ) {
-				focusable.removeAttribute( 'tabindex' );
-			}
+					if (
+						focusable.nodeName === 'A' &&
+						focusable.getAttribute( 'tabindex' ) !== '-1'
+					) {
+						const previousValue = focusable.getAttribute(
+							'tabindex'
+						);
+						focusable.setAttribute( 'tabindex', '-1' );
+						updates.push( () => {
+							if ( ! focusable.isConnected ) {
+								return;
+							}
+							if ( ! previousValue ) {
+								focusable.removeAttribute( 'tabindex' );
+							} else {
+								focusable.setAttribute(
+									'tabindex',
+									previousValue
+								);
+							}
+						} );
+					}
 
-			if ( focusable.hasAttribute( 'contenteditable' ) ) {
-				focusable.setAttribute( 'contenteditable', 'false' );
-			}
-		} );
-	};
+					const tabIndex = focusable.getAttribute( 'tabindex' );
+					if ( tabIndex !== null && tabIndex !== '-1' ) {
+						focusable.removeAttribute( 'tabindex' );
+						updates.push( () => {
+							if ( ! focusable.isConnected ) {
+								return;
+							}
+							focusable.setAttribute( 'tabindex', tabIndex );
+						} );
+					}
 
-	// Debounce re-disable since disabling process itself will incur
-	// additional mutations which should be ignored.
-	const debouncedDisable = useCallback(
-		debounce( disable, undefined, { leading: true } ),
-		[]
-	);
+					if (
+						focusable.hasAttribute( 'contenteditable' ) &&
+						focusable.getAttribute( 'contenteditable' ) !== 'false'
+					) {
+						focusable.setAttribute( 'contenteditable', 'false' );
+						updates.push( () => {
+							if ( ! focusable.isConnected ) {
+								return;
+							}
+							focusable.setAttribute( 'contenteditable', 'true' );
+						} );
+					}
 
-	useLayoutEffect( () => {
-		disable();
+					if (
+						node.ownerDocument.defaultView?.HTMLElement &&
+						focusable instanceof
+							node.ownerDocument.defaultView.HTMLElement
+					) {
+						const previousValue = focusable.style.getPropertyValue(
+							'pointer-events'
+						);
+						focusable.style.setProperty( 'pointer-events', 'none' );
+						updates.push( () => {
+							if ( ! focusable.isConnected ) {
+								return;
+							}
+							focusable.style.setProperty(
+								'pointer-events',
+								previousValue
+							);
+						} );
+					}
+				} );
+			};
+
+			// Debounce re-disable since disabling process itself will incur
+			// additional mutations which should be ignored.
+			const debouncedDisable = debounce( disable, undefined, {
+				leading: true,
+			} );
+			disable();
 
-		/** @type {MutationObserver | undefined} */
-		let observer;
-		if ( node.current ) {
-			observer = new window.MutationObserver( debouncedDisable );
-			observer.observe( node.current, {
+			/** @type {MutationObserver | undefined} */
+			const observer = new window.MutationObserver( debouncedDisable );
+			observer.observe( node, {
 				childList: true,
 				attributes: true,
 				subtree: true,
 			} );
-		}
 
-		return () => {
-			if ( observer ) {
-				observer.disconnect();
-			}
-			debouncedDisable.cancel();
-		};
-	}, [] );
-
-	return node;
+			return () => {
+				if ( observer ) {
+					observer.disconnect();
+				}
+				debouncedDisable.cancel();
+				updates.forEach( ( update ) => update() );
+			};
+		},
+		[ isDisabledProp ]
+	);
 }

package/src/hooks/use-focus-on-mount/index.js

@@ -50,6 +50,11 @@ export default function useFocusOnMount( focusOnMount = 'firstElement' ) {
 			}
 		}
 
-		target.focus();
+		target.focus( {
+			// When focusing newly mounted dialogs,
+			// the position of the popover is often not right on the first render
+			// This prevents the layout shifts when focusing the dialogs.
+			preventScroll: true,
+		} );
 	}, [] );
 }

package/src/hooks/use-ref-effect/index.ts

@@ -28,10 +28,10 @@ import { useCallback, useRef } from '@wordpress/element';
  * @return Ref callback.
  */
 export default function useRefEffect< TElement = Node >(
-	callback: ( node: TElement ) => ( () => void ) | undefined,
+	callback: ( node: TElement ) => ( () => void ) | void,
 	dependencies: DependencyList
 ): RefCallback< TElement | null > {
-	const cleanup = useRef< ( () => void ) | undefined >();
+	const cleanup = useRef< ( () => void ) | void >();
 	return useCallback( ( node: TElement | null ) => {
 		if ( node ) {
 			cleanup.current = callback( node );

package/src/hooks/use-resize-observer/index.native.js

@@ -10,8 +10,6 @@ import { useState, useCallback } from '@wordpress/element';
 /**
  * Hook which allows to listen the resize event of any target element when it changes sizes.
  *
- * @return {[JSX.Element, { width: number, height: number } | null]} An array of {Element} `resizeListener` and {?Object} `sizes` with properties `width` and `height`
- *
  * @example
  *
  * ```js

package/src/hooks/use-resize-observer/index.tsx

@@ -0,0 +1,362 @@
+/**
+ * External dependencies
+ */
+import type { RefCallback, RefObject } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	useMemo,
+	useRef,
+	useCallback,
+	useEffect,
+	useState,
+} from '@wordpress/element';
+import type { WPElement } from '@wordpress/element';
+
+type SubscriberCleanup = () => void;
+type SubscriberResponse = SubscriberCleanup | void;
+
+// This of course could've been more streamlined with internal state instead of
+// refs, but then host hooks / components could not opt out of renders.
+// This could've been exported to its own module, but the current build doesn't
+// seem to work with module imports and I had no more time to spend on this...
+function useResolvedElement< T extends HTMLElement >(
+	subscriber: ( element: T ) => SubscriberResponse,
+	refOrElement?: T | RefObject< T > | null
+): RefCallback< T > {
+	const callbackRefElement = useRef< T | null >( null );
+	const lastReportRef = useRef< {
+		reporter: () => void;
+		element: T | null;
+	} | null >( null );
+	const cleanupRef = useRef< SubscriberResponse | null >();
+
+	const callSubscriber = useCallback( () => {
+		let element = null;
+		if ( callbackRefElement.current ) {
+			element = callbackRefElement.current;
+		} else if ( refOrElement ) {
+			if ( refOrElement instanceof HTMLElement ) {
+				element = refOrElement;
+			} else {
+				element = refOrElement.current;
+			}
+		}
+
+		if (
+			lastReportRef.current &&
+			lastReportRef.current.element === element &&
+			lastReportRef.current.reporter === callSubscriber
+		) {
+			return;
+		}
+
+		if ( cleanupRef.current ) {
+			cleanupRef.current();
+			// Making sure the cleanup is not called accidentally multiple times.
+			cleanupRef.current = null;
+		}
+		lastReportRef.current = {
+			reporter: callSubscriber,
+			element,
+		};
+
+		// Only calling the subscriber, if there's an actual element to report.
+		if ( element ) {
+			cleanupRef.current = subscriber( element );
+		}
+	}, [ refOrElement, subscriber ] );
+
+	// On each render, we check whether a ref changed, or if we got a new raw
+	// element.
+	useEffect( () => {
+		// With this we're *technically* supporting cases where ref objects' current value changes, but only if there's a
+		// render accompanying that change as well.
+		// To guarantee we always have the right element, one must use the ref callback provided instead, but we support
+		// RefObjects to make the hook API more convenient in certain cases.
+		callSubscriber();
+	}, [ callSubscriber ] );
+
+	return useCallback< RefCallback< T > >(
+		( element ) => {
+			callbackRefElement.current = element;
+			callSubscriber();
+		},
+		[ callSubscriber ]
+	);
+}
+
+type ObservedSize = {
+	width: number | undefined;
+	height: number | undefined;
+};
+
+type ResizeHandler = ( size: ObservedSize ) => void;
+
+type HookResponse< T extends HTMLElement > = {
+	ref: RefCallback< T >;
+} & ObservedSize;
+
+// Declaring my own type here instead of using the one provided by TS (available since 4.2.2), because this way I'm not
+// forcing consumers to use a specific TS version.
+type ResizeObserverBoxOptions =
+	| 'border-box'
+	| 'content-box'
+	| 'device-pixel-content-box';
+
+declare global {
+	interface ResizeObserverEntry {
+		readonly devicePixelContentBoxSize: ReadonlyArray< ResizeObserverSize >;
+	}
+}
+
+// We're only using the first element of the size sequences, until future versions of the spec solidify on how
+// exactly it'll be used for fragments in multi-column scenarios:
+// From the spec:
+// > The box size properties are exposed as FrozenArray in order to support elements that have multiple fragments,
+// > which occur in multi-column scenarios. However the current definitions of content rect and border box do not
+// > mention how those boxes are affected by multi-column layout. In this spec, there will only be a single
+// > ResizeObserverSize returned in the FrozenArray, which will correspond to the dimensions of the first column.
+// > A future version of this spec will extend the returned FrozenArray to contain the per-fragment size information.
+// (https://drafts.csswg.org/resize-observer/#resize-observer-entry-interface)
+//
+// Also, testing these new box options revealed that in both Chrome and FF everything is returned in the callback,
+// regardless of the "box" option.
+// The spec states the following on this:
+// > This does not have any impact on which box dimensions are returned to the defined callback when the event
+// > is fired, it solely defines which box the author wishes to observe layout changes on.
+// (https://drafts.csswg.org/resize-observer/#resize-observer-interface)
+// I'm not exactly clear on what this means, especially when you consider a later section stating the following:
+// > This section is non-normative. An author may desire to observe more than one CSS box.
+// > In this case, author will need to use multiple ResizeObservers.
+// (https://drafts.csswg.org/resize-observer/#resize-observer-interface)
+// Which is clearly not how current browser implementations behave, and seems to contradict the previous quote.
+// For this reason I decided to only return the requested size,
+// even though it seems we have access to results for all box types.
+// This also means that we get to keep the current api, being able to return a simple { width, height } pair,
+// regardless of box option.
+const extractSize = (
+	entry: ResizeObserverEntry,
+	boxProp: 'borderBoxSize' | 'contentBoxSize' | 'devicePixelContentBoxSize',
+	sizeType: keyof ResizeObserverSize
+): number | undefined => {
+	if ( ! entry[ boxProp ] ) {
+		if ( boxProp === 'contentBoxSize' ) {
+			// The dimensions in `contentBoxSize` and `contentRect` are equivalent according to the spec.
+			// See the 6th step in the description for the RO algorithm:
+			// https://drafts.csswg.org/resize-observer/#create-and-populate-resizeobserverentry-h
+			// > Set this.contentRect to logical this.contentBoxSize given target and observedBox of "content-box".
+			// In real browser implementations of course these objects differ, but the width/height values should be equivalent.
+			return entry.contentRect[
+				sizeType === 'inlineSize' ? 'width' : 'height'
+			];
+		}
+
+		return undefined;
+	}
+
+	// A couple bytes smaller than calling Array.isArray() and just as effective here.
+	return entry[ boxProp ][ 0 ]
+		? entry[ boxProp ][ 0 ][ sizeType ]
+		: // TS complains about this, because the RO entry type follows the spec and does not reflect Firefox's current
+		  // behaviour of returning objects instead of arrays for `borderBoxSize` and `contentBoxSize`.
+		  // @ts-ignore
+		  entry[ boxProp ][ sizeType ];
+};
+
+type RoundingFunction = ( n: number ) => number;
+
+function useResizeObserver< T extends HTMLElement >(
+	opts: {
+		ref?: RefObject< T > | T | null | undefined;
+		onResize?: ResizeHandler;
+		box?: ResizeObserverBoxOptions;
+		round?: RoundingFunction;
+	} = {}
+): HookResponse< T > {
+	// Saving the callback as a ref. With this, I don't need to put onResize in the
+	// effect dep array, and just passing in an anonymous function without memoising
+	// will not reinstantiate the hook's ResizeObserver.
+	const onResize = opts.onResize;
+	const onResizeRef = useRef< ResizeHandler | undefined >( undefined );
+	onResizeRef.current = onResize;
+	const round = opts.round || Math.round;
+
+	// Using a single instance throughout the hook's lifetime
+	const resizeObserverRef = useRef< {
+		box?: ResizeObserverBoxOptions;
+		round?: RoundingFunction;
+		instance: ResizeObserver;
+	} >();
+
+	const [ size, setSize ] = useState< {
+		width?: number;
+		height?: number;
+	} >( {
+		width: undefined,
+		height: undefined,
+	} );
+
+	// In certain edge cases the RO might want to report a size change just after
+	// the component unmounted.
+	const didUnmount = useRef( false );
+	useEffect( () => {
+		return () => {
+			didUnmount.current = true;
+		};
+	}, [] );
+
+	// Using a ref to track the previous width / height to avoid unnecessary renders.
+	const previous: {
+		current: {
+			width?: number;
+			height?: number;
+		};
+	} = useRef( {
+		width: undefined,
+		height: undefined,
+	} );
+
+	// This block is kinda like a useEffect, only it's called whenever a new
+	// element could be resolved based on the ref option. It also has a cleanup
+	// function.
+	const refCallback = useResolvedElement< T >(
+		useCallback(
+			( element ) => {
+				// We only use a single Resize Observer instance, and we're instantiating it on demand, only once there's something to observe.
+				// This instance is also recreated when the `box` option changes, so that a new observation is fired if there was a previously observed element with a different box option.
+				if (
+					! resizeObserverRef.current ||
+					resizeObserverRef.current.box !== opts.box ||
+					resizeObserverRef.current.round !== round
+				) {
+					resizeObserverRef.current = {
+						box: opts.box,
+						round,
+						instance: new ResizeObserver( ( entries ) => {
+							const entry = entries[ 0 ];
+
+							let boxProp:
+								| 'borderBoxSize'
+								| 'contentBoxSize'
+								| 'devicePixelContentBoxSize' = 'borderBoxSize';
+							if ( opts.box === 'border-box' ) {
+								boxProp = 'borderBoxSize';
+							} else {
+								boxProp =
+									opts.box === 'device-pixel-content-box'
+										? 'devicePixelContentBoxSize'
+										: 'contentBoxSize';
+							}
+
+							const reportedWidth = extractSize(
+								entry,
+								boxProp,
+								'inlineSize'
+							);
+							const reportedHeight = extractSize(
+								entry,
+								boxProp,
+								'blockSize'
+							);
+
+							const newWidth = reportedWidth
+								? round( reportedWidth )
+								: undefined;
+							const newHeight = reportedHeight
+								? round( reportedHeight )
+								: undefined;
+
+							if (
+								previous.current.width !== newWidth ||
+								previous.current.height !== newHeight
+							) {
+								const newSize = {
+									width: newWidth,
+									height: newHeight,
+								};
+								previous.current.width = newWidth;
+								previous.current.height = newHeight;
+								if ( onResizeRef.current ) {
+									onResizeRef.current( newSize );
+								} else if ( ! didUnmount.current ) {
+									setSize( newSize );
+								}
+							}
+						} ),
+					};
+				}
+
+				resizeObserverRef.current.instance.observe( element, {
+					box: opts.box,
+				} );
+
+				return () => {
+					if ( resizeObserverRef.current ) {
+						resizeObserverRef.current.instance.unobserve( element );
+					}
+				};
+			},
+			[ opts.box, round ]
+		),
+		opts.ref
+	);
+
+	return useMemo(
+		() => ( {
+			ref: refCallback,
+			width: size.width,
+			height: size.height,
+		} ),
+		[ refCallback, size ? size.width : null, size ? size.height : null ]
+	);
+}
+
+/**
+ * Hook which allows to listen the resize event of any target element when it changes sizes.
+ * _Note: `useResizeObserver` will report `null` until after first render.
+ *
+ * @example
+ *
+ * ```js
+ * const App = () => {
+ * 	const [ resizeListener, sizes ] = useResizeObserver();
+ *
+ * 	return (
+ * 		<div>
+ * 			{ resizeListener }
+ * 			Your content here
+ * 		</div>
+ * 	);
+ * };
+ * ```
+ */
+export default function useResizeAware(): [
+	WPElement,
+	{ width: number | null; height: number | null }
+] {
+	const { ref, width, height } = useResizeObserver();
+	const sizes = useMemo( () => {
+		return { width: width ?? null, height: height ?? null };
+	}, [ width, height ] );
+	const resizeListener = (
+		<div
+			style={ {
+				position: 'absolute',
+				top: 0,
+				left: 0,
+				right: 0,
+				bottom: 0,
+				pointerEvents: 'none',
+				opacity: 0,
+				overflow: 'hidden',
+				zIndex: -1,
+			} }
+			aria-hidden="true"
+			ref={ ref }
+		/>
+	);
+	return [ resizeListener, sizes ];
+}

package/src/index.js

@@ -17,7 +17,7 @@ export { default as useConstrainedTabbing } from './hooks/use-constrained-tabbin
 export { default as useCopyOnClick } from './hooks/use-copy-on-click';
 export { default as useCopyToClipboard } from './hooks/use-copy-to-clipboard';
 export { default as __experimentalUseDialog } from './hooks/use-dialog';
-export { default as __experimentalUseDisabled } from './hooks/use-disabled';
+export { default as useDisabled } from './hooks/use-disabled';
 export { default as __experimentalUseDragging } from './hooks/use-dragging';
 export { default as useFocusOnMount } from './hooks/use-focus-on-mount';
 export { default as __experimentalUseFocusOutside } from './hooks/use-focus-outside';