@wordpress/components 29.0.1-next.a9f418477.0 → 29.1.0

package/src/box-control/README.md

@@ -28,34 +28,33 @@ function Example() {
   );
 };
 ```
+
 ## Props
 
 ### `__next40pxDefaultSize`
 
-Start opting into the larger default height that will become the default size in a future version.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `allowReset`
+Start opting into the larger default height that will become the default size in a future version.
 
-If this property is true, a button to reset the box control is rendered.
+### `allowReset`
 
  - Type: `boolean`
  - Required: No
  - Default: `true`
 
-### `id`
+If this property is true, a button to reset the box control is rendered.
 
-The id to use as a base for the unique HTML id attribute of the control.
+### `id`
 
  - Type: `string`
  - Required: No
 
-### `inputProps`
+The id to use as a base for the unique HTML id attribute of the control.
 
-Props for the internal `UnitControl` components.
+### `inputProps`
 
  - Type: `UnitControlPassthroughProps`
  - Required: No
@@ -63,25 +62,41 @@ Props for the internal `UnitControl` components.
     	min: 0,
     }`
 
-### `label`
+Props for the internal `UnitControl` components.
 
-Heading label for the control.
+### `label`
 
  - Type: `string`
  - Required: No
  - Default: `__( 'Box Control' )`
 
-### `onChange`
+Heading label for the control.
 
-A callback function when an input value changes.
+### `onChange`
 
  - Type: `(next: BoxControlValue) => void`
  - Required: No
  - Default: `() => {}`
 
-### `resetValues`
+A callback function when an input value changes.
 
-The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset.
+### `presets`
+
+ - Type: `Preset[]`
+ - Required: No
+
+Available presets to pick from.
+
+### `presetKey`
+
+ - Type: `string`
+ - Required: No
+
+The key of the preset to apply.
+If you provide a list of presets, you must provide a preset key to use.
+The format of preset selected values is going to be `var:preset|${ presetKey }|${ presetSlug }`
+
+### `resetValues`
 
  - Type: `BoxControlValue`
  - Required: No
@@ -92,35 +107,37 @@ The `top`, `right`, `bottom`, and `left` box dimension values to use when the co
     	left: undefined,
     }`
 
+The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset.
+
 ### `sides`
 
+ - Type: `readonly (keyof BoxControlValue | "horizontal" | "vertical")[]`
+ - Required: No
+
 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".
 
- - Type: `readonly (keyof BoxControlValue | "horizontal" | "vertical")[]`
- - Required: No
-
 ### `splitOnAxis`
 
-If this property is true, when the box control is unlinked, vertical and horizontal controls
-can be used instead of updating individual sides.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `units`
+If this property is true, when the box control is unlinked, vertical and horizontal controls
+can be used instead of updating individual sides.
 
-Available units to select from.
+### `units`
 
  - Type: `WPUnitControlUnit[]`
  - Required: No
  - Default: `CSS_UNITS`
 
-### `values`
+Available units to select from.
 
-The current values of the control, expressed as an object of `top`, `right`, `bottom`, and `left` values.
+### `values`
 
  - Type: `BoxControlValue`
  - Required: No
+
+The current values of the control, expressed as an object of `top`, `right`, `bottom`, and `left` values.

package/src/box-control/index.tsx

@@ -9,13 +9,10 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import { BaseControl } from '../base-control';
-import AllInputControl from './all-input-control';
-import InputControls from './input-controls';
-import AxialInputControls from './axial-input-controls';
+import InputControl from './input-control';
 import LinkedButton from './linked-button';
 import { Grid } from '../grid';
 import {
-	FlexedBoxControlIcon,
 	InputWrapper,
 	ResetButton,
 	LinkedButtonWrapper,
@@ -24,8 +21,9 @@ import { parseQuantityAndUnitFromRawValue } from '../unit-control/utils';
 import {
 	DEFAULT_VALUES,
 	getInitialSide,
-	isValuesMixed,
+	isValueMixed,
 	isValuesDefined,
+	getAllowedSides,
 } from './utils';
 import { useControlledState } from '../utils/hooks';
 import type {
@@ -85,6 +83,8 @@ function BoxControl( {
 	splitOnAxis = false,
 	allowReset = true,
 	resetValues = DEFAULT_VALUES,
+	presets,
+	presetKey,
 	onMouseOver,
 	onMouseOut,
 }: BoxControlProps ) {
@@ -97,7 +97,7 @@ function BoxControl( {
 
 	const [ isDirty, setIsDirty ] = useState( hasInitialValue );
 	const [ isLinked, setIsLinked ] = useState(
-		! hasInitialValue || ! isValuesMixed( inputValues ) || hasOneSide
+		! hasInitialValue || ! isValueMixed( inputValues ) || hasOneSide
 	);
 
 	const [ side, setSide ] = useState< BoxControlIconProps[ 'side' ] >(
@@ -155,6 +155,8 @@ function BoxControl( {
 		sides,
 		values: inputValues,
 		__next40pxDefaultSize,
+		presets,
+		presetKey,
 	};
 
 	maybeWarnDeprecated36pxSize( {
@@ -162,6 +164,7 @@ function BoxControl( {
 		__next40pxDefaultSize,
 		size: undefined,
 	} );
+	const sidesToRender = getAllowedSides( sides );
 
 	return (
 		<Grid
@@ -176,8 +179,7 @@ function BoxControl( {
 			</BaseControl.VisualLabel>
 			{ isLinked && (
 				<InputWrapper>
-					<FlexedBoxControlIcon side={ side } sides={ sides } />
-					<AllInputControl { ...inputControlProps } />
+					<InputControl side="all" { ...inputControlProps } />
 				</InputWrapper>
 			) }
 			{ ! hasOneSide && (
@@ -189,12 +191,24 @@ function BoxControl( {
 				</LinkedButtonWrapper>
 			) }
 
-			{ ! isLinked && splitOnAxis && (
-				<AxialInputControls { ...inputControlProps } />
-			) }
-			{ ! isLinked && ! splitOnAxis && (
-				<InputControls { ...inputControlProps } />
-			) }
+			{ ! isLinked &&
+				splitOnAxis &&
+				[ 'vertical', 'horizontal' ].map( ( axis ) => (
+					<InputControl
+						key={ axis }
+						side={ axis as 'horizontal' | 'vertical' }
+						{ ...inputControlProps }
+					/>
+				) ) }
+			{ ! isLinked &&
+				! splitOnAxis &&
+				Array.from( sidesToRender ).map( ( axis ) => (
+					<InputControl
+						key={ axis }
+						side={ axis }
+						{ ...inputControlProps }
+					/>
+				) ) }
 			{ allowReset && (
 				<ResetButton
 					className="component-box-control__reset-button"

package/src/box-control/input-control.tsx

@@ -0,0 +1,299 @@
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { __ } from '@wordpress/i18n';
+import { useState } from '@wordpress/element';
+import { settings } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import Tooltip from '../tooltip';
+import { parseQuantityAndUnitFromRawValue } from '../unit-control/utils';
+import {
+	CUSTOM_VALUE_SETTINGS,
+	getMergedValue,
+	getAllowedSides,
+	getPresetIndexFromValue,
+	getPresetValueFromIndex,
+	isValuePreset,
+	isValuesDefined,
+	isValueMixed,
+	LABELS,
+} from './utils';
+import {
+	FlexedBoxControlIcon,
+	FlexedRangeControl,
+	InputWrapper,
+	StyledUnitControl,
+} from './styles/box-control-styles';
+import type { BoxControlInputControlProps, BoxControlValue } from './types';
+import Button from '../button';
+
+const noop = () => {};
+
+function getSidesToModify(
+	side: BoxControlInputControlProps[ 'side' ],
+	sides: BoxControlInputControlProps[ 'sides' ],
+	isAlt?: boolean
+) {
+	const allowedSides = getAllowedSides( sides );
+
+	let modifiedSides: ( keyof BoxControlValue )[] = [];
+	switch ( side ) {
+		case 'all':
+			modifiedSides = [ 'top', 'bottom', 'left', 'right' ];
+			break;
+		case 'horizontal':
+			modifiedSides = [ 'left', 'right' ];
+			break;
+		case 'vertical':
+			modifiedSides = [ 'top', 'bottom' ];
+			break;
+		default:
+			modifiedSides = [ side ];
+	}
+
+	if ( isAlt ) {
+		switch ( side ) {
+			case 'top':
+				modifiedSides.push( 'bottom' );
+				break;
+			case 'bottom':
+				modifiedSides.push( 'top' );
+				break;
+			case 'left':
+				modifiedSides.push( 'left' );
+				break;
+			case 'right':
+				modifiedSides.push( 'right' );
+				break;
+		}
+	}
+
+	return modifiedSides.filter( ( s ) => allowedSides.has( s ) );
+}
+
+export default function BoxInputControl( {
+	__next40pxDefaultSize,
+	onChange = noop,
+	onFocus = noop,
+	values,
+	selectedUnits,
+	setSelectedUnits,
+	sides,
+	side,
+	min = 0,
+	presets,
+	presetKey,
+	...props
+}: BoxControlInputControlProps ) {
+	const defaultValuesToModify = getSidesToModify( side, sides );
+
+	const handleOnFocus = ( event: React.FocusEvent< HTMLInputElement > ) => {
+		onFocus( event, { side } );
+	};
+
+	const handleOnChange = ( nextValues: BoxControlValue ) => {
+		onChange( nextValues );
+	};
+
+	const handleRawOnValueChange = ( next?: string ) => {
+		const nextValues = { ...values };
+		defaultValuesToModify.forEach( ( modifiedSide ) => {
+			nextValues[ modifiedSide ] = next;
+		} );
+
+		handleOnChange( nextValues );
+	};
+
+	const handleOnValueChange = (
+		next?: string,
+		extra?: { event: React.SyntheticEvent< Element, Event > }
+	) => {
+		const nextValues = { ...values };
+		const isNumeric = next !== undefined && ! isNaN( parseFloat( next ) );
+		const nextValue = isNumeric ? next : undefined;
+		const modifiedSides = getSidesToModify(
+			side,
+			sides,
+			/**
+			 * Supports changing pair sides. For example, holding the ALT key
+			 * when changing the TOP will also update BOTTOM.
+			 */
+			// @ts-expect-error - TODO: event.altKey is only present when the change event was
+			// triggered by a keyboard event. Should this feature be implemented differently so
+			// it also works with drag events?
+			!! extra?.event.altKey
+		);
+
+		modifiedSides.forEach( ( modifiedSide ) => {
+			nextValues[ modifiedSide ] = nextValue;
+		} );
+
+		handleOnChange( nextValues );
+	};
+
+	const handleOnUnitChange = ( next?: string ) => {
+		const newUnits = { ...selectedUnits };
+		defaultValuesToModify.forEach( ( modifiedSide ) => {
+			newUnits[ modifiedSide ] = next;
+		} );
+		setSelectedUnits( newUnits );
+	};
+
+	const mergedValue = getMergedValue( values, defaultValuesToModify );
+	const hasValues = isValuesDefined( values );
+	const isMixed =
+		hasValues &&
+		defaultValuesToModify.length > 1 &&
+		isValueMixed( values, defaultValuesToModify );
+	const [ parsedQuantity, parsedUnit ] =
+		parseQuantityAndUnitFromRawValue( mergedValue );
+	const computedUnit = hasValues
+		? parsedUnit
+		: selectedUnits[ defaultValuesToModify[ 0 ] ];
+	const generatedId = useInstanceId( BoxInputControl, 'box-control-input' );
+	const inputId = [ generatedId, side ].join( '-' );
+	const isMixedUnit =
+		defaultValuesToModify.length > 1 &&
+		mergedValue === undefined &&
+		defaultValuesToModify.some(
+			( s ) => selectedUnits[ s ] !== computedUnit
+		);
+	const usedValue =
+		mergedValue === undefined && computedUnit ? computedUnit : mergedValue;
+	const mixedPlaceholder = isMixed || isMixedUnit ? __( 'Mixed' ) : undefined;
+	const hasPresets = presets && presets.length > 0 && presetKey;
+	const hasPresetValue =
+		hasPresets &&
+		mergedValue !== undefined &&
+		! isMixed &&
+		isValuePreset( mergedValue, presetKey );
+	const [ showCustomValueControl, setShowCustomValueControl ] = useState(
+		! hasPresets ||
+			( ! hasPresetValue && ! isMixed && mergedValue !== undefined )
+	);
+	const presetIndex = hasPresetValue
+		? getPresetIndexFromValue( mergedValue, presetKey, presets )
+		: undefined;
+	const marks = hasPresets
+		? [ { value: 0, label: '', tooltip: __( 'None' ) } ].concat(
+				presets.map( ( preset, index ) => ( {
+					value: index + 1,
+					label: '',
+					tooltip: preset.name ?? preset.slug,
+				} ) )
+		  )
+		: [];
+
+	return (
+		<InputWrapper key={ `box-control-${ side }` } expanded>
+			<FlexedBoxControlIcon side={ side } sides={ sides } />
+			{ showCustomValueControl && (
+				<>
+					<Tooltip placement="top-end" text={ LABELS[ side ] }>
+						<StyledUnitControl
+							{ ...props }
+							min={ min }
+							__shouldNotWarnDeprecated36pxSize
+							__next40pxDefaultSize={ __next40pxDefaultSize }
+							className="component-box-control__unit-control"
+							id={ inputId }
+							isPressEnterToChange
+							disableUnits={ isMixed || isMixedUnit }
+							value={ usedValue }
+							onChange={ handleOnValueChange }
+							onUnitChange={ handleOnUnitChange }
+							onFocus={ handleOnFocus }
+							label={ LABELS[ side ] }
+							placeholder={ mixedPlaceholder }
+							hideLabelFromVision
+						/>
+					</Tooltip>
+
+					<FlexedRangeControl
+						__nextHasNoMarginBottom
+						__next40pxDefaultSize={ __next40pxDefaultSize }
+						__shouldNotWarnDeprecated36pxSize
+						aria-controls={ inputId }
+						label={ LABELS[ side ] }
+						hideLabelFromVision
+						onChange={ ( newValue ) => {
+							handleOnValueChange(
+								newValue !== undefined
+									? [ newValue, computedUnit ].join( '' )
+									: undefined
+							);
+						} }
+						min={ isFinite( min ) ? min : 0 }
+						max={
+							CUSTOM_VALUE_SETTINGS[ computedUnit ?? 'px' ]
+								?.max ?? 10
+						}
+						step={
+							CUSTOM_VALUE_SETTINGS[ computedUnit ?? 'px' ]
+								?.step ?? 0.1
+						}
+						value={ parsedQuantity ?? 0 }
+						withInputField={ false }
+					/>
+				</>
+			) }
+
+			{ hasPresets && ! showCustomValueControl && (
+				<FlexedRangeControl
+					__next40pxDefaultSize
+					className="spacing-sizes-control__range-control"
+					value={ presetIndex !== undefined ? presetIndex + 1 : 0 }
+					onChange={ ( newIndex ) => {
+						const newValue =
+							newIndex === 0 || newIndex === undefined
+								? undefined
+								: getPresetValueFromIndex(
+										newIndex - 1,
+										presetKey,
+										presets
+								  );
+						handleRawOnValueChange( newValue );
+					} }
+					withInputField={ false }
+					aria-valuenow={
+						presetIndex !== undefined ? presetIndex + 1 : 0
+					}
+					aria-valuetext={
+						marks[ presetIndex !== undefined ? presetIndex + 1 : 0 ]
+							.tooltip
+					}
+					renderTooltipContent={ ( index ) =>
+						marks[ ! index ? 0 : index ].tooltip
+					}
+					min={ 0 }
+					max={ marks.length - 1 }
+					marks={ marks }
+					label={ LABELS[ side ] }
+					hideLabelFromVision
+					__nextHasNoMarginBottom
+				/>
+			) }
+
+			{ hasPresets && (
+				<Button
+					label={
+						showCustomValueControl
+							? __( 'Use size preset' )
+							: __( 'Set custom size' )
+					}
+					icon={ settings }
+					onClick={ () => {
+						setShowCustomValueControl( ! showCustomValueControl );
+					} }
+					isPressed={ showCustomValueControl }
+					size="small"
+					iconSize={ 24 }
+				/>
+			) }
+		</InputWrapper>
+	);
+}

package/src/box-control/stories/index.story.tsx

@@ -81,3 +81,15 @@ AxialControlsWithSingleSide.args = {
 	sides: [ 'horizontal' ],
 	splitOnAxis: true,
 };
+
+export const ControlWithPresets = TemplateControlled.bind( {} );
+ControlWithPresets.args = {
+	...Default.args,
+	presets: [
+		{ name: 'Small', slug: 'small', value: '4px' },
+		{ name: 'Medium', slug: 'medium', value: '8px' },
+		{ name: 'Large', slug: 'large', value: '12px' },
+		{ name: 'Extra Large', slug: 'extra-large', value: '16px' },
+	],
+	presetKey: 'padding',
+};

package/src/box-control/types.ts

@@ -15,6 +15,12 @@ export type CustomValueUnits = {
 	[ key: string ]: { max: number; step: number };
 };
 
+export interface Preset {
+	name: string;
+	slug: string;
+	value?: string;
+}
+
 type UnitControlPassthroughProps = Omit<
 	UnitControlProps,
 	'label' | 'onChange' | 'onFocus' | 'units'
@@ -94,6 +100,16 @@ export type BoxControlProps = Pick< UnitControlProps, 'units' > &
 		 * @default false
 		 */
 		__next40pxDefaultSize?: boolean;
+		/**
+		 * Available presets to pick from.
+		 */
+		presets?: Preset[];
+		/**
+		 * The key of the preset to apply.
+		 * If you provide a list of presets, you must provide a preset key to use.
+		 * The format of preset selected values is going to be `var:preset|${ presetKey }|${ presetSlug }`
+		 */
+		presetKey?: string;
 	};
 
 export type BoxControlInputControlProps = UnitControlPassthroughProps & {
@@ -110,8 +126,18 @@ 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;
+	presets?: Preset[];
+	presetKey?: string;
 };
 
 export type BoxControlIconProps = {