feat(autocomplete): add phase 2 tradeoffs and outcome documentation, implement bug test for onHighlightChange, and enhance useAutocomplete logic

Author: matheusrezende

README.md

@@ -138,3 +138,9 @@ Instructions:
 
 We're excited and looking forward to seeing what you'll create!
 Good luck 🚀
+
+## Phase 2 tradeoffs and outcome
+
+- Added an effect in `useAutocomplete` that resynchronizes the highlighted option whenever the filtered options array changes. This ensures late-arriving async options promote the correct `onHighlightChange` payload, at the cost of an extra highlight event when new data arrives.
+- Considered recalculating the highlight during every reset or `syncHighlightedIndex` tick, but those approaches either missed async updates or ran more often than needed. The chosen solution isolates the work to actual option changes while reusing the existing keyboard/navigation logic.
+- Introduced a regression test (`packages/material-ui/src/Autocomplete/Autocomplete.test.js`) that simulates the reported scenario—typing “1”, then “12”, then receiving updated options, to prevent the bug from resurfacing.

packages/material-ui/src/Autocomplete/Autocomplete.test.js

@@ -167,6 +167,55 @@ describe('<Autocomplete />', () => {
       checkHighlightIs(getByRole('listbox'), 'two');
     });
 
+    it('should update the highlighted option when the options change asynchronously', () => {
+      const handleHighlightChange = spy();
+      const optionsForOne = Array.from({ length: 5 }, (_, index) => `option 1 ${index + 1}`);
+
+      const { getByRole, setProps } = render(
+        <Autocomplete
+          open
+          autoHighlight
+          filterOptions={(x) => x}
+          options={[]}
+          onHighlightChange={handleHighlightChange}
+          renderInput={(params) => <TextField {...params} autoFocus />}
+        />,
+      );
+
+      const textbox = getByRole('textbox');
+
+      act(() => {
+        fireEvent.change(textbox, { target: { value: '1' } });
+      });
+
+      act(() => {
+        setProps({ options: optionsForOne });
+      });
+
+      expect(handleHighlightChange.callCount).to.be.greaterThan(0);
+      expect(handleHighlightChange.lastCall.args[1]).to.equal('option 1 1');
+
+      act(() => {
+        fireEvent.change(textbox, { target: { value: '12' } });
+      });
+
+      // Simulate stale results still containing the old first option.
+      act(() => {
+        setProps({ options: optionsForOne });
+      });
+
+      const callCountBeforeFinalUpdate = handleHighlightChange.callCount;
+      expect(handleHighlightChange.lastCall.args[1]).to.equal('option 1 1');
+
+      act(() => {
+        setProps({ options: ['option 2 12'] });
+      });
+
+      expect(handleHighlightChange.callCount).to.be.greaterThan(callCountBeforeFinalUpdate);
+      expect(handleHighlightChange.lastCall.args[1]).to.equal('option 2 12');
+      checkHighlightIs(getByRole('listbox'), 'option 2 12');
+    });
+
     it('should keep the current highlight if possible', () => {
       const { getByRole } = render(
         <Autocomplete

packages/material-ui/src/useAutocomplete/useAutocomplete.js

@@ -129,6 +129,7 @@ export default function useAutocomplete(props) {
   const [focusedTag, setFocusedTag] = React.useState(-1);
   const defaultHighlighted = autoHighlight ? 0 : -1;
   const highlightedIndexRef = React.useRef(defaultHighlighted);
+  const highlightedOptionRef = React.useRef(null);
 
   const [value, setValueState] = useControlled({
     controlled: valueProp,
@@ -184,27 +185,44 @@ export default function useAutocomplete(props) {
 
   const popupOpen = open;
 
-  const filteredOptions = popupOpen
-    ? filterOptions(
-        options.filter((option) => {
-          if (
-            filterSelectedOptions &&
-            (multiple ? value : [value]).some(
-              (value2) => value2 !== null && getOptionSelected(option, value2),
-            )
-          ) {
-            return false;
-          }
-          return true;
-        }),
-        // we use the empty string to manipulate `filterOptions` to not filter any options
-        // i.e. the filter predicate always returns true
-        {
-          inputValue: inputValueIsSelectedValue && inputPristine ? '' : inputValue,
-          getOptionLabel,
-        },
-      )
-    : [];
+  const filteredOptions = React.useMemo(() => {
+    if (!popupOpen) {
+      return [];
+    }
+
+    const filtered = filterOptions(
+      options.filter((option) => {
+        if (
+          filterSelectedOptions &&
+          (multiple ? value : [value]).some(
+            (value2) => value2 !== null && getOptionSelected(option, value2),
+          )
+        ) {
+          return false;
+        }
+        return true;
+      }),
+      // we use the empty string to manipulate `filterOptions` to not filter any options
+      // i.e. the filter predicate always returns true
+      {
+        inputValue: inputValueIsSelectedValue && inputPristine ? '' : inputValue,
+        getOptionLabel,
+      },
+    );
+    return filtered;
+  }, [
+    popupOpen,
+    filterOptions,
+    options,
+    filterSelectedOptions,
+    multiple,
+    value,
+    getOptionSelected,
+    inputValueIsSelectedValue,
+    inputPristine,
+    inputValue,
+    getOptionLabel,
+  ]);
 
   const focusTag = useEventCallback((tagToFocus) => {
     if (tagToFocus === -1) {
@@ -317,6 +335,8 @@ export default function useAutocomplete(props) {
 
   const setHighlightedIndex = useEventCallback(({ event, index, reason = 'auto' }) => {
     highlightedIndexRef.current = index;
+    highlightedOptionRef.current =
+      index === -1 || !filteredOptions[index] ? null : filteredOptions[index];
 
     // does the index exist?
     if (index === -1) {
@@ -433,7 +453,8 @@ export default function useAutocomplete(props) {
         return newIndex;
       };
 
-      const nextIndex = validOptionIndex(getNextIndex(), direction);
+      const proposedIndex = getNextIndex();
+      const nextIndex = validOptionIndex(proposedIndex, direction);
       setHighlightedIndex({ index: nextIndex, reason, event });
 
       // Sync the content of the input with the highlighted option.
@@ -455,6 +476,37 @@ export default function useAutocomplete(props) {
     },
   );
 
+  React.useEffect(() => {
+    const highlightedIndex = highlightedIndexRef.current;
+    const newHighlightedOption =
+      highlightedIndex === -1 ? null : filteredOptions[highlightedIndex] ?? null;
+    const previousHighlightedOption = highlightedOptionRef.current;
+
+    highlightedOptionRef.current = newHighlightedOption;
+
+    if (!popupOpen || highlightedIndex === -1) {
+      return;
+    }
+
+    if (newHighlightedOption == null) {
+      changeHighlightedIndex({ diff: 'reset', reason: 'option-change' });
+      return;
+    }
+
+    if (
+      previousHighlightedOption == null ||
+      !getOptionSelected(newHighlightedOption, previousHighlightedOption)
+    ) {
+      setHighlightedIndex({ index: highlightedIndex, reason: 'option-change' });
+    }
+  }, [
+    filteredOptions,
+    popupOpen,
+    changeHighlightedIndex,
+    setHighlightedIndex,
+    getOptionSelected,
+  ]);
+
   const isTouch = React.useRef(false);
 
   const syncHighlightedIndex = React.useCallback(() => {