@wordpress/components 19.4.1-next.f435e9e01b.0 → 19.6.1-next.a55ed9455a.0

package/src/ui/utils/space.ts

@@ -21,14 +21,14 @@ export function space( value?: SpaceInput ): string | undefined {
 		return undefined;
 	}
 
-	// handle empty strings, if it's the number 0 this still works
+	// Handle empty strings, if it's the number 0 this still works.
 	if ( ! value ) {
 		return '0';
 	}
 
 	const asInt = typeof value === 'number' ? value : Number( value );
 
-	// test if the input has a unit, was NaN, or was one of the named CSS values (like `auto`), in which case just use that value
+	// Test if the input has a unit, was NaN, or was one of the named CSS values (like `auto`), in which case just use that value.
 	if (
 		( typeof window !== 'undefined' &&
 			window.CSS?.supports?.( 'margin', value.toString() ) ) ||

package/src/unit-control/README.md

@@ -96,7 +96,7 @@ Example:
 
 -   Required: No
 
-### `units`: `WPUnitControlUnitList`
+### `units`: `WPUnitControlUnit[]`
 
 Collection of available units.
 

package/src/unit-control/index.native.js

@@ -16,7 +16,7 @@ import RangeCell from '../mobile/bottom-sheet/range-cell';
 import StepperCell from '../mobile/bottom-sheet/stepper-cell';
 import Picker from '../mobile/picker';
 import styles from './style.scss';
-import { CSS_UNITS, hasUnits, parseA11yLabelForUnit } from './utils';
+import { CSS_UNITS, hasUnits, getAccessibleLabelForUnit } from './utils';
 
 /**
  * WordPress dependencies
@@ -116,6 +116,8 @@ function UnitControl( {
 	};
 
 	const renderUnitPicker = useCallback( () => {
+		// Keeping for legacy reasons, although `false` should not be a valid
+		// value for the `units` prop anymore.
 		if ( units === false ) {
 			return null;
 		}
@@ -164,7 +166,7 @@ function UnitControl( {
 					shouldDisplayTextInput
 					decimalNum={ decimalNum }
 					openUnitPicker={ onPickerPresent }
-					unitLabel={ parseA11yLabelForUnit( unit ) }
+					unitLabel={ getAccessibleLabelForUnit( unit ) }
 					{ ...props }
 				>
 					{ renderUnitPicker() }
@@ -182,7 +184,7 @@ function UnitControl( {
 					separatorType={ separatorType }
 					decimalNum={ decimalNum }
 					openUnitPicker={ onPickerPresent }
-					unitLabel={ parseA11yLabelForUnit( unit ) }
+					unitLabel={ getAccessibleLabelForUnit( unit ) }
 					{ ...props }
 				>
 					{ renderUnitPicker() }

package/src/unit-control/index.tsx

@@ -4,8 +4,9 @@
 import type {
 	FocusEventHandler,
 	KeyboardEvent,
-	Ref,
+	ForwardedRef,
 	SyntheticEvent,
+	ChangeEvent,
 } from 'react';
 import { noop, omit } from 'lodash';
 import classnames from 'classnames';
@@ -13,7 +14,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { forwardRef, useMemo, useRef } from '@wordpress/element';
+import { forwardRef, useMemo, useRef, useEffect } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import { ENTER } from '@wordpress/keycodes';
 
@@ -27,9 +28,9 @@ import { Root, ValueInput } from './styles/unit-control-styles';
 import UnitSelectControl from './unit-select-control';
 import {
 	CSS_UNITS,
-	getParsedValue,
+	getParsedQuantityAndUnit,
 	getUnitsWithCurrentUnit,
-	getValidParsedUnit,
+	getValidParsedQuantityAndUnit,
 } from './utils';
 import { useControlledState } from '../utils/hooks';
 import type { UnitControlProps, UnitControlOnChangeCallback } from './types';
@@ -55,31 +56,48 @@ function UnitControl(
 		value: valueProp,
 		...props
 	}: WordPressComponentProps< UnitControlProps, 'input', false >,
-	forwardedRef: Ref< any >
+	forwardedRef: ForwardedRef< any >
 ) {
+	// The `value` prop, in theory, should not be `null`, but the following line
+	// ensures it fallback to `undefined` in case a consumer of `UnitControl`
+	// still passes `null` as a `value`.
+	const nonNullValueProp = valueProp ?? undefined;
 	const units = useMemo(
-		() => getUnitsWithCurrentUnit( valueProp, unitProp, unitsProp ),
-		[ valueProp, unitProp, unitsProp ]
+		() => getUnitsWithCurrentUnit( nonNullValueProp, unitProp, unitsProp ),
+		[ nonNullValueProp, unitProp, unitsProp ]
 	);
-	const [ value, initialUnit ] = getParsedValue( valueProp, unitProp, units );
+	const [ parsedQuantity, parsedUnit ] = getParsedQuantityAndUnit(
+		nonNullValueProp,
+		unitProp,
+		units
+	);
+
 	const [ unit, setUnit ] = useControlledState< string | undefined >(
 		unitProp,
 		{
-			initial: initialUnit,
+			initial: parsedUnit,
 			fallback: '',
 		}
 	);
 
-	// Stores parsed value for hand-off in state reducer
-	const refParsedValue = useRef< string | null >( null );
+	useEffect( () => {
+		setUnit( parsedUnit );
+	}, [ parsedUnit ] );
+
+	// Stores parsed value for hand-off in state reducer.
+	const refParsedQuantity = useRef< number | undefined >( undefined );
 
 	const classes = classnames( 'components-unit-control', className );
 
-	const handleOnChange: UnitControlOnChangeCallback = (
-		next,
-		changeProps
+	const handleOnQuantityChange = (
+		nextQuantityValue: number | string | undefined,
+		changeProps: { event: ChangeEvent< HTMLInputElement > }
 	) => {
-		if ( next === '' ) {
+		if (
+			nextQuantityValue === '' ||
+			typeof nextQuantityValue === 'undefined' ||
+			nextQuantityValue === null
+		) {
 			onChange( '', changeProps );
 			return;
 		}
@@ -88,53 +106,64 @@ function UnitControl(
 		 * Customizing the onChange callback.
 		 * This allows as to broadcast a combined value+unit to onChange.
 		 */
-		next = getValidParsedUnit( next, units, value, unit ).join( '' );
+		const onChangeValue = getValidParsedQuantityAndUnit(
+			nextQuantityValue,
+			units,
+			parsedQuantity,
+			unit
+		).join( '' );
 
-		onChange( next, changeProps );
+		onChange( onChangeValue, changeProps );
 	};
 
 	const handleOnUnitChange: UnitControlOnChangeCallback = (
-		next,
+		nextUnitValue,
 		changeProps
 	) => {
 		const { data } = changeProps;
 
-		let nextValue = `${ value }${ next }`;
+		let nextValue = `${ parsedQuantity ?? '' }${ nextUnitValue }`;
 
 		if ( isResetValueOnUnitChange && data?.default !== undefined ) {
-			nextValue = `${ data.default }${ next }`;
+			nextValue = `${ data.default }${ nextUnitValue }`;
 		}
 
 		onChange( nextValue, changeProps );
-		onUnitChange( next, changeProps );
+		onUnitChange( nextUnitValue, changeProps );
 
-		setUnit( next );
+		setUnit( nextUnitValue );
 	};
 
 	const mayUpdateUnit = ( event: SyntheticEvent< HTMLInputElement > ) => {
 		if ( ! isNaN( Number( event.currentTarget.value ) ) ) {
-			refParsedValue.current = null;
+			refParsedQuantity.current = undefined;
 			return;
 		}
-		const [ parsedValue, parsedUnit ] = getValidParsedUnit(
+		const [
+			validParsedQuantity,
+			validParsedUnit,
+		] = getValidParsedQuantityAndUnit(
 			event.currentTarget.value,
 			units,
-			value,
+			parsedQuantity,
 			unit
 		);
 
-		refParsedValue.current = parsedValue.toString();
+		refParsedQuantity.current = validParsedQuantity;
 
-		if ( isPressEnterToChange && parsedUnit !== unit ) {
+		if ( isPressEnterToChange && validParsedUnit !== unit ) {
 			const data = Array.isArray( units )
-				? units.find( ( option ) => option.value === parsedUnit )
+				? units.find( ( option ) => option.value === validParsedUnit )
 				: undefined;
 			const changeProps = { event, data };
 
-			onChange( `${ parsedValue }${ parsedUnit }`, changeProps );
-			onUnitChange( parsedUnit, changeProps );
+			onChange(
+				`${ validParsedQuantity ?? '' }${ validParsedUnit }`,
+				changeProps
+			);
+			onUnitChange( validParsedUnit, changeProps );
 
-			setUnit( parsedUnit );
+			setUnit( validParsedUnit );
 		}
 	};
 
@@ -163,9 +192,9 @@ function UnitControl(
 		 * then use that result to update the state.
 		 */
 		if ( action.type === inputControlActionTypes.COMMIT ) {
-			if ( refParsedValue.current !== null ) {
-				state.value = refParsedValue.current;
-				refParsedValue.current = null;
+			if ( refParsedQuantity.current !== undefined ) {
+				state.value = ( refParsedQuantity.current ?? '' ).toString();
+				refParsedQuantity.current = undefined;
 			}
 		}
 
@@ -209,11 +238,11 @@ function UnitControl(
 				label={ label }
 				onBlur={ handleOnBlur }
 				onKeyDown={ handleOnKeyDown }
-				onChange={ handleOnChange }
+				onChange={ handleOnQuantityChange }
 				ref={ forwardedRef }
 				size={ size }
 				suffix={ inputSuffix }
-				value={ value }
+				value={ parsedQuantity ?? '' }
 				step={ step }
 				__unstableStateReducer={ composeStateReducers(
 					unitControlStateReducer,
@@ -242,5 +271,5 @@ function UnitControl(
  */
 const ForwardedUnitControl = forwardRef( UnitControl );
 
-export { parseUnit, useCustomUnits } from './utils';
+export { parseQuantityAndUnitFromRawValue, useCustomUnits } from './utils';
 export default ForwardedUnitControl;

package/src/unit-control/stories/index.js

@@ -16,7 +16,7 @@ import UnitControl from '../';
 import { CSS_UNITS } from '../utils';
 
 export default {
-	title: 'Components/UnitControl',
+	title: 'Components (Experimental)/UnitControl',
 	component: UnitControl,
 	parameters: {
 		knobs: { disable: false },

package/src/unit-control/test/index.js

@@ -1,17 +1,19 @@
 /**
  * External dependencies
  */
-import { render, fireEvent } from '@testing-library/react';
+import { render, fireEvent, screen } from '@testing-library/react';
 
 /**
  * WordPress dependencies
  */
-import { UP, DOWN, ENTER } from '@wordpress/keycodes';
+import { UP, DOWN, ENTER, ESCAPE } from '@wordpress/keycodes';
+import { useState } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import UnitControl from '../';
+import { parseQuantityAndUnitFromRawValue } from '../utils';
 
 const getComponent = () =>
 	document.body.querySelector( '.components-unit-control' );
@@ -25,6 +27,52 @@ const getUnitLabel = () =>
 const fireKeyDown = ( data ) =>
 	fireEvent.keyDown( document.activeElement || document.body, data );
 
+const ControlledSyncUnits = () => {
+	const [ state, setState ] = useState( { valueA: '', valueB: '' } );
+
+	// Keep the unit sync'd between the two `UnitControl` instances.
+	const onUnitControlChange = ( fieldName, newValue ) => {
+		// eslint-disable-next-line @wordpress/no-unused-vars-before-return
+		const [ quantity, newUnit ] = parseQuantityAndUnitFromRawValue(
+			newValue
+		);
+
+		if ( ! Number.isFinite( quantity ) ) {
+			return;
+		}
+
+		const nextState = { ...state, [ fieldName ]: newValue };
+
+		Object.entries( state ).forEach( ( [ stateProp, stateValue ] ) => {
+			const [
+				stateQuantity,
+				stateUnit,
+			] = parseQuantityAndUnitFromRawValue( stateValue );
+
+			if ( stateProp !== fieldName && stateUnit !== newUnit ) {
+				nextState[ stateProp ] = `${ stateQuantity }${ newUnit }`;
+			}
+		} );
+
+		setState( nextState );
+	};
+
+	return (
+		<>
+			<UnitControl
+				label="Field A"
+				value={ state.valueA }
+				onChange={ ( v ) => onUnitControlChange( 'valueA', v ) }
+			/>
+			<UnitControl
+				label="Field B"
+				value={ state.valueB }
+				onChange={ ( v ) => onUnitControlChange( 'valueB', v ) }
+			/>
+		</>
+	);
+};
+
 describe( 'UnitControl', () => {
 	describe( 'Basic rendering', () => {
 		it( 'should render', () => {
@@ -45,7 +93,7 @@ describe( 'UnitControl', () => {
 		} );
 
 		it( 'should not render select, if units are disabled', () => {
-			render( <UnitControl unit="em" units={ false } /> );
+			render( <UnitControl unit="em" units={ [] } /> );
 			const input = getInput();
 			const select = getSelect();
 
@@ -126,6 +174,32 @@ describe( 'UnitControl', () => {
 
 			expect( state ).toBe( '40px' );
 		} );
+
+		it( 'should cancel change when ESCAPE key is pressed', () => {
+			let state = 50;
+			const setState = ( nextState ) => ( state = nextState );
+
+			render(
+				<UnitControl
+					value={ state }
+					onChange={ setState }
+					isPressEnterToChange
+				/>
+			);
+
+			const input = getInput();
+			input.focus();
+
+			fireEvent.change( input, { target: { value: '300px' } } );
+
+			expect( input.value ).toBe( '300px' );
+			expect( state ).toBe( 50 );
+
+			fireKeyDown( { keyCode: ESCAPE } );
+
+			expect( input.value ).toBe( '50' );
+			expect( state ).toBe( 50 );
+		} );
 	} );
 
 	describe( 'Unit', () => {
@@ -240,6 +314,31 @@ describe( 'UnitControl', () => {
 
 			expect( state ).toBe( '62%' );
 		} );
+
+		it( 'should update unit value when a new raw value is passed', () => {
+			render( <ControlledSyncUnits /> );
+
+			const [ inputA, inputB ] = screen.getAllByRole( 'spinbutton' );
+			const [ selectA, selectB ] = screen.getAllByRole( 'combobox' );
+
+			inputA.focus();
+			fireEvent.change( inputA, { target: { value: '55' } } );
+
+			inputB.focus();
+			fireEvent.change( inputB, { target: { value: '14' } } );
+
+			selectA.focus();
+			fireEvent.change( selectA, { target: { value: 'rem' } } );
+
+			expect( selectA ).toHaveValue( 'rem' );
+			expect( selectB ).toHaveValue( 'rem' );
+
+			selectB.focus();
+			fireEvent.change( selectB, { target: { value: 'vw' } } );
+
+			expect( selectA ).toHaveValue( 'vw' );
+			expect( selectB ).toHaveValue( 'vw' );
+		} );
 	} );
 
 	describe( 'Unit Parser', () => {

package/src/unit-control/test/utils.js

@@ -4,7 +4,7 @@
 import {
 	filterUnitsWithSettings,
 	useCustomUnits,
-	getValidParsedUnit,
+	getValidParsedQuantityAndUnit,
 	getUnitsWithCurrentUnit,
 } from '../utils';
 
@@ -34,7 +34,27 @@ describe( 'UnitControl utils', () => {
 			] );
 		} );
 
-		it( 'should return `false` where availableUnits match no preferred css units', () => {
+		it( 'should add default values to available units even if the default values are strings', () => {
+			// Although the public APIs of the component expect a `number` as the type of the
+			// default values, it's still good to test for strings (as it can happen in un-typed
+			// environments)
+			const cssUnits = [ { value: 'px' }, { value: '%' } ];
+			const units = useCustomUnits( {
+				availableUnits: [ '%', 'px' ],
+				defaultValues: {
+					'%': '14',
+					px: 'not a valid numeric quantity',
+				},
+				units: cssUnits,
+			} );
+
+			expect( units ).toEqual( [
+				{ value: 'px', default: undefined },
+				{ value: '%', default: 14 },
+			] );
+		} );
+
+		it( 'should return an empty array where availableUnits match no preferred css units', () => {
 			const cssUnits = [ { value: 'em' }, { value: 'vh' } ];
 			const units = useCustomUnits( {
 				availableUnits: [ '%', 'px' ],
@@ -42,7 +62,7 @@ describe( 'UnitControl utils', () => {
 				units: cssUnits,
 			} );
 
-			expect( units ).toBe( false );
+			expect( units ).toHaveLength( 0 );
 		} );
 	} );
 
@@ -65,6 +85,8 @@ describe( 'UnitControl utils', () => {
 			).toEqual( [] );
 		} );
 
+		// Although the component's APIs and types don't allow for `false` as a value
+		// unit lists, it's good to keep this test around for backwards compat.
 		it( 'should return empty array where available units is set to false', () => {
 			const preferredUnits = [ '%', 'px' ];
 			const availableUnits = false;
@@ -73,19 +95,31 @@ describe( 'UnitControl utils', () => {
 				filterUnitsWithSettings( preferredUnits, availableUnits )
 			).toEqual( [] );
 		} );
+
+		it( 'should return empty array where available units is set to an empty array', () => {
+			const preferredUnits = [ '%', 'px' ];
+			const availableUnits = [];
+
+			expect(
+				filterUnitsWithSettings( preferredUnits, availableUnits )
+			).toEqual( [] );
+		} );
 	} );
 
-	describe( 'getValidParsedUnit', () => {
+	describe( 'getValidParsedQuantityAndUnit', () => {
 		it( 'should parse valid number and unit', () => {
 			const nextValue = '42px';
 
-			expect( getValidParsedUnit( nextValue ) ).toEqual( [ 42, 'px' ] );
+			expect( getValidParsedQuantityAndUnit( nextValue ) ).toEqual( [
+				42,
+				'px',
+			] );
 		} );
 
 		it( 'should return next value only where no known unit parsed', () => {
 			const nextValue = '365zz';
 
-			expect( getValidParsedUnit( nextValue ) ).toEqual( [
+			expect( getValidParsedQuantityAndUnit( nextValue ) ).toEqual( [
 				365,
 				undefined,
 			] );
@@ -97,7 +131,11 @@ describe( 'UnitControl utils', () => {
 			const fallbackValue = 13;
 
 			expect(
-				getValidParsedUnit( nextValue, preferredUnits, fallbackValue )
+				getValidParsedQuantityAndUnit(
+					nextValue,
+					preferredUnits,
+					fallbackValue
+				)
 			).toEqual( [ 13, 'em' ] );
 		} );
 
@@ -106,7 +144,7 @@ describe( 'UnitControl utils', () => {
 			const fallbackUnit = '%';
 
 			expect(
-				getValidParsedUnit(
+				getValidParsedQuantityAndUnit(
 					nextValue,
 					undefined,
 					undefined,
@@ -119,10 +157,9 @@ describe( 'UnitControl utils', () => {
 			const nextValue = 101;
 			const preferredUnits = [ { value: 'px' } ];
 
-			expect( getValidParsedUnit( nextValue, preferredUnits ) ).toEqual( [
-				101,
-				'px',
-			] );
+			expect(
+				getValidParsedQuantityAndUnit( nextValue, preferredUnits )
+			).toEqual( [ 101, 'px' ] );
 		} );
 	} );
 
@@ -139,7 +176,11 @@ describe( 'UnitControl utils', () => {
 		];
 
 		it( 'should return units list with valid current unit prepended', () => {
-			const result = getUnitsWithCurrentUnit( '20%', null, limitedUnits );
+			const result = getUnitsWithCurrentUnit(
+				'20%',
+				undefined,
+				limitedUnits
+			);
 
 			expect( result ).toHaveLength( 3 );
 
@@ -163,7 +204,7 @@ describe( 'UnitControl utils', () => {
 		it( 'should return units list without invalid current unit prepended', () => {
 			const result = getUnitsWithCurrentUnit(
 				'20null',
-				null,
+				undefined,
 				limitedUnits
 			);
 
@@ -174,7 +215,7 @@ describe( 'UnitControl utils', () => {
 		it( 'should return units list without an existing current unit prepended', () => {
 			const result = getUnitsWithCurrentUnit(
 				'20em',
-				null,
+				undefined,
 				limitedUnits
 			);
 

package/src/unit-control/types.ts

@@ -12,8 +12,6 @@ import type {
 	Size as InputSize,
 } from '../input-control/types';
 
-export type Value = number | string;
-
 export type SelectSize = InputSize;
 
 export type WPUnitControlUnit = {
@@ -26,9 +24,9 @@ export type WPUnitControlUnit = {
 	 */
 	label: string;
 	/**
-	 * Default value for the unit, used when switching units.
+	 * Default value (quantity) for the unit, used when switching units.
 	 */
-	default?: Value;
+	default?: number;
 	/**
 	 * An accessible label used by screen readers.
 	 */
@@ -39,8 +37,6 @@ export type WPUnitControlUnit = {
 	step?: number;
 };
 
-export type WPUnitControlUnitList = Array< WPUnitControlUnit > | false;
-
 export type UnitControlOnChangeCallback = InputChangeCallback<
 	SyntheticEvent< HTMLSelectElement | HTMLInputElement >,
 	{ data?: WPUnitControlUnit }
@@ -74,9 +70,10 @@ export type UnitSelectControlProps = {
 	 *
 	 * @default CSS_UNITS
 	 */
-	units?: WPUnitControlUnitList;
+	units?: WPUnitControlUnit[];
 };
 
+// TODO: when available, should (partially) extend `NumberControl` props.
 export type UnitControlProps = UnitSelectControlProps & {
 	__unstableStateReducer?: StateReducer;
 	__unstableInputWidth?: CSSProperties[ 'width' ];
@@ -114,5 +111,5 @@ export type UnitControlProps = UnitSelectControlProps & {
 	 * Current value. If passed as a string, the current unit will be inferred from this value.
 	 * For example, a `value` of "50%" will set the current unit to `%`.
 	 */
-	value: Value;
+	value?: string | number;
 };

package/src/unit-control/unit-select-control.tsx

@@ -22,7 +22,7 @@ export default function UnitSelectControl( {
 	units = CSS_UNITS,
 	...props
 }: WordPressComponentProps< UnitSelectControlProps, 'select', false > ) {
-	if ( ! units || ! hasUnits( units ) || units?.length === 1 ) {
+	if ( ! hasUnits( units ) || units?.length === 1 ) {
 		return (
 			<UnitLabel
 				className="components-unit-control__unit-label"