Skip to content

Build your personal knowledge base with Trilium Notes

41.9 KB
Raw Blame
import "./FormList.css";

import { autoUpdate } from "@floating-ui/dom";
import type { KeyboardActionNames } from "@triliumnext/commons";
import type { Tooltip } from "bootstrap";
import clsx from "clsx";
import { ComponentChildren, createPortal, type CSSProperties, RefObject } from "preact";
import { useContext, useLayoutEffect, useMemo, useRef } from "preact/hooks";

import type { MenuHeaderActions } from "../../menus/context_menu";
import { t } from "../../services/i18n";
import { getActionSync } from "../../services/keyboard_actions";
import { handleRightToLeftPlacement, isMobile, openInAppHelpFromUrl } from "../../services/utils";
import ActionButton from "./ActionButton";
import FormTextBox from "./FormTextBox";
import FormToggle from "./FormToggle";
import { useStaticTooltip, useSyncedRef, useUniqueName } from "./hooks";
import Icon, { SvgIcon } from "./Icon";
import { MasterDetailHeader } from "./master_detail";
import { isRightToLeft, MenuContext, type MenuContextValue, type MenuFilter, MenuFilterContext, MenuLevelContext, type OpenSubmenu, pointerMoved, shouldDropStart, useMenu } from "./menu_context";
import { placeFloating } from "./Popup";
import { joinElements } from "./react_utils";
import { renderShortcutKbds } from "./shortcut_kbd";
import { type Slide, useSlide } from "./SlidePages";

interface FormListOpts {
    children: ComponentChildren;
    onSelect?: (value: string) => void;
    style?: CSSProperties;
    wrapperClassName?: string;
    fullHeight?: boolean;
}

export default function FormList({ children, onSelect, style, fullHeight, wrapperClassName }: FormListOpts) {
    const listRef = useRef<HTMLDivElement | null>(null);

    // Captured at the window: Bootstrap captures Escape, Up and Down at the document for any
    // `.dropdown-menu`, and throws when no toggle is next to it. Escape is stopped here, as
    // Bootstrap's handler also kept it from a dialog around the list.
    useLayoutEffect(() => {
        const onKeyDown = (e: KeyboardEvent) => {
            const list = listRef.current;
            const target = e.target as Element;
            if (!list?.contains(target)) return;
            if (e.key === "Escape") {
                e.stopPropagation();
            } else if ((e.key === "ArrowDown" || e.key === "ArrowUp") && !/input|textarea/i.test(target.tagName)) {
                e.preventDefault();
                e.stopPropagation();
                focusListItem(list, e.key === "ArrowDown" ? "next" : "previous", target);
            }
        };
        window.addEventListener("keydown", onKeyDown, true);
        return () => window.removeEventListener("keydown", onKeyDown, true);
    }, []);

    const builtinStyles = useMemo(() => {
        const style: CSSProperties = {};
        if (fullHeight) {
            style.height = "100%";
            style.overflow = "auto";
        }
        return style;
    }, [ fullHeight ]);

    return (
        <div className={clsx("dropdownWrapper", wrapperClassName)} style={builtinStyles}>
            <div className="dropdown" style={builtinStyles}>
                <div ref={listRef} class="dropdown-menu static show" style={{
                    ...style ?? {},
                    ...builtinStyles,
                    position: "relative",
                }} onClick={(e) => {
                    const dropdownItem = (e.target as HTMLElement).closest(".dropdown-item") as HTMLElement | null;
                    const value = dropdownItem?.dataset?.value;
                    if (value && onSelect) {
                        onSelect(value);
                    }
                }} onKeyDown={onDropdownMenuKeyDown}>
                    {children}
                </div>
            </div>
        </div>
    );
}

/**
 * Activates the currently focused list item on Enter/Space, so the list is keyboard-operable
 * and not mouse-only. The focused item is "clicked" to reuse the existing item- and list-level
 * click handlers (e.g. {@link FormList}'s `onSelect`, toggle items).
 */
function onDropdownMenuKeyDown(e: KeyboardEvent) {
    if (e.key !== "Enter" && e.key !== " ") {
        return;
    }

    const target = e.target as HTMLElement;

    const dropdownItem = target.closest(".dropdown-item") as HTMLElement | null;
    if (!dropdownItem || dropdownItem.classList.contains("disabled")) {
        return;
    }

    // Let interactive elements nested inside the item (inputs, buttons, links, anything
    // focusable) handle their own Enter/Space instead of hijacking it for the parent item.
    const interactive = target.closest("input, textarea, select, button, a, [tabindex]");
    if (interactive && interactive !== dropdownItem) {
        return;
    }

    e.preventDefault();
    dropdownItem.click();
}

/**
 * Focuses an enabled item that belongs to `list` itself, not to a nested submenu: the first, the
 * last, or the one after or before `from`, wrapping at either end.
 */
export function focusListItem(list: HTMLElement, where: "first" | "last" | "next" | "previous", from?: Element) {
    const items = [ ...list.querySelectorAll<HTMLElement>(".dropdown-item:not(.disabled):not(:disabled)") ]
        .filter((item) => item.parentElement?.closest(".dropdown-menu") === list);
    if (!items.length) return;

    const current = from?.closest<HTMLElement>(".dropdown-item");
    const index = current ? items.indexOf(current) : -1;
    let target: HTMLElement | undefined;
    if (where === "first" || (where === "next" && index < 0)) target = items[0];
    else if (where === "last" || (where === "previous" && index < 0)) target = items.at(-1);
    else target = items[(index + (where === "next" ? 1 : -1) + items.length) % items.length];
    target?.focus();
}

export interface FormListBadge {
    className?: string;
    text: string;
}

export interface FormListItemOpts {
    children: ComponentChildren;
    /** Without one the row keeps a blank slot, lining it up with the rows that have one; `null` leaves no slot. */
    icon?: string | null;
    /** The SVG of an icon drawn in place of {@link icon}, such as a CKEditor toolbar item's. */
    iconSvg?: string;
    /** Extra class for the icon itself, e.g. to hang a marker off its corner. */
    iconClassName?: string;
    value?: string;
    title?: string;
    active?: boolean;
    badges?: FormListBadge[];
    disabled?: boolean;
    /** Will indicate the reason why the item is disabled via an icon, when hovered over it. */
    disabledTooltip?: string;
    /**
     * Marks the row with a check: at the trailing edge when the row has an {@link icon} of its own,
     * which tells it from the other rows, and in place of the icon when it has none.
     */
    checked?: boolean | null;
    selected?: boolean;
    container?: boolean;
    onClick?: (e: MouseEvent) => void;
    /** Runs on a middle click on the row, which leaves the menu open. */
    onMiddleClick?: (e: MouseEvent) => void;
    /** Runs on a right-click on the row, which a menu ignores otherwise. */
    onContextMenu?: (e: MouseEvent) => void;
    description?: string;
    className?: string;
    rtl?: boolean;
    postContent?: ComponentChildren;
    itemRef?: RefObject<HTMLLIElement | null>;
    /**
     * Makes the row one that is checked or not, which a menu tells assistive technology;
     * {@link checked} says which.
     */
    checkable?: boolean;
    /**
     * Inside a menu, whether running the row closes the menu after its {@link onClick} runs. It
     * does unless this is `false`, for a caller that decides for itself, as `contextMenu` does.
     */
    closeOnSelect?: boolean;
    /** The action whose shortcuts, as the user configured them, show at the end of the row. */
    keyboardShortcut?: KeyboardActionNames;
    /** A shortcut shown as it is written, for a row with no action of its own. */
    shortcut?: string;
    /** Text at the end of the row, where a shortcut would go. */
    trailingText?: string;
    /** An icon at the end of the row, where a shortcut would go. */
    trailingIcon?: string;
}

const CHECK_ICON = "bx bx-check";
/** The blank icon a row carries only to line its title up with the icons of the others. */
const EMPTY_ICON = "bx bx-empty";

/** What in a row takes focus from a press: the controls that are typed into. */
const TEXT_ENTRY = "input:not([type='checkbox'], [type='radio']), textarea, select, [contenteditable='true']";

const TOOLTIP_CONFIG: Partial<Tooltip.Options> = {
    placement: menuItemTooltipSide,
    fallbackPlacements: [],
    animation: false
};

export function FormListItem({
    className, icon, iconSvg, iconClassName, value, title, active, disabled, checked, checkable,
    container, onClick, onMiddleClick, onContextMenu, selected, rtl, description,
    itemRef: externalItemRef, keyboardShortcut, shortcut, trailingText, trailingIcon, closeOnSelect,
    ...contentProps
}: FormListItemOpts) {
    const itemRef = useSyncedRef<HTMLLIElement>(externalItemRef, null);
    // Inside a `Menu` the row is one of its items; elsewhere, as in a dropdown, it stands alone.
    const menu = useContext(MenuContext);
    const level = useContext(MenuLevelContext);
    // Unique across portals, where `useId()` numbers a menu's layers over again.
    const id = useUniqueName("menu-row");
    const isActive = menu?.active?.id === id;

    /**
     * Runs the row, then closes the menu it stands in, as Bootstrap's dropdowns did, unless
     * {@link closeOnSelect} is `false` or the row's handler stopped the click: a row that stays up
     * to be worked again, such as a toggle, stops it.
     */
    function run(e: MouseEvent) {
        onClick?.(e);
        if (closeOnSelect !== false && !e.cancelBubble) menu?.close();
    }

    /**
     * Runs the row for the keys, as a click would, with the modifiers of the key that ran it, so
     * Ctrl+Enter does what a Ctrl+click does.
     */
    function select(e: MouseEvent | KeyboardEvent) {
        run(new MouseEvent("click", { ctrlKey: e.ctrlKey, shiftKey: e.shiftKey, altKey: e.altKey, metaKey: e.metaKey }));
    }

    function onPointed() {
        if (!menu || isMobile()) return;
        // Before `menu.setActive()`: closing a submenu can activate the row that opened it.
        menu.hoverSubmenu(level);
        // The keyboard goes on from the row the pointer last pointed at.
        if (!disabled) menu.setActive(level, id);
    }

    const hasOwnIcon = !!iconSvg || (!!icon && icon !== EMPTY_ICON);
    if (checked) {
        if (hasOwnIcon) trailingIcon ??= CHECK_ICON;
        else icon = CHECK_ICON;
    }

    useStaticTooltip(itemRef, TOOLTIP_CONFIG);

    return (
        <li
            ref={(element) => {
                itemRef.current = element;
                menu?.registerRow(id, element
                    ? { level, element, custom: false, disabled: !!disabled, hasSubmenu: false, select }
                    : undefined);
            }}
            id={menu ? id : undefined}
            class={clsx("dropdown-item", active && "active", disabled && "disabled", selected && "selected",
                container && "dropdown-container-item", isActive && "tn-menu-active", className)}
            data-value={value} title={title}
            role={menu ? (checkable ? "menuitemcheckbox" : "menuitem") : undefined}
            aria-checked={menu && checkable ? !!checked : undefined}
            aria-disabled={(menu && disabled) || undefined}
            // A menu keeps focus itself and marks the row its keys act on instead.
            tabIndex={menu ? undefined : container ? -1 : 0}
            // While the keys drive the menu, a row entered by a pointer at rest, as when the menu
            // appears under it, keeps the keys' row. See `pointerMoved`.
            onPointerEnter={menu ? () => {
                if (!menu.keyboardDriven) onPointed();
            } : undefined}
            // The keys can move the active row from under a pointer at rest, whose `:hover` would
            // then mark a second row. The next move of the pointer makes its row the active one.
            onPointerMove={menu ? (e) => {
                if (!isActive && pointerMoved(e)) onPointed();
            } : undefined}
            // A press keeps focus where it was, as in a native menu: a text editor keeps the
            // selection a command such as a spelling fix acts on, and a field beside a dropdown
            // stays in focus. A field inside the row takes focus as it would anywhere.
            onMouseDown={(e) => {
                if (e.button === 0 && !(e.target instanceof Element && e.target.closest(TEXT_ENTRY))) e.preventDefault();
                preventMiddlePress(e, onMiddleClick);
            }}
            // The row runs on the release, so a press can still be taken back by moving off.
            onClick={(e) => {
                if (!disabled) run(e);
            }}
            onAuxClick={middleClickHandler(onMiddleClick, disabled)}
            onContextMenu={onContextMenu}
            dir={rtl ? "rtl" : undefined}
        >
            {/* One classless span holds the row, as the rows of a menu are laid out. */}
            <span>
                {iconSvg
                    ? <SvgIcon svg={iconSvg} className={iconClassName} />
                    : icon === null ? <span /> : <Icon icon={icon} className={iconClassName} />}
                {/* An element, not spaces: in a flex row, text merges with a plain title but is
                    trimmed before one boxed by `menuName()`, indenting the two kinds of row apart. */}
                <span className="tn-menu-gap" />
                {description ? (
                    <div>
                        <FormListContent description={description} disabled={disabled} {...contentProps} />
                    </div>
                ) : (
                    <FormListContent description={description} disabled={disabled} {...contentProps} />
                )}
                <FormListShortcut keyboardShortcut={keyboardShortcut} shortcut={shortcut} />
                {trailingText && <span className="menu-trailing-text">{trailingText}</span>}
                {trailingIcon && <span className={clsx(trailingIcon, "tn-icon", "menu-trailing-icon")} />}
            </span>
        </li>
    );
}

/** Bootstrap's default `--bs-tooltip-max-width`, for a tooltip whose inner carries no cap of its own. */
const TOOLTIP_MAX_WIDTH = 200;
const TOOLTIP_OFFSET = 6;
/** The narrowest a tooltip is squeezed to. Below it the text is unreadable, so it is let to overflow. */
const MIN_TOOLTIP_WIDTH = 160;

/**
 * Puts a row's tooltip on the reading-direction end of the menu, or on the other side when the
 * viewport has no room there for a tooltip at its widest. The room is measured against that widest
 * tooltip rather than this one, so every row of a menu gets the same side whatever its text. A
 * window too narrow for either side gets the roomier one, with the tooltip wrapped to fit it.
 *
 * Bootstrap calls this with the tip first and the row it stands beside second, `this` being the
 * `Tooltip`.
 */
export function menuItemTooltipSide(tip?: HTMLElement, row?: Element): "left" | "right" {
    const preferred = handleRightToLeftPlacement("right");
    if (!tip || !row) return preferred;

    // A tooltip shown before may have been narrowed to the room it had then.
    tip.style.maxWidth = "";

    const { left, right } = row.getBoundingClientRect();
    const roomOn = (side: "left" | "right") => side === "right"
        ? window.innerWidth - right - TOOLTIP_OFFSET
        : left - TOOLTIP_OFFSET;
    const needed = tooltipWidth(tip) + TOOLTIP_OFFSET;
    const other = preferred === "right" ? "left" : "right";
    const room = roomOn(preferred);
    const side = room >= needed || roomOn(other) <= room ? preferred : other;
    const roomOnSide = roomOn(side);

    // Neither side may hold a tooltip at its widest, as a menu row on a narrow window leaves little
    // room either way: it wraps into what its side has rather than being cut by the window.
    if (roomOnSide < needed) {
        tip.style.maxWidth = `${Math.max(roomOnSide, MIN_TOOLTIP_WIDTH)}px`;
    }

    return side;
}

/**
 * The widest the tooltip can be: the cap its inner carries, which `tooltip.css` sets well above
 * Bootstrap's, on `.tooltip-inner`.
 */
function tooltipWidth(tip: HTMLElement) {
    const inner = tip.querySelector(".tooltip-inner");
    const cap = inner ? parseFloat(getComputedStyle(inner).maxWidth) : NaN;
    if (!Number.isNaN(cap)) return cap;

    const bootstrapCap = parseFloat(getComputedStyle(tip).getPropertyValue("--bs-tooltip-max-width"));
    return Number.isNaN(bootstrapCap) ? TOOLTIP_MAX_WIDTH : bootstrapCap;
}

export function FormListToggleableItem({
    title, currentValue, onChange, disabled, helpPage, helpTooltip, className, ...props
}: Omit<FormListItemOpts, "onClick" | "children"> & {
    title: string;
    currentValue: boolean;
    helpPage?: string;
    /** What the setting does, shown beside the menu while the row is hovered. */
    helpTooltip?: string;
    onChange(newValue: boolean): void | Promise<void>;
}) {
    const isWaiting = useRef(false);

    return (
        <FormListItem
            {...props}
            className={clsx("tn-menu-toggle", className)}
            title={helpTooltip}
            disabled={disabled}
            onClick={async (e) => {
                if ((e.target as HTMLElement | null)?.classList.contains("contextual-help")) {
                    return;
                }

                e.stopPropagation();
                if (!disabled && !isWaiting.current) {
                    isWaiting.current = true;
                    await onChange(!currentValue);
                    isWaiting.current = false;
                }
            }}>
            <FormToggle
                switchOnName={title}
                switchOffName={title}
                currentValue={currentValue}
                onChange={() => {}}
                afterName={<>
                    {helpPage && (
                        <span
                            class="bx bx-help-circle contextual-help"
                            onClick={() => openInAppHelpFromUrl(helpPage)}
                        />
                    )}
                    <span class="switch-spacer" />
                </>}
            />
        </FormListItem>
    );
}

function FormListContent({ children, badges, description, disabled, disabledTooltip }: Pick<FormListItemOpts, "children" | "badges" | "description" | "disabled" | "disabledTooltip">) {
    return <>
        {children}
        {badges && badges.map(({ className, text }) => (
            <span className={clsx("badge", className)}>{text}</span>
        ))}
        {disabled && disabledTooltip && (
            <span class="bx bx-info-circle contextual-help" title={disabledTooltip} />
        )}
        {description && <div className="description">{description}</div>}
    </>;
}

interface FormListHeaderOpts {
    /** Usually a heading, but anything a group can be introduced by: a summary, a row of marks. */
    text: ComponentChildren;
    /** Icon buttons at the end of the heading, which keep it as tall as a heading without them. */
    actions?: MenuHeaderActions;
}

/** The most actions a heading shows, as `MenuHeaderActions` allows. A script can pass more. */
const MAX_HEADER_ACTIONS = 3;

export function FormListHeader({ text, actions = [] }: FormListHeaderOpts) {
    const menu = useContext(MenuContext);
    const level = useContext(MenuLevelContext);
    const shownActions = actions.slice(0, MAX_HEADER_ACTIONS);
    const hasActions = shownActions.length > 0;

    // Its heading speaks for the row, which a menu does not count among its items.
    return (
        <li role="none">
            <h6 className={clsx("dropdown-header", hasActions && "tn-menu-header-with-actions")}>
                <span>{text}</span>
                {hasActions && (
                    <span
                        className="tn-menu-header-actions"
                        // As over a row, the pointer closes the submenu open at this level.
                        onPointerMove={(e) => {
                            if (menu && pointerMoved(e)) menu.hoverSubmenu(level);
                        }}
                        // A press keeps focus where it was, as on a row.
                        onMouseDown={(e) => e.preventDefault()}
                    >
                        {shownActions.map(({ icon, caption, callback }, index) => (
                            <ActionButton
                                key={index} icon={icon} text={caption} titlePosition="top"
                                onClick={(e) => {
                                    menu?.close();
                                    callback(e);
                                }}
                            />
                        ))}
                    </span>
                )}
            </h6>
        </li>
    );
}

/** A line between groups of rows. A click on it closes no menu. */
export function FormDropdownDivider() {
    return <li className="dropdown-divider" role="separator" onClick={(e) => e.stopPropagation()} />;
}

export interface FormDropdownSubmenuProps {
    icon?: string;
    /** The SVG of an icon drawn in place of {@link icon}, such as a CKEditor toolbar item's. */
    iconSvg?: string;
    title: ComponentChildren;
    children: ComponentChildren;
    /** A line under the title, as {@link FormListItem} shows one. */
    description?: string;
    /** Called when the row is clicked, or run from the keyboard, on the desktop. */
    onDropdownToggleClicked?: (e: MouseEvent) => void;
    /**
     * Whether the row runs an action of its own besides opening the submenu. A split row draws a
     * divider before its arrow, and a click on the arrow only opens the submenu. Defaults to
     * whether {@link onDropdownToggleClicked} is set.
     */
    split?: boolean;
    /** Whether running {@link onDropdownToggleClicked} closes the menu, as `FormListItem` does. */
    closeOnSelect?: boolean;
    /** Runs on a middle click on the row, which leaves the menu open. Not for a {@link tile}. */
    onMiddleClick?: (e: MouseEvent) => void;
    /** Runs on a right-click on the row, which a menu ignores otherwise. Not for a {@link tile}. */
    onContextMenu?: (e: MouseEvent) => void;
    disabled?: boolean;
    className?: string;
    /** Inside a menu, whether typing while the submenu is open filters it. See `MenuCommandItem.filterable`. */
    filterable?: boolean;
    /**
     * Draws the row as a tile of a `MenuTile` strip, which only opens the submenu: a tile has no
     * room for the arrow of a split row.
     */
    tile?: boolean;
}

/**
 * A row that opens its children as a submenu, in a separate layer beside the row, so a scrolling
 * menu neither clips it nor scrolls it away. Outside a `Menu`, which only a script can arrange, it
 * renders its title as a `FormListHeader` above its children.
 */
export function FormDropdownSubmenu(props: FormDropdownSubmenuProps) {
    const menu = useContext(MenuContext);
    if (!menu) return <><FormListHeader text={props.title} />{props.children}</>;
    return <MenuSubmenu {...props} menu={menu} />;
}

function MenuSubmenu({
    menu, icon, iconSvg, title, description, children, onDropdownToggleClicked,
    split = !!onDropdownToggleClicked, closeOnSelect, onMiddleClick, onContextMenu, disabled,
    className, filterable, tile
}: FormDropdownSubmenuProps & { menu: MenuContextValue }) {
    const level = useContext(MenuLevelContext);
    const id = useUniqueName("menu-row");
    const openSubmenu = menu.open[level];
    const open = openSubmenu?.id === id;
    const isActive = menu.active?.id === id;
    const filter = filterable ? { rowId: id, level, text: menu.filter?.rowId === id ? menu.filter.text : "" } : undefined;
    // A phone's page that closes keeps being drawn until it has slid out.
    const pageSlide = useSlide(open);

    function run(e: MouseEvent) {
        onDropdownToggleClicked?.(e);
        if (closeOnSelect) menu.close();
    }

    /** Runs the row's own action for the keys, with the modifiers of the key that ran it. */
    function select(e: MouseEvent | KeyboardEvent) {
        const { ctrlKey, shiftKey, altKey, metaKey } = e;
        run(new MouseEvent("click", { ctrlKey, shiftKey, altKey, metaKey }));
    }

    function onPointed(e: { currentTarget: HTMLLIElement }) {
        if (isMobile()) return;
        // The keyboard goes on from the row the pointer last pointed at.
        if (!disabled) menu.setActive(level, id);
        menu.hoverSubmenu(level, disabled ? undefined : id, e.currentTarget);
    }

    const layer = isMobile()
        // A phone has no room beside the menu, so a submenu replaces it as a page of its own.
        ? (open || pageSlide.from !== undefined) && menu.layerHost && createPortal((
            <SubmenuPage
                rowId={id} level={level + 1} title={title} slide={pageSlide} filter={filter}
            >
                {children}
            </SubmenuPage>
        ), menu.layerHost)
        : open && openSubmenu && menu.layerHost && createPortal((
            <SubmenuLayer level={level + 1} submenu={openSubmenu} filter={filter}>
                {children}
            </SubmenuLayer>
        ), menu.layerHost);

    if (tile) {
        return (
            <button
                id={id} type="button"
                ref={(element) => {
                    menu.registerRow(id, element
                        ? { level, element, custom: false, disabled: !!disabled, hasSubmenu: true, inline: true, filterable, select: () => {} }
                        : undefined);
                }}
                className={clsx("tn-menu-action", open && "submenu-open", isActive && "tn-menu-active", className)}
                role="menuitem" aria-haspopup="menu" aria-expanded={open}
                disabled={disabled} tabIndex={-1}
                // As over a row, the pointer closes another submenu at this level, but the tile
                // opens its own only on a press.
                onPointerMove={(e) => {
                    if (!pointerMoved(e)) return;
                    menu.hoverSubmenu(level, open ? id : undefined, e.currentTarget);
                    if (!disabled && !isActive) menu.setActive(level, id);
                }}
                // As any row: the press keeps focus where it was, and the release acts.
                onMouseDown={(e) => e.preventDefault()}
                onClick={(e) => {
                    // The dropdown's `closeOnClickInside` would close the whole menu.
                    e.stopPropagation();
                    menu.setActive(level, id);
                    menu.openSubmenu(level, id, e.currentTarget, true);
                }}
            >
                <span className="tn-menu-action-icon" aria-hidden="true">
                    {iconSvg ? <SvgIcon svg={iconSvg} /> : <Icon icon={icon} />}
                </span>
                <span id={titleId(id)} className="tn-menu-action-title">{title}</span>
                <span className="tn-menu-action-more bx bx-chevron-right" aria-hidden="true" />
                {layer}
            </button>
        );
    }

    return (
        <li
            id={id}
            ref={(element) => {
                menu.registerRow(id, element ? { level, element, custom: false, disabled: !!disabled, hasSubmenu: true, filterable, select } : undefined);
            }}
            className={clsx("dropdown-item dropdown-submenu", open && "submenu-open", isActive && "tn-menu-active",
                split && !isMobile() && "tn-menu-split", disabled && "disabled", className)}
            role="menuitem"
            aria-disabled={disabled || undefined}
            aria-haspopup="menu"
            aria-expanded={open}
            // While the keys drive the menu, a row entered by a pointer at rest, as when the menu
            // appears under it, keeps the keys' row. See `pointerMoved`.
            onPointerEnter={(e) => {
                if (!menu.keyboardDriven) onPointed(e);
            }}
            // The keys can move the active row from under a pointer at rest, whose `:hover` would
            // then mark a second row. The next move of the pointer makes its row the active one.
            onPointerMove={(e) => {
                if (!isActive && pointerMoved(e)) onPointed(e);
            }}
            // As any row: the press keeps focus where it was, and the release acts.
            onMouseDown={(e) => {
                if (e.button === 0) e.preventDefault();
                preventMiddlePress(e, onMiddleClick);
            }}
            onClick={(e) => {
                // The dropdown's `closeOnClickInside` would close the whole menu.
                e.stopPropagation();
                if (disabled) return;
                menu.openSubmenu(level, id, e.currentTarget, true);
                if (!isMobile()) run(e);
            }}
            onAuxClick={middleClickHandler(onMiddleClick, disabled)}
            onContextMenu={onContextMenu}
        >
            <span className="dropdown-toggle">
                {iconSvg ? <SvgIcon svg={iconSvg} /> : <Icon icon={icon} />}
                <span className="tn-menu-gap" />
                {description ? (
                    <div>
                        <span id={titleId(id)}>{title}</span>
                        <div className="description">{description}</div>
                    </div>
                ) : <span id={titleId(id)}>{title}</span>}
            </span>
            {split && !isMobile() && (
                <span
                    className="tn-menu-split-toggle"
                    aria-hidden="true"
                    onClick={(e) => {
                        e.stopPropagation();
                        const row = e.currentTarget.parentElement;
                        if (!disabled && row) menu.openSubmenu(level, id, row, true);
                    }}
                />
            )}
            {layer}
        </li>
    );
}

/**
 * A submenu opened on the desktop, placed beside the row it opened from rather than nested in it,
 * so a scrolling menu neither clips it nor scrolls it away. While its {@link filter} has text, the
 * layer keeps its top position relative to its row, and only its height changes with the matches.
 */
function SubmenuLayer({ level, submenu, filter, children }: {
    level: number,
    submenu: OpenSubmenu,
    filter: MenuFilter | undefined,
    children: ComponentChildren
}) {
    const layerRef = useRef<HTMLDivElement>(null);
    const { dropStart: dropStartLevels, setDropStart, submenuShown, hoverSubmenu } = useMenu();
    const dropStart = !!dropStartLevels[level - 1];
    const pinned = !!filter?.text;
    /** How far below its row's top the layer stands while pinned. */
    const pinnedOffset = useRef<number | undefined>(undefined);

    // Taken as the content changes, before the layer is placed again for its new height.
    useLayoutEffect(() => {
        const layer = layerRef.current;
        if (!pinned || !layer) {
            pinnedOffset.current = undefined;
        } else if (pinnedOffset.current === undefined) {
            pinnedOffset.current = parseFloat(layer.style.top) - submenu.anchor.getBoundingClientRect().top;
        }
    }, [ pinned, submenu.anchor ]);

    useLayoutEffect(() => {
        const layer = layerRef.current;
        if (!layer) return;

        const rtl = isRightToLeft();
        const startSide = rtl ? "right" : "left";
        const endSide = rtl ? "left" : "right";
        const options = {
            placement: `${dropStart ? startSide : endSide}-start`,
            // Overlaps its row by 2px, so the pointer crosses no gap on its way over, and lines its
            // first row up with that row.
            offset: ({ elements }: { elements: { floating: HTMLElement } }) => {
                const style = getComputedStyle(elements.floating);
                const inset = (parseFloat(style.paddingTop) || 0) + (parseFloat(style.borderTopWidth) || 0);
                return { mainAxis: -2, crossAxis: -inset };
            },
            shiftAcross: true, capHeight: true, hideWithAnchor: true
        } as const;
        const place = () => {
            const offset = pinnedOffset.current;
            const pinTop = offset === undefined || Number.isNaN(offset)
                ? undefined
                : submenu.anchor.getBoundingClientRect().top + offset;
            return placeFloating(layer, submenu.anchor, { ...options, pinTop });
        };
        return autoUpdate(submenu.anchor, layer, () => void place().then((placed) => {
            // After a flip, the parent level follows, so its rows' arrows match.
            const placedDropStart = placed.startsWith(startSide);
            if (placedDropStart !== dropStart) {
                setDropStart(level - 1, placedDropStart);
                return;
            }
            setDropStart(level, shouldDropStart(layer.getBoundingClientRect(),
                document.documentElement.clientWidth, rtl, dropStart));
        }));
    }, [ submenu.anchor, dropStart, level, setDropStart ]);

    // In a `.dropdown-submenu`, so the theme's submenu rules apply.
    return (
        <MenuLevelContext.Provider value={level}>
            <div className="dropdown-submenu">
                <div
                    ref={layerRef} role="menu" aria-labelledby={titleId(submenu.anchor.id)}
                    className={clsx("dropdown-menu show tn-menu", submenu.immediate && "tn-menu-immediate")}
                    // The fade starts once the opening delay is over.
                    onAnimationStart={(e) => {
                        if (e.target === e.currentTarget) submenuShown(submenu);
                    }}
                    // Over the layer, the pointer keeps it open as over its row, whatever rows it
                    // crossed on the way.
                    onPointerEnter={() => hoverSubmenu(level - 1, submenu.id, submenu.anchor)}
                >
                    <MenuList filter={filter}>{children}</MenuList>
                </div>
            </div>
        </MenuLevelContext.Provider>
    );
}

/**
 * A submenu opened on a phone: a page that takes the menu's place, headed by the submenu's title and
 * a way back. The level it covers stays mounted, as the row that owns this page stands in it.
 */
function SubmenuPage({ rowId, level, title, slide, filter, children }: {
    rowId: string,
    level: number,
    title: ComponentChildren,
    /** The slide of whether the page is open: from closed as it arrives, from open as it leaves. */
    slide: Slide<boolean>,
    filter: MenuFilter | undefined,
    children: ComponentChildren
}) {
    const menu = useMenu();

    function back() {
        menu.openSubmenu(level - 1);
        menu.setActive(level - 1, rowId);
    }

    return (
        <MenuLevelContext.Provider value={level}>
            <div
                role="menu" aria-labelledby={titleId(rowId)}
                className={clsx("tn-menu-page", slide.from === false && "tn-menu-page-entering",
                    slide.from === true && "tn-menu-page-leaving")}
                onAnimationEnd={slide.onAnimationEnd}
            >
                {/* As a row's press: the menu keeps focus, and the dropdown does not close on it. */}
                <div
                    className="tn-menu-page-header"
                    onMouseDown={(e) => e.preventDefault()}
                    onClick={(e) => e.stopPropagation()}
                >
                    <MasterDetailHeader inPage onBack={back} backTitle={t("menu.back")} pageTitle={title} listTitle={title} />
                </div>
                <MenuList filter={filter}>{children}</MenuList>
            </div>
        </MenuLevelContext.Provider>
    );
}

/**
 * One level of a menu: its rows in a scrolling list and, for a level with a {@link filter}, the
 * filter input above that list. The input stays in place while the rows scroll.
 */
export function MenuList({ filter, bottomUp, children }: {
    filter: MenuFilter | undefined,
    /** Puts the filter input below the list, for a menu that opens above its anchor. */
    bottomUp?: boolean,
    children: ComponentChildren
}) {
    // The rows scroll here and not in the frame, so the theme's `::before` blur stays behind
    // them. `role="none"` exposes the rows as the menu's own items.
    const list = <menu className="tn-menu-scroll" role="none">{children}</menu>;
    return (
        <MenuFilterContext.Provider value={filter}>
            {/* One box, so a phone's submenu page hides and slides the input with the rows. */}
            {filter ? (
                <div className="tn-menu-filterable">
                    {!bottomUp && <MenuFilterInput filter={filter} />}
                    {list}
                    {bottomUp && <MenuFilterInput filter={filter} />}
                </div>
            ) : list}
        </MenuFilterContext.Provider>
    );
}

/**
 * The filter input above a filterable level's rows. The input handles the editing keys; the menu
 * handles Up, Down, Enter, Escape and Tab, so a match can be picked while focus is in the input.
 */
function MenuFilterInput({ filter }: { filter: MenuFilter }) {
    const menu = useMenu();
    const inputRef = useRef<HTMLInputElement | null>(null);

    // An input unmounted while focused, as when the pointer closes its submenu, returns focus to
    // the menu and not to the page.
    useLayoutEffect(() => () => {
        if (document.activeElement !== inputRef.current) return;
        menu.layerHost?.focus({ preventScroll: true });
    }, [ menu.layerHost ]);

    return (
        <div className="tn-menu-filter">
            {/* A press anywhere in the box, the clear button's included, keeps focus in the input,
                and a click in it does not close the dropdown. */}
            <div
                className="tn-menu-filter-box tn-input-field"
                onMouseDown={(e) => {
                    if (e.target === inputRef.current) return;
                    e.preventDefault();
                    inputRef.current?.focus({ preventScroll: true });
                }}
                onClick={(e) => e.stopPropagation()}
            >
                <FormTextBox
                    inputRef={inputRef} className="tn-menu-filter-input"
                    data-level={filter.level + 1} currentValue={filter.text}
                    autoComplete="off" spellcheck={false}
                    placeholder={t("menu.filter_placeholder")} aria-label={t("menu.filter")}
                    onChange={(text) => menu.setFilter(text
                        ? { rowId: filter.rowId, level: filter.level, text }
                        : undefined)}
                />
                {filter.text
                    ? <ActionButton
                        className="tn-menu-filter-clear" icon="bx bx-x" text={t("menu.clear_filter")}
                        onClick={() => menu.setFilter(undefined)}
                    />
                    : <span className="bx bx-search" aria-hidden="true" />}
            </div>
        </div>
    );
}

/** The id of a row's title, which names the submenu it opens. */
function titleId(rowId: string) {
    return `${rowId}-title`;
}

/**
 * A row holding a control of its own, such as the color picker. The keys stand on it when its
 * content marks a way in with `tabindex="0"`, and a click on something in it that acts closes the
 * menu it stands in.
 */
export function FormListCustomItem({ children }: { children: ComponentChildren }) {
    // Outside a `Menu`, as in a dropdown's plain list, there is none to join.
    const menu = useContext(MenuContext);
    const level = useContext(MenuLevelContext);
    const id = useUniqueName("menu-row");

    return (
        <li
            className="dropdown-custom-item"
            // Its content carries the roles of what it acts with.
            role="none"
            ref={(element) => {
                menu?.registerRow(id, element
                    ? { level, element, custom: true, disabled: false, hasSubmenu: false, select: () => {} }
                    : undefined);
            }}
            // Only a click on what the row acts with closes the menu: one in the space around it,
            // such as between the color picker's cells, picks nothing.
            onClick={(e) => {
                if (menu && actsOnClick(e.target, e.currentTarget)) menu.close();
            }}
        >
            {children}
        </li>
    );
}

/** What a custom row's content acts with: the elements a click on does something. */
const ACTING_ELEMENTS = "button, a[href], input, select, textarea, [tabindex], "
    + "[role='button'], [role='option'], [role='menuitem'], [role='checkbox'], [role='radio'], [role='switch']";

/** Whether a click on `target` inside `row` landed on an enabled element that acts. */
function actsOnClick(target: EventTarget | null, row: HTMLElement) {
    const acting = target instanceof Element ? target.closest(ACTING_ELEMENTS) : null;
    return !!acting && row.contains(acting) && acting !== row
        && acting.getAttribute("aria-disabled") !== "true" && !acting.matches(":disabled");
}

/**
 * Cancels a middle press on a row with `onMiddleClick`. The press starts autoscrolling, and pastes
 * on Linux.
 */
function preventMiddlePress(e: MouseEvent, onMiddleClick: ((e: MouseEvent) => void) | undefined) {
    if (e.button === 1 && onMiddleClick) e.preventDefault();
}

/** An `auxclick` handler running `onMiddleClick`, which browsers fire for the right button too. */
function middleClickHandler(
    onMiddleClick: ((e: MouseEvent) => void) | undefined,
    disabled?: boolean
) {
    if (!onMiddleClick) return undefined;
    return (e: MouseEvent) => {
        if (e.button === 1 && !disabled) onMiddleClick(e);
    };
}

/**
 * The shortcuts of the row's `keyboardShortcut` action as the user configured them, or else its
 * literal `shortcut`. Read synchronously, so the menu is placed at its final width.
 */
function FormListShortcut({ keyboardShortcut, shortcut }: Pick<FormListItemOpts, "keyboardShortcut" | "shortcut">) {
    // A phone has no keyboard to press them on.
    if (isMobile()) return null;
    if (keyboardShortcut) {
        const shortcuts = getActionSync(keyboardShortcut)?.effectiveShortcuts;
        if (!shortcuts?.length) return null;
        return (
            <span className="keyboard-shortcut">
                {joinElements(shortcuts.map(shortcut => renderShortcutKbds(shortcut)), ",")}
            </span>
        );
    }

    return shortcut ? <kbd>{shortcut}</kbd> : null;
}