@wordpress/ui 0.9.1-next.v.202603161435.0 → 0.11.0

package/src/alert-dialog/popup.tsx

@@ -0,0 +1,116 @@
+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 dialogStyles from '../dialog/style.module.css';
+import { unlock } from '../lock-unlock';
+import { Stack } from '../stack';
+import { Text } from '../text';
+import { AlertDialogContext } from './context';
+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,
+			container,
+			intent = 'default',
+			title,
+			description,
+			children,
+			confirmButtonText = __( 'OK' ),
+			cancelButtonText = __( 'Cancel' ),
+			...props
+		},
+		ref
+	) {
+		const { phase, showSpinner, errorMessage, confirm } =
+			useContext( AlertDialogContext );
+
+		const confirmClassName =
+			intent === 'irreversible'
+				? alertDialogStyles[ 'irreversible-action' ]
+				: undefined;
+
+		const buttonsDisabled = phase !== 'idle' || undefined;
+
+		return (
+			<_AlertDialog.Portal container={ container }>
+				<_AlertDialog.Backdrop className={ dialogStyles.backdrop } />
+				<ThemeProvider>
+					<_AlertDialog.Popup
+						ref={ ref }
+						className={ clsx(
+							dialogStyles.popup,
+							className,
+							dialogStyles[ 'is-medium' ]
+						) }
+						{ ...props }
+					>
+						<Stack
+							direction="column"
+							gap="sm"
+							className={ alertDialogStyles.header }
+						>
+							<Text
+								variant="heading-xl"
+								render={ <_AlertDialog.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>
+		);
+	}
+);
+
+export { Popup };

package/src/alert-dialog/root.tsx

@@ -0,0 +1,226 @@
+import { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
+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.
+ *
+ * Use `AlertDialog.Trigger` to render a button that opens the dialog.
+ * Use `AlertDialog.Popup` to render the dialog content.
+ * The `AlertDialog.Trigger` is optional — the dialog can also be controlled
+ * via `open` / `onOpenChange` props.
+ *
+ * For use cases outside the standard confirm/cancel pattern, use the lower-level
+ * `Dialog` component directly.
+ *
+ * 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( {
+	children,
+	open: openProp,
+	onOpenChange,
+	defaultOpen,
+	onConfirm,
+}: RootProps ) {
+	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={ effectiveOpen }
+			defaultOpen={ defaultOpen }
+			onOpenChange={ handleOpenChange }
+			onOpenChangeComplete={ handleOpenChangeComplete }
+			actionsRef={ actionsRef }
+		>
+			<AlertDialogContext.Provider value={ contextValue }>
+				{ children }
+			</AlertDialogContext.Provider>
+		</_AlertDialog.Root>
+	);
+}
+
+export { Root };

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

@@ -0,0 +1,305 @@
+import { Menu } from '@base-ui/react/menu';
+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, Text } from '../..';
+
+const meta: Meta< typeof AlertDialog.Root > = {
+	title: 'Design System/Components/AlertDialog',
+	component: AlertDialog.Root,
+	subcomponents: {
+		'AlertDialog.Trigger': AlertDialog.Trigger,
+		'AlertDialog.Popup': AlertDialog.Popup,
+	},
+	argTypes: {
+		onConfirm: { action: fn() },
+		onOpenChange: { action: fn() },
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof AlertDialog.Root >;
+
+/**
+ * Standard confirmation dialog for reversible actions. The dialog can be
+ * dismissed via Escape key or the cancel/confirm buttons. Backdrop click
+ * is blocked.
+ */
+export const Default: Story = {
+	args: {
+		children: (
+			<>
+				<AlertDialog.Trigger>Move to trash</AlertDialog.Trigger>
+				<AlertDialog.Popup
+					title="Move to trash?"
+					description="This post will be moved to trash. You can restore it later."
+				/>
+			</>
+		),
+	},
+};
+
+/**
+ * Confirmation dialog for irreversible actions that cannot be undone.
+ * The confirm button uses error/danger coloring.
+ */
+export const Irreversible: Story = {
+	args: {
+		children: (
+			<>
+				<AlertDialog.Trigger>Delete permanently</AlertDialog.Trigger>
+				<AlertDialog.Popup
+					intent="irreversible"
+					title="Delete permanently?"
+					description="This action cannot be undone. All data will be lost."
+					confirmButtonText="Delete permanently"
+				/>
+			</>
+		),
+	},
+};
+
+/**
+ * Example with custom button labels for both confirm and cancel buttons.
+ */
+export const CustomLabels: Story = {
+	args: {
+		children: (
+			<>
+				<AlertDialog.Trigger>Send feedback</AlertDialog.Trigger>
+				<AlertDialog.Popup
+					title="Send feedback?"
+					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"
+				>
+					<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>
+			</>
+		),
+	},
+};
+
+const menuPopupStyles: React.CSSProperties = {
+	background: 'var(--wpds-color-bg-surface-neutral-strong)',
+	border: '1px solid var(--wpds-color-stroke-surface-neutral)',
+	borderRadius: '8px',
+	padding: '4px',
+	minWidth: '160px',
+	boxShadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
+};
+
+const menuItemStyles: React.CSSProperties = {
+	display: 'block',
+	width: '100%',
+	padding: '8px 12px',
+	borderRadius: '4px',
+	border: 'none',
+	background: 'none',
+	textAlign: 'start',
+	fontSize: 'inherit',
+	userSelect: 'none',
+};
+
+/**
+ * Example showing composition with a menu. The `AlertDialog.Trigger` is
+ * composed with Base UI's `Menu.Item` using the `render` prop, allowing the
+ * menu item to directly trigger the alert dialog.
+ *
+ * Note: the example currently uses the `Menu` component from BaseUI, although
+ * consumers should not use BaseUI directly and instead use the DS `Menu`
+ * component (not ready yet).
+ */
+export const MenuTrigger: Story = {
+	render: () => {
+		const [ menuOpen, setMenuOpen ] = useState( false );
+		return (
+			<>
+				<Menu.Root onOpenChange={ setMenuOpen } open={ menuOpen }>
+					<Menu.Trigger>Actions ▾</Menu.Trigger>
+					<Menu.Portal>
+						<Menu.Positioner>
+							<Menu.Popup style={ menuPopupStyles }>
+								<Menu.Item style={ menuItemStyles }>
+									Edit
+								</Menu.Item>
+								<AlertDialog.Root
+									onConfirm={ () => {
+										setMenuOpen( false );
+										action( 'onConfirm' )();
+									} }
+								>
+									<Menu.Item
+										render={
+											<AlertDialog.Trigger
+												// Quick fix to remove `button`-specific styles.
+												// This shouldn't be an issue once we use the DS `Menu`
+												// component, which will come with item styles.
+												render={ <div /> }
+											/>
+										}
+										style={ menuItemStyles }
+										closeOnClick={ false }
+									>
+										Delete...
+										<AlertDialog.Popup
+											intent="irreversible"
+											title="Delete permanently?"
+											description="This action cannot be undone. All data will be lost."
+											confirmButtonText="Delete permanently"
+										/>
+									</Menu.Item>
+								</AlertDialog.Root>
+							</Menu.Popup>
+						</Menu.Positioner>
+					</Menu.Portal>
+				</Menu.Root>
+			</>
+		);
+	},
+};
+
+function sleep( ms: number ) {
+	return new Promise< void >( ( resolve ) => setTimeout( resolve, ms ) );
+}
+
+/**
+ * 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 [ shouldFail, setShouldFail ] = useState( false );
+		const successId = useId();
+		const failureId = useId();
+
+		return (
+			<>
+				<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 }
+					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.',
+							};
+						}
+						return undefined;
+					} }
+				>
+					<AlertDialog.Trigger>
+						Delete permanently
+					</AlertDialog.Trigger>
+					<AlertDialog.Popup
+						intent="irreversible"
+						title="Delete permanently?"
+						description="This action cannot be undone. All data will be lost."
+						confirmButtonText="Delete permanently"
+					/>
+				</AlertDialog.Root>
+			</>
+		);
+	},
+};
+
+/**
+ * The `AlertDialog.Trigger` element is not necessary when the open state is
+ * controlled externally. This is useful when the dialog needs to be opened
+ * from code or from a non-standard trigger element.
+ */
+export const Controlled: Story = {
+	render: function Controlled( args ) {
+		const [ isOpen, setIsOpen ] = useState( false );
+
+		return (
+			<>
+				<button onClick={ () => setIsOpen( true ) }>Open Dialog</button>
+				<AlertDialog.Root
+					{ ...args }
+					open={ isOpen }
+					onOpenChange={ ( open, eventDetails ) => {
+						setIsOpen( open );
+						args.onOpenChange?.( open, eventDetails );
+					} }
+				>
+					<AlertDialog.Popup
+						title="Move to trash?"
+						description="This post will be moved to trash. You can restore it later."
+					/>
+				</AlertDialog.Root>
+			</>
+		);
+	},
+};

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

@@ -0,0 +1,21 @@
+@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);
+		--wp-ui-button-background-color-active: var(--wpds-color-bg-interactive-error-strong-active);
+		--wp-ui-button-foreground-color: var(--wpds-color-fg-interactive-error-strong);
+		--wp-ui-button-foreground-color-active: var(--wpds-color-fg-interactive-error-strong-active);
+	}
+}