Skip to content

Build your personal knowledge base with Trilium Notes

14.8 KB
Raw Blame
import type { ResourcesStatusResponse } from "@triliumnext/commons";
import { Modal } from "bootstrap";

import type { NotePickerDialogOptions } from "../widgets/dialogs/note_picker.js";

import appContext from "../components/app_context.js";
import type { ConfirmDeleteNoteBoxOptions, ConfirmDialogOptions, ConfirmDialogResult, ConfirmWithMessageOptions, MessageType } from "../widgets/dialogs/confirm.js";
import { InfoExtraProps } from "../widgets/dialogs/info.jsx";
import type { ItemPickerDialogOptions, PickerItem } from "../widgets/dialogs/item_picker.js";
import type { PromptDialogOptions } from "../widgets/dialogs/prompt.js";
import { focusSavedElement, saveFocusedElement } from "./focus.js";
import keyboardActionsService from "./keyboard_actions.js";
import type { NoteDeletionTarget } from "./note_deletion.js";
import server from "./server.js";

/**
 * @param declaredZIndex the z-index the dialog defines for itself, if any (see {@link raiseAboveStackedPopup}).
 */
export async function openDialog($dialog: JQuery<HTMLElement>, closeActDialog = true, config?: Partial<Modal.Options>, declaredZIndex?: number) {
    if (closeActDialog) {
        closeActiveDialog();
        glob.activeDialog = $dialog;
    }

    saveFocusedElement();

    // Lift this dialog above whatever is already open, if anything is (see raiseAboveWhatIsOpen).
    const bumpedZIndex = raiseAboveWhatIsOpen($dialog[0], declaredZIndex);

    Modal.getOrCreateInstance($dialog[0], config).show();

    // Normalise the just-shown dialog's backdrop z-index. Bootstrap appends the backdrop during
    // show(), and reuses the *same* element across shows of a kept-in-DOM modal — so a lift applied on
    // a previous open would otherwise persist as a stale inline z-index and leave the backdrop
    // floating above unrelated content on a later, non-lifted open. Always set it: raised alongside a
    // lifted dialog (so the popup behind is dimmed and click-blocked), or cleared back to the default
    // layer otherwise. Skipped when this dialog has no backdrop, so we never touch another modal's.
    if (config?.backdrop !== false) {
        const backdrops = document.querySelectorAll<HTMLElement>(".modal-backdrop");
        const ownBackdrop = backdrops[backdrops.length - 1];
        if (ownBackdrop) {
            ownBackdrop.style.zIndex = bumpedZIndex !== null ? String(bumpedZIndex - 1) : "";
        }
    }

    // After that normalising, which is written for a backdrop hanging at the end of the page and
    // would undo the layer this gives it there.
    showAboveWhateverHasTheScreen($dialog[0]);

    // After the backdrop has its final place in the page, because moving an element drops its focus.
    if (config?.focus !== false) {
        takeFocusUntilShown($dialog[0], config?.backdrop !== false);
    }

    $dialog.on("hidden.bs.modal", () => {
        sendDialogHome($dialog[0]);

        if (!glob.activeDialog || glob.activeDialog === $dialog) {
            focusSavedElement();
        }
    });

    keyboardActionsService.updateDisplayedShortcuts($dialog);

    return $dialog;
}

/**
 * Bootstrap moves focus into the dialog only when the opening transition ends. Until then, keeps
 * keystrokes out of the element that had focus, e.g. the note editor. Focus goes to the backdrop
 * where there is one, so a `focusout` handler can tell from `relatedTarget` that a dialog took it.
 */
function takeFocusUntilShown(dialogEl: HTMLElement, hasBackdrop: boolean) {
    const activeElement = document.activeElement;
    if (!(activeElement instanceof HTMLElement) || dialogEl.contains(activeElement)) {
        return;
    }

    const backdrops = document.querySelectorAll<HTMLElement>(".modal-backdrop");
    const ownBackdrop = hasBackdrop ? backdrops[backdrops.length - 1] : undefined;
    if (!ownBackdrop) {
        activeElement.blur();
        return;
    }

    ownBackdrop.tabIndex = -1;
    ownBackdrop.style.outline = "none";
    ownBackdrop.focus({ preventScroll: true });
}

/** Where a dialog stands while nothing has the screen, what came with it, and how to stop watching. */
const dialogHomes = new WeakMap<HTMLElement, {
    parent: Node;
    nextTo: Node | null;
    backdrop: HTMLElement | null;
    stopWatching: () => void;
}>();

/**
 * Puts a dialog where it can be seen and used over an element that has the screen to itself.
 *
 * A browser showing an element fullscreen draws that element and nothing else, and hands it every
 * press. A dialog lives in the shell rather than inside whatever was given the screen, so over a
 * fullscreen map or diagram (see `useFullscreen`) it was opened, focused and typed into while nothing
 * of it was ever painted — the quick editor reached for from a marker's preview simply swallowed the
 * click. Hosting it inside whatever is being shown puts it back on the screen and back in the way of
 * the pointer, exactly as the context menu is (see `hostInWhateverHasTheScreen`).
 *
 * Raising it into the top layer as a popover looks like the tidier answer and is not one: it is
 * painted there, above the fullscreen element, but every press still goes to the element underneath —
 * a dialog you can read and not use, which is worse than one you cannot see.
 *
 * The dialog is positioned against the viewport either way, so nothing about where it lands changes;
 * its backdrop goes with it, being at the end of the page too, and Bootstrap takes that away itself
 * whatever it is a child of.
 */
function showAboveWhateverHasTheScreen(dialogEl: HTMLElement) {
    const shownOver = document.fullscreenElement;
    const parent = dialogEl.parentNode;
    if (!shownOver || !parent || shownOver.contains(dialogEl)) {
        return;
    }

    // The screen may be given back while the dialog is still open — by pressing Escape, which the
    // browser answers itself — and the dialog belongs in the shell again the moment it is.
    const sendHomeOnScreenChange = () => sendDialogHome(dialogEl);
    document.addEventListener("fullscreenchange", sendHomeOnScreenChange);

    const backdrops = document.querySelectorAll<HTMLElement>(".modal-backdrop");
    const ownBackdrop = backdrops[backdrops.length - 1] ?? null;

    dialogHomes.set(dialogEl, {
        parent,
        nextTo: dialogEl.nextSibling,
        backdrop: ownBackdrop,
        stopWatching: () => document.removeEventListener("fullscreenchange", sendHomeOnScreenChange)
    });

    shownOver.appendChild(dialogEl);

    if (ownBackdrop) {
        // The dim comes along, ahead of the dialog rather than behind it, and on no layer of its
        // own. Bootstrap's 1050 would put it *over* a dialog the theme has lowered (a quick editor
        // sits at 999), which is a sheet of grey across the very thing that was opened; and reading
        // the dialog's own layer here is no answer either, since the rule that lowers it hangs on a
        // class the page has yet to be given. Standing first among equals settles it without a
        // number: the backdrop covers the map, being later in the page than the map is, and every
        // dialog worth the name is on a layer above zero.
        shownOver.insertBefore(ownBackdrop, dialogEl);
        ownBackdrop.style.zIndex = "0";
    }
}

/** Puts a dialog back where it was built. See {@link showAboveWhateverHasTheScreen}. */
function sendDialogHome(dialogEl: HTMLElement) {
    const home = dialogHomes.get(dialogEl);
    if (!home) return;

    dialogHomes.delete(dialogEl);
    home.stopWatching();
    home.parent.insertBefore(dialogEl, home.nextTo);

    if (home.backdrop) {
        // Back to the end of the page, where the rules that dress a backdrop can reach it again —
        // and without the layer it was lent, which the next open would otherwise inherit.
        home.backdrop.style.zIndex = "";
        document.body.appendChild(home.backdrop);
    }
}

export function closeActiveDialog() {
    if (glob.activeDialog) {
        Modal.getOrCreateInstance(glob.activeDialog[0]).hide();
        glob.activeDialog = null;
    }
}

/** Bootstrap's own modal layer, used by a dialog that declares no z-index. */
const STANDARD_MODAL_LAYER = 1055;

/** Self-managing popups (quick-edit, tree popup) set their own z-index via CSS; never lift them. */
const SELF_MANAGED_POPUP_SELECTOR = ".popup-editor-dialog, .tree-popup-editor-dialog";

/**
 * Raises a dialog above every modal already open, and returns the layer its backdrop must sit
 * just under.
 *
 * Two cases need the lift. A quick-edit or tree popup stacked on a modal sits at 1100, above the
 * standard 1055, so a dialog opened from it renders behind. Two dialogs that declare the same
 * layer tie, and DOM order decides, which is not the dialog just opened.
 *
 * The z-index is rewritten on every open so a lift does not outlive it, and `declaredZIndex`
 * (`Modal`'s `zIndex` prop) is what an unlifted dialog falls back to. A dialog that declares a
 * layer above everything open keeps it, but its backdrop is raised with it all the same: Bootstrap
 * puts the backdrop at 1050, under a modal at 1055, so a confirmation at 2000 asked from the
 * Options dialog would leave the settings undimmed beside it. Returns `null` when the backdrop can
 * stay on Bootstrap's own layer, which is when nothing else is open under the dialog.
 */
function raiseAboveWhatIsOpen(dialogEl: HTMLElement, declaredZIndex?: number): number | null {
    const others = Array.from(document.querySelectorAll<HTMLElement>(".modal.show"))
        .filter((modal) => modal !== dialogEl);
    const maxZIndex = others.reduce((max, modal) => Math.max(max, parseInt(getComputedStyle(modal).zIndex, 10) || 0), 0);

    const hasStackedPopup = document.body.classList.contains("popup-editor-stacked")
        || document.body.classList.contains("tree-popup-stacked");
    // The layer this dialog uses on its own, which decides whether anything open covers it.
    const own = declaredZIndex ?? STANDARD_MODAL_LAYER;
    const isCovered = hasStackedPopup || maxZIndex >= own;

    if (!isCovered || dialogEl.matches(SELF_MANAGED_POPUP_SELECTOR)) {
        dialogEl.style.zIndex = declaredZIndex ? String(declaredZIndex) : "";
        return declaredZIndex && others.length > 0 ? declaredZIndex : null;
    }

    // A dialog declaring a layer above everything open keeps it: the lift only raises.
    const zIndex = Math.max(maxZIndex + 10, own);
    dialogEl.style.zIndex = String(zIndex);
    return zIndex;
}

async function info(message: MessageType, extraProps?: InfoExtraProps) {
    return new Promise((res) => appContext.triggerCommand("showInfoDialog", { ...extraProps, message, callback: res }));
}

/**
 * Displays a confirmation dialog with the given message.
 *
 * @param message the message to display in the dialog. A string is rendered as HTML, sanitized by
 *                DOMPurify so the note titles and attribute names these questions name cannot inject
 *                markup; pass an element where the wording needs structure the dialog should not
 *                have to parse — an admonition warning about what the action costs, say.
 * @returns A promise that resolves to true if the user confirmed, false otherwise.
 */
async function confirm(message: MessageType) {
    return new Promise<boolean>((res) =>
        appContext.triggerCommand("showConfirmDialog", <ConfirmWithMessageOptions>{
            message,
            callback: (x: false | ConfirmDialogOptions) => res(x && x.confirmed)
        })
    );
}

/**
 * Shows a confirmation with an optional checkbox for deleting the notes it asks about.
 *
 * @param checkboxLabel labels the checkbox; omit it to show no checkbox.
 * @returns `confirmed` and `isDeleteNoteChecked`, or `false` when the dialog is dismissed.
 */
async function confirmWithNoteDeletion(message: MessageType, checkboxLabel?: string) {
    return new Promise<ConfirmDialogResult | undefined>((res) =>
        appContext.triggerCommand("showConfirmDialog", <ConfirmWithMessageOptions>{
            message,
            checkboxLabel,
            callback: res
        })
    );
}

/**
 * Asks whether a note should be taken off whatever is showing it, offering to delete the note along
 * with it.
 *
 * Hand it the target and the dialog works out for itself what accepting that offer would cost — the
 * note deleted outright, or merely one of its places removed — and says so under the checkbox. What
 * comes back says only whether the reader agreed and whether they ticked the box; carrying it out is
 * the caller's, through `deleteNoteOrBranch` in note_deletion.ts with the same target.
 *
 * @param title the note's title, which the stock question names.
 * @param deletionTarget the note and the placement it is being removed from. See
 *                       {@link NoteDeletionTarget}.
 * @param options the question to ask in place of the stock one, and whether removing the note from
 *                here deletes it whether the reader likes it or not.
 */
async function confirmDeleteNoteBoxWithNote(title: string, deletionTarget?: NoteDeletionTarget, options?: ConfirmDeleteNoteBoxOptions) {
    return new Promise<ConfirmDialogResult | undefined>((res) => appContext.triggerCommand("showConfirmDeleteNoteBoxWithNoteDialog", { ...options, title, callback: res, deletionTarget }));
}

/** Asks for a note, resolving to its id or to null where the reader picked none. */
export async function chooseNote(props: Omit<NotePickerDialogOptions, "callback"> = {}) {
    return new Promise<string | null>((res) =>
        appContext.triggerCommand("showNotePickerDialog", { ...props, callback: res }));
}

/**
 * Picks one item out of many, grouped and searchable.
 *
 * Named for the one thing it does now: picking several at once is the same dialog with a different
 * answer, and will be a method of its own beside this.
 *
 * @returns what was picked, or nothing where the reader backed out.
 */
export async function pickSingleItem(props: Omit<ItemPickerDialogOptions, "callback">) {
    return new Promise<PickerItem | null>((res) =>
        appContext.triggerCommand("showItemPickerDialog", { ...props, callback: res }));
}

export async function prompt(props: PromptDialogOptions) {
    return new Promise<string | null>((res) => appContext.triggerCommand("showPromptDialog", { ...props, callback: res }));
}

/**
 * Makes sure the resources `ids` are installed, asking to download those that are not and showing
 * the download.
 *
 * @returns `true` once every resource is installed, `false` when the download was declined,
 *   canceled or failed.
 */
export async function requireResources(ids: string[]) {
    const status = await server.get<ResourcesStatusResponse>(`resources?ids=${ids.map(encodeURIComponent).join(",")}`);
    if (status.resources.every(({ installed }) => installed)) {
        return true;
    }
    return new Promise<boolean>((res) =>
        appContext.triggerCommand("showResourceDownloadDialog", { ids, status, callback: res }));
}

export default {
    info,
    chooseNote,
    confirm,
    confirmWithNoteDeletion,
    confirmDeleteNoteBoxWithNote,
    pickSingleItem,
    prompt,
    requireResources
};