@wordpress/ui 0.11.0 → 0.12.0

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 { renderPortalWithChildren } from '../utils/render-portal-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,19 +74,17 @@ 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
 					ref={ mergedPopupRef }
 					initialFocus={ resolvedInitialFocus }
 					finalFocus={ finalFocus }
-					className={ clsx( variant !== 'unstyled' && styles.popup ) }
+					className={ clsx(
+						variant !== 'unstyled' && styles.popup,
+						className
+					) }
 					{ ...props }
 				>
 					<PopoverValidationProvider>
@@ -95,12 +95,14 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
 		</_Popover.Positioner>
 	);
 
-	return (
-		<_Popover.Portal container={ container }>
+	const portalChildren = (
+		<>
 			{ backdropElement }
 			{ positioner }
-		</_Popover.Portal>
+		</>
 	);
+
+	return renderPortalWithChildren( portal, <Portal />, portalChildren );
 } );
 
 export { Popup };

package/src/popover/portal.tsx

@@ -0,0 +1,17 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+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.
+ */
+const Portal = forwardRef< HTMLDivElement, PortalProps >(
+	function PopoverPortal( props, ref ) {
+		return <_Popover.Portal ref={ ref } { ...props } />;
+	}
+);
+
+export { Portal };

package/src/popover/root.tsx

@@ -12,8 +12,8 @@ import type { RootProps } from './types';
  *
  * - `Popover.Root` — provides open state and context to all sub-components.
  * - `Popover.Trigger` — the button that toggles the popup.
- * - `Popover.Popup` — the floating container (portal, positioning, collision
- *   avoidance).
+ * - `Popover.Popup` — the floating container (positioning, collision
+ *   avoidance); portals by default or via `portal={ <Popover.Portal /> }`.
  * - `Popover.Arrow` — an optional arrow pointing toward the anchor.
  * - `Popover.Title` — **required** heading that labels the popover for
  *   accessibility (can be visually hidden).

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

@@ -2,7 +2,8 @@ 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 { Popover, VisuallyHidden } from '../..';
+import * as Popover from '../';
+import { VisuallyHidden } from '../../visually-hidden';
 import { Icon } from '../../icon';
 import { IconButton } from '../../icon-button';
 import { GenericIframe, useMeasure } from './utils';
@@ -12,6 +13,7 @@ const meta: Meta< typeof Popover.Root > = {
 	component: Popover.Root,
 	subcomponents: {
 		'Popover.Trigger': Popover.Trigger,
+		'Popover.Portal': Popover.Portal,
 		'Popover.Popup': Popover.Popup,
 		'Popover.Arrow': Popover.Arrow,
 		'Popover.Title': Popover.Title,
@@ -442,10 +444,11 @@ export const OverlayPlacement: Story = {
 };
 
 /**
- * To render the popup inline (without a portal), create a local ref to a
- * `<span>` with `display: contents` and pass it as the `container` prop.
- * The popup will render inside the span rather than being portaled to
- * `document.body`, while retaining all positioning behavior.
+ * To keep the floating layer **in page flow** next to surrounding layout,
+ * create a local ref to a `<span>` with `display: contents` and pass
+ * `portal={ <Popover.Portal container={ ref } /> }`. The popup still uses a
+ * portal, but the portal **mounts** into that subtree instead of
+ * `document.body`, while retaining positioning behavior.
  *
  * **Note:** `backdrop` will not cover the full viewport in this mode.
  */
@@ -462,7 +465,11 @@ export const Inline: Story = {
 						ref={ inlineContainerRef }
 						style={ { display: 'contents' } }
 					/>
-					<Popover.Popup container={ inlineContainerRef }>
+					<Popover.Popup
+						portal={
+							<Popover.Portal container={ inlineContainerRef } />
+						}
+					>
 						<Popover.Arrow />
 						<Popover.Title
 							style={ {
@@ -472,8 +479,10 @@ export const Inline: Story = {
 							Inline Popover
 						</Popover.Title>
 						<Popover.Description>
-							This popup is rendered in place — no portal is used.
-							Inspect the DOM to see it lives inside its parent.
+							This example still uses `Popover.Portal`, but the
+							portal `container` is the in-tree span above, so the
+							portal node mounts inside the wrapper instead of
+							`document.body`.
 						</Popover.Description>
 					</Popover.Popup>
 				</Popover.Root>
@@ -571,8 +580,8 @@ export const CollisionAvoidance: Story = {
 
 /**
  * When the popover's trigger lives inside an iframe but the popover should
- * render in the parent document, pass a parent-document element to the
- * `container` prop on `Popover.Popup`.
+ * render in the parent document, pass a parent-document element through
+ * `portal={ <Popover.Portal container={ ... } /> }` on `Popover.Popup`.
  *
  * This technique is used in Gutenberg where the block editor canvas is an
  * iframe but toolbars and menus must appear outside it.
@@ -623,8 +632,12 @@ export const CrossIframe: Story = {
 									Popover&apos;s anchor (inside iframe)
 								</Popover.Trigger>
 								<Popover.Popup
-									container={
-										portalContainerRef as React.RefObject< HTMLElement >
+									portal={
+										<Popover.Portal
+											container={
+												portalContainerRef as React.RefObject< HTMLElement >
+											}
+										/>
 									}
 									collisionBoundary={
 										iframeBoundary ?? undefined
@@ -660,9 +673,9 @@ export const CrossIframe: Story = {
  * `@wordpress/components` as the render target.
  *
  * The `Slot` renders a `div` in the parent document, and its forwarded ref
- * is passed to `Popover.Popup`'s `container` prop so the popup portals into
- * the slot element. This mirrors the legacy Popover's `WithSlotOutsideIframe`
- * pattern.
+ * 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)',
@@ -712,8 +725,12 @@ export const CrossIframeWithSlotFill: Story = {
 									Popover&apos;s anchor (inside iframe)
 								</Popover.Trigger>
 								<Popover.Popup
-									container={
-										slotRef as React.RefObject< HTMLElement >
+									portal={
+										<Popover.Portal
+											container={
+												slotRef as React.RefObject< HTMLElement >
+											}
+										/>
 									}
 									collisionBoundary={
 										iframeBoundary ?? undefined
@@ -745,12 +762,19 @@ export const CrossIframeWithSlotFill: Story = {
 
 /**
  * Popovers in Gutenberg are managed with explicit z-index values, which can
- * create situations where a popover renders below another popover, when you
- * want it to be rendered above.
+ * create situations where a popover renders below another popover when you
+ * want it above.
+ *
+ * The `--wp-ui-popover-z-index` CSS variable controls the z-index of the
+ * popover's positioner (and its optional backdrop). Override it either:
+ *
+ * - **Globally**, by setting the variable on `:root` or `body` (raises every
+ *   popover in the page), or
+ * - **Per instance**, by passing a `Popover.Portal` with a `style` (or
+ *   `className`) to `Popover.Popup`'s `portal` prop. The variable cascades
+ *   from the portal wrapper to everything rendered inside it.
  *
- * The `--wp-ui-popover-z-index` CSS variable, available on the
- * `Popover.Popup` component, is an escape hatch that can be used to override
- * the z-index of a given popover on a case-by-case basis.
+ * This story demonstrates the per-instance approach.
  */
 export const WithCustomZIndex: Story = {
 	name: 'With Custom z-index',
@@ -758,7 +782,13 @@ export const WithCustomZIndex: Story = {
 		children: (
 			<>
 				<Popover.Trigger>Open Popover</Popover.Trigger>
-				<Popover.Popup style={ { '--wp-ui-popover-z-index': '9999' } }>
+				<Popover.Popup
+					portal={
+						<Popover.Portal
+							style={ { '--wp-ui-popover-z-index': '9999' } }
+						/>
+					}
+				>
 					<Popover.Arrow />
 					<Popover.Title
 						style={ {
@@ -768,8 +798,9 @@ export const WithCustomZIndex: Story = {
 						Custom z-index
 					</Popover.Title>
 					<Popover.Description>
-						This popover&apos;s positioner has z-index: 9999 via the
-						`--wp-ui-popover-z-index` CSS custom property.
+						This popover renders at `z-index: 9999` via the
+						`--wp-ui-popover-z-index` CSS custom property, set on
+						`Popover.Portal` through the `portal` prop.
 					</Popover.Description>
 				</Popover.Popup>
 			</>

package/src/popover/style.module.css

@@ -9,7 +9,7 @@
 		background-color: var(--wpds-color-bg-surface-neutral-strong);
 		padding: var(--wpds-dimension-padding-lg);
 		border-radius: var(--wpds-border-radius-md);
-		border: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral-weak);
+		border: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
 		box-shadow: var(--wpds-elevation-md);
 		font-family: var(--wpds-typography-font-family-body);
 		font-size: var(--wpds-typography-font-size-md);
@@ -18,6 +18,34 @@
 		outline: 0;
 	}
 
+	/*
+	 * When a backdrop is rendered alongside the popup, hide the
+	 * regular-mode border. The backdrop already provides visual
+	 * containment, so the border becomes redundant noise.
+	 * `transparent` (not `none`) keeps popup geometry identical
+	 * regardless of the `backdrop` prop — `box-sizing: border-box`
+	 * absorbs the 1px into the existing box.
+	 */
+	.backdrop ~ * .popup {
+		border-color: transparent;
+	}
+
+	/*
+	 * Forced-colors mode strips `box-shadow` and substitutes
+	 * `background-color` with `Canvas` (the page background), so the
+	 * boundary depends entirely on the border. Set `CanvasText`
+	 * explicitly for both backdrop and non-backdrop popups:
+	 * `transparent` is not substituted by the UA, and being
+	 * explicit also removes any reliance on UA color-substitution
+	 * behavior for the non-backdrop case.
+	 */
+	@media (forced-colors: active) {
+		.popup,
+		.backdrop ~ * .popup {
+			border-color: CanvasText;
+		}
+	}
+
 	.arrow {
 		display: flex;
 
@@ -47,11 +75,12 @@
 	}
 
 	.arrow-stroke {
-		fill: var(--wpds-color-stroke-surface-neutral-weak);
+		fill: var(--wpds-color-stroke-surface-neutral);
 	}
 
-	.description {
-		color: var(--wpds-color-fg-content-neutral-weak);
+	.title {
+		color: var(--wpds-color-fg-content-neutral);
+		--_gcd-heading-color: var(--wpds-color-fg-content-neutral);
 	}
 
 	.backdrop {