@wordpress/ui 0.10.0 → 0.11.0

package/src/popover/context.tsx

@@ -0,0 +1,100 @@
+import {
+	createContext,
+	useCallback,
+	useContext,
+	useEffect,
+	useMemo,
+	useRef,
+} from '@wordpress/element';
+
+/**
+ * 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;
+}
+
+/**
+ * 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 }</>;
+}
+
+/**
+ * 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;

package/src/popover/description.tsx

@@ -0,0 +1,29 @@
+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, ...props }, ref ) {
+		return (
+			<Text
+				ref={ ref }
+				variant="body-md"
+				render={ <_Popover.Description { ...props } /> }
+				className={ clsx( styles.description, className ) }
+			>
+				{ children }
+			</Text>
+		);
+	}
+);
+
+export { Description };

package/src/popover/index.ts

@@ -0,0 +1,9 @@
+import { Arrow } from './arrow';
+import { Close } from './close';
+import { Description } from './description';
+import { Popup } from './popup';
+import { Root } from './root';
+import { Title } from './title';
+import { Trigger } from './trigger';
+
+export { Arrow, Close, Description, Popup, Root, Title, Trigger };

package/src/popover/popup.tsx

@@ -0,0 +1,106 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import clsx from 'clsx';
+import { forwardRef } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
+import {
+	type ThemeProvider as ThemeProviderType,
+	privateApis as themePrivateApis,
+} from '@wordpress/theme';
+import { unlock } from '../lock-unlock';
+import resetStyles from '../utils/css/resets.module.css';
+import { useDeprioritizedInitialFocus } from '../utils/use-deprioritized-initial-focus';
+import { PopoverValidationProvider } from './context';
+import styles from './style.module.css';
+import type { PopupProps } from './types';
+
+const ThemeProvider: typeof ThemeProviderType =
+	unlock( themePrivateApis ).ThemeProvider;
+
+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.
+ */
+const Popup = forwardRef< HTMLDivElement, PopupProps >( function PopoverPopup(
+	{
+		align = 'center',
+		alignOffset,
+		anchor,
+		// Matches the popup's border-radius (--wpds-border-radius-md).
+		arrowPadding = 8,
+		backdrop = false,
+		children,
+		className,
+		collisionAvoidance,
+		collisionBoundary,
+		collisionPadding,
+		container,
+		finalFocus,
+		initialFocus,
+		side = 'bottom',
+		sideOffset = 8,
+		sticky,
+		style,
+		variant = 'default',
+		...props
+	},
+	ref
+) {
+	const { resolvedInitialFocus, popupRef } = useDeprioritizedInitialFocus( {
+		initialFocus,
+		deprioritizedAttribute: CLOSE_ATTR,
+	} );
+	const mergedPopupRef = useMergeRefs( [ ref, popupRef ] );
+
+	const backdropElement = backdrop ? (
+		<_Popover.Backdrop className={ styles.backdrop } />
+	) : null;
+
+	const positioner = (
+		<_Popover.Positioner
+			align={ align }
+			alignOffset={ alignOffset }
+			anchor={ anchor }
+			arrowPadding={ arrowPadding }
+			collisionAvoidance={ collisionAvoidance }
+			collisionBoundary={ collisionBoundary }
+			collisionPadding={ collisionPadding }
+			side={ side }
+			sideOffset={ sideOffset }
+			sticky={ sticky }
+			style={ style }
+			className={ clsx(
+				resetStyles[ 'box-sizing' ],
+				styles.positioner,
+				className
+			) }
+		>
+			<ThemeProvider>
+				<_Popover.Popup
+					ref={ mergedPopupRef }
+					initialFocus={ resolvedInitialFocus }
+					finalFocus={ finalFocus }
+					className={ clsx( variant !== 'unstyled' && styles.popup ) }
+					{ ...props }
+				>
+					<PopoverValidationProvider>
+						{ children }
+					</PopoverValidationProvider>
+				</_Popover.Popup>
+			</ThemeProvider>
+		</_Popover.Positioner>
+	);
+
+	return (
+		<_Popover.Portal container={ container }>
+			{ backdropElement }
+			{ positioner }
+		</_Popover.Portal>
+	);
+} );
+
+export { Popup };

package/src/popover/root.tsx

@@ -0,0 +1,41 @@
+import { Popover as _Popover } from '@base-ui/react/popover';
+import type { RootProps } from './types';
+
+/**
+ * An accessible popup anchored to a trigger element.
+ *
+ * Popover renders ARIA-compliant floating content that appears next to its
+ * trigger. It can contain interactive content such as form controls, menus,
+ * and rich descriptions.
+ *
+ * Compose the compound components to build a popover:
+ *
+ * - `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.Arrow` — an optional arrow pointing toward the anchor.
+ * - `Popover.Title` — **required** heading that labels the popover for
+ *   accessibility (can be visually hidden).
+ * - `Popover.Description` — optional paragraph linked via `aria-describedby`.
+ * - `Popover.Close` — a button that closes the popover when clicked.
+ *   **Required** when `modal` is `true` or `'trap-focus'` so that focus
+ *   can cycle correctly and the user can dismiss the popover.
+ *
+ * ```jsx
+ * <Popover.Root>
+ *   <Popover.Trigger>Open</Popover.Trigger>
+ *   <Popover.Popup>
+ *     <Popover.Arrow />
+ *     <Popover.Title>Popover title</Popover.Title>
+ *     <Popover.Description>Popover description</Popover.Description>
+ *     <Popover.Close>Close</Popover.Close>
+ *   </Popover.Popup>
+ * </Popover.Root>
+ * ```
+ */
+function Root( props: RootProps ) {
+	return <_Popover.Root { ...props } />;
+}
+
+export { Root };