@wordpress/ui 0.10.0 → 0.11.1-next.v.202604091042.0

package/src/alert-dialog/popup.tsx

@@ -1,56 +1,114 @@
+import { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
+import clsx from 'clsx';
 import { forwardRef, useContext } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
+import {
+	type ThemeProvider as ThemeProviderType,
+	privateApis as themePrivateApis,
+} from '@wordpress/theme';
+
 import { Button } from '../button';
-import * as Dialog from '../dialog';
+import dialogStyles from '../dialog/style.module.css';
+import { unlock } from '../lock-unlock';
+import { Stack } from '../stack';
+import { Text } from '../text';
 import { AlertDialogContext } from './context';
-import styles from './style.module.css';
+import alertDialogStyles from './style.module.css';
 import type { PopupProps } from './types';
 
+const ThemeProvider: typeof ThemeProviderType =
+	unlock( themePrivateApis ).ThemeProvider;
+
 const Popup = forwardRef< HTMLDivElement, PopupProps >(
 	function AlertDialogPopup(
 		{
+			className,
+			intent = 'default',
 			title,
+			description,
 			children,
-			onConfirm,
 			confirmButtonText = __( 'OK' ),
 			cancelButtonText = __( 'Cancel' ),
-			loading,
+			...props
 		},
 		ref
 	) {
-		const { intent } = useContext( AlertDialogContext );
+		const { phase, showSpinner, errorMessage, confirm } =
+			useContext( AlertDialogContext );
 
-		// When `loading` is provided, the consumer controls when the dialog
-		// closes (async flow). Use a plain Button so clicking confirm doesn't
-		// auto-close — the consumer sets `open={false}` after their operation.
-		const ConfirmButton = loading !== undefined ? Button : Dialog.Action;
+		const confirmClassName =
+			intent === 'irreversible'
+				? alertDialogStyles[ 'irreversible-action' ]
+				: undefined;
+
+		const buttonsDisabled = phase !== 'idle' || undefined;
 
 		return (
-			<Dialog.Popup ref={ ref }>
-				<Dialog.Header>
-					<Dialog.Title>{ title }</Dialog.Title>
-				</Dialog.Header>
-				{ children }
-				<Dialog.Footer>
-					<Dialog.Action
-						variant="minimal"
-						disabled={ loading || undefined }
-					>
-						{ cancelButtonText }
-					</Dialog.Action>
-					<ConfirmButton
-						className={
-							intent === 'irreversible'
-								? styles[ 'irreversible-action' ]
-								: undefined
-						}
-						onClick={ onConfirm }
-						loading={ loading }
+			<_AlertDialog.Portal>
+				<_AlertDialog.Backdrop className={ dialogStyles.backdrop } />
+				<ThemeProvider>
+					<_AlertDialog.Popup
+						ref={ ref }
+						className={ clsx(
+							dialogStyles.popup,
+							className,
+							dialogStyles[ 'is-medium' ]
+						) }
+						{ ...props }
 					>
-						{ confirmButtonText }
-					</ConfirmButton>
-				</Dialog.Footer>
-			</Dialog.Popup>
+						<Stack
+							direction="column"
+							gap="sm"
+							className={ alertDialogStyles.header }
+						>
+							<Text
+								variant="heading-xl"
+								render={ <_AlertDialog.Title /> }
+								className={ dialogStyles.title }
+							>
+								{ title }
+							</Text>
+							{ description && (
+								<Text
+									variant="body-md"
+									render={ <_AlertDialog.Description /> }
+								>
+									{ description }
+								</Text>
+							) }
+						</Stack>
+						{ children }
+						<Stack direction="column" gap="md">
+							<div className={ dialogStyles.footer }>
+								<_AlertDialog.Close
+									render={ <Button variant="minimal" /> }
+									disabled={ buttonsDisabled }
+								>
+									{ cancelButtonText }
+								</_AlertDialog.Close>
+								<Button
+									className={ confirmClassName }
+									onClick={ confirm }
+									loading={ showSpinner || undefined }
+									disabled={ buttonsDisabled }
+								>
+									{ confirmButtonText }
+								</Button>
+							</div>
+							{ errorMessage && (
+								<Text
+									variant="body-sm"
+									className={
+										alertDialogStyles[ 'error-message' ]
+									}
+								>
+									{ errorMessage }
+								</Text>
+							) }
+						</Stack>
+					</_AlertDialog.Popup>
+				</ThemeProvider>
+			</_AlertDialog.Portal>
 		);
 	}
 );

package/src/alert-dialog/root.tsx

@@ -1,8 +1,25 @@
 import { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
-import { useMemo } from '@wordpress/element';
+import { speak } from '@wordpress/a11y';
+import {
+	useCallback,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from '@wordpress/element';
+
 import { AlertDialogContext } from './context';
+import type { Phase } from './context';
 import type { RootProps } from './types';
 
+function isThenable( value: unknown ): value is PromiseLike< unknown > {
+	return (
+		value !== null &&
+		value !== undefined &&
+		typeof ( value as PromiseLike< unknown > ).then === 'function'
+	);
+}
+
 /**
  * A dialog that requires a user response to proceed.
  *
@@ -11,32 +28,193 @@ import type { RootProps } from './types';
  * The `AlertDialog.Trigger` is optional — the dialog can also be controlled
  * via `open` / `onOpenChange` props.
  *
- * ## Use cases
- *
- * - **Default intent**: Standard confirmation dialog for reversible actions.
- * - **Irreversible intent**: Confirmation dialog for irreversible actions that
- *   cannot be undone. The confirm button uses error/danger coloring.
- *
  * For use cases outside the standard confirm/cancel pattern, use the lower-level
  * `Dialog` component directly.
  *
- * See the [Destructive Actions guidelines](?path=/docs/design-system-patterns-destructive-actions--docs)
+ * See the [Destructive Actions guidelines](https://wordpress.github.io/gutenberg/?path=/docs/design-system-patterns-destructive-actions--docs)
  * for more details on when to use each pattern.
  */
 function Root( {
-	intent = 'default',
 	children,
-	open,
+	open: openProp,
 	onOpenChange,
 	defaultOpen,
+	onConfirm,
 }: RootProps ) {
-	const contextValue = useMemo( () => ( { intent } ), [ intent ] );
+	const [ internalOpen, setInternalOpen ] = useState( defaultOpen ?? false );
+
+	// Internal state machine for the confirm-and-close lifecycle.
+	//
+	// Phase transitions:
+	//
+	//   idle ──> pending ──> closing ──> idle
+	//           (confirm     (success,   (animation
+	//            clicked)     close)      complete)
+	//
+	//   idle ──> pending ──> idle
+	//           (confirm     (error, or
+	//            clicked)     {close:false})
+	//
+	//   idle ──> closing ──> idle
+	//           (cancel/     (animation
+	//            escape)      complete)
+	//
+	// `showSpinner` tracks whether the confirm button shows a loading
+	// indicator. It is orthogonal to `phase`:
+	//
+	//   Scenario                  | pending | closing
+	//   --------------------------+---------+---------
+	//   Sync onConfirm            | false   | false
+	//   Async onConfirm (success) | true    | true
+	//   Async onConfirm (error)   | true    | n/a (-> idle)
+	//   Cancel / Escape           | n/a     | false
+	//
+	// Buttons are disabled whenever phase !== 'idle'.
+	// Dismiss (Escape / Cancel) is blocked during 'pending'.
+	const [ phase, setPhase ] = useState< Phase >( 'idle' );
+	const [ showSpinner, setShowSpinner ] = useState( false );
+	const [ errorMessage, setErrorMessage ] = useState< string >();
+
+	const actionsRef = useRef< _AlertDialog.Root.Actions | null >( null );
+
+	const onConfirmRef = useRef( onConfirm );
+	onConfirmRef.current = onConfirm;
+
+	// Ref keeps phase accessible synchronously from callbacks that may
+	// run between a setState call and the subsequent React re-render.
+	const phaseRef = useRef( phase );
+	phaseRef.current = phase;
+
+	// Generation counter — safety net for the edge case where the component
+	// unmounts while an async confirm is in flight. Also incremented when
+	// the dialog finishes closing, so a stale promise settling after a
+	// dismiss+reopen cycle is silently discarded.
+	const confirmIdRef = useRef( 0 );
+
+	const effectiveOpen = openProp ?? internalOpen;
+
+	// Safety net: if the consumer keeps `open={true}` after a confirm
+	// (i.e. does not react to `onOpenChange`), the phase would be stuck
+	// at 'closing'. Detect the contradiction and reset to idle.
+	useEffect( () => {
+		if ( effectiveOpen && phase === 'closing' ) {
+			phaseRef.current = 'idle';
+			setPhase( 'idle' );
+			setShowSpinner( false );
+		}
+	}, [ effectiveOpen, phase ] );
+
+	const handleOpenChange = useCallback(
+		(
+			nextOpen: boolean,
+			eventDetails: _AlertDialog.Root.ChangeEventDetails
+		) => {
+			// Block dismiss while a confirm action is pending.
+			if ( ! nextOpen && phaseRef.current === 'pending' ) {
+				return;
+			}
+
+			if ( ! nextOpen && phaseRef.current === 'idle' ) {
+				phaseRef.current = 'closing';
+				setPhase( 'closing' );
+			}
+
+			setInternalOpen( nextOpen );
+			onOpenChange?.( nextOpen, eventDetails );
+		},
+		[ onOpenChange ]
+	);
+
+	const confirm = useCallback( async () => {
+		if ( phaseRef.current !== 'idle' ) {
+			return;
+		}
+
+		phaseRef.current = 'pending';
+		setPhase( 'pending' );
+		setErrorMessage( undefined );
+
+		const id = ++confirmIdRef.current;
+
+		try {
+			const rawResult = onConfirmRef.current?.();
+
+			// Show spinner only for async handlers (Promises).
+			// Sync handlers resolve in the same tick — no spinner needed.
+			if ( isThenable( rawResult ) ) {
+				setShowSpinner( true );
+			}
+
+			const result = await Promise.resolve( rawResult );
+
+			// Discard if the component unmounted or the dialog was
+			// dismissed and reopened while the promise was in flight.
+			if ( confirmIdRef.current !== id ) {
+				return;
+			}
+
+			// An error message implies the dialog should stay open.
+			if ( result?.error ) {
+				phaseRef.current = 'idle';
+				setPhase( 'idle' );
+				setShowSpinner( false );
+				setErrorMessage( result.error );
+				speak( result.error, 'assertive' );
+				return;
+			}
+
+			const shouldClose = result?.close !== false;
+
+			if ( shouldClose ) {
+				phaseRef.current = 'closing';
+				setPhase( 'closing' );
+				actionsRef.current?.close();
+			} else {
+				phaseRef.current = 'idle';
+				setPhase( 'idle' );
+				setShowSpinner( false );
+			}
+		} catch ( error ) {
+			if ( confirmIdRef.current !== id ) {
+				return;
+			}
+			phaseRef.current = 'idle';
+			setPhase( 'idle' );
+			setShowSpinner( false );
+			// eslint-disable-next-line no-console
+			console.error( error );
+		}
+	}, [] );
+
+	const handleOpenChangeComplete = useCallback( ( open: boolean ) => {
+		if ( ! open ) {
+			// Invalidate any in-flight async so a stale promise settling
+			// after dismiss+reopen doesn't close the new session.
+			confirmIdRef.current++;
+			phaseRef.current = 'idle';
+			setPhase( 'idle' );
+			setShowSpinner( false );
+			setErrorMessage( undefined );
+		}
+	}, [] );
+
+	const contextValue = useMemo(
+		() => ( {
+			phase,
+			showSpinner,
+			errorMessage,
+			confirm,
+		} ),
+		[ phase, showSpinner, errorMessage, confirm ]
+	);
 
 	return (
 		<_AlertDialog.Root
-			open={ open }
-			onOpenChange={ onOpenChange }
+			open={ effectiveOpen }
 			defaultOpen={ defaultOpen }
+			onOpenChange={ handleOpenChange }
+			onOpenChangeComplete={ handleOpenChangeComplete }
+			actionsRef={ actionsRef }
 		>
 			<AlertDialogContext.Provider value={ contextValue }>
 				{ children }

package/src/alert-dialog/stories/index.story.tsx

@@ -1,10 +1,10 @@
 import { Menu } from '@base-ui/react/menu';
-import { useState } from '@wordpress/element';
+import { useId, useState } from '@wordpress/element';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { action } from 'storybook/actions';
 import { fn } from 'storybook/test';
 
-import { AlertDialog } from '../..';
+import { AlertDialog, Text } from '../..';
 
 const meta: Meta< typeof AlertDialog.Root > = {
 	title: 'Design System/Components/AlertDialog',
@@ -14,6 +14,7 @@ const meta: Meta< typeof AlertDialog.Root > = {
 		'AlertDialog.Popup': AlertDialog.Popup,
 	},
 	argTypes: {
+		onConfirm: { action: fn() },
 		onOpenChange: { action: fn() },
 	},
 };
@@ -33,10 +34,8 @@ export const Default: Story = {
 				<AlertDialog.Trigger>Move to trash</AlertDialog.Trigger>
 				<AlertDialog.Popup
 					title="Move to trash?"
-					onConfirm={ action( 'onConfirm' ) }
-				>
-					This post will be moved to trash. You can restore it later.
-				</AlertDialog.Popup>
+					description="This post will be moved to trash. You can restore it later."
+				/>
 			</>
 		),
 	},
@@ -48,38 +47,64 @@ export const Default: Story = {
  */
 export const Irreversible: Story = {
 	args: {
-		intent: 'irreversible',
 		children: (
 			<>
 				<AlertDialog.Trigger>Delete permanently</AlertDialog.Trigger>
 				<AlertDialog.Popup
+					intent="irreversible"
 					title="Delete permanently?"
-					onConfirm={ action( 'onConfirm' ) }
+					description="This action cannot be undone. All data will be lost."
 					confirmButtonText="Delete permanently"
-				>
-					This action cannot be undone. All data will be lost.
-				</AlertDialog.Popup>
+				/>
 			</>
 		),
 	},
 };
 
 /**
- * Example with custom button text for both confirm and cancel buttons.
+ * Example with custom button labels for both confirm and cancel buttons.
  */
-export const CustomButtonText: Story = {
+export const CustomLabels: Story = {
 	args: {
 		children: (
 			<>
 				<AlertDialog.Trigger>Send feedback</AlertDialog.Trigger>
 				<AlertDialog.Popup
 					title="Send feedback?"
-					onConfirm={ action( 'onConfirm' ) }
+					description="Your feedback helps us improve. Would you like to send it now?"
 					confirmButtonText="Send feedback"
 					cancelButtonText="Not now"
+				/>
+			</>
+		),
+	},
+};
+
+/**
+ * Use `children` to render custom content between the description and the
+ * action buttons. The `description` should be self-contained for
+ * accessibility (`aria-describedby`); `children` adds supplementary detail.
+ */
+export const WithCustomContent: Story = {
+	args: {
+		children: (
+			<>
+				<AlertDialog.Trigger>Remove pages</AlertDialog.Trigger>
+				<AlertDialog.Popup
+					title="Remove 3 pages?"
+					description="These pages will be moved to trash."
+					confirmButtonText="Delete pages"
 				>
-					Your feedback helps us improve. Would you like to send it
-					now?
+					<ul
+						style={ {
+							margin: 0,
+							paddingInlineStart: 'var(--wpds-dimension-gap-lg)',
+						} }
+					>
+						<Text render={ <li /> }>About us</Text>
+						<Text render={ <li /> }>Contact</Text>
+						<Text render={ <li /> }>Privacy policy</Text>
+					</ul>
 				</AlertDialog.Popup>
 			</>
 		),
@@ -117,10 +142,7 @@ const menuItemStyles: React.CSSProperties = {
  * component (not ready yet).
  */
 export const MenuTrigger: Story = {
-	args: {
-		intent: 'irreversible',
-	},
-	render: ( args ) => {
+	render: () => {
 		const [ menuOpen, setMenuOpen ] = useState( false );
 		return (
 			<>
@@ -132,7 +154,12 @@ export const MenuTrigger: Story = {
 								<Menu.Item style={ menuItemStyles }>
 									Edit
 								</Menu.Item>
-								<AlertDialog.Root { ...args }>
+								<AlertDialog.Root
+									onConfirm={ () => {
+										setMenuOpen( false );
+										action( 'onConfirm' )();
+									} }
+								>
 									<Menu.Item
 										render={
 											<AlertDialog.Trigger
@@ -147,16 +174,11 @@ export const MenuTrigger: Story = {
 									>
 										Delete...
 										<AlertDialog.Popup
+											intent="irreversible"
 											title="Delete permanently?"
-											onConfirm={ () => {
-												setMenuOpen( false );
-												action( 'onConfirm' )();
-											} }
+											description="This action cannot be undone. All data will be lost."
 											confirmButtonText="Delete permanently"
-										>
-											This action cannot be undone. All
-											data will be lost.
-										</AlertDialog.Popup>
+										/>
 									</Menu.Item>
 								</AlertDialog.Root>
 							</Menu.Popup>
@@ -168,56 +190,88 @@ export const MenuTrigger: Story = {
 	},
 };
 
+function sleep( ms: number ) {
+	return new Promise< void >( ( resolve ) => setTimeout( resolve, ms ) );
+}
+
 /**
- * Consumer-driven async confirm flow. The consumer uses controlled mode to
- * keep the dialog open while the async operation is in progress, and passes
- * `loading` to show a spinner on the confirm button and disable the cancel
- * button.
+ * Async confirm flow. The consumer returns a promise from `onConfirm`.
+ * The dialog automatically manages the pending state: buttons are disabled
+ * and a spinner appears on the confirm button. Toggle between success and
+ * failure to test both outcomes.
+ *
+ * On failure, the consumer catches the error and returns
+ * `{ close: false, error: '...' }`. The component displays the message
+ * below the action buttons and announces it to screen readers. The error
+ * is automatically cleared on the next confirm attempt or when the dialog
+ * reopens.
  */
 export const AsyncConfirm: Story = {
 	render: function AsyncConfirm( args ) {
-		const [ isOpen, setIsOpen ] = useState( false );
-		const [ isLoading, setIsLoading ] = useState( false );
+		const [ shouldFail, setShouldFail ] = useState( false );
+		const successId = useId();
+		const failureId = useId();
 
 		return (
 			<>
-				<button onClick={ () => setIsOpen( true ) }>
-					Delete permanently
-				</button>
+				<fieldset>
+					<legend>Async task outcome</legend>
+					<label htmlFor={ successId }>
+						<input
+							id={ successId }
+							type="radio"
+							name="async-outcome"
+							checked={ ! shouldFail }
+							onChange={ () => setShouldFail( false ) }
+						/>
+						Success (closes dialog)
+					</label>
+					<label
+						htmlFor={ failureId }
+						style={ { marginInlineStart: 12 } }
+					>
+						<input
+							id={ failureId }
+							type="radio"
+							name="async-outcome"
+							checked={ shouldFail }
+							onChange={ () => setShouldFail( true ) }
+						/>
+						Failure (dialog stays open, shows error)
+					</label>
+				</fieldset>
+				<br />
 				<AlertDialog.Root
 					{ ...args }
-					open={ isOpen }
-					onOpenChange={ ( open, eventDetails ) => {
-						if ( ! isLoading ) {
-							setIsOpen( open );
+					onConfirm={ async () => {
+						action( 'onConfirm' )();
+						try {
+							await sleep( 2000 );
+							if ( shouldFail ) {
+								throw new Error( 'Task failed' );
+							}
+						} catch {
+							return {
+								close: false,
+								error: 'Something went wrong. Please try again.',
+							};
 						}
-						args.onOpenChange?.( open, eventDetails );
+						return undefined;
 					} }
 				>
+					<AlertDialog.Trigger>
+						Delete permanently
+					</AlertDialog.Trigger>
 					<AlertDialog.Popup
+						intent="irreversible"
 						title="Delete permanently?"
-						loading={ isLoading }
-						onConfirm={ () => {
-							action( 'onConfirm' )();
-							setIsLoading( true );
-							new Promise< void >( ( resolve ) =>
-								setTimeout( resolve, 2000 )
-							).then( () => {
-								setIsLoading( false );
-								setIsOpen( false );
-							} );
-						} }
+						description="This action cannot be undone. All data will be lost."
 						confirmButtonText="Delete permanently"
-					>
-						This action cannot be undone. All data will be lost.
-					</AlertDialog.Popup>
+					/>
 				</AlertDialog.Root>
 			</>
 		);
 	},
-	args: {
-		intent: 'irreversible',
-	},
 };
 
 /**
@@ -242,11 +296,8 @@ export const Controlled: Story = {
 				>
 					<AlertDialog.Popup
 						title="Move to trash?"
-						onConfirm={ action( 'onConfirm' ) }
-					>
-						This post will be moved to trash. You can restore it
-						later.
-					</AlertDialog.Popup>
+						description="This post will be moved to trash. You can restore it later."
+					/>
 				</AlertDialog.Root>
 			</>
 		);

package/src/alert-dialog/style.module.css

@@ -1,5 +1,16 @@
 @layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
 
+@layer wp-ui-components {
+	.header {
+		margin-bottom: var(--wpds-dimension-gap-lg);
+	}
+
+	.error-message {
+		align-self: flex-end;
+		color: var(--wpds-color-fg-content-error);
+	}
+}
+
 @layer wp-ui-compositions {
 	.irreversible-action {
 		--wp-ui-button-background-color: var(--wpds-color-bg-interactive-error-strong);