@wordpress/components 33.1.1-next.v.202605131006.0 → 34.0.0

package/src/navigation/test/index.tsx

@@ -1,347 +0,0 @@
-/**
- * External dependencies
- */
-import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-
-/**
- * WordPress dependencies
- */
-import { useState } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
-import Navigation from '..';
-import NavigationItem from '../item';
-import NavigationMenu from '../menu';
-
-const TestNavigation = ( {
-	activeItem,
-	rootTitle,
-	showBadge,
-}: {
-	activeItem?: string;
-	rootTitle?: string;
-	showBadge?: boolean;
-} ) => (
-	<Navigation activeItem={ activeItem }>
-		<NavigationMenu title={ rootTitle }>
-			<NavigationItem
-				badge={ showBadge ? 21 : undefined }
-				item="item-1"
-				title="Item 1"
-			/>
-			<NavigationItem
-				href="http://example.com"
-				item="item-2"
-				target="_blank"
-				title="Item 2"
-			/>
-			<NavigationItem
-				navigateToMenu="category"
-				item="category"
-				title="Category"
-			/>
-			<NavigationItem item="item-3">
-				<span>customize me</span>
-			</NavigationItem>
-		</NavigationMenu>
-		<NavigationMenu
-			backButtonLabel="Home"
-			menu="category"
-			parentMenu="root"
-			title="Category"
-		>
-			<NavigationItem item="child-1" title="Child 1" />
-			<NavigationItem item="child-2" title="Child 2" />
-		</NavigationMenu>
-	</Navigation>
-);
-
-const TestNavigationControlled = () => {
-	const [ activeItem, setActiveItem ] = useState( 'item-1' );
-	const [ activeMenu, setActiveMenu ] = useState( 'root' );
-
-	const onMockLinkClick: React.MouseEventHandler< HTMLAnchorElement > = (
-		event
-	) => {
-		event.preventDefault();
-		const item = ( event.target as HTMLAnchorElement ).href.replace(
-			'https://example.com/',
-			''
-		);
-		setActiveItem( item );
-	};
-
-	return (
-		<>
-			<Navigation
-				activeItem={ activeItem }
-				activeMenu={ activeMenu }
-				className="navigation-story"
-				onActivateMenu={ setActiveMenu }
-			>
-				<NavigationMenu title="Home">
-					<NavigationItem
-						item="item-1"
-						title="Item 1"
-						href="https://example.com/item-1"
-						onClick={ onMockLinkClick }
-					/>
-					<NavigationItem
-						item="item-2"
-						title="Item 2"
-						href="https://example.com/item-2"
-						onClick={ onMockLinkClick }
-					/>
-					<NavigationItem
-						item="item-sub-menu"
-						navigateToMenu="sub-menu"
-						title="Sub-Menu"
-					/>
-				</NavigationMenu>
-				<NavigationMenu
-					menu="sub-menu"
-					parentMenu="root"
-					title="Sub-Menu"
-				>
-					<NavigationItem
-						item="child-1"
-						onClick={ () => setActiveItem( 'child-1' ) }
-						title="Child 1"
-					/>
-					<NavigationItem
-						item="child-2"
-						onClick={ () => setActiveItem( 'child-2' ) }
-						title="Child 2"
-					/>
-					<NavigationItem
-						item="child-nested-sub-menu"
-						navigateToMenu="nested-sub-menu"
-						title="Nested Sub-Menu"
-					/>
-				</NavigationMenu>
-				<NavigationMenu
-					menu="nested-sub-menu"
-					parentMenu="sub-menu"
-					title="Nested Sub-Menu"
-				>
-					<NavigationItem
-						item="sub-child-1"
-						onClick={ () => setActiveItem( 'sub-child-1' ) }
-						title="Sub-Child 1"
-					/>
-					<NavigationItem
-						item="sub-child-2"
-						onClick={ () => setActiveItem( 'sub-child-2' ) }
-						title="Sub-Child 2"
-					/>
-				</NavigationMenu>
-			</Navigation>
-
-			<div className="navigation-story__aside">
-				<p>
-					Menu <code>{ activeMenu }</code> is active.
-					<br />
-					Item <code>{ activeItem }</code> is active.
-				</p>
-				<p>
-					<button
-						onClick={ () => {
-							setActiveMenu( 'nested-sub-menu' );
-						} }
-					>
-						Open the Nested Sub-Menu menu
-					</button>
-				</p>
-				<p>
-					<button
-						onClick={ () => {
-							setActiveItem( 'child-2' );
-							setActiveMenu( 'sub-menu' );
-						} }
-					>
-						Navigate to Child 2 item
-					</button>
-				</p>
-			</div>
-		</>
-	);
-};
-
-describe( 'Navigation', () => {
-	it( 'should render the panes and active item', async () => {
-		render( <TestNavigation activeItem="item-2" /> );
-
-		const menuItems = screen.getAllByRole( 'listitem' );
-
-		expect( console ).toHaveWarnedWith(
-			'wp.components.Navigation (and all subcomponents) is deprecated since version 6.8 and will be removed in version 7.1. Please use wp.components.Navigator instead.'
-		);
-
-		expect( menuItems ).toHaveLength( 4 );
-		expect( menuItems[ 0 ] ).toHaveTextContent( 'Item 1' );
-		expect( menuItems[ 1 ] ).toHaveTextContent( 'Item 2' );
-		expect( menuItems[ 2 ] ).toHaveTextContent( 'Category' );
-		expect( menuItems[ 3 ] ).toHaveTextContent( 'customize me' );
-
-		expect(
-			screen.getByRole( 'link', { current: 'page' } )
-		).toHaveTextContent( 'Item 2' );
-	} );
-
-	it( 'should render anchor links when menu item supplies an href', () => {
-		render( <TestNavigation /> );
-
-		const linkItem = screen.getByRole( 'link', { name: 'Item 2' } );
-
-		expect( linkItem ).toBeInTheDocument();
-		expect( linkItem ).toHaveAttribute( 'target', '_blank' );
-	} );
-
-	it( 'should render a custom component when menu item supplies one', () => {
-		render( <TestNavigation /> );
-
-		expect( screen.getByText( 'customize me' ) ).toBeInTheDocument();
-	} );
-
-	it( 'should set an active category on click', async () => {
-		const user = userEvent.setup();
-
-		render( <TestNavigation /> );
-
-		await user.click( screen.getByRole( 'button', { name: 'Category' } ) );
-
-		expect( screen.getByRole( 'heading' ) ).toHaveTextContent( 'Category' );
-		const menuItems = screen.getAllByRole( 'listitem' );
-		expect( menuItems ).toHaveLength( 2 );
-		expect( menuItems[ 0 ] ).toHaveTextContent( 'Child 1' );
-		expect( menuItems[ 1 ] ).toHaveTextContent( 'Child 2' );
-	} );
-
-	it( 'should render the root title', () => {
-		const { rerender } = render( <TestNavigation /> );
-
-		expect( screen.queryByRole( 'heading' ) ).not.toBeInTheDocument();
-
-		rerender( <TestNavigation rootTitle="Home" /> );
-
-		expect( screen.getByRole( 'heading' ) ).toBeInTheDocument();
-		expect( screen.getByRole( 'heading' ) ).toHaveTextContent( 'Home' );
-	} );
-
-	it( 'should render badges', () => {
-		render( <TestNavigation showBadge /> );
-
-		const menuItem = screen.getAllByRole( 'listitem' );
-		expect( menuItem[ 0 ] ).toHaveTextContent( 'Item 1' + '21' );
-	} );
-
-	it( 'should render menu titles when items exist', () => {
-		const { rerender } = render( <Navigation></Navigation> );
-
-		expect( screen.queryByText( 'Menu title' ) ).not.toBeInTheDocument();
-
-		rerender( <TestNavigation rootTitle="Menu title" /> );
-
-		expect( screen.getByText( 'Menu title' ) ).toBeInTheDocument();
-	} );
-
-	it( 'should navigate up a level when clicking the back button', async () => {
-		const user = userEvent.setup();
-
-		render( <TestNavigation rootTitle="Home" /> );
-
-		await user.click( screen.getByRole( 'button', { name: 'Category' } ) );
-
-		expect( screen.getByRole( 'heading' ) ).toHaveTextContent( 'Category' );
-
-		await user.click( screen.getByRole( 'button', { name: 'Home' } ) );
-
-		expect( screen.getByRole( 'heading' ) ).toHaveTextContent( 'Home' );
-	} );
-
-	it( 'should navigate correctly when controlled', async () => {
-		const user = userEvent.setup();
-
-		render( <TestNavigationControlled /> );
-
-		// check root menu is shown and item 1 is selected
-		expect(
-			screen.getByRole( 'heading', { name: 'Home' } )
-		).toBeInTheDocument();
-		expect(
-			screen.getByRole( 'link', { current: 'page' } )
-		).toHaveTextContent( 'Item 1' );
-
-		// click Item 2, check it's selected
-		await user.click( screen.getByRole( 'link', { name: 'Item 2' } ) );
-		expect(
-			screen.getByRole( 'link', { current: 'page' } )
-		).toHaveTextContent( 'Item 2' );
-
-		// click sub-menu, check new menu is shown
-		await user.click( screen.getByRole( 'button', { name: 'Sub-Menu' } ) );
-		expect(
-			screen.getByRole( 'heading', { name: 'Sub-Menu' } )
-		).toBeInTheDocument();
-
-		// click Child 1, check it's selected
-		await user.click( screen.getByRole( 'button', { name: 'Child 1' } ) );
-		expect(
-			screen.getByRole( 'button', { current: 'page' } )
-		).toHaveTextContent( 'Child 1' );
-
-		// click nested sub-menu, check nested sub-menu is shown
-		await user.click(
-			screen.getByRole( 'button', { name: 'Nested Sub-Menu' } )
-		);
-		expect(
-			screen.getByRole( 'heading', { name: 'Nested Sub-Menu' } )
-		).toBeInTheDocument();
-
-		// click Sub Child 2, check it's selected
-		await user.click(
-			screen.getByRole( 'button', { name: 'Sub-Child 2' } )
-		);
-		expect(
-			screen.getByRole( 'button', { current: 'page' } )
-		).toHaveTextContent( 'Sub-Child 2' );
-
-		// click back, check sub-menu is shown
-		await user.click( screen.getByRole( 'button', { name: 'Sub-Menu' } ) );
-		expect(
-			screen.getByRole( 'heading', { name: 'Sub-Menu' } )
-		).toBeInTheDocument();
-
-		// click back, check root menu is shown
-		await user.click( screen.getByRole( 'button', { name: 'Home' } ) );
-		expect(
-			screen.getByRole( 'heading', { name: 'Home' } )
-		).toBeInTheDocument();
-
-		// click the programmatic nested sub-menu button, check nested sub menu is shown
-		await user.click(
-			screen.getByRole( 'button', {
-				name: 'Open the Nested Sub-Menu menu',
-			} )
-		);
-		expect(
-			screen.getByRole( 'heading', { name: 'Nested Sub-Menu' } )
-		).toBeInTheDocument();
-
-		// click navigate to child2 item button, check the correct menu is shown and the item is selected
-		await user.click(
-			screen.getByRole( 'button', {
-				name: 'Navigate to Child 2 item',
-			} )
-		);
-		expect(
-			screen.getByRole( 'heading', { name: 'Sub-Menu' } )
-		).toBeInTheDocument();
-		expect(
-			screen.getByRole( 'button', { current: 'page' } )
-		).toHaveTextContent( 'Child 2' );
-	} );
-} );

package/src/navigation/types.ts

@@ -1,325 +0,0 @@
-/**
- * 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?: React.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;
-	};
-};