@wordpress/components 19.2.3 → 19.4.1-next.f435e9e01b.0

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">

package/src/navigator/test/index.js

@@ -26,17 +26,56 @@ jest.mock( 'framer-motion', () => {
 const PATHS = {
 	HOME: '/',
 	CHILD: '/child',
+	NESTED: '/child/nested',
 	NOT_FOUND: '/not-found',
 };
 
-function NavigatorButton( { path, isBack = false, onClick, ...props } ) {
-	const navigator = useNavigator();
+function NavigatorButton( { path, onClick, ...props } ) {
+	const { goTo } = useNavigator();
 	return (
 		<button
 			onClick={ () => {
-				navigator.push( path, { isBack } );
-				// Used to spy on the values passed to `navigator.push`
-				onClick?.( { path, isBack } );
+				goTo( path );
+				// Used to spy on the values passed to `navigator.goTo`
+				onClick?.( { type: 'goTo', path } );
+			} }
+			{ ...props }
+		/>
+	);
+}
+
+function NavigatorButtonWithFocusRestoration( { path, onClick, ...props } ) {
+	const { goTo } = useNavigator();
+	const dataAttrName = 'data-navigator-focusable-id';
+	const dataAttrValue = path;
+
+	const dataAttrCssSelector = `[${ dataAttrName }="${ dataAttrValue }"]`;
+
+	const buttonProps = {
+		...props,
+		[ dataAttrName ]: dataAttrValue,
+	};
+
+	return (
+		<button
+			onClick={ () => {
+				goTo( path, { focusTargetSelector: dataAttrCssSelector } );
+				// Used to spy on the values passed to `navigator.goTo`
+				onClick?.( { type: 'goTo', path } );
+			} }
+			{ ...buttonProps }
+		/>
+	);
+}
+
+function NavigatorBackButton( { onClick, ...props } ) {
+	const { goBack } = useNavigator();
+	return (
+		<button
+			onClick={ () => {
+				goBack();
+				// Used to spy on the values passed to `navigator.goBack`
+				onClick?.( { type: 'goBack' } );
 			} }
 			{ ...props }
 		/>
@@ -50,29 +89,38 @@ const MyNavigation = ( {
 	<NavigatorProvider initialPath={ initialPath }>
 		<NavigatorScreen path={ PATHS.HOME }>
 			<p>This is the home screen.</p>
-			<NavigatorButton
-				path={ PATHS.CHILD }
-				onClick={ onNavigatorButtonClick }
-			>
-				Navigate to child screen.
-			</NavigatorButton>
 			<NavigatorButton
 				path={ PATHS.NOT_FOUND }
 				onClick={ onNavigatorButtonClick }
 			>
 				Navigate to non-existing screen.
 			</NavigatorButton>
+			<NavigatorButtonWithFocusRestoration
+				path={ PATHS.CHILD }
+				onClick={ onNavigatorButtonClick }
+			>
+				Navigate to child screen.
+			</NavigatorButtonWithFocusRestoration>
 		</NavigatorScreen>
 
 		<NavigatorScreen path={ PATHS.CHILD }>
 			<p>This is the child screen.</p>
-			<NavigatorButton
-				path={ PATHS.HOME }
-				isBack
+			<NavigatorButtonWithFocusRestoration
+				path={ PATHS.NESTED }
 				onClick={ onNavigatorButtonClick }
 			>
+				Navigate to nested screen.
+			</NavigatorButtonWithFocusRestoration>
+			<NavigatorBackButton onClick={ onNavigatorButtonClick }>
 				Go back
-			</NavigatorButton>
+			</NavigatorBackButton>
+		</NavigatorScreen>
+
+		<NavigatorScreen path={ PATHS.NESTED }>
+			<p>This is the nested screen.</p>
+			<NavigatorBackButton onClick={ onNavigatorButtonClick }>
+				Go back
+			</NavigatorBackButton>
 		</NavigatorScreen>
 
 		{ /* A `NavigatorScreen` with `path={ PATHS.NOT_FOUND }` is purposefully not included */ }
@@ -91,6 +139,10 @@ const getChildScreen = ( { throwIfNotFound } = {} ) =>
 	getNavigationScreenByText( 'This is the child screen.', {
 		throwIfNotFound,
 	} );
+const getNestedScreen = ( { throwIfNotFound } = {} ) =>
+	getNavigationScreenByText( 'This is the nested screen.', {
+		throwIfNotFound,
+	} );
 
 const getNavigationButtonByText = ( text, { throwIfNotFound = true } = {} ) => {
 	const fnName = throwIfNotFound ? 'getByRole' : 'queryByRole';
@@ -104,7 +156,11 @@ const getToChildScreenButton = ( { throwIfNotFound } = {} ) =>
 	getNavigationButtonByText( 'Navigate to child screen.', {
 		throwIfNotFound,
 	} );
-const getToHomeScreenButton = ( { throwIfNotFound } = {} ) =>
+const getToNestedScreenButton = ( { throwIfNotFound } = {} ) =>
+	getNavigationButtonByText( 'Navigate to nested screen.', {
+		throwIfNotFound,
+	} );
+const getBackButton = ( { throwIfNotFound } = {} ) =>
 	getNavigationButtonByText( 'Go back', {
 		throwIfNotFound,
 	} );
@@ -117,6 +173,9 @@ describe( 'Navigator', () => {
 		expect(
 			getChildScreen( { throwIfNotFound: false } )
 		).not.toBeInTheDocument();
+		expect(
+			getNestedScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
 	} );
 
 	it( 'should show a different screen on the first render depending on the value of `initialPath`', () => {
@@ -126,6 +185,9 @@ describe( 'Navigator', () => {
 			getHomeScreen( { throwIfNotFound: false } )
 		).not.toBeInTheDocument();
 		expect( getChildScreen() ).toBeInTheDocument();
+		expect(
+			getNestedScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
 	} );
 
 	it( 'should ignore changes to `initialPath` after the first render', () => {
@@ -135,6 +197,9 @@ describe( 'Navigator', () => {
 		expect(
 			getChildScreen( { throwIfNotFound: false } )
 		).not.toBeInTheDocument();
+		expect(
+			getNestedScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
 
 		rerender( <MyNavigation initialPath={ PATHS.CHILD } /> );
 
@@ -142,6 +207,9 @@ describe( 'Navigator', () => {
 		expect(
 			getChildScreen( { throwIfNotFound: false } )
 		).not.toBeInTheDocument();
+		expect(
+			getNestedScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
 	} );
 
 	it( 'should not rended anything if the `initialPath` does not match any available screen', () => {
@@ -153,6 +221,9 @@ describe( 'Navigator', () => {
 		expect(
 			getChildScreen( { throwIfNotFound: false } )
 		).not.toBeInTheDocument();
+		expect(
+			getNestedScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
 	} );
 
 	it( 'should navigate across screens', () => {
@@ -160,34 +231,67 @@ describe( 'Navigator', () => {
 
 		render( <MyNavigation onNavigatorButtonClick={ spy } /> );
 
+		expect( getHomeScreen() ).toBeInTheDocument();
 		expect( getToChildScreenButton() ).toBeInTheDocument();
 
 		// Navigate to child screen
 		fireEvent.click( getToChildScreenButton() );
 
-		expect(
-			getHomeScreen( { throwIfNotFound: false } )
-		).not.toBeInTheDocument();
 		expect( getChildScreen() ).toBeInTheDocument();
-		expect( getToHomeScreenButton() ).toBeInTheDocument();
+		expect( getBackButton() ).toBeInTheDocument();
 
 		// Navigate back to home screen
-		fireEvent.click( getToHomeScreenButton() );
+		fireEvent.click( getBackButton() );
 
-		expect(
-			getChildScreen( { throwIfNotFound: false } )
-		).not.toBeInTheDocument();
 		expect( getHomeScreen() ).toBeInTheDocument();
+		expect( getToChildScreenButton() ).toBeInTheDocument();
+
+		// Navigate again to child screen
+		fireEvent.click( getToChildScreenButton() );
+
+		expect( getChildScreen() ).toBeInTheDocument();
+		expect( getToNestedScreenButton() ).toBeInTheDocument();
 
-		// Check the values passed to `navigator.push()`
-		expect( spy ).toHaveBeenCalledTimes( 2 );
+		// Navigate to nested screen
+		fireEvent.click( getToNestedScreenButton() );
+
+		expect( getNestedScreen() ).toBeInTheDocument();
+		expect( getBackButton() ).toBeInTheDocument();
+
+		// Navigate back to child screen
+		fireEvent.click( getBackButton() );
+
+		expect( getChildScreen() ).toBeInTheDocument();
+		expect( getToNestedScreenButton() ).toBeInTheDocument();
+
+		// Navigate back to home screen
+		fireEvent.click( getBackButton() );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+		expect( getToChildScreenButton() ).toBeInTheDocument();
+
+		// Check the values passed to `navigator.goTo()`
+		expect( spy ).toHaveBeenCalledTimes( 6 );
 		expect( spy ).toHaveBeenNthCalledWith( 1, {
 			path: PATHS.CHILD,
-			isBack: false,
+			type: 'goTo',
 		} );
 		expect( spy ).toHaveBeenNthCalledWith( 2, {
-			path: PATHS.HOME,
-			isBack: true,
+			type: 'goBack',
+		} );
+		expect( spy ).toHaveBeenNthCalledWith( 3, {
+			path: PATHS.CHILD,
+			type: 'goTo',
+		} );
+		expect( spy ).toHaveBeenNthCalledWith( 4, {
+			path: PATHS.NESTED,
+			type: 'goTo',
+		} );
+		expect( spy ).toHaveBeenNthCalledWith( 5, {
+			type: 'goBack',
+		} );
+		expect( spy ).toHaveBeenNthCalledWith( 6, {
+			type: 'goBack',
 		} );
 	} );
 
@@ -196,7 +300,7 @@ describe( 'Navigator', () => {
 
 		render( <MyNavigation onNavigatorButtonClick={ spy } /> );
 
-		expect( getToChildScreenButton() ).toBeInTheDocument();
+		expect( getToNonExistingScreenButton() ).toBeInTheDocument();
 
 		// Attempt to navigate to non-existing screen. No screens get rendered.
 		fireEvent.click( getToNonExistingScreenButton() );
@@ -207,12 +311,43 @@ describe( 'Navigator', () => {
 		expect(
 			getChildScreen( { throwIfNotFound: false } )
 		).not.toBeInTheDocument();
+		expect(
+			getNestedScreen( { throwIfNotFound: false } )
+		).not.toBeInTheDocument();
 
-		// Check the values passed to `navigator.push()`
+		// Check the values passed to `navigator.goTo()`
 		expect( spy ).toHaveBeenCalledTimes( 1 );
 		expect( spy ).toHaveBeenNthCalledWith( 1, {
 			path: PATHS.NOT_FOUND,
-			isBack: false,
+			type: 'goTo',
 		} );
 	} );
+
+	it( 'should restore focus correctly', () => {
+		render( <MyNavigation /> );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+
+		// Navigate to child screen
+		fireEvent.click( getToChildScreenButton() );
+
+		expect( getChildScreen() ).toBeInTheDocument();
+
+		// Navigate to nested screen
+		fireEvent.click( getToNestedScreenButton() );
+
+		expect( getNestedScreen() ).toBeInTheDocument();
+
+		// Navigate back to child screen, check that focus was correctly restored
+		fireEvent.click( getBackButton() );
+
+		expect( getChildScreen() ).toBeInTheDocument();
+		expect( getToNestedScreenButton() ).toHaveFocus();
+
+		// Navigate back to home screen, check that focus was correctly restored
+		fireEvent.click( getBackButton() );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+		expect( getToChildScreenButton() ).toHaveFocus();
+	} );
 } );

package/src/navigator/types.ts

@@ -1,26 +1,26 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type { ReactNode } from 'react';
 
-type NavigatorPathOptions = {
-	isBack?: boolean;
+type NavigateOptions = {
+	focusTargetSelector?: string;
 };
 
-export type NavigatorPath = NavigatorPathOptions & {
+export type NavigatorLocation = NavigateOptions & {
+	isInitial?: boolean;
+	isBack?: boolean;
 	path?: string;
 };
 
-export type NavigatorContext = [
-	NavigatorPath,
-	( path: NavigatorPath ) => void
-];
+export type NavigatorContext = {
+	location: NavigatorLocation;
+	goTo: ( path: string, options?: NavigateOptions ) => void;
+	goBack: () => void;
+};
 
 // Returned by the `useNavigator` hook
-export type Navigator = {
-	push: ( path: string, options: NavigatorPathOptions ) => void;
-};
+export type Navigator = NavigatorContext;
 
 export type NavigatorProviderProps = {
 	/**

package/src/navigator/use-navigator.ts

@@ -13,12 +13,12 @@ import type { Navigator } from './types';
  * Retrieves a `navigator` instance.
  */
 function useNavigator(): Navigator {
-	const [ , setPath ] = useContext( NavigatorContext );
+	const { location, goTo, goBack } = useContext( NavigatorContext );
 
 	return {
-		push( path, options ) {
-			setPath( { path, ...options } );
-		},
+		location,
+		goTo,
+		goBack,
 	};
 }
 

package/src/notice/index.native.js

@@ -36,9 +36,12 @@ const Notice = ( { onNoticeHidden, content, id, status } ) => {
 	};
 
 	useEffect( () => {
-		Dimensions.addEventListener( 'change', onDimensionsChange );
+		const dimensionsChangeSubscription = Dimensions.addEventListener(
+			'change',
+			onDimensionsChange
+		);
 		return () => {
-			Dimensions.removeEventListener( 'change', onDimensionsChange );
+			dimensionsChangeSubscription.remove();
 		};
 	}, [] );
 

package/src/notice/stories/index.js

@@ -12,7 +12,7 @@ export default {
 	title: 'Components/Notice',
 	component: Notice,
 	parameters: {
-		knobs: { disabled: false },
+		knobs: { disable: false },
 	},
 };
 

package/src/number-control/stories/index.js

@@ -17,7 +17,7 @@ export default {
 	title: 'Components/NumberControl',
 	component: NumberControl,
 	parameters: {
-		knobs: { disabled: false },
+		knobs: { disable: false },
 	},
 };
 

package/src/palette-edit/index.js

@@ -77,9 +77,16 @@ function Option( {
 
 	return (
 		<PaletteItem
+			className={ isEditing ? 'is-selected' : undefined }
 			as="div"
 			onClick={ onStartEditing }
-			{ ...( isEditing ? focusOutsideProps : {} ) }
+			{ ...( isEditing
+				? { ...focusOutsideProps }
+				: {
+						style: {
+							cursor: 'pointer',
+						},
+				  } ) }
 		>
 			<HStack justify="flex-start">
 				<FlexItem>
@@ -192,7 +199,7 @@ function PaletteEditListView( {
 	}, [] );
 	return (
 		<VStack spacing={ 3 }>
-			<ItemGroup isBordered isSeparated>
+			<ItemGroup isRounded>
 				{ elements.map( ( element, index ) => (
 					<Option
 						isGradient={ isGradient }