@wordpress/ui 0.9.1-next.v.202603102151.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/index.ts

@@ -0,0 +1,5 @@
+import { Panel } from './panel';
+import { Root } from './root';
+import { Trigger } from './trigger';
+
+export { Root, Trigger, Panel };

package/src/collapsible/panel.tsx

@@ -0,0 +1,16 @@
+import { Collapsible as _Collapsible } from '@base-ui/react/collapsible';
+import { forwardRef } from '@wordpress/element';
+import type { PanelProps } from './types';
+
+/**
+ * A panel with the collapsible contents. Hidden when collapsed, visible
+ * when expanded.
+ *
+ * `Collapsible` is a collection of React components that combine to render
+ * a collapsible panel controlled by a button.
+ */
+export const Panel = forwardRef< HTMLDivElement, PanelProps >(
+	function CollapsiblePanel( props, forwardedRef ) {
+		return <_Collapsible.Panel ref={ forwardedRef } { ...props } />;
+	}
+);

package/src/collapsible/root.tsx

@@ -0,0 +1,15 @@
+import { Collapsible as _Collapsible } from '@base-ui/react/collapsible';
+import { forwardRef } from '@wordpress/element';
+import type { RootProps } from './types';
+
+/**
+ * Groups all parts of the collapsible.
+ *
+ * `Collapsible` is a collection of React components that combine to render
+ * a collapsible panel controlled by a button.
+ */
+export const Root = forwardRef< HTMLDivElement, RootProps >(
+	function CollapsibleRoot( props, forwardedRef ) {
+		return <_Collapsible.Root ref={ forwardedRef } { ...props } />;
+	}
+);

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

@@ -0,0 +1,108 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from '@wordpress/element';
+import * as Collapsible from '../index';
+
+const meta: Meta< typeof Collapsible.Root > = {
+	title: 'Design System/Components/Collapsible',
+	component: Collapsible.Root,
+	subcomponents: {
+		'Collapsible.Trigger': Collapsible.Trigger,
+		'Collapsible.Panel': Collapsible.Panel,
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof Collapsible.Root >;
+
+export const Default: Story = {
+	args: {
+		children: (
+			<>
+				<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+				<Collapsible.Panel>
+					<p>Collapsible content here.</p>
+				</Collapsible.Panel>
+			</>
+		),
+	},
+};
+
+export const DefaultOpen: Story = {
+	argTypes: { open: { control: false } },
+	args: {
+		defaultOpen: true,
+		children: (
+			<>
+				<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+				<Collapsible.Panel>
+					<p>This panel is open by default.</p>
+				</Collapsible.Panel>
+			</>
+		),
+	},
+};
+
+export const Disabled: Story = {
+	args: {
+		disabled: true,
+		children: (
+			<>
+				<Collapsible.Trigger>Toggle (disabled)</Collapsible.Trigger>
+				<Collapsible.Panel>
+					<p>This content cannot be toggled.</p>
+				</Collapsible.Panel>
+			</>
+		),
+	},
+};
+
+/**
+ * When `hiddenUntilFound` is set on `Collapsible.Panel`, the collapsed content
+ * remains in the DOM using the `hidden="until-found"` HTML attribute instead of
+ * being removed entirely. This lets the browser's native page search (Ctrl/Cmd+F)
+ * find text inside collapsed panels and automatically expand them to reveal the
+ * match — improving discoverability without sacrificing the collapsed layout.
+ */
+export const HiddenUntilFound: Story = {
+	render: function HiddenUntilFound() {
+		return (
+			<div>
+				<p>
+					Use the browser&apos;s find-in-page (Ctrl/Cmd+F) to search
+					for &quot;hidden treasure&quot;. The collapsed panel will
+					automatically expand to reveal the match.
+				</p>
+				<Collapsible.Root>
+					<Collapsible.Trigger>Expand to reveal</Collapsible.Trigger>
+					<Collapsible.Panel hiddenUntilFound>
+						<p>
+							This is the hidden treasure that can be found via
+							the browser&apos;s built-in page search even while
+							the panel is collapsed.
+						</p>
+					</Collapsible.Panel>
+				</Collapsible.Root>
+			</div>
+		);
+	},
+};
+
+export const Controlled: Story = {
+	argTypes: {
+		open: { control: false },
+		defaultOpen: { control: false },
+	},
+	render: function Controlled() {
+		const [ open, setOpen ] = useState( false );
+		return (
+			<Collapsible.Root open={ open } onOpenChange={ setOpen }>
+				<Collapsible.Trigger>
+					{ open ? 'Close' : 'Open' }
+				</Collapsible.Trigger>
+				<Collapsible.Panel>
+					<p>Controlled collapsible panel.</p>
+				</Collapsible.Panel>
+			</Collapsible.Root>
+		);
+	},
+};

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

@@ -0,0 +1,228 @@
+import { render, screen } from '@testing-library/react';
+import { userEvent } from '@testing-library/user-event';
+import { createRef, useState } from '@wordpress/element';
+import * as Collapsible from '../index';
+
+function UncontrolledCollapsible( {
+	defaultOpen,
+	disabled,
+}: {
+	defaultOpen?: boolean;
+	disabled?: boolean;
+} ) {
+	return (
+		<Collapsible.Root defaultOpen={ defaultOpen } disabled={ disabled }>
+			<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+			<Collapsible.Panel>Panel content</Collapsible.Panel>
+		</Collapsible.Root>
+	);
+}
+
+function ControlledCollapsible( {
+	onOpenChange,
+}: {
+	onOpenChange?: ( open: boolean ) => void;
+} ) {
+	const [ open, setOpen ] = useState( false );
+	return (
+		<Collapsible.Root
+			open={ open }
+			onOpenChange={ ( nextOpen ) => {
+				setOpen( nextOpen );
+				onOpenChange?.( nextOpen );
+			} }
+		>
+			<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+			<Collapsible.Panel>Controlled panel</Collapsible.Panel>
+		</Collapsible.Root>
+	);
+}
+
+describe( 'Collapsible', () => {
+	describe( 'ref forwarding', () => {
+		it( 'forwards ref on Root', () => {
+			const ref = createRef< HTMLDivElement >();
+			render(
+				<Collapsible.Root ref={ ref }>
+					<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+					<Collapsible.Panel>Content</Collapsible.Panel>
+				</Collapsible.Root>
+			);
+			expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+		} );
+
+		it( 'forwards ref on Trigger', () => {
+			const ref = createRef< HTMLButtonElement >();
+			render(
+				<Collapsible.Root>
+					<Collapsible.Trigger ref={ ref }>
+						Toggle
+					</Collapsible.Trigger>
+					<Collapsible.Panel>Content</Collapsible.Panel>
+				</Collapsible.Root>
+			);
+			expect( ref.current ).toBeInstanceOf( HTMLButtonElement );
+		} );
+
+		it( 'forwards ref on Panel', () => {
+			const ref = createRef< HTMLDivElement >();
+			render(
+				<Collapsible.Root defaultOpen>
+					<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+					<Collapsible.Panel ref={ ref }>Content</Collapsible.Panel>
+				</Collapsible.Root>
+			);
+			expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+		} );
+	} );
+
+	describe( 'uncontrolled', () => {
+		it( 'is collapsed by default', () => {
+			render( <UncontrolledCollapsible /> );
+			expect(
+				screen.queryByText( 'Panel content' )
+			).not.toBeInTheDocument();
+		} );
+
+		it( 'shows panel when defaultOpen is true', () => {
+			render( <UncontrolledCollapsible defaultOpen /> );
+			expect( screen.getByText( 'Panel content' ) ).toBeVisible();
+		} );
+
+		it( 'toggles panel on trigger click', async () => {
+			const user = userEvent.setup();
+			render( <UncontrolledCollapsible /> );
+
+			expect(
+				screen.queryByText( 'Panel content' )
+			).not.toBeInTheDocument();
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Toggle' } )
+			);
+			expect( screen.getByText( 'Panel content' ) ).toBeVisible();
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Toggle' } )
+			);
+			expect(
+				screen.queryByText( 'Panel content' )
+			).not.toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'controlled', () => {
+		it( 'calls onOpenChange when toggled', async () => {
+			const onOpenChange = jest.fn();
+			const user = userEvent.setup();
+
+			render( <ControlledCollapsible onOpenChange={ onOpenChange } /> );
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Toggle' } )
+			);
+			expect( onOpenChange ).toHaveBeenCalledWith( true );
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Toggle' } )
+			);
+			expect( onOpenChange ).toHaveBeenCalledWith( false );
+		} );
+	} );
+
+	describe( 'disabled', () => {
+		it( 'does not toggle when disabled', async () => {
+			const user = userEvent.setup();
+			render( <UncontrolledCollapsible defaultOpen disabled /> );
+
+			expect( screen.getByText( 'Panel content' ) ).toBeVisible();
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Toggle' } )
+			);
+			expect( screen.getByText( 'Panel content' ) ).toBeVisible();
+		} );
+	} );
+
+	describe( 'render prop', () => {
+		it( 'supports render prop on Root', () => {
+			const ref = createRef< HTMLDivElement >();
+			render(
+				<Collapsible.Root ref={ ref } render={ <section /> }>
+					<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+					<Collapsible.Panel>Content</Collapsible.Panel>
+				</Collapsible.Root>
+			);
+			expect( ref.current?.tagName ).toBe( 'SECTION' );
+		} );
+
+		it( 'supports render prop on Trigger', () => {
+			render(
+				<Collapsible.Root>
+					<Collapsible.Trigger
+						nativeButton={ false }
+						render={ <div /> }
+					>
+						Toggle
+					</Collapsible.Trigger>
+					<Collapsible.Panel>Content</Collapsible.Panel>
+				</Collapsible.Root>
+			);
+			const trigger = screen.getByRole( 'button', { name: 'Toggle' } );
+			expect( trigger.tagName ).toBe( 'DIV' );
+		} );
+
+		it( 'supports render prop on Panel', () => {
+			const ref = createRef< HTMLDivElement >();
+			render(
+				<Collapsible.Root defaultOpen>
+					<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+					<Collapsible.Panel ref={ ref } render={ <section /> }>
+						Content
+					</Collapsible.Panel>
+				</Collapsible.Root>
+			);
+			expect( ref.current?.tagName ).toBe( 'SECTION' );
+		} );
+	} );
+
+	describe( 'custom className', () => {
+		it( 'applies className to Root', () => {
+			const ref = createRef< HTMLDivElement >();
+			render(
+				<Collapsible.Root ref={ ref } className="custom-root">
+					<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+					<Collapsible.Panel>Content</Collapsible.Panel>
+				</Collapsible.Root>
+			);
+			expect( ref.current ).toHaveClass( 'custom-root' );
+		} );
+
+		it( 'applies className to Trigger', () => {
+			render(
+				<Collapsible.Root>
+					<Collapsible.Trigger className="custom-trigger">
+						Toggle
+					</Collapsible.Trigger>
+					<Collapsible.Panel>Content</Collapsible.Panel>
+				</Collapsible.Root>
+			);
+			expect(
+				screen.getByRole( 'button', { name: 'Toggle' } )
+			).toHaveClass( 'custom-trigger' );
+		} );
+
+		it( 'applies className to Panel', () => {
+			const ref = createRef< HTMLDivElement >();
+			render(
+				<Collapsible.Root defaultOpen>
+					<Collapsible.Trigger>Toggle</Collapsible.Trigger>
+					<Collapsible.Panel ref={ ref } className="custom-panel">
+						Content
+					</Collapsible.Panel>
+				</Collapsible.Root>
+			);
+			expect( ref.current ).toHaveClass( 'custom-panel' );
+		} );
+	} );
+} );

package/src/collapsible/trigger.tsx

@@ -0,0 +1,15 @@
+import { Collapsible as _Collapsible } from '@base-ui/react/collapsible';
+import { forwardRef } from '@wordpress/element';
+import type { TriggerProps } from './types';
+
+/**
+ * A button that opens and closes the collapsible panel.
+ *
+ * `Collapsible` is a collection of React components that combine to render
+ * a collapsible panel controlled by a button.
+ */
+export const Trigger = forwardRef< HTMLButtonElement, TriggerProps >(
+	function CollapsibleTrigger( props, forwardedRef ) {
+		return <_Collapsible.Trigger ref={ forwardedRef } { ...props } />;
+	}
+);

package/src/collapsible/types.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import type { Collapsible as _Collapsible } from '@base-ui/react/collapsible';
+import type { ComponentProps } from '../utils/types';
+
+export type RootProps = ComponentProps< typeof _Collapsible.Root > & {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+};
+
+export type TriggerProps = ComponentProps< typeof _Collapsible.Trigger > & {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+};
+
+export type PanelProps = ComponentProps< typeof _Collapsible.Panel > & {
+	/**
+	 * The content to be rendered inside the component.
+	 */
+	children?: ReactNode;
+};

package/src/collapsible-card/content.tsx

@@ -1,6 +1,8 @@
-import { Collapsible } from '@base-ui/react/collapsible';
 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,12 +1,12 @@
-import { Collapsible } from '@base-ui/react/collapsible';
 import clsx from 'clsx';
-import type { MouseEvent } from 'react';
-import { forwardRef, useCallback, useRef } from '@wordpress/element';
-import { __ } from '@wordpress/i18n';
-import { chevronDown, chevronUp } from '@wordpress/icons';
+import { forwardRef, useMemo, useState } from '@wordpress/element';
+import { chevronDown } from '@wordpress/icons';
 import * as Card from '../card';
-import { IconButton } from '../icon-button';
+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';
 
 /**
@@ -20,52 +20,57 @@ import type { HeaderProps } from './types';
  */
 export const Header = forwardRef< HTMLDivElement, HeaderProps >(
 	function CollapsibleCardHeader(
-		{ children, className, onClick, ...restProps },
+		{ children, className, render, ...restProps },
 		ref
 	) {
-		const triggerRef = useRef< HTMLButtonElement >( null );
+		const [ descriptionId, setDescriptionId ] = useState< string >();
 
-		const handleHeaderClick = useCallback(
-			( event: MouseEvent< HTMLDivElement > ) => {
-				const trigger = triggerRef.current;
-				if (
-					trigger &&
-					event.target instanceof Node &&
-					! trigger.contains( event.target )
-				) {
-					trigger.click();
-				}
-
-				onClick?.( event );
-			},
-			[ onClick ]
+		const contextValue = useMemo(
+			() => ( { setDescriptionId } ),
+			[ setDescriptionId ]
 		);
 
 		return (
-			<Card.Header
-				ref={ ref }
-				className={ clsx( styles.header, className ) }
-				onClick={ handleHeaderClick }
-				{ ...restProps }
-			>
-				<div className={ styles[ 'header-content' ] }>{ children }</div>
-				<div className={ styles[ 'header-trigger-wrapper' ] }>
-					<Collapsible.Trigger
-						ref={ triggerRef }
-						render={ ( props, state ) => (
-							<IconButton
-								{ ...props }
-								label={ __( 'Expand or collapse card' ) }
-								icon={ state.open ? chevronUp : chevronDown }
-								variant="minimal"
-								tone="neutral"
-								size="compact"
-							/>
+			<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-positioner' ]
 						) }
-						className={ styles[ 'header-trigger' ] }
-					/>
-				</div>
-			</Card.Header>
+					>
+						<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/root.tsx

@@ -1,6 +1,6 @@
-import { Collapsible } from '@base-ui/react/collapsible';
 import { forwardRef } from '@wordpress/element';
 import * as Card from '../card';
+import * as Collapsible from '../collapsible';
 import type { RootProps } from './types';
 
 /**