Webfonts: register and enqueue fonts by font-family (#39559)

* Group registered webfonts by font family

* Add registered font-family groups to theme.json

* Separate between registering and enqueueing webfonts

* Add wp_enqueue_webfont method

* Fix wp_register_webfont description

* Do not duplicate font families if registering from both theme.json and API

* Rename font to webfont where appropriate

* Add tests

* Fix linter offenses

* Fire gutenberg_register_webfonts_from_theme_json on init

* Move webfonts logic from wordpress-6.0 to experimental

The API, although looking really good, is not ready for Core.
So we must move it from wordpress-6.0 to experimental,
and only add it there when it's ready to enter WordPress.

Relocate files to /lib/experimental.

Per the Gutenberg PHP > File structure documentation
https://github.com/WordPress/gutenberg/tree/trunk/lib#file-structure.

* Update return types and comment for consistency and matching.

* Use trigger_log instead of error_log().

* Fix tests with _doing_it_wrong.

Tests for methods that have a `_doing_it_wrong()` require
an `expectedIncorrectUsage` annotation, proper usage of test fixture methods,
and the usage of `__METHOD__` when invoking `_doing_it_wrong()`.

This commit:

- Fixes the test fixtures to use snake_case format and calling of the parent fixtures.
- Refactors `get_font_slug()` tests into data providers (preferred in Core) and separates tests that will trigger `_doing_it_wrong()` to use the annotation.
- Uses `__METHOD__` instead of `__FUNCTION__` in each `_doing_it_wrong()` instance.

* Add `get_webfonts_by_provider()` method to handle regrouping.

The `WP_Webfonts::generate_styles()` should not be aware of how to
reorganize the webfonts from grouped by font-family to grouped by
provider. Why? This is a separate task from generating styles for
the webfonts.

This commit creates a private method called `get_webfonts_by_provider()`
to encapsulate the know-how for this reorganizational work.

It also includes a micro-optimization that eliminates an extra
`foreach` loop and the building of an unnecessary `$webfonts`
array of arrays.

* Updates from code review.

* Restore loading lib/compat/wordpress-6.0/class-wp-theme-json-gutenberg.php.

Co-authored-by: Jeremy Yip <jeremy.yip@automattic.com>
Co-authored-by: hellofromtonya <tonya.mork@automattic.com>

lib/compat/wordpress-6.0/class-wp-theme-json-resolver-6-0.php

@@ -0,0 +1,64 @@
+<?php
+/**
+ * WP_Theme_JSON_Resolver_6_0 class
+ *
+ * @package gutenberg
+ */
+
+/**
+ * Class that abstracts the processing of the different data sources
+ * for site-level config and offers an API to work with them.
+ *
+ * This class is for internal core usage and is not supposed to be used by extenders (plugins and/or themes).
+ * This is a low-level API that may need to do breaking changes. Please,
+ * use get_global_settings, get_global_styles, and get_global_stylesheet instead.
+ *
+ * @access private
+ */
+class WP_Theme_JSON_Resolver_6_0 extends WP_Theme_JSON_Resolver_5_9 {
+	/**
+	 * Given a theme.json structure modifies it in place
+	 * to update certain values by its translated strings
+	 * according to the language set by the user.
+	 *
+	 * @param array  $theme_json The theme.json to translate.
+	 * @param string $domain     Optional. Text domain. Unique identifier for retrieving translated strings.
+	 *                           Default 'default'.
+	 * @return array Returns the modified $theme_json_structure.
+	 */
+	protected static function translate( $theme_json, $domain = 'default' ) {
+		if ( null === static::$i18n_schema ) {
+			$i18n_schema         = wp_json_file_decode( __DIR__ . '/theme-i18n.json' );
+			static::$i18n_schema = null === $i18n_schema ? array() : $i18n_schema;
+		}
+
+		return wp_translate_settings_using_i18n_schema( static::$i18n_schema, $theme_json, $domain );
+	}
+
+	/**
+	 * Returns the style variations defined by the theme.
+	 *
+	 * @return array
+	 */
+	public static function get_style_variations() {
+		$variations     = array();
+		$base_directory = get_stylesheet_directory() . '/styles';
+		if ( is_dir( $base_directory ) ) {
+			$nested_files      = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $base_directory ) );
+			$nested_html_files = iterator_to_array( new RegexIterator( $nested_files, '/^.+\.json$/i', RecursiveRegexIterator::GET_MATCH ) );
+			ksort( $nested_html_files );
+			foreach ( $nested_html_files as $path => $file ) {
+				$decoded_file = wp_json_file_decode( $path, array( 'associative' => true ) );
+				if ( is_array( $decoded_file ) ) {
+					$translated = static::translate( $decoded_file, wp_get_theme()->get( 'TextDomain' ) );
+					$variation  = ( new WP_Theme_JSON_Gutenberg( $translated ) )->get_raw_data();
+					if ( empty( $variation['title'] ) ) {
+						$variation['title'] = basename( $path, '.json' );
+					}
+					$variations[] = $variation;
+				}
+			}
+		}
+		return $variations;
+	}
+}