Skip to content

Media Editor: Add a placeholder state with download and copy buttons - #86490

Open
andrewserong wants to merge 8 commits into
trunkfrom
update/media-editor-file-placeholder-state
Open

andrewserong wants to merge 8 commits into
trunkfrom
update/media-editor-file-placeholder-state

Conversation

@andrewserong

@andrewserong andrewserong commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

What?

Part of #72734

Add a layout for the placeholder/preview state of files that cannot be previewed (e.g. ZIP files and so on).

Why?

Prior to this PR the fallback was very basic. This gives folks something more pleasing to look at, with easy to reach buttons for common tasks (download and copy link) with the filename and file size easy to see, so that it's easy to identify the file.

Download + Copy are features of the core media editor that have been missing in the new editor experiment.

How?

  • Add a layout for the file preview state of the media editor (based on EmptyState)
  • Re-use the existing filename and filesize fields to grab data for showing in the details area of the card
  • Add "Download" and "Copy URL" buttons to the card
  • For the error state of the media preview, use a similar layout using EmptyState, following a similar design

Testing Instructions

  1. Activate the Media Editor Route experiment:
image
  1. In the media library, upload some files that cannot be previewed (e.g. a ZIP file, a DOCX file)
  2. in the list view of the media library, go to edit the item
  3. Take a look at the preview and check that the download and copy url buttons work
  4. If you'd like to test the error state (that displays a similar card) try opening a Video file, then after the page is loaded, open up the Network tab in dev tools, right click on the mp4 file network request and click to block it, and then reload the page

Screenshots or screencast

Preview state for files (e.g. ZIP files):

image

Error state when a media file fails to load:

image

Use of AI Tools

Claude Code (Opus 5.5)

@andrewserong andrewserong self-assigned this Nov 9, 2026
@andrewserong andrewserong added [Type] Enhancement A suggestion for improvement. [Feature] Media Anything that impacts the experience of managing media labels Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

🎉 Props

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: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: noruzzamans <noruzzaman@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>

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


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: +1.18 kB (+0.01%)

Total Size: 8.66 MB

📦 View Changed
Filename Size Change
build/scripts/editor/index.min.js 573 kB +1.35 kB (+0.24%)
build/styles/editor/style-rtl.css 31.6 kB -52 B (-0.16%)
build/styles/editor/style-rtl.min.css 27.4 kB -35 B (-0.13%)
build/styles/editor/style.css 31.7 kB -51 B (-0.16%)
build/styles/editor/style.min.css 27.4 kB -35 B (-0.13%)

29f07ad Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 90cab26 trunk % Change
timeToFirstByte 50.4 ms +6.75% -4.96% 49.5 ms +5.25% -1.52% 1.82%
largestContentfulPaint 80 ms +10% -0% 80 ms +10% -5% 0%
lcpMinusTtfb 30.4 ms +19.08% -3.62% 29.9 ms +21.24% -10.37% 1.67%
wpBeforeTemplate 25.04 ms +10.3% -3.95% 24.88 ms +3.26% -1.69% 0.64%
wpTemplate 20.97 ms +4.86% -5.48% 20.57 ms +5.54% -2.14% 1.94%
wpTotal 46.24 ms +7.14% -5.47% 45.36 ms +5.73% -1.48% 1.94%
wpMemoryUsage 7.75 MB +0% -0% 7.71 MB +0% -0% 0.45%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 90cab26 trunk % Change
timeToFirstByte 40.75 ms +4.42% -2.58% 40.65 ms +4.06% -4.18% 0.25%
largestContentfulPaint 76 ms +5.26% -0% 76 ms +0% -5.26% 0%
lcpMinusTtfb 35.8 ms +4.05% -6.01% 34.3 ms +7.14% -3.35% 4.37%
wpBeforeTemplate 21.59 ms +3.1% -1.44% 21.43 ms +2.24% -2.38% 0.75%
wpTemplate 15.74 ms +4.26% -3.81% 15.64 ms +4.54% -5.37% 0.64%
wpTotal 37.41 ms +4.52% -2.27% 37.29 ms +4.53% -3.86% 0.32%
wpMemoryUsage 6.44 MB +0% -0% 6.40 MB +0% -0% 0.56%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 90cab26 trunk % Change
mediaProcessingJpeg 400.52 ms +0.29% -0.5% 399.41 ms +0.26% -0.59% 0.28%
mediaProcessingAvif 5859.76 ms +0.07% -0.42% 5863.94 ms +0.21% -0.28% -0.07%
mediaProcessingJpegToAvif 3962.89 ms +0.45% -0.09% 3956.16 ms +0.44% -0.29% 0.17%

media-upload

Metric 90cab26 trunk % Change
jpegUploadProcessing 1738.84 ms +16.57% -14.66% 1505.79 ms +0.91% -0.6% 15.48%
pngUploadProcessing 258.48 ms +1.58% -1.65% 257.86 ms +2.24% -1.2% 0.24%
largeJpegUploadProcessing 1501.28 ms +1.43% -0.58% 1495.3 ms +1.33% -0.38% 0.4%
multipleImageUploadProcessing 1684.34 ms +5.93% -2.27% 1673.76 ms +25.8% -1.41% 0.63%

post-editor

Metric 90cab26 trunk % Change
serverResponse 428.25 ms +3.85% -10.36% 409.81 ms +5.04% -8.11% 4.5%
firstPaint 414.85 ms +12.75% -4.05% 429.08 ms +3.25% -5.06% -3.32%
domContentLoaded 834.95 ms +1.69% -0.56% 830.96 ms +1.38% -0.55% 0.48%
loaded 836.16 ms +1.66% -0.57% 832.05 ms +1.41% -0.56% 0.49%
firstContentfulPaint 474.48 ms +1.74% -2.18% 472.08 ms +2.29% -3.14% 0.51%
firstBlock 2202.14 ms +1.11% -0.58% 2189.06 ms +1.04% -1.05% 0.6%
type 19.56 ms +9.3% -7.72% 19.88 ms +1.71% -5.28% -1.61%
typeWithoutInspector 19.84 ms +2.32% -11.9% 19.19 ms +9.28% -11.41% 3.39%
typeWithTopToolbar 24.68 ms +9.2% -6.97% 24.7 ms +6.28% -8.62% -0.08%
typeContainer 9.47 ms +2.43% -6.44% 8.45 ms +13.96% -6.27% 12.07%
focus 123.69 ms +5.03% -7.32% 121.29 ms +5% -4.66% 1.98%
firstFocus 260.58 ms +0% -0% 270.94 ms +0% -0% -3.82%
selectAll 384.05 ms +0.24% -1.77% 389.6 ms +6.65% -0.31% -1.42%
undo 33.08 ms +5.44% -7.56% 32.21 ms +7.58% -3.51% 2.7%
listViewOpen 80.08 ms +12.79% -5.33% 75.97 ms +7.62% -6.78% 5.41%
inserterOpen 45.49 ms +2.88% -10.73% 44.76 ms +2.19% -3.71% 1.63%
inserterHover 12.15 ms +10.53% -8.15% 12.89 ms +2.64% -14.97% -5.74%
inserterSearch 9.19 ms +0.87% -2.29% 8.61 ms +5.81% -3.48% 6.74%
loadPatterns 685.01 ms +3.93% -1.24% 703.74 ms +2.61% -6.13% -2.66%
wpTotal 416.96 ms +3.98% -10.53% 398.96 ms +5.15% -8.44% 4.51%
wpMemoryUsage 14.81 MB +0% -0% 14.77 MB +0% -0% 0.26%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 90cab26 trunk % Change
serverResponse 468.2 ms +0.65% -8.03% 465.62 ms +0.33% -7.75% 0.55%
firstPaint 417.7 ms +11.98% -8.4% 432.82 ms +4.36% -12.15% -3.49%
domContentLoaded 815 ms +4.11% -0.53% 806.68 ms +0.33% -1.93% 1.03%
loaded 815.96 ms +4.09% -0.52% 807.81 ms +0.29% -1.97% 1.01%
firstContentfulPaint 462.95 ms +1.2% -1.27% 450.99 ms +3.34% -1.09% 2.65%
firstBlock 2513.39 ms +2.96% -0.32% 2492.26 ms +1.24% -1% 0.85%
type 16.65 ms +12.01% -7.15% 16.67 ms +6.36% -10.26% -0.12%
navigate 109 ms +2.55% -6.86% 108.1 ms +3.61% -2.41% 0.83%
loadPatterns 1343.49 ms +6.23% -5.61% 1260.05 ms +8.69% -11.75% 6.62%
loadPages 956.09 ms +1.56% -2.35% 925.64 ms +1.77% -0.61% 3.29%
wpTotal 458.75 ms +0.56% -8.21% 456.22 ms +0.36% -7.92% 0.55%
wpMemoryUsage 12.82 MB +0% -0% 12.79 MB +0% -0% 0.27%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

29f07ad Run

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

As a user I want to be able to add multiple close buttons so that users can close the overlay from different positions in /test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js, passed after 1 failed attempt.
Error: expect(locator).toHaveCount(expected) failed

Locator:  getByRole('button', { name: 'Close' })
Expected: 2
Received: 1
Timeout:  5000ms

Call log:
  - Expect "toHaveCount" getByRole('button', { name: 'Close' }) with timeout 5000ms
  - waiting for getByRole('button', { name: 'Close' })
    14 × locator resolved to 1 element
       - unexpected value "1"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js:228:33
Undo restores the post selection when another synced entity is loaded in /test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 2
+ Received  + 2

  Object {
    "attributeKey": "content",
    "blockIndex": 0,
    "content": "abcdef",
-   "endOffset": 3,
-   "offset": 3,
+   "endOffset": 1,
+   "offset": 1,
  }

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts:363:5
does not select blocks in the canvas preview when editing from the sidebar (Site Editor v2) in /test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeVisible() failed

Locator: getByRole('listbox', { name: 'Search results' })
Expected: visible
Timeout: 5000ms
Error: element(s) not found

Call log:
  - Expect "toBeVisible" getByRole('listbox', { name: 'Search results' }) with timeout 5000ms
  - waiting for getByRole('listbox', { name: 'Search results' })

    at LinkControl.useLinkControlSearch (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js:423:33)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js:179:3

29f07ad Run

@andrewserong
andrewserong force-pushed the update/media-editor-file-placeholder-state branch from 88c5a2a to 2142947 Compare November 16, 2026 04:34
@andrewserong
andrewserong marked this pull request as ready for review November 16, 2026 05:19
@github-actions
github-actions Bot requested review from aduth and ciampo November 16, 2026 05:21
@andrewserong

Copy link
Copy Markdown
Contributor Author

@fcoveram just a non-urgent heads up about this PR. I'm gradually trying to build out the remaining features of the new media editor to fill in the gaps between the core media editor screen and this new experimental one.

This PR isn't very big, but is one piece: trying to create a pleasing default / preview state for those media files that cannot be previewed (e.g. ZIP files and the like).

We don't need to get everything right at the outset here as this route-based approach (and previewing non image media) is still behind an experiment, but I'm hoping that we can chip away at closing the gaps in functionality in the 7.3 cycle.

As always, open to any ideas / suggestions or going in a different direction with any of this 🙂

@andrewserong
andrewserong requested review from fcoveram and ramonjd and removed request for aduth and ciampo November 16, 2026 05:22
@andrewserong

Copy link
Copy Markdown
Contributor Author

And @aduth and @ciampo I've removed you as reviewers as this PR might be a false positive for your reviewer script as this is the media editor experiment rather than changes that affect the design system. That said, also happy for your feedback if you have opinions about how the media editor experiment should look! 🙂

@noruzzamans

Copy link
Copy Markdown
Member

Tested this locally on macOS (Chrome) using wp-env with a .zip file (application/zip):

  • The new card-based placeholder renders cleanly in the center of the canvas with accurate file details (filename, mime type, file size).
  • The Download button triggers file download smoothly.
  • The Copy URL button copies the attachment URL to the clipboard with the Copied URL to clipboard. snackbar notification.
  • Responsive layout and sidebar synchronization work properly.

Here is a short screen recording of the test:

Screen.Recording.2026-11-16.at.12.28.06.PM.mp4

LGTM! Great work @andrewserong 👍

@ciampo ciampo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's still interesting to witness how DS components get used in the editor! Left a couple of comments, although I agree we shouldn't be the main reviewers here :)

Comment on lines +288 to +292
<EmptyState.Actions className="media-editor-preview__error-actions">
<MediaPreviewFileActions
mediaUrl={ mediaUrl }
/>
</EmptyState.Actions>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should these actions wrap when the canvas is narrow? EmptyState.Actions switches to a non-wrapping row at a 480px viewport, so opening Details around 600px makes the error card overflow and clips its edges.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. I've updated the actions to wrap here, is this what you had in mind?

image

@aduth

aduth commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

And @aduth and @ciampo I've removed you as reviewers as this PR might be a false positive for your reviewer script as this is the media editor experiment rather than changes that affect the design system. That said, also happy for your feedback if you have opinions about how the media editor experiment should look! 🙂

I actually think it flagged pretty well here! Specifically, it scored high on design system patterns, since there's a "Copy to Clipboard" pattern that's relevant here. And specifically, there's some differences between the pattern's recommendations and what's implemented here:

  • Pattern: "Put the confirmation on the button [...] Don't use a snackbar here"
  • Pattern: "use its onError callback when the write fails" (not entirely sure when this happens!)
    • Implementation: Does not handle errors and provides no feedback
  • Pattern: "Use variant="minimal", tone="neutral", and size="compact": a copy action is rarely the primary button on the page"
    • Implementation: Uses a secondary button, but maybe this is a good case where the pattern shouldn't be so strict when buttons are used in a primary + secondary (solid + outline) arrangement like this. cc @jameskoster @simison

@jameskoster

Copy link
Copy Markdown
Contributor

I'm not sure this needs to be a card. Rendering an EmptyState on the page might be cleaner:

Screenshot 2026-11-16 at 15 31 05

Should the failure be a Notice?

@aduth yeah good point on the styling. I think it's okay for the button to inherit styling contextually from a pattern e.g. EmptyState.

andrewserong and others added 3 commits November 17, 2026 13:32
…e grey canvas

Drop the Card wrapper in favour of EmptyState with the folder icon for the
file info, error and empty states, and hide the canvas's grey background
when there's no preview. Let the actions wrap when the canvas is narrow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…in a new tab

Show the copy result on the Copy URL button and announce it with speak(),
instead of a snackbar, and handle copy failures. Open Download in a new tab,
so a cross-origin file that ignores the download attribute doesn't replace
the editor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@andrewserong andrewserong changed the title Media Editor: Add a card-based placeholder state with download and copy buttons Media Editor: Add a placeholder state with download and copy buttons Nov 17, 2026
@andrewserong

Copy link
Copy Markdown
Contributor Author

I actually think it flagged pretty well here! Specifically, it scored high on design system patterns, since there's a "Copy to Clipboard" pattern that's relevant here.

Oh glad to hear it, and I'm always grateful for the extra eyes 😄. Thanks for the extra context re: design system patterns, I hadn't seen that! Will double-check in future 👍

I've pushed some updates, and copied some of the approach from #85575 for the copy behaviour. It's a little duplicative since we're copying a pattern rather than reusing a component, but hopefully it's in the overall right direction. Here's how that's looking now:

2026-11-17.15.12.39.mp4

The above also ditches the grey canvas background for this placeholder state as suggested above. I've introduced the border for the sidebar to show only when we're hiding the grey canvas so that the edges are tidy for the image and video previews.

Should the failure be a Notice?

I went with the EmptyState for a couple of reasons: because this is a route it felt a bit more stable to me to have a proper empty state for the failure state and so that the URL can still be copied to help someone debug. It's an unlikely path to reach as it's the result of the source url itself being unable to be opened (but the attachment database record succeeds), so having the links handy could be useful in this case.


Thanks again for the feedback everyone, I think this is looking a lot better now! Happy to keep tweaking, but also this isn't an urgent PR as it's part of an ongoing experiment that's quite a long way away from being ready to land. That said, I'm enjoying building out these features and getting it in good shape as an eventual proposal for replacing the core screen.

@aduth

aduth commented Nov 17, 2026

Copy link
Copy Markdown
Member

Will double-check in future 👍

If you haven't already, setting up the design system's MCP server will get you this for free, since it instructs the agent to do this checking for you 😄

@andrewserong

Copy link
Copy Markdown
Contributor Author

If you haven't already, setting up the design system's MCP server will get you this for free, since it instructs the agent to do this checking for you 😄

Oh that's awesome. I had not, but I have now 😄

@aduth

aduth commented Nov 19, 2026

Copy link
Copy Markdown
Member

I'm not sure this needs to be a card. Rendering an EmptyState on the page might be cleaner:

I agree that EmptyState feels better visually here, though it does make me wonder if that could throw a wrench in how we think of EmptyState as being for empty states, as this isn't really an empty state. I might well be overthinking it, but perhaps there's a different way we should be thinking of the semantics of this kind of arrangement in terms of components or patterns.

And I recognize that this discussion should happen separately, and apologies to @andrewserong for derailing your pull request 😂 At the very least it turned out to be a great example of stress-testing the design system and its patterns!

Recognizing that this still needs an approving review though I'm not the best to give it in terms of my familiarity with this feature, is that something that @fcoveram and/or @ramonjd could provide, or would you be alright with a best-effort review from myself?

@andrewserong

Copy link
Copy Markdown
Contributor Author

This is all still behind an experiment so happy for a best effort review, but feel free to leave this PR for now! It can happily wait for @ramonjd until he's back from AFK. (I have plenty of other things to go on with so don't worry about me feeling blocked here 😄)

I might well be overthinking it, but perhaps there's a different way we should be thinking of the semantics of this kind of arrangement in terms of components or patterns.

I don't think you're overthinking it, and for this particular use case I think EmptyState is fine for now, but for this "molecule" (if I'm getting the design system language right) we've identified here a good use case that isn't empty per se, but is a similar kind of state. It's also not quite a placeholder (though I went with that word in the PR title as it's also not empty).

In any case the good news here is that it turns out the work that went into building out EmptyState resulted in a nice pattern that has more uses than just "empty"! 🙂

@jameskoster

jameskoster commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

@aduth I think it's a very good point. The take-away isn't clear to me though. The design is a common pattern that clearly has use outside of empty states, but adding a new component that shares 100% functionality doesn't seem ideal, and renaming would (I assume) be a breaking change... I'll open a new issue to discuss.

Edit: Opened #87142.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Feature] Media Anything that impacts the experience of managing media [Type] Enhancement A suggestion for improvement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants