@wordpress/components 19.12.0 → 19.15.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/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'.
 
@@ -137,7 +137,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

@@ -128,6 +128,7 @@ const Popover = (
 	}
 
 	const arrowRef = useRef( null );
+	const anchorRefFallback = useRef( null );
 	const isMobileViewport = useViewportMatch( 'medium', '<' );
 	const isExpanded = expandOnMobile && isMobileViewport;
 	const hasArrow = ! isExpanded && ! noArrow;
@@ -148,14 +149,17 @@ const Popover = (
 		} else if ( anchorRect && anchorRect?.ownerDocument ) {
 			return anchorRect.ownerDocument;
 		} else if ( getAnchorRect ) {
-			return getAnchorRect()?.ownerDocument ?? document;
+			return (
+				getAnchorRect( anchorRefFallback.current )?.ownerDocument ??
+				document
+			);
 		}
 
 		return 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;
@@ -203,7 +207,6 @@ const Popover = (
 			: undefined,
 		hasArrow ? arrow( { element: arrowRef } ) : undefined,
 	].filter( ( m ) => !! m );
-	const anchorRefFallback = useRef( null );
 	const slotName = useContext( slotNameContext ) || __unstableSlotName;
 	const slot = useSlot( slotName );
 
@@ -275,7 +278,7 @@ const Popover = (
 		} else if ( getAnchorRect ) {
 			usedRef = {
 				getBoundingClientRect() {
-					const rect = getAnchorRect();
+					const rect = getAnchorRect( anchorRefFallback.current );
 					return new window.DOMRect(
 						rect.x ?? rect.left,
 						rect.y ?? rect.top,

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;
+};