@wordpress/components 28.13.1-next.082ed6819.0 → 29.0.0

package/src/box-control/types.ts

@@ -17,68 +17,85 @@ export type CustomValueUnits = {
 
 type UnitControlPassthroughProps = Omit<
 	UnitControlProps,
-	'label' | 'onChange' | 'onFocus' | 'onMouseOver' | 'onMouseOut' | 'units'
+	'label' | 'onChange' | 'onFocus' | 'units'
 >;
 
-export type BoxControlProps = Pick<
-	UnitControlProps,
-	'onMouseOver' | 'onMouseOut' | 'units'
-> & {
-	/**
-	 * If this property is true, a button to reset the box control is rendered.
-	 *
-	 * @default true
-	 */
-	allowReset?: boolean;
-	/**
-	 * The id to use as a base for the unique HTML id attribute of the control.
-	 */
-	id?: string;
-	/**
-	 * Props for the internal `UnitControl` components.
-	 *
-	 * @default { min: 0 }
-	 */
-	inputProps?: UnitControlPassthroughProps;
-	/**
-	 * Heading label for the control.
-	 *
-	 * @default __( 'Box Control' )
-	 */
-	label?: string;
-	/**
-	 * A callback function when an input value changes.
-	 */
-	onChange: ( next: BoxControlValue ) => void;
-	/**
-	 * The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset.
-	 *
-	 * @default { top: undefined, right: undefined, bottom: undefined, left: undefined }
-	 */
-	resetValues?: BoxControlValue;
+type DeprecatedBoxControlProps = {
 	/**
-	 * Collection of sides to allow control of. If omitted or empty, all sides will be available.
-	 */
-	sides?: readonly ( keyof BoxControlValue | 'horizontal' | 'vertical' )[];
-	/**
-	 * If this property is true, when the box control is unlinked, vertical and horizontal controls
-	 * can be used instead of updating individual sides.
-	 *
-	 * @default false
+	 * @deprecated Pass to the `inputProps` prop instead.
+	 * @ignore
 	 */
-	splitOnAxis?: boolean;
+	onMouseOver?: UnitControlProps[ 'onMouseOver' ];
 	/**
-	 * The current values of the control, expressed as an object of `top`, `right`, `bottom`, and `left` values.
+	 * @deprecated Pass to the `inputProps` prop instead.
+	 * @ignore
 	 */
-	values?: BoxControlValue;
-	/**
-	 * Start opting into the larger default height that will become the default size in a future version.
-	 *
-	 * @default false
-	 */
-	__next40pxDefaultSize?: boolean;
+	onMouseOut?: UnitControlProps[ 'onMouseOut' ];
 };
 
+export type BoxControlProps = Pick< UnitControlProps, 'units' > &
+	DeprecatedBoxControlProps & {
+		/**
+		 * If this property is true, a button to reset the box control is rendered.
+		 *
+		 * @default true
+		 */
+		allowReset?: boolean;
+		/**
+		 * The id to use as a base for the unique HTML id attribute of the control.
+		 */
+		id?: string;
+		/**
+		 * Props for the internal `UnitControl` components.
+		 *
+		 * @default { min: 0 }
+		 */
+		inputProps?: UnitControlPassthroughProps;
+		/**
+		 * Heading label for the control.
+		 *
+		 * @default __( 'Box Control' )
+		 */
+		label?: string;
+		/**
+		 * A callback function when an input value changes.
+		 */
+		onChange: ( next: BoxControlValue ) => void;
+		/**
+		 * The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset.
+		 *
+		 * @default { top: undefined, right: undefined, bottom: undefined, left: undefined }
+		 */
+		resetValues?: BoxControlValue;
+		/**
+		 * Collection of sides to allow control of. If omitted or empty, all sides will be available.
+		 *
+		 * Allowed values are "top", "right", "bottom", "left", "vertical", and "horizontal".
+		 */
+		sides?: readonly (
+			| keyof BoxControlValue
+			| 'horizontal'
+			| 'vertical'
+		)[];
+		/**
+		 * If this property is true, when the box control is unlinked, vertical and horizontal controls
+		 * can be used instead of updating individual sides.
+		 *
+		 * @default false
+		 */
+		splitOnAxis?: boolean;
+		/**
+		 * The current values of the control, expressed as an object of `top`, `right`, `bottom`, and `left` values.
+		 */
+		values?: BoxControlValue;
+		/**
+		 * Start opting into the larger default height that will become the default size in a future version.
+		 *
+		 * @default false
+		 */
+		__next40pxDefaultSize?: boolean;
+	};
+
 export type BoxControlInputControlProps = UnitControlPassthroughProps & {
 	onChange?: ( nextValues: BoxControlValue ) => void;
 	onFocus?: (
@@ -93,8 +110,16 @@ export type BoxControlInputControlProps = UnitControlPassthroughProps & {
 	) => void;
 	selectedUnits: BoxControlValue;
 	setSelectedUnits: React.Dispatch< React.SetStateAction< BoxControlValue > >;
-	sides: BoxControlProps[ 'sides' ];
 	values: BoxControlValue;
+	/**
+	 * Collection of sides to allow control of. If omitted or empty, all sides will be available.
+	 */
+	sides: BoxControlProps[ 'sides' ];
+	/**
+	 * Side represents the current side being rendered by the input.
+	 * It can be a concrete side like: left, right, top, bottom or a combined one like: horizontal, vertical.
+	 */
+	side: keyof typeof LABELS;
 };
 
 export type BoxControlIconProps = {

package/src/box-control/utils.ts

@@ -6,12 +6,13 @@ import { __ } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
-import { parseQuantityAndUnitFromRawValue } from '../unit-control/utils';
 import type {
+	BoxControlInputControlProps,
 	BoxControlProps,
 	BoxControlValue,
 	CustomValueUnits,
 } from './types';
+import deprecated from '@wordpress/deprecated';
 
 export const CUSTOM_VALUE_SETTINGS: CustomValueUnits = {
 	px: { max: 300, step: 1 },
@@ -50,7 +51,6 @@ export const LABELS = {
 	bottom: __( 'Bottom side' ),
 	left: __( 'Left side' ),
 	right: __( 'Right side' ),
-	mixed: __( 'Mixed' ),
 	vertical: __( 'Top and bottom sides' ),
 	horizontal: __( 'Left and right sides' ),
 };
@@ -82,56 +82,46 @@ function mode< T >( arr: T[] ) {
 }
 
 /**
- * Gets the 'all' input value and unit from values data.
+ * Gets the merged input value and unit from values data.
  *
  * @param values         Box values.
- * @param selectedUnits  Box units.
  * @param availableSides Available box sides to evaluate.
  *
  * @return A value + unit for the 'all' input.
  */
-export function getAllValue(
+export function getMergedValue(
 	values: BoxControlValue = {},
-	selectedUnits?: BoxControlValue,
 	availableSides: BoxControlProps[ 'sides' ] = ALL_SIDES
 ) {
 	const sides = normalizeSides( availableSides );
-	const parsedQuantitiesAndUnits = sides.map( ( side ) =>
-		parseQuantityAndUnitFromRawValue( values[ side ] )
-	);
-	const allParsedQuantities = parsedQuantitiesAndUnits.map(
-		( value ) => value[ 0 ] ?? ''
-	);
-	const allParsedUnits = parsedQuantitiesAndUnits.map(
-		( value ) => value[ 1 ]
-	);
-
-	const commonQuantity = allParsedQuantities.every(
-		( v ) => v === allParsedQuantities[ 0 ]
-	)
-		? allParsedQuantities[ 0 ]
-		: '';
-
-	/**
-	 * The typeof === 'number' check is important. On reset actions, the incoming value
-	 * may be null or an empty string.
-	 *
-	 * Also, the value may also be zero (0), which is considered a valid unit value.
-	 *
-	 * typeof === 'number' is more specific for these cases, rather than relying on a
-	 * simple truthy check.
-	 */
-	let commonUnit;
-	if ( typeof commonQuantity === 'number' ) {
-		commonUnit = mode( allParsedUnits );
-	} else {
-		// Set meaningful unit selection if no commonQuantity and user has previously
-		// selected units without assigning values while controls were unlinked.
-		commonUnit =
-			getAllUnitFallback( selectedUnits ) ?? mode( allParsedUnits );
+	if (
+		sides.every(
+			( side: keyof BoxControlValue ) =>
+				values[ side ] === values[ sides[ 0 ] ]
+		)
+	) {
+		return values[ sides[ 0 ] ];
 	}
 
-	return [ commonQuantity, commonUnit ].join( '' );
+	return undefined;
+}
+
+/**
+ * Checks if the values are mixed.
+ *
+ * @param values         Box values.
+ * @param availableSides Available box sides to evaluate.
+ * @return Whether the values are mixed.
+ */
+export function isValueMixed(
+	values: BoxControlValue = {},
+	availableSides: BoxControlProps[ 'sides' ] = ALL_SIDES
+) {
+	const sides = normalizeSides( availableSides );
+	return sides.some(
+		( side: keyof BoxControlValue ) =>
+			values[ side ] !== values[ sides[ 0 ] ]
+	);
 }
 
 /**
@@ -150,26 +140,6 @@ export function getAllUnitFallback( selectedUnits?: BoxControlValue ) {
 	return mode( filteredUnits );
 }
 
-/**
- * Checks to determine if values are mixed.
- *
- * @param values        Box values.
- * @param selectedUnits Box units.
- * @param sides         Available box sides to evaluate.
- *
- * @return Whether values are mixed.
- */
-export function isValuesMixed(
-	values: BoxControlValue = {},
-	selectedUnits?: BoxControlValue,
-	sides: BoxControlProps[ 'sides' ] = ALL_SIDES
-) {
-	const allValue = getAllValue( values, selectedUnits, sides );
-	const isMixed = isNaN( parseFloat( allValue ) );
-
-	return isMixed;
-}
-
 /**
  * Checks to determine if values are defined.
  *
@@ -239,6 +209,8 @@ export function normalizeSides( sides: BoxControlProps[ 'sides' ] ) {
  * Applies a value to an object representing top, right, bottom and left sides
  * while taking into account any custom side configuration.
  *
+ * @deprecated
+ *
  * @param currentValues The current values for each side.
  * @param newValue      The value to apply to the sides object.
  * @param sides         Array defining valid sides.
@@ -250,6 +222,10 @@ export function applyValueToSides(
 	newValue?: string,
 	sides?: BoxControlProps[ 'sides' ]
 ): BoxControlValue {
+	deprecated( 'applyValueToSides', {
+		since: '6.8',
+		version: '7.0',
+	} );
 	const newValues = { ...currentValues };
 
 	if ( sides?.length ) {
@@ -270,3 +246,29 @@ export function applyValueToSides(
 
 	return newValues;
 }
+
+/**
+ * Return the allowed sides based on the sides configuration.
+ *
+ * @param sides Sides configuration.
+ * @return Allowed sides.
+ */
+export function getAllowedSides(
+	sides: BoxControlInputControlProps[ 'sides' ]
+) {
+	const allowedSides: Set< keyof BoxControlValue > = new Set(
+		! sides ? ALL_SIDES : []
+	);
+	sides?.forEach( ( allowedSide ) => {
+		if ( allowedSide === 'vertical' ) {
+			allowedSides.add( 'top' );
+			allowedSides.add( 'bottom' );
+		} else if ( allowedSide === 'horizontal' ) {
+			allowedSides.add( 'right' );
+			allowedSides.add( 'left' );
+		} else {
+			allowedSides.add( allowedSide );
+		}
+	} );
+	return allowedSides;
+}