@wordpress/components 19.3.0 → 19.4.0

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>
+	);
 }

package/src/spinner/stories/index.js

@@ -1,10 +1,43 @@
+/**
+ * External dependencies
+ */
+import { css } from '@emotion/react';
+
 /**
  * Internal dependencies
  */
+import { useCx } from '../../utils';
+import { space } from '../../ui/utils/space';
 import Spinner from '../';
 
-export default { title: 'Components/Spinner', component: Spinner };
+const sizes = {
+	default: undefined,
+	medium: space( 20 ),
+	large: space( 40 ),
+};
+
+export default {
+	title: 'Components/Spinner',
+	component: Spinner,
+	argTypes: {
+		size: {
+			options: Object.keys( sizes ),
+			mapping: sizes,
+			control: { type: 'select' },
+		},
+	},
+};
+
+const Template = ( { size } ) => {
+	const cx = useCx();
+	const spinnerClassname = cx( css`
+		width: ${ size };
+		height: ${ size };
+	` );
+	return <Spinner className={ spinnerClassname } />;
+};
 
-export const _default = () => {
-	return <Spinner />;
+export const Default = Template.bind( {} );
+Default.args = {
+	size: 'default',
 };

package/src/spinner/styles.js

@@ -0,0 +1,47 @@
+/**
+ * External dependencies
+ */
+import styled from '@emotion/styled';
+import { css, keyframes } from '@emotion/react';
+
+/**
+ * Internal dependencies
+ */
+import { COLORS, CONFIG } from '../utils';
+
+const spinAnimation = keyframes`
+	from {
+		transform: rotate(0deg);
+	}
+	to {
+		transform: rotate(360deg);
+	}
+ `;
+
+export const StyledSpinner = styled.svg`
+	width: ${ CONFIG.spinnerSize }px;
+	height: ${ CONFIG.spinnerSize }px;
+	display: inline-block;
+	margin: 5px 11px 0;
+	position: relative;
+	color: var( --wp-admin-theme-color );
+	overflow: visible;
+`;
+
+const commonPathProps = css`
+	fill: transparent;
+	stroke-width: 1.5px;
+`;
+
+export const SpinnerTrack = styled.circle`
+	${ commonPathProps };
+	stroke: ${ COLORS.gray[ 300 ] };
+`;
+
+export const SpinnerIndicator = styled.path`
+	${ commonPathProps };
+	stroke: currentColor;
+	stroke-linecap: round;
+	transform-origin: 50% 50%;
+	animation: 1.4s linear infinite both ${ spinAnimation };
+`;

package/src/surface/hook.js

@@ -54,6 +54,7 @@ export function useSurface( props ) {
 		borderRight,
 		borderTop,
 		className,
+		cx,
 		variant,
 	] );
 

package/src/text/hook.js

@@ -126,6 +126,7 @@ export default function useText( props ) {
 		align,
 		className,
 		color,
+		cx,
 		display,
 		isBlock,
 		isCaption,

package/src/tip/index.js

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { SVG, Path } from '@wordpress/primitives';
+import { Icon, tip } from '@wordpress/icons';
 
 /**
  * @typedef Props
@@ -15,9 +15,7 @@ import { SVG, Path } from '@wordpress/primitives';
 function Tip( props ) {
 	return (
 		<div className="components-tip">
-			<SVG width="24" height="24" viewBox="0 0 24 24">
-				<Path d="M12 15.8c-3.7 0-6.8-3-6.8-6.8s3-6.8 6.8-6.8c3.7 0 6.8 3 6.8 6.8s-3.1 6.8-6.8 6.8zm0-12C9.1 3.8 6.8 6.1 6.8 9s2.4 5.2 5.2 5.2c2.9 0 5.2-2.4 5.2-5.2S14.9 3.8 12 3.8zM8 17.5h8V19H8zM10 20.5h4V22h-4z" />
-			</SVG>
+			<Icon icon={ tip } />
 			<p>{ props.children }</p>
 		</div>
 	);

package/src/toggle-group-control/toggle-group-control/component.tsx

@@ -81,7 +81,7 @@ function ToggleGroupControl(
 				'medium',
 				className
 			),
-		[ className, isBlock ]
+		[ className, cx, isBlock ]
 	);
 	return (
 		<BaseControl help={ help }>

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

@@ -135,13 +135,15 @@ export const WithNonToolsPanelItems = () => {
 	);
 };
 
-export const WithOptionalItemsPlusIcon = () => {
+export const WithOptionalItemsPlusIcon = ( { isShownByDefault } ) => {
 	const [ height, setHeight ] = useState();
 	const [ width, setWidth ] = useState();
+	const [ minWidth, setMinWidth ] = useState();
 
 	const resetAll = () => {
 		setHeight( undefined );
 		setWidth( undefined );
+		setMinWidth( undefined );
 	};
 
 	return (
@@ -150,7 +152,20 @@ export const WithOptionalItemsPlusIcon = () => {
 				<ToolsPanel
 					label="Tools Panel (optional items only)"
 					resetAll={ resetAll }
+					key={ isShownByDefault }
 				>
+					<SingleColumnItem
+						hasValue={ () => !! minWidth }
+						label="Minimum width"
+						onDeselect={ () => setMinWidth( undefined ) }
+						isShownByDefault={ isShownByDefault }
+					>
+						<UnitControl
+							label="Minimum width"
+							value={ minWidth }
+							onChange={ ( next ) => setMinWidth( next ) }
+						/>
+					</SingleColumnItem>
 					<SingleColumnItem
 						hasValue={ () => !! width }
 						label="Width"
@@ -181,6 +196,10 @@ export const WithOptionalItemsPlusIcon = () => {
 	);
 };
 
+WithOptionalItemsPlusIcon.args = {
+	isShownByDefault: false,
+};
+
 const { Fill: ToolsPanelItems, Slot } = createSlotFill( 'ToolsPanelSlot' );
 const panelId = 'unique-tools-panel-id';
 

package/src/tools-panel/test/__snapshots__/index.js.snap

@@ -175,7 +175,6 @@ exports[`ToolsPanel first and last panel items should apply first/last classes t
             aria-hidden="true"
             focusable="false"
             height="24"
-            role="img"
             viewBox="0 0 24 24"
             width="24"
             xmlns="http://www.w3.org/2000/svg"