@wordpress/components 23.3.1 → 23.3.3

package/src/custom-select-control/test/index.js

@@ -4,9 +4,9 @@
 import { render, fireEvent, screen } from '@testing-library/react';
 
 /**
- * WordPress dependencies
+ * Internal dependencies
  */
-import { CustomSelectControl } from '@wordpress/components';
+import CustomSelectControl from '..';
 
 describe( 'CustomSelectControl', () => {
 	it( 'Captures the keypress event and does not let it propagate', () => {

package/src/dimension-control/test/__snapshots__/index.test.js.snap

@@ -116,7 +116,6 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
   width: 100%;
   max-width: none;
   cursor: pointer;
-  overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
   font-size: 16px;
@@ -126,6 +125,7 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
   padding-bottom: 0;
   padding-left: 8px;
   padding-right: 26px;
+  overflow: hidden;
 }
 
 @media ( min-width: 600px ) {
@@ -387,7 +387,6 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
   width: 100%;
   max-width: none;
   cursor: pointer;
-  overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
   font-size: 16px;
@@ -397,6 +396,7 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
   padding-bottom: 0;
   padding-left: 8px;
   padding-right: 26px;
+  overflow: hidden;
 }
 
 @media ( min-width: 600px ) {
@@ -668,7 +668,6 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
   width: 100%;
   max-width: none;
   cursor: pointer;
-  overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
   font-size: 16px;
@@ -678,6 +677,7 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
   padding-bottom: 0;
   padding-left: 8px;
   padding-right: 26px;
+  overflow: hidden;
 }
 
 @media ( min-width: 600px ) {
@@ -961,7 +961,6 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
   width: 100%;
   max-width: none;
   cursor: pointer;
-  overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
   font-size: 16px;
@@ -971,6 +970,7 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
   padding-bottom: 0;
   padding-left: 8px;
   padding-right: 26px;
+  overflow: hidden;
 }
 
 @media ( min-width: 600px ) {

package/src/index.js

@@ -59,7 +59,7 @@ export {
 	useCompositeState as __unstableUseCompositeState,
 } from './composite';
 export { ConfirmDialog as __experimentalConfirmDialog } from './confirm-dialog';
-export { default as CustomSelectControl } from './custom-select-control';
+export { StableCustomSelectControl as CustomSelectControl } from './custom-select-control';
 export { default as Dashicon } from './dashicon';
 export { default as DateTimePicker, DatePicker, TimePicker } from './date-time';
 export { default as __experimentalDimensionControl } from './dimension-control';
@@ -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';
@@ -126,7 +127,6 @@ export { default as PanelHeader } from './panel/header';
 export { default as PanelRow } from './panel/row';
 export { default as Placeholder } from './placeholder';
 export { default as Popover } from './popover';
-export { positionToPlacement as __experimentalPopoverPositionToPlacement } from './popover/utils';
 export { default as QueryControls } from './query-controls';
 export { default as __experimentalRadio } from './radio-group/radio';
 export { default as __experimentalRadioGroup } from './radio-group';
@@ -212,3 +212,6 @@ export {
 } from './higher-order/with-focus-return';
 export { default as withNotices } from './higher-order/with-notices';
 export { default as withSpokenMessages } from './higher-order/with-spoken-messages';
+
+// Private APIs.
+export { privateApis } from './private-apis';

package/src/navigator/context.ts

@@ -12,5 +12,9 @@ const initialContextValue: NavigatorContextType = {
 	location: {},
 	goTo: () => {},
 	goBack: () => {},
+	goToParent: () => {},
+	addScreen: () => {},
+	removeScreen: () => {},
+	params: {},
 };
 export const NavigatorContext = createContext( initialContextValue );

package/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';

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

package/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 {

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

@@ -35,4 +35,4 @@ The path of the screen to navigate to. The value of this prop needs to be [a val
 
 ### Inherited props
 
-`NavigatorButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href`.
+`NavigatorButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.

package/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,21 @@ 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, following a URL-like scheme where each path segment is separated by the `/` character.
+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.
 
 ## Props
 
@@ -58,6 +66,15 @@ 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;`
+
+The `goToParent` function allows navigating to the parent screen.
+
+Parent/child navigation only works if the path 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`
 
@@ -70,3 +87,7 @@ 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.
+
+### `params`: `Record< string, string | string[] >`
+
+The parsed record of parameters from the current location. For example if the current screen path is `/product/:productId` and the location is `/product/123`, then `params` will be `{ productId: '123' }`.

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';