zulip/web/src/list_widget.ts

import $ from "jquery";
import assert from "minimalistic-assert";

import * as blueslip from "./blueslip";
import * as scroll_util from "./scroll_util";

type SortingFunction<T> = (a: T, b: T) => number;
type GenericSortingFunction<T = Record<string, unknown>> = (prop: string) => SortingFunction<T>;

type ListWidgetMeta<Key = unknown, Item = Key> = {
    sorting_function: SortingFunction<Item> | null;
    sorting_functions: Map<string, SortingFunction<Item>>;
    filter_value: string;
    offset: number;
    list: Key[];
    filtered_list: Item[];
    reverse_mode: boolean;
    $scroll_container: JQuery;
};

// This type ensures the mutually exclusive nature of the predicate and filterer options.
type ListWidgetFilterOpts<Item = unknown> = {
    $element?: JQuery<HTMLInputElement>;
    onupdate?: () => void;
} & (
    | {
          predicate: (item: Item, value: string) => boolean;
          filterer?: never;
      }
    | {
          predicate?: never;
          filterer: (list: Item[], value: string) => Item[];
      }
);

type ListWidgetOpts<Key = unknown, Item = Key> = {
    name?: string;
    get_item: (key: Key) => Item;
    modifier: (item: Item, filter_value: string) => string;
    init_sort?: string | SortingFunction<Item>;
    initially_descending_sort?: boolean;
    html_selector?: (item: Item) => JQuery;
    callback_after_render?: () => void;
    post_scroll__pre_render_callback?: () => void;
    get_min_load_count?: (rendered_count: number, load_count: number) => number;
    is_scroll_position_for_render?: (scroll_container: HTMLElement) => boolean;
    filter?: ListWidgetFilterOpts<Item>;
    multiselect?: {
        selected_items: Key[];
    };
    sort_fields?: Record<string, SortingFunction<Item>>;
    $simplebar_container: JQuery;
    $parent_container?: JQuery;
};

type ListWidget<Key = unknown, Item = Key> = {
    get_current_list(): Item[];
    filter_and_sort(): void;
    retain_selected_items(): void;
    render(how_many?: number): void;
    render_item(item: Item): void;
    clear(): void;
    set_filter_value(value: string): void;
    set_reverse_mode(reverse_mode: boolean): void;
    set_sorting_function(sorting_function: string | SortingFunction<Item>): void;
    set_up_event_handlers(): void;
    clear_event_handlers(): void;
    increase_rendered_offset(): void;
    reduce_rendered_offset(): void;
    remove_rendered_row(row: JQuery): void;
    clean_redraw(): void;
    hard_redraw(): void;
    insert_rendered_row(item: Item, get_insert_index: (list: Item[], item: Item) => number): void;
    sort(sorting_function: string, prop?: string): void;
    replace_list_data(list: Key[]): void;
};

const DEFAULTS = {
    INITIAL_RENDER_COUNT: 80,
    LOAD_COUNT: 20,
    instances: new Map<string, ListWidget>(),
};

// ----------------------------------------------------
// This function describes (programmatically) how to use the ListWidget.
// ----------------------------------------------------

export function get_filtered_items<Key, Item>(
    value: string,
    list: Key[],
    opts: ListWidgetOpts<Key, Item>,
): Item[] {
    /*
        This is used by the main object (see `create`),
        but we split it out to make it a bit easier
        to test.
    */
    const get_item = opts.get_item;

    if (!opts.filter) {
        return list.map((key) => get_item(key));
    }

    if (opts.filter.filterer) {
        return opts.filter.filterer(
            list.map((key) => get_item(key)),
            value,
        );
    }

    const predicate = (item: Item): boolean => opts.filter!.predicate!(item, value);

    const result = [];

    for (const key of list) {
        const item = get_item(key);
        if (predicate(item)) {
            result.push(item);
        }
    }

    return result;
}

export const alphabetic_sort: GenericSortingFunction = (prop) =>
    function (a, b) {
        // The conversion to uppercase helps make the sorting case insensitive.
        const str1 = (a[prop] as string).toUpperCase();
        const str2 = (b[prop] as string).toUpperCase();

        if (str1 === str2) {
            return 0;
        } else if (str1 > str2) {
            return 1;
        }

        return -1;
    };

export const numeric_sort: GenericSortingFunction = (prop) =>
    function (a, b) {
        const a_prop = Number.parseFloat(a[prop] as string);
        const b_prop = Number.parseFloat(b[prop] as string);

        if (a_prop > b_prop) {
            return 1;
        } else if (a_prop === b_prop) {
            return 0;
        }

        return -1;
    };

const generic_sorts = {
    alphabetic: alphabetic_sort,
    numeric: numeric_sort,
};

export function generic_sort_functions<T extends Record<string, unknown>>(
    generic_func: keyof typeof generic_sorts,
    props: string[],
): Record<string, SortingFunction<T>> {
    const sorting_functions: Record<string, SortingFunction<T>> = {};
    for (const prop of props) {
        const key = `${prop}_${generic_func}`;
        sorting_functions[key] = generic_sorts[generic_func](prop);
    }

    return sorting_functions;
}

function is_scroll_position_for_render(scroll_container: HTMLElement): boolean {
    return (
        scroll_container.scrollHeight -
            (scroll_container.scrollTop + scroll_container.clientHeight) <
        10
    );
}

// @params
// $container: jQuery object to append to.
// list: The list of items to progressively append.
// opts: An object of random preferences.
export function create<Key = unknown, Item = Key>(
    $container: JQuery,
    list: Key[],
    opts: ListWidgetOpts<Key, Item>,
): ListWidget<Key, Item> | undefined {
    if (opts.name && DEFAULTS.instances.get(opts.name)) {
        // Clear event handlers for prior widget.
        const old_widget = DEFAULTS.instances.get(opts.name)!;
        old_widget.clear_event_handlers();
    }

    const meta: ListWidgetMeta<Key, Item> = {
        sorting_function: null,
        sorting_functions: new Map(),
        offset: 0,
        list,
        filtered_list: [],
        reverse_mode: false,
        filter_value: "",
        $scroll_container: scroll_util.get_scroll_element(opts.$simplebar_container),
    };

    const widget: ListWidget<Key, Item> = {
        get_current_list() {
            return meta.filtered_list;
        },

        filter_and_sort() {
            meta.filtered_list = get_filtered_items(meta.filter_value, meta.list, opts);

            if (meta.sorting_function) {
                meta.filtered_list.sort(meta.sorting_function);
            }

            if (meta.reverse_mode) {
                meta.filtered_list.reverse();
            }
        },

        // Used in case of Multiselect DropdownListWidget to retain
        // previously checked items even after widget redraws.
        retain_selected_items() {
            const items = opts.multiselect;

            if (items?.selected_items) {
                const data = items.selected_items;
                for (const value of data) {
                    const $list_item = $container.find(`li[data-value = "${value as string}"]`);
                    if ($list_item.length) {
                        const $link_elem = $list_item.find("a").expectOne();
                        $list_item.addClass("checked");
                        $link_elem.prepend($("<i>").addClass(["fa", "fa-check"]));
                    }
                }
            }
        },

        // Reads the provided list (in the scope directly above)
        // and renders the next block of messages automatically
        // into the specified container.
        render(how_many) {
            let load_count = how_many ?? DEFAULTS.LOAD_COUNT;
            if (opts.get_min_load_count) {
                load_count = opts.get_min_load_count(meta.offset, load_count);
            }

            // Stop once the offset reaches the length of the original list.
            if (meta.offset >= meta.filtered_list.length) {
                return;
            }

            const slice = meta.filtered_list.slice(meta.offset, meta.offset + load_count);

            let html = "";
            for (const item of slice) {
                const s = opts.modifier(item, meta.filter_value);

                if (typeof s !== "string") {
                    blueslip.error("List item is not a string", {item: s});
                    continue;
                }

                // append the HTML or nothing if corrupt (null, undef, etc.).
                if (s) {
                    html += s;
                }
            }

            $container.append($(html));
            meta.offset += load_count;

            if (opts.multiselect) {
                widget.retain_selected_items();
            }

            if (opts.callback_after_render) {
                opts.callback_after_render();
            }
        },

        render_item(item) {
            if (!opts.html_selector) {
                // We don't have any way to find the existing item.
                return;
            }
            const $html_item = meta.$scroll_container.find(opts.html_selector(item));
            if ($html_item.length === 0) {
                // We don't have the item in the current scroll container; it'll be
                // rendered with updated data when it is scrolled to.
                return;
            }

            const html = opts.modifier(item, meta.filter_value);
            if (typeof html !== "string") {
                blueslip.error("List item is not a string", {item: html});
                return;
            }

            // At this point, we have asserted we have all the information to replace
            // the html now.
            $html_item.replaceWith(html);
        },

        clear() {
            $container.empty();
            meta.offset = 0;
        },

        set_filter_value(filter_value) {
            meta.filter_value = filter_value;
        },

        set_reverse_mode(reverse_mode) {
            meta.reverse_mode = reverse_mode;
        },

        // the sorting function is either the function or a string which will be a key
        // for the sorting_functions map to get the function. In case of generic sort
        // functions like numeric and alphabetic, we pass the string in the given format -
        // "{property}_{numeric|alphabetic}" - e.g. "email_alphabetic" or "age_numeric".
        set_sorting_function(sorting_function) {
            if (typeof sorting_function === "function") {
                meta.sorting_function = sorting_function;
            } else if (typeof sorting_function === "string") {
                if (!meta.sorting_functions.has(sorting_function)) {
                    blueslip.error("Sorting function not found: " + sorting_function);
                    return;
                }

                meta.sorting_function = meta.sorting_functions.get(sorting_function)!;
            }
        },

        set_up_event_handlers() {
            // on scroll of the nearest scrolling container, if it hits the bottom
            // of the container then fetch a new block of items and render them.
            meta.$scroll_container.on("scroll.list_widget_container", function () {
                if (opts.post_scroll__pre_render_callback) {
                    opts.post_scroll__pre_render_callback();
                }

                if (opts.is_scroll_position_for_render === undefined) {
                    opts.is_scroll_position_for_render = is_scroll_position_for_render;
                }

                const should_render = opts.is_scroll_position_for_render(this);
                if (should_render) {
                    widget.render();
                }
            });

            if (opts.$parent_container) {
                opts.$parent_container.on("click.list_widget_sort", "[data-sort]", function () {
                    handle_sort($(this), widget);
                });
            }

            opts.filter?.$element?.on("input.list_widget_filter", function () {
                const value = this.value.toLocaleLowerCase();
                widget.set_filter_value(value);
                widget.hard_redraw();
            });
        },

        clear_event_handlers() {
            meta.$scroll_container.off("scroll.list_widget_container");

            if (opts.$parent_container) {
                opts.$parent_container.off("click.list_widget_sort", "[data-sort]");
            }

            opts.filter?.$element?.off("input.list_widget_filter");
        },

        increase_rendered_offset() {
            meta.offset = Math.min(meta.offset + 1, meta.filtered_list.length);
        },

        reduce_rendered_offset() {
            meta.offset = Math.max(meta.offset - 1, 0);
        },

        remove_rendered_row(rendered_row) {
            rendered_row.remove();
            // We removed a rendered row, so we need to reduce one offset.
            widget.reduce_rendered_offset();
        },

        clean_redraw() {
            widget.filter_and_sort();
            widget.clear();
            widget.render(DEFAULTS.INITIAL_RENDER_COUNT);
        },

        hard_redraw() {
            widget.clean_redraw();
            if (opts.filter?.onupdate) {
                opts.filter.onupdate();
            }
        },

        insert_rendered_row(item, get_insert_index) {
            // NOTE: Caller should call `filter_and_sort` before calling this function
            // so that `meta.filtered_list` already has the `item`.
            if (meta.filtered_list.length <= 2) {
                // Avoids edge cases for us and could be faster too.
                widget.clean_redraw();
                return;
            }

            assert(
                opts.filter?.predicate,
                "filter.predicate should be defined for insert_rendered_row",
            );
            if (!opts.filter.predicate(item, meta.filter_value)) {
                return;
            }

            // We need to insert the row for it to be displayed at the
            // correct position. filtered_list must contain the new item
            // since we know it is not hidden from the above check.
            const insert_index = get_insert_index(meta.filtered_list, item);

            // Rows greater than `offset` are not rendered in the DOM by list_widget;
            // for those, there's nothing to update.
            if (insert_index <= meta.offset) {
                if (!opts.html_selector) {
                    blueslip.error(
                        "Please specify modifier and html_selector when creating the widget.",
                    );
                }
                const rendered_row = opts.modifier(item, meta.filter_value);
                if (insert_index === meta.filtered_list.length - 1) {
                    const $target_row = opts.html_selector!(meta.filtered_list[insert_index - 1]);
                    $target_row.after(rendered_row);
                } else {
                    const $target_row = opts.html_selector!(meta.filtered_list[insert_index + 1]);
                    $target_row.before(rendered_row);
                }
                widget.increase_rendered_offset();
            }
        },

        sort(sorting_function, prop) {
            const key = prop ? `${prop}_${sorting_function}` : sorting_function;
            widget.set_sorting_function(key);
            widget.hard_redraw();
        },

        replace_list_data(list) {
            /*
                We mostly use this widget for lists where you are
                not adding or removing rows, so when you do modify
                the list, we have a brute force solution.
            */
            meta.list = list;
            widget.hard_redraw();
        },
    };

    widget.set_up_event_handlers();

    if (opts.sort_fields) {
        for (const [name, sorting_function] of Object.entries(opts.sort_fields)) {
            meta.sorting_functions.set(name, sorting_function);
        }
    }

    if (opts.init_sort) {
        widget.set_sorting_function(opts.init_sort);
    }

    if (opts.initially_descending_sort) {
        widget.set_reverse_mode(true);
        opts.$simplebar_container.find(".active").addClass("descend");
    }

    widget.clean_redraw();

    // Save the instance for potential future retrieval if a name is provided.
    if (opts.name) {
        DEFAULTS.instances.set(opts.name, widget);
    }

    return widget;
}

export function get(name: string): ListWidget | false {
    return DEFAULTS.instances.get(name) ?? false;
}

export function handle_sort($th: JQuery, list: ListWidget): void {
    /*
        one would specify sort parameters like this:
            - name => sort alphabetic.
            - age  => sort numeric.
            - status => look up `status` in sort_fields
                        to find custom sort function

        <thead>
            <th data-sort="alphabetic" data-sort-prop="name"></th>
            <th data-sort="numeric" data-sort-prop="age"></th>
            <th data-sort="status"></th>
        </thead>
        */
    const sort_type: string = $th.data("sort");
    const prop_name: string = $th.data("sort-prop");

    if ($th.hasClass("active")) {
        if (!$th.hasClass("descend")) {
            $th.addClass("descend");
        } else {
            $th.removeClass("descend");
        }
    } else {
        $th.siblings(".active").removeClass("active");
        $th.addClass("active");
    }

    list.set_reverse_mode($th.hasClass("descend"));

    // if `prop_name` is defined, it will trigger the generic sort functions,
    // and not if it is undefined.
    list.sort(sort_type, prop_name);
}

export const default_get_item = <T = unknown>(item: T): T => item;