From 95881cc81050ad4d373b388e5bcdf3fc1aa98380 Mon Sep 17 00:00:00 2001
From: Jarda Snajdr <jsnajdr@gmail.com>
Date: Tue, 27 Aug 2024 10:26:56 +0200
Subject: [PATCH 01/30] Simplify useResizeObserver

---
 packages/compose/README.md                    |   2 +-
 .../src/hooks/use-resize-observer/index.tsx   | 371 ++++--------------
 2 files changed, 84 insertions(+), 289 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index f3109253e44c11..0da853ad75c5af 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -500,7 +500,7 @@ _Returns_
 
 ### useResizeObserver
 
-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.
+Hook which allows to listen to the resize event of any target element when it changes size. \_Note: `useResizeObserver` will report `null` sizes until after first render.
 
 _Usage_
 
diff --git a/packages/compose/src/hooks/use-resize-observer/index.tsx b/packages/compose/src/hooks/use-resize-observer/index.tsx
index c8c964228edfc2..b350cab047493f 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.tsx
+++ b/packages/compose/src/hooks/use-resize-observer/index.tsx
@@ -1,116 +1,23 @@
 /**
  * External dependencies
  */
-import type { ReactElement, RefCallback, RefObject } from 'react';
+import type { ReactElement } from 'react';
 
 /**
  * WordPress dependencies
  */
 import {
-	useMemo,
-	useRef,
 	useCallback,
-	useEffect,
+	useLayoutEffect,
+	useRef,
 	useState,
 } 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 callbackElementRef = 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 ( callbackElementRef.current ) {
-			element = callbackElementRef.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 ) => {
-			callbackElementRef.current = element;
-			callSubscriber();
-		},
-		[ callSubscriber ]
-	);
-}
-
 type ObservedSize = {
-	width: number | undefined;
-	height: number | undefined;
+	width: number | null;
+	height: number | null;
 };
 
-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:
@@ -136,187 +43,86 @@ declare global {
 // 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;
+const extractSize = ( entry: ResizeObserverEntry ): ObservedSize => {
+	let entrySize;
+	if ( ! entry.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.
+		entrySize = [ entry.contentRect.width, entry.contentRect.height ];
+	} else if ( entry.contentBoxSize[ 0 ] ) {
+		const contentBoxSize = entry.contentBoxSize[ 0 ];
+		entrySize = [ contentBoxSize.inlineSize, contentBoxSize.blockSize ];
+	} else {
+		// TS complains about this, because the RO entry type follows the spec and does not reflect Firefox's buggy
+		// behaviour of returning objects instead of arrays for `borderBoxSize` and `contentBoxSize`.
+		const contentBoxSize =
+			entry.contentBoxSize as unknown as ResizeObserverSize;
+		entrySize = [ contentBoxSize.inlineSize, contentBoxSize.blockSize ];
 	}
 
-	// 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 ];
+	const [ width, height ] = entrySize.map( ( d ) => Math.round( d ) );
+	return { width, height };
+};
+
+const RESIZE_ELEMENT_STYLES = {
+	position: 'absolute',
+	top: 0,
+	left: 0,
+	right: 0,
+	bottom: 0,
+	pointerEvents: 'none',
+	opacity: 0,
+	overflow: 'hidden',
+	zIndex: -1,
+} as const;
+
+type ResizeElementProps = {
+	onResize: ( s: ObservedSize ) => void;
 };
 
-type RoundingFunction = ( n: number ) => number;
+function ResizeElement( { onResize }: ResizeElementProps ) {
+	const resizeElementRef = useRef< HTMLDivElement >( null );
+	const resizeCallbackRef = useRef( onResize );
 
-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;
+	useLayoutEffect( () => {
+		resizeCallbackRef.current = onResize;
+	}, [ onResize ] );
 
-	// Using a single instance throughout the hook's lifetime
-	const resizeObserverRef = useRef< {
-		box?: ResizeObserverBoxOptions;
-		round?: RoundingFunction;
-		instance: ResizeObserver;
-	} >();
+	useLayoutEffect( () => {
+		const resizeElement = resizeElementRef.current as HTMLDivElement;
+		const resizeObserver = new ResizeObserver( ( entries ) => {
+			const newSize = extractSize( entries[ 0 ] );
+			resizeCallbackRef.current( newSize );
+		} );
 
-	const [ size, setSize ] = useState< {
-		width?: number;
-		height?: number;
-	} >( {
-		width: undefined,
-		height: undefined,
-	} );
+		resizeObserver.observe( resizeElement );
 
-	// In certain edge cases the RO might want to report a size change just after
-	// the component unmounted.
-	const didUnmountRef = useRef( false );
-	useEffect( () => {
-		didUnmountRef.current = false;
 		return () => {
-			didUnmountRef.current = true;
+			resizeObserver.unobserve( resizeElement );
 		};
 	}, [] );
 
-	// Using a ref to track the previous width / height to avoid unnecessary renders.
-	const previousRef: {
-		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 (
-								previousRef.current.width !== newWidth ||
-								previousRef.current.height !== newHeight
-							) {
-								const newSize = {
-									width: newWidth,
-									height: newHeight,
-								};
-								previousRef.current.width = newWidth;
-								previousRef.current.height = newHeight;
-								if ( onResizeRef.current ) {
-									onResizeRef.current( newSize );
-								} else if ( ! didUnmountRef.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 (
+		<div
+			ref={ resizeElementRef }
+			style={ RESIZE_ELEMENT_STYLES }
+			aria-hidden="true"
+		/>
 	);
+}
 
-	return useMemo(
-		() => ( {
-			ref: refCallback,
-			width: size.width,
-			height: size.height,
-		} ),
-		[ refCallback, size ? size.width : null, size ? size.height : null ]
-	);
+function sizeEquals( a: ObservedSize, b: ObservedSize ) {
+	return a.width === b.width && a.height === b.height;
 }
 
+const NULL_SIZE: ObservedSize = { width: null, 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.
+ * Hook which allows to listen to the resize event of any target element when it changes size.
+ * _Note: `useResizeObserver` will report `null` sizes until after first render.
  *
  * @example
  *
@@ -333,30 +139,19 @@ function useResizeObserver< T extends HTMLElement >(
  * };
  * ```
  */
-export default function useResizeAware(): [
-	ReactElement,
-	{ 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 ];
+export default function useResizeObserver(): [ ReactElement, ObservedSize ] {
+	const [ size, setSize ] = useState( NULL_SIZE );
+
+	// Using a ref to track the previous width / height to avoid unnecessary renders.
+	const previousSizeRef = useRef( NULL_SIZE );
+
+	const handleResize = useCallback( ( newSize: ObservedSize ) => {
+		if ( ! sizeEquals( previousSizeRef.current, newSize ) ) {
+			previousSizeRef.current = newSize;
+			setSize( newSize );
+		}
+	}, [] );
+
+	const resizeElement = <ResizeElement onResize={ handleResize } />;
+	return [ resizeElement, size ];
 }

From 1e305a983734ceb07ce1b6435eaf303dd6549637 Mon Sep 17 00:00:00 2001
From: Jarda Snajdr <jsnajdr@gmail.com>
Date: Fri, 30 Aug 2024 08:56:59 +0200
Subject: [PATCH 02/30] Loop through all resize entries

---
 packages/compose/src/hooks/use-resize-observer/index.tsx | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/compose/src/hooks/use-resize-observer/index.tsx b/packages/compose/src/hooks/use-resize-observer/index.tsx
index b350cab047493f..05461bb2468b07 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.tsx
+++ b/packages/compose/src/hooks/use-resize-observer/index.tsx
@@ -94,8 +94,10 @@ function ResizeElement( { onResize }: ResizeElementProps ) {
 	useLayoutEffect( () => {
 		const resizeElement = resizeElementRef.current as HTMLDivElement;
 		const resizeObserver = new ResizeObserver( ( entries ) => {
-			const newSize = extractSize( entries[ 0 ] );
-			resizeCallbackRef.current( newSize );
+			for ( const entry of entries ) {
+				const newSize = extractSize( entry );
+				resizeCallbackRef.current( newSize );
+			}
 		} );
 
 		resizeObserver.observe( resizeElement );

From 55172e3b37ef00b279d8c1c61658e3c61b8e9a37 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Fri, 30 Aug 2024 18:38:53 +0200
Subject: [PATCH 03/30] Add `useEvent` util.

---
 packages/compose/README.md                    | 17 ++++++++
 packages/compose/src/hooks/use-event/index.ts | 43 +++++++++++++++++++
 packages/compose/src/index.js                 |  1 +
 3 files changed, 61 insertions(+)
 create mode 100644 packages/compose/src/hooks/use-event/index.ts

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 0da853ad75c5af..0df7b49903f09c 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -305,6 +305,23 @@ _Returns_
 
 -   `import('react').RefCallback<HTMLElement>`: Element Ref.
 
+### useEvent
+
+Creates a stable callback function that has access to the latest state and can be used within event handlers and effect callbacks. Throws when used in the render phase.
+
+_Usage_
+
+```tsx
+function Component( props ) {
+	const onClick = useEvent( props.onClick );
+	React.useEffect( () => {}, [ onClick ] );
+}
+```
+
+_Parameters_
+
+-   _callback_ `T`: The callback function to wrap.
+
 ### useFocusableIframe
 
 Dispatches a bubbling focus event when the iframe receives focus. Use `onFocus` as usual on the iframe or a parent element.
diff --git a/packages/compose/src/hooks/use-event/index.ts b/packages/compose/src/hooks/use-event/index.ts
new file mode 100644
index 00000000000000..cae5054f9aed92
--- /dev/null
+++ b/packages/compose/src/hooks/use-event/index.ts
@@ -0,0 +1,43 @@
+/**
+ * WordPress dependencies
+ */
+import { useRef, useInsertionEffect, useCallback } from '@wordpress/element';
+
+/**
+ * Any function.
+ */
+export type AnyFunction = ( ...args: any ) => any;
+
+/**
+ * Creates a stable callback function that has access to the latest state and
+ * can be used within event handlers and effect callbacks. Throws when used in
+ * the render phase.
+ *
+ * @param callback The callback function to wrap.
+ *
+ * @example
+ *
+ * ```tsx
+ * function Component(props) {
+ *   const onClick = useEvent(props.onClick);
+ *   React.useEffect(() => {}, [onClick]);
+ * }
+ * ```
+ */
+export default function useEvent< T extends AnyFunction >(
+	/**
+	 * The callback function to wrap.
+	 */
+	callback?: T
+) {
+	const ref = useRef< AnyFunction | undefined >( () => {
+		throw new Error( 'Cannot call an event handler while rendering.' );
+	} );
+	useInsertionEffect( () => {
+		ref.current = callback;
+	} );
+	return useCallback< AnyFunction >(
+		( ...args ) => ref.current?.( ...args ),
+		[]
+	) as T;
+}
diff --git a/packages/compose/src/index.js b/packages/compose/src/index.js
index f7e1d1618f97fb..29a9aa61737440 100644
--- a/packages/compose/src/index.js
+++ b/packages/compose/src/index.js
@@ -25,6 +25,7 @@ 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 useDisabled } from './hooks/use-disabled';
+export { default as useEvent } from './hooks/use-event';
 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';

From 0b91189f8c7feac117b5249681168a796e79b73c Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Fri, 30 Aug 2024 18:49:55 +0200
Subject: [PATCH 04/30] Add `useObserveElementSize` util.

---
 packages/compose/README.md                    |  25 ++++
 .../hooks/use-observe-element-size/index.ts   | 109 ++++++++++++++++++
 packages/compose/src/index.js                 |   1 +
 3 files changed, 135 insertions(+)
 create mode 100644 packages/compose/src/hooks/use-observe-element-size/index.ts

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 0df7b49903f09c..17aa8c3f9e02e3 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -480,6 +480,31 @@ _Returns_
 
 -   `V | undefined`: The value corresponding to the map key requested.
 
+### useObserveElementSize
+
+Tracks a given element's size and calls `onUpdate` for all of its discrete values using a `ResizeObserver`. The element can change dynamically and **it must not be stored in a ref**. Instead, it should be stored in a React state or equivalent.
+
+_Usage_
+
+```tsx
+const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
+useObserveElementSize(
+	targetElement,
+	( resizeObserverEntries, element ) => {
+		console.log( 'Resize observer entries:', resizeObserverEntries );
+		console.log( 'Element that was resized:', element );
+	},
+	{ box: 'border-box' }
+);
+<div ref={ setTargetElement } />;
+```
+
+_Parameters_
+
+-   _targetElement_ `HTMLElement | undefined | null`: The target element to observe. It can be changed dynamically.
+-   _onUpdate_ `( resizeObserverEntries: ResizeObserverEntry[], element: HTMLElement ) => void`: Callback that will be called when the element is resized. It is passed the list of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects passed to the `ResizeObserver.observe` callback internally, and the element being tracked at the time of this update.
+-   _resizeObserverOptions_ `ResizeObserverOptions`: Options to pass to `ResizeObserver.observe` when called internally. Updating this option will not cause the observer to be re-created, and it will only take effect if a new element is observed.
+
 ### usePrevious
 
 Use something's value from the previous render. Based on <https://usehooks.com/usePrevious/>.
diff --git a/packages/compose/src/hooks/use-observe-element-size/index.ts b/packages/compose/src/hooks/use-observe-element-size/index.ts
new file mode 100644
index 00000000000000..e8bc2470c83f37
--- /dev/null
+++ b/packages/compose/src/hooks/use-observe-element-size/index.ts
@@ -0,0 +1,109 @@
+/**
+ * WordPress dependencies
+ */
+import { useRef, useEffect } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import useEvent from '../use-event';
+
+/**
+ * Tracks a given element's size and calls `onUpdate` for all of its discrete
+ * values using a `ResizeObserver`. The element can change dynamically and **it
+ * must not be stored in a ref**. Instead, it should be stored in a React
+ * state or equivalent.
+ *
+ * @param targetElement         The target element to observe. It can be changed dynamically.
+ * @param onUpdate              Callback that will be called when the element is resized. It is passed the list of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects passed to the `ResizeObserver.observe` callback internally, and the element being tracked at the time of this update.
+ * @param resizeObserverOptions Options to pass to `ResizeObserver.observe` when called internally. Updating this option will not cause the observer to be re-created, and it will only take effect if a new element is observed.
+ *
+ * @example
+ *
+ * ```tsx
+ * const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
+ * useObserveElementSize(
+ * 	targetElement,
+ * 	( resizeObserverEntries, element ) => {
+ * 		console.log( 'Resize observer entries:', resizeObserverEntries );
+ * 		console.log( 'Element that was resized:', element );
+ * 	},
+ * 	{ box: 'border-box' }
+ * );
+ * <div ref={ setTargetElement } />;
+ * ```
+ */
+export default function useObserveElementSize(
+	/**
+	 * The target element to observe. It can be changed dynamically.
+	 */
+	targetElement: HTMLElement | undefined | null,
+	/**
+	 * Callback that will be called when the element is resized.
+	 */
+	onUpdate: (
+		/**
+		 * The list of
+		 * [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry)
+		 * objects passed to the `ResizeObserver.observe` callback internally.
+		 */
+		resizeObserverEntries: ResizeObserverEntry[],
+		/**
+		 * The element being tracked at the time of this update.
+		 */
+		element: HTMLElement
+	) => void,
+	/**
+	 * Options to pass to `ResizeObserver.observe` when called internally.
+	 *
+	 * Updating this option will not cause the observer to be re-created, and it
+	 * will only take effect if a new element is observed.
+	 */
+	resizeObserverOptions?: ResizeObserverOptions
+) {
+	const onUpdateEvent = useEvent( onUpdate );
+
+	const observedElementRef = useRef< HTMLElement | null >();
+	const resizeObserverRef = useRef< ResizeObserver >();
+
+	// Options are passed on `.observe` once and never updated, so we store them
+	// in an up-to-date ref to avoid unnecessary cycles of the effect due to
+	// unstable option objects such as inlined literals.
+	const resizeObserverOptionsRef = useRef( resizeObserverOptions );
+	useEffect( () => {
+		resizeObserverOptionsRef.current = resizeObserverOptions;
+	}, [ resizeObserverOptions ] );
+
+	// TODO: could/should this be a layout effect?
+	useEffect( () => {
+		if ( targetElement === observedElementRef.current ) {
+			return;
+		}
+
+		observedElementRef.current = targetElement;
+
+		// Set up a ResizeObserver.
+		if ( ! resizeObserverRef.current ) {
+			resizeObserverRef.current = new ResizeObserver( ( entries ) => {
+				if ( observedElementRef.current ) {
+					onUpdateEvent( entries, observedElementRef.current );
+				}
+			} );
+		}
+		const { current: resizeObserver } = resizeObserverRef;
+
+		// Observe new element.
+		if ( targetElement ) {
+			resizeObserver.observe(
+				targetElement,
+				resizeObserverOptionsRef.current
+			);
+		}
+
+		return () => {
+			// Unobserve previous element.
+			if ( observedElementRef.current ) {
+				resizeObserver.unobserve( observedElementRef.current );
+			}
+		};
+	}, [ onUpdateEvent, targetElement ] );
+}
diff --git a/packages/compose/src/index.js b/packages/compose/src/index.js
index 29a9aa61737440..c879f45f6a537e 100644
--- a/packages/compose/src/index.js
+++ b/packages/compose/src/index.js
@@ -34,6 +34,7 @@ export { default as useInstanceId } from './hooks/use-instance-id';
 export { default as useIsomorphicLayoutEffect } from './hooks/use-isomorphic-layout-effect';
 export { default as useKeyboardShortcut } from './hooks/use-keyboard-shortcut';
 export { default as useMediaQuery } from './hooks/use-media-query';
+export { default as useObserveElementSize } from './hooks/use-observe-element-size';
 export { default as usePrevious } from './hooks/use-previous';
 export { default as useReducedMotion } from './hooks/use-reduced-motion';
 export { default as useStateWithHistory } from './hooks/use-state-with-history';

From c4ee26c8bab90644e2393f260edd951bddde061c Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Fri, 30 Aug 2024 18:50:52 +0200
Subject: [PATCH 05/30] Simplify `useResizeObserver` by using `useEvent` and
 `useObserveElementSize`.

---
 .../src/hooks/use-resize-observer/index.tsx   | 47 +++++++------------
 1 file changed, 18 insertions(+), 29 deletions(-)

diff --git a/packages/compose/src/hooks/use-resize-observer/index.tsx b/packages/compose/src/hooks/use-resize-observer/index.tsx
index 05461bb2468b07..80f597cb0e19bf 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.tsx
+++ b/packages/compose/src/hooks/use-resize-observer/index.tsx
@@ -6,12 +6,12 @@ import type { ReactElement } from 'react';
 /**
  * WordPress dependencies
  */
-import {
-	useCallback,
-	useLayoutEffect,
-	useRef,
-	useState,
-} from '@wordpress/element';
+import { useCallback, useRef, useState } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import useEvent from '../use-event';
+import useObserveElementSize from '../use-observe-element-size';
 
 type ObservedSize = {
 	width: number | null;
@@ -84,32 +84,21 @@ type ResizeElementProps = {
 };
 
 function ResizeElement( { onResize }: ResizeElementProps ) {
-	const resizeElementRef = useRef< HTMLDivElement >( null );
-	const resizeCallbackRef = useRef( onResize );
-
-	useLayoutEffect( () => {
-		resizeCallbackRef.current = onResize;
-	}, [ onResize ] );
-
-	useLayoutEffect( () => {
-		const resizeElement = resizeElementRef.current as HTMLDivElement;
-		const resizeObserver = new ResizeObserver( ( entries ) => {
-			for ( const entry of entries ) {
-				const newSize = extractSize( entry );
-				resizeCallbackRef.current( newSize );
-			}
-		} );
-
-		resizeObserver.observe( resizeElement );
-
-		return () => {
-			resizeObserver.unobserve( resizeElement );
-		};
-	}, [] );
+	const resizeCallbackEvent = useEvent( onResize );
+
+	const [ resizeElement, setResizeElement ] =
+		useState< HTMLDivElement | null >();
+
+	useObserveElementSize( resizeElement, ( entries ) => {
+		for ( const entry of entries ) {
+			const newSize = extractSize( entry );
+			resizeCallbackEvent( newSize );
+		}
+	} );
 
 	return (
 		<div
-			ref={ resizeElementRef }
+			ref={ setResizeElement }
 			style={ RESIZE_ELEMENT_STYLES }
 			aria-hidden="true"
 		/>

From 93a36e1643b8f7a45ff033e8eedd3184a7c0604a Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 14:33:52 +0200
Subject: [PATCH 06/30] Switch to layout effect and accept refs too.

---
 packages/compose/README.md                    |  4 +-
 .../hooks/use-observe-element-size/index.ts   | 37 +++++++++++--------
 2 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 17aa8c3f9e02e3..d437b930fd1bde 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -482,7 +482,7 @@ _Returns_
 
 ### useObserveElementSize
 
-Tracks a given element's size and calls `onUpdate` for all of its discrete values using a `ResizeObserver`. The element can change dynamically and **it must not be stored in a ref**. Instead, it should be stored in a React state or equivalent.
+Tracks a given element's size and calls `onUpdate` for all of its discrete values using a `ResizeObserver`. The element can change dynamically. Alternatively, a ref containing the target element can be passed. However, any updates to the ref will be ignored.
 
 _Usage_
 
@@ -501,7 +501,7 @@ useObserveElementSize(
 
 _Parameters_
 
--   _targetElement_ `HTMLElement | undefined | null`: The target element to observe. It can be changed dynamically.
+-   _targetElement_ `HTMLElement | undefined | null | RefObject< HTMLElement >`: The target element to observe. It can be changed dynamically. Alternatively, a ref containing the target element can be passed. However, any updates to the ref will be ignored.
 -   _onUpdate_ `( resizeObserverEntries: ResizeObserverEntry[], element: HTMLElement ) => void`: Callback that will be called when the element is resized. It is passed the list of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects passed to the `ResizeObserver.observe` callback internally, and the element being tracked at the time of this update.
 -   _resizeObserverOptions_ `ResizeObserverOptions`: Options to pass to `ResizeObserver.observe` when called internally. Updating this option will not cause the observer to be re-created, and it will only take effect if a new element is observed.
 
diff --git a/packages/compose/src/hooks/use-observe-element-size/index.ts b/packages/compose/src/hooks/use-observe-element-size/index.ts
index e8bc2470c83f37..2bddbd49708dbc 100644
--- a/packages/compose/src/hooks/use-observe-element-size/index.ts
+++ b/packages/compose/src/hooks/use-observe-element-size/index.ts
@@ -1,7 +1,11 @@
+/**
+ * External dependencies
+ */
+import type { RefObject } from 'react';
 /**
  * WordPress dependencies
  */
-import { useRef, useEffect } from '@wordpress/element';
+import { useRef, useEffect, useLayoutEffect } from '@wordpress/element';
 /**
  * Internal dependencies
  */
@@ -9,11 +13,11 @@ import useEvent from '../use-event';
 
 /**
  * Tracks a given element's size and calls `onUpdate` for all of its discrete
- * values using a `ResizeObserver`. The element can change dynamically and **it
- * must not be stored in a ref**. Instead, it should be stored in a React
- * state or equivalent.
+ * values using a `ResizeObserver`. The element can change dynamically. Alternatively,
+ * a ref containing the target element can be passed. However, any updates to the ref
+ * will be ignored.
  *
- * @param targetElement         The target element to observe. It can be changed dynamically.
+ * @param targetElement         The target element to observe. It can be changed dynamically. Alternatively, a ref containing the target element can be passed. However, any updates to the ref will be ignored.
  * @param onUpdate              Callback that will be called when the element is resized. It is passed the list of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects passed to the `ResizeObserver.observe` callback internally, and the element being tracked at the time of this update.
  * @param resizeObserverOptions Options to pass to `ResizeObserver.observe` when called internally. Updating this option will not cause the observer to be re-created, and it will only take effect if a new element is observed.
  *
@@ -35,8 +39,11 @@ import useEvent from '../use-event';
 export default function useObserveElementSize(
 	/**
 	 * The target element to observe. It can be changed dynamically.
+	 *
+	 * Alternatively, a ref containing the target element can be passed. However, any updates
+	 * to the ref will be ignored.
 	 */
-	targetElement: HTMLElement | undefined | null,
+	targetElement: HTMLElement | undefined | null | RefObject< HTMLElement >,
 	/**
 	 * Callback that will be called when the element is resized.
 	 */
@@ -73,13 +80,16 @@ export default function useObserveElementSize(
 		resizeObserverOptionsRef.current = resizeObserverOptions;
 	}, [ resizeObserverOptions ] );
 
-	// TODO: could/should this be a layout effect?
-	useEffect( () => {
-		if ( targetElement === observedElementRef.current ) {
+	useLayoutEffect( () => {
+		const element =
+			targetElement instanceof HTMLElement
+				? targetElement
+				: targetElement?.current;
+		if ( element === observedElementRef.current ) {
 			return;
 		}
 
-		observedElementRef.current = targetElement;
+		observedElementRef.current = element;
 
 		// Set up a ResizeObserver.
 		if ( ! resizeObserverRef.current ) {
@@ -92,11 +102,8 @@ export default function useObserveElementSize(
 		const { current: resizeObserver } = resizeObserverRef;
 
 		// Observe new element.
-		if ( targetElement ) {
-			resizeObserver.observe(
-				targetElement,
-				resizeObserverOptionsRef.current
-			);
+		if ( element ) {
+			resizeObserver.observe( element, resizeObserverOptionsRef.current );
 		}
 
 		return () => {

From fc338499766395fcf21bd0ae4ed82aaf01186ef1 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 14:34:29 +0200
Subject: [PATCH 07/30] Prevent initial re-render in ResizeElement.

---
 packages/compose/src/hooks/use-resize-observer/index.tsx | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/packages/compose/src/hooks/use-resize-observer/index.tsx b/packages/compose/src/hooks/use-resize-observer/index.tsx
index 80f597cb0e19bf..979e8f869ff055 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.tsx
+++ b/packages/compose/src/hooks/use-resize-observer/index.tsx
@@ -84,12 +84,10 @@ type ResizeElementProps = {
 };
 
 function ResizeElement( { onResize }: ResizeElementProps ) {
+	const resizeElementRef = useRef< HTMLDivElement >( null );
 	const resizeCallbackEvent = useEvent( onResize );
 
-	const [ resizeElement, setResizeElement ] =
-		useState< HTMLDivElement | null >();
-
-	useObserveElementSize( resizeElement, ( entries ) => {
+	useObserveElementSize( resizeElementRef, ( entries ) => {
 		for ( const entry of entries ) {
 			const newSize = extractSize( entry );
 			resizeCallbackEvent( newSize );
@@ -98,7 +96,7 @@ function ResizeElement( { onResize }: ResizeElementProps ) {
 
 	return (
 		<div
-			ref={ setResizeElement }
+			ref={ resizeElementRef }
 			style={ RESIZE_ELEMENT_STYLES }
 			aria-hidden="true"
 		/>

From b422ccc35be8172eb13026d3800b269cdfdb1bdc Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 14:45:49 +0200
Subject: [PATCH 08/30] Better error message.

---
 packages/compose/src/hooks/use-event/index.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/compose/src/hooks/use-event/index.ts b/packages/compose/src/hooks/use-event/index.ts
index cae5054f9aed92..c895ce87fe7c02 100644
--- a/packages/compose/src/hooks/use-event/index.ts
+++ b/packages/compose/src/hooks/use-event/index.ts
@@ -31,7 +31,9 @@ export default function useEvent< T extends AnyFunction >(
 	callback?: T
 ) {
 	const ref = useRef< AnyFunction | undefined >( () => {
-		throw new Error( 'Cannot call an event handler while rendering.' );
+		throw new Error(
+			'Callbacks created with `useEvent` cannot be called during rendering.'
+		);
 	} );
 	useInsertionEffect( () => {
 		ref.current = callback;

From cff6661c2e0181c48761e9e02b6c08200249a3bb Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 14:51:27 +0200
Subject: [PATCH 09/30] Improved example of useEvent.

---
 packages/compose/README.md                    | 8 +++++++-
 packages/compose/src/hooks/use-event/index.ts | 8 +++++++-
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index d437b930fd1bde..f02b0c7bbe4926 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -314,7 +314,13 @@ _Usage_
 ```tsx
 function Component( props ) {
 	const onClick = useEvent( props.onClick );
-	React.useEffect( () => {}, [ onClick ] );
+	React.useEffect( () => {
+		onClick();
+		// Won't trigger the effect again when props.onClick is updated.
+	}, [ onClick ] );
+	// Won't re-render Button when props.onClick is updated (if Button is
+	// wrapped in React.memo).
+	return <Button onClick={ onClick } />;
 }
 ```
 
diff --git a/packages/compose/src/hooks/use-event/index.ts b/packages/compose/src/hooks/use-event/index.ts
index c895ce87fe7c02..40ec73fe35f337 100644
--- a/packages/compose/src/hooks/use-event/index.ts
+++ b/packages/compose/src/hooks/use-event/index.ts
@@ -20,7 +20,13 @@ export type AnyFunction = ( ...args: any ) => any;
  * ```tsx
  * function Component(props) {
  *   const onClick = useEvent(props.onClick);
- *   React.useEffect(() => {}, [onClick]);
+ *   React.useEffect(() => {
+ *     onClick();
+ *     // Won't trigger the effect again when props.onClick is updated.
+ *   }, [onClick]);
+ *   // Won't re-render Button when props.onClick is updated (if Button is
+ *   // wrapped in React.memo).
+ *   return <Button onClick={ onClick } />;
  * }
  * ```
  */

From 9531c10e0947a8c0fd16fa9818a04a075690dcae Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 15:08:25 +0200
Subject: [PATCH 10/30] Update packages/compose/src/hooks/use-event/index.ts

Co-authored-by: Marin Atanasov <8436925+tyxla@users.noreply.github.com>
---
 packages/compose/src/hooks/use-event/index.ts | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/compose/src/hooks/use-event/index.ts b/packages/compose/src/hooks/use-event/index.ts
index 40ec73fe35f337..d381bcb595bf65 100644
--- a/packages/compose/src/hooks/use-event/index.ts
+++ b/packages/compose/src/hooks/use-event/index.ts
@@ -18,14 +18,14 @@ export type AnyFunction = ( ...args: any ) => any;
  * @example
  *
  * ```tsx
- * function Component(props) {
- *   const onClick = useEvent(props.onClick);
- *   React.useEffect(() => {
+ * function Component( props ) {
+ *   const onClick = useEvent( props.onClick );
+ *   useEffect( () => {
  *     onClick();
  *     // Won't trigger the effect again when props.onClick is updated.
- *   }, [onClick]);
- *   // Won't re-render Button when props.onClick is updated (if Button is
- *   // wrapped in React.memo).
+ *   }, [ onClick ] );
+ *   // Won't re-render Button when props.onClick is updated (if `Button` is
+ *   // wrapped in `React.memo`).
  *   return <Button onClick={ onClick } />;
  * }
  * ```

From c58e10b4387e779efa021056320d0c489a44c455 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 15:57:53 +0200
Subject: [PATCH 11/30] Sync docs.

---
 packages/compose/README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index f02b0c7bbe4926..3a5328c4de2ca7 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -314,12 +314,12 @@ _Usage_
 ```tsx
 function Component( props ) {
 	const onClick = useEvent( props.onClick );
-	React.useEffect( () => {
+	useEffect( () => {
 		onClick();
 		// Won't trigger the effect again when props.onClick is updated.
 	}, [ onClick ] );
-	// Won't re-render Button when props.onClick is updated (if Button is
-	// wrapped in React.memo).
+	// Won't re-render Button when props.onClick is updated (if `Button` is
+	// wrapped in `React.memo`).
 	return <Button onClick={ onClick } />;
 }
 ```

From 0da2846a36572bd21368629eb5b92c1fe7b978db Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 16:17:59 +0200
Subject: [PATCH 12/30] Avoid redundant resize listener calls.

---
 packages/compose/src/hooks/use-resize-observer/index.tsx | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/packages/compose/src/hooks/use-resize-observer/index.tsx b/packages/compose/src/hooks/use-resize-observer/index.tsx
index 979e8f869ff055..bc5f64dc94a626 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.tsx
+++ b/packages/compose/src/hooks/use-resize-observer/index.tsx
@@ -88,10 +88,8 @@ function ResizeElement( { onResize }: ResizeElementProps ) {
 	const resizeCallbackEvent = useEvent( onResize );
 
 	useObserveElementSize( resizeElementRef, ( entries ) => {
-		for ( const entry of entries ) {
-			const newSize = extractSize( entry );
-			resizeCallbackEvent( newSize );
-		}
+		const newSize = extractSize( entries.at( -1 )! ); // Entries are never empty.
+		resizeCallbackEvent( newSize );
 	} );
 
 	return (

From bc7710032c19f2e21e08103c2348cb32bbae7b0a Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 18:47:57 +0200
Subject: [PATCH 13/30] Switch to structural check.

---
 .../compose/src/hooks/use-observe-element-size/index.ts     | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/compose/src/hooks/use-observe-element-size/index.ts b/packages/compose/src/hooks/use-observe-element-size/index.ts
index 2bddbd49708dbc..035c06691c2dac 100644
--- a/packages/compose/src/hooks/use-observe-element-size/index.ts
+++ b/packages/compose/src/hooks/use-observe-element-size/index.ts
@@ -82,9 +82,9 @@ export default function useObserveElementSize(
 
 	useLayoutEffect( () => {
 		const element =
-			targetElement instanceof HTMLElement
-				? targetElement
-				: targetElement?.current;
+			targetElement && 'current' in targetElement
+				? targetElement?.current
+				: targetElement;
 		if ( element === observedElementRef.current ) {
 			return;
 		}

From 638f551946f4ce0c31d8a0554bc05b59d456f865 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 19:00:23 +0200
Subject: [PATCH 14/30] Improve example.

---
 packages/compose/README.md                    | 20 +++++++++++++++++--
 .../hooks/use-observe-element-size/index.ts   | 20 +++++++++++++++++--
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 3a5328c4de2ca7..e55052d4f34fae 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -493,16 +493,32 @@ Tracks a given element's size and calls `onUpdate` for all of its discrete value
 _Usage_
 
 ```tsx
-const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
+const targetElementRef = useRef< HTMLElement >( null );
 useObserveElementSize(
-	targetElement,
+	targetElementRef,
 	( resizeObserverEntries, element ) => {
 		console.log( 'Resize observer entries:', resizeObserverEntries );
 		console.log( 'Element that was resized:', element );
 	},
 	{ box: 'border-box' }
 );
+<div ref={ targetElementRef } />;
+
+// Alternatively, if the target element can change dynamically, you can pass it
+// directly as a state:
+const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
+useObserveElementSize(
+	targetElement
+	// ...
+);
 <div ref={ setTargetElement } />;
+
+// The element could be obtained through other means, for example:
+useEffect( () => {
+	const element = document.querySelector(
+		`[data-element-id="${ elementId }"]`
+	);
+}, [ elementId ] );
 ```
 
 _Parameters_
diff --git a/packages/compose/src/hooks/use-observe-element-size/index.ts b/packages/compose/src/hooks/use-observe-element-size/index.ts
index 035c06691c2dac..78a60a8479ad05 100644
--- a/packages/compose/src/hooks/use-observe-element-size/index.ts
+++ b/packages/compose/src/hooks/use-observe-element-size/index.ts
@@ -24,16 +24,32 @@ import useEvent from '../use-event';
  * @example
  *
  * ```tsx
- * const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
+ * const targetElementRef = useRef< HTMLElement >( null );
  * useObserveElementSize(
- * 	targetElement,
+ * 	targetElementRef,
  * 	( resizeObserverEntries, element ) => {
  * 		console.log( 'Resize observer entries:', resizeObserverEntries );
  * 		console.log( 'Element that was resized:', element );
  * 	},
  * 	{ box: 'border-box' }
  * );
+ * <div ref={ targetElementRef } />;
+ *
+ * // Alternatively, if the target element can change dynamically, you can pass it
+ * // directly as a state:
+ * const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
+ * useObserveElementSize(
+ * 	targetElement,
+ * 	// ...
+ * );
  * <div ref={ setTargetElement } />;
+ *
+ * // The element could be obtained through other means, for example:
+ * useEffect( () => {
+ * 	const element = document.querySelector(
+ * 		`[data-element-id="${ elementId }"]`
+ * 	);
+ * }, [ elementId ] );
  * ```
  */
 export default function useObserveElementSize(

From 654bac5a5f06a274f575c134f7a8eeefd7b502ba Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 2 Sep 2024 19:02:18 +0200
Subject: [PATCH 15/30] Fix docs.

---
 packages/compose/README.md                                   | 1 +
 packages/compose/src/hooks/use-observe-element-size/index.ts | 1 +
 2 files changed, 2 insertions(+)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index e55052d4f34fae..79287fd07b799e 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -518,6 +518,7 @@ useEffect( () => {
 	const element = document.querySelector(
 		`[data-element-id="${ elementId }"]`
 	);
+	setTargetElement( element );
 }, [ elementId ] );
 ```
 
diff --git a/packages/compose/src/hooks/use-observe-element-size/index.ts b/packages/compose/src/hooks/use-observe-element-size/index.ts
index 78a60a8479ad05..28f87d85248de2 100644
--- a/packages/compose/src/hooks/use-observe-element-size/index.ts
+++ b/packages/compose/src/hooks/use-observe-element-size/index.ts
@@ -49,6 +49,7 @@ import useEvent from '../use-event';
  * 	const element = document.querySelector(
  * 		`[data-element-id="${ elementId }"]`
  * 	);
+ * 	setTargetElement( element );
  * }, [ elementId ] );
  * ```
  */

From 00f53f7e8e110d5044b6153695f9c75a224711fa Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Tue, 3 Sep 2024 14:05:01 +0200
Subject: [PATCH 16/30] Make `useObserveElementSize` generic.

---
 packages/compose/README.md                                | 4 ++--
 .../compose/src/hooks/use-observe-element-size/index.ts   | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 79287fd07b799e..2b7f6ad188d3cb 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -524,8 +524,8 @@ useEffect( () => {
 
 _Parameters_
 
--   _targetElement_ `HTMLElement | undefined | null | RefObject< HTMLElement >`: The target element to observe. It can be changed dynamically. Alternatively, a ref containing the target element can be passed. However, any updates to the ref will be ignored.
--   _onUpdate_ `( resizeObserverEntries: ResizeObserverEntry[], element: HTMLElement ) => void`: Callback that will be called when the element is resized. It is passed the list of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects passed to the `ResizeObserver.observe` callback internally, and the element being tracked at the time of this update.
+-   _targetElement_ `T | undefined | null | RefObject< T >`: The target element to observe. It can be changed dynamically. Alternatively, a ref containing the target element can be passed. However, any updates to the ref will be ignored.
+-   _onUpdate_ `( resizeObserverEntries: ResizeObserverEntry[], element: T ) => void`: Callback that will be called when the element is resized. It is passed the list of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects passed to the `ResizeObserver.observe` callback internally, and the element being tracked at the time of this update.
 -   _resizeObserverOptions_ `ResizeObserverOptions`: Options to pass to `ResizeObserver.observe` when called internally. Updating this option will not cause the observer to be re-created, and it will only take effect if a new element is observed.
 
 ### usePrevious
diff --git a/packages/compose/src/hooks/use-observe-element-size/index.ts b/packages/compose/src/hooks/use-observe-element-size/index.ts
index 28f87d85248de2..8c8d85d8a586a4 100644
--- a/packages/compose/src/hooks/use-observe-element-size/index.ts
+++ b/packages/compose/src/hooks/use-observe-element-size/index.ts
@@ -53,14 +53,14 @@ import useEvent from '../use-event';
  * }, [ elementId ] );
  * ```
  */
-export default function useObserveElementSize(
+export default function useObserveElementSize< T extends HTMLElement >(
 	/**
 	 * The target element to observe. It can be changed dynamically.
 	 *
 	 * Alternatively, a ref containing the target element can be passed. However, any updates
 	 * to the ref will be ignored.
 	 */
-	targetElement: HTMLElement | undefined | null | RefObject< HTMLElement >,
+	targetElement: T | undefined | null | RefObject< T >,
 	/**
 	 * Callback that will be called when the element is resized.
 	 */
@@ -74,7 +74,7 @@ export default function useObserveElementSize(
 		/**
 		 * The element being tracked at the time of this update.
 		 */
-		element: HTMLElement
+		element: T
 	) => void,
 	/**
 	 * Options to pass to `ResizeObserver.observe` when called internally.
@@ -86,7 +86,7 @@ export default function useObserveElementSize(
 ) {
 	const onUpdateEvent = useEvent( onUpdate );
 
-	const observedElementRef = useRef< HTMLElement | null >();
+	const observedElementRef = useRef< T | null >();
 	const resizeObserverRef = useRef< ResizeObserver >();
 
 	// Options are passed on `.observe` once and never updated, so we store them

From b6dc4f43d119e0c5128b356c0be90ad2a457a003 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Thu, 5 Sep 2024 17:31:21 +0200
Subject: [PATCH 17/30] New API that returns a ref.

---
 packages/compose/README.md                    |  22 ++--
 .../hooks/use-observe-element-size/index.ts   | 110 +++++++++---------
 .../src/hooks/use-resize-observer/index.tsx   |   8 +-
 3 files changed, 68 insertions(+), 72 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 2b7f6ad188d3cb..38f91d0d4e5e23 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -488,28 +488,28 @@ _Returns_
 
 ### useObserveElementSize
 
-Tracks a given element's size and calls `onUpdate` for all of its discrete values using a `ResizeObserver`. The element can change dynamically. Alternatively, a ref containing the target element can be passed. However, any updates to the ref will be ignored.
+Tracks a given element's size and calls `onUpdate` for all of its discrete values using a `ResizeObserver`. Pass the returned ref to the element or pass the element to the `targetElement` option directly.
 
 _Usage_
 
 ```tsx
-const targetElementRef = useRef< HTMLElement >( null );
-useObserveElementSize(
-	targetElementRef,
+const targetElementRef = useObserveElementSize(
 	( resizeObserverEntries, element ) => {
 		console.log( 'Resize observer entries:', resizeObserverEntries );
-		console.log( 'Element that was resized:', element );
+		console.log( 'Element that was measured:', element );
 	},
 	{ box: 'border-box' }
 );
 <div ref={ targetElementRef } />;
 
-// Alternatively, if the target element can change dynamically, you can pass it
-// directly as a state:
+// Alternatively, pass the element directly as an argument:
 const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
 useObserveElementSize(
-	targetElement
 	// ...
+	{
+		targetElement,
+		// ...
+	}
 );
 <div ref={ setTargetElement } />;
 
@@ -524,9 +524,9 @@ useEffect( () => {
 
 _Parameters_
 
--   _targetElement_ `T | undefined | null | RefObject< T >`: The target element to observe. It can be changed dynamically. Alternatively, a ref containing the target element can be passed. However, any updates to the ref will be ignored.
--   _onUpdate_ `( resizeObserverEntries: ResizeObserverEntry[], element: T ) => void`: Callback that will be called when the element is resized. It is passed the list of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects passed to the `ResizeObserver.observe` callback internally, and the element being tracked at the time of this update.
--   _resizeObserverOptions_ `ResizeObserverOptions`: Options to pass to `ResizeObserver.observe` when called internally. Updating this option will not cause the observer to be re-created, and it will only take effect if a new element is observed.
+-   _onUpdate_ `( resizeObserverEntries: ResizeObserverEntry[], element: T ) => void`: Callback that will be called when the element is measured (initially and after resizes).
+-   _resizeObserverOptions_ `ObserveElementSizeOptions< T >`: Options that, with the exception of `targetElement`, will be passed to `ResizeObserver.observe` when called internally. Updating them will not cause the observer to be re-created, and they will only take effect if a new element is observed.
+-   _resizeObserverOptions.targetElement_ `ObserveElementSizeOptions< T >[ 'targetElement' ]`: The target element to observe. This parameter is an alternative to the returned ref. The element can be changed dynamically.
 
 ### usePrevious
 
diff --git a/packages/compose/src/hooks/use-observe-element-size/index.ts b/packages/compose/src/hooks/use-observe-element-size/index.ts
index 8c8d85d8a586a4..1bf2409665061c 100644
--- a/packages/compose/src/hooks/use-observe-element-size/index.ts
+++ b/packages/compose/src/hooks/use-observe-element-size/index.ts
@@ -1,46 +1,47 @@
-/**
- * External dependencies
- */
-import type { RefObject } from 'react';
 /**
  * WordPress dependencies
  */
-import { useRef, useEffect, useLayoutEffect } from '@wordpress/element';
+import { useRef, useLayoutEffect } from '@wordpress/element';
 /**
  * Internal dependencies
  */
 import useEvent from '../use-event';
 
+/** `useObserveElementSize` options. */
+export type ObserveElementSizeOptions< T extends HTMLElement > =
+	ResizeObserverOptions & {
+		/**
+		 * The target element to observe. This parameter is an alternative to the
+		 * returned ref. The element can be changed dynamically.
+		 */
+		targetElement?: T | undefined | null;
+	};
+
 /**
  * Tracks a given element's size and calls `onUpdate` for all of its discrete
- * values using a `ResizeObserver`. The element can change dynamically. Alternatively,
- * a ref containing the target element can be passed. However, any updates to the ref
- * will be ignored.
- *
- * @param targetElement         The target element to observe. It can be changed dynamically. Alternatively, a ref containing the target element can be passed. However, any updates to the ref will be ignored.
- * @param onUpdate              Callback that will be called when the element is resized. It is passed the list of [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects passed to the `ResizeObserver.observe` callback internally, and the element being tracked at the time of this update.
- * @param resizeObserverOptions Options to pass to `ResizeObserver.observe` when called internally. Updating this option will not cause the observer to be re-created, and it will only take effect if a new element is observed.
+ * values using a `ResizeObserver`. Pass the returned ref to the element or
+ * pass the element to the `targetElement` option directly.
  *
  * @example
  *
  * ```tsx
- * const targetElementRef = useRef< HTMLElement >( null );
- * useObserveElementSize(
- * 	targetElementRef,
+ * const targetElementRef = useObserveElementSize(
  * 	( resizeObserverEntries, element ) => {
  * 		console.log( 'Resize observer entries:', resizeObserverEntries );
- * 		console.log( 'Element that was resized:', element );
+ * 		console.log( 'Element that was measured:', element );
  * 	},
  * 	{ box: 'border-box' }
  * );
  * <div ref={ targetElementRef } />;
  *
- * // Alternatively, if the target element can change dynamically, you can pass it
- * // directly as a state:
+ * // Alternatively, pass the element directly as an argument:
  * const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
  * useObserveElementSize(
- * 	targetElement,
  * 	// ...
+ * 	{
+ * 		targetElement,
+ * 		// ...
+ * 	}
  * );
  * <div ref={ setTargetElement } />;
  *
@@ -52,17 +53,15 @@ import useEvent from '../use-event';
  * 	setTargetElement( element );
  * }, [ elementId ] );
  * ```
+ *
+ * @param onUpdate                            Callback that will be called when the element is measured (initially and after resizes).
+ * @param resizeObserverOptions               Options that, with the exception of `targetElement`, will be passed to `ResizeObserver.observe` when called internally. Updating them will not cause the observer to be re-created, and they will only take effect if a new element is observed.
+ * @param resizeObserverOptions.targetElement The target element to observe. This parameter is an alternative to the returned ref. The element can be changed dynamically.
  */
 export default function useObserveElementSize< T extends HTMLElement >(
 	/**
-	 * The target element to observe. It can be changed dynamically.
-	 *
-	 * Alternatively, a ref containing the target element can be passed. However, any updates
-	 * to the ref will be ignored.
-	 */
-	targetElement: T | undefined | null | RefObject< T >,
-	/**
-	 * Callback that will be called when the element is resized.
+	 * Callback that will be called when the element is measured (initially and
+	 * after resizes).
 	 */
 	onUpdate: (
 		/**
@@ -77,38 +76,28 @@ export default function useObserveElementSize< T extends HTMLElement >(
 		element: T
 	) => void,
 	/**
-	 * Options to pass to `ResizeObserver.observe` when called internally.
+	 * Options that, with the exception of `targetElement`, will be passed to
+	 * `ResizeObserver.observe` when called internally.
 	 *
-	 * Updating this option will not cause the observer to be re-created, and it
-	 * will only take effect if a new element is observed.
+	 * Updating them will not cause the observer to be re-created, and they will
+	 * only take effect if a new element is observed.
 	 */
-	resizeObserverOptions?: ResizeObserverOptions
+	{
+		targetElement,
+		...resizeObserverOptions
+	}: ObserveElementSizeOptions< T > = {}
 ) {
 	const onUpdateEvent = useEvent( onUpdate );
 
 	const observedElementRef = useRef< T | null >();
 	const resizeObserverRef = useRef< ResizeObserver >();
-
-	// Options are passed on `.observe` once and never updated, so we store them
-	// in an up-to-date ref to avoid unnecessary cycles of the effect due to
-	// unstable option objects such as inlined literals.
-	const resizeObserverOptionsRef = useRef( resizeObserverOptions );
-	useEffect( () => {
-		resizeObserverOptionsRef.current = resizeObserverOptions;
-	}, [ resizeObserverOptions ] );
-
-	useLayoutEffect( () => {
-		const element =
-			targetElement && 'current' in targetElement
-				? targetElement?.current
-				: targetElement;
+	const setElement = useEvent( ( element?: T | null | undefined ) => {
 		if ( element === observedElementRef.current ) {
 			return;
 		}
-
 		observedElementRef.current = element;
 
-		// Set up a ResizeObserver.
+		// Set up `ResizeObserver`.
 		if ( ! resizeObserverRef.current ) {
 			resizeObserverRef.current = new ResizeObserver( ( entries ) => {
 				if ( observedElementRef.current ) {
@@ -118,16 +107,27 @@ export default function useObserveElementSize< T extends HTMLElement >(
 		}
 		const { current: resizeObserver } = resizeObserverRef;
 
+		// Unobserve previous element.
+		if ( observedElementRef.current ) {
+			resizeObserver.unobserve( observedElementRef.current );
+		}
+
 		// Observe new element.
 		if ( element ) {
-			resizeObserver.observe( element, resizeObserverOptionsRef.current );
+			resizeObserver.observe( element, resizeObserverOptions );
+		}
+	} );
+
+	// Handle `targetElement` option.
+	const isArgumentRef = useRef( Boolean( targetElement ) );
+	useLayoutEffect( () => {
+		if ( targetElement || isArgumentRef.current ) {
+			isArgumentRef.current = true;
+			setElement( targetElement );
+			return setElement;
 		}
+		return undefined;
+	}, [ setElement, targetElement ] );
 
-		return () => {
-			// Unobserve previous element.
-			if ( observedElementRef.current ) {
-				resizeObserver.unobserve( observedElementRef.current );
-			}
-		};
-	}, [ onUpdateEvent, targetElement ] );
+	return setElement;
 }
diff --git a/packages/compose/src/hooks/use-resize-observer/index.tsx b/packages/compose/src/hooks/use-resize-observer/index.tsx
index bc5f64dc94a626..27cc75f5b1a59a 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.tsx
+++ b/packages/compose/src/hooks/use-resize-observer/index.tsx
@@ -10,7 +10,6 @@ import { useCallback, useRef, useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import useEvent from '../use-event';
 import useObserveElementSize from '../use-observe-element-size';
 
 type ObservedSize = {
@@ -84,12 +83,9 @@ type ResizeElementProps = {
 };
 
 function ResizeElement( { onResize }: ResizeElementProps ) {
-	const resizeElementRef = useRef< HTMLDivElement >( null );
-	const resizeCallbackEvent = useEvent( onResize );
-
-	useObserveElementSize( resizeElementRef, ( entries ) => {
+	const resizeElementRef = useObserveElementSize( ( entries ) => {
 		const newSize = extractSize( entries.at( -1 )! ); // Entries are never empty.
-		resizeCallbackEvent( newSize );
+		onResize( newSize );
 	} );
 
 	return (

From 74c4a00d3887c1e48c080e205ccd8650f3db1d48 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Thu, 5 Sep 2024 22:01:07 +0200
Subject: [PATCH 18/30] Make utility private for now.

---
 packages/compose/README.md    | 42 -----------------------------------
 packages/compose/src/index.js |  1 -
 2 files changed, 43 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 38f91d0d4e5e23..32dbbf73903868 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -486,48 +486,6 @@ _Returns_
 
 -   `V | undefined`: The value corresponding to the map key requested.
 
-### useObserveElementSize
-
-Tracks a given element's size and calls `onUpdate` for all of its discrete values using a `ResizeObserver`. Pass the returned ref to the element or pass the element to the `targetElement` option directly.
-
-_Usage_
-
-```tsx
-const targetElementRef = useObserveElementSize(
-	( resizeObserverEntries, element ) => {
-		console.log( 'Resize observer entries:', resizeObserverEntries );
-		console.log( 'Element that was measured:', element );
-	},
-	{ box: 'border-box' }
-);
-<div ref={ targetElementRef } />;
-
-// Alternatively, pass the element directly as an argument:
-const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
-useObserveElementSize(
-	// ...
-	{
-		targetElement,
-		// ...
-	}
-);
-<div ref={ setTargetElement } />;
-
-// The element could be obtained through other means, for example:
-useEffect( () => {
-	const element = document.querySelector(
-		`[data-element-id="${ elementId }"]`
-	);
-	setTargetElement( element );
-}, [ elementId ] );
-```
-
-_Parameters_
-
--   _onUpdate_ `( resizeObserverEntries: ResizeObserverEntry[], element: T ) => void`: Callback that will be called when the element is measured (initially and after resizes).
--   _resizeObserverOptions_ `ObserveElementSizeOptions< T >`: Options that, with the exception of `targetElement`, will be passed to `ResizeObserver.observe` when called internally. Updating them will not cause the observer to be re-created, and they will only take effect if a new element is observed.
--   _resizeObserverOptions.targetElement_ `ObserveElementSizeOptions< T >[ 'targetElement' ]`: The target element to observe. This parameter is an alternative to the returned ref. The element can be changed dynamically.
-
 ### usePrevious
 
 Use something's value from the previous render. Based on <https://usehooks.com/usePrevious/>.
diff --git a/packages/compose/src/index.js b/packages/compose/src/index.js
index c879f45f6a537e..29a9aa61737440 100644
--- a/packages/compose/src/index.js
+++ b/packages/compose/src/index.js
@@ -34,7 +34,6 @@ export { default as useInstanceId } from './hooks/use-instance-id';
 export { default as useIsomorphicLayoutEffect } from './hooks/use-isomorphic-layout-effect';
 export { default as useKeyboardShortcut } from './hooks/use-keyboard-shortcut';
 export { default as useMediaQuery } from './hooks/use-media-query';
-export { default as useObserveElementSize } from './hooks/use-observe-element-size';
 export { default as usePrevious } from './hooks/use-previous';
 export { default as useReducedMotion } from './hooks/use-reduced-motion';
 export { default as useStateWithHistory } from './hooks/use-state-with-history';

From 4fb82b96a8db3af1ac16c17d8518d5f65241d65e Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Thu, 5 Sep 2024 22:03:22 +0200
Subject: [PATCH 19/30] Mark legacy `useResizeObserver` as such.

---
 .../index.native.js                                             | 0
 .../index.tsx                                                   | 0
 .../test/index.native.js                                        | 0
 packages/compose/src/index.js                                   | 2 +-
 4 files changed, 1 insertion(+), 1 deletion(-)
 rename packages/compose/src/hooks/{use-resize-observer => _legacy-use-resize-observer}/index.native.js (100%)
 rename packages/compose/src/hooks/{use-resize-observer => _legacy-use-resize-observer}/index.tsx (100%)
 rename packages/compose/src/hooks/{use-resize-observer => _legacy-use-resize-observer}/test/index.native.js (100%)

diff --git a/packages/compose/src/hooks/use-resize-observer/index.native.js b/packages/compose/src/hooks/_legacy-use-resize-observer/index.native.js
similarity index 100%
rename from packages/compose/src/hooks/use-resize-observer/index.native.js
rename to packages/compose/src/hooks/_legacy-use-resize-observer/index.native.js
diff --git a/packages/compose/src/hooks/use-resize-observer/index.tsx b/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
similarity index 100%
rename from packages/compose/src/hooks/use-resize-observer/index.tsx
rename to packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
diff --git a/packages/compose/src/hooks/use-resize-observer/test/index.native.js b/packages/compose/src/hooks/_legacy-use-resize-observer/test/index.native.js
similarity index 100%
rename from packages/compose/src/hooks/use-resize-observer/test/index.native.js
rename to packages/compose/src/hooks/_legacy-use-resize-observer/test/index.native.js
diff --git a/packages/compose/src/index.js b/packages/compose/src/index.js
index 29a9aa61737440..51cc1b46b33094 100644
--- a/packages/compose/src/index.js
+++ b/packages/compose/src/index.js
@@ -38,7 +38,7 @@ export { default as usePrevious } from './hooks/use-previous';
 export { default as useReducedMotion } from './hooks/use-reduced-motion';
 export { default as useStateWithHistory } from './hooks/use-state-with-history';
 export { default as useViewportMatch } from './hooks/use-viewport-match';
-export { default as useResizeObserver } from './hooks/use-resize-observer';
+export { default as useResizeObserver } from './hooks/_legacy-use-resize-observer';
 export { default as useAsyncList } from './hooks/use-async-list';
 export { default as useWarnOnChange } from './hooks/use-warn-on-change';
 export { default as useDebounce } from './hooks/use-debounce';

From a38114045f34d0067a87e7d307546c483db486ff Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Thu, 5 Sep 2024 22:11:52 +0200
Subject: [PATCH 20/30] Rename `useObserveElementSize` to `useResizeObserver`.

---
 .../src/hooks/_legacy-use-resize-observer/index.tsx      | 9 ++++++---
 .../index.ts                                             | 8 ++++----
 2 files changed, 10 insertions(+), 7 deletions(-)
 rename packages/compose/src/hooks/{use-observe-element-size => use-resize-observer}/index.ts (95%)

diff --git a/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx b/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
index 27cc75f5b1a59a..d5917380656c32 100644
--- a/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
+++ b/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
@@ -10,7 +10,7 @@ import { useCallback, useRef, useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import useObserveElementSize from '../use-observe-element-size';
+import useResizeObserver from '../use-resize-observer';
 
 type ObservedSize = {
 	width: number | null;
@@ -83,7 +83,7 @@ type ResizeElementProps = {
 };
 
 function ResizeElement( { onResize }: ResizeElementProps ) {
-	const resizeElementRef = useObserveElementSize( ( entries ) => {
+	const resizeElementRef = useResizeObserver( ( entries ) => {
 		const newSize = extractSize( entries.at( -1 )! ); // Entries are never empty.
 		onResize( newSize );
 	} );
@@ -122,7 +122,10 @@ const NULL_SIZE: ObservedSize = { width: null, height: null };
  * };
  * ```
  */
-export default function useResizeObserver(): [ ReactElement, ObservedSize ] {
+export default function useLegacyResizeObserver(): [
+	ReactElement,
+	ObservedSize,
+] {
 	const [ size, setSize ] = useState( NULL_SIZE );
 
 	// Using a ref to track the previous width / height to avoid unnecessary renders.
diff --git a/packages/compose/src/hooks/use-observe-element-size/index.ts b/packages/compose/src/hooks/use-resize-observer/index.ts
similarity index 95%
rename from packages/compose/src/hooks/use-observe-element-size/index.ts
rename to packages/compose/src/hooks/use-resize-observer/index.ts
index 1bf2409665061c..76d13ce640b5c9 100644
--- a/packages/compose/src/hooks/use-observe-element-size/index.ts
+++ b/packages/compose/src/hooks/use-resize-observer/index.ts
@@ -7,7 +7,7 @@ import { useRef, useLayoutEffect } from '@wordpress/element';
  */
 import useEvent from '../use-event';
 
-/** `useObserveElementSize` options. */
+/** `useResizeObserver` options. */
 export type ObserveElementSizeOptions< T extends HTMLElement > =
 	ResizeObserverOptions & {
 		/**
@@ -25,7 +25,7 @@ export type ObserveElementSizeOptions< T extends HTMLElement > =
  * @example
  *
  * ```tsx
- * const targetElementRef = useObserveElementSize(
+ * const targetElementRef = useResizeObserver(
  * 	( resizeObserverEntries, element ) => {
  * 		console.log( 'Resize observer entries:', resizeObserverEntries );
  * 		console.log( 'Element that was measured:', element );
@@ -36,7 +36,7 @@ export type ObserveElementSizeOptions< T extends HTMLElement > =
  *
  * // Alternatively, pass the element directly as an argument:
  * const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
- * useObserveElementSize(
+ * useResizeObserver(
  * 	// ...
  * 	{
  * 		targetElement,
@@ -58,7 +58,7 @@ export type ObserveElementSizeOptions< T extends HTMLElement > =
  * @param resizeObserverOptions               Options that, with the exception of `targetElement`, will be passed to `ResizeObserver.observe` when called internally. Updating them will not cause the observer to be re-created, and they will only take effect if a new element is observed.
  * @param resizeObserverOptions.targetElement The target element to observe. This parameter is an alternative to the returned ref. The element can be changed dynamically.
  */
-export default function useObserveElementSize< T extends HTMLElement >(
+export default function useResizeObserver< T extends HTMLElement >(
 	/**
 	 * Callback that will be called when the element is measured (initially and
 	 * after resizes).

From 7b4eccecbb23d71bf21abe1925a778681b3ab21c Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Thu, 5 Sep 2024 22:14:19 +0200
Subject: [PATCH 21/30] Add return type.

---
 packages/compose/src/hooks/use-resize-observer/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/compose/src/hooks/use-resize-observer/index.ts b/packages/compose/src/hooks/use-resize-observer/index.ts
index 76d13ce640b5c9..2f01eaeab2717f 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.ts
+++ b/packages/compose/src/hooks/use-resize-observer/index.ts
@@ -86,7 +86,7 @@ export default function useResizeObserver< T extends HTMLElement >(
 		targetElement,
 		...resizeObserverOptions
 	}: ObserveElementSizeOptions< T > = {}
-) {
+): ( element?: T | null | undefined ) => void {
 	const onUpdateEvent = useEvent( onUpdate );
 
 	const observedElementRef = useRef< T | null >();

From f42603c152cde7929cbcd461b3510daae499643c Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Thu, 5 Sep 2024 22:16:39 +0200
Subject: [PATCH 22/30] Add signature as overload.

---
 .../compose/src/hooks/use-resize-observer/index.ts | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/packages/compose/src/hooks/use-resize-observer/index.ts b/packages/compose/src/hooks/use-resize-observer/index.ts
index 2f01eaeab2717f..9a31bc5bfea945 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.ts
+++ b/packages/compose/src/hooks/use-resize-observer/index.ts
@@ -54,9 +54,9 @@ export type ObserveElementSizeOptions< T extends HTMLElement > =
  * }, [ elementId ] );
  * ```
  *
- * @param onUpdate                            Callback that will be called when the element is measured (initially and after resizes).
- * @param resizeObserverOptions               Options that, with the exception of `targetElement`, will be passed to `ResizeObserver.observe` when called internally. Updating them will not cause the observer to be re-created, and they will only take effect if a new element is observed.
- * @param resizeObserverOptions.targetElement The target element to observe. This parameter is an alternative to the returned ref. The element can be changed dynamically.
+ * @param onUpdate              Callback that will be called when the element is measured (initially and after resizes).
+ * @param options               Options that, with the exception of `targetElement`, will be passed to `ResizeObserver.observe` when called internally. Updating them will not cause the observer to be re-created, and they will only take effect if a new element is observed.
+ * @param options.targetElement The target element to observe. This parameter is an alternative to the returned ref. The element can be changed dynamically.
  */
 export default function useResizeObserver< T extends HTMLElement >(
 	/**
@@ -82,6 +82,14 @@ export default function useResizeObserver< T extends HTMLElement >(
 	 * Updating them will not cause the observer to be re-created, and they will
 	 * only take effect if a new element is observed.
 	 */
+	options?: ObserveElementSizeOptions< T >
+): ( element?: T | null | undefined ) => void;
+
+export default function useResizeObserver< T extends HTMLElement >(
+	onUpdate: (
+		resizeObserverEntries: ResizeObserverEntry[],
+		element: T
+	) => void,
 	{
 		targetElement,
 		...resizeObserverOptions

From 63deb161015cdf440c43f4bae67bc4a134bc8953 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Thu, 5 Sep 2024 22:23:48 +0200
Subject: [PATCH 23/30] Add support for legacy API.

---
 .../_legacy-use-resize-observer/index.tsx     |  2 +-
 .../src/hooks/use-resize-observer/index.ts    | 45 +++++++++++++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx b/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
index d5917380656c32..ee4b5f5bcd6bd2 100644
--- a/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
+++ b/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
@@ -12,7 +12,7 @@ import { useCallback, useRef, useState } from '@wordpress/element';
  */
 import useResizeObserver from '../use-resize-observer';
 
-type ObservedSize = {
+export type ObservedSize = {
 	width: number | null;
 	height: number | null;
 };
diff --git a/packages/compose/src/hooks/use-resize-observer/index.ts b/packages/compose/src/hooks/use-resize-observer/index.ts
index 9a31bc5bfea945..b83f31c0df14c3 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.ts
+++ b/packages/compose/src/hooks/use-resize-observer/index.ts
@@ -6,6 +6,12 @@ import { useRef, useLayoutEffect } from '@wordpress/element';
  * Internal dependencies
  */
 import useEvent from '../use-event';
+import type { ObservedSize } from '../_legacy-use-resize-observer';
+import _useLegacyResizeObserver from '../_legacy-use-resize-observer';
+/**
+ * External dependencies
+ */
+import type { ReactElement } from 'react';
 
 /** `useResizeObserver` options. */
 export type ObserveElementSizeOptions< T extends HTMLElement > =
@@ -85,7 +91,46 @@ export default function useResizeObserver< T extends HTMLElement >(
 	options?: ObserveElementSizeOptions< T >
 ): ( element?: T | null | undefined ) => void;
 
+/**
+ * **This is a legacy API and should not be used.**
+ *
+ * @deprecated Use the other `useResizeObserver` API instead: `const ref = useResizeObserver( ( entries ) => { ... } )`.
+ *
+ * Hook which allows to listen to the resize event of any target element when it changes size.
+ * _Note: `useResizeObserver` will report `null` sizes until after first render.
+ *
+ * @example
+ *
+ * ```js
+ * const App = () => {
+ * 	const [ resizeListener, sizes ] = useResizeObserver();
+ *
+ * 	return (
+ * 		<div>
+ * 			{ resizeListener }
+ * 			Your content here
+ * 		</div>
+ * 	);
+ * };
+ * ```
+ */
+export default function useResizeObserver(): [ ReactElement, ObservedSize ];
+
 export default function useResizeObserver< T extends HTMLElement >(
+	onUpdate?: (
+		resizeObserverEntries: ResizeObserverEntry[],
+		element: T
+	) => void,
+	options: ObserveElementSizeOptions< T > = {}
+):
+	| ( ( element?: T | null | undefined ) => void )
+	| [ ReactElement, ObservedSize ] {
+	return onUpdate
+		? _useResizeObserver( onUpdate, options )
+		: _useLegacyResizeObserver();
+}
+
+function _useResizeObserver< T extends HTMLElement >(
 	onUpdate: (
 		resizeObserverEntries: ResizeObserverEntry[],
 		element: T

From 30a07f0ee98f5cda514615d836d4661dd887cf6b Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Thu, 5 Sep 2024 22:24:45 +0200
Subject: [PATCH 24/30] Move into subdirectory.

---
 .../_legacy}/index.native.js                                  | 0
 .../_legacy}/index.tsx                                        | 2 +-
 .../_legacy}/test/index.native.js                             | 2 +-
 packages/compose/src/hooks/use-resize-observer/index.ts       | 4 ++--
 packages/compose/src/index.js                                 | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)
 rename packages/compose/src/hooks/{_legacy-use-resize-observer => use-resize-observer/_legacy}/index.native.js (100%)
 rename packages/compose/src/hooks/{_legacy-use-resize-observer => use-resize-observer/_legacy}/index.tsx (98%)
 rename packages/compose/src/hooks/{_legacy-use-resize-observer => use-resize-observer/_legacy}/test/index.native.js (96%)

diff --git a/packages/compose/src/hooks/_legacy-use-resize-observer/index.native.js b/packages/compose/src/hooks/use-resize-observer/_legacy/index.native.js
similarity index 100%
rename from packages/compose/src/hooks/_legacy-use-resize-observer/index.native.js
rename to packages/compose/src/hooks/use-resize-observer/_legacy/index.native.js
diff --git a/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx b/packages/compose/src/hooks/use-resize-observer/_legacy/index.tsx
similarity index 98%
rename from packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
rename to packages/compose/src/hooks/use-resize-observer/_legacy/index.tsx
index ee4b5f5bcd6bd2..e1f2be80e793ce 100644
--- a/packages/compose/src/hooks/_legacy-use-resize-observer/index.tsx
+++ b/packages/compose/src/hooks/use-resize-observer/_legacy/index.tsx
@@ -10,7 +10,7 @@ import { useCallback, useRef, useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import useResizeObserver from '../use-resize-observer';
+import useResizeObserver from '..';
 
 export type ObservedSize = {
 	width: number | null;
diff --git a/packages/compose/src/hooks/_legacy-use-resize-observer/test/index.native.js b/packages/compose/src/hooks/use-resize-observer/_legacy/test/index.native.js
similarity index 96%
rename from packages/compose/src/hooks/_legacy-use-resize-observer/test/index.native.js
rename to packages/compose/src/hooks/use-resize-observer/_legacy/test/index.native.js
index 6370b3f9cd054b..8ff90d0c778fd4 100644
--- a/packages/compose/src/hooks/_legacy-use-resize-observer/test/index.native.js
+++ b/packages/compose/src/hooks/use-resize-observer/_legacy/test/index.native.js
@@ -7,7 +7,7 @@ import { View } from 'react-native';
 /**
  * Internal dependencies
  */
-import useResizeObserver from '../';
+import useResizeObserver from '..';
 
 const TestComponent = ( { onLayout } ) => {
 	const [ resizeObserver, sizes ] = useResizeObserver();
diff --git a/packages/compose/src/hooks/use-resize-observer/index.ts b/packages/compose/src/hooks/use-resize-observer/index.ts
index b83f31c0df14c3..da00f8aafa2cb4 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.ts
+++ b/packages/compose/src/hooks/use-resize-observer/index.ts
@@ -6,8 +6,8 @@ import { useRef, useLayoutEffect } from '@wordpress/element';
  * Internal dependencies
  */
 import useEvent from '../use-event';
-import type { ObservedSize } from '../_legacy-use-resize-observer';
-import _useLegacyResizeObserver from '../_legacy-use-resize-observer';
+import type { ObservedSize } from './_legacy';
+import _useLegacyResizeObserver from './_legacy';
 /**
  * External dependencies
  */
diff --git a/packages/compose/src/index.js b/packages/compose/src/index.js
index 51cc1b46b33094..388fbe44048c3d 100644
--- a/packages/compose/src/index.js
+++ b/packages/compose/src/index.js
@@ -38,7 +38,7 @@ export { default as usePrevious } from './hooks/use-previous';
 export { default as useReducedMotion } from './hooks/use-reduced-motion';
 export { default as useStateWithHistory } from './hooks/use-state-with-history';
 export { default as useViewportMatch } from './hooks/use-viewport-match';
-export { default as useResizeObserver } from './hooks/_legacy-use-resize-observer';
+export { default as useResizeObserver } from './hooks/use-resize-observer/_legacy';
 export { default as useAsyncList } from './hooks/use-async-list';
 export { default as useWarnOnChange } from './hooks/use-warn-on-change';
 export { default as useDebounce } from './hooks/use-debounce';

From e57cc0e855069bdbc2821a39e31a75c28429c9c2 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Thu, 5 Sep 2024 22:25:43 +0200
Subject: [PATCH 25/30] Minor import fix.

---
 .../compose/src/hooks/use-resize-observer/_legacy/index.tsx     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/compose/src/hooks/use-resize-observer/_legacy/index.tsx b/packages/compose/src/hooks/use-resize-observer/_legacy/index.tsx
index e1f2be80e793ce..b44bd841964164 100644
--- a/packages/compose/src/hooks/use-resize-observer/_legacy/index.tsx
+++ b/packages/compose/src/hooks/use-resize-observer/_legacy/index.tsx
@@ -10,7 +10,7 @@ import { useCallback, useRef, useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import useResizeObserver from '..';
+import useResizeObserver from '../index';
 
 export type ObservedSize = {
 	width: number | null;

From 15eaebc1aee71dd6770cb68f264c59a810b36685 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Fri, 6 Sep 2024 01:30:56 +0200
Subject: [PATCH 26/30] Fix docgen to support overloads (will pick up the first
 function signature).

---
 packages/docgen/lib/get-type-annotation.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/docgen/lib/get-type-annotation.js b/packages/docgen/lib/get-type-annotation.js
index b844c86ef7958a..5e72724952f29e 100644
--- a/packages/docgen/lib/get-type-annotation.js
+++ b/packages/docgen/lib/get-type-annotation.js
@@ -401,6 +401,10 @@ function getTypeAnnotation( typeAnnotation ) {
  *                        TODO: Remove the special-casing here once we're able to infer the types from TypeScript itself.
  */
 function unwrapWrappedSelectors( token ) {
+	if ( babelTypes.isTSDeclareFunction( token ) ) {
+		return token;
+	}
+
 	if ( babelTypes.isFunctionDeclaration( token ) ) {
 		return token;
 	}

From 3387a0a773b163293f0ea016274af6e3ce66c366 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Fri, 6 Sep 2024 02:06:13 +0200
Subject: [PATCH 27/30] Replace legacy utility with the new one.

---
 packages/compose/README.md    | 43 +++++++++++++++++++++++++++--------
 packages/compose/src/index.js |  2 +-
 2 files changed, 34 insertions(+), 11 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 32dbbf73903868..6164aaecc311f7 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -523,23 +523,46 @@ _Returns_
 
 ### useResizeObserver
 
-Hook which allows to listen to the resize event of any target element when it changes size. \_Note: `useResizeObserver` will report `null` sizes until after first render.
+Tracks a given element's size and calls `onUpdate` for all of its discrete values using a `ResizeObserver`. Pass the returned ref to the element or pass the element to the `targetElement` option directly.
 
 _Usage_
 
-```js
-const App = () => {
-	const [ resizeListener, sizes ] = useResizeObserver();
+```tsx
+const targetElementRef = useResizeObserver(
+	( resizeObserverEntries, element ) => {
+		console.log( 'Resize observer entries:', resizeObserverEntries );
+		console.log( 'Element that was measured:', element );
+	},
+	{ box: 'border-box' }
+);
+<div ref={ targetElementRef } />;
+
+// Alternatively, pass the element directly as an argument:
+const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
+useResizeObserver(
+	// ...
+	{
+		targetElement,
+		// ...
+	}
+);
+<div ref={ setTargetElement } />;
 
-	return (
-		<div>
-			{ resizeListener }
-			Your content here
-		</div>
+// The element could be obtained through other means, for example:
+useEffect( () => {
+	const element = document.querySelector(
+		`[data-element-id="${ elementId }"]`
 	);
-};
+	setTargetElement( element );
+}, [ elementId ] );
 ```
 
+_Parameters_
+
+-   _onUpdate_ `( resizeObserverEntries: ResizeObserverEntry[], element: T ) => void`: Callback that will be called when the element is measured (initially and after resizes).
+-   _options_ `ObserveElementSizeOptions< T >`: Options that, with the exception of `targetElement`, will be passed to `ResizeObserver.observe` when called internally. Updating them will not cause the observer to be re-created, and they will only take effect if a new element is observed.
+-   _options.targetElement_ `ObserveElementSizeOptions< T >`: The target element to observe. This parameter is an alternative to the returned ref. The element can be changed dynamically.
+
 ### useStateWithHistory
 
 useState with undo/redo history.
diff --git a/packages/compose/src/index.js b/packages/compose/src/index.js
index 388fbe44048c3d..29a9aa61737440 100644
--- a/packages/compose/src/index.js
+++ b/packages/compose/src/index.js
@@ -38,7 +38,7 @@ export { default as usePrevious } from './hooks/use-previous';
 export { default as useReducedMotion } from './hooks/use-reduced-motion';
 export { default as useStateWithHistory } from './hooks/use-state-with-history';
 export { default as useViewportMatch } from './hooks/use-viewport-match';
-export { default as useResizeObserver } from './hooks/use-resize-observer/_legacy';
+export { default as useResizeObserver } from './hooks/use-resize-observer';
 export { default as useAsyncList } from './hooks/use-async-list';
 export { default as useWarnOnChange } from './hooks/use-warn-on-change';
 export { default as useDebounce } from './hooks/use-debounce';

From 8c2094f286caca292c3ec4d8d0285f35b1e51de3 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Sun, 8 Sep 2024 19:54:45 +0200
Subject: [PATCH 28/30] Apply feedback.

---
 packages/compose/README.md                    |  38 ++---
 .../src/hooks/use-resize-observer/index.ts    | 134 ++++--------------
 2 files changed, 42 insertions(+), 130 deletions(-)

diff --git a/packages/compose/README.md b/packages/compose/README.md
index 6164aaecc311f7..b4e20a79bab0cc 100644
--- a/packages/compose/README.md
+++ b/packages/compose/README.md
@@ -523,45 +523,29 @@ _Returns_
 
 ### useResizeObserver
 
-Tracks a given element's size and calls `onUpdate` for all of its discrete values using a `ResizeObserver`. Pass the returned ref to the element or pass the element to the `targetElement` option directly.
+Sets up a [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Resize_Observer_API) for an HTML or SVG element.
+
+Pass the returned setter as a callback ref to the React element you want to observe, or use it in layout effects for advanced use cases.
 
 _Usage_
 
 ```tsx
-const targetElementRef = useResizeObserver(
-	( resizeObserverEntries, element ) => {
-		console.log( 'Resize observer entries:', resizeObserverEntries );
-		console.log( 'Element that was measured:', element );
-	},
+const setElement = useResizeObserver(
+	( resizeObserverEntries ) => console.log( resizeObserverEntries ),
 	{ box: 'border-box' }
 );
-<div ref={ targetElementRef } />;
-
-// Alternatively, pass the element directly as an argument:
-const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
-useResizeObserver(
-	// ...
-	{
-		targetElement,
-		// ...
-	}
-);
-<div ref={ setTargetElement } />;
+<div ref={ setElement } />;
 
-// The element could be obtained through other means, for example:
-useEffect( () => {
-	const element = document.querySelector(
-		`[data-element-id="${ elementId }"]`
-	);
-	setTargetElement( element );
+// The setter can be used in other ways, for example:
+useLayoutEffect( () => {
+	setElement( document.querySelector( `data-element-id="${ elementId }"` ) );
 }, [ elementId ] );
 ```
 
 _Parameters_
 
--   _onUpdate_ `( resizeObserverEntries: ResizeObserverEntry[], element: T ) => void`: Callback that will be called when the element is measured (initially and after resizes).
--   _options_ `ObserveElementSizeOptions< T >`: Options that, with the exception of `targetElement`, will be passed to `ResizeObserver.observe` when called internally. Updating them will not cause the observer to be re-created, and they will only take effect if a new element is observed.
--   _options.targetElement_ `ObserveElementSizeOptions< T >`: The target element to observe. This parameter is an alternative to the returned ref. The element can be changed dynamically.
+-   _callback_ `ResizeObserverCallback`: The `ResizeObserver` callback - [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/ResizeObserver#callback).
+-   _options_ `ResizeObserverOptions`: Options passed to `ResizeObserver.observe` when called - [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/observe#options). Changes will be ignored.
 
 ### useStateWithHistory
 
diff --git a/packages/compose/src/hooks/use-resize-observer/index.ts b/packages/compose/src/hooks/use-resize-observer/index.ts
index da00f8aafa2cb4..30360983e9fc99 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.ts
+++ b/packages/compose/src/hooks/use-resize-observer/index.ts
@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { useRef, useLayoutEffect } from '@wordpress/element';
+import { useRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
@@ -13,83 +13,41 @@ import _useLegacyResizeObserver from './_legacy';
  */
 import type { ReactElement } from 'react';
 
-/** `useResizeObserver` options. */
-export type ObserveElementSizeOptions< T extends HTMLElement > =
-	ResizeObserverOptions & {
-		/**
-		 * The target element to observe. This parameter is an alternative to the
-		 * returned ref. The element can be changed dynamically.
-		 */
-		targetElement?: T | undefined | null;
-	};
-
 /**
- * Tracks a given element's size and calls `onUpdate` for all of its discrete
- * values using a `ResizeObserver`. Pass the returned ref to the element or
- * pass the element to the `targetElement` option directly.
+ * Sets up a [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Resize_Observer_API)
+ * for an HTML or SVG element.
+ *
+ * Pass the returned setter as a callback ref to the React element you want
+ * to observe, or use it in layout effects for advanced use cases.
  *
  * @example
  *
  * ```tsx
- * const targetElementRef = useResizeObserver(
- * 	( resizeObserverEntries, element ) => {
- * 		console.log( 'Resize observer entries:', resizeObserverEntries );
- * 		console.log( 'Element that was measured:', element );
- * 	},
+ * const setElement = useResizeObserver(
+ * 	( resizeObserverEntries ) => console.log( resizeObserverEntries ),
  * 	{ box: 'border-box' }
  * );
- * <div ref={ targetElementRef } />;
+ * <div ref={ setElement } />;
  *
- * // Alternatively, pass the element directly as an argument:
- * const [ targetElement, setTargetElement ] = useState< HTMLElement | null >();
- * useResizeObserver(
- * 	// ...
- * 	{
- * 		targetElement,
- * 		// ...
- * 	}
- * );
- * <div ref={ setTargetElement } />;
- *
- * // The element could be obtained through other means, for example:
- * useEffect( () => {
- * 	const element = document.querySelector(
- * 		`[data-element-id="${ elementId }"]`
- * 	);
- * 	setTargetElement( element );
+ * // The setter can be used in other ways, for example:
+ * useLayoutEffect( () => {
+ * 	setElement( document.querySelector( `data-element-id="${ elementId }"` ) );
  * }, [ elementId ] );
  * ```
  *
- * @param onUpdate              Callback that will be called when the element is measured (initially and after resizes).
- * @param options               Options that, with the exception of `targetElement`, will be passed to `ResizeObserver.observe` when called internally. Updating them will not cause the observer to be re-created, and they will only take effect if a new element is observed.
- * @param options.targetElement The target element to observe. This parameter is an alternative to the returned ref. The element can be changed dynamically.
+ * @param callback The `ResizeObserver` callback - [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/ResizeObserver#callback).
+ * @param options  Options passed to `ResizeObserver.observe` when called - [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/observe#options). Changes will be ignored.
  */
-export default function useResizeObserver< T extends HTMLElement >(
+export default function useResizeObserver< T extends Element >(
 	/**
-	 * Callback that will be called when the element is measured (initially and
-	 * after resizes).
+	 * The `ResizeObserver` callback - [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/ResizeObserver#callback).
 	 */
-	onUpdate: (
-		/**
-		 * The list of
-		 * [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry)
-		 * objects passed to the `ResizeObserver.observe` callback internally.
-		 */
-		resizeObserverEntries: ResizeObserverEntry[],
-		/**
-		 * The element being tracked at the time of this update.
-		 */
-		element: T
-	) => void,
+	callback: ResizeObserverCallback,
 	/**
-	 * Options that, with the exception of `targetElement`, will be passed to
-	 * `ResizeObserver.observe` when called internally.
-	 *
-	 * Updating them will not cause the observer to be re-created, and they will
-	 * only take effect if a new element is observed.
+	 * Options passed to `ResizeObserver.observe` when called - [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/observe#options). Changes will be ignored.
 	 */
-	options?: ObserveElementSizeOptions< T >
-): ( element?: T | null | undefined ) => void;
+	options?: ResizeObserverOptions
+): ( element?: T | null ) => void;
 
 /**
  * **This is a legacy API and should not be used.**
@@ -117,47 +75,30 @@ export default function useResizeObserver< T extends HTMLElement >(
 export default function useResizeObserver(): [ ReactElement, ObservedSize ];
 
 export default function useResizeObserver< T extends HTMLElement >(
-	onUpdate?: (
-		resizeObserverEntries: ResizeObserverEntry[],
-		element: T
-	) => void,
-	options: ObserveElementSizeOptions< T > = {}
-):
-	| ( ( element?: T | null | undefined ) => void )
-	| [ ReactElement, ObservedSize ] {
-	return onUpdate
-		? _useResizeObserver( onUpdate, options )
+	callback?: ResizeObserverCallback,
+	options: ResizeObserverOptions = {}
+): ( ( element?: T | null ) => void ) | [ ReactElement, ObservedSize ] {
+	return callback
+		? _useResizeObserver( callback, options )
 		: _useLegacyResizeObserver();
 }
 
 function _useResizeObserver< T extends HTMLElement >(
-	onUpdate: (
-		resizeObserverEntries: ResizeObserverEntry[],
-		element: T
-	) => void,
-	{
-		targetElement,
-		...resizeObserverOptions
-	}: ObserveElementSizeOptions< T > = {}
-): ( element?: T | null | undefined ) => void {
-	const onUpdateEvent = useEvent( onUpdate );
+	callback: ResizeObserverCallback,
+	resizeObserverOptions: ResizeObserverOptions = {}
+): ( element?: T | null ) => void {
+	const callbackEvent = useEvent( callback );
 
 	const observedElementRef = useRef< T | null >();
 	const resizeObserverRef = useRef< ResizeObserver >();
-	const setElement = useEvent( ( element?: T | null | undefined ) => {
+	return useEvent( ( element?: T | null ) => {
 		if ( element === observedElementRef.current ) {
 			return;
 		}
 		observedElementRef.current = element;
 
 		// Set up `ResizeObserver`.
-		if ( ! resizeObserverRef.current ) {
-			resizeObserverRef.current = new ResizeObserver( ( entries ) => {
-				if ( observedElementRef.current ) {
-					onUpdateEvent( entries, observedElementRef.current );
-				}
-			} );
-		}
+		resizeObserverRef.current ??= new ResizeObserver( callbackEvent );
 		const { current: resizeObserver } = resizeObserverRef;
 
 		// Unobserve previous element.
@@ -170,17 +111,4 @@ function _useResizeObserver< T extends HTMLElement >(
 			resizeObserver.observe( element, resizeObserverOptions );
 		}
 	} );
-
-	// Handle `targetElement` option.
-	const isArgumentRef = useRef( Boolean( targetElement ) );
-	useLayoutEffect( () => {
-		if ( targetElement || isArgumentRef.current ) {
-			isArgumentRef.current = true;
-			setElement( targetElement );
-			return setElement;
-		}
-		return undefined;
-	}, [ setElement, targetElement ] );
-
-	return setElement;
 }

From 6f3abb79e4551e52ac0aee01e8d25696c884be61 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Sun, 8 Sep 2024 20:02:27 +0200
Subject: [PATCH 29/30] Clean up and document.

---
 .../src/hooks/use-resize-observer/index.ts    | 65 ++++++++++---------
 1 file changed, 35 insertions(+), 30 deletions(-)

diff --git a/packages/compose/src/hooks/use-resize-observer/index.ts b/packages/compose/src/hooks/use-resize-observer/index.ts
index 30360983e9fc99..2a76b2aa6ab590 100644
--- a/packages/compose/src/hooks/use-resize-observer/index.ts
+++ b/packages/compose/src/hooks/use-resize-observer/index.ts
@@ -13,6 +13,41 @@ import _useLegacyResizeObserver from './_legacy';
  */
 import type { ReactElement } from 'react';
 
+// This is the current implementation of `useResizeObserver`.
+//
+// The legacy implementation is still supported for backwards compatibility.
+// This is achieved by overloading the exported function with both signatures,
+// and detecting which API is being used at runtime.
+function _useResizeObserver< T extends HTMLElement >(
+	callback: ResizeObserverCallback,
+	resizeObserverOptions: ResizeObserverOptions = {}
+): ( element?: T | null ) => void {
+	const callbackEvent = useEvent( callback );
+
+	const observedElementRef = useRef< T | null >();
+	const resizeObserverRef = useRef< ResizeObserver >();
+	return useEvent( ( element?: T | null ) => {
+		if ( element === observedElementRef.current ) {
+			return;
+		}
+		observedElementRef.current = element;
+
+		// Set up `ResizeObserver`.
+		resizeObserverRef.current ??= new ResizeObserver( callbackEvent );
+		const { current: resizeObserver } = resizeObserverRef;
+
+		// Unobserve previous element.
+		if ( observedElementRef.current ) {
+			resizeObserver.unobserve( observedElementRef.current );
+		}
+
+		// Observe new element.
+		if ( element ) {
+			resizeObserver.observe( element, resizeObserverOptions );
+		}
+	} );
+}
+
 /**
  * Sets up a [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Resize_Observer_API)
  * for an HTML or SVG element.
@@ -82,33 +117,3 @@ export default function useResizeObserver< T extends HTMLElement >(
 		? _useResizeObserver( callback, options )
 		: _useLegacyResizeObserver();
 }
-
-function _useResizeObserver< T extends HTMLElement >(
-	callback: ResizeObserverCallback,
-	resizeObserverOptions: ResizeObserverOptions = {}
-): ( element?: T | null ) => void {
-	const callbackEvent = useEvent( callback );
-
-	const observedElementRef = useRef< T | null >();
-	const resizeObserverRef = useRef< ResizeObserver >();
-	return useEvent( ( element?: T | null ) => {
-		if ( element === observedElementRef.current ) {
-			return;
-		}
-		observedElementRef.current = element;
-
-		// Set up `ResizeObserver`.
-		resizeObserverRef.current ??= new ResizeObserver( callbackEvent );
-		const { current: resizeObserver } = resizeObserverRef;
-
-		// Unobserve previous element.
-		if ( observedElementRef.current ) {
-			resizeObserver.unobserve( observedElementRef.current );
-		}
-
-		// Observe new element.
-		if ( element ) {
-			resizeObserver.observe( element, resizeObserverOptions );
-		}
-	} );
-}

From 4aa01b32bb2927c3d9574c045c91a3ff2ac20c06 Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Mon, 9 Sep 2024 23:19:43 +0200
Subject: [PATCH 30/30] Added changelog entries.

---
 packages/compose/CHANGELOG.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/compose/CHANGELOG.md b/packages/compose/CHANGELOG.md
index 951f70604f41c6..3f4b8fd27b0b08 100644
--- a/packages/compose/CHANGELOG.md
+++ b/packages/compose/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### New Features
+
+-   `useEvent`: a new utility that creates a stable callback function that has access to the latest state and can be used within event handlers and effect callbacks ([#64943](https://github.com/WordPress/gutenberg/pull/64943)).
+-   `useResizeObserver`: new and improved version of the utility (legacy API is still supported) ([#64943](https://github.com/WordPress/gutenberg/pull/64943)).
+
 ## 7.6.0 (2024-08-21)
 
 ## 7.5.0 (2024-08-07)
@@ -203,8 +208,8 @@
 
 ### Breaking Changes
 
--   Drop support for Internet Explorer 11 ([#31110](https://github.com/WordPress/gutenberg/pull/31110)). Learn more at https://make.wordpress.org/core/2021/04/22/ie-11-support-phase-out-plan/.
--   Increase the minimum Node.js version to v12 matching Long Term Support releases ([#31270](https://github.com/WordPress/gutenberg/pull/31270)). Learn more at https://nodejs.org/en/about/releases/.
+-   Drop support for Internet Explorer 11 ([#31110](https://github.com/WordPress/gutenberg/pull/31110)). Learn more at <https://make.wordpress.org/core/2021/04/22/ie-11-support-phase-out-plan/>.
+-   Increase the minimum Node.js version to v12 matching Long Term Support releases ([#31270](https://github.com/WordPress/gutenberg/pull/31270)). Learn more at <https://nodejs.org/en/about/releases/>.
 
 ## 3.25.0 (2021-03-17)