Add a filter hook for the theme style variations

[dhananjaykuber]

Fixes #63574

What?

This PR adds filter hooks to allow for custom style variations to be injected and additional directories to be scanned for JSON files. Specifically, it introduces:

• A filter hook over the result of WP_Theme_JSON_Resolver::get_style_variations() to let plugins filter the variations.
• A filter hook for the directory paths that should be scanned for JSON files.

Why?

Currently, only themes can register theme style variations by adding JSON files to their /styles folder. There is no API or filter hook to add custom variations outside of using the /styles folder. This PR addresses this limitation by providing the necessary hooks to extend and customize style variations more flexibly.

How?

• Filter for Directory Paths: A new filter wp_theme_json_style_variation_directories is added to allow custom directories to be included when scanning for style variation JSON files.
• Filter for Style Variations: Another filter wp_theme_json_variation_files is added to enable plugins to modify the array of style variation files collected from the directories.
• Updated get_style_variations Method: The get_style_variations method in the WP_Theme_JSON_Resolver class is updated to apply these filters and handle the inclusion of custom directories and variations.

Testing Instructions

• Create a new plugin or modify an existing one.
• Add the following code to the plugin:

<?php
// Add custom directories to scan for JSON files.
function add_custom_style_variation_directories( $directories ) {
	// Add custom styles directory.
	$directories['custom_directory'] = plugin_dir_path( __FILE__ ) . 'custom-styles';
	return $directories;
}
add_filter( 'wp_theme_json_style_variation_directories', 'add_custom_style_variation_directories' );

// Modify final style variations.
function modify_final_style_variations($variations) {
    // Example modification: Add a custom variation.
    $variations[] = array(
        'title' => 'Custom Variation',
        'styles' => array(
            'color' => array(
                'background' => '#ff0000',
            ),
        ),
    );
    return $variations;
}
add_filter('wp_theme_json_style_variations', 'modify_final_style_variations');

• Create a directory named custom-styles in the root of your plugin and add a JSON file with style variations.
• Activate the plugin and verify that the custom styles appear in the theme options.

Screenshots or screencast

• New Styles variations added by new custom-styles folder using wp_theme_json_style_variation_directories filter

• Filtered Styles variations added by wp_theme_json_variation_files filter

[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: dhananjaykuber <dhananjaykuber@git.wordpress.org>
Co-authored-by: justintadlock <greenshady@git.wordpress.org>
Co-authored-by: scruffian <scruffian@git.wordpress.org>
Co-authored-by: KevinBatdorf <kbat82@git.wordpress.org>
Co-authored-by: bph <bph@git.wordpress.org>

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

[justintadlock]

CC: @richtabor - What do you think of this direction? I'm in favor of the filter hooks introduced here and think this is a solid solution. Longer term, I think it'd be great to have dedicated register/unregister functions, which would certainly make the ability to unregister easier.

[scruffian]

See also #63318.

I'm not sure if a filter will be too much of a commitment, but with the approach in #63318 at least plugins have access to the main functions that are needed to access style variations.

[KevinBatdorf]

This PR is outdated due to #63318 but there's still no way to remove a variation conditionally. I'll open a new PR with just that change.

This PR could be closed.