@wordpress/components 23.4.0 → 23.6.0

package/src/dimension-control/README.md

@@ -8,77 +8,46 @@ This feature is still experimental. “Experimental” means this is an early im
 
 ## Usage
 
-In a block's `edit` implementation, render a `<DimensionControl />` component.
-
 ```jsx
-import { registerBlockType } from '@wordpress/blocks';
-import { __ } from '@wordpress/i18n';
-import { DimensionControl } from '@wordpress/components';
-
-const partialRight =
-	( fn, ...partialArgs ) =>
-	( ...args ) =>
-		fn( ...args, ...partialArgs );
-
-registerBlockType( 'my-plugin/my-block', {
-	// ...
-
-	attributes: {
-		// other attributes here
-		// ...
-
-		paddingSize: {
-			type: 'string',
-		},
-	},
-
-	edit( { attributes, setAttributes, clientId } ) {
-		const { paddingSize } = attributes;
-
-		const updateSpacing = ( dimension, size, device = '' ) => {
-			setAttributes( {
-				[ `${ dimension }${ device }` ]: size,
-			} );
-		};
-
-		return (
-			<DimensionControl
-				label={ __( 'Padding' ) }
-				icon={ 'desktop' }
-				onChange={ partialRight( updateSpacing, 'paddingSize' ) }
-				value={ paddingSize }
-			/>
-		);
-	},
-} );
+import { useState } from 'react';
+import { __experimentalDimensionControl as DimensionControl } from '@wordpress/components';
+
+export default function MyCustomDimensionControl() {
+	const [ paddingSize, setPaddingSize ] = useState( '' );
+
+	return (
+		<DimensionControl
+			label={ 'Padding' }
+			icon={ 'desktop' }
+			onChange={ ( value ) => setPaddingSize( value ) }
+			value={ paddingSize }
+		/>
+	);
+}
 ```
 
-_Note:_ it is recommended to partially apply the value of the Block attribute to be updated (eg: `paddingSize`, `marginSize`...etc) to your callback functions. This avoids the need to unnecessarily couple the component to the Block attribute schema.
-
 _Note:_ by default, if you do not provide an initial `value` prop for the current dimension value, then no value will be selected (ie: there is no default dimension set).
 
 ## Props
 
 ### `label`
 
--   **Type:** `String`
--   **Default:** `undefined`
+-   **Type:** `string`
 -   **Required:** Yes
 
 The human readable label for the control.
 
 ### `value`
 
--   **Type:** `String`
--   **Default:** `''`
+-   **Type:** `string`
 -   **Required:** No
 
 The current value of the dimension UI control. If provided the UI with automatically select the value.
 
 ### `sizes`
 
--   **Type:** `Array`
--   **Default:** See `packages/block-editor/src/components/dimension-control/sizes.js`
+-   **Type:** `{ name: string; slug: string }[]`
+-   **Default:** See `packages/block-editor/src/components/dimension-control/sizes.ts`
 -   **Required:** No
 
 An optional array of size objects in the following shape:
@@ -101,16 +70,14 @@ By default a set of relative sizes (`small`, `medium`...etc) are provided. See `
 
 ### `icon`
 
--   **Type:** `String`
--   **Default:** `undefined`
+-   **Type:** `string`
 -   **Required:** No
 
 An optional dashicon to display before to the control label.
 
 ### `onChange`
 
--   **Type:** `Function`
--   **Default:** `undefined`
+-   **Type:** `( value?: string ) => void;`
 -   **Required:** No
 -   **Arguments:**:
     -   `size` - a string representing the selected size (eg: `medium`)
@@ -119,7 +86,7 @@ A callback which is triggered when a spacing size value changes (is selected/cli
 
 ### `className`
 
--   **Type:** `String`
+-   **Type:** `string`
 -   **Default:** `''`
 -   **Required:** No
 

package/src/dimension-control/index.tsx

@@ -0,0 +1,101 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import Icon from '../icon';
+import SelectControl from '../select-control';
+import sizesTable, { findSizeBySlug } from './sizes';
+import type { DimensionControlProps, Size } from './types';
+import type { SelectControlSingleSelectionProps } from '../select-control/types';
+
+/**
+ * `DimensionControl` is a component designed to provide a UI to control spacing and/or dimensions.
+ *
+ * This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+ *
+ * ```jsx
+ * import { useState } from 'react';
+ * import { __experimentalDimensionControl as DimensionControl } from '@wordpress/components';
+ *
+ * export default function MyCustomDimensionControl() {
+ * 	const [ paddingSize, setPaddingSize ] = useState( '' );
+ *
+ * 	return (
+ * 		<DimensionControl
+ * 			label={ 'Padding' }
+ * 			icon={ 'desktop' }
+ * 			onChange={ ( value ) => setPaddingSize( value ) }
+ * 			value={ paddingSize }
+ * 		/>
+ * 	);
+ * }
+ * ```
+ */
+export function DimensionControl( props: DimensionControlProps ) {
+	const {
+		label,
+		value,
+		sizes = sizesTable,
+		icon,
+		onChange,
+		className = '',
+	} = props;
+
+	const onChangeSpacingSize: SelectControlSingleSelectionProps[ 'onChange' ] =
+		( val ) => {
+			const theSize = findSizeBySlug( sizes, val );
+
+			if ( ! theSize || value === theSize.slug ) {
+				onChange?.( undefined );
+			} else if ( typeof onChange === 'function' ) {
+				onChange( theSize.slug );
+			}
+		};
+
+	const formatSizesAsOptions = ( theSizes: Size[] ) => {
+		const options = theSizes.map( ( { name, slug } ) => ( {
+			label: name,
+			value: slug,
+		} ) );
+
+		return [
+			{
+				label: __( 'Default' ),
+				value: '',
+			},
+			...options,
+		];
+	};
+
+	const selectLabel = (
+		<>
+			{ icon && <Icon icon={ icon } /> }
+			{ label }
+		</>
+	);
+
+	return (
+		<SelectControl
+			className={ classnames(
+				className,
+				'block-editor-dimension-control'
+			) }
+			label={ selectLabel }
+			hideLabelFromVision={ false }
+			value={ value }
+			onChange={ onChangeSpacingSize }
+			options={ formatSizesAsOptions( sizes ) }
+		/>
+	);
+}
+
+export default DimensionControl;

package/src/dimension-control/{sizes.js → sizes.ts}

@@ -12,16 +12,19 @@
  */
 import { _x } from '@wordpress/i18n';
 
+/**
+ * Internal dependencies
+ */
+import type { Size } from './types';
+
 /**
  * Finds the correct size object from the provided sizes
  * table by size slug (eg: `medium`)
  *
- * @param {Array}  sizes containing objects for each size definition.
- * @param {string} slug  a string representation of the size (eg: `medium`).
- *
- * @return {Object} the matching size definition.
+ * @param sizes containing objects for each size definition.
+ * @param slug  a string representation of the size (eg: `medium`).
  */
-export const findSizeBySlug = ( sizes, slug ) =>
+export const findSizeBySlug = ( sizes: Size[], slug: string ) =>
 	sizes.find( ( size ) => slug === size.slug );
 
 export default [

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

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+/**
+ * Internal dependencies
+ */
+import { DimensionControl } from '..';
+import sizes from '../sizes';
+
+/**
+ * WordPress dependencies
+ */
+import { desktop, tablet, mobile } from '@wordpress/icons';
+
+export default {
+	component: DimensionControl,
+	title: 'Components (Experimental)/DimensionControl',
+	argTypes: {
+		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
+		icon: {
+			control: { type: 'select' },
+			options: [ '-', 'desktop', 'tablet', 'mobile' ],
+			mapping: {
+				'-': undefined,
+				desktop,
+				tablet,
+				mobile,
+			},
+		},
+		parameters: {
+			controls: { expanded: true },
+			docs: { source: { state: 'open' } },
+		},
+	},
+} as ComponentMeta< typeof DimensionControl >;
+
+const Template: ComponentStory< typeof DimensionControl > = ( args ) => (
+	<DimensionControl { ...args } />
+);
+
+export const Default = Template.bind( {} );
+
+Default.args = {
+	label: 'Please select a size',
+	sizes,
+};

package/src/dimension-control/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Internal dependencies
+ */
+import type { IconType } from '../icon';
+
+export type Size = {
+	/**
+	 * Human-readable name of the size.
+	 */
+	name: string;
+	/**
+	 * Short unique identifying name of the size.
+	 */
+	slug: string;
+};
+
+export type DimensionControlProps = {
+	/**
+	 * Label for the control.
+	 */
+	label: string;
+	/**
+	 * An array of sizes to choose from.
+	 *
+	 * @default DEFAULT_SIZES
+	 *
+	 * @see packages/components/src/dimension-control/sizes.ts
+	 */
+	sizes?: Size[];
+	/**
+	 * Optional icon rendered in front on the label.
+	 */
+	icon?: IconType;
+	/**
+	 * Used to externally control the current value of the control.
+	 */
+	value?: string;
+	/**
+	 * Function called with the control's internal state changes. The `value` property is equal to a given size slug.
+	 */
+	onChange?: ( value?: string ) => void;
+	/**
+	 * CSS class applied to `SelectControl`.
+	 *
+	 * @default ''
+	 */
+	className?: string;
+};

package/src/dropdown-menu/index.js

@@ -91,6 +91,9 @@ function DropdownMenu( dropdownMenuProps ) {
 						onToggle();
 					}
 				};
+				const { as: Toggle = Button, ...restToggleProps } =
+					toggleProps ?? {};
+
 				const mergedToggleProps = mergeProps(
 					{
 						className: classnames(
@@ -100,11 +103,11 @@ function DropdownMenu( dropdownMenuProps ) {
 							}
 						),
 					},
-					toggleProps
+					restToggleProps
 				);
 
 				return (
-					<Button
+					<Toggle
 						{ ...mergedToggleProps }
 						icon={ icon }
 						onClick={ ( event ) => {
@@ -126,7 +129,7 @@ function DropdownMenu( dropdownMenuProps ) {
 						showTooltip={ toggleProps?.showTooltip ?? true }
 					>
 						{ mergedToggleProps.children }
-					</Button>
+					</Toggle>
 				);
 			} }
 			renderContent={ ( props ) => {

package/src/flex/flex/hook.ts

@@ -40,7 +40,7 @@ function useDeprecatedProps(
 
 export function useFlex( props: WordPressComponentProps< FlexProps, 'div' > ) {
 	const {
-		align = 'center',
+		align,
 		className,
 		direction: directionProp = 'row',
 		expanded = true,
@@ -62,7 +62,7 @@ export function useFlex( props: WordPressComponentProps< FlexProps, 'div' > ) {
 
 	const classes = useMemo( () => {
 		const base = css( {
-			alignItems: isColumn ? 'normal' : align,
+			alignItems: align ?? ( isColumn ? 'normal' : 'center' ),
 			flexDirection: direction,
 			flexWrap: wrap ? 'wrap' : undefined,
 			gap: space( gap ),

package/src/font-size-picker/README.md

@@ -49,22 +49,20 @@ const MyFontSizePicker = () => {
 
 The component accepts the following props:
 
-### disableCustomFontSizes
+### `disableCustomFontSizes`: `boolean`
 
 If `true`, it will not be possible to choose a custom fontSize. The user will be forced to pick one of the pre-defined sizes passed in fontSizes.
 
--   Type: `Boolean`
 -   Required: no
 -   Default: `false`
 
-### fallbackFontSize
+### `fallbackFontSize`: `number`
 
 If no value exists, this prop defines the starting position for the font size picker slider. Only relevant if `withSlider` is `true`.
 
--   Type: `Number`
 -   Required: No
 
-### fontSizes
+### `fontSizes`: `FontSize[]`
 
 An array of font size objects. The object should contain properties size, name, and slug.
 The property `size` contains a number with the font size value, in `px` or a string specifying the font size CSS property that should be used eg: "13px", "1em", or "clamp(12px, 5vw, 100px)".
@@ -73,44 +71,52 @@ The `slug` property is a string with a unique identifier for the font size. Used
 
 **Note:** The slugs `default` and `custom` are reserved and cannot be used.
 
--   Type: `Array`
 -   Required: No
+-   Default: `[]`
 
-### onChange
+### `onChange`: `( value: number | string | undefined, selectedItem?: FontSize ) => void`
 
 A function that receives the new font size value.
 If onChange is called without any parameter, it should reset the value, attending to what reset means in that context, e.g., set the font size to undefined or set the font size a starting value.
 
--   Type: `function`
 -   Required: Yes
 
-### value
+### `size`: `'default' | '__unstable-large'`
 
-The current font size value.
+Size of the control.
 
--   Type: `Number | String`
 -   Required: No
+-   Default: `'default'`
 
-### withSlider
+### `units`: `string[]`
 
-If `true`, a slider will be displayed alongside the input field when a custom font size is active. Has no effect when `disableCustomFontSizes` is `true`.
+Available units for custom font size selection.
 
--   Type: `Boolean`
--   Required: no
--   Default: `false`
+-   Required: No
+
+### `value`: `number | string`
+
+The current font size value.
 
-### withReset
+-   Required: No
+
+### `withReset`: `boolean`
 
 If `true`, a reset button will be displayed alongside the input field when a custom font size is active. Has no effect when `disableCustomFontSizes` is `true`.
 
--   Type: `Boolean`
 -   Required: no
 -   Default: `true`
 
-### __nextHasNoMarginBottom
+### `withSlider`: `boolean`
+
+If `true`, a slider will be displayed alongside the input field when a custom font size is active. Has no effect when `disableCustomFontSizes` is `true`.
+
+-   Required: no
+-   Default: `false`
+
+### `__nextHasNoMarginBottom`: `boolean`
 
 Start opting into the new margin-free styles that will become the default in a future version, currently scheduled to be WordPress 6.4. (The prop can be safely removed once this happens.)
 
--   Type: `Boolean`
 -   Required: no
 -   Default: `false`

package/src/font-size-picker/index.tsx

@@ -50,6 +50,7 @@ const UnforwardedFontSizePicker = (
 		disableCustomFontSizes = false,
 		onChange,
 		size = 'default',
+		units: unitsProp,
 		value,
 		withSlider = false,
 		withReset = true,
@@ -64,7 +65,7 @@ const UnforwardedFontSizePicker = (
 	}
 
 	const units = useCustomUnits( {
-		availableUnits: [ 'px', 'em', 'rem' ],
+		availableUnits: unitsProp || [ 'px', 'em', 'rem' ],
 	} );
 
 	const shouldUseSelectControl = fontSizes.length > 5;

package/src/font-size-picker/stories/index.tsx

@@ -85,6 +85,7 @@ Default.args = {
 			size: 26,
 		},
 	],
+	units: [ 'px', 'em', 'rem' ],
 	value: 16,
 	withSlider: false,
 };

package/src/font-size-picker/test/index.tsx

@@ -699,5 +699,28 @@ describe( 'FontSizePicker', () => {
 				screen.queryByRole( 'button', { name: 'Reset' } )
 			).not.toBeInTheDocument();
 		} );
+
+		it( 'applies custom units to custom font size control', async () => {
+			const user = userEvent.setup();
+
+			render(
+				<FontSizePicker
+					__nextHasNoMarginBottom
+					fontSizes={ fontSizes }
+					value={ fontSizes[ 0 ].size }
+					units={ [ 'px', 'ch', 'ex' ] }
+				/>
+			);
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Set custom size' } )
+			);
+
+			const units = screen.getAllByRole( 'option' );
+			expect( units ).toHaveLength( 3 );
+			expect( units[ 0 ] ).toHaveAccessibleName( 'px' );
+			expect( units[ 1 ] ).toHaveAccessibleName( 'ch' );
+			expect( units[ 2 ] ).toHaveAccessibleName( 'ex' );
+		} );
 	}
 } );

package/src/font-size-picker/types.ts

@@ -26,6 +26,10 @@ export type FontSizePickerProps = {
 		value: number | string | undefined,
 		selectedItem?: FontSize
 	) => void;
+	/**
+	 * Available units for custom font size selection.
+	 */
+	units?: string[];
 	/**
 	 * The current font size value.
 	 */

package/src/form-token-field/index.tsx

@@ -153,7 +153,10 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 	}
 
 	function onBlur() {
-		if ( inputHasValidValue() ) {
+		if (
+			inputHasValidValue() &&
+			__experimentalValidateInput( incompleteTokenValue )
+		) {
 			setIsActive( false );
 		} else {
 			// Reset to initial state

package/src/form-token-field/stories/index.tsx

@@ -123,3 +123,16 @@ WithCustomRenderItem.args = {
 		<div>{ `${ item } — a nice place to visit` }</div>
 	),
 };
+
+/**
+ * Only values for which the `__experimentalValidateInput` function returns
+ * `true` will be tokenized. (This is still an experimental feature and is
+ * subject to change.)
+ */
+export const WithValidatedInput: ComponentStory< typeof FormTokenField > =
+	DefaultTemplate.bind( {} );
+WithValidatedInput.args = {
+	...Default.args,
+	__experimentalValidateInput: ( input: string ) =>
+		continents.includes( input ),
+};

package/src/form-token-field/test/index.tsx

@@ -950,6 +950,86 @@ describe( 'FormTokenField', () => {
 			expect( onChangeSpy ).not.toHaveBeenCalled();
 		} );
 
+		it( 'should hide the suggestion list on an empty input', async () => {
+			const user = userEvent.setup();
+
+			const suggestions = [ 'One', 'Two', 'Three' ];
+
+			render( <FormTokenFieldWithState suggestions={ suggestions } /> );
+
+			const input = screen.getByRole( 'combobox' );
+
+			await user.type( input, 'on' );
+
+			expectVisibleSuggestionsToBe( screen.getByRole( 'listbox' ), [
+				'One',
+			] );
+
+			expect( screen.getByRole( 'listbox' ) ).toBeVisible();
+
+			await user.clear( input );
+
+			expect( screen.queryByRole( 'listbox' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'should hide the suggestion list on blur and invalid input', async () => {
+			const user = userEvent.setup();
+
+			const suggestions = [ 'One', 'Two', 'Three' ];
+
+			render(
+				<FormTokenFieldWithState
+					suggestions={ suggestions }
+					__experimentalValidateInput={ ( token ) =>
+						suggestions.includes( token )
+					}
+				/>
+			);
+
+			const input = screen.getByRole( 'combobox' );
+
+			await user.type( input, 'on' );
+
+			expectVisibleSuggestionsToBe( screen.getByRole( 'listbox' ), [
+				'One',
+			] );
+
+			expect( screen.getByRole( 'listbox' ) ).toBeVisible();
+
+			await user.click( document.body );
+
+			expect( screen.queryByRole( 'listbox' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'should not hide the suggestion list on blur and valid input', async () => {
+			const user = userEvent.setup();
+
+			const suggestions = [ 'One', 'Two', 'Three' ];
+
+			render(
+				<FormTokenFieldWithState
+					suggestions={ suggestions }
+					__experimentalValidateInput={ ( token ) =>
+						suggestions.includes( token )
+					}
+				/>
+			);
+
+			const input = screen.getByRole( 'combobox' );
+
+			await user.type( input, 'One' );
+
+			expectVisibleSuggestionsToBe( screen.getByRole( 'listbox' ), [
+				'One',
+			] );
+
+			expect( screen.getByRole( 'listbox' ) ).toBeVisible();
+
+			await user.click( document.body );
+
+			expect( screen.getByRole( 'listbox' ) ).toBeVisible();
+		} );
+
 		it( 'matches the search text with the suggestions in a case-insensitive way', async () => {
 			const user = userEvent.setup();
 

package/src/gradient-picker/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * WordPress dependencies
  */