Add documentation and schema for contentRole block support

[t-hamano]

What? Why?

The contentRole support, newly added in version 6.9, has been added to many core blocks. This block support is working very well and can essentially be considered a stable API. Let's document this API.

How?

Welcome your feedback on how we can provide a better explanation!

Testing Instructions

Nothing.

[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: t-hamano <[email protected]>
Co-authored-by: fabiankaegy <[email protected]>

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

[fabiankaegy]

I think this is a good addition. However I wonder if we can be a little more specific as to where this actually gets used. Because setting a group to templateLock: contentOnly for example doesn't trigger this mode which is what I would have expected.

Would love to get more clarity on this from these docs :)

[t-hamano]

@fabiankaegy Thanks for the feedback!

Because setting a group to templateLock: contentOnly for example doesn't trigger this mode which is what I would have expected.

Could you provide more details on this point? It works as expected in my tests.

The HTML I used for testing is as follows:

<!-- wp:group {"templateLock":"contentOnly","layout":{"type":"constrained"}} -->
<div class="wp-block-group">
	<!-- wp:accordion -->
	<div role="group" class="wp-block-accordion">
		<!-- wp:accordion-item -->
		<div class="wp-block-accordion-item">
			<!-- wp:accordion-heading -->
			<h3 class="wp-block-accordion-heading"><button class="wp-block-accordion-heading__toggle"><span class="wp-block-accordion-heading__toggle-title">Accordion Title</span><span class="wp-block-accordion-heading__toggle-icon" aria-hidden="true">+</span></button></h3>
			<!-- /wp:accordion-heading -->

			<!-- wp:accordion-panel {"isSelected":true} -->
			<div role="region" class="wp-block-accordion-panel">
				<!-- wp:paragraph -->
				<p>Accordion Content</p>
				<!-- /wp:paragraph -->
			</div>
			<!-- /wp:accordion-panel -->
		</div>
		<!-- /wp:accordion-item -->
	</div>
	<!-- /wp:accordion -->
</div>
<!-- /wp:group -->

[fabiankaegy]

Ahh yeah I meant that it doesn't allow new items like lost items to be added:

#52018 (comment)

Which in theory is also tied to this block support

[t-hamano]

Ahh yeah I meant that it doesn't allow new items like lost items to be added:

I see. Until this problem is resolved, it might be best not to add any more schemas or documents 🤔

[fabiankaegy]

Yeah I feel like that would be better... Or adding a notice that this is only for WordPress 7.0? Not sure.

[t-hamano]

Ahh yeah I meant that it doesn't allow new items like lost items to be added:

I see. Until this problem is resolved, it might be best not to add any more schemas or documents 🤔

Based on this, let's close this pull request for now. We can reconsider updating the documentation and schema in version 7.0.