m string $file_name Name of the file.
	 * @param bool   $template  Optional. Use template theme directory. Default false.
	 * @return string The whole file path or empty if the file doesn't exist.
	 */
	protected static function get_file_path_from_theme( $file_name, $template = false ) {
		$path      = $template ? get_template_directory() : get_stylesheet_directory();
		$candidate = $path . '/' . $file_name;

		return is_readable( $candidate ) ? $candidate : '';
	}

	/**
	 * Cleans the cached data so it can be recalculated.
	 *
	 * @since 5.8.0
	 * @since 5.9.0 Added the `$user`, `$user_custom_post_type_id`,
	 *              and `$i18n_schema` variables to reset.
	 * @since 6.1.0 Added the `$blocks` and `$blocks_cache` variables
	 *              to reset.
	 */
	public static function clean_cached_data() {
		static::$core                     = null;
		static::$blocks                   = null;
		static::$blocks_cache             = array(
			'core'   => array(),
			'blocks' => array(),
			'theme'  => array(),
			'user'   => array(),
		);
		static::$theme                    = null;
		static::$user                     = null;
		static::$user_custom_post_type_id = null;
		static::$i18n_schema              = null;
	}

	/**
	 * Returns an array of all nested JSON files within a given directory.
	 *
	 * @since 6.2.0
	 *
	 * @param string $dir The directory to recursively iterate and list files of.
	 * @return array The merged array.
	 */
	private static function recursively_iterate_json( $dir ) {
		$nested_files      = new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $dir ) );
		$nested_json_files = iterator_to_array( new RegexIterator( $nested_files, '/^.+\.json$/i', RecursiveRegexIterator::GET_MATCH ) );
		return $nested_json_files;
	}

	/**
	 * Determines if a supplied style variation matches the provided scope.
	 *
	 * For backwards compatibility, if a variation does not define any scope
	 * related property, e.g. `blockTypes`, it is assumed to be a theme style
	 * variation.
	 *
	 * @since 6.6.0
	 *
	 * @param array  $variation Theme.json shaped style variation object.
	 * @param string $scope     Scope to check e.g. theme, block etc.
	 * @return boolean
	 */
	private static function style_variation_has_scope( $variation, $scope ) {
		if ( 'block' === $scope ) {
			return isset( $variation['blockTypes'] );
		}

		if ( 'theme' === $scope ) {
			return ! isset( $variation['blockTypes'] );
		}

		return false;
	}

	/**
	 * Returns the style variations defined by the theme.
	 *
	 * @since 6.0.0
	 * @since 6.2.0 Returns parent theme variations if theme is a child.
	 * @since 6.6.0 Added configurable scope parameter to allow filtering
	 *              theme.json partial files by the scope to which they
	 *              can be applied e.g. theme vs block etc.
	 *              Added basic caching for read theme.json partial files.
	 *
	 * @param string $scope The scope or type of style variation to retrieve e.g. theme, block etc.
	 * @return array
	 */
	public static function get_style_variations( $scope = 'theme' ) {
		$variation_files    = array();
		$variations         = array();
		$base_directory     = get_stylesheet_directory() . '/styles';
		$template_directory = get_template_directory() . '/styles';
		if ( is_dir( $base_directory ) ) {
			$variation_files = static::recursively_iterate_json( $base_directory );
		}
		if ( is_dir( $template_directory ) && $template_directory !== $base_directory ) {
			$variation_files_parent = static::recursively_iterate_json( $template_directory );
			// If the child and parent variation file basename are the same, only include the child theme's.
			foreach ( $variation_files_parent as $parent_path => $parent ) {
				foreach ( $variation_files as $child_path => $child ) {
					if ( basename( $parent_path ) === basename( $child_path ) ) {
						unset( $variation_files_parent[ $parent_path ] );
					}
				}
			}
			$variation_files = array_merge( $variation_files, $variation_files_parent );
		}
		ksort( $variation_files );
		foreach ( $variation_files as $path => $file ) {
			$decoded_file = self::read_json_file( $path );
			if ( is_array( $decoded_file ) && static::style_variation_has_scope( $decoded_file, $scope ) ) {
				$translated = static::translate( $decoded_file, wp_get_theme()->get( 'TextDomain' ) );
				$variation  = ( new WP_Theme_JSON( $translated ) )->get_raw_data();
				if ( empty( $variation['title'] ) ) {
					$variation['title'] = basename( $path, '.json' );
				}
				$variations[] = $variation;
			}
		}
		return $variations;
	}

	/**
	 * Resolves relative paths in theme.json styles to theme absolute paths
	 * and returns them in an array that can be embedded
	 * as the value of `_link` object in REST API responses.
	 *
	 * @since 6.6.0
	 *
	 * @param WP_Theme_JSON $theme_json A theme json instance.
	 * @return array An array of resolved paths.
	 */
	public static function get_resolved_theme_uris( $theme_json ) {
		$resolved_theme_uris = array();

		if ( ! $theme_json instanceof WP_Theme_JSON ) {
			return $resolved_theme_uris;
		}

		$theme_json_data = $theme_json->get_raw_data();

		// Top level styles.
		$background_image_url = isset( $theme_json_data['styles']['background']['backgroundImage']['url'] ) ? $theme_json_data['styles']['background']['backgroundImage']['url'] : null;

		/*
		 * The same file convention when registering web fonts.
		 * See: WP_Font_Face_Resolver::to_theme_file_uri.
		 */
		$placeholder = 'file:./';
		if (
			isset( $background_image_url ) &&
			is_string( $background_image_url ) &&
			// Skip if the src doesn't start with the placeholder, as there's nothing to replace.
			str_starts_with( $background_image_url, $placeholder )
		) {
			$file_type          = wp_check_filetype( $background_image_url );
			$src_url            = str_replace( $placeholder, '', $background_image_url );
			$resolved_theme_uri = array(
				'name'   => $background_image_url,
				'href'   => sanitize_url( get_theme_file_uri( $src_url ) ),
				'target' => 'styles.background.backgroundImage.url',
			);
			if ( isset( $file_type['type'] ) ) {
				$resolved_theme_uri['type'] = $file_type['type'];
			}
			$resolved_theme_uris[] = $resolved_theme_uri;
		}

		return $resolved_theme_uris;
	}

	/**
	 * Resolves relative paths in theme.json styles to theme absolute paths
	 * and merges them with incoming theme JSON.
	 *
	 * @since 6.6.0
	 *
	 * @param WP_Theme_JSON $theme_json A theme json instance.
	 * @return WP_Theme_JSON Theme merged with resolved paths, if any found.
	 */
	public static function resolve_theme_file_uris( $theme_json ) {
		$resolved_urls = static::get_resolved_theme_uris( $theme_json );
		if ( empty( $resolved_urls ) ) {
			return $theme_json;
		}

		$resolved_theme_json_data = array(
			'version' => WP_Theme_JSON::LATEST_SCHEMA,
		);

		foreach ( $resolved_urls as $resolved_url ) {
			$path = explode( '.', $resolved_url['target'] );
			_wp_array_set( $resolved_theme_json_data, $path, $resolved_url['href'] );
		}

		$theme_json->merge( new WP_Theme_JSON( $resolved_theme_json_data ) );

		return $theme_json;
	}

	/**
	 * Adds variations sourced from block style variations files to the supplied theme.json data.
	 *
	 * @since 6.6.0
	 *
	 * @param array $data       Array following the theme.json specification.
	 * @param array $variations Shared block style variations.
	 * @return array Theme json data including shared block style variation definitions.
	 */
	private static function inject_variations_from_block_style_variation_files( $data, $variations ) {
		if ( empty( $variations ) ) {
			return $data;
		}

		foreach ( $variations as $variation ) {
			if ( empty( $variation['styles'] ) || empty( $variation['blockTypes'] ) ) {
				continue;
			}

			$variation_name = $variation['slug'] ?? _wp_to_kebab_case( $variation['title'] );

			foreach ( $variation['blockTypes'] as $block_type ) {
				// First, override partial styles with any top-level styles.
				$top_level_data = $data['styles']['variations'][ $variation_name ] ?? array();
				if ( ! empty( $top_level_data ) ) {
					$variation['styles'] = array_replace_recursive( $variation['styles'], $top_level_data );
				}

				// Then, override styles so far with any block-level styles.
				$block_level_data = $data['styles']['blocks'][ $block_type ]['variations'][ $variation_name ] ?? array();
				if ( ! empty( $block_level_data ) ) {
					$variation['styles'] = array_replace_recursive( $variation['styles'], $block_level_data );
				}

				$path = array( 'styles', 'blocks', $block_type, 'variations', $variation_name );
				_wp_array_set( $data, $path, $variation['styles'] );
			}
		}

		return $data;
	}

	/**
	 * Adds variations sourced from the block styles registry to the supplied theme.json data.
	 *
	 * @since 6.6.0
	 *
	 * @param array $data Array following the theme.json specification.
	 * @return array Theme json data including shared block style variation definitions.
	 */
	private static function inject_variations_from_block_styles_registry( $data ) {
		$registry = WP_Block_Styles_Registry::get_instance();
		$styles   = $registry->get_all_registered();

		foreach ( $styles as $block_type => $variations ) {
			foreach ( $variations as $variation_name => $variation ) {
				if ( empty( $variation['style_data'] ) ) {
					continue;
				}

				// First, override registry styles with any top-level styles.
				$top_level_data = $data['styles']['variations'][ $variation_name ] ?? array();
				if ( ! empty( $top_level_data ) ) {
					$variation['style_data'] = array_replace_recursive( $variation['style_data'], $top_level_data );
				}

				// Then, override styles so far with any block-level styles.
				$block_level_data = $data['styles']['blocks'][ $block_type ]['variations'][ $variation_name ] ?? array();
				if ( ! empty( $block_level_data ) ) {
					$variation['style_data'] = array_replace_recursive( $variation['style_data'], $block_level_data );
				}

				$path = array( 'styles', 'blocks', $block_type, 'variations', $variation_name );
				_wp_array_set( $data, $path, $variation['style_data'] );
			}
		}

		return $data;
	}
}