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

package/src/alert-dialog/trigger.tsx

@@ -1,6 +1,6 @@
+import { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
 import { forwardRef } from '@wordpress/element';
 
-import * as Dialog from '../dialog';
 import type { TriggerProps } from './types';
 
 /**
@@ -8,7 +8,7 @@ import type { TriggerProps } from './types';
  */
 const Trigger = forwardRef< HTMLButtonElement, TriggerProps >(
 	function AlertDialogTrigger( props, ref ) {
-		return <Dialog.Trigger ref={ ref } { ...props } />;
+		return <_AlertDialog.Trigger ref={ ref } { ...props } />;
 	}
 );
 

package/src/alert-dialog/types.ts

@@ -1,7 +1,18 @@
 import type { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
 import type { ReactNode } from 'react';
 
-import type { TriggerProps as DialogTriggerProps } from '../dialog/types';
+import type { ComponentProps } from '../utils/types';
+
+/**
+ * The return type of `onConfirm`. Return `void` (or nothing) to auto-close
+ * the dialog after the confirm handler completes. Return `{ close: false }`
+ * to keep the dialog open (e.g. for validation errors).
+ *
+ * Return `{ error: '...' }` to display a built-in error message below the
+ * action buttons. When `error` is provided, the dialog stays open
+ * regardless of the `close` value.
+ */
+export type ConfirmResult = void | { close?: boolean; error?: string };
 
 export interface RootProps
 	extends Pick<
@@ -14,6 +25,43 @@ export interface RootProps
 	 */
 	children: ReactNode;
 
+	/**
+	 * Callback fired when the user confirms the action.
+	 *
+	 * - Synchronous handlers: the dialog closes immediately after the
+	 *   handler returns.
+	 * - Async handlers: the dialog enters a "pending" state (buttons
+	 *   disabled, spinner shown on the confirm button) until the promise
+	 *   settles.
+	 *
+	 * Return `{ close: false }` to keep the dialog open after the handler
+	 * completes (e.g. for server-side validation). Return `void` or
+	 * `{ close: true }` to close the dialog (the default).
+	 *
+	 * Return `{ error: '...' }` to show a built-in error message below
+	 * the action buttons. The dialog stays open regardless of the `close`
+	 * value. The error is announced to screen readers and is automatically
+	 * cleared on the next confirm attempt or when the dialog reopens.
+	 *
+	 * If the promise rejects (or the handler throws) without returning an
+	 * `error`, the dialog stays open and returns to idle without showing
+	 * a visible error message. The error is logged to the console.
+	 * To show a user-facing message on failure, catch the error and
+	 * return `{ close: false, error: '...' }`.
+	 */
+	onConfirm?: () => ConfirmResult | Promise< ConfirmResult >;
+}
+
+export interface TriggerProps extends ComponentProps< 'button' > {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+}
+
+export interface PopupProps
+	extends ComponentProps< 'div' >,
+		Pick< _AlertDialog.Popup.Props, 'initialFocus' | 'finalFocus' > {
 	/**
 	 * The semantic intent of the dialog, which determines its styling.
 	 *
@@ -28,26 +76,27 @@ export interface RootProps
 	 * @default 'default'
 	 */
 	intent?: 'default' | 'irreversible';
-}
 
-export type TriggerProps = DialogTriggerProps;
-
-export interface PopupProps {
 	/**
 	 * The title displayed in the dialog header. This serves as both the
-	 * visible heading and the accessible label for the dialog.
+	 * visible heading and the accessible label (`aria-labelledby`) for the
+	 * dialog. Must be a plain string to ensure a predictable accessible name.
 	 */
 	title: string;
 
 	/**
-	 * The message content displayed in the dialog body.
+	 * An optional description displayed below the title. Rendered using
+	 * Base UI's `AlertDialog.Description` for proper `aria-describedby`
+	 * association with the dialog. Must be a plain string to ensure a
+	 * predictable accessible description.
 	 */
-	children: ReactNode;
+	description?: string;
 
 	/**
-	 * Callback fired when the user confirms the action.
+	 * Optional body content displayed between the description and the
+	 * action buttons. Use for supplementary details or form fields.
 	 */
-	onConfirm: () => void;
+	children?: ReactNode;
 
 	/**
 	 * Custom text for the confirm button.
@@ -62,22 +111,4 @@ export interface PopupProps {
 	 * @default 'Cancel'
 	 */
 	cancelButtonText?: string;
-
-	/**
-	 * Whether the confirm action is in a loading state (e.g. an async
-	 * operation is in progress). When `true`, the confirm button shows a
-	 * spinner and the cancel button is disabled.
-	 *
-	 * **Important:** Passing this prop — even as `false` — opts into
-	 * manual-close mode: the confirm button will no longer auto-close the
-	 * dialog. The consumer is responsible for setting `open={false}` when
-	 * the operation completes. Omit the prop entirely for the default
-	 * auto-close-on-confirm behavior.
-	 *
-	 * To implement an async confirm flow, use controlled mode
-	 * (`open` / `onOpenChange`) and manage the loading state externally:
-	 * prevent closing in `onOpenChange` while loading, and set
-	 * `open={false}` once the operation completes.
-	 */
-	loading?: boolean;
 }

package/src/button/button.tsx

@@ -7,6 +7,7 @@ import { type ButtonProps } from './types';
 import styles from './style.module.css';
 import resetStyles from '../utils/css/resets.module.css';
 import focusStyles from '../utils/css/focus.module.css';
+import defenseStyles from '../utils/css/global-css-defense.module.css';
 
 export const Button = forwardRef< HTMLButtonElement, ButtonProps >(
 	function Button(
@@ -25,6 +26,7 @@ export const Button = forwardRef< HTMLButtonElement, ButtonProps >(
 		ref
 	) {
 		const mergedClassName = clsx(
+			defenseStyles.button,
 			resetStyles[ 'box-sizing' ],
 			focusStyles[ 'outset-ring--focus-except-active' ],
 			variant !== 'unstyled' && styles.button,

package/src/button/style.module.css

@@ -28,6 +28,10 @@
 		--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-size: var(--wp-ui-button-font-size);
+		--_gcd-button-font-weight: var(--wp-ui-button-font-weight);
+
 		/* Styles */
 		position: relative;
 		display: inline-flex;

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

@@ -116,7 +116,6 @@ export const CustomSemantics: Story = {
 		children: (
 			<>
 				<Card.Header>
-					{ /* eslint-disable-next-line jsx-a11y/heading-has-content -- content provided via render prop */ }
 					<Card.Title render={ <h2 /> }>Section heading</Card.Title>
 				</Card.Header>
 				<Card.Content>

package/src/card/style.module.css

@@ -12,6 +12,7 @@
 		border-radius: var(--wpds-border-radius-lg);
 		overflow: clip;
 		background-color: var(--wpds-color-bg-surface-neutral-strong);
+		color: var(--wpds-color-fg-content-neutral);
 	}
 
 	/* Padding is applied to the individual header/content elements to enable
@@ -40,6 +41,5 @@
 
 	.title {
 		margin: 0;
-		color: var(--wpds-color-fg-content-neutral);
 	}
 }

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

@@ -82,7 +82,6 @@ describe( 'Card', () => {
 			render(
 				<Card.Root>
 					<Card.Header>
-						{ /* eslint-disable-next-line jsx-a11y/heading-has-content -- content provided via render prop */ }
 						<Card.Title render={ <h2 /> }>Heading</Card.Title>
 					</Card.Header>
 				</Card.Root>

package/src/empty-state/title.tsx

@@ -12,7 +12,6 @@ export const Title = forwardRef< HTMLHeadingElement, EmptyStateTitleProps >(
 		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 ) }
 			>

package/src/form/primitives/field/description.tsx

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
 import { Field as _Field } from '@base-ui/react/field';
 import { forwardRef } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import fieldStyles from '../../../utils/css/field.module.css';
 import type { FieldDescriptionProps } from './types';
 
@@ -11,7 +12,11 @@ export const Description = forwardRef<
 	return (
 		<_Field.Description
 			ref={ ref }
-			className={ clsx( fieldStyles.description, className ) }
+			className={ clsx(
+				defenseStyles.p,
+				fieldStyles.description,
+				className
+			) }
 			{ ...restProps }
 		/>
 	);

package/src/form/primitives/fieldset/description.tsx

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
 import { mergeProps, useRender } from '@base-ui/react';
 import { forwardRef, useEffect, useId } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import fieldStyles from '../../../utils/css/field.module.css';
 import { useFieldsetContext } from './context';
 import type { FieldsetDescriptionProps } from './types';
@@ -27,7 +28,14 @@ export const FieldsetDescription = forwardRef<
 		render,
 		ref,
 		props: mergeProps< 'p' >(
-			{ className: clsx( fieldStyles.description, className ), id },
+			{
+				className: clsx(
+					defenseStyles.p,
+					fieldStyles.description,
+					className
+				),
+				id,
+			},
 			restProps
 		),
 	} );

package/src/form/primitives/input/input.tsx

@@ -1,6 +1,7 @@
 import { Input as _Input } from '@base-ui/react/input';
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import focusStyles from '../../../utils/css/focus.module.css';
 import styles from './style.module.css';
 import type { InputProps } from './types';
@@ -22,7 +23,11 @@ export const Input = forwardRef< HTMLElement, InputProps >( function Input(
 			prefix={ prefix }
 			suffix={ suffix }
 		>
-			<_Input ref={ ref } className={ styles.input } { ...restProps } />
+			<_Input
+				ref={ ref }
+				className={ clsx( defenseStyles.input, styles.input ) }
+				{ ...restProps }
+			/>
 		</InputLayout>
 	);
 } );

package/src/form/primitives/input/style.module.css

@@ -2,6 +2,10 @@
 
 @layer wp-ui-components {
 	.input {
+		--_gcd-input-padding:
+			var(--wp-ui-input-padding-block, 0)
+			var(--wp-ui-input-layout-padding-inline, 0);
+
 		padding-block: var(--wp-ui-input-padding-block, 0);
 		padding-inline: var(--wp-ui-input-layout-padding-inline, 0);
 		width: 100%;

package/src/form/primitives/input-layout/input-layout.tsx

@@ -1,5 +1,6 @@
 import clsx from 'clsx';
 import { Children, forwardRef } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import resetStyles from '../../../utils/css/resets.module.css';
 import styles from './style.module.css';
 import type { InputLayoutProps } from './types';
@@ -26,6 +27,7 @@ export const InputLayout = forwardRef< HTMLDivElement, InputLayoutProps >(
 			<div
 				ref={ ref }
 				className={ clsx(
+					defenseStyles.div,
 					resetStyles[ 'box-sizing' ],
 					styles[ 'input-layout' ],
 					styles[ `is-size-${ size }` ],

package/src/form/primitives/textarea/textarea.tsx

@@ -4,6 +4,7 @@ import { cloneElement, forwardRef } from '@wordpress/element';
 import styles from './style.module.css';
 import type { TextareaProps } from './types';
 import { Input } from '../input';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 
 const wrappedRender = (
 	render: NonNullable< TextareaProps[ 'render' ] >,
@@ -39,7 +40,15 @@ export const Textarea = forwardRef< HTMLTextAreaElement, TextareaProps >(
 				style={ style }
 				render={ wrappedRender(
 					render || ( ( props ) => <textarea { ...props } /> ),
-					{ className: styles.textarea, ref, rows, ...restProps }
+					{
+						className: clsx(
+							defenseStyles.textarea,
+							styles.textarea
+						),
+						ref,
+						rows,
+						...restProps,
+					}
 				) }
 				value={ value }
 				defaultValue={ defaultValue }

package/src/form/stories/shared.tsx

@@ -1,3 +1,5 @@
+import { Link } from '../..';
+
 export const WITH_DETAILS_DESCRIPTION = `\
 To add rich content (such as links) to the description, use the \`details\` prop.
 
@@ -11,9 +13,9 @@ so the readout is not unnecessarily verbose for screen reader users.`;
 export const DETAILS_EXAMPLE = (
 	<>
 		Details can include{ ' ' }
-		<a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a">
+		<Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a">
 			links to more information
-		</a>{ ' ' }
+		</Link>{ ' ' }
 		and other semantic elements.
 	</>
 );

package/src/index.ts

@@ -11,6 +11,7 @@ export * from './icon';
 export * from './icon-button';
 export * from './link';
 export * as Notice from './notice';
+export * as Popover from './popover';
 export * from './stack';
 export * as Tabs from './tabs';
 export * from './text';

package/src/link/link.tsx

@@ -6,6 +6,7 @@ import { type LinkProps } from './types';
 import resetStyles from '../utils/css/resets.module.css';
 import focusStyles from '../utils/css/focus.module.css';
 import styles from './style.module.css';
+import defenseStyles from '../utils/css/global-css-defense.module.css';
 
 /**
  * A styled anchor element with support for semantic color tones and an
@@ -39,6 +40,7 @@ export const Link = forwardRef< HTMLAnchorElement, LinkProps >( function Link(
 		ref,
 		props: mergeProps< 'a' >( props, {
 			className: clsx(
+				defenseStyles.a,
 				resetStyles[ 'box-sizing' ],
 				focusStyles[ 'outset-ring--focus' ],
 				variant !== 'unstyled' && styles.link,

package/src/link/style.module.css

@@ -9,28 +9,38 @@
 	/* Brand tone */
 	.is-brand,
 	.is-brand:visited {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-brand);
+
 		color: var(--wpds-color-fg-interactive-brand);
 	}
 
 	.is-brand:hover,
 	.is-brand:active {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-brand-active);
+
 		color: var(--wpds-color-fg-interactive-brand-active);
 	}
 
 	/* Neutral tone */
 	.is-neutral,
 	.is-neutral:visited {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-neutral);
+
 		color: var(--wpds-color-fg-interactive-neutral);
 		text-decoration-color: var(--wpds-color-stroke-interactive-neutral);
 	}
 
 	.is-neutral:hover,
 	.is-neutral:active {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-neutral-active);
+
 		color: var(--wpds-color-fg-interactive-neutral-active);
 	}
 
 	/* Unstyled variant */
 	.is-unstyled {
+		--_gcd-a-color: inherit;
+
 		color: inherit;
 		text-decoration: none;
 	}

package/src/popover/arrow.tsx

@@ -0,0 +1,49 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import styles from './style.module.css';
+import type { ArrowProps } from './types';
+
+function DefaultArrowSvg( props: React.ComponentProps< 'svg' > ) {
+	return (
+		<svg
+			width="20"
+			height="10"
+			viewBox="0 0 20 10"
+			fill="none"
+			{ ...props }
+		>
+			<path
+				d="M20 10H0V8h1.465a4 4 0 0 0 2.676-1.027l5.19-4.388c.378-.341.96-.341 1.338 0l5.19 4.388A4 4 0 0 0 18.535 8H20z"
+				className={ styles[ 'arrow-fill' ] }
+			/>
+			<path
+				d="M10 3.097 4.81 7.486A5 5 0 0 1 1.465 8.77H0V8h1.465a4 4 0 0 0 2.676-1.027l5.19-4.388c.378-.341.96-.341 1.338 0l5.19 4.388A4 4 0 0 0 18.535 8H20v.77h-1.465a5 5 0 0 1-3.345-1.284z"
+				className={ styles[ 'arrow-stroke' ] }
+			/>
+		</svg>
+	);
+}
+
+/**
+ * Renders an optional arrow element that points toward the anchor.
+ *
+ * Must be placed inside `Popover.Popup`. The arrow automatically rotates
+ * to match the current placement side.
+ */
+const Arrow = forwardRef< HTMLDivElement, ArrowProps >( function PopoverArrow(
+	{ children, className, ...props },
+	ref
+) {
+	return (
+		<_Popover.Arrow
+			ref={ ref }
+			className={ clsx( styles.arrow, className ) }
+			{ ...props }
+		>
+			{ children ?? <DefaultArrowSvg /> }
+		</_Popover.Arrow>
+	);
+} );
+
+export { Arrow };

package/src/popover/close.tsx

@@ -0,0 +1,24 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import { forwardRef } from '@wordpress/element';
+import type { CloseProps } from './types';
+
+/**
+ * Renders a button that closes the popover when clicked.
+ *
+ * When the popover opens, initial focus skips this button in favor of
+ * the first interactive element inside the popup (unless `initialFocus`
+ * on `Popover.Popup` overrides this behavior).
+ */
+const Close = forwardRef< HTMLButtonElement, CloseProps >(
+	function PopoverClose( props, ref ) {
+		return (
+			<_Popover.Close
+				ref={ ref }
+				data-wp-ui-popover-close=""
+				{ ...props }
+			/>
+		);
+	}
+);
+
+export { Close };

package/src/popover/context.tsx

@@ -0,0 +1,100 @@
+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 PopoverValidationContextType = {
+	registerTitle: ( element: HTMLElement | null ) => void;
+};
+
+const PopoverValidationContext = VALIDATION_ENABLED
+	? createContext< PopoverValidationContextType | null >( null )
+	: ( null as unknown as React.Context< PopoverValidationContextType | null > );
+
+function usePopoverValidationContextDev() {
+	return useContext( PopoverValidationContext );
+}
+
+function usePopoverValidationContextProd() {
+	return null;
+}
+
+/**
+ * Hook to access the popover validation context.
+ * Returns null in production or if not within a Popover.Popup.
+ */
+export const usePopoverValidationContext = VALIDATION_ENABLED
+	? usePopoverValidationContextDev
+	: usePopoverValidationContextProd;
+
+/**
+ * Development-only provider that tracks whether Popover.Title is rendered.
+ */
+function PopoverValidationProviderDev( {
+	children,
+}: {
+	children: React.ReactNode;
+} ) {
+	const titleElementRef = useRef< HTMLElement | null >( null );
+
+	const registerTitle = useCallback( ( element: HTMLElement | null ) => {
+		titleElementRef.current = element;
+	}, [] );
+
+	const contextValue = useMemo(
+		() => ( { registerTitle } ),
+		[ registerTitle ]
+	);
+
+	useEffect( () => {
+		const titleElement = titleElementRef.current;
+
+		if ( ! titleElement ) {
+			throw new Error(
+				'Popover: Missing <Popover.Title>. ' +
+					'For accessibility, every popover 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(
+				'Popover: <Popover.Title> cannot be empty. ' +
+					'Provide meaningful text content for the popover title.'
+			);
+		}
+	}, [] );
+
+	return (
+		<PopoverValidationContext.Provider value={ contextValue }>
+			{ children }
+		</PopoverValidationContext.Provider>
+	);
+}
+
+function PopoverValidationProviderProd( {
+	children,
+}: {
+	children: React.ReactNode;
+} ) {
+	return <>{ children }</>;
+}
+
+/**
+ * Provider component that validates Popover.Title presence in development mode.
+ * In production, this component is a no-op and just renders children.
+ */
+export const PopoverValidationProvider = VALIDATION_ENABLED
+	? PopoverValidationProviderDev
+	: PopoverValidationProviderProd;

package/src/popover/description.tsx

@@ -0,0 +1,34 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import clsx from 'clsx';
+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 popover content.
+ *
+ * The rendered element is linked to the popup via `aria-describedby`.
+ * Uses the `body-md` text variant by default.
+ */
+const Description = forwardRef< HTMLParagraphElement, DescriptionProps >(
+	function PopoverDescription(
+		{ className, children, render, ...props },
+		ref
+	) {
+		return (
+			<Text
+				ref={ ref }
+				variant="body-md"
+				render={
+					<_Popover.Description render={ render } { ...props } />
+				}
+				className={ clsx( styles.description, className ) }
+			>
+				{ children }
+			</Text>
+		);
+	}
+);
+
+export { Description };

package/src/popover/index.ts

@@ -0,0 +1,9 @@
+import { Arrow } from './arrow';
+import { Close } from './close';
+import { Description } from './description';
+import { Popup } from './popup';
+import { Root } from './root';
+import { Title } from './title';
+import { Trigger } from './trigger';
+
+export { Arrow, Close, Description, Popup, Root, Title, Trigger };