@wordpress/components 28.3.0 → 28.5.0

package/src/popover/stories/index.story.tsx

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { StoryFn, Meta } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react';
 
 /**
  * WordPress dependencies
@@ -79,174 +79,176 @@ const PopoverWithAnchor = ( args: PopoverProps ) => {
 	);
 };
 
-const Template: StoryFn< typeof Popover > = ( args ) => {
-	const [ isVisible, setIsVisible ] = useState( false );
-	const toggleVisible = () => {
-		setIsVisible( ( state ) => ! state );
-	};
-	const buttonRef = useRef< HTMLButtonElement | undefined >();
-	useEffect( () => {
-		buttonRef.current?.scrollIntoView?.( {
-			block: 'center',
-			inline: 'center',
-		} );
-	}, [] );
+export const Default: StoryObj< typeof Popover > = {
+	decorators: [
+		( Story ) => {
+			const [ isVisible, setIsVisible ] = useState( false );
+			const toggleVisible = () => {
+				setIsVisible( ( state ) => ! state );
+			};
+			const buttonRef = useRef< HTMLButtonElement | undefined >();
+			useEffect( () => {
+				buttonRef.current?.scrollIntoView?.( {
+					block: 'center',
+					inline: 'center',
+				} );
+			}, [] );
+
+			return (
+				<div
+					style={ {
+						width: '300vw',
+						height: '300vh',
+						display: 'flex',
+						alignItems: 'center',
+						justifyContent: 'center',
+					} }
+				>
+					<Button
+						variant="secondary"
+						onClick={ toggleVisible }
+						ref={ buttonRef }
+					>
+						Toggle Popover
+						{ isVisible && <Story /> }
+					</Button>
+				</div>
+			);
+		},
+	],
+	args: {
+		children: (
+			<div style={ { width: '280px', whiteSpace: 'normal' } }>
+				Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+				eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
+				enim ad minim veniam, quis nostrud exercitation ullamco laboris
+				nisi ut aliquip ex ea commodo consequat.
+			</div>
+		),
+	},
+};
 
-	return (
+export const Unstyled: StoryObj< typeof Popover > = {
+	...Default,
+	args: {
+		...Default.args,
+
+		variant: 'unstyled',
+	},
+};
+
+export const AllPlacements: StoryObj< typeof Popover > = {
+	render: ( { children, ...args } ) => (
 		<div
 			style={ {
-				width: '300vw',
-				height: '300vh',
-				display: 'flex',
-				alignItems: 'center',
-				justifyContent: 'center',
+				minWidth: '600px',
+				marginLeft: 'auto',
+				marginRight: 'auto',
 			} }
 		>
-			<Button
-				variant="secondary"
-				onClick={ toggleVisible }
-				ref={ buttonRef }
-			>
-				Toggle Popover
-				{ isVisible && <Popover { ...args } /> }
-			</Button>
-		</div>
-	);
-};
-
-export const Default: StoryFn< typeof Popover > = Template.bind( {} );
-Default.args = {
-	children: (
-		<div style={ { width: '280px', whiteSpace: 'normal' } }>
-			Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-			eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
-			ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
-			aliquip ex ea commodo consequat.
+			<h2>
+				Resize / scroll the viewport to test the behavior of the
+				popovers when they reach the viewport boundaries.
+			</h2>
+			<div>
+				{ AVAILABLE_PLACEMENTS.map( ( p ) => (
+					<PopoverWithAnchor
+						key={ p }
+						placement={ p }
+						{ ...args }
+						resize={ p === 'overlay' ? true : args.resize }
+					>
+						{ children }
+						<div>
+							<small>(placement: { p })</small>
+						</div>
+					</PopoverWithAnchor>
+				) ) }
+			</div>
 		</div>
 	),
+	// Excluding placement and position since they all possible values
+	// are passed directly in code.
+	parameters: {
+		controls: {
+			exclude: [ 'placement', 'position' ],
+		},
+	},
+	args: {
+		...Default.args,
+		children: (
+			<div style={ { width: '280px', whiteSpace: 'normal' } }>
+				Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+				eiusmod tempor incididunt ut labore et dolore magna aliqua.
+			</div>
+		),
+		noArrow: false,
+		offset: 10,
+		resize: false,
+		flip: false,
+	},
 };
 
-export const Unstyled: StoryFn< typeof Popover > = Template.bind( {} );
-Unstyled.args = {
-	children: (
-		<div style={ { width: '280px', whiteSpace: 'normal' } }>
-			Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-			eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
-			ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
-			aliquip ex ea commodo consequat.
-		</div>
-	),
-	variant: 'unstyled',
-};
+export const DynamicHeight: StoryObj< typeof Popover > = {
+	decorators: [
+		( Story ) => {
+			const [ height, setHeight ] = useState( 200 );
+			const increase = () => setHeight( height + 100 );
+			const decrease = () => setHeight( height - 100 );
 
-export const AllPlacements: StoryFn< typeof Popover > = ( {
-	children,
-	...args
-} ) => (
-	<div
-		style={ {
-			minWidth: '600px',
-			marginLeft: 'auto',
-			marginRight: 'auto',
-		} }
-	>
-		<h2>
-			Resize / scroll the viewport to test the behavior of the popovers
-			when they reach the viewport boundaries.
-		</h2>
-		<div>
-			{ AVAILABLE_PLACEMENTS.map( ( p ) => (
-				<PopoverWithAnchor
-					key={ p }
-					placement={ p }
-					{ ...args }
-					resize={ p === 'overlay' ? true : args.resize }
-				>
-					{ children }
+			return (
+				<div style={ { padding: '20px' } }>
 					<div>
-						<small>(placement: { p })</small>
+						<Button
+							variant="primary"
+							onClick={ increase }
+							style={ {
+								marginRight: '20px',
+							} }
+						>
+							Increase Size
+						</Button>
+
+						<Button variant="primary" onClick={ decrease }>
+							Decrease Size
+						</Button>
 					</div>
-				</PopoverWithAnchor>
-			) ) }
-		</div>
-	</div>
-);
-// Excluding placement and position since they all possible values
-// are passed directly in code.
-AllPlacements.parameters = {
-	controls: {
-		exclude: [ 'placement', 'position' ],
-	},
-};
-AllPlacements.args = {
-	...Default.args,
-	children: (
-		<div style={ { width: '280px', whiteSpace: 'normal' } }>
-			Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
-			eiusmod tempor incididunt ut labore et dolore magna aliqua.
-		</div>
-	),
-	noArrow: false,
-	offset: 10,
-	resize: false,
-	flip: false,
-};
 
-export const DynamicHeight: StoryFn< typeof Popover > = ( {
-	children,
-	...args
-} ) => {
-	const [ height, setHeight ] = useState( 200 );
-	const increase = () => setHeight( height + 100 );
-	const decrease = () => setHeight( height - 100 );
-
-	return (
-		<div style={ { padding: '20px' } }>
-			<div>
-				<Button
-					variant="primary"
-					onClick={ increase }
-					style={ {
-						marginRight: '20px',
-					} }
-				>
-					Increase Size
-				</Button>
-
-				<Button variant="primary" onClick={ decrease }>
-					Decrease Size
-				</Button>
-			</div>
+					<p>
+						When the height of the popover exceeds the available
+						space in the canvas, a scrollbar inside the popover
+						should appear.
+					</p>
 
-			<p>
-				When the height of the popover exceeds the available space in
-				the canvas, a scrollbar inside the popover should appear.
-			</p>
-
-			<div>
-				<Popover { ...args }>
-					<div
-						style={ {
-							height,
-							background: '#eee',
-							padding: '20px',
-						} }
-					>
-						{ children }
+					<div>
+						<style>{ `.components-popover { --dynamic-height: ${ height }px; }` }</style>
+						<Story />
 					</div>
-				</Popover>
+				</div>
+			);
+		},
+	],
+	args: {
+		...Default.args,
+		children: (
+			<div
+				style={ {
+					height: 'var(--dynamic-height)',
+					background: '#eee',
+					padding: '20px',
+				} }
+			>
+				Content with dynamic height
 			</div>
-		</div>
-	);
-};
-DynamicHeight.args = {
-	...Default.args,
-	children: 'Content with dynamic height',
+		),
+	},
 };
 
-export const WithSlotOutsideIframe: StoryFn< typeof Popover > = ( args ) => {
-	return <PopoverInsideIframeRenderedInExternalSlot { ...args } />;
-};
-WithSlotOutsideIframe.args = {
-	...Default.args,
+export const WithSlotOutsideIframe: StoryObj< typeof Popover > = {
+	render: ( args ) => (
+		<PopoverInsideIframeRenderedInExternalSlot { ...args } />
+	),
+	args: {
+		...Default.args,
+	},
 };

package/src/private-apis.ts

@@ -8,8 +8,6 @@ import {
 	CompositeRow as CompositeRowV2,
 	useCompositeStore as useCompositeStoreV2,
 } from './composite/v2';
-import { default as CustomSelectControl } from './custom-select-control';
-import { default as CustomSelectControlV2Legacy } from './custom-select-control-v2/legacy-component';
 import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
 import { createPrivateSlotFill } from './slot-fill';
 import {
@@ -35,8 +33,6 @@ lock( privateApis, {
 	CompositeItemV2,
 	CompositeRowV2,
 	useCompositeStoreV2,
-	CustomSelectControlV2Legacy,
-	CustomSelectControl,
 	__experimentalPopoverLegacyPositionToPlacement,
 	createPrivateSlotFill,
 	ComponentsContext,

package/src/query-controls/index.tsx

@@ -85,7 +85,11 @@ export function QueryControls( {
 						__next40pxDefaultSize={ __next40pxDefaultSize }
 						key="query-controls-order-select"
 						label={ __( 'Order by' ) }
-						value={ `${ orderBy }/${ order }` }
+						value={
+							orderBy === undefined || order === undefined
+								? undefined
+								: `${ orderBy }/${ order }`
+						}
 						options={ [
 							{
 								label: __( 'Newest to oldest' ),

package/src/radio-control/index.tsx

@@ -16,6 +16,16 @@ import BaseControl from '../base-control';
 import type { WordPressComponentProps } from '../context';
 import type { RadioControlProps } from './types';
 import { VStack } from '../v-stack';
+import { useBaseControlProps } from '../base-control/hooks';
+import { StyledHelp } from '../base-control/styles/base-control-styles';
+
+function generateOptionDescriptionId( radioGroupId: string, index: number ) {
+	return `${ radioGroupId }-${ index }-option-description`;
+}
+
+function generateOptionId( radioGroupId: string, index: number ) {
+	return `${ radioGroupId }-${ index }`;
+}
 
 /**
  * Render a user interface to select the user type using radio inputs.
@@ -53,13 +63,23 @@ export function RadioControl(
 		onChange,
 		hideLabelFromVision,
 		options = [],
+		id: preferredId,
 		...additionalProps
 	} = props;
-	const instanceId = useInstanceId( RadioControl );
-	const id = `inspector-radio-control-${ instanceId }`;
+	const id = useInstanceId(
+		RadioControl,
+		'inspector-radio-control',
+		preferredId
+	);
+
 	const onChangeValue = ( event: ChangeEvent< HTMLInputElement > ) =>
 		onChange( event.target.value );
 
+	// Use `useBaseControlProps` to get the id of the help text.
+	const {
+		controlProps: { 'aria-describedby': helpTextId },
+	} = useBaseControlProps( { id, help } );
+
 	if ( ! options?.length ) {
 		return null;
 	}
@@ -73,14 +93,19 @@ export function RadioControl(
 			help={ help }
 			className={ clsx( className, 'components-radio-control' ) }
 		>
-			<VStack spacing={ 3 }>
+			<VStack
+				spacing={ 3 }
+				className={ clsx( 'components-radio-control__group-wrapper', {
+					'has-help': !! help,
+				} ) }
+			>
 				{ options.map( ( option, index ) => (
 					<div
-						key={ `${ id }-${ index }` }
+						key={ generateOptionId( id, index ) }
 						className="components-radio-control__option"
 					>
 						<input
-							id={ `${ id }-${ index }` }
+							id={ generateOptionId( id, index ) }
 							className="components-radio-control__input"
 							type="radio"
 							name={ id }
@@ -88,16 +113,32 @@ export function RadioControl(
 							onChange={ onChangeValue }
 							checked={ option.value === selected }
 							aria-describedby={
-								!! help ? `${ id }__help` : undefined
+								clsx( [
+									!! option.description &&
+										generateOptionDescriptionId(
+											id,
+											index
+										),
+									helpTextId,
+								] ) || undefined
 							}
 							{ ...additionalProps }
 						/>
 						<label
 							className="components-radio-control__label"
-							htmlFor={ `${ id }-${ index }` }
+							htmlFor={ generateOptionId( id, index ) }
 						>
 							{ option.label }
 						</label>
+						{ !! option.description ? (
+							<StyledHelp
+								__nextHasNoMarginBottom
+								id={ generateOptionDescriptionId( id, index ) }
+								className="components-radio-control__option-description"
+							>
+								{ option.description }
+							</StyledHelp>
+						) : null }
 					</div>
 				) ) }
 			</VStack>

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

@@ -68,3 +68,26 @@ Default.args = {
 		{ label: 'Password Protected', value: 'password' },
 	],
 };
+
+export const WithOptionDescriptions: StoryFn< typeof RadioControl > =
+	Template.bind( {} );
+WithOptionDescriptions.args = {
+	...Default.args,
+	options: [
+		{
+			label: 'Public',
+			value: 'public',
+			description: 'Visible to everyone',
+		},
+		{
+			label: 'Private',
+			value: 'private',
+			description: 'Only visible to you',
+		},
+		{
+			label: 'Password Protected',
+			value: 'password',
+			description: 'Protected by a password',
+		},
+	],
+};

package/src/radio-control/style.scss

@@ -1,19 +1,29 @@
+.components-radio-control__group-wrapper.has-help {
+	margin-block-end: $grid-unit-15;
+}
+
 .components-radio-control__option {
-	display: flex;
+	display: grid;
+	grid-template-columns: auto 1fr;
+	grid-template-rows: auto minmax(0, max-content);
+	column-gap: $grid-unit-10;
 	align-items: center;
 }
 
 .components-radio-control__input[type="radio"] {
+	grid-column: 1;
+	grid-row: 1;
+
 	@include radio-control;
 
 	display: inline-flex;
-	margin: 0 $grid-unit-10 0 0;
+	margin: 0;
 	padding: 0;
 	appearance: none;
 	cursor: pointer;
 
 	&:focus {
-		box-shadow: 0 0 0 ($border-width * 2) $components-color-background, 0 0 0 ($border-width * 2 + $border-width-focus-fallback) $components-color-accent;
+		@include button-style-outset__focus(var(--wp-admin-theme-color));
 	}
 
 	&:checked {
@@ -28,5 +38,24 @@
 }
 
 .components-radio-control__label {
+	grid-column: 2;
+	grid-row: 1;
+
 	cursor: pointer;
+	line-height: $radio-input-size-sm;
+
+	@include break-small() {
+		line-height: $radio-input-size;
+	}
+}
+
+.components-radio-control__option-description {
+	grid-column: 2;
+	grid-row: 2;
+
+	padding-block-start: $grid-unit-05;
+
+	// Override the top margin of the StyledHelp component from BaseControl.
+	// TODO: we should tweak the StyledHelp component to not have a top margin.
+	margin-top: 0;
 }