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

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: {
@@ -33,6 +34,12 @@ const meta: Meta< typeof CollapsibleCard.Root > = {
 		'CollapsibleCard.HeaderDescription': CollapsibleCard.HeaderDescription,
 		'CollapsibleCard.Content': CollapsibleCard.Content,
 	},
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 
@@ -158,6 +165,61 @@ export const Stacked: Story = {
 	),
 };
 
+/**
+ * `CollapsibleCard.Header` renders a `<div>` wrapper by default. Pass an
+ * `<h1>`–`<h6>` React element to the `render` prop to wrap the trigger in
+ * a heading and contribute to the document outline. The right level
+ * depends on the surrounding outline, so the consumer is expected to opt
+ * in.
+ */
+export const WithHeadingElement: Story = {
+	parameters: { controls: { disable: true } },
+	render: () => (
+		<div
+			style={ {
+				display: 'flex',
+				flexDirection: 'column',
+				gap: 'var(--wpds-dimension-gap-lg)',
+			} }
+		>
+			<CollapsibleCard.Root>
+				<CollapsibleCard.Header render={ <h2 /> }>
+					<Card.Title>Heading level 2</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>
+						The wrapper renders as an h2 element when the consumer
+						passes an h2 React element to the render prop.
+					</Text>
+				</CollapsibleCard.Content>
+			</CollapsibleCard.Root>
+			<CollapsibleCard.Root>
+				<CollapsibleCard.Header render={ <h3 /> }>
+					<Card.Title>Heading level 3</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>
+						Pass any of h1–h6 to choose the level that fits the
+						surrounding document outline.
+					</Text>
+				</CollapsibleCard.Content>
+			</CollapsibleCard.Root>
+			<CollapsibleCard.Root>
+				<CollapsibleCard.Header>
+					<Card.Title>No heading (default)</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>
+						Without a render prop, the header wraps the trigger in a
+						plain div and does not contribute to the document
+						outline.
+					</Text>
+				</CollapsibleCard.Content>
+			</CollapsibleCard.Root>
+		</div>
+	),
+};
+
 /**
  * A collapsible card with a `HeaderDescription` that provides supplementary
  * information (e.g. status, summary) as an `aria-describedby` relationship.

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

@@ -1,6 +1,26 @@
 @layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
 
 @layer wp-ui-components {
+	/*
+	 * Style overrides for the outer wrapper rendered by `CollapsibleCard.Header`
+	 * (defaults to `<div>`, but consumers can opt into a heading level via
+	 * `render={ <h2 /> }` etc.). Combined with `defenseStyles.heading` so that,
+	 * when the wrapper renders as an h1–h6, the unlayered defense class beats
+	 * wp-admin's bare `h2`/`h3`/etc. selectors. Keeps the wrapper visually
+	 * transparent so UA and host stylesheets don't bleed into the inner
+	 * trigger.
+	 */
+	.heading-wrapper {
+		--_gcd-heading-color: inherit;
+		--_gcd-heading-font-size: inherit;
+		--_gcd-heading-font-weight: inherit;
+		--_gcd-heading-margin: 0;
+
+		/* Properties not covered by the defense file. */
+		font-family: inherit;
+		line-height: inherit;
+	}
+
 	.header-content {
 		flex: 1;
 		min-width: 0;
@@ -28,7 +48,7 @@
 	}
 
 	.header-trigger {
-		@media not (prefers-reduced-motion) {
+		@media not ( prefers-reduced-motion ) {
 			transition: rotate 0.15s ease-out;
 		}
 	}
@@ -44,9 +64,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 +85,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/collapsible-card/test/index.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { render, screen, within } from '@testing-library/react';
 import { userEvent } from '@testing-library/user-event';
 import { createRef } from '@wordpress/element';
 import * as Card from '../../card';
@@ -179,6 +179,65 @@ describe( 'CollapsibleCard', () => {
 		} );
 	} );
 
+	describe( 'header wrapper', () => {
+		it( 'does not contribute a heading to the document outline by default', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			expect(
+				screen.queryByRole( 'heading', { name: 'Title' } )
+			).not.toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', { name: 'Title' } )
+			).toBeVisible();
+		} );
+
+		it( 'wraps the trigger in a heading via `render`', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header render={ <h2 /> }>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			const heading = screen.getByRole( 'heading', {
+				level: 2,
+				name: 'Title',
+			} );
+			expect( heading ).toBeVisible();
+			expect(
+				within( heading ).getByRole( 'button', { name: 'Title' } )
+			).toBeVisible();
+		} );
+
+		it( 'forwards `className` and other props to the outer wrapper', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header
+						className="custom-header"
+						data-testid="header"
+					>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			const wrapper = screen.getByTestId( 'header' );
+			expect( wrapper ).toHaveClass( 'custom-header' );
+			// The forwarded attributes land on the outer wrapper, not the
+			// inner button trigger.
+			expect(
+				within( wrapper ).getByRole( 'button', { name: 'Title' } )
+			).not.toHaveAttribute( 'data-testid' );
+		} );
+	} );
+
 	describe( 'HeaderDescription', () => {
 		it( 'sets aria-describedby on the trigger pointing to the description', () => {
 			render(

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,126 +1,29 @@
-import {
-	createContext,
-	useCallback,
-	useContext,
-	useEffect,
-	useMemo,
-	useRef,
-} from '@wordpress/element';
-import { useScheduleValidation } from '../utils/use-schedule-validation';
+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 scheduleValidation = useScheduleValidation( () => {
-		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.'
-			);
-		}
-	} );
-
-	const registerTitle = useCallback(
-		( element: HTMLElement | null ) => {
-			titleElementRef.current = element;
-			scheduleValidation();
-
-			return () => {
-				titleElementRef.current = null;
-				scheduleValidation();
-			};
-		},
-		[ scheduleValidation ]
-	);
-
-	// Schedule an initial validation on mount to catch missing titles
-	// (when no Title component is rendered, registerTitle is never called).
-	useEffect( () => {
-		scheduleValidation();
-	}, [ scheduleValidation ] );
-
-	const contextValue = useMemo(
-		() => ( { registerTitle } ),
-		[ registerTitle ]
-	);
-
-	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 { renderSlotWithChildren } from '../utils/render-slot-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,41 @@ 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`.
  */
 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 +69,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 renderSlotWithChildren( 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 };