@wordpress/components 28.8.6 → 28.10.0

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

package/src/navigator/styles.ts

@@ -3,69 +3,140 @@
  */
 import { css, keyframes } from '@emotion/react';
 
-export const navigatorProviderWrapper = css`
+export const navigatorWrapper = css`
+	position: relative;
 	/* Prevents horizontal overflow while animating screen transitions */
-	overflow-x: hidden;
-	/* Mark this subsection of the DOM as isolated, providing performance benefits
-	 * by limiting calculations of layout, style and paint to a DOM subtree rather
-	 * than the entire page.
+	overflow-x: clip;
+	/*
+	 * Mark this DOM subtree as isolated when it comes to layout calculations,
+	 * providing performance benefits.
 	 */
-	contain: content;
+	contain: layout;
+
+	display: grid;
+	grid-template-columns: 1fr;
+	grid-template-rows: 1fr;
+	align-items: start;
 `;
 
-const fadeInFromRight = keyframes( {
-	'0%': {
+const fadeIn = keyframes( {
+	from: {
 		opacity: 0,
-		transform: `translateX( 50px )`,
 	},
-	'100%': { opacity: 1, transform: 'none' },
 } );
 
-const fadeInFromLeft = keyframes( {
-	'0%': {
+const fadeOut = keyframes( {
+	to: {
 		opacity: 0,
-		transform: `translateX( -50px )`,
 	},
-	'100%': { opacity: 1, transform: 'none' },
 } );
 
-type NavigatorScreenAnimationProps = {
-	isInitial?: boolean;
-	isBack?: boolean;
-	isRTL: boolean;
+export const slideFromRight = keyframes( {
+	from: {
+		transform: 'translateX(100px)',
+	},
+} );
+
+export const slideToLeft = keyframes( {
+	to: {
+		transform: 'translateX(-80px)',
+	},
+} );
+
+export const slideFromLeft = keyframes( {
+	from: {
+		transform: 'translateX(-100px)',
+	},
+} );
+
+export const slideToRight = keyframes( {
+	to: {
+		transform: 'translateX(80px)',
+	},
+} );
+
+const FADE = {
+	DURATION: 70,
+	EASING: 'linear',
+	DELAY: {
+		IN: 70,
+		OUT: 40,
+	},
+};
+const SLIDE = {
+	DURATION: 300,
+	EASING: 'cubic-bezier(0.33, 0, 0, 1)',
+};
+
+export const TOTAL_ANIMATION_DURATION = {
+	IN: Math.max( FADE.DURATION + FADE.DELAY.IN, SLIDE.DURATION ),
+	OUT: Math.max( FADE.DURATION + FADE.DELAY.OUT, SLIDE.DURATION ),
 };
 
-const navigatorScreenAnimation = ( {
-	isInitial,
-	isBack,
-	isRTL,
-}: NavigatorScreenAnimationProps ) => {
-	if ( isInitial && ! isBack ) {
-		return;
-	}
+export const ANIMATION_END_NAMES = {
+	end: {
+		in: slideFromRight.name,
+		out: slideToLeft.name,
+	},
+	start: {
+		in: slideFromLeft.name,
+		out: slideToRight.name,
+	},
+};
 
-	const animationName =
-		( isRTL && isBack ) || ( ! isRTL && ! isBack )
-			? fadeInFromRight
-			: fadeInFromLeft;
+const ANIMATION = {
+	end: {
+		in: css`
+			${ FADE.DURATION }ms ${ FADE.EASING } ${ FADE.DELAY
+				.IN }ms both ${ fadeIn }, ${ SLIDE.DURATION }ms ${ SLIDE.EASING } both ${ slideFromRight }
+		`,
+		out: css`
+			${ FADE.DURATION }ms ${ FADE.EASING } ${ FADE.DELAY
+				.OUT }ms both ${ fadeOut }, ${ SLIDE.DURATION }ms ${ SLIDE.EASING } both ${ slideToLeft }
+		`,
+	},
+	start: {
+		in: css`
+			${ FADE.DURATION }ms ${ FADE.EASING } ${ FADE.DELAY
+				.IN }ms both ${ fadeIn }, ${ SLIDE.DURATION }ms ${ SLIDE.EASING } both ${ slideFromLeft }
+		`,
+		out: css`
+			${ FADE.DURATION }ms ${ FADE.EASING } ${ FADE.DELAY
+				.OUT }ms both ${ fadeOut }, ${ SLIDE.DURATION }ms ${ SLIDE.EASING } both ${ slideToRight }
+		`,
+	},
+} as const;
+export const navigatorScreenAnimation = css`
+	z-index: 1;
 
-	return css`
-		animation-duration: 0.14s;
-		animation-timing-function: ease-in-out;
-		will-change: transform, opacity;
-		animation-name: ${ animationName };
+	&[data-animation-type='out'] {
+		z-index: 0;
+	}
 
-		@media ( prefers-reduced-motion ) {
-			animation-duration: 0s;
+	@media not ( prefers-reduced-motion ) {
+		&:not( [data-skip-animation] ) {
+			${ ( [ 'start', 'end' ] as const ).map( ( direction ) =>
+				( [ 'in', 'out' ] as const ).map(
+					( type ) => css`
+						&[data-animation-direction='${ direction }'][data-animation-type='${ type }'] {
+							animation: ${ ANIMATION[ direction ][ type ] };
+						}
+					`
+				)
+			) }
 		}
-	`;
-};
+	}
+`;
 
-export const navigatorScreen = ( props: NavigatorScreenAnimationProps ) => css`
+export const navigatorScreen = css`
 	/* Ensures horizontal overflow is visually accessible */
 	overflow-x: auto;
 	/* In case the root has a height, it should not be exceeded */
 	max-height: 100%;
+	box-sizing: border-box;
+
+	position: relative;
 
-	${ navigatorScreenAnimation( props ) }
+	grid-column: 1 / -1;
+	grid-row: 1 / -1;
 `;

package/src/navigator/test/index.tsx

@@ -14,14 +14,8 @@ import { useState } from '@wordpress/element';
  * Internal dependencies
  */
 import Button from '../../button';
-import {
-	NavigatorProvider,
-	NavigatorScreen,
-	NavigatorButton,
-	NavigatorBackButton,
-	NavigatorToParentButton,
-	useNavigator,
-} from '..';
+import { Navigator, useNavigator } from '..';
+import { NavigatorToParentButton } from '../legacy';
 import type { NavigateOptions } from '../types';
 
 const INVALID_HTML_ATTRIBUTE = {
@@ -76,11 +70,11 @@ function CustomNavigatorButton( {
 	path,
 	onClick,
 	...props
-}: Omit< ComponentPropsWithoutRef< typeof NavigatorButton >, 'onClick' > & {
+}: Omit< ComponentPropsWithoutRef< typeof Navigator.Button >, 'onClick' > & {
 	onClick?: CustomTestOnClickHandler;
 } ) {
 	return (
-		<NavigatorButton
+		<Navigator.Button
 			onClick={ () => {
 				// Used to spy on the values passed to `navigator.goTo`.
 				onClick?.( { type: 'goTo', path } );
@@ -95,7 +89,7 @@ function CustomNavigatorGoToBackButton( {
 	path,
 	onClick,
 	...props
-}: Omit< ComponentPropsWithoutRef< typeof NavigatorButton >, 'onClick' > & {
+}: Omit< ComponentPropsWithoutRef< typeof Navigator.Button >, 'onClick' > & {
 	onClick?: CustomTestOnClickHandler;
 } ) {
 	const { goTo } = useNavigator();
@@ -115,7 +109,7 @@ function CustomNavigatorGoToSkipFocusButton( {
 	path,
 	onClick,
 	...props
-}: Omit< ComponentPropsWithoutRef< typeof NavigatorButton >, 'onClick' > & {
+}: Omit< ComponentPropsWithoutRef< typeof Navigator.Button >, 'onClick' > & {
 	onClick?: CustomTestOnClickHandler;
 } ) {
 	const { goTo } = useNavigator();
@@ -134,11 +128,14 @@ function CustomNavigatorGoToSkipFocusButton( {
 function CustomNavigatorBackButton( {
 	onClick,
 	...props
-}: Omit< ComponentPropsWithoutRef< typeof NavigatorBackButton >, 'onClick' > & {
+}: Omit<
+	ComponentPropsWithoutRef< typeof Navigator.BackButton >,
+	'onClick'
+> & {
 	onClick?: CustomTestOnClickHandler;
 } ) {
 	return (
-		<NavigatorBackButton
+		<Navigator.BackButton
 			onClick={ () => {
 				// Used to spy on the values passed to `navigator.goBack`.
 				onClick?.( { type: 'goBack' } );
@@ -151,7 +148,10 @@ function CustomNavigatorBackButton( {
 function CustomNavigatorToParentButton( {
 	onClick,
 	...props
-}: Omit< ComponentPropsWithoutRef< typeof NavigatorBackButton >, 'onClick' > & {
+}: Omit<
+	ComponentPropsWithoutRef< typeof Navigator.BackButton >,
+	'onClick'
+> & {
 	onClick?: CustomTestOnClickHandler;
 } ) {
 	return (
@@ -194,13 +194,13 @@ const ProductScreen = ( {
 	const { params } = useNavigator();
 
 	return (
-		<NavigatorScreen path={ PATHS.PRODUCT_PATTERN }>
+		<Navigator.Screen path={ PATHS.PRODUCT_PATTERN }>
 			<p>{ SCREEN_TEXT.product }</p>
 			<p>Product ID is { params.productId }</p>
 			<CustomNavigatorBackButton onClick={ onBackButtonClick }>
 				{ BUTTON_TEXT.back }
 			</CustomNavigatorBackButton>
-		</NavigatorScreen>
+		</Navigator.Screen>
 	);
 };
 
@@ -215,8 +215,8 @@ const MyNavigation = ( {
 	const [ outerInputValue, setOuterInputValue ] = useState( '' );
 	return (
 		<>
-			<NavigatorProvider initialPath={ initialPath }>
-				<NavigatorScreen path={ PATHS.HOME }>
+			<Navigator initialPath={ initialPath }>
+				<Navigator.Screen path={ PATHS.HOME }>
 					<p>{ SCREEN_TEXT.home }</p>
 					{ /*
 					 * A button useful to test focus restoration. This button is the first
@@ -254,9 +254,9 @@ const MyNavigation = ( {
 					>
 						{ BUTTON_TEXT.toInvalidHtmlPathScreen }
 					</CustomNavigatorButton>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
-				<NavigatorScreen path={ PATHS.CHILD }>
+				<Navigator.Screen path={ PATHS.CHILD }>
 					<p>{ SCREEN_TEXT.child }</p>
 					{ /*
 					 * A button useful to test focus restoration. This button is the first
@@ -286,30 +286,30 @@ const MyNavigation = ( {
 						} }
 						value={ innerInputValue }
 					/>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
-				<NavigatorScreen path={ PATHS.NESTED }>
+				<Navigator.Screen path={ PATHS.NESTED }>
 					<p>{ SCREEN_TEXT.nested }</p>
 					<CustomNavigatorBackButton
 						onClick={ onNavigatorButtonClick }
 					>
 						{ BUTTON_TEXT.back }
 					</CustomNavigatorBackButton>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
 				<ProductScreen onBackButtonClick={ onNavigatorButtonClick } />
 
-				<NavigatorScreen path={ PATHS.INVALID_HTML_ATTRIBUTE }>
+				<Navigator.Screen path={ PATHS.INVALID_HTML_ATTRIBUTE }>
 					<p>{ SCREEN_TEXT.invalidHtmlPath }</p>
 					<CustomNavigatorBackButton
 						onClick={ onNavigatorButtonClick }
 					>
 						{ BUTTON_TEXT.back }
 					</CustomNavigatorBackButton>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
-				{ /* A `NavigatorScreen` with `path={ PATHS.NOT_FOUND }` is purposefully not included. */ }
-			</NavigatorProvider>
+				{ /* A `Navigator.Screen` with `path={ PATHS.NOT_FOUND }` is purposefully not included. */ }
+			</Navigator>
 
 			<label htmlFor="test-input-outer">Outer input</label>
 			<input
@@ -334,8 +334,8 @@ const MyHierarchicalNavigation = ( {
 } ) => {
 	return (
 		<>
-			<NavigatorProvider initialPath={ initialPath }>
-				<NavigatorScreen path={ PATHS.HOME }>
+			<Navigator initialPath={ initialPath }>
+				<Navigator.Screen path={ PATHS.HOME }>
 					<p>{ SCREEN_TEXT.home }</p>
 					{ /*
 					 * A button useful to test focus restoration. This button is the first
@@ -349,9 +349,9 @@ const MyHierarchicalNavigation = ( {
 					>
 						{ BUTTON_TEXT.toChildScreen }
 					</CustomNavigatorButton>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
-				<NavigatorScreen path={ PATHS.CHILD }>
+				<Navigator.Screen path={ PATHS.CHILD }>
 					<p>{ SCREEN_TEXT.child }</p>
 					{ /*
 					 * A button useful to test focus restoration. This button is the first
@@ -370,9 +370,9 @@ const MyHierarchicalNavigation = ( {
 					>
 						{ BUTTON_TEXT.back }
 					</CustomNavigatorBackButton>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
-				<NavigatorScreen path={ PATHS.NESTED }>
+				<Navigator.Screen path={ PATHS.NESTED }>
 					<p>{ SCREEN_TEXT.nested }</p>
 					<CustomNavigatorBackButton
 						onClick={ onNavigatorButtonClick }
@@ -385,14 +385,14 @@ const MyHierarchicalNavigation = ( {
 					>
 						{ BUTTON_TEXT.backUsingGoTo }
 					</CustomNavigatorGoToBackButton>
-				</NavigatorScreen>
+				</Navigator.Screen>
 				<CustomNavigatorGoToSkipFocusButton
 					path={ PATHS.NESTED }
 					onClick={ onNavigatorButtonClick }
 				>
 					{ BUTTON_TEXT.goToWithSkipFocus }
 				</CustomNavigatorGoToSkipFocusButton>
-			</NavigatorProvider>
+			</Navigator>
 		</>
 	);
 };
@@ -406,8 +406,8 @@ const MyDeprecatedNavigation = ( {
 } ) => {
 	return (
 		<>
-			<NavigatorProvider initialPath={ initialPath }>
-				<NavigatorScreen path={ PATHS.HOME }>
+			<Navigator initialPath={ initialPath }>
+				<Navigator.Screen path={ PATHS.HOME }>
 					<p>{ SCREEN_TEXT.home }</p>
 					{ /*
 					 * A button useful to test focus restoration. This button is the first
@@ -421,9 +421,9 @@ const MyDeprecatedNavigation = ( {
 					>
 						{ BUTTON_TEXT.toChildScreen }
 					</CustomNavigatorButton>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
-				<NavigatorScreen path={ PATHS.CHILD }>
+				<Navigator.Screen path={ PATHS.CHILD }>
 					<p>{ SCREEN_TEXT.child }</p>
 					{ /*
 					 * A button useful to test focus restoration. This button is the first
@@ -442,17 +442,17 @@ const MyDeprecatedNavigation = ( {
 					>
 						{ BUTTON_TEXT.back }
 					</CustomNavigatorToParentButton>
-				</NavigatorScreen>
+				</Navigator.Screen>
 
-				<NavigatorScreen path={ PATHS.NESTED }>
+				<Navigator.Screen path={ PATHS.NESTED }>
 					<p>{ SCREEN_TEXT.nested }</p>
 					<CustomNavigatorToParentButtonAlternative
 						onClick={ onNavigatorButtonClick }
 					>
 						{ BUTTON_TEXT.back }
 					</CustomNavigatorToParentButtonAlternative>
-				</NavigatorScreen>
-			</NavigatorProvider>
+				</Navigator.Screen>
+			</Navigator>
 		</>
 	);
 };
@@ -643,10 +643,10 @@ describe( 'Navigator', () => {
 	} );
 
 	it( 'should warn if the `path` prop does not follow the required format', () => {
-		render( <NavigatorScreen path="not-valid">Test</NavigatorScreen> );
+		render( <Navigator.Screen path="not-valid">Test</Navigator.Screen> );
 
 		expect( console ).toHaveWarnedWith(
-			'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.'
 		);
 	} );
 
@@ -880,7 +880,7 @@ describe( 'Navigator', () => {
 
 			// Rendering `NavigatorToParentButton` logs a deprecation notice
 			expect( console ).toHaveWarnedWith(
-				'wp.components.NavigatorToParentButton is deprecated since version 6.7. Please use wp.components.NavigatorBackButton instead.'
+				'wp.components.NavigatorToParentButton is deprecated since version 6.7. Please use wp.components.Navigator.BackButton instead.'
 			);
 		} );
 

package/src/navigator/types.ts

@@ -86,7 +86,7 @@ export type NavigatorContext = Navigator & {
 	match?: string;
 };
 
-export type NavigatorProviderProps = {
+export type NavigatorProps = {
 	/**
 	 * The initial active path.
 	 */
@@ -100,6 +100,24 @@ export type NavigatorProviderProps = {
 export type NavigatorScreenProps = {
 	/**
 	 * The screen's path, matched against the current path stored in the navigator.
+	 *
+	 * `Navigator` assumes that screens are organized hierarchically according
+	 * to their `path`, which should follow a URL-like scheme where each path
+	 * segment starts with and is separated by the `/` character.
+	 *
+	 * `Navigator` will treat "back" navigations as going to the parent screen —
+	 * it is, therefore, the responsibility of the consumer of the component to
+	 * create the correct screen hierarchy.
+	 *
+	 * 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;
+	 *  - if the current screen has a `path="/parent/child/grand-child"`, when
+	 *    going "back" `Navigator` will try to recursively navigate the path
+	 *    hierarchy until a matching screen (or the root `/`) is found.
 	 */
 	path: string;
 	/**