@wordpress/components 18.0.0 → 19.0.3

package/src/unit-control/{index.js → index.tsx}

@@ -1,6 +1,13 @@
 /**
  * External dependencies
  */
+// eslint-disable-next-line no-restricted-imports
+import type {
+	FocusEventHandler,
+	KeyboardEvent,
+	Ref,
+	SyntheticEvent,
+} from 'react';
 import { noop, omit } from 'lodash';
 import classnames from 'classnames';
 
@@ -14,6 +21,7 @@ import { ENTER } from '@wordpress/keycodes';
 /**
  * Internal dependencies
  */
+import type { WordPressComponentProps } from '../ui/context';
 import * as inputControlActionTypes from '../input-control/reducer/actions';
 import { composeStateReducers } from '../input-control/reducer/reducer';
 import { Root, ValueInput } from './styles/unit-control-styles';
@@ -25,6 +33,8 @@ import {
 	getValidParsedUnit,
 } from './utils';
 import { useControlledState } from '../utils/hooks';
+import type { UnitControlProps, UnitControlOnChangeCallback } from './types';
+import type { StateReducer } from '../input-control/reducer/state';
 
 function UnitControl(
 	{
@@ -45,24 +55,31 @@ function UnitControl(
 		units: unitsProp = CSS_UNITS,
 		value: valueProp,
 		...props
-	},
-	ref
+	}: WordPressComponentProps< UnitControlProps, 'input', false >,
+	forwardedRef: Ref< any >
 ) {
 	const units = useMemo(
 		() => getUnitsWithCurrentUnit( valueProp, unitProp, unitsProp ),
 		[ valueProp, unitProp, unitsProp ]
 	);
 	const [ value, initialUnit ] = getParsedValue( valueProp, unitProp, units );
-	const [ unit, setUnit ] = useControlledState( unitProp, {
-		initial: initialUnit,
-	} );
+	const [ unit, setUnit ] = useControlledState< string | undefined >(
+		unitProp,
+		{
+			initial: initialUnit,
+			fallback: '',
+		}
+	);
 
 	// Stores parsed value for hand-off in state reducer
-	const refParsedValue = useRef( null );
+	const refParsedValue = useRef< string | null >( null );
 
 	const classes = classnames( 'components-unit-control', className );
 
-	const handleOnChange = ( next, changeProps ) => {
+	const handleOnChange: UnitControlOnChangeCallback = (
+		next,
+		changeProps
+	) => {
 		if ( next === '' ) {
 			onChange( '', changeProps );
 			return;
@@ -77,7 +94,10 @@ function UnitControl(
 		onChange( next, changeProps );
 	};
 
-	const handleOnUnitChange = ( next, changeProps ) => {
+	const handleOnUnitChange: UnitControlOnChangeCallback = (
+		next,
+		changeProps
+	) => {
 		const { data } = changeProps;
 
 		let nextValue = `${ value }${ next }`;
@@ -92,24 +112,24 @@ function UnitControl(
 		setUnit( next );
 	};
 
-	const mayUpdateUnit = ( event ) => {
-		if ( ! isNaN( event.target.value ) ) {
+	const mayUpdateUnit = ( event: SyntheticEvent< HTMLInputElement > ) => {
+		if ( ! isNaN( Number( event.currentTarget.value ) ) ) {
 			refParsedValue.current = null;
 			return;
 		}
 		const [ parsedValue, parsedUnit ] = getValidParsedUnit(
-			event.target.value,
+			event.currentTarget.value,
 			units,
 			value,
 			unit
 		);
 
-		refParsedValue.current = parsedValue;
+		refParsedValue.current = parsedValue.toString();
 
 		if ( isPressEnterToChange && parsedUnit !== unit ) {
-			const data = units.find(
-				( option ) => option.value === parsedUnit
-			);
+			const data = Array.isArray( units )
+				? units.find( ( option ) => option.value === parsedUnit )
+				: undefined;
 			const changeProps = { event, data };
 
 			onChange( `${ parsedValue }${ parsedUnit }`, changeProps );
@@ -119,9 +139,9 @@ function UnitControl(
 		}
 	};
 
-	const handleOnBlur = mayUpdateUnit;
+	const handleOnBlur: FocusEventHandler< HTMLInputElement > = mayUpdateUnit;
 
-	const handleOnKeyDown = ( event ) => {
+	const handleOnKeyDown = ( event: KeyboardEvent< HTMLInputElement > ) => {
 		const { keyCode } = event;
 		if ( keyCode === ENTER ) {
 			mayUpdateUnit( event );
@@ -133,11 +153,11 @@ function UnitControl(
 	 * This allows us to tap into actions to transform the (next) state for
 	 * InputControl.
 	 *
-	 * @param {Object} state  State from InputControl
-	 * @param {Object} action Action triggering state change
-	 * @return {Object} The updated state to apply to InputControl
+	 * @param  state  State from InputControl
+	 * @param  action Action triggering state change
+	 * @return The updated state to apply to InputControl
 	 */
-	const unitControlStateReducer = ( state, action ) => {
+	const unitControlStateReducer: StateReducer = ( state, action ) => {
 		/*
 		 * On commits (when pressing ENTER and on blur if
 		 * isPressEnterToChange is true), if a parse has been performed
@@ -157,11 +177,11 @@ function UnitControl(
 		<UnitSelectControl
 			aria-label={ __( 'Select unit' ) }
 			disabled={ disabled }
-			isTabbable={ isUnitSelectTabbable }
-			options={ units }
+			isUnitSelectTabbable={ isUnitSelectTabbable }
 			onChange={ handleOnUnitChange }
 			size={ size }
-			value={ unit }
+			unit={ unit }
+			units={ units }
 		/>
 	) : null;
 
@@ -191,7 +211,7 @@ function UnitControl(
 				onBlur={ handleOnBlur }
 				onKeyDown={ handleOnKeyDown }
 				onChange={ handleOnChange }
-				ref={ ref }
+				ref={ forwardedRef }
 				size={ size }
 				suffix={ inputSuffix }
 				value={ value }
@@ -205,6 +225,22 @@ function UnitControl(
 	);
 }
 
+/**
+ * `UnitControl` allows the user to set a value as well as a unit (e.g. `px`).
+ *
+ *
+ * @example
+ * ```jsx
+ * import { __experimentalUnitControl as UnitControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const Example = () => {
+ *   const [ value, setValue ] = useState( '10px' );
+ *
+ *   return <UnitControl onChange={ setValue } value={ value } />;
+ * };
+ * ```
+ */
 const ForwardedUnitControl = forwardRef( UnitControl );
 
 export { parseUnit, useCustomUnits } from './utils';

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

@@ -18,6 +18,9 @@ import { CSS_UNITS } from '../utils';
 export default {
 	title: 'Components/UnitControl',
 	component: UnitControl,
+	parameters: {
+		knobs: { disabled: false },
+	},
 };
 
 const ControlWrapperView = styled.div`

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

@@ -8,13 +8,24 @@ import styled from '@emotion/styled';
  */
 import { COLORS, rtl } from '../../utils';
 import NumberControl from '../../number-control';
+import type { SelectSize } from '../types';
+
+// Using `selectSize` instead of `size` to avoid a type conflict with the
+// `size` HTML attribute of the `select` element.
+type SelectProps = {
+	selectSize: SelectSize;
+};
+
+type InputProps = {
+	disableUnits?: boolean;
+};
 
 export const Root = styled.div`
 	box-sizing: border-box;
 	position: relative;
 `;
 
-const paddingStyles = ( { disableUnits } ) => {
+const paddingStyles = ( { disableUnits }: InputProps ) => {
 	const value = disableUnits ? 3 : 24;
 
 	return css`
@@ -22,7 +33,7 @@ const paddingStyles = ( { disableUnits } ) => {
 	`;
 };
 
-const arrowStyles = ( { disableUnits } ) => {
+const arrowStyles = ( { disableUnits }: InputProps ) => {
 	if ( disableUnits ) return '';
 
 	return css`
@@ -51,7 +62,7 @@ export const ValueInput = styled( NumberControl )`
 	}
 `;
 
-const unitSizeStyles = ( { size } ) => {
+const unitSizeStyles = ( { selectSize }: SelectProps ) => {
 	const sizes = {
 		default: {
 			height: 28,
@@ -67,10 +78,10 @@ const unitSizeStyles = ( { size } ) => {
 		},
 	};
 
-	return css( sizes[ size ] );
+	return css( sizes[ selectSize ] );
 };
 
-const baseUnitLabelStyles = ( props ) => {
+const baseUnitLabelStyles = ( props: SelectProps ) => {
 	return css`
 		appearance: none;
 		background: transparent;
@@ -95,7 +106,7 @@ const baseUnitLabelStyles = ( props ) => {
 	`;
 };
 
-export const UnitLabel = styled.div`
+export const UnitLabel = styled.div< SelectProps >`
 	&&& {
 		pointer-events: none;
 
@@ -103,7 +114,7 @@ export const UnitLabel = styled.div`
 	}
 `;
 
-export const UnitSelect = styled.select`
+export const UnitSelect = styled.select< SelectProps >`
 	&&& {
 		${ baseUnitLabelStyles };
 		cursor: pointer;

package/src/unit-control/types.ts

@@ -1,5 +1,19 @@
+/**
+ * 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`).
@@ -24,3 +38,78 @@ export type WPUnitControlUnit = {
 };
 
 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.ts

@@ -154,7 +154,7 @@ export function getParsedValue(
 	value: Value,
 	unit?: string,
 	units?: WPUnitControlUnitList
-): [ Value, string ] {
+): [ Value, string | undefined ] {
 	const initialValue = unit ? `${ value }${ unit }` : value;
 
 	return parseUnit( initialValue, units );
@@ -178,17 +178,18 @@ export function hasUnits( units: WPUnitControlUnitList ): boolean {
  * @return The extracted number and unit.
  */
 export function parseUnit(
-	initialValue: Value,
+	initialValue: Value | undefined,
 	units: WPUnitControlUnitList = ALL_CSS_UNITS
-): [ Value, string ] {
+): [ Value, string | undefined ] {
 	const value = String( initialValue ).trim();
 
 	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 ) && units !== false ) {
@@ -212,14 +213,14 @@ export function parseUnit(
  * @return The extracted value and unit.
  */
 export function getValidParsedUnit(
-	next: Value,
+	next: Value | undefined,
 	units: WPUnitControlUnitList,
 	fallbackValue: Value,
-	fallbackUnit: string
-) {
+	fallbackUnit: string | undefined
+): [ Value, string | undefined ] {
 	const [ parsedValue, parsedUnit ] = parseUnit( next, units );
 	let baseValue = parsedValue;
-	let baseUnit: string;
+	let baseUnit: string | undefined;
 
 	// The parsed value from `parseUnit` should now be either a
 	// real number or an empty string. If not, use the fallback value.
@@ -233,7 +234,7 @@ export function getValidParsedUnit(
 	 * 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;
 	}
 
@@ -247,7 +248,7 @@ export function getValidParsedUnit(
  * @param  unit Unit value (example: px)
  * @return a11y label for the unit abbreviation
  */
-export function parseA11yLabelForUnit( unit: string ): string {
+export function parseA11yLabelForUnit( unit: string ): string | undefined {
 	const match = ALL_CSS_UNITS.find( ( item ) => item.value === unit );
 	return match?.a11yLabel ? match?.a11yLabel : match?.value;
 }
@@ -326,7 +327,7 @@ export const useCustomUnits = ( {
 export function getUnitsWithCurrentUnit(
 	currentValue: Value,
 	legacyUnit: string | undefined,
-	units: Array< WPUnitControlUnit > | false = ALL_CSS_UNITS
+	units: WPUnitControlUnitList = ALL_CSS_UNITS
 ): WPUnitControlUnitList {
 	if ( ! Array.isArray( units ) ) {
 		return units;

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/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 } ) => {

package/tsconfig.json

@@ -6,7 +6,8 @@
 		"types": [ "gutenberg-env" ],
 		// Some errors in Reakit types with TypeScript 4.3
 		// Remove the following line when they've been addressed.
-		"skipLibCheck": true
+		"skipLibCheck": true,
+		"strictNullChecks": true
 	},
 	"references": [
 		{ "path": "../compose" },
@@ -50,6 +51,7 @@
 		"src/number-control/**/*",
 		"src/popover/**/*",
 		"src/range-control/**/*",
+		"src/resizable-box/**/*",
 		"src/scroll-lock/**/*",
 		"src/scrollable/**/*",
 		"src/select-control/**/*",
@@ -65,6 +67,7 @@
 		"src/tooltip/**/*",
 		"src/truncate/**/*",
 		"src/ui/**/*",
+		"src/unit-control/**/*",
 		"src/utils/**/*",
 		"src/v-stack/**/*",
 		"src/view/**/*",