@wordpress/components 19.2.1-next.33ec3857e2.0 → 19.4.0

package/src/mobile/utils/use-is-floating-keyboard.native.js

@@ -18,15 +18,12 @@ export default function useIsFloatingKeyboard() {
 			setFloating( event.endCoordinates.width !== windowWidth );
 		};
 
-		Keyboard.addListener(
+		const keyboardChangeSubscription = Keyboard.addListener(
 			'keyboardWillChangeFrame',
 			onKeyboardWillChangeFrame
 		);
 		return () => {
-			Keyboard.removeListener(
-				'keyboardWillChangeFrame',
-				onKeyboardWillChangeFrame
-			);
+			keyboardChangeSubscription.remove();
 		};
 	}, [ windowWidth ] );
 

package/src/mobile/utils/use-unit-converter-to-mobile.native.js

@@ -40,6 +40,10 @@ const convertUnitToMobile = ( containerSize, globalStyles, value, unit ) => {
 	const { valueToConvert, valueUnit } = getValueAndUnit( value, unit ) || {};
 	const { fontSize = 16 } = globalStyles || {};
 
+	if ( valueToConvert === undefined ) {
+		return undefined;
+	}
+
 	switch ( valueUnit ) {
 		case 'rem':
 		case 'em':
@@ -66,10 +70,13 @@ const useConvertUnitToMobile = ( value, unit ) => {
 	);
 
 	useEffect( () => {
-		Dimensions.addEventListener( 'change', onDimensionsChange );
+		const dimensionsChangeSubscription = Dimensions.addEventListener(
+			'change',
+			onDimensionsChange
+		);
 
 		return () => {
-			Dimensions.removeEventListener( 'change', onDimensionsChange );
+			dimensionsChangeSubscription.remove();
 		};
 	}, [] );
 
@@ -78,7 +85,8 @@ const useConvertUnitToMobile = ( value, unit ) => {
 	}, [] );
 
 	return useMemo( () => {
-		const { valueToConvert, valueUnit } = getValueAndUnit( value, unit );
+		const { valueToConvert, valueUnit } =
+			getValueAndUnit( value, unit ) || {};
 
 		return convertUnitToMobile(
 			windowSizes,

package/src/modal/index.js

@@ -22,7 +22,6 @@ import {
 	useConstrainedTabbing,
 	useMergeRefs,
 } from '@wordpress/compose';
-import deprecated from '@wordpress/deprecated';
 import { ESCAPE } from '@wordpress/keycodes';
 import { __ } from '@wordpress/i18n';
 import { closeSmall } from '@wordpress/icons';
@@ -45,8 +44,7 @@ function Modal( props, forwardedRef ) {
 		focusOnMount = true,
 		shouldCloseOnEsc = true,
 		shouldCloseOnClickOutside = true,
-		isDismissable, // Deprecated
-		isDismissible = isDismissable || true,
+		isDismissible = true,
 		/* accessibility */
 		aria = {
 			labelledby: null,
@@ -93,13 +91,6 @@ function Modal( props, forwardedRef ) {
 		};
 	}, [] );
 
-	if ( isDismissable ) {
-		deprecated( 'isDismissable prop of the Modal component', {
-			since: '5.4',
-			alternative: 'isDismissible prop (renamed) of the Modal component',
-		} );
-	}
-
 	function handleEscapeKeyDown( event ) {
 		if (
 			shouldCloseOnEsc &&

package/src/navigator/context.ts

@@ -8,5 +8,9 @@ import { createContext } from '@wordpress/element';
  */
 import type { NavigatorContext as NavigatorContextType } from './types';
 
-const initialContextValue: NavigatorContextType = [ {}, () => {} ];
+const initialContextValue: NavigatorContextType = {
+	location: {},
+	goTo: () => {},
+	goBack: () => {},
+};
 export const NavigatorContext = createContext( initialContextValue );

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

@@ -6,8 +6,6 @@ This feature is still experimental. “Experimental” means this is an early im
 
 The `NavigatorProvider` component allows rendering nested panels or menus (via the [`NavigatorScreen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the `useNavigator` hook). The Global Styles sidebar is an example of this.
 
-The `Navigator*` family of components is _not_ opinionated in terms of UI, and can be composed with any UI components to navigate between the nested screens.
-
 ## Usage
 
 ```jsx
@@ -17,34 +15,34 @@ import {
 	__experimentalUseNavigator as useNavigator,
 } from '@wordpress/components';
 
-function NavigatorButton( {
-	path,
-	isBack = false,
-	...props
-} ) {
-	const navigator = useNavigator();
+function NavigatorButton( { path, ...props } ) {
+	const { goTo } = useNavigator();
 	return (
 		<Button
-			onClick={ () => navigator.push( path, { isBack } ) }
-			{ ...props }
-		/>
-	);
+		 variant="primary"
+		 onClick={ () => goTo( path ) }
+		 { ...props }
+	 />
+ );
+}
+
+function NavigatorBackButton( props ) {
+	const { goBack } = useNavigator();
+	return <Button variant="secondary" onClick={ () => goBack() } { ...props } />;
 }
 
 const MyNavigation = () => (
 	<NavigatorProvider initialPath="/">
 		<NavigatorScreen path="/">
 			<p>This is the home screen.</p>
-			<NavigatorButton isPrimary path="/child">
+			<NavigatorButton path="/child">
 				Navigate to child screen.
 			</NavigatorButton>
 		</NavigatorScreen>
 
 		<NavigatorScreen path="/child">
 			<p>This is the child screen.</p>
-			<NavigatorButton isPrimary path="/" isBack>
-				Go back
-			</NavigatorButton>
+			<NavigatorBackButton>Go back</NavigatorBackButton>
 		</NavigatorScreen>
 	</NavigatorProvider>
 );
@@ -64,12 +62,24 @@ The initial active path.
 
 You can retrieve a `navigator` instance by using the `useNavigator` hook.
 
-The hook offers the following methods:
+The `navigator` instance has a few properties:
 
-### `push`: `( path: string, options ) => void`
+### `goTo`: `( path: string, options: NavigateOptions ) => void`
 
-The `push` function allows you to navigate to a given path. The second argument can augment the navigation operations with different options.
+The `goTo` function allows navigating to a given path. The second argument can augment the navigation operations with different options.
 
 The available options are:
 
-- `isBack` (`boolean): A boolean flag indicating that we're moving back to a previous state. -->
+- `focusTargetSelector`: `string`. An optional property used to specify the CSS selector used to restore focus on the matching element when navigating back.
+
+### `goBack`: `() => void`
+
+The `goBack` function allows navigating to the previous path.
+
+### `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.

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

@@ -1,14 +1,13 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type { Ref } from 'react';
 import { css } from '@emotion/react';
 
 /**
  * WordPress dependencies
  */
-import { useMemo, useState } from '@wordpress/element';
+import { useMemo, useState, useCallback } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -21,7 +20,11 @@ import {
 import { useCx } from '../../utils/hooks/use-cx';
 import { View } from '../../view';
 import { NavigatorContext } from '../context';
-import type { NavigatorProviderProps, NavigatorPath } from '../types';
+import type {
+	NavigatorProviderProps,
+	NavigatorLocation,
+	NavigatorContext as NavigatorContextType,
+} from '../types';
 
 function NavigatorProvider(
 	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
@@ -34,20 +37,62 @@ function NavigatorProvider(
 		...otherProps
 	} = useContextSystem( props, 'NavigatorProvider' );
 
-	const [ path, setPath ] = useState< NavigatorPath >( {
-		path: initialPath,
-	} );
+	const [ locationHistory, setLocationHistory ] = useState<
+		NavigatorLocation[]
+	>( [
+		{
+			path: initialPath,
+		},
+	] );
+
+	const goTo: NavigatorContextType[ 'goTo' ] = useCallback(
+		( path, options = {} ) => {
+			setLocationHistory( [
+				...locationHistory,
+				{
+					...options,
+					path,
+					isBack: false,
+				},
+			] );
+		},
+		[ locationHistory ]
+	);
+
+	const goBack: NavigatorContextType[ 'goBack' ] = useCallback( () => {
+		if ( locationHistory.length > 1 ) {
+			setLocationHistory( [
+				...locationHistory.slice( 0, -2 ),
+				{
+					...locationHistory[ locationHistory.length - 2 ],
+					isBack: true,
+				},
+			] );
+		}
+	}, [ locationHistory ] );
+
+	const navigatorContextValue: NavigatorContextType = useMemo(
+		() => ( {
+			location: {
+				...locationHistory[ locationHistory.length - 1 ],
+				isInitial: locationHistory.length === 1,
+			},
+			goTo,
+			goBack,
+		} ),
+		[ locationHistory, goTo, goBack ]
+	);
 
 	const cx = useCx();
 	const classes = useMemo(
 		// Prevents horizontal overflow while animating screen transitions
 		() => cx( css( { overflowX: 'hidden' } ), className ),
-		[ className ]
+		[ className, cx ]
 	);
 
 	return (
 		<View ref={ forwardedRef } className={ classes } { ...otherProps }>
-			<NavigatorContext.Provider value={ [ path, setPath ] }>
+			<NavigatorContext.Provider value={ navigatorContextValue }>
 				{ children }
 			</NavigatorContext.Provider>
 		</View>
@@ -56,7 +101,6 @@ function NavigatorProvider(
 
 /**
  * The `NavigatorProvider` component allows rendering nested panels or menus (via the `NavigatorScreen` component) and navigate between these different states (via the `useNavigator` hook).
- * The Global Styles sidebar is an example of this. The `Navigator*` family of components is _not_ opinionated in terms of UI, and can be composed with any UI components to navigate between the nested screens.
  *
  * @example
  * ```jsx
@@ -66,34 +110,34 @@ function NavigatorProvider(
  *   __experimentalUseNavigator as useNavigator,
  * } from '@wordpress/components';
  *
- * function NavigatorButton( {
- *   path,
- *   isBack = false,
- *   ...props
- * } ) {
- *   const navigator = useNavigator();
- *   return (
- *   	<Button
- *   	  onClick={ () => navigator.push( path, { isBack } ) }
- *   	  { ...props }
- *   	/>
- *   );
+ * function NavigatorButton( { path, ...props } ) {
+ *  const { goTo } = useNavigator();
+ *  return (
+ *    <Button
+ *      variant="primary"
+ *      onClick={ () => goTo( path ) }
+ *      { ...props }
+ *    />
+ *  );
+ * }
+ *
+ * function NavigatorBackButton( props ) {
+ *   const { goBack } = useNavigator();
+ *   return <Button variant="secondary" onClick={ () => goBack() } { ...props } />;
  * }
  *
  * const MyNavigation = () => (
  *   <NavigatorProvider initialPath="/">
  *     <NavigatorScreen path="/">
  *       <p>This is the home screen.</p>
- *   	   <NavigatorButton isPrimary path="/child">
+ *   	   <NavigatorButton path="/child">
  *          Navigate to child screen.
  *       </NavigatorButton>
  *     </NavigatorScreen>
  *
  *     <NavigatorScreen path="/child">
  *       <p>This is the child screen.</p>
- *       <NavigatorButton isPrimary path="/" isBack>
- *         Go back
- *       </NavigatorButton>
+ *       <NavigatorBackButton>Go back</NavigatorBackButton>
  *     </NavigatorScreen>
  *   </NavigatorProvider>
  * );

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

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type { Ref } from 'react';
 // eslint-disable-next-line no-restricted-imports
 import { motion, MotionProps } from 'framer-motion';
@@ -10,8 +9,13 @@ import { css } from '@emotion/react';
 /**
  * WordPress dependencies
  */
-import { useContext, useEffect, useState, useMemo } from '@wordpress/element';
-import { useReducedMotion, useFocusOnMount } from '@wordpress/compose';
+import { focus } from '@wordpress/dom';
+import { useContext, useEffect, useMemo, useRef } from '@wordpress/element';
+import {
+	useReducedMotion,
+	useMergeRefs,
+	usePrevious,
+} from '@wordpress/compose';
 import { isRTL } from '@wordpress/i18n';
 
 /**
@@ -46,9 +50,11 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 	);
 
 	const prefersReducedMotion = useReducedMotion();
-	const [ currentPath ] = useContext( NavigatorContext );
-	const isMatch = currentPath.path === path;
-	const ref = useFocusOnMount();
+	const { location } = useContext( NavigatorContext );
+	const isMatch = location.path === path;
+	const wrapperRef = useRef< HTMLDivElement >( null );
+
+	const previousLocation = usePrevious( location );
 
 	const cx = useCx();
 	const classes = useMemo(
@@ -62,15 +68,44 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 				} ),
 				className
 			),
-		[ className ]
+		[ className, cx ]
 	);
 
-	// This flag is used to only apply the focus on mount when the actual path changes.
-	// It avoids the focus to happen on the first render.
-	const [ hasPathChanged, setHasPathChanged ] = useState( false );
+	// Focus restoration
+	const isInitialLocation = location.isInitial && ! location.isBack;
 	useEffect( () => {
-		setHasPathChanged( true );
-	}, [ path ] );
+		// Only attempt to restore focus:
+		// - if the current location is not the initial one (to avoid moving focus on page load)
+		// - when the screen becomes visible
+		// - if the wrapper ref has been assigned
+		if ( isInitialLocation || ! isMatch || ! wrapperRef.current ) {
+			return;
+		}
+
+		let elementToFocus: HTMLElement | null = null;
+
+		// 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 ) {
+			elementToFocus = wrapperRef.current.querySelector(
+				previousLocation.focusTargetSelector
+			);
+		}
+
+		// If the previous query didn't run or find any element to focus, fallback
+		// to the first tabbable element in the screen (or the screen itself).
+		if ( ! elementToFocus ) {
+			const firstTabbable = ( focus.tabbable.find(
+				wrapperRef.current
+			) as HTMLElement[] )[ 0 ];
+
+			elementToFocus = firstTabbable ?? wrapperRef.current;
+		}
+
+		elementToFocus.focus();
+	}, [ isInitialLocation, isMatch ] );
+
+	const mergedWrapperRef = useMergeRefs( [ forwardedRef, wrapperRef ] );
 
 	if ( ! isMatch ) {
 		return null;
@@ -78,7 +113,11 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 
 	if ( prefersReducedMotion ) {
 		return (
-			<View ref={ forwardedRef } className={ classes } { ...otherProps }>
+			<View
+				ref={ mergedWrapperRef }
+				className={ classes }
+				{ ...otherProps }
+			>
 				{ children }
 			</View>
 		);
@@ -96,8 +135,7 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 	const initial = {
 		opacity: 0,
 		x:
-			( isRTL() && currentPath.isBack ) ||
-			( ! isRTL() && ! currentPath.isBack )
+			( isRTL() && location.isBack ) || ( ! isRTL() && ! location.isBack )
 				? 50
 				: -50,
 	};
@@ -105,8 +143,7 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 		delay: animationExitDelay,
 		opacity: 0,
 		x:
-			( ! isRTL() && currentPath.isBack ) ||
-			( isRTL() && ! currentPath.isBack )
+			( ! isRTL() && location.isBack ) || ( isRTL() && ! location.isBack )
 				? 50
 				: -50,
 		transition: {
@@ -123,7 +160,7 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 
 	return (
 		<motion.div
-			ref={ hasPathChanged ? ref : undefined }
+			ref={ mergedWrapperRef }
 			className={ classes }
 			{ ...otherProps }
 			{ ...animatedProps }
@@ -144,34 +181,34 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
  *   __experimentalUseNavigator as useNavigator,
  * } from '@wordpress/components';
  *
- * function NavigatorButton( {
- *   path,
- *   isBack = false,
- *   ...props
- * } ) {
- *   const navigator = useNavigator();
- *   return (
- *   	<Button
- *   	  onClick={ () => navigator.push( path, { isBack } ) }
- *   	  { ...props }
- *   	/>
- *   );
+ * function NavigatorButton( { path, ...props } ) {
+ *  const { goTo } = useNavigator();
+ *  return (
+ *    <Button
+ *      variant="primary"
+ *      onClick={ () => goTo( path ) }
+ *      { ...props }
+ *    />
+ *  );
+ * }
+ *
+ * function NavigatorBackButton( props ) {
+ *   const { goBack } = useNavigator();
+ *   return <Button variant="secondary" onClick={ () => goBack() } { ...props } />;
  * }
  *
  * const MyNavigation = () => (
  *   <NavigatorProvider initialPath="/">
  *     <NavigatorScreen path="/">
  *       <p>This is the home screen.</p>
- *   	   <NavigatorButton isPrimary path="/child">
+ *   	   <NavigatorButton path="/child">
  *          Navigate to child screen.
  *       </NavigatorButton>
  *     </NavigatorScreen>
  *
  *     <NavigatorScreen path="/child">
  *       <p>This is the child screen.</p>
- *       <NavigatorButton isPrimary path="/" isBack>
- *         Go back
- *       </NavigatorButton>
+ *       <NavigatorBackButton>Go back</NavigatorBackButton>
  *     </NavigatorScreen>
  *   </NavigatorProvider>
  * );

package/src/navigator/stories/index.js

@@ -18,17 +18,36 @@ export default {
 	component: NavigatorProvider,
 };
 
-function NavigatorButton( { path, isBack = false, ...props } ) {
-	const navigator = useNavigator();
+function NavigatorButton( { path, ...props } ) {
+	const { goTo } = useNavigator();
+	const dataAttrName = 'data-navigator-focusable-id';
+	const dataAttrValue = path;
+
+	const dataAttrCssSelector = `[${ dataAttrName }="${ dataAttrValue }"]`;
+
+	const buttonProps = {
+		...props,
+		[ dataAttrName ]: dataAttrValue,
+	};
+
 	return (
 		<Button
 			variant="secondary"
-			onClick={ () => navigator.push( path, { isBack } ) }
-			{ ...props }
+			onClick={ () =>
+				goTo( path, { focusTargetSelector: dataAttrCssSelector } )
+			}
+			{ ...buttonProps }
 		/>
 	);
 }
 
+function NavigatorBackButton( props ) {
+	const { goBack } = useNavigator();
+	return (
+		<Button variant="secondary" onClick={ () => goBack() } { ...props } />
+	);
+}
+
 const MyNavigation = () => {
 	const cx = useCx();
 	return (
@@ -74,9 +93,7 @@ const MyNavigation = () => {
 				<Card>
 					<CardBody>
 						<p>This is the child screen.</p>
-						<NavigatorButton path="/" isBack>
-							Go back
-						</NavigatorButton>
+						<NavigatorBackButton>Go back</NavigatorBackButton>
 					</CardBody>
 				</Card>
 			</NavigatorScreen>
@@ -84,9 +101,7 @@ const MyNavigation = () => {
 			<NavigatorScreen path="/overflow-child">
 				<Card>
 					<CardBody>
-						<NavigatorButton path="/" isBack>
-							Go back
-						</NavigatorButton>
+						<NavigatorBackButton>Go back</NavigatorBackButton>
 						<div
 							className={ cx(
 								css( `
@@ -114,9 +129,7 @@ const MyNavigation = () => {
 			<NavigatorScreen path="/stickies">
 				<Card>
 					<Sticky as={ CardHeader } z="2">
-						<NavigatorButton path="/" isBack>
-							Go back
-						</NavigatorButton>
+						<NavigatorBackButton>Go back</NavigatorBackButton>
 					</Sticky>
 					<CardBody>
 						<Sticky top="69px" colors="papayawhip/peachpuff">