@wordpress/components 25.16.0 → 26.0.0

package/src/popover/test/index.tsx

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import { render, screen, waitFor, getByText } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import type { CSSProperties } from 'react';
 
 /**
@@ -36,6 +37,28 @@ type PlacementToInitialTranslationTuple = [
 	CSSProperties[ 'translate' ],
 ];
 
+beforeAll( () => {
+	// This mock is necessary because deep in the weeds, `useConstrained` relies
+	// on `focusable` to return a list of DOM elements that can be focused. Part
+	// of this process involves checking that an element has an intrinsic size,
+	// which will always fail in JSDom.
+	//
+	// https://github.com/WordPress/gutenberg/blob/trunk/packages/dom/src/focusable.js#L55-L61
+	jest.spyOn(
+		HTMLElement.prototype,
+		'offsetHeight',
+		'get'
+	).mockImplementation( function getOffsetHeight( this: HTMLElement ) {
+		// The `1` returned here is somewhat arbitrary – it just needs to be a
+		// non-zero integer.
+		return 1;
+	} );
+} );
+
+afterAll( () => {
+	jest.restoreAllMocks();
+} );
+
 // There's no matching `placement` for 'middle center' positions,
 // fallback to 'bottom' (same as `floating-ui`'s default.)
 const FALLBACK_FOR_MIDDLE_CENTER_POSITIONS = 'bottom';
@@ -188,6 +211,233 @@ describe( 'Popover', () => {
 				expect( document.body ).toHaveFocus();
 			} );
 		} );
+
+		describe( 'tab constraint behavior', () => {
+			// `constrainTabbing` is implicitly controlled by `focusOnMount`.
+			// By default, when `focusOnMount` is false, `constrainTabbing` will
+			// also be false; otherwise, `constrainTabbing` will be true.
+
+			const setup = async (
+				props?: Partial< React.ComponentProps< typeof Popover > >
+			) => {
+				const user = await userEvent.setup();
+				const view = render(
+					<Popover data-testid="popover-element" { ...props }>
+						<button>Button 1</button>
+						<button>Button 2</button>
+						<button>Button 3</button>
+					</Popover>
+				);
+
+				const popover = screen.getByTestId( 'popover-element' );
+				await waitFor( () => expect( popover ).toBeVisible() );
+
+				const [ firstButton, secondButton, thirdButton ] =
+					screen.getAllByRole( 'button' );
+
+				return {
+					...view,
+					popover,
+					firstButton,
+					secondButton,
+					thirdButton,
+					user,
+				};
+			};
+
+			// Note: due to an issue in testing-library/user-event [1], the
+			// tests for constrained tabbing fail.
+			// [1]: https://github.com/testing-library/user-event/issues/1188
+			//
+			// eslint-disable-next-line jest/no-disabled-tests
+			describe.skip( 'constrains tabbing', () => {
+				test( 'by default', async () => {
+					// The default value for `focusOnMount` is 'firstElement',
+					// which means the default value for `constrainTabbing` is
+					// 'true'.
+
+					const { user, firstButton, secondButton, thirdButton } =
+						await setup();
+
+					await waitFor( () => expect( firstButton ).toHaveFocus() );
+					await user.tab();
+					expect( secondButton ).toHaveFocus();
+					await user.tab();
+					expect( thirdButton ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab( { shift: true } );
+					expect( thirdButton ).toHaveFocus();
+				} );
+
+				test( 'when `focusOnMount` is true', async () => {
+					const {
+						user,
+						popover,
+						firstButton,
+						secondButton,
+						thirdButton,
+					} = await setup( { focusOnMount: true } );
+
+					expect( popover ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab();
+					expect( secondButton ).toHaveFocus();
+					await user.tab();
+					expect( thirdButton ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab( { shift: true } );
+					expect( thirdButton ).toHaveFocus();
+				} );
+
+				test( 'when `focusOnMount` is "firstElement"', async () => {
+					const { user, firstButton, secondButton, thirdButton } =
+						await setup( { focusOnMount: 'firstElement' } );
+
+					await waitFor( () => expect( firstButton ).toHaveFocus() );
+					await user.tab();
+					expect( secondButton ).toHaveFocus();
+					await user.tab();
+					expect( thirdButton ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab( { shift: true } );
+					expect( thirdButton ).toHaveFocus();
+				} );
+
+				test( 'when `focusOnMount` is false if `constrainTabbing` is true', async () => {
+					const {
+						user,
+						baseElement,
+						firstButton,
+						secondButton,
+						thirdButton,
+					} = await setup( {
+						focusOnMount: false,
+						constrainTabbing: true,
+					} );
+
+					expect( baseElement ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab();
+					expect( secondButton ).toHaveFocus();
+					await user.tab();
+					expect( thirdButton ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab( { shift: true } );
+					expect( thirdButton ).toHaveFocus();
+				} );
+			} );
+
+			describe( 'does not constrain tabbing', () => {
+				test( 'when `constrainTabbing` is false', async () => {
+					// The default value for `focusOnMount` is 'firstElement',
+					// which means the default value for `constrainTabbing` is
+					// 'true', but the provided value should override this.
+
+					const {
+						user,
+						baseElement,
+						firstButton,
+						secondButton,
+						thirdButton,
+					} = await setup( { constrainTabbing: false } );
+
+					await waitFor( () => expect( firstButton ).toHaveFocus() );
+					await user.tab();
+					expect( secondButton ).toHaveFocus();
+					await user.tab();
+					expect( thirdButton ).toHaveFocus();
+					await user.tab();
+					expect( baseElement ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab( { shift: true } );
+					expect( baseElement ).toHaveFocus();
+				} );
+
+				test( 'when `focusOnMount` is false', async () => {
+					const {
+						user,
+						baseElement,
+						firstButton,
+						secondButton,
+						thirdButton,
+					} = await setup( { focusOnMount: false } );
+
+					expect( baseElement ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab();
+					expect( secondButton ).toHaveFocus();
+					await user.tab();
+					expect( thirdButton ).toHaveFocus();
+					await user.tab();
+					expect( baseElement ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab( { shift: true } );
+					expect( baseElement ).toHaveFocus();
+				} );
+
+				test( 'when `focusOnMount` is true if `constrainTabbing` is false', async () => {
+					const {
+						user,
+						baseElement,
+						popover,
+						firstButton,
+						secondButton,
+						thirdButton,
+					} = await setup( {
+						focusOnMount: true,
+						constrainTabbing: false,
+					} );
+
+					expect( popover ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab();
+					expect( secondButton ).toHaveFocus();
+					await user.tab();
+					expect( thirdButton ).toHaveFocus();
+					await user.tab();
+					expect( baseElement ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab( { shift: true } );
+					expect( baseElement ).toHaveFocus();
+				} );
+
+				test( 'when `focusOnMount` is "firstElement" if `constrainTabbing` is false', async () => {
+					const {
+						user,
+						baseElement,
+						firstButton,
+						secondButton,
+						thirdButton,
+					} = await setup( {
+						focusOnMount: 'firstElement',
+						constrainTabbing: false,
+					} );
+
+					await waitFor( () => expect( firstButton ).toHaveFocus() );
+					await user.tab();
+					expect( secondButton ).toHaveFocus();
+					await user.tab();
+					expect( thirdButton ).toHaveFocus();
+					await user.tab();
+					expect( baseElement ).toHaveFocus();
+					await user.tab();
+					expect( firstButton ).toHaveFocus();
+					await user.tab( { shift: true } );
+					expect( baseElement ).toHaveFocus();
+				} );
+			} );
+		} );
 	} );
 
 	describe( 'Slot outside iframe', () => {

package/src/popover/types.ts

@@ -65,6 +65,15 @@ export type PopoverProps = {
 	 * @default true
 	 */
 	flip?: boolean;
+	/**
+	 * Determines whether tabbing is constrained to within the popover,
+	 * preventing keyboard focus from leaving the popover content without
+	 * explicit focus elswhere, or whether the popover remains part of the wider
+	 * tab order. If no value is passed, it will be derived from `focusOnMount`.
+	 *
+	 * @default `focusOnMount` !== false
+	 */
+	constrainTabbing?: boolean;
 	/**
 	 * By default, the _first tabbable element_ in the popover will receive focus
 	 * when it mounts. This is the same as setting this prop to `"firstElement"`.

package/src/progress-bar/stories/index.story.tsx

@@ -15,6 +15,7 @@ const meta: Meta< typeof ProgressBar > = {
 		value: { control: { type: 'number', min: 0, max: 100, step: 1 } },
 	},
 	parameters: {
+		badges: [ 'private' ],
 		controls: {
 			expanded: true,
 		},

package/src/query-controls/index.native.js

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { __ } from '@wordpress/i18n';
+import { __, _x } from '@wordpress/i18n';
 import { useCallback, memo } from '@wordpress/element';
 
 /**
@@ -23,12 +23,12 @@ const options = [
 		value: 'date/asc',
 	},
 	{
-		/* translators: label for ordering posts by title in ascending order */
+		/* translators: Label for ordering posts by title in ascending order. */
 		label: __( 'A → Z' ),
 		value: 'title/asc',
 	},
 	{
-		/* translators: label for ordering posts by title in descending order */
+		/* translators: Label for ordering posts by title in descending order. */
 		label: __( 'Z → A' ),
 		value: 'title/desc',
 	},
@@ -76,7 +76,7 @@ const QueryControls = memo(
 					<CategorySelect
 						categoriesList={ categoriesList }
 						label={ __( 'Category' ) }
-						noOptionLabel={ __( 'All' ) }
+						noOptionLabel={ _x( 'All', 'categories' ) }
 						selectedCategoryId={ selectedCategoryId }
 						onChange={ onCategoryChange }
 						hideCancelButton={ true }

package/src/query-controls/index.tsx

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { __ } from '@wordpress/i18n';
+import { __, _x } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
@@ -96,12 +96,12 @@ export function QueryControls( {
 								value: 'date/asc',
 							},
 							{
-								/* translators: label for ordering posts by title in ascending order */
+								/* translators: Label for ordering posts by title in ascending order. */
 								label: __( 'A → Z' ),
 								value: 'title/asc',
 							},
 							{
-								/* translators: label for ordering posts by title in descending order */
+								/* translators: Label for ordering posts by title in descending order. */
 								label: __( 'Z → A' ),
 								value: 'title/desc',
 							},
@@ -137,7 +137,7 @@ export function QueryControls( {
 							key="query-controls-category-select"
 							categoriesList={ props.categoriesList }
 							label={ __( 'Category' ) }
-							noOptionLabel={ __( 'All' ) }
+							noOptionLabel={ _x( 'All', 'categories' ) }
 							selectedCategoryId={ props.selectedCategoryId }
 							onChange={ props.onCategoryChange }
 						/>
@@ -174,7 +174,7 @@ export function QueryControls( {
 						key="query-controls-author-select"
 						authorList={ authorList }
 						label={ __( 'Author' ) }
-						noOptionLabel={ __( 'All' ) }
+						noOptionLabel={ _x( 'All', 'authors' ) }
 						selectedAuthorId={ selectedAuthorId }
 						onChange={ onAuthorChange }
 					/>

package/src/resizable-box/resize-tooltip/styles/resize-tooltip.styles.ts

@@ -30,12 +30,12 @@ export const TooltipWrapper = styled.div`
 `;
 
 export const Tooltip = styled.div`
-	background: ${ COLORS.gray[ 900 ] };
+	background: ${ COLORS.theme.foreground };
 	border-radius: 2px;
 	box-sizing: border-box;
 	font-family: ${ font( 'default.fontFamily' ) };
 	font-size: 12px;
-	color: ${ COLORS.ui.textDark };
+	color: ${ COLORS.theme.foregroundInverted };
 	padding: 4px 8px;
 	position: relative;
 `;
@@ -45,7 +45,7 @@ export const Tooltip = styled.div`
 
 export const LabelText = styled( Text )`
 	&&& {
-		color: ${ COLORS.ui.textDark };
+		color: ${ COLORS.theme.foregroundInverted };
 		display: block;
 		font-size: 13px;
 		line-height: 1.4;

package/src/search-control/README.md

@@ -20,6 +20,7 @@ function MySearchControl( { className, setState } ) {
 
     return (
         <SearchControl
+            __nextHasNoMarginBottom
             label={ __( 'Search posts' ) }
             value={ searchInput }
             onChange={ setSearchInput }
@@ -35,13 +36,14 @@ Props not included in this set will be applied to the input element.
 
 #### label
 
-If this property is added, a label will be generated using label property as the content.
+The accessible label for the input.
 
 A label should always be provided as an accessibility best practice, even when a placeholder is defined
 and `hideLabelFromVision` is `true`.
 
 -   Type: `String`
--   Required: Yes
+-   Required: No
+-   Default: `__( 'Search' )`
 
 #### placeholder
 
@@ -72,6 +74,15 @@ A function that receives the value of the input.
 -   Type: `function`
 -   Required: Yes
 
+#### onClose
+
+When an `onClose` callback is provided, the search control will render a close button that will trigger the given callback.
+
+Use this if you want the button to trigger your own logic to close the search field entirely, rather than just clearing the input value.
+
+-   Type: `function`
+-   Required: No
+
 #### help
 
 If this property is added, a help text will be generated using help property as the content.
@@ -79,12 +90,21 @@ If this property is added, a help text will be generated using help property as
 -   Type: `String|Element`
 -   Required: No
 
-### hideLabelFromVision
+#### hideLabelFromVision
 
 If true, the label will not be visible, but will be read by screen readers. Defaults to `true`.
 
 -   Type: `Boolean`
 -   Required: No
+-   Default: `true`
+
+#### __nextHasNoMarginBottom
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`
 
 #### `size`: `'default'` | `'compact'`
 

package/src/search-control/index.tsx

@@ -9,100 +9,117 @@ import classnames from 'classnames';
 import { useInstanceId, useMergeRefs } from '@wordpress/compose';
 import { __ } from '@wordpress/i18n';
 import { Icon, search, closeSmall } from '@wordpress/icons';
-import { forwardRef, useRef } from '@wordpress/element';
+import { forwardRef, useMemo, useRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import Button from '../button';
-import BaseControl from '../base-control';
 import type { WordPressComponentProps } from '../context/wordpress-component';
-import type { SearchControlProps } from './types';
+import type { SearchControlProps, SuffixItemProps } from './types';
 import type { ForwardedRef } from 'react';
+import { ContextSystemProvider } from '../context';
+import { StyledInputControl, SuffixItemWrapper } from './styles';
+
+function SuffixItem( {
+	searchRef,
+	value,
+	onChange,
+	onClose,
+}: SuffixItemProps ) {
+	if ( ! onClose && ! value ) {
+		return <Icon icon={ search } />;
+	}
+
+	const onReset = () => {
+		onChange( '' );
+		searchRef.current?.focus();
+	};
+
+	return (
+		<Button
+			size="small"
+			icon={ closeSmall }
+			label={ onClose ? __( 'Close search' ) : __( 'Reset search' ) }
+			onClick={ onClose ?? onReset }
+		/>
+	);
+}
 
 function UnforwardedSearchControl(
 	{
-		__nextHasNoMarginBottom,
-		__next40pxDefaultSize = false,
+		__nextHasNoMarginBottom = false,
 		className,
 		onChange,
-		onKeyDown,
 		value,
-		label,
+		label = __( 'Search' ),
 		placeholder = __( 'Search' ),
 		hideLabelFromVision = true,
-		help,
 		onClose,
 		size = 'default',
 		...restProps
-	}: WordPressComponentProps< SearchControlProps, 'input', false >,
+	}: Omit<
+		WordPressComponentProps< SearchControlProps, 'input', false >,
+		// TODO: Background styling currently doesn't support a disabled state. Needs design work.
+		'disabled'
+	>,
 	forwardedRef: ForwardedRef< HTMLInputElement >
 ) {
-	const searchRef = useRef< HTMLInputElement >();
-	const instanceId = useInstanceId( SearchControl );
-	const id = `components-search-control-${ instanceId }`;
-
-	const renderRightButton = () => {
-		if ( onClose ) {
-			return (
-				<Button
-					__next40pxDefaultSize={ __next40pxDefaultSize }
-					icon={ closeSmall }
-					label={ __( 'Close search' ) }
-					onClick={ onClose }
-					size={ size }
-				/>
-			);
-		}
+	// @ts-expect-error The `disabled` prop is not yet supported in the SearchControl component.
+	// Work with the design team (@WordPress/gutenberg-design) if you need this feature.
+	delete restProps.disabled;
 
-		if ( !! value ) {
-			return (
-				<Button
-					__next40pxDefaultSize={ __next40pxDefaultSize }
-					icon={ closeSmall }
-					label={ __( 'Reset search' ) }
-					onClick={ () => {
-						onChange( '' );
-						searchRef.current?.focus();
-					} }
-					size={ size }
-				/>
-			);
-		}
+	const searchRef = useRef< HTMLInputElement >( null );
+	const instanceId = useInstanceId(
+		SearchControl,
+		'components-search-control'
+	);
 
-		return <Icon icon={ search } />;
-	};
+	const contextValue = useMemo(
+		() => ( {
+			// Overrides the underlying BaseControl `__nextHasNoMarginBottom` via the context system
+			// to provide backwards compatibile margin for SearchControl.
+			// (In a standard InputControl, the BaseControl `__nextHasNoMarginBottom` is always set to true.)
+			BaseControl: { _overrides: { __nextHasNoMarginBottom } },
+			// `isBorderless` is still experimental and not a public prop for InputControl yet.
+			InputBase: { isBorderless: true },
+		} ),
+		[ __nextHasNoMarginBottom ]
+	);
 
 	return (
-		<BaseControl
-			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
-			label={ label }
-			id={ id }
-			hideLabelFromVision={ hideLabelFromVision }
-			help={ help }
-			className={ classnames( className, 'components-search-control', {
-				'is-next-40px-default-size': __next40pxDefaultSize,
-				'is-size-compact': size === 'compact',
-			} ) }
-		>
-			<div className="components-search-control__input-wrapper">
-				<input
-					{ ...restProps }
-					ref={ useMergeRefs( [ searchRef, forwardedRef ] ) }
-					className="components-search-control__input"
-					id={ id }
-					type="search"
-					placeholder={ placeholder }
-					onChange={ ( event ) => onChange( event.target.value ) }
-					onKeyDown={ onKeyDown }
-					autoComplete="off"
-					value={ value || '' }
-				/>
-				<div className="components-search-control__icon">
-					{ renderRightButton() }
-				</div>
-			</div>
-		</BaseControl>
+		<ContextSystemProvider value={ contextValue }>
+			<StyledInputControl
+				__next40pxDefaultSize
+				id={ instanceId }
+				hideLabelFromVision={ hideLabelFromVision }
+				label={ label }
+				ref={ useMergeRefs( [ searchRef, forwardedRef ] ) }
+				type="search"
+				size={ size }
+				className={ classnames(
+					'components-search-control',
+					className
+				) }
+				onChange={ ( nextValue?: string ) =>
+					onChange( nextValue ?? '' )
+				}
+				autoComplete="off"
+				placeholder={ placeholder }
+				value={ value ?? '' }
+				suffix={
+					<SuffixItemWrapper size={ size }>
+						<SuffixItem
+							searchRef={ searchRef }
+							value={ value }
+							onChange={ onChange }
+							onClose={ onClose }
+						/>
+					</SuffixItemWrapper>
+				}
+				{ ...restProps }
+			/>
+		</ContextSystemProvider>
 	);
 }
 
@@ -118,6 +135,7 @@ function UnforwardedSearchControl(
  *
  *   return (
  *     <SearchControl
+ *       __nextHasNoMarginBottom
  *       value={ searchInput }
  *       onChange={ setSearchInput }
  *     />

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

@@ -18,6 +18,7 @@ const meta: Meta< typeof SearchControl > = {
 	component: SearchControl,
 	argTypes: {
 		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
 	},
 	parameters: {
 		controls: { expanded: true },
@@ -46,7 +47,6 @@ const Template: StoryFn< typeof SearchControl > = ( {
 
 export const Default = Template.bind( {} );
 Default.args = {
-	label: 'Label Text',
 	help: 'Help text to explain the input.',
 };