@wordpress/components 23.5.0 → 23.6.0

package/src/navigation/types.ts

@@ -0,0 +1,325 @@
+/**
+ * Internal dependencies
+ */
+import type { ButtonProps } from '../button/types';
+
+type IfDiscriminantDefinedBothRequired< TDiscriminant, TOther > =
+	// When props in TDiscriminant are specified,
+	// then props from TOther are required too
+	| {
+			[ K in keyof ( TDiscriminant & TOther ) ]: NonNullable<
+				( TDiscriminant & TOther )[ K ]
+			>;
+	  }
+	// When props in TDiscriminant are not specified,
+	// then props from TOther are optional
+	| ( {
+			[ K in keyof TDiscriminant ]?: never;
+	  } & {
+			[ K in keyof TOther ]?: TOther[ K ];
+	  } );
+
+// React Components
+
+export type NavigationProps = {
+	/**
+	 * The active item slug.
+	 */
+	activeItem?: string;
+	/**
+	 * The active menu slug.
+	 *
+	 * @default 'root'
+	 */
+	activeMenu?: string;
+	/**
+	 * The children components.
+	 */
+	children?: React.ReactNode;
+	/**
+	 * Optional classname for the component.
+	 */
+	className?: string;
+	/**
+	 * Callback used to sync the active menu between the external state
+	 * and the Navigation's internal state.
+	 */
+	onActivateMenu?: ( activeMenuSlug: string ) => void;
+};
+
+// When `onSearch` is specified, `search` should be specified too
+type _NavigationMenuSearchProps = IfDiscriminantDefinedBothRequired<
+	{
+		/**
+		 * When the `hasSearch` prop is `true`, this callback handles the search
+		 * input's `onChange` event, making it controlled from the outside.
+		 * When using this prop, the `search` prop should be also set.
+		 */
+		onSearch: ( searchString: string ) => void;
+	},
+	{
+		/**
+		 * When the `hasSearch` is `true` and the `onSearch` prop is provided, this
+		 * prop controls the value of the search input.
+		 * Required when the `onSearch` prop is provided.
+		 */
+		search: string;
+	}
+>;
+
+export type NavigationMenuProps = _NavigationMenuSearchProps & {
+	/**
+	 * The back button label used in nested menus.
+	 * If not provided, the label will be inferred from the parent menu's title.
+	 * If the parent menu's title is not available then it will default to "Back".
+	 *
+	 * @default parentMenuTitle ?? 'Back'
+	 */
+	backButtonLabel?: string;
+	/**
+	 * A callback to handle clicking on the back button.
+	 * If this prop is provided then the back button will be shown.
+	 */
+	onBackButtonClick?: React.MouseEventHandler< HTMLElement >;
+	/**
+	 * The children components.
+	 */
+	children?: React.ReactNode;
+	/**
+	 * Optional classname for the component.
+	 */
+	className?: string;
+	/**
+	 * When `true`, enables the search feature on the menu title.
+	 */
+	hasSearch?: boolean;
+	/**
+	 * Indicates whether the menu is empty or not. Used together with the
+	 * `hideIfTargetMenuEmpty` prop of `NavigationItem`.
+	 */
+	isEmpty?: boolean;
+	/**
+	 * Indicates whether the search is debouncing or not. In case of `true`, the
+	 * "No results found." text is omitted. Used to prevent showing the
+	 * "No results found." text between debounced searches.
+	 */
+	isSearchDebouncing?: boolean;
+	/**
+	 * The unique identifier of the menu.
+	 * The root menu can omit this prop, and it will default to "root".
+	 * All other menus need to specify it.
+	 *
+	 * @default 'root'
+	 */
+	menu?: string;
+	/**
+	 * The parent menu slug; used by nested menus to indicate their parent menu.
+	 */
+	parentMenu?: string;
+	/**
+	 * The menu title. It's also the field used by the menu search function.
+	 */
+	title?: string;
+	/**
+	 * Use this prop to render additional actions in the menu title.
+	 */
+	titleAction?: React.ReactNode;
+};
+
+export type NavigationGroupProps = {
+	/**
+	 * Optional classname for the component.
+	 */
+	className?: string;
+	/**
+	 * The group title.
+	 */
+	title?: string;
+	/**
+	 * The children components.
+	 */
+	children: React.ReactNode;
+};
+
+type _NavigationItemButtonProps =
+	| ( ButtonProps & {
+			/**
+			 * If set to `true` the menu item will only act as a text-only item,
+			 * rather than a `<button />` or `<a />` element.
+			 */
+			isText?: false;
+	  } )
+	| {
+			/**
+			 * If set to `true` the menu item will only act as a text-only item,
+			 * rather than a `<button />` or `<a />` element.
+			 */
+			isText: true;
+	  };
+
+export type NavigationItemBaseProps = {
+	/**
+	 * The item badge content.
+	 */
+	badge?: string | number;
+	/**
+	 * The children components. When not specified, the item will render the
+	 * default item UI.
+	 */
+	children?: React.ReactNode;
+	/**
+	 * Optional classname for the component.
+	 */
+	className?: string;
+	/**
+	 * If provided, causes the component to render an `<a />` element
+	 * instead of a `<button />` element.
+	 */
+	href?: string;
+	/**
+	 * If no `children` are passed, this prop allows to specify a custom icon for
+	 * the menu item.
+	 */
+	icon?: JSX.Element;
+	/**
+	 * The unique identifier of the item.
+	 */
+	item?: string;
+	/**
+	 * The child menu slug. If provided, clicking on the item will navigate
+	 * to the target menu.
+	 */
+	navigateToMenu?: string;
+	/**
+	 * Indicates whether this item should be hidden if the menu specified in
+	 * `navigateToMenu` is marked as empty in the `isEmpty` prop.
+	 * Used together with the `isEmpty` prop of `NavigationMenu`.
+	 */
+	hideIfTargetMenuEmpty?: boolean;
+	/**
+	 * A callback to handle clicking on a menu item.
+	 *
+	 * @default noop
+	 */
+	onClick?: React.MouseEventHandler;
+	/**
+	 * The item title.
+	 */
+	title?: string;
+};
+
+export type NavigationItemProps = _NavigationItemButtonProps &
+	NavigationItemBaseProps;
+
+export type NavigationItemBaseContentProps = Pick<
+	NavigationItemProps,
+	'badge' | 'title'
+>;
+
+export type NavigationBackButtonProps = {
+	/**
+	 * The text displayed for the button
+	 */
+	backButtonLabel?: string;
+	/**
+	 * Optional classname for the component.
+	 */
+	className?: string;
+	/**
+	 * If provided, causes the component to render an `<a />` element
+	 * instead of a `<button />` element.
+	 */
+	href?: string;
+	/**
+	 * Callback function called when the button is clicked.
+	 */
+	onClick?: React.MouseEventHandler;
+	/**
+	 * Id of the parent menu
+	 */
+	parentMenu?: string;
+};
+
+export type NavigationMenuTitleSearchProps = Pick<
+	NavigationMenuProps,
+	'onSearch' | 'search' | 'title'
+> & {
+	// @see `speak` function from `@wordpress/a11y`
+	debouncedSpeak: (
+		message: string,
+		ariaLive?: 'off' | 'polite' | 'assertive'
+	) => void;
+	onCloseSearch: () => void;
+};
+
+export type NavigationMenuTitleProps = Pick<
+	NavigationMenuProps,
+	'hasSearch' | 'onSearch' | 'search' | 'title' | 'titleAction'
+>;
+
+export type NavigationSearchNoResultsFoundProps = Pick<
+	NavigationMenuProps,
+	'search'
+>;
+
+// Data objects & context
+
+export type Item = Omit< NavigationItemBaseProps, 'children' > & {
+	/**
+	 * The group id
+	 */
+	group?: string;
+	/**
+	 * The menu id
+	 */
+	menu?: string;
+	/**
+	 * True is the item is currently visible (ie. the item is part
+	 * of the active menu, and — if there is a search query — its title
+	 * matches the search query).
+	 */
+	_isVisible: boolean;
+};
+
+export type Menu = Omit< NavigationMenuProps, 'children' > & {
+	menu: string;
+};
+
+export type NavigationGroupContext = {
+	/**
+	 * The unique id of the group
+	 */
+	group?: string;
+};
+
+export type NavigationMenuContext = {
+	menu?: string;
+	search?: string;
+};
+
+export type NavigationContext = {
+	activeItem?: string;
+	activeMenu: string;
+	setActiveMenu: (
+		parentMenu: string,
+		animationDirection?: 'left' | 'right'
+	) => void;
+
+	navigationTree: {
+		items: Record< string, Item >;
+		getItem: ( itemId: string ) => Item | undefined;
+		addItem: ( itemId: string, itemProps: Item ) => void;
+		removeItem: ( itemId: string ) => void;
+
+		menus: Record< string, Menu >;
+		getMenu: ( menuId: string ) => Menu | undefined;
+		addMenu: ( menuId: string, menuProps: Menu ) => void;
+		removeMenu: ( menuId: string ) => void;
+		childMenu: Record< string, string[] >;
+		traverseMenu: (
+			startMenu: string,
+			callback: ( menuObject: Menu ) => boolean | undefined
+		) => void;
+		isMenuEmpty: ( menuId: string ) => boolean;
+	};
+};

package/src/navigation/{use-create-navigation-tree.js → use-create-navigation-tree.tsx}

@@ -8,20 +8,22 @@ import { useState } from '@wordpress/element';
  */
 import { useNavigationTreeNodes } from './use-navigation-tree-nodes';
 
+import type { NavigationContext, Item, Menu } from './types';
+
 export const useCreateNavigationTree = () => {
 	const {
 		nodes: items,
 		getNode: getItem,
 		addNode: addItem,
 		removeNode: removeItem,
-	} = useNavigationTreeNodes();
+	} = useNavigationTreeNodes< Item >();
 
 	const {
 		nodes: menus,
 		getNode: getMenu,
 		addNode: addMenu,
 		removeNode: removeMenu,
-	} = useNavigationTreeNodes();
+	} = useNavigationTreeNodes< Menu >();
 
 	/**
 	 * Stores direct nested menus of menus
@@ -30,38 +32,44 @@ export const useCreateNavigationTree = () => {
 	 * Key is the menu prop of the menu
 	 * Value is an array of menu keys
 	 */
-	const [ childMenu, setChildMenu ] = useState( {} );
-	const getChildMenu = ( menu ) => childMenu[ menu ] || [];
-
-	const traverseMenu = ( startMenu, callback ) => {
-		const visited = [];
-		let queue = [ startMenu ];
-		let current;
-
-		while ( queue.length > 0 ) {
-			current = getMenu( queue.shift() );
-
-			if ( ! current || visited.includes( current.menu ) ) {
-				continue;
-			}
+	const [ childMenu, setChildMenu ] = useState< Record< string, string[] > >(
+		{}
+	);
+	const getChildMenu = ( menu: string ) => childMenu[ menu ] || [];
+
+	const traverseMenu: NavigationContext[ 'navigationTree' ][ 'traverseMenu' ] =
+		( startMenu, callback ) => {
+			const visited: string[] = [];
+			let queue = [ startMenu ];
+			let current: Menu;
+
+			while ( queue.length > 0 ) {
+				// Type cast to string is safe because of the `length > 0` check above.
+				current = getMenu( queue.shift() as string );
+
+				if ( ! current || visited.includes( current.menu ) ) {
+					continue;
+				}
 
-			visited.push( current.menu );
-			queue = [ ...queue, ...getChildMenu( current.menu ) ];
+				visited.push( current.menu );
+				queue = [ ...queue, ...getChildMenu( current.menu ) ];
 
-			if ( callback( current ) === false ) {
-				break;
+				if ( callback( current ) === false ) {
+					break;
+				}
 			}
-		}
-	};
+		};
 
-	const isMenuEmpty = ( menuToCheck ) => {
+	const isMenuEmpty = ( menuToCheck: string ) => {
 		let isEmpty = true;
 
-		traverseMenu( menuToCheck, ( current ) => {
+		traverseMenu( menuToCheck, ( current: Menu ) => {
 			if ( ! current.isEmpty ) {
 				isEmpty = false;
 				return false;
 			}
+
+			return undefined;
 		} );
 
 		return isEmpty;
@@ -75,10 +83,14 @@ export const useCreateNavigationTree = () => {
 
 		menus,
 		getMenu,
-		addMenu: ( key, value ) => {
+		addMenu: ( key: string, value: Menu ) => {
 			setChildMenu( ( state ) => {
 				const newState = { ...state };
 
+				if ( ! value.parentMenu ) {
+					return newState;
+				}
+
 				if ( ! newState[ value.parentMenu ] ) {
 					newState[ value.parentMenu ] = [];
 				}

package/src/navigation/{use-navigation-tree-nodes.js → use-navigation-tree-nodes.tsx}

@@ -3,12 +3,16 @@
  */
 import { useState } from '@wordpress/element';
 
-export const useNavigationTreeNodes = () => {
-	const [ nodes, setNodes ] = useState( {} );
+export function useNavigationTreeNodes<
+	TNode extends { children?: React.ReactNode; [ key: string ]: unknown }
+>() {
+	const [ nodes, setNodes ] = useState<
+		Record< string, Omit< TNode, 'children' > >
+	>( {} );
 
-	const getNode = ( key ) => nodes[ key ];
+	const getNode = ( key: string ) => nodes[ key ];
 
-	const addNode = ( key, value ) => {
+	const addNode = ( key: string, value: TNode ) => {
 		const { children, ...newNode } = value;
 		return setNodes( ( original ) => ( {
 			...original,
@@ -16,7 +20,7 @@ export const useNavigationTreeNodes = () => {
 		} ) );
 	};
 
-	const removeNode = ( key ) => {
+	const removeNode = ( key: keyof typeof nodes ) => {
 		return setNodes( ( original ) => {
 			const { [ key ]: removedNode, ...remainingNodes } = original;
 			return remainingNodes;
@@ -24,4 +28,4 @@ export const useNavigationTreeNodes = () => {
 	};
 
 	return { nodes, getNode, addNode, removeNode };
-};
+}

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

@@ -4,8 +4,8 @@
 import removeAccents from 'remove-accents';
 
 // @see packages/block-editor/src/components/inserter/search-items.js
-export const normalizeInput = ( input ) =>
+export const normalizeInput = ( input: string ) =>
 	removeAccents( input ).replace( /^\//, '' ).toLowerCase();
 
-export const normalizedSearch = ( title, search ) =>
+export const normalizedSearch = ( title: string, search: string ) =>
 	-1 !== normalizeInput( title ).indexOf( normalizeInput( search ) );

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

@@ -172,13 +172,19 @@ function UnconnectedNavigatorScreen(
 		},
 		x: 0,
 	};
-	const initial = {
-		opacity: 0,
-		x:
-			( isRTL() && location.isBack ) || ( ! isRTL() && ! location.isBack )
-				? 50
-				: -50,
-	};
+	// Disable the initial animation if the screen is the very first screen to be
+	// rendered within the current `NavigatorProvider`.
+	const initial =
+		location.isInitial && ! location.isBack
+			? false
+			: {
+					opacity: 0,
+					x:
+						( isRTL() && location.isBack ) ||
+						( ! isRTL() && ! location.isBack )
+							? 50
+							: -50,
+			  };
 	const exit = {
 		delay: animationExitDelay,
 		opacity: 0,

package/src/navigator/test/index.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ReactNode, ForwardedRef, ComponentPropsWithoutRef } from 'react';
+import type { ComponentPropsWithoutRef } from 'react';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
@@ -23,27 +23,6 @@ import {
 	useNavigator,
 } from '..';
 
-jest.mock( 'framer-motion', () => {
-	const actual = jest.requireActual( 'framer-motion' );
-	return {
-		__esModule: true,
-		...actual,
-		AnimatePresence:
-			( { children }: { children?: ReactNode } ) =>
-			() =>
-				<div>{ children }</div>,
-		motion: {
-			...actual.motion,
-			div: require( 'react' ).forwardRef(
-				(
-					{ children }: { children?: ReactNode },
-					ref: ForwardedRef< HTMLDivElement >
-				) => <div ref={ ref }>{ children }</div>
-			),
-		},
-	};
-} );
-
 const INVALID_HTML_ATTRIBUTE = {
 	raw: ' "\'><=invalid_path',
 	escaped: " &quot;'&gt;<=invalid_path",
@@ -738,4 +717,68 @@ describe( 'Navigator', () => {
 			expect( getNavigationButton( 'toChildScreen' ) ).toHaveFocus();
 		} );
 	} );
+
+	describe( 'animation', () => {
+		it( 'should not animate the initial screen', async () => {
+			const onHomeAnimationStartSpy = jest.fn();
+
+			render(
+				<NavigatorProvider initialPath="/">
+					<NavigatorScreen
+						path="/"
+						onAnimationStart={ onHomeAnimationStartSpy }
+					>
+						<CustomNavigatorButton path="/child">
+							To child
+						</CustomNavigatorButton>
+					</NavigatorScreen>
+				</NavigatorProvider>
+			);
+
+			expect( onHomeAnimationStartSpy ).not.toHaveBeenCalled();
+		} );
+
+		it( 'should animate all other screens (including the initial screen when navigating back)', async () => {
+			const user = userEvent.setup();
+
+			const onHomeAnimationStartSpy = jest.fn();
+			const onChildAnimationStartSpy = jest.fn();
+
+			render(
+				<NavigatorProvider initialPath="/">
+					<NavigatorScreen
+						path="/"
+						onAnimationStart={ onHomeAnimationStartSpy }
+					>
+						<CustomNavigatorButton path="/child">
+							To child
+						</CustomNavigatorButton>
+					</NavigatorScreen>
+					<NavigatorScreen
+						path="/child"
+						onAnimationStart={ onChildAnimationStartSpy }
+					>
+						<CustomNavigatorBackButton>
+							Back to home
+						</CustomNavigatorBackButton>
+					</NavigatorScreen>
+				</NavigatorProvider>
+			);
+
+			expect( onHomeAnimationStartSpy ).not.toHaveBeenCalled();
+			expect( onChildAnimationStartSpy ).not.toHaveBeenCalled();
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'To child' } )
+			);
+			expect( onChildAnimationStartSpy ).toHaveBeenCalledTimes( 1 );
+			expect( onHomeAnimationStartSpy ).not.toHaveBeenCalled();
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Back to home' } )
+			);
+			expect( onChildAnimationStartSpy ).toHaveBeenCalledTimes( 1 );
+			expect( onHomeAnimationStartSpy ).toHaveBeenCalledTimes( 1 );
+		} );
+	} );
 } );

package/src/number-control/index.tsx

@@ -130,9 +130,7 @@ function UnforwardedNumberControl(
 			 * Handles drag to update events
 			 */
 			if ( type === inputControlActionTypes.DRAG && isDragEnabled ) {
-				// @ts-expect-error TODO: See if reducer actions can be typed better
 				const [ x, y ] = payload.delta;
-				// @ts-expect-error TODO: See if reducer actions can be typed better
 				const enableShift = payload.shiftKey && isShiftStepEnabled;
 				const modifier = enableShift
 					? ensureNumber( shiftStep ) * baseStep