Media Utils: Allow limiting uploads to a single file

[Mamaduka]

A proposal to update the uploadMedia method and allow limiting uploads to a single file. When filesList exceeds the set limit, the function will call an onError callback and exit early.

Why?

The mediaUpload setting, which utilizes this method, is often used with the DropZone component. This component allows any number of files, but consumers only see and use the first file.

Currently, restrictions need to be set on the consumer level. Examples:

• 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 ) {

Proposal

Introduce a new boolean multiple boolean argument for uploadMedia and mediaUpload methods. The multiple also matches the prop used by the MediaUpload component.

cc @swissspidy, @t-hamano

[swissspidy]

Re-sharing my thoughts from #68618 (comment):

There are many different places:

• Site logo block
• Featured image block
• Featured image panel in the document sidebar
• Media & text block
• Cover block

It's definitely a bit unexpected to upload multiple files when actually only 1 ends up being visible in the respective block/panel.

But should this really throw a hard error? Should this just (silently or with a warning) drop the excessive images instead?

---

A multiple argument is interesting, but the above questions are still valid. Also, what if you want to limit to a specific number of images?

Note that multiple would need to default to true for backward compatibility purposes.

[Mamaduka]

Initially, I considered adding a limit argument instead of multiple, but the latter is consistent with higher-level components like MediaUpload.

But should this really throw a hard error?

What do we consider a hard error in this case? Calling the onError callback and quitting the process?

Should this just (silently or with a warning) drop the excessive images instead?

Don't have a strong opinion on this. I think we should go with a resolution that users expect.

[swissspidy]

What do we consider a hard error in this case? Calling the onError callback and quitting the process?

Yes. What you implemented in #68618

[Mayank-Tripathi32]

Should this just (silently or with a warning) drop the excessive images instead?

I believe it would be better to notify the user, letting them know that only the first image has been uploaded instead of completing stopping with a hard error.