Image block: UI updates for the image lightbox (redo)

docs/reference-guides/core-blocks.md

@@ -2,10 +2,9 @@
 
 This page lists the blocks included in the block-library package.
 
--	Items marked with a strikeout (~~strikeout~~) are explicitly disabled.
--	Blocks marked with **Experimental:** true are only available when Gutenberg is active.
--	Blocks marked with **Experimental:** fse are only available in the Site Editor.
-
+-   Items marked with a strikeout (~~strikeout~~) are explicitly disabled.
+-   Blocks marked with **Experimental:** true are only available when Gutenberg is active.
+-   Blocks marked with **Experimental:** fse are only available in the Site Editor.
 
 <!-- START TOKEN Autogenerated - DO NOT EDIT -->
 
@@ -340,7 +339,7 @@ Insert an image to make a visual statement. ([Source](https://github.com/WordPre
 -	**Name:** core/image
 -	**Category:** media
 -	**Supports:** anchor, color (~~background~~, ~~text~~), filter (duotone)
--	**Attributes:** align, alt, aspectRatio, caption, height, href, id, linkClass, linkDestination, linkTarget, rel, scale, sizeSlug, title, url, width
+-	**Attributes:** align, alt, aspectRatio, caption, height, href, id, lightbox, linkClass, linkDestination, linkTarget, rel, scale, sizeSlug, title, url, width
 
 ## Latest Comments
 

docs/reference-guides/theme-json-reference/theme-json-living.md

@@ -130,6 +130,17 @@ Settings related to layout.
 
 ---
 
+### lightbox
+
+Settings related to the lightbox.
+
+| Property  | Type   | Default | Props  |
+| ---       | ---    | ---    |---   |
+| enabled | boolean |  |  |
+| allowEditing | boolean |  |  |
+
+---
+
 ### position
 
 Settings related to position.

lib/block-supports/behaviors.php

@@ -2,6 +2,10 @@
 /**
  * Behaviors block support flag.
  *
+ * This file will NOT be backported to Core. It exists to provide a
+ * migration path for theme.json files that used the deprecated "behaviors".
+ * This file will be removed from Gutenberg in version 17.0.0.
+ *
  * @package gutenberg
  */
 
@@ -37,13 +41,23 @@ function gutenberg_register_behaviors_support( $block_type ) {
 
 /**
  * Add the directives and layout needed for the lightbox behavior.
- * This functions shouldn't be in this file. It should be moved to a package (or somewhere else), where all the behaviors logic is defined.
  *
  * @param  string $block_content Rendered block content.
  * @param  array  $block         Block object.
  * @return string                Filtered block content.
  */
 function gutenberg_render_behaviors_support_lightbox( $block_content, $block ) {
+
+	// We've deprecated the lightbox implementation via behaviors.
+	// While we may continue to explore behaviors in the future, the lightbox
+	// logic seems very specific to the image and will likely never be a part
+	// of behaviors, even in the future. With that in mind, we've rewritten the lightbox
+	// to be a feature of the image block and will also soon remove the block_supports.
+	// *Note: This logic for generating the lightbox markup has been duplicated and moved
+	// to the image block's index.php.*
+	// See https://github.com/WordPress/gutenberg/issues/53403.
+	_deprecated_function( 'gutenberg_render_behaviors_support_lightbox', 'Gutenberg 17.0.0', '' );
+
 	$link_destination = isset( $block['attrs']['linkDestination'] ) ? $block['attrs']['linkDestination'] : 'none';
 	// Get the lightbox setting from the block attributes.
 	if ( isset( $block['attrs']['behaviors']['lightbox'] ) ) {

lib/blocks.php

@@ -431,4 +431,33 @@ function gutenberg_legacy_wp_block_post_meta( $value, $object_id, $meta_key, $si
 
 	return $value;
 }
+
 add_filter( 'default_post_metadata', 'gutenberg_legacy_wp_block_post_meta', 10, 4 );
+
+/**
+ * Complements the lightbox implementation for the 'core/image' block.
+ *
+ * This function is INTENTIONALLY left out of core as it only provides
+ * backwards compatibility for the legacy lightbox syntax that was only
+ * introduced in Gutenberg. The legacy syntax was using the `behaviors` key in
+ * the block attrbutes and the `theme.json` file.
+ *
+ * @since 16.7.0
+ *
+ * @param array $block The block to check.
+ * @return array The block with the legacyLightboxSettings set if available.
+ */
+function gutenberg_should_render_lightbox( $block ) {
+
+	if ( 'core/image' !== $block['blockName'] ) {
+		return $block;
+	}
+
+	if ( isset( $block['attrs']['behaviors']['lightbox'] ) ) {
+		$block['legacyLightboxSettings'] = $block['attrs']['behaviors']['lightbox'];
+	}
+
+	return $block;
+}
+
+add_filter( 'render_block_data', 'gutenberg_should_render_lightbox', 15, 1 );

lib/class-wp-theme-json-gutenberg.php

@@ -346,6 +346,7 @@ class WP_Theme_JSON_Gutenberg {
 	 *              `position.fixed` and `position.sticky`.
 	 * @since 6.3.0 Removed `layout.definitions`. Added `typography.writingMode`.
 	 * @since 6.4.0 Added `layout.allowEditing`.
+	 * @since 6.4.0 Added `lightbox`.
 	 * @var array
 	 */
 	const VALID_SETTINGS = array(
@@ -386,6 +387,10 @@ class WP_Theme_JSON_Gutenberg {
 			'wideSize'     => null,
 			'allowEditing' => null,
 		),
+		'lightbox'                      => array(
+			'enabled'      => null,
+			'allowEditing' => null,
+		),
 		'position'                      => array(
 			'fixed'  => null,
 			'sticky' => null,
@@ -616,7 +621,7 @@ public function __construct( $theme_json = array(), $origin = 'theme' ) {
 			$origin = 'theme';
 		}
 
-		$this->theme_json    = WP_Theme_JSON_Schema::migrate( $theme_json );
+		$this->theme_json    = WP_Theme_JSON_Schema_Gutenberg::migrate( $theme_json );
 		$registry            = WP_Block_Type_Registry::get_instance();
 		$valid_block_names   = array_keys( $registry->get_all_registered() );
 		$valid_element_names = array_keys( static::ELEMENTS );
@@ -2859,7 +2864,7 @@ protected static function filter_slugs( $node, $slugs ) {
 	public static function remove_insecure_properties( $theme_json ) {
 		$sanitized = array();
 
-		$theme_json = WP_Theme_JSON_Schema::migrate( $theme_json );
+		$theme_json = WP_Theme_JSON_Schema_Gutenberg::migrate( $theme_json );
 
 		$valid_block_names   = array_keys( static::get_blocks_metadata() );
 		$valid_element_names = array_keys( static::ELEMENTS );

lib/class-wp-theme-json-schema-gutenberg.php

@@ -0,0 +1,202 @@
+<?php
+/**
+ * WP_Theme_JSON_Schema_Gutenberg class
+ *
+ * This class/file will NOT be backported to Core. It exists to provide a
+ * migration path for theme.json files that used the deprecated "behaviors".
+ * This file will be removed from Gutenberg in version 17.0.0.
+ *
+ * @package gutenberg
+ * @since 16.7.0
+ */
+
+if ( class_exists( 'WP_Theme_JSON_Schema_Gutenberg' ) ) {
+	return;
+}
+
+/**
+ * Class that migrates a given theme.json structure to the latest schema.
+ *
+ * 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.
+ *
+ * @since 5.9.0
+ * @access private
+ */
+#[AllowDynamicProperties]
+class WP_Theme_JSON_Schema_Gutenberg {
+
+	/**
+	 * Maps old properties to their new location within the schema's settings.
+	 * This will be applied at both the defaults and individual block levels.
+	 */
+	const V1_TO_V2_RENAMED_PATHS = array(
+		'border.customRadius'         => 'border.radius',
+		'spacing.customMargin'        => 'spacing.margin',
+		'spacing.customPadding'       => 'spacing.padding',
+		'typography.customLineHeight' => 'typography.lineHeight',
+	);
+
+	/**
+	 * Function that migrates a given theme.json structure to the last version.
+	 *
+	 * @since 5.9.0
+	 *
+	 * @param array $theme_json The structure to migrate.
+	 *
+	 * @return array The structure in the last version.
+	 */
+	public static function migrate( $theme_json ) {
+		if ( ! isset( $theme_json['version'] ) ) {
+			$theme_json = array(
+				'version' => WP_Theme_JSON::LATEST_SCHEMA,
+			);
+		}
+
+		if ( 1 === $theme_json['version'] ) {
+			$theme_json = self::migrate_v1_to_v2( $theme_json );
+		}
+
+		if ( 2 === $theme_json['version'] ) {
+			$theme_json = self::migrate_deprecated_lightbox_behaviors( $theme_json );
+		}
+
+		return $theme_json;
+	}
+
+	/**
+	 * Removes the custom prefixes for a few properties
+	 * that were part of v1:
+	 *
+	 * 'border.customRadius'         => 'border.radius',
+	 * 'spacing.customMargin'        => 'spacing.margin',
+	 * 'spacing.customPadding'       => 'spacing.padding',
+	 * 'typography.customLineHeight' => 'typography.lineHeight',
+	 *
+	 * @since 5.9.0
+	 *
+	 * @param array $old Data to migrate.
+	 *
+	 * @return array Data without the custom prefixes.
+	 */
+	private static function migrate_v1_to_v2( $old ) {
+		// Copy everything.
+		$new = $old;
+
+		// Overwrite the things that changed.
+		if ( isset( $old['settings'] ) ) {
+			$new['settings'] = self::rename_paths( $old['settings'], self::V1_TO_V2_RENAMED_PATHS );
+		}
+
+		// Set the new version.
+		$new['version'] = 2;
+
+		return $new;
+	}
+
+
+	/**
+	 * Migrate away from the previous syntax that used a top-level "behaviors" key
+	 * in the `theme.json` to a new "lightbox" setting.
+	 *
+	 * This function SHOULD NOT be ported to Core!!!
+	 *
+	 * It is a temporary migration that will be removed in Gutenberg 17.0.0
+	 *
+	 * @since 16.7.0
+	 *
+	 * @param array $old Data with (potentially) behaviors.
+	 * @return array Data with behaviors removed.
+	 */
+	private static function migrate_deprecated_lightbox_behaviors( $old ) {
+		// Copy everything.
+		$new = $old;
+
+		// Migrate the old behaviors syntax to the new "lightbox" syntax.
+		if ( isset( $old['behaviors']['blocks']['core/image']['lightbox']['enabled'] ) ) {
+			_wp_array_set(
+				$new,
+				array( 'settings', 'blocks', 'core/image', 'lightbox', 'enabled' ),
+				$old['behaviors']['blocks']['core/image']['lightbox']['enabled']
+			);
+		}
+
+		// Migrate the behaviors setting to the new syntax. This setting controls
+		// whether the Lightbox UI shows up in the block editor.
+		if ( isset( $old['settings']['blocks']['core/image']['behaviors']['lightbox'] ) ) {
+			_wp_array_set(
+				$new,
+				array( 'settings', 'blocks', 'core/image', 'lightbox', 'allowEditing' ),
+				$old['settings']['blocks']['core/image']['behaviors']['lightbox']
+			);
+		}
+
+		return $new;
+	}
+
+	/**
+	 * Processes the settings subtree.
+	 *
+	 * @since 5.9.0
+	 *
+	 * @param array $settings        Array to process.
+	 * @param array $paths_to_rename Paths to rename.
+	 *
+	 * @return array The settings in the new format.
+	 */
+	private static function rename_paths( $settings, $paths_to_rename ) {
+		$new_settings = $settings;
+
+		// Process any renamed/moved paths within default settings.
+		self::rename_settings( $new_settings, $paths_to_rename );
+
+		// Process individual block settings.
+		if ( isset( $new_settings['blocks'] ) && is_array( $new_settings['blocks'] ) ) {
+			foreach ( $new_settings['blocks'] as &$block_settings ) {
+				self::rename_settings( $block_settings, $paths_to_rename );
+			}
+		}
+
+		return $new_settings;
+	}
+
+	/**
+	 * Processes a settings array, renaming or moving properties.
+	 *
+	 * @since 5.9.0
+	 *
+	 * @param array $settings        Reference to settings either defaults or an individual block's.
+	 * @param array $paths_to_rename Paths to rename.
+	 */
+	private static function rename_settings( &$settings, $paths_to_rename ) {
+		foreach ( $paths_to_rename as $original => $renamed ) {
+			$original_path = explode( '.', $original );
+			$renamed_path  = explode( '.', $renamed );
+			$current_value = _wp_array_get( $settings, $original_path, null );
+
+			if ( null !== $current_value ) {
+				_wp_array_set( $settings, $renamed_path, $current_value );
+				self::unset_setting_by_path( $settings, $original_path );
+			}
+		}
+	}
+
+	/**
+	 * Removes a property from within the provided settings by its path.
+	 *
+	 * @since 5.9.0
+	 *
+	 * @param array $settings Reference to the current settings array.
+	 * @param array $path Path to the property to be removed.
+	 */
+	private static function unset_setting_by_path( &$settings, $path ) {
+		$tmp_settings = &$settings; // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
+		$last_key     = array_pop( $path );
+		foreach ( $path as $key ) {
+			$tmp_settings = &$tmp_settings[ $key ];
+		}
+
+		unset( $tmp_settings[ $last_key ] );
+	}
+}

lib/load.php

@@ -200,6 +200,7 @@ function gutenberg_is_experiment_enabled( $name ) {
 require __DIR__ . '/global-styles-and-settings.php';
 require __DIR__ . '/class-wp-theme-json-data-gutenberg.php';
 require __DIR__ . '/class-wp-theme-json-gutenberg.php';
+require __DIR__ . '/class-wp-theme-json-schema-gutenberg.php';
 require __DIR__ . '/class-wp-theme-json-resolver-gutenberg.php';
 require __DIR__ . '/class-wp-duotone-gutenberg.php';
 require __DIR__ . '/blocks.php';

lib/theme.json

@@ -273,6 +273,11 @@
 					"radius": true
 				}
 			},
+			"core/image": {
+				"lightbox": {
+					"allowEditing": true
+				}
+			},
 			"core/pullquote": {
 				"border": {
 					"color": true,

packages/block-editor/src/components/global-styles/hooks.js

@@ -50,6 +50,8 @@ const VALID_SETTINGS = [
 	'layout.contentSize',
 	'layout.definitions',
 	'layout.wideSize',
+	'lightbox.enabled',
+	'lightbox.allowEditing',
 	'position.fixed',
 	'position.sticky',
 	'spacing.customSpacingSize',