@wordpress/components 23.3.1 → 23.3.2

package/src/navigator/stories/index.tsx

@@ -8,13 +8,15 @@ import type { ComponentMeta, ComponentStory } from '@storybook/react';
  */
 import Button from '../../button';
 import { Card, CardBody, CardFooter, CardHeader } from '../../card';
-import { HStack } from '../../h-stack';
+import { VStack } from '../../v-stack';
 import Dropdown from '../../dropdown';
 import {
 	NavigatorProvider,
 	NavigatorScreen,
 	NavigatorButton,
 	NavigatorBackButton,
+	NavigatorToParentButton,
+	useNavigator,
 } from '..';
 
 const meta: ComponentMeta< typeof NavigatorProvider > = {
@@ -46,7 +48,7 @@ const Template: ComponentStory< typeof NavigatorProvider > = ( {
 				<CardBody>
 					<p>This is the home screen.</p>
 
-					<HStack justify="flex-start" wrap>
+					<VStack alignment="left">
 						<NavigatorButton variant="secondary" path="/child">
 							Navigate to child screen.
 						</NavigatorButton>
@@ -62,6 +64,10 @@ const Template: ComponentStory< typeof NavigatorProvider > = ( {
 							Navigate to screen with sticky content.
 						</NavigatorButton>
 
+						<NavigatorButton variant="secondary" path="/product/1">
+							Navigate to product screen with id 1.
+						</NavigatorButton>
+
 						<Dropdown
 							renderToggle={ ( {
 								isOpen,
@@ -86,7 +92,7 @@ const Template: ComponentStory< typeof NavigatorProvider > = ( {
 								</Card>
 							) }
 						/>
-					</HStack>
+					</VStack>
 				</CardBody>
 			</Card>
 		</NavigatorScreen>
@@ -166,6 +172,10 @@ const Template: ComponentStory< typeof NavigatorProvider > = ( {
 				</CardFooter>
 			</Card>
 		</NavigatorScreen>
+
+		<NavigatorScreen path="/product/:id">
+			<ProductDetails />
+		</NavigatorScreen>
 	</NavigatorProvider>
 );
 
@@ -208,3 +218,83 @@ function MetaphorIpsum( { quantity }: { quantity: number } ) {
 		</>
 	);
 }
+
+function ProductDetails() {
+	const { params } = useNavigator();
+
+	return (
+		<Card>
+			<CardBody>
+				<NavigatorBackButton variant="secondary">
+					Go back
+				</NavigatorBackButton>
+				<p>This is the screen for the product with id: { params.id }</p>
+			</CardBody>
+		</Card>
+	);
+}
+
+const NestedNavigatorTemplate: ComponentStory< typeof NavigatorProvider > = ( {
+	style,
+	...props
+} ) => (
+	<NavigatorProvider
+		style={ { ...style, height: '100vh', maxHeight: '450px' } }
+		{ ...props }
+	>
+		<NavigatorScreen path="/">
+			<Card>
+				<CardBody>
+					<NavigatorButton variant="secondary" path="/child1">
+						Go to first child.
+					</NavigatorButton>
+					<NavigatorButton variant="secondary" path="/child2">
+						Go to second child.
+					</NavigatorButton>
+				</CardBody>
+			</Card>
+		</NavigatorScreen>
+		<NavigatorScreen path="/child1">
+			<Card>
+				<CardBody>
+					This is the first child
+					<NavigatorToParentButton variant="secondary">
+						Go back to parent
+					</NavigatorToParentButton>
+				</CardBody>
+			</Card>
+		</NavigatorScreen>
+		<NavigatorScreen path="/child2">
+			<Card>
+				<CardBody>
+					This is the second child
+					<NavigatorToParentButton variant="secondary">
+						Go back to parent
+					</NavigatorToParentButton>
+					<NavigatorButton
+						variant="secondary"
+						path="/child2/grandchild"
+					>
+						Go to grand child.
+					</NavigatorButton>
+				</CardBody>
+			</Card>
+		</NavigatorScreen>
+		<NavigatorScreen path="/child2/grandchild">
+			<Card>
+				<CardBody>
+					This is the grand child
+					<NavigatorToParentButton variant="secondary">
+						Go back to parent
+					</NavigatorToParentButton>
+				</CardBody>
+			</Card>
+		</NavigatorScreen>
+	</NavigatorProvider>
+);
+
+export const NestedNavigator: ComponentStory< typeof NavigatorProvider > =
+	NestedNavigatorTemplate.bind( {} );
+NestedNavigator.args = {
+	initialPath: '/child2/grandchild',
+};

package/src/navigator/test/index.tsx

@@ -13,11 +13,14 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
+import Button from '../../button';
 import {
 	NavigatorProvider,
 	NavigatorScreen,
 	NavigatorButton,
 	NavigatorBackButton,
+	NavigatorToParentButton,
+	useNavigator,
 } from '..';
 
 jest.mock( 'framer-motion', () => {
@@ -50,6 +53,9 @@ const PATHS = {
 	HOME: '/',
 	CHILD: '/child',
 	NESTED: '/child/nested',
+	PRODUCT_PATTERN: '/product/:productId',
+	PRODUCT_1: '/product/1',
+	PRODUCT_2: '/product/2',
 	INVALID_HTML_ATTRIBUTE: INVALID_HTML_ATTRIBUTE.raw,
 	NOT_FOUND: '/not-found',
 };
@@ -58,6 +64,7 @@ const SCREEN_TEXT = {
 	home: 'This is the home screen.',
 	child: 'This is the child screen.',
 	nested: 'This is the nested screen.',
+	product: 'This is the product screen.',
 	invalidHtmlPath: 'This is the screen with an invalid HTML value as a path.',
 };
 
@@ -65,9 +72,12 @@ const BUTTON_TEXT = {
 	toNonExistingScreen: 'Navigate to non-existing screen.',
 	toChildScreen: 'Navigate to child screen.',
 	toNestedScreen: 'Navigate to nested screen.',
+	toProductScreen1: 'Navigate to product 1 screen.',
+	toProductScreen2: 'Navigate to product 2 screen.',
 	toInvalidHtmlPathScreen:
 		'Navigate to screen with an invalid HTML value as a path.',
 	back: 'Go back',
+	backUsingGoTo: 'Go back using goTo',
 };
 
 type CustomTestOnClickHandler = (
@@ -77,6 +87,7 @@ type CustomTestOnClickHandler = (
 				path: string;
 		  }
 		| { type: 'goBack' }
+		| { type: 'goToParent' }
 ) => void;
 
 function CustomNavigatorButton( {
@@ -98,20 +109,21 @@ function CustomNavigatorButton( {
 	);
 }
 
-function CustomNavigatorButtonWithFocusRestoration( {
+function CustomNavigatorGoToBackButton( {
 	path,
 	onClick,
 	...props
 }: Omit< ComponentPropsWithoutRef< typeof NavigatorButton >, 'onClick' > & {
 	onClick?: CustomTestOnClickHandler;
 } ) {
+	const { goTo } = useNavigator();
 	return (
-		<NavigatorButton
+		<Button
 			onClick={ () => {
+				goTo( path, { isBack: true } );
 				// Used to spy on the values passed to `navigator.goTo`.
 				onClick?.( { type: 'goTo', path } );
 			} }
-			path={ path }
 			{ ...props }
 		/>
 	);
@@ -134,6 +146,41 @@ function CustomNavigatorBackButton( {
 	);
 }
 
+function CustomNavigatorToParentButton( {
+	onClick,
+	...props
+}: Omit< ComponentPropsWithoutRef< typeof NavigatorBackButton >, 'onClick' > & {
+	onClick?: CustomTestOnClickHandler;
+} ) {
+	return (
+		<NavigatorToParentButton
+			onClick={ () => {
+				// Used to spy on the values passed to `navigator.goBack`.
+				onClick?.( { type: 'goToParent' } );
+			} }
+			{ ...props }
+		/>
+	);
+}
+
+const ProductScreen = ( {
+	onBackButtonClick,
+}: {
+	onBackButtonClick?: CustomTestOnClickHandler;
+} ) => {
+	const { params } = useNavigator();
+
+	return (
+		<NavigatorScreen path={ PATHS.PRODUCT_PATTERN }>
+			<p>{ SCREEN_TEXT.product }</p>
+			<p>Product ID is { params.productId }</p>
+			<CustomNavigatorBackButton onClick={ onBackButtonClick }>
+				{ BUTTON_TEXT.back }
+			</CustomNavigatorBackButton>
+		</NavigatorScreen>
+	);
+};
+
 const MyNavigation = ( {
 	initialPath = PATHS.HOME,
 	onNavigatorButtonClick,
@@ -148,6 +195,12 @@ const MyNavigation = ( {
 			<NavigatorProvider initialPath={ initialPath }>
 				<NavigatorScreen path={ PATHS.HOME }>
 					<p>{ SCREEN_TEXT.home }</p>
+					{ /*
+					 * A button useful to test focus restoration. This button is the first
+					 * tabbable item in the screen, but should not receive focus when
+					 * navigating to screen as a result of a backwards navigation.
+					 */ }
+					<button>First tabbable home screen button</button>
 					<CustomNavigatorButton
 						path={ PATHS.NOT_FOUND }
 						onClick={ onNavigatorButtonClick }
@@ -160,6 +213,18 @@ const MyNavigation = ( {
 					>
 						{ BUTTON_TEXT.toChildScreen }
 					</CustomNavigatorButton>
+					<CustomNavigatorButton
+						path={ PATHS.PRODUCT_1 }
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.toProductScreen1 }
+					</CustomNavigatorButton>
+					<CustomNavigatorButton
+						path={ PATHS.PRODUCT_2 }
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.toProductScreen2 }
+					</CustomNavigatorButton>
 					<CustomNavigatorButton
 						path={ PATHS.INVALID_HTML_ATTRIBUTE }
 						onClick={ onNavigatorButtonClick }
@@ -170,12 +235,18 @@ const MyNavigation = ( {
 
 				<NavigatorScreen path={ PATHS.CHILD }>
 					<p>{ SCREEN_TEXT.child }</p>
-					<CustomNavigatorButtonWithFocusRestoration
+					{ /*
+					 * A button useful to test focus restoration. This button is the first
+					 * tabbable item in the screen, but should not receive focus when
+					 * navigating to screen as a result of a backwards navigation.
+					 */ }
+					<button>First tabbable child screen button</button>
+					<CustomNavigatorButton
 						path={ PATHS.NESTED }
 						onClick={ onNavigatorButtonClick }
 					>
 						{ BUTTON_TEXT.toNestedScreen }
-					</CustomNavigatorButtonWithFocusRestoration>
+					</CustomNavigatorButton>
 					<CustomNavigatorBackButton
 						onClick={ onNavigatorButtonClick }
 					>
@@ -203,6 +274,8 @@ const MyNavigation = ( {
 					</CustomNavigatorBackButton>
 				</NavigatorScreen>
 
+				<ProductScreen onBackButtonClick={ onNavigatorButtonClick } />
+
 				<NavigatorScreen path={ PATHS.INVALID_HTML_ATTRIBUTE }>
 					<p>{ SCREEN_TEXT.invalidHtmlPath }</p>
 					<CustomNavigatorBackButton
@@ -229,6 +302,72 @@ const MyNavigation = ( {
 	);
 };
 
+const MyHierarchicalNavigation = ( {
+	initialPath = PATHS.HOME,
+	onNavigatorButtonClick,
+}: {
+	initialPath?: string;
+	onNavigatorButtonClick?: CustomTestOnClickHandler;
+} ) => {
+	return (
+		<>
+			<NavigatorProvider initialPath={ initialPath }>
+				<NavigatorScreen path={ PATHS.HOME }>
+					<p>{ SCREEN_TEXT.home }</p>
+					{ /*
+					 * A button useful to test focus restoration. This button is the first
+					 * tabbable item in the screen, but should not receive focus when
+					 * navigating to screen as a result of a backwards navigation.
+					 */ }
+					<button>First tabbable home screen button</button>
+					<CustomNavigatorButton
+						path={ PATHS.CHILD }
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.toChildScreen }
+					</CustomNavigatorButton>
+				</NavigatorScreen>
+
+				<NavigatorScreen path={ PATHS.CHILD }>
+					<p>{ SCREEN_TEXT.child }</p>
+					{ /*
+					 * A button useful to test focus restoration. This button is the first
+					 * tabbable item in the screen, but should not receive focus when
+					 * navigating to screen as a result of a backwards navigation.
+					 */ }
+					<button>First tabbable child screen button</button>
+					<CustomNavigatorButton
+						path={ PATHS.NESTED }
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.toNestedScreen }
+					</CustomNavigatorButton>
+					<CustomNavigatorToParentButton
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.back }
+					</CustomNavigatorToParentButton>
+				</NavigatorScreen>
+
+				<NavigatorScreen path={ PATHS.NESTED }>
+					<p>{ SCREEN_TEXT.nested }</p>
+					<CustomNavigatorToParentButton
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.back }
+					</CustomNavigatorToParentButton>
+					<CustomNavigatorGoToBackButton
+						path={ PATHS.CHILD }
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.backUsingGoTo }
+					</CustomNavigatorGoToBackButton>
+				</NavigatorScreen>
+			</NavigatorProvider>
+		</>
+	);
+};
+
 const getScreen = ( screenKey: keyof typeof SCREEN_TEXT ) =>
 	screen.getByText( SCREEN_TEXT[ screenKey ] );
 const queryScreen = ( screenKey: keyof typeof SCREEN_TEXT ) =>
@@ -369,7 +508,7 @@ describe( 'Navigator', () => {
 		} );
 	} );
 
-	it( 'should not rended anything if the path does not match any available screen', async () => {
+	it( 'should not render anything if the path does not match any available screen', async () => {
 		const spy = jest.fn();
 
 		const user = userEvent.setup();
@@ -396,8 +535,6 @@ describe( 'Navigator', () => {
 	} );
 
 	it( 'should escape the value of the `path` prop', async () => {
-		const user = userEvent.setup();
-
 		render( <MyNavigation /> );
 
 		expect( getScreen( 'home' ) ).toBeInTheDocument();
@@ -407,24 +544,42 @@ describe( 'Navigator', () => {
 
 		// The following line tests the implementation details, but it's necessary
 		// as this would be otherwise transparent to the user.
+		// A potential way would be to check if an invalid HTML attribute could
+		// be detected in the tests (by JSDom or any other plugin). We could then
+		// make sure that an invalid path would not error because it's escaped
+		// correctly.
 		expect(
 			getNavigationButton( 'toInvalidHtmlPathScreen' )
 		).toHaveAttribute( 'id', INVALID_HTML_ATTRIBUTE.escaped );
+	} );
 
-		// Navigate to screen with an invalid HTML value for its `path`.
-		await user.click( getNavigationButton( 'toInvalidHtmlPathScreen' ) );
+	it( 'should match correctly paths with named arguments', async () => {
+		const user = userEvent.setup();
 
-		expect( getScreen( 'invalidHtmlPath' ) ).toBeInTheDocument();
-		expect( getNavigationButton( 'back' ) ).toBeInTheDocument();
+		render( <MyNavigation /> );
+
+		expect( getScreen( 'home' ) ).toBeInTheDocument();
 
-		// Navigate back to home screen, check that the focus restoration selector
-		// worked correctly despite the escaping.
+		// Navigate to Product 1 screen
+		await user.click( getNavigationButton( 'toProductScreen1' ) );
+
+		expect( getScreen( 'product' ) ).toBeInTheDocument();
+
+		// Check that named parameter is extracted correctly
+		expect( screen.getByText( 'Product ID is 1' ) ).toBeInTheDocument();
+
+		// Navigate back to home screen
 		await user.click( getNavigationButton( 'back' ) );
 
 		expect( getScreen( 'home' ) ).toBeInTheDocument();
-		expect(
-			getNavigationButton( 'toInvalidHtmlPathScreen' )
-		).toHaveFocus();
+
+		// Navigate to Product 2 screen
+		await user.click( getNavigationButton( 'toProductScreen2' ) );
+
+		expect( getScreen( 'product' ) ).toBeInTheDocument();
+
+		// Check that named parameter is extracted correctly
+		expect( screen.getByText( 'Product ID is 2' ) ).toBeInTheDocument();
 	} );
 
 	describe( 'focus management', () => {
@@ -437,7 +592,11 @@ describe( 'Navigator', () => {
 			await user.click( getNavigationButton( 'toChildScreen' ) );
 
 			// The first tabbable element receives focus.
-			expect( getNavigationButton( 'toNestedScreen' ) ).toHaveFocus();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'First tabbable child screen button',
+				} )
+			).toHaveFocus();
 
 			// Navigate to nested screen.
 			await user.click( getNavigationButton( 'toNestedScreen' ) );
@@ -448,14 +607,29 @@ describe( 'Navigator', () => {
 			// Navigate back to child screen.
 			await user.click( getNavigationButton( 'back' ) );
 
-			// The first tabbable element receives focus.
+			// Focus is restored on the last element that had focus when the
+			// navigation away from the screen occurred.
 			expect( getNavigationButton( 'toNestedScreen' ) ).toHaveFocus();
 
-			// Navigate back to home screen, check that focus was correctly restored.
+			// Navigate back to home screen.
 			await user.click( getNavigationButton( 'back' ) );
 
-			// The first tabbable element receives focus.
+			// Focus is restored on the last element that had focus when the
+			// navigation away from the screen occurred.
 			expect( getNavigationButton( 'toChildScreen' ) ).toHaveFocus();
+
+			// Navigate to product screen for product 2
+			await user.click( getNavigationButton( 'toProductScreen2' ) );
+
+			// The first tabbable element receives focus.
+			expect( getNavigationButton( 'back' ) ).toHaveFocus();
+
+			// Navigate back to home screen.
+			await user.click( getNavigationButton( 'back' ) );
+
+			// Focus is restored on the last element that had focus when the
+			// navigation away from the screen occurred.
+			expect( getNavigationButton( 'toProductScreen2' ) ).toHaveFocus();
 		} );
 
 		it( 'should keep focus on an active element inside navigator, while re-rendering', async () => {
@@ -467,7 +641,11 @@ describe( 'Navigator', () => {
 			await user.click( getNavigationButton( 'toChildScreen' ) );
 
 			// The first tabbable element receives focus.
-			expect( getNavigationButton( 'toNestedScreen' ) ).toHaveFocus();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'First tabbable child screen button',
+				} )
+			).toHaveFocus();
 
 			// Interact with the inner input.
 			// The focus should stay on the input element.
@@ -485,7 +663,11 @@ describe( 'Navigator', () => {
 			await user.click( getNavigationButton( 'toChildScreen' ) );
 
 			// The first tabbable element receives focus.
-			expect( getNavigationButton( 'toNestedScreen' ) ).toHaveFocus();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'First tabbable child screen button',
+				} )
+			).toHaveFocus();
 
 			// Interact with the outer input.
 			// The focus should stay on the input element.
@@ -493,5 +675,67 @@ describe( 'Navigator', () => {
 			await user.type( outerInput, 'd' );
 			expect( outerInput ).toHaveFocus();
 		} );
+
+		it( 'should restore focus correctly even when the `path` needs to be escaped', async () => {
+			const user = userEvent.setup();
+
+			render( <MyNavigation /> );
+
+			expect( getScreen( 'home' ) ).toBeInTheDocument();
+
+			// Navigate to screen with an invalid HTML value for its `path`.
+			await user.click(
+				getNavigationButton( 'toInvalidHtmlPathScreen' )
+			);
+
+			expect( getScreen( 'invalidHtmlPath' ) ).toBeInTheDocument();
+
+			// Navigate back to home screen, check that the focus restoration selector
+			// worked correctly despite the escaping.
+			await user.click( getNavigationButton( 'back' ) );
+
+			expect( getScreen( 'home' ) ).toBeInTheDocument();
+			expect(
+				getNavigationButton( 'toInvalidHtmlPathScreen' )
+			).toHaveFocus();
+		} );
+
+		it( 'should restore focus while using goTo and goToParent', async () => {
+			const user = userEvent.setup();
+
+			render( <MyHierarchicalNavigation /> );
+
+			expect( getScreen( 'home' ) ).toBeInTheDocument();
+
+			// Navigate to child screen.
+			await user.click( getNavigationButton( 'toChildScreen' ) );
+			expect( getScreen( 'child' ) ).toBeInTheDocument();
+
+			// Navigate to nested screen.
+			await user.click( getNavigationButton( 'toNestedScreen' ) );
+			expect( getScreen( 'nested' ) ).toBeInTheDocument();
+			expect( getNavigationButton( 'back' ) ).toBeInTheDocument();
+
+			// Navigate back to child screen using the back button.
+			await user.click( getNavigationButton( 'back' ) );
+			expect( getScreen( 'child' ) ).toBeInTheDocument();
+			expect( getNavigationButton( 'toNestedScreen' ) ).toHaveFocus();
+
+			// Re navigate to nested screen.
+			await user.click( getNavigationButton( 'toNestedScreen' ) );
+			expect( getScreen( 'nested' ) ).toBeInTheDocument();
+			expect(
+				getNavigationButton( 'backUsingGoTo' )
+			).toBeInTheDocument();
+
+			// Navigate back to child screen using the go to button.
+			await user.click( getNavigationButton( 'backUsingGoTo' ) );
+			expect( getScreen( 'child' ) ).toBeInTheDocument();
+			expect( getNavigationButton( 'toNestedScreen' ) ).toHaveFocus();
+
+			// Navigate back to home screen.
+			await user.click( getNavigationButton( 'back' ) );
+			expect( getNavigationButton( 'toChildScreen' ) ).toHaveFocus();
+		} );
 	} );
 } );