Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import "./Modal.css";
import { Modal as BootstrapModal } from "bootstrap";
import clsx from "clsx";
import { ComponentChildren, createPortal, CSSProperties, RefObject } from "preact";
import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "preact/hooks";
import appContext from "../../components/app_context";
import { openDialog } from "../../services/dialog";
import { t } from "../../services/i18n";
import { RENDER_SCOPE_CLASS } from "../../services/render_css_scope";
import { onSystemBack } from "../../services/system_back";
import { openInAppHelpFromUrl } from "../../services/utils";
import { useSyncedRef } from "./hooks";
import { suspendModalFocusTraps } from "./modal_focustrap";
import { ContainerVisibilityContext } from "./react_utils";
interface CustomTitleBarButton {
title: string;
iconClassName: string;
onClick: (e: MouseEvent) => void;
}
export interface ModalProps {
className?: string;
title?: string | ComponentChildren;
customTitleBarButtons?: (CustomTitleBarButton | null)[];
size: "xl" | "lg" | "md" | "sm";
children: ComponentChildren;
/**
* Items to display in the modal header, apart from the title itself which is handled separately.
*/
header?: ComponentChildren;
footer?: ComponentChildren;
footerStyle?: CSSProperties;
footerAlignment?: "right" | "between";
minWidth?: string;
maxWidth?: number;
zIndex?: number;
/**
* If true, the modal body will be scrollable if the content overflows.
* This is useful for larger modals where you want to keep the header and footer visible
* while allowing the body content to scroll.
* Defaults to false.
*/
scrollable?: boolean;
/**
* If set, the modal body and footer will be wrapped in a form and the submit event will call this function.
* Especially useful for user input that can be submitted with Enter key.
*/
onSubmit?: () => void;
/** Called when the modal is shown. */
onShown?: () => void;
/**
* Called when the modal is hidden, either via close button, backdrop click or submit.
*
* Here it's generally a good idea to set `show` to false to reflect the actual state of the modal.
*/
onHidden: () => void;
helpPageId?: string;
/**
* Gives access to the underlying modal element. This is useful for manipulating the modal directly
* or for attaching event listeners.
*/
modalRef?: RefObject<HTMLDivElement | null>;
/**
* Gives access to the underlying form element of the modal. This is only set if `onSubmit` is provided.
*/
formRef?: RefObject<HTMLFormElement | null>;
bodyStyle?: CSSProperties;
/**
* Controls whether the modal is shown. Setting it to `true` will trigger the modal to be displayed to the user, whereas setting it to `false` will hide the modal.
* This method must generally be coupled with `onHidden` in order to detect when the modal was closed externally (e.g. by the user clicking on the backdrop or on the close button).
*/
show: boolean;
/**
* By default displaying a modal will close all existing modals. Set this to true to keep the existing modals open instead. This is useful for confirmation modals.
*/
stackable?: boolean;
/**
* If true, the modal will remain in the DOM even when not shown. This can be useful for certain CSS transitions or when you want to avoid re-mounting the modal content.
*/
keepInDom?: boolean;
/**
* If true, the modal will not focus itself after becoming visible.
*/
noFocus?: boolean;
/**
* Content to display as a full-height sidebar on the left side of the modal.
* When set, the modal layout switches to a horizontal split with the sidebar
* spanning the entire height alongside the header, body and footer.
*/
sidebar?: ComponentChildren;
/**
* By default a sidebar modal repeats {@link title} as a header above the sidebar. Set this to
* skip that header — useful when {@link title} is the active note's own title (which belongs in
* the main header, not duplicated over the sidebar).
*/
hideSidebarHeader?: boolean;
/**
* Indicates if the dialog will be displayed as a full page on mobile devices.
*/
isFullPageOnMobile?: boolean;
/**
* What assistive technology announces the dialog as, for a dialog whose {@link title} is not a
* name it can read — one shown without a title at all, above all, which would otherwise be
* announced as nothing but "dialog".
*/
ariaLabel?: string;
}
export default function Modal({ children, className = "", size, title, customTitleBarButtons: titleBarButtons, header, footer, footerStyle, footerAlignment, onShown, onSubmit, helpPageId, minWidth, maxWidth, zIndex, scrollable, onHidden, modalRef: externalModalRef, formRef, bodyStyle, show, stackable, keepInDom, noFocus, sidebar, hideSidebarHeader, isFullPageOnMobile, ariaLabel }: ModalProps) {
const modalRef = useSyncedRef<HTMLDivElement>(externalModalRef);
const modalInstanceRef = useRef<BootstrapModal | undefined>(undefined);
const elementToFocus = useRef<Element | null | undefined>(undefined);
/*
* Bootstrap writes classes of its own onto this element — `show` above all, which is what makes
* a dialog visible — and Preact sets `className` in full whenever the prop changes, which takes
* them off again. The rendered attribute is therefore held at what the first render gave it,
* and the host's own classes are added and removed by hand below: a host that names what it is
* showing in its class (the note's colour, say) must be able to change it without putting its
* own dialog out.
*/
const renderedClassName = useRef(`modal fade mx-auto ${className}`);
const hostClasses = useRef(splitClasses(className));
useLayoutEffect(() => {
const modalElement = modalRef.current;
if (!modalElement) return;
const classes = splitClasses(className);
for (const cls of hostClasses.current) {
if (!classes.includes(cls)) {
modalElement.classList.remove(cls);
}
}
modalElement.classList.add(...classes);
hostClasses.current = classes;
}, [ className ]);
useEffect(() => {
const modalElement = modalRef.current;
if (!modalElement) return;
/*
* Bootstrap's modal events are native events, and native events bubble. A stacked modal is a
* DOM descendant of the one it opened over, so without this its opening and closing would be
* reported to every modal underneath as their own — closing the Options dialog the moment a
* dialog opened from inside it is dismissed.
*/
const ownEvent = (handler: () => void) => (event: Event) => {
if (event.target === modalElement) {
handler();
}
};
const onModalShown = onShown && ownEvent(onShown);
const onModalHidden = ownEvent(() => {
onHidden();
if (elementToFocus.current && "focus" in elementToFocus.current) {
(elementToFocus.current as HTMLElement).focus();
}
});
if (onModalShown) {
modalElement.addEventListener("shown.bs.modal", onModalShown);
}
modalElement.addEventListener("hidden.bs.modal", onModalHidden);
return () => {
if (onModalShown) {
modalElement.removeEventListener("shown.bs.modal", onModalShown);
}
modalElement.removeEventListener("hidden.bs.modal", onModalHidden);
};
}, [ onShown, onHidden ]);
// While this modal is shown, ensure it is the only modal trapping focus. Bootstrap has no stacked
// modal support: every underlying modal keeps its own focus-trap active and steals focus from inputs
// in the modal on top (e.g. the custom-dictionary editor in the quick-edit popup that opens over the
// Options dialog gets no cursor). Suspend the other modals' traps here and restore them on close.
//
// Must run before the effect that opens the dialog: `openDialog` focuses the new backdrop, and
// a trap still active at that point pulls focus into the modal underneath.
useEffect(() => {
if (!show || !modalRef.current) return;
return suspendModalFocusTraps(modalRef.current);
}, [ show ]);
useEffect(() => {
if (!show) return;
return onSystemBack(() => {
modalInstanceRef.current?.hide();
return true;
});
}, [ show ]);
useEffect(() => {
if (show && modalRef.current) {
elementToFocus.current = document.activeElement;
openDialog($(modalRef.current), !stackable, {
focus: !noFocus
}, zIndex).then(($widget) => {
modalInstanceRef.current = BootstrapModal.getOrCreateInstance($widget[0]);
});
} else {
const instance = modalInstanceRef.current;
instance?.hide();
/*
* Bootstrap drops a `hide()` made while the dialog is still opening — it is guarded on
* an internal `_isTransitioning`, which stands for the ~300ms the opening takes — and
* says nothing about having dropped it. A dialog told to close within that window (a
* picker closing itself on the first thing tapped, say) would be left open for good,
* and since our own tree has already emptied it, what stays on the screen is an empty
* sheet and its backdrop over a page that can no longer be pressed.
*
* A `hide()` that was carried out takes the class off at once, so a dialog still
* wearing it is one whose closing was dropped. Say it again the moment the opening
* lands, which is what `shown.bs.modal` reports.
*/
const modalElement = modalRef.current;
if (instance && modalElement?.classList.contains("show")) {
const hideOnceShown = () => instance.hide();
modalElement.addEventListener("shown.bs.modal", hideOnceShown, { once: true });
// Dropped in turn if the dialog is asked to open again before the first one lands.
return () => modalElement.removeEventListener("shown.bs.modal", hideOnceShown);
}
}
/*
* Not on `modalRef.current`, though the effect reads it. A ref holds nothing while the
* render that names the dependencies is running and the element by the time the effect
* runs, so listing it makes the first re-render after mounting look like a change and open
* the dialog a second time — and opening closes whatever dialog is active, which by then is
* this one (see openDialog). The dialog would put itself away on the first keystroke typed
* into it, telling its host it had been dismissed.
*
* A dialog that starts closed never showed it: `show` was false for those first renders, so
* the spurious run took the closing arm and did nothing, and by the time it opened the ref
* had long settled. Only one raised already open — the calendar's ghost — met it.
*
* Nothing is lost by leaving it out: the element the ref names is rendered unconditionally
* (see below), so it is always there by the time an effect could read it.
*/
}, [ show, noFocus, zIndex ]);
/*
* A dialog may be taken out of the tree while it is still up — a host that closes it by ceasing
* to draw it rather than by turning `show` off, which is what a dialog raised for something
* that then goes does (the calendar's ghost, once its event is made). Bootstrap keeps the
* backdrop on the body rather than within the dialog, and the class that stills the page behind
* it likewise, so nothing would take either away: what is left is a dimmed page that cannot be
* pressed or scrolled, with no dialog on it to explain itself.
*
* Told to hide as it goes, Bootstrap sees its own teardown through even with the element
* detached — the transition it waits on has a timer behind it — and a dialog that was already
* hidden is told nothing, `hide()` being a no-op once it is down.
*/
useEffect(() => () => {
modalInstanceRef.current?.hide();
}, []);
// Memoize styles to prevent recreation on every render
const dialogStyle = useMemo<CSSProperties>(() => {
const style: CSSProperties = {};
if (zIndex) {
style.zIndex = zIndex;
}
return style;
}, [zIndex]);
const documentStyle = useMemo<CSSProperties>(() => {
const style: CSSProperties = {};
if (maxWidth) {
style.maxWidth = `${maxWidth}px`;
}
if (minWidth) {
style.minWidth = minWidth;
}
return style;
}, [maxWidth, minWidth]);
const [ dialogElement, setDialogElement ] = useState<HTMLDivElement | null>(null);
const isTall = useIsTallerThanHalfScreen(dialogElement);
return (
<div className={renderedClassName.current} tabIndex={-1} style={dialogStyle} role="dialog" aria-label={ariaLabel} ref={modalRef}>
{(show || keepInDom) && <ContainerVisibilityContext.Provider value={show}><div className={clsx("modal-dialog", `modal-${size}`, {"modal-dialog-scrollable": scrollable, "modal-dialog-full-page-on-mobile": isFullPageOnMobile, "modal-content-with-sidebar": sidebar, "modal-dialog-tall": isTall})} style={documentStyle} role="document" ref={setDialogElement}>
<div className={clsx("modal-content", sidebar && "modal-content-with-sidebar")}>
{sidebar && <div className="modal-sidebar">
{title && !hideSidebarHeader && <div className="modal-sidebar-header">
<h5>{title}</h5>
</div>}
{sidebar}
</div>}
<ModalMain sidebar={!!sidebar}>
<div className="modal-header">
{!title || typeof title === "string" ? (
<h5 className="modal-title">{title ?? <> </>}</h5>
) : (
title
)}
{header}
{helpPageId && (
<button
className="help-button"
type="button"
title={t("modal.help_title")}
onClick={() => appContext.triggerCommand("openInPopup", { noteIdOrPath: `_help_${helpPageId}` })}
>?</button>
)}
{titleBarButtons?.filter((b) => b !== null).map((titleBarButton) => (
<button type="button"
className={clsx("custom-title-bar-button bx", titleBarButton.iconClassName)}
title={titleBarButton.title}
onClick={titleBarButton.onClick} />
))}
<button type="button" className="btn-close" data-bs-dismiss="modal" aria-label={t("modal.close")} />
</div>
{onSubmit ? (
<form ref={formRef} onSubmit={(e) => {
e.preventDefault();
onSubmit();
}}>
<ModalInner footer={footer} bodyStyle={bodyStyle} footerStyle={footerStyle} footerAlignment={footerAlignment}>{children}</ModalInner>
</form>
) : (
<ModalInner footer={footer} bodyStyle={bodyStyle} footerStyle={footerStyle} footerAlignment={footerAlignment}>
{children}
</ModalInner>
)}
</ModalMain>
</div>
</div></ContainerVisibilityContext.Provider>}
</div>
);
}
/** Mounts a script modal beside Bootstrap's body-level backdrop while retaining its source context. */
export function ScriptModal(props: ModalProps) {
const [ origin, setOrigin ] = useState<HTMLTemplateElement | null>(null);
const ntxId = origin?.closest("[data-ntx-id]")?.getAttribute("data-ntx-id");
const isRenderNote = !!origin?.closest(`.note-detail-render-content, .${RENDER_SCOPE_CLASS}`);
return <>
<template ref={setOrigin} />
{origin && createPortal(
<div className={clsx("script-modal-host", isRenderNote && RENDER_SCOPE_CLASS)} data-ntx-id={ntxId}>
<Modal {...props} />
</div>,
document.body
)}
</>;
}
/**
* Whether the dialog takes up more than half the screen. iOS shows such a dialog as an opaque sheet
* attached to the screen's edges, and a shorter one as a floating glass sheet. A tall dialog turns
* short again only below 45%, since the wider tall sheet can rewrap its content a little shorter.
*/
function useIsTallerThanHalfScreen(dialog: HTMLElement | null) {
const [ isTall, setIsTall ] = useState(false);
useEffect(() => {
if (!dialog) return;
const update = () => setIsTall((wasTall) => dialog.offsetHeight > window.innerHeight * (wasTall ? 0.45 : 0.5));
const observer = new ResizeObserver(update);
observer.observe(dialog);
window.addEventListener("resize", update);
return () => {
observer.disconnect();
window.removeEventListener("resize", update);
};
}, [ dialog ]);
return isTall;
}
/** The classes a host asked for, as `classList` takes them. */
function splitClasses(className: string) {
return className.split(" ").filter((cls) => cls !== "");
}
function ModalMain({ sidebar, children }: { sidebar: boolean; children: ComponentChildren }) {
if (sidebar) {
return <div className="modal-main">{children}</div>;
}
return <>{children}</>;
}
function ModalInner({ children, footer, footerAlignment, bodyStyle, footerStyle: _footerStyle }: Pick<ModalProps, "children" | "footer" | "footerAlignment" | "bodyStyle" | "footerStyle">) {
// Memoize footer style
const footerStyle = useMemo<CSSProperties>(() => {
const style: CSSProperties = _footerStyle ?? {};
if (footerAlignment === "between") {
style.justifyContent = "space-between";
}
return style;
}, [_footerStyle, footerAlignment]);
return (
<>
<div className="modal-body" style={bodyStyle}>
{children}
</div>
{footer && (
<div className="modal-footer" style={footerStyle}>
{footer}
</div>
)}
</>
);
}