@wordpress/components 19.4.1-next.f435e9e01b.0 → 19.6.0

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

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

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

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

package/src/navigator/navigator-provider/README.md

@@ -4,47 +4,34 @@
 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 panels or menus (via the [`NavigatorScreen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the `useNavigator` hook). The Global Styles sidebar is an example of this.
+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) 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,
-	__experimentalUseNavigator as useNavigator,
+  __experimentalNavigatorProvider as NavigatorProvider,
+  __experimentalNavigatorScreen as NavigatorScreen,
+  __experimentalNavigatorButton as NavigatorButton,
+  __experimentalNavigatorBackButton as NavigatorBackButton,
 } from '@wordpress/components';
 
-function NavigatorButton( { path, ...props } ) {
-	const { goTo } = useNavigator();
-	return (
-		<Button
-		 variant="primary"
-		 onClick={ () => goTo( path ) }
-		 { ...props }
-	 />
- );
-}
-
-function NavigatorBackButton( props ) {
-	const { goBack } = useNavigator();
-	return <Button variant="secondary" onClick={ () => goBack() } { ...props } />;
-}
-
 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>
+  <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>
 );
 ```
 

package/src/navigator/navigator-provider/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 import { css } from '@emotion/react';
 
 /**
@@ -28,7 +28,7 @@ import type {
 
 function NavigatorProvider(
 	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
 	const {
 		initialPath,
@@ -85,7 +85,7 @@ function NavigatorProvider(
 
 	const cx = useCx();
 	const classes = useMemo(
-		// Prevents horizontal overflow while animating screen transitions
+		// Prevents horizontal overflow while animating screen transitions.
 		() => cx( css( { overflowX: 'hidden' } ), className ),
 		[ className, cx ]
 	);
@@ -100,44 +100,34 @@ function NavigatorProvider(
 }
 
 /**
- * The `NavigatorProvider` component allows rendering nested panels or menus (via the `NavigatorScreen` component) and navigate between these different states (via the `useNavigator` hook).
+ * 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).
  *
  * @example
  * ```jsx
  * import {
  *   __experimentalNavigatorProvider as NavigatorProvider,
  *   __experimentalNavigatorScreen as NavigatorScreen,
- *   __experimentalUseNavigator as useNavigator,
+ *   __experimentalNavigatorButton as NavigatorButton,
+ *   __experimentalNavigatorBackButton as NavigatorBackButton,
  * } from '@wordpress/components';
  *
- * function NavigatorButton( { path, ...props } ) {
- *  const { goTo } = useNavigator();
- *  return (
- *    <Button
- *      variant="primary"
- *      onClick={ () => goTo( path ) }
- *      { ...props }
- *    />
- *  );
- * }
- *
- * function NavigatorBackButton( props ) {
- *   const { goBack } = useNavigator();
- *   return <Button variant="secondary" onClick={ () => goBack() } { ...props } />;
- * }
- *
  * const MyNavigation = () => (
  *   <NavigatorProvider initialPath="/">
  *     <NavigatorScreen path="/">
  *       <p>This is the home screen.</p>
- *   	   <NavigatorButton path="/child">
+ *        <NavigatorButton path="/child">
  *          Navigate to child screen.
  *       </NavigatorButton>
  *     </NavigatorScreen>
  *
  *     <NavigatorScreen path="/child">
  *       <p>This is the child screen.</p>
- *       <NavigatorBackButton>Go back</NavigatorBackButton>
+ *       <NavigatorBackButton>
+ *         Go back
+ *       </NavigatorBackButton>
  *     </NavigatorScreen>
  *   </NavigatorProvider>
  * );

package/src/navigator/navigator-screen/README.md

@@ -4,7 +4,7 @@
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>
 
-The `NavigatorScreen` component represents a single view/screen/panel/menu and is supposed to be used in combination with [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md).
+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
 

package/src/navigator/navigator-screen/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 // eslint-disable-next-line no-restricted-imports
 import { motion, MotionProps } from 'framer-motion';
 import { css } from '@emotion/react';
@@ -17,6 +17,7 @@ import {
 	usePrevious,
 } from '@wordpress/compose';
 import { isRTL } from '@wordpress/i18n';
+import { escapeAttribute } from '@wordpress/escape-html';
 
 /**
  * Internal dependencies
@@ -43,7 +44,7 @@ type Props = Omit<
 	keyof MotionProps
 >;
 
-function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
+function NavigatorScreen( props: Props, forwardedRef: ForwardedRef< any > ) {
 	const { children, className, path, ...otherProps } = useContextSystem(
 		props,
 		'NavigatorScreen'
@@ -51,7 +52,7 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 
 	const prefersReducedMotion = useReducedMotion();
 	const { location } = useContext( NavigatorContext );
-	const isMatch = location.path === path;
+	const isMatch = location.path === escapeAttribute( path );
 	const wrapperRef = useRef< HTMLDivElement >( null );
 
 	const previousLocation = usePrevious( location );
@@ -61,9 +62,9 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 		() =>
 			cx(
 				css( {
-					// Ensures horizontal overflow is visually accessible
+					// Ensures horizontal overflow is visually accessible.
 					overflowX: 'auto',
-					// In case the root has a height, it should not be exceeded
+					// In case the root has a height, it should not be exceeded.
 					maxHeight: '100%',
 				} ),
 				className
@@ -171,44 +172,34 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 }
 
 /**
- * The `NavigatorScreen` component represents a single view/screen/panel/menu and is supposed to be used in combination with the `NavigatorProvider` component.
+ * The `NavigatorScreen` component represents a single view/screen/panel and
+ * should be used in combination with the `NavigatorProvider`, the
+ * `NavigatorButton` and the `NavigatorBackButton` components (or the `useNavigator`
+ * hook).
  *
  * @example
  * ```jsx
  * import {
  *   __experimentalNavigatorProvider as NavigatorProvider,
  *   __experimentalNavigatorScreen as NavigatorScreen,
- *   __experimentalUseNavigator as useNavigator,
+ *   __experimentalNavigatorButton as NavigatorButton,
+ *   __experimentalNavigatorBackButton as NavigatorBackButton,
  * } from '@wordpress/components';
  *
- * function NavigatorButton( { path, ...props } ) {
- *  const { goTo } = useNavigator();
- *  return (
- *    <Button
- *      variant="primary"
- *      onClick={ () => goTo( path ) }
- *      { ...props }
- *    />
- *  );
- * }
- *
- * function NavigatorBackButton( props ) {
- *   const { goBack } = useNavigator();
- *   return <Button variant="secondary" onClick={ () => goBack() } { ...props } />;
- * }
- *
  * const MyNavigation = () => (
  *   <NavigatorProvider initialPath="/">
  *     <NavigatorScreen path="/">
  *       <p>This is the home screen.</p>
- *   	   <NavigatorButton path="/child">
+ *        <NavigatorButton path="/child">
  *          Navigate to child screen.
  *       </NavigatorButton>
  *     </NavigatorScreen>
  *
  *     <NavigatorScreen path="/child">
  *       <p>This is the child screen.</p>
- *       <NavigatorBackButton>Go back</NavigatorBackButton>
+ *       <NavigatorBackButton>
+ *         Go back
+ *       </NavigatorBackButton>
  *     </NavigatorScreen>
  *   </NavigatorProvider>
  * );

package/src/navigator/stories/index.js

@@ -11,43 +11,18 @@ import { Card, CardBody, CardFooter, CardHeader } from '../../card';
 import { HStack } from '../../h-stack';
 import { Flyout } from '../../flyout';
 import { useCx } from '../../utils/hooks/use-cx';
-import { NavigatorProvider, NavigatorScreen, useNavigator } from '../';
+import {
+	NavigatorProvider,
+	NavigatorScreen,
+	NavigatorButton,
+	NavigatorBackButton,
+} from '../';
 
 export default {
 	title: 'Components (Experimental)/Navigator',
 	component: NavigatorProvider,
 };
 
-function NavigatorButton( { path, ...props } ) {
-	const { goTo } = useNavigator();
-	const dataAttrName = 'data-navigator-focusable-id';
-	const dataAttrValue = path;
-
-	const dataAttrCssSelector = `[${ dataAttrName }="${ dataAttrValue }"]`;
-
-	const buttonProps = {
-		...props,
-		[ dataAttrName ]: dataAttrValue,
-	};
-
-	return (
-		<Button
-			variant="secondary"
-			onClick={ () =>
-				goTo( path, { focusTargetSelector: dataAttrCssSelector } )
-			}
-			{ ...buttonProps }
-		/>
-	);
-}
-
-function NavigatorBackButton( props ) {
-	const { goBack } = useNavigator();
-	return (
-		<Button variant="secondary" onClick={ () => goBack() } { ...props } />
-	);
-}
-
 const MyNavigation = () => {
 	const cx = useCx();
 	return (
@@ -61,15 +36,21 @@ const MyNavigation = () => {
 						<p>This is the home screen.</p>
 
 						<HStack justify="flex-start" wrap>
-							<NavigatorButton path="/child">
+							<NavigatorButton variant="secondary" path="/child">
 								Navigate to child screen.
 							</NavigatorButton>
 
-							<NavigatorButton path="/overflow-child">
+							<NavigatorButton
+								variant="secondary"
+								path="/overflow-child"
+							>
 								Navigate to screen with horizontal overflow.
 							</NavigatorButton>
 
-							<NavigatorButton path="/stickies">
+							<NavigatorButton
+								variant="secondary"
+								path="/stickies"
+							>
 								Navigate to screen with sticky content.
 							</NavigatorButton>
 
@@ -93,7 +74,9 @@ const MyNavigation = () => {
 				<Card>
 					<CardBody>
 						<p>This is the child screen.</p>
-						<NavigatorBackButton>Go back</NavigatorBackButton>
+						<NavigatorBackButton variant="secondary">
+							Go back
+						</NavigatorBackButton>
 					</CardBody>
 				</Card>
 			</NavigatorScreen>
@@ -101,7 +84,9 @@ const MyNavigation = () => {
 			<NavigatorScreen path="/overflow-child">
 				<Card>
 					<CardBody>
-						<NavigatorBackButton>Go back</NavigatorBackButton>
+						<NavigatorBackButton variant="secondary">
+							Go back
+						</NavigatorBackButton>
 						<div
 							className={ cx(
 								css( `
@@ -129,7 +114,9 @@ const MyNavigation = () => {
 			<NavigatorScreen path="/stickies">
 				<Card>
 					<Sticky as={ CardHeader } z="2">
-						<NavigatorBackButton>Go back</NavigatorBackButton>
+						<NavigatorBackButton variant="secondary">
+							Go back
+						</NavigatorBackButton>
 					</Sticky>
 					<CardBody>
 						<Sticky top="69px" colors="papayawhip/peachpuff">