Skip to content

Cover: Create the initial paragraph when the block gains a background#80028

Open
ellatrix wants to merge 5 commits into
trunkfrom
add/cover-content-on-background
Open

Cover: Create the initial paragraph when the block gains a background#80028
ellatrix wants to merge 5 commits into
trunkfrom
add/cover-content-on-background

Conversation

@ellatrix

@ellatrix ellatrix commented Jul 8, 2026

Copy link
Copy Markdown
Member

What?

Creates the Cover block's initial inner paragraph in the actions that give the block a background (selecting media, choosing an overlay color, enabling the featured image), instead of declaring it as an inner blocks template.

Why?

  1. The template only ever applied on placeholder exit. Cover's placeholder branch returns early without rendering the inner blocks container, so the template hook never ran until a background was chosen. Creating the paragraph in those actions encodes the actual behavior directly.
  2. Collaboration correctness. Template insertion runs independently on every peer after mount; a user action runs only on the acting client, so peers receive the background and the paragraph together (see RTC: Fix inner template multiple insertion #79021 for the general problem).
  3. Removes the Cover: Avoid content loss when the templateLock value is all or contentOnly #45632 guard. The conditional template prop existed to avoid re-synchronizing locked content; with no template there is nothing to guard.

How?

A scaffoldInnerBlocks() helper inserts the paragraph (with the existing fontSize handling from #34993) when the inner blocks are empty, called from onSelectMedia, onSetOverlayColor, and toggleUseFeaturedImage. The block transforms already create the paragraph explicitly.

One behavior change: a saved empty Cover that already has a background no longer gains a paragraph when the post is opened; it shows the block appender instead.

Testing Instructions

  1. Insert a Cover block; the media/color placeholder appears as before.
  2. Pick an overlay color or upload media; the title paragraph appears focused, type into it.
  3. Transform an image into a Cover; the caption paragraph is present.
  4. Undo after picking a color; the paragraph and background revert together.

Testing Instructions for Keyboard

Insert a Cover, Tab to a color swatch in the placeholder, press Enter, and type the title.

🤖 Generated with Claude Code

The initial inner paragraph was declared as an inner blocks template,
applied only once the inner container rendered, which happens when the
placeholder is exited. Create the paragraph explicitly in the actions
that give the block a background instead: selecting media, choosing an
overlay color, and enabling the featured image.

Because the paragraph is created by the acting client as part of the
user action, collaboration peers receive the background and the
paragraph together instead of each applying the template themselves.
The block transforms already create the paragraph explicitly.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jul 8, 2026

Copy link
Copy Markdown

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: ellatrix <ellatrix@git.wordpress.org>
Co-authored-by: jsnajdr <jsnajdr@git.wordpress.org>
Co-authored-by: youknowriad <youknowriad@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

github-actions Bot commented Jul 8, 2026

Copy link
Copy Markdown

Size Change: +134 B (0%)

Total Size: 7.67 MB

📦 View Changed
Filename Size Change
build/scripts/block-library/index.min.js 333 kB +134 B (+0.04%)

compressed-size-action

@ellatrix ellatrix added the [Type] Code Quality Issues or PRs that relate to code quality label Jul 8, 2026
ellatrix and others added 4 commits July 8, 2026 15:37
The initial paragraph is created in the same store batch as the
background attribute changes, so the change reaches the entity, undo
history, and collaboration peers as a single operation. The paragraph
is part of the persistent user action, so it is no longer marked as a
non-persistent change.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The calling actions can also remove the background, so instead of
per-call-site guards, the scaffold reads the updated attributes inside
the batch and only creates the paragraph when the block has a
background. This also covers combinations the guards missed, such as
disabling the featured image while a custom overlay color remains.

Resolve the font sizes with the block settings selector inside the
scaffold, so they are only read when a paragraph is actually created.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The template was only ever applied at the placeholder exit transition:
the placeholder branch does not render the inner blocks container, so
the template sync never ran until a background was chosen, and its
template reference prevented re-application afterwards. Removing the
initial paragraph is a content choice that later background changes
should not override, so the scaffold requires the placeholder to have
been showing when the action started, in addition to the block having
a background and no content when it completes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The color and featured image actions also run when a background is
removed, where an inserted paragraph would prevent the placeholder
from rendering again, since it requires empty content. Guarding those
two call sites on their new value is sufficient; drop the placeholder
transition tracking.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jul 8, 2026

Copy link
Copy Markdown

Flaky tests detected in 320bd1b.
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/28982004957
📝 Reported issues:

@youknowriad

Copy link
Copy Markdown
Contributor

I feel like this makes the code of the block more fragile and prone to error as we iterate on the block. That said, I'm wondering, is there a way to use a static template here and still have the block show a placeholder in some occasions?

@ellatrix

Copy link
Copy Markdown
Member Author

True, let me try it

@ellatrix

Copy link
Copy Markdown
Member Author

Ok if we set the template and show a placeholder anyway, the only issue is that when you set a background etc., we'll have to set selection manually afterwards to the paragraph.

@youknowriad

Copy link
Copy Markdown
Contributor

Ok if we set the template and show a placeholder anyway, the only issue is that when you set a background etc., we'll have to set selection manually afterwards to the paragraph.

I feel like this behavior is the right one for a cover, I could be wrong though.

@ellatrix

Copy link
Copy Markdown
Member Author

@youknowriad It would look something like this (based on top of the main PR): #80120

@ellatrix

Copy link
Copy Markdown
Member Author

I'm honestly also wondering if the empty paragraph shouldn't just be an appender. Tbh, it would be good to redesign the "default" appender to actually render a real (unmaterialised) paragraph block instead of a fake paragraph. That way the default appender could also be configured to take any default attributes such as font size and we wouldn't have to do this whole template thing.

@youknowriad

Copy link
Copy Markdown
Contributor

I'm honestly also wondering if the empty paragraph shouldn't just be an appender.

I kind of agree, can we try it and see how it feels?

@jsnajdr jsnajdr left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Looks good 👍 It's also nice that this PR replaces the old templateLock workaround from #45632.

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

Labels

[Package] Block library /packages/block-library [Type] Code Quality Issues or PRs that relate to code quality

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants