@wordpress/components 23.3.2 → 23.4.0

package/src/box-control/README.md

@@ -30,82 +30,73 @@ const Example = () => {
 ```
 
 ## Props
-### allowReset
+### `allowReset`: `boolean`
 
 If this property is true, a button to reset the box control is rendered.
 
-- Type: `Boolean`
 - Required: No
 - Default: `true`
 
-### splitOnAxis
+### `splitOnAxis`: `boolean`
 
 If this property is true, when the box control is unlinked, vertical and horizontal controls can be used instead of updating individual sides.
 
-- Type: `Boolean`
 - Required: No
 - Default: `false`
 
-### inputProps
+### `inputProps`: `object`
 
-Props for the internal [InputControl](../input-control) components.
+Props for the internal [UnitControl](../unit-control) components.
 
--   Type: `Object`
 -   Required: No
+-   Default: `{ min: 0 }`
 
-### label
+### `label`: `string`
 
-Heading label for BoxControl.
+Heading label for the control.
 
--   Type: `String`
 -   Required: No
--   Default: `Box Control`
+-   Default: `__( 'Box Control' )`
 
-### onChange
+### `onChange`: `(next: BoxControlValue) => void`
 
 A callback function when an input value changes.
 
--   Type: `Function`
 -   Required: Yes
 
-### resetValues
+### `resetValues`: `object`
 
 The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset.
 
--   Type: `Object`
 -   Required: No
+-   Default: `{ top: undefined, right: undefined, bottom: undefined, left: undefined }`
 
-### sides
+### `sides`: `string[]`
 
-Collection of sides to allow control of. If omitted or empty, all sides will be available.
+Collection of sides to allow control of. If omitted or empty, all sides will be available. Allowed values are "top", "right", "bottom", "left", "vertical", and "horizontal".
 
--   Type: `Array<Object>`
 -   Required: No
 
-### units
+### `units`: `WPUnitControlUnit[]`
 
 Collection of available units which are compatible with [UnitControl](../unit-control).
 
--   Type: `Array<Object>`
 -   Required: No
 
-### values
+### `values`: `object`
 
 The `top`, `right`, `bottom`, and `left` box dimension values.
 
--   Type: `Object`
 -   Required: No
 
-### onMouseOver
+### `onMouseOver`: `function`
 
 A handler for onMouseOver events.
 
--   Type: `Function`
 -   Required: No
 
-### onMouseOut
+### `onMouseOut`: `function`
 
 A handler for onMouseOut events.
 
--   Type: `Function`
 -   Required: No

package/src/box-control/{all-input-control.js → all-input-control.tsx}

@@ -1,6 +1,8 @@
 /**
  * Internal dependencies
  */
+import type { UnitControlProps } from '../unit-control/types';
+import type { BoxControlInputControlProps } from './types';
 import UnitControl from './unit-control';
 import {
 	LABELS,
@@ -22,18 +24,20 @@ export default function AllInputControl( {
 	selectedUnits,
 	setSelectedUnits,
 	...props
-} ) {
+}: BoxControlInputControlProps ) {
 	const allValue = getAllValue( values, selectedUnits, sides );
 	const hasValues = isValuesDefined( values );
 	const isMixed = hasValues && isValuesMixed( values, selectedUnits, sides );
-	const allPlaceholder = isMixed ? LABELS.mixed : null;
+	const allPlaceholder = isMixed ? LABELS.mixed : undefined;
 
-	const handleOnFocus = ( event ) => {
+	const handleOnFocus: React.FocusEventHandler< HTMLInputElement > = (
+		event
+	) => {
 		onFocus( event, { side: 'all' } );
 	};
 
-	const handleOnChange = ( next ) => {
-		const isNumeric = ! isNaN( parseFloat( next ) );
+	const handleOnChange: UnitControlProps[ 'onChange' ] = ( next ) => {
+		const isNumeric = next !== undefined && ! isNaN( parseFloat( next ) );
 		const nextValue = isNumeric ? next : undefined;
 		const nextValues = applyValueToSides( values, nextValue, sides );
 
@@ -42,7 +46,7 @@ export default function AllInputControl( {
 
 	// Set selected unit so it can be used as fallback by unlinked controls
 	// when individual sides do not have a value containing a unit.
-	const handleOnUnitChange = ( unit ) => {
+	const handleOnUnitChange: UnitControlProps[ 'onUnitChange' ] = ( unit ) => {
 		const newUnits = applyValueToSides( selectedUnits, unit, sides );
 		setSelectedUnits( newUnits );
 	};

package/src/box-control/{axial-input-controls.js → axial-input-controls.tsx}

@@ -5,8 +5,10 @@ import { parseQuantityAndUnitFromRawValue } from '../unit-control/utils';
 import UnitControl from './unit-control';
 import { LABELS } from './utils';
 import { Layout } from './styles/box-control-styles';
+import type { BoxControlInputControlProps } from './types';
 
-const groupedSides = [ 'vertical', 'horizontal' ];
+const groupedSides = [ 'vertical', 'horizontal' ] as const;
+type GroupedSide = typeof groupedSides[ number ];
 
 export default function AxialInputControls( {
 	onChange,
@@ -18,15 +20,17 @@ export default function AxialInputControls( {
 	setSelectedUnits,
 	sides,
 	...props
-} ) {
-	const createHandleOnFocus = ( side ) => ( event ) => {
-		if ( ! onFocus ) {
-			return;
-		}
-		onFocus( event, { side } );
-	};
+}: BoxControlInputControlProps ) {
+	const createHandleOnFocus =
+		( side: GroupedSide ) =>
+		( event: React.FocusEvent< HTMLInputElement > ) => {
+			if ( ! onFocus ) {
+				return;
+			}
+			onFocus( event, { side } );
+		};
 
-	const createHandleOnHoverOn = ( side ) => () => {
+	const createHandleOnHoverOn = ( side: GroupedSide ) => () => {
 		if ( ! onHoverOn ) {
 			return;
 		}
@@ -44,7 +48,7 @@ export default function AxialInputControls( {
 		}
 	};
 
-	const createHandleOnHoverOff = ( side ) => () => {
+	const createHandleOnHoverOff = ( side: GroupedSide ) => () => {
 		if ( ! onHoverOff ) {
 			return;
 		}
@@ -62,12 +66,12 @@ export default function AxialInputControls( {
 		}
 	};
 
-	const createHandleOnChange = ( side ) => ( next ) => {
+	const createHandleOnChange = ( side: GroupedSide ) => ( next?: string ) => {
 		if ( ! onChange ) {
 			return;
 		}
 		const nextValues = { ...values };
-		const isNumeric = ! isNaN( parseFloat( next ) );
+		const isNumeric = next !== undefined && ! isNaN( parseFloat( next ) );
 		const nextValue = isNumeric ? next : undefined;
 
 		if ( side === 'vertical' ) {
@@ -83,21 +87,22 @@ export default function AxialInputControls( {
 		onChange( nextValues );
 	};
 
-	const createHandleOnUnitChange = ( side ) => ( next ) => {
-		const newUnits = { ...selectedUnits };
+	const createHandleOnUnitChange =
+		( side: GroupedSide ) => ( next?: string ) => {
+			const newUnits = { ...selectedUnits };
 
-		if ( side === 'vertical' ) {
-			newUnits.top = next;
-			newUnits.bottom = next;
-		}
+			if ( side === 'vertical' ) {
+				newUnits.top = next;
+				newUnits.bottom = next;
+			}
 
-		if ( side === 'horizontal' ) {
-			newUnits.left = next;
-			newUnits.right = next;
-		}
+			if ( side === 'horizontal' ) {
+				newUnits.left = next;
+				newUnits.right = next;
+			}
 
-		setSelectedUnits( newUnits );
-	};
+			setSelectedUnits( newUnits );
+		};
 
 	// Filter sides if custom configuration provided, maintaining default order.
 	const filteredSides = sides?.length

package/src/box-control/{icon.js → icon.tsx}

@@ -1,6 +1,7 @@
 /**
  * Internal dependencies
  */
+import type { WordPressComponentProps } from '../ui/context';
 import {
 	Root,
 	Viewbox,
@@ -9,6 +10,7 @@ import {
 	BottomStroke,
 	LeftStroke,
 } from './styles/box-control-icon-styles';
+import type { BoxControlIconProps, BoxControlProps } from './types';
 
 const BASE_ICON_SIZE = 24;
 
@@ -17,11 +19,14 @@ export default function BoxControlIcon( {
 	side = 'all',
 	sides,
 	...props
-} ) {
-	const isSideDisabled = ( value ) =>
-		sides?.length && ! sides.includes( value );
+}: WordPressComponentProps< BoxControlIconProps, 'span' > ) {
+	const isSideDisabled = (
+		value: NonNullable< BoxControlProps[ 'sides' ] >[ number ]
+	) => sides?.length && ! sides.includes( value );
 
-	const hasSide = ( value ) => {
+	const hasSide = (
+		value: NonNullable< BoxControlProps[ 'sides' ] >[ number ]
+	) => {
 		if ( isSideDisabled( value ) ) {
 			return false;
 		}

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

@@ -29,6 +29,11 @@ import {
 	isValuesDefined,
 } from './utils';
 import { useControlledState } from '../utils/hooks';
+import type {
+	BoxControlIconProps,
+	BoxControlProps,
+	BoxControlValue,
+} from './types';
 
 const defaultInputProps = {
 	min: 0,
@@ -36,12 +41,38 @@ const defaultInputProps = {
 
 const noop = () => {};
 
-function useUniqueId( idProp ) {
+function useUniqueId( idProp?: string ) {
 	const instanceId = useInstanceId( BoxControl, 'inspector-box-control' );
 
 	return idProp || instanceId;
 }
-export default function BoxControl( {
+
+/**
+ * BoxControl components let users set values for Top, Right, Bottom, and Left.
+ * This can be used as an input control for values like `padding` or `margin`.
+ *
+ * ```jsx
+ * import { __experimentalBoxControl as BoxControl } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const Example = () => {
+ * 	const [ values, setValues ] = useState( {
+ * 		top: '50px',
+ * 		left: '10%',
+ * 		right: '10%',
+ * 		bottom: '50px',
+ * 	} );
+ *
+ * 	return (
+ * 		<BoxControl
+ * 			values={ values }
+ * 			onChange={ ( nextValues ) => setValues( nextValues ) }
+ * 		/>
+ * 	);
+ * };
+ * ```
+ */
+function BoxControl( {
 	id: idProp,
 	inputProps = defaultInputProps,
 	onChange = noop,
@@ -54,7 +85,7 @@ export default function BoxControl( {
 	resetValues = DEFAULT_VALUES,
 	onMouseOver,
 	onMouseOut,
-} ) {
+}: BoxControlProps ) {
 	const [ values, setValues ] = useControlledState( valuesProp, {
 		fallback: DEFAULT_VALUES,
 	} );
@@ -67,14 +98,14 @@ export default function BoxControl( {
 		! hasInitialValue || ! isValuesMixed( inputValues ) || hasOneSide
 	);
 
-	const [ side, setSide ] = useState(
+	const [ side, setSide ] = useState< BoxControlIconProps[ 'side' ] >(
 		getInitialSide( isLinked, splitOnAxis )
 	);
 
 	// Tracking selected units via internal state allows filtering of CSS unit
 	// only values from being saved while maintaining preexisting unit selection
 	// behaviour. Filtering CSS only values prevents invalid style values.
-	const [ selectedUnits, setSelectedUnits ] = useState( {
+	const [ selectedUnits, setSelectedUnits ] = useState< BoxControlValue >( {
 		top: parseQuantityAndUnitFromRawValue( valuesProp?.top )[ 1 ],
 		right: parseQuantityAndUnitFromRawValue( valuesProp?.right )[ 1 ],
 		bottom: parseQuantityAndUnitFromRawValue( valuesProp?.bottom )[ 1 ],
@@ -89,11 +120,14 @@ export default function BoxControl( {
 		setSide( getInitialSide( ! isLinked, splitOnAxis ) );
 	};
 
-	const handleOnFocus = ( event, { side: nextSide } ) => {
+	const handleOnFocus = (
+		_event: React.FocusEvent< HTMLInputElement >,
+		{ side: nextSide }: { side: typeof side }
+	) => {
 		setSide( nextSide );
 	};
 
-	const handleOnChange = ( nextValues ) => {
+	const handleOnChange = ( nextValues: BoxControlValue ) => {
 		onChange( nextValues );
 		setValues( nextValues );
 		setIsDirty( true );
@@ -132,7 +166,7 @@ export default function BoxControl( {
 					<FlexItem>
 						<Button
 							className="component-box-control__reset-button"
-							isSecondary
+							variant="secondary"
 							isSmall
 							onClick={ handleOnReset }
 							disabled={ ! isDirty }
@@ -176,3 +210,4 @@ export default function BoxControl( {
 }
 
 export { applyValueToSides } from './utils';
+export default BoxControl;

package/src/box-control/{input-controls.js → input-controls.tsx}

@@ -5,6 +5,8 @@ import UnitControl from './unit-control';
 import { parseQuantityAndUnitFromRawValue } from '../unit-control/utils';
 import { ALL_SIDES, LABELS } from './utils';
 import { LayoutContainer, Layout } from './styles/box-control-styles';
+import type { BoxControlInputControlProps, BoxControlValue } from './types';
+import type { UnitControlProps } from '../unit-control/types';
 
 const noop = () => {};
 
@@ -18,29 +20,33 @@ export default function BoxInputControls( {
 	setSelectedUnits,
 	sides,
 	...props
-} ) {
-	const createHandleOnFocus = ( side ) => ( event ) => {
-		onFocus( event, { side } );
-	};
+}: BoxControlInputControlProps ) {
+	const createHandleOnFocus =
+		( side: keyof BoxControlValue ) =>
+		( event: React.FocusEvent< HTMLInputElement > ) => {
+			onFocus( event, { side } );
+		};
 
-	const createHandleOnHoverOn = ( side ) => () => {
+	const createHandleOnHoverOn = ( side: keyof BoxControlValue ) => () => {
 		onHoverOn( { [ side ]: true } );
 	};
 
-	const createHandleOnHoverOff = ( side ) => () => {
+	const createHandleOnHoverOff = ( side: keyof BoxControlValue ) => () => {
 		onHoverOff( { [ side ]: false } );
 	};
 
-	const handleOnChange = ( nextValues ) => {
+	const handleOnChange = ( nextValues: BoxControlValue ) => {
 		onChange( nextValues );
 	};
 
-	const createHandleOnChange =
+	const createHandleOnChange: (
+		side: keyof BoxControlValue
+	) => UnitControlProps[ 'onChange' ] =
 		( side ) =>
 		( next, { event } ) => {
-			const { altKey } = event;
 			const nextValues = { ...values };
-			const isNumeric = ! isNaN( parseFloat( next ) );
+			const isNumeric =
+				next !== undefined && ! isNaN( parseFloat( next ) );
 			const nextValue = isNumeric ? next : undefined;
 
 			nextValues[ side ] = nextValue;
@@ -49,7 +55,10 @@ export default function BoxInputControls( {
 			 * Supports changing pair sides. For example, holding the ALT key
 			 * when changing the TOP will also update BOTTOM.
 			 */
-			if ( altKey ) {
+			// @ts-expect-error - TODO: event.altKey is only present when the change event was
+			// triggered by a keyboard event. Should this feature be implemented differently so
+			// it also works with drag events?
+			if ( event.altKey ) {
 				switch ( side ) {
 					case 'top':
 						nextValues.bottom = nextValue;
@@ -69,11 +78,12 @@ export default function BoxInputControls( {
 			handleOnChange( nextValues );
 		};
 
-	const createHandleOnUnitChange = ( side ) => ( next ) => {
-		const newUnits = { ...selectedUnits };
-		newUnits[ side ] = next;
-		setSelectedUnits( newUnits );
-	};
+	const createHandleOnUnitChange =
+		( side: keyof BoxControlValue ) => ( next?: string ) => {
+			const newUnits = { ...selectedUnits };
+			newUnits[ side ] = next;
+			setSelectedUnits( newUnits );
+		};
 
 	// Filter sides if custom configuration provided, maintaining default order.
 	const filteredSides = sides?.length

package/src/box-control/{linked-button.js → linked-button.tsx}

@@ -10,7 +10,10 @@ import { __ } from '@wordpress/i18n';
 import Button from '../button';
 import Tooltip from '../tooltip';
 
-export default function LinkedButton( { isLinked, ...props } ) {
+export default function LinkedButton( {
+	isLinked,
+	...props
+}: { isLinked?: boolean } & React.ComponentProps< typeof Button > ) {
 	const label = isLinked ? __( 'Unlink sides' ) : __( 'Link sides' );
 
 	return (

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

@@ -21,7 +21,7 @@ export const Viewbox = styled.span`
 	height: 100%;
 `;
 
-const strokeFocus = ( { isFocused } ) => {
+const strokeFocus = ( { isFocused }: { isFocused: boolean } ) => {
 	return css( {
 		backgroundColor: 'currentColor',
 		opacity: isFocused ? 1 : 0.3,

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

@@ -9,6 +9,7 @@ import styled from '@emotion/styled';
 import { Flex } from '../../flex';
 import BaseUnitControl from '../../unit-control';
 import { rtl } from '../../utils';
+import type { BoxUnitControlProps } from '../types';
 
 export const Root = styled.div`
 	box-sizing: border-box;
@@ -43,7 +44,11 @@ export const Layout = styled( Flex )`
 	justify-content: flex-start;
 `;
 
-const unitControlBorderRadiusStyles = ( { isFirst, isLast, isOnly } ) => {
+const unitControlBorderRadiusStyles = ( {
+	isFirst,
+	isLast,
+	isOnly,
+}: Pick< BoxUnitControlProps, 'isFirst' | 'isLast' | 'isOnly' > ) => {
 	if ( isFirst ) {
 		return rtl( { borderTopRightRadius: 0, borderBottomRightRadius: 0 } )();
 	}
@@ -59,7 +64,10 @@ const unitControlBorderRadiusStyles = ( { isFirst, isLast, isOnly } ) => {
 	} );
 };
 
-const unitControlMarginStyles = ( { isFirst, isOnly } ) => {
+const unitControlMarginStyles = ( {
+	isFirst,
+	isOnly,
+}: Pick< BoxUnitControlProps, 'isFirst' | 'isOnly' > ) => {
 	const marginLeft = isFirst || isOnly ? 0 : -1;
 
 	return rtl( { marginLeft } )();

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

@@ -9,7 +9,11 @@ import styled from '@emotion/styled';
  */
 import { COLORS, rtl } from '../../utils';
 
-const containerPositionStyles = ( { isPositionAbsolute } ) => {
+const containerPositionStyles = ( {
+	isPositionAbsolute,
+}: {
+	isPositionAbsolute: boolean;
+} ) => {
 	if ( ! isPositionAbsolute ) return '';
 
 	return css`
@@ -39,7 +43,7 @@ export const Side = styled.div`
 	transition: opacity 120ms linear;
 	z-index: 1;
 
-	${ ( { isActive } ) =>
+	${ ( { isActive }: { isActive: boolean } ) =>
 		isActive &&
 		`
 		opacity: 0.3;

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

@@ -12,10 +12,11 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import BoxControl from '../';
+import BoxControl from '..';
+import type { BoxControlProps, BoxControlValue } from '../types';
 
-const Example = ( extraProps ) => {
-	const [ state, setState ] = useState();
+const Example = ( extraProps: Omit< BoxControlProps, 'onChange' > ) => {
+	const [ state, setState ] = useState< BoxControlValue >();
 
 	return (
 		<BoxControl
@@ -29,7 +30,7 @@ const Example = ( extraProps ) => {
 describe( 'BoxControl', () => {
 	describe( 'Basic rendering', () => {
 		it( 'should render a box control input', () => {
-			render( <BoxControl /> );
+			render( <BoxControl onChange={ () => {} } /> );
 
 			expect(
 				screen.getByRole( 'textbox', { name: 'Box Control' } )
@@ -39,7 +40,7 @@ describe( 'BoxControl', () => {
 		it( 'should update values when interacting with input', async () => {
 			const user = userEvent.setup();
 
-			render( <BoxControl /> );
+			render( <BoxControl onChange={ () => {} } /> );
 
 			const input = screen.getByRole( 'textbox', {
 				name: 'Box Control',
@@ -61,7 +62,7 @@ describe( 'BoxControl', () => {
 		it( 'should reset values when clicking Reset', async () => {
 			const user = userEvent.setup();
 
-			render( <BoxControl /> );
+			render( <BoxControl onChange={ () => {} } /> );
 
 			const input = screen.getByRole( 'textbox', {
 				name: 'Box Control',
@@ -238,7 +239,7 @@ describe( 'BoxControl', () => {
 			const user = userEvent.setup();
 
 			// Render control.
-			render( <BoxControl /> );
+			render( <BoxControl onChange={ () => {} } /> );
 
 			// Make unit selection on all input control.
 			await user.selectOptions(
@@ -270,7 +271,7 @@ describe( 'BoxControl', () => {
 			const user = userEvent.setup();
 
 			// Render control.
-			const { rerender } = render( <BoxControl /> );
+			const { rerender } = render( <BoxControl onChange={ () => {} } /> );
 
 			// Make unit selection on all input control.
 			await user.selectOptions(
@@ -298,7 +299,9 @@ describe( 'BoxControl', () => {
 			} );
 
 			// Rerender with individual side value & confirm unit is selected.
-			rerender( <BoxControl values={ { top: '2.5em' } } /> );
+			rerender(
+				<BoxControl values={ { top: '2.5em' } } onChange={ () => {} } />
+			);
 
 			const rerenderedControls = screen.getAllByRole( 'combobox', {
 				name: 'Select unit',