@wordpress/ui 0.11.1-next.v.202604091042.0 → 0.12.0

package/src/button/style.module.css

@@ -20,7 +20,7 @@
 		--wp-ui-button-padding-inline: var(--wpds-dimension-padding-md);
 		--wp-ui-button-height: 40px;
 		--wp-ui-button-aspect-ratio: auto; /* Useful for overrides such as icon buttons */
-		--wp-ui-button-font-size: var(--wpds-font-size-md);
+		--wp-ui-button-font-size: var(--wpds-typography-font-size-md);
 		--wp-ui-button-min-width: calc(4ch + 2 * var(--wp-ui-button-padding-inline));
 
 		/* by default, borders have the same color as the background */
@@ -28,7 +28,7 @@
 		--wp-ui-button-border-color-active: var(--wp-ui-button-background-color-active);
 		--wp-ui-button-border-color-disabled: var(--wp-ui-button-background-color-disabled);
 
-		--_gcd-button-font-family: var(--wpds-font-family-body);
+		--_gcd-button-font-family: var(--wpds-typography-font-family-body);
 		--_gcd-button-font-size: var(--wp-ui-button-font-size);
 		--_gcd-button-font-weight: var(--wp-ui-button-font-weight);
 
@@ -48,10 +48,10 @@
 		border-radius: var(--wpds-border-radius-sm);
 		background-color: var(--wp-ui-button-background-color);
 		background-clip: padding-box;
-		font-family: var(--wpds-font-family-body);
+		font-family: var(--wpds-typography-font-family-body);
 		font-size: var(--wp-ui-button-font-size);
 		font-weight: var(--wp-ui-button-font-weight);
-		line-height: var(--wpds-font-line-height-sm);
+		line-height: var(--wpds-typography-line-height-sm);
 		text-decoration: none;
 		color: var(--wp-ui-button-foreground-color);
 		cursor: var(--wpds-cursor-control);

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

@@ -10,10 +10,10 @@ function Text( { children }: { children: React.ReactNode } ) {
 		<p
 			style={ {
 				margin: 0,
-				fontFamily: 'var(--wpds-font-family-body)',
-				fontSize: 'var(--wpds-font-size-md)',
-				fontWeight: 'var(--wpds-font-weight-regular)',
-				lineHeight: 'var(--wpds-font-line-height-sm)',
+				fontFamily: 'var(--wpds-typography-font-family-body)',
+				fontSize: 'var(--wpds-typography-font-size-md)',
+				fontWeight: 'var(--wpds-typography-font-weight-regular)',
+				lineHeight: 'var(--wpds-typography-line-height-sm)',
 				textWrap: 'pretty',
 				color: 'var(--wpds-color-fg-content-neutral-weak)',
 			} }
@@ -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/card/style.module.css

@@ -38,8 +38,4 @@
 		margin-inline: calc(-1 * var(--wp-ui-card-padding));
 		width: calc(100% + 2 * var(--wp-ui-card-padding));
 	}
-
-	.title {
-		margin: 0;
-	}
 }

package/src/card/test/index.test.tsx

@@ -91,5 +91,22 @@ describe( 'Card', () => {
 				screen.getByRole( 'heading', { level: 2, name: 'Heading' } )
 			).toBeVisible();
 		} );
+
+		it( 'forwards ref to custom Title render element', () => {
+			const titleRef = createRef< HTMLHeadingElement >();
+
+			render(
+				<Card.Root>
+					<Card.Header>
+						<Card.Title ref={ titleRef } render={ <h3 /> }>
+							Heading
+						</Card.Title>
+					</Card.Header>
+				</Card.Root>
+			);
+
+			expect( titleRef.current ).toBeInstanceOf( HTMLHeadingElement );
+			expect( titleRef.current?.tagName ).toBe( 'H3' );
+		} );
 	} );
 } );

package/src/card/title.tsx

@@ -1,20 +1,21 @@
 import { forwardRef } from '@wordpress/element';
-import clsx from 'clsx';
 import { Text } from '../text';
-import styles from './style.module.css';
 import type { TitleProps } from './types';
 
+const DEFAULT_TAG = <div />;
+
 /**
  * The title for a card. Renders as a `<div>` by default — use the `render`
  * prop to swap in a semantic heading element when appropriate.
  */
 export const Title = forwardRef< HTMLDivElement, TitleProps >(
-	function CardTitle( { className, render, children, ...props }, ref ) {
+	function CardTitle( { render = DEFAULT_TAG, children, ...props }, ref ) {
 		return (
 			<Text
+				ref={ ref }
 				variant="heading-lg"
-				render={ render ?? <div ref={ ref } { ...props } /> }
-				className={ clsx( styles.title, className ) }
+				render={ render }
+				{ ...props }
 			>
 				{ children }
 			</Text>

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

@@ -12,10 +12,10 @@ function Text( { children }: { children: React.ReactNode } ) {
 		<p
 			style={ {
 				margin: 0,
-				fontFamily: 'var(--wpds-font-family-body)',
-				fontSize: 'var(--wpds-font-size-md)',
-				fontWeight: 'var(--wpds-font-weight-regular)',
-				lineHeight: 'var(--wpds-font-line-height-sm)',
+				fontFamily: 'var(--wpds-typography-font-family-body)',
+				fontSize: 'var(--wpds-typography-font-size-md)',
+				fontWeight: 'var(--wpds-typography-font-weight-regular)',
+				lineHeight: 'var(--wpds-typography-line-height-sm)',
 				textWrap: 'pretty',
 				color: 'var(--wpds-color-fg-content-neutral-weak)',
 			} }
@@ -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: {
@@ -183,7 +184,7 @@ export const WithHeaderDescription: Story = {
 					<CollapsibleCard.HeaderDescription>
 						<span
 							style={ {
-								fontSize: 'var(--wpds-font-size-sm)',
+								fontSize: 'var(--wpds-typography-font-size-sm)',
 								color: 'var(--wpds-color-fg-content-neutral-weak)',
 							} }
 						>

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,27 +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,
+		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>
-			<_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 }
@@ -52,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 };