Spacing Support: Update padding support to allow configurable sides

docs/reference-guides/block-api/block-supports.md

@@ -329,16 +329,28 @@ supports: {
 -   Type: `Object`
 -   Default value: null
 -   Subproperties:
-    -   `padding`: type `boolean`, default value `false`
+    -   `padding`: type `boolean` or `array`, default value `false`
 
 This value signals that a block supports some of the CSS style properties related to spacing. When it does, the block editor will show UI controls for the user to set their values, if [the theme declares support](/docs/how-to-guides/themes/theme-support.md##cover-block-padding).
 
 ```js
 supports: {
-    padding: true, // Enable padding color UI control.
+    spacing: {
+        padding: true, // Enable padding UI control.
+    }
 }
 ```
 
 When the block declares support for a specific spacing property, the attributes definition is extended to include the `style` attribute.
 
 -   `style`: attribute of `object` type with no default assigned. This is added when `padding` support is declared. It stores the custom values set by the user.
+
+```js
+supports: {
+    spacing: {
+        padding: [ 'top', 'bottom' ], // Enable padding for arbitrary sides.
+    }
+}
+```
+
+A spacing property may define an array of allowable sides that can be configured. When arbitrary sides are defined only UI controls for those sides are displayed.

packages/block-editor/src/hooks/padding.js

@@ -9,11 +9,11 @@ import { __experimentalBoxControl as BoxControl } from '@wordpress/components';
 /**
  * Internal dependencies
  */
+import useEditorFeature from '../components/use-editor-feature';
+import { SPACING_SUPPORT_KEY, useCustomSides } from './spacing';
 import { cleanEmptyObject } from './utils';
 import { useCustomUnits } from '../components/unit-control';
 
-export const SPACING_SUPPORT_KEY = 'spacing';
-
 const isWeb = Platform.OS === 'web';
 const CSS_UNITS = [
 	{
@@ -43,10 +43,27 @@ const CSS_UNITS = [
 	},
 ];
 
-const hasPaddingSupport = ( blockName ) => {
-	const spacingSupport = getBlockSupport( blockName, SPACING_SUPPORT_KEY );
-	return spacingSupport && spacingSupport.padding !== false;
-};
+/**
+ * Determines if there is padding support.
+ *
+ * @param  {string|Object} blockType Block name or Block Type object.
+ * @return {boolean}                 Whether there is support.
+ */
+export function hasPaddingSupport( blockType ) {
+	const support = getBlockSupport( blockType, SPACING_SUPPORT_KEY );
+	return !! ( true === support || support?.padding );
+}
+
+/**
+ * Custom hook that checks if padding settings have been disabled.
+ *
+ * @param  {string} name The name of the block.
+ * @return {boolean}                 Whether padding setting is disabled.
+ */
+export function useIsPaddingDisabled( { name: blockName } = {} ) {
+	const isDisabled = ! useEditorFeature( 'spacing.customPadding' );
+	return ! hasPaddingSupport( blockName ) || isDisabled;
+}
 
 /**
  * Inspector control panel containing the padding related configuration
@@ -63,6 +80,7 @@ export function PaddingEdit( props ) {
 	} = props;
 
 	const units = useCustomUnits( CSS_UNITS );
+	const sides = useCustomSides( blockName, 'padding' );
 
 	if ( ! hasPaddingSupport( blockName ) ) {
 		return null;
@@ -72,6 +90,7 @@ export function PaddingEdit( props ) {
 		const newStyle = {
 			...style,
 			spacing: {
+				...style?.spacing,
 				padding: next,
 			},
 		};
@@ -102,6 +121,7 @@ export function PaddingEdit( props ) {
 					onChange={ onChange }
 					onChangeShowVisualizer={ onChangeShowVisualizer }
 					label={ __( 'Padding' ) }
+					sides={ sides }
 					units={ units }
 				/>
 			</>

packages/block-editor/src/hooks/spacing.js

@@ -0,0 +1,86 @@
+/**
+ * WordPress dependencies
+ */
+import { getBlockSupport } from '@wordpress/blocks';
+import { Platform } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import {
+	PaddingEdit,
+	hasPaddingSupport,
+	useIsPaddingDisabled,
+} from './padding';
+import SpacingPanelControl from '../components/spacing-panel-control';
+
+export const SPACING_SUPPORT_KEY = 'spacing';
+
+/**
+ * Inspector controls for spacing support.
+ *
+ * @param  {Object} props Block props.
+ * @return {WPElement}    Inspector controls for spacing support features.
+ */
+export function SpacingPanel( props ) {
+	const isDisabled = useIsSpacingDisabled( props );
+	const isSupported = hasSpacingSupport( props.name );
+
+	if ( isDisabled || ! isSupported ) {
+		return null;
+	}
+
+	return (
+		<SpacingPanelControl key="spacing">
+			<PaddingEdit { ...props } />
+		</SpacingPanelControl>
+	);
+}
+
+/**
+ * Determine whether there is block support for padding.
+ *
+ * @param {string} blockName Block name.
+ * @return {boolean}         Whether there is support.
+ */
+export function hasSpacingSupport( blockName ) {
+	if ( Platform.OS !== 'web' ) {
+		return false;
+	}
+
+	return hasPaddingSupport( blockName );
+}
+
+/**
+ * Determines whether spacing support has been disabled.
+ *
+ * @param  {Object} props Block properties.
+ * @return {boolean}      If spacing support is completely disabled.
+ */
+const useIsSpacingDisabled = ( props = {} ) => {
+	const paddingDisabled = useIsPaddingDisabled( props );
+
+	return paddingDisabled;
+};
+
+/**
+ * Custom hook to retrieve which padding/margin is supported
+ * e.g. top, right, bottom or left.
+ *
+ * Sides are opted into by default. It is only if a specific side is set to
+ * false that it is omitted.
+ *
+ * @param  {string} blockName Block name.
+ * @param  {string} feature   The feature custom sides relate to e.g. padding or margins.
+ * @return {Object}           Sides supporting custom margin.
+ */
+export function useCustomSides( blockName, feature ) {
+	const support = getBlockSupport( blockName, SPACING_SUPPORT_KEY );
+
+	// Skip when setting is boolean as theme isn't setting arbitrary sides.
+	if ( typeof support[ feature ] === 'boolean' ) {
+		return;
+	}
+
+	return support[ feature ];
+}

packages/block-editor/src/hooks/style.js

@@ -20,8 +20,7 @@ import { createHigherOrderComponent } from '@wordpress/compose';
 import { BORDER_SUPPORT_KEY, BorderPanel } from './border';
 import { COLOR_SUPPORT_KEY, ColorEdit } from './color';
 import { TypographyPanel, TYPOGRAPHY_SUPPORT_KEYS } from './typography';
-import { SPACING_SUPPORT_KEY, PaddingEdit } from './padding';
-import SpacingPanelControl from '../components/spacing-panel-control';
+import { SPACING_SUPPORT_KEY, SpacingPanel } from './spacing';
 
 const styleSupportKeys = [
 	...TYPOGRAPHY_SUPPORT_KEYS,
@@ -140,7 +139,7 @@ export function addSaveProps( props, blockType, attributes ) {
 }
 
 /**
- * Filters registered block settings to extand the block edit wrapper
+ * Filters registered block settings to extend the block edit wrapper
  * to apply the desired styles and classnames properly.
  *
  * @param  {Object} settings Original block settings
@@ -173,23 +172,12 @@ export function addEditProps( settings ) {
  */
 export const withBlockControls = createHigherOrderComponent(
 	( BlockEdit ) => ( props ) => {
-		const { name: blockName } = props;
-
-		const hasSpacingSupport = hasBlockSupport(
-			blockName,
-			SPACING_SUPPORT_KEY
-		);
-
 		return [
 			<TypographyPanel key="typography" { ...props } />,
 			<BorderPanel key="border" { ...props } />,
 			<ColorEdit key="colors" { ...props } />,
 			<BlockEdit key="edit" { ...props } />,
-			hasSpacingSupport && (
-				<SpacingPanelControl key="spacing">
-					<PaddingEdit { ...props } />
-				</SpacingPanelControl>
-			),
+			<SpacingPanel key="spacing" { ...props } />,
 		];
 	},
 	'withToolbarControls'

packages/block-editor/src/hooks/test/style.js

@@ -23,6 +23,9 @@ describe( 'getInlineStyles', () => {
 					style: 'dotted',
 					color: '#21759b',
 				},
+				spacing: {
+					padding: { top: '10px' },
+				},
 			} )
 		).toEqual( {
 			backgroundColor: 'black',
@@ -33,6 +36,7 @@ describe( 'getInlineStyles', () => {
 			color: 'red',
 			lineHeight: 1.5,
 			fontSize: 10,
+			paddingTop: '10px',
 		} );
 	} );
 } );

packages/edit-site/src/components/sidebar/spacing-panel.js

@@ -7,6 +7,7 @@ import {
 	__experimentalBoxControl as BoxControl,
 	PanelBody,
 } from '@wordpress/components';
+import { getBlockSupport } from '@wordpress/blocks';
 
 /**
  * Internal dependencies
@@ -42,7 +43,13 @@ const CSS_UNITS = [
 	},
 ];
 
-export function useHasSpacingPanel( { supports, name } ) {
+export function useHasSpacingPanel( context ) {
+	const hasPadding = useHasPadding( context );
+
+	return hasPadding;
+}
+
+export function useHasPadding( { name, supports } ) {
 	return (
 		useEditorFeature( 'spacing.customPadding', name ) &&
 		supports.includes( 'padding' )
@@ -65,29 +72,54 @@ function useCustomUnits( { units, contextName } ) {
 	return usedUnits.length === 0 ? false : usedUnits;
 }
 
-export default function SpacingPanel( {
-	context: { name },
-	getStyle,
-	setStyle,
-} ) {
+function useCustomSides( blockName, feature ) {
+	const support = getBlockSupport( blockName, 'spacing' );
+
+	// Skip when setting is boolean as theme isn't setting arbitrary sides.
+	if ( typeof support[ feature ] === 'boolean' ) {
+		return;
+	}
+
+	return support[ feature ];
+}
+
+function filterValuesBySides( values, sides ) {
+	if ( ! sides ) {
+		// If no custom side configuration all sides are opted into by default.
+		return values;
+	}
+
+	// Only include sides opted into within filtered values.
+	const filteredValues = {};
+	sides.forEach( ( side ) => ( filteredValues[ side ] = values[ side ] ) );
+
+	return filteredValues;
+}
+
+export default function SpacingPanel( { context, getStyle, setStyle } ) {
+	const { name } = context;
+	const showPaddingControl = useHasPadding( context );
 	const units = useCustomUnits( { contextName: name, units: CSS_UNITS } );
+
 	const paddingValues = getStyle( name, 'padding' );
-	const setPaddingValues = ( { top, right, bottom, left } ) => {
-		setStyle( name, 'padding', {
-			top: top || paddingValues?.top,
-			right: right || paddingValues?.right,
-			bottom: bottom || paddingValues?.bottom,
-			left: left || paddingValues?.left,
-		} );
+	const paddingSides = useCustomSides( name, 'padding' );
+
+	const setPaddingValues = ( newPaddingValues ) => {
+		const padding = filterValuesBySides( newPaddingValues, paddingSides );
+		setStyle( name, 'padding', padding );
 	};
+
 	return (
 		<PanelBody title={ __( 'Spacing' ) }>
-			<BoxControl
-				values={ paddingValues }
-				onChange={ setPaddingValues }
-				label={ __( 'Padding' ) }
-				units={ units }
-			/>
+			{ showPaddingControl && (
+				<BoxControl
+					values={ paddingValues }
+					onChange={ setPaddingValues }
+					label={ __( 'Padding' ) }
+					sides={ paddingSides }
+					units={ units }
+				/>
+			) }
 		</PanelBody>
 	);
 }