Add image block aspect ratio control

docs/reference-guides/core-blocks.md

@@ -340,7 +340,7 @@ Insert an image to make a visual statement. ([Source](https://github.com/WordPre
 -	**Name:** core/image
 -	**Category:** media
 -	**Supports:** anchor, behaviors (lightbox), color (~~background~~, ~~text~~), filter (duotone)
--	**Attributes:** align, alt, caption, height, href, id, linkClass, linkDestination, linkTarget, rel, sizeSlug, title, url, width
+-	**Attributes:** align, alt, aspectRatio, caption, height, href, id, linkClass, linkDestination, linkTarget, rel, scale, sizeSlug, title, url, width
 
 ## Latest Comments
 

packages/block-editor/package.json

@@ -32,6 +32,7 @@
 	],
 	"dependencies": {
 		"@babel/runtime": "^7.16.0",
+		"@emotion/styled": "^11.6.0",
 		"@react-spring/web": "^9.4.5",
 		"@wordpress/a11y": "file:../a11y",
 		"@wordpress/api-fetch": "file:../api-fetch",

packages/block-editor/src/components/dimensions-tool/aspect-ratio-tool.js

@@ -0,0 +1,124 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	SelectControl,
+	__experimentalToolsPanelItem as ToolsPanelItem,
+} from '@wordpress/components';
+import { __, _x } from '@wordpress/i18n';
+
+/**
+ * @typedef {import('@wordpress/components/build-types/select-control/types').SelectControlProps} SelectControlProps
+ */
+
+/**
+ * @type {SelectControlProps[]}
+ */
+export const DEFAULT_ASPECT_RATIO_OPTIONS = [
+	{
+		label: _x( 'Original', 'Aspect ratio option for dimensions control' ),
+		value: 'auto',
+	},
+	{
+		label: _x(
+			'Square - 1:1',
+			'Aspect ratio option for dimensions control'
+		),
+		value: '1',
+	},
+	{
+		label: _x(
+			'Standard - 4:3',
+			'Aspect ratio option for dimensions control'
+		),
+		value: '4/3',
+	},
+	{
+		label: _x(
+			'Portrait - 3:4',
+			'Aspect ratio option for dimensions control'
+		),
+		value: '3/4',
+	},
+	{
+		label: _x(
+			'Classic - 3:2',
+			'Aspect ratio option for dimensions control'
+		),
+		value: '3/2',
+	},
+	{
+		label: _x(
+			'Classic Portrait - 2:3',
+			'Aspect ratio option for dimensions control'
+		),
+		value: '2/3',
+	},
+	{
+		label: _x(
+			'Wide - 16:9',
+			'Aspect ratio option for dimensions control'
+		),
+		value: '16/9',
+	},
+	{
+		label: _x(
+			'Tall - 9:16',
+			'Aspect ratio option for dimensions control'
+		),
+		value: '9/16',
+	},
+	{
+		label: _x( 'Custom', 'Aspect ratio option for dimensions control' ),
+		value: 'custom',
+		disabled: true,
+		hidden: true,
+	},
+];
+
+/**
+ * @callback AspectRatioToolPropsOnChange
+ * @param {string} [value] New aspect ratio value.
+ * @return {void} No return.
+ */
+
+/**
+ * @typedef {Object} AspectRatioToolProps
+ * @property {string}                       [panelId]          ID of the panel this tool is associated with.
+ * @property {string}                       [value]            Current aspect ratio value.
+ * @property {AspectRatioToolPropsOnChange} [onChange]         Callback to update the aspect ratio value.
+ * @property {SelectControlProps[]}         [options]          Aspect ratio options.
+ * @property {string}                       [defaultValue]     Default aspect ratio value.
+ * @property {boolean}                      [isShownByDefault] Whether the tool is shown by default.
+ */
+
+export default function AspectRatioTool( {
+	panelId,
+	value,
+	onChange = () => {},
+	options = DEFAULT_ASPECT_RATIO_OPTIONS,
+	defaultValue = DEFAULT_ASPECT_RATIO_OPTIONS[ 0 ].value,
+	isShownByDefault = true,
+} ) {
+	// Match the CSS default so if the value is used directly in CSS it will look correct in the control.
+	const displayValue = value ?? 'auto';
+
+	return (
+		<ToolsPanelItem
+			hasValue={ () => displayValue !== defaultValue }
+			label={ __( 'Aspect ratio' ) }
+			onDeselect={ () => onChange( undefined ) }
+			isShownByDefault={ isShownByDefault }
+			panelId={ panelId }
+		>
+			<SelectControl
+				label={ __( 'Aspect ratio' ) }
+				value={ displayValue }
+				options={ options }
+				onChange={ onChange }
+				size={ '__unstable-large' }
+				__nextHasNoMarginBottom
+			/>
+		</ToolsPanelItem>
+	);
+}

packages/block-editor/src/components/dimensions-tool/index.js

@@ -0,0 +1,212 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import AspectRatioTool from './aspect-ratio-tool';
+import ScaleTool from './scale-tool';
+import WidthHeightTool from './width-height-tool';
+
+/**
+ * @typedef {import('@wordpress/components/build-types/select-control/types').SelectControlProps} SelectControlProps
+ */
+
+/**
+ * @typedef {import('@wordpress/components/build-types/unit-control/types').WPUnitControlUnit} WPUnitControlUnit
+ */
+
+/**
+ * @typedef {Object} Dimensions
+ * @property {string} [width]       CSS width property.
+ * @property {string} [height]      CSS height property.
+ * @property {string} [scale]       CSS object-fit property.
+ * @property {string} [aspectRatio] CSS aspect-ratio property.
+ */
+
+/**
+ * @callback DimensionsControlsOnChange
+ * @param {Dimensions} nextValue
+ * @return {void}
+ */
+
+/**
+ * @typedef {Object} DimensionsControlsProps
+ * @property {string}                     [panelId]            ID of the panel that contains the controls.
+ * @property {Dimensions}                 [value]              Current dimensions values.
+ * @property {DimensionsControlsOnChange} [onChange]           Callback to update the dimensions values.
+ * @property {SelectControlProps[]}       [aspectRatioOptions] Aspect ratio options.
+ * @property {SelectControlProps[]}       [scaleOptions]       Scale options.
+ * @property {WPUnitControlUnit[]}        [unitsOptions]       Units options.
+ */
+
+/**
+ * Component that renders controls to edit the dimensions of an image or container.
+ *
+ * @param {DimensionsControlsProps} props The component props.
+ *
+ * @return {WPElement} The dimensions controls.
+ */
+function DimensionsTool( {
+	panelId,
+	value = {},
+	onChange = () => {},
+	aspectRatioOptions, // Default options handled by AspectRatioTool.
+	defaultAspectRatio = 'auto', // Match CSS default value for aspect-ratio.
+	scaleOptions, // Default options handled by ScaleTool.
+	defaultScale = 'fill', // Match CSS default value for object-fit.
+	unitsOptions, // Default options handled by UnitControl.
+} ) {
+	// Coerce undefined and CSS default values to be null.
+	const width =
+		value.width === undefined || value.width === 'auto'
+			? null
+			: value.width;
+	const height =
+		value.height === undefined || value.height === 'auto'
+			? null
+			: value.height;
+	const aspectRatio =
+		value.aspectRatio === undefined || value.aspectRatio === 'auto'
+			? null
+			: value.aspectRatio;
+	const scale =
+		value.scale === undefined || value.scale === 'fill'
+			? null
+			: value.scale;
+
+	// Keep track of state internally, so when the value is cleared by means
+	// other than directly editing that field, it's easier to restore the
+	// previous value.
+	const [ lastScale, setLastScale ] = useState( scale );
+	const [ lastAspectRatio, setLastAspectRatio ] = useState( aspectRatio );
+
+	// 'custom' is not a valid value for CSS aspect-ratio, but it is used in the
+	// dropdown to indicate that setting both the width and height is the same
+	// as a custom aspect ratio.
+	const aspectRatioValue = width && height ? 'custom' : lastAspectRatio;
+
+	const showScaleControl = aspectRatio || ( width && height );
+
+	return (
+		<>
+			<AspectRatioTool
+				panelId={ panelId }
+				options={ aspectRatioOptions }
+				defaultValue={ defaultAspectRatio }
+				value={ aspectRatioValue }
+				onChange={ ( nextAspectRatio ) => {
+					const nextValue = { ...value };
+
+					// 'auto' is CSS default, so it gets treated as null.
+					nextAspectRatio =
+						nextAspectRatio === 'auto' ? null : nextAspectRatio;
+
+					setLastAspectRatio( nextAspectRatio );
+
+					// Update aspectRatio.
+					if ( ! nextAspectRatio ) {
+						delete nextValue.aspectRatio;
+					} else {
+						nextValue.aspectRatio = nextAspectRatio;
+					}
+
+					// Auto-update scale.
+					if ( ! nextAspectRatio ) {
+						delete nextValue.scale;
+					} else if ( lastScale ) {
+						nextValue.scale = lastScale;
+					} else {
+						nextValue.scale = defaultScale;
+						setLastScale( defaultScale );
+					}
+
+					// Auto-update width and height.
+					if ( nextAspectRatio && width && height ) {
+						delete nextValue.height;
+					}
+
+					onChange( nextValue );
+				} }
+			/>
+			{ showScaleControl && (
+				<ScaleTool
+					panelId={ panelId }
+					options={ scaleOptions }
+					defaultValue={ defaultScale }
+					value={ lastScale }
+					onChange={ ( nextScale ) => {
+						const nextValue = { ...value };
+
+						// 'fill' is CSS default, so it gets treated as null.
+						nextScale = nextScale === 'fill' ? null : nextScale;
+
+						setLastScale( nextScale );
+
+						// Update scale.
+						if ( ! nextScale ) {
+							delete nextValue.scale;
+						} else {
+							nextValue.scale = nextScale;
+						}
+
+						onChange( nextValue );
+					} }
+				/>
+			) }
+			<WidthHeightTool
+				panelId={ panelId }
+				units={ unitsOptions }
+				value={ { width, height } }
+				onChange={ ( { width: nextWidth, height: nextHeight } ) => {
+					const nextValue = { ...value };
+
+					// 'auto' is CSS default, so it gets treated as null.
+					nextWidth = nextWidth === 'auto' ? null : nextWidth;
+					nextHeight = nextHeight === 'auto' ? null : nextHeight;
+
+					// Update width.
+					if ( ! nextWidth ) {
+						delete nextValue.width;
+					} else {
+						nextValue.width = nextWidth;
+					}
+
+					// Update height.
+					if ( ! nextHeight ) {
+						delete nextValue.height;
+					} else {
+						nextValue.height = nextHeight;
+					}
+
+					// Auto-update aspectRatio.
+					if ( nextWidth && nextHeight ) {
+						delete nextValue.aspectRatio;
+					} else if ( lastAspectRatio ) {
+						nextValue.aspectRatio = lastAspectRatio;
+					} else {
+						// No setting defaultAspectRatio here, because
+						// aspectRatio is optional in this scenario,
+						// unlike scale.
+					}
+
+					// Auto-update scale.
+					if ( ! lastAspectRatio && !! nextWidth !== !! nextHeight ) {
+						delete nextValue.scale;
+					} else if ( lastScale ) {
+						nextValue.scale = lastScale;
+					} else {
+						nextValue.scale = defaultScale;
+						setLastScale( defaultScale );
+					}
+
+					onChange( nextValue );
+				} }
+			/>
+		</>
+	);
+}
+
+export default DimensionsTool;