@wordpress/components 19.6.1 → 19.8.0

package/src/unit-control/index.tsx

@@ -7,23 +7,23 @@ import type {
 	ForwardedRef,
 	SyntheticEvent,
 	ChangeEvent,
+	PointerEvent,
 } from 'react';
-import { noop, omit } from 'lodash';
+import { omit } from 'lodash';
 import classnames from 'classnames';
 
 /**
  * WordPress dependencies
  */
+import deprecated from '@wordpress/deprecated';
 import { forwardRef, useMemo, useRef, useEffect } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
-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';
 import UnitSelectControl from './unit-select-control';
 import {
@@ -36,9 +36,16 @@ import { useControlledState } from '../utils/hooks';
 import type { UnitControlProps, UnitControlOnChangeCallback } from './types';
 import type { StateReducer } from '../input-control/reducer/state';
 
-function UnitControl(
-	{
-		__unstableStateReducer: stateReducer = ( state ) => state,
+function UnforwardedUnitControl(
+	unitControlProps: WordPressComponentProps<
+		UnitControlProps,
+		'input',
+		false
+	>,
+	forwardedRef: ForwardedRef< any >
+) {
+	const {
+		__unstableStateReducer: stateReducerProp,
 		autoComplete = 'off',
 		className,
 		disabled = false,
@@ -47,17 +54,25 @@ function UnitControl(
 		isResetValueOnUnitChange = false,
 		isUnitSelectTabbable = true,
 		label,
-		onChange = noop,
-		onUnitChange = noop,
+		onChange: onChangeProp,
+		onUnitChange,
 		size = 'default',
 		style,
 		unit: unitProp,
 		units: unitsProp = CSS_UNITS,
 		value: valueProp,
+		onBlur: onBlurProp,
 		...props
-	}: WordPressComponentProps< UnitControlProps, 'input', false >,
-	forwardedRef: ForwardedRef< any >
-) {
+	} = unitControlProps;
+
+	if ( 'unit' in unitControlProps ) {
+		deprecated( 'UnitControl unit prop', {
+			since: '5.6',
+			hint: 'The unit should be provided within the `value` prop.',
+			version: '6.2',
+		} );
+	}
+
 	// 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`.
@@ -81,7 +96,9 @@ function UnitControl(
 	);
 
 	useEffect( () => {
-		setUnit( parsedUnit );
+		if ( parsedUnit !== undefined ) {
+			setUnit( parsedUnit );
+		}
 	}, [ parsedUnit ] );
 
 	// Stores parsed value for hand-off in state reducer.
@@ -91,14 +108,18 @@ function UnitControl(
 
 	const handleOnQuantityChange = (
 		nextQuantityValue: number | string | undefined,
-		changeProps: { event: ChangeEvent< HTMLInputElement > }
+		changeProps: {
+			event:
+				| ChangeEvent< HTMLInputElement >
+				| PointerEvent< HTMLInputElement >;
+		}
 	) => {
 		if (
 			nextQuantityValue === '' ||
 			typeof nextQuantityValue === 'undefined' ||
 			nextQuantityValue === null
 		) {
-			onChange( '', changeProps );
+			onChangeProp?.( '', changeProps );
 			return;
 		}
 
@@ -113,7 +134,7 @@ function UnitControl(
 			unit
 		).join( '' );
 
-		onChange( onChangeValue, changeProps );
+		onChangeProp?.( onChangeValue, changeProps );
 	};
 
 	const handleOnUnitChange: UnitControlOnChangeCallback = (
@@ -128,8 +149,8 @@ function UnitControl(
 			nextValue = `${ data.default }${ nextUnitValue }`;
 		}
 
-		onChange( nextValue, changeProps );
-		onUnitChange( nextUnitValue, changeProps );
+		onChangeProp?.( nextValue, changeProps );
+		onUnitChange?.( nextUnitValue, changeProps );
 
 		setUnit( nextUnitValue );
 	};
@@ -157,21 +178,24 @@ function UnitControl(
 				: undefined;
 			const changeProps = { event, data };
 
-			onChange(
+			onChangeProp?.(
 				`${ validParsedQuantity ?? '' }${ validParsedUnit }`,
 				changeProps
 			);
-			onUnitChange( validParsedUnit, changeProps );
+			onUnitChange?.( validParsedUnit, changeProps );
 
 			setUnit( validParsedUnit );
 		}
 	};
 
-	const handleOnBlur: FocusEventHandler< HTMLInputElement > = mayUpdateUnit;
+	const handleOnBlur: FocusEventHandler< HTMLInputElement > = ( event ) => {
+		mayUpdateUnit( event );
+		onBlurProp?.( event );
+	};
 
 	const handleOnKeyDown = ( event: KeyboardEvent< HTMLInputElement > ) => {
-		const { keyCode } = event;
-		if ( keyCode === ENTER ) {
+		const { key } = event;
+		if ( key === 'Enter' ) {
 			mayUpdateUnit( event );
 		}
 	};
@@ -186,6 +210,8 @@ function UnitControl(
 	 * @return The updated state to apply to InputControl
 	 */
 	const unitControlStateReducer: StateReducer = ( state, action ) => {
+		const nextState = { ...state };
+
 		/*
 		 * On commits (when pressing ENTER and on blur if
 		 * isPressEnterToChange is true), if a parse has been performed
@@ -193,14 +219,24 @@ function UnitControl(
 		 */
 		if ( action.type === inputControlActionTypes.COMMIT ) {
 			if ( refParsedQuantity.current !== undefined ) {
-				state.value = ( refParsedQuantity.current ?? '' ).toString();
+				nextState.value = (
+					refParsedQuantity.current ?? ''
+				).toString();
 				refParsedQuantity.current = undefined;
 			}
 		}
 
-		return state;
+		return nextState;
 	};
 
+	let stateReducer: StateReducer = unitControlStateReducer;
+	if ( stateReducerProp ) {
+		stateReducer = ( state, action ) => {
+			const baseState = unitControlStateReducer( state, action );
+			return stateReducerProp( baseState, action );
+		};
+	}
+
 	const inputSuffix = ! disableUnits ? (
 		<UnitSelectControl
 			aria-label={ __( 'Select unit' ) }
@@ -210,6 +246,7 @@ function UnitControl(
 			size={ size }
 			unit={ unit }
 			units={ units }
+			onBlur={ onBlurProp }
 		/>
 	) : null;
 
@@ -244,17 +281,14 @@ function UnitControl(
 				suffix={ inputSuffix }
 				value={ parsedQuantity ?? '' }
 				step={ step }
-				__unstableStateReducer={ composeStateReducers(
-					unitControlStateReducer,
-					stateReducer
-				) }
+				__unstableStateReducer={ stateReducer }
 			/>
 		</Root>
 	);
 }
 
 /**
- * `UnitControl` allows the user to set a value as well as a unit (e.g. `px`).
+ * `UnitControl` allows the user to set a numeric quantity as well as a unit (e.g. `px`).
  *
  *
  * @example
@@ -269,7 +303,7 @@ function UnitControl(
  * };
  * ```
  */
-const ForwardedUnitControl = forwardRef( UnitControl );
+export const UnitControl = forwardRef( UnforwardedUnitControl );
 
 export { parseQuantityAndUnitFromRawValue, useCustomUnits } from './utils';
-export default ForwardedUnitControl;
+export default UnitControl;

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

@@ -0,0 +1,170 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { UnitControl } from '../';
+import { CSS_UNITS } from '../utils';
+
+const meta: ComponentMeta< typeof UnitControl > = {
+	component: UnitControl,
+	title: 'Components (Experimental)/UnitControl',
+	argTypes: {
+		__unstableInputWidth: {
+			control: { type: 'text' },
+		},
+		__unstableStateReducer: {
+			control: { type: null },
+		},
+		size: {
+			control: { type: 'select' },
+		},
+		onChange: {
+			action: 'onChange',
+			control: { type: null },
+		},
+		onUnitChange: {
+			control: { type: null },
+		},
+		value: {
+			control: { type: null },
+		},
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const DefaultTemplate: ComponentStory< typeof UnitControl > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ value, setValue ] = useState< string | undefined >( '10px' );
+
+	return (
+		<div style={ { maxWidth: '100px' } }>
+			<UnitControl
+				{ ...args }
+				value={ value }
+				onChange={ ( v, extra ) => {
+					setValue( v );
+					onChange?.( v, extra );
+				} }
+			/>
+		</div>
+	);
+};
+
+export const Default: ComponentStory<
+	typeof UnitControl
+> = DefaultTemplate.bind( {} );
+Default.args = {
+	label: 'Label',
+};
+
+/**
+ * If the `isPressEnterToChange` prop is set to `true`, the `onChange` callback
+ * will not fire while a new value is typed in the input field (you can verify this
+ * behavior by inspecting the console's output).
+ */
+export const PressEnterToChange: ComponentStory<
+	typeof UnitControl
+> = DefaultTemplate.bind( {} );
+PressEnterToChange.args = {
+	...Default.args,
+	isPressEnterToChange: true,
+	onChange: ( v ) => {
+		// eslint-disable-next-line no-console
+		console.log( v );
+	},
+};
+
+/**
+ * Most of `NumberControl`'s props can be passed to `UnitControl`, and they will
+ * affect its numeric input field.
+ */
+export const TweakingTheNumberInput: ComponentStory<
+	typeof UnitControl
+> = DefaultTemplate.bind( {} );
+TweakingTheNumberInput.args = {
+	...Default.args,
+	min: 0,
+	max: 100,
+	step: 'any',
+	label: 'Custom label',
+};
+
+/**
+ * When only one unit is available, the unit selection dropdown becomes static text.
+ */
+export const WithSingleUnit: ComponentStory<
+	typeof UnitControl
+> = DefaultTemplate.bind( {} );
+WithSingleUnit.args = {
+	...Default.args,
+	units: CSS_UNITS.slice( 0, 1 ),
+};
+
+/**
+ * It is possible to pass a custom list of units. Every time the unit changes,
+ * if the `isResetValueOnUnitChange` is set to `true`, the input's quantity is
+ * reset to the new unit's default value.
+ */
+export const WithCustomUnits: ComponentStory< typeof UnitControl > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ value, setValue ] = useState< string | undefined >( '80km' );
+
+	return (
+		<div style={ { maxWidth: '100px' } }>
+			<UnitControl
+				{ ...args }
+				value={ value }
+				onChange={ ( v, extra ) => {
+					setValue( v );
+					onChange?.( v, extra );
+				} }
+			/>
+		</div>
+	);
+};
+WithCustomUnits.args = {
+	...Default.args,
+	isResetValueOnUnitChange: true,
+	min: 0,
+	units: [
+		{
+			value: 'km',
+			label: 'km',
+			default: 1,
+		},
+		{
+			value: 'mi',
+			label: 'mi',
+			default: 1,
+		},
+		{
+			value: 'm',
+			label: 'm',
+			default: 1000,
+		},
+		{
+			value: 'yd',
+			label: 'yd',
+			default: 1760,
+		},
+	],
+};