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

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,22 +15,67 @@
 		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). */
-		transform: translateY(-50%);
+		translate: 0 -50%;
+
+		/* For an outline that looks like `IconButton`'s */
+		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;
+	}
+
+	/* Simulate disabled button styles */
+	.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;
 		align-items: stretch;
 		gap: var(--wpds-dimension-gap-sm);
+		outline: none;
 
-		&:has(.header-trigger:not([data-disabled])) {
+		&:not([data-disabled]) {
 			cursor: var(--wpds-cursor-control);
 		}
 	}

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,13 +85,12 @@ describe( 'CollapsibleCard', () => {
 				</CollapsibleCard.Root>
 			);
 
-			expect(
-				screen.queryByText( 'Toggle content' )
-			).not.toBeInTheDocument();
+			expect( screen.getByText( 'Toggle content' ) ).not.toBeVisible();
 
 			await user.click(
 				screen.getByRole( 'button', {
-					name: 'Expand or collapse card',
+					name: 'Title',
+					expanded: false,
 				} )
 			);
 
@@ -101,38 +98,12 @@ describe( 'CollapsibleCard', () => {
 
 			await user.click(
 				screen.getByRole( 'button', {
-					name: 'Expand or collapse card',
+					name: 'Title',
+					expanded: true,
 				} )
 			);
 
-			expect(
-				screen.queryByText( 'Toggle content' )
-			).not.toBeInTheDocument();
-		} );
-
-		it( 'toggles content when clicking the header area', async () => {
-			const user = userEvent.setup();
-
-			render(
-				<CollapsibleCard.Root>
-					<CollapsibleCard.Header>
-						<Card.Title>Header click test</Card.Title>
-					</CollapsibleCard.Header>
-					<CollapsibleCard.Content>
-						<p>Header toggled content</p>
-					</CollapsibleCard.Content>
-				</CollapsibleCard.Root>
-			);
-
-			expect(
-				screen.queryByText( 'Header toggled content' )
-			).not.toBeInTheDocument();
-
-			await user.click( screen.getByText( 'Header click test' ) );
-
-			expect(
-				screen.getByText( 'Header toggled content' )
-			).toBeVisible();
+			expect( screen.getByText( 'Toggle content' ) ).not.toBeVisible();
 		} );
 
 		it( 'calls onOpenChange when toggled', async () => {
@@ -152,7 +123,8 @@ describe( 'CollapsibleCard', () => {
 
 			await user.click(
 				screen.getByRole( 'button', {
-					name: 'Expand or collapse card',
+					name: 'Title',
+					expanded: false,
 				} )
 			);
 
@@ -179,7 +151,8 @@ describe( 'CollapsibleCard', () => {
 
 			await user.click(
 				screen.getByRole( 'button', {
-					name: 'Expand or collapse card',
+					name: 'Title',
+					expanded: true,
 				} )
 			);
 
@@ -188,7 +161,7 @@ describe( 'CollapsibleCard', () => {
 	} );
 
 	describe( 'trigger', () => {
-		it( 'renders a toggle button', () => {
+		it( 'renders the header as a toggle button', () => {
 			render(
 				<CollapsibleCard.Root>
 					<CollapsibleCard.Header>
@@ -199,9 +172,103 @@ describe( 'CollapsibleCard', () => {
 
 			expect(
 				screen.getByRole( 'button', {
-					name: 'Expand or collapse card',
+					name: 'Title',
+					expanded: false,
 				} )
 			).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>

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

@@ -73,34 +73,6 @@ export const _Default: Story = {
 	},
 };
 
-/**
- * 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( {

package/src/dialog/style.module.css

@@ -29,7 +29,7 @@
 		z-index: var(--wp-ui-dialog-z-index, initial);
 		transform: translate(-50%, -50%);
 		box-sizing: border-box;
-		min-width: 320px;
+		min-width: var(--wpds-dimension-surface-width-sm);
 		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);
@@ -61,19 +61,19 @@
 		}
 
 		@media (min-width: 480px) {
-			min-width: 384px;
+			min-width: var(--wpds-dimension-surface-width-md);
 		}
 
 		&.is-small {
-			max-width: 384px;
+			max-width: var(--wpds-dimension-surface-width-md);
 		}
 
 		&.is-medium {
-			max-width: 512px;
+			max-width: var(--wpds-dimension-surface-width-lg);
 		}
 
 		&.is-large {
-			max-width: 840px;
+			max-width: var(--wpds-dimension-surface-width-2xl);
 		}
 
 		&.is-stretch {