@wordpress/components 23.3.5 → 23.5.0

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/circular-option-picker/README.md

@@ -0,0 +1,141 @@
+# `CircularOptionPicker`
+
+<div class="callout callout-alert">
+This component is not exported, and therefore can only be used internally to the `@wordpress/components` package.
+</div>
+
+`CircularOptionPicker` is a component that displays a set of options as circular buttons.
+
+## Usage
+
+```jsx
+import { CircularOptionPicker } from '../circular-option-picker';
+import { useState } from '@wordpress/element';
+
+const Example = () => {
+	const [ currentColor, setCurrentColor ] = useState();
+	const colors = [
+		{ color: '#f00', name: 'Red' },
+		{ color: '#0f0', name: 'Green' },
+		{ color: '#00f', name: 'Blue' },
+	];
+	const colorOptions = (
+		<>
+			{ colors.map( ( { color, name }, index ) => {
+				return (
+					<CircularOptionPicker.Option
+						key={ `${ color }-${ index }` }
+						tooltipText={ name }
+						style={ { backgroundColor: color, color } }
+						isSelected={ index === currentColor }
+						onClick={ () => setCurrentColor( index ) }
+						aria-label={ name }
+					/>
+				);
+			} ) }
+		</>
+	);
+	return (
+		<CircularOptionPicker
+				options={ colorOptions }
+				actions={
+					<CircularOptionPicker.ButtonAction
+						onClick={ () => setCurrentColor( undefined ) }
+					>
+						{ 'Clear' }
+					</CircularOptionPicker.ButtonAction>
+				}
+			/>
+	);
+};
+```
+
+## Props
+
+### `className`: `string`
+
+A CSS class to apply to the wrapper element.
+
+- Required: No
+
+### `actions`: `ReactNode`
+
+The action(s) to be rendered after the options, such as a 'clear' button as seen in `ColorPalette`.
+
+Usually a `CircularOptionPicker.ButtonAction` or `CircularOptionPicker.DropdownLinkAction` component.
+
+- Required: No
+
+### `options`: `ReactNode`
+
+The options to be rendered, such as color swatches.
+
+Usually a `CircularOptionPicker.Option` component.
+
+- Required: No
+
+### `children`: `ReactNode`
+
+The child elements.
+
+- Required: No
+
+## Subcomponents
+
+### `CircularOptionPicker.ButtonAction`
+
+A `ButtonAction` is an action that is rendered as a button alongside the options themselves.
+
+A common use case is a 'clear' button to deselect the currently selected option.
+
+#### Props
+
+##### `className`: `string`
+
+A CSS class to apply to the underlying `Button` component.
+
+- Required: No
+
+##### `children`: `ReactNode`
+
+The button's children.
+
+- Required: No
+
+##### Inherited props
+
+`CircularOptionPicker.ButtonAction` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.
+
+### `CircularOptionPicker.DropdownLinkAction`
+
+`CircularOptionPicker.DropdownLinkAction` is an action that's hidden behind a dropdown toggle. The button is formatted as a link and rendered as an `anchor` element.
+
+#### Props
+
+##### `className`: `string`
+
+A CSS class to apply to the underlying `Dropdown` component.
+
+- Required: No
+
+##### `linkText`: `string`
+
+The text to be displayed on the button.
+
+- Required: Yes
+
+##### `dropdownProps`: `object`
+
+The props for the underlying `Dropdown` component.
+
+Inherits all of the [`Dropdown` props](/packages/components/src/dropdown/README.md#props), except for `className` and `renderToggle`.
+
+- Required: Yes
+
+##### `buttonProps`: `object`
+
+Props for the underlying `Button` component.
+
+Inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href`, `target`, and `children`. 
+
+- Required: No

package/src/circular-option-picker/{index.js → index.tsx}

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /**
  * External dependencies
  */
@@ -15,15 +14,21 @@ import { Icon, check } from '@wordpress/icons';
 import Button from '../button';
 import Dropdown from '../dropdown';
 import Tooltip from '../tooltip';
+import type {
+	CircularOptionPickerProps,
+	DropdownLinkActionProps,
+	OptionProps,
+} from './types';
+import type { WordPressComponentProps } from '../ui/context';
+import type { ButtonAsButtonProps } from '../button/types';
 
-function Option( props ) {
-	const {
-		className,
-		isSelected,
-		selectedIconProps,
-		tooltipText,
-		...additionalProps
-	} = props;
+export function Option( {
+	className,
+	isSelected,
+	selectedIconProps,
+	tooltipText,
+	...additionalProps
+}: OptionProps ) {
 	const optionButton = (
 		<Button
 			isPressed={ isSelected }
@@ -53,8 +58,12 @@ function Option( props ) {
 	);
 }
 
-function DropdownLinkAction( props ) {
-	const { buttonProps, className, dropdownProps, linkText } = props;
+export function DropdownLinkAction( {
+	buttonProps,
+	className,
+	dropdownProps,
+	linkText,
+}: DropdownLinkActionProps ) {
 	return (
 		<Dropdown
 			className={ classnames(
@@ -77,8 +86,11 @@ function DropdownLinkAction( props ) {
 	);
 }
 
-function ButtonAction( props ) {
-	const { className, children, ...additionalProps } = props;
+export function ButtonAction( {
+	className,
+	children,
+	...additionalProps
+}: WordPressComponentProps< ButtonAsButtonProps, 'button', false > ) {
 	return (
 		<Button
 			className={ classnames(
@@ -93,7 +105,53 @@ function ButtonAction( props ) {
 	);
 }
 
-export default function CircularOptionPicker( props ) {
+/**
+ *`CircularOptionPicker` is a component that displays a set of options as circular buttons.
+ *
+ * ```jsx
+ * import { CircularOptionPicker } from '../circular-option-picker';
+ * import { useState } from '@wordpress/element';
+ *
+ * const Example = () => {
+ * 	const [ currentColor, setCurrentColor ] = useState();
+ * 	const colors = [
+ * 		{ color: '#f00', name: 'Red' },
+ * 		{ color: '#0f0', name: 'Green' },
+ * 		{ color: '#00f', name: 'Blue' },
+ * 	];
+ * 	const colorOptions = (
+ * 		<>
+ * 			{ colors.map( ( { color, name }, index ) => {
+ * 				return (
+ * 					<CircularOptionPicker.Option
+ * 						key={ `${ color }-${ index }` }
+ * 						tooltipText={ name }
+ * 						style={ { backgroundColor: color, color } }
+ * 						isSelected={ index === currentColor }
+ * 						onClick={ () => setCurrentColor( index ) }
+ * 						aria-label={ name }
+ * 					/>
+ * 				);
+ * 			} ) }
+ * 		</>
+ * 	);
+ * 	return (
+ * 		<CircularOptionPicker
+ * 				options={ colorOptions }
+ * 				actions={
+ * 					<CircularOptionPicker.ButtonAction
+ * 						onClick={ () => setCurrentColor( undefined ) }
+ * 					>
+ * 						{ 'Clear' }
+ * 					</CircularOptionPicker.ButtonAction>
+ * 				}
+ * 			/>
+ * 	);
+ * };
+ * ```
+ */
+
+function CircularOptionPicker( props: CircularOptionPickerProps ) {
 	const { actions, className, options, children } = props;
 	return (
 		<div
@@ -118,3 +176,5 @@ export default function CircularOptionPicker( props ) {
 CircularOptionPicker.Option = Option;
 CircularOptionPicker.ButtonAction = ButtonAction;
 CircularOptionPicker.DropdownLinkAction = DropdownLinkAction;
+
+export default CircularOptionPicker;