@mui/material 7.3.10 → 7.3.11

package/esm/Unstable_TrapFocus/FocusTrap.js

@@ -8,7 +8,9 @@ import ownerDocument from '@mui/utils/ownerDocument';
 import getReactElementRef from '@mui/utils/getReactElementRef';
 import exactProp from '@mui/utils/exactProp';
 import elementAcceptingRef from '@mui/utils/elementAcceptingRef';
+import contains from "../utils/contains.js";
 import getActiveElement from "../utils/getActiveElement.js";
+import { getFocusTarget } from "../utils/focusable.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Inspired by https://github.com/focus-trap/tabbable
 const candidatesSelector = ['input', 'select', 'textarea', 'a[href]', 'button', '[tabindex]', 'audio[controls]', 'video[controls]', '[contenteditable]:not([contenteditable="false"])'].join(',');
@@ -107,21 +109,29 @@ function FocusTrap(props) {
     activated.current = !disableAutoFocus;
   }, [disableAutoFocus, open]);
   React.useEffect(() => {
+    // Reset on every mount — React 18 Strict Mode double-mounts leave this
+    // stuck at `true` after the cleanup of the previous mount set it.
+    ignoreNextEnforceFocus.current = false;
+
     // We might render an empty child.
     if (!open || !rootRef.current) {
       return;
     }
     const doc = ownerDocument(rootRef.current);
     const activeElement = getActiveElement(doc);
-    if (!rootRef.current.contains(activeElement)) {
-      if (!rootRef.current.hasAttribute('tabIndex')) {
+
+    // Prefer the explicitly marked focusable element. Fall back to the root
+    // element for generic FocusTrap usage.
+    const focusTarget = getFocusTarget(rootRef.current) ?? rootRef.current;
+    if (!contains(rootRef.current, activeElement)) {
+      if (!focusTarget.hasAttribute('tabIndex')) {
         if (process.env.NODE_ENV !== 'production') {
           console.error(['MUI: The modal content node does not accept focus.', 'For the benefit of assistive technologies, ' + 'the tabIndex of the node is being set to "-1".'].join('\n'));
         }
-        rootRef.current.setAttribute('tabIndex', '-1');
+        focusTarget.setAttribute('tabIndex', '-1');
       }
       if (activated.current) {
-        rootRef.current.focus();
+        focusTarget.focus();
       }
     }
     return () => {
@@ -181,7 +191,7 @@ function FocusTrap(props) {
       }
 
       // The focus is already inside
-      if (rootElement.contains(activeEl)) {
+      if (contains(rootElement, activeEl)) {
         return;
       }
 

package/esm/index.js

@@ -1,5 +1,5 @@
 /**
- * @mui/material v7.3.10
+ * @mui/material v7.3.11
  *
  * @license MIT
  * This source code is licensed under the MIT license found in the

package/esm/useAutocomplete/useAutocomplete.d.ts

@@ -46,12 +46,11 @@ export interface UseAutocompleteProps<Value, Multiple extends boolean | undefine
    */
   autoHighlight?: boolean | undefined;
   /**
-   * If `true`, the selected option becomes the value of the input
-   * when the Autocomplete loses focus unless the user chooses
-   * a different option or changes the character string in the input.
+   * If `true`, the value is updated when the input loses focus under one of these conditions:
    *
-   * When using the `freeSolo` mode, the typed value will be the input value
-   * if the Autocomplete loses focus without highlighting an option.
+   * - An option highlighted via keyboard navigation or `autoHighlight` is selected.
+   *   Hover and touch highlights are ignored.
+   * - Otherwise, in `freeSolo` mode, the typed text becomes the value.
    * @default false
    */
   autoSelect?: boolean | undefined;

package/esm/useAutocomplete/useAutocomplete.js

@@ -1,6 +1,7 @@
 'use client';
 
 import * as React from 'react';
+import contains from '@mui/utils/contains';
 import setRef from '@mui/utils/setRef';
 import useEventCallback from '@mui/utils/useEventCallback';
 import useControlled from '@mui/utils/useControlled';
@@ -55,7 +56,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 && contains(listboxRef.current.parentElement, document.activeElement);
 const defaultIsOptionEqualToValue = (option, value) => option === value;
 const MULTIPLE_DEFAULT_VALUE = [];
 function getInputValue(value, multiple, getOptionLabel, renderValue) {
@@ -133,6 +134,20 @@ function useAutocomplete(props) {
   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;
@@ -272,22 +287,17 @@ function useAutocomplete(props) {
       }
     }
   }
-  const setHighlightedIndex = useEventCallback(({
-    event,
+  const syncHighlightedIndexToDOM = useEventCallback(({
     index,
-    reason
+    reason,
+    preserveScroll = false
   }) => {
-    highlightedIndexRef.current = index;
-
     // does the index exist?
     if (index === -1) {
       inputRef.current.removeAttribute('aria-activedescendant');
     } 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;
     }
@@ -306,7 +316,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}"]`);
@@ -334,15 +346,46 @@ function useAutocomplete(props) {
       }
     }
   });
+  const setHighlightedIndex = useEventCallback(({
+    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 = useEventCallback(({
+    index
+  }) => {
+    highlightedIndexRef.current = index;
+    syncHighlightedIndexToDOM({
+      index,
+      reason: highlightReasonRef.current
+    });
+  });
   const changeHighlightedIndex = useEventCallback(({
     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') {
@@ -379,7 +422,8 @@ function useAutocomplete(props) {
     setHighlightedIndex({
       index: nextIndex,
       reason,
-      event
+      event,
+      preserveScroll
     });
 
     // Sync the content of the input with the highlighted option.
@@ -433,15 +477,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;
     }
@@ -453,8 +506,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));
@@ -489,7 +546,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 = useEventCallback(node => {
     setRef(listboxRef, node);
     if (!node) {
@@ -535,6 +592,7 @@ function useAutocomplete(props) {
     }
     setOpenState(true);
     setInputPristine(true);
+    isTouchRef.current = false;
     if (onOpen) {
       onOpen(event);
     }
@@ -544,6 +602,8 @@ function useAutocomplete(props) {
       return;
     }
     setOpenState(false);
+    touchScrolledRef.current = false;
+    highlightReasonRef.current = null;
     if (onClose) {
       onClose(event, reason);
     }
@@ -561,7 +621,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;
@@ -588,7 +647,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();
     }
   };
@@ -777,29 +836,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.
@@ -885,7 +962,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');
@@ -896,9 +978,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');
       }
@@ -912,6 +995,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'));
@@ -921,20 +1010,35 @@ 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 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();
@@ -959,11 +1063,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 (!contains(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 && !contains(anchorEl, event.target)) {
       return;
     }
     if (event.target.getAttribute('id') !== id) {
@@ -974,11 +1078,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 (!contains(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 && !contains(anchorEl, event.target)) {
       return;
     }
     inputRef.current.focus();
@@ -1103,6 +1207,11 @@ function useAutocomplete(props) {
       onMouseDown: event => {
         // Prevent blur
         event.preventDefault();
+      },
+      onScroll: () => {
+        if (isTouchRef.current) {
+          touchScrolledRef.current = true;
+        }
       }
     }),
     getOptionProps: ({

package/esm/utils/contains.d.ts

@@ -0,0 +1,2 @@
+import contains from '@mui/utils/contains';
+export default contains;

package/esm/utils/contains.js

@@ -0,0 +1,2 @@
+import contains from '@mui/utils/contains';
+export default contains;

package/esm/utils/focusable.d.ts

@@ -0,0 +1,7 @@
+export declare const FOCUSABLE_ATTRIBUTE = "data-mui-focusable";
+/**
+ * Returns the element marked as the initial focus target inside a focus trap.
+ * The root element takes precedence over marked descendants so components can
+ * opt into focusing their own root surface directly.
+ */
+export declare function getFocusTarget(rootElement: HTMLElement | null | undefined): HTMLElement | null;

package/esm/utils/focusable.js

@@ -0,0 +1,13 @@
+export const FOCUSABLE_ATTRIBUTE = 'data-mui-focusable';
+
+/**
+ * Returns the element marked as the initial focus target inside a focus trap.
+ * The root element takes precedence over marked descendants so components can
+ * opt into focusing their own root surface directly.
+ */
+export function getFocusTarget(rootElement) {
+  if (!rootElement) {
+    return null;
+  }
+  return rootElement.hasAttribute(FOCUSABLE_ATTRIBUTE) ? rootElement : rootElement.querySelector(`[${FOCUSABLE_ATTRIBUTE}]`);
+}

package/esm/utils/getEventTarget.d.ts

@@ -0,0 +1,2 @@
+import getEventTarget from '@mui/utils/getEventTarget';
+export default getEventTarget;

package/esm/utils/getEventTarget.js

@@ -0,0 +1,2 @@
+import getEventTarget from '@mui/utils/getEventTarget';
+export default getEventTarget;

package/esm/version/index.js

@@ -1,6 +1,6 @@
-export const version = "7.3.10";
+export const version = "7.3.11";
 export const major = Number("7");
 export const minor = Number("3");
-export const patch = Number("10");
+export const patch = Number("11");
 export const prerelease = undefined;
 export default version;

package/index.js

@@ -1,5 +1,5 @@
 /**
- * @mui/material v7.3.10
+ * @mui/material v7.3.11
  *
  * @license MIT
  * This source code is licensed under the MIT license found in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/material",
-  "version": "7.3.10",
+  "version": "7.3.11",
   "author": "MUI Team",
   "description": "Material UI is an open-source React component library that implements Google's Material Design. It's comprehensive and can be used in production out of the box.",
   "keywords": [
@@ -33,10 +33,10 @@
     "prop-types": "^15.8.1",
     "react-is": "^19.2.3",
     "react-transition-group": "^4.4.5",
-    "@mui/core-downloads-tracker": "^7.3.10",
+    "@mui/core-downloads-tracker": "^7.3.11",
+    "@mui/utils": "^7.3.11",
     "@mui/types": "^7.4.12",
-    "@mui/utils": "^7.3.10",
-    "@mui/system": "^7.3.10"
+    "@mui/system": "^7.3.11"
   },
   "peerDependencies": {
     "@emotion/react": "^11.5.0",
@@ -44,7 +44,7 @@
     "@types/react": "^17.0.0 || ^18.0.0 || ^19.0.0",
     "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
     "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0",
-    "@mui/material-pigment-css": "^7.3.10"
+    "@mui/material-pigment-css": "^7.3.11"
   },
   "peerDependenciesMeta": {
     "@types/react": {

package/useAutocomplete/useAutocomplete.d.ts

@@ -46,12 +46,11 @@ export interface UseAutocompleteProps<Value, Multiple extends boolean | undefine
    */
   autoHighlight?: boolean | undefined;
   /**
-   * If `true`, the selected option becomes the value of the input
-   * when the Autocomplete loses focus unless the user chooses
-   * a different option or changes the character string in the input.
+   * If `true`, the value is updated when the input loses focus under one of these conditions:
    *
-   * When using the `freeSolo` mode, the typed value will be the input value
-   * if the Autocomplete loses focus without highlighting an option.
+   * - An option highlighted via keyboard navigation or `autoHighlight` is selected.
+   *   Hover and touch highlights are ignored.
+   * - Otherwise, in `freeSolo` mode, the typed text becomes the value.
    * @default false
    */
   autoSelect?: boolean | undefined;