@wordpress/components 19.10.0 → 19.13.0

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

@@ -0,0 +1,178 @@
+/**
+ * External dependencies
+ */
+import type { ComponentPropsWithRef, MouseEventHandler } from 'react';
+
+type Messages = {
+	/**
+	 * The user added a new token.
+	 */
+	added: string;
+	/**
+	 * The user removed an existing token.
+	 */
+	removed: string;
+	/**
+	 * The user focused the button to remove the token.
+	 */
+	remove: string;
+	/**
+	 * The user tried to add a token that didn't pass the validation.
+	 */
+	__experimentalInvalid: string;
+};
+
+export interface TokenItem {
+	/**
+	 *  The value of the token.
+	 */
+	value: string;
+	/**
+	 * One of 'error', 'validating', or 'success'. Applies styles to token.
+	 */
+	status?: 'error' | 'success' | 'validating';
+	/**
+	 * If not falsey, will add a title to the token.
+	 */
+	title?: string;
+	/**
+	 * When true, renders tokens as without a background.
+	 */
+	isBorderless?: boolean;
+	/**
+	 * Function to call when onMouseEnter event triggered on token.
+	 */
+	onMouseEnter?: MouseEventHandler< HTMLSpanElement >;
+	/**
+	 *  Function to call when onMouseLeave is triggered on token.
+	 */
+	onMouseLeave?: MouseEventHandler< HTMLSpanElement >;
+}
+
+export interface FormTokenFieldProps
+	extends Pick<
+		ComponentPropsWithRef< 'input' >,
+		'autoCapitalize' | 'autoComplete' | 'className'
+	> {
+	label?: string;
+	/**
+	 * An array of strings to present to the user as suggested tokens.
+	 */
+	suggestions?: string[];
+	/**
+	 * The maximum number of suggestions to display at a time.
+	 *
+	 * @default 100
+	 */
+	maxSuggestions?: number;
+	/**
+	 * An array of strings or objects to display as tokens in the field.
+	 * If objects are present in the array, they **must** have a property of `value`.
+	 */
+	value?: ( string | TokenItem )[];
+	/**
+	 * Function to call to transform tokens for display.
+	 * (In the editor, this is needed to decode HTML entities embedded in tags
+	 * - otherwise entities like `&` in tag names are double-encoded like `&amp;`,
+	 * once by the REST API and once by React).
+	 */
+	displayTransform?: ( token: string ) => string;
+	/**
+	 * Function to call to transform tokens for saving. The default is to trim the token value.
+	 * This function is also applied when matching suggestions against the current value
+	 * so that matching works correctly with leading or trailing spaces. (In the editor,
+	 * this is needed to remove leading and trailing spaces from tag names, like wp-admin does.
+	 * Otherwise the REST API won't save them.)
+	 *
+	 * @default ( token: string ) => token.trim()
+	 */
+	saveTransform?: ( token: string ) => string;
+	/**
+	 * Function to call when the tokens have changed. An array of new tokens is passed to the callback.
+	 *
+	 */
+	onChange?: ( tokens: ( string | TokenItem )[] ) => void;
+	/**
+	 * Function to call when the users types in the input field. It can be used to trigger autocomplete requests.
+	 *
+	 */
+	onInputChange?: ( input: string ) => void;
+	/**
+	 * Function to call when the TokenField has been focused on. The event is passed to the callback. Useful for analytics.
+	 *
+	 */
+	onFocus?: ( event: FocusEvent ) => void;
+	/**
+	 *  When true, renders tokens as without a background.
+	 */
+	isBorderless?: boolean;
+	/**
+	 * If passed, `TokenField` will disable ability to add new tokens once number of tokens is greater than or equal to `maxLength`.
+	 */
+	maxLength?: number;
+	/**
+	 * When true, tokens are not able to be added or removed.
+	 */
+	disabled?: boolean;
+	/**
+	 * If passed, the `TokenField` input will show a placeholder string if no value tokens are present.
+	 */
+	placeholder?: string;
+	/**
+	 * If true, will add a token when `TokenField` is focused and `space` is pressed.
+	 */
+	tokenizeOnSpace?: boolean;
+	/**
+	 * Allows customizing the messages presented by screen readers in different occasions:
+	 *
+	 * -   `added`: The user added a new token.
+	 * -   `removed`: The user removed an existing token.
+	 * -   `remove` : The user focused the button to remove the token.
+	 * -   `__experimentalInvalid`: The user tried to add a token that didn't pass the validation.
+	 */
+	messages?: Messages;
+	/**
+	 * If true, the suggestions list will be always expanded when the input field has the focus.
+	 */
+	__experimentalExpandOnFocus?: boolean;
+	/**
+	 * If passed, all introduced values will be validated before being added as tokens.
+	 *
+	 * @default () => true
+	 */
+	__experimentalValidateInput?: ( token: string ) => boolean;
+	/**
+	 * If false, the text on how to use the select (ie: _Separate with commas or the Enter key._) will be hidden.
+	 *
+	 * @default true
+	 */
+	__experimentalShowHowTo?: boolean;
+}
+
+export interface SuggestionsListProps< T = string | { value: string } > {
+	selectedIndex: number;
+	scrollIntoView: boolean;
+	match: T;
+	onHover: ( suggestion: T ) => void;
+	onSelect: ( suggestion: T ) => void;
+	suggestions: T[];
+	displayTransform: ( value: T ) => string;
+	instanceId: string | number;
+}
+
+export interface TokenProps extends TokenItem {
+	displayTransform: ( value: string ) => string;
+	disabled: boolean;
+	onClickRemove: ( { value }: { value: string } ) => void;
+	messages: Messages;
+	termPosition: number;
+	termsCount: number;
+}
+
+export interface TokenInputProps {
+	isExpanded: boolean;
+	instanceId: string | number;
+	selectedSuggestionIndex: number;
+	onChange?: ( { value }: { value: string } ) => void;
+	value: string;
+}

package/src/gradient-picker/index.js

@@ -108,9 +108,10 @@ export default function GradientPicker( {
 	__experimentalHasMultipleOrigins,
 	__experimentalIsRenderedInSidebar,
 } ) {
-	const clearGradient = useCallback( () => onChange( undefined ), [
-		onChange,
-	] );
+	const clearGradient = useCallback(
+		() => onChange( undefined ),
+		[ onChange ]
+	);
 	const Component =
 		__experimentalHasMultipleOrigins && gradients?.length
 			? MultipleOrigin

package/src/heading/hook.ts

@@ -51,10 +51,11 @@ export interface HeadingProps extends Omit< TextProps, 'size' > {
 export function useHeading(
 	props: WordPressComponentProps< HeadingProps, 'h1' >
 ) {
-	const { as: asProp, level = 2, ...otherProps } = useContextSystem(
-		props,
-		'Heading'
-	);
+	const {
+		as: asProp,
+		level = 2,
+		...otherProps
+	} = useContextSystem( props, 'Heading' );
 
 	const as = ( asProp || `h${ level }` ) as keyof JSX.IntrinsicElements;
 

package/src/higher-order/navigate-regions/index.js

@@ -95,10 +95,12 @@ export function useNavigateRegions( shortcuts = defaultShortcuts ) {
 }
 
 export default createHigherOrderComponent(
-	( Component ) => ( { shortcuts, ...props } ) => (
-		<div { ...useNavigateRegions( shortcuts ) }>
-			<Component { ...props } />
-		</div>
-	),
+	( Component ) =>
+		( { shortcuts, ...props } ) =>
+			(
+				<div { ...useNavigateRegions( shortcuts ) }>
+					<Component { ...props } />
+				</div>
+			),
 	'navigateRegions'
 );

package/src/higher-order/with-filters/test/index.js

@@ -81,12 +81,13 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-compose',
-			( FilteredComponent ) => () => (
-				<div>
-					<FilteredComponent />
-					<ComposedComponent />
-				</div>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<div>
+						<FilteredComponent />
+						<ComposedComponent />
+					</div>
+				)
 		);
 		const EnhancedComponent = withFilters( hookName )( MyComponent );
 
@@ -106,11 +107,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		const EnhancedComponent = withFilters( hookName )( SpiedComponent );
 
@@ -143,11 +145,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		jest.runAllTimers();
 
@@ -174,20 +177,22 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-2',
-			( FilteredComponent ) => () => (
-				<section>
-					<FilteredComponent />
-				</section>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<section>
+						<FilteredComponent />
+					</section>
+				)
 		);
 		jest.runAllTimers();
 
@@ -213,11 +218,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy',
-			( FilteredComponent ) => () => (
-				<div>
-					<FilteredComponent />
-				</div>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<div>
+						<FilteredComponent />
+					</div>
+				)
 		);
 		jest.runAllTimers();
 
@@ -249,11 +255,12 @@ describe( 'withFilters', () => {
 		addFilter(
 			hookName,
 			'test/enhanced-component-spy-1',
-			( FilteredComponent ) => () => (
-				<blockquote>
-					<FilteredComponent />
-				</blockquote>
-			)
+			( FilteredComponent ) => () =>
+				(
+					<blockquote>
+						<FilteredComponent />
+					</blockquote>
+				)
 		);
 		jest.runAllTimers();
 

package/src/higher-order/with-focus-return/index.js

@@ -31,18 +31,20 @@ function isComponentLike( object ) {
  * @return {Function} Higher Order Component with the focus restauration behaviour.
  */
 export default createHigherOrderComponent( ( options ) => {
-	const HoC = ( { onFocusReturn } = {} ) => ( WrappedComponent ) => {
-		const WithFocusReturn = ( props ) => {
-			const ref = useFocusReturn( onFocusReturn );
-			return (
-				<div ref={ ref }>
-					<WrappedComponent { ...props } />
-				</div>
-			);
-		};
+	const HoC =
+		( { onFocusReturn } = {} ) =>
+		( WrappedComponent ) => {
+			const WithFocusReturn = ( props ) => {
+				const ref = useFocusReturn( onFocusReturn );
+				return (
+					<div ref={ ref }>
+						<WrappedComponent { ...props } />
+					</div>
+				);
+			};
 
-		return WithFocusReturn;
-	};
+			return WithFocusReturn;
+		};
 
 	if ( isComponentLike( options ) ) {
 		const WrappedComponent = options;
@@ -55,8 +57,7 @@ export default createHigherOrderComponent( ( options ) => {
 export const Provider = ( { children } ) => {
 	deprecated( 'wp.components.FocusReturnProvider component', {
 		since: '5.7',
-		hint:
-			'This provider is not used anymore. You can just remove it from your codebase',
+		hint: 'This provider is not used anymore. You can just remove it from your codebase',
 	} );
 
 	return children;

package/src/higher-order/with-spoken-messages/index.js

@@ -15,12 +15,13 @@ import { speak } from '@wordpress/a11y';
  * @return {WPComponent} The wrapped component.
  */
 export default createHigherOrderComponent(
-	( Component ) => ( props ) => (
-		<Component
-			{ ...props }
-			speak={ speak }
-			debouncedSpeak={ useDebounce( speak, 500 ) }
-		/>
-	),
+	( Component ) => ( props ) =>
+		(
+			<Component
+				{ ...props }
+				speak={ speak }
+				debouncedSpeak={ useDebounce( speak, 500 ) }
+			/>
+		),
 	'withSpokenMessages'
 );

package/src/higher-order/with-spoken-messages/test/index.js

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import { render } from 'enzyme';
-import { isFunction } from 'lodash';
 
 /**
  * Internal dependencies
@@ -13,6 +12,7 @@ describe( 'withSpokenMessages', () => {
 	it( 'should generate speak and debouncedSpeak props', () => {
 		const testSpeak = jest.fn();
 		const testDebouncedSpeak = jest.fn();
+		const isFunction = ( maybeFunc ) => typeof maybeFunc === 'function';
 		const DumpComponent = withSpokenMessages(
 			( { speak, debouncedSpeak } ) => {
 				testSpeak( isFunction( speak ) );

package/src/icon/index.tsx

@@ -68,10 +68,10 @@ function Icon< P >( {
 
 	if ( 'function' === typeof icon ) {
 		if ( icon.prototype instanceof Component ) {
-			return createElement( icon, ( {
+			return createElement( icon, {
 				size,
 				...additionalProps,
-			} as unknown ) as P );
+			} as unknown as P );
 		}
 
 		return ( icon as ( ...args: any[] ) => JSX.Element )( {

package/src/index.js

@@ -71,7 +71,6 @@ export { DuotoneSwatch, DuotonePicker } from './duotone-picker';
 export { Elevation as __experimentalElevation } from './elevation';
 export { default as ExternalLink } from './external-link';
 export { Flex, FlexBlock, FlexItem } from './flex';
-export { Flyout as __experimentalFlyout } from './flyout';
 export { default as FocalPointPicker } from './focal-point-picker';
 export { default as FocusableIframe } from './focusable-iframe';
 export { default as FontSizePicker } from './font-size-picker';

package/src/index.native.js

@@ -61,6 +61,7 @@ export {
 	filterUnitsWithSettings as filterUnitsWithSettings,
 } from './unit-control/utils';
 export { default as Disabled } from './disabled';
+export { default as Draggable, DraggableTrigger } from './draggable';
 
 // Higher-Order Components.
 export { default as withConstrainedTabbing } from './higher-order/with-constrained-tabbing';

package/src/input-control/index.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { noop } from 'lodash';
 import classNames from 'classnames';
 import type { ForwardedRef } from 'react';
 
@@ -17,6 +16,9 @@ import { useState, forwardRef } from '@wordpress/element';
 import InputBase from './input-base';
 import InputField from './input-field';
 import type { InputControlProps } from './types';
+import { useDraft } from './utils';
+
+const noop = () => {};
 
 function useUniqueId( idProp?: string ) {
 	const instanceId = useInstanceId( InputControl );
@@ -52,6 +54,12 @@ export function UnforwardedInputControl(
 	const id = useUniqueId( idProp );
 	const classes = classNames( 'components-input-control', className );
 
+	const draftHookProps = useDraft( {
+		value,
+		onBlur: props.onBlur,
+		onChange,
+	} );
+
 	return (
 		<InputBase
 			__unstableInputWidth={ __unstableInputWidth }
@@ -75,14 +83,13 @@ export function UnforwardedInputControl(
 				id={ id }
 				isFocused={ isFocused }
 				isPressEnterToChange={ isPressEnterToChange }
-				onChange={ onChange }
 				onKeyDown={ onKeyDown }
 				onValidate={ onValidate }
 				ref={ ref }
 				setIsFocused={ setIsFocused }
 				size={ size }
 				stateReducer={ stateReducer }
-				value={ value }
+				{ ...draftHookProps }
 			/>
 		</InputBase>
 	);

package/src/input-control/input-field.tsx

@@ -1,7 +1,6 @@
 /**
  * External dependencies
  */
-import { noop } from 'lodash';
 import { useDrag } from '@use-gesture/react';
 import type {
 	SyntheticEvent,
@@ -24,9 +23,10 @@ import type { WordPressComponentProps } from '../ui/context';
 import { useDragCursor } from './utils';
 import { Input } from './styles/input-control-styles';
 import { useInputControlStateReducer } from './reducer/reducer';
-import { useUpdateEffect } from '../utils';
 import type { InputFieldProps } from './types';
 
+const noop = () => {};
+
 function InputField(
 	{
 		disabled = false,
@@ -67,40 +67,21 @@ function InputField(
 		pressEnter,
 		pressUp,
 		reset,
-	} = useInputControlStateReducer( stateReducer, {
-		isDragEnabled,
-		value: valueProp,
-		isPressEnterToChange,
-	} );
+	} = useInputControlStateReducer(
+		stateReducer,
+		{
+			isDragEnabled,
+			value: valueProp,
+			isPressEnterToChange,
+		},
+		onChange
+	);
 
-	const { _event, value, isDragging, isDirty } = state;
+	const { value, isDragging, isDirty } = state;
 	const wasDirtyOnBlur = useRef( false );
 
 	const dragCursor = useDragCursor( isDragging, dragDirection );
 
-	/*
-	 * Handles synchronization of external and internal value state.
-	 * If not focused and did not hold a dirty value[1] on blur
-	 * updates the value from the props. Otherwise if not holding
-	 * a dirty value[1] propagates the value and event through onChange.
-	 * [1] value is only made dirty if isPressEnterToChange is true
-	 */
-	useUpdateEffect( () => {
-		if ( valueProp === value ) {
-			return;
-		}
-		if ( ! isFocused && ! wasDirtyOnBlur.current ) {
-			commit( valueProp, _event as SyntheticEvent );
-		} else if ( ! isDirty ) {
-			onChange( value, {
-				event: _event as
-					| ChangeEvent< HTMLInputElement >
-					| PointerEvent< HTMLInputElement >,
-			} );
-			wasDirtyOnBlur.current = false;
-		}
-	}, [ value, isDirty, isFocused, valueProp ] );
-
 	const handleOnBlur = ( event: FocusEvent< HTMLInputElement > ) => {
 		onBlur( event );
 		setIsFocused?.( false );