@wordpress/ui 0.9.1-next.v.202603161435.0 → 0.11.0

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

@@ -203,10 +203,8 @@ describe( 'Dialog', () => {
 						<Dialog.Trigger>Open Dialog</Dialog.Trigger>
 						<Dialog.Popup>
 							<Dialog.Header>
-								{ /* @ts-expect-error this is just for test purposes */ }
-								<Dialog.Title>
-									{ /* Empty title */ }
-								</Dialog.Title>
+								{ /* Empty title */ }
+								<Dialog.Title />
 							</Dialog.Header>
 							<p>Content with empty title</p>
 							<Dialog.Footer>
@@ -306,4 +304,182 @@ describe( 'Dialog', () => {
 			expect( onError ).not.toHaveBeenCalled();
 		} );
 	} );
+
+	describe( 'Initial focus', () => {
+		it( 'should focus the first content element, skipping the close icon', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<Dialog.Root>
+					<Dialog.Trigger>Open Dialog</Dialog.Trigger>
+					<Dialog.Popup>
+						<Dialog.Header>
+							<Dialog.Title>My Title</Dialog.Title>
+							<Dialog.CloseIcon />
+						</Dialog.Header>
+						<button>Content Button</button>
+					</Dialog.Popup>
+				</Dialog.Root>
+			);
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Open Dialog' } )
+			);
+
+			await waitFor( () => {
+				expect(
+					screen.getByRole( 'button', { name: 'Content Button' } )
+				).toHaveFocus();
+			} );
+		} );
+
+		it( 'should fall back to the close icon when it is the only tabbable element', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<Dialog.Root>
+					<Dialog.Trigger>Open Dialog</Dialog.Trigger>
+					<Dialog.Popup>
+						<Dialog.Header>
+							<Dialog.Title>My Title</Dialog.Title>
+							<Dialog.CloseIcon />
+						</Dialog.Header>
+						<p>No tabbable content here</p>
+					</Dialog.Popup>
+				</Dialog.Root>
+			);
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Open Dialog' } )
+			);
+
+			await waitFor( () => {
+				expect(
+					screen.getByRole( 'button', { name: 'Close' } )
+				).toHaveFocus();
+			} );
+		} );
+
+		it( 'should not move focus when initialFocus is false', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<Dialog.Root>
+					<Dialog.Trigger>Open Dialog</Dialog.Trigger>
+					<Dialog.Popup initialFocus={ false }>
+						<Dialog.Header>
+							<Dialog.Title>My Title</Dialog.Title>
+							<Dialog.CloseIcon />
+						</Dialog.Header>
+						<button>Content Button</button>
+					</Dialog.Popup>
+				</Dialog.Root>
+			);
+
+			const trigger = screen.getByRole( 'button', {
+				name: 'Open Dialog',
+			} );
+			await user.click( trigger );
+
+			await waitFor( () => {
+				expect( screen.getByRole( 'dialog' ) ).toBeInTheDocument();
+			} );
+
+			expect(
+				screen.getByRole( 'button', { name: 'Content Button' } )
+			).not.toHaveFocus();
+			expect(
+				screen.getByRole( 'button', { name: 'Close' } )
+			).not.toHaveFocus();
+		} );
+
+		it( 'should use a custom initialFocus callback as-is', async () => {
+			const user = userEvent.setup();
+			const customFocus = jest.fn( () => false as const );
+
+			render(
+				<Dialog.Root>
+					<Dialog.Trigger>Open Dialog</Dialog.Trigger>
+					<Dialog.Popup initialFocus={ customFocus }>
+						<Dialog.Header>
+							<Dialog.Title>My Title</Dialog.Title>
+							<Dialog.CloseIcon />
+						</Dialog.Header>
+						<button>Content Button</button>
+					</Dialog.Popup>
+				</Dialog.Root>
+			);
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Open Dialog' } )
+			);
+
+			await waitFor( () => {
+				expect( screen.getByRole( 'dialog' ) ).toBeInTheDocument();
+			} );
+
+			expect( customFocus ).toHaveBeenCalled();
+		} );
+	} );
+
+	describe( 'container', () => {
+		it( 'should render inside the container when provided', async () => {
+			const user = userEvent.setup();
+			const containerRef = createRef< HTMLDivElement >();
+
+			render(
+				<div data-testid="wrapper">
+					<Dialog.Root>
+						<Dialog.Trigger>Open</Dialog.Trigger>
+						<div
+							ref={ containerRef }
+							data-testid="custom-container"
+						/>
+						<Dialog.Popup container={ containerRef }>
+							<Dialog.Header>
+								<Dialog.Title>Title</Dialog.Title>
+							</Dialog.Header>
+							Dialog content
+						</Dialog.Popup>
+					</Dialog.Root>
+				</div>
+			);
+
+			await user.click( screen.getByRole( 'button', { name: 'Open' } ) );
+
+			const content = await screen.findByText( 'Dialog content' );
+			expect( content ).toBeVisible();
+
+			expect( screen.getByTestId( 'custom-container' ) ).toContainElement(
+				content
+			);
+		} );
+
+		it( 'should render with a portal by default', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<div data-testid="wrapper">
+					<Dialog.Root>
+						<Dialog.Trigger>Open</Dialog.Trigger>
+						<Dialog.Popup>
+							<Dialog.Header>
+								<Dialog.Title>Title</Dialog.Title>
+							</Dialog.Header>
+							Portal content
+						</Dialog.Popup>
+					</Dialog.Root>
+				</div>
+			);
+
+			await user.click( screen.getByRole( 'button', { name: 'Open' } ) );
+
+			const content = await screen.findByText( 'Portal content' );
+			expect( content ).toBeVisible();
+
+			expect( screen.getByTestId( 'wrapper' ) ).not.toContainElement(
+				content
+			);
+		} );
+	} );
 } );

package/src/dialog/title.tsx

@@ -1,7 +1,7 @@
 import { Dialog as _Dialog } from '@base-ui/react/dialog';
-import clsx from 'clsx';
 import { useMergeRefs } from '@wordpress/compose';
 import { forwardRef, useLayoutEffect, useRef } from '@wordpress/element';
+import { Text } from '../text';
 import { useDialogValidationContext } from './context';
 import styles from './style.module.css';
 import type { TitleProps } from './types';
@@ -11,11 +11,21 @@ import type { TitleProps } from './types';
  * and serves as both the visible heading and the accessible label for
  * the dialog.
  *
- * Base UI's Dialog.Title renders an `<h2>` by default. Use the `render` prop
- * to customize the element if needed.
+ * **Required** — every dialog must include a `Dialog.Title`, even if
+ * visually hidden. The rendered element is linked to the popup via
+ * `aria-labelledby`. Renders an `<h2>` by default.
+ *
+ * To visually hide the title while keeping it accessible, wrap it with
+ * `VisuallyHidden` using the `render` prop:
+ *
+ * ```jsx
+ * <VisuallyHidden render={ <Dialog.Title /> }>
+ *   Accessible title text
+ * </VisuallyHidden>
+ * ```
  */
 const Title = forwardRef< HTMLHeadingElement, TitleProps >(
-	function DialogTitle( { className, render, ...props }, forwardedRef ) {
+	function DialogTitle( { children, ...props }, forwardedRef ) {
 		const validationContext = useDialogValidationContext();
 		const internalRef = useRef< HTMLHeadingElement >( null );
 		const mergedRef = useMergeRefs( [ internalRef, forwardedRef ] );
@@ -26,12 +36,14 @@ const Title = forwardRef< HTMLHeadingElement, TitleProps >(
 		}, [ validationContext ] );
 
 		return (
-			<_Dialog.Title
+			<Text
 				ref={ mergedRef }
-				className={ clsx( styles.title, className ) }
-				render={ render }
-				{ ...props }
-			/>
+				variant="heading-xl"
+				render={ <_Dialog.Title { ...props } /> }
+				className={ styles.title }
+			>
+				{ children }
+			</Text>
 		);
 	}
 );

package/src/dialog/types.ts

@@ -7,7 +7,11 @@ import type { ComponentProps } from '../utils/types';
 export interface RootProps
 	extends Pick<
 		_Dialog.Root.Props,
-		'open' | 'onOpenChange' | 'defaultOpen' | 'modal'
+		| 'open'
+		| 'onOpenChange'
+		| 'defaultOpen'
+		| 'modal'
+		| 'disablePointerDismissal'
 	> {
 	/**
 	 * The content to be rendered inside the component.
@@ -22,19 +26,26 @@ export interface TriggerProps extends ComponentProps< 'button' > {
 	children?: ReactNode;
 }
 
-export interface PopupProps extends ComponentProps< 'div' > {
+export interface PopupProps
+	extends ComponentProps< 'div' >,
+		Pick< _Dialog.Popup.Props, 'initialFocus' | 'finalFocus' > {
 	/**
 	 * The content to be rendered inside the component.
 	 */
 	children?: ReactNode;
 
+	/**
+	 * A parent element to render the portal into.
+	 */
+	container?: _Dialog.Portal.Props[ 'container' ];
+
 	/**
 	 * Renders the dialog at a preset width (excluding additional padding from
 	 * the viewport edges).
 	 *
-	 * - `'small'` — max-width of 384px.
-	 * - `'medium'` — max-width of 512px.
-	 * - `'large'` — max-width of 840px.
+	 * - `'small'` — narrow max-width.
+	 * - `'medium'` — moderate max-width.
+	 * - `'large'` — wide max-width.
 	 * - `'stretch'` — no max-width, stretches to fill available space.
 	 * - `'full'` — stretches to fill available width and height.
 	 *
@@ -68,8 +79,11 @@ export interface TitleProps extends ComponentProps< 'h2' > {
 	/**
 	 * The title content to be rendered. This serves as both the visible
 	 * heading and the accessible label for the dialog.
+	 *
+	 * When `Dialog.Title` is passed as a render element (e.g. to
+	 * `VisuallyHidden`), children can be provided by the wrapper instead.
 	 */
-	children: ReactNode;
+	children?: ReactNode;
 }
 
 export interface CloseIconProps

package/src/empty-state/actions.tsx

@@ -0,0 +1,24 @@
+import { useRender, mergeProps } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import type { EmptyStateActionsProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * A container for action buttons in an empty state. Actions are optional, and
+ * can include a primary and optional secondary action button.
+ */
+export const Actions = forwardRef< HTMLDivElement, EmptyStateActionsProps >(
+	function EmptyStateActions( { render, ...props }, ref ) {
+		const className = clsx( styles.actions );
+
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >( { className }, props ),
+		} );
+
+		return element;
+	}
+);

package/src/empty-state/description.tsx

@@ -0,0 +1,31 @@
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { Text } from '../text';
+import type { EmptyStateDescriptionProps } from './types';
+import styles from './style.module.css';
+
+const DEFAULT_TAG = <p />;
+
+/**
+ * The description text for an empty state, providing additional context and
+ * guidance on what the user should do next.
+ */
+export const Description = forwardRef<
+	HTMLParagraphElement,
+	EmptyStateDescriptionProps
+>( function EmptyStateDescription(
+	{ render = DEFAULT_TAG, className, children, ...props },
+	ref
+) {
+	return (
+		<Text
+			ref={ ref }
+			variant="body-md"
+			render={ render }
+			className={ clsx( styles.description, className ) }
+			{ ...props }
+		>
+			{ children }
+		</Text>
+	);
+} );

package/src/empty-state/icon.tsx

@@ -0,0 +1,24 @@
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { Icon as _Icon } from '../icon';
+import { Visual } from './visual';
+import type { EmptyStateIconProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * An icon visual for empty states. Renders an icon with styling treatment for
+ * empty states.
+ */
+export const Icon = forwardRef< HTMLDivElement, EmptyStateIconProps >(
+	function EmptyStateIcon( { icon, className, ...restProps }, ref ) {
+		return (
+			<Visual
+				ref={ ref }
+				className={ clsx( styles.icon, className ) }
+				{ ...restProps }
+			>
+				<_Icon icon={ icon } />
+			</Visual>
+		);
+	}
+);

package/src/empty-state/index.ts

@@ -0,0 +1,8 @@
+import { Root } from './root';
+import { Visual } from './visual';
+import { Icon } from './icon';
+import { Title } from './title';
+import { Description } from './description';
+import { Actions } from './actions';
+
+export { Root, Visual, Icon, Title, Description, Actions };

package/src/empty-state/root.tsx

@@ -0,0 +1,23 @@
+import { useRender, mergeProps } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import type { EmptyStateRootProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * The root container for an empty state component.
+ */
+export const Root = forwardRef< HTMLDivElement, EmptyStateRootProps >(
+	function EmptyStateRoot( { render, ...props }, ref ) {
+		const className = clsx( styles.root );
+
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >( { className }, props ),
+		} );
+
+		return element;
+	}
+);

package/src/empty-state/stories/index.story.tsx

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { search } from '@wordpress/icons';
+import { Button, EmptyState } from '../..';
+
+const meta: Meta< typeof EmptyState.Root > = {
+	title: 'Design System/Components/EmptyState',
+	component: EmptyState.Root,
+	subcomponents: {
+		'EmptyState.Visual': EmptyState.Visual,
+		'EmptyState.Icon': EmptyState.Icon,
+		'EmptyState.Title': EmptyState.Title,
+		'EmptyState.Description': EmptyState.Description,
+		'EmptyState.Actions': EmptyState.Actions,
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof EmptyState.Root >;
+
+export const Default: Story = {
+	args: {
+		children: (
+			<>
+				<EmptyState.Icon icon={ search } />
+				<EmptyState.Title>No results found</EmptyState.Title>
+				<EmptyState.Description>
+					Try adjusting your search or filter to find what you&apos;re
+					looking for.
+				</EmptyState.Description>
+				<EmptyState.Actions>
+					<Button variant="outline">Clear filters</Button>
+					<Button>Add item</Button>
+				</EmptyState.Actions>
+			</>
+		),
+	},
+};
+
+export const WithCustomVisual: Story = {
+	args: {
+		children: (
+			<>
+				<EmptyState.Visual>
+					<svg
+						width="50"
+						height="50"
+						viewBox="0 0 50 50"
+						fill="none"
+						xmlns="http://www.w3.org/2000/svg"
+					>
+						<circle cx="25" cy="25" r="25" fill="currentColor" />
+					</svg>
+				</EmptyState.Visual>
+				<EmptyState.Title>All caught up!</EmptyState.Title>
+				<EmptyState.Description>
+					You&apos;ve completed all your tasks. Great work!
+				</EmptyState.Description>
+				<EmptyState.Actions>
+					<Button>Create new task</Button>
+				</EmptyState.Actions>
+			</>
+		),
+	},
+};

package/src/empty-state/style.module.css

@@ -0,0 +1,53 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.root {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		text-align: center;
+		max-width: var(--wpds-dimension-surface-width-sm);
+		gap: var(--wpds-dimension-gap-xs);
+		font-family: var(--wpds-typography-font-family-body);
+		color: var(--wpds-color-fg-content-neutral);
+		text-wrap: balance;
+	}
+
+	.visual {
+		display: flex;
+		margin-block-end: var(--wpds-dimension-gap-xs);
+		align-items: center;
+		justify-content: center;
+		color: var(--wpds-color-fg-content-neutral-weak);
+		line-height: 1;
+	}
+
+	.icon {
+		padding: var(--wpds-dimension-padding-xs);
+		border: 1px solid var(--wpds-color-stroke-surface-neutral-weak);
+		border-radius: 50%;
+		background-color: var(--wpds-color-bg-surface-neutral-weak);
+	}
+
+	.title {
+		margin: 0;
+	}
+
+	.description {
+		margin: 0;
+		color: var(--wpds-color-fg-content-neutral-weak);
+	}
+
+	.actions {
+		display: flex;
+		margin-block-start: var(--wpds-dimension-gap-md);
+		flex-direction: column;
+		gap: var(--wpds-dimension-gap-xs);
+		align-items: center;
+
+		@media (min-width: 480px) {
+			flex-direction: row;
+			justify-content: center;
+		}
+	}
+}

package/src/empty-state/test/actions.test.tsx

@@ -0,0 +1,18 @@
+import { render } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import { Actions } from '../index';
+import { Button } from '../../button';
+
+describe( 'EmptyState.Actions', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLDivElement >();
+
+		render(
+			<Actions ref={ ref }>
+				<Button>Action</Button>
+			</Actions>
+		);
+
+		expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+	} );
+} );

package/src/empty-state/test/description.test.tsx

@@ -0,0 +1,26 @@
+import { render } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import { Description } from '../index';
+
+describe( 'EmptyState.Description', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLParagraphElement >();
+
+		render( <Description ref={ ref }>Description text</Description> );
+
+		expect( ref.current ).toBeInstanceOf( HTMLParagraphElement );
+	} );
+
+	it( 'forwards ref to custom render element', () => {
+		const ref = createRef< HTMLDivElement >();
+
+		render(
+			<Description ref={ ref } render={ <div /> }>
+				Description text
+			</Description>
+		);
+
+		expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+		expect( ref.current?.tagName ).toBe( 'DIV' );
+	} );
+} );

package/src/empty-state/test/icon.test.tsx

@@ -0,0 +1,13 @@
+import { render } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import { Icon } from '../index';
+
+describe( 'EmptyState.Icon', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLDivElement >();
+
+		render( <Icon ref={ ref } icon={ <svg /> } /> );
+
+		expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+	} );
+} );

package/src/empty-state/test/root.test.tsx

@@ -0,0 +1,13 @@
+import { render } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import { Root } from '../index';
+
+describe( 'EmptyState.Root', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLDivElement >();
+
+		render( <Root ref={ ref }>Empty state content</Root> );
+
+		expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+	} );
+} );

package/src/empty-state/test/title.test.tsx

@@ -0,0 +1,26 @@
+import { render } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import { Title } from '../index';
+
+describe( 'EmptyState.Title', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLHeadingElement >();
+
+		render( <Title ref={ ref }>No results found</Title> );
+
+		expect( ref.current ).toBeInstanceOf( HTMLHeadingElement );
+	} );
+
+	it( 'forwards ref to custom render element', () => {
+		const ref = createRef< HTMLHeadingElement >();
+
+		render(
+			<Title ref={ ref } render={ <h3 /> }>
+				No results found
+			</Title>
+		);
+
+		expect( ref.current ).toBeInstanceOf( HTMLHeadingElement );
+		expect( ref.current?.tagName ).toBe( 'H3' );
+	} );
+} );

package/src/empty-state/test/visual.test.tsx

@@ -0,0 +1,17 @@
+import { render } from '@testing-library/react';
+import { createRef } from '@wordpress/element';
+import { Visual } from '../index';
+
+describe( 'EmptyState.Visual', () => {
+	it( 'forwards ref', () => {
+		const ref = createRef< HTMLDivElement >();
+
+		render(
+			<Visual ref={ ref }>
+				<svg />
+			</Visual>
+		);
+
+		expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+	} );
+} );