@wordpress/compose 8.1.0 → 8.1.2-next.v.202606191442.0

package/src/hooks/use-media-query/test/ssr.js

@@ -0,0 +1,47 @@
+/**
+ * @jest-environment node
+ */
+
+/**
+ * External dependencies
+ */
+import { renderToString } from 'react-dom/server';
+
+/**
+ * Internal dependencies
+ */
+import useMediaQuery from '../';
+import useViewportMatch from '../../use-viewport-match';
+
+const MediaQueryComponent = ( { query } ) => {
+	const result = useMediaQuery( query );
+	return `useMediaQuery: ${ result }`;
+};
+
+const ViewportMatchComponent = ( { breakpoint, operator } ) => {
+	const result = useViewportMatch( breakpoint, operator );
+	return `useViewportMatch: ${ result }`;
+};
+
+describe( 'compose hooks in a server (no-window) environment', () => {
+	it( 'useMediaQuery renders to false without throwing when window is undefined', () => {
+		expect( typeof window ).toBe( 'undefined' );
+		expect(
+			renderToString( <MediaQueryComponent query="(min-width: 782px)" /> )
+		).toBe( 'useMediaQuery: false' );
+	} );
+
+	it( 'useMediaQuery renders to false when no query is provided', () => {
+		expect( renderToString( <MediaQueryComponent /> ) ).toBe(
+			'useMediaQuery: false'
+		);
+	} );
+
+	it( 'useViewportMatch renders to false without throwing when window is undefined', () => {
+		expect(
+			renderToString(
+				<ViewportMatchComponent breakpoint="small" operator=">=" />
+			)
+		).toBe( 'useViewportMatch: false' );
+	} );
+} );

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

@@ -4,12 +4,33 @@
 import { useRef, useCallback, useLayoutEffect } from '@wordpress/element';
 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 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-reduced-motion/{index.js → index.ts}

@@ -6,9 +6,9 @@ import useMediaQuery from '../use-media-query';
 /**
  * Hook returning whether the user has a preference for reduced motion.
  *
- * @return {boolean} Reduced motion preference value.
+ * @return Reduced motion preference value.
  */
-const useReducedMotion = () =>
+const useReducedMotion = (): boolean =>
 	useMediaQuery( '(prefers-reduced-motion: reduce)' );
 
 export default useReducedMotion;

package/src/hooks/use-throttle/{index.js → index.ts}

@@ -12,6 +12,8 @@ import { useEffect } from '@wordpress/element';
  * Internal dependencies
  */
 import { throttle } from '../../utils/throttle';
+import type { ThrottleOptions } from '../../utils/throttle';
+import type { DebouncedFunc } from '../../utils/debounce';
 
 /**
  * Throttles a function similar to Lodash's `throttle`. A new throttled function will
@@ -21,14 +23,18 @@ import { throttle } from '../../utils/throttle';
  *
  * @see https://lodash.com/docs/4#throttle
  *
- * @template {(...args: any[]) => void} TFunc
+ * @template TFunc
  *
- * @param {TFunc}                                          fn        The function to throttle.
- * @param {number}                                         [wait]    The number of milliseconds to throttle invocations to.
- * @param {import('../../utils/throttle').ThrottleOptions} [options] The options object. See linked documentation for details.
- * @return {import('../../utils/debounce').DebouncedFunc<TFunc>} Throttled function.
+ * @param    fn      The function to throttle.
+ * @param    wait    The number of milliseconds to throttle invocations to.
+ * @param    options The options object.
+ * @return          Throttled function.
  */
-export default function useThrottle( fn, wait, options ) {
+export default function useThrottle< TFunc extends ( ...args: any[] ) => void >(
+	fn: TFunc,
+	wait?: number,
+	options?: ThrottleOptions
+): DebouncedFunc< TFunc > {
 	const throttled = useMemoOne(
 		() => throttle( fn, wait ?? 0, options ),
 		[ fn, wait, options ]

package/src/hooks/use-viewport-match/{index.js → index.ts}

@@ -8,18 +8,23 @@ import { createContext, useContext } from '@wordpress/element';
  */
 import useMediaQuery from '../use-media-query';
 
-/**
- * @typedef {"xhuge" | "huge" | "wide" | "xlarge" | "large" | "medium" | "small" | "mobile"} WPBreakpoint
- */
+type Breakpoint =
+	| 'xhuge'
+	| 'huge'
+	| 'wide'
+	| 'xlarge'
+	| 'large'
+	| 'medium'
+	| 'small'
+	| 'mobile';
+type ViewportOperator = '>=' | '<';
 
 /**
  * Hash of breakpoint names with pixel width at which it becomes effective.
  *
  * @see _breakpoints.scss
- *
- * @type {Record<WPBreakpoint, number>}
  */
-const BREAKPOINTS = {
+const BREAKPOINTS: Record< Breakpoint, number > = {
 	xhuge: 1920,
 	huge: 1440,
 	wide: 1280,
@@ -30,57 +35,59 @@ const BREAKPOINTS = {
 	mobile: 480,
 };
 
-/**
- * @typedef {">=" | "<"} WPViewportOperator
- */
-
 /**
  * Object mapping media query operators to the condition to be used.
- *
- * @type {Record<WPViewportOperator, string>}
  */
-const CONDITIONS = {
+const CONDITIONS: Record< ViewportOperator, string > = {
 	'>=': 'min-width',
 	'<': 'max-width',
 };
 
 /**
- * Object mapping media query operators to a function that given a breakpointValue and a width evaluates if the operator matches the values.
- *
- * @type {Record<WPViewportOperator, (breakpointValue: number, width: number) => boolean>}
+ * Object mapping media query operators to a function that evaluates if the operator matches.
  */
-const OPERATOR_EVALUATORS = {
+const OPERATOR_EVALUATORS: Record<
+	ViewportOperator,
+	( breakpointValue: number, width: number ) => boolean
+> = {
 	'>=': ( breakpointValue, width ) => width >= breakpointValue,
 	'<': ( breakpointValue, width ) => width < breakpointValue,
 };
 
-const ViewportMatchWidthContext = createContext(
-	/** @type {null | number} */ ( null )
-);
+const ViewportMatchWidthContext = createContext< number | null >( null );
 ViewportMatchWidthContext.displayName = 'ViewportMatchWidthContext';
 
 /**
  * Returns true if the viewport matches the given query, or false otherwise.
  *
- * @param {WPBreakpoint}       breakpoint      Breakpoint size name.
- * @param {WPViewportOperator} [operator=">="] Viewport operator.
- * @param {Window}             [view=window]   Window instance in which to perform viewport matching.
+ * @param breakpoint Breakpoint size name.
+ * @param operator   Viewport operator.
+ * @param view       Window instance in which to perform viewport matching.
  *
  * @example
  *
- * ```js
+ * ```ts
  * useViewportMatch( 'huge', '<' );
  * useViewportMatch( 'medium' );
  * ```
  *
- * @return {boolean} Whether viewport matches query.
+ * @return Whether viewport matches query.
  */
-const useViewportMatch = ( breakpoint, operator = '>=', view = window ) => {
+const useViewportMatch = (
+	breakpoint: Breakpoint,
+	operator: ViewportOperator = '>=',
+	// Resolve the default lazily so SSR (where `window` is undeclared) does not
+	// throw a ReferenceError when this default expression is evaluated.
+	view: Window | undefined = typeof window !== 'undefined'
+		? window
+		: undefined
+): boolean => {
 	const simulatedWidth = useContext( ViewportMatchWidthContext );
 	const mediaQuery =
 		! simulatedWidth &&
 		`(${ CONDITIONS[ operator ] }: ${ BREAKPOINTS[ breakpoint ] }px)`;
 	const mediaQueryResult = useMediaQuery( mediaQuery || undefined, view );
+
 	if ( simulatedWidth ) {
 		return OPERATOR_EVALUATORS[ operator ](
 			BREAKPOINTS[ breakpoint ],

package/src/hooks/use-warn-on-change/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Internal dependencies
+ */
+import usePrevious from '../use-previous';
+
+/**
+ * Hook that performs a shallow comparison between the previous value of an object
+ * and the new one, if there's a difference, it prints it to the console.
+ * This is useful in performance related work, to check why a component re-renders.
+ *
+ *  @example
+ *
+ * ```tsx
+ * function MyComponent(props: Record<string, any>) {
+ *    useWarnOnChange(props);
+ *
+ *    return "Something";
+ * }
+ * ```
+ *
+ * @param object Object which changes to compare.
+ * @param prefix Just a prefix to show when console logging.
+ */
+function useWarnOnChange(
+	object: Record< string, any > | any[],
+	prefix: string = 'Change detection'
+): void {
+	const previousValues = usePrevious( object );
+
+	Object.entries( previousValues ?? [] ).forEach( ( [ key, value ] ) => {
+		if ( value !== object[ key as keyof typeof object ] ) {
+			// eslint-disable-next-line no-console
+			console.warn(
+				`${ prefix }: ${ key } key changed:`,
+				value,
+				object[ key as keyof typeof object ]
+			);
+		}
+	} );
+}
+
+export default useWarnOnChange;

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 )
-```