@wordpress/block-editor 12.4.0 → 12.6.0

package/src/components/default-block-appender/content.scss

@@ -26,6 +26,17 @@
 		opacity: 0.62;
 	}
 
+	// In "constrained" layout containers, the first and last paragraphs have their margins zeroed out.
+	// In the case of this appender, it needs to apply those same rules to avoid layout shifts.
+	// Such shifts happen when the bottom margin of the Title block has been set to less than the default 1em margin of paragraphs.
+	:where(body .is-layout-constrained) & {
+		> :first-child:first-child {
+			margin-block-start: 0;
+		}
+
+		// Since this particular appender will only ever appear on an entirely empty document, we don't account for last-child.
+	}
+
 	// Dropzone.
 	.components-drop-zone__content-icon {
 		display: none;

package/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>
+	);
+}

package/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;

package/src/components/dimensions-tool/scale-tool.js

@@ -0,0 +1,124 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	__experimentalToolsPanelItem as ToolsPanelItem,
+	__experimentalToggleGroupControl as ToggleGroupControl,
+	__experimentalToggleGroupControlOption as ToggleGroupControlOption,
+} from '@wordpress/components';
+import { useMemo } from '@wordpress/element';
+import { __, _x } from '@wordpress/i18n';
+
+/**
+ * @typedef {import('@wordpress/components/build-types/select-control/types').SelectControlProps} SelectControlProps
+ */
+
+/**
+ * The descriptions are purposely made generic as object-fit could be used for
+ * any replaced element. Provide your own set of options if you need different
+ * help text or labels.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/Replaced_element
+ *
+ * @type {SelectControlProps[]}
+ */
+const DEFAULT_SCALE_OPTIONS = [
+	{
+		value: 'fill',
+		label: _x( 'Fill', 'Scale option for dimensions control' ),
+		help: __( 'Fill the space by stretching the content.' ),
+	},
+	{
+		value: 'contain',
+		label: _x( 'Contain', 'Scale option for dimensions control' ),
+		help: __( 'Fit the content to the space without clipping.' ),
+	},
+	{
+		value: 'cover',
+		label: _x( 'Cover', 'Scale option for dimensions control' ),
+		help: __( "Fill the space by clipping what doesn't fit." ),
+	},
+	{
+		value: 'none',
+		label: _x( 'None', 'Scale option for dimensions control' ),
+		help: __(
+			'Do not adjust the sizing of the content. Content that is too large will be clipped, and content that is too small will have additional padding.'
+		),
+	},
+	{
+		value: 'scale-down',
+		label: _x( 'Scale down', 'Scale option for dimensions control' ),
+		help: __(
+			'Scale down the content to fit the space if it is too big. Content that is too small will have additional padding.'
+		),
+	},
+];
+
+/**
+ * @callback ScaleToolPropsOnChange
+ * @param {string} nextValue New scale value.
+ * @return {void}
+ */
+
+/**
+ * @typedef {Object} ScaleToolProps
+ * @property {string}                 [panelId]               ID of the panel that contains the controls.
+ * @property {string}                 [value]                 Current scale value.
+ * @property {ScaleToolPropsOnChange} [onChange]              Callback to update the scale value.
+ * @property {SelectControlProps[]}   [options]               Scale options.
+ * @property {string}                 [defaultValue]          Default scale value.
+ * @property {boolean}                [showControl=true]      Whether to show the control.
+ * @property {boolean}                [isShownByDefault=true] Whether the tool panel is shown by default.
+ */
+
+/**
+ * A tool to select the CSS object-fit property for the image.
+ *
+ * @param {ScaleToolProps} props
+ *
+ * @return {import('@wordpress/element').WPElement} The scale tool.
+ */
+export default function ScaleTool( {
+	panelId,
+	value,
+	onChange,
+	options = DEFAULT_SCALE_OPTIONS,
+	defaultValue = DEFAULT_SCALE_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 ?? 'fill';
+
+	const scaleHelp = useMemo( () => {
+		return options.reduce( ( acc, option ) => {
+			acc[ option.value ] = option.help;
+			return acc;
+		}, {} );
+	}, [ options ] );
+
+	return (
+		<ToolsPanelItem
+			label={ __( 'Scale' ) }
+			isShownByDefault={ isShownByDefault }
+			hasValue={ () => displayValue !== defaultValue }
+			onDeselect={ () => onChange( defaultValue ) }
+			panelId={ panelId }
+		>
+			<ToggleGroupControl
+				label={ __( 'Scale' ) }
+				isBlock
+				help={ scaleHelp[ displayValue ] }
+				value={ displayValue }
+				onChange={ onChange }
+				__nextHasNoMarginBottom
+			>
+				{ options.map( ( option ) => (
+					<ToggleGroupControlOption
+						key={ option.value }
+						{ ...option }
+					/>
+				) ) }
+			</ToggleGroupControl>
+		</ToolsPanelItem>
+	);
+}

package/src/components/dimensions-tool/stories/aspect-ratio-tool.js

@@ -0,0 +1,52 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import {
+	Panel,
+	__experimentalToolsPanel as ToolsPanel,
+} from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import AspectRatioTool from '../aspect-ratio-tool';
+
+export default {
+	title: 'BlockEditor (Private APIs)/DimensionsTool/AspectRatioTool',
+	component: AspectRatioTool,
+	argTypes: {
+		panelId: { control: { type: null } },
+		onChange: { action: 'changed' },
+	},
+};
+
+export const Default = ( { panelId, onChange: onChangeProp, ...props } ) => {
+	const [ value, setValue ] = useState( undefined );
+	const resetAll = () => {
+		setValue( undefined );
+		onChangeProp( undefined );
+	};
+	return (
+		<Panel>
+			<ToolsPanel
+				label="Aspect Ratio"
+				panelId={ panelId }
+				resetAll={ resetAll }
+			>
+				<AspectRatioTool
+					panelId={ panelId }
+					onChange={ ( nextValue ) => {
+						setValue( nextValue );
+						onChangeProp( nextValue );
+					} }
+					value={ value }
+					{ ...props }
+				/>
+			</ToolsPanel>
+		</Panel>
+	);
+};
+Default.args = {
+	panelId: 'panel-id',
+};

package/src/components/dimensions-tool/stories/index.js

@@ -0,0 +1,54 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import {
+	Panel,
+	__experimentalToolsPanel as ToolsPanel,
+} from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import DimensionsTool from '..';
+
+export default {
+	title: 'BlockEditor (Private APIs)/DimensionsTool',
+	component: DimensionsTool,
+	argTypes: {
+		panelId: { control: { type: null } },
+		onChange: { action: 'changed' },
+	},
+};
+
+const EMPTY_OBJECT = {};
+
+export const Default = ( { panelId, onChange, ...props } ) => {
+	const [ value, setValue ] = useState( EMPTY_OBJECT );
+	const resetAll = () => {
+		setValue( EMPTY_OBJECT );
+		onChange( EMPTY_OBJECT );
+	};
+	return (
+		<Panel>
+			<ToolsPanel
+				label="Dimensions"
+				panelId={ panelId }
+				resetAll={ resetAll }
+			>
+				<DimensionsTool
+					panelId={ panelId }
+					onChange={ ( nextValue ) => {
+						setValue( nextValue );
+						onChange( nextValue );
+					} }
+					value={ value }
+					{ ...props }
+				/>
+			</ToolsPanel>
+		</Panel>
+	);
+};
+Default.args = {
+	panelId: 'panel-id',
+};

package/src/components/dimensions-tool/stories/scale-tool.js

@@ -0,0 +1,48 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import {
+	Panel,
+	__experimentalToolsPanel as ToolsPanel,
+} from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import ScaleTool from '../scale-tool';
+
+export default {
+	title: 'BlockEditor (Private APIs)/DimensionsTool/ScaleTool',
+	component: ScaleTool,
+	argTypes: {
+		panelId: { control: { type: null } },
+		onChange: { action: 'changed' },
+	},
+};
+
+export const Default = ( { panelId, onChange: onChangeProp, ...props } ) => {
+	const [ value, setValue ] = useState( undefined );
+	const resetAll = () => {
+		setValue( undefined );
+		onChangeProp( undefined );
+	};
+	return (
+		<Panel>
+			<ToolsPanel label="Scale" panelId={ panelId } resetAll={ resetAll }>
+				<ScaleTool
+					panelId={ panelId }
+					onChange={ ( nextValue ) => {
+						setValue( nextValue );
+						onChangeProp( nextValue );
+					} }
+					value={ value }
+					{ ...props }
+				/>
+			</ToolsPanel>
+		</Panel>
+	);
+};
+Default.args = {
+	panelId: 'panel-id',
+};

package/src/components/dimensions-tool/stories/width-height-tool.js

@@ -0,0 +1,54 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import {
+	Panel,
+	__experimentalToolsPanel as ToolsPanel,
+} from '@wordpress/components';
+
+/**
+ * Internal dependencies
+ */
+import WidthHeightTool from '../width-height-tool';
+
+export default {
+	title: 'BlockEditor (Private APIs)/DimensionsTool/WidthHeightTool',
+	component: WidthHeightTool,
+	argTypes: {
+		panelId: { control: { type: null } },
+		onChange: { action: 'changed' },
+	},
+};
+
+const EMPTY_OBJECT = {};
+
+export const Default = ( { panelId, onChange: onChangeProp, ...props } ) => {
+	const [ value, setValue ] = useState( EMPTY_OBJECT );
+	const resetAll = () => {
+		setValue( EMPTY_OBJECT );
+		onChangeProp( EMPTY_OBJECT );
+	};
+	return (
+		<Panel>
+			<ToolsPanel
+				label="Width & Height"
+				panelId={ panelId }
+				resetAll={ resetAll }
+			>
+				<WidthHeightTool
+					panelId={ panelId }
+					onChange={ ( nextValue ) => {
+						setValue( nextValue );
+						onChangeProp( nextValue );
+					} }
+					value={ value }
+					{ ...props }
+				/>
+			</ToolsPanel>
+		</Panel>
+	);
+};
+Default.args = {
+	panelId: 'panel-id',
+};