MediaPlaceholder: Document the different responses returned by onSelect

[andreaslindahl]

Description

Why on earth does MediaPlaceholder's onSelect return different data structures when uploading directly from the MediaPlaceholder or inserting media from the Media Gallery?

When uploading directly, we get data that includes the different image sizes in a property called "media_details":

media_details: {
   sizes: {
      full: { file: "filename.jpg", width: 2000, height: 2000, ... }
      ...
   }
}

But when selecting a file from the media gallery, we get the different sizes in a "sizes" property:

sizes: {
   full: { url: "/wp-content/uploads/.../filename.jpg", width: 2000, height: 2000, ... }
}

As you can see, the data structure is different AND we get a "url" property, with the complete path, instead of just the filename in a "file" property.

Step-by-step reproduction instructions

1. Upload a file using the MediaPlaceholder
2. Inspect what you get back in the onSelect callback
3. Select a file from the media gallery using the MediaPlaceholder
4. Inspect what you get back in the onSelect callback

Screenshots, screen recording, code snippet

No response

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[Mamaduka]

The component uses REST API for uploading images, and MediaLibrary uses async-upload.php. The media library was built before REST API, and its responses never normalized to match API.

The core blocks use helper methods like pickRelevantMediaFiles to handle both cases.

[andreaslindahl]

Thanks, pickRelevantMediaFiles looks useful in this case.

Perhaps the documentation for MediaPlaceholder needs som clarification, since the data structure it describes isn't true for all use cases?

[Mamaduka]

Agreed. The documentation needs to reflect the difference. I'll update the issue title and labels.

P.S. This is the closest ticket I found on Trac for updating the response returned by MediaLibrary - https://core.trac.wordpress.org/ticket/39553.