Building an Autocomplete Combobox That Stays in Sync With Slow Results

// index.ts
import type { Person, PickerOptions, PointerPosition, SearchPeople, SearchState } from './types';

export type { Person, PickerOptions, SearchPeople } from './types';

/**
 * How long a search runs before the list shows a loading line, in milliseconds.
 *
 * Most results arrive well before a second, and a shorter delay would flash the line on every keystroke.
 */
const LOADING_DELAY = 1000;

/**
 * Finds one required part of the picker's markup, typed without a cast.
 *
 * @param $root - The element that wraps the whole picker.
 * @param selector - The CSS selector for the part.
 * @param type - The element class the part must be an instance of.
 * @returns The part.
 */
function part<T extends Element>( $root: Element, selector: string, type: new () => T ): T {
	const $found = $root.querySelector( selector );
	if ( ! ( $found instanceof type ) ) {
		throw new Error( `The assignee picker needs ${selector} inside its root element.` );
	}
	return $found;
}

/**
 * Checks whether `showPopover()` takes a `source` option, which makes the field the popover's anchor.
 *
 * Some browser versions support `position-area` but not this option, and there the list would sit in a corner of the viewport.
 * The browser converts the options object before it checks the element, so the getter runs even though the call then throws on a `<div>` that isn't a popover.
 *
 * @returns Whether the getter ran.
 */
function showPopoverTakesSource(): boolean {
	let read = false;
	try {
		document.createElement( 'div' ).showPopover( {
			get source() {
				read = true;
				return undefined;
			},
		} );
	} catch {
		// The call always throws on a div without the popover attribute, and only the getter matters here.
	}
	return read;
}

/**
 * Builds the letters an avatar shows, one for a single name and two for a full name, from its first and last words.
 *
 * @param name - A full name.
 * @returns The initials, uppercased.
 */
function initials( name: string ): string {
	const words = name.trim().split( /\s+/ );
	const first = words.at( 0 )?.at( 0 ) ?? '';
	const last = words.length > 1 ? words.at( -1 )?.at( 0 ) ?? '' : '';
	return `${first}${last}`.toUpperCase();
}

/**
 * An assignee field that searches people on a server as the user types, and submits the picked person's id with its form.
 *
 * It enhances markup that already works as a labeled text field, so it needs no framework and no shadow root of its own.
 * The root element must hold an `<input role="combobox">` whose `aria-controls` names the listbox, an `<input type="hidden">` that carries the id, a `[popover]` element around a `.heading` and the `[role="listbox"]`, a `.message` with a `.message-text` and a `.retry` button inside the popover, and a `[role="status"]` element.
 *
 * Before the user types, the list offers suggestions, the results of a search for an empty query.
 * A click on the field, an arrow key, or clearing the text opens them, and moving focus into the field with Tab doesn't, so tabbing through the form never drops a list over the next fields.
 *
 * It keeps four values apart.
 * The text in the field is the query, which typing changes and a pick replaces with the person's name.
 * The highlight is a person's id, moved by the arrow keys and the pointer, and cleared when that person leaves the results.
 * The selected person is stored on its own, set by a pick, cleared when the field is left empty, and restored by a form reset.
 * The hidden input submits that person's id.
 *
 * While the search for the text in the field runs, the list keeps the older results on screen, dimmed and marked busy, and nothing in it can be picked.
 */
export class AssigneePicker {

	/**
	 * The element that wraps every part, used to tell whether focus is still inside the picker.
	 */
	private readonly $root: HTMLElement;

	/**
	 * The text field, which keeps focus the whole time so typing, the caret, and input methods keep working while the arrow keys move the highlight.
	 */
	private readonly $input: HTMLInputElement;

	/**
	 * The hidden input the form submits, holding the selected person's id or an empty string.
	 */
	private readonly $value: HTMLInputElement;

	/**
	 * The popover that holds the listbox and the message under it.
	 *
	 * It's `popover="manual"`, because an `auto` popover closes when the user clicks inside the field to move the caret.
	 */
	private readonly $popup: HTMLElement;

	/**
	 * The "Suggested" line above the options, shown only while the list holds the suggestions.
	 *
	 * It sits outside the listbox, which may hold nothing but options.
	 */
	private readonly $heading: HTMLElement;

	/**
	 * The listbox, which holds nothing but options, so the messages live beside it.
	 */
	private readonly $list: HTMLElement;

	/**
	 * The visible line under the options for loading, no matches, and errors.
	 */
	private readonly $message: HTMLElement;

	/**
	 * The text of that line, kept apart from the Retry button so setting it never removes the button.
	 */
	private readonly $messageText: HTMLElement;

	/**
	 * The button that runs the failed search again.
	 */
	private readonly $retry: HTMLButtonElement;

	/**
	 * The live region that announces how a search ended.
	 *
	 * It has to be in the page before its first message, because screen readers only announce changes to a live region that was already there.
	 */
	private readonly $status: HTMLElement;

	/**
	 * The search this picker runs for each query.
	 */
	private readonly search: SearchPeople;

	/**
	 * Whether this browser can anchor the popover to the field, which takes both `position-area` in CSS and the `source` option of `showPopover()`.
	 *
	 * Without them, the browser draws the popover in the top-left corner of the viewport, because the stylesheet sets its margin to 0.
	 * In that case the picker drops the popover and lets the stylesheet place the list under the field instead.
	 */
	private readonly anchored: boolean;

	/**
	 * Removes every listener the picker added, in one call from `destroy()`.
	 */
	private readonly listeners = new AbortController();

	/**
	 * The person the markup started with, which a form reset brings back.
	 *
	 * It's read once, because setting the hidden input's value from script also rewrites its default, and a reset would otherwise bring back the last pick.
	 */
	private readonly initial: Person | null;

	/**
	 * The person the form will submit, stored apart from the results, so a search that doesn't return them changes nothing about who is assigned.
	 */
	private selected: Person | null;

	/**
	 * The query whose results the list may show, trimmed, or null when no search has run since the list last closed for good.
	 *
	 * It changes when a search starts, and results for any other query are ignored.
	 * An empty string is a real query, the one that returns the suggestions, so null keeps "nothing searched yet" apart from it.
	 */
	private query: string | null = null;

	/**
	 * The people the list shows, the results for `query` or, while that search runs, the results of the search before it.
	 */
	private results: Person[] = [];

	/**
	 * The id of the highlighted person, or null.
	 *
	 * It's an id and not a position, so new results that move the person to another row keep the highlight on them, and results without them clear it.
	 */
	private highlightedId: string | null = null;

	/**
	 * Where the search for the current query stands.
	 */
	private state: SearchState = 'idle';

	/**
	 * The controller for the request still on its way, or null.
	 *
	 * Every query gets a new one, because an aborted signal stays aborted.
	 */
	private request: AbortController | null = null;

	/**
	 * The timer that shows the loading line once a search has run for a second.
	 */
	private loadingTimer: number | undefined;

	/**
	 * Whether an input method is composing text in the field, the time between `compositionstart` and `compositionend`.
	 */
	private composing = false;

	/**
	 * Whether the user closed the list with Escape, so results that arrive afterwards don't open it again.
	 *
	 * Typing, a click on the field, or an arrow key clears it.
	 */
	private dismissed = false;

	/**
	 * Where the pointer was at its last `pointermove`, so a move event with the same coordinates is ignored.
	 */
	private lastPointer: PointerPosition | null = null;

	/**
	 * Connects the picker to its markup and stores the person the field starts with.
	 *
	 * @param $root - The element that wraps every part of the picker.
	 * @param options - The search to run.
	 */
	constructor( $root: HTMLElement, options: PickerOptions ) {
		this.$root = $root;
		this.$input = part( $root, 'input[role="combobox"]', HTMLInputElement );
		this.$value = part( $root, 'input[type="hidden"]', HTMLInputElement );
		this.$popup = part( $root, '[popover]', HTMLElement );
		this.$heading = part( this.$popup, '.heading', HTMLElement );
		this.$list = part( this.$popup, '[role="listbox"]', HTMLElement );
		this.$message = part( this.$popup, '.message', HTMLElement );
		this.$messageText = part( this.$message, '.message-text', HTMLElement );
		this.$retry = part( this.$message, '.retry', HTMLButtonElement );
		this.$status = part( $root, '[role="status"]', HTMLElement );
		this.search = options.search;
		if ( this.$list.id === '' ) {
			throw new Error( 'The listbox needs an id, which aria-controls and the option ids are built from.' );
		}

		this.anchored = CSS.supports( 'position-area', 'block-end' ) && showPopoverTakesSource();
		if ( ! this.anchored ) {
			this.$popup.removeAttribute( 'popover' );
			this.$popup.hidden = true;
		}

		this.initial = this.$value.value === '' ? null : { id: this.$value.value, name: this.$input.value };
		this.selected = this.initial;

		const { signal } = this.listeners;
		this.$input.addEventListener( 'input', this.onInput, { signal } );
		this.$input.addEventListener( 'click', this.onFieldClick, { signal } );
		this.$input.addEventListener( 'compositionstart', this.onCompositionStart, { signal } );
		this.$input.addEventListener( 'compositionend', this.onCompositionEnd, { signal } );
		this.$input.addEventListener( 'keydown', this.onKeyDown, { signal } );
		this.$root.addEventListener( 'focusout', this.onFocusOut, { signal } );
		this.$popup.addEventListener( 'mousedown', this.keepFocus, { signal } );
		this.$list.addEventListener( 'click', this.onListClick, { signal } );
		this.$list.addEventListener( 'pointermove', this.onPointerMove, { signal } );
		this.$retry.addEventListener( 'click', this.onRetry, { signal } );
		this.$input.form?.addEventListener( 'reset', this.onReset, { signal } );
		this.$input.form?.addEventListener( 'submit', this.onSubmit, { signal } );
	}

	/**
	 * Removes every listener and stops the request still on its way, for when the field leaves the page.
	 */
	destroy(): void {
		this.listeners.abort();
		this.request?.abort();
		window.clearTimeout( this.loadingTimer );
	}

	/**
	 * Searches for what the user typed, unless an input method is still composing it.
	 */
	private onInput = (): void => {
		if ( this.composing ) {
			return;
		}
		this.dismissed = false;
		this.startSearch( this.$input.value );
	};

	/**
	 * Opens the list when the user clicks or taps the field.
	 *
	 * A click while the list is open only moves the caret, so it changes nothing.
	 */
	private onFieldClick = (): void => {
		if ( ! this.isOpen() ) {
			this.openList();
		}
	};

	/**
	 * Opens the list on what the field holds, after an Escape, a pick, or with nothing typed yet.
	 *
	 * When the field shows the assigned person's name, the list offers suggestions instead of searching for that name, and the text is selected so the first letter typed replaces it.
	 * A query that didn't change keeps the results it already has, so reopening after Escape sends no new request.
	 */
	private openList(): void {
		this.dismissed = false;
		const text = this.$input.value;
		if ( this.selected !== null && text === this.selected.name ) {
			this.$input.select();
			this.startSearch( '' );
		} else {
			this.startSearch( text );
		}
		this.sync();
	}

	/**
	 * Stops searching while an input method composes, since the text in the field isn't what the user means yet.
	 */
	private onCompositionStart = (): void => {
		this.composing = true;
	};

	/**
	 * Searches for the composed text once the input method commits it.
	 *
	 * Firefox sends one more `input` event after this one, and `startSearch()` skips it because the query didn't change.
	 */
	private onCompositionEnd = (): void => {
		this.composing = false;
		this.dismissed = false;
		this.startSearch( this.$input.value );
	};

	/**
	 * Starts the search for a query, after stopping the one the user left.
	 *
	 * The results on screen stay until the results for the new query arrive, so the list never empties between keystrokes.
	 * Until then `isStale()` is true, and nothing in the list can be picked.
	 * An empty query takes the same path as any other, so suggestions that arrive after the user typed are ignored like the results of any older search.
	 *
	 * @param text - The text in the field.
	 * @param again - Whether to search even though the query didn't change, which only Retry does.
	 */
	private startSearch( text: string, again = false ): void {
		const query = text.trim();
		if ( query === this.query && ! again ) {
			return;
		}
		this.query = query;
		this.request?.abort();
		this.request = null;
		window.clearTimeout( this.loadingTimer );
		this.$status.textContent = '';

		const request = new AbortController();
		this.request = request;
		this.state = 'pending';
		this.loadingTimer = window.setTimeout( () => {
			if ( this.request === request ) {
				this.state = 'slow';
				this.sync();
			}
		}, LOADING_DELAY );
		this.sync();
		void this.load( query, request );
	}

	/**
	 * Runs one search and shows its results, but only while it's still the latest request.
	 *
	 * Aborting stops the request, but it can't undo results that were already parsed, and some searches take no signal at all.
	 * The check on the request right before `settle()` covers every case, even two requests for the same text, like "ma" before and after "mar".
	 * The catch block tests the request's own `signal.aborted`, because engines reject an aborted `fetch()` with different errors.
	 *
	 * @param query - The query to search for.
	 * @param request - The controller whose signal stops it.
	 */
	private async load( query: string, request: AbortController ): Promise<void> {
		try {
			const people = await this.search( query, { signal: request.signal } );
			if ( request !== this.request ) {
				return;
			}
			this.settle( people );
		} catch {
			if ( request.signal.aborted || request !== this.request ) {
				return;
			}
			this.fail();
		}
	}

	/**
	 * Shows the results for the current query and announces how many people they hold.
	 *
	 * The highlight stays on its person if they're still in the list and is cleared otherwise.
	 * It never falls back to the first row, because new results would then put someone the user never chose under Enter.
	 *
	 * @param people - The results.
	 */
	private settle( people: Person[] ): void {
		window.clearTimeout( this.loadingTimer );
		this.request = null;
		this.results = people;
		if ( ! people.some( ( person ) => person.id === this.highlightedId ) ) {
			this.highlightedId = null;
		}
		this.state = people.length === 0 ? 'empty' : 'done';
		this.$status.textContent = this.countMessage( people.length );
		this.drawOptions();
		this.sync();
	}

	/**
	 * Shows the error for a search that failed, and clears the list, since the people in it are results for an older query.
	 */
	private fail(): void {
		window.clearTimeout( this.loadingTimer );
		this.request = null;
		this.results = [];
		this.highlightedId = null;
		this.state = 'failed';
		this.$status.textContent = 'Couldn\'t load people';
		this.drawOptions();
		this.sync();
	}

	/**
	 * Builds the announcement for a finished search.
	 *
	 * Suggestions are announced as suggested people, since nothing typed explains where the list came from.
	 *
	 * @param count - How many people it found.
	 * @returns The message for the status region, empty when there are no suggestions to offer.
	 */
	private countMessage( count: number ): string {
		if ( this.query === '' ) {
			if ( count === 0 ) {
				return '';
			}
			return count === 1 ? '1 suggested person' : `${count} suggested people`;
		}
		if ( count === 0 ) {
			return `No one matches ${this.query}`;
		}
		return count === 1 ? '1 person' : `${count} people`;
	}

	/**
	 * Builds the DOM id of a person's option from the listbox id and the person's id.
	 *
	 * `aria-activedescendant` then names the person, so the same id never points at someone else after the list changes.
	 *
	 * @param personId - The person's id.
	 * @returns The option's id.
	 */
	private optionId( personId: string ): string {
		return `${this.$list.id}-${personId}`;
	}

	/**
	 * Draws one option per result, each with an initials avatar and the person's name.
	 *
	 * An empty listbox is hidden, so the popover can still show a message with no options above it.
	 * Suggestions get the "Suggested" line above them and a listbox label that says so, because the list isn't the results for anything the user typed.
	 */
	private drawOptions(): void {
		const $options = this.results.map( ( person ) => {
			const $option = document.createElement( 'li' );
			$option.id = this.optionId( person.id );
			$option.setAttribute( 'role', 'option' );
			$option.setAttribute( 'aria-selected', 'false' );
			$option.dataset.person = person.id;
			const $avatar = document.createElement( 'span' );
			$avatar.className = 'avatar';
			$avatar.setAttribute( 'aria-hidden', 'true' );
			$avatar.textContent = initials( person.name );
			const $name = document.createElement( 'span' );
			$name.className = 'name';
			$name.textContent = person.name;
			$option.append( $avatar, $name );
			return $option;
		} );
		this.$list.replaceChildren( ...$options );
		this.$list.hidden = $options.length === 0;
		const suggested = this.query === '' && $options.length > 0;
		this.$heading.hidden = ! suggested;
		this.$list.setAttribute( 'aria-label', suggested ? 'Suggested people' : 'People' );
	}

	/**
	 * Builds the text of the visible line under the options for the current state, or an empty string when there's nothing to say.
	 *
	 * "No one matches" shows only once the results are in, since people read a missing suggestion as the person not existing.
	 * Empty suggestions have nothing to report, so the list stays closed.
	 *
	 * @returns The text of the line.
	 */
	private messageText(): string {
		switch ( this.state ) {
			case 'slow':
				return this.query === '' ? 'Loading suggestions' : `Searching for ${this.query}`;
			case 'empty':
				return this.query === '' ? '' : `No one matches ${this.query}`;
			case 'failed':
				return 'Couldn\'t load people';
			default:
				return '';
		}
	}

	/**
	 * Checks whether the list on screen shows the results of an older search than the text in the field, the suggestions included.
	 *
	 * That's true from the moment a search starts until its results or its error arrive.
	 * During that time the arrow keys, the pointer, Enter, and a click pick no one, and the listbox is marked `aria-busy` and dimmed.
	 * Select2 and GitHub's `<auto-complete>` element both pick from the old list when Enter comes before the new results.
	 *
	 * @returns Whether the search for the current query is still running.
	 */
	private isStale(): boolean {
		return this.state === 'pending' || this.state === 'slow';
	}

	/**
	 * Brings the popover, the message, the expanded state, the busy state, and the highlight in line with the picker's values.
	 *
	 * The popover opens only while focus is in the picker and the user hasn't dismissed it.
	 * While the list shows older results, no option is marked as highlighted, but the highlighted id stays, so the highlight comes back if that person is in the new results.
	 *
	 * @param scroll - Whether to scroll the highlighted option into view, which only `move()` sets.
	 */
	private sync( scroll = false ): void {
		const message = this.messageText();
		this.$messageText.textContent = message;
		this.$message.hidden = message === '';
		this.$retry.hidden = this.state !== 'failed';

		const open = ( this.results.length > 0 || message !== '' ) && ! this.dismissed && this.hasFocus();
		this.setOpen( open );
		if ( ! open ) {
			this.highlightedId = null;
		}
		this.$input.setAttribute( 'aria-expanded', String( open && this.results.length > 0 ) );

		const stale = this.isStale();
		this.$list.setAttribute( 'aria-busy', String( stale ) );
		let $active: HTMLElement | null = null;
		for ( const $option of this.$list.children ) {
			if ( $option instanceof HTMLElement ) {
				const active = ! stale && $option.dataset.person === this.highlightedId;
				$option.setAttribute( 'aria-selected', String( active ) );
				if ( active ) {
					$active = $option;
				}
			}
		}
		if ( $active ) {
			this.$input.setAttribute( 'aria-activedescendant', $active.id );
			if ( scroll ) {
				this.keepVisible( $active );
			}
		} else {
			this.$input.removeAttribute( 'aria-activedescendant' );
		}
	}

	/**
	 * Scrolls the list just enough to show the highlighted option.
	 *
	 * Browsers don't scroll an active descendant into view, and `scrollIntoView()` would scroll the page too, so the list's own `scrollTop` moves.
	 *
	 * @param $option - The highlighted option.
	 */
	private keepVisible( $option: HTMLElement ): void {
		const list = this.$list.getBoundingClientRect();
		const option = $option.getBoundingClientRect();
		if ( option.top < list.top ) {
			this.$list.scrollTop -= list.top - option.top;
		} else if ( option.bottom > list.bottom ) {
			this.$list.scrollTop += option.bottom - list.bottom;
		}
	}

	/**
	 * Checks whether focus is on the field or on another part of the picker, like the Retry button.
	 *
	 * @returns Whether the picker holds focus.
	 */
	private hasFocus(): boolean {
		const tree = this.$root.getRootNode();
		if ( tree instanceof Document || tree instanceof ShadowRoot ) {
			return tree.activeElement !== null && this.$root.contains( tree.activeElement );
		}
		return false;
	}

	/**
	 * Checks whether the list is showing.
	 *
	 * @returns Whether the popover, or the list that stands in for it, is open.
	 */
	private isOpen(): boolean {
		return this.anchored ? this.$popup.matches( ':popover-open' ) : ! this.$popup.hidden;
	}

	/**
	 * Opens or closes the list.
	 *
	 * `source` makes the field the popover's anchor, which the stylesheet's `position-area` places the list against.
	 *
	 * @param open - Whether the list should show.
	 */
	private setOpen( open: boolean ): void {
		if ( open === this.isOpen() ) {
			return;
		}
		if ( ! this.anchored ) {
			this.$popup.hidden = ! open;
		} else if ( open ) {
			this.$popup.showPopover( { source: this.$input } );
		} else {
			this.$popup.hidePopover();
		}
	}

	/**
	 * Handles the keys of the combobox pattern while focus stays in the field.
	 *
	 * Safari can send the Enter that confirms a composition after `compositionend`, with `isComposing` false and `keyCode` 229, so both are checked.
	 * Down and Up on a closed list open it first, on suggestions when nothing is typed, and they highlight a person only once the results for the current query are in.
	 * Enter never submits the form while the list is open, and it picks no one when nothing is highlighted or the list shows older results.
	 *
	 * @param event - The field's `keydown` event.
	 */
	private onKeyDown = ( event: KeyboardEvent ): void => {
		if ( event.isComposing || event.keyCode === 229 ) {
			return;
		}
		switch ( event.key ) {
			case 'ArrowDown':
				event.preventDefault();
				if ( ! this.isOpen() ) {
					this.openList();
				}
				this.move( 1 );
				break;
			case 'ArrowUp':
				event.preventDefault();
				if ( ! this.isOpen() ) {
					this.openList();
				}
				this.move( -1 );
				break;
			case 'Enter':
				if ( this.isOpen() ) {
					event.preventDefault();
					const person = this.results.find( ( candidate ) => candidate.id === this.highlightedId );
					if ( person && ! this.isStale() ) {
						this.pick( person );
					}
				}
				break;
			case 'Escape':
				if ( this.isOpen() ) {
					event.preventDefault();
					this.dismissed = true;
					this.sync();
				}
				break;
		}
	};

	/**
	 * Moves the highlight one person down or up.
	 *
	 * Down from the field opens the list on the first person, and Down on the last person stays there instead of wrapping, so a list that grows under the user never jumps them back to the top.
	 * Up from the field goes to the last person, and Up on the first person returns to the field with nothing highlighted, where Enter does nothing.
	 * While the list shows older results, it doesn't move.
	 *
	 * @param step - 1 for Down, -1 for Up.
	 */
	private move( step: 1 | -1 ): void {
		if ( this.results.length === 0 || this.isStale() ) {
			return;
		}
		if ( ! this.isOpen() ) {
			this.sync();
		}
		const last = this.results.length - 1;
		const index = this.results.findIndex( ( person ) => person.id === this.highlightedId );
		let next: number;
		if ( step === 1 ) {
			next = index === -1 ? 0 : Math.min( index + 1, last );
		} else {
			next = index === -1 ? last : index - 1;
		}
		this.highlightedId = next < 0 ? null : this.results[next]?.id ?? null;
		this.sync( true );
	}

	/**
	 * Assigns a person, writing their name into the field and their id into the hidden input.
	 *
	 * The list closes and the search state starts over, and typing afterwards searches again without touching the selection.
	 * The browser fires no event for a value set from script, and the hidden input dispatches `change` itself for any code that watches the form.
	 *
	 * @param person - The person to assign.
	 */
	private pick( person: Person ): void {
		this.selected = { id: person.id, name: person.name };
		this.$input.value = person.name;
		this.$value.value = person.id;
		this.forget();
		this.$value.dispatchEvent( new Event( 'change', { bubbles: true } ) );
	}

	/**
	 * Drops the query, the results, and the request on its way, and closes the list.
	 */
	private forget(): void {
		this.request?.abort();
		this.request = null;
		window.clearTimeout( this.loadingTimer );
		this.query = null;
		this.results = [];
		this.highlightedId = null;
		this.state = 'idle';
		this.dismissed = false;
		this.$status.textContent = '';
		this.drawOptions();
		this.sync();
	}

	/**
	 * Keeps focus in the field when the user presses on the list or its message, which would otherwise blur the field and close the list before the click event fires.
	 *
	 * @param event - The popover's `mousedown` event.
	 */
	private keepFocus = ( event: MouseEvent ): void => {
		event.preventDefault();
	};

	/**
	 * Assigns the person whose option was clicked, unless the list shows older results.
	 *
	 * @param event - The listbox's `click` event.
	 */
	private onListClick = ( event: MouseEvent ): void => {
		if ( this.isStale() ) {
			return;
		}
		const person = this.personAt( event.target );
		if ( person ) {
			this.pick( person );
		}
	};

	/**
	 * Highlights the person under the pointer.
	 *
	 * It listens for `pointermove` and not `mouseover` or `mouseenter`, because those fire when the list changes under a mouse that isn't moving.
	 * A move with the same coordinates as the last one is ignored for the same reason, and so is any move while the list shows older results.
	 *
	 * @param event - The listbox's `pointermove` event.
	 */
	private onPointerMove = ( event: PointerEvent ): void => {
		if ( this.lastPointer?.x === event.clientX && this.lastPointer.y === event.clientY ) {
			return;
		}
		this.lastPointer = { x: event.clientX, y: event.clientY };
		if ( this.isStale() ) {
			return;
		}
		const person = this.personAt( event.target );
		if ( person && person.id !== this.highlightedId ) {
			this.highlightedId = person.id;
			this.sync();
		}
	};

	/**
	 * Finds the person whose option holds an event's target.
	 *
	 * @param target - The element the event happened on.
	 * @returns The person, or undefined outside the options.
	 */
	private personAt( target: EventTarget | null ): Person | undefined {
		const $option = target instanceof Element ? target.closest( '[role="option"]' ) : null;
		if ( ! ( $option instanceof HTMLElement ) ) {
			return undefined;
		}
		return this.results.find( ( person ) => person.id === $option.dataset.person );
	}

	/**
	 * Runs the failed search again and puts focus back in the field.
	 *
	 * It searches for the failed query again.
	 * When the suggestions failed while the field showed the assigned person's name, it searches for the empty query the suggestions use, since the name was never searched.
	 */
	private onRetry = (): void => {
		this.$input.focus();
		this.startSearch( this.query ?? this.$input.value, true );
	};

	/**
	 * Puts the field back in line with the selection.
	 *
	 * An empty field unassigns the person.
	 * Any other text goes back to the selected person's name, or to an empty field when nobody is selected, so the field never shows a name the form won't submit.
	 */
	private settleField(): void {
		if ( this.$input.value.trim() === '' && this.selected !== null ) {
			this.selected = null;
			this.$value.value = '';
			this.$value.dispatchEvent( new Event( 'change', { bubbles: true } ) );
		}
		this.$input.value = this.selected?.name ?? '';
		this.forget();
	}

	/**
	 * Settles the field once focus leaves the picker.
	 *
	 * @param event - The `focusout` event from any part of the picker.
	 */
	private onFocusOut = ( event: FocusEvent ): void => {
		if ( event.relatedTarget instanceof Node && this.$root.contains( event.relatedTarget ) ) {
			return;
		}
		this.settleField();
	};

	/**
	 * Settles the field when the form submits.
	 *
	 * Enter submits the form once the list is closed, while the field may still hold the text the user typed.
	 * The `submit` event fires before the form collects its values, so an emptied field is already unassigned when the hidden input is read.
	 */
	private onSubmit = (): void => {
		this.settleField();
	};

	/**
	 * Brings back the person the field started with when the form resets.
	 *
	 * The `reset` event fires before the form resets its controls, so the picker sets a zero-delay timer and restores the initial person in it.
	 * It can't rely on the hidden input's own reset, because setting `.value` on a hidden input rewrites its default too.
	 */
	private onReset = (): void => {
		window.setTimeout( () => {
			this.selected = this.initial;
			this.$input.value = this.initial?.name ?? '';
			this.$value.value = this.initial?.id ?? '';
			this.forget();
			this.$value.dispatchEvent( new Event( 'change', { bubbles: true } ) );
		}, 0 );
	};
}