@wordpress/components 28.5.0 → 28.7.0

package/src/modal/index.tsx

@@ -134,9 +134,9 @@ function UnforwardedModal(
 	}, [] );
 
 	// Keeps a fresh ref for the subsequent effect.
-	const refOnRequestClose = useRef< ModalProps[ 'onRequestClose' ] >();
+	const onRequestCloseRef = useRef< ModalProps[ 'onRequestClose' ] >();
 	useEffect( () => {
-		refOnRequestClose.current = onRequestClose;
+		onRequestCloseRef.current = onRequestClose;
 	}, [ onRequestClose ] );
 
 	// The list of `onRequestClose` callbacks of open (non-nested) Modals. Only
@@ -149,10 +149,10 @@ function UnforwardedModal(
 	// onRequestClose for any prior and/or nested modals as applicable.
 	useEffect( () => {
 		// add this modal instance to the dismissers set
-		dismissers.add( refOnRequestClose );
+		dismissers.add( onRequestCloseRef );
 		// request that all the other modals close themselves
 		for ( const dismisser of dismissers ) {
-			if ( dismisser !== refOnRequestClose ) {
+			if ( dismisser !== onRequestCloseRef ) {
 				dismisser.current?.();
 			}
 		}
@@ -162,7 +162,7 @@ function UnforwardedModal(
 				dismisser.current?.();
 			}
 			// remove this modal instance from the dismissers set
-			dismissers.delete( refOnRequestClose );
+			dismissers.delete( onRequestCloseRef );
 		};
 	}, [ dismissers, nestedDismissers ] );
 

package/src/modal/style.scss

@@ -8,7 +8,6 @@
 	background-color: rgba($black, 0.35);
 	z-index: z-index(".components-modal__screen-overlay");
 	display: flex;
-	// backdrop-filter: blur($grid-unit);
 	// This animates the appearance of the white background.
 	@include edit-post__fade-in-animation();
 }
@@ -20,19 +19,19 @@
 	margin: $grid-unit-50 0 0 0;
 	width: 100%;
 	background: $white;
-	box-shadow: $shadow-modal;
-	border-radius: $grid-unit-05 $grid-unit-05 0 0;
+	box-shadow: $elevation-large;
+	border-radius: $radius-large $radius-large 0 0;
 	overflow: hidden;
 	// Have the content element fill the vertical space yet not overflow.
 	display: flex;
 	// Animate the modal frame/contents appearing on the page.
-	animation: components-modal__appear-animation 0.1s ease-out;
+	animation: components-modal__appear-animation 0.26s cubic-bezier(0.29, 0, 0, 1);
 	animation-fill-mode: forwards;
 	@include reduce-motion("animation");
 
 	// Show a centered modal on bigger screens.
 	@include break-small() {
-		border-radius: $grid-unit-05;
+		border-radius: $radius-large;
 		margin: auto;
 		width: auto;
 		min-width: $modal-min-width;
@@ -80,10 +79,12 @@
 
 @keyframes components-modal__appear-animation {
 	from {
-		transform: translateY($grid-unit-40);
+		opacity: 0;
+		transform: scale(0.9);
 	}
 	to {
-		transform: translateY(0);
+		opacity: 1;
+		transform: scale(1);
 	}
 }
 

package/src/navigation/index.tsx

@@ -93,10 +93,10 @@ export function Navigation( {
 	};
 
 	// Used to prevent the sliding animation on mount
-	const isMounted = useRef( false );
+	const isMountedRef = useRef( false );
 	useEffect( () => {
-		if ( ! isMounted.current ) {
-			isMounted.current = true;
+		if ( ! isMountedRef.current ) {
+			isMountedRef.current = true;
 		}
 	}, [] );
 
@@ -130,7 +130,7 @@ export function Navigation( {
 					animateClassName
 						? clsx( {
 								[ animateClassName ]:
-									isMounted.current && slideOrigin,
+									isMountedRef.current && slideOrigin,
 						  } )
 						: undefined
 				}

package/src/navigation/styles/navigation-styles.tsx

@@ -15,7 +15,7 @@ import { COLORS } from '../../utils/colors-values';
 import Button from '../../button';
 import { Text } from '../../text';
 import { Heading } from '../../heading';
-import { rtl } from '../../utils';
+import { rtl, CONFIG } from '../../utils';
 import { space } from '../../utils/space';
 
 export const NavigationUI = styled.div`
@@ -111,7 +111,7 @@ export const GroupTitleUI = styled( Heading )`
 `;
 
 export const ItemBaseUI = styled.li`
-	border-radius: 2px;
+	border-radius: ${ CONFIG.radiusSmall };
 	color: inherit;
 	margin-bottom: 0;
 
@@ -172,7 +172,7 @@ export const ItemBadgeUI = styled.span`
 	margin-right: ${ () => ( isRTL() ? space( 2 ) : '0' ) };
 	display: inline-flex;
 	padding: ${ space( 1 ) } ${ space( 3 ) };
-	border-radius: 2px;
+	border-radius: ${ CONFIG.radiusSmall };
 
 	@keyframes fade-in {
 		from {

package/src/navigator/index.ts

@@ -1,6 +1,6 @@
-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';
+export { NavigatorProvider } from './navigator-provider/component';
+export { NavigatorScreen } from './navigator-screen/component';
+export { NavigatorButton } from './navigator-button/component';
+export { NavigatorBackButton } from './navigator-back-button/component';
+export { NavigatorToParentButton } from './navigator-to-parent-button/component';
+export { useNavigator } from './use-navigator';

package/src/navigator/navigator-back-button/component.tsx

@@ -48,7 +48,7 @@ function UnconnectedNavigatorBackButton(
  *     <NavigatorScreen path="/child">
  *       <p>This is the child screen.</p>
  *       <NavigatorBackButton>
- *         Go back
+ *         Go back (to parent)
  *       </NavigatorBackButton>
  *     </NavigatorScreen>
  *   </NavigatorProvider>

package/src/navigator/navigator-back-button/hook.ts

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

package/src/navigator/navigator-button/hook.ts

@@ -10,7 +10,7 @@ import { escapeAttribute } from '@wordpress/escape-html';
 import type { WordPressComponentProps } from '../../context';
 import { useContextSystem } from '../../context';
 import Button from '../../button';
-import useNavigator from '../use-navigator';
+import { useNavigator } from '../use-navigator';
 import type { NavigatorButtonProps } from '../types';
 
 const cssSelectorForAttribute = ( attrName: string, attrValue: string ) =>

package/src/navigator/navigator-provider/README.md

@@ -10,38 +10,42 @@ The `NavigatorProvider` component allows rendering nested views/panels/menus (vi
 
 ```jsx
 import {
-  __experimentalNavigatorProvider as NavigatorProvider,
-  __experimentalNavigatorScreen as NavigatorScreen,
-  __experimentalNavigatorButton as NavigatorButton,
-  __experimentalNavigatorToParentButton as NavigatorToParentButton,
+	__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 back
-      </NavigatorToParentButton>
-    </NavigatorScreen>
-  </NavigatorProvider>
+	<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>
+			<NavigatorBackButton>Go back</NavigatorBackButton>
+		</NavigatorScreen>
+	</NavigatorProvider>
 );
 ```
+
 **Important note**
 
-Parent/child navigation only works if the path you define are hierarchical, following a URL-like scheme where each path segment is separated by the `/` character.
+`Navigator` assumes that screens are organized hierarchically according to their `path`, which should follow a URL-like scheme where each path segment starts with and is separated by the `/` character.
+
+`Navigator` will treat "back" navigations as going to the parent screen — it is therefore responsibility of the consumer of the component to create the correct screen hierarchy.
+
 For example:
-- `/` is the root of all paths. There should always be a screen with `path="/"`.
-- `/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.
+
+-   `/` is the root of all paths. There should always be a screen with `path="/"`.
+-   `/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.
+-   if the current screen has a `path` with value `/parent/child/grand-child`, when going "back" `Navigator` will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) is found.
 
 ## Props
 
@@ -65,28 +69,25 @@ The `goTo` function allows navigating to a given path. The second argument can a
 
 The available options are:
 
-- `focusTargetSelector`: `string`. An optional property used to specify the CSS selector used to restore focus on the matching element when navigating back.
-- `isBack`: `boolean`. An optional property used to specify whether the navigation should be considered as backwards (thus enabling focus restoration when possible, and causing the animation to be backwards too)
-
-### `goToParent`: `() => void;`
+-   `focusTargetSelector`: `string`. An optional property used to specify the CSS selector used to restore focus on the matching element when navigating back;
+-   `isBack`: `boolean`. An optional property used to specify whether the navigation should be considered as backwards (thus enabling focus restoration when possible, and causing the animation to be backwards too);
+-   `skipFocus`: `boolean`. An optional property used to opt out of `Navigator`'s focus management, useful when the consumer of the component wants to manage focus themselves;
 
-The `goToParent` function allows navigating to the parent screen.
+### `goBack`: `( path: string, options: NavigateOptions ) => void`
 
-Parent/child navigation only works if the path you define are hierarchical (see note above).
+The `goBack` function allows navigating to the parent screen. Parent/child navigation only works if the paths you define are hierarchical (see note above).
 
 When a match is not found, the function will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) are found.
 
-### `goBack`: `() => void`
-
-The `goBack` function allows navigating to the previous path.
+The available options are the same as for the `goTo` method, except for the `isBack` property, which is not available for the `goBack` method.
 
 ### `location`: `NavigatorLocation`
 
 The `location` object represent the current location, and has a few properties:
 
-- `path`: `string`. The path associated to the location.
-- `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards in the location stack.
-- `isInitial`: `boolean`. A flag that is `true` only for the first (root) location in the location stack.
+-   `path`: `string`. The path associated to the location.
+-   `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards.
+-   `isInitial`: `boolean`. A flag that is `true` only for the initial location.
 
 ### `params`: `Record< string, string | string[] >`
 

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

@@ -8,6 +8,7 @@ import type { ForwardedRef } from 'react';
  */
 import { useMemo, useReducer } from '@wordpress/element';
 import isShallowEqual from '@wordpress/is-shallow-equal';
+import warning from '@wordpress/warning';
 
 /**
  * Internal dependencies
@@ -27,24 +28,31 @@ import type {
 	Screen,
 	NavigateToParentOptions,
 } from '../types';
+import deprecated from '@wordpress/deprecated';
 
 type MatchedPath = ReturnType< typeof patternMatch >;
 
 type RouterAction =
 	| { type: 'add' | 'remove'; screen: Screen }
-	| { type: 'goback' }
 	| { type: 'goto'; path: string; options?: NavigateOptions }
 	| { type: 'gotoparent'; options?: NavigateToParentOptions };
 
 type RouterState = {
+	initialPath: string;
 	screens: Screen[];
-	locationHistory: NavigatorLocation[];
+	currentLocation: NavigatorLocation;
 	matchedPath: MatchedPath;
+	focusSelectors: Map< string, string >;
 };
 
-const MAX_HISTORY_LENGTH = 50;
-
 function addScreen( { screens }: RouterState, screen: Screen ) {
+	if ( screens.some( ( s ) => s.path === screen.path ) ) {
+		warning(
+			`Navigator: a screen with path ${ screen.path } already exists.
+The screen with id ${ screen.id } will not be added.`
+		);
+		return screens;
+	}
 	return [ ...screens, screen ];
 }
 
@@ -52,95 +60,83 @@ function removeScreen( { screens }: RouterState, screen: Screen ) {
 	return screens.filter( ( s ) => s.id !== screen.id );
 }
 
-function goBack( { locationHistory }: RouterState ) {
-	if ( locationHistory.length <= 1 ) {
-		return locationHistory;
-	}
-	return [
-		...locationHistory.slice( 0, -2 ),
-		{
-			...locationHistory[ locationHistory.length - 2 ],
-			isBack: true,
-			hasRestoredFocus: false,
-		},
-	];
-}
-
 function goTo(
 	state: RouterState,
 	path: string,
 	options: NavigateOptions = {}
 ) {
-	const { locationHistory } = state;
+	const { focusSelectors } = state;
+	const currentLocation = { ...state.currentLocation, isInitial: false };
+
 	const {
-		focusTargetSelector,
+		// Default assignments
 		isBack = false,
 		skipFocus = false,
-		replace = false,
+		// Extract to avoid forwarding
+		replace,
+		focusTargetSelector,
+		// Rest
 		...restOptions
 	} = options;
 
-	const isNavigatingToSamePath =
-		locationHistory.length > 0 &&
-		locationHistory[ locationHistory.length - 1 ].path === path;
-	if ( isNavigatingToSamePath ) {
-		return locationHistory;
+	if ( currentLocation.path === path ) {
+		return { currentLocation, focusSelectors };
 	}
 
-	const isNavigatingToPreviousPath =
-		isBack &&
-		locationHistory.length > 1 &&
-		locationHistory[ locationHistory.length - 2 ].path === path;
-
-	if ( isNavigatingToPreviousPath ) {
-		return goBack( state );
-	}
-
-	const newLocation = {
-		...restOptions,
-		path,
-		isBack,
-		hasRestoredFocus: false,
-		skipFocus,
-	};
-
-	if ( locationHistory.length === 0 ) {
-		return replace ? [] : [ newLocation ];
+	let focusSelectorsCopy: typeof focusSelectors | undefined;
+	function getFocusSelectorsCopy() {
+		focusSelectorsCopy =
+			focusSelectorsCopy ?? new Map( state.focusSelectors );
+		return focusSelectorsCopy;
 	}
 
-	const newLocationHistory = locationHistory.slice(
-		locationHistory.length > MAX_HISTORY_LENGTH - 1 ? 1 : 0,
-		-1
-	);
-
-	if ( ! replace ) {
-		newLocationHistory.push(
-			// Assign `focusTargetSelector` to the previous location in history
-			// (the one we just navigated from).
-			{
-				...locationHistory[ locationHistory.length - 1 ],
-				focusTargetSelector,
-			}
+	// Set a focus selector that will be used when navigating
+	// back to the current location.
+	if ( focusTargetSelector && currentLocation.path ) {
+		getFocusSelectorsCopy().set(
+			currentLocation.path,
+			focusTargetSelector
 		);
 	}
 
-	newLocationHistory.push( newLocation );
+	// Get the focus selector for the new location.
+	let currentFocusSelector;
+	if ( focusSelectors.get( path ) ) {
+		if ( isBack ) {
+			// Use the found focus selector only when navigating back.
+			currentFocusSelector = focusSelectors.get( path );
+		}
+		// Make a copy of the focusSelectors map to remove the focus selector
+		// only if necessary (ie. a focus selector was found).
+		getFocusSelectorsCopy().delete( path );
+	}
 
-	return newLocationHistory;
+	return {
+		currentLocation: {
+			...restOptions,
+			path,
+			isBack,
+			hasRestoredFocus: false,
+			focusTargetSelector: currentFocusSelector,
+			skipFocus,
+		},
+		focusSelectors: focusSelectorsCopy ?? focusSelectors,
+	};
 }
 
 function goToParent(
 	state: RouterState,
 	options: NavigateToParentOptions = {}
 ) {
-	const { locationHistory, screens } = state;
-	const currentPath = locationHistory[ locationHistory.length - 1 ].path;
+	const { screens, focusSelectors } = state;
+	const currentLocation = { ...state.currentLocation, isInitial: false };
+	const currentPath = currentLocation.path;
 	if ( currentPath === undefined ) {
-		return locationHistory;
+		return { currentLocation, focusSelectors };
 	}
 	const parentPath = findParent( currentPath, screens );
 	if ( parentPath === undefined ) {
-		return locationHistory;
+		return { currentLocation, focusSelectors };
 	}
 	return goTo( state, parentPath, {
 		...options,
@@ -152,7 +148,13 @@ function routerReducer(
 	state: RouterState,
 	action: RouterAction
 ): RouterState {
-	let { screens, locationHistory, matchedPath } = state;
+	let {
+		screens,
+		currentLocation,
+		matchedPath,
+		focusSelectors,
+		...restState
+	} = state;
 	switch ( action.type ) {
 		case 'add':
 			screens = addScreen( state, action.screen );
@@ -160,30 +162,31 @@ function routerReducer(
 		case 'remove':
 			screens = removeScreen( state, action.screen );
 			break;
-		case 'goback':
-			locationHistory = goBack( state );
-			break;
 		case 'goto':
-			locationHistory = goTo( state, action.path, action.options );
+			( { currentLocation, focusSelectors } = goTo(
+				state,
+				action.path,
+				action.options
+			) );
 			break;
 		case 'gotoparent':
-			locationHistory = goToParent( state, action.options );
+			( { currentLocation, focusSelectors } = goToParent(
+				state,
+				action.options
+			) );
 			break;
 	}
 
 	// Return early in case there is no change
 	if (
 		screens === state.screens &&
-		locationHistory === state.locationHistory
+		currentLocation === state.currentLocation
 	) {
 		return state;
 	}
 
 	// Compute the matchedPath
-	const currentPath =
-		locationHistory.length > 0
-			? locationHistory[ locationHistory.length - 1 ].path
-			: undefined;
+	const currentPath = currentLocation.path;
 	matchedPath =
 		currentPath !== undefined
 			? patternMatch( currentPath, screens )
@@ -200,34 +203,55 @@ function routerReducer(
 		matchedPath = state.matchedPath;
 	}
 
-	return { screens, locationHistory, matchedPath };
+	return {
+		...restState,
+		screens,
+		currentLocation,
+		matchedPath,
+		focusSelectors,
+	};
 }
 
 function UnconnectedNavigatorProvider(
 	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) {
-	const { initialPath, children, className, ...otherProps } =
-		useContextSystem( props, 'NavigatorProvider' );
+	const {
+		initialPath: initialPathProp,
+		children,
+		className,
+		...otherProps
+	} = useContextSystem( props, 'NavigatorProvider' );
 
 	const [ routerState, dispatch ] = useReducer(
 		routerReducer,
-		initialPath,
+		initialPathProp,
 		( path ) => ( {
 			screens: [],
-			locationHistory: [ { path } ],
+			currentLocation: { path, isInitial: true },
 			matchedPath: undefined,
+			focusSelectors: new Map(),
+			initialPath: initialPathProp,
 		} )
 	);
 
 	// The methods are constant forever, create stable references to them.
 	const methods = useMemo(
 		() => ( {
-			goBack: () => dispatch( { type: 'goback' } ),
+			// Note: calling goBack calls `goToParent` internally, as it was established
+			// that `goBack` should behave like `goToParent`, and `goToParent` should
+			// be marked as deprecated.
+			goBack: ( options: NavigateToParentOptions | undefined ) =>
+				dispatch( { type: 'gotoparent', options } ),
 			goTo: ( path: string, options?: NavigateOptions ) =>
 				dispatch( { type: 'goto', path, options } ),
-			goToParent: ( options: NavigateToParentOptions | undefined ) =>
-				dispatch( { type: 'gotoparent', options } ),
+			goToParent: ( options: NavigateToParentOptions | undefined ) => {
+				deprecated( `wp.components.useNavigator().goToParent`, {
+					since: '6.7',
+					alternative: 'wp.components.useNavigator().goBack',
+				} );
+				dispatch( { type: 'gotoparent', options } );
+			},
 			addScreen: ( screen: Screen ) =>
 				dispatch( { type: 'add', screen } ),
 			removeScreen: ( screen: Screen ) =>
@@ -236,19 +260,16 @@ function UnconnectedNavigatorProvider(
 		[]
 	);
 
-	const { locationHistory, matchedPath } = routerState;
+	const { currentLocation, matchedPath } = routerState;
 
 	const navigatorContextValue: NavigatorContextType = useMemo(
 		() => ( {
-			location: {
-				...locationHistory[ locationHistory.length - 1 ],
-				isInitial: locationHistory.length === 1,
-			},
+			location: currentLocation,
 			params: matchedPath?.params ?? {},
 			match: matchedPath?.id,
 			...methods,
 		} ),
-		[ locationHistory, matchedPath, methods ]
+		[ currentLocation, matchedPath, methods ]
 	);
 
 	const cx = useCx();

package/src/navigator/navigator-screen/README.md

@@ -16,6 +16,18 @@ The component accepts the following props:
 
 ### `path`: `string`
 
-The screen's path, matched against the current path stored in the navigator.
+The screen"s path, matched against the current path stored in the navigator.
+
+`Navigator` assumes that screens are organized hierarchically according to their `path`, which should follow a URL-like scheme where each path segment starts with and is separated by the `/` character.
+
+`Navigator` will treat "back" navigations as going to the parent screen — it is therefore responsibility of the consumer of the component to create the correct screen hierarchy.
+
+For example:
+
+-   `/` is the root of all paths. There should always be a screen with `path="/"`.
+-   `/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.
+-   if the current screen has a `path` with value `/parent/child/grand-child`, when going "back" `Navigator` will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) is found.
 
 -   Required: Yes