Document new global styles filters (#44111)

docs/how-to-guides/README.md

@@ -30,7 +30,7 @@ Porting PHP meta boxes to blocks or sidebar plugins is highly encouraged, learn
 
 By default, blocks provide their styles to enable basic support for blocks in themes without any change. Themes can add/override these styles, or rely on defaults.
 
-There are some advanced block features which require opt-in support in the theme. See [theme support](/docs/how-to-guides/themes/theme-support.md).
+There are some advanced block features which require opt-in support in the theme. See [theme support](/docs/how-to-guides/themes/theme-support.md) and [how to filter global styles](/docs/reference-guides/filters/global-styles-filters.md).
 
 ## Autocomplete
 

docs/manifest.json

@@ -503,6 +503,12 @@
 		"markdown_source": "../docs/reference-guides/filters/autocomplete-filters.md",
 		"parent": "filters"
 	},
+	{
+		"title": "Global Styles Filters",
+		"slug": "global-styles-filters",
+		"markdown_source": "../docs/reference-guides/filters/global-styles-filters.md",
+		"parent": "filters"
+	},
 	{
 		"title": "SlotFills Reference",
 		"slug": "slotfills",

docs/reference-guides/README.md

@@ -23,6 +23,7 @@
 -   [i18n Hooks](/docs/reference-guides/filters/i18n-filters.md)
 -   [Parser Hooks](/docs/reference-guides/filters/parser-filters.md)
 -   [Autocomplete](/docs/reference-guides/filters/autocomplete-filters.md)
+-   [Global Styles Hooks](/docs/reference-guides/filters/global-styles-filters.md)
 
 ## [SlotFills Reference](/docs/reference-guides/slotfills/README.md)
 

docs/reference-guides/filters/global-styles-filters.md

@@ -0,0 +1,42 @@
+# Global Styles Filters
+
+WordPress 6.1 has introduced some server-side filters to hook into the data provided to Global Styles & Settings:
+
+- `global_styles_default`: hooks into the default data provided by WordPress
+- `global_styles_blocks`: hooks into the data provided by the blocks
+- `global_styles_theme`: hooks into the data provided by the theme
+- `global_styles_user`: hooks into the data provided by the user
+
+Each filter receives an instance of the `WP_Theme_JSON_Data` class with the data for the respective layer. To provide new data, the filter callback needs to use the `update_with( $new_data )` method, where `$new_data` is a valid `theme.json`-like structure. As with any `theme.json`, the new data needs to declare which `version` of the `theme.json` is using, so it can correctly be migrated to the runtime one, should it be different.
+
+_Example:_
+
+This is how to pass a new color palette for the theme and disable the text color UI:
+
+```php
+function filter_global_styles_theme( $theme_json ){
+	$new_data = array(
+		'version'  => 2,
+		'settings' => array(
+			'color' => array(
+				'text'       => false,
+				'palette'    => array( /* New palette */
+					array(
+						'slug'  => 'foreground',
+						'color' => 'black',
+						'name'  => __( 'Foreground', 'theme-domain' ),
+					),
+					array(
+						'slug'  => 'background',
+						'color' => 'white',
+						'name'  => __( 'Background', 'theme-domain' ),
+					),
+				),
+			),
+		),
+	);
+
+	return $theme_json->update_with( $new_data );
+}
+add_filter( 'global_styles_theme', 'filter_global_styles_theme' );
+```

docs/toc.json

@@ -198,6 +198,9 @@
 					{ "docs/reference-guides/filters/parser-filters.md": [] },
 					{
 						"docs/reference-guides/filters/autocomplete-filters.md": []
+					},
+					{
+						"docs/reference-guides/filters/global-styles-filters.md": []
 					}
 				]
 			},