@wordpress/ui 0.10.0 → 0.11.0

package/build-types/tooltip/stories/usage-guidelines.story.d.ts

@@ -0,0 +1,21 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+declare const meta: Meta;
+export default meta;
+type Story = StoryObj;
+/**
+ * Tooltips work best as visual labels for icon-only controls. Each trigger
+ * must have its own accessible name via `aria-label`.
+ */
+export declare const RecommendedUsage: Story;
+/**
+ * Popups that open when hovering an info icon should use `Popover` with
+ * `openOnHover` instead of a Tooltip. This ensures the content is accessible
+ * to touch and screen reader users.
+ */
+export declare const InfotipWithPopover: Story;
+/**
+ * `IconButton` has built-in tooltip support via the `label` prop,
+ * making it the easiest way to provide a tooltip for icon-only actions.
+ */
+export declare const IconButtonWithTooltip: Story;
+//# sourceMappingURL=usage-guidelines.story.d.ts.map

package/build-types/tooltip/stories/usage-guidelines.story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-guidelines.story.d.ts","sourceRoot":"","sources":["../../../src/tooltip/stories/usage-guidelines.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAS5D,QAAA,MAAM,IAAI,EAAE,IAMX,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC;AAEtB;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,KA2B9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,KA0ChC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAYnC,CAAC"}

package/build-types/tooltip/types.d.ts

@@ -14,5 +14,9 @@ export interface PopupProps extends ComponentProps<'div'>, Pick<Tooltip.Position
      * The content to be rendered inside the component.
      */
     children?: ReactNode;
+    /**
+     * A parent element to render the portal into.
+     */
+    container?: Tooltip.Portal.Props['container'];
 }
 //# sourceMappingURL=types.d.ts.map

package/build-types/tooltip/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tooltip/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG,IAAI,CAAE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAE,CAAC;AAE5E,MAAM,MAAM,aAAa,GAAG,IAAI,CAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,EACtB,OAAO,GAAG,UAAU,CACpB,CAAC;AAEF,MAAM,WAAW,YAAa,SAAQ,cAAc,CAAE,QAAQ,CAAE;IAC/D;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,UAChB,SAAQ,cAAc,CAAE,KAAK,CAAE,EAC9B,IAAI,CAAE,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAE;IAClE;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tooltip/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG,IAAI,CAAE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAE,CAAC;AAE5E,MAAM,MAAM,aAAa,GAAG,IAAI,CAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,EACtB,OAAO,GAAG,UAAU,CACpB,CAAC;AAEF,MAAM,WAAW,YAAa,SAAQ,cAAc,CAAE,QAAQ,CAAE;IAC/D;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,UAChB,SAAQ,cAAc,CAAE,KAAK,CAAE,EAC9B,IAAI,CAAE,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAE;IAClE;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAE,WAAW,CAAE,CAAC;CAChD"}

package/build-types/utils/types.d.ts

@@ -3,11 +3,15 @@ type HTMLAttributesWithRef<T extends ElementType = any> = HTMLAttributes<T> & {
     ref?: Ref<T> | undefined;
 };
 type ComponentRenderFn<Props> = (props: Props) => React.ReactElement<unknown>;
-export type ComponentProps<E extends ElementType> = Omit<ComponentPropsWithoutRef<E>, 'className' | 'children' | 'render'> & {
+export type ComponentProps<E extends ElementType> = Omit<ComponentPropsWithoutRef<E>, 'className' | 'children' | 'render' | 'style'> & {
     /**
-     * CSS class name to apply to the component.
+     * CSS class name to apply to the element.
      */
     className?: string;
+    /**
+     * CSS style to apply to the element.
+     */
+    style?: React.CSSProperties;
     /**
      * Replaces the component's default HTML element using a given React
      * element, or a function that returns a React element.

package/build-types/utils/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,GAAG,EACR,MAAM,OAAO,CAAC;AAEf,KAAK,qBAAqB,CAAE,CAAC,SAAS,WAAW,GAAG,GAAG,IACtD,cAAc,CAAE,CAAC,CAAE,GAAG;IAAE,GAAG,CAAC,EAAE,GAAG,CAAE,CAAC,CAAE,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,KAAK,iBAAiB,CAAE,KAAK,IAAK,CACjC,KAAK,EAAE,KAAK,KACR,KAAK,CAAC,YAAY,CAAE,OAAO,CAAE,CAAC;AAEnC,MAAM,MAAM,cAAc,CAAE,CAAC,SAAS,WAAW,IAAK,IAAI,CACzD,wBAAwB,CAAE,CAAC,CAAE,EAC7B,WAAW,GAAG,UAAU,GAAG,QAAQ,CACnC,GAAG;IACH;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EACJ,iBAAiB,CAAE,qBAAqB,CAAE,GAC1C,KAAK,CAAC,YAAY,CAAE,MAAM,CAAE,MAAM,EAAE,OAAO,CAAE,CAAE,CAAC;CACnD,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,GAAG,EACR,MAAM,OAAO,CAAC;AAEf,KAAK,qBAAqB,CAAE,CAAC,SAAS,WAAW,GAAG,GAAG,IACtD,cAAc,CAAE,CAAC,CAAE,GAAG;IAAE,GAAG,CAAC,EAAE,GAAG,CAAE,CAAC,CAAE,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,KAAK,iBAAiB,CAAE,KAAK,IAAK,CACjC,KAAK,EAAE,KAAK,KACR,KAAK,CAAC,YAAY,CAAE,OAAO,CAAE,CAAC;AAEnC,MAAM,MAAM,cAAc,CAAE,CAAC,SAAS,WAAW,IAAK,IAAI,CACzD,wBAAwB,CAAE,CAAC,CAAE,EAC7B,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAC7C,GAAG;IACH;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAE5B;;;OAGG;IACH,MAAM,CAAC,EACJ,iBAAiB,CAAE,qBAAqB,CAAE,GAC1C,KAAK,CAAC,YAAY,CAAE,MAAM,CAAE,MAAM,EAAE,OAAO,CAAE,CAAE,CAAC;CACnD,CAAC"}

package/build-types/utils/use-deprioritized-initial-focus.d.ts

@@ -1,9 +1,10 @@
-import type { Dialog as _Dialog } from '@base-ui/react/dialog';
+import type { Popover as _Popover } from '@base-ui/react/popover';
 /**
- * Derived from Base UI's `Dialog.Popup.Props['initialFocus']`.
- * The same type is shared by all Base UI overlay popups (Dialog, Popover, etc.).
+ * The `initialFocus` type shared by Base UI overlay popups (Dialog, Popover,
+ * AlertDialog, etc.). We derive it from `Popover.Popup.Props` here, but it
+ * is identical across all overlay components.
  */
-type InitialFocus = _Dialog.Popup.Props['initialFocus'];
+type InitialFocus = _Popover.Popup.Props['initialFocus'];
 /**
  * Returns a resolved `initialFocus` value that deprioritizes elements
  * marked with a given data attribute (e.g. a close icon), and an internal
@@ -28,7 +29,7 @@ export declare function useDeprioritizedInitialFocus({ initialFocus, deprioritiz
     initialFocus: InitialFocus;
     deprioritizedAttribute: string;
 }): {
-    resolvedInitialFocus: boolean | import("react").RefObject<HTMLElement | null> | ((openType: import("@base-ui/utils/useEnhancedClickHandler").InteractionType) => boolean | HTMLElement | null | void) | undefined;
+    resolvedInitialFocus: boolean | import("react").RefObject<HTMLElement | null> | ((openType: import("@base-ui/utils/useEnhancedClickHandler").InteractionType) => void | boolean | HTMLElement | null) | undefined;
     popupRef: import("react").RefObject<HTMLDivElement>;
 };
 export {};

package/build-types/utils/use-deprioritized-initial-focus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-deprioritized-initial-focus.d.ts","sourceRoot":"","sources":["../../src/utils/use-deprioritized-initial-focus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAI/D;;;GAGG;AACH,KAAK,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAE,cAAc,CAAE,CAAC;AAe1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAAE,EAC7C,YAAY,EACZ,sBAAsB,GACtB,EAAE;IACF,YAAY,EAAE,YAAY,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;CAC/B;;;EAiCA"}
+{"version":3,"file":"use-deprioritized-initial-focus.d.ts","sourceRoot":"","sources":["../../src/utils/use-deprioritized-initial-focus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIlE;;;;GAIG;AACH,KAAK,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAE,cAAc,CAAE,CAAC;AAe3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAAE,EAC7C,YAAY,EACZ,sBAAsB,GACtB,EAAE;IACF,YAAY,EAAE,YAAY,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;CAC/B;;;EAiCA"}

package/build-types/visually-hidden/stories/index.story.d.ts

@@ -4,4 +4,11 @@ declare const meta: Meta<typeof VisuallyHidden>;
 export default meta;
 type Story = StoryObj<typeof VisuallyHidden>;
 export declare const Default: Story;
+/**
+ * Use the `render` prop to change the underlying HTML element.
+ * By default, `VisuallyHidden` renders a `<div>`. Here it renders
+ * a `<label>` instead, keeping the native label–input association
+ * while hiding the label text visually.
+ */
+export declare const WithCustomElement: Story;
 //# sourceMappingURL=index.story.d.ts.map

package/build-types/visually-hidden/stories/index.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/visually-hidden/stories/index.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAErC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,cAAc,CAGtC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAE,OAAO,cAAc,CAAE,CAAC;AAE/C,eAAO,MAAM,OAAO,EAAE,KAUrB,CAAC"}
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/visually-hidden/stories/index.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAErC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,cAAc,CAGtC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAE,OAAO,cAAc,CAAE,CAAC;AAE/C,eAAO,MAAM,OAAO,EAAE,KAUrB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAgB/B,CAAC"}

package/build-types/visually-hidden/visually-hidden.d.ts

@@ -2,6 +2,40 @@ import type { VisuallyHiddenProps } from './types';
 /**
  * Visually hides content while keeping it accessible to screen readers.
  * Useful when providing context that's only meaningful to assistive technology.
+ *
+ * Renders a `<div>` by default. Use the `render` prop to swap the
+ * underlying element while preserving the visually-hidden behavior.
+ *
+ * ## Composing with other components
+ *
+ * When composing with another component that uses the `render` prop
+ * pattern, there are two directions — and they produce different results.
+ *
+ * Most of the time you'll want `VisuallyHidden` as the **host** (outer
+ * component) and pass the other component via `render`. This keeps the
+ * other component's HTML element and semantics intact, while
+ * `VisuallyHidden` only adds its hiding styles:
+ *
+ * ```jsx
+ * // OtherComponent keeps its semantic element (e.g. <h2>).
+ * <VisuallyHidden render={ <OtherComponent /> }>
+ *   Accessible text
+ * </VisuallyHidden>
+ * ```
+ *
+ * The opposite direction is also possible, but be aware that it replaces
+ * the other component's element with VisuallyHidden's default `<div>`:
+ *
+ * ```jsx
+ * // OtherComponent's element becomes a <div>.
+ * <OtherComponent render={ <VisuallyHidden /> }>
+ *   Accessible text
+ * </OtherComponent>
+ * ```
+ *
+ * Choose based on what you need: if the other component's semantic
+ * element matters (e.g. `<label>`, `<legend>`, `<h2>`), keep
+ * `VisuallyHidden` as the host so the element is preserved.
  */
 export declare const VisuallyHidden: import("react").ForwardRefExoticComponent<VisuallyHiddenProps & import("react").RefAttributes<HTMLDivElement>>;
 //# sourceMappingURL=visually-hidden.d.ts.map

package/build-types/visually-hidden/visually-hidden.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"visually-hidden.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/visually-hidden.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAGnD;;;GAGG;AACH,eAAO,MAAM,cAAc,gHAa1B,CAAC"}
+{"version":3,"file":"visually-hidden.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/visually-hidden.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,cAAc,gHAa1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/ui",
-	"version": "0.10.0",
+	"version": "0.11.0",
 	"description": "Themeable React UI components for the WordPress Design System.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -43,16 +43,16 @@
 	"types": "build-types",
 	"sideEffects": false,
 	"dependencies": {
-		"@base-ui/react": "^1.3.0",
-		"@wordpress/a11y": "^4.43.0",
-		"@wordpress/compose": "^7.43.0",
-		"@wordpress/element": "^6.43.0",
-		"@wordpress/i18n": "^6.16.0",
-		"@wordpress/icons": "^12.1.0",
-		"@wordpress/keycodes": "^4.43.0",
-		"@wordpress/primitives": "^4.43.0",
-		"@wordpress/private-apis": "^1.43.0",
-		"@wordpress/theme": "^0.10.0",
+		"@base-ui/react": "^1.4.0",
+		"@wordpress/a11y": "^4.44.0",
+		"@wordpress/compose": "^7.44.0",
+		"@wordpress/element": "^6.44.0",
+		"@wordpress/i18n": "^6.17.0",
+		"@wordpress/icons": "^12.2.0",
+		"@wordpress/keycodes": "^4.44.0",
+		"@wordpress/primitives": "^4.44.0",
+		"@wordpress/private-apis": "^1.44.0",
+		"@wordpress/theme": "^0.11.0",
 		"clsx": "^2.1.1",
 		"tabbable": "^6.4.0"
 	},
@@ -71,5 +71,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "2cea90674d11aa521ec3f71652fb3a6a4c383969"
+	"gitHead": "b862d8c84121a47bbeff882f6c87e61681ce2e0d"
 }

package/src/alert-dialog/context.tsx

@@ -1,14 +1,22 @@
 import { createContext } from '@wordpress/element';
-import type { RootProps } from './types';
 
-type Intent = NonNullable< RootProps[ 'intent' ] >;
+type Phase = 'idle' | 'pending' | 'closing';
 
 interface AlertDialogContextValue {
-	intent: Intent;
+	phase: Phase;
+	showSpinner: boolean;
+	errorMessage?: string;
+	confirm: () => Promise< void >;
 }
 
+const noop = async () => {};
+
 const AlertDialogContext = createContext< AlertDialogContextValue >( {
-	intent: 'default',
+	phase: 'idle',
+	showSpinner: false,
+	errorMessage: undefined,
+	confirm: noop,
 } );
 
 export { AlertDialogContext };
+export type { Phase };

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,
+			container,
+			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 container={ container }>
+				<_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 /> }
+							>
+								{ 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 }