@wordpress/components 23.3.2 → 23.4.0

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;
 
 	/**

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

@@ -7,6 +7,7 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import { parseQuantityAndUnitFromRawValue } from '../unit-control/utils';
+import type { BoxControlProps, BoxControlValue } from './types';
 
 export const LABELS = {
 	all: __( 'All' ),
@@ -26,16 +27,16 @@ export const DEFAULT_VALUES = {
 	left: undefined,
 };
 
-export const ALL_SIDES = [ 'top', 'right', 'bottom', 'left' ];
+export const ALL_SIDES = [ 'top', 'right', 'bottom', 'left' ] as const;
 
 /**
  * Gets an items with the most occurrence within an array
  * https://stackoverflow.com/a/20762713
  *
- * @param {Array<any>} arr Array of items to check.
- * @return {any} The item with the most occurrences.
+ * @param arr Array of items to check.
+ * @return The item with the most occurrences.
  */
-function mode( arr ) {
+function mode< T >( arr: T[] ) {
 	return arr
 		.sort(
 			( a, b ) =>
@@ -48,16 +49,16 @@ function mode( arr ) {
 /**
  * Gets the 'all' input value and unit from values data.
  *
- * @param {Object} values         Box values.
- * @param {Object} selectedUnits  Box units.
- * @param {Array}  availableSides Available box sides to evaluate.
+ * @param values         Box values.
+ * @param selectedUnits  Box units.
+ * @param availableSides Available box sides to evaluate.
  *
- * @return {string} A value + unit for the 'all' input.
+ * @return A value + unit for the 'all' input.
  */
 export function getAllValue(
-	values = {},
-	selectedUnits,
-	availableSides = ALL_SIDES
+	values: BoxControlValue = {},
+	selectedUnits?: BoxControlValue,
+	availableSides: BoxControlProps[ 'sides' ] = ALL_SIDES
 ) {
 	const sides = normalizeSides( availableSides );
 	const parsedQuantitiesAndUnits = sides.map( ( side ) =>
@@ -101,10 +102,10 @@ export function getAllValue(
 /**
  * Determine the most common unit selection to use as a fallback option.
  *
- * @param {Object} selectedUnits Current unit selections for individual sides.
- * @return {string} Most common unit selection.
+ * @param selectedUnits Current unit selections for individual sides.
+ * @return  Most common unit selection.
  */
-export function getAllUnitFallback( selectedUnits ) {
+export function getAllUnitFallback( selectedUnits?: BoxControlValue ) {
 	if ( ! selectedUnits || typeof selectedUnits !== 'object' ) {
 		return undefined;
 	}
@@ -117,13 +118,17 @@ export function getAllUnitFallback( selectedUnits ) {
 /**
  * Checks to determine if values are mixed.
  *
- * @param {Object} values        Box values.
- * @param {Object} selectedUnits Box units.
- * @param {Array}  sides         Available box sides to evaluate.
+ * @param values        Box values.
+ * @param selectedUnits Box units.
+ * @param sides         Available box sides to evaluate.
  *
- * @return {boolean} Whether values are mixed.
+ * @return Whether values are mixed.
  */
-export function isValuesMixed( values = {}, selectedUnits, sides = ALL_SIDES ) {
+export function isValuesMixed(
+	values: BoxControlValue = {},
+	selectedUnits?: BoxControlValue,
+	sides: BoxControlProps[ 'sides' ] = ALL_SIDES
+) {
 	const allValue = getAllValue( values, selectedUnits, sides );
 	const isMixed = isNaN( parseFloat( allValue ) );
 
@@ -133,11 +138,11 @@ export function isValuesMixed( values = {}, selectedUnits, sides = ALL_SIDES ) {
 /**
  * Checks to determine if values are defined.
  *
- * @param {Object} values Box values.
+ * @param values Box values.
  *
- * @return {boolean} Whether values are mixed.
+ * @return  Whether values are mixed.
  */
-export function isValuesDefined( values ) {
+export function isValuesDefined( values?: BoxControlValue ) {
 	return (
 		values !== undefined &&
 		Object.values( values ).filter(
@@ -153,12 +158,12 @@ export function isValuesDefined( values ) {
  * Get initial selected side, factoring in whether the sides are linked,
  * and whether the vertical / horizontal directions are grouped via splitOnAxis.
  *
- * @param {boolean} isLinked    Whether the box control's fields are linked.
- * @param {boolean} splitOnAxis Whether splitting by horizontal or vertical axis.
- * @return {string} The initial side.
+ * @param isLinked    Whether the box control's fields are linked.
+ * @param splitOnAxis Whether splitting by horizontal or vertical axis.
+ * @return The initial side.
  */
-export function getInitialSide( isLinked, splitOnAxis ) {
-	let initialSide = 'all';
+export function getInitialSide( isLinked: boolean, splitOnAxis: boolean ) {
+	let initialSide: keyof typeof LABELS = 'all';
 
 	if ( ! isLinked ) {
 		initialSide = splitOnAxis ? 'vertical' : 'top';
@@ -173,20 +178,20 @@ export function getInitialSide( isLinked, splitOnAxis ) {
  * to their appropriate sides to facilitate correctly determining value for
  * all input control.
  *
- * @param {Array} sides Available sides for box control.
- * @return {Array} Normalized sides configuration.
+ * @param sides Available sides for box control.
+ * @return Normalized sides configuration.
  */
-export function normalizeSides( sides ) {
-	const filteredSides = [];
+export function normalizeSides( sides: BoxControlProps[ 'sides' ] ) {
+	const filteredSides: ( keyof BoxControlValue )[] = [];
 
 	if ( ! sides?.length ) {
 		return ALL_SIDES;
 	}
 
 	if ( sides.includes( 'vertical' ) ) {
-		filteredSides.push( ...[ 'top', 'bottom' ] );
+		filteredSides.push( ...( [ 'top', 'bottom' ] as const ) );
 	} else if ( sides.includes( 'horizontal' ) ) {
-		filteredSides.push( ...[ 'left', 'right' ] );
+		filteredSides.push( ...( [ 'left', 'right' ] as const ) );
 	} else {
 		const newSides = ALL_SIDES.filter( ( side ) => sides.includes( side ) );
 		filteredSides.push( ...newSides );
@@ -199,13 +204,17 @@ export function normalizeSides( sides ) {
  * Applies a value to an object representing top, right, bottom and left sides
  * while taking into account any custom side configuration.
  *
- * @param {Object}        currentValues The current values for each side.
- * @param {string|number} newValue      The value to apply to the sides object.
- * @param {string[]}      sides         Array defining valid sides.
+ * @param currentValues The current values for each side.
+ * @param newValue      The value to apply to the sides object.
+ * @param sides         Array defining valid sides.
  *
- * @return {Object} Object containing the updated values for each side.
+ * @return Object containing the updated values for each side.
  */
-export function applyValueToSides( currentValues, newValue, sides ) {
+export function applyValueToSides(
+	currentValues: BoxControlValue,
+	newValue?: string,
+	sides?: BoxControlProps[ 'sides' ]
+): BoxControlValue {
 	const newValues = { ...currentValues };
 
 	if ( sides?.length ) {

package/src/button/test/index.tsx

@@ -1,7 +1,8 @@
 /**
  * External dependencies
  */
-import { act, render, screen } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 
 /**
  * WordPress dependencies
@@ -76,9 +77,14 @@ describe( 'Button', () => {
 			expect( screen.getByRole( 'button' ) ).toHaveClass( 'is-pressed' );
 		} );
 
-		it( 'should render a button element with has-text when children are passed', () => {
+		it( 'should render a button element with has-text when children are passed', async () => {
+			const user = userEvent.setup();
+
 			render( <Button icon={ plusCircle }>Children</Button> );
-			act( () => screen.getByRole( 'button' ).focus() );
+
+			// Move focus to the button
+			await user.tab();
+
 			expect( screen.getByRole( 'button' ) ).toHaveClass( 'has-text' );
 		} );
 
@@ -183,16 +189,14 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should add an aria-label when the label property is used, with Tooltip wrapper', async () => {
+			const user = userEvent.setup();
+
 			render( <Button icon={ plusCircle } label="WordPress" /> );
-			// Wait for the `floating-ui` effects in `Tooltip`/`Popover` to finish running
-			// See also: https://floating-ui.com/docs/react-dom#testing
-			await act( () => Promise.resolve() );
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
-			await act( () => {
-				screen.getByRole( 'button', { name: 'WordPress' } ).focus();
-			} );
+			// Move focus to the button
+			await user.tab();
 
 			expect( screen.getByText( 'WordPress' ) ).toBeVisible();
 		} );
@@ -216,6 +220,8 @@ describe( 'Button', () => {
 		} );
 
 		it( 'should populate tooltip with label content for buttons without visible labels (no children)', async () => {
+			const user = userEvent.setup();
+
 			render(
 				<Button
 					describedBy="Description text"
@@ -223,13 +229,11 @@ describe( 'Button', () => {
 					icon={ plusCircle }
 				/>
 			);
-			await act( () => Promise.resolve() );
 
 			expect( screen.queryByText( 'Label' ) ).not.toBeInTheDocument();
 
-			await act( async () => {
-				screen.getByRole( 'button', { name: 'Label' } ).focus();
-			} );
+			// Move focus to the button
+			await user.tab();
 
 			expect( screen.getByText( 'Label' ) ).toBeVisible();
 		} );
@@ -245,7 +249,6 @@ describe( 'Button', () => {
 					Children
 				</Button>
 			);
-			await act( () => Promise.resolve() );
 
 			expect(
 				screen.getByRole( 'button', {
@@ -254,7 +257,9 @@ describe( 'Button', () => {
 			).toBeVisible();
 		} );
 
-		it( 'should allow tooltip disable', () => {
+		it( 'should allow tooltip disable', async () => {
+			const user = userEvent.setup();
+
 			render(
 				<Button
 					icon={ plusCircle }
@@ -262,33 +267,37 @@ describe( 'Button', () => {
 					showTooltip={ false }
 				/>
 			);
-			const button = screen.getByRole( 'button', { name: 'WordPress' } );
 
-			expect( button ).toHaveAttribute( 'aria-label', 'WordPress' );
+			expect(
+				screen.getByRole( 'button', { name: 'WordPress' } )
+			).toHaveAttribute( 'aria-label', 'WordPress' );
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
-			act( () => button.focus() );
+			// Move focus to the button
+			await user.tab();
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 		} );
 
 		it( 'should show the tooltip for empty children', async () => {
+			const user = userEvent.setup();
+
 			render(
 				<Button icon={ plusCircle } label="WordPress" children={ [] } />
 			);
-			await act( () => Promise.resolve() );
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
-			await act( async () => {
-				screen.getByRole( 'button', { name: 'WordPress' } ).focus();
-			} );
+			// Move focus to the button
+			await user.tab();
 
 			expect( screen.getByText( 'WordPress' ) ).toBeVisible();
 		} );
 
-		it( 'should not show the tooltip when icon and children defined', () => {
+		it( 'should not show the tooltip when icon and children defined', async () => {
+			const user = userEvent.setup();
+
 			render(
 				<Button icon={ plusCircle } label="WordPress">
 					Children
@@ -297,26 +306,25 @@ describe( 'Button', () => {
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
-			act( () => {
-				screen.getByRole( 'button', { name: 'WordPress' } ).focus();
-			} );
+			// Move focus to the button
+			await user.tab();
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 		} );
 
 		it( 'should force showing the tooltip even if icon and children defined', async () => {
+			const user = userEvent.setup();
+
 			render(
 				<Button icon={ plusCircle } label="WordPress" showTooltip>
 					Children
 				</Button>
 			);
-			await act( () => Promise.resolve() );
 
 			expect( screen.queryByText( 'WordPress' ) ).not.toBeInTheDocument();
 
-			await act( async () => {
-				screen.getByRole( 'button', { name: 'WordPress' } ).focus();
-			} );
+			// Move focus to the button
+			await user.tab();
 
 			expect( screen.getByText( 'WordPress' ) ).toBeVisible();
 		} );

package/src/color-palette/README.md

@@ -66,6 +66,13 @@ colors.
 -   Required: No
 -   Default: `false`
 
+### `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
+
+The heading level.
+
+-   Required: No
+-   Default: `2`
+
 ### `value`: `string`
 
 Currently active value.

package/src/color-palette/index.tsx

@@ -107,6 +107,7 @@ function MultiplePalettes( {
 	onChange,
 	value,
 	actions,
+	headingLevel,
 }: MultiplePalettesProps ) {
 	if ( colors.length === 0 ) {
 		return null;
@@ -117,7 +118,9 @@ function MultiplePalettes( {
 			{ colors.map( ( { name, colors: colorPalette }, index ) => {
 				return (
 					<VStack spacing={ 2 } key={ index }>
-						<ColorHeading>{ name }</ColorHeading>
+						<ColorHeading level={ headingLevel }>
+							{ name }
+						</ColorHeading>
 						<SinglePalette
 							clearColor={ clearColor }
 							colors={ colorPalette }
@@ -182,6 +185,7 @@ function UnforwardedColorPalette(
 		onChange,
 		value,
 		__experimentalIsRenderedInSidebar = false,
+		headingLevel = 2,
 		...otherProps
 	} = props;
 	const [ normalizedColorValue, setNormalizedColorValue ] = useState( value );
@@ -243,6 +247,7 @@ function UnforwardedColorPalette(
 				{ __( 'Clear' ) }
 			</CircularOptionPicker.ButtonAction>
 		),
+		headingLevel,
 	};
 
 	return (

package/src/color-palette/types.ts

@@ -7,6 +7,7 @@ import type { CSSProperties, ReactNode } from 'react';
  * Internal dependencies
  */
 import type { DropdownProps } from '../dropdown/types';
+import type { HeadingSize } from '../heading/types';
 
 export type ColorObject = {
 	name: string;
@@ -27,6 +28,7 @@ type PaletteProps = {
 	onChange: ( newColor?: string, index?: number ) => void;
 	value?: string;
 	actions?: ReactNode;
+	headingLevel?: HeadingSize;
 };
 
 export type SinglePaletteProps = PaletteProps & {
@@ -70,6 +72,12 @@ export type ColorPaletteProps = Pick< PaletteProps, 'onChange' > & {
 	 * @default false
 	 */
 	enableAlpha?: boolean;
+	/**
+	 * The heading level.
+	 *
+	 * @default 2
+	 */
+	headingLevel?: HeadingSize;
 	/**
 	 * Currently active value.
 	 */

package/src/combobox-control/README.md

@@ -17,9 +17,6 @@ These are the same as [the ones for `SelectControl`s](/packages/components/src/s
 ### Usage
 
 ```jsx
-/**
- * WordPress dependencies
- */
 import { ComboboxControl } from '@wordpress/components';
 import { useState } from '@wordpress/element';
 
@@ -36,10 +33,6 @@ const options = [
 		value: 'large',
 		label: 'Large',
 	},
-	{
-		value: 'huge',
-		label: 'Huge',
-	},
 ];
 
 function MyComboboxControl() {
@@ -92,35 +85,35 @@ If this property is added, a help text will be generated using help property as
 
 The options that can be chosen from.
 
--   Type: `Array<{ value: String, label: String }>`
+-   Type: `Array<{ value: string, label: string }>`
 -   Required: Yes
 
 #### onFilterValueChange
 
-Function called with the control's search input value changes. The argument contains the next input value.
+Function called when the control's search input value changes. The argument contains the next input value.
 
--   Type: `Function`
+-   Type: `( value: string ) => void`
 -   Required: No
 
 #### onChange
 
 Function called with the selected value changes.
 
--   Type: `Function`
+-   Type: `( value: string | null | undefined ) => void`
 -   Required: No
 
 #### value
 
-The current value of the input.
+The current value of the control.
 
--   Type: `mixed`
--   Required: Yes
+-   Type: `string | null`
+-   Required: No
 
 #### __experimentalRenderItem
 
 Custom renderer invoked for each option in the suggestion list. The render prop receives as its argument an object containing, under the `item` key, the single option's data (directly from the array of data passed to the `options` prop).
 
--   Type: `Function` - `( args: { item: object } ) => ReactNode`
+-   Type: `( args: { item: object } ) => ReactNode`
 -   Required: No
 
 ## Related components