@wordpress/components 23.7.0 → 23.8.0

package/src/mobile/keyboard-aware-flat-list/test/use-text-input-offset.native.js

@@ -0,0 +1,147 @@
+/**
+ * External dependencies
+ */
+import { renderHook } from '@testing-library/react-native';
+
+/**
+ * WordPress dependencies
+ */
+import RCTAztecView from '@wordpress/react-native-aztec';
+
+/**
+ * Internal dependencies
+ */
+import useTextInputOffset from '../use-text-input-offset';
+
+jest.mock( '@wordpress/react-native-aztec', () => ( {
+	InputState: {
+		getCurrentFocusedElement: jest.fn(),
+	},
+} ) );
+
+describe( 'useTextInputOffset', () => {
+	afterEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'should return a function', () => {
+		// Arrange
+		const scrollViewRef = { current: {} };
+		const scrollEnabled = true;
+
+		// Act
+		const { result } = renderHook( () =>
+			useTextInputOffset( scrollEnabled, scrollViewRef )
+		);
+
+		// Assert
+		expect( result.current[ 0 ] ).toBeInstanceOf( Function );
+	} );
+
+	it( 'should return null when scrollViewRef.current is null', async () => {
+		// Arrange
+		const scrollViewRef = { current: null };
+		const scrollEnabled = true;
+
+		// Act
+		const { result } = renderHook( () =>
+			useTextInputOffset( scrollEnabled, scrollViewRef )
+		);
+		const getTextInputOffset = result.current[ 0 ];
+
+		// Assert
+		const offset = await getTextInputOffset();
+		expect( offset ).toBeNull();
+	} );
+
+	it( 'should return null when textInput is null', async () => {
+		// Arrange
+		const scrollViewRef = { current: {} };
+		const scrollEnabled = true;
+		RCTAztecView.InputState.getCurrentFocusedElement.mockReturnValue(
+			null
+		);
+
+		// Act
+		const { result } = renderHook( () =>
+			useTextInputOffset( scrollEnabled, scrollViewRef )
+		);
+		const getTextInputOffset = result.current[ 0 ];
+
+		// Assert
+		const offset = await getTextInputOffset();
+		expect( offset ).toBeNull();
+	} );
+
+	it( 'should return null when scroll is not enabled', async () => {
+		// Arrange
+		const scrollViewRef = { current: {} };
+		const scrollEnabled = false;
+
+		// Act
+		const { result } = renderHook( () =>
+			useTextInputOffset( scrollEnabled, scrollViewRef )
+		);
+		const getTextInputOffset = result.current[ 0 ];
+
+		// Assert
+		const offset = await getTextInputOffset();
+		expect( offset ).toBeNull();
+	} );
+
+	it( 'should return correct offset value when caretY is not null', async () => {
+		// Arrange
+		const scrollViewRef = { current: {} };
+		const scrollEnabled = true;
+		const x = 0;
+		const y = 10;
+		const width = 0;
+		const height = 100;
+		const textInput = {
+			measureLayout: jest.fn( ( _, callback ) => {
+				callback( x, y, width, height );
+			} ),
+		};
+		RCTAztecView.InputState.getCurrentFocusedElement.mockReturnValue(
+			textInput
+		);
+
+		// Act
+		const { result } = renderHook( () =>
+			useTextInputOffset( scrollEnabled, scrollViewRef )
+		);
+		const getTextInputOffset = result.current[ 0 ];
+
+		// Assert
+		const offset = await getTextInputOffset( { caretY: 10 } );
+		expect( offset ).toBe( 20 );
+	} );
+
+	it( 'should return correct offset value when caretY is -1', async () => {
+		// Arrange
+		const scrollViewRef = { current: {} };
+		const scrollEnabled = true;
+		const x = 0;
+		const y = 10;
+		const width = 0;
+		const height = 100;
+		const textInput = {
+			measureLayout: jest.fn( ( _, callback ) => {
+				callback( x, y, width, height );
+			} ),
+		};
+		RCTAztecView.InputState.getCurrentFocusedElement.mockReturnValue(
+			textInput
+		);
+
+		// Act
+		const { result } = renderHook( () =>
+			useTextInputOffset( scrollEnabled, scrollViewRef )
+		);
+		const getTextInputOffset = result.current[ 0 ];
+
+		// Assert
+		const offset = await getTextInputOffset( { caretY: -1 } );
+		expect( offset ).toBe( 110 );
+	} );
+} );

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

@@ -0,0 +1,87 @@
+/**
+ * External dependencies
+ */
+
+import { Keyboard } from 'react-native';
+
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useCallback, useState, useRef } from '@wordpress/element';
+
+/**
+ * Hook that adds Keyboard listeners to get the offset space
+ * when the keyboard is opened, taking into account focused AztecViews.
+ *
+ * @param {boolean}  scrollEnabled                Whether the scroll is enabled or not.
+ * @param {Function} shouldPreventAutomaticScroll Whether to prevent scrolling when there's a Keyboard offset set.
+ * @return {[number]} Keyboard offset.
+ */
+export default function useKeyboardOffset(
+	scrollEnabled,
+	shouldPreventAutomaticScroll
+) {
+	const [ keyboardOffset, setKeyboardOffset ] = useState( 0 );
+	const timeoutRef = useRef();
+
+	const onKeyboardDidHide = useCallback( () => {
+		if ( shouldPreventAutomaticScroll() ) {
+			clearTimeout( timeoutRef.current );
+			return;
+		}
+
+		// A timeout is being used to delay resetting the offset in cases
+		// where the focus is changed to a different TextInput.
+		clearTimeout( timeoutRef.current );
+		timeoutRef.current = setTimeout( () => {
+			setKeyboardOffset( 0 );
+		}, 200 );
+	}, [ shouldPreventAutomaticScroll ] );
+
+	const onKeyboardDidShow = useCallback( ( { endCoordinates } ) => {
+		clearTimeout( timeoutRef.current );
+		setKeyboardOffset( endCoordinates.height );
+	}, [] );
+
+	const onKeyboardWillShow = useCallback( () => {
+		clearTimeout( timeoutRef.current );
+	}, [] );
+
+	useEffect( () => {
+		let willShowSubscription;
+		let showSubscription;
+		let hideSubscription;
+
+		if ( scrollEnabled ) {
+			willShowSubscription = Keyboard.addListener(
+				'keyboardWillShow',
+				onKeyboardWillShow
+			);
+			showSubscription = Keyboard.addListener(
+				'keyboardDidShow',
+				onKeyboardDidShow
+			);
+			hideSubscription = Keyboard.addListener(
+				'keyboardDidHide',
+				onKeyboardDidHide
+			);
+		} else {
+			willShowSubscription?.remove();
+			showSubscription?.remove();
+			hideSubscription?.remove();
+		}
+
+		return () => {
+			clearTimeout( timeoutRef.current );
+			willShowSubscription?.remove();
+			showSubscription?.remove();
+			hideSubscription?.remove();
+		};
+	}, [
+		onKeyboardDidHide,
+		onKeyboardDidShow,
+		onKeyboardWillShow,
+		scrollEnabled,
+	] );
+	return [ keyboardOffset ];
+}

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

@@ -0,0 +1,105 @@
+/**
+ * External dependencies
+ */
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+/**
+ * WordPress dependencies
+ */
+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.
+ *
+ * @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 {SharedValue} scrollViewYOffset      Current offset position of the ScrollView.
+ * @return {Function[]} Function to scroll to the current TextInput's offset.
+ */
+export default function useScrollToTextInput(
+	extraScrollHeight,
+	keyboardOffset,
+	scrollEnabled,
+	scrollViewMeasurements,
+	scrollViewRef,
+	scrollViewYOffset
+) {
+	const { top, bottom } = useSafeAreaInsets();
+	const insets = top + bottom;
+
+	/**
+	 * Function to scroll to the current TextInput's offset.
+	 *
+	 * @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.
+	 */
+	const scrollToTextInputOffset = useCallback(
+		( caret, textInputOffset ) => {
+			const { caretHeight = DEFAULT_FONT_SIZE } = caret ?? {};
+
+			if (
+				! scrollViewRef.current ||
+				! scrollEnabled ||
+				! scrollViewMeasurements.current
+			) {
+				return;
+			}
+			const currentScrollViewYOffset = Math.max(
+				0,
+				scrollViewYOffset.value
+			);
+
+			// Scroll up.
+			if ( textInputOffset < currentScrollViewYOffset ) {
+				scrollViewRef.current.scrollTo( {
+					y: textInputOffset,
+					animated: true,
+				} );
+				return;
+			}
+
+			const availableScreenSpace = Math.abs(
+				Math.floor(
+					scrollViewMeasurements.current.height -
+						( keyboardOffset + extraScrollHeight + caretHeight )
+				)
+			);
+			const maxOffset = Math.floor(
+				currentScrollViewYOffset + availableScreenSpace
+			);
+
+			const isAtTheTop =
+				textInputOffset < scrollViewMeasurements.current.y + insets;
+
+			// Scroll down.
+			if ( textInputOffset > maxOffset && ! isAtTheTop ) {
+				scrollViewRef.current.scrollTo( {
+					y: textInputOffset - availableScreenSpace,
+					animated: true,
+				} );
+			}
+		},
+		[
+			extraScrollHeight,
+			insets,
+			keyboardOffset,
+			scrollEnabled,
+			scrollViewMeasurements,
+			scrollViewRef,
+			scrollViewYOffset,
+		]
+	);
+
+	return [ scrollToTextInputOffset ];
+}

package/src/mobile/keyboard-aware-flat-list/use-text-input-caret-position.native.js

@@ -0,0 +1,36 @@
+/**
+ * WordPress dependencies
+ */
+import RCTAztecView from '@wordpress/react-native-aztec';
+import { useCallback, useEffect, useState } from '@wordpress/element';
+
+/**
+ * Hook that listens to caret changes from AztecView TextInputs.
+ *
+ * @param {boolean} scrollEnabled Whether the scroll is enabled or not.
+ * @return {[number]} Current caret's data.
+ */
+export default function useTextInputCaretPosition( scrollEnabled ) {
+	const [ currentCaretData, setCurrentCaretData ] = useState();
+
+	const onCaretChange = useCallback( ( caret ) => {
+		setCurrentCaretData( caret );
+	}, [] );
+
+	useEffect( () => {
+		if ( scrollEnabled ) {
+			RCTAztecView.InputState.addCaretChangeListener( onCaretChange );
+		} else {
+			RCTAztecView.InputState.removeCaretChangeListener( onCaretChange );
+		}
+
+		return () => {
+			if ( scrollEnabled ) {
+				RCTAztecView.InputState.removeCaretChangeListener(
+					onCaretChange
+				);
+			}
+		};
+	}, [ scrollEnabled, onCaretChange ] );
+	return [ currentCaretData ];
+}

package/src/mobile/keyboard-aware-flat-list/use-text-input-offset.native.js

@@ -0,0 +1,54 @@
+/**
+ * WordPress dependencies
+ */
+import RCTAztecView from '@wordpress/react-native-aztec';
+import { useCallback } from '@wordpress/element';
+
+/** @typedef {import('@wordpress/element').RefObject} RefObject */
+/**
+ * Hook that calculates the currently focused TextInput's current
+ * caret Y coordinate position.
+ *
+ * @param {boolean}   scrollEnabled Whether the scroll is enabled or not.
+ * @param {RefObject} scrollViewRef ScrollView reference.
+ * @return {[Function]} Function to get the current TextInput's offset.
+ */
+export default function useTextInputOffset( scrollEnabled, scrollViewRef ) {
+	const getTextInputOffset = useCallback(
+		async ( caret ) => {
+			const { caretY = null } = caret ?? {};
+			const textInput =
+				RCTAztecView.InputState.getCurrentFocusedElement();
+
+			return new Promise( ( resolve ) => {
+				if (
+					scrollViewRef.current &&
+					textInput &&
+					scrollEnabled &&
+					caretY !== null
+				) {
+					textInput.measureLayout(
+						scrollViewRef.current,
+						( _x, y, _width, height ) => {
+							const caretYOffset =
+								// For cases where the caretY value is -1
+								// we use the y + height value, e.g the current
+								// character index is not valid or out of bounds
+								// see https://github.com/wordpress-mobile/AztecEditor-iOS/blob/4d0522d67b0056ac211466caaa76936cc5b4f947/Aztec/Classes/TextKit/TextView.swift#L762
+								caretY >= 0 && caretY < height
+									? y + caretY
+									: y + height;
+							resolve( Math.round( Math.abs( caretYOffset ) ) );
+						},
+						() => resolve( null )
+					);
+				} else {
+					resolve( null );
+				}
+			} );
+		},
+		[ scrollEnabled, scrollViewRef ]
+	);
+
+	return [ getTextInputOffset ];
+}

package/src/navigator/navigator-provider/component.tsx

@@ -147,6 +147,7 @@ function UnconnectedNavigatorProvider(
 			const {
 				focusTargetSelector,
 				isBack = false,
+				skipFocus = false,
 				...restOptions
 			} = options;
 
@@ -168,6 +169,7 @@ function UnconnectedNavigatorProvider(
 					path,
 					isBack,
 					hasRestoredFocus: false,
+					skipFocus,
 				};
 
 				if ( prevLocationHistory.length < 1 ) {

package/src/navigator/navigator-screen/component.tsx

@@ -43,7 +43,7 @@ const animationExitDelay = 0;
 // as some of them would overlap with HTML props (e.g. `onAnimationStart`, ...)
 type Props = Omit<
 	WordPressComponentProps< NavigatorScreenProps, 'div', false >,
-	keyof MotionProps
+	Exclude< keyof MotionProps, 'style' >
 >;
 
 function UnconnectedNavigatorScreen(
@@ -100,11 +100,13 @@ function UnconnectedNavigatorScreen(
 		// - when the screen becomes visible
 		// - if the wrapper ref has been assigned
 		// - if focus hasn't already been restored for the current location
+		// - if the `skipFocus` option is not set to `true`. This is useful when we trigger the navigation outside of NavigatorScreen.
 		if (
 			isInitialLocation ||
 			! isMatch ||
 			! wrapperRef.current ||
-			locationRef.current.hasRestoredFocus
+			locationRef.current.hasRestoredFocus ||
+			location.skipFocus
 		) {
 			return;
 		}
@@ -143,6 +145,7 @@ function UnconnectedNavigatorScreen(
 		isMatch,
 		location.isBack,
 		location.focusTargetSelector,
+		location.skipFocus,
 	] );
 
 	const mergedWrapperRef = useMergeRefs( [ forwardedRef, wrapperRef ] );

package/src/navigator/stories/index.tsx

@@ -298,3 +298,71 @@ export const NestedNavigator: ComponentStory< typeof NavigatorProvider > =
 NestedNavigator.args = {
 	initialPath: '/child2/grandchild',
 };
+
+const NavigatorButtonWithSkipFocus = ( {
+	path,
+	onClick,
+	...props
+}: React.ComponentProps< typeof NavigatorButton > ) => {
+	const { goTo } = useNavigator();
+
+	return (
+		<Button
+			{ ...props }
+			onClick={ ( e: React.MouseEvent< HTMLButtonElement > ) => {
+				goTo( path, { skipFocus: true } );
+				onClick?.( e );
+			} }
+		/>
+	);
+};
+
+export const SkipFocus: ComponentStory< typeof NavigatorProvider > = (
+	args
+) => {
+	return <NavigatorProvider { ...args } />;
+};
+SkipFocus.args = {
+	initialPath: '/',
+	children: (
+		<>
+			<div
+				style={ {
+					height: 250,
+					border: '1px solid black',
+				} }
+			>
+				<NavigatorScreen
+					path="/"
+					style={ {
+						height: '100%',
+					} }
+				>
+					<h1>Home screen</h1>
+					<NavigatorButton variant="secondary" path="/child">
+						Go to child screen.
+					</NavigatorButton>
+				</NavigatorScreen>
+				<NavigatorScreen
+					path="/child"
+					style={ {
+						height: '100%',
+					} }
+				>
+					<h2>Child screen</h2>
+					<NavigatorToParentButton variant="secondary">
+						Go to parent screen.
+					</NavigatorToParentButton>
+				</NavigatorScreen>
+			</div>
+
+			<NavigatorButtonWithSkipFocus
+				variant="secondary"
+				path="/child"
+				style={ { margin: '1rem 2rem' } }
+			>
+				Go to child screen, but keep focus on this button
+			</NavigatorButtonWithSkipFocus>
+		</>
+	),
+};

package/src/navigator/test/index.tsx

@@ -22,6 +22,7 @@ import {
 	NavigatorToParentButton,
 	useNavigator,
 } from '..';
+import type { NavigateOptions } from '../types';
 
 const INVALID_HTML_ATTRIBUTE = {
 	raw: ' "\'><=invalid_path',
@@ -57,6 +58,7 @@ const BUTTON_TEXT = {
 		'Navigate to screen with an invalid HTML value as a path.',
 	back: 'Go back',
 	backUsingGoTo: 'Go back using goTo',
+	goToWithSkipFocus: 'Go to with skipFocus',
 };
 
 type CustomTestOnClickHandler = (
@@ -64,6 +66,7 @@ type CustomTestOnClickHandler = (
 		| {
 				type: 'goTo';
 				path: string;
+				options?: NavigateOptions;
 		  }
 		| { type: 'goBack' }
 		| { type: 'goToParent' }
@@ -108,6 +111,26 @@ function CustomNavigatorGoToBackButton( {
 	);
 }
 
+function CustomNavigatorGoToSkipFocusButton( {
+	path,
+	onClick,
+	...props
+}: Omit< ComponentPropsWithoutRef< typeof NavigatorButton >, 'onClick' > & {
+	onClick?: CustomTestOnClickHandler;
+} ) {
+	const { goTo } = useNavigator();
+	return (
+		<Button
+			onClick={ () => {
+				goTo( path, { skipFocus: true } );
+				// Used to spy on the values passed to `navigator.goTo`.
+				onClick?.( { type: 'goTo', path } );
+			} }
+			{ ...props }
+		/>
+	);
+}
+
 function CustomNavigatorBackButton( {
 	onClick,
 	...props
@@ -342,6 +365,12 @@ const MyHierarchicalNavigation = ( {
 						{ BUTTON_TEXT.backUsingGoTo }
 					</CustomNavigatorGoToBackButton>
 				</NavigatorScreen>
+				<CustomNavigatorGoToSkipFocusButton
+					path={ PATHS.NESTED }
+					onClick={ onNavigatorButtonClick }
+				>
+					{ BUTTON_TEXT.goToWithSkipFocus }
+				</CustomNavigatorGoToSkipFocusButton>
 			</NavigatorProvider>
 		</>
 	);
@@ -716,6 +745,29 @@ describe( 'Navigator', () => {
 			await user.click( getNavigationButton( 'back' ) );
 			expect( getNavigationButton( 'toChildScreen' ) ).toHaveFocus();
 		} );
+
+		it( 'should skip focus based on location `skipFocus` option', async () => {
+			const user = userEvent.setup();
+			render( <MyHierarchicalNavigation /> );
+
+			// Navigate to child screen with skipFocus.
+			await user.click( getNavigationButton( 'goToWithSkipFocus' ) );
+			expect( queryScreen( 'home' ) ).not.toBeInTheDocument();
+			expect( getScreen( 'nested' ) ).toBeInTheDocument();
+
+			// The clicked button should remain focused.
+			expect( getNavigationButton( 'goToWithSkipFocus' ) ).toHaveFocus();
+
+			// Navigate back to parent screen.
+			await user.click( getNavigationButton( 'back' ) );
+			expect( getScreen( 'child' ) ).toBeInTheDocument();
+			// The first tabbable element receives focus.
+			expect(
+				screen.getByRole( 'button', {
+					name: 'First tabbable child screen button',
+				} )
+			).toHaveFocus();
+		} );
 	} );
 
 	describe( 'animation', () => {

package/src/navigator/types.ts

@@ -10,9 +10,10 @@ import type { ButtonAsButtonProps } from '../button/types';
 
 export type MatchParams = Record< string, string | string[] >;
 
-type NavigateOptions = {
+export type NavigateOptions = {
 	focusTargetSelector?: string;
 	isBack?: boolean;
+	skipFocus?: boolean;
 };
 
 export type NavigatorLocation = NavigateOptions & {

package/src/query-controls/author-select.tsx

@@ -27,6 +27,7 @@ export default function AuthorSelect( {
 					? String( selectedAuthorId )
 					: undefined
 			}
+			__nextHasNoMarginBottom
 		/>
 	);
 }

package/src/query-controls/category-select.tsx

@@ -36,6 +36,7 @@ export default function CategorySelect( {
 					: undefined
 			}
 			{ ...props }
+			__nextHasNoMarginBottom
 		/>
 	);
 }