Components: refactor Navigator* folder structure, rename Navigator to NavigatorProvider

docs/manifest.json

@@ -1068,9 +1068,15 @@
 		"parent": "components"
 	},
 	{
-		"title": "Navigator",
-		"slug": "navigator",
-		"markdown_source": "../packages/components/src/navigator/README.md",
+		"title": "NavigatorProvider",
+		"slug": "navigator-provider",
+		"markdown_source": "../packages/components/src/navigator/navigator-provider/README.md",
+		"parent": "components"
+	},
+	{
+		"title": "NavigatorScreen",
+		"slug": "navigator-screen",
+		"markdown_source": "../packages/components/src/navigator/navigator-screen/README.md",
 		"parent": "components"
 	},
 	{

packages/components/src/index.js

@@ -97,7 +97,7 @@ export { default as __experimentalNavigationGroup } from './navigation/group';
 export { default as __experimentalNavigationItem } from './navigation/item';
 export { default as __experimentalNavigationMenu } from './navigation/menu';
 export {
-	Navigator as __experimentalNavigator,
+	NavigatorProvider as __experimentalNavigatorProvider,
 	NavigatorScreen as __experimentalNavigatorScreen,
 	useNavigator as __experimentalUseNavigator,
 } from './navigator';

packages/components/src/navigator/index.js

@@ -1,3 +1,3 @@
-export { default as Navigator } from './navigator';
-export { default as NavigatorScreen } from './screen';
+export { default as NavigatorProvider } from './navigator-provider';
+export { default as NavigatorScreen } from './navigator-screen';
 export { default as useNavigator } from './use-navigator';

packages/components/src/navigator/README.md → packages/components/src/navigator/navigator-provider/README.md

@@ -1,18 +1,18 @@
-# Navigator
+# `NavigatorProvider`
 
 <div class="callout callout-alert">
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>
 
-The Navigator components allows rendering nested panels or menus (also called screens) and navigate between these different states. The Global Styles sidebar is an example of this.
+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 components is not opinionated in terms of UI, it lets compose any UI components to navigate between the nested screens.
+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
 import {
-	__experimentalNavigator as Navigator,
+	__experimentalNavigatorProvider as NavigatorProvider,
 	__experimentalNavigatorScreen as NavigatorScreen,
 	__experimentalUseNavigator as useNavigator,
 } from '@wordpress/components';
@@ -32,7 +32,7 @@ function NavigatorButton( {
 }
 
 const MyNavigation = () => (
-	<Navigator initialPath="/">
+	<NavigatorProvider initialPath="/">
 		<NavigatorScreen path="/">
 			<p>This is the home screen.</p>
 			<NavigatorButton isPrimary path="/child">
@@ -46,43 +46,31 @@ const MyNavigation = () => (
 				Go back
 			</NavigatorButton>
 		</NavigatorScreen>
-	</Navigator>
+	</NavigatorProvider>
 );
 ```
 
-## Navigator Props
+## Props
 
-`Navigator` supports the following props.
+The component accepts the following props:
 
-### `initialPath`
-
--   Type: `string`
--   Required: No
+### `initialPath`: `string`
 
 The initial active path.
 
-## NavigatorScreen Props
-
-`NavigatorScreen` supports the following props.
-
-### `path`
-
--   Type: `string`
--   Required: Yes
+-   Required: No
 
-The path of the current screen.
 
-## The navigator object.
+## The navigator object
 
 You can retrieve a `navigator` instance by using the `useNavigator` hook.
-The navigator offers the following methods:
 
-### `push`
+The hook offers the following methods:
 
--   Type: `( path: string, options ) => void`
+### `push`: `( path: string, options ) => void`
 
 The `push` function allows you to navigate 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.
+- `isBack` (`boolean): A boolean flag indicating that we're moving back to a previous state. -->

packages/components/src/navigator/navigator.js → packages/components/src/navigator/navigator-provider/component.js

@@ -6,9 +6,9 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { NavigatorContext } from './context';
+import { NavigatorContext } from '../context';
 
-function Navigator( { initialPath, children } ) {
+function NavigatorProvider( { initialPath, children } ) {
 	const [ path, setPath ] = useState( { path: initialPath } );
 
 	return (
@@ -18,4 +18,4 @@ function Navigator( { initialPath, children } ) {
 	);
 }
 
-export default Navigator;
+export default NavigatorProvider;

packages/components/src/navigator/navigator-provider/index.js

@@ -0,0 +1 @@
+export { default } from './component';

packages/components/src/navigator/navigator-screen/README.md

@@ -0,0 +1,22 @@
+# `NavigatorScreen`
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+The `NavigatorScreen` component represents a single view/screen/panel/menu and is supposed to be used in combination with [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md).
+
+## Usage
+
+Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example.
+
+## Props
+
+The component accepts the following props:
+
+### `path`
+
+-   Type: `string`
+-   Required: Yes
+
+The path of the current screen.

packages/components/src/navigator/screen.js → packages/components/src/navigator/navigator-screen/component.js

@@ -14,7 +14,7 @@ import { isRTL } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
-import { NavigatorContext } from './context';
+import { NavigatorContext } from '../context';
 
 const animationEnterDelay = 0;
 const animationEnterDuration = 0.14;

packages/components/src/navigator/navigator-screen/index.js

@@ -0,0 +1 @@
+export { default } from './component';

packages/components/src/navigator/stories/index.js

@@ -2,11 +2,11 @@
  * Internal dependencies
  */
 import Button from '../../button';
-import { Navigator, NavigatorScreen, useNavigator } from '../';
+import { NavigatorProvider, NavigatorScreen, useNavigator } from '../';
 
 export default {
 	title: 'Components (Experimental)/Navigator',
-	component: Navigator,
+	component: NavigatorProvider,
 };
 
 function NavigatorButton( { path, isBack = false, ...props } ) {
@@ -20,7 +20,7 @@ function NavigatorButton( { path, isBack = false, ...props } ) {
 }
 
 const MyNavigation = () => (
-	<Navigator initialPath="/">
+	<NavigatorProvider initialPath="/">
 		<NavigatorScreen path="/">
 			<p>This is the home screen.</p>
 			<NavigatorButton isPrimary path="/child">
@@ -34,7 +34,7 @@ const MyNavigation = () => (
 				Go back
 			</NavigatorButton>
 		</NavigatorScreen>
-	</Navigator>
+	</NavigatorProvider>
 );
 
 export const _default = () => {

packages/components/src/navigator/test/index.js

@@ -6,7 +6,7 @@ import { render, screen, fireEvent } from '@testing-library/react';
 /**
  * Internal dependencies
  */
-import { Navigator, NavigatorScreen, useNavigator } from '../';
+import { NavigatorProvider, NavigatorScreen, useNavigator } from '../';
 
 jest.mock( 'framer-motion', () => {
 	const actual = jest.requireActual( 'framer-motion' );
@@ -47,7 +47,7 @@ const MyNavigation = ( {
 	initialPath = PATHS.HOME,
 	onNavigatorButtonClick,
 } ) => (
-	<Navigator initialPath={ initialPath }>
+	<NavigatorProvider initialPath={ initialPath }>
 		<NavigatorScreen path={ PATHS.HOME }>
 			<p>This is the home screen.</p>
 			<NavigatorButton
@@ -76,7 +76,7 @@ const MyNavigation = ( {
 		</NavigatorScreen>
 
 		{ /* A `NavigatorScreen` with `path={ PATHS.NOT_FOUND }` is purposefully not included */ }
-	</Navigator>
+	</NavigatorProvider>
 );
 
 const getNavigationScreenByText = ( text, { throwIfNotFound = true } = {} ) => {

packages/edit-site/src/components/sidebar/global-styles-sidebar.js

@@ -8,7 +8,7 @@ import { map } from 'lodash';
  */
 import {
 	Button,
-	__experimentalNavigator as Navigator,
+	__experimentalNavigatorProvider as NavigatorProvider,
 	__experimentalNavigatorScreen as NavigatorScreen,
 	__experimentalUseNavigator as useNavigator,
 	__experimentalItemGroup as ItemGroup,
@@ -257,7 +257,7 @@ export default function GlobalStylesSidebar() {
 				</>
 			}
 		>
-			<Navigator initialPath="/">
+			<NavigatorProvider initialPath="/">
 				<NavigatorScreen path="/">
 					<StylePreview />
 
@@ -324,7 +324,7 @@ export default function GlobalStylesSidebar() {
 						setSetting={ setSetting }
 					/>
 				) ) }
-			</Navigator>
+			</NavigatorProvider>
 		</DefaultSidebar>
 	);
 }