@wordpress/ui 0.12.1-next.v.202604201441.0 → 0.13.0

package/src/alert-dialog/popup.tsx

@@ -1,18 +1,28 @@
 import { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
 import clsx from 'clsx';
 import { forwardRef, useContext } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
 import { __ } from '@wordpress/i18n';
 import {
 	type ThemeProvider as ThemeProviderType,
 	privateApis as themePrivateApis,
 } from '@wordpress/theme';
 
+import { renderSlotWithChildren } from '../utils/render-slot-with-children';
 import { Button } from '../button';
 import dialogStyles from '../dialog/style.module.css';
+import focusStyles from '../utils/css/focus.module.css';
+import overlayChromeStyles from '../utils/css/overlay-chrome.module.css';
+import { useDeprioritizedInitialFocus } from '../utils/use-deprioritized-initial-focus';
+import {
+	SCROLL_CONTAINER_ATTR,
+	useOverlayScrollStateAttributes,
+} from '../utils/use-overlay-scroll-state-attributes';
 import { unlock } from '../lock-unlock';
 import { Stack } from '../stack';
 import { Text } from '../text';
 import { AlertDialogContext } from './context';
+import { Portal } from './portal';
 import alertDialogStyles from './style.module.css';
 import type { PopupProps } from './types';
 
@@ -23,13 +33,17 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >(
 	function AlertDialogPopup(
 		{
 			className,
-			container,
+			portal,
 			intent = 'default',
 			title,
 			description,
 			children,
 			confirmButtonText = __( 'OK' ),
 			cancelButtonText = __( 'Cancel' ),
+			stickyHeader = true,
+			stickyFooter = true,
+			initialFocus,
+			finalFocus,
 			...props
 		},
 		ref
@@ -37,6 +51,32 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >(
 		const { phase, showSpinner, errorMessage, confirm } =
 			useContext( AlertDialogContext );
 
+		/*
+		 * Scroll ownership lives on an internal scroll container so the
+		 * shared chrome CSS can target `[data-wp-ui-overlay-scroll-container]`
+		 * here the same way it does on Dialog.Content / Drawer.Content.
+		 * `stickyHeader` / `stickyFooter` control whether the chrome renders
+		 * as a sibling of the scroller (pinned) or inside it (scrolls with
+		 * the body).
+		 */
+		const { ref: scrollStateRef, onScroll } =
+			useOverlayScrollStateAttributes< HTMLDivElement >();
+
+		/*
+		 * Skip the internal scroll container during initial focus
+		 * resolution: when the body overflows, that container becomes
+		 * `tabindex="0"` (so keyboard users can arrow-scroll it) and
+		 * would otherwise win first-tabbable status over the action
+		 * buttons. Mirrors the same wiring on Dialog/Drawer popups.
+		 */
+		const { resolvedInitialFocus, popupRef } = useDeprioritizedInitialFocus(
+			{
+				initialFocus,
+				deprioritizedAttributes: [ SCROLL_CONTAINER_ATTR ],
+			}
+		);
+		const mergedRef = useMergeRefs( [ ref, popupRef ] );
+
 		const confirmClassName =
 			intent === 'irreversible'
 				? alertDialogStyles[ 'irreversible-action' ]
@@ -44,30 +84,83 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >(
 
 		const buttonsDisabled = phase !== 'idle' || undefined;
 
-		return (
-			<_AlertDialog.Portal container={ container }>
+		const headerElement = (
+			<div className={ overlayChromeStyles.header }>
+				<Text
+					variant="heading-xl"
+					render={ <_AlertDialog.Title /> }
+					className={ overlayChromeStyles.title }
+				>
+					{ title }
+				</Text>
+			</div>
+		);
+
+		const footerElement = (
+			<div
+				className={ clsx(
+					overlayChromeStyles.footer,
+					alertDialogStyles[ 'footer-column' ]
+				) }
+			>
+				<Stack
+					direction="row"
+					gap="sm"
+					justify="flex-end"
+					align="center"
+				>
+					<_AlertDialog.Close
+						render={ <Button variant="minimal" /> }
+						disabled={ buttonsDisabled }
+					>
+						{ cancelButtonText }
+					</_AlertDialog.Close>
+					<Button
+						className={ confirmClassName }
+						onClick={ confirm }
+						loading={ showSpinner || undefined }
+						disabled={ buttonsDisabled }
+					>
+						{ confirmButtonText }
+					</Button>
+				</Stack>
+				{ errorMessage && (
+					<Text
+						variant="body-sm"
+						className={ alertDialogStyles[ 'error-message' ] }
+					>
+						{ errorMessage }
+					</Text>
+				) }
+			</div>
+		);
+
+		const portalChildren = (
+			<>
 				<_AlertDialog.Backdrop className={ dialogStyles.backdrop } />
 				<ThemeProvider>
 					<_AlertDialog.Popup
-						ref={ ref }
+						ref={ mergedRef }
 						className={ clsx(
 							dialogStyles.popup,
 							className,
 							dialogStyles[ 'is-medium' ]
 						) }
+						initialFocus={ resolvedInitialFocus }
+						finalFocus={ finalFocus }
 						{ ...props }
+						data-wp-ui-overlay-modal=""
 					>
-						<Stack
-							direction="column"
-							gap="sm"
-							className={ alertDialogStyles.header }
+						{ stickyHeader && headerElement }
+						<div
+							ref={ scrollStateRef }
+							className={ clsx(
+								overlayChromeStyles.content,
+								focusStyles[ 'outset-ring--focus-visible' ]
+							) }
+							onScroll={ onScroll }
 						>
-							<Text
-								variant="heading-xl"
-								render={ <_AlertDialog.Title /> }
-							>
-								{ title }
-							</Text>
+							{ ! stickyHeader && headerElement }
 							{ description && (
 								<Text
 									variant="body-md"
@@ -76,40 +169,16 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >(
 									{ 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>
+							{ children }
+							{ ! stickyFooter && footerElement }
+						</div>
+						{ stickyFooter && footerElement }
 					</_AlertDialog.Popup>
 				</ThemeProvider>
-			</_AlertDialog.Portal>
+			</>
 		);
+
+		return renderSlotWithChildren( portal, <Portal />, portalChildren );
 	}
 );
 

package/src/alert-dialog/portal.tsx

@@ -0,0 +1,17 @@
+import { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
+import { forwardRef } from '@wordpress/element';
+import type { PortalProps } from './types';
+
+/**
+ * Root element that portals `AlertDialog` overlay content. Pass to
+ * `AlertDialog.Popup`'s `portal` prop to customize the portal target and
+ * wrapper. When `portal` is omitted, `AlertDialog.Popup` uses this component
+ * with default props.
+ */
+const Portal = forwardRef< HTMLDivElement, PortalProps >(
+	function AlertDialogPortal( props, ref ) {
+		return <_AlertDialog.Portal ref={ ref } { ...props } />;
+	}
+);
+
+export { Portal };

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

@@ -4,6 +4,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { action } from 'storybook/actions';
 import { fn } from 'storybook/test';
 import * as AlertDialog from '../';
+import { Stack } from '../../stack';
 import { Text } from '../../text';
 
 const meta: Meta< typeof AlertDialog.Root > = {
@@ -11,12 +12,20 @@ const meta: Meta< typeof AlertDialog.Root > = {
 	component: AlertDialog.Root,
 	subcomponents: {
 		'AlertDialog.Trigger': AlertDialog.Trigger,
+		'AlertDialog.Portal': AlertDialog.Portal,
 		'AlertDialog.Popup': AlertDialog.Popup,
 	},
 	argTypes: {
 		onConfirm: { action: fn() },
 		onOpenChange: { action: fn() },
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 
@@ -97,7 +106,7 @@ export const WithCustomContent: Story = {
 				>
 					<ul
 						style={ {
-							margin: 0,
+							margin: 'var(--wpds-dimension-gap-sm) 0 0',
 							paddingInlineStart: 'var(--wpds-dimension-gap-lg)',
 						} }
 					>
@@ -111,6 +120,43 @@ export const WithCustomContent: Story = {
 	},
 };
 
+/**
+ * Popovers in Gutenberg are managed with explicit z-index values, which can
+ * create situations where an alert dialog renders below another popover when
+ * you want it above.
+ *
+ * `AlertDialog` reuses `Dialog`'s styles, so the same
+ * `--wp-ui-dialog-z-index` CSS variable controls the z-index of the alert
+ * dialog's backdrop and popup. Override it either:
+ *
+ * - **Globally**, by setting the variable on `:root` or `body` (raises every
+ *   dialog and alert dialog in the page), or
+ * - **Per instance**, by passing an `AlertDialog.Portal` with a `style` (or
+ *   `className`) to `AlertDialog.Popup`'s `portal` prop. The variable
+ *   cascades from the portal wrapper to everything rendered inside it.
+ *
+ * This story demonstrates the per-instance approach.
+ */
+export const WithCustomZIndex: Story = {
+	name: 'With Custom z-index',
+	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."
+					portal={
+						<AlertDialog.Portal
+							style={ { '--wp-ui-dialog-z-index': '9999' } }
+						/>
+					}
+				/>
+			</>
+		),
+	},
+};
+
 const menuPopupStyles: React.CSSProperties = {
 	background: 'var(--wpds-color-bg-surface-neutral-strong)',
 	border: '1px solid var(--wpds-color-stroke-surface-neutral)',
@@ -274,6 +320,88 @@ export const AsyncConfirm: Story = {
 	},
 };
 
+function StickyToggle( {
+	label,
+	value,
+	onChange,
+}: {
+	label: string;
+	value: boolean;
+	onChange: ( value: boolean ) => void;
+} ) {
+	const id = useId();
+	return (
+		<Stack direction="row" gap="sm" align="center">
+			<input
+				id={ id }
+				type="checkbox"
+				checked={ value }
+				onChange={ ( event ) => onChange( event.target.checked ) }
+			/>
+			<label htmlFor={ id }>{ label }</label>
+		</Stack>
+	);
+}
+
+function ScrollableContent() {
+	const [ stickyHeader, setStickyHeader ] = useState( true );
+	const [ stickyFooter, setStickyFooter ] = useState( true );
+	return (
+		<>
+			<Stack direction="column" gap="lg" align="start">
+				<Stack direction="row" gap="lg" align="center">
+					<StickyToggle
+						label="Sticky header"
+						value={ stickyHeader }
+						onChange={ setStickyHeader }
+					/>
+					<StickyToggle
+						label="Sticky footer"
+						value={ stickyFooter }
+						onChange={ setStickyFooter }
+					/>
+				</Stack>
+				<AlertDialog.Trigger>Review terms</AlertDialog.Trigger>
+			</Stack>
+			<AlertDialog.Popup
+				title="Terms of service"
+				description="Please review the terms before continuing."
+				confirmButtonText="Accept"
+				cancelButtonText="Decline"
+				stickyHeader={ stickyHeader }
+				stickyFooter={ stickyFooter }
+			>
+				<Stack direction="column" gap="lg">
+					{ Array.from( { length: 20 } ).map( ( _, index ) => (
+						<p key={ index } style={ { margin: 0 } }>
+							Paragraph { index + 1 }: Lorem ipsum dolor sit amet,
+							consectetur adipiscing elit. Sed do eiusmod tempor
+							incididunt ut labore et dolore magna aliqua. Ut enim
+							ad minim veniam, quis nostrud exercitation ullamco
+							laboris nisi ut aliquip ex ea commodo consequat.
+						</p>
+					) ) }
+				</Stack>
+			</AlertDialog.Popup>
+		</>
+	);
+}
+
+/**
+ * When the dialog's body overflows the available height, the title/description
+ * area stays pinned to the top of the popup and the action buttons stay pinned
+ * to the bottom so users keep sight of the context and primary actions while
+ * scrolling. Separator borders appear only when there is off-screen content
+ * above or below. Pass `stickyHeader={ false }` or `stickyFooter={ false }` on
+ * `AlertDialog.Popup` to opt out — the toggles in this story drive both props
+ * independently.
+ */
+export const Scrollable: Story = {
+	args: {
+		children: <ScrollableContent />,
+	},
+};
+
 /**
  * The `AlertDialog.Trigger` element is not necessary when the open state is
  * controlled externally. This is useful when the dialog needs to be opened

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

@@ -1,14 +1,23 @@
 @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);
 	}
+
+	/*
+	 * AlertDialog stacks an actions row and an optional error message in
+	 * its footer. Override the shared `.footer` row layout to a column so
+	 * both children lay out vertically while inheriting the chrome
+	 * padding + separator from `overlay-chrome.module.css`.
+	 */
+	.footer-column {
+		flex-direction: column;
+		align-items: stretch;
+		justify-content: flex-start;
+		gap: var(--wpds-dimension-gap-md);
+	}
 }
 
 @layer wp-ui-compositions {