@ukic/web-components 2.35.2 → 3.0.0-alpha.10

package/dist/collection/components/ic-menu/ic-menu.js

@@ -1,18 +1,26 @@
 import { h, Host, Fragment, } from "@stencil/core";
 import { createPopper } from "@popperjs/core";
 import Check from "../../assets/check-icon.svg";
-import { onComponentRequiredPropUndefined } from "../../utils/helpers";
+import { getOptionsWithoutGroupTitlesCount, isMacDevice, onComponentRequiredPropUndefined, } from "../../utils/helpers";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export class Menu {
     constructor() {
+        this.ACTIVE_DESCENDANT = "aria-activedescendant";
+        this.CLEAR_BUTTON_ID = "clear-button";
+        this.SEARCH_BAR_TAG = "IC-SEARCH-BAR";
         this.disabledOptionSelected = false;
         this.hasPreviouslyBlurred = false;
         this.hasTimedOut = false;
         this.isLoading = false;
+        this.isMultiSelect = false;
         this.isSearchBar = false;
         this.isSearchableSelect = false;
-        // Prevents menu re-opening immediately after it is closed on blur when clicking input.
-        this.preventClickOpen = false;
+        this.lastOptionSelected = null; // Index of last option selected
+        this.lastOptionFocused = null; // Index of last option focused
+        this.multiOptionClicked = null;
+        this.preventClickOpen = false; // Prevents menu re-opening immediately after it is closed on blur when clicking input.
+        this.preventMenuFocus = false; // (When multiple) ensures focus moves straight to select all button from menu.
+        this.shiftPressed = false;
         this.ungroupedOptions = [];
         this.handleClearListener = () => {
             this.optionHighlighted = "";
@@ -23,9 +31,16 @@ export class Menu {
         };
         this.handleMenuChange = (open, focusInput) => {
             this.menuStateChange.emit({ open, focusInput });
-            if (!open && focusInput !== false) {
-                this.inputEl.focus();
-                this.preventClickOpen = false;
+            if (!open) {
+                if (focusInput !== false) {
+                    this.inputEl.focus();
+                    this.preventClickOpen = false;
+                }
+                // Reset optionHighlighted so previously highlighted option doesn't get reselected when Enter pressed
+                if (this.isMultiSelect) {
+                    this.optionHighlighted = undefined;
+                    this.multiOptionClicked = null;
+                }
             }
         };
         this.setNextOptionValue = (selectedOptionIndex) => {
@@ -57,27 +72,37 @@ export class Menu {
             }
         };
         this.getParentEl = (parent) => {
-            if (parent.tagName === "IC-SEARCH-BAR") {
+            if (parent.tagName === this.SEARCH_BAR_TAG) {
                 this.isSearchBar = true;
             }
-            else if (parent.tagName === "IC-SELECT" &&
-                parent.getAttribute("searchable") !== null &&
-                parent.getAttribute("searchable") !== undefined) {
-                this.isSearchableSelect = true;
+            else if (parent.tagName === "IC-SELECT") {
+                if (parent.getAttribute("searchable") !== null &&
+                    parent.getAttribute("searchable") !== undefined) {
+                    this.isSearchableSelect = true;
+                }
+                else if (parent.getAttribute("multiple") !== null &&
+                    parent.getAttribute("multiple") !== undefined) {
+                    this.isMultiSelect = true;
+                }
             }
         };
+        // Open menu when up or down arrow keys are pressed
         this.arrowBehaviour = (event) => {
             event.preventDefault();
             this.handleMenuChange(true);
         };
-        this.setMenuOptions = () => this.isSearchBar ? this.options : this.ungroupedOptions;
+        this.getMenuOptions = () => this.isSearchBar ? this.options : this.ungroupedOptions;
+        // Set option that is focused and so should show focus state
         this.setHighlightedOption = (highlightedIndex) => {
-            const menuOptions = this.setMenuOptions();
+            const menuOptions = this.getMenuOptions();
             menuOptions[highlightedIndex] &&
                 !menuOptions[highlightedIndex].timedOut &&
                 (this.optionHighlighted =
                     menuOptions[highlightedIndex][this.valueField] || undefined);
         };
+        // Determines keyboard behaviour when selection is automatic
+        // (i.e. you don't have to press Enter select an option - just focus on it)
+        // and menu is closed
         this.autoSetInputValueKeyboardOpen = (event) => {
             const selectedOptionIndex = this.ungroupedOptions.findIndex((option) => option[this.valueField] === this.value);
             this.keyboardNav = false;
@@ -94,147 +119,278 @@ export class Menu {
                     break;
                 case " ":
                 case "Enter":
-                    if (event.target.id !== "clear-button") {
+                    if (event.target.id !== this.CLEAR_BUTTON_ID) {
                         this.handleMenuChange(true);
                     }
                     break;
             }
         };
-        this.manSetInputValueKeyboardOpen = (event) => {
-            const menuOptions = this.setMenuOptions();
-            const highlightedOptionIndex = menuOptions.findIndex((option) => option[this.valueField] === this.optionHighlighted);
-            const getOptionId = (index) => { var _a; return (_a = Array.from(this.host.querySelectorAll("li"))[index]) === null || _a === void 0 ? void 0 : _a.id; };
+        this.selectHighlightedOption = (options, highlightedOptionIndex) => {
+            if (!this.isLoading && !this.hasTimedOut) {
+                this.keyboardNav = true;
+            }
             const isOpen = this.isSearchBar || this.isSearchableSelect || this.open;
-            switch (event.key) {
-                case "ArrowDown":
-                    this.keyboardNav = true;
-                    this.arrowBehaviour(event);
-                    if (highlightedOptionIndex < menuOptions.length - 1) {
-                        this.setHighlightedOption(highlightedOptionIndex + 1);
-                        this.menuOptionId.emit({
-                            optionId: getOptionId(highlightedOptionIndex + 1),
-                        });
-                    }
-                    else {
-                        this.setHighlightedOption(0);
-                        this.menuOptionId.emit({
-                            optionId: getOptionId(0),
-                        });
+            if (isOpen) {
+                if (highlightedOptionIndex >= 0) {
+                    if (options[highlightedOptionIndex] !== undefined) {
+                        if (this.isSearchBar &&
+                            options[highlightedOptionIndex].disabled === true) {
+                            this.disabledOptionSelected = true;
+                        }
+                        else {
+                            this.setInputValue(highlightedOptionIndex);
+                        }
                     }
-                    this.preventIncorrectTabOrder = false;
-                    this.focusFromSearchKeypress = false;
-                    break;
-                case "ArrowUp":
-                    this.keyboardNav = true;
-                    this.arrowBehaviour(event);
-                    if (highlightedOptionIndex <= 0 ||
-                        highlightedOptionIndex > menuOptions.length + 1) {
-                        this.setHighlightedOption(menuOptions.length - 1);
+                }
+                else {
+                    this.setInputValue(highlightedOptionIndex);
+                }
+            }
+            else {
+                this.handleMenuChange(true);
+            }
+        };
+        // Check if option is selected based on the index of the option
+        this.isOptionSelected = (index) => {
+            const menuOptions = this.getMenuOptions();
+            return this.value
+                ? this.value.includes(menuOptions[index][this.valueField])
+                : false;
+        };
+        // Deselect currently selected options when shift pressed, but keep certain options selected
+        this.deselectSelectedOptions = (optionsToKeepSelected) => {
+            const menuOptions = this.getMenuOptions();
+            if (this.value) {
+                const selectedOptionIndexes = this.value.map((value) => {
+                    return menuOptions.findIndex((option) => option[this.valueField] === value);
+                });
+                // Call setInputValue (which toggles the selected state) on options that need to be deselected
+                selectedOptionIndexes.forEach((index) => !optionsToKeepSelected.includes(index) && this.setInputValue(index));
+            }
+        };
+        // Determines keyboard behaviour when selection is manual (i.e. when you have to press Enter to select an option)
+        this.manualSetInputValueKeyboardOpen = (event) => {
+            const menuOptions = this.getMenuOptions();
+            // For preventing focus disappearing on currently focused option when Shift / Cmd / Ctrl pressed
+            // (i.e. when user is likely in the middle of executing a keyboard combination to select options)
+            const isKeyboardCombination = event.shiftKey || event.metaKey || event.ctrlKey;
+            const highlightedOptionIndex = this.getOptionHighlightedIndex();
+            const clickedMultiOptionIndex = menuOptions.findIndex((option) => option[this.valueField] === this.multiOptionClicked);
+            const getOptionId = (index) => { var _a; return (_a = Array.from(this.host.querySelectorAll("li"))[index]) === null || _a === void 0 ? void 0 : _a.id; };
+            // Space press should be equivalent to Enter when multi-select
+            if (event.key === " " && this.isMultiSelect) {
+                this.handleOptionSelect(event, highlightedOptionIndex);
+            }
+            else {
+                switch (event.key) {
+                    case "ArrowDown":
+                        this.keyboardNav = true;
+                        this.arrowBehaviour(event);
+                        if (this.multiOptionClicked) {
+                            // Set focus to option last clicked
+                            // Prevents it resetting to the top of the menu when user switches to using keyboard
+                            this.setHighlightedOption(clickedMultiOptionIndex);
+                            this.multiOptionClicked = null;
+                        }
+                        else {
+                            this.handleSingleShiftSelect(event, highlightedOptionIndex, menuOptions);
+                            if (highlightedOptionIndex < menuOptions.length - 1) {
+                                this.setHighlightedOption(highlightedOptionIndex + 1);
+                                this.menuOptionId.emit({
+                                    optionId: getOptionId(highlightedOptionIndex + 1),
+                                });
+                                this.handleSingleShiftSelect(event, highlightedOptionIndex + 1, menuOptions);
+                            }
+                            else {
+                                this.setHighlightedOption(0);
+                                this.menuOptionId.emit({
+                                    optionId: getOptionId(0),
+                                });
+                                this.handleSingleShiftSelect(event, 0, menuOptions);
+                            }
+                            // Deselect currently selected options if arrow was pressed for first time after shift is held
+                            if (this.isMultiSelect && this.shiftPressed) {
+                                this.deselectSelectedOptions([
+                                    highlightedOptionIndex,
+                                    this.getOptionHighlightedIndex(),
+                                ]);
+                                this.shiftPressed = false;
+                            }
+                        }
+                        this.lastOptionFocused = this.getOptionHighlightedIndex();
+                        this.preventIncorrectTabOrder = false;
+                        this.focusFromSearchKeypress = false;
+                        break;
+                    case "ArrowUp":
+                        this.keyboardNav = true;
+                        this.arrowBehaviour(event);
+                        if (this.multiOptionClicked) {
+                            // Set focus to option last clicked
+                            // Prevents it resetting to the bottom of the menu when user switches to using keyboard
+                            this.setHighlightedOption(clickedMultiOptionIndex);
+                            this.multiOptionClicked = null;
+                        }
+                        else {
+                            this.handleSingleShiftSelect(event, highlightedOptionIndex, menuOptions);
+                            if (highlightedOptionIndex <= 0 ||
+                                highlightedOptionIndex > menuOptions.length + 1) {
+                                this.setHighlightedOption(menuOptions.length - 1);
+                                this.menuOptionId.emit({
+                                    optionId: getOptionId(menuOptions.length - 1),
+                                });
+                                this.handleSingleShiftSelect(event, menuOptions.length - 1, menuOptions);
+                            }
+                            else {
+                                this.setHighlightedOption(highlightedOptionIndex - 1);
+                                this.menuOptionId.emit({
+                                    optionId: getOptionId(highlightedOptionIndex - 1),
+                                });
+                                this.handleSingleShiftSelect(event, highlightedOptionIndex - 1, menuOptions);
+                            }
+                            // Deselect currently selected options if arrow was pressed for first time after shift is held
+                            if (this.isMultiSelect && this.shiftPressed) {
+                                this.deselectSelectedOptions([
+                                    highlightedOptionIndex,
+                                    this.getOptionHighlightedIndex(),
+                                ]);
+                                this.shiftPressed = false;
+                            }
+                        }
+                        this.lastOptionFocused = this.getOptionHighlightedIndex();
+                        this.preventIncorrectTabOrder = false;
+                        this.focusFromSearchKeypress = false;
+                        break;
+                    case "Home": {
+                        const startOptionIndex = 0;
+                        this.keyboardNav = true;
+                        event.preventDefault();
+                        this.arrowBehaviour(event);
+                        this.setHighlightedOption(startOptionIndex);
                         this.menuOptionId.emit({
-                            optionId: getOptionId(menuOptions.length - 1),
+                            optionId: getOptionId(startOptionIndex),
                         });
+                        if (event.shiftKey && event.ctrlKey) {
+                            this.handleMultipleShiftSelect(startOptionIndex);
+                        }
+                        this.lastOptionFocused = startOptionIndex;
+                        this.lastOptionSelected = startOptionIndex;
+                        break;
                     }
-                    else {
-                        this.setHighlightedOption(highlightedOptionIndex - 1);
+                    case "End": {
+                        const endOptionIndex = menuOptions.length - 1;
+                        this.keyboardNav = true;
+                        event.preventDefault();
+                        this.arrowBehaviour(event);
+                        this.setHighlightedOption(endOptionIndex);
                         this.menuOptionId.emit({
-                            optionId: getOptionId(highlightedOptionIndex - 1),
+                            optionId: getOptionId(endOptionIndex),
                         });
-                    }
-                    this.preventIncorrectTabOrder = false;
-                    this.focusFromSearchKeypress = false;
-                    break;
-                case "Home":
-                    this.keyboardNav = true;
-                    event.preventDefault();
-                    this.arrowBehaviour(event);
-                    this.setHighlightedOption(0);
-                    this.menuOptionId.emit({
-                        optionId: getOptionId(0),
-                    });
-                    break;
-                case "End":
-                    this.keyboardNav = true;
-                    event.preventDefault();
-                    this.arrowBehaviour(event);
-                    this.setHighlightedOption(menuOptions.length - 1);
-                    this.menuOptionId.emit({
-                        optionId: getOptionId(menuOptions.length - 1),
-                    });
-                    break;
-                case " ":
-                    this.keyboardNav = false;
-                    if (this.isSearchBar || this.isSearchableSelect) {
+                        if (event.shiftKey && event.ctrlKey) {
+                            this.handleMultipleShiftSelect(endOptionIndex);
+                        }
+                        this.lastOptionFocused = endOptionIndex;
+                        this.lastOptionSelected = endOptionIndex;
                         break;
                     }
-                    else {
-                        if (event.target.id !== "clear-button") {
-                            this.handleMenuChange(true);
+                    case " ":
+                        if (!isKeyboardCombination) {
+                            this.keyboardNav = false;
                         }
-                    }
-                    break;
-                case "Enter":
-                    event.preventDefault();
-                    this.keyboardNav = false;
-                    if (isOpen) {
-                        if (highlightedOptionIndex >= 0) {
-                            if (menuOptions[highlightedOptionIndex] !== undefined) {
-                                if (this.isSearchBar &&
-                                    menuOptions[highlightedOptionIndex].disabled === true) {
-                                    this.disabledOptionSelected = true;
-                                }
-                                else {
-                                    this.setInputValue(highlightedOptionIndex);
-                                    this.value =
-                                        menuOptions[highlightedOptionIndex][this.valueField];
-                                }
+                        if (this.isSearchBar || this.isSearchableSelect) {
+                            break;
+                        }
+                        else {
+                            if (event.target.id !== this.CLEAR_BUTTON_ID) {
+                                this.handleMenuChange(true);
+                            }
+                        }
+                        break;
+                    case "Enter":
+                        event.preventDefault();
+                        if (!isKeyboardCombination) {
+                            this.keyboardNav = false;
+                        }
+                        this.handleOptionSelect(event, highlightedOptionIndex);
+                        break;
+                    case "Escape":
+                        if (this.open) {
+                            event.stopImmediatePropagation();
+                        }
+                        this.handleMenuChange(false);
+                        this.menuOptionId.emit({ optionId: undefined });
+                        break;
+                    case "a":
+                        // Checks if Cmd (meta) key is pressed if Mac device (while excluding meta key on Windows)
+                        // Otherwise, if a different OS, checks Ctrl key
+                        if ((isMacDevice() && event.metaKey) ||
+                            (!isMacDevice() && event.ctrlKey)) {
+                            this.emitSelectAllEvents();
+                            this.lastOptionFocused = null;
+                            this.lastOptionSelected = null;
+                        }
+                        break;
+                    case "Shift":
+                    case "Tab":
+                        if (event.key === "Shift") {
+                            this.shiftPressed = true;
+                        }
+                        if (this.isSearchBar) {
+                            this.keyboardNav = true;
+                        }
+                        if (this.isMultiSelect) {
+                            if (this.open && !event.shiftKey && this.selectAllButton) {
+                                event.preventDefault();
+                                this.selectAllButton.focus(); // Move focus to select all button instead of focused option
+                                this.preventMenuFocus = true;
+                                this.preventClickOpen = true;
+                                this.optionHighlighted = undefined; // Stop any option focus states showing when focus moved to select all button
                             }
                         }
                         else {
-                            this.setInputValue(highlightedOptionIndex);
+                            this.preventIncorrectTabOrder = true;
                         }
-                    }
-                    else {
-                        this.handleMenuChange(true);
-                    }
-                    break;
-                case "Escape":
-                    if (this.open) {
-                        event.stopImmediatePropagation();
-                    }
-                    this.handleMenuChange(false);
-                    this.menuOptionId.emit({ optionId: undefined });
-                    break;
-                case "Shift":
-                case "Tab":
-                    if (this.isSearchBar) {
-                        this.keyboardNav = true;
-                    }
-                    this.preventIncorrectTabOrder = true;
-                    break;
-                default:
-                    this.keyboardNav = false;
-                    this.focusOnSearchOrSelectInput(menuOptions, highlightedOptionIndex);
-                    break;
+                        break;
+                    default:
+                        if (!isKeyboardCombination) {
+                            this.keyboardNav = false;
+                        }
+                        this.focusOnSearchOrSelectInput(menuOptions, highlightedOptionIndex);
+                }
             }
         };
         this.setInputValue = (highlightedOptionIndex) => {
-            const menuOptions = this.setMenuOptions();
+            const menuOptions = this.getMenuOptions();
             if (menuOptions[highlightedOptionIndex] !== undefined) {
                 this.menuOptionSelect.emit({
                     value: menuOptions[highlightedOptionIndex][this.valueField],
                 });
-                this.optionHighlighted = undefined;
-                this.menuOptionId.emit({ optionId: undefined });
+                if (this.closeOnSelect) {
+                    this.optionHighlighted = undefined;
+                    this.menuOptionId.emit({ optionId: undefined });
+                }
+            }
+            if (this.closeOnSelect) {
+                if (!this.hasTimedOut) {
+                    this.handleMenuChange(false);
+                }
+                else {
+                    this.parentEl.setFocus();
+                }
             }
-            if (!this.hasTimedOut)
-                this.handleMenuChange(false);
-            else
-                this.parentEl.setFocus();
         };
         this.handleOptionClick = (event) => {
             const { value, label } = event.target.dataset;
-            this.menuOptionSelect.emit({ value, label });
-            this.handleMenuChange(false);
+            if (this.isMultiSelect) {
+                const menuOptions = this.getMenuOptions();
+                const selectedOptionIndex = menuOptions.findIndex((option) => option.value === value);
+                this.handleOptionSelect(event, selectedOptionIndex, true);
+                this.multiOptionClicked = value;
+            }
+            else {
+                this.menuOptionSelect.emit({ value, label });
+                this.handleMenuChange(false);
+            }
+            this.optionHighlighted = undefined;
         };
         this.handleRetry = () => {
             this.retryButtonClicked.emit({ value: this.value });
@@ -247,13 +403,23 @@ export class Menu {
         };
         this.handleBlur = (event) => {
             if (event.relatedTarget !== this.inputEl) {
-                if (!this.menu.contains(event.relatedTarget)) {
+                if (event.relatedTarget === this.selectAllButton) {
+                    this.menu.removeAttribute(this.ACTIVE_DESCENDANT);
+                }
+                if (!(this.menu.contains(event.relatedTarget) ||
+                    event.relatedTarget === this.selectAllButton)) {
                     this.handleMenuChange(false, this.hasPreviouslyBlurred);
+                    this.menu.removeAttribute(this.ACTIVE_DESCENDANT);
+                    this.lastOptionFocused = null;
+                    this.lastOptionSelected = null;
                 }
             }
             else {
                 this.handleMenuChange(false);
                 this.preventClickOpen = true;
+                this.menu.removeAttribute(this.ACTIVE_DESCENDANT);
+                this.lastOptionFocused = null;
+                this.lastOptionSelected = null;
             }
             if (!this.isSearchBar)
                 this.hasPreviouslyBlurred = !!event.relatedTarget;
@@ -266,12 +432,113 @@ export class Menu {
                 this.autoSetValueOnMenuKeyDown(event);
             }
             else if (this.activationType === "manual" && !this.isSearchBar) {
-                this.manSetInputValueKeyboardOpen(event);
+                this.manualSetInputValueKeyboardOpen(event);
+            }
+        };
+        this.handleMenuKeyUp = (event) => {
+            if (event.key === "Tab" && event.shiftKey) {
+                this.preventClickOpen = false;
+            }
+            if (event.key === "Enter" && this.disabledOptionSelected) {
+                this.disabledOptionSelected = false;
+                event.stopImmediatePropagation();
+            }
+            if (event.key === "Shift") {
+                this.shiftPressed = false;
+            }
+        };
+        this.handleSelectAllClick = () => {
+            this.keyboardNav = false;
+            this.menu.focus();
+            this.emitSelectAllEvents();
+            this.lastOptionFocused = null;
+            this.lastOptionSelected = null;
+        };
+        this.handleSelectAllBlur = (event) => {
+            this.host.classList.remove("ic-select-select-all-focused");
+            if (!this.menu.contains(event.relatedTarget)) {
+                this.handleMenuChange(false, false);
+            }
+        };
+        this.handleSelectAllFocus = () => {
+            this.host.classList.add("ic-select-select-all-focused");
+            this.lastOptionFocused = null;
+            this.lastOptionSelected = null;
+        };
+        // Fix for Safari - select all button click was causing menu to close
+        this.handleSelectAllMouseDown = (event) => {
+            event.preventDefault();
+        };
+        // When shift key is being used to select contiguous options one by one on a multi-select
+        // I.e. holding shift and pressing up and down arrow keys
+        this.handleSingleShiftSelect = (event, optionToSelectIndex, options) => {
+            if (this.isMultiSelect &&
+                event.shiftKey &&
+                !this.isOptionSelected(optionToSelectIndex)) {
+                this.selectHighlightedOption(options, optionToSelectIndex);
+                this.lastOptionSelected = optionToSelectIndex;
+            }
+        };
+        // When shift key is being used to select multiple options at once on a multi-select
+        // I.e. holding shift when selecting another option
+        this.handleMultipleShiftSelect = (lastOptionInSelection, useFocusForSelection = false, firstOptionSelected = null) => {
+            this.shiftPressed = false;
+            const firstOptionInSelection = firstOptionSelected === null
+                ? this.getFirstOptionInSelection(useFocusForSelection)
+                : firstOptionSelected;
+            if (firstOptionInSelection !== null) {
+                const optionsToSelect = [];
+                if (firstOptionInSelection < lastOptionInSelection) {
+                    for (let i = firstOptionInSelection; i < lastOptionInSelection + 1; i++) {
+                        optionsToSelect.push(i);
+                    }
+                }
+                else {
+                    for (let i = firstOptionInSelection; i > lastOptionInSelection - 1; i--) {
+                        optionsToSelect.push(i);
+                    }
+                }
+                optionsToSelect.forEach((optionIndex) => !this.isOptionSelected(optionIndex) && this.setInputValue(optionIndex));
+                this.deselectSelectedOptions(optionsToSelect);
+            }
+        };
+        this.handleOptionSelect = (event, optionIndex, useFocusForSelection = false) => {
+            const menuOptions = this.getMenuOptions();
+            const firstOptionInSelection = this.getFirstOptionInSelection(useFocusForSelection);
+            if (event.shiftKey && firstOptionInSelection !== null) {
+                this.handleMultipleShiftSelect(optionIndex, useFocusForSelection, firstOptionInSelection);
+            }
+            else {
+                this.selectHighlightedOption(menuOptions, optionIndex);
+            }
+            this.lastOptionFocused = optionIndex;
+            this.lastOptionSelected = optionIndex;
+        };
+        this.getFirstOptionInSelection = (useFocusForSelection) => {
+            return useFocusForSelection && this.lastOptionFocused !== null
+                ? this.lastOptionFocused
+                : this.lastOptionSelected !== null
+                    ? this.lastOptionSelected
+                    : null;
+        };
+        this.emitSelectAllEvents = () => {
+            var _a, _b;
+            // Select all if there is either no value or not all options are selected
+            // 'true' means select all, 'false' means clear all
+            this.menuOptionSelectAll.emit({
+                select: !this.value || !(((_a = this.value) === null || _a === void 0 ? void 0 : _a.length) === this.ungroupedOptions.length),
+            });
+            // Emit clear event if all options are selected
+            if (((_b = this.value) === null || _b === void 0 ? void 0 : _b.length) === this.ungroupedOptions.length) {
+                this.icClear.emit();
             }
         };
         this.emitMenuKeyPress = (isNavKey, key) => {
             this.menuKeyPress.emit({ isNavKey: isNavKey, key: key });
         };
+        // Determines keyboard behaviour when selection is automatic
+        // (i.e. you don't have to press Enter select an option - just focus on it)
+        // and menu is focused
         this.autoSetValueOnMenuKeyDown = (event) => {
             event.cancelBubble = true;
             const selectedOptionIndex = this.ungroupedOptions.findIndex((option) => option[this.valueField] === this.value);
@@ -331,15 +598,6 @@ export class Menu {
             }
             this.emitMenuKeyPress(this.keyboardNav, event.key);
         };
-        this.handleMenuKeyUp = (event) => {
-            if (event.key === "Tab" && event.shiftKey) {
-                this.preventClickOpen = false;
-            }
-            if (event.key === "Enter" && this.disabledOptionSelected) {
-                this.disabledOptionSelected = false;
-                event.stopImmediatePropagation();
-            }
-        };
         this.getOptionId = (value) => {
             return `${this.menuId}-${value}`;
         };
@@ -365,6 +623,10 @@ export class Menu {
             }
             return sorted;
         };
+        this.getOptionHighlightedIndex = () => {
+            const menuOptions = this.getMenuOptions();
+            return menuOptions.findIndex((option) => option[this.valueField] === this.optionHighlighted);
+        };
         this.isManualMode = this.activationType === "manual";
         this.scrollToSelected = (menu) => {
             const selectedOption = this.selectOnEnter
@@ -376,9 +638,14 @@ export class Menu {
                     elTop < menu.scrollTop + menu.offsetHeight) {
                     menu.scrollTop = selectedOption.offsetTop;
                 }
+                // 'aria-activedescendant' affects screen reader focus
+                // https://www.w3.org/TR/2017/WD-wai-aria-practices-1.1-20170628/#kbd_focus_activedescendant
+                this.menu.setAttribute(this.ACTIVE_DESCENDANT, selectedOption.id);
                 selectedOption.focus();
             }
         };
+        // Set 'ungroupedOptions' variable and emit its value
+        // - this is all the options with disabled options and group titles removed
         this.loadUngroupedOptions = () => {
             if (this.options.length > 0 && this.options.map) {
                 this.options.map((option) => {
@@ -405,21 +672,24 @@ export class Menu {
         this.handleTimeoutBlur = (ev) => {
             this.timeoutBlur.emit({ ev });
         };
-        this.optionContent = (option) => {
-            var _a;
-            return (h(Fragment, null, option.loading && h("ic-loading-indicator", { size: "icon" }), h("div", { class: "option-text-container" }, h("div", { class: "option-label" }, option.icon && (h("div", { class: "option-icon", innerHTML: option.icon, "aria-hidden": "true" })), h("ic-typography", { variant: "body", "aria-hidden": "true" }, option[this.labelField])), option.description && (h("ic-typography", { id: `${this.getOptionId(option[this.valueField])}-description`, class: "option-description", variant: "caption", "aria-hidden": "true" }, h("p", null, option.description))), option.element && (h("div", { class: "option-element", innerHTML: option.element.component, "aria-hidden": "true" }))), !!option[this.valueField] &&
+        this.optionContent = (option, selected) => {
+            const showCheckIcon = !!option[this.valueField] &&
                 !!this.value &&
-                option[this.valueField].toLowerCase() === ((_a = this.value) === null || _a === void 0 ? void 0 : _a.toLowerCase()) &&
-                this.parentEl.tagName !== "IC-SEARCH-BAR" && (h("span", { class: "check-icon", innerHTML: Check }))));
+                selected &&
+                this.parentEl.tagName !== this.SEARCH_BAR_TAG;
+            return (h(Fragment, null, option.loading && h("ic-loading-indicator", { size: "icon" }), h("div", { class: {
+                    "option-text-container": true,
+                    "show-check-icon": showCheckIcon,
+                } }, h("div", { class: "option-label" }, option.icon && (h("div", { class: "option-icon", innerHTML: option.icon, "aria-hidden": "true" })), h("ic-typography", { variant: "body", "aria-hidden": "true" }, option[this.labelField])), option.description && (h("ic-typography", { id: `${this.getOptionId(option[this.valueField])}-description`, class: "option-description", variant: "caption", "aria-hidden": "true" }, h("p", null, option.description))), option.element && (h("div", { class: "option-element", innerHTML: option.element.component, "aria-hidden": "true" }))), showCheckIcon && h("span", { class: "check-icon", innerHTML: Check })));
         };
-        this.displayOption = (option, index, parentOption) => {
-            const { open, value, keyboardNav, isManualMode, initialOptionsListRender, optionHighlighted, options, } = this;
+        this.displayOption = (option, selected, index, parentOption) => {
+            const { open, keyboardNav, isManualMode, initialOptionsListRender, optionHighlighted, options, } = this;
             return (h("li", { id: this.getOptionId(option[this.valueField]), class: {
                     option: true,
                     "focused-option": isManualMode
                         ? (keyboardNav || initialOptionsListRender) &&
                             option[this.valueField] === optionHighlighted
-                        : keyboardNav && option[this.valueField] === value,
+                        : keyboardNav && selected,
                     "last-recommended-option": option.recommended &&
                         options[index + 1] &&
                         !options[index + 1].recommended,
@@ -427,20 +697,21 @@ export class Menu {
                     "loading-option": option.loading,
                     timeout: option.timedOut,
                 }, role: "option", tabindex: open &&
-                    (option[this.valueField] === value ||
-                        option[this.valueField] === optionHighlighted) &&
+                    (selected || option[this.valueField] === optionHighlighted) &&
                     keyboardNav
                     ? "0"
-                    : "-1", "aria-label": this.getOptionAriaLabel(option, parentOption), "aria-selected": `${option[this.valueField] === value}`, "aria-disabled": option.disabled ? "true" : "false", onClick: !option.timedOut && !option.loading && this.handleOptionClick, onBlur: this.handleBlur, onMouseDown: this.handleMouseDown, "data-value": option[this.valueField], "data-label": option[this.labelField] }, option.timedOut ? (h(Fragment, null, h("div", { class: "loading-error-info" }, h("svg", { class: "error-icon-svg", "aria-labelledby": "error-title", xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", fill: "#000000" }, h("title", { id: "error-title" }, "Error"), h("g", { id: "close-octagon" }, h("path", { id: "Vector", d: "M8.77 3L3.5 8.27V15.73L8.77 21H16.23L21.5 15.73V8.27L16.23 3M8.91 7L12.5 10.59L16.09 7L17.5 8.41L13.91 12L17.5 15.59L16.09 17L12.5 13.41L8.91 17L7.5 15.59L11.09 12L7.5 8.41" }))), h("ic-typography", { variant: "label" }, option[this.labelField])), h("ic-button", { size: "small", variant: "tertiary", onClick: this.handleRetry, onKeyDown: this.handleRetryKeyDown, onBlur: this.handleTimeoutBlur, id: "retry-button" }, "Retry"))) : (this.optionContent(option))));
+                    : "-1", "aria-label": this.getOptionAriaLabel(option, parentOption), "aria-selected": selected ? "true" : "false", "aria-disabled": option.disabled ? "true" : "false", onClick: !option.timedOut && !option.loading && this.handleOptionClick, onBlur: this.handleBlur, onMouseDown: this.handleMouseDown, "data-value": option[this.valueField], "data-label": option[this.labelField] }, option.timedOut ? (h(Fragment, null, h("div", { class: "loading-error-info" }, h("svg", { class: "error-icon-svg", "aria-labelledby": "error-title", xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 24 24", fill: "#000000" }, h("title", { id: "error-title" }, "Error"), h("g", { id: "close-octagon" }, h("path", { id: "Vector", d: "M8.77 3L3.5 8.27V15.73L8.77 21H16.23L21.5 15.73V8.27L16.23 3M8.91 7L12.5 10.59L16.09 7L17.5 8.41L13.91 12L17.5 15.59L16.09 17L12.5 13.41L8.91 17L7.5 15.59L11.09 12L7.5 8.41" }))), h("ic-typography", { variant: "label" }, option[this.labelField])), h("ic-button", { size: "small", variant: "tertiary", onClick: this.handleRetry, onKeyDown: this.handleRetryKeyDown, onBlur: this.handleTimeoutBlur, id: "retry-button" }, "Retry"))) : (this.optionContent(option, selected))));
         };
         this.focusFromSearchKeypress = false;
         this.initialOptionsListRender = false;
         this.keyboardNav = false;
         this.optionHighlighted = undefined;
         this.preventIncorrectTabOrder = false;
+        this.menuOptions = undefined;
         this.activationType = "automatic";
         this.anchorEl = undefined;
-        this.autoFocusOnSelected = true;
+        this.autofocusOnSelected = true;
+        this.closeOnSelect = true;
         this.fullWidth = false;
         this.inputEl = undefined;
         this.inputLabel = undefined;
@@ -450,8 +721,7 @@ export class Menu {
         this.parentEl = undefined;
         this.searchMode = "navigation";
         this.selectOnEnter = false;
-        this.size = "default";
-        this.small = false;
+        this.size = "medium";
         this.options = undefined;
         this.value = undefined;
         this.valueField = "value";
@@ -468,9 +738,6 @@ export class Menu {
         this.ungroupedOptions = [];
         this.loadUngroupedOptions();
     }
-    watchValueHandler() {
-        this.menuValueChange.emit({ value: this.value });
-    }
     connectedCallback() {
         this.getParentEl(this.parentEl);
         if (this.isSearchBar) {
@@ -497,7 +764,7 @@ export class Menu {
     }
     componentDidLoad() {
         if (this.isSearchBar &&
-            this.parentEl.disableFilter) {
+            this.parentEl.disableAutoFiltering) {
             this.focusFromSearchKeypress = true;
         }
         onComponentRequiredPropUndefined([
@@ -510,16 +777,15 @@ export class Menu {
     }
     componentDidUpdate() {
         const inputValueInOptions = this.options.some((option) => option[this.valueField] === this.value);
-        if (this.open && this.options.length !== 0) {
+        if (this.open && this.options.length !== 0 && !this.preventMenuFocus) {
             if (this.value &&
                 this.keyboardNav &&
                 inputValueInOptions &&
-                this.autoFocusOnSelected &&
+                this.autofocusOnSelected &&
                 !this.isSearchableSelect) {
                 this.scrollToSelected(this.menu);
             }
-            else if (this.inputEl.tagName !== "IC-TEXT-FIELD" &&
-                this.inputEl.tagName !== "INPUT") {
+            else if (this.selectOnEnter) {
                 this.menu.focus();
             }
             else if (!!this.optionHighlighted &&
@@ -527,13 +793,18 @@ export class Menu {
                 !this.preventIncorrectTabOrder) {
                 const highlightedEl = this.host.querySelector(`li[data-value="${this.optionHighlighted}"]`);
                 if (highlightedEl) {
+                    this.menu.setAttribute(this.ACTIVE_DESCENDANT, highlightedEl.id);
                     highlightedEl.focus();
                 }
             }
+            else if (this.inputEl.tagName !== "INPUT") {
+                this.menu.focus();
+            }
         }
         if (this.open && !this.value && this.selectOnEnter) {
             this.scrollToSelected(this.menu);
         }
+        this.preventMenuFocus = false;
     }
     componentDidRender() {
         if (this.open && !this.popperInstance && this.anchorEl) {
@@ -563,7 +834,7 @@ export class Menu {
             this.autoSetInputValueKeyboardOpen(event);
         }
         else {
-            this.manSetInputValueKeyboardOpen(event);
+            this.manualSetInputValueKeyboardOpen(event);
         }
     }
     /**
@@ -578,8 +849,9 @@ export class Menu {
      * boundary behaviour so sticking with PopperJS.
      */
     async initPopperJs(anchor) {
+        // Placements set to "-start" to accommodate for custom menu width - menu should always be aligned to the left
         this.popperInstance = createPopper(anchor, this.host, {
-            placement: "bottom",
+            placement: "bottom-start",
             modifiers: [
                 {
                     name: "offset",
@@ -590,7 +862,7 @@ export class Menu {
                 {
                     name: "flip",
                     options: {
-                        fallbackPlacements: ["top"],
+                        fallbackPlacements: ["top-start"],
                         rootBoundary: "viewport",
                     },
                 },
@@ -611,26 +883,47 @@ export class Menu {
         this.focusFromSearchKeypress = true;
     }
     render() {
-        const { inputLabel, options, menuId, value, fullWidth, hasTimedOut, isLoading, size, small, open, inputEl, keyboardNav, } = this;
+        const { inputLabel, options, menuId, value, fullWidth, hasTimedOut, isLoading, size, open, inputEl, keyboardNav, parentEl, SEARCH_BAR_TAG, } = this;
+        const selectAllButtonText = `${(value === null || value === void 0 ? void 0 : value.length) === this.ungroupedOptions.length ? "Clear" : "Select"} all`;
+        const hasNoResults = this.host.classList.contains("no-results");
         return (h(Host, { class: {
-                "full-width": fullWidth,
-                "no-focus": (inputEl === null || inputEl === void 0 ? void 0 : inputEl.tagName) === "INPUT" || hasTimedOut || isLoading,
-                small: small,
-                [size]: true,
-                open: open,
-            } }, options.length !== 0 && (h("ul", { id: menuId, class: "menu", role: "listbox", "aria-label": inputLabel, "aria-activedescendant": value != null && value !== "" ? this.getOptionId(value) : "", tabindex: open && !keyboardNav && (inputEl === null || inputEl === void 0 ? void 0 : inputEl.tagName) !== "INPUT" ? "0" : "-1", ref: (el) => (this.menu = el), onKeyDown: this.handleMenuKeyDown, onKeyUp: this.handleMenuKeyUp, onBlur: this.handleBlur }, this.getSortedOptions(options).map((option, index) => {
+                "ic-menu-full-width": fullWidth,
+                "ic-menu-no-focus": ((inputEl === null || inputEl === void 0 ? void 0 : inputEl.tagName) === "INPUT" &&
+                    (parentEl === null || parentEl === void 0 ? void 0 : parentEl.tagName) !== SEARCH_BAR_TAG) ||
+                    hasTimedOut ||
+                    isLoading,
+                [`ic-menu-${size}`]: true,
+                "ic-menu-open": open && options.length !== 0,
+                "ic-menu-multiple": this.isMultiSelect,
+            } }, options.length !== 0 && (h("ul", { id: menuId, class: "menu", role: "listbox", "aria-label": `${inputLabel} pop-up`, "aria-multiselectable": this.isMultiSelect ? "true" : "false", tabindex: open &&
+                !keyboardNav &&
+                ((inputEl === null || inputEl === void 0 ? void 0 : inputEl.tagName) !== "INPUT" ||
+                    (parentEl === null || parentEl === void 0 ? void 0 : parentEl.tagName) === SEARCH_BAR_TAG)
+                ? "0"
+                : "-1", ref: (el) => (this.menu = el), onKeyDown: this.handleMenuKeyDown, onKeyUp: this.handleMenuKeyUp, onBlur: this.handleBlur }, this.getSortedOptions(options).map((option, index) => {
             if (option.children) {
                 if (option.children.length > 0) {
-                    return (h("div", null, h("ic-typography", { class: "option-group-title", role: "presentation", variant: "subtitle-small" }, h("p", null, option[this.labelField])), option.children.map((childOption) => this.displayOption(childOption, index, option))));
+                    return (h("div", null, h("ic-typography", { class: "option-group-title", role: "presentation", variant: "subtitle-small" }, h("p", null, option[this.labelField])), option.children.map((childOption) => childOption.label &&
+                        this.displayOption(childOption, this.isMultiSelect
+                            ? value === null || value === void 0 ? void 0 : value.includes(childOption[this.valueField])
+                            : childOption[this.valueField] === value, index, option))));
                 }
                 else {
                     return null;
                 }
             }
             else {
-                return this.displayOption(option, index);
+                // Display option only if it has a label (rather than displaying an empty space)
+                return (option.label &&
+                    this.displayOption(option, this.isMultiSelect
+                        ? value === null || value === void 0 ? void 0 : value.includes(option[this.valueField])
+                        : option[this.valueField] === value, index));
             }
-        })))));
+        }))), options.length !== 0 &&
+            this.isMultiSelect &&
+            !isLoading &&
+            !hasTimedOut &&
+            !hasNoResults && (h("div", { class: "option-bar" }, h("ic-typography", null, h("p", null, `${value ? value.length : 0}/${getOptionsWithoutGroupTitlesCount(this.options)} selected`)), h("ic-button", { class: "select-all-button", "aria-label": `${selectAllButtonText} options for ${inputLabel}`, ref: (el) => (this.selectAllButton = el), variant: "tertiary", onClick: this.handleSelectAllClick, onMouseDown: this.handleSelectAllMouseDown, onBlur: this.handleSelectAllBlur, onFocus: this.handleSelectAllFocus, size: size === "small" ? "small" : "medium" }, selectAllButtonText)))));
     }
     static get is() { return "ic-menu"; }
     static get encapsulation() { return "scoped"; }
@@ -690,7 +983,7 @@ export class Menu {
                     "text": "The reference to an anchor element the menu will position itself from when rendered."
                 }
             },
-            "autoFocusOnSelected": {
+            "autofocusOnSelected": {
                 "type": "boolean",
                 "mutable": false,
                 "complexType": {
@@ -707,7 +1000,25 @@ export class Menu {
                         }],
                     "text": ""
                 },
-                "attribute": "auto-focus-on-selected",
+                "attribute": "autofocus-on-selected",
+                "reflect": false,
+                "defaultValue": "true"
+            },
+            "closeOnSelect": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "If `true`, the menu will close when an option is selected."
+                },
+                "attribute": "close-on-select",
                 "reflect": false,
                 "defaultValue": "true"
             },
@@ -891,7 +1202,7 @@ export class Menu {
                 "mutable": false,
                 "complexType": {
                     "original": "IcSizes",
-                    "resolved": "\"default\" | \"large\" | \"small\"",
+                    "resolved": "\"large\" | \"medium\" | \"small\"",
                     "references": {
                         "IcSizes": {
                             "location": "import",
@@ -904,32 +1215,11 @@ export class Menu {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "The size of the menu component."
+                    "text": "The size of the menu."
                 },
                 "attribute": "size",
                 "reflect": false,
-                "defaultValue": "\"default\""
-            },
-            "small": {
-                "type": "boolean",
-                "mutable": false,
-                "complexType": {
-                    "original": "boolean",
-                    "resolved": "boolean",
-                    "references": {}
-                },
-                "required": false,
-                "optional": true,
-                "docs": {
-                    "tags": [{
-                            "name": "deprecated",
-                            "text": "This prop should not be used anymore. Set prop `size` to \"small\" instead."
-                        }],
-                    "text": ""
-                },
-                "attribute": "small",
-                "reflect": false,
-                "defaultValue": "false"
+                "defaultValue": "\"medium\""
             },
             "options": {
                 "type": "unknown",
@@ -954,17 +1244,17 @@ export class Menu {
             },
             "value": {
                 "type": "string",
-                "mutable": true,
+                "mutable": false,
                 "complexType": {
-                    "original": "string",
-                    "resolved": "string",
+                    "original": "string | string[]",
+                    "resolved": "string | string[]",
                     "references": {}
                 },
                 "required": true,
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "The value of the currently selected option."
+                    "text": "The value of the currently selected option - or array of values (if multiple options allowed)."
                 },
                 "attribute": "value",
                 "reflect": false
@@ -995,11 +1285,27 @@ export class Menu {
             "initialOptionsListRender": {},
             "keyboardNav": {},
             "optionHighlighted": {},
-            "preventIncorrectTabOrder": {}
+            "preventIncorrectTabOrder": {},
+            "menuOptions": {}
         };
     }
     static get events() {
         return [{
+                "method": "icClear",
+                "name": "icClear",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitted when the clear all button is clicked."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
                 "method": "menuKeyPress",
                 "name": "menuKeyPress",
                 "bubbles": true,
@@ -1008,7 +1314,7 @@ export class Menu {
                 "docs": {
                     "tags": [{
                             "name": "internal",
-                            "text": "Emitted when key is pressed while menu is open"
+                            "text": "Emitted when key is pressed while menu is open."
                         }],
                     "text": ""
                 },
@@ -1026,7 +1332,7 @@ export class Menu {
                 "docs": {
                     "tags": [{
                             "name": "internal",
-                            "text": "Emitted when an option has been highlighted"
+                            "text": "Emitted when an option has been highlighted."
                         }],
                     "text": ""
                 },
@@ -1066,50 +1372,44 @@ export class Menu {
                     }
                 }
             }, {
-                "method": "menuStateChange",
-                "name": "menuStateChange",
+                "method": "menuOptionSelectAll",
+                "name": "menuOptionSelectAll",
                 "bubbles": true,
                 "cancelable": true,
                 "composed": true,
                 "docs": {
                     "tags": [{
                             "name": "internal",
-                            "text": "Emitted when state of menu changes (i.e. open or close)."
+                            "text": "Emitted when all options are selected or deselected."
                         }],
                     "text": ""
                 },
                 "complexType": {
-                    "original": "IcMenuChangeEventDetail",
-                    "resolved": "IcMenuChangeEventDetail",
-                    "references": {
-                        "IcMenuChangeEventDetail": {
-                            "location": "import",
-                            "path": "./ic-menu.types",
-                            "id": "src/components/ic-menu/ic-menu.types.ts::IcMenuChangeEventDetail"
-                        }
-                    }
+                    "original": "{ select: boolean }",
+                    "resolved": "{ select: boolean; }",
+                    "references": {}
                 }
             }, {
-                "method": "menuValueChange",
-                "name": "menuValueChange",
+                "method": "menuStateChange",
+                "name": "menuStateChange",
                 "bubbles": true,
                 "cancelable": true,
                 "composed": true,
                 "docs": {
                     "tags": [{
                             "name": "internal",
-                            "text": "Emitted when menu value changes."
+                            "text": "Emitted when state of menu changes (i.e. open or closed)."
                         }],
                     "text": ""
                 },
                 "complexType": {
-                    "original": "IcValueEventDetail",
-                    "resolved": "IcValueEventDetail",
+                    "original": "IcMenuChangeEventDetail",
+                    "resolved": "IcMenuChangeEventDetail",
                     "references": {
-                        "IcValueEventDetail": {
+                        "IcMenuChangeEventDetail": {
                             "location": "import",
-                            "path": "../../utils/types",
-                            "id": "src/utils/types.ts::IcValueEventDetail"
+                            "path": "./ic-menu.types",
+                            "id": "src/components/ic-menu/ic-menu.types.ts::IcMenuChangeEventDetail"
                         }
                     }
                 }
@@ -1122,7 +1422,7 @@ export class Menu {
                 "docs": {
                     "tags": [{
                             "name": "internal",
-                            "text": "Emitted when the retry button is clicked"
+                            "text": "Emitted when the retry button is clicked."
                         }],
                     "text": ""
                 },
@@ -1146,7 +1446,7 @@ export class Menu {
                 "docs": {
                     "tags": [{
                             "name": "internal",
-                            "text": "Emitted when the timeout menu loses focus"
+                            "text": "Emitted when the timeout menu loses focus."
                         }],
                     "text": ""
                 },
@@ -1294,9 +1594,6 @@ export class Menu {
             }, {
                 "propName": "options",
                 "methodName": "watchOptionsHandler"
-            }, {
-                "propName": "value",
-                "methodName": "watchValueHandler"
             }];
     }
 }