WordPress · ciampo · Mar 1, 2023 · Jan 23, 2023 · Jan 23, 2023 · Jan 23, 2023
@@ -12,6 +12,8 @@
 -   `TabPanel`: Improve unit test in preparation for controlled component updates ([#48086](https://github.com/WordPress/gutenberg/pull/48086)).
 -   `Autocomplete`: performance: avoid setting state on every value change ([#48485](https://github.com/WordPress/gutenberg/pull/48485)).
 -   `Higher Order` -- `with-constrained-tabbing`: Convert to TypeScript ([#48162](https://github.com/WordPress/gutenberg/pull/48162)).
+-   `Autocomplete`: Convert to TypeScript ([#47751](https://github.com/WordPress/gutenberg/pull/47751)).
+-   `Autocomplete`: avoid calling setState on input ([#48565](https://github.com/WordPress/gutenberg/pull/48565)).
 
 ## 23.4.0 (2023-02-15)
 

@@ -2,6 +2,57 @@
 
 This component is used to provide autocompletion support for a child input component.
 
+## Props
+
+The following props are used to control the behavior of the component.
+
+### record
+
+The rich text value object the autocomleter is being applied to.
+
+-   Required: Yes
+-   Type: `RichTextValue`
+
+### onChange
+
+A function to be called when an option is selected to insert into the existing text.
+
+-   Required: Yes
+-   Type: `( value: string ) => void`
+
+A function to be called when an option is selected to replace the existing text.
+
+-   Required: Yes
+-   Type: `( arg: [ OptionCompletion[ 'value' ] ] ) => void;`
+
+### completers
+
+An array of all of the completers to apply to the current element.
+
+-   Required: Yes
+-   Type: `Array< WPCompleter >`
+
+### contentRef
+
+A ref containing the editable element that will serve as the anchor for `Autocomplete`'s `Popover`.
+
+-   Required: Yes
+-   `MutableRefObject< HTMLElement | undefined >`
+
+### children
+
+A function that returns nodes to be rendered within the Autocomplete.
+
+-   Required: Yes
+-   Type: `Function`
+
+### isSelected
+
+Whether or not the Autocomplte componenet is selected, and if its `Popover` should be displayed.
+
+- Required: Yes
+- Type: `Boolean`
+
 ## Autocompleters
 
 Autocompleters enable us to offer users options for completing text input. For example, Gutenberg includes a user autocompleter that provides a list of user names and completes a selection with a user mention like `@mary`.

@@ -12,6 +12,8 @@ import {
 	useEffect,
 	useState,
 } from '@wordpress/element';
+// Error expected because `@wordpress/rich-text` is not yet fully typed.
+// @ts-expect-error
 import { useAnchor } from '@wordpress/rich-text';
 import { useMergeRefs, useRefEffect } from '@wordpress/compose';
 
@@ -23,8 +25,9 @@ import Button from '../button';
 import Popover from '../popover';
 import { VisuallyHidden } from '../visually-hidden';
 import { createPortal } from 'react-dom';
+import type { AutocompleterUIProps, WPCompleter } from './types';
 
-export function getAutoCompleterUI( autocompleter ) {
+export function getAutoCompleterUI( autocompleter: WPCompleter ) {
 	const useItems = autocompleter.useItems
 		? autocompleter.useItems
 		: getDefaultUseItems( autocompleter );
@@ -41,15 +44,15 @@ export function getAutoCompleterUI( autocompleter ) {
 		reset,
 		value,
 		contentRef,
-	} ) {
+	}: AutocompleterUIProps ) {
 		const [ items ] = useItems( filterValue );
 		const popoverAnchor = useAnchor( {
 			editableContentElement: contentRef.current,
 			value,
 		} );
 
 		const [ needsA11yCompat, setNeedsA11yCompat ] = useState( false );
-		const popoverRef = useRef();
+		const popoverRef = useRef< HTMLElement >( null );
 		const popoverRefs = useMergeRefs( [
 			popoverRef,
 			useRefEffect(
@@ -77,11 +80,15 @@ export function getAutoCompleterUI( autocompleter ) {
 			// eslint-disable-next-line react-hooks/exhaustive-deps
 		}, [ items ] );
 
-		if ( ! items.length > 0 ) {
+		if ( items.length === 0 ) {
 			return null;
 		}
 
-		const ListBox = ( { Component = 'div' } ) => (
+		const ListBox = ( {
+			Component = 'div',
+		}: {
+			Component?: React.ElementType;
+		} ) => (
 			<Component
 				id={ listBoxId }
 				role="listbox"
@@ -134,11 +141,17 @@ export function getAutoCompleterUI( autocompleter ) {
 	return AutocompleterUI;
 }
 
-function useOnClickOutside( ref, handler ) {
+function useOnClickOutside(
+	ref: React.RefObject< HTMLElement >,
+	handler: AutocompleterUIProps[ 'reset' ]
+) {
 	useEffect( () => {
-		const listener = ( event ) => {
+		const listener = ( event: MouseEvent | TouchEvent ) => {
 			// Do nothing if clicking ref's element or descendent elements, or if the ref is not referencing an element
-			if ( ! ref.current || ref.current.contains( event.target ) ) {
+			if (
+				! ref.current ||
+				ref.current.contains( event.target as Node )
+			) {
 				return;
 			}
 			handler( event );

@@ -13,8 +13,13 @@ import { useLayoutEffect, useState } from '@wordpress/element';
  * Internal dependencies
  */
 import { escapeRegExp } from '../utils/strings';
+import type { CancelablePromise, KeyedOption, WPCompleter } from './types';
 
-function filterOptions( search, options = [], maxResults = 10 ) {
+function filterOptions(
+	search: RegExp,
+	options: Array< KeyedOption > = [],
+	maxResults = 10
+) {
 	const filtered = [];
 	for ( let i = 0; i < options.length; i++ ) {
 		const option = options[ i ];
@@ -43,9 +48,9 @@ function filterOptions( search, options = [], maxResults = 10 ) {
 	return filtered;
 }
 
-export default function getDefaultUseItems( autocompleter ) {
-	return ( filterValue ) => {
-		const [ items, setItems ] = useState( [] );
+export default function getDefaultUseItems( autocompleter: WPCompleter ) {
+	return ( filterValue: string ) => {
+		const [ items, setItems ] = useState< Array< KeyedOption > >( [] );
 		/*
 		 * We support both synchronous and asynchronous retrieval of completer options
 		 * but internally treat all as async so we maintain a single, consistent code path.
@@ -61,7 +66,7 @@ export default function getDefaultUseItems( autocompleter ) {
 			const { options, isDebounced } = autocompleter;
 			const loadOptions = debounce(
 				() => {
-					const promise = Promise.resolve(
+					const promise: CancelablePromise = Promise.resolve(
 						typeof options === 'function'
 							? options( filterValue )
 							: options
@@ -112,6 +117,6 @@ export default function getDefaultUseItems( autocompleter ) {
 			};
 		}, [ filterValue ] );
 
-		return [ items ];
+		return [ items ] as const;
 	};
 }