@wordpress/components 28.5.0 → 28.7.0

package/src/navigator/navigator-to-parent-button/README.md

@@ -4,6 +4,8 @@
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>
 
+This component is deprecated. Please use the [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) component instead.
+
 The `NavigatorToParentButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorScreen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) components (or the `useNavigator` hook).
 
 ## Usage

package/src/navigator/navigator-to-parent-button/component.tsx

@@ -1,62 +1,33 @@
 /**
- * External dependencies
+ * WordPress dependencies
  */
-import type { ForwardedRef } from 'react';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
  */
+import { NavigatorBackButton } from '../navigator-back-button/component';
 import type { WordPressComponentProps } from '../../context';
 import { contextConnect } from '../../context';
-import { View } from '../../view';
-import { useNavigatorBackButton } from '../navigator-back-button/hook';
-import type { NavigatorToParentButtonProps } from '../types';
+import type { NavigatorBackButtonProps } from '../types';
 
 function UnconnectedNavigatorToParentButton(
-	props: WordPressComponentProps< NavigatorToParentButtonProps, 'button' >,
-	forwardedRef: ForwardedRef< any >
+	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >,
+	forwardedRef: React.ForwardedRef< any >
 ) {
-	const navigatorToParentButtonProps = useNavigatorBackButton( {
-		...props,
-		goToParent: true,
+	deprecated( 'wp.components.NavigatorToParentButton', {
+		since: '6.7',
+		alternative: 'wp.components.NavigatorBackButton',
 	} );
 
-	return <View ref={ forwardedRef } { ...navigatorToParentButtonProps } />;
+	return <NavigatorBackButton ref={ forwardedRef } { ...props } />;
 }
 
-/*
- * The `NavigatorToParentButton` component can be used to navigate to a screen and
- * should be used in combination with the `NavigatorProvider`, the
- * `NavigatorScreen` and the `NavigatorButton` components (or the `useNavigator`
- * hook).
- *
- * @example
- * ```jsx
- * import {
- *   __experimentalNavigatorProvider as NavigatorProvider,
- *   __experimentalNavigatorScreen as NavigatorScreen,
- *   __experimentalNavigatorButton as NavigatorButton,
- *   __experimentalNavigatorToParentButton as NavigatorToParentButton,
- * } from '@wordpress/components';
- *
- * const MyNavigation = () => (
- *   <NavigatorProvider initialPath="/">
- *     <NavigatorScreen path="/">
- *       <p>This is the home screen.</p>
- *        <NavigatorButton path="/child">
- *          Navigate to child screen.
- *       </NavigatorButton>
- *     </NavigatorScreen>
+/**
+ * _Note: this component is deprecated. Please use the `NavigatorBackButton`
+ * component instead._
  *
- *     <NavigatorScreen path="/child">
- *       <p>This is the child screen.</p>
- *       <NavigatorToParentButton>
- *         Go to parent
- *       </NavigatorToParentButton>
- *     </NavigatorScreen>
- *   </NavigatorProvider>
- * );
- * ```
+ * @deprecated
  */
 export const NavigatorToParentButton = contextConnect(
 	UnconnectedNavigatorToParentButton,

package/src/navigator/stories/index.story.tsx

@@ -7,17 +7,15 @@ import type { Meta, StoryObj } from '@storybook/react';
  * Internal dependencies
  */
 import Button from '../../button';
-import { Card, CardBody, CardFooter, CardHeader } from '../../card';
 import { VStack } from '../../v-stack';
-import Dropdown from '../../dropdown';
 import {
 	NavigatorProvider,
 	NavigatorScreen,
 	NavigatorButton,
 	NavigatorBackButton,
-	NavigatorToParentButton,
 	useNavigator,
 } from '..';
+import { HStack } from '../../h-stack';
 
 const meta: Meta< typeof NavigatorProvider > = {
 	component: NavigatorProvider,
@@ -33,268 +31,106 @@ const meta: Meta< typeof NavigatorProvider > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 	},
+	decorators: [
+		( Story ) => {
+			return (
+				<>
+					<style>{ `
+					  /* These attributes are a private implementation detail of the
+						  Navigator component. Do not use outside of its source code. */
+						[data-wp-component="NavigatorProvider"] {
+							height: calc(100vh - 2rem);
+							max-height: 250px;
+
+						}
+						[data-wp-component="NavigatorScreen"]:not([data-sticky]) {
+							padding: 8px;
+						}
+					` }</style>
+					<Story />
+				</>
+			);
+		},
+	],
 };
 export default meta;
 
 export const Default: StoryObj< typeof NavigatorProvider > = {
 	args: {
 		initialPath: '/',
-		style: { height: '100vh', maxHeight: '450px' },
 		children: (
 			<>
 				<NavigatorScreen path="/">
-					<Card>
-						<CardBody>
-							<p>This is the home screen.</p>
+					<h2>This is the home screen.</h2>
 
-							<VStack alignment="left">
-								<NavigatorButton
-									variant="secondary"
-									path="/child"
-								>
-									Navigate to child screen.
-								</NavigatorButton>
-
-								<NavigatorButton
-									variant="secondary"
-									path="/overflow-child"
-								>
-									Navigate to screen with horizontal overflow.
-								</NavigatorButton>
-
-								<NavigatorButton
-									variant="secondary"
-									path="/stickies"
-								>
-									Navigate to screen with sticky content.
-								</NavigatorButton>
+					<VStack alignment="left">
+						<NavigatorButton variant="primary" path="/child">
+							Go to child screen.
+						</NavigatorButton>
 
-								<NavigatorButton
-									variant="secondary"
-									path="/product/1"
-								>
-									Navigate to product screen with id 1.
-								</NavigatorButton>
+						<NavigatorButton variant="primary" path="/product/1">
+							Go to dynamic path screen with id 1.
+						</NavigatorButton>
 
-								<Dropdown
-									renderToggle={ ( {
-										isOpen,
-										onToggle,
-									}: {
-										// TODO: remove once `Dropdown` is refactored to TypeScript
-										isOpen: boolean;
-										onToggle: () => void;
-									} ) => (
-										<Button
-											onClick={ onToggle }
-											aria-expanded={ isOpen }
-											variant="primary"
-										>
-											Open test dialog
-										</Button>
-									) }
-									renderContent={ () => (
-										<Card>
-											<CardHeader>Go</CardHeader>
-											<CardBody>Stuff</CardBody>
-										</Card>
-									) }
-								/>
-							</VStack>
-						</CardBody>
-					</Card>
+						<NavigatorButton variant="primary" path="/product/2">
+							Go to dynamic path screen with id 2.
+						</NavigatorButton>
+					</VStack>
 				</NavigatorScreen>
 
 				<NavigatorScreen path="/child">
-					<Card>
-						<CardBody>
-							<p>This is the child screen.</p>
-							<NavigatorBackButton variant="secondary">
-								Go back
-							</NavigatorBackButton>
-						</CardBody>
-					</Card>
-				</NavigatorScreen>
-
-				<NavigatorScreen path="/overflow-child">
-					<Card>
-						<CardBody>
-							<NavigatorBackButton variant="secondary">
-								Go back
-							</NavigatorBackButton>
-							<div
-								style={ {
-									display: 'inline-block',
-									background: 'papayawhip',
-								} }
-							>
-								<span
-									style={ {
-										color: 'palevioletred',
-										whiteSpace: 'nowrap',
-										fontSize: '42vw',
-									} }
-								>
-									¯\_(ツ)_/¯
-								</span>
-							</div>
-						</CardBody>
-					</Card>
+					<h2>This is the child screen.</h2>
+					<HStack spacing={ 2 } alignment="left">
+						<NavigatorBackButton variant="secondary">
+							Go back
+						</NavigatorBackButton>
+
+						<NavigatorButton
+							variant="primary"
+							path="/child/grandchild"
+						>
+							Go to grand child screen.
+						</NavigatorButton>
+					</HStack>
 				</NavigatorScreen>
 
-				<NavigatorScreen path="/stickies">
-					<Card>
-						<CardHeader style={ getStickyStyles( { zIndex: 2 } ) }>
-							<NavigatorBackButton variant="secondary">
-								Go back
-							</NavigatorBackButton>
-						</CardHeader>
-						<CardBody>
-							<div
-								style={ getStickyStyles( {
-									top: 69,
-									bgColor: 'peachpuff',
-								} ) }
-							>
-								<h2>A wild sticky element appears</h2>
-							</div>
-							<MetaphorIpsum quantity={ 3 } />
-						</CardBody>
-						<CardBody>
-							<div
-								style={ getStickyStyles( {
-									top: 69,
-									bgColor: 'paleturquoise',
-								} ) }
-							>
-								<h2>Another wild sticky element appears</h2>
-							</div>
-							<MetaphorIpsum quantity={ 3 } />
-						</CardBody>
-						<CardFooter
-							style={ getStickyStyles( {
-								bgColor: 'mistyrose',
-							} ) }
-						>
-							<Button variant="primary">Primary noop</Button>
-						</CardFooter>
-					</Card>
+				<NavigatorScreen path="/child/grandchild">
+					<h2>This is the grand child screen.</h2>
+					<NavigatorBackButton variant="secondary">
+						Go back
+					</NavigatorBackButton>
 				</NavigatorScreen>
 
 				<NavigatorScreen path="/product/:id">
-					<ProductDetails />
+					<DynamicScreen />
 				</NavigatorScreen>
 			</>
 		),
 	},
 };
 
-function getStickyStyles( {
-	bottom = 0,
-	bgColor = 'whitesmoke',
-	top = 0,
-	zIndex = 1,
-} ): React.CSSProperties {
-	return {
-		display: 'flex',
-		position: 'sticky',
-		top,
-		bottom,
-		zIndex,
-		backgroundColor: bgColor,
-	};
-}
+function DynamicScreen() {
+	const { params } = useNavigator();
 
-function MetaphorIpsum( { quantity }: { quantity: number } ) {
-	const list = [
-		'A loopy clarinet’s year comes with it the thought that the fenny step-son is an ophthalmologist. The literature would have us believe that a glabrate country is not but a rhythm. A beech is a rub from the right perspective. In ancient times few can name an unglossed walrus that isn’t an unspilt trial.',
-		'Authors often misinterpret the afterthought as a roseless mother-in-law, when in actuality it feels more like an uncapped thunderstorm. In recent years, some posit the tarry bottle to be less than acerb. They were lost without the unkissed timbale that composed their customer. A donna is a springtime breath.',
-		'It’s an undeniable fact, really; their museum was, in this moment, a snotty beef. The swordfishes could be said to resemble prowessed lasagnas. However, the rainier authority comes from a cureless soup. Unfortunately, that is wrong; on the contrary, the cover is a powder.',
-	];
-	quantity = Math.min( list.length, quantity );
 	return (
 		<>
-			{ list.slice( 0, quantity ).map( ( text, key ) => (
-				<p style={ { maxWidth: '20em' } } key={ key }>
-					{ text }
-				</p>
-			) ) }
+			<h2>This is the dynamic screen</h2>
+			<p>
+				This screen can parse params dynamically. The current id is:{ ' ' }
+				{ params.id }
+			</p>
+			<NavigatorBackButton variant="secondary">
+				Go back
+			</NavigatorBackButton>
 		</>
 	);
 }
 
-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>
-	);
-}
-
-export const NestedNavigator: StoryObj< typeof NavigatorProvider > = {
+export const WithNestedInitialPath: StoryObj< typeof NavigatorProvider > = {
 	...Default,
 	args: {
 		...Default.args,
-		initialPath: '/child2/grandchild',
-		children: (
-			<>
-				<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>
-			</>
-		),
+		initialPath: '/child/grandchild',
 	},
 };
 
@@ -308,6 +144,10 @@ const NavigatorButtonWithSkipFocus = ( {
 	return (
 		<Button
 			{ ...props }
+			style={ {
+				marginInline: '8px',
+				...props.style,
+			} }
 			onClick={ ( e: React.MouseEvent< HTMLButtonElement > ) => {
 				goTo( path, { skipFocus: true } );
 				onClick?.( e );
@@ -323,39 +163,28 @@ export const SkipFocus: StoryObj< typeof NavigatorProvider > = {
 			<>
 				<div
 					style={ {
-						height: 250,
-						border: '1px solid black',
+						height: 150,
+						outline: '1px solid black',
+						outlineOffset: '-1px',
+						marginBlockEnd: '1rem',
 					} }
 				>
-					<NavigatorScreen
-						path="/"
-						style={ {
-							height: '100%',
-						} }
-					>
-						<h1>Home screen</h1>
-						<NavigatorButton variant="secondary" path="/child">
+					<NavigatorScreen path="/">
+						<h2>Home screen</h2>
+						<NavigatorButton variant="primary" path="/child">
 							Go to child screen.
 						</NavigatorButton>
 					</NavigatorScreen>
-					<NavigatorScreen
-						path="/child"
-						style={ {
-							height: '100%',
-						} }
-					>
+
+					<NavigatorScreen path="/child">
 						<h2>Child screen</h2>
-						<NavigatorToParentButton variant="secondary">
-							Go to parent screen.
-						</NavigatorToParentButton>
+						<NavigatorBackButton variant="secondary">
+							Go back to home screen
+						</NavigatorBackButton>
 					</NavigatorScreen>
 				</div>
 
-				<NavigatorButtonWithSkipFocus
-					variant="secondary"
-					path="/child"
-					style={ { margin: '1rem 2rem' } }
-				>
+				<NavigatorButtonWithSkipFocus path="/child">
 					Go to child screen, but keep focus on this button
 				</NavigatorButtonWithSkipFocus>
 			</>

package/src/navigator/test/index.tsx

@@ -25,8 +25,8 @@ import {
 import type { NavigateOptions } from '../types';
 
 const INVALID_HTML_ATTRIBUTE = {
-	raw: ' "\'><=invalid_path',
-	escaped: " &quot;'&gt;<=invalid_path",
+	raw: '/ "\'><=invalid_path',
+	escaped: "/ &quot;'&gt;<=invalid_path",
 };
 
 const PATHS = {
@@ -165,6 +165,27 @@ function CustomNavigatorToParentButton( {
 	);
 }
 
+function CustomNavigatorToParentButtonAlternative( {
+	onClick,
+	children,
+}: {
+	children: React.ReactNode;
+	onClick?: CustomTestOnClickHandler;
+} ) {
+	const { goToParent } = useNavigator();
+	return (
+		<button
+			onClick={ () => {
+				goToParent();
+				// Used to spy on the values passed to `navigator.goBack`.
+				onClick?.( { type: 'goToParent' } );
+			} }
+		>
+			{ children }
+		</button>
+	);
+}
+
 const ProductScreen = ( {
 	onBackButtonClick,
 }: {
@@ -344,20 +365,20 @@ const MyHierarchicalNavigation = ( {
 					>
 						{ BUTTON_TEXT.toNestedScreen }
 					</CustomNavigatorButton>
-					<CustomNavigatorToParentButton
+					<CustomNavigatorBackButton
 						onClick={ onNavigatorButtonClick }
 					>
 						{ BUTTON_TEXT.back }
-					</CustomNavigatorToParentButton>
+					</CustomNavigatorBackButton>
 				</NavigatorScreen>
 
 				<NavigatorScreen path={ PATHS.NESTED }>
 					<p>{ SCREEN_TEXT.nested }</p>
-					<CustomNavigatorToParentButton
+					<CustomNavigatorBackButton
 						onClick={ onNavigatorButtonClick }
 					>
 						{ BUTTON_TEXT.back }
-					</CustomNavigatorToParentButton>
+					</CustomNavigatorBackButton>
 					<CustomNavigatorGoToBackButton
 						path={ PATHS.CHILD }
 						onClick={ onNavigatorButtonClick }
@@ -376,6 +397,66 @@ const MyHierarchicalNavigation = ( {
 	);
 };
 
+const MyDeprecatedNavigation = ( {
+	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>
+					<CustomNavigatorToParentButtonAlternative
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.back }
+					</CustomNavigatorToParentButtonAlternative>
+				</NavigatorScreen>
+			</NavigatorProvider>
+		</>
+	);
+};
+
 const getScreen = ( screenKey: keyof typeof SCREEN_TEXT ) =>
 	screen.getByText( SCREEN_TEXT[ screenKey ] );
 const queryScreen = ( screenKey: keyof typeof SCREEN_TEXT ) =>
@@ -769,4 +850,53 @@ describe( 'Navigator', () => {
 			).toHaveFocus();
 		} );
 	} );
+
+	describe( 'deprecated APIs', () => {
+		it( 'should log a deprecation notice when using the NavigatorToParentButton component', async () => {
+			const user = userEvent.setup();
+
+			render( <MyDeprecatedNavigation initialPath={ PATHS.CHILD } /> );
+
+			expect( getScreen( 'child' ) ).toBeInTheDocument();
+
+			// Navigate back to home screen.
+			// The first tabbable element receives focus, since focus restoration
+			// it not possible (there was no forward navigation).
+			await user.click( getNavigationButton( 'back' ) );
+			expect( getScreen( 'home' ) ).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'First tabbable home screen button',
+				} )
+			).toHaveFocus();
+
+			// Rendering `NavigatorToParentButton` logs a deprecation notice
+			expect( console ).toHaveWarnedWith(
+				'wp.components.NavigatorToParentButton is deprecated since version 6.7. Please use wp.components.NavigatorBackButton instead.'
+			);
+		} );
+
+		it( 'should log a deprecation notice when using the useNavigator().goToParent() function', async () => {
+			const user = userEvent.setup();
+
+			render( <MyDeprecatedNavigation initialPath={ PATHS.NESTED } /> );
+
+			expect( getScreen( 'nested' ) ).toBeInTheDocument();
+
+			// Navigate back to child screen using the back button.
+			// The first tabbable element receives focus, since focus restoration
+			// it not possible (there was no forward navigation).
+			await user.click( getNavigationButton( 'back' ) );
+			expect( getScreen( 'child' ) ).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'First tabbable child screen button',
+				} )
+			).toHaveFocus();
+
+			expect( console ).toHaveWarnedWith(
+				'wp.components.useNavigator().goToParent is deprecated since version 6.7. Please use wp.components.useNavigator().goBack instead.'
+			);
+		} );
+	} );
 } );