@wordpress/compose 8.0.0 → 8.1.1

package/src/hooks/use-merge-refs/index.ts

@@ -2,13 +2,34 @@
  * WordPress dependencies
  */
 import { useRef, useCallback, useLayoutEffect } from '@wordpress/element';
-import type { Ref, RefCallback } from 'react';
+import type { MutableRefObject, Ref, RefCallback } from 'react';
 
-function assignRef< T >( ref: Ref< T >, value: T ) {
+// Returns a cleanup function if the ref callback returned one (React 19 ref
+// callback cleanup pattern), otherwise `undefined`. Object refs never have a
+// cleanup and only set `.current`.
+function assignRef< T >( ref: Ref< T >, value: T ): ( () => void ) | undefined {
 	if ( typeof ref === 'function' ) {
-		ref( value );
+		const returned = ref( value );
+		return typeof returned === 'function' ? returned : undefined;
 	} else if ( ref && ref.hasOwnProperty( 'current' ) ) {
-		ref.current = value;
+		( ref as MutableRefObject< T > ).current = value;
+	}
+	return undefined;
+}
+
+// Tear down a ref at the given index: prefer the stored cleanup; otherwise
+// fall back to calling the ref with `null`.
+function detachRef< T >(
+	ref: Ref< T >,
+	index: number,
+	cleanups: Array< ( () => void ) | undefined >
+): void {
+	const cleanup = cleanups[ index ];
+	if ( cleanup ) {
+		cleanups[ index ] = undefined;
+		cleanup();
+	} else {
+		assignRef( ref, null );
 	}
 }
 
@@ -28,22 +49,24 @@ function assignRef< T >( ref: Ref< T >, value: T ) {
  * old ref callback will be called with `null` and the new ref callback will be
  * called with the same value.
  *
- * To make ref callbacks easier to use, you can also pass the result of
- * `useRefEffect`, which makes cleanup easier by allowing you to return a
- * cleanup function instead of handling `null`.
+ * Inner ref callbacks may return a cleanup function (React 19's ref callback
+ * cleanup pattern). When a ref callback returns a function, that function is
+ * invoked at teardown (node change, dependency change, or unmount) **instead
+ * of** the callback being called with `null`. Callbacks that do not return a
+ * cleanup continue to receive `null` on teardown as before.
  *
  * It's also possible to _disable_ a ref (and its behaviour) by simply not
  * passing the ref.
  *
  * ```jsx
- * const ref = useRefEffect( ( node ) => {
+ * const ref = useCallback( ( node ) => {
  *   node.addEventListener( ... );
  *   return () => {
  *     node.removeEventListener( ... );
  *   };
  * }, [ ...dependencies ] );
  * const otherRef = useRef();
- * const mergedRefs useMergeRefs( [
+ * const mergedRefs = useMergeRefs( [
  *   enabled && ref,
  *   otherRef,
  * ] );
@@ -56,11 +79,15 @@ function assignRef< T >( ref: Ref< T >, value: T ) {
 export default function useMergeRefs< T >(
 	refs: Ref< T >[]
 ): RefCallback< T > {
-	const element = useRef( null );
+	const elementRef = useRef< T | null >( null );
 	const isAttachedRef = useRef( false );
 	const didElementChangeRef = useRef( false );
 	const previousRefsRef = useRef< Ref< T >[] >( [] );
 	const currentRefsRef = useRef( refs );
+	// Position-indexed cleanups returned by inner ref callbacks. A slot is
+	// `undefined` when the ref at that position did not return a cleanup (or
+	// is an object ref / disabled).
+	const cleanupsRef = useRef< Array< ( () => void ) | undefined > >( [] );
 
 	// Update on render before the ref callback is called, so the ref callback
 	// always has access to the current refs.
@@ -77,8 +104,11 @@ export default function useMergeRefs< T >(
 			refs.forEach( ( ref, index ) => {
 				const previousRef = previousRefsRef.current[ index ];
 				if ( ref !== previousRef ) {
-					assignRef( previousRef, null );
-					assignRef( ref, element.current );
+					detachRef( previousRef, index, cleanupsRef.current );
+					cleanupsRef.current[ index ] = assignRef(
+						ref,
+						elementRef.current as T
+					);
 				}
 			} );
 		}
@@ -97,20 +127,21 @@ export default function useMergeRefs< T >(
 	return useCallback( ( value: T | null ) => {
 		// Update the element so it can be used when calling ref callbacks on a
 		// dependency change.
-		assignRef( element, value );
+		elementRef.current = value;
 
 		didElementChangeRef.current = true;
 		isAttachedRef.current = value !== null;
 
 		// When an element changes, the current ref callback should be called
 		// with the new element and the previous one with `null`.
-		const refsToAssign = value
-			? currentRefsRef.current
-			: previousRefsRef.current;
-
-		// Update the latest refs.
-		for ( const ref of refsToAssign ) {
-			assignRef( ref, value );
+		if ( value === null ) {
+			previousRefsRef.current.forEach( ( ref, index ) => {
+				detachRef( ref, index, cleanupsRef.current );
+			} );
+		} else {
+			currentRefsRef.current.forEach( ( ref, index ) => {
+				cleanupsRef.current[ index ] = assignRef( ref, value );
+			} );
 		}
 	}, [] );
 }

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-resize-observer/use-resize-observer.ts

@@ -18,7 +18,7 @@ export function useResizeObserver< T extends HTMLElement >(
 ): ( element?: T | null ) => void {
 	const callbackEvent = useEvent( callback );
 
-	const observedElementRef = useRef< T >( null );
+	const observedElementRef = useRef< T | null >( null );
 	const resizeObserverRef = useRef< ResizeObserver >( undefined );
 	return useEvent( ( element?: T | null ) => {
 		if ( element === observedElementRef.current ) {

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;