Media Utils: Restrict file uploads with multiple prop in uploadMedia and mediaUpload

[yogeshbhutkar]

What?

Closes #68629

This PR adds a multiple prop to the uploadMedia and mediaUpload functions. The prop defaults to True. When set to False, any attempts to drop or select multiple images result in an error message returned to the user, and the process aborts completely due to an early return.

Why?

This PR uses a generalized approach to implement prop-based restrictions on file uploads instead of implementing separate logic in the consumers. Some consumer implementations include:

gutenberg/packages/block-editor/src/components/background-image-control/index.js

Line 316 in 0c42f22

if ( filesList?.length > 1 ) {

gutenberg/packages/block-library/src/site-logo/edit.js

Line 509 in 0c42f22

if ( filesList?.length > 1 ) {

How?

The multiple prop, which accepts a boolean value, has been introduced in the uploadMedia and mediaUpload functions. When multiple is set to false and multiple images are selected, the process is aborted early, triggering the onError callback.

Testing Instructions

1. Try uploading multiple files in the following places:
   1.1. Site logo block
   1.2. Featured image block
   1.3. Featured image panel in the document sidebar
   1.4. Media & text block
   1.5. Cover block
2. Ensure multiple files abort the process.

Screencast

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Type-related labels to choose from: [Type] Automated Testing, [Type] Breaking Change, [Type] Bug, [Type] Build Tooling, [Type] Code Quality, [Type] Copy, [Type] Developer Documentation, [Type] Enhancement, [Type] Experimental, [Type] Feature, [Type] New API, [Type] Task, [Type] Technical Prototype, [Type] Performance, [Type] Project Management, [Type] Regression, [Type] Security, [Type] WP Core Ticket, Backport from WordPress Core, Gutenberg Plugin.
• Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Type-related labels to choose from: [Type] Automated Testing, [Type] Breaking Change, [Type] Bug, [Type] Build Tooling, [Type] Code Quality, [Type] Copy, [Type] Developer Documentation, [Type] Enhancement, [Type] Experimental, [Type] Feature, [Type] New API, [Type] Task, [Type] Technical Prototype, [Type] Performance, [Type] Project Management, [Type] Regression, [Type] Security, [Type] WP Core Ticket, Backport from WordPress Core, Gutenberg Plugin.
• Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: yogeshbhutkar <[email protected]>
Co-authored-by: swissspidy <[email protected]>
Co-authored-by: Mayank-Tripathi32 <[email protected]>
Co-authored-by: t-hamano <[email protected]>
Co-authored-by: Mamaduka <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[swissspidy]

Let's add a unit test for this accordingly in packages/media-utils/src/utils/test/upload-media.ts

[swissspidy]

The change here is unnecessary, let's revert that.

[swissspidy]

Just use a regular Error if you don't want to pass a file.