Add wp_get_theme_data_custom_templates

[oandregal]

Part of WordPress/gutenberg#45171
Trac ticket: https://core.trac.wordpress.org/ticket/59137

What

This PR adds a new public function wp_get_theme_data_custom_templates to offer access to metadata stored under customTemplates in theme.json.

Why

There is a no public function to get access to that data, so consumers need to resort to private APIs. This follows the steps of wp_get_global_settings, wp_theme_has_theme_json, wp_get_theme_directory_pattern_slugs, and wp_get_theme_data_template_parts.

How

It creates a new function that uses the private calls and substitutes all the instances of the old one in the codebase.

How to test

TBD.

Commit message

Themes: add `wp_get_theme_data_custom_templates` function.

Adds a new public function, `wp_get_theme_data_custom_templates` that returns the `customTemplates` defined by the active theme from `theme.json`. It also substitutes the usage of private APIs by this new API.

Props johnbillion, audrasjb.
Fixes #59137

[johnbillion]

This function is missing a return statement and its @return tag is incorrect. Can you check and correct those please?

[oandregal]

This function is missing a return statement and its @return tag is incorrect. Can you check and correct those please?

Thanks, @johnbillion for catching the issue. Both things addressed.

[audrasjb]

Ah correct.
The change looks good to me, but we usually add a line break on long docblock sentences to avoid having too much characters on the same line

[oandregal]

The change looks good to me, but we usually add a line break on long docblock sentences to avoid having too much characters on the same line

Added the line break as well.

[oandregal]

Looking for how we do @return in other functions, I've noticed this #5033

[oandregal]

@johnbillion when you have the time, can you clear up the blocker so I can commit this?

[oandregal]

Committed at https://core.trac.wordpress.org/changeset/56413.