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

package/src/tooltip/popup.tsx

@@ -1,5 +1,5 @@
 import clsx from 'clsx';
-import { Tooltip } from '@base-ui/react/tooltip';
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
 import { forwardRef } from '@wordpress/element';
 import {
 	type ThemeProvider as ThemeProviderType,
@@ -7,59 +7,47 @@ import {
 } from '@wordpress/theme';
 import type { PopupProps } from './types';
 import { unlock } from '../lock-unlock';
-import resetStyles from '../utils/css/resets.module.css';
+import { Portal } from './portal';
+import { Positioner } from './positioner';
+import { renderSlotWithChildren } from '../utils/render-slot-with-children';
 import styles from './style.module.css';
 
 const ThemeProvider: typeof ThemeProviderType =
 	unlock( themePrivateApis ).ThemeProvider;
 
 const Popup = forwardRef< HTMLDivElement, PopupProps >( function TooltipPopup(
-	{
-		align = 'center',
-		container,
-		side = 'top',
-		sideOffset = 4,
-		children,
-		className,
-		style,
-		...props
-	},
+	{ portal, positioner, children, className, ...props },
 	ref
 ) {
-	return (
-		<Tooltip.Portal container={ container }>
-			<Tooltip.Positioner
-				align={ align }
-				side={ side }
-				sideOffset={ sideOffset }
-				style={ style }
-				className={ clsx(
-					resetStyles[ 'box-sizing' ],
-					className,
-					styles.positioner
-				) }
+	const popupContent = (
+		/* This should ideally use whatever dark color makes sense,
+		 * and not be hardcoded to #1e1e1e. The solutions would be to:
+		 *   - review the design of the tooltip, in case we want to stop
+		 *     hardcoding it to a dark background
+		 *   - create new semantic tokens as needed (aliasing either the
+		 *     "inverted bg" or "perma-dark bg" private tokens) and have
+		 *     Tooltip.Popup use them;
+		 *   - remove the hardcoded `bg` setting from the `ThemeProvider`
+		 *     below
+		 */
+		<ThemeProvider color={ { bg: '#1e1e1e' } }>
+			<_Tooltip.Popup
+				ref={ ref }
+				className={ clsx( styles.popup, className ) }
+				{ ...props }
 			>
-				{ /* This should ideally use whatever dark color makes sense,
-				and not be hardcoded to #1e1e1e. The solutions would be to:
-				  - review the design of the tooltip, in case we want to stop
-				    hardcoding it to a dark background
-				  - create new semantic tokens as needed (aliasing either the "inverted
-					  bg" or "perma-dark bg" private tokens) and have Tooltip.Popup use
-				    them;
-				  - remove the hardcoded `bg` setting from the `ThemeProvider` below
-					*/ }
-				<ThemeProvider color={ { bg: '#1e1e1e' } }>
-					<Tooltip.Popup
-						ref={ ref }
-						className={ styles.popup }
-						{ ...props }
-					>
-						{ children }
-					</Tooltip.Popup>
-				</ThemeProvider>
-			</Tooltip.Positioner>
-		</Tooltip.Portal>
+				{ children }
+			</_Tooltip.Popup>
+		</ThemeProvider>
 	);
+
+	const positionedPopup = renderSlotWithChildren(
+		positioner,
+		<Positioner />,
+		popupContent
+	);
+
+	return renderSlotWithChildren( portal, <Portal />, positionedPopup );
 } );
 
 export { Popup };

package/src/tooltip/portal.tsx

@@ -0,0 +1,16 @@
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
+import { forwardRef } from '@wordpress/element';
+import type { PortalProps } from './types';
+
+/**
+ * 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.
+ */
+const Portal = forwardRef< HTMLDivElement, PortalProps >(
+	function TooltipPortal( props, ref ) {
+		return <_Tooltip.Portal ref={ ref } { ...props } />;
+	}
+);
+
+export { Portal };

package/src/tooltip/positioner.tsx

@@ -0,0 +1,36 @@
+import clsx from 'clsx';
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
+import { forwardRef } from '@wordpress/element';
+import type { PositionerProps } from './types';
+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.
+ */
+const Positioner = forwardRef< HTMLDivElement, PositionerProps >(
+	function TooltipPositioner(
+		{ align = 'center', className, side = 'top', sideOffset = 4, ...props },
+		ref
+	) {
+		return (
+			<_Tooltip.Positioner
+				ref={ ref }
+				align={ align }
+				side={ side }
+				sideOffset={ sideOffset }
+				{ ...props }
+				className={ clsx(
+					resetStyles[ 'box-sizing' ],
+					styles.positioner,
+					className
+				) }
+			/>
+		);
+	}
+);
+
+export { Positioner };

package/src/tooltip/provider.tsx

@@ -1,8 +1,8 @@
-import { Tooltip } from '@base-ui/react/tooltip';
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
 import type { ProviderProps } from './types';
 
-function Provider( { children, ...props }: ProviderProps ) {
-	return <Tooltip.Provider { ...props }>{ children }</Tooltip.Provider>;
+function Provider( { ...props }: ProviderProps ) {
+	return <_Tooltip.Provider { ...props } />;
 }
 
 export { Provider };

package/src/tooltip/root.tsx

@@ -1,4 +1,4 @@
-import { Tooltip } from '@base-ui/react/tooltip';
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
 import type { RootProps } from './types';
 
 /**
@@ -15,7 +15,7 @@ import type { RootProps } from './types';
  * @see {@link https://wordpress.github.io/gutenberg/?path=/docs/design-system-components-iconbutton--docs IconButton}
  */
 function Root( props: RootProps ) {
-	return <Tooltip.Root { ...props } />;
+	return <_Tooltip.Root { ...props } />;
 }
 
 export { Root };

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

@@ -7,9 +7,18 @@ const meta: Meta< typeof Tooltip.Root > = {
 	title: 'Design System/Components/Tooltip',
 	component: Tooltip.Root,
 	subcomponents: {
-		Provider: Tooltip.Provider,
-		Trigger: Tooltip.Trigger,
-		Popup: Tooltip.Popup,
+		'Tooltip.Provider': Tooltip.Provider,
+		'Tooltip.Trigger': Tooltip.Trigger,
+		'Tooltip.Popup': Tooltip.Popup,
+		'Tooltip.Positioner': Tooltip.Positioner,
+		'Tooltip.Portal': Tooltip.Portal,
+	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
 	},
 };
 export default meta;
@@ -39,8 +48,11 @@ export const Disabled: StoryObj< typeof Tooltip.Root > = {
 };
 
 /**
- * Use the `side` prop to control where the tooltip appears relative to the
- * trigger element.
+ * Customize where the tooltip appears relative to the trigger by passing a
+ * `<Tooltip.Positioner />` element to `Tooltip.Popup`'s `positioner` prop.
+ * `Tooltip.Positioner` accepts `side`, `align`, `sideOffset`, and collision
+ * settings; when `positioner` is omitted, the tooltip uses the defaults
+ * (`side="top"`, `align="center"`, `sideOffset={ 4 }`).
  */
 export const Positioning: StoryObj< typeof Tooltip.Root > = {
 	render: () => (
@@ -54,27 +66,103 @@ export const Positioning: StoryObj< typeof Tooltip.Root > = {
 		>
 			<Tooltip.Root>
 				<Tooltip.Trigger aria-label="Up">⬆️</Tooltip.Trigger>
-				<Tooltip.Popup side="top">Up</Tooltip.Popup>
+				<Tooltip.Popup positioner={ <Tooltip.Positioner side="top" /> }>
+					Up
+				</Tooltip.Popup>
 			</Tooltip.Root>
 
 			<Tooltip.Root>
 				<Tooltip.Trigger aria-label="Forward">➡️</Tooltip.Trigger>
-				<Tooltip.Popup side="right">Forward</Tooltip.Popup>
+				<Tooltip.Popup
+					positioner={ <Tooltip.Positioner side="right" /> }
+				>
+					Forward
+				</Tooltip.Popup>
 			</Tooltip.Root>
 
 			<Tooltip.Root>
 				<Tooltip.Trigger aria-label="Down">⬇️</Tooltip.Trigger>
-				<Tooltip.Popup side="bottom">Down</Tooltip.Popup>
+				<Tooltip.Popup
+					positioner={ <Tooltip.Positioner side="bottom" /> }
+				>
+					Down
+				</Tooltip.Popup>
 			</Tooltip.Root>
 
 			<Tooltip.Root>
 				<Tooltip.Trigger aria-label="Back">⬅️</Tooltip.Trigger>
-				<Tooltip.Popup side="left">Back</Tooltip.Popup>
+				<Tooltip.Popup
+					positioner={ <Tooltip.Positioner side="left" /> }
+				>
+					Back
+				</Tooltip.Popup>
 			</Tooltip.Root>
 		</div>
 	),
 };
 
+/**
+ * Beyond `side`, `Tooltip.Positioner` accepts the rest of the positioner
+ * surface — `align`, `alignOffset`, `sideOffset`, collision settings, and
+ * more — for fine-grained placement.
+ */
+export const WithCustomPositioner: StoryObj< typeof Tooltip.Root > = {
+	args: {
+		children: (
+			<>
+				<Tooltip.Trigger aria-label="Save">💾</Tooltip.Trigger>
+				<Tooltip.Popup
+					positioner={
+						<Tooltip.Positioner
+							side="right"
+							align="start"
+							sideOffset={ 16 }
+						/>
+					}
+				>
+					Save
+				</Tooltip.Popup>
+			</>
+		),
+	},
+};
+
+/**
+ * Popovers in Gutenberg are managed with explicit z-index values, which can
+ * create situations where a tooltip renders below another popover when you
+ * want it above.
+ *
+ * The `--wp-ui-tooltip-z-index` CSS variable controls the z-index of the
+ * tooltip's positioner. Override it either:
+ *
+ * - **Globally**, by setting the variable on `:root` or `body` (raises every
+ *   tooltip in the page), or
+ * - **Per instance**, by passing a `Tooltip.Portal` with a `style` (or
+ *   `className`) to `Tooltip.Popup`'s `portal` prop. The variable cascades
+ *   from the portal wrapper to everything rendered inside it.
+ *
+ * This story demonstrates the per-instance approach.
+ */
+export const WithCustomZIndex: StoryObj< typeof Tooltip.Root > = {
+	name: 'With Custom z-index',
+	args: {
+		children: (
+			<>
+				<Tooltip.Trigger aria-label="Save">💾</Tooltip.Trigger>
+				<Tooltip.Popup
+					portal={
+						<Tooltip.Portal
+							style={ { '--wp-ui-tooltip-z-index': '9999' } }
+						/>
+					}
+				>
+					Save
+				</Tooltip.Popup>
+			</>
+		),
+	},
+};
+
 /**
  * Use `Tooltip.Provider` to control the delay before tooltips appear.
  * This is useful when you have multiple tooltips and want them to share

package/src/tooltip/stories/usage-guidelines.story.tsx

@@ -15,6 +15,11 @@ const meta: Meta = {
 	title: 'Design System/Components/Tooltip/Usage Guidelines',
 	parameters: {
 		controls: { disable: true },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
 	},
 	tags: [ '!dev' ],
 };

package/src/tooltip/style.module.css

@@ -1,17 +1,5 @@
 @layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
 
-/*
- * Temporary workaround for a Base UI tabbability regression with
- * checkVisibility() and display: contents.
- * See: https://github.com/mui/base-ui/issues/4622
- *
- * This must stay outside the CSS layers to override ThemeProvider's
- * unlayered display: contents.
- */
-[data-wpds-theme-provider-id]:has(> .popup) {
-	display: block;
-}
-
 @layer wp-ui-components {
 	.positioner {
 		z-index: var(--wp-ui-tooltip-z-index, initial);
@@ -28,5 +16,17 @@
 		line-height: 1.4; /* TODO: use DS token for line height */
 		color: var(--wpds-color-fg-content-neutral);
 		box-shadow: var(--wpds-elevation-sm);
+
+		/*
+		 * Forced-colors mode strips `box-shadow` and replaces the
+		 * `background-color` with `Canvas`, so the tooltip would merge
+		 * into the page. A 1px `CanvasText` border restores the edge.
+		 * The popup inherits `box-sizing: border-box` from the
+		 * positioner (via the shared `.box-sizing` reset utility), so
+		 * the 1px is absorbed and non-FC layout is unchanged.
+		 */
+		@media (forced-colors: active) {
+			border: 1px solid CanvasText;
+		}
 	}
 }

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

@@ -85,8 +85,8 @@ describe( 'Tooltip', () => {
 		).not.toBeInTheDocument();
 	} );
 
-	describe( 'container', () => {
-		it( 'should render inside the container when provided', async () => {
+	describe( 'portal', () => {
+		it( 'should render inside the portal container when a custom target is provided', async () => {
 			const user = userEvent.setup();
 			const containerRef = createRef< HTMLDivElement >();
 
@@ -99,7 +99,13 @@ describe( 'Tooltip', () => {
 								ref={ containerRef }
 								data-testid="custom-container"
 							/>
-							<Tooltip.Popup container={ containerRef }>
+							<Tooltip.Popup
+								portal={
+									<Tooltip.Portal
+										container={ containerRef }
+									/>
+								}
+							>
 								Tooltip content
 							</Tooltip.Popup>
 						</Tooltip.Root>

package/src/tooltip/trigger.tsx

@@ -1,14 +1,10 @@
-import { Tooltip } from '@base-ui/react/tooltip';
+import { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
 import { forwardRef } from '@wordpress/element';
 import type { TriggerProps } from './types';
 
 const Trigger = forwardRef< HTMLButtonElement, TriggerProps >(
-	function TooltipTrigger( { children, ...props }, ref ) {
-		return (
-			<Tooltip.Trigger ref={ ref } { ...props }>
-				{ children }
-			</Tooltip.Trigger>
-		);
+	function TooltipTrigger( props, ref ) {
+		return <_Tooltip.Trigger ref={ ref } { ...props } />;
 	}
 );
 

package/src/tooltip/types.ts

@@ -1,11 +1,18 @@
-import type { ReactNode } from 'react';
-import type { Tooltip } from '@base-ui/react/tooltip';
+import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
+import type { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
+
 import type { ComponentProps } from '../utils/types';
 
-export type RootProps = Pick< Tooltip.Root.Props, 'disabled' | 'children' >;
+export type PortalProps = ComponentPropsWithoutRef< typeof _Tooltip.Portal >;
+
+export type PositionerProps = ComponentPropsWithoutRef<
+	typeof _Tooltip.Positioner
+>;
+
+export type RootProps = Pick< _Tooltip.Root.Props, 'disabled' | 'children' >;
 
 export type ProviderProps = Pick<
-	Tooltip.Provider.Props,
+	_Tooltip.Provider.Props,
 	'delay' | 'children'
 >;
 
@@ -16,16 +23,26 @@ export interface TriggerProps extends ComponentProps< 'button' > {
 	children?: ReactNode;
 }
 
-export interface PopupProps
-	extends ComponentProps< 'div' >,
-		Pick< Tooltip.Positioner.Props, 'align' | 'side' | 'sideOffset' > {
+export interface PopupProps extends ComponentProps< 'div' > {
 	/**
 	 * The content to be rendered inside the component.
 	 */
 	children?: ReactNode;
 
 	/**
-	 * A parent element to render the portal into.
+	 * Optional portal element, typically `<Tooltip.Portal />` with custom
+	 * `container`. When omitted, `Tooltip.Popup` uses `Tooltip.Portal` with
+	 * default props. Do not pass `children` on the portal element; they would
+	 * be ignored.
+	 */
+	portal?: ReactElement< Omit< PortalProps, 'children' > >;
+
+	/**
+	 * Optional positioner element, typically `<Tooltip.Positioner />` with
+	 * custom positioning props (`side`, `align`, `sideOffset`, collision
+	 * settings, etc.). When omitted, `Tooltip.Popup` uses `Tooltip.Positioner`
+	 * with default props. Do not pass `children` on the positioner element;
+	 * they would be ignored.
 	 */
-	container?: Tooltip.Portal.Props[ 'container' ];
+	positioner?: ReactElement< Omit< PositionerProps, 'children' > >;
 }

package/src/utils/create-overlay-modal-context.tsx

@@ -0,0 +1,34 @@
+import { createContext, useContext } from '@wordpress/element';
+
+type OverlayModalProviderProps< Modal > = {
+	modal: Modal;
+	children: React.ReactNode;
+};
+
+/**
+ * Creates a modal context pair (`Provider` + `useModal`) for overlay
+ * primitives like Dialog and Drawer.
+ */
+export function createOverlayModalContext< Modal >( initialValue: Modal ) {
+	const OverlayModalContext = createContext< Modal >( initialValue );
+
+	function OverlayModalProvider( {
+		modal,
+		children,
+	}: OverlayModalProviderProps< Modal > ) {
+		return (
+			<OverlayModalContext.Provider value={ modal }>
+				{ children }
+			</OverlayModalContext.Provider>
+		);
+	}
+
+	function useOverlayModal() {
+		return useContext( OverlayModalContext );
+	}
+
+	return {
+		Provider: OverlayModalProvider,
+		useModal: useOverlayModal,
+	};
+}

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

@@ -0,0 +1,116 @@
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+} from '@wordpress/element';
+import { useScheduleValidation } from './use-schedule-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 OverlayValidationContextType = {
+	registerTitle: ( element: HTMLElement | null ) => () => void;
+};
+
+type OverlayValidationProviderProps = {
+	children: React.ReactNode;
+};
+
+/**
+ * Creates development-only title validation helpers for overlay primitives.
+ */
+export function createOverlayTitleValidation( componentName: string ) {
+	const componentNameLowerCase = componentName.toLowerCase();
+	const OverlayValidationContext = VALIDATION_ENABLED
+		? createContext< OverlayValidationContextType | null >( null )
+		: ( null as unknown as React.Context< OverlayValidationContextType | null > );
+
+	function useValidationContextDev() {
+		return useContext( OverlayValidationContext );
+	}
+
+	function useValidationContextProd() {
+		return null;
+	}
+
+	const useValidationContext = VALIDATION_ENABLED
+		? useValidationContextDev
+		: useValidationContextProd;
+
+	function ValidationProviderDev( {
+		children,
+	}: OverlayValidationProviderProps ) {
+		const titleElementRef = useRef< HTMLElement | null >( null );
+
+		const scheduleValidation = useScheduleValidation( () => {
+			const titleElement = titleElementRef.current;
+
+			if ( ! titleElement ) {
+				throw new Error(
+					`${ componentName }: Missing <${ componentName }.Title>. ` +
+						`For accessibility, every ${ componentNameLowerCase } 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(
+					`${ componentName }: <${ componentName }.Title> cannot be empty. ` +
+						`Provide meaningful text content for the ${ componentNameLowerCase } title.`
+				);
+			}
+		} );
+
+		const registerTitle = useCallback(
+			( element: HTMLElement | null ) => {
+				titleElementRef.current = element;
+				scheduleValidation();
+
+				return () => {
+					titleElementRef.current = null;
+					scheduleValidation();
+				};
+			},
+			[ scheduleValidation ]
+		);
+
+		const contextValue = useMemo(
+			() => ( { registerTitle } ),
+			[ registerTitle ]
+		);
+
+		// Schedule an initial validation on mount to catch missing titles
+		// (when no Title component is rendered, registerTitle is never called).
+		useEffect( () => {
+			scheduleValidation();
+		}, [ scheduleValidation ] );
+
+		return (
+			<OverlayValidationContext.Provider value={ contextValue }>
+				{ children }
+			</OverlayValidationContext.Provider>
+		);
+	}
+
+	function ValidationProviderProd( {
+		children,
+	}: OverlayValidationProviderProps ) {
+		return <>{ children }</>;
+	}
+
+	const ValidationProvider = VALIDATION_ENABLED
+		? ValidationProviderDev
+		: ValidationProviderProd;
+
+	return {
+		ValidationProvider,
+		useValidationContext,
+	};
+}

package/src/utils/css/dropdown-motion.module.css

@@ -8,9 +8,9 @@
 @layer wp-ui-utilities {
 	.dropdown-motion {
 		--wp-ui-dropdown-slide-distance: 4px;
-		--wp-ui-dropdown-slide-duration: 200ms;
-		--wp-ui-dropdown-slide-easing: cubic-bezier(0, 0, 0, 1);
-		--wp-ui-dropdown-fade-duration: 80ms;
+		--wp-ui-dropdown-slide-duration: var(--wpds-motion-duration-md);
+		--wp-ui-dropdown-slide-easing: var(--wpds-motion-easing-expressive);
+		--wp-ui-dropdown-fade-duration: var(--wpds-motion-duration-sm);
 		--wp-ui-dropdown-fade-easing: linear;
 
 		@media not ( prefers-reduced-motion ) {