Block alignment: Explain when the template is what limits a block's w…

[jasmussen]

What?

Builds on #82607, and part of the width guidance discussed in #79285.

#82607 explains a width constraint when the block responsible is on the page. This does the same when it is the template.

Before:

After:

How?

Claude wrote this:

block-editor can already tell that the constraint comes from outside the post: useAlignmentConstraint returned null in exactly that case. What it cannot do is say what a template is, or navigate to one — those are not its concepts.

So the detection stays where it is and the explanation is passed down. A new private setting, outerWidthConstraintKey, carries a description and an action; packages/editor fills it in, since it is the layer that knows the template. When there is no template, no permission to edit it, or no way to navigate, the setting is undefined and the menu is unchanged.

This is the established shape for handing host knowledge to the block editor — sectionRootClientIdKey, mediaEditKey and openMediaEditorModalKey all pass data or callbacks the same way. It keeps the layering honest: block-editor never learns what a template is, and being private, it does not become API anyone depends on.

Two details worth calling out:

No new UI. The menu already renders a constraint with a description and an action, from #82607. This only supplies a second source for one, so the two cases are the same affordance rather than two designs that happen to look alike.

The shared-edit warning is raised here too. Navigating to a template from the Template panel, the template actions panel, or the classic-theme equivalents all dispatch "Editing template. Changes made here affect all posts and pages that use the template." That notice belongs to each call site rather than to onNavigateToEntityRecord, so leaving from this menu would otherwise have dropped it silently. Same string, same preference gate.

Testing Instructions

You need a block theme whose template limits width — the simplest is to switch off "Inner blocks use content width" on the Content block of the Pages template.

1. Edit a page. Select a block at the top level of the content, with no Group around it.
2. Open the alignment dropdown in the block toolbar.
3. Expected: Wide and Full listed as "Not available", then a separator, then "Edit Pages template" with the template's name and "The template limits this block's width."
4. Choose it. The editor should navigate to that template, and a snackbar should say changes affect all posts and pages that use it.
5. Repeat with "Show template" on. Same entry, since the Content block is not editable from there either.

Please also confirm it stays quiet where it should:

• Turn "Inner blocks use content width" back on. Wide and Full work, and the entry disappears.
• A block inside a Group that limits width. You should get Add/block width constraint notice #82607's entry naming the Group, not this one — the page block takes precedence, since it is the thing the user can actually reach.
• A user without permission to edit templates sees no entry.
• A classic theme, or a post with no template.

Testing Instructions for Keyboard

1. Select a top-level block and press Alt + F10 to reach the block toolbar.
2. Arrow to the alignment control and press Enter.
3. Arrow to the last item. It should announce as a menu item, not a radio, and read its description.
4. Press Enter. The editor navigates, and the snackbar is announced.

Use of AI Tools

Claude Opus 5.

[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: jasmussen <joen@git.wordpress.org>
Co-authored-by: scruffian <scruffian@git.wordpress.org>
Co-authored-by: aduth <aduth@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]

🤖 PR meta 🤖

📦 Bundle size

Size Change: +520 B (+0.01%)

Total Size: 8.01 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-editor/index.min.js	480 kB	+94 B (+0.02%)
build/scripts/editor/index.min.js	584 kB	+426 B (+0.07%)

_{315b92b Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	e70e12b	add/block-width-constraint-notice	% Change
timeToFirstByte	60.7 ms +9.8% -12.93%	63.95 ms +4.85% -7.43%	-5.08%
largestContentfulPaint	92 ms +4.35% -8.7%	96 ms +8.33% -4.17%	-4.17%
lcpMinusTtfb	30.7 ms +4.72% -4.07%	31.2 ms +28.37% -4.81%	-1.6%
wpBeforeTemplate	32.98 ms +5.15% -20.29%	32.86 ms +5.33% -10.68%	0.37%
wpTemplate	23.15 ms +2.68% -2.98%	23.87 ms +3.64% -3.6%	-3.02%
wpTotal	56.06 ms +9.31% -12.52%	58.53 ms +5.83% -6.92%	-4.22%
wpMemoryUsage	7.52 MB +0% -0%	7.52 MB +0% -0%	0.04%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	e70e12b	add/block-width-constraint-notice	% Change
timeToFirstByte	41.4 ms +9.9% -4.95%	40.3 ms +14.02% -2.85%	2.73%
largestContentfulPaint	86 ms +4.65% -2.33%	84 ms +9.52% -0%	2.38%
lcpMinusTtfb	44.5 ms +2.02% -2.47%	44.05 ms +1.93% -1.25%	1.02%
wpBeforeTemplate	23.74 ms +13.1% -3.92%	23.79 ms +17.53% -3.99%	-0.21%
wpTemplate	13.79 ms +5.29% -3.77%	13.32 ms +8.41% -1.65%	3.53%
wpTotal	38.28 ms +9.33% -4.94%	37.24 ms +13.67% -3.11%	2.79%
wpMemoryUsage	5.51 MB +0% -0%	5.50 MB +0% -0%	0.05%
wpDbQueries	14 +0% -0%	14 +0% -0%	0%

media-processing

Metric	e70e12b	add/block-width-constraint-notice	% Change
mediaProcessingJpeg	397.76 ms +0.61% -1.03%	396.18 ms +1.19% -0.85%	0.4%
mediaProcessingAvif	5828.94 ms +1% -0.24%	5867.98 ms +0.62% -0.48%	-0.67%
mediaProcessingJpegToAvif	4044.89 ms +1.4% -0.45%	4107.82 ms +0.33% -0.36%	-1.53%

media-upload

Metric	e70e12b	add/block-width-constraint-notice	% Change
jpegUploadProcessing	1690.4 ms +15.38% -15.44%	1423.83 ms +1.83% -0.1%	18.72%
pngUploadProcessing	202.68 ms +6.23% -3.09%	214.81 ms +5.88% -3.32%	-5.65%
largeJpegUploadProcessing	1407.18 ms +0.42% -0.52%	1423.01 ms +1.31% -1.35%	-1.11%
multipleImageUploadProcessing	1566.56 ms +0.66% -1.75%	1580.83 ms +7.08% -5.24%	-0.9%

post-editor

Metric	e70e12b	add/block-width-constraint-notice	% Change
serverResponse	523.03 ms +3.16% -6.5%	529.3 ms +3.78% -8.28%	-1.18%
firstPaint	252.22 ms +7.89% -11.22%	263.7 ms +38.85% -10.94%	-4.35%
domContentLoaded	1315.76 ms +0.63% -0.67%	1330.68 ms +1.78% -1.08%	-1.12%
loaded	1317.17 ms +0.63% -0.66%	1332.06 ms +1.77% -1.07%	-1.12%
firstContentfulPaint	433.4 ms +2.73% -2.55%	454.77 ms +2.81% -6.76%	-4.7%
firstBlock	3605.98 ms +0.34% -0.71%	3653.6 ms +1.25% -2.13%	-1.3%
type	15.8 ms +3.99% -2.91%	15.4 ms +8.44% -5.58%	2.6%
typeWithoutInspector	14.77 ms +2.98% -6.91%	15.54 ms +13.32% -8.43%	-4.95%
typeWithTopToolbar	18.08 ms +2.93% -8.46%	19.09 ms +1.99% -8.38%	-5.29%
typeContainer	8.89 ms +11.25% -2.92%	9.15 ms +12.13% -5.25%	-2.84%
focus	74.9 ms +26.02% -8.33%	79.99 ms +9.69% -9.86%	-6.36%
firstFocus	170.91 ms +0% -0%	172.15 ms +0% -0%	-0.72%
selectAll	606.69 ms +2.03% -1.78%	647.03 ms +2.33% -3.99%	-6.23%
listViewOpen	71.85 ms +17.36% -14.17%	71.45 ms +18.29% -11.48%	0.56%
inserterOpen	22.1 ms +7.51% -4.07%	23.18 ms +3.45% -11.78%	-4.66%
inserterHover	3.74 ms +2.14% -12.57%	3.81 ms +7.35% -8.66%	-1.84%
inserterSearch	8.89 ms +9% -5.96%	8.41 ms +15.34% -4.88%	5.71%
loadPatterns	630.98 ms +7.31% -3.35%	635.94 ms +1.82% -1.86%	-0.78%
wpTotal	513.44 ms +2.63% -6.62%	518.7 ms +3.97% -8.21%	-1.01%
wpMemoryUsage	13.05 MB +0% -0%	13.05 MB +0% -0%	0.02%
wpDbQueries	54 +0% -1.85%	54 +0% -1.85%	0%

site-editor

Metric	e70e12b	add/block-width-constraint-notice	% Change
serverResponse	497.87 ms +2.7% -2.25%	500.74 ms +4.46% -7.13%	-0.57%
firstPaint	283.79 ms +15.63% -9.27%	253.23 ms +12.77% -13.63%	12.07%
domContentLoaded	1402.88 ms +1.17% -1.12%	1400.84 ms +0.52% -0.48%	0.15%
loaded	1404.05 ms +1.19% -1.11%	1402.16 ms +0.51% -0.46%	0.13%
firstContentfulPaint	432.74 ms +4.49% -3.39%	433.85 ms +2.71% -1.02%	-0.26%
firstBlock	4460.69 ms +1.73% -0.78%	4505.37 ms +0.37% -0.16%	-0.99%
type	15.6 ms +1.6% -4.81%	14.52 ms +10.06% -3.1%	7.44%
navigate	103.47 ms +3.6% -2.63%	106.5 ms +6.47% -10.61%	-2.85%
loadPatterns	1299.68 ms +18.33% -8.17%	1600.78 ms +0.64% -6.77%	-18.81%
loadPages	1088.61 ms +2.14% -5.56%	1124.39 ms +7.21% -3.59%	-3.18%
wpTotal	488.05 ms +2.88% -2.38%	491.17 ms +4.44% -7.22%	-0.64%
wpMemoryUsage	12.06 MB +0% -0%	12.06 MB +0% -0%	0.02%
wpDbQueries	43 +2.33% -0%	43 +2.33% -0%	0%

_{315b92b Run}

[scruffian]

I followed the testing instructions, but I can't get the message to show, sorry. What theme are you using?

[scruffian]

I think we should be using getTemplateInfo, which will display the name of the template, rather than title?rendered which will show the slug.

[scruffian]

Should we add a back action, like we do for other snackbars?

[jasmussen]

Thanks for the reviews, Ben. I tried to address it best as I could. If I read it right, you surfaced an issue I will apply in one of the other PRs as well.

On reproduction steps, the first catch may be why you couldn't reproduce it. As my Claude suggests:

• It was reading title.rendered off the template record. For a template nobody has renamed, that's empty or just the slug, and it was also gating the whole feature on having a title, so it silently rendered nothing.
• Now it uses getTemplateInfo as you suggested, so the name falls back to what the theme calls the template.

Try these new steps to repro:

1. Use a block theme that supports wide and full alignments, e.g. Twenty Twenty-Five.
2. Go to Appearance → Editor → Templates → Pages, select the Content block, and in Layout switch off "Inner blocks use content width". Save.
3. Edit any page. Add an image at the top level of the content — not inside a Group or Columns.
4. Select it and open the alignment dropdown in the block toolbar.

Expected: Wide and Full are listed as "Not available", then a separator, then Edit Pages template, with "The template limits this block's width." Choosing it navigates to that template and raises a snackbar with a Back action.

[aduth]

Hey 👋 I wanted to give you a heads-up since this pull request is affected by recent validation changes for changelog files.

#83043 adds additional validation for changelog files. You'll note that this pull request is currently failing a "Required changes from trunk" check.

What you'll need to do: You will need to either rebase or merge the latest code from trunk. In addition, a cursory review of open pull requests identified this pull request as potentially failing under the new validation checks. You will want to double-check that any changes to CHANGELOG.md files follow the Maintaining Changelogs guidance, which has been improved as part of these recent changes.

[jasmussen]

This is now dependant on #83955.