@wordpress/media-utils 5.33.1 → 5.34.0

package/build-types/components/media-upload-modal/index.d.ts

@@ -0,0 +1,89 @@
+import type { Attachment } from '../../utils/types';
+interface MediaUploadModalProps {
+    /**
+     * Array of allowed media types.
+     * @default ['image']
+     */
+    allowedTypes?: string[];
+    /**
+     * Whether multiple files can be selected.
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * The currently selected media item(s).
+     * Can be a single ID number or array of IDs for multiple selection.
+     */
+    value?: number | number[];
+    /**
+     * Function called when media is selected.
+     * Receives single attachment object or array of attachments.
+     */
+    onSelect: (media: Attachment | Attachment[]) => void;
+    /**
+     * Function called when the modal is closed without selection.
+     */
+    onClose?: () => void;
+    /**
+     * Function to handle media uploads.
+     * If not provided, drag and drop will be disabled.
+     */
+    onUpload?: (args: {
+        allowedTypes?: string[];
+        filesList: File[];
+        onFileChange?: (attachments: Partial<Attachment>[]) => void;
+        onError?: (error: Error) => void;
+        multiple?: boolean;
+    }) => void;
+    /**
+     * Title for the modal.
+     * @default 'Select Media'
+     */
+    title?: string;
+    /**
+     * Whether the modal is open.
+     */
+    isOpen: boolean;
+    /**
+     * Whether the modal can be closed by clicking outside or pressing escape.
+     * @default true
+     */
+    isDismissible?: boolean;
+    /**
+     * Additional CSS class for the modal.
+     */
+    modalClass?: string;
+    /**
+     * Whether to show a search input.
+     * @default true
+     */
+    search?: boolean;
+    /**
+     * Label for the search input.
+     */
+    searchLabel?: string;
+}
+/**
+ * MediaUploadModal component that uses Modal and DataViewsPicker for media selection.
+ *
+ * This is a modern functional component alternative to the legacy MediaUpload class component.
+ * It provides a cleaner API and better integration with the WordPress block editor.
+ *
+ * @param props               Component props
+ * @param props.allowedTypes  Array of allowed media types
+ * @param props.multiple      Whether multiple files can be selected
+ * @param props.value         Currently selected media item(s)
+ * @param props.onSelect      Function called when media is selected
+ * @param props.onClose       Function called when modal is closed
+ * @param props.onUpload      Function to handle media uploads
+ * @param props.title         Title for the modal
+ * @param props.isOpen        Whether the modal is open
+ * @param props.isDismissible Whether modal can be dismissed
+ * @param props.modalClass    Additional CSS class for modal
+ * @param props.search        Whether to show search input
+ * @param props.searchLabel   Label for search input
+ * @return JSX element or null
+ */
+export declare function MediaUploadModal({ allowedTypes, multiple, value, onSelect, onClose, onUpload, title, isOpen, isDismissible, modalClass, search, searchLabel, }: MediaUploadModalProps): import("react").JSX.Element | null;
+export default MediaUploadModal;
+//# sourceMappingURL=index.d.ts.map

package/build-types/components/media-upload-modal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/media-upload-modal/index.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,mBAAmB,CAAC;AAUpE,UAAU,qBAAqB;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,QAAQ,EAAE,CAAE,KAAK,EAAE,UAAU,GAAG,UAAU,EAAE,KAAM,IAAI,CAAC;IAEvD;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAE,IAAI,EAAE;QAClB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,SAAS,EAAE,IAAI,EAAE,CAAC;QAClB,YAAY,CAAC,EAAE,CAAE,WAAW,EAAE,OAAO,CAAE,UAAU,CAAE,EAAE,KAAM,IAAI,CAAC;QAChE,OAAO,CAAC,EAAE,CAAE,KAAK,EAAE,KAAK,KAAM,IAAI,CAAC;QACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;KACnB,KAAM,IAAI,CAAC;IAEZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAE,EACjC,YAA0B,EAC1B,QAAgB,EAChB,KAAK,EACL,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,KAA4B,EAC5B,MAAM,EACN,aAAoB,EACpB,UAAU,EACV,MAAa,EACb,WAAkC,GAClC,EAAE,qBAAqB,sCAsOvB;AAED,eAAe,gBAAgB,CAAC"}

package/build-types/private-apis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private-apis.d.ts","sourceRoot":"","sources":["../src/private-apis.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,eAAO,MAAM,WAAW,IAAK,CAAC"}
+{"version":3,"file":"private-apis.d.ts","sourceRoot":"","sources":["../src/private-apis.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,eAAO,MAAM,WAAW,IAAK,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/media-utils",
-	"version": "5.33.1",
+	"version": "5.34.0",
 	"description": "WordPress Media Upload Utils.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -36,14 +36,18 @@
 	"wpScript": true,
 	"types": "build-types",
 	"dependencies": {
-		"@wordpress/api-fetch": "^7.33.1",
-		"@wordpress/blob": "^4.33.1",
-		"@wordpress/element": "^6.33.1",
-		"@wordpress/i18n": "^6.6.1",
-		"@wordpress/private-apis": "^1.33.1"
+		"@wordpress/api-fetch": "^7.34.0",
+		"@wordpress/blob": "^4.34.0",
+		"@wordpress/components": "^30.7.0",
+		"@wordpress/core-data": "^7.34.0",
+		"@wordpress/data": "^10.34.0",
+		"@wordpress/dataviews": "^10.2.0",
+		"@wordpress/element": "^6.34.0",
+		"@wordpress/i18n": "^6.7.0",
+		"@wordpress/private-apis": "^1.34.0"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "5f84bafdec1bed05247c1080c12f6a237951b862"
+	"gitHead": "ceebff807958d2e8fc755b5a20473939c78b4d1d"
 }

package/src/components/media-upload-modal/index.tsx

@@ -0,0 +1,370 @@
+/**
+ * WordPress dependencies
+ */
+import { useState, useCallback, useMemo } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import {
+	privateApis as coreDataPrivateApis,
+	store as coreStore,
+} from '@wordpress/core-data';
+import { resolveSelect } from '@wordpress/data';
+import { Modal, DropZone } from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import { DataViewsPicker } from '@wordpress/dataviews';
+import type { View, Field, ActionButton } from '@wordpress/dataviews';
+import type { Attachment, RestAttachment } from '../../utils/types';
+import { transformAttachment } from '../../utils/transform-attachment';
+import { uploadMedia } from '../../utils/upload-media';
+import { unlock } from '../../lock-unlock';
+
+const { useEntityRecordsWithPermissions } = unlock( coreDataPrivateApis );
+
+// Layout constant - matching the picker grid layout type
+const LAYOUT_PICKER_GRID = 'pickerGrid';
+
+interface MediaUploadModalProps {
+	/**
+	 * Array of allowed media types.
+	 * @default ['image']
+	 */
+	allowedTypes?: string[];
+
+	/**
+	 * Whether multiple files can be selected.
+	 * @default false
+	 */
+	multiple?: boolean;
+
+	/**
+	 * The currently selected media item(s).
+	 * Can be a single ID number or array of IDs for multiple selection.
+	 */
+	value?: number | number[];
+
+	/**
+	 * Function called when media is selected.
+	 * Receives single attachment object or array of attachments.
+	 */
+	onSelect: ( media: Attachment | Attachment[] ) => void;
+
+	/**
+	 * Function called when the modal is closed without selection.
+	 */
+	onClose?: () => void;
+
+	/**
+	 * Function to handle media uploads.
+	 * If not provided, drag and drop will be disabled.
+	 */
+	onUpload?: ( args: {
+		allowedTypes?: string[];
+		filesList: File[];
+		onFileChange?: ( attachments: Partial< Attachment >[] ) => void;
+		onError?: ( error: Error ) => void;
+		multiple?: boolean;
+	} ) => void;
+
+	/**
+	 * Title for the modal.
+	 * @default 'Select Media'
+	 */
+	title?: string;
+
+	/**
+	 * Whether the modal is open.
+	 */
+	isOpen: boolean;
+
+	/**
+	 * Whether the modal can be closed by clicking outside or pressing escape.
+	 * @default true
+	 */
+	isDismissible?: boolean;
+
+	/**
+	 * Additional CSS class for the modal.
+	 */
+	modalClass?: string;
+
+	/**
+	 * Whether to show a search input.
+	 * @default true
+	 */
+	search?: boolean;
+
+	/**
+	 * Label for the search input.
+	 */
+	searchLabel?: string;
+}
+
+/**
+ * MediaUploadModal component that uses Modal and DataViewsPicker for media selection.
+ *
+ * This is a modern functional component alternative to the legacy MediaUpload class component.
+ * It provides a cleaner API and better integration with the WordPress block editor.
+ *
+ * @param props               Component props
+ * @param props.allowedTypes  Array of allowed media types
+ * @param props.multiple      Whether multiple files can be selected
+ * @param props.value         Currently selected media item(s)
+ * @param props.onSelect      Function called when media is selected
+ * @param props.onClose       Function called when modal is closed
+ * @param props.onUpload      Function to handle media uploads
+ * @param props.title         Title for the modal
+ * @param props.isOpen        Whether the modal is open
+ * @param props.isDismissible Whether modal can be dismissed
+ * @param props.modalClass    Additional CSS class for modal
+ * @param props.search        Whether to show search input
+ * @param props.searchLabel   Label for search input
+ * @return JSX element or null
+ */
+export function MediaUploadModal( {
+	allowedTypes = [ 'image' ],
+	multiple = false,
+	value,
+	onSelect,
+	onClose,
+	onUpload,
+	title = __( 'Select Media' ),
+	isOpen,
+	isDismissible = true,
+	modalClass,
+	search = true,
+	searchLabel = __( 'Search media' ),
+}: MediaUploadModalProps ) {
+	const [ selection, setSelection ] = useState< string[] >( () => {
+		if ( ! value ) {
+			return [];
+		}
+		return Array.isArray( value )
+			? value.map( String )
+			: [ String( value ) ];
+	} );
+
+	// DataViews configuration - allow view updates
+	const [ view, setView ] = useState< View >( () => ( {
+		type: LAYOUT_PICKER_GRID,
+		fields: [],
+		titleField: 'title',
+		mediaField: 'url',
+		search: '',
+		page: 1,
+		perPage: 20,
+		filters: [],
+	} ) );
+
+	// Build query args based on view properties, similar to PostList
+	const queryArgs = useMemo( () => {
+		const filters: Record< string, any > = {};
+
+		view.filters?.forEach( ( filter ) => {
+			// Handle media type filters
+			if ( filter.field === 'media_type' ) {
+				filters.media_type = filter.value;
+			}
+			// Handle author filters
+			if ( filter.field === 'author' ) {
+				filters.author = filter.value;
+			}
+			// Handle date filters
+			if ( filter.field === 'date' ) {
+				filters.after = filter.value?.after;
+				filters.before = filter.value?.before;
+			}
+			// Handle mime type filters
+			if ( filter.field === 'mime_type' ) {
+				filters.mime_type = filter.value;
+			}
+		} );
+
+		// Base media type on allowedTypes if no filter is set
+		if ( ! filters.media_type ) {
+			filters.media_type = allowedTypes.includes( '*' )
+				? undefined
+				: allowedTypes[ 0 ];
+		}
+
+		return {
+			per_page: view.perPage || 20,
+			page: view.page || 1,
+			status: 'inherit',
+			order: view.sort?.direction,
+			orderby: view.sort?.field,
+			search: view.search,
+			...filters,
+		};
+	}, [ view, allowedTypes ] );
+
+	// Fetch all media attachments using WordPress core data with permissions
+	const {
+		records: mediaRecords,
+		isResolving: isLoading,
+		totalItems,
+		totalPages,
+	} = useEntityRecordsWithPermissions( 'postType', 'attachment', queryArgs );
+
+	const fields: Field< RestAttachment >[] = useMemo(
+		() => [
+			{
+				id: 'url',
+				type: 'media' as const,
+				label: __( 'Media' ),
+				render: ( { item }: { item: RestAttachment } ) => (
+					<img
+						src={ item.source_url }
+						alt={ item.alt_text }
+						style={ {
+							width: '100%',
+							height: '100%',
+							objectFit: 'cover',
+							borderRadius: '4px',
+						} }
+					/>
+				),
+			},
+			{
+				id: 'title',
+				type: 'text' as const,
+				label: __( 'Title' ),
+				getValue: ( { item }: { item: RestAttachment } ) => {
+					const titleValue = item.title.raw || item.title.rendered;
+					return titleValue || __( '(no title)' );
+				},
+			},
+			{
+				id: 'alt',
+				type: 'text' as const,
+				label: __( 'Alt text' ),
+				getValue: ( { item }: { item: RestAttachment } ) =>
+					item.alt_text,
+			},
+		],
+		[]
+	);
+
+	const actions: ActionButton< RestAttachment >[] = useMemo(
+		() => [
+			{
+				id: 'select',
+				label: multiple ? __( 'Select' ) : __( 'Select' ),
+				isPrimary: true,
+				supportsBulk: multiple,
+				async callback() {
+					if ( selection.length === 0 ) {
+						return;
+					}
+
+					const selectedPostsQuery = {
+						include: selection,
+						per_page: -1,
+					};
+
+					const selectedPosts = await resolveSelect(
+						coreStore
+					).getEntityRecords(
+						'postType',
+						'attachment',
+						selectedPostsQuery
+					);
+
+					// Transform the selected posts to the expected Attachment format
+					const transformedPosts =
+						selectedPosts?.map( transformAttachment );
+
+					const selectedItems = multiple
+						? transformedPosts
+						: transformedPosts?.[ 0 ];
+
+					onSelect( selectedItems );
+				},
+			},
+		],
+		[ multiple, onSelect, selection ]
+	);
+
+	const handleModalClose = useCallback( () => {
+		onClose?.();
+	}, [ onClose ] );
+
+	const paginationInfo = useMemo(
+		() => ( {
+			totalItems,
+			totalPages,
+		} ),
+		[ totalItems, totalPages ]
+	);
+
+	const defaultLayouts = useMemo(
+		() => ( {
+			[ LAYOUT_PICKER_GRID ]: {},
+		} ),
+		[]
+	);
+
+	if ( ! isOpen ) {
+		return null;
+	}
+
+	// Use onUpload if provided, otherwise fall back to uploadMedia
+	const handleUpload = onUpload || uploadMedia;
+
+	return (
+		<Modal
+			title={ title }
+			onRequestClose={ handleModalClose }
+			isDismissible={ isDismissible }
+			className={ modalClass }
+			size="fill"
+		>
+			<DropZone
+				onFilesDrop={ ( files ) => {
+					let filteredFiles = files;
+					// Filter files by allowed types if specified
+					if ( allowedTypes && ! allowedTypes.includes( '*' ) ) {
+						filteredFiles = files.filter( ( file ) =>
+							allowedTypes.some( ( allowedType ) => {
+								// Check if the file type matches the allowed MIME type
+								return (
+									file.type === allowedType ||
+									file.type.startsWith(
+										allowedType.replace( '*', '' )
+									)
+								);
+							} )
+						);
+					}
+					if ( filteredFiles.length > 0 ) {
+						handleUpload( {
+							allowedTypes,
+							filesList: filteredFiles,
+							multiple,
+						} );
+					}
+				} }
+				label={ __( 'Drop files to upload' ) }
+			/>
+			<DataViewsPicker
+				data={ mediaRecords || [] }
+				fields={ fields }
+				view={ view }
+				onChangeView={ setView }
+				actions={ actions }
+				selection={ selection }
+				onChangeSelection={ setSelection }
+				isLoading={ isLoading }
+				paginationInfo={ paginationInfo }
+				defaultLayouts={ defaultLayouts }
+				getItemId={ ( item: RestAttachment ) => String( item.id ) }
+				search={ search }
+				searchLabel={ searchLabel }
+				itemListLabel={ __( 'Media items' ) }
+			/>
+		</Modal>
+	);
+}
+
+export default MediaUploadModal;

package/src/private-apis.ts

@@ -2,6 +2,7 @@
  * Internal dependencies
  */
 import { sideloadMedia } from './utils/sideload-media';
+import { MediaUploadModal } from './components/media-upload-modal';
 import { lock } from './lock-unlock';
 
 /**
@@ -11,4 +12,5 @@ export const privateApis = {};
 
 lock( privateApis, {
 	sideloadMedia,
+	MediaUploadModal,
 } );

package/tsconfig.json

@@ -8,6 +8,10 @@
 	"references": [
 		{ "path": "../api-fetch" },
 		{ "path": "../blob" },
+		{ "path": "../components" },
+		{ "path": "../core-data" },
+		{ "path": "../data" },
+		{ "path": "../dataviews" },
 		{ "path": "../element" },
 		{ "path": "../i18n" },
 		{ "path": "../private-apis" }