@wordpress/fields 0.31.1-next.v.202602111440.0 → 0.32.0

package/src/components/media-edit/index.tsx

@@ -14,6 +14,7 @@ import {
 	__experimentalText as Text,
 	__experimentalTruncate as Truncate,
 	__experimentalVStack as VStack,
+	__experimentalHStack as HStack,
 	BaseControl,
 	Tooltip,
 	VisuallyHidden,
@@ -28,7 +29,7 @@ import {
 	useRef,
 	useState,
 } from '@wordpress/element';
-import { __ } from '@wordpress/i18n';
+import { __, sprintf } from '@wordpress/i18n';
 import {
 	archive,
 	audio,
@@ -36,6 +37,10 @@ import {
 	file,
 	closeSmall,
 	error as errorIcon,
+	chevronUp,
+	chevronDown,
+	chevronLeft,
+	chevronRight,
 } from '@wordpress/icons';
 import {
 	MediaUpload,
@@ -49,9 +54,27 @@ import { store as noticesStore } from '@wordpress/notices';
  */
 import { unlock } from '../../lock-unlock';
 import type { MediaEditProps } from '../../types';
+import useMovingAnimation from './use-moving-animation';
 
 const { MediaUploadModal } = unlock( mediaUtilsPrivateApis );
 
+function AnimatedMediaItem( {
+	children,
+	index,
+	className,
+}: {
+	children: React.ReactNode;
+	index: number;
+	className?: string;
+} ) {
+	const ref = useMovingAnimation( index );
+	return (
+		<div ref={ ref } className={ className }>
+			{ children }
+		</div>
+	);
+}
+
 type BlobItem = {
 	id: string;
 	source_url: string;
@@ -59,6 +82,13 @@ type BlobItem = {
 	alt_text?: string;
 };
 
+function normalizeValue( value: number | number[] | undefined ): number[] {
+	if ( Array.isArray( value ) ) {
+		return value;
+	}
+	return value ? [ value ] : [];
+}
+
 /**
  * Conditional Media component that uses MediaUploadModal when experiment is enabled,
  * otherwise falls back to media-utils MediaUpload.
@@ -122,7 +152,9 @@ function MediaPickerButton( {
 	const isBlob = attachment && isBlobURL( attachment.source_url );
 	const mediaPickerButton = (
 		<div
-			className="fields__media-edit-picker-button"
+			className={ clsx( 'fields__media-edit-picker-button', {
+				'has-attachment': attachment,
+			} ) }
 			role="button"
 			tabIndex={ 0 }
 			onClick={ () => {
@@ -160,7 +192,11 @@ function MediaPickerButton( {
 	if ( ! showTooltip ) {
 		return mediaPickerButton;
 	}
-	return <Tooltip text={ label }>{ mediaPickerButton }</Tooltip>;
+	return (
+		<Tooltip text={ label } placement="top">
+			{ mediaPickerButton }
+		</Tooltip>
+	);
 }
 
 const archiveMimeTypes = [
@@ -195,6 +231,54 @@ function MediaEditPlaceholder( props: {
 	);
 }
 
+function MoveButtons( {
+	itemId,
+	index,
+	totalItems,
+	isUploading,
+	moveItem,
+	orientation = 'vertical',
+}: {
+	itemId: number;
+	index: number;
+	totalItems: number;
+	isUploading: boolean;
+	moveItem: ( id: number, direction: 'up' | 'down' ) => void;
+	orientation?: 'vertical' | 'horizontal';
+} ) {
+	const isHorizontal = orientation === 'horizontal';
+	return (
+		<>
+			<Button
+				__next40pxDefaultSize
+				icon={ isHorizontal ? chevronLeft : chevronUp }
+				label={ isHorizontal ? __( 'Move left' ) : __( 'Move up' ) }
+				size="small"
+				disabled={ isUploading || index === 0 }
+				accessibleWhenDisabled
+				tooltipPosition="top"
+				onClick={ ( event: React.MouseEvent< HTMLButtonElement > ) => {
+					event.stopPropagation();
+					moveItem( itemId, 'up' );
+				} }
+			/>
+			<Button
+				__next40pxDefaultSize
+				icon={ isHorizontal ? chevronRight : chevronDown }
+				label={ isHorizontal ? __( 'Move right' ) : __( 'Move down' ) }
+				size="small"
+				disabled={ isUploading || index === totalItems - 1 }
+				accessibleWhenDisabled
+				tooltipPosition="top"
+				onClick={ ( event: React.MouseEvent< HTMLButtonElement > ) => {
+					event.stopPropagation();
+					moveItem( itemId, 'down' );
+				} }
+			/>
+		</>
+	);
+}
+
 function MediaPreview( { attachment }: { attachment: MediaEditAttachment } ) {
 	const url = attachment.source_url;
 	const mimeType = attachment.mime_type || '';
@@ -222,9 +306,11 @@ interface MediaEditAttachmentsProps {
 	addButtonLabel: string;
 	multiple?: boolean;
 	removeItem: ( itemId: number ) => void;
+	moveItem: ( itemId: number, direction: 'up' | 'down' ) => void;
 	open: () => void;
 	onFilesDrop: ( files: File[], attachmentId?: number ) => void;
 	isUploading: boolean;
+	setTargetItemId: ( id?: number ) => void;
 }
 
 function ExpandedMediaEditAttachments( {
@@ -232,9 +318,11 @@ function ExpandedMediaEditAttachments( {
 	addButtonLabel,
 	multiple,
 	removeItem,
+	moveItem,
 	open,
 	onFilesDrop,
 	isUploading,
+	setTargetItemId,
 }: MediaEditAttachmentsProps ) {
 	return (
 		<div
@@ -244,20 +332,35 @@ function ExpandedMediaEditAttachments( {
 				'is-empty': ! allItems?.length,
 			} ) }
 		>
-			{ allItems?.map( ( attachment ) => {
+			{ allItems?.map( ( attachment, index ) => {
 				const hasPreviewImage =
 					attachment.mime_type?.startsWith( 'image' );
 				const isBlob = isBlobURL( attachment.source_url );
+				const attachmentNumericId = attachment.id as number;
 				return (
-					<div
+					<AnimatedMediaItem
 						key={ attachment.id }
+						index={ index }
 						className={ clsx( 'fields__media-edit-expanded-item', {
 							'has-preview-image': hasPreviewImage,
 						} ) }
 					>
 						<MediaPickerButton
-							open={ open }
-							label={ __( 'Replace' ) }
+							open={ () => {
+								setTargetItemId( attachmentNumericId );
+								open();
+							} }
+							label={
+								! isBlob
+									? sprintf(
+											/* translators: %s: The title of the media item. */
+											__( 'Replace %s' ),
+											(
+												attachment as Attachment< 'view' >
+											 ).title.rendered
+									  )
+									: __( 'Replace' )
+							}
 							showTooltip
 							onFilesDrop={ onFilesDrop }
 							attachment={ attachment }
@@ -275,52 +378,54 @@ function ExpandedMediaEditAttachments( {
 											attachment={ attachment }
 										/>
 									) }
-									{ ! isBlob &&
-										( ! hasPreviewImage ? (
-											<MediaTitle
-												attachment={
-													attachment as Attachment< 'view' >
-												}
-											/>
-										) : (
-											<div className="fields__media-edit-expanded-overlay">
-												<div className="fields__media-edit-expanded-title">
-													<MediaTitle
-														attachment={
-															attachment as Attachment< 'view' >
-														}
-													/>
-												</div>
-											</div>
-										) ) }
 								</VStack>
 							</div>
 						</MediaPickerButton>
 						{ ! isBlob && (
 							<div className="fields__media-edit-expanded-overlay">
-								<Button
-									__next40pxDefaultSize
-									className="fields__media-edit-expanded-remove"
-									icon={ closeSmall }
-									label={ __( 'Remove' ) }
-									size="small"
-									disabled={ isUploading }
-									accessibleWhenDisabled
-									onClick={ (
-										event: React.MouseEvent< HTMLButtonElement >
-									) => {
-										event.stopPropagation();
-										removeItem( attachment.id as number );
-									} }
-								/>
+								<HStack
+									className="fields__media-edit-expanded-actions"
+									spacing={ 0 }
+									alignment="flex-end"
+									expanded={ false }
+								>
+									{ multiple && allItems.length > 1 && (
+										<MoveButtons
+											itemId={ attachmentNumericId }
+											index={ index }
+											totalItems={ allItems.length }
+											isUploading={ isUploading }
+											moveItem={ moveItem }
+											orientation="horizontal"
+										/>
+									) }
+									<Button
+										__next40pxDefaultSize
+										icon={ closeSmall }
+										label={ __( 'Remove' ) }
+										size="small"
+										disabled={ isUploading }
+										accessibleWhenDisabled
+										tooltipPosition="top"
+										onClick={ (
+											event: React.MouseEvent< HTMLButtonElement >
+										) => {
+											event.stopPropagation();
+											removeItem( attachmentNumericId );
+										} }
+									/>
+								</HStack>
 							</div>
 						) }
-					</div>
+					</AnimatedMediaItem>
 				);
 			} ) }
 			{ ( multiple || ! allItems?.length ) && (
 				<MediaEditPlaceholder
-					open={ open }
+					open={ () => {
+						setTargetItemId( undefined );
+						open();
+					} }
 					label={ addButtonLabel }
 					onFilesDrop={ onFilesDrop }
 					isUploading={ isUploading }
@@ -335,68 +440,110 @@ function CompactMediaEditAttachments( {
 	addButtonLabel,
 	multiple,
 	removeItem,
+	moveItem,
 	open,
 	onFilesDrop,
 	isUploading,
+	setTargetItemId,
 }: MediaEditAttachmentsProps ) {
 	return (
 		<>
 			{ !! allItems?.length && (
-				<VStack spacing={ 2 }>
-					{ allItems.map( ( attachment ) => {
-						const isBlob = isBlobURL( attachment.source_url );
-						return (
-							<div
-								key={ attachment.id }
-								className="fields__media-edit-compact"
-							>
-								<MediaPickerButton
-									open={ open }
-									label={ __( 'Replace' ) }
-									showTooltip
-									onFilesDrop={ onFilesDrop }
-									attachment={ attachment }
-									isUploading={ isUploading }
+				<div
+					className={ clsx( 'fields__media-edit-compact-group', {
+						'is-single': allItems.length === 1,
+					} ) }
+				>
+					<VStack spacing={ 0 }>
+						{ allItems.map( ( attachment, index ) => {
+							const isBlob = isBlobURL( attachment.source_url );
+							const showMoveButtons =
+								multiple && allItems.length > 1;
+							const attachmentNumericId = attachment.id as number;
+							return (
+								<AnimatedMediaItem
+									key={ attachment.id }
+									index={ index }
+									className="fields__media-edit-compact"
 								>
-									<>
-										<MediaPreview
-											attachment={ attachment }
-										/>
-										{ ! isBlob && (
-											<MediaTitle
-												attachment={
-													attachment as Attachment< 'view' >
-												}
+									<MediaPickerButton
+										open={ () => {
+											setTargetItemId(
+												attachmentNumericId
+											);
+											open();
+										} }
+										label={ __( 'Replace' ) }
+										showTooltip
+										onFilesDrop={ onFilesDrop }
+										attachment={ attachment }
+										isUploading={ isUploading }
+									>
+										<>
+											<MediaPreview
+												attachment={ attachment }
 											/>
-										) }
-									</>
-								</MediaPickerButton>
-								<Button
-									__next40pxDefaultSize
-									className="fields__media-edit-remove"
-									text={ __( 'Remove' ) }
-									variant="secondary"
-									disabled={ isUploading }
-									accessibleWhenDisabled
-									onClick={ (
-										event: React.MouseEvent< HTMLButtonElement >
-									) => {
-										event.stopPropagation();
-										if (
-											typeof attachment.id === 'number'
-										) {
-											removeItem( attachment.id );
-										}
-									} }
-								/>
-							</div>
-						);
-					} ) }
-				</VStack>
+											{ ! isBlob && (
+												<MediaTitle
+													attachment={
+														attachment as Attachment< 'view' >
+													}
+												/>
+											) }
+										</>
+									</MediaPickerButton>
+									{ ! isBlob && (
+										<HStack
+											className="fields__media-edit-compact-movers"
+											spacing={ 0 }
+											alignment="flex-end"
+											expanded={ false }
+										>
+											{ showMoveButtons && (
+												<MoveButtons
+													itemId={
+														attachmentNumericId
+													}
+													index={ index }
+													totalItems={
+														allItems.length
+													}
+													isUploading={ isUploading }
+													moveItem={ moveItem }
+													orientation="vertical"
+												/>
+											) }
+											<Button
+												__next40pxDefaultSize
+												icon={ closeSmall }
+												label={ __( 'Remove' ) }
+												size="small"
+												disabled={ isUploading }
+												accessibleWhenDisabled
+												tooltipPosition="top"
+												onClick={ (
+													event: React.MouseEvent< HTMLButtonElement >
+												) => {
+													event.stopPropagation();
+													removeItem(
+														attachmentNumericId
+													);
+												} }
+											/>
+										</HStack>
+									) }
+								</AnimatedMediaItem>
+							);
+						} ) }
+					</VStack>
+				</div>
 			) }
 			{ ( multiple || ! allItems?.length ) && (
 				<MediaEditPlaceholder
-					open={ open }
+					open={ () => {
+						setTargetItemId( undefined );
+						open();
+					} }
 					label={ addButtonLabel }
 					onFilesDrop={ onFilesDrop }
 					isUploading={ isUploading }
@@ -425,7 +572,7 @@ function CompactMediaEditAttachments( {
  * @param {boolean}              [props.hideLabelFromVision] - Whether the label should be hidden from vision.
  * @param {boolean}              [props.isExpanded]          - Whether to render in an expanded form. Default `false`.
  *
- * @return {JSX.Element} The media edit control component.
+ * @return {React.JSX.Element} The media edit control component.
  *
  * @example
  * ```tsx
@@ -477,18 +624,68 @@ export default function MediaEdit< Item >( {
 			if ( ! value ) {
 				return null;
 			}
-			const normalizedValue = Array.isArray( value ) ? value : [ value ];
+			const normalizedValue = normalizeValue( value );
+			// Sorted IDs ensure stable cache key, avoiding
+			// unnecessary new requests on reorder.
+			const sortedIds = [ ...normalizedValue ].sort( ( a, b ) => a - b );
 			const { getEntityRecords } = select( coreStore );
 			return getEntityRecords( 'postType', 'attachment', {
-				include: normalizedValue,
+				include: sortedIds,
 			} ) as Attachment< 'view' >[] | null;
 		},
 		[ value ]
 	);
+	// Keep previous attachments during null transitions. When value changes,
+	// useSelect briefly returns null while the new query resolves. For pure
+	// reorders (same IDs), we fall back to the cached list to avoid a visual
+	// flash in compact mode. For replacements/uploads (new IDs not in cache),
+	// we let attachments be null as normal.
+	const stableAttachmentsRef = useRef< Attachment< 'view' >[] | null >(
+		null
+	);
+	if ( attachments !== null ) {
+		stableAttachmentsRef.current = attachments;
+	}
+	let stableAttachments = attachments;
+	if ( attachments === null && stableAttachmentsRef.current && value ) {
+		const stableIds = new Set(
+			stableAttachmentsRef.current.map( ( a ) => a.id )
+		);
+		if ( normalizeValue( value ).every( ( id ) => stableIds.has( id ) ) ) {
+			stableAttachments = stableAttachmentsRef.current;
+		}
+	}
+	// Reorder attachments to match value order.
+	const orderedAttachments = useMemo( () => {
+		if ( ! stableAttachments ) {
+			return null;
+		}
+		const normalizedValue = normalizeValue( value );
+		const attachmentMap = new Map(
+			stableAttachments.map( ( a ) => [ a.id, a ] )
+		);
+		return normalizedValue
+			.map( ( id ) => attachmentMap.get( id ) )
+			.filter( ( a ): a is Attachment< 'view' > => a !== undefined );
+	}, [ stableAttachments, value ] );
 	const { createErrorNotice } = useDispatch( noticesStore );
+	const { receiveEntityRecords } = useDispatch( coreStore );
 	// Support one upload action at a time for now.
-	const [ replacementId, setReplacementId ] = useState< number >();
+	const [ targetItemId, setTargetItemId ] = useState< number >();
+	// Deferred open: the legacy class-based MediaUpload reads props
+	// imperatively when `open()` is called, so calling it in the same
+	// handler as `setTargetItemId()` would open the modal with stale
+	// `value`/`multiple` props. Setting a pending flag defers the open
+	// until after the next render when props are up to date.
+	const openModalRef = useRef< () => void >( undefined );
+	const [ pendingOpen, setPendingOpen ] = useState( false );
 	const [ blobs, setBlobs ] = useState< string[] >( [] );
+	useEffect( () => {
+		if ( pendingOpen ) {
+			setPendingOpen( false );
+			openModalRef.current?.();
+		}
+	}, [ pendingOpen ] );
 	const onChangeControl = useCallback(
 		( newValue: number | number[] | undefined ) =>
 			onChange( field.setValue( { item: data, value: newValue } ) ),
@@ -496,7 +693,7 @@ export default function MediaEdit< Item >( {
 	);
 	const removeItem = useCallback(
 		( itemId: number ) => {
-			const currentIds = Array.isArray( value ) ? value : [ value ];
+			const currentIds = normalizeValue( value );
 			const newIds = currentIds.filter( ( id ) => id !== itemId );
 			// Mark as touched to immediately show any validation error.
 			setIsTouched( true );
@@ -504,65 +701,88 @@ export default function MediaEdit< Item >( {
 		},
 		[ value, onChangeControl ]
 	);
+	const moveItem = useCallback(
+		( itemId: number, direction: 'up' | 'down' ) => {
+			if ( ! orderedAttachments ) {
+				return;
+			}
+			const currentIds = orderedAttachments.map( ( a ) => a.id );
+			const index = currentIds.indexOf( itemId );
+			const newIndex = direction === 'up' ? index - 1 : index + 1;
+			[ currentIds[ index ], currentIds[ newIndex ] ] = [
+				currentIds[ newIndex ],
+				currentIds[ index ],
+			];
+			onChangeControl( currentIds );
+		},
+		[ orderedAttachments, onChangeControl ]
+	);
 	const onFilesDrop = useCallback(
-		( files: File[], _replacementId?: number ) => {
+		( files: File[], _targetItemId?: number ) => {
+			setTargetItemId( _targetItemId );
 			uploadMedia( {
 				allowedTypes: allowedTypes?.length ? allowedTypes : undefined,
 				filesList: files,
 				onFileChange( uploadedMedia: any[] ) {
-					setReplacementId( _replacementId );
-					const { blobItems, uploadedItems } = uploadedMedia.reduce(
-						( accumulator, item ) => {
-							if ( isBlobURL( item.url ) ) {
-								accumulator.blobItems.push( item.url );
-							} else {
-								accumulator.uploadedItems.push( item.id );
-							}
-							return accumulator;
-						},
-						{
-							blobItems: [] as string[],
-							uploadedItems: [] as number[],
-						}
-					);
-					setBlobs( blobItems );
-					// If all uploads are complete reset the replacementId.
-					if ( uploadedItems.length === uploadedMedia.length ) {
-						setReplacementId( undefined );
-					}
-					if ( ! uploadedItems.length ) {
+					const blobUrls = uploadedMedia
+						.filter( ( item ) => isBlobURL( item.url ) )
+						.map( ( item ) => item.url );
+					setBlobs( blobUrls );
+					// Wait for all uploads to complete before updating value.
+					if ( !! blobUrls.length ) {
 						return;
 					}
+					// `uploadMedia` creates attachments via `apiFetch`
+					// outside the core-data store, so invalidate
+					// all attachment queries to keep them fresh for
+					// other components that rely on core-data.
+					receiveEntityRecords(
+						'postType',
+						'attachment',
+						[],
+						undefined,
+						true
+					);
+					const uploadedIds = uploadedMedia.map(
+						( item ) => item.id
+					);
 					if ( ! multiple ) {
-						onChangeControl( uploadedItems[ 0 ] );
+						onChangeControl( uploadedIds[ 0 ] );
+						setTargetItemId( undefined );
 						return;
 					}
-					if ( ! value ) {
-						onChangeControl( uploadedItems );
-						return;
+					const currentValue = normalizeValue( value );
+					// Dropped on placeholder: append new items.
+					if ( _targetItemId === undefined ) {
+						onChangeControl( [ ...currentValue, ...uploadedIds ] );
+					} else {
+						// Dropped on existing item: insert at that position.
+						const newValue = [ ...currentValue ];
+						newValue.splice(
+							currentValue.indexOf( _targetItemId ),
+							1,
+							...uploadedIds
+						);
+						onChangeControl( newValue );
 					}
-					const normalizedValue = Array.isArray( value )
-						? value
-						: [ value ];
-					const newIds = [
-						...( _replacementId
-							? normalizedValue.filter(
-									( id: any ) => id !== _replacementId
-							  )
-							: normalizedValue ),
-						...uploadedItems,
-					];
-					onChangeControl( newIds );
+					setTargetItemId( undefined );
 				},
 				onError( error: Error ) {
-					setReplacementId( undefined );
+					setTargetItemId( undefined );
 					setBlobs( [] );
 					createErrorNotice( error.message, { type: 'snackbar' } );
 				},
 				multiple: !! multiple,
 			} );
 		},
-		[ allowedTypes, value, multiple, createErrorNotice, onChangeControl ]
+		[
+			allowedTypes,
+			value,
+			multiple,
+			createErrorNotice,
+			onChangeControl,
+			receiveEntityRecords,
+		]
 	);
 	const addButtonLabel =
 		field.placeholder ||
@@ -570,31 +790,27 @@ export default function MediaEdit< Item >( {
 	// Merge real attachments with any existing blob items that are being uploaded.
 	const allItems: Array< MediaEditAttachment > | null = useMemo( () => {
 		if ( ! blobs.length ) {
-			return attachments;
+			return orderedAttachments;
 		}
 		const items: Array< MediaEditAttachment > = [
-			...( attachments || [] ),
+			...( orderedAttachments || [] ),
 		];
 		const blobItems = blobs.map( ( url ) => ( {
 			id: url,
 			source_url: url,
 			mime_type: getBlobTypeByURL( url ),
 		} ) );
-		const replacementIndex = items.findIndex(
-			( a ) => a.id === replacementId
-		);
-		// Place blobs at the replacement index, when files
-		// dropped in existing media item.
-		if ( replacementIndex !== -1 ) {
-			return [
-				...items.slice( 0, replacementIndex ),
-				...blobItems,
-				...items.slice( replacementIndex + 1 ),
-			];
+		if ( targetItemId !== undefined ) {
+			// When files are dropped in existing media item, place the blobs at that item.
+			const targetIndex = items.findIndex(
+				( a ) => a.id === targetItemId
+			);
+			items.splice( targetIndex, 1, ...blobItems );
+		} else {
+			items.push( ...blobItems );
 		}
-		items.push( ...blobItems );
 		return items;
-	}, [ attachments, replacementId, blobs ] );
+	}, [ orderedAttachments, targetItemId, blobs ] );
 	useEffect( () => {
 		if ( ! isTouched ) {
 			return;
@@ -614,7 +830,7 @@ export default function MediaEdit< Item >( {
 					customValidityResult.message || __( 'Invalid' )
 				);
 			} else {
-				input.setCustomValidity( '' ); // Clear validity
+				input.setCustomValidity( '' ); // Clear validity.
 			}
 		} else {
 			// Clear any previous validation.
@@ -641,20 +857,56 @@ export default function MediaEdit< Item >( {
 			<fieldset className="fields__media-edit" data-field-id={ field.id }>
 				<ConditionalMediaUpload
 					onSelect={ ( selectedMedia: any ) => {
-						if ( multiple ) {
-							const newIds = Array.isArray( selectedMedia )
-								? selectedMedia.map( ( m: any ) => m.id )
-								: [ selectedMedia.id ];
-							onChangeControl( newIds );
-						} else {
+						if ( ! multiple ) {
 							onChangeControl( selectedMedia.id );
+							setTargetItemId( undefined );
+							return;
+						}
+						const newIds = Array.isArray( selectedMedia )
+							? selectedMedia.map( ( m: any ) => m.id )
+							: [ selectedMedia.id ];
+						const currentValue = normalizeValue( value );
+						if ( ! currentValue.length ) {
+							onChangeControl( newIds );
+						} else if ( targetItemId === undefined ) {
+							// Placeholder clicked: keep existing items that are
+							// still selected, then append newly selected items.
+							const existingItems = currentValue.filter( ( id ) =>
+								newIds.includes( id )
+							);
+							const newItems = newIds.filter(
+								( id ) => ! currentValue.includes( id )
+							);
+							onChangeControl( [
+								...existingItems,
+								...newItems,
+							] );
+						} else if ( selectedMedia.id !== targetItemId ) {
+							// Remove selected item from its old position, if it
+							// already exists in the value.
+							const filtered = currentValue.filter(
+								( id ) => id !== selectedMedia.id
+							);
+							// Replace the clicked item with the selected one.
+							onChangeControl(
+								filtered.map( ( id ) =>
+									id === targetItemId ? selectedMedia.id : id
+								)
+							);
 						}
+						setTargetItemId( undefined );
 					} }
+					onClose={ () => setTargetItemId( undefined ) }
 					allowedTypes={ allowedTypes }
-					value={ value }
-					multiple={ multiple }
+					// When replacing an existing item, pass only that item's ID
+					// and open in single-select mode so the user picks exactly
+					// one replacement, even if `multiple` is true.
+					value={ targetItemId !== undefined ? targetItemId : value }
+					multiple={ multiple && targetItemId === undefined }
 					title={ field.label }
 					render={ ( { open }: any ) => {
+						// Keep a ref to the latest `open` so the deferred effect can call it.
+						openModalRef.current = open;
 						const AttachmentsComponent = isExpanded
 							? ExpandedMediaEditAttachments
 							: CompactMediaEditAttachments;
@@ -666,7 +918,10 @@ export default function MediaEdit< Item >( {
 											{ field.label }
 										</VisuallyHidden>
 									) : (
-										<BaseControl.VisualLabel as="legend">
+										<BaseControl.VisualLabel
+											as="legend"
+											style={ { marginBottom: 0 } }
+										>
 											{ field.label }
 										</BaseControl.VisualLabel>
 									) ) }
@@ -675,9 +930,11 @@ export default function MediaEdit< Item >( {
 									addButtonLabel={ addButtonLabel }
 									multiple={ multiple }
 									removeItem={ removeItem }
-									open={ open }
+									moveItem={ moveItem }
+									open={ () => setPendingOpen( true ) }
 									onFilesDrop={ onFilesDrop }
 									isUploading={ !! blobs.length }
+									setTargetItemId={ setTargetItemId }
 								/>
 								{ field.description && (
 									<Text variant="muted">