@wordpress/components 19.4.1-next.f435e9e01b.0 → 19.6.0

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"

package/src/unit-control/utils.ts

@@ -7,7 +7,7 @@ import { Platform } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import type { Value, WPUnitControlUnit, WPUnitControlUnitList } from './types';
+import type { WPUnitControlUnit } from './types';
 
 const isWeb = Platform.OS === 'web';
 
@@ -15,105 +15,90 @@ const allUnits: Record< string, WPUnitControlUnit > = {
 	px: {
 		value: 'px',
 		label: isWeb ? 'px' : __( 'Pixels (px)' ),
-		default: '',
 		a11yLabel: __( 'Pixels (px)' ),
 		step: 1,
 	},
 	'%': {
 		value: '%',
 		label: isWeb ? '%' : __( 'Percentage (%)' ),
-		default: '',
 		a11yLabel: __( 'Percent (%)' ),
 		step: 0.1,
 	},
 	em: {
 		value: 'em',
 		label: isWeb ? 'em' : __( 'Relative to parent font size (em)' ),
-		default: '',
 		a11yLabel: _x( 'ems', 'Relative to parent font size (em)' ),
 		step: 0.01,
 	},
 	rem: {
 		value: 'rem',
 		label: isWeb ? 'rem' : __( 'Relative to root font size (rem)' ),
-		default: '',
 		a11yLabel: _x( 'rems', 'Relative to root font size (rem)' ),
 		step: 0.01,
 	},
 	vw: {
 		value: 'vw',
 		label: isWeb ? 'vw' : __( 'Viewport width (vw)' ),
-		default: '',
 		a11yLabel: __( 'Viewport width (vw)' ),
 		step: 0.1,
 	},
 	vh: {
 		value: 'vh',
 		label: isWeb ? 'vh' : __( 'Viewport height (vh)' ),
-		default: '',
 		a11yLabel: __( 'Viewport height (vh)' ),
 		step: 0.1,
 	},
 	vmin: {
 		value: 'vmin',
 		label: isWeb ? 'vmin' : __( 'Viewport smallest dimension (vmin)' ),
-		default: '',
 		a11yLabel: __( 'Viewport smallest dimension (vmin)' ),
 		step: 0.1,
 	},
 	vmax: {
 		value: 'vmax',
 		label: isWeb ? 'vmax' : __( 'Viewport largest dimension (vmax)' ),
-		default: '',
 		a11yLabel: __( 'Viewport largest dimension (vmax)' ),
 		step: 0.1,
 	},
 	ch: {
 		value: 'ch',
 		label: isWeb ? 'ch' : __( 'Width of the zero (0) character (ch)' ),
-		default: '',
 		a11yLabel: __( 'Width of the zero (0) character (ch)' ),
 		step: 0.01,
 	},
 	ex: {
 		value: 'ex',
 		label: isWeb ? 'ex' : __( 'x-height of the font (ex)' ),
-		default: '',
 		a11yLabel: __( 'x-height of the font (ex)' ),
 		step: 0.01,
 	},
 	cm: {
 		value: 'cm',
 		label: isWeb ? 'cm' : __( 'Centimeters (cm)' ),
-		default: '',
 		a11yLabel: __( 'Centimeters (cm)' ),
 		step: 0.001,
 	},
 	mm: {
 		value: 'mm',
 		label: isWeb ? 'mm' : __( 'Millimeters (mm)' ),
-		default: '',
 		a11yLabel: __( 'Millimeters (mm)' ),
 		step: 0.1,
 	},
 	in: {
 		value: 'in',
 		label: isWeb ? 'in' : __( 'Inches (in)' ),
-		default: '',
 		a11yLabel: __( 'Inches (in)' ),
 		step: 0.001,
 	},
 	pc: {
 		value: 'pc',
 		label: isWeb ? 'pc' : __( 'Picas (pc)' ),
-		default: '',
 		a11yLabel: __( 'Picas (pc)' ),
 		step: 1,
 	},
 	pt: {
 		value: 'pt',
 		label: isWeb ? 'pt' : __( 'Points (pt)' ),
-		default: '',
 		a11yLabel: __( 'Points (pt)' ),
 		step: 1,
 	},
@@ -145,130 +130,148 @@ export const DEFAULT_UNIT = allUnits.px;
  * Moving forward, ideally the value should be a string that contains both
  * the value and unit, example: '10px'
  *
- * @param  value Value
- * @param  unit  Unit value
- * @param  units Units to derive from.
- * @return The extracted number and unit.
+ * @param  rawValue     The raw value as a string (may or may not contain the unit)
+ * @param  fallbackUnit The unit used as a fallback, if not unit is detected in the `value`
+ * @param  allowedUnits Units to derive from.
+ * @return The extracted quantity and unit. The quantity can be `undefined` in case the raw value
+ * could not be parsed to a number correctly. The unit can be `undefined` in case the unit parse
+ * from the raw value could not be matched against the list of allowed units.
  */
-export function getParsedValue(
-	value: Value,
-	unit?: string,
-	units?: WPUnitControlUnitList
-): [ Value, string | undefined ] {
-	const initialValue = unit ? `${ value }${ unit }` : value;
+export function getParsedQuantityAndUnit(
+	rawValue?: string | number,
+	fallbackUnit?: string,
+	allowedUnits?: WPUnitControlUnit[]
+): [ number | undefined, string | undefined ] {
+	const initialValue = fallbackUnit
+		? `${ rawValue ?? '' }${ fallbackUnit }`
+		: rawValue;
 
-	return parseUnit( initialValue, units );
+	return parseQuantityAndUnitFromRawValue( initialValue, allowedUnits );
 }
 
 /**
  * Checks if units are defined.
  *
- * @param  units Units to check.
- * @return Whether units are defined.
+ * @param  units List of units.
+ * @return Whether the list actually contains any units.
  */
-export function hasUnits( units: WPUnitControlUnitList ): boolean {
+export function hasUnits( units?: WPUnitControlUnit[] ): boolean {
+	// Although the `isArray` check shouldn't be necessary (given the signature of
+	// this typed function), it's better to stay on the side of caution, since
+	// this function may be called from un-typed environments.
 	return Array.isArray( units ) && !! units.length;
 }
 
 /**
- * Parses a number and unit from a value.
+ * Parses a quantity and unit from a raw string value, given a list of allowed
+ * units and otherwise falling back to the default unit.
  *
- * @param  initialValue Value to parse
- * @param  units        Units to derive from.
- * @return The extracted number and unit.
+ * @param  rawValue     The raw value as a string (may or may not contain the unit)
+ * @param  allowedUnits Units to derive from.
+ * @return The extracted quantity and unit. The quantity can be `undefined` in case the raw value
+ * could not be parsed to a number correctly. The unit can be `undefined` in case the unit parsed
+ * from the raw value could not be matched against the list of allowed units.
  */
-export function parseUnit(
-	initialValue: Value | undefined,
-	units: WPUnitControlUnitList = ALL_CSS_UNITS
-): [ Value, string | undefined ] {
-	const value = String( initialValue ).trim();
+export function parseQuantityAndUnitFromRawValue(
+	rawValue?: string | number,
+	allowedUnits: WPUnitControlUnit[] = ALL_CSS_UNITS
+): [ number | undefined, string | undefined ] {
+	let trimmedValue;
+	let quantityToReturn;
 
-	let num: Value = parseFloat( value );
-	num = isNaN( num ) ? '' : num;
-
-	const unitMatch = value.match( /[\d.\-\+]*\s*(.*)/ );
-
-	let unit: string | undefined =
-		unitMatch?.[ 1 ] !== undefined ? unitMatch[ 1 ] : '';
-	unit = unit.toLowerCase();
+	if ( typeof rawValue !== 'undefined' || rawValue === null ) {
+		trimmedValue = `${ rawValue }`.trim();
+		const parsedQuantity = parseFloat( trimmedValue );
+		quantityToReturn = ! isFinite( parsedQuantity )
+			? undefined
+			: parsedQuantity;
+	}
 
-	if ( hasUnits( units ) && units !== false ) {
-		const match = units.find( ( item ) => item.value === unit );
-		unit = match?.value;
+	const unitMatch = trimmedValue?.match( /[\d.\-\+]*\s*(.*)/ );
+	const matchedUnit = unitMatch?.[ 1 ]?.toLowerCase();
+	let unitToReturn: string | undefined;
+	if ( hasUnits( allowedUnits ) ) {
+		const match = allowedUnits.find(
+			( item ) => item.value === matchedUnit
+		);
+		unitToReturn = match?.value;
 	} else {
-		unit = DEFAULT_UNIT.value;
+		unitToReturn = DEFAULT_UNIT.value;
 	}
 
-	return [ num, unit ];
+	return [ quantityToReturn, unitToReturn ];
 }
 
 /**
- * Parses a number and unit from a value. Validates parsed value, using fallback
+ * Parses quantity and unit from a raw value. Validates parsed value, using fallback
  * value if invalid.
  *
- * @param  next          The next value.
- * @param  units         Units to derive from.
- * @param  fallbackValue The fallback value.
- * @param  fallbackUnit  The fallback value.
- * @return The extracted value and unit.
+ * @param  rawValue         The next value.
+ * @param  allowedUnits     Units to derive from.
+ * @param  fallbackQuantity The fallback quantity, used in case it's not possible to parse a valid quantity from the raw value.
+ * @param  fallbackUnit     The fallback unit, used in case it's not possible to parse a valid unit from the raw value.
+ * @return The extracted quantity and unit. The quantity can be `undefined` in case the raw value
+ * could not be parsed to a number correctly, and the `fallbackQuantity` was also `undefined`. The
+ * unit can be `undefined` only if the unit parsed from the raw value could not be matched against
+ * the list of allowed units, the `fallbackQuantity` is also `undefined` and the list of
+ * `allowedUnits` is passed empty.
  */
-export function getValidParsedUnit(
-	next: Value | undefined,
-	units: WPUnitControlUnitList,
-	fallbackValue: Value,
-	fallbackUnit: string | undefined
-): [ Value, string | undefined ] {
-	const [ parsedValue, parsedUnit ] = parseUnit( next, units );
-	let baseValue = parsedValue;
-	let baseUnit: string | undefined;
+export function getValidParsedQuantityAndUnit(
+	rawValue: string | number,
+	allowedUnits: WPUnitControlUnit[],
+	fallbackQuantity?: number,
+	fallbackUnit?: string
+): [ number | undefined, string | undefined ] {
+	const [ parsedQuantity, parsedUnit ] = parseQuantityAndUnitFromRawValue(
+		rawValue,
+		allowedUnits
+	);
 
-	// The parsed value from `parseUnit` should now be either a
-	// real number or an empty string. If not, use the fallback value.
-	if ( ! Number.isFinite( parsedValue ) || parsedValue === '' ) {
-		baseValue = fallbackValue;
-	}
+	// The parsed value from `parseQuantityAndUnitFromRawValue` should now be
+	// either a real number or undefined. If undefined, use the fallback value.
+	const quantityToReturn = parsedQuantity ?? fallbackQuantity;
 
-	baseUnit = parsedUnit || fallbackUnit;
+	// If no unit is parsed from the raw value, or if the fallback unit is not
+	// defined, use the first value from the list of allowed units as fallback.
+	let unitToReturn = parsedUnit || fallbackUnit;
 
-	/**
-	 * If no unit is found, attempt to use the first value from the collection
-	 * of units as a default fallback.
-	 */
-	if ( Array.isArray( units ) && hasUnits( units ) && ! baseUnit ) {
-		baseUnit = units[ 0 ]?.value;
+	if ( ! unitToReturn && hasUnits( allowedUnits ) ) {
+		unitToReturn = allowedUnits[ 0 ].value;
 	}
 
-	return [ baseValue, baseUnit ];
+	return [ quantityToReturn, unitToReturn ];
 }
 
 /**
  * Takes a unit value and finds the matching accessibility label for the
  * unit abbreviation.
  *
- * @param  unit Unit value (example: px)
+ * @param  unit Unit value (example: `px`)
  * @return a11y label for the unit abbreviation
  */
-export function parseA11yLabelForUnit( unit: string ): string | undefined {
+export function getAccessibleLabelForUnit( unit: string ): string | undefined {
 	const match = ALL_CSS_UNITS.find( ( item ) => item.value === unit );
 	return match?.a11yLabel ? match?.a11yLabel : match?.value;
 }
 
 /**
- * Filters available units based on values defined by the unit setting/property.
+ * Filters available units based on values defined a list of allowed unit values.
  *
- * @param  unitSetting Collection of preferred unit value strings.
- * @param  units       Collection of available unit objects.
- *
- * @return Filtered units based on settings.
+ * @param  allowedUnitValues Collection of allowed unit value strings.
+ * @param  availableUnits    Collection of available unit objects.
+ * @return Filtered units.
  */
 export function filterUnitsWithSettings(
-	unitSetting: Array< string > = [],
-	units: WPUnitControlUnitList
-): Array< WPUnitControlUnit > {
-	return Array.isArray( units )
-		? units.filter( ( unit ) => {
-				return unitSetting.includes( unit.value );
-		  } )
+	allowedUnitValues: string[] = [],
+	availableUnits: WPUnitControlUnit[]
+): WPUnitControlUnit[] {
+	// Although the `isArray` check shouldn't be necessary (given the signature of
+	// this typed function), it's better to stay on the side of caution, since
+	// this function may be called from un-typed environments.
+	return Array.isArray( availableUnits )
+		? availableUnits.filter( ( unit ) =>
+				allowedUnitValues.includes( unit.value )
+		  )
 		: [];
 }
 
@@ -280,34 +283,38 @@ export function filterUnitsWithSettings(
  * @param  args                An object containing units, settingPath & defaultUnits.
  * @param  args.units          Collection of all potentially available units.
  * @param  args.availableUnits Collection of unit value strings for filtering available units.
- * @param  args.defaultValues  Collection of default values for defined units. Example: { px: '350', em: '15' }.
+ * @param  args.defaultValues  Collection of default values for defined units. Example: `{ px: 350, em: 15 }`.
  *
- * @return Filtered units based on settings.
+ * @return Filtered list of units, with their default values updated following the `defaultValues`
+ * argument's property.
  */
 export const useCustomUnits = ( {
-	units,
-	availableUnits,
+	units = ALL_CSS_UNITS,
+	availableUnits = [],
 	defaultValues,
 }: {
-	units?: WPUnitControlUnitList;
-	availableUnits?: Array< string >;
-	defaultValues: Record< string, Value >;
-} ): WPUnitControlUnitList => {
-	units = units || ALL_CSS_UNITS;
-	const usedUnits = filterUnitsWithSettings(
-		! availableUnits ? [] : availableUnits,
+	units?: WPUnitControlUnit[];
+	availableUnits?: string[];
+	defaultValues: Record< string, number >;
+} ): WPUnitControlUnit[] => {
+	const customUnitsToReturn = filterUnitsWithSettings(
+		availableUnits,
 		units
 	);
 
 	if ( defaultValues ) {
-		usedUnits.forEach( ( unit, i ) => {
+		customUnitsToReturn.forEach( ( unit, i ) => {
 			if ( defaultValues[ unit.value ] ) {
-				usedUnits[ i ].default = defaultValues[ unit.value ];
+				const [ parsedDefaultValue ] = parseQuantityAndUnitFromRawValue(
+					defaultValues[ unit.value ]
+				);
+
+				customUnitsToReturn[ i ].default = parsedDefaultValue;
 			}
 		} );
 	}
 
-	return usedUnits.length === 0 ? false : usedUnits;
+	return customUnitsToReturn;
 };
 
 /**
@@ -318,36 +325,32 @@ export const useCustomUnits = ( {
  * accurately displayed in the UI, even if the intention is to hide
  * the availability of that unit.
  *
- * @param  currentValue Selected value to parse.
- * @param  legacyUnit   Legacy unit value, if currentValue needs it appended.
- * @param  units        List of available units.
+ * @param  rawValue   Selected value to parse.
+ * @param  legacyUnit Legacy unit value, if rawValue needs it appended.
+ * @param  units      List of available units.
  *
  * @return A collection of units containing the unit for the current value.
  */
 export function getUnitsWithCurrentUnit(
-	currentValue: Value,
-	legacyUnit: string | undefined,
-	units: WPUnitControlUnitList = ALL_CSS_UNITS
-): WPUnitControlUnitList {
-	if ( ! Array.isArray( units ) ) {
-		return units;
-	}
-
-	const unitsWithCurrentUnit = [ ...units ];
-	const [ , currentUnit ] = getParsedValue(
-		currentValue,
+	rawValue?: string | number,
+	legacyUnit?: string,
+	units: WPUnitControlUnit[] = ALL_CSS_UNITS
+): WPUnitControlUnit[] {
+	const unitsToReturn = Array.isArray( units ) ? [ ...units ] : [];
+	const [ , currentUnit ] = getParsedQuantityAndUnit(
+		rawValue,
 		legacyUnit,
 		ALL_CSS_UNITS
 	);
 
 	if (
 		currentUnit &&
-		! unitsWithCurrentUnit.some( ( unit ) => unit.value === currentUnit )
+		! unitsToReturn.some( ( unit ) => unit.value === currentUnit )
 	) {
 		if ( allUnits[ currentUnit ] ) {
-			unitsWithCurrentUnit.unshift( allUnits[ currentUnit ] );
+			unitsToReturn.unshift( allUnits[ currentUnit ] );
 		}
 	}
 
-	return unitsWithCurrentUnit;
+	return unitsToReturn;
 }

package/src/utils/breakpoint-values.js

@@ -3,7 +3,7 @@ export default {
 	wide: '1280px',
 	'x-large': '1080px',
 	large: '960px', // admin sidebar auto folds
-	medium: '782px', // adminbar goes big
+	medium: '782px', // Adminbar goes big.
 	small: '600px',
 	mobile: '480px',
 	'zoomed-in': '280px',

package/src/utils/colors-values.js

@@ -150,7 +150,7 @@ export const ADMIN = {
 	themeDark10: `var( --wp-admin-theme-color-darker-10, ${ BLUE.medium.focus })`,
 };
 
-// Namespaced values for raw colors hex codes
+// Namespaced values for raw colors hex codes.
 export const UI = {
 	theme: ADMIN.theme,
 	background: BASE.white,

package/src/utils/hooks/test/use-controlled-state.js

@@ -117,7 +117,7 @@ describe( 'hooks', () => {
 			expect( input.value ).toBe( 'There' );
 			expect( spy ).toHaveBeenCalledWith( 'There' );
 
-			// Input is now controlled
+			// Input is now controlled.
 			rerender( <Example value="New Value" /> );
 			expect( input.value ).toBe( 'New Value' );
 

package/src/utils/hooks/test/use-controlled-value.js

@@ -83,9 +83,9 @@ describe( 'useControlledValue', () => {
 
 		expect( getInput() ).toHaveValue( 'Code is Poetry' );
 
-		// primarily this proves that the hook doesn't break if no onChange is passed but
+		// Primarily this proves that the hook doesn't break if no onChange is passed but
 		// value turns into a controlled state, for example if the value needs to be set
-		// to a constant in certain conditions but no change listening needs to happen
+		// to a constant in certain conditions but no change listening needs to happen.
 		fireEvent.change( getInput(), { target: { value: 'WordPress.org' } } );
 
 		// If `value` is passed then we expect the value to be fully controlled
@@ -93,7 +93,7 @@ describe( 'useControlledValue', () => {
 		// we're managing internal state.
 		expect( getInput() ).toHaveValue( 'Code is Poetry' );
 
-		// Next we un-set the value to uncover the internal state which was still maintained
+		// Next we un-set the value to uncover the internal state which was still maintained.
 		rerender( <Input /> );
 
 		expect( getInput() ).toHaveValue( 'WordPress.org' );

package/src/utils/hooks/test/use-latest-ref.js

@@ -71,7 +71,7 @@ function incrementCountDebouncedRef() {
 
 describe( 'useLatestRef', () => {
 	describe( 'Example', () => {
-		// prove the example works as expected
+		// Prove the example works as expected.
 		it( 'should start at 0', () => {
 			render( <Example /> );
 			expect( getCount() ).toEqual( 'Count: 0' );

package/src/utils/test/math.js

@@ -10,7 +10,7 @@ describe( 'add', () => {
 		expect( add( '105', 30 ) ).toBe( 135 );
 		expect( add( 105, '30' ) ).toBe( 135 );
 
-		// Negative values
+		// Negative values.
 		expect( add( 100, '-30' ) ).toBe( 70 );
 		expect( add( -100, '-30' ) ).toBe( -130 );
 	} );
@@ -27,7 +27,7 @@ describe( 'subtract', () => {
 		expect( subtract( '105', 30 ) ).toBe( 75 );
 		expect( subtract( 105, '30' ) ).toBe( 75 );
 
-		// Negative values
+		// Negative values.
 		expect( subtract( 100, '-30' ) ).toBe( 130 );
 		expect( subtract( -100, '-30' ) ).toBe( -70 );
 	} );