@wordpress/components 19.16.0 → 19.17.0

package/src/placeholder/README.md

@@ -9,12 +9,52 @@ import { more } from '@wordpress/icons';
 const MyPlaceholder = () => <Placeholder icon={ more } label="Placeholder" />;
 ```
 
-### Props
-
-| Name              | Type                | Default     | Description                                                       |
-| ----------------  | ------------------- | ----------- | ----------------------------------------------------------------- |
-| `icon`            | `string, WPElement` | `undefined` | If provided, renders an icon next to the label.                   |
-| `label`           | `string`            | `undefined` | Renders a label for the placeholder.                              |
-| `instructions`    | `string`            | `undefined` | Renders instruction text below label.                             |
-| `isColumnLayout`  | `bool`              | `false`     | Changes placeholder children layout from flex-row to flex-column. |
-| `withIllustration`| `bool`              | `false`     | Outputs a placeholder illustration.                             |
+## Props
+
+### `className`: `string`
+
+Class to set on the container div.
+
+-   Required: No
+
+### `icon`: `string|Function|WPComponent|null`
+
+If provided, renders an icon next to the label.
+
+-   Required: No
+
+### `instructions`: `string`
+
+Instructions of the placeholder.
+
+-   Required: No
+
+### `isColumnLayout`: `boolean`
+
+Changes placeholder children layout from flex-row to flex-column.
+
+-   Required: No
+
+### `label`: `string`
+
+Title of the placeholder.
+
+-   Required: Yes
+
+### `notices`: `ReactNode`
+
+A rendered notices list
+
+-   Required: No
+
+### `preview`: `ReactNode`
+
+Preview to be rendered in the placeholder.
+
+-   Required: No
+
+### `withIllustration`: `boolean`
+
+Outputs a placeholder illustration.
+
+-   Required: No

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

@@ -13,6 +13,8 @@ import { SVG, Path } from '@wordpress/primitives';
  * Internal dependencies
  */
 import Icon from '../icon';
+import type { PlaceholderProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
 const PlaceholderIllustration = (
 	<SVG
@@ -29,31 +31,33 @@ const PlaceholderIllustration = (
 /**
  * Renders a placeholder. Normally used by blocks to render their empty state.
  *
- * @param {Object}    props                  The component props.
- * @param {WPIcon}    props.icon             An icon rendered before the label.
- * @param {WPElement} props.children         Children to be rendered.
- * @param {string}    props.label            Title of the placeholder.
- * @param {string}    props.instructions     Instructions of the placeholder.
- * @param {string}    props.className        Class to set on the container div.
- * @param {Object}    props.notices          A rendered notices list.
- * @param {Object}    props.preview          Preview to be rendered in the placeholder.
- * @param {boolean}   props.isColumnLayout   Whether a column layout should be used.
- * @param {boolean}   props.withIllustration Whether to add an illustration to the placeholder.
+ * ```jsx
+ * import { Placeholder } from '@wordpress/components';
+ * import { more } from '@wordpress/icons';
  *
- * @return {Object} The rendered placeholder.
+ * const MyPlaceholder = () => <Placeholder icon={ more } label="Placeholder" />;
+ * ```
  */
-function Placeholder( {
-	icon,
-	children,
-	label,
-	instructions,
-	className,
-	notices,
-	preview,
-	isColumnLayout,
-	withIllustration,
-	...additionalProps
-} ) {
+export function Placeholder< IconProps = unknown >(
+	// ref is omitted until we have `WordPressComponentPropsWithoutRef` or add
+	// ref forwarding to Placeholder.
+	props: Omit<
+		WordPressComponentProps< PlaceholderProps< IconProps >, 'div', false >,
+		'ref'
+	>
+) {
+	const {
+		icon,
+		children,
+		label,
+		instructions,
+		className,
+		notices,
+		preview,
+		isColumnLayout,
+		withIllustration,
+		...additionalProps
+	} = props;
 	const [ resizeListener, { width } ] = useResizeObserver();
 
 	// Since `useResizeObserver` will report a width of `null` until after the

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

@@ -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.

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', {
@@ -129,33 +154,35 @@ 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( anchorRefFallback.current )?.ownerDocument ??
-				document
-			);
+			documentToReturn = getAnchorRect(
+				anchorRefFallback.current
+			)?.ownerDocument;
 		}
 
-		return document;
+		return documentToReturn ?? document;
 	}, [ anchorRef, anchorRect, getAnchorRect ] );
 
 	/**
@@ -170,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
@@ -231,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();
@@ -270,17 +324,22 @@ 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( anchorRefFallback.current );
 					return new window.DOMRect(
@@ -292,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;
@@ -321,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;
@@ -336,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.
 
@@ -356,7 +429,7 @@ const Popover = (
 				}
 			) }
 			{ ...contentProps }
-			ref={ mergedRefs }
+			ref={ mergedFloatingRef }
 			{ ...dialogProps }
 			tabIndex="-1"
 			style={
@@ -369,6 +442,7 @@ const Popover = (
 					  }
 			}
 		>
+			{ /* Prevents scroll on the document */ }
 			{ isExpanded && <ScrollLock /> }
 			{ isExpanded && (
 				<div className="components-popover__header">
@@ -385,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>
 	);