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

package/src/modal/index.js

@@ -1,3 +1,5 @@
+//@ts-nocheck
+
 /**
  * External dependencies
  */
@@ -6,7 +8,12 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { createPortal, useEffect, useRef } from '@wordpress/element';
+import {
+	createPortal,
+	useEffect,
+	useRef,
+	forwardRef,
+} from '@wordpress/element';
 import {
 	useInstanceId,
 	useFocusReturn,
@@ -15,7 +22,6 @@ import {
 	useConstrainedTabbing,
 	useMergeRefs,
 } from '@wordpress/compose';
-import deprecated from '@wordpress/deprecated';
 import { ESCAPE } from '@wordpress/keycodes';
 import { __ } from '@wordpress/i18n';
 import { closeSmall } from '@wordpress/icons';
@@ -30,31 +36,33 @@ import StyleProvider from '../style-provider';
 // Used to count the number of open modals.
 let openModalCount = 0;
 
-export default function Modal( {
-	bodyOpenClassName = 'modal-open',
-	role = 'dialog',
-	title = null,
-	focusOnMount = true,
-	shouldCloseOnEsc = true,
-	shouldCloseOnClickOutside = true,
-	isDismissable, // Deprecated
-	isDismissible = isDismissable || true,
-	/* accessibility */
-	aria = {
-		labelledby: null,
-		describedby: null,
-	},
-	onRequestClose,
-	icon,
-	closeButtonLabel,
-	children,
-	style,
-	overlayClassName,
-	className,
-	contentLabel,
-	onKeyDown,
-	isFullScreen = false,
-} ) {
+function Modal( props, forwardedRef ) {
+	const {
+		bodyOpenClassName = 'modal-open',
+		role = 'dialog',
+		title = null,
+		focusOnMount = true,
+		shouldCloseOnEsc = true,
+		shouldCloseOnClickOutside = true,
+		isDismissible = true,
+		/* accessibility */
+		aria = {
+			labelledby: null,
+			describedby: null,
+		},
+		onRequestClose,
+		icon,
+		closeButtonLabel,
+		children,
+		style,
+		overlayClassName,
+		className,
+		contentLabel,
+		onKeyDown,
+		isFullScreen = false,
+		__experimentalHideHeader = false,
+	} = props;
+
 	const ref = useRef();
 	const instanceId = useInstanceId( Modal );
 	const headingId = title
@@ -83,13 +91,6 @@ export default function Modal( {
 		};
 	}, [] );
 
-	if ( isDismissable ) {
-		deprecated( 'isDismissable prop of the Modal component', {
-			since: '5.4',
-			alternative: 'isDismissible prop (renamed) of the Modal component',
-		} );
-	}
-
 	function handleEscapeKeyDown( event ) {
 		if (
 			shouldCloseOnEsc &&
@@ -106,7 +107,7 @@ export default function Modal( {
 	return createPortal(
 		// eslint-disable-next-line jsx-a11y/no-static-element-interactions
 		<div
-			ref={ ref }
+			ref={ useMergeRefs( [ ref, forwardedRef ] ) }
 			className={ classnames(
 				'components-modal__screen-overlay',
 				overlayClassName
@@ -139,38 +140,43 @@ export default function Modal( {
 					onKeyDown={ onKeyDown }
 				>
 					<div
-						className={ 'components-modal__content' }
+						className={ classnames( 'components-modal__content', {
+							'hide-header': __experimentalHideHeader,
+						} ) }
 						role="document"
 					>
-						<div className="components-modal__header">
-							<div className="components-modal__header-heading-container">
-								{ icon && (
-									<span
-										className="components-modal__icon-container"
-										aria-hidden
-									>
-										{ icon }
-									</span>
-								) }
-								{ title && (
-									<h1
-										id={ headingId }
-										className="components-modal__header-heading"
-									>
-										{ title }
-									</h1>
+						{ ! __experimentalHideHeader && (
+							<div className="components-modal__header">
+								<div className="components-modal__header-heading-container">
+									{ icon && (
+										<span
+											className="components-modal__icon-container"
+											aria-hidden
+										>
+											{ icon }
+										</span>
+									) }
+									{ title && (
+										<h1
+											id={ headingId }
+											className="components-modal__header-heading"
+										>
+											{ title }
+										</h1>
+									) }
+								</div>
+								{ isDismissible && (
+									<Button
+										onClick={ onRequestClose }
+										icon={ closeSmall }
+										label={
+											closeButtonLabel ||
+											__( 'Close dialog' )
+										}
+									/>
 								) }
 							</div>
-							{ isDismissible && (
-								<Button
-									onClick={ onRequestClose }
-									icon={ closeSmall }
-									label={
-										closeButtonLabel || __( 'Close dialog' )
-									}
-								/>
-							) }
-						</div>
+						) }
 						{ children }
 					</div>
 				</div>
@@ -179,3 +185,5 @@ export default function Modal( {
 		document.body
 	);
 }
+
+export default forwardRef( Modal );

package/src/modal/stories/index.js

@@ -20,7 +20,7 @@ export default {
 	title: 'Components/Modal',
 	component: Modal,
 	parameters: {
-		knobs: { disabled: false },
+		knobs: { disable: false },
 	},
 };
 
@@ -55,6 +55,10 @@ export const _default = () => {
 		'shouldCloseOnClickOutside',
 		true
 	);
+	const __experimentalHideHeader = boolean(
+		'__experimentalHideHeader',
+		false
+	);
 
 	const iconComponent = showIcon ? <Icon icon={ wordpress } /> : null;
 
@@ -65,6 +69,7 @@ export const _default = () => {
 		shouldCloseOnEsc,
 		shouldCloseOnClickOutside,
 		title,
+		__experimentalHideHeader,
 	};
 
 	return <ModalExample { ...modalProps } />;

package/src/modal/style.scss

@@ -126,4 +126,13 @@
 		display: block;
 		margin-bottom: $grid-unit-30;
 	}
+
+	&.hide-header {
+		margin-top: 0;
+		padding-top: $grid-unit-30;
+
+		&::before {
+			content: none;
+		}
+	}
 }

package/src/modal/test/index.js

@@ -46,4 +46,15 @@ describe( 'Modal', () => {
 		const titleId = within( dialog ).getByText( 'Test Title' ).id;
 		expect( dialog ).toHaveAttribute( 'aria-labelledby', titleId );
 	} );
+
+	it( 'hides the header when the `__experimentalHideHeader` prop is used', () => {
+		render(
+			<Modal title="Test Title" __experimentalHideHeader>
+				<p>Modal content</p>
+			</Modal>
+		);
+		const dialog = screen.getByRole( 'dialog' );
+		const title = within( dialog ).queryByText( 'Test Title' );
+		expect( title ).not.toBeInTheDocument();
+	} );
 } );

package/src/navigation/README.md

@@ -44,15 +44,6 @@ const MyNavigation = () => (
 	</Navigation>
 );
 ```
-## CSS Classes leveraged
-
-The structural CSS for the navigation block targets generic classnames across menu items of multiple types including those automatically generated by the Page List block. Here are some of the notable classnames and what they are used for:
-
-- `.wp-block-navigation__submenu-container` is applied to submenus to main menu items.
-- `.wp-block-navigation-item` is applied to every menu item.
-- `.wp-block-navigation-item__content` is applied to the link inside a menu item.
-- `.wp-block-navigation-item__label` is applied to the innermost container around the menu item text label.
-- `.wp-block-navigation__submenu-icon` is applied to the submenu indicator (chevron).
 
 ## Navigation Props
 

package/src/navigator/context.ts

@@ -8,5 +8,9 @@ import { createContext } from '@wordpress/element';
  */
 import type { NavigatorContext as NavigatorContextType } from './types';
 
-const initialContextValue: NavigatorContextType = [ {}, () => {} ];
+const initialContextValue: NavigatorContextType = {
+	location: {},
+	goTo: () => {},
+	goBack: () => {},
+};
 export const NavigatorContext = createContext( initialContextValue );

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

@@ -6,8 +6,6 @@ This feature is still experimental. “Experimental” means this is an early im
 
 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 `Navigator*` family of components is _not_ opinionated in terms of UI, and can be composed with any UI components to navigate between the nested screens.
-
 ## Usage
 
 ```jsx
@@ -17,34 +15,34 @@ import {
 	__experimentalUseNavigator as useNavigator,
 } from '@wordpress/components';
 
-function NavigatorButton( {
-	path,
-	isBack = false,
-	...props
-} ) {
-	const navigator = useNavigator();
+function NavigatorButton( { path, ...props } ) {
+	const { goTo } = useNavigator();
 	return (
 		<Button
-			onClick={ () => navigator.push( path, { isBack } ) }
-			{ ...props }
-		/>
-	);
+		 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 isPrimary path="/child">
+			<NavigatorButton path="/child">
 				Navigate to child screen.
 			</NavigatorButton>
 		</NavigatorScreen>
 
 		<NavigatorScreen path="/child">
 			<p>This is the child screen.</p>
-			<NavigatorButton isPrimary path="/" isBack>
-				Go back
-			</NavigatorButton>
+			<NavigatorBackButton>Go back</NavigatorBackButton>
 		</NavigatorScreen>
 	</NavigatorProvider>
 );
@@ -64,12 +62,24 @@ The initial active path.
 
 You can retrieve a `navigator` instance by using the `useNavigator` hook.
 
-The hook offers the following methods:
+The `navigator` instance has a few properties:
 
-### `push`: `( path: string, options ) => void`
+### `goTo`: `( path: string, options: NavigateOptions ) => void`
 
-The `push` function allows you to navigate to a given path. The second argument can augment the navigation operations with different options.
+The `goTo` function allows navigating to a given path. The second argument can augment the navigation operations with different options.
 
 The available options are:
 
-- `isBack` (`boolean): A boolean flag indicating that we're moving back to a previous state. -->
+- `focusTargetSelector`: `string`. An optional property used to specify the CSS selector used to restore focus on the matching element when navigating back.
+
+### `goBack`: `() => void`
+
+The `goBack` function allows navigating to the previous path.
+
+### `location`: `NavigatorLocation`
+
+The `location` object represent the current location, and has a few properties:
+
+- `path`: `string`. The path associated to the location.
+- `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards in the location stack.
+- `isInitial`: `boolean`. A flag that is `true` only for the first (root) location in the location stack.

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

@@ -1,14 +1,13 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
 import type { Ref } from 'react';
 import { css } from '@emotion/react';
 
 /**
  * WordPress dependencies
  */
-import { useMemo, useState } from '@wordpress/element';
+import { useMemo, useState, useCallback } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -21,7 +20,11 @@ import {
 import { useCx } from '../../utils/hooks/use-cx';
 import { View } from '../../view';
 import { NavigatorContext } from '../context';
-import type { NavigatorProviderProps, NavigatorPath } from '../types';
+import type {
+	NavigatorProviderProps,
+	NavigatorLocation,
+	NavigatorContext as NavigatorContextType,
+} from '../types';
 
 function NavigatorProvider(
 	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
@@ -34,20 +37,62 @@ function NavigatorProvider(
 		...otherProps
 	} = useContextSystem( props, 'NavigatorProvider' );
 
-	const [ path, setPath ] = useState< NavigatorPath >( {
-		path: initialPath,
-	} );
+	const [ locationHistory, setLocationHistory ] = useState<
+		NavigatorLocation[]
+	>( [
+		{
+			path: initialPath,
+		},
+	] );
+
+	const goTo: NavigatorContextType[ 'goTo' ] = useCallback(
+		( path, options = {} ) => {
+			setLocationHistory( [
+				...locationHistory,
+				{
+					...options,
+					path,
+					isBack: false,
+				},
+			] );
+		},
+		[ locationHistory ]
+	);
+
+	const goBack: NavigatorContextType[ 'goBack' ] = useCallback( () => {
+		if ( locationHistory.length > 1 ) {
+			setLocationHistory( [
+				...locationHistory.slice( 0, -2 ),
+				{
+					...locationHistory[ locationHistory.length - 2 ],
+					isBack: true,
+				},
+			] );
+		}
+	}, [ locationHistory ] );
+
+	const navigatorContextValue: NavigatorContextType = useMemo(
+		() => ( {
+			location: {
+				...locationHistory[ locationHistory.length - 1 ],
+				isInitial: locationHistory.length === 1,
+			},
+			goTo,
+			goBack,
+		} ),
+		[ 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 (
 		<View ref={ forwardedRef } className={ classes } { ...otherProps }>
-			<NavigatorContext.Provider value={ [ path, setPath ] }>
+			<NavigatorContext.Provider value={ navigatorContextValue }>
 				{ children }
 			</NavigatorContext.Provider>
 		</View>
@@ -56,7 +101,6 @@ 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 Global Styles sidebar is an example of this. The `Navigator*` family of components is _not_ opinionated in terms of UI, and can be composed with any UI components to navigate between the nested screens.
  *
  * @example
  * ```jsx
@@ -66,34 +110,34 @@ function NavigatorProvider(
  *   __experimentalUseNavigator as useNavigator,
  * } from '@wordpress/components';
  *
- * function NavigatorButton( {
- *   path,
- *   isBack = false,
- *   ...props
- * } ) {
- *   const navigator = useNavigator();
- *   return (
- *   	<Button
- *   	  onClick={ () => navigator.push( path, { isBack } ) }
- *   	  { ...props }
- *   	/>
- *   );
+ * 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 isPrimary path="/child">
+ *   	   <NavigatorButton path="/child">
  *          Navigate to child screen.
  *       </NavigatorButton>
  *     </NavigatorScreen>
  *
  *     <NavigatorScreen path="/child">
  *       <p>This is the child screen.</p>
- *       <NavigatorButton isPrimary path="/" isBack>
- *         Go back
- *       </NavigatorButton>
+ *       <NavigatorBackButton>Go back</NavigatorBackButton>
  *     </NavigatorScreen>
  *   </NavigatorProvider>
  * );