Skip to content

Build your personal knowledge base with Trilium Notes

13.7 KB
Raw Blame
import { type EditorState, type Extension, Prec } from "@codemirror/state";
import { EditorView, ViewPlugin, type ViewUpdate } from "@codemirror/view";

/** What {@link HostedCompletionConfig.match} finds before the caret. */
export interface HostedCompletionMatch {
    /** Where the text a pick replaces starts, as an offset into the text before the caret. */
    from: number;
}

/**
 * What a pick does in place of inserting text: changes the document between `from`, where the match
 * starts, and `to`, the caret, or runs something else, as a command does.
 */
export type HostedCompletionApply = (view: EditorView, from: number, to: number) => void;

/** What a pick puts in place of the match: text, or what an {@link HostedCompletionApply} does. */
export type HostedCompletionInsert = string | HostedCompletionApply;

/** What a {@link HostedCompletionList} is shown for, each time the text before the caret changes. */
export interface HostedCompletionState<M extends HostedCompletionMatch> {
    match: M;
    /** Where the caret is, in viewport coordinates. */
    caretRect(): DOMRect;
    /** The editor's element. A list anchored at {@link caretRect} watches the containers around it. */
    editable: HTMLElement;
    /**
     * Replaces what stands between the match's `from` and the caret with `insert`, as a pick does,
     * or runs `insert` on that range. For a promise, the list closes and the text stays until it
     * settles on either, past the editor losing the focus, and stays for good where it settles on
     * `undefined`. An edit that reaches the text meanwhile, such as the editor taking another note's
     * content, gives the commit up.
     */
    commit(insert: HostedCompletionInsert | Promise<HostedCompletionInsert | undefined>): void;
    /**
     * Points the editor at the list's highlighted entry through `aria-activedescendant`, by the id
     * of the entry's element, or at none for `null`. Once the list closes, it points at none.
     */
    setActiveDescendant(id: string | null): void;
}

/** A host's list for {@link hostedCompletion}. */
export interface HostedCompletionList<M extends HostedCompletionMatch> {
    show(state: HostedCompletionState<M>): void;
    hide(): void;
    /**
     * Handles a key pressed in the editor while the list is open, other than Escape, which closes it.
     * Returns whether the list took the key, which then reaches the editor no further.
     */
    handleKeyDown(event: KeyboardEvent): boolean;
    /** The list's element while it shows entries. Escape closes the list only then. */
    readonly element: HTMLElement | null;
    destroy?(): void;
}

export interface HostedCompletionConfig<M extends HostedCompletionMatch> {
    /**
     * What can be completed at the caret, read from the text of the line before it, or `null` where
     * nothing can. `explicit` is set after Ctrl-Space, which asks for completions where typing alone
     * offers none. `state` is there for what the text alone does not tell, such as the syntax tree.
     */
    match(before: string, explicit: boolean, state: EditorState): M | null;
    /**
     * Whether moving the caret onto a match opens the list, as typing does. `true` by default. A host
     * whose matches are everywhere, such as any identifier in code, passes `false`: a caret move then
     * only keeps an open list while the caret stays on its match.
     */
    opensOnCaretMove?: boolean;
    /** Creates the list, once per editor. */
    list(view: EditorView): HostedCompletionList<M>;
}

/**
 * Hands what can be completed at the caret to a list the host runs entirely: what it lists, how it
 * draws it, which entry is highlighted and what a pick inserts. The editor keeps the focus, forwards
 * its keys to the list while it is open and puts what the list commits in place of the text the
 * match covers. A commit is read again like typing, so a pick that leaves something to complete,
 * such as `note.`, opens the list on what follows it.
 *
 * The counterpart of CKEditor's `mention.hostedFeeds`, so that a host can serve both editors with
 * the same lists. The list closes when nothing matches, when the editor loses the focus, and on
 * Escape, after which it stays closed for that match.
 */
export function hostedCompletion<M extends HostedCompletionMatch>({ match, opensOnCaretMove = true, list }: HostedCompletionConfig<M>): Extension {
    const plugin = ViewPlugin.fromClass(class {
        private readonly list: HostedCompletionList<M>;
        /** Where the open list's match starts in the document, or `-1` while it is closed. */
        private from = -1;
        /** The text before the caret the open list was shown for. */
        private before = "";
        /** Asked for with Ctrl-Space, until the list closes. */
        private explicit = false;
        /** Where the match Escape closed the list on starts, which keeps it closed. */
        private dismissedAt = -1;
        /** The text that commits waiting on a promise replace, mapped through the edits since. */
        private readonly pending = new Set<{ from: number; to: number }>();
        private destroyed = false;

        constructor(private readonly view: EditorView) {
            this.list = list(view);
            const lists = hostedLists.get(view) ?? new Set();
            lists.add(this.list);
            hostedLists.set(view, lists);
        }

        update(update: ViewUpdate) {
            if (update.docChanged && this.dismissedAt >= 0) {
                // With `assoc` 1, so text inserted right before the match leaves it on the match.
                this.dismissedAt = update.changes.mapPos(this.dismissedAt, 1);
            }
            if (update.docChanged) {
                for (const range of this.pending) {
                    if (update.changes.touchesRange(range.from, range.to)) {
                        this.pending.delete(range);
                    } else {
                        range.from = update.changes.mapPos(range.from);
                        range.to = update.changes.mapPos(range.to);
                    }
                }
            }

            if (update.docChanged || update.selectionSet || update.focusChanged) {
                this.sync(update.docChanged);
            }
        }

        handleKeyDown(event: KeyboardEvent) {
            if (event.isComposing) {
                return false;
            }

            if (isExplicitRequest(event)) {
                this.explicit = true;
                this.dismissedAt = -1;
                this.from = -1;
                this.sync(true);
                // Nothing to complete here, so the key goes on to the editor's own completion.
                if (this.from < 0) {
                    return false;
                }
            } else if (this.from < 0) {
                return false;
            } else if (event.key === "Escape") {
                // A list showing nothing leaves Escape to the field.
                if (!this.list.element) {
                    return false;
                }

                this.dismissedAt = this.from;
                this.close();
            } else if (!this.list.handleKeyDown(event)) {
                return false;
            }

            event.preventDefault();
            return true;
        }

        destroy() {
            this.destroyed = true;
            hostedLists.get(this.view)?.delete(this.list);
            this.setActiveDescendant(null);
            this.list.hide();
            this.list.destroy?.();
        }

        /** `typed`: the document changed, as typing or a commit does, rather than only the caret. */
        private sync(typed: boolean) {
            const found = this.view.hasFocus ? matchAt(this.view.state, match, this.explicit) : null;
            if (found?.from !== this.dismissedAt) {
                this.dismissedAt = -1;
            }

            // A match a commit waits on stays closed too, until the commit replaces it.
            const waiting = found && [ ...this.pending ].some((range) => range.from === found.from);
            if (!found || this.dismissedAt >= 0 || waiting) {
                this.close();
                return;
            }

            if (found.from === this.from && found.before === this.before) {
                return;
            }
            if (!typed && !opensOnCaretMove && found.from !== this.from) {
                this.close();
                return;
            }

            this.from = found.from;
            this.before = found.before;
            // Shown in a measure, as the list reads the caret's place, which CodeMirror allows only in
            // `read`. While `show` runs, `caretRect()` answers what `read` measured.
            this.view.requestMeasure({
                read: () => caretRect(this.view),
                write: (measured) => {
                    // A later update has replaced or closed the list meanwhile.
                    if (this.from !== found.from || this.before !== found.before) return;

                    let showing = true;
                    this.list.show({
                        match: found.match,
                        caretRect: () => (showing ? measured : caretRect(this.view)),
                        editable: this.view.dom,
                        commit: (insert) => this.commit(found.from, insert),
                        setActiveDescendant: (id) => {
                            if (this.from === found.from) {
                                this.setActiveDescendant(id);
                            }
                        }
                    });
                    showing = false;
                }
            });
        }

        private commit(from: number, insert: HostedCompletionInsert | Promise<HostedCompletionInsert | undefined>) {
            if (this.from !== from) {
                return;
            }

            this.explicit = false;
            if (typeof insert === "function") {
                insert(this.view, from, this.view.state.selection.main.head);
                return;
            }
            if (insert instanceof Promise) {
                void this.commitWhenSettled(from, insert);
                return;
            }

            const text = insert;
            this.view.dispatch({
                changes: { from, to: this.view.state.selection.main.head, insert: text },
                selection: { anchor: from + text.length },
                userEvent: "input.complete"
            });
        }

        /** Closes the list, which stays closed on the match, and replaces the match once `insert` settles. */
        private async commitWhenSettled(from: number, insert: Promise<HostedCompletionInsert | undefined>) {
            const range = { from, to: this.view.state.selection.main.head };
            this.pending.add(range);
            this.close();

            const settled = await insert.catch(() => undefined);
            // `update()` drops the range of a commit an edit gave up meanwhile.
            const stillWaiting = this.pending.delete(range);
            if (settled === undefined || !stillWaiting || this.destroyed) {
                return;
            }
            if (typeof settled === "function") {
                settled(this.view, range.from, range.to);
                return;
            }

            const text = settled;
            this.view.dispatch({
                changes: { from: range.from, to: range.to, insert: text },
                selection: { anchor: range.from + text.length },
                userEvent: "input.complete"
            });
        }

        private close() {
            this.explicit = false;
            if (this.from < 0) {
                return;
            }

            this.from = -1;
            this.before = "";
            this.setActiveDescendant(null);
            this.list.hide();
        }

        /** Set on `contentDOM` directly: CodeMirror removes only the attributes it set itself. */
        private setActiveDescendant(id: string | null) {
            if (id) {
                this.view.contentDOM.setAttribute("aria-activedescendant", id);
            } else {
                this.view.contentDOM.removeAttribute("aria-activedescendant");
            }
        }
    }, {
        eventHandlers: {
            keydown(event) {
                return this.handleKeyDown(event);
            }
        }
    });

    // Ahead of the field's keymap, so the list takes Enter and the arrows while it is open.
    return Prec.highest(plugin);
}

/** Whether a list of {@link hostedCompletion} shows entries in `view` and takes the arrow keys. */
export function isHostedCompletionShown(view: EditorView) {
    return [ ...(hostedLists.get(view) ?? []) ].some((list) => list.element !== null);
}

const hostedLists = new WeakMap<EditorView, Set<HostedCompletionList<never>>>();

/** Ctrl-Space, or Alt-` as CodeMirror binds it on a Mac, where Ctrl-Space switches the input source. */
function isExplicitRequest(event: KeyboardEvent) {
    return (event.ctrlKey && event.key === " ") || (event.altKey && event.key === "`");
}

/** What `match` finds before the caret, with where it starts in the document. */
function matchAt<M extends HostedCompletionMatch>(state: EditorState, match: HostedCompletionConfig<M>["match"], explicit: boolean) {
    const { main } = state.selection;
    if (!main.empty) {
        return null;
    }

    const line = state.doc.lineAt(main.head);
    const before = line.text.slice(0, main.head - line.from);
    const found = match(before, explicit, state);

    return found && { match: found, from: line.from + found.from, before };
}

function caretRect(view: EditorView) {
    const coords = view.coordsAtPos(view.state.selection.main.head);
    if (!coords) {
        return view.contentDOM.getBoundingClientRect();
    }

    return new DOMRect(coords.left, coords.top, coords.right - coords.left, coords.bottom - coords.top);
}