@wordpress/components 23.3.1 → 23.4.0

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

@@ -7,7 +7,15 @@ import { css } from '@emotion/react';
 /**
  * WordPress dependencies
  */
-import { useMemo, useState, useCallback } from '@wordpress/element';
+import {
+	useMemo,
+	useState,
+	useCallback,
+	useReducer,
+	useRef,
+	useEffect,
+} from '@wordpress/element';
+import isShallowEqual from '@wordpress/is-shallow-equal';
 
 /**
  * Internal dependencies
@@ -24,7 +32,28 @@ import type {
 	NavigatorProviderProps,
 	NavigatorLocation,
 	NavigatorContext as NavigatorContextType,
+	Screen,
 } from '../types';
+import { patternMatch, findParent } from '../utils/router';
+
+type MatchedPath = ReturnType< typeof patternMatch >;
+type ScreenAction = { type: string; screen: Screen };
+
+const MAX_HISTORY_LENGTH = 50;
+
+function screensReducer(
+	state: Screen[] = [],
+	action: ScreenAction
+): Screen[] {
+	switch ( action.type ) {
+		case 'add':
+			return [ ...state, action.screen ];
+		case 'remove':
+			return state.filter( ( s: Screen ) => s.id !== action.screen.id );
+	}
+
+	return state;
+}
 
 function UnconnectedNavigatorProvider(
 	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
@@ -40,19 +69,60 @@ 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;
+		if (
+			locationHistory.length === 0 ||
+			( currentPath =
+				locationHistory[ locationHistory.length - 1 ].path ) ===
+				undefined
+		) {
+			currentMatch.current = undefined;
+			return undefined;
+		}
 
-	const goTo: NavigatorContextType[ 'goTo' ] = useCallback(
-		( path, options = {} ) => {
-			setLocationHistory( ( prevLocationHistory ) => [
-				...prevLocationHistory,
-				{
-					...options,
-					path,
-					isBack: false,
-					hasRestoredFocus: false,
-				},
-			] );
-		},
+		const resolvePath = ( path: string ) => {
+			const newMatch = patternMatch( path, screens );
+
+			// If the new match is the same as the current match,
+			// return the previous one for performance reasons.
+			if (
+				currentMatch.current &&
+				newMatch &&
+				isShallowEqual(
+					newMatch.params,
+					currentMatch.current.params
+				) &&
+				newMatch.id === currentMatch.current.id
+			) {
+				return currentMatch.current;
+			}
+
+			return newMatch;
+		};
+
+		const newMatch = resolvePath( currentPath );
+		currentMatch.current = newMatch;
+		return newMatch;
+	}, [ screens, locationHistory ] );
+
+	const addScreen = useCallback(
+		( screen: Screen ) => dispatch( { type: 'add', screen } ),
+		[]
+	);
+
+	const removeScreen = useCallback(
+		( screen: Screen ) => dispatch( { type: 'remove', screen } ),
 		[]
 	);
 
@@ -72,16 +142,102 @@ function UnconnectedNavigatorProvider(
 		} );
 	}, [] );
 
+	const goTo: NavigatorContextType[ 'goTo' ] = useCallback(
+		( path, options = {} ) => {
+			const {
+				focusTargetSelector,
+				isBack = false,
+				...restOptions
+			} = options;
+
+			const isNavigatingToPreviousPath =
+				isBack &&
+				currentLocationHistory.current.length > 1 &&
+				currentLocationHistory.current[
+					currentLocationHistory.current.length - 2
+				].path === path;
+
+			if ( isNavigatingToPreviousPath ) {
+				goBack();
+				return;
+			}
+
+			setLocationHistory( ( prevLocationHistory ) => {
+				const newLocation = {
+					...restOptions,
+					path,
+					isBack,
+					hasRestoredFocus: false,
+				};
+
+				if ( prevLocationHistory.length < 1 ) {
+					return [ newLocation ];
+				}
+
+				return [
+					...prevLocationHistory.slice(
+						prevLocationHistory.length > MAX_HISTORY_LENGTH - 1
+							? 1
+							: 0,
+						-1
+					),
+					// Assign `focusTargetSelector` to the previous location in history
+					// (the one we just navigated from).
+					{
+						...prevLocationHistory[
+							prevLocationHistory.length - 1
+						],
+						focusTargetSelector,
+					},
+					newLocation,
+				];
+			} );
+		},
+		[ goBack ]
+	);
+
+	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;
+			}
+			goTo( parentPath, { isBack: true } );
+		}, [ goTo ] );
+
 	const navigatorContextValue: NavigatorContextType = useMemo(
 		() => ( {
 			location: {
 				...locationHistory[ locationHistory.length - 1 ],
 				isInitial: locationHistory.length === 1,
 			},
+			params: matchedPath ? matchedPath.params : {},
+			match: matchedPath ? matchedPath.id : undefined,
 			goTo,
 			goBack,
+			goToParent,
+			addScreen,
+			removeScreen,
 		} ),
-		[ locationHistory, goTo, goBack ]
+		[
+			locationHistory,
+			matchedPath,
+			goTo,
+			goBack,
+			goToParent,
+			addScreen,
+			removeScreen,
+		]
 	);
 
 	const cx = useCx();

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

@@ -10,12 +10,14 @@ import { css } from '@emotion/react';
  * WordPress dependencies
  */
 import { focus } from '@wordpress/dom';
-import { useContext, useEffect, useMemo, useRef } from '@wordpress/element';
 import {
-	useReducedMotion,
-	useMergeRefs,
-	usePrevious,
-} from '@wordpress/compose';
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+	useId,
+} from '@wordpress/element';
+import { useReducedMotion, useMergeRefs } from '@wordpress/compose';
 import { isRTL } from '@wordpress/i18n';
 import { escapeAttribute } from '@wordpress/escape-html';
 
@@ -48,17 +50,26 @@ function UnconnectedNavigatorScreen(
 	props: Props,
 	forwardedRef: ForwardedRef< any >
 ) {
+	const screenId = useId();
 	const { children, className, path, ...otherProps } = useContextSystem(
 		props,
 		'NavigatorScreen'
 	);
 
 	const prefersReducedMotion = useReducedMotion();
-	const { location } = useContext( NavigatorContext );
-	const isMatch = location.path === escapeAttribute( path );
+	const { location, match, addScreen, removeScreen } =
+		useContext( NavigatorContext );
+	const isMatch = match === screenId;
 	const wrapperRef = useRef< HTMLDivElement >( null );
 
-	const previousLocation = usePrevious( location );
+	useEffect( () => {
+		const screen = {
+			id: screenId,
+			path: escapeAttribute( path ),
+		};
+		addScreen( screen );
+		return () => removeScreen( screen );
+	}, [ screenId, path, addScreen, removeScreen ] );
 
 	const cx = useCx();
 	const classes = useMemo(
@@ -110,9 +121,9 @@ function UnconnectedNavigatorScreen(
 
 		// When navigating back, if a selector is provided, use it to look for the
 		// target element (assumed to be a node inside the current NavigatorScreen)
-		if ( location.isBack && previousLocation?.focusTargetSelector ) {
+		if ( location.isBack && location?.focusTargetSelector ) {
 			elementToFocus = wrapperRef.current.querySelector(
-				previousLocation.focusTargetSelector
+				location.focusTargetSelector
 			);
 		}
 
@@ -131,7 +142,7 @@ function UnconnectedNavigatorScreen(
 		isInitialLocation,
 		isMatch,
 		location.isBack,
-		previousLocation?.focusTargetSelector,
+		location.focusTargetSelector,
 	] );
 
 	const mergedWrapperRef = useMergeRefs( [ forwardedRef, wrapperRef ] );

package/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
+
+`NavigatorToParentButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.

package/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,
+ *   __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>
+ *
+ *     <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;

package/src/navigator/navigator-to-parent-button/index.ts

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

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',
+};