@wordpress/ui 0.13.1-next.v.202605131032.0 → 0.15.0

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

@@ -7,49 +7,45 @@ import {
 } from '@wordpress/theme';
 import { unlock } from '../../../lock-unlock';
 import { Portal } from './portal';
+import { Positioner } from './positioner';
 import { renderSlotWithChildren } from '../../../utils/render-slot-with-children';
 import itemPopupStyles from '../../../utils/css/item-popup.module.css';
-import resetStyles from '../../../utils/css/resets.module.css';
-import styles from './style.module.css';
 import type { SelectPopupProps } from './types';
-import { ITEM_POPUP_POSITIONER_PROPS } from '../constants';
 
 const ThemeProvider: typeof ThemeProviderType =
 	unlock( themePrivateApis ).ThemeProvider;
 
 export const Popup = forwardRef< HTMLDivElement, SelectPopupProps >(
-	function Popup( { className, portal, children, ...restProps }, ref ) {
-		const portalChildren = (
-			<_Select.Positioner
-				{ ...ITEM_POPUP_POSITIONER_PROPS }
-				alignItemWithTrigger={ false }
-				className={ clsx(
-					resetStyles[ 'box-sizing' ],
-					styles.positioner
-				) }
-			>
-				<ThemeProvider>
-					<_Select.Popup
-						ref={ ref }
-						className={ clsx( itemPopupStyles.popup, className ) }
-						{ ...restProps }
-					>
-						<_Select.List className={ itemPopupStyles.list }>
-							<div
-								className={
-									itemPopupStyles[
-										'list-scrollable-container'
-									]
-								}
-							>
-								{ children }
-							</div>
-						</_Select.List>
-					</_Select.Popup>
-				</ThemeProvider>
-			</_Select.Positioner>
+	function Popup(
+		{ className, portal, positioner, children, ...restProps },
+		ref
+	) {
+		const popupContent = (
+			<ThemeProvider>
+				<_Select.Popup
+					ref={ ref }
+					className={ clsx( itemPopupStyles.popup, className ) }
+					{ ...restProps }
+				>
+					<_Select.List className={ itemPopupStyles.list }>
+						<div
+							className={
+								itemPopupStyles[ 'list-scrollable-container' ]
+							}
+						>
+							{ children }
+						</div>
+					</_Select.List>
+				</_Select.Popup>
+			</ThemeProvider>
 		);
 
-		return renderSlotWithChildren( portal, <Portal />, portalChildren );
+		const positionedPopup = renderSlotWithChildren(
+			positioner,
+			<Positioner />,
+			popupContent
+		);
+
+		return renderSlotWithChildren( portal, <Portal />, positionedPopup );
 	}
 );

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

@@ -1,16 +1,23 @@
 import { Select as _Select } from '@base-ui/react/select';
 import { forwardRef } from '@wordpress/element';
 import type { PortalProps } from './types';
+import { getWpCompatOverlaySlot } from '../../../utils/wp-compat-overlay-slot';
 
 /**
- * Root element that portals `Select` listbox content. Pass to
- * `Select.Popup`'s `portal` prop. When `portal` is omitted, `Select.Popup`
- * uses this component with default props.
+ * Used to apply custom portal behavior to `Select`'s listbox content.
+ * `container` defaults to the `@wordpress/ui` compat overlay slot.
  */
-const Portal = forwardRef< HTMLDivElement, PortalProps >(
-	function SelectPortal( props, ref ) {
-		return <_Select.Portal ref={ ref } { ...props } />;
-	}
-);
+const Portal = forwardRef< HTMLDivElement, PortalProps >( function SelectPortal(
+	{ container, ...restProps },
+	ref
+) {
+	return (
+		<_Select.Portal
+			container={ container ?? getWpCompatOverlaySlot() }
+			{ ...restProps }
+			ref={ ref }
+		/>
+	);
+} );
 
 export { Portal };

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

@@ -0,0 +1,33 @@
+import clsx from 'clsx';
+import { Select as _Select } from '@base-ui/react/select';
+import { forwardRef } from '@wordpress/element';
+import type { PositionerProps } from './types';
+import resetStyles from '../../../utils/css/resets.module.css';
+import styles from './style.module.css';
+import { ITEM_POPUP_POSITIONER_PROPS } from '../constants';
+
+/**
+ * Used to apply custom positioning to `Select`'s listbox content.
+ */
+const Positioner = forwardRef< HTMLDivElement, PositionerProps >(
+	function SelectPositioner( { className, ...props }, ref ) {
+		return (
+			<_Select.Positioner
+				{ ...ITEM_POPUP_POSITIONER_PROPS }
+				// Override Base UI's `true` default so the popup is placed
+				// relative to the trigger rather than aligned with the
+				// highlighted item. Consumers can opt back in by passing `true`.
+				alignItemWithTrigger={ false }
+				{ ...props }
+				ref={ ref }
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					styles.positioner,
+					className
+				) }
+			/>
+		);
+	}
+);
+
+export { Positioner };

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

@@ -7,6 +7,7 @@ const meta: Meta< typeof Select.Root > = {
 	subcomponents: {
 		'Select.Trigger': Select.Trigger,
 		'Select.Portal': Select.Portal,
+		'Select.Positioner': Select.Positioner,
 		'Select.Popup': Select.Popup,
 		'Select.Item': Select.Item,
 	},

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

@@ -1,7 +1,9 @@
 import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { createRef } from '@wordpress/element';
+import type { ReactNode } from 'react';
 import * as Select from '../index';
+import { useEnableWpCompatOverlaySlot } from '../../../../utils/use-enable-wp-compat-overlay-slot';
 
 describe( 'Select', () => {
 	it( 'supports object item values', async () => {
@@ -211,4 +213,136 @@ describe( 'Select', () => {
 			);
 		} );
 	} );
+
+	describe( 'positioner', () => {
+		it( 'should render the custom positioner element wrapping the popup content', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<Select.Root>
+					<Select.Trigger />
+					<Select.Popup
+						positioner={
+							<Select.Positioner data-testid="custom-positioner" />
+						}
+					>
+						<Select.Item value="Item 1">Item 1</Select.Item>
+					</Select.Popup>
+				</Select.Root>
+			);
+
+			await user.click( screen.getByRole( 'combobox' ) );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			const positioner = screen.getByTestId( 'custom-positioner' );
+
+			expect( positioner ).toContainElement( item );
+		} );
+	} );
+
+	// Slot is identified by a data attribute, not a user-facing role/text.
+	/* eslint-disable testing-library/no-node-access */
+	describe( 'wp compat overlay slot', () => {
+		const SLOT_SELECTOR = '[data-wp-compat-overlay-slot]';
+
+		// Exercises the public opt-in path rather than poking the flag.
+		function WithSlotEnabled( { children }: { children: ReactNode } ) {
+			useEnableWpCompatOverlaySlot();
+			return <>{ children }</>;
+		}
+
+		afterEach( () => {
+			// The hook is one-way at runtime; reset explicitly between tests.
+			delete ( window as { __wpUiCompatOverlaySlotEnabled?: boolean } )
+				.__wpUiCompatOverlaySlotEnabled;
+			document
+				.querySelectorAll( SLOT_SELECTOR )
+				.forEach( ( el ) => el.remove() );
+		} );
+
+		it( 'portals the popup into the slot when the consumer opts in', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<WithSlotEnabled>
+					<Select.Root>
+						<Select.Trigger />
+						<Select.Popup>
+							<Select.Item value="Item 1">Item 1</Select.Item>
+						</Select.Popup>
+					</Select.Root>
+				</WithSlotEnabled>
+			);
+
+			await user.click( screen.getByRole( 'combobox' ) );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			expect( item ).toBeVisible();
+
+			const slot = document.querySelector( SLOT_SELECTOR );
+			expect( slot ).not.toBeNull();
+			expect( slot ).toContainElement( item );
+		} );
+
+		it( 'does not create a slot when the consumer has not opted in (dormant default)', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<Select.Root>
+					<Select.Trigger />
+					<Select.Popup>
+						<Select.Item value="Item 1">Item 1</Select.Item>
+					</Select.Popup>
+				</Select.Root>
+			);
+
+			await user.click( screen.getByRole( 'combobox' ) );
+
+			const item = await screen.findByRole( 'option', {
+				name: 'Item 1',
+			} );
+			expect( item ).toBeVisible();
+
+			expect( document.querySelector( SLOT_SELECTOR ) ).toBeNull();
+		} );
+
+		it( 'lets a caller-supplied portal container override the slot', async () => {
+			const user = userEvent.setup();
+			const containerRef = createRef< HTMLDivElement >();
+
+			render(
+				<WithSlotEnabled>
+					<Select.Root>
+						<Select.Trigger />
+						<div
+							ref={ containerRef }
+							data-testid="custom-container"
+						/>
+						<Select.Popup
+							portal={
+								<Select.Portal container={ containerRef } />
+							}
+						>
+							<Select.Item value="Item 1">Item 1</Select.Item>
+						</Select.Popup>
+					</Select.Root>
+				</WithSlotEnabled>
+			);
+
+			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
+			);
+		} );
+	} );
+	/* eslint-enable testing-library/no-node-access */
 } );

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

@@ -1,10 +1,12 @@
 import type { Select as _Select } from '@base-ui/react/select';
-import type { ComponentPropsWithoutRef, ReactElement } from 'react';
+import type { ReactElement } from 'react';
 
 import type { ComponentProps } from '../../../utils/types';
 import type { InputLayoutProps } from '../input-layout/types';
 
-export type PortalProps = ComponentPropsWithoutRef< typeof _Select.Portal >;
+export type PortalProps = ComponentProps< typeof _Select.Portal >;
+
+export type PositionerProps = ComponentProps< typeof _Select.Positioner >;
 
 // The second type parameter is the `multiple` flag (currently disabled).
 export type SelectRootProps< Value = unknown > = Omit<
@@ -54,6 +56,14 @@ export type SelectPopupProps = ComponentProps< typeof _Select.Popup > & {
 	 * be ignored.
 	 */
 	portal?: ReactElement< Omit< PortalProps, 'children' > >;
+	/**
+	 * Optional positioner element, typically `<Select.Positioner />` with
+	 * custom positioning props (`side`, `align`, `sideOffset`, collision
+	 * settings, etc.). When omitted, `Select.Popup` uses `Select.Positioner`
+	 * with default props. Do not pass `children` on the positioner element;
+	 * they would be ignored.
+	 */
+	positioner?: ReactElement< Omit< PositionerProps, 'children' > >;
 };
 
 export type SelectItemProps = Omit<

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

@@ -1,7 +1,9 @@
 import { act, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { createRef } from '@wordpress/element';
+import type { ReactNode } from 'react';
 import { SelectControl } from '../index';
+import { useEnableWpCompatOverlaySlot } from '../../../utils/use-enable-wp-compat-overlay-slot';
 
 describe( 'SelectControl', () => {
 	const mockItems = [
@@ -193,4 +195,66 @@ describe( 'SelectControl', () => {
 			expect( formData.get( 'country' ) ).toBe( '' );
 		} );
 	} );
+
+	// Slot is identified by a data attribute, not a user-facing role/text.
+	/* eslint-disable testing-library/no-node-access */
+	describe( 'wp compat overlay slot', () => {
+		const SLOT_SELECTOR = '[data-wp-compat-overlay-slot]';
+
+		// Exercises the public opt-in path rather than poking the flag.
+		function WithSlotEnabled( { children }: { children: ReactNode } ) {
+			useEnableWpCompatOverlaySlot();
+			return <>{ children }</>;
+		}
+
+		afterEach( () => {
+			// The hook is one-way at runtime; reset explicitly between tests.
+			delete ( window as { __wpUiCompatOverlaySlotEnabled?: boolean } )
+				.__wpUiCompatOverlaySlotEnabled;
+			document
+				.querySelectorAll( SLOT_SELECTOR )
+				.forEach( ( el ) => el.remove() );
+		} );
+
+		it( 'portals the popup into the slot when the consumer opts in', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<WithSlotEnabled>
+					<SelectControl label="Country" items={ mockItems } />
+				</WithSlotEnabled>
+			);
+
+			await user.click(
+				screen.getByRole( 'combobox', { name: 'Country' } )
+			);
+
+			const option = await screen.findByRole( 'option', {
+				name: 'Option 1',
+			} );
+			expect( option ).toBeVisible();
+
+			const slot = document.querySelector( SLOT_SELECTOR );
+			expect( slot ).not.toBeNull();
+			expect( slot ).toContainElement( option );
+		} );
+
+		it( 'does not create a slot when the consumer has not opted in (dormant default)', async () => {
+			const user = userEvent.setup();
+
+			render( <SelectControl label="Country" items={ mockItems } /> );
+
+			await user.click(
+				screen.getByRole( 'combobox', { name: 'Country' } )
+			);
+
+			const option = await screen.findByRole( 'option', {
+				name: 'Option 1',
+			} );
+			expect( option ).toBeVisible();
+
+			expect( document.querySelector( SLOT_SELECTOR ) ).toBeNull();
+		} );
+	} );
+	/* eslint-enable testing-library/no-node-access */
 } );

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

@@ -5,6 +5,7 @@ import { Icon } from '../index';
 const meta: Meta< typeof Icon > = {
 	title: 'Design System/Components/Icon',
 	component: Icon,
+	tags: [ 'manifest' ],
 	decorators: [
 		( Story ) => {
 			return (
@@ -20,9 +21,9 @@ const meta: Meta< typeof Icon > = {
 	],
 	parameters: {
 		componentStatus: {
-			status: 'use-with-caution',
+			status: 'recommended',
 			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).',
+			notes: 'Prefer this component over the `Icon` component from `@wordpress/components` or `@wordpress/icons`.',
 		},
 	},
 };

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

@@ -18,7 +18,7 @@ export const IconButton = forwardRef< HTMLButtonElement, IconButtonProps >(
 			// Prevent accidental forwarding of `children`
 			children: _children,
 			disabled,
-			focusableWhenDisabled,
+			focusableWhenDisabled = true,
 			icon,
 			size,
 			shortcut,

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

@@ -37,7 +37,14 @@ describe( 'IconButton', () => {
 		it( 'does not show tooltip when truly disabled', async () => {
 			const user = userEvent.setup();
 
-			render( <IconButton label="Save" icon={ <svg /> } disabled /> );
+			render(
+				<IconButton
+					label="Save"
+					icon={ <svg /> }
+					disabled
+					focusableWhenDisabled={ false }
+				/>
+			);
 
 			const button = screen.getByRole( 'button', { name: 'Save' } );
 			await user.hover( button );
@@ -45,17 +52,10 @@ describe( 'IconButton', () => {
 			expect( screen.queryByText( 'Save' ) ).not.toBeInTheDocument();
 		} );
 
-		it( 'shows tooltip when focusably disabled', async () => {
+		it( 'shows tooltip when disabled by default', async () => {
 			const user = userEvent.setup();
 
-			render(
-				<IconButton
-					label="Save"
-					icon={ <svg /> }
-					disabled
-					focusableWhenDisabled
-				/>
-			);
+			render( <IconButton label="Save" icon={ <svg /> } disabled /> );
 
 			const button = screen.getByRole( 'button', { name: 'Save' } );
 			await user.hover( button );

package/src/index.ts

@@ -17,4 +17,6 @@ export * from './stack';
 export * as Tabs from './tabs';
 export * from './text';
 export * as Tooltip from './tooltip';
+export { getWpCompatOverlaySlot } from './utils/wp-compat-overlay-slot';
+export { useEnableWpCompatOverlaySlot } from './utils/use-enable-wp-compat-overlay-slot';
 export * from './visually-hidden';

package/src/popover/index.ts

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

package/src/popover/popup.tsx

@@ -7,11 +7,11 @@ import {
 	privateApis as themePrivateApis,
 } from '@wordpress/theme';
 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 { Positioner } from './positioner';
 import styles from './style.module.css';
 import type { PopupProps } from './types';
 
@@ -26,27 +26,18 @@ const CLOSE_ATTR = 'data-wp-ui-popover-close';
  * Handles portal rendering, positioning relative to the anchor, collision
  * avoidance, focus management, and optional backdrop. Use
  * `portal={ <Popover.Portal container={ ... } /> }` for cross-document
- * scenarios such as iframes.
+ * scenarios such as iframes, and `positioner={ <Popover.Positioner … /> }`
+ * to customize placement.
  */
 const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 	{
-		align = 'center',
-		alignOffset,
-		anchor,
-		// Matches the popup's border-radius (--wpds-border-radius-md).
-		arrowPadding = 8,
 		backdrop = false,
 		children,
 		className,
-		collisionAvoidance,
-		collisionBoundary,
-		collisionPadding,
 		portal,
+		positioner,
 		finalFocus,
 		initialFocus,
-		side = 'bottom',
-		sideOffset = 8,
-		sticky,
 		variant = 'default',
 		...props
 	},
@@ -62,43 +53,35 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 		<_Popover.Backdrop className={ styles.backdrop } />
 	) : null;
 
-	const positioner = (
-		<_Popover.Positioner
-			align={ align }
-			alignOffset={ alignOffset }
-			anchor={ anchor }
-			arrowPadding={ arrowPadding }
-			collisionAvoidance={ collisionAvoidance }
-			collisionBoundary={ collisionBoundary }
-			collisionPadding={ collisionPadding }
-			side={ side }
-			sideOffset={ sideOffset }
-			sticky={ sticky }
-			className={ clsx( resetStyles[ 'box-sizing' ], styles.positioner ) }
-		>
-			<ThemeProvider>
-				<_Popover.Popup
-					ref={ mergedPopupRef }
-					initialFocus={ resolvedInitialFocus }
-					finalFocus={ finalFocus }
-					className={ clsx(
-						variant !== 'unstyled' && styles.popup,
-						className
-					) }
-					{ ...props }
-				>
-					<PopoverValidationProvider>
-						{ children }
-					</PopoverValidationProvider>
-				</_Popover.Popup>
-			</ThemeProvider>
-		</_Popover.Positioner>
+	const popupContent = (
+		<ThemeProvider>
+			<_Popover.Popup
+				ref={ mergedPopupRef }
+				initialFocus={ resolvedInitialFocus }
+				finalFocus={ finalFocus }
+				className={ clsx(
+					variant !== 'unstyled' && styles.popup,
+					className
+				) }
+				{ ...props }
+			>
+				<PopoverValidationProvider>
+					{ children }
+				</PopoverValidationProvider>
+			</_Popover.Popup>
+		</ThemeProvider>
+	);
+
+	const positionedPopup = renderSlotWithChildren(
+		positioner,
+		<Positioner />,
+		popupContent
 	);
 
 	const portalChildren = (
 		<>
 			{ backdropElement }
-			{ positioner }
+			{ positionedPopup }
 		</>
 	);
 

package/src/popover/portal.tsx

@@ -3,10 +3,7 @@ import { forwardRef } from '@wordpress/element';
 import type { PortalProps } from './types';
 
 /**
- * Root element that portals `Popover` floating content. Pass to
- * `Popover.Popup`'s `portal` prop (for example `container` for
- * cross-document rendering). When `portal` is omitted, `Popover.Popup` uses
- * this component with default props.
+ * Used to apply custom portal behavior to `Popover`'s floating content.
  */
 const Portal = forwardRef< HTMLDivElement, PortalProps >(
 	function PopoverPortal( props, ref ) {

package/src/popover/positioner.tsx

@@ -0,0 +1,42 @@
+import clsx from 'clsx';
+import { Popover as _Popover } from '@base-ui/react/popover';
+import { forwardRef } from '@wordpress/element';
+import type { PositionerProps } from './types';
+import resetStyles from '../utils/css/resets.module.css';
+import styles from './style.module.css';
+
+/**
+ * Used to apply custom positioning to `Popover`'s floating content.
+ */
+const Positioner = forwardRef< HTMLDivElement, PositionerProps >(
+	function PopoverPositioner(
+		{
+			align = 'center',
+			// Matches the popup's border-radius (--wpds-border-radius-md).
+			arrowPadding = 8,
+			className,
+			side = 'bottom',
+			sideOffset = 8,
+			...props
+		},
+		ref
+	) {
+		return (
+			<_Popover.Positioner
+				ref={ ref }
+				align={ align }
+				arrowPadding={ arrowPadding }
+				side={ side }
+				sideOffset={ sideOffset }
+				{ ...props }
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					styles.positioner,
+					className
+				) }
+			/>
+		);
+	}
+);
+
+export { Positioner };