@wordpress/components 28.8.3 → 28.9.0

package/src/navigator/README.md

@@ -0,0 +1,176 @@
+# `Navigator`
+
+`Navigator` is a collection components that allow rendering nested views/panels/menus (via the `Navigator.Screen` component) and navigate between them (via the `Navigator.Button` and `Navigator.BackButton` components).
+
+## Usage
+
+```jsx
+import { Navigator } from '@wordpress/components';
+
+const MyNavigation = () => (
+	<Navigator 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.BackButton>Go back</Navigator.BackButton>
+		</Navigator.Screen>
+	</Navigator>
+);
+```
+
+### 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`
+
+##### 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, 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`
+
+##### Props
+
+###### `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`
+
+##### Props
+
+###### `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.
+
+##### Props
+
+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' }`.

package/src/navigator/index.tsx

@@ -0,0 +1,131 @@
+/**
+ * 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 = () => (
+ *   <Navigator 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.BackButton>
+ *         Go back
+ *       </Navigator.BackButton>
+ *     </Navigator.Screen>
+ *   </Navigator>
+ * );
+ * ```
+ */
+export const Navigator = Object.assign( TopLevelNavigator, {
+	/**
+	 * The `Navigator.Screen` component represents a single view/screen/panel and
+	 * should be used in combination with the `Navigator`, the `Navigator.Button`
+	 * and the `Navigator.BackButton` components.
+	 *
+	 * @example
+	 * ```jsx
+	 * import { Navigator } from '@wordpress/components';
+	 *
+	 * const MyNavigation = () => (
+	 *   <Navigator 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.BackButton>
+	 *         Go back
+	 *       </Navigator.BackButton>
+	 *     </Navigator.Screen>
+	 *   </Navigator>
+	 * );
+	 * ```
+	 */
+	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 = () => (
+	 *   <Navigator 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.BackButton>
+	 *         Go back
+	 *       </Navigator.BackButton>
+	 *     </Navigator.Screen>
+	 *   </Navigator>
+	 * );
+	 * ```
+	 */
+	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 = () => (
+	 *   <Navigator 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.BackButton>
+	 *         Go back
+	 *       </Navigator.BackButton>
+	 *     </Navigator.Screen>
+	 *   </Navigator>
+	 * );
+	 * ```
+	 */
+	BackButton: Object.assign( NavigatorBackButton, {
+		displayName: 'Navigator.BackButton',
+	} ),
+} );

package/src/navigator/legacy.ts

@@ -0,0 +1,169 @@
+/**
+ * Internal dependencies
+ */
+import { Navigator as InternalNavigator } from './navigator/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 them
+ * (via the `NavigatorButton` and `NavigatorBackButton` components).
+ *
+ * ```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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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',
+	}
+);

package/src/navigator/{navigator-provider → navigator}/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 {
@@ -222,7 +222,7 @@ function UnconnectedNavigatorProvider(
 		children,
 		className,
 		...otherProps
-	} = useContextSystem( props, 'NavigatorProvider' );
+	} = useContextSystem( props, 'Navigator' );
 
 	const [ routerState, dispatch ] = useReducer(
 		routerReducer,
@@ -275,7 +275,7 @@ function UnconnectedNavigatorProvider(
 
 	const cx = useCx();
 	const classes = useMemo(
-		() => cx( styles.navigatorProviderWrapper, className ),
+		() => cx( styles.navigatorWrapper, className ),
 		[ className, cx ]
 	);
 
@@ -288,42 +288,4 @@ function UnconnectedNavigatorProvider(
 	);
 }
 
-/**
- * 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 = contextConnect(
-	UnconnectedNavigatorProvider,
-	'NavigatorProvider'
-);
-
-export default NavigatorProvider;
+export const Navigator = contextConnect( UnconnectedNavigator, 'Navigator' );

package/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'
+	'Navigator.BackButton'
 );
-
-export default NavigatorBackButton;

package/src/navigator/navigator-back-button/hook.ts

@@ -20,7 +20,7 @@ export function useNavigatorBackButton(
 		as = Button,
 
 		...otherProps
-	} = useContextSystem( props, 'NavigatorBackButton' );
+	} = useContextSystem( props, 'Navigator.BackButton' );
 
 	const { goBack } = useNavigator();
 	const handleClick: React.MouseEventHandler< HTMLButtonElement > =

package/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'
+	'Navigator.Button'
 );
-
-export default NavigatorButton;

package/src/navigator/navigator-button/hook.ts

@@ -25,7 +25,7 @@ export function useNavigatorButton(
 		as = Button,
 		attributeName = 'id',
 		...otherProps
-	} = useContextSystem( props, 'NavigatorButton' );
+	} = useContextSystem( props, 'Navigator.Button' );
 
 	const escapedPath = escapeAttribute( path );