Skip to content

armgit / zulip

Public Imported from GitHub
0

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

23.4 KB
Raw Blame
/* Module for popovers that have been ported to the modern
   TippyJS/Popper popover library from the legacy Bootstrap
   popovers system in popovers.js. */

import {$} from "jquery";
import assert from "minimalistic-assert";
import * as tippy from "tippy.js";

import * as blueslip from "./blueslip.ts";
import * as keydown_util from "./keydown_util.ts";
import * as message_viewport from "./message_viewport.ts";
import * as modals from "./modals.ts";
import * as overlays from "./overlays.ts";
import * as popovers from "./popovers.ts";
import * as ui_util from "./ui_util.ts";
import * as util from "./util.ts";

type PopoverName =
    | "compose_control_buttons"
    | "starred_messages"
    | "drafts"
    | "left_sidebar_inbox_popover"
    | "left_sidebar_all_messages_popover"
    | "left_sidebar_recent_view_popover"
    | "top_left_sidebar"
    | "message_actions"
    | "stream_card_popover"
    | "stream_settings"
    | "scroll_to_time"
    | "topics_menu"
    | "topic_links"
    | "send_later"
    | "change_visibility_policy"
    | "personal_menu"
    | "gear_menu"
    | "help_menu"
    | "buddy_list"
    | "stream_actions_popover"
    | "color_picker_popover"
    | "show_folders_sidebar"
    | "show_folders_inbox"
    | "folder_actions"
    | "send_later_options";

export const popover_instances: Record<PopoverName, tippy.Instance | null> = {
    compose_control_buttons: null,
    starred_messages: null,
    drafts: null,
    left_sidebar_inbox_popover: null,
    left_sidebar_all_messages_popover: null,
    left_sidebar_recent_view_popover: null,
    top_left_sidebar: null,
    message_actions: null,
    stream_card_popover: null,
    stream_settings: null,
    scroll_to_time: null,
    topics_menu: null,
    topic_links: null,
    send_later: null,
    change_visibility_policy: null,
    personal_menu: null,
    gear_menu: null,
    help_menu: null,
    buddy_list: null,
    stream_actions_popover: null,
    color_picker_popover: null,
    show_folders_sidebar: null,
    show_folders_inbox: null,
    folder_actions: null,
    send_later_options: null,
};

// Font size in em for popover derived from popover font size being
// 15px at base font size of 14px.
export const POPOVER_FONT_SIZE_IN_EM = 1.0714;
export const NAVBAR_POPOVER_OFFSET: [number, number] = [0, 7];

/* Keyboard UI functions */
export function popover_items_handle_keyboard(key: string, $items?: JQuery): void {
    if (!$items) {
        return;
    }

    const index = $items.index($items.filter(":focus"));

    if (key === "enter") {
        // This is not enough for some elements which need to trigger
        // natural click for them to work like ClipboardJS and follow
        // the link for anchor tags. For those elements, we need to
        // use `.navigate-link-on-enter` class on them.
        $items.eq(index).trigger("click");
        return;
    }

    // If the focused item doesn't have a visible focus ring (e.g., it was
    // focused programmatically when the popover opened via mouse click rather
    // than keyboard navigation), treat the navigation position as unset so
    // that the first arrow key press shows the focus ring on item 1 rather
    // than skipping to item 2. We blur first because calling .focus() on an
    // already-focused element is a no-op and won't trigger :focus-visible.
    const focused_item_has_focus_ring =
        index !== -1 && document.activeElement?.matches(":focus-visible") === true;
    if (
        !focused_item_has_focus_ring &&
        index !== -1 &&
        document.activeElement instanceof HTMLElement
    ) {
        document.activeElement.blur();
    }
    const nav_index = focused_item_has_focus_ring ? index : -1;

    if (key === "down_arrow" || key === "vim_down") {
        [...$items]
            .slice(nav_index === -1 ? 0 : nav_index + 1)
            .find((item) => item.getClientRects().length)
            ?.focus();
    } else if (key === "up_arrow" || key === "vim_up") {
        [...$items]
            .slice(0, nav_index === -1 ? $items.length : nav_index)
            .findLast((item) => item.getClientRects().length)
            ?.focus();
    }
}

export function focus_popover(instance: tippy.Instance): void {
    const $items = get_popover_items_for_instance(instance);
    focus_first_popover_item($items);
}

export function focus_first_popover_item($items: JQuery | undefined, index = 0): void {
    if (!$items) {
        return;
    }

    $items.eq(index).expectOne().trigger("focus");
}

export function sidebar_menu_instance_handle_keyboard(instance: tippy.Instance, key: string): void {
    const items = get_popover_items_for_instance(instance);
    popover_items_handle_keyboard(key, items);
}

export function get_visible_instance(): tippy.Instance | null | undefined {
    return Object.values(popover_instances).find(Boolean);
}

export function get_topic_menu_popover(): tippy.Instance | null {
    return popover_instances.topics_menu;
}

export function is_topic_menu_popover_displayed(): boolean {
    return popover_instances.topics_menu?.state.isVisible ?? false;
}

export function is_visibility_policy_popover_displayed(): boolean {
    return popover_instances.change_visibility_policy?.state.isVisible ?? false;
}

export function get_scheduled_messages_popover(): tippy.Instance | null {
    return popover_instances.send_later;
}

export function is_scheduled_messages_popover_displayed(): boolean {
    return popover_instances.send_later?.state.isVisible ?? false;
}

export function get_starred_messages_popover(): tippy.Instance | null {
    return popover_instances.starred_messages;
}

export function is_personal_menu_popover_displayed(): boolean {
    return popover_instances.personal_menu?.state.isVisible ?? false;
}

export function is_gear_menu_popover_displayed(): boolean {
    return popover_instances.gear_menu?.state.isVisible ?? false;
}

export function get_gear_menu_instance(): tippy.Instance | null {
    return popover_instances.gear_menu;
}

export function is_help_menu_popover_displayed(): boolean {
    return popover_instances.help_menu?.state.isVisible ?? false;
}

export function is_message_actions_popover_displayed(): boolean {
    return popover_instances.message_actions?.state.isVisible ?? false;
}

export function get_stream_actions_popover(): tippy.Instance | null {
    return popover_instances.stream_actions_popover;
}

export function is_stream_actions_popover_displayed(): boolean | undefined {
    return popover_instances.stream_actions_popover?.state.isVisible;
}

export function get_color_picker_popover(): tippy.Instance | null {
    return popover_instances.color_picker_popover;
}

export function is_color_picker_popover_displayed(): boolean | undefined {
    return popover_instances.color_picker_popover?.state.isVisible;
}

export function get_popover_items_for_instance(instance: tippy.Instance): JQuery | undefined {
    const $current_elem = $(instance.popper);
    const class_name = $current_elem.attr("class");

    if (!$current_elem) {
        blueslip.error("Trying to get menu items when popover is closed.", {class_name});
        return undefined;
    }

    return $current_elem.find("a, [tabindex='0']");
}

export function hide_current_popover_if_visible(instance: tippy.Instance | null): void {
    // Call this function instead of `instance.hide` to avoid tippy
    // logging about the possibility of already hidden instances,
    // which can occur when a click handler does a hide_all().
    if (instance?.state.isVisible) {
        instance.hide();
    }
}

export const default_popover_props: Partial<tippy.Props> = {
    delay: 0,
    appendTo: () => document.body,
    trigger: "click",
    interactive: true,
    hideOnClick: true,
    // The maxWidth has been set to "none" to avoid the default value of 300px.
    maxWidth: "none",
    touch: true,
    /* Don't use allow-HTML here since it is unsafe. Instead, use `parse_html`
       to generate the required html */
    popperOptions: {
        modifiers: [
            {
                // Hide popover for which the reference element is hidden.
                // References:
                // https://popper.js.org/docs/v2/modifiers/
                // https://github.com/atomiks/tippyjs/blob/ad85f6feb79cf6c5853c43bf1b2a50c4fa98e7a1/src/createTippy.ts#L608
                name: "destroy-popover-if-reference-hidden",
                enabled: true,
                phase: "beforeWrite",
                requires: ["$$tippy"],
                fn({state}) {
                    // Since the reference element can be removed from DOM, we rely on popper
                    // here to access the tippy instance which is reliable.
                    assert(state.elements.popper instanceof HTMLDivElement);
                    const popper: tippy.PopperElement = state.elements.popper;
                    const instance = popper._tippy;
                    assert(instance !== undefined);
                    const $popover = $(popper);
                    const $tippy_box = $popover.find(".tippy-box");
                    const is_reference_outside_window =
                        $tippy_box.attr("data-reference-hidden") !== undefined;

                    if ($tippy_box.hasClass("show-when-reference-hidden")) {
                        return;
                    }

                    if (is_reference_outside_window) {
                        hide_current_popover_if_visible(instance);
                        return;
                    }

                    const $reference = $(state.elements.reference);
                    // Hide popover if the reference element is below another element.
                    //
                    // We only care about the reference element if it is inside the message feed since
                    // hiding elements outside the message feed is tricky and expensive due to stacking context.
                    // References in overlays, modal, sidebar overlays, popovers, etc. can make the below logic hard
                    // to live with if we take elements outside message feed into account.
                    // Since `.sticky_header` is inside `#message_feed_container`, we allow popovers from reference inside
                    // `.sticky_header` to be visible.
                    if (
                        $reference.parents("#message_feed_container, .sticky_header").length !== 1
                    ) {
                        return;
                    }

                    const reference_rect = util.the($reference).getBoundingClientRect();
                    // This is the logic we want but since it is too expensive to run
                    // on every scroll, we run a cheaper version of this to just check if
                    // compose, sticky header or navbar are not obscuring the reference
                    // in message list where we want a better experience.
                    // Also, elementFromPoint can be quite buggy since element can be temporarily
                    // hidden or obscured by other elements like `simplebar-wrapper`.
                    //
                    // const topmost_element = document.elementFromPoint(
                    //     reference_rect.left,
                    //     reference_rect.top,
                    // );
                    // if (
                    //     !topmost_element ||
                    //     ($(topmost_element).closest($reference).length === 0 &&
                    //         $(topmost_element).find($reference).length === 0)
                    // ) {
                    //     instance.hide();
                    // }

                    // Hide popover if the reference element is below compose, sticky header or navbar.

                    // These are elements covering the reference element (intersection of elements at top
                    // top left and bottom right)
                    const elements_at_reference_position = document
                        .elementsFromPoint(reference_rect.left, reference_rect.top)
                        .filter((element) =>
                            document
                                .elementsFromPoint(reference_rect.right, reference_rect.bottom)
                                .includes(element),
                        );

                    if (
                        elements_at_reference_position.some(
                            (element) =>
                                element.id === "navbar-fixed-container" ||
                                element.id === "compose-content" ||
                                element.classList.contains("sticky_header"),
                        )
                    ) {
                        hide_current_popover_if_visible(instance);
                    }
                },
            },
        ],
    },
};

export const left_sidebar_tippy_options: Partial<tippy.Props> = {
    theme: "popover-menu",
    placement: "right",
    popperOptions: {
        modifiers: [
            {
                name: "flip",
                options: {
                    fallbackPlacements: ["bottom", "top", "left"],
                },
            },
        ],
    },
};

export function on_show_prep(instance: tippy.Instance): void {
    $(instance.popper).on("click", (e) => {
        // Popover is not hidden on click inside it unless the click handler for the
        // element explicitly hides the popover when handling the event.
        // `stopPropagation` is required here to avoid global click handlers from
        // being triggered.
        e.stopPropagation();
    });
    $(instance.popper).one("click", ".navigate_and_close_popover", (e) => {
        // Handler for links inside popover which don't need a special click handler.
        e.stopPropagation();
        hide_current_popover_if_visible(instance);
    });
}

function get_props_for_popover_centering(
    popover_props: Partial<tippy.Props>,
): Partial<tippy.Props> {
    return {
        arrow: false,
        getReferenceClientRect: () => new DOMRect(0, 0, 0, 0),
        // Since we are resetting the reference to (0,0) in DOM the placement here doesn't matter
        // Using "bottom" placement as it works well with Popper's positioning system
        // when the popover exceeds window height
        placement: "bottom",
        popperOptions: {
            modifiers: [
                {
                    name: "offset",
                    options: {
                        offset({popper}: {popper: DOMRect}) {
                            // Calculate the offset needed to place the reference in the center
                            const x_offset_to_center = window.innerWidth / 2;
                            let y_offset_to_center = window.innerHeight / 2 - popper.height / 2;

                            // Move popover to the top of the screen if user is focused on an element which can
                            // open keyboard on a mobile device causing the screen to resize.
                            // Resize doesn't happen on iOS when keyboard is open, and typing text in input field just works.
                            // For other browsers, we need to check if the focused element is an text field and
                            // is causing a resize (thus calling this `offset` modifier function), in which case
                            // we need to move the popover to the top of the screen.
                            if (util.is_mobile()) {
                                const $focused_element = $(document.activeElement!);
                                if (
                                    $focused_element.is(
                                        "input[type=text], input[type=number], textarea",
                                    )
                                ) {
                                    y_offset_to_center = 10;
                                }
                            }
                            return [x_offset_to_center, y_offset_to_center];
                        },
                    },
                },
            ],
        },
        onShow(instance) {
            // By default, Tippys with the `data-reference-hidden` attribute aren't displayed.
            // But when we render them as centered overlays on mobile and use
            // `getReferenceClientRect` for a virtual reference, Tippy slaps this
            // hidden attribute on our element, making it invisible. We want to bypass
            // this in scenarios where we're centering popovers on mobile screens.
            $(instance.popper).find(".tippy-box").addClass("show-when-reference-hidden");
            if (popover_props.onShow) {
                popover_props.onShow(instance);
            }
        },
        onMount(instance) {
            $("body").append($("<div>").attr("id", "popover-overlay-background"));
            if (popover_props.onMount) {
                popover_props.onMount(instance);
            }
        },
        onHidden(instance) {
            $("#popover-overlay-background").remove();
            if (popover_props.onHidden) {
                popover_props.onHidden(instance);
            }
        },
    };
}

// Returns the element to focus when a keyboard-opened popover closes,
// given the popover's reference element. Return undefined to fall back
// to focusing the reference itself.
export type GetFocusReturnElement = (reference: HTMLElement) => HTMLElement | undefined;

// Toggles a popover menu directly; intended for use in keyboard
// shortcuts and similar alternative ways to open a popover menu.
export function toggle_popover_menu(
    target: tippy.ReferenceElement,
    popover_props: Partial<tippy.Props>,
    options?: {
        show_as_overlay_on_mobile?: boolean;
        show_as_overlay_always?: boolean;
        // Only works for elements which are in message feed.
        message_feed_overlay_detection?: boolean;
        get_focus_return_element?: GetFocusReturnElement;
    },
): tippy.Instance {
    const instance = target._tippy;
    if (instance) {
        // Ideally, we'd check that the _tippy object is a
        // popover. For elements that host both a Tippy tooltip and a
        // popover, this can incorrectly return early after hiding the
        // Tippy tooltip.
        //
        // If we fix this, we can remove a few popovers.hide_all calls.
        hide_current_popover_if_visible(instance);
        return instance;
    }

    let mobile_popover_props = {};

    // If the window is mobile-sized, we will render the
    // popover centered on the screen as an overlay.
    let show_as_overlay =
        (options?.show_as_overlay_on_mobile === true &&
            ui_util.matches_viewport_state("lt_md_min")) ||
        options?.show_as_overlay_always === true;

    // Show the popover as overlay if the reference element is hidden in message feed.
    if (
        !show_as_overlay &&
        options?.message_feed_overlay_detection &&
        $(target).parents("#message_feed_container").length === 1
    ) {
        const target_props = $(target).get_offset_to_window();
        const viewport_info = message_viewport.message_viewport_info();
        if (
            target_props.top < viewport_info.visible_top ||
            target_props.bottom > viewport_info.visible_bottom
        ) {
            show_as_overlay = true;
        }
    }

    if (show_as_overlay) {
        mobile_popover_props = {
            ...get_props_for_popover_centering(popover_props),
        };
    }

    if (popover_props.popperOptions?.modifiers) {
        popover_props.popperOptions.modifiers = [
            ...default_popover_props.popperOptions!.modifiers!,
            ...popover_props.popperOptions.modifiers,
        ];
    }

    const props = {
        ...default_popover_props,
        showOnCreate: true,
        ...popover_props,
        ...mobile_popover_props,
    };

    // If the popover was opened via keyboard, restore focus to
    // the appropriate element when the popover closes (e.g., on Escape).
    // We check the active element rather than the target, since for some
    // popovers (e.g., buddy list) the reference element is a parent
    // container rather than the focused icon itself.
    const opened_via_keyboard = document.activeElement?.matches(":focus-visible") === true;
    if (opened_via_keyboard) {
        const on_hidden = props.onHidden;
        props.onHidden = (instance: tippy.Instance) => {
            if (on_hidden) {
                on_hidden.call(props, instance);
            }
            // Only restore focus if nothing else has claimed it. When a menu
            // item opens a modal or otherwise moves focus itself, we shouldn't
            // stomp over that — and focusing a tooltipped reference here
            // would cause its tooltip to pop open unexpectedly.
            if (document.activeElement !== document.body) {
                return;
            }
            if (instance.reference instanceof HTMLElement) {
                const focus_target =
                    options?.get_focus_return_element?.(instance.reference) ?? instance.reference;
                focus_target.focus();
            }
        };
    }

    return tippy.default(target, props);
}

export type RegisterOptions = {
    // Also open the popover when the target is focused and Enter is
    // pressed. Use this for targets that are reachable via keyboard
    // navigation.
    also_trigger_on_enter?: boolean;
    get_focus_return_element?: GetFocusReturnElement;
};

// Main function to define a popover menu, opened via clicking on the
// target selector.
export function register_popover_menu(
    target: string,
    popover_props: Partial<tippy.Props>,
    options: RegisterOptions = {},
): void {
    // For some elements, such as the click target to open the message
    // actions menu, we want to avoid propagating the click event to
    // parent elements. Tippy's built-in `delegate` method does not
    // have an option to do stopPropagation, so we use this method to
    // open the Tippy popovers associated with such elements.
    //
    // A click on the click target will close the menu; for this to
    // work correctly without leaking, all callers need call
    // `instance.destroy()` inside their `onHidden` handler.
    //
    // TODO: Should we instead we wrap the caller's `onHidden` hook,
    // if any, to add `instance.destroy()`?
    $("body").on("click", target, function (this: HTMLElement, e) {
        e.preventDefault();
        e.stopPropagation();
        toggle_popover(this, popover_props, options);
    });

    if (options.also_trigger_on_enter) {
        $("body").on("keydown", target, function (this: HTMLElement, e) {
            if (keydown_util.is_enter_event(e)) {
                e.preventDefault();
                e.stopPropagation();
                toggle_popover(this, popover_props, options);
            }
        });
    }
}

function toggle_popover(
    element: HTMLElement,
    popover_props: Partial<tippy.Props>,
    options: RegisterOptions,
): void {
    const instance = toggle_popover_menu(element, popover_props, options);
    // Hide popovers when user clicks on an element which navigates user to a link.
    // We don't explicitly handle these clicks per element and let browser handle them but in doing so,
    // we are not able to hide the popover which we would do otherwise.
    const $popper = $(instance.popper);
    $popper.on("click", "a[href]", () => {
        hide_current_popover_if_visible(instance);
    });
}

export function initialize(): void {
    /* Configure popovers to hide when toggling overlays. */
    overlays.register_pre_open_hook(popovers.hide_all);
    overlays.register_pre_close_hook(popovers.hide_all);
    modals.register_pre_open_hook(popovers.hide_all);
    modals.register_pre_close_hook(popovers.hide_all);
}