@wordpress/components 19.3.0 → 19.4.1

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

@@ -42,37 +42,25 @@ function NavigatorProvider(
 	>( [
 		{
 			path: initialPath,
-			isBack: false,
-			isInitial: true,
 		},
 	] );
 
-	const push: NavigatorContextType[ 'push' ] = useCallback(
-		( path, options ) => {
-			// Force the `isBack` flag to `false` when navigating forward on both the
-			// previous and the new location.
-			// Also force the `isInitial` flag to `false` for the new location, to make
-			// sure it doesn't get overridden by mistake.
+	const goTo: NavigatorContextType[ 'goTo' ] = useCallback(
+		( path, options = {} ) => {
 			setLocationHistory( [
-				...locationHistory.slice( 0, -1 ),
-				{
-					...locationHistory[ locationHistory.length - 1 ],
-					isBack: false,
-				},
+				...locationHistory,
 				{
 					...options,
 					path,
 					isBack: false,
-					isInitial: false,
 				},
 			] );
 		},
 		[ locationHistory ]
 	);
 
-	const pop: NavigatorContextType[ 'pop' ] = useCallback( () => {
+	const goBack: NavigatorContextType[ 'goBack' ] = useCallback( () => {
 		if ( locationHistory.length > 1 ) {
-			// Force the `isBack` flag to `true` when navigating back.
 			setLocationHistory( [
 				...locationHistory.slice( 0, -2 ),
 				{
@@ -85,18 +73,21 @@ function NavigatorProvider(
 
 	const navigatorContextValue: NavigatorContextType = useMemo(
 		() => ( {
-			location: locationHistory[ locationHistory.length - 1 ],
-			push,
-			pop,
+			location: {
+				...locationHistory[ locationHistory.length - 1 ],
+				isInitial: locationHistory.length === 1,
+			},
+			goTo,
+			goBack,
 		} ),
-		[ locationHistory, push, pop ]
+		[ locationHistory, goTo, goBack ]
 	);
 
 	const cx = useCx();
 	const classes = useMemo(
 		// Prevents horizontal overflow while animating screen transitions
 		() => cx( css( { overflowX: 'hidden' } ), className ),
-		[ className ]
+		[ className, cx ]
 	);
 
 	return (
@@ -120,19 +111,19 @@ function NavigatorProvider(
  * } from '@wordpress/components';
  *
  * function NavigatorButton( { path, ...props } ) {
- *  const { push } = useNavigator();
+ *  const { goTo } = useNavigator();
  *  return (
  *    <Button
  *      variant="primary"
- *      onClick={ () => push( path ) }
+ *      onClick={ () => goTo( path ) }
  *      { ...props }
  *    />
  *  );
  * }
  *
  * function NavigatorBackButton( props ) {
- *   const { pop } = useNavigator();
- *   return <Button variant="secondary" onClick={ () => pop() } { ...props } />;
+ *   const { goBack } = useNavigator();
+ *   return <Button variant="secondary" onClick={ () => goBack() } { ...props } />;
  * }
  *
  * const MyNavigation = () => (

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

@@ -9,8 +9,13 @@ import { css } from '@emotion/react';
 /**
  * WordPress dependencies
  */
-import { useContext, useEffect, useState, useMemo } from '@wordpress/element';
-import { useReducedMotion, useFocusOnMount } from '@wordpress/compose';
+import { focus } from '@wordpress/dom';
+import { useContext, useEffect, useMemo, useRef } from '@wordpress/element';
+import {
+	useReducedMotion,
+	useMergeRefs,
+	usePrevious,
+} from '@wordpress/compose';
 import { isRTL } from '@wordpress/i18n';
 
 /**
@@ -47,7 +52,9 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 	const prefersReducedMotion = useReducedMotion();
 	const { location } = useContext( NavigatorContext );
 	const isMatch = location.path === path;
-	const ref = useFocusOnMount();
+	const wrapperRef = useRef< HTMLDivElement >( null );
+
+	const previousLocation = usePrevious( location );
 
 	const cx = useCx();
 	const classes = useMemo(
@@ -61,15 +68,44 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 				} ),
 				className
 			),
-		[ className ]
+		[ className, cx ]
 	);
 
-	// This flag is used to only apply the focus on mount when the actual path changes.
-	// It avoids the focus to happen on the first render.
-	const [ hasPathChanged, setHasPathChanged ] = useState( false );
+	// Focus restoration
+	const isInitialLocation = location.isInitial && ! location.isBack;
 	useEffect( () => {
-		setHasPathChanged( true );
-	}, [ path ] );
+		// Only attempt to restore focus:
+		// - if the current location is not the initial one (to avoid moving focus on page load)
+		// - when the screen becomes visible
+		// - if the wrapper ref has been assigned
+		if ( isInitialLocation || ! isMatch || ! wrapperRef.current ) {
+			return;
+		}
+
+		let elementToFocus: HTMLElement | null = null;
+
+		// When navigating back, if a selector is provided, use it to look for the
+		// target element (assumed to be a node inside the current NavigatorScreen)
+		if ( location.isBack && previousLocation?.focusTargetSelector ) {
+			elementToFocus = wrapperRef.current.querySelector(
+				previousLocation.focusTargetSelector
+			);
+		}
+
+		// 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 ];
+
+			elementToFocus = firstTabbable ?? wrapperRef.current;
+		}
+
+		elementToFocus.focus();
+	}, [ isInitialLocation, isMatch ] );
+
+	const mergedWrapperRef = useMergeRefs( [ forwardedRef, wrapperRef ] );
 
 	if ( ! isMatch ) {
 		return null;
@@ -77,7 +113,11 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 
 	if ( prefersReducedMotion ) {
 		return (
-			<View ref={ forwardedRef } className={ classes } { ...otherProps }>
+			<View
+				ref={ mergedWrapperRef }
+				className={ classes }
+				{ ...otherProps }
+			>
 				{ children }
 			</View>
 		);
@@ -120,7 +160,7 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
 
 	return (
 		<motion.div
-			ref={ hasPathChanged ? ref : undefined }
+			ref={ mergedWrapperRef }
 			className={ classes }
 			{ ...otherProps }
 			{ ...animatedProps }
@@ -142,19 +182,19 @@ function NavigatorScreen( props: Props, forwardedRef: Ref< any > ) {
  * } from '@wordpress/components';
  *
  * function NavigatorButton( { path, ...props } ) {
- *  const { push } = useNavigator();
+ *  const { goTo } = useNavigator();
  *  return (
  *    <Button
  *      variant="primary"
- *      onClick={ () => push( path ) }
+ *      onClick={ () => goTo( path ) }
  *      { ...props }
  *    />
  *  );
  * }
  *
  * function NavigatorBackButton( props ) {
- *   const { pop } = useNavigator();
- *   return <Button variant="secondary" onClick={ () => pop() } { ...props } />;
+ *   const { goBack } = useNavigator();
+ *   return <Button variant="secondary" onClick={ () => goBack() } { ...props } />;
  * }
  *
  * const MyNavigation = () => (

package/src/navigator/stories/index.js

@@ -19,19 +19,33 @@ export default {
 };
 
 function NavigatorButton( { path, ...props } ) {
-	const { push } = useNavigator();
+	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={ () => push( path ) }
-			{ ...props }
+			onClick={ () =>
+				goTo( path, { focusTargetSelector: dataAttrCssSelector } )
+			}
+			{ ...buttonProps }
 		/>
 	);
 }
 
 function NavigatorBackButton( props ) {
-	const { pop } = useNavigator();
-	return <Button variant="secondary" onClick={ () => pop() } { ...props } />;
+	const { goBack } = useNavigator();
+	return (
+		<Button variant="secondary" onClick={ () => goBack() } { ...props } />
+	);
 }
 
 const MyNavigation = () => {

package/src/navigator/test/index.js

@@ -31,27 +31,51 @@ const PATHS = {
 };
 
 function NavigatorButton( { path, onClick, ...props } ) {
-	const { push } = useNavigator();
+	const { goTo } = useNavigator();
 	return (
 		<button
 			onClick={ () => {
-				push( path );
-				// Used to spy on the values passed to `navigator.push`
-				onClick?.( { type: 'push', path } );
+				goTo( path );
+				// Used to spy on the values passed to `navigator.goTo`
+				onClick?.( { type: 'goTo', 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,
+	};
+
+	return (
+		<button
+			onClick={ () => {
+				goTo( path, { focusTargetSelector: dataAttrCssSelector } );
+				// Used to spy on the values passed to `navigator.goTo`
+				onClick?.( { type: 'goTo', path } );
+			} }
+			{ ...buttonProps }
+		/>
+	);
+}
+
 function NavigatorBackButton( { onClick, ...props } ) {
-	const { pop } = useNavigator();
+	const { goBack } = useNavigator();
 	return (
 		<button
 			onClick={ () => {
-				pop();
-				// Used to spy on the values passed to `navigator.push`
-				onClick?.( { type: 'pop' } );
+				goBack();
+				// Used to spy on the values passed to `navigator.goBack`
+				onClick?.( { type: 'goBack' } );
 			} }
 			{ ...props }
 		/>
@@ -65,28 +89,28 @@ const MyNavigation = ( {
 	<NavigatorProvider initialPath={ initialPath }>
 		<NavigatorScreen path={ PATHS.HOME }>
 			<p>This is the home screen.</p>
-			<NavigatorButton
-				path={ PATHS.CHILD }
-				onClick={ onNavigatorButtonClick }
-			>
-				Navigate to child screen.
-			</NavigatorButton>
 			<NavigatorButton
 				path={ PATHS.NOT_FOUND }
 				onClick={ onNavigatorButtonClick }
 			>
 				Navigate to non-existing screen.
 			</NavigatorButton>
+			<NavigatorButtonWithFocusRestoration
+				path={ PATHS.CHILD }
+				onClick={ onNavigatorButtonClick }
+			>
+				Navigate to child screen.
+			</NavigatorButtonWithFocusRestoration>
 		</NavigatorScreen>
 
 		<NavigatorScreen path={ PATHS.CHILD }>
 			<p>This is the child screen.</p>
-			<NavigatorButton
+			<NavigatorButtonWithFocusRestoration
 				path={ PATHS.NESTED }
 				onClick={ onNavigatorButtonClick }
 			>
 				Navigate to nested screen.
-			</NavigatorButton>
+			</NavigatorButtonWithFocusRestoration>
 			<NavigatorBackButton onClick={ onNavigatorButtonClick }>
 				Go back
 			</NavigatorBackButton>
@@ -246,28 +270,28 @@ describe( 'Navigator', () => {
 		expect( getHomeScreen() ).toBeInTheDocument();
 		expect( getToChildScreenButton() ).toBeInTheDocument();
 
-		// Check the values passed to `navigator.push()`
+		// Check the values passed to `navigator.goTo()`
 		expect( spy ).toHaveBeenCalledTimes( 6 );
 		expect( spy ).toHaveBeenNthCalledWith( 1, {
 			path: PATHS.CHILD,
-			type: 'push',
+			type: 'goTo',
 		} );
 		expect( spy ).toHaveBeenNthCalledWith( 2, {
-			type: 'pop',
+			type: 'goBack',
 		} );
 		expect( spy ).toHaveBeenNthCalledWith( 3, {
 			path: PATHS.CHILD,
-			type: 'push',
+			type: 'goTo',
 		} );
 		expect( spy ).toHaveBeenNthCalledWith( 4, {
 			path: PATHS.NESTED,
-			type: 'push',
+			type: 'goTo',
 		} );
 		expect( spy ).toHaveBeenNthCalledWith( 5, {
-			type: 'pop',
+			type: 'goBack',
 		} );
 		expect( spy ).toHaveBeenNthCalledWith( 6, {
-			type: 'pop',
+			type: 'goBack',
 		} );
 	} );
 
@@ -291,11 +315,39 @@ describe( 'Navigator', () => {
 			getNestedScreen( { throwIfNotFound: false } )
 		).not.toBeInTheDocument();
 
-		// Check the values passed to `navigator.push()`
+		// Check the values passed to `navigator.goTo()`
 		expect( spy ).toHaveBeenCalledTimes( 1 );
 		expect( spy ).toHaveBeenNthCalledWith( 1, {
 			path: PATHS.NOT_FOUND,
-			type: 'push',
+			type: 'goTo',
 		} );
 	} );
+
+	it( 'should restore focus correctly', () => {
+		render( <MyNavigation /> );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+
+		// Navigate to child screen
+		fireEvent.click( getToChildScreenButton() );
+
+		expect( getChildScreen() ).toBeInTheDocument();
+
+		// Navigate to nested screen
+		fireEvent.click( getToNestedScreenButton() );
+
+		expect( getNestedScreen() ).toBeInTheDocument();
+
+		// Navigate back to child screen, check that focus was correctly restored
+		fireEvent.click( getBackButton() );
+
+		expect( getChildScreen() ).toBeInTheDocument();
+		expect( getToNestedScreenButton() ).toHaveFocus();
+
+		// Navigate back to home screen, check that focus was correctly restored
+		fireEvent.click( getBackButton() );
+
+		expect( getHomeScreen() ).toBeInTheDocument();
+		expect( getToChildScreenButton() ).toHaveFocus();
+	} );
 } );

package/src/navigator/types.ts

@@ -3,7 +3,9 @@
  */
 import type { ReactNode } from 'react';
 
-type NavigateOptions = {};
+type NavigateOptions = {
+	focusTargetSelector?: string;
+};
 
 export type NavigatorLocation = NavigateOptions & {
 	isInitial?: boolean;
@@ -13,8 +15,8 @@ export type NavigatorLocation = NavigateOptions & {
 
 export type NavigatorContext = {
 	location: NavigatorLocation;
-	push: ( path: string, options: NavigateOptions ) => void;
-	pop: () => void;
+	goTo: ( path: string, options?: NavigateOptions ) => void;
+	goBack: () => void;
 };
 
 // Returned by the `useNavigator` hook

package/src/navigator/use-navigator.ts

@@ -13,12 +13,12 @@ import type { Navigator } from './types';
  * Retrieves a `navigator` instance.
  */
 function useNavigator(): Navigator {
-	const { location, push, pop } = useContext( NavigatorContext );
+	const { location, goTo, goBack } = useContext( NavigatorContext );
 
 	return {
 		location,
-		push,
-		pop,
+		goTo,
+		goBack,
 	};
 }
 

package/src/placeholder/index.js

@@ -73,12 +73,14 @@ function Placeholder( {
 				<Icon icon={ icon } />
 				{ label }
 			</div>
-			{ !! instructions && (
-				<div className="components-placeholder__instructions">
-					{ instructions }
-				</div>
-			) }
-			<div className={ fieldsetClasses }>{ children }</div>
+			<fieldset className={ fieldsetClasses }>
+				{ !! instructions && (
+					<legend className="components-placeholder__instructions">
+						{ instructions }
+					</legend>
+				) }
+				{ children }
+			</fieldset>
 		</div>
 	);
 }

package/src/placeholder/style.scss

@@ -77,6 +77,18 @@
 	}
 }
 
+// Overrides for browser and editor fieldset styles.
+.components-placeholder__fieldset.components-placeholder__fieldset {
+	border: none;
+	padding: 0;
+
+	.components-placeholder__instructions {
+		padding: 0;
+		font-weight: normal;
+		font-size: 1em;
+	}
+}
+
 .components-placeholder__fieldset.is-column-layout,
 .components-placeholder__fieldset.is-column-layout form {
 	flex-direction: column;

package/src/placeholder/test/index.js

@@ -88,7 +88,7 @@ describe( 'Placeholder', () => {
 			const element = <div>Fieldset</div>;
 			const placeholder = shallow( <Placeholder children={ element } /> );
 			const placeholderFieldset = placeholder.find(
-				'.components-placeholder__fieldset'
+				'fieldset.components-placeholder__fieldset'
 			);
 			const child = placeholderFieldset.childAt( 0 );
 
@@ -96,6 +96,23 @@ describe( 'Placeholder', () => {
 			expect( child.matchesElement( element ) ).toBe( true );
 		} );
 
+		it( 'should display a legend if instructions are passed', () => {
+			const element = <div>Fieldset</div>;
+			const instructions = 'Choose an option.';
+			const placeholder = shallow(
+				<Placeholder
+					children={ element }
+					instructions={ instructions }
+				/>
+			);
+			const placeholderLegend = placeholder.find(
+				'legend.components-placeholder__instructions'
+			);
+
+			expect( placeholderLegend.exists() ).toBe( true );
+			expect( placeholderLegend.text() ).toEqual( instructions );
+		} );
+
 		it( 'should add an additional className to the top container', () => {
 			const placeholder = shallow(
 				<Placeholder className="wp-placeholder" />

package/src/scrollable/hook.js

@@ -36,7 +36,7 @@ export function useScrollable( props ) {
 				scrollDirection === 'auto' && styles.scrollAuto,
 				className
 			),
-		[ className, scrollDirection, smoothScroll ]
+		[ className, cx, scrollDirection, smoothScroll ]
 	);
 
 	return { ...otherProps, className: classes };

package/src/slot-fill/bubbles-virtually/fill.js

@@ -8,6 +8,7 @@ import { useRef, useState, useEffect, createPortal } from '@wordpress/element';
  * Internal dependencies
  */
 import useSlot from './use-slot';
+import StyleProvider from '../../style-provider';
 
 function useForceUpdate() {
 	const [ , setState ] = useState( {} );
@@ -48,5 +49,15 @@ export default function Fill( { name, children } ) {
 		children = children( slot.fillProps );
 	}
 
-	return createPortal( children, slot.ref.current );
+	// When using a `Fill`, the `children` will be rendered in the document of the
+	// `Slot`. This means that we need to wrap the `children` in a `StyleProvider`
+	// to make sure we're referencing the right document/iframe (instead of the
+	// context of the `Fill`'s parent).
+	const wrappedChildren = (
+		<StyleProvider document={ slot.ref.current.ownerDocument }>
+			{ children }
+		</StyleProvider>
+	);
+
+	return createPortal( wrappedChildren, slot.ref.current );
 }

package/src/spinner/README.md

@@ -1,19 +1,19 @@
 # Spinner
 
-Spinners notify users that their action is being processed.
-
-![Spinner component](https://wordpress.org/gutenberg/files/2019/07/spinner.png)
-
-## Best practices
-
-The spinner component should:
-
--   Signal to users that the processing of their request is underway and will soon complete.
+`Spinner` is a component used to notify users that their action is being processed.
 
 ## Usage
 
 ```jsx
 import { Spinner } from '@wordpress/components';
 
-const MySpinner = () => <Spinner />;
+function Example() {
+	return <Spinner />;
+}
 ```
+
+## Best practices
+
+The spinner component should:
+
+-   Signal to users that the processing of their request is underway and will soon complete.

package/src/spinner/index.js

@@ -1,8 +1,47 @@
+/**
+ * External dependencies
+ */
+import classNames from 'classnames';
+
 /**
  * Internal dependencies
  */
-import { StyledSpinner } from './styles/spinner-styles';
+import { StyledSpinner, SpinnerTrack, SpinnerIndicator } from './styles';
+
+/**
+ * @typedef OwnProps
+ *
+ * @property {string} [className] Class name
+ */
+/** @typedef {import('react').ComponentPropsWithoutRef<'svg'> & OwnProps} Props */
+
+/**
+ * @param {Props} props
+ * @return {JSX.Element} Element
+ */
+export default function Spinner( { className, ...props } ) {
+	return (
+		<StyledSpinner
+			className={ classNames( 'components-spinner', className ) }
+			viewBox="0 0 100 100"
+			xmlns="http://www.w3.org/2000/svg"
+			role="presentation"
+			focusable="false"
+			{ ...props }
+		>
+			{ /* Gray circular background */ }
+			<SpinnerTrack
+				cx="50"
+				cy="50"
+				r="50"
+				vectorEffect="non-scaling-stroke"
+			/>
 
-export default function Spinner() {
-	return <StyledSpinner className="components-spinner" />;
+			{ /* Theme-colored arc */ }
+			<SpinnerIndicator
+				d="m 50 0 a 50 50 0 0 1 50 50"
+				vectorEffect="non-scaling-stroke"
+			/>
+		</StyledSpinner>
+	);
 }