@wordpress/components 28.8.6 → 28.10.0

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

@@ -21,43 +21,7 @@ function UnconnectedNavigatorBackButton(
 	return <View ref={ forwardedRef } { ...navigatorBackButtonProps } />;
 }
 
-/**
- * The `NavigatorBackButton` 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,
- *   __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>
- *       <NavigatorBackButton>
- *         Go back (to parent)
- *       </NavigatorBackButton>
- *     </NavigatorScreen>
- *   </NavigatorProvider>
- * );
- * ```
- */
 export const NavigatorBackButton = contextConnect(
 	UnconnectedNavigatorBackButton,
-	'NavigatorBackButton'
+	'Navigator.BackButton'
 );
-
-export default NavigatorBackButton;

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

@@ -20,7 +20,7 @@ export function useNavigatorBackButton(
 		as = Button,
 
 		...otherProps
-	} = useContextSystem( props, 'NavigatorBackButton' );
+	} = useContextSystem( props, 'Navigator.BackButton' );
 
 	const { goBack } = useNavigator();
 	const handleClick: React.MouseEventHandler< HTMLButtonElement > =

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

@@ -21,42 +21,7 @@ function UnconnectedNavigatorButton(
 	return <View ref={ forwardedRef } { ...navigatorButtonProps } />;
 }
 
-/**
- * The `NavigatorButton` component can be used to navigate to a screen and should
- * be used in combination with the `NavigatorProvider`, the `NavigatorScreen`
- * and the `NavigatorBackButton` components (or the `useNavigator` hook).
- *
- * @example
- * ```jsx
- * import {
- *   __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>
- *       <NavigatorBackButton>
- *         Go back
- *       </NavigatorBackButton>
- *     </NavigatorScreen>
- *   </NavigatorProvider>
- * );
- * ```
- */
 export const NavigatorButton = contextConnect(
 	UnconnectedNavigatorButton,
-	'NavigatorButton'
+	'Navigator.Button'
 );
-
-export default NavigatorButton;

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

@@ -25,7 +25,7 @@ export function useNavigatorButton(
 		as = Button,
 		attributeName = 'id',
 		...otherProps
-	} = useContextSystem( props, 'NavigatorButton' );
+	} = useContextSystem( props, 'Navigator.Button' );
 
 	const escapedPath = escapeAttribute( path );
 

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

@@ -15,7 +15,6 @@ import {
 	useId,
 } from '@wordpress/element';
 import { useMergeRefs } from '@wordpress/compose';
-import { isRTL as isRTLFn } from '@wordpress/i18n';
 import { escapeAttribute } from '@wordpress/escape-html';
 import warning from '@wordpress/warning';
 
@@ -29,6 +28,7 @@ import { View } from '../../view';
 import { NavigatorContext } from '../context';
 import * as styles from '../styles';
 import type { NavigatorScreenProps } from '../types';
+import { useScreenAnimatePresence } from './use-screen-animate-presence';
 
 function UnconnectedNavigatorScreen(
 	props: WordPressComponentProps< NavigatorScreenProps, 'div', false >,
@@ -36,21 +36,29 @@ function UnconnectedNavigatorScreen(
 ) {
 	if ( ! /^\//.test( props.path ) ) {
 		warning(
-			'wp.components.NavigatorScreen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.'
+			'wp.components.Navigator.Screen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.'
 		);
 	}
 
 	const screenId = useId();
-	const { children, className, path, ...otherProps } = useContextSystem(
-		props,
-		'NavigatorScreen'
-	);
+
+	const {
+		children,
+		className,
+		path,
+		onAnimationEnd: onAnimationEndProp,
+		...otherProps
+	} = useContextSystem( props, 'Navigator.Screen' );
 
 	const { location, match, addScreen, removeScreen } =
 		useContext( NavigatorContext );
+	const { isInitial, isBack, focusTargetSelector, skipFocus } = location;
+
 	const isMatch = match === screenId;
 	const wrapperRef = useRef< HTMLDivElement >( null );
+	const skipAnimationAndFocusRestoration = !! isInitial && ! isBack;
 
+	// Register / unregister screen with the navigator context.
 	useEffect( () => {
 		const screen = {
 			id: screenId,
@@ -60,31 +68,28 @@ function UnconnectedNavigatorScreen(
 		return () => removeScreen( screen );
 	}, [ screenId, path, addScreen, removeScreen ] );
 
-	const isRTL = isRTLFn();
-	const { isInitial, isBack } = location;
+	// Animation.
+	const { animationStyles, shouldRenderScreen, screenProps } =
+		useScreenAnimatePresence( {
+			isMatch,
+			isBack,
+			onAnimationEnd: onAnimationEndProp,
+			skipAnimation: skipAnimationAndFocusRestoration,
+		} );
+
 	const cx = useCx();
 	const classes = useMemo(
-		() =>
-			cx(
-				styles.navigatorScreen( {
-					isInitial,
-					isBack,
-					isRTL,
-				} ),
-				className
-			),
-		[ className, cx, isInitial, isBack, isRTL ]
+		() => cx( styles.navigatorScreen, animationStyles, className ),
+		[ className, cx, animationStyles ]
 	);
 
+	// Focus restoration
 	const locationRef = useRef( location );
-
 	useEffect( () => {
 		locationRef.current = location;
 	}, [ location ] );
-
-	// Focus restoration
-	const isInitialLocation = location.isInitial && ! location.isBack;
 	useEffect( () => {
+		const wrapperEl = wrapperRef.current;
 		// 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
@@ -92,20 +97,20 @@ function UnconnectedNavigatorScreen(
 		// - if focus hasn't already been restored for the current location
 		// - if the `skipFocus` option is not set to `true`. This is useful when we trigger the navigation outside of NavigatorScreen.
 		if (
-			isInitialLocation ||
+			skipAnimationAndFocusRestoration ||
 			! isMatch ||
-			! wrapperRef.current ||
+			! wrapperEl ||
 			locationRef.current.hasRestoredFocus ||
-			location.skipFocus
+			skipFocus
 		) {
 			return;
 		}
 
-		const activeElement = wrapperRef.current.ownerDocument.activeElement;
+		const activeElement = wrapperEl.ownerDocument.activeElement;
 
 		// If an element is already focused within the wrapper do not focus the
 		// element. This prevents inputs or buttons from losing focus unnecessarily.
-		if ( wrapperRef.current.contains( activeElement ) ) {
+		if ( wrapperEl.contains( activeElement ) ) {
 			return;
 		}
 
@@ -113,75 +118,42 @@ 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 && location.focusTargetSelector ) {
-			elementToFocus = wrapperRef.current.querySelector(
-				location.focusTargetSelector
-			);
+		if ( isBack && focusTargetSelector ) {
+			elementToFocus = wrapperEl.querySelector( 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 );
-			elementToFocus = firstTabbable ?? wrapperRef.current;
+			const [ firstTabbable ] = focus.tabbable.find( wrapperEl );
+			elementToFocus = firstTabbable ?? wrapperEl;
 		}
 
 		locationRef.current.hasRestoredFocus = true;
 		elementToFocus.focus();
 	}, [
-		isInitialLocation,
+		skipAnimationAndFocusRestoration,
 		isMatch,
-		location.isBack,
-		location.focusTargetSelector,
-		location.skipFocus,
+		isBack,
+		focusTargetSelector,
+		skipFocus,
 	] );
 
 	const mergedWrapperRef = useMergeRefs( [ forwardedRef, wrapperRef ] );
 
-	return isMatch ? (
-		<View ref={ mergedWrapperRef } className={ classes } { ...otherProps }>
+	return shouldRenderScreen ? (
+		<View
+			ref={ mergedWrapperRef }
+			className={ classes }
+			{ ...screenProps }
+			{ ...otherProps }
+		>
 			{ children }
 		</View>
 	) : null;
 }
 
-/**
- * The `NavigatorScreen` component represents a single view/screen/panel and
- * should be used in combination with the `NavigatorProvider`, the
- * `NavigatorButton` and the `NavigatorBackButton` components (or the `useNavigator`
- * hook).
- *
- * @example
- * ```jsx
- * import {
- *   __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>
- *       <NavigatorBackButton>
- *         Go back
- *       </NavigatorBackButton>
- *     </NavigatorScreen>
- *   </NavigatorProvider>
- * );
- * ```
- */
 export const NavigatorScreen = contextConnect(
 	UnconnectedNavigatorScreen,
-	'NavigatorScreen'
+	'Navigator.Screen'
 );
-
-export default NavigatorScreen;

package/src/navigator/navigator-screen/use-screen-animate-presence.ts

@@ -0,0 +1,177 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	useState,
+	useEffect,
+	useLayoutEffect,
+	useCallback,
+} from '@wordpress/element';
+import { useReducedMotion } from '@wordpress/compose';
+import { isRTL as isRTLFn } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import * as styles from '../styles';
+
+// Possible values:
+// - 'INITIAL': the initial state
+// - 'ANIMATING_IN': start enter animation
+// - 'IN': enter animation has ended
+// - 'ANIMATING_OUT': start exit animation
+// - 'OUT': the exit animation has ended
+type AnimationStatus =
+	| 'INITIAL'
+	| 'ANIMATING_IN'
+	| 'IN'
+	| 'ANIMATING_OUT'
+	| 'OUT';
+
+// Allow an extra 20% of the total animation duration to account for potential
+// event loop delays.
+const ANIMATION_TIMEOUT_MARGIN = 1.2;
+
+const isEnterAnimation = (
+	animationDirection: 'end' | 'start',
+	animationStatus: AnimationStatus,
+	animationName: string
+) =>
+	animationStatus === 'ANIMATING_IN' &&
+	animationName === styles.ANIMATION_END_NAMES[ animationDirection ].in;
+
+const isExitAnimation = (
+	animationDirection: 'end' | 'start',
+	animationStatus: AnimationStatus,
+	animationName: string
+) =>
+	animationStatus === 'ANIMATING_OUT' &&
+	animationName === styles.ANIMATION_END_NAMES[ animationDirection ].out;
+
+export function useScreenAnimatePresence( {
+	isMatch,
+	skipAnimation,
+	isBack,
+	onAnimationEnd,
+}: {
+	isMatch: boolean;
+	skipAnimation: boolean;
+	isBack?: boolean;
+	onAnimationEnd?: React.AnimationEventHandler< Element >;
+} ) {
+	const isRTL = isRTLFn();
+	const prefersReducedMotion = useReducedMotion();
+
+	const [ animationStatus, setAnimationStatus ] =
+		useState< AnimationStatus >( 'INITIAL' );
+
+	// Start enter and exit animations when the screen is selected or deselected.
+	// The animation status is set to `IN` or `OUT` immediately if the animation
+	// should be skipped.
+	const becameSelected =
+		animationStatus !== 'ANIMATING_IN' &&
+		animationStatus !== 'IN' &&
+		isMatch;
+	const becameUnselected =
+		animationStatus !== 'ANIMATING_OUT' &&
+		animationStatus !== 'OUT' &&
+		! isMatch;
+	useLayoutEffect( () => {
+		if ( becameSelected ) {
+			setAnimationStatus(
+				skipAnimation || prefersReducedMotion ? 'IN' : 'ANIMATING_IN'
+			);
+		} else if ( becameUnselected ) {
+			setAnimationStatus(
+				skipAnimation || prefersReducedMotion ? 'OUT' : 'ANIMATING_OUT'
+			);
+		}
+	}, [
+		becameSelected,
+		becameUnselected,
+		skipAnimation,
+		prefersReducedMotion,
+	] );
+
+	// Animation attributes (derived state).
+	const animationDirection =
+		( isRTL && isBack ) || ( ! isRTL && ! isBack ) ? 'end' : 'start';
+	const isAnimatingIn = animationStatus === 'ANIMATING_IN';
+	const isAnimatingOut = animationStatus === 'ANIMATING_OUT';
+	let animationType: 'in' | 'out' | undefined;
+	if ( isAnimatingIn ) {
+		animationType = 'in';
+	} else if ( isAnimatingOut ) {
+		animationType = 'out';
+	}
+
+	const onScreenAnimationEnd = useCallback(
+		( e: React.AnimationEvent< HTMLElement > ) => {
+			onAnimationEnd?.( e );
+
+			if (
+				isExitAnimation(
+					animationDirection,
+					animationStatus,
+					e.animationName
+				)
+			) {
+				// When the exit animation ends on an unselected screen, set the
+				// status to 'OUT' to remove the screen contents from the DOM.
+				setAnimationStatus( 'OUT' );
+			} else if (
+				isEnterAnimation(
+					animationDirection,
+					animationStatus,
+					e.animationName
+				)
+			) {
+				// When the enter animation ends on a selected screen, set the
+				// status to 'IN' to ensure the screen is rendered in the DOM.
+				setAnimationStatus( 'IN' );
+			}
+		},
+		[ onAnimationEnd, animationStatus, animationDirection ]
+	);
+
+	// Fallback timeout to ensure that the logic is applied even if the
+	// `animationend` event is not triggered.
+	useEffect( () => {
+		let animationTimeout: number | undefined;
+
+		if ( isAnimatingOut ) {
+			animationTimeout = window.setTimeout( () => {
+				setAnimationStatus( 'OUT' );
+				animationTimeout = undefined;
+			}, styles.TOTAL_ANIMATION_DURATION.OUT * ANIMATION_TIMEOUT_MARGIN );
+		} else if ( isAnimatingIn ) {
+			animationTimeout = window.setTimeout( () => {
+				setAnimationStatus( 'IN' );
+				animationTimeout = undefined;
+			}, styles.TOTAL_ANIMATION_DURATION.IN * ANIMATION_TIMEOUT_MARGIN );
+		}
+
+		return () => {
+			if ( animationTimeout ) {
+				window.clearTimeout( animationTimeout );
+				animationTimeout = undefined;
+			}
+		};
+	}, [ isAnimatingOut, isAnimatingIn ] );
+
+	return {
+		animationStyles: styles.navigatorScreenAnimation,
+		// Render the screen's contents in the DOM not only when the screen is
+		// selected, but also while it is animating out.
+		shouldRenderScreen:
+			isMatch ||
+			animationStatus === 'IN' ||
+			animationStatus === 'ANIMATING_OUT',
+		screenProps: {
+			onAnimationEnd: onScreenAnimationEnd,
+			'data-animation-direction': animationDirection,
+			'data-animation-type': animationType,
+			'data-skip-animation': skipAnimation || undefined,
+		},
+	} as const;
+}

package/src/navigator/navigator-to-parent-button/component.tsx

@@ -17,21 +17,16 @@ function UnconnectedNavigatorToParentButton(
 ) {
 	deprecated( 'wp.components.NavigatorToParentButton', {
 		since: '6.7',
-		alternative: 'wp.components.NavigatorBackButton',
+		alternative: 'wp.components.Navigator.BackButton',
 	} );
 
 	return <NavigatorBackButton ref={ forwardedRef } { ...props } />;
 }
 
 /**
- * _Note: this component is deprecated. Please use the `NavigatorBackButton`
- * component instead._
- *
  * @deprecated
  */
 export const NavigatorToParentButton = contextConnect(
 	UnconnectedNavigatorToParentButton,
-	'NavigatorToParentButton'
+	'Navigator.ToParentButton'
 );
-
-export default NavigatorToParentButton;