- Go back
-
-
-);
-```
-
-### Hierarchical `path`s
-
-`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.
-
-### Height and animations
-
-Due to how `Navigator.Screen` animations work, it is recommended that the `Navigator` component is assigned a `height` to prevent some potential UI jumps while moving across screens.
-
-### Individual components
-
-`Navigator` is comprised of four individual components:
-
-- `Navigator`: a wrapper component and context provider. It holds the main logic for hiding and showing screens.
-- `Navigator.Screen`: represents a single view/screen/panel;
-- `Navigator.Button`: renders a button that allows navigating to a different `Navigator.Screen`;
-- `Navigator.BackButton`: renders a button that allows navigating to the parent `Navigator.Screen` (see the section above about hierarchical paths).
-
-For advanced usages, consumers can use the `useNavigator` hook.
-
-#### `Navigator`
-
-##### Props
-
-###### `initialPath`: `string`
-
-The initial active path.
-
-- Required: Yes
-
-###### `children`: `string`
-
-The children elements.
-
-- Required: Yes
-
-#### `Navigator.Screen`
-
-###### `path`: `string`
-
-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` with value `/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.
-
-- Required: Yes
-
-###### `children`: `string`
-
-The children elements.
-
-- Required: Yes
-
-##### `Navigator.Button`
-
-###### `path`: `string`
-
-The path of the screen to navigate to. The value of this prop needs to be [a valid value for an HTML attribute](https://html.spec.whatwg.org/multipage/syntax.html#attributes-2).
-
-- Required: Yes
-
-###### `attributeName`: `string`
-
-The HTML attribute used to identify the `Navigator.Button`, which is used by `Navigator` to restore focus.
-
-- Required: No
-- Default: `id`
-
-###### `children`: `string`
-
-The children elements.
-
-- Required: No
-
-###### Inherited props
-
-`Navigator.Button` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.
-
-##### `Navigator.BackButton`
-
-###### `children`: `string`
-
-The children elements.
-
-- Required: No
-
-###### Inherited props
-
-`Navigator.BackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.
-
-###### `useNavigator`
-
-You can retrieve a `navigator` instance by using the `useNavigator` hook.
-
-The `navigator` instance has a few properties:
-
-###### `goTo`: `( path: string, options: NavigateOptions ) => void`
-
-The `goTo` function allows navigating to a given path. The second argument can augment the navigation operations with different options.
-
-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);
-- `skipFocus`: `boolean`. An optional property used to opt out of `Navigator`'s focus management, useful when the consumer of the component wants to manage focus themselves;
-
-###### `goBack`: `( path: string, options: NavigateOptions ) => void`
-
-The `goBack` function allows navigating to the parent screen. Parent/child navigation only works if the paths you define are hierarchical (see note above).
-
-When a match is not found, the function will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) is found.
-
-The available options are the same as for the `goTo` method, except for the `isBack` property, which is not available for the `goBack` method.
-
-###### `location`: `NavigatorLocation`
-
-The `location` object represents 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.
-- `isInitial`: `boolean`. A flag that is `true` only for the initial location.
-
-###### `params`: `Record< string, string | string[] >`
-
-The parsed record of parameters from the current location. For example if the current screen path is `/product/:productId` and the location is `/product/123`, then `params` will be `{ productId: '123' }`.
diff --git a/packages/components/src/navigator/index.tsx b/packages/components/src/navigator/index.tsx
deleted file mode 100644
index 1d9ae95441e01..0000000000000
--- a/packages/components/src/navigator/index.tsx
+++ /dev/null
@@ -1,131 +0,0 @@
-/**
- * Internal dependencies
- */
-import { Navigator as TopLevelNavigator } from './navigator/component';
-import { NavigatorScreen } from './navigator-screen/component';
-import { NavigatorButton } from './navigator-button/component';
-import { NavigatorBackButton } from './navigator-back-button/component';
-export { useNavigator } from './use-navigator';
-
-/**
- * The `Navigator` component allows rendering nested views/panels/menus
- * (via the `Navigator.Screen` component) and navigate between them
- * (via the `Navigator.Button` and `Navigator.BackButton` components).
- *
- * ```jsx
- * import { Navigator } from '@wordpress/components';
- *
- * const MyNavigation = () => (
- *
- *
- *
- *
- * Go back
- *
- *
- *
- * );
- * ```
- */
- Screen: Object.assign( NavigatorScreen, {
- displayName: 'Navigator.Screen',
- } ),
- /**
- * The `Navigator.Button` component can be used to navigate to a screen and
- * should be used in combination with the `Navigator`, the `Navigator.Screen`
- * and the `Navigator.BackButton` components.
- *
- * @example
- * ```jsx
- * import { Navigator } from '@wordpress/components';
- *
- * const MyNavigation = () => (
- *
- *
- *
- *
- * Go back
- *
- *
- *
- * );
- * ```
- */
- Button: Object.assign( NavigatorButton, {
- displayName: 'Navigator.Button',
- } ),
- /**
- * The `Navigator.BackButton` component can be used to navigate to a screen and
- * should be used in combination with the `Navigator`, the `Navigator.Screen`
- * and the `Navigator.Button` components.
- *
- * @example
- * ```jsx
- * import { Navigator } from '@wordpress/components';
- *
- * const MyNavigation = () => (
- *
- *
- *
- *
- * Go back
- *
- *
- *
- * );
- * ```
- */
- BackButton: Object.assign( NavigatorBackButton, {
- displayName: 'Navigator.BackButton',
- } ),
-} );
diff --git a/packages/components/src/navigator/legacy.ts b/packages/components/src/navigator/legacy.ts
index 1caa5380fc049..54bc9e13829b1 100644
--- a/packages/components/src/navigator/legacy.ts
+++ b/packages/components/src/navigator/legacy.ts
@@ -1,7 +1,7 @@
/**
* Internal dependencies
*/
-import { Navigator as InternalNavigator } from './navigator/component';
+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';
@@ -10,8 +10,9 @@ export { useNavigator } from './use-navigator';
/**
* The `NavigatorProvider` component allows rendering nested views/panels/menus
- * (via the `NavigatorScreen` component and navigate between them
- * (via the `NavigatorButton` and `NavigatorBackButton` components).
+ * (via the `NavigatorScreen` component and navigate between these different
+ * view (via the `NavigatorButton` and `NavigatorBackButton` components or the
+ * `useNavigator` hook).
*
* ```jsx
* import {
@@ -47,7 +48,8 @@ export const NavigatorProvider = Object.assign( InternalNavigator, {
/**
* The `NavigatorScreen` component represents a single view/screen/panel and
* should be used in combination with the `NavigatorProvider`, the
- * `NavigatorButton` and the `NavigatorBackButton` components.
+ * `NavigatorButton` and the `NavigatorBackButton` components (or the `useNavigator`
+ * hook).
*
* @example
* ```jsx
@@ -84,7 +86,7 @@ export const NavigatorScreen = Object.assign( InternalNavigatorScreen, {
/**
* 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.
+ * and the `NavigatorBackButton` components (or the `useNavigator` hook).
*
* @example
* ```jsx
@@ -121,7 +123,8 @@ export const NavigatorButton = Object.assign( InternalNavigatorButton, {
/**
* 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.
+ * `NavigatorScreen` and the `NavigatorButton` components (or the `useNavigator`
+ * hook).
*
* @example
* ```jsx
diff --git a/packages/components/src/navigator/navigator-back-button/README.md b/packages/components/src/navigator/navigator-back-button/README.md
new file mode 100644
index 0000000000000..01d4221be536e
--- /dev/null
+++ b/packages/components/src/navigator/navigator-back-button/README.md
@@ -0,0 +1,15 @@
+# `NavigatorBackButton`
+
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
+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).
+
+## 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`.
diff --git a/packages/components/src/navigator/navigator-back-button/component.tsx b/packages/components/src/navigator/navigator-back-button/component.tsx
index b5c4de7df78a8..9e8d98a963d25 100644
--- a/packages/components/src/navigator/navigator-back-button/component.tsx
+++ b/packages/components/src/navigator/navigator-back-button/component.tsx
@@ -23,5 +23,5 @@ function UnconnectedNavigatorBackButton(
export const NavigatorBackButton = contextConnect(
UnconnectedNavigatorBackButton,
- 'Navigator.BackButton'
+ 'NavigatorBackButton'
);
diff --git a/packages/components/src/navigator/navigator-back-button/hook.ts b/packages/components/src/navigator/navigator-back-button/hook.ts
index d6fcd39647bff..9ddc095292190 100644
--- a/packages/components/src/navigator/navigator-back-button/hook.ts
+++ b/packages/components/src/navigator/navigator-back-button/hook.ts
@@ -20,7 +20,7 @@ export function useNavigatorBackButton(
as = Button,
...otherProps
- } = useContextSystem( props, 'Navigator.BackButton' );
+ } = useContextSystem( props, 'NavigatorBackButton' );
const { goBack } = useNavigator();
const handleClick: React.MouseEventHandler< HTMLButtonElement > =
diff --git a/packages/components/src/navigator/navigator-button/README.md b/packages/components/src/navigator/navigator-button/README.md
new file mode 100644
index 0000000000000..72154ec317da4
--- /dev/null
+++ b/packages/components/src/navigator/navigator-button/README.md
@@ -0,0 +1,38 @@
+# `NavigatorButton`
+
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
+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).
+
+## 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:
+
+### `attributeName`: `string`
+
+The HTML attribute used to identify the `NavigatorButton`, which is used by `Navigator` to restore focus.
+
+- Required: No
+- Default: `id`
+
+### `onClick`: `React.MouseEventHandler< HTMLElement >`
+
+The callback called in response to a `click` event.
+
+- Required: No
+
+### `path`: `string`
+
+The path of the screen to navigate to. The value of this prop needs to be [a valid value for an HTML attribute](https://html.spec.whatwg.org/multipage/syntax.html#attributes-2).
+
+- Required: Yes
+
+### Inherited props
+
+`NavigatorButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.
diff --git a/packages/components/src/navigator/navigator-button/component.tsx b/packages/components/src/navigator/navigator-button/component.tsx
index a6dc796337672..7c14c8108e82c 100644
--- a/packages/components/src/navigator/navigator-button/component.tsx
+++ b/packages/components/src/navigator/navigator-button/component.tsx
@@ -23,5 +23,5 @@ function UnconnectedNavigatorButton(
export const NavigatorButton = contextConnect(
UnconnectedNavigatorButton,
- 'Navigator.Button'
+ 'NavigatorButton'
);
diff --git a/packages/components/src/navigator/navigator-button/hook.ts b/packages/components/src/navigator/navigator-button/hook.ts
index 59d2aaa65662d..3e39b05661e1b 100644
--- a/packages/components/src/navigator/navigator-button/hook.ts
+++ b/packages/components/src/navigator/navigator-button/hook.ts
@@ -25,7 +25,7 @@ export function useNavigatorButton(
as = Button,
attributeName = 'id',
...otherProps
- } = useContextSystem( props, 'Navigator.Button' );
+ } = useContextSystem( props, 'NavigatorButton' );
const escapedPath = escapeAttribute( path );
diff --git a/packages/components/src/navigator/navigator-provider/README.md b/packages/components/src/navigator/navigator-provider/README.md
new file mode 100644
index 0000000000000..b9bc8f0c6bcdc
--- /dev/null
+++ b/packages/components/src/navigator/navigator-provider/README.md
@@ -0,0 +1,98 @@
+# `NavigatorProvider`
+
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
+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.
+
+## Usage
+
+```jsx
+import {
+ __experimentalNavigatorProvider as NavigatorProvider,
+ __experimentalNavigatorScreen as NavigatorScreen,
+ __experimentalNavigatorButton as NavigatorButton,
+ __experimentalNavigatorBackButton as NavigatorBackButton,
+} from '@wordpress/components';
+
+const MyNavigation = () => (
+
+
+
This is the home screen.
+
+ Navigate to child screen.
+
+
+
+
+
This is the child screen.
+ Go back
+
+
+);
+```
+
+### Hierarchical `path`s
+
+`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 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` with value `/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.
+
+### Height and animations
+
+Due to how `NavigatorScreen` animations work, it is recommended that the `NavigatorProvider` component is assigned a `height` to prevent some potential UI jumps while moving across screens.
+
+## Props
+
+The component accepts the following props:
+
+### `initialPath`: `string`
+
+The initial active path.
+
+- Required: No
+
+## The `navigator` object
+
+You can retrieve a `navigator` instance by using the `useNavigator` hook.
+
+The `navigator` instance has a few properties:
+
+### `goTo`: `( path: string, options: NavigateOptions ) => void`
+
+The `goTo` function allows navigating to a given path. The second argument can augment the navigation operations with different options.
+
+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);
+- `skipFocus`: `boolean`. An optional property used to opt out of `Navigator`'s focus management, useful when the consumer of the component wants to manage focus themselves;
+
+### `goBack`: `( path: string, options: NavigateOptions ) => void`
+
+The `goBack` function allows navigating to the parent screen. Parent/child navigation only works if the paths you define are hierarchical (see note above).
+
+When a match is not found, the function will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) are found.
+
+The available options are the same as for the `goTo` method, except for the `isBack` property, which is not available for the `goBack` method.
+
+### `location`: `NavigatorLocation`
+
+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.
+- `isInitial`: `boolean`. A flag that is `true` only for the initial location.
+
+### `params`: `Record< string, string | string[] >`
+
+The parsed record of parameters from the current location. For example if the current screen path is `/product/:productId` and the location is `/product/123`, then `params` will be `{ productId: '123' }`.
diff --git a/packages/components/src/navigator/navigator/component.tsx b/packages/components/src/navigator/navigator-provider/component.tsx
similarity index 84%
rename from packages/components/src/navigator/navigator/component.tsx
rename to packages/components/src/navigator/navigator-provider/component.tsx
index bd49b3682fb14..604034a952557 100644
--- a/packages/components/src/navigator/navigator/component.tsx
+++ b/packages/components/src/navigator/navigator-provider/component.tsx
@@ -222,7 +222,7 @@ function UnconnectedNavigator(
children,
className,
...otherProps
- } = useContextSystem( props, 'Navigator' );
+ } = useContextSystem( props, 'NavigatorProvider' );
const [ routerState, dispatch ] = useReducer(
routerReducer,
@@ -275,7 +275,7 @@ function UnconnectedNavigator(
const cx = useCx();
const classes = useMemo(
- () => cx( styles.navigatorWrapper, className ),
+ () => cx( styles.navigatorProviderWrapper, className ),
[ className, cx ]
);
@@ -288,4 +288,42 @@ function UnconnectedNavigator(
);
}
-export const Navigator = contextConnect( UnconnectedNavigator, '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 = () => (
+ *
+ *
+ *
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
+The `NavigatorScreen` component represents a single view/screen/panel and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) and the [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-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.
+
+## Props
+
+The component accepts the following props:
+
+### `path`: `string`
+
+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 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` with value `/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.
+
+- Required: Yes
diff --git a/packages/components/src/navigator/navigator-screen/component.tsx b/packages/components/src/navigator/navigator-screen/component.tsx
index fe0d81b90a17b..16cc0df24e35d 100644
--- a/packages/components/src/navigator/navigator-screen/component.tsx
+++ b/packages/components/src/navigator/navigator-screen/component.tsx
@@ -36,7 +36,7 @@ function UnconnectedNavigatorScreen(
) {
if ( ! /^\//.test( props.path ) ) {
warning(
- 'wp.components.Navigator.Screen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.'
+ 'wp.components.NavigatorScreen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.'
);
}
@@ -48,7 +48,7 @@ function UnconnectedNavigatorScreen(
path,
onAnimationEnd: onAnimationEndProp,
...otherProps
- } = useContextSystem( props, 'Navigator.Screen' );
+ } = useContextSystem( props, 'NavigatorScreen' );
const { location, match, addScreen, removeScreen } =
useContext( NavigatorContext );
@@ -155,5 +155,5 @@ function UnconnectedNavigatorScreen(
export const NavigatorScreen = contextConnect(
UnconnectedNavigatorScreen,
- 'Navigator.Screen'
+ 'NavigatorScreen'
);
diff --git a/packages/components/src/navigator/navigator-to-parent-button/README.md b/packages/components/src/navigator/navigator-to-parent-button/README.md
new file mode 100644
index 0000000000000..0100ea9b8d2e1
--- /dev/null
+++ b/packages/components/src/navigator/navigator-to-parent-button/README.md
@@ -0,0 +1,17 @@
+# `NavigatorToParentButton`
+
+
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+
+
+This component is deprecated. Please use the [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) component instead.
+
+The `NavigatorToParentButton` 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).
+
+## Usage
+
+Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example.
+
+### Inherited props
+
+`NavigatorToParentButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.
diff --git a/packages/components/src/navigator/navigator-to-parent-button/component.tsx b/packages/components/src/navigator/navigator-to-parent-button/component.tsx
index f1c2d27e2284a..161370a4323f4 100644
--- a/packages/components/src/navigator/navigator-to-parent-button/component.tsx
+++ b/packages/components/src/navigator/navigator-to-parent-button/component.tsx
@@ -17,16 +17,13 @@ function UnconnectedNavigatorToParentButton(
) {
deprecated( 'wp.components.NavigatorToParentButton', {
since: '6.7',
- alternative: 'wp.components.Navigator.BackButton',
+ alternative: 'wp.components.NavigatorBackButton',
} );
return ;
}
-/**
- * @deprecated
- */
export const NavigatorToParentButton = contextConnect(
UnconnectedNavigatorToParentButton,
- 'Navigator.ToParentButton'
+ 'NavigatorToParentButton'
);
diff --git a/packages/components/src/navigator/stories/index.story.tsx b/packages/components/src/navigator/stories/index.story.tsx
index e9e342bb0d2ee..f703969320ca5 100644
--- a/packages/components/src/navigator/stories/index.story.tsx
+++ b/packages/components/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 '../legacy';
import { HStack } from '../../h-stack';
-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',
+
+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',
argTypes: {
as: { control: { type: null } },
children: { control: { type: null } },
@@ -40,10 +40,10 @@ const meta: Meta< typeof Navigator > = {
* detail of the Navigator component. Do not use outside of
* its source code.
*/
- [data-wp-component="Navigator"] {
+ [data-wp-component="NavigatorProvider"] {
height: 250px;
}
- [data-wp-component="Navigator.Screen"] {
+ [data-wp-component="NavigatorScreen"]:not([data-sticky]) {
padding: 8px;
}
` }
@@ -55,55 +55,55 @@ const meta: Meta< typeof Navigator > = {
};
export default meta;
-export const Default: StoryObj< typeof Navigator > = {
+export const Default: StoryObj< typeof NavigatorProvider > = {
args: {
initialPath: '/',
children: (
<>
-
+
This is the home screen.
-
+
Go to child screen.
-
+
-
+
Go to dynamic path screen with id 1.
-
+
-
+
Go to dynamic path screen with id 2.
-
+
-
+
-
+
This is the child screen.
-
+
Go back
-
+
-
Go to grand child screen.
-
+
-
+
-
+
{ /*
* A button useful to test focus restoration. This button is the first
@@ -254,9 +254,9 @@ const MyNavigation = ( {
>
{ BUTTON_TEXT.toInvalidHtmlPathScreen }
-
+
-
+
{ SCREEN_TEXT.child }
{ /*
* A button useful to test focus restoration. This button is the first
@@ -286,30 +286,30 @@ const MyNavigation = ( {
} }
value={ innerInputValue }
/>
-
+
-
+
{ SCREEN_TEXT.nested }
{ BUTTON_TEXT.back }
-
+
-
+
{ SCREEN_TEXT.invalidHtmlPath }
{ BUTTON_TEXT.back }
-
+
- { /* A `Navigator.Screen` with `path={ PATHS.NOT_FOUND }` is purposefully not included. */ }
-
+ { /* A `NavigatorScreen` with `path={ PATHS.NOT_FOUND }` is purposefully not included. */ }
+
{
return (
<>
-
-
+
+
{ SCREEN_TEXT.home }
{ /*
* A button useful to test focus restoration. This button is the first
@@ -349,9 +349,9 @@ const MyHierarchicalNavigation = ( {
>
{ BUTTON_TEXT.toChildScreen }
-
+
-
+
{ SCREEN_TEXT.child }
{ /*
* A button useful to test focus restoration. This button is the first
@@ -370,9 +370,9 @@ const MyHierarchicalNavigation = ( {
>
{ BUTTON_TEXT.back }
-
+
-
+
{ /*
* A button useful to test focus restoration. This button is the first
@@ -421,9 +421,9 @@ const MyDeprecatedNavigation = ( {
>
{ BUTTON_TEXT.toChildScreen }
-
+
-
+
{ SCREEN_TEXT.child }
{ /*
* A button useful to test focus restoration. This button is the first
@@ -442,17 +442,17 @@ const MyDeprecatedNavigation = ( {
>
{ BUTTON_TEXT.back }
-
+
-
+
{ SCREEN_TEXT.nested }
{ BUTTON_TEXT.back }
-
-
+
+
);
};
@@ -643,10 +643,10 @@ describe( 'Navigator', () => {
} );
it( 'should warn if the `path` prop does not follow the required format', () => {
- render( Test );
+ render( Test );
expect( console ).toHaveWarnedWith(
- 'wp.components.Navigator.Screen: the `path` should follow a URL-like scheme; it should start with and be separated by the `/` character.'
+ 'wp.components.NavigatorScreen: 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.Navigator.BackButton instead.'
+ 'wp.components.NavigatorToParentButton is deprecated since version 6.7. Please use wp.components.NavigatorBackButton instead.'
);
} );
diff --git a/packages/components/src/navigator/types.ts b/packages/components/src/navigator/types.ts
index aeb5fd3b12c7f..ad26d3f1c9f49 100644
--- a/packages/components/src/navigator/types.ts
+++ b/packages/components/src/navigator/types.ts
@@ -100,24 +100,6 @@ export type NavigatorProps = {
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;
/**
diff --git a/packages/components/src/navigator/use-navigator.ts b/packages/components/src/navigator/use-navigator.ts
index 1ea99f3f1c857..7ac35d73150d3 100644
--- a/packages/components/src/navigator/use-navigator.ts
+++ b/packages/components/src/navigator/use-navigator.ts
@@ -10,10 +10,7 @@ import { NavigatorContext } from './context';
import type { Navigator } from './types';
/**
- * Retrieves a `navigator` instance. This hook provides advanced functionality,
- * such as imperatively navigating to a new location (with options like
- * navigating back or skipping focus restoration) and accessing the current
- * location and path parameters.
+ * Retrieves a `navigator` instance.
*/
export function useNavigator(): Navigator {
const { location, params, goTo, goBack, goToParent } =
diff --git a/storybook/manager-head.html b/storybook/manager-head.html
index 8525e48fffa58..f3eaef1350921 100644
--- a/storybook/manager-head.html
+++ b/storybook/manager-head.html
@@ -7,7 +7,6 @@
'customselectcontrol-v2',
'dimensioncontrol',
'navigation',
- 'navigator',
'progressbar',
'theme',
];