@wordpress/components 23.5.0 → 23.7.0

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

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

@@ -12,7 +12,8 @@ describe( 'withSpokenMessages', () => {
 	it( 'should generate speak and debouncedSpeak props', () => {
 		const testSpeak = jest.fn();
 		const testDebouncedSpeak = jest.fn();
-		const isFunction = ( maybeFunc ) => typeof maybeFunc === 'function';
+		const isFunction = ( maybeFunc: any ) =>
+			typeof maybeFunc === 'function';
 		const DumpComponent = withSpokenMessages(
 			( { speak, debouncedSpeak } ) => {
 				testSpeak( isFunction( speak ) );

package/src/icon/index.tsx

@@ -9,7 +9,6 @@ import type { ComponentType, HTMLProps, SVGProps } from 'react';
 import {
 	cloneElement,
 	createElement,
-	Component,
 	isValidElement,
 } from '@wordpress/element';
 import { SVG } from '@wordpress/primitives';
@@ -20,16 +19,20 @@ import { SVG } from '@wordpress/primitives';
 import Dashicon from '../dashicon';
 import type { IconKey as DashiconIconKey } from '../dashicon/types';
 
-export type IconType< P > = DashiconIconKey | ComponentType< P > | JSX.Element;
+export type IconType =
+	| DashiconIconKey
+	| ComponentType< { size?: number } >
+	| ( ( props: { size?: number } ) => JSX.Element )
+	| JSX.Element;
 
-interface BaseProps< P > {
+interface BaseProps {
 	/**
 	 * The icon to render. Supported values are: Dashicons (specified as
 	 * strings), functions, Component instances and `null`.
 	 *
 	 * @default null
 	 */
-	icon?: IconType< P > | null;
+	icon?: IconType | null;
 	/**
 	 * The size (width and height) of the icon.
 	 *
@@ -44,13 +47,13 @@ type AdditionalProps< T > = T extends ComponentType< infer U >
 	? SVGProps< SVGSVGElement >
 	: {};
 
-export type Props< P > = BaseProps< P > & AdditionalProps< IconType< P > >;
+export type Props = BaseProps & AdditionalProps< IconType >;
 
-function Icon< P >( {
+function Icon( {
 	icon = null,
 	size = 'string' === typeof icon ? 20 : 24,
 	...additionalProps
-}: Props< P > ) {
+}: Props ) {
 	if ( 'string' === typeof icon ) {
 		return (
 			<Dashicon
@@ -68,14 +71,7 @@ function Icon< P >( {
 	}
 
 	if ( 'function' === typeof icon ) {
-		if ( icon.prototype instanceof Component ) {
-			return createElement( icon, {
-				size,
-				...additionalProps,
-			} as unknown as P );
-		}
-
-		return ( icon as ( ...args: any[] ) => JSX.Element )( {
+		return createElement( icon, {
 			size,
 			...additionalProps,
 		} );

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

@@ -3,11 +3,15 @@
  */
 import { render, screen } from '@testing-library/react';
 
+/**
+ * WordPress dependencies
+ */
+import { Path, SVG } from '@wordpress/primitives';
+
 /**
  * Internal dependencies
  */
-import Icon from '../';
-import { Path, SVG } from '../../';
+import Icon from '..';
 
 describe( 'Icon', () => {
 	const testId = 'icon';

package/src/index.native.js

@@ -35,6 +35,7 @@ export {
 
 export { default as __experimentalStyleProvider } from './style-provider';
 export { default as BaseControl } from './base-control';
+export { hasSplitBorders as __experimentalHasSplitBorders } from './border-box-control/utils';
 export { default as TextareaControl } from './textarea-control';
 export { default as PanelBody } from './panel/body';
 export { default as PanelActions } from './panel/actions';

package/src/item-group/test/index.js

@@ -1,7 +1,8 @@
 /**
  * External dependencies
  */
-import { fireEvent, render, screen } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 
 /**
  * Internal dependencies
@@ -72,7 +73,8 @@ describe( 'ItemGroup', () => {
 	} );
 
 	describe( 'Item', () => {
-		it( 'should render as a `button` if the `onClick` handler is specified', () => {
+		it( 'should render as a `button` if the `onClick` handler is specified', async () => {
+			const user = userEvent.setup();
 			const spy = jest.fn();
 			render( <Item onClick={ spy }>Code is poetry</Item> );
 
@@ -80,7 +82,7 @@ describe( 'ItemGroup', () => {
 
 			expect( button ).toBeInTheDocument();
 
-			fireEvent.click( button );
+			await user.click( button );
 
 			expect( spy ).toHaveBeenCalled();
 		} );

package/src/mobile/bottom-sheet/bottom-sheet-navigation/test/navigation-container.native.js

@@ -28,7 +28,7 @@ const TestScreen = ( { fullScreen, name, navigateTo } ) => {
 };
 
 beforeAll( () => {
-	jest.useFakeTimers( 'legacy' );
+	jest.useFakeTimers( { legacyFakeTimers: true } );
 } );
 
 afterAll( () => {

package/src/mobile/bottom-sheet/cell.native.js

@@ -234,7 +234,7 @@ class BottomSheetCell extends Component {
 			// we show the TextInput just when the user wants to edit the value,
 			// and the Text component to display it.
 			// We also show the TextInput to display placeholder.
-			const shouldShowPlaceholder = isValueEditable && value === '';
+			const shouldShowPlaceholder = isInteractive && value === '';
 			return this.state.isEditingValue || shouldShowPlaceholder ? (
 				<TextInput
 					ref={ ( c ) => ( this._valueTextInput = c ) }

package/src/mobile/bottom-sheet-text-control/README.md

@@ -64,7 +64,14 @@ A function that receives the value that's input into the text editor.
 
 #### placeholder
 
-The placeholder text that will display in the component's subsheet, when its text editor is empty.
+The placeholder text that will display in the component's cell and subsheet when there is no set value.
+
+-   Type: `String`
+-   Required: No
+
+### cellPlaceholder
+
+The placeholder text that will display in the component's cell when there is no set value. The `cellPlaceholder` will override the more generic placeholder prop when set, enabling the placeholders in the component's cell and subsheet to be different if desired.
 
 -   Type: `String`
 -   Required: No

package/src/mobile/bottom-sheet-text-control/index.native.js

@@ -28,6 +28,7 @@ const BottomSheetTextControl = ( {
 	label,
 	icon,
 	footerNote,
+	cellPlaceholder,
 } ) => {
 	const [ showSubSheet, setShowSubSheet ] = useState( false );
 	const navigation = useNavigation();
@@ -57,10 +58,10 @@ const BottomSheetTextControl = ( {
 			navigationButton={
 				<BottomSheet.Cell
 					icon={ icon }
-					placeholder={ placeholder }
 					label={ label }
 					onPress={ openSubSheet }
 					value={ initialValue || '' }
+					placeholder={ cellPlaceholder || placeholder || '' }
 				>
 					<Icon icon={ chevronRight }></Icon>
 				</BottomSheet.Cell>

package/src/mobile/link-settings/test/link-settings-navigation.native.js

@@ -10,7 +10,7 @@ import { render, fireEvent, waitFor } from 'test/helpers';
 import LinkSettingsNavigation from '../link-settings-navigation';
 
 beforeAll( () => {
-	jest.useFakeTimers( 'legacy' );
+	jest.useFakeTimers( { legacyFakeTimers: true } );
 } );
 
 afterAll( () => {

package/src/navigation/README.md

@@ -122,7 +122,7 @@ The unique identifier of the menu. The root menu can omit this, and it will defa
 
 ### onSearch
 
--   Type: `function`
+-   Type: `( searchString: string ) => void;`
 -   Required: No
 
 When `hasSearch` is active, this function handles the search input's `onChange` event, making it controlled from the outside. It requires setting the `search` prop as well.
@@ -162,6 +162,13 @@ Indicates whether the menu is empty or not. Used together with the `hideIfTarget
 
 The menu title. It's also the field used by the menu search function.
 
+### `titleAction`
+
+-   Type: `React.ReactNode`
+-   Required: No
+
+Use this prop to render additional actions in the menu title.
+
 ## Navigation Group Props
 
 `NavigationGroup` supports the following props.
@@ -205,6 +212,13 @@ Optional className for the `NavigationItem` component.
 
 If provided, renders `a` instead of `button`.
 
+### `icon`
+
+-   Type: `JSX.Element`
+-   Required: No
+
+If no `children` are passed, this prop allows to specify a custom icon for the menu item.
+
 ### `item`
 
 -   Type: `string`
@@ -228,7 +242,7 @@ Indicates whether this item should be hidden if the menu specified in `navigateT
 
 ### `onClick`
 
--   Type: `function`
+-   Type: `React.MouseEventHandler`
 -   Required: No
 
 A callback to handle clicking on a menu item.

package/src/navigation/back-button/{index.js → index.tsx}

@@ -15,9 +15,17 @@ import { Icon, chevronLeft, chevronRight } from '@wordpress/icons';
 import { useNavigationContext } from '../context';
 import { MenuBackButtonUI } from '../styles/navigation-styles';
 
-function NavigationBackButton(
-	{ backButtonLabel, className, href, onClick, parentMenu },
-	ref
+import type { NavigationBackButtonProps } from '../types';
+
+function UnforwardedNavigationBackButton(
+	{
+		backButtonLabel,
+		className,
+		href,
+		onClick,
+		parentMenu,
+	}: NavigationBackButtonProps,
+	ref: React.ForwardedRef< HTMLAnchorElement | HTMLButtonElement >
 ) {
 	const { setActiveMenu, navigationTree } = useNavigationContext();
 
@@ -26,9 +34,12 @@ function NavigationBackButton(
 		className
 	);
 
-	const parentMenuTitle = navigationTree.getMenu( parentMenu )?.title;
+	const parentMenuTitle =
+		parentMenu !== undefined
+			? navigationTree.getMenu( parentMenu )?.title
+			: undefined;
 
-	const handleOnClick = ( event ) => {
+	const handleOnClick: React.MouseEventHandler< HTMLElement > = ( event ) => {
 		if ( typeof onClick === 'function' ) {
 			onClick( event );
 		}
@@ -52,4 +63,9 @@ function NavigationBackButton(
 		</MenuBackButtonUI>
 	);
 }
-export default forwardRef( NavigationBackButton );
+
+export const NavigationBackButton = forwardRef(
+	UnforwardedNavigationBackButton
+);
+
+export default NavigationBackButton;

package/src/navigation/{context.js → context.tsx}

@@ -8,27 +8,30 @@ import { createContext, useContext } from '@wordpress/element';
  */
 import { ROOT_MENU } from './constants';
 
+import type { NavigationContext as NavigationContextType } from './types';
+
 const noop = () => {};
+const defaultIsEmpty = () => false;
+const defaultGetter = () => undefined;
 
-export const NavigationContext = createContext( {
+export const NavigationContext = createContext< NavigationContextType >( {
 	activeItem: undefined,
 	activeMenu: ROOT_MENU,
 	setActiveMenu: noop,
-	isMenuEmpty: noop,
 
 	navigationTree: {
 		items: {},
-		getItem: noop,
+		getItem: defaultGetter,
 		addItem: noop,
 		removeItem: noop,
 
 		menus: {},
-		getMenu: noop,
+		getMenu: defaultGetter,
 		addMenu: noop,
 		removeMenu: noop,
 		childMenu: {},
 		traverseMenu: noop,
-		isMenuEmpty: noop,
+		isMenuEmpty: defaultIsEmpty,
 	},
 } );
 export const useNavigationContext = () => useContext( NavigationContext );

package/src/navigation/group/context.tsx

@@ -0,0 +1,15 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { NavigationGroupContext as NavigationGroupContextType } from '../types';
+
+export const NavigationGroupContext =
+	createContext< NavigationGroupContextType >( { group: undefined } );
+
+export const useNavigationGroupContext = () =>
+	useContext( NavigationGroupContext );

package/src/navigation/group/{index.js → index.tsx}

@@ -15,9 +15,15 @@ import { NavigationGroupContext } from './context';
 import { GroupTitleUI } from '../styles/navigation-styles';
 import { useNavigationContext } from '../context';
 
+import type { NavigationGroupProps } from '../types';
+
 let uniqueId = 0;
 
-export default function NavigationGroup( { children, className, title } ) {
+export function NavigationGroup( {
+	children,
+	className,
+	title,
+}: NavigationGroupProps ) {
 	const [ groupId ] = useState( `group-${ ++uniqueId }` );
 	const {
 		navigationTree: { items },
@@ -60,3 +66,5 @@ export default function NavigationGroup( { children, className, title } ) {
 		</NavigationGroupContext.Provider>
 	);
 }
+
+export default NavigationGroup;

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

@@ -18,21 +18,70 @@ import { NavigationContext } from './context';
 import { NavigationUI } from './styles/navigation-styles';
 import { useCreateNavigationTree } from './use-create-navigation-tree';
 
+import type {
+	NavigationProps,
+	NavigationContext as NavigationContextType,
+} from './types';
+
 const noop = () => {};
 
-export default function Navigation( {
+/**
+ * Render a navigation list with optional groupings and hierarchy.
+ *
+ * @example
+ * ```jsx
+ * import {
+ *   __experimentalNavigation as Navigation,
+ *   __experimentalNavigationGroup as NavigationGroup,
+ *   __experimentalNavigationItem as NavigationItem,
+ *   __experimentalNavigationMenu as NavigationMenu,
+ * } from '@wordpress/components';
+ *
+ * const MyNavigation = () => (
+ *   <Navigation>
+ *     <NavigationMenu title="Home">
+ *       <NavigationGroup title="Group 1">
+ *         <NavigationItem item="item-1" title="Item 1" />
+ *         <NavigationItem item="item-2" title="Item 2" />
+ *       </NavigationGroup>
+ *       <NavigationGroup title="Group 2">
+ *         <NavigationItem
+ *           item="item-3"
+ *           navigateToMenu="category"
+ *           title="Category"
+ *         />
+ *       </NavigationGroup>
+ *     </NavigationMenu>
+ *
+ *     <NavigationMenu
+ *       backButtonLabel="Home"
+ *       menu="category"
+ *       parentMenu="root"
+ *       title="Category"
+ *     >
+ *       <NavigationItem badge="1" item="child-1" title="Child 1" />
+ *       <NavigationItem item="child-2" title="Child 2" />
+ *     </NavigationMenu>
+ *   </Navigation>
+ * );
+ * ```
+ */
+export function Navigation( {
 	activeItem,
 	activeMenu = ROOT_MENU,
 	children,
 	className,
 	onActivateMenu = noop,
-} ) {
+}: NavigationProps ) {
 	const [ menu, setMenu ] = useState( activeMenu );
-	const [ slideOrigin, setSlideOrigin ] = useState();
+	const [ slideOrigin, setSlideOrigin ] = useState< 'left' | 'right' >();
 	const navigationTree = useCreateNavigationTree();
 	const defaultSlideOrigin = isRTL() ? 'right' : 'left';
 
-	const setActiveMenu = ( menuId, slideInOrigin = defaultSlideOrigin ) => {
+	const setActiveMenu: NavigationContextType[ 'setActiveMenu' ] = (
+		menuId,
+		slideInOrigin = defaultSlideOrigin
+	) => {
 		if ( ! navigationTree.getMenu( menuId ) ) {
 			return;
 		}
@@ -76,9 +125,14 @@ export default function Navigation( {
 		<NavigationUI className={ classes }>
 			<div
 				key={ menu }
-				className={ classnames( {
-					[ animateClassName ]: isMounted.current && slideOrigin,
-				} ) }
+				className={
+					animateClassName
+						? classnames( {
+								[ animateClassName ]:
+									isMounted.current && slideOrigin,
+						  } )
+						: undefined
+				}
 			>
 				<NavigationContext.Provider value={ context }>
 					{ children }
@@ -87,3 +141,5 @@ export default function Navigation( {
 		</NavigationUI>
 	);
 }
+
+export default Navigation;