@wordpress/components 23.3.2 → 23.4.0

package/src/popover/index.tsx

@@ -43,6 +43,7 @@ import {
 import { close } from '@wordpress/icons';
 import deprecated from '@wordpress/deprecated';
 import { Path, SVG } from '@wordpress/primitives';
+import { getScrollContainer } from '@wordpress/dom';
 
 /**
  * Internal dependencies
@@ -52,6 +53,7 @@ import ScrollLock from '../scroll-lock';
 import { Slot, Fill, useSlot } from '../slot-fill';
 import {
 	getFrameOffset,
+	getFrameScale,
 	positionToPlacement,
 	placementToMotionAnimationProps,
 	getReferenceOwnerDocument,
@@ -65,6 +67,7 @@ import type {
 	PopoverAnchorRefTopBottom,
 } from './types';
 import { limitShift as customLimitShift } from './limit-shift';
+import { overlayMiddlewares } from './overlay-middlewares';
 
 /**
  * Name of slot in which popover should fill.
@@ -268,6 +271,7 @@ const UnforwardedPopover = (
 	const frameOffsetRef = useRef( getFrameOffset( referenceOwnerDocument ) );
 
 	const middleware = [
+		...( placementProp === 'overlay' ? overlayMiddlewares() : [] ),
 		// Custom middleware which adjusts the popover's position by taking into
 		// account the offset of the anchor's iframe (if any) compared to the page.
 		{
@@ -361,7 +365,10 @@ const UnforwardedPopover = (
 		placement: computedPlacement,
 		middlewareData: { arrow: arrowData },
 	} = useFloating( {
-		placement: normalizedPlacementFromProps,
+		placement:
+			normalizedPlacementFromProps === 'overlay'
+				? undefined
+				: normalizedPlacementFromProps,
 		middleware,
 		whileElementsMounted: ( referenceParam, floatingParam, updateParam ) =>
 			autoUpdate( referenceParam, floatingParam, updateParam, {
@@ -399,12 +406,14 @@ const UnforwardedPopover = (
 			fallbackReferenceElement,
 			fallbackDocument: document,
 		} );
+		const scale = getFrameScale( resultingReferenceOwnerDoc );
 		const resultingReferenceElement = getReferenceElement( {
 			anchor,
 			anchorRef,
 			anchorRect,
 			getAnchorRect,
 			fallbackReferenceElement,
+			scale,
 		} );
 
 		referenceCallbackRef( resultingReferenceElement );
@@ -441,17 +450,24 @@ const UnforwardedPopover = (
 		}
 
 		const { defaultView } = referenceOwnerDocument;
+		const { frameElement } = defaultView;
+
+		const scrollContainer = frameElement
+			? getScrollContainer( frameElement )
+			: null;
 
 		const updateFrameOffset = () => {
 			frameOffsetRef.current = getFrameOffset( referenceOwnerDocument );
 			update();
 		};
 		defaultView.addEventListener( 'resize', updateFrameOffset );
+		scrollContainer?.addEventListener( 'scroll', updateFrameOffset );
 
 		updateFrameOffset();
 
 		return () => {
 			defaultView.removeEventListener( 'resize', updateFrameOffset );
+			scrollContainer?.removeEventListener( 'scroll', updateFrameOffset );
 		};
 	}, [ referenceOwnerDocument, update, refs.floating ] );
 

package/src/popover/overlay-middlewares.tsx

@@ -0,0 +1,29 @@
+/**
+ * External dependencies
+ */
+import { size, MiddlewareArguments } from '@floating-ui/react-dom';
+
+export function overlayMiddlewares() {
+	return [
+		{
+			name: 'overlay',
+			fn( { rects }: MiddlewareArguments ) {
+				return rects.reference;
+			},
+		},
+		size( {
+			apply( { rects, elements } ) {
+				const { firstElementChild } = elements.floating ?? {};
+
+				// Only HTMLElement instances have the `style` property.
+				if ( ! ( firstElementChild instanceof HTMLElement ) ) return;
+
+				// Reduce the height of the popover to the available space.
+				Object.assign( firstElementChild.style, {
+					width: `${ rects.reference.width }px`,
+					height: `${ rects.reference.height }px`,
+				} );
+			},
+		} ),
+	];
+}

package/src/popover/stories/index.tsx

@@ -31,6 +31,7 @@ const AVAILABLE_PLACEMENTS: PopoverProps[ 'placement' ][] = [
 	'left',
 	'left-start',
 	'left-end',
+	'overlay',
 ];
 
 const meta: ComponentMeta< typeof Popover > = {
@@ -170,7 +171,12 @@ export const AllPlacements: ComponentStory< typeof Popover > = ( {
 		</h2>
 		<div>
 			{ AVAILABLE_PLACEMENTS.map( ( p ) => (
-				<PopoverWithAnchor key={ p } placement={ p } { ...args }>
+				<PopoverWithAnchor
+					key={ p }
+					placement={ p }
+					{ ...args }
+					resize={ p === 'overlay' ? true : args.resize }
+				>
 					{ children }
 					<div>
 						<small>(placement: { p })</small>

package/src/popover/test/index.tsx

@@ -1,8 +1,8 @@
 /**
  * External dependencies
  */
-import { act, render, screen } from '@testing-library/react';
-import type { CSSProperties, ReactElement } from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import type { CSSProperties } from 'react';
 
 /**
  * WordPress dependencies
@@ -91,25 +91,21 @@ const ALL_POSITIONS_TO_EXPECTED_PLACEMENTS: PositionToPlacementTuple[] = [
 
 describe( 'Popover', () => {
 	describe( 'Component', () => {
-		// Render UI and then wait for the `floating-ui` effects inside `Popover` to finish running
-		// See also: https://floating-ui.com/docs/react-dom#testing
-		async function renderAsync( ui: ReactElement ) {
-			const view = render( ui );
-			await act( () => Promise.resolve() );
-			return view;
-		}
-
 		describe( 'basic behavior', () => {
 			it( 'should render content', async () => {
-				await renderAsync( <Popover>Hello</Popover> );
+				render( <Popover>Hello</Popover> );
 
-				expect( screen.getByText( 'Hello' ) ).toBeInTheDocument();
+				await waitFor( () =>
+					expect( screen.getByText( 'Hello' ) ).toBeVisible()
+				);
 			} );
 
 			it( 'should forward additional props to portaled element', async () => {
-				await renderAsync( <Popover role="tooltip">Hello</Popover> );
+				render( <Popover role="tooltip">Hello</Popover> );
 
-				expect( screen.getByRole( 'tooltip' ) ).toBeInTheDocument();
+				await waitFor( () =>
+					expect( screen.getByRole( 'tooltip' ) ).toBeVisible()
+				);
 			} );
 		} );
 
@@ -129,32 +125,44 @@ describe( 'Popover', () => {
 					);
 				};
 
-				await renderAsync(
+				render(
 					<PopoverWithAnchor>Popover content</PopoverWithAnchor>
 				);
 
-				expect(
-					screen.getByText( 'Popover content' )
-				).toBeInTheDocument();
+				await waitFor( () =>
+					expect(
+						screen.getByText( 'Popover content' )
+					).toBeVisible()
+				);
 			} );
 		} );
 
 		describe( 'focus behavior', () => {
 			it( 'should focus the popover by default when opened', async () => {
-				await renderAsync(
+				render(
 					<Popover data-testid="popover-element">
 						Popover content
 					</Popover>
 				);
 
-				expect( screen.getByTestId( 'popover-element' ) ).toHaveFocus();
+				const popover = screen.getByTestId( 'popover-element' );
+
+				await waitFor( () => expect( popover ).toBeVisible() );
+
+				expect( popover ).toHaveFocus();
 			} );
 
 			it( 'should allow focus-on-open behavior to be disabled', async () => {
-				await renderAsync(
+				render(
 					<Popover focusOnMount={ false }>Popover content</Popover>
 				);
 
+				await waitFor( () =>
+					expect(
+						screen.getByText( 'Popover content' )
+					).toBeVisible()
+				);
+
 				expect( document.body ).toHaveFocus();
 			} );
 		} );

package/src/popover/types.ts

@@ -12,8 +12,10 @@ type DomRectWithOwnerDocument = DOMRect & {
 	ownerDocument?: Document;
 };
 
+type PopoverPlacement = Placement | 'overlay';
+
 export type AnimatedWrapperProps = {
-	placement: Placement;
+	placement: PopoverPlacement;
 	shouldAnimate?: boolean;
 };
 
@@ -111,7 +113,7 @@ export type PopoverProps = {
 	 *
 	 * @default 'bottom-start'
 	 */
-	placement?: Placement;
+	placement?: PopoverPlacement;
 	/**
 	 * Legacy way to specify the popover's position with respect to its anchor.
 	 * _Note: this prop is deprecated. Use the `placement` prop instead._

package/src/popover/utils.ts

@@ -74,7 +74,7 @@ const POSITION_TO_PLACEMENT: Record<
  * Converts the `Popover`'s legacy "position" prop to the new "placement" prop
  * (used by `floating-ui`).
  *
- * @param  position The legacy position
+ * @param position The legacy position
  * @return The corresponding placement
  */
 export const positionToPlacement = (
@@ -105,13 +105,14 @@ const PLACEMENT_TO_ANIMATION_ORIGIN: Record<
 	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
+	overlay: { originX: 0.5, originY: 0.5 }, // open from center, center
 };
 
 /**
  * Given the floating-ui `placement`, compute the framer-motion props for the
  * popover's entry animation.
  *
- * @param  placement A placement string from floating ui
+ * @param placement A placement string from floating ui
  * @return The object containing the motion props
  */
 export const placementToMotionAnimationProps = (
@@ -141,7 +142,7 @@ export const placementToMotionAnimationProps = (
 /**
  * Returns the offset of a document's frame element.
  *
- * @param  document The iframe's owner document.
+ * @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.
@@ -157,6 +158,23 @@ export const getFrameOffset = (
 	return { x: iframeRect.left, y: iframeRect.top };
 };
 
+export const getFrameScale = (
+	document?: Document
+): {
+	x: number;
+	y: number;
+} => {
+	const frameElement = document?.defaultView?.frameElement as HTMLElement;
+	if ( ! frameElement ) {
+		return { x: 1, y: 1 };
+	}
+	const rect = frameElement.getBoundingClientRect();
+	return {
+		x: rect.width / frameElement.offsetWidth,
+		y: rect.height / frameElement.offsetHeight,
+	};
+};
+
 export const getReferenceOwnerDocument = ( {
 	anchor,
 	anchorRef,
@@ -213,11 +231,13 @@ export const getReferenceElement = ( {
 	anchorRect,
 	getAnchorRect,
 	fallbackReferenceElement,
+	scale,
 }: Pick<
 	PopoverProps,
 	'anchorRef' | 'anchorRect' | 'getAnchorRect' | 'anchor'
 > & {
 	fallbackReferenceElement: Element | null;
+	scale: { x: number; y: number };
 } ): ReferenceType | null => {
 	let referenceElement = null;
 
@@ -279,6 +299,22 @@ export const getReferenceElement = ( {
 		referenceElement = fallbackReferenceElement.parentElement;
 	}
 
+	if ( referenceElement && ( scale.x !== 1 || scale.y !== 1 ) ) {
+		// If the popover is inside an iframe, the coordinates of the
+		// reference element need to be scaled to match the iframe's scale.
+		const rect = referenceElement.getBoundingClientRect();
+		referenceElement = {
+			getBoundingClientRect() {
+				return new window.DOMRect(
+					rect.x * scale.x,
+					rect.y * scale.y,
+					rect.width * scale.x,
+					rect.height * scale.y
+				);
+			},
+		};
+	}
+
 	// Convert any `undefined` value to `null`.
 	return referenceElement ?? null;
 };

package/src/query-controls/terms.ts

@@ -16,7 +16,7 @@ import type {
 /**
  * Returns terms in a tree form.
  *
- * @param  flatTerms Array of terms in flat format.
+ * @param flatTerms Array of terms in flat format.
  *
  * @return Terms in tree format.
  */

package/src/range-control/utils.ts

@@ -14,9 +14,9 @@ import type { UseControlledRangeValueArgs } from './types';
 /**
  * A float supported clamp function for a specific value.
  *
- * @param  value The value to clamp.
- * @param  min   The minimum value.
- * @param  max   The maximum value.
+ * @param value The value to clamp.
+ * @param min   The minimum value.
+ * @param max   The maximum value.
  *
  * @return A (float) number
  */
@@ -31,7 +31,7 @@ export function floatClamp( value: number | null, min: number, max: number ) {
 /**
  * Hook to store a clamped value, derived from props.
  *
- * @param  settings
+ * @param settings
  * @return The controlled value and the value setter.
  */
 export function useControlledRangeValue(

package/src/resizable-box/resize-tooltip/utils.ts

@@ -34,12 +34,12 @@ interface UseResizeLabelArgs {
  * Custom hook that manages resize listener events. It also provides a label
  * based on current resize width x height values.
  *
- * @param  props
- * @param  props.axis        Only shows the label corresponding to the axis.
- * @param  props.fadeTimeout Duration (ms) before deactivating the resize label.
- * @param  props.onResize    Callback when a resize occurs. Provides { width, height } callback.
- * @param  props.position    Adjusts label value.
- * @param  props.showPx      Whether to add `PX` to the label.
+ * @param props
+ * @param props.axis        Only shows the label corresponding to the axis.
+ * @param props.fadeTimeout Duration (ms) before deactivating the resize label.
+ * @param props.onResize    Callback when a resize occurs. Provides { width, height } callback.
+ * @param props.position    Adjusts label value.
+ * @param props.showPx      Whether to add `PX` to the label.
  *
  * @return Properties for hook.
  */
@@ -174,14 +174,14 @@ interface GetSizeLabelArgs {
 /**
  * Gets the resize label based on width and height values (as well as recent changes).
  *
- * @param  props
- * @param  props.axis     Only shows the label corresponding to the axis.
- * @param  props.height   Height value.
- * @param  props.moveX    Recent width (x axis) changes.
- * @param  props.moveY    Recent width (y axis) changes.
- * @param  props.position Adjusts label value.
- * @param  props.showPx   Whether to add `PX` to the label.
- * @param  props.width    Width value.
+ * @param props
+ * @param props.axis     Only shows the label corresponding to the axis.
+ * @param props.height   Height value.
+ * @param props.moveX    Recent width (x axis) changes.
+ * @param props.moveY    Recent width (y axis) changes.
+ * @param props.position Adjusts label value.
+ * @param props.showPx   Whether to add `PX` to the label.
+ * @param props.width    Width value.
  *
  * @return The rendered label.
  */

package/src/snackbar/index.tsx

@@ -26,8 +26,8 @@ const NOTICE_TIMEOUT = 10000;
  * Custom hook which announces the message with the given politeness, if a
  * valid message is provided.
  *
- * @param  message    Message to announce.
- * @param  politeness Politeness to announce.
+ * @param message    Message to announce.
+ * @param politeness Politeness to announce.
  */
 function useSpokenMessage(
 	message: SnackbarProps[ 'spokenMessage' ],

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

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -18,6 +23,7 @@ import {
 	arrowRight,
 	chevronDown,
 } from '@wordpress/icons';
+import { SVG, Path } from '@wordpress/primitives';
 
 /**
  * Internal dependencies
@@ -29,9 +35,9 @@ import {
 	ToolbarItem,
 	ToolbarDropdownMenu,
 } from '..';
-import { SVG, Path, DropdownMenu } from '../../';
+import DropdownMenu from '../../dropdown-menu';
 
-export default {
+const meta: ComponentMeta< typeof Toolbar > = {
 	title: 'Components/Toolbar',
 	component: Toolbar,
 	subcomponents: {
@@ -49,6 +55,8 @@ export default {
 	},
 };
 
+export default meta;
+
 function InlineImageIcon() {
 	return (
 		<SVG xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
@@ -57,7 +65,7 @@ function InlineImageIcon() {
 	);
 }
 
-const Template = ( props ) => (
+const Template: ComponentStory< typeof Toolbar > = ( props ) => (
 	<div style={ { height: 280 } }>
 		<Toolbar { ...props } />
 	</div>
@@ -74,29 +82,32 @@ Default.args = {
 			</ToolbarGroup>
 			<ToolbarGroup>
 				<ToolbarItem>
-					{ ( toggleProps ) => (
-						<DropdownMenu
-							hasArrowIndicator
-							icon={ alignLeft }
-							label="Align"
-							controls={ [
-								{
-									icon: alignLeft,
-									title: 'Align left',
-									isActive: true,
-								},
-								{
-									icon: alignCenter,
-									title: 'Align center',
-								},
-								{
-									icon: alignRight,
-									title: 'Align right',
-								},
-							] }
-							toggleProps={ toggleProps }
-						/>
-					) }
+					{
+						// @ts-expect-error TODO: Remove when ToolbarItem/DropdownMenu is typed
+						( toggleProps ) => (
+							<DropdownMenu
+								hasArrowIndicator
+								icon={ alignLeft }
+								label="Align"
+								controls={ [
+									{
+										icon: alignLeft,
+										title: 'Align left',
+										isActive: true,
+									},
+									{
+										icon: alignCenter,
+										title: 'Align center',
+									},
+									{
+										icon: alignRight,
+										title: 'Align right',
+									},
+								] }
+								toggleProps={ toggleProps }
+							/>
+						)
+					}
 				</ToolbarItem>
 			</ToolbarGroup>
 			<ToolbarGroup>
@@ -106,6 +117,7 @@ Default.args = {
 				<ToolbarButton icon={ link } label="Link" />
 				<ToolbarGroup
 					isCollapsed
+					// @ts-expect-error TODO: Remove when ToolbarGroup is typed
 					icon={ false }
 					label="More rich text controls"
 					controls={ [
@@ -119,6 +131,7 @@ Default.args = {
 				/>
 			</ToolbarGroup>
 			<ToolbarGroup
+				// @ts-expect-error TODO: Remove when ToolbarGroup is typed
 				icon={ more }
 				label="Align"
 				isCollapsed

package/src/toolbar/test/{toolbar-group.js → toolbar-group.tsx}

@@ -23,7 +23,7 @@ describe( 'ToolbarGroup', () => {
 		} );
 
 		it( 'should render a list of controls with buttons', () => {
-			const clickHandler = ( event ) => event;
+			const clickHandler = ( event: Event ) => event;
 			const controls = [
 				{
 					icon: 'wordpress',
@@ -41,7 +41,7 @@ describe( 'ToolbarGroup', () => {
 		} );
 
 		it( 'should render a list of controls with buttons and active control', () => {
-			const clickHandler = ( event ) => event;
+			const clickHandler = ( event: Event ) => event;
 			const controls = [
 				{
 					icon: 'wordpress',

package/src/toolbar/toolbar/README.md

@@ -59,11 +59,16 @@ function MyToolbar() {
 
 Toolbar will pass all HTML props to the underlying element. Additionally, you can pass the custom props specified below.
 
-#### label
+#### `className`: `string`
+
+Class to set on the container div.
+
+-   Required: No
+
+#### `label`: `string`
 
 An accessible label for the toolbar.
 
--   Type: `String`
 -   Required: Yes
 
 ## Related components

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

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import classnames from 'classnames';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -14,18 +15,17 @@ import deprecated from '@wordpress/deprecated';
  */
 import ToolbarGroup from '../toolbar-group';
 import ToolbarContainer from './toolbar-container';
+import type { ToolbarProps } from './types';
+import type { WordPressComponentProps } from '../../ui/context';
 
-/**
- * Renders a toolbar.
- *
- * To add controls, simply pass `ToolbarButton` components as children.
- *
- * @param {Object} props             Component props.
- * @param {string} [props.className] Class to set on the container div.
- * @param {string} [props.label]     ARIA label for toolbar container.
- * @param {Object} ref               React Element ref.
- */
-function Toolbar( { className, label, ...props }, ref ) {
+function UnforwardedToolbar(
+	{
+		className,
+		label,
+		...props
+	}: WordPressComponentProps< ToolbarProps, 'div', false >,
+	ref: ForwardedRef< any >
+) {
 	if ( ! label ) {
 		deprecated( 'Using Toolbar without label prop', {
 			since: '5.6',
@@ -49,4 +49,25 @@ function Toolbar( { className, label, ...props }, ref ) {
 	);
 }
 
-export default forwardRef( Toolbar );
+/**
+ * Renders a toolbar.
+ *
+ * To add controls, simply pass `ToolbarButton` components as children.
+ *
+ * ```jsx
+ * import { Toolbar, ToolbarButton } from '@wordpress/components';
+ * import { formatBold, formatItalic, link } from '@wordpress/icons';
+ *
+ * function MyToolbar() {
+ *   return (
+ *     <Toolbar label="Options">
+ *       <ToolbarButton icon={ formatBold } label="Bold" />
+ *       <ToolbarButton icon={ formatItalic } label="Italic" />
+ *       <ToolbarButton icon={ link } label="Link" />
+ *     </Toolbar>
+ *   );
+ * }
+ * ```
+ */
+export const Toolbar = forwardRef( UnforwardedToolbar );
+export default Toolbar;