@wordpress/components 19.15.0 → 20.0.1-next.d6164808d3.0

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

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { last, clone, uniq, map, difference, some } from 'lodash';
+import { last, clone, map, some } from 'lodash';
 import classnames from 'classnames';
 import type { KeyboardEvent, MouseEvent, TouchEvent } from 'react';
 
@@ -34,6 +34,7 @@ import { TokensAndInputWrapperFlex } from './styles';
 import SuggestionsList from './suggestions-list';
 import type { FormTokenFieldProps, TokenItem } from './types';
 import { FlexItem } from '../flex';
+import { StyledLabel } from '../base-control/styles/base-control-styles';
 
 const identity = ( value: string ) => value;
 
@@ -72,10 +73,12 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 			remove: __( 'Remove item' ),
 			__experimentalInvalid: __( 'Invalid item' ),
 		},
+		__experimentalRenderItem,
 		__experimentalExpandOnFocus = false,
 		__experimentalValidateInput = () => true,
 		__experimentalShowHowTo = true,
 		__next36pxDefaultSize = false,
+		__experimentalAutoSelectFirstMatch = false,
 	} = props;
 
 	const instanceId = useInstanceId( FormTokenField );
@@ -407,12 +410,14 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 	}
 
 	function addNewTokens( tokens: string[] ) {
-		const tokensToAdd = uniq(
-			tokens
-				.map( saveTransform )
-				.filter( Boolean )
-				.filter( ( token ) => ! valueContainsToken( token ) )
-		);
+		const tokensToAdd = [
+			...new Set(
+				tokens
+					.map( saveTransform )
+					.filter( Boolean )
+					.filter( ( token ) => ! valueContainsToken( token ) )
+			),
+		];
 
 		if ( tokensToAdd.length > 0 ) {
 			const newValue = clone( value );
@@ -473,7 +478,9 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		} );
 
 		if ( match.length === 0 ) {
-			_suggestions = difference( _suggestions, normalizedValue );
+			_suggestions = _suggestions.filter(
+				( suggestion ) => ! normalizedValue.includes( suggestion )
+			);
 		} else {
 			match = match.toLocaleLowerCase();
 
@@ -532,8 +539,17 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		);
 
 		if ( resetSelectedSuggestion ) {
-			setSelectedSuggestionIndex( -1 );
-			setSelectedSuggestionScroll( false );
+			if (
+				__experimentalAutoSelectFirstMatch &&
+				inputHasMinimumChars &&
+				hasMatchingSuggestions
+			) {
+				setSelectedSuggestionIndex( 0 );
+				setSelectedSuggestionScroll( true );
+			} else {
+				setSelectedSuggestionIndex( -1 );
+				setSelectedSuggestionScroll( false );
+			}
 		}
 
 		if ( inputHasMinimumChars ) {
@@ -659,12 +675,12 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 	/* eslint-disable jsx-a11y/no-static-element-interactions */
 	return (
 		<div { ...tokenFieldProps }>
-			<label
+			<StyledLabel
 				htmlFor={ `components-form-token-input-${ instanceId }` }
 				className="components-form-token-field__label"
 			>
 				{ label }
-			</label>
+			</StyledLabel>
 			<div
 				ref={ tokensAndInput }
 				className={ classes }
@@ -692,6 +708,7 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 						scrollIntoView={ selectedSuggestionScroll }
 						onHover={ onSuggestionHovered }
 						onSelect={ onSuggestionSelected }
+						__experimentalRenderItem={ __experimentalRenderItem }
 					/>
 				) }
 			</div>

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

@@ -101,3 +101,25 @@ Async.args = {
 	label: 'Type a continent',
 	suggestions: continents,
 };
+
+export const DropdownSelector: ComponentStory< typeof FormTokenField > =
+	DefaultTemplate.bind( {} );
+DropdownSelector.args = {
+	...Default.args,
+	__experimentalExpandOnFocus: true,
+	__experimentalAutoSelectFirstMatch: true,
+};
+
+/**
+ * The rendered output of each suggestion can be customized by passing a
+ * render function to the `__experimentalRenderItem` prop. (This is still an experimental feature
+ * and is subject to change.)
+ */
+export const WithCustomRenderItem: ComponentStory< typeof FormTokenField > =
+	DefaultTemplate.bind( {} );
+WithCustomRenderItem.args = {
+	...Default.args,
+	__experimentalRenderItem: ( { item } ) => (
+		<div>{ `${ item } — a nice place to visit` }</div>
+	),
+};

package/src/form-token-field/style.scss

@@ -48,11 +48,6 @@
 	}
 }
 
-.components-form-token-field__label {
-	display: inline-block;
-	margin-bottom: $grid-unit-10;
-}
-
 .components-form-token-field__help {
 	font-size: $helptext-font-size;
 	font-style: normal;

package/src/form-token-field/suggestions-list.tsx

@@ -4,7 +4,7 @@
 import { map } from 'lodash';
 import scrollView from 'dom-scroll-into-view';
 import classnames from 'classnames';
-import type { MouseEventHandler } from 'react';
+import type { MouseEventHandler, ReactNode } from 'react';
 
 /**
  * WordPress dependencies
@@ -31,6 +31,7 @@ export function SuggestionsList< T extends string | { value: string } >( {
 	suggestions = [],
 	displayTransform,
 	instanceId,
+	__experimentalRenderItem,
 }: SuggestionsListProps< T > ) {
 	const [ scrollingIntoView, setScrollingIntoView ] = useState( false );
 
@@ -122,6 +123,24 @@ export function SuggestionsList< T extends string | { value: string } >( {
 					}
 				);
 
+				let output: ReactNode;
+
+				if ( typeof __experimentalRenderItem === 'function' ) {
+					output = __experimentalRenderItem( { item: suggestion } );
+				} else if ( matchText ) {
+					output = (
+						<span aria-label={ displayTransform( suggestion ) }>
+							{ matchText.suggestionBeforeMatch }
+							<strong className="components-form-token-field__suggestion-match">
+								{ matchText.suggestionMatch }
+							</strong>
+							{ matchText.suggestionAfterMatch }
+						</span>
+					);
+				} else {
+					output = displayTransform( suggestion );
+				}
+
 				/* eslint-disable jsx-a11y/click-events-have-key-events */
 				return (
 					<li
@@ -139,17 +158,7 @@ export function SuggestionsList< T extends string | { value: string } >( {
 						onMouseEnter={ handleHover( suggestion ) }
 						aria-selected={ index === selectedIndex }
 					>
-						{ matchText ? (
-							<span aria-label={ displayTransform( suggestion ) }>
-								{ matchText.suggestionBeforeMatch }
-								<strong className="components-form-token-field__suggestion-match">
-									{ matchText.suggestionMatch }
-								</strong>
-								{ matchText.suggestionAfterMatch }
-							</span>
-						) : (
-							displayTransform( suggestion )
-						) }
+						{ output }
 					</li>
 				);
 				/* eslint-enable jsx-a11y/click-events-have-key-events */

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

@@ -162,7 +162,7 @@ describe( 'FormTokenField', () => {
 			);
 		} );
 
-		it( 'should show suggestions when when input is empty if expandOnFocus is set to true', () => {
+		it( 'should show suggestions when input is empty if expandOnFocus is set to true', () => {
 			setUp( { __experimentalExpandOnFocus: true } );
 			wrapper.setState( {
 				isExpanded: true,
@@ -396,6 +396,37 @@ describe( 'FormTokenField', () => {
 			sendKeyDown( keyCodes.enter );
 			expect( wrapper.state.tokens ).toEqual( [ 'foo', 'bar' ] );
 		} );
+
+		it( 'should automatically select the first matching suggestions when __experimentalAutoSelectFirstMatch is set to true', () => {
+			setUp( { __experimentalAutoSelectFirstMatch: true } );
+
+			wrapper.setState( {
+				isExpanded: true,
+			} );
+
+			expect( getSuggestionsText() ).toEqual( [] );
+
+			const searchText = 'so';
+
+			act( () => {
+				setText( searchText );
+			} );
+
+			const expectedFirstMatchTokens =
+				fixtures.matchingSuggestions[ searchText ][ 0 ];
+
+			expect( getSelectedSuggestion() ).toEqual(
+				expectedFirstMatchTokens
+			);
+
+			sendKeyDown( keyCodes.enter );
+
+			expect( wrapper.state.tokens ).toEqual( [
+				'foo',
+				'bar',
+				expectedFirstMatchTokens.join( '' ),
+			] );
+		} );
 	} );
 
 	describe( 'removing tokens', () => {

package/src/form-token-field/types.ts

@@ -1,7 +1,11 @@
 /**
  * External dependencies
  */
-import type { ComponentPropsWithRef, MouseEventHandler } from 'react';
+import type {
+	ComponentPropsWithRef,
+	MouseEventHandler,
+	ReactNode,
+} from 'react';
 
 type Messages = {
 	/**
@@ -154,9 +158,25 @@ export interface FormTokenFieldProps
 	 * @default false
 	 */
 	__next36pxDefaultSize?: boolean;
+	/**
+	 * If true, the select the first matching suggestion when the user presses
+	 * the Enter key (or space when tokenizeOnSpace is true).
+	 *
+	 * @default false
+	 */
+	__experimentalAutoSelectFirstMatch?: boolean;
+	/**
+	 * Custom renderer for suggestions.
+	 */
+	__experimentalRenderItem?: ( args: { item: string } ) => ReactNode;
 }
 
-export interface SuggestionsListProps< T = string | { value: string } > {
+/**
+ * `T` can be either a `string` or an object which must have a `value` prop as a string.
+ */
+export interface SuggestionsListProps<
+	T = string | ( Record< string, unknown > & { value: string } )
+> {
 	selectedIndex: number;
 	scrollIntoView: boolean;
 	match: T;
@@ -165,6 +185,7 @@ export interface SuggestionsListProps< T = string | { value: string } > {
 	suggestions: T[];
 	displayTransform: ( value: T ) => string;
 	instanceId: string | number;
+	__experimentalRenderItem?: ( args: { item: T } ) => ReactNode;
 }
 
 export interface TokenProps extends TokenItem {

package/src/gradient-picker/index.js

@@ -16,6 +16,7 @@ import CircularOptionPicker from '../circular-option-picker';
 import CustomGradientPicker from '../custom-gradient-picker';
 import { VStack } from '../v-stack';
 import { ColorHeading } from '../color-palette/styles';
+import { Spacer } from '../spacer';
 
 function SingleOrigin( {
 	className,
@@ -99,6 +100,8 @@ function MultipleOrigin( {
 }
 
 export default function GradientPicker( {
+	/** Start opting into the new margin-free styles that will become the default in a future version. */
+	__nextHasNoMargin = false,
 	className,
 	gradients,
 	onChange,
@@ -117,6 +120,11 @@ export default function GradientPicker( {
 			? MultipleOrigin
 			: SingleOrigin;
 
+	// Can be removed when deprecation period is over
+	const deprecatedMarginSpacerProps = ! __nextHasNoMargin
+		? { marginTop: 3 }
+		: {};
+
 	return (
 		<Component
 			className={ className }
@@ -137,13 +145,20 @@ export default function GradientPicker( {
 			}
 			content={
 				! disableCustomGradients && (
-					<CustomGradientPicker
-						__experimentalIsRenderedInSidebar={
-							__experimentalIsRenderedInSidebar
-						}
-						value={ value }
-						onChange={ onChange }
-					/>
+					<Spacer
+						marginTop={ gradients?.length ? 3 : 0 }
+						marginBottom={ 0 }
+						{ ...deprecatedMarginSpacerProps }
+					>
+						<CustomGradientPicker
+							__nextHasNoMargin={ __nextHasNoMargin }
+							__experimentalIsRenderedInSidebar={
+								__experimentalIsRenderedInSidebar
+							}
+							value={ value }
+							onChange={ onChange }
+						/>
+					</Spacer>
 				)
 			}
 		/>

package/src/gradient-picker/stories/index.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { text, boolean, object } from '@storybook/addon-knobs';
-
 /**
  * WordPress dependencies
  */
@@ -16,94 +11,74 @@ import GradientPicker from '../';
 export default {
 	title: 'Components/GradientPicker',
 	component: GradientPicker,
-	parameters: {
-		knobs: { disable: false },
+	argTypes: {
+		__nextHasNoMargin: { control: { type: 'boolean' } },
+		clearable: { control: { type: 'boolean' } },
+		disableCustomGradients: { control: { type: 'boolean' } },
+		onChange: { action: 'onChange' },
 	},
 };
 
-const GradientPickerWithState = ( props ) => {
+const GRADIENTS = [
+	{
+		name: 'Vivid cyan blue to vivid purple',
+		gradient:
+			'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
+		slug: 'vivid-cyan-blue-to-vivid-purple',
+	},
+	{
+		name: 'Light green cyan to vivid green cyan',
+		gradient:
+			'linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)',
+		slug: 'light-green-cyan-to-vivid-green-cyan',
+	},
+	{
+		name: 'Luminous vivid amber to luminous vivid orange',
+		gradient:
+			'linear-gradient(135deg,rgba(252,185,0,1) 0%,rgba(255,105,0,1) 100%)',
+		slug: 'luminous-vivid-amber-to-luminous-vivid-orange',
+	},
+	{
+		name: 'Luminous vivid orange to vivid red',
+		gradient:
+			'linear-gradient(135deg,rgba(255,105,0,1) 0%,rgb(207,46,46) 100%)',
+		slug: 'luminous-vivid-orange-to-vivid-red',
+	},
+	{
+		name: 'Very light gray to cyan bluish gray',
+		gradient:
+			'linear-gradient(135deg,rgb(238,238,238) 0%,rgb(169,184,195) 100%)',
+		slug: 'very-light-gray-to-cyan-bluish-gray',
+	},
+	{
+		name: 'Cool to warm spectrum',
+		gradient:
+			'linear-gradient(135deg,rgb(74,234,220) 0%,rgb(151,120,209) 20%,rgb(207,42,186) 40%,rgb(238,44,130) 60%,rgb(251,105,98) 80%,rgb(254,248,76) 100%)',
+		slug: 'cool-to-warm-spectrum',
+	},
+];
+
+const Template = ( { onChange, ...props } ) => {
 	const [ gradient, setGradient ] = useState();
 	return (
 		<GradientPicker
 			{ ...props }
 			value={ gradient }
-			onChange={ setGradient }
+			onChange={ ( ...changeArgs ) => {
+				setGradient( ...changeArgs );
+				onChange?.( ...changeArgs );
+			} }
 		/>
 	);
 };
 
-export const _default = () => {
-	const disableCustomGradients = boolean( 'Disable Custom Gradients', false );
-	const clearable = boolean( 'Clearable', true );
-	const className = text( 'Class Name', '' );
-	const gradients = object( 'Gradients', [
-		{
-			name: 'Vivid cyan blue to vivid purple',
-			gradient:
-				'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
-			slug: 'vivid-cyan-blue-to-vivid-purple',
-		},
-		{
-			name: 'Light green cyan to vivid green cyan',
-			gradient:
-				'linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)',
-			slug: 'light-green-cyan-to-vivid-green-cyan',
-		},
-		{
-			name: 'Luminous vivid amber to luminous vivid orange',
-			gradient:
-				'linear-gradient(135deg,rgba(252,185,0,1) 0%,rgba(255,105,0,1) 100%)',
-			slug: 'luminous-vivid-amber-to-luminous-vivid-orange',
-		},
-		{
-			name: 'Luminous vivid orange to vivid red',
-			gradient:
-				'linear-gradient(135deg,rgba(255,105,0,1) 0%,rgb(207,46,46) 100%)',
-			slug: 'luminous-vivid-orange-to-vivid-red',
-		},
-		{
-			name: 'Very light gray to cyan bluish gray',
-			gradient:
-				'linear-gradient(135deg,rgb(238,238,238) 0%,rgb(169,184,195) 100%)',
-			slug: 'very-light-gray-to-cyan-bluish-gray',
-		},
-		{
-			name: 'Cool to warm spectrum',
-			gradient:
-				'linear-gradient(135deg,rgb(74,234,220) 0%,rgb(151,120,209) 20%,rgb(207,42,186) 40%,rgb(238,44,130) 60%,rgb(251,105,98) 80%,rgb(254,248,76) 100%)',
-			slug: 'cool-to-warm-spectrum',
-		},
-	] );
-
-	return (
-		<GradientPickerWithState
-			disableCustomGradients={ disableCustomGradients }
-			gradients={ gradients }
-			clearable={ clearable }
-			className={ className }
-		/>
-	);
+export const Default = Template.bind( {} );
+Default.args = {
+	gradients: GRADIENTS,
 };
 
-export const WithNoExistingGradients = () => {
-	const disableCustomGradients = boolean( 'Disable Custom Gradients', false );
-	const __experimentalHasMultipleOrigins = boolean(
-		'Experimental Has Multiple Origins',
-		true
-	);
-	const clearable = boolean( 'Clearable', true );
-	const className = text( 'Class Name', '' );
-	const gradients = object( 'Gradients', [] );
-
-	return (
-		<GradientPickerWithState
-			__experimentalHasMultipleOrigins={
-				__experimentalHasMultipleOrigins
-			}
-			disableCustomGradients={ disableCustomGradients }
-			gradients={ gradients }
-			clearable={ clearable }
-			className={ className }
-		/>
-	);
+export const WithNoExistingGradients = Template.bind( {} );
+WithNoExistingGradients.args = {
+	...Default.args,
+	gradients: [],
 };

package/src/guide/index.js

@@ -42,7 +42,9 @@ export default function Guide( {
 	useEffect( () => {
 		// Each time we change the current page, start from the first element of the page.
 		// This also solves any focus loss that can happen.
-		focus.tabbable.find( guideContainer.current )?.[ 0 ]?.focus();
+		if ( guideContainer.current ) {
+			focus.tabbable.find( guideContainer.current )?.[ 0 ]?.focus();
+		}
 	}, [ currentPage ] );
 
 	if ( Children.count( children ) ) {

package/src/guide/page-control.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { times } from 'lodash';
-
 /**
  * WordPress dependencies
  */
@@ -24,7 +19,7 @@ export default function PageControl( {
 			className="components-guide__page-control"
 			aria-label={ __( 'Guide controls' ) }
 		>
-			{ times( numberOfPages, ( page ) => (
+			{ Array.from( { length: numberOfPages } ).map( ( _, page ) => (
 				<li
 					key={ page }
 					// Set aria-current="step" on the active page, see https://www.w3.org/TR/wai-aria-1.1/#aria-current

package/src/guide/stories/index.js

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { times } from 'lodash';
 import { text, number } from '@storybook/addon-knobs';
 
 /**
@@ -41,16 +40,18 @@ const ModalExample = ( { numberOfPages, ...props } ) => {
 				<Guide
 					{ ...props }
 					onFinish={ closeGuide }
-					pages={ times( numberOfPages, ( page ) => ( {
-						content: (
-							<>
-								<h1>
-									Page { page + 1 } of { numberOfPages }
-								</h1>
-								<p>{ loremIpsum }</p>
-							</>
-						),
-					} ) ) }
+					pages={ Array.from( { length: numberOfPages } ).map(
+						( _, page ) => ( {
+							content: (
+								<>
+									<h1>
+										Page { page + 1 } of { numberOfPages }
+									</h1>
+									<p>{ loremIpsum }</p>
+								</>
+							),
+						} )
+					) }
 				/>
 			) }
 		</>