@wordpress/components 25.14.0 → 25.15.0

package/src/mobile/keyboard-aware-flat-list/index.ios.js

@@ -2,139 +2,104 @@
  * External dependencies
  */
 
-import { ScrollView, FlatList, useWindowDimensions } from 'react-native';
-import Animated, {
-	useAnimatedScrollHandler,
-	useSharedValue,
-} from 'react-native-reanimated';
+import { ScrollView, FlatList } from 'react-native';
+import Animated from 'react-native-reanimated';
 
 /**
  * WordPress dependencies
  */
-import { useCallback, useEffect, useRef } from '@wordpress/element';
+import {
+	useCallback,
+	useEffect,
+	forwardRef,
+	useImperativeHandle,
+} from '@wordpress/element';
 import { useThrottle } from '@wordpress/compose';
 
 /**
  * Internal dependencies
  */
+import useScroll from './use-scroll';
 import useTextInputOffset from './use-text-input-offset';
-import useKeyboardOffset from './use-keyboard-offset';
-import useScrollToTextInput from './use-scroll-to-text-input';
 import useTextInputCaretPosition from './use-text-input-caret-position';
 
+const DEFAULT_FONT_SIZE = 16;
 const AnimatedScrollView = Animated.createAnimatedComponent( ScrollView );
 
+/** @typedef {import('@wordpress/element').RefObject} RefObject */
 /**
  * React component that provides a FlatList that is aware of the keyboard state and can scroll
  * to the currently focused TextInput.
  *
- * @param {Object}   props                              Component props.
- * @param {number}   props.extraScrollHeight            Extra scroll height for the content.
- * @param {Function} props.innerRef                     Function to pass the ScrollView ref to the parent component.
- * @param {Function} props.onScroll                     Function to be called when the list is scrolled.
- * @param {boolean}  props.scrollEnabled                Whether the list can be scrolled.
- * @param {Object}   props.scrollViewStyle              Additional style for the ScrollView component.
- * @param {boolean}  props.shouldPreventAutomaticScroll Whether to prevent scrolling when there's a Keyboard offset set.
- * @param {Object}   props...                           Other props to pass to the FlatList component.
+ * @param {Object}    props                              Component props.
+ * @param {number}    props.extraScrollHeight            Extra scroll height for the content.
+ * @param {Function}  props.onScroll                     Function to be called when the list is scrolled.
+ * @param {boolean}   props.scrollEnabled                Whether the list can be scrolled.
+ * @param {Object}    props.scrollViewStyle              Additional style for the ScrollView component.
+ * @param {boolean}   props.shouldPreventAutomaticScroll Whether to prevent scrolling when there's a Keyboard offset set.
+ * @param {Object}    props...                           Other props to pass to the FlatList component.
+ * @param {RefObject} ref
  * @return {Component} KeyboardAwareFlatList component.
  */
-export const KeyboardAwareFlatList = ( {
-	extraScrollHeight,
-	innerRef,
-	onScroll,
-	scrollEnabled,
-	scrollViewStyle,
-	shouldPreventAutomaticScroll,
-	...props
-} ) => {
-	const scrollViewRef = useRef();
-	const scrollViewMeasurements = useRef();
-	const scrollViewYOffset = useSharedValue( -1 );
-
-	const { height: windowHeight, width: windowWidth } = useWindowDimensions();
-	const isLandscape = windowWidth >= windowHeight;
-
-	const [ keyboardOffset ] = useKeyboardOffset(
+export const KeyboardAwareFlatList = (
+	{
+		extraScrollHeight,
+		onScroll,
 		scrollEnabled,
-		shouldPreventAutomaticScroll
-	);
-
-	const [ currentCaretData ] = useTextInputCaretPosition( scrollEnabled );
+		scrollViewStyle,
+		shouldPreventAutomaticScroll,
+		...props
+	},
+	ref
+) => {
+	const {
+		scrollViewRef,
+		scrollHandler,
+		keyboardOffset,
+		scrollToSection,
+		scrollToElement,
+		onContentSizeChange,
+		lastScrollTo,
+	} = useScroll( {
+		scrollEnabled,
+		shouldPreventAutomaticScroll,
+		extraScrollHeight,
+		onScroll,
+		onSizeChange,
+	} );
 
 	const [ getTextInputOffset ] = useTextInputOffset(
 		scrollEnabled,
 		scrollViewRef
 	);
 
-	const [ scrollToTextInputOffset ] = useScrollToTextInput(
-		extraScrollHeight,
-		keyboardOffset,
-		scrollEnabled,
-		scrollViewMeasurements,
-		scrollViewRef,
-		scrollViewYOffset
-	);
-
 	const onScrollToTextInput = useThrottle(
 		useCallback(
 			async ( caret ) => {
+				const { caretHeight = DEFAULT_FONT_SIZE } = caret ?? {};
 				const textInputOffset = await getTextInputOffset( caret );
 				const hasTextInputOffset = textInputOffset !== null;
 
 				if ( hasTextInputOffset ) {
-					scrollToTextInputOffset( caret, textInputOffset );
+					scrollToSection( textInputOffset, caretHeight );
 				}
 			},
-			[ getTextInputOffset, scrollToTextInputOffset ]
+			[ getTextInputOffset, scrollToSection ]
 		),
 		200,
 		{ leading: false }
 	);
 
-	useEffect( () => {
-		onScrollToTextInput( currentCaretData );
-	}, [ currentCaretData, onScrollToTextInput ] );
-
-	// When the orientation changes, the ScrollView measurements
-	// need to be re-calculated.
-	useEffect( () => {
-		scrollViewMeasurements.current = null;
-	}, [ isLandscape ] );
-
-	const scrollHandler = useAnimatedScrollHandler( {
-		onScroll: ( event ) => {
-			const { contentOffset } = event;
-			scrollViewYOffset.value = contentOffset.y;
-			onScroll( event );
-		},
-	} );
-
-	const measureScrollView = useCallback( () => {
-		if ( scrollViewRef.current ) {
-			const scrollRef = scrollViewRef.current.getNativeScrollRef();
+	const [ currentCaretData ] = useTextInputCaretPosition( scrollEnabled );
 
-			scrollRef.measureInWindow( ( _x, y, width, height ) => {
-				scrollViewMeasurements.current = { y, width, height };
-			} );
-		}
-	}, [] );
+	const onSizeChange = useCallback(
+		() => onScrollToTextInput( currentCaretData ),
+		[ currentCaretData, onScrollToTextInput ]
+	);
 
-	const onContentSizeChange = useCallback( () => {
+	useEffect( () => {
 		onScrollToTextInput( currentCaretData );
-
-		// Sets the first values when the content size changes.
-		if ( ! scrollViewMeasurements.current ) {
-			measureScrollView();
-		}
-	}, [ measureScrollView, onScrollToTextInput, currentCaretData ] );
-
-	const getRef = useCallback(
-		( ref ) => {
-			scrollViewRef.current = ref;
-			innerRef( ref );
-		},
-		[ innerRef ]
-	);
+	}, [ currentCaretData, onScrollToTextInput ] );
 
 	// Adds content insets when the keyboard is opened to have
 	// extra padding at the bottom.
@@ -142,6 +107,15 @@ export const KeyboardAwareFlatList = ( {
 
 	const style = [ { flex: 1 }, scrollViewStyle ];
 
+	useImperativeHandle( ref, () => {
+		return {
+			scrollViewRef: scrollViewRef.current,
+			scrollToSection,
+			scrollToElement,
+			lastScrollTo,
+		};
+	} );
+
 	return (
 		<AnimatedScrollView
 			automaticallyAdjustContentInsets={ false }
@@ -149,7 +123,7 @@ export const KeyboardAwareFlatList = ( {
 			keyboardShouldPersistTaps="handled"
 			onContentSizeChange={ onContentSizeChange }
 			onScroll={ scrollHandler }
-			ref={ getRef }
+			ref={ scrollViewRef }
 			scrollEnabled={ scrollEnabled }
 			scrollEventThrottle={ 16 }
 			style={ style }
@@ -159,4 +133,4 @@ export const KeyboardAwareFlatList = ( {
 	);
 };
 
-export default KeyboardAwareFlatList;
+export default forwardRef( KeyboardAwareFlatList );

package/src/mobile/keyboard-aware-flat-list/test/{use-scroll-to-text-input.native.js → use-scroll-to-section.native.js}

@@ -7,22 +7,23 @@ import { renderHook } from '@testing-library/react-native';
 /**
  * Internal dependencies
  */
-import useScrollToTextInput from '../use-scroll-to-text-input';
+import useScrollToSection from '../use-scroll-to-section';
 
-describe( 'useScrollToTextInput', () => {
-	it( 'scrolls up to the current TextInput offset', () => {
+describe( 'useScrollToSection', () => {
+	it( 'scrolls up to the section', () => {
 		// Arrange
-		const currentCaretData = { caretHeight: 10 };
+		const sectionY = 50;
+		const sectionHeight = 10;
+
 		const extraScrollHeight = 50;
 		const keyboardOffset = 100;
 		const scrollEnabled = true;
 		const scrollViewRef = { current: { scrollTo: jest.fn() } };
 		const scrollViewMeasurements = { current: { height: 600 } };
 		const scrollViewYOffset = { value: 150 };
-		const textInputOffset = 50;
 
 		const { result } = renderHook( () =>
-			useScrollToTextInput(
+			useScrollToSection(
 				extraScrollHeight,
 				keyboardOffset,
 				scrollEnabled,
@@ -33,28 +34,29 @@ describe( 'useScrollToTextInput', () => {
 		);
 
 		// Act
-		result.current[ 0 ]( currentCaretData, textInputOffset );
+		result.current[ 0 ]( sectionY, sectionHeight );
 
 		// Assert
 		expect( scrollViewRef.current.scrollTo ).toHaveBeenCalledWith( {
-			y: textInputOffset,
+			y: sectionY,
 			animated: true,
 		} );
 	} );
 
-	it( 'scrolls down to the current TextInput offset', () => {
+	it( 'scrolls down to the section', () => {
 		// Arrange
-		const currentCaretData = { caretHeight: 10 };
+		const sectionY = 750;
+		const sectionHeight = 10;
+
 		const extraScrollHeight = 50;
 		const keyboardOffset = 100;
 		const scrollEnabled = true;
 		const scrollViewRef = { current: { scrollTo: jest.fn() } };
 		const scrollViewMeasurements = { current: { height: 600 } };
 		const scrollViewYOffset = { value: 250 };
-		const textInputOffset = 750;
 
 		const { result } = renderHook( () =>
-			useScrollToTextInput(
+			useScrollToSection(
 				extraScrollHeight,
 				keyboardOffset,
 				scrollEnabled,
@@ -65,15 +67,13 @@ describe( 'useScrollToTextInput', () => {
 		);
 
 		// Act
-		result.current[ 0 ]( currentCaretData, textInputOffset );
+		result.current[ 0 ]( sectionY, sectionHeight );
 
 		// Assert
 		const expectedYOffset =
-			textInputOffset -
+			sectionY -
 			( scrollViewMeasurements.current.height -
-				( keyboardOffset +
-					extraScrollHeight +
-					currentCaretData.caretHeight ) );
+				( keyboardOffset + extraScrollHeight + sectionHeight ) );
 		expect( scrollViewRef.current.scrollTo ).toHaveBeenCalledWith( {
 			y: expectedYOffset,
 			animated: true,
@@ -82,17 +82,18 @@ describe( 'useScrollToTextInput', () => {
 
 	it( 'does not scroll when the ScrollView ref is not available', () => {
 		// Arrange
-		const currentCaretData = { caretHeight: 10 };
+		const sectionY = 50;
+		const sectionHeight = 10;
+
 		const extraScrollHeight = 50;
 		const keyboardOffset = 100;
 		const scrollEnabled = true;
 		const scrollViewRef = { current: null };
 		const scrollViewMeasurements = { current: { height: 600 } };
 		const scrollViewYOffset = { value: 0 };
-		const textInputOffset = 50;
 
 		const { result } = renderHook( () =>
-			useScrollToTextInput(
+			useScrollToSection(
 				extraScrollHeight,
 				keyboardOffset,
 				scrollEnabled,
@@ -103,7 +104,7 @@ describe( 'useScrollToTextInput', () => {
 		);
 
 		// Act
-		result.current[ 0 ]( currentCaretData, textInputOffset );
+		result.current[ 0 ]( sectionY, sectionHeight );
 
 		// Assert
 		expect( scrollViewRef.current ).toBeNull();
@@ -111,17 +112,18 @@ describe( 'useScrollToTextInput', () => {
 
 	it( 'does not scroll when the scroll is not enabled', () => {
 		// Arrange
-		const currentCaretData = { caretHeight: 10 };
+		const sectionY = 50;
+		const sectionHeight = 10;
+
 		const extraScrollHeight = 50;
 		const keyboardOffset = 100;
 		const scrollEnabled = false;
 		const scrollViewRef = { current: { scrollTo: jest.fn() } };
 		const scrollViewMeasurements = { current: { height: 600 } };
 		const scrollViewYOffset = { value: 0 };
-		const textInputOffset = 50;
 
 		const { result } = renderHook( () =>
-			useScrollToTextInput(
+			useScrollToSection(
 				extraScrollHeight,
 				keyboardOffset,
 				scrollEnabled,
@@ -132,7 +134,7 @@ describe( 'useScrollToTextInput', () => {
 		);
 
 		// Act
-		result.current[ 0 ]( currentCaretData, textInputOffset );
+		result.current[ 0 ]( sectionY, sectionHeight );
 
 		// Assert
 		expect( scrollViewRef.current.scrollTo ).not.toHaveBeenCalled();

package/src/mobile/keyboard-aware-flat-list/test/use-scroll.native.js

@@ -0,0 +1,71 @@
+/**
+ * External dependencies
+ */
+
+import { renderHook } from 'test/helpers';
+
+/**
+ * Internal dependencies
+ */
+import useScroll from '../use-scroll';
+
+// Mock Reanimated with default mock
+jest.mock( 'react-native-reanimated', () => ( {
+	...require( 'react-native-reanimated/mock' ),
+	useAnimatedScrollHandler: jest.fn( ( args ) => args ),
+} ) );
+
+describe( 'useScroll', () => {
+	it( 'scrolls using current scroll position', () => {
+		const sectionY = 50;
+		const sectionHeight = 10;
+		const scrollViewMeasurements = { x: 0, y: 0, width: 0, height: 600 };
+		const extraScrollHeight = 50;
+		const scrollEnabled = true;
+		const shouldPreventAutomaticScroll = false;
+
+		const scrollTo = jest.fn();
+		const measureInWindow = jest.fn( ( callback ) =>
+			callback( ...Object.values( scrollViewMeasurements ) )
+		);
+		const scrollRef = { scrollTo, measureInWindow };
+		const onScroll = jest.fn();
+		const onSizeChange = jest.fn();
+
+		const { result } = renderHook( () =>
+			useScroll( {
+				scrollEnabled,
+				shouldPreventAutomaticScroll,
+				onScroll,
+				onSizeChange,
+				extraScrollHeight,
+			} )
+		);
+		const {
+			scrollViewRef,
+			onContentSizeChange,
+			scrollHandler,
+			scrollToSection,
+		} = result.current;
+
+		// Assign ref
+		scrollViewRef.current = scrollRef;
+
+		// Check content size changes
+		onContentSizeChange();
+		expect( measureInWindow ).toHaveBeenCalled();
+		expect( onSizeChange ).toHaveBeenCalled();
+
+		// Set up initial scroll offset
+		scrollHandler.onScroll( { contentOffset: { y: 150 } } );
+
+		// Scroll to section
+		scrollToSection( sectionY, sectionHeight );
+
+		// Assert
+		expect( scrollTo ).toHaveBeenCalledWith( {
+			y: sectionY,
+			animated: true,
+		} );
+	} );
+} );

package/src/mobile/keyboard-aware-flat-list/use-scroll-to-element.native.js

@@ -0,0 +1,41 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
+
+/** @typedef {import('@wordpress/element').RefObject} RefObject */
+/**
+ * Hook to scroll to a specified element by taking into account the Keyboard
+ * and the Header.
+ *
+ * @param {RefObject} scrollViewRef   Scroll view reference.
+ * @param {Function}  scrollToSection Function to scroll.
+ * @return {Function[]} Function to scroll to an element.
+ */
+export default function useScrollToElement( scrollViewRef, scrollToSection ) {
+	/**
+	 * Function to scroll to an element.
+	 *
+	 * @param {RefObject} elementRef Ref of the element.
+	 */
+	const scrollToElement = useCallback(
+		( elementRef ) => {
+			if ( ! scrollViewRef.current || ! elementRef ) {
+				return;
+			}
+
+			elementRef.current.measureLayout(
+				scrollViewRef.current,
+				( _x, y, _width, height ) => {
+					if ( height || y ) {
+						scrollToSection( Math.round( y ), height );
+					}
+				},
+				() => {}
+			);
+		},
+		[ scrollViewRef, scrollToSection ]
+	);
+
+	return [ scrollToElement ];
+}

package/src/mobile/keyboard-aware-flat-list/{use-scroll-to-text-input.native.js → use-scroll-to-section.native.js}

@@ -8,24 +8,21 @@ import { useSafeAreaInsets } from 'react-native-safe-area-context';
  */
 import { useCallback } from '@wordpress/element';
 
-const DEFAULT_FONT_SIZE = 16;
-
 /** @typedef {import('@wordpress/element').RefObject} RefObject */
 /** @typedef {import('react-native-reanimated').SharedValue} SharedValue */
 /**
- * Hook to scroll to the currently focused TextInput
- * depending on where the caret is placed taking into
- * account the Keyboard and the Header.
+ * Hook to scroll to a specified section by taking into account the Keyboard
+ * and the Header.
  *
  * @param {number}      extraScrollHeight      Extra space to not overlap the content.
  * @param {number}      keyboardOffset         Keyboard space offset.
  * @param {boolean}     scrollEnabled          Whether the scroll is enabled or not.
  * @param {RefObject}   scrollViewMeasurements ScrollView Layout measurements.
- * @param {RefObject}   scrollViewRef          ScrollView reference.
+ * @param {RefObject}   scrollViewRef          Scroll view reference.
  * @param {SharedValue} scrollViewYOffset      Current offset position of the ScrollView.
- * @return {Function[]} Function to scroll to the current TextInput's offset.
+ * @return {Function[]} Function to scroll to a section.
  */
-export default function useScrollToTextInput(
+export default function useScrollToSection(
 	extraScrollHeight,
 	keyboardOffset,
 	scrollEnabled,
@@ -37,33 +34,31 @@ export default function useScrollToTextInput(
 	const insets = top + bottom;
 
 	/**
-	 * Function to scroll to the current TextInput's offset.
+	 * Function to scroll to a section.
 	 *
-	 * @param {Object} caret             The caret position data of the currently focused TextInput.
-	 * @param {number} caret.caretHeight The height of the caret.
-	 * @param {number} textInputOffset   The offset calculated with the caret's Y coordinate + the
-	 *                                   TextInput's Y coord or height value.
+	 * @param {Object} section        Section data to scroll to.
+	 * @param {number} section.y      Y-coordinate of of the section.
+	 * @param {number} section.height Height of the section.
 	 */
-	const scrollToTextInputOffset = useCallback(
-		( caret, textInputOffset ) => {
-			const { caretHeight = DEFAULT_FONT_SIZE } = caret ?? {};
-
+	const scrollToSection = useCallback(
+		( sectionY, sectionHeight ) => {
 			if (
 				! scrollViewRef.current ||
 				! scrollEnabled ||
-				! scrollViewMeasurements.current
+				! scrollViewMeasurements
 			) {
 				return;
 			}
+
 			const currentScrollViewYOffset = Math.max(
 				0,
 				scrollViewYOffset.value
 			);
 
-			// Scroll up.
-			if ( textInputOffset < currentScrollViewYOffset ) {
+			// Scroll to the top of the section.
+			if ( sectionY < currentScrollViewYOffset ) {
 				scrollViewRef.current.scrollTo( {
-					y: textInputOffset,
+					y: sectionY,
 					animated: true,
 				} );
 				return;
@@ -72,7 +67,7 @@ export default function useScrollToTextInput(
 			const availableScreenSpace = Math.abs(
 				Math.floor(
 					scrollViewMeasurements.current.height -
-						( keyboardOffset + extraScrollHeight + caretHeight )
+						( keyboardOffset + extraScrollHeight + sectionHeight )
 				)
 			);
 			const maxOffset = Math.floor(
@@ -80,12 +75,12 @@ export default function useScrollToTextInput(
 			);
 
 			const isAtTheTop =
-				textInputOffset < scrollViewMeasurements.current.y + insets;
+				sectionY < scrollViewMeasurements.current.y + insets;
 
-			// Scroll down.
-			if ( textInputOffset > maxOffset && ! isAtTheTop ) {
+			// Scroll to the bottom of the section.
+			if ( sectionY > maxOffset && ! isAtTheTop ) {
 				scrollViewRef.current.scrollTo( {
-					y: textInputOffset - availableScreenSpace,
+					y: sectionY - availableScreenSpace,
 					animated: true,
 				} );
 			}
@@ -101,5 +96,5 @@ export default function useScrollToTextInput(
 		]
 	);
 
-	return [ scrollToTextInputOffset ];
+	return [ scrollToSection ];
 }

package/src/mobile/keyboard-aware-flat-list/use-scroll.native.js

@@ -0,0 +1,100 @@
+/**
+ * External dependencies
+ */
+
+import { useWindowDimensions } from 'react-native';
+import {
+	useAnimatedScrollHandler,
+	useSharedValue,
+} from 'react-native-reanimated';
+
+/**
+ * WordPress dependencies
+ */
+import { useCallback, useEffect, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import useKeyboardOffset from './use-keyboard-offset';
+import useScrollToSection from './use-scroll-to-section';
+import useScrollToElement from './use-scroll-to-element';
+
+export default function useScroll( {
+	scrollEnabled,
+	shouldPreventAutomaticScroll,
+	onScroll,
+	onSizeChange,
+	extraScrollHeight,
+} ) {
+	const scrollViewRef = useRef();
+	const scrollViewMeasurements = useRef();
+	const scrollViewYOffset = useSharedValue( -1 );
+	const lastScrollTo = useRef( {
+		clientId: null,
+	} );
+
+	const { height: windowHeight, width: windowWidth } = useWindowDimensions();
+	const isLandscape = windowWidth >= windowHeight;
+
+	const [ keyboardOffset ] = useKeyboardOffset(
+		scrollEnabled,
+		shouldPreventAutomaticScroll
+	);
+
+	const scrollHandler = useAnimatedScrollHandler( {
+		onScroll: ( event ) => {
+			const { contentOffset } = event;
+			scrollViewYOffset.value = contentOffset.y;
+			onScroll( event );
+		},
+	} );
+
+	// When the orientation changes, the ScrollView measurements
+	// need to be re-calculated.
+	useEffect( () => {
+		scrollViewMeasurements.current = null;
+	}, [ isLandscape ] );
+
+	const [ scrollToSection ] = useScrollToSection(
+		extraScrollHeight,
+		keyboardOffset,
+		scrollEnabled,
+		scrollViewMeasurements,
+		scrollViewRef,
+		scrollViewYOffset
+	);
+	const [ scrollToElement ] = useScrollToElement(
+		scrollViewRef,
+		scrollToSection
+	);
+
+	const measureScrollView = useCallback( () => {
+		if ( scrollViewRef.current ) {
+			scrollViewRef.current.measureInWindow( ( _x, y, width, height ) => {
+				scrollViewMeasurements.current = { y, width, height };
+			} );
+		}
+	}, [ scrollViewRef ] );
+
+	const onContentSizeChange = useCallback( () => {
+		if ( onSizeChange ) {
+			onSizeChange();
+		}
+
+		// Sets the first values when the content size changes.
+		if ( ! scrollViewMeasurements.current ) {
+			measureScrollView();
+		}
+	}, [ measureScrollView, onSizeChange ] );
+
+	return {
+		scrollViewRef,
+		scrollHandler,
+		keyboardOffset,
+		scrollToSection,
+		scrollToElement,
+		onContentSizeChange,
+		lastScrollTo,
+	};
+}