@mui/material 9.0.0 → 9.1.0

package/useAutocomplete/useAutocomplete.js

@@ -9,6 +9,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.createFilterOptions = createFilterOptions;
 exports.default = void 0;
 var React = _interopRequireWildcard(require("react"));
+var _contains = _interopRequireDefault(require("@mui/utils/contains"));
 var _setRef = _interopRequireDefault(require("@mui/utils/setRef"));
 var _useEventCallback = _interopRequireDefault(require("@mui/utils/useEventCallback"));
 var _useControlled = _interopRequireDefault(require("@mui/utils/useControlled"));
@@ -63,7 +64,7 @@ const defaultFilterOptions = createFilterOptions();
 
 // Number of options to jump in list box when `Page Up` and `Page Down` keys are used.
 const pageSize = 5;
-const defaultIsActiveElementInListbox = listboxRef => listboxRef.current !== null && listboxRef.current.parentElement?.contains(document.activeElement);
+const defaultIsActiveElementInListbox = listboxRef => listboxRef.current !== null && (0, _contains.default)(listboxRef.current.parentElement, document.activeElement);
 const defaultIsOptionEqualToValue = (option, value) => option === value;
 const MULTIPLE_DEFAULT_VALUE = [];
 function getInputValue(value, multiple, getOptionLabel, renderValue) {
@@ -115,6 +116,7 @@ function useAutocomplete(props) {
     options,
     readOnly = false,
     renderValue,
+    resetHighlightOnMouseLeave = false,
     selectOnFocus = !props.freeSolo,
     value: valueProp
   } = props;
@@ -135,12 +137,29 @@ function useAutocomplete(props) {
   const firstFocus = React.useRef(true);
   const inputRef = React.useRef(null);
   const listboxRef = React.useRef(null);
+  // VoiceOver synthesises a spurious Backspace on the input after a chip
+  // deletion moves DOM focus back to it. This flag suppresses that one event.
+  const ignoreNextBackspaceRef = React.useRef(false);
   const windowLostFocus = React.useRef(false);
   const [anchorEl, setAnchorEl] = React.useState(null);
   const [focusedItem, setFocusedItem] = React.useState(-1);
   const defaultHighlighted = autoHighlight ? 0 : -1;
   const highlightedIndexRef = React.useRef(defaultHighlighted);
 
+  // Tracks how the current highlight was set:
+  // - 'keyboard' — arrow keys, Home/End, PageUp/PageDown
+  // - 'mouse'    — handleOptionMouseMove
+  // - 'touch'    — handleOptionTouchStart
+  // - null       — programmatic (autoHighlight, value sync)
+  //
+  // This lets handleBlur and the Enter handler distinguish intentional
+  // interactions from incidental ones — e.g. autoSelect should not commit
+  // a highlight that came from a casual mouse hover.
+  /** @type {React.RefObject<AutocompleteHighlightChangeReason | null>} */
+  const highlightReasonRef = React.useRef(null);
+  const touchScrolledRef = React.useRef(false);
+  const isTouchRef = React.useRef(false);
+
   // Calculate the initial inputValue on mount only.
   // useRef ensures it doesn't update dynamically with defaultValue or value props.
   const initialInputValue = React.useRef(getInputValue(defaultValue ?? valueProp, multiple, getOptionLabel)).current;
@@ -157,10 +176,12 @@ function useAutocomplete(props) {
   });
   const [focused, setFocused] = React.useState(false);
   const resetInputValue = React.useCallback((event, newValue, reason) => {
-    // retain current `inputValue` if new option isn't selected and `clearOnBlur` is false
-    // When `multiple` is enabled, `newValue` is an array of all selected items including the newly selected item
+    // Retain the current `inputValue` when no new option is selected and `clearOnBlur` is false.
+    // In `multiple` mode, `newValue` is the next value array, so only length growth counts as a selection.
     const isOptionSelected = multiple ? value.length < newValue.length : newValue !== null;
-    if (!isOptionSelected && !clearOnBlur) {
+    // A controlled single-value `freeSolo` reset to `null` should still clear the input.
+    const shouldClearOnReset = reason === 'reset' && freeSolo && !multiple && newValue === null;
+    if (!isOptionSelected && !clearOnBlur && !shouldClearOnReset) {
       return;
     }
     const newInputValue = getInputValue(newValue, multiple, getOptionLabel, renderValue);
@@ -171,7 +192,7 @@ function useAutocomplete(props) {
     if (onInputChange) {
       onInputChange(event, newInputValue, reason);
     }
-  }, [getOptionLabel, inputValue, multiple, onInputChange, setInputValueState, clearOnBlur, value, renderValue]);
+  }, [getOptionLabel, inputValue, multiple, onInputChange, setInputValueState, clearOnBlur, freeSolo, value, renderValue]);
   const [open, setOpenState] = (0, _useControlled.default)({
     controlled: openProp,
     default: false,
@@ -226,8 +247,10 @@ function useAutocomplete(props) {
       return;
     }
 
-    // Only reset the input's value when freeSolo if the component's value changes.
-    if (freeSolo && !valueChange) {
+    // In freeSolo mode, only reset the input after a real value change.
+    // Also prevent the initial default value of `null` from clearing controlled values.
+    const shouldSkipFreeSoloReset = freeSolo && (!valueChange || value == null && previousProps.value === undefined);
+    if (shouldSkipFreeSoloReset) {
       return;
     }
     resetInputValue(null, value, 'reset');
@@ -278,12 +301,16 @@ function useAutocomplete(props) {
       }
     }
   }
-  const setHighlightedIndex = (0, _useEventCallback.default)(({
-    event,
+  const syncHighlightedIndexToDOM = (0, _useEventCallback.default)(({
     index,
-    reason
+    reason,
+    preserveScroll = false
   }) => {
-    highlightedIndexRef.current = index;
+    // React can clear refs before pending passive effects run during unmount.
+    // If both refs are gone, there is no DOM left to sync.
+    if (inputRef.current == null && listboxRef.current == null) {
+      return;
+    }
 
     // does the index exist?
     if (index === -1) {
@@ -291,9 +318,6 @@ function useAutocomplete(props) {
     } else {
       inputRef.current.setAttribute('aria-activedescendant', `${id}-option-${index}`);
     }
-    if (onHighlightChange && ['mouse', 'keyboard', 'touch'].includes(reason)) {
-      onHighlightChange(event, index === -1 ? null : filteredOptions[index], reason);
-    }
     if (!listboxRef.current) {
       return;
     }
@@ -312,7 +336,9 @@ function useAutocomplete(props) {
       return;
     }
     if (index === -1) {
-      listboxNode.scrollTop = 0;
+      if (!preserveScroll) {
+        listboxNode.scrollTop = 0;
+      }
       return;
     }
     const option = listboxRef.current.querySelector(`[data-option-index="${index}"]`);
@@ -340,15 +366,46 @@ function useAutocomplete(props) {
       }
     }
   });
+  const setHighlightedIndex = (0, _useEventCallback.default)(({
+    event,
+    index,
+    reason,
+    preserveScroll = false
+  }) => {
+    highlightedIndexRef.current = index;
+    highlightReasonRef.current = reason ?? null;
+    if (onHighlightChange && ['mouse', 'keyboard', 'touch'].includes(reason)) {
+      onHighlightChange(event, index === -1 ? null : filteredOptions[index], reason);
+    }
+    syncHighlightedIndexToDOM({
+      index,
+      reason,
+      preserveScroll
+    });
+  });
+  const setHighlightedIndexFromSync = (0, _useEventCallback.default)(({
+    index
+  }) => {
+    highlightedIndexRef.current = index;
+    syncHighlightedIndexToDOM({
+      index,
+      reason: highlightReasonRef.current
+    });
+  });
   const changeHighlightedIndex = (0, _useEventCallback.default)(({
     event,
     diff,
     direction = 'next',
-    reason
+    reason,
+    preserveScroll
   }) => {
     if (!popupOpen) {
       return;
     }
+    if (reason === 'keyboard') {
+      touchScrolledRef.current = false;
+      isTouchRef.current = false;
+    }
     const getNextIndex = () => {
       const maxIndex = filteredOptions.length - 1;
       if (diff === 'reset') {
@@ -385,7 +442,8 @@ function useAutocomplete(props) {
     setHighlightedIndex({
       index: nextIndex,
       reason,
-      event
+      event,
+      preserveScroll
     });
 
     // Sync the content of the input with the highlighted option.
@@ -439,15 +497,24 @@ function useAutocomplete(props) {
     // If it exists and the value and the inputValue haven't changed, just update its index, otherwise continue execution
     const previousHighlightedOptionIndex = getPreviousHighlightedOptionIndex();
     if (previousHighlightedOptionIndex !== -1) {
-      highlightedIndexRef.current = previousHighlightedOptionIndex;
+      // Keep the original highlight reason while re-syncing the DOM state.
+      // The highlighted option still exists after the filteredOptions array changed
+      // (e.g. async fetch returns new options while the user is mid-navigation),
+      // so the original interaction reason (keyboard, mouse, etc.) still applies.
+      setHighlightedIndexFromSync({
+        index: previousHighlightedOptionIndex
+      });
       return;
     }
     const valueItem = multiple ? value[0] : value;
 
     // The popup is empty, reset
     if (filteredOptions.length === 0 || valueItem == null) {
+      // Preserve scroll when new options are appended without changing the current filter.
+      const isAppendOnly = filteredOptionsChanged && previousProps.inputValue === inputValue && previousProps.filteredOptions?.length > 0 && filteredOptions.length > previousProps.filteredOptions.length && previousProps.filteredOptions.every((option, index) => getOptionLabel(option) === getOptionLabel(filteredOptions[index]));
       changeHighlightedIndex({
-        diff: 'reset'
+        diff: 'reset',
+        preserveScroll: isAppendOnly
       });
       return;
     }
@@ -459,8 +526,12 @@ function useAutocomplete(props) {
     if (valueItem != null) {
       const currentOption = filteredOptions[highlightedIndexRef.current];
 
-      // Keep the current highlighted index if possible
-      if (multiple && currentOption && value.findIndex(val => isOptionEqualToValue(currentOption, val)) !== -1) {
+      // Keep the current selected highlight while the popup stays open;
+      // on reopen, resync from the selected value.
+      if (multiple && currentOption && value.findIndex(val => isOptionEqualToValue(currentOption, val)) !== -1 && previousProps.filteredOptions?.length > 0) {
+        setHighlightedIndexFromSync({
+          index: highlightedIndexRef.current
+        });
         return;
       }
       const itemIndex = filteredOptions.findIndex(optionItem => isOptionEqualToValue(optionItem, valueItem));
@@ -495,7 +566,7 @@ function useAutocomplete(props) {
   filteredOptions.length,
   // Don't sync the highlighted index with the value when multiple
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  multiple ? false : value, changeHighlightedIndex, setHighlightedIndex, popupOpen, inputValue, multiple]);
+  multiple ? false : value, changeHighlightedIndex, setHighlightedIndex, setHighlightedIndexFromSync, popupOpen, inputValue, multiple]);
   const handleListboxRef = (0, _useEventCallback.default)(node => {
     (0, _setRef.default)(listboxRef, node);
     if (!node) {
@@ -541,6 +612,7 @@ function useAutocomplete(props) {
     }
     setOpenState(true);
     setInputPristine(true);
+    isTouchRef.current = false;
     if (onOpen) {
       onOpen(event);
     }
@@ -550,6 +622,8 @@ function useAutocomplete(props) {
       return;
     }
     setOpenState(false);
+    touchScrolledRef.current = false;
+    highlightReasonRef.current = null;
     if (onClose) {
       onClose(event, reason);
     }
@@ -567,7 +641,6 @@ function useAutocomplete(props) {
     }
     setValueState(newValue);
   };
-  const isTouch = React.useRef(false);
   const selectNewValue = (event, option, reasonProp = 'selectOption', origin = 'options') => {
     let reason = reasonProp;
     let newValue = option;
@@ -594,7 +667,7 @@ function useAutocomplete(props) {
     if (!disableCloseOnSelect && (!event || !event.ctrlKey && !event.metaKey)) {
       handleClose(event, reason);
     }
-    if (blurOnSelect === true || blurOnSelect === 'touch' && isTouch.current || blurOnSelect === 'mouse' && !isTouch.current) {
+    if (blurOnSelect === true || blurOnSelect === 'touch' && isTouchRef.current || blurOnSelect === 'mouse' && !isTouchRef.current) {
       inputRef.current.blur();
     }
   };
@@ -652,7 +725,6 @@ function useAutocomplete(props) {
     focusItem(nextItem);
   };
   const handleClear = event => {
-    ignoreFocus.current = true;
     setInputValueState('');
     if (onInputChange) {
       onInputChange(event, '', 'clear');
@@ -780,29 +852,47 @@ function useAutocomplete(props) {
           }
           break;
         case 'Enter':
-          if (highlightedIndexRef.current !== -1 && popupOpen) {
-            const option = filteredOptions[highlightedIndexRef.current];
-            const disabled = getOptionDisabled ? getOptionDisabled(option) : false;
+          {
+            // In freeSolo, only select the highlighted option if the user hasn't
+            // typed new text (inputPristine) or explicitly interacted with an option
+            // (keyboard, mouse, or touch — any non-null reason). This lets typed
+            // text win over a programmatic highlight (reason=null, e.g. from
+            // syncHighlightedIndex matching a previous value) while still honoring
+            // deliberate user interactions like hovering a suggestion then pressing Enter.
+            const shouldSelectHighlighted = !freeSolo || inputPristine || highlightReasonRef.current !== null;
+            if (highlightedIndexRef.current !== -1 && popupOpen && shouldSelectHighlighted &&
+            // After a touch-scroll the highlight is stale (the user scrolled
+            // past it), so skip selection until the next deliberate interaction.
+            !touchScrolledRef.current) {
+              const option = filteredOptions[highlightedIndexRef.current];
+              const disabled = getOptionDisabled ? getOptionDisabled(option) : false;
 
-            // Avoid early form validation, let the end-users continue filling the form.
-            event.preventDefault();
-            if (disabled) {
-              return;
-            }
-            selectNewValue(event, option, 'selectOption');
+              // Avoid early form validation, let the end-users continue filling the form.
+              event.preventDefault();
+              if (disabled) {
+                return;
+              }
+              selectNewValue(event, option, 'selectOption');
 
-            // Move the selection to the end.
-            if (autoComplete) {
-              inputRef.current.setSelectionRange(inputRef.current.value.length, inputRef.current.value.length);
-            }
-          } else if (freeSolo && inputValue !== '' && inputValueIsSelectedValue === false) {
-            if (multiple) {
-              // Allow people to add new values before they submit the form.
+              // Move the selection to the end.
+              if (autoComplete) {
+                inputRef.current.setSelectionRange(inputRef.current.value.length, inputRef.current.value.length);
+              }
+            } else if (freeSolo && inputValue !== '' && inputValueIsSelectedValue === false) {
+              if (multiple) {
+                // Allow people to add new values before they submit the form.
+                event.preventDefault();
+              }
+              selectNewValue(event, inputValue, 'createOption', 'freeSolo');
+            } else if (popupOpen && touchScrolledRef.current) {
+              // The highlight is stale from a touch-scroll - close without selecting.
               event.preventDefault();
+              // This happens on Enter, but re-using "escape" as the closest `AutocompleteCloseReason`
+              // to avoid creating a new reason
+              handleClose(event, 'escape');
             }
-            selectNewValue(event, inputValue, 'createOption', 'freeSolo');
+            break;
           }
-          break;
         case 'Escape':
           if (popupOpen) {
             // Avoid Opera to exit fullscreen mode.
@@ -820,6 +910,10 @@ function useAutocomplete(props) {
           break;
         case 'Backspace':
           // Remove the value on the left of the "cursor"
+          if (ignoreNextBackspaceRef.current) {
+            ignoreNextBackspaceRef.current = false;
+            break;
+          }
           if (multiple && !readOnly && inputValue === '' && value.length > 0) {
             const index = focusedItem === -1 ? value.length - 1 : focusedItem;
             const newValue = value.slice();
@@ -827,6 +921,18 @@ function useAutocomplete(props) {
             handleValue(event, newValue, 'removeOption', {
               option: value[index]
             });
+            if (focusedItem !== -1) {
+              // Suppress the spurious Backspace VoiceOver synthesises on the
+              // input after focus returns to it. Clear it shortly after
+              // deletion so a later real Backspace is not ignored if the
+              // synthetic follow-up event never arrives.
+              ignoreNextBackspaceRef.current = true;
+              setTimeout(() => {
+                if (ignoreNextBackspaceRef.current) {
+                  ignoreNextBackspaceRef.current = false;
+                }
+              }, 0);
+            }
           }
           if (!multiple && renderValue && !readOnly && inputValue === '') {
             handleValue(event, null, 'removeOption', {
@@ -880,7 +986,7 @@ function useAutocomplete(props) {
     }
   };
   const handleBlur = event => {
-    // Ignore the event when using the scrollbar with IE11
+    // Ignore the event when using the scrollbar with IE 11
     if (unstable_isActiveElementInListbox(listboxRef)) {
       inputRef.current.focus();
       return;
@@ -888,7 +994,12 @@ function useAutocomplete(props) {
     setFocused(false);
     firstFocus.current = true;
     ignoreFocus.current = false;
-    if (autoSelect && highlightedIndexRef.current !== -1 && popupOpen) {
+
+    // Auto-select the highlighted option on blur, but only if the highlight
+    // came from keyboard navigation or was set programmatically (autoHighlight).
+    // Mouse hover and touch should not trigger selection — the user may have
+    // moved the pointer over an option without intending to commit to it.
+    if (autoSelect && highlightedIndexRef.current !== -1 && popupOpen && highlightReasonRef.current !== 'mouse' && highlightReasonRef.current !== 'touch') {
       selectNewValue(event, filteredOptions[highlightedIndexRef.current], 'blur');
     } else if (autoSelect && freeSolo && inputValue !== '') {
       selectNewValue(event, inputValue, 'blur', 'freeSolo');
@@ -899,9 +1010,10 @@ function useAutocomplete(props) {
   };
   const handleInputChange = event => {
     const newValue = event.target.value;
-    if (inputValue !== newValue) {
+    const valueChanged = inputValue !== newValue;
+    if (valueChanged) {
       setInputValueState(newValue);
-      setInputPristine(false);
+      touchScrolledRef.current = false;
       if (onInputChange) {
         onInputChange(event, newValue, 'input');
       }
@@ -915,6 +1027,12 @@ function useAutocomplete(props) {
     } else {
       handleOpen(event);
     }
+
+    // Called after handleOpen so it overrides handleOpen's setInputPristine(true)
+    // when the first keystroke also opens the popup.
+    if (valueChanged) {
+      setInputPristine(false);
+    }
   };
   const handleOptionMouseMove = event => {
     const index = Number(event.currentTarget.getAttribute('data-option-index'));
@@ -924,20 +1042,46 @@ function useAutocomplete(props) {
         index,
         reason: 'mouse'
       });
+    } else {
+      // The option is already highlighted (e.g. programmatically via autoHighlight),
+      // but the user moved the mouse over it — mark as mouse-initiated so
+      // autoSelect on blur correctly treats this as incidental hover.
+      highlightReasonRef.current = 'mouse';
+    }
+    // Don't clear the touch-scroll guard while touch state is still latched.
+    // After a touch gesture, browsers may fire compatibility mousemove
+    // events; if those cleared the guard immediately, later compat events in
+    // the same sequence could be misclassified as a real mouse interaction.
+    // Touch state is cleared by the next deliberate interaction
+    // (keyboard nav, handleOptionClick, or handleOpen).
+    if (!isTouchRef.current) {
+      touchScrolledRef.current = false;
+    }
+  };
+  const handleListboxMouseLeave = event => {
+    if (!resetHighlightOnMouseLeave || highlightedIndexRef.current === -1 || highlightReasonRef.current !== 'mouse' || isTouchRef.current) {
+      return;
     }
+    setHighlightedIndex({
+      event,
+      index: -1,
+      reason: 'mouse',
+      preserveScroll: true
+    });
   };
   const handleOptionTouchStart = event => {
+    touchScrolledRef.current = false;
     setHighlightedIndex({
       event,
       index: Number(event.currentTarget.getAttribute('data-option-index')),
       reason: 'touch'
     });
-    isTouch.current = true;
+    isTouchRef.current = true;
   };
   const handleOptionClick = event => {
     const index = Number(event.currentTarget.getAttribute('data-option-index'));
     selectNewValue(event, filteredOptions[index], 'selectOption');
-    isTouch.current = false;
+    isTouchRef.current = false;
   };
   const handleItemDelete = index => event => {
     const newValue = value.slice();
@@ -962,11 +1106,11 @@ function useAutocomplete(props) {
   // Prevent input blur when interacting with the combobox
   const handleMouseDown = event => {
     // Prevent focusing the input if click is anywhere outside the Autocomplete
-    if (!event.currentTarget.contains(event.target)) {
+    if (!(0, _contains.default)(event.currentTarget, event.target)) {
       return;
     }
     // Don't interfere with interactions outside the input area (e.g. helper text)
-    if (anchorEl && !anchorEl.contains(event.target)) {
+    if (anchorEl && !(0, _contains.default)(anchorEl, event.target)) {
       return;
     }
     if (event.target.getAttribute('id') !== id) {
@@ -977,11 +1121,11 @@ function useAutocomplete(props) {
   // Focus the input when interacting with the combobox
   const handleClick = event => {
     // Prevent focusing the input if click is anywhere outside the Autocomplete
-    if (!event.currentTarget.contains(event.target)) {
+    if (!(0, _contains.default)(event.currentTarget, event.target)) {
       return;
     }
     // Don't interfere with interactions outside the input area (e.g. helper text)
-    if (anchorEl && !anchorEl.contains(event.target)) {
+    if (anchorEl && !(0, _contains.default)(anchorEl, event.target)) {
       return;
     }
     inputRef.current.focus();
@@ -1065,7 +1209,10 @@ function useAutocomplete(props) {
     getClearProps: () => ({
       tabIndex: -1,
       type: 'button',
-      onClick: handleClear
+      onClick: event => {
+        ignoreFocus.current = true;
+        handleClear(event);
+      }
     }),
     getItemProps: ({
       index = 0
@@ -1075,6 +1222,12 @@ function useAutocomplete(props) {
       }),
       'data-item-index': index,
       tabIndex: -1,
+      onFocus: () => {
+        // If focus on the item doesn't come from keyboard events, we update the state via onFocus.
+        if (focusedItem !== index) {
+          setFocusedItem(index);
+        }
+      },
       ...(!readOnly && {
         onDelete: multiple ? handleItemDelete(index) : handleSingleItemDelete
       })
@@ -1084,15 +1237,37 @@ function useAutocomplete(props) {
       type: 'button',
       onClick: handlePopupIndicator
     }),
-    getListboxProps: () => ({
+    getListboxProps: (other = {}) => ({
+      ...other,
       role: 'listbox',
       id: `${id}-listbox`,
       'aria-labelledby': `${id}-label`,
       'aria-multiselectable': multiple || undefined,
       ref: handleListboxRef,
       onMouseDown: event => {
+        other.onMouseDown?.(event);
+        if (event.defaultMuiPrevented) {
+          return;
+        }
+
         // Prevent blur
         event.preventDefault();
+      },
+      onScroll: event => {
+        other.onScroll?.(event);
+        if (event.defaultMuiPrevented) {
+          return;
+        }
+        if (isTouchRef.current) {
+          touchScrolledRef.current = true;
+        }
+      },
+      onMouseLeave: event => {
+        other.onMouseLeave?.(event);
+        if (event.defaultMuiPrevented) {
+          return;
+        }
+        handleListboxMouseLeave(event);
       }
     }),
     getOptionProps: ({