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

package/src/card/title.tsx

@@ -1,5 +1,6 @@
-import { mergeProps, useRender } from '@base-ui/react';
 import { forwardRef } from '@wordpress/element';
+import clsx from 'clsx';
+import { Text } from '../text';
 import styles from './style.module.css';
 import type { TitleProps } from './types';
 
@@ -8,15 +9,15 @@ import type { TitleProps } from './types';
  * 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( { className, render, children, ...props }, ref ) {
+		return (
+			<Text
+				variant="heading-lg"
+				render={ render ?? <div ref={ ref } { ...props } /> }
+				className={ clsx( styles.title, className ) }
+			>
+				{ 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 };

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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import * as Card from '../../card';
 import * as CollapsibleCard from '../index';
+import { Stack } from '../../stack';
 
 /**
  * Temporary text component for story examples. This will be replaced by an
@@ -11,7 +12,7 @@ function Text( { children }: { children: React.ReactNode } ) {
 		<p
 			style={ {
 				margin: 0,
-				fontFamily: [ 'var(--wp', 'ds-font-family-body)' ].join( '' ),
+				fontFamily: 'var(--wpds-font-family-body)',
 				fontSize: 'var(--wpds-font-size-md)',
 				fontWeight: 'var(--wpds-font-weight-regular)',
 				lineHeight: 'var(--wpds-font-line-height-sm)',
@@ -29,6 +30,7 @@ const meta: Meta< typeof CollapsibleCard.Root > = {
 	component: CollapsibleCard.Root,
 	subcomponents: {
 		'CollapsibleCard.Header': CollapsibleCard.Header,
+		'CollapsibleCard.HeaderDescription': CollapsibleCard.HeaderDescription,
 		'CollapsibleCard.Content': CollapsibleCard.Content,
 	},
 };
@@ -105,6 +107,102 @@ export const Disabled: Story = {
 	},
 };
 
+/**
+ * Multiple collapsible cards stacked vertically, simulating a typical
+ * settings-panel or FAQ-style layout.
+ */
+export const Stacked: Story = {
+	parameters: { controls: { disable: true } },
+	render: () => (
+		<div
+			style={ {
+				display: 'flex',
+				flexDirection: 'column',
+				gap: 'var(--wpds-dimension-gap-lg)',
+			} }
+		>
+			{ [
+				'General',
+				'Advanced',
+				'Accessibility',
+				'Performance',
+				'Privacy',
+				'Notifications',
+			].map( ( title ) => (
+				<CollapsibleCard.Root key={ title }>
+					<CollapsibleCard.Header>
+						<Card.Title>{ title }</Card.Title>
+					</CollapsibleCard.Header>
+					<CollapsibleCard.Content>
+						<Text>
+							Configure all { title.toLowerCase() } settings for
+							your site. Changes here affect how your site behaves
+							across all pages and posts.
+						</Text>
+						<Text>
+							Review each option carefully before saving. Some
+							changes may require a page reload to take effect.
+							Hover over individual options for more details about
+							what they control.
+						</Text>
+						<Text>
+							If you&apos;re unsure about a setting, you can
+							always reset to defaults using the button at the
+							bottom of this section. Your previous configuration
+							will be saved as a backup.
+						</Text>
+					</CollapsibleCard.Content>
+				</CollapsibleCard.Root>
+			) ) }
+		</div>
+	),
+};
+
+/**
+ * A collapsible card with a `HeaderDescription` that provides supplementary
+ * information (e.g. status, summary) as an `aria-describedby` relationship.
+ */
+export const WithHeaderDescription: Story = {
+	// `defaultOpen` (uncontrolled) and `open` (controlled) should not be
+	// used together — disable the `open` control to avoid confusion.
+	argTypes: { open: { control: false } },
+	args: {
+		defaultOpen: true,
+	},
+	render: ( { open, defaultOpen, onOpenChange, disabled, ...restArgs } ) => (
+		<CollapsibleCard.Root
+			open={ open }
+			defaultOpen={ defaultOpen }
+			onOpenChange={ onOpenChange }
+			disabled={ disabled }
+			{ ...restArgs }
+		>
+			<CollapsibleCard.Header>
+				<Stack justify="space-between">
+					<Card.Title>Settings</Card.Title>
+					<CollapsibleCard.HeaderDescription>
+						<span
+							style={ {
+								fontSize: 'var(--wpds-font-size-sm)',
+								color: 'var(--wpds-color-fg-content-neutral-weak)',
+							} }
+						>
+							3 items configured
+						</span>
+					</CollapsibleCard.HeaderDescription>
+				</Stack>
+			</CollapsibleCard.Header>
+			<CollapsibleCard.Content>
+				<Text>
+					The header description provides supplementary context to the
+					trigger button. Assistive technologies will announce the
+					description alongside the button label.
+				</Text>
+			</CollapsibleCard.Content>
+		</CollapsibleCard.Root>
+	),
+};
+
 /**
  * Visual comparison: a `CollapsibleCard` (open) next to a regular `Card`
  * to verify identical spacing and layout.

package/src/collapsible-card/style.module.css

@@ -6,7 +6,7 @@
 		min-width: 0;
 	}
 
-	.header-trigger-wrapper {
+	.header-trigger-positioner {
 		flex-shrink: 0;
 		align-self: center;
 		/* Prevent the trigger from making the header taller than its content,
@@ -15,7 +15,9 @@
 		overflow: visible;
 	}
 
-	.header-trigger {
+	.header-trigger-wrapper {
+		display: flex;
+
 		/* Offset by half the button's own height so it visually centers
 		   at the wrapper's midpoint (which `align-self: center` places at
 		   the vertical center of the header). */
@@ -25,6 +27,12 @@
 		border-radius: var(--wpds-border-radius-sm);
 	}
 
+	.header-trigger {
+		@media not (prefers-reduced-motion) {
+			transition: rotate 0.15s ease-out;
+		}
+	}
+
 	.header[data-panel-open] .header-trigger {
 		rotate: 180deg;
 	}
@@ -33,9 +41,33 @@
 	.header[data-disabled] .header-trigger {
 		color: var(--wpds-color-fg-interactive-neutral-disabled);
 	}
+
+	.content {
+		height: var(--collapsible-panel-height);
+		overflow: hidden;
+		margin-block-start: var(--wp-ui-card-header-content-margin);
+
+		&[hidden]:not([hidden="until-found"]) {
+			display: none;
+		}
+
+		&[data-starting-style],
+		&[data-ending-style] {
+			height: 0;
+		}
+
+		@media not (prefers-reduced-motion) {
+			transition: all 150ms ease-out;
+		}
+	}
+
 }
 
 @layer wp-ui-compositions {
+	.content-inner {
+		padding-block-start: 0;
+	}
+
 	.header {
 		display: flex;
 		flex-direction: row;

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

@@ -53,9 +53,7 @@ describe( 'CollapsibleCard', () => {
 				</CollapsibleCard.Root>
 			);
 
-			expect(
-				screen.queryByText( 'Hidden content' )
-			).not.toBeInTheDocument();
+			expect( screen.getByText( 'Hidden content' ) ).not.toBeVisible();
 		} );
 
 		it( 'shows content when defaultOpen is true', () => {
@@ -87,9 +85,7 @@ describe( 'CollapsibleCard', () => {
 				</CollapsibleCard.Root>
 			);
 
-			expect(
-				screen.queryByText( 'Toggle content' )
-			).not.toBeInTheDocument();
+			expect( screen.getByText( 'Toggle content' ) ).not.toBeVisible();
 
 			await user.click(
 				screen.getByRole( 'button', {
@@ -107,9 +103,7 @@ describe( 'CollapsibleCard', () => {
 				} )
 			);
 
-			expect(
-				screen.queryByText( 'Toggle content' )
-			).not.toBeInTheDocument();
+			expect( screen.getByText( 'Toggle content' ) ).not.toBeVisible();
 		} );
 
 		it( 'calls onOpenChange when toggled', async () => {
@@ -184,4 +178,97 @@ describe( 'CollapsibleCard', () => {
 			).toBeVisible();
 		} );
 	} );
+
+	describe( 'HeaderDescription', () => {
+		it( 'sets aria-describedby on the trigger pointing to the description', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Settings</Card.Title>
+						<CollapsibleCard.HeaderDescription data-testid="desc">
+							3 errors
+						</CollapsibleCard.HeaderDescription>
+					</CollapsibleCard.Header>
+					<CollapsibleCard.Content>
+						<p>Content</p>
+					</CollapsibleCard.Content>
+				</CollapsibleCard.Root>
+			);
+
+			const trigger = screen.getByRole( 'button', {
+				name: 'Settings',
+			} );
+			const descriptionElement = screen.getByTestId( 'desc' );
+
+			expect( descriptionElement ).toHaveAttribute( 'id' );
+			expect( trigger ).toHaveAttribute(
+				'aria-describedby',
+				descriptionElement.id
+			);
+		} );
+
+		it( 'marks the description content as aria-hidden', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Settings</Card.Title>
+						<CollapsibleCard.HeaderDescription data-testid="desc">
+							<span>Status: OK</span>
+						</CollapsibleCard.HeaderDescription>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			const descriptionWrapper = screen.getByTestId( 'desc' );
+			expect( descriptionWrapper ).toHaveAttribute(
+				'aria-hidden',
+				'true'
+			);
+		} );
+
+		it( 'does not set aria-describedby when HeaderDescription is absent', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			const trigger = screen.getByRole( 'button', { name: 'Title' } );
+			expect( trigger ).not.toHaveAttribute( 'aria-describedby' );
+		} );
+
+		it( 'forwards ref on HeaderDescription', () => {
+			const descRef = createRef< HTMLDivElement >();
+
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+						<CollapsibleCard.HeaderDescription ref={ descRef }>
+							Description
+						</CollapsibleCard.HeaderDescription>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			expect( descRef.current ).toBeInstanceOf( HTMLDivElement );
+		} );
+
+		it( 'renders description content visually', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+						<CollapsibleCard.HeaderDescription>
+							Badge content
+						</CollapsibleCard.HeaderDescription>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			expect( screen.getByText( 'Badge content' ) ).toBeVisible();
+		} );
+	} );
 } );

package/src/collapsible-card/types.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { PanelProps } from '../collapsible/types';
 import type { ComponentProps } from '../utils/types';
 
 export interface RootProps extends ComponentProps< 'div' > {
@@ -36,9 +37,30 @@ export interface HeaderProps extends ComponentProps< 'div' > {
 	children?: ReactNode;
 }
 
+export interface HeaderDescriptionProps extends ComponentProps< 'div' > {
+	/**
+	 * Secondary content that describes the header trigger via
+	 * `aria-describedby`. Rendered visually but marked `aria-hidden`
+	 * so assistive technologies consume it only through the description
+	 * relationship, avoiding double announcements.
+	 *
+	 * Avoid interactive elements — the entire header is the toggle trigger.
+	 */
+	children?: ReactNode;
+}
+
 export interface ContentProps extends ComponentProps< 'div' > {
 	/**
 	 * The content to be rendered inside the collapsible content area.
 	 */
 	children?: ReactNode;
+	/**
+	 * Allows the browser’s built-in page search to find and expand the panel contents.
+	 *
+	 * Overrides the `keepMounted` prop and uses `hidden="until-found"`
+	 * to hide the element without removing it from the DOM.
+	 *
+	 * @default true
+	 */
+	hiddenUntilFound?: PanelProps[ 'hiddenUntilFound' ];
 }

package/src/dialog/action.tsx

@@ -8,11 +8,17 @@ import type { ActionProps } from './types';
  * Accepts all Button component props for styling.
  */
 const Action = forwardRef< HTMLButtonElement, ActionProps >(
-	function DialogAction( { render, ...props }, ref ) {
+	function DialogAction( { render, disabled, loading, ...props }, ref ) {
+		// Resolve `disabled` the same way Button does so that
+		// _Dialog.Close's internal useButton (which controls
+		// aria-disabled) stays in sync with the rendered Button.
+		const resolvedDisabled = disabled ?? loading;
+
 		return (
 			<_Dialog.Close
 				ref={ ref }
-				render={ <Button render={ render } /> }
+				render={ <Button render={ render } loading={ loading } /> }
+				disabled={ resolvedDisabled }
 				{ ...props }
 			/>
 		);

package/src/dialog/close-icon.tsx

@@ -22,6 +22,7 @@ const CloseIcon = forwardRef< HTMLButtonElement, CloseIconProps >(
 						{ ...props }
 						icon={ icon ?? close }
 						label={ label ?? __( 'Close' ) }
+						data-wp-ui-dialog-close-icon=""
 					/>
 				}
 			/>

package/src/dialog/popup.tsx

@@ -1,11 +1,13 @@
 import { Dialog as _Dialog } from '@base-ui/react/dialog';
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
 import {
 	type ThemeProvider as ThemeProviderType,
 	privateApis as themePrivateApis,
 } from '@wordpress/theme';
 import { unlock } from '../lock-unlock';
+import { useDeprioritizedInitialFocus } from '../utils/use-deprioritized-initial-focus';
 import { DialogValidationProvider } from './context';
 import styles from './style.module.css';
 import type { PopupProps } from './types';
@@ -13,25 +15,42 @@ import type { PopupProps } from './types';
 const ThemeProvider: typeof ThemeProviderType =
 	unlock( themePrivateApis ).ThemeProvider;
 
+const CLOSE_ICON_ATTR = 'data-wp-ui-dialog-close-icon';
+
 /**
  * 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 },
+	{
+		className,
+		size = 'medium',
+		initialFocus,
+		finalFocus,
+		children,
+		...props
+	},
 	ref
 ) {
+	const { resolvedInitialFocus, popupRef } = useDeprioritizedInitialFocus( {
+		initialFocus,
+		deprioritizedAttribute: CLOSE_ICON_ATTR,
+	} );
+	const mergedRef = useMergeRefs( [ ref, popupRef ] );
+
 	return (
 		<_Dialog.Portal>
 			<_Dialog.Backdrop className={ styles.backdrop } />
 			<ThemeProvider>
 				<_Dialog.Popup
-					ref={ ref }
+					ref={ mergedRef }
 					className={ clsx(
 						styles.popup,
 						className,
 						styles[ `is-${ size }` ]
 					) }
+					initialFocus={ resolvedInitialFocus }
+					finalFocus={ finalFocus }
 					{ ...props }
 				>
 					<DialogValidationProvider>