Navigator: add basic history support, enable advanced focus restoration

docs/manifest.json

@@ -1043,6 +1043,18 @@
 		"markdown_source": "../packages/components/src/navigation/README.md",
 		"parent": "components"
 	},
+	{
+		"title": "NavigatorBackLink",
+		"slug": "navigator-back-link",
+		"markdown_source": "../packages/components/src/navigator/navigator-back-link/README.md",
+		"parent": "components"
+	},
+	{
+		"title": "NavigatorLink",
+		"slug": "navigator-link",
+		"markdown_source": "../packages/components/src/navigator/navigator-link/README.md",
+		"parent": "components"
+	},
 	{
 		"title": "NavigatorProvider",
 		"slug": "navigator-provider",

packages/components/src/index.js

@@ -100,6 +100,8 @@ export { default as __experimentalNavigationMenu } from './navigation/menu';
 export {
 	NavigatorProvider as __experimentalNavigatorProvider,
 	NavigatorScreen as __experimentalNavigatorScreen,
+	NavigatorLink as __experimentalNavigatorLink,
+	NavigatorBackLink as __experimentalNavigatorBackLink,
 	useNavigator as __experimentalUseNavigator,
 } from './navigator';
 export { default as Notice } from './notice';

packages/components/src/navigator/context.ts

@@ -8,5 +8,9 @@ import { createContext } from '@wordpress/element';
  */
 import type { NavigatorContext as NavigatorContextType } from './types';
 
-const initialContextValue: NavigatorContextType = [ {}, () => {} ];
+const initialContextValue: NavigatorContextType = {
+	location: {},
+	push: () => {},
+	pop: () => {},
+};
 export const NavigatorContext = createContext( initialContextValue );

packages/components/src/navigator/index.ts

@@ -1,3 +1,5 @@
 export { default as NavigatorProvider } from './navigator-provider';
 export { default as NavigatorScreen } from './navigator-screen';
+export { default as NavigatorLink } from './navigator-link';
+export { default as NavigatorBackLink } from './navigator-back-link';
 export { default as useNavigator } from './use-navigator';

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

@@ -0,0 +1,19 @@
+# `NavigatorBackLink`
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+**TODO**
+
+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
+
+**TODO**
+
+## Props
+
+The component accepts the following props:
+
+**TODO**

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

@@ -0,0 +1,32 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { Ref } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { View } from '../../view';
+import { useNavigatorBackLink } from './hook';
+import type { NavigatorBackLinkProps } from '../types';
+
+function NavigatorBackLink(
+	props: WordPressComponentProps< NavigatorBackLinkProps, 'button' >,
+	forwardedRef: Ref< any >
+) {
+	const navigatorBackLinkProps = useNavigatorBackLink( props );
+
+	return <View ref={ forwardedRef } { ...navigatorBackLinkProps } />;
+}
+
+/**
+ * TODO: add example
+ */
+const ConnectedNavigatorBackLink = contextConnect(
+	NavigatorBackLink,
+	'NavigatorBackLink'
+);
+
+export default ConnectedNavigatorBackLink;

packages/components/src/navigator/navigator-back-link/hook.ts

@@ -0,0 +1,37 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
+import Button from '../../button';
+import useNavigator from '../use-navigator';
+import type { NavigatorBackLinkProps } from '../types';
+
+export function useNavigatorBackLink(
+	props: WordPressComponentProps< NavigatorBackLinkProps, 'button' >
+) {
+	const { onClick, as = Button, ...otherProps } = useContextSystem(
+		props,
+		'NavigatorBackLink'
+	);
+
+	const { pop } = useNavigator();
+	const handleClick: React.MouseEventHandler< HTMLElement > = useCallback(
+		( e ) => {
+			e.preventDefault();
+			pop();
+			onClick?.( e );
+		},
+		[ pop, onClick ]
+	);
+
+	return {
+		as,
+		onClick: handleClick,
+		...otherProps,
+	};
+}

packages/components/src/navigator/navigator-back-link/index.ts

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

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

@@ -0,0 +1,19 @@
+# `NavigatorLink`
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+**TODO**
+
+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
+
+**TODO**
+
+## Props
+
+The component accepts the following props:
+
+**TODO**

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

@@ -0,0 +1,29 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { Ref } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import { contextConnect, WordPressComponentProps } from '../../ui/context';
+import { View } from '../../view';
+import { useNavigatorLink } from './hook';
+import type { NavigatorLinkProps } from '../types';
+
+function NavigatorLink(
+	props: WordPressComponentProps< NavigatorLinkProps, 'button' >,
+	forwardedRef: Ref< any >
+) {
+	const navigatorLinkProps = useNavigatorLink( props );
+
+	return <View ref={ forwardedRef } { ...navigatorLinkProps } />;
+}
+
+/**
+ * TODO: add example
+ */
+const ConnectedNavigatorLink = contextConnect( NavigatorLink, 'NavigatorLink' );
+
+export default ConnectedNavigatorLink;

packages/components/src/navigator/navigator-link/hook.ts

@@ -0,0 +1,50 @@
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { useContextSystem, WordPressComponentProps } from '../../ui/context';
+import Button from '../../button';
+import useNavigator from '../use-navigator';
+import type { NavigatorLinkProps } from '../types';
+
+const cssSelectorForAttribute = ( attrName: string, attrValue: string ) =>
+	`[${ attrName }="${ attrValue }"]`;
+
+export function useNavigatorLink(
+	props: WordPressComponentProps< NavigatorLinkProps, 'button' >
+) {
+	const {
+		path,
+		onClick,
+		as = Button,
+		attributeName = 'id',
+		...otherProps
+	} = useContextSystem( props, 'NavigatorLink' );
+
+	const { push } = useNavigator();
+	const handleClick: React.MouseEventHandler< HTMLElement > = useCallback(
+		( e ) => {
+			e.preventDefault();
+			push( path, {
+				focusTargetSelector: cssSelectorForAttribute(
+					attributeName,
+					path
+				),
+			} );
+			onClick?.( e );
+		},
+		[ push, onClick ]
+	);
+
+	return {
+		as,
+		onClick: handleClick,
+		path,
+		...otherProps,
+		[ attributeName ]: path,
+	};
+}

packages/components/src/navigator/navigator-link/index.ts

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

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

@@ -8,7 +8,7 @@ import { css } from '@emotion/react';
 /**
  * WordPress dependencies
  */
-import { useMemo, useState } from '@wordpress/element';
+import { useMemo, useState, useCallback } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -21,7 +21,11 @@ import {
 import { useCx } from '../../utils/hooks/use-cx';
 import { View } from '../../view';
 import { NavigatorContext } from '../context';
-import type { NavigatorProviderProps, NavigatorPath } from '../types';
+import type {
+	NavigatorProviderProps,
+	NavigatorLocation,
+	NavigatorContext as NavigatorContextType,
+} from '../types';
 
 function NavigatorProvider(
 	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
@@ -34,9 +38,59 @@ function NavigatorProvider(
 		...otherProps
 	} = useContextSystem( props, 'NavigatorProvider' );
 
-	const [ path, setPath ] = useState< NavigatorPath >( {
-		path: initialPath,
-	} );
+	const [ locationHistory, setLocationHistory ] = useState<
+		NavigatorLocation[]
+	>( [
+		{
+			path: initialPath,
+			isBack: false,
+			isInitial: true,
+		},
+	] );
+
+	const push: NavigatorContextType[ 'push' ] = useCallback(
+		( path, options ) => {
+			const { focusTargetSelector, ...restOptions } = options;
+
+			// The `focusTargetSelector` needs to be applied on the current
+			// location, while the remaining options need to be applied on the
+			// incoming location
+			setLocationHistory( [
+				...locationHistory.slice( 0, -1 ),
+				{
+					...locationHistory[ locationHistory.length - 1 ],
+					isBack: false,
+					focusTargetSelector,
+				},
+				{
+					...restOptions,
+					path,
+					isBack: false,
+					isInitial: false,
+				},
+			] );
+		},
+		[ locationHistory ]
+	);
+
+	const pop: NavigatorContextType[ 'pop' ] = useCallback( () => {
+		if ( locationHistory.length > 1 ) {
+			setLocationHistory( [
+				...locationHistory.slice( 0, -2 ),
+				// Force the `isBack` flag to `true` when navigating back.
+				{
+					...locationHistory[ locationHistory.length - 2 ],
+					isBack: true,
+				},
+			] );
+		}
+	}, [ locationHistory ] );
+
+	const navigatorContextValue: NavigatorContextType = {
+		location: locationHistory[ locationHistory.length - 1 ],
+		push,
+		pop,
+	};
 
 	const cx = useCx();
 	const classes = useMemo(
@@ -47,7 +101,7 @@ function NavigatorProvider(
 
 	return (
 		<View ref={ forwardedRef } className={ classes } { ...otherProps }>
-			<NavigatorContext.Provider value={ [ path, setPath ] }>
+			<NavigatorContext.Provider value={ navigatorContextValue }>
 				{ children }
 			</NavigatorContext.Provider>
 		</View>