@plaudit/gutenberg-api-extensions 2.79.0 → 2.80.0

package/src/controls/SortableFlexibleItemsControl.tsx

@@ -0,0 +1,35 @@
+import {Button, SelectControl} from "@wordpress/components";
+import {useCallback, useState} from "@wordpress/element";
+
+import {BaseSortableItemsControl, type BaseSortableItemsControlProps} from "./BaseSortableItemsControl";
+import type {NonEmptyArray} from "../lib/useful-types";
+import type {FlexibleItem} from "./types";
+
+import type {ReactNode} from "react";
+
+type SortableFlexibleItemsControlSpecificProps<T extends string> = {
+	availableTypes: NonEmptyArray<{label: string, value: T}>,
+	emptyValueBuilder: (type: T) => FlexibleItem<T>
+};
+export type SortableFlexibleItemsControl<T extends string> = Omit<BaseSortableItemsControlProps<FlexibleItem<T>>, 'buttonsArea'>&SortableFlexibleItemsControlSpecificProps<T>;
+export function SortableFlexibleItemsControl<T extends string>({availableTypes, emptyValueBuilder, ...baseProps}: SortableFlexibleItemsControl<T>) {
+	const buttonsArea = useCallback<BaseSortableItemsControlProps<FlexibleItem<T>>['buttonsArea']>(
+		// Unfortunately, the typedefs for React memo components don't allow us to properly check the emptyValueBuilder function
+		args => <ButtonsArea {...args} availableTypes={availableTypes} emptyValueBuilder={emptyValueBuilder} />, [availableTypes, emptyValueBuilder]);
+	return <BaseSortableItemsControl {...baseProps} buttonsArea={buttonsArea} />;
+}
+
+type ButtonsAreaProps<T extends string> = Parameters<BaseSortableItemsControlProps<FlexibleItem<T>>['buttonsArea']>[0]&SortableFlexibleItemsControlSpecificProps<T>;
+function ButtonsArea<T extends string>({addHandler, disabled, availableTypes, emptyValueBuilder}: ButtonsAreaProps<T>): ReactNode {
+	const [selectedType, setSelectedType] = useState(availableTypes[0].value);
+	return <div className="plaudit-sortable-items-buttons flexible-items">
+		<Button icon="insert" disabled={disabled} onClick={() => addHandler(emptyValueBuilder(selectedType))}>Add</Button>
+		<SelectControl
+			label="Type"
+			hideLabelFromVision={true}
+			value={selectedType}
+			options={availableTypes}
+			onChange={setSelectedType}
+		/>
+	</div>;
+}

package/src/controls/SortableItemsControl.tsx

@@ -0,0 +1,18 @@
+import {Button} from "@wordpress/components";
+import {useCallback} from "@wordpress/element";
+
+import {BaseSortableItemsControl, type BaseSortableItemsControlProps} from "./BaseSortableItemsControl";
+
+export type SortableItemsControlProps<D> = Omit<BaseSortableItemsControlProps<D>, 'buttonsArea'|'emptyValue'>&{emptyValue: D, addRowText?: string};
+export function SortableItemsControl<D>({emptyValue, addRowText, ...baseProps}: SortableItemsControlProps<D>) {
+	const buttonsArea = useCallback<BaseSortableItemsControlProps<D>['buttonsArea']>(
+		args => <ButtonsArea {...args} emptyValue={emptyValue} addRowText={addRowText} />, [emptyValue, addRowText]);
+	return <BaseSortableItemsControl {...baseProps} buttonsArea={buttonsArea} emptyValue={emptyValue} />;
+}
+
+type ButtonsAreaProps<D = any> = Parameters<BaseSortableItemsControlProps<D>['buttonsArea']>[0]&{emptyValue: D, addRowText?: string};
+function ButtonsArea<D>({addHandler, disabled, emptyValue, addRowText}: ButtonsAreaProps<D>) {
+	return <div className="plaudit-sortable-items-buttons">
+		<Button icon="insert" disabled={disabled} onClick={() => addHandler(typeof emptyValue === 'object' ? {...emptyValue} : emptyValue)}>{addRowText ?? "Add Row"}</Button>
+	</div>
+}

package/src/controls/basicNumericallyIdedItemPicker.tsx

@@ -0,0 +1,76 @@
+import {select as dataSelect} from "@wordpress/data";
+import {useCallback} from "@wordpress/element";
+
+import type {SNPControlSlots} from "../blocks";
+import {ExtendedFormTokenField, unpackDisplayedTokenText, ValidationState} from "./ExtendedFormTokenField";
+import {isNumeric} from "./shared";
+import type {TokenItem} from "../lib/useful-types";
+
+import type {ReactNode} from "react";
+
+type BasicNumericallyIdedItemPickerPropsBase = {
+	label?: string;
+	help?: ReactNode;
+	placeholder?: string;
+}&Partial<Pick<SNPControlSlots, 'Messages'>>;
+type BasicNumericallyIdedItemPickerPropsSingle = BasicNumericallyIdedItemPickerPropsBase&{
+	onChange(value: string): void;
+	value?: string;
+	multiple: false;
+};
+type BasicNumericallyIdedItemPickerPropsMultiple = BasicNumericallyIdedItemPickerPropsBase&{
+	onChange(value: string[]): void;
+	value?: string[];
+	multiple?: true|undefined;
+};
+export type BasicNumericallyIdedItemPickerProps = BasicNumericallyIdedItemPickerPropsSingle|BasicNumericallyIdedItemPickerPropsMultiple;
+
+export function basicNumericallyIdedItemPicker(props: BasicNumericallyIdedItemPickerProps, endpoint: string, queryProps: {[key: string]: any}) {
+	const {multiple, value, ...remainder} = props;
+
+	const suggestionQuery = useCallback((input: string, select: typeof dataSelect) => {
+		return select('plaudit/simple-gutenberg-apis')
+			.get(endpoint + "-options", {search: input, ...queryProps}) as TokenItem[]|undefined;
+	}, [queryProps]);
+	const validationQuery = useCallback((idsBeingValidated: string[], select: typeof dataSelect) => {
+		return (select('plaudit/simple-gutenberg-apis')
+			.get(endpoint + "-validation", {ids: idsBeingValidated.join(','), ...queryProps}) as TokenItem[]|undefined);
+	}, [queryProps]);
+
+	if (props.multiple === false) {
+		return <ExtendedFormTokenField
+			{...remainder}
+			value={props.value}
+			multiple={false}
+			onChange={props.onChange}
+			stringToTokenConverter={makeTokenFromSuggestion}
+			suggestionQuery={suggestionQuery}
+			validationQuery={validationQuery}
+			validator={validator}
+		/>;
+	} else {
+		return <ExtendedFormTokenField
+			{...remainder}
+			value={props.value}
+			multiple={true}
+			onChange={props.onChange}
+			stringToTokenConverter={makeTokenFromSuggestion}
+			suggestionQuery={suggestionQuery}
+			validationQuery={validationQuery}
+			validator={validator}
+		/>;
+	}
+}
+
+function makeTokenFromSuggestion(token: string): TokenItem {
+	if (isNumeric(token)) {
+		return {value: token, status: ValidationState.Validating};
+	} else {
+		const {value, title} = unpackDisplayedTokenText(token);
+		return {value, status: isNumeric(value) ? ValidationState.Validating : ValidationState.Invalid, title};
+	}
+}
+
+function validator(token: string) {
+	return /\(#([0-9]+)\)$/.exec(token)?.[1] !== undefined;
+}

package/src/controls/hooks/useImprovedTokenManager.ts

@@ -0,0 +1,157 @@
+import {useSelect} from "@wordpress/data";
+import type {MapSelect} from "@wordpress/data/types";
+import {useEffect, useMemo, useRef, useState} from "@wordpress/element";
+
+import type {TokenItem} from "../../lib/useful-types";
+
+export function packDisplayTokenText(token: TokenItem) {
+	return `${token.title || token.value} (#${token.value})`;
+}
+export function unpackDisplayedTokenText(token: string) {
+	const result = /(.+) \(#([^)]+)\)$/.exec(token);
+	return {title: result?.[1], value: result?.[2] ?? token};
+}
+
+// The strange values correspond to the literals that are expected by TokenItem.status, which allows the assignment code to be cleaner
+export const enum ValidationState {
+	Valid = 'success',
+	Invalid = 'error',
+	Validating = 'validating'
+}
+
+export type TokenManagementCallbacks = {
+	validationQuery(tokens: string[], ...args: Parameters<MapSelect>): TokenItem[]|undefined;
+	suggestionQuery(input: string, ...args: Parameters<MapSelect>): TokenItem[]|undefined;
+	stringToTokenConverter(suggestion: string): TokenItem;
+}
+
+type ImprovedTokenManagerReturnType = {
+	currentTokens: TokenItem[];
+	isValidating: boolean;
+	updateComponentValue: (value: (((prevState: (string | TokenItem)[]) => (string|TokenItem)[])|(string|TokenItem)[])) => void;
+	tokenStatusCache: Map<TokenItem["value"], TokenItem["status"]>
+};
+
+export function useImprovedTokenManager(
+	initialValue: (string|TokenItem)[]|undefined,
+	writeBackingValue: (value: TokenItem[]) => void,
+	validationQuery: TokenManagementCallbacks['validationQuery'],
+	makeTokenFromString: TokenManagementCallbacks['stringToTokenConverter'],
+	tokenTitleCache: Map<TokenItem['value'], TokenItem['title']>
+): ImprovedTokenManagerReturnType {
+	const [componentValue, updateComponentValue] = useState<(string|TokenItem)[]>(
+		() => initialValue?.map(item => typeof item === 'string' ? makeTokenFromString(item) : item) ?? []);
+
+	const tokenStatusCacheRef = useRef<Map<TokenItem['value'], TokenItem['status']>|undefined>(undefined);
+	if (tokenStatusCacheRef.current === undefined) {
+		tokenStatusCacheRef.current = new Map();
+	}
+
+	const convertedTokens = useTokenConverter(componentValue, makeTokenFromString, tokenStatusCacheRef.current);
+	const {isValidating, validatedTokens} = useTokenValidator(convertedTokens, validationQuery, tokenStatusCacheRef.current)
+	const titledTokens = useTokenTitleApplier(validatedTokens, tokenTitleCache);
+
+	useEffect(() => {
+		if (!isValidating) {
+			writeBackingValue(titledTokens);
+		}
+	}, [titledTokens, isValidating]);
+
+	return {currentTokens: titledTokens, isValidating, updateComponentValue, tokenStatusCache: tokenStatusCacheRef.current};
+}
+function syncTokenTitles(token: TokenItem, cache: Map<TokenItem['value'], TokenItem['title']>): TokenItem {
+	return {...token, title: cache.get(token.value) ?? addTokenTitleToCache(token, cache) ?? packDisplayTokenText(token)};
+}
+function addTokenTitleToCache(token: TokenItem, cache: Map<TokenItem['value'], TokenItem['title']>) {
+	let label = token.title?.trim();
+	if (!label) {
+		return;
+	}
+	const valueSuffix = `(#${token.value})`;
+	if (label.endsWith(valueSuffix)) {
+		label = label.substring(0, label.length - valueSuffix.length).trim();
+	}
+	const res = `${label.length > 30 ? `${label.substring(0, 30).trim()}…` : label} ${valueSuffix}`;
+	cache.set(token.value, res);
+	return res;
+}
+
+function isAllValidTokens(arr: (string|TokenItem)[]): arr is (Omit<TokenItem, 'title'|'status'>&Required<Pick<TokenItem, 'title'|'status'>>)[] {
+	return arr.every(token => typeof token !== 'string' && token.status !== undefined && token.status !== ValidationState.Validating && token.title !== undefined);
+}
+
+function useTokenConverter(
+	componentValue: (string|TokenItem)[], makeTokenFromString: (token: string) => TokenItem, tokenStatusCache: Map<TokenItem['value'], TokenItem['status']>
+) {
+	const priorComponentValue = useRef<(string|TokenItem)[]>([]);
+	const alreadyConvertedTokens = useRef<TokenItem[]>([]);
+	if (priorComponentValue.current === componentValue) {
+		return alreadyConvertedTokens.current;
+	}
+
+	const newlyConvertedTokens = isAllValidTokens(componentValue) ? componentValue
+		: componentValue.map(token => {
+			if (typeof token === 'string') {
+				const res = makeTokenFromString(token);
+				if (res.status === undefined) {
+					res.status = tokenStatusCache.get(res.value);
+				}
+				return res;
+			} else {
+				if (token.status === undefined || token.status === ValidationState.Validating) {
+					token.status = tokenStatusCache.get(token.value);
+				}
+				return token;
+			}
+		});
+
+	const convertedTokens = alreadyConvertedTokens.current;
+	if (newlyConvertedTokens.length !== convertedTokens.length) {
+		priorComponentValue.current = componentValue;
+		alreadyConvertedTokens.current = newlyConvertedTokens;
+		return newlyConvertedTokens;
+	}
+	for (let i = 0; i < newlyConvertedTokens.length; i++) {
+		if (newlyConvertedTokens[i]?.value !== convertedTokens[i]?.value || newlyConvertedTokens[i]?.status !== convertedTokens[i]?.status) {
+			priorComponentValue.current = componentValue;
+			alreadyConvertedTokens.current = newlyConvertedTokens;
+			return newlyConvertedTokens;
+		}
+	}
+	return convertedTokens;
+}
+
+function useTokenValidator(
+	convertedTokens: TokenItem[], validationQuery: TokenManagementCallbacks['validationQuery'], tokenStatusCache: Map<TokenItem['value'], TokenItem['status']>
+) {
+	const [statusUpdatedConvertedTokens, statusUpdatedConvertedTokenValues] = useMemo(() => {
+		const res = convertedTokens
+			.map(token => {
+				return (token.status === undefined || token.status === ValidationState.Validating) && tokenStatusCache.has(token.value)
+					? {...token, status: tokenStatusCache.get(token.value)} : token;
+			});
+		return [res, res.map(token => token.value)];
+	}, [convertedTokens, tokenStatusCache]);
+
+	return useSelect((select, registry) => {
+		if (statusUpdatedConvertedTokens.some(token => token.status === undefined || token.status === ValidationState.Validating)) {
+			const res = validationQuery(statusUpdatedConvertedTokenValues, select, registry);
+			if (res !== undefined) {
+				const validTokens = new Map(res.map(token => [token.value, token]));
+				const validatedTokens = convertedTokens.map(token => validTokens.get(token.value) ?? {...token, status: ValidationState.Invalid});
+				for (const token of validatedTokens) {
+					tokenStatusCache.set(token.value, token.status);
+				}
+				return {validatedTokens: res, isValidating: false};
+			} else {
+				return {validatedTokens: statusUpdatedConvertedTokens, isValidating: true};
+			}
+		} else {
+			return {validatedTokens: statusUpdatedConvertedTokens, isValidating: false};
+		}
+	}, [convertedTokens, statusUpdatedConvertedTokens, statusUpdatedConvertedTokenValues, validationQuery, tokenStatusCache]);
+}
+
+function useTokenTitleApplier(convertedTokens: TokenItem[], tokenTitleCache: Map<TokenItem['value'], TokenItem['title']>) {
+	return useMemo(() => convertedTokens.map(token => syncTokenTitles(token, tokenTitleCache)), [convertedTokens, tokenTitleCache]);
+}

package/src/controls/hooks/useMultiSingleConversionLayer.ts

@@ -0,0 +1,17 @@
+import {useCallback, useMemo} from "@wordpress/element";
+
+import type {TokenItem} from "../../lib/useful-types";
+
+export type ValueConverter = [string[], (value: TokenItem[]) => void];
+export function useMultiSingleConversionLayer(
+	value: string|string[]|undefined, onChange: ((tokens: string[]) => void)|((token: string) => void),
+	makeTokenFromSuggestion: (suggestion: string) => TokenItem, multiple = true
+): ValueConverter {
+	return [
+		useMemo(() => value === undefined ? [] : (Array.isArray(value) ? value : [value]), [value]),
+		useCallback(tokens => {
+			const bareTokens = tokens.filter(token => token.status === 'success').map(token => token.value);
+			onChange((multiple ? bareTokens : bareTokens[0]) as any);
+		}, [onChange, makeTokenFromSuggestion, multiple])
+	];
+}

package/src/controls/hooks/useNonRenderingCounter.ts

@@ -0,0 +1,6 @@
+import {useRef} from "@wordpress/element";
+
+export function useNonRenderingCounter(initialValue = 0): [{ readonly current: number }, () => number] {
+	const count = useRef(initialValue);
+	return [count, () => ++count.current];
+}

package/src/controls/hooks/useOutputMemoizingFilter.ts

@@ -0,0 +1,16 @@
+import {useCallback, useRef} from "@wordpress/element";
+
+export function useOutputMemoizingFilter<A extends any[], R>(filter: (...args: A) => R, externals?: any[]): typeof filter {
+	const existingState = useRef<undefined|[typeof filter, A, R]>(undefined);
+	const memoizedFilter = useCallback((...args: A): R => {
+		if (existingState.current !== undefined && existingState.current[0] === memoizedFilter
+			&& (existingState.current[1] === args || args.every((a, i) => existingState.current![1][i] === a))
+		) {
+			return existingState.current[2];
+		}
+		const res = filter(...args);
+		existingState.current = [memoizedFilter, args, res];
+		return res;
+	}, externals ? [filter, ...externals] : [filter]);
+	return memoizedFilter;
+}

package/src/controls/hooks/useSortableItemsModel.ts

@@ -0,0 +1,196 @@
+import {useEffect, useMemo, useState} from "@wordpress/element";
+
+import {Immer} from "immer";
+import {clone} from "../../lib/helpers";
+
+type Listeners<D> = {
+	onAdd?: (index: number, value: D) => void,
+	onChange?: (value: D[]) => void,
+	onRemove?: (index: number) => void,
+	onReorder?: (oldIndex: number, newIndex: number) => void
+};
+type SortableItemsModelArgs<D> = Listeners<D>&{
+	emptyValue?: D,
+	value?: D[]
+}
+export type SortableItemsModelKey = ReturnType<typeof crypto.randomUUID>;
+export type KeyedValue<D> = {value: D, key: SortableItemsModelKey};
+export type KeyedValues<D> = KeyedValue<D>[];
+type ActionDefs<D> = {
+	add(args: {index?: number, value: D}): void,
+	remove(args: {key: SortableItemsModelKey}): void,
+	move(args: {oldIndex: number, newIndex: number}): void,
+	change(args: {value: D, index: number}): void,
+
+	commit(args: {keyedValues: KeyedValues<D>}): void,
+	refresh(args: {listeners: Listeners<D>, value?: D[]}): void
+};
+
+type State<D> = {
+	listeners: Listeners<D>,
+	keyedValues: KeyedValues<D>,
+	value?: D[] // This is only used to avoid updating keyedValues on refresh wherever possible
+};
+
+export type IndexedItemActions<D> = {
+	add(value: D): void,
+	remove(): void,
+	moveUp(): void,
+	moveDown(): void,
+	change(value: D): void
+};
+export type IndexedItemActionsMaker<D> = (index: number, key: SortableItemsModelKey) => IndexedItemActions<D>;
+
+type Actions<D> = {add(value: D, index?: number): void, commit(keyedValues: KeyedValues<D>): void, makeIndexedItemActions: IndexedItemActionsMaker<D>};
+export function useSortableItemsModel<D>(args: SortableItemsModelArgs<D>) {
+	const {mutators, state} = usePseudoReducerBasedStateManagement<D>(args);
+
+	const {emptyValue} = args;
+	// We use a separate memo for the actions because dispatch should change significantly less-often than state
+	const actions = useMemo<Actions<D>>(() => {
+		return ({
+			add: (value: D, index?: number) => {
+				mutators.add({value, index});
+			},
+			commit: (keyedValues: KeyedValues<D>) => {
+				mutators.commit({keyedValues});
+			},
+			addEmptyValue: emptyValue !== undefined && emptyValue !== null ? (index?: number) => {
+				mutators.add({value: typeof emptyValue === 'object' ? {...emptyValue} : emptyValue, index});
+			} : undefined,
+			makeIndexedItemActions(index: number, key: SortableItemsModelKey) {
+				return useMemo(() => ({
+					add: (value: D) => {
+						mutators.add({value, index});
+					},
+					remove: () => {
+						mutators.remove({key});
+					},
+					moveUp: () => {
+						mutators.move({oldIndex: index, newIndex: index - 1});
+					},
+					moveDown: () => {
+						mutators.move({oldIndex: index, newIndex: index + 1});
+					},
+					change: (value: D) => {
+						mutators.change({value, index});
+					}
+				}), [index, key, mutators]);
+			}
+		});
+	}, [emptyValue, mutators]);
+
+	return {...actions, keyedValues: state.keyedValues};
+}
+
+function swap<T>(value: T[], newIndex: number, oldIndex: number): T[] {
+	const splicedValue = [...value];
+	if (newIndex > oldIndex) {
+		splicedValue.splice(newIndex + 1, 0, splicedValue[oldIndex]!);
+		splicedValue.splice(oldIndex, 1);
+	} else {
+		splicedValue.splice(newIndex, 0, ...splicedValue.splice(oldIndex, 1));
+	}
+	return splicedValue;
+}
+
+function usePseudoReducerBasedStateManagement<D>({value, onAdd, onChange, onRemove, onReorder}: SortableItemsModelArgs<D>) {
+	const [state, setState] = useState<State<D>>({keyedValues: [], listeners: {}});
+
+	const mutators = useMemo<ActionDefs<D>>(() => {
+		return {
+			add({value, index}) {
+				const newItemIndex = index ?? state.value?.length ?? 0;
+				const newValue = state.value?.toSpliced(newItemIndex, 0, value) ?? [value];
+				onAdd?.(newItemIndex, value);
+				onChange?.(newValue);
+				setState({
+					...state,
+					value: newValue,
+					keyedValues: state.keyedValues.toSpliced(newItemIndex, 0, {value: value, key: crypto.randomUUID()})
+				});
+			},
+			remove({key}) {
+				const actionIndex = state.keyedValues?.findIndex(({key: k}) => k === key) ?? -1;
+				if (actionIndex === -1) {
+					return;
+				}
+				const newValue = state.value?.toSpliced(actionIndex, 1) ?? [];
+				onRemove?.(actionIndex);
+				onChange?.(newValue);
+				setState({
+					...state,
+					value: newValue,
+					keyedValues: state.keyedValues.toSpliced(actionIndex, 1)
+				});
+			},
+			move({oldIndex, newIndex}) {
+				if (newIndex === oldIndex) {
+					return;
+				}
+				const newValue = swap(state.value ?? [], newIndex, oldIndex);
+				const changesStart = Math.min(newIndex, oldIndex);
+				newValue.splice(changesStart, newValue.length, ...newValue.slice(changesStart).map(v => clone(v)));
+				onReorder?.(oldIndex, newIndex);
+				onChange?.(newValue);
+				setState({
+					...state,
+					value: newValue,
+					keyedValues: swap(state.keyedValues, newIndex, oldIndex).map(({key}, i) => ({
+						value: newValue[i]!,
+						key
+					}))
+				});
+			},
+			change({value, index}) {
+				const newValue = (state.value ?? []).toSpliced(index, 1, value);
+				onChange?.(newValue);
+				setState({
+					...state,
+					value: newValue,
+					keyedValues: state.keyedValues.toSpliced(index, 1, {...state.keyedValues[index]!, value})
+				});
+			},
+			commit({keyedValues}) {
+				const newValue = keyedValues.map(({value}) => value);
+				onChange?.(newValue);
+				setState({
+					...state,
+					value: newValue,
+					keyedValues
+				});
+			},
+			refresh(args) {
+				const prevState = state;
+				setState((new Immer({autoFreeze: false})).produce(prevState, (draft: State<D>) => {
+					for (const [key, value] of Object.entries(args.listeners) as [keyof Listeners<D>, any][]) {
+						draft.listeners[key] = value;
+					}
+					if (prevState.value !== args.value) {
+						draft.value = args.value;
+						if (args.value !== undefined) {
+							if (args.value.length !== prevState.keyedValues.length) {
+								draft.keyedValues = args.value.map((v, i) => {
+									return {
+										value: v,
+										key: prevState.keyedValues[i] !== undefined && prevState.keyedValues[i].value === v ? prevState.keyedValues[i].key : crypto.randomUUID()
+									};
+								});
+							} else {
+								for (let i = 0; i < args.value.length; i++) {
+									draft.keyedValues[i]!.value = args.value[i]!;
+								}
+							}
+						}
+					}
+				}));
+			}
+		};
+	}, [state, onAdd, onChange, onRemove, onReorder]);
+
+	useEffect(() => {
+		mutators.refresh({listeners: {onAdd, onChange, onRemove, onReorder}, value});
+	}, [value, onAdd, onChange, onRemove, onReorder, mutators]);
+
+	return {mutators, state};
+}

package/src/controls/hooks/useSuggestions.ts

@@ -0,0 +1,91 @@
+import {useCallback, useEffect, useRef, useState} from "@wordpress/element";
+
+import {useNonRenderingCounter} from "./useNonRenderingCounter";
+
+import {useReducer} from "react";
+
+type UseSuggestionsArgs<T> = {
+	expandOnFocus?: boolean,
+	getOption?: (value?: string) => Promise<T|undefined>,
+	getSuggestions(filterValue: string): Promise<T[]>
+};
+type SuggestionState<T> = {
+	hasLoadingError: boolean,
+	suggestions: T[],
+	requestId: number
+};
+function useSimpleDebouncer(delay: number) {
+	const timerId = useRef<ReturnType<typeof window['setTimeout']>|undefined>(undefined);
+	return useCallback((action: () => void) => {
+		if (timerId.current !== undefined) {
+			clearTimeout(timerId.current);
+		}
+		timerId.current = setTimeout(() => {
+			timerId.current = undefined;
+			action();
+		}, delay);
+	}, [timerId]);
+}
+
+export function useSuggestions<T>(initialValue: string|null|undefined, {expandOnFocus, getOption, getSuggestions}: UseSuggestionsArgs<T>) {
+	const suggestionRequestDebouncer = useSimpleDebouncer(200);
+	const [requestId, nextRequestId] = useNonRenderingCounter();
+	const [isLoading, setIsLoading] = useState(false);
+	const [latestSuggestions, dispatchSuggestionsUpdate] = useReducer(useSuggestionSuggestionUpdateReducer<T>,
+		{hasLoadingError: false, requestId: 0, suggestions: []});
+	const [input, setInput] = useState(initialValue ?? "");
+
+	useEffect(() => {
+		const myRequestId = nextRequestId();
+		if (getOption === undefined) {
+			dispatchSuggestionsUpdate({hasLoadingError: false, suggestions: [], requestId: myRequestId});
+			return;
+		}
+		if (!expandOnFocus && input.length < 2) {
+			dispatchSuggestionsUpdate({hasLoadingError: false, suggestions: [], requestId: myRequestId});
+		} else {
+			setIsLoading(true);
+			getOption(input)
+				.then(option => dispatchSuggestionsUpdate({hasLoadingError: false, suggestions: option ? [option] : [], requestId: myRequestId}))
+				.catch(err => {
+					dispatchSuggestionsUpdate({hasLoadingError: true, suggestions: [], requestId: myRequestId});
+					console.error("An error occurred while loading options:", err);
+				});
+		}
+	}, [expandOnFocus, getOption]);
+
+	useEffect(() => {
+		const myRequestId = nextRequestId();
+		if (!expandOnFocus && input.length < 2) {
+			dispatchSuggestionsUpdate({hasLoadingError: false, suggestions: [], requestId: myRequestId});
+		} else {
+			const myRequestId = nextRequestId();
+			setIsLoading(true);
+			suggestionRequestDebouncer(() => {
+				getSuggestions(input)
+					.then(suggestions => dispatchSuggestionsUpdate({hasLoadingError: false, suggestions, requestId: myRequestId}))
+					.catch(err => {
+						dispatchSuggestionsUpdate({hasLoadingError: true, suggestions: [], requestId: myRequestId});
+						console.error("An error occurred while loading options:", err);
+					});
+			});
+		}
+	}, [input, suggestionRequestDebouncer]);
+
+	// This is a separate useEffect hook because we don't necessarily want to update the rendered state when a new request is sent out.
+	useEffect(() => setIsLoading(latestSuggestions.requestId < requestId.current), [latestSuggestions.requestId]);
+
+	return {
+		hasLoadingError: latestSuggestions.hasLoadingError, isInitializing: latestSuggestions.requestId === 0, isLoading,
+		input, setInput, suggestions: latestSuggestions.suggestions
+	}
+}
+function useSuggestionSuggestionUpdateReducer<T>(state: SuggestionState<T>, action: SuggestionState<T>): SuggestionState<T> {
+	if (action.requestId <= state.requestId) {
+		return state;
+	}
+	if (action.hasLoadingError) {
+		return {hasLoadingError: true, requestId: action.requestId, suggestions: [...state.suggestions]};
+	}
+	return action;
+}