Block Bindings: Preserve nested inner blocks when binding rich text

[cbravobernal]

Trac ticket: https://core.trac.wordpress.org/ticket/65406

Builds on @Sauliusv's #12084, which adds core/list-item to the supported binding attributes. This PR supersedes it: it keeps that registration and adds the render fix that makes the binding non-destructive (nested lists were dropped otherwise), plus tests. #12084 is closed in favor of this PR.

The problem, in one example

A List Item keeps its text and a nested list inside the same <li>:

<li>My text
  <ul class="wp-block-list"><li>Nested item</li></ul>
</li>

If you bind the list item's content attribute to a source, Block Bindings replaces everything inside <li> — and the nested list disappears:

<!-- Bound value: "Updated text" -->
<li>Updated text</li>   <!-- ❌ the nested list is gone -->

This happens because WP_Block::replace_html() replaces the whole element matched by the attribute's selector, with no awareness that part of that element is produced by inner blocks.

The fix

Stop the replacement at the first inner block.

A block's own rich text always comes before its inner blocks, so we only need to know where the first inner block begins:

<li>My text<ul ...>...</ul></li>
        ↑ replace up to here, keep the rest

WP_Block::render() already assembles the output by concatenating inner_content (own HTML + each inner block's rendered output). So it can record, for free, the byte offset where each inner block starts. Those offsets are passed to replace_rich_text(), which clamps the replacement to the first inner block inside the selector. An inner block that begins exactly at the rich-text start offset is treated as a boundary.

Result:

<li>Updated text<ul class="wp-block-list"><li>Nested item</li></ul></li>   <!-- ✅ -->

Why this approach

• Block-agnostic render path. The preservation logic contains zero list-item handling — it works from real block structure (the inner-block offsets), so it applies to any block that places an inner block inside a bound rich-text element. Enabling a specific block to bind rich text is then just a one-line entry in the supported-attributes map.
• Correct, not heuristic. Because it uses the actual inner-block positions, it naturally tells apart raw <ul> typed into the text (replaced, it's part of the rich text) from a real nested block (preserved). No tag-name guessing.
• No effect on existing blocks. Blocks without inner blocks pass an empty offset list, so the replacement behaves exactly as before.

What changed

• src/wp-includes/block-bindings.php — register content as a bindable attribute for core/list-item, the first Core block to bind rich text that contains an inner block.
• src/wp-includes/class-wp-block.php — record inner-block byte offsets during render(); pass them through replace_html() to replace_rich_text(), which stops at the first inner block inside the bound selector (boundary-inclusive), and document the $inner_block_offsets parameter.

Tests (tests/phpunit/tests/block-bindings/)

• test_rich_text_binding_preserves_nested_inner_blocks (data-driven, 6 fixtures) — fallback text before a nested list, raw markup before a nested list, an inner block that starts exactly at the rich-text boundary, multibyte fallback with a formatted bound value, a deep nested list with a surrounding sibling, and an ordered nested list with attributes. Each asserts the replaced strings are gone, the nested inner-block content is preserved, the exact rendered markup, and that the bound content attribute is updated.
• test_rich_text_binding_preserves_inner_blocks_for_any_block — an arbitrary registered block (rich text + an inner block in the same element) preserves its inner block too, proving there is no list-item special-casing in the render path.
• test_replace_rich_text_stops_at_inner_block_offset (in wp-block-get-block-bindings-processor.php) — direct unit test of the new $inner_block_offsets parameter: the replacement clamps at the recorded offset, preserving the markup that follows it.
• Plus a core/list-item case in the update-from-source data provider. The core/list-item registration itself is covered by that case end to end.

The render suite passes; the nested-list cases fail on trunk. --group block-bindings and --group blocks pass; PHPCS is clean.

Scope / notes

• Today core/list-item is the only Core block whose bound rich-text selector contains an inner block. Other Core blocks with multiple rich-text attributes (table, pullquote, file, quote, gallery) are not registered as bindable; and where they have inner blocks, the rich-text elements sit outside the inner-block content anyway, so enabling them later would not exercise different behavior.
• No Core block binds two rich-text attributes in the same element that also contains inner blocks, so offset invalidation across successive replacements isn't exercised; noted here in case such a block is added later.

Context

Unblocks the elegant version of the Gutenberg plugin feature in WordPress/gutenberg#78991, which currently needs a large compat workaround to preserve nested lists. With this change, that workaround can be removed for WordPress 7.1+.

Props

Original list-item supported-attribute registration and the companion Gutenberg work by @Sauliusv (#12084, WordPress/gutenberg#78991).

Use of AI Tools

Both Claude and Codex were used to help author the render fix and the expanded PHPUnit coverage, and to draft this description. All changes were reviewed locally and the full block-bindings/blocks suites were run before pushing.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props cbravobernal, jonsurrell.

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

[sirreal]

Code review

Note: This is an automated review generated by an AI agent (Claude Code, model Fable 5 / claude-fable-5), posted on behalf of @sirreal.

No high-confidence issues found. The core mechanism — recording byte offsets of inner blocks during render, clamping rich-text replacement at the first offset inside the matched element, and invalidating offsets once a replacement changes the markup — was checked for off-by-one errors, coordinate-space mismatches, stale-offset bugs, and regressions against the history of replace_html/replace_rich_text, and held up.

Two minor, non-blocking observations:

1. The replace_rich_text() docblock describes $inner_block_offsets as "Byte offsets in the source HTML", but the offsets are into the assembled $block_content string the processor was created from (as the corresponding comment in render() correctly states). Worth aligning the wording to avoid confusion with the serialized post content.

wordpress-develop/src/wp-includes/class-wp-block.php

Lines 451 to 456 in edac6d1

	* @param string $rich_text The rich text to replace the original content with.
	* @param int[] $inner_block_offsets Optional. Byte offsets in the source HTML where
	* inner blocks' rendered output begins. Default empty array.
	* @return bool True on success.
	*/
	public function replace_rich_text( $rich_text, $inner_block_offsets = array() ) {

2. In test_rich_text_binding_preserves_inner_blocks_for_any_block(), the remove_filter()/unregister_block_type() cleanup runs inline after $block->render(). If render() throws, test/rich-text-with-inner-blocks leaks into subsequent tests. Other test classes (e.g. tests/blocks/render.php) do this cleanup in tear_down().

wordpress-develop/tests/phpunit/tests/block-bindings/render.php

Lines 722 to 725 in edac6d1

	remove_filter( 'block_bindings_supported_attributes', $supported_attributes_filter, 10 );
	unregister_block_type( 'test/rich-text-with-inner-blocks' );

🤖 Generated with Claude Code (model: claude-fable-5)

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[sirreal]

I'm not very familiar with block bindings, but I'll try to provide helpful feedback.

Is it possible somehow to produce a list item child in the replacement? As noted in the comment, that difficult is why set_inner_html does not yet exist, because if an <li is inserted in <li>[[set this inner HTML]] <ul><li>nested</li></ul></li>, then the outside HTML structure is altered and the contract is broken. That's the main danger of working with something like an LI, <li><li> is two adjacent LI, not nested.

[sirreal]

Does this always hold? Specifically:

The block's own rich text always precedes its inner blocks, so replacing up to the first inner block offset replaces only that rich text.

Another way we might do this is to find all the text nodes from the block start to the first inner block and that becomes the replacement range. We could use a Tag Processor on that range to ensure that everything is, in fact, text.

[cbravobernal]

For core/list-item, yes. The block renders its innerContent in order: own rich-text first, then the inner-block placeholders. The offsets are recorded in that same render loop, so the first offset is probably where the rich text ends.

For an arbitrary block or manual markup, it's not guaranteed. I'll add a test.

On the Tag Processor idea

On finding the range by walking text nodes: the range isn't always text. It can contain raw block markup that should be replaced, right next to a real inner block that shouldn't, and they look identical once rendered. The offset is the only thing that knows which <ul> came from an actual inner block.

Still, I would need to add a test to be really sure about it.

[cbravobernal]

I'm not very familiar with block bindings, but I'll try to provide helpful feedback.

Is it possible somehow to produce a list item child in the replacement? As noted in the comment, that difficult is why set_inner_html does not yet exist, because if an <li is inserted in <li>[[set this inner HTML]] <ul><li>nested</li></ul></li>, then the outside HTML structure is altered and the contract is broken. That's the main danger of working with something like an LI, <li><li> is two adjacent LI, not nested.

Thanks for the review @sirreal ! You may not be block bindings familiar, but still a WordPress - HTML API expert 😄 .

Yes, it is possible. Is already also possible in paragraphs, headings and button, which is already happening since 6.5. I guess we consider block bindings a developer tool, and it's developer's risk to add unbalanced tags that could break different blocks.

Maybe is something we should work on on a different PR, so that way is only a fix for all blocks with this issue rather than coupling to this list-item only problem.