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

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

@@ -1,7 +1,13 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory, ComponentMeta } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
-import { useState, useRef } from '@wordpress/element';
+import { useState, useRef, useEffect } from '@wordpress/element';
+// @ts-expect-error The `@wordpress/block-editor` is not typed
 import { __unstableIframe as Iframe } from '@wordpress/block-editor';
 
 /**
@@ -9,26 +15,10 @@ import { __unstableIframe as Iframe } from '@wordpress/block-editor';
  */
 import Button from '../../button';
 import { Provider as SlotFillProvider } from '../../slot-fill';
-import Popover from '../';
+import { Popover } from '..';
+import type { PopoverProps } from '../types';
 
-// Format: "[yAxis] [xAxis]"
-// Valid yAxis values: 'top', 'middle', 'bottom'
-// Valid xAxis values: 'left', 'center', 'right'
-const AVAILABLE_POSITIONS = [
-	'top left',
-	'top center',
-	'top right',
-	'middle left',
-	'middle center',
-	'middle right',
-	'bottom left',
-	'bottom center',
-	'bottom right',
-];
-
-// Follows floating UI's conventions
-// See https://floating-ui.com/docs/computePosition#placement
-const AVAILABLE_PLACEMENTS = [
+const AVAILABLE_PLACEMENTS: PopoverProps[ 'placement' ][] = [
 	'top',
 	'top-start',
 	'top-end',
@@ -43,42 +33,31 @@ const AVAILABLE_PLACEMENTS = [
 	'left-end',
 ];
 
-export default {
+const meta: ComponentMeta< typeof Popover > = {
 	title: 'Components/Popover',
 	component: Popover,
 	argTypes: {
+		anchor: { control: { type: null } },
 		anchorRef: { control: { type: null } },
 		anchorRect: { control: { type: null } },
-		animate: { control: { type: 'boolean' } },
 		children: { control: { type: null } },
-		className: { control: { type: 'text' } },
-		expandOnMobile: { control: { type: 'boolean' } },
 		focusOnMount: {
 			control: { type: 'select' },
-			options: [ 'firstElement', 'container', false ],
+			options: [ 'firstElement', true, false ],
 		},
 		getAnchorRect: { control: { type: null } },
-		headerTitle: { control: { type: 'text' } },
-		isAlternate: { control: { type: 'boolean' } },
-		noArrow: { control: { type: 'boolean' } },
-		onClose: { control: { type: null } },
-		offset: { control: { type: 'number' } },
-		onFocusOutside: { control: { type: null } },
-		placement: {
-			control: { type: 'select' },
-			options: AVAILABLE_PLACEMENTS,
-		},
-		position: {
-			control: { type: 'select' },
-			options: AVAILABLE_POSITIONS,
-		},
+		onClose: { action: 'onClose' },
+		onFocusOutside: { action: 'onFocusOutside' },
 		__unstableSlotName: { control: { type: null } },
-		__unstableForcePosition: { control: { type: 'boolean' } },
-		__unstableShift: { control: { type: 'boolean' } },
+	},
+	parameters: {
+		controls: { expanded: true },
 	},
 };
 
-const PopoverWithAnchor = ( args ) => {
+export default meta;
+
+const PopoverWithAnchor = ( args: PopoverProps ) => {
 	const anchorRef = useRef( null );
 
 	return (
@@ -101,23 +80,34 @@ const PopoverWithAnchor = ( args ) => {
 	);
 };
 
-export const Default = ( args ) => {
+export const Default: ComponentStory< typeof Popover > = ( args ) => {
 	const [ isVisible, setIsVisible ] = useState( false );
 	const toggleVisible = () => {
 		setIsVisible( ( state ) => ! state );
 	};
+	const buttonRef = useRef< HTMLButtonElement | undefined >();
+	useEffect( () => {
+		buttonRef.current?.scrollIntoView?.( {
+			block: 'center',
+			inline: 'center',
+		} );
+	}, [] );
 
 	return (
 		<div
 			style={ {
-				minWidth: '600px',
-				minHeight: '600px',
+				width: '300vw',
+				height: '300vh',
 				display: 'flex',
 				alignItems: 'center',
 				justifyContent: 'center',
 			} }
 		>
-			<Button variant="secondary" onClick={ toggleVisible }>
+			<Button
+				variant="secondary"
+				onClick={ toggleVisible }
+				ref={ buttonRef }
+			>
 				Toggle Popover
 				{ isVisible && <Popover { ...args } /> }
 			</Button>
@@ -135,11 +125,10 @@ Default.args = {
 	),
 };
 
-/**
- * Resize / scroll the viewport to test the behavior of the popovers when they
- * reach the viewport boundaries.
- */
-export const AllPlacements = ( { children, ...args } ) => (
+export const AllPlacements: ComponentStory< typeof Popover > = ( {
+	children,
+	...args
+} ) => (
 	<div
 		style={ {
 			minWidth: '600px',
@@ -180,10 +169,14 @@ AllPlacements.args = {
 	),
 	noArrow: false,
 	offset: 10,
-	__unstableForcePosition: true,
+	resize: false,
+	flip: false,
 };
 
-export const DynamicHeight = ( { children, ...args } ) => {
+export const DynamicHeight: ComponentStory< typeof Popover > = ( {
+	children,
+	...args
+} ) => {
 	const [ height, setHeight ] = useState( 200 );
 	const increase = () => setHeight( height + 100 );
 	const decrease = () => setHeight( height - 100 );
@@ -232,18 +225,23 @@ DynamicHeight.args = {
 	children: 'Content with dynamic height',
 };
 
-export const WithSlotOutsideIframe = ( args ) => {
+export const WithSlotOutsideIframe: ComponentStory< typeof Popover > = (
+	args
+) => {
 	const anchorRef = useRef( null );
 	const slotName = 'popover-with-slot-outside-iframe';
 
 	return (
 		<SlotFillProvider>
 			<div>
+				{ /* @ts-expect-error Slot is not currently typed on Popover */ }
 				<Popover.Slot name={ slotName } />
 				<Iframe
 					style={ {
 						width: '100%',
 						height: '400px',
+						border: '0',
+						outline: '1px solid purple',
 					} }
 				>
 					<div

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

@@ -0,0 +1,192 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode, MutableRefObject, SyntheticEvent } from 'react';
+import type { Placement } from '@floating-ui/react-dom';
+
+type PositionYAxis = 'top' | 'middle' | 'bottom';
+type PositionXAxis = 'left' | 'center' | 'right';
+type PositionCorner = 'top' | 'right' | 'bottom' | 'left';
+
+type DomRectWithOwnerDocument = DOMRect & {
+	ownerDocument?: Document;
+};
+
+export type AnimatedWrapperProps = {
+	placement: Placement;
+	shouldAnimate?: boolean;
+};
+
+export type PopoverAnchorRefReference = MutableRefObject<
+	Element | null | undefined
+>;
+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
+	 * be also passed to the corresponding `PopoverSlot` component.
+	 *
+	 * @default 'Popover'
+	 */
+	__unstableSlotName?: string;
+	/**
+	 * 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.
+	 */
+	anchor?: Element | VirtualElement | null;
+	/**
+	 * Whether the popover should animate when opening.
+	 *
+	 * @default true
+	 */
+	animate?: boolean;
+	/**
+	 * The `children` elements rendered as the popover's content.
+	 */
+	children: ReactNode;
+	/**
+	 * Show the popover fullscreen on mobile viewports.
+	 */
+	expandOnMobile?: boolean;
+	/**
+	 * Specifies whether the popover should flip across its axis if there isn't
+	 * space for it in the normal placement.
+	 * When the using a 'top' placement, the popover will switch to a 'bottom'
+	 * placement. When using a 'left' placement, the popover will switch to a
+	 * `right' placement.
+	 * The popover will retain its alignment of 'start' or 'end' when flipping.
+	 *
+	 * @default true
+	 */
+	flip?: boolean;
+	/**
+	 * By default, the _first tabbable element_ in the popover will receive focus
+	 * when it mounts. This is the same as setting this prop to `"firstElement"`.
+	 * Specifying a `false` value disables the focus handling entirely (this
+	 * should only be done when an appropriately accessible substitute behavior
+	 * exists).
+	 *
+	 * @default 'firstElement'
+	 */
+	focusOnMount?: 'firstElement' | boolean;
+	/**
+	 * A callback invoked when the focus leaves the opened popover. This should
+	 * only be provided in advanced use-cases when a popover should close under
+	 * specific circumstances (for example, if the new `document.activeElement`
+	 * is content of or otherwise controlling popover visibility).
+	 *
+	 * When not provided, the `onClose` callback will be called instead.
+	 */
+	onFocusOutside?: ( event: SyntheticEvent ) => void;
+	/**
+	 * Used to customize the header text shown when the popover is toggled to
+	 * fullscreen on mobile viewports (see the `expandOnMobile` prop).
+	 */
+	headerTitle?: string;
+	/**
+	 * Used to enable a different visual style for the popover.
+	 */
+	isAlternate?: boolean;
+	/**
+	 * Used to show/hide the arrow that points at the popover's anchor.
+	 *
+	 * @default true
+	 */
+	noArrow?: boolean;
+	/**
+	 * The distance (in px) between the anchor and the popover.
+	 */
+	offset?: number;
+	/**
+	 * A callback invoked when the popover should be closed.
+	 */
+	onClose?: () => void;
+	/**
+	 * Used to specify the popover's position with respect to its anchor.
+	 *
+	 * @default 'bottom-start'
+	 */
+	placement?: Placement;
+	/**
+	 * Legacy way to specify the popover's position with respect to its anchor.
+	 * _Note: this prop is deprecated. Use the `placement` prop instead._
+	 */
+	position?:
+		| `${ PositionYAxis } ${ PositionXAxis }`
+		| `${ PositionYAxis } ${ PositionXAxis } ${ PositionCorner }`;
+	/**
+	 * Adjusts the size of the popover to prevent its contents from going out of
+	 * view when meeting the viewport edges.
+	 *
+	 * @default true
+	 */
+	resize?: boolean;
+	/**
+	 * Enables the `Popover` to shift in order to stay in view when meeting the
+	 * viewport edges.
+	 *
+	 * @default false
+	 */
+	shift?: boolean;
+
+	// Deprecated props
+	/**
+	 * Prevent the popover from flipping and resizing when meeting the viewport
+	 * edges. _Note: this prop is deprecated. Instead, provide use the individual
+	 * `flip` and `resize` props._
+	 *
+	 * @deprecated
+	 */
+	__unstableForcePosition?: boolean;
+	/**
+	 * Enables the `Popover` to shift in order to stay in view when meeting the
+	 * viewport edges.
+	 * _Note: this prop is deprecated. Use the `shift` prop instead._
+	 *
+	 * @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._
+	 *
+	 * @deprecated
+	 */
+	range?: unknown;
+};

package/src/popover/utils.ts

@@ -0,0 +1,242 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { MotionProps } from 'framer-motion';
+import type { ReferenceType } from '@floating-ui/react-dom';
+
+/**
+ * Internal dependencies
+ */
+import type {
+	PopoverProps,
+	PopoverAnchorRefReference,
+	PopoverAnchorRefTopBottom,
+} from './types';
+
+/**
+ * Converts the `Popover`'s legacy "position" prop to the new "placement" prop
+ * (used by `floating-ui`).
+ *
+ * @param  position The legacy position
+ * @return The corresponding placement
+ */
+export const positionToPlacement = (
+	position: NonNullable< PopoverProps[ 'position' ] >
+): NonNullable< PopoverProps[ 'placement' ] > => {
+	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 ) as NonNullable< PopoverProps[ 'placement' ] >;
+	}
+
+	return y as NonNullable< PopoverProps[ 'placement' ] >;
+};
+
+/**
+ * @typedef AnimationOrigin
+ * @type {Object}
+ * @property {number} originX A number between 0 and 1 (in CSS logical properties jargon, 0 is "start", 0.5 is "center", and 1 is "end")
+ * @property {number} originY A number between 0 and 1 (0 is top, 0.5 is center, and 1 is bottom)
+ */
+
+const PLACEMENT_TO_ANIMATION_ORIGIN: Record<
+	NonNullable< PopoverProps[ 'placement' ] >,
+	{ originX: number; originY: number }
+> = {
+	top: { originX: 0.5, originY: 1 }, // open from bottom, center
+	'top-start': { originX: 0, originY: 1 }, // open from bottom, left
+	'top-end': { originX: 1, originY: 1 }, // open from bottom, right
+	right: { originX: 0, originY: 0.5 }, // open from middle, left
+	'right-start': { originX: 0, originY: 0 }, // open from top, left
+	'right-end': { originX: 0, originY: 1 }, // open from bottom, left
+	bottom: { originX: 0.5, originY: 0 }, // open from top, center
+	'bottom-start': { originX: 0, originY: 0 }, // open from top, left
+	'bottom-end': { originX: 1, originY: 0 }, // open from top, right
+	left: { originX: 1, originY: 0.5 }, // open from middle, right
+	'left-start': { originX: 1, originY: 0 }, // open from top, right
+	'left-end': { originX: 1, originY: 1 }, // open from bottom, right
+};
+
+/**
+ * Given the floating-ui `placement`, compute the framer-motion props for the
+ * popover's entry animation.
+ *
+ * @param  placement A placement string from floating ui
+ * @return The object containing the motion props
+ */
+export const placementToMotionAnimationProps = (
+	placement: NonNullable< PopoverProps[ 'placement' ] >
+): MotionProps => {
+	const translateProp =
+		placement.startsWith( 'top' ) || placement.startsWith( 'bottom' )
+			? 'translateY'
+			: 'translateX';
+	const translateDirection =
+		placement.startsWith( 'top' ) || placement.startsWith( 'left' )
+			? 1
+			: -1;
+
+	return {
+		style: PLACEMENT_TO_ANIMATION_ORIGIN[ placement ],
+		initial: {
+			opacity: 0,
+			scale: 0,
+			[ translateProp ]: `${ 2 * translateDirection }em`,
+		},
+		animate: { opacity: 1, scale: 1, [ translateProp ]: 0 },
+		transition: { duration: 0.1, ease: [ 0, 0, 0.2, 1 ] },
+	};
+};
+
+/**
+ * Returns the offset of a document's frame element.
+ *
+ * @param  document The iframe's owner document.
+ *
+ * @return The offset of the document's frame element, or undefined if the
+ * document has no frame element.
+ */
+export const getFrameOffset = (
+	document?: Document
+): { x: number; y: number } | undefined => {
+	const frameElement = document?.defaultView?.frameElement;
+	if ( ! frameElement ) {
+		return;
+	}
+	const iframeRect = frameElement.getBoundingClientRect();
+	return { x: iframeRect.left, y: iframeRect.top };
+};
+
+export const getReferenceOwnerDocument = ( {
+	anchor,
+	anchorRef,
+	anchorRect,
+	getAnchorRect,
+	fallbackReferenceElement,
+	fallbackDocument,
+}: Pick<
+	PopoverProps,
+	'anchorRef' | 'anchorRect' | 'getAnchorRect' | 'anchor'
+> & {
+	fallbackReferenceElement: Element | null;
+	fallbackDocument: Document;
+} ): Document => {
+	// 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.
+	let resultingReferenceOwnerDoc;
+	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 ) {
+		resultingReferenceOwnerDoc = ( anchorRef as Range ).startContainer
+			.ownerDocument;
+	} else if (
+		( anchorRef as PopoverAnchorRefReference | undefined )?.current
+	) {
+		resultingReferenceOwnerDoc = (
+			( anchorRef as PopoverAnchorRefReference ).current as Element
+		 ).ownerDocument;
+	} else if ( anchorRef as Element | undefined ) {
+		// This one should be deprecated.
+		resultingReferenceOwnerDoc = ( anchorRef as Element ).ownerDocument;
+	} else if ( anchorRect && anchorRect?.ownerDocument ) {
+		resultingReferenceOwnerDoc = anchorRect.ownerDocument;
+	} else if ( getAnchorRect ) {
+		resultingReferenceOwnerDoc = getAnchorRect(
+			fallbackReferenceElement
+		)?.ownerDocument;
+	}
+
+	return resultingReferenceOwnerDoc ?? fallbackDocument;
+};
+
+export const getReferenceElement = ( {
+	anchor,
+	anchorRef,
+	anchorRect,
+	getAnchorRect,
+	fallbackReferenceElement,
+}: Pick<
+	PopoverProps,
+	'anchorRef' | 'anchorRect' | 'getAnchorRect' | 'anchor'
+> & {
+	fallbackReferenceElement: Element | null;
+} ): ReferenceType | null => {
+	let referenceElement = null;
+
+	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
+		// (top and bottom blocks are used to calculate the resulting rect).
+		referenceElement = {
+			getBoundingClientRect() {
+				const topRect = (
+					anchorRef as PopoverAnchorRefTopBottom
+				 ).top.getBoundingClientRect();
+				const bottomRect = (
+					anchorRef as PopoverAnchorRefTopBottom
+				 ).bottom.getBoundingClientRect();
+				return new window.DOMRect(
+					topRect.x,
+					topRect.y,
+					topRect.width,
+					bottomRect.bottom - topRect.top
+				);
+			},
+		};
+	} else if (
+		( anchorRef as PopoverAnchorRefReference | undefined )?.current
+	) {
+		// Standard React ref.
+		referenceElement = ( anchorRef as PopoverAnchorRefReference ).current;
+	} else if ( anchorRef as Element | undefined ) {
+		// If `anchorRef` holds directly the element's value (no `current` key)
+		// This is a weird scenario and should be deprecated.
+		referenceElement = anchorRef as Element;
+	} else if ( anchorRect ) {
+		// Create a virtual element for the ref.
+		referenceElement = {
+			getBoundingClientRect() {
+				return anchorRect;
+			},
+		};
+	} else if ( getAnchorRect ) {
+		// Create a virtual element for the ref.
+		referenceElement = {
+			getBoundingClientRect() {
+				const rect = getAnchorRect( fallbackReferenceElement );
+				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 ( fallbackReferenceElement ) {
+		// If no explicit ref is passed via props, fall back to
+		// anchoring to the popover's parent node.
+		referenceElement = fallbackReferenceElement.parentElement;
+	}
+
+	// Convert any `undefined` value to `null`.
+	return referenceElement ?? null;
+};