@wordpress/components 20.0.2-next.957ca95e4c.0 → 21.0.1

package/src/popover/{index.js → index.tsx}

@@ -1,20 +1,26 @@
-// @ts-nocheck
 /**
  * External dependencies
  */
+import type { ForwardedRef, SyntheticEvent, RefCallback } from 'react';
 import classnames from 'classnames';
 import {
 	useFloating,
-	flip,
-	shift,
+	flip as flipMiddleware,
+	shift as shiftMiddleware,
 	autoUpdate,
 	arrow,
 	offset as offsetMiddleware,
 	limitShift,
 	size,
+	Middleware,
 } from '@floating-ui/react-dom';
 // eslint-disable-next-line no-restricted-imports
-import { motion, useReducedMotion } from 'framer-motion';
+import {
+	motion,
+	useReducedMotion,
+	HTMLMotionProps,
+	MotionProps,
+} from 'framer-motion';
 
 /**
  * WordPress dependencies
@@ -26,6 +32,8 @@ import {
 	createContext,
 	useContext,
 	useMemo,
+	useState,
+	useCallback,
 	useEffect,
 } from '@wordpress/element';
 import {
@@ -47,7 +55,16 @@ import {
 	getFrameOffset,
 	positionToPlacement,
 	placementToMotionAnimationProps,
+	getReferenceOwnerDocument,
+	getReferenceElement,
 } from './utils';
+import type { WordPressComponentProps } from '../ui/context';
+import type {
+	PopoverProps,
+	AnimatedWrapperProps,
+	PopoverAnchorRefReference,
+	PopoverAnchorRefTopBottom,
+} from './types';
 
 /**
  * Name of slot in which popover should fill.
@@ -60,9 +77,8 @@ const SLOT_NAME = 'Popover';
 // 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 ) => (
+const ArrowTriangle = () => (
 	<SVG
-		{ ...props }
 		xmlns="http://www.w3.org/2000/svg"
 		viewBox={ `0 0 100 100` }
 		className="components-popover__triangle"
@@ -80,16 +96,20 @@ const ArrowTriangle = ( props ) => (
 	</SVG>
 );
 
-const MaybeAnimatedWrapper = forwardRef(
+const AnimatedWrapper = forwardRef(
 	(
 		{
 			style: receivedInlineStyles,
 			placement,
 			shouldAnimate = false,
 			...props
-		},
-		forwardedRef
+		}: HTMLMotionProps< 'div' > & AnimatedWrapperProps,
+		forwardedRef: ForwardedRef< any >
 	) => {
+		// When animating, animate only once (i.e. when the popover is opened), and
+		// do not animate on subsequent prop changes (as it conflicts with
+		// floating-ui's positioning updates).
+		const [ hasAnimatedOnce, setHasAnimatedOnce ] = useState( false );
 		const shouldReduceMotion = useReducedMotion();
 
 		const { style: motionInlineStyles, ...otherMotionProps } = useMemo(
@@ -97,23 +117,32 @@ const MaybeAnimatedWrapper = forwardRef(
 			[ placement ]
 		);
 
-		if ( shouldAnimate && ! shouldReduceMotion ) {
-			return (
-				<motion.div
-					style={ {
-						...motionInlineStyles,
-						...receivedInlineStyles,
-					} }
-					{ ...otherMotionProps }
-					{ ...props }
-					ref={ forwardedRef }
-				/>
-			);
-		}
+		const onAnimationComplete = useCallback(
+			() => setHasAnimatedOnce( true ),
+			[]
+		);
+
+		const computedAnimationProps: HTMLMotionProps< 'div' > =
+			shouldAnimate && ! shouldReduceMotion
+				? {
+						style: {
+							...motionInlineStyles,
+							...receivedInlineStyles,
+						},
+						...otherMotionProps,
+						onAnimationComplete,
+						animate: hasAnimatedOnce
+							? false
+							: otherMotionProps.animate,
+				  }
+				: {
+						animate: false,
+						style: receivedInlineStyles,
+				  };
 
 		return (
-			<div
-				style={ receivedInlineStyles }
+			<motion.div
+				{ ...computedAnimationProps }
 				{ ...props }
 				ref={ forwardedRef }
 			/>
@@ -121,11 +150,19 @@ const MaybeAnimatedWrapper = forwardRef(
 	}
 );
 
-const slotNameContext = createContext();
-
-const Popover = (
-	{
-		range,
+const slotNameContext = createContext< string | undefined >( undefined );
+
+const UnforwardedPopover = (
+	props: Omit<
+		WordPressComponentProps< PopoverProps, 'div', false >,
+		// To avoid overlaps between the standard HTML attributes and the props
+		// expected by `framer-motion`, omit all framer motion props from popover
+		// props (except for `animate`, which is re-defined in `PopoverProps`).
+		keyof Omit< MotionProps, 'animate' >
+	>,
+	forwardedRef: ForwardedRef< any >
+) => {
+	const {
 		animate = true,
 		headerTitle,
 		onClose,
@@ -137,27 +174,98 @@ const Popover = (
 		placement: placementProp = 'bottom-start',
 		offset: offsetProp = 0,
 		focusOnMount = 'firstElement',
-		anchorRef,
-		anchorRect,
-		getAnchorRect,
+		anchor,
 		expandOnMobile,
 		onFocusOutside,
 		__unstableSlotName = SLOT_NAME,
-		__unstableForcePosition = false,
-		__unstableShift = false,
+		flip = true,
+		resize = true,
+		shift = false,
+
+		// Deprecated props
+		__unstableForcePosition,
+		__unstableShift,
+		anchorRef,
+		anchorRect,
+		getAnchorRect,
+		range,
+
+		// Rest
 		...contentProps
-	},
-	forwardedRef
-) => {
+	} = props;
+
 	if ( range ) {
-		deprecated( 'range prop in Popover component', {
+		deprecated( '`range` prop in wp.components.Popover', {
+			since: '6.1',
+			version: '6.3',
+		} );
+	}
+
+	let computedFlipProp = flip;
+	let computedResizeProp = resize;
+	if ( __unstableForcePosition !== undefined ) {
+		deprecated( '`__unstableForcePosition` prop wp.components.Popover', {
+			since: '6.1',
+			version: '6.3',
+			alternative: '`flip={ false }` and  `resize={ false }`',
+		} );
+
+		// Back-compat, set the `flip` and `resize` props
+		// to `false` to replicate `__unstableForcePosition`.
+		computedFlipProp = ! __unstableForcePosition;
+		computedResizeProp = ! __unstableForcePosition;
+	}
+
+	let shouldShift = shift;
+	if ( __unstableShift !== undefined ) {
+		deprecated( '`__unstableShift` prop in wp.components.Popover', {
+			since: '6.1',
+			version: '6.3',
+			alternative: '`shift` prop`',
+		} );
+
+		// Back-compat.
+		shouldShift = __unstableShift;
+	}
+
+	if ( anchorRef !== undefined ) {
+		deprecated( '`anchorRef` prop in wp.components.Popover', {
+			since: '6.1',
+			version: '6.3',
+			alternative: '`anchor` prop',
+		} );
+	}
+
+	if ( anchorRect !== undefined ) {
+		deprecated( '`anchorRect` prop in wp.components.Popover', {
+			since: '6.1',
+			version: '6.3',
+			alternative: '`anchor` prop',
+		} );
+	}
+
+	if ( getAnchorRect !== undefined ) {
+		deprecated( '`getAnchorRect` prop in wp.components.Popover', {
 			since: '6.1',
 			version: '6.3',
+			alternative: '`anchor` prop',
 		} );
 	}
 
 	const arrowRef = useRef( null );
-	const anchorRefFallback = useRef( null );
+
+	const [ fallbackReferenceElement, setFallbackReferenceElement ] =
+		useState< HTMLSpanElement | null >( null );
+	const [ referenceOwnerDocument, setReferenceOwnerDocument ] = useState<
+		Document | undefined
+	>();
+
+	const anchorRefFallback: RefCallback< HTMLSpanElement > = useCallback(
+		( node ) => {
+			setFallbackReferenceElement( node );
+		},
+		[]
+	);
 
 	const isMobileViewport = useViewportMatch( 'medium', '<' );
 	const isExpanded = expandOnMobile && isMobileViewport;
@@ -166,29 +274,6 @@ const Popover = (
 		? positionToPlacement( position )
 		: placementProp;
 
-	const referenceOwnerDocument = useMemo( () => {
-		let documentToReturn;
-
-		if ( anchorRef?.top ) {
-			documentToReturn = anchorRef?.top.ownerDocument;
-		} else if ( anchorRef?.startContainer ) {
-			documentToReturn = anchorRef.startContainer.ownerDocument;
-		} else if ( anchorRef?.current ) {
-			documentToReturn = anchorRef.current.ownerDocument;
-		} else if ( anchorRef ) {
-			// This one should be deprecated.
-			documentToReturn = anchorRef.ownerDocument;
-		} else if ( anchorRect && anchorRect?.ownerDocument ) {
-			documentToReturn = anchorRect.ownerDocument;
-		} else if ( getAnchorRect ) {
-			documentToReturn = getAnchorRect(
-				anchorRefFallback.current
-			)?.ownerDocument;
-		}
-
-		return documentToReturn ?? document;
-	}, [ anchorRef, anchorRect, getAnchorRect ] );
-
 	/**
 	 * Offsets the position of the popover when the anchor is inside an iframe.
 	 *
@@ -232,36 +317,43 @@ const Popover = (
 				crossAxis: frameOffsetRef.current[ crossAxis ],
 			};
 		} ),
-		__unstableForcePosition ? undefined : flip(),
-		__unstableForcePosition
-			? undefined
-			: size( {
+		computedFlipProp ? flipMiddleware() : undefined,
+		computedResizeProp
+			? size( {
 					apply( sizeProps ) {
-						const { availableHeight } = sizeProps;
-						if ( ! refs.floating.current ) return;
+						const { firstElementChild } =
+							refs.floating.current ?? {};
+
+						// Only HTMLElement instances have the `style` property.
+						if ( ! ( firstElementChild instanceof HTMLElement ) )
+							return;
+
 						// Reduce the height of the popover to the available space.
-						Object.assign( refs.floating.current.firstChild.style, {
-							maxHeight: `${ availableHeight }px`,
+						Object.assign( firstElementChild.style, {
+							maxHeight: `${ sizeProps.availableHeight }px`,
 							overflow: 'auto',
 						} );
 					},
-			  } ),
-		__unstableShift
-			? shift( {
+			  } )
+			: undefined,
+		shouldShift
+			? shiftMiddleware( {
 					crossAxis: true,
 					limiter: limitShift(),
 					padding: 1, // Necessary to avoid flickering at the edge of the viewport.
 			  } )
 			: undefined,
-		hasArrow ? arrow( { element: arrowRef } ) : undefined,
-	].filter( ( m ) => !! m );
+		arrow( { element: arrowRef } ),
+	].filter(
+		( m: Middleware | undefined ): m is Middleware => m !== undefined
+	);
 	const slotName = useContext( slotNameContext ) || __unstableSlotName;
 	const slot = useSlot( slotName );
 
 	let onDialogClose;
 
 	if ( onClose || onFocusOutside ) {
-		onDialogClose = ( type, event ) => {
+		onDialogClose = ( type: string | undefined, event: SyntheticEvent ) => {
 			// 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 ) {
@@ -275,6 +367,7 @@ const Popover = (
 	const [ dialogRef, dialogProps ] = useDialog( {
 		focusOnMount,
 		__unstableOnClose: onDialogClose,
+		// @ts-expect-error The __unstableOnClose property needs to be deprecated first (see https://github.com/WordPress/gutenberg/pull/27675)
 		onClose: onDialogClose,
 	} );
 
@@ -284,7 +377,7 @@ const Popover = (
 		y,
 		// Callback refs (not regular refs). This allows the position to be updated.
 		// when either elements change.
-		reference,
+		reference: referenceCallbackRef,
 		floating,
 		// Object with "regular" refs to both "reference" and "floating"
 		refs,
@@ -292,107 +385,77 @@ const Popover = (
 		strategy,
 		update,
 		placement: computedPlacement,
-		middlewareData: { arrow: arrowData = {} },
-	} = useFloating( { placement: normalizedPlacementFromProps, middleware } );
+		middlewareData: { arrow: arrowData },
+	} = useFloating( {
+		placement: normalizedPlacementFromProps,
+		middleware,
+		whileElementsMounted: ( referenceParam, floatingParam, updateParam ) =>
+			autoUpdate( referenceParam, floatingParam, updateParam, {
+				animationFrame: true,
+			} ),
+	} );
 
 	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( () => {
-		let resultingReferenceRef;
-
-		if ( anchorRef?.top ) {
-			// 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();
-					return new window.DOMRect(
-						topRect.x,
-						topRect.y,
-						topRect.width,
-						bottomRect.bottom - topRect.top
-					);
-				},
-			};
-		} else if ( anchorRef?.current ) {
-			// Standard React ref.
-			resultingReferenceRef = anchorRef.current;
-		} else if ( 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 ) {
-			// Create a virtual element for the ref.
-			resultingReferenceRef = {
-				getBoundingClientRect() {
-					return anchorRect;
-				},
-			};
-		} else if ( getAnchorRect ) {
-			// Create a virtual element for the ref.
-			resultingReferenceRef = {
-				getBoundingClientRect() {
-					const rect = getAnchorRect( anchorRefFallback.current );
-					return new window.DOMRect(
-						rect.x ?? rect.left,
-						rect.y ?? rect.top,
-						rect.width ?? rect.right - rect.left,
-						rect.height ?? rect.bottom - rect.top
-					);
-				},
-			};
-		} else if ( 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 ( ! resultingReferenceRef ) {
-			return;
-		}
+	const arrowCallbackRef = useCallback(
+		( node ) => {
+			arrowRef.current = node;
+			update();
+		},
+		[ update ]
+	);
 
-		reference( resultingReferenceRef );
+	// When any of the possible anchor "sources" change,
+	// recompute the reference element (real or virtual) and its owner document.
+	useLayoutEffect( () => {
+		const resultingReferenceOwnerDoc = getReferenceOwnerDocument( {
+			anchor,
+			anchorRef,
+			anchorRect,
+			getAnchorRect,
+			fallbackReferenceElement,
+			fallbackDocument: document,
+		} );
+		const resultingReferenceElement = getReferenceElement( {
+			anchor,
+			anchorRef,
+			anchorRect,
+			getAnchorRect,
+			fallbackReferenceElement,
+		} );
 
-		if ( ! refs.floating.current ) {
-			return;
-		}
+		referenceCallbackRef( resultingReferenceElement );
 
-		return autoUpdate(
-			resultingReferenceRef,
-			refs.floating.current,
-			update,
-			{
-				animationFrame: true,
-			}
-		);
-		// '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 ] );
+		setReferenceOwnerDocument( resultingReferenceOwnerDoc );
+	}, [
+		anchor,
+		anchorRef as Element | undefined,
+		( anchorRef as PopoverAnchorRefTopBottom | undefined )?.top,
+		( anchorRef as PopoverAnchorRefTopBottom | undefined )?.bottom,
+		( anchorRef as Range | undefined )?.startContainer,
+		( anchorRef as PopoverAnchorRefReference )?.current,
+		anchorRect,
+		getAnchorRect,
+		fallbackReferenceElement,
+		referenceCallbackRef,
+	] );
 
 	// 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( () => {
-		const referenceAndFloatingHaveSameDocument =
-			referenceOwnerDocument === document;
-		const hasFrameElement =
-			!! referenceOwnerDocument?.defaultView?.frameElement;
-
-		if ( referenceAndFloatingHaveSameDocument || ! hasFrameElement ) {
+		if (
+			// Reference and root documents are the same.
+			referenceOwnerDocument === document ||
+			// Reference and floating are in the same document.
+			referenceOwnerDocument === refs?.floating?.current?.ownerDocument ||
+			// The reference's document has no view (i.e. window)
+			// or frame element (ie. it's not an iframe).
+			! referenceOwnerDocument?.defaultView?.frameElement
+		) {
 			frameOffsetRef.current = undefined;
 			return;
 		}
@@ -424,7 +487,7 @@ const Popover = (
 	let content = (
 		// eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
 		// eslint-disable-next-line jsx-a11y/no-static-element-interactions
-		<MaybeAnimatedWrapper
+		<AnimatedWrapper
 			shouldAnimate={ animate && ! isExpanded }
 			placement={ computedPlacement }
 			className={ classnames( 'components-popover', className, {
@@ -434,14 +497,14 @@ const Popover = (
 			{ ...contentProps }
 			ref={ mergedFloatingRef }
 			{ ...dialogProps }
-			tabIndex="-1"
+			tabIndex={ -1 }
 			style={
 				isExpanded
 					? undefined
 					: {
 							position: strategy,
-							left: Number.isNaN( x ) ? 0 : x,
-							top: Number.isNaN( y ) ? 0 : y,
+							left: Number.isNaN( x ) ? 0 : x ?? undefined,
+							top: Number.isNaN( y ) ? 0 : y ?? undefined,
 					  }
 			}
 		>
@@ -462,42 +525,79 @@ const Popover = (
 			<div className="components-popover__content">{ children }</div>
 			{ hasArrow && (
 				<div
-					ref={ arrowRef }
+					ref={ arrowCallbackRef }
 					className={ [
 						'components-popover__arrow',
 						`is-${ computedPlacement.split( '-' )[ 0 ] }`,
 					].join( ' ' ) }
 					style={ {
-						left: Number.isFinite( arrowData?.x )
-							? `${ arrowData.x }px`
-							: '',
-						top: Number.isFinite( arrowData?.y )
-							? `${ arrowData.y }px`
-							: '',
+						left:
+							typeof arrowData?.x !== 'undefined' &&
+							Number.isFinite( arrowData.x )
+								? `${
+										arrowData.x +
+										( frameOffsetRef.current?.x ?? 0 )
+								  }px`
+								: '',
+						top:
+							typeof arrowData?.y !== 'undefined' &&
+							Number.isFinite( arrowData.y )
+								? `${
+										arrowData.y +
+										( frameOffsetRef.current?.y ?? 0 )
+								  }px`
+								: '',
 					} }
 				>
 					<ArrowTriangle />
 				</div>
 			) }
-		</MaybeAnimatedWrapper>
+		</AnimatedWrapper>
 	);
 
 	if ( slot.ref ) {
 		content = <Fill name={ slotName }>{ content }</Fill>;
 	}
 
-	if ( anchorRef || anchorRect ) {
+	if ( anchorRef || anchorRect || anchor ) {
 		return content;
 	}
 
 	return <span ref={ anchorRefFallback }>{ content }</span>;
 };
 
-const PopoverContainer = forwardRef( Popover );
+/**
+ * `Popover` renders its content in a floating modal. If no explicit anchor is passed via props, it anchors to its parent element by default.
+ *
+ * ```jsx
+ * import { Button, Popover } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyPopover = () => {
+ * 	const [ isVisible, setIsVisible ] = useState( false );
+ * 	const toggleVisible = () => {
+ * 		setIsVisible( ( state ) => ! state );
+ * 	};
+ *
+ * 	return (
+ * 		<Button variant="secondary" onClick={ toggleVisible }>
+ * 			Toggle Popover!
+ * 			{ isVisible && <Popover>Popover is toggled!</Popover> }
+ * 		</Button>
+ * 	);
+ * };
+ * ```
+ *
+ */
+export const Popover = forwardRef( UnforwardedPopover );
 
-function PopoverSlot( { name = SLOT_NAME }, ref ) {
+function PopoverSlot(
+	{ name = SLOT_NAME }: { name?: string },
+	ref: ForwardedRef< any >
+) {
 	return (
 		<Slot
+			// @ts-expect-error Need to type `SlotFill`
 			bubblesVirtually
 			name={ name }
 			className="popover-slot"
@@ -506,7 +606,9 @@ function PopoverSlot( { name = SLOT_NAME }, ref ) {
 	);
 }
 
-PopoverContainer.Slot = forwardRef( PopoverSlot );
-PopoverContainer.__unstableSlotNameProvider = slotNameContext.Provider;
+// @ts-expect-error For Legacy Reasons
+Popover.Slot = forwardRef( PopoverSlot );
+// @ts-expect-error For Legacy Reasons
+Popover.__unstableSlotNameProvider = slotNameContext.Provider;
 
-export default PopoverContainer;
+export default Popover;