@wordpress/ui 0.11.0 → 0.12.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,6 +7,8 @@ import {
 } from '@wordpress/theme';
 import type { PopupProps } from './types';
 import { unlock } from '../lock-unlock';
+import { Portal } from './portal';
+import { renderPortalWithChildren } from '../utils/render-portal-with-children';
 import resetStyles from '../utils/css/resets.module.css';
 import styles from './style.module.css';
 
@@ -16,30 +18,23 @@ const ThemeProvider: typeof ThemeProviderType =
 const Popup = forwardRef< HTMLDivElement, PopupProps >( function TooltipPopup(
 	{
 		align = 'center',
-		container,
+		portal,
 		side = 'top',
 		sideOffset = 4,
 		children,
 		className,
-		style,
 		...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
-				) }
-			>
-				{ /* This should ideally use whatever dark color makes sense,
+	const portalChildren = (
+		<_Tooltip.Positioner
+			align={ align }
+			side={ side }
+			sideOffset={ sideOffset }
+			className={ clsx( resetStyles[ 'box-sizing' ], styles.positioner ) }
+		>
+			{ /* 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
@@ -48,18 +43,19 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function TooltipPopup(
 				    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>
+			<ThemeProvider color={ { bg: '#1e1e1e' } }>
+				<_Tooltip.Popup
+					ref={ ref }
+					className={ clsx( styles.popup, className ) }
+					{ ...props }
+				>
+					{ children }
+				</_Tooltip.Popup>
+			</ThemeProvider>
+		</_Tooltip.Positioner>
 	);
+
+	return renderPortalWithChildren( portal, <Portal />, portalChildren );
 } );
 
 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/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

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { formatBold, formatItalic } from '@wordpress/icons';
-import { Icon, Tooltip } from '../..';
+import { Icon } from '../../icon';
+import * as Tooltip from '../';
 
 const meta: Meta< typeof Tooltip.Root > = {
 	title: 'Design System/Components/Tooltip',
@@ -9,6 +10,7 @@ const meta: Meta< typeof Tooltip.Root > = {
 		Provider: Tooltip.Provider,
 		Trigger: Tooltip.Trigger,
 		Popup: Tooltip.Popup,
+		Portal: Tooltip.Portal,
 	},
 };
 export default meta;
@@ -74,6 +76,42 @@ export const Positioning: StoryObj< typeof Tooltip.Root > = {
 	),
 };
 
+/**
+ * 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

@@ -5,7 +5,11 @@ import {
 	formatUnderline,
 	info,
 } from '@wordpress/icons';
-import { Icon, IconButton, Popover, Tooltip, VisuallyHidden } from '../..';
+import * as Tooltip from '../';
+import { Icon } from '../../icon';
+import { IconButton } from '../../icon-button';
+import * as Popover from '../../popover';
+import { VisuallyHidden } from '../../visually-hidden';
 
 const meta: Meta = {
 	title: 'Design System/Components/Tooltip/Usage Guidelines',

package/src/tooltip/style.module.css

@@ -16,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,14 @@
-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 RootProps = Pick< _Tooltip.Root.Props, 'disabled' | 'children' >;
 
 export type ProviderProps = Pick<
-	Tooltip.Provider.Props,
+	_Tooltip.Provider.Props,
 	'delay' | 'children'
 >;
 
@@ -18,14 +21,17 @@ export interface TriggerProps extends ComponentProps< 'button' > {
 
 export interface PopupProps
 	extends ComponentProps< 'div' >,
-		Pick< Tooltip.Positioner.Props, 'align' | 'side' | 'sideOffset' > {
+		Pick< _Tooltip.Positioner.Props, 'align' | 'side' | 'sideOffset' > {
 	/**
 	 * 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.
 	 */
-	container?: Tooltip.Portal.Props[ 'container' ];
+	portal?: ReactElement< Omit< PortalProps, '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/item-popup.module.css

@@ -13,7 +13,7 @@
 		min-width: var(--anchor-width);
 		max-width: var(--available-width);
 		border-radius: var(--wpds-border-radius-md);
-		border: 1px solid var(--wpds-color-stroke-surface-neutral);
+		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);
@@ -45,7 +45,7 @@
 		padding-block: var(--wp-ui-popup-padding);
 
 		.list-scrollable-container:not(:empty) + & {
-			border-block-start: 1px solid var(--wpds-color-stroke-surface-neutral);
+			border-block-start: var(--wpds-border-width-xs) solid var(--wpds-color-stroke-surface-neutral);
 		}
 	}
 
@@ -55,8 +55,7 @@
 		--wp-ui-popup-item-padding-inline: 12px;
 		--wp-ui-popup-item-padding-block: 4px;
 
-		display: grid;
-		grid-template-columns: 24px 1fr;
+		display: flex;
 		align-items: center;
 		justify-content: flex-start;
 		gap: var(--wpds-dimension-gap-xs);
@@ -106,23 +105,22 @@
 		}
 	}
 
-	.item-indicator {
-		justify-self: center;
+	.item-indicator-icon {
+		flex-shrink: 0;
 	}
 
-	.empty {
+	/* Only style when there is content, because otherwise the element would block clicks
+	on the .list beneath it (both share grid-area: main and overlap). */
+	.empty:not(:empty) {
 		--wp-ui-popup-empty-min-height: 40px;
 		--wp-ui-popup-empty-padding-inline: 12px;
 
 		grid-area: main;
 		display: flex;
 		align-items: center;
+		min-height: var(--wp-ui-popup-empty-min-height);
 		padding-inline: var(--wp-ui-popup-empty-padding-inline);
 		color: var(--wpds-color-fg-content-neutral-weak);
-
-		&:not(:empty) {
-			min-height: var(--wp-ui-popup-empty-min-height);
-		}
 	}
 
 }