@wordpress/ui 0.11.0 → 0.12.0

package/src/collapsible-card/style.module.css

@@ -28,7 +28,7 @@
 	}
 
 	.header-trigger {
-		@media not (prefers-reduced-motion) {
+		@media not ( prefers-reduced-motion ) {
 			transition: rotate 0.15s ease-out;
 		}
 	}
@@ -44,9 +44,18 @@
 
 	.content {
 		height: var(--collapsible-panel-height);
-		overflow: hidden;
 		margin-block-start: var(--wp-ui-card-header-content-margin);
 
+		/* Clip while collapsed or transitioning so the panel collapses
+		   cleanly. The `overflowVisible` class is set once the open
+		   transition has settled, dropping the clip so descendant
+		   focus rings aren't cut off. */
+		overflow: hidden;
+
+		&.overflowVisible {
+			overflow: visible;
+		}
+
 		&[hidden]:not([hidden="until-found"]) {
 			display: none;
 		}
@@ -56,15 +65,18 @@
 			height: 0;
 		}
 
-		@media not (prefers-reduced-motion) {
+		@media not ( prefers-reduced-motion ) {
 			transition: all 150ms ease-out;
 		}
 	}
-
 }
 
 @layer wp-ui-compositions {
 	.content-inner {
+		/* Card.Content's `.header + .content` selector doesn't match here
+		   because Collapsible.Panel sits between Card.Header and Card.Content.
+		   Re-apply the zero top padding manually so the header/content gap
+		   matches Card. */
 		padding-block-start: 0;
 	}
 

package/src/dialog/content.tsx

@@ -0,0 +1,47 @@
+import { mergeProps, useRender } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
+import { useOverlayScrollStateAttributes } from '../utils/use-overlay-scroll-state-attributes';
+import focusStyles from '../utils/css/focus.module.css';
+import styles from './style.module.css';
+import type { ContentProps } from './types';
+
+/**
+ * Renders the scrollable body of the dialog, sitting between `Dialog.Header`
+ * and `Dialog.Footer` as a flex sibling.
+ *
+ * **Required for scrolling** — `Dialog.Content` is the element that owns
+ * the popup's overflow. Without it, body content that exceeds the popup's
+ * max height clips instead of scrolling. Render it once per popup and wrap
+ * any freeform body content in it.
+ *
+ * Placing `Dialog.Header` or `Dialog.Footer` *inside* `Dialog.Content`
+ * makes them scroll with the body (the "non-sticky" opt-out) rather than
+ * staying pinned to the popup's edges.
+ */
+const Content = forwardRef< HTMLDivElement, ContentProps >(
+	function DialogContent( { className, render, onScroll, ...props }, ref ) {
+		const { ref: scrollStateRef, onScroll: scrollStateOnScroll } =
+			useOverlayScrollStateAttributes< HTMLDivElement >( onScroll );
+		const mergedRef = useMergeRefs( [ ref, scrollStateRef ] );
+
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref: mergedRef,
+			props: mergeProps< 'div' >( props, {
+				className: clsx(
+					styles.content,
+					focusStyles[ 'outset-ring--focus-visible' ],
+					className
+				),
+				onScroll: scrollStateOnScroll,
+			} ),
+		} );
+
+		return element;
+	}
+);
+
+export { Content };

package/src/dialog/context.tsx

@@ -1,113 +1,29 @@
-import {
-	createContext,
-	useCallback,
-	useContext,
-	useEffect,
-	useMemo,
-	useRef,
-} from '@wordpress/element';
+import type { Dialog as _Dialog } from '@base-ui/react/dialog';
+import { createOverlayModalContext } from '../utils/create-overlay-modal-context';
+import { createOverlayTitleValidation } from '../utils/create-overlay-title-validation';
 
-/**
- * Whether validation is enabled. This is a build-time constant that allows
- * bundlers to tree-shake all validation code in production builds.
- */
-const VALIDATION_ENABLED = process.env.NODE_ENV !== 'production';
+// -- Modal context ----------------------------------------------------------
 
-type DialogValidationContextType = {
-	registerTitle: ( element: HTMLElement | null ) => void;
-};
+const dialogModal =
+	createOverlayModalContext< _Dialog.Root.Props[ 'modal' ] >( true );
 
-// Context is only created in development mode.
-const DialogValidationContext = VALIDATION_ENABLED
-	? createContext< DialogValidationContextType | null >( null )
-	: ( null as unknown as React.Context< DialogValidationContextType | null > );
+export const DialogModalProvider = dialogModal.Provider;
+export const useDialogModal = dialogModal.useModal;
 
-/**
- * Development-only hook to access the dialog validation context.
- */
-function useDialogValidationContextDev() {
-	return useContext( DialogValidationContext );
-}
+// -- Validation context (dev-only) ------------------------------------------
 
-/**
- * Production no-op hook.
- */
-function useDialogValidationContextProd() {
-	return null;
-}
+const dialogTitleValidation = createOverlayTitleValidation( 'Dialog' );
 
 /**
  * Hook to access the dialog validation context.
  * Returns null in production or if not within a Dialog.Popup.
  */
-export const useDialogValidationContext = VALIDATION_ENABLED
-	? useDialogValidationContextDev
-	: useDialogValidationContextProd;
-
-/**
- * Development-only provider that tracks whether Dialog.Title is rendered.
- */
-function DialogValidationProviderDev( {
-	children,
-}: {
-	children: React.ReactNode;
-} ) {
-	const titleElementRef = useRef< HTMLElement | null >( null );
-
-	const registerTitle = useCallback( ( element: HTMLElement | null ) => {
-		titleElementRef.current = element;
-	}, [] );
-
-	const contextValue = useMemo(
-		() => ( { registerTitle } ),
-		[ registerTitle ]
-	);
-
-	// Validate that Dialog.Title is rendered with non-empty text content
-	useEffect( () => {
-		// useLayoutEffect in Title runs before this useEffect,
-		// so titleElementRef should already be set if Title is present
-		const titleElement = titleElementRef.current;
-
-		if ( ! titleElement ) {
-			throw new Error(
-				'Dialog: Missing <Dialog.Title>. ' +
-					'For accessibility, every dialog requires a title. ' +
-					'If needed, the title can be visually hidden but must not be omitted.'
-			);
-		}
-
-		const textContent = titleElement.textContent?.trim();
-		if ( ! textContent ) {
-			throw new Error(
-				'Dialog: <Dialog.Title> cannot be empty. ' +
-					'Provide meaningful text content for the dialog title.'
-			);
-		}
-	}, [] );
-
-	return (
-		<DialogValidationContext.Provider value={ contextValue }>
-			{ children }
-		</DialogValidationContext.Provider>
-	);
-}
-
-/**
- * Production no-op provider that just renders children.
- */
-function DialogValidationProviderProd( {
-	children,
-}: {
-	children: React.ReactNode;
-} ) {
-	return <>{ children }</>;
-}
+export const useDialogValidationContext =
+	dialogTitleValidation.useValidationContext;
 
 /**
  * Provider component that validates Dialog.Title presence in development mode.
  * In production, this component is a no-op and just renders children.
  */
-export const DialogValidationProvider = VALIDATION_ENABLED
-	? DialogValidationProviderDev
-	: DialogValidationProviderProd;
+export const DialogValidationProvider =
+	dialogTitleValidation.ValidationProvider;

package/src/dialog/description.tsx

@@ -0,0 +1,27 @@
+import { Dialog as _Dialog } from '@base-ui/react/dialog';
+import { forwardRef } from '@wordpress/element';
+import { Text } from '../text';
+import styles from './style.module.css';
+import type { DescriptionProps } from './types';
+
+/**
+ * Renders an optional paragraph that describes the dialog content.
+ *
+ * The rendered element is linked to the popup via `aria-describedby`.
+ */
+const Description = forwardRef< HTMLParagraphElement, DescriptionProps >(
+	function DialogDescription( { children, ...props }, ref ) {
+		return (
+			<Text
+				ref={ ref }
+				variant="body-md"
+				render={ <_Dialog.Description { ...props } /> }
+				className={ styles.description }
+			>
+				{ children }
+			</Text>
+		);
+	}
+);
+
+export { Description };

package/src/dialog/footer.tsx

@@ -7,15 +7,23 @@ import type { FooterProps } from './types';
 /**
  * Renders the footer section of the dialog, typically containing
  * action buttons.
+ *
+ * Defaults to a native `<footer>` element for richer semantics (contentinfo
+ * landmark navigation where screen readers expose landmarks nested in
+ * dialogs). Pass `render` to opt out of the default tag.
+ *
+ * The footer is pinned to the bottom of the popup by default. To let it
+ * scroll with the body instead, render it *inside* `Dialog.Content`.
  */
-const Footer = forwardRef< HTMLDivElement, FooterProps >( function DialogFooter(
+const Footer = forwardRef< HTMLElement, FooterProps >( function DialogFooter(
 	{ className, render, ...props },
 	ref
 ) {
 	const element = useRender( {
+		defaultTagName: 'footer',
 		render,
 		ref,
-		props: mergeProps< 'div' >( props, {
+		props: mergeProps< 'footer' >( props, {
 			className: clsx( styles.footer, className ),
 		} ),
 	} );

package/src/dialog/header.tsx

@@ -7,15 +7,23 @@ import type { HeaderProps } from './types';
 /**
  * Renders the header section of the dialog, typically containing
  * the heading and close button.
+ *
+ * Defaults to a native `<header>` element for richer semantics (heading-level
+ * scanning, and banner landmark navigation where screen readers expose
+ * landmarks nested in dialogs). Pass `render` to opt out of the default tag.
+ *
+ * The header is pinned to the top of the popup by default. To let it scroll
+ * with the body instead, render it *inside* `Dialog.Content`.
  */
-const Header = forwardRef< HTMLDivElement, HeaderProps >( function DialogHeader(
+const Header = forwardRef< HTMLElement, HeaderProps >( function DialogHeader(
 	{ className, render, ...props },
 	ref
 ) {
 	const element = useRender( {
+		defaultTagName: 'header',
 		render,
 		ref,
-		props: mergeProps< 'div' >( props, {
+		props: mergeProps< 'header' >( props, {
 			className: clsx( styles.header, className ),
 		} ),
 	} );

package/src/dialog/index.ts

@@ -1,10 +1,25 @@
 import { Action } from './action';
 import { CloseIcon } from './close-icon';
+import { Content } from './content';
+import { Description } from './description';
 import { Footer } from './footer';
 import { Header } from './header';
 import { Popup } from './popup';
+import { Portal } from './portal';
 import { Root } from './root';
 import { Title } from './title';
 import { Trigger } from './trigger';
 
-export { Action, CloseIcon, Footer, Header, Popup, Root, Title, Trigger };
+export {
+	Action,
+	CloseIcon,
+	Content,
+	Description,
+	Footer,
+	Header,
+	Popup,
+	Portal,
+	Root,
+	Title,
+	Trigger,
+};

package/src/dialog/popup.tsx

@@ -8,7 +8,10 @@ import {
 } from '@wordpress/theme';
 import { unlock } from '../lock-unlock';
 import { useDeprioritizedInitialFocus } from '../utils/use-deprioritized-initial-focus';
-import { DialogValidationProvider } from './context';
+import { SCROLL_CONTAINER_ATTR } from '../utils/use-overlay-scroll-state-attributes';
+import { renderPortalWithChildren } from '../utils/render-portal-with-children';
+import { DialogValidationProvider, useDialogModal } from './context';
+import { Portal } from './portal';
 import styles from './style.module.css';
 import type { PopupProps } from './types';
 
@@ -20,28 +23,42 @@ const CLOSE_ICON_ATTR = 'data-wp-ui-dialog-close-icon';
 /**
  * Renders the dialog popup element that contains the dialog content.
  * Uses a portal to render outside the DOM hierarchy.
+ *
+ * When `portal` is omitted, defaults to `Dialog.Portal`. Portal merging is
+ * handled by `renderPortalWithChildren` (shared with other overlay `Popup`s).
  */
 const Popup = forwardRef< HTMLDivElement, PopupProps >( function DialogPopup(
 	{
 		className,
-		container,
+		portal,
+		children,
 		size = 'medium',
 		initialFocus,
 		finalFocus,
-		children,
 		...props
 	},
 	ref
 ) {
 	const { resolvedInitialFocus, popupRef } = useDeprioritizedInitialFocus( {
 		initialFocus,
-		deprioritizedAttribute: CLOSE_ICON_ATTR,
+		deprioritizedAttributes: [ CLOSE_ICON_ATTR, SCROLL_CONTAINER_ATTR ],
 	} );
 	const mergedRef = useMergeRefs( [ ref, popupRef ] );
+	const modal = useDialogModal();
 
-	return (
-		<_Dialog.Portal container={ container }>
-			<_Dialog.Backdrop className={ styles.backdrop } />
+	const portalChildren = (
+		<>
+			{ /*
+			 * Only render a backdrop for fully modal dialogs. Non-modal dialogs
+			 * should not dim the page, and `trap-focus` keeps outside pointer
+			 * interactions enabled, so a backdrop would misrepresent that mode.
+			 */ }
+			{ modal === true && (
+				<_Dialog.Backdrop
+					className={ styles.backdrop }
+					data-testid="dialog-backdrop"
+				/>
+			) }
 			<ThemeProvider>
 				<_Dialog.Popup
 					ref={ mergedRef }
@@ -53,14 +70,17 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function DialogPopup(
 					initialFocus={ resolvedInitialFocus }
 					finalFocus={ finalFocus }
 					{ ...props }
+					data-wp-ui-overlay-modal={ modal === true ? '' : undefined }
 				>
 					<DialogValidationProvider>
 						{ children }
 					</DialogValidationProvider>
 				</_Dialog.Popup>
 			</ThemeProvider>
-		</_Dialog.Portal>
+		</>
 	);
+
+	return renderPortalWithChildren( portal, <Portal />, portalChildren );
 } );
 
 export { Popup };

package/src/dialog/portal.tsx

@@ -0,0 +1,18 @@
+import { Dialog as _Dialog } from '@base-ui/react/dialog';
+import { forwardRef } from '@wordpress/element';
+import type { PortalProps } from './types';
+
+/**
+ * Root element that portals `Dialog` overlay content (`Backdrop`, inner
+ * `Popup`, etc.) outside the DOM hierarchy. Pass to `Dialog.Popup`'s
+ * `portal` prop to customize `container`, `className`, `style`, and other
+ * Base UI portal options. When `portal` is omitted, `Dialog.Popup` uses this
+ * component with default props.
+ */
+const Portal = forwardRef< HTMLDivElement, PortalProps >(
+	function DialogPortal( props, ref ) {
+		return <_Dialog.Portal ref={ ref } { ...props } />;
+	}
+);
+
+export { Portal };

package/src/dialog/root.tsx

@@ -1,14 +1,31 @@
 import { Dialog as _Dialog } from '@base-ui/react/dialog';
+import { DialogModalProvider } from './context';
 import type { RootProps } from './types';
 
 /**
- * Groups the dialog trigger and popup.
+ * An ARIA-compliant dialog that opens on top of the entire page.
  *
- * `Dialog` is a collection of React components that combine to render
- * an ARIA-compliant dialog pattern.
+ * Every dialog must include a `Dialog.Title` component for accessibility — it
+ * serves as both the visible heading and the accessible label for the dialog.
+ *
+ * Always include a visible close button, either `Dialog.CloseIcon` or a clear
+ * dismissing action button. If your dialog has a "Cancel" button in the footer,
+ * the close icon may be redundant and create confusion about what clicking "X"
+ * means.
+ *
+ * Use `Dialog.CloseIcon` for informational dialogs where dismissing is safe and
+ * expected. For dialogs requiring explicit user choice (especially destructive
+ * actions), omit the close icon and rely on footer action buttons like "Cancel"
+ * and "Confirm" instead.
  */
-function Root( props: RootProps ) {
-	return <_Dialog.Root { ...props } />;
+function Root( { modal = true, children, ...props }: RootProps ) {
+	return (
+		<_Dialog.Root modal={ modal } { ...props }>
+			<DialogModalProvider modal={ modal }>
+				{ children }
+			</DialogModalProvider>
+		</_Dialog.Root>
+	);
 }
 
 export { Root };