@wordpress/components 21.0.0 → 21.0.2

package/src/popover/README.md

@@ -6,7 +6,9 @@ The behavior of the popover when it exceeds the viewport's edges can be controll
 
 ## Usage
 
-Render a Popover within the parent to which it should anchor:
+Render a Popover within the parent to which it should anchor.
+
+If a Popover is returned by your component, it will be shown. To hide the popover, simply omit it from your component's render value.
 
 ```jsx
 import { Button, Popover } from '@wordpress/components';
@@ -27,7 +29,36 @@ const MyPopover = () => {
 };
 ```
 
-If a Popover is returned by your component, it will be shown. To hide the popover, simply omit it from your component's render value.
+In order to pass an explicit anchor, you can use the `anchor` prop. When doing so, **the anchor element should be stored in local state** rather than a plain React ref to ensure reactive updating when it changes.
+
+```jsx
+import { Button, Popover } from '@wordpress/components';
+import { useState } from '@wordpress/element';
+
+const MyPopover = () => {
+	// Use internal state instead of a ref to make sure that the component
+	// re-renders when the popover's anchor updates.
+	const [ popoverAnchor, setPopoverAnchor ] = useState();
+	const [ isVisible, setIsVisible ] = useState( false );
+	const toggleVisible = () => {
+		setIsVisible( ( state ) => ! state );
+	};
+
+	return (
+		<p ref={ setPopoverAnchor }>Popover s anchor</p>
+		<Button variant="secondary" onClick={ toggleVisible }>
+			Toggle Popover!
+		</Button>
+		{ isVisible && (
+			<Popover
+				anchor={ popoverAnchor }
+			>
+				Popover is toggled!
+			</Popover>
+		) }
+	);
+};
+```
 
 If you want Popover elements to render to a specific location on the page to allow style cascade to take effect, you must render a `Popover.Slot` further up the element tree:
 
@@ -51,14 +82,26 @@ render(
 
 The component accepts the following props. Props not included in this set will be applied to the element wrapping Popover content.
 
+### `anchor`: `Element | VirtualElement | null`
+
+The element that should be used by the `Popover` as its anchor. It can either be an `Element` or, alternatively, a `VirtualElement` — ie. an object with the `getBoundingClientRect()` and the `ownerDocument` properties defined.
+
+The element should be stored in state rather than a plain ref to ensure reactive updating when it changes.
+
+-   Required: No
+
 ### `anchorRect`: `DomRectWithOwnerDocument`
 
+_Note: this prop is deprecated and will be removed in WordPress 6.3. Please use the `anchor` prop instead._
+
 An object extending a `DOMRect` with an additional optional `ownerDocument` property, used to specify a fixed popover position.
 
 -   Required: No
 
 ### `anchorRef`: `Element | PopoverAnchorRefReference | PopoverAnchorRefTopBottom | Range`
 
+_Note: this prop is deprecated and will be removed in WordPress 6.3. Please use the `anchor` prop instead._
+
 Used to specify a fixed popover position. It can be an `Element`, a React reference to an `element`, an object with a `top` and a `bottom` properties (both pointing to elements), or a `range`.
 
 -   Required: No
@@ -114,6 +157,8 @@ When not provided, the `onClose` callback will be called instead.
 
 ### `getAnchorRect`: `( fallbackReferenceElement: Element | null ) => DomRectWithOwnerDocument`
 
+_Note: this prop is deprecated and will be removed in WordPress 6.3. Please use the `anchor` prop instead._
+
 A function returning the same value as the one expected by the `anchorRect` prop, used to specify a dynamic popover position.
 
 -   Required: No
@@ -180,6 +225,6 @@ Adjusts the size of the popover to prevent its contents from going out of view w
 
 ### `range`: `unknown`
 
-_Note: this prop is deprecated and has no effect on the component._
+_Note: this prop is deprecated and will be removed in WordPress 6.3. It has no effect on the component._
 
 -   Required: No

package/src/popover/index.tsx

@@ -163,7 +163,6 @@ const UnforwardedPopover = (
 	forwardedRef: ForwardedRef< any >
 ) => {
 	const {
-		range,
 		animate = true,
 		headerTitle,
 		onClose,
@@ -175,22 +174,28 @@ const UnforwardedPopover = (
 		placement: placementProp = 'bottom-start',
 		offset: offsetProp = 0,
 		focusOnMount = 'firstElement',
-		anchorRef,
-		anchorRect,
-		getAnchorRect,
+		anchor,
 		expandOnMobile,
 		onFocusOutside,
 		__unstableSlotName = SLOT_NAME,
 		flip = true,
 		resize = true,
 		shift = false,
-		__unstableShift,
+
+		// Deprecated props
 		__unstableForcePosition,
+		__unstableShift,
+		anchorRef,
+		anchorRect,
+		getAnchorRect,
+		range,
+
+		// Rest
 		...contentProps
 	} = props;
 
 	if ( range ) {
-		deprecated( 'range prop in Popover component', {
+		deprecated( '`range` prop in wp.components.Popover', {
 			since: '6.1',
 			version: '6.3',
 		} );
@@ -199,7 +204,7 @@ const UnforwardedPopover = (
 	let computedFlipProp = flip;
 	let computedResizeProp = resize;
 	if ( __unstableForcePosition !== undefined ) {
-		deprecated( '__unstableForcePosition prop in Popover component', {
+		deprecated( '`__unstableForcePosition` prop wp.components.Popover', {
 			since: '6.1',
 			version: '6.3',
 			alternative: '`flip={ false }` and  `resize={ false }`',
@@ -213,7 +218,7 @@ const UnforwardedPopover = (
 
 	let shouldShift = shift;
 	if ( __unstableShift !== undefined ) {
-		deprecated( '`__unstableShift` prop in Popover component', {
+		deprecated( '`__unstableShift` prop in wp.components.Popover', {
 			since: '6.1',
 			version: '6.3',
 			alternative: '`shift` prop`',
@@ -223,6 +228,30 @@ const UnforwardedPopover = (
 		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 [ fallbackReferenceElement, setFallbackReferenceElement ] =
@@ -383,6 +412,7 @@ const UnforwardedPopover = (
 	// recompute the reference element (real or virtual) and its owner document.
 	useLayoutEffect( () => {
 		const resultingReferenceOwnerDoc = getReferenceOwnerDocument( {
+			anchor,
 			anchorRef,
 			anchorRect,
 			getAnchorRect,
@@ -390,6 +420,7 @@ const UnforwardedPopover = (
 			fallbackDocument: document,
 		} );
 		const resultingReferenceElement = getReferenceElement( {
+			anchor,
 			anchorRef,
 			anchorRect,
 			getAnchorRect,
@@ -400,6 +431,7 @@ const UnforwardedPopover = (
 
 		setReferenceOwnerDocument( resultingReferenceOwnerDoc );
 	}, [
+		anchor,
 		anchorRef as Element | undefined,
 		( anchorRef as PopoverAnchorRefTopBottom | undefined )?.top,
 		( anchorRef as PopoverAnchorRefTopBottom | undefined )?.bottom,
@@ -527,7 +559,7 @@ const UnforwardedPopover = (
 		content = <Fill name={ slotName }>{ content }</Fill>;
 	}
 
-	if ( anchorRef || anchorRect ) {
+	if ( anchorRef || anchorRect || anchor ) {
 		return content;
 	}
 

package/src/popover/stories/index.tsx

@@ -37,6 +37,7 @@ const meta: ComponentMeta< typeof Popover > = {
 	title: 'Components/Popover',
 	component: Popover,
 	argTypes: {
+		anchor: { control: { type: null } },
 		anchorRef: { control: { type: null } },
 		anchorRect: { control: { type: null } },
 		children: { control: { type: null } },

package/src/popover/test/index.js

@@ -6,7 +6,7 @@ import { act, render, screen } from '@testing-library/react';
 /**
  * WordPress dependencies
  */
-import { useRef } from '@wordpress/element';
+import { useState } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -57,14 +57,16 @@ describe( 'Popover', () => {
 			).toMatchSnapshot();
 		} );
 
-		it( 'should render correctly when anchorRef is provided', () => {
+		it( 'should render correctly when anchor is provided', () => {
 			const PopoverWithAnchor = ( args ) => {
-				const anchorRef = useRef( null );
+				// Use internal state instead of a ref to make sure that the component
+				// re-renders when the popover's anchor updates.
+				const [ anchor, setAnchor ] = useState( null );
 
 				return (
 					<div>
-						<p ref={ anchorRef }>Anchor</p>
-						<Popover { ...args } anchorRef={ anchorRef } />
+						<p ref={ setAnchor }>Anchor</p>
+						<Popover { ...args } anchor={ anchor } />
 					</div>
 				);
 			};

package/src/popover/types.ts

@@ -22,6 +22,10 @@ export type PopoverAnchorRefReference = MutableRefObject<
 >;
 export type PopoverAnchorRefTopBottom = { top: Element; bottom: Element };
 
+export type VirtualElement = Pick< Element, 'getBoundingClientRect' > & {
+	ownerDocument?: Document;
+};
+
 export type PopoverProps = {
 	/**
 	 * The name of the Slot in which the popover should be rendered. It should
@@ -31,20 +35,14 @@ export type PopoverProps = {
 	 */
 	__unstableSlotName?: string;
 	/**
-	 * An object extending a `DOMRect` with an additional optional `ownerDocument`
-	 * property, used to specify a fixed popover position.
-	 */
-	anchorRect?: DomRectWithOwnerDocument;
-	/**
-	 * Used to specify a fixed popover position. It can be an `Element`, a React
-	 * reference to an `element`, an object with a `top` and a `bottom` properties
-	 * (both pointing to elements), or a `range`.
+	 * The element that should be used by the popover as its anchor. It can either
+	 * be an `Element` or, alternatively, a `VirtualElement` — ie. an object with
+	 * the `getBoundingClientRect()` and the `ownerDocument` properties defined.
+	 *
+	 * **The anchor element should be stored in local state** rather than a
+	 * plain React ref to ensure reactive updating when it changes.
 	 */
-	anchorRef?:
-		| Element
-		| PopoverAnchorRefReference
-		| PopoverAnchorRefTopBottom
-		| Range;
+	anchor?: Element | VirtualElement | null;
 	/**
 	 * Whether the popover should animate when opening.
 	 *
@@ -89,13 +87,6 @@ export type PopoverProps = {
 	 * When not provided, the `onClose` callback will be called instead.
 	 */
 	onFocusOutside?: ( event: SyntheticEvent ) => void;
-	/**
-	 * A function returning the same value as the one expected by the `anchorRect`
-	 * prop, used to specify a dynamic popover position.
-	 */
-	getAnchorRect?: (
-		fallbackReferenceElement: Element | null
-	) => DomRectWithOwnerDocument;
 	/**
 	 * Used to customize the header text shown when the popover is toggled to
 	 * fullscreen on mobile viewports (see the `expandOnMobile` prop).
@@ -164,6 +155,34 @@ export type PopoverProps = {
 	 * @deprecated
 	 */
 	__unstableShift?: boolean;
+	/**
+	 * An object extending a `DOMRect` with an additional optional `ownerDocument`
+	 * property, used to specify a fixed popover position.
+	 *
+	 * @deprecated
+	 */
+	anchorRect?: DomRectWithOwnerDocument;
+	/**
+	 * Used to specify a fixed popover position. It can be an `Element`, a React
+	 * reference to an `element`, an object with a `top` and a `bottom` properties
+	 * (both pointing to elements), or a `range`.
+	 *
+	 * @deprecated
+	 */
+	anchorRef?:
+		| Element
+		| PopoverAnchorRefReference
+		| PopoverAnchorRefTopBottom
+		| Range;
+	/**
+	 * A function returning the same value as the one expected by the `anchorRect`
+	 * prop, used to specify a dynamic popover position.
+	 *
+	 * @deprecated
+	 */
+	getAnchorRect?: (
+		fallbackReferenceElement: Element | null
+	) => DomRectWithOwnerDocument;
 	/**
 	 * _Note: this prop is deprecated and has no effect on the component._
 	 *

package/src/popover/utils.ts

@@ -116,12 +116,16 @@ export const getFrameOffset = (
 };
 
 export const getReferenceOwnerDocument = ( {
+	anchor,
 	anchorRef,
 	anchorRect,
 	getAnchorRect,
 	fallbackReferenceElement,
 	fallbackDocument,
-}: Pick< PopoverProps, 'anchorRef' | 'anchorRect' | 'getAnchorRect' > & {
+}: Pick<
+	PopoverProps,
+	'anchorRef' | 'anchorRect' | 'getAnchorRect' | 'anchor'
+> & {
 	fallbackReferenceElement: Element | null;
 	fallbackDocument: Document;
 } ): Document => {
@@ -133,7 +137,9 @@ export const getReferenceOwnerDocument = ( {
 	// with the `getBoundingClientRect()` function (like real elements).
 	// See https://floating-ui.com/docs/virtual-elements for more info.
 	let resultingReferenceOwnerDoc;
-	if ( ( anchorRef as PopoverAnchorRefTopBottom | undefined )?.top ) {
+	if ( anchor ) {
+		resultingReferenceOwnerDoc = anchor.ownerDocument;
+	} else if ( ( anchorRef as PopoverAnchorRefTopBottom | undefined )?.top ) {
 		resultingReferenceOwnerDoc = ( anchorRef as PopoverAnchorRefTopBottom )
 			?.top.ownerDocument;
 	} else if ( ( anchorRef as Range | undefined )?.startContainer ) {
@@ -160,16 +166,22 @@ export const getReferenceOwnerDocument = ( {
 };
 
 export const getReferenceElement = ( {
+	anchor,
 	anchorRef,
 	anchorRect,
 	getAnchorRect,
 	fallbackReferenceElement,
-}: Pick< PopoverProps, 'anchorRef' | 'anchorRect' | 'getAnchorRect' > & {
+}: Pick<
+	PopoverProps,
+	'anchorRef' | 'anchorRect' | 'getAnchorRect' | 'anchor'
+> & {
 	fallbackReferenceElement: Element | null;
 } ): ReferenceType | null => {
 	let referenceElement = null;
 
-	if ( ( anchorRef as PopoverAnchorRefTopBottom | undefined )?.top ) {
+	if ( anchor ) {
+		referenceElement = anchor;
+	} else if ( ( anchorRef as PopoverAnchorRefTopBottom | undefined )?.top ) {
 		// Create a virtual element for the ref. The expectation is that
 		// if anchorRef.top is defined, then anchorRef.bottom is defined too.
 		// Seems to be used by the block toolbar, when multiple blocks are selected

package/src/tooltip/index.js

@@ -9,7 +9,6 @@ import {
 	concatChildren,
 	useEffect,
 	useState,
-	useRef,
 } from '@wordpress/element';
 import { useDebounce, useMergeRefs } from '@wordpress/compose';
 
@@ -60,7 +59,7 @@ const getRegularElement = ( {
 };
 
 const addPopoverToGrandchildren = ( {
-	anchorRef,
+	anchor,
 	grandchildren,
 	isOver,
 	offset,
@@ -78,7 +77,7 @@ const addPopoverToGrandchildren = ( {
 				aria-hidden="true"
 				animate={ false }
 				offset={ offset }
-				anchorRef={ anchorRef }
+				anchor={ anchor }
 				shift
 			>
 				{ text }
@@ -124,13 +123,18 @@ function Tooltip( props ) {
 	const [ isMouseDown, setIsMouseDown ] = useState( false );
 	const [ isOver, setIsOver ] = useState( false );
 	const delayedSetIsOver = useDebounce( setIsOver, delay );
+	// Using internal state (instead of a ref) for the popover anchor to make sure
+	// that the component re-renders when the anchor updates.
+	const [ popoverAnchor, setPopoverAnchor ] = useState( null );
 
 	// Create a reference to the Tooltip's child, to be passed to the Popover
 	// so that the Tooltip can be correctly positioned. Also, merge with the
 	// existing ref for the first child, so that its ref is preserved.
-	const childRef = useRef( null );
 	const existingChildRef = Children.toArray( children )[ 0 ]?.ref;
-	const mergedChildRefs = useMergeRefs( [ childRef, existingChildRef ] );
+	const mergedChildRefs = useMergeRefs( [
+		setPopoverAnchor,
+		existingChildRef,
+	] );
 
 	const createMouseDown = ( event ) => {
 		// In firefox, the mouse down event is also fired when the select
@@ -253,7 +257,7 @@ function Tooltip( props ) {
 		: getRegularElement;
 
 	const popoverData = {
-		anchorRef: childRef,
+		anchor: popoverAnchor,
 		isOver,
 		offset: 4,
 		position,

package/tsconfig.json

@@ -18,6 +18,7 @@
 		"strictNullChecks": true
 	},
 	"references": [
+		{ "path": "../a11y" },
 		{ "path": "../compose" },
 		{ "path": "../date" },
 		{ "path": "../deprecated" },