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

package/src/alert-dialog/trigger.tsx

@@ -0,0 +1,15 @@
+import { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
+import { forwardRef } from '@wordpress/element';
+
+import type { TriggerProps } from './types';
+
+/**
+ * Renders a button that opens the alert dialog when clicked.
+ */
+const Trigger = forwardRef< HTMLButtonElement, TriggerProps >(
+	function AlertDialogTrigger( props, ref ) {
+		return <_AlertDialog.Trigger ref={ ref } { ...props } />;
+	}
+);
+
+export { Trigger };

package/src/alert-dialog/types.ts

@@ -0,0 +1,119 @@
+import type { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
+import type { ReactNode } from 'react';
+
+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<
+		_AlertDialog.Root.Props,
+		'open' | 'onOpenChange' | 'defaultOpen'
+	> {
+	/**
+	 * The content to be rendered inside the component. Typically includes
+	 * `AlertDialog.Trigger` and `AlertDialog.Popup`.
+	 */
+	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' > {
+	/**
+	 * A parent element to render the portal into.
+	 */
+	container?: _AlertDialog.Portal.Props[ 'container' ];
+
+	/**
+	 * The semantic intent of the dialog, which determines its styling.
+	 *
+	 * All intents use `role="alertdialog"`, are always modal, and block
+	 * backdrop click dismissal. Escape key and the cancel/confirm buttons
+	 * still dismiss the dialog.
+	 *
+	 * - `'default'`: Standard confirmation dialog for reversible actions.
+	 * - `'irreversible'`: Confirmation dialog for irreversible actions that
+	 *   cannot be undone. The confirm button uses error/danger coloring.
+	 *
+	 * @default 'default'
+	 */
+	intent?: 'default' | 'irreversible';
+
+	/**
+	 * The title displayed in the dialog header. This serves as both the
+	 * visible heading and the accessible label (`aria-labelledby`) for the
+	 * dialog. Must be a plain string to ensure a predictable accessible name.
+	 */
+	title: string;
+
+	/**
+	 * 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.
+	 */
+	description?: string;
+
+	/**
+	 * Optional body content displayed between the description and the
+	 * action buttons. Use for supplementary details or form fields.
+	 */
+	children?: ReactNode;
+
+	/**
+	 * Custom text for the confirm button.
+	 *
+	 * @default 'OK'
+	 */
+	confirmButtonText?: string;
+
+	/**
+	 * Custom text for the cancel button.
+	 *
+	 * @default 'Cancel'
+	 */
+	cancelButtonText?: string;
+}

package/src/badge/badge.tsx

@@ -1,29 +1,26 @@
-import { useRender, mergeProps } from '@base-ui/react';
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
 import { type BadgeProps } from './types';
 import styles from './style.module.css';
+import { Text } from '../text';
 
 /**
  * A badge component for displaying labels with semantic intent.
  */
 export const Badge = forwardRef< HTMLSpanElement, BadgeProps >( function Badge(
-	{ children, intent = 'none', render, className, ...props },
+	{ intent = 'none', className, ...props },
 	ref
 ) {
-	const element = useRender( {
-		render,
-		defaultTagName: 'span',
-		ref,
-		props: mergeProps< 'span' >( props, {
-			className: clsx(
+	return (
+		<Text
+			ref={ ref }
+			className={ clsx(
 				styles.badge,
 				styles[ `is-${ intent }-intent` ],
 				className
-			),
-			children,
-		} ),
-	} );
-
-	return element;
+			) }
+			{ ...props }
+			variant="body-sm"
+		/>
+	);
 } );

package/src/badge/style.module.css

@@ -5,10 +5,6 @@
 		padding-inline: var(--wpds-dimension-padding-sm);
 		padding-block: var(--wpds-dimension-padding-xs);
 		border-radius: var(--wpds-border-radius-lg);
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-sm);
-		font-weight: var(--wpds-font-weight-regular);
-		line-height: var(--wpds-font-line-height-xs);
 	}
 
 	.is-high-intent {

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

@@ -20,7 +20,7 @@
 		--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-font-size: var(--wpds-typography-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 */
@@ -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-typography-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;
@@ -44,12 +48,13 @@
 		border-radius: var(--wpds-border-radius-sm);
 		background-color: var(--wp-ui-button-background-color);
 		background-clip: padding-box;
-		font-family: var(--wpds-font-family-body);
+		font-family: var(--wpds-typography-font-family-body);
 		font-size: var(--wp-ui-button-font-size);
 		font-weight: var(--wp-ui-button-font-weight);
-		line-height: var(--wpds-font-line-height-sm);
+		line-height: var(--wpds-typography-line-height-sm);
 		text-decoration: none;
 		color: var(--wp-ui-button-foreground-color);
+		cursor: var(--wpds-cursor-control);
 
 		@media not ( prefers-reduced-motion ) {
 			transition: color 0.1s ease-out;
@@ -61,6 +66,7 @@
 
 		/* Use pointer cursor for buttons that are links */
 		&[href] {
+			/* stylelint-disable-next-line declaration-property-value-disallowed-list -- Links should always use pointer. */
 			cursor: pointer;
 		}
 

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

@@ -10,10 +10,10 @@ function Text( { children }: { children: React.ReactNode } ) {
 		<p
 			style={ {
 				margin: 0,
-				fontFamily: [ 'var(--wp', 'ds-font-family-body)' ].join( '' ),
-				fontSize: 'var(--wpds-font-size-md)',
-				fontWeight: 'var(--wpds-font-weight-regular)',
-				lineHeight: 'var(--wpds-font-line-height-sm)',
+				fontFamily: 'var(--wpds-typography-font-family-body)',
+				fontSize: 'var(--wpds-typography-font-size-md)',
+				fontWeight: 'var(--wpds-typography-font-weight-regular)',
+				lineHeight: 'var(--wpds-typography-line-height-sm)',
 				textWrap: 'pretty',
 				color: 'var(--wpds-color-fg-content-neutral-weak)',
 			} }
@@ -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

@@ -4,12 +4,15 @@
 	.root {
 		--wp-ui-card-padding: var(--wpds-dimension-padding-2xl);
 		--wp-ui-card-header-content-gap: var(--wpds-dimension-gap-xl);
+		--wp-ui-card-header-content-margin: calc(var(--wp-ui-card-header-content-gap) - var(--wp-ui-card-padding));
 
 		display: flex;
 		flex-direction: column;
 		border: 1px solid var(--wpds-color-stroke-surface-neutral-weak);
 		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
@@ -28,20 +31,11 @@
 	/* Custom vertical gap between header and content */
 	.header + .content {
 		padding-block-start: 0;
-		margin-block-start: calc(var(--wp-ui-card-header-content-gap) - var(--wp-ui-card-padding));
+		margin-block-start: var(--wp-ui-card-header-content-margin);
 	}
 
 	.fullbleed {
 		margin-inline: calc(-1 * var(--wp-ui-card-padding));
 		width: calc(100% + 2 * var(--wp-ui-card-padding));
 	}
-
-	.title {
-		margin: 0;
-		font-family: var(--wpds-font-family-heading);
-		font-size: var(--wpds-font-size-lg);
-		font-weight: var(--wpds-font-weight-medium);
-		line-height: var(--wpds-font-line-height-sm);
-		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>
@@ -92,5 +91,22 @@ describe( 'Card', () => {
 				screen.getByRole( 'heading', { level: 2, name: 'Heading' } )
 			).toBeVisible();
 		} );
+
+		it( 'forwards ref to custom Title render element', () => {
+			const titleRef = createRef< HTMLHeadingElement >();
+
+			render(
+				<Card.Root>
+					<Card.Header>
+						<Card.Title ref={ titleRef } render={ <h3 /> }>
+							Heading
+						</Card.Title>
+					</Card.Header>
+				</Card.Root>
+			);
+
+			expect( titleRef.current ).toBeInstanceOf( HTMLHeadingElement );
+			expect( titleRef.current?.tagName ).toBe( 'H3' );
+		} );
 	} );
 } );

package/src/card/title.tsx

@@ -1,22 +1,24 @@
-import { mergeProps, useRender } from '@base-ui/react';
 import { forwardRef } from '@wordpress/element';
-import styles from './style.module.css';
+import { Text } from '../text';
 import type { TitleProps } from './types';
 
+const DEFAULT_TAG = <div />;
+
 /**
  * The title for a card. Renders as a `<div>` by default — use the `render`
  * prop to swap in a semantic heading element when appropriate.
  */
 export const Title = forwardRef< HTMLDivElement, TitleProps >(
-	function CardTitle( { render, ...props }, ref ) {
-		const element = useRender( {
-			defaultTagName: 'div',
-			render,
-			ref,
-			// TODO: use `Text` component instead, when ready
-			props: mergeProps< 'div' >( { className: styles.title }, props ),
-		} );
-
-		return element;
+	function CardTitle( { render = DEFAULT_TAG, children, ...props }, ref ) {
+		return (
+			<Text
+				ref={ ref }
+				variant="heading-lg"
+				render={ render }
+				{ ...props }
+			>
+				{ children }
+			</Text>
+		);
 	}
 );

package/src/collapsible-card/content.tsx

@@ -1,6 +1,8 @@
 import { forwardRef } from '@wordpress/element';
+import clsx from 'clsx';
 import * as Card from '../card';
 import * as Collapsible from '../collapsible';
+import styles from './style.module.css';
 import type { ContentProps } from './types';
 
 /**
@@ -8,13 +10,24 @@ import type { ContentProps } from './types';
  * visible when expanded.
  */
 export const Content = forwardRef< HTMLDivElement, ContentProps >(
-	function CollapsibleCardContent( { render, ...restProps }, ref ) {
+	function CollapsibleCardContent(
+		{ className, render, children, hiddenUntilFound = true, ...restProps },
+		ref
+	) {
 		return (
 			<Collapsible.Panel
 				ref={ ref }
-				render={ <Card.Content render={ render } /> }
+				className={ clsx( styles.content, className ) }
+				hiddenUntilFound={ hiddenUntilFound }
 				{ ...restProps }
-			/>
+			>
+				<Card.Content
+					className={ styles[ 'content-inner' ] }
+					render={ render }
+				>
+					{ children }
+				</Card.Content>
+			</Collapsible.Panel>
 		);
 	}
 );

package/src/collapsible-card/context.ts

@@ -0,0 +1,7 @@
+import { createContext } from '@wordpress/element';
+
+export const HeaderDescriptionIdContext = createContext< {
+	setDescriptionId: ( id: string | undefined ) => void;
+} >( {
+	setDescriptionId: () => {},
+} );

package/src/collapsible-card/header-description.tsx

@@ -0,0 +1,43 @@
+import { forwardRef, useContext, useEffect, useId } from '@wordpress/element';
+import { HeaderDescriptionIdContext } from './context';
+import type { HeaderDescriptionProps } from './types';
+
+/**
+ * Secondary content placed in the collapsible card header that describes
+ * the trigger button via `aria-describedby`. Use it for supplementary
+ * information such as status badges or summary values.
+ *
+ * The content is visually rendered but marked `aria-hidden` so that
+ * assistive technologies consume it only through the `aria-describedby`
+ * relationship on the trigger, avoiding double announcements.
+ *
+ * Avoid interactive elements (buttons, links, inputs) inside this
+ * component — the entire header is the toggle trigger.
+ */
+export const HeaderDescription = forwardRef<
+	HTMLDivElement,
+	HeaderDescriptionProps
+>( function CollapsibleCardHeaderDescription(
+	{ children, className, ...restProps },
+	ref
+) {
+	const descriptionId = useId();
+	const { setDescriptionId } = useContext( HeaderDescriptionIdContext );
+
+	useEffect( () => {
+		setDescriptionId( descriptionId );
+		return () => setDescriptionId( undefined );
+	}, [ descriptionId, setDescriptionId ] );
+
+	return (
+		<div
+			ref={ ref }
+			id={ descriptionId }
+			aria-hidden="true"
+			className={ className }
+			{ ...restProps }
+		>
+			{ children }
+		</div>
+	);
+} );

package/src/collapsible-card/header.tsx

@@ -1,11 +1,12 @@
 import clsx from 'clsx';
-import { forwardRef } from '@wordpress/element';
+import { forwardRef, useMemo, useState } from '@wordpress/element';
 import { chevronDown } from '@wordpress/icons';
 import * as Card from '../card';
 import * as Collapsible from '../collapsible';
 import { Icon } from '../icon';
 import styles from './style.module.css';
 import focusStyles from '../utils/css/focus.module.css';
+import { HeaderDescriptionIdContext } from './context';
 import type { HeaderProps } from './types';
 
 /**
@@ -22,32 +23,54 @@ export const Header = forwardRef< HTMLDivElement, HeaderProps >(
 		{ children, className, render, ...restProps },
 		ref
 	) {
+		const [ descriptionId, setDescriptionId ] = useState< string >();
+
+		const contextValue = useMemo(
+			() => ( { setDescriptionId } ),
+			[ setDescriptionId ]
+		);
+
 		return (
-			<Collapsible.Trigger
-				className={ clsx( styles.header, className ) }
-				render={
-					<Card.Header
-						ref={ ref }
-						render={ render }
-						{ ...restProps }
-					/>
-				}
-				nativeButton={ false }
-			>
-				<div className={ styles[ 'header-content' ] }>{ children }</div>
-				<div className={ styles[ 'header-trigger-wrapper' ] }>
-					<Icon
-						icon={ chevronDown }
+			<HeaderDescriptionIdContext.Provider value={ contextValue }>
+				<Collapsible.Trigger
+					className={ clsx( styles.header, className ) }
+					render={
+						<Card.Header
+							ref={ ref }
+							render={ render }
+							{ ...restProps }
+						/>
+					}
+					nativeButton={ false }
+					aria-describedby={ descriptionId }
+				>
+					<div className={ styles[ 'header-content' ] }>
+						{ children }
+					</div>
+					<div
 						className={ clsx(
-							styles[ 'header-trigger' ],
-							// While the interactive trigger element is the whole header,
-							// the focus ring will be displayed only on the icon to visually
-							// emulate it being the button.
-							focusStyles[ 'outset-ring--focus-parent-visible' ]
+							styles[ 'header-trigger-positioner' ]
 						) }
-					/>
-				</div>
-			</Collapsible.Trigger>
+					>
+						<div
+							className={ clsx(
+								styles[ 'header-trigger-wrapper' ],
+								// While the interactive trigger element is the whole header,
+								// the focus ring will be displayed only on the icon to visually
+								// emulate it being the button.
+								focusStyles[
+									'outset-ring--focus-parent-visible'
+								]
+							) }
+						>
+							<Icon
+								icon={ chevronDown }
+								className={ styles[ 'header-trigger' ] }
+							/>
+						</div>
+					</div>
+				</Collapsible.Trigger>
+			</HeaderDescriptionIdContext.Provider>
 		);
 	}
 );

package/src/collapsible-card/index.ts

@@ -1,5 +1,6 @@
 import { Root } from './root';
 import { Header } from './header';
+import { HeaderDescription } from './header-description';
 import { Content } from './content';
 
-export { Root, Header, Content };
+export { Root, Header, HeaderDescription, Content };