From d5f274ce9325e826614130f2c07f38e47ccb8008 Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Fri, 8 Nov 2024 14:36:01 +1000 Subject: [PATCH 01/11] Use stabilized border support key --- lib/class-wp-theme-json-gutenberg.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/class-wp-theme-json-gutenberg.php b/lib/class-wp-theme-json-gutenberg.php index 083ce3516b71af..eaab90bf993e39 100644 --- a/lib/class-wp-theme-json-gutenberg.php +++ b/lib/class-wp-theme-json-gutenberg.php @@ -739,7 +739,7 @@ public static function get_element_class_name( $element ) { * @param string $origin Optional. What source of data this object represents. * One of 'blocks', 'default', 'theme', or 'custom'. Default 'theme'. */ - public function __construct( $theme_json = array( 'version' => WP_Theme_JSON_Gutenberg::LATEST_SCHEMA ), $origin = 'theme' ) { + public function __construct( $theme_json = array( 'version' => self::LATEST_SCHEMA ), $origin = 'theme' ) { if ( ! in_array( $origin, static::VALID_ORIGINS, true ) ) { $origin = 'theme'; } From aa44f85fd00b4051c1a41e70dab1587cf778766c Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Fri, 8 Nov 2024 17:22:03 +1000 Subject: [PATCH 02/11] Update stabilization approach to include border support --- lib/class-wp-theme-json-gutenberg.php | 2 +- lib/compat/wordpress-6.8/blocks.php | 11 +---------- packages/blocks/src/store/process-block-type.js | 16 +++------------- 3 files changed, 5 insertions(+), 24 deletions(-) diff --git a/lib/class-wp-theme-json-gutenberg.php b/lib/class-wp-theme-json-gutenberg.php index eaab90bf993e39..083ce3516b71af 100644 --- a/lib/class-wp-theme-json-gutenberg.php +++ b/lib/class-wp-theme-json-gutenberg.php @@ -739,7 +739,7 @@ public static function get_element_class_name( $element ) { * @param string $origin Optional. What source of data this object represents. * One of 'blocks', 'default', 'theme', or 'custom'. Default 'theme'. */ - public function __construct( $theme_json = array( 'version' => self::LATEST_SCHEMA ), $origin = 'theme' ) { + public function __construct( $theme_json = array( 'version' => WP_Theme_JSON_Gutenberg::LATEST_SCHEMA ), $origin = 'theme' ) { if ( ! in_array( $origin, static::VALID_ORIGINS, true ) ) { $origin = 'theme'; } diff --git a/lib/compat/wordpress-6.8/blocks.php b/lib/compat/wordpress-6.8/blocks.php index 0b7031403b1918..b057df30158ece 100644 --- a/lib/compat/wordpress-6.8/blocks.php +++ b/lib/compat/wordpress-6.8/blocks.php @@ -50,16 +50,7 @@ function gutenberg_stabilize_experimental_block_supports( $args ) { continue; } - /* - * Determine the order of keys, so the last defined can be preferred. - * - * The reason for preferring the last defined key is that after filters - * are applied, the last inserted key is likely the most up-to-date value. - * We cannot determine with certainty which value was "last modified" so - * the insertion order is the best guess. The extreme edge case of multiple - * filters tweaking the same support property will become less over time as - * extenders migrate existing blocks and plugins to stable keys. - */ + // Determine the order of keys, so the last defined can be preferred. $key_positions = array_flip( array_keys( $args['supports'] ) ); $experimental_index = $key_positions[ $support ] ?? -1; $stabilized_index = $key_positions[ $stabilized_key ] ?? -1; diff --git a/packages/blocks/src/store/process-block-type.js b/packages/blocks/src/store/process-block-type.js index bd7e5ab43800f0..e68f4c3d576379 100644 --- a/packages/blocks/src/store/process-block-type.js +++ b/packages/blocks/src/store/process-block-type.js @@ -77,7 +77,7 @@ function stabilizeSupports( rawSupports ) { const newSupports = {}; for ( const [ support, config ] of Object.entries( rawSupports ) ) { - // Add the support's config as is when it's not in need of stabilization. + // Add the current support's config as is if it does not need stabilization. if ( ! EXPERIMENTAL_TO_STABLE_KEYS[ support ] ) { newSupports[ support ] = config; continue; @@ -87,22 +87,13 @@ function stabilizeSupports( rawSupports ) { if ( typeof EXPERIMENTAL_TO_STABLE_KEYS[ support ] === 'string' ) { const stabilizedKey = EXPERIMENTAL_TO_STABLE_KEYS[ support ]; - // If there is no stabilized key present, use the experimental config as is. + // If there's no stabilized key present, just use the config as is. if ( ! Object.hasOwn( rawSupports, stabilizedKey ) ) { newSupports[ stabilizedKey ] = config; continue; } - /* - * Determine the order of keys, so the last defined can be preferred. - * - * The reason for preferring the last defined key is that after filters - * are applied, the last inserted key is likely the most up-to-date value. - * We cannot determine with certainty which value was "last modified" so - * the insertion order is the best guess. The extreme edge case of multiple - * filters tweaking the same support property will become less over time as - * extenders migrate existing blocks and plugins to stable keys. - */ + // Determine the insertion order for both key. const entries = Object.entries( rawSupports ); const experimentalIndex = entries.findIndex( ( [ key ] ) => key === support @@ -111,7 +102,6 @@ function stabilizeSupports( rawSupports ) { ( [ key ] ) => key === stabilizedKey ); - // Update support config, prefer the last defined value. if ( typeof config === 'object' && config !== null ) { newSupports[ stabilizedKey ] = experimentalIndex < stabilizedIndex From 941fadad1d9c55698d28007643463c78937618d1 Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Wed, 13 Nov 2024 14:44:58 +1000 Subject: [PATCH 03/11] Make comments match between JS and PHP stabilizations --- packages/blocks/src/store/process-block-type.js | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/blocks/src/store/process-block-type.js b/packages/blocks/src/store/process-block-type.js index e68f4c3d576379..deb01578f03819 100644 --- a/packages/blocks/src/store/process-block-type.js +++ b/packages/blocks/src/store/process-block-type.js @@ -77,7 +77,7 @@ function stabilizeSupports( rawSupports ) { const newSupports = {}; for ( const [ support, config ] of Object.entries( rawSupports ) ) { - // Add the current support's config as is if it does not need stabilization. + // Add the support's config as is when it's not in need of stabilization. if ( ! EXPERIMENTAL_TO_STABLE_KEYS[ support ] ) { newSupports[ support ] = config; continue; @@ -87,13 +87,13 @@ function stabilizeSupports( rawSupports ) { if ( typeof EXPERIMENTAL_TO_STABLE_KEYS[ support ] === 'string' ) { const stabilizedKey = EXPERIMENTAL_TO_STABLE_KEYS[ support ]; - // If there's no stabilized key present, just use the config as is. + // If there is no stabilized key present, use the experimental config as is. if ( ! Object.hasOwn( rawSupports, stabilizedKey ) ) { newSupports[ stabilizedKey ] = config; continue; } - // Determine the insertion order for both key. + // Determine the order of keys, so the last defined can be preferred. const entries = Object.entries( rawSupports ); const experimentalIndex = entries.findIndex( ( [ key ] ) => key === support @@ -102,6 +102,7 @@ function stabilizeSupports( rawSupports ) { ( [ key ] ) => key === stabilizedKey ); + // Update support config, prefer the last defined value. if ( typeof config === 'object' && config !== null ) { newSupports[ stabilizedKey ] = experimentalIndex < stabilizedIndex From 0b7d8ba91547313de56e043005d0ffdabf0b70fc Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Fri, 15 Nov 2024 12:15:49 +1000 Subject: [PATCH 04/11] Block Supports: Try stabilizing common experimental flags --- lib/compat/wordpress-6.8/blocks.php | 112 ++++++++++------ phpunit/block-supports/border-test.php | 173 ++++++++++++++++++++++++- 2 files changed, 242 insertions(+), 43 deletions(-) diff --git a/lib/compat/wordpress-6.8/blocks.php b/lib/compat/wordpress-6.8/blocks.php index b057df30158ece..206b7dba1648f8 100644 --- a/lib/compat/wordpress-6.8/blocks.php +++ b/lib/compat/wordpress-6.8/blocks.php @@ -20,8 +20,13 @@ function gutenberg_stabilize_experimental_block_supports( $args ) { return $args; } - $experimental_to_stable_keys = array( - 'typography' => array( + $experimental_supports_map = array( '__experimentalBorder' => 'border' ); + $common_experimental_properties = array( + '__experimentalDefaultControls' => 'defaultControls', + '__experimentalSkipSerialization' => 'skipSerialization', + ); + $experimental_support_properties = array( + 'typography' => array( '__experimentalFontFamily' => 'fontFamily', '__experimentalFontStyle' => 'fontStyle', '__experimentalFontWeight' => 'fontWeight', @@ -29,59 +34,90 @@ function gutenberg_stabilize_experimental_block_supports( $args ) { '__experimentalTextDecoration' => 'textDecoration', '__experimentalTextTransform' => 'textTransform', ), - '__experimentalBorder' => 'border', ); $updated_supports = array(); foreach ( $args['supports'] as $support => $config ) { - // Add the support's config as is when it's not in need of stabilization. - if ( empty( $experimental_to_stable_keys[ $support ] ) ) { + $stable_support_key = $experimental_supports_map[ $support ] ?? $support; + + /* + * Use the support's config as is when it's not in need of stabilization. + * + * A support does not need stabilization if: + * - The support key doesn't need stabilization AND + * - Either: + * - The config isn't an array, so can't have experimental properties OR + * - The config is an array but has no experimental properties to stabilize. + */ + if ( $support === $stable_support_key && + ( ! is_array( $config ) || + ( ! isset( $experimental_support_properties[ $stable_support_key ] ) && + empty( array_intersect_key( $common_experimental_properties, $config ) ) + ) + ) + ) { $updated_supports[ $support ] = $config; continue; } - // Stabilize the support's key if needed e.g. __experimentalBorder => border. - if ( is_string( $experimental_to_stable_keys[ $support ] ) ) { - $stabilized_key = $experimental_to_stable_keys[ $support ]; + $stabilize_config = function ( $unstable_config, $stable_support_key ) use ( $experimental_support_properties, $common_experimental_properties ) { + $stable_config = array(); + foreach ( $unstable_config as $key => $value ) { + // Get stable key from support-specific map, common properties map, or keep original. + $stable_key = $experimental_support_properties[ $stable_support_key ][ $key ] ?? + $common_experimental_properties[ $key ] ?? + $key; + + $stable_config[ $stable_key ] = $value; - // If there is no stabilized key present, use the experimental config as is. - if ( ! array_key_exists( $stabilized_key, $args['supports'] ) ) { - $updated_supports[ $stabilized_key ] = $config; - continue; + /* + * The `__experimentalSkipSerialization` key needs to be kept until + * WP 6.8 becomes the minimum supported version. This is due to the + * core `wp_should_skip_block_supports_serialization` function only + * checking for `__experimentalSkipSerialization` in earlier versions. + */ + if ( '__experimentalSkipSerialization' === $key || 'skipSerialization' === $key ) { + $stable_config['__experimentalSkipSerialization'] = $value; + } } + return $stable_config; + }; + + // Stabilize the config value. + $stable_config = is_array( $config ) ? $stabilize_config( $config, $stable_support_key ) : $config; - // Determine the order of keys, so the last defined can be preferred. + /* + * When both experimental and stable configs are present, use the order they + * are defined in to determine the final value. + * - If config is an array, merge the arrays in their order of definition. + * - If config is not an array, use the value defined last. + */ + if ( $support !== $stable_support_key && isset( $args['supports'][ $stable_support_key ] ) ) { $key_positions = array_flip( array_keys( $args['supports'] ) ); - $experimental_index = $key_positions[ $support ] ?? -1; - $stabilized_index = $key_positions[ $stabilized_key ] ?? -1; - $experimental_first = $experimental_index < $stabilized_index; + $experimental_first = + ( $key_positions[ $support ] ?? PHP_INT_MAX ) < + ( $key_positions[ $stable_support_key ] ?? PHP_INT_MAX ); + + if ( is_array( $args['supports'][ $stable_support_key ] ) ) { + /* + * To merge the alternative support config effectively, it also needs to be + * stabilized before merging to keep stabilized and experimental flags in + * sync. + */ + // TODO: This could be added to a "done list", to skip in the overall loop through `$args['supports']`. + $args['supports'][ $stable_support_key ] = $stabilize_config( $args['supports'][ $stable_support_key ], $stable_support_key ); - // Update support config, prefer the last defined value. - if ( is_array( $config ) ) { - $updated_supports[ $stabilized_key ] = $experimental_first - ? array_merge( $config, $args['supports'][ $stabilized_key ] ) - : array_merge( $args['supports'][ $stabilized_key ], $config ); + $stable_config = $experimental_first + ? array_merge( $stable_config, $args['supports'][ $stable_support_key ] ) + : array_merge( $args['supports'][ $stable_support_key ], $stable_config ); } else { - $updated_supports[ $stabilized_key ] = $experimental_first - ? $args['supports'][ $stabilized_key ] - : $config; + $stable_config = $experimental_first + ? $args['supports'][ $stable_support_key ] + : $stable_config; } - - continue; } - // Stabilize individual support feature keys e.g. __experimentalFontFamily => fontFamily. - if ( is_array( $experimental_to_stable_keys[ $support ] ) ) { - $stable_support_config = array(); - foreach ( $config as $key => $value ) { - if ( array_key_exists( $key, $experimental_to_stable_keys[ $support ] ) ) { - $stable_support_config[ $experimental_to_stable_keys[ $support ][ $key ] ] = $value; - } else { - $stable_support_config[ $key ] = $value; - } - } - $updated_supports[ $support ] = $stable_support_config; - } + $updated_supports[ $stable_support_key ] = $stable_config; } $args['supports'] = $updated_supports; diff --git a/phpunit/block-supports/border-test.php b/phpunit/block-supports/border-test.php index 0c320f24ebe4f2..6ec43b369d9a2a 100644 --- a/phpunit/block-supports/border-test.php +++ b/phpunit/block-supports/border-test.php @@ -128,11 +128,11 @@ public function test_flat_border_with_skipped_serialization() { 'test/flat-border-with-skipped-serialization', array( '__experimentalBorder' => array( - 'color' => true, - 'radius' => true, - 'width' => true, - 'style' => true, - '__experimentalSkipSerialization' => true, + 'color' => true, + 'radius' => true, + 'width' => true, + 'style' => true, + 'skipSerialization' => true, ), ) ); @@ -567,4 +567,167 @@ public function test_should_apply_stabilized_border_supports() { $this->assertSame( $expected, $actual ); } + + /** + * Tests that experimental border support configuration gets stabilized correctly. + */ + public function test_should_stabilize_border_supports() { + $block_type_args = array( + 'supports' => array( + '__experimentalBorder' => array( + 'color' => true, + 'radius' => true, + 'style' => true, + 'width' => true, + '__experimentalSkipSerialization' => true, + '__experimentalDefaultControls' => array( + 'color' => true, + 'radius' => true, + 'style' => true, + 'width' => true, + ), + ), + ), + ); + + $actual = gutenberg_stabilize_experimental_block_supports( $block_type_args ); + $expected = array( + 'supports' => array( + 'border' => array( + 'color' => true, + 'radius' => true, + 'style' => true, + 'width' => true, + 'skipSerialization' => true, + // Has to be kept due to core's `wp_should_skip_block_supports_serialization` only checking the experimental flag until 6.8. + '__experimentalSkipSerialization' => true, + 'defaultControls' => array( + 'color' => true, + 'radius' => true, + 'style' => true, + 'width' => true, + ), + ), + ), + ); + + $this->assertSame( $expected, $actual, 'Stabilized border block support config does not match.' ); + } + + /** + * Tests the merging of border support configuration when stabilizing + * experimental config. Due to the ability to filter block type args, plugins + * or themes could filter using outdated experimental keys. While not every + * permutation of filtering can be covered, the majority of use cases are + * served best by merging configs based on the order they were defined if possible. + */ + public function test_should_stabilize_border_supports_using_order_based_merge() { + $experimental_border_config = array( + 'color' => true, + 'radius' => true, + 'style' => true, + 'width' => true, + '__experimentalSkipSerialization' => true, + '__experimentalDefaultControls' => array( + 'color' => true, + 'radius' => true, + 'style' => true, + 'width' => true, + ), + + /* + * The following simulates theme/plugin filtering using `__experimentalBorder` + * key but stable serialization and default control keys. + */ + 'skipSerialization' => false, + 'defaultControls' => array( + 'color' => true, + 'radius' => false, + 'style' => true, + 'width' => true, + ), + ); + $stable_border_config = array( + 'color' => true, + 'radius' => true, + 'style' => false, + 'width' => true, + 'skipSerialization' => false, + 'defaultControls' => array( + 'color' => true, + 'radius' => false, + 'style' => false, + 'width' => true, + ), + + /* + * The following simulates theme/plugin filtering using stable `border` key + * but experimental serialization and default control keys. + */ + '__experimentalSkipSerialization' => true, + '__experimentalDefaultControls' => array( + 'color' => false, + 'radius' => false, + 'style' => false, + 'width' => false, + ), + ); + + $experimental_first_args = array( + 'supports' => array( + '__experimentalBorder' => $experimental_border_config, + 'border' => $stable_border_config, + ), + ); + + $actual = gutenberg_stabilize_experimental_block_supports( $experimental_first_args ); + $expected = array( + 'supports' => array( + 'border' => array( + 'color' => true, + 'radius' => true, + 'style' => false, + 'width' => true, + 'skipSerialization' => true, + '__experimentalSkipSerialization' => true, + 'defaultControls' => array( + 'color' => false, + 'radius' => false, + 'style' => false, + 'width' => false, + ), + + ), + ), + ); + $this->assertSame( $expected, $actual, 'Merged stabilized border block support config does not match when experimental keys are first.' ); + + $stable_first_args = array( + 'supports' => array( + 'border' => $stable_border_config, + '__experimentalBorder' => $experimental_border_config, + ), + ); + + $actual = gutenberg_stabilize_experimental_block_supports( $stable_first_args ); + $expected = array( + 'supports' => array( + 'border' => array( + 'color' => true, + 'radius' => true, + 'style' => true, + 'width' => true, + 'skipSerialization' => false, + '__experimentalSkipSerialization' => false, + 'defaultControls' => array( + 'color' => true, + 'radius' => false, + 'style' => true, + 'width' => true, + ), + ), + ), + ); + $this->assertSame( $expected, $actual, 'Merged stabilized border block support config does not match when stable keys are first.' ); + } } From c07f5f9d828331484f97397d8bc5755b527b3d80 Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Fri, 15 Nov 2024 15:35:10 +1000 Subject: [PATCH 05/11] Prevent stable configs overriding prior experimental stabilization and merge --- lib/compat/wordpress-6.8/blocks.php | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/lib/compat/wordpress-6.8/blocks.php b/lib/compat/wordpress-6.8/blocks.php index 206b7dba1648f8..7f27608efe2e2b 100644 --- a/lib/compat/wordpress-6.8/blocks.php +++ b/lib/compat/wordpress-6.8/blocks.php @@ -35,9 +35,19 @@ function gutenberg_stabilize_experimental_block_supports( $args ) { '__experimentalTextTransform' => 'textTransform', ), ); + $done = array(); $updated_supports = array(); foreach ( $args['supports'] as $support => $config ) { + /* + * If this support config has already been stabilized, skip it. + * A stable support key occurring after an experimental key, gets + * stabilized then so that the two configs can be merged effectively. + */ + if ( isset( $done[ $support ] ) ) { + continue; + } + $stable_support_key = $experimental_supports_map[ $support ] ?? $support; /* @@ -104,12 +114,12 @@ function gutenberg_stabilize_experimental_block_supports( $args ) { * stabilized before merging to keep stabilized and experimental flags in * sync. */ - // TODO: This could be added to a "done list", to skip in the overall loop through `$args['supports']`. $args['supports'][ $stable_support_key ] = $stabilize_config( $args['supports'][ $stable_support_key ], $stable_support_key ); - - $stable_config = $experimental_first + $stable_config = $experimental_first ? array_merge( $stable_config, $args['supports'][ $stable_support_key ] ) : array_merge( $args['supports'][ $stable_support_key ], $stable_config ); + // Prevents reprocessing this support as it was merged above. + $done[ $stable_support_key ] = true; } else { $stable_config = $experimental_first ? $args['supports'][ $stable_support_key ] From 201be3cca5fe27aec6b56cdcfc292592002b5399 Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Tue, 19 Nov 2024 15:05:50 +1000 Subject: [PATCH 06/11] Update JS block type processing to stabilize supports --- packages/blocks/src/api/constants.js | 12 +- .../blocks/src/store/process-block-type.js | 175 +++++--- .../src/store/test/process-block-type.js | 395 ++++++++++-------- 3 files changed, 343 insertions(+), 239 deletions(-) diff --git a/packages/blocks/src/api/constants.js b/packages/blocks/src/api/constants.js index 8ea32d591adb32..aaf6558c47bada 100644 --- a/packages/blocks/src/api/constants.js +++ b/packages/blocks/src/api/constants.js @@ -298,7 +298,16 @@ export const __EXPERIMENTAL_PATHS_WITH_OVERRIDE = { 'spacing.spacingSizes': true, }; -export const EXPERIMENTAL_TO_STABLE_KEYS = { +export const EXPERIMENTAL_SUPPORTS_MAP = { + __experimentalBorder: 'border', +}; + +export const COMMON_EXPERIMENTAL_PROPERTIES = { + __experimentalDefaultControls: 'defaultControls', + __experimentalSkipSerialization: 'skipSerialization', +}; + +export const EXPERIMENTAL_SUPPORT_PROPERTIES = { typography: { __experimentalFontFamily: 'fontFamily', __experimentalFontStyle: 'fontStyle', @@ -307,5 +316,4 @@ export const EXPERIMENTAL_TO_STABLE_KEYS = { __experimentalTextDecoration: 'textDecoration', __experimentalTextTransform: 'textTransform', }, - __experimentalBorder: 'border', }; diff --git a/packages/blocks/src/store/process-block-type.js b/packages/blocks/src/store/process-block-type.js index deb01578f03819..c913da6f23136a 100644 --- a/packages/blocks/src/store/process-block-type.js +++ b/packages/blocks/src/store/process-block-type.js @@ -18,7 +18,9 @@ import { isValidIcon, normalizeIconObject, omit } from '../api/utils'; import { BLOCK_ICON_DEFAULT, DEPRECATED_ENTRY_KEYS, - EXPERIMENTAL_TO_STABLE_KEYS, + EXPERIMENTAL_SUPPORTS_MAP, + COMMON_EXPERIMENTAL_PROPERTIES, + EXPERIMENTAL_SUPPORT_PROPERTIES, } from '../api/constants'; /** @typedef {import('../api/registration').WPBlockType} WPBlockType */ @@ -66,72 +68,141 @@ function mergeBlockVariations( return result; } +/** + * Stabilizes a block support configuration by converting experimental properties + * to their stable equivalents. + * + * @param {Object} unstableConfig The support configuration to stabilize. + * @param {string} stableSupportKey The stable support key for looking up properties. + * @return {Object} The stabilized support configuration. + */ +function stabilizeSupportConfig( unstableConfig, stableSupportKey ) { + const stableConfig = {}; + for ( const [ key, value ] of Object.entries( unstableConfig ) ) { + // Get stable key from support-specific map, common properties map, or keep original. + const stableKey = + EXPERIMENTAL_SUPPORT_PROPERTIES[ stableSupportKey ]?.[ key ] ?? + COMMON_EXPERIMENTAL_PROPERTIES[ key ] ?? + key; + + stableConfig[ stableKey ] = value; + + /* + * The `__experimentalSkipSerialization` key needs to be kept until + * WP 6.8 becomes the minimum supported version. This is due to the + * core `wp_should_skip_block_supports_serialization` function only + * checking for `__experimentalSkipSerialization` in earlier versions. + */ + if ( + key === '__experimentalSkipSerialization' || + key === 'skipSerialization' + ) { + stableConfig.__experimentalSkipSerialization = value; + } + } + return stableConfig; +} + +/** + * Stabilizes experimental block supports by converting experimental keys and properties + * to their stable equivalents. + * + * @param {Object|undefined} rawSupports The block supports configuration to stabilize. + * @return {Object|undefined} The stabilized block supports configuration. + */ function stabilizeSupports( rawSupports ) { if ( ! rawSupports ) { return rawSupports; } - // Create a new object to avoid mutating the original. This ensures that - // custom block plugins that rely on immutable supports are not affected. - // See: https://github.com/WordPress/gutenberg/pull/66849#issuecomment-2463614281 + /* + * Create a new object to avoid mutating the original. This ensures that + * custom block plugins that rely on immutable supports are not affected. + * See: https://github.com/WordPress/gutenberg/pull/66849#issuecomment-2463614281 + */ const newSupports = {}; + const done = {}; for ( const [ support, config ] of Object.entries( rawSupports ) ) { - // Add the support's config as is when it's not in need of stabilization. - if ( ! EXPERIMENTAL_TO_STABLE_KEYS[ support ] ) { - newSupports[ support ] = config; + /* + * If this support config has already been stabilized, skip it. + * A stable support key occurring after an experimental key, gets + * stabilized then so that the two configs can be merged effectively. + */ + if ( done[ support ] ) { continue; } - // Stabilize the support's key if needed e.g. __experimentalBorder => border. - if ( typeof EXPERIMENTAL_TO_STABLE_KEYS[ support ] === 'string' ) { - const stabilizedKey = EXPERIMENTAL_TO_STABLE_KEYS[ support ]; - - // If there is no stabilized key present, use the experimental config as is. - if ( ! Object.hasOwn( rawSupports, stabilizedKey ) ) { - newSupports[ stabilizedKey ] = config; - continue; - } - - // Determine the order of keys, so the last defined can be preferred. - const entries = Object.entries( rawSupports ); - const experimentalIndex = entries.findIndex( - ( [ key ] ) => key === support - ); - const stabilizedIndex = entries.findIndex( - ( [ key ] ) => key === stabilizedKey - ); - - // Update support config, prefer the last defined value. - if ( typeof config === 'object' && config !== null ) { - newSupports[ stabilizedKey ] = - experimentalIndex < stabilizedIndex - ? { ...config, ...rawSupports[ stabilizedKey ] } - : { ...rawSupports[ stabilizedKey ], ...config }; - } else { - newSupports[ stabilizedKey ] = - experimentalIndex < stabilizedIndex - ? rawSupports[ stabilizedKey ] - : config; - } + const stableSupportKey = + EXPERIMENTAL_SUPPORTS_MAP[ support ] ?? support; + + /* + * Use the support's config as is when it's not in need of stabilization. + * A support does not need stabilization if: + * - The support key doesn't need stabilization AND + * - Either: + * - The config isn't an object, so can't have experimental properties OR + * - The config is an object but has no experimental properties to stabilize. + */ + if ( + support === stableSupportKey && + ( ! isPlainObject( config ) || + ( ! EXPERIMENTAL_SUPPORT_PROPERTIES[ stableSupportKey ] && + Object.keys( config ).every( + ( key ) => ! COMMON_EXPERIMENTAL_PROPERTIES[ key ] + ) ) ) + ) { + newSupports[ support ] = config; continue; } - // Stabilize individual support feature keys - // e.g. __experimentalFontFamily => fontFamily. - const featureStabilizationRequired = - typeof EXPERIMENTAL_TO_STABLE_KEYS[ support ] === 'object' && - EXPERIMENTAL_TO_STABLE_KEYS[ support ] !== null; - const hasConfig = typeof config === 'object' && config !== null; - - if ( featureStabilizationRequired && hasConfig ) { - const stableConfig = {}; - for ( const [ key, value ] of Object.entries( config ) ) { - const stableKey = - EXPERIMENTAL_TO_STABLE_KEYS[ support ][ key ] || key; - stableConfig[ stableKey ] = value; + // Stabilize the config value. + const stableConfig = isPlainObject( config ) + ? stabilizeSupportConfig( config, stableSupportKey ) + : config; + + /* + * When both experimental and stable configs are present, use the order they + * are defined in to determine the final value. + * - If config is an array, merge the arrays in their order of definition. + * - If config is not an array, use the value defined last. + */ + if ( + support !== stableSupportKey && + Object.hasOwn( rawSupports, stableSupportKey ) + ) { + const keyPositions = Object.keys( rawSupports ).reduce( + ( acc, key, index ) => { + acc[ key ] = index; + return acc; + }, + {} + ); + const experimentalFirst = + ( keyPositions[ support ] ?? Number.MAX_VALUE ) < + ( keyPositions[ stableSupportKey ] ?? Number.MAX_VALUE ); + + if ( isPlainObject( rawSupports[ stableSupportKey ] ) ) { + /* + * To merge the alternative support config effectively, it also needs to be + * stabilized before merging to keep stabilized and experimental flags in sync. + */ + rawSupports[ stableSupportKey ] = stabilizeSupportConfig( + rawSupports[ stableSupportKey ], + stableSupportKey + ); + newSupports[ stableSupportKey ] = experimentalFirst + ? { ...stableConfig, ...rawSupports[ stableSupportKey ] } + : { ...rawSupports[ stableSupportKey ], ...stableConfig }; + // Prevents reprocessing this support as it was merged above. + done[ stableSupportKey ] = true; + } else { + newSupports[ stableSupportKey ] = experimentalFirst + ? rawSupports[ stableSupportKey ] + : stableConfig; } - newSupports[ support ] = stableConfig; + } else { + newSupports[ stableSupportKey ] = stableConfig; } } diff --git a/packages/blocks/src/store/test/process-block-type.js b/packages/blocks/src/store/test/process-block-type.js index c7f487a95301d0..82b2c1ad3080d7 100644 --- a/packages/blocks/src/store/test/process-block-type.js +++ b/packages/blocks/src/store/test/process-block-type.js @@ -26,7 +26,7 @@ describe( 'processBlockType', () => { removeFilter( 'blocks.registerBlockType', 'test/filterSupports' ); } ); - it( 'should return the block type with stabilized supports', () => { + it( 'should stabilize experimental block supports', () => { const blockSettings = { ...baseBlockSettings, supports: { @@ -66,7 +66,7 @@ describe( 'processBlockType', () => { blockSettings )( { select } ); - expect( processedBlockType.supports ).toEqual( { + expect( processedBlockType.supports ).toMatchObject( { typography: { fontSize: true, lineHeight: true, @@ -77,7 +77,7 @@ describe( 'processBlockType', () => { textTransform: true, textDecoration: true, __experimentalWritingMode: true, - __experimentalDefaultControls: { + defaultControls: { fontSize: true, fontAppearance: true, textTransform: true, @@ -88,79 +88,7 @@ describe( 'processBlockType', () => { radius: true, style: true, width: true, - __experimentalDefaultControls: { - color: true, - radius: true, - style: true, - width: true, - }, - }, - } ); - } ); - - it( 'should return the block type with stable supports', () => { - const blockSettings = { - ...baseBlockSettings, - supports: { - typography: { - fontSize: true, - lineHeight: true, - fontFamily: true, - fontStyle: true, - fontWeight: true, - letterSpacing: true, - textTransform: true, - textDecoration: true, - __experimentalWritingMode: true, - __experimentalDefaultControls: { - fontSize: true, - fontAppearance: true, - textTransform: true, - }, - }, - __experimentalBorder: { - color: true, - radius: true, - style: true, - width: true, - __experimentalDefaultControls: { - color: true, - radius: true, - style: true, - width: true, - }, - }, - }, - }; - - const processedBlockType = processBlockType( - 'test/block', - blockSettings - )( { select } ); - - expect( processedBlockType.supports ).toEqual( { - typography: { - fontSize: true, - lineHeight: true, - fontFamily: true, - fontStyle: true, - fontWeight: true, - letterSpacing: true, - textTransform: true, - textDecoration: true, - __experimentalWritingMode: true, - __experimentalDefaultControls: { - fontSize: true, - fontAppearance: true, - textTransform: true, - }, - }, - border: { - color: true, - radius: true, - style: true, - width: true, - __experimentalDefaultControls: { + defaultControls: { color: true, radius: true, style: true, @@ -227,7 +155,7 @@ describe( 'processBlockType', () => { blockSettings )( { select } ); - expect( processedBlockType.supports ).toEqual( { + expect( processedBlockType.supports ).toMatchObject( { typography: { fontSize: true, lineHeight: true, @@ -238,7 +166,7 @@ describe( 'processBlockType', () => { textTransform: true, textDecoration: true, __experimentalWritingMode: true, - __experimentalDefaultControls: { + defaultControls: { fontSize: true, fontAppearance: true, textTransform: true, @@ -249,7 +177,7 @@ describe( 'processBlockType', () => { radius: false, style: true, width: true, - __experimentalDefaultControls: { + defaultControls: { color: true, radius: true, style: true, @@ -259,8 +187,8 @@ describe( 'processBlockType', () => { } ); } ); - it( 'should stabilize experimental supports within block deprecations', () => { - const blockSettings = { + describe( 'block deprecations', () => { + const deprecatedBlockSettings = { ...baseBlockSettings, supports: { typography: { @@ -321,145 +249,242 @@ describe( 'processBlockType', () => { ], }; - // Freeze the deprecated block object and its supports so that the original is not mutated. - // This ensures the test covers a regression where the original object was mutated. - // See: https://github.com/WordPress/gutenberg/pull/63401#discussion_r1832394335. - Object.freeze( blockSettings.deprecated[ 0 ] ); - Object.freeze( blockSettings.deprecated[ 0 ].supports ); + beforeEach( () => { + // Freeze the deprecated block object and its supports so that the original is not mutated. + Object.freeze( deprecatedBlockSettings.deprecated[ 0 ] ); + Object.freeze( deprecatedBlockSettings.deprecated[ 0 ].supports ); + } ); + + it( 'should stabilize experimental supports', () => { + const processedBlockType = processBlockType( + 'test/block', + deprecatedBlockSettings + )( { select } ); + + expect( processedBlockType.deprecated[ 0 ].supports ).toMatchObject( + { + typography: { + fontFamily: true, + fontStyle: true, + fontWeight: true, + letterSpacing: true, + textTransform: true, + textDecoration: true, + __experimentalWritingMode: true, + }, + border: { + color: true, + radius: true, + style: true, + width: true, + defaultControls: { + color: true, + radius: true, + style: true, + width: true, + }, + }, + } + ); + } ); + + it( 'should reapply transformations after supports are filtered', () => { + addFilter( + 'blocks.registerBlockType', + 'test/filterSupports', + ( settings, name ) => { + if ( + name === 'test/block' && + settings.supports.typography + ) { + settings.supports.typography.__experimentalFontFamily = false; + settings.supports.typography.__experimentalFontStyle = false; + settings.supports.typography.__experimentalFontWeight = false; + settings.supports.__experimentalBorder = { + radius: false, + }; + } + return settings; + } + ); + + const processedBlockType = processBlockType( + 'test/block', + deprecatedBlockSettings + )( { select } ); + + expect( processedBlockType.deprecated[ 0 ].supports ).toMatchObject( + { + typography: { + fontFamily: false, + fontStyle: false, + fontWeight: false, + letterSpacing: true, + textTransform: true, + textDecoration: true, + __experimentalWritingMode: true, + }, + border: { + color: true, + radius: false, + style: true, + width: true, + defaultControls: { + color: true, + radius: true, + style: true, + width: true, + }, + }, + } + ); + } ); + } ); + + it( 'should stabilize common experimental properties across all supports', () => { + const blockSettings = { + ...baseBlockSettings, + supports: { + typography: { + fontSize: true, + __experimentalDefaultControls: { + fontSize: true, + }, + __experimentalSkipSerialization: true, + }, + spacing: { + padding: true, + __experimentalDefaultControls: { + padding: true, + }, + __experimentalSkipSerialization: true, + }, + }, + }; const processedBlockType = processBlockType( 'test/block', blockSettings )( { select } ); - expect( processedBlockType.deprecated[ 0 ].supports ).toEqual( { + expect( processedBlockType.supports ).toMatchObject( { typography: { - fontFamily: true, - fontStyle: true, - fontWeight: true, - letterSpacing: true, - textTransform: true, - textDecoration: true, - __experimentalWritingMode: true, + fontSize: true, + defaultControls: { + fontSize: true, + }, + skipSerialization: true, + __experimentalSkipSerialization: true, }, - border: { - color: true, - radius: true, - style: true, - width: true, - __experimentalDefaultControls: { - color: true, - radius: true, - style: true, - width: true, + spacing: { + padding: true, + defaultControls: { + padding: true, }, + skipSerialization: true, + __experimentalSkipSerialization: true, }, } ); } ); - it( 'should reapply transformations after supports are filtered within block deprecations', () => { + it( 'should merge experimental and stable keys in order of definition', () => { const blockSettings = { ...baseBlockSettings, supports: { - typography: { - fontSize: true, - lineHeight: true, - fontFamily: true, - fontStyle: true, - fontWeight: true, - letterSpacing: true, - textTransform: true, - textDecoration: true, - __experimentalWritingMode: true, - __experimentalDefaultControls: { - fontSize: true, - fontAppearance: true, - textTransform: true, - }, + __experimentalBorder: { + color: true, + radius: false, }, border: { - color: true, - radius: true, + color: false, style: true, - width: true, - __experimentalDefaultControls: { - color: true, - radius: true, - style: true, - width: true, - }, }, }, - deprecated: [ - { - supports: { - typography: { - __experimentalFontFamily: true, - __experimentalFontStyle: true, - __experimentalFontWeight: true, - __experimentalLetterSpacing: true, - __experimentalTextTransform: true, - __experimentalTextDecoration: true, - __experimentalWritingMode: true, - }, - __experimentalBorder: { - color: true, - radius: true, - style: true, - width: true, - __experimentalDefaultControls: { - color: true, - radius: true, - style: true, - width: true, - }, - }, - }, - }, - ], }; - addFilter( - 'blocks.registerBlockType', - 'test/filterSupports', - ( settings, name ) => { - if ( name === 'test/block' && settings.supports.typography ) { - settings.supports.typography.__experimentalFontFamily = false; - settings.supports.typography.__experimentalFontStyle = false; - settings.supports.typography.__experimentalFontWeight = false; - settings.supports.__experimentalBorder = { radius: false }; - } - return settings; - } - ); - const processedBlockType = processBlockType( 'test/block', blockSettings )( { select } ); - expect( processedBlockType.deprecated[ 0 ].supports ).toEqual( { - typography: { - fontFamily: false, - fontStyle: false, - fontWeight: false, - letterSpacing: true, - textTransform: true, - textDecoration: true, - __experimentalWritingMode: true, + expect( processedBlockType.supports ).toMatchObject( { + border: { + color: false, + radius: false, + style: true, }, + } ); + + const reversedSettings = { + ...baseBlockSettings, + supports: { + border: { + color: false, + style: true, + }, + __experimentalBorder: { + color: true, + radius: false, + }, + }, + }; + + const reversedProcessedType = processBlockType( + 'test/block', + reversedSettings + )( { select } ); + + expect( reversedProcessedType.supports ).toMatchObject( { border: { color: true, radius: false, style: true, - width: true, - __experimentalDefaultControls: { - color: true, - radius: true, - style: true, - width: true, + }, + } ); + } ); + + it( 'should handle non-object config values', () => { + const blockSettings = { + ...baseBlockSettings, + supports: { + __experimentalBorder: true, + border: false, + }, + }; + + const processedBlockType = processBlockType( + 'test/block', + blockSettings + )( { select } ); + + expect( processedBlockType.supports ).toMatchObject( { + border: false, + } ); + } ); + + it( 'should not modify supports that do not need stabilization', () => { + const blockSettings = { + ...baseBlockSettings, + supports: { + align: true, + spacing: { + padding: true, + margin: true, }, }, + }; + + const processedBlockType = processBlockType( + 'test/block', + blockSettings + )( { select } ); + + expect( processedBlockType.supports ).toMatchObject( { + align: true, + spacing: { + padding: true, + margin: true, + }, } ); } ); } ); From c80275018525a85509c03830a3521f5ed99fd8fc Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Tue, 19 Nov 2024 12:58:59 +1000 Subject: [PATCH 07/11] Use stabilized defaultControls flag --- packages/block-editor/src/hooks/border.js | 10 ++-------- packages/block-editor/src/hooks/color.js | 2 +- packages/block-editor/src/hooks/dimensions.js | 4 ++-- packages/block-editor/src/hooks/typography.js | 2 +- 4 files changed, 6 insertions(+), 12 deletions(-) diff --git a/packages/block-editor/src/hooks/border.js b/packages/block-editor/src/hooks/border.js index 4500444685befa..14b3dbf7669b3a 100644 --- a/packages/block-editor/src/hooks/border.js +++ b/packages/block-editor/src/hooks/border.js @@ -161,14 +161,8 @@ export function BorderPanel( { clientId, name, setAttributes, settings } ) { } const defaultControls = { - ...getBlockSupport( name, [ - BORDER_SUPPORT_KEY, - '__experimentalDefaultControls', - ] ), - ...getBlockSupport( name, [ - SHADOW_SUPPORT_KEY, - '__experimentalDefaultControls', - ] ), + ...getBlockSupport( name, [ BORDER_SUPPORT_KEY, 'defaultControls' ] ), + ...getBlockSupport( name, [ SHADOW_SUPPORT_KEY, 'defaultControls' ] ), }; return ( diff --git a/packages/block-editor/src/hooks/color.js b/packages/block-editor/src/hooks/color.js index ef8984c9367853..2fecc10a311984 100644 --- a/packages/block-editor/src/hooks/color.js +++ b/packages/block-editor/src/hooks/color.js @@ -290,7 +290,7 @@ export function ColorEdit( { clientId, name, setAttributes, settings } ) { const defaultControls = getBlockSupport( name, [ COLOR_SUPPORT_KEY, - '__experimentalDefaultControls', + 'defaultControls', ] ); const enableContrastChecking = diff --git a/packages/block-editor/src/hooks/dimensions.js b/packages/block-editor/src/hooks/dimensions.js index ffa4048b7740e3..c98cc34e4272c8 100644 --- a/packages/block-editor/src/hooks/dimensions.js +++ b/packages/block-editor/src/hooks/dimensions.js @@ -88,11 +88,11 @@ export function DimensionsPanel( { clientId, name, setAttributes, settings } ) { const defaultDimensionsControls = getBlockSupport( name, [ DIMENSIONS_SUPPORT_KEY, - '__experimentalDefaultControls', + 'defaultControls', ] ); const defaultSpacingControls = getBlockSupport( name, [ SPACING_SUPPORT_KEY, - '__experimentalDefaultControls', + 'defaultControls', ] ); const defaultControls = { ...defaultDimensionsControls, diff --git a/packages/block-editor/src/hooks/typography.js b/packages/block-editor/src/hooks/typography.js index ab9a464fe5efbc..160894eac4e610 100644 --- a/packages/block-editor/src/hooks/typography.js +++ b/packages/block-editor/src/hooks/typography.js @@ -133,7 +133,7 @@ export function TypographyPanel( { clientId, name, setAttributes, settings } ) { const defaultControls = getBlockSupport( name, [ TYPOGRAPHY_SUPPORT_KEY, - '__experimentalDefaultControls', + 'defaultControls', ] ); return ( From d538e9a5c866dbbb0702443aa87b35d8877a0e2d Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Tue, 19 Nov 2024 13:04:58 +1000 Subject: [PATCH 08/11] Use stabilized skipSerialization flag --- docs/explanations/architecture/styles.md | 16 +++++++++------- packages/block-editor/src/hooks/style.js | 18 ++++++------------ packages/block-editor/src/hooks/test/style.js | 3 +-- packages/block-editor/src/hooks/utils.js | 2 +- .../components/global-styles/screen-block.js | 5 ++--- packages/server-side-render/README.md | 2 +- 6 files changed, 20 insertions(+), 26 deletions(-) diff --git a/docs/explanations/architecture/styles.md b/docs/explanations/architecture/styles.md index 68f09f04d21d32..5f5e73d1372f7b 100644 --- a/docs/explanations/architecture/styles.md +++ b/docs/explanations/architecture/styles.md @@ -37,8 +37,10 @@ The user may change the state of this block by applying different styles: a text After some user modifications to the block, the initial markup may become something like this: ```html -

+

``` This is what we refer to as "user-provided block styles", also know as "local styles" or "serialized styles". Essentially, each tool (font size, color, etc) ends up adding some classes and/or inline styles to the block markup. The CSS styling for these classes is part of the block, global, or theme stylesheets. @@ -123,7 +125,7 @@ The block supports API only serializes the font size value to the wrapper, resul This is an active area of work you can follow [in the tracking issue](https://github.com/WordPress/gutenberg/issues/38167). The linked proposal is exploring a different way to serialize the user changes: instead of each block support serializing its own data (for example, classes such as `has-small-font-size`, `has-green-color`) the idea is the block would get a single class instead (for example, `wp-style-UUID`) and the CSS styling for that class will be generated in the server by WordPress. -While work continues in that proposal, there's an escape hatch, an experimental option block authors can use. Any block support can skip the serialization to HTML markup by using `__experimentalSkipSerialization`. For example: +While work continues in that proposal, there's an escape hatch, an experimental option block authors can use. Any block support can skip the serialization to HTML markup by using `skipSerialization`. For example: ```json { @@ -132,7 +134,7 @@ While work continues in that proposal, there's an escape hatch, an experimental "supports": { "typography": { "fontSize": true, - "__experimentalSkipSerialization": true + "skipSerialization": true } } } @@ -140,7 +142,7 @@ While work continues in that proposal, there's an escape hatch, an experimental This means that the typography block support will do all of the things (create a UI control, bind the block attribute to the control, etc) except serializing the user values into the HTML markup. The classes and inline styles will not be automatically applied to the wrapper and it is the block author's responsibility to implement this in the `edit`, `save`, and `render_callback` functions. See [this issue](https://github.com/WordPress/gutenberg/issues/28913) for examples of how it was done for some blocks provided by WordPress. -Note that, if `__experimentalSkipSerialization` is enabled for a group (typography, color, spacing) it affects _all_ block supports within this group. In the example above _all_ the properties within the `typography` group will be affected (e.g. `fontSize`, `lineHeight`, `fontFamily` .etc). +Note that, if `skipSerialization` is enabled for a group (typography, color, spacing) it affects _all_ block supports within this group. In the example above _all_ the properties within the `typography` group will be affected (e.g. `fontSize`, `lineHeight`, `fontFamily` .etc). To enable for a _single_ property only, you may use an array to declare which properties are to be skipped. In the example below, only `fontSize` will skip serialization, leaving other items within the `typography` group (e.g. `lineHeight`, `fontFamily` .etc) unaffected. @@ -152,7 +154,7 @@ To enable for a _single_ property only, you may use an array to declare which pr "typography": { "fontSize": true, "lineHeight": true, - "__experimentalSkipSerialization": [ "fontSize" ] + "skipSerialization": [ "fontSize" ] } } } @@ -473,7 +475,7 @@ If blocks do this, they need to be registered in the server using the `block.jso Every chunk of styles can only use a single selector. -This is particularly relevant if the block is using `__experimentalSkipSerialization` to serialize the different style properties to different nodes other than the wrapper. See "Current limitations of blocks supports" for more. +This is particularly relevant if the block is using `skipSerialization` to serialize the different style properties to different nodes other than the wrapper. See "Current limitations of blocks supports" for more. #### 3. **Only a single property per block** diff --git a/packages/block-editor/src/hooks/style.js b/packages/block-editor/src/hooks/style.js index 998d13cfd22247..db2acd01665b60 100644 --- a/packages/block-editor/src/hooks/style.js +++ b/packages/block-editor/src/hooks/style.js @@ -98,22 +98,16 @@ function addAttribute( settings ) { * @type {Record} */ const skipSerializationPathsEdit = { - [ `${ BORDER_SUPPORT_KEY }.__experimentalSkipSerialization` ]: [ 'border' ], - [ `${ COLOR_SUPPORT_KEY }.__experimentalSkipSerialization` ]: [ - COLOR_SUPPORT_KEY, - ], - [ `${ TYPOGRAPHY_SUPPORT_KEY }.__experimentalSkipSerialization` ]: [ + [ `${ BORDER_SUPPORT_KEY }.skipSerialization` ]: [ 'border' ], + [ `${ COLOR_SUPPORT_KEY }.skipSerialization` ]: [ COLOR_SUPPORT_KEY ], + [ `${ TYPOGRAPHY_SUPPORT_KEY }.skipSerialization` ]: [ TYPOGRAPHY_SUPPORT_KEY, ], - [ `${ DIMENSIONS_SUPPORT_KEY }.__experimentalSkipSerialization` ]: [ + [ `${ DIMENSIONS_SUPPORT_KEY }.skipSerialization` ]: [ DIMENSIONS_SUPPORT_KEY, ], - [ `${ SPACING_SUPPORT_KEY }.__experimentalSkipSerialization` ]: [ - SPACING_SUPPORT_KEY, - ], - [ `${ SHADOW_SUPPORT_KEY }.__experimentalSkipSerialization` ]: [ - SHADOW_SUPPORT_KEY, - ], + [ `${ SPACING_SUPPORT_KEY }.skipSerialization` ]: [ SPACING_SUPPORT_KEY ], + [ `${ SHADOW_SUPPORT_KEY }.skipSerialization` ]: [ SHADOW_SUPPORT_KEY ], }; /** diff --git a/packages/block-editor/src/hooks/test/style.js b/packages/block-editor/src/hooks/test/style.js index 2cfe299b8c8d91..40e7169194b82e 100644 --- a/packages/block-editor/src/hooks/test/style.js +++ b/packages/block-editor/src/hooks/test/style.js @@ -133,8 +133,7 @@ describe( 'addSaveProps', () => { const applySkipSerialization = ( features ) => { const updatedSettings = { ...blockSettings }; Object.keys( features ).forEach( ( key ) => { - updatedSettings.supports[ key ].__experimentalSkipSerialization = - features[ key ]; + updatedSettings.supports[ key ].skipSerialization = features[ key ]; } ); return updatedSettings; }; diff --git a/packages/block-editor/src/hooks/utils.js b/packages/block-editor/src/hooks/utils.js index 4334f70b9d13bf..ac6e55efe4d3bd 100644 --- a/packages/block-editor/src/hooks/utils.js +++ b/packages/block-editor/src/hooks/utils.js @@ -124,7 +124,7 @@ export function shouldSkipSerialization( feature ) { const support = getBlockSupport( blockNameOrType, featureSet ); - const skipSerialization = support?.__experimentalSkipSerialization; + const skipSerialization = support?.skipSerialization; if ( Array.isArray( skipSerialization ) ) { return skipSerialization.includes( feature ); diff --git a/packages/edit-site/src/components/global-styles/screen-block.js b/packages/edit-site/src/components/global-styles/screen-block.js index 64f49574b6b03b..347d3cd1bc0a73 100644 --- a/packages/edit-site/src/components/global-styles/screen-block.js +++ b/packages/edit-site/src/components/global-styles/screen-block.js @@ -113,9 +113,8 @@ function ScreenBlock( { name, variation } ) { if ( settingsForBlockElement?.spacing?.blockGap && blockType?.supports?.spacing?.blockGap && - ( blockType?.supports?.spacing?.__experimentalSkipSerialization === - true || - blockType?.supports?.spacing?.__experimentalSkipSerialization?.some?.( + ( blockType?.supports?.spacing?.skipSerialization === true || + blockType?.supports?.spacing?.skipSerialization?.some?.( ( spacingType ) => spacingType === 'blockGap' ) ) ) { diff --git a/packages/server-side-render/README.md b/packages/server-side-render/README.md index ba6fae302ca0a8..ef7cd9bf0189c1 100644 --- a/packages/server-side-render/README.md +++ b/packages/server-side-render/README.md @@ -79,7 +79,7 @@ add_filter( 'rest_endpoints', 'add_rest_method'); ### skipBlockSupportAttributes -Remove attributes and style properties applied by the block supports. This prevents duplication of styles in the block wrapper and the `ServerSideRender` components. Even if certain features skip serialization to HTML markup by `__experimentalSkipSerialization`, all attributes and style properties are removed. +Remove attributes and style properties applied by the block supports. This prevents duplication of styles in the block wrapper and the `ServerSideRender` components. Even if certain features skip serialization to HTML markup by `skipSerialization`, all attributes and style properties are removed. - Type: `Boolean` - Required: No From 14bae35f15d11d8e01166eb605df382217d00386 Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Tue, 19 Nov 2024 19:22:24 +1000 Subject: [PATCH 09/11] Add to backport log --- backport-changelog/6.8/7069.md | 1 + 1 file changed, 1 insertion(+) diff --git a/backport-changelog/6.8/7069.md b/backport-changelog/6.8/7069.md index 8b4ad69db02e75..69edbde58902d1 100644 --- a/backport-changelog/6.8/7069.md +++ b/backport-changelog/6.8/7069.md @@ -2,3 +2,4 @@ https://github.com/WordPress/wordpress-develop/pull/7069 * https://github.com/WordPress/gutenberg/pull/63401 * https://github.com/WordPress/gutenberg/pull/66918 +* https://github.com/WordPress/gutenberg/pull/67018 From 8b92b76ceb0380da92fc2dc4896981908d126c67 Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Wed, 20 Nov 2024 18:11:33 +1000 Subject: [PATCH 10/11] Add explanation of order importance to inline comments --- lib/compat/wordpress-6.8/blocks.php | 7 +++++++ packages/blocks/src/store/process-block-type.js | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/lib/compat/wordpress-6.8/blocks.php b/lib/compat/wordpress-6.8/blocks.php index 7f27608efe2e2b..64e3aef01244cc 100644 --- a/lib/compat/wordpress-6.8/blocks.php +++ b/lib/compat/wordpress-6.8/blocks.php @@ -101,6 +101,13 @@ function gutenberg_stabilize_experimental_block_supports( $args ) { * are defined in to determine the final value. * - If config is an array, merge the arrays in their order of definition. * - If config is not an array, use the value defined last. + * + * The reason for preferring the last defined key is that after filters + * are applied, the last inserted key is likely the most up-to-date value. + * We cannot determine with certainty which value was "last modified" so + * the insertion order is the best guess. The extreme edge case of multiple + * filters tweaking the same support property will become less over time as + * extenders migrate existing blocks and plugins to stable keys. */ if ( $support !== $stable_support_key && isset( $args['supports'][ $stable_support_key ] ) ) { $key_positions = array_flip( array_keys( $args['supports'] ) ); diff --git a/packages/blocks/src/store/process-block-type.js b/packages/blocks/src/store/process-block-type.js index c913da6f23136a..0d7b73daa1176a 100644 --- a/packages/blocks/src/store/process-block-type.js +++ b/packages/blocks/src/store/process-block-type.js @@ -166,6 +166,13 @@ function stabilizeSupports( rawSupports ) { * are defined in to determine the final value. * - If config is an array, merge the arrays in their order of definition. * - If config is not an array, use the value defined last. + * + * The reason for preferring the last defined key is that after filters + * are applied, the last inserted key is likely the most up-to-date value. + * We cannot determine with certainty which value was "last modified" so + * the insertion order is the best guess. The extreme edge case of multiple + * filters tweaking the same support property will become less over time as + * extenders migrate existing blocks and plugins to stable keys. */ if ( support !== stableSupportKey && From f502d300ba098c3308c7ada4f7e3c81718300e4e Mon Sep 17 00:00:00 2001 From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com> Date: Thu, 21 Nov 2024 15:36:40 +1000 Subject: [PATCH 11/11] Improve comments --- lib/compat/wordpress-6.8/blocks.php | 5 +++-- packages/blocks/src/store/process-block-type.js | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/lib/compat/wordpress-6.8/blocks.php b/lib/compat/wordpress-6.8/blocks.php index 64e3aef01244cc..4d4bdee2bb393b 100644 --- a/lib/compat/wordpress-6.8/blocks.php +++ b/lib/compat/wordpress-6.8/blocks.php @@ -97,8 +97,9 @@ function gutenberg_stabilize_experimental_block_supports( $args ) { $stable_config = is_array( $config ) ? $stabilize_config( $config, $stable_support_key ) : $config; /* - * When both experimental and stable configs are present, use the order they - * are defined in to determine the final value. + * If a plugin overrides the support config with the `register_block_type_args` + * filter, both experimental and stable configs may be present. In that case, + * use the order keys are defined in to determine the final value. * - If config is an array, merge the arrays in their order of definition. * - If config is not an array, use the value defined last. * diff --git a/packages/blocks/src/store/process-block-type.js b/packages/blocks/src/store/process-block-type.js index 0d7b73daa1176a..0ca28a3c3e2070 100644 --- a/packages/blocks/src/store/process-block-type.js +++ b/packages/blocks/src/store/process-block-type.js @@ -162,8 +162,9 @@ function stabilizeSupports( rawSupports ) { : config; /* - * When both experimental and stable configs are present, use the order they - * are defined in to determine the final value. + * If a plugin overrides the support config with the `blocks.registerBlockType` + * filter, both experimental and stable configs may be present. In that case, + * use the order keys are defined in to determine the final value. * - If config is an array, merge the arrays in their order of definition. * - If config is not an array, use the value defined last. *