@wordpress/components 23.5.0 → 23.6.0

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

package/src/guide/README.md

@@ -37,20 +37,6 @@ function MyTutorial() {
 
 The component accepts the following props:
 
-### onFinish
-
-A function which is called when the guide is finished. The guide is finished when the modal is closed or when the user clicks _Finish_ on the last page of the guide.
-
--   Type: `function`
--   Required: Yes
-
-### pages
-
-A list of objects describing each page in the guide. Each object **must** contain a `'content'` property and may optionally contain a `'image'` property.
-
--   Type: `array`
--   Required: Yes
-
 ### className
 
 A custom class to add to the modal.
@@ -62,7 +48,7 @@ A custom class to add to the modal.
 
 This property is used as the modal's accessibility label. It is required for accessibility reasons.
 
--   Type: `String`
+-   Type: `string`
 -   Required: Yes
 
 ### finishButtonText
@@ -71,3 +57,19 @@ Use this to customize the label of the _Finish_ button shown at the end of the g
 
 -   Type: `string`
 -   Required: No
+-	Default: `'Finish'`
+
+### onFinish
+
+A function which is called when the guide is finished. The guide is finished when the modal is closed or when the user clicks _Finish_ on the last page of the guide.
+
+-   Type: `( event?: KeyboardEvent< HTMLDivElement > | SyntheticEvent ) => void`
+-   Required: Yes
+
+### pages
+
+A list of objects describing each page in the guide. Each object **must** contain a `'content'` property and may optionally contain a `'image'` property.
+
+-   Type: `{ content: ReactNode; image?: ReactNode; }[]`
+-   Required: No
+-   Default: `[]`

package/src/guide/{icons.js → icons.tsx}

@@ -3,7 +3,7 @@
  */
 import { SVG, Circle } from '@wordpress/primitives';
 
-export const PageControlIcon = ( { isSelected } ) => (
+export const PageControlIcon = ( { isSelected }: { isSelected: boolean } ) => (
 	<SVG width="8" height="8" fill="none" xmlns="http://www.w3.org/2000/svg">
 		<Circle
 			cx="4"

package/src/guide/{index.js → index.tsx}

@@ -17,16 +17,49 @@ import { focus } from '@wordpress/dom';
 import Modal from '../modal';
 import Button from '../button';
 import PageControl from './page-control';
+import type { GuideProps } from './types';
 
-export default function Guide( {
+/**
+ * `Guide` is a React component that renders a _user guide_ in a modal. The guide consists of several pages which the user can step through one by one. The guide is finished when the modal is closed or when the user clicks _Finish_ on the last page of the guide.
+ *
+ * ```jsx
+ * function MyTutorial() {
+ * 	const [ isOpen, setIsOpen ] = useState( true );
+ *
+ * 	if ( ! isOpen ) {
+ * 		return null;
+ * 	}
+ *
+ * 	return (
+ * 		<Guide
+ * 			onFinish={ () => setIsOpen( false ) }
+ * 			pages={ [
+ * 				{
+ * 					content: <p>Welcome to the ACME Store!</p>,
+ * 				},
+ * 				{
+ * 					image: <img src="https://acmestore.com/add-to-cart.png" />,
+ * 					content: (
+ * 						<p>
+ * 							Click <i>Add to Cart</i> to buy a product.
+ * 						</p>
+ * 					),
+ * 				},
+ * 			] }
+ * 		/>
+ * 	);
+ * }
+ * ```
+ */
+function Guide( {
 	children,
 	className,
 	contentLabel,
-	finishButtonText,
+	finishButtonText = __( 'Finish' ),
 	onFinish,
 	pages = [],
-} ) {
-	const guideContainer = useRef();
+}: GuideProps ) {
+	const guideContainer = useRef< HTMLDivElement >( null );
 	const [ currentPage, setCurrentPage ] = useState( 0 );
 
 	useEffect( () => {
@@ -42,12 +75,17 @@ export default function Guide( {
 		// Each time we change the current page, start from the first element of the page.
 		// This also solves any focus loss that can happen.
 		if ( guideContainer.current ) {
-			focus.tabbable.find( guideContainer.current )?.[ 0 ]?.focus();
+			(
+				focus.tabbable.find( guideContainer.current ) as HTMLElement[]
+			 )[ 0 ]?.focus();
 		}
 	}, [ currentPage ] );
 
 	if ( Children.count( children ) ) {
-		pages = Children.map( children, ( child ) => ( { content: child } ) );
+		pages =
+			Children.map( children, ( child ) => ( {
+				content: child,
+			} ) ) ?? [];
 	}
 
 	const canGoBack = currentPage > 0;
@@ -124,7 +162,7 @@ export default function Guide( {
 							className="components-guide__finish-button"
 							onClick={ onFinish }
 						>
-							{ finishButtonText || __( 'Finish' ) }
+							{ finishButtonText }
 						</Button>
 					) }
 				</div>
@@ -132,3 +170,5 @@ export default function Guide( {
 		</Modal>
 	);
 }
+
+export default Guide;

package/src/guide/{page-control.js → page-control.tsx}

@@ -8,12 +8,13 @@ import { __, sprintf } from '@wordpress/i18n';
  */
 import Button from '../button';
 import { PageControlIcon } from './icons';
+import type { PageControlProps } from './types';
 
 export default function PageControl( {
 	currentPage,
 	numberOfPages,
 	setCurrentPage,
-} ) {
+}: PageControlProps ) {
 	return (
 		<ul
 			className="components-guide__page-control"

package/src/guide/{page.js → page.tsx}

@@ -4,7 +4,14 @@
 import { useEffect } from '@wordpress/element';
 import deprecated from '@wordpress/deprecated';
 
-export default function GuidePage( props ) {
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../ui/context';
+
+export default function GuidePage(
+	props: WordPressComponentProps< {}, 'div', false >
+) {
 	useEffect( () => {
 		deprecated( '<GuidePage>', {
 			since: '5.5',

package/src/guide/stories/{index.js → index.tsx}

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
 /**
  * WordPress dependencies
  */
@@ -7,9 +12,9 @@ import { useState } from '@wordpress/element';
  * Internal dependencies
  */
 import Button from '../../button';
-import Guide from '../';
+import Guide from '..';
 
-export default {
+const meta: ComponentMeta< typeof Guide > = {
 	title: 'Components/Guide',
 	component: Guide,
 	argTypes: {
@@ -18,8 +23,9 @@ export default {
 		onFinish: { action: 'onFinish' },
 	},
 };
+export default meta;
 
-const Template = ( { onFinish, ...props } ) => {
+const Template: ComponentStory< typeof Guide > = ( { onFinish, ...props } ) => {
 	const [ isOpen, setOpen ] = useState( false );
 
 	const openGuide = () => setOpen( true );
@@ -34,8 +40,8 @@ const Template = ( { onFinish, ...props } ) => {
 				<Guide
 					{ ...props }
 					onFinish={ ( ...finishArgs ) => {
-						closeGuide( ...finishArgs );
-						onFinish( ...finishArgs );
+						closeGuide();
+						onFinish?.( ...finishArgs );
 					} }
 				/>
 			) }

package/src/guide/test/{index.js → index.tsx}

@@ -7,17 +7,23 @@ import userEvent from '@testing-library/user-event';
 /**
  * Internal dependencies
  */
-import Guide from '../';
+import Guide from '..';
+
+const defaultProps = {
+	onFinish: () => {},
+	contentLabel: 'Arbitrary Content Label',
+};
 
 describe( 'Guide', () => {
 	it( 'renders nothing when there are no pages', () => {
-		render( <Guide pages={ [] } /> );
+		render( <Guide { ...defaultProps } pages={ [] } /> );
 		expect( screen.queryByRole( 'dialog' ) ).not.toBeInTheDocument();
 	} );
 
 	it( 'renders one page at a time', () => {
 		render(
 			<Guide
+				{ ...defaultProps }
 				pages={ [
 					{ content: <p>Page 1</p> },
 					{ content: <p>Page 2</p> },
@@ -33,6 +39,7 @@ describe( 'Guide', () => {
 	it( 'hides back button and shows forward button on the first page', () => {
 		render(
 			<Guide
+				{ ...defaultProps }
 				pages={ [
 					{ content: <p>Page 1</p> },
 					{ content: <p>Page 2</p> },
@@ -55,6 +62,7 @@ describe( 'Guide', () => {
 		const user = userEvent.setup();
 		render(
 			<Guide
+				{ ...defaultProps }
 				pages={ [
 					{ content: <p>Page 1</p> },
 					{ content: <p>Page 2</p> },
@@ -78,7 +86,12 @@ describe( 'Guide', () => {
 	} );
 
 	it( "doesn't display the page control if there is only one page", () => {
-		render( <Guide pages={ [ { content: <p>Page 1</p> } ] } /> );
+		render(
+			<Guide
+				{ ...defaultProps }
+				pages={ [ { content: <p>Page 1</p> } ] }
+			/>
+		);
 		expect(
 			screen.queryByRole( 'list', { name: 'Guide controls' } )
 		).not.toBeInTheDocument();
@@ -89,6 +102,7 @@ describe( 'Guide', () => {
 		const onFinish = jest.fn();
 		render(
 			<Guide
+				{ ...defaultProps }
 				onFinish={ onFinish }
 				pages={ [ { content: <p>Page 1</p> } ] }
 			/>
@@ -103,6 +117,7 @@ describe( 'Guide', () => {
 		const onFinish = jest.fn();
 		render(
 			<Guide
+				{ ...defaultProps }
 				onFinish={ onFinish }
 				pages={ [ { content: <p>Page 1</p> } ] }
 			/>
@@ -115,7 +130,7 @@ describe( 'Guide', () => {
 
 	describe( 'page navigation', () => {
 		it( 'renders an empty list when there are no pages', () => {
-			render( <Guide pages={ [] } /> );
+			render( <Guide { ...defaultProps } pages={ [] } /> );
 			expect(
 				screen.queryByRole( 'list', {
 					name: 'Guide controls',
@@ -131,6 +146,7 @@ describe( 'Guide', () => {
 		it( 'renders a button for each page', () => {
 			render(
 				<Guide
+					{ ...defaultProps }
 					pages={ [
 						{ content: <p>Page 1</p> },
 						{ content: <p>Page 2</p> },
@@ -154,6 +170,7 @@ describe( 'Guide', () => {
 
 			render(
 				<Guide
+					{ ...defaultProps }
 					pages={ [
 						{ content: <p>Page 1</p> },
 						{ content: <p>Page 2</p> },
@@ -196,6 +213,7 @@ describe( 'Guide', () => {
 
 			render(
 				<Guide
+					{ ...defaultProps }
 					pages={ [
 						{ content: <p>Page 1</p> },
 						{ content: <p>Page 2</p> },