@wordpress/ui 0.13.1-next.v.202605131006.0 → 0.14.0

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

@@ -1,6 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useId, useRef, useState } from '@wordpress/element';
-import { SlotFillProvider, Slot } from '@wordpress/components';
 import { close, info } from '@wordpress/icons';
 import * as Popover from '../';
 import { VisuallyHidden } from '../../visually-hidden';
@@ -14,6 +13,7 @@ const meta: Meta< typeof Popover.Root > = {
 	subcomponents: {
 		'Popover.Trigger': Popover.Trigger,
 		'Popover.Portal': Popover.Portal,
+		'Popover.Positioner': Popover.Positioner,
 		'Popover.Popup': Popover.Popup,
 		'Popover.Arrow': Popover.Arrow,
 		'Popover.Title': Popover.Title,
@@ -88,7 +88,7 @@ export const NoArrow: Story = {
 };
 
 /**
- * All combinations of `side` and `align` props on `Popover.Popup`.
+ * All combinations of `side` and `align` props on `Popover.Positioner`.
  *
  * Each row shows a side (`top`, `right`, `bottom`, `left`), and each column
  * shows an alignment (`start`, `center`, `end`).
@@ -116,12 +116,16 @@ export const Positioning: Story = {
 								{ side } / { align }
 							</Popover.Trigger>
 							<Popover.Popup
-								side={ side }
-								align={ align }
-								collisionAvoidance={ {
-									side: 'none',
-									align: 'none',
-								} }
+								positioner={
+									<Popover.Positioner
+										side={ side }
+										align={ align }
+										collisionAvoidance={ {
+											side: 'none',
+											align: 'none',
+										} }
+									/>
+								}
 							>
 								<VisuallyHidden render={ <Popover.Title /> }>
 									{ side } / { align }
@@ -416,16 +420,21 @@ export const OverlayPlacement: Story = {
 					</Popover.Trigger>
 					<Popover.Popup
 						ref={ popupRef }
-						side="bottom"
-						align="center"
-						sideOffset={
-							-1 *
-							( popupSize.height / 2 + triggerSize.height / 2 )
+						positioner={
+							<Popover.Positioner
+								side="bottom"
+								align="center"
+								sideOffset={
+									-1 *
+									( popupSize.height / 2 +
+										triggerSize.height / 2 )
+								}
+								collisionAvoidance={ {
+									side: 'none',
+									align: 'none',
+								} }
+							/>
 						}
-						collisionAvoidance={ {
-							side: 'none',
-							align: 'none',
-						} }
 					>
 						<Popover.Title
 							style={ {
@@ -538,8 +547,12 @@ export const CollisionAvoidance: Story = {
 					<Popover.Root defaultOpen>
 						<Popover.Trigger>Flip (default)</Popover.Trigger>
 						<Popover.Popup
-							side="top"
-							collisionBoundary={ boundary ?? undefined }
+							positioner={
+								<Popover.Positioner
+									side="top"
+									collisionBoundary={ boundary ?? undefined }
+								/>
+							}
 						>
 							<Popover.Title
 								style={ {
@@ -558,12 +571,16 @@ export const CollisionAvoidance: Story = {
 					<Popover.Root defaultOpen>
 						<Popover.Trigger>No collision</Popover.Trigger>
 						<Popover.Popup
-							side="top"
-							collisionBoundary={ boundary ?? undefined }
-							collisionAvoidance={ {
-								side: 'none',
-								align: 'none',
-							} }
+							positioner={
+								<Popover.Positioner
+									side="top"
+									collisionBoundary={ boundary ?? undefined }
+									collisionAvoidance={ {
+										side: 'none',
+										align: 'none',
+									} }
+								/>
+							}
 						>
 							<Popover.Title
 								style={ {
@@ -646,8 +663,12 @@ export const CrossIframe: Story = {
 											}
 										/>
 									}
-									collisionBoundary={
-										iframeBoundary ?? undefined
+									positioner={
+										<Popover.Positioner
+											collisionBoundary={
+												iframeBoundary ?? undefined
+											}
+										/>
 									}
 								>
 									<Popover.Arrow />
@@ -675,98 +696,6 @@ export const CrossIframe: Story = {
 	},
 };
 
-/**
- * Same cross-iframe scenario, but using `SlotFillProvider` and `Slot` from
- * `@wordpress/components` as the render target.
- *
- * The `Slot` renders a `div` in the parent document, and its forwarded ref
- * is passed to `Popover.Portal`'s `container` prop (via `Popover.Popup`'s
- * `portal` prop) so the popup portals into the slot element. This mirrors the
- * legacy Popover's `WithSlotOutsideIframe` pattern.
- */
-export const CrossIframeWithSlotFill: Story = {
-	name: 'Cross-Iframe (SlotFill)',
-	args: { defaultOpen: true },
-	argTypes: { defaultOpen: { control: false } },
-	render: function Render( { children: _children, ...args } ) {
-		const slotRef = useRef< HTMLDivElement >( null );
-		const [ iframeBoundary, setIframeBoundary ] =
-			useState< HTMLIFrameElement | null >( null );
-
-		return (
-			<SlotFillProvider>
-				<Slot
-					name="popover-container"
-					bubblesVirtually
-					ref={ slotRef }
-				/>
-				<GenericIframe
-					ref={ setIframeBoundary }
-					style={ {
-						width: '100%',
-						height: 400,
-						border: 0,
-						outline: '1px solid purple',
-					} }
-				>
-					<div
-						style={ {
-							height: '200vh',
-							paddingTop: '10vh',
-						} }
-					>
-						<div
-							style={ {
-								maxWidth: 200,
-								marginTop: 100,
-								marginInline: 'auto',
-							} }
-						>
-							<Popover.Root { ...args }>
-								<Popover.Trigger
-									style={ {
-										padding: 8,
-										background: 'salmon',
-									} }
-								>
-									Popover&apos;s anchor (inside iframe)
-								</Popover.Trigger>
-								<Popover.Popup
-									portal={
-										<Popover.Portal
-											container={
-												slotRef as React.RefObject< HTMLElement >
-											}
-										/>
-									}
-									collisionBoundary={
-										iframeBoundary ?? undefined
-									}
-								>
-									<Popover.Arrow />
-									<Popover.Title
-										style={ {
-											marginBottom:
-												'var(--wpds-dimension-gap-xs)',
-										} }
-									>
-										Cross-Iframe (SlotFill)
-									</Popover.Title>
-									<Popover.Description>
-										This popup renders in the parent
-										document via a `Slot` from
-										`@wordpress/components`.
-									</Popover.Description>
-								</Popover.Popup>
-							</Popover.Root>
-						</div>
-					</div>
-				</GenericIframe>
-			</SlotFillProvider>
-		);
-	},
-};
-
 /**
  * Popovers in Gutenberg are managed with explicit z-index values, which can
  * create situations where a popover renders below another popover when you
@@ -816,9 +745,9 @@ export const WithCustomZIndex: Story = {
 };
 
 /**
- * Use the `anchor` prop on `Popover.Popup` to position the popover against an
- * arbitrary element instead of the built-in trigger. Base UI accepts four
- * anchor types:
+ * Pass an `anchor` to `Popover.Positioner` (via `Popover.Popup`'s `positioner`
+ * slot) to position the popover against an arbitrary element instead of the
+ * built-in trigger. `anchor` accepts four types:
  *
  * 1. **Element** — a direct DOM element reference.
  * 2. **VirtualElement** — an object with a `getBoundingClientRect()` method.
@@ -852,7 +781,7 @@ export const Anchor: Story = {
 			textAlign: 'center' as const,
 		};
 
-		const popupProps = {
+		const sharedPositionerProps = {
 			collisionAvoidance: {
 				side: 'none' as const,
 				align: 'none' as const,
@@ -875,8 +804,12 @@ export const Anchor: Story = {
 					</div>
 					<Popover.Root open>
 						<Popover.Popup
-							anchor={ elementAnchor ?? undefined }
-							{ ...popupProps }
+							positioner={
+								<Popover.Positioner
+									anchor={ elementAnchor ?? undefined }
+									{ ...sharedPositionerProps }
+								/>
+							}
 						>
 							<VisuallyHidden render={ <Popover.Title /> }>
 								Element anchor
@@ -896,8 +829,12 @@ export const Anchor: Story = {
 					</div>
 					<Popover.Root open>
 						<Popover.Popup
-							anchor={ virtualAnchor }
-							{ ...popupProps }
+							positioner={
+								<Popover.Positioner
+									anchor={ virtualAnchor }
+									{ ...sharedPositionerProps }
+								/>
+							}
 						>
 							<VisuallyHidden render={ <Popover.Title /> }>
 								Virtual anchor
@@ -916,7 +853,14 @@ export const Anchor: Story = {
 						RefObject anchor
 					</div>
 					<Popover.Root open>
-						<Popover.Popup anchor={ refAnchor } { ...popupProps }>
+						<Popover.Popup
+							positioner={
+								<Popover.Positioner
+									anchor={ refAnchor }
+									{ ...sharedPositionerProps }
+								/>
+							}
+						>
 							<VisuallyHidden render={ <Popover.Title /> }>
 								Ref anchor
 							</VisuallyHidden>
@@ -935,8 +879,12 @@ export const Anchor: Story = {
 					</div>
 					<Popover.Root open>
 						<Popover.Popup
-							anchor={ () => callbackTarget.current }
-							{ ...popupProps }
+							positioner={
+								<Popover.Positioner
+									anchor={ () => callbackTarget.current }
+									{ ...sharedPositionerProps }
+								/>
+							}
 						>
 							<VisuallyHidden render={ <Popover.Title /> }>
 								Callback anchor
@@ -991,13 +939,12 @@ export const ToolbarVariant: Story = {
 };
 
 /**
- * Base UI's Positioner exposes `--available-height` and
- * `--available-width` CSS variables representing the space
- * between the anchor and the viewport edge. Apply them as `max-height` /
- * `max-width` via the `style` prop (which targets the positioner) to
- * constrain the popup size. Then add `overflow: auto` on an inner wrapper
- * so scrolling happens inside the popup content area — this replaces the
- * legacy Popover's `resize` prop.
+ * `Popover.Positioner` exposes `--available-height` and `--available-width`
+ * CSS variables representing the space between the anchor and the viewport
+ * edge. These cascade down to `Popover.Popup`, where applying them as
+ * `max-height` / `max-width` via the `style` prop constrains the popup size.
+ * Then add `overflow: auto` on an inner wrapper so scrolling happens inside
+ * the popup content area — this replaces the legacy Popover's `resize` prop.
  *
  * Open the popover and resize or scroll the container to see the popup shrink
  * to fit.
@@ -1019,7 +966,7 @@ export const ViewportConstrainedSize: Story = {
 				<Popover.Root { ...args }>
 					<Popover.Trigger>Show Content</Popover.Trigger>
 					<Popover.Popup
-						side="bottom"
+						positioner={ <Popover.Positioner side="bottom" /> }
 						style={ {
 							maxHeight: 'var(--available-height, 300px)',
 							maxWidth: 'var(--available-width, 300px)',

package/src/popover/test/index.test.tsx

@@ -528,6 +528,35 @@ describe( 'Popover', () => {
 		} );
 	} );
 
+	describe( 'positioner', () => {
+		it( 'should render the custom positioner element wrapping the popup content', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<Popover.Root>
+					<Popover.Trigger>Open</Popover.Trigger>
+					<Popover.Popup
+						positioner={
+							<Popover.Positioner data-testid="custom-positioner" />
+						}
+					>
+						<Popover.Title>Title</Popover.Title>
+						Positioner slot content
+					</Popover.Popup>
+				</Popover.Root>
+			);
+
+			await user.click( screen.getByRole( 'button', { name: 'Open' } ) );
+
+			const content = await screen.findByText(
+				'Positioner slot content'
+			);
+			const positioner = screen.getByTestId( 'custom-positioner' );
+
+			expect( positioner ).toContainElement( content );
+		} );
+	} );
+
 	describe( 'anchor', () => {
 		it( 'should render the popup when an anchor element is provided without a trigger', async () => {
 			function AnchorTest() {
@@ -539,7 +568,13 @@ describe( 'Popover', () => {
 							Anchor element
 						</div>
 						<Popover.Root defaultOpen>
-							<Popover.Popup anchor={ anchorEl ?? undefined }>
+							<Popover.Popup
+								positioner={
+									<Popover.Positioner
+										anchor={ anchorEl ?? undefined }
+									/>
+								}
+							>
 								<Popover.Title>Title</Popover.Title>
 								Anchored content
 							</Popover.Popup>

package/src/popover/types.ts

@@ -1,9 +1,11 @@
-import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 import type { Popover as _Popover } from '@base-ui/react/popover';
 
 import type { ComponentProps } from '../utils/types';
 
-export type PortalProps = ComponentPropsWithoutRef< typeof _Popover.Portal >;
+export type PortalProps = ComponentProps< typeof _Popover.Portal >;
+
+export type PositionerProps = ComponentProps< typeof _Popover.Positioner >;
 
 export interface RootProps
 	extends Pick<
@@ -27,19 +29,6 @@ export interface TriggerProps
 
 export interface PopupProps
 	extends ComponentProps< 'div' >,
-		Pick<
-			_Popover.Positioner.Props,
-			| 'align'
-			| 'alignOffset'
-			| 'anchor'
-			| 'arrowPadding'
-			| 'collisionAvoidance'
-			| 'collisionBoundary'
-			| 'collisionPadding'
-			| 'side'
-			| 'sideOffset'
-			| 'sticky'
-		>,
 		Pick< _Popover.Popup.Props, 'initialFocus' | 'finalFocus' > {
 	/**
 	 * Whether to render a backdrop overlay behind the popover.
@@ -66,6 +55,15 @@ export interface PopupProps
 	 */
 	portal?: ReactElement< Omit< PortalProps, 'children' > >;
 
+	/**
+	 * Optional positioner element, typically `<Popover.Positioner />` with
+	 * custom positioning props (`side`, `align`, `sideOffset`, collision
+	 * settings, anchor, etc.). When omitted, `Popover.Popup` uses
+	 * `Popover.Positioner` with default props. Do not pass `children` on
+	 * the positioner element; they would be ignored.
+	 */
+	positioner?: ReactElement< Omit< PositionerProps, 'children' > >;
+
 	/**
 	 * The visual style variant of the popup.
 	 *

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

@@ -7,6 +7,7 @@ import * as Tooltip from '../../tooltip';
 const meta: Meta< typeof Tabs.Root > = {
 	title: 'Design System/Components/Tabs',
 	component: Tabs.Root,
+	tags: [ 'manifest' ],
 	subcomponents: {
 		'Tabs.List': Tabs.List,
 		'Tabs.Tab': Tabs.Tab,
@@ -14,9 +15,8 @@ const meta: Meta< typeof Tabs.Root > = {
 	},
 	parameters: {
 		componentStatus: {
-			status: 'use-with-caution',
+			status: 'recommended',
 			whereUsed: 'global',
-			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of color consistency with `@wordpress/components`. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
 		},
 	},
 };

package/src/tooltip/portal.tsx

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

package/src/tooltip/positioner.tsx

@@ -6,10 +6,7 @@ import resetStyles from '../utils/css/resets.module.css';
 import styles from './style.module.css';
 
 /**
- * Positions the floating tooltip content relative to the trigger. Pass to
- * `Tooltip.Popup`'s `positioner` prop to customize `side`, `align`,
- * `sideOffset`, collision behavior, etc. When `positioner` is omitted,
- * `Tooltip.Popup` uses this component with default props.
+ * Used to apply custom positioning to `Tooltip`'s floating content.
  */
 const Positioner = forwardRef< HTMLDivElement, PositionerProps >(
 	function TooltipPositioner(

package/src/tooltip/style.module.css

@@ -25,7 +25,7 @@
 		 * positioner (via the shared `.box-sizing` reset utility), so
 		 * the 1px is absorbed and non-FC layout is unchanged.
 		 */
-		@media (forced-colors: active) {
+		@media ( forced-colors: active ) {
 			border: 1px solid CanvasText;
 		}
 	}

package/src/tooltip/test/index.test.tsx

@@ -1,7 +1,9 @@
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { createRef } from '@wordpress/element';
+import type { ReactNode } from 'react';
 import * as Tooltip from '../index';
+import { useEnableWpCompatOverlaySlot } from '../../utils/use-enable-wp-compat-overlay-slot';
 import type { ProviderProps } from '../types';
 
 // Test wrapper that sets delay={0} to avoid real-time delays in tests.
@@ -151,4 +153,112 @@ describe( 'Tooltip', () => {
 			);
 		} );
 	} );
+
+	// 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>
+					<TestProvider>
+						<Tooltip.Root>
+							<Tooltip.Trigger>Hover me</Tooltip.Trigger>
+							<Tooltip.Popup>Tooltip content</Tooltip.Popup>
+						</Tooltip.Root>
+					</TestProvider>
+				</WithSlotEnabled>
+			);
+
+			await user.hover(
+				screen.getByRole( 'button', { name: 'Hover me' } )
+			);
+
+			const content = await screen.findByText( 'Tooltip content' );
+			expect( content ).toBeVisible();
+
+			const slot = document.querySelector( SLOT_SELECTOR );
+			expect( slot ).not.toBeNull();
+			expect( slot ).toContainElement( content );
+		} );
+
+		it( 'does not create a slot when the consumer has not opted in (dormant default)', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<TestProvider>
+					<Tooltip.Root>
+						<Tooltip.Trigger>Hover me</Tooltip.Trigger>
+						<Tooltip.Popup>Tooltip content</Tooltip.Popup>
+					</Tooltip.Root>
+				</TestProvider>
+			);
+
+			await user.hover(
+				screen.getByRole( 'button', { name: 'Hover me' } )
+			);
+
+			const content = await screen.findByText( 'Tooltip content' );
+			expect( content ).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>
+					<TestProvider>
+						<Tooltip.Root>
+							<Tooltip.Trigger>Hover me</Tooltip.Trigger>
+							<div
+								ref={ containerRef }
+								data-testid="custom-container"
+							/>
+							<Tooltip.Popup
+								portal={
+									<Tooltip.Portal
+										container={ containerRef }
+									/>
+								}
+							>
+								Tooltip content
+							</Tooltip.Popup>
+						</Tooltip.Root>
+					</TestProvider>
+				</WithSlotEnabled>
+			);
+
+			await user.hover(
+				screen.getByRole( 'button', { name: 'Hover me' } )
+			);
+
+			const content = await screen.findByText( 'Tooltip content' );
+			expect( content ).toBeVisible();
+			expect( screen.getByTestId( 'custom-container' ) ).toContainElement(
+				content
+			);
+		} );
+	} );
+	/* eslint-enable testing-library/no-node-access */
 } );

package/src/tooltip/types.ts

@@ -1,13 +1,11 @@
-import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
+import type { ReactElement, ReactNode } from 'react';
 import type { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
 
 import type { ComponentProps } from '../utils/types';
 
-export type PortalProps = ComponentPropsWithoutRef< typeof _Tooltip.Portal >;
+export type PortalProps = ComponentProps< typeof _Tooltip.Portal >;
 
-export type PositionerProps = ComponentPropsWithoutRef<
-	typeof _Tooltip.Positioner
->;
+export type PositionerProps = ComponentProps< typeof _Tooltip.Positioner >;
 
 export type RootProps = Pick< _Tooltip.Root.Props, 'disabled' | 'children' >;
 

package/src/utils/create-overlay-title-validation.tsx

@@ -46,7 +46,7 @@ export function createOverlayTitleValidation( componentName: string ) {
 	function ValidationProviderDev( {
 		children,
 	}: OverlayValidationProviderProps ) {
-		const titleElementRef = useRef< HTMLElement | null >( null );
+		const titleElementRef = useRef< HTMLElement >( null );
 
 		const scheduleValidation = useScheduleValidation( () => {
 			const titleElement = titleElementRef.current;

package/src/utils/css/item-popup.module.css

@@ -16,10 +16,6 @@
 		border: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
 		box-shadow: var(--wpds-elevation-md);
 		background-color: var(--wpds-color-bg-surface-neutral-strong);
-		font-family: var(--wpds-typography-font-family-body);
-		font-size: var(--wpds-typography-font-size-md);
-		line-height: 1.4;
-		color: var(--wpds-color-fg-interactive-neutral);
 	}
 
 	.list {
@@ -27,6 +23,10 @@
 		grid-area: main;
 		grid-template-rows: minmax(0, 1fr) auto;
 		grid-template-areas: "scrollable" "footer";
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-md);
+		line-height: var(--wpds-typography-line-height-sm);
+		color: var(--wpds-color-fg-interactive-neutral);
 	}
 
 	.list-scrollable-container {
@@ -124,6 +124,9 @@
 		align-items: center;
 		min-height: var(--wp-ui-popup-empty-min-height);
 		padding-inline: var(--wp-ui-popup-empty-padding-inline);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-md);
+		line-height: var(--wpds-typography-line-height-sm);
 		color: var(--wpds-color-fg-content-neutral-weak);
 	}