@wordpress/components 19.11.0 → 19.14.0

package/src/placeholder/index.js

@@ -7,24 +7,38 @@ import classnames from 'classnames';
  * WordPress dependencies
  */
 import { useResizeObserver } from '@wordpress/compose';
+import { SVG, Path } from '@wordpress/primitives';
 
 /**
  * Internal dependencies
  */
 import Icon from '../icon';
 
+const PlaceholderIllustration = (
+	<SVG
+		className="components-placeholder__illustration"
+		fill="none"
+		xmlns="http://www.w3.org/2000/svg"
+		viewBox="0 0 60 60"
+		preserveAspectRatio="none"
+	>
+		<Path vectorEffect="non-scaling-stroke" d="M60 60 0 0" />
+	</SVG>
+);
+
 /**
  * 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 {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.
  *
  * @return {Object} The rendered placeholder.
  */
@@ -37,6 +51,7 @@ function Placeholder( {
 	notices,
 	preview,
 	isColumnLayout,
+	withIllustration,
 	...additionalProps
 } ) {
 	const [ resizeListener, { width } ] = useResizeObserver();
@@ -55,13 +70,15 @@ function Placeholder( {
 	const classes = classnames(
 		'components-placeholder',
 		className,
-		modifierClassNames
+		modifierClassNames,
+		withIllustration ? 'has-illustration' : null
 	);
 	const fieldsetClasses = classnames( 'components-placeholder__fieldset', {
 		'is-column-layout': isColumnLayout,
 	} );
 	return (
 		<div { ...additionalProps } className={ classes }>
+			{ withIllustration ? PlaceholderIllustration : null }
 			{ resizeListener }
 			{ notices }
 			{ preview && (

package/src/placeholder/style.scss

@@ -30,6 +30,13 @@
 	.components-base-control__label {
 		font-size: $default-font-size;
 	}
+
+	&.has-illustration {
+		background: none;
+		border: none;
+		box-shadow: none;
+		min-width: 100px;
+	}
 }
 
 .components-placeholder__error,
@@ -171,3 +178,19 @@
 		}
 	}
 }
+
+// Style the placeholder illustration.
+.components-placeholder__illustration {
+	border: $border-width dashed currentColor;
+	box-sizing: border-box;
+	position: absolute;
+	top: 0;
+	right: 0;
+	bottom: 0;
+	left: 0;
+	width: 100%;
+	height: 100%;
+	stroke: currentColor;
+	stroke-dasharray: 3;
+	opacity: 0.4;
+}

package/src/popover/index.js

@@ -115,6 +115,7 @@ const Popover = (
 		__unstableSlotName = SLOT_NAME,
 		__unstableObserveElement,
 		__unstableForcePosition,
+		__unstableShift = false,
 		...contentProps
 	},
 	ref
@@ -134,26 +135,29 @@ const Popover = (
 		? positionToPlacement( position )
 		: placement;
 
-	/**
-	 * Offsets the the position of the popover when the anchor is inside an iframe.
-	 */
-	const frameOffset = useMemo( () => {
-		let ownerDocument = document;
+	const ownerDocument = useMemo( () => {
 		if ( anchorRef?.top ) {
-			ownerDocument = anchorRef?.top.ownerDocument;
+			return anchorRef?.top.ownerDocument;
 		} else if ( anchorRef?.startContainer ) {
-			ownerDocument = anchorRef.startContainer.ownerDocument;
+			return anchorRef.startContainer.ownerDocument;
 		} else if ( anchorRef?.current ) {
-			ownerDocument = anchorRef.current.ownerDocument;
+			return anchorRef.current.ownerDocument;
 		} else if ( anchorRef ) {
 			// This one should be deprecated.
-			ownerDocument = anchorRef.ownerDocument;
+			return anchorRef.ownerDocument;
 		} else if ( anchorRect && anchorRect?.ownerDocument ) {
-			ownerDocument = anchorRect.ownerDocument;
+			return anchorRect.ownerDocument;
 		} else if ( getAnchorRect ) {
-			ownerDocument = getAnchorRect()?.ownerDocument ?? document;
+			return getAnchorRect()?.ownerDocument ?? document;
 		}
 
+		return document;
+	}, [ anchorRef, anchorRect, getAnchorRect ] );
+
+	/**
+	 * Offsets the the position of the popover when the anchor is inside an iframe.
+	 */
+	const frameOffset = useMemo( () => {
 		const { defaultView } = ownerDocument;
 		const { frameElement } = defaultView;
 
@@ -171,7 +175,7 @@ const Popover = (
 				};
 			},
 		};
-	}, [ anchorRef, anchorRect, getAnchorRect ] );
+	}, [ ownerDocument ] );
 
 	const middlewares = [
 		frameOffset,
@@ -180,21 +184,23 @@ const Popover = (
 		__unstableForcePosition
 			? undefined
 			: size( {
-					apply( { width, height } ) {
+					apply( sizeProps ) {
+						const { height } = sizeProps;
 						if ( ! refs.floating.current ) return;
-
+						// Reduce the height of the popover to the available space.
 						Object.assign( refs.floating.current.firstChild.style, {
-							maxWidth: `${ width }px`,
 							maxHeight: `${ height }px`,
 							overflow: 'auto',
 						} );
 					},
 			  } ),
-		,
-		shift( {
-			crossAxis: true,
-			limiter: limitShift(),
-		} ),
+		__unstableShift
+			? shift( {
+					crossAxis: true,
+					limiter: limitShift(),
+					padding: 1, // Necessary to avoid flickering at the edge of the viewport.
+			  } )
+			: undefined,
 		hasArrow ? arrow( { element: arrowRef } ) : undefined,
 	].filter( ( m ) => !! m );
 	const anchorRefFallback = useRef( null );
@@ -270,13 +276,12 @@ const Popover = (
 			usedRef = {
 				getBoundingClientRect() {
 					const rect = getAnchorRect();
-					return {
-						...rect,
-						x: rect.x ?? rect.left,
-						y: rect.y ?? rect.top,
-						height: rect.height ?? rect.bottom - rect.top,
-						width: rect.width ?? rect.right - rect.left,
-					};
+					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 ( anchorRefFallback.current ) {
@@ -309,6 +314,16 @@ const Popover = (
 		};
 	}, [ __unstableObserveElement ] );
 
+	// If we're using getAnchorRect, we need to update the position as we scroll the iframe.
+	useLayoutEffect( () => {
+		if ( ownerDocument === document ) {
+			return;
+		}
+
+		ownerDocument.addEventListener( 'scroll', update );
+		return () => ownerDocument.removeEventListener( 'scroll', update );
+	}, [ ownerDocument ] );
+
 	/** @type {false | string} */
 	const animateClassName =
 		!! animate &&

package/src/query-controls/README.md

@@ -179,7 +179,7 @@ A function that receives the new author value. If this is not specified, the aut
 
 #### onCategoryChange
 
-A function that receives the new author value. If this is not specified, the category controls are not included.
+A function that receives the new category value. If this is not specified, the category controls are not included.
 
 -   Type: `Function`
 -   Required: No

package/src/radio-control/README.md

@@ -75,57 +75,51 @@ const MyRadioControl = () => {
 			onChange={ ( value ) => setOption( value ) }
 		/>
 	);
-}
+};
 ```
 
 ### Props
 
 The component accepts the following props:
 
-### hideLabelFromVision
+#### `help`: `string | WPElement`
 
-If true, the label will only be visible to screen readers.
+If this property is added, a help text will be generated using help property as the content.
 
--   Type: `Boolean`
 -   Required: No
 
-#### label
+#### `hideLabelFromVision`: `boolean`
 
-If this property is added, a label will be generated using label property as the content.
+If true, the label will only be visible to screen readers.
 
--   Type: `String`
 -   Required: No
 
-#### help
+#### `label`: `string`
 
-If this property is added, a help text will be generated using help property as the content.
+If this property is added, a label will be generated using label property as the content.
 
--   Type: `String|WPElement`
 -   Required: No
 
-#### selected
+#### `onChange`: `( value: string ) => void`
 
-The value property of the currently selected option.
+A function that receives the value of the new option that is being selected as input.
 
--   Type: `Object`
--   Required: No
+-   Required: Yes
 
-#### options
+#### `options`: `{ label: string, value: string }[]`
 
-An array of objects containing the following properties:
+An array of objects containing the value and label of the options.
 
--   `label`: (string) The label to be shown to the user.
--   `value`: (Object) The internal value compared against select and passed to onChange.
+-   `label`: `string` The label to be shown to the user.
+-   `value`: `string` The internal value compared against select and passed to onChange.
 
-*   Type: `Array`
 *   Required: No
 
-#### onChange
+#### `selected`: `string`
 
-A function that receives the value of the new option that is being selected as input.
+The value property of the currently selected option.
 
--   Type: `function`
--   Required: Yes
+-   Required: No
 
 ## Related components
 

package/src/radio-control/index.tsx

@@ -0,0 +1,107 @@
+/**
+ * External dependencies
+ */
+import { isEmpty } from 'lodash';
+import classnames from 'classnames';
+import type { ChangeEvent } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '../base-control';
+import type { WordPressComponentProps } from '../ui/context';
+import type { RadioControlProps } from './types';
+
+/**
+ * Render a user interface to select the user type using radio inputs.
+ *
+ * ```jsx
+ * import { RadioControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyRadioControl = () => {
+ *   const [ option, setOption ] = useState( 'a' );
+ *
+ *   return (
+ *     <RadioControl
+ *       label="User type"
+ *       help="The type of the current user"
+ *       selected={ option }
+ *       options={ [
+ *         { label: 'Author', value: 'a' },
+ *         { label: 'Editor', value: 'e' },
+ *       ] }
+ *       onChange={ ( value ) => setOption( value ) }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function RadioControl(
+	// ref is omitted until we have `WordPressComponentPropsWithoutRef` or add
+	// ref forwarding to RadioControl.
+	props: Omit<
+		WordPressComponentProps< RadioControlProps, 'input', false >,
+		'ref'
+	>
+) {
+	const {
+		label,
+		className,
+		selected,
+		help,
+		onChange,
+		hideLabelFromVision,
+		options = [],
+		...additionalProps
+	} = props;
+	const instanceId = useInstanceId( RadioControl );
+	const id = `inspector-radio-control-${ instanceId }`;
+	const onChangeValue = ( event: ChangeEvent< HTMLInputElement > ) =>
+		onChange( event.target.value );
+
+	if ( isEmpty( options ) ) {
+		return null;
+	}
+
+	return (
+		<BaseControl
+			label={ label }
+			id={ id }
+			hideLabelFromVision={ hideLabelFromVision }
+			help={ help }
+			className={ classnames( className, 'components-radio-control' ) }
+		>
+			{ options.map( ( option, index ) => (
+				<div
+					key={ `${ id }-${ index }` }
+					className="components-radio-control__option"
+				>
+					<input
+						id={ `${ id }-${ index }` }
+						className="components-radio-control__input"
+						type="radio"
+						name={ id }
+						value={ option.value }
+						onChange={ onChangeValue }
+						checked={ option.value === selected }
+						aria-describedby={
+							!! help ? `${ id }__help` : undefined
+						}
+						{ ...additionalProps }
+					/>
+					<label htmlFor={ `${ id }-${ index }` }>
+						{ option.label }
+					</label>
+				</div>
+			) ) }
+		</BaseControl>
+	);
+}
+
+export default RadioControl;

package/src/radio-control/stories/index.tsx

@@ -0,0 +1,72 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import RadioControl from '..';
+
+const meta: ComponentMeta< typeof RadioControl > = {
+	component: RadioControl,
+	title: 'Components/RadioControl',
+	argTypes: {
+		onChange: {
+			action: 'onChange',
+		},
+		selected: {
+			control: { type: null },
+		},
+		label: {
+			control: { type: 'text' },
+		},
+		help: {
+			control: { type: 'text' },
+		},
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof RadioControl > = ( {
+	onChange,
+	options,
+	...args
+} ) => {
+	const [ value, setValue ] = useState( options?.[ 0 ]?.value );
+
+	return (
+		<RadioControl
+			{ ...args }
+			selected={ value }
+			options={ options }
+			onChange={ ( v ) => {
+				setValue( v );
+				onChange( v );
+			} }
+		/>
+	);
+};
+
+export const Default: ComponentStory< typeof RadioControl > = Template.bind(
+	{}
+);
+Default.args = {
+	label: 'Post visibility',
+	options: [
+		{ label: 'Public', value: 'public' },
+		{ label: 'Private', value: 'private' },
+		{ label: 'Password Protected', value: 'password' },
+	],
+};

package/src/radio-control/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+
+export type RadioControlProps = Pick<
+	BaseControlProps,
+	'label' | 'help' | 'hideLabelFromVision'
+> & {
+	/**
+	 * A function that receives the value of the new option that is being
+	 * selected as input.
+	 */
+	onChange: ( value: string ) => void;
+	/**
+	 * An array of objects containing the value and label of the options.
+	 */
+	options?: {
+		/**
+		 * The label to be shown to the user
+		 */
+		label: string;
+		/**
+		 * The internal value compared against select and passed to onChange
+		 */
+		value: string;
+	}[];
+	/**
+	 * The value property of the currently selected option.
+	 */
+	selected?: string;
+};

package/src/range-control/index.js

@@ -3,7 +3,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { clamp, isFinite, noop } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -20,6 +19,7 @@ import Button from '../button';
 import Icon from '../icon';
 import { COLORS } from '../utils';
 import { floatClamp, useControlledRangeValue } from './utils';
+import { clamp } from '../utils/math';
 import InputRange from './input-range';
 import RangeRail from './rail';
 import SimpleTooltip from './tooltip';
@@ -35,6 +35,8 @@ import {
 	Wrapper,
 } from './styles/range-control-styles';
 
+const noop = () => {};
+
 function RangeControl(
 	{
 		afterIcon,
@@ -121,7 +123,7 @@ function RangeControl(
 
 	const id = useInstanceId( RangeControl, 'inspector-range-control' );
 	const describedBy = !! help ? `${ id }__help` : undefined;
-	const enableTooltip = showTooltipProp !== false && isFinite( value );
+	const enableTooltip = showTooltipProp !== false && Number.isFinite( value );
 
 	const handleOnRangeChange = ( event ) => {
 		const nextValue = parseFloat( event.target.value );

package/src/range-control/input-range.js

@@ -1,9 +1,4 @@
 // @ts-nocheck
-/**
- * External dependencies
- */
-import { noop } from 'lodash';
-
 /**
  * WordPress dependencies
  */
@@ -15,6 +10,8 @@ import { forwardRef } from '@wordpress/element';
 import { InputRange as BaseInputRange } from './styles/range-control-styles';
 import { useDebouncedHoverInteraction } from './utils';
 
+const noop = () => {};
+
 function InputRange(
 	{
 		describedBy,

package/src/range-control/utils.js

@@ -1,8 +1,4 @@
 // @ts-nocheck
-/**
- * External dependencies
- */
-import { clamp, noop } from 'lodash';
 
 /**
  * WordPress dependencies
@@ -13,6 +9,9 @@ import { useCallback, useRef, useEffect, useState } from '@wordpress/element';
  * Internal dependencies
  */
 import { useControlledState } from '../utils/hooks';
+import { clamp } from '../utils/math';
+
+const noop = () => {};
 
 /**
  * A float supported clamp function for a specific value.

package/src/resizable-box/resize-tooltip/index.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { noop } from 'lodash';
 import classnames from 'classnames';
 import type { Ref, ForwardedRef } from 'react';
 
@@ -30,6 +29,8 @@ type ResizeTooltipProps = React.ComponentProps< typeof Root > & {
 	zIndex?: number;
 };
 
+const noop = () => {};
+
 function ResizeTooltip(
 	{
 		axis,

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

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { noop } from 'lodash';
-
 /**
  * WordPress dependencies
  */
@@ -10,6 +5,7 @@ import { useEffect, useRef, useState } from '@wordpress/element';
 import { useResizeObserver } from '@wordpress/compose';
 
 const { clearTimeout, setTimeout } = window;
+const noop = () => {};
 
 export type Axis = 'x' | 'y';
 

package/src/responsive-wrapper/index.js

@@ -15,10 +15,8 @@ function ResponsiveWrapper( {
 	children,
 	isInline = false,
 } ) {
-	const [
-		containerResizeListener,
-		{ width: containerWidth },
-	] = useResizeObserver();
+	const [ containerResizeListener, { width: containerWidth } ] =
+		useResizeObserver();
 	if ( Children.count( children ) !== 1 ) {
 		return null;
 	}

package/src/sandbox/test/index.js

@@ -46,9 +46,8 @@ describe( 'Sandbox', () => {
 
 		const iframe = result.container.querySelector( '.components-sandbox' );
 
-		let sandboxedIframe = iframe.contentWindow.document.body.querySelector(
-			'.mock-iframe'
-		);
+		let sandboxedIframe =
+			iframe.contentWindow.document.body.querySelector( '.mock-iframe' );
 
 		expect( sandboxedIframe.getAttribute( 'src' ) ).toBe(
 			'https://super.embed'
@@ -58,9 +57,8 @@ describe( 'Sandbox', () => {
 			fireEvent.click( result.getByRole( 'button' ) );
 		} );
 
-		sandboxedIframe = iframe.contentWindow.document.body.querySelector(
-			'.mock-iframe'
-		);
+		sandboxedIframe =
+			iframe.contentWindow.document.body.querySelector( '.mock-iframe' );
 
 		expect( sandboxedIframe.getAttribute( 'src' ) ).toBe(
 			'https://another.super.embed'