@wordpress/components 23.4.0 → 23.6.0

package/src/guide/README.md

@@ -37,20 +37,6 @@ function MyTutorial() {
 
 The component accepts the following props:
 
-### onFinish
-
-A function which is called when the guide is finished. The guide is finished when the modal is closed or when the user clicks _Finish_ on the last page of the guide.
-
--   Type: `function`
--   Required: Yes
-
-### pages
-
-A list of objects describing each page in the guide. Each object **must** contain a `'content'` property and may optionally contain a `'image'` property.
-
--   Type: `array`
--   Required: Yes
-
 ### className
 
 A custom class to add to the modal.
@@ -62,7 +48,7 @@ A custom class to add to the modal.
 
 This property is used as the modal's accessibility label. It is required for accessibility reasons.
 
--   Type: `String`
+-   Type: `string`
 -   Required: Yes
 
 ### finishButtonText
@@ -71,3 +57,19 @@ Use this to customize the label of the _Finish_ button shown at the end of the g
 
 -   Type: `string`
 -   Required: No
+-	Default: `'Finish'`
+
+### onFinish
+
+A function which is called when the guide is finished. The guide is finished when the modal is closed or when the user clicks _Finish_ on the last page of the guide.
+
+-   Type: `( event?: KeyboardEvent< HTMLDivElement > | SyntheticEvent ) => void`
+-   Required: Yes
+
+### pages
+
+A list of objects describing each page in the guide. Each object **must** contain a `'content'` property and may optionally contain a `'image'` property.
+
+-   Type: `{ content: ReactNode; image?: ReactNode; }[]`
+-   Required: No
+-   Default: `[]`

package/src/guide/{icons.js → icons.tsx}

@@ -3,7 +3,7 @@
  */
 import { SVG, Circle } from '@wordpress/primitives';
 
-export const PageControlIcon = ( { isSelected } ) => (
+export const PageControlIcon = ( { isSelected }: { isSelected: boolean } ) => (
 	<SVG width="8" height="8" fill="none" xmlns="http://www.w3.org/2000/svg">
 		<Circle
 			cx="4"

package/src/guide/{index.js → index.tsx}

@@ -17,16 +17,49 @@ import { focus } from '@wordpress/dom';
 import Modal from '../modal';
 import Button from '../button';
 import PageControl from './page-control';
+import type { GuideProps } from './types';
 
-export default function Guide( {
+/**
+ * `Guide` is a React component that renders a _user guide_ in a modal. The guide consists of several pages which the user can step through one by one. The guide is finished when the modal is closed or when the user clicks _Finish_ on the last page of the guide.
+ *
+ * ```jsx
+ * function MyTutorial() {
+ * 	const [ isOpen, setIsOpen ] = useState( true );
+ *
+ * 	if ( ! isOpen ) {
+ * 		return null;
+ * 	}
+ *
+ * 	return (
+ * 		<Guide
+ * 			onFinish={ () => setIsOpen( false ) }
+ * 			pages={ [
+ * 				{
+ * 					content: <p>Welcome to the ACME Store!</p>,
+ * 				},
+ * 				{
+ * 					image: <img src="https://acmestore.com/add-to-cart.png" />,
+ * 					content: (
+ * 						<p>
+ * 							Click <i>Add to Cart</i> to buy a product.
+ * 						</p>
+ * 					),
+ * 				},
+ * 			] }
+ * 		/>
+ * 	);
+ * }
+ * ```
+ */
+function Guide( {
 	children,
 	className,
 	contentLabel,
-	finishButtonText,
+	finishButtonText = __( 'Finish' ),
 	onFinish,
 	pages = [],
-} ) {
-	const guideContainer = useRef();
+}: GuideProps ) {
+	const guideContainer = useRef< HTMLDivElement >( null );
 	const [ currentPage, setCurrentPage ] = useState( 0 );
 
 	useEffect( () => {
@@ -42,12 +75,17 @@ export default function Guide( {
 		// Each time we change the current page, start from the first element of the page.
 		// This also solves any focus loss that can happen.
 		if ( guideContainer.current ) {
-			focus.tabbable.find( guideContainer.current )?.[ 0 ]?.focus();
+			(
+				focus.tabbable.find( guideContainer.current ) as HTMLElement[]
+			 )[ 0 ]?.focus();
 		}
 	}, [ currentPage ] );
 
 	if ( Children.count( children ) ) {
-		pages = Children.map( children, ( child ) => ( { content: child } ) );
+		pages =
+			Children.map( children, ( child ) => ( {
+				content: child,
+			} ) ) ?? [];
 	}
 
 	const canGoBack = currentPage > 0;
@@ -124,7 +162,7 @@ export default function Guide( {
 							className="components-guide__finish-button"
 							onClick={ onFinish }
 						>
-							{ finishButtonText || __( 'Finish' ) }
+							{ finishButtonText }
 						</Button>
 					) }
 				</div>
@@ -132,3 +170,5 @@ export default function Guide( {
 		</Modal>
 	);
 }
+
+export default Guide;

package/src/guide/{page-control.js → page-control.tsx}

@@ -8,12 +8,13 @@ import { __, sprintf } from '@wordpress/i18n';
  */
 import Button from '../button';
 import { PageControlIcon } from './icons';
+import type { PageControlProps } from './types';
 
 export default function PageControl( {
 	currentPage,
 	numberOfPages,
 	setCurrentPage,
-} ) {
+}: PageControlProps ) {
 	return (
 		<ul
 			className="components-guide__page-control"

package/src/guide/{page.js → page.tsx}

@@ -4,7 +4,14 @@
 import { useEffect } from '@wordpress/element';
 import deprecated from '@wordpress/deprecated';
 
-export default function GuidePage( props ) {
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../ui/context';
+
+export default function GuidePage(
+	props: WordPressComponentProps< {}, 'div', false >
+) {
 	useEffect( () => {
 		deprecated( '<GuidePage>', {
 			since: '5.5',

package/src/guide/stories/{index.js → index.tsx}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -7,9 +12,9 @@ import { useState } from '@wordpress/element';
  * Internal dependencies
  */
 import Button from '../../button';
-import Guide from '../';
+import Guide from '..';
 
-export default {
+const meta: ComponentMeta< typeof Guide > = {
 	title: 'Components/Guide',
 	component: Guide,
 	argTypes: {
@@ -18,8 +23,9 @@ export default {
 		onFinish: { action: 'onFinish' },
 	},
 };
+export default meta;
 
-const Template = ( { onFinish, ...props } ) => {
+const Template: ComponentStory< typeof Guide > = ( { onFinish, ...props } ) => {
 	const [ isOpen, setOpen ] = useState( false );
 
 	const openGuide = () => setOpen( true );
@@ -34,8 +40,8 @@ const Template = ( { onFinish, ...props } ) => {
 				<Guide
 					{ ...props }
 					onFinish={ ( ...finishArgs ) => {
-						closeGuide( ...finishArgs );
-						onFinish( ...finishArgs );
+						closeGuide();
+						onFinish?.( ...finishArgs );
 					} }
 				/>
 			) }

package/src/guide/test/{index.js → index.tsx}

@@ -7,17 +7,23 @@ import userEvent from '@testing-library/user-event';
 /**
  * Internal dependencies
  */
-import Guide from '../';
+import Guide from '..';
+
+const defaultProps = {
+	onFinish: () => {},
+	contentLabel: 'Arbitrary Content Label',
+};
 
 describe( 'Guide', () => {
 	it( 'renders nothing when there are no pages', () => {
-		render( <Guide pages={ [] } /> );
+		render( <Guide { ...defaultProps } pages={ [] } /> );
 		expect( screen.queryByRole( 'dialog' ) ).not.toBeInTheDocument();
 	} );
 
 	it( 'renders one page at a time', () => {
 		render(
 			<Guide
+				{ ...defaultProps }
 				pages={ [
 					{ content: <p>Page 1</p> },
 					{ content: <p>Page 2</p> },
@@ -33,6 +39,7 @@ describe( 'Guide', () => {
 	it( 'hides back button and shows forward button on the first page', () => {
 		render(
 			<Guide
+				{ ...defaultProps }
 				pages={ [
 					{ content: <p>Page 1</p> },
 					{ content: <p>Page 2</p> },
@@ -55,6 +62,7 @@ describe( 'Guide', () => {
 		const user = userEvent.setup();
 		render(
 			<Guide
+				{ ...defaultProps }
 				pages={ [
 					{ content: <p>Page 1</p> },
 					{ content: <p>Page 2</p> },
@@ -78,7 +86,12 @@ describe( 'Guide', () => {
 	} );
 
 	it( "doesn't display the page control if there is only one page", () => {
-		render( <Guide pages={ [ { content: <p>Page 1</p> } ] } /> );
+		render(
+			<Guide
+				{ ...defaultProps }
+				pages={ [ { content: <p>Page 1</p> } ] }
+			/>
+		);
 		expect(
 			screen.queryByRole( 'list', { name: 'Guide controls' } )
 		).not.toBeInTheDocument();
@@ -89,6 +102,7 @@ describe( 'Guide', () => {
 		const onFinish = jest.fn();
 		render(
 			<Guide
+				{ ...defaultProps }
 				onFinish={ onFinish }
 				pages={ [ { content: <p>Page 1</p> } ] }
 			/>
@@ -103,6 +117,7 @@ describe( 'Guide', () => {
 		const onFinish = jest.fn();
 		render(
 			<Guide
+				{ ...defaultProps }
 				onFinish={ onFinish }
 				pages={ [ { content: <p>Page 1</p> } ] }
 			/>
@@ -115,7 +130,7 @@ describe( 'Guide', () => {
 
 	describe( 'page navigation', () => {
 		it( 'renders an empty list when there are no pages', () => {
-			render( <Guide pages={ [] } /> );
+			render( <Guide { ...defaultProps } pages={ [] } /> );
 			expect(
 				screen.queryByRole( 'list', {
 					name: 'Guide controls',
@@ -131,6 +146,7 @@ describe( 'Guide', () => {
 		it( 'renders a button for each page', () => {
 			render(
 				<Guide
+					{ ...defaultProps }
 					pages={ [
 						{ content: <p>Page 1</p> },
 						{ content: <p>Page 2</p> },
@@ -154,6 +170,7 @@ describe( 'Guide', () => {
 
 			render(
 				<Guide
+					{ ...defaultProps }
 					pages={ [
 						{ content: <p>Page 1</p> },
 						{ content: <p>Page 2</p> },
@@ -196,6 +213,7 @@ describe( 'Guide', () => {
 
 			render(
 				<Guide
+					{ ...defaultProps }
 					pages={ [
 						{ content: <p>Page 1</p> },
 						{ content: <p>Page 2</p> },

package/src/guide/types.ts

@@ -0,0 +1,68 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { ModalProps } from '../modal/types';
+
+export type Page = {
+	/**
+	 * Content of the page.
+	 */
+	content: ReactNode;
+	/**
+	 * Image displayed above the page content.
+	 */
+	image?: ReactNode;
+};
+
+export type GuideProps = {
+	/**
+	 * Deprecated. Use `pages` prop instead.
+	 *
+	 * @deprecated since 5.5
+	 */
+	children?: ReactNode;
+	/**
+	 * A custom class to add to the modal.
+	 */
+	className?: string;
+	/**
+	 * Used as the modal's accessibility label.
+	 */
+	contentLabel: ModalProps[ 'contentLabel' ];
+	/**
+	 * Use this to customize the label of the _Finish_ button shown at the end of the guide.
+	 *
+	 * @default 'Finish'
+	 */
+	finishButtonText?: string;
+	/**
+	 * A function which is called when the guide is finished.
+	 */
+	onFinish: ModalProps[ 'onRequestClose' ];
+	/**
+	 * A list of objects describing each page in the guide. Each object **must** contain a `'content'` property and may optionally contain a `'image'` property.
+	 *
+	 * @default []
+	 */
+	pages?: Page[];
+};
+
+export type PageControlProps = {
+	/**
+	 * Current page index.
+	 */
+	currentPage: number;
+	/**
+	 * Total number of pages.
+	 */
+	numberOfPages: number;
+	/**
+	 * Called when user clicks on a `PageControlIcon` button.
+	 */
+	setCurrentPage: ( page: number ) => void;
+};

package/src/h-stack/README.md

@@ -44,8 +44,8 @@ Determines how the child elements are aligned.
 -   `bottom`: Aligns content to the bottom.
 -   `bottomLeft`: Aligns content to the bottom/left.
 -   `bottomRight`: Aligns content to the bottom/right.
--   `edge`: Aligns content to the edges of the container.
--   `stretch`: Stretches content to the edges of the container.
+-   `edge`: Justifies content to be evenly spread out up to the main axis edges of the container.
+-   `stretch`: Stretches content to the cross axis edges of the container.
 
 ##### direction
 

package/src/h-stack/stories/e2e/index.tsx

@@ -0,0 +1,36 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory, ComponentMeta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../../../view';
+import { HStack } from '../..';
+
+const meta: ComponentMeta< typeof HStack > = {
+	component: HStack,
+	title: 'Components (Experimental)/HStack',
+};
+export default meta;
+
+const Template: ComponentStory< typeof HStack > = ( props ) => {
+	return (
+		<HStack
+			style={ { background: '#eee', minHeight: '3rem' } }
+			{ ...props }
+		>
+			{ [ 'One', 'Two', 'Three', 'Four', 'Five' ].map( ( text ) => (
+				<View key={ text } style={ { background: '#b9f9ff' } }>
+					{ text }
+				</View>
+			) ) }
+		</HStack>
+	);
+};
+
+export const Default: ComponentStory< typeof HStack > = Template.bind( {} );
+Default.args = {
+	spacing: 3,
+};

package/src/h-stack/types.ts

@@ -41,8 +41,8 @@ export type Props = Omit< FlexProps, 'align' | 'gap' > & {
 	 * * `bottom`: Aligns content to the bottom.
 	 * * `bottomLeft`: Aligns content to the bottom/left.
 	 * * `bottomRight`: Aligns content to the bottom/right.
-	 * * `edge`: Aligns content to the edges of the container.
-	 * * `stretch`: Stretches content to the edges of the container.
+	 * * `edge`: Justifies content to be evenly spread out up to the main axis edges of the container.
+	 * * `stretch`: Stretches content to the cross axis edges of the container.
 	 *
 	 * @default 'edge'
 	 */

package/src/h-stack/utils.ts

@@ -11,7 +11,7 @@ import { isValueDefined } from '../utils/values';
 
 const H_ALIGNMENTS: Alignments = {
 	bottom: { align: 'flex-end', justify: 'center' },
-	bottomLeft: { align: 'flex-start', justify: 'flex-end' },
+	bottomLeft: { align: 'flex-end', justify: 'flex-start' },
 	bottomRight: { align: 'flex-end', justify: 'flex-end' },
 	center: { align: 'center', justify: 'center' },
 	edge: { align: 'center', justify: 'space-between' },
@@ -25,13 +25,13 @@ const H_ALIGNMENTS: Alignments = {
 
 const V_ALIGNMENTS: Alignments = {
 	bottom: { justify: 'flex-end', align: 'center' },
-	bottomLeft: { justify: 'flex-start', align: 'flex-end' },
+	bottomLeft: { justify: 'flex-end', align: 'flex-start' },
 	bottomRight: { justify: 'flex-end', align: 'flex-end' },
 	center: { justify: 'center', align: 'center' },
 	edge: { justify: 'space-between', align: 'center' },
 	left: { justify: 'center', align: 'flex-start' },
 	right: { justify: 'center', align: 'flex-end' },
-	stretch: { justify: 'stretch' },
+	stretch: { align: 'stretch' },
 	top: { justify: 'flex-start', align: 'center' },
 	topLeft: { justify: 'flex-start', align: 'flex-start' },
 	topRight: { justify: 'flex-start', align: 'flex-end' },

package/src/higher-order/navigate-regions/{index.js → index.tsx}

@@ -8,6 +8,7 @@ import {
 	useMergeRefs,
 } from '@wordpress/compose';
 import { isKeyboardEvent } from '@wordpress/keycodes';
+import type { WPKeycodeModifier } from '@wordpress/keycodes';
 
 const defaultShortcuts = {
 	previous: [
@@ -23,7 +24,7 @@ const defaultShortcuts = {
 			modifier: 'access',
 			character: 'p',
 		},
-	],
+	] as const,
 	next: [
 		{
 			modifier: 'ctrl',
@@ -33,27 +34,36 @@ const defaultShortcuts = {
 			modifier: 'access',
 			character: 'n',
 		},
-	],
+	] as const,
 };
 
-export function useNavigateRegions( shortcuts = defaultShortcuts ) {
-	const ref = useRef();
+type Shortcuts = {
+	previous: readonly { modifier: WPKeycodeModifier; character: string }[];
+	next: readonly { modifier: WPKeycodeModifier; character: string }[];
+};
+
+export function useNavigateRegions( shortcuts: Shortcuts = defaultShortcuts ) {
+	const ref = useRef< HTMLDivElement >( null );
 	const [ isFocusingRegions, setIsFocusingRegions ] = useState( false );
 
-	function focusRegion( offset ) {
+	function focusRegion( offset: number ) {
 		const regions = Array.from(
-			ref.current.querySelectorAll( '[role="region"][tabindex="-1"]' )
+			ref.current?.querySelectorAll< HTMLElement >(
+				'[role="region"][tabindex="-1"]'
+			) ?? []
 		);
 		if ( ! regions.length ) {
 			return;
 		}
 		let nextRegion = regions[ 0 ];
 		// Based off the current element, use closest to determine the wrapping region since this operates up the DOM. Also, match tabindex to avoid edge cases with regions we do not want.
-		const selectedIndex = regions.indexOf(
-			ref.current.ownerDocument.activeElement.closest(
+		const wrappingRegion =
+			ref.current?.ownerDocument?.activeElement?.closest< HTMLElement >(
 				'[role="region"][tabindex="-1"]'
-			)
-		);
+			);
+		const selectedIndex = wrappingRegion
+			? regions.indexOf( wrappingRegion )
+			: -1;
 		if ( selectedIndex !== -1 ) {
 			let nextIndex = selectedIndex + offset;
 			nextIndex = nextIndex === -1 ? regions.length - 1 : nextIndex;
@@ -83,7 +93,7 @@ export function useNavigateRegions( shortcuts = defaultShortcuts ) {
 	return {
 		ref: useMergeRefs( [ ref, clickRef ] ),
 		className: isFocusingRegions ? 'is-focusing-regions' : '',
-		onKeyDown( event ) {
+		onKeyDown( event: React.KeyboardEvent< HTMLDivElement > ) {
 			if (
 				shortcuts.previous.some( ( { modifier, character } ) => {
 					return isKeyboardEvent[ modifier ]( event, character );
@@ -101,6 +111,32 @@ export function useNavigateRegions( shortcuts = defaultShortcuts ) {
 	};
 }
 
+/**
+ * `navigateRegions` is a React [higher-order component](https://facebook.github.io/react/docs/higher-order-components.html)
+ * adding keyboard navigation to switch between the different DOM elements marked as "regions" (role="region").
+ * These regions should be focusable (By adding a tabIndex attribute for example). For better accessibility,
+ * these elements must be properly labelled to briefly describe the purpose of the content in the region.
+ * For more details, see "Landmark Roles" in the [WAI-ARIA specification](https://www.w3.org/TR/wai-aria/)
+ * and "Landmark Regions" in the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/).
+ *
+ * ```jsx
+ * import { navigateRegions } from '@wordpress/components';
+ *
+ * const MyComponentWithNavigateRegions = navigateRegions( () => (
+ * 	<div>
+ * 		<div role="region" tabIndex="-1" aria-label="Header">
+ * 			Header
+ * 		</div>
+ * 		<div role="region" tabIndex="-1" aria-label="Content">
+ * 			Content
+ * 		</div>
+ * 		<div role="region" tabIndex="-1" aria-label="Sidebar">
+ * 			Sidebar
+ * 		</div>
+ * 	</div>
+ * ) );
+ * ```
+ */
 export default createHigherOrderComponent(
 	( Component ) =>
 		( { shortcuts, ...props } ) =>

package/src/higher-order/navigate-regions/style.scss

@@ -24,13 +24,14 @@
 	// visible. For the future, it's important to take into consideration that
 	// the navigable regions should always have a computed size. For now, we can
 	// fix some edge cases but these CSS rules should be later removed in favor of
-	// a more abstracted approach to make the navigabel regions focus style work
+	// a more abstracted approach to make the navigable regions focus style work
 	// regardles of the CSS used on other components.
 
 	// Header top bar when Distraction free mode is on.
 	&.is-distraction-free .interface-interface-skeleton__header .edit-post-header,
 	.interface-interface-skeleton__sidebar .edit-post-layout__toggle-sidebar-panel,
 	.interface-interface-skeleton__actions .edit-post-layout__toggle-publish-panel,
+	.interface-interface-skeleton__actions .edit-post-layout__toggle-entities-saved-states-panel,
 	.editor-post-publish-panel {
 		outline: 4px solid $components-color-accent;
 		outline-offset: -4px;

package/src/higher-order/with-constrained-tabbing/index.tsx

@@ -0,0 +1,30 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	createHigherOrderComponent,
+	useConstrainedTabbing,
+} from '@wordpress/compose';
+
+/**
+ * `withConstrainedTabbing` is a React [higher-order component](https://facebook.github.io/react/docs/higher-order-components.html)
+ * adding the ability to constrain keyboard navigation with the Tab key within a component.
+ * For accessibility reasons, some UI components need to constrain Tab navigation, for example
+ * modal dialogs or similar UI. Use of this component is recommended only in cases where a way to
+ * navigate away from the wrapped component is implemented by other means, usually by pressing
+ * the Escape key or using a specific UI control, e.g. a "Close" button.
+ */
+const withConstrainedTabbing = createHigherOrderComponent(
+	( WrappedComponent ) =>
+		function ComponentWithConstrainedTabbing( props ) {
+			const ref = useConstrainedTabbing();
+			return (
+				<div ref={ ref } tabIndex={ -1 }>
+					<WrappedComponent { ...props } />
+				</div>
+			);
+		},
+	'withConstrainedTabbing'
+);
+
+export default withConstrainedTabbing;

package/src/higher-order/with-fallback-styles/{index.js → index.tsx}

@@ -9,11 +9,28 @@ import fastDeepEqual from 'fast-deep-equal/es6';
 import { Component } from '@wordpress/element';
 import { createHigherOrderComponent } from '@wordpress/compose';
 
-export default ( mapNodeToProps ) =>
+type Props = {
+	node?: HTMLElement;
+	[ key: string ]: any;
+};
+
+type State = {
+	fallbackStyles?: { [ key: string ]: any };
+	grabStylesCompleted: boolean;
+};
+
+export default (
+	mapNodeToProps: (
+		node: HTMLElement,
+		props: Props
+	) => { [ key: string ]: any }
+) =>
 	createHigherOrderComponent( ( WrappedComponent ) => {
-		return class extends Component {
-			constructor() {
-				super( ...arguments );
+		return class extends Component< Props, State > {
+			nodeRef?: HTMLElement;
+
+			constructor( props: Props ) {
+				super( props );
 				this.nodeRef = this.props.node;
 				this.state = {
 					fallbackStyles: undefined,
@@ -23,7 +40,7 @@ export default ( mapNodeToProps ) =>
 				this.bindRef = this.bindRef.bind( this );
 			}
 
-			bindRef( node ) {
+			bindRef( node: HTMLDivElement ) {
 				if ( ! node ) {
 					return;
 				}