Skip to content

Build your personal knowledge base with Trilium Notes

36.7 KB
Raw Blame
import {
    ALLOWED_PROTOCOLS, encodeBlockParameter, resolveBlockReference
} from "@triliumnext/commons";

import appContext, { type NoteCommandData } from "../components/app_context.js";
import { openInCurrentNoteContext } from "../components/note_context.js";
import linkContextMenuService from "../menus/link_context_menu.js";
import {
    getBlockReferenceLabel, getCachedBlockReferenceLabel, loadBlockReferenceLabel
} from "./block_excerpts.js";
import cssClassManager from "./css_class_manager.js";
import froca from "./froca.js";
import { t } from "./i18n.js";
import { getNoteImageUrl } from "./image_urls.js";
import { showError } from "./toast.js";
import treeService from "./tree.js";
import utils, { isShare } from "./utils.js";

/** The icon a column reference uses when the link carries no `columnIcon`. */
const DEFAULT_COLUMN_REFERENCE_ICON = "bx bx-columns";
const MISSING_NOTE_TITLE = "[missing note]";

function getNotePathFromUrl(url: string) {
    const notePathMatch = /#(root[A-Za-z0-9_/]*)$/.exec(url);

    return notePathMatch === null ? null : notePathMatch[1];
}

async function getLinkIcon(noteId: string, viewMode: ViewMode | undefined) {
    let icon;

    if (!viewMode || viewMode === "default") {
        const note = await froca.getNote(noteId);

        icon = note?.getIcon();
    } else if (viewMode === "source") {
        icon = "tn-icon bx bx-code-curly";
    } else if (viewMode === "attachments") {
        icon = "tn-icon bx bx-file";
    }
    return icon;
}

export type ViewMode = "default" | "source" | "attachments" | "contextual-help" | "note-map";

export interface ViewScope {
    /**
     * - "source", when viewing the source code of a note.
     * - "attachments", when viewing the attachments of a note.
     * - "contextual-help", if the current view represents a help window that was opened to the side of the main content.
     * - "default", otherwise.
     */
    viewMode?: ViewMode;
    attachmentId?: string;
    readOnlyTemporarilyDisabled?: boolean;
    /**
     * If true, it indicates that the note in the view should be opened in read-only mode (for supported note types such as text or code).
     *
     * The reason why we store this information here is that a note can become read-only as the user types content in it, and we wouldn't want
     * to immediately enter read-only mode.
     */
    isReadOnly?: boolean;
    /**
     * If true, a text note is edited with the floating toolbar whatever the user's editor-type
     * option says — the toolbar following the selection rather than standing in a bar of its own.
     *
     * For views too narrow to carry a full toolbar, such as the geo map's marker pane: a classic bar
     * built for the width of a note either spills out of them or eats the room the note is left.
     */
    floatingToolbar?: boolean;
    /** When set, scrolls to a bookmark anchor within the note after navigation. */
    bookmark?: string;
    /**
     * The blocks of a text note a reference points at, `id` or `startId:endId`, which the note
     * scrolls to and flashes once it renders. Consumed once, as `bookmark` is.
     */
    block?: string;
    /**
     * Search terms to highlight and jump to after navigating from search results; consumed once
     * by the destination type widget (mirrors `bookmark` semantics).
     */
    searchTerms?: string[];
    /**
     * The id of the board column a reference points at, which the board reveals once it has drawn
     * it. Consumed once, as `bookmark` is.
     */
    column?: string;
    /**
     * The title, icon and colour a column reference renders as, copied from the board when the
     * reference was made. Carried in the link because reading them needs the board's own
     * configuration; {@link column} is what the board resolves, so a rename only dates the label.
     */
    columnTitle?: string;
    columnIcon?: string;
    columnColor?: string;
    /**
     * The note id of the board card a reference points at, revealed the same way {@link column}
     * is.
     */
    card?: string;
    /**
     * The PDF page a reference points at, which the PDF viewer turns to once it has opened the
     * document. Consumed once, as `bookmark` is.
     */
    page?: string;
    /**
     * The id of the PDF annotation a reference points at, which the viewer scrolls to on
     * {@link page}. A reference to an annotation always carries its page too, so a deleted
     * annotation still leaves the reader on the right page.
     */
    annotation?: string;
}

/**
 * The state of a single split pane, as carried by the `splits` hash parameter when a tab is
 * moved or copied into a window of its own.
 */
export interface HashPane {
    notePath?: string | null;
    hoistedNoteId?: string | null;
    viewScope?: ViewScope;
}

/** A note path as it may appear in a hash: slash-separated note ids. */
const NOTE_PATH_PATTERN = /^[_a-z0-9]{4,}(\/[_a-z0-9]{4,})*$/i;

/**
 * How many extra panes a hash is allowed to carry. Well beyond any layout a user would build by
 * hand, but low enough that a hand-written address can't ask the app to open hundreds of panes.
 */
const MAX_SPLIT_PANES_IN_HASH = 8;

/** Hash parameters that belong to a pane's view scope rather than to the window as a whole. */
const VIEW_SCOPE_PARAMS = ["viewMode", "attachmentId", "bookmark", "block", "column",
    "columnTitle", "columnIcon", "columnColor", "card", "page", "annotation"];

interface CreateLinkOptions {
    title?: string;
    showTooltip?: boolean;
    showNotePath?: boolean;
    showNoteIcon?: boolean;
    referenceLink?: boolean;
    autoConvertToImage?: boolean;
    viewScope?: ViewScope;
    /**
     * Inline text appended right after the link title (before the note path, which renders on its
     * own line). Rendered as a `.note-link-suffix` span so it rides the title's baseline instead of
     * being pushed into a column by the wider note-path block — e.g. an annotation on why the note
     * is being shown.
     */
    titleSuffix?: string;
}

async function createLink(notePath: string | undefined, options: CreateLinkOptions = {}) {
    if (!notePath || !notePath.trim()) {
        logError("Missing note path");

        return $("<span>").text(MISSING_NOTE_TITLE);
    }

    if (!notePath.startsWith("root")) {
        // all note paths should start with "root/" (except for "root" itself)
        // used, e.g., to find internal links
        notePath = `root/${notePath}`;
    }

    const showTooltip = options.showTooltip === undefined ? true : options.showTooltip;
    const showNotePath = options.showNotePath === undefined ? false : options.showNotePath;
    const showNoteIcon = options.showNoteIcon === undefined ? false : options.showNoteIcon;
    const referenceLink = options.referenceLink === undefined ? false : options.referenceLink;
    const autoConvertToImage = options.autoConvertToImage === undefined ? false : options.autoConvertToImage;

    const { noteId, parentNoteId } = treeService.getNoteIdAndParentIdFromUrl(notePath);
    if (!noteId) {
        logError("Missing note ID");

        return $("<span>").text(MISSING_NOTE_TITLE);
    }

    const viewScope = options.viewScope || {};
    const viewMode = viewScope.viewMode || "default";
    let linkTitle = options.title;

    if (linkTitle === undefined) {
        /* v8 ignore start -- the implicit `else` of this chain (noteId falsy) is unreachable: an empty noteId already returned at the guard above */
        if (viewMode === "attachments" && viewScope.attachmentId) {
            const attachment = await froca.getAttachment(viewScope.attachmentId);

            linkTitle = attachment ? attachment.title : "[missing attachment]";
        } else if (noteId) {
            linkTitle = await treeService.getNoteTitle(noteId, parentNoteId);
        }
        /* v8 ignore stop */
    }

    const note = await froca.getNote(noteId);

    if (autoConvertToImage && note?.type && ["image", "canvas", "mermaid"].includes(note.type) && viewMode === "default") {
        return $("<img>")
            .attr("src", getNoteImageUrl(noteId, linkTitle || "", String(Math.random())))
            .attr("alt", linkTitle || "");
    }

    const $container = $("<span>");

    if (showNoteIcon) {
        const icon = await getLinkIcon(noteId, viewMode);

        if (icon) {
            $container.append($("<span>").addClass(`bx ${icon}`)).append(" ");
        }
    }

    const hash = calculateHash({
        notePath,
        viewScope
    });

    const $noteLink = $("<a>", {
        href: hash,
        text: linkTitle
    });

    if (!showTooltip) {
        $noteLink.addClass("no-tooltip-preview");
    }

    if (referenceLink) {
        $noteLink.addClass("reference-link");
    }

    $container.append($noteLink);

    if (options.titleSuffix) {
        $container.append($("<span>").addClass("note-link-suffix").text(options.titleSuffix));
    }

    if (showNotePath) {
        let pathSegments: string[];
        if (notePath == "root") {
            pathSegments = ["⌂"];
        } else {
            const resolvedPathSegments = (await treeService.resolveNotePathToSegments(notePath)) || [];
            resolvedPathSegments.pop(); // Remove last element

            const resolvedPath = resolvedPathSegments.join("/");
            pathSegments = await treeService.getNotePathTitleComponents(resolvedPath);
        }

        /* v8 ignore next 2 -- defensive guards: pathSegments is always a non-empty array (getNotePathTitleComponents never returns empty, and the root case yields ["⌂"]) */
        if (pathSegments) {
            if (pathSegments.length) {
                $container.append($("<small>").append(treeService.formatNotePath(pathSegments)));
            }
        }
    }

    return $container;
}

export function calculateHash(
    { notePath, ntxId, hoistedNoteId, viewScope = {}, splits, activeSplit }: NoteCommandData
) {
    notePath = notePath || "";
    const params = [
        ntxId ? { ntxId } : null,
        hoistedNoteId && hoistedNoteId !== "root" ? { hoistedNoteId } : null,
        viewScope.viewMode && viewScope.viewMode !== "default" ? { viewMode: viewScope.viewMode } : null,
        viewScope.attachmentId ? { attachmentId: viewScope.attachmentId } : null,
        viewScope.block ? { block: viewScope.block } : null,
        viewScope.column ? { column: viewScope.column } : null,
        viewScope.columnTitle ? { columnTitle: viewScope.columnTitle } : null,
        viewScope.columnIcon ? { columnIcon: viewScope.columnIcon } : null,
        viewScope.columnColor ? { columnColor: viewScope.columnColor } : null,
        viewScope.card ? { card: viewScope.card } : null,
        viewScope.page ? { page: viewScope.page } : null,
        viewScope.annotation ? { annotation: viewScope.annotation } : null,
        viewScope.searchTerms?.length
            ? { searchTerms: viewScope.searchTerms.map(encodeURIComponent).join(",") }
            : null,
        splits?.length ? { splits: splits.map(encodeSplitPane).join(",") } : null,
        splits?.length && activeSplit ? { activeSplit: String(activeSplit) } : null
    ].filter((p) => !!p);

    const paramStr = params
        .map((pair) => {
            const name = Object.keys(pair)[0];
            const value = (pair as Record<string, string | undefined>)[name];

            /* v8 ignore next -- `value` is never undefined: every retained pair holds a string. It
               can be empty, but only for a `splits` list whose panes are all empty. */
            const encodedValue = name === "block"
                ? encodeBlockParameter(value || "")
                : encodeURIComponent(value || "");
            return `${encodeURIComponent(name)}=${encodedValue}`;
        })
        .join("&");

    if (!notePath && !paramStr) {
        return "";
    }

    let hash = `#${notePath}`;

    if (paramStr) {
        hash += `?${paramStr}`;
    }

    return hash;
}

/**
 * Serializes one extra pane into an entry of the `splits` parameter: its own hash body, minus the
 * leading `#`. Entries are joined with commas, which is unambiguous because neither a note path nor
 * an encoded parameter value can contain one. A pane holding no note yields an empty entry, so that
 * the pane count of the original tab survives the trip.
 */
function encodeSplitPane(pane: HashPane) {
    return calculateHash(pane).slice(1);
}

/** The subset of `window.location` needed to build a URL, which a plain `URL` also satisfies. */
interface UrlParts {
    protocol: string;
    host: string;
    pathname: string;
    search: string;
}

/**
 * Builds the address of a detached ("extra") window showing the given target.
 *
 * The current query string is carried over rather than replaced. On the server it holds nothing of
 * interest, but in standalone the query *is* the environment (`?safeMode`, `?startNoteId` — see
 * `QUERY_TO_ENV` in the standalone platform provider), so a window that dropped it would boot with
 * different settings than the one it was opened from, and would apply those to every other window
 * should it later inherit the database lock.
 */
export function calculateExtraWindowUrl(target: NoteCommandData, location: UrlParts = window.location) {
    const params = new URLSearchParams(location.search);
    params.set("extraWindow", "1");

    return `${location.protocol}//${location.host}${location.pathname}?${params}${calculateHash(target)}`;
}

/** Whether the query string of `url` (everything before `hashIdx`) carries the `extraWindow` marker. */
function isExtraWindowUrl(url: string, hashIdx: number) {
    return /[?&]extraWindow(?:[=&]|$)/.test(url.slice(0, hashIdx));
}

/**
 * Parses the navigation state in the hash of `url`. A full URL is internal when it addresses the
 * document at `location` or has an accepted internal form. Any other URL is external: `{}`.
 */
export function parseNavigationStateFromUrl(
    url: string | undefined,
    location: UrlParts = window.location
) {
    if (!url) {
        return {};
    }

    url = url.trim();
    const hashIdx = url.indexOf("#");
    if (hashIdx === -1) {
        return {};
    }

    const isExtraWindow = isExtraWindowUrl(url, hashIdx);

    // Exclude external links that contain #
    if (
        hashIdx !== 0
        && !url.includes("/#root")
        && !url.includes("/#?searchString")
        && !isExtraWindow
        && !isSameDocumentUrl(url, hashIdx, location)
    ) {
        return {};
    }

    const hash = url.substr(hashIdx + 1); // strip also the initial '#'
    const [notePath, paramString] = hash.split("?");

    const viewScope: ViewScope = {
        viewMode: "default"
    };
    let ntxId: string | null = null;
    let hoistedNoteId: string | null = null;
    let searchString: string | null = null;
    let openInPopup = false;
    let splits: HashPane[] | null = null;
    let activeSplit = 0;

    for (const [name, value] of parseHashParams(paramString)) {
        if (name === "ntxId") {
            ntxId = value;
        } else if (name === "hoistedNoteId") {
            hoistedNoteId = value;
        } else if (name === "searchString") {
            searchString = value; // supports triggering search from URL, e.g. #?searchString=blabla
        } else if (name === "searchTerms") {
            // `value` already went through one decodeURIComponent() in parseHashParams (undoing the
            // generic pipeline's outer encode); each comma-separated token needs its own inner decode.
            // A malformed token (corrupted URL, hand-edited link) must not break navigation for
            // the rest of the link, so drop it rather than letting decodeURIComponent throw.
            viewScope.searchTerms = value
                .split(",")
                .map((token) => {
                    try {
                        return decodeURIComponent(token);
                    } catch {
                        return null;
                    }
                })
                .filter((token): token is string => token !== null);
        } else if (VIEW_SCOPE_PARAMS.includes(name)) {
            (viewScope as any)[name] = value;
        } else if (name === "popup") {
            openInPopup = true;
        } else if (name === "splits") {
            // Splits lay out the whole window, so they are honoured only while booting a
            // detached one. A link inside a note reaches this same parser, and no note should
            // be able to rearrange the panes of the window it is read in.
            splits = isExtraWindow ? parseSplitPanes(value) : null;
        } else if (name === "activeSplit") {
            activeSplit = Number.parseInt(value, 10) || 0;
        } else {
            console.warn(`Unrecognized hash parameter '${name}'.`);
        }
    }

    if (searchString) {
        return { searchString };
    }

    // A hash carrying splits is one we wrote ourselves, so its main pane may hold no note —
    // that is how a tab whose first pane was empty keeps the rest of its panes.
    const isEmptyMainPaneWithSplits = !notePath && !!splits?.length;

    if (!isEmptyMainPaneWithSplits && !NOTE_PATH_PATTERN.test(notePath)) {
        return {};
    }

    return {
        notePath,
        noteId: treeService.getNoteIdFromUrl(notePath),
        ntxId,
        hoistedNoteId,
        viewScope,
        searchString,
        openInPopup,
        splits,
        activeSplit
    };
}

/** Whether `url` addresses the document at `location`, query string included, hash ignored. */
function isSameDocumentUrl(url: string, hashIdx: number, location: UrlParts) {
    const documentUrl = url.slice(0, hashIdx);

    const { protocol, host, pathname, search } = location;
    return documentUrl === `${protocol}//${host}${pathname}${search}`;
}

/** Iterates the `name=value` pairs of a hash's parameter string, decoding both sides. */
function parseHashParams(paramString: string | undefined) {
    if (!paramString) {
        return [];
    }

    return paramString.split("&").map((pair) => {
        const [name, value] = pair.split("=");

        return [decodeURIComponent(name), decodeURIComponent(value ?? "")] as const;
    });
}

/**
 * Parses the `splits` parameter — the panes that stood beside the main one, in order. Entries that
 * aren't a well-formed pane are dropped rather than failing the whole hash, so a mangled address
 * still opens what it can.
 */
function parseSplitPanes(value: string): HashPane[] {
    return value
        .split(",")
        .slice(0, MAX_SPLIT_PANES_IN_HASH)
        .map(parseSplitPane)
        .filter((pane) => !!pane);
}

function parseSplitPane(entry: string): HashPane | null {
    const [notePath, paramString] = entry.split("?");

    // An empty entry is a pane that held no note; anything else has to be a real note path.
    if (notePath && !NOTE_PATH_PATTERN.test(notePath)) {
        return null;
    }

    const pane: HashPane = {
        notePath: notePath || null,
        hoistedNoteId: null,
        viewScope: { viewMode: "default" }
    };

    for (const [name, paramValue] of parseHashParams(paramString)) {
        if (name === "hoistedNoteId") {
            pane.hoistedNoteId = paramValue;
        } else if (VIEW_SCOPE_PARAMS.includes(name)) {
            (pane.viewScope as any)[name] = paramValue;
        }
        // Everything else — `ntxId`, `searchString`, a nested `splits` — describes a window rather
        // than a pane, and has no meaning this far down.
    }

    return pane;
}

/**
 * Interactive content that handles its own clicks opts out of link navigation by carrying this class. It is
 * needed where such content sits inside a link — a media player in a collection card, whose card is itself a
 * `.block-link` — so that pressing play doesn't also open the note. Marking the content is what lets its
 * clicks keep bubbling to the document, which the Bootstrap dropdowns inside it rely on; stopping propagation
 * at the player would kill link navigation and those dropdowns alike.
 */
const NO_LINK_NAVIGATION_SELECTOR = ".no-link-navigation";

function goToLink(evt: MouseEvent | JQuery.ClickEvent | JQuery.MouseDownEvent) {
    const $target = $(evt.target as any);
    if ($target.closest(NO_LINK_NAVIGATION_SELECTOR).length) {
        return false;
    }

    const $link = $target.closest("a,.block-link");
    const hrefLink = $link.attr("href") || $link.attr("data-href");

    return goToLinkExt(evt, hrefLink, $link);
}

/**
 * Handles navigation to a link, which can be an internal note path (e.g., `#root/1234`) or an external URL (e.g., `https://example.com`).
 *
 * @param evt the event that triggered the link navigation, or `null` if the link was clicked programmatically. Used to determine if the link should be opened in a new tab/window, based on the button presses.
 * @param hrefLink the link to navigate to, which can be a note path (e.g., `#root/1234`) or an external URL with any supported protocol (e.g., `https://example.com`).
 * @param $link the jQuery element of the link that was clicked, used to determine if the link is an anchor link (e.g., `#fn1` or `#fnref1`) and to handle it accordingly.
 * @returns `true` if the link was handled (i.e., the element was found and scrolled to), or a falsy value otherwise.
 */
export function goToLinkExt(evt: MouseEvent | JQuery.ClickEvent | JQuery.MouseDownEvent | React.PointerEvent<HTMLCanvasElement> | null, hrefLink: string | undefined, $link?: JQuery<HTMLElement> | null) {
    if (hrefLink?.startsWith("data:")) {
        return true;
    }

    // The preview button of the text editor's link toolbar acts on its clicks alone, and the
    // editor has handled a click that jumped into the note itself.
    if (evt && $link?.hasClass("ck-link-toolbar__preview")
        && (evt.type === "dblclick" || isDefaultPrevented(evt))) {
        return true;
    }

    evt?.preventDefault();
    evt?.stopPropagation();

    if (hrefLink && hrefLink.startsWith("#") && !hrefLink.startsWith("#root/") && $link) {
        if (handleAnchor(hrefLink, $link)) {
            return true;
        }
    }

    const { notePath, noteId, viewScope, openInPopup } = parseNavigationStateFromUrl(hrefLink);

    const ctrlKey = evt && utils.isCtrlKey(evt);
    const shiftKey = evt?.shiftKey;
    const isLeftClick = !evt || ("which" in evt && evt.which === 1);
    // Right click is handled separately.
    const isMiddleClick = evt && "which" in evt && evt.which === 2;
    // The preview button of the text editor's link toolbar opens a note in place, as a link does.
    const isLinkToolbarPreview = !!$link?.hasClass("ck-link-toolbar__preview");
    const targetIsBlank = $link?.attr("target") === "_blank" && !isLinkToolbarPreview;
    const isDoubleClick = isLeftClick && evt?.type === "dblclick";
    const openInNewTab = (isLeftClick && (ctrlKey || targetIsBlank)) || isDoubleClick || isMiddleClick;
    const activate = (isLeftClick && ctrlKey && shiftKey) || (isMiddleClick && shiftKey);
    const openInNewWindow = isLeftClick && evt?.shiftKey && !ctrlKey;
    const isPlainLeftClick = isLeftClick && !ctrlKey && !shiftKey && !isDoubleClick;

    if (notePath) {
        if (isPlainLeftClick && $link && isInEditableText($link)) {
            // The text editor shows the link toolbar, whose preview button opens the note.
            return true;
        }

        // A link to blocks of the note it is in acts as a link within a page.
        if (isPlainLeftClick && !openInPopup && !targetIsBlank && $link && viewScope?.block
            && showBlocksInPlace($link, noteId, viewScope.block)) {
            return true;
        }

        if (isLeftClick && openInPopup) {
            appContext.triggerCommand("openInPopup", { noteIdOrPath: notePath, viewScope });
        } else if (openInNewWindow) {
            appContext.triggerCommand("openInWindow", { notePath, viewScope });
        } else if (openInNewTab) {
            appContext.tabManager.openTabWithNoteWithHoisting(notePath, {
                activate: activate ? true : targetIsBlank,
                viewScope,
                placement: "afterCurrent"
            });
        } else if (isLeftClick) {
            openInCurrentNoteContext(evt, notePath, viewScope);
        }
    } else if (hrefLink) {
        const outsideOfCKEditor = !$link || $link.closest("[contenteditable]").length === 0;

        if (openInNewTab || openInNewWindow || (isLeftClick && (isLinkToolbarPreview || outsideOfCKEditor))) {
            if (hrefLink.toLowerCase().startsWith("http") || hrefLink.startsWith("api/")) {
                window.open(hrefLink, "_blank");
            } else if (ALLOWED_PROTOCOLS.some((protocol) => hrefLink.toLowerCase().startsWith(`${protocol}:`))) {
                // Enable protocols supported by CKEditor 5 to be clickable.
                if (window.electronApi) {
                    const reportLinkError = (e: unknown) => {
                        const message = e instanceof Error ? e.message : String(e);
                        logError(`Failed to open link '${hrefLink}': ${message}`);
                        showError(t("link.failed_to_open", { href: hrefLink, message }));
                    };

                    if (hrefLink.toLowerCase().startsWith("file:")) {
                        // The main process resolves the URL to a path and picks the dispatch
                        // that works per platform; shell.openExternal alone mishandles Unicode
                        // file:// URLs on Windows.
                        window.electronApi.shell.openFileUrl(hrefLink).then((err: string) => {
                            if (err) reportLinkError(new Error(err));
                        }).catch(reportLinkError);
                    } else {
                        window.electronApi.shell.openExternal(hrefLink);
                    }
                } else {
                    window.open(hrefLink, "_blank");
                }
            }
        }
    }

    return true;
}

/** Whether `$link` is in the content of an editable text note, rather than in an embed in it. */
function isInEditableText($link: JQuery<HTMLElement>) {
    return $link.closest(".ck-content").hasClass("note-detail-editable-text-editor");
}

/**
 * Scrolls to either the footnote (if clicking on a reference such as `[1]`), or to the reference of a footnote (if clicking on the footnote `^` arrow),
 * or CKEditor bookmarks.
 *
 * @param hrefLink the URL of the link that was clicked (it should be in the form of `#fn` or `#fnref`).
 * @param $link the element of the link that was clicked.
 * @returns `true` if the link was handled (i.e., the element was found and scrolled to), `false` otherwise.
 */
function handleAnchor(hrefLink: string, $link: JQuery<HTMLElement>) {
    const content = $link.closest(".ck-content")[0];
    const name = hrefLink.slice(1);
    // Exact comparison: an anchor name can hold characters that a CSS selector does not allow.
    const isFound = !!content
        && Array.from(content.querySelectorAll("[id]")).some((element) => element.id === name);
    if (isFound) {
        void loadBlockJump().then(({ showAnchor }) => showAnchor(content, name));
    }
    return isFound;
}

/**
 * Scrolls to the blocks `block` of the note `noteId` and flashes them, when `$link` is in the
 * content of that note that holds them. Returns whether it does.
 */
function showBlocksInPlace($link: JQuery<HTMLElement>, noteId: string | null, block: string) {
    const content = $link.closest(".ck-content")[0];
    const ntxId = $link.closest("[data-ntx-id]").attr("data-ntx-id");
    if (!content || !ntxId || appContext.tabManager.getNoteContextById(ntxId).noteId !== noteId) {
        return false;
    }

    // A broken range is left to the note context, which also shows the error.
    const { start, end } = resolveBlockReference(content, block);
    if (!start || !end) {
        return false;
    }

    void loadBlockJump().then(({ showBlockReference }) => showBlockReference(content, block));
    return true;
}

/** Whether something before `goToLinkExt()` already took the default action of `evt`. */
function isDefaultPrevented(evt: NonNullable<Parameters<typeof goToLinkExt>[0]>) {
    return "isDefaultPrevented" in evt ? evt.isDefaultPrevented() : evt.defaultPrevented;
}

/** The module that scrolls to blocks and anchors and flashes them, loaded on first use. */
function loadBlockJump() {
    return import("@triliumnext/ckeditor5/src/plugins/block_reference/block_reference_read_only.js");
}

function linkContextMenu(e: PointerEvent) {
    const $link = $(e.target as any).closest("a");
    const url = $link.attr("href") || $link.attr("data-href");

    if ($link.attr("data-no-context-menu")) {
        return;
    }

    const { notePath, viewScope } = parseNavigationStateFromUrl(url);

    if (!notePath) {
        return;
    }

    if (utils.isCtrlKey(e) && e.button === 2) {
        appContext.triggerCommand("openInPopup", { noteIdOrPath: notePath, viewScope });
        e.preventDefault();
        return;
    }

    e.preventDefault();

    linkContextMenuService.openContextMenu(notePath, e, viewScope, null);
}

/**
 * Fills `$el` with the label of the reference link to `href`. A link to blocks of `hostNoteId`, the
 * note the link is in, shows only the text of the blocks, read from `content` when it holds them,
 * as an editor does. When `isExcerpt`, `content` holds only some blocks of the note, and the others
 * are read from the saved note. A link to a note that does not exist shows `storedTitle`, the title
 * the content holds for it.
 */
async function loadReferenceLinkTitle(
    $el: JQuery<HTMLElement>,
    href: string | null | undefined = null,
    hostNoteId?: string,
    storedTitle?: string,
    content?: ParentNode | null,
    isExcerpt = false
) {
    const $link = $el[0].tagName === "A" ? $el : $el.find("a");

    href = href || $link.attr("href");
    if (!href) {
        console.warn(`Empty URL for parsing: ${$el[0].outerHTML}`);
        return;
    }

    const { noteId, viewScope } = parseNavigationStateFromUrl(href);
    if (!noteId) {
        // Not returned on: the editing downcast creates an empty <span> that only this call fills.
        // An attachment image URL, an external link or imported HTML can carry such an href.
        console.warn("Missing note ID.");
    }

    // A card reference holds the board in its path and the card in `card`. The link renders the
    // card; the path is what it opens.
    const subjectId = viewScope?.card || noteId;
    const note = subjectId ? await froca.getNote(subjectId, true) : null;

    if (viewScope?.block && note && (content || noteId === hostNoteId)) {
        const liveLabel = content ? getBlockReferenceLabel(content, viewScope.block) : null;
        const label = liveLabel && !(liveLabel.isBroken && isExcerpt)
            ? liveLabel
            : await loadBlockReferenceLabel(note, viewScope.block) ?? liveLabel;
        if (label) {
            $el.text(label.text).toggleClass("block-reference-broken", label.isBroken);
            if (!label.isHeading) {
                $el.prepend($("<span>").addClass("tn-icon bx bx-paragraph"));
            }
            return;
        }
    }

    if (!note) {
        $el.text(storedTitle || MISSING_NOTE_TITLE)
            .addClass("reference-link-missing no-link-navigation")
            .prepend($("<span>").addClass("tn-icon bx bx-x"));
        return;
    }

    $el.addClass(note.getColorClass());

    const title = await getReferenceLinkTitle(href);
    // A column reference renders as "<board>: <column>", the column in a `<small>` below.
    $el.text(viewScope?.columnTitle ? `${title}:` : title);

    if (viewScope?.bookmark) {
        $el.append($("<small>").append(
            $("<span>").addClass("bx bx-bookmark"),
            document.createTextNode(viewScope.bookmark)
        ));
    }

    if (viewScope?.block) {
        const label = await loadBlockReferenceLabel(note, viewScope.block);
        if (label) {
            $el.append($("<small>")
                .toggleClass("block-reference-broken", label.isBroken)
                .append(
                    $("<span>").addClass("bx bx-paragraph"),
                    document.createTextNode(label.text)
                ));
        }
    }

    if (viewScope?.page) {
        $el.append($("<small>").append(
            $("<span>").addClass(viewScope.annotation ? "bx bx-comment-detail" : "bx bx-file"),
            document.createTextNode(getPdfReferenceLabel(viewScope.page, viewScope.annotation))
        ));
    }

    if (viewScope?.columnTitle) {
        $el.append($("<small>")
            .addClass(cssClassManager.createClassForColor(viewScope.columnColor ?? null))
            .append(
                $("<span>").addClass(viewScope.columnIcon || DEFAULT_COLUMN_REFERENCE_ICON),
                document.createTextNode(` ${viewScope.columnTitle}`)
            ));
    }

    const icon = await getLinkIcon(note.noteId, viewScope?.viewMode);
    if (icon) {
        $el.prepend($("<span>").addClass(icon));
    }
}

async function getReferenceLinkTitle(href: string) {
    const { noteId, viewScope } = parseNavigationStateFromUrl(href);
    if (!noteId) {
        return MISSING_NOTE_TITLE;
    }

    // A card reference is titled by the card, not by the board in its path.
    const note = await froca.getNote(viewScope?.card || noteId);
    if (!note) {
        return MISSING_NOTE_TITLE;
    }

    if (viewScope?.viewMode === "attachments" && viewScope?.attachmentId) {
        // `froca.getAttachmentOfNote()` reloads the attachments when the cached list lacks it.
        const attachment = await froca.getAttachmentOfNote(noteId, viewScope.attachmentId);

        return attachment ? attachment.title : "[missing attachment]";
    }

    return note.title;
}

/**
 * The label of the reference link to `href`, from the notes already in froca. A link to a note that
 * is not there gets `storedTitle`, the title the content holds for it. A link to blocks of
 * `content`, the content the link is in, gets their text. When `isExcerpt`, `content` holds only
 * some blocks of the note, and the others are read from the saved note.
 */
function getReferenceLinkTitleSync(
    href: string, storedTitle?: string, content?: ParentNode | null, isExcerpt = false
) {
    const { noteId, viewScope } = parseNavigationStateFromUrl(href);
    if (!noteId) {
        return storedTitle || MISSING_NOTE_TITLE;
    }

    const note = froca.getNoteFromCache(viewScope?.card || noteId);
    if (content && viewScope?.block) {
        const label = getBlockReferenceLabel(content, viewScope.block);
        const savedLabel = label.isBroken && isExcerpt && note
            ? getCachedBlockReferenceLabel(note, viewScope.block)
            : null;
        return (savedLabel ?? label).text;
    }

    if (!note) {
        return storedTitle || MISSING_NOTE_TITLE;
    }

    if (viewScope?.viewMode === "attachments" && viewScope?.attachmentId) {
        if (!note.attachments) {
            return "[loading title...]";
        }

        const attachment = note.attachments.find((att) => att.attachmentId === viewScope.attachmentId);

        return attachment ? attachment.title : "[missing attachment]";
    }

    if (viewScope?.columnTitle) {
        return `${note.title}: ${viewScope.columnTitle}`;
    }

    if (viewScope?.bookmark) {
        return `${note.title} - ${viewScope.bookmark}`;
    }

    const blockLabel = viewScope?.block
        ? getCachedBlockReferenceLabel(note, viewScope.block)
        : null;
    if (blockLabel && !blockLabel.isBroken) {
        return `${note.title} - ${blockLabel.text}`;
    }

    if (viewScope?.page) {
        return `${note.title} - ${getPdfReferenceLabel(viewScope.page, viewScope.annotation)}`;
    }

    return note.title;
}

/** What a reference to a PDF says after the title: the page, or the annotation on it. */
function getPdfReferenceLabel(pageNumber: string, annotation: string | undefined) {
    return t(annotation ? "pdf.annotation_reference" : "pdf.page_reference", { pageNumber });
}

// A shared page hosting an app view keeps its links as plain links to other shared pages.
/* v8 ignore next -- the `print` device branch is evaluated once at module load; under test glob.device is undefined, so the false arm cannot be exercised */
if (glob.device !== "print" && !isShare) {
    // TODO: Check why the event is not supported.
    //@ts-ignore
    $(document).on("click", "a", goToLink);
    // TODO: Check why the event is not supported.
    //@ts-ignore
    $(document).on("auxclick", "a", goToLink); // to handle the middle button
    // TODO: Check why the event is not supported.
    //@ts-ignore
    $(document).on("contextmenu", "a", linkContextMenu);
    // TODO: Check why the event is not supported.
    //@ts-ignore
    $(document).on("dblclick", "a", goToLink);

    $(document).on("mousedown", "a", (e) => {
        if (e.which === 2) {
            // prevent paste on middle click
            // https://github.com/zadam/trilium/issues/2995
            // https://developer.mozilla.org/en-US/docs/Web/API/Element/auxclick_event#preventing_default_actions
            e.preventDefault();
            return false;
        }
    });
}

export default {
    getNotePathFromUrl,
    createLink,
    goToLink,
    goToLinkExt,
    loadReferenceLinkTitle,
    getReferenceLinkTitle,
    getReferenceLinkTitleSync,
    calculateHash,
    calculateExtraWindowUrl,
    parseNavigationStateFromUrl
};