@wordpress/ui 0.11.1-next.v.202604091042.0 → 0.12.0

package/src/link/test/index.test.tsx

@@ -16,6 +16,24 @@ describe( 'Link', () => {
 		expect( ref.current ).toBeInstanceOf( HTMLAnchorElement );
 	} );
 
+	it( 'calls onClick when clicked (often used for analytics tracking)', async () => {
+		const user = userEvent.setup();
+		const onClick = jest.fn(
+			( event: React.MouseEvent< HTMLAnchorElement > ) =>
+				event.preventDefault()
+		);
+
+		render(
+			<Link href="/page" onClick={ onClick }>
+				Go to page
+			</Link>
+		);
+
+		await user.click( screen.getByRole( 'link', { name: 'Go to page' } ) );
+
+		expect( onClick ).toHaveBeenCalledTimes( 1 );
+	} );
+
 	describe( 'openInNewTab', () => {
 		it( 'sets target="_blank" when true', () => {
 			render(
@@ -47,47 +65,33 @@ describe( 'Link', () => {
 
 			expect(
 				screen.getByLabelText( '(opens in a new tab)' )
-			).toBeInTheDocument();
+			).toBeVisible();
 		} );
 
-		it( 'prevents default for internal anchor links', async () => {
-			const user = userEvent.setup();
-			const onClick = jest.fn();
-
+		it( 'keeps the link text on the anchor element', () => {
 			render(
-				<Link href="#section" openInNewTab onClick={ onClick }>
-					Jump
+				<Link href="https://example.com" openInNewTab>
+					External
 				</Link>
 			);
 
-			await user.click( screen.getByRole( 'link' ) );
-
-			expect( onClick ).toHaveBeenCalledTimes( 1 );
-			expect( onClick.mock.calls[ 0 ][ 0 ].defaultPrevented ).toBe(
-				true
+			expect( screen.getByText( 'External' ) ).toBe(
+				screen.getByRole( 'link' )
 			);
 		} );
 
-		it( 'does not prevent default for external links', async () => {
-			const user = userEvent.setup();
-			const onClick = jest.fn();
-
+		it( 'includes the new tab notice in the link name', () => {
 			render(
-				<Link
-					href="https://example.com"
-					openInNewTab
-					onClick={ onClick }
-				>
+				<Link href="https://example.com" openInNewTab>
 					External
 				</Link>
 			);
 
-			await user.click( screen.getByRole( 'link' ) );
-
-			expect( onClick ).toHaveBeenCalledTimes( 1 );
-			expect( onClick.mock.calls[ 0 ][ 0 ].defaultPrevented ).toBe(
-				false
-			);
+			expect(
+				screen.getByRole( 'link', {
+					name: 'External (opens in a new tab)',
+				} )
+			).toBeVisible();
 		} );
 	} );
 } );

package/src/link/types.ts

@@ -22,8 +22,7 @@ export interface LinkProps extends Omit< ComponentProps< 'a' >, 'target' > {
 
 	/**
 	 * Whether to open the link in a new browser tab.
-	 * When true, sets `target="_blank"`, appends a visual arrow indicator,
-	 * and prevents navigation for internal anchors (`#`-prefixed hrefs).
+	 * When true, sets `target="_blank"` and appends a visual arrow indicator.
 	 *
 	 * @default false
 	 */

package/src/notice/action-link.tsx

@@ -1,6 +1,7 @@
 import clsx from 'clsx';
 import { forwardRef } from '@wordpress/element';
 import { Link } from '../link';
+import { Text } from '../text';
 import type { ActionLinkProps } from './types';
 import styles from './style.module.css';
 
@@ -8,14 +9,16 @@ import styles from './style.module.css';
  * An action link for use within Notice.Actions.
  */
 export const ActionLink = forwardRef< HTMLAnchorElement, ActionLinkProps >(
-	function NoticeActionLink( { className, ...props }, ref ) {
+	function NoticeActionLink( { className, render, ...props }, ref ) {
 		return (
-			<Link
+			<Text
 				ref={ ref }
 				className={ clsx( styles[ 'action-link' ], className ) }
 				{ ...props }
-				tone="neutral"
-				variant="default"
+				variant="body-md"
+				render={
+					<Link tone="neutral" variant="default" render={ render } />
+				}
 			/>
 		);
 	}

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,11 +64,6 @@
 
 	.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);
-		margin-block: auto;
 
 		/* Add more horizontal space when following another action link/button */
 		&:not(:first-child) {
@@ -125,6 +120,11 @@
 }
 
 @layer wp-ui-compositions {
+	/* Override `Text` margin */
+	.action-link {
+		margin-block: auto;
+	}
+
 	/* Add partial transparency to CloseIcon and outline/minimal ActionButton
 	 * for a better look over tinted backgrounds */
 	.close-icon,

package/src/popover/context.tsx

@@ -1,100 +1,17 @@
-import {
-	createContext,
-	useCallback,
-	useContext,
-	useEffect,
-	useMemo,
-	useRef,
-} from '@wordpress/element';
+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 registerTitle = useCallback( ( element: HTMLElement | null ) => {
-		titleElementRef.current = element;
-	}, [] );
-
-	const contextValue = useMemo(
-		() => ( { registerTitle } ),
-		[ registerTitle ]
-	);
-
-	useEffect( () => {
-		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.'
-			);
-		}
-	}, [] );
-
-	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,29 +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, render, ...props },
-		ref
-	) {
+	function PopoverDescription( { children, ...props }, ref ) {
 		return (
 			<Text
 				ref={ ref }
 				variant="body-md"
-				render={
-					<_Popover.Description render={ render } { ...props } />
-				}
-				className={ clsx( styles.description, className ) }
+				render={ <_Popover.Description { ...props } /> }
 			>
 				{ 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 { 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>
 			</>
@@ -1267,7 +1298,7 @@ export const HoverTrigger: Story = {
  * popup itself, it's a popover. If the trigger's purpose is unrelated to
  * opening the popup, it's a tooltip.
  */
-export const InfoTip: Story = {
+export const Infotip: Story = {
 	parameters: { controls: { disable: true } },
 	render: function Render( args ) {
 		return (

package/src/popover/style.module.css

@@ -9,15 +9,43 @@
 		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-font-family-body);
-		font-size: var(--wpds-font-size-md);
-		line-height: var(--wpds-font-line-height-md);
+		font-family: var(--wpds-typography-font-family-body);
+		font-size: var(--wpds-typography-font-size-md);
+		line-height: var(--wpds-typography-line-height-md);
 		color: var(--wpds-color-fg-content-neutral);
 		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 {