@wordpress/ui 0.9.1-next.v.202603102151.0 → 0.10.0

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

@@ -306,4 +306,121 @@ 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();
+		} );
+	} );
 } );

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,7 +26,9 @@ 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.
 	 */
@@ -32,9 +38,9 @@ export interface PopupProps extends ComponentProps< 'div' > {
 	 * 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.
 	 *

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,27 @@
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { Text } from '../text';
+import type { EmptyStateDescriptionProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * 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, className, children, ...props },
+	ref
+) {
+	return (
+		<Text
+			variant="body-md"
+			render={ render ?? <p ref={ ref } { ...props } /> }
+			className={ clsx( styles.description, className ) }
+		>
+			{ 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-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,13 @@
+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 );
+	} );
+} );

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,13 @@
+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 );
+	} );
+} );

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 );
+	} );
+} );

package/src/empty-state/title.tsx

@@ -0,0 +1,23 @@
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { Text } from '../text';
+import type { EmptyStateTitleProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * The title is a short heading that communicates the empty state.
+ */
+export const Title = forwardRef< HTMLHeadingElement, EmptyStateTitleProps >(
+	function EmptyStateTitle( { render, className, children, ...props }, ref ) {
+		return (
+			<Text
+				variant="heading-lg"
+				// eslint-disable-next-line jsx-a11y/heading-has-content -- content provided via render prop
+				render={ render ?? <h2 ref={ ref } { ...props } /> }
+				className={ clsx( styles.title, className ) }
+			>
+				{ children }
+			</Text>
+		);
+	}
+);

package/src/empty-state/types.ts

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react';
+import type { ComponentProps } from '../utils/types';
+import type { IconProps } from '../icon/types';
+
+export interface EmptyStateRootProps extends ComponentProps< 'div' > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+export interface EmptyStateVisualProps extends ComponentProps< 'div' > {
+	/**
+	 * The visual content of the empty state (e.g., icon, illustration).
+	 */
+	children?: ReactNode;
+}
+
+export interface EmptyStateIconProps extends ComponentProps< 'div' > {
+	/**
+	 * The icon to render.
+	 */
+	icon: IconProps[ 'icon' ];
+}
+
+export interface EmptyStateTitleProps extends ComponentProps< 'h2' > {
+	/**
+	 * The title text of the empty state.
+	 */
+	children?: ReactNode;
+}
+
+export interface EmptyStateDescriptionProps extends ComponentProps< 'p' > {
+	/**
+	 * The description text of the empty state.
+	 */
+	children?: ReactNode;
+}
+
+export interface EmptyStateActionsProps extends ComponentProps< 'div' > {
+	/**
+	 * The action buttons for the empty state.
+	 */
+	children?: ReactNode;
+}

package/src/empty-state/visual.tsx

@@ -0,0 +1,24 @@
+import { useRender, mergeProps } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import type { EmptyStateVisualProps } from './types';
+import styles from './style.module.css';
+
+/**
+ * A container for visual content in an empty state (e.g., icons, illustrations).
+ * Provides appropriate spacing and alignment for visual elements.
+ */
+export const Visual = forwardRef< HTMLDivElement, EmptyStateVisualProps >(
+	function EmptyStateVisual( { render, ...props }, ref ) {
+		const className = clsx( styles.visual );
+
+		const element = useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >( { className }, props ),
+		} );
+
+		return element;
+	}
+);

package/src/form/index.ts

@@ -0,0 +1,3 @@
+export * from './primitives';
+
+export * from './input-control';

package/src/form/input-control/index.ts

@@ -0,0 +1 @@
+export { InputControl } from './input-control';

package/src/form/input-control/input-control.tsx

@@ -0,0 +1,33 @@
+import { forwardRef } from '@wordpress/element';
+import { Input, Field } from '../primitives';
+import type { InputControlProps } from './types';
+
+/**
+ * A complete input field with integrated label and description.
+ */
+export const InputControl = forwardRef< HTMLInputElement, InputControlProps >(
+	function InputControl(
+		{
+			className,
+			label,
+			description,
+			details,
+			hideLabelFromVision,
+			...restProps
+		},
+		ref
+	) {
+		return (
+			<Field.Root className={ className }>
+				<Field.Label hideFromVision={ hideLabelFromVision }>
+					{ label }
+				</Field.Label>
+				<Input ref={ ref } { ...restProps } />
+				{ description && (
+					<Field.Description>{ description }</Field.Description>
+				) }
+				{ details && <Field.Details>{ details }</Field.Details> }
+			</Field.Root>
+		);
+	}
+);