Add parent navigation support for the navigator component

docs/manifest.json

@@ -1061,6 +1061,12 @@
 		"markdown_source": "../packages/components/src/navigator/navigator-screen/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "NavigatorToParentButton",
+		"slug": "navigator-to-parent-button",
+		"markdown_source": "../packages/components/src/navigator/navigator-to-parent-button/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "Notice",
 		"slug": "notice",

packages/components/CHANGELOG.md

@@ -7,6 +7,7 @@
 -  `ColorPalette`, `GradientPicker`, `PaletteEdit`, `ToolsPanel`: add new props to set a custom heading level ([43848](https://github.com/WordPress/gutenberg/pull/43848) and [#47788](https://github.com/WordPress/gutenberg/pull/47788)).
 -   `ColorPalette`: ensure text label contrast checking works with CSS variables ([#47373](https://github.com/WordPress/gutenberg/pull/47373)).
 -  `Navigator`: Support dynamic paths with parameters ([#47827](https://github.com/WordPress/gutenberg/pull/47827)).
+-  `Navigator`: Support hierarchical paths navigation and add `NavigatorToParentButton` component ([#47883](https://github.com/WordPress/gutenberg/pull/47883)).
 
 ### Internal
 

packages/components/src/index.js

@@ -115,6 +115,7 @@ export {
 	NavigatorScreen as __experimentalNavigatorScreen,
 	NavigatorButton as __experimentalNavigatorButton,
 	NavigatorBackButton as __experimentalNavigatorBackButton,
+	NavigatorToParentButton as __experimentalNavigatorToParentButton,
 	useNavigator as __experimentalUseNavigator,
 } from './navigator';
 export { default as Notice } from './notice';

packages/components/src/navigator/context.ts

@@ -12,6 +12,7 @@ const initialContextValue: NavigatorContextType = {
 	location: {},
 	goTo: () => {},
 	goBack: () => {},
+	goToParent: () => {},
 	addScreen: () => {},
 	removeScreen: () => {},
 	params: {},

packages/components/src/navigator/index.ts

@@ -2,4 +2,5 @@ export { NavigatorProvider } from './navigator-provider';
 export { NavigatorScreen } from './navigator-screen';
 export { NavigatorButton } from './navigator-button';
 export { NavigatorBackButton } from './navigator-back-button';
+export { NavigatorToParentButton } from './navigator-to-parent-button';
 export { default as useNavigator } from './use-navigator';

packages/components/src/navigator/navigator-back-button/README.md

@@ -10,22 +10,6 @@ The `NavigatorBackButton` component can be used to navigate to a screen and shou
 
 Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example.
 
-## Props
-
-The component accepts the following props:
-
-### `onClick`: `React.MouseEventHandler< HTMLElement >`
-
-The callback called in response to a `click` event.
-
--   Required: No
-
-### `path`: `string`
-
-The path of the screen to navigate to.
-
--   Required: Yes
-
 ### Inherited props
 
 `NavigatorBackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href`.

packages/components/src/navigator/navigator-back-button/hook.ts

@@ -9,26 +9,31 @@ import { useCallback } from '@wordpress/element';
 import { useContextSystem, WordPressComponentProps } from '../../ui/context';
 import Button from '../../button';
 import useNavigator from '../use-navigator';
-import type { NavigatorBackButtonProps } from '../types';
+import type { NavigatorBackButtonHookProps } from '../types';
 
 export function useNavigatorBackButton(
-	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >
+	props: WordPressComponentProps< NavigatorBackButtonHookProps, 'button' >
 ) {
 	const {
 		onClick,
 		as = Button,
+		goToParent: goToParentProp = false,
 		...otherProps
 	} = useContextSystem( props, 'NavigatorBackButton' );
 
-	const { goBack } = useNavigator();
+	const { goBack, goToParent } = useNavigator();
 	const handleClick: React.MouseEventHandler< HTMLButtonElement > =
 		useCallback(
 			( e ) => {
 				e.preventDefault();
-				goBack();
+				if ( goToParentProp ) {
+					goToParent();
+				} else {
+					goBack();
+				}
 				onClick?.( e );
 			},
-			[ goBack, onClick ]
+			[ goToParentProp, goToParent, goBack, onClick ]
 		);
 
 	return {

packages/components/src/navigator/navigator-provider/README.md

@@ -4,7 +4,7 @@
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>
 
-The `NavigatorProvider` component allows rendering nested views/panels/menus (via the [`NavigatorScreen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) and [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). The Global Styles sidebar is an example of this.
+The `NavigatorProvider` component allows rendering nested views/panels/menus (via the [`NavigatorScreen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md), [`NavigatorToParentButton`](/packages/components/src/navigator/navigator-to-parent-button/README.md) and [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). The Global Styles sidebar is an example of this.
 
 ## Usage
 
@@ -13,7 +13,7 @@ import {
   __experimentalNavigatorProvider as NavigatorProvider,
   __experimentalNavigatorScreen as NavigatorScreen,
   __experimentalNavigatorButton as NavigatorButton,
-  __experimentalNavigatorBackButton as NavigatorBackButton,
+  __experimentalNavigatorToParentButton as NavigatorToParentButton,
 } from '@wordpress/components';
 
 const MyNavigation = () => (
@@ -27,13 +27,20 @@ const MyNavigation = () => (
 
     <NavigatorScreen path="/child">
       <p>This is the child screen.</p>
-      <NavigatorBackButton>
+      <NavigatorToParentButton>
         Go back
-      </NavigatorBackButton>
+      </NavigatorToParentButton>
     </NavigatorScreen>
   </NavigatorProvider>
 );
 ```
+**Important note**
+
+Parent/child navigation only works if the path you define are hierarchical. For example:
+ - `/` is the root of all paths. 
+ - `/parent/child` is a child of `/parent`. 
+ - `/parent/child/grand-child` is a child of `/parent/child`.
+ - `/parent/:param` is a child of `/parent` as well.
 
 ## Props
 

packages/components/src/navigator/navigator-provider/component.tsx

@@ -13,6 +13,7 @@ import {
 	useCallback,
 	useReducer,
 	useRef,
+	useEffect,
 } from '@wordpress/element';
 import isShallowEqual from '@wordpress/is-shallow-equal';
 
@@ -33,7 +34,7 @@ import type {
 	NavigatorContext as NavigatorContextType,
 	Screen,
 } from '../types';
-import { patternMatch } from '../utils/router';
+import { patternMatch, findParent } from '../utils/router';
 
 type MatchedPath = ReturnType< typeof patternMatch >;
 type ScreenAction = { type: string; screen: Screen };
@@ -66,7 +67,15 @@ function UnconnectedNavigatorProvider(
 			path: initialPath,
 		},
 	] );
+	const currentLocationHistory = useRef< NavigatorLocation[] >( [] );
 	const [ screens, dispatch ] = useReducer( screensReducer, [] );
+	const currentScreens = useRef< Screen[] >( [] );
+	useEffect( () => {
+		currentScreens.current = screens;
+	}, [ screens ] );
+	useEffect( () => {
+		currentLocationHistory.current = locationHistory;
+	}, [ locationHistory ] );
 	const currentMatch = useRef< MatchedPath >();
 	const matchedPath = useMemo( () => {
 		let currentPath: string | undefined;
@@ -118,12 +127,16 @@ function UnconnectedNavigatorProvider(
 	const goTo: NavigatorContextType[ 'goTo' ] = useCallback(
 		( path, options = {} ) => {
 			setLocationHistory( ( prevLocationHistory ) => {
-				const { focusTargetSelector, ...restOptions } = options;
+				const {
+					focusTargetSelector,
+					isBack = false,
+					...restOptions
+				} = options;
 
 				const newLocation = {
 					...restOptions,
 					path,
-					isBack: false,
+					isBack,
 					hasRestoredFocus: false,
 				};
 
@@ -164,6 +177,34 @@ function UnconnectedNavigatorProvider(
 		} );
 	}, [] );
 
+	const goToParent: NavigatorContextType[ 'goToParent' ] =
+		useCallback( () => {
+			const currentPath =
+				currentLocationHistory.current[
+					currentLocationHistory.current.length - 1
+				].path;
+			if ( currentPath === undefined ) {
+				return;
+			}
+			const parentPath = findParent(
+				currentPath,
+				currentScreens.current
+			);
+			if ( parentPath === undefined ) {
+				return;
+			}
+			const isBack =
+				currentLocationHistory.current.length > 1 &&
+				currentLocationHistory.current[
+					currentLocationHistory.current.length - 2
+				].path === parentPath;
+			if ( isBack ) {
+				goBack();
+			} else {
+				goTo( parentPath, { isBack: true } );
+			}
+		}, [ goBack, goTo ] );
+
 	const navigatorContextValue: NavigatorContextType = useMemo(
 		() => ( {
 			location: {
@@ -174,10 +215,19 @@ function UnconnectedNavigatorProvider(
 			match: matchedPath ? matchedPath.id : undefined,
 			goTo,
 			goBack,
+			goToParent,
 			addScreen,
 			removeScreen,
 		} ),
-		[ locationHistory, matchedPath, goTo, goBack, addScreen, removeScreen ]
+		[
+			locationHistory,
+			matchedPath,
+			goTo,
+			goBack,
+			goToParent,
+			addScreen,
+			removeScreen,
+		]
 	);
 
 	const cx = useCx();

packages/components/src/navigator/navigator-to-parent-button/README.md

@@ -0,0 +1,15 @@
+# `NavigatorToParentButton`
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+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
+
+Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example.
+
+### Inherited props
+
+`NavigatorBackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href`.

packages/components/src/navigator/navigator-to-parent-button/component.tsx

@@ -0,0 +1,65 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { View } from '../../view';
+import { useNavigatorBackButton } from '../navigator-back-button/hook';
+import type { NavigatorToParentButtonProps } from '../types';
+
+function UnconnectedNavigatorToParentButton(
+	props: WordPressComponentProps< NavigatorToParentButtonProps, 'button' >,
+	forwardedRef: ForwardedRef< any >
+) {
+	const navigatorToParentButtonProps = useNavigatorBackButton( {
+		...props,
+		goToParent: true,
+	} );
+
+	return <View ref={ forwardedRef } { ...navigatorToParentButtonProps } />;
+}
+
+/*
+ * 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,
+ *   __experimentalNavigatorBackButton as NavigatorBackButton,
+ * } 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>
+ *
+ *     <NavigatorScreen path="/child">
+ *       <p>This is the child screen.</p>
+ *       <NavigatorToParentButton>
+ *         Go to parent
+ *       </NavigatorToParentButton>
+ *     </NavigatorScreen>
+ *   </NavigatorProvider>
+ * );
+ * ```
+ */
+export const NavigatorToParentButton = contextConnect(
+	UnconnectedNavigatorToParentButton,
+	'NavigatorToParentButton'
+);
+
+export default NavigatorToParentButton;

packages/components/src/navigator/navigator-to-parent-button/index.ts

@@ -0,0 +1 @@
+export { default as NavigatorToParentButton } from './component';