@wordpress/components 21.2.0 → 22.0.0

package/src/modal/types.ts

@@ -0,0 +1,144 @@
+/**
+ * External dependencies
+ */
+import type {
+	AriaRole,
+	CSSProperties,
+	ReactNode,
+	KeyboardEventHandler,
+	KeyboardEvent,
+	SyntheticEvent,
+} from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import type { useFocusOnMount } from '@wordpress/compose';
+
+export type ModalProps = {
+	aria?: {
+		/**
+		 * If this property is added, it will be added to the modal content
+		 * `div` as `aria-describedby`.
+		 */
+		describedby?: string;
+		/**
+		 * If this property is added, it will be added to the modal content
+		 * `div` as `aria-labelledby`. Use this when you are rendering the title
+		 * yourself within the modal's content area instead of using the `title`
+		 * prop. This ensures the title is usable by assistive technology.
+		 *
+		 * Titles are required for accessibility reasons, see `contentLabel` and
+		 * `title` for other ways to provide a title.
+		 */
+		labelledby?: string;
+	};
+	/**
+	 * Class name added to the body element when the modal is open.
+	 *
+	 * @default 'modal-open'
+	 */
+	bodyOpenClassName?: string;
+	/**
+	 * The children elements.
+	 */
+	children: ReactNode;
+	/**
+	 * If this property is added, it will an additional class name to the modal
+	 * content `div`.
+	 */
+	className?: string;
+	/**
+	 * Label on the close button.
+	 */
+	closeButtonLabel?: string;
+	/**
+	 * If this property is added, it will be added to the modal content `div` as
+	 * `aria-label`.
+	 *
+	 * Titles are required for accessibility reasons, see `aria.labelledby` and
+	 * `title` for other ways to provide a title.
+	 */
+	contentLabel?: string;
+	/**
+	 * If this property is true, it will focus the first tabbable element
+	 * rendered in the modal.
+	 *
+	 * @default true
+	 */
+	focusOnMount?: Parameters< typeof useFocusOnMount >[ 0 ];
+	/**
+	 * If this property is added, an icon will be added before the title.
+	 */
+	icon?: JSX.Element;
+	/**
+	 * If this property is set to false, the modal will not display a close icon
+	 * and cannot be dismissed.
+	 *
+	 * @default true
+	 */
+	isDismissible?: boolean;
+	/**
+	 * This property when set to `true` will render a full screen modal.
+	 *
+	 * @default false
+	 */
+	isFullScreen?: boolean;
+	/**
+	 *  Handle the key down on the modal frame `div`.
+	 */
+	onKeyDown?: KeyboardEventHandler< HTMLDivElement >;
+	/**
+	 * This function is called to indicate that the modal should be closed.
+	 */
+	onRequestClose: (
+		event?: KeyboardEvent< HTMLDivElement > | SyntheticEvent
+	) => void;
+	/**
+	 * If this property is added, it will an additional class name to the modal
+	 * overlay `div`.
+	 */
+	overlayClassName?: string;
+	/**
+	 * If this property is added, it will override the default role of the
+	 * modal.
+	 *
+	 * @default 'dialog'
+	 */
+	role?: AriaRole;
+	/**
+	 * If this property is added, it will determine whether the modal requests
+	 * to close when a mouse click occurs outside of the modal content.
+	 *
+	 * @default true
+	 */
+	shouldCloseOnClickOutside?: boolean;
+	/**
+	 * If this property is added, it will determine whether the modal requests
+	 * to close when the escape key is pressed.
+	 *
+	 * @default true
+	 */
+	shouldCloseOnEsc?: boolean;
+	/**
+	 * If this property is added, it will be added to the modal frame `div`.
+	 */
+	style?: CSSProperties;
+	/**
+	 * This property is used as the modal header's title.
+	 *
+	 * Titles are required for accessibility reasons, see `aria.labelledby` and
+	 * `contentLabel` for other ways to provide a title.
+	 */
+	title?: string;
+	/**
+	 * When set to `true`, the Modal's header (including the icon, title and
+	 * close button) will not be rendered.
+	 *
+	 * _Warning_: This property is still experimental. “Experimental” means this
+	 * is an early implementation subject to drastic and breaking changes.
+	 *
+	 * @default false
+	 */
+	__experimentalHideHeader?: boolean;
+};

package/src/navigation/test/index.js

@@ -220,7 +220,7 @@ describe( 'Navigation', () => {
 		render( <TestNavigation showBadge /> );
 
 		const menuItem = screen.getAllByRole( 'listitem' );
-		expect( menuItem[ 0 ].textContent ).toBe( 'Item 1' + '21' );
+		expect( menuItem[ 0 ] ).toHaveTextContent( 'Item 1' + '21' );
 	} );
 
 	it( 'should render menu titles when items exist', () => {

package/src/navigator/index.ts

@@ -1,5 +1,5 @@
-export { default as NavigatorProvider } from './navigator-provider';
-export { default as NavigatorScreen } from './navigator-screen';
-export { default as NavigatorButton } from './navigator-button';
-export { default as NavigatorBackButton } from './navigator-back-button';
+export { NavigatorProvider } from './navigator-provider';
+export { NavigatorScreen } from './navigator-screen';
+export { NavigatorButton } from './navigator-button';
+export { NavigatorBackButton } from './navigator-back-button';
 export { default as useNavigator } from './use-navigator';

package/src/navigator/navigator-back-button/component.tsx

@@ -11,7 +11,7 @@ import { View } from '../../view';
 import { useNavigatorBackButton } from './hook';
 import type { NavigatorBackButtonProps } from '../types';
 
-function NavigatorBackButton(
+function UnconnectedNavigatorBackButton(
 	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >,
 	forwardedRef: ForwardedRef< any >
 ) {
@@ -54,9 +54,9 @@ function NavigatorBackButton(
  * );
  * ```
  */
-const ConnectedNavigatorBackButton = contextConnect(
-	NavigatorBackButton,
+export const NavigatorBackButton = contextConnect(
+	UnconnectedNavigatorBackButton,
 	'NavigatorBackButton'
 );
 
-export default ConnectedNavigatorBackButton;
+export default NavigatorBackButton;

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

@@ -1 +1 @@
-export { default } from './component';
+export { default as NavigatorBackButton } from './component';

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

@@ -11,7 +11,7 @@ import { View } from '../../view';
 import { useNavigatorButton } from './hook';
 import type { NavigatorButtonProps } from '../types';
 
-function NavigatorButton(
+function UnconnectedNavigatorButton(
 	props: WordPressComponentProps< NavigatorButtonProps, 'button' >,
 	forwardedRef: ForwardedRef< any >
 ) {
@@ -53,9 +53,9 @@ function NavigatorButton(
  * );
  * ```
  */
-const ConnectedNavigatorButton = contextConnect(
-	NavigatorButton,
+export const NavigatorButton = contextConnect(
+	UnconnectedNavigatorButton,
 	'NavigatorButton'
 );
 
-export default ConnectedNavigatorButton;
+export default NavigatorButton;

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

@@ -1 +1 @@
-export { default } from './component';
+export { default as NavigatorButton } from './component';

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

@@ -26,7 +26,7 @@ import type {
 	NavigatorContext as NavigatorContextType,
 } from '../types';
 
-function NavigatorProvider(
+function UnconnectedNavigatorProvider(
 	props: WordPressComponentProps< NavigatorProviderProps, 'div' >,
 	forwardedRef: ForwardedRef< any >
 ) {
@@ -49,6 +49,7 @@ function NavigatorProvider(
 					...options,
 					path,
 					isBack: false,
+					hasRestoredFocus: false,
 				},
 			] );
 		},
@@ -62,6 +63,7 @@ function NavigatorProvider(
 				{
 					...locationHistory[ locationHistory.length - 2 ],
 					isBack: true,
+					hasRestoredFocus: false,
 				},
 			] );
 		}
@@ -129,9 +131,9 @@ function NavigatorProvider(
  * );
  * ```
  */
-const ConnectedNavigatorProvider = contextConnect(
-	NavigatorProvider,
+export const NavigatorProvider = contextConnect(
+	UnconnectedNavigatorProvider,
 	'NavigatorProvider'
 );
 
-export default ConnectedNavigatorProvider;
+export default NavigatorProvider;

package/src/navigator/navigator-provider/index.ts

@@ -1 +1 @@
-export { default } from './component';
+export { default as NavigatorProvider } from './component';

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

@@ -44,7 +44,10 @@ type Props = Omit<
 	keyof MotionProps
 >;
 
-function NavigatorScreen( props: Props, forwardedRef: ForwardedRef< any > ) {
+function UnconnectedNavigatorScreen(
+	props: Props,
+	forwardedRef: ForwardedRef< any >
+) {
 	const { children, className, path, ...otherProps } = useContextSystem(
 		props,
 		'NavigatorScreen'
@@ -79,14 +82,20 @@ function NavigatorScreen( props: Props, forwardedRef: ForwardedRef< any > ) {
 		// - 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 ) {
+		// - if focus hasn't already been restored for the current location
+		if (
+			isInitialLocation ||
+			! isMatch ||
+			! wrapperRef.current ||
+			location.hasRestoredFocus
+		) {
 			return;
 		}
 
 		const activeElement = wrapperRef.current.ownerDocument.activeElement;
 
 		// If an element is already focused within the wrapper do not focus the
-		// element. This prevents inputs or buttons from losing focus unecessarily.
+		// element. This prevents inputs or buttons from losing focus unnecessarily.
 		if ( wrapperRef.current.contains( activeElement ) ) {
 			return;
 		}
@@ -110,10 +119,12 @@ function NavigatorScreen( props: Props, forwardedRef: ForwardedRef< any > ) {
 			elementToFocus = firstTabbable ?? wrapperRef.current;
 		}
 
+		location.hasRestoredFocus = true;
 		elementToFocus.focus();
 	}, [
 		isInitialLocation,
 		isMatch,
+		location.hasRestoredFocus,
 		location.isBack,
 		previousLocation?.focusTargetSelector,
 	] );
@@ -217,9 +228,9 @@ function NavigatorScreen( props: Props, forwardedRef: ForwardedRef< any > ) {
  * );
  * ```
  */
-const ConnectedNavigatorScreen = contextConnect(
-	NavigatorScreen,
+export const NavigatorScreen = contextConnect(
+	UnconnectedNavigatorScreen,
 	'NavigatorScreen'
 );
 
-export default ConnectedNavigatorScreen;
+export default NavigatorScreen;

package/src/navigator/navigator-screen/index.ts

@@ -1 +1 @@
-export { default } from './component';
+export { default as NavigatorScreen } from './component';

package/src/navigator/stories/index.tsx

@@ -0,0 +1,210 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../button';
+import { Card, CardBody, CardFooter, CardHeader } from '../../card';
+import { HStack } from '../../h-stack';
+import Dropdown from '../../dropdown';
+import {
+	NavigatorProvider,
+	NavigatorScreen,
+	NavigatorButton,
+	NavigatorBackButton,
+} from '..';
+
+const meta: ComponentMeta< typeof NavigatorProvider > = {
+	component: NavigatorProvider,
+	title: 'Components (Experimental)/Navigator',
+	subcomponents: { NavigatorScreen, NavigatorButton, NavigatorBackButton },
+	argTypes: {
+		as: { control: { type: null } },
+		children: { control: { type: null } },
+		initialPath: { control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof NavigatorProvider > = ( {
+	style,
+	...props
+} ) => (
+	<NavigatorProvider
+		style={ { ...style, height: '100vh', maxHeight: '450px' } }
+		{ ...props }
+	>
+		<NavigatorScreen path="/">
+			<Card>
+				<CardBody>
+					<p>This is the home screen.</p>
+
+					<HStack justify="flex-start" wrap>
+						<NavigatorButton variant="secondary" path="/child">
+							Navigate to child screen.
+						</NavigatorButton>
+
+						<NavigatorButton
+							variant="secondary"
+							path="/overflow-child"
+						>
+							Navigate to screen with horizontal overflow.
+						</NavigatorButton>
+
+						<NavigatorButton variant="secondary" path="/stickies">
+							Navigate to screen with sticky content.
+						</NavigatorButton>
+
+						<Dropdown
+							renderToggle={ ( {
+								isOpen,
+								onToggle,
+							}: {
+								// TODO: remove once `Dropdown` is refactored to TypeScript
+								isOpen: boolean;
+								onToggle: () => void;
+							} ) => (
+								<Button
+									onClick={ onToggle }
+									aria-expanded={ isOpen }
+									variant="primary"
+								>
+									Open test dialog
+								</Button>
+							) }
+							renderContent={ () => (
+								<Card>
+									<CardHeader>Go</CardHeader>
+									<CardBody>Stuff</CardBody>
+								</Card>
+							) }
+						/>
+					</HStack>
+				</CardBody>
+			</Card>
+		</NavigatorScreen>
+
+		<NavigatorScreen path="/child">
+			<Card>
+				<CardBody>
+					<p>This is the child screen.</p>
+					<NavigatorBackButton variant="secondary">
+						Go back
+					</NavigatorBackButton>
+				</CardBody>
+			</Card>
+		</NavigatorScreen>
+
+		<NavigatorScreen path="/overflow-child">
+			<Card>
+				<CardBody>
+					<NavigatorBackButton variant="secondary">
+						Go back
+					</NavigatorBackButton>
+					<div
+						style={ {
+							display: 'inline-block',
+							background: 'papayawhip',
+						} }
+					>
+						<span
+							style={ {
+								color: 'palevioletred',
+								whiteSpace: 'nowrap',
+								fontSize: '42vw',
+							} }
+						>
+							¯\_(ツ)_/¯
+						</span>
+					</div>
+				</CardBody>
+			</Card>
+		</NavigatorScreen>
+
+		<NavigatorScreen path="/stickies">
+			<Card>
+				<CardHeader style={ getStickyStyles( { zIndex: 2 } ) }>
+					<NavigatorBackButton variant="secondary">
+						Go back
+					</NavigatorBackButton>
+				</CardHeader>
+				<CardBody>
+					<div
+						style={ getStickyStyles( {
+							top: 69,
+							bgColor: 'peachpuff',
+						} ) }
+					>
+						<h2>A wild sticky element appears</h2>
+					</div>
+					<MetaphorIpsum quantity={ 3 } />
+				</CardBody>
+				<CardBody>
+					<div
+						style={ getStickyStyles( {
+							top: 69,
+							bgColor: 'paleturquoise',
+						} ) }
+					>
+						<h2>Another wild sticky element appears</h2>
+					</div>
+					<MetaphorIpsum quantity={ 3 } />
+				</CardBody>
+				<CardFooter
+					style={ getStickyStyles( {
+						bgColor: 'mistyrose',
+					} ) }
+				>
+					<Button variant="primary">Primary noop</Button>
+				</CardFooter>
+			</Card>
+		</NavigatorScreen>
+	</NavigatorProvider>
+);
+
+export const Default: ComponentStory< typeof NavigatorProvider > =
+	Template.bind( {} );
+Default.args = {
+	initialPath: '/',
+};
+
+function getStickyStyles( {
+	bottom = 0,
+	bgColor = 'whitesmoke',
+	top = 0,
+	zIndex = 1,
+} ): React.CSSProperties {
+	return {
+		display: 'flex',
+		position: 'sticky',
+		top,
+		bottom,
+		zIndex,
+		backgroundColor: bgColor,
+	};
+}
+
+function MetaphorIpsum( { quantity }: { quantity: number } ) {
+	const list = [
+		'A loopy clarinet’s year comes with it the thought that the fenny step-son is an ophthalmologist. The literature would have us believe that a glabrate country is not but a rhythm. A beech is a rub from the right perspective. In ancient times few can name an unglossed walrus that isn’t an unspilt trial.',
+		'Authors often misinterpret the afterthought as a roseless mother-in-law, when in actuality it feels more like an uncapped thunderstorm. In recent years, some posit the tarry bottle to be less than acerb. They were lost without the unkissed timbale that composed their customer. A donna is a springtime breath.',
+		'It’s an undeniable fact, really; their museum was, in this moment, a snotty beef. The swordfishes could be said to resemble prowessed lasagnas. However, the rainier authority comes from a cureless soup. Unfortunately, that is wrong; on the contrary, the cover is a powder.',
+	];
+	quantity = Math.min( list.length, quantity );
+	return (
+		<>
+			{ list.slice( 0, quantity ).map( ( text, key ) => (
+				<p style={ { maxWidth: '20em' } } key={ key }>
+					{ text }
+				</p>
+			) ) }
+		</>
+	);
+}