@wordpress/ui 0.12.1-next.v.202604201441.0 → 0.13.0

package/src/form/select-control/test/index.test.tsx

@@ -0,0 +1,196 @@
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createRef } from '@wordpress/element';
+import { SelectControl } from '../index';
+
+describe( 'SelectControl', () => {
+	const mockItems = [
+		{ value: '', label: 'Select' },
+		{ value: 'option1', label: 'Option 1' },
+		{ value: 'option2', label: 'Option 2' },
+		{ value: 'option3', label: 'Option 3' },
+	];
+
+	it( 'forwards ref to the visible trigger', () => {
+		const ref = createRef< HTMLButtonElement >();
+
+		render(
+			<SelectControl ref={ ref } label="Country" items={ mockItems } />
+		);
+
+		const trigger = screen.getByRole( 'combobox', { name: 'Country' } );
+
+		expect( ref.current ).toBe( trigger );
+		act( () => {
+			ref.current?.focus();
+		} );
+		expect( trigger ).toHaveFocus();
+	} );
+
+	it( 'renders accessible label and description', () => {
+		render(
+			<SelectControl
+				label="Country"
+				description="Choose your country"
+				items={ mockItems }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'combobox', {
+				name: 'Country',
+				description: 'Choose your country',
+			} )
+		).toBeVisible();
+	} );
+
+	it( 'renders custom placeholder text when no value is selected', () => {
+		render(
+			<SelectControl
+				label="Country"
+				items={ mockItems }
+				placeholder="Choose a country"
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'combobox', {
+				name: 'Country',
+			} )
+		).toHaveTextContent( 'Choose a country' );
+	} );
+
+	it( 'renders with a visually hidden label', () => {
+		render(
+			<SelectControl
+				label="Country"
+				hideLabelFromVision
+				items={ mockItems }
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'combobox', { name: 'Country' } )
+		).toBeVisible();
+	} );
+
+	it( 'renders with details', () => {
+		render(
+			<SelectControl
+				label="Country"
+				items={ mockItems }
+				details={
+					<span>
+						Select the country where your store is registered.
+					</span>
+				}
+			/>
+		);
+
+		expect(
+			screen.getByText( /where your store is registered/ )
+		).toBeVisible();
+	} );
+
+	it( 'passes the current value to custom trigger content', async () => {
+		const user = userEvent.setup();
+
+		render(
+			<SelectControl
+				label="Country"
+				items={ mockItems }
+				defaultValue={ mockItems[ 1 ] }
+				triggerContent={ ( item ) => `Selected ${ item.label }` }
+			/>
+		);
+
+		const trigger = screen.getByRole( 'combobox', {
+			name: 'Country',
+		} );
+
+		expect( trigger ).toHaveTextContent( 'Selected Option 1' );
+
+		await user.click( trigger );
+		await user.click(
+			await screen.findByRole( 'option', {
+				name: 'Option 2',
+			} )
+		);
+
+		expect( trigger ).toHaveTextContent( 'Selected Option 2' );
+	} );
+
+	describe( 'Form data behavior', () => {
+		it( 'submits correct form data when option is selected with custom name', async () => {
+			const user = userEvent.setup();
+			const handleSubmit = jest.fn(
+				( event: React.FormEvent< HTMLFormElement > ) => {
+					event.preventDefault();
+					return new FormData( event.currentTarget );
+				}
+			);
+
+			render(
+				<form onSubmit={ handleSubmit }>
+					<SelectControl
+						label="Country"
+						name="country"
+						items={ mockItems }
+					/>
+					<button type="submit">Submit</button>
+				</form>
+			);
+
+			await user.click(
+				screen.getByRole( 'combobox', {
+					name: 'Country',
+				} )
+			);
+
+			const optionToSelect = await screen.findByRole( 'option', {
+				name: /Option 2/i,
+			} );
+			await user.click( optionToSelect );
+
+			await user.click(
+				screen.getByRole( 'button', {
+					name: 'Submit',
+				} )
+			);
+
+			const formData = handleSubmit.mock.results[ 0 ].value;
+			expect( formData.get( 'country' ) ).toBe( 'option2' );
+		} );
+
+		it( 'submits form data with default value when no selection is made', async () => {
+			const user = userEvent.setup();
+			const handleSubmit = jest.fn(
+				( event: React.FormEvent< HTMLFormElement > ) => {
+					event.preventDefault();
+					return new FormData( event.currentTarget );
+				}
+			);
+
+			render(
+				<form onSubmit={ handleSubmit }>
+					<SelectControl
+						label="Country"
+						name="country"
+						items={ mockItems }
+						defaultValue={ mockItems[ 0 ] }
+					/>
+					<button type="submit">Submit</button>
+				</form>
+			);
+
+			await user.click(
+				screen.getByRole( 'button', {
+					name: 'Submit',
+				} )
+			);
+
+			const formData = handleSubmit.mock.results[ 0 ].value;
+			expect( formData.get( 'country' ) ).toBe( '' );
+		} );
+	} );
+} );

package/src/form/select-control/types.ts

@@ -0,0 +1,50 @@
+import type React from 'react';
+import type { ControlProps } from '../types';
+import type {
+	SelectRootProps,
+	SelectTriggerProps,
+} from '../primitives/select/types';
+
+export type SelectItem = {
+	label: string;
+	value: string | null;
+	disabled?: boolean;
+};
+
+export type SelectControlProps = Omit<
+	SelectRootProps< SelectItem >,
+	'items' | 'inputRef'
+> &
+	ControlProps & {
+		/**
+		 * CSS class to apply.
+		 */
+		className?: string;
+		/**
+		 * The array of option items to render in the select.
+		 */
+		items?: SelectItem[];
+		/**
+		 * Text to show when no value is selected. This is overridden by `triggerContent`
+		 * if specified, or by a null item's label in `items`.
+		 *
+		 * @default __( 'Select' )
+		 */
+		placeholder?: SelectTriggerProps[ 'placeholder' ];
+		/**
+		 * The custom trigger content to use instead of the default.
+		 *
+		 * ```jsx
+		 * triggerContent={ ( item ) => item.label }
+		 * ```
+		 */
+		triggerContent?:
+			| ( ( item: SelectItem ) => React.ReactNode )
+			| React.ReactNode;
+		/**
+		 * The size of the control.
+		 *
+		 * @default 'default'
+		 */
+		size?: Exclude< SelectTriggerProps[ 'size' ], 'small' >;
+	};

package/src/form/types.ts

@@ -4,7 +4,7 @@ export type ControlProps = {
 	/**
 	 * The accessible label. All controls must be labeled.
 	 */
-	label: React.ComponentProps< typeof Field.Label >[ 'children' ];
+	label: string;
 	/**
 	 * The accessible description, associated using `aria-describedby`.
 	 *

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

@@ -18,6 +18,13 @@ const meta: Meta< typeof Icon > = {
 			);
 		},
 	],
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending a general readiness review. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/icon-button/icon-button.tsx

@@ -22,6 +22,7 @@ export const IconButton = forwardRef< HTMLButtonElement, IconButtonProps >(
 			icon,
 			size,
 			shortcut,
+			positioner,
 			...restProps
 		}: IconButtonProps & { children?: unknown },
 		ref
@@ -52,7 +53,7 @@ export const IconButton = forwardRef< HTMLButtonElement, IconButtonProps >(
 							className={ styles.icon }
 						/>
 					</Tooltip.Trigger>
-					<Tooltip.Popup>
+					<Tooltip.Popup positioner={ positioner }>
 						{ label }
 						{ shortcut && (
 							<>

package/src/icon-button/stories/index.story.tsx

@@ -11,6 +11,7 @@ import {
 } from '@wordpress/icons';
 import { displayShortcut, ariaKeyShortcut } from '@wordpress/keycodes';
 import { IconButton } from '../index';
+import * as Tooltip from '../../tooltip';
 
 const meta: Meta< typeof IconButton > = {
 	title: 'Design System/Components/IconButton',
@@ -20,6 +21,13 @@ const meta: Meta< typeof IconButton > = {
 			control: { type: 'boolean' },
 		},
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components`, text overflow behavior, and overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 
@@ -126,3 +134,15 @@ export const WithShortcut: Story = {
 		shortcut: EXAMPLE_SHORTCUT_OBJECT,
 	},
 };
+
+/**
+ * Customize where the tooltip appears relative to the button by passing a
+ * `<Tooltip.Positioner />` element with a `side` to the `positioner` prop.
+ */
+export const WithCustomPositioner: Story = {
+	...Default,
+	args: {
+		...Default.args,
+		positioner: <Tooltip.Positioner side="right" />,
+	},
+};

package/src/icon-button/types.ts

@@ -1,5 +1,6 @@
 import { type ButtonProps } from '../button/types';
 import { type IconProps } from '../icon/types';
+import { type PopupProps as TooltipPopupProps } from '../tooltip/types';
 
 export type IconButtonProps = Omit< ButtonProps, 'children' > & {
 	/**
@@ -35,4 +36,12 @@ export type IconButtonProps = Omit< ButtonProps, 'children' > & {
 		 */
 		ariaKeyShortcut: string;
 	};
+
+	/**
+	 * Customize how the tooltip is positioned relative to the button. Accepts
+	 * a `<Tooltip.Positioner />` element with custom positioning props
+	 * (`side`, `align`, `sideOffset`, collision settings, etc.). When omitted,
+	 * the tooltip uses the default placement.
+	 */
+	positioner?: TooltipPopupProps[ 'positioner' ];
 };

package/src/index.ts

@@ -5,6 +5,7 @@ export * as Collapsible from './collapsible';
 export * as CollapsibleCard from './collapsible-card';
 export * as AlertDialog from './alert-dialog';
 export * as Dialog from './dialog';
+export * as Drawer from './drawer';
 export * as EmptyState from './empty-state';
 export * from './form';
 export * from './icon';

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

@@ -6,6 +6,13 @@ import { Text } from '../../text';
 const meta: Meta< typeof Link > = {
 	title: 'Design System/Components/Link',
 	component: Link,
+	tags: [ 'manifest' ],
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 
@@ -66,9 +73,8 @@ export const Inline: Story = {
 };
 
 /**
- * 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).
+ * When composing `Text` and `Link` via the `render` prop, keep `Text` as the
+ * host and pass `Link` via `render` so the resulting element stays an `<a>`.
  */
 export const Standalone: Story = {
 	args: {
@@ -80,13 +86,8 @@ export const Standalone: Story = {
 		},
 	},
 	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>
+		<Text variant="body-md" render={ <Link { ...args } /> }>
+			A standalone link with body-md typography
+		</Text>
 	),
 };

package/src/link/style.module.css

@@ -3,7 +3,7 @@
 @layer wp-ui-components {
 	.link {
 		text-underline-offset: 0.2em;
-		text-decoration-thickness: 0.5px;
+		text-decoration-thickness: from-font;
 	}
 
 	/* Brand tone */
@@ -50,6 +50,7 @@
 	 * inline-block so the link underline stays scoped to the text. */
 
 	.link-icon {
+		line-height: 1;
 		display: inline-block;
 		margin-inline-start: var(--wpds-dimension-padding-xs);
 		font-weight: var(--wpds-typography-font-weight-regular);

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

@@ -12,6 +12,13 @@ const meta: Meta< typeof Notice.Root > = {
 		'Notice.ActionButton': Notice.ActionButton,
 		'Notice.ActionLink': Notice.ActionLink,
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components`. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/popover/context.tsx

@@ -1,116 +1,17 @@
-import {
-	createContext,
-	useCallback,
-	useContext,
-	useEffect,
-	useMemo,
-	useRef,
-} from '@wordpress/element';
-import { useScheduleValidation } from '../utils/use-schedule-validation';
+import { createOverlayTitleValidation } from '../utils/create-overlay-title-validation';
 
-/**
- * Whether validation is enabled. This is a build-time constant that allows
- * bundlers to tree-shake all validation code in production builds.
- */
-const VALIDATION_ENABLED = process.env.NODE_ENV !== 'production';
-
-type PopoverValidationContextType = {
-	registerTitle: ( element: HTMLElement | null ) => () => void;
-};
-
-const PopoverValidationContext = VALIDATION_ENABLED
-	? createContext< PopoverValidationContextType | null >( null )
-	: ( null as unknown as React.Context< PopoverValidationContextType | null > );
-
-function usePopoverValidationContextDev() {
-	return useContext( PopoverValidationContext );
-}
-
-function usePopoverValidationContextProd() {
-	return null;
-}
+const popoverTitleValidation = createOverlayTitleValidation( 'Popover' );
 
 /**
  * Hook to access the popover validation context.
  * Returns null in production or if not within a Popover.Popup.
  */
-export const usePopoverValidationContext = VALIDATION_ENABLED
-	? usePopoverValidationContextDev
-	: usePopoverValidationContextProd;
-
-/**
- * Development-only provider that tracks whether Popover.Title is rendered.
- */
-function PopoverValidationProviderDev( {
-	children,
-}: {
-	children: React.ReactNode;
-} ) {
-	const titleElementRef = useRef< HTMLElement | null >( null );
-
-	const scheduleValidation = useScheduleValidation( () => {
-		const titleElement = titleElementRef.current;
-
-		if ( ! titleElement ) {
-			throw new Error(
-				'Popover: Missing <Popover.Title>. ' +
-					'For accessibility, every popover requires a title. ' +
-					'If needed, the title can be visually hidden but must not be omitted.'
-			);
-		}
-
-		const textContent = titleElement.textContent?.trim();
-		if ( ! textContent ) {
-			throw new Error(
-				'Popover: <Popover.Title> cannot be empty. ' +
-					'Provide meaningful text content for the popover title.'
-			);
-		}
-	} );
-
-	const registerTitle = useCallback(
-		( element: HTMLElement | null ) => {
-			titleElementRef.current = element;
-			scheduleValidation();
-
-			return () => {
-				titleElementRef.current = null;
-				scheduleValidation();
-			};
-		},
-		[ scheduleValidation ]
-	);
-
-	// Schedule an initial validation on mount to catch missing titles
-	// (when no Title component is rendered, registerTitle is never called).
-	useEffect( () => {
-		scheduleValidation();
-	}, [ scheduleValidation ] );
-
-	const contextValue = useMemo(
-		() => ( { registerTitle } ),
-		[ registerTitle ]
-	);
-
-	return (
-		<PopoverValidationContext.Provider value={ contextValue }>
-			{ children }
-		</PopoverValidationContext.Provider>
-	);
-}
-
-function PopoverValidationProviderProd( {
-	children,
-}: {
-	children: React.ReactNode;
-} ) {
-	return <>{ children }</>;
-}
+export const usePopoverValidationContext =
+	popoverTitleValidation.useValidationContext;
 
 /**
  * Provider component that validates Popover.Title presence in development mode.
  * In production, this component is a no-op and just renders children.
  */
-export const PopoverValidationProvider = VALIDATION_ENABLED
-	? PopoverValidationProviderDev
-	: PopoverValidationProviderProd;
+export const PopoverValidationProvider =
+	popoverTitleValidation.ValidationProvider;

package/src/popover/description.tsx

@@ -1,24 +1,20 @@
 import { Popover as _Popover } from '@base-ui/react/popover';
-import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
 import { Text } from '../text';
-import styles from './style.module.css';
 import type { DescriptionProps } from './types';
 
 /**
  * Renders an optional paragraph that describes the popover content.
  *
  * The rendered element is linked to the popup via `aria-describedby`.
- * Uses the `body-md` text variant by default.
  */
 const Description = forwardRef< HTMLParagraphElement, DescriptionProps >(
-	function PopoverDescription( { className, children, ...props }, ref ) {
+	function PopoverDescription( { children, ...props }, ref ) {
 		return (
 			<Text
 				ref={ ref }
 				variant="body-md"
 				render={ <_Popover.Description { ...props } /> }
-				className={ clsx( styles.description, className ) }
 			>
 				{ children }
 			</Text>

package/src/popover/index.ts

@@ -2,8 +2,9 @@ import { Arrow } from './arrow';
 import { Close } from './close';
 import { Description } from './description';
 import { Popup } from './popup';
+import { Portal } from './portal';
 import { Root } from './root';
 import { Title } from './title';
 import { Trigger } from './trigger';
 
-export { Arrow, Close, Description, Popup, Root, Title, Trigger };
+export { Arrow, Close, Description, Portal, Popup, Root, Title, Trigger };

package/src/popover/popup.tsx

@@ -9,7 +9,9 @@ import {
 import { unlock } from '../lock-unlock';
 import resetStyles from '../utils/css/resets.module.css';
 import { useDeprioritizedInitialFocus } from '../utils/use-deprioritized-initial-focus';
+import { renderSlotWithChildren } from '../utils/render-slot-with-children';
 import { PopoverValidationProvider } from './context';
+import { Portal } from './portal';
 import styles from './style.module.css';
 import type { PopupProps } from './types';
 
@@ -22,8 +24,9 @@ const CLOSE_ATTR = 'data-wp-ui-popover-close';
  * Renders the floating popup container for the popover content.
  *
  * Handles portal rendering, positioning relative to the anchor, collision
- * avoidance, focus management, and optional backdrop. Supply a `container`
- * element for cross-document scenarios such as iframes.
+ * avoidance, focus management, and optional backdrop. Use
+ * `portal={ <Popover.Portal container={ ... } /> }` for cross-document
+ * scenarios such as iframes.
  */
 const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 	{
@@ -38,13 +41,12 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 		collisionAvoidance,
 		collisionBoundary,
 		collisionPadding,
-		container,
+		portal,
 		finalFocus,
 		initialFocus,
 		side = 'bottom',
 		sideOffset = 8,
 		sticky,
-		style,
 		variant = 'default',
 		...props
 	},
@@ -52,7 +54,7 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 ) {
 	const { resolvedInitialFocus, popupRef } = useDeprioritizedInitialFocus( {
 		initialFocus,
-		deprioritizedAttribute: CLOSE_ATTR,
+		deprioritizedAttributes: [ CLOSE_ATTR ],
 	} );
 	const mergedPopupRef = useMergeRefs( [ ref, popupRef ] );
 
@@ -72,12 +74,7 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 			side={ side }
 			sideOffset={ sideOffset }
 			sticky={ sticky }
-			style={ style }
-			className={ clsx(
-				resetStyles[ 'box-sizing' ],
-				styles.positioner,
-				className
-			) }
+			className={ clsx( resetStyles[ 'box-sizing' ], styles.positioner ) }
 		>
 			<ThemeProvider>
 				<_Popover.Popup
@@ -85,8 +82,8 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 					initialFocus={ resolvedInitialFocus }
 					finalFocus={ finalFocus }
 					className={ clsx(
-						styles.popup,
-						variant !== 'unstyled' && styles.default
+						variant !== 'unstyled' && styles.popup,
+						className
 					) }
 					{ ...props }
 				>
@@ -98,12 +95,14 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 		</_Popover.Positioner>
 	);
 
-	return (
-		<_Popover.Portal container={ container }>
+	const portalChildren = (
+		<>
 			{ backdropElement }
 			{ positioner }
-		</_Popover.Portal>
+		</>
 	);
+
+	return renderSlotWithChildren( portal, <Portal />, portalChildren );
 } );
 
 export { Popup };