Menus.js

/*
 * GNU AGPL-3.0 License
 *
 * Copyright (c) 2021 - present core.ai . All rights reserved.
 * Original work Copyright (c) 2012 - 2021 Adobe Systems Incorporated. All rights reserved.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see https://opensource.org/licenses/AGPL-3.0.
 *
 */

// @INCLUDE_IN_API_DOCS

/*global logger*/

define(function (require, exports, module) {


    let _ = require("thirdparty/lodash");

    // Load dependent modules
    let Commands = require("command/Commands"),
        EventDispatcher = require("utils/EventDispatcher"),
        KeyBindingManager = require("command/KeyBindingManager"),
        Keys = require("command/Keys"),
        Strings = require("strings"),
        StringUtils = require("utils/StringUtils"),
        CommandManager = require("command/CommandManager"),
        PopUpManager = require("widgets/PopUpManager"),
        ViewUtils = require("utils/ViewUtils"),
        Metrics = require("utils/Metrics"),
        MainViewManager = require("view/MainViewManager"),
        AppInit = require("utils/AppInit"),
        DeprecationWarning = require("utils/DeprecationWarning");

    // make sure the global brackets letiable is loaded
    require("utils/Global");

    const KEY = Keys.KEY;
    const allMenuCommands = new Set();
    /**
     * Brackets Application Menu Constants
     * @enum {string}
     */
    let AppMenuBar = {
        FILE_MENU: "file-menu",
        EDIT_MENU: "edit-menu",
        FIND_MENU: "find-menu",
        VIEW_MENU: "view-menu",
        NAVIGATE_MENU: "navigate-menu",
        DEBUG_MENU: "debug-menu",
        HELP_MENU: "help-menu"
    };

    /**
     * Brackets Context Menu Constants
     * @enum {string}
     */
    let ContextMenuIds = {
        EDITOR_MENU: "editor-context-menu",
        INLINE_EDITOR_MENU: "inline-editor-context-menu",
        PROJECT_MENU: "project-context-menu",
        WORKING_SET_CONTEXT_MENU: "workingset-context-menu",
        WORKING_SET_CONFIG_MENU: "workingset-configuration-menu",
        SPLITVIEW_MENU: "splitview-menu"
    };

    /**
     * Brackets well known submenus
     * @enum {string}
     */
    let SubMenuIds = {
        GIT_SUB_MENU: "git-submenu"
    };

    /**
     * Event triggered before the context menu opens.
     * @event EVENT_BEFORE_CONTEXT_MENU_OPEN
     */
    const EVENT_BEFORE_CONTEXT_MENU_OPEN = "beforeContextMenuOpen";

    /**
     * Event triggered before the context menu closes.
     * @event EVENT_BEFORE_CONTEXT_MENU_CLOSE
     */
    const EVENT_BEFORE_CONTEXT_MENU_CLOSE = "beforeContextMenuClose";

    /**
     * Event triggered before a sub-menu opens.
     * @event EVENT_BEFORE_SUB_MENU_OPEN
     */
    const EVENT_BEFORE_SUB_MENU_OPEN = "beforeSubMenuOpen";

    /**
     * Event triggered before a sub-menu closes.
     * @event EVENT_BEFORE_SUB_MENU_CLOSE
     */
    const EVENT_BEFORE_SUB_MENU_CLOSE = "beforeSubMenuClose";

    /**
     * Event triggered when a menu or menu is added
     * @event EVENT_MENU_ADDED
     */
    const EVENT_MENU_ADDED = "menuAdded";

    /**
     * Event triggered when a menu or submenu is added
     * @event EVENT_SUB_MENU_ADDED
     */
    const EVENT_SUB_MENU_ADDED = "subMenuAdded";

    /**
     * Event triggered when a menu item is added
     * @event EVENT_MENU_ITEM_ADDED
     */
    const EVENT_MENU_ITEM_ADDED = "menuItemAdded";



    // Define each section as a separate constant
    const FILE_OPEN_CLOSE_COMMANDS = { sectionMarker: Commands.FILE_NEW };
    const FILE_SAVE_COMMANDS = { sectionMarker: Commands.FILE_SAVE };
    const FILE_LIVE = { sectionMarker: Commands.FILE_LIVE_FILE_PREVIEW };
    const FILE_SETTINGS = { sectionMarker: Commands.FILE_EXTENSION_MANAGER };
    const FILE_EXTENSION_MANAGER = { sectionMarker: Commands.FILE_EXTENSION_MANAGER }; // Deprecated

    const EDIT_UNDO_REDO_COMMANDS = { sectionMarker: Commands.EDIT_UNDO };
    const EDIT_TEXT_COMMANDS = { sectionMarker: Commands.EDIT_CUT };
    const EDIT_SELECTION_COMMANDS = { sectionMarker: Commands.EDIT_SELECT_ALL };
    const EDIT_MODIFY_SELECTION = { sectionMarker: Commands.EDIT_INDENT };
    const EDIT_COMMENT_SELECTION = { sectionMarker: Commands.EDIT_LINE_COMMENT };
    const EDIT_CODE_HINTS_COMMANDS = { sectionMarker: Commands.SHOW_CODE_HINTS };
    const EDIT_TOGGLE_OPTIONS = { sectionMarker: Commands.TOGGLE_CLOSE_BRACKETS };

    const FIND_FIND_COMMANDS = { sectionMarker: Commands.CMD_FIND };
    const FIND_FIND_IN_COMMANDS = { sectionMarker: Commands.CMD_FIND_IN_FILES };
    const FIND_REPLACE_COMMANDS = { sectionMarker: Commands.CMD_REPLACE };

    const VIEW_HIDESHOW_COMMANDS = { sectionMarker: Commands.VIEW_HIDE_SIDEBAR };
    const VIEW_FONTSIZE_COMMANDS = { sectionMarker: Commands.VIEW_ZOOM_SUBMENU };
    const VIEW_TOGGLE_OPTIONS = { sectionMarker: Commands.TOGGLE_ACTIVE_LINE };

    const NAVIGATE_GOTO_COMMANDS = { sectionMarker: Commands.NAVIGATE_QUICK_OPEN };
    const NAVIGATE_DOCUMENTS_COMMANDS = { sectionMarker: Commands.NAVIGATE_NEXT_DOC };
    const NAVIGATE_OS_COMMANDS = { sectionMarker: Commands.NAVIGATE_SHOW_IN_FILE_TREE };
    const NAVIGATE_QUICK_EDIT_COMMANDS = { sectionMarker: Commands.TOGGLE_QUICK_EDIT };
    const NAVIGATE_QUICK_DOCS_COMMANDS = { sectionMarker: Commands.TOGGLE_QUICK_DOCS };



    /**
     * Brackets Application Menu Section Constants
     * It is preferred that plug-ins specify the location of new MenuItems
     * in terms of a menu section rather than a specific MenuItem. This provides
     * looser coupling to Bracket's internal MenuItems and makes menu organization
     * more semantic.
     * Use these constants as the "relativeID" parameter when calling addMenuItem() and
     * specify a position of FIRST_IN_SECTION or LAST_IN_SECTION.
     *
     * Menu sections are denoted by dividers or the beginning/end of a menu
     *
     * @enum {string}
     */
    const MenuSection = {
        FILE_OPEN_CLOSE_COMMANDS,
        FILE_SAVE_COMMANDS,
        FILE_LIVE,
        FILE_SETTINGS,
        FILE_EXTENSION_MANAGER, // Deprecated

        EDIT_UNDO_REDO_COMMANDS,
        EDIT_TEXT_COMMANDS,
        EDIT_SELECTION_COMMANDS,
        EDIT_MODIFY_SELECTION,
        EDIT_COMMENT_SELECTION,
        EDIT_CODE_HINTS_COMMANDS,
        EDIT_TOGGLE_OPTIONS,

        FIND_FIND_COMMANDS,
        FIND_FIND_IN_COMMANDS,
        FIND_REPLACE_COMMANDS,

        VIEW_HIDESHOW_COMMANDS,
        VIEW_FONTSIZE_COMMANDS,
        VIEW_TOGGLE_OPTIONS,

        NAVIGATE_GOTO_COMMANDS,
        NAVIGATE_DOCUMENTS_COMMANDS,
        NAVIGATE_OS_COMMANDS,
        NAVIGATE_QUICK_EDIT_COMMANDS,
        NAVIGATE_QUICK_DOCS_COMMANDS
    };


    /**
     * Insertion position constants
     * Used by addMenu(), addMenuItem(), and addSubMenu() to
     * specify the relative position of a newly created menu object
     * @enum {string}
     */
    const BEFORE = "before",
        AFTER = "after",
        FIRST = "first",
        LAST = "last",
        FIRST_IN_SECTION = "firstInSection",
        LAST_IN_SECTION = "lastInSection";

    /**
     * Other constants
     */
    let DIVIDER = "---";
    let SUBMENU = "SUBMENU";

    /**
     * Maps menuID's to Menu objects
     * @type {Object} menuMap
     * @property {Object.<string, Menu>} menuID - A map of Menu IDs to Menu objects.
     * @private
     */
    let menuMap = {};

    /**
     * Maps contextMenuID's to ContextMenu objects
     * @type {Object} contextMenuMap
     * @property {Object.<string, ContextMenu>} contextMenuID - A map of ContextMenu IDs to ContextMenu objects.
     * @private
     */
    let contextMenuMap = {};

    /**
     * Maps menuItemID's to MenuItem object
     * @type {Object} menuItemMap
     * @property {Object.<string, MenuItem>} menuItemID - A map of MenuItem IDs to MenuItem objects.
     * @private
     */
    let menuItemMap = {};

    /**
     * Maps menuItemID's to ContextMenu objects
     * @type {Object} subMenuItemMap
     * @property {Object.<string, ContextMenu>} menuItemId - A map of MenuItem IDs to ContextMenu objects.
     * @private
     */
    let subMenuItemMap = {};

    /**
     * Retrieves the Menu object for the corresponding id.
     * @param {string} id
     * @return {Menu}
     */
    function getMenu(id) {
        return menuMap[id];
    }

    /**
     * Retrieves the subMenu object for the corresponding id if present.
     * @param {string} id
     * @return {Menu}
     */
    function getSubMenu(id) {
        return getContextMenu(id);
    }

    /**
     * retruns a set containing all commands that has a menu item registered
     * @returns {Set<string>}
     */
    function getAllMenuItemCommands() {
        return new Set(allMenuCommands);
    }

    /**
     * Retrieves the map of all Menu objects.
     * @return {Object.<string, Menu>}
     */
    function getAllMenus() {
        return menuMap;
    }

    /**
     * Retrieves the ContextMenu object for the corresponding id.
     * @param {string} id
     * @return {ContextMenu}
     */
    function getContextMenu(id) {
        return contextMenuMap[id];
    }

    /**
    * Removes the attached event listeners from the corresponding object.
    * @param {MenuItem} menuItem
    * @private
    */
    function removeMenuItemEventListeners(menuItem) {
        menuItem._command
            .off("enabledStateChange", menuItem._enabledChanged)
            .off("checkedStateChange", menuItem._checkedChanged)
            .off("nameChange", menuItem._nameChanged)
            .off("keyBindingAdded", menuItem._keyBindingAdded)
            .off("keyBindingRemoved", menuItem._keyBindingRemoved);
    }

    /**
     * Retrieves the MenuItem object for the corresponding id.
     * @param {string} id
     * @return {MenuItem}
     */
    function getMenuItem(id) {
        return menuItemMap[id];
    }

    function _getHTMLMenu(id) {
        return $("#" + StringUtils.jQueryIdEscape(id)).get(0);
    }

    function _getHTMLMenuItem(id) {
        return $("#" + StringUtils.jQueryIdEscape(id)).get(0);
    }

    function _addKeyBindingToMenuItem(commandID, $menuItem, key, displayKey) {
        let $shortcut = $menuItem.find(".menu-shortcut");

        if ($shortcut.length === 0) {
            const html = KeyBindingManager.canAssignBinding(commandID) ?
                "<span class='menu-shortcut' />" :
                "<span class='menu-shortcut fixed-shortcut' />";
            $shortcut = $(html);
            $menuItem.append($shortcut);
        }

        $shortcut.data("key", key);
        $shortcut.text(KeyBindingManager.formatKeyDescriptor(displayKey));
    }

    function _addExistingKeyBinding(menuItem) {
        const commandID = menuItem.getCommand().getID();
        let bindings = KeyBindingManager.getKeyBindings(commandID),
            binding = null;

        if (bindings.length > 0) {
            // add the latest key binding
            binding = bindings[bindings.length - 1];
            _addKeyBindingToMenuItem(commandID, $(_getHTMLMenuItem(menuItem.id)), binding.key, binding.displayKey);
        }

        return binding;
    }

    let _menuDividerIDCount = 1;
    function _getNextMenuItemDividerID() {
        return "brackets-menuDivider-" + _menuDividerIDCount++;
    }

    // Help function for inserting elements into a list
    function _insertInList($list, $element, position, $relativeElement) {
        // Determine where to insert. Default is LAST.
        let inserted = false;
        if (position) {

            // Adjust relative position for menu section positions since $relativeElement
            // has already been resolved by _getRelativeMenuItem() to a menuItem
            if (position === FIRST_IN_SECTION) {
                position = BEFORE;
            } else if (position === LAST_IN_SECTION) {
                position = AFTER;
            }

            if (position === FIRST) {
                $list.prepend($element);
                inserted = true;
            } else if ($relativeElement && $relativeElement.length > 0) {
                if (position === AFTER) {
                    $relativeElement.after($element);
                    inserted = true;
                } else if (position === BEFORE) {
                    $relativeElement.before($element);
                    inserted = true;
                }
            }
        }

        // Default to LAST
        if (!inserted) {
            $list.append($element);
        }
    }

    /**
     * MenuItem represents a single menu item that executes a Command or a menu divider. MenuItems
     * may have a sub-menu. A MenuItem may correspond to an HTML-based
     * menu item or a native menu item if Brackets is running in a native application shell
     *
     * Since MenuItems may have a native implementation clients should create MenuItems through
     * addMenuItem() and should NOT construct a MenuItem object directly.
     * Clients should also not access HTML content of a menu directly and instead use
     * the MenuItem API to query and modify menus items.
     *
     * MenuItems are views on to Command objects so modify the underlying Command to modify the
     * name, enabled, and checked state of a MenuItem. The MenuItem will update automatically
     *
     * @constructor
     *
     * @param {string} id
     * @param {string|Command} command - the Command this MenuItem will reflect.
     *                                   Use DIVIDER to specify a menu divider
     * @param [options]
     * @param {boolean} options.hideWhenCommandDisabled will not show the menu item if command is disabled.
     */
    function MenuItem(id, command, options = {}) {
        this.id = id;
        this.isDivider = (command === DIVIDER);
        this.isNative = false;

        if (!this.isDivider && command !== SUBMENU) {
            // Bind event handlers
            this._enabledChanged = this._enabledChanged.bind(this);
            this._checkedChanged = this._checkedChanged.bind(this);
            this._nameChanged = this._nameChanged.bind(this);
            this._keyBindingAdded = this._keyBindingAdded.bind(this);
            this._keyBindingRemoved = this._keyBindingRemoved.bind(this);

            this._command = command;
            this._hideWhenCommandDisabled = options.hideWhenCommandDisabled;
            this._command
                .on("enabledStateChange", this._enabledChanged)
                .on("checkedStateChange", this._checkedChanged)
                .on("nameChange", this._nameChanged)
                .on("keyBindingAdded", this._keyBindingAdded)
                .on("keyBindingRemoved", this._keyBindingRemoved);
        }
    }

    /**
     * Menu represents a top-level menu in the menu bar. A Menu may correspond to an HTML-based
     * menu or a native menu if Brackets is running in a native application shell.
     *
     * Since menus may have a native implementation clients should create Menus through
     * addMenu() and should NOT construct a Menu object directly.
     * Clients should also not access HTML content of a menu directly and instead use
     * the Menu API to query and modify menus.
     *
     * @constructor
     *
     * @param {string} id
     */
    function Menu(id) {
        this.id = id;
        // Submenus inherit their owner's namespace even though they render as context menus.
        this._metricsEventType = Metrics.EVENT_TYPE.APP_MENU;
    }

    Menu.prototype._getMenuItemId = function (commandId) {
        return (this.id + "-" + commandId);
    };

    /**
     * Determine MenuItem in this Menu, that has the specified command
     *
     * @param {Command} command - the command to search for.
     * @private
     * @return {?HTMLLIElement} menu item list element
     */
    Menu.prototype._getMenuItemForCommand = function (command) {
        if (!command) {
            return null;
        }
        let foundMenuItem = menuItemMap[this._getMenuItemId(command.getID())];
        if (!foundMenuItem) {
            return null;
        }
        return $(_getHTMLMenuItem(foundMenuItem.id)).closest("li");
    };

    /**
     * Determine relative MenuItem
     *
     * @param {?string} relativeID - id of command (future: sub-menu).
     * @param {?string} position - only needed when relativeID is a MenuSection
     * @return {?HTMLLIElement} menu item list element
     * @private
     */
    Menu.prototype._getRelativeMenuItem = function (relativeID, position) {
        let $relativeElement;

        if (relativeID) {
            if (position === FIRST_IN_SECTION || position === LAST_IN_SECTION) {
                if (!relativeID.hasOwnProperty("sectionMarker")) {
                    console.error("Bad Parameter in _getRelativeMenuItem(): relativeID must be a MenuSection when position refers to a menu section");
                    return null;
                }

                // Determine the $relativeElement by traversing the sibling list and
                // stop at the first divider found
                // TODO: simplify using nextUntil()/prevUntil()
                let $sectionMarker = this._getMenuItemForCommand(CommandManager.get(relativeID.sectionMarker));
                if (!$sectionMarker) {
                    console.error("_getRelativeMenuItem(): MenuSection " + relativeID.sectionMarker +
                        " not found in Menu " + this.id);
                    return null;
                }
                let $listElem = $sectionMarker;
                $relativeElement = $listElem;
                while (true) {
                    $listElem = (position === FIRST_IN_SECTION ? $listElem.prev() : $listElem.next());
                    if ($listElem.length === 0) {
                        break;
                    } else if ($listElem.find(".divider").length > 0) {
                        break;
                    } else {
                        $relativeElement = $listElem;
                    }
                }

            } else {
                if (relativeID.hasOwnProperty("sectionMarker")) {
                    console.error("Bad Parameter in _getRelativeMenuItem(): if relativeID is a MenuSection, position must be FIRST_IN_SECTION or LAST_IN_SECTION");
                    return null;
                }

                // handle FIRST, LAST, BEFORE, & AFTER
                let command = CommandManager.get(relativeID);
                if (command) {
                    // Lookup Command for this Command id
                    // Find MenuItem that has this command
                    $relativeElement = this._getMenuItemForCommand(command);
                }
                if (!$relativeElement) {
                    console.error("_getRelativeMenuItem(): MenuItem with Command id " + relativeID +
                        " not found in Menu " + this.id);
                    return null;
                }
            }

            return $relativeElement;

        } else if (position && position !== FIRST && position !== LAST) {
            console.error("Bad Parameter in _getRelativeMenuItem(): relative position specified with no relativeID");
            return null;
        }

        return $relativeElement;
    };

    /**
     * Removes the specified menu item from this Menu. Key bindings are unaffected; use KeyBindingManager
     * directly to remove key bindings if desired.
     *
     * @param {!string | Command} command - command the menu would execute if we weren't deleting it.
     */
    Menu.prototype.removeMenuItem = function (command) {
        let menuItemID,
            commandID;

        if (!command) {
            console.error("removeMenuItem(): missing required parameters: command");
            return;
        }

        if (typeof (command) === "string") {
            let commandObj = CommandManager.get(command);
            if (!commandObj) {
                console.error("removeMenuItem(): command not found: " + command);
                return;
            }
            commandID = command;
        } else {
            commandID = command.getID();
        }
        menuItemID = this._getMenuItemId(commandID);

        let menuItem = getMenuItem(menuItemID);
        removeMenuItemEventListeners(menuItem);

        $(_getHTMLMenuItem(menuItemID)).parent().remove();

        delete menuItemMap[menuItemID];
    };

    /**
     * Removes the specified menu divider from this Menu.
     *
     * @param {!string} menuItemID - the menu item id of the divider to remove.
     */
    Menu.prototype.removeMenuDivider = function (menuItemID) {
        let menuItem,
            $HTMLMenuItem;

        if (!menuItemID) {
            console.error("removeMenuDivider(): missing required parameters: menuItemID");
            return;
        }

        menuItem = getMenuItem(menuItemID);

        if (!menuItem) {
            console.error("removeMenuDivider(): parameter menuItemID: %s is not a valid menu item id", menuItemID);
            return;
        }

        if (!menuItem.isDivider) {
            console.error("removeMenuDivider(): parameter menuItemID: %s is not a menu divider", menuItemID);
            return;
        }

        // Targeting parent to get the menu divider <hr> and the <li> that contains it
        $HTMLMenuItem = $(_getHTMLMenuItem(menuItemID)).parent();
        if ($HTMLMenuItem) {
            $HTMLMenuItem.remove();
        } else {
            console.error("removeMenuDivider(): HTML menu divider not found: %s", menuItemID);
            return;
        }

        if (!menuItemMap[menuItemID]) {
            console.error("removeMenuDivider(): menu divider not found in menuItemMap: %s", menuItemID);
            return;
        }

        delete menuItemMap[menuItemID];
    };

    /**
     * Adds a new menu item with the specified id and display text. The insertion position is
     * specified via the relativeID and position arguments which describe a position
     * relative to another MenuItem or MenuGroup. It is preferred that plug-ins
     * insert new  MenuItems relative to a menu section rather than a specific
     * MenuItem (see Menu Section Constants).
     *
     * TODO: Sub-menus are not yet supported, but when they are implemented this API will
     * allow adding new MenuItems to sub-menus as well.
     *
     * Note, keyBindings are bound to Command objects not MenuItems. The provided keyBindings
     *      will be bound to the supplied Command object rather than the MenuItem.
     *
     * @param {!string | Command} command - the command the menu will execute.
     *      Pass Menus.DIVIDER for a menu divider, or just call addMenuDivider() instead.
     * @param {?(string | {key: string, platform: string[]})} [keyBindings] - Register one or more key bindings to associate with the supplied command
     * @param {?string} [position] - constant defining the position of new MenuItem relative to
     *      other MenuItems. Values:
     *          - With no relativeID, use Menus.FIRST or LAST (default is LAST)
     *          - Relative to a command id, use BEFORE or AFTER (required)
     *          - Relative to a MenuSection, use FIRST_IN_SECTION or LAST_IN_SECTION (required)
     * @param {?string} [relativeID] - command id OR one of the MenuSection.* constants. Required
     *      for all position constants except FIRST and LAST.
     * @param [options]
     * @param {boolean} options.hideWhenCommandDisabled will not show the menu item if command is disabled. Helps to
     *   clear the clutter on greyed out menu items if not applicable to context.
     *
     * @return {MenuItem} the newly created MenuItem
     */
    Menu.prototype.addMenuItem = function (command, keyBindings, position, relativeID, options = {}) {
        const self = this;
        let id,
            $menuItem,
            menuItem,
            name,
            commandID;

        if (!command) {
            console.error("addMenuItem(): missing required parameters: command");
            return null;
        }

        if (typeof (command) === "string") {
            if (command === DIVIDER) {
                name = DIVIDER;
                commandID = _getNextMenuItemDividerID();
            } else {
                commandID = command;
                command = CommandManager.get(commandID);
                if (!command) {
                    console.error("addMenuItem(): commandID not found: " + commandID);
                    return null;
                }
                name = command.getName();
                if (!allMenuCommands.has(commandID)) {
                    allMenuCommands.add(commandID);
                }
            }
        } else {
            commandID = command.getID();
            name = command.getName();
            if (!allMenuCommands.has(commandID)) {
                allMenuCommands.add(commandID);
            }
        }

        // Internal id is the a composite of the parent menu id and the command id.
        id = self._getMenuItemId(commandID);

        if (menuItemMap[id]) {
            console.log("MenuItem added with same id of existing MenuItem: " + id);
            return null;
        }

        // create MenuItem
        menuItem = new MenuItem(id, command, {
            hideWhenCommandDisabled: options.hideWhenCommandDisabled
        });
        menuItemMap[id] = menuItem;


        if (name === DIVIDER) {
            $menuItem = $("<li><hr class='divider' id='" + id + "' /></li>");
        } else {
            // Create the HTML Menu
            let keyboardIcon = '';
            if (KeyBindingManager.canAssignBinding(commandID)) {
                keyboardIcon = `<span class='keyboard-icon' title='${Strings.KEYBOARD_SHORTCUT_CHANGE_TITLE}'><i class="fa-regular fa-keyboard"></i></span>`;
            }
            $menuItem = $("<li><a href='#' class='menuAnchor' id='" + id + "'> <span class='menu-name'></span>" +
                `<span class='right-pusher'></span>${keyboardIcon}` +
                "</a></li>");
            const $menuAnchor = $menuItem.find(".menuAnchor");

            $menuItem.find(".keyboard-icon").on("click", (event) => {
                KeyBindingManager.showShortcutSelectionDialog(command);
                event.preventDefault();
                event.stopPropagation();
            });

            $menuItem.on("click", function (event) {
                if ($menuAnchor.hasClass('disabled')) {
                    event.preventDefault();
                    event.stopPropagation();
                    return true;
                }
                Metrics.countEvent(self._metricsEventType || Metrics.EVENT_TYPE.UI_MENU, "click", menuItem._command.getID());
                logger.leaveTrail("UI Menu Click: " + menuItem._command.getID());
                MainViewManager.focusActivePane();
                const commandId = menuItem._command.getID();

                // NOTE: we handle save commands differently because we want save commands to go through the
                // CommandManager.execute() to trigger beforeExecuteCommand events consistently, whether invoked via
                // menu click or keyboard shortcut.
                // because there are listeners that uses beforeExecuteCommand to listen to save commands
                // (for ex: tabbar listens to save commands to add placeholder tabs to working set)
                // Other commands use direct execution to preserve file tree context
                if(commandId === Commands.FILE_SAVE ||
                   commandId === Commands.FILE_SAVE_AS ||
                   commandId === Commands.FILE_SAVE_ALL) {
                    CommandManager.execute(commandId);
                } else if (menuItem._command._options.eventSource) {
                    menuItem._command.execute({
                        eventSource: CommandManager.SOURCE_UI_MENU_CLICK,
                        sourceType: self.id
                    });
                } else {
                    menuItem._command.execute();
                }
            });

            let self = this;
            $menuItem.on("mouseenter", function () {
                // This is to prevent size jumps when the keyboard
                // icon hides and shows as selection changes
                $menuAnchor.addClass("use-invisible-for-width-compute");
                const currentWidth = window.getComputedStyle(this).width;
                $menuAnchor.removeClass("use-invisible-for-width-compute");
                $(this).css('min-width', currentWidth);
                self.closeSubMenu();
                // now show selection
                $menuItem.parent().find(".menuAnchor").removeClass("selected");
                if (!$menuAnchor.hasClass('disabled')) {
                    $menuAnchor.addClass("selected");
                }
            });
            $menuItem.on("mouseleave", function () {
                $(this).css('min-width', '');
                self.closeSubMenu();
                $menuItem.find(".menuAnchor").removeClass("selected");
            });
        }

        // Insert menu item
        let $relativeElement = this._getRelativeMenuItem(relativeID, position);
        _insertInList($("li#" + StringUtils.jQueryIdEscape(this.id) + " > ul.dropdown-menu"),
            $menuItem, position, $relativeElement);


        // Initialize MenuItem state
        if (menuItem.isDivider) {
            menuItem.dividerId = commandID;
        } else {
            if (keyBindings) {
                // Add key bindings. The MenuItem listens to the Command object to update MenuItem DOM with shortcuts.
                if (!Array.isArray(keyBindings)) {
                    keyBindings = [keyBindings];
                }
            }

            // Note that keyBindings passed during MenuItem creation take precedent over any existing key bindings
            KeyBindingManager.addBinding(commandID, keyBindings);

            // Look for existing key bindings
            _addExistingKeyBinding(menuItem);

            menuItem._checkedChanged();
            menuItem._enabledChanged();
            menuItem._nameChanged();
        }

        const menuId = self.id;
        exports.trigger(EVENT_MENU_ITEM_ADDED, menuId, commandID, menuItem);

        return menuItem;
    };

    /**
     * Inserts divider item in menu.
     * @param {?string} position - constant defining the position of new the divider relative
     *      to other MenuItems. Default is LAST.  (see Insertion position constants).
     * @param {?string} relativeID - id of menuItem, sub-menu, or menu section that the new
     *      divider will be positioned relative to. Required for all position constants
     *      except FIRST and LAST
     *
     * @return {MenuItem} the newly created divider
     */
    Menu.prototype.addMenuDivider = function (position, relativeID) {
        return this.addMenuItem(DIVIDER, "", position, relativeID);
    };

    /**
     * NOT IMPLEMENTED
     *
     * All properties are required unless noted as optional.
     *
     * @param {Array<{id: string, command: string | Command, bindings: string | Array<{key: string, platform: string}> | undefined}>} jsonStr
     * @param {?string} position - constant defining the position of the new MenuItem relative
     *      to other MenuItems. Default is LAST.  (see Insertion position constants).
     * @param {?string} relativeID - id of menuItem, sub-menu, or menu section that the new
     *      menuItem will be positioned relative to. Required when position is
     *      AFTER or BEFORE, ignored when position is FIRST or LAST.
     *
     * @return {MenuItem} the newly created MenuItem
     * @private
     */
    // Menu.prototype.createMenuItemsFromJSON = function (jsonStr, position, relativeID) {
    //     NOT IMPLEMENTED
    // };



    /**
     * NOT IMPLEMENTED
     * @param {!string} text displayed in menu item
     * @param {!string} id
     * @param {?string} position - constant defining the position of new the MenuItem relative
     *      to other MenuItems. Default is LAST.  (see Insertion position constants)
     * @param {?string} relativeID - id of menuItem, sub-menu, or menu section that the new
     *      menuItem will be positioned relative to. Required when position is
     *      AFTER or BEFORE, ignored when position is FIRST or LAST.
     *
     * @return {MenuItem} newly created menuItem for sub-menu
     * @private
     */
    // MenuItem.prototype.createSubMenu = function (text, id, position, relativeID) {
    //     NOT IMPLEMENTED
    // };

    /**
     *
     * Creates a new submenu and a menuItem and adds the menuItem of the submenu
     * to the menu and returns the submenu.
     *
     * A submenu will have the same structure of a menu with a additional field
     * parentMenuItem which has the reference of the submenu's parent menuItem.

     * A submenu will raise the following events:
     * - beforeSubMenuOpen
     * - beforeSubMenuClose
     *
     * Note, This function will create only a context submenu.
     *
     * TODO: Make this function work for Menus
     *
     *
     * @param {!string} name displayed in menu item of the submenu
     * @param {!string} id
     * @param {?string} position - constant defining the position of new MenuItem of the submenu relative to
     *      other MenuItems. Values:
     *          - With no relativeID, use Menus.FIRST or LAST (default is LAST)
     *          - Relative to a command id, use BEFORE or AFTER (required)
     *          - Relative to a MenuSection, use FIRST_IN_SECTION or LAST_IN_SECTION (required)
     * @param {?string} relativeID - command id OR one of the MenuSection.* constants. Required
     *      for all position constants except FIRST and LAST.
     *
     * @return {Menu} the newly created submenu
     */
    Menu.prototype.addSubMenu = function (name, id, position, relativeID) {

        if (!name || !id) {
            console.error("addSubMenu(): missing required parameters: name and id");
            return null;
        }

        // Guard against duplicate context menu ids
        if (contextMenuMap[id]) {
            console.log("Context menu added with id of existing Context Menu: " + id);
            return null;
        }

        let menu = new ContextMenu(id);
        menu._metricsEventType = this._metricsEventType;
        contextMenuMap[id] = menu;

        let menuItemID = this.id + "-" + id;

        if (menuItemMap[menuItemID]) {
            console.log("MenuItem added with same id of existing MenuItem: " + id);
            return null;
        }

        // create MenuItem
        let menuItem = new MenuItem(menuItemID, SUBMENU);
        menuItemMap[menuItemID] = menuItem;
        subMenuItemMap[menuItemID] = menu;

        menu.parentMenuItem = menuItem;

        // create MenuItem DOM
        // Create the HTML MenuItem
        let $menuItem = $("<li><a class='sub-menu-item menuAnchor' href='#' id='" + menuItemID + "'> " +
            "<span class='menu-name'>" + name + "</span>" +
            "<span class='right-pusher'></span>" +
            "<span>&rtrif;</span>" +
            "</a></li>");
        const $menuAnchor = $menuItem.find(".menuAnchor");

        let self = this;
        $menuItem.on("mouseenter", function (e) {
            $menuAnchor.addClass("use-invisible-for-width-compute");
            const currentWidth = window.getComputedStyle(this).width;
            $menuAnchor.removeClass("use-invisible-for-width-compute");
            $(this).css('min-width', currentWidth);
            if (self.openSubMenu && self.openSubMenu.id === menu.id) {
                return;
            }
            self.closeSubMenu();
            self.openSubMenu = menu;
            menu.open();
            $menuItem.parent().find(".menuAnchor").removeClass("selected");
            $menuItem.find(".menuAnchor").addClass("selected");
        });

        $menuItem.on("mouseleave", function () {
            $(this).css('min-width', '');
            $menuItem.find(".menuAnchor").removeClass("selected");
        });

        // Insert menu item
        let $relativeElement = this._getRelativeMenuItem(relativeID, position);
        _insertInList($("li#" + StringUtils.jQueryIdEscape(this.id) + " > ul.dropdown-menu"),
            $menuItem, position, $relativeElement);

        exports.trigger(EVENT_SUB_MENU_ADDED, id, menu);

        return menu;
    };


    /**
     * Removes the specified submenu from this Menu.
     *
     * Note, this function will only remove context submenus
     *
     * TODO: Make this function work for Menus
     *
     * @param {!string} subMenuID - the menu id of the submenu to remove.
     */
    Menu.prototype.removeSubMenu = function (subMenuID) {
        let subMenu,
            parentMenuItem,
            commandID = "";

        if (!subMenuID) {
            console.error("removeSubMenu(): missing required parameters: subMenuID");
            return;
        }

        subMenu = getContextMenu(subMenuID);

        if (!subMenu || !subMenu.parentMenuItem) {
            console.error("removeSubMenu(): parameter subMenuID: %s is not a valid submenu id", subMenuID);
            return;
        }

        parentMenuItem = subMenu.parentMenuItem;