Navigator: refactor to TypeScript (#35214)

packages/components/src/navigator/context.ts

@@ -0,0 +1,12 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { NavigatorContext as NavigatorContextType } from './types';
+
+const initialContextValue: NavigatorContextType = [ {}, () => {} ];
+export const NavigatorContext = createContext( initialContextValue );

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

@@ -60,8 +60,7 @@ The initial active path.
 
 -   Required: No
 
-
-## The navigator object
+## The `navigator` object
 
 You can retrieve a `navigator` instance by using the `useNavigator` hook.
 

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

@@ -0,0 +1,96 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { Ref } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import {
+	contextConnect,
+	useContextSystem,
+	WordPressComponentProps,
+} from '../../ui/context';
+import { View } from '../../view';
+import { NavigatorContext } from '../context';
+import type { NavigatorProviderProps, NavigatorPath } from '../types';
+
+function NavigatorProvider(
+	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
+	forwardedRef: Ref< any >
+) {
+	const { initialPath, children, ...otherProps } = useContextSystem(
+		props,
+		'NavigatorProvider'
+	);
+
+	const [ path, setPath ] = useState< NavigatorPath >( {
+		path: initialPath,
+	} );
+
+	return (
+		<View ref={ forwardedRef } { ...otherProps }>
+			<NavigatorContext.Provider value={ [ path, setPath ] }>
+				{ children }
+			</NavigatorContext.Provider>
+		</View>
+	);
+}
+
+/**
+ * The `NavigatorProvider` component allows rendering nested panels or menus (via the `NavigatorScreen` component) and navigate between these different states (via the `useNavigator` hook).
+ * The Global Styles sidebar is an example of this. 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.
+ *
+ * @example
+ * ```jsx
+ * import {
+ *   __experimentalNavigatorProvider as NavigatorProvider,
+ *   __experimentalNavigatorScreen as NavigatorScreen,
+ *   __experimentalUseNavigator as useNavigator,
+ * } from '@wordpress/components';
+ *
+ * function NavigatorButton( {
+ *   path,
+ *   isBack = false,
+ *   ...props
+ * } ) {
+ *   const navigator = useNavigator();
+ *   return (
+ *   	<Button
+ *   	  onClick={ () => navigator.push( path, { isBack } ) }
+ *   	  { ...props }
+ *   	/>
+ *   );
+ * }
+ *
+ * const MyNavigation = () => (
+ *   <NavigatorProvider initialPath="/">
+ *     <NavigatorScreen path="/">
+ *       <p>This is the home screen.</p>
+ *   	   <NavigatorButton isPrimary path="/child">
+ *          Navigate to child screen.
+ *       </NavigatorButton>
+ *     </NavigatorScreen>
+ *
+ *     <NavigatorScreen path="/child">
+ *       <p>This is the child screen.</p>
+ *       <NavigatorButton isPrimary path="/" isBack>
+ *         Go back
+ *       </NavigatorButton>
+ *     </NavigatorScreen>
+ *   </NavigatorProvider>
+ * );
+ * ```
+ */
+const ConnectedNavigatorProvider = contextConnect(
+	NavigatorProvider,
+	'NavigatorProvider'
+);
+
+export default ConnectedNavigatorProvider;

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

@@ -14,9 +14,8 @@ Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/
 
 The component accepts the following props:
 
-### `path`
+### `path`: `string`
 
--   Type: `string`
--   Required: Yes
+The screen's path, matched against the current path stored in the navigator.
 
-The path of the current screen.
+-   Required: Yes