@wordpress/components 17.0.0 → 19.0.2

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

@@ -350,5 +350,23 @@ describe( 'UnitControl', () => {
 
 			expect( getSelect().value ).toBe( 'px' );
 		} );
+
+		it( 'should display valid CSS unit when not explicitly included in units list', () => {
+			render(
+				<UnitControl
+					value={ '10%' }
+					units={ [
+						{ value: 'px', label: 'px' },
+						{ value: 'em', label: 'em' },
+					] }
+				/>
+			);
+
+			const select = getSelect();
+			const options = select.querySelectorAll( 'option' );
+
+			expect( select.value ).toBe( '%' );
+			expect( options.length ).toBe( 3 );
+		} );
 	} );
 } );

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

@@ -5,6 +5,7 @@ import {
 	filterUnitsWithSettings,
 	useCustomUnits,
 	getValidParsedUnit,
+	getUnitsWithCurrentUnit,
 } from '../utils';
 
 describe( 'UnitControl utils', () => {
@@ -63,6 +64,15 @@ describe( 'UnitControl utils', () => {
 				filterUnitsWithSettings( preferredUnits, availableUnits )
 			).toEqual( [] );
 		} );
+
+		it( 'should return empty array where available units is set to false', () => {
+			const preferredUnits = [ '%', 'px' ];
+			const availableUnits = false;
+
+			expect(
+				filterUnitsWithSettings( preferredUnits, availableUnits )
+			).toEqual( [] );
+		} );
 	} );
 
 	describe( 'getValidParsedUnit', () => {
@@ -115,4 +125,61 @@ describe( 'UnitControl utils', () => {
 			] );
 		} );
 	} );
+
+	describe( 'getUnitsWithCurrentUnit', () => {
+		const limitedUnits = [
+			{
+				value: 'px',
+				label: 'px',
+			},
+			{
+				value: 'em',
+				label: 'em',
+			},
+		];
+
+		it( 'should return units list with valid current unit prepended', () => {
+			const result = getUnitsWithCurrentUnit( '20%', null, limitedUnits );
+
+			expect( result ).toHaveLength( 3 );
+
+			const currentUnit = result.shift();
+			expect( currentUnit.value ).toBe( '%' );
+			expect( currentUnit.label ).toBe( '%' );
+			expect( result ).toEqual( limitedUnits );
+		} );
+
+		it( 'should return units list with valid current unit prepended using legacy values', () => {
+			const result = getUnitsWithCurrentUnit( 20, '%', limitedUnits );
+
+			expect( result ).toHaveLength( 3 );
+
+			const currentUnit = result.shift();
+			expect( currentUnit.value ).toBe( '%' );
+			expect( currentUnit.label ).toBe( '%' );
+			expect( result ).toEqual( limitedUnits );
+		} );
+
+		it( 'should return units list without invalid current unit prepended', () => {
+			const result = getUnitsWithCurrentUnit(
+				'20null',
+				null,
+				limitedUnits
+			);
+
+			expect( result ).toHaveLength( 2 );
+			expect( result ).toEqual( limitedUnits );
+		} );
+
+		it( 'should return units list without an existing current unit prepended', () => {
+			const result = getUnitsWithCurrentUnit(
+				'20em',
+				null,
+				limitedUnits
+			);
+
+			expect( result ).toHaveLength( 2 );
+			expect( result ).toEqual( limitedUnits );
+		} );
+	} );
 } );

package/src/unit-control/types.ts

@@ -0,0 +1,115 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { SyntheticEvent } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { StateReducer } from '../input-control/reducer/state';
+import type { InputChangeCallback } from '../input-control/types';
+
+export type Value = number | string;
+
+export type SelectSize = 'default' | 'small';
+
+export type WPUnitControlUnit = {
+	/**
+	 * The value for the unit, used in a CSS value (e.g `px`).
+	 */
+	value: string;
+	/**
+	 * The label used in a dropdown selector for the unit.
+	 */
+	label: string;
+	/**
+	 * Default value for the unit, used when switching units.
+	 */
+	default?: Value;
+	/**
+	 * An accessible label used by screen readers.
+	 */
+	a11yLabel?: string;
+	/**
+	 * A step value used when incrementing/decrementing the value.
+	 */
+	step?: number;
+};
+
+export type WPUnitControlUnitList = Array< WPUnitControlUnit > | false;
+
+export type UnitControlOnChangeCallback = InputChangeCallback<
+	SyntheticEvent< HTMLSelectElement | HTMLInputElement >,
+	{ data?: WPUnitControlUnit }
+>;
+
+export type UnitSelectControlProps = {
+	/**
+	 * Whether the control can be focused via keyboard navigation.
+	 *
+	 * @default true
+	 */
+	isUnitSelectTabbable?: boolean;
+	/**
+	 * A callback function invoked when the value is changed.
+	 *
+	 * @default noop
+	 */
+	onChange?: UnitControlOnChangeCallback;
+	/**
+	 * Size of the control option. Supports "default" and "small".
+	 *
+	 * @default 'default'
+	 */
+	size?: SelectSize;
+	/**
+	 * Current unit.
+	 */
+	unit?: string;
+	/**
+	 * Available units to select from.
+	 *
+	 * @default CSS_UNITS
+	 */
+	units?: WPUnitControlUnitList;
+};
+
+export type UnitControlProps = UnitSelectControlProps & {
+	__unstableStateReducer?: StateReducer;
+	/**
+	 * If `true`, the unit `<select>` is hidden.
+	 *
+	 * @default false
+	 */
+	disableUnits?: boolean;
+	/**
+	 * If `true`, the `ENTER` key press is required in order to trigger an `onChange`.
+	 * If enabled, a change is also triggered when tabbing away (`onBlur`).
+	 *
+	 * @default false
+	 */
+	isPressEnterToChange?: boolean;
+	/**
+	 * If `true`, and the selected unit provides a `default` value, this value is set
+	 * when changing units.
+	 *
+	 * @default false
+	 */
+	isResetValueOnUnitChange?: boolean;
+	/**
+	 * If this property is added, a label will be generated using label property as the content.
+	 */
+	label?: string;
+	/**
+	 * Callback when the `unit` changes.
+	 *
+	 * @default noop
+	 */
+	onUnitChange?: UnitControlOnChangeCallback;
+	/**
+	 * 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;
+};

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

@@ -0,0 +1,62 @@
+/**
+ * External dependencies
+ */
+import { noop } from 'lodash';
+import classnames from 'classnames';
+// eslint-disable-next-line no-restricted-imports
+import type { ChangeEvent } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../ui/context';
+import { UnitSelect, UnitLabel } from './styles/unit-control-styles';
+import { CSS_UNITS, hasUnits } from './utils';
+import type { UnitSelectControlProps } from './types';
+
+export default function UnitSelectControl( {
+	className,
+	isUnitSelectTabbable: isTabbable = true,
+	onChange = noop,
+	size = 'default',
+	unit = 'px',
+	units = CSS_UNITS,
+	...props
+}: WordPressComponentProps< UnitSelectControlProps, 'select', false > ) {
+	if ( ! units || ! hasUnits( units ) || units?.length === 1 ) {
+		return (
+			<UnitLabel
+				className="components-unit-control__unit-label"
+				selectSize={ size }
+			>
+				{ unit }
+			</UnitLabel>
+		);
+	}
+
+	const handleOnChange = ( event: ChangeEvent< HTMLSelectElement > ) => {
+		const { value: unitValue } = event.target;
+		const data = units.find( ( option ) => option.value === unitValue );
+
+		onChange( unitValue, { event, data } );
+	};
+
+	const classes = classnames( 'components-unit-control__select', className );
+
+	return (
+		<UnitSelect
+			className={ classes }
+			onChange={ handleOnChange }
+			selectSize={ size }
+			tabIndex={ isTabbable ? undefined : -1 }
+			value={ unit }
+			{ ...props }
+		>
+			{ units.map( ( option ) => (
+				<option value={ option.value } key={ option.value }>
+					{ option.label }
+				</option>
+			) ) }
+		</UnitSelect>
+	);
+}

package/src/unit-control/{utils.js → utils.ts}

@@ -1,17 +1,17 @@
-/**
- * External dependencies
- */
-import { isEmpty } from 'lodash';
-
 /**
  * WordPress dependencies
  */
 import { __, _x } from '@wordpress/i18n';
 import { Platform } from '@wordpress/element';
 
+/**
+ * Internal dependencies
+ */
+import type { Value, WPUnitControlUnit, WPUnitControlUnitList } from './types';
+
 const isWeb = Platform.OS === 'web';
 
-const allUnits = {
+const allUnits: Record< string, WPUnitControlUnit > = {
 	px: {
 		value: 'px',
 		label: isWeb ? 'px' : __( 'Pixels (px)' ),
@@ -19,7 +19,7 @@ const allUnits = {
 		a11yLabel: __( 'Pixels (px)' ),
 		step: 1,
 	},
-	percent: {
+	'%': {
 		value: '%',
 		label: isWeb ? '%' : __( 'Percentage (%)' ),
 		default: '',
@@ -129,7 +129,7 @@ export const ALL_CSS_UNITS = Object.values( allUnits );
  */
 export const CSS_UNITS = [
 	allUnits.px,
-	allUnits.percent,
+	allUnits[ '%' ],
 	allUnits.em,
 	allUnits.rem,
 	allUnits.vw,
@@ -145,12 +145,16 @@ 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 {number|string} value Value
- * @param {string}        unit  Unit value
- * @param {Array<Object>} units Units to derive from.
- * @return {Array<number, string>} The extracted number and unit.
+ * @param  value Value
+ * @param  unit  Unit value
+ * @param  units Units to derive from.
+ * @return The extracted number and unit.
  */
-export function getParsedValue( value, unit, units ) {
+export function getParsedValue(
+	value: Value,
+	unit?: string,
+	units?: WPUnitControlUnitList
+): [ Value, string | undefined ] {
 	const initialValue = unit ? `${ value }${ unit }` : value;
 
 	return parseUnit( initialValue, units );
@@ -159,32 +163,36 @@ export function getParsedValue( value, unit, units ) {
 /**
  * Checks if units are defined.
  *
- * @param {any} units Units to check.
- * @return {boolean} Whether units are defined.
+ * @param  units Units to check.
+ * @return Whether units are defined.
  */
-export function hasUnits( units ) {
-	return ! isEmpty( units ) && units !== false;
+export function hasUnits( units: WPUnitControlUnitList ): boolean {
+	return Array.isArray( units ) && !! units.length;
 }
 
 /**
  * Parses a number and unit from a value.
  *
- * @param {string}        initialValue Value to parse
- * @param {Array<Object>} units        Units to derive from.
- * @return {Array<number, string>} The extracted number and unit.
+ * @param  initialValue Value to parse
+ * @param  units        Units to derive from.
+ * @return The extracted number and unit.
  */
-export function parseUnit( initialValue, units = ALL_CSS_UNITS ) {
+export function parseUnit(
+	initialValue: Value | undefined,
+	units: WPUnitControlUnitList = ALL_CSS_UNITS
+): [ Value, string | undefined ] {
 	const value = String( initialValue ).trim();
 
-	let num = parseFloat( value, 10 );
+	let num: Value = parseFloat( value );
 	num = isNaN( num ) ? '' : num;
 
-	const unitMatch = value.match( /[\d.\-\+]*\s*(.*)/ )[ 1 ];
+	const unitMatch = value.match( /[\d.\-\+]*\s*(.*)/ );
 
-	let unit = unitMatch !== undefined ? unitMatch : '';
+	let unit: string | undefined =
+		unitMatch?.[ 1 ] !== undefined ? unitMatch[ 1 ] : '';
 	unit = unit.toLowerCase();
 
-	if ( hasUnits( units ) ) {
+	if ( hasUnits( units ) && units !== false ) {
 		const match = units.find( ( item ) => item.value === unit );
 		unit = match?.value;
 	} else {
@@ -198,18 +206,25 @@ export function parseUnit( initialValue, units = ALL_CSS_UNITS ) {
  * Parses a number and unit from a value. Validates parsed value, using fallback
  * value if invalid.
  *
- * @param {number|string} next          The next value.
- * @param {Array<Object>} units         Units to derive from.
- * @param {number|string} fallbackValue The fallback value.
- * @param {string}        fallbackUnit  The fallback value.
- * @return {Array<number, string>} The extracted number and unit.
+ * @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.
  */
-export function getValidParsedUnit( next, units, fallbackValue, fallbackUnit ) {
+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;
+	let baseUnit: string | undefined;
 
-	if ( isNaN( parsedValue ) || parsedValue === '' ) {
+	// 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;
 	}
 
@@ -219,7 +234,7 @@ export function getValidParsedUnit( next, units, fallbackValue, fallbackUnit ) {
 	 * If no unit is found, attempt to use the first value from the collection
 	 * of units as a default fallback.
 	 */
-	if ( hasUnits( units ) && ! baseUnit ) {
+	if ( Array.isArray( units ) && hasUnits( units ) && ! baseUnit ) {
 		baseUnit = units[ 0 ]?.value;
 	}
 
@@ -230,26 +245,31 @@ export function getValidParsedUnit( next, units, fallbackValue, fallbackUnit ) {
  * Takes a unit value and finds the matching accessibility label for the
  * unit abbreviation.
  *
- * @param {string} unit Unit value (example: px)
- * @return {string} a11y label for the unit abbreviation
+ * @param  unit Unit value (example: px)
+ * @return a11y label for the unit abbreviation
  */
-export function parseA11yLabelForUnit( unit ) {
+export function parseA11yLabelForUnit( 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 settings.
+ * Filters available units based on values defined by the unit setting/property.
  *
- * @param {Array} settings Collection of preferred units.
- * @param {Array} units    Collection of available units.
+ * @param  unitSetting Collection of preferred unit value strings.
+ * @param  units       Collection of available unit objects.
  *
- * @return {Array} Filtered units based on settings.
+ * @return Filtered units based on settings.
  */
-export function filterUnitsWithSettings( settings = [], units = [] ) {
-	return units.filter( ( unit ) => {
-		return settings.includes( unit.value );
-	} );
+export function filterUnitsWithSettings(
+	unitSetting: Array< string > = [],
+	units: WPUnitControlUnitList
+): Array< WPUnitControlUnit > {
+	return Array.isArray( units )
+		? units.filter( ( unit ) => {
+				return unitSetting.includes( unit.value );
+		  } )
+		: [];
 }
 
 /**
@@ -257,14 +277,22 @@ export function filterUnitsWithSettings( settings = [], units = [] ) {
  * TODO: ideally this hook shouldn't be needed
  * https://github.com/WordPress/gutenberg/pull/31822#discussion_r633280823
  *
- * @param {Object}                  args                An object containing units, settingPath & defaultUnits.
- * @param {Array<Object>|undefined} args.units          Collection of available units.
- * @param {Array<string>|undefined} args.availableUnits The setting path. Defaults to 'spacing.units'.
- * @param {Object|undefined}        args.defaultValues  Collection of default values for defined units. Example: { px: '350', em: '15' }.
+ * @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' }.
  *
- * @return {Array|boolean} Filtered units based on settings.
+ * @return Filtered units based on settings.
  */
-export const useCustomUnits = ( { units, availableUnits, defaultValues } ) => {
+export const useCustomUnits = ( {
+	units,
+	availableUnits,
+	defaultValues,
+}: {
+	units?: WPUnitControlUnitList;
+	availableUnits?: Array< string >;
+	defaultValues: Record< string, Value >;
+} ): WPUnitControlUnitList => {
 	units = units || ALL_CSS_UNITS;
 	const usedUnits = filterUnitsWithSettings(
 		! availableUnits ? [] : availableUnits,
@@ -281,3 +309,45 @@ export const useCustomUnits = ( { units, availableUnits, defaultValues } ) => {
 
 	return usedUnits.length === 0 ? false : usedUnits;
 };
+
+/**
+ * Get available units with the unit for the currently selected value
+ * prepended if it is not available in the list of units.
+ *
+ * This is useful to ensure that the current value's unit is always
+ * 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.
+ *
+ * @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,
+		legacyUnit,
+		ALL_CSS_UNITS
+	);
+
+	if (
+		currentUnit &&
+		! unitsWithCurrentUnit.some( ( unit ) => unit.value === currentUnit )
+	) {
+		if ( allUnits[ currentUnit ] ) {
+			unitsWithCurrentUnit.unshift( allUnits[ currentUnit ] );
+		}
+	}
+
+	return unitsWithCurrentUnit;
+}

package/src/utils/colors.js

@@ -1,7 +1,10 @@
 /**
  * External dependencies
  */
-import tinycolor from 'tinycolor2';
+import { colord, extend } from 'colord';
+import namesPlugin from 'colord/plugins/names';
+
+extend( [ namesPlugin ] );
 
 /**
  * Generating a CSS compliant rgba() color value.
@@ -15,6 +18,5 @@ import tinycolor from 'tinycolor2';
  * // rgba(0, 0, 0, 0.5)
  */
 export function rgba( hexValue = '', alpha = 1 ) {
-	const { r, g, b } = tinycolor( hexValue ).toRgb();
-	return `rgba(${ r }, ${ g }, ${ b }, ${ alpha })`;
+	return colord( hexValue ).alpha( alpha ).toRgbString();
 }

package/src/utils/hooks/index.js

@@ -1,6 +1,6 @@
 export { default as useControlledState } from './use-controlled-state';
-export { default as useJumpStep } from './use-jump-step';
 export { default as useUpdateEffect } from './use-update-effect';
+export { useCombinedRef } from './use-combined-ref';
 export { useControlledValue } from './use-controlled-value';
 export { useCx } from './use-cx';
 export { useLatestRef } from './use-latest-ref';

package/src/utils/hooks/use-combined-ref.ts

@@ -0,0 +1,29 @@
+/**
+ * WordPress dependencies
+ */
+import { useRef, useEffect } from '@wordpress/element';
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import type { MutableRefObject, RefCallback } from 'react';
+
+type Ref< T > = MutableRefObject< T | null > | RefCallback< T | null >;
+
+export function useCombinedRef< T extends HTMLElement >( ...refs: Ref< T >[] ) {
+	const targetRef = useRef( null );
+
+	useEffect( () => {
+		refs.forEach( ( ref ) => {
+			if ( ! ref ) return;
+
+			if ( typeof ref === 'function' ) {
+				ref( targetRef.current );
+			} else {
+				ref.current = targetRef.current;
+			}
+		} );
+	}, [ refs ] );
+
+	return targetRef;
+}

package/src/utils/test/colors.js

@@ -0,0 +1,11 @@
+/**
+ * Internal dependencies
+ */
+import { rgba } from '../colors';
+
+describe( 'rbga', () => {
+	it( 'should output the expected string', () => {
+		expect( rgba( '#000000', 0.5 ) ).toBe( 'rgba(0, 0, 0, 0.5)' );
+		expect( rgba( '#f00', 0.2 ) ).toBe( 'rgba(255, 0, 0, 0.2)' );
+	} );
+} );

package/src/v-stack/component.js

@@ -1,9 +1,20 @@
 /**
  * Internal dependencies
  */
-import { createComponent } from '../ui/utils';
+import { contextConnect } from '../ui/context';
+import { View } from '../view';
 import { useVStack } from './hook';
 
+/**
+ * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
+ * @param {import('react').Ref<any>}                                                        forwardedRef
+ */
+function VStack( props, forwardedRef ) {
+	const vStackProps = useVStack( props );
+
+	return <View { ...vStackProps } ref={ forwardedRef } />;
+}
+
 /**
  * `VStack` (or Vertical Stack) is a layout component that arranges child elements in a vertical line.
  *
@@ -27,10 +38,6 @@ import { useVStack } from './hook';
  * }
  * ```
  */
-const VStack = createComponent( {
-	as: 'div',
-	useHook: useVStack,
-	name: 'VStack',
-} );
+const ConnectedVStack = contextConnect( VStack, 'VStack' );
 
-export default VStack;
+export default ConnectedVStack;

package/src/z-stack/stories/index.js

@@ -14,6 +14,9 @@ import { ZStack } from '..';
 export default {
 	component: ZStack,
 	title: 'Components (Experimental)/ZStack',
+	parameters: {
+		knobs: { disabled: false },
+	},
 };
 
 const Avatar = ( { backgroundColor } ) => {