@wordpress/ui 0.8.0 → 0.9.0

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

@@ -0,0 +1,33 @@
+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';
+
+/**
+ * The collapsible content area of the card. Hidden when collapsed,
+ * visible when expanded.
+ */
+export const Content = forwardRef< HTMLDivElement, ContentProps >(
+	function CollapsibleCardContent(
+		{ className, render, children, hiddenUntilFound = true, ...restProps },
+		ref
+	) {
+		return (
+			<Collapsible.Panel
+				ref={ ref }
+				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/header.tsx

@@ -0,0 +1,53 @@
+import clsx from 'clsx';
+import { forwardRef } 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 type { HeaderProps } from './types';
+
+/**
+ * The header of a collapsible card. Always visible, and acts as the
+ * toggle trigger — clicking anywhere on it expands or collapses the
+ * card's content.
+ *
+ * Avoid placing interactive elements (buttons, links, inputs) inside the
+ * header, since the entire area is clickable and their events will bubble
+ * to trigger the collapse toggle.
+ */
+export const Header = forwardRef< HTMLDivElement, HeaderProps >(
+	function CollapsibleCardHeader(
+		{ children, className, render, ...restProps },
+		ref
+	) {
+		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 }
+						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' ]
+						) }
+					/>
+				</div>
+			</Collapsible.Trigger>
+		);
+	}
+);

package/src/collapsible-card/index.ts

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

package/src/collapsible-card/root.tsx

@@ -0,0 +1,37 @@
+import { forwardRef } from '@wordpress/element';
+import * as Card from '../card';
+import * as Collapsible from '../collapsible';
+import type { RootProps } from './types';
+
+/**
+ * A card that can be expanded and collapsed. When collapsed, only the
+ * header is visible.
+ *
+ * ```jsx
+ * import { CollapsibleCard, Card } from '@wordpress/ui';
+ *
+ * function MyComponent() {
+ * 	return (
+ * 		<CollapsibleCard.Root defaultOpen>
+ * 			<CollapsibleCard.Header>
+ * 				<Card.Title>Heading</Card.Title>
+ * 			</CollapsibleCard.Header>
+ * 			<CollapsibleCard.Content>
+ * 				<p>Collapsible content here.</p>
+ * 			</CollapsibleCard.Content>
+ * 		</CollapsibleCard.Root>
+ * 	);
+ * }
+ * ```
+ */
+export const Root = forwardRef< HTMLDivElement, RootProps >(
+	function CollapsibleCardRoot( { render, ...restProps }, ref ) {
+		return (
+			<Collapsible.Root
+				ref={ ref }
+				render={ <Card.Root render={ render } /> }
+				{ ...restProps }
+			/>
+		);
+	}
+);

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

@@ -0,0 +1,207 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import * as Card from '../../card';
+import * as CollapsibleCard from '../index';
+
+/**
+ * Temporary text component for story examples. This will be replaced by an
+ * official DS `<Text />` component once it's available.
+ */
+function Text( { children }: { children: React.ReactNode } ) {
+	return (
+		<p
+			style={ {
+				margin: 0,
+				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)',
+				textWrap: 'pretty',
+				color: 'var(--wpds-color-fg-content-neutral-weak)',
+			} }
+		>
+			{ children }
+		</p>
+	);
+}
+
+const meta: Meta< typeof CollapsibleCard.Root > = {
+	title: 'Design System/Components/CollapsibleCard',
+	component: CollapsibleCard.Root,
+	subcomponents: {
+		'CollapsibleCard.Header': CollapsibleCard.Header,
+		'CollapsibleCard.Content': CollapsibleCard.Content,
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof CollapsibleCard.Root >;
+
+/**
+ * A collapsible card that is open by default.
+ */
+export const Default: Story = {
+	args: {
+		children: (
+			<>
+				<CollapsibleCard.Header>
+					<Card.Title>
+						Collapsible card (closed by default)
+					</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>
+						This is the collapsible content area. It can contain any
+						elements, just like a regular Card.Content.
+					</Text>
+					<Text>
+						When collapsed, only the header and chevron are visible.
+					</Text>
+				</CollapsibleCard.Content>
+			</>
+		),
+	},
+};
+
+/**
+ * A collapsible card that starts collapsed.
+ */
+export const InitiallyOpened: Story = {
+	// `defaultOpen` (uncontrolled) and `open` (controlled) should not be
+	// used together — disable the `open` control to avoid confusion.
+	argTypes: { open: { control: false } },
+	args: {
+		...Default.args,
+		defaultOpen: true,
+		children: (
+			<>
+				<CollapsibleCard.Header>
+					<Card.Title>Collapsed by default</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>This content was hidden until you expanded it.</Text>
+				</CollapsibleCard.Content>
+			</>
+		),
+	},
+};
+
+/**
+ * A disabled collapsible card cannot be toggled by the user.
+ */
+export const Disabled: Story = {
+	args: {
+		...Default.args,
+		disabled: true,
+		children: (
+			<>
+				<CollapsibleCard.Header>
+					<Card.Title>Disabled card</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>The header is not interactive when disabled.</Text>
+				</CollapsibleCard.Content>
+			</>
+		),
+	},
+};
+
+/**
+ * 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>
+	),
+};
+
+/**
+ * Visual comparison: a `CollapsibleCard` (open) next to a regular `Card`
+ * to verify identical spacing and layout.
+ */
+export const ComparedToCard: Story = {
+	// `defaultOpen` (uncontrolled) and `open` (controlled) should not be
+	// used together — disable the `open` control to avoid confusion.
+	argTypes: { open: { control: false } },
+	args: {
+		...Default.args,
+		defaultOpen: true,
+	},
+	render: ( { open, defaultOpen, onOpenChange, disabled, ...restArgs } ) => (
+		<div
+			style={ {
+				display: 'flex',
+				flexDirection: 'column',
+				gap: 'var( --wpds-dimension-gap-lg )',
+			} }
+		>
+			<CollapsibleCard.Root
+				open={ open }
+				defaultOpen={ defaultOpen }
+				onOpenChange={ onOpenChange }
+				disabled={ disabled }
+				{ ...restArgs }
+			>
+				<CollapsibleCard.Header>
+					<Card.Title>CollapsibleCard (open)</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>
+						Content should align with the regular card below.
+					</Text>
+				</CollapsibleCard.Content>
+			</CollapsibleCard.Root>
+			<Card.Root { ...restArgs }>
+				<Card.Header>
+					<Card.Title>Regular Card</Card.Title>
+				</Card.Header>
+				<Card.Content>
+					<Text>
+						Content should align with the collapsible card above.
+					</Text>
+				</Card.Content>
+			</Card.Root>
+		</div>
+	),
+};

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

@@ -0,0 +1,78 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	.header-content {
+		flex: 1;
+		min-width: 0;
+	}
+
+	.header-trigger-wrapper {
+		flex-shrink: 0;
+		align-self: center;
+		/* Prevent the trigger from making the header taller than its content,
+		   preserving the same metrics between `Card` and `CollapsibleCard`. */
+		max-height: 0;
+		overflow: visible;
+	}
+
+	.header-trigger {
+		/* 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). */
+		translate: 0 -50%;
+
+		/* For an outline that looks like `IconButton`'s */
+		border-radius: var(--wpds-border-radius-sm);
+
+		@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;
+
+		&:not([data-disabled]) {
+			cursor: var(--wpds-cursor-control);
+		}
+	}
+}