@wordpress/ui 0.8.0 → 0.9.0

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

@@ -0,0 +1,181 @@
+import { render, screen } from '@testing-library/react';
+import { userEvent } from '@testing-library/user-event';
+import { createRef } from '@wordpress/element';
+import * as Card from '../../card';
+import * as CollapsibleCard from '../index';
+
+describe( 'CollapsibleCard', () => {
+	describe( 'basic behaviour', () => {
+		it( 'forwards ref', () => {
+			const rootRef = createRef< HTMLDivElement >();
+			const headerRef = createRef< HTMLDivElement >();
+			const contentRef = createRef< HTMLDivElement >();
+
+			render(
+				<CollapsibleCard.Root ref={ rootRef } defaultOpen>
+					<CollapsibleCard.Header ref={ headerRef }>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+					<CollapsibleCard.Content ref={ contentRef }>
+						<p>Content</p>
+					</CollapsibleCard.Content>
+				</CollapsibleCard.Root>
+			);
+
+			expect( rootRef.current ).toBeInstanceOf( HTMLDivElement );
+			expect( headerRef.current ).toBeInstanceOf( HTMLDivElement );
+			expect( contentRef.current ).toBeInstanceOf( HTMLDivElement );
+		} );
+
+		it( 'renders header content', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Card heading</Card.Title>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			expect( screen.getByText( 'Card heading' ) ).toBeVisible();
+		} );
+	} );
+
+	describe( 'collapsing', () => {
+		it( 'hides content when collapsed (default)', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+					<CollapsibleCard.Content>
+						<p>Hidden content</p>
+					</CollapsibleCard.Content>
+				</CollapsibleCard.Root>
+			);
+
+			expect( screen.getByText( 'Hidden content' ) ).not.toBeVisible();
+		} );
+
+		it( 'shows content when defaultOpen is true', () => {
+			render(
+				<CollapsibleCard.Root defaultOpen>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+					<CollapsibleCard.Content>
+						<p>Visible content</p>
+					</CollapsibleCard.Content>
+				</CollapsibleCard.Root>
+			);
+
+			expect( screen.getByText( 'Visible content' ) ).toBeVisible();
+		} );
+
+		it( 'toggles content on trigger click', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+					<CollapsibleCard.Content>
+						<p>Toggle content</p>
+					</CollapsibleCard.Content>
+				</CollapsibleCard.Root>
+			);
+
+			expect( screen.getByText( 'Toggle content' ) ).not.toBeVisible();
+
+			await user.click(
+				screen.getByRole( 'button', {
+					name: 'Title',
+					expanded: false,
+				} )
+			);
+
+			expect( screen.getByText( 'Toggle content' ) ).toBeVisible();
+
+			await user.click(
+				screen.getByRole( 'button', {
+					name: 'Title',
+					expanded: true,
+				} )
+			);
+
+			expect( screen.getByText( 'Toggle content' ) ).not.toBeVisible();
+		} );
+
+		it( 'calls onOpenChange when toggled', async () => {
+			const onOpenChange = jest.fn();
+			const user = userEvent.setup();
+
+			render(
+				<CollapsibleCard.Root onOpenChange={ onOpenChange }>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+					<CollapsibleCard.Content>
+						<p>Content</p>
+					</CollapsibleCard.Content>
+				</CollapsibleCard.Root>
+			);
+
+			await user.click(
+				screen.getByRole( 'button', {
+					name: 'Title',
+					expanded: false,
+				} )
+			);
+
+			expect( onOpenChange.mock.calls[ 0 ][ 0 ] ).toBe( true );
+		} );
+	} );
+
+	describe( 'disabled', () => {
+		it( 'does not toggle when disabled', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<CollapsibleCard.Root defaultOpen disabled>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+					<CollapsibleCard.Content>
+						<p>Should stay visible</p>
+					</CollapsibleCard.Content>
+				</CollapsibleCard.Root>
+			);
+
+			expect( screen.getByText( 'Should stay visible' ) ).toBeVisible();
+
+			await user.click(
+				screen.getByRole( 'button', {
+					name: 'Title',
+					expanded: true,
+				} )
+			);
+
+			expect( screen.getByText( 'Should stay visible' ) ).toBeVisible();
+		} );
+	} );
+
+	describe( 'trigger', () => {
+		it( 'renders the header as a toggle button', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Title',
+					expanded: false,
+				} )
+			).toBeVisible();
+		} );
+	} );
+} );

package/src/collapsible-card/types.ts

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react';
+import type { PanelProps } from '../collapsible/types';
+import type { ComponentProps } from '../utils/types';
+
+export interface RootProps extends ComponentProps< 'div' > {
+	/**
+	 * The content to be rendered inside the collapsible card.
+	 * Should include `CollapsibleCard.Header` and `CollapsibleCard.Content`.
+	 */
+	children?: ReactNode;
+	/**
+	 * Whether the collapsible panel is currently open (controlled).
+	 *
+	 * To render an uncontrolled collapsible card, use `defaultOpen` instead.
+	 */
+	open?: boolean;
+	/**
+	 * Whether the collapsible panel is initially open (uncontrolled).
+	 * @default false
+	 */
+	defaultOpen?: boolean;
+	/**
+	 * Event handler called when the panel is opened or closed.
+	 */
+	onOpenChange?: ( open: boolean ) => void;
+	/**
+	 * Whether the component should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean;
+}
+
+export interface HeaderProps extends ComponentProps< 'div' > {
+	/**
+	 * The content to be rendered inside the header.
+	 */
+	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/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 {

package/src/dialog/types.ts

@@ -32,9 +32,9 @@ export interface PopupProps extends ComponentProps< 'div' > {
 	 * Renders the dialog at a preset width (excluding additional padding from
 	 * the viewport edges).
 	 *
-	 * - `'small'` — max-width of 384px.
-	 * - `'medium'` — max-width of 512px.
-	 * - `'large'` — max-width of 840px.
+	 * - `'small'` — narrow max-width.
+	 * - `'medium'` — moderate max-width.
+	 * - `'large'` — wide max-width.
 	 * - `'stretch'` — no max-width, stretches to fill available space.
 	 * - `'full'` — stretches to fill available width and height.
 	 *

package/src/form/primitives/field/label.tsx

@@ -2,10 +2,14 @@ import clsx from 'clsx';
 import { Field as _Field } from '@base-ui/react/field';
 import { forwardRef } from '@wordpress/element';
 import fieldStyles from '../../../utils/css/field.module.css';
+import { VisuallyHidden } from '../../../visually-hidden';
 import type { FieldLabelProps } from './types';
 
 export const Label = forwardRef< HTMLLabelElement, FieldLabelProps >(
-	function Label( { className, variant, ...restProps }, ref ) {
+	function Label(
+		{ className, hideFromVision, variant, ...restProps },
+		ref
+	) {
 		return (
 			<_Field.Label
 				ref={ ref }
@@ -14,6 +18,10 @@ export const Label = forwardRef< HTMLLabelElement, FieldLabelProps >(
 					variant && fieldStyles[ `is-${ variant }` ],
 					className
 				) }
+				{ ...( hideFromVision && {
+					render: <VisuallyHidden />,
+					nativeLabel: false,
+				} ) }
 				{ ...restProps }
 			/>
 		);

package/src/form/primitives/field/stories/index.story.tsx

@@ -100,6 +100,23 @@ export const UsingAriaLabelledby: StoryObj< typeof Field.Root > = {
 	},
 };
 
+/**
+ * When `hideFromVision` is set on `Field.Label`, the label is visually
+ * hidden but remains accessible to screen readers.
+ */
+export const HiddenLabel: StoryObj< typeof Field.Root > = {
+	args: {
+		children: (
+			<>
+				<Field.Label hideFromVision>Label</Field.Label>
+				<Field.Control
+					render={ <input type="text" placeholder="Placeholder" /> }
+				/>
+			</>
+		),
+	},
+};
+
 /**
  * To add rich content (such as links) to the description, use `Field.Details`.
  *

package/src/form/primitives/field/test/index.test.tsx

@@ -34,6 +34,19 @@ describe( 'Field', () => {
 		expect( detailsRef.current ).toBeInstanceOf( HTMLDivElement );
 	} );
 
+	it( 'keeps the accessible name when the label is visually hidden', () => {
+		render(
+			<Field.Root>
+				<Field.Label hideFromVision>Field Label</Field.Label>
+				<Field.Control render={ <input /> } />
+			</Field.Root>
+		);
+
+		expect(
+			screen.getByRole( 'textbox', { name: 'Field Label' } )
+		).toBeVisible();
+	} );
+
 	it( 'renders details with a semantically associated description for the control', () => {
 		render(
 			<Field.Root>

package/src/form/primitives/field/types.ts

@@ -33,6 +33,13 @@ export type FieldLabelProps = ComponentProps< typeof Field.Label > & {
 	 * elements such as links or buttons.
 	 */
 	children?: Field.Label.Props[ 'children' ];
+	/**
+	 * Whether to visually hide the label while keeping it accessible
+	 * to screen readers.
+	 *
+	 * @default false
+	 */
+	hideFromVision?: boolean;
 	/**
 	 * The visual variant of the label.
 	 *

package/src/form/primitives/fieldset/legend.tsx

@@ -2,14 +2,21 @@ import clsx from 'clsx';
 import { Fieldset as _Fieldset } from '@base-ui/react/fieldset';
 import { forwardRef } from '@wordpress/element';
 import fieldStyles from '../../../utils/css/field.module.css';
+import { VisuallyHidden } from '../../../visually-hidden';
 import type { FieldsetLegendProps } from './types';
 
 export const FieldsetLegend = forwardRef< HTMLDivElement, FieldsetLegendProps >(
-	function FieldsetLegend( { className, ...restProps }, ref ) {
+	function FieldsetLegend(
+		{ className, hideFromVision, ...restProps },
+		ref
+	) {
 		return (
 			<_Fieldset.Legend
 				ref={ ref }
 				className={ clsx( fieldStyles.label, className ) }
+				{ ...( hideFromVision && {
+					render: <VisuallyHidden />,
+				} ) }
 				{ ...restProps }
 			/>
 		);

package/src/form/primitives/fieldset/stories/index.story.tsx

@@ -33,6 +33,26 @@ export const Default: Story = {
 	},
 };
 
+/**
+ * When `hideFromVision` is set on `Fieldset.Legend`, the legend is visually
+ * hidden but remains accessible to screen readers.
+ */
+export const HiddenLegend: Story = {
+	args: {
+		children: (
+			<>
+				<Fieldset.Legend hideFromVision>Legend</Fieldset.Legend>
+				{ [ 'Apples', 'Bananas' ].map( ( fruit ) => (
+					// eslint-disable-next-line jsx-a11y/label-has-associated-control
+					<label key={ fruit }>
+						<input type="checkbox" /> { fruit }
+					</label>
+				) ) }
+			</>
+		),
+	},
+};
+
 /**
  * To add rich content (such as links) to the description, use `Fieldset.Details`.
  *

package/src/form/primitives/fieldset/test/index.test.tsx

@@ -29,6 +29,20 @@ describe( 'Fieldset', () => {
 		expect( detailsRef.current ).toBeInstanceOf( HTMLDivElement );
 	} );
 
+	it( 'keeps the accessible name when the legend is visually hidden', () => {
+		render(
+			<Fieldset.Root>
+				<Fieldset.Legend hideFromVision>
+					Choose your options
+				</Fieldset.Legend>
+			</Fieldset.Root>
+		);
+
+		expect(
+			screen.getByRole( 'group', { name: 'Choose your options' } )
+		).toBeVisible();
+	} );
+
 	it( 'accessibly associates description when Fieldset.Description is present', () => {
 		render(
 			<Fieldset.Root>

package/src/form/primitives/fieldset/types.ts

@@ -7,6 +7,13 @@ export type FieldsetRootProps = ComponentProps< typeof _Fieldset.Root > & {
 
 export type FieldsetLegendProps = ComponentProps< typeof _Fieldset.Legend > & {
 	children?: React.ReactNode;
+	/**
+	 * Whether to visually hide the legend while keeping it accessible
+	 * to screen readers.
+	 *
+	 * @default false
+	 */
+	hideFromVision?: boolean;
 };
 
 export type FieldsetDescriptionProps = ComponentProps< 'p' > & {

package/src/form/primitives/input-layout/slot.tsx

@@ -9,13 +9,17 @@ import type { InputLayoutSlotProps } from './types';
 export const InputLayoutSlot = forwardRef<
 	HTMLDivElement,
 	InputLayoutSlotProps
->( function InputLayoutSlot( { padding = 'default', ...restProps }, ref ) {
+>( function InputLayoutSlot(
+	{ padding = 'default', className, ...restProps },
+	ref
+) {
 	return (
 		<div
 			ref={ ref }
 			className={ clsx(
 				styles[ 'input-layout-slot' ],
-				styles[ `is-padding-${ padding }` ]
+				styles[ `is-padding-${ padding }` ],
+				className
 			) }
 			{ ...restProps }
 		/>

package/src/index.ts

@@ -1,11 +1,16 @@
 export * from './badge';
 export * from './button';
+export * as Card from './card';
+export * as Collapsible from './collapsible';
+export * as CollapsibleCard from './collapsible-card';
 export * as Dialog from './dialog';
 export * from './form/primitives';
 export * from './icon';
 export * from './icon-button';
+export * from './link';
 export * as Notice from './notice';
 export * from './stack';
 export * as Tabs from './tabs';
+export * from './text';
 export * as Tooltip from './tooltip';
 export * from './visually-hidden';

package/src/link/index.ts

@@ -0,0 +1 @@
+export { Link } from './link';

package/src/link/link.tsx

@@ -0,0 +1,73 @@
+import { useRender, mergeProps } from '@base-ui/react';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { type LinkProps } from './types';
+import resetStyles from '../utils/css/resets.module.css';
+import focusStyles from '../utils/css/focus.module.css';
+import styles from './style.module.css';
+
+/**
+ * A styled anchor element with support for semantic color tones and an
+ * unstyled escape hatch.
+ */
+export const Link = forwardRef< HTMLAnchorElement, LinkProps >( function Link(
+	{
+		children,
+		variant = 'default',
+		tone = 'brand',
+		openInNewTab = false,
+		render,
+		className,
+		onClick,
+		...props
+	},
+	ref
+) {
+	const isInternalAnchor = !! props.href?.startsWith( '#' );
+
+	const handleClick = ( event: React.MouseEvent< HTMLAnchorElement > ) => {
+		if ( openInNewTab && isInternalAnchor ) {
+			event.preventDefault();
+		}
+		onClick?.( event );
+	};
+
+	const element = useRender( {
+		render,
+		defaultTagName: 'a',
+		ref,
+		props: mergeProps< 'a' >( props, {
+			className: clsx(
+				resetStyles[ 'box-sizing' ],
+				focusStyles[ 'outset-ring--focus' ],
+				variant !== 'unstyled' && styles.link,
+				variant !== 'unstyled' && styles[ `is-${ tone }` ],
+				variant === 'unstyled' && styles[ 'is-unstyled' ],
+				openInNewTab && styles[ 'has-link-icon' ],
+				className
+			),
+			onClick: handleClick,
+			target: openInNewTab ? '_blank' : undefined,
+			children: openInNewTab ? (
+				<>
+					<span className={ styles[ 'link-contents' ] }>
+						{ children }
+					</span>
+					<span
+						className={ styles[ 'link-icon' ] }
+						role="img"
+						aria-label={
+							/* translators: accessibility text appended to link text */
+							__( '(opens in a new tab)' )
+						}
+					/>
+				</>
+			) : (
+				children
+			),
+		} ),
+	} );
+
+	return element;
+} );

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

@@ -0,0 +1,92 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Link } from '../index';
+import { Stack } from '../../stack';
+import { Text } from '../../text';
+
+const meta: Meta< typeof Link > = {
+	title: 'Design System/Components/Link',
+	component: Link,
+};
+export default meta;
+
+type Story = StoryObj< typeof Link >;
+
+export const Default: Story = {
+	args: {
+		children: 'Learn more',
+		href: '#',
+	},
+};
+
+/**
+ * Note: `tone` has no effect on `unstyled` variant
+ */
+export const AllTonesAndVariants: Story = {
+	...Default,
+	argTypes: {
+		tone: {
+			control: false,
+		},
+		variant: {
+			control: false,
+		},
+	},
+	render: ( args ) => (
+		<Stack direction="column" gap="lg">
+			{ ( [ 'brand', 'neutral' ] as const ).map( ( tone ) =>
+				( [ 'default', 'unstyled' ] as const ).map( ( variant ) => (
+					<Stack
+						direction="column"
+						gap="xs"
+						key={ `${ tone }-${ variant }` }
+					>
+						<Text variant="heading-sm">
+							{ tone } tone, { variant } variant
+						</Text>
+						<Link { ...args } tone={ tone } variant={ variant } />
+					</Stack>
+				) )
+			) }
+		</Stack>
+	),
+};
+
+export const Inline: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		children: 'inline link',
+	},
+	render: ( args ) => (
+		<Text variant="body-md" render={ <p /> }>
+			This is a paragraph with an <Link { ...args } /> that inherits its
+			typography from the parent Text component.
+		</Text>
+	),
+};
+
+/**
+ * When composing `Text` and `Link` via the `render` prop, the order matters:
+ * - `<Text render={ <Link /> } />` renders an `<a>` element (Link's default tag wins).
+ * - `<Link render={ <Text /> } />` renders a `<span>` element (Text's default tag wins).
+ */
+export const Standalone: Story = {
+	args: {
+		href: '#',
+	},
+	argTypes: {
+		children: {
+			control: false,
+		},
+	},
+	render: ( args ) => (
+		<Stack direction="column" gap="md">
+			<Text variant="body-md" render={ <Link { ...args } /> }>
+				A standalone link with body-md typography
+			</Text>
+			<Text variant="body-sm" render={ <Link { ...args } /> }>
+				A standalone link with body-sm typography
+			</Text>
+		</Stack>
+	),
+};