@wordpress/components 23.4.0 → 23.6.0

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

@@ -26,6 +26,8 @@ import {
 	insert,
 	isCollapsed,
 	getTextContent,
+	// Error expected because `@wordpress/rich-text` is not yet fully typed.
+	// @ts-expect-error
 } from '@wordpress/rich-text';
 import { speak } from '@wordpress/a11y';
 
@@ -34,100 +36,48 @@ import { speak } from '@wordpress/a11y';
  */
 import { getAutoCompleterUI } from './autocompleter-ui';
 import { escapeRegExp } from '../utils/strings';
-
-/**
- * A raw completer option.
- *
- * @typedef {*} CompleterOption
- */
-
-/**
- * @callback FnGetOptions
- *
- * @return {(CompleterOption[]|Promise.<CompleterOption[]>)} The completer options or a promise for them.
- */
-
-/**
- * @callback FnGetOptionKeywords
- * @param {CompleterOption} option a completer option.
- *
- * @return {string[]} list of key words to search.
- */
-
-/**
- * @callback FnIsOptionDisabled
- * @param {CompleterOption} option a completer option.
- *
- * @return {string[]} whether or not the given option is disabled.
- */
-
-/**
- * @callback FnGetOptionLabel
- * @param {CompleterOption} option a completer option.
- *
- * @return {(string|Array.<(string|WPElement)>)} list of react components to render.
- */
-
-/**
- * @callback FnAllowContext
- * @param {string} before the string before the auto complete trigger and query.
- * @param {string} after  the string after the autocomplete trigger and query.
- *
- * @return {boolean} true if the completer can handle.
- */
-
-/**
- * @typedef {Object} OptionCompletion
- * @property {'insert-at-caret'|'replace'} action the intended placement of the completion.
- * @property {OptionCompletionValue}       value  the completion value.
- */
-
-/**
- * A completion value.
- *
- * @typedef {(string|WPElement|Object)} OptionCompletionValue
- */
-
-/**
- * @callback FnGetOptionCompletion
- * @param {CompleterOption} value the value of the completer option.
- * @param {string}          query the text value of the autocomplete query.
- *
- * @return {(OptionCompletion|OptionCompletionValue)} the completion for the given option. If an
- * 													   OptionCompletionValue is returned, the
- * 													   completion action defaults to `insert-at-caret`.
- */
-
-/**
- * @typedef {Object} WPCompleter
- * @property {string}                           name                a way to identify a completer, useful for selective overriding.
- * @property {?string}                          className           A class to apply to the popup menu.
- * @property {string}                           triggerPrefix       the prefix that will display the menu.
- * @property {(CompleterOption[]|FnGetOptions)} options             the completer options or a function to get them.
- * @property {?FnGetOptionKeywords}             getOptionKeywords   get the keywords for a given option.
- * @property {?FnIsOptionDisabled}              isOptionDisabled    get whether or not the given option is disabled.
- * @property {FnGetOptionLabel}                 getOptionLabel      get the label for a given option.
- * @property {?FnAllowContext}                  allowContext        filter the context under which the autocomplete activates.
- * @property {FnGetOptionCompletion}            getOptionCompletion get the completion associated with a given option.
- */
-
-function useAutocomplete( {
+import type {
+	AutocompleteProps,
+	AutocompleterUIProps,
+	InsertOption,
+	KeyedOption,
+	OptionCompletion,
+	ReplaceOption,
+	UseAutocompleteProps,
+	WPCompleter,
+} from './types';
+
+const EMPTY_FILTERED_OPTIONS: KeyedOption[] = [];
+
+export function useAutocomplete( {
 	record,
 	onChange,
 	onReplace,
 	completers,
 	contentRef,
-} ) {
+}: UseAutocompleteProps ) {
 	const debouncedSpeak = useDebounce( speak, 500 );
 	const instanceId = useInstanceId( useAutocomplete );
 	const [ selectedIndex, setSelectedIndex ] = useState( 0 );
-	const [ filteredOptions, setFilteredOptions ] = useState( [] );
-	const [ filterValue, setFilterValue ] = useState( '' );
-	const [ autocompleter, setAutocompleter ] = useState( null );
-	const [ AutocompleterUI, setAutocompleterUI ] = useState( null );
+
+	const [ filteredOptions, setFilteredOptions ] = useState<
+		Array< KeyedOption >
+	>( EMPTY_FILTERED_OPTIONS );
+	const [ filterValue, setFilterValue ] =
+		useState< AutocompleterUIProps[ 'filterValue' ] >( '' );
+	const [ autocompleter, setAutocompleter ] = useState< WPCompleter | null >(
+		null
+	);
+	const [ AutocompleterUI, setAutocompleterUI ] = useState<
+		( ( props: AutocompleterUIProps ) => JSX.Element | null ) | null
+	>( null );
+
 	const backspacing = useRef( false );
 
-	function insertCompletion( replacement ) {
+	function insertCompletion( replacement: React.ReactNode ) {
+		if ( autocompleter === null ) {
+			return;
+		}
 		const end = record.start;
 		const start =
 			end - autocompleter.triggerPrefix.length - filterValue.length;
@@ -136,7 +86,7 @@ function useAutocomplete( {
 		onChange( insert( record, toInsert, start, end ) );
 	}
 
-	function select( option ) {
+	function select( option: KeyedOption ) {
 		const { getOptionCompletion } = autocompleter || {};
 
 		if ( option.isDisabled ) {
@@ -146,19 +96,33 @@ function useAutocomplete( {
 		if ( getOptionCompletion ) {
 			const completion = getOptionCompletion( option.value, filterValue );
 
-			const { action, value } =
-				undefined === completion.action ||
-				undefined === completion.value
-					? { action: 'insert-at-caret', value: completion }
-					: completion;
+			const isCompletionObject = (
+				obj: OptionCompletion
+			): obj is InsertOption | ReplaceOption => {
+				return (
+					obj !== null &&
+					typeof obj === 'object' &&
+					'action' in obj &&
+					obj.action !== undefined &&
+					'value' in obj &&
+					obj.value !== undefined
+				);
+			};
+
+			const completionObject = isCompletionObject( completion )
+				? completion
+				: ( {
+						action: 'insert-at-caret',
+						value: completion,
+				  } as InsertOption );
 
-			if ( 'replace' === action ) {
-				onReplace( [ value ] );
+			if ( 'replace' === completionObject.action ) {
+				onReplace( [ completionObject.value ] );
 				// When replacing, the component will unmount, so don't reset
 				// state (below) on an unmounted component.
 				return;
-			} else if ( 'insert-at-caret' === action ) {
-				insertCompletion( value );
+			} else if ( 'insert-at-caret' === completionObject.action ) {
+				insertCompletion( completionObject.value );
 			}
 		}
 
@@ -169,13 +133,13 @@ function useAutocomplete( {
 
 	function reset() {
 		setSelectedIndex( 0 );
-		setFilteredOptions( [] );
+		setFilteredOptions( EMPTY_FILTERED_OPTIONS );
 		setFilterValue( '' );
 		setAutocompleter( null );
 		setAutocompleterUI( null );
 	}
 
-	function announce( options ) {
+	function announce( options: Array< KeyedOption > ) {
 		if ( ! debouncedSpeak ) {
 			return;
 		}
@@ -202,7 +166,7 @@ function useAutocomplete( {
 	 *
 	 * @param {Array} options
 	 */
-	function onChangeOptions( options ) {
+	function onChangeOptions( options: Array< KeyedOption > ) {
 		setSelectedIndex(
 			options.length === filteredOptions.length ? selectedIndex : 0
 		);
@@ -210,7 +174,7 @@ function useAutocomplete( {
 		announce( options );
 	}
 
-	function handleKeyDown( event ) {
+	function handleKeyDown( event: KeyboardEvent ) {
 		backspacing.current = event.key === 'Backspace';
 
 		if ( ! autocompleter ) {
@@ -281,23 +245,19 @@ function useAutocomplete( {
 
 	useEffect( () => {
 		if ( ! textContent ) {
-			reset();
+			if ( autocompleter ) reset();
 			return;
 		}
 
-		const text = removeAccents( textContent );
-		const textAfterSelection = getTextContent(
-			slice( record, undefined, getTextContent( record ).length )
-		);
 		const completer = completers?.find(
 			( { triggerPrefix, allowContext } ) => {
-				const index = text.lastIndexOf( triggerPrefix );
+				const index = textContent.lastIndexOf( triggerPrefix );
 
 				if ( index === -1 ) {
 					return false;
 				}
 
-				const textWithoutTrigger = text.slice(
+				const textWithoutTrigger = textContent.slice(
 					index + triggerPrefix.length
 				);
 
@@ -339,9 +299,16 @@ function useAutocomplete( {
 					return false;
 				}
 
+				const textAfterSelection = getTextContent(
+					slice( record, undefined, getTextContent( record ).length )
+				);
+
 				if (
 					allowContext &&
-					! allowContext( text.slice( 0, index ), textAfterSelection )
+					! allowContext(
+						textContent.slice( 0, index ),
+						textAfterSelection
+					)
 				) {
 					return false;
 				}
@@ -358,11 +325,12 @@ function useAutocomplete( {
 		);
 
 		if ( ! completer ) {
-			reset();
+			if ( autocompleter ) reset();
 			return;
 		}
 
 		const safeTrigger = escapeRegExp( completer.triggerPrefix );
+		const text = removeAccents( textContent );
 		const match = text
 			.slice( text.lastIndexOf( completer.triggerPrefix ) )
 			.match( new RegExp( `${ safeTrigger }([\u0000-\uFFFF]*)$` ) );
@@ -374,7 +342,7 @@ function useAutocomplete( {
 				? getAutoCompleterUI( completer )
 				: AutocompleterUI
 		);
-		setFilterValue( query );
+		setFilterValue( query === null ? '' : query );
 		// Temporarily disabling exhaustive-deps to avoid introducing unexpected side effecst.
 		// See https://github.com/WordPress/gutenberg/pull/41820
 		// eslint-disable-next-line react-hooks/exhaustive-deps
@@ -385,7 +353,7 @@ function useAutocomplete( {
 	const isExpanded = !! autocompleter && filteredOptions.length > 0;
 	const listBoxId = isExpanded
 		? `components-autocomplete-listbox-${ instanceId }`
-		: null;
+		: undefined;
 	const activeId = isExpanded
 		? `components-autocomplete-item-${ instanceId }-${ selectedKey }`
 		: null;
@@ -412,53 +380,47 @@ function useAutocomplete( {
 	};
 }
 
-export function useAutocompleteProps( options ) {
-	const [ isVisible, setIsVisible ] = useState( false );
-	const ref = useRef();
-	const recordAfterInput = useRef();
-	const onKeyDownRef = useRef();
+function useLastDifferentValue( value: UseAutocompleteProps[ 'record' ] ) {
+	const history = useRef< Set< typeof value > >( new Set() );
+
+	history.current.add( value );
+
+	// Keep the history size to 2.
+	if ( history.current.size > 2 ) {
+		history.current.delete( Array.from( history.current )[ 0 ] );
+	}
+
+	return Array.from( history.current )[ 0 ];
+}
+
+export function useAutocompleteProps( options: UseAutocompleteProps ) {
+	const ref = useRef< HTMLElement >( null );
+	const onKeyDownRef = useRef< ( event: KeyboardEvent ) => void >();
+	const { record } = options;
+	const previousRecord = useLastDifferentValue( record );
 	const { popover, listBoxId, activeId, onKeyDown } = useAutocomplete( {
 		...options,
 		contentRef: ref,
 	} );
 	onKeyDownRef.current = onKeyDown;
 
-	useEffect( () => {
-		if ( isVisible ) {
-			if ( ! recordAfterInput.current ) {
-				recordAfterInput.current = options.record;
-			} else if (
-				recordAfterInput.current.start !== options.record.start ||
-				recordAfterInput.current.end !== options.record.end
-			) {
-				setIsVisible( false );
-				recordAfterInput.current = null;
-			}
-		}
-		// eslint-disable-next-line react-hooks/exhaustive-deps
-	}, [ options.record ] );
-
 	const mergedRefs = useMergeRefs( [
 		ref,
-		useRefEffect( ( element ) => {
-			function _onKeyDown( event ) {
-				onKeyDownRef.current( event );
-			}
-			function _onInput() {
-				// Only show auto complete UI if the user is inputting text.
-				setIsVisible( true );
-				recordAfterInput.current = null;
+		useRefEffect( ( element: HTMLElement ) => {
+			function _onKeyDown( event: KeyboardEvent ) {
+				onKeyDownRef.current?.( event );
 			}
 			element.addEventListener( 'keydown', _onKeyDown );
-			element.addEventListener( 'input', _onInput );
 			return () => {
 				element.removeEventListener( 'keydown', _onKeyDown );
-				element.removeEventListener( 'input', _onInput );
 			};
 		}, [] ),
 	] );
 
-	if ( ! isVisible ) {
+	// We only want to show the popover if the user has typed something.
+	const didUserInput = record.text !== previousRecord?.text;
+
+	if ( ! didUserInput ) {
 		return { ref: mergedRefs };
 	}
 
@@ -471,7 +433,11 @@ export function useAutocompleteProps( options ) {
 	};
 }
 
-export default function Autocomplete( { children, isSelected, ...options } ) {
+export default function Autocomplete( {
+	children,
+	isSelected,
+	...options
+}: AutocompleteProps ) {
 	const { popover, ...props } = useAutocomplete( options );
 	return (
 		<>

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

@@ -14,6 +14,8 @@ import { useRef } from '@wordpress/element';
  */
 import { getAutoCompleterUI } from '../autocompleter-ui';
 
+type FruitOption = { visual: string; name: string; id: number };
+
 describe( 'AutocompleterUI', () => {
 	describe( 'click outside behavior', () => {
 		it( 'should call reset function when a click on another element occurs', async () => {
@@ -23,25 +25,35 @@ describe( 'AutocompleterUI', () => {
 
 			const autocompleter = {
 				name: 'fruit',
+				options: [
+					{ visual: '🍎', name: 'Apple', id: 1 },
+					{ visual: '🍊', name: 'Orange', id: 2 },
+					{ visual: '🍇', name: 'Grapes', id: 3 },
+				],
 				// The prefix that triggers this completer
 				triggerPrefix: '~',
+				getOptionLabel: ( option: FruitOption ) => (
+					<span>
+						<span className="icon">{ option.visual }</span>
+						{ option.name }
+					</span>
+				),
 				// Mock useItems function to return a autocomplete item.
-				useItems: () => {
-					return [
-						[
-							{
-								isDisabled: false,
-								key: 'Apple',
-								value: 'Apple',
-								label: (
-									<span>
-										<span className="icon">🍎</span>
-										{ 'Apple' }
-									</span>
-								),
-							},
-						],
-					];
+				useItems: ( filterValue: string ) => {
+					const options = autocompleter.options;
+					const keyedOptions = options.map(
+						( optionData, optionIndex ) => ( {
+							key: `${ autocompleter.name }-${ optionIndex }`,
+							value: optionData,
+							label: autocompleter.getOptionLabel( optionData ),
+							keywords: [],
+							isDisabled: false,
+						} )
+					);
+					const filteredOptions = keyedOptions.filter( ( option ) =>
+						option.value.name.includes( filterValue )
+					);
+					return [ filteredOptions ] as const;
 				},
 			};
 
@@ -50,19 +62,18 @@ describe( 'AutocompleterUI', () => {
 			const OtherElement = <div>Other Element</div>;
 
 			const Container = () => {
-				const contentRef = useRef();
+				const contentRef = useRef< HTMLElement >( null );
 
 				return (
 					<div>
 						<AutocompleterUI
 							className={ 'test' }
-							filterValue={ '~' }
-							instanceId={ '1' }
+							filterValue={ 'Apple' }
+							instanceId={ 1 }
 							listBoxId={ '1' }
 							selectedIndex={ 0 }
 							onChangeOptions={ () => {} }
 							onSelect={ () => {} }
-							value={ { visual: '🍎', name: 'Apple', id: 1 } }
 							contentRef={ contentRef }
 							reset={ resetSpy }
 						/>

package/src/autocomplete/types.ts

@@ -0,0 +1,220 @@
+/**
+ * WordPress dependencies
+ */
+import type { WPElement } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import type { useAutocomplete } from '.';
+
+// Insert the `value` into the text.
+export type InsertOption = {
+	action: 'insert-at-caret';
+	value: React.ReactNode;
+};
+
+// Replace the current block with the block specified in the `value` property
+export type ReplaceOption = { action: 'replace'; value: RichTextValue };
+
+export type OptionCompletion = React.ReactNode | InsertOption | ReplaceOption;
+
+type OptionLabel = string | WPElement | Array< string | WPElement >;
+export type KeyedOption = {
+	key: string;
+	value: any;
+	label: OptionLabel;
+	keywords: Array< string >;
+	isDisabled: boolean;
+};
+
+export type WPCompleter< TCompleterOption = any > = {
+	/**
+	 * The name of the completer. Useful for identifying a specific completer to
+	 * be overridden via extensibility hooks.
+	 */
+	name: string;
+	/**
+	 * The string prefix that should trigger the completer. For example,
+	 * Gutenberg's block completer is triggered when the '/' character is
+	 * entered.
+	 */
+	triggerPrefix: string;
+	/**
+	 * The raw options for completion. May be an array, a function that returns
+	 * an array, or a function that returns a promise for an array.
+	 * Options may be of any type or shape. The completer declares how those
+	 * options are rendered and what their completions should be when selected.
+	 */
+	options:
+		| ( (
+				query: string
+		  ) =>
+				| PromiseLike< readonly TCompleterOption[] >
+				| readonly TCompleterOption[] )
+		| readonly TCompleterOption[];
+	/**
+	 * A function that returns the keywords for the specified option.
+	 */
+	getOptionKeywords?: ( option: TCompleterOption ) => Array< string >;
+	/**
+	 * A function that returns whether or not the specified option is disabled.
+	 * Disabled options cannot be selected.
+	 */
+	isOptionDisabled?: ( option: TCompleterOption ) => boolean;
+	/**
+	 * A function that returns the label for a given option. A label may be a
+	 * string or a mixed array of strings, elements, and components.
+	 */
+	getOptionLabel: ( option: TCompleterOption ) => OptionLabel;
+	/**
+	 * A function that takes a Range before and a Range after the autocomplete
+	 * trigger and query text and returns a boolean indicating whether the
+	 * completer should be considered for that context.
+	 */
+	allowContext?: ( before: string, after: string ) => boolean;
+	/**
+	 * A function that takes an option and returns how the option should
+	 * be completed. By default, the result is a value to be inserted in the
+	 * text.
+	 * However, a completer may explicitly declare how a completion should be
+	 * treated by returning an object with `action` and `value` properties. The
+	 * `action` declares what should be done with the `value`.
+	 */
+	getOptionCompletion?: (
+		option: TCompleterOption,
+		query: string
+	) => OptionCompletion;
+	/**
+	 * A function that returns an array of items to be displayed in the
+	 * Autocomplete UI. These items have uniform shape and have been filtered by
+	 * `AutocompleterUIProps.filterValue`.
+	 */
+	useItems?: ( filterValue: string ) => readonly [ Array< KeyedOption > ];
+	/**
+	 * Whether or not changes to the `filterValue` should be debounced.
+	 */
+	isDebounced?: boolean;
+	/**
+	 * A CSS class name to be applied to the completion menu.
+	 */
+	className?: string;
+};
+
+type ContentRef = React.RefObject< HTMLElement >;
+
+export type AutocompleterUIProps = {
+	/**
+	 * The value to filter the options by.
+	 */
+	filterValue: string;
+	/**
+	 * An id unique to each instance of the component, used in the IDs of the
+	 * buttons generated for individual options.
+	 */
+	instanceId: number;
+	/**
+	 * The id of to be applied to the listbox of options.
+	 */
+	listBoxId: string | undefined;
+	/**
+	 * The class to apply to the wrapper element.
+	 */
+	className?: string;
+	/**
+	 * The index of the currently selected option.
+	 */
+	selectedIndex: number;
+	/**
+	 * A function to be called when the filterValue changes.
+	 */
+	onChangeOptions: ( items: Array< KeyedOption > ) => void;
+	/**
+	 * A function to be called when an option is selected.
+	 */
+	onSelect: ( option: KeyedOption ) => void;
+	/**
+	 * A function to be called when the completer is reset
+	 * (e.g. when the user hits the escape key).
+	 */
+	onReset?: () => void;
+	/**
+	 * A function that defines the behavior of the completer when it is reset
+	 */
+	reset: ( event: Event ) => void;
+	// This is optional because it's still needed for mobile/native.
+	/**
+	 * The rich text value object the autocompleter is being applied to.
+	 */
+	value?: RichTextValue;
+	/**
+	 * A ref containing the editable element that will serve as the anchor for
+	 * `Autocomplete`'s `Popover`.
+	 */
+	contentRef: ContentRef;
+};
+
+export type CancelablePromise< T = void > = Promise< T > & {
+	canceled?: boolean;
+};
+
+/**
+ * When `@wordpress/rich-text` is fully typed, the following
+ * types should be moved to and imported from there
+ *
+ * @see /packages/rich-text/src/create.js
+ */
+type RichTextFormat = {
+	type: string;
+};
+type RichTextFormatList = Array< RichTextFormat >;
+type RichTextValue = {
+	text: string;
+	formats?: Array< RichTextFormatList >;
+	replacements?: Array< RichTextFormat >;
+	start: number | undefined;
+	end: number | undefined;
+};
+
+export type UseAutocompleteProps = {
+	/**
+	 * The rich text value object the autocompleter is being applied to.
+	 */
+	record: RichTextValue & {
+		start: NonNullable< RichTextValue[ 'start' ] >;
+		end: NonNullable< RichTextValue[ 'end' ] >;
+	};
+	/**
+	 * A function to be called when an option is selected to insert into the
+	 * existing text.
+	 */
+	onChange: ( value: string ) => void;
+	/**
+	 * A function to be called when an option is selected to replace the
+	 * existing text.
+	 */
+	onReplace: ( values: RichTextValue[] ) => void;
+	/**
+	 * An array of all of the completers to apply to the current element.
+	 */
+	completers: Array< WPCompleter >;
+	/**
+	 * A ref containing the editable element that will serve as the anchor for
+	 * `Autocomplete`'s `Popover`.
+	 */
+	contentRef: ContentRef;
+};
+
+export type AutocompleteProps = UseAutocompleteProps & {
+	/**
+	 * A function that returns nodes to be rendered within the Autocomplete.
+	 */
+	children: (
+		props: Omit< ReturnType< typeof useAutocomplete >, 'popover' >
+	) => React.ReactNode;
+	/**
+	 * Whether or not the Autocomplte componenet is selected, and if its
+	 * `Popover`
+	 * should be displayed.
+	 */
+	isSelected: boolean;
+};