Image block: UI updates for the image lightbox

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, behaviors, 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

@@ -172,6 +172,20 @@ Settings related to typography.
 Generate custom CSS custom properties of the form `--wp--custom--{key}--{nested-key}: {value};`. `camelCased` keys are transformed to `kebab-case` as to follow the CSS property naming schema. Keys at different depth levels are separated by `--`, so keys should not include `--` in the name.
 
 
+---
+
+### enabled
+
+Defines whether the lightbox is enabled or not.
+
+
+---
+
+### allowEditing
+
+Defines whether to show the Lightbox UI in the block editor. If set to `false`, the user won't be able to change the lightbox settings in the block editor.
+
+
 ---
 ## Styles
 

lib/blocks.php

@@ -431,4 +431,72 @@ 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 );
+
+
+/**
+ * Check if the lightbox should be rendered for a given 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.
+ *
+ * @param array $block The block to check.
+ * @return array The block with the lightboxEnabled flag set if the lightbox should be rendered.
+ */
+function gutenberg_should_render_lightbox( $block ) {
+
+	if ( 'core/image' !== $block['blockName'] ) {
+		return $block;
+	}
+
+	// Get the lightbox setting from the block attributes.
+	if ( isset( $block['attrs']['lightbox'] ) ) {
+		$lightbox_settings = $block['attrs']['lightbox'];
+		// If not present, check legacy syntax.
+	} elseif ( isset( $block['attrs']['behaviors']['lightbox'] ) ) {
+		$lightbox_settings = $block['attrs']['behaviors']['lightbox'];
+	}
+
+	// If not present in block attributes, check global settings.
+	if ( ! isset( $lightbox_settings ) ) {
+		$lightbox_settings = gutenberg_get_global_settings( array( 'lightbox' ), array( 'block_name' => 'core/image' ) );
+
+		// If not present in global settings, check the top-level global settings.
+		if ( ! isset( $lightbox_settings['enabled'] ) ) {
+			$lightbox_settings = gutenberg_get_global_settings( array( 'lightbox' ) );
+		}
+	}
+
+	// If not present in global settings, check legacy syntax.
+	if ( ! isset( $lightbox_settings['enabled'] ) ) {
+		$theme_data = WP_Theme_JSON_Resolver_Gutenberg::get_merged_data()->get_data();
+		if ( isset( $theme_data['behaviors']['blocks'][ $block['blockName'] ]['lightbox'] ) ) {
+			$lightbox_settings = $theme_data['behaviors']['blocks'][ $block['blockName'] ]['lightbox'];
+		}
+	}
+
+	$link_destination = isset( $block['attrs']['linkDestination'] ) ? $block['attrs']['linkDestination'] : 'none';
+
+	// If the lightbox is enabled, the image is not linked, flag the lightbox to be rendered.
+	if ( isset( $lightbox_settings['enabled'] ) &&
+		true === $lightbox_settings['enabled'] &&
+		'none' === $link_destination
+	) {
+		$block['lightboxEnabled'] = true;
+
+		// The legacy syntax allows setting the animation type.
+		if ( isset( $lightbox_settings['animation'] ) ) {
+			$block['lightboxAnimation'] = $lightbox_settings['animation'];
+		}
+	}
+
+	return $block;
+}
+
+// Run with a priority of 15 to ensure it runs after
+// `block_core_image_should_render_lightbox` core filter (that has a
+// priority of 10).
+add_filter( 'render_block_data', 'gutenberg_should_render_lightbox', 15, 1 );

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

@@ -331,6 +331,7 @@ class WP_Theme_JSON_Gutenberg {
 		'templateParts',
 		'title',
 		'version',
+		'behaviors',
 	);
 
 	/**
@@ -346,6 +347,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.enabled` and `lightbox.allowEditing`.
 	 * @var array
 	 */
 	const VALID_SETTINGS = array(
@@ -383,6 +385,10 @@ class WP_Theme_JSON_Gutenberg {
 			'wideSize'     => null,
 			'allowEditing' => null,
 		),
+		'lightbox'                      => array(
+			'enabled'      => null,
+			'allowEditing' => null,
+		),
 		'position'                      => array(
 			'fixed'  => null,
 			'sticky' => null,
@@ -415,6 +421,7 @@ class WP_Theme_JSON_Gutenberg {
 			'textTransform'  => null,
 			'writingMode'    => null,
 		),
+		'behaviors'                     => null,
 	);
 
 	/**

lib/theme.json

@@ -273,6 +273,12 @@
 					"radius": true
 				}
 			},
+			"core/image": {
+				"lightbox": {
+					"enabled": null,
+					"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',

packages/block-editor/src/components/global-styles/image-settings-panel.js

@@ -0,0 +1,54 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	__experimentalToolsPanel as ToolsPanel,
+	__experimentalToolsPanelItem as ToolsPanelItem,
+	ToggleControl,
+} from '@wordpress/components';
+import { __, _x } from '@wordpress/i18n';
+
+export function useHasImageSettingsPanel( name, settings ) {
+	return name === 'core/image' && settings?.lightbox?.allowEditing;
+}
+
+export default function ImageSettingsPanel( {
+	onChange,
+	userSettings,
+	settings,
+	panelId,
+} ) {
+	const resetLightbox = () => {
+		onChange( undefined );
+	};
+
+	const onChangeLightbox = ( newSetting ) => {
+		onChange( {
+			enabled: newSetting,
+		} );
+	};
+
+	return (
+		<>
+			<ToolsPanel
+				label={ _x( 'Settings', 'Image settings' ) }
+				resetAll={ resetLightbox }
+				panelId={ panelId }
+			>
+				<ToolsPanelItem
+					hasValue={ () => !! userSettings?.lightbox }
+					label={ __( 'Expand on Click' ) }
+					onDeselect={ resetLightbox }
+					isShownByDefault={ true }
+					panelId={ panelId }
+				>
+					<ToggleControl
+						label={ __( 'Expand on Click' ) }
+						checked={ !! settings?.lightbox?.enabled }
+						onChange={ onChangeLightbox }
+					/>
+				</ToolsPanelItem>
+			</ToolsPanel>
+		</>
+	);
+}

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

@@ -23,5 +23,9 @@ export { default as BorderPanel, useHasBorderPanel } from './border-panel';
 export { default as ColorPanel, useHasColorPanel } from './color-panel';
 export { default as EffectsPanel, useHasEffectsPanel } from './effects-panel';
 export { default as FiltersPanel, useHasFiltersPanel } from './filters-panel';
+export {
+	default as ImageSettingsPanel,
+	useHasImageSettingsPanel,
+} from './image-settings-panel';
 export { default as AdvancedPanel } from './advanced-panel';
 export { areGlobalStyleConfigsEqual } from './utils';

packages/block-library/src/image/block.json

@@ -33,6 +33,15 @@
 			"selector": "figcaption",
 			"__experimentalRole": "content"
 		},
+		"behaviors": {
+			"type": "object"
+		},
+		"lightbox": {
+			"type": "object",
+			"enabled": {
+				"type": "boolean"
+			}
+		},
 		"title": {
 			"type": "string",
 			"source": "attribute",

packages/block-library/src/image/image.js

@@ -7,6 +7,7 @@ import {
 	ResizableBox,
 	Spinner,
 	TextareaControl,
+	ToggleControl,
 	TextControl,
 	ToolbarButton,
 	ToolbarGroup,
@@ -23,6 +24,7 @@ import {
 	__experimentalImageURLInputUI as ImageURLInputUI,
 	MediaReplaceFlow,
 	store as blockEditorStore,
+	useSetting,
 	BlockAlignmentControl,
 	__experimentalImageEditor as ImageEditor,
 	__experimentalGetElementClassName,
@@ -65,6 +67,7 @@ import { isExternalImage } from './edit';
  */
 import { MIN_SIZE, ALLOWED_MEDIA_TYPES } from './constants';
 import { evalAspectRatio } from './utils';
+import deprecated from '@wordpress/deprecated';
 
 const { DimensionsTool, ResolutionTool } = unlock( blockEditorPrivateApis );
 
@@ -113,6 +116,7 @@ export default function Image( {
 		scale,
 		linkTarget,
 		sizeSlug,
+		lightbox,
 	} = attributes;
 
 	// The only supported unit is px, so we can parseInt to strip the px here.
@@ -171,6 +175,7 @@ export default function Image( {
 			},
 			[ clientId ]
 		);
+
 	const { replaceBlocks, toggleSelection } = useDispatch( blockEditorStore );
 	const { createErrorNotice, createSuccessNotice } =
 		useDispatch( noticesStore );
@@ -365,6 +370,18 @@ export default function Image( {
 		availableUnits: [ 'px' ],
 	} );
 
+	const lightboxSetting = useSetting( 'lightbox' );
+
+	const lightboxChecked = useMemo( () => {
+		// If the lightbox is set in the block attributes, use that.
+		if ( lightbox?.enabled ) return true;
+
+		// If the lightbox is NOT set in the block attributes AND it IS enabled in
+		// the settings, use that.
+		if ( ! lightbox && lightboxSetting?.enabled ) return true;
+		return false;
+	}, [ lightbox, lightboxSetting ] );
+
 	const controls = (
 		<>
 			<BlockControls group="block">
@@ -451,6 +468,7 @@ export default function Image( {
 							height: undefined,
 							scale: undefined,
 							aspectRatio: undefined,
+							lightbox: undefined,
 						} )
 					}
 				>
@@ -519,6 +537,24 @@ export default function Image( {
 						onChange={ updateImage }
 						options={ imageSizeOptions }
 					/>
+					<ToolsPanelItem
+						hasValue={ () => !! lightbox }
+						label={ __( 'Expand on Click' ) }
+						onDeselect={ () => {
+							setAttributes( { lightbox: undefined } );
+						} }
+						isShownByDefault={ true }
+					>
+						<ToggleControl
+							label={ __( 'Expand on Click' ) }
+							checked={ lightboxChecked }
+							onChange={ ( newValue ) => {
+								setAttributes( {
+									lightbox: { enabled: newValue },
+								} );
+							} }
+						/>
+					</ToolsPanelItem>
 				</ToolsPanel>
 			</InspectorControls>
 			<InspectorControls group="advanced">
@@ -726,6 +762,22 @@ export default function Image( {
 		);
 	}
 
+	const { behaviors } = attributes;
+
+	if ( behaviors ) {
+		deprecated( 'Lightbox using `behaviors` syntax', {
+			since: '16.7 on 2023.09.27',
+			version: '16.9 on 2023.10.11',
+			alternative: 'new lightbox syntax',
+			plugin: 'Gutenberg',
+			link: 'https://github.com/WordPress/gutenberg/pull/54071',
+			hint: `You can update your lightbox settings with the new syntax
+				   by toggling the image block's Expand on Click setting in the global styles
+				   or block settings, or by modifying settings in theme.json with
+				   { 'blocks': { 'core/image' :  { 'lightbox' : { 'enabled': true | false } } } }`,
+		} );
+	}
+
 	return (
 		<>
 			{ /* Hide controls during upload to avoid component remount,