@wordpress/components 23.3.1 → 23.4.0

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',

package/src/box-control/types.ts

@@ -0,0 +1,121 @@
+/**
+ * External dependencies
+ */
+import type { useHover } from '@use-gesture/react';
+
+/**
+ * Internal dependencies
+ */
+import type { UnitControlProps } from '../unit-control/types';
+import type { LABELS } from './utils';
+
+export type BoxControlValue = {
+	top?: string;
+	right?: string;
+	bottom?: string;
+	left?: string;
+};
+
+type UnitControlPassthroughProps = Omit<
+	UnitControlProps,
+	'label' | 'onChange' | 'onFocus' | 'onMouseOver' | 'onMouseOut' | 'units'
+>;
+
+export type BoxControlProps = Pick<
+	UnitControlProps,
+	'onMouseOver' | 'onMouseOut' | 'units'
+> & {
+	/**
+	 * If this property is true, a button to reset the box control is rendered.
+	 *
+	 * @default true
+	 */
+	allowReset?: boolean;
+	/**
+	 * The id to use as a base for the unique HTML id attribute of the control.
+	 */
+	id?: string;
+	/**
+	 * Props for the internal `UnitControl` components.
+	 *
+	 * @default `{ min: 0 }`
+	 */
+	inputProps?: UnitControlPassthroughProps;
+	/**
+	 * Heading label for the control.
+	 *
+	 * @default `__( 'Box Control' )`
+	 */
+	label?: string;
+	/**
+	 * A callback function when an input value changes.
+	 */
+	onChange: ( next: BoxControlValue ) => void;
+	/**
+	 * The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset.
+	 *
+	 * @default `{ top: undefined, right: undefined, bottom: undefined, left: undefined }`
+	 */
+	resetValues?: BoxControlValue;
+	/**
+	 * Collection of sides to allow control of. If omitted or empty, all sides will be available.
+	 */
+	sides?: readonly ( keyof BoxControlValue | 'horizontal' | 'vertical' )[];
+	/**
+	 * If this property is true, when the box control is unlinked, vertical and horizontal controls
+	 * can be used instead of updating individual sides.
+	 *
+	 * @default false
+	 */
+	splitOnAxis?: boolean;
+	/**
+	 * The current values of the control, expressed as an object of `top`, `right`, `bottom`, and `left` values.
+	 */
+	values?: BoxControlValue;
+};
+
+export type BoxControlInputControlProps = UnitControlPassthroughProps & {
+	onChange?: ( nextValues: BoxControlValue ) => void;
+	onFocus?: (
+		_event: React.FocusEvent< HTMLInputElement >,
+		{ side }: { side: keyof typeof LABELS }
+	) => void;
+	onHoverOff?: (
+		sides: Partial< Record< keyof BoxControlValue, boolean > >
+	) => void;
+	onHoverOn?: (
+		sides: Partial< Record< keyof BoxControlValue, boolean > >
+	) => void;
+	selectedUnits: BoxControlValue;
+	setSelectedUnits: React.Dispatch< React.SetStateAction< BoxControlValue > >;
+	sides: BoxControlProps[ 'sides' ];
+	values: BoxControlValue;
+};
+
+export type BoxUnitControlProps = UnitControlPassthroughProps &
+	Pick< UnitControlProps, 'onChange' | 'onFocus' > & {
+		isFirst?: boolean;
+		isLast?: boolean;
+		isOnly?: boolean;
+		label?: string;
+		onHoverOff?: (
+			event: ReturnType< typeof useHover >[ 'event' ],
+			state: Omit< ReturnType< typeof useHover >, 'event' >
+		) => void;
+		onHoverOn?: (
+			event: ReturnType< typeof useHover >[ 'event' ],
+			state: Omit< ReturnType< typeof useHover >, 'event' >
+		) => void;
+	};
+
+export type BoxControlIconProps = {
+	/**
+	 * @default 24
+	 */
+	size?: number;
+	/**
+	 * @default 'all'
+	 */
+	side?: keyof typeof LABELS;
+	sides?: BoxControlProps[ 'sides' ];
+};

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

@@ -8,6 +8,7 @@ import { useHover } from '@use-gesture/react';
  */
 import BaseTooltip from '../tooltip';
 import { UnitControlWrapper, UnitControl } from './styles/box-control-styles';
+import type { BoxUnitControlProps } from './types';
 
 const noop = () => {};
 
@@ -20,7 +21,7 @@ export default function BoxUnitControl( {
 	label,
 	value,
 	...props
-} ) {
+}: BoxUnitControlProps ) {
 	const bindHoverGesture = useHover( ( { event, ...state } ) => {
 		if ( state.hovering ) {
 			onHoverOn( event, state );
@@ -48,7 +49,13 @@ export default function BoxUnitControl( {
 	);
 }
 
-function Tooltip( { children, text } ) {
+function Tooltip( {
+	children,
+	text,
+}: {
+	children: JSX.Element;
+	text?: string;
+} ) {
 	if ( ! text ) return children;
 
 	/**