@wordpress/components 28.5.0 → 28.7.0

package/src/navigator/types.ts

@@ -11,26 +11,72 @@ import type { ButtonAsButtonProps } from '../button/types';
 export type MatchParams = Record< string, string | string[] >;
 
 export type NavigateOptions = {
+	/**
+	 * Specify the CSS selector used to restore focus on an given element when
+	 * navigating back. When not provided, the component will attempt to restore
+	 * focus on the element that originated the forward navigation.
+	 */
 	focusTargetSelector?: string;
+	/**
+	 * Whether the navigation is a backwards navigation. This enables focus
+	 * restoration (when possible), and causes the animation to be backwards.
+	 */
 	isBack?: boolean;
+	/**
+	 * Opt out of focus management. Useful when the consumer of the component
+	 * wants to manage focus themselves.
+	 */
 	skipFocus?: boolean;
+	/**
+	 * Note: this option is deprecated and currently doesn't have any effect.
+	 * @deprecated
+	 * @ignore
+	 */
 	replace?: boolean;
 };
 
 export type NavigateToParentOptions = Omit< NavigateOptions, 'isBack' >;
 
 export type NavigatorLocation = NavigateOptions & {
+	/**
+	 * Whether the current location is the initial one (ie. first in the stack).
+	 */
 	isInitial?: boolean;
+	/**
+	 * The path associated to the location.
+	 */
 	path?: string;
+	/**
+	 * Whether focus was already restored for this location (in case of
+	 * backwards navigation).
+	 */
 	hasRestoredFocus?: boolean;
 };
 
 // Returned by the `useNavigator` hook.
 export type Navigator = {
+	/**
+	 * The current location.
+	 */
 	location: NavigatorLocation;
+	/**
+	 * Params associated with the current location
+	 */
 	params: MatchParams;
+	/**
+	 * Navigate to a new location.
+	 */
 	goTo: ( path: string, options?: NavigateOptions ) => void;
-	goBack: () => void;
+	/**
+	 * Go back to the parent location (ie. "/some/path" will navigate back
+	 * to "/some")
+	 */
+	goBack: ( options?: NavigateToParentOptions ) => void;
+	/**
+	 * _Note: This function is deprecated. Please use `goBack` instead._
+	 * @deprecated
+	 * @ignore
+	 */
 	goToParent: ( options?: NavigateToParentOptions ) => void;
 };
 
@@ -64,15 +110,6 @@ export type NavigatorScreenProps = {
 
 export type NavigatorBackButtonProps = ButtonAsButtonProps;
 
-export type NavigatorBackButtonHookProps = NavigatorBackButtonProps & {
-	/**
-	 * Whether we should navigate to the parent screen.
-	 *
-	 * @default 'false'
-	 */
-	goToParent?: boolean;
-};
-
 export type NavigatorToParentButtonProps = NavigatorBackButtonProps;
 
 export type NavigatorButtonProps = NavigatorBackButtonProps & {

package/src/navigator/use-navigator.ts

@@ -12,7 +12,7 @@ import type { Navigator } from './types';
 /**
  * Retrieves a `navigator` instance.
  */
-function useNavigator(): Navigator {
+export function useNavigator(): Navigator {
 	const { location, params, goTo, goBack, goToParent } =
 		useContext( NavigatorContext );
 
@@ -24,5 +24,3 @@ function useNavigator(): Navigator {
 		params,
 	};
 }
-
-export default useNavigator;

package/src/number-control/README.md

@@ -139,3 +139,11 @@ Amount by which the `value` is changed when incrementing/decrementing. It is als
 -   Type: `Number | "any"`
 -   Required: No
 -   Default: `1`
+
+### __next40pxDefaultSize
+
+Start opting into the larger default height that will become the default size in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`

package/src/palette-edit/index.tsx

@@ -275,9 +275,9 @@ function PaletteEditListView< T extends Color | Gradient >( {
 	addColorRef,
 }: PaletteEditListViewProps< T > ) {
 	// When unmounting the component if there are empty elements (the user did not complete the insertion) clean them.
-	const elementsReference = useRef< typeof elements >();
+	const elementsReferenceRef = useRef< typeof elements >();
 	useEffect( () => {
-		elementsReference.current = elements;
+		elementsReferenceRef.current = elements;
 	}, [ elements ] );
 
 	const debounceOnChange = useDebounce( onChange, 100 );

package/src/palette-edit/styles.ts

@@ -31,7 +31,7 @@ export const IndicatorStyled = styled( ColorIndicator )`
 export const NameInputControl = styled( InputControl )`
 	${ InputControlContainer } {
 		background: ${ COLORS.gray[ 100 ] };
-		border-radius: ${ CONFIG.controlBorderRadius };
+		border-radius: ${ CONFIG.radiusXSmall };
 		${ Input }${ Input }${ Input }${ Input } {
 			height: ${ space( 8 ) };
 		}
@@ -85,8 +85,8 @@ export const PaletteItem = styled( View )`
 		outline-offset: 0;
 	}
 
-	border-top-left-radius: ${ CONFIG.controlBorderRadius };
-	border-top-right-radius: ${ CONFIG.controlBorderRadius };
+	border-top-left-radius: ${ CONFIG.radiusSmall };
+	border-top-right-radius: ${ CONFIG.radiusSmall };
 
 	& + & {
 		border-top-left-radius: 0;
@@ -94,8 +94,8 @@ export const PaletteItem = styled( View )`
 	}
 
 	&:last-child {
-		border-bottom-left-radius: ${ CONFIG.controlBorderRadius };
-		border-bottom-right-radius: ${ CONFIG.controlBorderRadius };
+		border-bottom-left-radius: ${ CONFIG.radiusSmall };
+		border-bottom-right-radius: ${ CONFIG.radiusSmall };
 		border-bottom-color: ${ CONFIG.surfaceBorderColor };
 	}
 

package/src/placeholder/style.scss

@@ -19,7 +19,7 @@
 
 
 	// Block UI appearance.
-	border-radius: $radius-block-ui;
+	border-radius: $radius-small;	// Match the block toolbar material radius.
 	background-color: $white;
 	box-shadow: inset 0 0 0 $border-width $gray-900;
 	outline: 1px solid transparent; // Shown for Windows 10 High Contrast mode.
@@ -144,6 +144,9 @@
 	display: flex;
 	box-shadow: none;
 
+	// In the unselected state, radius should match Global Styles > Image > Radius.
+	border-radius: 0;
+
 	// Blur the background so layered dashed placeholders are still visually separate.
 	// Make the background transparent to not interfere with the background overlay in placeholder-style() pseudo element
 	backdrop-filter: blur(100px);

package/src/popover/index.tsx

@@ -113,8 +113,9 @@ const UnforwardedPopover = (
 		WordPressComponentProps< PopoverProps, 'div', false >,
 		// To avoid overlaps between the standard HTML attributes and the props
 		// expected by `framer-motion`, omit all framer motion props from popover
-		// props (except for `animate` and `children`, which are re-defined in `PopoverProps`).
-		keyof Omit< MotionProps, 'animate' | 'children' >
+		// props (except for `animate` and `children` which are re-defined in
+		// `PopoverProps`, and `style` which is merged safely).
+		keyof Omit< MotionProps, 'animate' | 'children' | 'style' >
 	>,
 	forwardedRef: ForwardedRef< any >
 ) => {
@@ -139,6 +140,7 @@ const UnforwardedPopover = (
 		shift = false,
 		inline = false,
 		variant,
+		style: contentStyle,
 
 		// Deprecated props
 		__unstableForcePosition,
@@ -370,6 +372,7 @@ const UnforwardedPopover = (
 	const animationProps: HTMLMotionProps< 'div' > = shouldAnimate
 		? {
 				style: {
+					...contentStyle,
 					...motionInlineStyles,
 					...style,
 				},
@@ -378,7 +381,10 @@ const UnforwardedPopover = (
 		  }
 		: {
 				animate: false,
-				style,
+				style: {
+					...contentStyle,
+					...style,
+				},
 		  };
 
 	// When Floating UI has finished positioning and Framer Motion has finished animating

package/src/popover/style.scss

@@ -22,8 +22,8 @@ $shadow-popover-border-top-only-alternate: 0 #{-$border-width} 0 $gray-900;
 
 .components-popover__content {
 	background: $white;
-	box-shadow: $shadow-popover-border-default, $shadow-popover;
-	border-radius: $radius-block-ui;
+	box-shadow: $shadow-popover-border-default, $elevation-x-small;
+	border-radius: $radius-medium;
 	box-sizing: border-box;
 	width: min-content;
 

package/src/popover/test/index.tsx

@@ -179,6 +179,40 @@ describe( 'Popover', () => {
 			} );
 		} );
 
+		describe( 'style', () => {
+			it( 'outputs inline styles added through the style prop in addition to built-in popover positioning styles', async () => {
+				render(
+					<Popover
+						style={ { zIndex: 0 } }
+						data-testid="popover-element"
+					>
+						Hello
+					</Popover>
+				);
+				const popover = screen.getByTestId( 'popover-element' );
+
+				await waitFor( () => expect( popover ).toBeVisible() );
+				expect( popover ).toHaveStyle(
+					'position: absolute; top: 0px; left: 0px; z-index: 0;'
+				);
+			} );
+
+			it( 'is not possible to override built-in popover positioning styles via the style prop', async () => {
+				render(
+					<Popover
+						style={ { position: 'static' } }
+						data-testid="popover-element"
+					>
+						Hello
+					</Popover>
+				);
+				const popover = screen.getByTestId( 'popover-element' );
+
+				await waitFor( () => expect( popover ).toBeVisible() );
+				expect( popover ).not.toHaveStyle( 'position: static;' );
+			} );
+		} );
+
 		describe( 'focus behavior', () => {
 			it( 'should focus the popover container when opened', async () => {
 				render(

package/src/private-apis.ts

@@ -1,25 +1,11 @@
 /**
  * Internal dependencies
  */
-import {
-	Composite as CompositeV2,
-	CompositeGroup as CompositeGroupV2,
-	CompositeItem as CompositeItemV2,
-	CompositeRow as CompositeRowV2,
-	useCompositeStore as useCompositeStoreV2,
-} from './composite/v2';
+import { Composite } from './composite';
+import { useCompositeStore } from './composite/store';
 import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
 import { createPrivateSlotFill } from './slot-fill';
-import {
-	DropdownMenu as DropdownMenuV2,
-	DropdownMenuGroup as DropdownMenuGroupV2,
-	DropdownMenuItem as DropdownMenuItemV2,
-	DropdownMenuCheckboxItem as DropdownMenuCheckboxItemV2,
-	DropdownMenuRadioItem as DropdownMenuRadioItemV2,
-	DropdownMenuSeparator as DropdownMenuSeparatorV2,
-	DropdownMenuItemLabel as DropdownMenuItemLabelV2,
-	DropdownMenuItemHelpText as DropdownMenuItemHelpTextV2,
-} from './dropdown-menu-v2';
+import { DropdownMenuV2 } from './dropdown-menu-v2';
 import { ComponentsContext } from './context/context-system-provider';
 import Theme from './theme';
 import Tabs from './tabs';
@@ -28,23 +14,18 @@ import { lock } from './lock-unlock';
 
 export const privateApis = {};
 lock( privateApis, {
-	CompositeV2,
-	CompositeGroupV2,
-	CompositeItemV2,
-	CompositeRowV2,
-	useCompositeStoreV2,
+	CompositeV2: Composite,
+	CompositeGroupV2: Composite.Group,
+	CompositeItemV2: Composite.Item,
+	CompositeRowV2: Composite.Row,
+	CompositeTypeaheadV2: Composite.Typeahead,
+	CompositeHoverV2: Composite.Hover,
+	useCompositeStoreV2: useCompositeStore,
 	__experimentalPopoverLegacyPositionToPlacement,
 	createPrivateSlotFill,
 	ComponentsContext,
 	Tabs,
 	Theme,
 	DropdownMenuV2,
-	DropdownMenuGroupV2,
-	DropdownMenuItemV2,
-	DropdownMenuCheckboxItemV2,
-	DropdownMenuRadioItemV2,
-	DropdownMenuSeparatorV2,
-	DropdownMenuItemLabelV2,
-	DropdownMenuItemHelpTextV2,
 	kebabCase,
 } );

package/src/progress-bar/styles.ts

@@ -40,7 +40,7 @@ export const Track = styled.div`
 		${ COLORS.theme.foreground },
 		transparent 90%
 	);
-	border-radius: ${ CONFIG.radiusBlockUi };
+	border-radius: ${ CONFIG.radiusFull };
 
 	// Windows high contrast mode.
 	outline: 2px solid transparent;
@@ -58,7 +58,7 @@ export const Indicator = styled.div< {
 	position: absolute;
 	top: 0;
 	height: 100%;
-	border-radius: ${ CONFIG.radiusBlockUi };
+	border-radius: ${ CONFIG.radiusFull };
 	/* Text color at 90% opacity */
 	background-color: color-mix(
 		in srgb,

package/src/query-controls/README.md

@@ -240,3 +240,10 @@ The selected category for the `categoriesList` prop.
 
 -   Required: No
 -   Platform: Web
+
+#### `__next40pxDefaultSize`: `boolean`
+
+Start opting into the larger default height that will become the default size in a future version.
+
+- Required: No
+- Default: `false`

package/src/query-controls/index.tsx

@@ -60,7 +60,6 @@ function isMultipleCategorySelection(
  * ```
  */
 export function QueryControls( {
-	__next40pxDefaultSize = false,
 	authorList,
 	selectedAuthorId,
 	numberOfItems,
@@ -82,7 +81,7 @@ export function QueryControls( {
 				onOrderChange && onOrderByChange && (
 					<SelectControl
 						__nextHasNoMarginBottom
-						__next40pxDefaultSize={ __next40pxDefaultSize }
+						__next40pxDefaultSize
 						key="query-controls-order-select"
 						label={ __( 'Order by' ) }
 						value={
@@ -137,7 +136,7 @@ export function QueryControls( {
 					props.categoriesList &&
 					props.onCategoryChange && (
 						<CategorySelect
-							__next40pxDefaultSize={ __next40pxDefaultSize }
+							__next40pxDefaultSize
 							key="query-controls-category-select"
 							categoriesList={ props.categoriesList }
 							label={ __( 'Category' ) }
@@ -150,7 +149,7 @@ export function QueryControls( {
 					props.categorySuggestions &&
 					props.onCategoryChange && (
 						<FormTokenField
-							__next40pxDefaultSize={ __next40pxDefaultSize }
+							__next40pxDefaultSize
 							__nextHasNoMarginBottom
 							key="query-controls-categories-select"
 							label={ __( 'Categories' ) }
@@ -174,7 +173,7 @@ export function QueryControls( {
 					),
 				onAuthorChange && (
 					<AuthorSelect
-						__next40pxDefaultSize={ __next40pxDefaultSize }
+						__next40pxDefaultSize
 						key="query-controls-author-select"
 						authorList={ authorList }
 						label={ __( 'Author' ) }
@@ -186,7 +185,7 @@ export function QueryControls( {
 				onNumberOfItemsChange && (
 					<RangeControl
 						__nextHasNoMarginBottom
-						__next40pxDefaultSize={ __next40pxDefaultSize }
+						__next40pxDefaultSize
 						key="query-controls-range-control"
 						label={ __( 'Number of items' ) }
 						value={ numberOfItems }

package/src/query-controls/types.ts

@@ -107,7 +107,8 @@ type BaseQueryControlsProps = {
 	 * Start opting into the larger default height that will become the
 	 * default size in a future version.
 	 *
-	 * @default false
+	 * @deprecated Default behavior since WP 6.7. Prop can be safely removed.
+	 * @ignore
 	 */
 	__next40pxDefaultSize?: boolean;
 };

package/src/radio-control/index.tsx

@@ -16,8 +16,8 @@ import BaseControl from '../base-control';
 import type { WordPressComponentProps } from '../context';
 import type { RadioControlProps } from './types';
 import { VStack } from '../v-stack';
-import { useBaseControlProps } from '../base-control/hooks';
 import { StyledHelp } from '../base-control/styles/base-control-styles';
+import { VisuallyHidden } from '../visually-hidden';
 
 function generateOptionDescriptionId( radioGroupId: string, index: number ) {
 	return `${ radioGroupId }-${ index }-option-description`;
@@ -27,6 +27,10 @@ function generateOptionId( radioGroupId: string, index: number ) {
 	return `${ radioGroupId }-${ index }`;
 }
 
+function generateHelpId( radioGroupId: string ) {
+	return `${ radioGroupId }__help`;
+}
+
 /**
  * Render a user interface to select the user type using radio inputs.
  *
@@ -75,24 +79,24 @@ export function RadioControl(
 	const onChangeValue = ( event: ChangeEvent< HTMLInputElement > ) =>
 		onChange( event.target.value );
 
-	// Use `useBaseControlProps` to get the id of the help text.
-	const {
-		controlProps: { 'aria-describedby': helpTextId },
-	} = useBaseControlProps( { id, help } );
-
 	if ( ! options?.length ) {
 		return null;
 	}
 
 	return (
-		<BaseControl
-			__nextHasNoMarginBottom
-			label={ label }
+		<fieldset
 			id={ id }
-			hideLabelFromVision={ hideLabelFromVision }
-			help={ help }
 			className={ clsx( className, 'components-radio-control' ) }
+			aria-describedby={ !! help ? generateHelpId( id ) : undefined }
 		>
+			{ hideLabelFromVision ? (
+				<VisuallyHidden as="legend">{ label }</VisuallyHidden>
+			) : (
+				<BaseControl.VisualLabel as="legend">
+					{ label }
+				</BaseControl.VisualLabel>
+			) }
+
 			<VStack
 				spacing={ 3 }
 				className={ clsx( 'components-radio-control__group-wrapper', {
@@ -113,14 +117,9 @@ export function RadioControl(
 							onChange={ onChangeValue }
 							checked={ option.value === selected }
 							aria-describedby={
-								clsx( [
-									!! option.description &&
-										generateOptionDescriptionId(
-											id,
-											index
-										),
-									helpTextId,
-								] ) || undefined
+								!! option.description
+									? generateOptionDescriptionId( id, index )
+									: undefined
 							}
 							{ ...additionalProps }
 						/>
@@ -142,7 +141,16 @@ export function RadioControl(
 					</div>
 				) ) }
 			</VStack>
-		</BaseControl>
+			{ !! help && (
+				<StyledHelp
+					__nextHasNoMarginBottom
+					id={ generateHelpId( id ) }
+					className="components-base-control__help"
+				>
+					{ help }
+				</StyledHelp>
+			) }
+		</fieldset>
 	);
 }
 

package/src/radio-control/style.scss

@@ -1,3 +1,12 @@
+.components-radio-control {
+	border: 0;
+	margin: 0;
+	padding: 0;
+
+	font-family: $default-font;
+	font-size: $default-font-size;
+}
+
 .components-radio-control__group-wrapper.has-help {
 	margin-block-end: $grid-unit-15;
 }
@@ -32,7 +41,7 @@
 
 		&::before {
 			content: "";
-			border-radius: 50%;
+			border-radius: $radius-round;
 		}
 	}
 }
@@ -57,5 +66,7 @@
 
 	// Override the top margin of the StyledHelp component from BaseControl.
 	// TODO: we should tweak the StyledHelp component to not have a top margin.
-	margin-top: 0;
+	&.components-radio-control__option-description {
+		margin-top: 0;
+	}
 }

package/src/radio-control/test/index.tsx

@@ -56,6 +56,47 @@ describe.each( [
 	const [ , Component ] = modeAndComponent;
 
 	describe( 'semantics and labelling', () => {
+		it( 'should group all radios under a fieldset with an accessible label (legend)', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component { ...defaultProps } onChange={ onChangeSpy } />
+			);
+
+			expect(
+				screen.getByRole( 'group', { name: defaultProps.label } )
+			).toBeVisible();
+		} );
+
+		it( 'should group all radios under a fieldset with an accessible label even when the label is visually hidden', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component
+					{ ...defaultProps }
+					hideLabelFromVision
+					onChange={ onChangeSpy }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'group', { name: defaultProps.label } )
+			).toBeVisible();
+		} );
+
+		it( 'should describe the radio group with the help text', () => {
+			const onChangeSpy = jest.fn();
+			render(
+				<Component
+					{ ...defaultProps }
+					help="Test help text"
+					onChange={ onChangeSpy }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'group', { name: defaultProps.label } )
+			).toHaveAccessibleDescription( 'Test help text' );
+		} );
+
 		it( 'should render radio inputs with accessible labels', () => {
 			const onChangeSpy = jest.fn();
 			render(
@@ -101,46 +142,7 @@ describe.each( [
 			).toHaveAccessibleName( defaultProps.options[ 1 ].label );
 		} );
 
-		it( 'should use the group help text to describe individual options', () => {
-			const onChangeSpy = jest.fn();
-			render(
-				<Component
-					{ ...defaultProps }
-					onChange={ onChangeSpy }
-					selected={ defaultProps.options[ 1 ].value }
-					help="Select your favorite animal."
-				/>
-			);
-
-			for ( const option of defaultProps.options ) {
-				expect(
-					screen.getByRole( 'radio', { name: option.label } )
-				).toHaveAccessibleDescription( 'Select your favorite animal.' );
-			}
-		} );
-
 		it( 'should use the option description text to describe individual options', () => {
-			const onChangeSpy = jest.fn();
-			render(
-				<Component
-					{ ...defaultPropsWithDescriptions }
-					onChange={ onChangeSpy }
-					selected={ defaultProps.options[ 1 ].value }
-				/>
-			);
-
-			let index = 1;
-			for ( const option of defaultProps.options ) {
-				expect(
-					screen.getByRole( 'radio', { name: option.label } )
-				).toHaveAccessibleDescription(
-					`This is the option number ${ index }.`
-				);
-				index += 1;
-			}
-		} );
-
-		it( 'should use both the option description text and the group help text to describe individual options', () => {
 			const onChangeSpy = jest.fn();
 			render(
 				<Component
@@ -151,12 +153,13 @@ describe.each( [
 				/>
 			);
 
+			// Group help text should not be used to describe individual options.
 			let index = 1;
 			for ( const option of defaultProps.options ) {
 				expect(
 					screen.getByRole( 'radio', { name: option.label } )
 				).toHaveAccessibleDescription(
-					`This is the option number ${ index }. Select your favorite animal`
+					`This is the option number ${ index }.`
 				);
 				index += 1;
 			}

package/src/radio-group/radio.tsx

@@ -7,6 +7,7 @@ import { forwardRef, useContext } from '@wordpress/element';
  * External dependencies
  */
 import * as Ariakit from '@ariakit/react';
+import { useStoreState } from '@ariakit/react';
 
 /**
  * Internal dependencies
@@ -26,7 +27,7 @@ function UnforwardedRadio(
 ) {
 	const { store, disabled } = useContext( RadioGroupContext );
 
-	const selectedValue = store?.useState( 'value' );
+	const selectedValue = useStoreState( store, 'value' );
 	const isChecked = selectedValue !== undefined && selectedValue === value;
 
 	return (