(experiment)(wip) Components: Abstract/namespace all related Navigator components in the root component

packages/components/CHANGELOG.md

@@ -94,6 +94,11 @@
 
 -   `FontSizerPicker`: Improve docs for default units ([#60996](https://github.com/WordPress/gutenberg/pull/60996)).
 
+### Deprecation
+
+-   `Navigator`: Remove "experimental" designation ([#60927](https://github.com/WordPress/gutenberg/pull/60927)).
+-   `Navigator`: Group all related children as properties in the root component `NavigatorProvider` and add a `Navigator` alias for it ([#60926](https://github.com/WordPress/gutenberg/pull/60926)).
+
 ## 27.4.0 (2024-04-19)
 
 ### Deprecations

packages/components/src/index.ts

@@ -116,12 +116,32 @@ export { default as __experimentalNavigationGroup } from './navigation/group';
 export { default as __experimentalNavigationItem } from './navigation/item';
 export { default as __experimentalNavigationMenu } from './navigation/menu';
 export {
+	/**
+	 * @deprecated Import `Navigator` and use `Navigator.Root` instead..
+	 */
 	NavigatorProvider as __experimentalNavigatorProvider,
+	/**
+	 * @deprecated Import `Navigator` and use `Navigator.Screen` instead.
+	 */
 	NavigatorScreen as __experimentalNavigatorScreen,
+	/**
+	 * @deprecated Import `Navigator` and use `Navigator.Button` instead.
+	 */
 	NavigatorButton as __experimentalNavigatorButton,
+	/**
+	 * @deprecated Import `Navigator` and use `Navigator.BackButton` instead.
+	 */
 	NavigatorBackButton as __experimentalNavigatorBackButton,
+	/**
+	 * @deprecated Import `Navigator` and use `Navigator.ToParentButton` instead.
+	 */
 	NavigatorToParentButton as __experimentalNavigatorToParentButton,
+	/**
+	 * @deprecated Import `useNavigator` instead.
+	 */
 	useNavigator as __experimentalUseNavigator,
+	Navigator,
+	useNavigator,
 } from './navigator';
 export { default as Notice } from './notice';
 export { default as __experimentalNumberControl } from './number-control';

packages/components/src/navigator/index.ts

@@ -1,6 +1,25 @@
-export { NavigatorProvider } from './navigator-provider';
-export { NavigatorScreen } from './navigator-screen';
-export { NavigatorButton } from './navigator-button';
-export { NavigatorBackButton } from './navigator-back-button';
-export { NavigatorToParentButton } from './navigator-to-parent-button';
+/**
+ * Internal dependencies
+ */
+import { NavigatorProvider } from './navigator-provider';
+import { NavigatorScreen } from './navigator-screen';
+import { NavigatorButton } from './navigator-button';
+import { NavigatorBackButton } from './navigator-back-button';
+import { NavigatorToParentButton } from './navigator-to-parent-button';
+
+export {
+	NavigatorProvider,
+	NavigatorScreen,
+	NavigatorButton,
+	NavigatorBackButton,
+	NavigatorToParentButton,
+};
 export { default as useNavigator } from './use-navigator';
+
+export const Navigator = {
+	Root: NavigatorProvider,
+	Screen: NavigatorScreen,
+	Button: NavigatorButton,
+	BackButton: NavigatorBackButton,
+	ToParentButton: NavigatorToParentButton,
+};

packages/components/src/navigator/navigator-back-button/README.md

@@ -1,15 +1,11 @@
-# `NavigatorBackButton`
+# `Navigator.BackButton`
 
-<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 `NavigatorBackButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorScreen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) components (or the `useNavigator` hook).
+The `Navigator.BackButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md) (also aliased as `Navigator`), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md) components (or the `useNavigator` hook).
 
 ## Usage
 
 Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example.
 
 ### Inherited props
 
-`NavigatorBackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.
+`Navigator.BackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.

packages/components/src/navigator/navigator-back-button/component.tsx

@@ -22,42 +22,39 @@ function UnconnectedNavigatorBackButton(
 }
 
 /**
- * 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`
+ * The `Navigator.BackButton` component can be used to navigate to a screen and
+ * should be used in combination with the `NavigatorProvider` (also aliased as `Navigator`),
+ * the `Navigator.Screen` and the `Navigator.Button` components (or the `useNavigator`
  * hook).
  *
  * @example
  * ```jsx
  * import {
- *   __experimentalNavigatorProvider as NavigatorProvider,
- *   __experimentalNavigatorScreen as NavigatorScreen,
- *   __experimentalNavigatorButton as NavigatorButton,
- *   __experimentalNavigatorBackButton as NavigatorBackButton,
+ *   Navigator,
  * } from '@wordpress/components';
  *
  * const MyNavigation = () => (
- *   <NavigatorProvider initialPath="/">
- *     <NavigatorScreen path="/">
+ *   <Navigator.Root initialPath="/">
+ *     <Navigator.Screen path="/">
  *       <p>This is the home screen.</p>
- *        <NavigatorButton path="/child">
+ *        <Navigator.Button path="/child">
  *          Navigate to child screen.
- *       </NavigatorButton>
- *     </NavigatorScreen>
+ *       </Navigator.Button>
+ *     </Navigator.Screen>
  *
- *     <NavigatorScreen path="/child">
+ *     <Navigator.Screen path="/child">
  *       <p>This is the child screen.</p>
- *       <NavigatorBackButton>
+ *       <Navigator.BackButton>
  *         Go back
- *       </NavigatorBackButton>
- *     </NavigatorScreen>
- *   </NavigatorProvider>
+ *       </Navigator.BackButton>
+ *     </Navigator.Screen>
+ *   </Navigator.Root>
  * );
  * ```
  */
 export const NavigatorBackButton = contextConnect(
 	UnconnectedNavigatorBackButton,
-	'NavigatorBackButton'
+	'Navigator.BackButton'
 );
 
 export default NavigatorBackButton;

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

@@ -1,10 +1,6 @@
-# `NavigatorButton`
+# `Navigator.Button`
 
-<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 `NavigatorButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorScreen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components (or the `useNavigator` hook).
+The `Navigator.Button` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md) (also aliased as `Navigator`), the [`Navigator.Screen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components (or the `useNavigator` hook).
 
 ## Usage
 
@@ -35,4 +31,4 @@ The path of the screen to navigate to. The value of this prop needs to be [a val
 
 ### Inherited props
 
-`NavigatorButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.
+`Navigator.Button` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.

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

@@ -22,41 +22,38 @@ function UnconnectedNavigatorButton(
 }
 
 /**
- * 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).
+ * The `Navigator.Button` component can be used to navigate to a screen and should
+ * be used in combination with the `NavigatorProvider` (also aliased as `Navigator`), the
+ * `Navigator.Screen` and the `Navigator.BackButton` components (or the `useNavigator` hook).
  *
  * @example
  * ```jsx
  * import {
- *   __experimentalNavigatorProvider as NavigatorProvider,
- *   __experimentalNavigatorScreen as NavigatorScreen,
- *   __experimentalNavigatorButton as NavigatorButton,
- *   __experimentalNavigatorBackButton as NavigatorBackButton,
+ *   Navigator,
  * } from '@wordpress/components';
  *
  * const MyNavigation = () => (
- *   <NavigatorProvider initialPath="/">
- *     <NavigatorScreen path="/">
+ *   <Navigator.Root initialPath="/">
+ *     <Navigator.Screen path="/">
  *       <p>This is the home screen.</p>
- *        <NavigatorButton path="/child">
+ *        <Navigator.Button path="/child">
  *          Navigate to child screen.
- *       </NavigatorButton>
- *     </NavigatorScreen>
+ *       </Navigator.Button>
+ *     </Navigator.Screen>
  *
- *     <NavigatorScreen path="/child">
+ *     <Navigator.Screen path="/child">
  *       <p>This is the child screen.</p>
- *       <NavigatorBackButton>
+ *       <Navigator.BackButton>
  *         Go back
- *       </NavigatorBackButton>
- *     </NavigatorScreen>
- *   </NavigatorProvider>
+ *       </Navigator.BackButton>
+ *     </Navigator.Screen>
+ *   </Navigator.Root>
  * );
  * ```
  */
 export const NavigatorButton = contextConnect(
 	UnconnectedNavigatorButton,
-	'NavigatorButton'
+	'Navigator.Button'
 );
 
 export default NavigatorButton;

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

@@ -1,47 +1,38 @@
 # `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 `NavigatorProvider` component allows rendering nested views/panels/menus (via the [`NavigatorScreen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md), [`NavigatorToParentButton`](/packages/components/src/navigator/navigator-to-parent-button/README.md) and [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). The Global Styles sidebar is an example of this.
+The `NavigatorProvider` (also aliased as `Navigator`) component allows rendering nested views/panels/menus (via the [`Navigator.Screen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the [`Navigator.Button`](/packages/components/src/navigator/navigator-button/README.md), [`Navigator.ToParentButton`](/packages/components/src/navigator/navigator-to-parent-button/README.md) and [`Navigator.BackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). The Global Styles sidebar is an example of this.
 
 ## Usage
 
 ```jsx
-import {
-  __experimentalNavigatorProvider as NavigatorProvider,
-  __experimentalNavigatorScreen as NavigatorScreen,
-  __experimentalNavigatorButton as NavigatorButton,
-  __experimentalNavigatorToParentButton as NavigatorToParentButton,
-} from '@wordpress/components';
+import { Navigator } 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>
-      <NavigatorToParentButton>
-        Go back
-      </NavigatorToParentButton>
-    </NavigatorScreen>
-  </NavigatorProvider>
+	<Navigator.Root initialPath="/">
+		<Navigator.Screen path="/">
+			<p>This is the home screen.</p>
+			<Navigator.Button path="/child">
+				Navigate to child screen.
+			</Navigator.Button>
+		</Navigator.Screen>
+
+		<Navigator.Screen path="/child">
+			<p>This is the child screen.</p>
+			<Navigator.ToParentButton>Go back</Navigator.ToParentButton>
+		</Navigator.Screen>
+	</Navigator.Root>
 );
 ```
+
 **Important note**
 
 Parent/child navigation only works if the path you define are hierarchical, following a URL-like scheme where each path segment is separated by the `/` character.
 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.
+
+-   `/` 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.
 
 ## Props
 
@@ -65,8 +56,8 @@ The `goTo` function allows navigating to a given path. The second argument can a
 
 The available options are:
 
-- `focusTargetSelector`: `string`. An optional property used to specify the CSS selector used to restore focus on the matching element when navigating back.
-- `isBack`: `boolean`. An optional property used to specify whether the navigation should be considered as backwards (thus enabling focus restoration when possible, and causing the animation to be backwards too)
+-   `focusTargetSelector`: `string`. An optional property used to specify the CSS selector used to restore focus on the matching element when navigating back.
+-   `isBack`: `boolean`. An optional property used to specify whether the navigation should be considered as backwards (thus enabling focus restoration when possible, and causing the animation to be backwards too)
 
 ### `goToParent`: `() => void;`
 
@@ -84,9 +75,9 @@ The `goBack` function allows navigating to the previous path.
 
 The `location` object represent the current location, and has a few properties:
 
-- `path`: `string`. The path associated to the location.
-- `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards in the location stack.
-- `isInitial`: `boolean`. A flag that is `true` only for the first (root) location in the location stack.
+-   `path`: `string`. The path associated to the location.
+-   `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards in the location stack.
+-   `isInitial`: `boolean`. A flag that is `true` only for the first (root) location in the location stack.
 
 ### `params`: `Record< string, string | string[] >`
 

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

@@ -27,6 +27,10 @@
 	Screen,
 	NavigateToParentOptions,
 } from '../types';
+import { NavigatorBackButton } from '../navigator-back-button';
+import { NavigatorScreen } from '../navigator-screen';
+import { NavigatorButton } from '../navigator-button';
+import { NavigatorToParentButton } from '../navigator-to-parent-button';
 
 type MatchedPath = ReturnType< typeof patternMatch >;
 
@@ -267,41 +271,37 @@
 }
 
 /**
- * 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).
+ * The `Navigator.Root` allows rendering nested views/panels/menus
+ * (via the `Navigator.Screen` component) and navigate between these
+ * different views (via the `Navigator.Button` and `Navigator.BackButton`
+ * components or the `useNavigator` hook).
  *
  * ```jsx
  * import {
- *   __experimentalNavigatorProvider as NavigatorProvider,
- *   __experimentalNavigatorScreen as NavigatorScreen,
- *   __experimentalNavigatorButton as NavigatorButton,
- *   __experimentalNavigatorBackButton as NavigatorBackButton,
+ *   Navigator,
  * } from '@wordpress/components';
  *
  * const MyNavigation = () => (
- *   <NavigatorProvider initialPath="/">
- *     <NavigatorScreen path="/">
+ *   <Navigator.Root> initialPath="/">
+ *     <Navigator.Screen path="/">
  *       <p>This is the home screen.</p>
- *        <NavigatorButton path="/child">
+ *        <Navigator.Button path="/child">
  *          Navigate to child screen.
- *       </NavigatorButton>
- *     </NavigatorScreen>
+ *       </Navigator.Button>
+ *     </Navigator.Screen>
  *
- *     <NavigatorScreen path="/child">
+ *     <Navigator.Screen path="/child">
  *       <p>This is the child screen.</p>
- *       <NavigatorBackButton>
+ *       <Navigator.BackButton>
  *         Go back
- *       </NavigatorBackButton>
- *     </NavigatorScreen>
- *   </NavigatorProvider>
+ *       </Navigator.BackButton>
+ *     </Navigator.Screen>
+ *   </Navigator.Root>
  * );
  * ```
  */
 export const NavigatorProvider = contextConnect(
 	UnconnectedNavigatorProvider,
 	'NavigatorProvider'
 );
-
 export default NavigatorProvider;