@wordpress/components 19.4.0 → 19.5.0

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 );
@@ -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">

package/src/navigator/test/index.js

@@ -6,7 +6,12 @@ import { render, screen, fireEvent } from '@testing-library/react';
 /**
  * Internal dependencies
  */
-import { NavigatorProvider, NavigatorScreen, useNavigator } from '../';
+import {
+	NavigatorProvider,
+	NavigatorScreen,
+	NavigatorButton,
+	NavigatorBackButton,
+} from '../';
 
 jest.mock( 'framer-motion', () => {
 	const actual = jest.requireActual( 'framer-motion' );
@@ -23,57 +28,53 @@ jest.mock( 'framer-motion', () => {
 	};
 } );
 
+const INVALID_HTML_ATTRIBUTE = {
+	raw: ' "\'><=invalid_path',
+	escaped: " &quot;'&gt;<=invalid_path",
+};
+
 const PATHS = {
 	HOME: '/',
 	CHILD: '/child',
 	NESTED: '/child/nested',
+	INVALID_HTML_ATTRIBUTE: INVALID_HTML_ATTRIBUTE.raw,
 	NOT_FOUND: '/not-found',
 };
 
-function NavigatorButton( { path, onClick, ...props } ) {
-	const { goTo } = useNavigator();
+function CustomNavigatorButton( { path, onClick, ...props } ) {
 	return (
-		<button
+		<NavigatorButton
 			onClick={ () => {
-				goTo( path );
 				// Used to spy on the values passed to `navigator.goTo`
 				onClick?.( { type: 'goTo', path } );
 			} }
+			path={ path }
 			{ ...props }
 		/>
 	);
 }
 
-function NavigatorButtonWithFocusRestoration( { path, onClick, ...props } ) {
-	const { goTo } = useNavigator();
-	const dataAttrName = 'data-navigator-focusable-id';
-	const dataAttrValue = path;
-
-	const dataAttrCssSelector = `[${ dataAttrName }="${ dataAttrValue }"]`;
-
-	const buttonProps = {
-		...props,
-		[ dataAttrName ]: dataAttrValue,
-	};
-
+function CustomNavigatorButtonWithFocusRestoration( {
+	path,
+	onClick,
+	...props
+} ) {
 	return (
-		<button
+		<NavigatorButton
 			onClick={ () => {
-				goTo( path, { focusTargetSelector: dataAttrCssSelector } );
 				// Used to spy on the values passed to `navigator.goTo`
 				onClick?.( { type: 'goTo', path } );
 			} }
-			{ ...buttonProps }
+			path={ path }
+			{ ...props }
 		/>
 	);
 }
 
-function NavigatorBackButton( { onClick, ...props } ) {
-	const { goBack } = useNavigator();
+function CustomNavigatorBackButton( { onClick, ...props } ) {
 	return (
-		<button
+		<NavigatorBackButton
 			onClick={ () => {
-				goBack();
 				// Used to spy on the values passed to `navigator.goBack`
 				onClick?.( { type: 'goBack' } );
 			} }
@@ -89,38 +90,51 @@ const MyNavigation = ( {
 	<NavigatorProvider initialPath={ initialPath }>
 		<NavigatorScreen path={ PATHS.HOME }>
 			<p>This is the home screen.</p>
-			<NavigatorButton
+			<CustomNavigatorButton
 				path={ PATHS.NOT_FOUND }
 				onClick={ onNavigatorButtonClick }
 			>
 				Navigate to non-existing screen.
-			</NavigatorButton>
-			<NavigatorButtonWithFocusRestoration
+			</CustomNavigatorButton>
+			<CustomNavigatorButton
 				path={ PATHS.CHILD }
 				onClick={ onNavigatorButtonClick }
 			>
 				Navigate to child screen.
-			</NavigatorButtonWithFocusRestoration>
+			</CustomNavigatorButton>
+			<CustomNavigatorButton
+				path={ PATHS.INVALID_HTML_ATTRIBUTE }
+				onClick={ onNavigatorButtonClick }
+			>
+				Navigate to screen with an invalid HTML value as a path.
+			</CustomNavigatorButton>
 		</NavigatorScreen>
 
 		<NavigatorScreen path={ PATHS.CHILD }>
 			<p>This is the child screen.</p>
-			<NavigatorButtonWithFocusRestoration
+			<CustomNavigatorButtonWithFocusRestoration
 				path={ PATHS.NESTED }
 				onClick={ onNavigatorButtonClick }
 			>
 				Navigate to nested screen.
-			</NavigatorButtonWithFocusRestoration>
-			<NavigatorBackButton onClick={ onNavigatorButtonClick }>
+			</CustomNavigatorButtonWithFocusRestoration>
+			<CustomNavigatorBackButton onClick={ onNavigatorButtonClick }>
 				Go back
-			</NavigatorBackButton>
+			</CustomNavigatorBackButton>
 		</NavigatorScreen>
 
 		<NavigatorScreen path={ PATHS.NESTED }>
 			<p>This is the nested screen.</p>
-			<NavigatorBackButton onClick={ onNavigatorButtonClick }>
+			<CustomNavigatorBackButton onClick={ onNavigatorButtonClick }>
 				Go back
-			</NavigatorBackButton>
+			</CustomNavigatorBackButton>
+		</NavigatorScreen>
+
+		<NavigatorScreen path={ PATHS.INVALID_HTML_ATTRIBUTE }>
+			<p>This is the screen with an invalid HTML value as a path.</p>
+			<CustomNavigatorBackButton onClick={ onNavigatorButtonClick }>
+				Go back
+			</CustomNavigatorBackButton>
 		</NavigatorScreen>
 
 		{ /* A `NavigatorScreen` with `path={ PATHS.NOT_FOUND }` is purposefully not included */ }
@@ -143,6 +157,13 @@ const getNestedScreen = ( { throwIfNotFound } = {} ) =>
 	getNavigationScreenByText( 'This is the nested screen.', {
 		throwIfNotFound,
 	} );
+const getInvalidHTMLPathScreen = ( { throwIfNotFound } = {} ) =>
+	getNavigationScreenByText(
+		'This is the screen with an invalid HTML value as a path.',
+		{
+			throwIfNotFound,
+		}
+	);
 
 const getNavigationButtonByText = ( text, { throwIfNotFound = true } = {} ) => {
 	const fnName = throwIfNotFound ? 'getByRole' : 'queryByRole';
@@ -160,6 +181,13 @@ const getToNestedScreenButton = ( { throwIfNotFound } = {} ) =>
 	getNavigationButtonByText( 'Navigate to nested screen.', {
 		throwIfNotFound,
 	} );
+const getToInvalidHTMLPathScreenButton = ( { throwIfNotFound } = {} ) =>
+	getNavigationButtonByText(
+		'Navigate to screen with an invalid HTML value as a path.',
+		{
+			throwIfNotFound,
+		}
+	);
 const getBackButton = ( { throwIfNotFound } = {} ) =>
 	getNavigationButtonByText( 'Go back', {
 		throwIfNotFound,
@@ -350,4 +378,31 @@ describe( 'Navigator', () => {
 		expect( getHomeScreen() ).toBeInTheDocument();
 		expect( getToChildScreenButton() ).toHaveFocus();
 	} );
+
+	it( 'should escape the value of the `path` prop', () => {
+		render( <MyNavigation /> );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+		expect( getToInvalidHTMLPathScreenButton() ).toBeInTheDocument();
+
+		// The following line tests the implementation details, but it's necessary
+		// as this would be otherwise transparent to the user.
+		expect( getToInvalidHTMLPathScreenButton() ).toHaveAttribute(
+			'id',
+			INVALID_HTML_ATTRIBUTE.escaped
+		);
+
+		// Navigate to screen with an invalid HTML value for its `path`
+		fireEvent.click( getToInvalidHTMLPathScreenButton() );
+
+		expect( getInvalidHTMLPathScreen() ).toBeInTheDocument();
+		expect( getBackButton() ).toBeInTheDocument();
+
+		// Navigate back to home screen, check that the focus restoration selector
+		// worked correctly despite the escaping
+		fireEvent.click( getBackButton() );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+		expect( getToInvalidHTMLPathScreenButton() ).toHaveFocus();
+	} );
 } );

package/src/navigator/types.ts

@@ -43,3 +43,29 @@ export type NavigatorScreenProps = {
 	 */
 	children: ReactNode;
 };
+
+type ButtonProps = {
+	// TODO: should also extend `Button` prop types once the `Button` component
+	// is refactored to TypeScript.
+};
+export type NavigatorBackButtonProps = Omit< ButtonProps, 'href' > & {
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
+};
+
+export type NavigatorButtonProps = NavigatorBackButtonProps & {
+	/**
+	 * The path of the screen to navigate to. The value of this prop needs to be
+	 * a valid value for an HTML attribute.
+	 */
+	path: string;
+	/**
+	 * The HTML attribute used to identify the `NavigatorButton`, which is used
+	 * by `Navigator` to restore focus.
+	 *
+	 * @default 'id'
+	 */
+	attributeName?: string;
+};

package/src/number-control/stories/index.js

@@ -14,7 +14,7 @@ import { useState } from '@wordpress/element';
 import NumberControl from '../';
 
 export default {
-	title: 'Components/NumberControl',
+	title: 'Components (Experimental)/NumberControl',
 	component: NumberControl,
 	parameters: {
 		knobs: { disable: false },

package/src/radio/stories/index.js

@@ -4,7 +4,7 @@
 import RadioGroup from '../../radio-group';
 import Radio from '../';
 
-export default { title: 'Components/Radio', component: Radio };
+export default { title: 'Components (Experimental)/Radio', component: Radio };
 
 export const _default = () => {
 	// Radio components must be a descendent of a RadioGroup component.

package/src/radio-group/stories/index.js

@@ -9,7 +9,10 @@ import { useState } from '@wordpress/element';
 import Radio from '../../radio';
 import RadioGroup from '../';
 
-export default { title: 'Components/RadioGroup', component: RadioGroup };
+export default {
+	title: 'Components (Experimental)/RadioGroup',
+	component: RadioGroup,
+};
 
 export const _default = () => {
 	/* eslint-disable no-restricted-syntax */

package/src/resizable-box/index.tsx

@@ -9,7 +9,7 @@ import { forwardRef } from '@wordpress/element';
 import classnames from 'classnames';
 import { Resizable } from 're-resizable';
 import type { ResizableProps } from 're-resizable';
-import type { ReactNode, Ref } from 'react';
+import type { ReactNode, ForwardedRef } from 'react';
 
 /**
  * Internal dependencies
@@ -104,7 +104,7 @@ function ResizableBox(
 		__experimentalTooltipProps: tooltipProps = {},
 		...props
 	}: ResizableBoxProps,
-	ref: Ref< Resizable >
+	ref: ForwardedRef< Resizable >
 ): JSX.Element {
 	return (
 		<Resizable

package/src/resizable-box/resize-tooltip/index.tsx

@@ -3,7 +3,7 @@
  */
 import { noop } from 'lodash';
 import classnames from 'classnames';
-import type { Ref } from 'react';
+import type { Ref, ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -43,7 +43,7 @@ function ResizeTooltip(
 		zIndex = 1000,
 		...props
 	}: ResizeTooltipProps,
-	ref: Ref< HTMLDivElement >
+	ref: ForwardedRef< HTMLDivElement >
 ): JSX.Element | null {
 	const { label, resizeListener } = useResizeLabel( {
 		axis,

package/src/resizable-box/resize-tooltip/label.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -33,7 +33,7 @@ type LabelProps = React.DetailedHTMLProps<
 
 function Label(
 	{ label, position = POSITIONS.corner, zIndex = 1000, ...props }: LabelProps,
-	ref: Ref< HTMLDivElement >
+	ref: ForwardedRef< HTMLDivElement >
 ): JSX.Element | null {
 	const showLabel = !! label;
 

package/src/scrollable/component.js

@@ -7,7 +7,7 @@ import { useScrollable } from './hook';
 
 /**
  * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').Ref<any>}                                                        forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                               forwardedRef
  */
 function Scrollable( props, forwardedRef ) {
 	const scrollableProps = useScrollable( props );

package/src/select-control/index.tsx

@@ -3,8 +3,7 @@
  */
 import { isEmpty, noop } from 'lodash';
 import classNames from 'classnames';
-// eslint-disable-next-line no-restricted-imports
-import type { ChangeEvent, FocusEvent, ReactNode, Ref } from 'react';
+import type { ChangeEvent, FocusEvent, ReactNode, ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -74,7 +73,7 @@ function SelectControl(
 		suffix,
 		...props
 	}: WordPressComponentProps< SelectControlProps, 'select', false >,
-	ref: Ref< HTMLSelectElement >
+	ref: ForwardedRef< HTMLSelectElement >
 ) {
 	const [ isFocused, setIsFocused ] = useState( false );
 	const id = useUniqueId( idProp );

package/src/spacer/component.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Ref } from 'react';
+import type { ForwardedRef } from 'react';
 
 /**
  * Internal dependencies
@@ -13,7 +13,7 @@ import type { Props } from './types';
 
 function Spacer(
 	props: WordPressComponentProps< Props, 'div' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
 	const spacerProps = useSpacer( props );
 

package/src/surface/component.js

@@ -7,7 +7,7 @@ import { useSurface } from './hook';
 
 /**
  * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').Ref<any>}                                                        forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                               forwardedRef
  */
 function Surface( props, forwardedRef ) {
 	const surfaceProps = useSurface( props );

package/src/text/component.js

@@ -7,7 +7,7 @@ import useText from './hook';
 
 /**
  * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'span'>} props
- * @param {import('react').Ref<any>}                                                         forwardedRef
+ * @param {import('react').ForwardedRef<any>}                                                forwardedRef
  */
 function Text( props, forwardedRef ) {
 	const textProps = useText( props );

package/src/text-control/index.js

@@ -24,8 +24,8 @@ import BaseControl from '../base-control';
 
 /**
  *
- * @param {Props}                                 props Props
- * @param {import('react').Ref<HTMLInputElement>} [ref]
+ * @param {Props}                                          props Props
+ * @param {import('react').ForwardedRef<HTMLInputElement>} ref
  */
 function TextControl(
 	{

package/src/toggle-group-control/stories/index.js

@@ -17,7 +17,7 @@ import Button from '../../button';
 
 export default {
 	component: ToggleGroupControl,
-	title: 'Components/ToggleGroupControl',
+	title: 'Components (Experimental)/ToggleGroupControl',
 	parameters: {
 		knobs: { disable: false },
 	},

package/src/toggle-group-control/toggle-group-control/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 { RadioGroup, useRadioState } from 'reakit';
 
@@ -31,7 +31,7 @@ const noop = () => {};
 
 function ToggleGroupControl(
 	props: WordPressComponentProps< ToggleGroupControlProps, 'input' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
 	const {
 		className,

package/src/toggle-group-control/toggle-group-control-option/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 { Radio } from 'reakit';
 
@@ -39,7 +39,7 @@ const WithToolTip = ( { showTooltip, text, children }: WithToolTipProps ) => {
 
 function ToggleGroupControlOption(
 	props: WordPressComponentProps< ToggleGroupControlOptionProps, 'button' >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
 	const toggleGroupControlContext = useToggleGroupControlContext();
 	const id = useInstanceId(

package/src/tools-panel/stories/index.js

@@ -467,7 +467,6 @@ export const WithConditionallyRenderedControl = () => {
 	);
 };
 
-export { TypographyPanel } from './typography-panel';
 export { ToolsPanelWithItemGroupSlot } from './tools-panel-with-item-group-slot';
 
 const PanelWrapperView = styled.div`