Navigator: internal refactor in preparation for stabilization (WordPr…

…ess#65671)

* Rename navigator-provider internal folder to navigator

* Rename internal NavigatorProvider variables to Navigator

* Remove default exports

* Remove JSDocs from individual component files

* Move exports to legacy.ts file, including JSDocs

* Undo folder rename as it was causing a different doc manifest

---

Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>

packages/components/src/index.ts

@@ -131,7 +131,7 @@ export {
 	NavigatorBackButton as __experimentalNavigatorBackButton,
 	NavigatorToParentButton as __experimentalNavigatorToParentButton,
 	useNavigator as __experimentalUseNavigator,
-} from './navigator';
+} from './navigator/legacy';
 export { default as Notice } from './notice';
 export { default as __experimentalNumberControl } from './number-control';
 export { default as NoticeList } from './notice/list';

packages/components/src/navigator/legacy.ts

@@ -0,0 +1,172 @@
+/**
+ * Internal dependencies
+ */
+import { Navigator as InternalNavigator } from './navigator-provider/component';
+import { NavigatorScreen as InternalNavigatorScreen } from './navigator-screen/component';
+import { NavigatorButton as InternalNavigatorButton } from './navigator-button/component';
+import { NavigatorBackButton as InternalNavigatorBackButton } from './navigator-back-button/component';
+import { NavigatorToParentButton as InternalNavigatorToParentButton } from './navigator-to-parent-button/component';
+export { useNavigator } from './use-navigator';
+
+/**
+ * The `NavigatorProvider` component allows rendering nested views/panels/menus
+ * (via the `NavigatorScreen` component and navigate between these different
+ * view (via the `NavigatorButton` and `NavigatorBackButton` components or the
+ * `useNavigator` hook).
+ *
+ * ```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 NavigatorProvider = Object.assign( InternalNavigator, {
+	displayName: 'NavigatorProvider',
+} );
+
+/**
+ * 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 = Object.assign( InternalNavigatorScreen, {
+	displayName: 'NavigatorScreen',
+} );
+
+/**
+ * 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 = Object.assign( InternalNavigatorButton, {
+	displayName: 'NavigatorButton',
+} );
+
+/**
+ * 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 = Object.assign( InternalNavigatorBackButton, {
+	displayName: 'NavigatorBackButton',
+} );
+
+/**
+ * _Note: this component is deprecated. Please use the `NavigatorBackButton`
+ * component instead._
+ *
+ * @deprecated
+ */
+export const NavigatorToParentButton = Object.assign(
+	InternalNavigatorToParentButton,
+	{
+		displayName: 'NavigatorToParentButton',
+	}
+);

packages/components/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'
 );
-
-export default NavigatorBackButton;

packages/components/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'
 );
-
-export default NavigatorButton;

packages/components/src/navigator/navigator-provider/component.tsx

@@ -21,7 +21,7 @@ import { View } from '../../view';
 import { NavigatorContext } from '../context';
 import * as styles from '../styles';
 import type {
-	NavigatorProviderProps,
+	NavigatorProps,
 	NavigatorLocation,
 	NavigatorContext as NavigatorContextType,
 	NavigateOptions,
@@ -213,8 +213,8 @@ function routerReducer(
 	};
 }
 
-function UnconnectedNavigatorProvider(
-	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
+function UnconnectedNavigator(
+	props: WordPressComponentProps< NavigatorProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) {
 	const {
@@ -321,9 +321,9 @@ function UnconnectedNavigatorProvider(
  * );
  * ```
  */
-export const NavigatorProvider = contextConnect(
-	UnconnectedNavigatorProvider,
+export const Navigator = contextConnect(
+	UnconnectedNavigator,
 	'NavigatorProvider'
 );
 
-export default NavigatorProvider;
+export default Navigator;

packages/components/src/navigator/navigator-screen/component.tsx

@@ -153,43 +153,7 @@ function UnconnectedNavigatorScreen(
 	) : 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'
 );
-
-export default NavigatorScreen;

packages/components/src/navigator/navigator-to-parent-button/component.tsx

@@ -23,15 +23,7 @@ function UnconnectedNavigatorToParentButton(
 	return <NavigatorBackButton ref={ forwardedRef } { ...props } />;
 }
 
-/**
- * _Note: this component is deprecated. Please use the `NavigatorBackButton`
- * component instead._
- *
- * @deprecated
- */
 export const NavigatorToParentButton = contextConnect(
 	UnconnectedNavigatorToParentButton,
 	'NavigatorToParentButton'
 );
-
-export default NavigatorToParentButton;

packages/components/src/navigator/stories/index.story.tsx

@@ -14,7 +14,7 @@ import {
 	NavigatorButton,
 	NavigatorBackButton,
 	useNavigator,
-} from '..';
+} from '../legacy';
 import { HStack } from '../../h-stack';
 
 const meta: Meta< typeof NavigatorProvider > = {

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

@@ -21,7 +21,7 @@ import {
 	NavigatorBackButton,
 	NavigatorToParentButton,
 	useNavigator,
-} from '..';
+} from '../legacy';
 import type { NavigateOptions } from '../types';
 
 const INVALID_HTML_ATTRIBUTE = {

packages/components/src/navigator/types.ts

@@ -86,7 +86,7 @@ export type NavigatorContext = Navigator & {
 	match?: string;
 };
 
-export type NavigatorProviderProps = {
+export type NavigatorProps = {
 	/**
 	 * The initial active path.
 	 */