@wordpress/components 19.12.0 → 19.13.0

package/src/navigation/test/index.js

@@ -1,7 +1,13 @@
 /**
  * External dependencies
  */
-import { render, screen, fireEvent } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -10,7 +16,7 @@ import Navigation from '..';
 import NavigationItem from '../item';
 import NavigationMenu from '../menu';
 
-const testNavigation = ( { activeItem, rootTitle, showBadge } = {} ) => (
+const TestNavigation = ( { activeItem, rootTitle, showBadge } = {} ) => (
 	<Navigation activeItem={ activeItem }>
 		<NavigationMenu title={ rootTitle }>
 			<NavigationItem
@@ -45,92 +51,286 @@ const testNavigation = ( { activeItem, rootTitle, showBadge } = {} ) => (
 	</Navigation>
 );
 
+const TestNavigationControlled = () => {
+	const [ activeItem, setActiveItem ] = useState( 'item-1' );
+	const [ activeMenu, setActiveMenu ] = useState( 'root' );
+
+	const onMockLinkClick = ( event ) => {
+		event.preventDefault();
+		const item = event.target.href.replace( 'https://example.com/', '' );
+		setActiveItem( item );
+	};
+
+	return (
+		<>
+			<Navigation
+				activeItem={ activeItem }
+				activeMenu={ activeMenu }
+				className="navigation-story"
+				onActivateMenu={ setActiveMenu }
+			>
+				<NavigationMenu title="Home">
+					<NavigationItem
+						item="item-1"
+						title="Item 1"
+						href="https://example.com/item-1"
+						onClick={ onMockLinkClick }
+					/>
+					<NavigationItem
+						item="item-2"
+						title="Item 2"
+						href="https://example.com/item-2"
+						onClick={ onMockLinkClick }
+					/>
+					<NavigationItem
+						item="item-sub-menu"
+						navigateToMenu="sub-menu"
+						title="Sub-Menu"
+					/>
+				</NavigationMenu>
+				<NavigationMenu
+					menu="sub-menu"
+					parentMenu="root"
+					title="Sub-Menu"
+				>
+					<NavigationItem
+						item="child-1"
+						onClick={ () => setActiveItem( 'child-1' ) }
+						title="Child 1"
+					/>
+					<NavigationItem
+						item="child-2"
+						onClick={ () => setActiveItem( 'child-2' ) }
+						title="Child 2"
+					/>
+					<NavigationItem
+						item="child-nested-sub-menu"
+						navigateToMenu="nested-sub-menu"
+						title="Nested Sub-Menu"
+					/>
+				</NavigationMenu>
+				<NavigationMenu
+					menu="nested-sub-menu"
+					parentMenu="sub-menu"
+					title="Nested Sub-Menu"
+				>
+					<NavigationItem
+						item="sub-child-1"
+						onClick={ () => setActiveItem( 'sub-child-1' ) }
+						title="Sub-Child 1"
+					/>
+					<NavigationItem
+						item="sub-child-2"
+						onClick={ () => setActiveItem( 'sub-child-2' ) }
+						title="Sub-Child 2"
+					/>
+				</NavigationMenu>
+			</Navigation>
+
+			<div className="navigation-story__aside">
+				<p>
+					Menu <code>{ activeMenu }</code> is active.
+					<br />
+					Item <code>{ activeItem }</code> is active.
+				</p>
+				<p>
+					<button
+						onClick={ () => {
+							setActiveMenu( 'nested-sub-menu' );
+						} }
+					>
+						Open the Nested Sub-Menu menu
+					</button>
+				</p>
+				<p>
+					<button
+						onClick={ () => {
+							setActiveItem( 'child-2' );
+							setActiveMenu( 'sub-menu' );
+						} }
+					>
+						Navigate to Child 2 item
+					</button>
+				</p>
+			</div>
+		</>
+	);
+};
+
 describe( 'Navigation', () => {
 	it( 'should render the panes and active item', async () => {
-		render( testNavigation( { activeItem: 'item-2' } ) );
+		render( <TestNavigation activeItem="item-2" /> );
 
 		const menuItems = screen.getAllByRole( 'listitem' );
 
-		expect( menuItems.length ).toBe( 4 );
-		expect( menuItems[ 0 ].textContent ).toBe( 'Item 1' );
-		expect( menuItems[ 1 ].textContent ).toBe( 'Item 2' );
-		expect( menuItems[ 2 ].textContent ).toBe( 'Category' );
-		expect( menuItems[ 3 ].textContent ).toBe( 'customize me' );
-		expect( menuItems[ 0 ].classList.contains( 'is-active' ) ).toBe(
-			false
-		);
-		expect( menuItems[ 1 ].classList.contains( 'is-active' ) ).toBe( true );
+		expect( menuItems ).toHaveLength( 4 );
+		expect( menuItems[ 0 ] ).toHaveTextContent( 'Item 1' );
+		expect( menuItems[ 1 ] ).toHaveTextContent( 'Item 2' );
+		expect( menuItems[ 2 ] ).toHaveTextContent( 'Category' );
+		expect( menuItems[ 3 ] ).toHaveTextContent( 'customize me' );
+
+		expect(
+			screen.getByRole( 'link', { current: 'page' } )
+		).toHaveTextContent( 'Item 2' );
 	} );
 
-	it( 'should render anchor links when menu item supplies an href', async () => {
-		render( testNavigation() );
+	it( 'should render anchor links when menu item supplies an href', () => {
+		render( <TestNavigation /> );
 
 		const linkItem = screen.getByRole( 'link', { name: 'Item 2' } );
 
-		expect( linkItem ).toBeDefined();
-		expect( linkItem.target ).toBe( '_blank' );
+		expect( linkItem ).toBeInTheDocument();
+		expect( linkItem ).toHaveAttribute( 'target', '_blank' );
 	} );
 
-	it( 'should render a custom component when menu item supplies one', async () => {
-		render( testNavigation() );
+	it( 'should render a custom component when menu item supplies one', () => {
+		render( <TestNavigation /> );
 
-		const customItem = screen.getByText( 'customize me' );
-
-		expect( customItem ).toBeDefined();
+		expect( screen.getByText( 'customize me' ) ).toBeInTheDocument();
 	} );
 
 	it( 'should set an active category on click', async () => {
-		render( testNavigation() );
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
 
-		fireEvent.click( screen.getByRole( 'button', { name: 'Category' } ) );
-		const categoryTitle = screen.getByRole( 'heading' );
-		const menuItems = screen.getAllByRole( 'listitem' );
+		render( <TestNavigation /> );
+
+		await user.click( screen.getByRole( 'button', { name: 'Category' } ) );
 
-		expect( categoryTitle.textContent ).toBe( 'Category' );
-		expect( menuItems.length ).toBe( 2 );
-		expect( menuItems[ 0 ].textContent ).toBe( 'Child 1' );
-		expect( menuItems[ 1 ].textContent ).toBe( 'Child 2' );
+		expect( screen.getByRole( 'heading' ) ).toHaveTextContent( 'Category' );
+		const menuItems = screen.getAllByRole( 'listitem' );
+		expect( menuItems ).toHaveLength( 2 );
+		expect( menuItems[ 0 ] ).toHaveTextContent( 'Child 1' );
+		expect( menuItems[ 1 ] ).toHaveTextContent( 'Child 2' );
 	} );
 
-	it( 'should render the root title', async () => {
-		const { rerender } = render( testNavigation() );
+	it( 'should render the root title', () => {
+		const { rerender } = render( <TestNavigation /> );
 
-		const emptyTitle = screen.queryByRole( 'heading' );
-		expect( emptyTitle ).toBeNull();
+		expect( screen.queryByRole( 'heading' ) ).not.toBeInTheDocument();
 
-		rerender( testNavigation( { rootTitle: 'Home' } ) );
+		rerender( <TestNavigation rootTitle="Home" /> );
 
-		const rootTitle = screen.getByRole( 'heading' );
-		expect( rootTitle.textContent ).toBe( 'Home' );
+		expect( screen.getByRole( 'heading' ) ).toBeInTheDocument();
+		expect( screen.getByRole( 'heading' ) ).toHaveTextContent( 'Home' );
 	} );
 
-	it( 'should render badges', async () => {
-		render( testNavigation( { showBadge: true } ) );
+	it( 'should render badges', () => {
+		render( <TestNavigation showBadge /> );
 
 		const menuItem = screen.getAllByRole( 'listitem' );
 		expect( menuItem[ 0 ].textContent ).toBe( 'Item 1' + '21' );
 	} );
 
-	it( 'should render menu titles when items exist', async () => {
+	it( 'should render menu titles when items exist', () => {
 		const { rerender } = render( <Navigation></Navigation> );
 
-		const emptyMenu = screen.queryByText( 'Menu title' );
-		expect( emptyMenu ).toBeNull();
+		expect( screen.queryByText( 'Menu title' ) ).not.toBeInTheDocument();
 
-		rerender( testNavigation( { rootTitle: 'Menu title' } ) );
+		rerender( <TestNavigation rootTitle="Menu title" /> );
 
-		const menuTitle = screen.queryByText( 'Menu title' );
-		expect( menuTitle ).not.toBeNull();
+		expect( screen.getByText( 'Menu title' ) ).toBeInTheDocument();
 	} );
 
 	it( 'should navigate up a level when clicking the back button', async () => {
-		render( testNavigation( { rootTitle: 'Home' } ) );
-
-		fireEvent.click( screen.getByRole( 'button', { name: 'Category' } ) );
-		let menuTitle = screen.getByRole( 'heading' );
-		expect( menuTitle.textContent ).toBe( 'Category' );
-		fireEvent.click( screen.getByRole( 'button', { name: 'Home' } ) );
-		menuTitle = screen.getByRole( 'heading' );
-		expect( menuTitle.textContent ).toBe( 'Home' );
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
+
+		render( <TestNavigation rootTitle="Home" /> );
+
+		await user.click( screen.getByRole( 'button', { name: 'Category' } ) );
+
+		expect( screen.getByRole( 'heading' ) ).toHaveTextContent( 'Category' );
+
+		await user.click( screen.getByRole( 'button', { name: 'Home' } ) );
+
+		expect( screen.getByRole( 'heading' ) ).toHaveTextContent( 'Home' );
+	} );
+
+	it( 'should navigate correctly when controlled', async () => {
+		const user = userEvent.setup( {
+			advanceTimers: jest.advanceTimersByTime,
+		} );
+
+		render( <TestNavigationControlled /> );
+
+		// check root menu is shown and item 1 is selected
+		expect(
+			screen.getByRole( 'heading', { name: 'Home' } )
+		).toBeInTheDocument();
+		expect(
+			screen.getByRole( 'link', { current: 'page' } )
+		).toHaveTextContent( 'Item 1' );
+
+		// click Item 2, check it's selected
+		await user.click( screen.getByRole( 'link', { name: 'Item 2' } ) );
+		expect(
+			screen.getByRole( 'link', { current: 'page' } )
+		).toHaveTextContent( 'Item 2' );
+
+		// click sub-menu, check new menu is shown
+		await user.click( screen.getByRole( 'button', { name: 'Sub-Menu' } ) );
+		expect(
+			screen.getByRole( 'heading', { name: 'Sub-Menu' } )
+		).toBeInTheDocument();
+
+		// click Child 1, check it's selected
+		await user.click( screen.getByRole( 'button', { name: 'Child 1' } ) );
+		expect(
+			screen.getByRole( 'button', { current: 'page' } )
+		).toHaveTextContent( 'Child 1' );
+
+		// click nested sub-menu, check nested sub-menu is shown
+		await user.click(
+			screen.getByRole( 'button', { name: 'Nested Sub-Menu' } )
+		);
+		expect(
+			screen.getByRole( 'heading', { name: 'Nested Sub-Menu' } )
+		).toBeInTheDocument();
+
+		// click Sub Child 2, check it's selected
+		await user.click(
+			screen.getByRole( 'button', { name: 'Sub-Child 2' } )
+		);
+		expect(
+			screen.getByRole( 'button', { current: 'page' } )
+		).toHaveTextContent( 'Sub-Child 2' );
+
+		// click back, check sub-menu is shown
+		await user.click( screen.getByRole( 'button', { name: 'Sub-Menu' } ) );
+		expect(
+			screen.getByRole( 'heading', { name: 'Sub-Menu' } )
+		).toBeInTheDocument();
+
+		// click back, check root menu is shown
+		await user.click( screen.getByRole( 'button', { name: 'Home' } ) );
+		expect(
+			screen.getByRole( 'heading', { name: 'Home' } )
+		).toBeInTheDocument();
+
+		// click the programmatic nested sub-menu button, check nested sub menu is shown
+		await user.click(
+			screen.getByRole( 'button', {
+				name: 'Open the Nested Sub-Menu menu',
+			} )
+		);
+		expect(
+			screen.getByRole( 'heading', { name: 'Nested Sub-Menu' } )
+		).toBeInTheDocument();
+
+		// click navigate to child2 item button, check the correct menu is shown and the item is selected
+		await user.click(
+			screen.getByRole( 'button', {
+				name: 'Navigate to Child 2 item',
+			} )
+		);
+		expect(
+			screen.getByRole( 'heading', { name: 'Sub-Menu' } )
+		).toBeInTheDocument();
+		expect(
+			screen.getByRole( 'button', { current: 'page' } )
+		).toHaveTextContent( 'Child 2' );
 	} );
 } );

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

@@ -17,20 +17,22 @@ import type { NavigatorBackButtonProps } from '../types';
 export function useNavigatorBackButton(
 	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >
 ) {
-	const { onClick, as = Button, ...otherProps } = useContextSystem(
-		props,
-		'NavigatorBackButton'
-	);
+	const {
+		onClick,
+		as = Button,
+		...otherProps
+	} = useContextSystem( props, 'NavigatorBackButton' );
 
 	const { goBack } = useNavigator();
-	const handleClick: React.MouseEventHandler< HTMLButtonElement > = useCallback(
-		( e ) => {
-			e.preventDefault();
-			goBack();
-			onClick?.( e );
-		},
-		[ goBack, onClick ]
-	);
+	const handleClick: React.MouseEventHandler< HTMLButtonElement > =
+		useCallback(
+			( e ) => {
+				e.preventDefault();
+				goBack();
+				onClick?.( e );
+			},
+			[ goBack, onClick ]
+		);
 
 	return {
 		as,

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

@@ -32,19 +32,20 @@ export function useNavigatorButton(
 	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 ]
-	);
+	const handleClick: React.MouseEventHandler< HTMLButtonElement > =
+		useCallback(
+			( e ) => {
+				e.preventDefault();
+				goTo( escapedPath, {
+					focusTargetSelector: cssSelectorForAttribute(
+						attributeName,
+						escapedPath
+					),
+				} );
+				onClick?.( e );
+			},
+			[ goTo, onClick ]
+		);
 
 	return {
 		as,

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

@@ -30,12 +30,8 @@ function NavigatorProvider(
 	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) {
-	const {
-		initialPath,
-		children,
-		className,
-		...otherProps
-	} = useContextSystem( props, 'NavigatorProvider' );
+	const { initialPath, children, className, ...otherProps } =
+		useContextSystem( props, 'NavigatorProvider' );
 
 	const [ locationHistory, setLocationHistory ] = useState<
 		NavigatorLocation[]

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

@@ -96,9 +96,9 @@ function NavigatorScreen( props: Props, forwardedRef: ForwardedRef< any > ) {
 		// If the previous query didn't run or find any element to focus, fallback
 		// to the first tabbable element in the screen (or the screen itself).
 		if ( ! elementToFocus ) {
-			const firstTabbable = ( focus.tabbable.find(
-				wrapperRef.current
-			) as HTMLElement[] )[ 0 ];
+			const firstTabbable = (
+				focus.tabbable.find( wrapperRef.current ) as HTMLElement[]
+			 )[ 0 ];
 
 			elementToFocus = firstTabbable ?? wrapperRef.current;
 		}

package/src/notice/index.js

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { noop } from 'lodash';
 import classnames from 'classnames';
 
 /**
@@ -19,6 +18,8 @@ import { Button } from '../';
 
 /** @typedef {import('@wordpress/element').WPElement} WPElement */
 
+const noop = () => {};
+
 /**
  * Custom hook which announces the message with the given politeness, if a
  * valid message is provided.

package/src/notice/list.js

@@ -2,13 +2,15 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { noop, omit } from 'lodash';
+import { omit } from 'lodash';
 
 /**
  * Internal dependencies
  */
 import Notice from './';
 
+const noop = () => {};
+
 /**
  * Renders a list of notices.
  *

package/src/panel/body.js

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { noop } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -18,6 +17,8 @@ import Button from '../button';
 import Icon from '../icon';
 import { useControlledState, useUpdateEffect } from '../utils';
 
+const noop = () => {};
+
 export function PanelBody(
 	{
 		buttonProps = {},

package/src/placeholder/README.md

@@ -11,9 +11,10 @@ const MyPlaceholder = () => <Placeholder icon={ more } label="Placeholder" />;
 
 ### Props
 
-| Name             | Type                | Default     | Description                                                       |
-| ---------------- | ------------------- | ----------- | ----------------------------------------------------------------- |
-| `icon`           | `string, WPElement` | `undefined` | If provided, renders an icon next to the label.                   |
-| `label`          | `string`            | `undefined` | Renders a label for the placeholder.                              |
-| `instructions`   | `string`            | `undefined` | Renders instruction text below label.                             |
-| `isColumnLayout` | `bool`              | `false`     | Changes placeholder children layout from flex-row to flex-column. |
+| Name              | Type                | Default     | Description                                                       |
+| ----------------  | ------------------- | ----------- | ----------------------------------------------------------------- |
+| `icon`            | `string, WPElement` | `undefined` | If provided, renders an icon next to the label.                   |
+| `label`           | `string`            | `undefined` | Renders a label for the placeholder.                              |
+| `instructions`    | `string`            | `undefined` | Renders instruction text below label.                             |
+| `isColumnLayout`  | `bool`              | `false`     | Changes placeholder children layout from flex-row to flex-column. |
+| `withIllustration`| `bool`              | `false`     | Outputs a placeholder illustration.                             |

package/src/placeholder/index.js

@@ -7,24 +7,38 @@ import classnames from 'classnames';
  * WordPress dependencies
  */
 import { useResizeObserver } from '@wordpress/compose';
+import { SVG, Path } from '@wordpress/primitives';
 
 /**
  * Internal dependencies
  */
 import Icon from '../icon';
 
+const PlaceholderIllustration = (
+	<SVG
+		className="components-placeholder__illustration"
+		fill="none"
+		xmlns="http://www.w3.org/2000/svg"
+		viewBox="0 0 60 60"
+		preserveAspectRatio="none"
+	>
+		<Path vectorEffect="non-scaling-stroke" d="M60 60 0 0" />
+	</SVG>
+);
+
 /**
  * Renders a placeholder. Normally used by blocks to render their empty state.
  *
- * @param {Object}    props                The component props.
- * @param {WPIcon}    props.icon           An icon rendered before the label.
- * @param {WPElement} props.children       Children to be rendered.
- * @param {string}    props.label          Title of the placeholder.
- * @param {string}    props.instructions   Instructions of the placeholder.
- * @param {string}    props.className      Class to set on the container div.
- * @param {Object}    props.notices        A rendered notices list.
- * @param {Object}    props.preview        Preview to be rendered in the placeholder.
- * @param {boolean}   props.isColumnLayout Whether a column layout should be used.
+ * @param {Object}    props                  The component props.
+ * @param {WPIcon}    props.icon             An icon rendered before the label.
+ * @param {WPElement} props.children         Children to be rendered.
+ * @param {string}    props.label            Title of the placeholder.
+ * @param {string}    props.instructions     Instructions of the placeholder.
+ * @param {string}    props.className        Class to set on the container div.
+ * @param {Object}    props.notices          A rendered notices list.
+ * @param {Object}    props.preview          Preview to be rendered in the placeholder.
+ * @param {boolean}   props.isColumnLayout   Whether a column layout should be used.
+ * @param {boolean}   props.withIllustration Whether to add an illustration to the placeholder.
  *
  * @return {Object} The rendered placeholder.
  */
@@ -37,6 +51,7 @@ function Placeholder( {
 	notices,
 	preview,
 	isColumnLayout,
+	withIllustration,
 	...additionalProps
 } ) {
 	const [ resizeListener, { width } ] = useResizeObserver();
@@ -55,13 +70,15 @@ function Placeholder( {
 	const classes = classnames(
 		'components-placeholder',
 		className,
-		modifierClassNames
+		modifierClassNames,
+		withIllustration ? 'has-illustration' : null
 	);
 	const fieldsetClasses = classnames( 'components-placeholder__fieldset', {
 		'is-column-layout': isColumnLayout,
 	} );
 	return (
 		<div { ...additionalProps } className={ classes }>
+			{ withIllustration ? PlaceholderIllustration : null }
 			{ resizeListener }
 			{ notices }
 			{ preview && (

package/src/placeholder/style.scss

@@ -30,6 +30,13 @@
 	.components-base-control__label {
 		font-size: $default-font-size;
 	}
+
+	&.has-illustration {
+		background: none;
+		border: none;
+		box-shadow: none;
+		min-width: 100px;
+	}
 }
 
 .components-placeholder__error,
@@ -171,3 +178,19 @@
 		}
 	}
 }
+
+// Style the placeholder illustration.
+.components-placeholder__illustration {
+	border: $border-width dashed currentColor;
+	box-sizing: border-box;
+	position: absolute;
+	top: 0;
+	right: 0;
+	bottom: 0;
+	left: 0;
+	width: 100%;
+	height: 100%;
+	stroke: currentColor;
+	stroke-dasharray: 3;
+	opacity: 0.4;
+}