@wordpress/components 19.15.0 → 20.0.1-next.d6164808d3.0

package/src/popover/index.js

@@ -13,6 +13,8 @@ import {
 	limitShift,
 	size,
 } from '@floating-ui/react-dom';
+// eslint-disable-next-line no-restricted-imports
+import { motion, useReducedMotion } from 'framer-motion';
 
 /**
  * WordPress dependencies
@@ -24,6 +26,7 @@ import {
 	createContext,
 	useContext,
 	useMemo,
+	useEffect,
 } from '@wordpress/element';
 import {
 	useViewportMatch,
@@ -32,6 +35,7 @@ import {
 } from '@wordpress/compose';
 import { close } from '@wordpress/icons';
 import deprecated from '@wordpress/deprecated';
+import { Path, SVG } from '@wordpress/primitives';
 
 /**
  * Internal dependencies
@@ -39,7 +43,11 @@ import deprecated from '@wordpress/deprecated';
 import Button from '../button';
 import ScrollLock from '../scroll-lock';
 import { Slot, Fill, useSlot } from '../slot-fill';
-import { getAnimateClassName } from '../animate';
+import {
+	getFrameOffset,
+	positionToPlacement,
+	placementToMotionAnimationProps,
+} from './utils';
 
 /**
  * Name of slot in which popover should fill.
@@ -48,50 +56,72 @@ import { getAnimateClassName } from '../animate';
  */
 const SLOT_NAME = 'Popover';
 
-const slotNameContext = createContext();
-
-const positionToPlacement = ( position ) => {
-	const [ x, y, z ] = position.split( ' ' );
-
-	if ( [ 'top', 'bottom' ].includes( x ) ) {
-		let suffix = '';
-		if ( ( !! z && z === 'left' ) || y === 'right' ) {
-			suffix = '-start';
-		} else if ( ( !! z && z === 'right' ) || y === 'left' ) {
-			suffix = '-end';
-		}
-		return x + suffix;
-	}
-
-	return y;
-};
-
-const placementToAnimationOrigin = ( placement ) => {
-	const [ a, b ] = placement.split( '-' );
-
-	let x, y;
-	if ( a === 'top' || a === 'bottom' ) {
-		x = a === 'top' ? 'bottom' : 'top';
-		y = 'middle';
-		if ( b === 'start' ) {
-			y = 'left';
-		} else if ( b === 'end' ) {
-			y = 'right';
+// An SVG displaying a triangle facing down, filled with a solid
+// color and bordered in such a way to create an arrow-like effect.
+// Keeping the SVG's viewbox squared simplify the arrow positioning
+// calculations.
+const ArrowTriangle = ( props ) => (
+	<SVG
+		{ ...props }
+		xmlns="http://www.w3.org/2000/svg"
+		viewBox={ `0 0 100 100` }
+		className="components-popover__triangle"
+		role="presentation"
+	>
+		<Path
+			className="components-popover__triangle-bg"
+			d="M 0 0 L 50 50 L 100 0"
+		/>
+		<Path
+			className="components-popover__triangle-border"
+			d="M 0 0 L 50 50 L 100 0"
+			vectorEffect="non-scaling-stroke"
+		/>
+	</SVG>
+);
+
+const MaybeAnimatedWrapper = forwardRef(
+	(
+		{
+			style: receivedInlineStyles,
+			placement,
+			shouldAnimate = false,
+			...props
+		},
+		forwardedRef
+	) => {
+		const shouldReduceMotion = useReducedMotion();
+
+		const { style: motionInlineStyles, ...otherMotionProps } = useMemo(
+			() => placementToMotionAnimationProps( placement ),
+			[ placement ]
+		);
+
+		if ( shouldAnimate && ! shouldReduceMotion ) {
+			return (
+				<motion.div
+					style={ {
+						...motionInlineStyles,
+						...receivedInlineStyles,
+					} }
+					{ ...otherMotionProps }
+					{ ...props }
+					ref={ forwardedRef }
+				/>
+			);
 		}
-	}
 
-	if ( a === 'left' || a === 'right' ) {
-		x = 'center';
-		y = a === 'left' ? 'right' : 'left';
-		if ( b === 'start' ) {
-			x = 'top';
-		} else if ( b === 'end' ) {
-			x = 'bottom';
-		}
+		return (
+			<div
+				style={ receivedInlineStyles }
+				{ ...props }
+				ref={ forwardedRef }
+			/>
+		);
 	}
+);
 
-	return x + ' ' + y;
-};
+const slotNameContext = createContext();
 
 const Popover = (
 	{
@@ -104,8 +134,8 @@ const Popover = (
 		noArrow = true,
 		isAlternate,
 		position,
-		placement = 'bottom-start',
-		offset,
+		placement: placementProp = 'bottom-start',
+		offset: offsetProp = 0,
 		focusOnMount = 'firstElement',
 		anchorRef,
 		anchorRect,
@@ -114,11 +144,11 @@ const Popover = (
 		onFocusOutside,
 		__unstableSlotName = SLOT_NAME,
 		__unstableObserveElement,
-		__unstableForcePosition,
+		__unstableForcePosition = false,
 		__unstableShift = false,
 		...contentProps
 	},
-	ref
+	forwardedRef
 ) => {
 	if ( range ) {
 		deprecated( 'range prop in Popover component', {
@@ -129,71 +159,90 @@ const Popover = (
 
 	const arrowRef = useRef( null );
 	const anchorRefFallback = useRef( null );
+
 	const isMobileViewport = useViewportMatch( 'medium', '<' );
 	const isExpanded = expandOnMobile && isMobileViewport;
 	const hasArrow = ! isExpanded && ! noArrow;
-	const usedPlacement = position
+	const normalizedPlacementFromProps = position
 		? positionToPlacement( position )
-		: placement;
+		: placementProp;
+
+	const referenceOwnerDocument = useMemo( () => {
+		let documentToReturn;
 
-	const ownerDocument = useMemo( () => {
 		if ( anchorRef?.top ) {
-			return anchorRef?.top.ownerDocument;
+			documentToReturn = anchorRef?.top.ownerDocument;
 		} else if ( anchorRef?.startContainer ) {
-			return anchorRef.startContainer.ownerDocument;
+			documentToReturn = anchorRef.startContainer.ownerDocument;
 		} else if ( anchorRef?.current ) {
-			return anchorRef.current.ownerDocument;
+			documentToReturn = anchorRef.current.ownerDocument;
 		} else if ( anchorRef ) {
 			// This one should be deprecated.
-			return anchorRef.ownerDocument;
+			documentToReturn = anchorRef.ownerDocument;
 		} else if ( anchorRect && anchorRect?.ownerDocument ) {
-			return anchorRect.ownerDocument;
+			documentToReturn = anchorRect.ownerDocument;
 		} else if ( getAnchorRect ) {
-			return (
-				getAnchorRect( anchorRefFallback.current )?.ownerDocument ??
-				document
-			);
+			documentToReturn = getAnchorRect(
+				anchorRefFallback.current
+			)?.ownerDocument;
 		}
 
-		return document;
+		return documentToReturn ?? document;
 	}, [ anchorRef, anchorRect, getAnchorRect ] );
 
 	/**
 	 * Offsets the position of the popover when the anchor is inside an iframe.
+	 *
+	 * Store the offset in a ref, due to constraints with floating-ui:
+	 * https://floating-ui.com/docs/react-dom#variables-inside-middleware-functions.
 	 */
-	const frameOffset = useMemo( () => {
-		const { defaultView } = ownerDocument;
-		const { frameElement } = defaultView;
-
-		if ( ! frameElement || ownerDocument === document ) {
-			return undefined;
-		}
+	const frameOffsetRef = useRef( getFrameOffset( referenceOwnerDocument ) );
+	/**
+	 * Store the offset prop in a ref, due to constraints with floating-ui:
+	 * https://floating-ui.com/docs/react-dom#variables-inside-middleware-functions.
+	 */
+	const offsetRef = useRef( offsetProp );
 
-		const iframeRect = frameElement.getBoundingClientRect();
-		return {
-			name: 'iframeOffset',
-			fn( { x, y } ) {
-				return {
-					x: x + iframeRect.left,
-					y: y + iframeRect.top,
-				};
-			},
-		};
-	}, [ ownerDocument ] );
+	const middleware = [
+		offsetMiddleware( ( { placement: currentPlacement } ) => {
+			if ( ! frameOffsetRef.current ) {
+				return offsetRef.current;
+			}
 
-	const middlewares = [
-		frameOffset,
-		offset ? offsetMiddleware( offset ) : undefined,
+			const isTopBottomPlacement =
+				currentPlacement.includes( 'top' ) ||
+				currentPlacement.includes( 'bottom' );
+
+			// The main axis should represent the gap between the
+			// floating element and the reference element. The cross
+			// axis is always perpendicular to the main axis.
+			const mainAxis = isTopBottomPlacement ? 'y' : 'x';
+			const crossAxis = mainAxis === 'x' ? 'y' : 'x';
+
+			// When the popover is before the reference, subtract the offset,
+			// of the main axis else add it.
+			const hasBeforePlacement =
+				currentPlacement.includes( 'top' ) ||
+				currentPlacement.includes( 'left' );
+			const mainAxisModifier = hasBeforePlacement ? -1 : 1;
+
+			return {
+				mainAxis:
+					offsetRef.current +
+					frameOffsetRef.current[ mainAxis ] * mainAxisModifier,
+				crossAxis: frameOffsetRef.current[ crossAxis ],
+			};
+		} ),
 		__unstableForcePosition ? undefined : flip(),
 		__unstableForcePosition
 			? undefined
 			: size( {
 					apply( sizeProps ) {
-						const { height } = sizeProps;
+						const { availableHeight } = sizeProps;
 						if ( ! refs.floating.current ) return;
 						// Reduce the height of the popover to the available space.
 						Object.assign( refs.floating.current.firstChild.style, {
-							maxHeight: `${ height }px`,
+							maxHeight: `${ availableHeight }px`,
 							overflow: 'auto',
 						} );
 					},
@@ -210,15 +259,19 @@ const Popover = (
 	const slotName = useContext( slotNameContext ) || __unstableSlotName;
 	const slot = useSlot( slotName );
 
-	const onDialogClose = ( type, event ) => {
-		// Ideally the popover should have just a single onClose prop and
-		// not three props that potentially do the same thing.
-		if ( type === 'focus-outside' && onFocusOutside ) {
-			onFocusOutside( event );
-		} else if ( onClose ) {
-			onClose();
-		}
-	};
+	let onDialogClose;
+
+	if ( onClose || onFocusOutside ) {
+		onDialogClose = ( type, event ) => {
+			// Ideally the popover should have just a single onClose prop and
+			// not three props that potentially do the same thing.
+			if ( type === 'focus-outside' && onFocusOutside ) {
+				onFocusOutside( event );
+			} else if ( onClose ) {
+				onClose();
+			}
+		};
+	}
 
 	const [ dialogRef, dialogProps ] = useDialog( {
 		focusOnMount,
@@ -227,33 +280,43 @@ const Popover = (
 	} );
 
 	const {
+		// Positioning coordinates
 		x,
 		y,
+		// Callback refs (not regular refs). This allows the position to be updated.
+		// when either elements change.
 		reference,
 		floating,
-		strategy,
+		// Object with "regular" refs to both "reference" and "floating"
 		refs,
+		// Type of CSS position property to use (absolute or fixed)
+		strategy,
 		update,
-		placement: placementData,
+		placement: computedPlacement,
 		middlewareData: { arrow: arrowData = {} },
-	} = useFloating( {
-		placement: usedPlacement,
-		middleware: middlewares,
-	} );
-	const staticSide = {
-		top: 'bottom',
-		right: 'left',
-		bottom: 'top',
-		left: 'right',
-	}[ placementData.split( '-' )[ 0 ] ];
-	const mergedRefs = useMergeRefs( [ floating, dialogRef, ref ] );
-
-	// Updates references
+	} = useFloating( { placement: normalizedPlacementFromProps, middleware } );
+
+	useEffect( () => {
+		offsetRef.current = offsetProp;
+		update();
+	}, [ offsetProp, update ] );
+
+	// Update the `reference`'s ref.
+	//
+	// In floating-ui's terms:
+	// - "reference" refers to the popover's anchor element.
+	// - "floating" refers the floating popover's element.
+	// A floating element can also be positioned relative to a virtual element,
+	// instead of a real one. A virtual element is represented by an object
+	// with the `getBoundingClientRect()` function (like real elements).
+	// See https://floating-ui.com/docs/virtual-elements for more info.
 	useLayoutEffect( () => {
-		// No ref or position have been passed
-		let usedRef;
+		let resultingReferenceRef;
+
 		if ( anchorRef?.top ) {
-			usedRef = {
+			// Create a virtual element for the ref. The expectation is that
+			// if anchorRef.top is defined, then anchorRef.bottom is defined too.
+			resultingReferenceRef = {
 				getBoundingClientRect() {
 					const topRect = anchorRef.top.getBoundingClientRect();
 					const bottomRect = anchorRef.bottom.getBoundingClientRect();
@@ -266,17 +329,22 @@ const Popover = (
 				},
 			};
 		} else if ( anchorRef?.current ) {
-			usedRef = anchorRef.current;
+			// Standard React ref.
+			resultingReferenceRef = anchorRef.current;
 		} else if ( anchorRef ) {
-			usedRef = anchorRef;
+			// If `anchorRef` holds directly the element's value (no `current` key)
+			// This is a weird scenario and should be deprecated.
+			resultingReferenceRef = anchorRef;
 		} else if ( anchorRect ) {
-			usedRef = {
+			// Create a virtual element for the ref.
+			resultingReferenceRef = {
 				getBoundingClientRect() {
 					return anchorRect;
 				},
 			};
 		} else if ( getAnchorRect ) {
-			usedRef = {
+			// Create a virtual element for the ref.
+			resultingReferenceRef = {
 				getBoundingClientRect() {
 					const rect = getAnchorRect( anchorRefFallback.current );
 					return new window.DOMRect(
@@ -288,23 +356,32 @@ const Popover = (
 				},
 			};
 		} else if ( anchorRefFallback.current ) {
-			usedRef = anchorRefFallback.current;
+			// If no explicit ref is passed via props, fall back to
+			// anchoring to the popover's parent node.
+			resultingReferenceRef = anchorRefFallback.current.parentNode;
 		}
 
-		if ( ! usedRef ) {
+		if ( ! resultingReferenceRef ) {
 			return;
 		}
 
-		reference( usedRef );
+		reference( resultingReferenceRef );
 
 		if ( ! refs.floating.current ) {
 			return;
 		}
 
-		return autoUpdate( usedRef, refs.floating.current, update );
-	}, [ anchorRef, anchorRect, getAnchorRect ] );
-
-	// This is only needed for a smoth transition when moving blocks.
+		return autoUpdate(
+			resultingReferenceRef,
+			refs.floating.current,
+			update
+		);
+		// 'reference' and 'refs.floating' are refs and don't need to be listed
+		// as dependencies (see https://github.com/WordPress/gutenberg/pull/41612)
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [ anchorRef, anchorRect, getAnchorRect, update ] );
+
+	// This is only needed for a smooth transition when moving blocks.
 	useLayoutEffect( () => {
 		if ( ! __unstableObserveElement ) {
 			return;
@@ -315,25 +392,49 @@ const Popover = (
 		return () => {
 			observer.disconnect();
 		};
-	}, [ __unstableObserveElement ] );
+	}, [ __unstableObserveElement, update ] );
 
-	// If we're using getAnchorRect, we need to update the position as we scroll the iframe.
+	// If the reference element is in a different ownerDocument (e.g. iFrame),
+	// we need to manually update the floating's position as the reference's owner
+	// document scrolls. Also update the frame offset if the view resizes.
 	useLayoutEffect( () => {
-		if ( ownerDocument === document ) {
+		if ( referenceOwnerDocument === document ) {
+			frameOffsetRef.current = undefined;
 			return;
 		}
 
-		ownerDocument.addEventListener( 'scroll', update );
-		return () => ownerDocument.removeEventListener( 'scroll', update );
-	}, [ ownerDocument ] );
+		const { defaultView } = referenceOwnerDocument;
 
-	/** @type {false | string} */
-	const animateClassName =
-		!! animate &&
-		getAnimateClassName( {
-			type: 'appear',
-			origin: placementToAnimationOrigin( placementData ),
-		} );
+		referenceOwnerDocument.addEventListener( 'scroll', update );
+
+		let updateFrameOffset;
+		const hasFrameElement =
+			!! referenceOwnerDocument?.defaultView?.frameElement;
+		if ( hasFrameElement ) {
+			updateFrameOffset = () => {
+				frameOffsetRef.current = getFrameOffset(
+					referenceOwnerDocument
+				);
+				update();
+			};
+			updateFrameOffset();
+			defaultView.addEventListener( 'resize', updateFrameOffset );
+		}
+
+		return () => {
+			referenceOwnerDocument.removeEventListener( 'scroll', update );
+
+			if ( updateFrameOffset ) {
+				defaultView.removeEventListener( 'resize', updateFrameOffset );
+			}
+		};
+	}, [ referenceOwnerDocument, update ] );
+
+	const mergedFloatingRef = useMergeRefs( [
+		floating,
+		dialogRef,
+		forwardedRef,
+	] );
 
 	// Disable reason: We care to capture the _bubbled_ events from inputs
 	// within popover as inferring close intent.
@@ -341,18 +442,15 @@ const Popover = (
 	let content = (
 		// eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
 		// eslint-disable-next-line jsx-a11y/no-static-element-interactions
-		<div
-			className={ classnames(
-				'components-popover',
-				className,
-				animateClassName,
-				{
-					'is-expanded': isExpanded,
-					'is-alternate': isAlternate,
-				}
-			) }
+		<MaybeAnimatedWrapper
+			shouldAnimate={ animate && ! isExpanded }
+			placement={ computedPlacement }
+			className={ classnames( 'components-popover', className, {
+				'is-expanded': isExpanded,
+				'is-alternate': isAlternate,
+			} ) }
 			{ ...contentProps }
-			ref={ mergedRefs }
+			ref={ mergedFloatingRef }
 			{ ...dialogProps }
 			tabIndex="-1"
 			style={
@@ -365,6 +463,7 @@ const Popover = (
 					  }
 			}
 		>
+			{ /* Prevents scroll on the document */ }
 			{ isExpanded && <ScrollLock /> }
 			{ isExpanded && (
 				<div className="components-popover__header">
@@ -381,24 +480,24 @@ const Popover = (
 			<div className="components-popover__content">{ children }</div>
 			{ hasArrow && (
 				<div
-					className="components-popover__arrow"
 					ref={ arrowRef }
+					className={ [
+						'components-popover__arrow',
+						`is-${ computedPlacement.split( '-' )[ 0 ] }`,
+					].join( ' ' ) }
 					style={ {
-						left:
-							! arrowData?.x || Number.isNaN( arrowData?.x )
-								? 0
-								: arrowData.x,
-						top:
-							! arrowData?.y || Number.isNaN( arrowData?.y )
-								? 0
-								: arrowData.y,
-						right: undefined,
-						bottom: undefined,
-						[ staticSide ]: '-4px',
+						left: Number.isFinite( arrowData?.x )
+							? `${ arrowData.x }px`
+							: '',
+						top: Number.isFinite( arrowData?.y )
+							? `${ arrowData.y }px`
+							: '',
 					} }
-				/>
+				>
+					<ArrowTriangle />
+				</div>
 			) }
-		</div>
+		</MaybeAnimatedWrapper>
 	);
 
 	if ( slot.ref ) {