@wordpress/components 23.4.0 → 23.6.0

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

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -6,16 +11,25 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Navigation from '../..';
-import NavigationItem from '../../item';
-import NavigationMenu from '../../menu';
-import NavigationGroup from '../../group';
+import { Navigation } from '../..';
+import { NavigationItem } from '../../item';
+import { NavigationMenu } from '../../menu';
+import { NavigationGroup } from '../../group';
 
-export function GroupStory() {
+export const GroupStory: ComponentStory< typeof Navigation > = ( {
+	className,
+	...props
+} ) => {
 	const [ activeItem, setActiveItem ] = useState( 'item-1' );
 
 	return (
-		<Navigation activeItem={ activeItem } className="navigation-story">
+		<Navigation
+			{ ...props }
+			activeItem={ activeItem }
+			className={ [ 'navigation-story', className ]
+				.filter( Boolean )
+				.join( ' ' ) }
+		>
 			<NavigationMenu title="Home">
 				<NavigationGroup title="Group 1">
 					<NavigationItem
@@ -44,4 +58,4 @@ export function GroupStory() {
 			</NavigationMenu>
 		</Navigation>
 	);
-}
+};

package/src/navigation/stories/utils/{hide-if-empty.js → hide-if-empty.tsx}

@@ -1,14 +1,27 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory } from '@storybook/react';
+
 /**
  * Internal dependencies
  */
-import Navigation from '../..';
-import NavigationItem from '../../item';
-import NavigationMenu from '../../menu';
+import { Navigation } from '../..';
+import { NavigationItem } from '../../item';
+import { NavigationMenu } from '../../menu';
 
-export function HideIfEmptyStory() {
+export const HideIfEmptyStory: ComponentStory< typeof Navigation > = ( {
+	className,
+	...props
+} ) => {
 	return (
 		<>
-			<Navigation className="navigation-story">
+			<Navigation
+				{ ...props }
+				className={ [ 'navigation-story', className ]
+					.filter( Boolean )
+					.join( ' ' ) }
+			>
 				<NavigationMenu title="Home" menu="root" isEmpty={ false }>
 					<NavigationItem
 						navigateToMenu="root-sub-1"
@@ -54,4 +67,4 @@ export function HideIfEmptyStory() {
 			</p>
 		</>
 	);
-}
+};

package/src/navigation/stories/utils/{more-examples.js → more-examples.tsx}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -7,14 +12,17 @@ import { Icon, wordpress, home } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
-import Navigation from '../..';
-import NavigationGroup from '../../group';
-import NavigationItem from '../../item';
-import NavigationMenu from '../../menu';
+import { Navigation } from '../..';
+import { NavigationGroup } from '../../group';
+import { NavigationItem } from '../../item';
+import { NavigationMenu } from '../../menu';
 
-export function MoreExamplesStory() {
+export const MoreExamplesStory: ComponentStory< typeof Navigation > = ( {
+	className,
+	...props
+} ) => {
 	const [ activeItem, setActiveItem ] = useState( 'child-1' );
-	const [ delayedBadge, setDelayedBadge ] = useState();
+	const [ delayedBadge, setDelayedBadge ] = useState< number | undefined >();
 	useEffect( () => {
 		const timeout = setTimeout( () => setDelayedBadge( 2 ), 1500 );
 		return () => clearTimeout( timeout );
@@ -24,7 +32,13 @@ export function MoreExamplesStory() {
 		useState( 1 );
 
 	return (
-		<Navigation activeItem={ activeItem } className="navigation-story">
+		<Navigation
+			{ ...props }
+			activeItem={ activeItem }
+			className={ [ 'navigation-story', className ]
+				.filter( Boolean )
+				.join( ' ' ) }
+		>
 			<NavigationMenu title="Home">
 				<NavigationGroup title="Items without Active State">
 					<NavigationItem item="item-1" title="Item 1" />
@@ -126,10 +140,14 @@ export function MoreExamplesStory() {
 				menu="custom-back-click-handler-prevented-menu"
 				title="Custom back button click handler prevented"
 				parentMenu="root"
-				onBackButtonClick={ ( event ) => {
-					event.preventDefault();
-					setBackButtonPreventedBadge( backButtonPreventedBadge + 1 );
-				} }
+				onBackButtonClick={
+					( ( event ) => {
+						event.preventDefault();
+						setBackButtonPreventedBadge(
+							backButtonPreventedBadge + 1
+						);
+					} ) as React.MouseEventHandler
+				}
 				backButtonLabel="Increment badge"
 			>
 				<NavigationItem
@@ -140,4 +158,4 @@ export function MoreExamplesStory() {
 			</NavigationMenu>
 		</Navigation>
 	);
-}
+};

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

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -6,10 +11,10 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Navigation from '../..';
-import NavigationGroup from '../../group';
-import NavigationItem from '../../item';
-import NavigationMenu from '../../menu';
+import { Navigation } from '../..';
+import { NavigationGroup } from '../../group';
+import { NavigationItem } from '../../item';
+import { NavigationMenu } from '../../menu';
 import { normalizedSearch } from '../../utils';
 
 const searchItems = [
@@ -24,12 +29,21 @@ const searchItems = [
 	{ item: 'waldo', title: 'Waldo' },
 ];
 
-export function SearchStory() {
+export const SearchStory: ComponentStory< typeof Navigation > = ( {
+	className,
+	...props
+} ) => {
 	const [ activeItem, setActiveItem ] = useState( 'item-1' );
 	const [ search, setSearch ] = useState( '' );
 
 	return (
-		<Navigation activeItem={ activeItem } className="navigation-story">
+		<Navigation
+			{ ...props }
+			activeItem={ activeItem }
+			className={ [ 'navigation-story', className ]
+				.filter( Boolean )
+				.join( ' ' ) }
+		>
 			<NavigationMenu hasSearch title="Home">
 				<NavigationGroup title="Items">
 					{ searchItems.map( ( { item, title } ) => (
@@ -74,4 +88,4 @@ export function SearchStory() {
 			</NavigationMenu>
 		</Navigation>
 	);
-}
+};

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

@@ -16,11 +16,19 @@ import Navigation from '..';
 import NavigationItem from '../item';
 import NavigationMenu from '../menu';
 
-const TestNavigation = ( { activeItem, rootTitle, showBadge } = {} ) => (
+const TestNavigation = ( {
+	activeItem,
+	rootTitle,
+	showBadge,
+}: {
+	activeItem?: string;
+	rootTitle?: string;
+	showBadge?: boolean;
+} ) => (
 	<Navigation activeItem={ activeItem }>
 		<NavigationMenu title={ rootTitle }>
 			<NavigationItem
-				badge={ showBadge && 21 }
+				badge={ showBadge ? 21 : undefined }
 				item="item-1"
 				title="Item 1"
 			/>
@@ -55,9 +63,14 @@ const TestNavigationControlled = () => {
 	const [ activeItem, setActiveItem ] = useState( 'item-1' );
 	const [ activeMenu, setActiveMenu ] = useState( 'root' );
 
-	const onMockLinkClick = ( event ) => {
+	const onMockLinkClick: React.MouseEventHandler< HTMLAnchorElement > = (
+		event
+	) => {
 		event.preventDefault();
-		const item = event.target.href.replace( 'https://example.com/', '' );
+		const item = ( event.target as HTMLAnchorElement ).href.replace(
+			'https://example.com/',
+			''
+		);
 		setActiveItem( item );
 	};
 

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 ] = [];
 				}