@wordpress/components 32.5.2-next.v.202604091042.0 → 33.0.0

package/src/form-token-field/test/index.tsx

@@ -17,6 +17,7 @@ import type { ComponentProps } from 'react';
  * WordPress dependencies
  */
 import { useState } from '@wordpress/element';
+import { logged } from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -122,6 +123,14 @@ function unescapeAndFormatSpaces( str: string ) {
 }
 
 describe( 'FormTokenField', () => {
+	afterEach( () => {
+		// `@wordpress/deprecated` caches each warning message after the first
+		// log; reset it so multiple tests can assert the same deprecation.
+		for ( const key in logged ) {
+			delete logged[ key ];
+		}
+	} );
+
 	describe( 'basic usage', () => {
 		it( "should add tokens with the input's value when pressing the enter key", async () => {
 			const user = userEvent.setup();
@@ -582,18 +591,17 @@ describe( 'FormTokenField', () => {
 			);
 		} );
 
-		it( 'should show extra instructions when the `__experimentalShowHowTo` prop  is set to `true`', () => {
+		it( 'should show the default how-to text via the `help` prop by default', () => {
 			const instructionsTokenizeSpace =
 				'Separate with commas, spaces, or the Enter key.';
 			const instructionsDefault =
 				'Separate with commas or the Enter key.';
 
-			// The __experimentalShowHowTo prop is `true` by default
 			const { rerender } = render( <FormTokenFieldWithState /> );
 
 			expect( screen.getByText( instructionsDefault ) ).toBeVisible();
 
-			// The "show how to" text is used to aria-describedby the input
+			// The default how-to text is used to aria-describedby the input.
 			expect(
 				screen.getByRole( 'combobox' )
 			).toHaveAccessibleDescription( instructionsDefault );
@@ -604,27 +612,79 @@ describe( 'FormTokenField', () => {
 				screen.getByText( instructionsTokenizeSpace )
 			).toBeVisible();
 
-			// The "show how to" text is used to aria-describedby the input
 			expect(
 				screen.getByRole( 'combobox' )
 			).toHaveAccessibleDescription( instructionsTokenizeSpace );
+		} );
 
-			rerender(
+		it( 'should allow hiding the help text by passing an empty string', () => {
+			render( <FormTokenFieldWithState help="" /> );
+
+			expect(
+				screen.queryByText( 'Separate with commas or the Enter key.' )
+			).not.toBeInTheDocument();
+			expect(
+				screen.getByRole( 'combobox' )
+			).not.toHaveAccessibleDescription();
+		} );
+
+		it( 'should associate the `help` text with the input accessibly', () => {
+			render( <FormTokenFieldWithState help="Help text" /> );
+			expect(
+				screen.getByRole( 'combobox' )
+			).toHaveAccessibleDescription( 'Help text' );
+			// The default how-to text should no longer be rendered.
+			expect(
+				screen.queryByText( 'Separate with commas or the Enter key.' )
+			).not.toBeInTheDocument();
+		} );
+
+		it( 'should warn and hide the default text when `__experimentalShowHowTo` is `false`', () => {
+			render(
+				<FormTokenFieldWithState __experimentalShowHowTo={ false } />
+			);
+
+			expect( console ).toHaveWarnedWith(
+				'`__experimentalShowHowTo` prop in wp.components.FormTokenField is deprecated since version 7.1. Please use `help` prop instead. Note: The `help` prop now defaults to the previous how-to text. Pass an empty string to hide it.'
+			);
+
+			expect(
+				screen.queryByText( 'Separate with commas or the Enter key.' )
+			).not.toBeInTheDocument();
+			expect(
+				screen.getByRole( 'combobox' )
+			).not.toHaveAccessibleDescription();
+		} );
+
+		it( 'should warn and prefer `help` over `__experimentalShowHowTo` when both are provided', () => {
+			const { rerender } = render(
 				<FormTokenFieldWithState
-					tokenizeOnSpace
 					__experimentalShowHowTo={ false }
+					help="Help text"
 				/>
 			);
 
+			expect( console ).toHaveWarned();
 			expect(
-				screen.queryByText( instructionsDefault )
-			).not.toBeInTheDocument();
+				screen.getByRole( 'combobox' )
+			).toHaveAccessibleDescription( 'Help text' );
 			expect(
-				screen.queryByText( instructionsTokenizeSpace )
+				screen.queryByText( 'Separate with commas or the Enter key.' )
 			).not.toBeInTheDocument();
+
+			rerender(
+				<FormTokenFieldWithState
+					__experimentalShowHowTo
+					help="Help text"
+				/>
+			);
+
 			expect(
 				screen.getByRole( 'combobox' )
-			).not.toHaveAccessibleDescription();
+			).toHaveAccessibleDescription( 'Help text' );
+			expect(
+				screen.queryByText( 'Separate with commas or the Enter key.' )
+			).not.toBeInTheDocument();
 		} );
 
 		it( "should use the value of the `placeholder` prop as the input's placeholder only when there are no tokens", async () => {

package/src/form-token-field/token-input.tsx

@@ -87,12 +87,7 @@ export function UnForwardedTokenInput(
 					? `components-form-token-suggestions-${ instanceId }-${ selectedSuggestionIndex }`
 					: undefined
 			}
-			aria-describedby={ [
-				`components-form-token-suggestions-howto-${ instanceId }`,
-				ariaDescribedBy,
-			]
-				.filter( Boolean )
-				.join( ' ' ) }
+			aria-describedby={ ariaDescribedBy }
 		/>
 	);
 }

package/src/form-token-field/types.ts

@@ -147,9 +147,12 @@ export interface FormTokenFieldProps
 	 */
 	__experimentalValidateInput?: ( token: string ) => boolean;
 	/**
-	 * If false, the text on how to use the select (ie: _Separate with commas or the Enter key._) will be hidden.
+	 * Use the `help` prop instead. The `help` prop now defaults to the previous
+	 * how-to text; if you were passing `__experimentalShowHowTo={ false }` to
+	 * hide it, pass an empty string to `help` instead.
 	 *
-	 * @default true
+	 * @deprecated Use the `help` prop instead.
+	 * @ignore
 	 */
 	__experimentalShowHowTo?: boolean;
 	/**
@@ -193,6 +196,17 @@ export interface FormTokenFieldProps
 	 * @default false
 	 */
 	tokenizeOnBlur?: boolean;
+	/**
+	 * Additional description for the control.
+	 *
+	 * Only use for meaningful description or instructions for the control. An
+	 * element containing the description will be programmatically associated to
+	 * the `FormTokenField` via `aria-describedby`.
+	 *
+	 * Defaults to a how-to message (e.g. _Separate with commas or the Enter key._);
+	 * pass an empty string to hide it.
+	 */
+	help?: ReactNode;
 }
 
 /**

package/src/gradient-picker/stories/index.story.tsx

@@ -15,6 +15,7 @@ import { useState } from '@wordpress/element';
 import GradientPicker from '..';
 
 const meta: Meta< typeof GradientPicker > = {
+	tags: [ 'manifest' ],
 	title: 'Components/Selection & Input/Color/GradientPicker',
 	id: 'components-gradientpicker',
 	component: GradientPicker,

package/src/icon/stories/index.story.tsx

@@ -16,6 +16,7 @@ import Icon from '..';
 import { VStack } from '../../v-stack';
 
 const meta: Meta< typeof Icon > = {
+	tags: [ 'manifest' ],
 	title: 'Components/Icon',
 	component: Icon,
 	parameters: {

package/src/input-control/stories/index.story.tsx

@@ -31,7 +31,7 @@ const meta: Meta< typeof InputControl > = {
 		type: { control: { type: 'text' } },
 		value: { control: { disable: true } },
 	},
-	tags: [ 'status-experimental' ],
+	tags: [ 'status-experimental', 'manifest' ],
 	args: {
 		onChange: fn(),
 		onValidate: fn(),

package/src/item-group/stories/index.story.tsx

@@ -19,7 +19,7 @@ const meta: Meta< typeof ItemGroup > = {
 		as: { control: false },
 		children: { control: false },
 	},
-	tags: [ 'status-experimental' ],
+	tags: [ 'status-experimental', 'manifest' ],
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },

package/src/keyboard-shortcuts/stories/index.story.tsx

@@ -9,6 +9,7 @@ import type { Meta, StoryFn } from '@storybook/react-vite';
 import KeyboardShortcuts from '..';
 
 const meta: Meta< typeof KeyboardShortcuts > = {
+	tags: [ 'manifest' ],
 	component: KeyboardShortcuts,
 	title: 'Components/Utilities/KeyboardShortcuts',
 	id: 'components-keyboardshortcuts',

package/src/menu/popover.tsx

@@ -24,10 +24,7 @@ import { Context } from './context';
 export const Popover = forwardRef<
 	HTMLDivElement,
 	WordPressComponentProps< PopoverProps, 'div', false >
->( function Popover(
-	{ gutter, children, shift, modal = true, ...otherProps },
-	ref
-) {
+>( function Popover( { gutter, shift, modal = true, ...otherProps }, ref ) {
 	const menuContext = useContext( Context );
 
 	// Extract the side from the applied placement — useful for animations.
@@ -70,6 +67,18 @@ export const Popover = forwardRef<
 		);
 	}
 
+	const renderMenu = useCallback(
+		( htmlProps: React.ComponentPropsWithRef< 'div' > ) => (
+			<Styled.MenuMotionRoot>
+				<Styled.MenuSurface
+					{ ...htmlProps }
+					variant={ menuContext.variant }
+				/>
+			</Styled.MenuMotionRoot>
+		),
+		[ menuContext.variant ]
+	);
+
 	return (
 		<Styled.Menu
 			{ ...otherProps }
@@ -88,9 +97,7 @@ export const Popover = forwardRef<
 			wrapperProps={ wrapperProps }
 			hideOnEscape={ hideOnEscape }
 			unmountOnHide
-			variant={ menuContext.variant }
-		>
-			{ children }
-		</Styled.Menu>
+			render={ renderMenu }
+		/>
 	);
 } );

package/src/menu/styles.ts

@@ -32,12 +32,17 @@ const TOOLBAR_VARIANT_BOX_SHADOW = `0 0 0 ${ CONFIG.borderWidth } ${ TOOLBAR_VAR
 
 const GRID_TEMPLATE_COLS = 'minmax( 0, max-content ) 1fr';
 
-export const Menu = styled( Ariakit.Menu )< Pick< ContextProps, 'variant' > >`
+export const Menu = styled( Ariakit.Menu )`
 	position: relative;
 	/* Same as popover component */
 	/* TODO: is there a way to read the sass variable? */
 	z-index: 1000000;
 
+	/* Only visible in Windows High Contrast mode */
+	outline: 2px solid transparent !important;
+`;
+
+export const MenuSurface = styled.div< Pick< ContextProps, 'variant' > >`
 	display: grid;
 	grid-template-columns: ${ GRID_TEMPLATE_COLS };
 	grid-template-rows: auto;
@@ -59,11 +64,16 @@ export const Menu = styled( Ariakit.Menu )< Pick< ContextProps, 'variant' > >`
 			? TOOLBAR_VARIANT_BOX_SHADOW
 			: DEFAULT_BOX_SHADOW };
 	` }
+`;
 
-	/* Only visible in Windows High Contrast mode */
-	outline: 2px solid transparent !important;
-
-	/* Open/close animation */
+/**
+ * Outer wrapper for menu motion. `Menu.Popover` uses Ariakit’s `render` prop so
+ * this element wraps the inner surface that receives all merged menu props
+ * (ref, role, `data-*`, children). Transitions mirror the pre-refactor `Menu`
+ * styles from `trunk`, driven by `data-enter` / `data-side` on the inner
+ * surface via `:has(> …)`.
+ */
+export const MenuMotionRoot = styled.div`
 	@media not ( prefers-reduced-motion ) {
 		transition-property: transform, opacity;
 		transition-duration: ${ DROPDOWN_MOTION_CSS.SLIDE_DURATION },
@@ -72,40 +82,40 @@ export const Menu = styled( Ariakit.Menu )< Pick< ContextProps, 'variant' > >`
 			${ DROPDOWN_MOTION_CSS.FADE_EASING };
 		will-change: transform, opacity;
 
-		&:not( [data-submenu] ) {
+		&:not( :has( > ${ MenuSurface }[data-submenu] ) ) {
 			/* Regardless of the side, fade in and out. */
 			opacity: 0;
-			&[data-enter] {
+			&:has( > ${ MenuSurface }[data-enter] ) {
 				opacity: 1;
 			}
 
 			/* Slide in the direction the menu is opening. */
-			&[data-side='bottom'] {
+			&:has( > ${ MenuSurface }[data-side='bottom'] ) {
 				transform: translateY(
 					-${ DROPDOWN_MOTION_CSS.SLIDE_DISTANCE }
 				);
 			}
-			&[data-side='top'] {
+			&:has( > ${ MenuSurface }[data-side='top'] ) {
 				transform: translateY(
 					${ DROPDOWN_MOTION_CSS.SLIDE_DISTANCE }
 				);
 			}
-			&[data-side='left'] {
+			&:has( > ${ MenuSurface }[data-side='left'] ) {
 				transform: translateX(
 					${ DROPDOWN_MOTION_CSS.SLIDE_DISTANCE }
 				);
 			}
-			&[data-side='right'] {
+			&:has( > ${ MenuSurface }[data-side='right'] ) {
 				transform: translateX(
 					-${ DROPDOWN_MOTION_CSS.SLIDE_DISTANCE }
 				);
 			}
-			&[data-enter][data-side='bottom'],
-			&[data-enter][data-side='top'] {
+			&:has( > ${ MenuSurface }[data-enter][data-side='bottom'] ),
+			&:has( > ${ MenuSurface }[data-enter][data-side='top'] ) {
 				transform: translateY( 0 );
 			}
-			&[data-enter][data-side='left'],
-			&[data-enter][data-side='right'] {
+			&:has( > ${ MenuSurface }[data-enter][data-side='left'] ),
+			&:has( > ${ MenuSurface }[data-enter][data-side='right'] ) {
 				transform: translateX( 0 );
 			}
 		}
@@ -114,6 +124,7 @@ export const Menu = styled( Ariakit.Menu )< Pick< ContextProps, 'variant' > >`
 
 const baseItem = css`
 	all: unset;
+	cursor: pointer;
 
 	position: relative;
 	min-height: ${ space( 8 ) };
@@ -157,7 +168,6 @@ const baseItem = css`
 
 	&[aria-disabled='true'] {
 		color: ${ COLORS.ui.textDisabled };
-		cursor: not-allowed;
 	}
 
 	/* Active item (including hover) */

package/src/menu/test/index.tsx

@@ -18,6 +18,14 @@ const delay = ( delayInMs: number ) => {
 	return new Promise( ( resolve ) => setTimeout( resolve, delayInMs ) );
 };
 
+const waitForFocusedMenu = () =>
+	waitFor( () => expect( screen.getByRole( 'menu' ) ).toHaveFocus() );
+
+const waitForFocusedMenuItem = ( name: string ) =>
+	waitFor( () =>
+		expect( screen.getByRole( 'menuitem', { name } ) ).toHaveFocus()
+	);
+
 // Open dropdown => open menu
 // Submenu trigger item => open submenu
 
@@ -114,7 +122,7 @@ describe( 'Menu', () => {
 			await click( toggleButton );
 
 			// Menu open, focus is on the menu wrapper
-			expect( screen.getByRole( 'menu' ) ).toHaveFocus();
+			await waitForFocusedMenu();
 		} );
 
 		it( 'should open and focus the first item when pressing the arrow down key on the trigger', async () => {
@@ -145,9 +153,7 @@ describe( 'Menu', () => {
 
 			// Menu open, focus is on the first focusable item
 			// (disabled items are still focusable and accessible)
-			expect(
-				screen.getByRole( 'menuitem', { name: 'First item' } )
-			).toHaveFocus();
+			await waitForFocusedMenuItem( 'First item' );
 		} );
 
 		it( 'should open and focus the first item when pressing the space key on the trigger', async () => {
@@ -178,9 +184,7 @@ describe( 'Menu', () => {
 
 			// Menu open, focus is on the first focusable item
 			// (disabled items are still focusable and accessible
-			expect(
-				screen.getByRole( 'menuitem', { name: 'First item' } )
-			).toHaveFocus();
+			await waitForFocusedMenuItem( 'First item' );
 		} );
 
 		it( 'should close when pressing the escape key', async () => {
@@ -201,7 +205,7 @@ describe( 'Menu', () => {
 
 			// Focuses menu on mouse click, focuses first item on keyboard press
 			// Can be changed with a custom useEffect
-			expect( screen.getByRole( 'menu' ) ).toHaveFocus();
+			await waitForFocusedMenu();
 
 			// Pressing esc will close the menu and move focus to the toggle
 			await press.Escape();
@@ -349,9 +353,7 @@ describe( 'Menu', () => {
 			);
 
 			// The menu is focused automatically when `defaultOpen` is set.
-			await waitFor( () =>
-				expect( screen.getByRole( 'menu' ) ).toHaveFocus()
-			);
+			await waitForFocusedMenu();
 
 			// Arrow up/down selects menu items
 			// The selection wraps around from last to first and viceversa
@@ -391,18 +393,13 @@ describe( 'Menu', () => {
 			).toHaveFocus();
 
 			// Arrow right/left can be used to enter/leave submenus
+			// (focus crosses menu contexts, so wait for it to settle)
 			await press.ArrowRight();
-			expect(
-				screen.getByRole( 'menuitem', {
-					name: 'Submenu item 1',
-				} )
-			).toHaveFocus();
+			await waitForFocusedMenuItem( 'Submenu item 1' );
 
 			await press.ArrowDown();
 			expect(
-				screen.getByRole( 'menuitem', {
-					name: 'Submenu item 2',
-				} )
+				screen.getByRole( 'menuitem', { name: 'Submenu item 2' } )
 			).toHaveFocus();
 
 			await press.ArrowLeft();
@@ -414,11 +411,7 @@ describe( 'Menu', () => {
 
 			// Spacebar or enter key can also be used to enter a submenu
 			await press.Enter();
-			expect(
-				screen.getByRole( 'menuitem', {
-					name: 'Submenu item 1',
-				} )
-			).toHaveFocus();
+			await waitForFocusedMenuItem( 'Submenu item 1' );
 
 			await press.ArrowLeft();
 			expect(
@@ -428,11 +421,7 @@ describe( 'Menu', () => {
 			).toHaveFocus();
 
 			await press.Space();
-			expect(
-				screen.getByRole( 'menuitem', {
-					name: 'Submenu item 1',
-				} )
-			).toHaveFocus();
+			await waitForFocusedMenuItem( 'Submenu item 1' );
 
 			await press.ArrowLeft();
 			expect(
@@ -886,7 +875,7 @@ describe( 'Menu', () => {
 			);
 
 			// Menu open, focus is on the menu wrapper
-			expect( screen.getByRole( 'menu' ) ).toHaveFocus();
+			await waitForFocusedMenu();
 
 			expect(
 				screen.queryByRole( 'button', {
@@ -916,18 +905,19 @@ describe( 'Menu', () => {
 			);
 
 			// Menu open, focus is on the menu wrapper
-			expect( screen.getByRole( 'menu' ) ).toHaveFocus();
+			await waitForFocusedMenu();
 
 			// Menu is not modal, therefore the outer button is part of the
 			// accessibility tree and can be found.
 			const outerButton = screen.getByRole( 'button', {
 				name: 'Button outside of dropdown',
 			} );
+			expect( outerButton ).toBeVisible();
 
 			// The outer button can be focused by pressing tab. Doing so will cause
 			// the Menu to close.
 			await press.Tab();
-			expect( outerButton ).toBeInTheDocument();
+			expect( outerButton ).toBeVisible();
 			expect( screen.queryByRole( 'menu' ) ).not.toBeInTheDocument();
 		} );
 	} );
@@ -1068,7 +1058,7 @@ describe( 'Menu', () => {
 					name: 'Open dropdown',
 				} )
 			);
-			expect( screen.getByRole( 'menu' ) ).toHaveFocus();
+			await waitForFocusedMenu();
 
 			// Type "tw", it should match and focus the item with content "Two"
 			await type( 'tw' );
@@ -1104,7 +1094,7 @@ describe( 'Menu', () => {
 					name: 'Open dropdown',
 				} )
 			);
-			expect( screen.getByRole( 'menu' ) ).toHaveFocus();
+			await waitForFocusedMenu();
 
 			// Type a string that doesn't match any items. Focus shouldn't move.
 			await type( 'abc' );

package/src/menu-group/stories/index.story.tsx

@@ -16,6 +16,7 @@ import MenuItem from '../../menu-item';
 import MenuItemsChoice from '../../menu-items-choice';
 
 const meta: Meta< typeof MenuGroup > = {
+	tags: [ 'manifest' ],
 	title: 'Components/Actions/MenuGroup',
 	component: MenuGroup,
 	id: 'components-menugroup',

package/src/menu-item/stories/index.story.tsx

@@ -16,6 +16,7 @@ import MenuItem from '..';
 import Shortcut from '../../shortcut';
 
 const meta: Meta< typeof MenuItem > = {
+	tags: [ 'manifest' ],
 	component: MenuItem,
 	title: 'Components/Actions/MenuItem',
 	id: 'components-menuitem',

package/src/menu-items-choice/stories/index.story.tsx

@@ -15,6 +15,7 @@ import MenuItemsChoice from '..';
 import MenuGroup from '../../menu-group';
 
 const meta: Meta< typeof MenuItemsChoice > = {
+	tags: [ 'manifest' ],
 	component: MenuItemsChoice,
 	title: 'Components/Actions/MenuItemsChoice',
 	id: 'components-menuitemschoice',

package/src/mobile/link-settings/index.native.js

@@ -32,7 +32,7 @@ import LinkRelIcon from './link-rel';
 
 import styles from './style.scss';
 
-const NEW_TAB_REL = 'noreferrer noopener';
+const NEW_TAB_REL = 'noopener';
 function LinkSettings( {
 	// Control link settings `BottomSheet` visibility
 	isVisible,

package/src/modal/index.tsx

@@ -121,6 +121,7 @@ function UnforwardedModal(
 	const onRequestCloseRef =
 		useRef< ModalProps[ 'onRequestClose' ] >( undefined );
 	useEffect( () => {
+		// eslint-disable-next-line react-compiler/react-compiler -- false positive, see https://github.com/facebook/react/issues/29196
 		onRequestCloseRef.current = onRequestClose;
 	}, [ onRequestClose ] );
 

package/src/modal/stories/index.story.tsx

@@ -18,6 +18,7 @@ import Modal from '../';
 import type { ModalProps } from '../types';
 
 const meta: Meta< typeof Modal > = {
+	tags: [ 'manifest' ],
 	component: Modal,
 	title: 'Components/Overlays/Modal',
 	id: 'components-modal',