@wordpress/ui 0.11.0 → 0.12.0

package/src/popover/test/index.test.tsx

@@ -1,8 +1,21 @@
-import { render, screen, waitFor } from '@testing-library/react';
+import { act, render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { Component, createRef, useState } from '@wordpress/element';
+import { createRef, useState } from '@wordpress/element';
 import * as Popover from '../index';
 
+function collectUncaughtErrors() {
+	const errors: Error[] = [];
+	const handler = ( event: ErrorEvent ) => {
+		event.preventDefault();
+		errors.push( event.error );
+	};
+	window.addEventListener( 'error', handler );
+	return {
+		errors,
+		cleanup: () => window.removeEventListener( 'error', handler ),
+	};
+}
+
 describe( 'Popover', () => {
 	describe( 'forwards ref', () => {
 		it( 'should forward ref on Trigger', () => {
@@ -376,6 +389,35 @@ describe( 'Popover', () => {
 				);
 			} );
 		} );
+
+		it( 'merges user `className` on Popover.Title with the internal one', async () => {
+			// Regression test for the shared `useRender` class-name merge
+			// that also covers Popover.Description and its Dialog/Drawer
+			// counterparts.
+			const user = userEvent.setup();
+
+			render(
+				<Popover.Root>
+					<Popover.Trigger>Open</Popover.Trigger>
+					<Popover.Popup>
+						<Popover.Title className="custom-title">
+							Title
+						</Popover.Title>
+					</Popover.Popup>
+				</Popover.Root>
+			);
+
+			await user.click( screen.getByRole( 'button', { name: 'Open' } ) );
+
+			const heading = await screen.findByRole( 'heading', {
+				name: 'Title',
+			} );
+			// The regression this guards against: `useRender` must still
+			// forward the user-supplied className to the underlying DOM node.
+			// CSS module classes are stubbed in the Jest environment, so we
+			// can only assert the user class end-to-end.
+			expect( heading ).toHaveClass( 'custom-title' );
+		} );
 	} );
 
 	describe( 'variant', () => {
@@ -421,7 +463,7 @@ describe( 'Popover', () => {
 		} );
 	} );
 
-	describe( 'inline (via container)', () => {
+	describe( 'inline via portal (custom container)', () => {
 		function InlinePopover() {
 			const containerRef = createRef< HTMLSpanElement >();
 			return (
@@ -432,7 +474,11 @@ describe( 'Popover', () => {
 							ref={ containerRef }
 							style={ { display: 'contents' } }
 						/>
-						<Popover.Popup container={ containerRef }>
+						<Popover.Popup
+							portal={
+								<Popover.Portal container={ containerRef } />
+							}
+						>
 							<Popover.Title>Title</Popover.Title>
 							Inline content
 						</Popover.Popup>
@@ -441,7 +487,7 @@ describe( 'Popover', () => {
 			);
 		}
 
-		it( 'should render inside the container when a local ref is used', async () => {
+		it( 'should render inside the portal container when a local ref is used', async () => {
 			const user = userEvent.setup();
 
 			render( <InlinePopover /> );
@@ -613,84 +659,87 @@ describe( 'Popover', () => {
 	} );
 
 	describe( 'title validation', () => {
+		// Suppress console.error from React act() warnings and jsdom
+		// unhandled-error logging. Validation errors are caught via
+		// collectUncaughtErrors (window 'error' event) instead.
+		let originalConsoleError: typeof console.error;
+
+		beforeEach( () => {
+			// eslint-disable-next-line no-console
+			originalConsoleError = console.error;
+			// eslint-disable-next-line no-console
+			console.error = jest.fn();
+		} );
+
+		afterEach( () => {
+			// eslint-disable-next-line no-console
+			console.error = originalConsoleError;
+		} );
+
 		it( 'should throw when Popover.Title is missing', async () => {
 			const user = userEvent.setup();
-			const onError = jest.fn();
-
-			// Suppress console.error from React error boundary
-			const spy = jest
-				.spyOn( console, 'error' )
-				.mockImplementation( () => {} );
+			const { errors, cleanup } = collectUncaughtErrors();
 
 			render(
-				<ErrorBoundary onError={ onError }>
-					<Popover.Root>
-						<Popover.Trigger>Open</Popover.Trigger>
-						<Popover.Popup>No title here</Popover.Popup>
-					</Popover.Root>
-				</ErrorBoundary>
+				<Popover.Root>
+					<Popover.Trigger>Open</Popover.Trigger>
+					<Popover.Popup>No title here</Popover.Popup>
+				</Popover.Root>
 			);
 
 			await user.click( screen.getByRole( 'button', { name: 'Open' } ) );
 
 			await waitFor( () => {
-				expect( onError ).toHaveBeenCalledWith(
-					expect.objectContaining( {
-						message: expect.stringContaining(
-							'Missing <Popover.Title>'
-						),
-					} )
-				);
+				expect( errors.length ).toBeGreaterThan( 0 );
 			} );
 
-			spy.mockRestore();
+			expect( errors[ 0 ].message ).toBe(
+				'Popover: Missing <Popover.Title>. ' +
+					'For accessibility, every popover requires a title. ' +
+					'If needed, the title can be visually hidden but must not be omitted.'
+			);
+
+			cleanup();
 		} );
 
 		it( 'should throw when Popover.Title is empty', async () => {
 			const user = userEvent.setup();
-			const onError = jest.fn();
-
-			const spy = jest
-				.spyOn( console, 'error' )
-				.mockImplementation( () => {} );
+			const { errors, cleanup } = collectUncaughtErrors();
 
 			render(
-				<ErrorBoundary onError={ onError }>
-					<Popover.Root>
-						<Popover.Trigger>Open</Popover.Trigger>
-						<Popover.Popup>
-							<Popover.Title />
-						</Popover.Popup>
-					</Popover.Root>
-				</ErrorBoundary>
+				<Popover.Root>
+					<Popover.Trigger>Open</Popover.Trigger>
+					<Popover.Popup>
+						<Popover.Title />
+					</Popover.Popup>
+				</Popover.Root>
 			);
 
 			await user.click( screen.getByRole( 'button', { name: 'Open' } ) );
 
 			await waitFor( () => {
-				expect( onError ).toHaveBeenCalledWith(
-					expect.objectContaining( {
-						message: expect.stringContaining( 'cannot be empty' ),
-					} )
-				);
+				expect( errors.length ).toBeGreaterThan( 0 );
 			} );
 
-			spy.mockRestore();
+			expect( errors[ 0 ].message ).toBe(
+				'Popover: <Popover.Title> cannot be empty. ' +
+					'Provide meaningful text content for the popover title.'
+			);
+
+			cleanup();
 		} );
 
 		it( 'should not throw when Popover.Title is present', async () => {
 			const user = userEvent.setup();
-			const onError = jest.fn();
+			const { errors, cleanup } = collectUncaughtErrors();
 
 			render(
-				<ErrorBoundary onError={ onError }>
-					<Popover.Root>
-						<Popover.Trigger>Open</Popover.Trigger>
-						<Popover.Popup>
-							<Popover.Title>Valid Title</Popover.Title>
-						</Popover.Popup>
-					</Popover.Root>
-				</ErrorBoundary>
+				<Popover.Root>
+					<Popover.Trigger>Open</Popover.Trigger>
+					<Popover.Popup>
+						<Popover.Title>Valid Title</Popover.Title>
+					</Popover.Popup>
+				</Popover.Root>
 			);
 
 			await user.click( screen.getByRole( 'button', { name: 'Open' } ) );
@@ -699,29 +748,95 @@ describe( 'Popover', () => {
 				expect( screen.getByText( 'Valid Title' ) ).toBeVisible();
 			} );
 
-			expect( onError ).not.toHaveBeenCalled();
+			await act(
+				() => new Promise( ( resolve ) => setTimeout( resolve, 50 ) )
+			);
+			expect( errors ).toHaveLength( 0 );
+
+			cleanup();
 		} );
-	} );
-} );
 
-class ErrorBoundary extends Component<
-	{ children: React.ReactNode; onError: ( error: Error ) => void },
-	{ hasError: boolean }
-> {
-	state = { hasError: false };
+		it( 'should throw when title is removed after mount', async () => {
+			const { errors, cleanup } = collectUncaughtErrors();
+
+			const ui = ( showTitle: boolean ) => (
+				<Popover.Root defaultOpen>
+					<Popover.Trigger>Open</Popover.Trigger>
+					<Popover.Popup>
+						{ showTitle && <Popover.Title>My Title</Popover.Title> }
+						<p>Content</p>
+					</Popover.Popup>
+				</Popover.Root>
+			);
+
+			const { rerender } = render( ui( true ) );
 
-	static getDerivedStateFromError() {
-		return { hasError: true };
-	}
+			// Wait for the popover to render.
+			await waitFor( () => {
+				expect( screen.getByText( 'Content' ) ).toBeInTheDocument();
+			} );
 
-	componentDidCatch( error: Error ) {
-		this.props.onError( error );
-	}
+			// Let initial validation settle — no errors expected.
+			await act(
+				() => new Promise( ( resolve ) => setTimeout( resolve, 50 ) )
+			);
+			expect( errors ).toHaveLength( 0 );
 
-	render() {
-		if ( this.state.hasError ) {
-			return null;
-		}
-		return this.props.children;
-	}
-}
+			// Remove the title via rerender.
+			rerender( ui( false ) );
+
+			await waitFor( () => {
+				expect( errors.length ).toBeGreaterThan( 0 );
+			} );
+
+			expect( errors[ 0 ].message ).toBe(
+				'Popover: Missing <Popover.Title>. ' +
+					'For accessibility, every popover requires a title. ' +
+					'If needed, the title can be visually hidden but must not be omitted.'
+			);
+
+			cleanup();
+		} );
+
+		it( 'should recover when title is added back', async () => {
+			const { errors, cleanup } = collectUncaughtErrors();
+
+			const ui = ( showTitle: boolean ) => (
+				<Popover.Root defaultOpen>
+					<Popover.Trigger>Open</Popover.Trigger>
+					<Popover.Popup>
+						{ showTitle && <Popover.Title>My Title</Popover.Title> }
+						<p>Content</p>
+					</Popover.Popup>
+				</Popover.Root>
+			);
+
+			const { rerender } = render( ui( false ) );
+
+			// Wait for the popover to render.
+			await waitFor( () => {
+				expect( screen.getByText( 'Content' ) ).toBeInTheDocument();
+			} );
+
+			// Initially no title — should error.
+			await waitFor( () => {
+				expect( errors.length ).toBeGreaterThan( 0 );
+			} );
+
+			const errorCountAfterInitial = errors.length;
+
+			// Add the title back via rerender.
+			rerender( ui( true ) );
+
+			// Wait for deferred validation to settle.
+			await act(
+				() => new Promise( ( resolve ) => setTimeout( resolve, 50 ) )
+			);
+
+			// No new errors should have been thrown.
+			expect( errors ).toHaveLength( errorCountAfterInitial );
+
+			cleanup();
+		} );
+	} );
+} );

package/src/popover/title.tsx

@@ -1,8 +1,9 @@
 import { Popover as _Popover } from '@base-ui/react/popover';
 import { useMergeRefs } from '@wordpress/compose';
-import { forwardRef, useLayoutEffect, useRef } from '@wordpress/element';
+import { forwardRef, useEffect, useRef } from '@wordpress/element';
 import { Text } from '../text';
 import { usePopoverValidationContext } from './context';
+import styles from './style.module.css';
 import type { TitleProps } from './types';
 
 /**
@@ -22,13 +23,16 @@ import type { TitleProps } from './types';
  * ```
  */
 const Title = forwardRef< HTMLHeadingElement, TitleProps >(
-	function PopoverTitle( { className, children, ...props }, forwardedRef ) {
+	function PopoverTitle( { children, ...props }, forwardedRef ) {
 		const validationContext = usePopoverValidationContext();
 		const internalRef = useRef< HTMLHeadingElement >( null );
 		const mergedRef = useMergeRefs( [ internalRef, forwardedRef ] );
 
-		useLayoutEffect( () => {
-			validationContext?.registerTitle( internalRef.current );
+		useEffect( () => {
+			if ( validationContext ) {
+				return validationContext.registerTitle( internalRef.current );
+			}
+			return undefined;
 		}, [ validationContext ] );
 
 		return (
@@ -36,7 +40,7 @@ const Title = forwardRef< HTMLHeadingElement, TitleProps >(
 				ref={ mergedRef }
 				variant="heading-xl"
 				render={ <_Popover.Title { ...props } /> }
-				className={ className }
+				className={ styles.title }
 			>
 				{ children }
 			</Text>

package/src/popover/types.ts

@@ -1,7 +1,10 @@
-import type { ReactNode } from 'react';
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
 import type { Popover as _Popover } from '@base-ui/react/popover';
+
 import type { ComponentProps } from '../utils/types';
 
+export type PortalProps = ComponentPropsWithoutRef< typeof _Popover.Portal >;
+
 export interface RootProps
 	extends Pick<
 		_Popover.Root.Props,
@@ -22,16 +25,6 @@ export interface TriggerProps
 	children?: ReactNode;
 }
 
-/**
- * `Popover.Popup` maps to two Base UI elements internally: the
- * **Positioner** (outer, handles fixed positioning and z-index) and the
- * **Popup** (inner, holds content and visual styles).
- *
- * `style` and `className` are forwarded to the **Positioner** so that
- * z-index overrides (`--wp-ui-popover-z-index`) and Base UI CSS variables
- * (`--available-height`, `--available-width`) work correctly. All other
- * HTML attributes are forwarded to the inner **Popup** element.
- */
 export interface PopupProps
 	extends ComponentProps< 'div' >,
 		Pick<
@@ -64,12 +57,14 @@ export interface PopupProps
 	children?: ReactNode;
 
 	/**
-	 * A parent element to render the portal into.
+	 * Optional portal element, typically `<Popover.Portal />` with custom
+	 * `container` for cross-document rendering. Floating content is rendered
+	 * as this portal's children (do not pass `children` on the portal element;
+	 * they would be ignored).
 	 *
-	 * Useful for cross-document rendering, such as rendering a popover
-	 * in a parent document when the trigger is inside an iframe.
+	 * When omitted, `Popover.Popup` uses `Popover.Portal` with default props.
 	 */
-	container?: _Popover.Portal.Props[ 'container' ];
+	portal?: ReactElement< Omit< PortalProps, 'children' > >;
 
 	/**
 	 * The visual style variant of the popup.

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

@@ -2,6 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Stack } from '../index';
 
 const meta: Meta< typeof Stack > = {
+	tags: [ 'manifest' ],
 	title: 'Design System/Components/Stack',
 	component: Stack,
 };

package/src/tabs/context.tsx

@@ -2,10 +2,11 @@ import {
 	createContext,
 	useContext,
 	useCallback,
+	useEffect,
 	useMemo,
 	useRef,
-	useEffect,
 } from '@wordpress/element';
+import { useScheduleValidation } from '../utils/use-schedule-validation';
 
 type TabsValidationContextType = {
 	registerTab: () => () => void;
@@ -77,33 +78,20 @@ function TabsValidationProviderDev( {
 } ) {
 	const tabCountRef = useRef( 0 );
 	const panelCountRef = useRef( 0 );
-	const validationScheduledRef = useRef< ReturnType<
-		typeof setTimeout
-	> | null >( null );
 
-	const scheduleValidation = useCallback( () => {
-		if ( validationScheduledRef.current ) {
-			clearTimeout( validationScheduledRef.current );
+	const scheduleValidation = useScheduleValidation( () => {
+		const tabCount = tabCountRef.current;
+		const panelCount = panelCountRef.current;
+
+		if ( tabCount !== panelCount ) {
+			throw new Error(
+				`Tabs: Tab/Panel count mismatch (${ tabCount } Tabs, ${ panelCount } Panels). ` +
+					`Each Tab must be associated with exactly one Panel. ` +
+					`Mismatched or missing associations can break screen reader navigation ` +
+					`and violate WAI-ARIA Tabs pattern requirements.`
+			);
 		}
-
-		// Schedule validation for the next tick to allow all
-		// registrations/unregistrations to complete.
-		validationScheduledRef.current = setTimeout( () => {
-			const tabCount = tabCountRef.current;
-			const panelCount = panelCountRef.current;
-
-			if ( tabCount !== panelCount ) {
-				throw new Error(
-					`Tabs: Tab/Panel count mismatch (${ tabCount } Tabs, ${ panelCount } Panels). ` +
-						`Each Tab must be associated with exactly one Panel. ` +
-						`Mismatched or missing associations can break screen reader navigation ` +
-						`and violate WAI-ARIA Tabs pattern requirements.`
-				);
-			}
-
-			validationScheduledRef.current = null;
-		}, 0 );
-	}, [] );
+	} );
 
 	const registerTab = useCallback( () => {
 		tabCountRef.current += 1;
@@ -125,14 +113,6 @@ function TabsValidationProviderDev( {
 		};
 	}, [ scheduleValidation ] );
 
-	useEffect( () => {
-		return () => {
-			if ( validationScheduledRef.current ) {
-				clearTimeout( validationScheduledRef.current );
-			}
-		};
-	}, [] );
-
 	const contextValue = useMemo(
 		() => ( {
 			registerTab,

package/src/tabs/panel.tsx

@@ -2,7 +2,8 @@ import { forwardRef } from '@wordpress/element';
 import clsx from 'clsx';
 import { Tabs as _Tabs } from '@base-ui/react/tabs';
 import { useRegisterPanel } from './context';
-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 type { TabPanelProps } from './types';
 
 /**
@@ -18,7 +19,11 @@ export const Panel = forwardRef< HTMLDivElement, TabPanelProps >(
 		return (
 			<_Tabs.Panel
 				ref={ forwardedRef }
-				className={ clsx( styles.tabpanel, className ) }
+				className={ clsx(
+					defenseStyles.div,
+					focusStyles[ 'outset-ring--focus-visible' ],
+					className
+				) }
 				{ ...otherProps }
 			/>
 		);

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

@@ -1,7 +1,8 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState, cloneElement } from '@wordpress/element';
 import { link, more, wordpress } from '@wordpress/icons';
-import { Tabs, Tooltip } from '../..';
+import * as Tabs from '../';
+import * as Tooltip from '../../tooltip';
 
 const meta: Meta< typeof Tabs.Root > = {
 	title: 'Design System/Components/Tabs',

package/src/tabs/style.module.css

@@ -249,21 +249,4 @@
 			rotate: 180deg;
 		}
 	}
-
-	.tabpanel {
-		&:focus {
-			box-shadow: none;
-			outline: none;
-		}
-
-		&:focus-visible {
-			box-shadow:
-				0 0 0 var(--wpds-border-width-focus)
-				var(--wpds-color-stroke-focus-brand);
-
-			/* Windows high contrast mode. */
-			outline: 2px solid transparent;
-			outline-offset: 0;
-		}
-	}
 }

package/src/tabs/test/index.test.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable jest/no-conditional-expect */
-import { render, screen, waitFor } from '@testing-library/react';
+import { act, render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { DirectionProvider } from '@base-ui/react/direction-provider';
 import { useEffect, useState, createRef } from '@wordpress/element';
@@ -2344,7 +2344,9 @@ describe( 'Tabs', () => {
 			await waitForComponentToBeInitializedWithSelectedTab( 'One' );
 
 			// Wait a bit to ensure validation has run
-			await new Promise( ( resolve ) => setTimeout( resolve, 50 ) );
+			await act(
+				() => new Promise( ( resolve ) => setTimeout( resolve, 50 ) )
+			);
 
 			expect( errors ).toHaveLength( 0 );
 
@@ -2391,7 +2393,9 @@ describe( 'Tabs', () => {
 			await waitForComponentToBeInitializedWithSelectedTab( 'One' );
 
 			// Wait for validation
-			await new Promise( ( resolve ) => setTimeout( resolve, 50 ) );
+			await act(
+				() => new Promise( ( resolve ) => setTimeout( resolve, 50 ) )
+			);
 
 			// No errors since counts match
 			expect( errors ).toHaveLength( 0 );

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

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

package/src/text/text.tsx

@@ -20,8 +20,8 @@ export const Text = forwardRef< HTMLSpanElement, TextProps >( function Text(
 		props: mergeProps< 'span' >( props, {
 			className: clsx(
 				styles.text,
-				variant.startsWith( 'heading-' ) && defenseStyles.heading,
-				variant.startsWith( 'body-' ) && defenseStyles.p,
+				defenseStyles.heading,
+				defenseStyles.p,
 				styles[ variant ],
 				className
 			),

package/src/tooltip/index.ts

@@ -1,6 +1,7 @@
 import { Popup } from './popup';
+import { Portal } from './portal';
 import { Trigger } from './trigger';
 import { Root } from './root';
 import { Provider } from './provider';
 
-export { Provider, Root, Trigger, Popup };
+export { Provider, Root, Trigger, Popup, Portal };