@wordpress/components 28.8.3 → 28.9.0

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;

package/src/navigator/stories/index.story.tsx

@@ -8,20 +8,20 @@ import type { Meta, StoryObj } from '@storybook/react';
  */
 import Button from '../../button';
 import { VStack } from '../../v-stack';
-import {
-	NavigatorProvider,
-	NavigatorScreen,
-	NavigatorButton,
-	NavigatorBackButton,
-	useNavigator,
-} from '..';
 import { HStack } from '../../h-stack';
-
-const meta: Meta< typeof NavigatorProvider > = {
-	component: NavigatorProvider,
-	// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
-	subcomponents: { NavigatorScreen, NavigatorButton, NavigatorBackButton },
-	title: 'Components (Experimental)/Navigator',
+import { Navigator, useNavigator } from '../';
+
+const meta: Meta< typeof Navigator > = {
+	component: Navigator,
+	subcomponents: {
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		Screen: Navigator.Screen,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		Button: Navigator.Button,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		BackButton: Navigator.BackButton,
+	},
+	title: 'Components/Navigator',
 	argTypes: {
 		as: { control: { type: null } },
 		children: { control: { type: null } },
@@ -36,14 +36,14 @@ const meta: Meta< typeof NavigatorProvider > = {
 			return (
 				<>
 					<style>{ `
-					  /* These attributes are a private implementation detail of the
-						  Navigator component. Do not use outside of its source code. */
-						[data-wp-component="NavigatorProvider"] {
-							height: calc(100vh - 2rem);
-							max-height: 250px;
-
+					  /* The data-wp-component attribute is a private implementation
+						 * detail of the Navigator component. Do not use outside of
+						 * its source code.
+						 */
+						[data-wp-component="Navigator"] {
+							height: 250px;
 						}
-						[data-wp-component="NavigatorScreen"]:not([data-sticky]) {
+						[data-wp-component="Navigator.Screen"] {
 							padding: 8px;
 						}
 					` }</style>
@@ -55,55 +55,55 @@ const meta: Meta< typeof NavigatorProvider > = {
 };
 export default meta;
 
-export const Default: StoryObj< typeof NavigatorProvider > = {
+export const Default: StoryObj< typeof Navigator > = {
 	args: {
 		initialPath: '/',
 		children: (
 			<>
-				<NavigatorScreen path="/">
+				<Navigator.Screen path="/">
 					<h2>This is the home screen.</h2>
 
 					<VStack alignment="left">
-						<NavigatorButton variant="primary" path="/child">
+						<Navigator.Button variant="primary" path="/child">
 							Go to child screen.
-						</NavigatorButton>
+						</Navigator.Button>
 
-						<NavigatorButton variant="primary" path="/product/1">
+						<Navigator.Button variant="primary" path="/product/1">
 							Go to dynamic path screen with id 1.
-						</NavigatorButton>
+						</Navigator.Button>
 
-						<NavigatorButton variant="primary" path="/product/2">
+						<Navigator.Button variant="primary" path="/product/2">
 							Go to dynamic path screen with id 2.
-						</NavigatorButton>
+						</Navigator.Button>
 					</VStack>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
-				<NavigatorScreen path="/child">
+				<Navigator.Screen path="/child">
 					<h2>This is the child screen.</h2>
 					<HStack spacing={ 2 } alignment="left">
-						<NavigatorBackButton variant="secondary">
+						<Navigator.BackButton variant="secondary">
 							Go back
-						</NavigatorBackButton>
+						</Navigator.BackButton>
 
-						<NavigatorButton
+						<Navigator.Button
 							variant="primary"
 							path="/child/grandchild"
 						>
 							Go to grand child screen.
-						</NavigatorButton>
+						</Navigator.Button>
 					</HStack>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
-				<NavigatorScreen path="/child/grandchild">
+				<Navigator.Screen path="/child/grandchild">
 					<h2>This is the grand child screen.</h2>
-					<NavigatorBackButton variant="secondary">
+					<Navigator.BackButton variant="secondary">
 						Go back
-					</NavigatorBackButton>
-				</NavigatorScreen>
+					</Navigator.BackButton>
+				</Navigator.Screen>
 
-				<NavigatorScreen path="/product/:id">
+				<Navigator.Screen path="/product/:id">
 					<DynamicScreen />
-				</NavigatorScreen>
+				</Navigator.Screen>
 			</>
 		),
 	},
@@ -119,14 +119,14 @@ function DynamicScreen() {
 				This screen can parse params dynamically. The current id is:{ ' ' }
 				{ params.id }
 			</p>
-			<NavigatorBackButton variant="secondary">
+			<Navigator.BackButton variant="secondary">
 				Go back
-			</NavigatorBackButton>
+			</Navigator.BackButton>
 		</>
 	);
 }
 
-export const WithNestedInitialPath: StoryObj< typeof NavigatorProvider > = {
+export const WithNestedInitialPath: StoryObj< typeof Navigator > = {
 	...Default,
 	args: {
 		...Default.args,
@@ -138,7 +138,7 @@ const NavigatorButtonWithSkipFocus = ( {
 	path,
 	onClick,
 	...props
-}: React.ComponentProps< typeof NavigatorButton > ) => {
+}: React.ComponentProps< typeof Navigator.Button > ) => {
 	const { goTo } = useNavigator();
 
 	return (
@@ -156,7 +156,7 @@ const NavigatorButtonWithSkipFocus = ( {
 	);
 };
 
-export const SkipFocus: StoryObj< typeof NavigatorProvider > = {
+export const SkipFocus: StoryObj< typeof Navigator > = {
 	args: {
 		initialPath: '/',
 		children: (
@@ -167,21 +167,22 @@ export const SkipFocus: StoryObj< typeof NavigatorProvider > = {
 						outline: '1px solid black',
 						outlineOffset: '-1px',
 						marginBlockEnd: '1rem',
+						display: 'contents',
 					} }
 				>
-					<NavigatorScreen path="/">
+					<Navigator.Screen path="/">
 						<h2>Home screen</h2>
-						<NavigatorButton variant="primary" path="/child">
+						<Navigator.Button variant="primary" path="/child">
 							Go to child screen.
-						</NavigatorButton>
-					</NavigatorScreen>
+						</Navigator.Button>
+					</Navigator.Screen>
 
-					<NavigatorScreen path="/child">
+					<Navigator.Screen path="/child">
 						<h2>Child screen</h2>
-						<NavigatorBackButton variant="secondary">
+						<Navigator.BackButton variant="secondary">
 							Go back to home screen
-						</NavigatorBackButton>
-					</NavigatorScreen>
+						</Navigator.BackButton>
+					</Navigator.Screen>
 				</div>
 
 				<NavigatorButtonWithSkipFocus path="/child">