@wordpress/components 23.5.0 → 23.7.0

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

@@ -44,6 +44,7 @@ const FormTokenFieldWithState = ( {
 				setSelectedValue( tokens );
 				onChange?.( tokens );
 			} }
+			__nextHasNoMarginBottom
 		/>
 	);
 };
@@ -950,6 +951,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/form-token-field/types.ts

@@ -169,6 +169,12 @@ export interface FormTokenFieldProps
 	 * Custom renderer for suggestions.
 	 */
 	__experimentalRenderItem?: ( args: { item: string } ) => ReactNode;
+	/**
+	 * Start opting into the new margin-free styles that will become the default in a future version.
+	 *
+	 * @default false
+	 */
+	__nextHasNoMarginBottom?: boolean;
 }
 
 /**

package/src/gradient-picker/README.md

@@ -49,63 +49,56 @@ const myGradientPicker = () => {
 
 The component accepts the following props:
 
-### value
+### `className`: `string`
+
+The class name added to the wrapper.
+
+-   Required: No
+
+### `value`: `string`
 
 The current value of the gradient. Pass a css gradient like `linear-gradient(90deg, rgb(6, 147, 227) 0%, rgb(155, 81, 224) 100%)`. Optionally pass in a `null` value to specify no gradient is currently selected.
 
--   Type: `string`
 -   Required: No
 -   Default: `linear-gradient(90deg, rgb(6, 147, 227) 0%, rgb(155, 81, 224) 100%)`
 
-### onChange
+### `onChange`: `( currentGradient: string | undefined ) => void`
 
 The function called when a new gradient has been defined. It is passed the `currentGradient` as an argument.
 
--   Type: `Function`
 -   Required: Yes
 
-### gradients
+### `gradients`: `GradientsProp[]`
 
-An array of objects of predefined gradients which show up as `CircularOptionPicker` above the gradient selector.
+An array of objects of predefined gradients displayed above the gradient selector.
 
--   Type: `array`
 -   Required: No
+-   Default: `[]`
 
-### clearable
+### `clearable`: `boolean`
 
 Whether the palette should have a clearing button or not.
 
--   Type: `Boolean`
 -   Required: No
 -   Default: true
 
-### clearGradient
-
-Called when a new gradient has been defined. It is passed the `currentGradient` as an argument.
-
--   Type: `Function`
--   Required: No
-
-### disableCustomGradients
+### `disableCustomGradients`: `boolean`
 
 If true, the gradient picker will not be displayed and only defined gradients from `gradients` are available.
 
--   Type: `Boolean`
 -   Required: No
 -   Default: false
 
-### __nextHasNoMargin
+### `__nextHasNoMargin`: `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`
 
-### headingLevel
+### `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
 
-The heading level.
+The heading level. Only applies in cases where gradients are provided from multiple origins (ie. when the array passed as the `gradients` prop contains two or more items).
 
--   Type: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
 -   Required: No
 -   Default: `2`

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

@@ -13,13 +13,21 @@ import CustomGradientPicker from '../custom-gradient-picker';
 import { VStack } from '../v-stack';
 import { ColorHeading } from '../color-palette/styles';
 import { Spacer } from '../spacer';
+import type {
+	GradientPickerComponentProps,
+	PickerProps,
+	OriginObject,
+	GradientObject,
+} from './types';
 
 // The Multiple Origin Gradients have a `gradients` property (an array of
 // gradient objects), while Single Origin ones have a `gradient` property.
-const isMultipleOriginObject = ( obj ) =>
+const isMultipleOriginObject = (
+	obj: Record< string, any >
+): obj is OriginObject =>
 	Array.isArray( obj.gradients ) && ! ( 'gradient' in obj );
 
-const isMultipleOriginArray = ( arr ) => {
+const isMultipleOriginArray = ( arr: any[] ): arr is OriginObject[] => {
 	return (
 		arr.length > 0 &&
 		arr.every( ( gradientObj ) => isMultipleOriginObject( gradientObj ) )
@@ -33,7 +41,7 @@ function SingleOrigin( {
 	onChange,
 	value,
 	actions,
-} ) {
+}: PickerProps< GradientObject > ) {
 	const gradientOptions = useMemo( () => {
 		return gradients.map( ( { gradient, name }, index ) => (
 			<CircularOptionPicker.Option
@@ -78,7 +86,7 @@ function MultipleOrigin( {
 	value,
 	actions,
 	headingLevel,
-} ) {
+}: PickerProps< OriginObject > ) {
 	return (
 		<VStack spacing={ 3 } className={ className }>
 			{ gradients.map( ( { name, gradients: gradientSet }, index ) => {
@@ -105,25 +113,72 @@ function MultipleOrigin( {
 	);
 }
 
-export default function GradientPicker( {
+function Component( props: PickerProps< any > ) {
+	if ( isMultipleOriginArray( props.gradients ) ) {
+		return <MultipleOrigin { ...props } />;
+	}
+	return <SingleOrigin { ...props } />;
+}
+
+/**
+ *  GradientPicker is a React component that renders a color gradient picker to
+ * define a multi step gradient. There's either a _linear_ or a _radial_ type
+ * available.
+ *
+ * ```jsx
+ *import { GradientPicker } from '@wordpress/components';
+ *import { useState } from '@wordpress/element';
+ *
+ *const myGradientPicker = () => {
+ *	const [ gradient, setGradient ] = useState( null );
+ *
+ *	return (
+ *		<GradientPicker
+ *			__nextHasNoMargin
+ *			value={ gradient }
+ *			onChange={ ( currentGradient ) => setGradient( currentGradient ) }
+ *			gradients={ [
+ *				{
+ *					name: 'JShine',
+ *					gradient:
+ *						'linear-gradient(135deg,#12c2e9 0%,#c471ed 50%,#f64f59 100%)',
+ *					slug: 'jshine',
+ *				},
+ *				{
+ *					name: 'Moonlit Asteroid',
+ *					gradient:
+ *						'linear-gradient(135deg,#0F2027 0%, #203A43 0%, #2c5364 100%)',
+ *					slug: 'moonlit-asteroid',
+ *				},
+ *				{
+ *					name: 'Rastafarie',
+ *					gradient:
+ *						'linear-gradient(135deg,#1E9600 0%, #FFF200 0%, #FF0000 100%)',
+ *					slug: 'rastafari',
+ *				},
+ *			] }
+ *		/>
+ *	);
+ *};
+ *```
+ *
+ */
+export function GradientPicker( {
 	/** Start opting into the new margin-free styles that will become the default in a future version. */
 	__nextHasNoMargin = false,
 	className,
-	gradients,
+	gradients = [],
 	onChange,
 	value,
 	clearable = true,
 	disableCustomGradients = false,
 	__experimentalIsRenderedInSidebar,
 	headingLevel = 2,
-} ) {
+}: GradientPickerComponentProps ) {
 	const clearGradient = useCallback(
 		() => onChange( undefined ),
 		[ onChange ]
 	);
-	const Component = isMultipleOriginArray( gradients )
-		? MultipleOrigin
-		: SingleOrigin;
 
 	if ( ! __nextHasNoMargin ) {
 		deprecated( 'Outer margin styles for wp.components.GradientPicker', {
@@ -135,7 +190,7 @@ export default function GradientPicker( {
 
 	const deprecatedMarginSpacerProps = ! __nextHasNoMargin
 		? {
-				marginTop: ! gradients?.length ? 3 : undefined,
+				marginTop: ! gradients.length ? 3 : undefined,
 				marginBottom: ! clearable ? 6 : 0,
 		  }
 		: {};
@@ -143,7 +198,7 @@ export default function GradientPicker( {
 	return (
 		// Outmost Spacer wrapper can be removed when deprecation period is over
 		<Spacer marginBottom={ 0 } { ...deprecatedMarginSpacerProps }>
-			<VStack spacing={ gradients?.length ? 4 : 0 }>
+			<VStack spacing={ gradients.length ? 4 : 0 }>
 				{ ! disableCustomGradients && (
 					<CustomGradientPicker
 						__nextHasNoMargin
@@ -154,10 +209,9 @@ export default function GradientPicker( {
 						onChange={ onChange }
 					/>
 				) }
-				{ ( gradients?.length || clearable ) && (
+				{ ( gradients.length || clearable ) && (
 					<Component
 						className={ className }
-						clearable={ clearable }
 						clearGradient={ clearGradient }
 						gradients={ gradients }
 						onChange={ onChange }
@@ -179,3 +233,5 @@ export default function GradientPicker( {
 		</Spacer>
 	);
 }
+
+export default GradientPicker;

package/src/gradient-picker/stories/{index.js → index.tsx}

@@ -1,3 +1,7 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
 /**
  * WordPress dependencies
  */
@@ -6,18 +10,21 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import GradientPicker from '../';
+import GradientPicker from '..';
 
-export default {
+const meta: ComponentMeta< typeof GradientPicker > = {
 	title: 'Components/GradientPicker',
 	component: GradientPicker,
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+		actions: { argTypesRegex: '^on.*' },
+	},
 	argTypes: {
-		__nextHasNoMargin: { control: { type: 'boolean' } },
-		clearable: { control: { type: 'boolean' } },
-		disableCustomGradients: { control: { type: 'boolean' } },
-		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
 	},
 };
+export default meta;
 
 const GRADIENTS = [
 	{
@@ -58,8 +65,12 @@ const GRADIENTS = [
 	},
 ];
 
-const Template = ( { onChange, ...props } ) => {
-	const [ gradient, setGradient ] = useState();
+const Template: ComponentStory< typeof GradientPicker > = ( {
+	onChange,
+	...props
+} ) => {
+	const [ gradient, setGradient ] =
+		useState< ( typeof props )[ 'value' ] >( null );
 	return (
 		<GradientPicker
 			{ ...props }

package/src/gradient-picker/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Internal dependencies
+ */
+import type { HeadingSize } from '../heading/types';
+
+export type GradientObject = {
+	gradient: string;
+	name: string;
+	slug: string;
+};
+export type OriginObject = { name: string; gradients: GradientObject[] };
+export type GradientsProp = GradientObject[] | OriginObject[];
+
+type GradientPickerBaseProps = {
+	/**
+	 * The class name added to the wrapper.
+	 */
+	className?: string;
+	/**
+	 * The function called when a new gradient has been defined. It is passed to
+	 * the `currentGradient` as an argument.
+	 */
+	onChange: ( currentGradient: string | undefined ) => void;
+	/**
+	 * The current value of the gradient. Pass a css gradient string (See default value for example).
+	 * Optionally pass in a `null` value to specify no gradient is currently selected.
+	 *
+	 * @default 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)'
+	 */
+	value?: GradientObject[ 'gradient' ] | null;
+	/**
+	 * Whether the palette should have a clearing button or not.
+	 *
+	 * @default true
+	 */
+	clearable?: boolean;
+	/**
+	 * The heading level. Only applies in cases where gradients are provided
+	 * from multiple origins (ie. when the array passed as the `gradients` prop
+	 * contains two or more items).
+	 *
+	 * @default 2
+	 */
+	headingLevel?: HeadingSize;
+};
+
+export type GradientPickerComponentProps = GradientPickerBaseProps & {
+	/**
+	 * An array of objects as predefined gradients displayed above the gradient
+	 * selector. Alternatively, if there are multiple sets (or 'origins') of
+	 * gradients, you can pass an array of objects each with a `name` and a
+	 * `gradients` array which will in turn contain the predefined gradient objects.
+	 *
+	 * @default []
+	 */
+	gradients?: GradientsProp;
+	/**
+	 * Start opting in to 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.)
+	 *
+	 * @default false
+	 */
+	__nextHasNoMargin?: boolean;
+	/**
+	 * If true, the gradient picker will not be displayed and only defined
+	 * gradients from `gradients` will be shown.
+	 *
+	 * @default false
+	 */
+	disableCustomGradients?: boolean;
+	/**
+	 * Whether this is rendered in the sidebar.
+	 *
+	 * @default false
+	 */
+	__experimentalIsRenderedInSidebar?: boolean;
+};
+
+export type PickerProps< TOriginType extends GradientObject | OriginObject > =
+	GradientPickerBaseProps & {
+		clearGradient: () => void;
+		onChange: (
+			currentGradient: string | undefined,
+			index: number
+		) => void;
+		actions?: React.ReactNode;
+		gradients: TOriginType[];
+	};

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