Skip to content

Build your personal knowledge base with Trilium Notes

27.0 KB
Raw Blame
import "./FormAutocomplete.css";

import type { ReferenceElement } from "@floating-ui/dom";
import type { ComponentChildren, RefObject } from "preact";
import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "preact/hooks";

import FormTextBox from "./FormTextBox";
import { useUniqueName } from "./hooks";
import Popup, { type PopupProps } from "./Popup";

/** Marks the dropdown, which is portalled to the body: popups checking for outside clicks must ignore it. */
export const AUTOCOMPLETE_DROPDOWN_SELECTOR = ".form-autocomplete-dropdown";

const DEBOUNCE_MS = 150;

type FormTextBoxProps = Parameters<typeof FormTextBox>[0];

/** What the dropdown is placed under: an element, or a rect such as a caret's. */
type DropdownAnchor = HTMLElement | ReferenceElement;

interface FormAutocompleteProps extends Omit<FormTextBoxProps, "onChange"> {
    currentValue: string;
    onChange(newValue: string): void;
    /**
     * Provides the suggestions for a query. Called debounced while the dropdown is open; results
     * arriving after a newer query has been issued are discarded, so it may resolve out of order.
     */
    source(query: string): Promise<string[]>;
    /** Opens the dropdown as soon as the field receives focus, not just on typing. */
    openOnFocus?: boolean;
    /**
     * Opens the list on Enter where it is closed, for a box whose entries are what the field is for.
     * A list sent away — by Escape, or by taking something from it — is otherwise only brought back
     * by typing, which means editing a query that was already right.
     *
     * The key is not consumed when it only opens the list, so a form around the field is submitted by
     * it as before.
     */
    openOnEnter?: boolean;
    /**
     * Receives a suggestion picked from the dropdown (click or Enter) instead of `onChange`, for a
     * host that treats a made choice differently from typing — both otherwise arrive as the same
     * string. Left out, picking reports through `onChange`, exactly like typing. (Not `onSelect`,
     * which is the DOM's own text-selection event and reaches the input as such.)
     */
    onPick?(item: string): void;
    /**
     * Leaves the list open once an entry is picked, for a field collecting several — where picking
     * one is rarely the end of it, and closing would ask for the list back each time.
     *
     * The entries are fetched afresh, so a list narrowing as it is picked from (one leaving out what
     * has been taken already) is correct the moment its source says so.
     */
    keepOpenOnPick?: boolean;
    /**
     * Renders one suggestion, for lists where the bare text does not tell the whole story. Only the
     * appearance of the row is affected: what a suggestion means and what selecting it commits stay
     * the string the source returned. Defaults to showing that string. `query` is the text typed,
     * for setting what matches it in bold.
     */
    renderItem?(item: string, query: string): ComponentChildren;
    /**
     * Rendered inside the field, ahead of the box being typed into — the chips of a field holding
     * several values, which belong within its frame rather than above it.
     *
     * The two are then wrapped together, and the list is measured against that wrapper, so it spans
     * the whole field instead of only the stretch of it left over for typing.
     */
    leading?: ComponentChildren;
    /**
     * Content rendered inside the field, after the input. Use it for a button that commits what the
     * input holds, as {@link FormAutocompleteProps.leading} carries the chips that precede it.
     *
     * Passing either prop wraps the input in a `tn-field` element, which the dropdown is then placed
     * under and spans.
     */
    trailing?: ComponentChildren;
    /**
     * Marks an entry as a heading over the ones below it rather than a choice of its own: it takes no
     * click, is stepped over on the way through the list, and is never what Enter takes.
     */
    isHeading?(item: string): boolean;
    /**
     * The least the list is drawn at, in pixels, for a field too narrow for what its entries have to
     * say — a search box in the corner of a map offering whole addresses. The field's own width is
     * still the floor and the viewport the ceiling, so the list never runs off the screen.
     */
    dropdownMinWidth?: number;
    /**
     * Opens the list with an entry already picked out — the one the field's text names, or failing
     * that the first — so that Enter takes it without arrowing down to it first.
     *
     * For a box whose suggestions are the choices themselves: there the highlighted entry is where
     * the field already stands, and Enter means "this one". Left out for a box that only helps with
     * typing, where nothing is chosen until the user says so and Enter belongs to the form around it.
     */
    autoActivate?: boolean;
}

/**
 * A text box with a suggestion dropdown, driven by an async {@link FormAutocompleteProps.source}.
 *
 * The dropdown is portalled to the body and positioned over everything else, so it is not clipped
 * by scrolling ancestors. Selecting a suggestion reports it through `onChange`, exactly like typing.
 */
export default function FormAutocomplete({ currentValue, onChange, source, openOnFocus, openOnEnter, onPick, keepOpenOnPick, renderItem, leading, trailing, autoActivate, isHeading, dropdownMinWidth, inputRef, onFocus, onBlur, onKeyDown, onCompositionStart, onCompositionEnd, ...restProps }: FormAutocompleteProps) {
    const ownInputRef = useRef<HTMLInputElement>(null);
    const inputEl = inputRef ?? ownInputRef;
    const fieldRef = useRef<HTMLDivElement>(null);
    const isDisabled = !!(restProps.readOnly || restProps.disabled);

    const autocomplete = useAutocomplete({
        query: currentValue,
        source,
        onPick: onPick ?? onChange,
        inputRef: inputEl,
        disabled: isDisabled,
        openOnFocus,
        openOnEnter,
        keepOpenOnPick,
        autoActivate,
        isHeading
    });

    const field = (
        <FormTextBox
            // Keyed for the sake of a field carrying chips, which are keyed themselves: keyed and
            // unkeyed siblings together are matched up by position as the chips grow, which rebuilds
            // the box rather than keeping it — and a rebuilt box is one the focus has left.
            key="field"
            {...restProps}
            inputRef={inputEl}
            currentValue={currentValue}
            onChange={(newValue) => {
                onChange(newValue);
                autocomplete.handleInput();
            }}
            onFocus={(e) => {
                autocomplete.handleFocus();
                onFocus?.(e);
            }}
            onBlur={(newValue) => {
                autocomplete.handleBlur();
                onBlur?.(newValue);
            }}
            onKeyDown={(e) => {
                autocomplete.handleKeyDown(e);
                onKeyDown?.(e);
            }}
            onCompositionStart={(e) => {
                autocomplete.handleCompositionStart();
                onCompositionStart?.(e);
            }}
            onCompositionEnd={(e) => {
                autocomplete.handleCompositionEnd();
                onCompositionEnd?.(e);
            }}
            {...autocomplete.comboboxProps}
        />
    );

    return (
        <>
            {leading !== undefined || trailing !== undefined
                ? <div ref={fieldRef} className="tn-field form-autocomplete-field">{leading}{field}{trailing}</div>
                : field}

            <AutocompleteDropdown
                autocomplete={autocomplete}
                query={currentValue}
                // The wrapper where there is one, so a field carrying chips is spanned whole.
                anchor={fieldRef.current ?? inputEl.current}
                minWidth={dropdownMinWidth}
                renderItem={renderItem}
                isHeading={isHeading}
            />
        </>
    );
}

/** Drives an {@link AutocompleteList} from where its query is typed. */
export interface AutocompleteListHandle {
    /** Handles a key pressed where the query is typed, and returns whether the list took it. */
    handleKeyDown(e: KeyboardEvent): boolean;
}

/** The least width of an {@link AutocompleteList}, whose anchor at a caret has none. */
const CARET_LIST_MIN_WIDTH = 220;

/**
 * The dropdown of a {@link FormAutocomplete} for a query typed somewhere else, such as after a `#` in
 * a text editor, which keeps the focus and forwards its keys through `handleRef`. It opens with
 * nothing highlighted, so Enter stays with the host until an entry is arrowed to.
 */
export function AutocompleteList({ query, source, anchor, renderItem, onPick, handleRef, elementRef, onActiveDescendant }: {
    query: string;
    source(query: string): Promise<string[]>;
    anchor: DropdownAnchor;
    renderItem?(item: string, query: string): ComponentChildren;
    onPick(item: string): void;
    handleRef: RefObject<AutocompleteListHandle | null>;
    elementRef?: PopupProps["elementRef"];
    /** Called with the id of the highlighted entry's element, or `null` while none is highlighted. */
    onActiveDescendant?(id: string | null): void;
}) {
    // The focus stays where the query is typed, so there is no field to return it to.
    const inputRef = useRef<HTMLInputElement>(null);
    const autocomplete = useAutocomplete({ query, source, onPick, inputRef });

    // The host shows the list by mounting it and closes it by unmounting it.
    useEffect(() => autocomplete.open(), []);
    useForwardedKeys(autocomplete, handleRef, onActiveDescendant);

    return (
        <AutocompleteDropdown
            autocomplete={autocomplete}
            query={query}
            anchor={anchor}
            minWidth={CARET_LIST_MIN_WIDTH}
            renderItem={renderItem}
            elementRef={elementRef}
        />
    );
}

/**
 * Takes the keys forwarded from where a list's query is typed. Tab takes the highlighted entry, as
 * Enter does, where a field leaves Tab to move the focus. Reports the highlighted entry's element id
 * to `onActiveDescendant`, for the host to point its `aria-activedescendant` at, as a field's
 * `comboboxProps` do.
 */
export function useForwardedKeys<T>(
    autocomplete: ReturnType<typeof useAutocomplete<T>>,
    handleRef: RefObject<AutocompleteListHandle | null>,
    onActiveDescendant?: (id: string | null) => void
) {
    const { isShown, activeIndex, itemId } = autocomplete;
    const activeId = isShown && activeIndex >= 0 ? itemId(activeIndex) : null;
    const onActiveDescendantRef = useRef(onActiveDescendant);
    onActiveDescendantRef.current = onActiveDescendant;
    useEffect(() => onActiveDescendantRef.current?.(activeId), [ activeId ]);
    // A layout cleanup runs during the unmount itself; a passive one runs after paint, by which
    // time `createHostedList()` has already let go of the host it would report to.
    useLayoutEffect(() => () => onActiveDescendantRef.current?.(null), []);

    useLayoutEffect(() => {
        handleRef.current = {
            handleKeyDown(e) {
                if (!autocomplete.isShown) return false;
                if (e.key === "Tab" && !e.isComposing && autocomplete.takeHighlighted(e)) return true;
                autocomplete.handleKeyDown(e);
                return e.defaultPrevented;
            }
        };
        // Lets go of the list, so a host that outlives it holds none of its entries.
        return () => {
            handleRef.current = null;
        };
    });
}

/**
 * The list of a {@link useAutocomplete}, in a {@link Popup} under `anchor`, which places it again as
 * the list or the anchor changes size or moves.
 */
function AutocompleteDropdown({ autocomplete, query, anchor, minWidth = 0, renderItem, isHeading, elementRef }: {
    autocomplete: ReturnType<typeof useAutocomplete<string>>;
    /** The text typed, which `renderItem` is given. */
    query: string;
    anchor: DropdownAnchor | null;
    minWidth?: number;
    renderItem?(item: string, query: string): ComponentChildren;
    isHeading?(item: string): boolean;
    elementRef?: PopupProps["elementRef"];
}) {
    const { isShown, items, activeIndex, itemId, pick } = autocomplete;

    if (!isShown || !anchor) {
        return null;
    }

    return (
        <Popup
            anchor={anchor}
            className="form-autocomplete-dropdown"
            elementRef={elementRef}
            // As wide as the field, or as `minWidth` where that is more.
            style={{ width: `${Math.max(anchor.getBoundingClientRect().width, minWidth)}px` }}
        >
            <ul
                className="form-autocomplete-list"
                role="listbox"
                // Keeps the focus where the query is typed, so its blur does not close the dropdown
                // before the click lands on an item.
                onMouseDown={(e) => e.preventDefault()}
            >
                {items.map((item, index) => (
                    isHeading?.(item)
                        ? <li key={item} className="form-autocomplete-heading" role="presentation">
                            {renderItem ? renderItem(item, query) : item}
                        </li>
                        : <li
                            key={item}
                            id={itemId(index)}
                            className={`form-autocomplete-item ${index === activeIndex ? "active" : ""}`}
                            role="option"
                            aria-selected={index === activeIndex}
                            onMouseMove={(e) => autocomplete.hover(index, e)}
                            onClick={() => pick(item)}
                        >
                            {renderItem ? renderItem(item, query) : item}
                        </li>
                ))}
            </ul>
        </Popup>
    );
}

interface UseAutocompleteOptions<T> {
    /** The text in the field, which `source` is queried with. */
    query: string;
    /** See {@link FormAutocompleteProps.source}. */
    source(query: string): Promise<T[]>;
    /** Called with the entry picked by click or Enter. */
    onPick(item: T): void;
    /** The field, which keeps the focus once an entry is picked. */
    inputRef: RefObject<HTMLInputElement | null>;
    /** Keeps the list closed, for a read-only or disabled field. */
    disabled?: boolean;
    /** See {@link FormAutocompleteProps.openOnFocus}. */
    openOnFocus?: boolean;
    /** See {@link FormAutocompleteProps.openOnEnter}. */
    openOnEnter?: boolean;
    /**
     * See {@link FormAutocompleteProps.keepOpenOnPick}. A function decides per entry, for an entry
     * that refreshes the list rather than choosing from it.
     */
    keepOpenOnPick?: boolean | ((item: T) => boolean);
    /** See {@link FormAutocompleteProps.autoActivate}. */
    autoActivate?: boolean;
    /**
     * The entry `autoActivate` opens the list on when none matches the query, in place of the first
     * one that can be taken. A negative index falls back to that first one.
     */
    fallbackIndex?(items: T[]): number;
    /** See {@link FormAutocompleteProps.isHeading}. */
    isHeading?(item: T): boolean;
    /** The text of an entry, which `autoActivate` matches against the query. Defaults to `String(item)`. */
    textOf?(item: T): string;
    /**
     * Runs each lookup in place of the default debounce of {@link DEBOUNCE_MS}, for a source that
     * needs its own pacing. It must be stable across renders.
     */
    schedule?(lookUp: () => Promise<void>): void;
}

/**
 * The behavior of a combobox, without its markup: when the list opens and closes, which entry is
 * highlighted, and what the keys do. The focus stays in the field, which points at the highlighted
 * entry through `aria-activedescendant`.
 *
 * The host renders the list from `items`, gives each entry the id `itemId(index)`, and passes the
 * field's events to the `handle*` functions. Entries are fetched while the list is open, debounced
 * or paced by `schedule`, and a response to a superseded query is discarded.
 */
export function useAutocomplete<T>({ query, source, onPick, inputRef, disabled, openOnFocus, openOnEnter, keepOpenOnPick, autoActivate, fallbackIndex, isHeading, textOf = String, schedule }: UseAutocompleteOptions<T>) {
    const [ isOpen, setIsOpen ] = useState(false);
    // What an input method is composing is not yet what the user means, so nothing is looked up for
    // it until the composition ends.
    const [ isComposing, setIsComposing ] = useState(false);
    const [ items, setItems ] = useState<T[]>([]);
    const [ activeIndex, setActiveIndex ] = useState(-1);

    // Discards responses of queries that were superseded while in flight.
    const latestQuery = useRef(0);
    // The Enter handler reads the list as last rendered, so a pick holds Enter off that list until the
    // next render: a second Enter in the same task then reaches the host's form (issue #5669).
    const pickedSinceRender = useRef(false);
    pickedSinceRender.current = false;
    // Whether the entries on show answer an older query than the field's text. An Enter (or a
    // forwarded Tab) pressed then is held in `keyHeld` and picks from the newer query's entries once
    // they arrive.
    const isStale = useRef(false);
    const keyHeld = useRef(false);
    // A host that forwards its keys changes `query` without `handleInput`, and a key can arrive
    // before the lookup effect runs. A key held before such a change confirmed the text it replaced.
    // After `handleInput`, a key held before this render confirmed the text it renders.
    const renderedQuery = useRef(query);
    const inputSinceRender = useRef(false);
    if (renderedQuery.current !== query) {
        renderedQuery.current = query;
        isStale.current = true;
        if (!inputSinceRender.current) keyHeld.current = false;
    }
    inputSinceRender.current = false;
    const pickLatest = useRef(pick);
    pickLatest.current = pick;
    // Set when the keyboard or a new list moves the highlight, which the effect below scrolls into view.
    // The pointer never sets it: scrolling a partly shown row under the pointer would move the list.
    const scrollToActive = useRef(false);
    // Where the pointer last moved over the list. Scrolling slides a row under a still pointer, and the
    // browser can report that as a move at the same spot, which is not the pointer choosing the row.
    const lastPointer = useRef<{ x: number; y: number } | undefined>(undefined);
    // Names the entries so the field can point at the highlighted one: focus stays in the box, so
    // that pointer is all a screen reader has to go on.
    const itemIdPrefix = useUniqueName("autocomplete-item");
    const itemId = useCallback((index: number) => `${itemIdPrefix}-${index}`, [ itemIdPrefix ]);
    const isShown = isOpen && items.length > 0;

    const open = useCallback(() => {
        if (!disabled) setIsOpen(true);
    }, [ disabled ]);

    const close = useCallback(() => {
        // Invalidates in-flight queries too, so a late response cannot repopulate a closed dropdown.
        latestQuery.current++;
        isStale.current = false;
        keyHeld.current = false;
        setIsOpen(false);
        setActiveIndex(-1);
        setItems([]);
    }, []);

    // A lookup a scheduler still holds supersedes nothing once the list is gone, so it is dropped
    // rather than run for a list no longer there.
    useEffect(() => () => {
        latestQuery.current++;
    }, []);

    // Fetch suggestions for the current query, debounced. The previous items stay visible while
    // the request is in flight, so refining a query does not make the dropdown flicker.
    useEffect(() => {
        if (!isOpen || isComposing) {
            return;
        }

        const queryId = ++latestQuery.current;
        isStale.current = true;
        const lookUp = async () => {
            // A scheduler can run a lookup that a newer query (or a close) has since superseded.
            if (latestQuery.current !== queryId) return;

            const suggestions = await source(query);

            // A newer query (or a close) happened while awaiting.
            if (latestQuery.current === queryId) {
                const index = autoActivate ? bestMatchIndex(suggestions, query, isHeading, textOf, fallbackIndex) : -1;
                isStale.current = false;
                setItems(suggestions);
                scrollToActive.current = true;
                setActiveIndex(index);
                if (keyHeld.current) {
                    keyHeld.current = false;
                    if (index >= 0) pickLatest.current(suggestions[index]);
                }
            }
        };

        if (schedule) {
            schedule(lookUp);
            return;
        }

        const timeout = setTimeout(lookUp, DEBOUNCE_MS);
        return () => clearTimeout(timeout);
    }, [ isOpen, isComposing, query, source, autoActivate, fallbackIndex, isHeading, textOf, schedule ]);

    // Keep the highlighted entry in sight: it can be picked out on opening, or arrowed past the
    // bottom of a list taller than the room the dropdown was given.
    useEffect(() => {
        if (activeIndex < 0 || !scrollToActive.current) return;
        scrollToActive.current = false;
        // `nearest` scrolls the list by as little as it takes, and not at all while the entry is
        // already in view.
        document.getElementById(itemId(activeIndex))?.scrollIntoView({ block: "nearest" });
    }, [ activeIndex, items, itemId ]);

    function pick(item: T) {
        if (isHeading?.(item)) {
            return;
        }

        pickedSinceRender.current = true;
        onPick(item);
        if (typeof keepOpenOnPick === "function" ? keepOpenOnPick(item) : keepOpenOnPick) {
            // Nothing is highlighted until the refreshed entries arrive, so Enter cannot take twice
            // what the list is about to stop offering.
            setActiveIndex(-1);
        } else {
            close();
        }
        inputRef.current?.focus();
    }

    /**
     * Picks the highlighted entry for a key that confirms it, or holds the key until the entries for
     * a newer query arrive. Returns whether the key was taken.
     */
    function takeHighlighted(e: KeyboardEvent) {
        // Without `autoActivate` the newer entries open with nothing highlighted, so a key pressed
        // before they arrive belongs to the host.
        if (!isShown || activeIndex < 0 || pickedSinceRender.current || (!autoActivate && isStale.current)) {
            return false;
        }
        // Consume the key so it does not also reach the surrounding form or dialog.
        e.preventDefault();
        e.stopPropagation();
        if (isStale.current) {
            keyHeld.current = true;
        } else {
            pick(items[activeIndex]);
        }
        return true;
    }

    function handleKeyDown(e: KeyboardEvent) {
        // The keys belong to the input method, such as the Enter that commits a candidate.
        if (e.isComposing) return;

        switch (e.key) {
            case "ArrowDown":
            case "ArrowUp":
                e.preventDefault();
                if (!isShown) {
                    open();
                } else {
                    const delta = e.key === "ArrowDown" ? 1 : -1;
                    scrollToActive.current = true;
                    setActiveIndex((index) => stepOver(items, index, delta, isHeading));
                }
                break;

            case "Enter":
                if (!takeHighlighted(e) && openOnEnter) {
                    open();
                }
                break;

            case "Escape":
                if (isShown) {
                    // Only dismiss the dropdown; a surrounding popup keeps its own Escape handling.
                    e.stopPropagation();
                    close();
                }
                break;

            case "Tab":
                close();
                break;
        }
    }

    return {
        isOpen,
        isShown,
        items,
        activeIndex,
        setActiveIndex,
        itemId,
        /** Highlights the row the pointer moves over, without scrolling the list. */
        hover(index: number, e: { clientX: number; clientY: number }) {
            const last = lastPointer.current;
            if (last && last.x === e.clientX && last.y === e.clientY) return;
            lastPointer.current = { x: e.clientX, y: e.clientY };
            scrollToActive.current = false;
            setActiveIndex(index);
        },
        open,
        close,
        pick,
        /** Call once the field's text has changed. */
        handleInput() {
            // The lookup effect runs after the next render, and a key can arrive before it.
            isStale.current = true;
            // A held key confirms the text it was pressed on, not text typed after it.
            keyHeld.current = false;
            inputSinceRender.current = true;
            open();
        },
        handleFocus() {
            if (openOnFocus) open();
        },
        handleBlur: close,
        handleCompositionStart() {
            setIsComposing(true);
        },
        handleCompositionEnd() {
            setIsComposing(false);
        },
        handleKeyDown,
        takeHighlighted,
        /** The field's combobox attributes. */
        comboboxProps: {
            role: "combobox",
            "aria-expanded": isShown,
            "aria-autocomplete": "list",
            "aria-activedescendant": activeIndex >= 0 ? itemId(activeIndex) : undefined
        } as const
    };
}

/**
 * Which entry a list opens on: the one the field's text names, or else the one `fallbackIndex` picks or
 * the first that can be taken, so that a field whose text stands for a choice already made opens on it
 * and one being typed into opens on its best candidate. Matched the way the sources filter — ignoring
 * case and surrounding space.
 */
function bestMatchIndex<T>(items: T[], text: string, isHeading: ((item: T) => boolean) | undefined, textOf: (item: T) => string, fallbackIndex?: (items: T[]) => number) {
    const canBeTaken = (item: T) => !isHeading?.(item);
    const trimmed = text.trim().toLowerCase();
    const exact = items.findIndex((item) => canBeTaken(item) && textOf(item).toLowerCase() === trimmed);

    if (exact >= 0) return exact;
    const fallback = fallbackIndex?.(items) ?? -1;
    return fallback >= 0 ? fallback : items.findIndex(canBeTaken);
}

/**
 * The next entry that can be taken, in the direction asked for, wrapping at either end and stepping
 * over the headings in between. Nothing to step to — a list of headings alone — leaves nothing
 * highlighted.
 *
 * Exported for its own tests, the alternative being to drive a dropdown by keystrokes to find out
 * which row a heading was skipped for.
 */
export function stepOver<T>(items: T[], from: number, delta: number, isHeading?: (item: T) => boolean) {
    // With nothing highlighted, stepping up starts past the end so that it lands on the last entry.
    let index = from < 0 && delta < 0 ? items.length : from;

    for (let step = 0; step < items.length; step++) {
        index = (index + delta + items.length) % items.length;
        if (!isHeading?.(items[index])) {
            return index;
        }
    }

    return -1;
}