@wordpress/media-utils 5.6.0 → 5.8.0

package/src/utils/test/{upload-media.test.js → upload-media.ts}

@@ -1,19 +1,18 @@
-/**
- * WordPress dependencies
- */
-import { createBlobURL } from '@wordpress/blob';
-import apiFetch from '@wordpress/api-fetch';
-
 /**
  * Internal dependencies
  */
-import { uploadMedia, getMimeTypesArray } from '../upload-media';
+import { uploadMedia } from '../upload-media';
+import { UploadError } from '../upload-error';
+import { uploadToServer } from '../upload-to-server';
+
+jest.mock( '../upload-to-server', () => ( {
+	uploadToServer: jest.fn(),
+} ) );
 
 jest.mock( '@wordpress/blob', () => ( {
 	createBlobURL: jest.fn(),
 	revokeBlobURL: jest.fn(),
 } ) );
-jest.mock( '@wordpress/api-fetch', () => jest.fn() );
 
 const xmlFile = new window.File( [ 'fake_file' ], 'test.xml', {
 	type: 'text/xml',
@@ -23,6 +22,10 @@ const imageFile = new window.File( [ 'fake_file' ], 'test.jpeg', {
 } );
 
 describe( 'uploadMedia', () => {
+	afterEach( () => {
+		jest.clearAllMocks();
+	} );
+
 	it( 'should do nothing on no files', async () => {
 		const onError = jest.fn();
 		const onFileChange = jest.fn();
@@ -33,7 +36,7 @@ describe( 'uploadMedia', () => {
 		} );
 
 		expect( onError ).not.toHaveBeenCalled();
-		expect( onFileChange ).not.toHaveBeenCalled();
+		expect( uploadToServer ).not.toHaveBeenCalled();
 	} );
 
 	it( 'should error if allowedTypes contains a partial mime type and the validation fails', async () => {
@@ -47,11 +50,14 @@ describe( 'uploadMedia', () => {
 		} );
 
 		expect( onError ).toHaveBeenCalledWith(
-			expect.objectContaining( {
+			new UploadError( {
 				code: 'MIME_TYPE_NOT_SUPPORTED',
+				message:
+					'test.xml: Sorry, this file type is not supported here.',
+				file: xmlFile,
 			} )
 		);
-		expect( onFileChange ).not.toHaveBeenCalled();
+		expect( uploadToServer ).not.toHaveBeenCalled();
 	} );
 
 	it( 'should error if allowedTypes contains a complete mime type and the validation fails', async () => {
@@ -65,17 +71,17 @@ describe( 'uploadMedia', () => {
 		} );
 
 		expect( onError ).toHaveBeenCalledWith(
-			expect.objectContaining( {
+			new UploadError( {
 				code: 'MIME_TYPE_NOT_SUPPORTED',
+				message:
+					'test.jpeg: Sorry, this file type is not supported here.',
+				file: xmlFile,
 			} )
 		);
-		expect( onFileChange ).not.toHaveBeenCalled();
+		expect( uploadToServer ).not.toHaveBeenCalled();
 	} );
 
 	it( 'should work if allowedTypes contains a complete mime type and the validation succeeds', async () => {
-		createBlobURL.mockReturnValue( 'blob:fake_blob' );
-		apiFetch.mockResolvedValue( { title: { raw: 'Test' } } );
-
 		const onError = jest.fn();
 		const onFileChange = jest.fn();
 		await uploadMedia( {
@@ -83,10 +89,11 @@ describe( 'uploadMedia', () => {
 			filesList: [ imageFile ],
 			onError,
 			onFileChange,
+			wpAllowedMimeTypes: { jpeg: 'image/jpeg' },
 		} );
 
 		expect( onError ).not.toHaveBeenCalled();
-		expect( onFileChange ).toHaveBeenCalledTimes( 2 );
+		expect( uploadToServer ).toHaveBeenCalled();
 	} );
 
 	it( 'should error if allowedTypes contains multiple types and the validation fails', async () => {
@@ -100,17 +107,17 @@ describe( 'uploadMedia', () => {
 		} );
 
 		expect( onError ).toHaveBeenCalledWith(
-			expect.objectContaining( {
+			new UploadError( {
 				code: 'MIME_TYPE_NOT_SUPPORTED',
+				message:
+					'test.xml: Sorry, this file type is not supported here.',
+				file: xmlFile,
 			} )
 		);
-		expect( onFileChange ).not.toHaveBeenCalled();
+		expect( uploadToServer ).not.toHaveBeenCalled();
 	} );
 
 	it( 'should work if allowedTypes contains multiple types and the validation succeeds', async () => {
-		createBlobURL.mockReturnValue( 'blob:fake_blob' );
-		apiFetch.mockResolvedValue( { title: { raw: 'Test' } } );
-
 		const onError = jest.fn();
 		const onFileChange = jest.fn();
 		await uploadMedia( {
@@ -118,16 +125,14 @@ describe( 'uploadMedia', () => {
 			filesList: [ imageFile ],
 			onError,
 			onFileChange,
+			wpAllowedMimeTypes: { jpeg: 'image/jpeg', mp4: 'video/mp4' },
 		} );
 
 		expect( onError ).not.toHaveBeenCalled();
-		expect( onFileChange ).toHaveBeenCalledTimes( 2 );
+		expect( uploadToServer ).toHaveBeenCalled();
 	} );
 
 	it( 'should only fail the invalid file and still allow others to succeed when uploading multiple files', async () => {
-		createBlobURL.mockReturnValue( 'blob:fake_blob' );
-		apiFetch.mockResolvedValue( { title: { raw: 'Test' } } );
-
 		const onError = jest.fn();
 		const onFileChange = jest.fn();
 		await uploadMedia( {
@@ -135,15 +140,18 @@ describe( 'uploadMedia', () => {
 			filesList: [ imageFile, xmlFile ],
 			onError,
 			onFileChange,
+			wpAllowedMimeTypes: { jpeg: 'image/jpeg' },
 		} );
 
 		expect( onError ).toHaveBeenCalledWith(
-			expect.objectContaining( {
+			new UploadError( {
 				code: 'MIME_TYPE_NOT_SUPPORTED',
+				message:
+					'test.xml: Sorry, you are not allowed to upload this file type.',
 				file: xmlFile,
 			} )
 		);
-		expect( onFileChange ).toHaveBeenCalledTimes( 2 );
+		expect( uploadToServer ).toHaveBeenCalledTimes( 1 );
 	} );
 
 	it( 'should error if the file size is greater than the maximum', async () => {
@@ -155,19 +163,22 @@ describe( 'uploadMedia', () => {
 			maxUploadFileSize: 1,
 			onError,
 			onFileChange,
+			wpAllowedMimeTypes: { jpeg: 'image/jpeg' },
 		} );
 
 		expect( onError ).toHaveBeenCalledWith(
-			expect.objectContaining( {
+			new UploadError( {
 				code: 'SIZE_ABOVE_LIMIT',
+				message:
+					'test.jpeg: This file exceeds the maximum upload size for this site.',
+				file: imageFile,
 			} )
 		);
-		expect( onFileChange ).not.toHaveBeenCalled();
+		expect( uploadToServer ).not.toHaveBeenCalled();
 	} );
 
 	it( 'should call error handler with the correct error object if file type is not allowed for user', async () => {
 		const onError = jest.fn();
-		const onFileChange = jest.fn();
 		await uploadMedia( {
 			allowedTypes: [ 'image' ],
 			filesList: [ imageFile ],
@@ -176,53 +187,13 @@ describe( 'uploadMedia', () => {
 		} );
 
 		expect( onError ).toHaveBeenCalledWith(
-			expect.objectContaining( {
+			new UploadError( {
 				code: 'MIME_TYPE_NOT_ALLOWED_FOR_USER',
+				message:
+					'test.jpeg: Sorry, you are not allowed to upload this file type.',
+				file: imageFile,
 			} )
 		);
-		expect( onFileChange ).not.toHaveBeenCalled();
-	} );
-} );
-
-describe( 'getMimeTypesArray', () => {
-	it( 'should return the parameter passed if it is "falsy" e.g: undefined or null', () => {
-		expect( getMimeTypesArray( null ) ).toEqual( null );
-		expect( getMimeTypesArray( undefined ) ).toEqual( undefined );
-	} );
-
-	it( 'should return an empty array if an empty object is passed', () => {
-		expect( getMimeTypesArray( {} ) ).toEqual( [] );
-	} );
-
-	it( 'should return the type plus a new mime type with type and subtype with the extension if a type is passed', () => {
-		expect( getMimeTypesArray( { ext: 'chicken' } ) ).toEqual( [
-			'chicken',
-			'chicken/ext',
-		] );
-	} );
-
-	it( 'should return the mime type passed and a new mime type with type and the extension as subtype', () => {
-		expect( getMimeTypesArray( { ext: 'chicken/ribs' } ) ).toEqual( [
-			'chicken/ribs',
-			'chicken/ext',
-		] );
-	} );
-
-	it( 'should return the mime type passed and an additional mime type per extension supported', () => {
-		expect( getMimeTypesArray( { 'jpg|jpeg|jpe': 'image/jpeg' } ) ).toEqual(
-			[ 'image/jpeg', 'image/jpg', 'image/jpeg', 'image/jpe' ]
-		);
-	} );
-
-	it( 'should handle multiple mime types', () => {
-		expect(
-			getMimeTypesArray( { 'ext|aaa': 'chicken/ribs', aaa: 'bbb' } )
-		).toEqual( [
-			'chicken/ribs',
-			'chicken/ext',
-			'chicken/aaa',
-			'bbb',
-			'bbb/aaa',
-		] );
+		expect( uploadToServer ).not.toHaveBeenCalled();
 	} );
 } );

package/src/utils/test/validate-file-size.ts

@@ -0,0 +1,70 @@
+/**
+ * Internal dependencies
+ */
+import { validateFileSize } from '../validate-file-size';
+import { UploadError } from '../upload-error';
+
+const imageFile = new window.File( [ 'fake_file' ], 'test.jpeg', {
+	type: 'image/jpeg',
+} );
+
+const emptyFile = new window.File( [], 'test.jpeg', {
+	type: 'image/jpeg',
+} );
+
+describe( 'validateFileSize', () => {
+	afterEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'should error if the file is empty', () => {
+		expect( () => {
+			validateFileSize( emptyFile );
+		} ).toThrow(
+			new UploadError( {
+				code: 'EMPTY_FILE',
+				message: 'test.jpeg: This file is empty.',
+				file: imageFile,
+			} )
+		);
+	} );
+
+	it( 'should error if the file is is greater than the maximum', () => {
+		expect( () => {
+			validateFileSize( imageFile, 2 );
+		} ).toThrow(
+			new UploadError( {
+				code: 'SIZE_ABOVE_LIMIT',
+				message:
+					'test.jpeg: This file exceeds the maximum upload size for this site.',
+				file: imageFile,
+			} )
+		);
+	} );
+
+	it( 'should not error if the file is below the limit', () => {
+		expect( () => {
+			validateFileSize( imageFile, 100 );
+		} ).not.toThrow(
+			new UploadError( {
+				code: 'SIZE_ABOVE_LIMIT',
+				message:
+					'test.jpeg: This file exceeds the maximum upload size for this site.',
+				file: imageFile,
+			} )
+		);
+	} );
+
+	it( 'should not error if there is no limit', () => {
+		expect( () => {
+			validateFileSize( imageFile );
+		} ).not.toThrow(
+			new UploadError( {
+				code: 'SIZE_ABOVE_LIMIT',
+				message:
+					'test.jpeg: This file exceeds the maximum upload size for this site.',
+				file: imageFile,
+			} )
+		);
+	} );
+} );

package/src/utils/test/validate-mime-type-for-user.ts

@@ -0,0 +1,37 @@
+/**
+ * Internal dependencies
+ */
+import { validateMimeTypeForUser } from '../validate-mime-type-for-user';
+import { UploadError } from '../upload-error';
+
+const imageFile = new window.File( [ 'fake_file' ], 'test.jpeg', {
+	type: 'image/jpeg',
+} );
+
+describe( 'validateMimeTypeForUser', () => {
+	afterEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'should not error if  wpAllowedMimeTypes is null or missing', async () => {
+		expect( () => {
+			validateMimeTypeForUser( imageFile );
+		} ).not.toThrow();
+		expect( () => {
+			validateMimeTypeForUser( imageFile, null );
+		} ).not.toThrow();
+	} );
+
+	it( 'should error if file type is not allowed for user', async () => {
+		expect( () => {
+			validateMimeTypeForUser( imageFile, { aac: 'audio/aac' } );
+		} ).toThrow(
+			new UploadError( {
+				code: 'MIME_TYPE_NOT_ALLOWED_FOR_USER',
+				message:
+					'test.jpeg: Sorry, you are not allowed to upload this file type.',
+				file: imageFile,
+			} )
+		);
+	} );
+} );

package/src/utils/test/validate-mime-type.ts

@@ -0,0 +1,57 @@
+/**
+ * Internal dependencies
+ */
+import { validateMimeType } from '../validate-mime-type';
+import { UploadError } from '../upload-error';
+
+const xmlFile = new window.File( [ 'fake_file' ], 'test.xml', {
+	type: 'text/xml',
+} );
+const imageFile = new window.File( [ 'fake_file' ], 'test.jpeg', {
+	type: 'image/jpeg',
+} );
+
+describe( 'validateMimeType', () => {
+	afterEach( () => {
+		jest.clearAllMocks();
+	} );
+
+	it( 'should error if allowedTypes contains a partial mime type and the validation fails', async () => {
+		expect( () => {
+			validateMimeType( xmlFile, [ 'image' ] );
+		} ).toThrow(
+			new UploadError( {
+				code: 'MIME_TYPE_NOT_SUPPORTED',
+				message:
+					'test.xml: Sorry, this file type is not supported here.',
+				file: xmlFile,
+			} )
+		);
+	} );
+
+	it( 'should error if allowedTypes contains a complete mime type and the validation fails', async () => {
+		expect( () => {
+			validateMimeType( imageFile, [ 'image/gif' ] );
+		} ).toThrow(
+			new UploadError( {
+				code: 'MIME_TYPE_NOT_SUPPORTED',
+				message:
+					'test.jpeg: Sorry, this file type is not supported here.',
+				file: xmlFile,
+			} )
+		);
+	} );
+
+	it( 'should error if allowedTypes contains multiple types and the validation fails', async () => {
+		expect( () => {
+			validateMimeType( xmlFile, [ 'video', 'image' ] );
+		} ).toThrow(
+			new UploadError( {
+				code: 'MIME_TYPE_NOT_SUPPORTED',
+				message:
+					'test.xml: Sorry, this file type is not supported here.',
+				file: xmlFile,
+			} )
+		);
+	} );
+} );

package/src/utils/transform-attachment.ts

@@ -0,0 +1,24 @@
+/**
+ * Internal dependencies
+ */
+import type { Attachment, RestAttachment } from './types';
+
+/**
+ * Transforms an attachment object from the REST API shape into the shape expected by the block editor and other consumers.
+ *
+ * @param attachment REST API attachment object.
+ */
+export function transformAttachment( attachment: RestAttachment ): Attachment {
+	// eslint-disable-next-line camelcase
+	const { alt_text, source_url, ...savedMediaProps } = attachment;
+	return {
+		...savedMediaProps,
+		alt: attachment.alt_text,
+		caption: attachment.caption?.raw ?? '',
+		title: attachment.title.raw,
+		url: attachment.source_url,
+		poster:
+			attachment._embedded?.[ 'wp:featuredmedia' ]?.[ 0 ]?.source_url ||
+			undefined,
+	};
+}

package/src/utils/types.ts

@@ -0,0 +1,207 @@
+/**
+ * A media attachment object in a REST API context.
+ *
+ * Simplified version of what's defined in the wp-types package.
+ *
+ * @see https://www.npmjs.com/package/wp-types
+ */
+interface WP_REST_API_Attachment {
+	/**
+	 * Unique identifier for the attachment.
+	 */
+	id: number;
+	/**
+	 * The ID of the featured media for the post.
+	 */
+	featured_media: number;
+	/**
+	 * URL to the attachment.
+	 */
+	link: string;
+	/**
+	 * The date the attachment was published, in the site's timezone.
+	 */
+	date: string;
+	/**
+	 * The date the attachment was published, as GMT.
+	 */
+	date_gmt: string;
+	/**
+	 * The date the attachment was last modified, in the site's timezone.
+	 */
+	modified: string;
+	/**
+	 * The date the attachment was last modified, as GMT.
+	 */
+	modified_gmt: string;
+	/**
+	 * An alphanumeric identifier for the attachment unique to its type.
+	 */
+	slug: string;
+	/**
+	 * A named status for the attachment.
+	 */
+	status: string;
+	/**
+	 * Type of Post for the attachment.
+	 */
+	type: 'attachment';
+	/**
+	 * Alternative text to display when attachment is not displayed.
+	 */
+	alt_text: string;
+	/**
+	 * The attachment caption.
+	 */
+	caption: {
+		/**
+		 * Caption for the attachment, as it exists in the database. Only present when using the 'edit' context.
+		 */
+		raw?: string;
+		/**
+		 * HTML caption for the attachment, transformed for display.
+		 */
+		rendered: string;
+	};
+	/**
+	 * The attachment description.
+	 */
+	description: {
+		/**
+		 * Description for the attachment, as it exists in the database. Only present when using the 'edit' context.
+		 */
+		raw?: string;
+		/**
+		 * HTML description for the attachment, transformed for display.
+		 */
+		rendered: string;
+	};
+	/**
+	 * Attachment type.
+	 */
+	media_type: 'image' | 'file';
+	/**
+	 * The attachment MIME type.
+	 */
+	mime_type: string;
+	/**
+	 * Details about the media file, specific to its type.
+	 */
+	media_details: {
+		[ k: string ]: unknown;
+	};
+	/**
+	 * The ID for the associated post of the attachment.
+	 */
+	post: number | null;
+	/**
+	 * URL to the original attachment file.
+	 */
+	source_url: string;
+	/**
+	 * List of the missing image sizes of the attachment.  Only present when using the 'edit' context.
+	 */
+	missing_image_sizes?: string[];
+	/**
+	 * Permalink template for the attachment. Only present when using the 'edit' context and the post type is public.
+	 */
+	permalink_template?: string;
+	/**
+	 * Slug automatically generated from the attachment title. Only present when using the 'edit' context and the post type is public.
+	 */
+	generated_slug?: string;
+	/**
+	 * An array of the class names for the post container element.
+	 */
+	class_list: string[];
+	/**
+	 * The title for the attachment.
+	 */
+	title: {
+		/**
+		 * Title for the attachment, as it exists in the database. Only present when using the 'edit' context.
+		 */
+		raw?: string;
+		/**
+		 * HTML title for the attachment, transformed for display.
+		 */
+		rendered: string;
+	};
+	/**
+	 * The ID for the author of the attachment.
+	 */
+	author: number;
+	/**
+	 * Whether or not comments are open on the attachment.
+	 */
+	comment_status: string;
+	/**
+	 * Whether or not the attachment can be pinged.
+	 */
+	ping_status: string;
+	/**
+	 * Meta fields.
+	 */
+	meta:
+		| []
+		| {
+				[ k: string ]: unknown;
+		  };
+	/**
+	 * The theme file to use to display the attachment.
+	 */
+	template: string;
+	_links: {
+		[ k: string ]: {
+			href: string;
+			embeddable?: boolean;
+			[ k: string ]: unknown;
+		}[];
+	};
+	/**
+	 * The embedded representation of relations. Only present when the '_embed' query parameter is set.
+	 */
+	_embedded?: {
+		/**
+		 * The author of the post.
+		 */
+		author: unknown[];
+		/**
+		 * The featured image post.
+		 */
+		'wp:featuredmedia'?: WP_REST_API_Attachment[];
+		[ k: string ]: unknown;
+	};
+	[ k: string ]: unknown;
+}
+
+/**
+ * REST API attachment object with additional fields added by this project.
+ */
+export interface RestAttachment extends WP_REST_API_Attachment {}
+
+type BetterOmit< T, K extends PropertyKey > = {
+	[ P in keyof T as P extends K ? never : P ]: T[ P ];
+};
+
+/**
+ * Transformed attachment object.
+ */
+export type Attachment = BetterOmit<
+	RestAttachment,
+	'alt_text' | 'source_url' | 'caption' | 'title'
+> & {
+	alt: WP_REST_API_Attachment[ 'alt_text' ];
+	caption: WP_REST_API_Attachment[ 'caption' ][ 'raw' ] & string;
+	title: WP_REST_API_Attachment[ 'title' ][ 'raw' ];
+	url: WP_REST_API_Attachment[ 'source_url' ];
+	poster?: WP_REST_API_Attachment[ 'source_url' ];
+};
+
+export type OnChangeHandler = ( attachments: Partial< Attachment >[] ) => void;
+export type OnSuccessHandler = ( attachments: Partial< Attachment >[] ) => void;
+export type OnErrorHandler = ( error: Error ) => void;
+
+export type CreateRestAttachment = Partial< RestAttachment >;
+
+export type AdditionalData = BetterOmit< CreateRestAttachment, 'meta' >;

package/src/utils/upload-error.ts

@@ -0,0 +1,26 @@
+interface UploadErrorArgs {
+	code: string;
+	message: string;
+	file: File;
+	cause?: Error;
+}
+
+/**
+ * MediaError class.
+ *
+ * Small wrapper around the `Error` class
+ * to hold an error code and a reference to a file object.
+ */
+export class UploadError extends Error {
+	code: string;
+	file: File;
+
+	constructor( { code, message, file, cause }: UploadErrorArgs ) {
+		super( message, { cause } );
+
+		Object.setPrototypeOf( this, new.target.prototype );
+
+		this.code = code;
+		this.file = file;
+	}
+}