@wordpress/ui 0.6.1-next.v.0 → 0.7.0

package/src/button/style.module.css

@@ -17,10 +17,11 @@
 		--wp-ui-button-foreground-color: var(--wpds-color-fg-interactive-brand-strong);
 		--wp-ui-button-foreground-color-active: var(--wpds-color-fg-interactive-brand-strong-active);
 		--wp-ui-button-foreground-color-disabled: var(--wpds-color-fg-interactive-neutral-strong-disabled);
-		--wp-ui-button-padding-inline: calc(3 * var(--wpds-dimension-base)); /* TODO: Create new interactive padding tokens */
+		--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-min-width: calc(4ch + 2 * var(--wp-ui-button-padding-inline));
 
 		/* by default, borders have the same color as the background */
 		--wp-ui-button-border-color: var(--wp-ui-button-background-color);
@@ -32,8 +33,9 @@
 		display: inline-flex;
 		justify-content: center;
 		align-items: center;
-		gap: calc(2 * var(--wpds-dimension-base)); /* TODO: Consider new interactive/control gap tokens */
+		gap: var(--wpds-dimension-gap-sm);
 		aspect-ratio: var(--wp-ui-button-aspect-ratio);
+		min-width: var(--wp-ui-button-min-width);
 		height: var(--wp-ui-button-height);
 		padding-inline: var(--wp-ui-button-padding-inline);
 		border-style: solid;
@@ -68,20 +70,22 @@
 			text-decoration: inherit;
 		}
 
-		/* States */
-		&:not([aria-disabled="true"]):is(:hover, :active, :focus) {
+		/* States — use property declarations (not variable reassignment) so that
+		   higher CSS layers can safely override the custom property values without
+		   breaking state handling. */
+		&:not([data-disabled]):is(:hover, :active, :focus) {
 			/* hover/active/focus states apply when the button is not disabled. A non
 			disabled, loading button will have hover/active/focus styles */
-			--wp-ui-button-background-color: var(--wp-ui-button-background-color-active);
-			--wp-ui-button-foreground-color: var(--wp-ui-button-foreground-color-active);
-			--wp-ui-button-border-color: var(--wp-ui-button-border-color-active);
+			background-color: var(--wp-ui-button-background-color-active);
+			color: var(--wp-ui-button-foreground-color-active);
+			border-color: var(--wp-ui-button-border-color-active);
 		}
 
-		&[aria-disabled="true"]:not(.is-loading) {
+		&[data-disabled]:not(.is-loading) {
 			/* A loading button, even when disabled, won't "look" disabled */
-			--wp-ui-button-background-color: var(--wp-ui-button-background-color-disabled);
-			--wp-ui-button-foreground-color: var(--wp-ui-button-foreground-color-disabled);
-			--wp-ui-button-border-color: var(--wp-ui-button-border-color-disabled);
+			background-color: var(--wp-ui-button-background-color-disabled);
+			color: var(--wp-ui-button-foreground-color-disabled);
+			border-color: var(--wp-ui-button-border-color-disabled);
 
 			@media ( forced-colors: active ) {
 				border-color: GrayText;
@@ -119,7 +123,7 @@
 	}
 
 	.is-small {
-		--wp-ui-button-padding-inline: calc(2 * var(--wpds-dimension-base)); /* TODO: Create new interactive padding tokens */
+		--wp-ui-button-padding-inline: var(--wpds-dimension-padding-sm);
 		--wp-ui-button-height: 24px;
 	}
 
@@ -188,6 +192,7 @@
 	}
 
 	.is-unstyled {
+		min-width: unset;
 		border: none;
 		background: none;
 	}
@@ -199,6 +204,12 @@
 	.is-loading {
 		color: transparent;
 
+		/* Keep text transparent when a loading button is hovered — needed because
+		 the hover state now sets `color` as a property declaration. */
+		&:not([data-disabled]):is(:hover, :active, :focus) {
+			color: transparent;
+		}
+
 		* {
 			opacity: 0;
 		}

package/src/dialog/action.tsx

@@ -0,0 +1,22 @@
+import { Dialog as _Dialog } from '@base-ui/react/dialog';
+import { forwardRef } from '@wordpress/element';
+import { Button } from '../button';
+import type { ActionProps } from './types';
+
+/**
+ * Renders a button that closes the dialog when clicked.
+ * Accepts all Button component props for styling.
+ */
+const Action = forwardRef< HTMLButtonElement, ActionProps >(
+	function DialogAction( { render, ...props }, ref ) {
+		return (
+			<_Dialog.Close
+				ref={ ref }
+				render={ <Button render={ render } /> }
+				{ ...props }
+			/>
+		);
+	}
+);
+
+export { Action };

package/src/dialog/close-icon.tsx

@@ -0,0 +1,32 @@
+import { Dialog as _Dialog } from '@base-ui/react/dialog';
+import { forwardRef } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { close } from '@wordpress/icons';
+import { IconButton } from '../icon-button';
+import type { CloseIconProps } from './types';
+
+/**
+ * Renders an icon button that closes the dialog when clicked.
+ * Provides a default close icon and accessible label.
+ */
+const CloseIcon = forwardRef< HTMLButtonElement, CloseIconProps >(
+	function DialogCloseIcon( { icon, label, ...props }, ref ) {
+		return (
+			<_Dialog.Close
+				ref={ ref }
+				render={
+					<IconButton
+						variant="minimal"
+						size="compact"
+						tone="neutral"
+						{ ...props }
+						icon={ icon ?? close }
+						label={ label ?? __( 'Close' ) }
+					/>
+				}
+			/>
+		);
+	}
+);
+
+export { CloseIcon };

package/src/dialog/context.tsx

@@ -0,0 +1,113 @@
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+} from '@wordpress/element';
+
+/**
+ * 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';
+
+type DialogValidationContextType = {
+	registerTitle: ( element: HTMLElement | null ) => void;
+};
+
+// Context is only created in development mode.
+const DialogValidationContext = VALIDATION_ENABLED
+	? createContext< DialogValidationContextType | null >( null )
+	: ( null as unknown as React.Context< DialogValidationContextType | null > );
+
+/**
+ * Development-only hook to access the dialog validation context.
+ */
+function useDialogValidationContextDev() {
+	return useContext( DialogValidationContext );
+}
+
+/**
+ * Production no-op hook.
+ */
+function useDialogValidationContextProd() {
+	return null;
+}
+
+/**
+ * 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 }</>;
+}
+
+/**
+ * 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;

package/src/dialog/footer.tsx

@@ -0,0 +1,26 @@
+import { mergeProps, useRender } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import styles from './style.module.css';
+import type { FooterProps } from './types';
+
+/**
+ * Renders the footer section of the dialog, typically containing
+ * action buttons.
+ */
+const Footer = forwardRef< HTMLDivElement, FooterProps >( function DialogFooter(
+	{ className, render, ...props },
+	ref
+) {
+	const element = useRender( {
+		render,
+		ref,
+		props: mergeProps< 'div' >( props, {
+			className: clsx( styles.footer, className ),
+		} ),
+	} );
+
+	return element;
+} );
+
+export { Footer };

package/src/dialog/header.tsx

@@ -0,0 +1,26 @@
+import { mergeProps, useRender } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import styles from './style.module.css';
+import type { HeaderProps } from './types';
+
+/**
+ * Renders the header section of the dialog, typically containing
+ * the heading and close button.
+ */
+const Header = forwardRef< HTMLDivElement, HeaderProps >( function DialogHeader(
+	{ className, render, ...props },
+	ref
+) {
+	const element = useRender( {
+		render,
+		ref,
+		props: mergeProps< 'div' >( props, {
+			className: clsx( styles.header, className ),
+		} ),
+	} );
+
+	return element;
+} );
+
+export { Header };

package/src/dialog/index.ts

@@ -0,0 +1,10 @@
+import { Action } from './action';
+import { CloseIcon } from './close-icon';
+import { Footer } from './footer';
+import { Header } from './header';
+import { Popup } from './popup';
+import { Root } from './root';
+import { Title } from './title';
+import { Trigger } from './trigger';
+
+export { Action, CloseIcon, Footer, Header, Popup, Root, Title, Trigger };

package/src/dialog/popup.tsx

@@ -0,0 +1,46 @@
+import { Dialog as _Dialog } from '@base-ui/react/dialog';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import {
+	type ThemeProvider as ThemeProviderType,
+	privateApis as themePrivateApis,
+} from '@wordpress/theme';
+import { unlock } from '../lock-unlock';
+import { DialogValidationProvider } from './context';
+import styles from './style.module.css';
+import type { PopupProps } from './types';
+
+const ThemeProvider: typeof ThemeProviderType =
+	unlock( themePrivateApis ).ThemeProvider;
+
+/**
+ * Renders the dialog popup element that contains the dialog content.
+ * Uses a portal to render outside the DOM hierarchy.
+ */
+const Popup = forwardRef< HTMLDivElement, PopupProps >( function DialogPopup(
+	{ className, size = 'medium', children, ...props },
+	ref
+) {
+	return (
+		<_Dialog.Portal>
+			<_Dialog.Backdrop className={ styles.backdrop } />
+			<ThemeProvider>
+				<_Dialog.Popup
+					ref={ ref }
+					className={ clsx(
+						styles.popup,
+						className,
+						styles[ `is-${ size }` ]
+					) }
+					{ ...props }
+				>
+					<DialogValidationProvider>
+						{ children }
+					</DialogValidationProvider>
+				</_Dialog.Popup>
+			</ThemeProvider>
+		</_Dialog.Portal>
+	);
+} );
+
+export { Popup };

package/src/dialog/root.tsx

@@ -0,0 +1,14 @@
+import { Dialog as _Dialog } from '@base-ui/react/dialog';
+import type { RootProps } from './types';
+
+/**
+ * Groups the dialog trigger and popup.
+ *
+ * `Dialog` is a collection of React components that combine to render
+ * an ARIA-compliant dialog pattern.
+ */
+function Root( props: RootProps ) {
+	return <_Dialog.Root { ...props } />;
+}
+
+export { Root };

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

@@ -0,0 +1,177 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useId, useState } from '@wordpress/element';
+import type { ComponentProps } from 'react';
+import * as Dialog from '../index';
+
+const meta: Meta< typeof Dialog.Root > = {
+	title: 'Design System/Components/Dialog',
+	component: Dialog.Root,
+	subcomponents: {
+		'Dialog.Trigger': Dialog.Trigger,
+		'Dialog.Popup': Dialog.Popup,
+		'Dialog.Header': Dialog.Header,
+		'Dialog.Title': Dialog.Title,
+		'Dialog.CloseIcon': Dialog.CloseIcon,
+		'Dialog.Action': Dialog.Action,
+		'Dialog.Footer': Dialog.Footer,
+	},
+	argTypes: {
+		modal: {
+			control: 'inline-radio',
+			options: [ true, false, 'trap-focus' ],
+			table: {
+				defaultValue: { summary: 'true' },
+				type: {
+					summary: 'boolean | "trap-focus"',
+				},
+			},
+		},
+	},
+	parameters: {
+		docs: {
+			description: {
+				component: `
+Dialog is a popup that opens on top of the entire page. Every dialog must include a \`Dialog.Title\` component for accessibility — it serves as both the visible heading and the accessible label for the dialog.
+
+When using the Dialog component, make sure to 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.
+				`,
+			},
+		},
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof Dialog.Root >;
+
+/**
+ * An informational dialog with a close icon, where there is no ambiguity on
+ * what happens when clicking the close icon.
+ */
+export const _Default: Story = {
+	args: {
+		children: (
+			<>
+				<Dialog.Trigger>Open Dialog</Dialog.Trigger>
+				<Dialog.Popup>
+					<Dialog.Header>
+						<Dialog.Title>Welcome</Dialog.Title>
+						<Dialog.CloseIcon />
+					</Dialog.Header>
+					<p>
+						This dialog demonstrates best practices for
+						informational dialogs. It includes a close icon because
+						dismissing it is safe and expected.
+					</p>
+					<Dialog.Footer>
+						<Dialog.Action>Got it</Dialog.Action>
+					</Dialog.Footer>
+				</Dialog.Popup>
+			</>
+		),
+	},
+};
+
+/**
+ * A confirmation dialog that intentionally omits the close icon. The user
+ * must explicitly choose "Cancel" or "Confirm" to make their intent clear,
+ * since it is not obvious what would happen when clicking a close icon.
+ */
+export const ConfirmDialog: Story = {
+	args: {
+		children: (
+			<>
+				<Dialog.Trigger>Confirm Action</Dialog.Trigger>
+				<Dialog.Popup>
+					<Dialog.Header>
+						<Dialog.Title>Confirm Action</Dialog.Title>
+					</Dialog.Header>
+					<p>
+						Are you sure you want to proceed? This action cannot be
+						undone.
+					</p>
+					<Dialog.Footer>
+						<Dialog.Action variant="outline">Cancel</Dialog.Action>
+						<Dialog.Action>Confirm</Dialog.Action>
+					</Dialog.Footer>
+				</Dialog.Popup>
+			</>
+		),
+	},
+};
+
+const ALL_SIZES = [ 'small', 'medium', 'large', 'stretch', 'full' ] as const;
+
+function SizeSelector( {
+	value,
+	onChange,
+}: {
+	value: ComponentProps< typeof Dialog.Popup >[ 'size' ];
+	onChange: ( size: ComponentProps< typeof Dialog.Popup >[ 'size' ] ) => void;
+} ) {
+	const selectId = useId();
+	return (
+		<div style={ { display: 'flex', gap: 8, alignItems: 'center' } }>
+			<label htmlFor={ selectId }>Dialog size preset</label>
+			<select
+				id={ selectId }
+				value={ value }
+				onChange={ ( e ) =>
+					onChange(
+						e.target.value as ComponentProps<
+							typeof Dialog.Popup
+						>[ 'size' ]
+					)
+				}
+			>
+				{ ALL_SIZES.map( ( s ) => (
+					<option key={ s } value={ s }>
+						{ s }
+						{ s === 'medium' ? ' (default)' : '' }
+					</option>
+				) ) }
+			</select>
+		</div>
+	);
+}
+
+function SizePlaygroundContent() {
+	const [ size, setSize ] =
+		useState< ComponentProps< typeof Dialog.Popup >[ 'size' ] >( 'medium' );
+	return (
+		<>
+			<div
+				style={ {
+					display: 'flex',
+					flexDirection: 'column',
+					gap: 16,
+					alignItems: 'start',
+				} }
+			>
+				<SizeSelector value={ size } onChange={ setSize } />
+				<Dialog.Trigger>Open Dialog</Dialog.Trigger>
+			</div>
+			<Dialog.Popup size={ size }>
+				<Dialog.Header>
+					<Dialog.Title>Size Playground</Dialog.Title>
+					<Dialog.CloseIcon />
+				</Dialog.Header>
+				<SizeSelector value={ size } onChange={ setSize } />
+				<p>
+					Use the dropdown above (or outside the dialog) to change the
+					popup size. Both controls stay in sync.
+				</p>
+				<Dialog.Footer>
+					<Dialog.Action>Got it</Dialog.Action>
+				</Dialog.Footer>
+			</Dialog.Popup>
+		</>
+	);
+}
+
+export const AllSizes: Story = {
+	args: {
+		children: <SizePlaygroundContent />,
+	},
+};

package/src/dialog/style.module.css

@@ -0,0 +1,114 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.backdrop {
+		position: fixed;
+		inset: 0;
+		background-color: rgba(0, 0, 0, 0.35);
+
+		&[data-starting-style],
+		&[data-ending-style] {
+			opacity: 0;
+		}
+
+		&[data-open] {
+			opacity: 1;
+		}
+
+		@media not (prefers-reduced-motion) {
+			transition: opacity 0.2s ease-out;
+		}
+	}
+
+	.popup {
+		position: fixed;
+		top: 50%;
+		/* stylelint-disable-next-line plugin/use-logical-properties-and-values -- Physical centering technique used with transform: translate(-50%, -50%) */
+		left: 50%;
+		transform: translate(-50%, -50%);
+		box-sizing: border-box;
+		min-width: 320px;
+		width: calc(100vw - 2 * var(--wpds-dimension-padding-2xl));
+		max-height: calc(100vh - 2 * var(--wpds-dimension-padding-2xl));
+		padding: var(--wpds-dimension-padding-2xl);
+		background-color: var(--wpds-color-bg-surface-neutral-strong);
+		border-radius: var(--wpds-border-radius-lg);
+		box-shadow: var(--wpds-elevation-lg);
+		overflow: auto;
+		font-family: var(--wpds-font-family-body);
+		font-size: var(--wpds-font-size-md);
+		line-height: var(--wpds-font-line-height-md);
+		color: var(--wpds-color-fg-content-neutral);
+
+		&[data-starting-style],
+		&[data-ending-style] {
+			opacity: 0;
+			transform: translate(-50%, -50%) scale(0.9);
+		}
+
+		@media not (prefers-reduced-motion) {
+			transition:
+				opacity 0.2s cubic-bezier(1, 0, 0.2, 1),
+				transform 0.2s cubic-bezier(1, 0, 0.2, 1);
+
+			&[data-open] {
+				transition:
+					opacity 0.2s cubic-bezier(0.29, 0, 0, 1),
+					transform 0.2s cubic-bezier(0.29, 0, 0, 1);
+			}
+		}
+
+		@media (min-width: 480px) {
+			min-width: 384px;
+		}
+
+		&.is-small {
+			max-width: 384px;
+		}
+
+		&.is-medium {
+			max-width: 512px;
+		}
+
+		&.is-large {
+			max-width: 840px;
+		}
+
+		&.is-stretch {
+			/* The dialog stretches to fill available width. */
+			max-width: none;
+		}
+
+		&.is-full {
+			/*
+			 * Force full height (full width is already in default styles).
+			 * The max-{width,height} properties will make sure some padding is shown.
+			 */
+			height: 100vh;
+		}
+	}
+
+	.header {
+		display: flex;
+		justify-content: space-between;
+		align-items: center;
+		margin-bottom: var(--wpds-dimension-gap-lg);
+	}
+
+	.title {
+		margin: 0;
+		font-size: var(--wpds-font-size-xl);
+		font-weight: var(--wpds-font-weight-medium);
+		line-height: var(--wpds-font-line-height-xl);
+		color: var(--wpds-color-fg-content-neutral);
+	}
+
+	.footer {
+		display: flex;
+		justify-content: flex-end;
+		align-items: center;
+		gap: var(--wpds-dimension-gap-sm);
+		margin-top: var(--wpds-dimension-gap-lg);
+		padding-top: var(--wpds-dimension-padding-lg);
+	}
+}