@wordpress/components 19.14.0 → 19.17.0

package/src/placeholder/stories/index.tsx

@@ -0,0 +1,64 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { starEmpty, starFilled, styles, wordpress } from '@wordpress/icons';
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import Placeholder from '../';
+import TextControl from '../../text-control';
+
+const ICONS = { starEmpty, starFilled, styles, wordpress };
+
+const meta: ComponentMeta< typeof Placeholder > = {
+	component: Placeholder,
+	title: 'Components/Placeholder',
+	argTypes: {
+		children: { control: { type: null } },
+		notices: { control: { type: null } },
+		preview: { control: { type: null } },
+		icon: {
+			control: { type: 'select' },
+			options: Object.keys( ICONS ),
+			mapping: ICONS,
+		},
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Placeholder > = ( args ) => {
+	const [ value, setValue ] = useState( '' );
+
+	return (
+		<Placeholder { ...args }>
+			<div>
+				<TextControl
+					label="Sample Field"
+					placeholder="Enter something here"
+					value={ value }
+					onChange={ setValue }
+				/>
+			</div>
+		</Placeholder>
+	);
+};
+
+export const Default: ComponentStory< typeof Placeholder > = Template.bind(
+	{}
+);
+Default.args = {
+	icon: 'wordpress',
+	label: 'My Placeholder Label',
+	instructions: 'Here are instructions you should follow',
+};

package/src/placeholder/style.scss

@@ -27,10 +27,6 @@
 	box-shadow: inset 0 0 0 $border-width $gray-900;
 	outline: 1px solid transparent; // Shown for Windows 10 High Contrast mode.
 
-	.components-base-control__label {
-		font-size: $default-font-size;
-	}
-
 	&.has-illustration {
 		background: none;
 		border: none;

package/src/placeholder/types.ts

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { IconType } from '../icon';
+
+export type PlaceholderProps< IconProps = unknown > = {
+	/**
+	 * The children elements.
+	 */
+	children?: ReactNode;
+	/**
+	 * Class to set on the container div.
+	 */
+	className?: string;
+	/**
+	 * If provided, renders an icon next to the label.
+	 */
+	icon?: IconType< IconProps >;
+	/**
+	 * Instructions of the placeholder.
+	 */
+	instructions?: string;
+	/**
+	 * Changes placeholder children layout from flex-row to flex-column.
+	 */
+	isColumnLayout?: boolean;
+	/**
+	 * Title of the placeholder.
+	 */
+	label?: string;
+	/**
+	 * A rendered notices list
+	 */
+	notices?: ReactNode;
+	/**
+	 * Preview to be rendered in the placeholder.
+	 */
+	preview?: ReactNode;
+	/**
+	 * Outputs a placeholder illustration.
+	 */
+	withIllustration?: boolean;
+};

package/src/popover/README.md

@@ -61,7 +61,7 @@ Set this prop to `false` to disable focus changing entirely. This should only be
 
 ### placement
 
-The direction in which the popover should open relative to its parent node or anchor node. 
+The direction in which the popover should open relative to its parent node or anchor node.
 
 The available base placements are 'top', 'right', 'bottom', 'left'.
 
@@ -71,6 +71,13 @@ Each of these base placements has an alignment in the form -start and -end. For
 -   Required: No
 -   Default: `"bottom-start"`
 
+### offset
+
+The distance (in pixels) between the anchor and popover.
+
+-   Type: `Number`
+-   Required: No
+
 ### children
 
 The content to be displayed within the popover.
@@ -137,7 +144,7 @@ A callback function which is used to override the anchor value computation algor
 
 If you need the `DOMRect` object i.e., the position of popover to be calculated on every time, the popover re-renders, then use `getAnchorRect`.
 
-`getAnchorRect` callback function receives a reference to the popover anchor element as a function parameter and it should return a `DOMRect` object.
+`getAnchorRect` callback function receives a reference to the popover anchor element as a function parameter and it should return a `DOMRect` object. Noting that `getAnchorRect` can be called with `null`.
 
 -   Type: `Function`
 -   Required: No

package/src/popover/index.js

@@ -32,6 +32,7 @@ import {
 } from '@wordpress/compose';
 import { close } from '@wordpress/icons';
 import deprecated from '@wordpress/deprecated';
+import { Path, SVG } from '@wordpress/primitives';
 
 /**
  * Internal dependencies
@@ -48,6 +49,30 @@ import { getAnimateClassName } from '../animate';
  */
 const SLOT_NAME = 'Popover';
 
+// 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 slotNameContext = createContext();
 
 const positionToPlacement = ( position ) => {
@@ -104,7 +129,7 @@ const Popover = (
 		noArrow = true,
 		isAlternate,
 		position,
-		placement = 'bottom-start',
+		placement: placementProp = 'bottom-start',
 		offset,
 		focusOnMount = 'firstElement',
 		anchorRef,
@@ -114,11 +139,11 @@ const Popover = (
 		onFocusOutside,
 		__unstableSlotName = SLOT_NAME,
 		__unstableObserveElement,
-		__unstableForcePosition,
+		__unstableForcePosition = false,
 		__unstableShift = false,
 		...contentProps
 	},
-	ref
+	forwardedRef
 ) => {
 	if ( range ) {
 		deprecated( 'range prop in Popover component', {
@@ -128,34 +153,40 @@ 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 ownerDocument = useMemo( () => {
+		let documentToReturn;
+
 		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()?.ownerDocument ?? document;
+			documentToReturn = getAnchorRect(
+				anchorRefFallback.current
+			)?.ownerDocument;
 		}
 
-		return document;
+		return documentToReturn ?? document;
 	}, [ anchorRef, anchorRect, getAnchorRect ] );
 
 	/**
-	 * Offsets the the position of the popover when the anchor is inside an iframe.
+	 * Offsets the position of the popover when the anchor is inside an iframe.
 	 */
 	const frameOffset = useMemo( () => {
 		const { defaultView } = ownerDocument;
@@ -166,20 +197,42 @@ const Popover = (
 		}
 
 		const iframeRect = frameElement.getBoundingClientRect();
-		return {
-			name: 'iframeOffset',
-			fn( { x, y } ) {
-				return {
-					x: x + iframeRect.left,
-					y: y + iframeRect.top,
-				};
-			},
-		};
+		return { x: iframeRect.left, y: iframeRect.top };
 	}, [ ownerDocument ] );
 
-	const middlewares = [
-		frameOffset,
-		offset ? offsetMiddleware( offset ) : undefined,
+	const middleware = [
+		frameOffset || offset
+			? offsetMiddleware( ( { placement: currentPlacement } ) => {
+					if ( ! frameOffset ) {
+						return offset;
+					}
+
+					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;
+					const normalizedOffset = offset ? offset : 0;
+
+					return {
+						mainAxis:
+							normalizedOffset +
+							frameOffset[ mainAxis ] * mainAxisModifier,
+						crossAxis: frameOffset[ crossAxis ],
+					};
+			  } )
+			: undefined,
 		__unstableForcePosition ? undefined : flip(),
 		__unstableForcePosition
 			? undefined
@@ -203,19 +256,22 @@ const Popover = (
 			: undefined,
 		hasArrow ? arrow( { element: arrowRef } ) : undefined,
 	].filter( ( m ) => !! m );
-	const anchorRefFallback = useRef( null );
 	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,
@@ -224,33 +280,38 @@ 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 } );
+
+	// 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();
@@ -263,19 +324,24 @@ 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();
+					const rect = getAnchorRect( anchorRefFallback.current );
 					return new window.DOMRect(
 						rect.x ?? rect.left,
 						rect.y ?? rect.top,
@@ -285,23 +351,29 @@ 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 );
+		return autoUpdate(
+			resultingReferenceRef,
+			refs.floating.current,
+			update
+		);
 	}, [ anchorRef, anchorRect, getAnchorRect ] );
 
-	// This is only needed for a smoth transition when moving blocks.
+	// This is only needed for a smooth transition when moving blocks.
 	useLayoutEffect( () => {
 		if ( ! __unstableObserveElement ) {
 			return;
@@ -314,7 +386,9 @@ const Popover = (
 		};
 	}, [ __unstableObserveElement ] );
 
-	// 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.
 	useLayoutEffect( () => {
 		if ( ownerDocument === document ) {
 			return;
@@ -329,9 +403,15 @@ const Popover = (
 		!! animate &&
 		getAnimateClassName( {
 			type: 'appear',
-			origin: placementToAnimationOrigin( placementData ),
+			origin: placementToAnimationOrigin( computedPlacement ),
 		} );
 
+	const mergedFloatingRef = useMergeRefs( [
+		floating,
+		dialogRef,
+		forwardedRef,
+	] );
+
 	// Disable reason: We care to capture the _bubbled_ events from inputs
 	// within popover as inferring close intent.
 
@@ -349,7 +429,7 @@ const Popover = (
 				}
 			) }
 			{ ...contentProps }
-			ref={ mergedRefs }
+			ref={ mergedFloatingRef }
 			{ ...dialogProps }
 			tabIndex="-1"
 			style={
@@ -362,6 +442,7 @@ const Popover = (
 					  }
 			}
 		>
+			{ /* Prevents scroll on the document */ }
 			{ isExpanded && <ScrollLock /> }
 			{ isExpanded && (
 				<div className="components-popover__header">
@@ -378,22 +459,22 @@ 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>
 	);