Rename to useLatestRef

Co-authored-by: Haz <hazdiego@gmail.com>

packages/components/src/utils/hooks/index.js

@@ -2,4 +2,4 @@ export { default as useControlledState } from './use-controlled-state';
 export { default as useJumpStep } from './use-jump-step';
 export { default as useUpdateEffect } from './use-update-effect';
 export { useControlledValue } from './use-controlled-value';
-export { usePropRef } from './use-prop-ref';
+export { useLatestRef } from './use-latest-ref';

packages/components/src/utils/hooks/test/use-prop-ref.js → packages/components/src/utils/hooks/test/use-latest-ref.js

@@ -11,15 +11,15 @@ import { useCallback } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { usePropRef } from '..';
+import { useLatestRef } from '..';
 
 function getInput() {
 	return screen.getByRole( 'textbox' );
 }
 
-describe( 'usePropRef', () => {
+describe( 'useLatestRef', () => {
 	function Example( { value, onChange } ) {
-		const ref = usePropRef( value );
+		const ref = useLatestRef( value );
 
 		const handleChange = useCallback( () => {
 			onChange( ref.current );
@@ -31,9 +31,13 @@ describe( 'usePropRef', () => {
 	it( 'should maintain the ref when the prop value changes', () => {
 		const { rerender } = render( <Example value="A" /> );
 
+		rerender( <Example value="B" /> );
+
 		expect( getInput().value ).toEqual( 'A' );
+	} );
 
-		rerender( <Example value="B" /> );
+	it( 'should keep a handle on the value', () => {
+		render( <Example value="A" /> );
 
 		expect( getInput().value ).toEqual( 'A' );
 	} );

packages/components/src/utils/hooks/use-latest-ref.ts

@@ -0,0 +1,52 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { RefObject } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useLayoutEffect, useRef } from '@wordpress/element';
+
+/**
+ * Creates a reference for a prop. This is useful for preserving dependency
+ * memoization for hooks like useCallback.
+ *
+ * @example
+ *               ```js
+ *               // Referencing a simple prop, used in a useCallback function.
+ *               const valueRef = usePropRef(value)
+ *
+ *               const increment = useCallback(() => {
+ *               const value = valueRef.current
+ *               onChange(value + 1)
+ *               }, [onChange, valueRef])
+ *               ```
+ *
+ *               ---
+ *
+ *               Multiple props can be passed in using an `object`.
+ *
+ * @example
+ * ```js
+ * const propRefs = usePropRef({ value, step })
+ *
+ * const increment = useCallback(() => {
+ *   const { value, step } = propRefs.current
+ *   onChange(value + step)
+ * }, [onChange, propRefs])
+ * ```
+ *
+ * @param  value The value to reference
+ * @return The prop reference.
+ */
+export function useLatestRef< T >( value: T ): RefObject< T > {
+	const ref = useRef( value );
+
+	useLayoutEffect( () => {
+		ref.current = value;
+	} );
+
+	return ref;
+}