@wordpress/components 28.8.1-next.5368f64a9.0 → 28.8.2

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Meta, StoryFn } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
 /**
  * Internal dependencies
@@ -22,18 +22,13 @@ const meta: Meta< typeof ButtonGroup > = {
 };
 export default meta;
 
-const Template: StoryFn< typeof ButtonGroup > = ( args ) => {
-	const style = { margin: '0 4px' };
-	return (
-		<ButtonGroup { ...args }>
-			<Button variant="primary" style={ style }>
-				Button 1
-			</Button>
-			<Button variant="primary" style={ style }>
-				Button 2
-			</Button>
-		</ButtonGroup>
-	);
+export const Default: StoryObj< typeof ButtonGroup > = {
+	args: {
+		children: (
+			<>
+				<Button variant="primary">Button 1</Button>
+				<Button>Button 2</Button>
+			</>
+		),
+	},
 };
-
-export const Default: StoryFn< typeof ButtonGroup > = Template.bind( {} );

package/src/card/card/component.tsx

@@ -34,7 +34,7 @@ function UnconnectedCard(
 		size,
 		...otherProps
 	} = useCard( props );
-	const elevationBorderRadius = isRounded ? CONFIG.cardBorderRadius : 0;
+	const elevationBorderRadius = isRounded ? CONFIG.radiusLarge : 0;
 
 	const cx = useCx();
 

package/src/card/styles.ts

@@ -12,7 +12,7 @@ import { COLORS, CONFIG } from '../utils';
 // (as opposed to the `border` property), the value of the border radius needs
 // to be adjusted by removing 1px (this is because the `box-shadow` renders
 // as an "outer radius").
-const adjustedBorderRadius = `calc(${ CONFIG.cardBorderRadius } - 1px)`;
+const adjustedBorderRadius = `calc(${ CONFIG.radiusLarge } - 1px)`;
 
 export const Card = css`
 	box-shadow: 0 0 0 1px ${ CONFIG.surfaceBorderColor };

package/src/card/test/__snapshots__/index.tsx.snap

@@ -8,8 +8,8 @@ Snapshot Diff:
 @@ -1,8 +1,8 @@
   <div>
     <div
--     class="components-card__body components-card-body css-d0qyo2-PolymorphicDiv-Body-borderRadius-medium e19lxcc00"
-+     class="components-scrollable components-card__body components-card-body css-vpf7zs-PolymorphicDiv-Scrollable-scrollableScrollbar-scrollY-Body-borderRadius-medium e19lxcc00"
+-     class="components-card__body components-card-body css-12jqy32-PolymorphicDiv-Body-borderRadius-medium e19lxcc00"
++     class="components-scrollable components-card__body components-card-body css-26nv7r-PolymorphicDiv-Scrollable-scrollableScrollbar-scrollY-Body-borderRadius-medium e19lxcc00"
       data-wp-c16t="true"
       data-wp-component="CardBody"
     >
@@ -25,8 +25,8 @@ Snapshot Diff:
 @@ -1,8 +1,8 @@
   <div>
     <div
--     class="components-card__body components-card-body css-d0qyo2-PolymorphicDiv-Body-borderRadius-medium e19lxcc00"
-+     class="components-card__body components-card-body css-4zm8r0-PolymorphicDiv-Body-borderRadius-medium-shady e19lxcc00"
+-     class="components-card__body components-card-body css-12jqy32-PolymorphicDiv-Body-borderRadius-medium e19lxcc00"
++     class="components-card__body components-card-body css-1j7lja1-PolymorphicDiv-Body-borderRadius-medium-shady e19lxcc00"
       data-wp-c16t="true"
       data-wp-component="CardBody"
     >
@@ -42,8 +42,8 @@ Snapshot Diff:
 @@ -1,8 +1,8 @@
   <div>
     <div
--     class="components-flex components-card__footer components-card-footer css-1l4bmbt-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-medium e19lxcc00"
-+     class="components-flex components-card__footer components-card-footer css-8pv7rj-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-medium-shady e19lxcc00"
+-     class="components-flex components-card__footer components-card-footer css-19sc0cg-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-medium e19lxcc00"
++     class="components-flex components-card__footer components-card-footer css-14budie-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-medium-shady e19lxcc00"
       data-wp-c16t="true"
       data-wp-component="CardFooter"
     >
@@ -59,8 +59,8 @@ Snapshot Diff:
 @@ -1,8 +1,8 @@
   <div>
     <div
--     class="components-flex components-card__footer components-card-footer css-1l4bmbt-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-medium e19lxcc00"
-+     class="components-flex components-card__footer components-card-footer css-1hguscv-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-medium e19lxcc00"
+-     class="components-flex components-card__footer components-card-footer css-19sc0cg-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-medium e19lxcc00"
++     class="components-flex components-card__footer components-card-footer css-2io175-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-medium e19lxcc00"
       data-wp-c16t="true"
       data-wp-component="CardFooter"
     >
@@ -76,8 +76,8 @@ Snapshot Diff:
 @@ -1,8 +1,8 @@
   <div>
     <div
--     class="components-flex components-card__header components-card-header css-1tfuk0d-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-medium e19lxcc00"
-+     class="components-flex components-card__header components-card-header css-10qs2ur-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-medium-shady e19lxcc00"
+-     class="components-flex components-card__header components-card-header css-1qwshfy-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-medium e19lxcc00"
++     class="components-flex components-card__header components-card-header css-1bzc8bz-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-medium-shady e19lxcc00"
       data-wp-c16t="true"
       data-wp-component="CardHeader"
     >
@@ -96,16 +96,16 @@ Snapshot Diff:
         class="css-76dw7d-PolymorphicDiv-Content e19lxcc00"
       >
         <div
--         class="components-flex components-card__header components-card-header css-1tfuk0d-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-medium e19lxcc00"
-+         class="components-flex components-card__header components-card-header css-d1c2bv-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-large e19lxcc00"
+-         class="components-flex components-card__header components-card-header css-1qwshfy-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-medium e19lxcc00"
++         class="components-flex components-card__header components-card-header css-1t2zg3y-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-large e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="CardHeader"
         >
           Header
         </div>
         <div
--         class="components-card__body components-card-body css-d0qyo2-PolymorphicDiv-Body-borderRadius-medium e19lxcc00"
-+         class="components-card__body components-card-body css-kub9fa-PolymorphicDiv-Body-borderRadius-large e19lxcc00"
+-         class="components-card__body components-card-body css-12jqy32-PolymorphicDiv-Body-borderRadius-medium e19lxcc00"
++         class="components-card__body components-card-body css-e0vrqx-PolymorphicDiv-Body-borderRadius-large e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="CardBody"
         >
@@ -122,7 +122,7 @@ Snapshot Diff:
   Array [
     Object {
       "background-color": "#fff",
--     "border-radius": "calc(2px - 1px)",
+-     "border-radius": "calc(8px - 1px)",
       "box-shadow": "0 0 0 1px rgba(0, 0, 0, 0.1)",
       "color": "#1e1e1e",
       "outline": "none",
@@ -141,24 +141,24 @@ Snapshot Diff:
         class="css-76dw7d-PolymorphicDiv-Content e19lxcc00"
       >
         <div
--         class="components-flex components-card__header components-card-header css-1xfrxuu-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-large-borderless e19lxcc00"
-+         class="components-flex components-card__header components-card-header css-1mitrbv-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-small e19lxcc00"
+-         class="components-flex components-card__header components-card-header css-ubn8f6-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-large-borderless e19lxcc00"
++         class="components-flex components-card__header components-card-header css-1t1rswf-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-small e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="CardHeader"
         >
           Header
         </div>
         <div
--         class="components-card__body components-card-body css-kub9fa-PolymorphicDiv-Body-borderRadius-large e19lxcc00"
-+         class="components-card__body components-card-body css-d0qyo2-PolymorphicDiv-Body-borderRadius-medium e19lxcc00"
+-         class="components-card__body components-card-body css-e0vrqx-PolymorphicDiv-Body-borderRadius-large e19lxcc00"
++         class="components-card__body components-card-body css-12jqy32-PolymorphicDiv-Body-borderRadius-medium e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="CardBody"
         >
           Body
         </div>
         <div
--         class="components-flex components-card__footer components-card-footer css-8o7z5w-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-large-borderless e19lxcc00"
-+         class="components-flex components-card__footer components-card-footer css-1umuqb4-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-xSmallCardPadding e19lxcc00"
+-         class="components-flex components-card__footer components-card-footer css-167csgt-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-large-borderless e19lxcc00"
++         class="components-flex components-card__footer components-card-footer css-1kcgqsk-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-xSmallCardPadding e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="CardFooter"
         >
@@ -174,8 +174,8 @@ Snapshot Diff:
 @@ -1,30 +1,30 @@
   <div>
     <div
--     class="components-surface components-card css-5ubhkm-PolymorphicDiv-Surface-getBorders-primary-Card-boxShadowless-rounded e19lxcc00"
-+     class="components-surface components-card css-1lc0qq8-PolymorphicDiv-Surface-getBorders-primary-Card-rounded e19lxcc00"
+-     class="components-surface components-card css-1hs39fv-PolymorphicDiv-Surface-getBorders-primary-Card-boxShadowless-rounded e19lxcc00"
++     class="components-surface components-card css-1c6nh8q-PolymorphicDiv-Surface-getBorders-primary-Card-rounded e19lxcc00"
       data-wp-c16t="true"
       data-wp-component="Card"
     >
@@ -183,24 +183,24 @@ Snapshot Diff:
         class="css-76dw7d-PolymorphicDiv-Content e19lxcc00"
       >
         <div
--         class="components-flex components-card__header components-card-header css-1xfrxuu-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-large-borderless e19lxcc00"
-+         class="components-flex components-card__header components-card-header css-1mitrbv-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-small e19lxcc00"
+-         class="components-flex components-card__header components-card-header css-ubn8f6-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-large-borderless e19lxcc00"
++         class="components-flex components-card__header components-card-header css-1t1rswf-PolymorphicDiv-Flex-base-ItemsRow-Header-borderRadius-borderColor-small e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="CardHeader"
         >
           Header
         </div>
         <div
--         class="components-card__body components-card-body css-kub9fa-PolymorphicDiv-Body-borderRadius-large e19lxcc00"
-+         class="components-card__body components-card-body css-1djcdvu-PolymorphicDiv-Body-borderRadius-small e19lxcc00"
+-         class="components-card__body components-card-body css-e0vrqx-PolymorphicDiv-Body-borderRadius-large e19lxcc00"
++         class="components-card__body components-card-body css-hms9n9-PolymorphicDiv-Body-borderRadius-small e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="CardBody"
         >
           Body
         </div>
         <div
--         class="components-flex components-card__footer components-card-footer css-8o7z5w-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-large-borderless e19lxcc00"
-+         class="components-flex components-card__footer components-card-footer css-1awxp6o-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-small e19lxcc00"
+-         class="components-flex components-card__footer components-card-footer css-167csgt-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-large-borderless e19lxcc00"
++         class="components-flex components-card__footer components-card-footer css-18yn3ff-PolymorphicDiv-Flex-base-ItemsRow-Footer-borderRadius-borderColor-small e19lxcc00"
           data-wp-c16t="true"
           data-wp-component="CardFooter"
         >
@@ -215,7 +215,7 @@ exports[`Card Card component should render correctly 1`] = `
   position: relative;
   box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.1);
   outline: none;
-  border-radius: calc(2px - 1px);
+  border-radius: calc(8px - 1px);
 }
 
 .emotion-2 {
@@ -254,13 +254,13 @@ exports[`Card Card component should render correctly 1`] = `
 }
 
 .emotion-4:first-of-type {
-  border-top-left-radius: calc(2px - 1px);
-  border-top-right-radius: calc(2px - 1px);
+  border-top-left-radius: calc(8px - 1px);
+  border-top-right-radius: calc(8px - 1px);
 }
 
 .emotion-4:last-of-type {
-  border-bottom-left-radius: calc(2px - 1px);
-  border-bottom-right-radius: calc(2px - 1px);
+  border-bottom-left-radius: calc(8px - 1px);
+  border-bottom-right-radius: calc(8px - 1px);
 }
 
 .emotion-6 {
@@ -271,13 +271,13 @@ exports[`Card Card component should render correctly 1`] = `
 }
 
 .emotion-6:first-of-type {
-  border-top-left-radius: calc(2px - 1px);
-  border-top-right-radius: calc(2px - 1px);
+  border-top-left-radius: calc(8px - 1px);
+  border-top-right-radius: calc(8px - 1px);
 }
 
 .emotion-6:last-of-type {
-  border-bottom-left-radius: calc(2px - 1px);
-  border-bottom-right-radius: calc(2px - 1px);
+  border-bottom-left-radius: calc(8px - 1px);
+  border-bottom-right-radius: calc(8px - 1px);
 }
 
 .emotion-10 {
@@ -306,13 +306,13 @@ exports[`Card Card component should render correctly 1`] = `
 }
 
 .emotion-14:first-of-type {
-  border-top-left-radius: calc(2px - 1px);
-  border-top-right-radius: calc(2px - 1px);
+  border-top-left-radius: calc(8px - 1px);
+  border-top-right-radius: calc(8px - 1px);
 }
 
 .emotion-14:last-of-type {
-  border-bottom-left-radius: calc(2px - 1px);
-  border-bottom-right-radius: calc(2px - 1px);
+  border-bottom-left-radius: calc(8px - 1px);
+  border-bottom-right-radius: calc(8px - 1px);
 }
 
 .emotion-16 {
@@ -347,13 +347,13 @@ exports[`Card Card component should render correctly 1`] = `
 }
 
 .emotion-16:first-of-type {
-  border-top-left-radius: calc(2px - 1px);
-  border-top-right-radius: calc(2px - 1px);
+  border-top-left-radius: calc(8px - 1px);
+  border-top-right-radius: calc(8px - 1px);
 }
 
 .emotion-16:last-of-type {
-  border-bottom-left-radius: calc(2px - 1px);
-  border-bottom-right-radius: calc(2px - 1px);
+  border-bottom-left-radius: calc(8px - 1px);
+  border-bottom-right-radius: calc(8px - 1px);
 }
 
 .emotion-18 {
@@ -370,7 +370,7 @@ exports[`Card Card component should render correctly 1`] = `
   left: 0;
   right: 0;
   top: 0;
-  border-radius: 2px;
+  border-radius: 8px;
 }
 
 @media not ( prefers-reduced-motion ) {
@@ -469,15 +469,15 @@ Snapshot Diff:
       </div>
       <div
         aria-hidden="true"
--       class="components-elevation css-1dd80bh-PolymorphicDiv-Elevation-sx-Base-sx-Base-elevationClassName e19lxcc00"
-+       class="components-elevation css-1jg41yu-PolymorphicDiv-Elevation-sx-Base-sx-Base-elevationClassName e19lxcc00"
+-       class="components-elevation css-a91pvj-PolymorphicDiv-Elevation-sx-Base-sx-Base-elevationClassName e19lxcc00"
++       class="components-elevation css-1q4cuxd-PolymorphicDiv-Elevation-sx-Base-sx-Base-elevationClassName e19lxcc00"
         data-wp-c16t="true"
         data-wp-component="Elevation"
       />
       <div
         aria-hidden="true"
--       class="components-elevation css-iuptql-PolymorphicDiv-Elevation-sx-Base-sx-Base-elevationClassName e19lxcc00"
-+       class="components-elevation css-1jg41yu-PolymorphicDiv-Elevation-sx-Base-sx-Base-elevationClassName e19lxcc00"
+-       class="components-elevation css-5u83fl-PolymorphicDiv-Elevation-sx-Base-sx-Base-elevationClassName e19lxcc00"
++       class="components-elevation css-1q4cuxd-PolymorphicDiv-Elevation-sx-Base-sx-Base-elevationClassName e19lxcc00"
         data-wp-c16t="true"
         data-wp-component="Elevation"
       />
@@ -497,7 +497,7 @@ exports[`Card Card component should warn when the isElevated prop is passed 1`]
   position: relative;
   box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.1);
   outline: none;
-  border-radius: calc(2px - 1px);
+  border-radius: calc(8px - 1px);
 }
 
 .emotion-2 {
@@ -518,7 +518,7 @@ exports[`Card Card component should warn when the isElevated prop is passed 1`]
   left: 0;
   right: 0;
   top: 0;
-  border-radius: 2px;
+  border-radius: 8px;
 }
 
 @media not ( prefers-reduced-motion ) {
@@ -542,7 +542,7 @@ exports[`Card Card component should warn when the isElevated prop is passed 1`]
   left: 0;
   right: 0;
   top: 0;
-  border-radius: 2px;
+  border-radius: 8px;
 }
 
 @media not ( prefers-reduced-motion ) {

package/src/combobox-control/README.md

@@ -111,6 +111,13 @@ If the control is clicked, the dropdown will expand regardless of this prop.
 -   Required: No
 -   Default: `true`
 
+### placeholder
+
+If passed, the combobox input will show a placeholder string if no values are present.
+
+-   Type: `string`
+-   Required: No
+
 #### __experimentalRenderItem
 
 Custom renderer invoked for each option in the suggestion list. The render prop receives as its argument an object containing, under the `item` key, the single option's data (directly from the array of data passed to the `options` prop).

package/src/combobox-control/index.tsx

@@ -129,6 +129,7 @@ function ComboboxControl( props: ComboboxControlProps ) {
 		},
 		__experimentalRenderItem,
 		expandOnFocus = true,
+		placeholder,
 	} = useDeprecated36pxDefaultSizeProp( props );
 
 	const [ value, setValue ] = useControlledValue( {
@@ -340,6 +341,7 @@ function ComboboxControl( props: ComboboxControlProps ) {
 								className="components-combobox-control__input"
 								instanceId={ instanceId }
 								ref={ inputContainer }
+								placeholder={ placeholder }
 								value={ isExpanded ? inputValue : currentLabel }
 								onFocus={ onFocus }
 								onBlur={ onBlur }

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

@@ -188,6 +188,46 @@ describe.each( [
 		expect( input ).toHaveValue( targetOption.label );
 	} );
 
+	it( 'calls onFilterValueChange whenever the textbox changes', async () => {
+		const user = userEvent.setup();
+		const onFilterValueChangeSpy = jest.fn();
+		render(
+			<Component
+				options={ timezones }
+				label={ defaultLabelText }
+				onFilterValueChange={ onFilterValueChangeSpy }
+			/>
+		);
+
+		const input = getInput( defaultLabelText );
+
+		await user.type( input, 'a' );
+		expect( onFilterValueChangeSpy ).toHaveBeenCalledWith( 'a' );
+	} );
+
+	it( 'clears the textbox value if there is no selected value on blur', async () => {
+		const user = userEvent.setup();
+		const onFilterValueChangeSpy = jest.fn();
+		render(
+			<Component
+				options={ timezones }
+				label={ defaultLabelText }
+				onFilterValueChange={ onFilterValueChangeSpy }
+			/>
+		);
+		const input = getInput( defaultLabelText );
+
+		await user.type( input, 'a' );
+		expect( input ).toHaveValue( 'a' );
+
+		// Blur and focus the input.
+		await user.tab();
+		await user.click( input );
+
+		expect( input ).toHaveValue( '' );
+		expect( onFilterValueChangeSpy ).toHaveBeenLastCalledWith( '' );
+	} );
+
 	it( 'should select the correct option from a search', async () => {
 		const user = await userEvent.setup();
 		const targetOption = timezones[ 13 ];

package/src/combobox-control/types.ts

@@ -82,4 +82,8 @@ export type ComboboxControlProps = Pick<
 	 * The current value of the control.
 	 */
 	value?: string | null;
+	/**
+	 * If passed, the combobox input will show a placeholder string if no values are present.
+	 */
+	placeholder?: string;
 };

package/src/custom-select-control-v2/styles.ts

@@ -120,6 +120,7 @@ export const SelectPopover = styled( Ariakit.SelectPopover )`
 	background-color: ${ COLORS.theme.background };
 	border-radius: ${ CONFIG.radiusSmall };
 	border: 1px solid ${ COLORS.theme.foreground };
+	box-shadow: ${ CONFIG.elevationMedium };
 
 	/* z-index(".components-popover") */
 	z-index: 1000000;

package/src/dropdown-menu-v2/styles.ts

@@ -37,7 +37,7 @@ const DIVIDER_COLOR = COLORS.theme.gray[ 200 ];
 const LIGHTER_TEXT_COLOR = COLORS.theme.gray[ 700 ];
 const LIGHT_BACKGROUND_COLOR = COLORS.theme.gray[ 100 ];
 const TOOLBAR_VARIANT_BORDER_COLOR = COLORS.theme.foreground;
-const DEFAULT_BOX_SHADOW = `0 0 0 ${ CONFIG.borderWidth } ${ DEFAULT_BORDER_COLOR }, ${ CONFIG.elevationXSmall }`;
+const DEFAULT_BOX_SHADOW = `0 0 0 ${ CONFIG.borderWidth } ${ DEFAULT_BORDER_COLOR }, ${ CONFIG.elevationMedium }`;
 const TOOLBAR_VARIANT_BOX_SHADOW = `0 0 0 ${ CONFIG.borderWidth } ${ TOOLBAR_VARIANT_BORDER_COLOR }`;
 
 const GRID_TEMPLATE_COLS = 'minmax( 0, max-content ) 1fr';

package/src/form-toggle/style.scss

@@ -60,6 +60,7 @@ $transition-duration: 0.2s;
 			$transition-duration background-color ease-out;
 		@include reduce-motion("transition");
 		background-color: $gray-900;
+		box-shadow: $elevation-x-small;
 
 		// Transparent border acts as a fill in Windows High Contrast Mode.
 		border: math.div($toggle-thumb-size, 2) solid transparent;

package/src/modal/index.tsx

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import clsx from 'clsx';
-import type { ForwardedRef, KeyboardEvent, RefObject, UIEvent } from 'react';
 
 /**
  * WordPress dependencies
@@ -38,10 +37,11 @@ import StyleProvider from '../style-provider';
 import type { ModalProps } from './types';
 import { withIgnoreIMEEvents } from '../utils/with-ignore-ime-events';
 import { Spacer } from '../spacer';
+import { useModalExitAnimation } from './use-modal-exit-animation';
 
 // Used to track and dismiss the prior modal when another opens unless nested.
 type Dismissers = Set<
-	RefObject< ModalProps[ 'onRequestClose' ] | undefined >
+	React.RefObject< ModalProps[ 'onRequestClose' ] | undefined >
 >;
 const ModalContext = createContext< Dismissers >( new Set() );
 
@@ -50,7 +50,7 @@ const bodyOpenClasses = new Map< string, number >();
 
 function UnforwardedModal(
 	props: ModalProps,
-	forwardedRef: ForwardedRef< HTMLDivElement >
+	forwardedRef: React.ForwardedRef< HTMLDivElement >
 ) {
 	const {
 		bodyOpenClassName = 'modal-open',
@@ -70,7 +70,7 @@ function UnforwardedModal(
 		closeButtonLabel,
 		children,
 		style,
-		overlayClassName,
+		overlayClassName: overlayClassnameProp,
 		className,
 		contentLabel,
 		onKeyDown,
@@ -184,6 +184,9 @@ function UnforwardedModal(
 		};
 	}, [ bodyOpenClassName ] );
 
+	const { closeModal, frameRef, frameStyle, overlayClassname } =
+		useModalExitAnimation();
+
 	// Calls the isContentScrollable callback when the Modal children container resizes.
 	useLayoutEffect( () => {
 		if ( ! window.ResizeObserver || ! childrenContainerRef.current ) {
@@ -200,21 +203,21 @@ function UnforwardedModal(
 		};
 	}, [ isContentScrollable, childrenContainerRef ] );
 
-	function handleEscapeKeyDown( event: KeyboardEvent< HTMLDivElement > ) {
+	function handleEscapeKeyDown(
+		event: React.KeyboardEvent< HTMLDivElement >
+	) {
 		if (
 			shouldCloseOnEsc &&
 			( event.code === 'Escape' || event.key === 'Escape' ) &&
 			! event.defaultPrevented
 		) {
 			event.preventDefault();
-			if ( onRequestClose ) {
-				onRequestClose( event );
-			}
+			closeModal().then( () => onRequestClose( event ) );
 		}
 	}
 
 	const onContentContainerScroll = useCallback(
-		( e: UIEvent< HTMLDivElement > ) => {
+		( e: React.UIEvent< HTMLDivElement > ) => {
 			const scrollY = e?.currentTarget?.scrollTop ?? -1;
 
 			if ( ! hasScrolledContent && scrollY > 0 ) {
@@ -248,7 +251,7 @@ function UnforwardedModal(
 			const isSameTarget = target === pressTarget;
 			pressTarget = null;
 			if ( button === 0 && isSameTarget ) {
-				onRequestClose();
+				closeModal().then( () => onRequestClose() );
 			}
 		},
 	};
@@ -259,7 +262,8 @@ function UnforwardedModal(
 			ref={ useMergeRefs( [ ref, forwardedRef ] ) }
 			className={ clsx(
 				'components-modal__screen-overlay',
-				overlayClassName
+				overlayClassname,
+				overlayClassnameProp
 			) }
 			onKeyDown={ withIgnoreIMEEvents( handleEscapeKeyDown ) }
 			{ ...( shouldCloseOnClickOutside ? overlayPressHandlers : {} ) }
@@ -271,8 +275,12 @@ function UnforwardedModal(
 						sizeClass,
 						className
 					) }
-					style={ style }
+					style={ {
+						...frameStyle,
+						...style,
+					} }
 					ref={ useMergeRefs( [
+						frameRef,
 						constrainedTabbingRef,
 						focusReturnRef,
 						focusOnMount !== 'firstContentElement'
@@ -331,7 +339,13 @@ function UnforwardedModal(
 										/>
 										<Button
 											size="small"
-											onClick={ onRequestClose }
+											onClick={ (
+												event: React.MouseEvent< HTMLButtonElement >
+											) =>
+												closeModal().then( () =>
+													onRequestClose( event )
+												)
+											}
 											icon={ close }
 											label={
 												closeButtonLabel ||

package/src/modal/style.scss

@@ -8,8 +8,15 @@
 	background-color: rgba($black, 0.35);
 	z-index: z-index(".components-modal__screen-overlay");
 	display: flex;
-	// This animates the appearance of the white background.
-	@include edit-post__fade-in-animation();
+	// This animates the appearance of the backdrop.
+	@include animation__fade-in();
+
+	&.is-animating-out {
+		// Note: it's important that the fade-out animation doesn't end after the
+		// modal frame's disappear animation, because the component will be removed
+		// from the DOM when that animation ends.
+		@include animation__fade-out($delay: 80ms);
+	}
 }
 
 // The modal window element.
@@ -25,10 +32,17 @@
 	// Have the content element fill the vertical space yet not overflow.
 	display: flex;
 	// Animate the modal frame/contents appearing on the page.
-	animation: components-modal__appear-animation 0.26s cubic-bezier(0.29, 0, 0, 1);
+	animation-name: components-modal__appear-animation;
+	animation-duration: var(--modal-frame-animation-duration);
 	animation-fill-mode: forwards;
+	animation-timing-function: cubic-bezier(0.29, 0, 0, 1);
 	@include reduce-motion("animation");
 
+	.components-modal__screen-overlay.is-animating-out & {
+		animation-name: components-modal__disappear-animation;
+		animation-timing-function: cubic-bezier(1, 0, 0.2, 1);
+	}
+
 	// Show a centered modal on bigger screens.
 	@include break-small() {
 		border-radius: $radius-large;
@@ -88,6 +102,19 @@
 	}
 }
 
+// Note: this animation is also used in the animationend JS event listener.
+// Make sure that the animation name is kept in sync across the two files.
+@keyframes components-modal__disappear-animation {
+	from {
+		opacity: 1;
+		transform: scale(1);
+	}
+	to {
+		opacity: 0;
+		transform: scale(0.9);
+	}
+}
+
 // Fix header to the top so it is always there to provide context to the modal
 // if the content needs to be scrolled (for example, on the keyboard shortcuts
 // modal screen).