Button: update spacing support to use axial padding (#33859)

* Add support for axial sides to padding block support

* Update button to support general and axial padding only

* Update docs

* Enable axial support for margin block support

* Warn against invalid sides configuration and disable support

If a spacing support is configured with an invalid mix of axial and
individual sides, log a warning and disable the feature. If only
one feature is invalidly configured, this does not affect the other;
eg if padding is configured incorrectly but margin is not, padding
is disabled but margins will continue to work.

* Update docs

* Clearer hook name

* Check that support is defined in useCustomSides

Previously the hook was only used if the feature was known to be
supported. Now that it is used in checking the spacing configuration,
it is possible for `support` to be undefined here.

* Update global styles panel

* Make padding a default control for the button block

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

@@ -585,4 +585,4 @@ supports: {
 }
 ```
 
-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.
+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. Axial sides are defined with the `vertical` and `horizontal` terms, and display a single UI control for each axial pair (for example, `vertical` controls both the top and bottom sides). A spacing property may support arbitrary individual sides **or** axial sides, but not a mix of both.

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

@@ -30,6 +30,8 @@ import {
 import { cleanEmptyObject } from './utils';
 
 export const SPACING_SUPPORT_KEY = 'spacing';
+export const ALL_SIDES = [ 'top', 'right', 'bottom', 'left' ];
+export const AXIAL_SIDES = [ 'vertical', 'horizontal' ];
 
 /**
  * Inspector controls for dimensions support.
@@ -146,9 +148,37 @@ 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' ) {
+	if ( ! support || typeof support[ feature ] === 'boolean' ) {
 		return;
 	}
 
 	return support[ feature ];
 }
+
+/**
+ * Custom hook to determine whether the sides configured in the
+ * block support are valid. A dimension property cannot declare
+ * support for a mix of axial and individual sides.
+ *
+ * @param {string} blockName Block name.
+ * @param {string} feature   The feature custom sides relate to e.g. padding or margins.
+ *
+ * @return {boolean} If the feature has a valid configuration of sides.
+ */
+export function useIsDimensionsSupportValid( blockName, feature ) {
+	const sides = useCustomSides( blockName, feature );
+
+	if (
+		sides &&
+		sides.some( ( side ) => ALL_SIDES.includes( side ) ) &&
+		sides.some( ( side ) => AXIAL_SIDES.includes( side ) )
+	) {
+		// eslint-disable-next-line no-console
+		console.warn(
+			`The ${ feature } support for the "${ blockName }" block can not be configured to support both axial and arbitrary sides.`
+		);
+		return false;
+	}
+
+	return true;
+}

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

@@ -13,7 +13,12 @@ import {
  * Internal dependencies
  */
 import useSetting from '../components/use-setting';
-import { SPACING_SUPPORT_KEY, useCustomSides } from './dimensions';
+import {
+	AXIAL_SIDES,
+	SPACING_SUPPORT_KEY,
+	useCustomSides,
+	useIsDimensionsSupportValid,
+} from './dimensions';
 import { cleanEmptyObject } from './utils';
 
 /**
@@ -69,7 +74,9 @@ export function resetMargin( { attributes = {}, setAttributes } ) {
  */
 export function useIsMarginDisabled( { name: blockName } = {} ) {
 	const isDisabled = ! useSetting( 'spacing.customMargin' );
-	return ! hasMarginSupport( blockName ) || isDisabled;
+	const isInvalid = ! useIsDimensionsSupportValid( blockName, 'margin' );
+
+	return ! hasMarginSupport( blockName ) || isDisabled || isInvalid;
 }
 
 /**
@@ -96,6 +103,8 @@ export function MarginEdit( props ) {
 		],
 	} );
 	const sides = useCustomSides( blockName, 'margin' );
+	const splitOnAxis =
+		sides && sides.some( ( side ) => AXIAL_SIDES.includes( side ) );
 
 	if ( useIsMarginDisabled( props ) ) {
 		return null;
@@ -139,6 +148,7 @@ export function MarginEdit( props ) {
 					sides={ sides }
 					units={ units }
 					allowReset={ false }
+					splitOnAxis={ splitOnAxis }
 				/>
 			</>
 		),

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

@@ -13,7 +13,12 @@ import {
  * Internal dependencies
  */
 import useSetting from '../components/use-setting';
-import { SPACING_SUPPORT_KEY, useCustomSides } from './dimensions';
+import {
+	AXIAL_SIDES,
+	SPACING_SUPPORT_KEY,
+	useCustomSides,
+	useIsDimensionsSupportValid,
+} from './dimensions';
 import { cleanEmptyObject } from './utils';
 
 /**
@@ -69,7 +74,9 @@ export function resetPadding( { attributes = {}, setAttributes } ) {
  */
 export function useIsPaddingDisabled( { name: blockName } = {} ) {
 	const isDisabled = ! useSetting( 'spacing.customPadding' );
-	return ! hasPaddingSupport( blockName ) || isDisabled;
+	const isInvalid = ! useIsDimensionsSupportValid( blockName, 'padding' );
+
+	return ! hasPaddingSupport( blockName ) || isDisabled || isInvalid;
 }
 
 /**
@@ -96,6 +103,8 @@ export function PaddingEdit( props ) {
 		],
 	} );
 	const sides = useCustomSides( blockName, 'padding' );
+	const splitOnAxis =
+		sides && sides.some( ( side ) => AXIAL_SIDES.includes( side ) );
 
 	if ( useIsPaddingDisabled( props ) ) {
 		return null;
@@ -139,6 +148,7 @@ export function PaddingEdit( props ) {
 					sides={ sides }
 					units={ units }
 					allowReset={ false }
+					splitOnAxis={ splitOnAxis }
 				/>
 			</>
 		),

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

@@ -68,7 +68,10 @@
 		"reusable": false,
 		"spacing": {
 			"__experimentalSkipSerialization": true,
-			"padding": true
+			"padding": [ "horizontal", "vertical" ],
+			"__experimentalDefaultControls": {
+				"padding": true
+			}
 		},
 		"__experimentalBorder": {
 			"radius": true,

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

@@ -15,6 +15,8 @@ import { __experimentalUseCustomSides as useCustomSides } from '@wordpress/block
  */
 import { useSetting } from '../editor/utils';
 
+const AXIAL_SIDES = [ 'horizontal', 'vertical' ];
+
 export function useHasDimensionsPanel( context ) {
 	const hasPadding = useHasPadding( context );
 	const hasMargin = useHasMargin( context );
@@ -42,7 +44,17 @@ function filterValuesBySides( values, sides ) {
 
 	// Only include sides opted into within filtered values.
 	const filteredValues = {};
-	sides.forEach( ( side ) => ( filteredValues[ side ] = values[ side ] ) );
+	sides.forEach( ( side ) => {
+		if ( side === 'vertical' ) {
+			filteredValues.top = values.top;
+			filteredValues.bottom = values.bottom;
+		}
+		if ( side === 'horizontal' ) {
+			filteredValues.left = values.left;
+			filteredValues.right = values.right;
+		}
+		filteredValues[ side ] = values[ side ];
+	} );
 
 	return filteredValues;
 }
@@ -78,6 +90,9 @@ export default function DimensionsPanel( { context, getStyle, setStyle } ) {
 
 	const paddingValues = splitStyleValue( getStyle( name, 'padding' ) );
 	const paddingSides = useCustomSides( name, 'padding' );
+	const isAxialPadding =
+		paddingSides &&
+		paddingSides.some( ( side ) => AXIAL_SIDES.includes( side ) );
 
 	const setPaddingValues = ( newPaddingValues ) => {
 		const padding = filterValuesBySides( newPaddingValues, paddingSides );
@@ -89,6 +104,9 @@ export default function DimensionsPanel( { context, getStyle, setStyle } ) {
 
 	const marginValues = splitStyleValue( getStyle( name, 'margin' ) );
 	const marginSides = useCustomSides( name, 'margin' );
+	const isAxialMargin =
+		marginSides &&
+		marginSides.some( ( side ) => AXIAL_SIDES.includes( side ) );
 
 	const setMarginValues = ( newMarginValues ) => {
 		const margin = filterValuesBySides( newMarginValues, marginSides );
@@ -123,6 +141,7 @@ export default function DimensionsPanel( { context, getStyle, setStyle } ) {
 						sides={ paddingSides }
 						units={ units }
 						allowReset={ false }
+						splitOnAxis={ isAxialPadding }
 					/>
 				</ToolsPanelItem>
 			) }
@@ -140,6 +159,7 @@ export default function DimensionsPanel( { context, getStyle, setStyle } ) {
 						sides={ marginSides }
 						units={ units }
 						allowReset={ false }
+						splitOnAxis={ isAxialMargin }
 					/>
 				</ToolsPanelItem>
 			) }