@wordpress/ui 0.10.0 → 0.11.0

package/src/empty-state/test/description.test.tsx

@@ -10,4 +10,17 @@ describe( 'EmptyState.Description', () => {
 
 		expect( ref.current ).toBeInstanceOf( HTMLParagraphElement );
 	} );
+
+	it( 'forwards ref to custom render element', () => {
+		const ref = createRef< HTMLDivElement >();
+
+		render(
+			<Description ref={ ref } render={ <div /> }>
+				Description text
+			</Description>
+		);
+
+		expect( ref.current ).toBeInstanceOf( HTMLDivElement );
+		expect( ref.current?.tagName ).toBe( 'DIV' );
+	} );
 } );

package/src/empty-state/test/title.test.tsx

@@ -10,4 +10,17 @@ describe( 'EmptyState.Title', () => {
 
 		expect( ref.current ).toBeInstanceOf( HTMLHeadingElement );
 	} );
+
+	it( 'forwards ref to custom render element', () => {
+		const ref = createRef< HTMLHeadingElement >();
+
+		render(
+			<Title ref={ ref } render={ <h3 /> }>
+				No results found
+			</Title>
+		);
+
+		expect( ref.current ).toBeInstanceOf( HTMLHeadingElement );
+		expect( ref.current?.tagName ).toBe( 'H3' );
+	} );
 } );

package/src/empty-state/title.tsx

@@ -4,17 +4,23 @@ import { Text } from '../text';
 import type { EmptyStateTitleProps } from './types';
 import styles from './style.module.css';
 
+const DEFAULT_TAG = <h2 />;
+
 /**
  * The title is a short heading that communicates the empty state.
  */
 export const Title = forwardRef< HTMLHeadingElement, EmptyStateTitleProps >(
-	function EmptyStateTitle( { render, className, children, ...props }, ref ) {
+	function EmptyStateTitle(
+		{ render = DEFAULT_TAG, className, children, ...props },
+		ref
+	) {
 		return (
 			<Text
+				ref={ ref }
 				variant="heading-lg"
-				// eslint-disable-next-line jsx-a11y/heading-has-content -- content provided via render prop
-				render={ render ?? <h2 ref={ ref } { ...props } /> }
+				render={ render }
 				className={ clsx( styles.title, className ) }
+				{ ...props }
 			>
 				{ children }
 			</Text>

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

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
 import { Field as _Field } from '@base-ui/react/field';
 import { forwardRef } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import fieldStyles from '../../../utils/css/field.module.css';
 import type { FieldDescriptionProps } from './types';
 
@@ -11,7 +12,11 @@ export const Description = forwardRef<
 	return (
 		<_Field.Description
 			ref={ ref }
-			className={ clsx( fieldStyles.description, className ) }
+			className={ clsx(
+				defenseStyles.p,
+				fieldStyles.description,
+				className
+			) }
 			{ ...restProps }
 		/>
 	);

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

@@ -22,9 +22,11 @@ export const Details = forwardRef< HTMLDivElement, FieldDetailsProps >(
 	function Details( { className, ...restProps }, ref ) {
 		return (
 			<>
-				<_Field.Description render={ <VisuallyHidden /> }>
+				{ /* VisuallyHidden is the host so that _Field.Description's
+				   semantic element is preserved. See VisuallyHidden docs. */ }
+				<VisuallyHidden render={ <_Field.Description /> }>
 					{ __( 'More details follow the field.' ) }
-				</_Field.Description>
+				</VisuallyHidden>
 				<div
 					ref={ ref }
 					className={ clsx( fieldStyles.description, className ) }

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

@@ -10,7 +10,7 @@ export const Label = forwardRef< HTMLLabelElement, FieldLabelProps >(
 		{ className, hideFromVision, variant, ...restProps },
 		ref
 	) {
-		return (
+		const label = (
 			<_Field.Label
 				ref={ ref }
 				className={ clsx(
@@ -18,12 +18,16 @@ export const Label = forwardRef< HTMLLabelElement, FieldLabelProps >(
 					variant && fieldStyles[ `is-${ variant }` ],
 					className
 				) }
-				{ ...( hideFromVision && {
-					render: <VisuallyHidden />,
-					nativeLabel: false,
-				} ) }
 				{ ...restProps }
 			/>
 		);
+
+		// VisuallyHidden is the host so that _Field.Label's semantic
+		// element is preserved. See VisuallyHidden docs for details.
+		if ( hideFromVision ) {
+			return <VisuallyHidden render={ label } />;
+		}
+
+		return label;
 	}
 );

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

@@ -5,7 +5,7 @@ import resetStyles from '../../../utils/css/resets.module.css';
 import type { FieldRootProps } from './types';
 import { Stack } from '../../../stack';
 
-const defaultRender = ( props: React.ComponentProps< typeof Stack > ) => (
+const DEFAULT_RENDER = ( props: React.ComponentProps< typeof Stack > ) => (
 	<Stack { ...props } direction="column" gap="sm" />
 );
 
@@ -19,7 +19,7 @@ const defaultRender = ( props: React.ComponentProps< typeof Stack > ) => (
  * accessible labeling. See examples for how to associate the label in different cases.
  */
 export const Root = forwardRef< HTMLDivElement, FieldRootProps >( function Root(
-	{ className, render = defaultRender, ...restProps },
+	{ className, render = DEFAULT_RENDER, ...restProps },
 	ref
 ) {
 	return (

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

@@ -47,6 +47,17 @@ describe( 'Field', () => {
 		).toBeVisible();
 	} );
 
+	it( 'preserves the native label element when hideFromVision is enabled', () => {
+		render(
+			<Field.Root>
+				<Field.Label hideFromVision>Field Label</Field.Label>
+				<Field.Control render={ <input /> } />
+			</Field.Root>
+		);
+
+		expect( screen.getByText( 'Field Label' ).tagName ).toBe( 'LABEL' );
+	} );
+
 	it( 'renders details with a semantically associated description for the control', () => {
 		render(
 			<Field.Root>

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

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
 import { mergeProps, useRender } from '@base-ui/react';
 import { forwardRef, useEffect, useId } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import fieldStyles from '../../../utils/css/field.module.css';
 import { useFieldsetContext } from './context';
 import type { FieldsetDescriptionProps } from './types';
@@ -27,7 +28,14 @@ export const FieldsetDescription = forwardRef<
 		render,
 		ref,
 		props: mergeProps< 'p' >(
-			{ className: clsx( fieldStyles.description, className ), id },
+			{
+				className: clsx(
+					defenseStyles.p,
+					fieldStyles.description,
+					className
+				),
+				id,
+			},
 			restProps
 		),
 	} );

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

@@ -10,15 +10,20 @@ export const FieldsetLegend = forwardRef< HTMLDivElement, FieldsetLegendProps >(
 		{ className, hideFromVision, ...restProps },
 		ref
 	) {
-		return (
+		const legend = (
 			<_Fieldset.Legend
 				ref={ ref }
 				className={ clsx( fieldStyles.label, className ) }
-				{ ...( hideFromVision && {
-					render: <VisuallyHidden />,
-				} ) }
 				{ ...restProps }
 			/>
 		);
+
+		// VisuallyHidden is the host so that _Fieldset.Legend's semantic
+		// element is preserved. See VisuallyHidden docs for details.
+		if ( hideFromVision ) {
+			return <VisuallyHidden render={ legend } />;
+		}
+
+		return legend;
 	}
 );

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

@@ -43,6 +43,28 @@ describe( 'Fieldset', () => {
 		).toBeVisible();
 	} );
 
+	it( 'preserves the legend element type when hideFromVision is enabled', () => {
+		const { rerender } = render(
+			<Fieldset.Root>
+				<Fieldset.Legend>Choose your options</Fieldset.Legend>
+			</Fieldset.Root>
+		);
+
+		const tagWithout = screen.getByText( 'Choose your options' ).tagName;
+
+		rerender(
+			<Fieldset.Root>
+				<Fieldset.Legend hideFromVision>
+					Choose your options
+				</Fieldset.Legend>
+			</Fieldset.Root>
+		);
+
+		expect( screen.getByText( 'Choose your options' ).tagName ).toBe(
+			tagWithout
+		);
+	} );
+
 	it( 'accessibly associates description when Fieldset.Description is present', () => {
 		render(
 			<Fieldset.Root>

package/src/form/primitives/input/input.tsx

@@ -1,6 +1,7 @@
 import { Input as _Input } from '@base-ui/react/input';
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import focusStyles from '../../../utils/css/focus.module.css';
 import styles from './style.module.css';
 import type { InputProps } from './types';
@@ -22,7 +23,11 @@ export const Input = forwardRef< HTMLElement, InputProps >( function Input(
 			prefix={ prefix }
 			suffix={ suffix }
 		>
-			<_Input ref={ ref } className={ styles.input } { ...restProps } />
+			<_Input
+				ref={ ref }
+				className={ clsx( defenseStyles.input, styles.input ) }
+				{ ...restProps }
+			/>
 		</InputLayout>
 	);
 } );

package/src/form/primitives/input/style.module.css

@@ -2,6 +2,10 @@
 
 @layer wp-ui-components {
 	.input {
+		--_gcd-input-padding:
+			var(--wp-ui-input-padding-block, 0)
+			var(--wp-ui-input-layout-padding-inline, 0);
+
 		padding-block: var(--wp-ui-input-padding-block, 0);
 		padding-inline: var(--wp-ui-input-layout-padding-inline, 0);
 		width: 100%;

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

@@ -1,5 +1,6 @@
 import clsx from 'clsx';
 import { Children, forwardRef } from '@wordpress/element';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 import resetStyles from '../../../utils/css/resets.module.css';
 import styles from './style.module.css';
 import type { InputLayoutProps } from './types';
@@ -26,6 +27,7 @@ export const InputLayout = forwardRef< HTMLDivElement, InputLayoutProps >(
 			<div
 				ref={ ref }
 				className={ clsx(
+					defenseStyles.div,
 					resetStyles[ 'box-sizing' ],
 					styles[ 'input-layout' ],
 					styles[ `is-size-${ size }` ],

package/src/form/primitives/input-layout/style.module.css

@@ -11,13 +11,13 @@
 		border-style: solid;
 		border-color: var(--wpds-color-stroke-interactive-neutral);
 		border-radius: var(--wpds-border-radius-sm);
-		font-family: var(--wpds-font-family-body);
-		font-size: max(var(--wpds-font-size-md), 16px); /* avoid mobile zoom */
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: max(var(--wpds-typography-font-size-md), 16px); /* avoid mobile zoom */
 		line-height: 1;
 		color: var(--wpds-color-fg-interactive-neutral);
 
 		@media (min-width: 600px) {
-			font-size: var(--wpds-font-size-md);
+			font-size: var(--wpds-typography-font-size-md);
 		}
 
 		&.is-size-compact {

package/src/form/primitives/select/popup.tsx

@@ -16,9 +16,12 @@ const ThemeProvider: typeof ThemeProviderType =
 	unlock( themePrivateApis ).ThemeProvider;
 
 export const Popup = forwardRef< HTMLDivElement, SelectPopupProps >(
-	function Popup( { className, children, style, ...restProps }, ref ) {
+	function Popup(
+		{ className, container, children, style, ...restProps },
+		ref
+	) {
 		return (
-			<_Select.Portal>
+			<_Select.Portal container={ container }>
 				<_Select.Positioner
 					{ ...ITEM_POPUP_POSITIONER_PROPS }
 					alignItemWithTrigger={ false }

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

@@ -1,4 +1,4 @@
-import { render } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { createRef } from '@wordpress/element';
 import * as Select from '../index';
@@ -30,4 +30,63 @@ describe( 'Select', () => {
 		expect( popupRef.current ).toBeInstanceOf( HTMLDivElement );
 		expect( itemRef.current ).toBeInstanceOf( HTMLDivElement );
 	} );
+
+	describe( 'container', () => {
+		it( 'should render inside the container when provided', async () => {
+			const user = userEvent.setup();
+			const containerRef = createRef< HTMLDivElement >();
+
+			render(
+				<div data-testid="wrapper">
+					<Select.Root>
+						<Select.Trigger />
+						<div
+							ref={ containerRef }
+							data-testid="custom-container"
+						/>
+						<Select.Popup container={ containerRef }>
+							<Select.Item value="Item 1" />
+						</Select.Popup>
+					</Select.Root>
+				</div>
+			);
+
+			await user.click( screen.getByRole( 'combobox' ) );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			expect( item ).toBeVisible();
+
+			expect( screen.getByTestId( 'custom-container' ) ).toContainElement(
+				item
+			);
+		} );
+
+		it( 'should render with a portal by default', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<div data-testid="wrapper">
+					<Select.Root>
+						<Select.Trigger />
+						<Select.Popup>
+							<Select.Item value="Item 1" />
+						</Select.Popup>
+					</Select.Root>
+				</div>
+			);
+
+			await user.click( screen.getByRole( 'combobox' ) );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			expect( item ).toBeVisible();
+
+			expect( screen.getByTestId( 'wrapper' ) ).not.toContainElement(
+				item
+			);
+		} );
+	} );
 } );

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

@@ -1,4 +1,5 @@
 import type { Select as _Select } from '@base-ui/react/select';
+import type { ComponentProps } from '../../../utils/types';
 import type { InputLayoutProps } from '../input-layout/types';
 
 // The second type parameter is the `multiple` flag (currently disabled).
@@ -7,7 +8,7 @@ export type SelectRootProps = Omit<
 	'multiple'
 >;
 
-export type SelectTriggerProps = Omit< _Select.Trigger.Props, 'children' > & {
+export type SelectTriggerProps = ComponentProps< typeof _Select.Trigger > & {
 	/**
 	 * The size of the trigger.
 	 *
@@ -27,11 +28,20 @@ export type SelectTriggerProps = Omit< _Select.Trigger.Props, 'children' > & {
 	children?: _Select.Value.Props[ 'children' ];
 };
 
-export type SelectPopupProps = _Select.Popup.Props;
+export type SelectPopupProps = ComponentProps< typeof _Select.Popup > & {
+	/**
+	 * The content to be rendered inside the popup.
+	 */
+	children?: React.ReactNode;
+	/**
+	 * A parent element to render the portal into.
+	 */
+	container?: _Select.Portal.Props[ 'container' ];
+};
 
 export type SelectItemProps = Omit<
-	_Select.Item.Props,
-	'children' | 'value'
+	ComponentProps< typeof _Select.Item >,
+	'value'
 > & {
 	/**
 	 * A unique value that identifies this select item.

package/src/form/primitives/textarea/textarea.tsx

@@ -4,6 +4,7 @@ import { cloneElement, forwardRef } from '@wordpress/element';
 import styles from './style.module.css';
 import type { TextareaProps } from './types';
 import { Input } from '../input';
+import defenseStyles from '../../../utils/css/global-css-defense.module.css';
 
 const wrappedRender = (
 	render: NonNullable< TextareaProps[ 'render' ] >,
@@ -39,7 +40,15 @@ export const Textarea = forwardRef< HTMLTextAreaElement, TextareaProps >(
 				style={ style }
 				render={ wrappedRender(
 					render || ( ( props ) => <textarea { ...props } /> ),
-					{ className: styles.textarea, ref, rows, ...restProps }
+					{
+						className: clsx(
+							defenseStyles.textarea,
+							styles.textarea
+						),
+						ref,
+						rows,
+						...restProps,
+					}
 				) }
 				value={ value }
 				defaultValue={ defaultValue }

package/src/form/stories/shared.tsx

@@ -1,3 +1,5 @@
+import { Link } from '../..';
+
 export const WITH_DETAILS_DESCRIPTION = `\
 To add rich content (such as links) to the description, use the \`details\` prop.
 
@@ -11,9 +13,9 @@ so the readout is not unnecessarily verbose for screen reader users.`;
 export const DETAILS_EXAMPLE = (
 	<>
 		Details can include{ ' ' }
-		<a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a">
+		<Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a">
 			links to more information
-		</a>{ ' ' }
+		</Link>{ ' ' }
 		and other semantic elements.
 	</>
 );

package/src/index.ts

@@ -11,6 +11,7 @@ export * from './icon';
 export * from './icon-button';
 export * from './link';
 export * as Notice from './notice';
+export * as Popover from './popover';
 export * from './stack';
 export * as Tabs from './tabs';
 export * from './text';

package/src/link/link.tsx

@@ -6,6 +6,7 @@ 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';
+import defenseStyles from '../utils/css/global-css-defense.module.css';
 
 /**
  * A styled anchor element with support for semantic color tones and an
@@ -39,6 +40,7 @@ export const Link = forwardRef< HTMLAnchorElement, LinkProps >( function Link(
 		ref,
 		props: mergeProps< 'a' >( props, {
 			className: clsx(
+				defenseStyles.a,
 				resetStyles[ 'box-sizing' ],
 				focusStyles[ 'outset-ring--focus' ],
 				variant !== 'unstyled' && styles.link,

package/src/link/style.module.css

@@ -9,28 +9,38 @@
 	/* Brand tone */
 	.is-brand,
 	.is-brand:visited {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-brand);
+
 		color: var(--wpds-color-fg-interactive-brand);
 	}
 
 	.is-brand:hover,
 	.is-brand:active {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-brand-active);
+
 		color: var(--wpds-color-fg-interactive-brand-active);
 	}
 
 	/* Neutral tone */
 	.is-neutral,
 	.is-neutral:visited {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-neutral);
+
 		color: var(--wpds-color-fg-interactive-neutral);
 		text-decoration-color: var(--wpds-color-stroke-interactive-neutral);
 	}
 
 	.is-neutral:hover,
 	.is-neutral:active {
+		--_gcd-a-color: var(--wpds-color-fg-interactive-neutral-active);
+
 		color: var(--wpds-color-fg-interactive-neutral-active);
 	}
 
 	/* Unstyled variant */
 	.is-unstyled {
+		--_gcd-a-color: inherit;
+
 		color: inherit;
 		text-decoration: none;
 	}
@@ -55,7 +65,7 @@
 
 	.link-icon {
 		margin-inline-start: var(--wpds-dimension-padding-xs);
-		font-weight: var(--wpds-font-weight-regular);
+		font-weight: var(--wpds-typography-font-weight-regular);
 	}
 
 	.link-icon::after {

package/src/notice/style.module.css

@@ -3,7 +3,7 @@
 @layer wp-ui-components {
 	.notice {
 		--icon-height: 24px;
-		--text-vertical-padding: calc((var(--icon-height) - var(--wpds-font-line-height-sm)) / 2);
+		--text-vertical-padding: calc((var(--icon-height) - var(--wpds-typography-line-height-sm)) / 2);
 
 		--wp-ui-notice-background-color: var(--wpds-color-bg-surface-neutral-weak);
 		--wp-ui-notice-border-color: var(--wpds-color-stroke-surface-neutral);
@@ -64,10 +64,10 @@
 
 	.action-link {
 		flex-shrink: 0;
-		font-family: var(--wpds-font-family-body);
-		font-size: var(--wpds-font-size-md);
-		font-weight: var(--wpds-font-weight-regular);
-		line-height: var(--wpds-font-line-height-sm);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-md);
+		font-weight: var(--wpds-typography-font-weight-regular);
+		line-height: var(--wpds-typography-line-height-sm);
 		margin-block: auto;
 
 		/* Add more horizontal space when following another action link/button */

package/src/popover/arrow.tsx

@@ -0,0 +1,49 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import styles from './style.module.css';
+import type { ArrowProps } from './types';
+
+function DefaultArrowSvg( props: React.ComponentProps< 'svg' > ) {
+	return (
+		<svg
+			width="20"
+			height="10"
+			viewBox="0 0 20 10"
+			fill="none"
+			{ ...props }
+		>
+			<path
+				d="M20 10H0V8h1.465a4 4 0 0 0 2.676-1.027l5.19-4.388c.378-.341.96-.341 1.338 0l5.19 4.388A4 4 0 0 0 18.535 8H20z"
+				className={ styles[ 'arrow-fill' ] }
+			/>
+			<path
+				d="M10 3.097 4.81 7.486A5 5 0 0 1 1.465 8.77H0V8h1.465a4 4 0 0 0 2.676-1.027l5.19-4.388c.378-.341.96-.341 1.338 0l5.19 4.388A4 4 0 0 0 18.535 8H20v.77h-1.465a5 5 0 0 1-3.345-1.284z"
+				className={ styles[ 'arrow-stroke' ] }
+			/>
+		</svg>
+	);
+}
+
+/**
+ * Renders an optional arrow element that points toward the anchor.
+ *
+ * Must be placed inside `Popover.Popup`. The arrow automatically rotates
+ * to match the current placement side.
+ */
+const Arrow = forwardRef< HTMLDivElement, ArrowProps >( function PopoverArrow(
+	{ children, className, ...props },
+	ref
+) {
+	return (
+		<_Popover.Arrow
+			ref={ ref }
+			className={ clsx( styles.arrow, className ) }
+			{ ...props }
+		>
+			{ children ?? <DefaultArrowSvg /> }
+		</_Popover.Arrow>
+	);
+} );
+
+export { Arrow };

package/src/popover/close.tsx

@@ -0,0 +1,24 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import { forwardRef } from '@wordpress/element';
+import type { CloseProps } from './types';
+
+/**
+ * Renders a button that closes the popover when clicked.
+ *
+ * When the popover opens, initial focus skips this button in favor of
+ * the first interactive element inside the popup (unless `initialFocus`
+ * on `Popover.Popup` overrides this behavior).
+ */
+const Close = forwardRef< HTMLButtonElement, CloseProps >(
+	function PopoverClose( props, ref ) {
+		return (
+			<_Popover.Close
+				ref={ ref }
+				data-wp-ui-popover-close=""
+				{ ...props }
+			/>
+		);
+	}
+);
+
+export { Close };