Dynamic Gallery: Rename toolbar button to Detach and add a modal explaining what will happen

[andrewserong]

What?

Fixes #80613

The Dynamic mode of the gallery block (the Dynamic Gallery variation) has an ambiguous "Convert to images" button in the block toolbar. As discussed in #80613 this can be confusing to users, and it also doesn't accurately reflect what's really going to happen.

This PR tries out ideas discussed in that issue: let's try renaming the button to Detach and add a confirm dialog that helps explain what will happen.

Very happy for feedback and ideas on the wording! Right now I've borrowed from @ramonjd's mockups.

Why?

The block can operate in two modes: dynamic mode connected to a source, and a static mode where the block isn't attached to a source and is made up of editable inner blocks. The two modes provide powerful behaviour (at least I think so), but it's also difficult to understand.

Hopefully, the button and modal can help users learn how to interact with the gallery block in each of its states, and also with this change, we hopefully reduce some confusion.

How?

• Add an additional confirm dialog and state to the dynamic mode of the gallery block
• When a user clicks "Detach" trigger the modal instead of immediately switching to a static version of the gallery block

Testing Instructions

• Upload a bunch of images to a post or page (or attach them manually via the media library)
• Insert a Gallery block to the page and select "Use attached images" to switch to the dynamic mode
• Try out the "Detach" button in the block toolbar or the "Detach gallery" button in the inspector sidebar
• How does the text read / look / feel? Does it make sense?
• Click to confirm the detach. And make sure it otherwise works as on trunk.

Screenshots or screencast

This screenshot includes the three changes:

• Block toolbar button copy change (it now says Detach)
• Inspector controls button copy change (it now says Detach gallery)
• The new modal

Use of AI Tools

Claude Code (Opus 5) for making the initial change, with testing and a little tweaking by me.

[github-actions]

Size Change: +237 B (0%)

Total Size: 7.75 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-library/index.min.js	356 kB	+237 B (+0.07%)

_{compressed-size-action}

[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: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: bph <bph@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: fcoveram <fcoveram@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>

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

[github-actions]

Flaky tests detected in 5857f08.
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.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/30332099419
📝 Reported issues:

• [Flaky Test] Should navigate inner blocks with arrow keys #39607 in /test/e2e/specs/editor/various/writing-flow.spec.js
• [Flaky Test] persists table layout across all tabs with unified view persistence #80156 in /test/e2e/specs/site-editor/pages-view-persistence.spec.js

[jasmussen]

I like it! It feels like it explains quite well, even if after the fact, what this is. How do you feel about it?

Nit, I'd love if this could be a small dialog rather than be medium sized. We can potentially make the text shorter if that helps. I do like how you emulated detaching from the page list, but perhaps we can trim it. Instead of:

Detach gallery?

The gallery displays the images attached to the post. Detaching will enable you to add, delete, or reorder images. However newly attached images will no longer be added automatically.

[Cancel] [Detach]

Perhaps we could:

Detach Gallery

This gallery displays your post's attachments. Detaching will enable you to add, delete, or reorder images. However, new attachments will no longer be added automatically.

[Cancel] [Detach]

Well, barely shorter. Up to you!

[Mamaduka]

Nit, I'd love if this could be a small dialog rather than be medium sized.

I thought all confirmation dialogs were the same size.

[jasmussen]

Could be my mistake, it just looked wider in the screenshot. You can safely ignore me if that's not the case.

[fcoveram]

From Joen's idea shared here, I like the body of the second but without shrinking the "images attached to the post" part, and the heading of the first. Therefore…

Detach gallery?

The gallery displays the images attached to the post. Detaching will enable you to add, delete, or reorder images. However, new attachments will no longer be added automatically.

[Cancel] [Detach]

[jasmussen]

A note, "Detach Gallery" vs. "Detach gallery?"—the reason I proposed the former is that when you click Edit on a Page List inside the navigation block, it asks: "Edit Page List". Neutrally and matter of factly, and referring to the block name with capital letters. It's not strongly felt, just context.

[bph]

This works very nicely. As attached images are a fairly complex concept for end users, I would keep the explanation as is and not assume too much knowledge from the content creators.

The gallery displays the images attached to the post. Detaching it will enable you to add, delete, or reorder images. However, newly attached images will no longer be added automatically.

Great work. The "Detach" verb has been in use in the Media Library for a while.

🤦‍♀️ BTW: Although I have been using WordPress since 2009, I was not aware of the feature that I could attach images to posts from there.

[bph]

LGTM - Not that my approval does anything. See also my separate comment.

[andrewserong]

Thanks for the feedback, folks! I've updated the heading and sidebar buttons to use a capital G and updated the modal body wording to match Francisco's redrafting (#80727 (comment)). Here's how it's looking:

LGTM - Not that my approval does anything. See also my separate comment.

It's worth a lot to me, thank you! 😄

[Mamaduka]

Looks great 🚢

[ramonjd]

LGTM - general poll:

should we align table of contents/page list with this pattern for 7.1 or leave it for now?

my gut instinct is to do it in GB, but not force it through to 7.1.

[andrewserong]

should we align table of contents/page list with this pattern for 7.1 or leave it for now?
my gut instinct is to do it in GB, but not force it through to 7.1.

Good question. I think we could do it in GB but not force it through for 7.1. While aligning them all is a good idea, it feels a bit beyond the scope of polishing the Dynamic Gallery block (which is a 7.1 feature).

[github-actions]

There was a conflict while trying to cherry-pick the commit to the wp/7.1 branch. Please resolve the conflict manually and create a PR to the wp/7.1 branch.

PRs to wp/7.1 are similar to PRs to trunk, but you should base your PR on the wp/7.1 branch instead of trunk.

# Checkout the wp/7.1 branch instead of trunk.
git checkout wp/7.1

# Create a new branch for your PR.
git checkout -b my-branch

# Cherry-pick the commit.
git cherry-pick 794b6778f11aca2cbc4b3a4431f427cfcc73b17e

# Check which files have conflicts.
git status

# Resolve the conflict...
# Add the resolved files to the staging area.
git status
git add .
git cherry-pick --continue

# Push the branch to the repository
git push origin my-branch

# Create a PR and set the base to the wp/7.1 branch.
# See https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-base-branch-of-a-pull-request.

[andrewserong]

I've opened a manual backport to the wp/7.1 branch over in #80774