@wordpress/ui 0.11.0 → 0.12.0

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

@@ -3,8 +3,9 @@ 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 '../..';
+import * as AlertDialog from '../';
+import { Stack } from '../../stack';
+import { Text } from '../../text';
 
 const meta: Meta< typeof AlertDialog.Root > = {
 	title: 'Design System/Components/AlertDialog',
@@ -97,7 +98,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 +112,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 +312,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 {

package/src/alert-dialog/test/index.test.tsx

@@ -1453,8 +1453,8 @@ describe( 'AlertDialog', () => {
 		} );
 	} );
 
-	describe( 'container', () => {
-		it( 'should render inside the container when provided', async () => {
+	describe( 'portal', () => {
+		it( 'should render inside the portal container when a custom target is provided', async () => {
 			const user = userEvent.setup();
 			const containerRef = createRef< HTMLDivElement >();
 
@@ -1468,7 +1468,11 @@ describe( 'AlertDialog', () => {
 						/>
 						<AlertDialog.Popup
 							title="Confirm"
-							container={ containerRef }
+							portal={
+								<AlertDialog.Portal
+									container={ containerRef }
+								/>
+							}
 						/>
 					</AlertDialog.Root>
 				</div>
@@ -1506,4 +1510,326 @@ describe( 'AlertDialog', () => {
 			);
 		} );
 	} );
+
+	describe( 'overlay scroll container', () => {
+		// AlertDialog's scroll container is a library-internal `<div>` with
+		// no role or testid — a `querySelector` is the only way to reach
+		// it from a test. The Testing Library rule is disabled for this
+		// helper because that's exactly what it's flagging.
+		const findScroller = ( popup: HTMLElement | null ): HTMLDivElement => {
+			if ( ! popup ) {
+				throw new Error(
+					'Popup ref not attached — did AlertDialog.Popup render?'
+				);
+			}
+			// eslint-disable-next-line testing-library/no-node-access
+			const el = popup.querySelector(
+				'[data-wp-ui-overlay-scroll-container]'
+			);
+			if ( ! ( el instanceof HTMLDivElement ) ) {
+				throw new Error(
+					'Scroll container not found inside AlertDialog popup'
+				);
+			}
+			return el;
+		};
+
+		it( 'renders an internal scroll container with data-wp-ui-overlay-scroll-container', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			expect( findScroller( popupRef.current ) ).toBeInstanceOf(
+				HTMLDivElement
+			);
+		} );
+
+		it( 'is always modal (data-wp-ui-overlay-modal present on popup)', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			expect( popupRef.current ).toHaveAttribute(
+				'data-wp-ui-overlay-modal'
+			);
+		} );
+
+		it( 'pins header and footer outside the scroller when sticky props are true (default)', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			const scroller = findScroller( popupRef.current );
+			const title = screen.getByRole( 'heading', { name: 'Title' } );
+			const ok = screen.getByRole( 'button', { name: 'OK' } );
+
+			// Default: chrome sits outside the scroll container.
+			expect( scroller ).not.toContainElement( title );
+			expect( scroller ).not.toContainElement( ok );
+		} );
+
+		it( 'nests header and footer inside the scroller when stickyHeader and stickyFooter are false', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup
+						ref={ popupRef }
+						title="Title"
+						stickyHeader={ false }
+						stickyFooter={ false }
+					>
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			const scroller = findScroller( popupRef.current );
+			const title = screen.getByRole( 'heading', { name: 'Title' } );
+			const ok = screen.getByRole( 'button', { name: 'OK' } );
+
+			expect( scroller ).toContainElement( title );
+			expect( scroller ).toContainElement( ok );
+		} );
+
+		it( 'toggles tabindex="0" on the scroller based on overflow', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			const scroller = findScroller( popupRef.current );
+
+			Object.defineProperty( scroller, 'scrollHeight', {
+				configurable: true,
+				value: 500,
+			} );
+			Object.defineProperty( scroller, 'clientHeight', {
+				configurable: true,
+				value: 100,
+			} );
+			Object.defineProperty( scroller, 'scrollTop', {
+				configurable: true,
+				value: 0,
+			} );
+
+			act( () => {
+				scroller.dispatchEvent(
+					new Event( 'scroll', { bubbles: true } )
+				);
+			} );
+
+			expect( scroller ).toHaveAttribute( 'tabindex', '0' );
+
+			Object.defineProperty( scroller, 'scrollHeight', {
+				configurable: true,
+				value: 100,
+			} );
+
+			act( () => {
+				scroller.dispatchEvent(
+					new Event( 'scroll', { bubbles: true } )
+				);
+			} );
+
+			expect( scroller ).not.toHaveAttribute( 'tabindex' );
+		} );
+
+		it( 'toggles data-wp-ui-overlay-scrolled-from-* on the scroller based on scroll position', async () => {
+			const popupRef = createRef< HTMLDivElement >();
+
+			render(
+				<AlertDialog.Root defaultOpen>
+					<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+					<AlertDialog.Popup ref={ popupRef } title="Title">
+						Body
+					</AlertDialog.Popup>
+				</AlertDialog.Root>
+			);
+
+			await waitFor( () => {
+				expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+			} );
+
+			// JSDOM doesn't lay out elements, so we simulate an
+			// overflowing scroll container by stubbing layout metrics
+			// per scenario and dispatching a scroll event.
+			const scroller = findScroller( popupRef.current );
+			Object.defineProperty( scroller, 'scrollHeight', {
+				configurable: true,
+				value: 500,
+			} );
+			Object.defineProperty( scroller, 'clientHeight', {
+				configurable: true,
+				value: 100,
+			} );
+
+			const setScrollTop = ( value: number ) => {
+				Object.defineProperty( scroller, 'scrollTop', {
+					configurable: true,
+					value,
+				} );
+				act( () => {
+					scroller.dispatchEvent(
+						new Event( 'scroll', { bubbles: true } )
+					);
+				} );
+			};
+
+			setScrollTop( 0 );
+			expect( scroller ).not.toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-top'
+			);
+			expect( scroller ).toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-bottom'
+			);
+
+			setScrollTop( 200 );
+			expect( scroller ).toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-top'
+			);
+			expect( scroller ).toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-bottom'
+			);
+
+			setScrollTop( 400 );
+			expect( scroller ).toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-top'
+			);
+			expect( scroller ).not.toHaveAttribute(
+				'data-wp-ui-overlay-scrolled-from-bottom'
+			);
+		} );
+
+		it( 'does not focus the scroll container on open even when it is keyboard-tabbable', async () => {
+			// JSDOM reports `scrollHeight`/`clientHeight` as 0 by default,
+			// so the scroll container would never overflow on its own and
+			// would never become `tabindex="0"`. Forcing both prototype
+			// getters to overflow values here makes the scroller
+			// keyboard-reachable at the moment Base UI resolves
+			// `initialFocus` — exactly the configuration that, without
+			// `useDeprioritizedInitialFocus` wired up, lets the scroller
+			// steal focus from the action buttons.
+			const originalScrollHeight = Object.getOwnPropertyDescriptor(
+				Element.prototype,
+				'scrollHeight'
+			);
+			const originalClientHeight = Object.getOwnPropertyDescriptor(
+				Element.prototype,
+				'clientHeight'
+			);
+			Object.defineProperty( Element.prototype, 'scrollHeight', {
+				configurable: true,
+				get() {
+					return 500;
+				},
+			} );
+			Object.defineProperty( Element.prototype, 'clientHeight', {
+				configurable: true,
+				get() {
+					return 100;
+				},
+			} );
+
+			try {
+				const user = userEvent.setup();
+				const popupRef = createRef< HTMLDivElement >();
+
+				render(
+					<AlertDialog.Root>
+						<AlertDialog.Trigger>Open</AlertDialog.Trigger>
+						<AlertDialog.Popup ref={ popupRef } title="Title">
+							Body that overflows
+						</AlertDialog.Popup>
+					</AlertDialog.Root>
+				);
+
+				await user.click(
+					screen.getByRole( 'button', { name: 'Open' } )
+				);
+
+				await waitFor( () => {
+					expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
+				} );
+
+				// The scroll container (overflow forced via the
+				// prototype stubs above) must not steal focus from the
+				// action buttons — that's exactly what the
+				// `useDeprioritizedInitialFocus` wiring on
+				// `AlertDialog.Popup` is there to prevent. The Cancel
+				// button is the first non-deprioritized tabbable, so
+				// focus should settle on it.
+				const scroller = findScroller( popupRef.current );
+				await waitFor( () => {
+					expect(
+						screen.getByRole( 'button', { name: 'Cancel' } )
+					).toHaveFocus();
+				} );
+				expect( scroller ).not.toHaveFocus();
+			} finally {
+				if ( originalScrollHeight ) {
+					Object.defineProperty(
+						Element.prototype,
+						'scrollHeight',
+						originalScrollHeight
+					);
+				}
+				if ( originalClientHeight ) {
+					Object.defineProperty(
+						Element.prototype,
+						'clientHeight',
+						originalClientHeight
+					);
+				}
+			}
+		} );
+	} );
 } );

package/src/alert-dialog/types.ts

@@ -1,8 +1,12 @@
 import type { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
-import type { ReactNode } from 'react';
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
 
 import type { ComponentProps } from '../utils/types';
 
+export type PortalProps = ComponentPropsWithoutRef<
+	typeof _AlertDialog.Portal
+>;
+
 /**
  * The return type of `onConfirm`. Return `void` (or nothing) to auto-close
  * the dialog after the confirm handler completes. Return `{ close: false }`
@@ -63,9 +67,15 @@ export interface PopupProps
 	extends ComponentProps< 'div' >,
 		Pick< _AlertDialog.Popup.Props, 'initialFocus' | 'finalFocus' > {
 	/**
-	 * A parent element to render the portal into.
+	 * Optional portal element, typically `<AlertDialog.Portal />` with
+	 * custom `container`, `className`, or `style`. Overlay content is
+	 * rendered as this portal's children (do not pass `children` on the portal
+	 * element; they would be ignored).
+	 *
+	 * When omitted, `AlertDialog.Popup` uses `AlertDialog.Portal` with default
+	 * props.
 	 */
-	container?: _AlertDialog.Portal.Props[ 'container' ];
+	portal?: ReactElement< Omit< PortalProps, 'children' > >;
 
 	/**
 	 * The semantic intent of the dialog, which determines its styling.
@@ -116,4 +126,21 @@ export interface PopupProps
 	 * @default 'Cancel'
 	 */
 	cancelButtonText?: string;
+
+	/**
+	 * When `true`, the dialog's title stays pinned to the top of the popup
+	 * as the body scrolls. When `false`, the title scrolls with the body.
+	 *
+	 * @default true
+	 */
+	stickyHeader?: boolean;
+
+	/**
+	 * When `true`, the dialog's action buttons (and error message, if any)
+	 * stay pinned to the bottom of the popup as the body scrolls. When
+	 * `false`, they scroll with the body.
+	 *
+	 * @default true
+	 */
+	stickyFooter?: boolean;
 }

package/src/badge/stories/choosing-intent.story.tsx

@@ -15,7 +15,7 @@ const meta: Meta< typeof Badge > = {
 	parameters: {
 		controls: { disable: true },
 	},
-	tags: [ '!dev' /* Hide individual story pages from sidebar */ ],
+	tags: [ '!dev' /* Hide individual story pages from sidebar */, 'manifest' ],
 };
 export default meta;
 

package/src/badge/stories/index.story.tsx

@@ -3,6 +3,7 @@ import { Fragment } from '@wordpress/element';
 import { Badge } from '../index';
 
 const meta: Meta< typeof Badge > = {
+	tags: [ 'manifest' ],
 	title: 'Design System/Components/Badge',
 	component: Badge,
 };

package/src/card/stories/index.story.tsx

@@ -24,6 +24,7 @@ function Text( { children }: { children: React.ReactNode } ) {
 }
 
 const meta: Meta< typeof Card.Root > = {
+	tags: [ 'manifest' ],
 	title: 'Design System/Components/Card',
 	component: Card.Root,
 	subcomponents: {

package/src/collapsible/stories/index.story.tsx

@@ -3,6 +3,7 @@ import { useState } from '@wordpress/element';
 import * as Collapsible from '../index';
 
 const meta: Meta< typeof Collapsible.Root > = {
+	tags: [ 'manifest' ],
 	title: 'Design System/Components/Collapsible',
 	component: Collapsible.Root,
 	subcomponents: {

package/src/collapsible-card/content.tsx

@@ -17,7 +17,18 @@ export const Content = forwardRef< HTMLDivElement, ContentProps >(
 		return (
 			<Collapsible.Panel
 				ref={ ref }
-				className={ clsx( styles.content, className ) }
+				// @ts-expect-error Base UI supports the callback-style
+				// version of the `className` prop, but we're purposefully
+				// not advertising it in our `@wordpress/ui` re-export.
+				className={ ( state ) =>
+					clsx(
+						styles.content,
+						state.open &&
+							state.transitionStatus === 'idle' &&
+							styles.overflowVisible,
+						className
+					)
+				}
 				hiddenUntilFound={ hiddenUntilFound }
 				{ ...restProps }
 			>

package/src/collapsible-card/header.tsx

@@ -5,6 +5,7 @@ import * as Card from '../card';
 import * as Collapsible from '../collapsible';
 import { Icon } from '../icon';
 import styles from './style.module.css';
+import defenseStyles from '../utils/css/global-css-defense.module.css';
 import focusStyles from '../utils/css/focus.module.css';
 import { HeaderDescriptionIdContext } from './context';
 import type { HeaderProps } from './types';
@@ -55,6 +56,7 @@ export const Header = forwardRef< HTMLDivElement, HeaderProps >(
 						<div
 							className={ clsx(
 								styles[ 'header-trigger-wrapper' ],
+								defenseStyles.div,
 								// While the interactive trigger element is the whole header,
 								// the focus ring will be displayed only on the icon to visually
 								// emulate it being the button.

package/src/collapsible-card/stories/index.story.tsx

@@ -26,6 +26,7 @@ function Text( { children }: { children: React.ReactNode } ) {
 }
 
 const meta: Meta< typeof CollapsibleCard.Root > = {
+	tags: [ 'manifest' ],
 	title: 'Design System/Components/CollapsibleCard',
 	component: CollapsibleCard.Root,
 	subcomponents: {