@wordpress/components 33.0.1-next.v.202604201441.0 → 33.1.0

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

@@ -2,7 +2,13 @@
  * External dependencies
  */
 import clsx from 'clsx';
-import type { KeyboardEvent, MouseEvent, TouchEvent, FocusEvent } from 'react';
+import type {
+	KeyboardEvent,
+	MouseEvent,
+	TouchEvent,
+	FocusEvent,
+	ReactNode,
+} from 'react';
 
 /**
  * WordPress dependencies
@@ -12,6 +18,7 @@ import { __, _n, sprintf } from '@wordpress/i18n';
 import { useDebounce, useInstanceId, usePrevious } from '@wordpress/compose';
 import { speak } from '@wordpress/a11y';
 import { isShallowEqual } from '@wordpress/is-shallow-equal';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -70,10 +77,11 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		__experimentalRenderItem,
 		__experimentalExpandOnFocus = false,
 		__experimentalValidateInput = () => true,
-		__experimentalShowHowTo = true,
+		__experimentalShowHowTo,
 		__next40pxDefaultSize = false,
 		__experimentalAutoSelectFirstMatch = false,
 		tokenizeOnBlur = false,
+		help,
 	} = useDeprecated36pxDefaultSizeProp< FormTokenFieldProps >( props );
 
 	maybeWarnDeprecated36pxSize( {
@@ -82,6 +90,27 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		__next40pxDefaultSize,
 	} );
 
+	const defaultHelp = tokenizeOnSpace
+		? __( 'Separate with commas, spaces, or the Enter key.' )
+		: __( 'Separate with commas or the Enter key.' );
+
+	let computedHelp: ReactNode = help !== undefined ? help : defaultHelp;
+
+	if ( typeof __experimentalShowHowTo === 'boolean' ) {
+		deprecated(
+			'`__experimentalShowHowTo` prop in wp.components.FormTokenField',
+			{
+				since: '7.1',
+				alternative: '`help` prop',
+				hint: 'The `help` prop now defaults to the previous how-to text. Pass an empty string to hide it.',
+			}
+		);
+
+		if ( __experimentalShowHowTo === false && help === undefined ) {
+			computedHelp = '';
+		}
+	}
+
 	const instanceId = useInstanceId( FormTokenField );
 
 	// We reset to these initial values again in the onBlur
@@ -655,6 +684,10 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 	}
 
 	function renderInput() {
+		const describedById = computedHelp
+			? `components-form-token-input-${ instanceId }__help`
+			: undefined;
+
 		const inputProps = {
 			instanceId,
 			autoCapitalize,
@@ -665,6 +698,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 			onBlur,
 			isExpanded,
 			selectedSuggestionIndex,
+			'aria-describedby': describedById,
 		};
 
 		return (
@@ -749,16 +783,12 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 					/>
 				) }
 			</div>
-			{ __experimentalShowHowTo && (
+			{ computedHelp && (
 				<StyledHelp
-					id={ `components-form-token-suggestions-howto-${ instanceId }` }
+					id={ `components-form-token-input-${ instanceId }__help` }
 					className="components-form-token-field__help"
 				>
-					{ tokenizeOnSpace
-						? __(
-								'Separate with commas, spaces, or the Enter key.'
-						  )
-						: __( 'Separate with commas or the Enter key.' ) }
+					{ computedHelp }
 				</StyledHelp>
 			) }
 		</div>

package/src/form-token-field/stories/index.story.tsx

@@ -25,6 +25,7 @@ const meta: Meta< typeof FormTokenField > = {
 		__experimentalValidateInput: {
 			control: false,
 		},
+		help: { control: 'text' },
 	},
 	parameters: {
 		controls: {
@@ -32,7 +33,7 @@ const meta: Meta< typeof FormTokenField > = {
 		},
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'Will be superseded by `SearchableChipSelect` in `@wordpress/ui`, but continue using for now.',
 		},

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

@@ -23,7 +23,7 @@ const meta: Meta< typeof GradientPicker > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

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

@@ -26,7 +26,7 @@ const meta: Meta< typeof Guide > = {
 	},
 	parameters: {
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'editor',
 		},
 	},

package/src/higher-order/with-notices/test/index.tsx

@@ -14,10 +14,10 @@ import {
  * WordPress dependencies
  */
 import {
+	createRef,
 	forwardRef,
 	useEffect,
 	useImperativeHandle,
-	useRef,
 } from '@wordpress/element';
 
 /**
@@ -91,15 +91,17 @@ describe( 'withNotices return type', () => {
 } );
 
 describe( 'withNotices operations', () => {
-	let handle: React.RefObject< any >;
-	const Handle = ( props: any ) => {
-		handle = useRef( null );
-		return <TestNoticeOperations { ...props } ref={ handle } />;
-	};
+	function setup( props: any = {} ) {
+		const handle = createRef< any >();
+		const utils = render(
+			<TestNoticeOperations { ...props } ref={ handle } />
+		);
+		return { ...utils, handle };
+	}
 
 	it( 'should create notices with createNotice', () => {
 		const message = 'Aló!';
-		const { container } = render( <Handle /> );
+		const { container, handle } = setup();
 		const { getByText } = within( container );
 		act( () => {
 			handle.current.createNotice( { content: message } );
@@ -109,7 +111,7 @@ describe( 'withNotices operations', () => {
 
 	it( 'should create notices of error status with createErrorNotice', () => {
 		const message = 'can’t touch this';
-		const { container } = render( <Handle /> );
+		const { container, handle } = setup();
 		const { getByText } = within( container );
 		act( () => {
 			handle.current.createErrorNotice( message );
@@ -120,7 +122,7 @@ describe( 'withNotices operations', () => {
 
 	it( 'should remove a notice with removeNotice', async () => {
 		const notice = { id: 'so real', content: 'so why can’t I touch it?' };
-		const { container } = render( <Handle /> );
+		const { container, handle } = setup();
 		const { getByText } = within( container );
 		act( () => {
 			handle.current.createNotice( notice );
@@ -137,7 +139,7 @@ describe( 'withNotices operations', () => {
 	it( 'should remove all notices with removeAllNotices', async () => {
 		const messages = [ 'Aló!', 'hu dis?', 'Otis' ];
 		const notices = noticesFrom( messages );
-		const { container } = render( <Handle notifications={ notices } /> );
+		const { container, handle } = setup( { notifications: notices } );
 		const { getByText } = within( container );
 		expect(
 			await waitForElementToBeRemoved( () => {

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

@@ -23,7 +23,7 @@ const meta: Meta< typeof Icon > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'Prefer this component over the `Icon` component from `@wordpress/icons`.',
 		},

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

@@ -41,7 +41,7 @@ const meta: Meta< typeof InputControl > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'Will be superseded by `InputControl` in `@wordpress/ui`, but continue using for now.',
 		},

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

@@ -24,7 +24,7 @@ const meta: Meta< typeof ItemGroup > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

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

@@ -17,7 +17,7 @@ const meta: Meta< typeof KeyboardShortcuts > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 		},
 	},

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/stories/index.story.tsx

@@ -56,7 +56,7 @@ const meta: Meta< typeof Menu > = {
 			source: { excludeDecorators: true },
 		},
 		componentStatus: {
-			status: 'stable',
+			status: 'recommended',
 			whereUsed: 'global',
 			notes: 'When building for the Gutenberg repo, use this component instead of `DropdownMenu`. Otherwise, continue using `DropdownMenu` for now.',
 		},

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