Skip to content

Build your personal knowledge base with Trilium Notes

18.7 KB
Raw Blame
import type { Placement } from "@floating-ui/dom";
import type { Tooltip } from "bootstrap";
import clsx from "clsx";
import {
    ButtonHTMLAttributes, ComponentChildren, CSSProperties, HTMLAttributes, RefObject
} from "preact";
import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "preact/hooks";

import type { MenuItem } from "../../menus/context_menu";
import { isMobile, isNarrowLayout, onNarrowLayoutChange } from "../../services/utils";
import { focusListItem } from "./FormList";
import { useBodyClass, useTooltip, useUniqueName } from "./hooks";
import { suspendModalFocusTraps } from "./modal_focustrap";
import Menu from "./Menu";
import Popup, { type PopupProps } from "./Popup";

type DataAttributes = {
    [key: `data-${string}`]: string | number | boolean | undefined;
};

export interface DropdownProps extends Pick<HTMLAttributes<HTMLDivElement>, "id" | "className"> {
    buttonClassName?: string;
    buttonProps?: Partial<ButtonHTMLAttributes<HTMLButtonElement> & DataAttributes>;
    children?: ComponentChildren;
    /**
     * For a {@link Dropdown}, its rows as data instead of {@link children}: a row runs its
     * `handler`, then closes the menu.
     */
    items?: MenuItem<unknown>[];
    /**
     * For a {@link Dropdown} of {@link items}, or of children whose rows `MenuItemRows` draws,
     * offers an input at its top that filters them.
     */
    filterable?: boolean;
    /** For a {@link filterable} menu above its toggle, keeps the rows in their own order. */
    keepOrder?: boolean;
    title?: string;
    dropdownContainerStyle?: CSSProperties;
    dropdownContainerClassName?: string;
    dropdownContainerRef?: RefObject<HTMLDivElement | null>;
    hideToggleArrow?: boolean;
    /** If set to true, then the dropdown button will be considered an icon action (without normal border and sized for icons only). */
    iconAction?: boolean;
    noSelectButtonStyle?: boolean;
    /**
     * Leaves the look of the toggle to {@link buttonClassName} alone, without Bootstrap's `btn`, for a
     * toggle on a surface that styles its own buttons, such as an `OverlayControlGroup`.
     */
    bareButton?: boolean;
    /** Disables the toggle, and closes the popup if it is open. */
    disabled?: boolean;
    text?: ComponentChildren;
    onShown?: () => void;
    onHidden?: () => void;
    /** The side of the toggle the popup prefers; it flips to the other near the viewport's edge. */
    placement?: Placement;
    /**
     * What closes the popup besides Escape and the toggle: `true` a click inside and a press
     * outside, `"inside"` or `"outside"` that one alone, `false` neither. A row that stops its click
     * keeps a menu open whatever this says.
     */
    autoClose?: boolean | "inside" | "outside";
    dropdownRef?: RefObject<DropdownHandle | null>;
    titlePosition?: "top" | "right" | "bottom" | "left";
    titleOptions?: Partial<Tooltip.Options>;
    /**
     * For a launcher bar menu: on a phone, dims the page above the bar and leaves the popup to the
     * stylesheet, which pins it above the bar. On a tablet's wider mobile layout, the popup opens
     * beside its toggle over the dimmed page. No effect on a desktop layout.
     */
    mobileBackdrop?: boolean;
    /**
     * On a phone, shows the popup as a sheet rising from the bottom of the screen over a dimmed
     * page, the way the app's other mobile menus appear. On a tablet's wider mobile layout, the
     * popup opens beside its toggle over the dimmed page instead. No effect on a desktop layout.
     */
    mobileBottomSheet?: boolean;
    /**
     * Dims the page behind the popup on any screen, for one that is a task of its own rather than
     * a list of actions: the icon picker, which holds a search field and a grid of a thousand
     * icons. Drawn in the popup's portal, immediately before it.
     */
    backdrop?: boolean;
}

export interface DropdownPanelProps extends DropdownProps {
    /**
     * Caps the panel to the room beside its toggle and scrolls its content inside it, for content
     * that can outgrow the screen. The panel's frame stays put, so the theme's blur on its
     * `::before` covers it whatever the content scrolls to.
     */
    scrollable?: boolean;
}

/** Opens and closes a dropdown from outside it, for a caller that decides when. */
export interface DropdownHandle {
    show(): void;
    hide(): void;
    toggle(): void;
}

/** The gap, in pixels, between the toggle and its popup, as Bootstrap's dropdowns kept. */
const TOGGLE_GAP = 2;

/**
 * A menu under a toggle: its rows are `FormListItem`s and the other `FormList` rows, which the
 * menu's keys move between. For anything else, such as a picker or a form, use {@link DropdownPanel}.
 */
export default function Dropdown(props: DropdownProps) {
    return (
        <DropdownToggle
            {...props}
            hasPopup="menu"
            popup={({ popupProps, className, bottomSheet, startAt, isWanted, dismiss, close }) => (
                <Menu
                    {...popupProps}
                    className={className}
                    bottomSheet={bottomSheet}
                    startAt={startAt}
                    isWanted={isWanted}
                    items={props.items}
                    filterable={props.filterable}
                    keepOrder={props.keepOrder}
                    onSelect={(item, e) => {
                        item.handler?.(item, e);
                        if (!item.items) close();
                    }}
                    onDismiss={() => dismiss("outside")}
                    onClose={close}
                >
                    {props.children}
                </Menu>
            )}
        />
    );
}

/**
 * A popup under a toggle for content other than a menu's rows, such as a picker, a form or a
 * list of links. Its fields keep their keys; Up and Down move between its `.dropdown-item`s.
 */
export function DropdownPanel({ scrollable, ...props }: DropdownPanelProps) {
    return (
        <DropdownToggle
            {...props}
            hasPopup="true"
            onToggleArrow={(popup, edge) => focusListItem(popup, edge)}
            popup={({ popupProps, className, bottomSheet, startAt, dismiss }) => (
                <PanelPopup
                    {...popupProps}
                    // Otherwise it grows with its content, as Bootstrap's dropdowns did.
                    capHeight={!!scrollable}
                    placedByStylesheet={popupProps.placedByStylesheet}
                    reveal
                    className={clsx("dropdown-menu show", className, bottomSheet && "mobile-bottom-menu")}
                    startAt={startAt}
                    onDismiss={dismiss}
                >
                    {scrollable
                        ? <div className="tn-panel-scroll">{props.children}</div>
                        : props.children}
                </PanelPopup>
            )}
        />
    );
}

/** What {@link DropdownToggle} hands the popup it draws. */
interface PopupSlot {
    /** Placement, portal, backdrop and click handling, for the `Popup` or `Menu`. */
    popupProps: Pick<PopupProps, "anchor" | "placement" | "offset" | "portalClassName" | "backdropClassName"
        | "elementRef" | "style" | "aria-labelledby" | "onClick" | "placedByStylesheet">;
    className: string;
    bottomSheet: boolean;
    /** The item to start at, for a popup a key on the toggle opened. */
    startAt: "first" | "last" | undefined;
    isWanted(): boolean;
    /** Closes it for a press outside or Escape, as `autoClose` allows. */
    dismiss(reason: "outside" | "escape"): void;
    close(): void;
}

/**
 * The toggle both kinds of dropdown share: the button, its tooltip, the open state and its
 * callbacks, the handle, and the phone's cover. `popup` draws what opens under it.
 */
function DropdownToggle({ id, className, buttonClassName, title, text, dropdownContainerStyle, dropdownContainerClassName, dropdownContainerRef: externalContainerRef, hideToggleArrow, iconAction, disabled, noSelectButtonStyle, bareButton, onShown, onHidden, placement, autoClose = true, buttonProps, dropdownRef, titlePosition, titleOptions, mobileBackdrop: mobileBackdropProp, mobileBottomSheet, backdrop, hasPopup, onToggleArrow, popup }: Omit<DropdownProps, "children"> & {
    hasPopup: "menu" | "true";
    /** Called for Up or Down on the toggle while the popup is up. */
    onToggleArrow?(popup: HTMLElement, edge: "first" | "last"): void;
    popup(slot: PopupSlot): ComponentChildren;
}) {
    // The sheet is placed by the app's own rule and dims what is behind it, so it is asked for as
    // one thing and unpacked here. It follows the layout, as a tablet can turn while it is open.
    const followsLayout = (!!mobileBottomSheet || !!mobileBackdropProp) && isMobile();
    const [ narrow, setNarrow ] = useState(isNarrowLayout);
    useEffect(() => {
        if (!followsLayout) return;
        setNarrow(isNarrowLayout());
        return onNarrowLayoutChange(() => setNarrow(isNarrowLayout()));
    }, [ followsLayout ]);
    const bottomSheet = followsLayout && narrow && !!mobileBottomSheet;
    // A launcher bar menu on a phone is pinned above the bar by `style.css`.
    const pinnedAboveBar = followsLayout && narrow && !mobileBottomSheet;
    const mobileBackdrop = (!!mobileBackdropProp || !!mobileBottomSheet) && isMobile();
    const containerRef = useRef<HTMLDivElement | null>(null);
    const triggerRef = useRef<HTMLButtonElement | null>(null);
    const popupRef = useRef<HTMLDivElement | null>(null);
    const [ shown, setShown ] = useState(false);
    useBodyClass("backdrop-open", shown && (!!backdrop || mobileBackdrop));
    /** The item to start at once the popup shows, for a popup a key on the toggle opened. */
    const [ startAt, setStartAt ] = useState<"first" | "last">();

    // Memoized so useTooltip's effect (keyed on config identity) doesn't dispose and recreate the
    // Bootstrap tooltip on every re-render — only when the title (or positioning) actually changes.
    const tooltipConfig = useMemo<Partial<Tooltip.Options>>(() => ({
        ...titleOptions,
        // Bootstrap reads the `title` attribute once, so a dynamic title is driven from config.
        // Bootstrap rejects `undefined`; "" shows no tooltip.
        title: title ?? titleOptions?.title ?? "",
        placement: titlePosition ?? "bottom",
        fallbackPlacements: [ titlePosition ?? "bottom" ]
    }), [ title, titleOptions, titlePosition ]);
    // On the wrapper, and silenced while the popup is up, so the title does not hang over it.
    const { hideTooltip } = useTooltip(containerRef, tooltipConfig, !shown);

    // Every open and close goes through here, which says so at once, as Bootstrap's events did
    // within the press: a caller holding something open for the menu's sake, such as the board's
    // card editor, must know before the focus the press moves reaches it.
    const shownRef = useRef(shown);
    const callbacks = useRef({ onShown, onHidden, hideTooltip });
    callbacks.current = { onShown, onHidden, hideTooltip };
    const restoreFocusTraps = useRef<(() => void) | null>(null);
    const setOpen = useCallback((open: boolean) => {
        if (shownRef.current === open) return;
        shownRef.current = open;
        // A dialog's focus trap would pull focus out of a popup that stands outside the dialog. The
        // traps go before the render, since a bottom sheet takes focus in the effect that places it.
        if (open) {
            restoreFocusTraps.current = suspendModalFocusTraps();
        }
        // Focus that the popup holds goes back to the toggle, as a native menu button's does; a
        // command that moved it elsewhere keeps it there.
        if (!open && popupRef.current?.contains(document.activeElement)) triggerRef.current?.focus();
        if (!open) {
            restoreFocusTraps.current?.();
            restoreFocusTraps.current = null;
        }
        if (!open) setStartAt(undefined);
        setShown(open);
        if (open) {
            callbacks.current.hideTooltip();
            callbacks.current.onShown?.();
        } else {
            callbacks.current.onHidden?.();
        }
    }, []);

    useLayoutEffect(() => {
        if (externalContainerRef) externalContainerRef.current = containerRef.current;
    }, [ externalContainerRef ]);

    useLayoutEffect(() => {
        if (!dropdownRef) return;
        dropdownRef.current = {
            show: () => setOpen(true),
            hide: () => setOpen(false),
            toggle: () => setOpen(!shownRef.current)
        };
    }, [ dropdownRef ]);

    // A disabled toggle cannot be pressed to close its popup, so disabling it closes the popup.
    useLayoutEffect(() => {
        if (disabled) setOpen(false);
    }, [ disabled ]);

    // The popup anchors to `triggerRef`, which is empty during the first render, so a dropdown shown
    // from the start renders again once the toggle is mounted, before the browser paints.
    const [ , setTriggerMounted ] = useState(false);
    useLayoutEffect(() => {
        if (shownRef.current) setTriggerMounted(true);
    }, []);

    // On a phone the shell's cover dims the page under the popup; a tap on it closes the popup,
    // being one outside it.
    useEffect(() => {
        if (!shown || !mobileBackdrop) return;
        const cover = document.getElementById("context-menu-cover");
        cover?.classList.add("show", "global-menu-cover");
        return () => cover?.classList.remove("show", "global-menu-cover");
    }, [ shown, mobileBackdrop ]);

    useEffect(() => () => restoreFocusTraps.current?.(), []);

    const ariaId = useUniqueName("button");
    const toggleId = id ?? ariaId;

    /** Closes it on a click inside, as Bootstrap's `autoClose` did, for content that is no row of a menu. */
    function closeOnClickInside(e: MouseEvent) {
        if (autoClose === "outside" || autoClose === false) return;
        const target = e.target as Element;
        // Neither the menu's own padding nor a field in it closes it.
        if (target === e.currentTarget || /input|select|option|textarea|form/i.test(target.tagName)) return;
        setOpen(false);
    }

    return (
        // `title` stands in only for the moment before the tooltip is wired: Bootstrap moves the
        // attribute into the tooltip and drops it, so the browser's own doesn't double up with ours.
        <div ref={containerRef} class={`dropdown ${className ?? ""}`} style={{ display: "flex" }} title={title}>
            <button
                {...buttonProps}
                className={clsx(
                    iconAction ? "icon-action" : !bareButton && "btn",
                    // `.icon-action` styles its disabled state by class, as `ActionButton` sets it.
                    iconAction && disabled && "disabled",
                    !noSelectButtonStyle && "select-button",
                    buttonClassName,
                    !hideToggleArrow && "dropdown-toggle",
                    shown && "show"
                )}
                ref={triggerRef}
                type="button"
                aria-haspopup={hasPopup}
                aria-expanded={shown}
                id={toggleId}
                disabled={disabled}
                onClick={(e) => {
                    buttonProps?.onClick?.(e);
                    setOpen(!shownRef.current);
                }}
                // Up or Down on the toggle opens the popup at its first or last item.
                onKeyDown={(e) => {
                    buttonProps?.onKeyDown?.(e);
                    if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
                    e.preventDefault();
                    const edge = e.key === "ArrowDown" ? "first" : "last";
                    if (shown) {
                        if (popupRef.current) onToggleArrow?.(popupRef.current, edge);
                    } else {
                        setStartAt(edge);
                        setOpen(true);
                    }
                }}
            >
                {text}
                <span className="caret" />
            </button>

            {shown && triggerRef.current && popup({
                popupProps: {
                    anchor: triggerRef.current,
                    placement,
                    offset: TOGGLE_GAP,
                    // In a wrapper with the dropdown's classes, so CSS scoped under them still
                    // applies to the popup in the page's body. style.css stacks a portaled popup by
                    // `tn-dropdown-portal`, and its backdrop just under it.
                    placedByStylesheet: bottomSheet || pinnedAboveBar,
                    portalClassName: clsx("tn-dropdown-portal", className),
                    backdropClassName: backdrop ? "tn-dropdown-backdrop" : undefined,
                    elementRef: popupRef,
                    style: dropdownContainerStyle,
                    "aria-labelledby": toggleId,
                    onClick: closeOnClickInside
                },
                className: clsx("tn-dropdown-menu", dropdownContainerClassName),
                bottomSheet,
                startAt,
                isWanted: () => shownRef.current,
                dismiss: (reason) => {
                    if (reason === "outside" && (autoClose === "inside" || autoClose === false)) return;
                    setOpen(false);
                },
                close: () => setOpen(false)
            })}
        </div>
    );
}

/** A panel's popup, whose items Up and Down move between. */
function PanelPopup({ startAt, elementRef, ...props }: PopupProps & { startAt: "first" | "last" | undefined }) {
    const popupRef = useRef<HTMLDivElement | null>(null);

    // Captured at the window, so Bootstrap's handler for keys in a `.dropdown-menu`, which finds
    // no toggle beside a popup, never sees them.
    useEffect(() => {
        const onKeyDown = (e: KeyboardEvent) => {
            const popup = popupRef.current;
            const target = e.target as Element;
            if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return;
            if (!popup?.contains(target) || /input|textarea/i.test(target.tagName)) return;
            e.preventDefault();
            e.stopPropagation();
            focusListItem(popup, e.key === "ArrowDown" ? "next" : "previous", target);
        };
        window.addEventListener("keydown", onKeyDown, true);
        return () => window.removeEventListener("keydown", onKeyDown, true);
    }, []);

    const setElement = useCallback((element: HTMLDivElement | null) => {
        popupRef.current = element;
        if (typeof elementRef === "function") elementRef(element);
        else if (elementRef) elementRef.current = element;
    }, [ elementRef ]);

    return (
        <Popup
            {...props}
            elementRef={setElement}
            onPlaced={() => {
                if (startAt && popupRef.current) focusListItem(popupRef.current, startAt);
            }}
        />
    );
}