@wordpress/components 23.5.0 → 23.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "23.5.0",
+	"version": "23.6.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -37,24 +37,24 @@
 		"@emotion/styled": "^11.6.0",
 		"@emotion/utils": "^1.0.0",
 		"@floating-ui/react-dom": "1.0.0",
-		"@use-gesture/react": "^10.2.6",
-		"@wordpress/a11y": "^3.28.0",
-		"@wordpress/compose": "^6.5.0",
-		"@wordpress/date": "^4.28.0",
-		"@wordpress/deprecated": "^3.28.0",
-		"@wordpress/dom": "^3.28.0",
-		"@wordpress/element": "^5.5.0",
-		"@wordpress/escape-html": "^2.28.0",
-		"@wordpress/hooks": "^3.28.0",
-		"@wordpress/html-entities": "^3.28.0",
-		"@wordpress/i18n": "^4.28.0",
-		"@wordpress/icons": "^9.19.0",
-		"@wordpress/is-shallow-equal": "^4.28.0",
-		"@wordpress/keycodes": "^3.28.0",
-		"@wordpress/primitives": "^3.26.0",
-		"@wordpress/private-apis": "^0.10.0",
-		"@wordpress/rich-text": "^6.5.0",
-		"@wordpress/warning": "^2.28.0",
+		"@use-gesture/react": "^10.2.24",
+		"@wordpress/a11y": "^3.29.0",
+		"@wordpress/compose": "^6.6.0",
+		"@wordpress/date": "^4.29.0",
+		"@wordpress/deprecated": "^3.29.0",
+		"@wordpress/dom": "^3.29.0",
+		"@wordpress/element": "^5.6.0",
+		"@wordpress/escape-html": "^2.29.0",
+		"@wordpress/hooks": "^3.29.0",
+		"@wordpress/html-entities": "^3.29.0",
+		"@wordpress/i18n": "^4.29.0",
+		"@wordpress/icons": "^9.20.0",
+		"@wordpress/is-shallow-equal": "^4.29.0",
+		"@wordpress/keycodes": "^3.29.0",
+		"@wordpress/primitives": "^3.27.0",
+		"@wordpress/private-apis": "^0.11.0",
+		"@wordpress/rich-text": "^6.6.0",
+		"@wordpress/warning": "^2.29.0",
 		"change-case": "^4.1.2",
 		"classnames": "^2.3.1",
 		"colord": "^2.7.0",
@@ -85,5 +85,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "d5e03a74b79e3ca84afda24375474a103a063ee4"
+	"gitHead": "9534a7b3bbf07c1d40b94fdb7a3d091f297bfb06"
 }

package/src/animate/index.js

@@ -25,7 +25,7 @@ function getDefaultOrigin( type ) {
 /**
  * @param {GetAnimateOptions} options
  *
- * @return {string | void} ClassName that applies the animations
+ * @return {string | undefined} ClassName that applies the animations
  */
 export function getAnimateClassName( options ) {
 	if ( options.type === 'loading' ) {
@@ -48,6 +48,8 @@ export function getAnimateClassName( options ) {
 			'is-from-' + origin
 		);
 	}
+
+	return undefined;
 }
 
 // @ts-ignore Reason: Planned for deprecation

package/src/autocomplete/README.md

@@ -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`.

package/src/autocomplete/{autocompleter-ui.js → autocompleter-ui.tsx}

@@ -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 );
@@ -39,17 +42,15 @@ export function getAutoCompleterUI( autocompleter ) {
 		onSelect,
 		onReset,
 		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 +78,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 +139,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 );

package/src/autocomplete/{get-default-use-items.js → get-default-use-items.tsx}

@@ -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;
 	};
 }

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,102 +36,48 @@ import { speak } from '@wordpress/a11y';
  */
 import { getAutoCompleterUI } from './autocompleter-ui';
 import { escapeRegExp } from '../utils/strings';
-
-const EMPTY_ARRAY = [];
-
-/**
- * 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( EMPTY_ARRAY );
-	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;
@@ -138,7 +86,7 @@ function useAutocomplete( {
 		onChange( insert( record, toInsert, start, end ) );
 	}
 
-	function select( option ) {
+	function select( option: KeyedOption ) {
 		const { getOptionCompletion } = autocompleter || {};
 
 		if ( option.isDisabled ) {
@@ -148,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
+				);
+			};
 
-			if ( 'replace' === action ) {
-				onReplace( [ value ] );
+			const completionObject = isCompletionObject( completion )
+				? completion
+				: ( {
+						action: 'insert-at-caret',
+						value: completion,
+				  } as InsertOption );
+
+			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 );
 			}
 		}
 
@@ -171,13 +133,13 @@ function useAutocomplete( {
 
 	function reset() {
 		setSelectedIndex( 0 );
-		setFilteredOptions( EMPTY_ARRAY );
+		setFilteredOptions( EMPTY_FILTERED_OPTIONS );
 		setFilterValue( '' );
 		setAutocompleter( null );
 		setAutocompleterUI( null );
 	}
 
-	function announce( options ) {
+	function announce( options: Array< KeyedOption > ) {
 		if ( ! debouncedSpeak ) {
 			return;
 		}
@@ -204,7 +166,7 @@ function useAutocomplete( {
 	 *
 	 * @param {Array} options
 	 */
-	function onChangeOptions( options ) {
+	function onChangeOptions( options: Array< KeyedOption > ) {
 		setSelectedIndex(
 			options.length === filteredOptions.length ? selectedIndex : 0
 		);
@@ -212,7 +174,7 @@ function useAutocomplete( {
 		announce( options );
 	}
 
-	function handleKeyDown( event ) {
+	function handleKeyDown( event: KeyboardEvent ) {
 		backspacing.current = event.key === 'Backspace';
 
 		if ( ! autocompleter ) {
@@ -380,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
@@ -391,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;
@@ -418,8 +380,8 @@ function useAutocomplete( {
 	};
 }
 
-function useLastDifferentValue( value ) {
-	const history = useRef( new Set() );
+function useLastDifferentValue( value: UseAutocompleteProps[ 'record' ] ) {
+	const history = useRef< Set< typeof value > >( new Set() );
 
 	history.current.add( value );
 
@@ -431,9 +393,9 @@ function useLastDifferentValue( value ) {
 	return Array.from( history.current )[ 0 ];
 }
 
-export function useAutocompleteProps( options ) {
-	const ref = useRef();
-	const onKeyDownRef = useRef();
+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( {
@@ -444,9 +406,9 @@ export function useAutocompleteProps( options ) {
 
 	const mergedRefs = useMergeRefs( [
 		ref,
-		useRefEffect( ( element ) => {
-			function _onKeyDown( event ) {
-				onKeyDownRef.current( event );
+		useRefEffect( ( element: HTMLElement ) => {
+			function _onKeyDown( event: KeyboardEvent ) {
+				onKeyDownRef.current?.( event );
 			}
 			element.addEventListener( 'keydown', _onKeyDown );
 			return () => {
@@ -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 }
 						/>