add unit test

packages/components/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,13 +58,15 @@ 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 = (
 	args:
 		| {
 				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', () => {

packages/components/src/navigator/types.ts

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