@wordpress/ui 0.9.1-next.v.202603161435.0 → 0.11.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,10 +12,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)',
 			} }
@@ -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-typography-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,43 @@ 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,
+		container,
+		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.Portal container={ container }>
 			<_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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useId, useState } from '@wordpress/element';
 import type { ComponentProps } from 'react';
+import { VisuallyHidden } from '../../visually-hidden';
 import * as Dialog from '../index';
 
 const meta: Meta< typeof Dialog.Root > = {
@@ -73,34 +74,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( {
@@ -189,3 +162,35 @@ export const WithCustomZIndex: Story = {
 	..._Default,
 	name: 'With Custom z-index',
 };
+
+/**
+ * A dialog with a visually hidden title. The title is still present in the
+ * DOM for `aria-labelledby`, but is not visible to sighted users.
+ *
+ * Use `<VisuallyHidden render={ <Dialog.Title /> }>` so that `Dialog.Title`
+ * keeps its `<h2>` element while being visually hidden.
+ */
+export const WithVisuallyHiddenTitle: Story = {
+	args: {
+		children: (
+			<>
+				<Dialog.Trigger>Open Dialog</Dialog.Trigger>
+				<Dialog.Popup>
+					<Dialog.Header>
+						<VisuallyHidden render={ <Dialog.Title /> }>
+							Accessible dialog heading
+						</VisuallyHidden>
+						<Dialog.CloseIcon />
+					</Dialog.Header>
+					<p>
+						This dialog has a visually hidden title. Inspect the DOM
+						or use a screen reader to verify the heading is present.
+					</p>
+					<Dialog.Footer>
+						<Dialog.Action>Got it</Dialog.Action>
+					</Dialog.Footer>
+				</Dialog.Popup>
+			</>
+		),
+	},
+};

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);
@@ -37,9 +37,9 @@
 		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);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-md);
+		line-height: var(--wpds-typography-line-height-md);
 		color: var(--wpds-color-fg-content-neutral);
 
 		&[data-starting-style],
@@ -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 {
@@ -92,17 +92,21 @@
 
 	.header {
 		display: flex;
-		justify-content: space-between;
 		align-items: center;
+		gap: var(--wpds-dimension-gap-sm);
 		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);
+		margin-inline-end: auto;
+
+		/* Workaround: the GCD shorthand `margin` overrides the longhand above.
+		 * Keep both so the layout survives GCD removal. */
+		--_gcd-heading-margin: 0 auto 0 0;
+
+		&:dir(rtl) {
+			--_gcd-heading-margin: 0 0 0 auto;
+		}
 	}
 
 	.footer {