@wordpress/components 28.5.0 → 28.6.0

package/src/navigator/navigator-provider/component.tsx

@@ -27,12 +27,12 @@ import type {
 	Screen,
 	NavigateToParentOptions,
 } from '../types';
+import deprecated from '@wordpress/deprecated';
 
 type MatchedPath = ReturnType< typeof patternMatch >;
 
 type RouterAction =
 	| { type: 'add' | 'remove'; screen: Screen }
-	| { type: 'goback' }
 	| { type: 'goto'; path: string; options?: NavigateOptions }
 	| { type: 'gotoparent'; options?: NavigateToParentOptions };
 
@@ -160,9 +160,6 @@ function routerReducer(
 		case 'remove':
 			screens = removeScreen( state, action.screen );
 			break;
-		case 'goback':
-			locationHistory = goBack( state );
-			break;
 		case 'goto':
 			locationHistory = goTo( state, action.path, action.options );
 			break;
@@ -223,11 +220,20 @@ function UnconnectedNavigatorProvider(
 	// The methods are constant forever, create stable references to them.
 	const methods = useMemo(
 		() => ( {
-			goBack: () => dispatch( { type: 'goback' } ),
+			// Note: calling goBack calls `goToParent` internally, as it was established
+			// that `goBack` should behave like `goToParent`, and `goToParent` should
+			// be marked as deprecated.
+			goBack: ( options: NavigateToParentOptions | undefined ) =>
+				dispatch( { type: 'gotoparent', options } ),
 			goTo: ( path: string, options?: NavigateOptions ) =>
 				dispatch( { type: 'goto', path, options } ),
-			goToParent: ( options: NavigateToParentOptions | undefined ) =>
-				dispatch( { type: 'gotoparent', options } ),
+			goToParent: ( options: NavigateToParentOptions | undefined ) => {
+				deprecated( `wp.components.useNavigator().goToParent`, {
+					since: '6.7',
+					alternative: 'wp.components.useNavigator().goBack',
+				} );
+				dispatch( { type: 'gotoparent', options } );
+			},
 			addScreen: ( screen: Screen ) =>
 				dispatch( { type: 'add', screen } ),
 			removeScreen: ( screen: Screen ) =>

package/src/navigator/navigator-screen/README.md

@@ -16,6 +16,18 @@ The component accepts the following props:
 
 ### `path`: `string`
 
-The screen's path, matched against the current path stored in the navigator.
+The screen"s path, matched against the current path stored in the navigator.
+
+`Navigator` assumes that screens are organized hierarchically according to their `path`, which should follow a URL-like scheme where each path segment starts with and is separated by the `/` character.
+
+`Navigator` will treat "back" navigations as going to the parent screen — it is therefore responsibility of the consumer of the component to create the correct screen hierarchy.
+
+For example:
+
+-   `/` is the root of all paths. There should always be a screen with `path="/"`.
+-   `/parent/child` is a child of `/parent`.
+-   `/parent/child/grand-child` is a child of `/parent/child`.
+-   `/parent/:param` is a child of `/parent` as well.
+-   if the current screen has a `path` with value `/parent/child/grand-child`, when going "back" `Navigator` will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) is found.
 
 -   Required: Yes

package/src/navigator/navigator-to-parent-button/README.md

@@ -4,6 +4,8 @@
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>
 
+This component is deprecated. Please use the [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) component instead.
+
 The `NavigatorToParentButton` component can be used to navigate to a screen and should be used in combination with the [`NavigatorProvider`](/packages/components/src/navigator/navigator-provider/README.md), the [`NavigatorScreen`](/packages/components/src/navigator/navigator-screen/README.md) and the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) components (or the `useNavigator` hook).
 
 ## Usage

package/src/navigator/navigator-to-parent-button/component.tsx

@@ -1,62 +1,33 @@
 /**
- * External dependencies
+ * WordPress dependencies
  */
-import type { ForwardedRef } from 'react';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
  */
+import { NavigatorBackButton } from '../navigator-back-button';
 import type { WordPressComponentProps } from '../../context';
 import { contextConnect } from '../../context';
-import { View } from '../../view';
-import { useNavigatorBackButton } from '../navigator-back-button/hook';
-import type { NavigatorToParentButtonProps } from '../types';
+import type { NavigatorBackButtonProps } from '../types';
 
 function UnconnectedNavigatorToParentButton(
-	props: WordPressComponentProps< NavigatorToParentButtonProps, 'button' >,
-	forwardedRef: ForwardedRef< any >
+	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >,
+	forwardedRef: React.ForwardedRef< any >
 ) {
-	const navigatorToParentButtonProps = useNavigatorBackButton( {
-		...props,
-		goToParent: true,
+	deprecated( 'wp.components.NavigatorToParentButton', {
+		since: '6.7',
+		alternative: 'wp.components.NavigatorBackButton',
 	} );
 
-	return <View ref={ forwardedRef } { ...navigatorToParentButtonProps } />;
+	return <NavigatorBackButton ref={ forwardedRef } { ...props } />;
 }
 
-/*
- * The `NavigatorToParentButton` component can be used to navigate to a screen and
- * should be used in combination with the `NavigatorProvider`, the
- * `NavigatorScreen` and the `NavigatorButton` components (or the `useNavigator`
- * hook).
- *
- * @example
- * ```jsx
- * import {
- *   __experimentalNavigatorProvider as NavigatorProvider,
- *   __experimentalNavigatorScreen as NavigatorScreen,
- *   __experimentalNavigatorButton as NavigatorButton,
- *   __experimentalNavigatorToParentButton as NavigatorToParentButton,
- * } from '@wordpress/components';
- *
- * const MyNavigation = () => (
- *   <NavigatorProvider initialPath="/">
- *     <NavigatorScreen path="/">
- *       <p>This is the home screen.</p>
- *        <NavigatorButton path="/child">
- *          Navigate to child screen.
- *       </NavigatorButton>
- *     </NavigatorScreen>
+/**
+ * _Note: this component is deprecated. Please use the `NavigatorBackButton`
+ * component instead._
  *
- *     <NavigatorScreen path="/child">
- *       <p>This is the child screen.</p>
- *       <NavigatorToParentButton>
- *         Go to parent
- *       </NavigatorToParentButton>
- *     </NavigatorScreen>
- *   </NavigatorProvider>
- * );
- * ```
+ * @deprecated
  */
 export const NavigatorToParentButton = contextConnect(
 	UnconnectedNavigatorToParentButton,

package/src/navigator/test/index.tsx

@@ -25,8 +25,8 @@ import {
 import type { NavigateOptions } from '../types';
 
 const INVALID_HTML_ATTRIBUTE = {
-	raw: ' "\'><=invalid_path',
-	escaped: " &quot;'&gt;<=invalid_path",
+	raw: '/ "\'><=invalid_path',
+	escaped: "/ &quot;'&gt;<=invalid_path",
 };
 
 const PATHS = {
@@ -165,6 +165,27 @@ function CustomNavigatorToParentButton( {
 	);
 }
 
+function CustomNavigatorToParentButtonAlternative( {
+	onClick,
+	children,
+}: {
+	children: React.ReactNode;
+	onClick?: CustomTestOnClickHandler;
+} ) {
+	const { goToParent } = useNavigator();
+	return (
+		<button
+			onClick={ () => {
+				goToParent();
+				// Used to spy on the values passed to `navigator.goBack`.
+				onClick?.( { type: 'goToParent' } );
+			} }
+		>
+			{ children }
+		</button>
+	);
+}
+
 const ProductScreen = ( {
 	onBackButtonClick,
 }: {
@@ -344,20 +365,20 @@ const MyHierarchicalNavigation = ( {
 					>
 						{ BUTTON_TEXT.toNestedScreen }
 					</CustomNavigatorButton>
-					<CustomNavigatorToParentButton
+					<CustomNavigatorBackButton
 						onClick={ onNavigatorButtonClick }
 					>
 						{ BUTTON_TEXT.back }
-					</CustomNavigatorToParentButton>
+					</CustomNavigatorBackButton>
 				</NavigatorScreen>
 
 				<NavigatorScreen path={ PATHS.NESTED }>
 					<p>{ SCREEN_TEXT.nested }</p>
-					<CustomNavigatorToParentButton
+					<CustomNavigatorBackButton
 						onClick={ onNavigatorButtonClick }
 					>
 						{ BUTTON_TEXT.back }
-					</CustomNavigatorToParentButton>
+					</CustomNavigatorBackButton>
 					<CustomNavigatorGoToBackButton
 						path={ PATHS.CHILD }
 						onClick={ onNavigatorButtonClick }
@@ -376,6 +397,66 @@ const MyHierarchicalNavigation = ( {
 	);
 };
 
+const MyDeprecatedNavigation = ( {
+	initialPath = PATHS.HOME,
+	onNavigatorButtonClick,
+}: {
+	initialPath?: string;
+	onNavigatorButtonClick?: CustomTestOnClickHandler;
+} ) => {
+	return (
+		<>
+			<NavigatorProvider initialPath={ initialPath }>
+				<NavigatorScreen path={ PATHS.HOME }>
+					<p>{ SCREEN_TEXT.home }</p>
+					{ /*
+					 * A button useful to test focus restoration. This button is the first
+					 * tabbable item in the screen, but should not receive focus when
+					 * navigating to screen as a result of a backwards navigation.
+					 */ }
+					<button>First tabbable home screen button</button>
+					<CustomNavigatorButton
+						path={ PATHS.CHILD }
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.toChildScreen }
+					</CustomNavigatorButton>
+				</NavigatorScreen>
+
+				<NavigatorScreen path={ PATHS.CHILD }>
+					<p>{ SCREEN_TEXT.child }</p>
+					{ /*
+					 * A button useful to test focus restoration. This button is the first
+					 * tabbable item in the screen, but should not receive focus when
+					 * navigating to screen as a result of a backwards navigation.
+					 */ }
+					<button>First tabbable child screen button</button>
+					<CustomNavigatorButton
+						path={ PATHS.NESTED }
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.toNestedScreen }
+					</CustomNavigatorButton>
+					<CustomNavigatorToParentButton
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.back }
+					</CustomNavigatorToParentButton>
+				</NavigatorScreen>
+
+				<NavigatorScreen path={ PATHS.NESTED }>
+					<p>{ SCREEN_TEXT.nested }</p>
+					<CustomNavigatorToParentButtonAlternative
+						onClick={ onNavigatorButtonClick }
+					>
+						{ BUTTON_TEXT.back }
+					</CustomNavigatorToParentButtonAlternative>
+				</NavigatorScreen>
+			</NavigatorProvider>
+		</>
+	);
+};
+
 const getScreen = ( screenKey: keyof typeof SCREEN_TEXT ) =>
 	screen.getByText( SCREEN_TEXT[ screenKey ] );
 const queryScreen = ( screenKey: keyof typeof SCREEN_TEXT ) =>
@@ -769,4 +850,53 @@ describe( 'Navigator', () => {
 			).toHaveFocus();
 		} );
 	} );
+
+	describe( 'deprecated APIs', () => {
+		it( 'should log a deprecation notice when using the NavigatorToParentButton component', async () => {
+			const user = userEvent.setup();
+
+			render( <MyDeprecatedNavigation initialPath={ PATHS.CHILD } /> );
+
+			expect( getScreen( 'child' ) ).toBeInTheDocument();
+
+			// Navigate back to home screen.
+			// The first tabbable element receives focus, since focus restoration
+			// it not possible (there was no forward navigation).
+			await user.click( getNavigationButton( 'back' ) );
+			expect( getScreen( 'home' ) ).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'First tabbable home screen button',
+				} )
+			).toHaveFocus();
+
+			// Rendering `NavigatorToParentButton` logs a deprecation notice
+			expect( console ).toHaveWarnedWith(
+				'wp.components.NavigatorToParentButton is deprecated since version 6.7. Please use wp.components.NavigatorBackButton instead.'
+			);
+		} );
+
+		it( 'should log a deprecation notice when using the useNavigator().goToParent() function', async () => {
+			const user = userEvent.setup();
+
+			render( <MyDeprecatedNavigation initialPath={ PATHS.NESTED } /> );
+
+			expect( getScreen( 'nested' ) ).toBeInTheDocument();
+
+			// Navigate back to child screen using the back button.
+			// The first tabbable element receives focus, since focus restoration
+			// it not possible (there was no forward navigation).
+			await user.click( getNavigationButton( 'back' ) );
+			expect( getScreen( 'child' ) ).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'First tabbable child screen button',
+				} )
+			).toHaveFocus();
+
+			expect( console ).toHaveWarnedWith(
+				'wp.components.useNavigator().goToParent is deprecated since version 6.7. Please use wp.components.useNavigator().goBack instead.'
+			);
+		} );
+	} );
 } );

package/src/navigator/types.ts

@@ -11,26 +11,70 @@ 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;
+	/**
+	 * Whether the navigation should replace the current location in the stack.
+	 */
 	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 +108,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/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/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,13 +1,7 @@
 /**
  * Internal dependencies
  */
-import {
-	Composite as CompositeV2,
-	CompositeGroup as CompositeGroupV2,
-	CompositeItem as CompositeItemV2,
-	CompositeRow as CompositeRowV2,
-	useCompositeStore as useCompositeStoreV2,
-} from './composite/v2';
+import { Composite, useCompositeStore } from './composite';
 import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
 import { createPrivateSlotFill } from './slot-fill';
 import {
@@ -28,11 +22,11 @@ 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,
+	useCompositeStoreV2: useCompositeStore,
 	__experimentalPopoverLegacyPositionToPlacement,
 	createPrivateSlotFill,
 	ComponentsContext,

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`