@mongodb-js/compass-components 1.29.3 → 1.30.0

package/lib/components/combobox/Combobox.js

@@ -27,6 +27,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Combobox = void 0;
+/* eslint-disable filename-rules/match */
 const react_1 = __importStar(require("react"));
 const clone_1 = __importDefault(require("lodash/clone"));
 const isArray_1 = __importDefault(require("lodash/isArray"));
@@ -53,6 +54,8 @@ const ComboboxOption_1 = require("./ComboboxOption");
 const utils_1 = require("./utils");
 const tokens_1 = require("@leafygreen-ui/tokens");
 const descriptionWidth = tokens_1.spacing[5] * 14;
+// By default we want the menu option to be the same width as the input
+// If the user has specified a description, we add extra space to fit the description.
 const popoverMenuStyles = (width, numDescChars) => {
     if (numDescChars === 0) {
         return (0, emotion_1.css) `
@@ -70,6 +73,11 @@ const popoverMenuStyles = (width, numDescChars) => {
     );
   `;
 };
+/**
+ * Combobox is a combination of a Select and TextInput,
+ * allowing the user to either type a value directly or select a value from the list.
+ * Can be configured to select a single or multiple options.
+ */
 function Combobox({ children, label, description, placeholder = 'Select', 'aria-label': ariaLabel, disabled = false, size = Combobox_types_1.ComboboxSize.Default, darkMode: darkModeProp, state = 'none', errorMessage, searchState = 'unset', searchEmptyMessage = 'No results found', searchErrorMessage = 'Could not get results!', searchLoadingMessage = 'Loading results...', filteredOptions, onFilter, clearable = true, onClear, overflow = 'expand-y', multiselect = false, initialValue, onChange, value, chipTruncationLocation, chipCharacterLimit = 12, className, usePortal = true, portalClassName, portalContainer, scrollContainer, popoverZIndex, popoverClassName, ...rest }) {
     const { darkMode, theme } = (0, leafygreen_provider_1.useDarkMode)(darkModeProp);
     const getOptionRef = (0, hooks_1.useDynamicRefs)({ prefix: 'option' });
@@ -97,7 +105,13 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
         : placeholder;
     const closeMenu = () => setOpen(false);
     const openMenu = () => setOpen(true);
+    /**
+     * Array of all of the options objects
+     */
     const allOptions = (0, react_1.useMemo)(() => (0, utils_1.flattenChildren)(children), [children]);
+    /**
+     * Utility function that tells Typescript whether selection is multiselect
+     */
     const isMultiselect = (0, react_1.useCallback)((val) => {
         if (multiselect && (typeof val === 'string' || typeof val === 'number')) {
             lib_1.consoleOnce.error(`Error in Combobox: multiselect is set to \`true\`, but received a ${typeof val} value: "${val}"`);
@@ -107,6 +121,10 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
         }
         return multiselect && (0, isArray_1.default)(val);
     }, [multiselect]);
+    /**
+     * Forces focus of input box
+     * @param cursorPos index the cursor should be set to
+     */
     const setInputFocus = (0, react_1.useCallback)((cursorPos) => {
         if (!disabled && inputRef && inputRef.current) {
             inputRef.current.focus();
@@ -115,18 +133,27 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             }
         }
     }, [disabled]);
+    /**
+     * Update selection.
+     * This behaves differently in multi. vs single select.
+     * @param value option value the selection should be set to
+     */
     const updateSelection = (0, react_1.useCallback)((value) => {
         if (isMultiselect(selection)) {
+            // We know M is true here
             const newSelection = (0, clone_1.default)(selection);
             if ((0, isNull_1.default)(value)) {
                 newSelection.length = 0;
             }
             else {
                 if (selection.includes(value)) {
+                    // remove from array
                     newSelection.splice(newSelection.indexOf(value), 1);
                 }
                 else {
+                    // add to array
                     newSelection.push(value);
+                    // clear text
                     setInputValue('');
                 }
             }
@@ -139,15 +166,28 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             onChange?.(newSelection);
         }
     }, [isMultiselect, onChange, selection]);
+    /**
+     * Returns whether a given value is included in, or equal to, the current selection
+     * @param value the option value to check
+     */
     const isValueCurrentSelection = (0, react_1.useCallback)((value) => {
         return isMultiselect(selection)
             ? selection.includes(value)
             : value === selection;
     }, [isMultiselect, selection]);
+    /**
+     * Returns whether given text is included in, or equal to, the current selection.
+     * Similar to `isValueCurrentSelection`, but assumes the text argument is the `displayName` for the selection
+     * @param text the text to check
+     */
     const isTextCurrentSelection = (0, react_1.useCallback)((text) => {
         const value = (0, utils_1.getValueForDisplayName)(text, allOptions);
         return isValueCurrentSelection(value);
     }, [allOptions, isValueCurrentSelection]);
+    /**
+     * Returns whether the provided option is disabled
+     * @param option the option value or OptionObject to check
+     */
     const isOptionDisabled = (option) => {
         if (typeof option === 'string') {
             const optionObj = (0, utils_1.getOptionObjectFromValue)(option, allOptions);
@@ -157,14 +197,23 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             return !!option.isDisabled;
         }
     };
+    /**
+     * Computes whether the option is visible based on the current input
+     * @param option the option value or OptionObject to compute
+     */
     const shouldOptionBeVisible = (0, react_1.useCallback)((option) => {
         const value = typeof option === 'string' ? option : option.value;
+        // If filtered options are provided
         if (filteredOptions && filteredOptions.length > 0) {
             return filteredOptions.includes(value);
         }
+        // If the text input value is the current selection
+        // (or included in the selection)
+        // then all options should be visible
         if (isTextCurrentSelection(inputValue)) {
             return true;
         }
+        // otherwise, we do our own filtering
         const displayName = typeof option === 'string'
             ? (0, utils_1.getDisplayNameForValue)(value, allOptions)
             : option.displayName;
@@ -173,30 +222,58 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             .includes(inputValue.toLowerCase());
         return isValueInDisplayName;
     }, [filteredOptions, isTextCurrentSelection, inputValue, allOptions]);
+    /**
+     * The array of visible options objects
+     */
     const visibleOptions = (0, react_1.useMemo)(() => allOptions.filter(shouldOptionBeVisible), [allOptions, shouldOptionBeVisible]);
+    /**
+     * Returns whether the given value is in the options array
+     * @param value the value to check
+     */
     const isValueValid = (0, react_1.useCallback)((value) => {
         return value ? !!allOptions.find((opt) => opt.value === value) : false;
     }, [allOptions]);
+    /**
+     * Returns the index of a given value in the array of visible (filtered) options
+     * @param value the option value to get the index of
+     */
     const getIndexOfValue = (0, react_1.useCallback)((value) => {
         return visibleOptions
             ? visibleOptions.findIndex((option) => option.value === value)
             : -1;
     }, [visibleOptions]);
+    /**
+     * Returns the option value of a given index in the array of visible (filtered) options
+     * @param index the option index to get the value of
+     */
     const getValueAtIndex = (0, react_1.useCallback)((index) => {
         if (visibleOptions && visibleOptions.length >= index) {
             const option = visibleOptions[index];
             return option ? option.value : undefined;
         }
     }, [visibleOptions]);
+    /**
+     * Returns the index of the active chip in the selection array
+     */
     const getActiveChipIndex = (0, react_1.useCallback)(() => isMultiselect(selection)
         ? selection.findIndex((value) => getChipRef(value)?.current?.contains(document.activeElement))
         : -1, [getChipRef, isMultiselect, selection]);
+    /**
+     *
+     * Focus Management
+     *
+     */
     const [focusedElementName, trackFocusedElement] = (0, react_1.useState)();
     const isElementFocused = (elementName) => elementName === focusedElementName;
+    /**
+     * Updates the highlighted menu option based on the provided direction
+     * @param direction the direction to move the focus. `'next' | 'prev' | 'first' | 'last'`
+     */
     const updateHighlightedOption = (0, react_1.useCallback)((direction) => {
         const optionsCount = visibleOptions?.length ?? 0;
         const lastIndex = optionsCount - 1 > 0 ? optionsCount - 1 : 0;
         const indexOfHighlight = getIndexOfValue(highlightedOption);
+        // Remove focus from chip
         if (direction && isOpen) {
             setFocusedChip(null);
             setInputFocus();
@@ -235,6 +312,11 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
         setInputFocus,
         visibleOptions?.length,
     ]);
+    /**
+     * Updates the focused chip based on the provided direction
+     * @param direction the direction to move the focus. `'next' | 'prev' | 'first' | 'last'`
+     * @param relativeToIndex the chip index to move focus relative to
+     */
     const updateFocusedChip = (0, react_1.useCallback)((direction, relativeToIndex) => {
         if (isMultiselect(selection)) {
             switch (direction) {
@@ -274,13 +356,18 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             }
         }
     }, [getActiveChipIndex, isMultiselect, selection]);
+    /**
+     * Handles an arrow key press
+     */
     const handleArrowKey = (0, react_1.useCallback)((direction, event) => {
+        // Remove focus from menu
         if (direction)
             setHighlightedOption(null);
         switch (direction) {
             case 'right':
                 switch (focusedElementName) {
                     case Combobox_types_1.ComboboxElement.Input: {
+                        // If cursor is at the end of the input
                         if (inputRef.current?.selectionEnd ===
                             inputRef.current?.value.length) {
                             clearButtonRef.current?.focus();
@@ -291,12 +378,15 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
                     case Combobox_types_1.ComboboxElement.MiddleChip:
                     case Combobox_types_1.ComboboxElement.LastChip: {
                         if (focusedElementName === Combobox_types_1.ComboboxElement.LastChip ||
+                            // the first chip is also the last chip (i.e. only one)
                             selection?.length === 1) {
+                            // if focus is on last chip, go to input
                             setInputFocus(0);
                             updateFocusedChip(null);
                             event.preventDefault();
                             break;
                         }
+                        // First/middle chips
                         updateFocusedChip('next');
                         break;
                     }
@@ -316,6 +406,7 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
                     case Combobox_types_1.ComboboxElement.MiddleChip:
                     case Combobox_types_1.ComboboxElement.LastChip: {
                         if (isMultiselect(selection)) {
+                            // Break if cursor is not at the start of the input
                             if (focusedElementName === Combobox_types_1.ComboboxElement.Input &&
                                 inputRef.current?.selectionStart !== 0) {
                                 break;
@@ -340,11 +431,14 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
         setInputFocus,
         updateFocusedChip,
     ]);
+    // When the input value changes (or when the menu opens)
+    // Update the focused option
     (0, react_1.useEffect)(() => {
         if (inputValue !== prevValue) {
             updateHighlightedOption('first');
         }
     }, [inputValue, isOpen, prevValue, updateHighlightedOption]);
+    // When the focused option changes, update the menu scroll if necessary
     (0, react_1.useEffect)(() => {
         if (highlightedOption) {
             const focusedElementRef = getOptionRef(highlightedOption);
@@ -357,6 +451,12 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             }
         }
     }, [highlightedOption, getOptionRef]);
+    /**
+     * Rendering
+     */
+    /**
+     * Callback to render a child as an <InternalComboboxOption> element
+     */
     const renderOption = (0, react_1.useCallback)((child) => {
         if ((0, lib_1.isComponentType)(child, 'ComboboxOption')) {
             const { value, displayName } = (0, utils_1.getNameAndValue)(child.props);
@@ -395,7 +495,13 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
         shouldOptionBeVisible,
         updateSelection,
     ]);
+    /**
+     * The rendered JSX elements for the options
+     */
     const renderedOptionsJSX = (0, react_1.useMemo)(() => react_1.default.Children.map(children, renderOption), [children, renderOption]);
+    /**
+     * The rendered JSX for the selection Chips
+     */
     const renderedChips = (0, react_1.useMemo)(() => {
         if (isMultiselect(selection)) {
             return selection.filter(isValueValid).map((value, index) => {
@@ -405,6 +511,7 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
                 const isLastChip = index >= selection.length - 1;
                 const onRemove = () => {
                     if (isLastChip) {
+                        // Focus the input if this is the last chip in the set
                         setInputFocus();
                         updateFocusedChip(null);
                     }
@@ -433,6 +540,9 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
     const handleClearButtonFocus = () => {
         setHighlightedOption(null);
     };
+    /**
+     * The rendered JSX for the input icons (clear, warn & caret)
+     */
     const renderedInputIcons = (0, react_1.useMemo)(() => {
         const handleClearButtonClick = (e) => {
             if (!disabled) {
@@ -460,14 +570,27 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
         onFilter,
         isOpen,
     ]);
+    /**
+     * Flag to determine whether the rendered options have icons
+     */
     const withIcons = (0, react_1.useMemo)(() => allOptions.some((opt) => opt.hasGlyph), [allOptions]);
+    /**
+     *
+     * Selection Management
+     *
+     */
     const onCloseMenu = (0, react_1.useCallback)(() => {
+        // Single select, and no change to selection
         if (!isMultiselect(selection) && selection === prevSelection) {
             const exactMatchedOption = visibleOptions.find((option) => option.displayName === inputValue || option.value === inputValue);
+            // check if inputValue is matches a valid option
+            // Set the selection to that value if the component is not controlled
             if (exactMatchedOption && !value) {
                 setSelection(exactMatchedOption.value);
             }
             else if (selection) {
+                // Revert the value to the previous selection.
+                // Set the value instead of displayName to align with handleInputChange COMPASS-6511
                 setInputValue(selection);
             }
         }
@@ -483,9 +606,12 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
     const onSelect = (0, react_1.useCallback)(() => {
         if (doesSelectionExist) {
             if (isMultiselect(selection)) {
+                // Scroll the wrapper to the end. No effect if not `overflow="scroll-x"`
                 scrollInputToEnd();
             }
             else if (!isMultiselect(selection)) {
+                // Update the text input.
+                // Set the value instead of displayName to align with handleInputChange COMPASS-6511
                 setInputValue(selection);
                 closeMenu();
             }
@@ -494,9 +620,11 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             setInputValue('');
         }
     }, [doesSelectionExist, allOptions, isMultiselect, selection]);
+    // Set the initialValue
     (0, react_1.useEffect)(() => {
         if (initialValue) {
             if ((0, isArray_1.default)(initialValue)) {
+                // Ensure the values we set are real options
                 const filteredValue = initialValue.filter((value) => isValueValid(value)) ?? [];
                 setSelection(filteredValue);
             }
@@ -509,13 +637,16 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
         else {
             setSelection((0, Combobox_types_1.getNullSelection)(multiselect));
         }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
+    // When controlled value changes, update the selection
     (0, react_1.useEffect)(() => {
         if (!(0, isUndefined_1.default)(value) && value !== prevValue) {
             if ((0, isNull_1.default)(value)) {
                 setSelection(null);
             }
             else if (isMultiselect(value)) {
+                // Ensure the value(s) passed in are valid options
                 const newSelection = value.filter(isValueValid);
                 setSelection(newSelection);
             }
@@ -524,29 +655,49 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             }
         }
     }, [isMultiselect, isValueValid, prevValue, value]);
+    // onSelect
+    // Side effects to run when the selection changes
     (0, react_1.useEffect)(() => {
         if (!(0, isEqual_1.default)(selection, prevSelection)) {
             onSelect();
         }
     }, [onSelect, prevSelection, selection]);
+    // when the menu closes, update the value if needed
     (0, react_1.useEffect)(() => {
         if (!isOpen && wasOpen) {
             onCloseMenu();
         }
     }, [isOpen, wasOpen, onCloseMenu]);
+    /**
+     *
+     * Menu management
+     *
+     */
     const [popoverMenuWidth, setPopoverMenuWidth] = (0, react_1.useState)(0);
+    // When the menu opens, or the selection changes, or the focused option changes
+    // update the menu width
     (0, react_1.useEffect)(() => {
         setPopoverMenuWidth(comboboxRef.current?.clientWidth ?? 0);
     }, [comboboxRef, isOpen, highlightedOption, selection]);
+    // Handler fired when the menu has finished transitioning in/out
     const handleTransitionEnd = () => {
         setPopoverMenuWidth(comboboxRef.current?.clientWidth ?? 0);
     };
+    /**
+     *
+     * Event Handlers
+     *
+     */
+    // Prevent combobox from gaining focus by default
     const handleInputWrapperMousedown = (e) => {
         if (disabled) {
             e.preventDefault();
         }
     };
+    // Set focus to the input element on click
     const handleComboboxClick = (e) => {
+        // If we clicked the wrapper, not the input itself.
+        // (Focus is set automatically if the click is on the input)
         if (e.target !== inputRef.current) {
             let cursorPos = 0;
             if (inputRef.current) {
@@ -556,21 +707,29 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             }
             setInputFocus(cursorPos);
         }
+        // Only open the menu in response to a click
         openMenu();
     };
+    // Fired whenever the wrapper gains focus,
+    // and any time the focus within changes
     const handleComboboxFocus = (e) => {
         scrollInputToEnd();
         trackFocusedElement(getNameFromElement(e.target));
     };
+    // Fired onChange
     const handleInputChange = ({ target: { value }, }) => {
         setInputValue(value);
+        // fire any filter function passed in
         onFilter?.(value);
     };
     const handleKeyDown = (event) => {
         const isFocusInMenu = menuRef.current?.contains(document.activeElement);
         const isFocusOnCombobox = comboboxRef.current?.contains(document.activeElement);
         const isFocusInComponent = isFocusOnCombobox || isFocusInMenu;
+        // Only run if the focus is in the component
         if (isFocusInComponent) {
+            // No support for modifiers yet
+            // TODO - Handle support for multiple chip selection
             if (event.ctrlKey || event.shiftKey || event.altKey) {
                 return;
             }
@@ -583,14 +742,17 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
                                 updateHighlightedOption('first');
                                 updateFocusedChip(null);
                             }
+                            // else use default behavior
                             break;
                         }
                         case 'LastChip': {
+                            // use default behavior
                             updateFocusedChip(null);
                             break;
                         }
                         case 'FirstChip':
                         case 'MiddleChip': {
+                            // use default behavior
                             break;
                         }
                         case 'ClearButton':
@@ -606,32 +768,45 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
                 }
                 case lib_1.keyMap.Enter: {
                     if (!isOpen) {
+                        // If the menu is not open, enter should open the menu
                         openMenu();
                     }
-                    else if (focusedElementName === Combobox_types_1.ComboboxElement.Input &&
+                    else if (
+                    // Select the highlighted option iff
+                    // the menu is open,
+                    // we're focused on input element,
+                    // and the highlighted option is not disabled
+                    focusedElementName === Combobox_types_1.ComboboxElement.Input &&
                         !(0, isNull_1.default)(highlightedOption) &&
                         !isOptionDisabled(highlightedOption)) {
                         updateSelection(highlightedOption);
                     }
-                    else if (focusedElementName === Combobox_types_1.ComboboxElement.ClearButton) {
+                    else if (
+                    // Focused on clear button
+                    focusedElementName === Combobox_types_1.ComboboxElement.ClearButton) {
                         updateSelection(null);
                         setInputFocus();
                     }
                     break;
                 }
                 case lib_1.keyMap.Backspace: {
+                    // Backspace key focuses last chip if the input is focused
+                    // Note: Chip removal behavior is handled in `onRemove` defined in `renderChips`
                     if (isMultiselect(selection)) {
                         if (focusedElementName === 'Input' &&
                             inputRef.current?.selectionStart === 0) {
                             updateFocusedChip('last');
                         }
                     }
+                    // Open the menu regardless
                     openMenu();
                     break;
                 }
                 case lib_1.keyMap.ArrowDown: {
                     if (isOpen) {
+                        // Prevent the page from scrolling
                         event.preventDefault();
+                        // only change option if the menu is already open
                         updateHighlightedOption('next');
                     }
                     else {
@@ -641,7 +816,9 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
                 }
                 case lib_1.keyMap.ArrowUp: {
                     if (isOpen) {
+                        // Prevent the page from scrolling
                         event.preventDefault();
+                        // only change option if the menu is already open
                         updateHighlightedOption('prev');
                     }
                     else {
@@ -665,17 +842,34 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             }
         }
     };
+    /**
+     *
+     * Global Event Handler
+     *
+     */
+    /**
+     * We add two event handlers to the document to handle the backdrop click behavior.
+     * Intended behavior is to close the menu, and keep focus on the Combobox.
+     * No other click event handlers should fire on backdrop click
+     *
+     * 1. Mousedown event fires
+     * 2. We prevent `mousedown`'s default behavior, to prevent focus from being applied to the body (or other target)
+     * 3. Click event fires
+     * 4. We handle this event on _capture_, and stop propagation before the `click` event propagates all the way to any other element.
+     *  This ensures that even if we click on a button, that handler is not fired
+     * 5. Then we call `closeMenu`, setting `isOpen = false`, and rerender the component
+     */
     (0, hooks_1.useEventListener)('mousedown', (mousedown) => {
         if (!doesComponentContainEventTarget(mousedown)) {
-            mousedown.preventDefault();
-            mousedown.stopPropagation();
+            mousedown.preventDefault(); // Prevent focus from being applied to body
+            mousedown.stopPropagation(); // Stop any other mousedown events from firing
         }
     }, {
         enabled: isOpen,
     });
     (0, hooks_1.useEventListener)('click', (click) => {
         if (!doesComponentContainEventTarget(click)) {
-            click.stopPropagation();
+            click.stopPropagation(); // Stop any other click events from firing
             closeMenu();
         }
     }, {
@@ -710,6 +904,12 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
             chipTruncationLocation,
             chipCharacterLimit,
             inputValue,
+            // When we open the menu (popover), we want the width of
+            // menu options to be same as the size of the input by default.
+            // If user has specifed a description with the option, we want
+            // the width of the option display value to be the same as the
+            // width of the input and the accomodate the description
+            // in rest of the popover width.
             searchInputSize: popoverMenuWidth,
         } },
         react_1.default.createElement("div", { className: (0, emotion_1.cx)((0, Combobox_styles_1.comboboxParentStyle)(size), className), ...rest },
@@ -733,16 +933,29 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
                 renderedInputIcons),
             state === 'error' && errorMessage && (react_1.default.createElement("div", { className: (0, emotion_1.cx)(Combobox_styles_1.errorMessageThemeStyle[theme], Combobox_styles_1.errorMessageSizeStyle[size]) }, errorMessage)),
             react_1.default.createElement(ComboboxMenu_1.ComboboxMenu, { id: menuId, labelId: labelId, refEl: comboboxRef, ref: menuRef, className: (0, emotion_1.cx)(popoverMenuStyles(popoverMenuWidth, descriptionCharacters), popoverClassName), searchLoadingMessage: searchLoadingMessage, searchErrorMessage: searchErrorMessage, searchEmptyMessage: searchEmptyMessage, ...popoverProps }, renderedOptionsJSX))));
+    // Closure-dependant utils
+    /**
+     * Returns whether the event target is a Combobox element
+     */
     function doesComponentContainEventTarget({ target }) {
         return (menuRef.current?.contains(target) ||
             comboboxRef.current?.contains(target) ||
             false);
     }
+    /**
+     * Scrolls the combobox to the far right.
+     * Used when `overflow === 'scroll-x'`.
+     * Has no effect otherwise
+     */
     function scrollInputToEnd() {
         if (inputWrapperRef && inputWrapperRef.current) {
+            // TODO - consider converting to .scrollTo(). This is not yet supported in IE or jsdom
             inputWrapperRef.current.scrollLeft = inputWrapperRef.current.scrollWidth;
         }
     }
+    /**
+     * Returns the provided element as a ComboboxElement string
+     */
     function getNameFromElement(element) {
         if (!element)
             return;
@@ -769,6 +982,7 @@ function Combobox({ children, label, description, placeholder = 'Select', 'aria-
 }
 exports.Combobox = Combobox;
 Combobox.propTypes = {
+    // Multiselect props
     multiselect: prop_types_1.default.bool,
     value: prop_types_1.default.oneOfType([
         prop_types_1.default.string,
@@ -779,6 +993,7 @@ Combobox.propTypes = {
         prop_types_1.default.arrayOf(prop_types_1.default.string),
     ]),
     overflow: prop_types_1.default.oneOf(Object.values(Combobox_types_1.Overflow)),
+    // Standard Props
     darkMode: prop_types_1.default.bool,
     label: prop_types_1.default.string,
     'aria-label': prop_types_1.default.string,
@@ -800,10 +1015,15 @@ Combobox.propTypes = {
     description: prop_types_1.default.string,
     placeholder: prop_types_1.default.string,
     filteredOptions: prop_types_1.default.arrayOf(prop_types_1.default.string),
+    // Popover Props
     popoverZIndex: prop_types_1.default.number,
     usePortal: prop_types_1.default.bool,
     scrollContainer: prop_types_1.default.elementType,
     portalContainer: prop_types_1.default.elementType,
     portalClassName: prop_types_1.default.string,
 };
+/**
+ * Why'd you have to go and make things so complicated?
+ * - Avril; and also me to myself about this component
+ */
 //# sourceMappingURL=Combobox.js.map