@wordpress/components 23.5.0 → 23.6.0

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/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/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;
 				}

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

@@ -13,11 +13,37 @@ const ANIMATION_FRAME_PERIOD = 16;
  * to be mounted. When a filter is added or removed that matches the hook name,
  * the wrapped component re-renders.
  *
- * @param {string} hookName Hook name exposed to be used by filters.
+ * @param hookName Hook name exposed to be used by filters.
  *
- * @return {Function} Higher-order component factory.
+ * @return Higher-order component factory.
+ *
+ * ```jsx
+ * import { withFilters } from '@wordpress/components';
+ * import { addFilter } from '@wordpress/hooks';
+ *
+ * const MyComponent = ( { title } ) => <h1>{ title }</h1>;
+ *
+ * const ComponentToAppend = () => <div>Appended component</div>;
+ *
+ * function withComponentAppended( FilteredComponent ) {
+ * 	return ( props ) => (
+ * 		<>
+ * 			<FilteredComponent { ...props } />
+ * 			<ComponentToAppend />
+ * 		</>
+ * 	);
+ * }
+ *
+ * addFilter(
+ * 	'MyHookName',
+ * 	'my-plugin/with-component-appended',
+ * 	withComponentAppended
+ * );
+ *
+ * const MyComponentWithFilters = withFilters( 'MyHookName' )( MyComponent );
+ * ```
  */
-export default function withFilters( hookName ) {
+export default function withFilters( hookName: string ) {
 	return createHigherOrderComponent( ( OriginalComponent ) => {
 		const namespace = 'core/with-filters/' + hookName;
 
@@ -25,10 +51,8 @@ export default function withFilters( hookName ) {
 		 * The component definition with current filters applied. Each instance
 		 * reuse this shared reference as an optimization to avoid excessive
 		 * calls to `applyFilters` when many instances exist.
-		 *
-		 * @type {?Component}
 		 */
-		let FilteredComponent;
+		let FilteredComponent: React.ComponentType;
 
 		/**
 		 * Initializes the FilteredComponent variable once, if not already
@@ -36,13 +60,18 @@ export default function withFilters( hookName ) {
 		 */
 		function ensureFilteredComponent() {
 			if ( FilteredComponent === undefined ) {
-				FilteredComponent = applyFilters( hookName, OriginalComponent );
+				FilteredComponent = applyFilters(
+					hookName,
+					OriginalComponent
+				) as React.ComponentType;
 			}
 		}
 
 		class FilteredComponentRenderer extends Component {
-			constructor() {
-				super( ...arguments );
+			static instances: FilteredComponentRenderer[];
+
+			constructor( props: { [ key: string ]: any } ) {
+				super( props );
 
 				ensureFilteredComponent();
 			}
@@ -86,7 +115,10 @@ export default function withFilters( hookName ) {
 		const throttledForceUpdate = debounce( () => {
 			// Recreate the filtered component, only after delay so that it's
 			// computed once, even if many filters added.
-			FilteredComponent = applyFilters( hookName, OriginalComponent );
+			FilteredComponent = applyFilters(
+				hookName,
+				OriginalComponent
+			) as React.ComponentType;
 
 			// Force each instance to render.
 			FilteredComponentRenderer.instances.forEach( ( instance ) => {
@@ -99,9 +131,9 @@ export default function withFilters( hookName ) {
 		 * mounted instance should re-render with the new filters having been
 		 * applied to the original component.
 		 *
-		 * @param {string} updatedHookName Name of the hook that was updated.
+		 * @param updatedHookName Name of the hook that was updated.
 		 */
-		function onHooksUpdated( updatedHookName ) {
+		function onHooksUpdated( updatedHookName: string ) {
 			if ( updatedHookName === hookName ) {
 				throttledForceUpdate();
 			}

package/src/higher-order/with-filters/test/{index.js → index.tsx}

@@ -18,7 +18,11 @@ describe( 'withFilters', () => {
 	const MyComponent = () => <div>My component</div>;
 
 	afterEach( () => {
-		removeAllFilters( hookName );
+		removeAllFilters( hookName, 'test/enhanced-component-override' );
+		removeAllFilters( hookName, 'test/enhanced-component-compose' );
+		removeAllFilters( hookName, 'test/enhanced-component-spy' );
+		removeAllFilters( hookName, 'test/enhanced-component-spy-1' );
+		removeAllFilters( hookName, 'test/enhanced-component-spy-2' );
 	} );
 
 	it( 'should display original component when no filters applied', () => {

package/src/higher-order/with-focus-return/index.tsx

@@ -0,0 +1,74 @@
+/**
+ * WordPress dependencies
+ */
+import { Component } from '@wordpress/element';
+import { createHigherOrderComponent, useFocusReturn } from '@wordpress/compose';
+import deprecated from '@wordpress/deprecated';
+
+/**
+ * Returns true if the given object is component-like. An object is component-
+ * like if it is an instance of wp.element.Component, or is a function.
+ *
+ * @param object Object to test.
+ *
+ * @return Whether object is component-like.
+ */
+function isComponentLike( object: any ): object is React.ComponentType {
+	return object instanceof Component || typeof object === 'function';
+}
+
+type Props = {
+	onFocusReturn?: () => void;
+};
+
+/**
+ * Higher Order Component used to be used to wrap disposable elements like
+ * sidebars, modals, dropdowns. When mounting the wrapped component, we track a
+ * reference to the current active element so we know where to restore focus
+ * when the component is unmounted.
+ *
+ * @param options The component to be enhanced with
+ *                focus return behavior, or an object
+ *                describing the component and the
+ *                focus return characteristics.
+ *
+ * @return Higher Order Component with the focus restauration behaviour.
+ */
+export default createHigherOrderComponent(
+	// @ts-expect-error TODO: Reconcile with intended `createHigherOrderComponent` types
+	( options: WPComponent | Record< string, unknown > ) => {
+		const HoC =
+			( { onFocusReturn }: Props = {} ) =>
+			( WrappedComponent: React.ComponentType ) => {
+				const WithFocusReturn = (
+					props: Record< string, unknown >
+				) => {
+					const ref = useFocusReturn( onFocusReturn );
+					return (
+						<div ref={ ref }>
+							<WrappedComponent { ...props } />
+						</div>
+					);
+				};
+
+				return WithFocusReturn;
+			};
+
+		if ( isComponentLike( options ) ) {
+			const WrappedComponent = options;
+			return HoC()( WrappedComponent );
+		}
+
+		return HoC( options );
+	},
+	'withFocusReturn'
+);
+
+export const Provider = ( { children }: { children: React.ReactNode } ) => {
+	deprecated( 'wp.components.FocusReturnProvider component', {
+		since: '5.7',
+		hint: 'This provider is not used anymore. You can just remove it from your codebase',
+	} );
+
+	return children;
+};

package/src/higher-order/with-focus-return/test/{index.js → index.tsx}

@@ -12,9 +12,9 @@ import { Component } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import withFocusReturn from '../';
+import withFocusReturn from '..';
 
-class Test extends Component {
+class Test extends Component< { className: string; focusHistory: unknown } > {
 	render() {
 		const { className, focusHistory } = this.props;
 		return (

package/src/higher-order/with-notices/README.md

@@ -2,7 +2,7 @@
 
 `withNotices` is a React [higher-order component](https://facebook.github.io/react/docs/higher-order-components.html) used typically in adding the ability to post notice messages within the original component.
 
-Wrapping the original component with `withNotices` encapsulates the component with the additional props `noticeOperations` and `noticeUI`.
+Wrapping the original component with `withNotices` encapsulates the component with the additional props `noticeOperations`, `noticeUI`, and `noticeList`.
 
 **noticeOperations**
 Contains a number of useful functions to add notices to your site.
@@ -34,6 +34,9 @@ _Parameters_
 <a  name="noticeUi"  href="#noticeUi">#</a>**noticeUi**
 The rendered `NoticeList`.
 
+<a  name="noticeList"  href="#noticeList">#</a>**noticeList**
+The array of notice objects to be displayed.
+
 ## Usage
 
 ```jsx

package/src/higher-order/with-notices/index.tsx

@@ -0,0 +1,116 @@
+/**
+ * External dependencies
+ */
+import { v4 as uuid } from 'uuid';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef, useState, useMemo } from '@wordpress/element';
+import { createHigherOrderComponent } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import NoticeList from '../../notice/list';
+import type { WithNoticeProps } from './types';
+
+/**
+ * Override the default edit UI to include notices if supported.
+ *
+ * Wrapping the original component with `withNotices` encapsulates the component
+ * with the additional props `noticeOperations` and `noticeUI`.
+ *
+ * ```jsx
+ * import { withNotices, Button } from '@wordpress/components';
+ *
+ * const MyComponentWithNotices = withNotices(
+ * 	( { noticeOperations, noticeUI } ) => {
+ * 		const addError = () =>
+ * 			noticeOperations.createErrorNotice( 'Error message' );
+ * 		return (
+ * 			<div>
+ * 				{ noticeUI }
+ * 				<Button variant="secondary" onClick={ addError }>
+ * 					Add error
+ * 				</Button>
+ * 			</div>
+ * 		);
+ * 	}
+ * );
+ * ```
+ *
+ * @param OriginalComponent Original component.
+ *
+ * @return Wrapped component.
+ */
+export default createHigherOrderComponent( ( OriginalComponent ) => {
+	function Component(
+		props: { [ key: string ]: any },
+		ref: React.ForwardedRef< any >
+	) {
+		const [ noticeList, setNoticeList ] = useState<
+			WithNoticeProps[ 'noticeList' ]
+		>( [] );
+
+		const noticeOperations = useMemo<
+			WithNoticeProps[ 'noticeOperations' ]
+		>( () => {
+			const createNotice: WithNoticeProps[ 'noticeOperations' ][ 'createNotice' ] =
+				( notice ) => {
+					const noticeToAdd = notice.id
+						? notice
+						: { ...notice, id: uuid() };
+					setNoticeList( ( current ) => [ ...current, noticeToAdd ] );
+				};
+
+			return {
+				createNotice,
+				createErrorNotice: ( msg ) => {
+					// @ts-expect-error TODO: Missing `id`, potentially a bug
+					createNotice( {
+						status: 'error',
+						content: msg,
+					} );
+				},
+				removeNotice: ( id ) => {
+					setNoticeList( ( current ) =>
+						current.filter( ( notice ) => notice.id !== id )
+					);
+				},
+				removeAllNotices: () => {
+					setNoticeList( [] );
+				},
+			};
+		}, [] );
+
+		const propsOut = {
+			...props,
+			noticeList,
+			noticeOperations,
+			noticeUI: noticeList.length > 0 && (
+				<NoticeList
+					className="components-with-notices-ui"
+					notices={ noticeList }
+					onRemove={ noticeOperations.removeNotice }
+				/>
+			),
+		};
+
+		return isForwardRef ? (
+			<OriginalComponent { ...propsOut } ref={ ref } />
+		) : (
+			<OriginalComponent { ...propsOut } />
+		);
+	}
+
+	let isForwardRef: boolean;
+	// @ts-expect-error - `render` will only be present when OriginalComponent was wrapped with forwardRef().
+	const { render } = OriginalComponent;
+	// Returns a forwardRef if OriginalComponent appears to be a forwardRef.
+	if ( typeof render === 'function' ) {
+		isForwardRef = true;
+		return forwardRef( Component );
+	}
+	return Component;
+}, 'withNotices' );

package/src/higher-order/with-notices/test/{index.js → index.tsx}

@@ -24,25 +24,30 @@ import {
  * Internal dependencies
  */
 import withNotices from '..';
+import type { WithNoticeProps } from '../types';
 
 // Implementation detail of Notice component used to query the dismissal button.
 const stockDismissText = 'Dismiss this notice';
 
-function noticesFrom( list ) {
+function noticesFrom( list: string[] ) {
 	return list.map( ( item ) => ( { id: item, content: item } ) );
 }
 
-function isComponentLike( object ) {
+function isComponentLike( object: any ) {
 	return typeof object === 'function';
 }
 
-function isForwardRefLike( { render: renderMethod } ) {
+function isForwardRefLike( { render: renderMethod }: any ) {
 	return typeof renderMethod === 'function';
 }
 
 const content = 'Base content';
 
-const BaseComponent = ( { noticeOperations, noticeUI, notifications } ) => {
+const BaseComponent = ( {
+	noticeOperations,
+	noticeUI,
+	notifications,
+}: WithNoticeProps & { notifications: ReturnType< typeof noticesFrom > } ) => {
 	useEffect( () => {
 		if ( notifications ) {
 			notifications.forEach( ( item ) =>
@@ -78,8 +83,8 @@ describe( 'withNotices return type', () => {
 } );
 
 describe( 'withNotices operations', () => {
-	let handle;
-	const Handle = ( props ) => {
+	let handle: React.MutableRefObject< any >;
+	const Handle = ( props: any ) => {
 		handle = useRef();
 		return <TestNoticeOperations { ...props } ref={ handle } />;
 	};

package/src/higher-order/with-notices/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Internal dependencies
+ */
+import type { NoticeListProps } from '../../notice/types';
+
+export type WithNoticeProps = {
+	noticeList: NoticeListProps[ 'notices' ];
+	noticeOperations: {
+		/**
+		 * Function passed down as a prop that adds a new notice.
+		 *
+		 * @param notice Notice to add.
+		 */
+		createNotice: (
+			notice: NoticeListProps[ 'notices' ][ number ]
+		) => void;
+		/**
+		 * Function passed as a prop that adds a new error notice.
+		 *
+		 * @param msg Error message of the notice.
+		 */
+		createErrorNotice: ( msg: string ) => void;
+		/**
+		 * Removes a notice by id.
+		 *
+		 * @param id Id of the notice to remove.
+		 */
+		removeNotice: ( id: string ) => void;
+		/**
+		 * Removes all notices
+		 */
+		removeAllNotices: () => void;
+	};
+	noticeUI: false | JSX.Element;
+};