@wordpress/compose 8.1.0 → 8.1.1

package/src/hooks/use-merge-refs/test/index.js

@@ -345,3 +345,291 @@ describe( 'useMergeRefs', () => {
 		] );
 	} );
 } );
+
+describe( 'useMergeRefs with cleanup-returning ref callbacks', () => {
+	// Setup
+	// =====
+	//
+	// Same structure as the suite above, but the ref callbacks return a
+	// cleanup function. React 19 (and `useMergeRefs`) invokes the cleanup at
+	// teardown instead of calling the callback with `null`. The cleanup pushes
+	// the string `'cleanup'` into the same history array, so each call site's
+	// full lifecycle is captured as `[ node, 'cleanup', newNode, 'cleanup' ]`.
+	// The strict invariant is that `null` never appears in the history of a
+	// cleanup-returning ref.
+
+	function renderCallback( args ) {
+		renderCallback.history.push( args );
+	}
+
+	renderCallback.history = [];
+
+	function MergedRefs( {
+		count,
+		tagName: TagName = 'ul',
+		disable1,
+		disable2,
+	} ) {
+		function refCallback1( value ) {
+			refCallback1.history.push( value );
+			return () => {
+				refCallback1.history.push( 'cleanup' );
+			};
+		}
+
+		refCallback1.history = [];
+
+		function refCallback2( value ) {
+			refCallback2.history.push( value );
+			return () => {
+				refCallback2.history.push( 'cleanup' );
+			};
+		}
+
+		refCallback2.history = [];
+
+		renderCallback( [ refCallback1.history, refCallback2.history ] );
+
+		const ref1 = useCallback( refCallback1, [] );
+		const ref2 = useCallback( refCallback2, [ count ] );
+		const mergedRefs = useMergeRefs( [
+			! disable1 && ref1,
+			! disable2 && ref2,
+		] );
+
+		return <TagName ref={ mergedRefs } />;
+	}
+
+	afterEach( () => {
+		renderCallback.history = [];
+	} );
+
+	it( 'should invoke cleanup on unmount instead of calling ref with null', () => {
+		const { unmount } = render( <MergedRefs /> );
+
+		const originalElement = screen.getByRole( 'list' );
+
+		expect( renderCallback.history ).toEqual( [
+			[ [ originalElement ], [ originalElement ] ],
+		] );
+
+		unmount();
+
+		// Cleanups run; refs are NOT called with `null`.
+		expect( renderCallback.history ).toEqual( [
+			[
+				[ originalElement, 'cleanup' ],
+				[ originalElement, 'cleanup' ],
+			],
+		] );
+	} );
+
+	it( 'should invoke cleanup on node change instead of calling ref with null', () => {
+		const { rerender, unmount } = render( <MergedRefs /> );
+
+		const originalElement = screen.getByRole( 'list' );
+
+		rerender( <MergedRefs tagName="button" /> );
+
+		const newElement = screen.getByRole( 'button' );
+
+		// Node change triggers the outer callback first with `null` (which
+		// runs the cleanups) and then with the new node (which sets up new
+		// cleanups).
+		expect( renderCallback.history ).toEqual( [
+			[
+				[ originalElement, 'cleanup', newElement ],
+				[ originalElement, 'cleanup', newElement ],
+			],
+			[ [], [] ],
+		] );
+
+		unmount();
+
+		expect( renderCallback.history ).toEqual( [
+			[
+				[ originalElement, 'cleanup', newElement, 'cleanup' ],
+				[ originalElement, 'cleanup', newElement, 'cleanup' ],
+			],
+			[ [], [] ],
+		] );
+	} );
+
+	it( 'should invoke cleanup on dependency change instead of calling ref with null', () => {
+		const { rerender, unmount } = render( <MergedRefs count={ 1 } /> );
+
+		const originalElement = screen.getByRole( 'list' );
+
+		expect( renderCallback.history ).toEqual( [
+			[ [ originalElement ], [ originalElement ] ],
+		] );
+
+		rerender( <MergedRefs count={ 2 } /> );
+
+		// Only ref2's deps changed. Its previous cleanup runs and the new ref
+		// callback is called with the still-attached node. ref1 is untouched.
+		expect( renderCallback.history ).toEqual( [
+			[ [ originalElement ], [ originalElement, 'cleanup' ] ],
+			[ [], [ originalElement ] ],
+		] );
+
+		unmount();
+
+		expect( renderCallback.history ).toEqual( [
+			[
+				[ originalElement, 'cleanup' ],
+				[ originalElement, 'cleanup' ],
+			],
+			[ [], [ originalElement, 'cleanup' ] ],
+		] );
+	} );
+
+	it( 'should invoke cleanup on simultaneous node and dependency change', () => {
+		const { rerender, unmount } = render( <MergedRefs count={ 1 } /> );
+
+		const originalElement = screen.getByRole( 'list' );
+
+		rerender( <MergedRefs count={ 2 } tagName="button" /> );
+
+		const newElement = screen.getByRole( 'button' );
+
+		// Outer callback's null/new-node pair runs both cleanups and sets
+		// up the new ones (ref1 reused, ref2 has a new identity).
+		expect( renderCallback.history ).toEqual( [
+			[
+				[ originalElement, 'cleanup', newElement ],
+				[ originalElement, 'cleanup' ],
+			],
+			[ [], [ newElement ] ],
+		] );
+
+		unmount();
+
+		expect( renderCallback.history ).toEqual( [
+			[
+				[ originalElement, 'cleanup', newElement, 'cleanup' ],
+				[ originalElement, 'cleanup' ],
+			],
+			[ [], [ newElement, 'cleanup' ] ],
+		] );
+	} );
+
+	it( 'should invoke cleanup when a ref becomes disabled', () => {
+		const { rerender, unmount } = render( <MergedRefs /> );
+
+		const originalElement = screen.getByRole( 'list' );
+
+		rerender( <MergedRefs disable1 /> );
+
+		// ref1 is disabled: its stored cleanup must fire. ref2 is unchanged.
+		expect( renderCallback.history ).toEqual( [
+			[ [ originalElement, 'cleanup' ], [ originalElement ] ],
+			[ [], [] ],
+		] );
+
+		unmount();
+
+		expect( renderCallback.history ).toEqual( [
+			[
+				[ originalElement, 'cleanup' ],
+				[ originalElement, 'cleanup' ],
+			],
+			[ [], [] ],
+		] );
+	} );
+
+	it( 'should support mixing a cleanup-returning ref with a void-returning ref', () => {
+		function MergedRefsMixed() {
+			function refCleanup( value ) {
+				refCleanup.history.push( value );
+				return () => {
+					refCleanup.history.push( 'cleanup' );
+				};
+			}
+
+			refCleanup.history = [];
+
+			function refVoid( value ) {
+				refVoid.history.push( value );
+			}
+
+			refVoid.history = [];
+
+			renderCallback( [ refCleanup.history, refVoid.history ] );
+
+			const r1 = useCallback( refCleanup, [] );
+			const r2 = useCallback( refVoid, [] );
+			const merged = useMergeRefs( [ r1, r2 ] );
+
+			return <ul ref={ merged } />;
+		}
+
+		const { unmount } = render( <MergedRefsMixed /> );
+
+		const el = screen.getByRole( 'list' );
+
+		expect( renderCallback.history ).toEqual( [ [ [ el ], [ el ] ] ] );
+
+		unmount();
+
+		// Cleanup ref sees the cleanup; void ref still sees null. Independent.
+		expect( renderCallback.history ).toEqual( [
+			[
+				[ el, 'cleanup' ],
+				[ el, null ],
+			],
+		] );
+	} );
+
+	it( 'should support mixing an object ref with a cleanup-returning ref', () => {
+		const objectRef = { current: null };
+
+		function MergedRefsMixed( { tagName: TagName = 'ul' } ) {
+			function refCleanup( value ) {
+				refCleanup.history.push( value );
+				return () => {
+					refCleanup.history.push( 'cleanup' );
+				};
+			}
+
+			refCleanup.history = [];
+
+			renderCallback( [ refCleanup.history ] );
+
+			const r = useCallback( refCleanup, [] );
+			const merged = useMergeRefs( [ objectRef, r ] );
+
+			return <TagName ref={ merged } />;
+		}
+
+		const { rerender, unmount } = render( <MergedRefsMixed /> );
+
+		const originalElement = screen.getByRole( 'list' );
+
+		// Object ref's .current is set; cleanup ref is called with the node.
+		expect( objectRef.current ).toBe( originalElement );
+		expect( renderCallback.history ).toEqual( [ [ [ originalElement ] ] ] );
+
+		rerender( <MergedRefsMixed tagName="button" /> );
+
+		const newElement = screen.getByRole( 'button' );
+
+		// Node change: object ref retargets, callback ref's cleanup fires
+		// and the callback is re-invoked with the new node.
+		expect( objectRef.current ).toBe( newElement );
+		expect( renderCallback.history ).toEqual( [
+			[ [ originalElement, 'cleanup', newElement ] ],
+			[ [] ],
+		] );
+
+		unmount();
+
+		// Object ref nulled via the fallback assignRef path; callback ref
+		// sees its cleanup, never null.
+		expect( objectRef.current ).toBe( null );
+		expect( renderCallback.history ).toEqual( [
+			[ [ originalElement, 'cleanup', newElement, 'cleanup' ] ],
+			[ [] ],
+		] );
+	} );
+} );

package/src/hooks/use-viewport-match/index.js

@@ -64,7 +64,7 @@ ViewportMatchWidthContext.displayName = 'ViewportMatchWidthContext';
  *
  * @param {WPBreakpoint}       breakpoint      Breakpoint size name.
  * @param {WPViewportOperator} [operator=">="] Viewport operator.
- * @param {Window}             [view=window]   Window instance in which to perform viewport matching.
+ * @param {Window|undefined}   [view=window]   Window instance in which to perform viewport matching.
  *
  * @example
  *
@@ -75,7 +75,13 @@ ViewportMatchWidthContext.displayName = 'ViewportMatchWidthContext';
  *
  * @return {boolean} Whether viewport matches query.
  */
-const useViewportMatch = ( breakpoint, operator = '>=', view = window ) => {
+const useViewportMatch = (
+	breakpoint,
+	operator = '>=',
+	// Resolve the default lazily so SSR (where `window` is undeclared) does not
+	// throw a ReferenceError when this default expression is evaluated.
+	view = typeof window !== 'undefined' ? window : undefined
+) => {
 	const simulatedWidth = useContext( ViewportMatchWidthContext );
 	const mediaQuery =
 		! simulatedWidth &&

package/src/higher-order/with-network-connectivity/README.md

@@ -1,20 +0,0 @@
-# withNetworkConnectivity
-
-`withNetworkConnectivity` provides a true/false mobile connectivity status based on the `useNetworkConnectivity` hook.
-
-## Usage
-
-```jsx
-/**
- * WordPress dependencies
- */
-import { withNetworkConnectivity } from '@wordpress/compose';
-
-export class MyComponent extends Component {
-	if ( this.props.isConnected !== true ) {
-		console.log( 'You are currently offline.' )
-	}
-}
-
-export default withNetworkConnectivity( MyComponent )
-```

package/src/higher-order/with-network-connectivity/index.native.js

@@ -1,19 +0,0 @@
-/**
- * Internal dependencies
- */
-import { createHigherOrderComponent } from '../../utils/create-higher-order-component';
-import useNetworkConnectivity from '../../hooks/use-network-connectivity';
-
-const withNetworkConnectivity = createHigherOrderComponent(
-	( WrappedComponent ) => {
-		return ( props ) => {
-			const { isConnected } = useNetworkConnectivity();
-			return (
-				<WrappedComponent { ...props } isConnected={ isConnected } />
-			);
-		};
-	},
-	'withNetworkConnectivity'
-);
-
-export default withNetworkConnectivity;

package/src/higher-order/with-preferred-color-scheme/index.native.js

@@ -1,40 +0,0 @@
-/**
- * Internal dependencies
- */
-import { createHigherOrderComponent } from '../../utils/create-higher-order-component';
-import usePreferredColorScheme from '../../hooks/use-preferred-color-scheme';
-
-/**
- * WordPress dependencies
- */
-import { useCallback } from '@wordpress/element';
-
-const withPreferredColorScheme = createHigherOrderComponent(
-	( WrappedComponent ) => ( props ) => {
-		const colorScheme = usePreferredColorScheme();
-		const isDarkMode = colorScheme === 'dark';
-
-		const getStyles = useCallback(
-			( lightStyles, darkStyles ) => {
-				const finalDarkStyles = {
-					...lightStyles,
-					...darkStyles,
-				};
-
-				return isDarkMode ? finalDarkStyles : lightStyles;
-			},
-			[ isDarkMode ]
-		);
-
-		return (
-			<WrappedComponent
-				preferredColorScheme={ colorScheme }
-				getStylesFromColorScheme={ getStyles }
-				{ ...props }
-			/>
-		);
-	},
-	'withPreferredColorScheme'
-);
-
-export default withPreferredColorScheme;

package/src/hooks/use-constrained-tabbing/index.native.js

@@ -1,14 +0,0 @@
-/**
- * WordPress dependencies
- */
-import { useRef } from '@wordpress/element';
-
-function useConstrainedTabbing() {
-	const ref = useRef();
-
-	// Do nothing on mobile as tabbing is not a mobile behavior.
-
-	return ref;
-}
-
-export default useConstrainedTabbing;

package/src/hooks/use-focus-outside/index.native.js

@@ -1,170 +0,0 @@
-/**
- * WordPress dependencies
- */
-import { useCallback, useEffect, useRef } from '@wordpress/element';
-
-/**
- * Input types which are classified as button types, for use in considering
- * whether element is a (focus-normalized) button.
- *
- * @type {string[]}
- */
-const INPUT_BUTTON_TYPES = [ 'button', 'submit' ];
-
-/**
- * @typedef {HTMLButtonElement | HTMLLinkElement | HTMLInputElement} FocusNormalizedButton
- */
-
-/**
- * Returns true if the given element is a button element subject to focus
- * normalization, or false otherwise.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#Clicking_and_focus
- *
- * @param {EventTarget} eventTarget The target from a mouse or touch event.
- *
- * @return {eventTarget is FocusNormalizedButton} Whether element is a button.
- */
-function isFocusNormalizedButton( eventTarget ) {
-	switch ( eventTarget.nodeName ) {
-		case 'A':
-		case 'BUTTON':
-			return true;
-
-		case 'INPUT':
-			return INPUT_BUTTON_TYPES.includes(
-				/** @type {HTMLInputElement} */ ( eventTarget ).type
-			);
-	}
-
-	return false;
-}
-
-/**
- * @typedef {React.SyntheticEvent} SyntheticEvent
- */
-
-/**
- * @callback EventCallback
- * @param {SyntheticEvent} event input related event.
- */
-
-/**
- * @typedef FocusOutsideReactElement
- * @property {EventCallback} handleFocusOutside callback for a focus outside event.
- */
-
-/**
- * @typedef {React.MutableRefObject<FocusOutsideReactElement | undefined>} FocusOutsideRef
- */
-
-/**
- * @typedef {Object} FocusOutsideReturnValue
- * @property {EventCallback} onFocus      An event handler for focus events.
- * @property {EventCallback} onBlur       An event handler for blur events.
- * @property {EventCallback} onMouseDown  An event handler for mouse down events.
- * @property {EventCallback} onMouseUp    An event handler for mouse up events.
- * @property {EventCallback} onTouchStart An event handler for touch start events.
- * @property {EventCallback} onTouchEnd   An event handler for touch end events.
- */
-
-/**
- * A react hook that can be used to check whether focus has moved outside the
- * element the event handlers are bound to.
- *
- * @param {EventCallback} onFocusOutside A callback triggered when focus moves outside
- *                                       the element the event handlers are bound to.
- *
- * @return {FocusOutsideReturnValue} An object containing event handlers. Bind the event handlers
- *                                   to a wrapping element element to capture when focus moves
- *                                   outside that element.
- */
-export default function useFocusOutside( onFocusOutside ) {
-	const currentOnFocusOutside = useRef( onFocusOutside );
-	useEffect( () => {
-		currentOnFocusOutside.current = onFocusOutside;
-	}, [ onFocusOutside ] );
-
-	const preventBlurCheck = useRef( false );
-
-	/**
-	 * @type {React.MutableRefObject<number | undefined>}
-	 */
-	const blurCheckTimeoutId = useRef();
-
-	/**
-	 * Cancel a blur check timeout.
-	 */
-	const cancelBlurCheck = useCallback( () => {
-		clearTimeout( blurCheckTimeoutId.current );
-	}, [] );
-
-	// Cancel blur checks on unmount.
-	useEffect( () => {
-		return () => cancelBlurCheck();
-	}, [] );
-
-	// Cancel a blur check if the callback or ref is no longer provided.
-	useEffect( () => {
-		if ( ! onFocusOutside ) {
-			cancelBlurCheck();
-		}
-	}, [ onFocusOutside, cancelBlurCheck ] );
-
-	/**
-	 * Handles a mousedown or mouseup event to respectively assign and
-	 * unassign a flag for preventing blur check on button elements. Some
-	 * browsers, namely Firefox and Safari, do not emit a focus event on
-	 * button elements when clicked, while others do. The logic here
-	 * intends to normalize this as treating click on buttons as focus.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#Clicking_and_focus
-	 *
-	 * @param {SyntheticEvent} event Event for mousedown or mouseup.
-	 */
-	const normalizeButtonFocus = useCallback( ( event ) => {
-		const { type, target } = event;
-		const isInteractionEnd = [ 'mouseup', 'touchend' ].includes( type );
-
-		if ( isInteractionEnd ) {
-			preventBlurCheck.current = false;
-		} else if ( isFocusNormalizedButton( target ) ) {
-			preventBlurCheck.current = true;
-		}
-	}, [] );
-
-	/**
-	 * A callback triggered when a blur event occurs on the element the handler
-	 * is bound to.
-	 *
-	 * Calls the `onFocusOutside` callback in an immediate timeout if focus has
-	 * move outside the bound element and is still within the document.
-	 *
-	 * @param {SyntheticEvent} event Blur event.
-	 */
-	const queueBlurCheck = useCallback( ( event ) => {
-		// React does not allow using an event reference asynchronously
-		// due to recycling behavior, except when explicitly persisted.
-		event.persist();
-
-		// Skip blur check if clicking button. See `normalizeButtonFocus`.
-		if ( preventBlurCheck.current ) {
-			return;
-		}
-
-		blurCheckTimeoutId.current = setTimeout( () => {
-			if ( 'function' === typeof currentOnFocusOutside.current ) {
-				currentOnFocusOutside.current( event );
-			}
-		}, 0 );
-	}, [] );
-
-	return {
-		onFocus: cancelBlurCheck,
-		onMouseDown: normalizeButtonFocus,
-		onMouseUp: normalizeButtonFocus,
-		onTouchStart: normalizeButtonFocus,
-		onTouchEnd: normalizeButtonFocus,
-		onBlur: queueBlurCheck,
-	};
-}

package/src/hooks/use-keyboard-shortcut/index.native.js

@@ -1,2 +0,0 @@
-const useKeyboardShortcut = () => null;
-export default useKeyboardShortcut;

package/src/hooks/use-network-connectivity/index.native.js

@@ -1,59 +0,0 @@
-/**
- * WordPress dependencies
- */
-import { useEffect, useState } from '@wordpress/element';
-import {
-	requestConnectionStatus,
-	subscribeConnectionStatus,
-} from '@wordpress/react-native-bridge';
-
-/**
- * @typedef {Object} NetworkInformation
- *
- * @property {boolean} [isConnected] Whether the device is connected to a network.
- */
-
-/**
- * Returns the current network connectivity status provided by the native bridge.
- *
- * @example
- *
- * ```jsx
- * const { isConnected } = useNetworkConnectivity();
- * ```
- *
- * @return {NetworkInformation} Network information.
- */
-export default function useNetworkConnectivity() {
-	const [ isConnected, setIsConnected ] = useState( true );
-
-	useEffect( () => {
-		let isCurrent = true;
-
-		requestConnectionStatus( ( isBridgeConnected ) => {
-			if ( ! isCurrent ) {
-				return;
-			}
-
-			setIsConnected( isBridgeConnected );
-		} );
-
-		return () => {
-			isCurrent = false;
-		};
-	}, [] );
-
-	useEffect( () => {
-		const subscription = subscribeConnectionStatus(
-			( { isConnected: isBridgeConnected } ) => {
-				setIsConnected( isBridgeConnected );
-			}
-		);
-
-		return () => {
-			subscription.remove();
-		};
-	}, [] );
-
-	return { isConnected };
-}