Fix flash when clicking template name in the editor when a plugin registered template matches a default WP theme template

[Aljullu]

What?

Fixes #65584.

Backport PR WordPress/wordpress-develop#7676.

Many themes (including TT4) have templates for specific post types (ie: page.html) but don't specify their postTypes in theme.json. That's because in some cases it's not needed (ie: page.html is automatically used for pages, single.html is automatically used for posts, etc.).

That caused the templates endpoint to filter out plugin-registered templates incorrectly. If the $query passed to the endpoint contained a post_type, theme templates that didn't explicitly match that post type would be ignored. So if a theme had a page.html and a plugin registered a page template, the one from the plugin would be used, which is incorrect.

In the UI, that caused a visual glitch when clicking on the Template setting in the post/page editor.

How?

Removing $query from _gutenberg_get_block_templates_files() so we get all templates, not only the ones matching the specific $post_type. When getting all templates from the theme, we can correctly filter out any duplicate coming from a plugin.

Testing Instructions

1. Add the following code to your site:

add_action( 'init', function() {
	register_block_template(
		'templates//page',
		[
			'title' => 'My Single Page',
			'description' => 'This is my single page template',
			'content' => '<!-- wp:paragraph --><p>This is a plugin-registered template.</p><!-- /wp:paragraph -->',
			'post_types' => [ 'page' ],
		]
	);
	register_block_template(
		'templates//single',
		[
			'title' => 'My Single Post',
			'description' => 'This is my single post template',
			'content' => '<!-- wp:paragraph --><p>This is a plugin-registered template.</p><!-- /wp:paragraph -->',
			'post_types' => [ 'post' ],
		]
	);
} );

2. Create a new page.
3. The Template setting should be set to "Pages".
4. Click on "Pages" and verify there is no flash.
5. Repeat with a post.

Screenshots or screencast

Enregistrament.de.pantalla.del.2024-10-23.10-13-53.webm

[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: Aljullu <aljullu@git.wordpress.org>
Co-authored-by: anton-vlasenko <antonvlasenko@git.wordpress.org>
Co-authored-by: colorful-tones <colorful-tones@git.wordpress.org>
Co-authored-by: ndiego <ndiego@git.wordpress.org>
Co-authored-by: getdave <get_dave@git.wordpress.org>
Co-authored-by: widoz <wido@git.wordpress.org>

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

[anton-vlasenko]

I've tested this PR according to the provided instructions, and it appears to resolve the flickering issue.
Please see my note below.
Thanks!

[anton-vlasenko]

If the issue is related to filtering templates by post_type, what if we try removing only the problematic post_type key instead of the entire $query array?
This might resolve the issue while maintaining relatively good performance, as it would remove the need to fetch all block template files.

What do you think, @Aljullu?

Suggested change

	$template_files = _gutenberg_get_block_templates_files( $template_type );
	// Inline comment explaining why the $query is not used.
	$template_files_query = $query;
	unset( $template_files_query['post_type'] );
	$template_files = _gutenberg_get_block_templates_files( $template_type, $template_files_query );

Additionally, adding an inline comment to explain why the query array isn’t passed to the _gutenberg_get_block_templates_files() function would make it easier to understand the code and reduce the risk of it being overwritten later.

[Aljullu]

Makes sense, I applied the changes in 1641d59.

[anton-vlasenko]

It would be nice to add a unit test to prevent this bug from reoccurring, but it’s not a blocker.

[Aljullu]

Good call, I added the tests directly to the backport PR in WordPress/wordpress-develop#7676. I'm happy to add tests in Gutenberg too, but I see there are no unit tests for this part of the codebase in Gutenberg, so I assumed it's better to write them in WordPress directly? What do you think? 🤔

[github-actions]

Flaky tests detected in f1ec716.
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/11571372008
📝 Reported issues:

• [Flaky Test] should handle the inserter outer section #38757 in /test/e2e/specs/widgets/customizing-widgets.spec.js

[Aljullu]

Thanks for the review, @anton-vlasenko! This is ready for another look, I also created the PR in WP core: WordPress/wordpress-develop#7676.

[anton-vlasenko]

Looks good to me. Great job!