Skip to content

Build your personal knowledge base with Trilium Notes

11.2 KB
Raw Blame
import "./master_detail.css";
import "./slide_animations.css";

import clsx from "clsx";
import { ComponentChildren, createContext, RefObject } from "preact";
import { useCallback, useContext, useEffect, useRef, useState } from "preact/hooks";

import { onSystemBack } from "../../services/system_back";
import utils from "../../services/utils";
import ActionButton from "./ActionButton";
import { useWindowSize } from "./hooks";
import Modal, { ModalProps } from "./Modal";
import { useSlide } from "./SlidePages";

/**
 * The flow a dialog that pairs a list with a detail takes on a screen too narrow to hold both: one at a
 * time, the detail sliding in over the list and a way back in its header. Everything a dialog needs for
 * it lives here — the state and the classes ({@link useMobileMasterDetail}), the two panes
 * ({@link MasterPane}, {@link DetailPane}), the header ({@link MasterDetailHeader}) and their styling
 * (master_detail.css) — so that three dialogs do not each carry their own copy of the same slide.
 */

/** Mobile viewports at least this wide (tablets) keep a side-by-side layout; narrower ones get the
 *  master-detail flow. */
export const MASTER_DETAIL_TABLET_MIN_WIDTH = 768;

export interface MobileMasterDetail {
    /** True on narrow mobile viewports where the list and detail collapse into a master-detail flow. */
    isMasterDetail: boolean;
    /** Which half of the master-detail flow is currently visible. */
    mobileView: "list" | "page";
    /** Switch between the two views with a slide animation. */
    switchMobileView: (view: "list" | "page") => void;
    /** Set the view directly without animating (e.g. when (re)opening the dialog). */
    resetMobileView: (view: "list" | "page") => void;
}

/**
 * Drives the mobile master-detail flow: it tracks which pane is visible, animates the slide between
 * them, and toggles the corresponding classes on the modal element (`mobile-master-detail`,
 * `mobile-view-{list,page}`, `mobile-transition-to-{list,page}`), which master_detail.css lays out and
 * slides. The dialog's own stylesheet is left with whatever is particular to its panes.
 */
export function useMobileMasterDetail(modalRef: RefObject<HTMLElement | null>): MobileMasterDetail {
    const [ mobileView, setMobileView ] = useState<"list" | "page">("list");
    const isMobile = utils.isMobile();
    const { windowWidth } = useWindowSize();
    const isMasterDetail = isMobile && windowWidth < MASTER_DETAIL_TABLET_MIN_WIDTH;
    /** Whether the next change of view slides: a switch does, a reset does not. */
    const slideNext = useRef(false);
    // Outside the master-detail flow both panes are on show, and there is nothing to slide between.
    const slide = useSlide(mobileView, isMasterDetail && slideNext.current);
    // While set, both panes stay rendered so the outgoing one can slide away as the incoming one slides in.
    const mobileTransition = slide.from === undefined ? null : mobileView === "page" ? "to-page" : "to-list";

    const switchMobileView = useCallback((view: "list" | "page") => {
        slideNext.current = true;
        setMobileView(view);
    }, []);

    const { settle } = slide;
    const resetMobileView = useCallback((view: "list" | "page") => {
        slideNext.current = false;
        setMobileView(view);
        settle();
    }, [ settle ]);

    // Bootstrap adds its own classes (e.g. `show`) to the modal element at runtime, so the className
    // prop must stay static; toggle the mobile view classes directly on the element instead.
    useEffect(() => {
        modalRef.current?.classList.toggle("mobile-master-detail", isMasterDetail);
        modalRef.current?.classList.toggle("mobile-view-list", mobileView === "list");
        modalRef.current?.classList.toggle("mobile-view-page", mobileView === "page");
        modalRef.current?.classList.toggle("mobile-transition-to-list", mobileTransition === "to-list");
        modalRef.current?.classList.toggle("mobile-transition-to-page", mobileTransition === "to-page");
    }, [ isMasterDetail, mobileView, mobileTransition ]);

    // The slide's end bubbles up from the panes.
    const { onAnimationEnd } = slide;
    useEffect(() => {
        const modalElement = modalRef.current;
        if (!modalElement) return;
        modalElement.addEventListener("animationend", onAnimationEnd);
        return () => modalElement.removeEventListener("animationend", onAnimationEnd);
    }, [ onAnimationEnd ]);

    return { isMasterDetail, mobileView, switchMobileView, resetMobileView };
}

interface PaneProps {
    /** The dialog's own class for the pane, for whatever is particular to what is in it. */
    className?: string;
    children: ComponentChildren;
}

/** The list half of the flow. Rendered inside the modal body, the Modal sidebar being unused there. */
export function MasterPane({ className, children }: PaneProps) {
    return <div class={clsx("tn-master-pane", className)}>{children}</div>;
}

/** The half the list leads to, which slides in over it. */
export function DetailPane({ className, children }: PaneProps) {
    return <div class={clsx("tn-detail-pane", className)}>{children}</div>;
}

interface MasterDetailHeaderProps {
    /** Whether the detail is what is on show, which is what the header is a way back from. */
    inPage: boolean;
    onBack: () => void;
    /** The back button's tooltip: where it goes back to, in the dialog's own words. */
    backTitle: string;
    /** What the detail on show is called. */
    pageTitle?: ComponentChildren;
    /** What the dialog is called, shown while the list is. */
    listTitle: ComponentChildren;
    /** A decorative icon for the list view, standing where the back button stands in the other. */
    listIcon?: string;
    /** The dialog's own actions, which belong to the list rather than to one page of it. */
    listActions?: ComponentChildren;
    /**
     * Actions belonging to the page on show. The header carries the page's name here, so a control
     * that explains or acts on the page as a whole reads beside it rather than inside the page.
     */
    pageActions?: ComponentChildren;
}

/**
 * The header of a master-detail modal, in place of its static title (which master_detail.css hides):
 * the way back and the name of what is on show, or the dialog's own name while the list is.
 */
export function MasterDetailHeader({
    inPage, onBack, backTitle, pageTitle, listTitle, listIcon, listActions, pageActions
}: MasterDetailHeaderProps) {
    const back = useRef(onBack);
    back.current = onBack;
    useEffect(() => {
        if (!inPage) return;
        return onSystemBack(() => {
            back.current();
            return true;
        });
    }, [ inPage ]);

    return (
        <div class="tn-master-detail-header">
            {inPage ? (
                <ActionButton icon="bx bx-chevron-left" text={backTitle} onClick={onBack} />
            ) : (
                // Borrows `icon-action` so it keeps exactly the back button's footprint, and the title
                // does not shift as the views change.
                listIcon && <span class={clsx("tn-master-detail-icon icon-action", listIcon)} aria-hidden="true" />
            )}
            {/* A page that names itself passes no title, and gets no room taken for one. */}
            {(inPage ? pageTitle : listTitle) && (
                <h5 class="tn-master-detail-title">{inPage ? pageTitle : listTitle}</h5>
            )}
            {inPage
                ? pageActions && <div class="tn-master-detail-page-actions">{pageActions}</div>
                : listActions}
        </div>
    );
}

interface MasterDetailState {
    /** Whether the host is showing one pane at a time, with the other sliding in over it. */
    isMasterDetail: boolean;
    /**
     * Announces the page being shown to the host, so that it can head it and slide to it: its title,
     * and how to leave it. A `null` title means the list is what is on show.
     */
    showPage: (title: string | null, close: () => void) => void;
}

const MasterDetailContext = createContext<MasterDetailState>({
    isMasterDetail: false,
    showPage: () => {}
});

/** What a component nested in a master-detail modal knows of the flow it is part of. */
export function useMasterDetail() {
    return useContext(MasterDetailContext);
}

/**
 * Hands the page a component is showing to the master-detail host around it — the host heads it with the
 * title and slides to it, and its back button calls `close`. Outside such a host this does nothing, so a
 * component that can be shown in either place needs no second version of itself.
 */
export function useMasterDetailPage(title: string | null, close: () => void) {
    const { showPage } = useMasterDetail();
    // Read at press time rather than captured: what closing the page means changes as it is edited.
    const closeRef = useRef(close);
    closeRef.current = close;

    useEffect(() => showPage(title, () => closeRef.current()), [ title, showPage ]);
}

/**
 * A modal whose contents are a master-detail flow: it drives the flow, heads the page on show with a way
 * back, and lets whatever is inside it announce that page ({@link useMasterDetailPage}) rather than
 * having to be handed down to the pieces that draw it.
 */
export function MasterDetailModal({ backTitle, listIcon, listActions, children, ...modalProps }: ModalProps & {
    backTitle: string;
    listIcon?: string;
    listActions?: ComponentChildren;
}) {
    const modalRef = useRef<HTMLDivElement>(null);
    const [ page, setPage ] = useState<{ title: string; close: () => void } | null>(null);
    const { isMasterDetail, mobileView, switchMobileView, resetMobileView } = useMobileMasterDetail(modalRef);

    const showPage = useCallback((title: string | null, close: () => void) => {
        // Whatever was announced last, `close` included: two pages of the same name are still two pages,
        // and holding on to the first one's would be closing something else than what is on show.
        setPage(title === null ? null : { title, close });
        switchMobileView(title === null ? "list" : "page");
    }, [ switchMobileView ]);

    // Opens on the list, whatever page a previous show was left on. Hiding closes the page, so that a
    // modal kept in the DOM (`keepInDom`) leaves no page for the system back gesture to act on.
    const pageRef = useRef(page);
    pageRef.current = page;
    const wasShown = useRef(false);
    useEffect(() => {
        if (modalProps.show) {
            resetMobileView("list");
        } else if (wasShown.current) {
            pageRef.current?.close();
        }
        wasShown.current = modalProps.show;
    }, [ modalProps.show, resetMobileView ]);

    return (
        <Modal
            {...modalProps}
            modalRef={modalRef}
            header={isMasterDetail ? (
                <MasterDetailHeader
                    inPage={mobileView === "page"}
                    onBack={() => page?.close()}
                    backTitle={backTitle}
                    pageTitle={page?.title}
                    listTitle={modalProps.title}
                    listIcon={listIcon}
                    listActions={listActions}
                />
            ) : modalProps.header}
        >
            <MasterDetailContext.Provider value={{ isMasterDetail, showPage }}>
                {children}
            </MasterDetailContext.Provider>
        </Modal>
    );
}